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
@@ -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、源码和当前专题文档

 ## 共享记忆更新准则