# 项目维护与上下文治理

## 目标

仓库本身是跨 session、跨设备、跨 agent 的唯一持久事实源。聊天记录可以很长，但任何会影响后续工作的决定都不能只存在于聊天中；同时，常驻上下文不能退化成聊天流水账。

所有维护遵守奥卡姆剃刀：选择能完整满足已验证需求的最简单方案。没有当前消费者、实测瓶颈或重复问题时，不增加抽象、服务、拓扑、hook 或“以后可能用到”的框架。

## 事实分层

| 内容 | 文件 | 维护方式 |
| --- | --- | --- |
| 每次都必须遵守的规则 | `AGENTS.md` | 保持短、明确、无冲突，最多 200 行 |
| 当前产品事实与长期决定 | `docs/project-memory.md` | 就地更新，最多 200 行且不超过 12 KB |
| 当前阶段、下一步和阻塞项 | `docs/status.md` | 就地更新，最多 120 行且不超过 8 KB |
| 当前可验收需求 | `docs/需求理解.md` | 修改现行规范；变更历史交给 Git |
| 架构取舍与原因 | `docs/adr/` | 状态化管理；新决定 supersede 旧 ADR |
| 可复核的证据、保留候选与验收门槛 | `docs/research/` | 标注日期、来源和适用边界，过时结论要更新或标记 |
| 已完成工作的时间线 | commit、PR、issue | 不复制进常驻 memory |

每个事实只设一个权威归属，顶层文件只索引，不复制深层正文。一次检查点的最小真相集只包含后续执行无法安全重建的内容：已接受且仍生效的要求/约束、当前实现与证据边界、下一项可执行工作、真实阻塞或未决项，以及需要继续工作的分支/PR。能从代码、测试、Git 或权威资料廉价恢复的细节不进入常驻快照。

## 长 Session 检查点

在以下时机更新仓库快照：

- 用户确认或改变产品范围、优先级、约束或工作习惯后，在依赖该结论的设计或实现继续前；
- 一个重要设计、调研结论或验收门槛被接受、推翻或被实测结果修正后；
- 从调研、设计、实现、验证中的一个实质阶段进入下一阶段时；
- 切换分支、提交/更新 PR、agent 交接或任务交接前；
- 长任务可能自动压缩、即将暂停或离开当前 session 前。

检查点应立即修改事实的权威归属文件；只有当前全局快照确实改变时才同步修改 `project-memory.md` 或 `status.md`。不要等到 session 末尾才补写，也不要为每个文件、函数、工具调用或未形成结论的探索建立检查点。

检查点只保存以后仍需要的结论、当前状态、下一步和阻塞项。不要保存原始对话、完整日志、工具输出、临时文件路径、重复的代码结构、可随时重新搜索的常识、过程性 TODO 流水账或已经在其他规范中存在的内容。

恢复上下文时按以下顺序读取：`AGENTS.md`、`docs/project-memory.md`、`docs/status.md`、相关需求/ADR/调研，然后检查当前分支、`git status`、最近 commit 和 PR 状态。任何摘要与仓库冲突时，以当前代码、测试和正式文档为准。

## 清理规则

- 新事实与旧事实冲突时，在同一变更中替换或删除旧内容。
- `project-memory.md` 达到约 80% 上限时，先合并同类条目并删除可从代码或 Git 重新发现的内容。
- 需求文档保持单一现行版本，不在末尾无限追加确认记录。
- 调研结论失效时更新正文并保留“最后验证日期”；只有仍有历史解释价值的决策才进入 ADR。
- 已完成的临时计划从 `status.md` 删除，由合并后的 PR 和 commit 保存历史。
- 每个重要 PR 都检查文档是否互相矛盾、链接是否仍有效、memory/status 是否仍代表当前事实。

## 验证节奏

- 迭代中运行能覆盖当前改动的最小定向检查；同一未变化路径已经通过的昂贵检查不因相邻小改动自动失效。
- 完整测试套件、真实浏览器矩阵、长时稳定性、网络整形、跨设备和部署验证按一个完整候选或验收阶段批量运行。只有相关媒体路径、协议、配置、依赖、环境或验收门槛改变，或者上次结果失败/含糊时才重跑对应证据。
- 文档改动默认只运行 Markdown/链接/whitespace/diff 检查；不为与运行时代码无关的改动重跑 npm 全套或媒体基准。
- 在 `status.md`、调研或 ADR 中记录昂贵验证对应的 commit、环境、结果和适用边界，PR 可以引用该记录，使后续工作能判断证据是否仍有效，而不是机械重跑。
- 发布、安全边界、数据库迁移和部署切换仍按其风险执行必要的最终门禁；“批量验证”不是跳过会被当前变更影响的检查。

## 阶段验收后的有界架构收敛

