# 知言家 AI Coding 伴侣 · 新 AI 工具 Hook 配置任务包

目标：教会用户根据当前 AI 工具自己的官方 Hook / 插件文档完成接入，让该工具直接发送知言家标准事件，不要先假定目标工具的配置答案。

## 第 1 步 · 读取目标工具官方文档

1. 确认当前工具名称和用户指定的 source。
2. 从该工具官网或官方仓库查找并阅读 Hook / 插件文档，记录文档地址。
3. 确认官方配置位置、原生事件名、事件输入字段和 Hook 运行方式。
4. 先向用户列出“官方原生事件 -> 触发时机 -> sessionId -> turnId -> requestId -> 标准事件”的接入表，再修改配置。
5. 只配置官方确认支持的事件；不要套用其他 AI 工具的目录、配置格式或原生事件名。

## 第 2 步 · 确定 source

source 使用稳定的小写 ID，建议只含字母、数字和连字符，例如：your-tool。MiMo Code 已有正式教程，应改读 https://zyhome.run/docs/integrations/mimo-code.txt 并固定使用 mimo-code。
同一工具的所有事件必须使用同一个 source。不要使用 opencode、codex、claude、qoder、trae 或 mcp 冒充其他工具。

## 第 3 步 · 映射原生动作

- 用户提交新消息 -> user_message_submitted
- 请求授权 -> approval_requested
- 请求用户补充信息 -> supplement_requested
- 授权或补充结束并继续处理 -> processing_resumed
- 本轮完成、失败或取消 -> turn_completed

工具没有对应原生动作时跳过，不要编造 Hook。

## 第 4 步 · 构造事件

所有事件都必须包含：

```json
{
  "schemaVersion": 1,
  "eventId": "本条 Hook 事件 ID；投递重试时复用",
  "source": "用户指定的 source",
  "event": "标准事件名",
  "sessionId": "当前 AI 会话 ID",
  "turnId": "当前一轮任务 ID；同轮始终复用",
  "occurredAt": "RFC3339 时间"
}
```

ID 含义：
- eventId：一条 Hook 事件；同一条事件投递重试时复用，新事件使用新 ID。
- sessionId：一次 AI 会话；整个会话期间复用。
- turnId：用户提交一条消息后产生的一轮任务；本轮开始、等待、继续和完成时复用，下一轮使用新 ID。
- requestId：一次授权或补充请求；请求发出和解除时复用。

事件字段：

1. user_message_submitted
   - reason: user_prompt_submitted
   - level: info

2. approval_requested
   - reason: permission_requested
   - level: notice
   - interaction: {"kind":"authorization","requestId":"原生请求 ID","status":"requested","resolutionScope":"request"}

3. supplement_requested
   - reason: question_requested
   - level: notice
   - interaction: {"kind":"supplement","requestId":"原生请求 ID","status":"requested","resolutionScope":"request"}

4. processing_resumed
   - interaction 必须复用要解除的原生 requestId。
   - 授权通过：kind=authorization，status=approved，reason=permission_resolved，level=info。
   - 授权已解决：kind=authorization，status=resolved，reason=permission_resolved，level=info。
   - 自动授权：kind=authorization，status=auto_approved，reason=permission_auto_approved，level=info。
   - 授权拒绝：kind=authorization，status=denied，reason=permission_denied，level=warning。
   - 授权关闭：kind=authorization，status=dismissed，reason=permission_dismissed，level=warning。
   - 用户已补充：kind=supplement，status=replied，reason=question_replied，level=info。
   - 补充已解决：kind=supplement，status=resolved，reason=supplement_resolved，level=info。
   - 用户拒绝补充：kind=supplement，status=rejected，reason=question_rejected，level=warning。
   - 补充窗口关闭：kind=supplement，status=dismissed，reason=supplement_dismissed，level=warning。
   - resolutionScope 使用 request；只有明确解除本轮全部授权时才使用 all_authorizations。

5. turn_completed
   - 完成：reason=turn_completed，level=info，outcome={"status":"completed"}
   - 失败：reason=execution_failed，level=error，outcome={"status":"failed","error":{"code":"稳定的小写错误代码","retryable":false}}
   - 取消：reason=cancelled，level=warning，outcome={"status":"cancelled"}

同一轮的开始、等待、继续和完成必须复用同一个 turnId。下一轮用户消息使用新的 turnId。
没有稳定 turnId 或 requestId 时不要猜测；应在该工具自己的长生命周期插件中保存，无法可靠保存时跳过对应事件。

## 第 5 步 · 投递

插件方式：
1. 读取 %LOCALAPPDATA%\zy_home_vibe_coding_driver\service.json。
2. 只接受 baseUrl 为 127.0.0.1、localhost 或其他本机回环地址。
3. POST 标准 JSON 到 ${baseUrl}/events，Content-Type 使用 application/json。

命令 Hook 方式：
1. 使用 %LOCALAPPDATA%\zy_home_vibe_coding_driver\bin\zy_home_vibe_coding_driver_hookbridge.exe。
2. 使用 --source 和 --event 明确指定标准动作。
3. 从官方 Hook 输入中读取并传入稳定 sessionId、turnId 和需要的 requestId。
4. 按事件需要传入 --reason、--level、--interaction-kind、--interaction-status、--resolution-scope、--outcome-status 等明确字段。
5. 可以先加 --dry-run 检查生成的标准 JSON。
6. 不使用 --hook-event-name 让驱动或 HookBridge 猜测新工具语义。

禁止把原始 Hook payload 直接发送给驱动。禁止发送 Prompt、模型回答、完整命令、文件内容、diff、环境变量、凭据或 Cookie。

## 第 6 步 · 安全合并与验证

1. 先备份目标工具配置，只增量添加本接入，保留其他 Hook / 插件。
2. 使用目标工具官方要求的编码和格式，完成静态语法检查。
3. 重启目标工具。
4. 发送一条普通消息，确认驱动出现指定 source。
5. 只测试官方 Hook 已支持的授权、继续和完成动作。
6. HTTP 202 且 recognized=true 表示格式已识别；applied=true 表示任务状态发生有效变化。

完成后报告：读取了哪份官方文档、接入表、修改了哪些文件、使用的 source、配置了哪些原生事件、哪些事件因官方不支持而跳过、是否需要重启。不要启动或停止驱动。