dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-chat/references/intent-guide.md

@@ -0,0 +1,56 @@
+# Chat 低频意图消歧
+
+只在根 Skill 的 Golden Route 无法区分相邻能力时读取。命令 flags 和安全语义以精确 leaf Schema/Runtime 为准。
+
+## 消息选择
+
+| 用户终点 | 选择 | 不要混用 |
+|---|---|---|
+| 给姓名发简单文本 | `+dm` | 先查人再原子发送 |
+| 给群名发简单文本 | `+send-to-group` | 先搜群再原子发送 |
+| 文件、Bot、Webhook、复杂 @、幂等 | `+messages-send` | 为不同身份各走一套原子入口 |
+| 读取或导出指定会话，可附带发送者姓名 | `+chat-messages`；姓名用非必填 `--sender-query` | 解析成功后读后筛选；解析失败抑制未过滤消息并返回错误；不补跑搜索 |
+| 直接按发送者、关键词、@对象或消息类型搜索 | `+search-msg` | 条件检索优先，可限定单个或跨多个会话 |
+| 已知消息 IDs 取详情 | `+messages-mget` | 重新搜索关键词 |
+| @我的消息 | `+at-me` | 全量消息后本地猜测 @ |
+| 已知 thread/topic ID 的回复 | `+thread-replies` | 普通消息列表 |
+| 引用回复一条消息 | `+messages-reply` | 普通发送 |
+| 单条/合并/话题转发 | `+messages-forward` / `+messages-combine-forward` / `+messages-forward-topic` | 复制正文重新发送 |
+| 流式卡片创建或更新 | `+messages-send-card` / `+messages-update-card` | 普通 text/Markdown 发送 |
+
+## Topic 选择
+
+话题与话题圈的创建、发布、已有消息升级、浏览、回复、互动和整条转发统一读取 [thread.md](chat/thread.md)，不从普通消息入口选路。
+
+## 对象层级
+
+| 用户终点 | 对象 | Reference |
+|---|---|---|
+| 收藏或取消收藏 | 当前用户的 Favorite | [message-actions.md](chat/message-actions.md) |
+| Pin/Unpin 一条消息 | 消息 Pin | [message-actions.md](chat/message-actions.md) |
+| 置顶/取消置顶一条消息 | 消息 Top | [message-actions.md](chat/message-actions.md) |
+| 置顶/取消置顶整个会话 | 会话 Top | [chat-conversation.md](chat/chat-conversation.md) |
+| 查看置顶会话 | 会话列表 | `+conversation-list-top` |
+| 标记消息已读 | 消息读取状态 | [message-actions.md](chat/message-actions.md) |
+| 清红点、标记会话未读 | 会话状态 | [chat-conversation.md](chat/chat-conversation.md) |
+
+Favorite、消息 Pin、消息 Top 和会话 Top 不能互换，即使用户都说“收藏/钉住/置顶”。
+
+## 群与机器人
+
+| 用户终点 | 选择 |
+|---|---|
+| 已有成员 IDs 创建群 | `+chat-create` |
+| 查群、查看成员、邀请链接 | [group-discovery.md](chat/group-discovery.md) |
+| 加人、踢人、管理员、群公告、群设置 | [group-admin.md](chat/group-admin.md) |
+| 找可用机器人并取得单聊 ID | `chat bot find`，不是只查自己创建机器人的 `bot search` |
+| 已知 robotCode 发送 | `+messages-send --as bot` |
+| 机器人入群、移除、批量群发或撤回 | [chat-bot.md](chat/chat-bot.md) |
+
+## 跨产品边界
+
+- 紧急 DING、短信或电话：切 `dingtalk-misc`，不要当普通 Chat 消息。
+- 邮件：切 `dingtalk-mail`。
+- 只查询人员资料或把姓名解析成 ID：切 `dingtalk-contact`；若终点只是简单发消息，直接留在 Chat 使用 `+dm`。
+- 企业知识跨文档、消息、邮件搜索：切 `dingtalk-aisearch`；明确只搜聊天消息时使用 `+search-msg`。
+- 文档翻译先由文档产品读取正文；`chat text translate` 只处理纯文本。

