@wwkit/harness 1.0.9 → 1.0.10

package/skills/read-docs/references/opencode/train/skill-basic.md

@@ -0,0 +1,608 @@
+# 技能创建培训
+
+学习创建 OpenCode 技能（Skill），实现可复用的 AI 工作流。
+
+## 理论介绍
+
+### 什么是技能（Skill）？
+
+技能是通过 `SKILL.md` 定义的可复用行为，让 Agent 按照预设工作流程执行任务。
+
+**核心特点**：
+- **可复用**：一次定义，多处使用
+- **按需加载**：Agent 需要时才加载完整内容
+- **渐进式**：先展示描述，后加载详情
+- **可扩展**：支持 references 目录存放详细文档
+
+### 技能文件结构
+
+```
+.opencode/skills/
+└── my-skill/
+    ├── SKILL.md           # 必需：技能定义文件
+    └── references/        # 可选：详细文档目录
+        ├── guide.md
+        └── examples.md
+```
+
+### 技能发现机制
+
+OpenCode 搜索以下位置：
+- **项目配置**：`.opencode/skills/<name>/SKILL.md`
+- **全局配置**：`~/.config/opencode/skills/<name>/SKILL.md`
+
+从当前工作目录向上遍历直到 Git 工作树根目录。
+
+### 技能加载流程
+
+```
+用户请求 → Agent 看到技能列表 → 选择合适技能 → 加载 SKILL.md → 执行工作流
+```
+
+**渐进式加载**：
+1. Agent 先看到技能名称和描述
+2. 调用 `skill` 工具加载完整内容
+3. 按工作流执行任务
+
+## SKILL.md 结构
+
+### Frontmatter 规范
+
+每个 `SKILL.md` 必须以 YAML frontmatter 开头：
+
+```yaml
+---
+name: skill-name            # 必需：正则 ^[a-z0-9]+(-[a-z0-9]+)*$
+description: 技能描述        # 必需：1-1024 字符，需足够具体
+license: MIT                # 可选：许可证
+compatibility: opencode     # 可选：兼容性
+metadata:                   # 可选：元数据
+  audience: developers
+  workflow: git
+---
+```
+
+### Description 编写原则
+
+**好的描述**：
+- ✅ 说明技能做什么
+- ✅ 说明适用场景
+- ✅ 说明不适用场景
+- ✅ 提供关键特性
+
+**示例**：
+```yaml
+description: |
+  用于分析业务数据：收入趋势、ARR 计算、客户分群。
+  提供：公司表结构、指标定义公式、标准过滤器。
+  适用：需要写 SQL 分析业务数据、理解公司指标定义。
+  不适用：数据库管理、DDL 操作、性能调优。
+```
+
+### 正文结构
+
+推荐结构：
+```markdown
+# 技能标题
+
+## 工作流程
+1. 明确需求
+2. 执行步骤
+3. 验证结果
+
+## 关键规则
+- 必须遵守的规则
+- 常见错误避免
+
+## 详细文档
+需要详细信息时参考 references/
+```
+
+## 实例展示
+
+### 案例 1：翻译技能（简单）
+
+创建 `.opencode/skills/translate/SKILL.md`：
+
+```markdown
+---
+name: translate
+description: 专业翻译技能，保留格式和术语。用于翻译技术文档、API 文档、代码注释。
+---
+
+# 翻译技能
+
+## 翻译规范
+
+1. **保持格式**：保留原文的段落结构和 Markdown 格式
+2. **术语处理**：专有名词保留原文并标注，如 "API（应用程序接口）"
+3. **技术术语**：查阅术语表或保留英文
+4. **润色通读**：翻译后进行通读润色
+
+## 输出格式
+
+翻译结果用代码块包裹：
+
+```
+翻译内容...
+```
+
+对于不确定的翻译，用括号标注原文：
+
+```
+原文术语（Original Term）
+```
+
+## 注意事项
+
+- ❌ 不要翻译代码块中的代码
+- ❌ 不要翻译 URL 和路径
+- ✅ 保持原文的专业性和准确性
+```
+
+**使用方式**：
+```
+用户：帮我翻译 README.md
+Agent：加载 translate 技能 → 按规范翻译 → 输出结果
+```
+
+### 案例 2：代码审查技能（中级）
+
+创建 `.opencode/skills/code-review/SKILL.md`：
+
+```markdown
+---
+name: code-review
+description: |
+  代码质量审查技能，检查代码规范、安全性、性能问题。
+  提供：审查清单、常见问题库、修复建议模板。
+  适用：PR 审查、代码质量检查、最佳实践验证。
+  不适用：功能实现、Bug 修复、性能优化实施。
+---
+
+# 代码审查技能
+
+## 审查工作流
+
+当用户请求代码审查时：
+
+### 1. 明确审查范围
+
+询问用户：
+- 审查哪些文件或目录？
+- 关注哪些方面？（安全/性能/规范/全部）
+- 有特定的审查标准吗？
+
+### 2. 执行审查
+
+按照审查清单逐项检查：
+
+#### 代码规范
+- ✅ 命名规范：变量、函数、类名是否符合约定
+- ✅ 格式规范：缩进、空格、换行是否统一
+- ✅ 注释规范：关键逻辑是否有注释
+
+#### 安全性
+- ✅ 输入验证：是否有未验证的用户输入
+- ✅ 权限检查：敏感操作是否有权限验证
+- ✅ 数据泄露：是否暴露敏感信息
+
+#### 性能
+- ✅ 算法效率：是否有明显的性能问题
+- ✅ 资源管理：是否有内存泄漏风险
+- ✅ 数据库查询：是否有 N+1 查询问题
+
+### 3. 输出审查报告
+
+格式：
+
+```markdown
+## 审查摘要
+
+- 审查文件：[文件列表]
+- 发现问题：[问题数量]
+- 严重程度：[高/中/低]
+
+## 详细问题
+
+### 问题 1：[问题标题]
+- **文件**：src/file.js:123
+- **严重程度**：高
+- **问题描述**：...
+- **修复建议**：...
+
+### 问题 2：...
+```
+
+## 审查清单
+
+详细清单见 `references/checklist.md`
+
+## 常见问题库
+
+常见问题及修复见 `references/common-issues.md`
+```
+
+创建 `references/checklist.md`：
+
+```markdown
+# 代码审查清单
+
+## JavaScript/TypeScript 规范
+
+### 命名规范
+- [ ] 变量使用 camelCase
+- [ ] 常量使用 UPPER_CASE
+- [ ] 类名使用 PascalCase
+- [ ] 私有属性使用 _前缀或 #前缀
+
+### 格式规范
+- [ ] 使用 2 空格缩进
+- [ ] 使用单引号或双引号统一
+- [ ] 语句末尾分号统一
+- [ ] 每行最大长度不超过 100 字符
+
+### 安全性
+- [ ] 避免 eval() 和 Function()
+- [ ] 验证用户输入
+- [ ] 避免硬编码密钥和密码
+- [ ] 使用 HTTPS 传输敏感数据
+
+## 性能检查
+
+- [ ] 避免深层嵌套循环
+- [ ] 使用防抖/节流处理高频事件
+- [ ] 避免在循环中创建函数
+- [ ] 合理使用缓存
+```
+
+**使用方式**：
+```
+用户：审查 src/components/ 目录
+Agent：加载 code-review 技能 → 按清单审查 → 输出报告
+```
+
+### 案例 3：SQL 分析技能（高级）
+
+创建 `.opencode/skills/sql-analysis/SKILL.md`：
+
+```markdown
+---
+name: sql-analysis
+description: |
+  用于分析业务数据：收入趋势、ARR 计算、客户分群、产品使用、销售管道。
+  提供：公司表结构、指标定义公式、标准过滤器、常用查询模板。
+  适用：需要写 SQL 分析业务数据、理解公司指标定义、查询数据仓库。
+  不适用：数据库管理、DDL 操作、性能调优、通用 SQL 教学。
+---
+
+# SQL 分析技能
+
+## 快速工作流程
+
+当用户请求数据分析时：
+
+### 1. 明确需求
+
+询问用户：
+- 什么时间范围？（默认当年）
+- 哪个客户分群？
+- 这个分析用于什么决策？
+
+### 2. 检查现有看板
+
+查看 `references/dashboards.md` 是否有现成报表。
+如果有，优先引导用户使用。
+
+### 3. 确定数据源
+
+- 优先使用汇总表而非原始事件数据
+- 查询前确认表有必需字段
+- 参考 `references/tables.md` 查看表结构
+
+### 4. 执行分析
+
+- 应用必需过滤器（排除测试账户等）
+- 用已知基准验证结果
+- 使用标准查询模板
+
+## 标准查询过滤器
+
+所有收入查询必须：
+```sql
+WHERE account != 'Test'          -- 排除测试账户
+  AND 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`：
+
+```markdown
+# 财务表详细结构
+
+## 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'
+  AND month <= DATE_TRUNC(CURRENT_DATE(), MONTH)
+GROUP BY 1, 2
+ORDER BY 2 DESC, 3 DESC
+```
+
+### ARR 增长趋势
+
+```sql
+SELECT 
+  month,
+  SUM(arr) as total_arr,
+  LAG(SUM(arr)) OVER (ORDER BY month) as prev_arr,
+  (SUM(arr) - LAG(SUM(arr)) OVER (ORDER BY month)) / 
+    LAG(SUM(arr)) OVER (ORDER BY month) * 100 as growth_rate
+FROM monthly_revenue
+WHERE account_id != 'Test'
+GROUP BY 1
+ORDER BY 1 DESC
+LIMIT 12
+```
+```
+
+**使用方式**：
+```
+用户：分析本年度 ARR 增长趋势
+Agent：加载 sql-analysis 技能 → 查看 finance.md → 编写查询 → 输出结果
+```
+
+### 案例 4：品牌规范技能（设计）
+
+创建 `.opencode/skills/brand-guidelines/SKILL.md`：
+
+```markdown
+---
+name: brand-guidelines
+description: |
+  应用公司官方品牌色和排版规范。用于创建需要公司视觉风格的文档、演示文稿、界面设计。
+  提供：品牌色板、字体规范、应用规则、设计模板。
+  适用：创建品牌文档、设计 UI、制作演示文稿。
+  不适用：非品牌项目、个人项目、实验性设计。
+---
+
+# 品牌规范技能
+
+## 颜色规范
+
+### 主色
+
+| 名称 | 色值 | 用途 |
+|------|------|------|
+| 深色 | `#141413` | 主要文字和深色背景 |
+| 浅色 | `#faf9f5` | 浅色背景和深色上的文字 |
+| 中灰 | `#b0aea5` | 次要元素 |
+
+### 强调色
+
+| 名称 | 艅值 | 用途 |
+|------|------|------|
+| 橙色 | `#d97757` | 主强调色，按钮、链接 |
+| 蓝色 | `#6a9bcc` | 次强调色，辅助信息 |
+| 绿色 | `#788c5d` | 第三强调色，成功状态 |
+
+## 字体规范
+
+| 类型 | 字体 | 备选 | 用途 |
+|------|------|------|------|
+| 标题 | Poppins | Arial | 标题（24pt 及以上） |
+| 正文 | Lora | Georgia | 正文内容 |
+
+## 应用规则
+
+1. **标题字体**：24pt 及以上使用 Poppins
+2. **正文字体**：使用 Lora
+3. **文字颜色**：根据背景智能选择
+   - 深色背景 → 浅色文字
+   - 浅色背景 → 深色文字
+
+## 设计模板
+
+详细模板见 `references/templates.md`
+```
+
+**使用方式**：
+```
+用户：创建产品介绍文档，使用品牌风格
+Agent：加载 brand-guidelines 技能 → 应用颜色和字体 → 创建文档
+```
+
+## 技能权限配置
+
+### 在配置文件中控制
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "skill": {
+      "*": "allow",              // 默认允许所有技能
+      "translate": "allow",      // 允许翻译技能
+      "internal-*": "deny",      // 禁用内部技能
+      "experimental-*": "ask"    // 实验性技能需审批
+    }
+  }
+}
+```
+
+### 在 Agent 中覆盖
+
+```markdown
+---
+permission:
+  skill:
+    "documents-*": "allow"
+    "experimental-*": "deny"
+---
+```
+
+### 禁用技能工具
+
+```markdown
+---
+tools:
+  skill: false
+---
+```
+
+## 动手练习
+
+### 练习 1：创建简单技能
+
+**任务**：创建一个格式化技能，统一代码格式
+
+**提示**：
+```markdown
+---
+name: format-code
+description: |
+  统一代码格式化技能，应用团队编码规范。
+  提供：格式化规则、ESLint 配置、Prettier 配置。
+---
+
+# 格式化技能
+
+## 格式化规则
+
+1. 使用 2 空格缩进
+2. 使用单引号
+3. 语句末尾无分号
+4. ...
+
+## 执行步骤
+
+1. 检查现有格式
+2. 应用格式化规则
+3. 验证格式正确性
+```
+
+### 练习 2：创建含 references 的技能
+
+**任务**：创建 API 文档生成技能，包含 references
+
+**结构**：
+```
+.opencode/skills/api-docs/
+├── SKILL.md
+└── references/
+    ├── template.md
+    └── examples.md
+```
+
+**SKILL.md**：
+```markdown
+---
+name: api-docs
+description: |
+  API 文档生成技能，创建标准化的 API 文档。
+  提供：文档模板、参数规范、示例格式。
+---
+
+# API 文档生成技能
+
+## 工作流程
+
+1. 分析 API 接口
+2. 提取参数和返回值
+3. 生成标准化文档
+
+## 文档模板
+
+详细模板见 `references/template.md`
+
+## 示例文档
+
+参考示例见 `references/examples.md`
+```
+
+### 练习 3：优化技能描述
+
+**任务**：优化以下技能描述，使其更具体
+
+**原始描述**：
+```yaml
+description: "帮助写文档"
+```
+
+**优化后**：
+```yaml
+description: |
+  技术文档写作技能，擅长 API 文档、README、用户手册。
+  提供：文档结构模板、写作规范、常见错误避免。
+  适用：写新项目文档、更新现有文档、解释代码功能。
+  不适用：代码审查、Bug 修复、功能实现。
+```
+
+## 常见问题
+
+### Q1: 技能和 Agent 有什么区别？
+
+| 特性 | 技能 | Agent |
+|------|------|-------|
+| 定义方式 | SKILL.md | Markdown 或 JSON |
+| 加载时机 | 按需加载 | 会话切换 |
+| 主要用途 | 可复用工作流 | 专门任务助手 |
+| 工具权限 | 继承 Agent | 可独立配置 |
+
+### Q2: references 目录有什么作用？
+
+存放详细文档，避免 SKILL.md 过长：
+- **SKILL.md**：工作流和关键逻辑
+- **references/**：详细文档、模板、示例
+
+### Q3: 如何测试技能是否生效？
+
+1. 启动 OpenCode
+2. 描述任务需求
+3. 查看是否加载正确技能
+4. 验证工作流执行正确
+
+### Q4: 技能可以调用其他技能吗？
+
+可以，在 SKILL.md 中提及：
+```markdown
+## 相关技能
+
+需要翻译时，使用 translate 技能
+需要审查时，使用 code-review 技能
+```
+
+## 下一步
+
+- 🤖 [Agent 配置培训](/train/agent-basic) - 学习创建专门的 Agent
+- ⚡ [命令使用培训](/train/command-basic) - 学习自定义命令
+- 🎯 [实战案例](/train/practice) - 综合应用所学知识

package/skills/read-docs/references/opencode/tui/commands/config.md

@@ -0,0 +1,32 @@
+# configure
+Customize TUI behavior through `tui.json` (or `tui.jsonc`).
+- This is separate from `opencode.json`.
+- `keybinds` is merged with built-in defaults, so you only need to configure the shortcuts you want to change.
+
+```json
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "theme": "opencode",
+  "leader_timeout": 2000,
+  "keybinds": {
+    "leader": "ctrl+x",
+    "command_list": "ctrl+p"
+  },
+  "scroll_speed": 3,
+  "scroll_acceleration": {
+    "enabled": false
+  },
+  "diff_style": "auto",
+  "mouse": true,
+  "attention": {
+    "enabled": true,
+    "notifications": true,
+    "sound": true,
+    "volume": 0.4,
+    "sound_pack": "opencode.default",
+    "sounds": {
+      "error": "./sounds/error.mp3"
+    }
+  }
+}
+```

package/skills/read-docs/references/opencode/tui/commands/editor.md

@@ -0,0 +1,47 @@
+# editor
+Open external editor for composing messages. Uses the editor set in your `EDITOR` environment variable. 
+```
+/editor
+```
+
+流程是：
+1. TUI 创建一个临时文件
+2. 用 $EDITOR 打开它（如 vim、code --wait）
+3. 你在编辑器里写内容，保存并关闭
+4. TUI 读取临时文件内容，作为消息发送给 AI 和 git commit 不加 -m 时打开编辑器写提交信息是同一个机制。
+
+关键是编辑器必须阻塞等待——像 vim 天然阻塞，VS Code 则需要 code --wait 参数才会等关闭后再返回控制权给 TUI。
+
+## setup
+Both the `/editor` and `/export` commands use the editor specified in your EDITOR environment variable.
+
+Linux/macOS
+```
+export EDITOR=nano
+export EDITOR=vim
+
+# For GUI editors, VS Code, Cursor, VSCodium, Windsurf, Zed, etc.
+export EDITOR="code --wait"
+```
+
+Windows(cmd)
+```
+set EDITOR=notepad
+set EDITOR=code --wait
+```
+
+Windows(Powershell)
+```
+$env:EDITOR = "notepad"
+$env:EDITOR = "code --wait"
+```
+
+## popular editors
+- code : VSCode
+- cursor
+- windsurf
+- nvim
+- vim
+- nano
+- notepad : Windows Notepad
+- subl : sublime text