本文是所有接手 USTSACMLand 的 Agent 的根级入口。无论任务来自新会话、自动化任务还是其他 Agent 的交接，都必须先完整阅读本文，再阅读与任务直接相关的专项文档。
USTSACMLand 是苏州科技大学 ACM 集训队官网。当前正式产品范围包括：
- 集训队与算法竞赛介绍、校内赛事入口和新手学习引导；
- 成员、平台账号、Rating 与刷题榜单；
- 注册、登录、邮箱确认、找回密码、账号资料和训练目标；
- 管理员成员管理、平台数据维护、同步状态和生产配置；
- Codeforces、牛客、AtCoder、洛谷、QOJ 与 XCPC ELO 数据同步；
- GitHub Pages、Cloudflare 自定义域名、Supabase 数据库与 Edge Functions。
正式站点为 https://ustsacm.fun/。当前事实必须从代码、ROADMAP.md、GitHub、Supabase 和生产只读检查中重新确认，不得把旧会话、旧截图或本文中的概述当作实时状态。
WebChat / AI 学习助手、图片输入和推荐计划已经暂停并退出当前产品范围。保留其代码、Schema、migration、函数、测试、后台配置和历史数据边界，不删除、不重新开发、不向普通成员显示，也不打开生产开关。只允许处理关闭态安全、Schema 兼容、备份、注销和数据保护回归。
所有可由仓库工具、CLI、浏览器、供应商控制台或自动化完成的开发和维护工作都由 Agent 执行，包括：
- 需求分析、代码实现、测试、视觉检查和文档更新；
- issue / PR、CI、合并、发布、部署、回滚和发布后观察；
- 数据同步巡检、失败诊断、队列维护和受控重跑；
- migration、Edge Function、备份、恢复演练和凭据轮换编排；
- 管理员操作、生产烟测、故障处置、证据记录和下一次交接。
不要把 Agent 能完成的步骤转交给项目负责人。需要网页操作时由 Agent 使用已授权的 Chrome 会话；需要命令时由 Agent 执行命令；需要等待 CI 或部署时由 Agent 持续监控到终态。
项目负责人只负责 Agent 无法代替的事项：
- 输入或更新密码、API Key、MFA、验证码、恢复材料和付款信息；
- 完成实名认证、供应商申诉、域名续费等必须由账号持有人进行的行为；
- 决定许可证、品牌授权、产品范围、费用和风险接受；
- 对不可逆、删除性、高费用或高风险生产变更给出明确批准。
负责人提供输入或批准后，Agent 应立即接回后续操作、验证和记录，不要求负责人继续完成可自动执行的步骤。若已有登录态或所需授权，Agent 应直接工作，不重复索取凭据。
项目接受只有一名真人持有账号恢复能力的风险。Agent 能接管全部日常工作，但不能在负责人失联时取代其 MFA、实名域名、付款方式或法律责任。
任何写操作前依次完成：
- 完整阅读本文件、
ROADMAP.md和任务涉及的专项文档。 - 检查
git status -sb、当前分支、远端、默认分支、最近提交和未跟踪文件。 - 区分用户已有修改、本任务修改和生成物；不得覆盖或清理来源不明的改动。
- 检查任务涉及的 GitHub PR / Actions / Pages、Supabase migration / Functions / cron 或 Cloudflare 状态。
- 明确当前事实、任务范围、验证方式、回滚方式及需要负责人输入或批准的唯一事项。
- 向用户简短报告所见状态和执行计划，然后持续工作到任务终态。
冷启动时优先使用只读检查。诊断结论必须来自代码、日志、状态接口或可复现结果，不能仅依赖历史对话。
- 阅读仓库、文档、Git 历史、PR、Actions 和公开生产页面。
- 运行本地 lint、类型检查、测试、构建、格式检查和只读健康检查。
- 在用户要求修改或开发时编辑任务范围内的代码、测试和文档。
- 在用户要求诊断时完成只读排查并给出证据；除非请求同时包含修复，不擅自扩大为生产写操作。
- 在用户明确要求提交、推送、合并、部署、发布或回滚后，执行完整流程并监控到终态。
- 应用生产 migration 或修改生产 RLS、Auth、Vault、cron、Function Secret；
- 部署会改变生产数据行为的 Edge Function；
- 修改 Cloudflare DNS、TLS、缓存规则、自定义域名或执行大范围 Purge；
- 触发恢复、改变恢复下限、删除生产数据、注销账号或批量改写成员数据；
- 轮换密码、Cookie、CSRF、API Key、队列 Token、备份口令或恢复 Token；
- 提升或降级管理员、创建正式版本标签、执行产生明显费用的操作。
批准只覆盖已说明的目标、范围和本次执行。得到批准后由 Agent 完成操作，不再把执行步骤退回给负责人。操作结果不确定时先只读对账，禁止重复点击或盲目重放写请求。
- 读取、回显、复制到聊天、写入命令历史、日志、截图或 Git 的密码、Token、Cookie、JWT、恢复码、浏览器存储或成员私有数据；
- 绕过 MFA、验证码、分支保护、Environment 审批、RLS、速率限制或第三方反自动化措施；
- 发起网络安全探测、爆破、请求洪泛、漏洞利用或故意触发第三方封禁；
- 使用
git reset --hard、强推默认分支、重写已部署 migration、删除未知文件或覆盖他人改动； - 未经重新立项开启 WebChat、图片输入或推荐计划；
- 用演示数据、缓存页面或旧截图冒充生产验证结果。
- 默认 ASCII；已有中文文档和界面可继续使用中文。
- 手工编辑使用
apply_patch；格式化和明确的机械批量改写可使用项目工具。 - 搜索优先使用
rg；可并行的只读检查并行执行。 - 始终先查看工作树。来源不明的改动视为用户修改并保留。
- 只暂存本任务文件，工作树混杂时逐文件
git add，不使用无差别git add -A。 - 不提交
.claude/、.agents/、.cli-home/、.codex-tmp/、.firecrawl/、.playwright/、artifacts/、dist/、test-results/、日志、截图、导出、备份和本地环境文件。 - 不读取或提交
.env*中的真实值。配置契约只通过.env.example和文档维护。 - 不进行与当前任务无关的重构、格式 churn、依赖升级或元数据改写。
- 除非用户明确要求，不提交、不推送、不合并、不部署。
如果使用子 Agent，必须给出边界清晰、可独立完成的子任务和文件所有权，并提醒其共享工作树、保留其他人的改动。主 Agent 负责整合、复核和最终验证，不能把子 Agent 的结论未经检查直接作为完成证据。
每项开发按以下顺序完成：
- 阅读现有实现、测试、数据契约和设计规范。
- 找到根因或明确产品行为，再做最小范围修改。
- 补充与风险相称的单元、集成、数据库或 E2E 测试。
- 运行最接近改动面的验证，再运行必要的共享门禁。
- 前端变更使用 Chrome 检查桌面、390px 移动端和宽屏；检查交互、控制台、溢出、文字遮挡和截图。
- 数据库或生产变更先写兼容顺序与回滚计划，按“数据库 -> Edge Functions -> Pages”执行。
- 更新
ROADMAP.md、运行手册或证据文档中的真实状态；只有确认完成的条目才从- [ ]改为- [x]。 - 复查 diff，确认没有 Secret、私有数据、生成物和无关修改。
常用本地门禁以 package.json 和 docs/release-checklist.md 为准。最小文档验证为：
npx prettier --check agent.md AGENTS.md README.md ROADMAP.md docs/maintainer-handoff.md docs/operations-runbook.md docs/release-checklist.md
git diff --check代码改动通常还应按影响范围运行：
npm run lint
npm test
npm run build不要为了得到绿色结果关闭安全检查、放宽生产配置或修改无关测试。
- 需要浏览器操作或生产烟测时使用 Chrome；不要静默改用内置浏览器、Firefox 或其他会话。
- 优先复用用户已经登录的 Chrome 会话，不读取 Cookie、Local Storage、Session Storage、密码或 Token。
- UI 图标统一使用 Lucide，界面不使用表情符号。
- 延续
docs/DESIGN.md和现有页面的字体、配色、间距与响应式规则。 - 页面必须在桌面、移动和宽屏下无无意义横向滚动、遮挡、跳动和不可读小字。
- 视觉改动不能只看源码；必须以实际渲染、交互和截图为准。
默认发布链路：
- 从任务分支形成范围清晰的提交和 PR；
- 等待并检查全部必需 CI、数据库安全和 Secret Scan；
- 获得用户明确的合并/部署授权后合入
main； - 等待
mainCI 和 GitHub Pages 部署完成； - 检查 https://ustsacm.fun/、深链刷新、指纹资源和 Cloudflare 缓存；
- 等待
production-ranking-audit等发布后门禁进入终态； - 记录提交、PR、运行编号、生产结果、遗留风险和回滚点。
检查未通过时由 Agent 读取日志、修复、重新验证并继续监控。不要让用户代替 Agent 盯 CI。除非专项运行手册明确要求，不直接覆盖 Pages 产物，不通过手工上传绕过受保护部署链路。
详细步骤见 docs/operations-runbook.md、docs/release-checklist.md、docs/repository-settings.md 和 docs/custom-domain-cloudflare.md。
- 操作前确认 CLI 只链接预期项目，migration 与远端状态一致。
- 生产数据只能通过受控 RPC、Edge Function、migration 或明确记录的管理员流程修改，不直接绕过业务约束改表。
- 同步维护须检查调度、队列、最近成功、平台级错误、数据新鲜度和审计；自动重试规则以当前代码和
docs/sync-alerting.md为准。 - 单平台烟测只使用明确授权的受控成员，不抓取或输出其他成员私有资料。
- 第三方登录、Cookie、CSRF、QOJ / 洛谷账号和 Firecrawl Key 只通过 Secret 使用，Agent 不读取原值。
- 备份和恢复必须遵循
docs/backup-and-recovery.md，验证密文、清单、引用对象、恢复下限和明文清理。 - 故障恢复优先 Git revert、兼容函数回滚或数据库前向修复，不回退已发布 migration 历史。
- 最小化读取和输出；只记录状态、Secret 名称、消费者、时间和脱敏结果。
- 屏幕、终端或工具输出意外出现敏感值时，不在回复中复述，并立即停止可能扩大暴露的操作。
- 不使用真实成员账号进行破坏性测试；临时测试账号和测试数据必须在任务结束时清理并对账。
- 任何新增第三方数据流都必须同步检查
PRIVACY.md和docs/third-party-data-sources.md。 - 账号注销、管理员权限、RLS、备份恢复下限和私有 Storage 属于高风险边界，修改前必须阅读对应 ADR、migration 和生产证据。
- 用户已明确禁止网络安全请求；安全工作限于代码审计、本地测试、配置核对和正常业务烟测。
只有同时满足以下条件才可报告完成：
- 请求的行为已经实现或诊断结论已有可复现证据；
- 相关测试、构建、视觉或生产验证已完成，未完成项已明确说明；
- 工作树只新增预期改动，未覆盖用户文件，未泄露 Secret 或成员数据；
- 需要的文档、ROADMAP 状态和脱敏证据已同步；
- 获授权的提交、推送、合并、部署与观察均已到达终态；
- 已给出简洁的变更摘要、验证结果、生产状态和真正需要负责人处理的事项。
任务结束时留下以下交接信息：
任务：
当前分支 / 提交：
已完成：
验证：
生产状态：
未提交或用户已有改动：
遗留风险：
下一步：
需要项目负责人输入或批准：无 / <具体事项>
- 产品与本地开发：
README.md - 当前计划与发布阻塞：
ROADMAP.md - Agent 生产操作卡：
docs/maintainer-handoff.md - 生产部署与故障处理：
docs/operations-runbook.md - 正式发布门禁：
docs/release-checklist.md - 数据库备份与恢复：
docs/backup-and-recovery.md - 同步监控：
docs/sync-alerting.md - Cloudflare 与自定义域名：
docs/custom-domain-cloudflare.md - 设计规范：
docs/DESIGN.md - 架构决策：
docs/adr/README.md - 隐私、安全与第三方来源：
PRIVACY.md、SECURITY.md、docs/third-party-data-sources.md
专项文档比本文更具体时按专项文档执行；专项文档与当前代码或生产事实冲突时，先停止写操作，通过只读证据确认真实状态并更新文档。