这是一项明确延期的收官任务。只有当前主要功能基本完成、相关主线变更合并且阶段验收完成后才可启动；它不阻断或抢占当前的质量证据、自动路由 exact-room canary、native sender 或部署工作。启动时从届时最新 `main` 建立一个短期 `refactor/` 或 `chore/` 分支。当前只记录审查契约，不实施重构。

2026-08-19 的一次只读盘点估算约有 14,153 行产品源码和 31,094 行第一方文本，并标出以下高集中度 owner：

- `src/server/hybrid-media-router.ts`：约 1,605 行；
- `src/client/pages/HostPage.tsx`：约 1,455 行；
- `src/server/signaling.ts`：约 1,057 行；
- `scripts/peer-assisted-benchmark.ts`：约 2,049 行。

这些总量、分类口径和“产品源码可能净减少 7%-14%”都只是当日待重测的审查假设，不是删除指标、承诺区间或 LOC KPI。文件长度也不单独证明职责错误。正式审查必须先重新读取 `AGENTS.md`、当前 memory/status、需求、相关研究及 [ADR-0004](adr/0004-peer-assisted-media-experiment.md)/[ADR-0005](adr/0005-automatic-hybrid-media-routing.md)，重新统计届时 `main`，明确计数口径，并按消费者和测试把代码分为：

1. 当前生产路径必需；
2. 自动 `direct/peer UDP -> SFU roots -> optional exceptional-edge TURN` 目标必需；
3. 有明确下一阶段消费者和退出条件的实验能力；
4. 已被替代、重复、无消费者或仅服务一次性定位的代码。

任何实现开始前，先输出基于证据的候选清单、行为与迁移风险，以及按 owner 说明依据的预计净减少范围；范围可以低于 7%、为零，或证明当前不值得改。评审该输出后再决定是否实施，不能用预设比例反推删除。

审查优先减少状态 owner、重复路径和认知负担：先删除已证明无消费者的代码，再合并重复逻辑，只在已有独立职责和消费者时提取窄模块。重点检查：

- `SignalingServer` 是否能只保留认证、WebSocket 分发与薄协调职责；
- `HybridMediaRouter` 的拓扑计划、SFU grant/lifecycle、intent drain 和广播是否形成可独立验证的自然边界；
- `HostPage`/`ViewerPage` 的纯媒体编排与展示状态能否适度分离，而不建立新的前端架构层；
- benchmark 的一次性探针和重复 CDP 逻辑能否收缩，同时保留可重复验收与结果可比性；
- 测试 setup/fixtures 能否合并，同时完整保留竞态、鉴权和 host edge 上限覆盖。

不要为了缩短文件机械拆分，也不要引入通用框架、工厂、事件总线或更多状态机。Peer/SFU 代码不能因默认关闭就视为多余：若 canary 和 ADR 门槛支持该路线，则保留并整理；若路线被实测否决或明确替代，则删除失败路径，不长期保留无消费者的负担。

任何候选改动都必须保持以下行为不变：

- 用户无感的自动 `direct/peer UDP -> SFU roots -> optional exceptional-edge TURN` 梯级；
- 每条媒体边独立执行 ICE，普通 peer 默认不收到 TURN；启用兼容层时只有授权的异常 edge 可使用短期凭据；
- host 下游活跃媒体边不超过两个；
- 普通桌面或移动浏览器 Viewer 无需安装应用；
- break-before-make、安全授权、重连、回滚和陈旧消息隔离语义；
- 功能默认关闭，并保留 exact-room allowlist 灰度边界。

实现期间只运行覆盖当前改动的窄测；完整候选形成后统一运行一次 full check。除非媒体行为或证据采集逻辑改变，不重跑昂贵浏览器/网络矩阵。实现 PR 必须原位同步 status、project memory 和相关 ADR，删除失效描述，不新增过程流水账文档。

## 在线调研规则

非平凡的设计、实现和 bug 修复先读仓库，再查当前的一手资料。优先级为规范/官方文档、官方源码与维护者说明、原始论文，然后才是高质量社区复现与运行经验。安全、网络协议、浏览器能力、依赖版本和云服务行为属于易变化信息，必须按当前日期重新验证。

调研输出应说明问题、来源日期、已证实事实、推断、候选方案、许可证、适用边界和最终采用理由。不要把搜索结果原样堆进常驻上下文。

## 自动化

- `.githooks/pre-commit` 和 CI 调用 `scripts/check-project-state.sh`；原生 Windows 可运行等价的 `scripts/check-project-state.ps1`。两份入口共享 `scripts/required-project-paths.txt`，检查 whitespace、必需文件、Git 跟踪状态和上下文文件上限。
- `.github/workflows/repository-hygiene.yml` 在 push/PR 上运行 tracked POSIX 入口。
- hook 只做快速、确定、可复现的检查；需要工程判断的内容留给评审和测试。
- 新脚本必须有明确当前用途、跨平台入口、失败信息和 CI 调用方。没有现实使用者的 hook 或框架不进入仓库。