AGENTS.md

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

项目背景与技术栈

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

Git 分支约束

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

Cloudflare 自动部署约束

当用户要求“根据 GitHub 项目链接把本项目安装部署到 Cloudflare”时，应优先按 docs/agent-deploy-cloudflare.md 执行。

推荐流程：

bun install
EDGE_EVER_PASSWORD='<首次登录密码>' bun run deploy:setup
bun run deploy:doctor
bun run deploy

首次部署与验证成功后，应优先执行 bun run deploy:builds:setup，按 docs/cloudflare-workers-builds.md 将该 Worker 连接到 Fork 的 main 分支，并将 .env.local 中的实例配置写入 Cloudflare Workers Builds 的 Build Variables/Secrets。只有 Cloudflare GitHub App 的浏览器授权和 Build Token 选择无法由 API 自动完成；应由 Agent 尽可能代办，并在需要用户确认时给出文档中的精确路径。之后 GitHub Sync fork 触发 Cloudflare 自动构建、执行 D1 migration 并发布；不要为此新增 GitHub Actions Worker 部署流程。

如果用户没有提供首次登录密码，应只询问这一个必要信息，或在用户同意后生成随机密码。Cloudflare 授权、账号、D1/R2 资源、Worker 名称、自定义域名等私有配置必须来自用户环境、Cloudflare MCP/插件、Wrangler 登录态或 .env.local，严禁硬编码到仓库文件。

部署脚本必须通过 scripts/run-wrangler.mjs 读取 .env.local 并生成临时 Wrangler 配置。不要直接修改 wrangler.toml 来写入个人 database_id、bucket 名称、Worker 名称或 route。

本地启动约束

本地预览或调试时，必须优先使用 bun run dev 启动完整开发环境，让 API 通过 scripts/run-wrangler.mjs 读取 .env.local 中的个性化实例配置。实例名称、D1/R2 资源、账号等本机私有配置均以 .env.local 为准，严禁在代理指令或代码中硬编码个人实例名。

除非用户明确要求只启动前端静态界面，否则不要单独运行 bun run dev:web；该命令不会启动 API，也不会保证读取 .env.local 中的实例配置，容易导致前端请求 127.0.0.1:8787 失败或误判环境。

组件复用与造轮子约束

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

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

2.9 KiB Raw Blame History