@wwkit/harness 1.0.9 → 1.0.11

package/skills/read-docs/references/opencode/tui/commands/index.md

@@ -0,0 +1,125 @@
+# Commands
+Type `/` followed by a command name to execute
+```
+/help
+```
+
+Most commands also have keyboard shortcuts using `ctrl+x` as the default leader key.
+
+
+## connect
+Add a provider to OpenCode. Allows you to select from available providers and add their API keys.
+```
+/connect
+```
+
+## compact
+Compact the current session:
+```
+/compact
+
+// alias
+/summarize
+
+// keybind
+ctrl+x c
+```
+
+## details
+Toggle tool execution details.
+```
+/details
+```
+
+## exit
+Exit OpenCode. Aliases: `/quit`, `/q`
+```
+/exit
+
+// keybind
+ctrl+x q
+```
+
+## export
+Export current conversation to Markdown and open in your default editor.
+```
+/export
+
+// keybind
+ctrl+x x
+```
+
+## models
+List available models.
+```
+/models
+
+// keybind
+ctrl+x m
+```
+
+## new
+Start a new session. Alias: `/clear`
+```
+/new
+
+// keybind
+ctrl+x n
+```
+
+## redo
+Redo a previously undone message. Only available after using `/undo`.
+```
+/redo
+
+// keybind
+ctrl+x r
+```
+Uses Git to manage the file changes. So your project needs to be a Git repository.
+
+## undo
+Undo last message in the conversation.
+```
+/undo
+
+// keybind
+ctrl+x u
+```
+
+Removes the most recent user message, all subsequent responses, and any file changes.
+
+## sessions
+List and switch between sessions. Aliases: `/resume`, `/continue`
+```
+/resume
+
+// keybind
+ctrl+x l
+```
+
+## themes
+List available themes.
+```
+/themes
+
+// keybind
+ctrl+x t
+```
+
+## thinking
+Toggle the visibility of thinking/reasoning blocks in the conversation. When enabled, you can see the model’s reasoning process for models that support extended thinking.
+```
+/thinking
+```
+
+## share
+Share current session.
+```
+/share
+```
+
+## unshare
+Unshare current session.
+```
+/unshare
+```

package/skills/read-docs/references/opencode/tui/commands/init.md

@@ -0,0 +1,5 @@
+# init
+Guided setup for creating or updating `AGENTS.md`.
+```
+/init
+```

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

@@ -0,0 +1,26 @@
+# TUI
+Using the OpenCode terminal user interface.
+
+```
+opencode
+
+// start with a specific working dir
+opencode /path/to/project
+```
+
+## File references
+Using `@` to reference files in the current working dir.
+- The content of the file is added to the conversation automatically.
+```
+How is auth handled in @packages/functions/src/api/index.ts
+```
+
+
+## Bash commands
+Start with `!` to run a shell command.
+- The output of the command is added to the conversation as a tool result.
+```
+!ls -la
+```
+
+

package/skills/read-docs/references/superpowers/bootstrap.md

