规范化历史文档并接入文档索引门禁

新增文档生命周期分类索引与可见状态头补充规范驱动开发模板和仓库级 skill 新增文档索引检查并接入 lint 修复文档入口链接并纳入现役专题
2026-09-13 14:53:18 +08:00
parent b12a81e9c2
commit a01709c55a
26 changed files with 548 additions and 11 deletions
@@ -5,6 +5,7 @@
 ## 目录约定

 - `.codex/skills/` 是项目专属 skill 根目录。每个 skill 以目录中的 `SKILL.md` 为入口，配套的参考资料和脚本放在同一目录下。
+- `spec-driven-development` 负责跨模块、公开契约、SpacetimeDB、AGC/Runtime 和复杂 UI 任务的规范先行与逐里程碑验收；具体规则以 `docs/` 下的 SDD 工作流和模板为准。
 - `.codex/plugins/` 保存随仓库分发的项目插件资源及其参考资料。当前的 `game-studio` 插件提供浏览器游戏设计、原型、2D/3D 技术栈、素材管线和 playtest 工作流；是否启用遵循当前 Codex 的插件加载机制，不依赖旧工具的环境变量或个人配置脚本。
 - `.codex/hooks/`、`.codex/environments/` 等目录保存项目工具链所需的 hooks 和环境模板；它们不替代项目代码中的运行时配置。
 - 长期有效的产品、架构、接口、排障和协作知识统一放在 `docs/` 与 `docs/project-memory/`，不复制到本目录。
@@ -0,0 +1,43 @@
+---
+name: spec-driven-development
+description: 在 Genarrative 中处理跨模块功能、公开 API/DTO、SpacetimeDB schema、AGC/Runtime 或复杂 UI 状态链路时，按主规范、里程碑规范、单里程碑实现计划和验收证据推进；小型局部修复不触发。
+license: MIT
+metadata:
+  codex:
+    tags: [SDD, 规范驱动开发, 主规范, 里程碑, 验收]
+---
+
+# SDD 规范驱动开发
+
+本 skill 把 Genarrative 的复杂任务路由到规范先行、单里程碑交付的工作流。权威规则和模板分别见：
+
+- `docs/【协作规范】规范驱动开发工作流-2026-09-12.md`
+- `docs/project-memory/shared-memory/【模板】规范驱动开发主规范与里程碑模板-2026-09-12.md`
+
+## 触发条件
+
+使用本 skill 的任务包括：
+
+- 跨前端、`api-server`、`platform-*`、`spacetime-client`、`spacetime-module` 或 `module-*` 的功能。
+- `/api/external/v1`、共享 DTO、OpenAPI、SpacetimeDB schema、迁移或跨版本重放合同变化。
+- AGC / DirectProject、Agent Runtime、工具白名单、审批、持久化恢复或资源工作流变化。
+- 复杂 UI 状态链路、入口/页面生命周期变化，或需要多个独立验收面的功能。
+
+文案、单文件局部修复、无行为变化重构和一次性诊断继续使用轻量流程；执行中一旦触及公开行为或跨模块合同，切换到本 skill。
+
+## 执行要求
+
+1. 检查工作树，读取当前专题、源码、测试、契约和历史决策；写清交付结果、验收判据和不做项。
+2. 找到或更新唯一主规范。主规范描述行为合同、边界、非目标、兼容/迁移和证据，不绑定实现细节。
+3. 在 `docs/project-memory/plans/` 创建一个或多个 `【里程碑】中文标题-YYYY-MM-DD.md`，填写 `Version`、`Status`、`Date`、`Parent Spec`、范围、依赖和验收标准；评审通过前不写业务代码。
+4. 每次只选择一个已评审里程碑，创建对应的 `【实施计划】中文标题-YYYY-MM-DD.md`，明确修改边界、顺序、验证命令、风险和回滚点。
+5. 发现行为需要变化时，严格按 `主规范 → 尚未实现的里程碑规范 → 当前实现计划 → 代码与测试` 更新。
+6. 完成一个里程碑后，提供主规范/里程碑逐条对照、自动化验证、必要运行时 smoke、边界验证和未验证项；未验收不得推进下一个里程碑。
+7. 全部验收通过后，将持久结论合并回主规范，删除已完成的临时计划，并检查文档、契约、测试和提交边界一致。
+
+## 约束
+
+- 里程碑和实现计划是开发期协调文件，完成或取消后删除；阶段编号和临时名称不得进入产品代码、用户文档、测试名称或提交标题。
+- 活动计划可以提交以便团队同步，但不得把一次性实现步骤写进长期规范。
+- 继续遵守现有 API、SpacetimeDB、AGC、编码和中文文档约束；本 skill 不替代专题门禁。
+- 文档任务至少运行 `npm run check:doc-index`、`npm run check:encoding` 和 `git diff --check`；代码任务再运行范围匹配的测试、类型检查、schema/OpenAPI 或运行时 smoke。
@@ -16,6 +16,7 @@
  3. [`docs/project-memory/README.md`](docs/project-memory/README.md)、[`project-overview.md`](docs/project-memory/shared-memory/project-overview.md)、[`team-conventions.md`](docs/project-memory/shared-memory/team-conventions.md)、[`development-workflow.md`](docs/project-memory/shared-memory/development-workflow.md)。
  4. 与任务相关的 [`decision-log.md`](docs/project-memory/shared-memory/decision-log.md)、[`pitfalls.md`](docs/project-memory/shared-memory/pitfalls.md)、[`docs/README.md`](docs/README.md) 和当前专题文档。
 - 落地工程修改前，先确认是否已有足够具体的 PRD、技术方案或当前融合文档；文档仍存在编码级歧义时，先补文档再编码。
