合并 origin/master 并同步 SpacetimeDB 2.8.3 指导

合并 origin/master 的工具与文档迁移删除已被统一 skill 替代的旧 SpacetimeDB skill 将统一 SpacetimeDB 指导更新到 2.8.3
2026-08-27 14:16:40 +08:00
parent 745eb75b1f 9476ff7648
commit 1c2dd0279b
91 changed files with 253 additions and 1036 deletions
@@ -1,6 +1,6 @@
 # 项目记忆目录

-本目录只保存可以通过 Git 共享、并且对当前开发仍有效的项目知识。`.hermes/` 只放 Hermes 工具资源，不作为项目知识库。
+本目录只保存可以通过 Git 共享、并且对当前开发仍有效的项目知识。`.codex/` 只放 Codex 工具资源，不作为项目知识库。

 ## 当前结构

@@ -2185,13 +2185,15 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证方式：微信小程序首点登录仍打开原生登录页；小程序支付仍跳转 `/pages/wechat-pay/index` 并保留 hash 回灌确认；订阅授权仍跳转 `/pages/subscribe-message/index` 且返回不阻断生成；普通浏览器分享、H5 支付和 Native 二维码支付不受影响。前端验证运行 HostBridge、auth、payment、分享、订阅和个人中心充值相关定向测试，并执行 `npm run typecheck`、`npm run check:encoding`。
 - 关联文档：`docs/【前端架构】宿主壳能力统一协议-2026-06-17.md`。

-## 2026-06-15 SpacetimeDB 本地 skills 只保留 CLI / Concepts / Rust
+## 2026-06-15 SpacetimeDB 本地 skills 范围（已由 2026-08-27 决策覆盖）
+
+> 2026-08-27 覆盖说明：本节记录的“三个本地 skill”方案已收敛为单一项目适配层；当前口径见下方“SpacetimeDB 项目 skill 与官方插件职责收敛”。

 - 背景：本仓库的 SpacetimeDB 接入已固定为 `server-rs + Axum + SpacetimeDB`，本地 skill 需要从上游 SpacetimeDB `skills/` 更新到 2.5 口径，同时避免继续维护当前项目不使用的 TypeScript server/client、C# 和 Unity 专用 skill。
- 决策：`.codex/skills/` 下只保留 `spacetimedb-cli`、`spacetimedb-concepts`、`spacetimedb-rust` 三个本地 SpacetimeDB skill；删除 `spacetimedb-typescript`、`spacetimedb-csharp`、`spacetimedb-unity`。前端 / Node 侧如需处理 SpacetimeDB 订阅或绑定，按当前生成绑定、项目代码和官方文档核对，不再依赖仓库内单独 TypeScript skill。
- 影响范围：`AGENTS.md` 的 SpacetimeDB skill 清单、`.codex/skills/` 本地 skill 维护范围、后续 SpacetimeDB 设计 / CLI / Rust module 开发协作口径。
- 验证方式：用上游 `clockworklabs/SpacetimeDB@master` 的 `skills/` 目录对照，运行本地 skill 校验、删除引用扫描、`git diff --check -- .codex/skills AGENTS.md .hermes/shared-memory/decision-log.md` 和 `npm run check:encoding`。
- 关联文档：`AGENTS.md`、`.codex/skills/spacetimedb-cli/SKILL.md`、`.codex/skills/spacetimedb-concepts/SKILL.md`、`.codex/skills/spacetimedb-rust/SKILL.md`。
+- 决策：当时仅在仓库内维护与当前后端路线相关的 SpacetimeDB skill，通用 SDK/CLI 内容按上游资料核对；该历史范围已由 2026-08-27 的项目适配层方案替代。
+- 影响范围：当时的 `AGENTS.md` SpacetimeDB skill 清单和本地 skill 维护范围；当前范围以新的项目适配层及官方插件路由为准。
+- 验证方式：保留当时的上游 skill 对照、本地 skill 校验、删除引用扫描、diff 和编码检查记录。
+- 关联文档：`AGENTS.md`、`.codex/skills/genarrative-spacetimedb/SKILL.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`。

 ## 2026-06-13 图片大图预览统一为黑底全屏查看器

@@ -3406,9 +3408,9 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在

 - 背景：新增玩法的创作工具如果默认复制既有玩法的聊天式 Agent、轻输入 Agent 或专属素材模型，平台会不断复制出不可控分支，后续接入、测试和恢复语义都会漂移。
 - 决策：新增玩法创作工具统一收敛为平台级 SOP：默认使用表单/图片输入创作工作台；单图资产统一通过 `CreativeImageInputPanel`；系列素材统一走批量规划、sheet 生图、后端切图、透明化、OSS 持久化和局部重生成流水线；不把任一玩法专属素材模型当平台通用模型。
- 影响范围：`CONTEXT.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、`.hermes/skills/genarrative-play-type-integration/SKILL.md`、后续新增玩法 PRD 和工程实现。
+- 影响范围：`CONTEXT.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、后续新增玩法 PRD 和工程实现。
 - 验证方式：新增玩法 PRD 必须显式声明单图资产槽位和系列素材槽位；新增工作台测试确认没有默认聊天式 Agent 输入；skill 通过 `quick_validate.py`。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、`.hermes/skills/genarrative-play-type-integration/SKILL.md`。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`。

 ## 2026-05-20 敲木鱼玩法按完整平台纵切接入

@@ -3983,13 +3985,13 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证方式：VN 定向前端测试、`npm run typecheck`、`npm run check:encoding`、`cargo test -p api-server visual_novel`、`cargo test -p api-server creation_agent_document_input`。
 - 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`。

-## 2026-05-04 在仓库 `.hermes/` 中建立团队共享记忆
+## 2026-05-04 建立仓库级项目知识与工具边界

