@wwkit/harness 1.0.8 → 1.0.10

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

@@ -0,0 +1,71 @@
+# Formatters
+OpenCode can format files after they are written or edited using language-specific formatters.
+
+> Formatters are disabled by default; enable them in your config before OpenCode will run them.
+
+## Built-in
+OpenCode comes with several built-in formatters for popular languages and frameworks.
+- `prettier` : .js, .jsx, .ts, .tsx, .html, .css, .md, .json, .yaml
+- `uv` : .py, .pyi
+- `shfmt` : .sh, .bash
+- `pint` : .php
+
+## How it works
+When OpenCode writes or edits a file and formatters are enabled, it:
+
+1. Checks the file extension against all enabled formatters.
+2. Runs the appropriate formatter command on the file.
+3. Applies the formatting changes.
+
+This process happens in the background for enabled formatters.
+
+## Configure
+You can enable and customize formatters through the formatter section in your OpenCode config.
+
+To enable all built-in formatters, set formatter to true.
+```
+{
+  "$schema": "https://opencode.ai/config.json",
+  "formatter": true
+}
+```
+
+Each formatter configuration supports the following:
+- `disabled` : `boolean` Set this to true to disable the formatter
+- `command` : `string[]` The command to run for formatting. 
+  - Required for custom formatters; 
+  - optional for built-ins.
+- `environment` : `object` Environment variables to set when running the formatter
+- `extensions` : `string[]` File extensions this formatter should handle
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "formatter": {
+    "prettier": {
+      "disabled": true
+    }
+  }
+}
+```
+
+## Custom formatters
+The `$FILE` placeholder in the command will be replaced with the path to the file being formatted.
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "formatter": {
+    "prettier": {
+      "command": ["npx", "prettier", "--write", "$FILE"],
+      "environment": {
+        "NODE_ENV": "development"
+      },
+      "extensions": [".js", ".ts", ".jsx", ".tsx"]
+    },
+    "custom-markdown-formatter": {
+      "command": ["deno", "fmt", "$FILE"],
+      "extensions": [".md"]
+    }
+  }
+}
+```

package/skills/read-docs/references/opencode/guide/config.md

