@wwkit/harness 1.0.8 → 1.0.10

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

@@ -0,0 +1,75 @@
+# 插件示例
+
+## 发送通知
+
+在特定事件发生时发送通知：
+
+```js
+// .opencode/plugins/notification.js
+export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => {
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.idle") {
+        await $`osascript -e 'display notification "Session completed!" with title "opencode"'`
+      }
+    },
+  }
+}
+```
+
+## .env 文件保护
+
+防止 OpenCode 读取 .env 文件：
+
+```js
+// .opencode/plugins/env-protection.js
+export const EnvProtection = async ({ project, client, $, directory, worktree }) => {
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (input.tool === "read" && output.args.filePath.includes(".env")) {
+        throw new Error("Do not read .env files")
+      }
+    },
+  }
+}
+```
+
+## 注入环境变量
+
+向所有 Shell 执行注入环境变量：
+
+```js
+export const InjectEnvPlugin = async () => {
+  return {
+    "shell.env": async (input, output) => {
+      output.env.MY_API_KEY = "secret"
+      output.env.PROJECT_ROOT = input.cwd
+    },
+  }
+}
+```
+
+## 自定义工具
+
+插件也可以向 OpenCode 添加自定义工具：
+
+```js
+import { type Plugin, tool } from "@opencode-ai/plugin"
+
+export const CustomToolsPlugin: Plugin = async (ctx) => {
+  return {
+    tool: {
+      mytool: tool({
+        description: "This is a custom tool",
+        args: {
+          foo: tool.schema.string(),
+        },
+        async execute(args, context) {
+          const { directory, worktree } = context
+          return `Hello ${args.foo} from ${directory} (worktree: ${worktree})`
+        },
+      }),
+    },
+  }
+}
+```

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

