From 56ae43f6d32baf8ee9c0b31fc09108daf12853fe Mon Sep 17 00:00:00 2001 From: SkyJourney Date: Tue, 25 Aug 2026 15:39:31 +0800 Subject: [PATCH] =?UTF-8?q?feat(hermes):=20=E6=96=B0=E5=A2=9E=20Hermes=20A?= =?UTF-8?q?gent=20=E6=8F=92=E4=BB=B6=E5=B8=82=E5=9C=BA=E6=94=AF=E6=8C=81?= =?UTF-8?q?=EF=BC=8C=E5=90=AB=E7=8B=AC=E7=AB=8B=20memcore-hermes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - huanxi/huanxi-admin/obsidian/zentao 新增裸 plugin.json（Agent Plugins v1.0.0 标准），复用同一份 skills/ - 凭证类插件不打包 mcp.json（规范禁止内嵌密钥），改为 README 里的 ~/.hermes/config.yaml 手动配置指引 - memcore-hermes：记忆目录复用优先级 .claude/memory → .codex/memory → 新建 .agents/memory，显式规避与 Hermes 原生全局 MEMORY.md/USER.md 重复记录 - 后续将追加 packs/*.yaml（hermes plugins pack install 用），需要本次 commit 的 SHA Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_015D4xWG3gRWkUKJDgyvtyJw --- .claude/memory/MEMORY.md | 4 +- .claude/memory/decisions.md | 12 + .claude/memory/project_overview.md | 18 +- CLAUDE.md | 19 +- README.md | 70 +++- plugins/huanxi-admin/plugin.json | 11 + plugins/huanxi/plugin.json | 11 + plugins/memcore-hermes/plugin.json | 11 + .../skills/memcore-shared/SKILL.md | 86 +++++ .../skills/memory-lint/SKILL.md | 304 ++++++++++++++++++ .../skills/memory-sync/SKILL.md | 160 +++++++++ .../skills/memory-update/SKILL.md | 199 ++++++++++++ plugins/obsidian/plugin.json | 11 + plugins/zentao/plugin.json | 11 + 14 files changed, 903 insertions(+), 24 deletions(-) create mode 100644 plugins/huanxi-admin/plugin.json create mode 100644 plugins/huanxi/plugin.json create mode 100644 plugins/memcore-hermes/plugin.json create mode 100644 plugins/memcore-hermes/skills/memcore-shared/SKILL.md create mode 100644 plugins/memcore-hermes/skills/memory-lint/SKILL.md create mode 100644 plugins/memcore-hermes/skills/memory-sync/SKILL.md create mode 100644 plugins/memcore-hermes/skills/memory-update/SKILL.md create mode 100644 plugins/obsidian/plugin.json create mode 100644 plugins/zentao/plugin.json diff --git a/.claude/memory/MEMORY.md b/.claude/memory/MEMORY.md index ae19aff..a041966 100644 --- a/.claude/memory/MEMORY.md +++ b/.claude/memory/MEMORY.md @@ -3,7 +3,7 @@ | 文件 | 描述 | 类型 | 引用 | Commit | |------|------|------|------|--------| -| decisions.md | 关键架构决策：无版本号/userConfig/Bearer Token/SKILL.md规范/路径锁定/memcore三项优化/memcore-shared共享层/lint_report保活/Base commit兜底/obsidian社区对标审查/memory-lint速度分档过期检测/Codex插件骨架与memcore-codex独立目录/Codex侧bearer_token_env_var/不做Antigravity兼容/zentao-mcp网桥双认证格式兼容 | project | 3* | 9d9e31c | -| project_overview.md | 项目定位、目录结构、插件规范、发布流程（huanxi/huanxi-admin/memcore/obsidian/zentao，均含 Codex 支持情况） | project | 2 | 9d9e31c | +| decisions.md | 关键架构决策：无版本号/userConfig/Bearer Token/SKILL.md规范/路径锁定/memcore三项优化/memcore-shared共享层/lint_report保活/Base commit兜底/obsidian社区对标审查/memory-lint速度分档过期检测/Codex插件骨架与memcore-codex独立目录/Codex侧bearer_token_env_var/不做Antigravity兼容/zentao-mcp网桥双认证格式兼容/Hermes插件骨架与packs选装 | project | 3* | 待commit | +| project_overview.md | 项目定位、目录结构、插件规范、发布流程（huanxi/huanxi-admin/memcore/obsidian/zentao，均含 Codex + Hermes 支持情况） | project | 2 | 待commit | | feedback_plugin_dev.md | 插件开发协作规范：同步四处/路径解析/工具签名对照/MCP docstring单一真相/签名变更全量扫描 | feedback | 2 | 38beecb | | lint_report.md | memory-lint 最新执行结果 | lint | 0 | a64c646 | diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index af992b7..7de3e86 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -222,3 +222,15 @@ commit: 9d9e31c **How to apply**：zentao 插件的 Claude/Codex 双端 Token 配置模式确认与 huanxi 一致（[[decisions.md#huanxi plugin 使用 userConfig 而非环境变量传 Token]] + [[decisions.md#Codex 侧 MCP Token 用 bearer_token_env_var，不用 ${VAR} 模板（2026-08-22）]]），无需为 zentao 网桥单独定制认证适配。未来若网桥做重大改版，需重新确认这条双格式兼容性是否还成立。 **See Also**：[[project_overview.md#已发布插件]] + +--- + +## Hermes 插件骨架：Agent Plugins v1 + packs 选装（2026-08-25） + +**结论**：huanxi/huanxi-admin/obsidian/zentao 在插件根目录新增裸 `plugin.json`（[Agent Plugins v1.0.0](https://agent-plugins.org/) 标准，字段仅 `$schema`+`name`+可选元数据），复用同一份 `skills/`；`memcore` 因架构差异走独立目录 `plugins/memcore-hermes/`（记忆目录优先级 `.claude/memory` → `.codex/memory` → 新建 `.agents/memory`，且显式提醒 Hermes 自己按 profile 隔离的全局 `~/.hermes/memories/` 不是项目记忆后端）。分发不走 `hermes plugins install owner/repo`（该命令按文档examples只支持整仓库=一个插件包），改用 `packs/.yaml` + `hermes plugins pack install`（pack manifest 的 `subdir` 字段官方支持 monorepo 定位）。 + +**Why**：调研过程中依次排除了三条路径——① `hermes plugins install owner/repo` 无 subdir 支持（用户质疑"仓库多插件不合理"后深挖才找到 pack 机制，此前调研不够）；② 自建 `plugins.index_url` 覆盖官方社区索引会让用户暂时搜不到 NousResearch 官方索引里的插件，属单值配置非叠加，用户认为代价太大；③ 最终定为每插件一个 `packs/.yaml`，互不影响、无副作用。凭证类插件不打包 `mcp.json` 是因为 Agent Plugins v1 规范明文禁止内嵌密钥（headers/env 都不行），Hermes 原生 `~/.hermes/config.yaml` 支持 `${VAR}` 插值，改为 README 手动配置指引，用户体验类比 Codex 桌面应用的 `launchctl setenv` 变通方案。 + +**How to apply**：Hermes 的 `ref` 字段要求精确 40 位 commit SHA、不接受分支名，`packs/*.yaml` 需要在每次相关内容发布后手动 bump（不像 Claude Code 的 git SHA 自动追新）。两处未经真实 Hermes 验证的点（`pack install` 是否支持直接传 http(s) 链接、`subdir` 定位的目录只有 `plugin.json` 没有原生 `plugin.yaml` 时能否被正确安装）已在 README 里标注为待用户实测项，反馈后再回来更新文档措辞。 + +**See Also**：[[project_overview.md#已发布插件]] diff --git a/.claude/memory/project_overview.md b/.claude/memory/project_overview.md index a6f8d58..6cf1b45 100644 --- a/.claude/memory/project_overview.md +++ b/.claude/memory/project_overview.md @@ -58,17 +58,17 @@ description: "触发描述（用户实际口语，不用内部视角）" ## 已发布插件 -| 插件 | 技能 | 特性 | Codex 支持 | -|------|------|------|------| -| `huanxi` | 个人端 7 个（report/leader/task/issue/meeting/lookup/shared） | userConfig Bearer Token（hxp_）+ MCP Server（URL 走 office 子域，无端口） | ✅ `.codex-plugin/plugin.json` 共用同一 `skills/`，Token 走环境变量 `HUANXI_TOKEN`（`bearer_token_env_var`） | -| `huanxi-admin` | 管理端 4 个（admin-report/admin-module/admin-ops/admin-shared） | userConfig Bearer Token（hxa_）+ MCP Server；普通员工无需安装，2026-08-21 v1.0.0 生产切换后首次发布 | ✅ 同上模式，Token 环境变量 `HUANXI_ADMIN_TOKEN` | -| `memcore` | Claude 版 4 个（memory-sync/lint/update/shared） | 纯技能，无 MCP；memcore-shared 作内部 include（路径锁定 + 阈值常量 + PROJECT_DIR 解析），支持 synonyms.md 等价词表、Phase 3C 即时引用快扫、Phase 0 并发冲突保护、lint_report 稳定 ID + resolved 跳过、Base commit 兜底 | ✅ 独立目录 `plugins/memcore-codex/`（不与 Claude 版共用 `skills/`），架构不同：`AGENTS.md` 会话入口、`.claude/memory` 优先复用否则落 `.codex/memory`、无远程同步 | -| `obsidian` | 10 个（obsidian/bases/canvas/daily/history/meta/plugins/search/tasks/workflow-pkm） | 纯技能，无 MCP；对标社区基准（kepano/obsidian-skills 31.8k★、AgriciDaniel/claude-obsidian）后扩展 canvas 视觉层；核心 obsidian 含 OFM 语法速查；workflow-pkm 含 Web Clip 子流程 | ✅ `.codex-plugin/plugin.json` 共用同一 `skills/`，无 MCP 无需 Token | -| `zentao` | 8 个（project/story/bug/task/test/plan/misc/shared） | userConfig Token（禅道「个人中心 → 获取凭证」14 天有效期自助生成，非 Bearer 标准格式，走自定义 header `"token": "${user_config.token}"`）+ MCP Server；MCP Server 是基于开源 merzzzl/openapi-mcp-server 二次开发的 zentao-mcp 网桥，部署在 `pm.ops.yixiong-tech.com/mcp`，请求体字段统一包在 `payload` 里；README 配了三张截图（`docs/images/zentao-token/`）图解获取凭证流程 | ✅ `.codex-plugin/plugin.json` 共用同一 `skills/`，Token 走环境变量 `ZENTAO_TOKEN`（`bearer_token_env_var`）；网桥已确认同时兼容自定义 `token` header 与标准 `Authorization: Bearer`，双端认证均可用 | +| 插件 | 技能 | 特性 | Codex 支持 | Hermes 支持 | +|------|------|------|------|------| +| `huanxi` | 个人端 7 个（report/leader/task/issue/meeting/lookup/shared） | userConfig Bearer Token（hxp_）+ MCP Server（URL 走 office 子域，无端口） | ✅ `.codex-plugin/plugin.json` 共用同一 `skills/`，Token 走环境变量 `HUANXI_TOKEN`（`bearer_token_env_var`） | ✅ 裸 `plugin.json`（Agent Plugins v1）共用同一 `skills/`，不打包 `mcp.json`，Token 走 `~/.hermes/config.yaml` 手动 `${VAR}` 插值 | +| `huanxi-admin` | 管理端 4 个（admin-report/admin-module/admin-ops/admin-shared） | userConfig Bearer Token（hxa_）+ MCP Server；普通员工无需安装，2026-08-21 v1.0.0 生产切换后首次发布 | ✅ 同上模式，Token 环境变量 `HUANXI_ADMIN_TOKEN` | ✅ 同 huanxi 模式，Token 环境变量 `HUANXI_ADMIN_TOKEN` | +| `memcore` | Claude 版 4 个（memory-sync/lint/update/shared） | 纯技能，无 MCP；memcore-shared 作内部 include（路径锁定 + 阈值常量 + PROJECT_DIR 解析），支持 synonyms.md 等价词表、Phase 3C 即时引用快扫、Phase 0 并发冲突保护、lint_report 稳定 ID + resolved 跳过、Base commit 兜底 | ✅ 独立目录 `plugins/memcore-codex/`（不与 Claude 版共用 `skills/`），架构不同：`AGENTS.md` 会话入口、`.claude/memory` 优先复用否则落 `.codex/memory`、无远程同步 | ✅ 独立目录 `plugins/memcore-hermes/`，记忆目录优先级 `.claude/memory` → `.codex/memory` → 新建 `.agents/memory`；显式提醒不与 Hermes 原生全局 `~/.hermes/memories/`（按 profile 隔离）混淆 | +| `obsidian` | 10 个（obsidian/bases/canvas/daily/history/meta/plugins/search/tasks/workflow-pkm） | 纯技能，无 MCP；对标社区基准（kepano/obsidian-skills 31.8k★、AgriciDaniel/claude-obsidian）后扩展 canvas 视觉层；核心 obsidian 含 OFM 语法速查；workflow-pkm 含 Web Clip 子流程 | ✅ `.codex-plugin/plugin.json` 共用同一 `skills/`，无 MCP 无需 Token | ✅ 裸 `plugin.json` 共用同一 `skills/`，无 MCP 无需配置 | +| `zentao` | 8 个（project/story/bug/task/test/plan/misc/shared） | userConfig Token（禅道「个人中心 → 获取凭证」14 天有效期自助生成，非 Bearer 标准格式，走自定义 header `"token": "${user_config.token}"`）+ MCP Server；MCP Server 是基于开源 merzzzl/openapi-mcp-server 二次开发的 zentao-mcp 网桥，部署在 `pm.ops.yixiong-tech.com/mcp`，请求体字段统一包在 `payload` 里；README 配了三张截图（`docs/images/zentao-token/`）图解获取凭证流程 | ✅ `.codex-plugin/plugin.json` 共用同一 `skills/`，Token 走环境变量 `ZENTAO_TOKEN`（`bearer_token_env_var`）；网桥已确认同时兼容自定义 `token` header 与标准 `Authorization: Bearer`，双端认证均可用 | ✅ 裸 `plugin.json` 共用同一 `skills/`，Token 走 `~/.hermes/config.yaml` 手动配置 `headers: {token: "${ZENTAO_TOKEN}"}` | -Codex/ChatGPT 桌面应用侧市场索引独立维护在 `.agents/plugins/marketplace.json`（marketplace 名 `yixiong-codex-hub`），与 Claude 侧 `.claude-plugin/marketplace.json`（`yixiong-claude-hub`）并存，互不干扰。已确认不做 Antigravity（Google agy）兼容。 +Codex/ChatGPT 桌面应用侧市场索引独立维护在 `.agents/plugins/marketplace.json`（marketplace 名 `yixiong-codex-hub`），与 Claude 侧 `.claude-plugin/marketplace.json`（`yixiong-claude-hub`）并存，互不干扰。Hermes 侧没有中心化市场索引机制，靠仓库根目录 [`packs/`](../../packs) 下逐插件的 pack manifest（`hermes plugins pack install ./packs/.yaml`）选装，`ref` 需在每次相关发布后手动 bump 到最新 commit SHA。已确认不做 Antigravity（Google agy）兼容。 -**See Also**：[[decisions.md#huanxi plugin 使用 userConfig 而非环境变量传 Token]]、[[decisions.md#Codex/ChatGPT 桌面应用插件骨架——三个插件共享 skills/，memcore 独立目录（2026-08-22）]]、[[decisions.md#不做 Antigravity（Google agy / Antigravity 2.0）兼容（2026-08-22）]]、[[decisions.md#zentao-mcp 网桥已打补丁，双认证格式兼容（2026-08-25）]] +**See Also**：[[decisions.md#huanxi plugin 使用 userConfig 而非环境变量传 Token]]、[[decisions.md#Codex/ChatGPT 桌面应用插件骨架——三个插件共享 skills/，memcore 独立目录（2026-08-22）]]、[[decisions.md#不做 Antigravity（Google agy / Antigravity 2.0）兼容（2026-08-22）]]、[[decisions.md#zentao-mcp 网桥已打补丁，双认证格式兼容（2026-08-25）]]、[[decisions.md#Hermes 插件骨架：Agent Plugins v1 + packs 选装（2026-08-25）]] ## 发布流程 diff --git a/CLAUDE.md b/CLAUDE.md index 5aa222b..9b516ac 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -24,6 +24,8 @@ plugins/ 本仓库同时是 Codex/ChatGPT 桌面应用的插件市场，独立索引在 `.agents/plugins/marketplace.json`。huanxi/huanxi-admin/obsidian 在各自插件目录下再放一份 `.codex-plugin/plugin.json`（与 `.claude-plugin/plugin.json` 并列），共用同一份 `skills/`；`memcore` 因架构差异（见下方「Codex plugin.json」与「memcore 技能调用关系」两节）走独立目录 `plugins/memcore-codex/`。 +本仓库还支持 Hermes Agent（Nous Research 开源本地 Agent），走开放标准 [Agent Plugins v1.0.0](https://agent-plugins.org/)：huanxi/huanxi-admin/obsidian/zentao 在插件根目录再放一份**裸** `plugin.json`（不嵌套在点前缀目录里，规范要求），共用同一份 `skills/`；`memcore` 因架构差异同样走独立目录 `plugins/memcore-hermes/`。Hermes 没有中心化市场命令，靠 [`packs/`](./packs) 目录下的 pack manifest（`hermes plugins pack install`）逐个选装，见下方「Hermes plugin.json」一节。 + ## 核心文件格式 ### marketplace.json（市场索引） @@ -77,6 +79,17 @@ description: 一句话说明该技能的用途（Claude 用此判断何时触发 - 不支持 `hooks` 字段 - 技能 frontmatter 的 `disable-model-invocation` 只能是 `false` 或不写；技能"内部 include 不给用户直接调用"要用该技能 `agents/openai.yaml` 里的 `policy.allow_implicit_invocation: false` + description 措辞实现 +### Hermes plugin.json（Hermes 侧插件元数据） + +跟 Claude/Codex 侧都不通用，走 [agent-plugins.org 官方 spec](https://agent-plugins.org/specification) 定义的硬性约束： + +- 文件必须叫 `plugin.json`，直接放在插件根目录（不能嵌套进任何点前缀目录） +- 必需字段只有 `$schema` + `name`；`name` 限定 `[a-z0-9.-]`、1–64 字符，不能以 `-`/`.` 开头结尾，不能出现连续的 `--`/`..` +- `skills/` 目录下每个直接子目录只要含 `SKILL.md` 就会被识别为一个技能，不需要额外声明 +- **规范禁止在 `mcp.json` 里内嵌密钥**（headers/env 都不行，也没有等价于 `bearer_token_env_var`/`userConfig` 的字段）：带 Token 的插件（huanxi/huanxi-admin/zentao）因此不打包 `mcp.json`，MCP 配置改走 README 里的 `~/.hermes/config.yaml` 手动指引（该文件原生支持 `${VAR}` 环境变量插值） +- 单仓库多插件靠 `hermes plugins pack install ./packs/.yaml` 的 `subdir` 字段定位子目录，`ref` 必须是精确 40 位 commit SHA（不接受分支名），改动插件后要记得同步 bump `packs/*.yaml` 里的 `ref` +- 有两点文档未写清楚、没能验证：`pack install` 是否支持直接传 http(s) 链接（而非本地路径）；`subdir` 指向的目录若只有 `plugin.json`（没有 Hermes 原生 `plugin.yaml`）能否被正确识别——见 [[decisions.md#Hermes 插件骨架：Agent Plugins v1 + packs 选装（2026-08-25）]] + ## 新增插件流程 1. 在 `plugins/` 下创建目录 `plugins//` @@ -94,7 +107,7 @@ description: 一句话说明该技能的用途（Claude 用此判断何时触发 | `obsidian` | `/obsidian` `/obsidian-bases` `/obsidian-canvas` `/obsidian-daily` `/obsidian-history` `/obsidian-meta` `/obsidian-plugins` `/obsidian-search` `/obsidian-tasks` `/obsidian-workflow-pkm` | Obsidian 知识库完整工作流（10 个技能；对标 kepano/obsidian-skills 31.8k★ 与 AgriciDaniel/claude-obsidian） | | `zentao` | `/zentao-shared` `/zentao-project` `/zentao-story` `/zentao-bug` `/zentao-task` `/zentao-test` `/zentao-plan` `/zentao-misc` | 禅道项目管理系统（8 个技能），含 MCP Server 自动配置（禅道「个人中心 → 获取凭证」14 天 Token）；MCP Server 是基于开源 [merzzzl/openapi-mcp-server](https://github.com/merzzzl/openapi-mcp-server) 二次开发的 zentao-mcp 网桥，部署在 `pm.ops.yixiong-tech.com/mcp`，请求体字段统一包在 `payload` 里 | -五个插件均有 Codex/ChatGPT 桌面应用版本（见上方「Codex plugin.json」一节）。huanxi/huanxi-admin/obsidian/zentao 的 Codex 版共用本表里的同一份 `skills/`；`memcore` 的 Codex 版是独立目录 `plugins/memcore-codex/`（内容与下方 Claude 版 memcore 不同，改动时两边分别维护，不要假设同步）。已调研并确认不做 Google Antigravity（agy）兼容——其官方文档目前没有 marketplace 概念。 +五个插件均有 Codex/ChatGPT 桌面应用版本（见上方「Codex plugin.json」一节）和 Hermes Agent 版本（见上方「Hermes plugin.json」一节）。huanxi/huanxi-admin/obsidian/zentao 的 Codex 版、Hermes 版都共用本表里的同一份 `skills/`；`memcore` 的 Codex 版是独立目录 `plugins/memcore-codex/`，Hermes 版是独立目录 `plugins/memcore-hermes/`（内容与下方 Claude 版 memcore 均不同，三边分别维护，不要假设同步）。已调研并确认不做 Google Antigravity（agy）兼容——其官方文档目前没有 marketplace 概念。 ### memcore 技能调用关系 @@ -129,8 +142,8 @@ description: 一句话说明该技能的用途（Claude 用此判断何时触发 ``` .claude/memory/ ├── MEMORY.md # 索引（入口） -├── decisions.md # 关键架构决策（含 memcore-shared/lint_report 保活/Base commit 兜底/obsidian 社区对标审查/memory-lint 速度分档过期检测/Codex 插件骨架与 memcore-codex 独立目录/bearer_token_env_var/不做 Antigravity 兼容/zentao-mcp 网桥双认证格式兼容等 17 项） -├── project_overview.md # 项目定位与结构（huanxi/huanxi-admin/memcore/obsidian/zentao 已发布插件，均含 Codex 支持情况） +├── decisions.md # 关键架构决策（含 memcore-shared/lint_report 保活/Base commit 兜底/obsidian 社区对标审查/memory-lint 速度分档过期检测/Codex 插件骨架与 memcore-codex 独立目录/bearer_token_env_var/不做 Antigravity 兼容/zentao-mcp 网桥双认证格式兼容/Hermes 插件骨架与 packs 选装等 18 项） +├── project_overview.md # 项目定位与结构（huanxi/huanxi-admin/memcore/obsidian/zentao 已发布插件，均含 Codex + Hermes 支持情况） ├── feedback_plugin_dev.md # 插件开发协作规范（含 MCP docstring 单一真相、签名变更全量扫描） └── lint_report.md # 记忆健康检查报告（按需） ``` diff --git a/README.md b/README.md index 0807d33..922d88d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 蚁熊技能市场 -蚁熊团队内部的插件市场，同时支持 **Claude Code** 和 **Codex（含 ChatGPT 桌面应用与 CLI 两种形态）**——汇聚团队在真实业务场景里打磨出来的技能与工作流插件，从项目管理到知识库协作，从代码审查到数据工程，装上它，让 AI 编程助手更懂蚁熊。 +蚁熊团队内部的插件市场，同时支持 **Claude Code**、**Codex（含 ChatGPT 桌面应用与 CLI 两种形态）**和 **Hermes Agent**——汇聚团队在真实业务场景里打磨出来的技能与工作流插件，从项目管理到知识库协作，从代码审查到数据工程，装上它，让 AI 编程助手更懂蚁熊。 ## 快速安装 @@ -61,15 +61,37 @@ codex plugin marketplace add https://gitea.rk-health.com/yixiong/yixiong-claude- > Codex 侧的插件清单独立维护在 [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json)。除 `memcore` 外，其余四个插件与 Claude Code 版共用同一份 `skills/`；`memcore` 因为架构差异（会话入口、记忆目录约定、有无远程同步都不同）走的是独立目录 [`plugins/memcore-codex/`](./plugins/memcore-codex)，两边分开维护。 +### Hermes Agent + +Hermes（Nous Research 开源的本地 Agent）没有像 Claude/Codex 那样的"注册市场源"命令，但官方支持一个跨客户端开放标准 [Agent Plugins v1.0.0](https://agent-plugins.org/)（`plugin.json` + `skills/`），且 `hermes plugins pack install` 支持 `subdir` 定位 monorepo 子目录——所以我们没有另开仓库，而是在每个插件根目录放一份裸 `plugin.json`，复用同一份 `skills/`，用一组 [`packs/`](./packs) 里的 pack manifest 文件做选装。 + +**安装（想装哪个装哪个，互不影响）：** + +```bash +git clone https://gitea.rk-health.com/yixiong/yixiong-claude-marketplace.git +cd yixiong-claude-marketplace + +hermes plugins pack show ./packs/zentao.yaml # 先看会装什么 +hermes plugins pack install ./packs/zentao.yaml # 确认后装（想装别的插件换文件名） +``` + +想一次装全部五个：`hermes plugins pack install ./packs/all.yaml`。 + +> ⚠️ **`ref` 是手动维护的定长 commit SHA，不会像 Claude Code 那样自动追新**——Hermes 的 pack manifest 要求精确 40 位 commit SHA，不接受分支名，我们每次发布都会同步 bump `packs/*.yaml` 里的 `ref`；如果你 clone 下来的代码比 pack 文件新，装的仍是 pack 里锁定的那个旧版本，想要最新内容就 `git pull` 到对应 commit 或等我们下一次发布。 +> +> ⚠️ **凭证类插件（`huanxi`/`huanxi-admin`/`zentao`）不含 MCP 声明**——Agent Plugins v1 的 `mcp.json` 规范明文禁止内嵌密钥，所以这三个插件只打包了技能，MCP Server 需要你在 `~/.hermes/config.yaml` 里手动加几行（下面各插件小节有具体片段），比 Claude 的"装插件时弹窗填 Token"体验差一点，这是协议本身的限制，不是我们没做完。 +> +> ⚠️ **两处我没能用真实 Hermes 验证、需要你实测反馈的点**：① `hermes plugins pack install` 是否支持直接传 raw 链接（不用先 clone）；② `subdir` 指向的目录是纯 `plugin.json`（没有原生 `plugin.yaml`）时能否被正确识别——文档都没写明，等你的 Hermes 装一次就知道了。 + ## 插件一览 -| 插件 | 技能数 | 适用场景 | 谁需要装 | Claude Code | Codex | -|---|---|---|---|:---:|:---:| -| [`huanxi`](./plugins/huanxi) | 7 | 寰汐企业管理系统个人端——日报、负责人日报、任务、议题、会议、组织检索 | 全员 | ✅ | ✅ | -| [`huanxi-admin`](./plugins/huanxi-admin) | 4 | 寰汐管理端——汇报盘点、模块与成员配置、运维简报 | 需要后台管理员发放 `hxa_` Token 的管理岗 | ✅ | ✅ | -| [`memcore`](./plugins/memcore) / [`memcore-codex`](./plugins/memcore-codex) | 4 | 项目记忆体系核心引擎——跨会话记忆的同步/增量更新/健康校验 | 用 Claude Code 或 Codex 做长期项目的开发者 | ✅ | ✅ | -| [`obsidian`](./plugins/obsidian) | 10 | Obsidian 知识库全套协作工作流——vault 管理、搜索图谱、Bases、Canvas、每日笔记等 | 用 Obsidian 做知识管理的人 | ✅ | ✅ | -| [`zentao`](./plugins/zentao) | 8 | 禅道项目管理——项目集/产品/项目/执行、需求（story/epic/requirement）、Bug、任务、测试、计划与发布、反馈工单 | 用禅道管项目/需求/Bug/任务的人 | ✅ | ✅ | +| 插件 | 技能数 | 适用场景 | 谁需要装 | Claude Code | Codex | Hermes | +|---|---|---|---|:---:|:---:|:---:| +| [`huanxi`](./plugins/huanxi) | 7 | 寰汐企业管理系统个人端——日报、负责人日报、任务、议题、会议、组织检索 | 全员 | ✅ | ✅ | ✅ | +| [`huanxi-admin`](./plugins/huanxi-admin) | 4 | 寰汐管理端——汇报盘点、模块与成员配置、运维简报 | 需要后台管理员发放 `hxa_` Token 的管理岗 | ✅ | ✅ | ✅ | +| [`memcore`](./plugins/memcore) / [`memcore-codex`](./plugins/memcore-codex) / [`memcore-hermes`](./plugins/memcore-hermes) | 4 | 项目记忆体系核心引擎——跨会话记忆的同步/增量更新/健康校验 | 用 Claude Code / Codex / Hermes 做长期项目的开发者 | ✅ | ✅ | ✅ | +| [`obsidian`](./plugins/obsidian) | 10 | Obsidian 知识库全套协作工作流——vault 管理、搜索图谱、Bases、Canvas、每日笔记等 | 用 Obsidian 做知识管理的人 | ✅ | ✅ | ✅ | +| [`zentao`](./plugins/zentao) | 8 | 禅道项目管理——项目集/产品/项目/执行、需求（story/epic/requirement）、Bug、任务、测试、计划与发布、反馈工单 | 用禅道管项目/需求/Bug/任务的人 | ✅ | ✅ | ✅ | ### huanxi / huanxi-admin @@ -91,16 +113,31 @@ codex plugin marketplace add https://gitea.rk-health.com/yixiong/yixiong-claude- - **ChatGPT 桌面应用（图形界面启动，不经过 shell）**：`export` 对它无效，要设成系统级持久变量： - macOS：终端里跑一次 `launchctl setenv HUANXI_TOKEN hxp_你的token`（`huanxi-admin` 同理换成 `HUANXI_ADMIN_TOKEN`），然后重新打开桌面应用；这个设置只在当前登录会话有效，重启电脑要重新执行，长期用建议放进登录项脚本 - Windows：「系统属性 → 环境变量」里新增用户变量 `HUANXI_TOKEN` / `HUANXI_ADMIN_TOKEN`，保存后重新打开应用 +4. **Hermes Agent**：装完插件包（只含技能，不含 MCP 声明）后，在 `~/.hermes/config.yaml` 里手动加一段，`${VAR}` 会在连接时从环境变量解析，不会明文写死在文件里： + + ```yaml + mcp_servers: + huanxi: + url: "https://huanxi.office.yixiong-tech.com/mcp/" + headers: + Authorization: "Bearer ${HUANXI_TOKEN}" + huanxi-admin: # 只有装了 huanxi-admin 才需要这段 + url: "https://huanxi.office.yixiong-tech.com/admin-mcp/" + headers: + Authorization: "Bearer ${HUANXI_ADMIN_TOKEN}" + ``` + + 再设置环境变量（Hermes 是本地长驻进程，跟终端应用同源，`export` 写法同 Codex CLI 那节）：`export HUANXI_TOKEN=hxp_你的token`。 ### memcore 给 AI 编程助手加一套跨会话持久记忆的引擎：`memory-sync` 做全量同步、`memory-update` 做增量写入、`memory-lint` 做健康校验（孤儿引用、断链、内容矛盾、过期检测）。不依赖 MCP，纯技能实现，**无需任何配置，安装即用**。 -Claude Code 版（[`plugins/memcore`](./plugins/memcore)）以 `.claude/memory/` 为唯一权威，`memory-sync` 会额外和 `~/.claude/projects/*/memory/` 做远程镜像同步，支持多机协作。Codex 版（[`plugins/memcore-codex`](./plugins/memcore-codex)）架构不同：会话入口是 `AGENTS.md` 而非 `CLAUDE.md`，记忆目录优先复用已有的 `.claude/memory/`、否则落在 `.codex/memory/`，且**不做远程同步**——Codex 没有等价的跨机器 auto memory 层，记忆只落在当前仓库内。两个版本共享同一套 `SYNTHESIS_THRESHOLD`、过期检测速度分档等常量设计，但各自独立维护。 +Claude Code 版（[`plugins/memcore`](./plugins/memcore)）以 `.claude/memory/` 为唯一权威，`memory-sync` 会额外和 `~/.claude/projects/*/memory/` 做远程镜像同步，支持多机协作。Codex 版（[`plugins/memcore-codex`](./plugins/memcore-codex)）架构不同：会话入口是 `AGENTS.md` 而非 `CLAUDE.md`，记忆目录优先复用已有的 `.claude/memory/`、否则落在 `.codex/memory/`，且**不做远程同步**——Codex 没有等价的跨机器 auto memory 层，记忆只落在当前仓库内。Hermes 版（[`plugins/memcore-hermes`](./plugins/memcore-hermes)）会话入口同样是 `AGENTS.md`，记忆目录复用优先级是 `.claude/memory/` → `.codex/memory/` → 都没有则新建 `.agents/memory/`（目录名不绑定单一工具，方便未来第三个工具接入）；Hermes 自己有一套按 profile 隔离的全局记忆（`~/.hermes/memories/MEMORY.md`/`USER.md`），跟项目级记忆是两回事，memcore-hermes 会在同步时提醒这个边界，避免同一份项目事实两处漂移。三个版本共享同一套 `SYNTHESIS_THRESHOLD`、过期检测速度分档等常量设计，但各自独立维护。 ### obsidian -检测到项目里有 `.obsidian/` 目录会自动激活，覆盖 vault 管理、全文与图谱搜索、frontmatter、任务、每日笔记、Bases 数据库、Canvas 视觉层、版本历史、插件配置、PKM 编排十个技能，对标社区里比较成熟的 Obsidian 技能实现后做了扩展。**无需任何配置**，Claude Code 和 Codex CLI 共用同一份技能内容。 +检测到项目里有 `.obsidian/` 目录会自动激活，覆盖 vault 管理、全文与图谱搜索、frontmatter、任务、每日笔记、Bases 数据库、Canvas 视觉层、版本历史、插件配置、PKM 编排十个技能，对标社区里比较成熟的 Obsidian 技能实现后做了扩展。**无需任何配置**，Claude Code、Codex CLI、Hermes Agent 共用同一份技能内容。 ### zentao @@ -125,6 +162,17 @@ Claude Code 版（[`plugins/memcore`](./plugins/memcore)）以 `.claude/memory/` - **命令行**：`export ZENTAO_TOKEN=你的token`，建议写进 `~/.zshrc` / `~/.bashrc` - **ChatGPT 桌面应用**：macOS 用 `launchctl setenv ZENTAO_TOKEN 你的token`，Windows 走「系统属性 → 环境变量」新增用户变量 `ZENTAO_TOKEN`，设置后需重新打开应用 +6. **Hermes Agent**：装完插件包后在 `~/.hermes/config.yaml` 里加一段（注意 zentao-mcp 网桥认的 header 字段是 `token`，不是标准 `Authorization: Bearer`）： + + ```yaml + mcp_servers: + zentao: + url: "https://pm.ops.yixiong-tech.com/mcp" + headers: + token: "${ZENTAO_TOKEN}" + ``` + + 再 `export ZENTAO_TOKEN=你的token`。 ## 开发 @@ -132,6 +180,8 @@ Claude Code 版（[`plugins/memcore`](./plugins/memcore)）以 `.claude/memory/` Codex 插件的 `.codex-plugin/plugin.json` 有几个硬性约束（用本机 `plugin-creator` 技能自带的 `validate_plugin.py` 校验）：`skills` 字段必须精确指向 `./skills`、`mcpServers` 字符串路径必须精确指向 `./.mcp.json`（都在插件根目录，不能嵌套在 `.codex-plugin/` 里），且顶层 `interface` 块（`displayName`/`shortDescription`/`longDescription`/`developerName`/`category`/`capabilities`/`defaultPrompt`）是必填项。 +Hermes 插件走开放标准 [Agent Plugins v1.0.0](https://agent-plugins.org/specification)：`plugin.json` 是裸文件（不嵌套在点前缀目录里），必需字段只有 `$schema` + `name`（`name` 限定 `[a-z0-9.-]`，1–64 字符，不能有连续 `-`/`.`），`skills/` 目录下每个直接子目录含 `SKILL.md` 即被识别为一个技能。规范本身禁止在 `mcp.json` 里内嵌密钥，所以带 Token 的插件不打包 `mcp.json`，MCP 配置走 README 里各插件小节的手动指引。新增/修改 Hermes 相关内容后，同步维护 [`packs/`](./packs) 里对应的 pack manifest（`ref` 手动 bump 到最新 commit SHA）。 + ## 更新记录 见 [CHANGELOG.md](./CHANGELOG.md)。 diff --git a/plugins/huanxi-admin/plugin.json b/plugins/huanxi-admin/plugin.json new file mode 100644 index 0000000..c6a46d8 --- /dev/null +++ b/plugins/huanxi-admin/plugin.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "huanxi-admin", + "version": "1.0.0", + "description": "寰汐企业管理系统 · 管理端。全量视角，含汇报盘点、模块与成员配置、运维简报三个工作流技能。需要管理员发放的 hxa_ Token，高危操作（账号启停/提权/删除）不在此端点。MCP 连接需要在 Hermes 的 ~/.hermes/config.yaml 里手动配置 Token（见仓库 README「Hermes Agent」一节），Agent Plugins v1 协议不支持随插件包内嵌密钥。", + "author": { + "name": "姜顺志" + }, + "license": "MIT", + "keywords": ["huanxi", "productivity", "project-management", "admin"] +} diff --git a/plugins/huanxi/plugin.json b/plugins/huanxi/plugin.json new file mode 100644 index 0000000..cdac98a --- /dev/null +++ b/plugins/huanxi/plugin.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "huanxi", + "version": "1.0.0", + "description": "寰汐企业管理系统 · 个人端。以你本人的身份操作，权限与网页端一致。含日报、负责人日报、任务、议题、会议、组织检索六个工作流技能。MCP 连接需要在 Hermes 的 ~/.hermes/config.yaml 里手动配置 Token（见仓库 README「Hermes Agent」一节），Agent Plugins v1 协议不支持随插件包内嵌密钥。", + "author": { + "name": "姜顺志" + }, + "license": "MIT", + "keywords": ["huanxi", "productivity", "project-management"] +} diff --git a/plugins/memcore-hermes/plugin.json b/plugins/memcore-hermes/plugin.json new file mode 100644 index 0000000..9410a50 --- /dev/null +++ b/plugins/memcore-hermes/plugin.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "memcore-hermes", + "version": "1.0.0", + "description": "Hermes Agent 记忆体系核心引擎。提供 memcore-shared（内部共享约定）+ memory-sync（全量同步编排）+ memory-update（增量写入）+ memory-lint（健康校验）。项目记忆目录复用 .claude/memory 或 .codex/memory，都不存在时新建 .agents/memory；不读写 Hermes 原生全局 MEMORY.md/USER.md，也不使用任何远程记忆。", + "author": { + "name": "蚁熊团队" + }, + "license": "MIT", + "keywords": ["memory", "productivity", "project-memory"] +} diff --git a/plugins/memcore-hermes/skills/memcore-shared/SKILL.md b/plugins/memcore-hermes/skills/memcore-shared/SKILL.md new file mode 100644 index 0000000..0c71ee8 --- /dev/null +++ b/plugins/memcore-hermes/skills/memcore-shared/SKILL.md @@ -0,0 +1,86 @@ +--- +name: memcore-shared +description: "memcore 内部共享约定：记忆目录选择优先级、会话入口术语、禁止触碰的路径、synthesis/过期检测阈值常量、Hermes 全局记忆避让规则。仅供 memory-sync、memory-update、memory-lint 三个技能在 Phase 0 内部 Read 引用，不用于直接回答用户问题或独立执行任务。" +--- + +# memcore-shared + +三个主技能（memory-sync / memory-update / memory-lint）的内部共享 include。**用户不会直接调用本技能**，三个主技能在开始执行前必须先 Read 本文件载入以下约束。 + +--- + +## 统一术语 + +- `SESSION_GUIDE_FILE`：`AGENTS.md`，Hermes（及 Codex）共用的会话启动入口锚点。 +- `PROJECT_MEMORY_DIR`：项目内唯一记忆目录，取 `.claude/memory`、`.codex/memory` 或 `.agents/memory`（选择规则见下）。 +- `MEMORY_INDEX`：`PROJECT_MEMORY_DIR/MEMORY.md`。 + +修改 `SESSION_GUIDE_FILE`、`MEMORY_INDEX` 或任何记忆文件时，优先使用小范围补丁，不要整文件重写。记忆变更和代码变更必须分开说明、分开确认。 + +--- + +## PROJECT_MEMORY_DIR 选择优先级 + +三个主技能执行前都必须先按以下优先级确定唯一记忆目录： + +1. 若 `AGENTS.md` 已含记忆体系区块，优先读取该区块中记录的记忆目录；目录存在则使用它（这条规则天然让 memcore-hermes 与 memcore-codex 共存于同一项目时不会各建一份）。 +2. 若 `$PROJECT_DIR/.claude/memory/` 存在，使用它——视为复用现有 Claude 项目记忆。 +3. 若 `$PROJECT_DIR/.codex/memory/` 存在，使用它——视为复用现有 Codex 项目记忆。 +4. 若 `$PROJECT_DIR/CLAUDE.md` 存在但以上两个目录都不存在，先读取 `CLAUDE.md` 中与记忆体系相关的说明；只在用户明确要求建立结构化记忆目录时才创建 `.agents/memory/`。 +5. 以上都不存在，需要创建记忆时使用 `$PROJECT_DIR/.agents/memory/`，但创建前必须向用户说明将建立的目录结构和基础文件，并等待确认。 + +关键规则： + +- `AGENTS.md` 是会话入口锚点，不是记忆目录本身。 +- 已有 `CLAUDE.md`、`.claude/memory/` 或 `.codex/memory/` 时直接引用现有内容，不重复添加同类记忆引导。 +- 不在 `.claude/memory/`、`.codex/memory/`、`.agents/memory/` 三者之间互相复制——只能存在一个作为 `PROJECT_MEMORY_DIR`。 +- 选 `.agents/memory/` 而不是 `.hermes/memory/`：这个目录名不绑定单一工具，未来若有第三个工具也想复用项目级记忆，可以按同样的选择优先级接入，不必再新造一个工具专属目录名。 + +--- + +## 禁止触碰的路径 + +| 路径 | 原因 | +|---|---| +| `~/.hermes/memories/`（`MEMORY.md`/`USER.md`） | Hermes 原生全局记忆，按 profile 隔离、跨项目共享，是个人召回层，不是团队可审查的项目事实来源，不作为本套记忆体系的后端，也不得读取后原样复制进项目记忆 | +| `~/.hermes/mcp-tokens/`、`~/.hermes/.env`、`~/.hermes/config.yaml` 中的密钥字段 | 凭证与本地配置，与项目记忆无关，严禁读写或摘录 | +| `~/.claude/projects/*/memory/` | Claude 侧系统 auto memory 路径，与本套记忆体系无关，严禁读写 | +| `$PROJECT_DIR` 之外任何其他路径 | 跨项目污染 | + +必须可审查、可协作、可复现的项目事实一律写入 `AGENTS.md`、`CLAUDE.md`、`.claude/memory/`、`.codex/memory/` 或 `.agents/memory/`，不写入上表任何路径。 + +--- + +## Hermes 全局记忆避让规则（不重复记录） + +Hermes 会自动把它认为值得记住的内容写入 `~/.hermes/memories/MEMORY.md`（agent 笔记）与 `USER.md`（用户档案），这个行为是**自主触发、默认开启**的，不受本套技能控制。三个主技能在执行时必须显式提醒（写入报告/摘要即可，不需要修改 Hermes 配置）： + +> `PROJECT_MEMORY_DIR` 是本项目事实的权威来源；Hermes 自己的全局 `MEMORY.md`/`USER.md` 属于跨项目的个人记忆层，不应该收录本项目特有的架构决策、协作规范、进度信息——这些统一沉淀在 `PROJECT_MEMORY_DIR`，避免同一份事实在两处漂移出不一致的版本。 + +这条规则本身不是"技术拦截"（memcore 没有能力阻止 Hermes 自动写全局记忆），而是**写入 memory-sync/memory-update 的 Phase 0 提醒文案**，让用户知道两套记忆的边界在哪，出现内容重复或冲突时知道以哪一份为准（答案：`PROJECT_MEMORY_DIR`）。 + +--- + +## 全局常量 + +| 常量 | 值 | 含义 | 使用位置 | +|---|---|---|---| +| `SYNTHESIS_THRESHOLD` | `3` | 跨文件引用数 ≥ 此值即为 synthesis 升级候选 | memory-update Phase 3、memory-lint Phase 3 & 8 | +| `LINT_STALE_MIN_DAYS` | `7` | `last_updated` 不足此天数 → 跳过过期检测 | memory-lint Phase 5 | +| `LINT_HIGH_VELOCITY` | `1.0`（次/天） | 全仓库提交速度 ≥ 此值 → 高频迭代区 → ERROR | memory-lint Phase 5 | +| `LINT_LOW_VELOCITY` | `0.3`（次/天） | 全仓库提交速度 ≥ 此值 → 中频迭代区 → WARN | memory-lint Phase 5 | +| `LINT_STALE_ABSOLUTE_DAYS` | `180` | 速度低于 `LINT_LOW_VELOCITY` 时的绝对兜底天数 → WARN | memory-lint Phase 5 | + +子技能引用常量时使用上述名称，调整阈值只需修改本文件单一来源。可由 `MEMORY.md` 头部 `` 覆盖 `LINT_STALE_MIN_DAYS`。 + +--- + +## 引用约定 + +子技能开头标准引用句： + +```markdown +**前置约束：先 Read `../memcore-shared/SKILL.md`（记忆目录选择优先级 + 禁止路径 + Hermes 全局记忆避让规则 + 常量）** +``` + +读取后，子技能内所有出现的 `$PROJECT_DIR`、`PROJECT_MEMORY_DIR`、`MEMORY_INDEX`、`SESSION_GUIDE_FILE` 及上述常量均按本文件定义执行。 diff --git a/plugins/memcore-hermes/skills/memory-lint/SKILL.md b/plugins/memcore-hermes/skills/memory-lint/SKILL.md new file mode 100644 index 0000000..9258fd9 --- /dev/null +++ b/plugins/memcore-hermes/skills/memory-lint/SKILL.md @@ -0,0 +1,304 @@ +--- +name: memory-lint +description: 检查仓库/项目本地记忆目录的健康状况，修复结构性问题并生成 lint_report.md。用于校验 MEMORY.md 索引、孤儿/幽灵文件、双向引用、内容矛盾、按提交速度分档的过期检测和可推断内容污染。Hermes 版本只读写项目本地记忆；若仓库已有 CLAUDE.md/.claude/memory/ 或 AGENTS.md/.codex/memory/，直接引用现有记忆内容，不重复创建。 +--- + +# memory-lint + +健康检查项目本地记忆目录。会话目录视为 `$PROJECT_DIR`。 + +**前置约束：先 Read `../memcore-shared/SKILL.md`**（记忆目录选择优先级 + 禁止路径 + Hermes 全局记忆避让规则 + 常量），其约束在本技能全程生效。 + +修改 `MEMORY_INDEX`、`lint_report.md` 或任何记忆文件时，优先使用小范围补丁；不要整文件重写。记忆变更和代码变更必须分开说明、分开确认。 + +若目标记忆目录不存在，输出缺失说明并建议先执行 `memory-sync` 或 `memory-update` 初始化。 + +## Phase 0 - 读取状态 + +读取： + +- `MEMORY.md` +- 记忆目录内全部 `*.md` +- `Base commit` +- `Last synced` + +提取索引文件集合 `$INDEX_FILES` 和磁盘文件集合 `$DISK_FILES`。 + +## Phase 1-2 - 孤儿与幽灵检测 + +| 检查 | 定义 | 级别 | AUTO-FIX | +| --- | --- | --- | --- | +| 孤儿 | 索引有，磁盘无 | ERROR | 从 `MEMORY.md` 删除该条目 | +| 幽灵 | 磁盘有，索引无 | WARN | 补入索引 | + +幽灵类型推断（按优先级匹配）： + +- `synonyms.md`（精确匹配） → reference +- `user_*` → user +- `project_*` 或 `decisions.md` → project +- `feedback*` → feedback +- `reference*` → reference +- `synthesis_*` → synthesis +- 其他默认 project + +排除 `MEMORY.md`、`lint_report.md`。 + +## Phase 3 - 交叉引用完整性 + +### 3A 存在性检测 + 引用计数构建 + +扫描所有 `[[filename.md#section]]`，构建： + +- 引用表：`源文件#源章节 -> 目标文件#目标章节` +- 文件级被引用计数 `$REF_COUNT`（按源文件去重）→ Phase 7 写入 MEMORY.md「引用」列 +- decisions 和 feedback 条目级引用计数 `$ITEM_REF_COUNT`（按源文件去重）→ Phase 8 写入 lint_report.md，供 `memory-update` 反向触发消费 + +| 情况 | 级别 | 动作 | +| --- | --- | --- | +| 目标文件不存在 | ERROR | NEED-HUMAN | +| 目标章节缺失，且存在高相似标题 | WARN | AUTO-FIX 更新引用 | +| 目标章节缺失，且无相似项 | WARN | NEED-HUMAN | + +### 3B 对称性检测（双链闭环） + +复用 3A 引用表，对每条 `A#x -> B#y` 检查 B 的 `## y` 是否含任意 `[[A` 引用（不要求精确章节）。 + +- 级别：WARN +- AUTO-FIX：B 的目标章节末尾追加 `**See Also：** [[A#x]]` +- 边界：`lint_report.md` 不参与；B 整文件无对 A 任何引用 → AUTO-FIX；B 有引用但不在目标章节 → 仅 WARN 不自动修改 + +双链 AUTO-FIX 阈值：缺失反链不超过 5 条且涉及文件不超过 3 个时可以自动补齐；超过阈值、跨多个主题、或将触碰 `user_profile.md` / `synthesis_*.md` 时不自动修改，写入 `lint_report.md` 等待确认。 + +## Phase 4-pre - 等价表述加载 + +矛盾检测前先加载 `$PROJECT_MEMORY_DIR/synonyms.md`（可选文件）： + +```bash +[ -f "$PROJECT_MEMORY_DIR/synonyms.md" ] && \ + grep -v "^#\|^---\|^$\|^name:\|^description:\|^type:" \ + "$PROJECT_MEMORY_DIR/synonyms.md" +# 输出每行一个等价组（逗号分隔），大小写不敏感，存入 $SYNONYMS_GROUPS +``` + +`synonyms.md` 格式（用户自行在项目内创建和维护）： + +```markdown +--- +name: 等价表述清单 +description: 矛盾检测等价词表，同组词视为相同概念 +type: reference +--- + +# 等价表述清单 +> 每行一组，逗号分隔，大小写不敏感 + +PostgreSQL, PG, Postgres, postgresql +JWT, JSON Web Token +``` + +判定规则：两处描述中出现的技术术语若属同一等价组，跳过，不纳入矛盾候选。无 `synonyms.md` 时，仅检测直接数值/版本冲突，对措辞差异不报告。 + +## Phase 4 - 内容矛盾 + +| 维度 | 检查 | +| --- | --- | +| decisions vs feedback | 决策与协作规范是否冲突 | +| decisions vs 架构/依赖文件 | 是否与当前依赖清单（如 `package.json`、`requirements.txt`、`pom.xml`）实际内容冲突 | +| 多个 feedback 文件 | 是否重复或矛盾 | +| synthesis vs decisions | 归档结论是否抵触现有决策 | +| 合并残留标记 | 是否含 `` | + +矛盾判定门槛（过 synonyms.md 等价检查后）： + +| 情况 | 处理 | +| --- | --- | +| 同主题，等价组内术语不同 | 跳过，不报告 | +| 同主题，结论相反 | WARN → NEED-HUMAN | +| 同主题，数值或版本直接冲突 | ERROR → NEED-HUMAN | +| 仅措辞不同，无直接逻辑冲突 | 跳过（宁漏报不误报） | + +合并残留标记的 NEED-HUMAN 条目必须包含： + +- 位置：文件名、章节标题、标记内容。 +- Checklist：Q1 当前本地版本是否正确？Q2 另一版本是否有当前版本没有的有效信息？Q3 两者是否可以合并为单一表述？ +- 决策矩阵：Q2 否 → 删除 `[合并待审]` 或分歧段落和标记；Q2 是 + Q3 是 → 合并为单一表述后删除标记；Q2 是 + Q3 否 → 保留两段内容，但清除 HTML 标记并说明适用边界。 + +## Phase 5 - 过期检测（提交速度分档） + +不用固定天数二级阈值，改用「自 `last_updated` 以来的全仓库提交速度」判断过期风险的严重程度：高频迭代项目下 7 天未同步就可能已经漂移，低活跃项目下 180 天未动也可能仍然准确。阈值常量由 `memcore-shared` 定义。 + +```bash +# days_since：last_updated 距今天数 +days_since=$(( ($(date +%s) - $(date -d "$last_updated" +%s)) / 86400 )) + +# 不足 LINT_STALE_MIN_DAYS（默认 7 天）→ 跳过本文件的过期检测 +if [ "$days_since" -lt 7 ]; then + continue +fi + +# commits_since：全仓库自 last_updated 以来的提交数 +commits_since=$(git -C "$PROJECT_DIR" log --oneline --since="$last_updated" -- . | wc -l) + +# velocity：提交速度（次/天） +velocity=$(echo "scale=2; $commits_since / $days_since" | bc) +``` + +分级（可由 `MEMORY.md` 头部 `` 覆盖 `LINT_STALE_MIN_DAYS`）： + +| 条件 | 级别 | 语义 | +| --- | --- | --- | +| `velocity ≥ LINT_HIGH_VELOCITY`（默认 1.0） | ERROR | 高频迭代区，未同步几乎必然漂移 | +| `LINT_LOW_VELOCITY ≤ velocity < LINT_HIGH_VELOCITY`（默认 0.3~1.0） | WARN | 中频迭代，需人工确认是否漂移 | +| `velocity < LINT_LOW_VELOCITY` 且 `days_since < LINT_STALE_ABSOLUTE_DAYS`（默认 180） | — | 低活跃期，不判定过期 | +| `velocity < LINT_LOW_VELOCITY` 且 `days_since ≥ LINT_STALE_ABSOLUTE_DAYS` | WARN | 绝对兜底，防止彻底沉寂的记忆永不复查 | + +不要只因为日期老就自动刷新 `last_updated`。若内容仍有效，写入 NEED-HUMAN 让用户确认是否仅刷新日期；若内容与项目推进不符，标记为语义过时并给出证据位置。 + +## Phase 6 - 可推断内容污染 + +污染特征：大量具体文件路径、类名、方法签名、git 流水账、可从依赖文件直接读取的版本号列表。 + +**边界**：架构层级描述（"认证模块提供 JWT + OAuth2 双协议"）保留；具体类名/方法/路径列表删除或建议改写。 + +## Phase 7 - 执行 AUTO-FIX + +只允许修复结构性问题： + +1. 移除索引孤儿。 +2. 补入索引幽灵。 +3. 更新高置信断链引用。 +4. 在阈值内补齐双向链接；超过阈值则写入 NEED-HUMAN。 +5. 刷新 `MEMORY.md` 的「引用」列（基于 `$REF_COUNT`）：表格统一 5 列 `| 文件 | 描述 | 类型 | 引用 | Commit |`；「引用」值 ≥ `SYNTHESIS_THRESHOLD` 加 `*`（如 `5*`），否则显示数字；按引用次数倒序排列，同次数按类型序：user → project → feedback → reference → synthesis → lint。 + +不要自动修改业务结论、技术决策、用户偏好或主观归档内容。 + +## Phase 8 - 生成 lint_report.md + +### Phase 8-pre - NEED-HUMAN 稳定 ID 与已 resolved 保活 + +**目的**：用户在 `lint_report.md` 中给某个 NEED-HUMAN 条目添加 `` 标记后，下次 lint 不再重复列出该条目（即使问题尚未真正修复，用户已表达「不处理」意图）。 + +**ID 生成规则**： + +```bash +# 每个 NEED-HUMAN 条目计算稳定 ID（与执行时间无关，仅与"问题本体"有关） +# 输入：phase 编号 + 目标文件 + 目标章节 + 问题关键事实 +# 输出：sha1 前 8 位 +gen_id() { + printf '%s|%s|%s|%s' "$1" "$2" "$3" "$4" | sha1sum | cut -c1-8 +} + +# 示例： +# Phase 3A 断链：gen_id "3A" "decisions.md" "## 数据库选型" "[[synthesis_arch_xxx.md]]" +# Phase 4 矛盾：gen_id "4" "decisions.md+project_overview.md" "数据库选型" "PostgreSQL vs MySQL" +# Phase 5 过期：gen_id "5" "project_progress.md" "" "stale-86d" +# Phase 6 污染：gen_id "6" "project_overview.md" "" "line-N" +``` + +**已 resolved ID 提取**： + +```bash +RESOLVED_IDS=$(grep -B1 "`。 + +**用户如何使用**：在 `lint_report.md` 中某个 NEED-HUMAN 条目末尾、`` 同段内，追加： + +```markdown + +``` + +下次 lint 跑到时，发现该 id 在 `RESOLVED_IDS` 中，整条跳过，不再骚扰。 + +### 报告模板 + +```markdown +--- +name: 记忆健康检查报告 +description: memory-lint 最新一次执行的检查结果与待处理项 +type: lint +last_updated: YYYY-MM-DD +--- + +# 记忆健康检查报告 + +> _执行时间: YYYY-MM-DD | Base commit: `HASH` | Last synced: DATE_ +> +> **如何使用**：NEED-HUMAN 条目末尾有 `` 标记。处理完或决定不处理时，在同段追加 ``，下次 lint 该条目自动跳过。 + +## 健康概览 + +| 检查项 | AUTO-FIX | NEED-HUMAN（含已 resolved 跳过 N 项） | +| --- | --- | --- | +| 1 孤儿 / 2 幽灵 / 3A 引用 / 3B 双链 | N / N / N / N | — / — / N / N | +| 4 矛盾 / 5 过期 / 6 污染 | — | N / N / N | + +**AUTO-FIX 已执行 N 项 | NEED-HUMAN 新列出 N 项 | 历史已 resolved 跳过 M 项** + +--- + +## AUTO-FIX 已执行清单 + +- [x] 移除孤儿：`synthesis_xxx.md` +- [x] 补入幽灵：`feedback_api.md`（feedback） +- [x] 更新断链：`[[feedback.md#旧标题]]` → `[[feedback.md#新标题]]` +- [x] MEMORY.md「引用」列已刷新（N 文件，倒序） + +--- + +## 条目级高频引用 Top（供 memory-update 消费） + +跨 ≥ `SYNTHESIS_THRESHOLD` 个不同源文件被引用的 decisions/feedback 条目。无候选时保留标题 + "无候选"。 + +| 条目 | 跨文件次数 | 建议 | +| --- | --- | --- | +| `decisions.md#示例决策标题` | 4 | 升级为 synthesis_xxx.md | + +--- + +## NEED-HUMAN 待处理清单 + +每项附 3 问 yes/no checklist + 决策矩阵，避免模糊判断，末尾附 ``。 + +### [ERROR] 引用断链 — 目标文件不存在 + +- **位置**：`decisions.md → ## 数据库选型` → `[[synthesis_arch_xxx.md]]` +- **Checklist**：Q1 内容是否真实归档过？Q2 git history 能否找到删除/重命名证据？Q3 该引用是「锦上添花」还是「核心支撑」？ +- **矩阵**：Q1+Q2 是 → 恢复文件；Q1 是 + Q2 否 → 重新归档；Q1 否 → 删引用；Q3 核心 → 必须二选一不允许保留断链 + + +### [WARN] 过期记忆 — 提交速度分级超阈值 + +- **文件**：`project_progress.md`（last_updated: 2026-01-15，过期 86 天，同期 62 次提交，速度 0.72/天 → 中频区 WARN） +- **Checklist**：Q1 覆盖领域在此期间是否有里程碑变更？Q2 现有内容是否仍可指导决策？Q3 是否有继任 synthesis_* 已分担其职责？ +- **矩阵**：Q1 是 + Q2 否 → 触发 memory-update；Q2 是（仅日期老、速度低）→ 仅刷新 last_updated；Q3 是 → 归档/删除，索引指向继任者 + +``` + +## Phase 9 - 输出摘要 + +被 `memory-sync` 调用： + +``` +🔍 memory-lint：AUTO-FIX N 项，NEED-HUMAN N 项（历史 resolved 跳过 M 项，详见 lint_report.md） +``` + +独立调用：扩展输出已修复 / 待处理清单 + 报告路径；全通过则输出「记忆体系健康，已更新执行时间」。 + +发现矛盾候选且 `synonyms.md` 不存在时，额外提示：创建 `.claude/memory/synonyms.md`（或对应的 `.codex/memory/synonyms.md`、`.agents/memory/synonyms.md`）可将等价术语预先排除出矛盾检测，降低误报率。 + +每次执行必须更新 `lint_report.md`（即使全通过也刷新执行时间）。 + +## 执行约束 + +1. AUTO-FIX 边界严格 — 只修结构性错误（孤儿、幽灵、断链、双链），不改业务内容。 +2. NEED-HUMAN 完整记录 — 每项含 checklist + 决策矩阵 + 末尾 `` 稳定 ID。 +3. resolved 保活 — Phase 8-pre 提取旧 `lint_report.md` 中带 `` 的 ID 集合，新报告中同 ID 条目跳过；用户标记 resolved 即长效免打扰。 +4. 矛盾检测先过等价表 — 先加载 `synonyms.md` 再判矛盾；措辞不一致 ≠ 矛盾，宁漏报不误报。 +5. 污染检测边界（重申）— 架构层级保留 / 具体类名路径删除。 +6. 使用 `.claude/memory/` 或 `.codex/memory/` 时只复用现有项目记忆，不复制到 `.agents/memory/`。 +7. 不访问远程记忆路径，不维护任何跨机器镜像；不 lint Hermes 原生全局记忆（`~/.hermes/memories/`）。 +8. 被 `memory-sync` 调用时返回简短摘要；独立调用时输出已修复和待处理清单。 +9. 记忆变更和代码变更分开执行；不要把用户未确认的代码修改混入 lint 修复。 diff --git a/plugins/memcore-hermes/skills/memory-sync/SKILL.md b/plugins/memcore-hermes/skills/memory-sync/SKILL.md new file mode 100644 index 0000000..9bdd755 --- /dev/null +++ b/plugins/memcore-hermes/skills/memory-sync/SKILL.md @@ -0,0 +1,160 @@ +--- +name: memory-sync +description: 编排 Hermes 项目本地记忆同步流程：识别现有 CLAUDE.md/.claude/memory 或 AGENTS.md/.codex/memory，确定唯一记忆目录，执行 memory-update 和 memory-lint，维护项目记忆索引和 AGENTS.md 启动引导。用于完整刷新仓库记忆体系。Hermes 版本不使用远程记忆，也不读写 Hermes 原生全局 MEMORY.md/USER.md；若已有 Claude/Codex 记忆内容则直接引用，不重复添加。 +--- + +# memory-sync + +执行项目本地记忆体系的完整同步周期。会话目录视为 `$PROJECT_DIR`。 + +**前置约束：先 Read `../memcore-shared/SKILL.md`**（记忆目录选择优先级 + 禁止路径 + Hermes 全局记忆避让规则 + 常量），其约束在本技能全程生效。 + +## 总流程 + +```text +Phase 0 确定 PROJECT_MEMORY_DIR（按 memcore-shared 优先级）+ 提醒 Hermes 全局记忆避让规则 +Phase 1 Git 和记忆冲突检查 +Phase 2 读取现有 Claude/Codex/Hermes 项目记忆 +Phase 3 计算 diff 或全量审查范围 +Phase 4 调用 memory-update +Phase 5 调用 memory-lint +Phase 6 维护 AGENTS.md 启动引导 +Phase 7 完成报告 +``` + +## Phase 0 - 确定 PROJECT_MEMORY_DIR + +按 `memcore-shared` 的选择优先级确定 `PROJECT_MEMORY_DIR`。若最终落在「需要创建 `.agents/memory/`」的分支，向用户说明目录结构并等待确认后再继续。 + +同时提醒一次（不需要用户回应，写进本次交流即可）：本项目事实统一沉淀在 `PROJECT_MEMORY_DIR`，Hermes 自己的全局 `~/.hermes/memories/MEMORY.md`/`USER.md` 是跨项目个人记忆层，两者不是一回事，出现内容重复以 `PROJECT_MEMORY_DIR` 为准。 + +## Phase 1 - Git 和记忆冲突检查 + +若项目是 git 仓库，先读取： + +```bash +git status --short +git rev-parse --show-toplevel +git rev-parse --short HEAD +``` + +存在未解决冲突时，优先处理记忆目录内的冲突文件。不要自动提交用户未确认的非记忆变更。 + +非 git 仓库继续执行，commit 字段填 `N/A`。 + +记忆文件冲突采用语义合并，限于 `PROJECT_MEMORY_DIR`： + +| 冲突类型 | 处理方式 | +| --- | --- | +| frontmatter `last_updated` | 取两者较新日期 | +| frontmatter `commit` | 取当前 HEAD 或本地工作区对应值 | +| `## Section` 两边内容相同 | 保留一份 | +| `## Section` 仅一边存在 | 保留或追加到文件末尾 | +| `## Section` 两边都存在但内容不同 | 保留当前本地版本，将另一版本追加为 `## [合并待审] Section`，标注 `` | +| `MEMORY.md` 索引冲突 | 不手工合并，保留当前版本，交给 `memory-lint` 重建索引 | +| `user_profile.md` 或 `synthesis_*.md` | 不自动合并，在文件头标注 `` | + +合并前应备份冲突文件，备份文件不要提交。完成后提示用户审查 `` 标记，并由 `memory-lint` 写入 NEED-HUMAN。 + +## Phase 2 - 读取现有记忆 + +若存在 `MEMORY.md`，先读取索引，再按需加载文件： + +- 必读：`decisions.md`、`feedback*.md`、`project_progress.md`、`project_overview.md` 中由索引标为 project 或 feedback 的文件。 +- 按需：`user_profile.md`、`reference.md`、`synthesis_*.md`、`lint_report.md`。 + +若只有 `CLAUDE.md`，读取其中与项目约定、记忆体系、开发流程有关的章节，并避免重复生成同类内容。 + +## Phase 3 - 计算审查范围 + +从 `MEMORY.md` 头部读取 `Base commit`。有锚点时使用： + +```bash +git diff --name-only $ANCHOR_COMMIT..HEAD +``` + +无锚点、非 git 仓库或首次初始化时执行全量审查。 + +## Phase 4 - 调用 memory-update + +按 `memory-update` 的规则增量写入本地记忆文件和 `MEMORY.md` 索引。 + +要求： + +- 只更新本次变化涉及的维度。 +- 以 Why、约束、边界和协作规范为主。 +- 不记录可从代码直接恢复的明细。 +- 若使用 `.claude/memory/` 或 `.codex/memory/`，保持原目录，不创建重复的 `.agents/memory/`。 + +## Phase 5 - 调用 memory-lint + +按 `memory-lint` 的规则执行健康检查： + +- 修复索引孤儿、幽灵、断链和缺失反向链接。 +- 刷新引用计数。 +- 生成或更新 `lint_report.md`。 +- 将内容矛盾、过期、污染和合并残留写入 NEED-HUMAN。 + +## Phase 6 - 维护 AGENTS.md 启动引导 + +Hermes 项目的启动引导优先写入 `AGENTS.md`——这也是 Codex 版本共用的同一个文件，两个工具在同一项目下不会各写一份。 + +处理顺序： + +1. 若项目已有 `AGENTS.md`，检查是否存在 `## 记忆体系（会话启动必读）` 区块。 +2. 若区块存在且仍与 `MEMORY.md` 一致，只引用，不重复追加。 +3. 若区块缺失或过期，先向用户说明将更新的内容，确认后再修改；提取区块内已记录的 commit 锚点（若有），据此判断哪些子章节需要针对性调整，而不是整块重写。 +4. 若项目没有 `AGENTS.md` 但已有 `CLAUDE.md`、`.claude/memory/` 或 `.codex/memory/`，默认只引用现有记忆；需要 Hermes 启动引导时，询问用户是否创建 `AGENTS.md`，不要把已有记忆目录复制到 `.agents/memory/`。 +5. 若项目没有 `AGENTS.md`、`CLAUDE.md`、`.claude/memory/` 和 `.codex/memory/`，需要项目级 Hermes 引导时创建 `AGENTS.md`，并指向 `.agents/memory/`。 +6. 不为了 Hermes 强制创建或改写 `CLAUDE.md`。 + +`AGENTS.md` 记忆体系区块模板： + +```markdown +## 记忆体系（会话启动必读） + +> 新会话或上下文压缩后，必须先读记忆目录的 `MEMORY.md` 索引，再按需加载文件。代码事实与项目记忆冲突时，以代码事实为准并更新项目记忆。 + +### 读取流程 +1. 读取 `{MEMORY_DIR}/MEMORY.md` 获取文件清单、类型和引用计数。 +2. **必读锚点**：{REQUIRED_MEMORY_FILES} +3. **选读锚点**：{OPTIONAL_MEMORY_FILES} +4. 若仓库使用 `.claude/memory/` 或 `.codex/memory/`，直接读取该目录；不要复制到 `.agents/memory/`。 + +### 权威优先级 +1. 当前代码、配置、测试和真实文件状态。 +2. 仓库内项目记忆：`AGENTS.md`、`CLAUDE.md`、`.claude/memory/`、`.codex/memory/` 或 `.agents/memory/`。 +3. Hermes 原生全局 `~/.hermes/memories/`（按 profile 隔离的个人跨项目记忆层，仅作辅助上下文，不是本项目事实来源）。 +``` + +区块生成规则： + +- `{MEMORY_DIR}` 必须替换为实际目录：`.claude/memory`、`.codex/memory` 或 `.agents/memory`。 +- `{REQUIRED_MEMORY_FILES}` 必须来自 `MEMORY.md` 中实际存在的 project/feedback 类型文件，通常包括 `decisions.md`、`feedback*.md`、`project_progress.md`、`project_overview.md`。 +- `{OPTIONAL_MEMORY_FILES}` 必须来自 `MEMORY.md` 中实际存在的 user/reference/synthesis/lint 类型文件，通常包括 `user_profile.md`、`reference.md`、`synthesis_*.md`、`lint_report.md`。 +- 已有 `CLAUDE.md` 记忆引导时，`AGENTS.md` 可以指向相同记忆目录，但不要复制正文。 +- 任何写入 `AGENTS.md`、`CLAUDE.md`、`MEMORY.md` 或记忆文件的动作，都必须先说明变更并等待用户确认。 + +## Phase 7 - 完成报告 + +报告包括： + +- 使用的记忆目录。 +- 是否复用了 `CLAUDE.md`、`.claude/memory/` 或 `.codex/memory/`。 +- `memory-update` 更新文件数量。 +- `memory-lint` AUTO-FIX 和 NEED-HUMAN 数量（含历史已 `` 跳过的数量）。 +- 高频引用条目候选 synthesis 升级，来自 `lint_report.md` 的「条目级高频引用 Top」；无候选时写明无候选。 +- 是否更新了 `AGENTS.md` 启动引导。 +- 未执行项或跳过项，例如未初始化 `.agents/memory/`、未更新 `AGENTS.md`、存在 NEED-HUMAN 待处理、跳过 synthesis 创建。 +- 当前 `Base commit`。 + +## 执行约束 + +1. 项目本地记忆是唯一来源。 +2. 不访问或模拟 Claude 远程记忆。 +3. 已有 Claude/Codex 项目记忆时复用，不复制、不重复生成。 +4. 不读写 Hermes 原生全局 `~/.hermes/memories/`；它们是按 profile 隔离的个人召回层，不是本套项目记忆的后端，也不摘录进项目记忆。 +5. `memory-update` 必须先于 `memory-lint`。 +6. Hermes 启动引导优先维护 `AGENTS.md`；不要为了 Hermes 强制创建或改写 `CLAUDE.md`。 +7. 修改 `AGENTS.md`、`CLAUDE.md`、`MEMORY.md` 或记忆文件前，先说明变更并取得用户确认。 +8. 记忆变更和代码变更分开执行；不要把用户未确认的代码修改混入记忆同步。 diff --git a/plugins/memcore-hermes/skills/memory-update/SKILL.md b/plugins/memcore-hermes/skills/memory-update/SKILL.md new file mode 100644 index 0000000..f694927 --- /dev/null +++ b/plugins/memcore-hermes/skills/memory-update/SKILL.md @@ -0,0 +1,199 @@ +--- +name: memory-update +description: 根据 git diff 或当前任务上下文，增量更新仓库/项目本地记忆目录和 MEMORY.md 索引。用于把代码变更、架构决策、协作反馈、外部参考和用户偏好沉淀到项目记忆中。Hermes 版本不使用远程记忆，也不写入 Hermes 原生全局 MEMORY.md/USER.md；若仓库已有 CLAUDE.md/.claude/memory/ 或 AGENTS.md/.codex/memory/，直接引用现有记忆内容，不重复创建或复制；否则使用 .agents/memory/。 +--- + +# memory-update + +按增量范围更新项目本地记忆。会话目录视为 `$PROJECT_DIR`。 + +**前置约束：先 Read `../memcore-shared/SKILL.md`**（记忆目录选择优先级 + 禁止路径 + Hermes 全局记忆避让规则 + 常量），其约束在本技能全程生效。 + +修改 `MEMORY_INDEX` 或任何记忆文件时，优先使用小范围补丁；不要整文件重写。记忆变更和代码变更必须分开说明、分开确认。 + +## Phase 1 - 读取增量锚点 + +```bash +# 主锚点：MEMORY.md 头部 _Last synced: DATE | Base commit: `HASH`_ → $ANCHOR_COMMIT +ANCHOR_COMMIT=$(grep -oE 'Base commit: `[^`]+`' "$PROJECT_MEMORY_DIR/MEMORY.md" 2>/dev/null \ + | head -1 | sed 's/Base commit: `//; s/`$//') + +# 兜底锚点：若 MEMORY.md 头部锚点丢失，取各文件 frontmatter commit 字段的最旧值 +# 防止「误删 MEMORY.md 头部 → 雪崩全量重写」 +if [ -z "$ANCHOR_COMMIT" ] || [ "$ANCHOR_COMMIT" = "N/A" ]; then + FALLBACK=$(grep -h "^commit:" "$PROJECT_MEMORY_DIR/"*.md 2>/dev/null \ + | awk '{print $2}' | sort -u) + if [ -n "$FALLBACK" ]; then + ANCHOR_COMMIT=$(git -C "$PROJECT_DIR" rev-list --topo-order $FALLBACK 2>/dev/null | tail -1) + echo "⚠ MEMORY.md 头部锚点丢失，使用兜底锚点：$ANCHOR_COMMIT（来自各文件 frontmatter 最旧 commit）" + fi +fi + +git -C "$PROJECT_DIR" rev-parse --short HEAD # → $HEAD_HASH（非 git 仓库填 N/A） +``` + +**为什么需要兜底**：`MEMORY.md` 头部的 `Base commit: HASH` 是单一来源，一旦用户手动编辑误删此行，整个 diff 范围会退化为全量，触发 update 重写所有文件。兜底机制从各文件 frontmatter 的 `commit:` 字段取**最旧值**，确保覆盖所有真实改动而不误判为无差别全量。 + +有 `ANCHOR_COMMIT`（含兜底命中）时以该提交作为差量起点；仍为空、非 git 仓库或首次初始化时执行全量审查。 + +## Phase 2 - 计算变更范围 + +```bash +[ -n "$ANCHOR_COMMIT" ] && git diff --name-only $ANCHOR_COMMIT..HEAD # → $CHANGED_FILES +``` + +无锚点时审查当前项目结构、依赖文件、现有记忆文件和本次会话明确产生的信息。 + +## Phase 3 - 更新记忆文件 + +### 维度路由（$CHANGED_FILES → 目标文件） + +| 变更内容 | 写入到 | +| --- | --- | +| 业务代码、模块边界、架构形态 | `project_overview.md`、`decisions.md` | +| 依赖文件、运行方式、工具链 | `project_overview.md` | +| 进度信号、阶段状态、待办 | `project_progress.md` | +| 用户纠正、协作规范、风格偏好 | `feedback.md` 或 `feedback_{topic}.md` | +| 外部 URL、第三方约束 | `reference.md` | +| 用户长期偏好 | `user_profile.md` | +| 高价值分析归档 | `synthesis_{type}_{topic}.md` | + +### 文件职责边界 + +| 文件 | 类型 | 写入 | 不写入 | +| --- | --- | --- | --- | +| `user_profile.md` | user | 角色、背景、长期偏好 | 任务进度 | +| `project_overview.md` | project | 技术栈、架构、目录、约定 | 可从代码直接 grep 的明细 | +| `project_progress.md` | project | 阶段、待办、里程碑 | git 流水账 | +| `decisions.md` | project | Why 格式决策 | 实现细节 | +| `feedback*.md` | feedback | 协作规范，含 Why 和 How to apply | 一次性修复 | +| `reference.md` | reference | 外部 URL 和用途 | 本地路径 | +| `synthesis_*.md` | synthesis | 高价值分析结论 | 对话逐字记录 | + +### 统一 frontmatter + +```markdown +--- +name: 文件标题 +description: 一句话描述，影响未来加载判断 +type: user | project | feedback | reference | synthesis +last_updated: YYYY-MM-DD +commit: HASH +--- +``` + +`type` 可选值包含 `lint`。`memory-update` 通常不生成 `lint_report.md`，但更新索引时必须能识别 `lint` 类型。 + +`decisions.md` 和 `feedback*.md` 条目格式： + +```markdown +## 标题 + +**结论：** xxx +**Why：** 背景、约束、历史教训 +**How to apply：** 何时适用、边界 +**See Also：** [[file.md#标题]] +``` + +`synthesis_*.md` 使用完整文件格式，至少包含 `## 背景`、`## 分析过程`、`## 结论`、`## See Also`。 + +feedback 拆分规则：当同一主题的协作规范超过 5 条，拆分到 `feedback_{topic}.md`，并在原 `feedback.md` 中保留索引或 See Also 引用。一次性修复、临时提醒和已经由代码体现的偏好不要沉淀为 feedback。 + +### Phase 3A - 交叉引用 + +新增 decisions 或 feedback 条目时： + +1. 扫描记忆目录内其他 Markdown 标题。 +2. 主题相关时，在新条目末尾追加 `[[file.md#标题]]`。 +3. 反向补链：被引用条目也追加对新条目的引用。 + +### Phase 3B - synthesis 三路触发 + +当某个 decisions 或 feedback 条目被 `SYNTHESIS_THRESHOLD`（默认 3）个以上不同文件引用，且条目中没有 `**Synthesized:**` 或 30 天内的 `` 标记时，建议升级为 `synthesis_*.md`，并等待用户确认后创建。 + +1. **会话内主动触发**：出现技术选型对比、Bug 根因分析、架构演进、安全或性能分析时，建议归档为 `synthesis_{type}_{topic}.md`。 +2. **lint 反向触发**：读取 `lint_report.md` 的「条目级高频引用 Top」，跨 `SYNTHESIS_THRESHOLD` 个以上不同源文件被引用的 decisions/feedback 条目是候选。 +3. **即时快扫触发**（见 Phase 3C）：每次 update 后扫描 `decisions.md` 和 `feedback*.md` 条目引用数，不等待下一次完整 lint。 + +synthesis 判重和免打扰： + +- 条目已有 `**Synthesized:** [[xxx.md]]` 时，视为已升级，不重复创建。 +- 条目已有 `` 且未超过 30 天时，不再提醒。 +- 用户拒绝单个候选时，在原条目末尾追加 decline 标记。 +- 用户选择 `skip-all` 时，本次 update 不再继续建议 synthesis。 +- 创建 synthesis 后，在原条目末尾追加 `**Synthesized:** [[synthesis_xxx.md]]`。 + +### Phase 3C - 即时引用计数快扫（不依赖 lint） + +每次执行 Phase 3 末尾**强制运行**。目的：在短会话或任务型对话中，不依赖 lint 的延迟触发，直接检测 synthesis 升级候选。 + +```bash +SYNTHESIS_THRESHOLD=3 # 与 memcore-shared 全局常量保持一致 + +for entry_file in "$PROJECT_MEMORY_DIR/decisions.md" "$PROJECT_MEMORY_DIR/feedback"*.md; do + [ -f "$entry_file" ] || continue + fn=$(basename "$entry_file") + while IFS= read -r title; do + # 使用 grep -F（fixed string）避免 [[ ]] 在正则中的歧义；-- 防止 title 以 - 开头被误解为选项 + count=$(grep -rlF -- "[[${fn}#${title}]]" \ + "$PROJECT_MEMORY_DIR/" --include="*.md" 2>/dev/null \ + | grep -v "^${entry_file}$" | wc -l) + [ "$count" -ge "$SYNTHESIS_THRESHOLD" ] && echo "$count|$fn#$title" + done < <(grep "^## " "$entry_file" | sed 's/^## //') +done | sort -t'|' -k1 -rn +``` + +**脚本健壮性说明**： + +- 使用 `grep -F`（fixed string）避免 `[[` `]]` 在正则中的歧义。 +- title 含中文 / 空格 / 标点时不会破坏匹配。 +- 单文件中同标题多次引用按 `-l` 仅记一次（按文件去重）。 + +对每条输出候选（`count|file#title`）： + +1. 读原条目内是否含 `**Synthesized:**` → 已升级，跳过。 +2. 读原条目内是否含 `` → 30 天内，跳过。 +3. 以上均无 → 触发提议（同 Phase 3B step 流程）。 + +**与 lint 的分工**： + +- Phase 3C（快扫）：每次 memory-update 必跑，判据为「存在引用行数」，适合即时触发。 +- lint Phase 3（精扫）：按源文件去重的精确计数，健康检查时运行。 +- 两者以 `**Synthesized:**` 标记为唯一判重依据，不重复创建文件。 +- 阈值唯一来源为 `memcore-shared` 的 `SYNTHESIS_THRESHOLD`，调整请改 `memcore-shared`。 + +### 写入要点 + +- 仅更新有变化维度，不重写无关文件。 +- frontmatter 的 `last_updated` 改今日，`commit` 改 `$HEAD_HASH`。 +- 追加为主，不删已有内容（除非过时/冲突）。 + +## Phase 4 - 更新 MEMORY.md 索引 + +索引格式： + +```markdown +# Memory Index +> _Last synced: YYYY-MM-DD | Base commit: `HASH`_ + +| 文件 | 描述 | 类型 | 引用 | Commit | +| --- | --- | --- | --- | --- | +``` + +更新规则： + +- 改过的文件同步 `Commit` 列。 +- 头部 `Last synced` 和 `Base commit` 改为今日与 `$HEAD_HASH`。 +- 新增文件的 `引用` 列先填 `0`，精确值由 `memory-lint` 刷新。 +- `引用` 值大于等于 `SYNTHESIS_THRESHOLD` 时加 `*`，例如 `5*`。 + +## 执行约束 + +1. 最小化更新，只写本次确认的变化维度。 +2. 不记录可推断内容，例如完整文件路径列表、方法签名、git 流水账。 +3. feedback 同主题超过 5 条时拆分到主题文件。 +4. 追加为主，除非内容明确过时或冲突。 +5. 如果使用的是 `.claude/memory/` 或 `.codex/memory/`，视为复用现有项目记忆；不要迁移、复制或生成重复的 `.agents/memory/`。 +6. 不把 Hermes 原生全局记忆（`~/.hermes/memories/`）当作可编辑后端；需要跨会话保留的项目事实必须写入仓库/项目内记忆。 +7. 被 `memory-sync` 调用时只返回简短摘要；独立调用时输出完整更新摘要。 +8. 记忆变更和代码变更分开执行；不要把用户未确认的代码修改混入记忆更新。 diff --git a/plugins/obsidian/plugin.json b/plugins/obsidian/plugin.json new file mode 100644 index 0000000..c732e89 --- /dev/null +++ b/plugins/obsidian/plugin.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "obsidian", + "version": "1.0.0", + "description": "Obsidian 知识库 AI 协作插件族，共十个技能：vault 管理（obsidian，含 OFM 语法速查）、全文搜索与图谱（obsidian-search）、frontmatter 元数据（obsidian-meta）、Markdown 任务与 GTD（obsidian-tasks）、每日笔记（obsidian-daily）、Bases 数据库视图（obsidian-bases）、Canvas 视觉层（obsidian-canvas）、版本历史与恢复（obsidian-history）、插件与环境配置（obsidian-plugins）、PKM 编排工作流（obsidian-workflow-pkm）。纯技能，无 MCP，无需任何配置。", + "author": { + "name": "姜顺志" + }, + "license": "MIT", + "keywords": ["obsidian", "pkm", "knowledge-management"] +} diff --git a/plugins/zentao/plugin.json b/plugins/zentao/plugin.json new file mode 100644 index 0000000..af7df8e --- /dev/null +++ b/plugins/zentao/plugin.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "zentao", + "version": "1.0.0", + "description": "禅道项目管理系统：项目集/产品/项目/执行、需求（story/epic/requirement）、Bug、任务、测试、计划与发布、反馈工单等工作流技能。MCP 连接需要在 Hermes 的 ~/.hermes/config.yaml 里手动配置 Token（见仓库 README「Hermes Agent」一节），Agent Plugins v1 协议不支持随插件包内嵌密钥。", + "author": { + "name": "蚁熊团队" + }, + "license": "MIT", + "keywords": ["zentao", "productivity", "project-management"] +}