From b07fccb9ae163b9f5b35e43bc0c32d9d50f73434 Mon Sep 17 00:00:00 2001 From: kdletters Date: Thu, 27 Aug 2026 11:48:35 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=E6=94=B6=E6=95=9B=20SpacetimeDB=20?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E6=8C=87=E5=AF=BC=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 Genarrative 单一 SpacetimeDB 项目适配 skill 删除重复的 CLI、Rust、Concepts 项目 skill 更新 AGENTS 与协作工作流入口 同步项目决策记录和官方插件路由 --- .../skills/genarrative-spacetimedb/SKILL.md | 126 ++++++++ .codex/skills/spacetimedb-cli/SKILL.md | 178 ----------- .codex/skills/spacetimedb-concepts/SKILL.md | 119 -------- .codex/skills/spacetimedb-rust/SKILL.md | 280 ------------------ AGENTS.md | 2 +- .../shared-memory/decision-log.md | 18 +- .../shared-memory/development-workflow.md | 2 + ...规范】Agent工作入口与执行准则-2026-06-22.md | 8 +- 8 files changed, 146 insertions(+), 587 deletions(-) create mode 100644 .codex/skills/genarrative-spacetimedb/SKILL.md delete mode 100644 .codex/skills/spacetimedb-cli/SKILL.md delete mode 100644 .codex/skills/spacetimedb-concepts/SKILL.md delete mode 100644 .codex/skills/spacetimedb-rust/SKILL.md diff --git a/.codex/skills/genarrative-spacetimedb/SKILL.md b/.codex/skills/genarrative-spacetimedb/SKILL.md new file mode 100644 index 000000000..9590af7c9 --- /dev/null +++ b/.codex/skills/genarrative-spacetimedb/SKILL.md @@ -0,0 +1,126 @@ +--- +name: genarrative-spacetimedb +description: Genarrative 的 SpacetimeDB 项目适配规范。用于涉及 SpacetimeDB 架构、Rust module、schema、migration、reducer、procedure、view、绑定生成、CLI、MCP、发布、调试或运行时核验的任务。 +--- + +# Genarrative SpacetimeDB 项目指导 + +本 skill 只保存 Genarrative 的项目约束和操作边界；SpacetimeDB 的通用 API、语言 SDK 和 CLI 手册由已安装的官方插件提供。项目规则覆盖插件示例中的默认值或与本仓库冲突的建议。 + +## 官方插件依赖 + +开始 SpacetimeDB 任务时，按任务范围读取官方插件 skill： + +- `spacetimedb:concepts`：核心语义、表、reducer、procedure、view、订阅和身份。 +- `spacetimedb:rust-server`：Rust module、表属性、访问器、迁移兼容性和 SDK API。 +- `spacetimedb:cli`：初始化、构建、发布、生成绑定、SQL、调用、日志和 server 管理。 +- `spacetimedb:typescript-client`：前端生成绑定、订阅和 TypeScript 客户端 SDK；其它语言客户端按需读取插件对应 skill。 +- `spacetimedb:mcp`：通过已连接的 MCP 操作运行中的数据库；没有 MCP 工具时使用 CLI 等价命令。 + +如果当前环境尚未安装插件，使用： + +```bash +codex plugin marketplace add clockworklabs/SpacetimeDB --sparse .agents --sparse codex-plugin +codex plugin add spacetimedb\@spacetimedb-plugins +``` + +插件不可用时，以当前源码、`docs/`、生成绑定和仓库脚本为准，不凭记忆发明 SpacetimeDB API。 + +## 架构边界 + +Genarrative 的唯一有效后端路线是： + +```text +server-rs + Axum + SpacetimeDB +``` + +- `module-*`：领域模型、命令、应用规则、领域事件和领域错误；不得直接依赖 Axum、SpacetimeDB table/reducer/procedure、`spacetime-client`、外部平台或文件系统。 +- `spacetime-module`：SpacetimeDB 表、reducer、procedure、view、migration、事务 adapter 和 row mapper。 +- `spacetime-client`：后端访问 SpacetimeDB 的 typed facade；其它后端 crate 不直接创建第二套访问路径。 +- `api-server`：HTTP、SSE、BFF 和外部副作用编排。 +- `platform-*`：OSS、LLM、认证、语音等外部平台能力。 +- `shared-contracts` / `packages/shared`：前后端 DTO、公开契约和无业务真相的共享 TypeScript 代码。 +- 前端只负责表现、交互、临时 UI 状态和后端结果渲染，不绕过 BFF/投影直接读取私有表或推导正式业务状态。 + +SpacetimeDB 是数据和事务层，不替代 `api-server` BFF、`spacetime-client` facade 或公开 read model。插件提供的“SpacetimeDB 可替代传统服务端”通用描述不能改变本项目边界。 + +## 语义与安全不变量 + +- Reducer 是原子事务写路径，不向调用者返回业务数据；读取通过订阅、read model、view 或 BFF。 +- Reducer 必须确定性执行：不得访问文件系统、网络、系统时钟或外部随机源；使用 `ctx.timestamp`、`ctx.rng()` / `ctx.random()` 等 SpacetimeDB 能力。 +- 授权使用上下文中的 `ctx.sender()`（或当前语言对应 API），不信任调用参数传入的身份。 +- Auto-increment ID 不是排序依据；需要顺序时使用时间戳或显式序列字段。 +- Private table 是后端事实；用户可见状态通过 BFF、投影或明确的 public table/view 暴露。公共表仍只能由 reducer/procedure 写入。 +- Procedure 在 2.7 已稳定，可使用显式事务和 `ctx.http`；Genarrative 默认仍把外部 provider 协议放在 `platform-*`，把编排放在 `api-server`，除非当前架构明确要求 module procedure。 +- Event table 必须显式订阅，按插入事件消费；不要依赖其持久化行或 `OnUpdate`。需要更新回调时使用持久表或带主键的 procedural view。 +- Standalone MCP 是 operator/developer 集成面，不是 BFF、facade 或公开 read model 的替代品。MCP/SQL/CLI 的写入都必须有明确授权；日常 smoke 优先只读。 + +## Schema 与迁移 + +修改现有 SpacetimeDB persistent table 时： + +1. 新字段只能追加到 Rust 表结构体末尾，并设置明确的 `#[default(...)]`。 +2. 删除、改名、重排、改类型或破坏性约束变更前，必须先询问用户并确认迁移计划。 +3. 同步更新 `server-rs/crates/spacetime-module/src/migration.rs`、后端架构文档中的表目录、生成绑定和相关契约/测试。 +4. 运行： + + ```bash + npm run spacetime:generate + npm run check:spacetime-schema + ``` + +Event table 的较宽松自动迁移规则不适用于 persistent table，不能借此绕过上述门禁。以当前源码和 `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 为 schema 真相。 + +## CLI、目标 server 与本地开发 + +- 优先使用仓库 wrapper：`npm run dev:spacetime`、`npm run dev:api-server`、`npm run spacetime:generate`。 +- 直接使用 CLI 时始终显式传 `--server` 或 `--server-url`；不要依赖默认云端目标或个人 CLI 默认 server。 +- 不新增 `maincloud` / `MAINCLOUD` 命令、环境变量、脚本或文档；历史残留只按历史处理。 +- 人工命令、本地联调、排障步骤和文档示例禁止使用 `spacetime --root-dir`；本地数据隔离使用项目脚本或 `--data-dir`。 +- `spacetime publish` 的 `--delete-data=always` 只在明确授权的破坏性操作中使用；schema 冲突优先按项目脚本和受控迁移流程处理。 +- 项目 SpacetimeDB crate、SDK、CLI/standalone 和生成 bindings 按 `2.7.0` 对齐；官方 `v2.7.0-hotfix3` 是发行资产标签，运行时二进制仍应报告 `2.7.0`，当前 hotfix3 CLI commit 为 `d220349adb7af7eefa810eb08a185609356b83f6`，裸 tag commit `a08663c7b94688a2542577532d472f751e641f5b` 即使版本号相同也必须拒绝。升级时核对 Cargo 精确 pin、实际 CLI 和运行中服务二进制，不把本地 CLI 重装当作仓库升级。 + +本地开发默认由项目启动器管理端口；实际监听地址以 `.app/dev-stack.json` 和启动日志为准，不能从文档默认端口推断当前目标。发布后确认 api-server 使用的是同一 database、server 和 token。 + +## MCP 与运行时核验 + +如果当前会话暴露 SpacetimeDB MCP 工具，读取运行中的数据库优先使用 typed MCP：先 `list_databases` / `get_schema`，再做只读 SQL 或 `ping`；调用 reducer 或 SQL 写入前确认目标、身份和授权。没有 MCP 工具时使用显式目标的 CLI。2.7 standalone 的 MCP HTTP endpoint 是 `POST /v1/database/{name_or_identity}/mcp`，提供 `ping`、`get_schema`、`sql`、`call`；升级 smoke 在隔离数据库中只做 `initialize`、`tools/list`、`ping`、`get_schema`，除非写入明确属于任务范围。 + +排查“服务健康但业务不可用”时按顺序核对： + +1. SpacetimeDB standalone 是否运行（本地优先 `npm run dev:spacetime`，主机侧核对 systemd）。 +2. module 是否发布到 api-server 实际使用的同一个 server/database。 +3. 生成绑定是否来自当前 module。 +4. api-server 的 database、server URL 和 token 是否一致。 +5. reducer/procedure 是否真正被调用；区分超时、权限、schema 不存在和业务错误。 +6. `/healthz` / `/readyz` 通过但业务仍失败时，继续检查 API 日志和公开路由，不把健康检查当作业务成功证明。 + +主机升级需核对运行中进程而非只看 PATH： + +```bash +type -a spacetime +spacetime --version +pid="$(systemctl show spacetimedb.service -p MainPID --value)" +readlink -f "/proc/${pid}/exe" +"/proc/${pid}/exe" --version +curl -fsS http://127.0.0.1:3101/v1/ping +``` + +## 修改后的最小验证 + +按范围执行定向测试/类型检查，并至少运行： + +```bash +npm run check:encoding +git diff --check +``` + +涉及 schema 时追加 `npm run spacetime:generate` 和 `npm run check:spacetime-schema`；涉及 API 时按当前后端文档启动 `npm run dev:api-server` 并检查 `/healthz`。无法运行的验证要在交付说明中标记为未验证并说明原因。 + +## 参考入口 + +- `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` +- `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` +- `server-rs/README.md` +- `scripts/check-spacetime-schema-guard.mjs` +- `scripts/check-server-rs-ddd-boundaries.mjs` diff --git a/.codex/skills/spacetimedb-cli/SKILL.md b/.codex/skills/spacetimedb-cli/SKILL.md deleted file mode 100644 index 73dac7168..000000000 --- a/.codex/skills/spacetimedb-cli/SKILL.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -name: spacetimedb-cli -description: SpacetimeDB 2.7 CLI reference for Genarrative. Use for spacetime build, publish, generate, call, sql, logs, server management, local dev, explicit server targeting, version checks, and remote runtime verification. ---- - -# SpacetimeDB CLI - -Use this skill when working with the `spacetime` CLI in Genarrative. Prefer repository scripts when they exist, and keep every operation pinned to an explicit target server or local process. - -## Genarrative Rules - -- Do not rely on the default SpacetimeDB cloud target. Pass `--server` or `--server-url` explicitly in scripts, docs, smoke tests, and manual troubleshooting. -- Do not introduce `maincloud` / `MAINCLOUD` commands, env vars, or docs. Treat old references as historical residue. -- Do not use `spacetime --root-dir` in manual commands or docs. Use project scripts, `--data-dir`, explicit `--server`, or the configured running service. -- For repository version upgrades, update `server-rs/Cargo.toml` exact pins, regenerate bindings, and verify the actual CLI/runtime version. Do not treat a local CLI reinstall as a repo upgrade. -- For host upgrades, verify the running service binary, not just shell PATH: `systemctl show ... MainPID` -> `/proc/$pid/exe --version` -> `/v1/ping`. - -## Core Commands - -```bash -# Build module -spacetime build -spacetime build --debug - -# Publish to an explicit server -spacetime publish my-database --server http://127.0.0.1:3101 --yes=migrate,break-clients - -# Destructive publish only when explicitly intended -spacetime publish my-database --server http://127.0.0.1:3101 --delete-data=always --yes=delete-data,migrate - -# Delete data only for breaking schema conflicts -spacetime publish my-database --server http://127.0.0.1:3101 --delete-data=on-conflict --yes=migrate - -# Generate bindings -spacetime generate --lang typescript|csharp|rust|unrealcpp --out-dir ./bindings --module-path ./server -``` - -## Genarrative Local Workflow - -```bash -# Prefer project wrappers -npm run dev:spacetime -npm run dev:api-server -npm run spacetime:generate - -# Query local database -spacetime sql my-db --server http://127.0.0.1:3101 "SELECT * FROM players" - -# Logs -spacetime logs my-db --server http://127.0.0.1:3101 -f -``` - -## Database Interaction - -```bash -# SQL / describe -spacetime sql my-db --server http://127.0.0.1:3101 "SELECT * FROM users" -spacetime describe my-db --server http://127.0.0.1:3101 --json -spacetime describe my-db table users --server http://127.0.0.1:3101 --json - -# Reducer/procedure calls. Arguments are positional JSON values. -spacetime call --server http://127.0.0.1:3101 my-db my_reducer '"value"' '123' - -# 2.5+ accepts hex strings for Identity arguments without full JSON tuple syntax. -spacetime call --server http://127.0.0.1:3101 my-db reducer_needing_identity 0xabc123... - -# Subscribe from CLI -spacetime subscribe my-db "SELECT * FROM users" --num-updates 10 --server http://127.0.0.1:3101 -``` - -## Standalone MCP Endpoint (2.7) - -SpacetimeDB 2.7 standalone exposes an authenticated JSON-RPC MCP endpoint at -`POST /v1/database/{name_or_identity}/mcp`. It advertises `ping`, `get_schema`, -`sql`, and `call`. The SQL and reducer tools execute with the bearer token's -identity, so keep routine smoke checks read-only. - -```bash -curl -fsS \ - -H "Authorization: Bearer ${SPACETIME_TOKEN}" \ - -H 'Content-Type: application/json' \ - --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"genarrative-smoke","version":"1.0.0"}}}' \ - http://127.0.0.1:3101/v1/database/my-db/mcp - -curl -fsS \ - -H "Authorization: Bearer ${SPACETIME_TOKEN}" \ - -H 'Content-Type: application/json' \ - --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"ping","arguments":{"message":"genarrative"}}}' \ - http://127.0.0.1:3101/v1/database/my-db/mcp -``` - -For repository upgrade validation, also call `tools/list` and the read-only -`get_schema` tool against an isolated local database. Do not use `sql` or `call` -for writes unless that mutation is explicitly in scope. - -## Server & Auth - -```bash -spacetime server list -spacetime server add local --url http://localhost:3000 --default -spacetime server add genarrative-dev --url http://127.0.0.1:3101 -spacetime server ping genarrative-dev - -spacetime login -spacetime login --token -spacetime login show -spacetime logout -``` - -## Version & Runtime Verification - -```bash -# CLI resolution can be misleading; compare all candidates when diagnosing. -type -a spacetime -spacetime --version -spacetime version list - -# Verify a systemd service binary actually changed. -pid="$(systemctl show spacetimedb.service -p MainPID --value)" -readlink -f "/proc/${pid}/exe" -"/proc/${pid}/exe" --version -curl -fsS http://127.0.0.1:3101/v1/ping -``` - -## Flags - -| Flag | Description | -|------|-------------| -| `--server`, `-s` | Target server nickname, host, or URL | -| `--yes`, `-y` | Non-interactive prompt skipping; in 2.6+ use scoped values | -| `--delete-data`, `-c` | Publish data policy: `always`, `on-conflict`, or `never` | -| `--module-path`, `-p` | Module project path | -| `--bin-path`, `-b` | Publish/generate from compiled wasm | -| `--no-config` | Ignore `spacetime.json` | -| `--env` | Select config file layering environment | - -## Troubleshooting - -### Not Logged In - -```bash -spacetime login -``` - -### Server Not Responding - -```bash -spacetime server ping -curl -fsS http://127.0.0.1:3101/v1/ping -``` - -For local Genarrative work, start SpacetimeDB first with `npm run dev:spacetime`, then start `npm run dev:api-server`. - -### Schema Conflict - -```bash -spacetime publish my-db --server http://127.0.0.1:3101 --delete-data=on-conflict --yes=migrate -``` - -Use `--delete-data=always` only with explicit approval. - -### Version Mismatch - -```bash -rg -n 'spacetimedb' server-rs/Cargo.toml -spacetime --version -spacetime version list -pid="$(systemctl show spacetimedb.service -p MainPID --value)" -"/proc/${pid}/exe" --version -``` - -## Notes - -- Procedure calls remain stable in 2.7; module HTTP handlers/webhooks and RLS capabilities still require their documented gates. -- 2.5 fixed `publish --delete-data` config fallback; 2.6 kept that behavior and improved CLI binary distribution; 2.7 adds `spacetime sql --format json` and database `lock` / `unlock`. -- The official 2.7.0 Linux release archives and container image currently use the `v2.7.0-hotfix3` asset tag while binaries report `2.7.0`; keep the asset tag distinct from the runtime version check. -- Do not assume `spacetime version install 2.7.0` selected hotfix3: stale updater metadata can install bare-tag commit `a08663c7...`. For the current release, verify CLI commit `d220349a...` and use the official hotfix3 archive or repository provision flow when it differs. -- Genarrative scripts should pass `--server` or `--server-url` explicitly instead of relying on CLI defaults. diff --git a/.codex/skills/spacetimedb-concepts/SKILL.md b/.codex/skills/spacetimedb-concepts/SKILL.md deleted file mode 100644 index e671603dd..000000000 --- a/.codex/skills/spacetimedb-concepts/SKILL.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -name: spacetimedb-concepts -description: Understand SpacetimeDB 2.7 architecture, reducer/procedure/table/view semantics, schema evolution, subscriptions, identity, and Genarrative-specific backend boundaries. Use when designing or reviewing SpacetimeDB-backed features. ---- - -# SpacetimeDB Core Concepts - -SpacetimeDB is a relational database that also executes application logic in uploaded modules. In Genarrative, it is the data and transaction layer behind `server-rs + Axum + SpacetimeDB`, not a replacement for the `api-server` BFF or external platform adapters. - -## Genarrative Boundaries - -- Domain rules live in `module-*`. -- SpacetimeDB tables, reducers, procedures, migrations, row mappers, and read models live in `spacetime-module`. -- Backend access goes through `spacetime-client` facades. -- HTTP/SSE/BFF and external orchestration stay in `api-server`. -- External side effects stay in `platform-*`. -- Frontend renders backend truth and must not bypass BFF/projections to invent formal business state. - -## Critical Rules - -1. **Reducers are transactional**: they do not return data to callers. Read through subscriptions, read models, views, or BFF endpoints. -2. **Reducers are deterministic**: no filesystem, network, wall-clock, or external RNG. Use `ctx.timestamp`, `ctx.rng()` / `ctx.random()`, and tables. -3. **Procedures are stable in 2.7**: they can use explicit transactions and outgoing HTTP via `ctx.http`. -4. **Identity comes from context**: use `ctx.sender()` or language equivalent for authorization. Never trust identity passed as an argument. -5. **Auto-increment IDs are not ordering guarantees**: gaps are normal. Use timestamps or explicit sequence columns for ordering. -6. **Schema changes need migration discipline**: existing Genarrative table fields must be appended with defaults; update migration code, table catalog, generated bindings, and run `npm run check:spacetime-schema`. - -## Tables - -- Private tables are the default; only reducers/procedures and database owners can access them. -- Public tables are exposed to clients through subscriptions. Writes still go through reducers/procedures. -- Organize data by access pattern when bandwidth or update frequency differs. -- Existing persistent tables in Genarrative are conservative: no rename, delete, reorder, or type changes without a user-approved migration plan. - -## Reducers - -Reducers are deterministic transactional functions. They are the primary client-invoked mutation path. - -- No global mutable state. -- No filesystem, network, timers, or non-deterministic RNG. -- Return `Result<(), String>` for expected sender-visible errors. -- Use `ctx.sender()` for authorization. -- Store persistent state in tables. - -## Procedures - -Procedures are stable in 2.7. They can be scheduled, can open explicit transactions with `with_tx` / `try_with_tx`, and can use outgoing HTTP (`ctx.http`). - -Genarrative default: keep external provider protocols in `platform-*` and orchestration in `api-server` unless a task explicitly moves a workflow into a module procedure. - -Module HTTP handlers/webhooks and RLS `client_visibility_filter` remain subject to their documented gates in 2.7. - -## Views - -Views expose computed read-only data. SpacetimeDB 2.7 supports primary keys on procedural views in Rust, TypeScript, C#, and C++. Clients can receive update events when subscribed to such views with primary keys. Ensure the view never returns duplicate primary keys, because that can fail view refresh and roll back the triggering transaction. - -## Event Tables - -Event tables broadcast reducer/procedure-specific facts to subscribers and must be subscribed explicitly. They are excluded from `subscribe_to_all_tables()`. - -Since 2.6, event tables support broader layout-altering automigrations, including column removal, reordering, and type changes that regular tables reject. This relaxed migration behavior is for event-only tables, not persistent tables. - -Event-table primary keys and constraints are transaction-scoped. They can reject duplicate event rows within one transaction, but event rows are not retained in client cache, so clients observe event tables through insert callbacks only. Do not design Genarrative event tables around `OnUpdate` / `on_update` / `onUpdate`; use a persistent table or a primary-keyed procedural view when update callbacks are required. - -Official 2.4.1 through 2.7 release notes document primary-key-backed update callbacks for procedural views, not event tables. - -## Subscriptions - -1. Subscribe to SQL queries or generated table/query builders. -2. Receive initial matching rows. -3. Receive updates when subscribed rows change. -4. Render from subscribed data, not reducer return values. - -Best practices: - -- Group subscriptions by lifetime. -- Subscribe to new data before unsubscribing old data during transitions. -- Avoid overlapping queries that duplicate row delivery. -- Use indexes for subscribed filters. - -## Standalone MCP - -SpacetimeDB 2.7 standalone exposes `POST /v1/database/{name_or_identity}/mcp` -using MCP JSON-RPC protocol `2025-06-18`. Its tools are `ping`, `get_schema`, -`sql`, and `call`; SQL and reducer calls run with the authenticated caller's -identity. In Genarrative this is an operator/developer integration surface, not -a replacement for `api-server` BFF routes, `spacetime-client` facades, or public -read models. Upgrade smoke should use an isolated local database and restrict -itself to `initialize`, `tools/list`, `ping`, and `get_schema` unless writes are -explicitly intended. - -## 2.2.0 to 2.7.0 Delta - -Genarrative introduced SpacetimeDB around 2.2.0. Important changes since then: - -- **2.2.0**: v3 WebSocket transport and TS SDK default, safer production operations (`lock`/`unlock`, safer `delete`, better `publish --yes`), TS React `useProcedure`, table clearing APIs, empty-table drop automigration, primary-key migration fixes, bytes-key B-tree support, durability hardening. -- **2.3.0**: first-party Godot SDK, more WebSocket pipelining/batching, HTTP/2 backend support, Vue `useProcedure`, Unity 6 WebGL support, commitlog compression/throughput improvements, Rust `DbContext` generics, `ReducerContext::identity` deprecated in favor of `database_identity`, connection lifecycle and unsubscribe fixes. -- **2.4.0**: unstable module HTTP handlers/webhooks, faster synchronous WASM reducer runtime, commitlog resume truncation fix for silent data loss risk, better commitlog decode context, V8 heap metrics for procedure workers, JS execution-time billing regression reverted. -- **2.4.1**: Rust and TypeScript procedural views can declare primary keys, enabling `OnUpdate` events for subscribed views; fixed index schema from ST tables. -- **2.5.0**: procedures are stable, C# procedural views gain primary keys, event tables allow broader layout-altering automigrations, BTreeSet storage makes row insertion deterministic and avoids accidentally quadratic bulk insert behavior, `wasm_memory_bytes` billing metric semantics changed, template version constraints unified, `publish --delete-data` config fallback fixed, CLI `call` accepts hex Identity arguments. -- **2.6.0**: procedural-view primary keys are available across Rust, TypeScript, and C#, commitlog gains `max_segment_size` / `write_buffer_size` / `preallocate_segments`, the default write buffer increases for throughput, event-table automigrations improve, and CLI binary distribution expands. -- **2.6.1**: procedure contexts again receive the caller `Identity` and `ConnectionId`; generated TypeScript `Option` fields use optional keys; `spacetime init --template` lists available templates when no template argument is supplied. -- **2.7.0**: existing tables can add unique or primary-key constraints when current data satisfies them; standalone exposes an authenticated database MCP endpoint; Rust adds context-capability and table-accessor traits; `spacetime sql --format json` and database locking are available; view cleanup, backing-table migration, connection metrics, and memory metrics improve. Official current release assets use the `v2.7.0-hotfix3` tag while binaries report `2.7.0`. - -## Debugging Checklist - -1. Is the Genarrative SpacetimeDB server running? Use `npm run dev:spacetime` locally or host-local `systemctl`. -2. Is the module published to the same server the API uses? -3. Are generated bindings current? Use `npm run spacetime:generate`. -4. Is `api-server` using the same database and token? -5. Is the reducer/procedure actually called? -6. Did `/healthz` / `/readyz` pass while business SpacetimeDB calls still timeout? Inspect API logs and public route behavior. - -## Editing Behavior - -- Make the smallest change necessary. -- Do not invent SpacetimeDB APIs; verify against current docs, generated bindings, or source. -- For Genarrative schema edits, update migration code, table catalog/docs, generated bindings, and relevant tests. -- After schema edits, run `npm run spacetime:generate` and `npm run check:spacetime-schema`. diff --git a/.codex/skills/spacetimedb-rust/SKILL.md b/.codex/skills/spacetimedb-rust/SKILL.md deleted file mode 100644 index ef0a239d6..000000000 --- a/.codex/skills/spacetimedb-rust/SKILL.md +++ /dev/null @@ -1,280 +0,0 @@ ---- -name: spacetimedb-rust -description: Develop SpacetimeDB 2.7 server modules in Rust for Genarrative. Use when writing or reviewing tables, reducers, procedures, views, migrations, row mappers, schema changes, and module logic. ---- - -# SpacetimeDB Rust Module Development - -Use this skill for Rust code in `server-rs/crates/spacetime-module` and related Genarrative schema/migration work. - -## Genarrative Rules - -- Keep domain rules in `module-*`; keep SpacetimeDB tables, reducers, procedures, views, mappers, and transaction adapters in `spacetime-module`. -- Existing table fields must be appended at the end with explicit defaults. Do not rename, remove, reorder, or change field types without a user-confirmed migration plan. -- After schema changes, update `migration.rs`, table catalog/docs, generated bindings, and run `npm run spacetime:generate` plus `npm run check:spacetime-schema`. -- Private tables are backend facts. Expose user-visible state through BFF endpoints/read models rather than direct client SQL. - -## Hallucinated APIs: Do Not Use - -```rust -#[derive(Table)] // Tables use #[table], not derive -#[derive(Reducer)] // Reducers use #[reducer], not derive -#[derive(SpacetimeType)] // Do not derive this on #[table] structs - -pub fn reducer(ctx: &mut ReducerContext) {} // Use &ReducerContext - -ctx.db.player // Use ctx.db.player() -ctx.db.player.find(id) // Use ctx.db.player().id().find(&id) -ctx.sender // Use ctx.sender() -ctx.db.user().name().update(..) // Update by primary key only - -spacetimedb = { version = "...", features = ["unstable"] } // Not needed for procedures since 2.5 -``` - -## Required Patterns - -```rust -use spacetimedb::{reducer, table, Identity, ReducerContext, Table, Timestamp}; -use spacetimedb::SpacetimeType; // Custom types only, not tables - -#[table(accessor = player, public)] -pub struct Player { - #[primary_key] - #[auto_inc] - pub id: u64, - pub owner: Identity, - pub name: String, - pub created_at: Timestamp, -} - -#[reducer] -pub fn create_player(ctx: &ReducerContext, name: String) -> Result<(), String> { - if name.trim().is_empty() { - return Err("name required".to_string()); - } - ctx.db.player().try_insert(Player { - id: 0, - owner: ctx.sender(), - name, - created_at: ctx.timestamp, - })?; - Ok(()) -} -``` - -Hard requirements: - -- Import `Table` for table operations. -- Use `accessor = identifier`, not string literals. -- Use `ctx.sender()` for authorization. -- Use `ctx.rng()` / `ctx.random()` / `ctx.new_uuid_*()` for deterministic randomness and UUIDs. -- Use `Result<(), String>` for expected sender errors; avoid panics except impossible states. -- Use `try_insert()` in `Result` reducers when constraint violations should be reported cleanly. - -## Tables - -```rust -#[spacetimedb::table(accessor = game_tick_schedule, scheduled(game_tick))] -pub struct GameTickSchedule { - #[primary_key] - #[auto_inc] - pub scheduled_id: u64, - pub scheduled_at: ScheduleAt, -} -``` - -Table attributes: - -| Attribute | Description | -|-----------|-------------| -| `accessor = identifier` | API name used in `ctx.db.{accessor}()` | -| `public` | Visible to clients via subscriptions | -| `event` | Transient event table | -| `scheduled(function_name)` | Schedule table that triggers a reducer/procedure | -| `index(accessor = idx, btree(columns = [a, b]))` | Multi-column index | - -Column attributes: - -| Attribute | Description | -|-----------|-------------| -| `#[primary_key]` | One primary key per table | -| `#[auto_inc]` | Auto-generates integer values when inserting `0` | -| `#[unique]` | Unique constraint and `find()` accessor | -| `#[index(btree)]` | B-tree index and `filter()` accessor | -| `#[default(...)]` | Required for new fields on existing Genarrative tables | - -## Genarrative Schema Change Pattern - -```rust -#[spacetimedb::table(accessor = creation_entry_config, public)] -pub struct CreationEntryConfig { - #[primary_key] - pub id: u64, - pub existing_field: String, - - // Append new fields at the end and provide a default. - #[default(false)] - pub new_flag: bool, -} -``` - -Then update `migration.rs`, table catalog/docs, generated bindings, and run: - -```bash -npm run spacetime:generate -npm run check:spacetime-schema -``` - -## Table Operations - -```rust -let row = ctx.db.player().insert(Player { id: 0, owner, name, created_at }); -ctx.db.player().try_insert(row)?; - -let by_id = ctx.db.player().id().find(&123u64); -for player in ctx.db.player().owner().filter(&ctx.sender()) {} -for player in ctx.db.player().level().filter(&(18u32..=65u32)) {} -for player in ctx.db.player().iter() {} -let count = ctx.db.player().count(); - -if let Some(player) = ctx.db.player().id().find(&id) { - ctx.db.player().id().update(Player { name: new_name, ..player }); -} - -ctx.db.player().id().delete(&id); -``` - -For delete/update based on non-PK filters, collect keys first to avoid iterator invalidation. - -## Indexes - -```rust -#[spacetimedb::table( - accessor = score, - public, - index(accessor = by_player_level, btree(columns = [player_id, level])) -)] -pub struct Score { - pub player_id: u32, - pub level: u32, - pub points: i64, -} - -for row in ctx.db.score().by_player_level().filter(&(42,)) {} -for row in ctx.db.score().by_player_level().filter(&(42, 5)) {} -``` - -## Event Tables - -```rust -#[table(accessor = damage_event, public, event)] -pub struct DamageEvent { - pub target: Identity, - pub amount: u32, -} - -#[reducer] -fn deal_damage(ctx: &ReducerContext, target: Identity, amount: u32) { - ctx.db.damage_event().insert(DamageEvent { target, amount }); -} -``` - -Event tables must be subscribed explicitly and are excluded from `subscribe_to_all_tables()`. - -Since 2.6, event tables support broader layout-altering automigrations than regular tables, including column removal, reordering, and type changes. This relaxed migration policy does not apply to persistent tables. - -Event-table primary keys and constraints are enforced only within the current transaction. They do not make event rows persistent, and client SDKs expose event tables as insert-only event streams. Do not rely on `OnUpdate` / `on_update` / `onUpdate` for event tables; use a persistent table or a primary-keyed procedural view when update callbacks are required. - -Official 2.4.1 through 2.7 release notes tie primary-key-backed update callbacks to procedural views, not event tables. - -## Views - -```rust -#[spacetimedb::view(accessor = my_players, public, primary_key = id)] -pub fn my_players(ctx: &spacetimedb::ViewContext) -> Vec { - ctx.db.player().owner().filter(&ctx.sender()).collect() -} -``` - -Rust and TypeScript gained primary key support for procedural views in 2.4.1. With primary keys, clients can receive update events when subscribed to such views. Avoid duplicate primary keys in view results. - -## Lifecycle & Scheduled Reducers - -```rust -#[spacetimedb::reducer(init)] -pub fn init(ctx: &ReducerContext) -> Result<(), String> { Ok(()) } - -#[spacetimedb::reducer(client_connected)] -pub fn on_connect(ctx: &ReducerContext) -> Result<(), String> { Ok(()) } - -#[spacetimedb::reducer(client_disconnected)] -pub fn on_disconnect(ctx: &ReducerContext) -> Result<(), String> { Ok(()) } - -use spacetimedb::{ScheduleAt, TimeDuration}; - -ctx.db.game_tick_schedule().insert(GameTickSchedule { - scheduled_id: 0, - scheduled_at: ScheduleAt::Interval(std::time::Duration::from_millis(100).into()), -}); - -let run_at = ctx.timestamp + std::time::Duration::from_secs(60); -ctx.db.game_tick_schedule().insert(GameTickSchedule { - scheduled_id: 0, - scheduled_at: ScheduleAt::Time(run_at), -}); -``` - -For scheduled reducers, check `ctx.sender_auth().is_internal()` when the reducer should only be system-triggered. - -## Procedures - -Procedures remain stable in 2.7 and no longer require the `unstable` feature. - -```rust -use spacetimedb::{procedure, ProcedureContext}; - -#[procedure] -fn save_external_data(ctx: &mut ProcedureContext, url: String) -> Result<(), String> { - let body = ctx.http.get(url).send()?.text()?; - ctx.try_with_tx(|tx| { - tx.db.external_data().insert(ExternalData { id: 0, content: body }); - Ok(()) - })?; - Ok(()) -} -``` - -| Reducers | Procedures | -|----------|------------| -| `&ReducerContext` | `&mut ProcedureContext` | -| Direct `ctx.db` access | Use `with_tx()` / `try_with_tx()` | -| No HTTP/network | Outgoing HTTP via `ctx.http` | -| Deterministic transaction path | Side-effect-capable workflow path | - -In Genarrative, keep external provider protocols in `platform-*` by default unless the architecture explicitly moves that workflow into the module. - -## Identity & Auth - -```rust -fn require_owner(ctx: &ReducerContext, owner: &Identity) -> Result<(), String> { - if ctx.sender() != *owner { - return Err("Not authorized".to_string()); - } - Ok(()) -} -``` - -`ReducerContext::identity` is deprecated since 2.3; use the current database/module identity API when needed, and use `ctx.sender()` for caller identity. - -## Commands - -```bash -spacetime build -spacetime publish my_database --server http://127.0.0.1:3101 --module-path . --yes=migrate -spacetime publish my_database --server http://127.0.0.1:3101 --delete-data=on-conflict --module-path . --yes=migrate -spacetime logs my_database --server http://127.0.0.1:3101 -spacetime call --server http://127.0.0.1:3101 my_database create_player '"Alice"' -spacetime sql my_database --server http://127.0.0.1:3101 "SELECT * FROM player" -npm run spacetime:generate -npm run check:spacetime-schema -``` diff --git a/AGENTS.md b/AGENTS.md index f7969ee42..c859362fd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,7 +42,7 @@ - 涉及 AI 游戏创作独立 App、多智能体 Runtime、本地项目产物或本地 HTTP 预览时，先读取 [`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`](docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)。 - 新增、补齐、迁移或重构玩法入口、玩法类型、创作工作台、生成页、结果页、发布、运行态、作品架、广场或公开 read model 前，必须读取并按 [`genarrative-play-type-integration`](.codex/skills/genarrative-play-type-integration/SKILL.md) 执行。 - 涉及 `npm run dev` / `npm run dev:spacetime` / `npm run dev:api-server` / `npm run dev:web` / `npm run dev:admin-web` 的端口探测、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理目标或后台 dev 端口时，按 [`.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md`](.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md) 执行。 -- 涉及 SpacetimeDB 的设计、实现、脚本、调试、发布、绑定生成、schema、reducer、procedure、view 或 Rust API 时，必须读取并按 [`spacetimedb-cli`](.codex/skills/spacetimedb-cli/SKILL.md)、[`spacetimedb-rust`](.codex/skills/spacetimedb-rust/SKILL.md)、[`spacetimedb-concepts`](.codex/skills/spacetimedb-concepts/SKILL.md) 中相关 skill 执行。 +- 涉及 SpacetimeDB 的设计、实现、脚本、调试、发布、绑定生成、schema、reducer、procedure、view 或 API 时，必须先读取并按 [`genarrative-spacetimedb`](.codex/skills/genarrative-spacetimedb/SKILL.md) 执行。 ## 后端红线 diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 4ffd04577..44c6c3147 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -2177,13 +2177,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 图片大图预览统一为黑底全屏查看器 @@ -7747,3 +7749,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`；个人配置、缓存和凭据不进入仓库。 diff --git a/docs/project-memory/shared-memory/development-workflow.md b/docs/project-memory/shared-memory/development-workflow.md index 3be0c4b05..21a49bcf0 100644 --- a/docs/project-memory/shared-memory/development-workflow.md +++ b/docs/project-memory/shared-memory/development-workflow.md @@ -35,6 +35,8 @@ ## 验证路由 +SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.md`；该项目适配层按需调用已安装的官方 `spacetimedb` 插件 skill，插件提供通用 SDK/CLI/MCP 知识，项目 skill 负责 Genarrative 架构边界和验证门禁。 + 按改动范围选择定向门禁，不以无关全量扫描代替契约验证： | 范围 | 至少运行 | diff --git a/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md b/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md index d3bd16972..5fa6161e9 100644 --- a/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md +++ b/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md @@ -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 表结构体最后，并设置明确默认值。删除、改名、重排或改类型前必须先询问用户并确认迁移计划。 From 9476ff764875baa3b50c61972db307746279a847 Mon Sep 17 00:00:00 2001 From: kdletters Date: Thu, 27 Aug 2026 13:55:12 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=E8=BF=81=E7=A7=BB=E4=BB=93=E5=BA=93?= =?UTF-8?q?=E5=B7=A5=E5=85=B7=E8=B5=84=E6=BA=90=E5=88=B0=20Codex=20?= =?UTF-8?q?=E5=B9=B6=E5=9B=BA=E5=8C=96=E6=89=A7=E8=A1=8C=E8=BE=B9=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将 .hermes 工具资源迁移至 .codex 同步代码、文档与 RAG 路径引用 补充任务范围、验收与时间盒执行规则 --- .codex/README.md | 16 ++ .../game-studio/.codex-plugin/plugin.json | 0 .../plugins/game-studio/__init__.py | 8 +- .../plugins/game-studio/assets/app-icon.png | Bin .../game-studio/assets/game-studio.svg | 0 .../plugins/game-studio/plugin.yaml | 0 .../references/alternative-3d-engines.md | 0 .../references/engine-selection.md | 0 .../references/frontend-prompts.md | 0 .../references/gltf-loading-starter.md | 0 .../references/phaser-architecture.md | 0 .../references/playtest-checklist.md | 0 .../references/rapier-integration-starter.md | 0 .../references/react-three-fiber-stack.md | 0 .../references/react-three-fiber-starter.md | 0 .../game-studio/references/sprite-pipeline.md | 0 .../references/three-hud-layout-patterns.md | 0 .../references/three-webgl-architecture.md | 0 .../game-studio/references/threejs-stack.md | 0 .../references/threejs-vanilla-starter.md | 0 .../references/web-3d-asset-pipeline.md | 0 .../webgl-debugging-and-performance.md | 0 .../scripts/build_sprite_edit_canvas.py | 0 .../scripts/normalize_sprite_strip.py | 0 .../scripts/render_sprite_preview_sheet.py | 0 .../game-studio/skills/game-playtest/SKILL.md | 0 .../skills/game-playtest/agents/openai.yaml | 0 .../game-studio/skills/game-studio/SKILL.md | 0 .../skills/game-studio/agents/openai.yaml | 0 .../skills/game-ui-frontend/SKILL.md | 0 .../game-ui-frontend/agents/openai.yaml | 0 .../skills/phaser-2d-game/SKILL.md | 0 .../skills/phaser-2d-game/agents/openai.yaml | 0 .../skills/react-three-fiber-game/SKILL.md | 0 .../react-three-fiber-game/agents/openai.yaml | 0 .../skills/sprite-pipeline/SKILL.md | 0 .../skills/sprite-pipeline/agents/openai.yaml | 0 .../skills/three-webgl-game/SKILL.md | 0 .../three-webgl-game/agents/openai.yaml | 0 .../skills/web-3d-asset-pipeline/SKILL.md | 0 .../web-3d-asset-pipeline/agents/openai.yaml | 0 .../skills/web-game-foundations/SKILL.md | 0 .../web-game-foundations/agents/openai.yaml | 0 .codex/skills/README.md | 7 + .../behavior-driven-development/SKILL.md | 10 +- .../genarrative-admin-backoffice/SKILL.md | 7 +- .../admin-database-table-query-2026-05-08.md | 0 ...admin-tracking-events-export-2026-05-07.md | 0 .../references/daily-login-auth-closure.md | 0 .../daily-login-tracking-trigger-points.md | 0 .../dev-rust-stack-startup-2026-05-08.md | 0 .../private-table-sql-token-refresh.md | 0 .../spacetimedb-http-sql-sats-display.md | 0 .../genarrative-auth-session-flow/SKILL.md | 4 +- ...restore-daily-login-tracking-2026-05-08.md | 0 .../SKILL.md | 5 +- .../SKILL.md | 7 +- .../genarrative-analytics-tracking-runtime.md | 0 .../genarrative-profile-features/SKILL.md | 4 +- .../profile-feedback-entry-2026-05-08.md | 0 .../genarrative-profile-invite-flow/SKILL.md | 4 +- .../query-invite-code-flow-2026-05-07.md | 0 .hermes/README.md | 66 ----- .hermes/skills/README.md | 27 -- .../SKILL.md | 253 ------------------ AGENTS.md | 9 +- .../src-tauri/src/agent/direct_tool_bridge.rs | 3 +- .../src-tauri/src/agent/direct_tools_mcp.rs | 8 +- .../src/agent/generation/prompt_context.rs | 6 +- .../src/agent/runtime_tools/context.rs | 8 +- .../src-tauri/src/command_exec.rs | 7 +- .../src-tauri/src/command_sandbox.rs | 13 +- .../src-tauri/src/commands.rs | 3 +- .../src/components/AssetImporter/utils.ts | 1 - docs/project-memory/README.md | 2 +- .../shared-memory/decision-log.md | 18 +- .../shared-memory/development-workflow.md | 4 +- .../shared-memory/handoff-template.md | 2 +- docs/project-memory/shared-memory/pitfalls.md | 22 +- .../shared-memory/team-conventions.md | 2 +- ...案】AI游戏创作Agent Runtime V1.1-2026-07-12.md | 6 +- ...案】AI游戏创作智能体App实施计划-2026-06-24.md | 6 +- ...规范】Agent工作入口与执行准则-2026-06-22.md | 6 +- ...发运维】本地开发验证与生产运维-2026-05-15.md | 2 +- ...项目基线】当前产品与工程约束-2026-05-15.md | 2 +- scripts/rag/README.md | 2 +- scripts/rag/rag-config.json | 2 +- 87 files changed, 107 insertions(+), 445 deletions(-) create mode 100644 .codex/README.md rename {.hermes => .codex}/plugins/game-studio/.codex-plugin/plugin.json (100%) rename {.hermes => .codex}/plugins/game-studio/__init__.py (76%) rename {.hermes => .codex}/plugins/game-studio/assets/app-icon.png (100%) rename {.hermes => .codex}/plugins/game-studio/assets/game-studio.svg (100%) rename {.hermes => .codex}/plugins/game-studio/plugin.yaml (100%) rename {.hermes => .codex}/plugins/game-studio/references/alternative-3d-engines.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/engine-selection.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/frontend-prompts.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/gltf-loading-starter.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/phaser-architecture.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/playtest-checklist.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/rapier-integration-starter.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/react-three-fiber-stack.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/react-three-fiber-starter.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/sprite-pipeline.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/three-hud-layout-patterns.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/three-webgl-architecture.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/threejs-stack.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/threejs-vanilla-starter.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/web-3d-asset-pipeline.md (100%) rename {.hermes => .codex}/plugins/game-studio/references/webgl-debugging-and-performance.md (100%) rename {.hermes => .codex}/plugins/game-studio/scripts/build_sprite_edit_canvas.py (100%) rename {.hermes => .codex}/plugins/game-studio/scripts/normalize_sprite_strip.py (100%) rename {.hermes => .codex}/plugins/game-studio/scripts/render_sprite_preview_sheet.py (100%) rename {.hermes => .codex}/plugins/game-studio/skills/game-playtest/SKILL.md (100%) rename {.hermes => .codex}/plugins/game-studio/skills/game-playtest/agents/openai.yaml (100%) rename {.hermes => .codex}/plugins/game-studio/skills/game-studio/SKILL.md (100%) rename {.hermes => .codex}/plugins/game-studio/skills/game-studio/agents/openai.yaml (100%) rename {.hermes => .codex}/plugins/game-studio/skills/game-ui-frontend/SKILL.md (100%) rename {.hermes => .codex}/plugins/game-studio/skills/game-ui-frontend/agents/openai.yaml (100%) rename {.hermes => .codex}/plugins/game-studio/skills/phaser-2d-game/SKILL.md (100%) rename {.hermes => .codex}/plugins/game-studio/skills/phaser-2d-game/agents/openai.yaml (100%) rename {.hermes => .codex}/plugins/game-studio/skills/react-three-fiber-game/SKILL.md (100%) rename {.hermes => .codex}/plugins/game-studio/skills/react-three-fiber-game/agents/openai.yaml (100%) rename {.hermes => .codex}/plugins/game-studio/skills/sprite-pipeline/SKILL.md (100%) rename {.hermes => .codex}/plugins/game-studio/skills/sprite-pipeline/agents/openai.yaml (100%) rename {.hermes => .codex}/plugins/game-studio/skills/three-webgl-game/SKILL.md (100%) rename {.hermes => .codex}/plugins/game-studio/skills/three-webgl-game/agents/openai.yaml (100%) rename {.hermes => .codex}/plugins/game-studio/skills/web-3d-asset-pipeline/SKILL.md (100%) rename {.hermes => .codex}/plugins/game-studio/skills/web-3d-asset-pipeline/agents/openai.yaml (100%) rename {.hermes => .codex}/plugins/game-studio/skills/web-game-foundations/SKILL.md (100%) rename {.hermes => .codex}/plugins/game-studio/skills/web-game-foundations/agents/openai.yaml (100%) create mode 100644 .codex/skills/README.md rename {.hermes => .codex}/skills/behavior-driven-development/SKILL.md (97%) rename {.hermes => .codex}/skills/genarrative-admin-backoffice/SKILL.md (97%) rename {.hermes => .codex}/skills/genarrative-admin-backoffice/references/admin-database-table-query-2026-05-08.md (100%) rename {.hermes => .codex}/skills/genarrative-admin-backoffice/references/admin-tracking-events-export-2026-05-07.md (100%) rename {.hermes => .codex}/skills/genarrative-admin-backoffice/references/daily-login-auth-closure.md (100%) rename {.hermes => .codex}/skills/genarrative-admin-backoffice/references/daily-login-tracking-trigger-points.md (100%) rename {.hermes => .codex}/skills/genarrative-admin-backoffice/references/dev-rust-stack-startup-2026-05-08.md (100%) rename {.hermes => .codex}/skills/genarrative-admin-backoffice/references/private-table-sql-token-refresh.md (100%) rename {.hermes => .codex}/skills/genarrative-admin-backoffice/references/spacetimedb-http-sql-sats-display.md (100%) rename {.hermes => .codex}/skills/genarrative-auth-session-flow/SKILL.md (99%) rename {.hermes => .codex}/skills/genarrative-auth-session-flow/references/session-restore-daily-login-tracking-2026-05-08.md (100%) rename {.hermes => .codex}/skills/genarrative-dev-stack-port-routing/SKILL.md (98%) rename {.hermes => .codex}/skills/genarrative-play-type-integration/references/genarrative-analytics-tracking-runtime.md (100%) rename {.hermes => .codex}/skills/genarrative-profile-features/SKILL.md (99%) rename {.hermes => .codex}/skills/genarrative-profile-features/references/profile-feedback-entry-2026-05-08.md (100%) rename {.hermes => .codex}/skills/genarrative-profile-invite-flow/SKILL.md (99%) rename {.hermes => .codex}/skills/genarrative-profile-invite-flow/references/query-invite-code-flow-2026-05-07.md (100%) delete mode 100644 .hermes/README.md delete mode 100644 .hermes/skills/README.md delete mode 100644 .hermes/skills/genarrative-play-type-integration/SKILL.md diff --git a/.codex/README.md b/.codex/README.md new file mode 100644 index 000000000..4ea0ba9a9 --- /dev/null +++ b/.codex/README.md @@ -0,0 +1,16 @@ +# Genarrative Codex 项目工具 + +`.codex/` 是仓库级 Codex 工具目录，保存项目共享的 skills、插件资源、hooks 和相关配置模板。它只描述如何协作和加载工具，不承载项目业务知识。 + +## 目录约定 + +- `.codex/skills/` 是项目专属 skill 根目录。每个 skill 以目录中的 `SKILL.md` 为入口，配套的参考资料和脚本放在同一目录下。 +- `.codex/plugins/` 保存随仓库分发的项目插件资源及其参考资料。当前的 `game-studio` 插件提供浏览器游戏设计、原型、2D/3D 技术栈、素材管线和 playtest 工作流；是否启用遵循当前 Codex 的插件加载机制，不依赖旧工具的环境变量或个人配置脚本。 +- `.codex/hooks/`、`.codex/environments/` 等目录保存项目工具链所需的 hooks 和环境模板；它们不替代项目代码中的运行时配置。 +- 长期有效的产品、架构、接口、排障和协作知识统一放在 `docs/` 与 `docs/project-memory/`，不复制到本目录。 + +## 使用边界 + +进入仓库后先读根目录 `AGENTS.md`，再按任务路由读取对应 skill。SpacetimeDB 的通用概念、Rust 服务端、CLI、TypeScript 客户端和 MCP 用法由已安装的官方插件提供；项目约束和入口由 `.codex/skills/genarrative-spacetimedb/SKILL.md` 统一编排。 + +个人 `~/.codex` 配置、凭据、会话、环境变量和本地路径不得复制到仓库。若本目录内容与当前代码或最新 `docs/` 冲突，以代码和最新文档为准，并修正过期工具说明。 diff --git a/.hermes/plugins/game-studio/.codex-plugin/plugin.json b/.codex/plugins/game-studio/.codex-plugin/plugin.json similarity index 100% rename from .hermes/plugins/game-studio/.codex-plugin/plugin.json rename to .codex/plugins/game-studio/.codex-plugin/plugin.json diff --git a/.hermes/plugins/game-studio/__init__.py b/.codex/plugins/game-studio/__init__.py similarity index 76% rename from .hermes/plugins/game-studio/__init__.py rename to .codex/plugins/game-studio/__init__.py index bcf37e070..b7ea43159 100644 --- a/.hermes/plugins/game-studio/__init__.py +++ b/.codex/plugins/game-studio/__init__.py @@ -1,8 +1,8 @@ -"""Hermes wrapper for the OpenAI Codex Game Studio plugin. +"""Metadata bridge for the bundled Codex Game Studio project plugin. -This plugin was imported from a Codex curated plugin cache. It exposes the -plugin's bundled SKILL.md files as Hermes plugin skills using qualified names -like `game-studio:phaser-2d-game`. +The manifest and bundled ``SKILL.md`` files are the source of truth. This +module only exposes their descriptions to a compatible plugin host and keeps +the project resource bundle free of runtime-specific behavior. """ from __future__ import annotations diff --git a/.hermes/plugins/game-studio/assets/app-icon.png b/.codex/plugins/game-studio/assets/app-icon.png similarity index 100% rename from .hermes/plugins/game-studio/assets/app-icon.png rename to .codex/plugins/game-studio/assets/app-icon.png diff --git a/.hermes/plugins/game-studio/assets/game-studio.svg b/.codex/plugins/game-studio/assets/game-studio.svg similarity index 100% rename from .hermes/plugins/game-studio/assets/game-studio.svg rename to .codex/plugins/game-studio/assets/game-studio.svg diff --git a/.hermes/plugins/game-studio/plugin.yaml b/.codex/plugins/game-studio/plugin.yaml similarity index 100% rename from .hermes/plugins/game-studio/plugin.yaml rename to .codex/plugins/game-studio/plugin.yaml diff --git a/.hermes/plugins/game-studio/references/alternative-3d-engines.md b/.codex/plugins/game-studio/references/alternative-3d-engines.md similarity index 100% rename from .hermes/plugins/game-studio/references/alternative-3d-engines.md rename to .codex/plugins/game-studio/references/alternative-3d-engines.md diff --git a/.hermes/plugins/game-studio/references/engine-selection.md b/.codex/plugins/game-studio/references/engine-selection.md similarity index 100% rename from .hermes/plugins/game-studio/references/engine-selection.md rename to .codex/plugins/game-studio/references/engine-selection.md diff --git a/.hermes/plugins/game-studio/references/frontend-prompts.md b/.codex/plugins/game-studio/references/frontend-prompts.md similarity index 100% rename from .hermes/plugins/game-studio/references/frontend-prompts.md rename to .codex/plugins/game-studio/references/frontend-prompts.md diff --git a/.hermes/plugins/game-studio/references/gltf-loading-starter.md b/.codex/plugins/game-studio/references/gltf-loading-starter.md similarity index 100% rename from .hermes/plugins/game-studio/references/gltf-loading-starter.md rename to .codex/plugins/game-studio/references/gltf-loading-starter.md diff --git a/.hermes/plugins/game-studio/references/phaser-architecture.md b/.codex/plugins/game-studio/references/phaser-architecture.md similarity index 100% rename from .hermes/plugins/game-studio/references/phaser-architecture.md rename to .codex/plugins/game-studio/references/phaser-architecture.md diff --git a/.hermes/plugins/game-studio/references/playtest-checklist.md b/.codex/plugins/game-studio/references/playtest-checklist.md similarity index 100% rename from .hermes/plugins/game-studio/references/playtest-checklist.md rename to .codex/plugins/game-studio/references/playtest-checklist.md diff --git a/.hermes/plugins/game-studio/references/rapier-integration-starter.md b/.codex/plugins/game-studio/references/rapier-integration-starter.md similarity index 100% rename from .hermes/plugins/game-studio/references/rapier-integration-starter.md rename to .codex/plugins/game-studio/references/rapier-integration-starter.md diff --git a/.hermes/plugins/game-studio/references/react-three-fiber-stack.md b/.codex/plugins/game-studio/references/react-three-fiber-stack.md similarity index 100% rename from .hermes/plugins/game-studio/references/react-three-fiber-stack.md rename to .codex/plugins/game-studio/references/react-three-fiber-stack.md diff --git a/.hermes/plugins/game-studio/references/react-three-fiber-starter.md b/.codex/plugins/game-studio/references/react-three-fiber-starter.md similarity index 100% rename from .hermes/plugins/game-studio/references/react-three-fiber-starter.md rename to .codex/plugins/game-studio/references/react-three-fiber-starter.md diff --git a/.hermes/plugins/game-studio/references/sprite-pipeline.md b/.codex/plugins/game-studio/references/sprite-pipeline.md similarity index 100% rename from .hermes/plugins/game-studio/references/sprite-pipeline.md rename to .codex/plugins/game-studio/references/sprite-pipeline.md diff --git a/.hermes/plugins/game-studio/references/three-hud-layout-patterns.md b/.codex/plugins/game-studio/references/three-hud-layout-patterns.md similarity index 100% rename from .hermes/plugins/game-studio/references/three-hud-layout-patterns.md rename to .codex/plugins/game-studio/references/three-hud-layout-patterns.md diff --git a/.hermes/plugins/game-studio/references/three-webgl-architecture.md b/.codex/plugins/game-studio/references/three-webgl-architecture.md similarity index 100% rename from .hermes/plugins/game-studio/references/three-webgl-architecture.md rename to .codex/plugins/game-studio/references/three-webgl-architecture.md diff --git a/.hermes/plugins/game-studio/references/threejs-stack.md b/.codex/plugins/game-studio/references/threejs-stack.md similarity index 100% rename from .hermes/plugins/game-studio/references/threejs-stack.md rename to .codex/plugins/game-studio/references/threejs-stack.md diff --git a/.hermes/plugins/game-studio/references/threejs-vanilla-starter.md b/.codex/plugins/game-studio/references/threejs-vanilla-starter.md similarity index 100% rename from .hermes/plugins/game-studio/references/threejs-vanilla-starter.md rename to .codex/plugins/game-studio/references/threejs-vanilla-starter.md diff --git a/.hermes/plugins/game-studio/references/web-3d-asset-pipeline.md b/.codex/plugins/game-studio/references/web-3d-asset-pipeline.md similarity index 100% rename from .hermes/plugins/game-studio/references/web-3d-asset-pipeline.md rename to .codex/plugins/game-studio/references/web-3d-asset-pipeline.md diff --git a/.hermes/plugins/game-studio/references/webgl-debugging-and-performance.md b/.codex/plugins/game-studio/references/webgl-debugging-and-performance.md similarity index 100% rename from .hermes/plugins/game-studio/references/webgl-debugging-and-performance.md rename to .codex/plugins/game-studio/references/webgl-debugging-and-performance.md diff --git a/.hermes/plugins/game-studio/scripts/build_sprite_edit_canvas.py b/.codex/plugins/game-studio/scripts/build_sprite_edit_canvas.py similarity index 100% rename from .hermes/plugins/game-studio/scripts/build_sprite_edit_canvas.py rename to .codex/plugins/game-studio/scripts/build_sprite_edit_canvas.py diff --git a/.hermes/plugins/game-studio/scripts/normalize_sprite_strip.py b/.codex/plugins/game-studio/scripts/normalize_sprite_strip.py similarity index 100% rename from .hermes/plugins/game-studio/scripts/normalize_sprite_strip.py rename to .codex/plugins/game-studio/scripts/normalize_sprite_strip.py diff --git a/.hermes/plugins/game-studio/scripts/render_sprite_preview_sheet.py b/.codex/plugins/game-studio/scripts/render_sprite_preview_sheet.py similarity index 100% rename from .hermes/plugins/game-studio/scripts/render_sprite_preview_sheet.py rename to .codex/plugins/game-studio/scripts/render_sprite_preview_sheet.py diff --git a/.hermes/plugins/game-studio/skills/game-playtest/SKILL.md b/.codex/plugins/game-studio/skills/game-playtest/SKILL.md similarity index 100% rename from .hermes/plugins/game-studio/skills/game-playtest/SKILL.md rename to .codex/plugins/game-studio/skills/game-playtest/SKILL.md diff --git a/.hermes/plugins/game-studio/skills/game-playtest/agents/openai.yaml b/.codex/plugins/game-studio/skills/game-playtest/agents/openai.yaml similarity index 100% rename from .hermes/plugins/game-studio/skills/game-playtest/agents/openai.yaml rename to .codex/plugins/game-studio/skills/game-playtest/agents/openai.yaml diff --git a/.hermes/plugins/game-studio/skills/game-studio/SKILL.md b/.codex/plugins/game-studio/skills/game-studio/SKILL.md similarity index 100% rename from .hermes/plugins/game-studio/skills/game-studio/SKILL.md rename to .codex/plugins/game-studio/skills/game-studio/SKILL.md diff --git a/.hermes/plugins/game-studio/skills/game-studio/agents/openai.yaml b/.codex/plugins/game-studio/skills/game-studio/agents/openai.yaml similarity index 100% rename from .hermes/plugins/game-studio/skills/game-studio/agents/openai.yaml rename to .codex/plugins/game-studio/skills/game-studio/agents/openai.yaml diff --git a/.hermes/plugins/game-studio/skills/game-ui-frontend/SKILL.md b/.codex/plugins/game-studio/skills/game-ui-frontend/SKILL.md similarity index 100% rename from .hermes/plugins/game-studio/skills/game-ui-frontend/SKILL.md rename to .codex/plugins/game-studio/skills/game-ui-frontend/SKILL.md diff --git a/.hermes/plugins/game-studio/skills/game-ui-frontend/agents/openai.yaml b/.codex/plugins/game-studio/skills/game-ui-frontend/agents/openai.yaml similarity index 100% rename from .hermes/plugins/game-studio/skills/game-ui-frontend/agents/openai.yaml rename to .codex/plugins/game-studio/skills/game-ui-frontend/agents/openai.yaml diff --git a/.hermes/plugins/game-studio/skills/phaser-2d-game/SKILL.md b/.codex/plugins/game-studio/skills/phaser-2d-game/SKILL.md similarity index 100% rename from .hermes/plugins/game-studio/skills/phaser-2d-game/SKILL.md rename to .codex/plugins/game-studio/skills/phaser-2d-game/SKILL.md diff --git a/.hermes/plugins/game-studio/skills/phaser-2d-game/agents/openai.yaml b/.codex/plugins/game-studio/skills/phaser-2d-game/agents/openai.yaml similarity index 100% rename from .hermes/plugins/game-studio/skills/phaser-2d-game/agents/openai.yaml rename to .codex/plugins/game-studio/skills/phaser-2d-game/agents/openai.yaml diff --git a/.hermes/plugins/game-studio/skills/react-three-fiber-game/SKILL.md b/.codex/plugins/game-studio/skills/react-three-fiber-game/SKILL.md similarity index 100% rename from .hermes/plugins/game-studio/skills/react-three-fiber-game/SKILL.md rename to .codex/plugins/game-studio/skills/react-three-fiber-game/SKILL.md diff --git a/.hermes/plugins/game-studio/skills/react-three-fiber-game/agents/openai.yaml b/.codex/plugins/game-studio/skills/react-three-fiber-game/agents/openai.yaml similarity index 100% rename from .hermes/plugins/game-studio/skills/react-three-fiber-game/agents/openai.yaml rename to .codex/plugins/game-studio/skills/react-three-fiber-game/agents/openai.yaml diff --git a/.hermes/plugins/game-studio/skills/sprite-pipeline/SKILL.md b/.codex/plugins/game-studio/skills/sprite-pipeline/SKILL.md similarity index 100% rename from .hermes/plugins/game-studio/skills/sprite-pipeline/SKILL.md rename to .codex/plugins/game-studio/skills/sprite-pipeline/SKILL.md diff --git a/.hermes/plugins/game-studio/skills/sprite-pipeline/agents/openai.yaml b/.codex/plugins/game-studio/skills/sprite-pipeline/agents/openai.yaml similarity index 100% rename from .hermes/plugins/game-studio/skills/sprite-pipeline/agents/openai.yaml rename to .codex/plugins/game-studio/skills/sprite-pipeline/agents/openai.yaml diff --git a/.hermes/plugins/game-studio/skills/three-webgl-game/SKILL.md b/.codex/plugins/game-studio/skills/three-webgl-game/SKILL.md similarity index 100% rename from .hermes/plugins/game-studio/skills/three-webgl-game/SKILL.md rename to .codex/plugins/game-studio/skills/three-webgl-game/SKILL.md diff --git a/.hermes/plugins/game-studio/skills/three-webgl-game/agents/openai.yaml b/.codex/plugins/game-studio/skills/three-webgl-game/agents/openai.yaml similarity index 100% rename from .hermes/plugins/game-studio/skills/three-webgl-game/agents/openai.yaml rename to .codex/plugins/game-studio/skills/three-webgl-game/agents/openai.yaml diff --git a/.hermes/plugins/game-studio/skills/web-3d-asset-pipeline/SKILL.md b/.codex/plugins/game-studio/skills/web-3d-asset-pipeline/SKILL.md similarity index 100% rename from .hermes/plugins/game-studio/skills/web-3d-asset-pipeline/SKILL.md rename to .codex/plugins/game-studio/skills/web-3d-asset-pipeline/SKILL.md diff --git a/.hermes/plugins/game-studio/skills/web-3d-asset-pipeline/agents/openai.yaml b/.codex/plugins/game-studio/skills/web-3d-asset-pipeline/agents/openai.yaml similarity index 100% rename from .hermes/plugins/game-studio/skills/web-3d-asset-pipeline/agents/openai.yaml rename to .codex/plugins/game-studio/skills/web-3d-asset-pipeline/agents/openai.yaml diff --git a/.hermes/plugins/game-studio/skills/web-game-foundations/SKILL.md b/.codex/plugins/game-studio/skills/web-game-foundations/SKILL.md similarity index 100% rename from .hermes/plugins/game-studio/skills/web-game-foundations/SKILL.md rename to .codex/plugins/game-studio/skills/web-game-foundations/SKILL.md diff --git a/.hermes/plugins/game-studio/skills/web-game-foundations/agents/openai.yaml b/.codex/plugins/game-studio/skills/web-game-foundations/agents/openai.yaml similarity index 100% rename from .hermes/plugins/game-studio/skills/web-game-foundations/agents/openai.yaml rename to .codex/plugins/game-studio/skills/web-game-foundations/agents/openai.yaml diff --git a/.codex/skills/README.md b/.codex/skills/README.md new file mode 100644 index 000000000..407ed1cd6 --- /dev/null +++ b/.codex/skills/README.md @@ -0,0 +1,7 @@ +# Genarrative 项目 skills + +`.codex/skills/` 是仓库级、可通过 Git 共享的项目专属 skill 根目录。每个目录的 `SKILL.md` 是唯一入口；较长的参考资料、示例和脚本放在该 skill 的 `references/`、`assets/` 或 `scripts/` 下。 + +项目 skill 负责把当前仓库的目录、契约、验证门禁和历史约束串起来，不重复维护通用框架知识。涉及 SpacetimeDB 时，先读 `genarrative-spacetimedb/SKILL.md`，由它路由到已安装的官方 SpacetimeDB 插件 skills。 + +长期项目知识放在 `docs/` 与 `docs/project-memory/`；不要把个人配置、密钥、会话、缓存或临时计划写入本目录。发现 skill 与代码或最新文档不一致时，按当前实现更新 skill，并同步必要的项目文档。 diff --git a/.hermes/skills/behavior-driven-development/SKILL.md b/.codex/skills/behavior-driven-development/SKILL.md similarity index 97% rename from .hermes/skills/behavior-driven-development/SKILL.md rename to .codex/skills/behavior-driven-development/SKILL.md index 5b3e4e674..f2e94eb80 100644 --- a/.hermes/skills/behavior-driven-development/SKILL.md +++ b/.codex/skills/behavior-driven-development/SKILL.md @@ -1,11 +1,9 @@ --- name: behavior-driven-development description: 在 Genarrative 中需要用 BDD/行为驱动方式把 PRD、用户故事、验收标准转成可执行场景、Gherkin 用例、测试计划或 TDD 落地顺序时使用。 -version: 1.0.0 -author: Hermes Agent license: MIT metadata: - hermes: + codex: tags: [BDD, Gherkin, 验收标准, 用户故事, 测试, Genarrative] related_skills: [writing-plans, test-driven-development, systematic-debugging, requesting-code-review] --- @@ -280,11 +278,11 @@ fn anonymous_user_cannot_publish_generated_draft() { | 产物类型 | 推荐路径 | 适用场景 | | --- | --- | --- | -| 实施前分析 / 临时计划 | 当前任务说明或 `.tmp/-bdd-scenarios.md` | 某次 Hermes 开发任务前，用于澄清行为、拆测试、辅助实现；不作为长期产品依据。 | +| 实施前分析 / 临时计划 | 当前任务说明或 `.tmp/-bdd-scenarios.md` | 某次 Codex 开发任务前，用于澄清行为、拆测试、辅助实现；不作为长期产品依据。 | | 正式产品验收 / PRD 场景 | 当前 `docs/` 融合文档，必要时新增 `docs/【产品验收】<功能名>BDD场景-YYYY-MM-DD.md` | 产品、测试、开发都需要长期参考的验收标准、用户故事、功能边界。 | | 技术/API/领域行为场景 | 当前 `docs/` 融合文档，必要时新增 `docs/【技术验收】<功能名>BDD场景-YYYY-MM-DD.md` | 后端 API、领域规则、状态机、SpacetimeDB reducer/table、SSE/异步任务、埋点副作用。 | | 自动化 Gherkin feature 文件 | `tests/features/*.feature` 或 `e2e/features/*.feature` | 项目已接入 Cucumber/Playwright BDD 等 Gherkin runner 时。未接入前不要随意新建测试 runner 目录。 | -| 稳定流程或团队经验 | `docs/project-memory/shared-memory/` 或 `.hermes/skills/` | 不是某个功能验收，而是长期可复用的团队流程、坑点、执行规范。 | +| 稳定流程或团队经验 | `docs/project-memory/shared-memory/` 或 `.codex/skills/` | 不是某个功能验收，而是长期可复用的团队流程、坑点、执行规范。 | 默认规则： @@ -311,7 +309,7 @@ e2e/features/invite-code.feature - 实施计划：当前任务上下文或 `.tmp/.md` - 产品/验收文档：当前 `docs/` 融合文档，必要时新增 `docs/【产品验收】中文标题-YYYY-MM-DD.md` - 技术设计：当前 `docs/` 融合文档，必要时新增 `docs/【技术方案】中文标题-YYYY-MM-DD.md` -- 共享经验或稳定流程：`docs/project-memory/shared-memory/` 或 `.hermes/skills/` +- 共享经验或稳定流程：`docs/project-memory/shared-memory/` 或 `.codex/skills/` BDD 文档建议包含： diff --git a/.hermes/skills/genarrative-admin-backoffice/SKILL.md b/.codex/skills/genarrative-admin-backoffice/SKILL.md similarity index 97% rename from .hermes/skills/genarrative-admin-backoffice/SKILL.md rename to .codex/skills/genarrative-admin-backoffice/SKILL.md index 24adcbf38..5c826f743 100644 --- a/.hermes/skills/genarrative-admin-backoffice/SKILL.md +++ b/.codex/skills/genarrative-admin-backoffice/SKILL.md @@ -1,12 +1,9 @@ --- name: genarrative-admin-backoffice -short_description: 在 Genarrative/陶泥儿后台新增或修改管理页、后台只读/写接口、导出能力时使用。 description: 在 Genarrative/陶泥儿后台新增或修改管理页、后台 BFF 接口、shared-contracts/admin DTO、admin-web 路由导航、Excel/表格导出与验证发布时使用。 -version: 1.0.0 -author: Hermes Agent license: MIT metadata: - hermes: + codex: tags: [Genarrative, 陶泥儿后台, admin-web, 后台接口, Excel导出, Rust, Axum, SpacetimeDB] related_skills: [genarrative-play-type-integration] --- @@ -168,7 +165,7 @@ npm run dev - 本地和人工排障不再使用 `spacetime --root-dir`。如果看到 `bin/current/spacetimedb-cli` 缺失类错误，优先确认是否仍在运行旧脚本或旧发布包；本地开发应使用 `npm run dev` / `npm run dev:spacetime`，通过项目脚本和 `--data-dir` 隔离 SpacetimeDB 数据目录，不再把用户级 SpacetimeDB 安装同步到项目目录。 - `scripts/dev.mjs` 默认 `api timeout: 600s`. 合并 master 后首次 Rust 依赖/工作区重编译可能超过默认等待窗口，导致完整 `npm run dev` 在 api-server 就绪前超时并回收 SpacetimeDB。先让 Rust 编译完成，或临时用 `npm run dev:api-server -- --api-timeout-seconds 900` 预热 api-server 编译；之后再重新跑完整 `npm run dev`。 -- 用户贴出的 Hermes background watch 通知可能来自已退出的旧 session。先用 `process poll` 查该 session 状态，再判断是否需要处理；不要把旧失败误判成当前服务失败。 +- 用户贴出的 Codex background watch 通知可能来自已退出的旧 session。先用 `process poll` 查该 session 状态，再判断是否需要处理；不要把旧失败误判成当前服务失败。 ## 测试与验证 diff --git a/.hermes/skills/genarrative-admin-backoffice/references/admin-database-table-query-2026-05-08.md b/.codex/skills/genarrative-admin-backoffice/references/admin-database-table-query-2026-05-08.md similarity index 100% rename from .hermes/skills/genarrative-admin-backoffice/references/admin-database-table-query-2026-05-08.md rename to .codex/skills/genarrative-admin-backoffice/references/admin-database-table-query-2026-05-08.md diff --git a/.hermes/skills/genarrative-admin-backoffice/references/admin-tracking-events-export-2026-05-07.md b/.codex/skills/genarrative-admin-backoffice/references/admin-tracking-events-export-2026-05-07.md similarity index 100% rename from .hermes/skills/genarrative-admin-backoffice/references/admin-tracking-events-export-2026-05-07.md rename to .codex/skills/genarrative-admin-backoffice/references/admin-tracking-events-export-2026-05-07.md diff --git a/.hermes/skills/genarrative-admin-backoffice/references/daily-login-auth-closure.md b/.codex/skills/genarrative-admin-backoffice/references/daily-login-auth-closure.md similarity index 100% rename from .hermes/skills/genarrative-admin-backoffice/references/daily-login-auth-closure.md rename to .codex/skills/genarrative-admin-backoffice/references/daily-login-auth-closure.md diff --git a/.hermes/skills/genarrative-admin-backoffice/references/daily-login-tracking-trigger-points.md b/.codex/skills/genarrative-admin-backoffice/references/daily-login-tracking-trigger-points.md similarity index 100% rename from .hermes/skills/genarrative-admin-backoffice/references/daily-login-tracking-trigger-points.md rename to .codex/skills/genarrative-admin-backoffice/references/daily-login-tracking-trigger-points.md diff --git a/.hermes/skills/genarrative-admin-backoffice/references/dev-rust-stack-startup-2026-05-08.md b/.codex/skills/genarrative-admin-backoffice/references/dev-rust-stack-startup-2026-05-08.md similarity index 100% rename from .hermes/skills/genarrative-admin-backoffice/references/dev-rust-stack-startup-2026-05-08.md rename to .codex/skills/genarrative-admin-backoffice/references/dev-rust-stack-startup-2026-05-08.md diff --git a/.hermes/skills/genarrative-admin-backoffice/references/private-table-sql-token-refresh.md b/.codex/skills/genarrative-admin-backoffice/references/private-table-sql-token-refresh.md similarity index 100% rename from .hermes/skills/genarrative-admin-backoffice/references/private-table-sql-token-refresh.md rename to .codex/skills/genarrative-admin-backoffice/references/private-table-sql-token-refresh.md diff --git a/.hermes/skills/genarrative-admin-backoffice/references/spacetimedb-http-sql-sats-display.md b/.codex/skills/genarrative-admin-backoffice/references/spacetimedb-http-sql-sats-display.md similarity index 100% rename from .hermes/skills/genarrative-admin-backoffice/references/spacetimedb-http-sql-sats-display.md rename to .codex/skills/genarrative-admin-backoffice/references/spacetimedb-http-sql-sats-display.md diff --git a/.hermes/skills/genarrative-auth-session-flow/SKILL.md b/.codex/skills/genarrative-auth-session-flow/SKILL.md similarity index 99% rename from .hermes/skills/genarrative-auth-session-flow/SKILL.md rename to .codex/skills/genarrative-auth-session-flow/SKILL.md index 4644306fd..7e49913a1 100644 --- a/.hermes/skills/genarrative-auth-session-flow/SKILL.md +++ b/.codex/skills/genarrative-auth-session-flow/SKILL.md @@ -1,11 +1,9 @@ --- name: genarrative-auth-session-flow description: 在 Genarrative 中排查或修改登录、access token、refresh cookie、AuthGate 会话恢复、登录态刷新、认证埋点链路时使用。 -version: 1.0.0 -author: Hermes Agent license: MIT metadata: - hermes: + codex: tags: [Genarrative, auth, session, cookie, refresh-token, AuthGate, tracking] related_skills: [systematic-debugging, test-driven-development, genarrative-profile-features] --- diff --git a/.hermes/skills/genarrative-auth-session-flow/references/session-restore-daily-login-tracking-2026-05-08.md b/.codex/skills/genarrative-auth-session-flow/references/session-restore-daily-login-tracking-2026-05-08.md similarity index 100% rename from .hermes/skills/genarrative-auth-session-flow/references/session-restore-daily-login-tracking-2026-05-08.md rename to .codex/skills/genarrative-auth-session-flow/references/session-restore-daily-login-tracking-2026-05-08.md diff --git a/.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md b/.codex/skills/genarrative-dev-stack-port-routing/SKILL.md similarity index 98% rename from .hermes/skills/genarrative-dev-stack-port-routing/SKILL.md rename to .codex/skills/genarrative-dev-stack-port-routing/SKILL.md index cde9e6977..0a0a6540c 100644 --- a/.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md +++ b/.codex/skills/genarrative-dev-stack-port-routing/SKILL.md @@ -1,12 +1,9 @@ --- name: genarrative-dev-stack-port-routing -short_description: 修改 Genarrative 本地 dev 启动端口、代理目标、端口冲突处理时使用。 description: 在 Genarrative 中修改 npm run dev / dev:spacetime / dev:api-server / dev:bgfilter-worker / dev:web / dev:admin-web 的本地启动端口、端口可用性探测、端口漂移、SpacetimeDB publish server、Rust 进程环境变量、Vite 代理目标和后台 admin-web 启动串联时使用。 -version: 1.2.0 -author: Hermes Agent license: MIT metadata: - hermes: + codex: tags: [Genarrative, dev-stack, 端口探测, Vite, api-server, SpacetimeDB, npm-run-dev] related_skills: [genarrative-admin-backoffice] --- diff --git a/.codex/skills/genarrative-play-type-integration/SKILL.md b/.codex/skills/genarrative-play-type-integration/SKILL.md index 63d14982e..9ba349906 100644 --- a/.codex/skills/genarrative-play-type-integration/SKILL.md +++ b/.codex/skills/genarrative-play-type-integration/SKILL.md @@ -3,7 +3,7 @@ name: genarrative-play-type-integration description: 在 Genarrative 中新增或补齐一个创作入口/玩法类型时，按入口配置、前端分流、契约、后端接口、工作台、独立生成页、结果页、发布、统一作品详情、正式 runtime、公开 read model、基础统计与作品架/广场的顺序接入。 license: MIT metadata: - author: Hermes Agent + author: Genarrative Team version: "1.0" --- @@ -90,13 +90,14 @@ metadata: 12. **旧数据策略**：旧草稿、旧发布配置、旧分享码是迁移、降级展示、重新生成，还是明确不兼容。 - `AGENTS.md` -- `.hermes/shared-memory/` +- `docs/project-memory/shared-memory/` - `CONTEXT.md` - `docs/README.md` - `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` - 相关玩法 PRD 或设计文档 +- `.codex/skills/genarrative-play-type-integration/references/genarrative-analytics-tracking-runtime.md`（涉及正式 runtime 埋点时） -如果文档不能精确指导字段、契约、资产槽位、生成流程和恢复语义，先补文档再编码。新增长期约定时同步 `.hermes/shared-memory/`。 +如果文档不能精确指导字段、契约、资产槽位、生成流程和恢复语义，先补文档再编码。新增长期约定时同步 `docs/project-memory/shared-memory/`。 ### 2. 定玩法边界 diff --git a/.hermes/skills/genarrative-play-type-integration/references/genarrative-analytics-tracking-runtime.md b/.codex/skills/genarrative-play-type-integration/references/genarrative-analytics-tracking-runtime.md similarity index 100% rename from .hermes/skills/genarrative-play-type-integration/references/genarrative-analytics-tracking-runtime.md rename to .codex/skills/genarrative-play-type-integration/references/genarrative-analytics-tracking-runtime.md diff --git a/.hermes/skills/genarrative-profile-features/SKILL.md b/.codex/skills/genarrative-profile-features/SKILL.md similarity index 99% rename from .hermes/skills/genarrative-profile-features/SKILL.md rename to .codex/skills/genarrative-profile-features/SKILL.md index 5dd6c87b5..81de55e44 100644 --- a/.hermes/skills/genarrative-profile-features/SKILL.md +++ b/.codex/skills/genarrative-profile-features/SKILL.md @@ -1,11 +1,9 @@ --- name: genarrative-profile-features description: 在 Genarrative “我的”页签新增或修改个人中心入口、独立 profile 路由、反馈/记录/设置类页面时使用。 -version: 1.0.0 -author: Hermes Agent license: MIT metadata: - hermes: + codex: tags: [Genarrative, profile, 我的页签, 前端, 路由, 反馈] related_skills: [writing-plans, test-driven-development] --- diff --git a/.hermes/skills/genarrative-profile-features/references/profile-feedback-entry-2026-05-08.md b/.codex/skills/genarrative-profile-features/references/profile-feedback-entry-2026-05-08.md similarity index 100% rename from .hermes/skills/genarrative-profile-features/references/profile-feedback-entry-2026-05-08.md rename to .codex/skills/genarrative-profile-features/references/profile-feedback-entry-2026-05-08.md diff --git a/.hermes/skills/genarrative-profile-invite-flow/SKILL.md b/.codex/skills/genarrative-profile-invite-flow/SKILL.md similarity index 99% rename from .hermes/skills/genarrative-profile-invite-flow/SKILL.md rename to .codex/skills/genarrative-profile-invite-flow/SKILL.md index 784998a10..eb2483590 100644 --- a/.hermes/skills/genarrative-profile-invite-flow/SKILL.md +++ b/.codex/skills/genarrative-profile-invite-flow/SKILL.md @@ -1,11 +1,9 @@ --- name: genarrative-profile-invite-flow description: 在 Genarrative 中排查或修改邀请码、邀请好友、首次登录后填写邀请码、我的页签邀请码兑换链路时使用。 -version: 1.0.0 -author: Hermes Agent license: MIT metadata: - hermes: + codex: tags: [Genarrative, 邀请码, referral, auth, profile, query-params, 前端] related_skills: [] --- diff --git a/.hermes/skills/genarrative-profile-invite-flow/references/query-invite-code-flow-2026-05-07.md b/.codex/skills/genarrative-profile-invite-flow/references/query-invite-code-flow-2026-05-07.md similarity index 100% rename from .hermes/skills/genarrative-profile-invite-flow/references/query-invite-code-flow-2026-05-07.md rename to .codex/skills/genarrative-profile-invite-flow/references/query-invite-code-flow-2026-05-07.md diff --git a/.hermes/README.md b/.hermes/README.md deleted file mode 100644 index e8b760a11..000000000 --- a/.hermes/README.md +++ /dev/null @@ -1,66 +0,0 @@ -# Genarrative Hermes 工具目录 - -本目录只保留 Hermes 专用的仓库级工具资源，例如 Hermes skills、plugins 和启用说明。项目知识本体、长期记忆、计划和 TODO 不再放在 `.hermes/`，统一迁移到 `docs/project-memory/`。 - -## 使用原则 - -- `.hermes/` 中只保存 Hermes 工具运行或加载所需内容。 -- 项目长期知识、架构约定、排障经验、协作规则、计划和 TODO 统一放在 `docs/project-memory/`。 -- 不提交个人配置、API Key、会话转录、模型密钥、本地路径密钥等敏感内容。 -- 个人 Hermes 的 `~/.hermes/config.yaml`、`~/.hermes/.env`、`~/.hermes/sessions/` 不应复制到本仓库。 -- 后续新增的 Markdown 文档文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`，便于团队跨目录检索。 -- 若 `.hermes/` 中的工具说明与代码或 `docs/` 冲突，以当前代码和最新 `docs/` 为准。 - -## 目录结构 - -```text -.hermes/ -├─ README.md # Hermes 工具目录说明 -├─ skills/ # 仓库级 Hermes skills -└─ plugins/ # 仓库级 Hermes plugins（需显式启用项目 plugin） -``` - -## 仓库级 Plugins - -本仓库可共享的 Hermes plugin 放在 `.hermes/plugins//`。当前已包含： - -- `.hermes/plugins/game-studio/`：浏览器游戏设计、原型、2D/3D 技术栈、素材管线与 playtest 相关工作流。 - -Hermes 的项目级 plugin 默认不会自动加载。团队成员拉取仓库后，如需使用本仓库内 plugin，请在仓库根目录启动 Hermes 前设置： - -```bash -export HERMES_ENABLE_PROJECT_PLUGINS=1 -``` - -然后确认当前 Hermes 配置的 `plugins.enabled` 中包含 `game-studio`。如果成员本机尚未启用过该 plugin，当前 Hermes 的 `hermes plugins enable` 只识别用户级或内置 plugin，可能不会识别项目级 plugin；可用以下命令写入个人配置： - -```bash -python - <<'PY' -from hermes_cli.config import load_config, save_config -config = load_config() -plugins = config.setdefault('plugins', {}) -enabled = set(plugins.get('enabled') or []) -disabled = set(plugins.get('disabled') or []) -enabled.add('game-studio') -disabled.discard('game-studio') -plugins['enabled'] = sorted(enabled) -plugins['disabled'] = sorted(disabled) -save_config(config) -PY -``` - -启用后重新进入一个新 Hermes 会话。`hermes plugins list` 当前主要展示内置和用户级 plugin，未必列出项目级 plugin；如需验证项目级扫描，可在仓库根目录运行： - -```bash -HERMES_ENABLE_PROJECT_PLUGINS=1 HERMES_PLUGINS_DEBUG=1 hermes chat -q "请读取 game-studio:game-studio skill 并概括它的用途" -``` - -该 plugin 注册的是带命名空间的 plugin skills，可用类似 `game-studio:phaser-2d-game` 的名称显式加载。 - -## 推荐给 Hermes 的启动提示 - -在本仓库中开始复杂任务时，可以先对 Hermes 说： - -```text -请先读取 AGENTS.md 以及 docs/project-memory/shared-memory/ 下与本任务相关的团队共享记忆，再开始分析。若任务完成后产生稳定项目知识，请更新 docs/project-memory/shared-memory/ 对应文件。 -``` diff --git a/.hermes/skills/README.md b/.hermes/skills/README.md deleted file mode 100644 index 3464aa0e3..000000000 --- a/.hermes/skills/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# 仓库级 Hermes Skills - -本目录预留给未来可共享的仓库级 Hermes skills。 - -## 什么时候沉淀为 Skill - -当某个流程满足以下条件之一时，可以考虑从普通 Markdown 升级为 skill： - -- 需要反复执行，且步骤稳定。 -- 涉及多个目录、命令或验证步骤。 -- 曾经踩过坑，需要明确规避步骤。 -- 新成员容易做错。 -- Hermes 在执行时需要强制加载专门知识。 - -## 建议结构 - -```text -.hermes/skills/ -└─ skill-name/ - └─ SKILL.md -``` - -## 注意 - -- 不要把 API Key、Token、账号密码写入 skill。 -- 如果 skill 与 `AGENTS.md` 或 `docs/` 冲突，先更新冲突来源再使用。 -- Skill 应包含触发条件、步骤、坑点和验证方式。 diff --git a/.hermes/skills/genarrative-play-type-integration/SKILL.md b/.hermes/skills/genarrative-play-type-integration/SKILL.md deleted file mode 100644 index f34f15583..000000000 --- a/.hermes/skills/genarrative-play-type-integration/SKILL.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -name: genarrative-play-type-integration -description: 在 Genarrative 新增、开放或重构玩法创作工具时，按平台级强约束 SOP 接入入口配置、表单/图片输入创作工作台、单图资产槽位、系列素材图集生成、独立契约、后端 DDD、结果页、运行态、作品架、广场与验证；用于避免复制既有玩法、默认对话式 Agent、页面内手写图片输入或复用玩法专属素材模型。 ---- - -# Genarrative 新增玩法创作工具平台 SOP - -把新增玩法当成平台能力接入，不把任何既有玩法当作默认模板。先确定通用模式和契约，再写具体玩法代码。 - -## 硬性禁区 - -- 不恢复前端硬编码入口配置；创作入口事实源必须来自 SpacetimeDB 和 `/api/creation-entry/config`。 -- 不把聊天输入区、流式消息或轻输入 Agent 作为新增玩法默认工作台。 -- 不在新页面内手写图片上传、参考图、AI 重绘、历史图选择、预览或删除确认逻辑。 -- 不把通用系列素材建模成任一玩法专属 DTO；玩法只能追加自己的运行态字段。 -- 不让前端承接正式业务真相；发布、试玩、通关、失败、计分、资产持久化和作品状态以后端投影为准。 -- 不新建平行入口系统、平行作品架或平行公开列表；优先扩展现有平台壳、现有阶段和现有聚合。 -- 不在 UI 面板内默认写功能说明、规则说明或开发解释文案。 - -## 接入前输入 - -开始编码前，PRD 或当前玩法文档必须已经明确： - -- `playId`、对外名称、工程域名、入口 `visible/open` 状态。 -- 创作链路：入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态。 -- 表单字段：字段名、默认值、校验、后端落库位置、生成提示词来源。 -- 单图资产槽位：`slotId`、`slotType`、`slotName`、提示词来源、读取字段、写回字段、是否允许历史图和 AI 重绘。 -- 系列素材槽位：`batchId` 语义、`sheetSpec`、`slotSpecs`、切图规则、透明化规则、失败回写、局部重生成策略。 -- API 命名空间：`/api/creation//sessions`、`actions`、`works`、`runtime`。 -- 草稿恢复、生成中恢复、失败重试、登录切换、发布后回读和移动端行为。 -- 验证命令和例外声明；没有例外时写明“无创作工具模式例外”。 - -## 默认模式 - -新增玩法默认采用表单/图片输入创作工作台： - -```text -创作入口 -> 表单/图片输入工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态 -``` - -工作台只提交结构化表单、图片槽位和配置 payload。确需自然语言对话时，先走“例外流程”，不能把聊天区直接加进默认工作台。 - -## SOP - -### 1. 文档和领域词先行 - -先读： - -- `AGENTS.md` -- `docs/project-memory/shared-memory/` -- `CONTEXT.md` -- `docs/README.md` -- `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` -- 相关玩法 PRD 或设计文档 - -如果文档不能精确指导字段、契约、资产槽位、生成流程和恢复语义，先补文档再编码。新增长期约定时同步 `docs/project-memory/shared-memory/`。 - -### 2. 定玩法边界 - -固定 `playId`、对外名称、工程域、入口状态、是否支持结果页、试玩、发布、作品架、广场、分享和 runtime。不要先用临时 ID 接线后再批量改名。 - -### 3. 接入口配置 - -入口配置事实源是 SpacetimeDB `creation_entry_type_config`。后台通过 `/admin/api/creation-entry/config` 管理，前台通过 `/api/creation-entry/config` 读取。 - -前端只允许在展示层派生： - -- 可见入口卡片。 -- 锁定或开放状态。 -- 排序、图标、短标题等展示信息。 - -`api-server` 路由熔断必须使用同一份入口配置。禁止新增或恢复前端本地默认入口配置作为事实源。 - -### 4. 前端阶段 - -按需要扩展 `SelectionStage`： - -- `-workspace` -- `-generating` -- `-result` -- `-runtime` -- `-gallery-detail` - -阶段名可以按玩法命名，UI 形态必须仍是表单/图片创作工作台。进入工作台时只初始化结构化草稿状态，不启动默认聊天会话。 - -### 5. 工作台实现 - -工作台必须满足： - -- 使用表单控件、图片槽位、风格选项、难度选项、开关和提交按钮组织输入。 -- 单图槽位统一使用 `CreativeImageInputPanel`。 -- 组件缺少能力时先扩展 `CreativeImageInputPanel` 的受控 props，不在玩法页面复制上传、参考图、AI 重绘、历史图、预览或删除确认。 -- 主图读取、裁剪、历史素材弹层、计费确认、自动保存和后端请求由外层页面持有；通用面板只表达输入 UI 和短生命周期 UI 状态。 -- 提交 payload 必须是表单字段与图片槽位结构，不是用户消息文本。 - -### 6. 单图资产槽位 - -角色形象、UI 背景、容器、封面、分享图、图标等单张图都按单图资产槽位处理。 - -统一约定： - -- 槽位用 `slotId` 稳定标识，`slotType` 表达用途，`slotName` 用于 UI 标签。 -- 上传图、参考图、AI 重绘、历史图选择和删除确认都通过 `CreativeImageInputPanel` 入口表达。 -- 后端写回 `imageSrc`、`imageObjectKey`、`assetObjectId` 中可用字段；前端展示前通过平台资产读取能力换签。 -- 单个槽位重生成只禁用该槽位动作，不阻塞结果页其它槽位、系列素材槽位或导航。 - -### 7. 系列素材图集生成 - -地块、物品、障碍、装饰、UI 部件等一组同类素材都走通用系列素材图集生成流程： - -```text -批量规划 -> sheet 生图 -> 后端切图 -> 去背景/透明化 -> PNG 输出 -> OSS 持久化 -> 状态回写 -> 局部重生成 -``` - -玩法只提供： - -- `sheetSpec`：画布比例、行列、单格尺寸、输出格式、背景处理策略。 -- `slotSpecs`：每个素材槽位的 `slotId`、`slotType`、`slotName`、提示词、sheet 单元格映射。 -- 玩法字段映射：把通用素材结果映射回玩法自己的 draft/profile/runtime 字段。 - -通用系列素材结果建议字段： - -- `batchId` -- `slotId` -- `slotType` -- `slotName` -- `prompt` -- `imageSrc` -- `imageObjectKey` -- `assetObjectId` -- `sourceSheetCell` -- `status` -- `error` - -玩法可追加运行态字段，例如半径、宽度、视图索引或碰撞参数，但不能依赖任何玩法专属字段作为平台通用模型。新增玩法 compile action 内部调用通用系列素材服务；如果通用服务还缺能力，先补通用服务再接玩法。 - -### 8. 契约与 API - -前后端必须同步补契约： - -- `packages/shared/src/contracts/` -- `server-rs/crates/shared-contracts/src/` - -玩法 API 保留独立命名空间： - -- `POST /api/creation//sessions` -- `GET /api/creation//sessions/{sessionId}` -- `POST /api/creation//sessions/{sessionId}/actions` -- `/api/creation//works` -- `/api/creation//runtime` - -契约需要区分： - -- 工作台输入。 -- 草稿 snapshot。 -- 单图资产槽位。 -- 系列素材批次与槽位。 -- 结果页操作。 -- 发布作品摘要。 -- runtime snapshot。 - -### 9. 后端分层 - -按 DDD 边界落地： - -- `module-`：纯领域规则、状态机、draft/runtime 校验。 -- `shared-contracts`：前后端 DTO。 -- `spacetime-module`：表、reducer、procedure、事务编排、migration。 -- `spacetime-client`：typed facade 和 row mapper。 -- `api-server`：Axum 路由、鉴权、BFF、SSE、生成编排。 -- `platform-*`：LLM、图片生成、OSS、认证等外部副作用。 - -涉及 SpacetimeDB schema 时同步 `migration.rs`、表目录和绑定，并运行 `npm run check:spacetime-schema`。 - -### 10. 结果页 - -结果页至少支持： - -- 展示草稿和生成状态。 -- 返回工作台编辑。 -- 单图槽位重生成。 -- 系列素材追加、替换、局部重生成。 -- 发布。 -- 试玩。 -- 错误展示和失败重试。 - -单图槽位和系列素材槽位的生成状态互不阻塞。已有可查看结果时，局部重生成不能把作品架草稿重新变成不可打开的全局生成中。 - -### 11. 运行态、作品架和广场 - -需要试玩或发布时补齐： - -- runtime start/action/finish API。 -- 作品保存、发布、删除、回读。 -- 作品架摘要。 -- 公开列表、详情、分享码。 -- 公开列表优先消费后端投影或 BFF 缓存，不让前端直接拼源表事实。 - -运行态可以做低延迟表现，但正式胜负、分数、奖励、排行榜和发布状态以后端裁决为准。 - -### 12. 恢复与登录态 - -必须处理： - -- 刷新恢复生成中草稿。 -- 生成页计时从后端摘要时间恢复。 -- 失败后回读 session/work detail 再决定是否展示失败。 -- 退出登录清空私有玩法状态。 -- 私有生成图展示前换签。 -- result/runtime 缺必要 draft 时回到可恢复入口，不停在空白页。 - -### 13. 例外流程 - -任何非表单/图片工作台、对话式 Agent、独立创作系统或特殊资产模型都必须先更新 PRD 和平台文档。例外声明至少写清： - -- 为什么默认表单/图片工作台不能满足。 -- 例外影响哪些输入、契约、后端流程和测试。 -- 如何保留单图资产槽位和系列素材槽位的通用能力。 -- 如何回退到平台默认链路。 - -没有文档例外，不进入编码。 - -## PRD 检查块 - -在新增玩法 PRD 中保留这一段： - -```md -## 创作工具平台接入声明 - -- 工作台模式：表单/图片输入创作工作台 -- 创作链路：入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态 -- 单图资产槽位： - - slotId / slotType / slotName / 提示词来源 / 写回字段 / 是否允许历史图 / 是否允许 AI 重绘 -- 系列素材槽位： - - batchId / sheetSpec / slotSpecs / 切图规则 / 透明化规则 / 失败回写 / 局部重生成 -- API 命名空间：/api/creation//... -- 业务真相：后端裁决字段和前端表现字段边界 -- 创作工具模式例外：无；如有，先写明例外原因和回退方式 -- 验证命令： -``` - -## 验证门禁 - -按改动范围运行： - -- `npm run check:encoding` -- `npm run typecheck` -- 前端工作台测试：确认没有聊天式 Agent 输入，提交的是表单/图片 payload。 -- `CreativeImageInputPanel` 测试：覆盖多玩法标签、上传、AI 重绘、参考图上限、历史图入口和删除确认。 -- 系列素材测试：覆盖 sheet layout、切图、透明化、OSS 持久化、追加、替换、局部重生成和失败回写。 -- 结果页测试：覆盖单图槽位重生成和系列素材槽位重生成互不阻塞。 -- 后端定向测试：覆盖 compile action、资产持久化、失败回写、发布和 runtime start。 -- 涉及 SpacetimeDB schema 时运行 `npm run check:spacetime-schema`。 diff --git a/AGENTS.md b/AGENTS.md index c859362fd..4ba512832 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,11 +4,12 @@ - 本文件只保留 Agent 进入仓库后必须立即遵守的最高优先级规则；完整执行细则见 [`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`](docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md)。 - 团队级长期项目记忆位于 [`docs/project-memory/`](docs/project-memory/)，供 3 名开发人员和各自本地 Agent 通过 Git 同步。 -- [`.hermes/`](.hermes/) 只保存 Hermes 专用仓库级工具资源，例如 skills、plugins 和启用说明；长期项目知识不要写入 `.hermes/`。 +- [`.codex/`](.codex/) 只保存仓库级 Codex 工具资源，例如 skills、plugins、hooks 和配置模板；长期项目知识不要写入 `.codex/`。 - 若 `docs/project-memory/shared-memory/` 与当前代码或最新 `docs/` 冲突，以代码和最新 `docs/` 为准，并同步修正过期共享记忆。 ## 开始任务前 +- 先写清一句话交付结果、验收判据和不做项，再按“必须项 / 风险项 / 可选项”排序；优先完成修改、定向验证和边界检查组成的最小闭环。设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，否则记录为后续事项；工具探测、历史整理或验证便利不能自行改变任务目标。 - 简单自包含任务可以直接执行；复杂开发、跨模块修改、后端 / UI / 文档体系调整前，按顺序读取： 1. 本文件。 2. [`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`](docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md)。 @@ -19,7 +20,7 @@ ## 绝对约束 -- 禁止提交个人 `~/.hermes` 配置、`.env`、API Key、Token、Cookie、会话记录、认证文件、本地私密路径、构建产物、日志、缓存和数据库 dump。 +- 禁止提交个人 `~/.codex` 配置、`.env`、API Key、Token、Cookie、会话记录、认证文件、本地私密路径、构建产物、日志、缓存和数据库 dump。 - 不要在 `.gitignore` 中新增 `.env.local`。 - 不要擅自把现有中文文案、注释、剧情或文档改写成英文；看到中文乱码时先确认真实编码，不要沿用乱码或用英文替换。 - 修改包含中文的文件时优先局部补丁，避免整文件重写；修改后优先运行仓库编码检查。 @@ -38,10 +39,10 @@ ## 任务路由 - Issue 使用自托管 Gitea；优先用 Gitea UI/API 或 `tea` CLI，不使用 GitHub `gh` 或 GitLab `glab`，除非仓库已迁移。默认 triage 标签：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。 -- 需要仓库级 Hermes skills/plugins 时，再读取 [`.hermes/README.md`](.hermes/README.md)。 +- 需要仓库级 Codex skills/plugins 时，再读取 [`.codex/README.md`](.codex/README.md)。 - 涉及 AI 游戏创作独立 App、多智能体 Runtime、本地项目产物或本地 HTTP 预览时，先读取 [`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`](docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)。 - 新增、补齐、迁移或重构玩法入口、玩法类型、创作工作台、生成页、结果页、发布、运行态、作品架、广场或公开 read model 前，必须读取并按 [`genarrative-play-type-integration`](.codex/skills/genarrative-play-type-integration/SKILL.md) 执行。 -- 涉及 `npm run dev` / `npm run dev:spacetime` / `npm run dev:api-server` / `npm run dev:web` / `npm run dev:admin-web` 的端口探测、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理目标或后台 dev 端口时，按 [`.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md`](.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md) 执行。 +- 涉及 `npm run dev` / `npm run dev:spacetime` / `npm run dev:api-server` / `npm run dev:web` / `npm run dev:admin-web` 的端口探测、端口漂移、SpacetimeDB publish server、api-server 环境变量、Vite 代理目标或后台 dev 端口时，按 [`.codex/skills/genarrative-dev-stack-port-routing/SKILL.md`](.codex/skills/genarrative-dev-stack-port-routing/SKILL.md) 执行。 - 涉及 SpacetimeDB 的设计、实现、脚本、调试、发布、绑定生成、schema、reducer、procedure、view 或 API 时，必须先读取并按 [`genarrative-spacetimedb`](.codex/skills/genarrative-spacetimedb/SKILL.md) 执行。 ## 后端红线 diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs index 0470d5a8a..6a6a73b29 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tool_bridge.rs @@ -1286,7 +1286,6 @@ fn bridge_project_file_is_hidden_control_path(path: &str) -> bool { part.eq_ignore_ascii_case(".agent") || part.eq_ignore_ascii_case(".git") || part.eq_ignore_ascii_case(".codex") - || part.eq_ignore_ascii_case(".hermes") || part.eq_ignore_ascii_case("node_modules") }) } @@ -2312,7 +2311,7 @@ mod tests { for path in [ ".agent/manifest.json", "tools/.codex/private.png", - "vendor/.hermes/private.png", + "vendor/.codex/private.png", "game/node_modules/private.png", ] { assert!( diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs index 31cbeaf63..047dfab0d 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/direct_tools_mcp.rs @@ -612,9 +612,9 @@ fn validate_account_asset_import_string_array( )); } if should_skip_project_snapshot_path(text) - || text.split('/').any(|part| { - part.eq_ignore_ascii_case(".codex") || part.eq_ignore_ascii_case(".hermes") - }) + || text + .split('/') + .any(|part| part.eq_ignore_ascii_case(".codex")) || reject_sensitive_project_file_read(text).is_err() { return Err(format!("工具参数 {field} 不得访问隐藏、构建或敏感控制路径")); @@ -1288,7 +1288,7 @@ mod tests { .is_err()); for local_path in [ "tools/.codex/hero.png", - "vendor/.hermes/hero.png", + "vendor/.codex/hero.png", "game/node_modules/hero.png", "secrets/hero.png", ] { diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/prompt_context.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/prompt_context.rs index db1b51976..e1b1a1aa5 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/generation/prompt_context.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/generation/prompt_context.rs @@ -184,9 +184,9 @@ fn prompt_context_hidden_project_path(path: &str) -> bool { // directories and sensitive file suffixes; a media extension alone must // never make one of those paths visible to the model. should_skip_project_snapshot_path(path) - || path.split('/').any(|component| { - component.eq_ignore_ascii_case(".codex") || component.eq_ignore_ascii_case(".hermes") - }) + || path + .split('/') + .any(|component| component.eq_ignore_ascii_case(".codex")) } fn prompt_context_media_type(path: &str) -> Option<&'static str> { diff --git a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/context.rs b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/context.rs index 71a033ff8..0580895f0 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/context.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/context.rs @@ -470,9 +470,9 @@ fn runtime_asset_import_string_array( || text.contains("://") || has_parent || should_skip_project_snapshot_path(text) - || text.split('/').any(|part| { - part.eq_ignore_ascii_case(".codex") || part.eq_ignore_ascii_case(".hermes") - }) + || text + .split('/') + .any(|part| part.eq_ignore_ascii_case(".codex")) || reject_sensitive_project_file_read(text).is_err() { return Err("localPaths 只能使用受控项目根内的项目相对图片路径".to_string()); @@ -774,7 +774,7 @@ mod asset_import_input_tests { assert!(runtime_asset_import_string_array(&private, "localPaths", 100).is_err()); for protected in [ "tools/.codex/hero.png", - "vendor/.hermes/hero.png", + "vendor/.codex/hero.png", "game/node_modules/hero.png", "secrets/hero.png", ] { diff --git a/apps/ai-game-creator-shell/src-tauri/src/command_exec.rs b/apps/ai-game-creator-shell/src-tauri/src/command_exec.rs index 873662bca..db05d7596 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/command_exec.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/command_exec.rs @@ -759,7 +759,6 @@ fn project_command_argument_contains_sensitive_path(value: &str) -> bool { | ".git" | ".agents" | ".codex" - | ".hermes" | ".hg" | ".svn" | ".ssh" @@ -2280,7 +2279,7 @@ mod tests { async fn project_command_workspace_sandbox_blocks_host_controls_and_network() { let dir = command_project("workspace-sandbox"); let root = dir.path(); - for name in [".git", ".agents", ".codex", ".hermes"] { + for name in [".git", ".agents", ".codex"] { fs::create_dir_all(root.join(name)).expect("create protected directory"); fs::write(root.join(name).join("marker"), name).expect("write protected marker"); } @@ -2294,7 +2293,7 @@ mod tests { printf WORKSPACE_OK > workspace-write.txt test ! -r {outside:?} ! printf NO > {outside:?} -for control in .git .agents .codex .hermes; do +for control in .git .agents .codex; do test -r "$control/marker" ! touch "$control/blocked-write" done @@ -2326,7 +2325,7 @@ raise SystemExit(code)' fs::read_to_string(&outside).expect("outside sentinel"), "HOST_SECRET" ); - for name in [".git", ".agents", ".codex", ".hermes"] { + for name in [".git", ".agents", ".codex"] { assert!(!root.join(name).join("blocked-write").exists()); } fs::remove_file(outside).ok(); diff --git a/apps/ai-game-creator-shell/src-tauri/src/command_sandbox.rs b/apps/ai-game-creator-shell/src-tauri/src/command_sandbox.rs index 11725bddf..ed2a9cdf1 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/command_sandbox.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/command_sandbox.rs @@ -181,7 +181,7 @@ mod linux { use std::time::{Duration, Instant}; const TRUSTED_BWRAP_PATHS: [&str; 2] = ["/usr/bin/bwrap", "/bin/bwrap"]; - const PROTECTED_READ_ONLY_NAMES: [&str; 4] = [".git", ".agents", ".codex", ".hermes"]; + const PROTECTED_READ_ONLY_NAMES: [&str; 3] = [".git", ".agents", ".codex"]; const TOOLCHAIN_ENVIRONMENT_ROOTS: [&str; 4] = ["RUSTUP_HOME", "JAVA_HOME", "GOROOT", "DOTNET_ROOT"]; const FIXED_SYSTEM_READ_ONLY_PATHS: [&str; 8] = [ @@ -962,7 +962,6 @@ mod linux { PathBuf::from("/workspace/project/.git"), PathBuf::from("/workspace/project/.agents"), PathBuf::from("/workspace/project/.codex"), - PathBuf::from("/workspace/project/.hermes"), ], external_read_only: vec![ReadOnlyMount { source: PathBuf::from("/opt/toolchain/bin/tool"), @@ -995,7 +994,7 @@ mod linux { &launch.arguments, &["--bind", "/workspace/project", "/workspace/project"] )); - for path in [".git", ".agents", ".codex", ".hermes"] { + for path in [".git", ".agents", ".codex"] { let path = format!("/workspace/project/{path}"); assert!(has_sequence( &launch.arguments, @@ -1162,7 +1161,7 @@ mod linux { let outside = tree.0.join("outside-secret.txt"); std::fs::create_dir_all(&root).expect("create workspace"); std::fs::write(&outside, "OUTSIDE_SECRET").expect("write outside secret"); - for name in [".agent", ".git", ".agents", ".codex", ".hermes"] { + for name in [".agent", ".git", ".agents", ".codex"] { std::fs::create_dir_all(root.join(name)).expect("create control directory"); std::fs::write(root.join(name).join("marker"), name).expect("write control marker"); } @@ -1175,7 +1174,7 @@ import subprocess Path("workspace-write.txt").write_text("WORKSPACE_OK") assert Path("workspace-write.txt").read_text() == "WORKSPACE_OK" -for control in [".git", ".agents", ".codex", ".hermes"]: +for control in [".git", ".agents", ".codex"]: assert Path(control, "marker").read_text() == control try: Path(control, "blocked-write").write_text("NO") @@ -1259,7 +1258,7 @@ print("SANDBOX_OK") std::fs::read_to_string(&outside).expect("outside secret unchanged"), "OUTSIDE_SECRET" ); - for name in [".git", ".agents", ".codex", ".hermes"] { + for name in [".git", ".agents", ".codex"] { assert!(!root.join(name).join("blocked-write").exists()); } } @@ -1272,7 +1271,7 @@ print("SANDBOX_OK") let tree = unique_temp_tree(); let root = tree.0.join("workspace-staged-gate"); std::fs::create_dir_all(&root).expect("create workspace"); - for name in [".agent", ".git", ".agents", ".codex", ".hermes"] { + for name in [".agent", ".git", ".agents", ".codex"] { std::fs::create_dir_all(root.join(name)).expect("create control directory"); } let marker = root.join("committed-target-ran"); diff --git a/apps/ai-game-creator-shell/src-tauri/src/commands.rs b/apps/ai-game-creator-shell/src-tauri/src/commands.rs index 15809d736..73221b283 100644 --- a/apps/ai-game-creator-shell/src-tauri/src/commands.rs +++ b/apps/ai-game-creator-shell/src-tauri/src/commands.rs @@ -2802,7 +2802,6 @@ mod agent_asset_import_tests { for (index, directory) in [ ".git", ".codex", - ".hermes", "node_modules", "target", "dist", @@ -3350,7 +3349,7 @@ fn reject_agent_local_image_source_path(normalized_path: &str) -> Result<(), Str if should_skip_project_snapshot_path(normalized_path) || normalized_path .split('/') - .any(|part| part.eq_ignore_ascii_case(".codex") || part.eq_ignore_ascii_case(".hermes")) + .any(|part| part.eq_ignore_ascii_case(".codex")) { return Err("本地图片导入不得访问隐藏、构建或工具控制目录".to_string()); } diff --git a/apps/ai-game-creator-shell/src/components/AssetImporter/utils.ts b/apps/ai-game-creator-shell/src/components/AssetImporter/utils.ts index 47231e90e..b8c80e344 100644 --- a/apps/ai-game-creator-shell/src/components/AssetImporter/utils.ts +++ b/apps/ai-game-creator-shell/src/components/AssetImporter/utils.ts @@ -189,7 +189,6 @@ function isVisibleProjectPath(localPath: string) { 'secrets', 'credentials', '.codex', - '.hermes', 'node_modules', 'target', 'dist', diff --git a/docs/project-memory/README.md b/docs/project-memory/README.md index 6c1fb53b7..ee8ef51f8 100644 --- a/docs/project-memory/README.md +++ b/docs/project-memory/README.md @@ -1,6 +1,6 @@ # 项目记忆目录 -本目录只保存可以通过 Git 共享、并且对当前开发仍有效的项目知识。`.hermes/` 只放 Hermes 工具资源，不作为项目知识库。 +本目录只保存可以通过 Git 共享、并且对当前开发仍有效的项目知识。`.codex/` 只放 Codex 工具资源，不作为项目知识库。 ## 当前结构 diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 44c6c3147..0cb6906fd 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -3400,9 +3400,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 敲木鱼玩法按完整平台纵切接入 @@ -3977,13 +3977,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 @@ -5856,7 +5856,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。 diff --git a/docs/project-memory/shared-memory/development-workflow.md b/docs/project-memory/shared-memory/development-workflow.md index 21a49bcf0..34ec431a4 100644 --- a/docs/project-memory/shared-memory/development-workflow.md +++ b/docs/project-memory/shared-memory/development-workflow.md @@ -1,6 +1,6 @@ # 开发工作流 -更新时间：`2026-08-25` +更新时间：`2026-08-27` ## 标准流程 @@ -8,6 +8,8 @@ 确认工作树与目标分支 → 读取入口和当前专题 → 查代码真相 → 小步修改 → 定向验证 → 更新当前文档/记忆 → 检查提交边界 ``` +任务开始时先写清一句话交付结果、验收判据和不做项，再按“必须项 / 风险项 / 可选项”排序。先完成修改、定向验证和边界检查组成的最小闭环；设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，否则记录为后续事项。不要让工具探测、历史整理或验证便利自行改变任务目标。 + ## 开始前 - 运行 `git status --short`，保留用户已有的未提交修改；不要在共享工作树中使用破坏性 Git 命令。 diff --git a/docs/project-memory/shared-memory/handoff-template.md b/docs/project-memory/shared-memory/handoff-template.md index e7f0681a3..01ad2101b 100644 --- a/docs/project-memory/shared-memory/handoff-template.md +++ b/docs/project-memory/shared-memory/handoff-template.md @@ -1,6 +1,6 @@ # 任务交接模板 -> 用途：当一名开发者把任务交给另一名开发者，或让 Hermes 接续上下文时，复制本模板并填写。 +> 用途：当一名开发者把任务交给另一名开发者，或让 Codex 接续上下文时，复制本模板并填写。 ## 基本信息 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index cf3ddfd0f..004fda8de 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -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 --database ` 和 `npm run dev:api-server -- --api-port --spacetime-port --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 都要强制拉镜像 diff --git a/docs/project-memory/shared-memory/team-conventions.md b/docs/project-memory/shared-memory/team-conventions.md index 1291c9fe1..349f14e18 100644 --- a/docs/project-memory/shared-memory/team-conventions.md +++ b/docs/project-memory/shared-memory/team-conventions.md @@ -4,7 +4,7 @@ - 3 名开发人员在各自环境使用本地 Agent，通过同一 Git 仓库同步代码和项目知识。 - 每个任务保持分支、工作树和修改范围清晰；多人或多 Agent 并行修改前先划分不重叠的文件边界。 -- 项目知识进入 `docs/` 与 `docs/project-memory/`；个人 `~/.hermes`、Agent 会话和本地配置不共享。 +- 项目知识进入 `docs/` 与 `docs/project-memory/`；个人 `~/.codex`、Agent 会话和本地配置不共享。 ## 开发前 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 4616fd53a..4a255f578 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 @@ -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.md` 与兼容目录 `.agents/skills//SKILL.md`，只接受这两个根下的直接子目录入口，不递归把 reference 中的其它 `SKILL.md` 当独立 Skill。本仓库既有规范以 `.codex/skills` 为准；同名且两处都合法时 `.codex` 胜出，删除高优先级入口后 `.agents` 才可接管。V1.25 不扫描 AppData、用户主目录、全局 Codex/Hermes 安装目录、Git submodule 外部路径或网络 marketplace。 +- 发现根固定为项目内 `.codex/skills//SKILL.md` 与兼容目录 `.agents/skills//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 语义。 diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md index 09fff70fb..3f814a390 100644 --- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md +++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md @@ -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`。 diff --git a/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md b/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md index 5fa6161e9..1111073b8 100644 --- a/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md +++ b/docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md @@ -24,7 +24,7 @@ - `docs/`：当前 PRD、架构、开发运维、设计和测试口径。 - `docs/project-memory/shared-memory/`：长期团队记忆、决策、流程和踩坑摘要。 -- `.hermes/`：Hermes 工具资源，不作为项目知识库。 +- `.codex/`：Codex 工具资源，不作为项目知识库。 - `.codex/skills/`：Codex 可复用技能；只在任务命中时读取。 - `scripts/rag/`：Agent 本地检索入口，只提供候选上下文。 @@ -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 与提交 diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index 7de599e9c..c50307981 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -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/` 工具目录作为项目知识库索引源。 首次拉取或需要重建索引时： diff --git a/docs/【项目基线】当前产品与工程约束-2026-05-15.md b/docs/【项目基线】当前产品与工程约束-2026-05-15.md index 38f4e5a2d..68e502148 100644 --- a/docs/【项目基线】当前产品与工程约束-2026-05-15.md +++ b/docs/【项目基线】当前产品与工程约束-2026-05-15.md @@ -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/`。 ## 当前文档策略 diff --git a/scripts/rag/README.md b/scripts/rag/README.md index cbdfeea6d..725abb34f 100644 --- a/scripts/rag/README.md +++ b/scripts/rag/README.md @@ -80,4 +80,4 @@ Agent 使用规则： - `docs/project-memory/` - `docs/` -`.hermes/` 是 Hermes 工具目录，不作为项目知识库索引源。 +`.codex/` 是 Codex 工具目录，不作为项目知识库索引源。 diff --git a/scripts/rag/rag-config.json b/scripts/rag/rag-config.json index 0d33855d7..18df13270 100644 --- a/scripts/rag/rag-config.json +++ b/scripts/rag/rag-config.json @@ -30,7 +30,7 @@ "exclude": [ ".git/", ".rag/", - ".hermes/", + ".codex/", ".codegraph/", ".app/", "node_modules/",