@@ -0,0 +1,107 @@
+# Bootstrap 注入机制
+
+## 安装方式
+
+在 opencode 的 `opencode.json` 中注册：
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
+}
+```
+
+或使用本地路径：
+
+```json
+{
+  "plugin": ["~/.config/opencode/node_modules/superpowers"]
+}
+```
+
+## 插件入口
+
+**文件**: `.opencode/plugins/superpowers.js`（`package.json` 的 `"main"`）
+
+插件导出 `SuperpowersPlugin`，接收 `{ client, directory }` 参数，返回两个 hook：
+
+| Hook | 作用 |
+|------|------|
+| `config` | 将 `skills/` 目录注册到 `config.skills.paths`，让 opencode 发现 superpowers 的 14 个技能 |
+| `experimental.chat.messages.transform` | 将 `using-superpowers/SKILL.md` 的内容注入到会话的第一条 user message 前面 |
+
+## Bootstrap 注入逻辑
+
+```javascript
+// .opencode/plugins/superpowers.js (简化)
+
+const getBootstrapContent = () => {
+  // 模块级缓存：SKILL.md 不变，只读一次
+  if (_bootstrapCache !== undefined) return _bootstrapCache
+
+  const skillPath = path.join(skillsDir, 'using-superpowers', 'SKILL.md')
+  const fullContent = fs.readFileSync(skillPath, 'utf8')
+  const { content } = extractAndStripFrontmatter(fullContent)  // 去掉 frontmatter
+
+  _bootstrapCache = `<EXTREMELY_IMPORTANT>
+You have superpowers.
+
+**IMPORTANT: The using-superpowers skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the skill tool to load "using-superpowers" again - that would be redundant.**
+
+${content}
+
+${toolMapping}
+</EXTREMELY_IMPORTANT>`
+  return _bootstrapCache
+}
+
+return {
+  'experimental.chat.messages.transform': async (_input, output) => {
+    const bootstrap = getBootstrapContent()
+    if (!bootstrap || !output.messages.length) return
+
+    const firstUser = output.messages.find(m => m.info.role === 'user')
+    if (!firstUser || !firstUser.parts.length) return
+
+    // 幂等检查：已有注入则跳过
+    if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('EXTREMELY_IMPORTANT'))) return
+
+    // 注入到第一条 user message 的 parts 最前面
+    const ref = firstUser.parts[0]
+    firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap })
+  }
+}
+```
+
+## 关键设计决策
+
+1. **注入到 user message 而非 system message**：避免 system message 在每轮重复导致的 token 膨胀（#750），以及多 system message 破坏 Qwen 等模型的问题（#894）
+2. **模块级缓存**：`messages.transform` 在每个 agent step 都触发（不只是每轮），缓存避免重复磁盘 IO（#1202）
+3. **幂等检查**：通过 `EXTREMELY_IMPORTANT` 标记防止重复注入
+4. **工具映射**：为 opencode 平台生成特定的工具映射表
+
+## 工具映射（opencode 平台）
+
+| 技能中的动作 | opencode 工具 |
+|-------------|--------------|
+| Create or update todos | `todowrite` |
+| `Subagent (general-purpose):` | `task` with `subagent_type: "general"` |
+| Invoke a skill | `skill` 工具 |
+| Read files | `read` |
+| Create, edit, or delete files | `apply_patch` |
+| Run shell commands | `bash` |
+| Search files | `grep`, `glob` |
+| Fetch a URL | `webfetch` |
+
+## 跨平台注入机制
+
+| 平台 | 注入机制 | 触发时机 |
+|------|---------|---------|
+| opencode | `experimental.chat.messages.transform` hook | 每个 agent step |
+| Claude Code | `SessionStart` hook → `additionalContext` | 会话启动/clear/compact |
+| Cursor | `SessionStart` hook → `additional_context` | 会话启动 |
+| Codex | 插件系统 | 插件加载 |
+| Gemini CLI | 扩展系统 | 扩展加载 |
+| Pi | 扩展 + 原生技能 | 会话启动 + compact 后 |
+| Copilot CLI | `additionalContext` (SDK 标准) | 会话启动 |
+
+Claude Code 的 session-start hook 是一个 bash 脚本，读取 `using-superpowers/SKILL.md`，JSON 转义后输出为 `additionalContext`。

package/skills/read-docs/references/superpowers/comparison.md

@@ -0,0 +1,77 @@
+# 与 harness work agent 对比
+
+## 架构对比
+
+| 维度 | Superpowers | harness work agent |
+|------|------------|-------------------|
+| **编排者** | 宿主内置 agent + 技能 prompt | 自定义 `work` agent（`mode: primary`） |
+| **编排指令来源** | `using-superpowers` bootstrap + 技能 | agent 定义文件本身 |
+| **Worker** | 宿主内置 `general-purpose` | 宿主内置 `explore` / `general` |
+| **自定义 agent** | 无 | 7 个（work/extract/revise/query/lint/pyit/pyut） |
+| **技能系统** | 14 个技能，通过 `skill` 工具加载 | harness 自己的技能系统 |
+| **平台** | 跨平台（11+ harness） | 仅 opencode |
+
+## 调度策略对比
+
+| 维度 | Superpowers SDD | work agent |
+|------|----------------|------------|
+| **任务并行** | ❌ 串行（禁止并行实现） | ✅ 允许 ≤5 并行 |
+| **任务大小** | 2-5 分钟/任务 | ≤5 分钟/任务 |
+| **Review** | 每任务两阶段（spec + quality） | 无强制 review |
+| **Fix Loop** | ≤5 轮，含 model escalation | ≤3 轮重规划 |
+| **状态持久化** | Ledger 文件（抗 compaction） | TodoWrite + 摘要 |
+| **上下文传递** | 文件为主（brief/report/diff） | prompt 内联 |
+| **模型选择** | 精细策略（按任务类型选模型） | 不涉及 |
+| **容忍失败** | BLOCKED → 换模型/拆任务/升级 | failed 只记录不中断 |
+
+## 上下文隔离对比
+
+两者都利用 opencode 的子会话隔离（subagent 看不到父会话历史），但策略不同：
+
+| 维度 | Superpowers | work agent |
+|------|------------|------------|
+| **prompt 自包含** | ✅ 必须自包含 | ✅ 必须自包含 |
+| **上下文通过文件** | ✅ brief/report/diff 都是文件 | ❌ 上下文在 prompt 内 |
+| **返回精简** | ✅ ≤15 行摘要，详情写文件 | ✅ 摘要协议 |
+| **摘要格式** | Status + commits + test summary | status + 结论 + 变更 + 阻塞 + 建议 |
+
+## Bootstrap 注入 vs Agent 定义
+
+Superpowers 选择**不定义新 agent**，而是通过 `messages.transform` 注入 bootstrap 指令：
+
+- **优势**：跨平台（同一套技能适用于 Claude Code/Codex/opencode 等），不需要每个平台定义 agent
+- **代价**：bootstrap 内容在每次 agent step 都存在于 context 中（虽然通过注入到 user message 而非 system message 减少了重复）
+- **限制**：无法使用 agent 级别的配置（如 `temperature`、`permission`、`tools` 限制）
+
+harness 的 `work` agent 选择**定义自定义 agent**，获得更精细的控制，但绑定到 opencode 平台。
+
+## 关键设计差异
+
+### Review 策略
+
+Superpowers 的 review 机制比 work agent 更精细：
+- **每任务 review**：spec compliance + code quality 两阶段
+- **Scoped re-review**：fix 后只验证 fix，不重新审查全部
+- **Final review**：全分支审查，最强模型
+- **Adjudication**：controller 在 Round 5 后裁决，每条裁决记入 ledger
+
+### 文件传递
+
+Superpowers 的一个核心创新是**大量使用文件传递上下文**：
+- `task-brief` 脚本提取任务文本到文件
+- implementer 报告写文件
+- `review-package` 脚本生成 diff 包文件
+- Ledger 记录进度到文件
+
+这解决了两个问题：
+1. **Controller context 保护**：大段文本不经过 controller 的 context window
+2. **Compaction 恢复**：文件在 compaction 后仍然存在
+
+### 模型分层
+
+Superpowers 是少数明确实施模型分层策略的系统：
+- 机械实现用便宜模型
+- 判断任务用标准模型
+- 架构/review 用最强模型
+- Fix loop 升级模型
+- Turn count > token price 的洞察

package/skills/read-docs/references/superpowers/context.md

@@ -0,0 +1,71 @@
+# 上下文管理与模型选择
+
+## 文件作为上下文媒介
+
+Superpowers 的核心设计目标之一是**保护 controller 的 context window**：
+
+| 信息 | 传递方式 | 原因 |
+|------|---------|------|
+| 任务详情（brief） | 文件 | 避免粘贴计划全文到 prompt |
+| 实现报告（report） | 文件 | implementer 详情写文件，只返回 ≤15 行摘要 |
+| Review diff | 文件 | `review-package` 生成 diff 包文件，reviewer 一次 Read |
+| Findings | prompt 内联 | 需要精确传递给 fix implementer |
+| Ledger | 文件 | 跨 compaction 持久化 |
+| 上下文/接口 | prompt 内联 | subagent 看不到历史，必须自包含 |
+
+**反模式（被明确禁止）**：
+
+> A real session's dispatch hit 42k chars of which 99% was pasted history. A fresh subagent needs its task, the interfaces it touches, and the global constraints. Nothing else.
+
+## Ledger 机制
+
+Ledger 是 SDD 的状态持久化机制，解决 **compaction 导致上下文丢失** 的问题：
+
+```
+文件: .superpowers/sdd/<plan-name>/progress.md
+
+内容示例:
+# SDD ledger — plan: docs/superpowers/plans/feature-plan.md
+Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)
+Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)
+Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)
+Task 3: parked — magic number — ruling: plan mandates constant, deferred to final review
+Task 3: complete (commits b7c8d9e..e8f9a0b, 1 parked)
+```
+
+**为什么需要 Ledger**：
+
+> Conversation memory does not survive compaction. In real sessions, controllers that lost their place have re-dispatched entire completed task sequences — the single most expensive failure observed.
+
+Ledger 的恢复逻辑：
+- 第一行命名计划文件 → 确认归属
+- `Task <N>: complete` → 已完成，不重新派发
+- 最后一行是 fix round → 中断在 loop 中，从下一轮恢复
+- 第一行命名不同计划 → 别人的 ledger，不动它，重新开始
+
+## Model Selection 策略
+
+| 任务类型 | 模型层级 | 理由 |
+|---------|---------|------|
+| 机械实现（1-2 文件，完整 spec） | 最便宜 | 计划已包含完整代码，只是转录+测试 |
+| 集成/判断（多文件协调） | 标准 | 需要理解跨文件影响 |
+| 架构/设计 | 最强 | 需要设计判断 |
+| Task Reviewer | 按难度选择 | 小 diff 用便宜模型，并发/安全用强模型 |
+| Fix Loop Round 4-5 | 比原 implementer 强一级 | fresh eyes + capability bump |
+| Final Review | 最强 | 全分支审查，最重要 |
+| Scoped Re-review | 便宜-中档 | 只验证 fix，范围小 |
+
+**关键洞察**：
+
+> Turn count beats token price. Wall-clock and context cost scale with how many turns a subagent takes, and the cheapest models routinely take 2-3× the turns on multi-step work — costing more overall.
+
+因此：reviewer 和从 prose 描述工作的 implementer 最低用中档模型；计划文本包含完整代码时才用最便宜模型。
+
+## Subagent 类型
+
+Superpowers 只使用宿主平台的内置 agent，不定义自定义 agent：
+
+| subagent_type | 使用场景 | 来源 |
+|---------------|---------|------|
+| `general-purpose` / `general` | 实现、review、fix | opencode 内置 |
+| `explore` | 代码库探索（brainstorming 阶段） | opencode 内置 |

package/skills/read-docs/references/superpowers/index.md

@@ -0,0 +1,58 @@
+# Superpowers 概述
+
+> 基于 superpowers v6.2.0 源码分析。源码位置：`~/.config/opencode/node_modules/superpowers/`
+
+## 是什么
+
+Superpowers 是一个跨平台的 coding agent 增强插件，通过 **skills（技能）** + **bootstrap 注入** 实现 agent 行为编排。它的核心不是定义新的 agent 类型，而是通过在会话启动时注入一段"元指令"（`using-superpowers`），强制 agent 在执行任何任务前先检查并加载相关技能。
+
+## 核心架构
+
+```
+用户输入
+  │
+  ▼
+┌─────────────────────────────────────────┐
+│  Bootstrap 注入（messages.transform）     │
+│  将 using-superpowers SKILL.md 内容      │
+│  注入到第一条 user message 的 parts 前面  │
+└──────────────────┬──────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────┐
+│  Agent 看到 bootstrap 指令              │
+│  "你有 superpowers，必须先检查技能"       │
+│  │                                      │
+│  ├─ "构建功能" → 加载 brainstorming 技能 │
+│  ├─ "修 bug" → 加载 systematic-debugging│
+│  └─ "执行计划" → 加载 SDD 或 executing   │
+└──────────────────┬──────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────┐
+│  技能驱动的工作流                        │
+│  brainstorming → writing-plans →        │
+│  subagent-driven-development →          │
+│  requesting-code-review →               │
+│  finishing-a-development-branch          │
+└─────────────────────────────────────────┘
+```
+
+## 与 harness work agent 的区别
+
+| 维度 | Superpowers | harness work agent |
+|------|------------|-------------------|
+| 编排者 | 宿主内置 agent + 技能 prompt | 自定义 `work` agent（`mode: primary`） |
+| Worker | 宿主内置 `general-purpose` | 宿主内置 `explore` / `general` |
+| 自定义 agent | 无 | 7 个（work/extract/revise/query/lint/pyit/pyut） |
+| 平台 | 跨平台（11+ harness） | 仅 opencode |
+
+## 模块索引
+
+- [Bootstrap 注入](/superpowers/bootstrap) — 插件加载、messages.transform hook、跨平台注入
+- [技能体系](/superpowers/skills) — 14 个技能、自动触发、Red Flags
+- [主工作流](/superpowers/workflow) — brainstorming → plans → SDD → review → finish
+- [Subagent-Driven Development](/superpowers/sdd) — SDD 核心流程、implementer/reviewer 模板、fix loop
+- [并行派发](/superpowers/parallel) — dispatching-parallel-agents 技能
+- [上下文管理](/superpowers/context) — 文件传递、Ledger、Model Selection
+- [与 work agent 对比](/superpowers/comparison) — 架构、调度策略、上下文隔离的逐项对比

package/skills/read-docs/references/superpowers/parallel.md

@@ -0,0 +1,49 @@
+# 并行派发（dispatching-parallel-agents）
+
+## 与 SDD 的区别
+
+| 维度 | SDD | dispatching-parallel-agents |
+|------|-----|---------------------------|
+| 场景 | 执行计划中的串行任务 | 修复多个独立问题 |
+| 并行 | ❌ 禁止并行实现 | ✅ 核心就是并行 |
+| 任务来源 | 实现计划 | 多个独立失败（不同文件/子系统） |
+| Review | 每任务两阶段 review | 返回后统一验证 |
+| 模型选择 | 精细策略 | 统一用 general-purpose |
+
+## 使用条件
+
+**使用**：
+- 3+ 个独立失败（不同根因）
+- 各问题可独立理解（不需交叉上下文）
+- 无共享状态（不会编辑同一文件）
+
+**不使用**：
+- 失败相关（修一个可能修复其他）
+- 需要理解全局系统状态
+- agent 会互相干扰
+
+## 派发模式
+
+```
+# 3 个独立失败，一条消息 3 个 task 调用
+Subagent (general-purpose): "Fix agent-tool-abort.test.ts failures"
+Subagent (general-purpose): "Fix batch-completion-behavior.test.ts failures"
+Subagent (general-purpose): "Fix tool-approval-race-conditions.test.ts failures"
+# 全部并行执行
+```
+
+> Multiple dispatch calls in one response = parallel execution. One per response = sequential.
+
+## Prompt 结构要求
+
+好的并行 agent prompt：
+1. **Focused** — 一个清晰的问题域
+2. **Self-contained** — 理解问题所需的全部上下文
+3. **Specific about output** — agent 应返回什么
+
+## 返回后验证
+
+1. **Review each summary** — 理解什么变了
+2. **Check for conflicts** — agent 是否编辑了同一代码
+3. **Run full suite** — 验证所有 fix 协同工作
+4. **Spot check** — agent 可能有系统性错误