opencode/AGENTS.md

全局规则

缩写说明

• oc = opencode（OpenCode 的缩写）

---

语言偏好

用户交互

重要：请始终使用中文（简体中文）与用户交流。

所有回复、解释、错误消息、建议和对话都应该使用中文，除非：

• 用户明确要求使用其他语言
• 技术术语在中文中没有合适的翻译（可以中英文混用，如 "React Hooks"）

代码注释

• 默认使用中文
• 遵循项目规范（如果项目有特殊要求，以项目规范为准）

独立文档文件

• 默认使用英文（.md、.txt、.rst 等文档文件）
• 只有用户明确要求使用中文时才使用中文

重要注意事项

1. 不要因为文档、命令或代码是英文就切换语言

   • 即使项目文档是英文的，对话回复时仍然用中文解释
   • 即使执行的命令是英文的，回复时仍然用中文说明
   • 即使错误信息是英文的，回复时仍然用中文分析

2. 工具输出可以保持原语言

   • 代码本身使用英文（函数名、变量名等）
   • 终端命令使用英文
   • 但你对这些内容的解释和说明必须用中文

3. 用户交互始终用中文

   • 所有对话、提问、确认都用中文
   • 所有建议、总结、分析都用中文
   • 所有错误解释和问题诊断都用中文
   • 专有名词可以使用英文

这是用户的个人偏好设置，适用于所有项目和所有交互场景。

---

回复展示规范

内容展示限制

重要：回复中不得直接展示超过 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

• 缩进：2空格
• 分号：使用分号
• 引号：优先使用双引号
• 注释：
  • 使用 JSDoc 格式书写公开函数文档
  • 复杂逻辑使用自然语言注释
  • 中文注释需说明 "为什么"，而不只是 "做什么"

一般规则

• 命名采用 camelCase（变量/函数）、PascalCase（类/组件）、UPPER_SNAKE_CASE（常量）
• 避免使用单字母变量，除非在循环中
• 函数长度不超过 100 行，优先拆分

---

开发流程

Git 提交规范

• 遵循 Conventional Commits 规范
• 格式：<type>(<scope>): <subject>
• 类型：feat（功能）、fix（修复）、docs（文档）、style（格式）、refactor（重构）、test（测试）、chore（维护）、ci、build、perf
• 主题：使用中文，简洁明了，不超过 50 字
• 描述：如有需要，空一行后补充详细说明
• 主分支：默认使用 main（不是 master）

详细的 Git 工作流程、版本管理、Tag 规范等请参考 skill/git/SKILL.md

分支命名

• 功能分支：feature/描述
• 修复分支：fix/描述
• 文档分支：docs/描述
• 示例：feature/user-authentication、fix/memory-leak

代码审查

• 提交 PR 前必须确保本地测试通过
• PR 需要至少 1 个审查者批准
• 修复所有 linter 和类型检查错误

发布流程

• 主分支（main）始终保持可部署状态
• 不直接推送到主分支，必须通过 PR
• 标签格式：
  • 单仓库（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. 运行完整的测试套件

为什么要这样做？

• 降低风险：避免一次性批量修改导致大规模错误
• 快速发现问题：在样本阶段就能发现设计或实现上的问题
• 提高质量：样本验证通过后，批量应用的质量更有保障
• 节省时间：虽然看似多一步，但能避免批量回退和重做

例外情况

以下情况可以跳过样本验证：

• 非常简单的修改（如：批量重命名变量）
• 已有充分测试覆盖的修改
• 用户明确要求直接批量修改

---

OpenCode 工具使用策略

什么时候使用各个工具

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 状态
• 用于任务规划、跟踪进度、防止遗漏

---

代码质量标准

测试要求

• 单元测试：新功能必须包含测试
• 集成测试：API 和跨模块交互需要测试
• 目标覆盖率：>= 50%
• 运行测试：提交前必须本地通过全部测试

构建和类型检查

• 类型检查必须通过：严格模式下零错误
• 构建必须成功：无警告或错误
• Linter 检查：修复所有警告，至少遵守 recommended 规则
• 运行时验证：不允许 any 类型，除非有明确注释说明原因

性能标准

• 首屏加载：< 3 秒（首次）、< 1 秒（缓存）
• 包体积：监控 bundle size，新增功能不超过 50KB
• 内存泄漏：定期检查，不允许持久化内存增长

安全要求

• 不提交敏感信息（.env、密钥等）到版本控制
• 依赖项定期更新，及时修复已知漏洞
• 输入验证和输出编码，防止 XSS、注入等攻击

---

任务管理最佳实践

使用 TodoWrite 的原则

1. 提早规划：接收任务后立即创建 todo 列表
2. 分解细节：复杂任务拆分成 3-5 个可操作的步骤
3. 实时更新：任务完成后立即标记为 completed
4. 单个进行：同时只有 1 个 in_progress，完成后再开始下一个
5. 优先级标记：高优先级任务标记为 high

任务状态定义

• pending：未开始
• in_progress：当前正在进行（限 1 个）
• completed：已完成
• cancelled：不再需要

---

常见问题和快速参考

何时创建新文件 vs 编辑现有文件？

• 优先编辑：修改现有代码和配置
• 仅在必要时创建：添加全新的功能模块或配置文件