@@ -0,0 +1,419 @@
+# OpenCode 配置
+
+OpenCode 使用 JSON 或 JSONC（带注释的 JSON）配置文件进行配置。
+
+## 配置格式
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "anthropic/claude-sonnet-4-5",
+  "autoupdate": true,
+  "server": {
+    "port": 4096,
+  },
+}
+```
+
+## 配置文件位置
+
+配置文件按以下优先级加载（后者覆盖前者）：
+
+| 优先级 | 位置 | 说明 |
+|--------|------|------|
+| 1 | 远程配置（`.well-known/opencode`） | 组织级默认配置 |
+| 2 | 全局配置（`~/.config/opencode/opencode.json`） | 用户偏好 |
+| 3 | 自定义配置（`OPENCODE_CONFIG` 环境变量） | 自定义覆盖 |
+| 4 | 项目配置（`.opencode/opencode.json`） | 项目级设置 |
+
+### 自定义配置路径
+
+通过 `OPENCODE_CONFIG` 环境变量指定自定义配置文件：
+
+```bash
+export OPENCODE_CONFIG=/path/to/my/custom-config.json
+```
+
+自定义配置在全局配置和项目配置之间加载。
+
+### 自定义配置目录
+
+通过 `OPENCODE_CONFIG_DIR` 环境变量指定自定义配置目录：
+
+```bash
+export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
+```
+
+该目录将按 `.opencode` 目录的标准结构搜索 agents、commands、modes 和 plugins。
+
+## 配置项详解
+
+### Server
+
+配置 `opencode serve` 和 `opencode web` 命令的服务器设置：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "server": {
+    "port": 4096,
+    "hostname": "0.0.0.0",
+    "mdns": true,
+    "mdnsDomain": "myproject.local",
+    "cors": ["http://localhost:5173"]
+  }
+}
+```
+
+### Shell
+
+配置交互式终端使用的 Shell：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "shell": "pwsh"
+}
+```
+
+### Tools
+
+管理 LLM 可使用的工具：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "tools": {
+    "write": false,
+    "bash": false
+  }
+}
+```
+
+### Models
+
+配置使用的 Provider 和模型：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {},
+  "model": "anthropic/claude-sonnet-4-5",
+  "small_model": "anthropic/claude-haiku-4-5"
+}
+```
+
+Provider 选项可包含 `timeout`、`chunkTimeout` 和 `setCacheKey`：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "anthropic": {
+      "options": {
+        "timeout": 600000,
+        "chunkTimeout": 30000,
+        "setCacheKey": true
+      }
+    }
+  }
+}
+```
+
+### Image Attachments
+
+OpenCode 在发送图片前会自动标准化，默认超过 2000x2000 像素或 5242880 base64 字节时自动缩放：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "attachment": {
+    "image": {
+      "auto_resize": true,
+      "max_width": 2000,
+      "max_height": 2000,
+      "max_base64_bytes": 5242880
+    }
+  }
+}
+```
+
+### Agents
+
+配置专门的 Agent 执行特定任务：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "code-reviewer": {
+      "description": "Reviews code for best practices and potential issues",
+      "model": "anthropic/claude-sonnet-4-5",
+      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
+      "tools": {
+        "write": false,
+        "edit": false,
+      },
+    },
+  },
+}
+```
+
+也可以使用 Markdown 文件定义 Agent，放置在 `~/.config/opencode/agents/` 或 `.opencode/agents/`。
+
+### Default Agent
+
+设置默认 Agent：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "default_agent": "plan"
+}
+```
+
+### Sharing
+
+配置分享功能：
+
+| 值 | 说明 |
+|----|------|
+| `manual` | 手动分享（默认） |
+| `auto` | 自动分享新对话 |
+| `disabled` | 禁用分享 |
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "share": "manual"
+}
+```
+
+### Commands
+
+配置自定义命令：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "command": {
+    "test": {
+      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
+      "description": "Run tests with coverage",
+      "agent": "build",
+      "model": "anthropic/claude-haiku-4-5",
+    },
+    "component": {
+      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
+      "description": "Create a new component",
+    },
+  },
+}
+```
+
+也可以使用 Markdown 文件定义命令，放置在 `~/.config/opencode/commands/` 或 `.opencode/commands/`。
+
+### Snapshot
+
+OpenCode 使用快照跟踪 Agent 操作期间的文件变更，支持撤销和恢复。默认启用：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "snapshot": false
+}
+```
+
+### Autoupdate
+
+OpenCode 启动时自动下载更新（默认启用）：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "autoupdate": false
+}
+```
+
+### Formatters
+
+配置代码格式化器，详见 [格式化器](/guide/formatters)。
+
+### LSP Servers
+
+配置 LSP 服务器：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": true
+}
+```
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": {
+    "typescript": {
+      "disabled": true
+    }
+  }
+}
+```
+
+### Permissions
+
+默认允许所有操作，可通过 `permission` 配置审批策略：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "ask",
+    "bash": "ask"
+  }
+}
+```
+
+### Compaction
+
+控制上下文压缩行为：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "compaction": {
+    "auto": true,
+    "prune": true,
+    "reserved": 10000
+  }
+}
+```
+
+### Watcher
+
+配置文件监视器的忽略模式：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "watcher": {
+    "ignore": ["node_modules/**", "dist/**", ".git/**"]
+  }
+}
+```
+
+### MCP Servers
+
+配置 MCP 服务器，详见 [MCP 服务器](/tools/mcp)。
+
+### Plugins
+
+配置插件，详见 [插件](/plugins/)。
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
+}
+```
+
+### Instructions
+
+配置模型的指令文件：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
+}
+```
+
+### Enabled Providers
+
+指定允许使用的 Provider 白名单：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "enabled_providers": ["anthropic", "openai"]
+}
+```
+
+## 变量替换
+
+配置文件支持变量替换。
+
+### 环境变量
+
+使用 `{env:VARIABLE_NAME}` 引用环境变量：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "{env:OPENCODE_MODEL}",
+  "provider": {
+    "anthropic": {
+      "models": {},
+      "options": {
+        "apiKey": "{env:ANTHROPIC_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### 文件内容
+
+使用 `{file:path/to/file}` 引用文件内容（相对于配置文件目录，或以 `/`、`~` 开头的绝对路径）：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["./custom-instructions.md"],
+  "provider": {
+    "openai": {
+      "options": {
+        "apiKey": "{file:~/.secrets/openai-key}"
+      }
+    }
+  }
+}
+```
+
+## TUI 配置
+
+使用独立的 `tui.json`（或 `tui.jsonc`）配置 TUI 界面设置：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "scroll_speed": 3,
+  "scroll_acceleration": {
+    "enabled": true
+  },
+  "diff_style": "auto",
+  "mouse": true,
+  "attention": {
+    "enabled": true,
+    "notifications": true,
+    "sound": true,
+    "volume": 0.4
+  }
+}
+```
+
+通过 `OPENCODE_TUI_CONFIG` 环境变量指定自定义 TUI 配置文件。
+
+### Keybinds
+
+自定义 TUI 键盘快捷键：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "keybinds": {
+    "command_list": "ctrl+p"
+  }
+}
+```

