feat(acp): implement ACP server with session lifecycle, tool streaming, and IDE integration (#368)

This commit scaffolds the @moonshot-ai/acp-adapter package and introduces the full ACP (Agent Communication Protocol) server implementation for Kimi Code CLI, including: - Scaffold @moonshot-ai/acp-adapter workspace package with build skeleton - `kimi acp` CLI subcommand and stdout-safe logging - ACP version negotiation and AgentSideConnection wrapper - Auth gate for session creation - Session lifecycle: new, list, load with history replay - Prompt content conversion (text, image, embedded resources, resource links) - Assistant streaming with thinking support and end-turn handling - Tool call streaming (started, delta, progress) with result conversion (text / diff) - Approval handling with diff/text display blocks mapped to ACP options - Kaos read/write interface (AcpKaos) for unsaved buffer access - Session mode (yolo/auto) and model management - Config options builder with thinking toggle - MCP server forwarding from ACP to harness - Agent plan updates and available commands updates - AskUserQuestion bridged to session/request_permission - Plan review options surfaced through requestPermission - Error mapping, ext_method stubs, and graceful shutdown - IDE integration guide (Zed + JetBrains) - End-to-end tests against ACP TS SDK client
2026-07-09 17:29:12 +00:00 · 2026-06-03 21:11:30 +08:00 · 2026-06-03 21:11:30 +08:00 · 3eafa79f39
commit 3eafa79f39
parent 8639105313
84 changed files with 13691 additions and 15 deletions
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@ -47,6 +47,7 @@ export default withMermaid(defineConfig({
                { text: '常见使用案例', link: '/zh/guides/use-cases' },
                { text: '交互与输入', link: '/zh/guides/interaction' },
                { text: '会话与上下文', link: '/zh/guides/sessions' },
+                { text: '在 IDE 中使用', link: '/zh/guides/ides' },
              ],
            },
          ],
@ -79,6 +80,7 @@ export default withMermaid(defineConfig({
              text: '参考手册',
              items: [
                { text: 'kimi 命令', link: '/zh/reference/kimi-command' },
+                { text: 'kimi acp 子命令', link: '/zh/reference/kimi-acp' },
                { text: '内置工具', link: '/zh/reference/tools' },
                { text: '斜杠命令', link: '/zh/reference/slash-commands' },
                { text: '键盘快捷键', link: '/zh/reference/keyboard' },
@ -121,6 +123,7 @@ export default withMermaid(defineConfig({
                { text: 'Common Use Cases', link: '/en/guides/use-cases' },
                { text: 'Interaction and Input', link: '/en/guides/interaction' },
                { text: 'Sessions and Context', link: '/en/guides/sessions' },
+                { text: 'Using in IDEs', link: '/en/guides/ides' },
              ],
            },
          ],
@ -153,6 +156,7 @@ export default withMermaid(defineConfig({
              text: 'Reference',
              items: [
                { text: 'kimi Command', link: '/en/reference/kimi-command' },
+                { text: 'kimi acp Subcommand', link: '/en/reference/kimi-acp' },
                { text: 'Built-in Tools', link: '/en/reference/tools' },
                { text: 'Slash Commands', link: '/en/reference/slash-commands' },
                { text: 'Keyboard Shortcuts', link: '/en/reference/keyboard' },
--- a/docs/en/guides/ides.md
+++ b/docs/en/guides/ides.md
@ -0,0 +1,69 @@
+# Using in IDEs
+
+Kimi Code CLI integrates with IDEs through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/), so you can use AI-assisted coding directly inside your editor.
+
+## Prerequisites
+
+Before configuring your IDE, make sure Kimi Code CLI is installed and signed in.
+
+The ACP adapter exposes a `kimi acp` subcommand. The IDE launches it as a child process and speaks JSON-RPC on its stdio. Every session reuses the CLI's existing auth state — no separate login is required from inside the IDE.
+
+::: tip Path note
+On macOS, child processes spawned by an IDE's GUI typically do **not** inherit the `PATH` from your terminal shell. If `kimi` lives anywhere other than the usual `/usr/local/bin`-style directories, configure the IDE with an **absolute path**. Run `which kimi` in a terminal to find the current location.
+:::
+
+## Using in Zed
+
+[Zed](https://zed.dev/) is a modern editor with native ACP support.
+
+Add the following to Zed's configuration file `~/.config/zed/settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "Kimi Code CLI": {
+      "type": "custom",
+      "command": "kimi",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Field reference:
+
+- `type`: fixed value `"custom"`.
+- `command`: path to the Kimi Code CLI executable. If `kimi` is not on `PATH`, use a full absolute path (e.g. `/Users/you/.local/bin/kimi`).
+- `args`: startup arguments. The `acp` subcommand switches Kimi Code into ACP mode.
+- `env`: extra environment variables. Usually empty — Zed injects a sensible default environment.
+
+After saving, opening a new chat in Zed's Agent panel will spawn an ACP-mode `kimi` subprocess using your configuration. Any MCP servers declared inside Zed's `agent_servers` block are forwarded to Kimi Code via the ACP protocol.
+
+## Using in JetBrains IDEs
+
+JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, …) support ACP through the AI Chat plugin.
+
+If you do not have a JetBrains AI subscription, enable `llm.enable.mock.response` in the Registry so you can still reach the AI Chat panel when only ACP is needed. Press Shift twice to search for "Registry" and open it.
+
+From the AI Chat panel menu, click "Configure ACP agents" and add the following:
+
+```json
+{
+  "agent_servers": {
+    "Kimi Code CLI": {
+      "command": "~/.local/bin/kimi",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+JetBrains is strict about the `command` field — always use an **absolute path**. `which kimi` in a terminal will print the right value. After saving, `Kimi Code CLI` will appear in the AI Chat Agent selector.
+
+## Troubleshooting
+
+- **The session terminates immediately / the IDE shows "agent exited"**: usually a bad `command` path or the CLI is not signed in. Run `kimi acp` in a terminal: if it blocks waiting for stdin, the CLI itself is healthy and the issue is the IDE config; if it errors immediately, follow the message (most commonly `/login` is missing).
+- **The IDE shows "auth required"**: there's no usable auth token. Quit the IDE, run `kimi` in a terminal to sign in, then relaunch the IDE.
+- **MCP tools don't show up**: see the capability matrix in [`kimi acp`](../reference/kimi-acp.md) and confirm the MCP transport you configured is supported. The current ACP adapter forwards `http` and `stdio` transports; `sse` and `acp` MCP entries are silently dropped and a warn line is written to the diagnostic log.
--- a/docs/en/reference/kimi-acp.md
+++ b/docs/en/reference/kimi-acp.md
@ -0,0 +1,151 @@
+# `kimi acp` Subcommand
+
+`kimi acp` switches Kimi Code CLI into **ACP (Agent Client Protocol)** mode: it speaks JSON-RPC on stdio to an ACP client (Zed, JetBrains AI Chat, etc.) so an IDE can drive kimi's sessions, prompts, and tool calls directly.
+
+```sh
+kimi acp
+```
+
+When launched, the command prints no banner — it immediately waits for an `initialize` request on stdin. Logs go to stderr (and to the diagnostic log under `~/.kimi-code/logs/`), keeping the ACP channel clean.
+
+::: tip Who calls this?
+You typically never run `kimi acp` by hand — it's the subprocess entry point an IDE will spawn. For the IDE-side configuration, see [Using in IDEs](../guides/ides.md).
+:::
+
+## Capability Matrix
+
+The ACP adapter advertises the following capabilities in its `initialize` response. IDEs can use these to enable or disable UI affordances.
+
+| Capability | Value | Notes |
+| --- | --- | --- |
+| `promptCapabilities.image` | `true` | Accepts ACP `image` content blocks (base64 + mimeType). |
+| `promptCapabilities.audio` | `false` | Audio prompts are not supported. |
+| `promptCapabilities.embeddedContext` | `false` | Embedded resource prompts are not advertised; `resource`/`resource_link` are still accepted through the text channel. |
+| `mcpCapabilities.http` | `true` | HTTP MCP servers from the IDE are forwarded. |
+| `mcpCapabilities.sse` | `false` | SSE MCP servers are dropped (with a warn log). |
+| `loadSession` | `true` | `session/load` is supported; history is replayed via `session/update` on resume. |
+| `sessionCapabilities.list` | `{}` | `session/list` enumerates the user's sessions. |
+
+## ACP method coverage
+
+The spec splits methods into a **stable** surface and a still-evolving **unstable** surface (the `unstable_*`-prefixed handlers on `@agentclientprotocol/sdk@0.23.0`). The two are tracked separately because they have very different stability guarantees — the stable surface is what any production ACP client will exercise; the unstable surface covers experimental extensions (inline-edit predictions, document buffer sync, provider management, elicitation, etc.).
+
+**Summary: 10/12 stable agent-side methods (83%) + 4/9 stable client reverse-RPCs (44%); on the unstable surface only `session/set_model` is wired (1/19).** Every method needed for a normal agent flow (initialize → auth → new/load/resume → prompt → cancel + file I/O + tool approval) is implemented.
+
+### Stable agent-side — IDE → agent (10 / 12)
+
+| Method | Status | Notes |
+| --- | --- | --- |
+| `initialize` | yes | Version negotiation; returns `agentInfo: { name: 'Kimi Code CLI', version }`, capability matrix, `authMethods` |
+| `authenticate` | yes | Validates `method_id='login'`; missing token → `authRequired (-32000)`, unknown id → `invalidParams (-32602)` |
+| `session/new` | yes | Accepts `cwd` / `mcpServers`; returns `configOptions[]` |
+| `session/load` | yes | Rehydrates on-disk session and replays history as `session/update` notifications |
+| `session/resume` | yes | Lighter-weight sibling of `session/load`; skips history replay (spec G4) |
+| `session/prompt` | yes | Accepts `text` / `image` / `resource` / `resource_link` content blocks; streams `agent_message_chunk` |
+| `session/cancel` | yes | Interrupts the current turn |
+| `session/list` | yes | Enumerates on-disk sessions (advertised via `sessionCapabilities.list = {}`) |
+| `session/set_mode` | yes | Compatibility path; funnels into the same dispatcher as `set_config_option({configId:'mode'})` |
+| `session/set_config_option` | yes | Unified model / thinking / mode picker dispatch |
+| `session/close` | no | |
+| `logout` | no | |
+
+### Stable client-side reverse-RPC — agent → IDE (4 / 9)
+
+| Method | Status | Notes |
+| --- | --- | --- |
+| `session/update` | yes | Streams `agent_message_chunk` / `tool_call*` / `plan` / `config_option_update` / `available_commands_update` |
+| `session/request_permission` | yes | Tool approvals and question elicitation share this channel |
+| `fs/read_text_file` | yes | kaos file reads route to the client (advertised by `fsCapabilities`) |
+| `fs/write_text_file` | yes | kaos file writes route to the client |
+| `terminal/create` · `output` · `release` · `kill` · `wait_for_exit` | no | Terminal reverse-RPC not yet wired; shell commands run locally |
+
+### Unstable surface (1 / 19)
+
+| Method | Status | Notes |
+| --- | --- | --- |
+| `session/set_model` | yes | Compatibility path; equivalent to `set_config_option({configId:'model'})`. Also accepts the legacy `'<alias>,thinking'` merged form, which is split into a bare-model `setModel` plus an implicit `setThinking('high')` |
+| `session/delete` · `session/fork` | no | Session lifecycle extensions |
+| `document/didOpen` · `didChange` · `didClose` · `didFocus` · `didSave` | no | Editor buffer sync |
+| `nes/start` · `suggest` · `accept` · `reject` · `close` | no | Inline-edit predictions |
+| `providers/list` · `set` · `disable` | no | Built-in provider management (use `kimi provider` instead) |
+| `elicitation/create` · `elicitation/complete` | no | Currently overlapped by `session/request_permission` |
+
+(`mcp/connect`, `mcp/disconnect`, `mcp/message` are declared in the SDK enum but not yet routed by the SDK dispatcher itself, so they sit outside the coverage denominator.)
+
+Any method not listed above returns `methodNotFound`.
+
+## Session configOptions
+
+Starting in Phase 14, `session/new` and `session/load` no longer return a dedicated `modes` field. Instead, both pickers ride on the ACP spec's generic `configOptions: SessionConfigOption[]` surface. Phase 15 split thinking out of the model id into its own axis, and Phase 16 reshaped that axis from `SessionConfigBoolean` to a 2-entry `select` (`off` / `on`) so Zed renders it — Zed's chip strip currently only knows how to draw `type: 'select'`. The advertisement now ships up to three options:
+
+- `id: 'model'` (`type: 'select'`, `category: 'model'`) — one row per configured model alias. **No more `,thinking` variant rows** — thinking has moved to a separate axis below.
+- `id: 'thinking'` (`type: 'select'`, `category: 'thought_level'`, options `[{value:'off'},{value:'on'}]`) — appears **only when the currently-selected model's catalog entry advertises `thinkingSupported`**. Switching to a non-thinking model causes the next `config_option_update` to omit this option entirely; the client should re-render the picker strip accordingly.
+- `id: 'mode'` (`type: 'select'`, `category: 'mode'`) — the locked four-mode taxonomy from PLAN D9: `default` / `plan` / `auto` / `yolo`.
+
+Example `configOptions` payload (current model supports thinking):
+
+```json
+{
+  "configOptions": [
+    {
+      "type": "select",
+      "id": "model",
+      "name": "Model",
+      "category": "model",
+      "currentValue": "kimi-coder",
+      "options": [
+        { "value": "kimi-coder", "name": "Kimi Coder" },
+        { "value": "kimi-v2", "name": "Kimi v2" }
+      ]
+    },
+    {
+      "type": "select",
+      "id": "thinking",
+      "name": "Thinking",
+      "category": "thought_level",
+      "currentValue": "off",
+      "options": [
+        { "value": "off", "name": "Thinking Off" },
+        { "value": "on", "name": "Thinking On" }
+      ]
+    },
+    {
+      "type": "select",
+      "id": "mode",
+      "name": "Mode",
+      "category": "mode",
+      "currentValue": "default",
+      "options": [
+        { "value": "default", "name": "Default", "description": "Manual approvals; tools execute normally." },
+        { "value": "plan", "name": "Plan", "description": "Read-only planning; no tool execution." },
+        { "value": "auto", "name": "Auto", "description": "Auto-approve safe operations." },
+        { "value": "yolo", "name": "YOLO", "description": "Auto-approve everything." }
+      ]
+    }
+  ]
+}
+```
+
+**Switching:** clients should prefer the generic `session/set_config_option({ sessionId, configId, type, value })` path. For compatibility, `session/set_session_mode` and `session/unstable_set_session_model` still work — the entry points all funnel to the same execution path inside the adapter. Notes on each `configId`:
+
+- `'model'` accepts the bare alias id (e.g. `'kimi-coder'`) or the legacy merged form `'kimi-coder,thinking'` — the latter is split into a bare-model `setModel` plus an implicit thinking-on call so older clients keep working.
+- `'thinking'` accepts the strings `'on'` / `'off'` and maps to `Session.setThinking('high')` (`'on'`) or `Session.setThinking('off')` (`'off'`). The granularity of `'low' / 'medium' / 'xhigh' / 'max'` is intentionally hidden behind the binary wire — Phase 16 uses a 2-entry `select` instead of `SessionConfigBoolean` for Zed UI compatibility only.
+- `'mode'` accepts one of `'default' / 'plan' / 'auto' / 'yolo'` (PLAN D9).
+
+**Change notifications:** every model, thinking, or mode change pushes `sessionUpdate: 'config_option_update'` with the full `configOptions` snapshot. Phase 12's `current_mode_update` has been retired and is no longer emitted.
+
+## MCP Forwarding
+
+When an ACP client provides `mcpServers` in `session/new` or `session/load`, the adapter converts them as follows:
+
+- `http` → kimi `transport: 'http'` (headers projected to `Record<string, string>`).
+- `stdio` → kimi `transport: 'stdio'` (env projected the same way).
+- `sse` / `acp` → dropped, with a warn log line, so unsupported transports never silently fall through.
+
+## When to Use `kimi acp`
+
+- **Direct IDE integration**: see [Using in IDEs](../guides/ides.md).
+- **Custom ACP client**: connect `@agentclientprotocol/sdk`'s `ClientSideConnection` to `kimi acp`'s stdio. A single client implementation can then drive kimi, Claude Code, or any other ACP agent.
+- **Local integration testing**: this repository's `packages/acp-adapter` ships an in-memory pipe end-to-end test that exercises `initialize` → `session/new` → `session/prompt` → `end_turn`, which can serve as a reference implementation.
+
+For normal CLI interactions, keep using `kimi` (without the `acp` subcommand) to launch the TUI.
--- a/docs/en/reference/kimi-command.md
+++ b/docs/en/reference/kimi-command.md
@ -122,6 +122,16 @@ In `stream-json` mode, each stdout line is one JSON object. Ordinary replies are

 ## Subcommands

+### `kimi login`
+
+Authenticate Kimi Code CLI with the Kimi Code OAuth provider via the RFC 8628 device-code flow, without entering the TUI. The command opens a device authorization request, prints the verification URL and user code to stderr, then polls until the browser flow completes. The resulting token is written to the same on-disk location used by the in-TUI `/login` command, so the next `kimi` invocation picks it up automatically.
+
+```sh
+kimi login
+```
+
+This subcommand takes no flags. It is the entry point that ACP-compatible editors invoke via the `terminal-auth` authentication method advertised by `kimi acp`. Press Ctrl-C at any time to cancel the pending device-code poll; the command exits with status `1` on cancellation or failure, `0` on success.
+
 ### `kimi export`

 Bundle a session into a ZIP file for sharing, archival, or bug reports. The exported archive contains all files under the session directory, such as context records, state files, and the session diagnostic log if that session has already produced `logs/kimi-code.log`.
--- a/docs/zh/guides/ides.md
+++ b/docs/zh/guides/ides.md
@ -0,0 +1,69 @@
+# 在 IDE 中使用
+
+Kimi Code CLI 支持通过 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) 集成到 IDE 中，让你在编辑器内直接使用 AI 辅助编程。
+
+## 前置准备
+
+在配置 IDE 之前，请确保已安装 Kimi Code CLI 并完成登录配置。
+
+ACP 适配层暴露子命令 `kimi acp`，IDE 通过子进程方式启动它，并在标准输入/输出上跑 JSON-RPC。每次 IDE 创建会话时，CLI 会复用它的鉴权状态——不需要重复登录。
+
+::: tip 路径提示
+macOS 下从 IDE GUI 启动的子进程通常**不会**继承终端 shell 的 `PATH`，所以如果 `kimi` 不在 `/usr/local/bin` 这类系统目录里，IDE 配置中要使用绝对路径。终端里运行 `which kimi` 可以查到当前生效的路径。
+:::
+
+## 在 Zed 中使用
+
+[Zed](https://zed.dev/) 是一个原生支持 ACP 的现代编辑器。
+
+在 Zed 的配置文件 `~/.config/zed/settings.json` 中添加：
+
+```json
+{
+  "agent_servers": {
+    "Kimi Code CLI": {
+      "type": "custom",
+      "command": "kimi",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+配置说明：
+
+- `type`：固定值 `"custom"`
+- `command`：Kimi Code CLI 的可执行路径。如果 `kimi` 不在 PATH 中，请使用完整路径（例如 `/Users/you/.local/bin/kimi`）。
+- `args`：启动参数。`acp` 子命令切换到 ACP 模式。
+- `env`：附加环境变量，通常留空即可。Zed 会自动注入一份默认环境。
+
+保存配置后，在 Zed 的 Agent 面板里新建一次对话，就会以你刚才配置的 `Kimi Code CLI` 启动一个 ACP 子进程。Zed 在 `agent_servers` 这层声明的 MCP 服务也会通过 ACP 协议转发到 kimi 这一侧。
+
+## 在 JetBrains IDE 中使用
+
+JetBrains 系列 IDE（IntelliJ IDEA、PyCharm、WebStorm 等）通过 AI 聊天插件支持 ACP。
+
+如果没有 JetBrains AI 订阅，可以在注册表中启用 `llm.enable.mock.response`，便于在仅使用 ACP 的场景里访问 AI 聊天面板。连按两次 Shift 搜索 "Registry / 注册表" 即可打开。
+
+在 AI 聊天面板的菜单中点击 "Configure ACP agents"，添加以下配置：
+
+```json
+{
+  "agent_servers": {
+    "Kimi Code CLI": {
+      "command": "~/.local/bin/kimi",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+JetBrains 这一侧对 `command` 字段处理较严格——务必填写**绝对路径**，可以在终端执行 `which kimi` 拿到。保存后，AI 聊天的 Agent 选择器里就会出现 `Kimi Code CLI`。
+
+## 故障排查
+
+- **会话立刻被中断 / IDE 提示 "agent exited"**：通常是 `command` 路径不对或 kimi 没登录。先在终端跑一次 `kimi acp` 验证：如果阻塞等待标准输入则说明 CLI 本身没问题，问题在 IDE 配置；如果立刻报错则按报错提示处理（多数是没 `/login`）。
+- **IDE 显示 "auth required"**：表示 CLI 没有可用的鉴权令牌。退出 IDE，在终端执行 `kimi` 完成登录后再启动 IDE 即可。
+- **MCP 工具看不到**：参考 [`kimi acp`](../reference/kimi-acp.md) 中的能力表确认 IDE 配的 MCP 传输类型是否被支持。当前 Kimi Code CLI 的 ACP 适配层支持 `http`、`stdio` 两种传输方式，`sse` 与 `acp` 类型会被静默丢弃并在日志中给出 warn。
--- a/docs/zh/reference/kimi-acp.md
+++ b/docs/zh/reference/kimi-acp.md
@ -0,0 +1,151 @@
+# `kimi acp` 子命令
+
+`kimi acp` 把 Kimi Code CLI 切换到 **ACP (Agent Client Protocol)** 模式：在标准输入/输出上以 JSON-RPC 形式与 ACP 客户端（如 Zed、JetBrains AI Chat 等）对话，让 IDE 直接驱动 kimi 的会话、prompt 与工具调用。
+
+```sh
+kimi acp
+```
+
+启动后命令不会打印任何 banner，立刻等待 ACP 客户端在 stdin 上发出 `initialize` 请求。日志会写到标准错误（以及 `~/.kimi-code/logs/` 下的诊断日志），所以 ACP 通道本身保持干净。
+
+::: tip 谁会调用它？
+你通常不需要手动跑 `kimi acp`——这个命令是给 IDE 的子进程入口准备的。IDE 端的配置见 [在 IDE 中使用](../guides/ides.md)。
+:::
+
+## 能力矩阵
+
+下表列出当前 ACP 适配层声明的能力。`agentCapabilities` 字段在 `initialize` 响应里完整返回，IDE 端可据此调整 UI。
+
+| 能力 | 取值 | 说明 |
+| --- | --- | --- |
+| `promptCapabilities.image` | `true` | 支持 ACP `image` 内容块（base64 + mimeType）。 |
+| `promptCapabilities.audio` | `false` | 暂不支持音频 prompt。 |
+| `promptCapabilities.embeddedContext` | `false` | 暂不支持嵌入式资源 prompt（`resource`/`resource_link` 走文本通道）。 |
+| `mcpCapabilities.http` | `true` | 转发 IDE 配置的 HTTP MCP 服务。 |
+| `mcpCapabilities.sse` | `false` | 不支持 SSE MCP 服务，相关条目会被丢弃并写 warn 日志。 |
+| `loadSession` | `true` | 支持 `session/load` 续接已有会话，加载时会同步回放历史。 |
+| `sessionCapabilities.list` | `{}` | 支持 `session/list` 枚举当前用户的会话。 |
+
+## 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 + 工具审批）都已实现。
+
+### 稳定面 agent-side — IDE → agent（10 / 12）
+
+| 方法 | 状态 | 说明 |
+| --- | --- | --- |
+| `initialize` | 是 | 版本协商；返回 `agentInfo: { name: 'Kimi Code CLI', version }`、能力矩阵、`authMethods` |
+| `authenticate` | 是 | 校验 `method_id='login'`；token 缺失返回 `authRequired (-32000)`，未知 id 返回 `invalidParams (-32602)` |
+| `session/new` | 是 | 接受 `cwd` / `mcpServers`，返回 `configOptions[]` |
+| `session/load` | 是 | 恢复磁盘会话并把历史以 `session/update` 同步回放 |
+| `session/resume` | 是 | `session/load` 的轻量兄弟方法，跳过历史回放（spec G4） |
+| `session/prompt` | 是 | 接受 `text` / `image` / `resource` / `resource_link` 内容块，流式输出 `agent_message_chunk` |
+| `session/cancel` | 是 | 中断当前 turn |
+| `session/list` | 是 | 枚举磁盘会话（通过 `sessionCapabilities.list = {}` 公告） |
+| `session/set_mode` | 是 | 兼容路径，与 `set_config_option({configId:'mode'})` 走同一 dispatcher |
+| `session/set_config_option` | 是 | 统一的 model / thinking / mode picker 分发 |
+| `session/close` | 否 | |
+| `logout` | 否 | |
+
+### 稳定面 client-side reverse-RPC — agent → IDE（4 / 9）
+
+| 方法 | 状态 | 说明 |
+| --- | --- | --- |
+| `session/update` | 是 | 流式推送 `agent_message_chunk` / `tool_call*` / `plan` / `config_option_update` / `available_commands_update` |
+| `session/request_permission` | 是 | 工具审批和问题 elicitation 共用此通道 |
+| `fs/read_text_file` | 是 | kaos 层文件读取路由到客户端（通过 `fsCapabilities` 公告） |
+| `fs/write_text_file` | 是 | kaos 层文件写入路由到客户端 |
+| `terminal/create` · `output` · `release` · `kill` · `wait_for_exit` | 否 | 终端 reverse-RPC 未接，shell 命令走本地执行 |
+
+### 不稳定面（1 / 19）
+
+| 方法 | 状态 | 说明 |
+| --- | --- | --- |
+| `session/set_model` | 是 | 兼容路径，等价于 `set_config_option({configId:'model'})`。也接受老的 `'<alias>,thinking'` 合并形式，会被拆为裸 model 的 `setModel` 加一次隐式的 `setThinking('high')` |
+| `session/delete` · `session/fork` | 否 | 会话生命周期扩展 |
+| `document/didOpen` · `didChange` · `didClose` · `didFocus` · `didSave` | 否 | 编辑器缓冲区同步 |
+| `nes/start` · `suggest` · `accept` · `reject` · `close` | 否 | inline-edit 预测 |
+| `providers/list` · `set` · `disable` | 否 | 内置 provider 管理（请用 `kimi provider`） |
+| `elicitation/create` · `elicitation/complete` | 否 | 当前由 `session/request_permission` 覆盖 |
+
+（`mcp/connect`、`mcp/disconnect`、`mcp/message` 虽然在 SDK enum 中声明，但 SDK 本身的 dispatcher 尚未路由，故不计入分母。）
+
+上述未列出的方法一律返回 `methodNotFound`。
+
+## 会话 configOptions
+
+Phase 14 起，`session/new` 和 `session/load` 不再返回独立的 `modes` 字段，而是把所有 picker 都收敛到 ACP 规范的通用 `configOptions: SessionConfigOption[]` 数组下。Phase 15 进一步把 thinking 从 model id 拆出来变成独立的轴，Phase 16 把 thinking 从 `SessionConfigBoolean` 改成 2 项 `select`（`off` / `on`），因为 Zed 当前的 chip 渲染器只识别 `select`；目前公告**最多三个**选项：
+
+- `id: 'model'`（`type: 'select'`、`category: 'model'`）— 列出 harness 配置的所有 model alias，**不再展开 `,thinking` 变体行**；thinking 走下面独立的轴。
+- `id: 'thinking'`（`type: 'select'`、`category: 'thought_level'`，options 为 `[{value:'off'},{value:'on'}]`）— **仅当当前选中的 model 在 catalog 里标了 `thinkingSupported` 时才出现**；切到不支持的 model 后下次 `config_option_update` 会直接省掉这一条，客户端按 spec 的 "configOptions 集合可在不同更新之间增减" 重绘 picker 即可。
+- `id: 'mode'`（`type: 'select'`、`category: 'mode'`）— 锁定的四模式分类法 PLAN D9：`default` / `plan` / `auto` / `yolo`。
+
+`configOptions` 的样例（当前 model 支持 thinking）：
+
+```json
+{
+  "configOptions": [
+    {
+      "type": "select",
+      "id": "model",
+      "name": "Model",
+      "category": "model",
+      "currentValue": "kimi-coder",
+      "options": [
+        { "value": "kimi-coder", "name": "Kimi Coder" },
+        { "value": "kimi-v2", "name": "Kimi v2" }
+      ]
+    },
+    {
+      "type": "select",
+      "id": "thinking",
+      "name": "Thinking",
+      "category": "thought_level",
+      "currentValue": "off",
+      "options": [
+        { "value": "off", "name": "Thinking Off" },
+        { "value": "on", "name": "Thinking On" }
+      ]
+    },
+    {
+      "type": "select",
+      "id": "mode",
+      "name": "Mode",
+      "category": "mode",
+      "currentValue": "default",
+      "options": [
+        { "value": "default", "name": "Default", "description": "Manual approvals; tools execute normally." },
+        { "value": "plan", "name": "Plan", "description": "Read-only planning; no tool execution." },
+        { "value": "auto", "name": "Auto", "description": "Auto-approve safe operations." },
+        { "value": "yolo", "name": "YOLO", "description": "Auto-approve everything." }
+      ]
+    }
+  ]
+}
+```
+
+**切换：** 客户端推荐统一走 `session/set_config_option({ sessionId, configId, type, value })`。为了向后兼容，旧的 `session/set_session_mode` 和 `session/unstable_set_session_model` 仍可用，所有入口在适配层汇聚到同一个执行路径。各 `configId` 的语义：
+
+- `'model'` 接受裸 alias id（如 `'kimi-coder'`）或旧的合并形式 `'kimi-coder,thinking'`——后者会被拆成裸 model 的 `setModel` 加一次隐式的 thinking-on，老客户端不会断。
+- `'thinking'` 接受字符串 `'on'` / `'off'`，映射到 `Session.setThinking('high')`（`'on'`）或 `Session.setThinking('off')`（`'off'`）。`'low' / 'medium' / 'xhigh' / 'max'` 这种粒度刻意隐藏在适配层背后——ACP 暴露的 thinking 轴是二态的（Phase 16 用 2 项 `select` 而非 `SessionConfigBoolean`，仅为 Zed UI 兼容）。
+- `'mode'` 接受 `'default' / 'plan' / 'auto' / 'yolo'`（PLAN D9）。
+
+**变更通知：** model / thinking / mode 任一改变都会推送 `sessionUpdate: 'config_option_update'`，载荷为完整的 `configOptions` 快照。Phase 12 的 `current_mode_update` 已下线，不再发出。
+
+## MCP 转发
+
+ACP 客户端在 `session/new` 或 `session/load` 中提供 `mcpServers` 时，适配层会做如下转换：
+
+- `http` → kimi 的 `transport: 'http'` 配置（headers 以 `Record<string, string>` 形式传入）。
+- `stdio` → kimi 的 `transport: 'stdio'` 配置（env 同样转 Record）。
+- `sse` / `acp` → 丢弃并写一条 warn 日志，避免错误地静默接受不支持的传输。
+
+## 何时使用 `kimi acp`
+
+- **直接接入 IDE**：见 [在 IDE 中使用](../guides/ides.md)。
+- **写 ACP 客户端**：用 `@agentclientprotocol/sdk` 的 `ClientSideConnection` 接到 `kimi acp` 的 stdio，即可用一份代码同时驱动 kimi、Claude Code 等其他 ACP agent。
+- **本地集成测试**：能力矩阵稳定后，本仓库的 `packages/acp-adapter` 也跑了一个 in-memory pipe 的 e2e 测试，可作为参考实现。
+
+普通 CLI 交互依旧通过 `kimi`（不带 `acp` 子命令）启动 TUI。
--- a/docs/zh/reference/kimi-command.md
+++ b/docs/zh/reference/kimi-command.md
@ -122,6 +122,16 @@ kimi -p "List changed files" --output-format stream-json

 ## 子命令

+### `kimi login`
+
+通过 RFC 8628 device-code 流程登录 Kimi Code OAuth，无需进入 TUI。命令会发起一次 device authorization 请求，将验证地址和用户码打印到 stderr，然后轮询直到浏览器侧完成授权。生成的 token 写入 TUI `/login` 同款的本地位置，下次启动 `kimi` 时会自动加载。
+
+```sh
+kimi login
+```
+
+该子命令没有任何 flag。它就是 `kimi acp` 通过 `terminal-auth` 认证方式公告给 ACP 编辑器的入口点。在轮询期间随时按 Ctrl-C 可取消登录；取消或失败时退出码为 `1`，成功为 `0`。
+
 ### `kimi export`

 把一个会话打包成 ZIP 文件，便于分享、归档或者提交问题反馈。导出的压缩包包含会话目录下的所有文件，例如上下文记录、状态文件和会话诊断日志（如果该会话已经产生 `logs/kimi-code.log`）。