2.6 KiB
2.6 KiB
名字 → ID 解析
本文件详细说明如何将模块名、人员名解析为系统 ID，所有步骤均缓存优先。
模块名 → 模块 ID
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
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 权限或联系管理员 |