本目录承载项目文档。项目计划书.md 是唯一权威来源,与其余文档冲突时以计划书为准;CLAUDE.md(仓库根)是其执行摘要。
| 位置 | 内容 |
|---|---|
项目计划书.md |
唯一权威来源:产品定位、四信任域架构、VM 语义、题目 DSL、判题与威胁模型、测试验收 |
中期计划.md |
中期规划(UI 重设计 × 完整可用版本):验收定义 E-1develop/decisions-分发改版与UI重设计.md **D-UI-1 |
contracts/ |
冻结契约与规则文档(WP 交付物中"活"的规范面):字段分类、DSL 边界、 |
adr/ |
架构决策记录(ADR 全文见计划书 5.4;本目录收录决策的执行记录与复核依据) |
phases/ |
阶段任务分解与验收评审(随阶段推进增长) |
develop/ |
设计期文档(模块设计与整改裁决过程记录,非冻结契约) |
archive/ |
随退役面失去载体的历史证据(先归档再删除的不可复现证据;只增不改,非活契约、非现行门禁口径;见 archive/README.md) |
user/ |
使用文档(面向学习者 / 出题人 / 宿主平台的最终用户;非冻结契约,与权威规约冲突时以规约为准) |
| 文档 | 交付 | 说明 |
|---|---|---|
| 数据分类与秘密零驻留清单.md | WP-1 | 每个跨域字段的 PUBLIC / SERVER_ONLY / BOUNDARY 分类与"秘密不进浏览器"论证;机检条目供 CI 直接引用 |
| 最小DSL范围.md | WP-4 | 指令面 / 谓词面 / 编排面词汇的唯一来源;明确禁止项 |
| WP-5 | EMBED_PROTOCOL_VERSION / EMBED_THEMES / V-1~V-13)随插件形态整体退役,不再作为活契约;文件已随 WP-96 从磁盘删除,替代 = 启动票据 / 启动地址(见下行;已落地)。历史依据 = git 历史 + docs/develop/decisions-分发改版与UI重设计.md;其不可复现的证据面(iframe 面矩阵 axe 归档)经先归档再删除保留,见 archive/README.md |
|
| 版本策略.md | WP-6 | 四类版本的定义与关系、判题 / 回放记录项、生产环境锁定 |
| 启动票据协议.md | 分发改版 WP-90 | 服务端下发启动地址这条链的契约语义:目标时序、两份载荷字段表、票据形态与生命周期、换票与统一 401 失败语义、Redis launch:{jti} fail-closed 存储、攻击面与残留风险、与既有面 / 已退役面的关系、机检 9 条。契约面已落地,实现归 WP-91 / WP-92 |
| 规范化JSON序列化.md | WP-6 | stackmaster-canonical-json/1:TS 与 Rust 双实现跨语言一致的前提 |
| 文档 | 说明 |
|---|---|
| ADR-8-vm-core语言产能决策.md | vm-core 维持 Rust 的产能决策、证据与回退 tripwire(2026-09-05) |
| ADR-9-verifier进程形态决策.md | verifier 进程形态 Q1 定案(候选 (b):Node verifier + vm-worker 裁决重放命令面)、裁决映射与拒裁方向、隐藏测试 11 值汇总合成(§四·一,7×11 矩阵)、fuzz / miri 评估(2026-09-12) |
| 文档 | 说明 |
|---|---|
| [Vm 模块设计.md](develop/Vm 模块设计.md) | Vm 模块设计(硬规范与语义) |
| [Vm 模块设计冲突与整改方案.md](develop/Vm 模块设计冲突与整改方案.md) | G / D 系列裁决与整改批次记录 |
| [Vm 模块后续审查事项与整改清单.md](develop/Vm 模块后续审查事项与整改清单.md) | R 系列审查整改与回归纪律 |
| 引擎进程协议.md | 编排器 / verifier ↔ vm-worker 进程协议:版本登记、帧格式、命令面、职责切分与错误语义(WP-1,冻结;阶段六 WP-61 additive 演进:裁决重放命令面 export_action_log / verify,§4.9,版本维持 1) |
| 秘密零驻留CI检查项映射.md | 零驻留清单机检条目 → CI 检查项落点与反例位置(随 WP 接线更新) |
| 指令规约.md | vm-core 逐 opcode 执行语义权威规约:统一执行入口、位宽 / 栈 / 标志模型、异常与事件面、调用与 Canary、自定义指令与接口派发(WP-4) |
| 判题语义规约.md | vm-core 判题语义权威规约:谓词求值、权威成功 / 失败判定、多阶段状态机运行时、seed 策略与派生、隐藏测试执行(WP-5);§八·一 正式裁决 11 值汇总语义(阶段六 WP-62) |
| 快照与回放语义规约.md | vm-runtime 权威规约:COW 分页快照与 checkpoint、规范化动作日志(6.3 清单)、revision / undo / checkout / reset 语义、回放一致性、版本锁定与资源计数(WP-6) |
| 权威API语义规约.md | session-api / verifier(D-API-* )实现期决策单一登记处:路由与通道形态、凭证链路、版本窗口与幂等窗口运维参数、通道行为、工程载体纪律(配置 fail-closed / 日志纪律 / 优雅停机)、限流与配额、跨域机检、指标面与 k6 基线(阶段三 WP-0 ~ WP-8 全量;阶段六 WP-60 / WP-61:D-API-83data-window-type 锚点、moveTab 时序、Niri 布局交互、无障碍语义收敛);中期 M2:D-API-117 |
| decisions-分发改版与UI重设计.md | 分发改版与 UI 重设计的主控决策登记(2026-09-18 建立,生效中):P0-决 = D-UI-1 ~ D-UI-7(左右两分比例 / 视图位数量 / Ctrl+↑↓ 冲突处置 / 拖拽落点语义 / 窄屏降级 / 主题 token 收敛 / 无障碍与列表键盘路径)+ 分发侧实施前钉死项 D-LT-1 ~ D-LT-4(契约面颗粒度 / 票据形态与生命周期 / 日志与 Referer 处置 / 用户文档回填时机)+ 本次「不做」清单 8 项 + WP-90~99 派生义务落点表 |
| 文档 | 说明 |
|---|---|
| 阶段一任务分解.md | WP-0 ~ WP-6 任务、依赖与退出条件(已全部完成) |
| 阶段一验收评审.md | 阶段一退出条件逐条评审、门禁证据与阶段二移交项 |
| 阶段二任务分解.md | WP-0 ~ WP-9:vm-engine 工程载体、challenge-compiler、vm-core / vm-runtime / projection / vm-worker、会话编排核心、测试强化与收尾 |
| 阶段二验收评审.md | 阶段二退出条件逐条评审(十条全过)、13.1 清单逐条核对、门禁证据与 ADR-8 tripwire 验收点结论(WP-9) |
| 阶段三任务分解.md | WP-0 ~ WP-8:会话级命令与传输信封契约冻结、session-api 工程载体、认证与凭证、持久化与快照加密静止、REST 生命周期、认证 WSS 与投影下发、限流配额、跨域载荷机检与 Compose 集成、可观测与收尾 |
| 阶段三验收评审.md | 阶段三退出条件逐条评审(§五退出条件 → 可复跑证据)、13.3 / 13.5 条目核对表、TS / Rust / 覆盖率 / fixture / ZR-ENG 映射门禁证据汇总与阶段四 / 五 / 六移交项(WP-8) |
| 阶段四任务分解.md | 三轨道统一分解:前端落地(WP-F1 |
| 阶段四验收评审.md | 阶段四退出条件逐条评审(§五十条 → 可复跑证据)、清单 A 类 19 条勾稽表、门禁证据汇总、决策点定案记录(Q3/Q5/debugMode/ASLR/SeedDeriver 黄金向量/推送模型/虚拟列表裁决)与阶段五 / 六移交清单(WP-45) |
| 阶段五任务分解.md | WP-50 ~ WP-56:嵌入交付通道与描述包下发定案(前置)、embed-runtime 宿主侧 SDK 与 react-wrapper、插件 Shell 正式实现(web-component 占位退场)、主题与语言机制面(vm-ui 增量)、M2 描述包正式下发接入、测试与门禁(13.3 iframe 面 E2E / axe 真机补测 / 13.4 浏览器矩阵)、验收评审;边界裁决(契约零新增基线、主题/语言为实现义务非美化、CDN 归生产部署面)、六决策点与十条退出条件 —— 2026-09-18 分发改版注:本行所述 embed-runtime / react-wrapper / 插件 Shell / web-component 与 13.3 iframe 面 E2E 均随嵌入协议面整体退役(替代 = 与 API 同源的独立页面分发 + 启动票据 / 启动地址);该文档为历史证据(只增不改),不作为现行契约或现行形态的依据 —— 订正(2026-09-19 WP-96):上文「退役面」的物理下线与代码删除已于本批执行完毕(packages/{embed-runtime,react-wrapper,web-component}、apps/plugin-dev、docs/contracts/嵌入协议.md),本行所述形态在磁盘上已不存在 |
| 阶段六任务分解.md | WP-60 ~ WP-68:裁决呈现通道与异步裁决语义定案(前置,契约先行)、verifier 独立裁决服务(信任域 4)、隐藏测试裁决与正式裁决汇总(判题驱动复用)、正式裁决结果呈现(vm-ui 增量)与 ZR-T4 收口、审计面完善与归档、全面租户隔离与限流租户预算复核、容器级 Worker 隔离(T1)、安全测试收口(9.2 / 13.5 与裁决可复现)、MVP 题目集 / T3 扩展评估与验收评审;边界裁决(T0 收口与 T1 进入次序、v1 seed 无应用面的裁决重放语义、T2 / T3 边界、admin 不在本阶段)、六决策点(Q1~Q6)与十一条退出条件 |
| 阶段五验收评审.md | 阶段五退出条件逐条评审(§五十条:9 ✅ + 1 |
| 阶段六安全测试收口.md | WP-67 收口报告:9.2 威胁模型四边界逐格证据表(裁决边界攻击面矩阵:裁决伪造 / 重放请求伪造 / verdict 重询滥用 / 侧信道观察逐格锚)、13.5 秘密零驻留四类取证(构建产物 / 运行时含 verifier seed 零驻留与容器零留存 / 投影泄漏 ZR-P1 |
| 阶段六扩展评估报告.md | T3 七项候选(堆利用 / ROP / 防护机制深化 / 信息泄露类 / 更完整指令集 / 后端 WASM / 真实 ELF 实验模式)逐项三维评估:教学数据(D-API-107 每题观察点 + 十五章框架,MVP 试用未开始如实为"待观察"形态 + 观察启动判据)、性能基准(k6 三轮归档 / 容器冷启动与镜像预算 / verifier /metrics 观察面,数字出处逐项标注)、安全评审(9.2 四边界延伸:威胁面增量与前提条件)与触发条件建议;只评估不实现,是否扩展的最终决策不在本阶段产出(WP-68b) |
| 阶段六验收评审.md | 阶段六退出条件十一条逐条评审(11 ✅,条件 8 试用期 benchmark 注记 + 条件 10 fuzz CI 承载形态登记如实注明)、九工作包交付清单(commit hash + 主控修补登记)、MVP 验收 13.6 八条逐条证据、门禁证据汇总本机实跑(TS 2173 / Rust 728 双 profile / IT 覆盖率 2243 passed 整体四维 89.96+ / verifier 包 91.17+ 计入 / compose host 35 用例 / miri 零 UB / cargo-fuzz 本机不可用登记)、阶段二~五移交清单勾稽集中表(37 行:已完成(前期)9 / 本阶段完成 12 / 仍开放 12 / 持续有效 2 / 同参照 2)与遗留移交三节——阶段六关闭(WP-68b) |
| 中期任务分解.md | 中期计划(UI 重设计 × 完整可用版本)的执行层拆解:WP-70 ~ WP-82 逐包子任务(文件级落点 + 交付物 + 完成标准)与收口;E-1 |
| 中期M2核查表.md | 中期 M2 的 E-4 证据表:对照 docs/develop/前端的交互和开发设计.md(83 行)逐条核查工作区 / 内存视图窗口组件 / 栈视图 / 指令视图 / 寄存器视图 / 自由视图 / payload 搭建窗口,每条给出「符合 / 已定案 / 偏差已双向回填」三态与实现落点或 i18n 键面证据;含 §8 M2 增量一览与 §9 遗留(真机复验阻塞 / WP-74 效果面 / chip tooltip 微瑕 / WP-80 承接项) |
| 中期验收评审.md | 中期 M1~M3 的收口验收评审:E-1 |
| 中期试用报告模板.md | 首轮试用报告模板:按计划书第十五章 13 项观察项组织,每项标注数据来源(已有指标族 / 受控查询 / 人工访谈)与判据;与 D-API-107 每题观察点对齐(8 题 × 3 项) |
| 中期遗留清单.md | 中期遗留项的执行视图(派单与跟踪用):32 项按 P0 高优先 / P1 需 CI 清偿与外部阻塞 / P2 证据强度与门禁盲区 / P3 契约与覆盖缺口 / P4 低优先 分组,逐项给「状态 / 归属 / 触发条件 / 下一步动作 / 原§六#N 映射」,附统计总表、已闭环留档区、环境事实、编号双射一致性要求与建议派单分组;与 中期验收评审.md §六(评审期登记,承载判定依据与证据原委)双向约束、须同批更新 |
| 分发改版与UI重设计任务分解与接手入口.md | ➡ 分发改版 + UI 重设计的接手入口与排期(2026-09-18 建立,执行中:WP-90 ~ WP-95a 已落地;WP-96 在途):30 秒现状、必读文档索引、铁律(先契约后实现 / 可读性纪律 / 宿主三义项 / 退役≠可删 / 双射同批)、WP-90~99 排期与关键路径、门禁命令与已知环境事实、陷阱清单(PowerShell 往返 / Vite watcher / 假绿 / 正则误报)、第一批动作、不要做什么、已完成清单与交接自检清单 |
| 文档 | 面向 | 说明 |
|---|---|---|
| 学习者上手指南.md | 学习者 | 工作区(固定窗口集 + 列式条带)导览、读内存(窗口 / 锚点 / 跳转链)、Payload 积木、检查点与时间线、调试模式 what-if 纪律、提交与正式裁决(11 值)、16 错误码速查、MVP 八题学习路径 |
| 界面帮助手册.html | 学习者(界面参考) | 单文件网页手册:页面解剖与工作区布局模型(固定窗口集 / Niri 式列条带 / P0-P1-P2 预设 / 列宽窗高 / 降级渲染)、菜单·状态条·横幅逐项、字节视图(窗口/锚点/跳转/检索/交叉标注/跳转链)、寄存器与教学组件五件套、Payload 三区与积木全表、调试模式与指令视图、提交三态、断线重连、主题三预设(含 terminal 实际观感)、完整交互链(调试→解题→提交→反馈逐步含所见)、动作↔入口对照与窗口语义速查 |
| 出题人指南.md | 出题人 | 双包模型与红线、构造式制作流程(loadChallengePair 装载管线)、vmProfile / 内存布局 / IR 与字节模式 / 自定义指令与作者接口 / 判题面与隐藏测试 / 教学面 / 预算与随机化、高频拒绝规则速查、版本字段、已知边界(canary / ASLR / 输入槽) |
| 出题人文档/index.html | 出题人(分层分页文档,共 11 页) | 目录首页 + 四层:第 0 层认知入门(全局地图 + 31 术语卡)、第 1 层概念详解 7 页(32 个概念统一"一句话/展开/为什么/例子/常见误解"讲透:双包/位宽端序/栈帧劫持/IR 与字节模式/判题时机/谓词/隐藏测试/11 值/stages/种子/ASLR/装载管线/规范化 JSON/登记签名/出题者积木)、第 2 层任务指南(最小题/ret2win/接口 flag 题/排查手册/发布,5 个照着做)、第 3 层精确参考(公开/私有包字段表、20 opcode、谓词/微算子/效果原语、XS+XC 规则速查、错误码/版本/检查清单) |
| 宿主平台接入指南.md | 宿主平台 | 架构(平台后端 ⇄ session-api ⇄ 学习者浏览器以顶层导航打开一次性启动地址)、签发端点 / 地址下发 / 换票 / 建会话、配置键清单、旧插件形态迁移对照(2026-09-19 已按启动地址链重写,WP-96-C2);成绩同步章节(/host/scores,WP-78)保留不变 |
| 试用环境部署指南.md | 运维 / 部署者 | 试用环境(compose 单机公网)部署与回滚:运维端点暴露面定案(D-API-104 选项② 反代准入)、TLS 终止与域名、最小授权角色连线、环境变量与秘密注入方式(不存秘密、不入 git)、公网暴露面盘点;纪律 = 未实测不给配置片段 |
| 文档 | 说明 |
|---|---|
| README.md | 归档条目的来源 / 对应形态 / 保留理由与「这些面已不可达」的扫描面清单。现有条目 = axe-归档-plugin-dev/(原 apps/plugin-dev/e2e/reports/axe/**,3 个日期目录 / 27 个文件;归档与源逐文件 SHA256 一致后随 WP-96 删除原件)。只增不改,非活契约、非现行门禁口径 |
契约语义文档随契约单一来源放在包内(packages/*/docs),由包发布物携带:
packages/protocol/docs/会话动作协议语义.md(WP-2);packages/protocol/docs/投影与错误契约语义.md(WP-3);packages/challenge-schema/docs/双包Schema语义.md(WP-4);packages/challenge-compiler/docs/装载与编译期校验语义.md(阶段二 WP-2)。
应用上手文档:apps/session-api/README.md(阶段三 WP-8:Compose 一键拓扑、环境变量与迁移、test:compose 双形态、Windows 降级路径、/metrics 指标面、k6 基线、常见问题)。
工具文档:tooling/contract-smoke/README.md(跨语言契约冒烟)。
contracts/ 与包内契约语义文档均为冻结面:任何变更须先走 WP-1 §1.3 契约变更流程(先改分类论证 → 改契约包与 fixture → 评审 → 再改实现)。新增 ADR 落 adr/(命名 ADR-<编号>-<主题>.md);新阶段开工时在 phases/ 增加任务分解与验收评审。
2026-09-18 分发改版注(唯一例外面):contracts/嵌入协议.md 不适用上述版本演进流程 —— 嵌入协议面已整体退役(不做「收窄枚举 + 递增版本」,走硬切 + 迁移指引),替代 = 启动票据 / 启动地址(属新契约面,须先契约后实现,其本身照常适用本流程)。退役面的物理下线与代码删除不在本批(须与实现同批;计划书 §8.2 / §5.6 与 CLAUDE.md「在途改版」已记此纪律)—— 订正(2026-09-19 WP-96):该批已执行,contracts/嵌入协议.md 及退役三包与应用已在磁盘上删除;本条自此仅作历史留档(现行契约面 = 启动票据 / 启动地址,照常适用上述流程)。