package/skills/read-docs/references/opencode/guide/formatters.md

@@ -0,0 +1,70 @@
+# 格式化器
+
+OpenCode 可以在文件写入或编辑后使用语言特定的格式化器自动格式化代码。
+
+格式化器默认禁用，需在配置中启用。
+
+## 内置格式化器
+
+| 格式化器 | 支持的文件类型 |
+|----------|---------------|
+| prettier | `.js`, `.jsx`, `.ts`, `.tsx`, `.html`, `.css`, `.md`, `.json`, `.yaml` |
+| uv | `.py`, `.pyi` |
+
+启用后，如果项目 `package.json` 中包含 prettier 依赖，OpenCode 将自动使用 prettier 格式化匹配的文件。
+
+## 工作原理
+
+当 OpenCode 写入或编辑文件且格式化器启用时：
+
+1. 检查文件扩展名是否匹配已启用的格式化器
+2. 运行对应的格式化器命令
+3. 应用格式化变更
+4. 此过程在后台自动进行
+
+## 启用格式化器
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "formatter": true
+}
+```
+
+禁用特定格式化器：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "formatter": {
+    "prettier": {
+      "disabled": true
+    }
+  }
+}
+```
+
+## 自定义格式化器
+
+可以配置内置格式化器的选项，或添加自定义格式化器：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "formatter": {
+    "prettier": {
+      "command": ["npx", "prettier", "--write", "$FILE"],
+      "environment": {
+        "NODE_ENV": "development"
+      },
+      "extensions": [".js", ".ts", ".jsx", ".tsx"]
+    },
+    "custom-markdown-formatter": {
+      "command": ["deno", "fmt", "$FILE"],
+      "extensions": [".md"]
+    }
+  }
+}
+```
+
+命令中的 `$FILE` 占位符将被替换为正在格式化的文件路径。

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

@@ -0,0 +1,37 @@
+# OpenCode 指南
+
+OpenCode 是一个 AI 驱动的编码助手，支持自定义配置、技能扩展和多种 AI 模型。
+
+## 快速开始
+
+1. 安装 OpenCode
+2. 运行 `opencode` 启动交互式会话
+3. 使用 `/init` 命令初始化项目配置
+
+## 核心概念
+
+| 概念 | 说明 | 文档 |
+|------|------|------|
+| 配置 | JSON/JSONC 配置文件管理所有设置 | [配置](/guide/config) |
+| 格式化器 | 自动格式化写入和编辑的代码 | [格式化器](/guide/formatters) |
+| Provider | 配置 AI 模型提供商和 API 密钥 | [Provider](/guide/providers) |
+| 规则 | 通过 AGENTS.md 提供自定义指令 | [规则](/guide/rules) |
+| 技能 | 可复用的行为定义（SKILL.md） | [技能](/skills/) |
+| Agent | 专门的 AI 助手 | [Agent](/agents/) |
+| 命令 | 自定义快捷命令 | [命令](/commands/) |
+| 插件 | 扩展 OpenCode 功能 | [插件](/plugins/) |
+| 工具 | LLM 可调用的操作 | [工具](/tools/) |
+
+## 内置 Agent
+
+| Agent | 类型 | 说明 |
+|-------|------|------|
+| build | 主 Agent | 默认 Agent，所有工具启用 |
+| plan | 主 Agent | 规划和分析，文件编辑和 bash 需审批 |
+| general | 子 Agent | 通用多步骤任务，完整工具访问 |
+| explore | 子 Agent | 快速只读代码探索 |
+| scout | 子 Agent | 外部文档和依赖研究 |
+
+## 资源文件
+
+<SrcTree />

package/skills/read-docs/references/opencode/guide/providers.md

@@ -0,0 +1,31 @@
+# Providers
+
+添加 Provider 需要两步：
+
+1. 使用 `/connect` 命令添加 Provider 的 API 密钥
+2. 在 OpenCode 配置中配置 Provider
+
+## 凭证管理
+
+通过 `/connect` 命令添加的 API 密钥存储在 `~/.local/share/opencode/auth.json` 中。
+
+## 配置 Provider
+
+在 OpenCode 配置的 `provider` 部分自定义 Provider：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "anthropic": {
+      "options": {
+        "baseURL": "https://api.anthropic.com/v1"
+      }
+    }
+  }
+}
+```
+
+## OpenCode Zen
+
+OpenCode Zen 是 OpenCode 团队提供的经过测试验证的模型列表，可确保与 OpenCode 良好配合。

