@harmonyos-arkts/opencode-acp 0.0.1

package/docs/question-asked.md

@@ -0,0 +1,287 @@
+# 问题回答（UserQuestionTool）实现说明
+
+## 背景
+
+OpenCode 的 `UserQuestionTool` 允许 agent 向用户提问并阻塞等待回答。典型场景：
+- agent 需要用户确认技术选型（React vs Vue）
+- agent 需要用户提供额外信息
+- agent 遇到歧义需要用户裁决
+
+**问题**：OpenCode 内置 ACP 和 Harmony-ACP 原本都忽略了 `question.asked` SSE 事件，导致 agent 调用 UserQuestionTool 时 Deferred promise 永远不 resolve，agent 挂起。
+
+**解决方案**：Harmony-ACP 拦截 `question.asked` SSE 事件，通过 ACP 扩展机制 `extMethod("questionAsked")` 转发给客户端，用户回答后通过 OpenCode SDK 回复，解除 agent 阻塞。
+
+## 为什么用 extMethod 而不是 requestPermission
+
+ACP 协议唯一的 agent→client request-response 机制是 `requestPermission`，但它只支持预定义选项（optionId），不支持自由文本。`extMethod` 的参数和返回值都是 `Record<string, unknown>`，天然支持任意结构。
+
+| 方面 | requestPermission | extMethod("questionAsked") |
+|------|-------------------|---------------------------|
+| 返回值 | 只有 optionId | 自由结构，直接返回 answers 数组 |
+| 自由文本 | 不支持 | 天然支持 |
+| 多问题 | 需 hack 合并 | 一次性传递完整问题列表 |
+| 语义 | 扭曲 permission 语义 | 干净的 question 语义 |
+
+## 完整流程
+
+### 数据流总览
+
+```
+OpenCode                              Harmony-ACP                              ACP Client
+────────                              ───────────                              ──────────
+
+agent 调用 UserQuestionTool
+    │
+    ├── Question.Service.ask()
+    │     创建 Deferred promise
+    │     发布 "question.asked" SSE 事件
+    │     await Deferred（阻塞）
+    │
+    ├── SSE: question.asked ───────►  EventHandler.handleEvent()
+    │                                   │
+    │                                   ├── resolveSession(q.sessionID)
+    │                                   ├── ocEvent("question.asked", ...)
+    │                                   │
+    │                                   ├── connection.extMethod("questionAsked", {
+    │                                   │     sessionId,
+    │                                   │     questionId: "q_1",
+    │                                   │     questions: [{ question, header, options, ... }]
+    │                                   │   }) ─────────────────────────────────────►
+    │                                   │                                           │
+    │                                   │                                           │ 识别 questionAsked
+    │                                   │                                           │ 渲染问题 UI
+    │                                   │                                           │ 等待用户输入
+    │                                   │   ◄─────────────────────────────────────── ┤
+    │                                   │   { answers: [["React"], ["自定义文本"]] }
+    │                                   │
+    │                                   ├── sdk.question.reply({ requestID, answers })
+    │                                   │
+    ◄── Deferred resolve，agent 继续 ──┘
+```
+
+### 阶段 1：Agent 发起提问
+
+agent 调用 `UserQuestionTool`，OpenCode 内部流程：
+
+```
+agent → UserQuestionTool.execute(params)
+      → Question.Service.ask({
+          sessionID: "ses_root123",
+          questions: [{
+            question: "Which framework?",
+            header: "Framework",
+            options: [
+              { label: "React", description: "React framework" },
+              { label: "Vue", description: "Vue framework" }
+            ],
+            multiple: false,
+            custom: true
+          }]
+        })
+      → 生成 QuestionID (如 "q_1")
+      → 创建 Deferred<Answer[], RejectedError>
+      → GlobalBus 发布 "question.asked" 事件
+      → await Deferred  ← 阻塞在这里
+```
+
+### 阶段 2：Harmony-ACP 拦截并转发
+
+`EventHandler.handleEvent()` 收到 SSE 事件，处理 `"question.asked"` case：
+
+```typescript
+// src/event-handler.ts
+
+case "question.asked": {
+  const q = event.properties  // { id, sessionID, questions }
+
+  // 1. 解析 session 路由（子 session 也能提问）
+  const resolved = this.resolveSession(q.sessionID)
+  if (!resolved) return
+
+  // 2. 记录日志
+  ocEvent("question.asked", { id: q.id, questions: q.questions.length })
+
+  // 3. 序列化：同一 session 的多个 question 依次处理
+  const prev = this.questionQueues.get(q.sessionID) ?? Promise.resolve()
+  const next = prev.then(async () => {
+
+    // 4. 通过 extMethod 发给 ACP 客户端
+    const res = await this.connection
+      .extMethod("questionAsked", {
+        sessionId,
+        questionId: q.id,
+        questions: q.questions,
+      })
+      .catch(() => undefined)
+
+    // 5a. 客户端无响应 → reject
+    if (!res || !res.answers) {
+      await this.sdk.question.reject({ requestID: q.id, directory })
+      return
+    }
+
+    // 5b. 客户端返回答案 → reply
+    await this.sdk.question.reply({
+      requestID: q.id,
+      directory,
+      answers: res.answers,  // Array<Array<string>>
+    })
+  })
+
+  // 6. 更新队列
+  this.questionQueues.set(q.sessionID, next)
+}
+```
+
+### 阶段 3：ACP 客户端处理
+
+客户端实现 `extMethod` handler（以 vscode-acp 为例）：
+
+```typescript
+// vscode-acp/src/core/AcpClientImpl.ts
+
+async extMethod(method: string, params: Record<string, unknown>) {
+  if (method === "questionAsked") {
+    return this.questionHandler.handleQuestionAsked(params)
+  }
+}
+```
+
+```typescript
+// vscode-acp/src/handlers/QuestionHandler.ts
+
+async handleQuestionAsked(params) {
+  const { questions } = params
+
+  for (const q of questions) {
+    if (q.options.length > 0) {
+      // 有选项 → QuickPick（支持多选）
+      const selected = await vscode.window.showQuickPick(items, { canPickMany: q.multiple })
+      answers.push(selected.map(s => s.label))
+    } else {
+      // 自由文本 → InputBox
+      const answer = await vscode.window.showInputBox({ prompt: q.question })
+      answers.push([answer])
+    }
+  }
+
+  return { answers }  // [["React"]] 或 [["自定义文本"]]
+}
+```
+
+### 阶段 4：回复 OpenCode 解除阻塞
+
+Harmony-ACP 调用 `sdk.question.reply()`：
+
+```
+Harmony-ACP → OpenCode HTTP API: POST /question/q_1/reply
+                Body: { answers: [["React"]] }
+
+OpenCode → Question.Service.reply()
+        → Deferred.resolve([["React"]])
+        → agent 收到回答，继续执行
+```
+
+或者如果用户取消，调用 `sdk.question.reject()`：
+
+```
+Harmony-ACP → OpenCode HTTP API: POST /question/q_1/reject
+
+OpenCode → Question.Service.reject()
+        → Deferred.reject(RejectedError)
+        → agent 收到错误，处理取消逻辑
+```
+
+## 事件格式
+
+### question.asked（SSE 事件，OpenCode → Harmony-ACP）
+
+```typescript
+{
+  type: "question.asked",
+  properties: {
+    id: "q_1",                    // QuestionID
+    sessionID: "ses_root123",     // 哪个 session 在问
+    questions: [{
+      question: "Which framework do you want to use?",  // 完整问题文本
+      header: "Framework",                               // 短标题（≤30 字符）
+      options: [                                          // 可选项
+        { label: "React", description: "React framework" },
+        { label: "Vue", description: "Vue framework" }
+      ],
+      multiple: false,        // 可多选
+      custom: true             // 允许自由文本（默认 true）
+    }],
+    tool?: {                   // 关联的 tool call（可选）
+      messageID: "msg_abc",
+      callID: "call_xyz"
+    }
+  }
+}
+```
+
+### extMethod("questionAsked")（Harmony-ACP → ACP Client）
+
+```typescript
+// 请求
+{
+  sessionId: "ses_root123",
+  questionId: "q_1",
+  questions: [{ question, header, options, multiple, custom }]
+}
+
+// 响应（用户回答）
+{ answers: [["React"]] }
+
+// 响应（用户取消或无响应）
+// extMethod 抛出错误或返回 undefined
+```
+
+### sdk.question.reply（Harmony-ACP → OpenCode）
+
+```typescript
+// 回答
+await sdk.question.reply({
+  requestID: "q_1",
+  directory: "/path/to/project",
+  answers: [["React"]]       // QuestionAnswer = Array<string>
+})
+
+// 拒绝
+await sdk.question.reject({
+  requestID: "q_1",
+  directory: "/path/to/project"
+})
+```
+
+## 序列化设计
+
+同一 session 可能连续触发多个 question。`questionQueues` 确保它们按序处理：
+
+```typescript
+private questionQueues = new Map<string, Promise<void>>()
+```
+
+```
+question 1 到达 → questionQueues["ses_1"] = Promise<处理 Q1>
+                    │
+                    ├── Q1 处理中，客户端等待用户输入
+                    │
+question 2 到达 → questionQueues["ses_1"] = Promise<处理 Q1>.then(() => 处理 Q2)
+                    │
+                    ├── Q1 完成 → 开始处理 Q2
+                    │
+                    └── Q2 完成 → questionQueues 删除 "ses_1"
+```
+
+这与 permission 处理的 `permissionQueues` 使用相同模式，防止同一 session 的多个交互请求并发导致状态混乱。
+
+## 涉及的文件
+
+| 文件 | 改动 | 作用 |
+|------|------|------|
+| `src/event-handler.ts` | 新增 `question.asked` case + `questionQueues` | 拦截 SSE 事件、调用 extMethod、回复 OpenCode |
+| `scripts/view-log.mjs` | 新增 `question.asked/reply/rejected` 格式化 | 日志查看器展示问题流程 |
+| `vscode-acp/src/handlers/QuestionHandler.ts` | 新建 | VSCode 客户端问题 UI（QuickPick / InputBox） |
+| `vscode-acp/src/core/AcpClientImpl.ts` | 新增 `extMethod()` | 客户端 extMethod 路由 |
+| `vscode-acp/src/core/ConnectionManager.ts` | 创建 QuestionHandler | 注入 handler |

