@wwkit/harness 1.0.9 → 1.0.10

package/skills/read-docs/references/opencode/tools/arguments.md

@@ -0,0 +1,305 @@
+# Arguments
+
+## Zod
+TypeScript-first schema validation with static type inference: `https://zod.dev/`
+
+You can use tool.schema, which is just Zod, to define argument types.
+```ts
+args: {
+  query: tool.schema.string().describe("SQL query to execute")
+}
+```
+
+You can also import Zod directly and return a plain object:
+```ts
+import { z } from "zod"
+
+export default {
+  description: "Tool description",
+  args: {
+    param: z.string().describe("Parameter description"),
+  },
+  async execute(args, context) {
+    // Tool implementation
+    return "result"
+  },
+}
+```
+
+## Example
+Write a tool in Python
+You can write your tools in any language you want. Here’s an example that adds two numbers using Python.
+
+First, create the tool as a Python script:
+```py
+.opencode/tools/add.py
+
+import sys
+
+a = int(sys.argv[1])
+b = int(sys.argv[2])
+print(a + b)
+```
+
+Then create the tool definition that invokes it:
+```ts
+// .opencode/tools/python-add.ts
+import { tool } from "@opencode-ai/plugin"
+import path from "path"
+
+export default tool({
+  description: "Add two numbers using Python",
+  args: {
+    a: tool.schema.number().describe("First number"),
+    b: tool.schema.number().describe("Second number"),
+  },
+  async execute(args, context) {
+    const script = path.join(context.worktree, ".opencode/tools/add.py")
+    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
+    return result.trim()
+  },
+})
+```
+
+## Bun.$ Shell API
+
+OpenCode 内置 Bun 运行时，可在 Tool 中直接使用 `Bun.$` Shell API 执行命令。
+
+### 基础用法
+
+```ts
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Execute shell commands",
+  args: {
+    cmd: tool.schema.string().describe("Command to execute"),
+  },
+  async execute(args, context) {
+    // 获取文本输出
+    const text = await Bun.$`echo ${args.cmd}`.text()
+    return text.trim()
+  },
+})
+```
+
+### 常用方法
+
+```ts
+// 文本输出
+const text = await Bun.$`cat file.txt`.text()
+
+// JSON 输出
+const data = await Bun.$`echo '{"name":"test"}'`.json()
+
+// 二进制数据
+const buffer = await Bun.$`cat image.png`.arrayBuffer()
+
+// 只执行不获取输出
+await Bun.$`mkdir -p ${dir}`
+
+// 检查退出码
+const { exitCode, stdout } = await Bun.$`some-command`
+if (exitCode !== 0) {
+  throw new Error(`Command failed with code ${exitCode}`)
+}
+```
+
+### 变量插值（自动转义）
+
+```ts
+const file = "test.txt"
+const count = 10
+
+// 变量自动转义，防止注入
+await Bun.$`cat ${file}`.text()
+await Bun.$`head -n ${count} ${file}`.text()
+
+// 数组自动展开
+const files = ["a.txt", "b.txt", "c.txt"]
+await Bun.$`cat ${files}`.text()  // => cat a.txt b.txt c.txt
+```
+
+### 错误处理
+
+```ts
+// 捕获错误
+try {
+  await Bun.$`some-command`.text()
+} catch (error) {
+  console.error("Command failed:", error.message)
+}
+
+// 忽略错误
+const result = await Bun.$`some-command`.quiet()
+```
+
+### 管道操作
+
+```ts
+// 管道
+const result = await Bun.$`cat file.txt | grep pattern`.text()
+
+// 流式处理
+const proc = Bun.$`cat large-file.txt`
+const reader = proc.stdout.getReader()
+```
+
+### 实用示例
+
+```ts
+// Git 操作
+export default tool({
+  description: "Get git status",
+  args: {},
+  async execute() {
+    const status = await Bun.$`git status --short`.text()
+    return status || "Working tree clean"
+  },
+})
+
+// 文件操作
+export default tool({
+  description: "Count lines in file",
+  args: {
+    file: tool.schema.string().describe("File path"),
+  },
+  async execute(args) {
+    const count = await Bun.$`wc -l ${args.file}`.text()
+    return `Total lines: ${count.trim()}`
+  },
+})
+
+// 系统信息
+export default tool({
+  description: "Get system info",
+  args: {},
+  async execute() {
+    const [os, arch, cores] = await Promise.all([
+      Bun.$`uname -s`.text(),
+      Bun.$`uname -m`.text(),
+      Bun.$`nproc`.text(),
+    ])
+    return { os: os.trim(), arch: arch.trim(), cores: cores.trim() }
+  },
+})
+
+// 多行脚本
+export default tool({
+  description: "Initialize project structure",
+  args: {
+    name: tool.schema.string().describe("Project name"),
+  },
+  async execute(args) {
+    const result = await Bun.$`
+      mkdir -p ${args.name}/src/components
+      mkdir -p ${args.name}/tests
+      cd ${args.name}
+      touch src/index.ts
+      touch tests/index.test.ts
+      echo "Project ${args.name} initialized"
+    `.text()
+    return result.trim()
+  },
+})
+```
+
+### 传递复杂对象给脚本
+
+命令行参数本质是字符串数组，无法直接传递复杂对象。推荐通过 **stdin** 或 **临时文件** 传递 JSON。
+
+#### 方案1：stdin（推荐）
+
+Tool 通过 stdin 传递 JSON，Python 脚本从 stdin 读取，双方解耦。
+
+```ts
+// Tool 定义
+export default tool({
+  description: "Run Python with config",
+  args: {
+    config: tool.schema.object({
+      name: tool.schema.string(),
+      count: tool.schema.number(),
+      options: tool.schema.object({
+        debug: tool.schema.boolean(),
+      }),
+    }).describe("Configuration object"),
+  },
+  async execute(args) {
+    const proc = Bun.$`python3 script.py`
+    proc.stdin.write(JSON.stringify(args.config))
+    const result = await proc.text()
+    return result.trim()
+  },
+})
+```
+
+```py
+# script.py
+import sys
+import json
+
+# 从 stdin 读取 JSON
+config = json.load(sys.stdin)
+
+print(f"Name: {config['name']}")
+print(f"Count: {config['count']}")
+print(f"Debug: {config['options']['debug']}")
+```
+
+#### 方案2：临时文件
+
+Tool 写入临时文件，Python 从文件读取，适合大对象或需要持久化的场景。
+
+```ts
+export default tool({
+  description: "Run Python with config file",
+  args: {
+    config: tool.schema.object({
+      name: tool.schema.string(),
+      count: tool.schema.number(),
+    }).describe("Configuration object"),
+  },
+  async execute(args) {
+    // 写入临时文件
+    const tmpFile = `/tmp/config-${Date.now()}.json`
+    await Bun.write(tmpFile, JSON.stringify(args.config))
+    
+    // 执行 Python 脚本
+    const result = await Bun.$`python3 script.py --config ${tmpFile}`.text()
+    
+    // 清理临时文件
+    await Bun.$`rm ${tmpFile}`
+    
+    return result.trim()
+  },
+})
+```
+
+```py
+# script.py
+import sys
+import json
+import argparse
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--config", help="Config file path")
+args = parser.parse_args()
+
+# 从文件读取 JSON
+with open(args.config, 'r') as f:
+    config = json.load(f)
+
+print(f"Name: {config['name']}")
+print(f"Count: {config['count']}")
+```
+
+#### 方案对比
+
+| 方案 | 优点 | 缺点 | 适用场景 |
+|------|------|------|---------|
+| **stdin** | 解耦、简单、无需清理 | 无法持久化 | 小对象、一次性传递 |
+| **临时文件** | 可持久化、支持大对象 | 需要清理、文件管理 | 大对象、需要复用 |
+
+**推荐**：优先使用 stdin，简单且解耦。
+```

package/skills/read-docs/references/opencode/tools/context.md

@@ -0,0 +1,18 @@
+# Context in a tool
+Tools receive context about the current session:
+```ts
+// .opencode/tools/project.ts
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Get project information",
+  args: {},
+  async execute(args, context) {
+    // Access context information
+    const { agent, sessionID, messageID, directory, worktree } = context
+    return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}`
+  },
+})
+```
+- Use context.directory for the session working directory. 
+- Use context.worktree for the git worktree root.

