| name | metadoc-agent-tools |
| description | Standardizes creating and maintaining MetaDoc agent tools. Use when adding a new tool, changing tool spec/instruction/i18n, adding or updating a Display component, or aligning tool–Display message passing in meta-doc. |
MetaDoc Agent Tools 创建与维护流程
在 MetaDoc 中新增或修改 Agent 工具时，按本流程执行，保证工具规约、i18n、Display 组件与消息传递一致。
何时使用本 Skill
- 新增一个
*-tool.ts 或修改现有工具的 spec/instruction/回调
- 新增或修改配套的 Display 组件（如
*Display.vue）
- 调整工具的简略/详细提示词（brief/fullSpec）或多语言
- 统一 Tool ↔ Display 的消息传递方式
核心路径与角色
| 角色 | 路径 |
|---|
| Tool 定义 | src/renderer/src/utils/agent-tools/*-tool.ts |
| Display 组件 | src/renderer/src/utils/agent-tools/components/*Display.vue |
| 注册入口 | src/renderer/src/utils/agent-tools/index.ts |
| Tool↔Display 通信 | tool-display-communication.ts（emit/on） |
| Display 实时状态 | composables/useToolDisplayRealtime.ts |
| 手册（可选） | src/renderer/src/manuals/zh_CN/agent/tools.md |
详细类型与事件命名见 reference.md。
一、创建/修改 Tool（*-tool.ts）
1.1 配置结构（必守）
- id：唯一，如
'color-processing'。
- name / description：i18n，使用
ToolLocales（如 zh_cn、en_us 的 name、description）。
- instruction：详细说明，支持 i18n（
ToolLocales 每语言下可带 instruction）；内容为 Markdown，含功能、使用场景、输入/输出格式、注意事项。
- spec（推荐）：用于上下文优化。
- brief：简略提示词，始终进入 System Prompt，供意图识别与工具选择。
- fullSpec：详细说明，按需注入；与 instruction 内容可一致或更精简。
- callback：
(params, signal, onUpdate) => Promise<ToolCallbackResult>。
- displayComponent：对应
*Display.vue 组件（可选）。
- inputSchema / outputSchema：JSON Schema，便于校验与文档。
- locales：与 name/description/instruction 的 i18n 一致。
1.2 回调约定
- 进度与中间结果：通过
onUpdate(data, progress) 发送。
data: { content, format, componentName? }（ToolCallbackData）。progress: { percentage, message? }（0–100）。
- 返回：
Promise<ToolCallbackResult>，即 { status, data?, result?, error?, progress? }。
- 有 Display 时，
data 中 content 为 Display 所需结构，componentName 与 Display 组件名一致。
- 错误：使用
tool-utils.ts 的 createDetailedError 等，便于 LLM 重试。
- 可取消：回调内检查
signal.aborted，必要时提前返回。
1.3 注册
在 index.ts 的 initializeAgentTools() 中 agentToolManager.registerTool(xxxToolConfig)。
二、创建/修改 Display 组件（*Display.vue）
2.1 Props 与数据源
- 实现 ToolDisplayComponentProps：
data、status、progress?、error?、toolConfig、invocationId?、onUpdate?、onCancel?。
- 实时数据：使用
useToolDisplayRealtime(invocationId, data, status, progress)，得到 realtimeData、realtimeStatus、realtimeProgress。
- 展示用数据：优先用 realtime，否则用 props；若 payload 带
content 包装，用 parseToolData(data) 取出再渲染。
2.2 主题与 i18n
- 主题：用
themeState 或现有主题 composable，保证与应用主题一致（如背景、文字色）。
- 文案：全部用
$t('agent.display.<toolName>.<key>')，不在模板里写死中文/英文。key 放在 agent.display.<toolName> 下（与项目 i18n 文件一致）。
2.3 消息传递（与 Tool 一致）
- Tool 侧：仅通过
onUpdate 传入的 data 经 tool-display-communication 转发（tool-update:{invocationId} / tool-complete / tool-failed）。
- Display 侧：只通过
invocationId 订阅上述事件，用 useToolDisplayRealtime 消费；不在此处直接调用 Tool 或 agent 接口。
- 交互回传：如需把用户操作反馈给会话，使用 props 的
onUpdate(data)，由上层与 Agent 约定用法。
三、i18n 规约
- Tool 名称/描述/instruction：在
*-tool.ts 的 ToolLocales 中为每种语言提供 name、description，以及可选的 instruction。
- Display 文案：在全局 i18n 资源中增加
agent.display.<toolName>.*（如 agent.display.color.title、agent.display.edit.appliedEdits）。与 ColorDisplay.vue、EditDisplay.vue、TodoListDisplay.vue 等现有用法保持一致。
- 使用
i18n-helper.ts 的 getLocalizedText / getLocalizedInstruction 时，与上述 key 约定一致。
四、清单：新增一个完整 Tool
按顺序打勾，避免遗漏：
- [ ] 在
utils/agent-tools/ 下新增 *-tool.ts，实现 AgentToolConfig（id、name、description、instruction、spec.brief/fullSpec、callback、displayComponent、inputSchema/outputSchema、locales）。
- [ ] 在
utils/agent-tools/components/ 下新增 *Display.vue，实现 ToolDisplayComponentProps，使用 useToolDisplayRealtime 与 parseToolData，主题与 $t('agent.display.<toolName>.*')。
- [ ] 在全局 i18n 中补充
agent.display.<toolName> 下所有展示用 key。
- [ ] 在
index.ts 的 initializeAgentTools() 中注册该 Tool。
- [ ] （可选）若影响“工具集”或对用户可见的能力说明，更新
manuals/zh_CN/agent/tools.md。
五、清单：仅修改现有 Tool
- [ ] 改 spec（brief/fullSpec）或 instruction 时，同步检查各语言
ToolLocales 与 locales。
- [ ] 改回调的入参/出参或
onUpdate 的 content 结构时，同步改对应 Display 的解析与展示逻辑，以及 parseToolData 若需兼容。
- [ ] 改 Display 时，确保仍只通过
invocationId + useToolDisplayRealtime 与既有事件协议通信；新增文案一律走 agent.display.<toolName>.*。
六、参考实现
- 轻量 Tool + Display：
color-tool.ts + ColorDisplay.vue（spec、i18n、onUpdate、Display 状态）。
- 复杂 Tool + 多阶段 UI：
edit-tool.ts + EditDisplay.vue，todolist-tool.ts + TodoListDisplay.vue。
- 通信与类型：
tool-display-communication.ts，types/agent-tool.ts，composables/useToolDisplayRealtime.ts。
更多字段说明、事件名、序列化与快照见 reference.md。
