feat(huanxi): 拆为个人端 / 管理端两个插件，技能全面对齐寰汐 v2
寰汐 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
This commit is contained in:
SkyJourney
co-authored by
Claude Opus 5
Claude Opus 5
parent
d7aaaf8224
commit
4ce9a92013
@@ -1,137 +1,84 @@
|
||||
---
|
||||
name: huanxi-org
|
||||
description: "寰汐组织/模块/人员查询。当用户说"我有哪些模块"、"查一下某人账号/ID"、"刷新一下缓存"、"看组织架构"、"谁在哪个模块"、"帮我找一下XXX的用户ID"时触发。提供名字→ID 解析（+resolve）、缓存刷新（+sync）、当前用户（+me）、模块列表（+modules）、组织树（+tree）。"
|
||||
description: "寰汐组织与检索：查人、查部门、全局搜索、按标签反查、团队任务看板。当用户说「XX是谁」「这个部门有哪些人」「搜一下」「团队在忙什么」时使用。"
|
||||
---
|
||||
|
||||
# 寰汐组织与人员查询
|
||||
# 寰汐组织与检索
|
||||
|
||||
**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
|
||||
**前置：先读 `huanxi-shared`。**
|
||||
|
||||
> ⚠️ **工具调用规范**：执行任何 `mcp__huanxi__*` 调用前，以工具实际注册的参数名和类型为准，本文档示例仅供工作流引导（见 shared 全局约定第 6 条）。
|
||||
本技能主要有两个职责：**把名字解析成 ID** 供其他技能使用，以及**维护缓存**。
|
||||
|
||||
---
|
||||
|
||||
## 核心能力
|
||||
## 解析 ID
|
||||
|
||||
本技能提供「名字 → ID」解析能力，是所有其他 huanxi-* 技能的依赖。所有操作**缓存优先**。
|
||||
几乎所有写操作都要 ID。顺序是：先读缓存，未命中再调工具，拿到后写回缓存。
|
||||
|
||||
```
|
||||
user_search(q="冯普") 姓名模糊搜 → 拿 id
|
||||
user_search(ids=[...]) 已知 id 批量取详情
|
||||
module_query(role?) 我参与的模块（带 my_role）
|
||||
org_tree() 组织架构树，含各部门成员姓名
|
||||
```
|
||||
|
||||
`user_search` 结果里标注了 `offboarding`（离职观察期，不宜再派新活）与 `inactive`
|
||||
（已停用）——把人派给这两类之前先提醒用户。
|
||||
|
||||
---
|
||||
|
||||
## Shortcuts
|
||||
## 全局检索
|
||||
|
||||
| 指令 | 说明 |
|
||||
|------|------|
|
||||
| [`+me`](references/resolve-ids.md#me) | 查看当前用户身份（读 me.json，缓存永久） |
|
||||
| [`+modules`](references/resolve-ids.md#modules) | 列出我参与的所有模块（24h 缓存） |
|
||||
| [`+resolve`](references/resolve-ids.md) | 把模块名/人员名解析为 ID |
|
||||
| [`+tree`](#org-tree) | 展示完整组织架构树（实时查询，不缓存） |
|
||||
| [`+sync`](#sync) | 强制刷新 modules.json + users.json 缓存 |
|
||||
```
|
||||
search(q="关键词") 一次返回六组：任务/模块/用户/标签/会议/议题，各组带总数
|
||||
```
|
||||
|
||||
不确定某个东西叫什么、在哪个模块时先用它定位，拿到 id 再调对应的 `*_get`。
|
||||
比逐个域去 query 快得多。
|
||||
|
||||
```
|
||||
tag_related(tag_id) 按标签反查五个域的关联内容
|
||||
```
|
||||
|
||||
标签是**平级横切索引**，同一个标签可以贴在用户/模块/任务/会议/议题任何一种上。
|
||||
这个工具回答「打了这个标签的所有东西都有哪些」。
|
||||
|
||||
---
|
||||
|
||||
## +me：查看当前用户身份 {#me}
|
||||
## 公告与报告
|
||||
|
||||
```
|
||||
Step 1: Read ~/.claude/huanxi-cache/me.json
|
||||
→ 若存在且有 data 字段：直接展示（永久缓存，无需检查 TTL）
|
||||
→ 若不存在：执行 Step 2
|
||||
|
||||
Step 2: mcp__huanxi__user_get_me()
|
||||
Step 3: Write ~/.claude/huanxi-cache/me.json:
|
||||
{ "cached_at": "<ISO8601>", "data": <返回值> }
|
||||
Step 4: 展示用户信息（name, feishu_user_id, 角色等）
|
||||
announcement_query(kind?, series_slug?, period_key?, ids?)
|
||||
```
|
||||
|
||||
统一入口，覆盖系统周报、周度复盘、版本发布、运维简报、人工公告。
|
||||
**只返回你有权看的**——报告按受众分档（全员/管理层/老板/本人），过滤在服务端完成，
|
||||
查不到某条不代表它不存在。
|
||||
|
||||
想看某条内置报告的历次期次，传 `series_slug`；想要具体某期，加 `period_key`。
|
||||
|
||||
---
|
||||
|
||||
## +modules：列出参与模块 {#modules}
|
||||
## 团队看板
|
||||
|
||||
```
|
||||
Step 1: Read ~/.claude/huanxi-cache/modules.json → 检查 TTL（24h）
|
||||
→ 未过期：直接展示
|
||||
→ 过期或不存在：执行 Step 2
|
||||
|
||||
Step 2: mcp__huanxi__module_list()
|
||||
Step 3: Write ~/.claude/huanxi-cache/modules.json:
|
||||
{ "cached_at": "<ISO8601>", "data": <返回值> }
|
||||
Step 4: 展示模块列表（id, name, my_role）
|
||||
people_board() 按人聚合的跨模块任务负载，**含 0 任务的人**
|
||||
```
|
||||
|
||||
「我团队现在都在忙什么」「谁比较闲」用它，比逐个 `task_query` 高效得多。
|
||||
含 0 任务的人是有意的——那正是「谁完全没有负载」这个问题的答案。
|
||||
|
||||
---
|
||||
|
||||
## +resolve：名字 → ID 解析
|
||||
## 缓存维护
|
||||
|
||||
详细流程见 [references/resolve-ids.md](references/resolve-ids.md)。
|
||||
本技能负责的三份缓存（详见 `huanxi-shared`）：
|
||||
|
||||
**快速规则：**
|
||||
- 模块名 → 先查 `modules.json`，未命中则拉 `module_list()`
|
||||
- 人员名 → 先查 `users.json`，未命中则调 `user_list(name=xxx)`，结果追加写入缓存
|
||||
- 模糊匹配时若有多个结果，列出候选项让用户选择
|
||||
| 文件 | 来源 | TTL |
|
||||
|---|---|---|
|
||||
| `personal/me.json` | `whoami` | 永久 |
|
||||
| `personal/users.json` | `user_search` | 24h |
|
||||
| `personal/my-modules.json` | `module_query` | 24h |
|
||||
| `admin/org-tree.json` | `org_tree` | 24h |
|
||||
|
||||
---
|
||||
|
||||
## +tree：组织架构树 {#org-tree}
|
||||
|
||||
```
|
||||
Step 1: mcp__huanxi__org_get_tree()（不缓存，实时查询）
|
||||
Step 2: 以树形结构展示组织架构
|
||||
```
|
||||
|
||||
> 组织架构变动相对频繁（人员入离职），不缓存，每次实时查询。
|
||||
|
||||
---
|
||||
|
||||
## +sync：强制刷新缓存 {#sync}
|
||||
|
||||
```
|
||||
Step 1: mcp__huanxi__module_list()
|
||||
→ Write ~/.claude/huanxi-cache/modules.json（强制覆盖）
|
||||
|
||||
Step 2: mcp__huanxi__user_list()（拉全量用户）
|
||||
→ Write ~/.claude/huanxi-cache/users.json（强制覆盖）
|
||||
|
||||
Step 3: 告知用户：缓存已刷新（模块 N 个，用户 M 人）
|
||||
```
|
||||
|
||||
> **何时需要 +sync**：添加新模块成员后、有新员工入职后、模块结构调整后。
|
||||
>
|
||||
> ⚠️ **Token 变更时**：若切换了寰汐账号（修改了 MCP Bearer Token），`me.json` 是永久缓存，+sync 不会更新它。需手动删除 `~/.claude/huanxi-cache/me.json`，再执行 `/huanxi-org +me` 重新获取新身份。
|
||||
|
||||
---
|
||||
|
||||
## 缓存文件结构参考
|
||||
|
||||
**me.json：**
|
||||
```json
|
||||
{
|
||||
"cached_at": "2026-04-13T09:00:00+08:00",
|
||||
"data": {
|
||||
"id": "123",
|
||||
"name": "张三",
|
||||
"feishu_user_id": "ou_xxx"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> ⚠️ 用户身份的系统内部 ID 字段名是 `id`（与后端 `user_get_me` / `user_list` 返回结构一致），不是 `user_id`。
|
||||
|
||||
**modules.json：**
|
||||
```json
|
||||
{
|
||||
"cached_at": "2026-04-13T09:00:00+08:00",
|
||||
"data": [
|
||||
{ "id": "mod_001", "name": "前端开发", "my_role": "member" },
|
||||
{ "id": "mod_002", "name": "后端API", "my_role": "leader" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**users.json：**
|
||||
```json
|
||||
{
|
||||
"cached_at": "2026-04-13T09:00:00+08:00",
|
||||
"data": [
|
||||
{ "id": "456", "name": "李四", "feishu_user_id": "ou_yyy" }
|
||||
]
|
||||
}
|
||||
```
|
||||
用户说「刷新一下」「组织变了」时，删掉对应文件重新拉取即可。
|
||||
|
||||
Reference in New Issue
Block a user