小紫 AI 工作台

# 贤紫优选 · ASI 模型微调与适配规范 v1.0

  **文档性质**：对外公开 · 开发者与企业可据此微调自有模型以适配贤紫智能代码编辑器的 ASI 工具与对话能力  
  **规范版本**：v1.0（本文档自身的修订号）  
  **适配产品版本**：**v2.5.146**（贤紫智能代码编辑器；内置工具名与可解析协议以该版本为基准校验）  
  **适用范围**：开源模型、企业自研模型、私有化部署模型  
  
  ---
  
  ## 1. 文档目的
  
  本规范说明：**如何通过数据构造、训练阶段设计与推理配置，使微调后的模型在贤紫 ASI 环境下稳定完成「理解任务 → 选择工具 → 传参 → 消化工具结果 → 给出最终答复」的闭环**，并与会话上下文、工具执行结果协同工作。
  
  遵循本规范可显著降低：格式错乱、工具名幻觉、参数不合 schema、多轮状态丢失、越权或危险操作倾向等问题。
  
  ---
  
  ## 2. ASI 对模型的核心能力要求
  
  ### 2.1 必选能力
  
  | 能力 | 说明 |
  |------|------|
  | **结构化工具调用** | 能按约定字段输出 `tool_calls`（或与所用推理接口兼容的等价结构），工具名与注册表一致。 |
  | **参数服从 schema** | 参数类型、必填项、枚举、路径/范围与各工具 `parameters` 约定一致，避免自由文本替代结构化字段。 |
  | **多轮与工具回注** | 在收到 `role: tool`（或等价）的工具执行结果后，能继续推理并决定：再次调用工具或输出最终自然语言答案。 |
  | **指令遵循** | 遵守系统级策略（语言、安全边界、是否允许执行命令等），不绕过产品侧权限与确认机制。 |
  
  ### 2.2 强烈建议能力
  
  - **并行工具调用**：在独立子任务可并行时，一次输出多个 `tool_calls`，减少回合数。  
  - **参数自纠错**：在收到参数非法类错误返回后，根据错误信息修正参数重试。  
  - **任务分解**：复杂需求先检索/再编辑/再验证，避免一步到位幻觉。  
  
  ---
  
  ## 3. 贤紫内置工具名与注册字段（微调须与产品一致）
  
  下列名称为**贤紫智能代码编辑器 v2.5.146** 对应内置工具标识（英文蛇形命名，大小写须完全一致）。若终端用户版本高于/低于 v2.5.146，工具增减以实际安装版本或发行说明为准。用户通过插件扩展的工具名以本地 `moss-tools.json` 为准，不在此固定列表中。
  
  ### 3.1 代码与工程类（主工具集）
  
  | 工具名 | 典型用途（摘要） |
  |--------|------------------|
  | `codebase_search` | 代码库语义检索 |
  | `read_file` | 读取单个文件（修改类操作前通常需先调用） |
  | `replace_lines` | 按行号范围替换（常用参数：`startLine`、`endLine`、`newText` 等） |
  | `insert_line` | 在指定行插入内容 |
  | `delete_lines` | 删除行范围 |
  | `replace_text` | 按文本查找替换（常用参数：`oldText`、`newText` 等） |
  | `list_directory` | 列出目录 |
  | `get_project_structure` | 获取工程结构 |
  | `get_cursor_context` | 获取编辑器当前上下文 |
  | `create_file` | 创建文件 |
  | `delete_file` | 删除文件 |
  | `grep_search` | 正则/文本搜索 |
  | `file_search` | 按文件名查找 |
  | `find_code_location` | 定位符号/定义 |
  | `run_terminal_cmd` | 执行终端命令 |
  | `reapply` | 重新应用某次编辑 |
  | `diff_history` | 查看差异历史 |
  | `lint_check` | 语法/风格检查 |
  | `refactor` | 智能重构 |
  | `run_tests` | 运行测试 |
  | `generate_tests` | 生成测试 |
  | `fix_tests` | 修复测试 |
  
  ### 3.2 注册表字段（单条工具定义）
  
  贤紫侧每条工具在注册表中至少包含以下字段，与 **OpenAI / Ollama 常见 function calling** 一致，便于微调数据与线上 `tools` 列表对齐：
  
  | 字段 | 含义 |
  |------|------|
  | `name` | 工具唯一标识，与上表字符串一致 |
  | `description` | 自然语言说明，供模型择时调用 |
  | `parameters` | 对象结构：`type: "object"`、`properties`、`required`（如有），与常见 function calling 参数描述方式一致 |
  
  对外传给模型时，常见封装为：`{ "type": "function", "function": { "name", "description", "parameters" } }`（具体以所用推理接口为准）。
  
  ### 3.3 写入类工具（微调数据中的「落盘」语义）
  
  以下工具会改变磁盘或本地配置（训练负例、安全样本需区别对待）：  
  `replace_lines`、`insert_line`、`delete_lines`、`replace_text`、`create_file`、`delete_file`、`reapply`、`refactor`，以及 `moss_register_plugin_tool`、`moss_update_asi_user_prompt`。
  
  ### 3.4 各工具完整 `parameters` 结构说明（v2.5.146）
  
  贤紫 **v2.5.146** 主工具集在注册表中为 **21** 项（与 §3.1 表格一致）。下列为每项工具 `parameters` 的**完整结构约定**（`type` / `properties` / `required` / `description` / `default` 与产品注册逻辑对齐；**不含** `$schema` 等元声明，仅为贤紫编辑器侧参数说明，与任何第三方规范站点无绑定关系）。微调数据**键名**须与下表 `properties` 一致；部分字段另有别名由运行时归一化，训练时仍建议用主键名。
  
  #### `codebase_search`
  
  ```json
  {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "搜索查询（支持自然语言）" },
      "fileType": { "type": "string", "description": "文件类型过滤（如 .js, .py）" },
      "limit": { "type": "number", "description": "结果数量限制", "default": 10 }
    },
    "required": ["query"]
  }
  ```
  
  #### `read_file`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "文件路径（相对或绝对）" },
      "startLine": { "type": "number", "description": "起始行号（可选，从 1 开始）" },
      "endLine": { "type": "number", "description": "结束行号（可选，从 1 开始）" }
    },
    "required": ["path"]
  }
  ```
  
  #### `replace_lines`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "文件路径（别名：filePath, file_path, file）" },
      "startLine": { "type": "number", "description": "起始行号（从 1 开始）" },
      "endLine": { "type": "number", "description": "结束行号（从 1 开始）" },
      "newText": { "type": "string", "description": "新内容（别名：newLines, content, code, text, replacement）" }
    },
    "required": ["path", "startLine", "endLine", "newText"]
  }
  ```
  
  #### `insert_line`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "文件路径（别名：filePath, file_path, file）" },
      "line": { "type": "number", "description": "行号（从 1 开始；N 行文件可用 line=N+1 在末尾插入）" },
      "text": { "type": "string", "description": "插入内容（别名：content, code, lineText, insertText, value）" }
    },
    "required": ["path", "line", "text"]
  }
  ```
  
  #### `delete_lines`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "文件路径（别名：filePath, file_path, file）" },
      "startLine": { "type": "number", "description": "起始行号（从 1 开始）" },
      "endLine": { "type": "number", "description": "结束行号（从 1 开始）" }
    },
    "required": ["path", "startLine", "endLine"]
  }
  ```
  
  #### `replace_text`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "文件路径（别名：filePath, file_path, file）" },
      "oldText": { "type": "string", "description": "要查找的文本（别名：oldString, search, searchValue, find）" },
      "newText": { "type": "string", "description": "替换后的文本（别名：newString, replace, replaceValue, replacement）" }
    },
    "required": ["path", "oldText", "newText"]
  }
  ```
  
  #### `list_directory`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "目录路径（相对项目根；\"src\"、\"public\"、\".\" 等）" },
      "recursive": { "type": "boolean", "description": "是否递归子目录", "default": false },
      "fileType": { "type": "string", "description": "文件类型过滤（如 .js, .py）" },
      "minSize": { "type": "number", "description": "最小文件大小（字节）" },
      "maxSize": { "type": "number", "description": "最大文件大小（字节）" },
      "modifiedAfter": { "type": "string", "description": "修改时间过滤（ISO 日期字符串）" },
      "sortBy": { "type": "string", "description": "排序：name、size、modified", "default": "name" },
      "sortOrder": { "type": "string", "description": "asc 或 desc", "default": "asc" }
    },
    "required": ["path"]
  }
  ```
  
  #### `get_project_structure`
  
  ```json
  {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
  ```
  
  #### `get_cursor_context`
  
  ```json
  {
    "type": "object",
    "properties": {
      "linesBefore": { "type": "number", "description": "光标前多少行", "default": 10 },
      "linesAfter": { "type": "number", "description": "光标后多少行", "default": 10 },
      "semanticContext": { "type": "boolean", "description": "语义上下文理解", "default": true },
      "includeCallers": { "type": "boolean", "description": "包含调用者", "default": false },
      "includeCallees": { "type": "boolean", "description": "包含被调用者", "default": false }
    },
    "required": []
  }
  ```
  
  #### `create_file`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "文件路径（别名：filePath, file_path, file）" },
      "content": { "type": "string", "description": "文件内容（别名：text, code, body）" },
      "overwrite": { "type": "boolean", "description": "是否覆盖已存在文件", "default": false }
    },
    "required": ["path", "content"]
  }
  ```
  
  #### `run_terminal_cmd`
  
  ```json
  {
    "type": "object",
    "properties": {
      "command": { "type": "string", "description": "要执行的命令（别名：cmd, commandText, text）" },
      "cwd": { "type": "string", "description": "工作目录（别名：workingDir, workDir, directory）" },
      "is_background": { "type": "boolean", "description": "是否后台运行（别名：isBackground, background）" }
    },
    "required": ["command"]
  }
  ```
  
  #### `grep_search`
  
  ```json
  {
    "type": "object",
    "properties": {
      "pattern": { "type": "string", "description": "正则表达式模式" },
      "fileType": { "type": "string", "description": "文件类型过滤" },
      "caseSensitive": { "type": "boolean", "description": "是否区分大小写", "default": false },
      "limit": { "type": "number", "description": "结果数量限制", "default": 50 }
    },
    "required": ["pattern"]
  }
  ```
  
  #### `file_search`
  
  ```json
  {
    "type": "object",
    "properties": {
      "pattern": { "type": "string", "description": "文件名模式（通配符或模糊匹配）" },
      "fileType": { "type": "string", "description": "文件类型过滤" },
      "fuzzy": { "type": "boolean", "description": "是否模糊匹配", "default": true },
      "searchPath": { "type": "boolean", "description": "是否搜索路径", "default": true }
    },
    "required": ["pattern"]
  }
  ```
  
  #### `delete_file`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "要删除的文件路径" },
      "permanent": { "type": "boolean", "description": "是否永久删除", "default": false }
    },
    "required": ["path"]
  }
  ```
  
  #### `reapply`
  
  ```json
  {
    "type": "object",
    "properties": {
      "index": { "type": "number", "description": "历史索引（0 为最近一次）", "default": 0 }
    },
    "required": []
  }
  ```
  
  #### `diff_history`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "文件路径（不提供则全部历史）" },
      "limit": { "type": "number", "description": "条数限制", "default": 10 }
    },
    "required": []
  }
  ```
  
  #### `lint_check`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "文件路径，或 \"project\" / \".\" / \"*\"" }
    },
    "required": ["path"]
  }
  ```
  
  #### `find_code_location`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "文件路径（可选）" },
      "search": { "type": "string", "description": "代码片段、类名、函数名或变量名" },
      "searchType": { "type": "string", "description": "exact、contains、regex、class、function、variable", "default": "contains" },
      "findReferences": { "type": "boolean", "description": "查找所有引用", "default": false },
      "findDefinition": { "type": "boolean", "description": "查找定义", "default": false },
      "fileType": { "type": "string", "description": "文件类型过滤" }
    },
    "required": ["search"]
  }
  ```
  
  #### `refactor`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "要重构的文件路径" },
      "refactorType": { "type": "string", "description": "performance、readability、structure、error_handling、general", "default": "general" },
      "symbol": { "type": "string", "description": "目标符号（可选）" },
      "startLine": { "type": "number", "description": "起始行（可选）" },
      "endLine": { "type": "number", "description": "结束行（可选）" },
      "analyzeImpact": { "type": "boolean", "description": "是否分析影响范围", "default": true },
      "preview": { "type": "boolean", "description": "是否仅预览", "default": false },
      "includeContext": { "type": "boolean", "description": "是否包含上下文", "default": true }
    },
    "required": ["path"]
  }
  ```
  
  #### `run_tests`
  
  ```json
  {
    "type": "object",
    "properties": {
      "testFile": { "type": "string", "description": "指定测试文件（可选）" },
      "testPattern": { "type": "string", "description": "测试名过滤（可选）" },
      "coverage": { "type": "boolean", "description": "是否生成覆盖率", "default": false }
    },
    "required": []
  }
  ```
  
  #### `generate_tests`
  
  ```json
  {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "被测源文件路径" },
      "testFramework": { "type": "string", "description": "jest、mocha、pytest 等（可选，自动检测）" },
      "testTypes": {
        "type": "array",
        "items": { "type": "string" },
        "description": "unit、integration、edge、error 等",
        "default": ["unit", "edge", "error"]
      }
    },
    "required": ["path"]
  }
  ```
  
  #### `fix_tests`
  
  ```json
  {
    "type": "object",
    "properties": {
      "testResults": { "type": "object", "description": "测试结果对象（可选）" },
      "testFile": { "type": "string", "description": "测试文件路径（可选）" },
      "autoRun": { "type": "boolean", "description": "修复后是否自动重跑", "default": true }
    },
    "required": []
  }
  ```
  
  ---
  
  ## 4. 与 ASI 对齐的消息与工具协议（训练须一致）
  
  ### 4.1 标准多轮结构（逻辑）
  
  训练数据中的对话应能还原以下逻辑（具体字段名可与推理接口约定对齐）：
  
  1. `user`：用户目标与约束。  
  2. `assistant`：仅含 `tool_calls` 或最终答复（勿混用未定义格式）。  
  3. `tool`：工具名 + 结构化结果或标准错误码说明。  
  4. `assistant`：基于工具结果继续推理直至任务结束。  
  
  ### 4.2 `tool_calls` 字段约定（示例）
  
  ```json
  {
    "tool_calls": [
      {
        "id": "call_001",
        "name": "read_file",
        "arguments": { "path": "src/app.ts" }
      }
    ]
  }
  ```
  
  **微调数据中的黄金规则**：
  
  - `name` 必须来自 ASI 工具注册表中的**精确字符串**（大小写一致）。  
  - `arguments` 必须是合法 JSON 对象，键名与 schema 一致，禁止把整段意图塞进单一字符串字段冒充结构。  
  
  ### 4.3 工具结果角色
  
  工具执行结果在对话中应以 **`role: tool`**（或与运行时一致的等价角色）回注；训练样本必须包含「工具结果 → 模型下一步」的完整链条，否则上线后易出现「调用工具后不知道如何继续」的断裂。
  
  ### 4.4 贤紫可解析的调用形式（与微调一致即可）
  
  产品侧除 **API 返回的 `tool_calls` / `function` 调用**外，还支持在**助手文本**中嵌入可解析片段（便于不支持原生 function calling 的模型）。微调时若模拟此类输出，须与下列字面量一致：
  
  1. **原生结构**：响应对象中带 `tool_calls` 数组；单项可为 `function.name` + `function.arguments`（字符串或对象），或与实现兼容的 `name` + `parameters`。  
  2. **文本回退（单行）**：一行内包含  
     `[TOOL_CALL]` + 工具名 + `[ARGS]` + JSON 参数对象（键名须与工具定义一致，例如 `replace_lines` 使用 `startLine`、`endLine`、`newText`）。  
  3. **其它文本兼容格式**：部分流程中支持 `[TOOL:工具名]{...}[/TOOL]` 或代码块内的 JSON 工具调用数组（以实际推理接口为准）。
  
  **行为约束（与产品提示一致）**：不得用「工具执行：…」「模拟工具调用」等**叙述**代替真实可解析调用；需要读/写/搜索时必须产出上述结构之一。
  
  ### 4.5 代理步骤总结行（部分场景）
  
  在「规划 → 工具执行 → 总结」类流程中，总结步末尾可能要求输出一行状态：  
  `AGENT_STATUS: DONE`、`CONTINUE` 或 `STOP`（仅该步总结，不附带新的工具调用）。微调若覆盖此类场景，应保留该行格式。
  
  ---
  
  ## 5. 微调数据规范（FT-Data for ASI）
  
  ### 5.1 推荐格式：JSONL
  
  每行一条样本，`messages` 为完整多轮对话（含工具调用与工具结果）。
  
  ```json
  {
    "messages": [
      {
        "role": "system",
        "content": "你是 ASI 编码助手。仅使用已注册工具；参数必须符合各工具 parameters 定义；不确定时先只读检索再修改。"
      },
      {
        "role": "user",
        "content": "帮我在项目中找到处理登录的函数并说明调用关系。"
      },
      {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_1",
            "name": "codebase_search",
            "arguments": { "query": "login authentication user auth", "limit": 10 }
          }
        ]
      },
      {
        "role": "tool",
        "name": "codebase_search",
        "content": "{\"matches\":[...]}"
      },
      {
        "role": "assistant",
        "content": "根据检索结果，登录相关逻辑主要在……"
      }
    ],
    "tags": ["retrieve", "explain", "asi_v1"],
    "quality": { "schema_valid": true, "tools_from_registry": true }
  }
  ```
  
  ### 5.2 数据配比建议
  
  | 类型 | 占比（经验值） | 作用 |
  |------|----------------|------|
  | **单工具成功路径** | 35% | 学会正确格式与常见工具。 |
  | **多工具链** | 35% | 检索→读文件→编辑→验证类真实工作流。 |
  | **负例与纠错** | 15% | 非法参数、权限拒绝、超时后的修正与降级说明。 |
  | **纯对话（不调用工具）** | 15% | 避免「万事皆工具」；简单问答直接文本回答。 |
  
  ### 5.3 质量门槛（训练前自检）
  
  - 工具名与注册表一致率 **≥ 99%**。  
  - 参数可 JSON 解析且通过对应 schema 校验的样本 **≥ 98%**。  
  - 每条多轮样本必须 **闭环**（有明确最终 `assistant` 文本或合理终止策略）。  
  - 对高风险操作（删除、执行命令、外网请求）的样本须带 **权限/确认** 相关上下文，与产品安全策略一致。  
  
  ---
  
  ## 6. 训练阶段建议
  
  ### 6.1 阶段一：监督微调（SFT）
  
  - **目标**：学会 ASI 消息格式、工具名空间、典型编码任务的工具选择顺序。  
  - **重点**：同一工具在不同意图下的参数差异（例如 `path` 与 `query` 不要混用）。  
  
  ### 6.2 阶段二：偏好对齐（可选，DPO / ORPO 等）
  
  - **目标**：同一状态下，偏好「合法工具调用 + 更短路径」胜过「胡编工具名或冗长无效步骤」。  
  - **构造拒绝样本**：错误工具名、编造参数、忽略工具报错继续胡说。  
  
  ### 6.3 阶段三：在线或离线反馈迭代
  
  - 用 ASI 真实日志（脱敏后）抽取失败案例，补充为「纠错类」样本，持续压低参数错误率与无效回合数。  
  
  ---
  
  ## 7. 推理侧配置（与微调配套）
  
  | 配置项 | 建议 |
  |--------|------|
  | **温度** | 工具调用密集任务偏低（如 0.1–0.3），降低格式漂移。 |
  | **停止符 / 输出模式** | 与所用推理接口对工具输出的要求一致，避免模型输出无法解析的碎片格式。 |
  | **最大长度** | 预留工具结果占用的 token，避免截断导致「半次调用」。 |
  | **系统提示词** | 与训练时 system 内容同分布；大改系统提示需补训或评测。 |
  
  ---
  
  ## 8. 接入与验收清单
  
  - [ ] 提供模型 **max context**、是否 **原生 function calling**、与贤紫工具列表的字段映射说明。  
  - [ ] 在贤紫官方或自建 **离线评测集** 上跑通：工具调用成功率、参数合法率、任务完成率、安全违规率。  
  - [ ] 沙箱灰度：真实项目中小流量验证 ≥ 1 周，记录失败类型分布。  
  - [ ] 发布 **兼容声明**：模型版本、规范版本（本文 v1.0）、**目标产品版本（建议标明 v2.5.146）**、已知限制（如不支持并行调用则需标注）。  
  
  ---
  
  ## 9. 常见失败模式与规避
  
  | 现象 | 常见原因 | 规避 |
  |------|----------|------|
  | 编造工具名 | 训练数据工具名不统一或未覆盖 | 统一注册表字符串 + 负样本惩罚 |
  | 参数类型错误 | schema 样本不足 | 增加边界类型与枚举样本 |
  | 工具结果后胡编 | 缺少 tool 回注段落 | 每条链必须含 tool 结果与后续 assistant |
  | 过度调用工具 | 数据全是工具流 | 提高「无需工具」样本比例 |
  | 忽视报错 | 缺少错误码样本 | 增加错误返回与正确重试/解释类样本 |
  
  ---
  
  ## 10. 版本与兼容性
  
  - 本文档 **规范 v1.0** 与 **贤紫智能代码编辑器 v2.5.146** 的内置工具名、注册字段及可解析调用形式对齐。  
  - 若产品版本高于 v2.5.146 导致工具增减或调用字段变化，将发布 **规范 v1.1+** 并给出迁移说明；微调模型时建议在兼容声明中同时标注 **规范版本** 与 **产品版本**。  
  
  ---
  
  ## 11. 联系与生态
  
  欢迎开发者与企业基于本规范共建：**高质量中文/多语言编码工具调用数据集、行业场景基准、开源/私有化适配示例**。  
  
  ---
  
  **版权声明**：本文档可由贤紫优选 / 贤紫智能代码编辑器项目随版本发布；转载请注明版本号与来源。