docs(huanxi-skills): 修正工具调用描述与参数出入，补充工具定义优先规范
参数/描述修正： - report-submit.md：report_submit → report_submit_item - huanxi-shared 全局约定：同步修正 report_submit 工具名 - weekly-draft.md：多模块循环示例 week → week_number（weekly_report_save 正确参数名） - 工具索引补全参数：task_list_mine/people_get_board/user_list/weekly_report_submit - resolve-ids.md：澄清 feishu_user_id 与 feishu_open_id 是两个不同字段 新增工具调用规范： - huanxi-shared 全局约定第 6 条：以 MCP 工具实际定义为准 - 5 个 skill 文件前置区域统一加 ⚠️ 提示引用第 6 条 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SkyJourney
co-authored by
Claude Sonnet 4.6
Claude Sonnet 4.6
parent
bd960dbddd
commit
8289fa6060
@@ -7,6 +7,8 @@ description: "寰汐负责人日报工作流：查看下属汇报情况（+check
|
||||
|
||||
**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
|
||||
|
||||
> ⚠️ **工具调用规范**：执行任何 `mcp__huanxi__*` 调用前，以工具实际注册的参数名和类型为准，本文档示例仅供工作流引导（见 shared 全局约定第 6 条）。
|
||||
|
||||
---
|
||||
|
||||
## 标准工作流（完整流程）
|
||||
|
||||
@@ -7,6 +7,8 @@ description: "寰汐组织/模块/人员查询。当用户说"我有哪些模块
|
||||
|
||||
**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
|
||||
|
||||
> ⚠️ **工具调用规范**：执行任何 `mcp__huanxi__*` 调用前，以工具实际注册的参数名和类型为准，本文档示例仅供工作流引导（见 shared 全局约定第 6 条）。
|
||||
|
||||
---
|
||||
|
||||
## 核心能力
|
||||
|
||||
@@ -50,9 +50,10 @@
|
||||
```
|
||||
|
||||
**特别注意：**
|
||||
- 用户的系统内部 ID 字段名是 `id`（后端 `user_list` 返回结构），`≠ feishu_user_id`（飞书 open_id）
|
||||
- 设置任务执行人时，MCP 工具的参数名叫 `assignee_ids`，传入的值就是 user.id 列表
|
||||
- 飞书消息通知用 `feishu_user_id`（MCP 内部会自动处理，无需手动区分）
|
||||
- 用户的系统内部 ID 字段名是 `id`（后端 `user_list` 返回结构），`≠ feishu_user_id`
|
||||
- `feishu_user_id` 是飞书通讻录的 user_id（`on_` 前缀），`feishu_open_id` 是飞书 open_id（`ou_` 前缀）；两者是**不同字段**，不要混用
|
||||
- 设置任务执行人时，MCP 工具的参数名叫 `assignee_ids`，传入的值是 user.id（系统内部 UUID 列表）
|
||||
- 飞书消息通知由 MCP 服务端内部处理，调用工具时只需传系统内部 user.id 即可
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -7,6 +7,8 @@ description: "寰汐员工日报工作流：查看今日日报状态（+check）
|
||||
|
||||
**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
|
||||
|
||||
> ⚠️ **工具调用规范**：执行任何 `mcp__huanxi__*` 调用前，以工具实际注册的参数名和类型为准，本文档示例仅供工作流引导（见 shared 全局约定第 6 条）。
|
||||
|
||||
---
|
||||
|
||||
## 标准工作流（完整流程）
|
||||
|
||||
@@ -26,7 +26,7 @@ Step 2: 展示完整草稿给用户审阅：
|
||||
└─────────────────────────────────────────
|
||||
|
||||
Step 3: 等待用户明确确认（"确认"/"提交"/"好的"/"ok"等）
|
||||
⚠️ 未收到确认前，禁止调用 report_submit
|
||||
⚠️ 未收到确认前，禁止调用 report_submit_item
|
||||
|
||||
Step 4: 对每个需提交的草稿条目（item.status == "draft"）：
|
||||
mcp__huanxi__report_submit_item(item_id=<item.id>)
|
||||
|
||||
@@ -82,14 +82,14 @@ workdays.json → Infinity（按 date key，已查过的不再查）
|
||||
|------|------|------|
|
||||
| `module_list(my_role?)` | 列出我参与的模块 | → `modules.json`（24h）|
|
||||
| `module_get(module_id)` | 获取模块详情（含成员） | 不缓存 |
|
||||
| `user_list(name?)` | 搜索组织用户 | → `users.json`（24h）|
|
||||
| `user_list(name?, department_id?, is_active?, limit?)` | 搜索组织用户 | → `users.json`（24h）|
|
||||
| `org_get_tree()` | 获取组织架构树 | 不缓存 |
|
||||
| `people_get_board()` | 人员任务看板 | 不缓存 |
|
||||
| `people_get_board(user_id?, module_id?, date?)` | 人员任务看板（不传则全员；传 user_id 只看该人） | 不缓存 |
|
||||
|
||||
### 任务管理
|
||||
| 工具 | 用途 | 缓存 |
|
||||
|------|------|------|
|
||||
| `task_list_mine()` | 我认领的任务 | 不缓存 |
|
||||
| `task_list_mine(status?, module_id?, priority?, snapshot_active?)` | 我认领的任务 | 不缓存 |
|
||||
| `task_list_by_module(module_id)` | 模块下所有任务 | 不缓存 |
|
||||
| `task_get(task_id)` | 任务详情 | 不缓存 |
|
||||
| `task_create(...)` | 创建任务 | — |
|
||||
@@ -120,7 +120,7 @@ workdays.json → Infinity（按 date key，已查过的不再查）
|
||||
| `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_submit(module_id, year?, week_number?)` | 提交周报（不传 year/week_number 默认提交当周） |
|
||||
| `weekly_report_withdraw(module_id, year?, week_number?)` | 撤回周报 |
|
||||
|
||||
### 系统与 LLM
|
||||
@@ -134,8 +134,9 @@ workdays.json → Infinity（按 date key，已查过的不再查）
|
||||
|
||||
## 全局约定
|
||||
|
||||
1. **提交前必须确认**：`report_submit`、`leader_report_submit`、`weekly_report_submit` 执行前必须向用户展示内容并等待明确确认，禁止自动提交。
|
||||
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 中的调用示例仅供工作流引导，不得作为参数的唯一依据。如果示例与工具实际定义有出入，以工具定义优先。
|
||||
|
||||
@@ -7,6 +7,8 @@ description: "寰汐任务管理：创建任务（+create）、更新任务状
|
||||
|
||||
**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
|
||||
|
||||
> ⚠️ **工具调用规范**：执行任何 `mcp__huanxi__*` 调用前，以工具实际注册的参数名和类型为准，本文档示例仅供工作流引导（见 shared 全局约定第 6 条）。
|
||||
|
||||
---
|
||||
|
||||
## Shortcuts
|
||||
|
||||
@@ -7,6 +7,8 @@ description: "寰汐周报工作流（仅限模块负责人）：查看本周周
|
||||
|
||||
**前置条件：先 Read `../huanxi-shared/SKILL.md`（缓存规则 + TTL 策略）**
|
||||
|
||||
> ⚠️ **工具调用规范**：执行任何 `mcp__huanxi__*` 调用前，以工具实际注册的参数名和类型为准，本文档示例仅供工作流引导（见 shared 全局约定第 6 条）。
|
||||
|
||||
---
|
||||
|
||||
## 权限说明
|
||||
|
||||
@@ -92,7 +92,7 @@ for module in leader_modules:
|
||||
1. 提取该模块的 leader_report_batch（本周各日记录）
|
||||
2. AI 生成草稿（content + next_week_plan）
|
||||
3. 展示给用户确认/修改
|
||||
4. weekly_report_save(module_id=module.id, year, week, ...)
|
||||
4. weekly_report_save(module_id=module.id, year, week_number, ...)
|
||||
5. 告知：模块 "{module.name}" 草稿已保存 ✅
|
||||
|
||||
所有模块草稿完成后：统一展示，询问是否提交
|
||||
|
||||
Reference in New Issue
Block a user