- 背景：团队有 3 名开发人员，均在各自本地安装 Hermes，并需要独立拉取仓库、修改代码、本地测试；团队希望形成共享的长期项目记忆。
- 决策：不共享个人 `~/.hermes`，先在 Genarrative 仓库内使用 `.hermes/` 保存可 Git 同步的团队共享记忆、计划和未来 skills。
- 影响范围：`AGENTS.md`、`.hermes/README.md`、`docs/project-memory/shared-memory/`。
- 验证方式：任一开发者拉取仓库后，在项目根目录启动 Hermes，均可读取同一套 `docs/project-memory/shared-memory/` 文件。
- 关联文档：`.hermes/README.md`、`docs/project-memory/shared-memory/team-conventions.md`。
+- 背景：团队有 3 名开发人员，需要独立拉取仓库、修改代码和本地测试，同时共享稳定的项目知识与工具约定。
+- 决策：长期项目知识统一保存在 `docs/project-memory/`；仓库内 `.codex/` 仅保存可 Git 同步的 Codex skills、插件资源、hooks 和配置模板；个人 `~/.codex` 始终保持本机私有。
+- 影响范围：`AGENTS.md`、`.codex/README.md`、`docs/project-memory/shared-memory/`。
+- 验证方式：任一开发者拉取仓库后，先读 `AGENTS.md`，即可按入口读取同一套 `docs/project-memory/shared-memory/` 和 `.codex/skills/`。
+- 关联文档：`.codex/README.md`、`docs/project-memory/shared-memory/team-conventions.md`。

 ## 2026-04-25 后端唯一落地口径固定为 Rust / SpacetimeDB

@@ -5862,7 +5864,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在

 - 决策：Linux `command.exec / command.start / project.verify` 的安全事实源从固定 program / argv 白名单或平行 npm spawn 升级为同一个 bubblewrap OS sandbox launcher。approval policy 继续决定是否确认，sandbox 独立限制文件系统和网络；普通 confirm 永远不能扩大 sandbox。
 - 决策：Linux 只允许受信任系统 bubblewrap，缺失、权限异常或 namespace setup 失败必须在项目命令执行前失败关闭，不用裸 userns、代理变量或宿主全权限回退。当前机器 bubblewrap 0.11.1 已通过真实 namespace smoke，裸 userns 因 AppArmor uid_map 限制不可作为可靠 fallback。
- 决策：项目根可写，`.git / .agents / .codex / .hermes` 只读，`.agent` 隐藏且不可写，项目外普通用户文件不挂载，network namespace 默认隔离；HOME / TMP / cache 使用 sandbox 私有目录，所有 shell、PTY 和后代继承同一边界。
+- 决策：项目根可写，`.git / .agents / .codex` 只读，`.agent` 隐藏且不可写，项目外普通用户文件不挂载，network namespace 默认隔离；HOME / TMP / cache 使用 sandbox 私有目录，所有 shell、PTY 和后代继承同一边界。
 - 决策：Linux sandbox 生效后，program 扩展为受信任 PATH 中的裸可执行名，argv 仅保留结构长度与控制字符门禁，允许 shell 管道和项目脚本；Windows 在等价原生 sandbox 落地前继续使用 V1.10 固定白名单与 Job Object，不能宣称通用命令或 Codex CLI 级隔离。
 - 验收门禁：项目内构建 / 测试 / Git 读取成功；项目外读写、控制目录写入和网络访问失败；子进程与 PTY 会话继承相同边界；bubblewrap 不可用时零项目命令执行。真实 Provider 还需在无固定命令配方下自行发现并运行项目命令。
 - 审计与发布：process record v2 保存 launch 当时的 backend / mode / network / profile，后续 process 工具从 durable/live 身份读取，preflight 失败使用 unavailable / not-established，不能按平台静态宣称已建立。共享 `os-workspace-sandbox` capability 只标记 Linux；deb / rpm 声明 bubblewrap 依赖，AppImage 依赖宿主预装并保持 fail-closed。
@@ -7755,3 +7757,9 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - DirectProject 的 Codex cwd 固定为真实 `game/` 目录时，原生文件工具和 patch 必须使用 cwd 相对路径（`index.html`、`style.css`、`game.js`）；`game/...` 仅用于 AGC manifest、回执和客户端投影，不能作为 cwd 内原生 patch 路径，以避免 `writing outside of the project`。
 - 直连 Runtime 已取得 Developer Key 时，资源编辑的 `remote_credentials` 是该操作的完整身份边界；其中冻结平台快照为空表示 Developer 模式，禁止再从进程全局 GUI 登录态补回账号快照。平台账号模式仍只使用同一组凭据捕获的快照。
 - 回归覆盖 Direct 系统提示路径合同和 Developer Key / GUI 快照隔离；未触碰用户项目 `.agent` 锁、账本或凭据。
+
+## 2026-08-27 SpacetimeDB 项目 skill 与官方插件职责收敛
+
+- 决策：`.codex/skills/` 下的 SpacetimeDB 指导收敛为单一 `.codex/skills/genarrative-spacetimedb/SKILL.md`。官方 `spacetimedb` 插件负责通用 concepts、Rust server、CLI、TypeScript client 和 MCP 知识；项目 skill 只保留 Genarrative 的架构边界、schema/migration 门禁、目标 server 安全规则、运行时排障和验证路径。
+- 路由：涉及 SpacetimeDB 的任务统一先读取项目适配 skill，再按需读取 `spacetimedb:concepts`、`spacetimedb:rust-server`、`spacetimedb:cli`、`spacetimedb:typescript-client` 或 `spacetimedb:mcp`。插件通用示例不得覆盖项目禁止 `maincloud`、禁止人工 `spacetime --root-dir`、显式 server 和后端分层等约束。
+- 安装：团队环境缺少插件时使用 `codex plugin marketplace add clockworklabs/SpacetimeDB --sparse .agents --sparse codex-plugin` 和 `codex plugin add spacetimedb\@spacetimedb-plugins`；个人配置、缓存和凭据不进入仓库。
@@ -1,6 +1,6 @@
 # 开发工作流

-更新时间：`2026-08-25`
+更新时间：`2026-08-27`

 ## 标准流程

