@pencil-agent/nano-pencil 2.0.0 → 2.0.1

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

@@ -1,851 +0,0 @@
-# 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