From 861bb3aa57729b158c8c6573f37e505e4793e785 Mon Sep 17 00:00:00 2001 From: voson Date: Tue, 13 Jan 2026 11:07:37 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E7=AE=80=E5=8C=96=E5=85=A8?= =?UTF-8?q?=E5=B1=80=E8=A7=84=E5=88=99=EF=BC=8C=E6=96=B0=E5=A2=9E=E7=A6=81?= =?UTF-8?q?=E6=AD=A2=E8=87=AA=E5=8A=A8=20Git=20=E6=93=8D=E4=BD=9C=E7=9A=84?= =?UTF-8?q?=E9=99=90=E5=88=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 505 ++++++++++++------------------------------------------ 1 file changed, 107 insertions(+), 398 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ca16437..2bc978c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,448 +1,157 @@ -# 全局规则 +# OpenCode 全局规则 -## 缩写说明 - -- **oc** = opencode（OpenCode 的缩写） +## 缩写 +- **oc** = opencode --- -## 语言偏好 +## 1. 语言与交互 ### 用户交互 -**重要：请始终使用中文（简体中文）与用户交流。** +- **必须使用中文**与用户交流 +- 技术术语可中英文混用（如 "React Hooks"） +- 对话、提问、确认、建议、错误解释都用中文 -所有回复、解释、错误消息、建议和对话都应该使用中文，除非： -- 用户明确要求使用其他语言 -- 技术术语在中文中没有合适的翻译（可以中英文混用，如 "React Hooks"） - -### 代码注释 -- **默认使用中文** -- 遵循项目规范（如果项目有特殊要求，以项目规范为准） - -### 独立文档文件 -- **默认使用英文**（.md、.txt、.rst 等文档文件） -- 只有用户明确要求使用中文时才使用中文 - -### 重要注意事项 - -1. **不要因为文档、命令或代码是英文就切换语言** - - 即使项目文档是英文的，对话回复时仍然用中文解释 - - 即使执行的命令是英文的，回复时仍然用中文说明 - - 即使错误信息是英文的，回复时仍然用中文分析 - -2. **工具输出可以保持原语言** - - 代码本身使用英文（函数名、变量名等） - - 终端命令使用英文 - - 但你对这些内容的解释和说明必须用中文 - -3. **用户交互始终用中文** - - 所有对话、提问、确认都用中文 - - 所有建议、总结、分析都用中文 - - 所有错误解释和问题诊断都用中文 - - 专有名词可以使用英文 - -这是用户的个人偏好设置，适用于所有项目和所有交互场景。 +### 代码与文档 +- **代码注释**：默认中文，遵循项目规范 +- **独立文档文件**（.md、.txt）：默认英文 +- **工具输出**：可保持原语言，但解释用中文 --- -## 回复展示规范 +## 2. 回复规范 -### 内容展示限制 -**重要：回复中不得直接展示超过 100 行的内容。** +### 内容限制 +- **禁止展示超过 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，添加敏感文件保护规则 - -核心修改：用户名已脱敏，配置文件保护已加强。 -``` - -**例外情况（可以提供详细报告）：** -- 用户明确要求生成报告 -- 复杂的检查任务需要呈现检查结果 -- 错误诊断需要详细分析 +### 回复风格 +- 任务完成后简短总结（不超过 5 条要点） +- 禁止详细报告、表格、装饰性符号、重复描述 +- 例外：用户明确要求或错误诊断 ### 示例 - -❌ **错误做法：** -``` -我创建了 src/utils/helper.ts 文件，内容如下： -[粘贴 200 行完整代码] -``` - -✅ **正确做法：** -``` -已创建 src/utils/helper.ts（200 行），包含 formatDate、debounce、throttle、deepClone 等工具函数。 -``` - -❌ **错误做法（冗余总结）：** -``` -[执行了一系列操作] - -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -✅ 操作完成报告 -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -【详细的表格和统计】 -【重复的操作描述】 -【多个章节的报告】 - -━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - -[然后又生成一个"最终总结"] - -## ✅ 最终总结 - -【再次总结相同的内容】 -``` - -✅ **正确做法（简洁总结）：** -``` -✅ 已完成： -- 修改 git-add.md，添加未跟踪文件的一站式选项 -- 新增 all/u 选项可一次暂存所有文件 - -核心改进：不再需要运行两次命令。 -``` +✅ **正确**：已创建 LICENSE 文件，使用 MIT License。 +❌ **错误**：[展示完整的 License 文本内容] --- -## 代码风格偏好 +## 3. Git 操作限制 -### JavaScript/TypeScript -- **缩进**：2空格 -- **分号**：使用分号 -- **引号**：优先使用双引号 -- **注释**： - - 使用 JSDoc 格式书写公开函数文档 - - 复杂逻辑使用自然语言注释 - - 中文注释需说明 "为什么"，而不只是 "做什么" +### 🔴 严格禁止自动执行 -### 一般规则 -- 命名采用 camelCase（变量/函数）、PascalCase（类/组件）、UPPER_SNAKE_CASE（常量） -- 避免使用单字母变量，除非在循环中 -- 函数长度不超过 100 行，优先拆分 +**未经用户明确命令，禁止自动执行以下操作：** +- ❌ `git add`（暂存文件） +- ❌ `git commit`（创建提交） +- ❌ `git tag`（创建标签） +- ❌ `git push`（推送到远程） + +### 允许的场景 +✅ 用户明确使用命令：`/git-add`、`/git-commit`、`/git-push` +✅ 用户直接要求："帮我提交代码"、"推送到远程" +❌ 用户仅说："创建文件"、"修改配置"（不包含 Git 操作指令） + +### 原则 +- **创建/修改文件 ≠ 自动提交** +- **完成任务 ≠ 自动推送** +- 需要 Git 操作时，**询问用户**或**提示用户使用命令** --- -## 开发流程 +## 4. 开发规范 -### Git 提交规范 -- 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范 -- **格式**：`(): ` -- **类型**：feat（功能）、fix（修复）、docs（文档）、style（格式）、refactor（重构）、test（测试）、chore（维护）、ci、build、perf -- **主题**：使用中文，简洁明了，不超过 50 字 -- **描述**：如有需要，空一行后补充详细说明 -- **主分支**：默认使用 `main`（不是 master） +### Git 提交 +- 遵循 [Conventional Commits](https://www.conventionalcommits.org/) +- 格式：`(): `（中文） +- 类型：feat、fix、docs、style、refactor、test、chore、ci、build、perf +- 主分支：`main` -> 详细的 Git 工作流程、版本管理、Tag 规范等请参考 `skill/git/SKILL.md` +详见 `skill/git/SKILL.md` + +### 代码风格（JavaScript/TypeScript） +- 缩进：2 空格 +- 分号：使用 +- 引号：双引号 +- 命名：camelCase、PascalCase、UPPER_SNAKE_CASE ### 分支命名 -- 功能分支：`feature/描述` -- 修复分支：`fix/描述` -- 文档分支：`docs/描述` -- 示例：`feature/user-authentication`、`fix/memory-leak` - -### 代码审查 -- 提交 PR 前必须确保本地测试通过 -- PR 需要至少 1 个审查者批准 -- 修复所有 linter 和类型检查错误 - -### 发布流程 -- 主分支（main）始终保持可部署状态 -- 不直接推送到主分支，必须通过 PR -- **标签格式**： - - 单仓库（polyrepo）：`..`（如 `1.2.0`） - - 多仓库（monorepo）：`-..`（如 `ios-1.2.0`） - -> 详细的版本管理、Tag 规范和 Git 工作流程请参考 `skill/git/SKILL.md` +- `feature/描述`、`fix/描述`、`docs/描述` --- -## 批量修改策略 +## 5. 批量修改策略 -### 先验证再批量修改原则 +**原则：先修改一个，验证通过后再批量修改** -**重要：在进行批量修改时，必须遵循"先修改一个，验证通过后再批量修改"的原则。** +### 步骤 +1. 选择样本（最具代表性） +2. 修改样本 +3. 验证功能 +4. 批量应用 +5. 最终验证 -适用范围： -- **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. 运行完整的测试套件 -``` - -### 为什么要这样做？ - -- **降低风险**：避免一次性批量修改导致大规模错误 -- **快速发现问题**：在样本阶段就能发现设计或实现上的问题 -- **提高质量**：样本验证通过后，批量应用的质量更有保障 -- **节省时间**：虽然看似多一步，但能避免批量回退和重做 - -### 例外情况 - -以下情况可以跳过样本验证： -- 非常简单的修改（如：批量重命名变量） -- 已有充分测试覆盖的修改 -- 用户明确要求直接批量修改 +### 例外 +- 简单修改（如批量重命名） +- 已有测试覆盖 +- 用户明确要求 --- -## OpenCode 工具使用策略 +## 6. 工具使用策略 -### 什么时候使用各个工具 - -**Task 工具**（优先使用） -- 探索复杂、陌生的代码库结构 -- 执行多步骤的分析任务 -- 需要全局视野的搜索和研究 -- 复杂的代码重构计划 - -**Bash 工具** -- 执行系统命令和 git 操作 -- 运行构建、测试、打包命令 -- 文件系统操作（只在必要时） -- 不要用 Bash 做文件读写，改用 Read/Edit/Write 工具 - -**Read/Edit/Write 工具** -- 读取文件内容：优先用 Read，不用 cat/head/tail -- 修改现有文件：用 Edit，不用 sed/awk -- 创建新文件：用 Write，不用 echo 或 heredoc - -**Glob/Grep 工具** -- 精准查找特定文件：用 Glob（pattern 匹配） -- 搜索文件内容：用 Grep（正则表达式） -- 避免用 Bash 的 find 和 grep 命令 - -**TodoWrite 工具**（重要） -- 任务超过 3 步时必须创建 todo 列表 -- 立即标记完成，不要批量完成 -- 只有 1 个 todo 保持 in_progress 状态 -- 用于任务规划、跟踪进度、防止遗漏 +| 工具 | 用途 | +|------|------| +| **Task** | 探索代码库、多步骤分析、全局搜索 | +| **Bash** | Git 操作、构建、测试命令 | +| **Read/Edit/Write** | 文件读写（不用 cat/sed/echo） | +| **Glob/Grep** | 文件查找和内容搜索 | +| **TodoWrite** | 任务管理（超过 3 步必须使用） | --- -## 代码质量标准 +## 7. 任务管理 -### 测试要求 -- **单元测试**：新功能必须包含测试 -- **集成测试**：API 和跨模块交互需要测试 -- **目标覆盖率**：>= 50% -- 运行测试：提交前必须本地通过全部测试 +### TodoWrite 使用原则 +- 任务超过 3 步时创建 todo 列表 +- 立即标记完成（不批量完成） +- 同时只有 1 个 `in_progress` -### 构建和类型检查 -- **类型检查必须通过**：严格模式下零错误 -- **构建必须成功**：无警告或错误 -- **Linter 检查**：修复所有警告，至少遵守 recommended 规则 -- **运行时验证**：不允许 `any` 类型，除非有明确注释说明原因 - -### 性能标准 -- **首屏加载**：< 3 秒（首次）、< 1 秒（缓存） -- **包体积**：监控 bundle size，新增功能不超过 50KB -- **内存泄漏**：定期检查，不允许持久化内存增长 - -### 安全要求 -- 不提交敏感信息（.env、密钥等）到版本控制 -- 依赖项定期更新，及时修复已知漏洞 -- 输入验证和输出编码，防止 XSS、注入等攻击 +### 状态 +- `pending`、`in_progress`、`completed`、`cancelled` --- -## 任务管理最佳实践 +## 8. 代码质量 -### 使用 TodoWrite 的原则 -1. **提早规划**：接收任务后立即创建 todo 列表 -2. **分解细节**：复杂任务拆分成 3-5 个可操作的步骤 -3. **实时更新**：任务完成后立即标记为 completed -4. **单个进行**：同时只有 1 个 in_progress，完成后再开始下一个 -5. **优先级标记**：高优先级任务标记为 high +### 测试 +- 新功能必须包含测试 +- 覆盖率 ≥ 50% -### 任务状态定义 -- **pending**：未开始 -- **in_progress**：当前正在进行（限 1 个） -- **completed**：已完成 -- **cancelled**：不再需要 +### 构建 +- 类型检查零错误 +- 修复所有 Linter 警告 + +### 安全 +- 不提交敏感信息（.env、密钥） +- 输入验证和输出编码 --- -## 常见问题和快速参考 +## 快速参考 -### 何时创建新文件 vs 编辑现有文件？ -- **优先编辑**：修改现有代码和配置 -- **仅在必要时创建**：添加全新的功能模块或配置文件 +| 场景 | 操作 | +|------|------| +| 用户说"创建文件" | 创建文件，**不自动提交** | +| 用户说"提交代码" | 可以执行 `git commit` | +| 用户使用 `/git-push` | 执行完整推送流程 | +| 创建超过 100 行的文件 | 只说明路径和用途，**不展示内容** | +| 命令输出已完整 | 直接展示，**不重复总结** | +| 批量修改 10 个文件 | 先改 1 个验证，再批量 | + +--- + +详细指南： +- Git 工作流：`skill/git/SKILL.md` +- Gitea 集成：`skill/gitea/SKILL.md` +- 开发规范：各 `skill/*/SKILL.md`