@@ -8,6 +8,8 @@
 确认工作树与目标分支 → 读取入口和当前专题 → 查代码真相 → 小步修改 → 定向验证 → 更新当前文档/记忆 → 检查提交边界
 ```

+任务开始时先写清一句话交付结果、验收判据和不做项，再按“必须项 / 风险项 / 可选项”排序。先完成修改、定向验证和边界检查组成的最小闭环；设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，否则记录为后续事项。不要让工具探测、历史整理或验证便利自行改变任务目标。
+
 ## 开始前

 - 运行 `git status --short`，保留用户已有的未提交修改；不要在共享工作树中使用破坏性 Git 命令。
@@ -35,6 +37,8 @@

 ## 验证路由

+SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.md`；该项目适配层按需调用已安装的官方 `spacetimedb` 插件 skill，插件提供通用 SDK/CLI/MCP 知识，项目 skill 负责 Genarrative 架构边界和验证门禁。
+
 按改动范围选择定向门禁，不以无关全量扫描代替契约验证：

 | 范围 | 至少运行 |
@@ -1,6 +1,6 @@
 # 任务交接模板

-> 用途：当一名开发者把任务交给另一名开发者，或让 Hermes 接续上下文时，复制本模板并填写。
+> 用途：当一名开发者把任务交给另一名开发者，或让 Codex 接续上下文时，复制本模板并填写。

 ## 基本信息

@@ -1251,7 +1251,7 @@
 - 原因：邀请码流程迁移后仍按新用户窗口保留 `canShowReferralRedeemShortcut` 次级入口；但当前页面口径已经固定为五项常用功能宫格，邀请码填写应由邀请链接 query 或明确引导打开弹窗。
 - 处理：移除常驻 `次级入口` / `填邀请码` 渲染，不删除 `ProfileReferralModal` 的 `redeem` 面板，也不破坏 `?inviteCode=` / `?invite_code=` 自动打开填写弹窗。
 - 验证：新用户账号打开“我的”页时没有 `次级入口` 和 `填邀请码` 按钮；带 `?inviteCode=spring-2026` 的登录用户仍自动打开邀请码弹窗并预填 `SPRING2026`。
- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`.hermes/skills/genarrative-profile-invite-flow/SKILL.md`。
+- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`.codex/skills/genarrative-profile-invite-flow/SKILL.md`。

 ## 创作卡片点击要直达已有入口表单，别再保留空白入口页

@@ -1914,13 +1914,13 @@
 - 验证：`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`；`npm run typecheck`。
 - 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/components/match3d-result/Match3DResultView.test.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

-## `.hermes` 只放共享内容，不放个人 Hermes 配置
+## `.codex` 只放项目工具，不放个人 Codex 配置

- 现象：团队成员误把个人 Hermes 配置、会话或密钥复制进仓库。
- 原因：仓库 `.hermes/` 与个人 `~/.hermes/` 名称相似。
- 处理：仓库 `.hermes/` 只放 Markdown 共享记忆、计划和可公开 skills；不提交 `.env`、`config.yaml`、`sessions/`、`auth.json`。
- 验证：提交前检查 `git diff -- .hermes`，确认没有密钥、会话记录或个人路径敏感信息。
- 关联：`.hermes/README.md`。
+- 现象：团队成员误把个人 Codex 配置、会话或密钥复制进仓库。
+- 原因：仓库 `.codex/` 与个人 `~/.codex/` 名称相似。
+- 处理：仓库 `.codex/` 只放可公开的 skills、插件资源、hooks 和配置模板；长期项目知识写入 `docs/project-memory/`，不提交 `.env`、`config.toml`、`sessions/`、`auth.json`。
+- 验证：提交前检查 `git diff -- .codex`，确认没有密钥、会话记录或个人路径敏感信息。
+- 关联：`.codex/README.md`。

 ## 儿童动作 Demo 卡在摄像头不可用或挥手不推进先查 mocap 消费链路

@@ -3306,7 +3306,7 @@
 - 原因：Vite 可能来自当前 worktree，但代理目标的 `api-server` 仍是另一个 worktree 的旧进程，或者 `api-server` 连到旧 SpacetimeDB 模块；此时 `/api/creation-entry/config` 会返回旧入口配置。
 - 处理：先用 `Get-NetTCPConnection -State Listen -LocalPort 3000,8083,3103` 结合 `Get-CimInstance Win32_Process` 确认端口进程路径；停止串线的旧 `api-server`，再用当前 worktree 的 `npm run dev:spacetime -- --spacetime-port <port> --database <database>` 和 `npm run dev:api-server -- --api-port <port> --spacetime-port <port> --database <database>` 拉起同一套服务。
 - 验证：`GET /api/creation-entry/config` 应包含目标入口，且监听端口的命令行都指向同一个 worktree；浏览器创作 Tab 对应分类应显示入口卡。
- 关联：`scripts/dev.mjs`、`.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+- 关联：`scripts/dev.mjs`、`.codex/skills/genarrative-dev-stack-port-routing/SKILL.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

 ## Windows junction 工作区下 dev.mjs 直接执行入口要用 realpath 判断

@@ -3683,8 +3683,8 @@

 - 现象：命令看似使用隔离 HOME / TMP、离线包管理器和不可达代理，仍能直接读取宿主用户文件、用原始 socket 联网，或由 `project.verify` 的平行 npm spawn 绕开 `command.exec` 限制。
 - 原因：环境变量和 argv 白名单只约束主动配合的程序，进程组 / Job Object 主要解决生命周期；它们不建立 mount / network namespace，也不能保护 `.agent` Runtime 控制面。只包 `command.exec` 而漏掉 `command.start` 或 `project.verify` 同样属于 fail-open。
