@wwkit/harness 1.0.9 → 1.0.10

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` : 允许跨域浏览器来源，，默认仅本机

package/skills/read-docs/references/opencode/commands/examples.md

@@ -0,0 +1,42 @@
+# 命令示例
+
+## review — 代码审查
+
+位置：`.opencode/command/review.md`，执行：`/review src/main.ts`
+
+```md
+---
+description: 审查指定文件的代码质量
+agent: plan
+---
+@$1
+请审查这个文件的代码质量，重点关注：
+1. 代码规范和命名
+2. 潜在 Bug
+3. 性能问题
+4. 可维护性
+```
+
+## commit — 生成提交消息
+
+```md
+---
+description: 根据变更生成 Commit 消息
+---
+根据以下变更生成 commit 消息：
+!`git diff --staged`
+要求：
+- 遵循 Conventional Commits 规范
+- 简洁明了，说明"为什么"而非"做了什么"
+```
+
+## translate — 翻译为中文
+
+```md
+---
+description: 翻译为中文
+subtask: true
+---
+请将以下内容翻译为中文：
+$ARGUMENTS
+```

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

@@ -0,0 +1,185 @@
+# 命令（Commands）
+
+自定义命令让你在 TUI 中执行预设的提示词：
+
+```
+/my-command
+```
+
+可以通过 OpenCode 配置或在 `commands/` 目录创建 Markdown 文件添加自定义命令。
+
+## 创建命令文件
+
+在 `commands/` 目录创建 Markdown 文件：
+
+- 全局：`~/.config/opencode/commands/`
+- 项目级：`.opencode/commands/`
+
+```md
+---
+description: Run tests with coverage
+agent: build
+model: anthropic/claude-3-5-sonnet-20241022
+---
+
+Run the full test suite with coverage report and show any failures.
+Focus on the failing tests and suggest fixes.
+```
+
+Frontmatter 定义命令属性，正文内容成为模板。
+
+使用命令：
+
+```
+/test
+```
+
+## 提示词配置
+
+### 参数传递
+
+使用 `$ARGUMENTS` 占位符传递参数：
+
+```md
+---
+description: Create a new component
+---
+
+Create a new React component named $ARGUMENTS with TypeScript support.
+Include proper typing and basic structure.
+```
+
+运行：
+
+```
+/component Button
+```
+
+使用位置参数：
+
+- `$1`：第一个参数
+- `$2`：第二个参数
+- 以此类推
+
+```md
+---
+description: Create a new file with content
+---
+
+Create a file named $1 in the directory $2
+with the following content: $3
+```
+
+运行：
+
+```
+/create-file config.json src "{ \"key\": \"value\" }"
+```
+
+### Shell 输出
+
+使用 `` !`command` `` 注入 bash 命令输出：
+
+```md
+---
+description: Analyze test coverage
+---
+
+Here are the current test results:
+!`npm test`
+
+Based on these results, suggest improvements to increase coverage.
+```
+
+### 文件引用
+
+使用 `@` 引用文件：
+
+```md
+---
+description: Review component
+---
+
+Review the component in @src/components/Button.tsx.
+Check for performance issues and suggest improvements.
+```
+
+## 配置选项
+
+### Template（必需）
+
+定义命令执行时发送给 LLM 的提示词：
+
+```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
+
+命令的简要描述，在 TUI 中输入命令时显示：
+
+```jsonc
+{
+  "command": {
+    "test": {
+      "description": "Run tests with coverage"
+    }
+  }
+}
+```
+
+### Agent
+
+指定执行此命令的 Agent（可选，默认为当前 Agent）：
+
+```jsonc
+{
+  "command": {
+    "review": {
+      "agent": "plan"
+    }
+  }
+}
+```
+
+### Subtask
+
+强制命令触发子代理调用：
+
+```jsonc
+{
+  "command": {
+    "analyze": {
+      "subtask": true
+    }
+  }
+}
+```
+
+### Model
+
+覆盖命令的默认模型：
+
+```jsonc
+{
+  "command": {
+    "analyze": {
+      "model": "anthropic/claude-3-5-sonnet-20241022"
+    }
+  }
+}
+```
+
+## 内置命令
+
+OpenCode 包含以下内置命令：`/init`、`/undo`、`/redo`、`/share`、`/help`。
+
+## 更多内容
+
+- [命令示例](/commands/examples) — 实用命令示例

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

