@wwkit/harness 1.0.9 → 1.0.11

package/skills/read-docs/references/opencode/agents/index.md

@@ -0,0 +1,309 @@
+# Agent
+
+Agent 是可配置的专门 AI 助手，用于特定任务和工作流。
+
+可以在会话中切换 Agent，或使用 `@` 提及调用。
+
+## Agent 类型
+
+| 类型 | 说明 |
+|------|------|
+| Primary Agent | 直接交互的主助手 |
+| Subagent | Primary Agent 可调用的专门助手（也可通过 `@` 手动调用） |
+
+## 内置 Agent
+
+### Primary Agent
+
+| Agent | 说明 |
+|-------|------|
+| build | 默认主 Agent，所有工具启用 |
+| plan | 规划和分析专用，文件编辑和 bash 默认需审批 |
+
+### Subagent
+
+| Agent | 说明 |
+|-------|------|
+| general | 通用多步骤任务，完整工具访问（除 todo），可并行执行 |
+| explore | 快速只读代码探索，查找文件和搜索代码 |
+| scout | 外部文档和依赖研究 |
+
+## 使用方式
+
+### 切换 Primary Agent
+
+使用 Tab 键在会话中切换。
+
+### 调用 Subagent
+
+- **自动调用**：Primary Agent 根据描述自动选择合适的 Subagent
+- **手动调用**：在消息中 `@` 提及，如 `@general help me search for this function`
+
+### 会话导航
+
+| 操作 | 快捷键 |
+|------|--------|
+| 进入第一个子会话 | `Leader+Down`（`session_child_first`） |
+| 切换到下一个子会话 | `Right`（`session_child_cycle`） |
+| 切换到上一个子会话 | `Left`（`session_child_cycle_reverse`） |
+| 返回父会话 | `Up`（`session_parent`） |
+
+## 配置方式
+
+### JSON 配置
+
+在 `opencode.json` 中配置：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent":{
+    "code-reviewer": {
+      "description": "Reviews code for best practices and potential issues",
+      "mode": "subagent",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
+      "permission": {
+        "edit": "deny"
+      }
+    }
+  }
+}
+```
+
+### Markdown 配置
+
+放置在以下位置：
+
+- 全局：`~/.config/opencode/agents/`，如 `~/.config/opencode/agents/review.md`
+- 项目级：`.opencode/agents/`
+
+```md
+---
+description: Reviews code for quality and best practices
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.1
+permission:
+  edit: deny
+  bash: deny
+---
+
+You are in code review mode. Focus on:
+
+- Code quality and best practices
+- Potential bugs and edge cases
+- Performance implications
+- Security considerations
+
+Provide constructive feedback without making direct changes.
+```
+
+文件名即为 Agent 名称，如 `review.md` 创建 `review` Agent。
+
+## 配置选项
+
+### Description
+
+提供 Agent 的简要描述和使用场景。
+
+### Temperature
+
+控制 LLM 响应的随机性和创造性：
+
+```json
+{
+  "agent": {
+    "plan": { "temperature": 0.1 },
+    "creative": { "temperature": 0.8 }
+  }
+}
+```
+
+### Steps
+
+控制 Agent 最大迭代次数：
+
+```json
+{
+  "agent": {
+    "quick-thinker": {
+      "description": "Fast reasoning with limited iterations",
+      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
+      "steps": 5
+    }
+  }
+}
+```
+
+### Disable
+
+禁用 Agent：
+
+```json
+{
+  "agent": {
+    "review": { "disable": true }
+  }
+}
+```
+
+### Prompt
+
+指定自定义系统提示词文件：
+
+```json
+{
+  "agent": {
+    "review": {
+      "prompt": "{file:./prompts/code-review.txt}"
+    }
+  }
+}
+```
+
+### Model
+
+为 Agent 覆盖默认模型：
+
+```json
+{
+  "agent": {
+    "plan": { "model": "anthropic/claude-haiku-4-20250514" }
+  }
+}
+```
+
+### Permissions
+
+配置 Agent 的操作权限：
+
+| 值 | 说明 |
+|----|------|
+| `ask` | 运行前需审批 |
+| `allow` | 允许所有操作 |
+| `deny` | 禁用工具 |
+
+权限键值表：
+
+| 键 | 控制的工具 |
+|----|-----------|
+| read | read |
+| edit | write, edit, apply_patch |
+| glob | glob |
+| grep | grep |
+| list | list |
+| bash | bash |
+| task | task |
+| external_directory | 读写项目工作树外的文件 |
+| todowrite | todowrite, todoread |
+| webfetch | webfetch |
+| websearch | websearch |
+| lsp | lsp |
+| skill | skill |
+| question | question |
+| doom_loop | Agent 卡住时的恢复提示 |
+
+`read`、`edit`、`glob`、`grep`、`list`、`bash`、`task`、`external_directory`、`lsp`、`skill` 支持简写操作或 glob/模式到操作的对象映射。
+
+按 Agent 覆盖权限：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": { "edit": "deny" },
+  "agent": {
+    "build": { "permission": { "edit": "ask" } }
+  }
+}
+```
+
+Markdown Agent 中配置权限：
+
+```md
+---
+description: Code review without edits
+mode: subagent
+permission:
+  edit: deny
+  bash:
+    "*": ask
+    "git diff": allow
+    "git log*": allow
+    "grep *": allow
+  webfetch: deny
+---
+
+Only analyze code and suggest changes.
+```
+
+### Mode
+
+控制 Agent 模式：`primary`、`subagent` 或 `all`（默认）。
+
+### Hidden
+
+隐藏 Subagent（不在 `@` 自动补全中显示）：
+
+```json
+{
+  "agent": {
+    "internal-helper": { "mode": "subagent", "hidden": true }
+  }
+}
+```
+
+仅对 `mode: subagent` 的 Agent 有效。
+
+### Additional
+
+其他选项将直接传递给 Provider 作为模型选项：
+
+```json
+{
+  "agent": {
+    "deep-thinker": {
+      "description": "Agent that uses high reasoning effort for complex problems",
+      "model": "openai/gpt-5",
+      "reasoningEffort": "high",
+      "textVerbosity": "low"
+    }
+  }
+}
+```
+
+## 创建 Agent
+
+使用命令创建：
+
+```
+opencode agent create
+```
+
+交互式流程：
+
+1. 选择保存位置（全局或项目级）
+2. 描述 Agent 功能
+3. 生成系统提示词和标识符
+4. 选择允许的权限
+5. 创建 Markdown 配置文件
+
+## 常见用例
+
+| Agent | 用途 |
+|-------|------|
+| Build | 全功能开发，所有工具启用 |
+| Plan | 分析和规划，不修改文件 |
+| Review | 代码审查，只读 + 文档工具 |
+| Debug | 调查问题，bash + read 工具 |
+| Docs | 文档编写，文件操作但无系统命令 |
+
+## 更多内容
+
+- [Agent 详解](/agents/detail) — 父子协作、提示词组装、权限设计
+- [Agent 工作流](/agents/workflow) — 5 种工作流模式
+- [Agent 设计模式](/agents/design-pattern) — 核心设计原则
+- [Agent 示例](/agents/examples) — 实用示例
+- [Agent 案例](/agents/cases) — 完整系统设计案例
+- [Subagent 内部机制](/agents/subagent-internals) — task 工具实现、会话生命周期、权限隔离、后台 subagent、命令触发子任务
+- [并行派发与调度策略](/agents/parallel-dispatch) — 并行机制、work agent 路由决策、摘要协议、设计决策