@@ -0,0 +1,188 @@
+# 插件（Plugins）
+
+插件通过钩入各种事件和自定义行为来扩展 OpenCode。
+
+## 使用插件
+
+### 从本地文件加载
+
+将 JavaScript 或 TypeScript 文件放在插件目录：
+
+- `.opencode/plugins/` — 项目级插件
+- `~/.config/opencode/plugins/` — 全局插件
+
+这些目录中的文件在启动时自动加载。
+
+### 从 npm 加载
+
+在配置文件中指定 npm 包：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
+}
+```
+
+npm 插件使用 Bun 在启动时自动安装，包及其依赖缓存在 `~/.cache/opencode/node_modules/`。
+
+### 加载顺序
+
+插件从所有来源加载，所有钩子按顺序运行：
+
+1. 全局配置（`~/.config/opencode/opencode.json`）
+2. 项目配置（`opencode.json`）
+3. 全局插件目录（`~/.config/opencode/plugins/`）
+4. 项目插件目录（`.opencode/plugins/`）
+
+同名同版本的 npm 包只加载一次，但本地插件和 npm 插件即使名称相似也会分别加载。
+
+## 创建插件
+
+插件是导出一个或多个插件函数的 JavaScript/TypeScript 模块。每个函数接收上下文对象并返回钩子对象。
+
+### 基本结构
+
+```js
+export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
+  console.log("Plugin initialized!")
+
+  return {
+    // Hook implementations go here
+  }
+}
+```
+
+插件函数接收的参数：
+
+| 参数 | 说明 |
+|------|------|
+| project | 当前项目信息 |
+| directory | 当前工作目录 |
+| worktree | Git 工作树路径 |
+| client | OpenCode SDK 客户端 |
+| $ | Bun 的 Shell API |
+
+### 依赖管理
+
+本地插件和自定义工具可以使用外部 npm 包，在配置目录添加 `package.json`：
+
+```jsonc
+// .opencode/package.json
+{
+  "dependencies": {
+    "shescape": "^2.1.0"
+  }
+}
+```
+
+OpenCode 启动时自动运行 `bun install` 安装依赖：
+
+```js
+// .opencode/plugins/my-plugin.ts
+import { escape } from "shescape"
+
+export const MyPlugin = async (ctx) => {
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (input.tool === "bash") {
+        output.args.command = escape(output.args.command)
+      }
+    },
+  }
+}
+```
+
+## 事件列表
+
+### 命令事件
+
+| 事件 | 说明 |
+|------|------|
+| `command.executed` | 命令执行 |
+
+### 文件事件
+
+| 事件 | 说明 |
+|------|------|
+| `file.edited` | 文件编辑 |
+| `file.watcher.updated` | 文件监视器更新 |
+
+### 安装事件
+
+| 事件 | 说明 |
+|------|------|
+| `installation.updated` | 安装更新 |
+
+### LSP 事件
+
+| 事件 | 说明 |
+|------|------|
+| `lsp.client.diagnostics` | LSP 诊断 |
+| `lsp.updated` | LSP 更新 |
+
+### 消息事件
+
+| 事件 | 说明 |
+|------|------|
+| `message.part.removed` | 消息部分移除 |
+| `message.part.updated` | 消息部分更新 |
+| `message.removed` | 消息移除 |
+| `message.updated` | 消息更新 |
+
+### 权限事件
+
+| 事件 | 说明 |
+|------|------|
+| `permission.asked` | 权限请求 |
+| `permission.replied` | 权限回复 |
+
+### 服务器事件
+
+| 事件 | 说明 |
+|------|------|
+| `server.connected` | 服务器连接 |
+
+### 会话事件
+
+| 事件 | 说明 |
+|------|------|
+| `session.created` | 会话创建 |
+| `session.compacted` | 会话压缩 |
+| `session.deleted` | 会话删除 |
+| `session.diff` | 会话差异 |
+| `session.error` | 会话错误 |
+| `session.idle` | 会话空闲 |
+| `session.status` | 会话状态 |
+| `session.updated` | 会话更新 |
+
+### Shell 事件
+
+| 事件 | 说明 |
+|------|------|
+| `shell.env` | Shell 环境变量 |
+
+### 工具事件
+
+| 事件 | 说明 |
+|------|------|
+| `tool.execute.after` | 工具执行后 |
+| `tool.execute.before` | 工具执行前 |
+
+### TUI 事件
+
+| 事件 | 说明 |
+|------|------|
+| `tui.prompt.append` | TUI 提示追加 |
+| `tui.command.execute` | TUI 命令执行 |
+| `tui.toast.show` | TUI 提示显示 |
+
+### Todo 事件
+
+| 事件 | 说明 |
+|------|------|
+| `todo.updated` | Todo 更新 |
+
+## 更多内容
+
+- [插件示例](/plugins/examples) — 通知、环境保护、自定义工具等示例

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

@@ -0,0 +1,119 @@
+# reference
+Add local directories and Git repositories as project references.
+
+References give OpenCode access to directories outside the current project.Use them to 
+- make documentation, 
+- shared libraries, examples
+- another repository available while you work.
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "references": {
+    "docs": {
+      "path": "../product-docs",
+      "description": "Use for product behavior and documentation conventions",
+    },
+    "sdk": {
+      "repository": "anomalyco/opencode-sdk-js",
+      "branch": "main",
+      "description": "Use for JavaScript SDK implementation details",
+    },
+  },
+}
+```
+
+## Local directories
+Use `path` to reference a local directory, Paths can be:
+- Relative to the *config file* that defines the reference
+- Absolute, such as `/home/user/docs`
+- Relative to your home directory, such as `~/docs`
+```json
+{
+  "references": {
+    "docs": {
+      "path": "../docs",
+    },
+  },
+}
+```
+
+You can also use a string shorthand:
+```json
+{
+  "references": {
+    "docs": "../docs",
+  },
+}
+```
+
+## Git repositories
+Use `repository` to reference a Git repository, accepts:
+- Git URLs, 
+- host/path references, 
+- GitHub owner/repo shorthand. 
+
+```json
+{
+  "references": {
+    "effect": {
+      "repository": "Effect-TS/effect",
+      "branch": "main",
+    },
+  },
+}
+```
+
+The optional `branch` field selects a branch or ref. Without branch, OpenCode uses the repository’s default branch.
+
+You can use string shorthand.
+```json
+{
+  "references": {
+    "effect": "Effect-TS/effect",
+  },
+}
+```
+
+## Describe usage
+Add `description` to explain when an agent should use a reference.
+```json
+{
+  "references": {
+    "design-system": {
+      "path": "../design-system",
+      "description": "Use when implementing UI components or design tokens",
+    },
+  },
+}
+```
+OpenCode includes references with descriptions in agent context. Descriptions should be short and specific enough to distinguish references with similar content. 
+
+## Hide autocomplete entries
+Set `hidden` to true to omit a reference from @ autocomplete in the TUI.
+```json
+{
+  "references": {
+    "internal": {
+      "path": "../internal",
+      "description": "Use for internal implementation details",
+      "hidden": true,
+    },
+  },
+}
+```
+
+## Use references
+Configured references appear in TUI `@` autocomplete. Type `@alias` to attach the reference root, or `@alias/` to search for files inside it.
+```
+Compare this implementation with @sdk/src/client.ts
+```
+
+Agents also receive the resolved paths and descriptions of configured references that have descriptions in their system context, so they can inspect a reference when it is relevant without you attaching it manually.
+
+## Configure fields
+- `path` : local reference dir
+- `repository` : git url, host/path, owener/repo
+- `branch` : optional git branch
+- `description` : guidance desc when to use the reference
+- `hidden` : hide the reference form TUI `@` autocomplete

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

