@harmonyos-arkts/opencode-acp 0.0.1 → 0.0.3

package/docs/codebase-overview.md

@@ -0,0 +1,191 @@
+# Harmony-ACP 代码详解
+
+## 各文件详细介绍
+
+### `src/index.ts` — 入口 (114 行)
+
+程序入口，负责三件事：
+
+1. **CLI 参数解析** (`parseArgs`)：支持 `--server`、`--cwd`、`--log`、`--help`
+2. **服务器连接**：通过 `@opencode-ai/sdk` 创建客户端，调用 `health()` 验证 OpenCode 服务可达
+3. **ACP 连接建立**：将 stdin/stdout 包装为 `ReadableStream`/`WritableStream`，通过 `ndJsonStream` 创建 NDJSON 双向流，然后实例化 `AgentSideConnection` 启动 ACP 协议
+
+---
+
+### `src/agent.ts` — ACP Agent (934 行，最大文件)
+
+实现 ACP 协议的 `Agent` 接口，是整个代理的核心业务逻辑。主要职责：
+
+#### 协议生命周期
+
+- `initialize()` — 声明能力（loadSession、MCP、fork、resume 等）
+- `authenticate()` — 占位，未实现
+
+#### 会话管理
+
+- `newSession()` — 在 OpenCode 创建会话，加载模型和模式
+- `loadSession()` — 加载已有会话，**回放历史消息**给客户端
+- `listSessions()` — 分页列出会话
+- `unstable_forkSession()` / `unstable_resumeSession()` — 分叉和恢复会话
+
+#### 提示执行
+
+- `prompt()` — 将客户端 prompt 转换为 OpenCode SDK 调用，支持普通 prompt 和 `/command` 格式
+- `cancel()` — 中止正在进行的会话
+
+#### 配置
+
+- `setSessionMode()` / `unstable_setSessionModel()` / `setSessionConfigOption()` — 运行时切换模型和模式
+
+#### 内部辅助方法
+
+| 方法                   | 职责                                                                              |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| `defaultModel()`       | 多级模型发现：配置 → opencode config → providers → fallback `opencode/big-pickle` |
+| `loadSessionMode()`    | 加载可用模型列表，注册 MCP 服务器，推送 `available_commands_update`               |
+| `processMessage()`     | 消息回放（文本、工具调用、文件、推理等）                                          |
+| `replayToolPart()`     | 工具调用回放（completed/error 状态）                                              |
+| `convertPromptParts()` | ACP prompt 格式 → OpenCode parts 格式                                             |
+| `parseUri()`           | 解析 `file://` 和 `zed://` URI                                                    |
+| `logMessageContent()`  | prompt 完成后抓取完整消息内容记录日志                                             |
+| `buildUsage()`         | 从 `AssistantMessage.tokens` 构建 ACP Usage 对象                                  |
+
+---
+
+### `src/session-manager.ts` — 会话管理器 (182 行)
+
+增强版会话跟踪，核心区别在于**自动发现子会话**。
+
+#### 数据结构
+
+- `sessions: Map<string, SessionState>` — 所有会话（含子会话）
+- `children: Map<string, Set<string>>` — 父→子的索引
+
+#### 关键方法
+
+| 方法                    | 职责                                                                         |
+| ----------------------- | ---------------------------------------------------------------------------- |
+| `create()` / `load()`   | 注册顶层会话（由 agent 调用）                                                |
+| `registerDiscovered()`  | **核心增强**：通过 SSE 事件自动注册子会话，继承父会话的 cwd/mcpServers/model |
+| `findRootSession()`     | 向上遍历 parentID 链找到根会话                                               |
+| `getRelatedSessions()`  | 递归获取子树所有会话                                                         |
+| `getChildren()`         | 获取直接子会话 ID 列表                                                       |
+| `getModel/setModel`     | 会话模型状态管理                                                             |
+| `getVariant/setVariant` | 会话变体管理                                                                 |
+| `getMode/setMode`       | 会话模式管理                                                                 |
+
+---
+
+### `src/event-handler.ts` — SSE 事件处理 (618 行)
+
+订阅 OpenCode SSE 事件流，路由到 ACP 客户端。实现"独立虚拟会话"策略。
+
+#### 核心状态
+
+| 字段               | 用途                                          |
+| ------------------ | --------------------------------------------- |
+| `messageBuffers`   | 累积 text/thought chunk，边界时刷新为完整日志 |
+| `bashSnapshots`    | bash 输出去重（用简单哈希避免重复推送）       |
+| `toolStarts`       | 跟踪已发送 `tool_call` 开始事件的 callID      |
+| `permissionQueues` | 按 sessionID 串行化权限请求                   |
+| `questionQueues`   | 按 sessionID 串行化问题请求                   |
+
+#### 事件处理
+
+| 事件类型                              | 处理逻辑                                                                                         |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `session.created` / `session.updated` | 自动发现子会话，通过 `announceChildSession()` 向客户端广播虚拟会话（带 `_meta.parentSessionId`） |
+| `permission.asked`                    | 转发给 ACP 客户端请求权限，支持 edit 的 diff 应用（用 `diff` 库的 `applyPatch`）                 |
+| `question.asked`                      | 通过 `extMethod("questionAsked")` 转发给客户端，60 秒超时                                        |
+| `message.part.delta`                  | 实时推送 `agent_message_chunk` / `agent_thought_chunk`，同时累积到 buffer                        |
+| `message.part.updated`                | 处理工具调用状态转换：pending → running → completed/error                                        |
+
+#### 消息缓冲机制
+
+- `accumulateDelta()` — 累积 delta 到 buffer
+- `flushMessageBuffer()` — 在边界事件（tool_call、新消息、stop）时刷新为 `agent_message_complete` 日志
+- `flushAllBuffers()` — 停止时刷新所有剩余 buffer
+
+#### 辅助
+
+- `sendToClient()` — `connection.sessionUpdate()` 的包装，在发送前记录日志并刷新 buffer
+- `resolveSession()` — 根据 sessionId 查找已注册会话或其祖先
+- `bashOutput()` — 从工具 metadata 中提取 bash 输出
+- `simpleHash()` — 简单字符串哈希，用于 bash 输出去重
+
+---
+
+### `src/logger.ts` — 结构化日志 (139 行)
+
+JSONL 格式日志系统，写入 `~/.harmony-acp/logs/`，每次启动一个文件。
+
+#### 5 个分类 API
+
+| 函数        | 分类       | 用途                                           |
+| ----------- | ---------- | ---------------------------------------------- |
+| `acpIn()`   | `acp.in`   | 客户端请求（editor → harmony-acp）             |
+| `acpOut()`  | `acp.out`  | 返回客户端的响应（harmony-acp → editor）       |
+| `ocCall()`  | `oc.call`  | 调用 OpenCode 的请求（harmony-acp → opencode） |
+| `ocEvent()` | `oc.event` | OpenCode 的事件（opencode → harmony-acp）      |
+| `sysLog()`  | `system`   | 生命周期事件                                   |
+
+#### 特性
+
+- `initLogger()` — 创建日志文件，自动清理超过 30 个的旧日志
+- `setLogEnabled()` — 默认关闭，需 `--log` 启用
+- `sanitize()` — 常规日志截断到 2K 字符
+- `acpAssembled()` / `sanitizeAssembled()` — 组装消息保留到 10K 字符
+
+---
+
+### `src/types.ts` — 类型定义 (53 行)
+
+定义核心接口：
+
+| 接口           | 用途                                              |
+| -------------- | ------------------------------------------------- |
+| `SessionState` | 增强会话状态（含 parentID、title、model、modeId） |
+| `ACPConfig`    | 服务器配置（sdk、serverUrl、cwd、defaultModel）   |
+| `ModeOption`   | 会话模式选项                                      |
+| `ModelOption`  | 模型选项                                          |
+
+---
+
+### `src/utils.ts` — 工具函数 (53 行)
+
+两个纯函数：
+
+| 函数            | 用途                                                                                      |
+| --------------- | ----------------------------------------------------------------------------------------- |
+| `toToolKind()`  | OpenCode 工具名 → ACP ToolKind 映射（bash→execute, edit/write→edit, grep/glob→search 等） |
+| `toLocations()` | 从工具输入元数据中提取文件路径位置信息                                                    |
+
+---
+
+## 数据流总览
+
+```
+编辑器                    Harmony-ACP                          OpenCode Server
+  │                          │                                      │
+  │── JSON-RPC (stdio) ────→ │                                      │
+  │   initialize/newSession  │ ── HTTP POST (session.create) ────→ │
+  │                          │ ←── JSON response ───────────────── │
+  │                          │                                      │
+  │   prompt                 │ ── HTTP POST (session.prompt) ────→ │
+  │                          │                                      │
+  │                          │ ←── SSE stream (events) ─────────── │
+  │                          │   message.part.delta                 │
+  │                          │   message.part.updated               │
+  │                          │   permission.asked                   │
+  │                          │   question.asked                     │
+  │                          │   session.created (子会话发现)        │
+  │                          │                                      │
+  │←── sessionUpdate ─────── │                                      │
+  │   agent_message_chunk    │                                      │
+  │   tool_call / update     │                                      │
+  │   session_info_update    │                                      │
+  │   usage_update           │                                      │
+  │                          │                                      │
+  │── requestPermission ──→ │ ── HTTP POST (permission.reply) ──→ │
+  │── extMethod(question) → │ ── HTTP POST (question.reply) ────→ │
+```

