AGENTS.md

本文件用于约束和指导参与本项目的 AI 代理与协作者。除非用户明确给出更高优先级的指令，否则应遵守以下规则。

项目背景与技术栈

涉及本项目的背景、定位、部署信息与技术栈说明时，请优先参考 README.md。

中英文文档同步约束

修改中文文档时，必须同步更新对应的英文文档，确保内容一致。

Git 分支约束

严禁创建新的 Git 分支；所有修改、提交和推送都必须直接在 main 分支上完成。

GitHub Issue 与 Release 约束

正式版本遵循 Semantic Versioning。发布前检查最新 Release 和远端标签，选择未使用的版本号。Git 标签与 Release 标题必须完全一致，格式为 vX.Y.Z。每个正式版本标签必须与一个已发布的 GitHub Release 一一对应，不得遗留只有标签、没有 Release 的正式版本；发现历史遗留的孤立正式标签时，应先识别并处理其影响，再继续发布新版本。

Release 正文必须以上一个实际发布的正式 GitHub Release 为变更基线，完整审计从该 Release 标签到本次发布提交之间的全部提交，并面向用户汇总其中所有可感知变化，不得直接复制提交记录，也不得只说明当前任务或最新一次提交。若中间存在只有 Git 标签、没有对应 GitHub Release 的版本，不得将其视为发布基线；应继续回溯到最近一个实际存在的正式 Release。正文应覆盖该完整区间内的功能、修复、界面、文档及其他用户可感知变化；变更较多、需要审计或方便开发者追溯时，可按需附上 GitHub Compare 链接。

Release 标签必须指向 main 上经过验证的发布提交；默认发布为非 Draft、非 Prerelease。发布正文使用以下结构：

## 主要更新

- 面向用户说明本次变化及影响。

关联 Issue：#<issue-number>

## 验证

- 列出实际完成的测试、类型检查和构建结果。

每个功能或修复 Release 必须关联带有对应 Label 的 GitHub Issue；没有 Issue 时先创建。发布后在 Issue 中回链 Release，并按完成状态关闭。验证失败时不得发布正式 Release。

Cloudflare 自动部署约束

当用户要求根据 GitHub 项目链接将本项目安装部署到 Cloudflare 时，必须先完整阅读并严格按照 docs/agent-deploy-cloudflare.md 执行。该文档是此部署流程的唯一操作规范；不要在本文件重复维护部署命令、密码配置或 Workers Builds 步骤。

本地启动约束

默认使用 bun run dev 启动完整本地环境（本地 D1/R2 和固定演示种子），不得连接 .env.local 中的远程实例。
仅在用户明确指定远程实例并要求连接时，使用 EDGE_EVER_INSTANCE=<实例名> bun run dev:remote；私有配置以 .env.local 为准，不得硬编码实例名。
仅在用户明确要求只启动前端时使用 bun run dev:web。

组件复用与造轮子约束

UI 功能应尽量复用 shadcn/ui 等现有 UI 组件。在实现其他功能时，也应优先采用成熟、稳定的开源组件或库，绝对禁止在没有充分必要性的前提下自行从零造轮子。

为方便代码维护，当页面或功能模块出现复杂结构、重复布局或潜在复用场景时，应视情况封装为独立组件，保持页面入口聚焦于组合与数据传递。

3.4 KiB Raw Blame History Unescape Escape