@wwkit/harness 1.0.8 → 1.0.10

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

@@ -0,0 +1,509 @@
+# 基础配置培训
+
+学习 OpenCode 配置系统的核心概念，掌握配置文件编写和环境变量使用。
+
+## 理论介绍
+
+### 什么是配置系统？
+
+OpenCode 使用 JSON/JSONC 配置文件管理所有设置，包括：
+- **模型选择**：指定使用的 AI 模型
+- **权限控制**：管理 Agent 的操作权限
+- **Agent 定义**：创建专门的 AI 助手
+- **命令配置**：定义自定义快捷命令
+
+### 配置文件位置
+
+按优先级加载（后者覆盖前者）：
+
+| 优先级 | 位置 | 用途 |
+|--------|------|------|
+| 1 | 远程配置（`.well-known/opencode`） | 组织级默认配置 |
+| 2 | 全局配置（`~/.config/opencode/opencode.json`） | 用户偏好 |
+| 3 | 自定义配置（`OPENCODE_CONFIG` 环境变量） | 自定义覆盖 |
+| 4 | 项目配置（`.opencode/opencode.json`） | 项目级设置 |
+
+### 配置格式
+
+支持两种格式：
+- **JSON**：标准 JSON 格式
+- **JSONC**：带注释的 JSON（推荐）
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "anthropic/claude-sonnet-4-5",
+  
+  // 这是注释，JSONC 支持
+  "autoupdate": true
+}
+```
+
+## 核心配置项
+
+### 1. 模型配置
+
+#### 基础配置
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "anthropic/claude-sonnet-4-5",
+  "small_model": "anthropic/claude-haiku-4-5"
+}
+```
+
+**说明**：
+- `model`：主模型，处理复杂任务
+- `small_model`：小模型，处理简单任务（节省成本）
+
+#### Provider 配置
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "anthropic": {
+      "options": {
+        "apiKey": "{env:ANTHROPIC_API_KEY}",
+        "timeout": 600000,      // 10分钟超时
+        "chunkTimeout": 30000   // 30秒分块超时
+      }
+    }
+  }
+}
+```
+
+### 2. 权限配置
+
+#### 基础权限
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "edit": "ask",    // 文件编辑需审批
+    "bash": "ask"     // Shell 命令需审批
+  }
+}
+```
+
+**权限值说明**：
+- `allow`：允许所有操作
+- `ask`：运行前需用户审批
+- `deny`：禁用该工具
+
+#### 精细化权限
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permission": {
+    "bash": {
+      "*": "ask",                 // 默认需审批
+      "git status": "allow",      // git status 允许
+      "git diff*": "allow",       // git diff 相关允许
+      "npm test": "allow"         // 测试命令允许
+    }
+  }
+}
+```
+
+### 3. Agent 配置
+
+#### 简单 Agent
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "reviewer": {
+      "description": "代码审查 Agent",
+      "model": "anthropic/claude-haiku-4-5",
+      "permission": {
+        "edit": "deny"
+      }
+    }
+  }
+}
+```
+
+#### 多模型协作
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "planner": {
+      "description": "规划者：分析需求，制定计划",
+      "model": "anthropic/claude-opus-4-5",
+      "temperature": 0.2
+    },
+    "executor": {
+      "description": "执行者：实现具体代码",
+      "model": "anthropic/claude-sonnet-4-5",
+      "temperature": 0.3
+    }
+  }
+}
+```
+
+### 4. 命令配置
+
+#### 基础命令
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "command": {
+    "test": {
+      "template": "运行完整测试套件并显示覆盖率报告",
+      "description": "运行测试",
+      "agent": "build"
+    }
+  }
+}
+```
+
+#### 参数化命令
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "command": {
+    "component": {
+      "template": "创建名为 $ARGUMENTS 的 React 组件",
+      "description": "创建新组件"
+    }
+  }
+}
+```
+
+### 5. 工具配置
+
+#### 禁用工具
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "tools": {
+    "write": false,    // 禁用文件写入
+    "bash": false      // 禁用 Shell 命令
+  }
+}
+```
+
+#### 启用 LSP
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "lsp": true
+}
+```
+
+## 环境变量使用
+
+### 基础用法
+
+使用 `{env:VARIABLE_NAME}` 引用环境变量：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "{env:OPENCODE_MODEL}",
+  "provider": {
+    "anthropic": {
+      "options": {
+        "apiKey": "{env:ANTHROPIC_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### 设置环境变量
+
+#### Linux/macOS
+
+```bash
+export ANTHROPIC_API_KEY="your-api-key"
+export OPENCODE_MODEL="anthropic/claude-sonnet-4-5"
+```
+
+#### Windows PowerShell
+
+```powershell
+$env:ANTHROPIC_API_KEY="your-api-key"
+$env:OPENCODE_MODEL="anthropic/claude-sonnet-4-5"
+```
+
+### 自定义配置路径
+
+```bash
+export OPENCODE_CONFIG=/path/to/custom-config.json
+export OPENCODE_CONFIG_DIR=/path/to/config-directory
+```
+
+## 实例展示
+
+### 案例 1：团队项目配置
+
+创建 `.opencode/opencode.json`：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  
+  // 使用团队统一的模型
+  "model": "anthropic/claude-sonnet-4-5",
+  "small_model": "anthropic/claude-haiku-4-5",
+  
+  // 启用自动更新
+  "autoupdate": true,
+  
+  // 配置权限：安全优先
+  "permission": {
+    "edit": "ask",
+    "bash": {
+      "*": "ask",
+      "git status": "allow",
+      "git diff*": "allow",
+      "npm run lint": "allow",
+      "npm test": "allow"
+    }
+  },
+  
+  // 定义团队常用 Agent
+  "agent": {
+    "reviewer": {
+      "description": "代码审查：检查代码质量和最佳实践",
+      "mode": "subagent",
+      "model": "anthropic/claude-haiku-4-5",
+      "permission": {
+        "edit": "deny",
+        "bash": "deny"
+      }
+    },
+    
+    "docs-writer": {
+      "description": "文档编写：API 文档、README、用户手册",
+      "mode": "subagent",
+      "model": "anthropic/claude-sonnet-4-5",
+      "temperature": 0.3
+    }
+  },
+  
+  // 定义常用命令
+  "command": {
+    "lint": {
+      "template": "运行 ESLint 检查并修复所有问题",
+      "description": "代码规范检查",
+      "agent": "build"
+    },
+    
+    "test": {
+      "template": "运行测试套件并分析失败原因",
+      "description": "运行测试",
+      "agent": "build"
+    },
+    
+    "review": {
+      "template": "审查当前代码变更，检查代码质量",
+      "description": "代码审查",
+      "agent": "reviewer"
+    }
+  },
+  
+  // 启用 LSP
+  "lsp": true,
+  
+  // 配置文件监视器
+  "watcher": {
+    "ignore": ["node_modules/**", "dist/**", ".git/**"]
+  }
+}
+```
+
+### 案例 2：个人开发配置
+
+创建 `~/.config/opencode/opencode.json`：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  
+  // 偏好使用 Haiku 节省成本
+  "model": "anthropic/claude-haiku-4-5",
+  
+  // 开放权限，快速开发
+  "permission": {
+    "edit": "allow",
+    "bash": "allow"
+  },
+  
+  // 个人常用 Agent
+  "agent": {
+    "explorer": {
+      "description": "快速探索代码库",
+      "mode": "subagent",
+      "model": "anthropic/claude-haiku-4-5"
+    }
+  },
+  
+  // 禁用自动更新
+  "autoupdate": false
+}
+```
+
+### 案例 3：安全审查配置
+
+创建 `.opencode/opencode.json`：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  
+  // 使用大模型进行深度分析
+  "model": "anthropic/claude-opus-4-5",
+  
+  // 严格权限控制
+  "permission": {
+    "edit": "deny",
+    "bash": {
+      "*": "deny",
+      "git log*": "allow",
+      "git diff*": "allow"
+    },
+    "webfetch": "deny",
+    "websearch": "deny"
+  },
+  
+  // 定义审查 Agent
+  "agent": {
+    "security-reviewer": {
+      "description": "安全审查：检查代码安全性问题",
+      "mode": "primary",
+      "model": "anthropic/claude-opus-4-5",
+      "temperature": 0.1,
+      "permission": {
+        "edit": "deny",
+        "bash": "deny"
+      }
+    }
+  }
+}
+```
+
+## 动手练习
+
+### 练习 1：创建基础配置
+
+**任务**：创建项目配置文件，满足以下需求：
+1. 使用 Sonnet 作为主模型
+2. 文件编辑需审批，git 命令允许
+3. 定义一个代码审查 Agent
+
+**提示**：
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "anthropic/claude-sonnet-4-5",
+  "permission": {
+    // 补充权限配置
+  },
+  "agent": {
+    // 补充 Agent 定义
+  }
+}
+```
+
+### 练习 2：配置环境变量
+
+**任务**：
+1. 设置环境变量 `OPENCODE_MODEL`
+2. 在配置文件中引用该环境变量
+3. 验证配置生效
+
+**步骤**：
+```bash
+# 1. 设置环境变量
+export OPENCODE_MODEL="anthropic/claude-haiku-4-5"
+
+# 2. 在配置文件中使用
+# model: "{env:OPENCODE_MODEL}"
+
+# 3. 启动 OpenCode 验证
+opencode
+```
+
+### 练习 3：精细化权限配置
+
+**任务**：配置 Bash 权限，满足：
+1. 默认需审批
+2. 允许所有 git 命令
+3. 允许 npm run 命令
+4. 禁止 rm 命令
+
+**参考答案**：
+```jsonc
+{
+  "permission": {
+    "bash": {
+      "*": "ask",
+      "git *": "allow",
+      "npm run *": "allow",
+      "rm *": "deny"
+    }
+  }
+}
+```
+
+## 常见问题
+
+### Q1: JSON 和 JSONC 有什么区别？
+
+**JSONC** 支持注释，更易读：
+```jsonc
+{
+  "model": "claude-sonnet",  // 这是注释
+  "autoupdate": true
+}
+```
+
+**JSON** 不支持注释：
+```json
+{
+  "model": "claude-sonnet",
+  "autoupdate": true
+}
+```
+
+### Q2: 配置优先级如何理解？
+
+优先级从低到高：
+```
+远程配置 → 全局配置 → 自定义配置 → 项目配置
+```
+
+项目配置优先级最高，适合团队统一配置。
+
+### Q3: 如何验证配置是否生效？
+
+启动 OpenCode 后：
+1. 使用 `/help` 查看可用命令
+2. 切换 Agent 查看是否显示自定义 Agent
+3. 执行操作验证权限配置
+
+### Q4: 配置文件可以放在其他位置吗？
+
+可以，通过环境变量指定：
+```bash
+export OPENCODE_CONFIG=/custom/path/config.json
+```
+
+## 下一步
+
+- 📖 [技能创建培训](/train/skill-basic) - 学习创建可复用技能
+- 🤖 [Agent 配置培训](/train/agent-basic) - 深入理解 Agent 系统
+- ⚡ [实战案例](/train/practice) - 综合应用所学知识

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

@@ -0,0 +1,164 @@
+# OpenCode Agent 培训课程
+
+面向基础开发者的 OpenCode Agent 实战培训，通过理论讲解和实例演练快速掌握核心技能。
+
+## 课程概述
+
+本培训课程帮助开发者快速上手 OpenCode Agent，掌握配置、技能、Agent、命令等核心概念的实际应用。
+
+### 学习目标
+
+- ✅ 理解 OpenCode 配置系统的工作原理
+- ✅ 掌握技能（Skill）的创建和使用方法
+- ✅ 学会配置专门的 Agent 执行特定任务
+- ✅ 熟练使用自定义命令提高工作效率
+- ✅ 通过实战案例巩固所学知识
+
+### 课程结构
+
+| 章节 | 内容 | 预计时长 |
+|------|------|----------|
+| [基础配置](/train/config-basic) | 配置文件结构、常用配置项、环境变量 | 30分钟 |
+| [技能创建](/train/skill-basic) | SKILL.md 编写、工作流设计、references 使用 | 40分钟 |
+| [Agent 配置](/train/agent-basic) | Agent 类型、权限管理、多模型协作 | 35分钟 |
+| [命令使用](/train/command-basic) | 命令模板、参数传递、Shell 集成 | 25分钟 |
+| [实战案例](/train/practice) | 综合案例演练、常见问题解决 | 50分钟 |
+
+## 前置知识
+
+### 必备基础
+
+- ✅ 基本的 JSON/YAML 配置文件理解
+- ✅ Markdown 文档编写能力
+- ✅ 命令行工具使用经验
+- ✅ Git 基本操作
+
+### 推荐了解
+
+- 🔹 LLM（大语言模型）基本概念
+- 🔹 Node.js 项目结构
+- 🔹 TypeScript/JavaScript 开发经验
+
+## 环境准备
+
+### 安装 OpenCode
+
+```bash
+# 下载安装
+npm install -g @anthropic/opencode
+
+# 或使用包管理器
+brew install opencode  # macOS
+```
+
+### 初始化项目
+
+```bash
+# 启动 OpenCode
+opencode
+
+# 在 OpenCode 中初始化项目配置
+/init
+```
+
+### 目录结构
+
+```
+项目根目录/
+├── .opencode/
+│   ├── opencode.json    # 项目配置文件
+│   ├── agents/          # Agent 定义
+│   ├── commands/        # 自定义命令
+│   └── skills/          # 技能定义
+└── AGENTS.md            # 项目规则文件
+```
+
+## 学习路径
+
+### 🎯 快速入门路径（推荐新手）
+
+```
+基础配置 → 技能创建 → 命令使用 → 实战案例
+```
+
+适合：刚接触 OpenCode，希望快速上手
+
+### 🚀 进阶开发路径（推荐有经验者）
+
+```
+基础配置 → Agent 配置 → 技能创建 → 实战案例
+```
+
+适合：熟悉配置系统，希望深入定制
+
+### 💡 完整学习路径
+
+```
+基础配置 → 技能创建 → Agent 配置 → 命令使用 → 实战案例
+```
+
+适合：希望全面掌握 OpenCode 的开发者
+
+## 学习建议
+
+### 理论与实践结合
+
+每个章节包含：
+- **理论部分**：理解概念和原理
+- **实例展示**：实际配置和代码示例
+- **动手练习**：实践巩固所学知识
+
+### 循序渐进
+
+建议按照课程顺序学习，逐步深入：
+1. 先掌握配置基础
+2. 学会创建简单技能
+3. 理解 Agent 工作原理
+4. 熟练使用命令
+5. 通过实战案例综合应用
+
+### 实际应用
+
+学习过程中建议：
+- 在实际项目中应用所学内容
+- 创建符合团队需求的技能和 Agent
+- 积累常见场景的配置模板
+
+## 常见问题
+
+### Q1: OpenCode 和其他 AI 编码助手有什么区别？
+
+OpenCode 强调**可配置性**和**可扩展性**：
+- 通过配置文件精细控制 AI 行为
+- 创建专门的 Agent 处理特定任务
+- 定义技能实现可复用的工作流
+
+### Q2: 配置文件应该放在哪里？
+
+按优先级：
+- **项目级**：`.opencode/opencode.json`（推荐）
+- **全局级**：`~/.config/opencode/opencode.json`
+- **远程配置**：`.well-known/opencode`
+
+### Q3: 技能和 Agent 有什么区别？
+
+| 特性 | 技能（Skill） | Agent |
+|------|--------------|-------|
+| 定义文件 | SKILL.md | Markdown 或 JSON |
+| 加载方式 | 按需加载 | 会话切换或自动调用 |
+| 主要用途 | 可复用工作流 | 专门任务助手 |
+| 工具权限 | 继承 Agent 权限 | 可独立配置权限 |
+
+### Q4: 如何选择合适的模型？
+
+根据任务复杂度：
+- **简单任务**：使用 Haiku 等小模型（快速、低成本）
+- **复杂分析**：使用 Sonnet 等中模型（平衡性能和成本）
+- **深度推理**：使用 Opus 等大模型（最高质量）
+
+## 获取帮助
+
+- 📖 [官方文档](/guide/)
+- 💬 [技能详解](/skills/detail)
+- 🤖 [Agent 详解](/agents/detail)
+- ⚡ [命令示例](/commands/examples)