package/skills/read-docs/references/opencode/agents/parallel-dispatch.md

@@ -0,0 +1,149 @@
+# 并行派发与调度策略
+
+> 并行工作流模式参见 [Agent 工作流](/agents/workflow)。本文聚焦 opencode task 工具的并行内部机制和 harness work agent 的调度策略。
+
+## 并行原理
+
+opencode 的 `task` 工具描述明确鼓励并行：
+
+> "Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses"
+
+当 LLM 在一条 assistant message 中返回多个 `task` tool call 时，opencode 的 chat processor **并发执行**这些工具调用。每个 `task` 调用创建独立的子会话，互不干扰。
+
+## 并行限制
+
+| 限制项 | 默认值 | 说明 |
+|--------|--------|------|
+| 并行数量 | 无显式限制 | work agent prompt 中限制 ≤5 |
+| 嵌套深度 | `subagent_depth: 1` | 子 agent 默认不能再派发子 agent |
+| 文件所有权 | 由编排者保证 | 同一文件不并行改（work agent 规划 writable 白名单） |
+
+## 完整调度时序
+
+```
+用户                work agent            task 工具           子会话(explore)      子会话(general)
+ │                     │                     │                    │                    │
+ │── "实现功能X" ─────►│                     │                    │                    │
+ │                     │                     │                    │                    │
+ │                  解析输入                  │                    │                    │
+ │                  路由判断: parallel          │                    │                    │
+ │                  内联规划                   │                    │                    │
+ │                  todowrite 落单            │                    │                    │
+ │                     │                     │                    │                    │
+ │                     ├── task(explore) ──►│创建子会话 ─────────►│                    │
+ │                     │                     │parentID=父ID       │                    │
+ │                     │                     │权限隔离             │                    │
+ │                     │                     │prompt 注入 ───────►│                    │
+ │                     ├── task(general) ──►│创建子会话 ──────────────────────────────►│
+ │                     │                     │parentID=父ID       │                    │
+ │                     │                     │权限隔离             │                    │
+ │                     │                     │prompt 注入 ────────────────────────────►│
+ │                     │                     │                    │                    │
+ │                     │                     │                    │ 工具调用(read/grep) │
+ │                     │                     │                    │ 多轮 reasoning      │
+ │                     │                     │                    │ 生成结果摘要        │
+ │                     │                     │◄── XML 结果 ──────│                    │
+ │                     │                     │                    │                    │
+ │                     │                     │                    │                    │ 工具调用(edit/bash)
+ │                     │                     │                    │                    │ 多轮 reasoning
+ │                     │                     │                    │                    │ 生成结果摘要
+ │                     │                     │◄── XML 结果 ─────────────────────────────│
+ │                     │◄── 结果返回 ─────────│                    │                    │
+ │                     │                     │                    │                    │
+ │                  收集摘要                   │                    │                    │
+ │                  todowrite 勾单            │                    │                    │
+ │                  综合分析                   │                    │                    │
+ │                  验收                      │                    │                    │
+ │                     │                     │                    │                    │
+ │◄── 最终结果 ────────│                     │                    │                    │
+```
+
+## work agent 调度策略
+
+### 路由决策
+
+```
+用户输入
+  │
+  ▼
+解析 target / root_dir / constraints
+  │
+  ▼
+路由判断
+  ├─ single（单 worker 足够）
+  │   └─ 派 1 个 subagent 直接执行
+  │
+  └─ parallel（需要编排）
+      └─ 内联规划 → 并行派发 → 收集摘要 → 综合/验收
+```
+
+路由判断权重：**可拆性**（≥2 个独立子问题）> **时效**（用户要求快）> **规模**（文件多/改动大）
+
+### subagent_type 选择
+
+| subagent_type | 场景 | 工具权限 |
+|---------------|------|---------|
+| `explore` | 只读调研（搜索代码、读取文件、理解结构） | read/grep/glob（只读） |
+| `general` | 可写改动（编辑代码、执行命令、多步实现） | 全部工具（可写） |
+
+### 任务项规划格式
+
+work agent 为每个子任务规划以下字段：
+
+```
+task_id:      T1 / T2 / ...
+goal:        目标，≤1 句话，可验收
+agent:       explore（只读）| general（可写）
+input:       自包含完整上下文
+writable:    可写文件白名单（为空 ⇒ 只读）
+forbidden:   禁改文件清单（至少含 constraints）
+output:      交付说明（强制以摘要协议结尾）
+budget:      预计 ≤5 分钟
+```
+
+### 并行规则
+
+1. **路由判断**：先判断 single（单 worker 足够）还是 parallel（需要编排）
+2. **文件所有权分区**：同一轮内并行的 subagent 不得改同一文件
+3. **只读与可写并行**：只读调研任务与写文件任务可并行（只读不受分区限制）
+4. **有依赖串行**：无依赖的并行，有依赖的串行
+5. **容忍部分失败**：单个 worker failed/blocked 只记录不中断
+
+## 摘要协议
+
+所有被 work 派发的 subagent 必须以固定格式摘要结尾：
+
+```
+## 结果摘要
+status=done|partial|failed|blocked|escalate
+结论: <≤3 行>
+变更: <文件路径 + diff 摘要，每文件一行，无则填 无>
+阻塞: <阻塞项，无则填 无>
+建议: <下一步建议>
+```
+
+| Status | 含义 | 编排者动作 |
+|--------|------|-----------|
+| `done` | 目标完成 | 标记任务完成 |
+| `partial` | 部分完成 | 记录，继续综合 |
+| `failed` | 失败 | 记录失败项 |
+| `blocked` | 被环境/依赖卡住 | 记录，可能重规划 |
+| `escalate` | 超出边界/需人工介入 | 停止该分支，向用户说明 |
+
+## 关键设计决策
+
+### 上下文隔离
+
+子 agent 完全隔离，看不到父会话历史。原因：防止上下文爆炸、确保聚焦、降低 token 消耗、使并行子 agent 互不干扰。代价：编排者必须为每个子任务编写自包含的 prompt。
+
+### 权限收敛
+
+子 agent 默认不能使用 `task` 和 `todowrite` 工具。原因：防止无限递归、任务清单管理是编排者独有的职责。例外：agent 的 `permission` 配置中显式允许 `task` 时可嵌套，但受 `subagent_depth` 限制。
+
+### 结果精简
+
+子 agent 只返回最后一条 text part，编排者只读取摘要。原因：防止结果倾倒导致父会话上下文膨胀、强制子 agent 浓缩信息。
+
+### 容忍部分失败
+
+单个 worker failed/blocked 只记录不中断。原因：并行任务中一个失败不应影响其他独立任务、最大化任务完成率。

