@wwkit/harness 1.0.9 → 1.0.11

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)

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

@@ -0,0 +1,81 @@
+# run
+Run opencode in `non-interactive` mode by passing a prompt directly.
+```
+opencode run [message..]
+```
+
+## run --attach
+You can also attach to a running `opencode serve` instance to avoid MCP server cold boot times on every run:
+```
+opencode serve --port 4096
+opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"
+```
+
+冷启动与attach：
+- `opencode run`每次执行都要：启动进程 → 加载 MCP Server → 初始化模型 → 执行 → 退出。MCP Server 启动可能需要数秒，频繁执行时浪费时间。
+
+解决方案：
+- 终端1：启动常驻服务器（一次性冷启动）
+  ```
+  opencode serve --port 4096
+  ```
+- 终端n：多任务复用同一个服务器（跳过冷启动）
+  ```
+  opencode run --attach http://localhost:4096 "Explain async/await"
+  opencode run --attach http://localhost:4096 "Fix the bug in main.ts"
+  ```
+
+## Flags
+### Model and Perm
+- `--model` `-m` : Model to use in the form of `provider/model`
+- `--auto` : Auto-approve permissions that are not explicitly denied
+
+### Invoke
+- `--command` : The command to run, use message for args
+- `--agent` : Agent to use
+
+### Attach
+- `--attach` : Attach to a running opencode server (e.g., `http://localhost:4096`)
+- `--port` : Port for the local server (defaults to random port)
+- `--password` `-p` : Basic auth password (defaults to `OPENCODE_SERVER_PASSWORD`)
+- `--username` `-u` : Basic auth username (defaults to `OPENCODE_SERVER_USERNAME` or `opencode`)
+
+### IO
+- `--dir` : Directory to run in, or path on the remote server when attaching
+- `--file` `-f` : File(s) to attach to message
+- `--format` : Format: default (formatted) or json (raw JSON events)
+
+### Session
+- `--continue` `-c` : Continue the last session
+- `--session` `-s` : Session ID to continue
+- `--fork` : Fork the session when continuing (use with --continue or --session)
+- `--share` : Share the session
+- `--title` : Title for the session (uses truncated prompt if no value provided)
+
+### Thinking
+- `--variant` : Model variant (provider-specific reasoning effort)
+- `--thinking` : Show thinking blocks
+
+## Fork
+- 原会话不变
+- sessions列表新增一个会话
+- 复制快照后独立发展
+
+## File
+文件内容会作为用户消息的一部分发送给模型。适合指令较长或需要复用的场景。
+```
+// 不需要额外 message
+opencode run -f instructions.md
+
+// 或文件内容 + 简短补充
+opencode run -f instructions.md -- "注意优先处理错误处理部分"
+
+// multi files
+opencode run -f instructions.md instructions.md -- "注意优先处理错误处理部分"
+```
+
+## Variant
+控制模型推理努力程度，类似OpenAI的reasoning effort参数
+- `low` : 低推理，快速响应
+- `medium` : 中等推理（默认）
+- `high` : 高推理（深度思考，适合复杂任务）

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

