# 校墙项目工作流

开始任何修改前，先阅读 [`docs/PROJECT_INDEX.md`](docs/PROJECT_INDEX.md)，按代码地图定位入口，避免扫描整个仓库。

## 主 Agent 工作流

采用“主 Agent 单一窗口、按需拆分、统一验收、证据确认上线”的工作流。主 Agent 负责理解需求、答疑、确认、任务拆分、审核整合、验收、发布和简洁交付；子 Agent 只做内部任务，不直接向用户汇报。

1. 接收需求：明确目标、验收标准和授权范围；区分咨询、只读审查、实现和发布，沿用已明确的授权。
2. 查代码与现状：先读 `docs/PROJECT_INDEX.md`，再查相关代码、分支、工作树和已有改动，以当前源码为准。
3. 制定短计划：说明准备改什么、如何验证、是否拆分或隔离；简单任务可直接执行。
4. 执行与调度：短小、关联紧密的工作由主 Agent 完成；可独立验收的工作再交给子 Agent，存在依赖的步骤顺序执行。
5. 审核与整合：主 Agent 检查子任务差异、接口兼容和遗漏，统一解决冲突；整合后重新验证受影响链路。
6. 验收与发布：完成本文件的检查；已有发布授权则继续，否则提供可审阅结果后集中确认。
7. 交付：输出改了什么、验证了什么、发布到哪个提交、剩余事项，不复述工具过程。

只有需求存在实质歧义、需要取舍、可能覆盖用户改动，或外部操作尚未授权时才确认；普通实现选择由主 Agent 决定。

## 子 Agent 调度规则

- 子 Agent 的问题、结果和阻塞均内部回传，由主 Agent 答疑和汇总。
- 代码实现、排查和常规验证默认显式使用 `gpt-5.6-luna`；视觉设计、交互细节或审美质量会显著影响结果的独立任务，才使用 `gpt-5.6-terra`，推理最高 `high`。任何子 Agent 都不得超过 Terra high，且不得继承更高的主 Agent 配置；无法保证上限时由主 Agent 完成。
- 每项委派必须说明：目标、必要上下文、可修改范围、依赖、验收条件和回传格式。
- 适合拆分：独立调查、互不重叠的实现、独立审查与验证。拆分成本超过收益时直接做。
- 同一文件或紧密共享状态由一个负责人修改；子 Agent 不扩大范围、不自行发布、不递归委派。
- 回传必须包含改动位置、结论证据、实际运行的检查及未解决问题。主 Agent 审核后才能算完成。

## 工作树与代码索引

- 小修复可在当前工作树完成；多模块、大改动、并行实现或高风险变更使用独立工作树。
- 开工记录基线提交、已有改动及本任务创建的工作树；不覆盖、搬走或回滚用户改动。
- 主 Agent 负责整合和最终验收；不能把各子任务分别通过视为整合通过。
- 仅清理本任务自行创建、成果已保留且没有未处理改动的工作树；其他工作树不动。
- `docs/PROJECT_INDEX.md` 是唯一代码地图，只记录路径、职责和关联入口。新增、移动或删除页面、接口、服务、测试、部署入口时同步更新；详细业务说明放专题文档。

| 功能 | 主要入口及关联 |
| --- | --- |
| 公众号 | `frontend/admin/mp-draft.html` → `routes/mp-draft.js` → `services/mp-draft.js` |
| 点歌 | `frontend/radio.html`、`frontend/js/radio.js` → `routes/songs.js`；关联公众号点歌单 |
| 微信 | `routes/wechat.js` → `services/wechat*.js` |
| AI | `services/ai.js`；关联实际调用方 |
| 权限 | `middleware/auth.js`；关联受保护路由和后台入口 |
| 邮件 | `services/email.js`；关联认证和通知调用方 |
| 移动端与卡片 | `frontend/css/mobile-fix.css`、公共及页面样式；关联页面脚本和 `public/` 镜像 |
| Git 部署 | `routes/deploy.js` → `deploy.sh`；关联部署检查和更新日志 |
| 测试 | `package.json`、`scripts/test-*.js`；关联被验证功能 |

修改 HTML、页面 JS 或 CSS 后必须同步 `frontend/` 与 `public/`，并运行 `npm run check:mirrors`。`769px+` 使用桌面布局，`768px-` 才使用移动布局。

## 发布验收清单

所有功能变更逐项记录“通过／失败／不适用及原因”；未实测不得写通过。

- 桌面与移动端：实际检查典型宽度及 `768px/769px` 边界，覆盖卡片、CSS、溢出、遮挡和交互。
- 状态与权限：检查正常、空、加载、错误状态，以及未登录、普通用户和相关管理角色；权限由后端落实。
- 关联输出：检查公众号预览与实际同步内容、媒体及链接一致；涉及邮件时检查实际渲染、链接及移动端可读性。
- 镜像与隐私：同步 `frontend/` 与 `public/`；检查密钥不进入代码、日志、截图和交付材料。
- 提交前检查：按影响运行相关测试、`npm test`、`npm run check:mirrors`、`npm run check:privacy`、`npm run check:deployment` 和 `git diff --check`；补充未包含在总测试中的专项检查。
- 发布材料：更新索引和 `config/release-notes.json`，审阅最终差异；只提交本任务内容，最终修改后相关检查必须通过。
- Git 推送：核实仓库及目标分支，发布分支为 `main`；确认远端提交等于已验收提交。
- webhook 部署：通过统一 `/api/deploy-webhook` 流程触发；已有自动触发时不重复触发。凭据只从私有配置读取。
- 线上确认：查询 `/api/deploy-status`，核对本次更新时间、`state=success`、`exitCode=0`、服务器提交号等于目标提交；确认 `wall` 状态、健康检查和变更功能线上表现。

webhook 的 HTTP `202` 仅表示请求已处理，甚至可能因分支不匹配而跳过；不能作为上线证明。提交不符、失败、回滚或超时均明确报告，不宣称发布成功。

更新日志保持简短：更新内容、实际验证、Git 分支/提交和线上核对结果、未完成或未验证事项。

## 何时开新对话

- 仍在处理同一目标、当前上下文有用，或正在解决连续依赖、冲突、部署验收时，继续当前对话。
- 阶段已完成、目标明显变化、无关历史过多，或频繁需要重读才能找回关键决定时，建议新对话。
- 不按固定轮数切换，也不为每个小功能新建对话；优先缩小读取范围、压缩阶段结论。
- 切换前准备交接：目标、授权与禁止事项、路径和分支、用户已有改动、已完成内容、验证结果和剩余步骤。
- 新对话仍由主 Agent 面向用户，子任务保持内部沟通；交接不等于获得新的发布授权。若平台要求用户明确创建新对话，主 Agent 说明交接后等待该请求。