Add Agent execution guidelines & trim AGENTS.md

Introduce a new detailed Agent handbook (docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md) and refactor AGENTS.md to be an entry-only navigation page. Update documentation cross-references (docs/README.md, project-memory README, document-map, team-conventions, development-workflow, decision-log and project-overview) to point to the new file and clarify reading/order rules, submission/validation constraints, and SpacetimeDB/back-end wording. Also adjust image canvas generation placement rules in the frontend doc and apply related changes to image-editor hooks/tests (src/components/image-editor/*). Purpose: separate high-level entry rules from complex execution details to reduce startup cost for complex tasks and centralize execution practices in a single guideline document.
2026-06-22 21:44:07 +08:00
parent 1e3a68a459
commit dfd567fe2c
14 changed files with 307 additions and 111 deletions
@@ -1,9 +1,10 @@
 # 文档总览

-`docs/` 现在按主题拆成了 6 类；旧后端路线文档开始聚合和删除，后续实现以 Rust / SpacetimeDB 当前基线为准。
+`docs/` 现在按主题维护项目当前口径；旧后端路线文档开始聚合和删除，后续实现以 Rust / SpacetimeDB 当前基线为准。

 ## 快速入口

+- [Agent 工作入口与执行准则](./%E3%80%90%E5%8D%8F%E4%BD%9C%E8%A7%84%E8%8C%83%E3%80%91Agent%E5%B7%A5%E4%BD%9C%E5%85%A5%E5%8F%A3%E4%B8%8E%E6%89%A7%E8%A1%8C%E5%87%86%E5%88%99-2026-06-22.md)：复杂任务前的 Agent 阅读顺序、执行边界、技能路由、文档规则和验证口径。
 - [经验沉淀](./experience/README.md)：项目开发经验、UI 交接、历史实现经验。
 - [审计与复盘](./audits/README.md)：工程审查、文本/乱码审计、专项落地审计。
 - [系统设计](./design/README.md)：玩法、关系、物品与对话设计。
@@ -21,7 +21,7 @@ docs/project-memory/

 ## 使用原则

- 开发前先读 `AGENTS.md`，再按任务读取 `docs/project-memory/shared-memory/` 和当前 `docs/` 文档。
+- 开发前先读 `AGENTS.md`；复杂任务继续读取 `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`，再按任务读取 `docs/project-memory/shared-memory/` 和当前 `docs/` 文档。
 - 长期有效的架构约定、接口变化、排障经验、开发流程和协作规则写入 `shared-memory/`。
 - 阶段性计划写入 `plans/`，已确定但暂未实施的共享 TODO 写入 `todos/`。
 - 如果本目录内容与代码或最新 `docs/` 冲突，以代码和最新 `docs/` 为准，并同步修正过期记忆。
@@ -24,6 +24,14 @@
 - 验证方式：运行 `editor_generation_config`、公开定价路由、图标素材价格校验、图片画布定价模型和后台定价页相关测试。
 - 关联文档：`docs/【编辑器】模型定价配置管理方案-2026-06-22.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。

+## 2026-06-22 AGENTS.md 收敛为入口导航
+
+- 背景：`AGENTS.md` 同时承载项目记忆、RAG、Issue、UI、Git、后端、SpacetimeDB 和文档图谱等细则，入口过重，复杂任务启动成本高。
+- 决策：`AGENTS.md` 只保留最高优先级规则、任务路由、后端红线、验证提交要求和文档图谱；新增 `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md` 承接完整执行细则。复杂任务阅读顺序固定为 `AGENTS.md` -> Agent 执行准则 -> `docs/project-memory/` -> `docs/README.md` 和专题文档。
+- 影响范围：`AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`、`docs/README.md`、`docs/project-memory/README.md` 和共享记忆索引。
+- 验证方式：执行 `npm run check:encoding`、`git diff --check`，并检查入口文档不再重复承载专题细则。
+- 关联文档：`AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`。
+
 ## 2026-06-22 图片画布角色动作主媒体改为透明序列帧

 - 背景：角色动作生成后端已经在视频生成后抽取透明 PNG 帧并完成绿幕去背；画板继续把 `previewVideoPath` 当主媒体会让用户看到未扣绿幕视频，下载也拿不到可直接用于游戏素材的帧序列。
@@ -5,7 +5,7 @@
 ## 标准任务流程

 ```text
-同步代码 → 读取 AGENTS.md → 读取 docs/project-memory/shared-memory → 查找/完善 docs → 制定计划 → 小步实现 → 本地验证 → 更新文档/记忆 → 提交
+同步代码 → 读取 AGENTS.md → 复杂任务读取 Agent 执行准则 → 读取 docs/project-memory/shared-memory → 查找/完善 docs → 制定计划 → 小步实现 → 本地验证 → 更新文档/记忆 → 提交
 ```

 ## 建议启动方式
@@ -30,6 +30,7 @@ hermes
 - [ ] 当前分支是否正确
 - [ ] 是否已拉取最新代码
 - [ ] 是否阅读 `AGENTS.md`
+- [ ] 复杂任务是否阅读 `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`
 - [ ] 是否阅读 `docs/project-memory/shared-memory/` 相关文件
 - [ ] 是否阅读 `README.md` 中的运行和检查命令
 - [ ] 是否阅读 `docs/README.md` 及任务相关分类 README
@@ -294,7 +295,7 @@ npm run check:server-rs-ddd

 ```text
 请检查当前 git diff，指出：
-1. 是否违反 AGENTS.md 或 docs/project-memory/shared-memory 约定；
+1. 是否违反 AGENTS.md、Agent 执行准则或 docs/project-memory/shared-memory 约定；
 2. 是否需要补充 docs；
 3. 是否有长期知识需要写入 docs/project-memory/shared-memory；
 4. 建议的测试命令和提交信息。
@@ -1,12 +1,13 @@
 # 文档地图与阅读索引

-更新时间：`2026-05-15`
+更新时间：`2026-06-22`

 ## 当前文档入口

 | 场景 | 优先阅读 |
 | --- | --- |
 | 建立项目背景 | `README.md`、`AGENTS.md`、`docs/project-memory/shared-memory/project-overview.md` |
+| Agent 复杂任务执行规则 | `AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md` |
 | 找当前文档 | `docs/README.md` |
 | 产品、命名、UI、协作和废弃路线 | `docs/【项目基线】当前产品与工程约束-2026-05-15.md` |
 | 后端、DDD、API、SpacetimeDB schema 和表目录 | `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` |
@@ -22,9 +23,10 @@
 通用复杂任务：

 1. `AGENTS.md`
-2. `docs/project-memory/shared-memory/`
-3. `docs/README.md`
-4. 与任务匹配的当前融合文档
+2. `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`
+3. `docs/project-memory/shared-memory/`
+4. `docs/README.md`
+5. 与任务匹配的当前融合文档

 后端 / 数据真相 / SpacetimeDB：

@@ -48,6 +50,7 @@
 ## 维护规则

 - 当前 `docs/` 只保留少量融合文档。
+- `AGENTS.md` 只保留最高优先级入口；Agent 执行细则优先沉到 `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md` 或对应专题文档。
 - 新增工程实现时，如果已有对应当前文档，必须同步更新。
 - 如果没有合适位置，新文档文件名必须使用 `【标签名】中文标题-YYYY-MM-DD.md`。
 - 阶段性流水账、一次性修复记录和已关闭实验不要再新增为长期文档。
@@ -51,6 +51,7 @@ server-rs + Axum + SpacetimeDB
 ## 当前文档入口

 - `docs/README.md`
+- `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`
 - `docs/【项目基线】当前产品与工程约束-2026-05-15.md`
 - `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`
 - `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`
@@ -19,6 +19,7 @@
 - `.hermes/skills/` Hermes 专用仓库级 skills
 - `docs/` 中 PRD、设计、技术、经验、审计、查询手册
 - `AGENTS.md` 项目级 Agent 约束
+- `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md` Agent 执行细则

 禁止提交：

@@ -33,10 +34,11 @@

 1. 拉取最新代码。
 2. 阅读 `AGENTS.md`。
-3. 阅读 `docs/project-memory/shared-memory/` 中与任务相关的文件。
-4. 阅读 `docs/README.md` 和任务相关分类 README。
-5. 阅读对应 PRD、设计、技术、经验或审计文档。
-6. 如果文档不足以指导编码，先补充或修正文档。
+3. 复杂任务阅读 `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`。
+4. 阅读 `docs/project-memory/shared-memory/` 中与任务相关的文件。
+5. 阅读 `docs/README.md` 和任务相关分类 README。
+6. 阅读对应 PRD、设计、技术、经验或审计文档。
+7. 如果文档不足以指导编码，先补充或修正文档。

 ## 开发中

@@ -64,21 +66,16 @@

 1. `README.md`
 2. `AGENTS.md`
-3. `docs/project-memory/shared-memory/`
-4. `docs/README.md`
-5. `docs/experience/README.md`
-6. `docs/audits/README.md`
-7. 任务所属分类：`docs/design/`、`docs/technical/`、`docs/planning/`、`docs/prd/`、`docs/reference/`、`docs/tracking/`、`docs/operations/`
+3. `docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`
+4. `docs/project-memory/shared-memory/`
+5. `docs/README.md`
+6. 任务所属分类：`docs/design/`、`docs/technical/`、`docs/planning/`、`docs/prd/`、`docs/reference/`、`docs/tracking/`、`docs/operations/`

 后端任务建议：

-1. `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`
-2. `docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md`
-3. `docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`
-4. `docs/technical/SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md`
-5. `docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`
-6. `docs/technical/SPACETIMEDB_TABLE_CATALOG.md`
-7. `docs/technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md`
+1. `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`
+2. `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`
+3. 任务相关 crate README、源码和当前专题文档

 ## 共享记忆更新准则

@@ -0,0 +1,116 @@
+# Agent 工作入口与执行准则
+
+更新时间：`2026-06-22`
+
+## 文档定位
+
+本文件承接 `AGENTS.md` 中不适合塞在入口页里的执行细则。`AGENTS.md` 是最高优先级入口，本文件是复杂任务的默认操作手册；如果本文件与代码、最新 `docs/` 或项目共享记忆冲突，以当前代码和最新 `docs/` 为准，并同步修正文档。
+
+## 阅读顺序
+
+简单自包含任务可以直接执行。复杂开发、跨模块修改、后端 / UI / 文档体系调整前，按这个顺序读：
+
+1. `AGENTS.md`
+2. 本文件
+3. `docs/project-memory/README.md`
+4. `docs/project-memory/shared-memory/project-overview.md`
+5. `docs/project-memory/shared-memory/team-conventions.md`
+6. `docs/project-memory/shared-memory/development-workflow.md`
+7. 与任务相关的 `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-client` facade。
+- HTTP / SSE / BFF 和外部副作用编排留在 `api-server`；OSS、LLM、认证、语音等外部平台能力留在 `platform-*`。
+- 前后端 DTO 和公开契约留在 `shared-contracts` / `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 或 `tea` CLI。
+- 默认 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 侧进程和公开端点验证
+
+如果无法运行某项验证，最终说明要写清原因、风险和已经完成的替代检查。
@@ -97,7 +97,7 @@
 - 图片类待生成占位尺寸必须与面板当前比例和尺寸同步：普通图片、角色形象、图标素材、UI 设计图按当前 `aspectRatio + imageSize` 计算像素尺寸；生成规范固定为 `16:9·2K`，占位为 `2048 x 1152`；宣发素材按 workflow 输出尺寸创建占位。
 - 视频待生成占位必须与面板当前比例和清晰度同步：默认 `16:9 · 480p` 为 `854 x 480`，切换比例、`720p` 或 `1080p` 后按比例和清晰度重算偶数宽度；调整参数时保持占位中心点不变。
 - 面板中用户修改比例、尺寸或清晰度后，已有空白待生成占位立即同步更新 `width / height / originalWidth / originalHeight`，且保持中心点不跳动。
- 快速编辑点击生成后不在原图上播放生成中遮罩，而是立即创建独立 `Quick Edit Generator` 画布生成占位并播放生成中动画；生成成功后结果落在该占位框位置，失败时占位标记失败并恢复快速编辑面板。
+- 快速编辑点击生成后不在原图上播放生成中遮罩，而是立即创建独立 `Quick Edit Generator` 画布生成占位并播放生成中动画；该占位必须复用新建图片的 placement 避让逻辑，和已有素材 / 生成占位至少保留 32px 画布间距，不允许固定放到原图右侧后压住其它素材；生成成功后结果落在该占位框位置，失败时占位标记失败并恢复快速编辑面板。

 ## 画布悬浮信息