package/docs/mcp-extmethod-design.md

@@ -0,0 +1,366 @@
+# MCP API 暴露方案：通过 ACP extMethod
+
+## 背景
+
+当前 harmony-acp 在 session 创建时通过 `sdk.mcp.add()` 注册 MCP 服务器，但 ACP client 无法在运行时动态查看/管理 MCP 服务器。需要将 OpenCode 服务端的 MCP API 通过 ACP 协议的 extMethod 机制暴露给 ACP client，使其可以动态查看状态、添加/删除/连接/断开 MCP 服务器。
+
+## 方案：ACP extMethod
+
+利用 ACP 协议已有的 `extMethod` 机制（当前已用于 `questionAsked`），定义 MCP 相关的 extension method。ACP client 通过 JSON-RPC 调用，harmony-acp 代理到 OpenCode SDK。
+
+### 架构
+
+```
+ACP Client (Editor) ← stdio/JSON-RPC → Harmony-ACP ← HTTP/SSE → OpenCode Server
+       │                                    │                          │
+       │  extMethod("mcp/status")           │                          │
+       │──────────────────────────────────>│                          │
+       │                                    │  sdk.mcp.status()        │
+       │                                    │─────────────────────────>│
+       │                                    │  Record<string, Status>  │
+       │                                    │<─────────────────────────│
+       │  { status: {...} }                 │                          │
+       │<──────────────────────────────────│                          │
+```
+
+---
+
+## 暴露的 MCP 操作
+
+| extMethod 名 | 对应 SDK 调用 | 说明 |
+|---|---|---|
+| `mcp/status` | `sdk.mcp.status()` | 获取所有 MCP 服务器状态 |
+| `mcp/add` | `sdk.mcp.add()` | 添加 MCP 服务器 |
+| `mcp/connect` | `sdk.mcp.connect()` | 连接已禁用的服务器 |
+| `mcp/disconnect` | `sdk.mcp.disconnect()` | 断开服务器 |
+| `mcp/auth/start` | `sdk.mcp.auth.start()` | 启动 OAuth 认证 |
+| `mcp/auth/callback` | `sdk.mcp.auth.callback()` | 完成 OAuth 认证 |
+| `mcp/auth/remove` | `sdk.mcp.auth.remove()` | 删除 OAuth 凭据 |
+
+### 各操作详细签名
+
+#### `mcp/status`
+
+获取所有已配置 MCP 服务器的连接状态。
+
+**请求参数：**
+```typescript
+{
+  sessionId: string  // 用于获取 cwd
+}
+```
+
+**响应：**
+```typescript
+{
+  [serverName: string]: {
+    status: "connected" | "disabled" | "failed" | "needs_auth" | "needs_client_registration"
+    error?: string  // 仅 failed 和 needs_client_registration 状态
+  }
+}
+```
+
+#### `mcp/add`
+
+动态添加 MCP 服务器。
+
+**请求参数：**
+```typescript
+{
+  sessionId: string
+  name: string
+  config: {
+    // Local 类型
+    type: "local"
+    command: string[]
+    environment?: Record<string, string>
+    enabled?: boolean
+    timeout?: number
+  } | {
+    // Remote 类型
+    type: "remote"
+    url: string
+    headers?: Record<string, string>
+    enabled?: boolean
+    oauth?: { clientId?: string, clientSecret?: string, scope?: string, redirectUri?: string } | false
+    timeout?: number
+  }
+}
+```
+
+**响应：**
+```typescript
+{
+  [serverName: string]: McpStatus  // 添加后所有服务器状态
+}
+```
+
+#### `mcp/connect`
+
+连接一个已禁用/断开的 MCP 服务器。
+
+**请求参数：**
+```typescript
+{
+  sessionId: string
+  name: string
+}
+```
+
+**响应：**
+```typescript
+{
+  success: true
+}
+```
+
+#### `mcp/disconnect`
+
+断开一个 MCP 服务器。
+
+**请求参数：**
+```typescript
+{
+  sessionId: string
+  name: string
+}
+```
+
+**响应：**
+```typescript
+{
+  success: true
+}
+```
+
+#### `mcp/auth/start`
+
+启动 OAuth 认证流程，返回授权 URL。
+
+**请求参数：**
+```typescript
+{
+  sessionId: string
+  name: string
+}
+```
+
+**响应：**
+```typescript
+{
+  authorizationUrl: string
+  oauthState: string
+}
+```
+
+**错误：** 如果服务器不支持 OAuth，返回错误。
+
+#### `mcp/auth/callback`
+
+用授权码完成 OAuth 认证。
+
+**请求参数：**
+```typescript
+{
+  sessionId: string
+  name: string
+  code: string  // OAuth 授权码
+}
+```
+
+**响应：**
+```typescript
+McpStatus  // 认证后的服务器状态
+```
+
+#### `mcp/auth/remove`
+
+删除 MCP 服务器的 OAuth 凭据。
+
+**请求参数：**
+```typescript
+{
+  sessionId: string
+  name: string
+}
+```
+
+**响应：**
+```typescript
+{
+  success: true
+}
+```
+
+---
+
+## 实现步骤
+
+### Step 1: 新建 `src/mcp-manager.ts` — MCP 操作封装
+
+创建 MCP 管理模块，封装所有 MCP 相关的 SDK 调用，统一处理错误和日志。
+
+```typescript
+// src/mcp-manager.ts
+import type { OpencodeClient } from "@opencode-ai/sdk/v2"
+import { ocCall } from "./logger.js"
+
+export class McpManager {
+  constructor(private sdk: OpencodeClient) {}
+
+  async status(directory: string) {
+    ocCall("mcp.status", { directory })
+    const result = await this.sdk.mcp.status({ directory })
+    return result.data ?? {}
+  }
+
+  async add(directory: string, name: string, config: any) {
+    ocCall("mcp.add", { directory, name })
+    const result = await this.sdk.mcp.add({ directory, name, config })
+    return result.data ?? {}
+  }
+
+  async connect(directory: string, name: string) {
+    ocCall("mcp.connect", { directory, name })
+    await this.sdk.mcp.connect({ directory, name })
+    return { success: true }
+  }
+
+  async disconnect(directory: string, name: string) {
+    ocCall("mcp.disconnect", { directory, name })
+    await this.sdk.mcp.disconnect({ directory, name })
+    return { success: true }
+  }
+
+  async startAuth(directory: string, name: string) {
+    ocCall("mcp.auth.start", { directory, name })
+    const result = await this.sdk.mcp.auth.start({ directory, name })
+    return result.data
+  }
+
+  async callbackAuth(directory: string, name: string, code: string) {
+    ocCall("mcp.auth.callback", { directory, name })
+    const result = await this.sdk.mcp.auth.callback({ directory, name, code })
+    return result.data
+  }
+
+  async removeAuth(directory: string, name: string) {
+    ocCall("mcp.auth.remove", { directory, name })
+    await this.sdk.mcp.auth.remove({ directory, name })
+    return { success: true }
+  }
+}
+```
+
+### Step 2: 修改 `src/agent.ts` — 注册 extMethod 处理器
+
+在 Agent 类中添加 `extMethod` 方法（ACP SDK 的 Agent 接口支持可选的 `extMethod?` 回调），路由 MCP 方法到 `McpManager`。
+
+```typescript
+// agent.ts 中添加
+
+import { McpManager } from "./mcp-manager.js"
+
+export class Agent implements ACPAgent {
+  private mcpManager: McpManager
+
+  constructor(config: ACPConfig) {
+    // ...
+    this.mcpManager = new McpManager(config.sdk)
+  }
+
+  async extMethod(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>> {
+    if (method.startsWith("mcp/")) {
+      return this.handleMcpMethod(method, params)
+    }
+    throw new Error(`Unknown extMethod: ${method}`)
+  }
+
+  private async handleMcpMethod(method: string, params: Record<string, unknown>) {
+    const sessionId = params.sessionId as string
+    const session = this.sessionManager.get(sessionId)
+    const directory = session.cwd
+
+    switch (method) {
+      case "mcp/status":
+        return this.mcpManager.status(directory) as Promise<Record<string, unknown>>
+      case "mcp/add":
+        return this.mcpManager.add(directory, params.name as string, params.config) as Promise<Record<string, unknown>>
+      case "mcp/connect":
+        return this.mcpManager.connect(directory, params.name as string)
+      case "mcp/disconnect":
+        return this.mcpManager.disconnect(directory, params.name as string)
+      case "mcp/auth/start":
+        return this.mcpManager.startAuth(directory, params.name as string) as Promise<Record<string, unknown>>
+      case "mcp/auth/callback":
+        return this.mcpManager.callbackAuth(directory, params.name as string, params.code as string) as Promise<Record<string, unknown>>
+      case "mcp/auth/remove":
+        return this.mcpManager.removeAuth(directory, params.name as string)
+      default:
+        throw new Error(`Unknown MCP method: ${method}`)
+    }
+  }
+}
+```
+
+### Step 3: 迁移现有 MCP 注册逻辑
+
+将 `agent.ts:loadSessionMode()` 中 727-757 行的 MCP 注册代码使用 `McpManager.add()` 替代，消除重复代码。
+
+### Step 4: 更新 `src/__tests__/helpers/mock-sdk.ts`
+
+在 mock SDK 中补全 MCP 相关方法：
+
+```typescript
+mcp: {
+  add: vi.fn().mockResolvedValue({}),
+  status: vi.fn().mockResolvedValue({ data: {} }),
+  connect: vi.fn().mockResolvedValue({ data: true }),
+  disconnect: vi.fn().mockResolvedValue({ data: true }),
+  auth: {
+    start: vi.fn().mockResolvedValue({ data: { authorizationUrl: "", oauthState: "" } }),
+    callback: vi.fn().mockResolvedValue({ data: { status: "connected" } }),
+    remove: vi.fn().mockResolvedValue({ data: { success: true } }),
+  },
+},
+```
+
+### Step 5: 新建 `src/__tests__/mcp-manager.test.ts`
+
+为 `McpManager` 编写单元测试，覆盖所有 MCP 操作。
+
+### Step 6: 更新 `src/__tests__/agent.test.ts`
+
+添加 extMethod MCP 路由的测试用例，验证方法分发和参数传递。
+
+### Step 7: 更新文档
+
+- 更新 `README.md` 说明 MCP extMethod 接口
+- 更新 `CHANGELOG.md`
+
+---
+
+## 关键文件清单
+
+| 文件 | 操作 | 说明 |
+|---|---|---|
+| `src/mcp-manager.ts` | **新建** | MCP 操作封装，代理 SDK 调用 |
+| `src/agent.ts` | **修改** | 添加 extMethod 路由、集成 McpManager、迁移 MCP 注册逻辑 |
+| `src/types.ts` | **修改** | 添加 MCP 相关类型（可选） |
+| `src/__tests__/mcp-manager.test.ts` | **新建** | McpManager 单元测试 |
+| `src/__tests__/agent.test.ts` | **修改** | 添加 extMethod 测试 |
+| `src/__tests__/helpers/mock-sdk.ts` | **修改** | 补全 MCP mock 方法 |
+| `README.md` | **修改** | 文档更新 |
+| `CHANGELOG.md` | **修改** | 记录变更 |
+
+## 复用
+
+- `@opencode-ai/sdk` 的 `Mcp` 类（`sdk.mcp.*`）：所有 MCP 操作直接代理
+- ACP SDK 的 `extMethod` 机制：已有协议支持，无需修改
+- `SessionManager`：复用 `get()` 获取 session 的 `cwd` 用于 SDK 调用
+- 现有日志工具：`ocCall` 记录 OpenCode 调用
+
+## 验证方式
+
+1. `cd /Users/liwenwei/Documents/Code/harmony-acp && pnpm test` — 所有测试通过
+2. 手动测试：启动 opencode server → 启动 harmony-acp → 通过 ACP client 发送 extMethod 调用验证 MCP 操作