package/skills/read-docs/references/opencode/tools/custom.md

@@ -0,0 +1,111 @@
+# 自定义工具
+
+自定义工具是你创建的函数，LLM 可以在对话中调用。
+
+## 创建工具
+
+工具定义为 TypeScript 或 JavaScript 文件，但工具定义可以调用任何语言编写的脚本。
+
+## 位置
+
+- 本地：`.opencode/tools/` 目录
+- 全局：`~/.config/opencode/tools/` 目录
+
+## 使用 tool() 辅助函数
+
+```js
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Query the project database",
+  args: {
+    query: tool.schema.string().describe("SQL query to execute"),
+  },
+  async execute(args) {
+    return `Executed query: ${args.query}`
+  },
+})
+```
+
+文件名即为工具名。
+
+## 单文件多工具
+
+每个导出成为独立工具，命名为 `<filename>_<exportname>`：
+
+```js
+import { tool } from "@opencode-ai/plugin"
+
+export const add = tool({
+  description: "Add two numbers",
+  args: {
+    a: tool.schema.number().describe("First number"),
+    b: tool.schema.number().describe("Second number"),
+  },
+  async execute(args) {
+    return (args.a + args.b).toString()
+  },
+})
+
+export const multiply = tool({
+  description: "Multiply two numbers",
+  args: {
+    a: tool.schema.number().describe("First number"),
+    b: tool.schema.number().describe("Second number"),
+  },
+  async execute(args) {
+    return (args.a * args.b).toString()
+  },
+})
+```
+
+创建两个工具：`math_add` 和 `math_multiply`。
+
+### 参数类型
+
+使用 `tool.schema`（基于 Zod）定义参数类型：
+
+```js
+args: {
+  query: tool.schema.string().describe("SQL query to execute")
+}
+```
+
+也可以直接导入 Zod：
+
+```js
+import { z } from "zod"
+
+export default {
+  description: "Tool description",
+  args: {
+    param: z.string().describe("Parameter description"),
+  },
+  async execute(args, context) {
+    return "result"
+  },
+}
+```
+
+### 上下文信息
+
+工具接收当前会话的上下文：
+
+```js
+import { tool } from "@opencode-ai/plugin"
+
+export default tool({
+  description: "Get project information",
+  args: {},
+  async execute(args, context) {
+    const { agent, sessionID, messageID, directory, worktree } = context
+    return `Agent: ${agent}, Session: ${sessionID}, Directory: ${directory}`
+  },
+})
+```
+
+## 更多内容
+
+- [工具详解](/tools/detail) — 常用类型、取消处理、依赖管理、输出限制
+- [工具示例](/tools/examples) — HTTP API 封装等示例
+- [MCP 服务器](/tools/mcp) — 通过 MCP 添加外部工具

