---
name: huanxi-shared
description: "寰汐 MCP 共享基础：本地缓存策略（me/modules/users/workdays）、TTL 规则、缓存读写伪代码、MCP 工具索引。所有 huanxi-* 技能必须先 Read 本文件，再执行各自工作流。"
---

# 寰汐 MCP 共享规则

本技能是所有 `huanxi-*` 技能的**必读前置**，定义缓存策略、工具索引和全局约定。

---

## 必读声明

**所有 huanxi-* 技能开头都必须先 `Read` 本文件（`../huanxi-shared/SKILL.md`），再执行各自工作流。**

---

## 本地缓存机制

缓存文件统一存放在 `~/.claude/huanxi-cache/`。

### 缓存文件清单

| 文件 | 内容 | TTL | 刷新方式 |
|------|------|-----|---------|
| `me.json` | 当前用户身份（user_id, name, feishu_user_id） | 永久 | 手动删除文件 |
| `modules.json` | 我参与的模块列表（id, name, my_role） | 24h | 过期自动重拉 或 `/huanxi-org +sync` |
| `users.json` | 组织用户搜索结果（name/feishu_user_id 索引） | 24h | 过期自动重拉 或 `/huanxi-org +sync` |
| `workdays.json` | 工作日查询结果（date → bool 的 KV 字典） | 永久（按日期 key） | 已有日期不重新查 |

### 缓存读写伪代码

**读缓存（每次使用 MCP 数据前执行此逻辑）：**

```
function read_cache(file, ttl_hours):
  1. Read ~/.claude/huanxi-cache/{file}.json
  2. 若文件不存在 → cache_miss
  3. 读取 cached_at 字段，计算 age = now - cached_at（小时）
  4. 若 ttl_hours = Infinity 或 age < ttl_hours → 返回 data 字段（cache_hit）
  5. 否则 → cache_miss

function cache_miss_handler(tool_name, params):
  1. 调用 MCP 工具：mcp__huanxi__{tool_name}(params)
  2. Write ~/.claude/huanxi-cache/{file}.json:
     { "cached_at": "<当前 ISO8601 时间>", "data": <MCP 返回值> }
  3. 返回 data
```

**workdays.json 特殊逻辑（按 key 缓存）：**

```
function get_workday(date):
  1. Read workdays.json → 得到 { "2026-04-14": true, ... }
  2. 若 date 已在 dict 中 → 直接返回
  3. 否则 → 调用 mcp__huanxi__system_get_workday(date)
  4. 将 {date: result} 追加写入 workdays.json
```

### TTL 快速参考

```
me.json       → Infinity（永久，身份不变）
modules.json  → 24h
users.json    → 24h
workdays.json → Infinity（按 date key，已查过的不再查）
```

---

## MCP 工具索引

寰汐 MCP 工具前缀：`mcp__huanxi__`

### 用户与认证
| 工具 | 用途 | 缓存 |
|------|------|------|
| `user_get_me()` | 获取当前 Token 代表的用户 | → `me.json`（永久）|

### 模块与组织
| 工具 | 用途 | 缓存 |
|------|------|------|
| `module_list(my_role?)` | 列出我参与的模块 | → `modules.json`（24h）|
| `module_get(module_id)` | 获取模块详情（含成员） | 不缓存 |
| `user_list(name?)` | 搜索组织用户 | → `users.json`（24h）|
| `org_get_tree()` | 获取组织架构树 | 不缓存 |
| `people_get_board()` | 人员任务看板 | 不缓存 |

### 任务管理
| 工具 | 用途 | 缓存 |
|------|------|------|
| `task_list_mine()` | 我认领的任务 | 不缓存 |
| `task_list_by_module(module_id)` | 模块下所有任务 | 不缓存 |
| `task_get(task_id)` | 任务详情 | 不缓存 |
| `task_create(...)` | 创建任务 | — |
| `task_update(task_id, ...)` | 更新任务 | — |
| `task_set_assignees(task_id, assignee_ids)` | 设置执行人（幂等） | — |

### 员工日报
| 工具 | 用途 |
|------|------|
| `report_get_today(date?)` | 获取指定日期日报 |
| `report_get_tasks_to_report()` | 获取今日待汇报任务 |
| `report_save_draft(items=[...])` | 批量保存草稿（upsert）|
| `report_submit_item(item_id, date?)` | 提交单条日报条目 |
| `report_withdraw_item(item_id, date?)` | 撤回单条已提交日报条目 |

### 负责人日报
| 工具 | 用途 |
|------|------|
| `leader_report_get_subordinates(date, module_id)` | 查看下属汇报情况 |
| `leader_report_save(report_date, content, module_id?)` | 保存负责人日报草稿 |
| `leader_report_submit(report_date, module_id)` | 提交负责人日报 |
| `leader_report_withdraw(report_date, module_id)` | 撤回负责人日报 |
| `leader_report_get_batch(date, module_ids)` | 批量获取多模块日报 |

### 周报
| 工具 | 用途 |
|------|------|
| `weekly_report_get(year, week)` | 获取指定 ISO 周的周报 |
| `weekly_report_get_batch(year, week, module_ids)` | 批量获取多模块周报 |
| `weekly_report_save(module_id, year, week_number, content?, next_week_plan?)` | 保存周报草稿 |
| `weekly_report_submit(module_id)` | 提交周报 |
| `weekly_report_withdraw(module_id, year?, week_number?)` | 撤回周报 |

### 系统与 LLM
| 工具 | 用途 | 缓存 |
|------|------|------|
| `system_get_workday(date?)` | 查询是否工作日 | → `workdays.json`（永久）|
| `llm_polish_report(content)` | AI 润色日报内容 | — |
| `llm_generate_leader_summary(module_id, date)` | AI 生成负责人日报草稿 | — |

---

## 全局约定

1. **提交前必须确认**：`report_submit`、`leader_report_submit`、`weekly_report_submit` 执行前必须向用户展示内容并等待明确确认，禁止自动提交。
2. **非工作日不强制**：检测到非工作日时，告知用户并询问是否仍要填写，不得直接中断流程。
3. **缓存优先**：执行任何需要 module_id / user_id 的操作前，先读缓存；缓存未命中或过期才调 MCP。
4. **ISO 周数**：周报的 `year` 字段存 ISO year（`date.isocalendar()[0]`），不是日历年。12 月底 / 1 月初注意跨年。
5. **task_set_assignees 幂等**：设置执行人使用此工具（幂等），不要用 task_update 的 assignee 字段追加。