@wwkit/harness 1.0.9 → 1.0.10

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

@@ -0,0 +1,668 @@
+# 命令使用培训
+
+学习创建和使用 OpenCode 自定义命令，提高工作效率。
+
+## 理论介绍
+
+### 什么是命令（Command）？
+
+自定义命令让你在 TUI 中执行预设的提示词：
+
+```
+/my-command
+```
+
+**核心特点**：
+- **快捷执行**：一键触发预设任务
+- **参数化**：支持传递参数
+- **模板化**：复用常见工作流
+- **Agent 指定**：指定执行命令的 Agent
+
+### 命令文件位置
+
+创建 Markdown 文件：
+- **全局**：`~/.config/opencode/commands/`
+- **项目级**：`.opencode/commands/`
+
+文件名即为命令名，如 `test.md` 创建 `/test` 命令。
+
+### 命令结构
+
+```markdown
+---
+description: 命令描述
+agent: build
+model: anthropic/claude-sonnet-4-5
+---
+
+命令模板内容...
+```
+
+**Frontmatter 字段**：
+- `description`：命令描述（可选）
+- `agent`：执行命令的 Agent（可选）
+- `model`：覆盖模型（可选）
+- `subtask`：强制触发子代理（可选）
+
+## 命令模板功能
+
+### 1. 参数传递
+
+#### 使用 `$ARGUMENTS`
+
+传递所有参数：
+
+```markdown
+---
+description: 创建新组件
+---
+
+创建名为 $ARGUMENTS 的 React 组件，包含 TypeScript 支持。
+```
+
+**使用**：
+```
+/component Button
+```
+
+#### 使用位置参数
+
+传递特定位置参数：
+
+```markdown
+---
+description: 创建文件
+---
+
+在目录 $2 创建文件 $1，内容为：
+$3
+```
+
+**使用**：
+```
+/create-file config.json src "{ \"key\": \"value\" }"
+```
+
+### 2. Shell 输出注入
+
+使用 `` !`command` `` 注入 bash 命令输出：
+
+```markdown
+---
+description: 分析测试覆盖率
+---
+
+以下是当前测试结果：
+!`npm test`
+
+基于这些结果，建议改进覆盖率的方法。
+```
+
+**执行流程**：
+1. 运行 `npm test`
+2. 将输出注入提示词
+3. Agent 分析结果
+
+### 3. 文件引用
+
+使用 `@` 引用文件：
+
+```markdown
+---
+description: 审查组件
+---
+
+审查组件 @src/components/Button.tsx。
+检查性能问题并建议改进。
+```
+
+**执行流程**：
+1. 读取 `src/components/Button.tsx`
+2. 将内容注入提示词
+3. Agent 审查文件
+
+### 4. 组合使用
+
+组合多种功能：
+
+```markdown
+---
+description: 完整审查流程
+agent: reviewer
+---
+
+审查变更：
+
+## Git 变更
+!`git diff origin/main...HEAD`
+
+## 相关文件
+@$ARGUMENTS
+
+请审查这些变更，检查代码质量和安全性。
+```
+
+**使用**：
+```
+/review src/components/Button.tsx
+```
+
+## 实例展示
+
+### 案例 1：测试命令
+
+创建 `.opencode/commands/test.md`：
+
+```markdown
+---
+description: 运行测试套件并分析失败
+agent: build
+---
+
+运行完整测试套件并显示覆盖率报告：
+
+```bash
+npm test -- --coverage
+```
+
+分析失败的测试：
+1. 识别失败原因
+2. 定位问题代码
+3. 提供修复建议
+
+输出结构化报告。
+```
+
+**使用**：
+```
+/test
+```
+
+### 案例 2：组件创建命令
+
+创建 `.opencode/commands/component.md`：
+
+```markdown
+---
+description: 创建 React 组件
+agent: build
+---
+
+创建名为 $ARGUMENTS 的 React 组件，要求：
+
+## 组件结构
+
+1. **文件位置**：`src/components/$ARGUMENTS.tsx`
+2. **TypeScript 支持**：完整类型定义
+3. **Props 定义**：明确的接口定义
+4. **样式方案**：使用 CSS Modules 或 Tailwind
+
+## 组件模板
+
+```typescript
+interface $ARGUMENTSProps {
+  // Props 定义
+}
+
+export function $ARGUMENTS({ }: $ARGUMENTSProps) {
+  return (
+    // 组件实现
+  )
+}
+```
+
+## 附加文件
+
+- 创建测试文件：`src/components/$ARGUMENTS.test.tsx`
+- 创建样式文件：`src/components/$ARGUMENTS.css`
+
+创建完成后，确保组件可导入和使用。
+```
+
+**使用**：
+```
+/component Button
+/component UserCard
+```
+
+### 案例 3：代码审查命令
+
+创建 `.opencode/commands/review.md`：
+
+```markdown
+---
+description: 审查代码变更
+agent: reviewer
+---
+
+审查以下代码变更：
+
+## Git 差异
+!`git diff HEAD`
+
+## 相关文件
+@$ARGUMENTS
+
+## 审查要求
+
+1. **代码质量**：
+   - 命名规范
+   - 格式规范
+   - 注释规范
+
+2. **安全性**：
+   - 输入验证
+   - 权限检查
+   - 数据泄露
+
+3. **性能**：
+   - 算法效率
+   - 资源管理
+
+输出审查报告，指出具体问题和修复建议。
+```
+
+**使用**：
+```
+/review src/utils/helper.ts
+```
+
+### 案例 4：文档生成命令
+
+创建 `.opencode/commands/docs.md`：
+
+```markdown
+---
+description: 生成 API 文档
+agent: docs-writer
+---
+
+为以下文件生成 API 文档：
+
+@$ARGUMENTS
+
+## 文档要求
+
+1. **概述**：一句话说明功能
+2. **参数说明**：
+   - 参数名
+   - 类型
+   - 默认值
+   - 说明
+
+3. **返回值**：
+   - 类型
+   - 说明
+
+4. **示例代码**：
+   - 基础用法
+   - 高级用法
+
+5. **注意事项**：
+
+使用 Markdown 格式，代码块指定语言。
+```
+
+**使用**：
+```
+/docs src/api/user.ts
+```
+
+### 案例 5：Git 提交命令
+
+创建 `.opencode/commands/commit.md`：
+
+```markdown
+---
+description: 创建 Git 提交
+agent: build
+---
+
+创建 Git 提交，提交信息为：$ARGUMENTS
+
+## 提交前检查
+
+1. 查看变更：
+!`git status`
+!`git diff`
+
+2. 运行测试：
+!`npm test`
+
+3. 运行 lint：
+!`npm run lint`
+
+## 提交要求
+
+- 提交信息格式：`type: description`
+- type 可选：feat, fix, docs, style, refactor, test, chore
+- 描述简洁明了
+
+如果测试或 lint 失败，先修复问题再提交。
+```
+
+**使用**：
+```
+/commit feat: 添加用户认证功能
+/commit fix: 修复登录验证 Bug
+```
+
+### 案例 6：依赖更新命令
+
+创建 `.opencode/commands/update-deps.md`：
+
+```markdown
+---
+description: 更新项目依赖
+agent: build
+---
+
+更新项目依赖：
+
+## 当前依赖状态
+!`npm outdated`
+
+## 更新步骤
+
+1. **检查更新**：
+   ```bash
+   npm outdated
+   ```
+
+2. **更新依赖**：
+   ```bash
+   npm update
+   ```
+
+3. **测试验证**：
+   ```bash
+   npm test
+   ```
+
+4. **提交变更**：
+   ```bash
+   git add package.json package-lock.json
+   git commit -m "chore: 更新依赖"
+   ```
+
+## 注意事项
+
+- 主要版本更新需谨慎
+- 更新后必须运行测试
+- 检查是否有 breaking changes
+
+如果测试失败，回滚变更并分析问题。
+```
+
+**使用**：
+```
+/update-deps
+```
+
+### 案例 7：项目初始化命令
+
+创建 `.opencode/commands/init-project.md`：
+
+```markdown
+---
+description: 初始化新项目
+agent: build
+---
+
+初始化名为 $ARGUMENTS 的项目：
+
+## 项目结构
+
+```
+$ARGUMENTS/
+├── src/
+│   ├── components/
+│   ├── utils/
+│   └── index.ts
+├── tests/
+├── package.json
+├── tsconfig.json
+├── README.md
+└── .gitignore
+```
+
+## 创建步骤
+
+1. 创建目录结构
+2. 生成 package.json：
+   ```json
+   {
+     "name": "$ARGUMENTS",
+     "version": "1.0.0",
+     "scripts": {
+       "build": "tsc",
+       "test": "jest"
+     }
+   }
+   ```
+
+3. 生成 tsconfig.json
+4. 生成 README.md
+5. 初始化 Git 仓库
+
+## 初始化 Git
+
+```bash
+git init
+git add .
+git commit -m "init: 初始化项目"
+```
+
+创建完成后，项目可以立即开始开发。
+```
+
+**使用**：
+```
+/init-project my-app
+```
+
+### 案例 8：性能分析命令
+
+创建 `.opencode/commands/perf.md`：
+
+```markdown
+---
+description: 性能分析
+agent: analyzer
+---
+
+分析性能问题：
+
+## 当前状态
+!`npm run build -- --profile`
+
+## 分析要求
+
+1. **构建性能**：
+   - 构建时间
+   - Bundle 大小
+   - 模块依赖
+
+2. **运行性能**：
+   - 启动时间
+   - 内存使用
+   - CPU 占用
+
+3. **优化建议**：
+   - 代码分割
+   - 懒加载
+   - Tree shaking
+
+输出性能报告和优化建议。
+```
+
+**使用**：
+```
+/perf
+```
+
+## JSON 配置方式
+
+在 `opencode.json` 中配置：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  
+  "command": {
+    "test": {
+      "template": "运行完整测试套件并分析失败原因",
+      "description": "运行测试",
+      "agent": "build",
+      "model": "anthropic/claude-haiku-4-5"
+    },
+    
+    "component": {
+      "template": "创建名为 $ARGUMENTS 的 React组件",
+      "description": "创建组件",
+      "subtask": true
+    }
+  }
+}
+```
+
+## 动手练习
+
+### 练习 1：创建简单命令
+
+**任务**：创建一个 lint 命令
+
+**提示**：
+```markdown
+---
+description: 运行代码规范检查
+---
+
+运行 ESLint 检查：
+
+```bash
+npm run lint
+```
+
+分析问题并提供修复建议。
+```
+
+### 练习 2：创建参数化命令
+
+**任务**：创建一个文件创建命令
+
+**提示**：
+```markdown
+---
+description: 创建文件
+---
+
+在目录 $2 创建文件 $1，内容为：
+$3
+
+创建完成后验证文件内容。
+```
+
+### 练习 3：创建 Shell 集成命令
+
+**任务**：创建一个 Git 状态命令
+
+**提示**：
+```markdown
+---
+description: 查看 Git 状态
+---
+
+当前 Git 状态：
+!`git status`
+
+分析变更并提供下一步建议。
+```
+
+### 练习 4：创建组合命令
+
+**任务**：创建一个完整的开发流程命令
+
+**提示**：
+```markdown
+---
+description: 完整开发流程
+agent: build
+---
+
+执行完整开发流程：
+
+## 1. 查看变更
+!`git status`
+
+## 2. 运行 lint
+!`npm run lint`
+
+## 3. 运行测试
+!`npm test`
+
+## 4. 构建项目
+!`npm run build`
+
+分析所有步骤的结果，如果失败提供修复建议。
+```
+
+## 常见问题
+
+### Q1: 命令和技能有什么区别？
+
+| 特性 | 命令 | 技能 |
+|------|------|------|
+| 触发方式 | `/command-name` | Agent 按需加载 |
+| 主要用途 | 快捷执行预设任务 | 可复用工作流 |
+| 参数支持 | `$ARGUMENTS` | 无参数机制 |
+| Agent 指定 | Frontmatter | 继承 Agent |
+
+### Q2: 如何调试命令？
+
+1. 使用 `/help` 查看命令列表
+2. 执行命令查看输出
+3. 检查 Shell 输出是否正确
+4. 验证 Agent 是否正确执行
+
+### Q3: 命令可以调用其他命令吗？
+
+不可以，但可以通过 Agent 间接协作：
+```
+命令 → Agent → 技能 → 工作流
+```
+
+### Q4: 如何创建交互式命令？
+
+使用 Agent 的 `question` 工具：
+```markdown
+---
+description: 交互式组件创建
+agent: build
+---
+
+创建组件，询问用户：
+1. 组件名称
+2. 组件类型
+3. 样式方案
+
+根据用户选择创建组件。
+```
+
+## 内置命令
+
+OpenCode 包含以下内置命令：
+
+| 命令 | 说明 |
+|------|------|
+| `/init` | 初始化项目配置 |
+| `/undo` | 撤销操作 |
+| `/redo` | 重做操作 |
+| `/share` | 分享对话 |
+| `/help` | 显示帮助 |
+
+## 下一步
+
+- 🎯 [实战案例](/train/practice) - 综合应用所学知识
+- 📖 [命令示例](/commands/examples) - 更多命令示例
+- 🤖 [Agent 配置](/train/agent-basic) - 深入理解 Agent