- 处理：Linux 三个入口统一使用受信任系统 bubblewrap；项目根 rw，`.git / .agents / .codex / .hermes` ro，`.agent` 以 000 空 mount 隐藏，项目外普通用户路径不挂载，network namespace 默认隔离，嵌套 userns 禁用。全局 namespace canary 与项目 mount preflight 都必须在 revision / processId / 目标 program 前成功；任何失败都不回退宿主执行。Windows 在等价 restricted process / AppContainer 落地前继续标记为固定命令 legacy 边界。
- 验证：不能只断言 bwrap argv。必须运行真实目标和子进程，分别检查工作区写入、宿主 sentinel、五个控制目录、原始 socket、PTY stdin / graceful terminate、Runner SIGKILL 后宿主 `/proc` 无项目 cwd 进程，以及 unavailable 时 marker 为零。
+- 处理：Linux 三个入口统一使用受信任系统 bubblewrap；项目根 rw，`.git / .agents / .codex` ro，`.agent` 以 000 空 mount 隐藏，项目外普通用户路径不挂载，network namespace 默认隔离，嵌套 userns 禁用。全局 namespace canary 与项目 mount preflight 都必须在 revision / processId / 目标 program 前成功；任何失败都不回退宿主执行。Windows 在等价 restricted process / AppContainer 落地前继续标记为固定命令 legacy 边界。
+- 验证：不能只断言 bwrap argv。必须运行真实目标和子进程，分别检查工作区写入、宿主 sentinel、四个控制目录、原始 socket、PTY stdin / graceful terminate、Runner SIGKILL 后宿主 `/proc` 无项目 cwd 进程，以及 unavailable 时 marker 为零。
 - 关联：`apps/ai-game-creator-shell/src-tauri/src/command_sandbox.rs`、`command_exec.rs`、`process_session.rs`、`project.rs`、`docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`。

 ## 工具链环境根不能把整个用户目录挂进命令沙箱
@@ -4232,7 +4232,7 @@
 - 原因：两个进程角色共享同一 crate、target 和可执行文件，却被错误地当成两个互不相关的 dev service。更危险的是先启动 `GENARRATIVE_PROCESS_ROLE=all` 的 API：它会立即消费外部生成队列，可能在内部 BgFilter worker 尚未 ready 时领取任务。
 - 处理：`npm run dev` 与 `npm run dev:api-server` 只创建一套 Rust watcher，并把两个进程作为组合重启单元：先停止 API 与 BgFilter worker，再只让 worker 的 `cargo run` 完成必要构建，等待 worker `/readyz`，最后启动并验活 API。交互 `rs api-server`、`rs bgfilter-worker` 在完整栈内也必须走同一组合重启。`ProcessRole::All` 永远不内嵌 BgFilter listener；父子进程共享解析后的内部 base URL / Token，Linux 第五端口固定为端口段 `start + 4`，Windows 把第五端口纳入统一探测和漂移。
 - 验证：定向测试断言组合重启顺序为“stop API → stop worker → start/ready worker → start/ready API”，`dev:api-server` 自动带起同 runner worker，端口解析得到五个互不冲突的端口；再运行 `node --check scripts/dev.mjs`、dev-stack 定向测试和编码检查。
- 关联：`scripts/dev.mjs`、`scripts/dev-stack-port-utils.mjs`、`.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+- 关联：`scripts/dev.mjs`、`scripts/dev-stack-port-utils.mjs`、`.codex/skills/genarrative-dev-stack-port-routing/SKILL.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

 ## 固定 digest 不等于每个 CI job 都要强制拉镜像

@@ -4,7 +4,7 @@

 - 3 名开发人员在各自环境使用本地 Agent，通过同一 Git 仓库同步代码和项目知识。
 - 每个任务保持分支、工作树和修改范围清晰；多人或多 Agent 并行修改前先划分不重叠的文件边界。
- 项目知识进入 `docs/` 与 `docs/project-memory/`；个人 `~/.hermes`、Agent 会话和本地配置不共享。
+- 项目知识进入 `docs/` 与 `docs/project-memory/`；个人 `~/.codex`、Agent 会话和本地配置不共享。

 ## 开发前

@@ -556,7 +556,7 @@ V1.11 把命令安全边界从“固定 program + argv 规则 + 隔离环境变
 - `command.exec` 与 `command.start` 必须继续共用唯一 `ProjectCommandLaunchSpec`，`project.verify` 必须调用同一 sandbox launcher。真实 executable / argv 在该层包装为受信任系统 bubblewrap；一次性 Tokio child、PTY child wrapper、npm 验证脚本和全部后代不能有绕过该包装的生产 spawn 路径。
 - bubblewrap 只允许从固定系统候选路径解析，文件必须是普通可执行文件且不能被当前普通用户写入。缺失、权限异常、namespace setup 失败或挂载失败都返回 `sandbox-unavailable` / preflight 失败；不得尝试裸 `unshare`、代理断网或无沙箱宿主执行作为 fallback。
 - sandbox 使用独立 user / mount / pid / ipc / uts / cgroup / network namespace，禁用嵌套 user namespace，并启用 parent-death 收束。系统 executable / dynamic runtime 和明确工具链缓存只读挂载；规范项目根以原绝对路径读写挂载，cwd 仍必须是无 symlink / reparse point 的项目内目录。
- 项目根挂载后覆盖控制目录：`.git / .agents / .codex / .hermes` 存在时按原路径只读挂载；`.agent` 使用不可读写的空 mount 覆盖，命令不能看到 Runtime sidecar、会话、审计或配置。项目内指向外部的 symlink 因目标未挂载而不可访问。
+- 项目根挂载后覆盖控制目录：`.git / .agents / .codex` 存在时按原路径只读挂载；`.agent` 使用不可读写的空 mount 覆盖，命令不能看到 Runtime sidecar、会话、审计或配置。项目内指向外部的 symlink 因目标未挂载而不可访问。
 - HOME / USERPROFILE / TMP / Cargo / npm cache 使用 sandbox 内私有临时目录。允许只读复用不含凭据的工具链 source cache，但外部工具链环境根必须 canonicalize 后再次校验为与变量类型匹配的窄叶目录；`RUSTUP_HOME=$HOME`、`.rustup -> $HOME` 和其它宽用户目录必须失败关闭。不得挂载整个用户 HOME、AppData、SSH、云凭据、Cookie 或 Runtime 配置目录。
 - 网络 namespace 默认无外部网络，HTTP(S) / ALL proxy 与离线包管理器变量只作为纵深防御。`networkAccess` 首版固定 `disabled`，模型输入不能开启；需要联网必须作为未来独立 approval escalation 设计，不能复用普通 confirm 偷渡。

