Compare commits
2
Commits
106c394a46
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 SkyJourneyandClaude Sonnet 5
|
437ab425be | ||
|
SkyJourneyandClaude Sonnet 5
|
9e1dcf6634 |
@@ -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网桥双认证格式兼容/Hermes插件骨架与packs选装 | project | 3* | 56ae43f |
|
||||
| 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选装/Hermes安全扫描description限制/Hermes MCP session-id已知bug | project | 3* | 9e1dcf6 |
|
||||
| project_overview.md | 项目定位、目录结构、插件规范、发布流程（huanxi/huanxi-admin/memcore/obsidian/zentao，均含 Codex + Hermes 支持情况） | project | 2 | 56ae43f |
|
||||
| feedback_plugin_dev.md | 插件开发协作规范：同步四处/路径解析/工具签名对照/MCP docstring单一真相/签名变更全量扫描 | feedback | 2 | 38beecb |
|
||||
| lint_report.md | memory-lint 最新执行结果 | lint | 0 | a64c646 |
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
name: 架构决策
|
||||
description: Marketplace 设计中的关键技术决策及其原因：无版本号/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选装
|
||||
description: Marketplace 设计中的关键技术决策及其原因：无版本号/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选装/Hermes安全扫描description限制/Hermes MCP session-id已知bug
|
||||
type: project
|
||||
last_updated: 2026-08-25
|
||||
commit: 56ae43f
|
||||
commit: 9e1dcf6
|
||||
---
|
||||
|
||||
# 关键架构决策
|
||||
@@ -231,6 +231,30 @@ commit: 56ae43f
|
||||
|
||||
**Why**：调研过程中依次排除了三条路径——① `hermes plugins install owner/repo` 无 subdir 支持（用户质疑"仓库多插件不合理"后深挖才找到 pack 机制，此前调研不够）；② 自建 `plugins.index_url` 覆盖官方社区索引会让用户暂时搜不到 NousResearch 官方索引里的插件，属单值配置非叠加，用户认为代价太大；③ 最终定为每插件一个 `packs/<name>.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 里标注为待用户实测项，反馈后再回来更新文档措辞。
|
||||
**How to apply**：Hermes 的 `ref` 字段要求精确 40 位 commit SHA、不接受分支名，`packs/*.yaml` 需要在每次相关内容发布后手动 bump（不像 Claude Code 的 git SHA 自动追新）。两处此前未经验证的点已由用户用真实 Hermes 实测确认：① `pack install` 支持直接传 http(s) raw 链接，不用先 clone；② `subdir` 定位的目录只有 `plugin.json`（没有原生 `plugin.yaml`）能被正确安装（前提是通过安全扫描，见 [[decisions.md#Hermes 插件安装安全扫描：plugin.json description 不能含配置路径字面量（2026-08-25）]]）。
|
||||
|
||||
**See Also**：[[project_overview.md#已发布插件]]
|
||||
**See Also**：[[project_overview.md#已发布插件]]、[[decisions.md#Hermes 插件安装安全扫描：plugin.json description 不能含配置路径字面量（2026-08-25）]]、[[decisions.md#Hermes MCP Streamable HTTP session-id 已知 bug——凭证类插件连接受阻（2026-08-25）]]
|
||||
|
||||
---
|
||||
|
||||
## Hermes 插件安装安全扫描：plugin.json description 不能含配置路径字面量（2026-08-25）
|
||||
|
||||
**结论**：huanxi/huanxi-admin/zentao 的 `plugin.json` `description` 字段精简为一句话简介，删除了原先写的 `~/.hermes/config.yaml` 等操作指引文字；具体配置步骤只保留在 README 里。
|
||||
|
||||
**Why**：用户实测 `hermes plugins pack install` 被安全扫描 BLOCKED——Hermes 官方文档确认 community source（非 Nous 官方审核）插件的扫描是零容忍策略，任意 1 个 finding 就拒绝安装且 `--force` 无法覆盖；报错精确指向 `plugin.json:5`（description 字段），命中的是 `CRITICAL persistence` 类别。description 里字面写的 `~/.hermes/config.yaml`（点前缀配置文件路径字符串）大概率撞上了扫描器针对"持久化/自我修改配置"模式的启发式规则——这类字符串常见于恶意插件描述自己如何篡改用户配置实现驻留，扫描器无法区分"教用户怎么手动配置"和"指导 AI 怎么植入后门"两种语义。
|
||||
|
||||
**How to apply**：任何 Hermes 插件（尤其面向 community source 分发的）的 `plugin.json` description 只写功能简介，不要出现具体文件路径（尤其 `~/.` 开头的配置/凭证类路径）、shell 命令片段或操作步骤——这类内容一律放 README，不进 plugin.json。遇到 BLOCKED 报错时先看 `Verdict`/`findings` 指向的具体文件和行号，大概率能定位到触发字符串。
|
||||
|
||||
**See Also**：[[decisions.md#Hermes 插件骨架：Agent Plugins v1 + packs 选装（2026-08-25）]]
|
||||
|
||||
---
|
||||
|
||||
## Hermes MCP Streamable HTTP session-id 已知 bug——凭证类插件连接受阻（2026-08-25）
|
||||
|
||||
**结论**：huanxi/huanxi-admin/zentao 在 Hermes 上配置 HTTP 类型 MCP Server 后，`initialize` 握手能成功，但后续请求会报 400 并最终 park 连接。用 curl 直连 zentao-mcp 网桥验证过网桥本身没问题（认证正常、`initialize` 返回 200 且带 `mcp-session-id`），判断是 Hermes 客户端未正确捕获/回传 Streamable HTTP 协议要求的 `mcp-session-id`，与 [NousResearch/hermes-agent#20349](https://github.com/NousResearch/hermes-agent/issues/20349) 描述的现象一致。用户决定暂不深究 workaround，等 Hermes 上游修复。
|
||||
|
||||
**Why**：MCP Streamable HTTP 传输协议是有状态会话——服务器在 `initialize` 响应头里下发 `mcp-session-id`，客户端后续请求必须原样带回 `Mcp-Session-Id` 请求头，服务器才认下一步请求；curl 手工构造带完整 header 的请求能跑通全流程，排除了网桥端的问题。`protocol: legacy`/`skip_preflight: true` 都试过无效，因为问题出在握手**之后**的会话保持，不是握手协商本身。
|
||||
|
||||
**How to apply**：这不是我们插件配置能修的问题，不要在 plugin.json/pack/README 里继续折腾 MCP 相关参数试图绕过。定期检查 [#20349](https://github.com/NousResearch/hermes-agent/issues/20349) 状态，Hermes 发布修复版本后回来验证并更新 README 里的已知问题说明；`obsidian`/`memcore-hermes` 不含 MCP，不受影响，可以正常使用。
|
||||
|
||||
**See Also**：[[decisions.md#Hermes 插件骨架：Agent Plugins v1 + packs 选装（2026-08-25）]]
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
<!-- Last updated: 2026-08-25 | Commit: 56ae43f -->
|
||||
<!-- Last updated: 2026-08-25 | Commit: 9e1dcf6 -->
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
@@ -87,8 +87,9 @@ description: 一句话说明该技能的用途（Claude 用此判断何时触发
|
||||
- 必需字段只有 `$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/<name>.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）]]
|
||||
- 单仓库多插件靠 `hermes plugins pack install ./packs/<name>.yaml` 的 `subdir` 字段定位子目录，`ref` 必须是精确 40 位 commit SHA（不接受分支名），改动插件后要记得同步 bump `packs/*.yaml` 里的 `ref`；`pack install` 已实测确认支持直接传 http(s) raw 链接，也确认纯 `plugin.json`（无原生 `plugin.yaml`）能被正确安装
|
||||
- **`description` 字段不要写配置文件路径字面量**（如 `~/.hermes/config.yaml`）——Hermes 对 community source 插件的安装前安全扫描零容忍，命中一次就 BLOCKED、`--force` 不能覆盖，此类路径字符串容易被误判成 persistence 危险模式，见 [[decisions.md#Hermes 插件安装安全扫描：plugin.json description 不能含配置路径字面量（2026-08-25）]]
|
||||
- **已知问题**：huanxi/huanxi-admin/zentao 的 HTTP MCP 在 Hermes 上会因为 Streamable HTTP `mcp-session-id` 回传 bug 连不上（[NousResearch/hermes-agent#20349](https://github.com/NousResearch/hermes-agent/issues/20349)），非我们插件问题，等上游修复，见 [[decisions.md#Hermes MCP Streamable HTTP session-id 已知 bug——凭证类插件连接受阻（2026-08-25）]]
|
||||
|
||||
## 新增插件流程
|
||||
|
||||
@@ -142,7 +143,7 @@ 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 网桥双认证格式兼容/Hermes 插件骨架与 packs 选装等 18 项）
|
||||
├── decisions.md # 关键架构决策（含 memcore-shared/lint_report 保活/Base commit 兜底/obsidian 社区对标审查/memory-lint 速度分档过期检测/Codex 插件骨架与 memcore-codex 独立目录/bearer_token_env_var/不做 Antigravity 兼容/zentao-mcp 网桥双认证格式兼容/Hermes 插件骨架与 packs 选装/Hermes 安全扫描 description 限制/Hermes MCP session-id 已知 bug 等 20 项）
|
||||
├── project_overview.md # 项目定位与结构（huanxi/huanxi-admin/memcore/obsidian/zentao 已发布插件，均含 Codex + Hermes 支持情况）
|
||||
├── feedback_plugin_dev.md # 插件开发协作规范（含 MCP docstring 单一真相、签名变更全量扫描）
|
||||
└── lint_report.md # 记忆健康检查报告（按需）
|
||||
|
||||
@@ -68,20 +68,27 @@ Hermes（Nous Research 开源的本地 Agent）没有像 Claude/Codex 那样的"
|
||||
**安装（想装哪个装哪个，互不影响）：**
|
||||
|
||||
```bash
|
||||
# 方式一：先看会装什么，再装（本地路径，需要先 clone）
|
||||
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 show ./packs/zentao.yaml # 先看会装什么
|
||||
hermes plugins pack install ./packs/zentao.yaml # 确认后装（想装别的插件换文件名）
|
||||
# 方式二：不用 clone，直接传 raw 链接（已验证可用）
|
||||
hermes plugins pack install https://gitea.rk-health.com/yixiong/yixiong-claude-marketplace/raw/branch/main/packs/zentao.yaml
|
||||
```
|
||||
|
||||
想一次装全部五个：`hermes plugins pack install ./packs/all.yaml`。
|
||||
|
||||
装的插件是**用户/profile 级**的，不是项目级——Hermes 的 `plugins install`/`pack install` 都没有 `--scope`/`--project` 之类的参数，固定装进 `$HERMES_HOME/plugins/`（默认 profile 就是 `~/.hermes/plugins/`），装完之后在这台机器的哪个目录开 Hermes 会话都能用，跟"只在这个仓库目录里生效"的直觉不一样。
|
||||
|
||||
> ⚠️ **`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 装一次就知道了。
|
||||
> ⚠️ **`plugin.json` 的 `description` 不要写配置路径字面量**——Hermes 对 community source（非官方审核）插件的安装前安全扫描是"零容忍"策略，任意 1 个 finding 就直接 BLOCKED、`--force` 也无法覆盖；早期版本我们在 description 里写了 `~/.hermes/config.yaml` 这种点前缀路径字符串，被误判成 persistence（持久化）类危险模式挡了下来。现在 description 只放一句话简介，配置指令都放在这份 README 里，不会再触发。
|
||||
>
|
||||
> ⚠️ **已知问题（非我们插件的锅，等 Hermes 上游修复）**：`huanxi`/`huanxi-admin`/`zentao` 走 HTTP 类型 MCP Server，实测在 Hermes 上会卡在 `initialize` 握手之后——网桥正确返回了 `mcp-session-id`（Streamable HTTP 协议的有状态会话标识），但 Hermes 客户端没有正确捕获/回传这个 session id，导致后续请求被判定为无效、报 400，最终连接被 park。这跟 [NousResearch/hermes-agent#20349](https://github.com/NousResearch/hermes-agent/issues/20349) 描述的现象一致，用 curl 直连网桥验证过网桥本身没问题（认证、握手响应都正常）。装完插件后如果 MCP 连不上，先去这条 issue 底下看有没有新版本修复，`protocol: legacy` 试过没用（握手本身不是问题所在）；`obsidian`/`memcore-hermes` 不受影响（不含 MCP）。
|
||||
|
||||
## 插件一览
|
||||
|
||||
|
||||
Reference in New Issue
Block a user