dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-shared/references/recipes/lite-catalog.md

@@ -0,0 +1,275 @@
+# Lite Recipe 完整步骤
+
+> 核心流程步骤 3 判定为 lite 后，按本文件中对应 recipe 的步骤**直接执行**。
+> 所有命令均须加 `--format json`（下文省略）。
+
+## #1 消息沟通
+
+所有消息沟通相关的命令详情、参数说明、意图路由和复合工作流，请查阅 `dingtalk-chat`。
+
+## #2 任务管理
+
+### create-todo
+
+1. 确定执行者：指定姓名 → `aisearch person --query "<姓名>" --dimension name` → `userId`；未指定 → `contact user get-self` → `userId`；多人 → 逐个搜索逗号拼接。
+2. 创建：`todo task create --title "<标题>" --executors <userId>[,<userId2>...] --priority <优先级>`（可选 `--due "<截止ISO>"`）→ `todoTaskId`
+
+### todo-query-ops
+
+- 查询：`todo task list [--status false|true]`（不传=全部）
+- 详情：`todo task get --task-id <id>`
+- 完成/重开：`todo task done --task-id <id> --status <true|false>`
+- 按主题筛选：list 后按标题关键词过滤
+
+## #3 会议日程
+
+### list-today-meetings
+
+**优先**：加载 `dingtalk-calendar` sub-skill 后按其「今天/明天/本周日程」recipe 执行；该自动化脚本只在 `dingtalk-calendar` 包内可用。
+备选：`dws calendar event list --start "<今日起始ISO>" --end "<今日结束ISO>"`（须加 `--format json`）
+
+### check-users-busy
+
+查询多人在某时段内的闲忙（**busy**，不是用 `event list` 扫日程）：
+
+1. 解析用户：对每个姓名执行 `aisearch person --query "<姓名>" --dimension name` → `userId`；多人将 `userId` 用英文逗号拼接（无空格或按 `dingtalk-calendar` `busy search` 要求）。
+2. 确认时段：用户须给出或可收敛为明确的 `--start` / `--end`（ISO-8601）；若未给出，**先追问**起止时间，禁止用任意默认全天窗口代替用户意图。
+3. 执行：`dws calendar busy search --users <userId1,userId2,...> --start "<ISO>" --end "<ISO>" --format json`
+
+详见 `dingtalk-calendar` 中「查询用户闲忙状态」。
+
+## #4 文档知识
+
+### query-doc
+
+1. 全局搜索：`drive search --query "<关键词>"` → `nodeId`（聚合钉盘+文档空间）
+2. 空间内搜索：`wiki node search --workspace <WS_ID> --query "<关键词>"` → `nodeId`
+3. `doc read --node <nodeId>`（按需；大文档只抽章节）
+
+### list-folder-docs
+
+`drive list --workspace <WS_ID>` 或 `wiki node list --workspace <WS_ID>`
+
+## #5 工作汇报
+
+### query-report-list
+
+1. 收到的日志：先把用户时间词转成起止时间，再执行 `report inbox list --start "<YYYY-MM-DDT00:00:00+08:00>" --end "<YYYY-MM-DDT23:59:59+08:00>" --cursor 0 --size 20 --format json`。用户只说“最近/近期/最近收到”时默认最近 7 天。
+2. 我发过/我创建的日志：首条查询必须用 `report outbox list --cursor 0 --size 20 --format json`；如用户指定时间，补 `--start "<YYYY-MM-DDT00:00:00+08:00>" --end "<YYYY-MM-DDT23:59:59+08:00>"`。
+3. 按发件人过滤收件箱：先 `aisearch person --query "<姓名>" --dimension name --format json` 取 `userId/staffId`，再加 `--sender-user-ids <id>`；空结果必须说明未找到该发件人的日志，不得改选其他人。
+4. 面向用户时必须基于 `result[]` 拼 Markdown 表，表头固定为 `日期 | 标题 | 发送人 | 状态 | 钉钉链接`；每条 `result[]` 都会带这五个中文字段，不要把 `reportId` / `日志ID` 作为主列。
+5. 用户要正文、详情、统计、汇总或总结多篇日志时，必须用内部保留的 `reportId` 逐篇执行 `report entry get --report-id <reportId> --format json` 或 `report entry stats --report-id <reportId> --format json`；选前 5 篇时调用次数应等于实际选中篇数。
+
+时间 flag 硬约束：只允许 `--start` / `--end`；禁止 `--start-date` / `--end-date` / `--date`。不要只传 `2026-05-04`，必须展开成 `2026-05-04T00:00:00+08:00` 这种完整 ISO；禁止 UTC `Z` / `date -u`。
+
+硬约束：`report inbox list` 是收到的日志（别人发给我），`report outbox list` 是我创建/发出的日志（我发给别人）。不要混淆方向；不要回答"API 不支持收到的日志"。
+
+> 旧命令兼容：`report list` / `report inbox` / `report sent` / `report created` / `report detail` / `report stats` 仍可执行，但已 deprecated，stderr 会打废弃提醒，新计划一律使用 `inbox list` / `outbox list` / `entry get` / `entry stats`。
+
+禁止：不要先查 help，不要为了格式化列表创建脚本；不要传 `--size 50/100`。`report inbox` 可作为兼容入口使用，但新计划优先写规范命令 `report inbox list --start "<YYYY-MM-DDT00:00:00+08:00>" --end "<YYYY-MM-DDT23:59:59+08:00>" --cursor 0 --size 20 --format json`。
+
+### check-report-read-status
+
+`report entry stats --report-id <reportId>` → 已读/未读
+
+## #7 听记与会后
+
+> 产品命令完整参考见 `dingtalk-minutes`。full recipe 见 `dingtalk-minutes/references/07-minutes.md`。
+
+### minutes-query（查询与获取）
+
+> **scope 选择铁律（P2 真实 badcase）**：`list` 后的 scope 决定查询范围，最高频误判是把"我能访问的所有听记"错选成 `mine`：
+> - `mine` = **仅我自己创建/发起**的听记（范围最窄）
+> - `shared` = **仅他人共享给我**的听记
+> - `all` = **我可访问的全部**（= mine ∪ shared，范围最广）
+> - **判定口诀**：query 含"访问/权限/可见/能看到/所有/我的"等覆盖范围语义 → 一律走 `all`；**仅当**明确说"我创建的/我发起的/我录的" → 才走 `mine`。**不要因为句子里有"我"字就退化成 `mine`。**
+> - 错误：`我能访问的所有听记` → `list mine`（漏掉共享给我的，判定不通过）
+> - 正确：`我能访问的所有听记` → `dws minutes list all --format json`
+
+> **选对象铁律（0605 P2 EDD badcase 提炼，命令对了但选错听记 = 整任务失败）**：list/搜索拿到结果后，必须按语义精准锁定目标听记，详见 `dingtalk-minutes`「选对象铁律 S1~S6」。速记：
+> - **S1 跨组织汇总**：以 list 返回的 `taskUuid + title + organizationName` 三元组为准逐条照抄，组织与听记不可张冠李戴。
+> - **S2 "最近一次某类会议"**：先 `--query "<主题词>"`（如周会）过滤出该类，再在候选里取时间最新；主题匹配优先级高于时间。
+> - **S3 比时长最长**：必须读 `durationMicros` 字段做数值比较，禁止凭印象/标题猜，口头结论与操作的 taskUuid 须自洽。
+> - **S4 内容为空**：锁定 taskUuid 后所有 get/update 复用同一 id；某字段为空就如实说，**禁止偷偷切换到另一条听记**。
+> - **S5 模糊日期匹配不到**：日期可能是"会议主题日期"而非"创建日期"，按标题关键词搜，精确日期没命中就放宽 ±7 天/同主题候选请用户确认，**禁止直接报"找不到"**。搜索回退策略：① 先 `--query "<主题关键词>"` 不带日期搜 → ② 若结果过多则加 `--start/--end` 扩大到 ±7 天 → ③ 列出候选让用户确认。
+> - **S6 给标题没给 id**：必须先 `list all --query "<标题关键词>"` 定位 taskUuid 再 update/get，禁止凭记忆直接填 `--id` 跳过定位。
+
+**列表查询**（`list` 后**必须**跟 scope：`mine`/`shared`/`all`，默认补 `all`）：
+
+```bash
+# 我可访问的所有听记（默认）
+dws minutes list all --format json
+# 按关键词服务端搜索（严禁全量拉取后本地 grep）
+dws minutes list all --query "周会" --format json
+# 按时间范围筛选（ISO-8601 格式）
+dws minutes list mine --start "2026-05-01T00:00:00+08:00" --end "2026-05-25T23:59:59+08:00" --format json
+# 关键词 + 时间组合
+dws minutes list all --query "需求评审" --start "2026-05-25T00:00:00+08:00" --end "2026-05-25T23:59:59+08:00" --format json
+# 限制条数
+dws minutes list mine --limit 5 --format json
+# 共享给我的听记
+dws minutes list shared --query "ROI" --format json
+```
+
+| 参数 | 说明 |
+|------|------|
+| `--query "<关键词>"` | 服务端关键词搜索 |
+| `--start "<ISO-8601>"` | 开始时间 |
+| `--end "<ISO-8601>"` | 结束时间 |
+| `--limit <N>` | 每页条数，默认 10（`--max` 为兼容别名） |
+| `--cursor "<token>"` | 分页 token，首页留空（`--next-token` 为兼容别名） |
+
+**获取详情**：
+
+- 批量基础信息：`minutes get batch --ids <uuid1,uuid2,...>`
+- 单篇摘要：`minutes get summary --id <taskUuid>`
+- 转写原文（自动翻页）：`minutes get transcription --id <taskUuid>`（返回 `cursor` / `nextToken` / `nextCursor` 时用 `--cursor <token>` 继续）
+- 关键词：`minutes get keywords --id <taskUuid>`
+- 待办事项：`minutes get todos --id <taskUuid>`
+- 基础信息：`minutes get info --id <taskUuid>`
+- 音频地址：`minutes get audio --id <taskUuid>`
+
+> `--id`/`--uuid`/`--task-uuid` 三者等价。推荐 `--id`。
+
+### minutes-edit（编辑与替换）
+
+- **替换转写文字**：`minutes replace-text --id <taskUuid> --search "旧文字" --replace "新文字"`
+  - 执行前检查特殊字符（引号/书名号/括号等），若包含先提示用户确认去除
+  - 替换成功后追问是否加热词：`minutes hot-word add --words "新文字"`
+- **替换发言人**：先统一搜人取得 dingUid → `minutes speaker replace --id <taskUuid> --from "发言人X" --to "姓名" --target-uid <userId>`
+  - 查询 dingUid：`aisearch person --query "姓名" --dimension name --format json` → 取 `userId`
+  - 多个匹配 → 列出候选让用户选；无匹配 → 不带 `--target-uid` 执行
+- **修改标题**：`minutes update title --id <taskUuid> --title "新标题"`
+- **修改摘要**：`minutes update summary --id <taskUuid> --content "新内容"`
+- **热词管理**：`minutes hot-word add --words "词1,词2"` / `minutes hot-word list`
+- **思维导图**：`minutes mind-graph create --id <taskUuid>` → `mind-graph status --id <taskUuid>` 轮询至完成
+
+### minutes-tag（标签/分组查询）
+
+- 查询标签列表：`minutes tag list` → 返回用户在听记页面创建的所有标签/分组（含 tagId 和名称）
+- 按标签查听记：`minutes tag query --tag-id <tagId> [--limit 20] [--cursor <token>]`
+  - tagId 来自 `tag list` 返回值，不可编造
+  - 支持分页，`--cursor` 传入上一次返回的 nextToken
+
+**典型链路**：用户说"帮我看看'周会'标签下的听记" →
+1. `dws minutes tag list --format json` → 按名称匹配找到 tagId
+2. `dws minutes tag query --tag-id <tagId> --format json`
+
+### minutes-permission（权限管理）
+
+- 添加成员：`minutes permission add --ids <uuid1,uuid2> --member-uids <uid1,uid2> --policy 4`
+  - 需先通过 `aisearch person --query "<姓名>" --dimension name` 获取目标 userId
+  - policy：0=不可见 / 1=仅查看 / 2=查看+下载 / 3=查看+下载+编辑 / 4=全部权限
+- 移除成员：`minutes permission remove --ids <uuid1,uuid2> --member-uids <uid1,uid2>`
+
+### minutes-upload（音频上传）
+
+```bash
+# 创建上传会话
+dws minutes upload create --file-name "meeting.mp3" --file-size 61565431 --format json
+# 上传完成后确认
+dws minutes upload complete --session-id <sid> --format json
+# 取消上传
+dws minutes upload cancel --session-id <sid> --format json
+```
+
+### 最佳实践案例速查（详见 `dingtalk-minutes`）
+
+| 案例 | 场景 | 正确链路 |
+|------|------|----------|
+| 案例 1 | 听记 URL + 创建思维导图 | 提取 taskUuid → `mind-graph create` → `mind-graph status` 轮询；**禁止**走 app-development 或前端库 |
+| 案例 2 | 替换文字后未引导热词 | 检查特殊字符 → `replace-text` → 追问加热词 `hot-word add` |
+| 案例 3 | 查听记拉了不必要的转写 | 用户只要列表 → `list` 即可，**不要**自动拉 `get transcription` |
+| 案例 4 | 拉完转写只输出时间线原文 | 拉完后追问按发言人聚类 → 引导匹配 → 调用 `speaker replace` 写回 |
+| 案例 5 | 查某人说了什么不引导替换 | 推断发言人 → **用户确认** → 结构化总结 → 引导 `speaker replace` |
+| 案例 6 | 通讯录+部门+转写三路印证 | Step 3 画像 + Step 4 `aisearch person` 并发 → 置信度 ≥70% → 确认 → 替换 |
+| 案例 7 | grep 花名误判未参会 | **禁止**在转写文本里 grep 人名判参会；**必须**调 `aisearch person` |
+| 案例 8 | 听记类 query 不走 dws | **禁止**用 session_search/browser_use/activity:search 替代 dws；模糊请求先 `list mine` |
+| 案例 9 | 按标签筛选听记 | `tag list` → 按名称匹配 tagId → `tag query --tag-id <tagId>`；**禁止**编造 tagId |
+
+### 听记取数深度约束（0609 点踩 case 提炼）
+
+> 详细说明见 `dingtalk-minutes`。
+
+- **转写原文硬约束**：用户诉求含「聚焦原话/逐字/沟通细节/具体讨论了什么」等词时，**必须先调 `get transcription` 翻页拉全**，禁止仅凭 summary 出稿
+- **数据源下钻**：听记维度**必须 `get summary`（或 `get transcription`）读正文**，严禁只取标题列表；scope 用 `all`；空时换窗重试或标注
+- **听记链接解析**：聊天消息中遇到听记链接（`flash_minutes_detail`/`SHANJI`）→ 解析 `minutesId` → 调 `minutes get summary/transcription`，禁止把链接降级为关键词
+- **忠实性约束**：源数据无某要素（行动项/责任人/数字）时禁止生成；统计字段基于实际取数计数，不得编造
+- **多源全覆盖**：用户枚举多数据源时每个来源都必须调对应工具；瞬时错误重试；如实声明缺失来源，禁编无来源数字
+
+### 间接意图识别铁律
+
+query 未提"听记"但任务产出依赖会议讨论内容时（报告/总结/日报/复盘/商业分析/市场感知），听记采集是**必跑前置步骤**：
+
+1. **铁律 A**：任务含"会议/讨论/沟通"信息需求 → `dws minutes list` 必跑
+2. **铁律 B**：用户说"文档啥也没有" → 听记优先级更高（唯一结构化数据源）
+3. **铁律 C**：多源聚合场景 → 每个被提及的数据源都必须有采集动作，听记侧 0 调用 = 严重失败
+
+## #8 通讯录
+
+### get-contact-self
+
+`contact user get-self` → 当前用户 userId、部门、主管等
+
+### search-person
+
+**搜人首选入口**。凡是“找人/搜人/找同事/谁负责/上级/下级/负责人/团队成员”均优先用 `aisearch person`：
+
+1. 从用户问题中提取 keyword（人名/业务关键词）和 dimension（维度），规则见 `dingtalk-aisearch`。
+2. `aisearch person --query "<关键词>" --dimension <维度>`
+3. 结果中提取 `userId` 和 `title`（姓名）展示给用户。
+4. 若需要 userId 做后续操作（发消息/建待办），可直接使用结果中的 `userId`。
+5. **重名消歧**：多人同名时禁止默认选第一个，须追加 `contact user get --ids` 获取部门/职位后请用户确认，详见 `dingtalk-contact/references/08-directory.md`「多命中」。
+
+### search-user
+
+仅在以下**精确查询**场景使用，搜人请优先用 `search-person`：
+
+- 需要获取 userId 给其他产品使用（发消息/建待办/约日程）
+- 已有 userId 需查完整详情（`contact user get --ids`）
+
+1. `aisearch person --query "<姓名>" --dimension name` → `userId`；**多命中须列出候选请用户确认**。
+2. **重名消歧**：多人同名时禁止默认选第一个，须追加 `contact user get --ids` 获取部门/职位后请用户确认，详见 `dingtalk-contact/references/08-directory.md`「多命中」。
+3. 需详情时：`contact user get --ids <userId>`（多人可 `--ids id1,id2,...`）
+
+## #9 邮件
+
+### mail-list-mailbox
+
+查询当前用户自己的可用邮箱地址列表。**仅返回自己的邮箱**，不能查他人邮箱（查他人邮箱请走 `dingtalk-mail` 中「查找他人邮箱地址」三路并发查询流程）。
+
+`mail mailbox list`
+
+### mail-search
+
+搜索邮件。**必须使用 KQL 语法通过 `--query` 传递查询条件**，禁止臆造 `--subject`、`--from` 等不存在的 flag。
+
+1. 获取邮箱地址：`mail mailbox list` → 取用户邮箱地址。若用户已提供邮箱可跳过。
+2. 构造 KQL 查询：根据用户意图将搜索条件转为 KQL 表达式（详见 `dingtalk-mail` 中 KQL 查询字段说明）。
+   - 按主题：`subject:周报`、`subject:"项目 进展"`（含空格须加双引号）
+   - 按发件人：`from:alice@company.com` 或 `from:"张三"`
+   - 按日期：`date>2025-06-01T00:00:00Z`（ISO8601 格式，必须含时间部分）
+   - 按文件夹：`folderId:2`（2=收件箱, 1=已发送, 5=草稿, 6=已删除）
+   - 按是否有附件：`hasAttachments:true`
+   - 组合：`from:alice AND subject:周报 AND date>2025-06-01T00:00:00Z`
+3. 执行搜索：`mail message search --email <邮箱> --query "<KQL表达式>" --limit 20`
+4. 查看详情（按需）：`mail message get --email <邮箱> --id <messageId>`
+
+### mail-send
+
+发送邮件。
+
+1. 获取邮箱地址：`mail mailbox list` → 取用户邮箱作为 `--from`。
+2. 确定收件人：用户直接提供邮箱地址 → 直接使用；用户提供姓名 → 走「查找他人邮箱地址」三路并发流程（见 `dingtalk-mail`）。
+3. 发送：`mail message send --from <发件邮箱> --to <收件邮箱> --subject "<主题>" --content "<正文>"`（可选 `--cc`、`--attachment`、`--inline-attachment`）。
+
+### mail-reply-forward
+
+回复或转发邮件。
+
+1. 获取邮箱地址：`mail mailbox list` → 取用户邮箱。
+2. 定位原始邮件：若用户未提供 messageId → 先用 `mail-search` 搜索定位。
+3. 执行：
+   - 回复：`mail message reply --from <邮箱> --id <messageId>`（可选 `--to`、`--subject`、`--content`）
+   - 回复全部：`mail message reply-all --from <邮箱> --id <messageId>`（可选 `--to`、`--subject`、`--content`）
+   - 转发：`mail message forward --from <邮箱> --to <收件邮箱> --id <messageId>`（可选 `--subject`、`--content`）

