规范化历史文档并合入 AGC 插件宿主能力 (#339)
## 变更 - 建立文档生命周期与现状索引，统一 `current`、`historical`、`review`、开放事项和活动计划边界。 - 为历史/待复核文档补充状态头，将有源码与测试证据的专题纳入当前入口。 - 新增规范驱动开发 skill 与 `check:doc-index` 门禁，并接入 `lint`。 - 合入 `origin/master` 的 AGC 通用插件宿主与 Cocos Creator 编辑器能力，并补充父子规范关系和验收范围。 ## 合并说明 - 合入基线：`origin/master` `4a46f89c9`。 - 合并提交：`259134b59`。 - 合并过程无冲突。 ## 验证 - `npm run check:doc-index` - `npm run check:encoding` - `git diff --check` - `python -X utf8 C:/Users/kdletters/.codex/skills/.system/skill-creator/scripts/quick_validate.py .codex/skills/spec-driven-development` - 推送前 pre-push master 门禁通过。 ## CI 请以本 PR 的 Gitea CI 检查为准；提交后持续关注，失败时按失败 job 继续修复。 Reviewed-on: #339 Co-authored-by: kdletters <kdletters@qq.com> Co-committed-by: kdletters <kdletters@qq.com>
This commit was merged in pull request #339.
This commit is contained in:
@@ -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 | | |
|
||||
```
|
||||
Reference in New Issue
Block a user