@@ -572,7 +572,7 @@ V1.11 把命令安全边界从“固定 program + argv 规则 + 隔离环境变

 - namespace canary 与项目 mount preflight 失败时，必须在 revision / processId 推进前返回稳定的 sandbox unavailable / setup 错误并保持项目命令未执行。当前 preflight 与随后真实 bwrap launch 是两次独立启动：真实 launch 若在目标 exec 前发生第二次 setup 失败，目标程序不会绕过沙箱执行，但尚无可信 exec-ready 握手证明失败阶段，revision 可能已经推进并按普通命令失败收束。这是 V1.11 已知残余，后续必须用 launcher 握手把“沙箱已建立且目标已 exec”与“仅准备采用沙箱”分开，不能把当前行为描述为原子保证。
 - command log、terminal receipt、Agent DB 和 process record 至少记录固定 `sandboxMode=workspace-write / networkAccess=disabled / sandboxBackend=bubblewrap / sandboxProfileVersion=workspace-v1` 安全元数据，不记录 host mount source、用户 HOME、bwrap 完整 argv 或本地工具链路径。process record 使用 schema v2 持久化 launch 当时的四项元数据，poll / stdin / terminate 和旧 boot reconciliation 必须从 record / live session 读取，不能按当前平台静态猜测；旧 v1 record 只能迁移为 `legacy-unknown`。纯 preflight 失败记录 `unavailable / not-established`，不得谎报 bubblewrap 已建立。
- 确定性真实进程测试必须证明：项目内构建 / 测试 / Git 读取成功；项目外普通文件读取与写入失败；`.git / .agent / .agents / .codex / .hermes` 写入失败；网络默认不可达；shell 子进程继承同一边界；bwrap 不可用时项目命令零执行且失败关闭。`command.start` 还必须让 PTY 后代实际执行 `setsid + chdir` 后的项目外读取、控制目录写入和原始 socket 负例，并断言 process record 与每段专用审计的四项 sandbox metadata。
+- 确定性真实进程测试必须证明：项目内构建 / 测试 / Git 读取成功；项目外普通文件读取与写入失败；`.git / .agent / .agents / .codex` 写入失败；网络默认不可达；shell 子进程继承同一边界；bwrap 不可用时项目命令零执行且失败关闭。`command.start` 还必须让 PTY 后代实际执行 `setsid + chdir` 后的项目外读取、控制目录写入和原始 socket 负例，并断言 process record 与每段专用审计的四项 sandbox metadata。
 - deb / rpm 发布包声明 `bubblewrap` 宿主依赖；AppImage 不携带 bubblewrap sidecar，发布页和安装检查必须明确要求受支持版本的系统 `/usr/bin/bwrap` 或 `/bin/bwrap`。缺失时命令工具安全失败关闭，但该 AppImage 不算具备可用的通用开发能力。
 - 真实 Provider disposable E2E 不给固定 program、文件名或工具顺序，要求模型自行发现项目技术栈，运行构建、测试和 Git 检查，并用结构化审计证明所有命令都在 workspace-write / network-disabled 下执行。上述门禁通过前不得宣称 V1.11 完成。

@@ -986,7 +986,7 @@ V1.24 修正仓库启动上下文把 `AGENTS.md` 与 README/CONTEXT 一律描述

 V1.25 在 V1.24 仓库启动上下文上增加项目内 Skill catalog，但不把 Skill 正文预加载到每轮 prompt。目标是对齐 Codex 的 progressive disclosure：模型始终只看到用于触发判断的 `name / description / entryPath / contentSha256`，任务真实命中后再通过现有 `file.read` 获取 `SKILL.md` 正文，并只按正文导航读取必要 reference。Skill 是项目工作流知识，不是新工具、权限包或可执行插件。

- 发现根固定为项目内 `.codex/skills/<skill-name>/SKILL.md` 与兼容目录 `.agents/skills/<skill-name>/SKILL.md`，只接受这两个根下的直接子目录入口，不递归把 reference 中的其它 `SKILL.md` 当独立 Skill。本仓库既有规范以 `.codex/skills` 为准；同名且两处都合法时 `.codex` 胜出，删除高优先级入口后 `.agents` 才可接管。V1.25 不扫描 AppData、用户主目录、全局 Codex/Hermes 安装目录、Git submodule 外部路径或网络 marketplace。
+- 发现根固定为项目内 `.codex/skills/<skill-name>/SKILL.md` 与兼容目录 `.agents/skills/<skill-name>/SKILL.md`，只接受这两个根下的直接子目录入口，不递归把 reference 中的其它 `SKILL.md` 当独立 Skill。本仓库既有规范以 `.codex/skills` 为准；同名且两处都合法时 `.codex` 胜出，删除高优先级入口后 `.agents` 才可接管。V1.25 不扫描 AppData、用户主目录、全局 Codex 安装目录、Git submodule 外部路径或网络 marketplace。
 - `skill-name` 必须与目录名和 YAML frontmatter `name` 完全一致，使用 1-64 个 ASCII 小写字母、数字或单连字符，首尾必须是字母或数字；frontmatter 必须位于文件开头并提供非空字符串 `name / description`。YAML 使用结构化 parser；未知字段不产生 Runtime 能力。描述清洗凭据和绝对路径、折叠为单行并限制 2048 bytes。
 - 单个 `SKILL.md` 最大 128 KiB，catalog 最多 64 项，prompt 中 Skill metadata section 最大 4 KiB。超限、解析失败、符号链接、路径不规范或读取失败的入口不进入 catalog；预算或读取导致的省略必须使 repository context 标记 `truncated=true`，不能把部分 YAML 当有效 metadata。
 - 仓库启动上下文升级为 `repository-startup-context-v3`，新增有界 `skills` 列表。fingerprint 覆盖 active Skill 的规范入口路径、来源根、清洗后 name/description、清洗后完整文件 SHA-256 和截断状态；Skill 正文、metadata、优先级或入口增删发生变化时，任何受 repository context gate 保护的旧 pending action 都必须先形成 drift blocker，再在同一 run 重规划。shadowed 的低优先级同名入口不影响 active 语义。