package/skills/read-docs/references/opencode/tools/detail.md

@@ -0,0 +1,104 @@
+# 工具详解
+
+## 常用参数类型
+
+```js
+import { tool } from "@opencode-ai/plugin"
+export default tool({
+  description: "Demo of parameter types",
+  args: {
+    // 字符串
+    name: tool.schema.string().describe("User name"),
+    // 可选参数
+    email: tool.schema.string().email().optional().describe("Optional email"),
+    // 带默认值
+    limit: tool.schema.number().default(10).describe("Max results"),
+    // 枚举
+    status: tool.schema.enum(["pending", "done"]).describe("Task status"),
+    // 布尔
+    verbose: tool.schema.boolean().describe("Enable verbose output"),
+    // 数组
+    tags: tool.schema.array(tool.schema.string()).describe("List of tags"),
+    // 对象
+    config: tool.schema.object({
+      host: tool.schema.string(),
+      port: tool.schema.number(),
+    }).describe("Server config"),
+  },
+  async execute(args) {
+    return JSON.stringify(args, null, 2)
+  },
+})
+```
+
+## 取消操作
+
+当用户取消操作（如按 Ctrl+C）时，abort 信号会被触发。长时间运行的工具应监听此信号：
+
+```js
+// .opencode/tool/long-task.ts
+import { tool } from "@opencode-ai/plugin"
+export default tool({
+  description: "A long-running task",
+  args: {},
+  async execute(args, context) {
+    // 检查是否已取消
+    if (context.abort.aborted) {
+      return "Task cancelled"
+    }
+    // 传递给支持 AbortSignal 的 API
+    const response = await fetch("https://api.example.com/data", {
+      signal: context.abort,
+    })
+    return await response.text()
+  },
+})
+```
+
+## 依赖管理
+
+自定义工具可以使用外部 npm 包，在配置目录添加 `package.json` 声明依赖：
+
+```json
+{
+  "dependencies": {
+    "node-fetch": "^3.0.0",
+    "cheerio": "^1.0.0"
+  }
+}
+```
+
+OpenCode 启动时自动运行 `bun install` 安装依赖：
+
+```js
+// .opencode/tool/scraper.ts
+import { tool } from "@opencode-ai/plugin"
+import * as cheerio from "cheerio"
+export default tool({
+  description: "Extract text from a webpage",
+  args: {
+    url: tool.schema.string().url().describe("URL to scrape"),
+  },
+  async execute(args, context) {
+    const response = await fetch(args.url, { signal: context.abort })
+    const html = await response.text()
+    const $ = cheerio.load(html)
+    return $("body").text().trim()
+  },
+})
+```
+
+## 输出限制
+
+工具返回值会被自动截断以避免上下文溢出：
+
+| 限制 | 值 |
+|------|-----|
+| 最大行数 | 2000 行 |
+| 最大字节 | 50 KB |
+
+超出限制时，OpenCode 会在末尾添加 `...N lines truncated...` 提示。
+
+## 查看工具列表
+
+启动 OpenCode 后，使用 `/tools` 命令查看所有可用工具列表，确认自定义工具出现在列表中。

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

