Kimi Code CLI 扩展能力与生态集成教程
Kimi Code CLI 扩展能力与生态集成教程
kimi acp 子命令
2 分钟阅读
kimi acp 子命令
kimi acp 是 Kimi Code CLI 面向IDE集成场景设计的专用子命令，用于将CLI切换到 ACP (Agent Client Protocol) 模式：在标准输入/输出上以 JSON-RPC 2.0 协议与 ACP 客户端（如 Zed、JetBrains AI Chat、VS Code等）对话，让IDE可以直接驱动 Kimi 的会话、Prompt 与工具调用能力，开发者无需在IDE和终端之间切换，即可在编码界面内直接使用Kimi Code的全量功能，大幅提升编码效率。
启动后命令不会打印任何 banner 或额外输出，立刻等待 ACP 客户端在 stdin 上发出 initialize 握手请求，确保标准输入输出流的纯净，避免JSON-RPC消息混入多余内容导致解析失败。日志会写到标准错误（以及 ~/.kimi-code/logs/ 下的诊断日志文件），ACP 通信通道本身保持干净，不影响协议交互。
排查指南：若IDE连接Kimi Code失败，可查看
~/.kimi-code/logs/下的acp-*.log日志文件，定位握手失败、消息解析错误等问题。
能力矩阵
下表列出当前 ACP 适配层声明的全量能力，agentCapabilities 字段会在 initialize 握手响应里完整返回，IDE 端可据此调整 UI 展示与功能适配，避免调用未支持的能力。
| 能力 | 取值 | 说明 |
|---|---|---|
promptCapabilities.image | true | 支持 ACP image 内容块（base64 + mimeType），IDE内粘贴截图可直接发送给Kimi多模态模型 |
promptCapabilities.audio | false | 暂不支持音频 prompt，后续版本将逐步开放 |
promptCapabilities.embeddedContext | true | 客户端可发送 resource/resource_link 嵌入式资源块，文本内容会以 <resource uri="...">...</resource> 形式注入 prompt；blob 资源被丢弃并打印warn日志，无需特殊处理 |
mcpCapabilities.http | true | 转发 IDE 配置的 HTTP MCP 服务，无需在CLI中重复配置MCP |
mcpCapabilities.sse | true | 转发 IDE 配置的旧式 SSE MCP 服务，兼容旧版MCP协议 |
loadSession | true | 支持 session/load 续接已有会话，加载时会同步回放历史消息到IDE，保持会话上下文一致 |
sessionCapabilities.list | {} | 支持 session/list 枚举当前用户的所有历史会话，IDE可实现会话选择器功能 |
ACP 方法覆盖
ACP 规范把方法分为稳定面和仍在演化的不稳定面（@agentclientprotocol/sdk@0.23.0 中以 unstable_* 前缀挂载的 handler）。两部分稳定性保证完全不同——稳定面是任何生产 ACP 客户端都会用到的核心方法，提供长期兼容性保证；不稳定面覆盖实验性扩展（inline-edit 预测、document 缓冲区同步、provider 管理、elicitation 等），接口可能随时变更，因此分开追踪。
概览：稳定面 agent-side 实现 10/12（83%）+ client reverse-RPC 实现 4/9（44%）；不稳定面只接入了 session/set_model（1/19）。 任何正常 Agent 流程所需的核心方法（initialize → auth → new/load/resume → prompt → cancel + 文件 I/O + 工具审批）都已实现，可满足IDE集成的全部核心需求。
稳定面 agent-side — IDE → agent（10 / 12）
该类方法是IDE向Agent发起的请求，用于控制会话生命周期、发送prompt、修改配置等。
| 方法 | 状态 | 说明 |
|---|---|---|
initialize | 是 | 版本协商；返回 agentInfo: { name: 'Kimi Code CLI', version }、能力矩阵、authMethods，是ACP通信的第一个请求 |
authenticate | 是 | 校验 method_id='login'；token 缺失返回 authRequired (-32000)，IDE会弹出登录提示；未知 id 返回 invalidParams (-32602) |
session/new | 是 | 接受 cwd / mcpServers，返回 configOptions[]，创建新会话时会自动关联IDE当前打开的项目目录 |
session/load | 是 | 恢复磁盘会话并把历史以 session/update 同步回放给IDE，确保IDE与CLI的会话历史完全一致 |
session/resume | 是 | session/load 的轻量兄弟方法，跳过历史回放，加载速度更快，适合不需要查看历史的场景 |
session/prompt | 是 | 接受 text / image / resource / resource_link 内容块，流式输出 agent_message_chunk，实现IDE内的打字机效果 |
session/cancel | 是 | 中断当前生成轮次，与终端内的Ctrl-C效果一致 |
session/list | 是 | 枚举磁盘会话（通过 sessionCapabilities.list = {} 公告），IDE可基于此实现会话选择界面 |
session/set_mode | 是 | 兼容路径，与 set_config_option({configId:'mode'}) 走同一 dispatcher，用于切换会话模式 |
session/set_config_option | 是 | 统一的 model / thinking / mode picker 分发接口，IDE内的模型切换、权限修改等操作均通过该接口实现 |
session/close | 否 | 暂未实现，IDE销毁子进程时直接终止即可，会话会自动保存 |
logout | 否 | 暂未实现，可通过终端内的/logout命令或删除配置文件完成退出登录 |
稳定面 client-side reverse-RPC — agent → IDE（4 / 9）
该类方法是Agent反向调用IDE的接口，用于向IDE推送生成内容、请求审批、读写文件等。
| 方法 | 状态 | 说明 |
|---|---|---|
session/update | 是 | 流式推送 agent_message_chunk / tool_call* / plan / config_option_update / available_commands_update，IDE可实时更新界面 |
session/request_permission | 是 | 工具审批和问题 elicitation 共用此通道，IDE会弹出审批弹窗供用户操作 |
fs/read_text_file | 是 | kaos 层文件读取路由到客户端，可读取IDE中未保存的缓冲区内容，确保AI拿到的是最新的文件版本 |
fs/write_text_file | 是 | kaos 层文件写入路由到客户端，写入后会自动触发IDE的文件刷新，无需用户手动 reload |
terminal/create · output · release · kill · wait_for_exit | 否 | 终端 reverse-RPC 未接，shell 命令走本地执行，输出可在CLI日志或TUI中查看 |
不稳定面（1 / 19）
不稳定面为ACP协议的实验性功能，接口可能随时变更，仅实现了高频使用的兼容接口，其余方法均返回methodNotFound错误。
| 方法 | 状态 | 说明 |
|---|---|---|
session/set_model | 是 | 兼容路径，等价于 set_config_option({configId:'model'})，用于兼容旧版IDE插件的模型切换逻辑 |
| 其余 18 个方法 | 否 | 包括 session 生命周期扩展、缓冲区同步、inline-edit 预测、provider 管理等，后续将根据协议成熟度逐步适配 |
上述未列出的方法一律返回 methodNotFound 错误，IDE端需做好兼容处理。
MCP 转发
ACP 客户端在 session/new 或 session/load 中提供 mcpServers 时，适配层会自动做如下转换，无需在CLI中重复配置MCP服务：
http→ kimi 的transport: 'http'配置stdio→ kimi 的transport: 'stdio'配置sse→ kimi 的transport: 'sse'配置acp→ 丢弃并写一条 warn 日志，暂不支持ACP类型的MCP服务，可忽略该警告或转换为其他类型的MCP