@wwkit/harness 1.0.8 → 1.0.10

package/skills/read-docs/references/opencode/train/practice.md

@@ -0,0 +1,873 @@
+# 实战案例培训
+
+通过综合案例演练，巩固所学知识，解决实际问题。
+
+## 案例 1：团队协作项目配置
+
+### 场景描述
+
+团队需要统一 OpenCode 配置，确保：
+- 使用统一的模型和权限
+- 定义团队常用 Agent 和技能
+- 创建标准化的命令
+
+### 解决方案
+
+#### 1. 创建项目配置
+
+`.opencode/opencode.json`：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  
+  // 统一模型
+  "model": "anthropic/claude-sonnet-4-5",
+  "small_model": "anthropic/claude-haiku-4-5",
+  
+  // 安全优先的权限配置
+  "permission": {
+    "edit": "ask",
+    "bash": {
+      "*": "ask",
+      "git status": "allow",
+      "git diff*": "allow",
+      "git log*": "allow",
+      "npm run lint": "allow",
+      "npm test": "allow",
+      "npm run build": "allow"
+    }
+  },
+  
+  // 团队 Agent
+  "agent": {
+    "reviewer": {
+      "description": "代码审查：检查代码质量和安全性",
+      "mode": "subagent",
+      "model": "anthropic/claude-haiku-4-5",
+      "temperature": 0.1,
+      "permission": {
+        "edit": "deny",
+        "bash": {
+          "*": "deny",
+          "git diff*": "allow",
+          "git log*": "allow"
+        }
+      }
+    },
+    
+    "docs-writer": {
+      "description": "文档编写：API 文档、README",
+      "mode": "subagent",
+      "model": "anthropic/claude-sonnet-4-5",
+      "temperature": 0.3
+    },
+    
+    "tester": {
+      "description": "测试执行：运行测试并分析失败",
+      "mode": "subagent",
+      "model": "anthropic/claude-haiku-4-5",
+      "permission": {
+        "bash": {
+          "*": "deny",
+          "npm test": "allow",
+          "npm run test:*": "allow"
+        }
+      }
+    }
+  },
+  
+  // 团队命令
+  "command": {
+    "lint": {
+      "template": "运行 ESLint 检查并修复问题",
+      "description": "代码规范检查",
+      "agent": "build"
+    },
+    
+    "test": {
+      "template": "运行测试套件并分析失败",
+      "description": "运行测试",
+      "agent": "tester"
+    },
+    
+    "review": {
+      "template": "审查代码变更",
+      "description": "代码审查",
+      "agent": "reviewer"
+    },
+    
+    "docs": {
+      "template": "为 $ARGUMENTS 生成文档",
+      "description": "生成文档",
+      "agent": "docs-writer"
+    }
+  },
+  
+  // 启用 LSP
+  "lsp": true
+}
+```
+
+#### 2. 创建团队技能
+
+`.opencode/skills/team-workflow/SKILL.md`：
+
+```markdown
+---
+name: team-workflow
+description: |
+  团队协作工作流技能，标准化开发流程。
+  提供：PR 流程、代码规范、测试标准。
+  适用：团队项目开发、协作开发。
+  不适用：个人项目、实验性开发。
+---
+
+# 团队协作工作流
+
+## 开发流程
+
+### 1. 功能开发
+
+```bash
+# 创建分支
+git checkout -b feat/功能名/yyyy-mm-dd
+
+# 开发代码
+# ...
+
+# 运行检查
+npm run lint
+npm test
+
+# 提交代码
+git add .
+git commit -m "feat: 功能描述"
+```
+
+### 2. 代码审查
+
+使用 `/review` 命令：
+- 检查代码质量
+- 检查安全性
+- 检查性能
+
+### 3. 创建 PR
+
+```bash
+git push origin feat/功能名/yyyy-mm-dd
+```
+
+## 代码规范
+
+详细规范见 `references/code-standards.md`
+
+## 测试标准
+
+详细标准见 `references/test-standards.md`
+```
+
+#### 3. 创建团队规则
+
+`AGENTS.md`：
+
+```markdown
+# 团队开发规范
+
+## 提交规范
+
+使用 Conventional Commits：
+- feat: 新功能
+- fix: Bug 修复
+- docs: 文档更新
+- style: 格式调整
+- refactor: 重构
+- test: 测试相关
+- chore: 工程配置
+
+## 分支命名
+
+格式：`type/关键字/yyyy-mm-dd`
+
+示例：
+- feat/user-auth/2024-01-15
+- fix/login-bug/2024-01-16
+
+## 代码规范
+
+- 使用 2 空格缩进
+- 使用单引号
+- 语句末尾无分号
+- 变量使用 camelCase
+- 常量使用 UPPER_CASE
+
+## 测试要求
+
+- 新功能必须有测试
+- Bug 修复必须有测试
+- 测试覆盖率 > 80%
+
+## 文档要求
+
+- README 必须包含快速开始
+- API 必须有文档
+- 复杂逻辑必须有注释
+```
+
+### 使用示例
+
+```bash
+# 开发流程
+/test              # 运行测试
+/lint              # 检查代码规范
+/review            # 审查代码
+/commit feat: 添加用户认证  # 提交代码
+```
+
+## 案例 2：自动化 CI/CD 集成
+
+### 场景描述
+
+将 OpenCode Agent 集成到 CI/CD 流程，自动执行：
+- 代码审查
+- 测试运行
+- 文档生成
+
+### 解决方案
+
+#### 1. 创建 CI Agent
+
+`.opencode/agents/ci-bot.md`：
+
+```markdown
+---
+description: |
+  CI/CD 自动化 Agent，执行持续集成任务。
+  适用场景：自动化 PR 审查、测试执行、文档生成。
+  不适用：手动开发、功能实现。
+mode: primary
+model: anthropic/claude-opus-4-5
+steps: 100
+temperature: 0.1
+permission:
+  edit: deny
+  bash:
+    "*": deny
+    "git log*": allow
+    "git diff*": allow
+    "npm test": allow
+    "npm run lint": allow
+    "npm run build": allow
+  task:
+    "*": deny
+    "reviewer": allow
+    "tester": allow
+---
+
+# CI/CD 自动化 Agent
+
+## 工作流程
+
+### 1. 获取变更
+
+```bash
+git diff origin/main...HEAD
+git log origin/main..HEAD --oneline
+```
+
+### 2. 执行检查
+
+- 运行 lint 检查
+- 运行测试套件
+- 调用 reviewer Agent 审查代码
+
+### 3. 输出报告
+
+```markdown
+## CI 检查报告
+
+### 变更摘要
+- 文件数：X
+- 新增行：X
+- 删除行：X
+
+### Lint 检查
+- ✅/❌ [状态]
+
+### 测试结果
+- ✅/❌ [状态]
+- 覆盖率：X%
+
+### 代码审查
+- 问题数：X
+- 严重程度：[高/中/低]
+
+### 建议
+1. [建议内容]
+```
+
+## 约束条件
+
+- ❌ 不修改代码
+- ✅ 自动化检查
+- ✅ 结构化输出
+```
+
+#### 2. 创建 CI 命令
+
+`.opencode/commands/ci-check.md`：
+
+```markdown
+---
+description: CI 检查流程
+agent: ci-bot
+---
+
+执行完整 CI 检查流程：
+
+## 1. 获取变更
+!`git diff origin/main...HEAD`
+
+## 2. 运行 lint
+!`npm run lint`
+
+## 3. 运行测试
+!`npm test -- --coverage`
+
+## 4. 构建项目
+!`npm run build`
+
+分析所有检查结果，输出 CI 报告。
+
+如果任何检查失败，提供修复建议。
+```
+
+#### 3. CI 流水线集成
+
+`.github/workflows/ci.yml`：
+
+```yaml
+name: CI
+
+on: [pull_request]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v2
+        with:
+          node-version: '18'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Run OpenCode CI check
+        run: |
+          opencode --command ci-check
+          # 输出结果到 PR 评论
+```
+
+### 使用示例
+
+```bash
+# 手动触发 CI 检查
+/ci-check
+
+# 自动触发（PR 创建时）
+# GitHub Actions 自动运行
+```
+
+## 案例 3：文档站点自动化
+
+### 场景描述
+
+自动生成和维护文档站点：
+- API 文档自动生成
+- README 自动更新
+- 示例代码自动提取
+
+### 解决方案
+
+#### 1. 创建文档生成技能
+
+`.opencode/skills/auto-docs/SKILL.md`：
+
+```markdown
+---
+name: auto-docs
+description: |
+  自动文档生成技能，从代码自动生成文档。
+  提供：API 文档模板、README 模板、示例提取规则。
+  适用：自动生成 API 文档、更新 README、提取示例。
+  不适用：手动编写文档、非代码文档。
+---
+
+# 自动文档生成
+
+## 工作流程
+
+### 1. 分析代码
+
+- 扫描源码目录
+- 提取函数和类定义
+- 提取注释和类型信息
+
+### 2. 生成文档
+
+#### API 文档
+
+```markdown
+## 函数名
+
+### 描述
+[从注释提取]
+
+### 参数
+| 参数 | 类型 | 默认值 | 说明 |
+|-----|------|--------|------|
+| ... | ... | ... | ... |
+
+### 返回值
+- 类型：[类型]
+- 说明：[说明]
+
+### 示例
+[从代码提取]
+```
+
+#### README
+
+```markdown
+# 项目名
+
+## 快速开始
+[从示例提取]
+
+## API 文档
+[链接到 API 文档]
+
+## 示例
+[从代码提取]
+```
+
+### 3. 验证文档
+
+- 检查示例代码可运行
+- 检查参数说明完整
+- 检查链接有效
+
+## 文档模板
+
+详细模板见 `references/templates.md`
+
+## 示例提取规则
+
+详细规则见 `references/extract-rules.md`
+```
+
+#### 2. 创建文档 Agent
+
+`.opencode/agents/doc-generator.md`：
+
+```markdown
+---
+description: |
+  文档生成 Agent，自动生成和维护文档。
+  适用场景：API 文档生成、README 更新、示例提取。
+  不适用：手动文档编写、非代码文档。
+mode: subagent
+model: anthropic/claude-sonnet-4-5
+temperature: 0.3
+---
+
+# 文档生成 Agent
+
+## 能力
+
+- 从代码提取 API 信息
+- 生成标准化文档
+- 更新 README
+- 提取示例代码
+
+## 工作流程
+
+1. 扫描代码目录
+2. 分析代码结构
+3. 生成文档
+4. 验证文档
+
+## 输出格式
+
+- API 文档：Markdown 格式
+- README：标准模板
+- 示例：可运行代码
+```
+
+#### 3. 创建文档命令
+
+`.opencode/commands/gen-docs.md`：
+
+```markdown
+---
+description: 生成完整文档
+agent: doc-generator
+---
+
+为以下目录生成完整文档：
+$ARGUMENTS
+
+## 生成内容
+
+1. API 文档
+2. README 更新
+3. 示例提取
+
+## 输出位置
+
+- API 文档：docs/api/
+- README：README.md
+- 示例：docs/examples/
+
+生成完成后验证文档完整性。
+```
+
+### 使用示例
+
+```bash
+# 为整个项目生成文档
+/gen-docs src/
+
+# 为特定模块生成文档
+/gen-docs src/utils/
+
+# 更新 README
+/gen-docs README.md
+```
+
+## 案例 4：多语言项目配置
+
+### 场景描述
+
+多语言项目需要：
+- 不同语言使用不同 Agent
+- 统一的代码规范
+- 语言特定的技能
+
+### 解决方案
+
+#### 1. 创建语言特定 Agent
+
+`.opencode/agents/ts-dev.md`：
+
+```markdown
+---
+description: TypeScript 开发 Agent
+mode: subagent
+model: anthropic/claude-sonnet-4-5
+---
+
+# TypeScript 开发 Agent
+
+## 能力
+
+- TypeScript 类型定义
+- 接口设计
+- 类型安全实现
+
+## 规范
+
+- 使用 interface 定义类型
+- 使用 type 定义联合类型
+- 避免使用 any
+- 优先使用 const
+```
+
+`.opencode/agents/python-dev.md`：
+
+```markdown
+---
+description: Python 开发 Agent
+mode: subagent
+model: anthropic/claude-sonnet-4-5
+---
+
+# Python 开发 Agent
+
+## 能力
+
+- Python 代码实现
+- 类型提示
+- Pythonic 代码风格
+
+## 规范
+
+- 使用 type hints
+- 遵循 PEP 8
+- 使用 f-string
+- 优先使用 list comprehension
+```
+
+#### 2. 创建语言检测技能
+
+`.opencode/skills/lang-detect/SKILL.md`：
+
+```markdown
+---
+name: lang-detect
+description: |
+  语言检测技能，自动识别代码语言并调用对应 Agent。
+  适用：多语言项目开发、混合语言项目。
+---
+
+# 语言检测技能
+
+## 工作流程
+
+1. 分析文件扩展名
+2. 识别代码语言
+3. 调用对应 Agent
+
+## 语言映射
+
+| 扩展名 | 语言 | Agent |
+|--------|------|-------|
+| .ts, .tsx | TypeScript | ts-dev |
+| .py | Python | python-dev |
+| .js, .jsx | JavaScript | js-dev |
+| .go | Go | go-dev |
+
+## 调用方式
+
+根据文件扩展名自动调用对应 Agent。
+```
+
+#### 3. 创建通用命令
+
+`.opencode/commands/dev.md`：
+
+```markdown
+---
+description: 语言自适应开发
+---
+
+开发功能：$ARGUMENTS
+
+## 自动检测
+
+根据文件扩展名自动选择 Agent：
+- TypeScript → @ts-dev
+- Python → @python-dev
+- JavaScript → @js-dev
+
+## 开发流程
+
+1. 分析需求
+2. 选择语言和 Agent
+3. 实现代码
+4. 验证实现
+```
+
+### 使用示例
+
+```bash
+# 自动检测语言并开发
+/dev src/utils/helper.ts "创建日期格式化函数"
+/dev src/utils/parser.py "创建 JSON 解析器"
+```
+
+## 案例 5：安全审查系统
+
+### 场景描述
+
+建立完整的安全审查系统：
+- 自动安全检查
+- 漏洞扫描
+- 安全报告生成
+
+### 解决方案
+
+#### 1. 创建安全审查 Agent
+
+`.opencode/agents/security-reviewer.md`：
+
+```markdown
+---
+description: |
+  安全审查 Agent，检查代码安全性问题。
+  适用场景：安全审查、漏洞扫描、安全报告。
+  不适用：功能开发、性能优化。
+mode: primary
+model: anthropic/claude-opus-4-5
+temperature: 0.1
+permission:
+  edit: deny
+  bash:
+    "*": deny
+    "npm audit": allow
+    "git diff*": allow
+---
+
+# 安全审查 Agent
+
+## 审查清单
+
+### 输入验证
+- [ ] 用户输入是否验证
+- [ ] 是否有 XSS 风险
+- [ ] 是否有 SQL 注入风险
+
+### 权限检查
+- [ ] 敏感操作是否有权限验证
+- [ ] 是否有越权风险
+
+### 数据安全
+- [ ] 是否暴露敏感信息
+- [ ] 密码和密钥是否硬编码
+- [ ] 是否使用 HTTPS
+
+### 依赖安全
+- [ ] 依赖是否有已知漏洞
+- [ ] 是否使用过时依赖
+
+## 工作流程
+
+1. 运行 npm audit
+2. 分析代码变更
+3. 检查安全清单
+4. 输出安全报告
+
+## 输出格式
+
+```markdown
+## 安全审查报告
+
+### 依赖漏洞
+- [漏洞列表]
+
+### 代码安全问题
+- [问题列表]
+
+### 建议
+- [修复建议]
+```
+```
+
+#### 2. 创建安全审查命令
+
+`.opencode/commands/security-check.md`：
+
+```markdown
+---
+description: 安全审查
+agent: security-reviewer
+---
+
+执行完整安全审查：
+
+## 1. 依赖漏洞扫描
+!`npm audit`
+
+## 2. 代码变更分析
+!`git diff HEAD`
+
+## 3. 安全清单检查
+按照安全清单逐项检查。
+
+输出完整安全报告，包括：
+- 依赖漏洞
+- 代码安全问题
+- 修复建议
+```
+
+### 使用示例
+
+```bash
+# 执行安全审查
+/security-check
+
+# 审查特定文件
+/security-check src/api/auth.ts
+```
+
+## 常见问题解决
+
+### 问题 1：Agent 权限过于严格
+
+**症状**：Agent 无法执行必要操作
+
+**解决**：
+```jsonc
+{
+  "permission": {
+    "bash": {
+      "*": "ask",           // 默认需审批
+      "git *": "allow",     // git 命令允许
+      "npm *": "allow"      // npm 命令允许
+    }
+  }
+}
+```
+
+### 问题 2：技能加载失败
+
+**症状**：技能未按预期加载
+
+**检查**：
+1. SKILL.md 文件位置正确
+2. Frontmatter 格式正确
+3. Description 足够具体
+
+### 问题 3：命令参数传递错误
+
+**症状**：参数未正确传递
+
+**解决**：
+- 使用 `$ARGUMENTS` 传递所有参数
+- 使用 `$1, $2, $3` 传递位置参数
+- 检查命令调用格式
+
+### 问题 4：多 Agent 协作混乱
+
+**症状**：Agent 调用不清晰
+
+**解决**：
+- 明确 Agent 类型（primary/subagent）
+- 使用 `@` 明确调用 Subagent
+- 在配置中设置 `mode`
+
+## 最佳实践总结
+
+### 配置管理
+
+1. **项目级配置优先**：团队统一配置
+2. **权限安全优先**：默认 ask，明确 allow
+3. **模型按需选择**：简单任务用小模型
+
+### Agent 设计
+
+1. **专门化**：每个 Agent 专注一类任务
+2. **权限隔离**：审查 Agent 禁止编辑
+3. **模型适配**：复杂任务用大模型
+
+### 技能设计
+
+1. **工作流清晰**：明确步骤和规则
+2. **references 分离**：详细文档独立存放
+3. **描述具体**：说明适用和不适用场景
+
+### 命令设计
+
+1. **参数化**：支持 `$ARGUMENTS`
+2. **Shell 集成**：注入命令输出
+3. **Agent 指定**：明确执行 Agent
+
+## 下一步学习
+
+- 📖 [技能详解](/skills/detail) - 深入理解技能系统
+- 🤖 [Agent 详解](/agents/detail) - 深入理解 Agent 系统
+- ⚡ [命令示例](/commands/examples) - 更多命令示例
+- 🎯 [Agent 设计模式](/agents/design-pattern) - Agent 设计原则