142 lines
5.6 KiB
Markdown
142 lines
5.6 KiB
Markdown
---
|
||
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 字段追加。
|