From ab6d78b0960567f5cd188aa65ce261a1c429448e Mon Sep 17 00:00:00 2001 From: SkyJourney Date: Fri, 1 May 2026 12:12:08 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=20huanxi=20=E4=B8=8E?= =?UTF-8?q?=20memcore=20=E6=8F=92=E4=BB=B6=EF=BC=8C=E5=AE=8C=E5=96=84=20CL?= =?UTF-8?q?AUDE.md=20=E4=B8=8E=E8=AE=B0=E5=BF=86=E4=BD=93=E7=B3=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 plugins/huanxi：Bearer Token 模式 MCP Server + 6 个工作流技能 （日报/负责人日报/周报/任务/组织），修正全部 MCP 工具签名 - 新增 plugins/memcore：memory-sync/update/lint 三技能记忆引擎， 修正 git add 范围避免误提交敏感文件 - CLAUDE.md：移除 version 字段示例，补充 userConfig/mcpServers 说明， 注入「记忆体系（会话启动必读）」区块 - .claude/memory/：初始化项目记忆索引（decisions/project_overview/ feedback_plugin_dev/lint_report） Co-Authored-By: Claude Sonnet 4.6 --- .claude/memory/MEMORY.md | 9 ++++ .claude/memory/decisions.md | 60 +++++++++++++++++++++ .claude/memory/feedback_plugin_dev.md | 57 ++++++++++++++++++++ .claude/memory/lint_report.md | 32 ++++++++++++ .claude/memory/project_overview.md | 75 +++++++++++++++++++++++++++ .claude/settings.local.json | 8 +++ CLAUDE.md | 27 +++++++++- 7 files changed, 266 insertions(+), 2 deletions(-) create mode 100644 .claude/memory/MEMORY.md create mode 100644 .claude/memory/decisions.md create mode 100644 .claude/memory/feedback_plugin_dev.md create mode 100644 .claude/memory/lint_report.md create mode 100644 .claude/memory/project_overview.md create mode 100644 .claude/settings.local.json diff --git a/.claude/memory/MEMORY.md b/.claude/memory/MEMORY.md new file mode 100644 index 0000000..0698272 --- /dev/null +++ b/.claude/memory/MEMORY.md @@ -0,0 +1,9 @@ +# Memory Index +> _Last synced: 2026-05-01 | Base commit: `0c46ed0`_ + +| 文件 | 描述 | 类型 | 引用 | Commit | +|------|------|------|------|--------| +| decisions.md | 关键架构决策：无版本号/userConfig/Bearer Token/SKILL.md规范 | project | 1 | 0c46ed0 | +| project_overview.md | 项目定位、目录结构、插件规范、发布流程 | project | 1 | 0c46ed0 | +| feedback_plugin_dev.md | 插件开发协作规范：同步四处/路径解析/工具签名对照 | feedback | 0 | 0c46ed0 | +| lint_report.md | memory-lint 最新执行结果 | lint | 0 | 0c46ed0 | diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md new file mode 100644 index 0000000..34bb171 --- /dev/null +++ b/.claude/memory/decisions.md @@ -0,0 +1,60 @@ +--- +name: 架构决策 +description: Marketplace 设计中的关键技术决策及其原因 +type: project +last_updated: 2026-05-01 +commit: 0c46ed0 +--- + +# 关键架构决策 + +## plugin.json 不设 version 字段 + +**结论**：所有 plugin.json 均不含 `version` 字段。 + +**Why**：Claude Code 官方文档说明，若 plugin.json 设置了固定 `version`，推送新 commit 不改 version 字符串时，已安装用户看不到更新。省略 version 后，Claude Code 自动用 git commit SHA 做版本判断，每次推送 main 分支即为新版本。 + +**How to apply**：新增插件时不要加 `version` 字段。memcore 和 huanxi 均已按此规范执行。 + +--- + +## huanxi plugin 使用 userConfig 而非环境变量传 Token + +**结论**：`plugin.json` 用 `userConfig` + `sensitive: true` 声明 Bearer Token 输入，`mcpServers.headers` 中用 `${user_config.token}` 引用。 + +**Why**：`sensitive: true` 将 token 存入系统钥匙链（或 `~/.claude/.credentials.json`），不会出现在 settings.json 中，避免随仓库提交泄露。Claude Code 安装插件时自动弹窗提示用户输入，体验好于环境变量。 + +**How to apply**：其他需要用户配置 API Key/Token 的插件，均应使用此模式，不要用 `${ENV_VAR}` 方式。 + +```json +"userConfig": { + "token": { + "type": "string", + "title": "寰汐 Personal Token", + "description": "在寰汐系统后台生成，hxp_ 前缀", + "sensitive": true + } +} +``` + +**See Also**：[[project_overview.md#已发布插件]] + +--- + +## huanxi MCP Server 认证：Bearer Token 直连，不改后端 + +**结论**：plugin.json 配置 `Authorization: Bearer ${user_config.token}` header，MCP server 已有的 `_PersonalTokenVerifier` 直接验证 `hxp_` token，无需改后端。 + +**Why**：后端已有 ASGI 中间件模式（AdminMcpAuthMiddleware）和 PersonalTokenVerifier，Bearer Token 天然支持。OAuth2 Discovery Flow 是 FastMCP 框架层的特性，当客户端直接在 header 中传 Bearer Token 时可绕过 OAuth 流程。改后端风险高且无必要。 + +**How to apply**：未来新增 MCP server 插件时，只需在 plugin.json 配置 header，不需要修改后端认证逻辑。 + +--- + +## SKILL.md frontmatter 只保留 name 和 description + +**结论**：SKILL.md frontmatter 只写 `name` 和 `description` 两个字段，去掉 `version`。 + +**Why**：Claude Code 插件规范中 SKILL.md frontmatter 只定义了 `name` 和 `description`。`version` 字段不在规范内，silently ignored，且与 plugin.json 层面的版本管理重复。已从所有 huanxi skill 文件中移除。 + +**How to apply**：新建 SKILL.md 时只写这两个字段。`description` 字段写用户实际口语触发词（第三人称描述），不要用"当需要…时触发"的内部视角表达。 diff --git a/.claude/memory/feedback_plugin_dev.md b/.claude/memory/feedback_plugin_dev.md new file mode 100644 index 0000000..0025c83 --- /dev/null +++ b/.claude/memory/feedback_plugin_dev.md @@ -0,0 +1,57 @@ +--- +name: 插件开发协作反馈 +description: 在此 marketplace 项目中开发插件时需遵守的协作规范和经验教训 +type: feedback +last_updated: 2026-05-01 +commit: 0c46ed0 +--- + +# 插件开发协作规范 + +## 新增插件时必须同步更新四个位置 + +**规范**：新增插件必须同步修改：① `plugins//` 目录 ② `plugins//.claude-plugin/plugin.json` ③ `.claude-plugin/marketplace.json` 的 plugins 数组 ④ `CLAUDE.md` 的已发布插件表格。 + +**Why**：marketplace.json 是 Claude Code 的安装入口，CLAUDE.md 是新会话的参考文档，两者不更新会导致插件不可被发现。 + +**How to apply**：每次创建插件后用 checklist 验证四处都已修改。 + +--- + +## cp -r 复制目录时注意目标路径存在与否 + +**规范**：用 `cp -r source/ dest/` 复制 skill 目录时，若 `dest/` 目录不存在，source 内容会直接成为 `dest/`（而非 `dest/source/`）。 + +**Why**：本次将 huanxi-shared 复制到 skills/ 目录时，因为 skills/ 不存在，SKILL.md 直接落在了 skills/ 下而非 skills/huanxi-shared/ 下，需要手动修复。 + +**How to apply**：多目录批量复制时，先 `mkdir -p` 目标目录，再逐个 `cp -r`；或改用第一个 `cp -r` 后检查结构。 + +--- + +## 引入 Skill 相对路径时需考虑运行时路径解析 + +**规范**：SKILL.md 中引用其他 skill 文件时使用 `../sibling-skill/SKILL.md` 的相对路径（如 huanxi-* 系列引用 huanxi-shared），这种模式在 Claude Code 插件的 skill 目录结构下是可行的，但依赖 Claude 正确解析路径。 + +**Why**：validator 审查时指出相对路径存在解析风险，但由于 huanxi-* 系列已在用户本地以相同目录结构正常工作，打包后一致性可保持。 + +**How to apply**：若未来发现 Read 相对路径失败，改为在每个 skill 内联关键共享规则（工具签名表、缓存 TTL），降低对 Read 成功的依赖。 + +--- + +## SKILL.md description 使用用户口语，不用内部视角 + +**规范**：frontmatter 的 `description` 字段应描述用户会说的话（"我有哪些模块"、"帮我写日报"），不要写内部触发条件（"当需要解析模块名/人员名为 ID 时触发"）。 + +**Why**：description 是 Claude Code 判断何时触发该技能的依据，也是展示给用户的摘要。内部视角语言对用户无意义，且不能有效触发。 + +**How to apply**：新建 skill 时，先想"用户实际会怎么说这个需求"，用这些词写 description。 + +--- + +## plugin-validator 和 skill-reviewer 审查之后要对照实际代码修正工具签名 + +**规范**：Plugin 审查发现工具名称错误时（如 report_submit vs report_submit_item），必须回到源代码（`huanxi_mcp/tools/*.py`）确认实际函数签名，以代码为准修正 skill 描述。 + +**Why**：本次发现 huanxi-shared 工具索引中 report_submit/withdraw 用了旧名，leader_report_submit/withdraw 缺必填参数，weekly_report_save 参数名用 week 而非 week_number，这些都是 MCP 升级后 skill 未同步导致的。 + +**How to apply**：每次 MCP server 工具链升级后，运行 plugin-validator 对照检查 skill 中的工具调用。 diff --git a/.claude/memory/lint_report.md b/.claude/memory/lint_report.md new file mode 100644 index 0000000..aec2926 --- /dev/null +++ b/.claude/memory/lint_report.md @@ -0,0 +1,32 @@ +--- +name: 记忆健康检查报告 +description: memory-lint 最新一次执行的检查结果与待处理项 +type: lint +last_updated: 2026-05-01 +--- + +# 记忆健康检查报告 + +> _执行时间: 2026-05-01 | Base commit: `0c46ed0` | Last synced: 2026-05-01_ + +## 健康概览 + +| 检查项 | AUTO-FIX | NEED-HUMAN | +|--------|---------|-----------| +| 1 孤儿 / 2 幽灵 / 3A 引用 / 3B 双链 | 0 / 0 / 0 / 1 | — / — / 0 / 0 | +| 4 矛盾 / 5 过期 / 6 污染 | — | 0 / 0 / 0 | + +**AUTO-FIX 已执行 1 项 | NEED-HUMAN 待处理 0 项** + +--- + +## AUTO-FIX 已执行清单 + +- [x] 补入反向链接：`project_overview.md → ## 已发布插件` 末尾追加 `See Also: [[decisions.md#...]]` +- [x] MEMORY.md「引用」列已刷新（3 文件，按引用倒序） + +--- + +## 条目级高频引用 Top（供 /memory-update 消费） + +无候选（所有条目跨文件引用次数 < 3） diff --git a/.claude/memory/project_overview.md b/.claude/memory/project_overview.md new file mode 100644 index 0000000..8578cdc --- /dev/null +++ b/.claude/memory/project_overview.md @@ -0,0 +1,75 @@ +--- +name: 项目概述 +description: yixiong-claude-marketplace 的定位、目录结构、插件规范和发布流程 +type: project +last_updated: 2026-05-01 +commit: 0c46ed0 +--- + +# 蚁熊内部 Claude Code Marketplace + +## 定位 + +蚁熊公司内部 Claude Code Plugin Marketplace（技能市场），统一管理和发布供全员安装的 Claude Code 插件与技能。Marketplace 名称：`yixiong-claude-hub`。 + +## 目录结构 + +``` +.claude-plugin/ +└── marketplace.json # 市场索引：声明所有插件 + +plugins/ +└── / + ├── .claude-plugin/ + │ └── plugin.json # 插件元数据 + └── skills/ + └── / + ├── SKILL.md + └── references/ # 可选：详细工作流文档 +``` + +## 文件格式规范 + +### marketplace.json +```json +{ + "name": "yixiong-claude-hub", + "owner": { "name": "蚁熊团队" }, + "description": "...", + "plugins": [ + { "name": "", "source": "./plugins/", "description": "..." } + ] +} +``` + +### plugin.json（关键字段） +- **无 `version` 字段**：用 git commit SHA 作为版本基准，每次推送 main 即发布 +- `userConfig`：用于用户输入敏感配置（token 等），`sensitive: true` 存系统钥匙链 +- `mcpServers`：声明 MCP 服务器，headers 中可用 `${user_config.KEY}` 替换 + +### SKILL.md frontmatter（只需两字段） +```yaml +--- +name: skill-name +description: "触发描述（用户实际口语，不用内部视角）" +--- +``` +- **不写 `version`**：version 不是 SKILL.md 规范字段 + +## 已发布插件 + +| 插件 | 技能 | 特性 | +|------|------|------| +| `huanxi` | 6 个（report/leader/task/weekly/org/shared） | userConfig Bearer Token + MCP Server | +| `memcore` | 3 个（memory-sync/lint/update） | 纯技能，无 MCP | + +**See Also**：[[decisions.md#huanxi plugin 使用 userConfig 而非环境变量传 Token]] + +## 发布流程 + +1. 新增/修改插件内容 +2. 提交 main 分支（`git push`） +3. 已安装用户会话启动时自动检测更新（需用户先手动开启 auto-update 一次：`/plugin` → Marketplaces → Enable auto-update） +4. 有更新时提示执行 `/reload-plugins` + +**第三方 marketplace 默认关闭 auto-update**，同事安装后需手动开启一次。 diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..0cd2d2e --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,8 @@ +{ + "permissions": { + "allow": [ + "Bash(mkdir -p ~/.claude/projects/C--Projects-yixiong-claude-marketplace/memory/)", + "Bash(cp -pf \"C:/Projects/yixiong-claude-marketplace/.claude/memory/\"*.md ~/.claude/projects/C--Projects-yixiong-claude-marketplace/memory/)" + ] + } +} diff --git a/CLAUDE.md b/CLAUDE.md index d26793f..27513e2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,4 @@ + # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. @@ -44,12 +45,13 @@ plugins/ { "name": "plugin-name", "description": "...", - "version": "1.0.0", "author": { "name": "蚁熊团队" } } ``` -版本遵循 SemVer：修改技能内容 → patch，新增技能 → minor，破坏性变更 → major。 +**不设 `version` 字段**：Claude Code 自动用 git commit SHA 作为版本基准，每次推送 main 分支即为新版本，已安装用户会话启动时自动检测更新。 + +含 MCP Server 的插件额外支持 `userConfig`（用户敏感配置，存系统钥匙链）和 `mcpServers`（服务器声明），可在 headers 中用 `${user_config.KEY}` 引用用户配置。 ### SKILL.md（技能实现） @@ -85,3 +87,24 @@ description: 一句话说明该技能的用途（Claude 用此判断何时触发 └── /memory-lint ← 健康校验，可独立执行 ``` +## 记忆体系（会话启动必读） + +> 每次新会话或长会话压缩后，必须先读 `MEMORY.md` 索引再按需加载文件。代码与记忆冲突 → 以代码为准并更新记忆。 + +### 读取流程 + +1. `cat .claude/memory/MEMORY.md` 获取清单 +2. **必读**（type=`project`/`feedback`）：decisions.md / feedback_plugin_dev.md / project_overview.md +3. **按需**（type=`lint`）：lint_report.md + +### 记忆目录骨架 + +``` +.claude/memory/ +├── MEMORY.md # 索引（入口） +├── decisions.md # 关键架构决策 +├── project_overview.md # 项目定位与结构 +├── feedback_plugin_dev.md # 插件开发协作规范 +└── lint_report.md # 记忆健康检查报告（按需） +``` +