package/skills/read-docs/references/opencode/guide/rules.md

@@ -0,0 +1,63 @@
+# 规则（Rules）
+
+通过创建 `AGENTS.md` 文件为 OpenCode 提供自定义指令。
+
+## 初始化
+
+在 OpenCode 中运行 `/init` 命令创建 `AGENTS.md` 文件：
+
+- `/init` 扫描项目中的重要文件，可能提出针对性问题
+- 如果已有 `AGENTS.md`，`/init` 会原地改进而非盲目替换
+
+## 示例
+
+手动创建 `AGENTS.md`：
+
+```md
+# SST v3 Monorepo Project
+
+This is an SST v3 monorepo with TypeScript. The project uses bun workspaces for package management.
+
+## Project Structure
+
+- `packages/` - Contains all workspace packages (functions, core, web, etc.)
+- `infra/` - Infrastructure definitions split by service (storage.ts, api.ts, web.ts)
+- `sst.config.ts` - Main SST configuration with dynamic imports
+
+## Code Standards
+
+- Use TypeScript with strict mode enabled
+- Shared code goes in `packages/core/` with proper exports configuration
+- Functions go in `packages/functions/`
+- Infrastructure should be split into logical files in `infra/`
+
+## Monorepo Conventions
+
+- Import shared modules using workspace names: `@my-app/core/example`
+```
+
+## 项目级规则
+
+在项目根目录放置 `AGENTS.md`，仅对该项目生效。
+
+## 全局规则
+
+在 `~/.config/opencode/AGENTS.md` 放置全局规则，对所有 OpenCode 会话生效。
+
+## 加载优先级
+
+OpenCode 启动时按以下顺序查找规则文件：
+
+1. 本地文件：从当前目录向上遍历查找 `AGENTS.md`
+2. 全局文件：`~/.config/opencode/AGENTS.md`
+
+## 自定义指令文件
+
+在 `opencode.json` 或全局 `~/.config/opencode/opencode.json` 中指定自定义指令文件：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
+}
+```