@wwkit/harness 1.0.9 → 1.0.11

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

@@ -0,0 +1,772 @@
+# Agent 配置培训
+
+学习配置 OpenCode Agent，创建专门的 AI 助手执行特定任务。
+
+## 理论介绍
+
+### 什么是 Agent？
+
+Agent 是可配置的专门 AI 助手，用于特定任务和工作流。
+
+**核心特点**：
+- **专门化**：针对特定任务优化
+- **可切换**：在会话中切换 Agent
+- **可调用**：通过 `@` 提及调用 Subagent
+- **可配置**：独立权限、模型、温度等
+
+### Agent 类型
+
+| 类型 | 说明 | 使用方式 |
+|------|------|----------|
+| Primary Agent | 直接交互的主助手 | Tab 键切换 |
+| Subagent | Primary Agent 可调用的专门助手 | 自动调用或 `@` 提及 |
+
+### 内置 Agent
+
+#### Primary Agent
+
+| Agent | 说明 |
+|-------|------|
+| build | 默认主 Agent，所有工具启用 |
+| plan | 规划和分析专用，文件编辑和 bash 默认需审批 |
+
+#### Subagent
+
+| Agent | 说明 |
+|-------|------|
+| general | 通用多步骤任务，完整工具访问（除 todo），可并行执行 |
+| explore | 快速只读代码探索，查找文件和搜索代码 |
+| scout | 外部文档和依赖研究 |
+
+### Agent 协作模式
+
+#### 父子协作
+
+```
+Primary Agent (父)
+  ├── 调用 Subagent 1 (子)
+  ├── 调用 Subagent 2 (子)
+  └── 整合结果
+```
+
+**工作流程**：
+1. Primary Agent 分析任务
+2. 调用合适的 Subagent
+3. Subagent 执行专门任务
+4. Primary Agent 整合结果
+
+#### 会话导航
+
+| 操作 | 快捷键 |
+|------|--------|
+| 进入第一个子会话 | `Leader+Down` |
+| 切换到下一个子会话 | `Right` |
+| 切换到上一个子会话 | `Left` |
+| 返回父会话 | `Up` |
+
+## Agent 配置方式
+
+### JSON 配置
+
+在 `opencode.json` 中配置：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "agent": {
+    "reviewer": {
+      "description": "代码审查 Agent",
+      "mode": "subagent",
+      "model": "anthropic/claude-haiku-4-5",
+      "temperature": 0.1,
+      "prompt": "你是代码审查专家，专注于代码质量和最佳实践",
+      "permission": {
+        "edit": "deny"
+      }
+    }
+  }
+}
+```
+
+### Markdown 配置
+
+放置在以下位置：
+- **全局**：`~/.config/opencode/agents/`
+- **项目级**：`.opencode/agents/`
+
+文件名即为 Agent 名称，如 `review.md` 创建 `review` Agent。
+
+```markdown
+---
+description: 代码审查 Agent，检查代码质量和最佳实践
+mode: subagent
+model: anthropic/claude-haiku-4-5
+temperature: 0.1
+permission:
+  edit: deny
+  bash: deny
+---
+
+你是代码审查专家，专注于：
+
+- 代码质量和最佳实践
+- 潜在 Bug 和边界情况
+- 性能影响
+- 安全考虑
+
+提供建设性反馈，不直接修改代码。
+```
+
+## 配置选项详解
+
+### Description
+
+提供 Agent 的简要描述和使用场景：
+
+```jsonc
+{
+  "agent": {
+    "docs-writer": {
+      "description": "技术文档写作专家，擅长 API 文档、README、用户手册"
+    }
+  }
+}
+```
+
+**描述建议**：
+- ✅ 说明 Agent 专长
+- ✅ 说明适用场景
+- ✅ 说明不适用场景
+
+### Temperature
+
+控制 LLM 响应的随机性和创造性：
+
+| 值 | 特点 | 适用场景 |
+|----|------|----------|
+| 0.1 | 最确定性 | 代码审查、安全分析 |
+| 0.3 | 平衡 | 文档编写、代码实现 |
+| 0.7 | 较创造性 | 创意设计、探索性任务 |
+| 0.9 | 最创造性 | 艺术创作、创新设计 |
+
+```jsonc
+{
+  "agent": {
+    "reviewer": { "temperature": 0.1 },
+    "writer": { "temperature": 0.7 }
+  }
+}
+```
+
+### Steps
+
+控制 Agent 最大迭代次数：
+
+```jsonc
+{
+  "agent": {
+    "quick-thinker": {
+      "description": "快速推理，有限迭代",
+      "steps": 5
+    },
+    "deep-analyzer": {
+      "description": "深度分析，更多迭代",
+      "steps": 100
+    }
+  }
+}
+```
+
+### Model
+
+为 Agent 覆盖默认模型：
+
+```jsonc
+{
+  "agent": {
+    "planner": {
+      "model": "anthropic/claude-opus-4-5"  // 深度分析用大模型
+    },
+    "executor": {
+      "model": "anthropic/claude-sonnet-4-5"  // 执行用中模型
+    },
+    "checker": {
+      "model": "anthropic/claude-haiku-4-5"  // 检查用小模型
+    }
+  }
+}
+```
+
+### Permissions
+
+配置 Agent 的操作权限：
+
+#### 权限值
+
+| 值 | 说明 |
+|----|------|
+| `ask` | 运行前需审批 |
+| `allow` | 允许所有操作 |
+| `deny` | 禁用工具 |
+
+#### 权限键
+
+| 键 | 控制的工具 |
+|----|-----------|
+| read | read |
+| edit | write, edit, apply_patch |
+| glob | glob |
+| grep | grep |
+| bash | bash |
+| task | task |
+| todowrite | todowrite, todoread |
+| skill | skill |
+| question | question |
+
+#### 精细化权限
+
+```jsonc
+{
+  "agent": {
+    "reviewer": {
+      "permission": {
+        "edit": "deny",
+        "bash": {
+          "*": "deny",
+          "git diff*": "allow",
+          "git log*": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+### Mode
+
+控制 Agent 模式：
+
+| 值 | 说明 |
+|----|------|
+| `primary` | Primary Agent，直接交互 |
+| `subagent` | Subagent，可被调用 |
+| `all` | 两种模式都可用（默认） |
+
+```jsonc
+{
+  "agent": {
+    "planner": { "mode": "primary" },
+    "helper": { "mode": "subagent" }
+  }
+}
+```
+
+### Hidden
+
+隐藏 Subagent（不在 `@` 自动补全中显示）：
+
+```jsonc
+{
+  "agent": {
+    "internal-helper": {
+      "mode": "subagent",
+      "hidden": true
+    }
+  }
+}
+```
+
+### Prompt
+
+指定自定义系统提示词：
+
+#### 内嵌提示词
+
+```jsonc
+{
+  "agent": {
+    "reviewer": {
+      "prompt": "你是代码审查专家，专注于代码质量和最佳实践"
+    }
+  }
+}
+```
+
+#### 文件引用
+
+```jsonc
+{
+  "agent": {
+    "reviewer": {
+      "prompt": "{file:./prompts/code-review.txt}"
+    }
+  }
+}
+```
+
+### Disable
+
+禁用 Agent：
+
+```jsonc
+{
+  "agent": {
+    "old-agent": { "disable": true }
+  }
+}
+```
+
+## 实例展示
+
+### 案例 1：文档写作 Agent
+
+创建 `.opencode/agents/docs-writer.md`：
+
+```markdown
+---
+description: |
+  技术文档写作专家，擅长 API 文档、README、用户手册。
+  适用场景：写新项目文档、更新现有文档、解释代码功能。
+  不适用：代码审查、Bug 修复、功能实现。
+mode: subagent
+temperature: 0.3
+---
+
+# 角色
+
+你是技术文档专家，擅长将复杂概念解释得通俗易懂。
+
+# 文档规范
+
+- 使用 Markdown 格式
+- 代码示例必须可运行
+- 包含输入/输出说明
+- 中文优先，专业术语保留英文
+
+# 文档结构
+
+1. **概述**：一句话说明是什么
+2. **快速开始**：30 秒能跑起来
+3. **详细 API**：完整参数说明
+4. **示例代码**：覆盖常见场景
+5. **常见问题**：预判用户疑惑
+
+# 约束条件
+
+- ✅ 快速开始的代码必须可直接复制运行
+- ✅ 参数说明要包含类型和默认值
+- ❌ 避免假设用户已有背景知识
+
+# 输出格式
+
+文档使用标准 Markdown 格式，代码块指定语言：
+
+```javascript
+// 示例代码
+```
+```
+
+**使用方式**：
+```
+用户：@docs-writer 为 API 创建文档
+Agent：调用 docs-writer → 按规范生成文档
+```
+
+### 案例 2：代码审查 Agent
+
+创建 `.opencode/agents/reviewer.md`：
+
+```markdown
+---
+description: |
+  代码审查 Agent，检查代码质量、安全性、性能问题。
+  适用场景：PR 审查、代码质量检查、最佳实践验证。
+  不适用：功能实现、Bug 修复。
+mode: subagent
+model: anthropic/claude-haiku-4-5
+temperature: 0.1
+permission:
+  edit: deny
+  bash:
+    "*": deny
+    "git diff*": allow
+    "git log*": allow
+---
+
+# 角色
+
+你是代码审查专家，专注于：
+
+- 代码质量和最佳实践
+- 潜在 Bug 和边界情况
+- 性能影响
+- 安全考虑
+
+# 审查流程
+
+1. **明确范围**：询问审查哪些文件
+2. **逐项检查**：按清单审查
+3. **输出报告**：结构化审查结果
+
+# 审查清单
+
+## 代码规范
+- 命名规范
+- 格式规范
+- 注释规范
+
+## 安全性
+- 输入验证
+- 权限检查
+- 数据泄露
+
+## 性能
+- 算法效率
+- 资源管理
+- 数据库查询
+
+# 输出格式
+
+```markdown
+## 审查摘要
+- 审查文件：[文件列表]
+- 发现问题：[问题数量]
+- 严重程度：[高/中/低]
+
+## 详细问题
+
+### 问题 1：[问题标题]
+- **文件**：src/file.js:123
+- **严重程度**：高
+- **问题描述**：...
+- **修复建议**：...
+```
+
+# 约束条件
+
+- ❌ 不直接修改代码
+- ✅ 提供建设性反馈
+- ✅ 指出具体问题和位置
+```
+
+**使用方式**：
+```
+用户：审查 src/components/ 目录
+Agent：调用 reviewer → 按清单审查 → 输出报告
+```
+
+### 案例 3：多模型协作系统
+
+创建 `.opencode/opencode.json`：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  
+  "agent": {
+    // 规划者：使用大模型深度分析
+    "planner": {
+      "description": "规划者：分析需求，制定详细计划",
+      "mode": "primary",
+      "model": "anthropic/claude-opus-4-5",
+      "temperature": 0.2,
+      "steps": 20,
+      "permission": {
+        "edit": "ask",
+        "bash": "ask"
+      }
+    },
+    
+    // 执行者：使用中模型快速实现
+    "executor": {
+      "description": "执行者：实现具体代码",
+      "mode": "primary",
+      "model": "anthropic/claude-sonnet-4-5",
+      "temperature": 0.3,
+      "steps": 100,
+      "permission": {
+        "edit": "allow",
+        "bash": "allow"
+      }
+    },
+    
+    // 检查者：使用小模型快速检查
+    "checker": {
+      "description": "检查者：验证实现正确性",
+      "mode": "subagent",
+      "model": "anthropic/claude-haiku-4-5",
+      "temperature": 0.1,
+      "permission": {
+        "edit": "deny",
+        "bash": {
+          "*": "deny",
+          "npm test": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+**工作流程**：
+```
+1. 切换到 planner → 分析需求，制定计划
+2. 切换到 executor → 实现代码
+3. 调用 checker → 验证正确性
+```
+
+### 案例 4：自动化 PR 审查机器人
+
+创建 `.opencode/agents/pr-reviewer.md`：
+
+```markdown
+---
+description: |
+  PR 审查机器人，自动审查代码变更。
+  适用场景：自动化 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"
+  task:
+    "*": deny
+    "security-auditor": "allow"
+    "performance-checker": "allow"
+---
+
+# 角色
+
+你是自动化 PR 审查机器人，负责审查代码变更。
+
+# 审查流程
+
+## 1. 获取变更
+
+```bash
+git diff origin/main...HEAD
+git log origin/main..HEAD --oneline
+```
+
+## 2. 分析变更
+
+- 检查代码质量
+- 检查安全性
+- 检查性能
+- 运行测试
+
+## 3. 输出审查结果
+
+```markdown
+## PR 审查报告
+
+### 变更摘要
+- 文件数：X
+- 新增行：X
+- 删除行：X
+
+### 代码质量
+- ✅/❌ [检查项]
+
+### 安全性
+- ✅/❌ [检查项]
+
+### 测试结果
+- ✅/❌ [测试状态]
+
+### 建议
+1. [建议内容]
+```
+
+# 审查标准
+
+详细标准见团队编码规范文档。
+
+# 约束条件
+
+- ❌ 不修改代码
+- ✅ 自动化审查
+- ✅ 结构化输出
+```
+
+### 案例 5：探索 Agent（只读）
+
+创建 `.opencode/agents/explorer.md`：
+
+```markdown
+---
+description: |
+  快速代码探索 Agent，只读访问。
+  适用场景：查找文件、搜索代码、理解代码结构。
+  不适用：修改代码、执行命令。
+mode: subagent
+model: anthropic/claude-haiku-4-5
+permission:
+  edit: deny
+  bash: deny
+---
+
+# 角色
+
+你是代码探索助手，帮助快速理解代码库。
+
+# 探索能力
+
+- 查找文件：使用 glob 工具
+- 搜索代码：使用 grep 工具
+- 读取文件：使用 read 工具
+
+# 工作流程
+
+1. **理解需求**：明确用户想找什么
+2. **搜索定位**：使用工具查找
+3. **总结结果**：简洁说明找到的内容
+
+# 输出格式
+
+```markdown
+## 探索结果
+
+### 找到的文件
+- `path/to/file1.js` - [简要说明]
+- `path/to/file2.js` - [简要说明]
+
+### 关键代码
+[代码片段]
+
+### 建议
+[下一步建议]
+```
+
+# 约束条件
+
+- ❌ 不修改代码
+- ❌ 不执行命令
+- ✅ 快速响应
+- ✅ 简洁输出
+```
+
+**使用方式**：
+```
+用户：@explorer 找到所有 API 路由定义
+Agent：调用 explorer → 搜索文件 → 输出结果
+```
+
+## 动手练习
+
+### 练习 1：创建简单 Agent
+
+**任务**：创建一个测试 Agent，专门运行测试
+
+**提示**：
+```markdown
+---
+description: 测试执行 Agent，运行测试套件并分析结果
+mode: subagent
+---
+
+# 角色
+你是测试执行专家...
+
+# 工作流程
+1. 运行测试
+2. 分析失败
+3. 输出结果
+
+# 输出格式
+...
+```
+
+### 练习 2：配置多模型 Agent
+
+**任务**：创建三个 Agent，使用不同模型
+
+**配置**：
+```jsonc
+{
+  "agent": {
+    "analyst": {
+      "model": "anthropic/claude-opus-4-5",
+      "temperature": 0.1
+    },
+    "developer": {
+      "model": "anthropic/claude-sonnet-4-5",
+      "temperature": 0.3
+    },
+    "checker": {
+      "model": "anthropic/claude-haiku-4-5",
+      "temperature": 0.1
+    }
+  }
+}
+```
+
+### 练习 3：精细化权限配置
+
+**任务**：创建一个 Agent，满足以下权限要求：
+- 禁止文件编辑
+- 允许 git 命令
+- 允许 npm 命令
+- 禁止其他 bash 命令
+
+**配置**：
+```markdown
+---
+permission:
+  edit: deny
+  bash:
+    "*": deny
+    "git *": allow
+    "npm *": allow
+---
+```
+
+## 常见问题
+
+### Q1: Primary Agent 和 Subagent 如何选择？
+
+**Primary Agent**：
+- 直接交互，用户手动切换
+- 适合主要工作流程
+
+**Subagent**：
+- 自动调用或 `@` 提及
+- 适合专门任务
+
+### Q2: 如何调试 Agent 配置？
+
+1. 启动 OpenCode
+2. 切换到 Agent（Tab 键）
+3. 检查是否显示正确 Agent
+4. 测试权限和工具是否生效
+
+### Q3: Agent 可以继承配置吗？
+
+可以，Agent 配置覆盖全局配置：
+```
+全局配置 → Agent 配置 → 技能配置
+```
+
+### Q4: 如何创建交互式 Agent？
+
+使用 `question` 工具：
+```markdown
+# 工作流程
+
+1. 使用 question 工具询问用户
+2. 根据用户选择执行任务
+3. 输出结果
+```
+
+## 下一步
+
+- ⚡ [命令使用培训](/train/command-basic) - 学习自定义命令
+- 🎯 [实战案例](/train/practice) - 综合应用所学知识
+- 📖 [Agent 详解](/agents/detail) - 深入理解 Agent 系统