---
name: huanxi-admin-shared
description: "寰汐管理端 MCP 共享基础：管理身份语义、高危操作边界、缓存策略、状态两层模型、人员查询。所有 huanxi-admin-* 技能必须先读本文件。"
---

# 寰汐管理端 · 共享规则

所有 `huanxi-admin-*` 技能的**必读前置**。本技能族用的是管理端 Token（`hxa_`），
与个人端（`hxp_`）是两条独立通道，**工具集不同、视角不同**。

---

## 你是以谁的身份在操作

管理端 Token 不绑定业务用户，执行时以 **Token 创建人的管理员身份**进行，
所有写操作按该身份记入审计。`whoami` 回答「我现在代表谁」。

创建人若已停用或被撤销后台权限，Token 会一并失效——这不是 bug，是随人事变动收回权限。

视角是**全量**的：模块、任务、汇报都不受「我参不参与」过滤。这是与个人端最大的差别，
也意味着你看到的东西大多不是你自己的，措辞上要注意（说「张三的日报」而不是「你的日报」）。

---

## 高危操作不在本端点

**账号启停、授予/撤销管理员与老板身份、通讯录全量同步、各类删除、状态选项与标签等
字典的写操作——全部走网页后台。**

理由不是「危险所以不给」，而是网页后台有确认弹窗与完整的操作上下文，MCP 通道没有
等价的「让人看清楚再点」环节。用户提这类需求时，直接告诉他去后台哪个页面，
**不要试图用别的工具绕过去**。

---

## 参数以工具自身的说明为准

本文档与各技能都不重画参数表。参数名、必填项、取值范围以工具在 MCP 里注册的
docstring 为唯一真相；技能只描述调用顺序、ID 如何传递、哪里必须停下来等用户确认。

工具名在 Claude 客户端里带前缀 `mcp__huanxi-admin__`，其他平台按各自约定；
本文档统一写裸名。

---

## 状态是可配置的两层模型

**不要硬编码状态字面量。** 分两层：

- `category`：四类固定语义 `not_started` / `in_progress` / `completed` / `cancelled`，用于**判断**
- `status_option_id`：具体状态项的 UUID，用于**写入**

改状态前先 `dict_get` 取对应 `entity_type`（module/task/issue/meeting，必须选对）
下的选项。字典本身的增删改不在本端点。

---

## 人员查询

```
user_query(q?, ids?, status?, has_backend_permission?)
```

> 组织架构树（`org_tree`）已随 M16 身份体系替换下线——公司改用蚁熊通行证，
> 它不提供部门信息。

`user_query` 比个人端多两个维度：`status`（active 在职 / observation 交接观察期 /
inactive 已停用）与 `has_backend_permission`。用于盘点「谁在观察期」「谁有后台权限」。
**只读**——账号启停与权限授予见上文。

---

## 缓存

缓存根 `~/.claude/huanxi-cache/`，管理端用 `admin/` 子目录，与个人端隔离——
两边看到的模块范围不同，混用会把不该展示的内容展示出去。

| 类别 | 策略 |
|---|---|
| 身份 `admin/me.json` | 永久 |
| 配置字典 `dict/*.json` | **`dict_version` 比对** + 24h 兜底 |
| 人员与模块 `admin/all-modules.json` | 24h |
| 工作日 `dict/workdays.json` | 按日期 key 永久 |
| **业务数据**（汇报/任务/会议/议题） | **一律不缓存** |

字典为什么不能只靠 TTL：状态选项可能被停用，拿过期 ID 去写会**直接报错**——
失败方向是「操作失败」而非「看到旧数据」，值得比对一次。`dict_get` 的返回自带
`versions` 字段，连内容一起存即可，不要分两次调。

---

## 全局约定

1. **有副作用的写操作先确认**：`module_set_members`（替换语义，会移除名单外的人）、
   `module_update` 切「已取消」（级联取消该模块全部未完成任务并通知成员）。
2. **盘点类查询直接给结论**：用户问「谁没交」，答案是名单，不是让他自己看原始数据。
3. **先解析 ID 再操作**，不要凭名字猜。