172 lines
5.5 KiB
Markdown
172 lines
5.5 KiB
Markdown
# 全局规则
|
||
|
||
## 缩写说明
|
||
|
||
- **oc** = opencode（OpenCode 的缩写）
|
||
|
||
---
|
||
|
||
## 语言偏好
|
||
|
||
**重要：请始终使用中文（简体中文）与用户交流。**
|
||
|
||
所有回复、解释、错误消息、建议和对话都应该使用中文，除非：
|
||
- 代码注释需要使用英文（根据项目规范）
|
||
- 用户明确要求使用其他语言
|
||
- 技术术语在中文中没有合适的翻译（可以中英文混用，如 "React Hooks"）
|
||
|
||
### 重要注意事项
|
||
|
||
1. **不要因为文档、命令或代码是英文就切换语言**
|
||
- 即使项目文档是英文的，回复时仍然用中文解释
|
||
- 即使执行的命令是英文的，回复时仍然用中文说明
|
||
- 即使错误信息是英文的，回复时仍然用中文分析
|
||
|
||
2. **工具输出可以保持原语言**
|
||
- 代码本身使用英文（函数名、变量名等）
|
||
- 终端命令使用英文
|
||
- 但你对这些内容的解释和说明必须用中文
|
||
|
||
3. **用户交互始终用中文**
|
||
- 所有对话、提问、确认都用中文
|
||
- 所有建议、总结、分析都用中文
|
||
- 所有错误解释和问题诊断都用中文
|
||
|
||
这是用户的个人偏好设置，适用于所有项目和所有交互场景。
|
||
|
||
---
|
||
|
||
## 代码风格偏好
|
||
|
||
### JavaScript/TypeScript
|
||
- **缩进**：2空格
|
||
- **分号**：使用分号
|
||
- **引号**：优先使用双引号
|
||
- **注释**：
|
||
- 使用 JSDoc 格式书写公开函数文档
|
||
- 复杂逻辑使用自然语言注释
|
||
- 中文注释需说明 "为什么"，而不只是 "做什么"
|
||
|
||
### 一般规则
|
||
- 命名采用 camelCase（变量/函数）、PascalCase（类/组件）、UPPER_SNAKE_CASE（常量）
|
||
- 避免使用单字母变量，除非在循环中
|
||
- 函数长度不超过 100 行，优先拆分
|
||
|
||
---
|
||
|
||
## 开发流程
|
||
|
||
### Git 提交规范
|
||
- **格式**：`<type>(<scope>): <subject>`
|
||
- **类型**：feat（功能）、fix（修复）、docs（文档）、style（格式）、refactor（重构）、test（测试）、chore（维护）
|
||
- **主题**：使用中文，简洁明了，不超过 50 字
|
||
- **描述**：如有需要，空一行后补充详细说明
|
||
|
||
### 分支命名
|
||
- 功能分支：`feature/描述`
|
||
- 修复分支：`fix/描述`
|
||
- 文档分支：`docs/描述`
|
||
- 示例：`feature/user-authentication`、`fix/memory-leak`
|
||
|
||
### 代码审查
|
||
- 提交 PR 前必须确保本地测试通过
|
||
- PR 需要至少 1 个审查者批准
|
||
- 修复所有 linter 和类型检查错误
|
||
|
||
### 发布流程
|
||
- 主分支（main/master）始终保持可部署状态
|
||
- 不直接推送到主分支，必须通过 PR
|
||
- 标签格式：`v<major>.<minor>.<patch>`
|
||
|
||
---
|
||
|
||
## 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 和跨模块交互需要测试
|
||
- **目标覆盖率**：>= 80%
|
||
- 运行测试：提交前必须本地通过全部测试
|
||
|
||
### 构建和类型检查
|
||
- **类型检查必须通过**：严格模式下零错误
|
||
- **构建必须成功**：无警告或错误
|
||
- **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**：不再需要
|
||
|
||
---
|
||
|
||
## 常见问题和快速参考
|
||
|
||
### 如何列出所有可用命令？
|
||
按下 `ctrl+p` 可查看 OpenCode 的所有可用操作。
|
||
|
||
### 如何获取帮助或反馈？
|
||
- 在 GitHub 提交 issue：https://github.com/anomalyco/opencode
|
||
- 查看官方文档：https://opencode.ai/docs
|
||
|
||
### 何时创建新文件 vs 编辑现有文件？
|
||
- **优先编辑**：修改现有代码和配置
|
||
- **仅在必要时创建**：添加全新的功能模块或配置文件
|