package/docs/subagent-visibility.md

@@ -0,0 +1,170 @@
+# 子会话可见性（Subagent Visibility）实现说明
+
+## 背景
+
+OpenCode 的 agent 可以通过 Task 工具创建子 agent（subagent）来并行处理子任务。每个子 agent 有独立的 session，通过 SSE 事件流暴露出来。
+
+**问题**：OpenCode 内置的 ACP agent 只注册通过 `newSession`/`loadSession` 显式创建的顶层 session。子 session 未注册在 SessionManager 中，导致其事件（消息、工具调用等）被静默丢弃，ACP 客户端完全看不到子 agent 的存在。
+
+**Harmony-ACP 的解决方案**："独立虚拟会话"策略 — 自动发现子 session，注册到 SessionManager，为其分配独立的 sessionId 通知客户端，使客户端能区分父/子消息。
+
+## 核心数据结构
+
+### SessionState（src/types.ts）
+
+```typescript
+export interface SessionState {
+  id: string
+  cwd: string
+  parentID?: string     // 子 session 有，顶层 session 没有
+  title?: string
+  mcpServers: McpServer[]
+  createdAt: Date
+  model?: { providerID: string; modelID: string }
+  variant?: string
+  modeId?: string
+}
+```
+
+### SessionManager 内部索引（src/session-manager.ts）
+
+```typescript
+class SessionManager {
+  private sessions = new Map<string, SessionState>()    // sessionId → state
+  private children = new Map<string, Set<string>>()     // parentId → childIds
+}
+```
+
+两个 Map 维护完整的会话树：
+
+```
+sessions:
+  "ses_root123"  → { id: "ses_root123",  parentID: undefined }
+  "ses_child456" → { id: "ses_child456", parentID: "ses_root123" }
+  "ses_child789" → { id: "ses_child789", parentID: "ses_root123" }
+
+children:
+  "ses_root123" → Set { "ses_child456", "ses_child789" }
+```
+
+## 完整流程
+
+### 阶段 1：顶层 Session 创建
+
+用户在 ACP 客户端发起 `session/new`：
+
+```
+ACP Client                Harmony-ACP                      OpenCode Server
+─────────                 ────────────                     ────────────────
+session/new ──────────►  Agent.newSession()
+                              │
+                              ├── SessionManager.create()
+                              │     └── sdk.session.create() ──► 创建 session
+                              │           ◄── { id: "ses_root123" }
+                              │
+                              ├── sessions.set("ses_root123", { ... })
+                              │
+                              └── response ─────────────────►  { sessionId: "ses_root123" }
+```
+
+此时 `sessions` 中只有顶层 session，`children` 为空。
+
+### 阶段 2：子 Session 自动发现
+
+Agent 执行 Task 工具创建子 agent。OpenCode 通过 SSE 广播 `session.created` 事件：
+
+```
+OpenCode Server ── SSE: session.created ──►  EventHandler.handleEvent()
+    { type: "session.created",                      │
+      properties: {                                 │
+        info: {                                     ├── 检查 parentID 存在 → 是子 session
+          id: "ses_child456",                       │
+          parentID: "ses_root123",                  ├── SessionManager.registerDiscovered()
+          title: "Explore project"                  │     ├── 创建 SessionState { parentID: "ses_root123" }
+        }                                           │     ├── sessions.set("ses_child456", ...)
+      }                                             │     └── children.get("ses_root123").add("ses_child456")
+    }                                               │
+                                                    ├── announceChildSession()
+                                                    │     └── sendToClient({
+                                                    │           sessionId: "ses_child456",   ← 子 session 自己的 ID
+                                                    │           sessionUpdate: "session_info_update",
+                                                    │           title: "Explore project",
+                                                    │           _meta: {
+                                                    │             parentSessionId: "ses_root123",
+                                                    │             isSubagent: true
+                                                    │           }
+                                                    │         })
+                                                    │
+ACP Client  ◄── session_info_update ────────────────┘
+              (sessionId = "ses_child456")
+              客户端看到一个新的虚拟 session，
+              通过 _meta.parentSessionId 关联到父 session
+```
+
+关键设计：
+- 子 session 用**自己的 sessionId** 发送 `session_info_update`，不是用父 session 的
+- `_meta.parentSessionId` 让客户端知道它是子 session
+- `_meta.isSubagent = true` 标记身份
+
+### 阶段 3：子 Session 事件路由
+
+子 agent 产生消息、工具调用等事件时，SSE 事件携带子 session 的 sessionID。`resolveSession()` 负责路由：
+
+```
+SSE 事件: message.part.delta { sessionID: "ses_child456", ... }
+    │
+    ▼
+resolveSession("ses_child456")
+    │
+    ├── sessions.get("ses_child456") → 命中！返回 { sessionId: "ses_child456", cwd: "..." }
+    │
+    └── sendToClient({ sessionId: "ses_child456", update: { agent_message_chunk ... } })
+          │
+          ▼
+    ACP Client 收到 sessionId="ses_child456" 的消息，
+    知道这是子 agent 的输出，可以渲染在对应位置
+```
+
+### 阶段 4：多层嵌套处理
+
+子 agent 还可以创建孙 agent。`findRootSession()` 沿 parent 链向上递归查找：
+
+```
+resolveSession("ses_grandchild")
+    │
+    ├── sessions.get("ses_grandchild") → 命中！直接返回
+    │   （registerDiscovered 已经注册过了）
+    │
+    └── 返回 { sessionId: "ses_grandchild", cwd: "..." }
+```
+
+如果中间某个节点未被注册（理论上不应发生），`findRootSession()` 会沿 parent 链向上查找：
+
+```
+findRootSession("ses_grandchild")
+    → sessions.get("ses_grandchild") → { parentID: "ses_child456" }
+    → findRootSession("ses_child456")
+    → sessions.get("ses_child456") → { parentID: "ses_root123" }
+    → findRootSession("ses_root123")
+    → sessions.get("ses_root123") → { parentID: undefined } → 返回 ses_root123
+```
+
+## 关键方法说明
+
+| 方法 | 文件 | 作用 |
+|------|------|------|
+| `SessionManager.registerDiscovered()` | session-manager.ts:97 | 自动注册 SSE 发现的子 session，建立 parent-child 索引 |
+| `SessionManager.findRootSession()` | session-manager.ts:123 | 递归向上查找顶层 session（沿 parent 链） |
+| `SessionManager.getRelatedSessions()` | session-manager.ts:135 | 获取 session 子树所有 ID（含自身） |
+| `EventHandler.resolveSession()` | event-handler.ts:169 | 路由事件：直接查找 → 向上查找 → 返回 sessionId 和 cwd |
+| `EventHandler.announceChildSession()` | event-handler.ts:421 | 向 ACP 客户端发送 session_info_update 通知子 session |
+
+## 与 OpenCode 内置 ACP 的对比
+
+| 方面 | OpenCode 内置 ACP | Harmony-ACP |
+|------|-------------------|-------------|
+| 顶层 session 注册 | ✅ newSession/loadSession 时注册 | ✅ 同上 |
+| 子 session 注册 | ❌ 不注册，事件丢弃 | ✅ SSE 事件自动发现并注册 |
+| parent-child 索引 | ❌ 无 | ✅ `children` Map 维护 |
+| 子 session 事件路由 | ❌ 无法路由 | ✅ `resolveSession()` 正确路由 |
+| 客户端子 session 感知 | ❌ 客户端不知道子 session 存在 | ✅ 通过 `session_info_update` + `_meta` 通知 |