@@ -221,7 +221,7 @@ Supervisor 认领该回执后，由父 run 自己为每个原 delivery 逐一创
 - 状态询问、解释和不冲突补充默认继续当前 Provider；明确停止、改向或会让在途方案过期时才允许请求中断。判定失败时继续任务，并在下一安全边界消费消息，不得把失败等同于需要中断。
 - UI 通过持久 conversation 展示关联回复，刷新后仍可见；返回的 `assistantReply / interruptDecision / decisionReason` 只用于本次命令结果与诊断，不形成第二个会话或第二个 Run。

-V1.11 的受保护仓库控制目录同时包含 `.git / .agent / .agents / .codex / .hermes`；其中 `.agent` 对项目命令隐藏，其余控制目录只读。
+V1.11 的受保护仓库控制目录同时包含 `.git / .agent / .agents / .codex`；其中 `.agent` 对项目命令隐藏，其余控制目录只读。

 2026-08-04 起，Runtime 的公共工具规划指令、Supervisor 协作编排 playbook、条件 overlay 和编译期静态 Agent 节点目录统一由版本化 Prompt Bundle 驱动，位于 `apps/ai-game-creator-shell/src-tauri/prompts/runtime/`。`manifest.json` 是 section 路径、组合顺序、平台 / Editor 变体、role overlay、Provider 协作 fragment，以及 Supervisor 与六组专业 Agent 静态目录的单一来源；role overlay 只允许 `rootSourceKind` 强类型语义 selector，构建期拒绝未知 kind，运行期把权威 source 常量映射为生成 kind。`build.rs` 同时监听 Bundle 每一级目录、manifest 和已登记 section，保证任意嵌套目录新增孤立 Markdown 都会触发增量构建，并以失败关闭方式校验 schema、引用、路径 / symlink、孤立 Markdown、selector、节点身份、旧 alias 和生成标识符，再生成 `'static + Copy` Rust 定义并编译进发布二进制。公共 runtime system header 保持身份中立；生成的 Supervisor planning composition 必须复用 `supervisorChat.identity`。每个 section 只能属于 runtime composition、Supervisor composition、chat 字段、platform variant、visual variant、role overlay 或 Provider fragment 中一个语义所有者；唯一例外是同一 identity section 由 Supervisor planning 与 `supervisorChat.identity` 显式复用，从而同时阻断 Supervisor 指令外泄和动态 variant 与静态 composition 的重复注入。专业节点 taskId / group / role 还必须在构建期与 `shared-contracts::new_game_creation_app_seed_tasks()` 强一致，防止身份合同、静态目录和正式 seed DAG 漂移。Bundle 承载公共指令、隔离 Agent 合同、平台差异、角色选择、并行委派、all-join、视觉返工、claim gate，Supervisor 共享核心身份、interaction / final-reply 专属合同及其组合，以及首批协作、delivery 收敛、manifest wait、试玩后续委派等 repair 自然语言合同；background planning 在 system composition 复用核心身份，所有 user context 都不再重复注入 Supervisor 身份合同正文。`agent_runtime_native_executable_tools()` 仍是原生可执行工具的权威源列表，同时供 Prompt 工具目录与 native capability registry 使用，MCP 工具只从当前请求的动态 catalog 暴露。最终 Provider 请求必须通过生成的 section、composition、overlay 与 provider fragment API 构建，禁止恢复直接 `include_str!("prompts/runtime/...")`、在 Provider 或 `prompt.rs` 源码中复制协作 graph 文案，或依赖自然语言精确 `.replace()` 注入工具合同、平台规则或角色规则。Bundle 不是完整可执行 graph：正式 DAG 依赖边、权限、沙箱、委派容量、持久 all-join 状态机、完成门和身份校验仍由 Rust、`shared-contracts` 与经校验的 `.agent/collaboration-policy.json` 强制执行，不允许通过 Skill、外部配置或任意运行时 Prompt 覆盖绕过。

@@ -239,7 +239,7 @@ Prompt 静态门禁必须断言上述 Bundle section 当前定义的权威语义

 2026-07-14 V1.10 真实 `gpt-5.5` 验收：`process-session` 在无工具配方任务中完成 start / 3 次连续 cursor poll / stdin / terminate，41 条 task、75 条 event、63 条 Agent DB、8 条 receipt、4 套确认生命周期和唯一 completed / assistant，fixture launch 为 1，终态 PID / 端口、重放、重复与公共正文 / 密钥 / 诱饵泄漏均为 0。独立 Runner 强杀套件形成 21 条 task、34 条 event、36 条 Agent DB，新 boot 保持原 run / session，只产生 1 条 reconciliation，launch 仍为 1、PID reconnect / final / assistant / 重放 / 泄漏均为 0；两个 disposable 项目均已清理。