+- 跨模块功能、公开 API/DTO、SpacetimeDB schema、AGC/Runtime 或复杂 UI 状态链路必须按 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](docs/【协作规范】规范驱动开发工作流-2026-09-12.md) 先完成主规范、里程碑规范和单里程碑实现计划；评审与验收门禁未通过前不得进入下一里程碑。局部修复、文案和无行为变化重构继续走轻量流程。
 - 本仓库的本地 RAG 位于 [`scripts/rag/`](scripts/rag/)；RAG 只作为候选上下文，不替代打开源文件核对。默认不安装 RAG 运行时依赖，需要启用时必须先询问用户，并只安装到 gitignored 的 `.rag/runtime/`。

 ## 绝对约束
@@ -5,10 +5,16 @@
 ## 必读入口

 1. [Agent 工作入口与执行准则](./【协作规范】Agent工作入口与执行准则-2026-06-22.md)
-2. [当前产品与工程约束](./【项目基线】当前产品与工程约束-2026-05-15.md)
-3. [server-rs 与 SpacetimeDB 数据契约](./【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md)
-4. [本地开发验证与生产运维](./【开发运维】本地开发验证与生产运维-2026-05-15.md)
-5. [项目记忆入口](./project-memory/README.md)
+2. [规范驱动开发工作流](./【协作规范】规范驱动开发工作流-2026-09-12.md)
+3. [文档生命周期与现状索引](./【协作规范】文档生命周期与现状索引-2026-09-12.md)
+4. [当前产品与工程约束](./【项目基线】当前产品与工程约束-2026-05-15.md)
+5. [server-rs 与 SpacetimeDB 数据契约](./【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md)
+6. [本地开发验证与生产运维](./【开发运维】本地开发验证与生产运维-2026-05-15.md)
+7. [项目记忆入口](./project-memory/README.md)
+
+## 文档治理
+
+- [文档生命周期与现状索引](./【协作规范】文档生命周期与现状索引-2026-09-12.md)：说明现行规范、历史记录、待复核文档、开放事项和活动计划的分类边界。

 ## 当前产品与平台

@@ -25,7 +31,7 @@

 - [AI 游戏创作智能体 App 实施计划](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)：当前 DirectProject、受控语义工具、UI workflow、资源和运行时合同。
 - [策划会话 Runtime V2 接入与旧链路退役方案](./technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md)：新单 Agent 策划会话、GDD 策略、未来 MCP/Skill 兼容插槽、阶段任务与退役验收合同。
- [DirectProject Codex 原始历史与异常恢复](./technical/【技术方案】DirectProject%20Codex原始历史与异常恢复-2026-09-04.md)：原始 Responses item 持久化、线程注入与异常回合收尾。
+- [DirectProject Codex 原始历史与异常恢复](<./technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md>)：原始 Responses item 持久化、线程注入与异常回合收尾。
 - [DirectProject 客户端 Skill 与 MCP 扩展导入方案](./technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md)：客户端扩展导入、按独立 Skill/MCP 拆分、命名、启用和启动时注入边界。
 - [AGC 客户端更新检查与下载](./technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md)：启动版本检测、OSS 清单格式和下载约定。
 - [DirectProject 本轮附件路径映射](./technical/【技术方案】DirectProject本轮附件路径映射-2026-08-31.md)：Direct 首轮只映射附件原名与项目相对路径，不灌正文、不区别 GDD。
@@ -65,9 +71,34 @@
 - [宿主壳能力统一协议](./【前端架构】宿主壳能力统一协议-2026-06-17.md)
 - [Expo React Native 与 Tauri 宿主壳方案](./【前端架构】ExpoReactNative与Tauri宿主壳方案-2026-06-17.md)

