@wwkit/harness 1.0.8 → 1.0.10

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

@@ -0,0 +1,126 @@
+# 技能（Skills）
+
+技能是通过 `SKILL.md` 定义的可复用行为，让 OpenCode 从仓库或主目录中发现和加载可复用的指令。
+
+技能通过 `skill` 工具按需加载——Agent 看到可用技能列表，需要时加载完整内容。
+
+## 放置技能文件
+
+每个技能一个文件夹，内含 `SKILL.md`。OpenCode 搜索以下位置：
+
+- 项目配置：`.opencode/skills/<name>/SKILL.md`
+- 全局配置：`~/.config/opencode/skills/<name>/SKILL.md`
+
+## 发现机制
+
+对于项目本地路径，OpenCode 从当前工作目录向上遍历直到 Git 工作树根目录，加载 `.opencode/skills/*/SKILL.md`。
+
+全局定义从 `~/.config/opencode/skills/*/SKILL.md` 加载。
+
+## Frontmatter 规范
+
+每个 `SKILL.md` 必须以 YAML frontmatter 开头，仅识别以下字段：
+
+| 字段 | 必需 | 说明 |
+|------|------|------|
+| name | 是 | 正则 `^[a-z0-9]+(-[a-z0-9]+)*$` |
+| description | 是 | 1-1024 字符，需足够具体以便 Agent 正确选择 |
+| license | 否 | 许可证 |
+| compatibility | 否 | 兼容性 |
+| metadata | 否 | 字符串到字符串的映射 |
+
+## 示例
+
+```md
+---
+name: git-release
+description: Create consistent releases and changelogs
+license: MIT
+compatibility: opencode
+metadata:
+  audience: maintainers
+  workflow: github
+---
+
+## What I do
+
+- Draft release notes from merged PRs
+- Propose a version bump
+- Provide a copy-pasteable `gh release create` command
+
+## When to use me
+
+Use this when you are preparing a tagged release.
+Ask clarifying questions if the target versioning scheme is unclear.
+```
+
+## 工具描述
+
+OpenCode 在 `skill` 工具描述中列出可用技能：
+
+```xml
+<available_skills>
+  <skill>
+    <name>git-release</name>
+    <description>Create consistent releases and changelogs</description>
+  </skill>
+</available_skills>
+```
+
+Agent 通过调用工具加载技能：
+
+```
+skill({ name: "git-release" })
+```
+
+## 权限配置
+
+在 `opencode.json` 中使用模式匹配控制技能访问：
+
+| 值 | 说明 |
+|----|------|
+| `allow` | 立即加载技能 |
+| `deny` | 对 Agent 隐藏，拒绝访问 |
+| `ask` | 加载前需用户审批 |
+
+```jsonc
+{
+  "permission": {
+    "skill": {
+      "*": "allow",
+      "pr-review": "allow",
+      "internal-*": "deny",
+      "experimental-*": "ask"
+    }
+  }
+}
+```
+
+## 按 Agent 覆盖权限
+
+为特定 Agent 设置不同的权限：
+
+```md
+---
+permission:
+  skill:
+    "documents-*": "allow"
+---
+```
+
+## 禁用技能工具
+
+完全禁用技能功能：
+
+```md
+---
+tools:
+  skill: false
+---
+```
+
+## 更多内容
+
+- [技能详解](/skills/detail) — 渐进式加载、Description 编写、创建步骤
+- [技能工作流](/skills/workflow) — 5 种工作流模式
+- [技能示例](/skills/examples) — 从简单到复杂的示例

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

