SkyJourneyandClaude Opus 5
4ce9a92013
寰汐 v2 上线双 MCP（个人端 /mcp/ 与管理端 /admin-mcp/），两条端点是**两条独立的 信任边界**——Token 前缀不同、工具集不同、视角不同（管理端看全量、个人端只看我参与的）。 一个插件塞两套会让普通员工的客户端里出现他根本调不动的管理工具，因此拆成两个插件， 按角色各装各的。 ## huanxi（个人端，全体员工） 7 个技能：shared / report / leader / task / issue / meeting / org - 新增 `issue` `meeting`——v2 的议题域与会议域（M6v2 会议×议题解耦后的产物） - **删除 `weekly`**——v2 没有 weekly_report 表，周报已并入报告体系 - 各技能重写为**流水线定义**而非使用说明：写明工具调用顺序、ID 在步骤间怎么传、 人工确认节点落在哪。「禁止自动提交」这条 v1 已验证的硬约束保留 - 删掉 `references/` 拆分文件——v2 技能自包含 ## huanxi-admin（管理端，仅后台管理员） 4 个技能：admin-shared / admin-report / admin-module / admin-ops MCP server key 取 `huanxi-admin`（与个人端的 `huanxi` 不同名），否则两插件并存时 会键冲突。 ## 缓存目录按信任边界隔离 `~/.claude/huanxi-cache/` 下分 `personal/` `admin/` `dict/`：前两者视角不同， 混用会越权展示或数据错乱；`dict/` 与身份无关可共享。业务数据（任务/日报/会议/议题） **显式声明不缓存**——v1 没写这条，Agent 会自行决定缓存然后拿到陈旧数据。 ## 源码单一真相不在本仓库 技能源码在寰汐仓库 `skills/`，与 MCP docstring 同仓库同 commit——签名一改， 技能与工具在同一次改动里更新，从结构上消除跨仓库漂移（本仓库记忆 `feedback_plugin_dev.md` 记录的 4 类漂移覆盖全部 6 个 v1 技能，正是这个病）。 本仓库退化为**分发壳**，只接收 `python skills/sync_marketplace.py` 的产物，不手工编辑。 寰汐侧有 CI 守卫：技能里出现的每个工具名必须存在于实际注册表、个人端技能不得 指导调用管理端独有工具、不得硬编码状态字面量。 ## 本分支不合 main 插件配置的域名此刻跑的还是 v1，合进 main 会通过自动更新推给已安装用户， 他们的技能会去调 v1 上不存在的工具。合并前置条件写在 CLAUDE.md「已发布插件」节。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019Vyeia9k43dVaUFNLo8Lny
131 lines
5.8 KiB
Markdown
131 lines
5.8 KiB
Markdown
<!-- Last updated: 2026-07-10 | Commit: a13898b -->
|
||
# 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 指令）
|
||
```
|
||
|
||
## 核心文件格式
|
||
|
||
### marketplace.json（市场索引）
|
||
|
||
```json
|
||
{
|
||
"name": "yixiong-claude-hub",
|
||
"owner": { "name": "蚁熊团队" },
|
||
"description": "...",
|
||
"plugins": [
|
||
{ "name": "<plugin-name>", "source": "./plugins/<plugin-name>", "description": "..." }
|
||
]
|
||
}
|
||
```
|
||
|
||
每新增一个插件，必须在 `plugins` 数组中追加对应条目。
|
||
|
||
### plugin.json（插件元数据）
|
||
|
||
```json
|
||
{
|
||
"name": "plugin-name",
|
||
"description": "...",
|
||
"author": { "name": "蚁熊团队" }
|
||
}
|
||
```
|
||
|
||
**不设 `version` 字段**：Claude Code 自动用 git commit SHA 作为版本基准，每次推送 main 分支即为新版本，已安装用户会话启动时自动检测更新。
|
||
|
||
含 MCP Server 的插件额外支持 `userConfig`（用户敏感配置，存系统钥匙链）和 `mcpServers`（服务器声明），可在 headers 中用 `${user_config.KEY}` 引用用户配置。
|
||
|
||
### SKILL.md（技能实现）
|
||
|
||
```markdown
|
||
---
|
||
description: 一句话说明该技能的用途（Claude 用此判断何时触发该技能）
|
||
---
|
||
|
||
技能的具体指令内容…
|
||
```
|
||
|
||
`description` 字段是触发判据，务必精确描述使用场景，避免与其他技能产生歧义。
|
||
|
||
## 新增插件流程
|
||
|
||
1. 在 `plugins/` 下创建目录 `plugins/<plugin-name>/`
|
||
2. 创建 `plugins/<plugin-name>/.claude-plugin/plugin.json`
|
||
3. 在 `plugins/<plugin-name>/skills/<skill-name>/SKILL.md` 编写技能
|
||
4. 在 `.claude-plugin/marketplace.json` 的 `plugins` 数组中追加该插件条目
|
||
|
||
## 已发布插件
|
||
|
||
| 插件 | 技能 | 说明 |
|
||
|------|------|------|
|
||
| `huanxi` | `/huanxi-shared` `/huanxi-report` `/huanxi-leader` `/huanxi-task` `/huanxi-issue` `/huanxi-meeting` `/huanxi-org` | 寰汐 · **个人端**工作流，自动配置个人端 MCP（`hxp_` Token，员工在个人中心自助生成） |
|
||
| `huanxi-admin` | `/huanxi-admin-shared` `/huanxi-admin-report` `/huanxi-admin-module` `/huanxi-admin-ops` | 寰汐 · **管理端**工作流，自动配置管理端 MCP（`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） |
|
||
|
||
> **两个 huanxi 插件当前只在 `huanxi-v2` 分支上，未合 `main`。**
|
||
> 它们描述的是寰汐 **v2** 的 MCP 工具，而插件里配置的域名此刻跑的还是 **v1**——合进 main
|
||
> 会通过自动更新推给已安装用户，他们的技能会去调 v1 上不存在的工具（`dict_get` /
|
||
> `issue_create` / `meeting_query` 等），表现为一连串「工具不存在」。
|
||
>
|
||
> **合并前置条件**：v2 已部署到插件 `mcpServers` 里配置的那个域名。
|
||
> 源码单一真相在寰汐仓库 `skills/`，同步方式：`python skills/sync_marketplace.py`。
|
||
|
||
### 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` 索引再按需加载文件。代码与记忆冲突 → 以代码为准并更新记忆。
|
||
|
||
### 读取流程
|
||
|
||
1. `cat .claude/memory/MEMORY.md` 获取清单
|
||
2. **必读**（type=`project`/`feedback`）：decisions.md / project_overview.md / feedback_plugin_dev.md
|
||
3. **按需**（type=`lint`）：lint_report.md（仅查看 NEED-HUMAN 待处理项时读）
|
||
|
||
### 记忆目录骨架
|
||
|
||
```
|
||
.claude/memory/
|
||
├── MEMORY.md # 索引（入口）
|
||
├── decisions.md # 关键架构决策（含 memcore-shared/lint_report 保活/Base commit 兜底/obsidian 社区对标审查/memory-lint 速度分档过期检测等 13 项）
|
||
├── project_overview.md # 项目定位与结构（huanxi/memcore/obsidian 10 技能 已发布插件）
|
||
├── feedback_plugin_dev.md # 插件开发协作规范（含 MCP docstring 单一真相、签名变更全量扫描）
|
||
└── lint_report.md # 记忆健康检查报告（按需）
|
||
```
|
||
|