+## 已核准专题补充
+
+以下文档已有源码、测试或运行时证据，现纳入 `current` 集合：
+
+- [画板角色形象生成入口设计](./【编辑器】画板角色形象生成入口设计-2026-06-15.md)
+- [画板图标素材生成入口设计](./【编辑器】画板图标素材生成入口设计-2026-06-15.md)
+- [画板 UI 设计图生成入口设计](./【编辑器】画板UI设计图生成入口设计-2026-06-17.md)
+- [生成类面板 Lovart 统一改造方案](./【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md)
+- [宣发素材工具入口设计](./【编辑器】宣发素材工具演示入口设计-2026-06-17.md)
+- [预览画布缩放滑杆](./【交互设计】预览画布缩放滑杆-2026-09-05.md)
+- [图片画布撤销、恢复范围与操作提示方案](./【图片画布】撤销范围与操作提示方案-2026-07-17.md)
+- [微信虚拟支付接入](./【技术方案】微信虚拟支付接入-2026-05-26.md)
+- [SSE 客户端传输层收口约定](./technical/【前端架构】SSE客户端传输层收口约定-2026-06-03.md)
+- [全站客服悬浮入口接入约定](./technical/【前端架构】全站客服悬浮入口接入约定-2026-06-23.md)
+- [图片画布素材导出方案](./technical/【前端架构】图片画布素材导出方案-2026-06-15.md)
+- [UI 编辑器图片素材选择器](./technical/【前端设计】UI编辑器图片素材选择器-2026-09-03.md)
+- [后台 Dashboard 运营看板方案](./technical/【后台管理】Dashboard运营看板方案-2026-06-23.md)
+- [后台多账号与 Tab 访问权限方案](./technical/【后台管理】多账号与Tab访问权限方案-2026-07-14.md)
+- [Pingora 独立网关试点](<./technical/【开发运维】Pingora独立网关试点-2026-06-11.md>)
+- [AGC 后台模型别名与对话选择](./technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md)
+- [UI 编辑器工作流完成通知弹窗](./technical/【设计】UI编辑器工作流完成通知弹窗-2026-09-04.md)
+- [官网 SEO 地基实施约定](./technical/【SEO】官网SEO地基实施约定-2026-07-10.md)
+- [UI 编辑器拖动变换提交边界](./【UI编辑器】拖动变换提交边界-2026-09-03.md)
+
 ## 维护规则

 - 当前文档只保留稳定合同、公开契约和仍在推进的专题；一次性计划、实施记录和已关闭实验完成后删除或融合，不再长期堆积。
+- 文档现行/历史/待复核状态以[文档生命周期与现状索引](./【协作规范】文档生命周期与现状索引-2026-09-12.md)为准；未列入当前入口的文档不能直接作为实现依据。
 - `docs/project-memory/shared-memory/` 只保存长期有效的概览、决策、流程和踩坑；`plans/`、`todos/` 仅保存仍开放且有明确下一门禁的事项。
 - 修改 `/api/external/v1` 必须同步 OpenAPI 和契约测试；修改 SpacetimeDB schema 必须同步 migration、表目录、绑定和 schema 检查。
 - 旧模板、旧公开作品、旧运行态和旧后端路线不因历史源码或数据表仍存在而恢复入口。
@@ -14,7 +14,8 @@ docs/project-memory/
 │  ├─ document-map.md
 │  ├─ decision-log.md
 │  ├─ pitfalls.md
-│  └─ handoff-template.md
+│  ├─ handoff-template.md
+│  └─ 【模板】规范驱动开发主规范与里程碑模板-2026-09-12.md
 ├─ plans/   # 仅限正在执行的短期计划
 └─ todos/   # 仅限仍开放且有退出条件的事项
 ```
@@ -8,12 +8,21 @@
 确认工作树与目标分支 → 读取入口和当前专题 → 查代码真相 → 小步修改 → 定向验证 → 更新当前文档/记忆 → 检查提交边界
 ```

+跨模块功能、公开契约、SpacetimeDB schema、AGC/Runtime 和复杂 UI 状态链路在“小步修改”前增加 SDD 门禁：
+
+```text
+调研与定界 → 更新主规范 → 拆分并评审里程碑规范 → 为单个里程碑写实现计划 → 实现 → 对照规范验证与验收 → 合并主规范并清理临时计划
+```
+
+完整规则和模板见 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](../../【协作规范】规范驱动开发工作流-2026-09-12.md)。小型局部修改仍直接使用下方轻量流程；执行中若触及公开行为，立即升级到 SDD。
+
 任务开始时先写清一句话交付结果、验收判据和不做项，再按“必须项 / 风险项 / 可选项”排序。先完成修改、定向验证和边界检查组成的最小闭环；设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，否则记录为后续事项。不要让工具探测、历史整理或验证便利自行改变任务目标。

 ## 开始前

 - 运行 `git status --short`，保留用户已有的未提交修改；不要在共享工作树中使用破坏性 Git 命令。
 - 复杂任务先读 `AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`、`docs/README.md` 和对应专题。