@@ -0,0 +1,84 @@
+# serve
+Start a headless OpenCode server for API access without the TUI interface.
+```
+opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]
+
+opencode serve --cors http://localhost:5173 --cors https://app.example.com
+```
+
+## Flags
+- `--port` : Port to listen on, default `4096`
+- `--hostname` : Hostname to listen on, default `127.0.0.1` 
+- `--mdns` : Enable mDNS discovery, default `false`
+- `--mdns-domain` : Custom mDNS domain name, default `opencode.local`
+- `--cors` : Additional browser origin to allow CORS, defualt `[]`
+  - can be passed multiple time
+
+## Authentication
+Set `OPENCODE_SERVER_PASSWORD` to protect the server with HTTP basic auth. 
+- The username defaults to `opencode`, or set `OPENCODE_SERVER_USERNAME` to override it. 
+- This applies to both `opencode serve` and `opencode web`.
+
+```
+OPENCODE_SERVER_PASSWORD=your-password opencode serve
+```
+
+## How it works
+When you run opencode it starts a TUI and a server. You can run opencode serve to start a standalone server.
+
+#### Connect to an existing server
+When you start the TUI it randomly assigns a port and hostname. You can instead pass in the `--hostname` and `--port` flags. Then use this to connect to its server.
+
+## Spec
+The server publishes an OpenAPI 3.1 spec that can be viewed at:
+```
+http://<hostname>:<port>/doc
+```
+
+For example, http://localhost:4096/doc. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.
+
+## APIs
+The opencode server exposes the following APIs.
+
+### Global
+- `/global/health` : Get server health and version, `{healthy:true,version:string}`
+- `/global/event` : Get global events (SSE stream)
+
+### Project
+- `/project` : list all projects, `Project[]`
+- `/project/current` : Get the current project, `Project`
+
+### Path & VCS
+- `/path` : Get the current path, `Path`
+- `/vcs` : Get VCS info for the current project, `VcsInfo`
+
+### Instance
+- `/instance/dispose` : Dispose the current instance, `boolean`
+
+## Config
+
+## Provider
+
+## Sessions
+
+## Messages
+
+## Commands
+
+## Files
+
+## Tools
+
+## LSP
+
+## Agents
+
+## Logging
+
+## TUI
+
+## Auth
+
+## Evetns
+
+## Docs

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

@@ -0,0 +1,38 @@
+# session
+Manage sessions
+```
+// list all sessions
+opencode session list
+
+// delete an session
+opencode session delete <sessionID>
+```
+
+## Flags:
+- `--max-count` `-n` : limit to N most recent sessions
+- `--format` : Output format : table or json
+
+# export
+Export session data as JSON
+```
+opencode export [sessionID]
+
+# write to a file
+opencode export ses_0cadb81d5ffernOJ0n2SD1FZ6S > ses_0cadb81d5ffernOJ0n2SD1FZ6S.json
+```
+If you don’t provide a session ID, you’ll be prompted to select from available sessions.
+
+## Flags
+- `--sanitize` : Redact sensitive transcript/file data
+
+# import
+Import session data from a JSON file or share URL.
+```
+opencode import <file>
+
+// local file
+opencode import session.json
+
+// share url
+opencode import https://opncd.ai/s/abc123
+```

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

@@ -0,0 +1,15 @@
+# web
+Start a headless OpenCode server with a web interface.
+```
+opencode web
+```
+This starts an HTTP server and opens a web browser to access OpenCode through a web interface.
+
+Set `OPENCODE_SERVER_PASSWORD` to enable HTTP basic auth (username defaults to `opencode`).
+
+## Flags
+- `--port` :  Port to listen on
+- `--hostname` :  Hostname to listen on
+- `--mdns`
+- `--mdns-domain`
+- `--cors`

package/skills/read-docs/references/opencode/cli/env.md