-2026-07-14 起，同一文档的“V1.11 OS 强制工作区沙箱与通用项目命令”替代 V1.2 / V1.10 在 Linux 上的固定 program / 严格 argv 白名单边界。`command.exec / command.start` 继续接受结构化 `program + args + cwd`、沿用 confirm policy、durable action、revision、verification、输出和进程会话协议；`project.verify` 也必须复用同一 launcher，不能保留平行的宿主 npm spawn。Linux 只在受信任系统 bubblewrap 创建的 workspace-write sandbox 内启动真实命令：项目根可写，`.git / .agents / .codex / .hermes` 只读，`.agent` 不可见且不可写，项目外普通用户文件不挂载，网络 namespace 默认隔离，所有后代继承相同边界。program 只接受无路径分隔符的裸可执行名并从受信任 PATH 解析，argv 只保留数量、长度和控制字符硬限制；允许 `bash -lc`、Git、构建器、测试器和项目脚本在沙箱内自行工作。外部工具链环境根必须 canonicalize 后校验为窄工具链目录，禁止把整个 HOME 或其符号链接目标挂入沙箱。bubblewrap 缺失、不可执行或 setup 失败必须在项目命令执行前失败关闭，不允许退回宿主全权限。process record v2 与命令审计持久化真实 launch metadata，失败不能按平台静态冒充已建立沙箱。共享 `os-workspace-sandbox` capability 只标记 Linux；Windows 首版继续使用原固定白名单、隔离环境和 Job Object，不能宣称已达到同等 OS sandbox。deb / rpm 声明 bubblewrap 依赖，AppImage 依赖宿主预装且缺失时功能失败关闭；approval 与 sandbox 仍是两层独立门禁。
+2026-07-14 起，同一文档的“V1.11 OS 强制工作区沙箱与通用项目命令”替代 V1.2 / V1.10 在 Linux 上的固定 program / 严格 argv 白名单边界。`command.exec / command.start` 继续接受结构化 `program + args + cwd`、沿用 confirm policy、durable action、revision、verification、输出和进程会话协议；`project.verify` 也必须复用同一 launcher，不能保留平行的宿主 npm spawn。Linux 只在受信任系统 bubblewrap 创建的 workspace-write sandbox 内启动真实命令：项目根可写，`.git / .agents / .codex` 只读，`.agent` 不可见且不可写，项目外普通用户文件不挂载，网络 namespace 默认隔离，所有后代继承相同边界。program 只接受无路径分隔符的裸可执行名并从受信任 PATH 解析，argv 只保留数量、长度和控制字符硬限制；允许 `bash -lc`、Git、构建器、测试器和项目脚本在沙箱内自行工作。外部工具链环境根必须 canonicalize 后校验为窄工具链目录，禁止把整个 HOME 或其符号链接目标挂入沙箱。bubblewrap 缺失、不可执行或 setup 失败必须在项目命令执行前失败关闭，不允许退回宿主全权限。process record v2 与命令审计持久化真实 launch metadata，失败不能按平台静态冒充已建立沙箱。共享 `os-workspace-sandbox` capability 只标记 Linux；Windows 首版继续使用原固定白名单、隔离环境和 Job Object，不能宣称已达到同等 OS sandbox。deb / rpm 声明 bubblewrap 依赖，AppImage 依赖宿主预装且缺失时功能失败关闭；approval 与 sandbox 仍是两层独立门禁。

 2026-07-14 V1.11.1 第一切片：`command.exec / project.verify` 已共用受信任 trampoline launcher。bwrap 的 `child-pid` 只推进 child-created，`--block-fd` 放行后仍须收到 `SANDBOX_READY`；Runtime 完成 revision / verification durable callback 后才发送 `COMMIT_EXEC`，收到 `EXEC_ESTABLISHED` 后才计算业务 timeout。当前不把这套 stdin 私有控制通道用于 PTY；`command.start` 与 process record v3 仍是下一切片，相关链路完成前 V1.11.1 保持进行中。

@@ -1177,7 +1177,7 @@ game-project/

 ## 2026-08-20 Direct Codex 审核 Skill Pack 与受控工具内核

- 普通项目对话只由一个 project-bound Codex app-server thread 执行。客户端系统提示词只放最小工程合同、当前游戏源码有界快照、项目 prompts 和审核 Skill 索引；不再批量读取项目 `.codex/.agents/.hermes` Skill 正文，也不恢复 Supervisor、专业 Agent 或 harness。
+- 普通项目对话只由一个 project-bound Codex app-server thread 执行。客户端系统提示词只放最小工程合同、当前游戏源码有界快照、项目 prompts 和审核 Skill 索引；不再批量读取项目 `.codex/.agents` Skill 正文，也不恢复 Supervisor、专业 Agent 或 harness。
 - 首页恢复“做游戏 / 做素材 / 做方案”三个创作类型，默认“做游戏”。该选择与设置页的 Agent Runtime 模式无关；每次首页提交仍只自动创建一个新项目并进入项目工作台。用户正文原样进入项目对话，`game|art|doc` 仅作为受限结构化首轮上下文传给同一 Codex thread，不拼接“初始意图”文案、不产生首页对话、不切换 Provider 或恢复旧 Runtime 编排。
 - `agc-skill-pack.v1` 只包含项目结构、陶泥儿美术、Web 游戏实现、真实浏览器试玩、客户端资源投影五项 Skill。清单记录用途、触发条件、所需工具、版本和内容 SHA-256；审核文本按 UTF-8 读取并将 CRLF 规范为 LF 后计算指纹和安装，避免混合换行造成 Windows / Linux 构建结果漂移，语义内容变化时必须同步重算对应清单指纹并提升版本。同步统一运行 `npm run agc:skill-pack:sync`，只读校验由 AGC `typecheck` 和 release build 自动执行，发现漂移时直接列出 Skill 与实际摘要，不让失配内容进入构建产物。客户端把审核文件安装到隔离目录后通过 app-server `skills/extraRoots/set + skills/list` 注册并复核，完整正文由 Codex 原生 Skill 机制按意图加载，一层引用只能经 `agc_read_skill_resource` 读取清单内 Markdown。引用路径按平台无关规则拒绝反斜杠、盘符、UNC、绝对路径和 `..`，不能依赖当前宿主的 `std::path` 语义判断其它平台路径。
 - DirectProject 只连接客户端内置的 `agc_tools` STDIO MCP，工具固定为审核引用读取、标准陶泥儿美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive 语义生成、已登记图片去背景和 desktop/mobile 浏览器试玩。MCP 进程只做协议；真实浏览器与付费 External v1 调用通过随机 loopback 地址回到客户端主进程，因此不复制 GUI 登录态、开发者 Key、项目路径、revision、operation 或幂等键到模型上下文。已登记工具固定自动批准，但付费资源工具仍由客户端绑定稳定回合身份、限制单回合请求数、串行执行并优先恢复匹配账本；通用 shell、Codex 原生 webSearch、任意网络、多 Agent、插件和外部 MCP 继续关闭。`codex_app_server` 模式要求 `llm.webSearchEnabled=false`。