+- 需要完整 SDD 的任务先确认主规范位置和验收证据，再创建 `docs/project-memory/plans/` 下的里程碑规范与实现计划；计划完成、取消或合并后删除。
 - 后端事实以 `server-rs/crates/api-server/src/app.rs`、`server-rs/crates/api-server/src/modules.rs`、Cargo manifest、SpacetimeDB schema 和源码为准；现役 API 不从未挂载模块推导。
 - External v1 以 `docs/openapi/genarrative-external-v1.openapi.json` 与 `modules/external_api.rs` 为准。
 - 本地端口的默认值只用于启动配置；实际运行端口以 `.app/dev-stack.json` 和启动日志为准。
@@ -31,6 +40,7 @@
 ## 文档维护

 - 当前稳定合同进入 `docs/`；长期决策、通用流程、排障经验进入 `shared-memory/`。
+- 文档现行、历史、待复核、开放事项和活动计划的分类以 [`docs/【协作规范】文档生命周期与现状索引-2026-09-12.md`](../../【协作规范】文档生命周期与现状索引-2026-09-12.md) 为准；`historical` 和 `review` 文件开头保留状态头，不能直接作为实现依据。
 - `plans/` 只保存正在执行且有明确下一门禁的计划；`todos/` 只保存真实开放且有关闭条件的事项。完成或作废后删除或融合。
 - 不把分支名、一次性测试轮次、提交流水账和个人路径写成长期规则。
 - H5 HostBridge 真实调用链的临时替身词扫描必须覆盖生产调用链；宿主壳真实能力以现行 HostBridge 协议与代码为准。
@@ -45,7 +55,7 @@ SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.m

 | 范围                | 至少运行                                                                                                                           |
 | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| 文档 / 中文文本     | `npm run check:encoding`、`git diff --check`                                                                                       |
+| 文档 / 中文文本     | `npm run check:doc-index`、`npm run check:encoding`、`git diff --check`                                                            |
 | 前端                | 相关 Vitest、类型检查；需要时做桌面/移动视口 smoke                                                                                 |
 | Rust 后端           | 对应 crate 的 `cargo test` / `cargo check`、`/healthz` smoke                                                                       |
 | External v1         | OpenAPI 解析、实现/DTO 契约测试和鉴权 smoke                                                                                        |
@@ -8,9 +8,11 @@

 1. `AGENTS.md`
 2. `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`
-3. `docs/README.md`
-4. `docs/project-memory/shared-memory/`
-5. 与任务匹配的当前专题合同
+3. `docs/【协作规范】规范驱动开发工作流-2026-09-12.md`（跨模块或公开合同任务）
+4. `docs/【协作规范】文档生命周期与现状索引-2026-09-12.md`
+5. `docs/README.md`
+6. `docs/project-memory/shared-memory/`
+7. 与任务匹配的当前专题合同

 后端 / 数据真相 / SpacetimeDB：

@@ -12,6 +12,7 @@
 2. 阅读 `AGENTS.md`；复杂任务继续读取 Agent 执行准则、项目概览、本文、开发工作流和当前专题文档。
 3. 以源码、`package.json`、Cargo manifest、`app.rs`、OpenAPI 和生成契约核对易漂移事实；RAG 与历史记录只提供候选上下文。
 4. 文档不足以确定字段、状态、迁移或验收时，先补当前权威文档再编码。
+5. 跨模块功能、公开契约、SpacetimeDB schema、AGC/Runtime 和复杂 UI 状态链路先建立主规范、里程碑规范和单里程碑实现计划，并在评审通过后实现。

 ## 开发中

