From 332f887c66a15fcffa2e30b2c9209ee4c98d1698 Mon Sep 17 00:00:00 2001 From: kdletters Date: Thu, 14 May 2026 15:45:25 +0800 Subject: [PATCH] docs: add shared todo plan naming rules --- .hermes/README.md | 3 +- .hermes/shared-memory/document-map.md | 3 ++ .hermes/shared-memory/team-conventions.md | 9 ++-- .hermes/todos/README.md | 15 ++++++ ...力模块化与图片资产Adapter收口计划-2026-05-14.md | 54 +++++++++++++++++++ AGENTS.md | 1 + docs/README.md | 4 ++ 7 files changed, 85 insertions(+), 4 deletions(-) create mode 100644 .hermes/todos/README.md create mode 100644 .hermes/todos/【后端架构】api-server能力模块化与图片资产Adapter收口计划-2026-05-14.md diff --git a/.hermes/README.md b/.hermes/README.md index b5cdaf6a..ac288c9f 100644 --- a/.hermes/README.md +++ b/.hermes/README.md @@ -8,6 +8,7 @@ - 不提交个人配置、API Key、会话转录、模型密钥、本地路径密钥等敏感内容。 - 个人 Hermes 的 `~/.hermes/config.yaml`、`~/.hermes/.env`、`~/.hermes/sessions/` 不应复制到本仓库。 - 开发前先阅读本目录下与任务相关的记忆文件；开发后如产生稳定知识，更新对应文档。 +- 后续新增的 Markdown 文档文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`，便于团队跨目录检索。 - 若本目录内容与 `docs/` 或代码事实冲突，以当前代码和最新 `docs/` 为准，并同步修正过期记忆。 ## 目录结构 @@ -24,6 +25,7 @@ │ ├─ pitfalls.md # 踩坑与排障记录 │ └─ handoff-template.md # 任务交接模板 ├─ plans/ # 阶段性计划与实施方案 +├─ todos/ # 已定稿但尚未执行的共享 TODO 计划 ├─ skills/ # 仓库级 Hermes skills └─ plugins/ # 仓库级 Hermes plugins（需显式启用项目 plugin） ``` @@ -89,4 +91,3 @@ HERMES_ENABLE_PROJECT_PLUGINS=1 HERMES_PLUGINS_DEBUG=1 hermes chat -q "请读取 - 大段临时聊天记录 - 尚未确认的一次性猜测 - 构建产物、日志、缓存、数据库 dump - diff --git a/.hermes/shared-memory/document-map.md b/.hermes/shared-memory/document-map.md index 409eee36..6d0285bc 100644 --- a/.hermes/shared-memory/document-map.md +++ b/.hermes/shared-memory/document-map.md @@ -30,6 +30,8 @@ - `operations/`：后台运营核查、对账和排障查询。 - `prd/`：产品需求与阶段计划。 +新增 Markdown 文档文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`。标签用于跨目录检索，不替代 `docs/` 的目录分类；历史文档不要求批量重命名。 + ## 推荐阅读顺序 通用复杂任务： @@ -96,5 +98,6 @@ RPG 创作与运行时链路： - 新增工程实现时，如果已有对应文档，必须同步更新。 - 如果没有对应文档，新文档放入 `docs/` 下合适分类。 +- 新文档文件名必须使用 `【标签名】` 前缀，标题尽量保留中文语义，日期使用 `YYYY-MM-DD`。 - `.hermes/shared-memory/` 只保留跨任务、跨成员、高频使用的摘要和索引。 - 如果文档与代码冲突，先确认代码事实，再更新过期文档和共享记忆。 diff --git a/.hermes/shared-memory/team-conventions.md b/.hermes/shared-memory/team-conventions.md index 3c3cc18f..dbb357a4 100644 --- a/.hermes/shared-memory/team-conventions.md +++ b/.hermes/shared-memory/team-conventions.md @@ -15,6 +15,7 @@ - `.hermes/shared-memory/` 团队级长期记忆 - `.hermes/plans/` 阶段性实施计划 +- `.hermes/todos/` 已确定需要执行、但尚未进入实施的共享 TODO 计划 - `.hermes/skills/` 未来可复用仓库级 skills - `docs/` 中 PRD、设计、技术、经验、审计、查询手册 - `AGENTS.md` 项目级 Agent 约束 @@ -41,6 +42,7 @@ - 保持修改范围聚焦，不做无关重构。 - 复用、修改、扩展现有系统优先，避免新建重复系统或页面。 +- 新增 Markdown 文档时，文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`；只在任务需要时重命名历史文档，避免无关大 diff。 - 涉及中文文本时注意 UTF-8 编码和乱码排查。 - 涉及后端时遵循 DDD 分层，不把业务真相下沉到前端或临时兼容层。 - `maincloud` / `Maincloud` / `MAINCLOUD` 相关代码、脚本、测试、环境变量、命令和文档要求均视为历史残留，禁止新增、运行或引用；API smoke 统一使用 `npm run api-server` 与 `/healthz`。 @@ -51,9 +53,10 @@ 1. 运行与修改范围匹配的测试或验证命令。 2. 更新相关 `docs/` 文档。 -3. 若产生长期有效知识，更新 `.hermes/shared-memory/`。 -4. 若形成可复用流程，考虑沉淀到 `.hermes/skills/`。 -5. 在提交信息中区分代码变更与文档/记忆变更。 +3. 新增或沉淀 Markdown 文档时，确认文件名已使用 `【标签名】` 前缀。 +4. 若产生长期有效知识，更新 `.hermes/shared-memory/`。 +5. 若形成可复用流程，考虑沉淀到 `.hermes/skills/`。 +6. 在提交信息中区分代码变更与文档/记忆变更。 ## 文档阅读顺序 diff --git a/.hermes/todos/README.md b/.hermes/todos/README.md new file mode 100644 index 00000000..04a11d76 --- /dev/null +++ b/.hermes/todos/README.md @@ -0,0 +1,15 @@ +# 项目共享 TODO 计划 + +本目录用于存放已经讨论定稿、需要后续执行，但当前尚未实施的项目级计划文档。 + +## 使用规则 + +- 每个 TODO 计划单独一个 Markdown 文件，文件名优先使用可检索的中文标题与日期。 +- 每个 TODO 计划文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`。 +- 计划内容必须足够明确，后续开发者可以直接据此开始实施。 +- 已执行完成的计划应迁移到对应 `docs/` 技术/规划文档，或在本文档中标记完成并移出 TODO 队列。 +- 不在这里保存个人私密路径、密钥、临时聊天记录或未确认猜测。 + +## 当前待执行 + +- [【后端架构】api-server 能力模块化与图片资产 Adapter 收口计划](./【后端架构】api-server能力模块化与图片资产Adapter收口计划-2026-05-14.md) diff --git a/.hermes/todos/【后端架构】api-server能力模块化与图片资产Adapter收口计划-2026-05-14.md b/.hermes/todos/【后端架构】api-server能力模块化与图片资产Adapter收口计划-2026-05-14.md new file mode 100644 index 00000000..e076e786 --- /dev/null +++ b/.hermes/todos/【后端架构】api-server能力模块化与图片资产Adapter收口计划-2026-05-14.md @@ -0,0 +1,54 @@ +# api-server 能力模块化与图片资产 Adapter 收口计划 + +状态：待执行 + +## Summary + +把两份计划合并成一个分阶段重构：先把 `api-server` 从扁平 `src/*.rs` 收成按能力组织的 Module + Router 结构；同时把散落在玩法 handler 里的“图片生成 -> 下载 -> OSS 写入/head -> asset_object 确认 -> entity binding”收成 `generated_image_assets` 深 Module。 + +本轮不改变 HTTP contract、DTO、前端行为、SpacetimeDB schema 或计费语义。 + +## Key Changes + +- 新增 `server-rs/crates/api-server/src/modules/`，每个能力 Module 暴露 `router(state) -> Router`，`app.rs` 只负责全局 middleware 和 `.merge(...)`。 +- 能力分组建议：`admin`、`auth`、`assets`、`creation`、`runtime`、`platform`，核心基础设施继续保留在根层或 `core`。 +- 在 `modules/assets/generated_image_assets` 新增内部 Adapter Module，Interface 固定为“生成并入库”： + - 输入包含 provider、prompt、size、参考图、OSS 路径、asset kind、entity kind/id、slot、owner/profile/source_job_id。 + - 输出包含 `asset_object_id`、`legacy_public_path`、`object_key`、mime/extension、task_id/actual_prompt。 +- `asset_billing.rs` 不改语义；调用方继续在外层显式包 `execute_billable_asset_operation*`，图片 Adapter 不读写钱包。 +- 首批迁移稳定单图链路：Big Fish 正式图片、Square Hole 图片、Custom World 场景图/封面类图片入库路径。 +- 暂不迁移 Puzzle VectorEngine edits/multipart、Match3D 5x5 sheet/切图/绿幕后处理，以及音频、视频、GLB 转存链路。 + +## Implementation Notes + +- `generated_image_assets` 内部集中处理 OSS 缺配置、下载图片 mime/extension 归一、空内容/上游错误映射、`put_object -> head_object -> confirm_asset_object -> bind_asset_object_to_entity`。 +- 调用方玩法文件只保留领域上下文拼装、prompt 构造、计费包裹和响应映射。 +- `openai_image_generation.rs` 继续保留底层 VectorEngine 能力；本轮只让新 Adapter 封装“provider 结果 + OSS/asset_object 持久化”的更深 Interface。 +- 第一阶段不拆 `match3d.rs`、`puzzle.rs`、`custom_world.rs` 等超大 handler 内部实现；后续再单独切第二阶段。 + +## Docs + +- 新增或更新 `server-rs/crates/api-server/README.md`，说明能力 Module 目录规则、Router 暴露规则和 Adapter 边界。 +- 新增 `docs/technical` 说明，并挂到 `docs/technical/README.md`。 +- 文档明确：`api-server` 仍是 HTTP/SSE/BFF Adapter 与平台编排层，不承接领域规则主逻辑。 + +## Test Plan + +- 结构与路由回归： + - `cargo check -p api-server --manifest-path server-rs/Cargo.toml` + - `cargo test -p api-server --manifest-path server-rs/Cargo.toml` + - `npm run check:server-rs-ddd` + - `npm run check:encoding` + - `git diff --check` +- 图片 Adapter 单测覆盖 OSS 缺配置、asset object/binding 输入构造、URL/base64 结果归一、上游错误和空图片内容映射。 +- 迁移点回归： + - `cargo test -p api-server big_fish --manifest-path server-rs/Cargo.toml` + - `cargo test -p api-server square_hole --manifest-path server-rs/Cargo.toml` + - `cargo test -p api-server custom_world --manifest-path server-rs/Cargo.toml` +- API smoke 使用 `npm run api-server` 并检查 `/healthz`；不使用 `api-server:maincloud`。 + +## Assumptions + +- 本轮目标是提升 locality、降低重复和减少 `app.rs` 路由树压力。 +- `generated_image_assets` 先留在 `api-server` 内部，不新增 workspace crate。 +- Match3D、Puzzle 的复杂图片链路作为第二阶段迁移，不阻塞第一阶段收口。 diff --git a/AGENTS.md b/AGENTS.md index 6970172b..4a13fb06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,7 @@ Single-context layout: read root `CONTEXT.md` when present and architecture deci - 代码需要有完善的中文注释 - 在落地工程修改前检查是否有详细指导本次落地的文档，若没有文档或文档的完善程度仍有落地过程中编码级别的歧义优先优化文档后落地工程迭代。 - 对工程的修改不仅要落地到代码更面，还要更改对应文档，若没有生成新的文档，文档统一存在doc目录中 +- 后续新增的 Markdown 文档文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`；例如 `【后端架构】api-server能力模块化与图片资产Adapter收口计划-2026-05-14.md`。不要求批量重命名历史文档，除非本次任务明确涉及该文档。 - 不要擅自把现有中文文案、注释、剧情、文档改写成英文，除非用户明确要求翻译。 - 看到中文乱码时，不要直接沿用乱码文本，也不要用英文替换；先确认文件真实编码，再决定是否修改。 - 在 PowerShell 5.1 中读取或写入文本时，必须显式使用 UTF-8；如果终端输出疑似乱码，要用 `Get-Content -Encoding UTF8`、Python 或 Node 再次核对原文。 diff --git a/docs/README.md b/docs/README.md index 7ead8697..4b9a3b5f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -49,3 +49,7 @@ AI 文字游戏模板接入以 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_ - `reference/`：偏目录、速查、检索辅助。 - `tracking/`：偏埋点原始事实和聚合投影查询，不放任务进度或钱包对账。 - `operations/`：偏后台运营核查、对账和排障查询。 + +## 文档命名规则 + +后续新增的 Markdown 文档文件名必须以分类标签开头，格式为 `【标签名】中文标题-日期.md`。标签用于跨目录检索，不替代上面的目录分类；历史文档不要求批量重命名，除非本次任务明确涉及该文档。