@pencil-agent/nano-pencil 2.0.1 → 2.0.2

package/docs/ACP/345/215/217/350/256/256/351/233/206/346/210/220/345/274/200/345/217/221/346/226/207/346/241/243.md

@@ -0,0 +1,851 @@
+# nanoPencil ACP 协议集成开发文档
+
+> **状态**：待开发
+>
+> **目标版本**：1.12.0
+>
+> **ACP 版本**：0.16.x（@agentclientprotocol/sdk）
+>
+> **相关文档**：
+> - ACP 官方：https://agentclientprotocol.com
+> - TypeScript SDK：https://agentclientprotocol.github.io/typescript-sdk
+> - 参考实现：[Gemini CLI ACP Agent](https://github.com/google-gemini/gemini-cli)
+
+---
+
+## 目录
+
+- [一、背景与动机](#一背景与动机)
+- [二、ACP 协议概述](#二acp-协议概述)
+- [三、现有架构分析](#三现有架构分析)
+- [四、改动方案](#四改动方案)
+- [五、详细设计](#五详细设计)
+- [六、事件映射表](#六事件映射表)
+- [七、文件变更总览](#七文件变更总览)
+- [八、实施步骤](#八实施步骤)
+- [九、验收标准](#九验收标准)
+- [十、附录](#十附录)
+
+---
+
+## 一、背景与动机
+
+### 1.1 什么是 ACP
+
+ACP（Agent Client Protocol）是由 Zed 发起的开放标准，定义了代码编辑器（Client）与 AI 编码代理（Agent）之间的通信协议。基于 JSON-RPC 2.0，通过 stdin/stdout 进行双向通信。
+
+### 1.2 为什么 nanoPencil 需要支持 ACP
+
+| 维度 | 当前状态 | 支持 ACP 后 |
+|------|---------|------------|
+| 编辑器集成 | 仅自有 RPC 协议，Pencil Desktop 专用 | 兼容 Zed、JetBrains 等所有 ACP Client |
+| 外部调用 | 需要了解自定义 RPC 协议 | 标准协议，零学习成本 |
+| 生态兼容 | 独立生态 | 与 Claude Code、Gemini CLI、Copilot 等互通 |
+| 维护成本 | 自维护私有协议 | 社区维护开放标准 |
+
+### 1.3 设计原则
+
+1. **增量集成** — ACP 作为新的运行模式，不影响现有 Interactive / Print / RPC 三种模式
+2. **复用核心** — 复用 `AgentSession` 和 `createAgentSession` SDK，仅在 I/O 层适配
+3. **最小改动** — 核心改动集中在新增 `modes/acp/` 目录，对现有代码改动控制在 30 行以内
+
+---
+
+## 二、ACP 协议概述
+
+### 2.1 通信模型
+
+```
+┌─────────────────┐        JSON-RPC 2.0         ┌─────────────────┐
+│  Client (编辑器) │ ◄──── stdin/stdout ────────► │  Agent (CLI)    │
+│  Zed / JetBrains │                              │  nanoPencil     │
+└─────────────────┘                              └─────────────────┘
+```
+
+- **Client → Agent**（方法调用）：`initialize`、`session/new`、`session/prompt`、`session/cancel`
+- **Agent → Client**（通知）：`session/update`（流式文本、工具调用、思考过程等）
+- **Agent → Client**（方法调用）：`session/request_permission`（请求工具执行授权）
+
+### 2.2 一次完整的 Prompt Turn
+
+```
+Client                                          Agent (nanoPencil)
+  │                                               │
+  │──── session/prompt (用户消息) ──────────────►│
+  │                                               │── 调用 LLM
+  │◄─── session/update (thinking) ────────────── │
+  │◄─── session/update (agent_message_chunk) ──── │
+  │◄─── session/update (tool_call, pending) ───── │
+  │                                               │
+  │◄─── session/request_permission ────────────── │  (可选)
+  │──── permission response ──────────────────►  │
+  │                                               │── 执行工具
+  │◄─── session/update (tool_call_update) ──────  │
+  │                                               │── 将结果送回 LLM
+  │◄─── session/update (agent_message_chunk) ──── │
+  │                                               │
+  │◄─── session/prompt response (end_turn) ────── │
+```
+
+### 2.3 关键消息格式
+
+**initialize 响应**：
+```json
+{
+  "protocolVersion": "2025-03-26",
+  "agentCapabilities": {
+    "loadSession": false
+  }
+}
+```
+
+**session/update 通知（文本块）**：
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc",
+    "update": {
+      "sessionUpdate": "agent_message_chunk",
+      "content": { "type": "text", "text": "好的，" }
+    }
+  }
+}
+```
+
+**session/update 通知（工具调用）**：
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc",
+    "update": {
+      "sessionUpdate": "tool_call",
+      "toolCallId": "call_001",
+      "title": "Reading file",
+      "kind": "read",
+      "status": "pending",
+      "locations": [{ "path": "/project/src/main.ts" }]
+    }
+  }
+}
+```
+
+**session/prompt 响应**：
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": { "stopReason": "end_turn" }
+}
+```
+
+---
+
+## 三、现有架构分析
+
+### 3.1 nanoPencil 运行模式架构
+
+```
+cli.ts → main.ts → parseArgs()
+                  → createAgentSession()
+                  → 模式选择:
+                      ├── Interactive (TUI)
+                      ├── Print (stdout 输出)
+                      ├── RPC (自定义 JSON Lines)
+                      └── ACP (新增 ✦)
+```
+
+所有模式共享同一个 `AgentSession` 核心，区别仅在 I/O 层。
+
+### 3.2 核心接口
+
+**AgentSession** 提供：
+- `session.prompt(message, options)` — 发送用户消息并触发 Agent 循环
+- `session.subscribe(listener)` — 订阅 `AgentSessionEvent` 事件流
+- `session.abort()` — 中止当前 turn
+- `session.bindExtensions(options)` — 绑定扩展 UI 上下文
+- `session.steer(message)` / `session.followUp(message)` — 流式中追加消息
+
+**AgentSessionEvent** 事件类型：
+```typescript
+type AgentSessionEvent =
+  | AgentEvent           // agent-core 事件
+  | { type: "auto_compaction_start"; ... }
+  | { type: "auto_compaction_end"; ... }
+  | { type: "auto_retry_start"; ... }
+  | { type: "auto_retry_end"; ... };
+```
+
+**AgentEvent** 事件类型：
+```typescript
+type AgentEvent =
+  | { type: "agent_start" }
+  | { type: "agent_end"; messages: AgentMessage[] }
+  | { type: "turn_start" }
+  | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] }
+  | { type: "message_start"; message: AgentMessage }
+  | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent }
+  | { type: "message_end"; message: AgentMessage }
+  | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any }
+  | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any }
+  | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean };
+```
+
+**AssistantMessageEvent** 事件类型（在 message_update 中传递）：
+```typescript
+type AssistantMessageEvent =
+  | { type: "text_start"; ... }
+  | { type: "text_delta"; delta: string; ... }
+  | { type: "text_end"; ... }
+  | { type: "thinking_start"; ... }
+  | { type: "thinking_delta"; delta: string; ... }
+  | { type: "thinking_end"; ... }
+  | { type: "toolcall_start"; ... }
+  | { type: "toolcall_delta"; delta: string; ... }
+  | { type: "toolcall_end"; toolCall: ToolCall; ... }
+  | { type: "done"; reason: "stop" | "length" | "toolUse"; ... }
+  | { type: "error"; ... };
+```
+
+### 3.3 RPC 模式参考
+
+现有 RPC 模式 (`modes/rpc/rpc-mode.ts`) 是 ACP 模式的最佳参考：
+
+- **相同点**：stdin/stdout 双向通信、无头模式、事件流转发
+- **不同点**：RPC 用自定义 JSON Lines；ACP 用标准 JSON-RPC 2.0 + SDK
+
+RPC 模式核心流程：
+1. `session.bindExtensions()` 绑定扩展（非 TUI 环境）
+2. `session.subscribe(event => output(event))` 转发事件
+3. `readline` 逐行读取 stdin → `handleCommand()` 处理命令
+4. 返回 `new Promise(() => {})` 保持进程存活
+
+ACP 模式将遵循相同模式，但使用 `AgentSideConnection` + `ndJsonStream` 替代手动 readline。
+
+---
+
+## 四、改动方案
+
+### 4.1 改动文件清单
+
+| 文件 | 操作 | 改动量 | 说明 |
+|------|------|--------|------|
+| `package.json` | 修改 | +1 行 | 新增 `@agentclientprotocol/sdk` 依赖 |
+| `cli/args.ts` | 修改 | +5 行 | 新增 `--acp` 参数 |
+| `main.ts` | 修改 | +10 行 | ACP 模式分支 + stdin 跳过 |
+| `modes/acp/acp-mode.ts` | **新增** | ~300 行 | ACP Agent 模式核心 |
+| `modes/index.ts` | 修改 | +1 行 | 导出 `runAcpMode` |
+
+**总计：~320 行新增，~15 行改动**
+
+### 4.2 不变的文件
+
+以下文件**完全不需要修改**：
+
+```
+core/runtime/agent-session.ts     ✓ 核心逻辑不变
+core/runtime/sdk.ts               ✓ SDK 接口不变
+packages/agent-core/              ✓ agent-core 不变
+packages/ai/                      ✓ AI 层不变
+modes/interactive/                ✓ 交互模式不变
+modes/print-mode.ts               ✓ Print 模式不变
+modes/rpc/                        ✓ RPC 模式不变
+core/extensions/                  ✓ 扩展系统不变
+core/tools/                       ✓ 工具系统不变
+```
+
+---
+
+## 五、详细设计
+
+### 5.1 依赖变更 — `package.json`
+
+在 `dependencies` 中新增：
+
+```json
+{
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.16.1"
+  }
+}
+```
+
+### 5.2 CLI 参数 — `cli/args.ts`
+
+在 `Args` 接口中新增字段：
+
+```typescript
+export interface Args {
+  // ...existing fields...
+  /** Enable ACP (Agent Client Protocol) mode for editor integration */
+  acp?: boolean;
+}
+```
+
+在 `parseArgs` 函数中添加解析：
+
+```typescript
+} else if (arg === "--acp") {
+  result.acp = true;
+```
+
+在 `printHelp` 中添加说明：
+
+```
+  --acp                          Run as ACP Agent (for editor integration)
+```
+
+### 5.3 模式选择 — `main.ts`
+
+#### 5.3.1 跳过 stdin 管道读取
+
+```typescript
+// 现有代码 (约第 707 行):
+if (parsed.mode !== "rpc") {
+
+// 改为:
+if (parsed.mode !== "rpc" && !parsed.acp) {
+```
+
+#### 5.3.2 添加 ACP 模式分支
+
+```typescript
+// 现有代码 (约第 825 行):
+if (mode === "rpc") {
+  await runRpcMode(session);
+} else if (isInteractive) {
+
+// 改为:
+if (parsed.acp) {
+  const { runAcpMode } = await import("./modes/acp/acp-mode.js");
+  await runAcpMode(session);
+} else if (mode === "rpc") {
+  await runRpcMode(session);
+} else if (isInteractive) {
+```
+
+使用动态 `import()` 确保不使用 ACP 模式时不加载 SDK，减少启动时间。
+
+### 5.4 ACP Agent 模式 — `modes/acp/acp-mode.ts`
+
+这是核心新增文件。实现 ACP `Agent` 接口，将 `AgentSession` 的事件流映射为 ACP 协议消息。
+
+#### 5.4.1 整体结构
+
+```typescript
+import * as acp from "@agentclientprotocol/sdk";
+import { Readable, Writable } from "node:stream";
+import type { AgentSession } from "../../core/runtime/agent-session.js";
+import { VERSION } from "../../config.js";
+
+/**
+ * NanoPencilAgent - 实现 ACP Agent 接口
+ *
+ * 将 nanoPencil 的 AgentSession 包装为 ACP Agent，
+ * 通过 stdin/stdout 与 ACP Client 通信。
+ */
+class NanoPencilAgent implements acp.Agent {
+  private connection: acp.AgentSideConnection;
+  private session: AgentSession;
+  private activeSessions: Map<string, { abortController: AbortController | null }>;
+
+  constructor(connection: acp.AgentSideConnection, session: AgentSession) { ... }
+
+  async initialize(params: acp.InitializeRequest): Promise<acp.InitializeResult> { ... }
+  async newSession(params: acp.NewSessionRequest): Promise<acp.NewSessionResult> { ... }
+  async authenticate(params: acp.AuthenticateRequest): Promise<acp.AuthenticateResult> { ... }
+  async prompt(params: acp.PromptRequest): Promise<acp.PromptResult> { ... }
+  async cancel(params: acp.CancelNotification): Promise<void> { ... }
+  async setSessionMode(params: acp.SetSessionModeRequest): Promise<acp.SetSessionModeResult> { ... }
+}
+
+export async function runAcpMode(session: AgentSession): Promise<never> { ... }
+```
+
+#### 5.4.2 `initialize` — 协商版本和能力
+
+```typescript
+async initialize(params: acp.InitializeRequest): Promise<acp.InitializeResult> {
+  return {
+    protocolVersion: acp.PROTOCOL_VERSION,
+    agentCapabilities: {
+      loadSession: false,     // 暂不支持 loadSession
+    },
+  };
+}
+```
+
+#### 5.4.3 `newSession` — 创建会话
+
+```typescript
+async newSession(params: acp.NewSessionRequest): Promise<acp.NewSessionResult> {
+  const sessionId = `sess-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  this.activeSessions.set(sessionId, { abortController: null });
+  return { sessionId };
+}
+```
+
+#### 5.4.4 `prompt` — 核心交互
+
+这是最复杂的方法，负责：
+1. 从 ACP prompt 内容中提取文本
+2. 订阅 `AgentSessionEvent` 并转换为 ACP `session/update`
+3. 调用 `session.prompt()` 阻塞直到 turn 结束
+4. 返回 `stopReason`
+
+```typescript
+async prompt(params: acp.PromptRequest): Promise<acp.PromptResult> {
+  const { sessionId, prompt } = params;
+  const sessionState = this.activeSessions.get(sessionId);
+  if (!sessionState) throw new Error(`Session ${sessionId} not found`);
+
+  // 中止之前的 prompt（如果有）
+  sessionState.abortController?.abort();
+  sessionState.abortController = new AbortController();
+
+  // 提取文本
+  const userText = prompt
+    .filter((block): block is acp.TextContent => block.type === "text")
+    .map((block) => block.text)
+    .join("\n");
+
+  // 订阅事件并转发为 ACP session/update
+  const unsubscribe = this.session.subscribe((event) => {
+    this.mapEventToAcp(sessionId, event);
+  });
+
+  try {
+    await this.session.prompt(userText, { source: "acp" });
+    return { stopReason: "end_turn" };
+  } catch (error) {
+    if (sessionState.abortController.signal.aborted) {
+      return { stopReason: "cancelled" };
+    }
+    return { stopReason: "error" };
+  } finally {
+    unsubscribe();
+    sessionState.abortController = null;
+  }
+}
+```
+
+#### 5.4.5 `cancel` — 中止当前 turn
+
+```typescript
+async cancel(params: acp.CancelNotification): Promise<void> {
+  const sessionState = this.activeSessions.get(params.sessionId);
+  if (sessionState) {
+    sessionState.abortController?.abort();
+    await this.session.abort();
+  }
+}
+```
+
+#### 5.4.6 事件映射方法
+
+```typescript
+private mapEventToAcp(sessionId: string, event: AgentSessionEvent): void {
+  switch (event.type) {
+    case "message_update": {
+      const sub = event.assistantMessageEvent;
+      switch (sub.type) {
+        case "text_delta":
+          this.connection.sessionUpdate({
+            sessionId,
+            update: {
+              sessionUpdate: "agent_message_chunk",
+              content: { type: "text", text: sub.delta },
+            },
+          });
+          break;
+
+        case "thinking_delta":
+          this.connection.sessionUpdate({
+            sessionId,
+            update: {
+              sessionUpdate: "agent_message_chunk",
+              content: { type: "thought", text: sub.delta },
+            },
+          });
+          break;
+
+        // toolcall_start, toolcall_end 等在 tool_execution_* 事件中处理
+      }
+      break;
+    }
+
+    case "tool_execution_start":
+      this.connection.sessionUpdate({
+        sessionId,
+        update: {
+          sessionUpdate: "tool_call",
+          toolCallId: event.toolCallId,
+          title: `${event.toolName}`,
+          kind: this.mapToolKind(event.toolName),
+          status: "pending",
+          rawInput: event.args,
+        },
+      });
+      break;
+
+    case "tool_execution_end":
+      this.connection.sessionUpdate({
+        sessionId,
+        update: {
+          sessionUpdate: "tool_call_update",
+          toolCallId: event.toolCallId,
+          status: event.isError ? "errored" : "completed",
+          content: [{
+            type: "content",
+            content: {
+              type: "text",
+              text: typeof event.result === "string"
+                ? event.result
+                : JSON.stringify(event.result, null, 2),
+            },
+          }],
+          rawOutput: event.result,
+        },
+      });
+      break;
+
+    // agent_start, agent_end, turn_start, turn_end 等不需要映射
+  }
+}
+```
+
+#### 5.4.7 工具类型映射
+
+ACP 定义了标准化的工具 `kind`：
+
+```typescript
+private mapToolKind(toolName: string): string {
+  switch (toolName) {
+    case "read":   return "read";
+    case "edit":   return "edit";
+    case "write":  return "write";
+    case "bash":   return "command";
+    case "grep":   return "read";
+    case "find":   return "read";
+    case "ls":     return "read";
+    default:       return "other";
+  }
+}
+```
+
+#### 5.4.8 扩展 UI Context
+
+ACP 模式需要一个无头环境的扩展 UI Context，与 RPC 模式类似。可以从 `modes/rpc/rpc-mode.ts` 第 120-274 行的 `createExtensionUIContext()` 复制并简化：
+
+```typescript
+function createAcpExtensionUIContext(): ExtensionUIContext {
+  return {
+    // 对话式交互 → 静默返回默认值
+    select: async () => undefined,
+    confirm: async () => false,
+    input: async () => undefined,
+    editor: async () => undefined,
+
+    // 通知/状态 → 输出到 stderr（不干扰 ACP 协议的 stdout）
+    notify(message, type) {
+      process.stderr.write(`[${type ?? "info"}] ${message}\n`);
+    },
+    setStatus() {},
+    setWorkingMessage() {},
+    setWidget() {},
+    setFooter() {},
+    setHeader() {},
+    setTitle() {},
+    setEditorComponent() {},
+    pasteToEditor() {},
+    setEditorText() {},
+    getEditorText: () => "",
+
+    async custom() { return undefined as never; },
+    onTerminalInput: () => () => {},
+    get theme() { return theme; },
+    getAllThemes: () => [],
+    getTheme: () => undefined,
+    setTheme: () => ({ success: false, error: "Theme not supported in ACP mode" }),
+    getToolsExpanded: () => false,
+    setToolsExpanded() {},
+  };
+}
+```
+
+#### 5.4.9 `runAcpMode` 入口函数
+
+```typescript
+export async function runAcpMode(session: AgentSession): Promise<never> {
+  // 绑定扩展
+  await session.bindExtensions({
+    uiContext: createAcpExtensionUIContext(),
+    commandContextActions: {
+      waitForIdle: () => session.agent.waitForIdle(),
+      newSession: async (options) => {
+        const success = await session.newSession(options);
+        return { cancelled: !success };
+      },
+      fork: async (entryId) => {
+        const result = await session.fork(entryId);
+        return { cancelled: result.cancelled };
+      },
+      navigateTree: async (targetId, options) => {
+        const result = await session.navigateTree(targetId, options);
+        return { cancelled: result.cancelled };
+      },
+      switchSession: async (sessionPath) => {
+        const success = await session.switchSession(sessionPath);
+        return { cancelled: !success };
+      },
+      reload: async () => { await session.reload(); },
+    },
+    shutdownHandler: () => { process.exit(0); },
+    onError: (err) => {
+      process.stderr.write(
+        `[extension_error] ${err.extensionPath}: ${err.error}\n`
+      );
+    },
+  });
+
+  // 建立 ACP 连接（stdin/stdout）
+  const input = Writable.toWeb(process.stdout);
+  const output = Readable.toWeb(process.stdin) as ReadableStream<Uint8Array>;
+  const stream = acp.ndJsonStream(input, output);
+
+  new acp.AgentSideConnection(
+    (conn) => new NanoPencilAgent(conn, session),
+    stream,
+  );
+
+  // 保持进程存活
+  return new Promise(() => {});
+}
+```
+
+### 5.5 导出 — `modes/index.ts`
+
+新增导出：
+
+```typescript
+export { runAcpMode } from "./acp/acp-mode.js";
+```
+
+---
+
+## 六、事件映射表
+
+### 6.1 AgentSessionEvent → ACP session/update 完整映射
+
+| nanoPencil 事件 | 子事件 | ACP sessionUpdate 类型 | 说明 |
+|-----------------|--------|----------------------|------|
+| `message_update` | `text_delta` | `agent_message_chunk` (text) | 流式文本增量 |
+| `message_update` | `text_start` | — | 不需要映射 |
+| `message_update` | `text_end` | — | 不需要映射 |
+| `message_update` | `thinking_delta` | `agent_message_chunk` (thought) | 思考过程增量 |
+| `message_update` | `thinking_start` | — | 不需要映射 |
+| `message_update` | `thinking_end` | — | 不需要映射 |
+| `message_update` | `toolcall_start` | — | 由 `tool_execution_start` 处理 |
+| `message_update` | `toolcall_delta` | — | 参数流式（可忽略） |
+| `message_update` | `toolcall_end` | — | 由 `tool_execution_start` 处理 |
+| `message_update` | `done` | — | 由 prompt 返回值处理 |
+| `message_update` | `error` | — | 由 prompt 异常处理 |
+| `tool_execution_start` | — | `tool_call` (pending) | 工具开始执行 |
+| `tool_execution_update` | — | `tool_call_update` (partial) | 工具中间输出（可选） |
+| `tool_execution_end` | — | `tool_call_update` (completed/errored) | 工具执行完成 |
+| `agent_start` | — | — | 不需要映射 |
+| `agent_end` | — | — | 由 prompt 返回值处理 |
+| `turn_start` | — | — | 不需要映射 |
+| `turn_end` | — | — | 由 prompt 返回值处理 |
+| `message_start` | — | — | 不需要映射 |
+| `message_end` | — | — | 不需要映射 |
+| `auto_compaction_start` | — | — | 可通过 stderr 日志 |
+| `auto_compaction_end` | — | — | 可通过 stderr 日志 |
+| `auto_retry_start` | — | — | 可通过 stderr 日志 |
+| `auto_retry_end` | — | — | 可通过 stderr 日志 |
+
+### 6.2 工具名称 → ACP tool kind 映射
+
+| nanoPencil 工具名 | ACP kind | 说明 |
+|-------------------|----------|------|
+| `read` | `read` | 文件读取 |
+| `edit` | `edit` | 文件编辑 |
+| `write` | `write` | 文件写入 |
+| `bash` | `command` | 命令执行 |
+| `grep` | `read` | 内容搜索 |
+| `find` | `read` | 文件搜索 |
+| `ls` | `read` | 目录列表 |
+| `source` | `read` | 源码分析 |
+| MCP 工具 | `other` | MCP 扩展工具 |
+| 扩展注册工具 | `other` | 扩展自定义工具 |
+
+### 6.3 ACP stopReason 映射
+
+| nanoPencil 结果 | ACP stopReason | 条件 |
+|-----------------|---------------|------|
+| prompt 正常完成 | `end_turn` | `session.prompt()` resolve |
+| 用户取消 | `cancelled` | `session.abort()` 或 AbortController |
+| LLM 错误 | `error` | `session.prompt()` reject（非取消） |
+
+---
+
+## 七、文件变更总览
+
+### 7.1 新增文件
+
+```
+modes/acp/acp-mode.ts          # ACP Agent 模式核心（~300 行）
+```
+
+### 7.2 修改文件
+
+```
+package.json                    # +1 依赖
+cli/args.ts                     # +5 行（--acp 参数）
+main.ts                         # +10 行（ACP 分支 + stdin 跳过）
+modes/index.ts                  # +1 行（导出）
+```
+
+### 7.3 不变文件
+
+```
+core/runtime/agent-session.ts   ✓ 核心不变
+core/runtime/sdk.ts             ✓ SDK 不变
+modes/interactive/              ✓ 交互模式不变
+modes/print-mode.ts             ✓ Print 模式不变
+modes/rpc/                      ✓ RPC 模式不变
+packages/agent-core/            ✓ agent-core 不变
+packages/ai/                    ✓ AI 层不变
+core/extensions/                ✓ 扩展系统不变
+core/tools/                     ✓ 工具系统不变
+```
+
+---
+
+## 八、实施步骤
+
+### Step 1：安装依赖
+
+```bash
+npm install @agentclientprotocol/sdk
+```
+
+### Step 2：添加 --acp 参数
+
+修改 `cli/args.ts`：
+- `Args` 接口新增 `acp?: boolean`
+- `parseArgs` 中处理 `--acp`
+- `printHelp` 中添加说明
+
+### Step 3：创建 ACP 模式
+
+新增 `modes/acp/acp-mode.ts`：
+1. 实现 `NanoPencilAgent` 类（implements `acp.Agent`）
+2. 实现 `createAcpExtensionUIContext()` 
+3. 实现 `runAcpMode(session)` 入口函数
+4. 实现事件映射 `mapEventToAcp()`
+
+### Step 4：接入主流程
+
+修改 `main.ts`：
+- stdin 读取跳过 ACP 模式
+- 模式选择添加 ACP 分支
+
+修改 `modes/index.ts`：
+- 导出 `runAcpMode`
+
+### Step 5：构建与手动测试
+
+```bash
+# 构建
+npm run build
+
+# 测试 ACP 模式启动
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0"},"capabilities":{}}}' | node dist/cli.js --acp
+
+# 预期输出（stdout）：
+# {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","agentCapabilities":{"loadSession":false}}}
+```
+
+### Step 6：端到端测试
+
+使用 ACP Client 进行端到端验证：
+
+```bash
+# 方式 1：使用 Zed 编辑器
+# 在 Zed 的 Agent 设置中添加 nanoPencil：
+# Command: nanopencil --acp
+
+# 方式 2：使用 ACP SDK 自带的 ClientSideConnection 编写测试客户端
+```
+
+---
+
+## 九、验收标准
+
+| 编号 | 验收项 | 验证方法 |
+|------|--------|----------|
+| AC-1 | `nanopencil --acp` 启动后等待 stdin | 手动运行，进程不退出 |
+| AC-2 | 发送 `initialize` 收到正确响应 | echo JSON-RPC → stdin，检查 stdout |
+| AC-3 | 发送 `session/new` 返回 `sessionId` | echo JSON-RPC → stdin |
+| AC-4 | 发送 `session/prompt` 后收到流式 `session/update` | 观察 stdout 逐条 JSON-RPC 通知 |
+| AC-5 | 文本流式输出为 `agent_message_chunk` (text) | 检查 `sessionUpdate` 字段 |
+| AC-6 | 思考过程输出为 `agent_message_chunk` (thought) | 使用 thinking 模型测试 |
+| AC-7 | 工具调用输出 `tool_call` (pending) + `tool_call_update` (completed) | Agent 执行工具时观察 |
+| AC-8 | Turn 结束时 `session/prompt` 响应包含 `stopReason: "end_turn"` | 检查 JSON-RPC 响应 |
+| AC-9 | 发送 `session/cancel` 后 turn 中止 | 长 prompt 期间发送 cancel |
+| AC-10 | 现有 Interactive / Print / RPC 模式不受影响 | 分别运行三种模式验证 |
+| AC-11 | `npm run build` 编译通过 | CI 构建 |
+| AC-12 | 扩展系统在 ACP 模式下正常加载 | 观察 stderr 日志 |
+
+---
+
+## 十、附录
+
+### 附录 A：ACP 协议与 nanoPencil RPC 对比
+
+| 维度 | nanoPencil RPC | ACP |
+|------|---------------|-----|
+| 协议标准 | 自定义 JSON Lines | JSON-RPC 2.0 开放标准 |
+| SDK 支持 | 自实现 | `@agentclientprotocol/sdk` |
+| 请求格式 | `{ type, id?, ... }` | `{ jsonrpc: "2.0", method, params, id }` |
+| 响应格式 | `{ type: "response", command, success }` | `{ jsonrpc: "2.0", result/error, id }` |
+| 事件格式 | 原始 `AgentSessionEvent` | `session/update` 通知 |
+| Client 兼容 | Pencil Desktop 专用 | Zed、JetBrains 等通用 |
+| 功能丰富度 | 完整（模型切换、compaction 等） | 基础 prompt/cancel |
+| 扩展 UI | 通过 `extension_ui_request` | 不支持（需自定义扩展） |
+
+> RPC 模式保留用于 Pencil Desktop 深度集成，ACP 模式用于通用编辑器集成。两者共存。
+
+### 附录 B：已知 ACP 兼容编辑器
+
+| 编辑器 | ACP Client 支持 | 状态 |
+|--------|----------------|------|
+| Zed | 原生支持 | 已发布 |
+| JetBrains IDEs | 原生支持 | 已发布 |
+| VS Code | 通过扩展 | 社区支持 |
+| Cursor | 通过扩展 | 社区支持 |
+
+### 附录 C：已知 ACP Agent
+
+| Agent | 启动命令 | 说明 |
+|-------|---------|------|
+| Claude Code | `claude --acp` | Anthropic |
+| Gemini CLI | `gemini --acp` | Google |
+| GitHub Copilot | `github-copilot --acp` | GitHub |
+| Codex CLI | `codex --acp` | OpenAI |
+| Goose | `goose --acp` | Square |
+| **nanoPencil** | **`nanopencil --acp`** | **本项目** |
+
+### 附录 D：后续演进方向
+
+1. **loadSession 支持** — 实现 ACP `session/load`，复用 nanoPencil 的 SessionManager
+2. **权限请求** — 对 bash/edit/write 工具通过 `requestPermission` 请求用户授权
+3. **Plan 支持** — 将 plan-mode 扩展的计划步骤映射为 ACP plan update
+4. **Slash Commands** — 通过 ACP `available_commands_update` 广播可用命令
+5. **Session Modes** — 映射 nanoPencil 的 thinking level 为 ACP session mode
+6. **文件系统集成** — 实现 ACP 的 `fs/readTextFile` / `fs/writeTextFile`，使用 Client 的文件系统
+7. **终端集成** — 实现 ACP 的 `terminal/*` 方法，使用 Client 的终端执行 bash