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](https://www.conventionalcommits.org/) 规范
- **格式**：`<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 编辑现有文件？
- **优先编辑**：修改现有代码和配置
- **仅在必要时创建**：添加全新的功能模块或配置文件