yixiong-claude-marketplace/plugins/huanxi/skills/huanxi-shared/SKILL.md

name, description

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

寰汐 MCP 共享规则

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

---

必读声明

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

---

本地缓存机制

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

缓存文件清单

文件	内容	TTL	刷新方式
me.json	当前用户身份（id, name, feishu_user_id；注意字段名是 id 而不是 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?, department_id?, is_active?, limit?)	搜索组织用户	→ users.json（24h）
org_get_tree()	获取组织架构树	不缓存
people_get_board(user_id?, module_id?, date?)	人员任务看板（不传则全员；传 user_id 只看该人）	不缓存

任务管理

工具	用途	缓存
task_list_mine(status?, module_id?, priority?, snapshot_active?)	我认领的任务	不缓存
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, year?, week_number?)	提交周报（不传 year/week_number 默认提交当周）
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_item、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 字段追加。
6. 工具调用以 MCP 定义为准：调用任何 mcp__huanxi__* 工具前，必须以该工具在 MCP Server 中实际注册的参数名和类型为准，本文档及各 skill 中的调用示例仅供工作流引导，不得作为参数的唯一依据。如果示例与工具实际定义有出入，以工具定义优先。