@harmonyos-arkts/opencode-acp 0.0.1 → 0.0.3

package/docs/provider-config-flow.md

@@ -0,0 +1,312 @@
+# VSCode → ACP → OpenCode Provider 配置全链路
+
+## 核心概念：OpenCode 的 Provider 可见性机制
+
+OpenCode 有两个层面的 provider 数据：
+
+| 数据源 | 接口 | 内容 | 用途 |
+|--------|------|------|------|
+| **数据库全量** | `GET /provider` | models.dev 中的所有 provider（70+） | 发现哪些 provider 可配置 |
+| **运行时可用** | `GET /config/providers` | 有凭证或 autoload 的 provider + 模型列表 | 模型选择下拉框 |
+
+**关键**：`GET /config/providers` 返回的不是"有 API Key 的 provider"，而是 `s.providers` 这个内部状态。进入 `s.providers` 的条件（`provider/provider.ts:1076-1285`）：
+
+| 条件 | 代码位置 | 说明 |
+|------|---------|------|
+| 配置文件声明了 provider | 1124 行 | `opencode.json` 中 `provider.<id>` 有配置 |
+| 环境变量有 key | 1211 行 | 如 `ANTHROPIC_API_KEY=xxx` |
+| auth.json 有 key | 1224 行 | 通过 `PUT /auth/:providerID` 存入的 |
+| Plugin auth loader | 1237 行 | Plugin 提供的认证加载器 |
+| **Custom loader autoload** | 1258 行 | **`opencode` provider 始终 autoload** |
+
+### `opencode` Provider 的特殊性
+
+`opencode` provider 有一个特殊的 custom loader（`provider/provider.ts:152-174`）：
+
+```typescript
+// 即使没有任何 key，只要还有免费模型，就 autoload
+if (!ok) {
+  // 删除付费模型，保留免费模型（cost.input === 0）
+  for (const [key, value] of Object.entries(input.models)) {
+    if (value.cost.input === 0) continue
+    delete input.models[key]
+  }
+}
+return {
+  autoload: Object.keys(input.models).length > 0,  // 有免费模型就 autoload
+  options: ok ? {} : { apiKey: "public" },          // 无 key 用 "public"
+}
+```
+
+**这意味着**：即使零配置，`GET /config/providers` 也会返回 `opencode` provider，包含所有免费模型（如 `glm-4.6`、`big-pickle` 等）。TUI 的 `/models` 能看到 GLM 模型就是这个原因。
+
+### 所以：配置 GLM 的场景分两种
+
+**场景 A：使用 OpenCode Zen 的免费 GLM 模型**
+
+```
+opencode provider 下的 glm-4.6 是免费模型
+→ 无需任何配置，直接可用
+→ providerID: "opencode", modelID: "glm-4.6"
+```
+
+**场景 B：使用智谱 AI 官方 API**
+
+```
+需要配置 zhipuai provider 的 API Key
+→ extMethod("provider/auth/set", { providerID: "zhipuai", auth: { type: "api", key: "xxx" } })
+→ 配置后 zhipuai provider 进入 s.providers
+→ 其下所有 GLM 模型可用
+```
+
+## 阶段一：启动 & 发现
+
+```
+VSCode 启动 harmony-acp 进程
+  │
+  ├─ harmony-acp 连接 OpenCode server (http://localhost:4096)
+  │   └─ sdk.global.health() 验证连通
+  │
+  └─ VSCode 调用 initialize()
+      │
+      └─ harmony-acp 返回:
+         {
+           authMethods: [{ id: "opencode-login", name: "Login with opencode" }],
+           _meta: {
+             providers: [
+               { id: "opencode",  name: "OpenCode",  connected: true },   ← 始终连接（免费模型）
+               { id: "anthropic", name: "Anthropic",  connected: false },
+               { id: "openai",    name: "OpenAI",     connected: false },
+               { id: "zhipuai",   name: "ZhipuAI",    connected: false },
+             ]
+           }
+         }
+```
+
+**VSCode 此时知道**：哪些 provider 可用、哪些已连接。
+
+## 阶段二：创建 Session & 发现可用模型
+
+```
+VSCode 调用 newSession({ cwd })
+  │
+  ├─ harmony-acp 调用 sdk.config.providers()
+  │   → 返回 [opencode provider]  ← 因为 opencode 始终 autoload
+  │   → opencode.models = { "glm-4.6", "big-pickle", ... }  ← 免费模型
+  │
+  ├─ harmony-acp 调用 defaultModel()
+  │   → 找到 opencode provider → 选择第一个模型
+  │
+  ├─ sdk.session.create() → 成功创建 session
+  │
+  └─ 返回给 VSCode:
+      {
+        sessionId: "xxx",
+        models: {
+          currentModelId: "opencode/glm-4.6",
+          availableModels: [
+            { modelId: "opencode/glm-4.6",    name: "OpenCode/GLM-4.6" },
+            { modelId: "opencode/big-pickle",  name: "OpenCode/Big Pickle" },
+          ]
+        },
+        configOptions: [
+          { id: "model", currentValue: "opencode/glm-4.6", options: [...] },
+          { id: "mode",  currentValue: "build", options: [...] }
+        ]
+      }
+```
+
+**此时**：VSCode 可以用免费模型直接对话，但只有 `opencode` provider 的免费模型可选。
+
+## 阶段三：用户配置新 Provider 的 API Key
+
+用户想使用 Claude、GPT 等付费模型，需要配置对应 provider 的 API Key。
+
+```
+用户在 VSCode 中选择 "配置 Provider"
+  │
+  ├─① extMethod("provider/list", { sessionId })
+  │   │
+  │   └─ harmony-acp → sdk.provider.list()
+  │       → GET /provider → 返回全量 provider 列表
+  │       → { all: [opencode, anthropic, openai, zhipuai, ...], connected: ["opencode"] }
+  │       → VSCode 展示 "未连接" 的 provider 列表让用户选择
+  │
+  ├─② 用户选择 anthropic，VSCode 查询认证方式:
+  │   extMethod("provider/auth/methods", { sessionId })
+  │   │
+  │   └─ harmony-acp → sdk.provider.auth()
+  │       → GET /provider/auth
+  │       → { anthropic: [{ type: "api", label: "API Key" }] }
+  │       → VSCode 知道需要输入 API Key，展示输入框
+  │
+  ├─③ 用户输入 API Key，VSCode 调用:
+  │   extMethod("provider/auth/set", {
+  │     providerID: "anthropic",
+  │     auth: { type: "api", key: "sk-ant-xxx" }
+  │   })
+  │   │
+  │   └─ harmony-acp → sdk.auth.set()
+  │       → PUT /auth/anthropic → 写入 ~/.opencode/data/auth.json
+  │       → 返回 { success: true }
+  │
+  └─④ 验证是否生效（可选）:
+      extMethod("provider/list", { sessionId })
+      │
+      └─ harmony-acp → sdk.provider.list()
+          → 返回: { connected: ["opencode", "anthropic"] }  ← anthropic 已连接
+```
+
+## 阶段四：切换到新模型
+
+配置 API Key 后，**不需要重新创建 session**，直接通过 `setSessionConfigOption` 切换模型：
+
+```
+VSCode 调用 setSessionConfigOption({
+  sessionId, configId: "model", value: "anthropic/claude-sonnet-4"
+})
+  │
+  ├─ harmony-acp → sdk.config.providers()
+  │   → 现在返回 [opencode, anthropic]  ← anthropic 有 key 了
+  │   → anthropic.models = { "claude-sonnet-4", "claude-opus-4", ... }
+  │
+  ├─ parseModelSelection("anthropic/claude-sonnet-4")
+  │   → { providerID: "anthropic", modelID: "claude-sonnet-4" }
+  │
+  └─ 更新 session model → 返回新的 configOptions（包含 anthropic 的所有模型）
+```
+
+或者用 `setSessionModel`：
+
+```
+VSCode 调用 unstable_setSessionModel({
+  sessionId, modelId: "anthropic/claude-sonnet-4/high"
+})
+  │
+  └─ 同样效果，支持 variant 选择
+```
+
+## 阶段五：开始对话
+
+```
+VSCode 调用 prompt({ sessionId, prompt: [...] })
+  │
+  └─ harmony-acp → sdk.session.prompt({
+       sessionID,
+       model: { providerID: "anthropic", modelID: "claude-sonnet-4" },
+       parts: [...]
+     })
+  │
+  └─ OpenCode 用该模型发起 API 调用
+      → 如果 key 无效，此时才报错 → harmony-acp 捕获 → RequestError.authRequired()
+      → 如果 key 有效，正常流式返回
+```
+
+## 完整数据流图
+
+```
+VSCode                    harmony-acp                    OpenCode Server
+  │                           │                               │
+  │── initialize() ──────────>│                               │
+  │                           │── sdk.provider.list() ───────>│ GET /provider
+  │                           │<── {all, connected} ──────────│
+  │<── {authMethods, _meta} ──│                               │
+  │                           │                               │
+  │── newSession() ──────────>│                               │
+  │                           │── sdk.config.providers() ────>│ GET /config/providers
+  │                           │<── [opencode + 免费模型] ─────│ (opencode 始终 autoload)
+  │                           │── sdk.session.create() ──────>│ POST /session
+  │                           │<── { id } ────────────────────│
+  │<── { sessionId, models } ─│                               │
+  │                           │                               │
+  │── prompt(免费模型) ───────>│                               │
+  │                           │── sdk.session.prompt() ──────>│ POST /session/xxx/prompt
+  │                           │<── SSE events ────────────────│
+  │<── streaming response ────│                               │
+  │                           │                               │
+  │== 用户想用 Claude =======│                               │
+  │                           │                               │
+  │── extMethod("provider/list") ─────────>│                  │
+  │                           │── sdk.provider.list() ───────>│ GET /provider
+  │                           │<── {all, connected} ──────────│
+  │<── 全量 provider 列表 ────│                               │
+  │                           │                               │
+  │── extMethod("provider/auth/methods") ──>│                 │
+  │                           │── sdk.provider.auth() ───────>│ GET /provider/auth
+  │                           │<── {anthropic: [{type:"api"}]}│
+  │<── 认证方式 ──────────────│                               │
+  │                           │                               │
+  │── extMethod("provider/auth/set") ──────>│                 │
+  │  { providerID, auth }     │── sdk.auth.set() ────────────>│ PUT /auth/anthropic
+  │                           │                               │ → 写入 auth.json
+  │                           │<── true ──────────────────────│
+  │<── { success: true } ─────│                               │
+  │                           │                               │
+  │── setSessionConfigOption ─>│                              │
+  │  { "anthropic/claude-sonnet-4" }                           │
+  │                           │── sdk.config.providers() ────>│ GET /config/providers
+  │                           │<── [opencode, anthropic] ────│
+  │<── 更新后的模型列表 ──────│                               │
+  │                           │                               │
+  │── prompt(claude) ────────>│                               │
+  │                           │── sdk.session.prompt() ──────>│ POST /session/xxx/prompt
+  │                           │<── SSE events ────────────────│
+  │<── streaming response ────│                               │
+```
+
+## 涉及的 OpenCode 接口
+
+### 控制面路由（`routes/control/index.ts`）
+
+| 方法 | 路径 | 用途 |
+|------|------|------|
+| `PUT` | `/auth/:providerID` | 设置 API Key，写入 `~/.opencode/data/auth.json` |
+| `DELETE` | `/auth/:providerID` | 移除凭证 |
+
+### 实例面路由（`routes/instance/provider.ts`）
+
+| 方法 | 路径 | 用途 |
+|------|------|------|
+| `GET` | `/provider` | 返回全量 provider 列表 + connected 状态 |
+| `GET` | `/provider/auth` | 返回每个 provider 的认证方式（API Key / OAuth） |
+| `POST` | `/:providerID/oauth/authorize` | OAuth 授权（仅 Plugin 注册了 OAuth hook 的 provider） |
+| `POST` | `/:providerID/oauth/callback` | OAuth 回调 |
+
+### 实例面路由（`routes/instance/config.ts`）
+
+| 方法 | 路径 | 用途 |
+|------|------|------|
+| `GET` | `/config/providers` | 返回 `s.providers`（有凭证或 autoload 的 provider + 模型列表） |
+
+## 两个 Provider 接口的区别
+
+| | `GET /provider` | `GET /config/providers` |
+|---|---|---|
+| 数据源 | models.dev 全量数据库 + connected 状态 | `s.providers` 内部状态（有凭证/autoload） |
+| 返回范围 | **所有** provider（70+） | 仅"可用"的 provider |
+| 用途 | 发现可配置的 provider、展示配置入口 | 模型选择下拉框的数据源 |
+| 返回格式 | `{ all, default, connected }` | `{ providers, default }` |
+| ACP extMethod | `provider/list` | 无（harmony-acp 内部调用） |
+| TUI 使用 | `store.provider_next` | `store.provider`（`/models` 下拉框） |
+
+## API Key 有效性判定
+
+- **配置阶段**：只判断"存不存在"，不判断"对不对"
+- **使用阶段**：首次 `prompt()` 调用时才真正验证，key 无效则抛 `AI_LoadAPIKeyError`
+- harmony-acp 在 `newSession`/`loadSession`/`forkSession`/`resumeSession` 中捕获该错误，返回 `RequestError.authRequired()`
+
+## OAuth 接口的调用条件
+
+OAuth 流程**不是通用的**，只有 Plugin 注册了 `auth.provider` hook 的 provider 才支持。
+
+流程（参考 `packages/app/src/components/dialog-connect-provider.tsx`）：
+
+1. `GET /provider/auth` 获取认证方式列表
+2. 如果 `type === "oauth"` 且有 `prompts` → 展示表单让用户填写
+3. `POST /:providerID/oauth/authorize` 获取授权 URL
+4. 根据 `method` 字段：
+   - `"code"` → 用户从浏览器复制 code → `POST /:providerID/oauth/callback({ code })`
+   - `"auto"` → 自动回调 → `POST /:providerID/oauth/callback`（无 code）
+5. 回调成功后 OpenCode 自动写入 auth.json
+
+绝大多数用户（Anthropic、OpenAI 等）只需 API Key 方式，不走 OAuth。