@@ -0,0 +1,39 @@
+# Environment variables
+OpenCode can be configured using environment variables.
+
+## path
+- `OPENCODE_GIT_BASH_PATH` : `string` Path to git bash executable on Windows
+- `OPENCODE_TUI_CONFIG` : `string` Path to TUI config file
+- `OPENCODE_CONFIG` : `string` Path to config file
+- `OPENCODE_CONFIG_DIR` : `string` Path to config directory
+- `OPENCODE_MODELS_URL` : `string` Custom URL for fetching models configuration
+
+设置`OPENCODE_CONFIG`的会与全局`~/.config/opencode`合并。
+
+## config
+- `OPENCODE_CONFIG_CONTENT` : `string` Inline json config content
+- `OPENCODE_PERMISSION` : `string` Inline json permission config
+
+## session
+- `OPENCODE_AUTO_SHARE` : `boolean` Automatically share sessions
+
+## server
+- `OPENCODE_SERVER_PASSWORD` :	`string`	Enable basic auth for serve/web
+- `OPENCODE_SERVER_USERNAME` : `string`	Override basic auth username (default opencode)
+
+## enable
+- `OPENCODE_ENABLE_EXPERIMENTAL_MODELS` : `boolean` Enable experimental models
+- `OPENCODE_ENABLE_EXA` : `boolean` Enable Exa web search tools
+
+## disable
+- `OPENCODE_DISABLE_AUTOUPDATE` : `boolean` Disable automatic udpate checks
+- `OPENCODE_DISABLE_PRUNE` : `boolean` Disable pruning of old data
+- `OPENCODE_DISABLE_TERMINAL_TITLE` : `boolean` Disable automatic terminal title updates
+- `OPENCODE_DISABLE_DEFAULT_PLUGINS` : `boolean` Disable default plugins
+- `OPENCODE_DISABLE_LSP_DOWNLOAD` : `boolean` Disable automatic LSP server downloads
+- `OPENCODE_DISABLE_AUTOCOMPACT` : `boolean` Disable automatic context compaction
+- `OPENCODE_DISABLE_CLAUDE_CODE` : `boolean` Disable reading from `.claude` (prompt + skills)
+- `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT` : `boolean` Disable reading `~/.claude/CLAUDE.md`
+- `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` : `boolean` Disable loading `.claude/skills`
+- `OPENCODE_DISABLE_MODELS_FETCH` : `boolean` Disable fetching models from remote sources
+- `OPENCODE_DISABLE_MOUSE` : `boolean` Disable mouse capture in the TUI

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

@@ -0,0 +1,19 @@
+# CLI
+OpenCode CLI options and commands.
+
+The OpenCode CLI by default starts the TUI when run without any arguments.
+```
+opencode
+```
+
+But it also accepts commands as documented on this page. This allows you to interact with OpenCode programmatically.
+```
+opencode run "Explain how closures work in JavaScript"
+```
+
+## Global Flags
+- `--help` `-h` : Display help
+- `--version` `-v` : Print version number
+- `--print-logs` : Print logs to stderr
+- `--log-level` : Log Level, DEBUG,INFO,WARN,ERROR
+- `--pure` : Run without external plugins

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

@@ -0,0 +1,35 @@
+# TUI
+The OpenCode CLI by default starts the TUI when run without any arguments.
+```
+opencode
+```
+
+## Flags
+- `--continue` `-c` : Continue the last session
+- `--session` `-s` : Session ID to continue
+- `--model` `-m` : Model to use in the form of `provider/model`
+- `--agent` : 	Agent to use
+- `--auto` : Auto-approve permissions that are not explicitly denied
+
+### --auto
+结合 opencode.json 中的 permission 配置理解：
+```json
+{
+  "permission": {
+    "skill": { "*": "allow" },      // 技能调用：全部允许
+    "agent": { "*": "allow" },      // Agent 调用：全部允许
+    "command": { "*": "deny" }     // 命令执行：拒绝
+  }
+}
+```
+- permission 中设为 "allow" 的 → 始终自动批准
+- permission 中设为 "deny" 的 → 始终拒绝
+- 未在 permission 中配置的 → 默认需手动确认，但 --auto 会将其自动批准
+简单说：--auto = 免确认模式，适合自动化流水线或信任当前操作环境的场景。
+
+### web服务配置
+- `--hostname 0.0.0.0` : Hostname to listen on，默认`localhost`仅本机可访问
+- `--port 8081` : Port to listen on, 默认`3000`
+- `--mdns` : 启动 mDNS 局域网，默认关闭
+- `--mdns-domain opencode.local` : 自定义mDNS域名
+- `--cors http://myapp.com` : 允许跨域浏览器来源，，默认仅本机