package/skills/read-docs/references/opencode/agents/subagent-internals.md

@@ -0,0 +1,217 @@
+# Subagent 内部机制
+
+> 基于 opencode v1.18.30 二进制逆向 + SDK 类型定义分析。配置层面（agent 定义、mode、permission）参见 [Agent 详解](/agents/detail)。
+
+## task 工具参数
+
+```typescript
+{
+  description: string,       // 3-5 词的任务描述
+  prompt: string,            // 完整任务指令（必须自包含）
+  subagent_type: string,     // agent 名称（如 "explore"、"general"）
+  task_id?: string,          // 传入已有 task_id 可恢复之前的子会话
+  background?: boolean,      // 实验性：后台执行
+  command?: string           // 触发此任务的命令
+}
+```
+
+## 执行流程（TaskTool.execute）
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  1. 深度检查                                                  │
+│     沿 parentID 链向上遍历，计算嵌套深度 h                     │
+│     if h >= subagent_depth (默认 1) → 报错退出                │
+├─────────────────────────────────────────────────────────────┤
+│  2. 权限检查                                                  │
+│     向用户请求使用 subagent_type 的权限                        │
+│     (除非 bypassAgentCheck=true，如命令触发的子任务)            │
+├─────────────────────────────────────────────────────────────┤
+│  3. Agent 解析                                                │
+│     AgentRegistry.get(subagent_type)                         │
+│     找不到 → "Unknown agent type" 错误                        │
+├─────────────────────────────────────────────────────────────┤
+│  4. 会话创建/恢复                                             │
+│     有 task_id → 尝试恢复已有子会话（继续之前的上下文）          │
+│     无 task_id → 创建新子会话:                                 │
+│       Session.create({                                       │
+│         parentID: 当前会话ID,                                │
+│         title: description + " (@agent subagent)",           │
+│         agent: subagent_type,                               │
+│         permission: [...继承+限制规则...]                     │
+│       })                                                     │
+├─────────────────────────────────────────────────────────────┤
+│  5. 模型解析                                                  │
+│     优先使用 agent 配置的 model                               │
+│     否则继承父 assistant message 的 model                     │
+├─────────────────────────────────────────────────────────────┤
+│  6. 执行子任务 (TaskTool.runTask)                             │
+│     a. 解析 prompt 中的 @file 引用                            │
+│     b. 调用 SessionPrompt.prompt({                           │
+│          sessionID: 子会话ID,                                │
+│          model: 解析的模型,                                   │
+│          agent: subagent_type,                              │
+│          parts: 解析后的 prompt parts                        │
+│        })                                                    │
+│     c. 等待子会话 LLM 执行完成                                │
+│     d. 提取子 agent 最终消息的最后一个 text part               │
+├─────────────────────────────────────────────────────────────┤
+│  7. 结果返回                                                  │
+│     前台模式: 等待完成，返回 XML 格式结果                      │
+│     后台模式: 立即返回，完成后注入结果                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 结果格式
+
+子 agent 的结果以 XML 标签返回给父 agent：
+
+```xml
+<task id="<sessionID>" state="completed">
+<task_result>
+<子 agent 最后一条 text part 的内容>
+</task_result>
+</task>
+```
+
+失败时：
+
+```xml
+<task id="<sessionID>" state="error">
+<task_error>
+<错误信息>
+</task_error>
+</task>
+```
+
+## 权限隔离（lt 函数）
+
+子会话创建时，权限规则由 `lt()` 函数生成：
+
+| 规则 | 默认效果 | 说明 |
+|------|---------|------|
+| `task: deny` | 禁止子 agent 再派发子 agent | 防止无限递归 |
+| `todowrite: deny` | 禁止子 agent 使用 todowrite | 只有编排者管理任务清单 |
+| `primary_tools: deny` | 禁止子 agent 使用 primary 专属工具 | 如 `experimental.primary_tools` 配置 |
+| 继承父会话 `deny` 规则 | 保持安全策略一致 | |
+| 继承父会话 `external_directory` 规则 | 保持目录访问限制 | |
+
+除非 agent 的 `permission` 配置中显式允许 `task` 或 `todowrite`，否则默认被拒绝。
+
+## 会话恢复（task_id 复用）
+
+传入 `task_id` 可以恢复之前的子会话：
+
+```javascript
+let T = m.task_id
+  ? yield* t.get(wt.make(m.task_id)).pipe(s.catchCause(() => s.succeed(void 0)))
+  : void 0;
+
+// 如果找到已有会话，复用；否则创建新的
+let O = T ?? (yield* t.create({...}));
+```
+
+恢复时，子会话**保留之前的所有消息和工具输出**，新的 prompt 追加到已有消息序列后。这使得编排者可以：
+- 让子 agent 继续未完成的任务
+- 向子 agent 提供额外信息后重试
+- 让子 agent 修正之前的错误
+
+## 会话存储
+
+- **存储后端**：SQLite（Node >= 22.5 用内置 `node:sqlite`，否则 `sqlite3` CLI）
+- **存储位置**：`Path.state` 目录下的 SQLite 数据库
+- **事件溯源**：v2 使用 durable events（`aggregateID` = sessionID, `seq` = 单调序号）
+
+| 隔离维度 | 方式 |
+|---------|------|
+| 消息 | 每个 Message/Part 有 `sessionID`，按会话隔离 |
+| 上下文 | 子会话不继承父会话消息 |
+| 权限 | `lt()` 函数生成隔离的权限规则集 |
+| 工具 | `primary_tools` 限制 + agent `tools` 配置 |
+| 深度 | `subagent_depth` 限制嵌套层数 |
+
+父子关系查询：`GET /session/{id}/children → Array<Session>`
+
+## 后台 Subagent（实验性）
+
+启用方式：`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` 或配置 `experimental.backgroundSubagents`。
+
+| 维度 | 前台模式（默认） | 后台模式（实验性） |
+|------|----------------|-------------------|
+| 返回时机 | 等待子会话完成 | 立即返回 "running" |
+| 父 agent 行为 | 阻塞等待 | 继续执行其他任务 |
+| 结果注入 | 作为 tool result | 完成后注入 synthetic message |
+| 提升机制 | 无 | `waitForPromotion()` 可将后台提升为前台 |
+
+后台完成后，结果通过 `TaskTool.injectBackgroundResult` 注入父会话：
+
+```javascript
+yield* K.prompt({
+  sessionID: <父会话ID>,
+  parts: [{
+    type: "text",
+    synthetic: true,
+    text: <XML 格式的任务结果>
+  }]
+});
+```
+
+## 命令触发的子任务（handleSubtask 路径）
+
+除了 LLM 直接调用 `task` 工具外，还有一条由**命令**触发的子任务路径。
+
+### 触发条件
+
+当用户执行一个命令，且命令对应的 agent `mode === "subagent"` 时（或命令配置了 `subtask: true`），opencode 自动创建 `SubtaskPart`：
+
+```javascript
+let G = ie.mode === "subagent" && O.subtask !== false || O.subtask === true;
+let We = G ? [{
+  type: "subtask",
+  agent: ie.name,
+  description: O.description ?? "",
+  command: t.command,
+  model: { providerID, modelID },
+  prompt: Y.find((A) => A.type === "text")?.text ?? ""
+}] : [...L, ...t.parts ?? []];
+```
+
+### 执行差异
+
+- **权限检查**：`bypassAgentCheck: true`，跳过用户权限确认
+- **结果处理**：命令触发的子任务完成后，注入 synthetic user message：`"Summarize the task tool output above and continue with your task."`
+- **消息创建**：自动创建 assistant message + tool part 记录子任务执行
+
+### @agent 引用
+
+用户在消息中使用 `@agent` 语法时，生成 `AgentPart`，opencode 注入 synthetic 指令：
+
+```
+Use the above message and context to generate a prompt and call the task tool with subagent: <agent_name>
+```
+
+## 关键类型定义
+
+### SubtaskPart
+
+```typescript
+type SubtaskPart = {
+  id: string
+  sessionID: string
+  messageID: string
+  type: "subtask"
+  prompt: string
+  description: string
+  agent: string             // 要派发的 subagent 名称
+  model?: { providerID: string; modelID: string }
+  command?: string
+}
+```
+
+### 配置项参考
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `subagent_depth` | `1` | 子 agent 嵌套深度限制 |
+| `experimental.primary_tools` | `[]` | 仅 primary agent 可用的工具列表 |
+| `experimental.backgroundSubagents` | `false` | 启用后台 subagent |