feat: 新增 huanxi 与 memcore 插件，完善 CLAUDE.md 与记忆体系
- 新增 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 <noreply@anthropic.com>
This commit is contained in:
SkyJourney
co-authored by
Claude Sonnet 4.6
Claude Sonnet 4.6
parent
0c46ed0306
commit
ab6d78b096
@@ -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 |
|
||||
@@ -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` 字段写用户实际口语触发词（第三人称描述），不要用"当需要…时触发"的内部视角表达。
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
name: 插件开发协作反馈
|
||||
description: 在此 marketplace 项目中开发插件时需遵守的协作规范和经验教训
|
||||
type: feedback
|
||||
last_updated: 2026-05-01
|
||||
commit: 0c46ed0
|
||||
---
|
||||
|
||||
# 插件开发协作规范
|
||||
|
||||
## 新增插件时必须同步更新四个位置
|
||||
|
||||
**规范**：新增插件必须同步修改：① `plugins/<name>/` 目录 ② `plugins/<name>/.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 中的工具调用。
|
||||
@@ -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）
|
||||
@@ -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/
|
||||
└── <plugin-name>/
|
||||
├── .claude-plugin/
|
||||
│ └── plugin.json # 插件元数据
|
||||
└── skills/
|
||||
└── <skill-name>/
|
||||
├── SKILL.md
|
||||
└── references/ # 可选：详细工作流文档
|
||||
```
|
||||
|
||||
## 文件格式规范
|
||||
|
||||
### marketplace.json
|
||||
```json
|
||||
{
|
||||
"name": "yixiong-claude-hub",
|
||||
"owner": { "name": "蚁熊团队" },
|
||||
"description": "...",
|
||||
"plugins": [
|
||||
{ "name": "<name>", "source": "./plugins/<name>", "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**，同事安装后需手动开启一次。
|
||||
@@ -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/)"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,3 +1,4 @@
|
||||
<!-- Last updated: 2026-05-01 | Commit: 0c46ed0 -->
|
||||
# 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 # 记忆健康检查报告（按需）
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user