@wwkit/harness 1.0.10 → 1.0.12

package/commands/fix.md

@@ -0,0 +1,77 @@
+---
+description: 修复问题：问题定位→修复方案→修复测试→review→总结，并写入 {root_dir}/.webwork/harness/fix/yyyy-mm-dd/问题极简标题-hhmmss.md
+agent: build
+---
+
+你（build agent）根据用户问题描述 `$ARGUMENTS` 执行 5 阶段修复流程，产出文档写入 `{root_dir}/.webwork/harness/fix/<yyyy-mm-dd>/<问题极简标题>-<hhmmss>.md`。
+
+## 前置
+
+1. 解析问题描述 `$ARGUMENTS`；若为空，提示用户补充问题描述后停止。
+2. 确定工程根目录（当前 workdir / root_dir），所有相对路径基于它。
+3. 用 `todowrite` 建立 5 项任务清单（必须显式使用，逐项勾单，不攒批）：
+
+   - [ ] 1. 问题定位
+   - [ ] 2. 修复方案
+   - [ ] 3. 修复测试
+   - [ ] 4. review
+   - [ ] 5. 总结
+
+## 阶段 1：问题定位
+
+- 用 `grep`/`glob`/`read` 定位与问题相关的代码，梳理调用链，尽量复现问题。
+- 无法复现时如实记录"未能复现"及原因（环境/数据缺失等），不臆测。
+- 产出结论：**问题现象 → 定位位置（file:line）→ 根因**。
+
+## 阶段 2：修复方案
+
+- 先写方案再动手：列出涉及文件、改法、影响面、风险点。
+- 多种方案时选最简单可靠者，一句话说明取舍。
+- 方案需写出来（供阶段 4 review 对照），确认无逻辑漏洞后进入阶段 3。
+
+## 阶段 3：修复测试
+
+- 实施修改：遵循仓库既有代码风格，不加多余注释，只改必须改的地方。
+- 验证修复：运行相关测试/构建命令，或重跑复现用例确认症状消失。
+- 验证失败则回到阶段 2/3 迭代（自限 ≤3 轮），记录每轮结果。
+
+## 阶段 4：review
+
+- 自查 diff：边界情况、兼容性、遗漏改动、是否有其他调用方受影响。
+- 复查是否根治而非掩盖症状；发现问题回到阶段 2 修正，修正后重跑阶段 3 验证。
+- 全部通过后进入阶段 5。
+
+## 阶段 5：总结
+
+1. 生成日期目录和时间戳：`date +%Y-%m-%d` 获取日期，`date +%H%M%S` 获取时间戳（如 `{root_dir}/.webwork/harness/fix/2026-09-15/`），`mkdir -p` 创建。
+2. 标题：从问题描述提炼 ≤6 字极简短语（去空格/标点/特殊字符），如"登录接口401"。
+3. 用 `write` 写入 `{root_dir}/.webwork/harness/fix/<yyyy-mm-dd>/<问题极简标题>-<hhmmss>.md`，结构：
+
+   ```
+   # <问题极简标题>
+
+   - 日期：<yyyy-mm-dd>
+   - 问题描述：<用户描述摘要>
+
+   ## 1. 问题定位
+
+   <现象 / 位置 / 根因>
+
+   ## 2. 修复方案
+
+   <方案与取舍>
+
+   ## 3. 修复测试
+
+   <改动摘要 + 验证命令与结果>
+
+   ## 4. Review
+
+   <自查结论>
+
+   ## 5. 总结
+
+   <影响面、后续建议>
+   ```
+
+4. `todowrite` 确认 5 项全部勾完，向用户输出：**文档路径** + 修复结论摘要（改动文件、验证结果）。

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@wwkit/harness",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "author": "bluesliu <langcai163@163.com>",
   "description": "WebWork abilities for opencode",
   "type": "module",
   "main": "plugin.js",
   "files": [
     "plugin.js",
+    "plugins",
+    "scripts",
     "skills",
     "agents",
     "commands",

package/plugins/work-bootstrap.js

@@ -0,0 +1,77 @@
+import { randomUUID } from 'crypto'
+
+const BOOTSTRAP_MARKER = '__wwkit_work_bootstrap__'
+
+const BOOTSTRAP_TEXT = `[${BOOTSTRAP_MARKER}]
+
+你是 work（任务调度指挥官）。以下强约束优先级高于你的其他指令，必须遵守：
+
+## Red Flags（禁止行为）
+
+1. **禁止亲自逐行实现**：你的职责是拆解→派发→汇总，不是写代码。除非是单步 trivial 任务（≤1 文件、≤5 行），否则必须派发 subagent。
+2. **禁止先动手后规划**：多步骤任务必须先 todowrite 落单，再派发。
+3. **禁止上下文倾倒**：subagent prompt 必须自包含精炼上下文，不要把整个对话历史贴进去。
+4. **禁止串行派发**：独立任务必须在一条消息里并行发出多个 task 调用（≤5）。
+5. **禁止无限重试**：单个 worker failed/blocked 只记录不中断；全部失败才重规划；重规划 ≤3 轮。
+
+## 强制优先级
+
+- 能 single 绝不 parallel（先路由判断）。
+- 但如果任务涉及 ≥2 个独立子问题或 ≥3 个文件，必须 parallel。
+- subagent 类型：只读调研用 explore，可写改动用 general。
+- 每轮派发前必须确认 writable 白名单不重叠（文件所有权分区）。`
+
+export const WorkBootstrapPlugin = async () => {
+  return {
+    'experimental.chat.messages.transform': async (input, output) => {
+      const messages = output.messages
+      if (!Array.isArray(messages) || messages.length === 0) return
+
+      const users = messages.filter((m) => m?.info?.role === 'user')
+      const lastUser = users[users.length - 1]
+      if (!lastUser) return
+
+      const agent = lastUser.info?.agent
+      if (agent !== 'work') return
+
+      const alreadyInjected = messages.some((m) => {
+        const parts = m?.parts
+        if (!Array.isArray(parts)) return false
+        return parts.some(
+          (p) => p?.type === 'text' && typeof p.text === 'string' && p.text.includes(BOOTSTRAP_MARKER)
+        )
+      })
+      if (alreadyInjected) return
+
+      const sessionId = lastUser.info?.sessionID || lastUser.info?.id || ''
+      const messageId = lastUser.info?.id || ''
+
+      const bootstrapPart = {
+        id: `prt_${randomUUID()}`,
+        sessionID: sessionId,
+        messageID: messageId,
+        type: 'text',
+        text: BOOTSTRAP_TEXT,
+        synthetic: true,
+        time: { start: Date.now() }
+      }
+
+      messages.unshift({
+        info: {
+          id: `msg_${randomUUID()}`,
+          sessionID: sessionId,
+          role: 'assistant',
+          time: { created: Date.now() },
+          parentID: '',
+          modelID: '',
+          providerID: '',
+          mode: 'primary',
+          path: { cwd: '', root: '' },
+          cost: 0,
+          tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } }
+        },
+        parts: [bootstrapPart]
+      })
+    }
+  }
+}

