SkyJourneyandClaude Opus 5
4ce9a92013
寰汐 v2 上线双 MCP（个人端 /mcp/ 与管理端 /admin-mcp/），两条端点是**两条独立的 信任边界**——Token 前缀不同、工具集不同、视角不同（管理端看全量、个人端只看我参与的）。 一个插件塞两套会让普通员工的客户端里出现他根本调不动的管理工具，因此拆成两个插件， 按角色各装各的。 ## huanxi（个人端，全体员工） 7 个技能：shared / report / leader / task / issue / meeting / org - 新增 `issue` `meeting`——v2 的议题域与会议域（M6v2 会议×议题解耦后的产物） - **删除 `weekly`**——v2 没有 weekly_report 表，周报已并入报告体系 - 各技能重写为**流水线定义**而非使用说明：写明工具调用顺序、ID 在步骤间怎么传、 人工确认节点落在哪。「禁止自动提交」这条 v1 已验证的硬约束保留 - 删掉 `references/` 拆分文件——v2 技能自包含 ## huanxi-admin（管理端，仅后台管理员） 4 个技能：admin-shared / admin-report / admin-module / admin-ops MCP server key 取 `huanxi-admin`（与个人端的 `huanxi` 不同名），否则两插件并存时 会键冲突。 ## 缓存目录按信任边界隔离 `~/.claude/huanxi-cache/` 下分 `personal/` `admin/` `dict/`：前两者视角不同， 混用会越权展示或数据错乱；`dict/` 与身份无关可共享。业务数据（任务/日报/会议/议题） **显式声明不缓存**——v1 没写这条，Agent 会自行决定缓存然后拿到陈旧数据。 ## 源码单一真相不在本仓库 技能源码在寰汐仓库 `skills/`，与 MCP docstring 同仓库同 commit——签名一改， 技能与工具在同一次改动里更新，从结构上消除跨仓库漂移（本仓库记忆 `feedback_plugin_dev.md` 记录的 4 类漂移覆盖全部 6 个 v1 技能，正是这个病）。 本仓库退化为**分发壳**，只接收 `python skills/sync_marketplace.py` 的产物，不手工编辑。 寰汐侧有 CI 守卫：技能里出现的每个工具名必须存在于实际注册表、个人端技能不得 指导调用管理端独有工具、不得硬编码状态字面量。 ## 本分支不合 main 插件配置的域名此刻跑的还是 v1，合进 main 会通过自动更新推给已安装用户， 他们的技能会去调 v1 上不存在的工具。合并前置条件写在 CLAUDE.md「已发布插件」节。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019Vyeia9k43dVaUFNLo8Lny
96 lines
3.9 KiB
Markdown
96 lines
3.9 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()
|
||
```
|
||
|
||
`user_query` 比个人端多两个维度：`status`（active 在职 / observation 交接观察期 /
|
||
inactive 已停用）与 `has_backend_permission`。用于盘点「谁在观察期」「谁有后台权限」。
|
||
**只读**——账号启停与权限授予见上文。
|
||
|
||
---
|
||
|
||
## 缓存
|
||
|
||
缓存根 `~/.claude/huanxi-cache/`，管理端用 `admin/` 子目录，与个人端隔离——
|
||
两边看到的模块范围不同，混用会把不该展示的内容展示出去。
|
||
|
||
| 类别 | 策略 |
|
||
|---|---|
|
||
| 身份 `admin/me.json` | 永久 |
|
||
| 配置字典 `dict/*.json` | **`dict_version` 比对** + 24h 兜底 |
|
||
| 组织 `admin/org-tree.json` `admin/all-modules.json` | 24h |
|
||
| 工作日 `dict/workdays.json` | 按日期 key 永久 |
|
||
| **业务数据**（汇报/任务/会议/议题） | **一律不缓存** |
|
||
|
||
字典为什么不能只靠 TTL：状态选项可能被停用，拿过期 ID 去写会**直接报错**——
|
||
失败方向是「操作失败」而非「看到旧数据」，值得比对一次。`dict_get` 的返回自带
|
||
`versions` 字段，连内容一起存即可，不要分两次调。
|
||
|
||
---
|
||
|
||
## 全局约定
|
||
|
||
1. **有副作用的写操作先确认**：`module_set_members`（替换语义，会移除名单外的人）、
|
||
`module_update` 切「已取消」（级联取消该模块全部未完成任务并通知成员）。
|
||
2. **盘点类查询直接给结论**：用户问「谁没交」，答案是名单，不是让他自己看原始数据。
|
||
3. **先解析 ID 再操作**，不要凭名字猜。
|