package/skills/dws/dingtalk-contact/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: dingtalk-contact
+description: 钉钉通讯录精确查询。Use when 已有 userId 后查详情、部门、职位或邮箱，按完整手机号反查用户，或查询自己、部门成员及角色。姓名模糊搜索、工号、职责、上下级走 dingtalk-aisearch，拿到 userId 后用本 skill 补详情。命令前缀：dws contact。
+metadata:
+  cli_version: ">=0.2.14"
+  category: product
+  requires:
+    bins:
+      - dws
+---
+
+# 钉钉通讯录 Skill
+
+## 前置条件 — 执行操作前必读
+
+> **CRITICAL — 执行任何 `dws` 操作前，MUST 先用 Read 工具完整读取 [`dingtalk-shared`](../dingtalk-shared/SKILL.md)。**该轻量文件包含全局执行契约、安全底线及 shared references 的按需加载导航；不要预加载其全部 references。
+
+> 命令参考：[contact.md](references/contact.md)；剧本：[08-directory.md](references/08-directory.md)。
+
+<!-- VISIBLE_SHORTCUTS_START -->
+## Shortcuts（无专用脚本/recipe 时优先）
+
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 `dws schema --cli-path "contact +<shortcut>" --compact --format json`），在当前 Cobra flags 不确定时读取 `dws contact <shortcut> --help`。只有参数映射、接口绑定或 provenance 审计才省略 `--compact`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service contact --format json` 批量发现。
+
+| Shortcut | 风险 | 适用场景 |
+|---|---|---|
+| `dws contact +by-mobile` | read | 按手机号查询某人的完整资料（自动解析 userId 后取详情） |
+| `dws contact +dept-members` | read | 按部门名列出部门成员（自动解析 deptId） |
+| `dws contact +list-dept-members` | read | 查看部门成员（仅本部门，不含下级） |
+| `dws contact +list-followings` | read | 获取当前用户的特别关注列表 |
+| `dws contact +list-role-members` | read | 查询角色下的成员列表 |
+| `dws contact +list-sub-depts` | read | 查看指定部门的子部门 |
+| `dws contact +lookup` | read | 按姓名查询某人的完整资料（自动解析 userId 后取详情） |
+| `dws contact +me` | read | 查看我自己的通讯录资料（姓名/userId/手机/部门/组织，干净投影） |
+| `dws contact +org` | read | 按姓名查某人所在部门的详情（自动解析 userId 与 deptId） |
+| `dws contact +resolve-dept` | read | 按名称搜索部门并解析出唯一 deptId（只读） |
+| `dws contact +search-mobile` | read | 按手机号搜索通讯录用户 |
+| `dws contact +search-user` | read | 按关键词搜索通讯录用户 |
+| `dws contact +team` | read | 按姓名列出某人所在部门的成员（自动解析 userId 与 deptId） |
+<!-- VISIBLE_SHORTCUTS_END -->
+
+## 意图表
+
+| 用户说 | 命令 |
+|--------|------|
+| "查我自己的信息" | `dws contact user get-self` |
+| "按 userId 查详情" | `dws contact user get --ids <userId1>,<userId2>,...`（多个并行） |
+| "完整手机号反查用户" | `dws contact user search-mobile --mobile <手机号>` |
+| "按部门名拉成员" | `python scripts/contact_dept_members.py --query "<部门名>"` |
+| "搜部门" | `dws contact dept search --query "<关键词>"` |
+| "部门成员列表" | `dws contact dept list-members --ids <deptId>` |
+| "列出企业角色 / 有哪些角色" | `dws contact label list` |
+| "按角色名查角色ID" | `dws contact label get --names "<角色名>"` |
+| "查某角色下有哪些成员" | `dws contact label list-members --id <labelId>` |
+
+## 标准 SOP（必遵流程）
+
+> 命中以下意图**必须**按对应 SOP 顺序执行；**禁止**跳步、替换命令、编造 userId。每条命令必须带 `--format json`。姓名模糊搜索、工号、职责与上下级走 `dingtalk-aisearch`；完整手机号精确反查走 contact；拿到 userId 后由 contact 补详情。
+
+### SOP-1 搜人（search-person）
+
+**触发**：按姓名/工号/部门/职责/上下级找人，或用手机号线索做语义搜索。
+
+1. **切 aisearch（必须）**：`dws aisearch person --query "<关键词>" --dimension <维度> --format json`（姓名→`name`、工号→`jobNumber`、手机号语义线索→`phone`、负责人→`duty`、部门→`department`、上下级→`supervisor`/`subordinate`）。
+2. **解析（必须）**：从结果取 `userId`、`title`；**多人同名禁止默认选第一个**，必须批量 `dws contact user get --ids <id1,id2,...> --format json` 拿部门/职位后让用户确认。
+3. **补详情（必须）**：要完整部门/职位/邮箱/主管时 `dws contact user get --ids <userId> --format json`。
+
+**禁止**：用 `contact user search` 做姓名或工号搜索、默认取首个候选、编造人员字段。完整手机号精确反查是 `search-mobile` 的唯一搜索例外。
+
+### SOP-1A 完整手机号精确反查（search-person-by-mobile）
+
+**触发**：用户提供完整手机号并要求确认是谁或取得 userId。
+
+1. **执行（必须）**：`dws contact user search-mobile --mobile "<完整手机号>" --format json`。
+2. **补详情（按需）**：从结果取 `userId`，需要部门、职位或邮箱时继续 `dws contact user get --ids <userId> --format json`。
+
+**禁止**：把完整手机号精确反查改走姓名搜索，或在未返回 userId 时猜测人员。
+
+### SOP-2 精确查人/补详情（search-user）
+
+**触发**：已有 userId 要查完整详情，或要拿 userId 给下游（发消息/建待办/约日程）。
+
+1. **拿 userId（必须）**：`dws aisearch person --query "<姓名>" --dimension name --format json` → `userId`；多命中必须列候选请用户确认。
+2. **查详情（必须）**：`dws contact user get --ids <userId> --format json`，按返回字段（`orgEmployeeModel` 下部门/职位/邮箱）答复。
+
+**禁止**：用模糊关键词直接调 `contact user search` 凑数、编造未返回字段。
+
+### SOP-3 查自己（get-contact-self）
+
+**触发**：我的信息/我的 userId/我的部门。
+
+1. **执行（必须）**：`dws contact user get-self --format json`，取 `orgEmployeeModel.userId` / `orgUserName` / `depts[].deptName` / 主管等。
+
+**禁止**：把自己 userId 写死或猜测。
+
+### SOP-4 查部门 / 角色（dept-and-relation）
+
+**触发**：部门列表/部门成员/角色/角色成员。
+
+1. **执行（必须）**：搜部门 `dws contact dept search --query "<部门名>" --format json`；某部门下子部门 `dws contact dept list-children --dept <父部门ID> --format json`；部门成员 `dws contact dept list-members --ids <部门ID>[,<部门ID2>...] --format json`；部门详情 `dws contact dept get-info --dept <部门ID> --format json`。角色：`dws contact label list` / `dws contact label get --names "<角色名>"` / `dws contact label list-members --id <labelId>`。搜索企业根部门时服务端可能返回 `deptId=-1` 哨兵，后续 `list-children` / `list-members` / `get-info` 必须规范化为真实根部门 `deptId=1`。
+2. **补详情（必须）**：拿到 userId 后用 `contact user get --ids` 补部门/职位；上下级关系优先经 `dingtalk-aisearch` 的 `supervisor`/`subordinate` 维度。
+
+**禁止**：使用不存在的 `contact dept list`（已废弃/歧义）、编造 deptId/labelId、跳过 aisearch 维度直接猜上下级。
+
+## 高频硬约束
+
+- 通讯录问题必须调用 `dws contact` 或 `dws aisearch` 获取实时结果；严禁只读 `USER.md`、环境身份或静态上下文后直接回答。
+- 查自己用 `dws contact user get-self --format json`，不要把 `me/self/current` 当作 `userId` 传给 `user get`。
+- 姓名模糊搜索、工号反查、职责或上下级搜索走 `dws aisearch person`；完整手机号精确反查走 `dws contact user search-mobile --mobile "<手机号>" --format json`。拿到 `userId` 后按需 `dws contact user get --ids <userId> --format json` 补部门/职位/邮箱。
+- 查询直属主管/上下级时，如果 `contact user get` 没返回明确主管字段，必须继续 `dws aisearch person --query "<完整姓名或工号>" --dimension supervisor --format json`，不要停在"可能需要进一步查询"。
+- 多个同名候选时，批量 `contact user get --ids id1,id2,... --format json` 获取部门/职位后再消歧；不要默认取第一个。
+- 用户查询企业角色、角色ID、角色成员，或“管理员/财务/HR/主管”等角色类型人员时，走 `contact label list/get/list-members`；不要用 `dept list-members` 筛字段替代。
+
+## 跨产品协作
+
+- 姓名模糊搜索、上下级、谁负责、工号反查、手机号语义搜索 → `dingtalk-aisearch`
+- 完整手机号精确反查 → `dws contact user search-mobile`
+- 拿到 email 发邮件 → 切到 `dingtalk-mail`
+- 拿到 userId 发消息 → 切到 `dingtalk-chat`
+## 局部意图与短流程
+
+- [局部意图消歧](references/intent-guide.md)；[短流程](references/lite-recipes.md)。

package/skills/dws/dingtalk-contact/references/08-directory.md

@@ -0,0 +1,51 @@
+# 通讯录（组织架构）
+
+> **SKILL.md** 中 #8 内联 3 条 **lite**：`get-contact-self`、`search-person`、`search-user`。下列 recipe、专用规则与消歧请在命中 #8 且**超出**上述 lite 时阅读本文。
+> 产品命令见 [contact.md](./contact.md)。通用批量/并行见 [recipes/conventions.md](recipes/conventions.md)。
+
+## 专用规则（#8 非 lite 步骤必守）
+
+- **角色类查人优先 label**：用户说"角色为XX的员工/XX角色的员工/XX角色的人员""所有主管/主管理员/财务/HR/总经理"等角色类型人员时，**优先** `contact label list` 获取全部角色 → 匹配目标角色 → `contact label list-members --id <labelId>`；若用户明确指定了角色名称（如"角色为总经理"），则先用 `contact label get --names <XX>` 精确匹配，**若精确匹配无结果，降级 `label list` 模糊匹配**（如用户说"管理员"可匹配到"主管理员"和"子管理员"）。
+- **脚本优先**：按部门拉成员**优先** `python scripts/contact_dept_members.py --query "<部门名>"`（`--dry-run` / `--format json`）；失败再 `dept search` → `dept list-members --ids`。
+- **详情链路**：用户要子部门、职位、联系方式、汇报关系等，在 `aisearch person` 找到 `userId` 后**必须**再 `contact user get --ids <userId>`；禁止仅用搜索结果的浅表字段交差。
+- **`user get` 后部门仍空**：不得过早结束或只建议用户去 App；须在 CLI 能力内尝试 **用户点名的部门** `dept search` + `dept list-members` 等与 `userId` 交叉核对，再结构化汇总「返回中有哪些字段 / 哪些为空及可能原因」。
+- **多命中**：`aisearch person` 或 `dept search` 返回多条时须列候选（姓名、title、部门线索）请用户确认，禁止默认猜一人。具体消歧流程：
+  1. 从搜索结果中提取所有同名/多命中用户的 `userId`
+  2. 调用 `contact user get --ids userId1,userId2,...` 获取每人详情（含 `depts` 部门列表、职位等）
+  3. 将「姓名 + 部门 + 职位」列表展示给用户，请用户确认选择哪一位
+  4. 使用用户确认的 `userId` 继续后续操作
+  > **根因**：`aisearch person` 不返回完整部门信息，无法仅凭搜索结果区分同名用户。**必须**追加 `contact user get` 获取部门信息才能消歧。
+- **批量**：多个 `userId` 用 `contact user get --ids id1,id2,...`；多部门成员列表按需并行，遵守单次批量上限与 [recipes/conventions.md](recipes/conventions.md)。
+- **子部门枚举**：已知父部门 `deptId` 时**优先** `contact dept list-children --dept <父deptId>` 直接拿到完整子部门列表；只知道部门名时先 `contact dept search --query "<父部门名>"` 取 `deptId` 再 `list-children`；用户明示的子部门名（无需枚举）可直接 `dept search` 命中。多子部门展开见 `explore-subdepts-and-members`。
+
+## 与其他场景消歧
+
+- **按角色/职位类型查人（主管/管理员/财务等）** → 优先 `contact label list` + `label list-members`；label 精确命中角色维度，返回完整名单；aisearch 是语义模糊搜索不保证完整性。
+- **搜人/找人/找同事/查工号/手机号语义搜索** → **`aisearch person`**（支持姓名/部门/职责/上下级/手机号线索/工号维度），见 `dingtalk-aisearch`。
+- **完整手机号精确反查** → `contact user search-mobile --mobile "<手机号>"`。
+- **已有 userId 后查详情 / 查自己 / 查部门与角色** → `contact`（精确查询）。
+- **纯查部门与子部门成员 / 验证归属 / 组织关系** → `contact`。
+- **终点是发消息、待办、日程** → 先用 `search-person` 或 `search-user` 取 `userId`，再进入 #1 / #2 / #3。
+- **联系客户 + 发邮件** → 先用 `contact` 取 `orgAuthEmail`，再走 `dingtalk-mail`。
+
+## Recipe 速查（本表步骤，非 SKILL lite）
+
+| Recipe | 步骤 |
+|--------|------|
+| `lookup-label-members` | 1. `contact label list` → 浏览全部角色，匹配目标角色的 labelId<br>2. `contact label list-members --id <labelId>` → 该角色下的成员列表 |
+| `search-user-by-mobile` | 1. `contact user search-mobile --mobile "<完整手机号>"` → 按需 `contact user get --ids <userId>` |
+| `lookup-dept-id` | 1. `contact dept search --query "<部门关键词>"` → 回显 `deptId`（多命中须消歧） |
+| `list-subdepts` | 1. 已有父 `deptId` → `contact dept list-children --dept <父deptId>` 直接取直属子部门列表<br>2. 只有部门名 → 先 `lookup-dept-id` 取 `deptId`，再 `list-children` |
+| `list-dept-members` | 1. **优先** `python scripts/contact_dept_members.py --query "<部门名>"`<br>2. 备选：`lookup-dept-id` → `contact dept list-members --ids <deptId>`<br>3. 若要每人档案字段：对 `userId` 批量 `contact user get --ids …` |
+| `list-multi-dept-members` | 1. 对每个部门名 `contact dept search --query "<名>"` → 各 `deptId`<br>2. `contact dept list-members --ids <id1>,<id2>,...`（多部门并行/批量见 conventions）<br>3. 需要档案再 `contact user get --ids …` |
+| `verify-user-dept` | 1. `contact dept search --query "<部门名>"` → `deptId`<br>2. `contact dept list-members --ids <deptId>` 中匹配姓名；或先 `search-user` lite 再 `user get` 核对部门字段 |
+
+## Full / 多步组合
+
+| Recipe | 行动指南（固定路线） |
+|--------|---------------------|
+| explore-subdepts-and-members | 1. 取父部门 `deptId`：用户给了 ID 直接用；只给名字则 `contact dept search --query "<父部门名>"` → 父 `deptId`（多命中先消歧）<br>2. **优先** `contact dept list-children --dept <父deptId>` 拿到全部直属子 `deptId` 列表；若用户只点名了部分子部门，则改为对每个子部门名 `contact dept search --query "<子部门名>"`<br>3. 对子 `deptId`：`contact dept list-members --ids <id1>,<id2>,...`（多部门按 conventions **并行/批量**）<br>4. 若还要成员详情：汇总 `userId` → `contact user get --ids …`（≤30 条/批，超出分批 + 用户确认） |
+| verify-user-in-dept | 同速查表 `verify-user-dept`；多轮对话中用户追加「是否在某部门」时叠加本路线 |
+| cross-level-dept-members | 1. `contact dept search --query "<父部门关键词>"` → 父 `deptId`<br>2. **优先** `contact dept list-children --dept <父deptId>` 枚举全部直属子 `deptId`；用户已点名的子部门则用 `dept search` 精确命中<br>3. 需要逐层下钻时，对上一步拿到的子 `deptId` 继续 `dept list-children` 递归（注意控制深度，避免一次拉太多）<br>4. `contact dept list-members --ids <id1,id2,…>` → 按需 `user get` |
+| user-detail-organization | 1. `aisearch person --query "<关键词>" --dimension <维度>` → `userId`（多结果先消歧）<br>2. **必须** `contact user get --ids <userId>`<br>3. 若用户同时给出部门语境：叠加 `verify-user-dept` |
+| batch-users-by-keyword | 1. `aisearch person --query "<职位或技能关键词>" --dimension position,duty` → 多条<br>2. 提取 `userId`（≤30）→ `contact user get --ids …`<br>3. 结果过多时汇总或请用户收窄 |