package/scripts/work-review-package

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Generate a review package: commit list, stat summary, and the net
+# diff with extended context, written to a file the reviewer reads in one
+# call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit
+# tasks intact.
+#
+# Usage: work-review-package WORKSPACE_DIR TASK_NUMBER BASE HEAD [SUFFIX]
+#   Writes to: <WORKSPACE_DIR>/task-<N>-review-<base7>..<head7>.diff
+#   If SUFFIX is "final", writes to: <WORKSPACE_DIR>/final-review-<base7>..<head7>.diff
+set -euo pipefail
+
+if [ $# -lt 4 ] || [ $# -gt 5 ]; then
+  echo "usage: work-review-package WORKSPACE_DIR TASK_NUMBER BASE HEAD [SUFFIX]" >&2
+  exit 2
+fi
+
+ws="$1"
+n="$2"
+base="$3"
+head="$4"
+suffix="${5:-}"
+[ -d "$ws" ] || { echo "no such workspace directory: $ws" >&2; exit 2; }
+
+git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
+git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }
+
+base7=$(git rev-parse --short "$base")
+head7=$(git rev-parse --short "$head")
+
+if [ "$suffix" = "final" ]; then
+  out="$ws/final-review-${base7}..${head7}.diff"
+else
+  out="$ws/task-${n}-review-${base7}..${head7}.diff"
+fi
+
+{
+  echo "# Review package: ${base}..${head}"
+  echo
+  echo "## Commits"
+  git log --oneline "${base}..${head}"
+  echo
+  echo "## Files changed"
+  git diff --stat "${base}..${head}"
+  echo
+  echo "## Diff"
+  git diff -U10 "${base}..${head}"
+} > "$out"
+
+commits=$(git rev-list --count "${base}..${head}")
+echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"