package/docs/question-asked.md

@@ -3,11 +3,28 @@
 ## 背景
 
 OpenCode 的 `UserQuestionTool` 允许 agent 向用户提问并阻塞等待回答。典型场景：
+
 - agent 需要用户确认技术选型（React vs Vue）
 - agent 需要用户提供额外信息
 - agent 遇到歧义需要用户裁决
 
-**问题**：OpenCode 内置 ACP 和 Harmony-ACP 原本都忽略了 `question.asked` SSE 事件，导致 agent 调用 UserQuestionTool 时 Deferred promise 永远不 resolve，agent 挂起。
+**问题**：OpenCode 内置 ACP 忽略了 `question.asked` SSE 事件，导致 agent 调用 UserQuestionTool 时 Deferred promise 永远不 resolve，agent 挂起。
+
+opencode question.asked流程：
+
+1. Agent 调用 QuestionTool → Question.ask() → 创建 deferred，发布 question.asked 事件到 bus → await deferred
+2. TUI 通过 SSE 接收 question.asked 事件，向用户显示问题
+3. 用户回答 → TUI 调用 HTTP POST /question/:requestID/reply → Question.reply() → 解析 deferred
+4. Agent 继续
+
+opencode acp 缺少对 "question.asked" 的处理。 当 agent 通过 UserQuestionTool (即 QuestionTool 在 src/tool/question.ts 中) 调用 Question.ask() 时：
+
+1. Question.ask() 创建一个 Deferred，发布 question.asked 到总线，并 await 延迟处理
+2. runEventSubscription() 通过全局 SSE 流接收到事件
+3. handleEvent() 调用并使用 switch(event.type) — 没有 case "question.asked" 分支
+4. 该事件被静默丢弃
+5. ACP 客户端 (例如 Claude Code、Copilot 等) 从未收到关于问题的通知，无法显示 UI，也无法调用 POST /question/:requestID/reply
+6. Deferred 永远不会解决 → agent 永久挂起
 
 **解决方案**：Harmony-ACP 拦截 `question.asked` SSE 事件，通过 ACP 扩展机制 `extMethod("questionAsked")` 转发给客户端，用户回答后通过 OpenCode SDK 回复，解除 agent 阻塞。
 
