@harmonyos-arkts/opencode-acp 0.0.2 → 0.0.3

package/docs/codebase-overview.md

@@ -39,16 +39,16 @@
 
 #### 内部辅助方法
 
-| 方法 | 职责 |
-|------|------|
-| `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 对象 |
+| 方法                   | 职责                                                                              |
+| ---------------------- | --------------------------------------------------------------------------------- |
+| `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 对象                                  |
 
 ---
 
@@ -63,16 +63,16 @@
 
 #### 关键方法
 
-| 方法 | 职责 |
-|------|------|
-| `create()` / `load()` | 注册顶层会话（由 agent 调用） |
-| `registerDiscovered()` | **核心增强**：通过 SSE 事件自动注册子会话，继承父会话的 cwd/mcpServers/model |
-| `findRootSession()` | 向上遍历 parentID 链找到根会话 |
-| `getRelatedSessions()` | 递归获取子树所有会话 |
-| `getChildren()` | 获取直接子会话 ID 列表 |
-| `getModel/setModel` | 会话模型状态管理 |
-| `getVariant/setVariant` | 会话变体管理 |
-| `getMode/setMode` | 会话模式管理 |
+| 方法                    | 职责                                                                         |
+| ----------------------- | ---------------------------------------------------------------------------- |
+| `create()` / `load()`   | 注册顶层会话（由 agent 调用）                                                |
+| `registerDiscovered()`  | **核心增强**：通过 SSE 事件自动注册子会话，继承父会话的 cwd/mcpServers/model |
+| `findRootSession()`     | 向上遍历 parentID 链找到根会话                                               |
+| `getRelatedSessions()`  | 递归获取子树所有会话                                                         |
+| `getChildren()`         | 获取直接子会话 ID 列表                                                       |
+| `getModel/setModel`     | 会话模型状态管理                                                             |
+| `getVariant/setVariant` | 会话变体管理                                                                 |
+| `getMode/setMode`       | 会话模式管理                                                                 |
 
 ---
 
@@ -82,23 +82,23 @@
 
 #### 核心状态
 
-| 字段 | 用途 |
-|------|------|
-| `messageBuffers` | 累积 text/thought chunk，边界时刷新为完整日志 |
-| `bashSnapshots` | bash 输出去重（用简单哈希避免重复推送） |
-| `toolStarts` | 跟踪已发送 `tool_call` 开始事件的 callID |
-| `permissionQueues` | 按 sessionID 串行化权限请求 |
-| `questionQueues` | 按 sessionID 串行化问题请求 |
+| 字段               | 用途                                          |
+| ------------------ | --------------------------------------------- |
+| `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 |
+| `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                                        |
 
 #### 消息缓冲机制
 
@@ -121,13 +121,13 @@ 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` | 生命周期事件 |
+| 函数        | 分类       | 用途                                           |
+| ----------- | ---------- | ---------------------------------------------- |
+| `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`   | 生命周期事件                                   |
 
 #### 特性
 
@@ -142,12 +142,12 @@ JSONL 格式日志系统，写入 `~/.harmony-acp/logs/`，每次启动一个文
 
 定义核心接口：
 
-| 接口 | 用途 |
-|------|------|
+| 接口           | 用途                                              |
+| -------------- | ------------------------------------------------- |
 | `SessionState` | 增强会话状态（含 parentID、title、model、modeId） |
-| `ACPConfig` | 服务器配置（sdk、serverUrl、cwd、defaultModel） |
-| `ModeOption` | 会话模式选项 |
-| `ModelOption` | 模型选项 |
+| `ACPConfig`    | 服务器配置（sdk、serverUrl、cwd、defaultModel）   |
+| `ModeOption`   | 会话模式选项                                      |
+| `ModelOption`  | 模型选项                                          |
 
 ---
 
@@ -155,10 +155,10 @@ JSONL 格式日志系统，写入 `~/.harmony-acp/logs/`，每次启动一个文
 
 两个纯函数：
 
-| 函数 | 用途 |
-|------|------|
-| `toToolKind()` | OpenCode 工具名 → ACP ToolKind 映射（bash→execute, edit/write→edit, grep/glob→search 等） |
-| `toLocations()` | 从工具输入元数据中提取文件路径位置信息 |
+| 函数            | 用途                                                                                      |
+| --------------- | ----------------------------------------------------------------------------------------- |
+| `toToolKind()`  | OpenCode 工具名 → ACP ToolKind 映射（bash→execute, edit/write→edit, grep/glob→search 等） |
+| `toLocations()` | 从工具输入元数据中提取文件路径位置信息                                                    |
 
 ---
 

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 操作