package/scripts/work-task-brief

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# Write a task brief file from stdin, so the implementer reads its task
+# text in one call instead of receiving it through the controller's context.
+#
+# Usage: work-task-brief WORKSPACE_DIR TASK_NUMBER
+#   Reads task text from stdin, writes to <WORKSPACE_DIR>/task-<N>-brief.md
+set -euo pipefail
+
+if [ $# -ne 2 ]; then
+  echo "usage: work-task-brief WORKSPACE_DIR TASK_NUMBER" >&2
+  echo "  Reads task text from stdin." >&2
+  exit 2
+fi
+
+ws="$1"
+n="$2"
+[ -d "$ws" ] || { echo "no such workspace directory: $ws" >&2; exit 2; }
+
+out="$ws/task-${n}-brief.md"
+cat > "$out"
+
+if [ ! -s "$out" ]; then
+  echo "task brief is empty (stdin had no content)" >&2
+  exit 3
+fi
+
+echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"

package/scripts/work-workspace

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Resolve and ensure the working-tree directory for one work session's
+# short-lived artifacts: plan, task briefs, implementer reports, review
+# packages, and the progress ledger.
+#
+# Directory: <root_dir>/webwork/harness/work/<session-id>/
+# One directory per session so concurrent sessions never collide.
+#
+# Usage: work-workspace ROOT_DIR [SESSION_ID]
+# Prints the session directory's absolute path.
+set -euo pipefail
+
+if [ $# -lt 1 ] || [ $# -gt 2 ]; then
+  echo "usage: work-workspace ROOT_DIR [SESSION_ID]" >&2
+  exit 2
+fi
+
+root="$1"
+[ -d "$root" ] || { echo "no such directory: $root" >&2; exit 2; }
+
+if [ $# -eq 2 ]; then
+  sid="$2"
+else
+  sid="$(date +%s)"
+fi
+
+base="$root/webwork/harness/work"
+dir="$base/$sid"
+mkdir -p "$dir"
+printf '*\n' > "$base/.gitignore"
+cd "$dir" && pwd

package/skills/lint-env-ensure/references/config.md

@@ -41,8 +41,8 @@
 
 | 参数 | 值 | 说明 |
 |------|-----|------|
-| report_dir_pattern | `{root_dir}/.webwork/lint/reports/{YYYYMMDD_HHMMSS}/` | 报告输出目录 |
-| report.lint_report | `lint_report.md` | 最终报告文件名 |
+| report_dir_pattern | `{root_dir}/.webwork/harness/lint/{YYYY-MM-DD}/` | 报告输出目录 |
+| report.lint_report | `lint_report-{HHMMSS}.md` | 最终报告文件名 |
 
 ## 语言映射
 

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

@@ -305,3 +305,5 @@ opencode agent create
 - [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 |