@@ -0,0 +1,71 @@
+# 工具示例
+
+## HTTP API 封装
+
+封装 JIRA API 调用：
+
+```js
+// .opencode/tool/jira.ts
+import { tool } from "@opencode-ai/plugin"
+export const getIssue = tool({
+  description: "Get JIRA issue details by key",
+  args: {
+    key: tool.schema.string().describe("Issue key, e.g. PROJ-123"),
+  },
+  async execute(args, context) {
+    const response = await fetch(
+      `https://your-company.atlassian.net/rest/api/3/issue/${args.key}`,
+      {
+        headers: {
+          Authorization: `Basic ${btoa("email@example.com:API_TOKEN")}`,
+          Accept: "application/json",
+        },
+        signal: context.abort,
+      }
+    )
+    if (!response.ok) {
+      throw new Error(`Failed to fetch issue: ${response.status}`)
+    }
+    const issue = await response.json()
+    return JSON.stringify(issue, null, 2)
+  },
+})
+```
+
+::: warning
+生产环境中，API Token 应从环境变量读取而非硬编码。
+:::
+
+## Python 脚本集成
+
+先用 Python 编写脚本：
+
+```py
+import sys
+
+a = int(sys.argv[1])
+b = int(sys.argv[2])
+print(a + b)
+```
+
+然后创建工具定义调用它：
+
+```js
+import { tool } from "@opencode-ai/plugin"
+import path from "path"
+
+export default tool({
+  description: "Add two numbers using Python",
+  args: {
+    a: tool.schema.number().describe("First number"),
+    b: tool.schema.number().describe("Second number"),
+  },
+  async execute(args, context) {
+    const script = path.join(context.worktree, ".opencode/tools/add.py")
+    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
+    return result.trim()
+  },
+})
+```
+
+这里使用 `Bun.$` 工具运行 Python 脚本。

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

@@ -0,0 +1,56 @@
+# 工具（Tools）
+
+工具允许 LLM 在代码库中执行操作。OpenCode 内置一组工具，也可以通过自定义工具或 MCP 服务器扩展。
+
+默认所有工具启用且无需权限。
+
+自定义工具按键名匹配，如果自定义工具与内置工具同名，自定义工具优先。
+
+## 配置
+
+使用 `permission` 字段控制工具行为：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "deny",
+    "bash": "ask",
+    "webfetch": "allow",
+    // use wildcards
+    "mymcp_*": "ask"
+  }
+}
+```
+
+## 内置工具
+
+| 工具 | 说明 |
+|------|------|
+| bash | 在项目环境中执行 Shell 命令 |
+| edit | 使用精确字符串替换修改现有文件 |
+| write | 创建新文件或覆盖现有文件 |
+| read | 读取代码库中的文件内容 |
+| grep | 使用正则表达式搜索文件内容 |
+| glob | 通过模式匹配查找文件 |
+| lsp | 与 LSP 服务器交互，获取代码智能功能 |
+| apply_patch | 应用补丁到文件 |
+| skill | 加载技能（SKILL.md 文件）并返回其内容 |
+| todowrite | 管理编码会话中的待办列表 |
+| webfetch | 获取网页内容 |
+| websearch | 搜索网络信息（需 OpenCode Provider 或设置 `OPENCODE_ENABLE_EXA` 环境变量） |
+| question | 在执行过程中向用户提问 |
+
+### apply_patch
+apply_patch 是 opencode 的补丁应用工具，用于将 patch/diff 内容批量应用到代码库中。
+核心要点：
+- 权限：受 edit 权限控制，与 edit、write 工具共享同一权限
+- 输入：通过 args.patchText 传入补丁文本（而非 filePath）
+- 路径格式：路径嵌入在补丁文本的标记行中，相对于项目根目录
+- 支持操作：
+  - Add File: src/new-file.ts — 新增文件
+  - Update File: src/existing.ts — 更新文件
+  - Move to: src/renamed.ts — 重命名/移动文件
+  - Delete File: src/obsolete.ts — 删除文件
+- Hook 识别：在 hook 中用 input.tool === "apply_patch" 判断（不是 "patch"）
+简言之：它比 edit 工具更适合批量、多文件的修改场景，可以一次性完成增删改移操作。

package/skills/read-docs/references/opencode/tools/lsp.md

@@ -0,0 +1,26 @@
+# lsp
+Interact with your configured LSP servers to get code intelligence features like definitions, references, hover info, and call hierarchy.
+
+> This tool is only available when `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` (or `OPENCODE_EXPERIMENTAL=true`).
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "lsp": "allow"
+  }
+}
+```
+
+## LSP Servers
+OpenCode can integrate with Language Server Protocol (LSP) servers to use diagnostics as feedback for the agent
+
+### 工作原理
+启用 LSP 后，opencode 打开文件时会：
+- 根据文件扩展名匹配已启用的 LSP 服务器
+- 若服务器未运行则自动启动
+
+### 最佳实践
+LSP 可通过语言服务器的诊断信息帮助 agent 发现和修复问题，但并非总是有益——语言服务器可能失同步、占用内存、因版本/项目而异、拖慢工作流。
+
+许多项目中，直接让 agent 运行 lint/typecheck 等 CLI 工具更佳，避免上述代价。将这些命令写入 AGENTS.md 或 skill 中，以便 agent 知道该运行什么。仅在项目确实受益时启用 LSP。