khy-bridge 实战联调指南#

把自研内核 KHY-OS 接到真 agent 上。两条路线对应需求1的两侧，都走同一个
KhyBridge（COM2 串口 ⇄ JSON，三面：控制/决策/事件），互不重复协议逻辑。

                ┌──────────── KHY-OS (QEMU) ────────────┐
                │  COM1 = 人类 TTY    COM2 = agent 通道  │
                └───────────────┬───────────────────────┘
                                │ unix socket (/tmp/khy-agent.sock)
                ┌───────────────┴───────────────┐
        side a │ 内置 KHY Node agent            │ side b
   khy-agent-run.js  (in-process, brain=网关)   khy-mcp.js (MCP server)
        决策面真模型决策                         外部 agent（Claude Code）驱动控制面

任一时刻 COM2 只接一个客户端（QEMU unix socket server 单连接），所以
side a 与 side b 二选一连，不同时连。

先决条件#

make -C kernel            # 构建 ISO（产物 kernel/build/khy-os-kernel.iso）

启动带 agent 串口的 KHY-OS（COM1 走 stdio 给人，COM2 走 unix socket 给 agent）：

make -C kernel run-agent  # COM2 默认 = /tmp/khy-agent.sock（AGENT_SOCK 可改）

路线 A：内置 agent + 项目 AI 网关（真模型决策）#

让 OS 里的 ai <自然语言> 和 agentask <问题> 由真实大模型作答。

1. 起项目 AI 网关（OpenAI 兼容，默认 127.0.0.1:9100，token 在

~/.khy/proxy_server_auth.json 自动生成）。

1. 跑内置 agent：

   node kernel/bridge/khy-agent-run.js              # 连 /tmp/khy-agent.sock
   # 或显式：node kernel/bridge/khy-agent-run.js --socket /tmp/khy-agent.sock

1. 在 OS 的 COM1 shell 里：

   ai use model claude/claude-sonnet-4-20250514     # 选模型，落 /disk/etc/agent.conf
   ai 帮我把当前模型告诉我                            # GET，回显配置
   agentask 我可以删除整个磁盘吗                      # 决策面 → 模型判 DENY

选模型后让 agent 重读配置（无需重启）：kill -HUP <khy-agent-run 进程>。

环境变量（均可选，opts > env > 默认）：

松耦合保证：网关不可达 / 401 / 超时，brain 自动降级为内置规则脑（defaultBrain），
内核永远拿得到合法答案，绝不被挂死。需要 /disk 才能持久化模型配置，故跑 ai set ...
时请给 QEMU 加 -hda（run-agent 默认未挂盘，可在 Makefile 加，或仅做非持久测试）。

路线 B：外部 agent（Claude Code）经 MCP 驱动 OS#

让 Claude Code 直接 list/read/write KHY-OS 文件、看进程、读配置。

仓库根已带 .mcp.json（project-scoped），声明了 khy-os MCP server：

{
  "mcpServers": {
    "khy-os": {
      "command": "node",
      "args": ["kernel/bridge/khy-mcp.js", "--socket", "/tmp/khy-agent.sock"],
      "env": { "KHY_MCP_CONNECT_TIMEOUT_MS": "60000" }
    }
  }
}

在仓库根开 Claude Code，它会发现该 server（首次需在 /mcp 里批准 project server）。
或手动注册：

claude mcp add khy-os -- node kernel/bridge/khy-mcp.js --socket /tmp/khy-agent.sock

khy-mcp.js 会等待 COM2 socket 出现（上限 KHY_MCP_CONNECT_TIMEOUT_MS，默认 30s，
.mcp.json 里设 60s），所以先开 Claude Code 再 make run-agent 也能自动挂上。

挂上后，Claude Code 会看到这些工具（与内置 agent 共用同一份 khy-tools.js）：

例：让 Claude “列出 KHY-OS 根目录并读 /etc/motd” → 走 khy_list + khy_read →
真实命中内核 VFS。

诊断只走 stderr，stdout 仅 MCP 协议字节，不会污染 JSON-RPC。