@wwkit/harness 1.0.9 → 1.0.10

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

@@ -0,0 +1,307 @@
+# 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) — 完整系统设计案例

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

@@ -0,0 +1,161 @@
+# Agent 工作流
+
+## 模式 1：Prompt Chaining（提示链）
+
+将任务分解为顺序执行的步骤，每一步的输出是下一步的输入。
+
+**适用场景**：任务可清晰分解为固定子任务，需要用延迟换取准确性。
+
+```md
+---
+description: 多步骤翻译处理
+mode: subagent
+steps: 10
+---
+# 任务流程
+按以下步骤执行，每步完成后再进行下一步：
+## 步骤 1：直译
+将原文逐句翻译成中文，保持原意。
+## 步骤 2：意译润色
+在直译基础上，调整为通顺的中文表达。
+## 步骤 3：专业术语检查
+检查专业术语是否准确，必要时保留英文。
+## 步骤 4：格式化
+按照目标格式（Markdown）整理输出。
+# 输出要求
+每个步骤都输出中间结果，最后给出最终版本。
+```
+
+## 模式 2：Routing（路由）
+
+根据输入特征，将任务导向不同的专门处理流程。
+
+**适用场景**：不同类别需要不同处理方式，分类可以准确完成。
+
+```md
+---
+description: 代码问题分类路由器
+mode: subagent
+---
+# 角色
+你是代码问题分类专家，负责将问题路由到正确的处理流程。
+# 分类规则
+分析用户的代码问题，判断属于以下哪一类：
+1. **Bug 修复** → 调用 @bug-fixer
+2. **性能优化** → 调用 @performance-optimizer
+3. **安全审计** → 调用 @security-auditor
+4. **代码重构** → 调用 @refactor-expert
+5. **新功能开发** → 不路由，直接处理
+# 输出格式
+先说明分类理由，然后调用相应的 subagent。
+```
+
+## 模式 3：Parallelization（并行化）
+
+多个任务同时执行，最后汇总结果。
+
+**两种变体**：
+- **Sectioning（分片）**：独立子任务并行
+- **Voting（投票）**：同一任务多视角验证
+
+**适用场景**：子任务相互独立，需要多视角提高准确性，时间敏感需要加速。
+
+```md
+---
+description: 代码质量并行检查器
+mode: subagent
+---
+# 任务
+对给定代码同时进行多维度检查。
+# 并行任务
+**同时**调用以下 subagent（使用多个 Task tool 调用）：
+1. @security-auditor - 安全漏洞检查
+2. @performance-reviewer - 性能分析
+3. @style-checker - 代码风格检查
+4. @test-coverage-analyzer - 测试覆盖分析
+# 汇总规则
+收集所有结果后，生成综合报告：
+## 综合评分
+- 安全性：X/10
+- 性能：X/10
+- 代码风格：X/10
+- 测试覆盖：X/10
+- **总分**：X/40
+## 问题汇总
+按严重程度排序所有发现的问题。
+## 优先修复建议
+给出最应该优先处理的 3 个问题。
+```
+
+## 模式 4：Orchestrator-Workers（编排-工人）
+
+中央 LLM（编排器）动态分析任务，将其分解并分配给专门的 Worker Agent。
+
+**适用场景**：无法预测需要哪些子任务，任务复杂度不确定，需要灵活应对。
+
+```md
+---
+description: 项目分析编排器，动态分配分析任务
+mode: primary
+---
+# 角色
+你是项目分析编排器，负责理解用户需求并协调专家团队。
+# 可用专家
+- @architecture-analyst - 架构分析
+- @dependency-auditor - 依赖审计
+- @security-auditor - 安全审计
+- @performance-profiler - 性能分析
+- @docs-reviewer - 文档评审
+- @test-analyzer - 测试分析
+# 工作流程
+1. **理解需求**：分析用户想知道什么
+2. **制定计划**：决定需要调用哪些专家
+3. **执行分析**：调用选定的专家
+4. **整合结果**：汇总所有专家的发现
+5. **给出建议**：基于整体分析给出行动建议
+# 原则
+- 不要过度分析，根据用户需求选择必要的专家
+- 如果用户问题简单，可能不需要任何专家
+```
+
+## 模式 5：Evaluator-Optimizer（评估-优化）
+
+一个 Agent 生成内容，另一个 Agent 评估，循环直到满足标准。
+
+**适用场景**：有明确的评估标准，迭代改进有价值，类似人类的"写作-修改"过程。
+
+```md
+---
+description: 迭代代码优化器
+mode: subagent
+steps: 15
+---
+# 角色
+你是代码优化专家，通过迭代改进代码质量。
+# 优化循环
+## 1. 分析阶段
+- 阅读当前代码
+- 识别可优化点
+- 评估当前质量分数
+## 2. 优化阶段
+- 选择影响最大的优化点
+- 实施优化
+- 确保不破坏功能
+## 3. 验证阶段
+- 运行测试确保功能正常
+- 重新评估质量分数
+## 4. 决策阶段
+- 如果质量分数 >= 8，停止优化
+- 如果质量分数提升 < 0.5，停止
+- 否则，继续下一轮
+# 质量评分标准
+| 分数 | 可读性 | 性能 | 安全性 | 测试覆盖 |
+|------|--------|------|--------|---------|
+| 9-10 | 命名清晰、注释完整 | O(n)或更优 | 无漏洞 | >90% |
+| 7-8 | 命名合理、关键注释 | O(n log n) | 低风险 | 70-90% |
+| 5-6 | 基本可读 | O(n²) | 中风险 | 50-70% |
+| <5 | 难以理解 | O(n³)+ | 高风险 | <50% |
+# 失败处理
+- 测试失败：立即回滚本轮修改，尝试其他方向
+- 步数耗尽：输出当前最佳版本和剩余优化建议
+```

