From cd7fca4a4f3ca85512a2972da41daed680472ee4 Mon Sep 17 00:00:00 2001 From: kdletters Date: Thu, 18 Jun 2026 15:17:06 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E9=95=BF=E6=9C=9F=E9=A1=B9?= =?UTF-8?q?=E7=9B=AE=E8=AE=B0=E5=BF=86=E5=85=A5=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md 将复杂任务记忆入口固定到 docs/project-memory 项目基线与踩坑记录同步声明 .hermes 仅保存 Hermes 工具资源 决策记录新增 2026-06-18 长期记忆路径口径并标注旧 .hermes 记录为历史 --- AGENTS.md | 2 +- docs/project-memory/shared-memory/decision-log.md | 14 +++++++++++--- docs/project-memory/shared-memory/pitfalls.md | 4 ++-- docs/【项目基线】当前产品与工程约束-2026-05-15.md | 2 +- 4 files changed, 15 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 653626033..5699de822 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,12 +4,12 @@ - 本仓库的团队级项目记忆位于 [`docs/project-memory/`](docs/project-memory/)，用于在 3 名开发人员和各自本地 Agent 之间同步长期项目知识。 - [`.hermes/`](.hermes/) 只保存 Hermes 专用的仓库级工具资源，例如 skills、plugins 和启用说明，不作为项目知识库。 - 开始复杂开发任务前，除阅读本文件外，还应优先读取： - - [`.hermes/README.md`](.hermes/README.md) - [`docs/project-memory/README.md`](docs/project-memory/README.md) - [`docs/project-memory/shared-memory/project-overview.md`](docs/project-memory/shared-memory/project-overview.md) - [`docs/project-memory/shared-memory/team-conventions.md`](docs/project-memory/shared-memory/team-conventions.md) - [`docs/project-memory/shared-memory/development-workflow.md`](docs/project-memory/shared-memory/development-workflow.md) - 与任务相关的 [`docs/project-memory/shared-memory/decision-log.md`](docs/project-memory/shared-memory/decision-log.md) 和 [`docs/project-memory/shared-memory/pitfalls.md`](docs/project-memory/shared-memory/pitfalls.md) +- 仅在需要使用仓库级 Hermes skills/plugins 时，再读取 [`.hermes/README.md`](.hermes/README.md)；长期项目记忆不要从 `.hermes/` 读取。 - 如果本次任务产生长期有效的架构约定、接口变化、排障经验、开发流程或协作规则，应同步更新 `docs/project-memory/shared-memory/` 中对应文件。 - 禁止提交个人 `~/.hermes` 配置、`.env`、API Key、Token、会话记录、认证文件和本地私密路径。 - 若 `docs/project-memory/shared-memory/` 与当前代码或 `docs/` 最新文档冲突，以代码和最新 `docs/` 为准，并同步修正过期共享记忆。 diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 1424f58e5..d37951164 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -21,9 +21,17 @@ - 背景：本仓库的 SpacetimeDB 接入已固定为 `server-rs + Axum + SpacetimeDB`，本地 skill 需要从上游 SpacetimeDB `skills/` 更新到 2.5 口径，同时避免继续维护当前项目不使用的 TypeScript server/client、C# 和 Unity 专用 skill。 - 决策：`.codex/skills/` 下只保留 `spacetimedb-cli`、`spacetimedb-concepts`、`spacetimedb-rust` 三个本地 SpacetimeDB skill；删除 `spacetimedb-typescript`、`spacetimedb-csharp`、`spacetimedb-unity`。前端 / Node 侧如需处理 SpacetimeDB 订阅或绑定，按当前生成绑定、项目代码和官方文档核对，不再依赖仓库内单独 TypeScript skill。 - 影响范围：`AGENTS.md` 的 SpacetimeDB skill 清单、`.codex/skills/` 本地 skill 维护范围、后续 SpacetimeDB 设计 / CLI / Rust module 开发协作口径。 -- 验证方式：用上游 `clockworklabs/SpacetimeDB@master` 的 `skills/` 目录对照，运行本地 skill 校验、删除引用扫描、`git diff --check -- .codex/skills AGENTS.md .hermes/shared-memory/decision-log.md` 和 `npm run check:encoding`。 +- 验证方式：用上游 `clockworklabs/SpacetimeDB@master` 的 `skills/` 目录对照，运行本地 skill 校验、删除引用扫描、`git diff --check -- .codex/skills AGENTS.md docs/project-memory/shared-memory/decision-log.md` 和 `npm run check:encoding`。 - 关联文档：`AGENTS.md`、`.codex/skills/spacetimedb-cli/SKILL.md`、`.codex/skills/spacetimedb-concepts/SKILL.md`、`.codex/skills/spacetimedb-rust/SKILL.md`。 +## 2026-06-18 长期项目记忆固定读取 `docs/project-memory/` + +- 背景：项目记忆已从仓库 `.hermes/` 迁移到 `docs/project-memory/`，但部分协作说明仍把 `.hermes/` 写成共享记忆或计划容器，容易让 Agent 和开发者回到旧路径。 +- 决策：长期项目记忆、计划和 TODO 只从 `docs/project-memory/` 读取和维护；`.hermes/` 仅保存 Hermes 专用的仓库级 skills、plugins 和启用说明。`AGENTS.md` 的复杂任务阅读清单不再把 `.hermes/README.md` 放在项目记忆入口中，只有使用 Hermes 工具资源时才读取它。 +- 影响范围：`AGENTS.md`、`.hermes/README.md`、`docs/project-memory/README.md`、`docs/project-memory/shared-memory/`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。 +- 验证方式：扫描 `AGENTS.md`、当前 `docs/` 与 `.hermes/README.md`，确认当前口径不再把 `.hermes/` 描述为长期项目记忆路径。 +- 关联文档：`AGENTS.md`、`docs/project-memory/README.md`、`.hermes/README.md`。 + ## 2026-06-13 图片大图预览统一为黑底全屏查看器 - 背景：`CreativeImageInputPanel` 的参考图 / 主图预览曾使用白底 `UnifiedModal` 工具弹窗，移动端会透出原页面背景，且不能全屏查看、缩放或拖拽细节。 @@ -1785,10 +1793,10 @@ - 验证方式：VN 定向前端测试、`npm run typecheck`、`npm run check:encoding`、`cargo test -p api-server visual_novel`、`cargo test -p api-server creation_agent_document_input`。 - 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`。 -## 2026-05-04 在仓库 `.hermes/` 中建立团队共享记忆 +## 2026-05-04 历史：曾在仓库 `.hermes/` 中建立团队共享记忆 - 背景：团队有 3 名开发人员，均在各自本地安装 Hermes，并需要独立拉取仓库、修改代码、本地测试；团队希望形成共享的长期项目记忆。 -- 决策：不共享个人 `~/.hermes`，先在 Genarrative 仓库内使用 `.hermes/` 保存可 Git 同步的团队共享记忆、计划和未来 skills。 +- 决策：不共享个人 `~/.hermes`，当时先在 Genarrative 仓库内使用 `.hermes/` 保存可 Git 同步的团队共享记忆、计划和未来 skills；该路径已被 2026-06-18 的 `docs/project-memory/` 口径取代，当前不再作为长期项目记忆入口。 - 影响范围：`AGENTS.md`、`.hermes/README.md`、`docs/project-memory/shared-memory/`。 - 验证方式：任一开发者拉取仓库后，在项目根目录启动 Hermes，均可读取同一套 `docs/project-memory/shared-memory/` 文件。 - 关联文档：`.hermes/README.md`、`docs/project-memory/shared-memory/team-conventions.md`。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 0b94909cf..983c77463 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -797,11 +797,11 @@ - 验证：`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`；`npm run typecheck`。 - 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/components/match3d-result/Match3DResultView.test.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。 -## `.hermes` 只放共享内容，不放个人 Hermes 配置 +## `.hermes` 只放 Hermes 工具资源，不放项目记忆或个人配置 - 现象：团队成员误把个人 Hermes 配置、会话或密钥复制进仓库。 - 原因：仓库 `.hermes/` 与个人 `~/.hermes/` 名称相似。 -- 处理：仓库 `.hermes/` 只放 Markdown 共享记忆、计划和可公开 skills；不提交 `.env`、`config.yaml`、`sessions/`、`auth.json`。 +- 处理：仓库 `.hermes/` 只放 Hermes 专用 skills、plugins 和启用说明；团队共享记忆、计划和 TODO 统一放在 `docs/project-memory/`；不提交 `.env`、`config.yaml`、`sessions/`、`auth.json`。 - 验证：提交前检查 `git diff -- .hermes`，确认没有密钥、会话记录或个人路径敏感信息。 - 关联：`.hermes/README.md`。 diff --git a/docs/【项目基线】当前产品与工程约束-2026-05-15.md b/docs/【项目基线】当前产品与工程约束-2026-05-15.md index 310adb1da..cfdb5b030 100644 --- a/docs/【项目基线】当前产品与工程约束-2026-05-15.md +++ b/docs/【项目基线】当前产品与工程约束-2026-05-15.md @@ -122,7 +122,7 @@ server-rs + Axum + SpacetimeDB - Issue tracker 是自托管 Gitea。可用 Gitea UI/API 或 `tea` CLI；不要用 GitHub `gh` 或 GitLab `glab`。 - 默认 triage labels：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。 - 根 `CONTEXT.md` 是当前领域语言入口；架构决策以本文档和 `docs/project-memory/shared-memory/decision-log.md` 的最新稳定摘要为准。 -- `.hermes/` 只保存可进入 Git 的团队共享记忆、计划和可公开 skill，不提交个人 Hermes 配置、会话、密钥、Token 或本地私密路径。 +- `.hermes/` 只保存 Hermes 专用的仓库级工具资源，例如 skills、plugins 和启用说明；团队共享记忆、计划和 TODO 统一放在 `docs/project-memory/`，不提交个人 Hermes 配置、会话、密钥、Token 或本地私密路径。 - 每次工程修改都应同步更新本目录当前文档；如果产生长期有效知识，再同步 `docs/project-memory/shared-memory/`。 ## 当前文档策略