From 6efaa2b7a68b640858f5c0430efb60c953091a2d Mon Sep 17 00:00:00 2001 From: AAA <35992542+TNTcraftHIM@users.noreply.github.com> Date: Sun, 23 Aug 2026 15:20:43 +0800 Subject: [PATCH] docs: keep only the current internal contract --- AGENTS.md | 1 + docs/project-memory.md | 1 + docs/需求理解.md | 2 +- 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index a5a6111..58bf7b4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,7 @@ - Highest priority: before implementation, cleanup, or deployment, settle the meaning against the whole product model and evidence, challenge contradictions or needless complexity, and write the accepted decision to its owning truth documents. Discussions, examples, review suggestions, experiments, checkboxes, and agent ideas are inputs, not implementation authority; never turn a partial interpretation into code or a branch. - Apply Occam's razor as "simple, not simplistic": prefer standards, mature framework behavior, and one small general mechanism that covers the product model. When a concrete failure appears, fix the owning invariant or reconciliation loop first; add a case-specific branch, gate, probe, timer, state container, or test only when evidence shows the general mechanism cannot cover it. Do not implement by repeatedly patching examples. +- Until the owner explicitly declares a public release, maintain only the current internal product contract. Do not preserve backward or forward compatibility, legacy wire/config aliases, dual parsers or writers, translators, deprecated APIs, migration shims, or tests whose only consumer is an older release. Upgrade the private deployment atomically, reject stale clients before authority, delete replaced surfaces, and use Git history for rollback. Reassess compatibility only when public release requirements are explicitly opened. - Before dependent work starts, update every affected owning requirement, design, ADR or research conclusion, plus `docs/project-memory.md` and `docs/status.md` when their snapshots change. Checkpoint the consistent truth in Git; chat is not durable truth. - If semantics remain disputed, record the hold in `docs/todo.md` and freeze only dependent work. Do not encode a guess as accepted truth. - **Current-truth ("Dongpo pork") rule:** after a correction, current docs, UI, code, comments, configuration, and PR copy state only the accepted behavior and rationale that still constrains it. Remove rejected alternatives and explanations of their removal; Git history owns that history. diff --git a/docs/project-memory.md b/docs/project-memory.md index 79d08fb..6245f32 100644 --- a/docs/project-memory.md +++ b/docs/project-memory.md @@ -18,6 +18,7 @@ Last updated: 2026-08-23 - Video codec selection remains `automatic | H.264 | VP8`. The accepted first switching boundary is a generation-fenced renegotiation/republish transaction while sharing is explicitly paused; unpaused hot switching is later reuse of that transaction, not an independent mechanism. - Two distribution artifacts are accepted only after the current feature, NAT, and real-network ledger is complete. A public-server one-click deployment package installs the current application plus STUN/SFU/TURN and proxy components on a user-owned server. A Windows/macOS/Linux local package runs the Host, application server, and local state on the broadcaster's machine without source, Node, or any external Screener/network service; it keeps workable direct P2P but reports the reachability loss imposed by public ingress, TLS, gateway, NAT, or firewall limits rather than promising universal connectivity. - Current UI, presence, route labels, and diagnostics describe observed state only; they do not create route authority. +- Before an explicit public-release decision, the private deployment and repository keep only the current product contract. Incompatible wire, configuration, parser, and API changes ship atomically; stale clients fail before authority, replaced compatibility surfaces are deleted, and Git history owns rollback. - Viewer startup feedback remains on the stage until current-generation frame presentation is proven, distinguishes peer, fallback, media, autoplay, recovery, and failure phases, and keeps `Play` specific to autoplay rejection. The strict-NAT guessed-candidate idea remains an isolated emulator gate; only a pass may authorize one manually approved, kill-switched canary in an operator-owned test room with explicit consent from both endpoints and exact room/edge/generation/budget bounds. ## Current Source And Production diff --git a/docs/需求理解.md b/docs/需求理解.md index 1d2d978..67224cf 100644 --- a/docs/需求理解.md +++ b/docs/需求理解.md @@ -74,7 +74,7 @@ SFU/TURN 的 publication、subscription、transport、server-resource accounting - 安全：应用控制面全程 HTTPS/WSS；site access、Host token 与 room-scoped Viewer grant 权限正交，任何一个 Viewer grant 只授予一个房间的观看角色。P2P/TURN 边在 WebRTC 端点间使用 DTLS-SRTP，普通 SFU 是逐跳 DTLS-SRTP；只有另行实现并验收应用层 E2EE 才能对 SFU operator 保持媒体端到端机密。仓库、数据库、日志和错误不得包含明文密码或 grant。已鉴权 Host 与 shipped clients 是当前私密房间中的可信媒体参与者；越权房间、角色和未授权 subscription 必须拒绝。旧 generation 不得重新取得 route authority，并在有界 drain 后由 exact-room 删除阻止再次加入。 - 隐私：P2P 会向房间内好友暴露网络地址，首版威胁模型仅覆盖可信熟人；若要求隐藏 IP，必须切换为服务器转发。 - 可维护性：代码、需求、调研、项目记忆、`AGENTS.md` 和 `.codex/` 均在 Git 中跟踪；开发配置不得依赖单一操作系统的绝对路径。 -- 迁移完整性：同一 release 的客户端、服务端和部署配置原子迁移；canary 结束后删除被替代的配置、wire、parser、双写与测试，不为无当前消费者的旧版本保留兼容层或第二套架构。Git 历史承担旧实现追溯。 +- 迁移完整性：项目拥有者明确宣布公开发布前，只维护当前内部产品合同，不承担 backward/forward compatibility。客户端、服务端和部署配置按同一 release 原子迁移；旧客户端在 authority 前拒绝，替代后立即删除旧配置、wire、parser、双写、translator、deprecated alias、migration shim 与仅服务旧版本的测试，不保留第二套架构。Git 历史承担旧实现追溯；公开发布后才按明确的新要求重新评估兼容策略。 - Web 优先：每项用户能力先使用普通浏览器的标准 API 和正常权限流程；只有当前目标浏览器存在已证实的能力缺口且该功能仍属当前范围时，才允许独立、可选的 Sender。不得为假设中的未来能力预建客户端、兼容层或第二套会话架构。 - 兼容性：分享端首个目标矩阵为 Windows 10/11 的当前 Chrome/Edge；普通移动浏览器当前只属于 Viewer 矩阵。截止 2026-08-21，MDN Browser Compatibility Data 仍将 Chrome Android、Firefox Android 和 Safari iOS 的 `getDisplayMedia()` 标为不支持；Web Host 必须用运行时能力检测，API 缺失时明确显示不支持，API 存在但调用拒绝时区分用户拒绝/取消与 capture failure，不能用 UA/设备型号伪造兼容。观看端仍必须覆盖当前 Android Chrome 和 iOS Safari，并实测自动播放限制、横竖屏、锁屏恢复与移动网络切换。所有 Web Viewer 使用统一的 server-authoritative endpoint capacity；移动真机表现是兼容观察，不建立单独 route class。