SkyJourneyandClaude Sonnet 5
600c0dd323
huanxi 插件的技能内容从 v1 全面替换为 v2（huanxi-org/huanxi-weekly 等 v1 专属技能下线，新增 huanxi-issue/huanxi-lookup/huanxi-meeting），MCP 连接与 Token 获取方式同步更新为个人中心自助生成。 新增独立的 huanxi-admin 插件（管理端 4 个技能，hxa_ Token，普通员工无需 安装），此前一直卡在"v2 未部署到生产域名前不推送"这条约束，今晚寰汐 v1.0.0 生产切换完成后条件满足。 产物由 huanxi-menagement 仓库 skills/sync_marketplace.py 生成，技能源码 单一真相在该仓库的 skills/，本仓库只接收产物、不手工编辑。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018xxRKMuiGR4wYT3QbwCpDc
98 lines
4.0 KiB
Markdown
98 lines
4.0 KiB
Markdown
---
|
||
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 再操作**，不要凭名字猜。
|