贡献指南

以下约定用于保持代码库的一致性。它们同时适用于人类贡献者与自动化 agent。

包管理器

• 使用 Bun 作为主要包管理器。
• 用 bun install 安装依赖。
• 用 bun run <script> 运行脚本。
• 用 bun add <package> 添加依赖。
• 提交 bun.lock。

样式

• 全局设计不使用内联样式。使用由组件/页面导入的集中式样式文件（见 src/styles.ts）。

测试

• 为每个请求的行为或变更编写测试。
• 不要为了迁就代码改动而修改或删除测试。

测试通过 @cloudflare/vitest-pool-workers 在真实的 Workers 运行时中执行。见 本地开发。

国际化

• 所有管理页面/组件中面向用户的字符串都经由 t() 处理，并存放在翻译文件中。
• 新的 UI 文案先加入翻译文件（src/i18n/en.ts 为唯一事实来源），再通过 t("namespace.key") 引用。
• 英语是唯一事实来源与回退；id.ts 与 sv.ts 必须保持键的一致性。

数据库迁移

• 保留所有既有数据。
• 当重建被 ON DELETE CASCADE 外键引用的表时，先保存并删除依赖表，重命名后再恢复。
• 迁移后验证所有受影响表的行数不变。

迁移列表与命令见 数据库与迁移。

SDK 一致性

• 对 sdk/ 下任一 SDK 的改动都需要评估并同步到其他 SDK。
• 所有 SDK 的 README 保持同步，仅按语言习惯做必要调整。

发布相关细节见 发布流程。

仓库规则

• 永不 force push。
• 使用 GPG 签名的提交。
• 若无法签名或签名失败，则不创建提交。改为输出带 -S 的完整 git commit 命令，供用户稍后执行。
• 提交信息中不含 "Co-Authored-By" 行。
• 保持提交逻辑分组、聚焦。

写作规则

适用于文档、更新日志条目和面向用户的文案：

• 优先使用具体词而非笼统词。
• 不使用破折号 (em dash)。
• 不使用空洞的强调词。
• 默认使用主动语态。
• 拆分超过两个从句的句子。
• 不使用清嗓子式的开场白。

文档规则

• 不要硬编码可能漂移的动态内容。直接引用源头（例如 MCP 工具列表应链接到 src/mcp/server.ts，而非复制一份）。