# 知言家 AI Coding 伴侣 · MCP 接入任务包

本包用于让 AI 客户端为本机配置知言家本地 MCP 服务和状态通知 Skill。复制本包全文发给 AI，即可按步骤执行，无需联网抓取网页。

注意：Codex、Claude Code、OpenCode、TRAE、Qoder 家族已支持 Hook，优先使用 Hook 方案（见 https://zyhome.run/docs/integrations/ ）。MCP 仅适用于不支持 Hook 但支持 MCP 协议的客户端。

## 背景
知言家驱动从 v0.0.14 起内置本地 stdio MCP 服务，只暴露一个工具 zy_vibe_set_task_status，参数只有 status 一个。AI 客户端通过本地 stdio 启动 hookbridge，调用该工具把任务状态同步到桌面设备灯效。无需 API Key、无需网络服务、无需升级固件。

## 前置确认
1. 驱动已安装并在系统托盘运行（知言家 logo）。
2. hookbridge 路径：%LOCALAPPDATA%\zy_home_vibe_coding_driver\bin\zy_home_vibe_coding_driver_hookbridge.exe
   PowerShell 确认（应返回 True）：

   $HookBridge = Join-Path $env:LOCALAPPDATA "zy_home_vibe_coding_driver\bin\zy_home_vibe_coding_driver_hookbridge.exe"
   Test-Path -LiteralPath $HookBridge

   返回 False 时重装或修复驱动，从安装目录取用。

## 第 1 步 · 添加本地 stdio MCP 服务
在客户端 MCP 配置文件中加入（QoderWork 路径 ~/.qoderworkcn/mcp.json）：

```json
{
  "mcpServers": {
    "zy_home_ai_coding_driver_mcp": {
      "type": "stdio",
      "command": "C:\\Users\\<用户名>\\AppData\\Local\\zy_home_vibe_coding_driver\\bin\\zy_home_vibe_coding_driver_hookbridge.exe",
      "args": ["--mcp"]
    }
  }
}
```

要点：
- command 用绝对路径，把 <用户名> 替换为当前 Windows 用户名。
- --mcp 是独立参数，单独写在 args，不要拼到路径字符串。
- 传输类型选 stdio / local，不是 HTTP、SSE。
- 不需要 URL、Token、端口、工作目录或环境变量。
- 客户端不认 "type" 字段时，删掉该行，保留 command 和 args。
- QoderWork 改完 mcp.json 后若服务器显示未连接，到 设置 -> 连接器 把该服务器禁用再启用一次。

## 第 2 步 · 创建状态通知 Skill
在客户端技能目录新建 SKILL.md（QoderWork 路径 ~/.qoderworkcn/skills/zy-home-ai-coding-notify/SKILL.md），内容：

```markdown
---
name: zy-home-ai-coding-notify
description: "ALWAYS use this skill at the start and end of every user interaction. Sends hardware light notifications via the zy_home_ai_coding_driver_mcp MCP to indicate task lifecycle on the physical device. This skill applies to ALL tasks regardless of topic."
version: 2.0.0
---

# 硬件状态灯通知

每次用户交互必须调用 zy_home_ai_coding_driver_mcp MCP 的 `zy_vibe_set_task_status` 工具，参数只有 `status` 一个：

| 时机 | status |
| --- | --- |
| 任务开始（最先执行的工具调用之一） | `running` |
| 即将请求用户授权、批准或确认高风险操作 | `approval_required` |
| 因缺少信息必须向用户提问 | `input_required` |
| 用户响应后任务恢复 | `running` |
| 任务成功完成或被取消（最后的工具调用之一） | `completed` |
| 任务因错误无法继续 | `failed` |

- 开始时的 `running` 与结束时的 `completed`/`failed` 必须成对；漏调收尾会让硬件卡在“处理中”灯效。
- 只在状态变化时调用一次，不要在中间步骤重复调用。
- MCP 服务不可用（调用报错）时静默跳过，不要中断任务。
```

## 第 3 步 · 验证
1. 重载客户端，打开 MCP/Tools 面板，确认：
   - 服务器名与配置键名一致（zy_home_ai_coding_driver_mcp）；
   - 连接类型为本地 stdio；
   - 工具列表中只有一个 zy_vibe_set_task_status（部分客户端会加前缀显示为 mcp__zy_home_ai_coding_driver_mcp__zy_vibe_set_task_status，以 zy_vibe_set_task_status 结尾即正确）。
2. 发送测试提示词：

```text
请使用 zy_home_ai_coding_driver_mcp MCP 完成一次设备状态测试：
先调用 zy_vibe_set_task_status，将 status 设置为 running；
回复“状态测试进行中”；
最后再次调用该工具，将 status 设置为 completed。
不要执行其他工具或命令。
```

3. 预期结果：驱动控制台出现 MCP 默认任务；running 后设备进入进行中灯效；completed 后任务自然收尾。
4. 首次工具调用可能触发客户端的工具信任确认，确认前核对工具名和本地可执行文件路径。

## 状态枚举（仅这五个英文值）
running / approval_required / input_required / completed / failed
不支持 waiting、idle、cancelled 或中文。任务被取消用 completed 收尾（取消不是错误）。

## 排查速查
- Executable not found / spawn failed：hookbridge 路径是否绝对、Test-Path 是否 True、JSON 反斜杠是否正确转义。
- Server 连接失败：是否选 stdio；--mcp 是否作为独立参数；驱动文件是否被安全软件隔离。
- 已连接但 0 个工具：完全重启客户端，确认启动的是当前安装目录的 hookbridge。
- 显示 1 个工具但设备无变化：查看本轮是否真有工具调用记录，而非只在文字里说“已更新”。
- 工具提示事件投递失败：驱动未运行，先打开驱动控制台再重试。
- 状态参数错误：只用五个英文枚举值，不要传任务名、摘要等附加字段。
- 一个任务显示两次：同一客户端可能同时开了 Hook 和 MCP，保留一条路线。
- 多个 MCP 客户端互相覆盖：这是单共享任务的设计，需要隔离时改用各客户端 Hook 路线。

## 查看驱动日志（必要时）
Get-Content -LiteralPath "$env:LOCALAPPDATA\zy_home_vibe_coding_driver\service.json"
Get-Content -Tail 100 -LiteralPath "$env:LOCALAPPDATA\zy_home_vibe_coding_driver\service.log"
service.json 中的 baseUrl 应指向本机回环地址，是本地投递用的，不要公开到局域网或互联网，也不是 MCP URL。