@@ -0,0 +1,146 @@
+# 技能工作流
+
+## 模式 1：顺序工作流编排
+
+适用场景：需要按固定顺序执行的多步骤流程。
+
+```md
+---
+name: customer-onboarding
+description: 端到端客户入职工作流。处理账户创建、支付设置、订阅管理。
+  当用户说"入职新客户"、"设置订阅"、"创建账户"时使用。
+---
+# 客户入职工作流
+## 步骤 1：创建账户
+调用 MCP 工具：`create_customer`
+参数：name, email, company
+## 步骤 2：设置支付
+调用 MCP 工具：`setup_payment_method`
+等待：支付方式验证
+## 步骤 3：创建订阅
+调用 MCP 工具：`create_subscription`
+参数：plan_id, customer_id（来自步骤 1）
+## 步骤 4：发送欢迎邮件
+调用 MCP 工具：`send_email`
+模板：welcome_email_template
+## 失败回滚
+如果任何步骤失败：
+1. 记录失败原因
+2. 回滚已创建的资源
+3. 通知管理员
+```
+
+## 模式 2：多 MCP 协调
+
+适用场景：工作流跨多个服务。
+
+```md
+---
+name: design-to-dev
+description: 从设计文件生成开发任务。当用户提到"设计交接"、"Figma 转任务"时使用。
+---
+# 设计到开发交接
+## 阶段 1：设计导出 (Figma MCP)
+1. 从 Figma 导出设计资源
+2. 生成设计规格文档
+3. 创建资源清单
+## 阶段 2：资源存储 (Drive MCP)
+1. 在 Drive 创建项目文件夹
+2. 上传所有资源
+3. 生成分享链接
+## 阶段 3：任务创建 (Linear MCP)
+1. 创建开发任务
+2. 附加资源链接到任务
+3. 分配给工程团队
+## 阶段 4：通知 (Slack MCP)
+1. 在 #engineering 发布交接摘要
+2. 包含资源链接和任务引用
+```
+
+## 模式 3：迭代优化
+
+适用场景：输出质量需要多次改进。
+
+```md
+---
+name: report-generator
+description: 生成高质量报告，自动迭代优化直到达标。
+---
+# 迭代报告生成
+## 初始草稿
+1. 通过 MCP 获取数据
+2. 生成初版报告
+3. 保存到临时文件
+## 质量检查
+运行验证脚本：`scripts/check_report.py`
+检查项：
+- 缺失章节
+- 格式不一致
+- 数据验证错误
+## 优化循环
+WHILE 质量未达标:
+  1. 修复已识别的问题
+  2. 重新生成受影响的章节
+  3. 再次验证
+## 最终定稿
+1. 应用最终格式
+2. 生成摘要
+3. 保存最终版本
+```
+
+## 模式 4：上下文感知工具选择
+
+适用场景：同一目标，根据上下文选择不同工具。
+
+```md
+---
+name: smart-storage
+description: 根据文件类型和用途自动选择最佳存储位置。
+---
+# 智能文件存储
+## 决策树
+1. 检查文件类型和大小
+2. 确定最佳存储位置：
+   - 大文件 (>10MB) → 云存储 MCP
+   - 协作文档 → Notion/Docs MCP
+   - 代码文件 → GitHub MCP
+   - 临时文件 → 本地存储
+## 执行存储
+根据决策：
+- 调用对应的 MCP 工具
+- 应用服务特定的元数据
+- 生成访问链接
+## 用户反馈
+解释为什么选择了那个存储位置
+```
+
+## 模式 5：领域智能
+
+适用场景：技能提供超越工具访问的专业知识。
+
+```md
+---
+name: payment-compliance
+description: 带合规检查的支付处理。当处理跨境支付、大额交易时使用。
+---
+# 合规支付处理
+## 处理前（合规检查）
+1. 通过 MCP 获取交易详情
+2. 应用合规规则：
+   - 检查制裁名单
+   - 验证管辖区允许
+   - 评估风险等级
+3. 记录合规决策
+## 处理
+IF 合规通过:
+    - 调用支付处理 MCP 工具
+    - 应用适当的欺诈检查
+    - 处理交易
+ELSE:
+    - 标记为人工审核
+    - 创建合规案例
+## 审计追踪
+- 记录所有合规检查
+- 记录处理决策
+- 生成审计报告
+```

package/skills/read-docs/references/opencode/tests/agent.md

@@ -0,0 +1,10 @@
+# agent
+## Step1: define a agent
+```
+.opencode\agents\create.md
+```
+
+## Step2: use the agent
+```
+opencode --agent create
+```

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