@@ -0,0 +1,78 @@
+# rules
+You can provide custom instructions to opencode by creating an `AGENTS.md` file.
+
+It contains instructions that will be included in the LLM’s context to customize its behavior for your specific project.
+
+## Initialize
+To create a new AGENTS.md file, you can run the `/init` command in opencode.
+
+It focuses on the things future agent sessions are most likely to need:
+- build, lint, and test commands
+- command order and focused verification steps when they matter
+- architecture and repo structure that are not obvious from filenames alone
+- project-specific conventions, setup quirks, and operational gotchas
+
+## Manual
+You can also just create this file manually. 
+```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`
+```
+
+## Location
+####  Project
+Place an AGENTS.md in your project root for project-specific rules.
+
+#### Global
+in a `~/.config/opencode/AGENTS.md` file.
+
+Since this isn’t committed to Git or shared with your team, we recommend using this to specify any personal rules that the LLM should follow.
+
+#### Custom Instructions
+You can specify custom instruction files in your `opencode.json` or the global `~/.config/opencode/opencode.json`.
+
+All instruction files are combined with your AGENTS.md files.
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "instructions": [
+    "CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md",
+    // remote URLs with a 5 second timeout
+    "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"
+  ]
+}
+```
+
+You can teach opencode to read external files by providing explicit instructions in your AGENTS.md. Here’s a practical example:
+```md
+# TypeScript Project Rules
+
+## External File Loading
+
+CRITICAL: When you encounter a file reference (e.g., @rules/general.md), use your Read tool to load it on a need-to-know basis. They're relevant to the SPECIFIC task at hand.
+
+Instructions:
+
+- Do NOT preemptively load all references - use lazy loading based on actual need
+- When loaded, treat content as mandatory instructions that override defaults
+- Follow references recursively when needed
+```

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

