[Docs] (Disaggregated): the top-level files become short indexes in plain language; the design text moves to design/, the how-to and reference material to guide/

- README, ARCHITECTURE, ROADMAP, MEASUREMENTS and CURRENT_STAGE_PROGRESS are rewritten as indexes
  (84 KB -> 15 KB): what the project is, where it stands, and where each detail lives. ROADMAP is one
  plain sentence per phase; MEASUREMENTS is the five conclusions that matter plus one line per phase;
  CURRENT_STAGE_PROGRESS is the P12 goal, a checklist and the next steps.
- ARCHITECTURE's body moves unchanged into ten design/ files, keeping §1-§17 and appendices A/B, so
  `ARCHITECTURE.md §N` references in code resolve through the table in ARCHITECTURE.md.
- guide/ holds build-and-run, code map, glossary and the engineering discipline (from README and
  ROADMAP), and the device pinning record that used to sit in devices/.
- The open-debt table moves to notes/DEBTS.md; the detailed current-stage tables (with decision IDs,
  the open line items and evidence locations) move into notes/p12/README.md. notes/README.md maps
  every moved path and section.
- The documentation citation lint in test.yml also covers design/ and guide/, which describe the
  current tree as the top-level files did.
This commit is contained in:
2026-09-24 22:39:46 +00:00
parent 43b5cfa94e
commit 0fe015886e
25 changed files with 785 additions and 793 deletions
+17
View File
@@ -0,0 +1,17 @@
# 仍开放的债务(跨阶段)
> 路线图只列"有债务、看这里"。每条写明去向;已关闭的历史债与当时的完整债务表见 [`p5b/README.md`](p5b/README.md) 末节。开放问题另见 [`OPEN-QUESTIONS.md`](OPEN-QUESTIONS.md)。更新:2026-09-24。
| 债务 | 去向 |
|---|---|
| `SEG_REPLY` 2 MiB 单槽 payload cap、PACK-PBO 回读的 fire-and-forget | P9(ID-47、ID-57);stream 链路上 cap 变成 `maxReplyBytes` 窗口 |
| 未接入内容分块的 record 类型:program archive 与 `draw_vbo` range 尾 | P6.5 sl 与 P8 共用的分片(开放问题 11) |
| class-C 余项与仿真路径:`SetSwapInterval`(P10)、`DeleteTransformFeedback`(P9);multi-draw client indices、RGB CPU mip、`texture-remint-pull` 等具名拒绝 | P8 / P9 |
| `GetCaps` 的两个 blobref | 一旦运输,必须有 server → client 的 carrier rule,不能套 `SEG_STAGE` |
| E1 对照的重定义(ID-122) | 无主(开放问题 24) |
| `MOBILEGL_IPC_IDLE_EXIT_S` 未解析;`CONTRACT-P6.md` 仍把 `DynamicBackendParameters` 定宽记在 P7 名下(已由 P6.5 wf 落地) | 文档 / 小修 |
| P12 文档债:`MG_Remote/CONTRACT-P12.md` 未写;`protocol.fbs` 的窗口注释仍是旧说法 | P12 收尾 |
| 树外脚本:普查跑器、`wsl_p5_gate.sh` 等在 `~/w7/notes/`,git merge 不会传播 | 需要时入库 |
| 临时 CI trigger | 合入 `dev` 前删除 `test.yml` / `apk.yml` 的 `feat/disaggregated` 触发器 |
已关闭的历史债(P5 的 27 个 wrong-answer、`rsp` 残余读、P5b 的 inproc 依赖、ABI 指纹、默认 staging 装不下 128 MiB 上传、184 符号棘轮 CI 门)及当时的完整债务表见 [`notes/p5b/README.md`](p5b/README.md) 末节。
+10 -6
View File
@@ -1,6 +1,6 @@
# 阶段笔记(notes)
这一层放**各阶段的全部细节**:每个阶段一个目录,目录里的 `README.md` 是该阶段的**汇总**(摘要、阶段表原行、逐门实测、落地形状、当时的进度页),其余文件是那个阶段的原始工作笔记——包计划(`BRIEF-*.md` / `TASK-*.md`)、契约草稿、集成者逐条裁定(`INTEGRATOR-DECISIONS-*.md`)、只读审计与普查、包报告、设备记录与证据。上层四份索引([`../ROADMAP.md`](../ROADMAP.md)、[`../ARCHITECTURE.md`](../ARCHITECTURE.md)、[`../MEASUREMENTS.md`](../MEASUREMENTS.md)、[`../CURRENT_STAGE_PROGRESS.md`](../CURRENT_STAGE_PROGRESS.md))只留摘要并链到这里。
这一层放**各阶段的全部细节**:每个阶段一个目录,目录里的 `README.md` 是该阶段的**汇总**(摘要、阶段表原行、逐门实测、落地形状、当时的进度页),其余文件是那个阶段的原始工作笔记——包计划(`BRIEF-*.md` / `TASK-*.md`)、契约草稿、集成者逐条裁定(`INTEGRATOR-DECISIONS-*.md`)、只读审计与普查、包报告、设备记录与证据。顶层的索引([`../ROADMAP.md`](../ROADMAP.md)、[`../MEASUREMENTS.md`](../MEASUREMENTS.md)、[`../CURRENT_STAGE_PROGRESS.md`](../CURRENT_STAGE_PROGRESS.md))只留一句话并链到这里;不属于某个阶段的设计正文在 [`../design/`](../design/),上手与参考在 [`../guide/`](../guide/)。
## 按阶段
@@ -25,7 +25,7 @@
| **P12**(当前)server 自有屏幕窗口 | [`p12/`](p12/README.md) | `PLAN-P12.md`、`INTEGRATOR-DECISIONS-P12.md`、`device/` |
| P8 / P9 / P10 / P11 / P13(待排) | [`p8/`](p8/README.md)、[`p9/`](p9/README.md)、[`p10/`](p10/README.md)、[`p11/`](p11/README.md)、[`p13/`](p13/README.md) | 目前只有路线图上的完整范围与出口门 |
跨阶段:[`OPEN-QUESTIONS.md`](OPEN-QUESTIONS.md)(开放问题全文,编号稳定);[`handoff/`](handoff/)(P7 的集成者审查稿,路径被 P7 交接文档引用,保持原位);[`recovered/`](recovered/)(从失败的 workflow 运行里捞回的 P0–P2 期材料,`wf1` 设计定稿前的计划草案、`wf2` P0、`wf3` P0.5、`wf4` P1、`wf5` P2;与阶段目录逐字节重复的副本已于 2026-09-24 删除,只留独有的)。
跨阶段:[`DEBTS.md`](DEBTS.md)(仍开放的债务与去向)、[`OPEN-QUESTIONS.md`](OPEN-QUESTIONS.md)(开放问题全文,编号稳定);[`handoff/`](handoff/)(P7 的集成者审查稿,路径被 P7 交接文档引用,保持原位);[`recovered/`](recovered/)(从失败的 workflow 运行里捞回的 P0–P2 期材料,`wf1` 设计定稿前的计划草案、`wf2` P0、`wf3` P0.5、`wf4` P1、`wf5` P2;与阶段目录逐字节重复的副本已于 2026-09-24 删除,只留独有的)。
## 旧引用怎么找
@@ -39,6 +39,10 @@
| `docs/Disaggregated/P6-SPAWN-PLAN.md`、`P6-CONTRACT-DRAFT.md`、`P6-ENDSTATE-REVIEW.md` | [`p6/`](p6/README.md) 同名文件 |
| `docs/Disaggregated/CURRENT_STAGE_STATUS.md` | 并入 [`../CURRENT_STAGE_PROGRESS.md`](../CURRENT_STAGE_PROGRESS.md);其中 P7 的出口门 / 已落地 / 真机三节在 [`p7/README.md`](p7/README.md),P12 部分在 [`p12/README.md`](p12/README.md) |
| 旧 `CURRENT_STAGE_PROGRESS.md` 的 P6.5 第一波与 P6 收官快照 | [`p65/README.md`](p65/README.md)、[`p6/README.md`](p6/README.md) |
| 当前阶段页的明细(带裁定编号的表、余项清单、证据位置) | [`p12/README.md`](p12/README.md) 的"当前状态详情"节 |
| `docs/Disaggregated/devices/pin-verification-2026-09-07.md` | [`../guide/pin-verification-2026-09-07.md`](../guide/pin-verification-2026-09-07.md) |
| `ARCHITECTURE.md` 的设计正文(§1–§17、附 A / B) | [`../design/`](../design/) 下十个文件,编号不变;对照表在 [`../ARCHITECTURE.md`](../ARCHITECTURE.md) |
| 旧 `README.md` 的构建运行、代码地图、术语;旧 `ROADMAP.md` 的通用纪律 | [`../guide/`](../guide/) |
**按编号引用的旧章节**(小节编号在新位置原样保留):
@@ -47,8 +51,8 @@
| `MEASUREMENTS.md` §1 / §2 / §3 / §4 / §5 | [`p0`](p0/README.md) / [`p1`](p1/README.md) / [`p2`](p2/README.md) / [`p3a`](p3a/README.md) / [`p4a`](p4a/README.md) 的"实测"节 |
| `MEASUREMENTS.md` §6 / §7 / §8 / §9 | [`p5`](p5/README.md) / [`p5b`](p5b/README.md) / [`p5c`](p5c/README.md) / [`p5d`](p5d/README.md) |
| `MEASUREMENTS.md` §10 / §11 / §12 / §13 | [`p5e`](p5e/README.md)(§10、§11)/ [`p6`](p6/README.md) / [`p34b`](p34b/README.md) |
| `ARCHITECTURE.md` §17.1–§17.4 / §17.5 / §17.6 / §17.7 | [`p5`](p5/README.md) / [`p5b`](p5b/README.md) / [`p5c`](p5c/README.md) / [`p5e`](p5e/README.md) 的"落地形状"节(上层 §17 留一张索引表) |
| `ROADMAP.md` 阶段表某行、"P5c 计划与审计"、"立即的下一项:P6.5 第一波"、债务表、开放问题 | 对应阶段 `README.md` 的"阶段表行"节;[`p5c`](p5c/README.md);[`p65`](p65/README.md);[`p5b`](p5b/README.md) 末节;[`OPEN-QUESTIONS.md`](OPEN-QUESTIONS.md) |
| `ARCHITECTURE.md` §17.1–§17.4 / §17.5 / §17.6 / §17.7 | [`p5`](p5/README.md) / [`p5b`](p5b/README.md) / [`p5c`](p5c/README.md) / [`p5e`](p5e/README.md) 的"落地形状"节([`../design/10-phase-shapes.md`](../design/10-phase-shapes.md) 留一张索引表) |
| `ROADMAP.md` 阶段表某行、"P5c 计划与审计"、"立即的下一项:P6.5 第一波"、债务表、开放问题 | 对应阶段 `README.md` 的"阶段表行"节;[`p5c`](p5c/README.md);[`p65`](p65/README.md);[`DEBTS.md`](DEBTS.md)(历史全表在 [`p5b`](p5b/README.md) 末节);[`OPEN-QUESTIONS.md`](OPEN-QUESTIONS.md) |
| `ARCHITECTURE.md:NNN`、`MEASUREMENTS.md:NNN` 这类**行号**引用 | 指向写下它时的那个版本,今天已不对应;按上下文所说的节去找,或 `git show <当时的头>:docs/Disaggregated/<文件>` |
| `~/w7/notes/<phase>/<file>.md` | `docs/Disaggregated/notes/<phase>/<file>.md`(这些笔记原先只存在于一台机器的 `~/w7/notes/`) |
@@ -59,11 +63,11 @@
| **收录** | 全部 `.md` 笔记,以及阶段自己决定入库的小脚本、判读工装与证据摘要(如 `p7/device-window-*/`、`p12/device/`、`p12/gate/`) |
| **不收录** | 大体积、随每次运行重新产生、只在产生它的机器上有意义的证据数据:完整运行日志、APK 与 `.idsig`、`nm` 转储、设备 logcat。上层文档引用它们时给的是路径,不是内容 |
新阶段开工时建 `notes/<阶段>/`,把计划、裁定与报告都放进去;阶段收官时补齐该目录的 `README.md` 汇总,上层索引只加一行摘要。
新阶段开工时建 `notes/<阶段>/`,把计划、裁定与报告都放进去;阶段收官时补齐该目录的 `README.md` 汇总,顶层索引只改一行。
## 不受 citation lint 管
CI 的文档引用 lint 只检查 `docs/Disaggregated/*.md`(非递归,`.github/workflows/test.yml`),**本目录不在其中,这是有意的**:笔记里的 `file:line` 写在各自当时的代码头上,拿今天的 HEAD 解析必然大面积失败——那是它们作为历史记录的正确状态。要核对某份笔记的引用,用它自己声明的那个 revision:
CI 的文档引用 lint 只检查顶层、`design/` 与 `guide/`(`.github/workflows/test.yml`),**本目录不在其中,这是有意的**:笔记里的 `file:line` 写在各自当时的代码头上,拿今天的 HEAD 解析必然大面积失败——那是它们作为历史记录的正确状态。要核对某份笔记的引用,用它自己声明的那个 revision:
```bash
python3 scripts/check_doc_citations.py --rev <当时的头> docs/Disaggregated/notes/<phase>/<file>.md
+50
View File
@@ -22,6 +22,56 @@
- **P12 子集**:APK `26.09.29b7b28-trace`(**控制协议修订 3**,与 p7w8 的 server 不兼容),证据 `notes/p12/device/`(九格拼图 `evidence-strip.png`)。七个编号检查在三个 head 上跑过,`trial-*/` 是按 head 归档的旧轮次。
## 当前状态详情(2026-09-24,原 `CURRENT_STAGE_PROGRESS.md` 正文)
> 顶层 [`CURRENT_STAGE_PROGRESS.md`](../../CURRENT_STAGE_PROGRESS.md) 只留摘要;带裁定编号的落地表、门表、余项清单与证据位置在这里。
### 1. 一句话
Android 上的 server 自建窗口(自己的 SurfaceView)把 IPC 渲染流**上屏**,client 以 `WindowKind::ServerOwned` **完全无头**接入。子集已实现并入,**未收官**:审查轮修复之后欠一次真机复测,两个出口门都还没打。
### 2. 已落地
| 面 | 内容 | 出处 |
|---|---|---|
| wire | `WindowKind::ServerOwned`、控制修订 2 → 3、`SurfaceReply` 带回窗口真实尺寸或具名拒绝 | PLAN-P12 §1 |
| server 窗口 | `ServerDisplay`(钩子 + 租约 + 有界 3 s `Detach`);会话表面模式首次创建即闩定(`SurfaceModeMismatch`);无显示具名拒绝(`NoServerDisplay`);失窗 → `Fatal{ServerWindowLost}` → client 读干净 device-lost | ID-P12-2、ID-P12-3 |
| client | `MOBILEGL_IPC_SURFACE=server` → 无头窗口 surface,不发 `SetWindowHandle`;resize 变成对 server 窗口的几何请求,采用 server 回的真实尺寸 | ID-P12-10 |
| 进程内 server | `MobileGLDisplayActivity`(`:mglwin`)里一个线程跑 TCP server:会话串行、会话间重置闩、后端按进程钉住;与离屏 `MobileGLServerService` 互斥,一台设备同一时刻一个 server | ID-P12-4 |
| 审查轮 | 10 个问题已修;两个大项:批内失窗检查(`DrainRing` 每次 pop 前)、会话间 Espryt 单元影子悬空;另有推流中停机、会话结束清理、陈旧尺寸、日志转发 | ID-P12-5 … 11 |
### 3. 门
| 门 | 状态 | 证据 |
|---|---|---|
| G1 | ✅ pull 构建同机前后 `.text` 一致、符号 0 增 0 减 | ID-P12-15 |
| 主机门 | ✅ unit 2605/2605,spawn / tcp 与三条 Magma 双进程车道全绿;剩余红全部归容器的 CMake/CTest 版本 | ID-P12-14 |
| 真机七项检查(Redmi `2f7cbe2e`) | ✅ 审查轮之前(`29b7b284`):双后端上屏 ssim 1.0、串行 + `Refuse{Busy}`、失窗 device-lost、离屏不回归、无显示具名拒绝、一台设备一个 server;⏳ **审查轮之后未复测** | PLAN-P12 §2、ID-P12-13 |
| 出口门 (a) | ❌ FCL 同机 spawn、双后端入世界、**杀 server** 产生干净 device-lost(本轮的驱动是 trace_replay,device-lost 由按 HOME 触发) | PLAN-P12 §3 |
| 出口门 (b) | ❌ **另一台机器**的 client 经 TCP 在 Redmi 入世界,并记录 P6.5 必测数(本轮 client 是 `adb forward` 环路) | PLAN-P12 §3 |
### 4. 在跑
无。
### 5. 下一步
1. **真机复测**(ID-P12-13):重建 APK(控制修订 3),重跑七项检查,外加"推流中按 HOME:回调返回前 surface 已释放,并记耗时";在与原门同版本的 CMake/CTest 上复跑一次主机门。
2. **出口门**:先 (b) 跨机 TCP 入世界 + P6.5 必测数,再 (a) FCL + 杀 server。
3. **收尾**:写 `MG_Remote/CONTRACT-P12.md`;修 `notes/p12/gate.sh` 的 G1 符号比较(与基准不同源,会印出误导的 `added=N removed=N`);按惯例做一次收官审查。
4. **阶段表行里的余项**(交接时在树上核过,均未做):in-process server 的 `unix:` 监听、DirectGLES `g_Display` / `g_Surface` / `g_Context` 去全局、cached-app freezer、多 context、FCL env 与 plugin 开关表接线、D8 窗口种类白名单。
5. 其后按 [`ROADMAP.md`](../../ROADMAP.md):monolith 跑道 P8;IPC 跑道 P9 → P10 → P11;P6.5 残余(39 例 device 矩阵 + 必测数)与 P3b/P4b 余项并行;`CONTRACT-P7.md` §12 的记录债按阶段认领。
### 6. 阻塞 / 需要人
- 没有需要用户决策的阻塞。真机复测需要一台装有 NDK、连着 Redmi 的机器(审查轮所在的云容器没有)。
- 已知环境敏感项:`IterationRPProgram203Scenario`(`integration-magma-full-split`)偶发红,按 ID-P7-22 / ID-P12-12 读作"既有、环境敏感"(钉 lavapipe ICD 即绿),不阻塞 P12。
### 7. 真机与证据
- 当前 APK `26.09.29b7b28-trace`(控制修订 3,与 P7 终局窗口的 p7w8 server 不兼容);设备 Redmi `2f7cbe2e`(Adreno 830),定频协议 [`devices/pin-verification-2026-09-07.md`](../../guide/pin-verification-2026-09-07.md)。
- 真机证据 `notes/p12/device/`(`evidence-strip.png` 九格拼图,`trial-*/` 是按 head 归档的旧轮次);主机门日志 `notes/p12/gate/`;设备脚本 `notes/p12/android/`。
## 本目录
| 文件 | 内容 |