package/skills/dws/dingtalk-shared/references/recipes/meta.md

@@ -0,0 +1,67 @@
+# Recipe 规范
+
+> 每个 recipe 是一个 **SKILL.md**，格式与产品 skill 同等身份。
+
+## 架构三层
+
+```
+Layer 1: _common/conventions.md     → 全局共享（认证、安全规则、字段术语）
+                                       相当于 gws-shared/SKILL.md
+
+Layer 2: products/*.md              → 产品能力（命令用法、flags、示例）
+                                       相当于 gws-gmail/SKILL.md, gws-docs/SKILL.md
+
+Layer 3: recipe-xxx/SKILL.md        → 组合配方（固定步骤 + 声明依赖）
+                                       相当于 recipe-send-team-announcement/SKILL.md
+```
+
+## Recipe SKILL.md 格式
+
+```yaml
+---
+name: recipe-<verb>-<object>
+description: "一句话描述"
+metadata:
+  category: "recipe"
+  domain: "<领域编号>"
+  requires:
+    bins:
+      - dws
+    skills:
+      - <product-1>
+      - <product-2>
+---
+```
+
+**正文**只包含：
+1. 标题 + 一句话描述
+2. `> **PREREQUISITE:** ...` 提示加载哪些 skill
+3. `## Steps` — 编号步骤，每步一条 `dws` 命令
+
+**不包含**（这些留给 conventions.md 和 best_practice.md）：
+- 安全门控/决策分支/踩坑提醒
+- 失败处理策略
+- 数据佐证
+
+## 命名规则
+
+```
+recipe-<verb>-<object>[-<modifier>]
+```
+
+| 动词 | 含义 | 示例 |
+|------|------|------|
+| send | 发送 | recipe-send-message |
+| create | 创建 | recipe-create-todo |
+| query | 查询 | recipe-query-doc |
+| write | 写入 | recipe-write-doc |
+| resolve | 解析 | recipe-resolve-contact |
+| generate | 生成 | recipe-generate-daily-report |
+| share | 分享 | recipe-share-doc-and-notify |
+
+## 路由规则
+
+Agent 识别意图后：
+1. 匹配到 recipe → 加载 recipe 声明的 skills → 按 Steps 执行
+2. 无匹配 recipe → 走领域 best_practice.md 策略指南
+3. 只需单个命令 → 直接查 products/*.md

package/skills/dws/dingtalk-shared/references/routing.md

@@ -0,0 +1,52 @@
+# 产品路由
+
+仅在用户泛称 DWS/钉钉操作，或者无法从意图直接选择单一产品 skill 时读取。调度器
+已经命中清晰产品 skill 时不要读取本文件。
+
+## 一级产品选择
+
+| 用户目标 | 读取目标 |
+|---|---|
+| AI 表格、多维表、字段、记录、视图、仪表盘 | [`dingtalk-aitable`](../../dingtalk-aitable/SKILL.md) |
+| 日程、参会人、会议室、闲忙 | [`dingtalk-calendar`](../../dingtalk-calendar/SKILL.md) |
+| 群聊、消息、机器人、Webhook、群成员 | [`dingtalk-chat`](../../dingtalk-chat/SKILL.md) |
+| 实时监听未来 IM 消息、reaction、已读、撤回、群生命周期或 OA 审批变化 | [`dingtalk-event`](../../dingtalk-event/SKILL.md) |
+| 已有 userId 的用户详情、部门、角色、组织关系 | [`dingtalk-contact`](../../dingtalk-contact/SKILL.md) |
+| 文档正文读取、创建、更新、块编辑、媒体和导出 | [`dingtalk-doc`](../../dingtalk-doc/SKILL.md) |
+| 文件搜索、上传下载、复制移动、重命名、权限 | [`dingtalk-drive`](../../dingtalk-drive/SKILL.md) |
+| 邮件查询、搜索、读取和发送 | [`dingtalk-mail`](../../dingtalk-mail/SKILL.md) |
+| 听记列表、摘要、转写、关键字和标题 | [`dingtalk-minutes`](../../dingtalk-minutes/SKILL.md) |
+| 待办创建、查询、更新、完成和删除 | [`dingtalk-todo`](../../dingtalk-todo/SKILL.md) |
+| 知识库/钉盘空间、空间节点和成员管理 | [`dingtalk-wiki`](../../dingtalk-wiki/SKILL.md) |
+| 姓名模糊找人、负责人、上下级、工号、手机号语义线索、企业知识和行为记录搜索 | [`dingtalk-aisearch`](../../dingtalk-aisearch/SKILL.md) |
+| 完整手机号精确反查，或已有 userId 后查人员详情、部门和角色 | [`dingtalk-contact`](../../dingtalk-contact/SKILL.md) |
+| Markdown / `.md` 内容读取、创建、覆盖、局部修改或版本差异比较 | [`dingtalk-misc`](../../dingtalk-misc/SKILL.md) → [`markdown.md`](../../dingtalk-misc/references/markdown.md) |
+| 组织大脑、人才池、员工档案专项、职业历程、绩效、结构化人才搜索 | [`dingtalk-misc`](../../dingtalk-misc/SKILL.md) → [`hrbrain.md`](../../dingtalk-misc/references/hrbrain.md) |
+| PAT 行为授权、scope 授权、授权浏览器策略 | [`dingtalk-misc`](../../dingtalk-misc/SKILL.md) → [`pat.md`](../../dingtalk-misc/references/pat.md) |
+| 切换组织、跨组织、多组织、profile 管理 | [`dingtalk-misc`](../../dingtalk-misc/SKILL.md) → [`profile.md`](../../dingtalk-misc/references/profile.md) |
+| 审批查询与处理、考勤、会议、电子表格、日志、DING、直播、开放平台应用、技能市场安装等长尾产品 | [`dingtalk-misc`](../../dingtalk-misc/SKILL.md) |
+| 宜搭 / AI 应用创建脚本 / 财务辅助脚本（无稳定产品面） | [`dingtalk-misc`](../../dingtalk-misc/SKILL.md) → [`unsupported-scripts.md`](../../dingtalk-misc/references/unsupported-scripts.md)；默认说明未产品化，勿当正式 CLI |
+
+选择 `dingtalk-misc` 后，先读取其 `SKILL.md` 产品索引，再只读取命中产品的单个
+reference，不要加载全部长尾产品文档。
+
+## 高频边界
+
+- `aisearch person`：按姓名、职责、上下级、工号或手机号线索语义找人；`contact`：
+  完整手机号精确反查，或拿到 userId 后查详情、部门和角色；`mail`：邮件内容与收发。
+- `drive`：对任何文件都成立的存储操作；`doc`：文档正文和块内容；`wiki`：空间与
+  节点组织。
+- `.md` 内容读写走 `markdown`（`dingtalk-misc`）；复制、移动、删除等实体操作走 `drive`。
+- `aitable`：字段/记录式数据表；`sheet`：单元格、公式、多工作表。`sheet` 位于
+  [`dingtalk-misc`](../../dingtalk-misc/references/sheet.md)。
+- `calendar`：日历事件、参会人和会议室；视频会议（conference）当前 CLI 不支持，请在钉钉客户端操作；
+  `minutes`：会后听记内容。
+- `report`：钉钉日志系统中的日报/周报；`doc`：普通文档创作；`todo`：个人任务。
+- `chat`：发送消息、读取历史消息和主动群操作；独立的 `event`：未来个人 IM/OA/Todo 事件长连接监听；
+  `ding`：强提醒，位于 `dingtalk-misc`。
+- `hrbrain` / `markdown` / `pat` / `profile` 均位于 `dingtalk-misc`。
+- 请假、加班、外出、出差、补卡等考勤业务审批优先走 `attendance`；其他通用审批查询、同意、
+  拒绝、转交和撤销走 `oa`。两者均位于 `dingtalk-misc`；未来审批任务或实例变化的实时通知走
+  独立的 `dingtalk-event`。
+
+边界仍无法判断时，只读取 [intent-guide.md](intent-guide.md) 的对应章节。

package/skills/dws/dingtalk-shared/references/runtime-contract.md

@@ -0,0 +1,11 @@
+## 最小 DWS 执行契约
+
+- 只通过 `dws` CLI 操作钉钉；结构化读取使用 `--format json`，按真实返回判断结果。
+- 已知命令直接执行。只有 leaf 参数或安全语义不确定时读取精确 Schema，只有 Cobra flag 不确定时读取精确 leaf Help；不要加载产品级 Catalog 代替选路。
+- 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。
+- 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 `isOrgCurrent=true` 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。
+- 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。
+- 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；需要确认时先说明对象、动作与影响，再追加 `--yes`。
+- 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。
+- 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。
+- 遇到认证、权限、profile、confirmation 或未知错误时，只加载 `dingtalk-shared` 中对应 reference；不要连续猜测替代命令。

package/skills/dws/dingtalk-shared/references/schema-usage.md

@@ -0,0 +1,88 @@
+# Schema 渐进查询
+
+`dws schema` 内嵌当前二进制公开命令面的结构化契约。**Agent 选择命令、读取参数映射/约束和安全语义时优先渐进查询 leaf Schema**；真正组装执行参数前，用 `--help` 确认当前 Cobra 接受的 flags。
+
+本节同时适用于基础/原子命令与公开内建 `+` shortcut。用户自定义或未公开 shortcut 不进入发布 Schema；是否可执行仍以当前 Cobra help 为准。
+
+## 已知命令路径例外
+
+当产品 Skill、意图表或任务 reference **已经给出精确 CLI path** 时：
+
+- 不要再查产品级/分组级 Schema，也不要加载完整 Shortcut Catalog
+- 可直接执行；只有参数、约束或安全语义不确定时才读该命令的 leaf Schema
+- 只有当前 Cobra flags 不确定时才补读 leaf Help
+
+稳定 command identity 已与真实 Cobra tree 绑定。不要读取 Catalog 文件、native annotation 或其他生成 JSON 来重新推断命令。
+
+## 四层查询
+
+```bash
+# 第 1 层：产品概览（列出产品 + 工具数 + 用途摘要）
+dws schema
+
+# 第 2 层：产品级（该产品工具的 cli_path + description + effect/risk）
+dws schema calendar --compact
+
+# 第 3 层：分组级
+dws schema "calendar event" --compact
+
+# 第 4 层：Agent leaf（参数契约）
+dws schema "calendar event create" --compact
+
+# --all：全量 leaf，仅 CI / 审计 / 参数 baseline
+dws schema --all --format json
+```
+
+### `--all` 边界（强制）
+
+`--all` 输出体积很大。仅在用户明确要求全量导出，或 CI / Catalog 审计 / 参数防丢 baseline 时使用。普通业务任务严禁用 `--all` 做命令发现，也不要把全量结果注入 Agent 上下文；必须按「产品概览 → 产品/分组 → leaf」渐进查询。
+
+完整兼容性 baseline 必须使用未裁剪的 `schema --all`；`schema --all --compact` 会移除 provenance 和接口映射字段，不得作为完整 baseline。
+
+同一工具省略 `--compact` 的 full leaf 与 `--all` 条目是同一份 `ToolSpec` 契约；compact leaf 只做展示投影，不重新解析语义。Alias 查询只改变路径视图，不得据此重写参数。若同一视图观察到内容差异，按契约漂移报告，不要选一份继续猜。
+
+### `--compact`
+
+正向字段白名单：保留 `cli_path`、`canonical_path`、`description`、`effect`、`risk`、`confirmation`、`interface_mode`、`availability`、`interface_reason`、`parameters`、`constraints`、`examples`、`use_when`、`avoid_when`；新增 full/audit 字段不会自动泄漏进 Agent 上下文。它有意不返回 `interface_ref`、参数 `property/interface_type` 和 provenance（如 `agent_metadata_source`、`effect_source`、`primary_cli_path` 等）；检查这些映射事实时，用 full leaf 配合 `--jq` 精确投影。
+
+若旧二进制报 `unknown_flag: --compact`，去掉 `--compact` 重跑同一查询；不要因此判定 leaf 不存在，也不要用 Schema 查业务数据。
+
+## 字段速查
+
+```jsonc
+{
+  "cli_path": "calendar event create",
+  "effect": "write",              // read | write | destructive
+  "risk": "medium",               // low | medium | high
+  "confirmation": "not_required", // not_required | user_required
+  "availability": "available",
+  "parameters": { "title": { "type": "string", "required": true } },
+  "constraints": { "require_together": [["a", "b"]] }
+}
+```
+
+- `confirmation=user_required` → 先确认再加 `--yes`；协议见 [confirmation.md](./confirmation.md)
+- `availability=unavailable` → 不执行；说明 `interface_reason`
+- `parameters.<flag>.required=true` / `cli_required=true` → 按 Schema/Cobra 契约提供参数
+- `constraints.require_together` → 列出的 flag 必须同时提供
+
+## Schema、Help 与业务数据边界
+
+| 信息 | 事实源 |
+|---|---|
+| 命令是否存在、Cobra 接受哪些 flags | `dws <cli_path> --help` |
+| Agent 选择、CLI 参数/required/组合约束、risk/confirmation | `dws schema "<cli_path>" --compact` |
+| CLI↔RPC 参数映射、接口绑定或 provenance 审计 | full leaf 配合 `--jq` / `--fields` 精确投影；不要把整个 full leaf 注入 Agent 上下文 |
+| shortcut 同上 | 已知路径：`dws schema --cli-path "<service> +<shortcut>" --compact --format json` |
+| 钉钉业务数据 | 真实 `read` / `search` / `list` 等命令 |
+
+Schema 与 Help 冲突是**契约漂移**：执行参数只用 Cobra 接受的 flags；安全语义冲突时采用更保守确认，无法确认则停止并报告。
+
+`dws schema` 只查询命令契约。完成发现后必须继续执行真实业务命令；不要把 Schema 结果当成业务查询结果。
+
+### 两类易混 Schema
+
+- `dws event schema <event_key> --flatten`：事件业务字段
+- `dws schema "event consume" --compact`：CLI 命令参数
+
+二者不可互相替代。

package/skills/dws/dingtalk-shared/references/url-patterns.md

@@ -0,0 +1,144 @@
+# URL 格式与处理规范
+
+## 路由第 0 步：意图直达（优先级高于 URL 探测）
+
+用户已经明确表达某产品的内容意图时，直接进入对应产品场域，不要先做 URL 类型
+探测。尤其：
+
+- 明确提到 Markdown / `.md` 文件的读取或修改，按普通文件走 `drive` 场域：
+  先 `dws drive download` 下载到本地处理，再用 `dws drive upload` 回传。
+- 明确“读这篇文档 / 编辑文档正文”进入 `doc`；明确“看这个在线表格数据”进入
+  `sheet`。
+
+仅当用户只粘贴 URL、没有明确产品意图，或意图与链接类型可能冲突时，才执行下方
+类型探测。
+
+## alidocs URL 分流决策（意图不明确时执行）
+
+收到 `alidocs.dingtalk.com` URL 且无法从指令判断产品时，必须按以下顺序判断：
+
+1. URL 路径含 `/i/p/` → **分享短链**，禁止调用 `dws doc` 任何子命令 → 按下方 [分享短链处理](#分享短链处理) 执行
+2. URL 路径含 `/i/nodes/` → **节点链接**，需探测类型 → 按下方 [alidocs URL 类型探测流程](#alidocs-url-类型探测流程) 执行
+3. URL 路径含 `/spreadsheetv2/` → **电子表格直链**，直接路由到 `sheet`，将完整 URL 原样传给 `--node` 参数
+4. URL 路径含 `/document/edit` 或 `/document/preview` 且 query 参数包含 `dentryKey` → **文档链接**，直接路由到 `doc`，将完整 URL 原样传给 `--node` 参数（URL 中不一定有 `type=d`，只需匹配路径和 `dentryKey` 参数即可）
+5. 其他 alidocs URL 格式 → 告知用户当前暂不支持该链接格式
+
+---
+
+## 已知 URL 格式
+
+需要自行拼接链接时，只能使用以下模板：
+
+| 产品 | 用途 | URL 格式 | ID 来源 |
+|------|------|----------|---------|
+| `aitable` | AI表格 Base 链接 | `https://alidocs.dingtalk.com/i/nodes/{baseId}` | `base list/search/create/get` 返回的 `baseId` |
+| `aitable` | AI表格指定数据表链接 | `https://alidocs.dingtalk.com/i/nodes/{baseId}?iframeQuery=sheetId%3D{tableId}` | `baseId` + `table create/get` 或 `base get` 返回的 `tableId` |
+| `aitable` | AI表格指定数据表+视图链接 | `https://alidocs.dingtalk.com/i/nodes/{baseId}?iframeQuery=sheetId%3D{tableId}%26viewId%3D{viewId}` | `baseId` + `tableId` + `view create/get` 返回的 `viewId` |
+| `aitable` | AI表格模板预览 | `https://docs.dingtalk.com/table/template/{templateId}` | `template search` 返回的 `templateId` |
+| `doc` | 文档链接 | `https://alidocs.dingtalk.com/i/nodes/{dentryUuid}` | `doc` 命令返回的 `dentryUuid` |
+| `sheet` | 电子表格链接 | `https://alidocs.dingtalk.com/i/nodes/{dentryUuid}` | `sheet create` 返回的 `dentryUuid` |
+| `sheet` | 电子表格直链 | `https://alidocs.dingtalk.com/spreadsheetv2/{key}/...?dentryKey={key}&type=s` | 用户提供的完整 URL，直接传给 `--node` |
+| `doc` | 文档链接（edit/preview） | `https://alidocs.dingtalk.com/document/{edit\|preview}?...&dentryKey={key}` | 用户提供的完整 URL，直接传给 `--node` |
+| `minutes` | 听记链接 | `https://shanji.dingtalk.com/app/transcribes/{taskUuid}` | `list mine/shared` 返回的 `taskUuid` |
+
+不在此表中的产品，禁止自行拼接 URL。命令返回中包含完整链接时直接使用，否则告知用户无法提供。
+
+## 分享短链处理
+
+`alidocs.dingtalk.com/i/p/{shortKey}` 是钉钉文档的**对外分享短链**，`dws doc` 命令无法解析此格式。
+
+### 识别规则
+
+URL 路径中包含 `/i/p/` 即为分享短链（无论后面是否还有子路径），例如：
+- `https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2`
+- `https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2/docs/AY39rGpMPmeVNpXZevZm8OZkXKnaoNQ7`
+- `https://alidocs.dingtalk.com/i/p/AbCdEfGh1234`
+- `https://alidocs.dingtalk.com/i/p/AbCdEfGh1234/sheets/XYZ789`
+
+> **关键**：只要 URL 中出现 `/i/p/`，无论后面跟什么子路径（`/docs/...`、`/sheets/...` 等），都属于分享短链，一律禁止调用 `dws doc`。
+
+### 处理方式
+
+**不要调用 `dws doc` 任何子命令**（包括 `doc info`、`doc read` 等），`dws` 无法解析此格式。
+
+- **需要获取文档内容时**：使用 `read_url` 工具直接读取该链接
+- **其他操作（如移动、复制、权限管理等）**：告知用户此链接为分享短链，无法直接执行复制、移动、权限管理等操作。如需保存该文档内容，建议用户在钉钉客户端中打开该页面，手动复制文本内容，然后可通过 `dws doc create` 创建一篇新文档并将内容写入
+
+```
+# 需要读取文档内容时（无论 /i/p/ 后面有没有子路径，都用 read_url）
+read_url("https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2")
+read_url("https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2/docs/AY39rGpMPmeVNpXZevZm8OZkXKnaoNQ7")
+
+# 禁止（以下全部会失败，dws 无法解析任何含 /i/p/ 的 URL）
+dws doc info --node "https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2" --format json
+dws doc read --node "https://alidocs.dingtalk.com/i/p/Y7kmbokZp3pgGLq2/docs/AY39rGpMPmeVNpXZevZm8OZkXKnaoNQ7" --format json
+```
+
+### 当 `read_url` 返回内容不完整时
+
+钉钉文档分享页是动态渲染的，`read_url` 可能只能获取到页面标题等有限信息，无法获取文档正文。此时**禁止猜测原因**（如"权限不足""文档为空""文档已删除"等），**禁止建议用户"提供 `/i/nodes/` 格式链接"**（分享短链和节点链接是不同体系，普通用户无法自行转换）。应直接告知用户：
+
+> 这个链接是钉钉文档的分享短链，由于页面是动态渲染的，我无法通过该链接直接获取文档的完整正文内容。
+>
+> 你可以：
+> 1. 在钉钉客户端中打开该文档，将正文内容复制粘贴给我
+> 2. 如果文档已保存在你的文档空间中，可以告诉我文档名称，我通过 `dws drive search` 搜索后再读取
+
+---
+
+## alidocs URL 类型探测流程
+
+`alidocs.dingtalk.com/i/nodes/{id}` 是钉钉文档空间的统一 URL，可能指向**文档、电子表格、多维表、文件、文件夹**等不同类型。**禁止仅凭 URL 就假定为文档**，必须先探测类型再路由到正确的产品。
+
+### 探测步骤
+
+```
+Step 1 → dws drive info --node "<URL>" --format json
+Step 2 → 从返回中提取 extension、nodeType 字段
+Step 3 → 按下方路由规则映射到对应产品
+```
+
+> 路由依据是 `extension`，不是 `contentType`。`drive info` 检测到
+> `adoc` / `axls` / `able` 时会自动补充在线文档信息。
+
+### 路由映射表
+
+| 条件 | 路由到产品 | 后续操作 |
+|------|-----------|---------|
+| `extension=adoc` | `doc` | 加载 `dingtalk-doc` 操作内容 |
+| `extension=axls` | `sheet` | 加载 `dingtalk-misc` 的 `references/sheet.md` 操作（仅 `axls` 在线电子表格） |
+| `extension=able` | `aitable` | 将 nodeId 作为 baseId，加载 `dingtalk-aitable` 操作 |
+| `extension=xlsx` / `xls` / `xlsm` / `csv` | `drive` | 必须用 `dws drive download` 下载到本地处理，禁止走 `sheet` |
+| `nodeType=file`（非在线文档扩展名，含 `md`） | `drive` | 下载用 `dws drive download --node <ID> --output <PATH> --format json`；上传/覆盖用 `dws drive upload` |
+| `nodeType=folder` | `drive` / `wiki` | 调用 `dws drive list --workspace <WS_ID>` 或 `dws wiki node list` 列出子节点 |
+| 以上均不匹配 | — | 告知用户当前暂不支持该类型 |
+
+> axls vs xlsx 关键区分：
+> - `axls`（钉钉在线电子表格，`contentType=ALIDOC`）→ 走 `sheet` 产品线（读/写/筛选/导出等服务端原子操作）
+> - `xlsx` / `xls` / `xlsm` / `csv`（上传到文档空间的本地表格文件，`contentType=DOCUMENT`）→ 必须走 `dws drive download` 下载到本地后再解析处理，严禁错误路由到 `sheet` 产品线（sheet 命令只支持在线表格，调用 xlsx 节点会直接报错）
+> - 用户想把在线表格导出为 xlsx 文件 → 用 `dws sheet export`（输入是 `axls`，输出是 xlsx，这是 axls → xlsx 的格式转换，不属于 xlsx 读取场景）
+
+### 示例
+
+```bash
+# 用户传入: https://alidocs.dingtalk.com/i/nodes/abc123
+dws drive info --node "https://alidocs.dingtalk.com/i/nodes/abc123" --format json
+
+# 返回 extension=axls → 在线电子表格，路由到 sheet
+dws sheet list --node "https://alidocs.dingtalk.com/i/nodes/abc123" --format json
+
+# 返回 extension=xlsx/xls/csv → 本地表格文件，必须下载处理（禁止走 sheet）
+dws drive download --node "https://alidocs.dingtalk.com/i/nodes/xlsx456" --output <PATH> --format json
+
+# 返回 nodeType=file → 普通文件，下载
+dws drive download --node "https://alidocs.dingtalk.com/i/nodes/def456" --output <PATH> --format json
+
+# 返回 nodeType=folder → 文件夹，列出子节点
+dws drive list --workspace <WS_ID> --format json
+```
+
+### 何时可跳过探测
+
+当用户指令中已明确指定产品（如"帮我读这个文档"、"看下这个表格的数据"），可结合用户意图**跳过探测**直接路由。仅在以下情况**必须执行探测**：
+- 用户只粘贴 URL，无其他上下文
+- 用户指令与 URL 实际类型可能不一致（如说"文档"但实际是表格）