5.5 KiB
5.5 KiB
全局规则
缩写说明
- oc = opencode（OpenCode 的缩写）
语言偏好
重要：请始终使用中文（简体中文）与用户交流。
所有回复、解释、错误消息、建议和对话都应该使用中文，除非：
- 代码注释需要使用英文（根据项目规范）
- 用户明确要求使用其他语言
- 技术术语在中文中没有合适的翻译（可以中英文混用，如 "React Hooks"）
重要注意事项
-
不要因为文档、命令或代码是英文就切换语言
- 即使项目文档是英文的，回复时仍然用中文解释
- 即使执行的命令是英文的，回复时仍然用中文说明
- 即使错误信息是英文的，回复时仍然用中文分析
-
工具输出可以保持原语言
- 代码本身使用英文（函数名、变量名等）
- 终端命令使用英文
- 但你对这些内容的解释和说明必须用中文
-
用户交互始终用中文
- 所有对话、提问、确认都用中文
- 所有建议、总结、分析都用中文
- 所有错误解释和问题诊断都用中文
这是用户的个人偏好设置，适用于所有项目和所有交互场景。
代码风格偏好
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 的原则
- 提早规划：接收任务后立即创建 todo 列表
- 分解细节：复杂任务拆分成 3-5 个可操作的步骤
- 实时更新：任务完成后立即标记为 completed
- 单个进行：同时只有 1 个 in_progress，完成后再开始下一个
- 优先级标记：高优先级任务标记为 high
任务状态定义
- pending：未开始
- in_progress：当前正在进行（限 1 个）
- completed：已完成
- cancelled：不再需要
常见问题和快速参考
如何列出所有可用命令？
按下 ctrl+p 可查看 OpenCode 的所有可用操作。
如何获取帮助或反馈？
- 在 GitHub 提交 issue：https://github.com/anomalyco/opencode
- 查看官方文档：https://opencode.ai/docs
何时创建新文件 vs 编辑现有文件？
- 优先编辑：修改现有代码和配置
- 仅在必要时创建：添加全新的功能模块或配置文件