chore: 重构 OpenCode 命令和技能文档体系
- 新增：统一的 git 命令文档（add/commit/push/pull 等） - 新增：整合的 Gitea 技能文档（API、运行器、工作流等） - 新增：工作流模板（Android、Go、Node.js 等） - 移除：已弃用的旧命令脚本和发布脚本 - 改进：.gitignore 添加敏感文件保护规则 - 改进：AGENTS.md 完善了开发规范和示例 此次重组统一了命令和技能的文档结构，便于后续维护和扩展。
This commit is contained in:
Voson
303
AGENTS.md
303
AGENTS.md
@@ -8,17 +8,25 @@
|
||||
|
||||
## 语言偏好
|
||||
|
||||
### 用户交互
|
||||
**重要：请始终使用中文（简体中文）与用户交流。**
|
||||
|
||||
所有回复、解释、错误消息、建议和对话都应该使用中文，除非：
|
||||
- 代码注释需要使用英文（根据项目规范）
|
||||
- 用户明确要求使用其他语言
|
||||
- 技术术语在中文中没有合适的翻译（可以中英文混用，如 "React Hooks"）
|
||||
|
||||
### 代码注释
|
||||
- **默认使用中文**
|
||||
- 遵循项目规范（如果项目有特殊要求，以项目规范为准）
|
||||
|
||||
### 独立文档文件
|
||||
- **默认使用英文**（.md、.txt、.rst 等文档文件）
|
||||
- 只有用户明确要求使用中文时才使用中文
|
||||
|
||||
### 重要注意事项
|
||||
|
||||
1. **不要因为文档、命令或代码是英文就切换语言**
|
||||
- 即使项目文档是英文的，回复时仍然用中文解释
|
||||
- 即使项目文档是英文的，对话回复时仍然用中文解释
|
||||
- 即使执行的命令是英文的，回复时仍然用中文说明
|
||||
- 即使错误信息是英文的，回复时仍然用中文分析
|
||||
|
||||
@@ -31,11 +39,202 @@
|
||||
- 所有对话、提问、确认都用中文
|
||||
- 所有建议、总结、分析都用中文
|
||||
- 所有错误解释和问题诊断都用中文
|
||||
- 专有名词可以使用英文
|
||||
|
||||
这是用户的个人偏好设置，适用于所有项目和所有交互场景。
|
||||
|
||||
---
|
||||
|
||||
## 回复展示规范
|
||||
|
||||
### 内容展示限制
|
||||
**重要：回复中不得直接展示超过 100 行的内容。**
|
||||
|
||||
适用范围：
|
||||
- 文档内容（.md、.txt、.rst 等）
|
||||
- 代码文件（.js、.ts、.py、.go 等）
|
||||
- 配置文件
|
||||
- 任何其他文本内容
|
||||
|
||||
### 长内容处理原则
|
||||
|
||||
1. **创建文件时（超过 100 行）**
|
||||
- 首先考虑：是否可以拆分成多个模块？
|
||||
- 优先使用模块化设计，拆分成多个小文件
|
||||
- 如果确实应该保持单一文件（如：配置文件、工具类等）：
|
||||
- 只告知用户文件已创建
|
||||
- 提供文件路径
|
||||
- 说明文件用途和关键特性
|
||||
- 不要在回复中粘贴完整内容
|
||||
|
||||
2. **展示修改时**
|
||||
- 只展示核心、关键的改动部分
|
||||
- 使用代码片段展示（通常 10-30 行）
|
||||
- 用省略号（...）表示被省略的部分
|
||||
- 说明改动的位置和目的
|
||||
|
||||
3. **提供概览时**
|
||||
- 使用摘要和要点列表
|
||||
- 展示关键函数签名或接口定义
|
||||
- 提供文件路径供用户自行查看
|
||||
|
||||
### 回复简洁性要求
|
||||
|
||||
**必须隐藏的内容：**
|
||||
- 完整的文件内容（超过 100 行）
|
||||
- 详细的执行日志（除非有错误需要诊断）
|
||||
- 重复性的代码模式
|
||||
- 自动生成的代码（如类型定义、配置模板等）
|
||||
|
||||
**必须展示的内容：**
|
||||
- 核心改动代码片段（< 50 行）
|
||||
- 关键错误信息
|
||||
- 重要的配置修改
|
||||
- 用户需要注意的变更点
|
||||
|
||||
### 文件操作展示规范
|
||||
|
||||
**重要：CRUD 文件时，只需总结操作结果，无需展示具体变更内容。**
|
||||
|
||||
适用于以下操作：
|
||||
- **Create（创建）**：创建新文件
|
||||
- **Read（读取）**：读取文件内容（除非用户明确要求展示）
|
||||
- **Update（更新）**：修改现有文件
|
||||
- **Delete（删除）**：删除文件
|
||||
|
||||
**展示原则：**
|
||||
- ✅ 说明操作类型（创建、修改、删除）
|
||||
- ✅ 提供文件路径
|
||||
- ✅ 简要说明改动的目的和影响
|
||||
- ❌ 不展示具体的代码变更内容
|
||||
- ❌ 不展示文件的完整内容
|
||||
|
||||
**示例：**
|
||||
|
||||
✅ **正确做法：**
|
||||
```
|
||||
已修改 src/config/settings.ts，更新了数据库连接配置。
|
||||
```
|
||||
|
||||
❌ **错误做法：**
|
||||
```
|
||||
已修改 src/config/settings.ts：
|
||||
[展示修改前后的代码对比]
|
||||
```
|
||||
|
||||
### 避免重复命令输出
|
||||
|
||||
**重要：不要重复或总结命令输出中已有的内容。**
|
||||
|
||||
当命令输出已经包含完整信息时（如：状态、操作步骤、使用说明等）：
|
||||
- ✅ 直接展示命令输出即可
|
||||
- ❌ 不要在命令输出后再次总结相同的内容
|
||||
- ❌ 不要重复命令中已提供的操作指令
|
||||
|
||||
**例外情况：**
|
||||
- 命令出错需要分析和解释
|
||||
- 需要提取关键信息进行下一步操作
|
||||
- 用户明确要求总结
|
||||
|
||||
**示例：**
|
||||
|
||||
❌ **错误做法：**
|
||||
```
|
||||
[命令输出：包含完整的 runner 列表、状态、启动命令]
|
||||
|
||||
✅ 已成功列出所有 Gitea Runners！
|
||||
|
||||
当前状态：
|
||||
- 总计：1 个 runner
|
||||
- 名称：runner-mac-mini4
|
||||
- 状态：已停止
|
||||
|
||||
快速操作：
|
||||
如需启动，执行：[重复命令输出中的启动命令]
|
||||
```
|
||||
|
||||
✅ **正确做法：**
|
||||
```
|
||||
[命令输出：包含完整的 runner 列表、状态、启动命令]
|
||||
|
||||
（直接展示命令输出，无需额外总结）
|
||||
```
|
||||
|
||||
### 任务完成后的回复规范
|
||||
|
||||
**重要：避免冗余的总结报告，保持简洁。**
|
||||
|
||||
任务完成后，只需要提供一个简短的总结，包含：
|
||||
1. ✅ 已完成的操作（使用要点列表，不超过 5 条）
|
||||
2. 📝 核心修改内容（1-2 句话概括）
|
||||
3. ⚠️ 需要注意的事项（如果有）
|
||||
|
||||
**禁止的做法：**
|
||||
- ❌ 生成详细的表格报告（如"检查报告"、"修复报告"）
|
||||
- ❌ 生成多个总结（"总结报告" + "最终总结"）
|
||||
- ❌ 使用大量装饰性符号和分隔线
|
||||
- ❌ 重复描述已经执行过的步骤
|
||||
- ❌ 生成统计数据（除非用户明确要求）
|
||||
|
||||
**推荐的做法：**
|
||||
```
|
||||
✅ 已完成：
|
||||
- 修改了 7 个文件，替换用户名为占位符
|
||||
- 更新 .gitignore，添加敏感文件保护规则
|
||||
|
||||
核心修改：用户名已脱敏，配置文件保护已加强。
|
||||
```
|
||||
|
||||
**例外情况（可以提供详细报告）：**
|
||||
- 用户明确要求生成报告
|
||||
- 复杂的检查任务需要呈现检查结果
|
||||
- 错误诊断需要详细分析
|
||||
|
||||
### 示例
|
||||
|
||||
❌ **错误做法：**
|
||||
```
|
||||
我创建了 src/utils/helper.ts 文件，内容如下：
|
||||
[粘贴 200 行完整代码]
|
||||
```
|
||||
|
||||
✅ **正确做法：**
|
||||
```
|
||||
已创建 src/utils/helper.ts（200 行），包含 formatDate、debounce、throttle、deepClone 等工具函数。
|
||||
```
|
||||
|
||||
❌ **错误做法（冗余总结）：**
|
||||
```
|
||||
[执行了一系列操作]
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
✅ 操作完成报告
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
【详细的表格和统计】
|
||||
【重复的操作描述】
|
||||
【多个章节的报告】
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
[然后又生成一个"最终总结"]
|
||||
|
||||
## ✅ 最终总结
|
||||
|
||||
【再次总结相同的内容】
|
||||
```
|
||||
|
||||
✅ **正确做法（简洁总结）：**
|
||||
```
|
||||
✅ 已完成：
|
||||
- 修改 git-add.md，添加未跟踪文件的一站式选项
|
||||
- 新增 all/u 选项可一次暂存所有文件
|
||||
|
||||
核心改进：不再需要运行两次命令。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 代码风格偏好
|
||||
|
||||
### JavaScript/TypeScript
|
||||
@@ -57,10 +256,14 @@
|
||||
## 开发流程
|
||||
|
||||
### Git 提交规范
|
||||
- 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范
|
||||
- **格式**：`<type>(<scope>): <subject>`
|
||||
- **类型**：feat（功能）、fix（修复）、docs（文档）、style（格式）、refactor（重构）、test（测试）、chore（维护）
|
||||
- **类型**：feat（功能）、fix（修复）、docs（文档）、style（格式）、refactor（重构）、test（测试）、chore（维护）、ci、build、perf
|
||||
- **主题**：使用中文，简洁明了，不超过 50 字
|
||||
- **描述**：如有需要，空一行后补充详细说明
|
||||
- **主分支**：默认使用 `main`（不是 master）
|
||||
|
||||
> 详细的 Git 工作流程、版本管理、Tag 规范等请参考 `skill/git/SKILL.md`
|
||||
|
||||
### 分支命名
|
||||
- 功能分支：`feature/描述`
|
||||
@@ -74,9 +277,90 @@
|
||||
- 修复所有 linter 和类型检查错误
|
||||
|
||||
### 发布流程
|
||||
- 主分支（main/master）始终保持可部署状态
|
||||
- 主分支（main）始终保持可部署状态
|
||||
- 不直接推送到主分支，必须通过 PR
|
||||
- 标签格式：`v<major>.<minor>.<patch>`
|
||||
- **标签格式**：
|
||||
- 单仓库（polyrepo）：`<major>.<minor>.<patch>`（如 `1.2.0`）
|
||||
- 多仓库（monorepo）：`<subproject>-<major>.<minor>.<patch>`（如 `ios-1.2.0`）
|
||||
|
||||
> 详细的版本管理、Tag 规范和 Git 工作流程请参考 `skill/git/SKILL.md`
|
||||
|
||||
---
|
||||
|
||||
## 批量修改策略
|
||||
|
||||
### 先验证再批量修改原则
|
||||
|
||||
**重要：在进行批量修改时，必须遵循"先修改一个，验证通过后再批量修改"的原则。**
|
||||
|
||||
适用范围：
|
||||
- **Command（命令）**：修改或新增多个命令时
|
||||
- **Skill（技能）**：修改或新增多个技能时
|
||||
- **代码功能**：批量修改多个文件或多个函数时
|
||||
- **配置文件**：批量修改多个配置项时
|
||||
|
||||
### 执行步骤
|
||||
|
||||
1. **选择样本**
|
||||
- 从批量修改的目标中选择 1 个作为样本
|
||||
- 优先选择最具代表性或最复杂的一个
|
||||
|
||||
2. **修改样本**
|
||||
- 完成样本的修改
|
||||
- 确保代码质量和规范
|
||||
|
||||
3. **验证样本**
|
||||
- 运行相关测试
|
||||
- 检查功能是否正常
|
||||
- 确认修改符合预期
|
||||
|
||||
4. **批量应用**
|
||||
- 验证通过后，将相同的修改应用到其他目标
|
||||
- 保持一致性和规范性
|
||||
|
||||
5. **最终验证**
|
||||
- 批量修改完成后，运行全局测试
|
||||
- 确保所有修改都正常工作
|
||||
|
||||
### 示例场景
|
||||
|
||||
**场景 1：批量修改多个命令**
|
||||
```
|
||||
用户要求：给所有命令添加错误处理逻辑
|
||||
|
||||
正确做法：
|
||||
1. 选择 1 个命令作为样本（如：最复杂的命令）
|
||||
2. 添加错误处理逻辑
|
||||
3. 测试该命令是否正常工作
|
||||
4. 验证通过后，批量应用到其他命令
|
||||
5. 运行所有命令的测试
|
||||
```
|
||||
|
||||
**场景 2：批量重构代码**
|
||||
```
|
||||
用户要求：重构 10 个相似的函数，改用新的设计模式
|
||||
|
||||
正确做法：
|
||||
1. 选择 1 个函数进行重构
|
||||
2. 编写测试确保功能正确
|
||||
3. Code Review 确认设计合理
|
||||
4. 批量重构其他 9 个函数
|
||||
5. 运行完整的测试套件
|
||||
```
|
||||
|
||||
### 为什么要这样做？
|
||||
|
||||
- **降低风险**：避免一次性批量修改导致大规模错误
|
||||
- **快速发现问题**：在样本阶段就能发现设计或实现上的问题
|
||||
- **提高质量**：样本验证通过后，批量应用的质量更有保障
|
||||
- **节省时间**：虽然看似多一步，但能避免批量回退和重做
|
||||
|
||||
### 例外情况
|
||||
|
||||
以下情况可以跳过样本验证：
|
||||
- 非常简单的修改（如：批量重命名变量）
|
||||
- 已有充分测试覆盖的修改
|
||||
- 用户明确要求直接批量修改
|
||||
|
||||
---
|
||||
|
||||
@@ -119,7 +403,7 @@
|
||||
### 测试要求
|
||||
- **单元测试**：新功能必须包含测试
|
||||
- **集成测试**：API 和跨模块交互需要测试
|
||||
- **目标覆盖率**：>= 80%
|
||||
- **目标覆盖率**：>= 50%
|
||||
- 运行测试：提交前必须本地通过全部测试
|
||||
|
||||
### 构建和类型检查
|
||||
@@ -159,13 +443,6 @@
|
||||
|
||||
## 常见问题和快速参考
|
||||
|
||||
### 如何列出所有可用命令？
|
||||
按下 `ctrl+p` 可查看 OpenCode 的所有可用操作。
|
||||
|
||||
### 如何获取帮助或反馈？
|
||||
- 在 GitHub 提交 issue：https://github.com/anomalyco/opencode
|
||||
- 查看官方文档：https://opencode.ai/docs
|
||||
|
||||
### 何时创建新文件 vs 编辑现有文件？
|
||||
- **优先编辑**：修改现有代码和配置
|
||||
- **仅在必要时创建**：添加全新的功能模块或配置文件
|
||||
|
||||
Reference in New Issue
Block a user