package/skills/read-docs/references/opencode/cli/commands/acp.md

@@ -0,0 +1,32 @@
+# acp
+Start an ACP (Agent Client Protocol) server that communicates via stdin/stdout using nd-JSON. 
+```
+opencode acp
+
+# 指定工作目录
+opencode acp --cwd D:\jsapp\wego_oc
+
+# 用 HTTP 方式
+opencode acp --port 8080 --hostname 0.0.0.0
+```
+
+## Flags
+- `--cwd` : working directory
+- `--port` : Port to listen on
+- `--hostname` : Hostname to listen on
+- `--mdns`
+- `--mdns-domain`
+- `--cors`
+
+## ACP vs MCP
+- mcp : 让Agent调用外部工具
+- acp : 让外部程序调用Agent，适用场景：IDE 插件、CI/CD 流水线、自定义客户端等需要程序化调用 OpenCode Agent 能力的场景。
+
+## apis vs acp
+- apis: OpenAPI3.1 http协议，http rest通信，适合web应用、脚本、通用集成
+- acp: acp协议，stdin/stdout通信，适合IDE插件、Agent编排、流水线
+
+## serve and client
+- `opencode` : 自动启动server，客户端为TUI
+- `opencode serve` : 单独启动server，无客户端，提供 HTTP Rest API
+- `opencode acp` : 单独启动server，无客户端，提供acp

package/skills/read-docs/references/opencode/cli/commands/agent.md

@@ -0,0 +1,16 @@
+## agent
+Manage agents for OpenCode (`create` or `list`).
+```
+opencode agent [command]
+```
+
+Create a new agent with custom configuration.
+```
+opencode agent create
+```
+
+List all available agents.
+```
+opencode agent list
+```
+

package/skills/read-docs/references/opencode/cli/commands/attach.md