@@ -0,0 +1,115 @@
+# 规范驱动开发主规范与里程碑模板
+
+本文件是规范驱动开发的复制模板；具体规则见 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](../../【协作规范】规范驱动开发工作流-2026-09-12.md)。模板中的阶段名称和编号只用于开发期文件，不得进入产品代码、用户文档、测试名称或提交标题。
+
+## 主规范模板
+
+```md
+# 【技术方案/产品合同】<功能名称>
+
+更新时间：`YYYY-MM-DD`
+
+## 目标
+
+## 非目标
+
+## 入口与边界
+
+- 用户/系统入口：
+- 涉及模块：
+- 正式状态来源：
+
+## 必须成立的行为
+
+### 正常路径
+
+### 失败、重试与幂等
+
+### 权限、归属与数据边界
+
+## 契约与迁移
+
+- API / DTO / OpenAPI：
+- SpacetimeDB schema / migration / bindings：
+- 兼容与迁移策略：
+
+## 验收标准与证据
+
+| 条款 | 验收方式 | 证据 |
+| --- | --- | --- |
+|  |  | 待补 |
+
+## 未决问题与决策
+```
+
+## 里程碑规范模板
+
+文件：`docs/project-memory/plans/【里程碑】<中文标题>-YYYY-MM-DD.md`
+
+```md
+# 【里程碑】<只描述行为切片>
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | proposed |
+| Date | YYYY-MM-DD |
+| Parent Spec | `docs/<主规范路径>` |
+
+## 目标
+
+## 范围
+
+## 不在范围内
+
+## 依赖与前置条件
+
+## 验收标准
+
+- [ ] 待补
+
+## 证据要求
+
+- 自动化：
+- 运行时：
+- 边界：
+```
+
+里程碑规范只写目标、边界和验收标准，不写文件清单、函数名、实现顺序或具体算法。
+
+## 实现计划模板
+
+文件：`docs/project-memory/plans/【实施计划】<中文标题>-YYYY-MM-DD.md`
+
+```md
+# 【实施计划】<对应里程碑>
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】<文件名>` |
+| Status | ready |
+| Owner | <人或 Agent> |
+
+## 修改边界
+
+- 允许修改：
+- 明确不修改：
+
+## 实现顺序
+
+1. 待补
+
+## 验证命令
+
+1. 待补
+
+## 风险与回滚点
+```
+
+## 验收证据矩阵模板
+
+```md
+| 规范条款 | 验证命令/操作 | 结果 | 证据位置 | 未验证原因 |
+| --- | --- | --- | --- | --- |
+|  |  | PASS/FAIL |  |  |
+```
@@ -1,4 +1,7 @@
 # 图片画布编辑器 Lovart 化与持久化接入方案
+> 文档状态：`historical`
+本文仅用于历史追溯，不作为当前实现依据。
+

 ## 背景

@@ -1,4 +1,7 @@
 # 图片画布编辑器前端拆分计划
+> 文档状态：`historical`
+本文仅用于历史追溯，不作为当前实现依据。
+

 日期：2026-06-17

@@ -1,4 +1,7 @@
 # 外部生成 Worker 化方案
+> 文档状态：`historical`
+本文仅用于历史追溯，不作为当前实现依据。
+

 > 2026-07-18 退役覆盖：旧创作模板 job 类型、玩法写回和玩法恢复链路均已退出现役 worker。当前 worker 只领取 `source_module = editor-canvas` 的任务；本文涉及拼图、跳一跳、拼消消、敲木鱼等玩法的内容仅作为历史设计记录，历史队列行不得被领取或改写。

@@ -1,4 +1,7 @@
 # 本地 SSH 服务器管理面板技术方案
+> 文档状态：`review`
+本文尚未核准为当前实现依据，请先核对文档生命周期索引和相关专题。
+

 日期：`2026-06-11`

@@ -1,4 +1,7 @@
 # AI 游戏创作 Agent Runtime V1.1 技术方案
+> 文档状态：`historical`
+本文仅用于历史追溯，不作为当前实现依据。
+

 原始版本：`2026-07-14`；口径复核：`2026-08-25`

@@ -1,4 +1,7 @@
 # 图片画布游戏场景生成链路
+> 文档状态：`historical`
+本文仅用于历史追溯，不作为当前实现依据。
+

 更新时间：`2026-08-08`

@@ -1,4 +1,7 @@
 # 【技术说明】AGC 接第三方 Provider 的兼容性缺陷
+> 文档状态：`historical`
+本文仅用于历史追溯，不作为当前实现依据。
+

 - 首次记录：2026-08-19
 - 最新核对：2026-08-27，当前实现仍保留本文所述 Provider 分发约束
@@ -1,4 +1,7 @@
 # 【技术说明】DirectProject 未消费用户上传权威文档
+> 文档状态：`historical`
+本文仅用于历史追溯，不作为当前实现依据。
+

 - 首次记录：2026-08-30
 - 问题类型：DirectProject 上下文消费缺陷 / 可审计性缺陷
@@ -1,4 +1,7 @@
 # AI Web 工程静态预览 MVP 验收清单
+> 文档状态：`historical`
+本文仅用于历史追溯，不作为当前实现依据。
+

 更新时间：`2026-06-13`

@@ -1,4 +1,7 @@
 # DirectProject 客户端 Skill 自然语言触发能力缺口
+> 文档状态：`historical`
+本文仅用于历史追溯，不作为当前实现依据。
+

 状态：待提 Issue，当前仅记录现状和候选方向，未修改代码。

@@ -1,4 +1,7 @@
 # 一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案
+> 文档状态：`historical`
+本文仅用于历史追溯，不作为当前实现依据。
+

 更新时间：`2026-05-25`

@@ -33,6 +33,7 @@ RAG 默认不安装运行时依赖，也不把 LanceDB、Transformers.js 或本
 ## 执行风格

 - 修改范围保持聚焦，不做无关重构。
+- 跨模块、公开契约、SpacetimeDB schema、AGC/Runtime 和复杂 UI 状态链路按 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](./【协作规范】规范驱动开发工作流-2026-09-12.md) 执行主规范、里程碑、实现计划和逐里程碑验收；局部修复继续使用轻量流程。
 - 优先复用现有系统、页面、组件、脚本、DTO 和文档位置。
 - 不新增平行入口、平行作品架、平行公开列表、平行业务真相或临时兼容层。
 - 不把前端临时状态当正式业务事实；正式状态以后端投影、后端 API 或当前架构文档为准。
@@ -0,0 +1,88 @@
+# 文档生命周期与现状索引
+
+更新时间：`2026-09-12`
+
+## 规范定位
+
+本文件是 `docs/` 文档治理的分类索引，解决“哪些文档可以作为实现依据”的问题，不替代各专题文档中的业务合同。代码、当前专题和最新决策与本索引冲突时，以代码和最新专题为准，并在同次变更中修正索引。
+
+## 分类规则
+
+| 状态 | 可否作为实现依据 | 规则 |
+| --- | --- | --- |
+| `current` | 可以 | `docs/README.md` 当前入口中的全部文档，以及 `project-memory/shared-memory/` 和 `project-memory/README.md` 中的当前流程、决策和概览。 |
+| `historical` | 不可以 | 文件名或正文明确标注为实施记录、专利交底、问题记录、历史设计或待提 Issue，只用于追溯。 |
+| `review` | 暂不可以 | 未进入当前入口且缺少足够明确的状态证据；负责人确认后才可转为 `current` 或 `historical`。 |
+| `open-todo` | 不可以 | `project-memory/todos/` 中仍开放的待解决或待评估事项，不能单独作为实现合同。 |
+| `active-plan` | 仅限当前里程碑 | `project-memory/plans/` 下正在执行的 SDD 计划，完成、取消或合并后删除。 |
+
+## 维护规则
+
+1. `docs/README.md` 只链接 `current` 文档、公开契约和本索引，不把 `historical`、`review` 或 `open-todo` 当作实现入口。
+2. 新增文档必须写清更新时间、状态和父规范；跨模块任务按 SDD 建立主规范、里程碑规范和实现计划。
+3. 文档行为被新合同覆盖时，先更新主规范，再把旧文档标为 `historical` 或删除，不保留互相冲突的“当前”说法。
+4. `review` 文档一次只处理一组相关主题，确认依据后再移动、合并或删除，不因整理方便批量改名。
+5. 归档只改变文档入口和分类，不删除仍被代码、契约、迁移或历史审计引用的文件。
+6. `historical` 和 `review` 文档文件开头必须保留对应状态头；状态变更时先更新索引，再同步状态头和 `docs/README.md` 入口。
+
+状态头格式：
+
+```md
+> 文档状态：`historical`（仅用于历史追溯，不作为当前实现依据）
+```
+
+或：
+
+```md
+> 文档状态：`review`（尚未核准为当前实现依据）
+```
+
+## 当前集合
+
+`current` 集合由以下可复核规则确定：
+
+- `docs/README.md` 中所有相对 Markdown 链接指向的文档。
+- `docs/project-memory/README.md`。
+- `docs/project-memory/shared-memory/*.md`。
+
+因此新增或移除当前规范时，优先更新 `docs/README.md` 或共享记忆目录，再同步本索引的状态说明。
+
+## 历史集合
+
+以下文档明确是历史记录、实施记录、专利材料或问题记录：
+
+- `docs/【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md`
+- `docs/【专利交底】一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案-2026-05-25.md`
+- `docs/technical/【问题记录】DirectProject客户端Skill自然语言触发能力缺口-2026-09-01.md`
+- `docs/technical/【技术说明】DirectProject未消费用户上传权威文档-2026-08-30.md`
+- `docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`
+- `docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md`
+- `docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`
+- `docs/technical/【技术方案】图片画布游戏场景生成链路-2026-08-04.md`
+- `docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`
+- `docs/technical/【技术说明】AGC接第三方Provider的兼容性缺陷-2026-08-19.md`
+- `docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md`
+
+这些文件保留用于追溯；若其中仍有有效结论，应先融合到当前专题，再删除重复表述。
+
+## 待复核集合
+
+以下文档未进入当前入口，当前先标为 `review`，不直接作为实现依据：
+
+- `docs/technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md`
+
+## 开放事项与活动计划
+
+当前 `open-todo`：
+
+- `docs/project-memory/todos/【待解决】AI游戏创作高风险审批Rank-2026-07-20.md`
+- `docs/project-memory/todos/【待评估】UI编辑器字体跨运行时像素一致性-2026-08-19.md`
+- `docs/project-memory/todos/【已知问题】AppConfig与AppState调试输出敏感配置泄漏-Master遗留-2026-08-07.md`
+
+当前没有活动计划；新任务按 SDD 规则在 `docs/project-memory/plans/` 建立计划，完成、取消或合并后删除。
+
+## 下一轮复核顺序
+
+1. 先处理与当前 AGC/Runtime、UI 编辑器和后台能力直接相关的 `review` 文档，逐份核对代码调用方和最新专题。
+2. 再处理已完成实施记录：保留发布、回滚或事故追溯证据，其余结论融合回主规范后删除。
+3. 最后检查 `docs/README.md` 链接和本索引覆盖率，确保新增文档不会绕过分类。
@@ -0,0 +1,96 @@
+# 规范驱动开发工作流
+
+更新时间：`2026-09-12`
+
+## 目的
+
+Genarrative 对跨模块行为、公开契约和持久化合同采用规范驱动开发（Spec-Driven Development，SDD）。先确定必须成立的行为和验收证据，再实现代码；实现发现行为需要变化时，先修改规范，再让未完成的工作重新对齐。
+
+这套流程补充现有的轻量开发流程，不把所有小改动都变成文档项目。
+
+## 适用范围
+
+以下任务必须走完整 SDD：
+
+- 跨前端、`api-server`、`platform-*`、`spacetime-client`、`spacetime-module` 或 `module-*` 的功能。
+- `/api/external/v1`、共享 DTO、OpenAPI、SpacetimeDB schema、迁移或跨版本重放合同的变化。
+- AGC / DirectProject、Agent Runtime、工具白名单、审批、持久化恢复或资源工作流的变化。
+- 复杂 UI 状态链路、入口/页面生命周期变化，或需要多个独立验收面的功能。
+- 任何无法用一个定向测试和一个局部补丁完整说明的需求。
+
+文案、单文件局部修复、无行为变化的重构和一次性诊断继续使用现有轻量流程；若执行中发现影响公开行为或跨模块合同，应立即升级为完整 SDD。
+
+## 产物与位置
+
+### 主规范
+
+主规范是长期维护的行为合同，放在现有权威 `docs/` 或对应专题文档中。它描述范围、必须成立的行为、边界、非目标、兼容/迁移和验收证据，不绑定具体类名、文件名或实现算法。已有专题文档足够精确时直接更新它，不新建平行主规范。
+
+主规范至少包含：
+
+1. 目标与非目标。
+2. 参与入口、状态和跨模块边界。
+3. 正常、失败、重试、幂等和权限行为。
+4. 数据/API/schema 约束及兼容或迁移要求。
+5. 验收标准与证据来源。
+6. 未决问题和决策记录（若有）。
+
+### 里程碑规范
+
+里程碑规范是开发期拆分出来的临时合同，放在 `docs/project-memory/plans/`，使用 `【里程碑】中文标题-YYYY-MM-DD.md` 命名。它必须写明 `Version`、`Status`、`Date`、`Parent Spec`、目标、边界、验收标准和依赖；不得写具体实现步骤。
+
+活动中的里程碑计划允许提交并通过 Git 在团队间同步。里程碑完成、取消或合并后立即删除；持久结论回写主规范或共享记忆，历史由 Git 保留。里程碑编号、阶段名称和临时文件名不得进入产品代码、面向用户文档、测试名称或提交标题。
+
+### 实现计划
+
+每个里程碑开始实现前，单独创建 `【实施计划】中文标题-YYYY-MM-DD.md`，放在同一 `plans/` 目录并引用对应里程碑规范。实现计划只覆盖一个里程碑，包含代码边界、修改顺序、验证命令、风险和回滚点；不得扩大里程碑契约。
+
+实现计划和里程碑规范都属于临时产物，完成后一起删除或融合，不把一次性步骤写进长期文档。
+
+## 工作流与门禁
+
+### 1. 调研与定界
+
+先检查工作树、当前专题、源码、测试、契约和历史决策，写清一句话交付结果、验收判据和不做项。确认主规范位置、受影响模块、成功证据和重大不确定性。重大不确定性未解决前不进入实现。
+
+### 2. 编写与评审
+
+更新主规范后，从主规范拆出里程碑规范和依赖关系，一并交付评审。评审至少确认范围、边界、状态转移、失败语义、兼容策略和验收证据；评审通过前不得写业务代码。
+
+### 3. 单里程碑实现
+
+一次只实现一个已评审里程碑。先落地该里程碑的实现计划，再按计划修改代码、契约、测试和对应文档。实现中若行为需要变化，按以下顺序更新：
+
+```text
+主规范 → 尚未实现的里程碑规范 → 当前实现计划 → 代码与测试
+```
+
+已经验收的里程碑不通过隐式兼容分支回写；需要改变其行为时，重新开一个明确的规范变更并说明迁移影响。
+
+### 4. 验证与验收
+
+验证同时对照里程碑规范和主规范，提交可复核的证据矩阵。证据应覆盖正常路径、失败关闭、权限/归属、幂等/重放、数据契约和必要的浏览器或真实运行时 smoke。定向测试通过不等于验收完成；必须明确哪些证据已获得、哪些因环境或 Provider 缺失而未验证。
+
+每个里程碑完成后停止推进，等待验收结论。未验收的里程碑不得作为下一个里程碑的已完成依赖。
+
+### 5. 合入与清理
+
+全部里程碑验收通过后，把最终持久行为和决策合并回主规范，核对实现、测试、OpenAPI/schema/绑定和专题文档一致，删除 `plans/` 下完成的临时文件，再检查提交边界。主规范不能留下“某里程碑期间”的阶段性措辞。
+
+## 验收证据最低要求
+
+交付记录至少列出：
+
+| 证据 | 内容 |
+| --- | --- |
+| 规范对照 | 主规范与当前里程碑的条款逐项结果 |
+| 自动化验证 | 实际执行的测试、类型检查、schema/OpenAPI 检查及结果 |
+| 运行时验证 | 必要的 API、浏览器、SpacetimeDB、AGC 或 Provider smoke |
+| 边界验证 | 权限、失败关闭、幂等、重试、恢复和数据泄漏检查（按任务取舍） |
+| 未验证项 | 环境缺失、真实 Provider/登录不可用或其他限制，以及剩余风险 |
+
+文档任务至少运行 `npm run check:doc-index`、`npm run check:encoding` 和 `git diff --check`。代码任务继续遵守现有前端、后端、SpacetimeDB 和 AGC 专题门禁；SDD 不替代这些门禁。
+
+## 模板
+
+可直接复制的主规范、里程碑规范、实现计划和证据矩阵模板见 [`docs/project-memory/shared-memory/【模板】规范驱动开发主规范与里程碑模板-2026-09-12.md`](project-memory/shared-memory/【模板】规范驱动开发主规范与里程碑模板-2026-09-12.md)。
@@ -1,4 +1,7 @@
 # SFX 生成优化 V2.0 T6 测试与发布门禁实施记录
+> 文档状态：`historical`
+本文仅用于历史追溯，不作为当前实现依据。
+

 日期：`2026-08-07`

@@ -61,6 +61,7 @@
    "clean:rust-incremental": "node scripts/rust-build-cache.mjs --clean-incremental",
    "test:rust-build-cache": "node --test scripts/rust-build-cache.test.mjs",
    "check:encoding": "node scripts/check-encoding.mjs",
+    "check:doc-index": "node scripts/check-doc-index.mjs",
    "check:git-hooks": "node --test scripts/git-hooks.test.mjs",
    "check:npm-workspaces": "node --test scripts/check-npm-workspaces.test.mjs && node scripts/check-npm-workspaces.mjs",
    "check:repository-ci": "bash scripts/check-repository-ci.sh",
@@ -113,7 +114,7 @@
    "check:server-rs-ddd": "npm run check:spacetime-schema && npm run check:spacetime-runtime-access && npm run check:module-runtime-artifact && node scripts/check-server-rs-ddd-boundaries.mjs",
    "lint:eslint": "eslint . --ext .ts,.tsx,.js,.mjs,.cjs --max-warnings 0",
    "typecheck": "tsc -p tsconfig.typecheck-guardrails.json --noEmit",
-    "lint": "npm run check:encoding && npm run check:npm-workspaces && npm run check:git-hooks && npm run check:rustfmt && npm run check:spacetime-schema && npm run check:production-ops && npm run check:preview-deployer && npm run check:maintenance-page && npm run lint:eslint && npm run typecheck",
+    "lint": "npm run check:encoding && npm run check:doc-index && npm run check:npm-workspaces && npm run check:git-hooks && npm run check:rustfmt && npm run check:spacetime-schema && npm run check:production-ops && npm run check:preview-deployer && npm run check:maintenance-page && npm run lint:eslint && npm run typecheck",
    "lint:fix": "eslint . --ext .ts,.tsx,.js,.mjs,.cjs --fix && prettier --write .",
    "format:rust": "cargo fmt --all --manifest-path server-rs/Cargo.toml && cargo fmt --all --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml",
    "format": "prettier --write . && npm run format:rust",
--- a/Show More
+++ b/Show More