@@ -0,0 +1,113 @@
+# 技能详解
+
+## 渐进式加载（Progressive Disclosure）
+
+技能不是把所有内容塞进上下文，而是分层加载：
+
+| 层级 | 内容 | 大小 | 加载时机 |
+|------|------|------|----------|
+| 第一层 | name + description | ~100 词 | 始终可见，判断是否需要加载 |
+| 第二层 | SKILL.md 正文 | 中等 | 任务匹配时加载，包含主要指令 |
+| 第三层 | references/ 目录 | 详细 | 仅在需要具体细节时加载 |
+
+## 目录结构
+
+基本结构：
+
+```
+.opencode/
+└── skill/
+    └── code-review/
+        └── SKILL.md      # 技能定义文件（必须大写）
+```
+
+完整结构：
+
+```
+.opencode/
+└── skill/
+    └── sql-analysis/
+        ├── SKILL.md              # 主文件：工作流程和关键逻辑
+        └── references/           # 详细文档（按需加载）
+            ├── finance.md        # 财务表结构
+            ├── product.md        # 产品表结构
+            └── examples.md       # 查询示例
+```
+
+## Description 编写
+
+Description 是唯一决定技能是否被触发的因素。OpenCode 使用语义理解（不是关键词匹配）来判断任务是否需要某个技能。
+
+### 反面示例
+
+```
+description: 帮助处理文档
+```
+
+### 正面示例
+
+```md
+description: |
+  从 PDF 中提取表格并转换为 CSV 格式，用于数据分析工作流。
+  适用：填写 PDF 表单、批量处理 PDF 文档、提取 PDF 内嵌数据。
+  不适用：简单 PDF 查看、基本格式转换、PDF 编辑。
+```
+
+### Description 模板
+
+```
+description: |
+  [一句话说明核心能力]
+  提供：[该技能包含的资源，如表结构、公式、模板]
+  适用：[触发场景1]、[触发场景2]、[触发场景3]
+  不适用：[边界场景1]、[边界场景2]
+```
+
+### Description 要素
+
+| 要素 | 说明 | 示例 |
+|------|------|------|
+| 具体能力 | 能做什么 | 提取表格、转换格式 |
+| 提供资源 | 包含什么 | 表结构、公式、模板 |
+| 触发场景 | 什么时候用 | 批量处理、表单填写 |
+| 边界限制 | 什么时候不用 | 简单查看 |
+
+## 创建步骤
+
+### 步骤 1：明确需求
+
+在写任何内容之前，回答这些问题：
+
+1. 这个技能解决什么具体问题？→ 明确价值
+2. 什么情况下应该触发？→ 设计 description
+3. 成功的输出是什么样？→ 定义验收标准
+4. 有哪些边缘情况？→ 避免遗漏
+
+### 步骤 2：写 name
+
+简短清晰，反映核心功能。
+
+### 步骤 3：写 description（最重要）
+
+Description 决定触发，是最关键的部分。
+
+### 步骤 4：写主要指令
+
+写作原则：
+
+1. 用 Markdown 结构 — 标题、列表、表格增加可读性
+2. 提供具体示例 — 代码块展示正确用法
+3. 说明不能做什么 — 避免误用
+4. 引用详细文档 — 保持主文件精简
+
+### 步骤 5：测试验证
+
+系统化测试技能，确保在各种场景下都能正常工作。
+
+## 技能 + MCP
+
+| MCP 提供 | 技能提供 |
+|----------|----------|
+| 连接到各种服务（Notion、Linear、GitHub...） | 如何使用这些工具的最佳实践 |
+| 实时数据访问 | 多步骤工作流编排 |
+| 工具调用能力 | 领域专业知识 |

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

