From a01709c55a509f9f8fd7ee8d92d7d12b5b16ce45 Mon Sep 17 00:00:00 2001 From: kdletters Date: Sun, 13 Sep 2026 14:53:18 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=E8=A7=84=E8=8C=83=E5=8C=96=E5=8E=86?= =?UTF-8?q?=E5=8F=B2=E6=96=87=E6=A1=A3=E5=B9=B6=E6=8E=A5=E5=85=A5=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E7=B4=A2=E5=BC=95=E9=97=A8=E7=A6=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增文档生命周期分类索引与可见状态头 补充规范驱动开发模板和仓库级 skill 新增文档索引检查并接入 lint 修复文档入口链接并纳入现役专题 --- .codex/README.md | 1 + .../skills/spec-driven-development/SKILL.md | 43 +++++++ AGENTS.md | 1 + docs/README.md | 41 ++++++- docs/project-memory/README.md | 3 +- .../shared-memory/development-workflow.md | 12 +- .../shared-memory/document-map.md | 8 +- .../shared-memory/team-conventions.md | 1 + ...规范驱动开发主规范与里程碑模板-2026-09-12.md | 115 ++++++++++++++++++ ...架构】图片画布编辑器MVP接入方案-2026-06-11.md | 3 + ...构】图片画布编辑器前端拆分计划-2026-06-17.md | 3 + ...端架构】外部生成Worker化方案-2026-06-03.md | 3 + ...】本地SSH服务器管理面板技术方案-2026-06-11.md | 3 + ...案】AI游戏创作Agent Runtime V1.1-2026-07-12.md | 3 + ...方案】图片画布游戏场景生成链路-2026-08-04.md | 3 + ...】AGC接第三方Provider的兼容性缺陷-2026-08-19.md | 3 + ...irectProject未消费用户上传权威文档-2026-08-30.md | 3 + ...例】AIWeb工程静态预览MVP验收清单-2026-06-13.md | 3 + ...ect客户端Skill自然语言触发能力缺口-2026-09-01.md | 3 + ...成高质量2D小游戏高一致性美术素材的解决方案-2026-05-25.md | 3 + ...规范】Agent工作入口与执行准则-2026-06-22.md | 1 + ...作规范】文档生命周期与现状索引-2026-09-12.md | 88 ++++++++++++++ ...协作规范】规范驱动开发工作流-2026-09-12.md | 96 +++++++++++++++ ...】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md | 3 + package.json | 3 +- scripts/check-doc-index.mjs | 110 +++++++++++++++++ 26 files changed, 548 insertions(+), 11 deletions(-) create mode 100644 .codex/skills/spec-driven-development/SKILL.md create mode 100644 docs/project-memory/shared-memory/【模板】规范驱动开发主规范与里程碑模板-2026-09-12.md create mode 100644 docs/【协作规范】文档生命周期与现状索引-2026-09-12.md create mode 100644 docs/【协作规范】规范驱动开发工作流-2026-09-12.md create mode 100644 scripts/check-doc-index.mjs diff --git a/.codex/README.md b/.codex/README.md index 4ea0ba9a9..f4d751fe4 100644 --- a/.codex/README.md +++ b/.codex/README.md @@ -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/`，不复制到本目录。 diff --git a/.codex/skills/spec-driven-development/SKILL.md b/.codex/skills/spec-driven-development/SKILL.md new file mode 100644 index 000000000..a55efe6bb --- /dev/null +++ b/.codex/skills/spec-driven-development/SKILL.md @@ -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。 diff --git a/AGENTS.md b/AGENTS.md index 7b4ddcfdd..003e0180c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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/`。 ## 绝对约束 diff --git a/docs/README.md b/docs/README.md index bf567a4e0..db23cb809 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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 检查。 - 旧模板、旧公开作品、旧运行态和旧后端路线不因历史源码或数据表仍存在而恢复入口。 diff --git a/docs/project-memory/README.md b/docs/project-memory/README.md index ee8ef51f8..397ea7af6 100644 --- a/docs/project-memory/README.md +++ b/docs/project-memory/README.md @@ -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/ # 仅限仍开放且有退出条件的事项 ``` diff --git a/docs/project-memory/shared-memory/development-workflow.md b/docs/project-memory/shared-memory/development-workflow.md index d72defe9e..6409631f4 100644 --- a/docs/project-memory/shared-memory/development-workflow.md +++ b/docs/project-memory/shared-memory/development-workflow.md @@ -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 | diff --git a/docs/project-memory/shared-memory/document-map.md b/docs/project-memory/shared-memory/document-map.md index 4f3754bf2..b807e9884 100644 --- a/docs/project-memory/shared-memory/document-map.md +++ b/docs/project-memory/shared-memory/document-map.md @@ -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： diff --git a/docs/project-memory/shared-memory/team-conventions.md b/docs/project-memory/shared-memory/team-conventions.md index 4d1753b5d..7dec95491 100644 --- a/docs/project-memory/shared-memory/team-conventions.md +++ b/docs/project-memory/shared-memory/team-conventions.md @@ -12,6 +12,7 @@ 2. 阅读 `AGENTS.md`；复杂任务继续读取 Agent 执行准则、项目概览、本文、开发工作流和当前专题文档。 3. 以源码、`package.json`、Cargo manifest、`app.rs`、OpenAPI 和生成契约核对易漂移事实；RAG 与历史记录只提供候选上下文。 4. 文档不足以确定字段、状态、迁移或验收时，先补当前权威文档再编码。 +5. 跨模块功能、公开契约、SpacetimeDB schema、AGC/Runtime 和复杂 UI 状态链路先建立主规范、里程碑规范和单里程碑实现计划，并在评审通过后实现。 ## 开发中 diff --git a/docs/project-memory/shared-memory/【模板】规范驱动开发主规范与里程碑模板-2026-09-12.md b/docs/project-memory/shared-memory/【模板】规范驱动开发主规范与里程碑模板-2026-09-12.md new file mode 100644 index 000000000..733366bcb --- /dev/null +++ b/docs/project-memory/shared-memory/【模板】规范驱动开发主规范与里程碑模板-2026-09-12.md @@ -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 | | | +``` diff --git a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md index 7bc040984..d166dfb70 100644 --- a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md +++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md @@ -1,4 +1,7 @@ # 图片画布编辑器 Lovart 化与持久化接入方案 +> 文档状态：`historical` +本文仅用于历史追溯，不作为当前实现依据。 + ## 背景 diff --git a/docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md b/docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md index 49d64adfc..3095e04e5 100644 --- a/docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md +++ b/docs/technical/【前端架构】图片画布编辑器前端拆分计划-2026-06-17.md @@ -1,4 +1,7 @@ # 图片画布编辑器前端拆分计划 +> 文档状态：`historical` +本文仅用于历史追溯，不作为当前实现依据。 + 日期：2026-06-17 diff --git a/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md b/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md index 9f796b666..3df5bb9ef 100644 --- a/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md +++ b/docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md @@ -1,4 +1,7 @@ # 外部生成 Worker 化方案 +> 文档状态：`historical` +本文仅用于历史追溯，不作为当前实现依据。 + > 2026-07-18 退役覆盖：旧创作模板 job 类型、玩法写回和玩法恢复链路均已退出现役 worker。当前 worker 只领取 `source_module = editor-canvas` 的任务；本文涉及拼图、跳一跳、拼消消、敲木鱼等玩法的内容仅作为历史设计记录，历史队列行不得被领取或改写。 diff --git a/docs/technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md b/docs/technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md index aeecda909..7099d8de1 100644 --- a/docs/technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md +++ b/docs/technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md @@ -1,4 +1,7 @@ # 本地 SSH 服务器管理面板技术方案 +> 文档状态：`review` +本文尚未核准为当前实现依据，请先核对文档生命周期索引和相关专题。 + 日期：`2026-06-11` diff --git a/docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md b/docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md index 876086c00..06e155fd2 100644 --- a/docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md +++ b/docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md @@ -1,4 +1,7 @@ # AI 游戏创作 Agent Runtime V1.1 技术方案 +> 文档状态：`historical` +本文仅用于历史追溯，不作为当前实现依据。 + 原始版本：`2026-07-14`；口径复核：`2026-08-25` diff --git a/docs/technical/【技术方案】图片画布游戏场景生成链路-2026-08-04.md b/docs/technical/【技术方案】图片画布游戏场景生成链路-2026-08-04.md index f40d27339..0879eb61a 100644 --- a/docs/technical/【技术方案】图片画布游戏场景生成链路-2026-08-04.md +++ b/docs/technical/【技术方案】图片画布游戏场景生成链路-2026-08-04.md @@ -1,4 +1,7 @@ # 图片画布游戏场景生成链路 +> 文档状态：`historical` +本文仅用于历史追溯，不作为当前实现依据。 + 更新时间：`2026-08-08` diff --git a/docs/technical/【技术说明】AGC接第三方Provider的兼容性缺陷-2026-08-19.md b/docs/technical/【技术说明】AGC接第三方Provider的兼容性缺陷-2026-08-19.md index 0bc7324d8..7f8381c29 100644 --- a/docs/technical/【技术说明】AGC接第三方Provider的兼容性缺陷-2026-08-19.md +++ b/docs/technical/【技术说明】AGC接第三方Provider的兼容性缺陷-2026-08-19.md @@ -1,4 +1,7 @@ # 【技术说明】AGC 接第三方 Provider 的兼容性缺陷 +> 文档状态：`historical` +本文仅用于历史追溯，不作为当前实现依据。 + - 首次记录：2026-08-19 - 最新核对：2026-08-27，当前实现仍保留本文所述 Provider 分发约束 diff --git a/docs/technical/【技术说明】DirectProject未消费用户上传权威文档-2026-08-30.md b/docs/technical/【技术说明】DirectProject未消费用户上传权威文档-2026-08-30.md index 9358213ac..c24f39e47 100644 --- a/docs/technical/【技术说明】DirectProject未消费用户上传权威文档-2026-08-30.md +++ b/docs/technical/【技术说明】DirectProject未消费用户上传权威文档-2026-08-30.md @@ -1,4 +1,7 @@ # 【技术说明】DirectProject 未消费用户上传权威文档 +> 文档状态：`historical` +本文仅用于历史追溯，不作为当前实现依据。 + - 首次记录：2026-08-30 - 问题类型：DirectProject 上下文消费缺陷 / 可审计性缺陷 diff --git a/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md b/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md index 45445ff21..7b09b265e 100644 --- a/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md +++ b/docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md @@ -1,4 +1,7 @@ # AI Web 工程静态预览 MVP 验收清单 +> 文档状态：`historical` +本文仅用于历史追溯，不作为当前实现依据。 + 更新时间：`2026-06-13` diff --git a/docs/technical/【问题记录】DirectProject客户端Skill自然语言触发能力缺口-2026-09-01.md b/docs/technical/【问题记录】DirectProject客户端Skill自然语言触发能力缺口-2026-09-01.md index 03c9e4b64..906f70499 100644 --- a/docs/technical/【问题记录】DirectProject客户端Skill自然语言触发能力缺口-2026-09-01.md +++ b/docs/technical/【问题记录】DirectProject客户端Skill自然语言触发能力缺口-2026-09-01.md @@ -1,4 +1,7 @@ # DirectProject 客户端 Skill 自然语言触发能力缺口 +> 文档状态：`historical` +本文仅用于历史追溯，不作为当前实现依据。 + 状态：待提 Issue，当前仅记录现状和候选方向，未修改代码。 diff --git a/docs/【专利交底】一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案-2026-05-25.md b/docs/【专利交底】一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案-2026-05-25.md index 391e1d69c..f8d27b8c6 100644 --- a/docs/【专利交底】一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案-2026-05-25.md +++ b/docs/【专利交底】一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案-2026-05-25.md @@ -1,4 +1,7 @@ # 一种极低成本快速生成高质量2D小游戏高一致性美术素材的解决方案 +> 文档状态：`historical` +本文仅用于历史追溯，不作为当前实现依据。 + 更新时间：`2026-05-25` diff --git a/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md b/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md index 1111073b8..297e08fa2 100644 --- a/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md +++ b/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md @@ -33,6 +33,7 @@ RAG 默认不安装运行时依赖，也不把 LanceDB、Transformers.js 或本 ## 执行风格 - 修改范围保持聚焦，不做无关重构。 +- 跨模块、公开契约、SpacetimeDB schema、AGC/Runtime 和复杂 UI 状态链路按 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](./【协作规范】规范驱动开发工作流-2026-09-12.md) 执行主规范、里程碑、实现计划和逐里程碑验收；局部修复继续使用轻量流程。 - 优先复用现有系统、页面、组件、脚本、DTO 和文档位置。 - 不新增平行入口、平行作品架、平行公开列表、平行业务真相或临时兼容层。 - 不把前端临时状态当正式业务事实；正式状态以后端投影、后端 API 或当前架构文档为准。 diff --git a/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md b/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md new file mode 100644 index 000000000..ec52ae65f --- /dev/null +++ b/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md @@ -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` 链接和本索引覆盖率，确保新增文档不会绕过分类。 diff --git a/docs/【协作规范】规范驱动开发工作流-2026-09-12.md b/docs/【协作规范】规范驱动开发工作流-2026-09-12.md new file mode 100644 index 000000000..abcc0e8b4 --- /dev/null +++ b/docs/【协作规范】规范驱动开发工作流-2026-09-12.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)。 diff --git a/docs/【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md b/docs/【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md index f923422ad..2ad92bfe0 100644 --- a/docs/【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md +++ b/docs/【实施记录】SFX生成优化V2.0T6测试与发布门禁-2026-08-07.md @@ -1,4 +1,7 @@ # SFX 生成优化 V2.0 T6 测试与发布门禁实施记录 +> 文档状态：`historical` +本文仅用于历史追溯，不作为当前实现依据。 + 日期：`2026-08-07` diff --git a/package.json b/package.json index e7ac811f0..4da401e86 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/scripts/check-doc-index.mjs b/scripts/check-doc-index.mjs new file mode 100644 index 000000000..b1c69eeb0 --- /dev/null +++ b/scripts/check-doc-index.mjs @@ -0,0 +1,110 @@ +import fs from 'node:fs'; +import path from 'node:path'; + +const root = process.cwd(); +const docsRoot = path.join(root, 'docs'); +const readmePath = path.join(docsRoot, 'README.md'); +const indexPath = path.join( + docsRoot, + '【协作规范】文档生命周期与现状索引-2026-09-12.md', +); + +const read = (file) => fs.readFileSync(file, 'utf8'); +const rel = (file) => path.relative(root, file).replaceAll(path.sep, '/'); +const resolveDocPath = (value) => { + const decoded = decodeURIComponent(value.replaceAll('\\', '/')); + const withoutPrefix = decoded.startsWith('./') ? decoded.slice(2) : decoded; + const target = path.normalize(path.join(docsRoot, withoutPrefix)); + const relative = path.relative(docsRoot, target); + if (relative.startsWith('..') || path.isAbsolute(relative)) { + throw new Error(`docs/README.md 链接越过 docs 根目录: ${value}`); + } + return target; +}; + +const readme = read(readmePath); +const index = read(indexPath); +const current = new Set(['docs/README.md', 'docs/project-memory/README.md']); + +for (const match of readme.matchAll(/\]\((?:<)?([^)>]+)(?:>)?\)/g)) { + const value = match[1]; + if ( + value.startsWith('http') || + value.includes('#') || + !(value.endsWith('.md') || value.endsWith('.json')) + ) + continue; + const file = resolveDocPath(value); + if (!fs.existsSync(file)) { + throw new Error(`docs/README.md 链接不存在: ${value}`); + } + if (value.endsWith('.md')) current.add(rel(file)); +} + +for (const file of fs.readdirSync( + path.join(docsRoot, 'project-memory', 'shared-memory'), +)) { + if (file.endsWith('.md')) + current.add(`docs/project-memory/shared-memory/${file}`); +} + +const sectionPaths = (heading, nextHeading) => { + const body = index.split(heading, 2)[1]?.split(nextHeading, 2)[0] ?? ''; + return new Set( + [...body.matchAll(/^- `([^`]+\.md)`$/gm)].map((match) => match[1]), + ); +}; + +const historical = sectionPaths('## 历史集合', '## 待复核集合'); +const review = sectionPaths('## 待复核集合', '## 开放事项与活动计划'); +for (const file of historical) { + if (review.has(file)) + throw new Error(`文件同时出现在 historical 和 review: ${file}`); +} +const allDocs = [...walkMarkdown(docsRoot)].map(rel); +const classified = new Set([...current, ...historical, ...review]); + +for (const file of [...historical, ...review]) { + const absolute = path.join(root, file); + if (!fs.existsSync(absolute)) throw new Error(`索引中的文件不存在: ${file}`); + const body = read(absolute).slice(0, 1200); + const expected = historical.has(file) ? 'historical' : 'review'; + if (!body.includes(`文档状态：\`${expected}\``)) { + throw new Error(`${file} 缺少 ${expected} 状态头`); + } + if (current.has(file)) + throw new Error(`${file} 同时被 current 和 ${expected} 分类`); +} + +for (const file of current) { + if (!file.endsWith('.md')) continue; + if (file === rel(indexPath)) continue; + const body = read(path.join(root, file)).slice(0, 1200); + if (/^> 文档状态：`(?:historical|review)`/m.test(body)) { + throw new Error( + `${file} 已进入 current，但仍保留 historical/review 状态头`, + ); + } +} + +for (const file of allDocs) { + if (file.includes('/plans/') || file.includes('/todos/')) continue; + if (!classified.has(file)) throw new Error(`文档未分类: ${file}`); +} + +for (const file of [...historical, ...review]) { + if (!allDocs.includes(file)) + throw new Error(`索引包含非 Markdown 文件: ${file}`); +} + +console.log( + `文档索引检查通过：${allDocs.length} 份 Markdown，current=${current.size}，historical=${historical.size}，review=${review.size}`, +); + +function* walkMarkdown(directory) { + for (const entry of fs.readdirSync(directory, { withFileTypes: true })) { + const file = path.join(directory, entry.name); + if (entry.isDirectory()) yield* walkMarkdown(file); + else if (entry.isFile() && entry.name.endsWith('.md')) yield file; + } +} -- 2.52.0 From 2694b81c5168799d222860ec8ff999afdc2d4a82 Mon Sep 17 00:00:00 2001 From: kdletters Date: Sun, 13 Sep 2026 14:59:42 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=E8=A7=84=E8=8C=83=E5=8C=96=20AGC=20?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E4=B8=8E=20Cocos=20=E5=90=88=E5=85=A5?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补充当前状态、父规范关系和验收范围 对齐 master 合入内容与文档生命周期索引 --- ...【技术方案】AGC Cocos Creator 编辑器桥接模块-2026-09-09.md | 4 ++++ .../【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/docs/technical/【技术方案】AGC Cocos Creator 编辑器桥接模块-2026-09-09.md b/docs/technical/【技术方案】AGC Cocos Creator 编辑器桥接模块-2026-09-09.md index 6dd227d24..74cbe6b64 100644 --- a/docs/technical/【技术方案】AGC Cocos Creator 编辑器桥接模块-2026-09-09.md +++ b/docs/technical/【技术方案】AGC Cocos Creator 编辑器桥接模块-2026-09-09.md @@ -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。目录与实现一起随客户端编译分发，不依赖项目扩展或开发机目录。 diff --git a/docs/technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md b/docs/technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md index 31fa1360d..778dddf1f 100644 --- a/docs/technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md +++ b/docs/technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md @@ -1,5 +1,9 @@ # AGC 通用插件宿主与编辑器适配 +> 文档状态：`current` +> 规范关系：AGC 插件与编辑器适配主规范 +> 验收范围：插件 manifest、宿主生命周期、RPC、Capability/权限审计、UI 挂载和编辑器适配器边界 + 更新时间：`2026-09-09` ## 目标与边界 -- 2.52.0