说明：以下为完整规范正文（Markdown 源码排版），供开发者与企业按 v2.5.146 产品版本对齐工具名与训练数据；与仓库内 贤紫优选-ASI模型微调与适配规范-v1.md 同步。
# 贤紫优选 · 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. 联系与生态
欢迎开发者与企业基于本规范共建：**高质量中文/多语言编码工具调用数据集、行业场景基准、开源/私有化适配示例**。
---
**版权声明**：本文档可由贤紫优选 / 贤紫智能代码编辑器项目随版本发布；转载请注明版本号与来源。