Piik/docs/maintenance.md

项目维护与上下文治理

目标

仓库本身是跨 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-0005，重新统计届时 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、安全授权、重连、回滚和陈旧消息隔离语义；
• 轻量实例可关闭 controller；旗舰部署以 PEER_ASSISTED_MEDIA=true 对所有正常房间启用，room 1 仅是历史 smoke，已不再保留 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 或框架不进入仓库。