@@ -0,0 +1,20 @@
+# attach
+Attach a terminal to an already running OpenCode backend server started via serve or web commands.
+
+```
+opencode attach [url]
+
+// start the backend server for web access
+opencode web --port 4096 --hostname 0.0.0.0
+
+// in another terminal, attach the TUI to the running backend
+opencode attach http://10.20.30.40:4096
+```
+
+Flags
+- `--dir`	Working directory to start TUI in
+- `-c` Continue the last session
+- `-s` Session ID to continue
+- `--fork`	Fork the session when continuing (use with --continue or --session)
+- `-p` Basic auth password (defaults to OPENCODE_SERVER_PASSWORD)
+- `-u` Basic auth username (defaults to OPENCODE_SERVER_USERNAME or opencode)

package/skills/read-docs/references/opencode/cli/commands/mcp.md

@@ -0,0 +1,37 @@
+# mcp
+Manage Model Context Protocol servers.
+```
+opencode mcp [command]
+```
+
+## add
+Add an MCP server to your configuration.
+```
+opencode mcp add
+```
+
+## list
+List all configured MCP servers and their connection status.
+```
+opencode mcp list
+```
+
+## auth
+Authenticate with an OAuth-enabled MCP server.
+```
+opencode mcp auth [name]
+
+opencode mcp auth list
+```
+
+## logout
+Remove OAuth credentials for an MCP server.
+```
+opencode mcp logout [name]
+```
+
+## debug
+Debug OAuth connection issues for an MCP server.
+```
+opencode mcp debug <name>
+```

package/skills/read-docs/references/opencode/cli/commands/others.md

@@ -0,0 +1,49 @@
+# stats
+Show token usage and cost statistics for your sessions.
+```
+opencode stats
+```
+
+## Flags:
+- `--days` : last N days
+- `--tools` : Number of tools to show
+- `--models` : Show model usage breakdown
+- `--project` : Filter by project
+
+# db
+Dtabase tools
+```
+opencode db [query]
+```
+## Flags
+- `--format` : Output format, json or tsv
+
+# debug
+Debugging and troubleshooting tools
+```
+opencode debug [command]
+```
+
+# uninstall
+Uninstall OpenCode and remove all related files.
+```
+opencode uninstall
+```
+
+## Flags
+- `--keep-config` `-c` : Keep config files
+- `--keep-data` `-d` : Keep session data and snapshots
+- `--dry-run` : Show what would be removed without removing
+- `--force` `-f` : Skip confirmation prompts
+
+# upgrade
+Updates opencode to the latest version or a specific version
+```
+// latest
+opencode upgrade
+
+// specific
+opencode upgrade v0.1.48
+```
+## Flags
+- `--method` `-m` : The installation method, curl/npm/pnmp/bun/brew

package/skills/read-docs/references/opencode/cli/commands/plugin.md

@@ -0,0 +1,13 @@
+# plugin
+Install a plugin and update your config.
+
+```
+opencode plugin <module>
+
+// alias
+opencode plug <module>
+```
+
+## Flags
+- `--global` `-g` : Install in global config
+- `--force` `-f` : Replace existing plugin version

package/skills/read-docs/references/opencode/cli/commands/provider.md

@@ -0,0 +1,44 @@
+# auth
+Command to manage credentials and login for providers.
+```
+opencode auth [command]
+```
+
+## login
+
+OpenCode is powered by the provider list at Models.dev, so you can use opencode auth login to configure API keys for any provider you’d like to use. This is stored in ~/.local/share/opencode/auth.json.
+
+```
+opencode auth login
+```
+
+When OpenCode starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a .env file in your project.
+
+Flags
+- `--provider` `-p` : Provider ID or name to log in to
+- `--method` `-m` : Login method label to use, skipping method selection
+
+## list
+Lists all the authenticated providers as stored in the credentials file.
+```
+opencode auth list
+opencode auth ls
+```
+
+## logout
+Logs you out of a provider by clearing it from the credentials file.
+```
+opencode auth logout
+```
+
+# models
+List all available models from configured providers in the format provider/model.
+```
+opencode models [provider]
+
+opencode models anthropic
+```
+
+## Flags
+- `--refresh` : Refresh the models cache form models.dev
+- `--verbose` : Use more verbose model output (includes metadata like costs)