@@ -0,0 +1,152 @@
+# Providers
+To add a provider you need to:
+- Add the API keys for the provider using the `/connect` command.
+- Configure the provider in your OpenCode config.
+
+## Credentials
+When you add a provider’s API keys with the `/connect` command, they are stored in `~/.local/share/opencode/auth.json`.
+
+## Config
+You can customize the providers through the provider section in your OpenCode config.
+
+### Base URL
+You can customize the base URL for any provider by setting the baseURL option. 
+- This is useful when using proxy services or custom endpoints.
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "anthropic": {
+      "options": {
+        "baseURL": "https://api.anthropic.com/v1"
+      }
+    }
+  }
+}
+```
+
+### Hiding models
+Both options take an array of model IDs — the same IDs shown in the `/models` picker.
+- `blacklist` removes the listed models from the picker.
+- `whitelist` keeps only the listed models and hides the rest.
+
+You can combine them: whitelist narrows the set, then blacklist removes entries from it.
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "anthropic": {
+      "blacklist": ["claude-opus-4-20250514"],
+      "whitelist": ["claude-sonnet-4-20250514"]
+    }
+  }
+}
+```
+
+## OpenCode Zen
+OpenCode Zen is a list of models provided by the OpenCode team that have been tested and verified to work well with OpenCode.
+
+
+Run the /connect command in the TUI, select OpenCode Zen, and head to opencode.ai/auth.
+```
+/connect
+```
+
+Run /models in the TUI to see the list of models we recommend.
+```
+/models
+```
+
+## OpenCode Go
+OpenCode Go is a low cost subscription plan that provides reliable access to popular open coding models provided by the OpenCode team that have been tested and verified to work well with OpenCode.
+
+
+## Custom provider
+To add any OpenAI-compatible provider that’s not listed in the /connect command.
+
+Create or update your opencode.json file in your project directory:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "myprovider": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "My AI ProviderDisplay Name",
+      "options": {
+        "baseURL": "https://api.myprovider.com/v1"
+      },
+      "models": {
+        "my-model-name": {
+          "name": "My Model Display Name"
+        }
+      }
+    }
+  }
+}
+```
+
+Configuration options:
+- npm: AI SDK package to use:
+  - `@ai-sdk/openai-compatible` for OpenAI-compatible providers (for `/v1/chat/completions`).
+  - `@ai-sdk/openai` for `/v1/responses`
+- name: Display name in UI.
+- models: Available models.
+- options.baseURL: API endpoint URL.
+- options.apiKey: Optionally set the API key, if not using auth.
+  - support `env` variable syntax
+- options.headers: Optionally set custom headers.
+- limit.context: Maximum input tokens the model accepts.
+- limit.output: Maximum tokens the model can generate.
+
+### Demo 1:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "llmproxy": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "llmproxy",
+      "options": {
+        "baseURL": "http://127.0.0.1:31943/v1",
+        "apiKey": "sk-123",
+        "headers":{}
+      },
+      "models": {
+        "MiniMax-M2.7": {
+          "name": "MiniMax-M2.7"
+        },
+      }
+    }
+  },
+}
+```
+
+### Demo 2:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "myprovider": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "My AI ProviderDisplay Name",
+      "options": {
+        "baseURL": "https://api.myprovider.com/v1",
+        "apiKey": "{env:ANTHROPIC_API_KEY}",
+        "headers": {
+          "Authorization": "Bearer custom-token"
+        }
+      },
+      "models": {
+        "my-model-name": {
+          "name": "My Model Display Name",
+          "limit": {
+            "context": 200000,
+            "output": 65536
+          }
+        }
+      }
+    }
+  }
+}
+```