@@ -0,0 +1,60 @@
+# env config
+
+## Step1: show current settings
+By default, using `~/.config/opencode`
+```
+echo $OPENCODE_CONFIG
+echo $OPENCODE_CONFIG_DIR
+```
+
+## Step2: Create a test command
+Create a command 
+- project dir: `D:\jsapp\wego_oc`
+- config dir: `.opencode\commands\foo.md` 
+
+## Step3.1: config once
+In other dir run:
+
+```
+// Use TUI
+$env:OPENCODE_CONFIG_DIR="D:\jsapp\wego_oc\opencode"; opencode
+```
+
+```
+// Use run
+$env:OPENCODE_CONFIG_DIR="D:/jsapp/wego_oc/opencode"; opencode run --command foo
+```
+
+## Step3.2: config 
+Manage env var in Windows
+```
+// set
+[System.Environment]::SetEnvironmentVariable('OPENCODE_CONFIG_DIR', "D:/jsapp/wego_oc/opencode", 'User')
+
+// check
+[System.Environment]::GetEnvironmentVariable('OPENCODE_CONFIG_DIR', 'User')
+
+// delete
+[System.Environment]::SetEnvironmentVariable('OPENCODE_CONFIG_DIR', $null, 'User')
+```
+
+Windows使用新增环境变量
+- 新开terminal
+- 设置到当前terminal
+  ```
+   $env:OPENCODE_CONFIG_DIR = [System.Environment]::GetEnvironmentVariable('OPENCODE_CONFIG_DIR', 'User')
+  ```
+
+Use opencode
+```
+// TUI
+opencode
+
+// run
+opencode run --command foo
+```
+
+## once setting in a serve
+```
+$env:OPENCODE_CONFIG_DIR="D:\jsapp\wego_oc\opencode"; opencode serve --port 5200
+```

package/skills/read-docs/references/opencode/tests/file.md

@@ -0,0 +1,12 @@
+# file
+## Step1: create a file
+```
+C:\Users\l30026940\Downloads\README.md
+```
+
+## Step2: use this file conent
+必须用`--`把额外信息与`--file`参数分隔，file参数支持连续的多个文件地址
+```
+// only support by run
+opencode run --agent create --file "C:\Users\l30026940\Downloads\README.md" -- "总结为200字以内的摘要，并写入readme-summary.md"
+```

package/skills/read-docs/references/opencode/tests/serve.md

@@ -0,0 +1,18 @@
+# serve
+
+## Step1: start a standalone server
+```
+opencode serve --port 5200
+```
+
+output:
+```
+Warning: OPENCODE_SERVER_PASSWORD is not set; server is unsecured.
+opencode server listening on http://127.0.0.1:5200
+```
+
+## Step2: attach to this server
+In another terminal:
+```
+opencode attach http://127.0.0.1:5200
+```

package/skills/read-docs/references/opencode/tests/session.md

@@ -0,0 +1,31 @@
+# session相关功能测试
+
+## export and import
+
+### Step1: show the sesion id
+
+```
+opencode session list -n 5
+```
+
+output:
+```
+ses_0cadb81d5ffernOJ0n2SD1FZ6S  New session - 2026-07-06T01:56:51.883Z  15:14
+ses_0cadd1cf2ffe2bVpcckQ9ZsQp6  New session - 2026-07-06T01:55:06.637Z  09:55 · 2026/7/6
+...
+```
+
+### Step2: export the latest session
+```
+opencode export ses_0cadb81d5ffernOJ0n2SD1FZ6S > ses_0cadb81d5ffernOJ0n2SD1FZ6S.json
+```
+output:
+```
+Exporting session: ses_0cadb81d5ffernOJ0n2SD1FZ6S
+```
+
+### Step3: import by json
+Open a new terminal and cwd to the same root dir
+```
+opencode import ses_0cadb81d5ffernOJ0n2SD1FZ6S.json
+```

package/skills/read-docs/references/opencode/tests/web.md

@@ -0,0 +1,17 @@
+# web服务验证
+
+## Step1: 启动Web服务
+```
+opencode web --port 5200
+opencode web --port 5200 --hostname localhost --cors http://localhost:5200
+```
+
+output:
+```
+Web interface:      http://127.0.0.1:5200/
+```
+
+## Step2: 浏览器访问
+```
+http://127.0.0.1:5200/
+```