2026-09-13 16:21:34 +08:00
28 changed files with 556 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-09-09.md)：通用插件宿主、SDK、权限审计、UI 挂载和 Cocos 编辑器适配边界。
 - [AGC Cocos Creator 编辑器桥接模块](<./technical/【技术方案】AGC Cocos Creator 编辑器桥接模块-2026-09-09.md>)：独立 crate、feature 开关、目标校验与 Windows 注入边界。
@@ -67,9 +73,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,5 +1,9 @@
 # AGC Cocos Creator 编辑器桥接模块

+> 文档状态：`current`
+> 父规范：[`AGC 通用插件宿主与编辑器适配`](./【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md)
+> 验收范围：Cocos Creator 目标校验、bootstrap/pipe 握手、操作目录、事务回滚、预览和 DirectProject 工具接入
+
 ## 2026-09-13 内置操作目录实施合同

 - 交付：在插件包内实现 36 个 `cocos_*` 操作，以同一份 JSON Schema 目录供插件宿主和 DirectProject `agc_tools` 使用；保留通用 execute。目录与实现一起随客户端编译分发，不依赖项目扩展或开发机目录。
@@ -1,5 +1,9 @@
 # AGC 通用插件宿主与编辑器适配

+> 文档状态：`current`
+> 规范关系：AGC 插件与编辑器适配主规范
+> 验收范围：插件 manifest、宿主生命周期、RPC、Capability/权限审计、UI 挂载和编辑器适配器边界
+
 更新时间：`2026-09-09`

 ## 目标与边界
@@ -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)。
--- a/Show More
+++ b/Show More