@harmonyos-arkts/opencode-acp 0.0.1 → 0.0.2

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harmonyos-arkts/opencode-acp",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Enhanced ACP (Agent Client Protocol) server for OpenCode with subagent visibility",
   "type": "module",
   "main": "dist/index.cjs",
@@ -18,19 +18,22 @@
     "build": "node scripts/build.mjs",
     "typecheck": "tsc --noEmit",
     "dev": "node --watch src/index.ts",
-    "test": "node scripts/test.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "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"
+    "@opencode-ai/sdk": "latest",
+    "diff": "^9.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.17",
     "esbuild": "^0.25.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.5"
   },
   "engines": {
     "node": ">=18.0.0"