@@ -0,0 +1,141 @@
+# 技能示例
+
+## 简单示例：translate
+
+```md
+---
+name: translate
+description: 专业翻译，保留格式和术语。用于翻译技术文档、API 文档、代码注释。
+---
+# 翻译技能
+## 翻译规范
+1. 保持原文格式和段落结构
+2. 专有名词保留原文并标注
+3. 技术术语查阅术语表
+4. 翻译后进行通读润色
+## 输出格式
+翻译结果用代码块包裹;
+对于不确定的翻译，用括号标注原文。
+```
+
+## 简单示例：brand-guidelines
+
+```md
+---
+name: brand-guidelines
+description: 应用公司官方品牌色和排版规范。用于创建需要公司视觉风格的文档、演示文稿、界面设计。
+---
+# 品牌规范技能
+## 颜色
+**主色**：
+- 深色：`#141413` - 主要文字和深色背景
+- 浅色：`#faf9f5` - 浅色背景和深色上的文字
+- 中灰：`#b0aea5` - 次要元素
+**强调色**：
+- 橙色：`#d97757` - 主强调色
+- 蓝色：`#6a9bcc` - 次强调色
+- 绿色：`#788c5d` - 第三强调色
+## 字体
+- **标题**：Poppins（备选 Arial）
+- **正文**：Lora（备选 Georgia）
+## 应用规则
+- 标题（24pt 及以上）使用 Poppins
+- 正文使用 Lora
+- 根据背景智能选择文字颜色
+```
+
+## 中级示例：sql-analysis（含 references/）
+
+`SKILL.md` 只包含工作流程和关键逻辑，详细的表结构放在 `references/` 目录中。
+
+### SKILL.md
+
+```md
+---
+name: sql-analysis
+description: |
+  用于分析业务数据：收入趋势、ARR 计算、客户分群、产品使用、销售管道。
+  提供：公司表结构、指标定义公式、标准过滤器、常用查询模板。
+  适用：需要写 SQL 分析业务数据、理解公司指标定义、查询数据仓库。
+  不适用：数据库管理、DDL 操作、性能调优、通用 SQL 教学。
+---
+# SQL 分析技能
+## 快速工作流程
+当用户请求数据分析时：
+1. **明确需求**
+   - 什么时间范围？（默认当年）
+   - 哪个客户分群？
+   - 这个分析用于什么决策？
+2. **检查现有看板**
+   - 查看 `references/dashboards.md` 是否有现成报表
+   - 如果有，优先引导用户使用
+3. **确定数据源**
+   - 优先使用汇总表而非原始事件数据
+   - 查询前确认表有必需字段
+4. **执行分析**
+   - 应用必需过滤器（排除测试账户等）
+   - 用已知基准验证结果
+## 标准查询过滤器
+所有收入查询必须：
+- 排除测试账户：`WHERE account != 'Test'`
+- 只用完整周期：`WHERE month <= DATE_TRUNC(CURRENT_DATE(), MONTH)`
+## ARR 计算方式
+- 月收入转 ARR：`monthly_revenue * 12`
+- 7 日运行率：`rolling_7d * 52`
+## 详细文档
+需要表结构和查询模式时，参考：
+- **收入与财务** → `references/finance.md`
+- **产品使用** → `references/product.md`
+- **销售管道** → `references/sales.md`
+```
+
+### references/finance.md（第三层）
+
+```md
+# 财务表详细结构
+## monthly_revenue 表
+| 字段 | 类型 | 说明 |
+|-----|------|------|
+| account_id | STRING | 账户 ID |
+| month | DATE | 月份（每月第一天） |
+| mrr | FLOAT | 月度经常性收入 |
+| arr | FLOAT | 年度经常性收入 |
+| segment | STRING | 客户分群 |
+## 常用查询
+### 按分群统计月收入
+```sql
+SELECT 
+  segment,
+  DATE_TRUNC(month, MONTH) as period,
+  SUM(mrr) as total_mrr
+FROM monthly_revenue
+WHERE account_id != 'Test'
+GROUP BY 1, 2
+ORDER BY 2 DESC, 3 DESC
+```
+```
+
+## Anthropic 示例：docx
+
+```md
+---
+name: docx
+description: "文档创建、编辑和分析，支持修订、批注、格式保留和文本提取。当 Claude 需要处理 .docx 文件时使用：(1) 创建新文档 (2) 修改内容 (3) 处理修订 (4) 添加批注"
+license: Proprietary. LICENSE.txt has complete terms
+---
+# DOCX 创建、编辑和分析
+## 概述
+用户可能要求创建、编辑或分析 .docx 文件。.docx 本质上是包含 XML 文件的 ZIP 压缩包。
+## 工作流程决策树
+### 读取/分析内容
+使用下面的"文本提取"或"原始 XML 访问"部分
+### 创建新文档
+使用"创建新 Word 文档"工作流程
+### 编辑现有文档
+- **你自己的文档 + 简单修改**：使用"基础 OOXML 编辑"
+- **别人的文档**：使用**修订工作流程**（推荐默认）
+- **法律、学术、商业、政府文档**：**必须**使用修订工作流程
+## 文本提取
+使用 pandoc 转换为 markdown：
+`pandoc --track-changes=all path-to-file.docx -o output.md`
+```