7.3 KiB
Agent 工作入口与执行准则
更新时间：2026-06-22
文档定位
本文件承接 AGENTS.md 中不适合塞在入口页里的执行细则。AGENTS.md 是最高优先级入口，本文件是复杂任务的默认操作手册；如果本文件与代码、最新 docs/ 或项目共享记忆冲突，以当前代码和最新 docs/ 为准，并同步修正文档。
阅读顺序
简单自包含任务可以直接执行。复杂开发、跨模块修改、后端 / UI / 文档体系调整前，按这个顺序读：
AGENTS.md- 本文件
docs/project-memory/README.mddocs/project-memory/shared-memory/project-overview.mddocs/project-memory/shared-memory/team-conventions.mddocs/project-memory/shared-memory/development-workflow.md- 与任务相关的
decision-log.md、pitfalls.md、docs/README.md和专题文档
如果已有文档不能精确指导字段、契约、页面状态、资产链路、迁移或验收命令，先补文档再编码。
信息来源边界
docs/：当前 PRD、架构、开发运维、设计和测试口径。docs/project-memory/shared-memory/：长期团队记忆、决策、流程和踩坑摘要。.hermes/：Hermes 工具资源，不作为项目知识库。.codex/skills/：Codex 可复用技能；只在任务命中时读取。scripts/rag/：Agent 本地检索入口，只提供候选上下文。
RAG 默认不安装运行时依赖，也不把 LanceDB、Transformers.js 或本地 embedding 模型写入根 package.json。需要启用时，先询问用户；用户确认后只安装到 gitignored 的 .rag/runtime/，模型缓存和向量库留在 .rag/。
执行风格
- 修改范围保持聚焦，不做无关重构。
- 优先复用现有系统、页面、组件、脚本、DTO 和文档位置。
- 不新增平行入口、平行作品架、平行公开列表、平行业务真相或临时兼容层。
- 不把前端临时状态当正式业务事实；正式状态以后端投影、后端 API 或当前架构文档为准。
- 涉及中文内容时保持中文，不擅自翻译成英文。
- 发现中文乱码时先确认真实编码，不直接沿用乱码，也不用英文替换。
- 含中文文件优先局部补丁；非必要不要整文件重写。
- 阶段性大任务完成后，整理当前上下文、剩余风险和下一步入口，降低后续接手噪音。
文档规则
- 工程修改必须同步更新对应
docs/文档。 - 没有合适文档时，新文档放入
docs/下合适位置，文件名使用【标签名】中文标题-日期.md。 - PRD 或技术方案要具体到能指导编码，不写会导致落地漂移的泛泛描述。
- 长期有效的架构约定、接口变化、排障经验、开发流程或协作规则写入
docs/project-memory/shared-memory/。 - 阶段性计划放入
docs/project-memory/plans/；确定但未实施的共享 TODO 放入docs/project-memory/todos/。 - 不提交个人配置、密钥、Token、Cookie、会话记录、认证文件、本地私密路径、构建产物、日志、缓存和数据库 dump。
UI 与前端规则
- UI 面板保持清爽，不默认写功能说明、规则说明、键盘快捷键说明或开发解释文本。
- 移动端优先，同时保证桌面端体验完整。
- 弹出独立面板的交互使用弹窗、抽屉、popover 或页面级 portal，不在当前面板下面追加内容。
- 页面展示以后端返回状态为准，不在前端自行计算结论型业务状态。
- 创作入口事实源来自 SpacetimeDB，经
/api/creation-entry/config下发；前端只做展示派生。 - 优先扩展现有公共组件，例如平台弹窗、图片输入、媒体预览、状态提示和动作按钮，不在业务页复制通用逻辑。
后端与数据真相
- 后端路线固定为
server-rs + Axum + SpacetimeDB。 - 旧
server-node、Express、PostgreSQL、Go 服务端、maincloud相关脚本、环境变量、测试和文档要求均为历史残留。 - 领域规则沉到
module-*；SpacetimeDB 表、reducer、procedure、事务 adapter 和 row mapper 留在spacetime-module。 - 后端访问 SpacetimeDB 统一经
spacetime-clientfacade。 - HTTP / SSE / BFF 和外部副作用编排留在
api-server；OSS、LLM、认证、语音等外部平台能力留在platform-*。 - 前后端 DTO、公开契约和跨页面复用的无业务真相 TypeScript 代码留在
shared-contracts/packages/shared；共享 UI 组件与纯工具可留在packages/shared，但领域规则、后端副作用和正式状态不得下沉。 - 契约、路由、DTO 去留和 breaking change 以当前后端架构文档、
api-server/src/app.rs、shared-contracts和packages/shared为准。
后端修改后按当前 DDD 文档执行验收。涉及 API smoke 时，使用 npm run dev:api-server 重新拉起后端并检查 /healthz；不要使用旧 maincloud 启动口径。
SpacetimeDB 规则
涉及 SpacetimeDB 设计、实现、脚本、调试、发布、绑定生成、schema、reducer、procedure、view 或 Rust API 时，先读取对应 skill：
.codex/skills/spacetimedb-cli/SKILL.md.codex/skills/spacetimedb-rust/SKILL.md.codex/skills/spacetimedb-concepts/SKILL.md
已有表新增字段时，字段必须放在 Rust 表结构体最后，并设置明确默认值。删除、改名、重排或改类型前必须先询问用户并确认迁移计划。
修改 schema 后必须同步：
server-rs/crates/spacetime-module/src/migration.rs- 表目录 / 数据契约文档
- 生成绑定
npm run check:spacetime-schema
人工命令、本地联调、排障步骤和文档示例禁止继续使用 spacetime --root-dir；本地数据隔离使用项目脚本或 --data-dir，发布目标显式传 --server / --server-url。
技能路由
- 新增、补齐、迁移或重构玩法入口、玩法类型、创作工作台、生成页、结果页、发布、运行态、作品架、广场或公开 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/当工具目录。
Issue 与提交
- Issue 使用自托管 Gitea；优先使用 Gitea UI/API 或
teaCLI。 - 默认 triage 标签：
needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。 - 提交标题必须使用中文；标题后逐行写明本次提交修改了什么，每条变更单独一行。
- 提交前检查 staged diff，避免把无关文件、密钥、本地配置或用户未要求的改动带进去。
默认验证
按修改范围选择验证，不追求无意义全量扫：
- 文档 / 中文文本：
npm run check:encoding、git diff --check - 前端：定向测试、
npm run typecheck、必要的页面交互 smoke 和移动端视口检查 - 后端：对应 crate 的
cargo test/cargo check、API smoke、/healthz - SpacetimeDB schema：
npm run check:spacetime-schema - 发布 / 运维：当前开发运维文档中的脚本门禁、host 侧进程和公开端点验证
如果无法运行某项验证，最终说明要写清原因、风险和已经完成的替代检查。