@@ -24,7 +24,7 @@

 - `docs/`：当前 PRD、架构、开发运维、设计和测试口径。
 - `docs/project-memory/shared-memory/`：长期团队记忆、决策、流程和踩坑摘要。
- `.hermes/`：Hermes 工具资源，不作为项目知识库。
+- `.codex/`：Codex 工具资源，不作为项目知识库。
 - `.codex/skills/`：Codex 可复用技能；只在任务命中时读取。
 - `scripts/rag/`：Agent 本地检索入口，只提供候选上下文。

@@ -73,11 +73,11 @@ RAG 默认不安装运行时依赖，也不把 LanceDB、Transformers.js 或本

 ## SpacetimeDB 规则

-涉及 SpacetimeDB 设计、实现、脚本、调试、发布、绑定生成、schema、reducer、procedure、view 或 Rust API 时，先读取对应 skill：
+涉及 SpacetimeDB 设计、实现、脚本、调试、发布、绑定生成、schema、reducer、procedure、view 或 API 时，先读取项目适配 skill：

- `.codex/skills/spacetimedb-cli/SKILL.md`
- `.codex/skills/spacetimedb-rust/SKILL.md`
- `.codex/skills/spacetimedb-concepts/SKILL.md`
+- `.codex/skills/genarrative-spacetimedb/SKILL.md`
+
+该 skill 按任务范围路由到官方 SpacetimeDB 插件的 `spacetimedb:concepts`、`spacetimedb:rust-server`、`spacetimedb:cli`、`spacetimedb:typescript-client`、`spacetimedb:mcp` skill；项目边界覆盖插件通用示例。插件缺失时按项目 skill 中的安装命令补齐，个人插件配置、缓存和凭据不得进入仓库。

 已有表新增字段时，字段必须放在 Rust 表结构体最后，并设置明确默认值。删除、改名、重排或改类型前必须先询问用户并确认迁移计划。

@@ -93,8 +93,8 @@ RAG 默认不安装运行时依赖，也不把 LanceDB、Transformers.js 或本
 ## 技能路由

 - 新增、补齐、迁移或重构玩法入口、玩法类型、创作工作台、生成页、结果页、发布、运行态、作品架、广场或公开 read model：读取 `.codex/skills/genarrative-play-type-integration/SKILL.md`。
- 本地 dev 端口、代理目标、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理和后台 dev 串联：读取 `.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md`。
- 仓库级 Hermes skills/plugins：先读 `.hermes/README.md`，只把 `.hermes/` 当工具目录。
+- 本地 dev 端口、代理目标、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理和后台 dev 串联：读取 `.codex/skills/genarrative-dev-stack-port-routing/SKILL.md`。
+- 仓库级 Codex skills/plugins：先读 `.codex/README.md`，只把 `.codex/` 当工具目录。

 ## Issue 与提交

@@ -312,7 +312,7 @@ npm run check:admin-account-procedures

 项目已安装 `@colbymchenry/codegraph` 作为开发期依赖，用于在本地生成语义代码索引，辅助 AI / IDE 做符号搜索、调用关系和影响范围分析。索引目录为 `.codegraph/`，其中 `config.json` 可提交，数据库、缓存和日志由 `.codegraph/.gitignore` 保持本机私有。

-项目文档 RAG 索引使用 `scripts/rag/` 下的脚本和本地 `.rag/` 运行时目录，主要供 Agent 检索项目上下文，不作为人工阅读入口。默认不安装 RAG 相关依赖，不把 LanceDB、Transformers.js 或本地 embedding 模型写入根 `package.json`；需要启用时，Agent 必须先询问用户是否安装，并在用户确认后只安装到 gitignored 的 `.rag/runtime/`。索引范围默认包含 `AGENTS.md`、`CONTEXT.md`、`docs/project-memory/` 和 `docs/`，不把 `.hermes/` 工具目录作为项目知识库索引源。
+项目文档 RAG 索引使用 `scripts/rag/` 下的脚本和本地 `.rag/` 运行时目录，主要供 Agent 检索项目上下文，不作为人工阅读入口。默认不安装 RAG 相关依赖，不把 LanceDB、Transformers.js 或本地 embedding 模型写入根 `package.json`；需要启用时，Agent 必须先询问用户是否安装，并在用户确认后只安装到 gitignored 的 `.rag/runtime/`。索引范围默认包含 `AGENTS.md`、`CONTEXT.md`、`docs/project-memory/` 和 `docs/`，不把 `.codex/` 工具目录作为项目知识库索引源。

 首次拉取或需要重建索引时：

@@ -119,7 +119,7 @@ server-rs + Axum + SpacetimeDB
 - Issue tracker 是自托管 Gitea。可用 Gitea UI/API 或 `tea` CLI；不要用 GitHub `gh` 或 GitLab `glab`。
 - 默认 triage labels：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。
 - 根 `CONTEXT.md` 是当前领域语言入口；架构决策以本文档和 `docs/project-memory/shared-memory/decision-log.md` 的最新稳定摘要为准。
- `.hermes/` 只保存 Hermes 专用的仓库级工具资源，例如 skills、plugins 和启用说明；团队共享记忆、计划和 TODO 统一放在 `docs/project-memory/`，不提交个人 Hermes 配置、会话、密钥、Token 或本地私密路径。
+- `.codex/` 只保存仓库级 Codex 工具资源，例如 skills、plugins、hooks 和配置模板；团队共享记忆、计划和 TODO 统一放在 `docs/project-memory/`，不提交个人 Codex 配置、会话、密钥、Token 或本地私密路径。
 - 每次工程修改都应同步更新本目录当前文档；如果产生长期有效知识，再同步 `docs/project-memory/shared-memory/`。

 ## 当前文档策略