Files

T

SkyJourneyandClaude Sonnet 5 df375117ae feat(hermes): 新增 packs/ 逐插件 pack manifest，同步记忆体系收尾

packs/*.yaml 的 ref 均锁定到上一个 commit（56ae43f），指向本次新增的
huanxi/huanxi-admin/memcore-hermes/obsidian/zentao 五个插件目录；
另加 all.yaml 支持一次性全装。同步刷新记忆文件的 commit 锚点。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015D4xWG3gRWkUKJDgyvtyJw

2026-08-25 15:40:56 +08:00

10 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

蚁熊公司内部 Claude Code Plugin Marketplace（技能市场）。开发者在此仓库中维护供全员安装使用的 Claude Code 插件（Plugin）和技能（Skill）。

目录结构

.claude-plugin/
└── marketplace.json          # 市场索引：声明本仓库包含哪些插件

plugins/
└── <plugin-name>/            # 每个插件独占一个子目录
    ├── .claude-plugin/
    │   └── plugin.json       # 插件元数据（name, description, version, author）
    └── skills/
        └── <skill-name>/
            └── SKILL.md      # 技能实现（frontmatter + Markdown 指令）

本仓库同时是 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：huanxi/huanxi-admin/obsidian/zentao 在插件根目录再放一份裸 plugin.json（不嵌套在点前缀目录里，规范要求），共用同一份 skills/；memcore 因架构差异同样走独立目录 plugins/memcore-hermes/。Hermes 没有中心化市场命令，靠 packs/ 目录下的 pack manifest（hermes plugins pack install）逐个选装，见下方「Hermes plugin.json」一节。

核心文件格式

marketplace.json（市场索引）

{
  "name": "yixiong-claude-hub",
  "owner": { "name": "蚁熊团队" },
  "description": "...",
  "plugins": [
    { "name": "<plugin-name>", "source": "./plugins/<plugin-name>", "description": "..." }
  ]
}

每新增一个插件，必须在 plugins 数组中追加对应条目。

plugin.json（插件元数据）

{
  "name": "plugin-name",
  "description": "...",
  "author": { "name": "蚁熊团队" }
}

不设 version 字段：Claude Code 自动用 git commit SHA 作为版本基准，每次推送 main 分支即为新版本，已安装用户会话启动时自动检测更新。

含 MCP Server 的插件额外支持 userConfig（用户敏感配置，存系统钥匙链）和 mcpServers（服务器声明），可在 headers 中用 ${user_config.KEY} 引用用户配置。

SKILL.md（技能实现）

---
description: 一句话说明该技能的用途（Claude 用此判断何时触发该技能）
---

技能的具体指令内容…

description 字段是触发判据，务必精确描述使用场景，避免与其他技能产生歧义。

Codex plugin.json（Codex 侧插件元数据）

用本机 ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py <plugin-path> 校验后确认的硬性约束（与 Claude 侧 plugin.json 不通用，不要照抄）：

skills 字段规整化后必须精确等于 "skills"，不能指向自定义子路径
mcpServers 若为字符串路径，必须精确等于 "./.mcp.json"，且该文件在插件根目录（不能嵌套进 .codex-plugin/）；HTTP 类型 MCP server 的 Bearer Token 用专用字段 bearer_token_env_var: "ENV_VAR_NAME"，不支持 ${VAR} 模板插值（见 decisions.md#Codex 侧 MCP Token 用 bearer_token_env_var，不用 ${VAR} 模板（2026-08-22））
顶层 interface 块必填：displayName/shortDescription/longDescription/developerName/category/capabilities/defaultPrompt
不支持 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 定义的硬性约束：

文件必须叫 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/<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）

新增插件流程

在 plugins/ 下创建目录 plugins/<plugin-name>/
创建 plugins/<plugin-name>/.claude-plugin/plugin.json
在 plugins/<plugin-name>/skills/<skill-name>/SKILL.md 编写技能
在 .claude-plugin/marketplace.json 的 plugins 数组中追加该插件条目

已发布插件

插件	技能	说明
`huanxi`	`/huanxi-shared` `/huanxi-report` `/huanxi-leader` `/huanxi-task` `/huanxi-issue` `/huanxi-meeting` `/huanxi-lookup`	寰汐企业管理系统 · 个人端（7 技能），以本人身份操作，含 MCP Server 自动配置（hxp_ Token）
`huanxi-admin`	`/huanxi-admin-shared` `/huanxi-admin-report` `/huanxi-admin-module` `/huanxi-admin-ops`	寰汐企业管理系统 · 管理端（4 技能），全量视角，需后台管理员发放 hxa_ Token，普通员工无需安装
`memcore`	`/memory-sync` `/memory-update` `/memory-lint` `/memcore-shared`（内部 include）	项目记忆体系核心引擎
`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 二次开发的 zentao-mcp 网桥，部署在 `pm.ops.yixiong-tech.com/mcp`，请求体字段统一包在 `payload` 里

五个插件均有 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 技能调用关系

/memcore-shared ← 内部 include（路径锁定 + 全局常量 + PROJECT_DIR 解析），不由用户直接调用
       ↑ Read 引用
       │
/memory-sync   ← 总编排（11 phases），调用下面两个技能
  ├── /memory-update  ← 增量写入，可独立执行
  └── /memory-lint    ← 健康校验，可独立执行

关键常量统一来源（修改 memcore-shared 一处即可全局生效）：

SYNTHESIS_THRESHOLD = 3（synthesis 升级跨文件引用阈值）
LINT_STALE_MIN_DAYS = 7（过期检测最低观察窗口，不足则跳过）
LINT_HIGH_VELOCITY = 1.0 次/天 / LINT_LOW_VELOCITY = 0.3 次/天（过期检测速度分档：全仓库提交速度 ≥ 高值 ERROR，≥ 低值 WARN）
LINT_STALE_ABSOLUTE_DAYS = 180（低速仓库的过期绝对兜底天数）
MULTI_HOST_WARN_DAYS = 7（多机不同步预警阈值）

记忆体系（会话启动必读）

每次新会话或长会话压缩后，必须先读 MEMORY.md 索引再按需加载文件。代码与记忆冲突 → 以代码为准并更新记忆。

读取流程

cat .claude/memory/MEMORY.md 获取清单
必读（type=project/feedback）：decisions.md / project_overview.md / feedback_plugin_dev.md
按需（type=lint）：lint_report.md（仅查看 NEED-HUMAN 待处理项时读）

记忆目录骨架

.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 项）
├── project_overview.md          # 项目定位与结构（huanxi/huanxi-admin/memcore/obsidian/zentao 已发布插件，均含 Codex + Hermes 支持情况）
├── feedback_plugin_dev.md       # 插件开发协作规范（含 MCP docstring 单一真相、签名变更全量扫描）
└── lint_report.md               # 记忆健康检查报告（按需）

10 KiB Raw Blame History Unescape Escape