package/docs/tui-vs-acp-analysis.md

@@ -0,0 +1,61 @@
+# OpenCode TUI 能力 vs Harmony-ACP 对比分析
+
+## 已实现的能力
+
+| 能力 | TUI | Harmony-ACP | 说明 |
+|------|-----|-------------|------|
+| 会话创建/加载 | ✅ | ✅ | newSession, loadSession |
+| 会话列表/切换 | ✅ | ✅ | listSessions |
+| 会话 Fork | ✅ | ✅ | forkSession |
+| 会话恢复 | ✅ | ✅ | resumeSession |
+| Prompt（文本/图片） | ✅ | ✅ | 支持文本、图片、资源 |
+| 取消执行 | ✅ | ✅ | cancel |
+| 消息流式输出 | ✅ | ✅ | agent_message_chunk |
+| 思考过程流式输出 | ✅ | ✅ | agent_thought_chunk |
+| Tool Call 生命周期 | ✅ | ✅ | pending → running → completed/failed |
+| 权限请求 | ✅ | ✅ | requestPermission |
+| 问题回答 | ✅ | ✅ | extMethod("questionAsked") |
+| 子会话可见性 | ✅ | ✅ | 独立虚拟 session + parent-child 关联 |
+| 模式切换 | ✅ | ✅ | setSessionMode |
+| 模型切换 | ✅ | ✅ | setSessionModel |
+| Token/费用追踪 | ✅ | ✅ | usage_update |
+| Diff 显示 | ✅ | ✅ | edit tool 带 diff content |
+| 流量日志 | ❌ | ✅ | Harmony-ACP 独有能力，全量 ACP/OC 流量记录 |
+
+## 未实现 / 缺失的能力
+
+| 能力 | TUI 有 | Harmony-ACP | 影响 |
+|------|--------|-------------|------|
+| **Plan 更新** | ✅ | ❌ | plan_update 未实现，planning agent 输出不可见 |
+| **Session 删除** | ✅ | ❌ | 无 deleteSession |
+| **Session 重命名** | ✅ | ❌ | 无 rename |
+| **Session 压缩** | ✅ | ❌ | compact 消息未转发 |
+| **Undo/Redo** | ✅ | ❌ | 撤销/重做消息 |
+| **Share/Export** | ✅ | ❌ | 分享/导出会话 |
+| **Todo 更新** | ✅ | ❌ | todo.updated 事件未处理 |
+| **认证** | ❌ | ❌ | 声明了 auth 但未实现 |
+| **Modes 填充** | 部分 | ⚠️ | TODO: mode loading 未完成 |
+| **Model Options** | 部分 | ⚠️ | TODO: 从 providers 填充 |
+| **Context Size** | ✅ | ⚠️ | usage_update 中 size 硬编码为 0 |
+| **LSP/MCP 状态** | ✅ | ❌ | 未转发 LSP、MCP、VCS 状态 |
+| **VCS 分支** | ✅ | ❌ | vcs.branch.updated 未转发 |
+| **诊断信息** | ✅ | ❌ | LSP errors/warnings 未转发 |
+| **资源链接处理** | ✅ | ⚠️ | 非文本 resource_link 被跳过 |
+
+## 按优先级排序
+
+### 高优先级（影响基本使用体验）
+
+1. **Plan 更新** — planning agent 的核心能力，缺失会导致 plan 模式下客户端看不到任何输出
+2. **Session 删除** — 基础管理能力
+3. **Modes 填充** — 当前 modes 返回 undefined
+
+### 中优先级（提升可用性）
+
+4. **Todo 更新** — task/todo 工具的可见性
+5. **Session 压缩/Undo** — 长会话管理
+6. **LSP/MCP 状态** — 编辑器集成体验
+
+### 低优先级（锦上添花）
+
+7. Share/Export、认证、VCS 分支、诊断信息

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@harmonyos-arkts/opencode-acp",
+  "version": "0.0.1",
+  "description": "Enhanced ACP (Agent Client Protocol) server for OpenCode with subagent visibility",
+  "type": "module",
+  "main": "dist/index.cjs",
+  "bin": {
+    "harmony-acp": "dist/index.cjs"
+  },
+  "files": [
+    "dist/index.cjs",
+    "dist/index.cjs.map",
+    "README.zh.md",
+    "docs/"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "dev": "node --watch src/index.ts",
+    "test": "node scripts/test.mjs",
+    "test:integration": "node scripts/test-integration.mjs",
+    "logs": "node scripts/view-log.mjs",
+    "logs:filter": "node scripts/view-log.mjs --filter"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.16.1",
+    "@opencode-ai/sdk": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.17",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}