@@ -15,12 +32,12 @@ OpenCode 的 `UserQuestionTool` 允许 agent 向用户提问并阻塞等待回
 
 ACP 协议唯一的 agent→client request-response 机制是 `requestPermission`，但它只支持预定义选项（optionId），不支持自由文本。`extMethod` 的参数和返回值都是 `Record<string, unknown>`，天然支持任意结构。
 
-| 方面 | requestPermission | extMethod("questionAsked") |
-|------|-------------------|---------------------------|
-| 返回值 | 只有 optionId | 自由结构，直接返回 answers 数组 |
-| 自由文本 | 不支持 | 天然支持 |
-| 多问题 | 需 hack 合并 | 一次性传递完整问题列表 |
-| 语义 | 扭曲 permission 语义 | 干净的 question 语义 |
+| 方面     | requestPermission    | extMethod("questionAsked")      |
+| -------- | -------------------- | ------------------------------- |
+| 返回值   | 只有 optionId        | 自由结构，直接返回 answers 数组 |
+| 自由文本 | 不支持               | 天然支持                        |
+| 多问题   | 需 hack 合并         | 一次性传递完整问题列表          |
+| 语义     | 扭曲 permission 语义 | 干净的 question 语义            |
 
 ## 完整流程
 
@@ -244,14 +261,14 @@ OpenCode → Question.Service.reject()
 await sdk.question.reply({
   requestID: "q_1",
   directory: "/path/to/project",
-  answers: [["React"]]       // QuestionAnswer = Array<string>
-})
+  answers: [["React"]], // QuestionAnswer = Array<string>
+});
 
 // 拒绝
 await sdk.question.reject({
   requestID: "q_1",
-  directory: "/path/to/project"
-})
+  directory: "/path/to/project",
+});
 ```
 
 ## 序列化设计
@@ -278,10 +295,10 @@ question 2 到达 → questionQueues["ses_1"] = Promise<处理 Q1>.then(() =>
 
 ## 涉及的文件
 
-| 文件 | 改动 | 作用 |
-|------|------|------|
-| `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 |
+| 文件                                         | 改动                                          | 作用                                         |
+| -------------------------------------------- | --------------------------------------------- | -------------------------------------------- |
+| `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/session-stats-to-vscode-design.md

@@ -0,0 +1,217 @@
+# 方案：将 Session 统计信息暴露给 harmony-acp 并呈现到 VSCode
+
+> 日期：2026-04-29
+> 状态：方案设计
+
+---
+
+## Context
+
+OpenCode session 表已持久化 `summary_additions`/`summary_deletions`/`summary_files`/`summary_diffs`，SDK 类型已包含 `summary` 字段。但 harmony-acp 目前只通过 `usage_update` 发送 token/cost，未暴露代码行变更信息。
+
+**目标：** VSCode 能实时/加载时看到 session 的代码修改统计（additions/deletions/files）。
+
+---
+
+## 架构决策：`usage_update._meta` 扩展
+
+选择 `usage_update._meta` 而非 `session_info_update`，理由：
+
+1. **语义一致** — 代码行变更与 token/cost 同属"资源消耗"维度，`usage_update` 即"这次消耗了什么"
+2. **减少事件流** — 不额外增加通知，VSCode 一个回调拿到所有统计，避免 UI 抖动
+3. **`_meta` 为扩展设计** — ACP 协议文档明确 `_meta` 用于附加数据
+4. **时序对齐** — token 和代码变更在同一事件中，无中间态
+5. **文件级 diff 已有通道** — edit tool 的 tool_call_update 已返回 diff，无需重复传输
+
+**数据格式：**
+```typescript
+usage_update._meta.codeChange = {
+  additions: number
+  deletions: number
+  files: number
+}
+```
+
+---
+
+## 修改范围
+
+仅修改 harmony-acp，**不改 OpenCode、不改 ACP 协议**：
+
+- OpenCode 已有 `session.diff` SSE 事件 + `EventSessionDiff` SDK 类型
+- ACP `UsageUpdate._meta` 是 `{ [key: string]: unknown }` 扩展字段
+- harmony-acp 已在 `_meta` 传递 `parentCost`/`childCost`，模式一致
+
+---
+
+## 数据流
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  OpenCode Server                                                │
+│                                                                  │
+│  Session 完成时 → SSE 事件 session.diff {sessionID, diff[]}     │
+│  Session 加载时 → API session.get() 返回 summary 字段            │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │ SSE / HTTP
+                            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  harmony-acp (EventHandler)                                     │
+│                                                                  │
+│  1. 监听 session.diff → 聚合 additions/deletions/files          │
+│  2. 存入 diffStats Map<sessionID, CodeChangeStats>              │
+│  3. loadSession 时从 session.summary 回填                        │
+│  4. sendUsageUpdate() 时读取并附加到 _meta.codeChange            │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │ ACP JSON-RPC (usage_update)
+                            ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  VSCode Extension                                               │
+│                                                                  │
+│  usage_update._meta.codeChange = { additions, deletions, files }│
+│  → 状态栏展示 "+123 -45 (3 files)"                              │
+│  → Session 面板展示详细统计                                      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 实现步骤
+
+### Step 1: 新增 CodeChangeStats 类型
+
+**文件：** `src/types.ts`
+
+```typescript
+export interface CodeChangeStats {
+  additions: number
+  deletions: number
+  files: number
+}
+```
+
+### Step 2: EventHandler 监听 `session.diff` 事件
+
+**文件：** `src/event-handler.ts`
+
+在 `handleEvent()` 的 switch 中新增 `session.diff` 分支：
+
+```typescript
+case "session.diff": {
+  const { sessionID, diff } = event.properties
+  const stats = diff.reduce(
+    (acc, d) => ({
+      additions: acc.additions + d.additions,
+      deletions: acc.deletions + d.deletions,
+      files: acc.files + 1,
+    }),
+    { additions: 0, deletions: 0, files: 0 },
+  )
+  this.diffStats.set(sessionID, stats)
+  return
+}
+```
+
+新增实例变量和方法：
+- `diffStats: Map<string, CodeChangeStats>` — 存储 session 级 diff 聚合
+- `getDiffStats(sessionId)` — 供 agent.ts 读取
+- `setDiffStats(sessionId, stats)` — 供 agent.ts 回填历史数据
+- `clearDiffStats(sessionId)` — session 结束时清理
+
+### Step 3: `sendUsageUpdate()` 附加 codeChange
+
+**文件：** `src/agent.ts` 的 `sendUsageUpdate()` 方法
+
+在现有 `_meta` 构造中增加 `codeChange` 字段：
+
+```typescript
+const stats = this.eventHandler.getDiffStats(sessionId)
+// 聚合子 session 的 diff
+let childStats: CodeChangeStats | undefined
+for (const childId of children) {
+  const cs = this.eventHandler.getDiffStats(childId)
+  if (cs) {
+    childStats = childStats
+      ? { additions: childStats.additions + cs.additions, deletions: childStats.deletions + cs.deletions, files: childStats.files + cs.files }
+      : cs
+  }
+}
+
+const totalStats = stats || childStats
+  ? {
+      additions: (stats?.additions ?? 0) + (childStats?.additions ?? 0),
+      deletions: (stats?.deletions ?? 0) + (childStats?.deletions ?? 0),
+      files: (stats?.files ?? 0) + (childStats?.files ?? 0),
+    }
+  : undefined
+
+// 在 _meta 中附加
+_meta: {
+  ...existingMeta,
+  ...totalStats && { codeChange: totalStats },
+  ...childStats && {
+    childCodeChange: childStats,
+  },
+}
+```
+
+### Step 4: 加载历史 session 时读取 summary
+
+**文件：** `src/agent.ts`
+
+在 `loadSession()` 和 `unstable_resumeSession()` 中：
+
+这两个方法已通过 `sdk.session.get()` 获取 session 数据。SDK 返回的 `Session` 类型包含 `summary?: { additions, deletions, files, diffs }`。
+
+从返回数据中提取 summary，存入 EventHandler 的 `diffStats` map：
+
+```typescript
+const session = await this.sdk.session.get({ sessionID, directory })
+if (session.data?.summary) {
+  this.eventHandler.setDiffStats(sessionID, {
+    additions: session.data.summary.additions,
+    deletions: session.data.summary.deletions,
+    files: session.data.summary.files,
+  })
+}
+```
+
+这样已有的 `sendUsageUpdate()` 调用会自动携带历史统计数据。
+
+### Step 5: Session 清理
+
+**文件：** `src/event-handler.ts`
+
+在子 session 完成（`sendChildSessionCompleted`）和 session 关闭时，清理 `diffStats` 中对应条目避免内存泄漏。
+
+---
+
+## 涉及文件
+
+| 文件 | 修改内容 |
+|------|---------|
+| `src/types.ts` | 新增 `CodeChangeStats` 接口 |
+| `src/event-handler.ts` | 新增 `session.diff` 事件处理 + `diffStats` map + get/set/clear 方法 |
+| `src/agent.ts` | `sendUsageUpdate()` 附加 `_meta.codeChange`；`loadSession()`/`resumeSession()` 读取 `session.summary` |
+
+---
+
+## 依赖的 OpenCode 现有能力
+
+| 能力 | 来源 | 说明 |
+|------|------|------|
+| `session.diff` SSE 事件 | OpenCode SDK `EventSessionDiff` | session 代码变更时实时推送 `SnapshotFileDiff[]` |
+| `Session.summary` 字段 | OpenCode SDK `Session` 类型 | 含 `additions`/`deletions`/`files`/`diffs` |
+| `UsageUpdate._meta` | ACP 协议 | `{ [key: string]: unknown }` 扩展字段 |
+| 已有 `_meta` 扩展模式 | harmony-acp `sendUsageUpdate()` | 已传递 `parentCost`/`childCost`/`childSessionCount` |
+
+---
+
+## 验证
+
+1. 启动 OpenCode server（`bun dev serve`）
+2. 启动 harmony-acp 连接 VSCode
+3. 创建 session，让 agent 修改几个文件
+4. 检查 VSCode 收到的 `usage_update._meta.codeChange` 是否正确
+5. `loadSession()` 加载已有 session，验证历史 summary 也正确传递
+6. 创建含子 session 的任务，验证子 session 的 diff 也被聚合