Genarrative/AGENTS.md

AGENTS.md

入口定位

• 本文件只保留 Agent 进入仓库后必须立即遵守的最高优先级规则；完整执行细则见 docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md。
• 团队级长期项目记忆位于 docs/project-memory/，供 3 名开发人员和各自本地 Agent 通过 Git 同步。
• .codex/ 只保存仓库级 Codex 工具资源，例如 skills、plugins、hooks 和配置模板；长期项目知识不要写入 .codex/。
• 若 docs/project-memory/shared-memory/ 与当前代码或最新 docs/ 冲突，以代码和最新 docs/ 为准，并同步修正过期共享记忆。

开始任务前

• 先写清一句话交付结果、验收判据和不做项，再按“必须项 / 风险项 / 可选项”排序；优先完成修改、定向验证和边界检查组成的最小闭环。设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，否则记录为后续事项；工具探测、历史整理或验证便利不能自行改变任务目标。
• 简单自包含任务可以直接执行；复杂开发、跨模块修改、后端 / UI / 文档体系调整前，按顺序读取：
  1. 本文件。
  2. docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md。
  3. docs/project-memory/README.md、project-overview.md、team-conventions.md、development-workflow.md。
  4. 与任务相关的 decision-log.md、pitfalls.md、docs/README.md 和当前专题文档。
• 落地工程修改前，先确认是否已有足够具体的 PRD、技术方案或当前融合文档；文档仍存在编码级歧义时，先补文档再编码。
• 本仓库的本地 RAG 位于 scripts/rag/；RAG 只作为候选上下文，不替代打开源文件核对。默认不安装 RAG 运行时依赖，需要启用时必须先询问用户，并只安装到 gitignored 的 .rag/runtime/。

绝对约束

• 禁止提交个人 ~/.codex 配置、.env、API Key、Token、Cookie、会话记录、认证文件、本地私密路径、构建产物、日志、缓存和数据库 dump。
• 不要在 .gitignore 中新增 .env.local。
• 不要擅自把现有中文文案、注释、剧情或文档改写成英文；看到中文乱码时先确认真实编码，不要沿用乱码或用英文替换。
• 修改包含中文的文件时优先局部补丁，避免整文件重写；修改后优先运行仓库编码检查。
• 后续新增 Markdown 文档文件名必须以分类标签开头，格式为 【标签名】中文标题-日期.md；历史文档不要求批量重命名，除非本次任务明确涉及。
• 工程修改要同步更新对应 docs/ 文档；产生长期有效的架构约定、接口变化、排障经验、开发流程或协作规则时，同步更新 docs/project-memory/shared-memory/。
• 默认保持系统简洁：优先复用、修改、扩展现有系统、页面和公共组件，不新建平行系统或平行页面。
• UI 开发优先复用现有公共组件；发现跨页面或跨端重复的视觉/交互模式时，先抽取到 packages/shared 共享组件库并让现有页面迁移使用，禁止在业务页复制同类 UI。共享组件只承载通用表现与交互，不下沉领域规则、后端副作用或正式业务状态。
• 对已明确退役且不存在现役调用方、公开契约、持久化数据、活跃实例或迁移要求的对象，坚持“四不写”：
  1. 不写历史兼容代码。
  2. 不写用于维持退役行为的防御性兼容测试。
  3. 不写仅说明其曾存在或已删除的墓碑注释。
  4. 不写仅记录其已删除的墓碑文档；直接将权威文档更新为当前状态。
• 公开 API、持久化数据、SpacetimeDB schema、跨版本重放、活跃实例和正式迁移不适用“四不写”；必要兼容应最小化、白名单化并配套契约或迁移测试，迁移完成后同步删除兼容实现与对应测试。
• UI 面板中不要默认写功能说明、规则描述或开发解释文案；移动端优先，同时保证网页端可正常显示和操作。
• 点击按钮弹出独立面板的设计，不要实现成在当前面板下面追加内容。

任务路由

• Issue 使用自托管 Gitea；优先用 Gitea UI/API 或 tea CLI，不使用 GitHub gh 或 GitLab glab，除非仓库已迁移。默认 triage 标签：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。
• 需要仓库级 Codex skills/plugins 时，再读取 .codex/README.md。
• 涉及 AI 游戏创作独立 App、多智能体 Runtime、本地项目产物或本地 HTTP 预览时，先读取 docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md。
• 新增、补齐、迁移或重构玩法入口、玩法类型、创作工作台、生成页、结果页、发布、运行态、作品架、广场或公开 read model 前，必须读取并按 genarrative-play-type-integration 执行。
• 涉及 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 执行。
• 涉及 SpacetimeDB 的设计、实现、脚本、调试、发布、绑定生成、schema、reducer、procedure、view 或 API 时，必须先读取并按 genarrative-spacetimedb 执行。

后端红线

• 后端最新技术约束以 docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md 为准。
• 后端路线固定为 server-rs + Axum + SpacetimeDB；旧 server-node、Express、PostgreSQL、Go 服务端、maincloud / Maincloud / MAINCLOUD 只作为历史残留，不作为兼容目标。
• DDD 分层边界按总纲执行：领域规则沉到 module-*，SpacetimeDB 表和事务编排留在 spacetime-module，后端访问 SpacetimeDB 统一经 spacetime-client facade，HTTP/SSE/BFF 留在 api-server，外部副作用留在 platform-*，前后端 DTO 留在 shared-contracts。
• 前端只做表现、交互和临时 UI 状态，不承接正式业务真相，不绕过后端投影或后端 API 直接实现业务规则。
• 契约、路由、DTO 去留和 breaking change 以当前后端架构文档、server-rs/crates/api-server/src/app.rs、shared-contracts 和 packages/shared 为准；不得在前端、api-server 或临时兼容层中重新发明旧接口。
• 凡修改 /api/external/v1 的路由、HTTP 方法、请求 / 响应 DTO、请求头、状态码、鉴权或异步语义，必须在同一次变更中同步更新权威契约 docs/openapi/genarrative-external-v1.openapi.json 及对应契约测试；Rust 实现与 OpenAPI 未保持一致时任务不得视为完成。
• SpacetimeDB 已有表新增字段时，字段必须放在 Rust 表结构体最后，并设置明确默认值；需要删除、改名、重排或改类型时，必须先询问用户并确认迁移计划。
• 修改 SpacetimeDB schema 后必须同步 migration.rs、表目录和生成绑定，并运行 npm run check:spacetime-schema。
• 除 CI/CD 脚本内部受控用法外，人工命令、本地联调、排障步骤和文档示例禁止继续使用 spacetime --root-dir。

验证与提交

• 修改后按范围运行定向测试、类型检查、npm run check:encoding 和 git diff --check；后端 API smoke 使用 npm run dev:api-server 拉起后端并检查 /healthz。
• 修改 SpacetimeDB schema 后追加 npm run check:spacetime-schema；涉及发布或生产运维时按当前开发运维文档和脚本门禁执行。
• 提交代码时，提交标题必须使用中文；标题后逐行写明本次提交修改了什么，每条变更单独一行。

文档图谱

docs/
├─ README.md
├─ 【协作规范】Agent工作入口与执行准则-2026-06-22.md
├─ 【项目基线】当前产品与工程约束-2026-05-15.md
├─ 【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
├─ 【玩法创作】平台入口与玩法链路-2026-05-15.md
└─ 【开发运维】本地开发验证与生产运维-2026-05-15.md