chore: sync before memory update

2026-05-01 12:04:12 +08:00
parent 1b3ae007ee
commit 0c46ed0306
22 changed files with 1850 additions and 20 deletions
@@ -0,0 +1,133 @@
+---
+name: huanxi-org
+description: "寰汐组织/模块/人员查询。当用户说"我有哪些模块"、"查一下某人账号/ID"、"刷新一下缓存"、"看组织架构"、"谁在哪个模块"、"帮我找一下XXX的用户ID"时触发。提供名字→ID 解析（+resolve）、缓存刷新（+sync）、当前用户（+me）、模块列表（+modules）、组织树（+tree）。"
+---
+
+# 寰汐组织与人员查询
+
+**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
+
+---
+
+## 核心能力
+
+本技能提供「名字 → ID」解析能力，是所有其他 huanxi-* 技能的依赖。所有操作**缓存优先**。
+
+---
+
+## 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 缓存 |
+
+---
+
+## +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, 角色等）
+```
+
+---
+
+## +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）
+```
+
+---
+
+## +resolve：名字 → ID 解析
+
+详细流程见 [references/resolve-ids.md](references/resolve-ids.md)。
+
+**快速规则：**
+- 模块名 → 先查 `modules.json`，未命中则拉 `module_list()`
+- 人员名 → 先查 `users.json`，未命中则调 `user_list(name=xxx)`，结果追加写入缓存
+- 模糊匹配时若有多个结果，列出候选项让用户选择
+
+---
+
+## +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": {
+    "user_id": "123",
+    "name": "张三",
+    "feishu_user_id": "ou_xxx"
+  }
+}
+```
+
+**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": [
+    { "user_id": "456", "name": "李四", "feishu_user_id": "ou_yyy" }
+  ]
+}
+```
@@ -0,0 +1,76 @@
+# 名字 → ID 解析
+
+本文件详细说明如何将模块名、人员名解析为系统 ID，所有步骤均**缓存优先**。
+
+---
+
+## 模块名 → 模块 ID {#modules}
+
+```
+1. Read ~/.claude/huanxi-cache/modules.json
+   → 检查 cached_at，若 age < 24h → 进入匹配逻辑
+   → 过期或不存在 → 调用 mcp__huanxi__module_list() 并写入缓存
+
+2. 匹配逻辑：
+   a. 精确匹配 name == 输入 → 返回 id
+   b. 精确匹配失败 → 模糊匹配（name.includes(输入) 或 输入.includes(name)）
+   c. 模糊匹配唯一命中 → 确认并返回 id
+   d. 多个候选 → 列出候选项，让用户选择
+   e. 零命中 → 告知用户，建议运行 +sync 刷新缓存
+```
+
+**示例：**
+- 用户说"前端模块" → 从缓存匹配到 `{ id: "mod_001", name: "前端开发" }` → 返回 `mod_001`
+- 用户说"API" → 匹配到 `后端API` → 返回 `mod_002`
+- 匹配到多个 → 展示候选列表
+
+---
+
+## 人员名 → 用户 ID {#users}
+
+```
+1. Read ~/.claude/huanxi-cache/users.json
+   → 检查 cached_at，若 age < 24h → 在 data 数组中查找
+
+2. 查找逻辑：
+   a. name 精确匹配 → 返回 user_id
+   b. name 包含输入 → 列出候选
+   c. 未找到 → 执行 Step 3
+
+3. 缓存未命中时：
+   a. 调用 mcp__huanxi__user_list(name=<输入>)
+   b. 将结果追加（合并去重）写入 users.json（不覆盖已有缓存）
+   c. 重新执行 Step 2 匹配逻辑
+
+4. 仍未找到 → 告知用户姓名不存在，建议确认拼写或运行 +sync
+```
+
+**特别注意：**
+- `user_id`（系统内部 ID）≠ `feishu_user_id`（飞书 open_id）
+- 设置任务执行人用 `user_id`
+- 飞书消息通知用 `feishu_user_id`（MCP 内部会自动处理，无需手动区分）
+
+---
+
+## 自动 ID 解析流程（综合示例）
+
+当用户说"创建任务，负责人是李四，模块是前端开发"时：
+
+```
+1. 解析模块 → read modules.json → 匹配"前端开发" → mod_001
+2. 解析人员 → read users.json → 匹配"李四" → user_id: 456
+3. 若任一缓存未命中：先拉 MCP，写缓存，再继续
+4. 两个 ID 都拿到后 → 调用 task_create(module_id="mod_001", ...)
+5. 创建完成后 → task_set_assignees(task_id, ["456"])
+```
+
+---
+
+## 常见错误处理
+
+| 情况 | 处理 |
+|------|------|
+| 多个同名用户 | 展示完整名单（含部门/角色），让用户指定 |
+| 模块名拼写不完整 | 模糊匹配，确认后继续 |
+| 缓存文件损坏（JSON 解析失败）| 忽略缓存，直接调 MCP，重建文件 |
+| MCP 返回空列表 | 告知用户，建议检查 Token 权限或联系管理员 |