dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-misc/references/dev/webapp.md

@@ -0,0 +1,22 @@
+# 网页应用配置
+
+> 网页应用=应用的能力扩展之一，钉钉内打开的 H5；见 [devapp.md](../devapp.md) 概念地图。
+
+`dws dev app webapp get` 查配置，`webapp config` 配移动端/PC 首页和管理后台地址。参数用 `dws dev app webapp get --help` 和 `dws dev app webapp config --help` 查询；config 至少给一个配置字段。
+
+- 未配置网页应用前，`get` 返回空对象 `{}`。拿到 `{}` 就是还没配过，走 `webapp config` 首次配置。
+- `h5PageType` 未显式传入时不要假设固定默认值；配置后以 `webapp get` 回读为准。
+
+## 发现命令
+
+调用任何方法前先查清楚再敲：
+
+```
+# 浏览命令组下的子命令与 flag
+dws dev app webapp --help
+
+# 查某方法的必填参数、类型、默认值
+dws dev <command-path> --help
+```
+
+按 `--help` 输出构造 flag；不要凭旧 schema 名称猜参数。

package/skills/dws/dingtalk-misc/references/devapp.md

@@ -0,0 +1,148 @@
+# 开放平台应用管理（dev / devapp）
+
+> **渐进式文档**：本文件为路由层（MUST DO / 概念地图 / 产品索引）；各命令组的详细参数与流程在 [dev/](./dev/) 目录下按需加载。命令前缀：`dws dev`（原子）与 `dws devapp +create` 等 `+` shortcut。
+
+## MUST DO
+
+每次执行 dev 命令前，先查清楚再敲，别凭记忆或猜：
+
+1. `--help` 看命令树（一个组下有哪些子命令、flag），例 `dws dev app --help`
+2. `--help` 看叶子命令参数（flag、默认值、示例），按当前二进制输出构造；不要再依赖已下线的动态 schema
+3. 全部命令带 `--format json`
+4. 写操作：`--dry-run` 看 `invocation.params` 确认无误，再换 `--yes`（`dev connect` 例外见 [connect.md](./dev/connect.md)；MCP 见 [mcp.md](./dev/mcp.md)）
+5. 写完回读确认（`get` / `robot get` / `version status`）
+6. `clientSecret/appSecret` 不写进回答（脱敏）
+7. `robot result` 只要出现 `completionState=BLOCKED_BY_VERSION_PUBLISH` 或 `mustContinue=true`，必须继续执行 blocking `nextSteps`，不得停在 `dev connect`
+8. `dev connect` 的 `completionState=LOCAL_DEBUG_ONLY` / `doesNotPublish=true` 只代表本地调试，不能作为最终完成态
+9. `version check-approval` 若返回 `completionState=WAITING_FOR_APPROVER_SELECTION`，选择题原样展示 `approvalPromptText`（或 `approvalOptions[].label`），不得把姓名丢成泛化“候选审批人”
+10. `robot result` 若缺 `unifiedAppId` 或返回 `completionState=BLOCKED_BY_MISSING_UNIFIED_APP_ID`，必须停下要求明确的 `unifiedAppId`；禁止用 `clientId/appKey` 自动反查后继续执行版本写操作
+
+<!-- VISIBLE_SHORTCUTS_START -->
+## Shortcuts（无专用脚本/recipe 时优先）
+
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 `dws schema --cli-path "devapp +<shortcut>" --compact --format json`），在当前 Cobra flags 不确定时读取 `dws devapp <shortcut> --help`。只有参数映射、接口绑定或 provenance 审计才省略 `--compact`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service devapp --format json` 批量发现。
+
+| Shortcut | 风险 | 适用场景 |
+|---|---|---|
+| `dws devapp +create` | write | 创建开放平台企业内部应用 |
+| `dws devapp +credentials-get` | read | 读取开放平台应用凭证 |
+| `dws devapp +delete` | high-risk-write | 删除开放平台企业内部应用（不可逆） |
+| `dws devapp +disable` | high-risk-write | 停用开放平台企业内部应用 |
+| `dws devapp +enable` | write | 启用开放平台企业内部应用 |
+| `dws devapp +event-list` | read | 查询应用可用事件目录与订阅状态 |
+| `dws devapp +event-subscribe` | write | 订阅应用事件回调 |
+| `dws devapp +get` | read | 查询开放平台企业内部应用详情 |
+| `dws devapp +list` | read | 查询开放平台企业内部应用列表 |
+| `dws devapp +member-add` | write | 添加开放平台应用成员 |
+| `dws devapp +member-list` | read | 查询开放平台应用成员 |
+| `dws devapp +member-remove` | high-risk-write | 移除开放平台应用成员 |
+| `dws devapp +permission-list` | read | 查询开放平台应用权限列表 |
+| `dws devapp +robot-config` | write | 创建或更新现有应用的机器人配置（upsert） |
+| `dws devapp +robot-disable` | high-risk-write | 停用现有应用的机器人能力 |
+| `dws devapp +robot-enable` | write | 启用现有应用机器人能力（纯启用，无需配置字段） |
+| `dws devapp +robot-get` | read | 查询现有应用的机器人配置 |
+| `dws devapp +update` | write | 修改开放平台企业内部应用基础信息 |
+| `dws devapp +version-check-approval` | read | 预检版本发布是否需要审批（不实际发布） |
+| `dws devapp +version-create` | write | 基于当前配置创建应用新版本 |
+| `dws devapp +version-get` | read | 查询指定版本详情 |
+| `dws devapp +version-list` | read | 分页查询应用版本列表 |
+| `dws devapp +version-status` | read | 查询版本发布/审批状态 |
+| `dws devapp +webapp-config` | write | 配置网页应用能力 |
+| `dws devapp +webapp-get` | read | 查询网页应用配置 |
+<!-- VISIBLE_SHORTCUTS_END -->
+
+## 概念地图
+先建立领域模型，再看命令——所有命令都是对这张图上某个节点的操作，用户的模糊意图先映射到节点再选命令。
+
+### 应用是什么
+钉钉开放平台的「企业内部应用」是企业自建的扩展程序。一个应用是一个容器：
+
+```
+企业内部应用（主键 unifiedAppId）
+├── 凭证        appKey/appSecret —— 应用调 OpenAPI 的身份（credentials）
+├── 权限        权限点 scopeValue，每个权限点授权一组 OpenAPI（permission）
+├── 成员        DEVELOPER 等角色，决定谁能改这个应用（member）
+├── 安全配置    IP 白名单 / 登录重定向 / 端内免登 URL（security）
+├── 能力扩展    应用对用户「长什么样」，可同时挂多种：
+│   ├── 网页应用  钉钉内打开的 H5，配移动端/PC 首页地址（webapp）
+│   └── 机器人    群聊/单聊收发消息，走回调 URL 或接本地 agent（robot）
+└── 版本        配置改动的生效通道（version）
+```
+映射示例：「想做个钉钉里打开的网页」就是 创建应用，再配 webapp，再发版本；「做个答疑机器人」就是先创建应用拿 `unifiedAppId`，再 `robot config/enable` 配机器人，发版本后本地调试用 `dev connect`。无绑定的 `robot submit/result` 只有在结果返回明确 `unifiedAppId` 时才能续到版本发布。
+
+### ID 体系
+| 标识 | 是什么 | 用在哪 |
+|------|--------|--------|
+| `unifiedAppId` | 统一应用 ID，全树主键 | 唯一全树定位标识，所有单应用命令都用 `--unified-app-id` |
+| `appKey` = `clientId` | 应用身份标识，同一个标识的两个名字，非密钥 | OpenAPI 调用、建联；`dev app get --app-key` 只读查详情；也可作 `--app-key` 列表过滤 |
+| `appSecret` = `clientSecret` | 应用密钥，敏感 | 同上，按敏感凭证处理 |
+| `agentId` | 应用 ID，仅出现在返回数据里 | 不能用于写操作定位 |
+| `robotCode` | 机器人编号 | 加群、机器人发消息、建联 |
+
+应用定位：写操作统一只用 `--unified-app-id`；`dev app get` 可用 `--app-key` 只读查详情（`--name` 仍仅作 list 过滤）。agentId 只是返回字段，不能用于写操作定位。appKey 与 clientId 是同一标识的两个名字，无需追问区别。
+
+### 生效模型
+- 改配置不等于线上生效，需审批的变更（如 `requiredApproval=true` 的权限点）先累积在开发态，必须走版本通道才上线：
+```
+配置变更（permission add / robot config / webapp config ...）
+  → version create → check-approval（预检审批要求+候选审批人）
+  → publish（需审批时由用户选审批人）→ versionStatus=RELEASE 才生效
+```
+- 机器人等能力需版本发布后才能被搜索、加群、路由消息。
+- `robot result` 返回 `APPROVAL_REQUIRED` 时不要重复建号：这表示已建号但线上使用需走版本发布审核；若已返回 clientId/clientSecret，可先用于本地 `dev connect` 调试。
+- `robot result` 顶层 `completionState=BLOCKED_BY_VERSION_PUBLISH` / `mustContinue=true` 是硬门禁：继续执行 blocking `nextSteps`，直到版本 `RELEASE`、`AUDIT/UNDER_REVIEW`，或停在 `SELECT_APPROVER` 等用户选审批人。
+- `robot result` 顶层 `completionState=BLOCKED_BY_MISSING_UNIFIED_APP_ID` / `actionRequired=provide_unified_app_id` 表示缺少可安全写版本的应用主键：只能让用户提供明确 `unifiedAppId`，不能根据 `clientId/appKey` 的列表结果自动选择应用。
+- `dev connect` 成功只代表本地 Stream 调试可用。只要 `robot result.lifecycle.overallComplete=false`，或版本未进入 `RELEASE` / `AUDIT` / `UNDER_REVIEW`，不要总结“全部完成”“机器人已创建并成功连接”“可以在钉钉中 @机器人使用”。
+- 用户问「为什么没生效 / 机器人搜不到 / 权限加了还报错」时，先查 `version status`。
+- 两套状态别混：应用 appStatus（字符串，取值如 normal / published）是应用开关；版本 versionStatus（INIT / AUDIT / RELEASE / GRAY）是变更走到哪了。app list 不回 appStatus（恒 null），看应用状态以 app get 为准。
+
+### 边界与角色
+- 本产品只管企业内部应用。接口文档用本包 [devdoc.md](./devdoc.md)；钉钉云文档用 `dingtalk-doc`；工作台入口的「应用」用 `workbench app`；群里发消息用的机器人用 `dingtalk-chat`；审批流用本包 [oa.md](./oa.md)。
+- 角色：开发者（member DEVELOPER）改配置；管理员管启停；审批人批版本发布。
+
+## 核心规则
+1. `应用`、`机器人` 是泛词：用户只说这两个词、无开放平台上下文时，先追问确认是不是开发者后台的企业内部应用，不要猜——很可能是工作台应用或群消息机器人（转出口见上方「边界与角色」）。
+2. 应用名只可用于只读列表过滤或人工排查；`app get --app-key` 可只读查详情并拿回 `unifiedAppId`。任何写操作必须由用户或上游结果提供明确 `unifiedAppId`，不能把单条列表命中当自动确认。
+3. 权限申请/取消只接受 `scopeValue`，不传 API 名或分组名——权限点才是授权单元，API 名与权限点是多对一。
+4. 主动读取密钥走 `credentials get`（secret 的脱敏要求见 MUST DO）；例外：connect 流程内部把 secret 作为参数传给 `dev connect` 是必要用途。
+5. 审批人必须用户拍板，agent 不代选、不默认取第一个。
+6. 选审批人时优先原样展示 `approvalPromptText`（成品文案）；需结构化时读 `approvalOptions[].label`；只有都缺时才用原始 `approvalCandidates` 的 `name（userId: xxx）` 自己拼标签。
+
+### 通用出参约定（跨所有命令）
+- 游标分页（list / permission list / version list / event list / `devdoc article search`）：首次不传 `--cursor`，出参带 `nextCursor`（空=到底）原样回传续翻；`hasMore == nextCursor 非空`。cursor 是上游不透明令牌，不要自己解析或构造，也不要跨命令复用。
+- 批量聚合：`permission remove` 出参是 `{removed, removedScopeValues, rejectedScopeValues, success, message}`，逐条看 `removedScopeValues`/`rejectedScopeValues` 判断每个权限点成败。
+- pretty：`--format pretty` 会在应用/版本状态字段旁附 `*Text` 可读标签（如 `appStatusText`）；JSON 格式不附，以原始字段为准。
+- 失败：`ServiceResult.success=false` 原样透传 `errorCode/errorMsg`，不编造解释，解读走下方文档 RAG。
+
+## 开放平台文档 RAG / 错误码排查
+- dev 命令执行中，只要用户问开放平台 API、接口参数、字段含义、权限点、回调、SDK、配额、错误码，或命令返回上游 OpenAPI/SDK 错误，必须先用 `dws devdoc article search --query "<关键词>" --format json` 做官方文档 RAG（`dev doc search` 当前网关未注册该工具键，会报「未找到指定工具」，一律走 `devdoc article search`；flag 是 `--query` 不是 `--keyword`）。
+- 业务错误（`ServiceResult.success=false`）原样透传 `errorCode/errorMsg`，不要编造解释；需要解读错误含义时走 devdoc RAG。
+- 查询词优先保留原始 API 名、能力名、权限点、完整错误码和 message；首轮形如 `errcode <code> <message>`，无结果再换 `<产品/场景> <错误码>`、`<接口名> 参数`。
+- 本地 CLI 错误（如 `unknown command` / `unknown flag` / 认证）仍按 root `dws` / `dingtalk-shared` 的错误处理执行；`devdoc` 用于开放平台业务错误码和接口语义排查。
+- `devdoc` 只查钉钉开放平台开发者文档，不查业务数据；排查结论必须基于命中条目的标题、摘要或链接，不能编造错误原因或不存在的命令。
+
+## 典型任务
+端到端任务都是「定位应用，改容器某节点，按审批需要走版本生效，最后回读验证」。完整链路（建网页应用 / 权限到生效 / 建机器人接本地调试 / 排查没生效）见 [recipes.md](./dev/recipes.md)。
+
+## 产品索引
+
+按命令组直达（一命令组一文件）：
+
+| 命令组 | 参考文档 | 覆盖命令 |
+|--------|---------|---------|
+| 应用 | [app.md](./dev/app.md) | list / get / create / update / delete / disable / enable |
+| 凭证 | [credentials.md](./dev/credentials.md) | credentials get |
+| 网页应用 | [webapp.md](./dev/webapp.md) | webapp get / config |
+| 权限 | [permission.md](./dev/permission.md) | permission list / add / remove |
+| 成员 | [member.md](./dev/member.md) | member list / add / remove |
+| 安全配置 | [security.md](./dev/security.md) | security config |
+| 机器人 | [robot.md](./dev/robot.md) | robot submit / result / get / config / enable / disable |
+| 本地建联 | [connect.md](./dev/connect.md) | dev connect（渠道预检 / agent 模型工作目录 / 会话记忆 / AI 卡片） |
+| 版本发布 | [version.md](./dev/version.md) | version create / list / get / check-approval / publish / status |
+| 事件订阅 | [event.md](./dev/event.md) | event list / subscribe / unsubscribe（事件定位走搜索优先） |
+| MCP 开发 | [mcp.md](./dev/mcp.md) | mcp service / tool / auth / credential / member / hsf |
+| 索引 | [dev-index.md](./dev/dev-index.md) | 主题速查表 |
+
+## Gotchas
+- 新应用 `version list` 返回空不等于无可发布内容：先 `version create`，用返回的 `versionId` 继续 check-approval/publish。
+- `robotStatus=UNCONFIGURED` 是「应用还没配过机器人」，走 `robot config` 首次创建，不是 `enable`。

package/skills/dws/dingtalk-misc/references/devdoc-intent-guide.md

@@ -0,0 +1,7 @@
+# devdoc 局部意图消歧
+
+本文件从单 Skill `intent-guide.md` 拆分而来，仅保留与本产品相关的跨产品消歧规则。
+
+| 用户说... | 真实意图 | 应该用 | 不要用 | 理由 |
+|---|---|---|---|---|
+| "搜一下 OAuth2 接入文档" | 搜索开发文档 | `devdoc` | `doc search` | 搜索开放平台技术文档，不是钉钉内部内容 |

package/skills/dws/dingtalk-misc/references/devdoc.md

@@ -0,0 +1,42 @@
+# devdoc — 开放平台文档
+
+## 搜索开放平台文档
+```
+Usage:
+  dws devdoc article search [flags]
+Example:
+  dws devdoc article search --query "OAuth2 接入" --page 1 --size 10 --format json
+Flags:
+      --query string     搜索关键词 (必填)
+      --page string      页码 (默认 1)
+      --size string      每页数量 (默认 10)
+```
+
+## 意图判断
+
+- 用户说"开发文档 / API 文档 / 接口文档 / 调用报错" → `devdoc article search`
+
+## 上下文传递
+
+| 操作 | 从返回中提取 | 用于 |
+|------|-------------|------|
+| `devdoc article search` | 文档链接 | 直接展示给用户 |
+
+---
+
+## SKILL 摘要（原 dingtalk-devdoc/SKILL.md 正文）
+
+## 意图表
+
+| 用户说 | 命令 |
+|--------|------|
+| "查 OAuth2 接入文档" | `dws devdoc article search --query "OAuth2 接入"` |
+| "API 调用报错怎么办" | `dws devdoc article search --query "<报错关键词>"` |
+| "开放接口文档" | `dws devdoc article search --query "<接口名或场景>"` |
+
+## 跨产品协作
+
+- 钉钉云文档（个人 / 企业内文档）→ 切到 `dingtalk-doc`
+## 局部意图与 Recipe
+
+- [局部意图消歧](devdoc-intent-guide.md)。

package/skills/dws/dingtalk-misc/references/ding.md

@@ -0,0 +1,184 @@
+# DING 消息
+
+完成 shared 前置读取后，本页是 DING 唯一默认 Reference。已知路径直接执行；仅在
+真实 `unknown command` / `unknown flag` 时读一次 leaf Help，契约不确定时读一次
+compact leaf Schema。业务失败不是命令漂移，不能触发命令探索。
+
+## 机器人写前门禁
+
+用户明确指定企业机器人时，写入前固定主体和通道：
+
+1. 用户给出真实 `robot-code` 时才传 `--robot-code`。用户指定某个机器人显示名但没给
+   该机器人的 code 时，写前直接以 `robot_credentials_missing` blocked；显示名不是 code，
+   也不能用环境中的默认机器人替代。
+2. 用户只要求企业机器人、没有指定具体机器人时，省略 `--robot-code` 并执行一次；
+   Runtime 只解析已配置的 `DINGTALK_DING_ROBOT_CODE`，Agent 不读取、打印或探测该变量。
+3. 缺凭据返回 `robot_credentials_missing`；机器人无效或不在当前组织返回
+   `robot_not_in_org`。两者都为 `retryable=false`；首次明确失败即 blocked，不执行
+   `dws auth login`，也不再发第二次请求。
+4. blocked 后禁止重试、`--verbose`、Help/Schema、dev/devapp、chat bot、配置目录、
+   其他 profile、日志或评测文件搜索；禁止切换为个人身份、其他机器人或其他通道。
+   CLI 不枚举候选 robot-code，也不使用另一个机器人的凭据补偿本次失败。
+5. 只有用户提供新的有效 robot-code、明确切换组织或重新指定主体/通道，才开始新的
+   逻辑请求。
+
+## 意图与入口
+
+| 用户意图 | 首选入口 | 身份/边界 |
+|---|---|---|
+| 查历史、未读、已发、评论或删除记录 | `dws ding message list` | 按 `openDingId` 识别消息 |
+| 查一个 DING 的接收状态 | `dws ding +receiver-status` | 必须已有 `openDingId` |
+| 发 DING，未指定机器人 | `dws ding message send-personal` | 当前用户；接收人用 `openDingTalkId` |
+| 明确用企业机器人发送 | `dws ding message send` | 接收人用 `userId`；需要 `robot-code` |
+| 把聊天消息转为 DING | `dws ding message send-by-message` | 使用目标会话和消息的稳定 ID |
+| 撤回当前用户 DING | `dws ding message recall-personal` | 使用发送回执的 `openDingId` |
+| 撤回机器人 DING | `dws ding message recall` | 使用同一 `robot-code` 和 `openDingId` |
+| 普通聊天、建群、群消息和解散群 | `dingtalk-chat` | Chat 拥有群资源，DING 只负责强提醒 |
+
+全链使用同一 profile。零/多候选、身份不明或 profile 不一致时停止，禁止取首项或
+按内容猜 ID。成功必须有业务回执；失败、投递未知、未确认状态不得报成功。
+
+## 完成条件
+
+| 用户要求 | 完整成功必须具备 |
+|---|---|
+| 发送 | 指定主体/通道的成功回执和真实 `openDingId` |
+| 发送并查状态 | 同一 `openDingId` 的精确接收状态 |
+| 发送、查状态并撤回 | 前两项完成，且同一主体的 DING recall 返回成功终态 |
+| 全部/多页列表 | 明确分页终止证据；否则只能报告 partial 和停止原因 |
+| `sms` / `call` | 实际主体、实际通道、费用属性、`openDingId` 与请求后续终态 |
+
+完整发送—查询—撤回链不得中途缩减；Runtime 再次确认时按结构化停点续接，保留
+待执行动作和稳定 ID。
+
+## 调用与上下文预算
+
+- 每个姓名只解析一次；同一逻辑请求的 send、status、recall 各最多一次。仅用户明确
+  要求等待时，status 才有界轮询。
+- 先用单次响应完整校验，再无损投影；`{actor, channel, openDingId, status, recall,
+  pagination}` 只是最小集合，正文、收件人、时间等用户要求字段必须原样保留。
+- 投影只减少重复上下文，不删除业务信息，也不得为恢复已丢字段重发远端请求。最终
+  报告所需事实、条数和完整性；禁止为整理输出追加 list、Help 或 Schema。
+
+## 身份与稳定 ID
+
+姓名接收人只解析一次：
+
+```bash
+dws aisearch person --query "<姓名>" --dimension name --format json
+```
+
+| 用途 | 参数 | 稳定来源 |
+|---|---|---|
+| 机器人发送 | `--users <userId,...>` | 人员解析的 `userId` |
+| 个人发送/消息转 DING | `--users <openDingTalkId,...>` | 人员解析的 `openDingTalkId` |
+| 消息转 DING | `--group` / `--message-id` | 目标聊天回执的 `openConversationId` / `openMessageId` |
+| 状态查询/撤回 | `--ding-id` / `--id` | 发送回执或真实列表的 `openDingId` |
+
+这些 ID 不可互换；机器人凭据、主体与 profile 按“机器人写前门禁”处理。
+
+## 消息转 DING 的资源生命周期
+
+`send-by-message` 是“源聊天消息 → 新 DING”转换。成功回执同时保存以下身份，禁止
+覆盖到同一个变量：
+
+| 字段 | 资源类型 | 后续用途 |
+|---|---|---|
+| `sourceMessageId` | chat message | 仅用于聊天消息查询或撤回 |
+| `sourceConversationId` | chat conversation | 来源审计和会话定位 |
+| `openDingId` | ding | DING 接收状态和撤回 |
+| `recallTarget` | ding | `{resourceType: "ding", openDingId}` |
+
+转换后撤回时，只执行：
+
+```bash
+dws ding message recall-personal --id <OPEN_DING_ID> --format json
+```
+
+撤回前根据回执字段和 `resourceType=ding` 校验来源，只使用 `openDingId`，不得拿
+`sourceMessageId` 或会话 ID 替代。`openDingId` 是不透明标识，不依据 `msg` / `cid` 前缀
+推断资源类型；裸 `--id` 的资源有效性由服务端校验，CLI 只拒绝空白值，不额外查询。
+若结构化证据表明目标属于 Chat，立即停止并重新取得 DING 回执；不能改用 Chat 撤回
+来宣称完成。服务端拒绝后也不切换资源、身份或重放。
+
+## 临时群消息转 DING 的有界状态链
+
+这类跨产品任务只为群生命周期加载 `dingtalk-chat` 的 `group-admin.md`；不加载聊天消息
+查询、搜索或消息动作 Reference，除非用户另外要求操作源聊天消息。人员只使用
+`dingtalk-aisearch` 根 Skill 的 person 入口，不加载其二级 Reference；按“身份与稳定 ID”
+一次解析后，同时复用其 `openDingTalkId` 建群和作为 DING 接收人，禁止在 Chat 内再次按
+姓名解析。
+
+1. `dws chat +chat-create --name "<群名>" --users <OPEN_DINGTALK_IDS> --format json`；
+   保留完整回执，后续只使用其中的 `openConversationId`，创建失败不继续。
+2. `dws chat +messages-send --as user --group <OPEN_CONVERSATION_ID> --text "<正文>"
+   --format json`；保存完整响应及 `sendReceipt`，不要改用只返回粗粒度结果的发送入口。
+3. `sendReceipt.readyForMessageActions=true` 时直接读取
+   `messageRef.openMessageId/openConversationId`；否则只用其中的 `openTaskId` 调用一次
+   `dws chat +messages-query-send-status --open-task-id <OPEN_TASK_ID> --format json`。
+   状态仍未给出完整 `messageRef` 时报告 pending/blocked，不执行 `+chat-messages`、内容
+   搜索或重复发送来猜消息 ID。完整 `messageRef.openConversationId` 必须等于建群回执的
+   `openConversationId`；不一致时立即 blocked。
+4. 完整 `messageRef` 就绪后执行一次 `dws ding message send-by-message`。保存转换回执的
+   `sourceMessageId`、`sourceConversationId`、`openDingId` 和 `recallTarget`；同一请求需要
+   幂等控制时生成一次 `--uuid` 并始终复用。
+5. 只有用户要求时才用 `openDingId` 查 DING 接收状态或撤回 DING；不得撤回源 Chat
+   消息来代替 DING 撤回。临时群最后只用
+   `dws chat +chat-dismiss --group <OPEN_CONVERSATION_ID> --format json` 解散一次。
+
+默认调用预算是：每个不同人员一次解析、一次建群、一次群消息发送、至多一次发送状态
+查询、一次消息转 DING、一次临时群解散；DING 状态和撤回仅按用户要求各一次。最终结果
+保留人员映射、`openConversationId`、`openTaskId`、`sourceMessageId`、`openDingId`、投递/
+撤回状态和清理结果；某一步失败时同时报告此前已提交的资源，不能用减少上下文掩盖部分成功。
+
+## 查询与分页
+
+```bash
+dws ding message list --type <ALL|UNREAD|SEND|NEW_COMMENT|DELETED> \
+  --cursor 0 --format json
+dws ding +receiver-status --ding-id <OPEN_DING_ID> --format json
+```
+
+- list 项已含 `content`、`openDingId` 和状态；读取这些字段不追加详情调用。
+- list 不传 `--type` 时按 `ALL` 查询；首次 `--cursor 0`，后续只用响应的 `nextCursor`。
+- 只有 `hasMore=true` 且 `nextCursor` 是严格前进的正整数时继续；达到用户上限、
+  `hasMore=false`、游标缺失、停滞或循环时立即停止并如实说明完整性。
+- 跨页默认按 `openDingId` 去重。只有用户明确要求内容合并时才按规范化内容去重，
+  并同时报告原始条数和合并后条数。
+
+## 发送与撤回
+
+```bash
+# 当前用户身份
+dws ding message send-personal \
+  --users <OPEN_DINGTALK_ID> --content "<内容>" --type app --format json
+
+# 企业机器人身份
+dws ding message send \
+  --users <USER_ID> --content "<内容>" --type app --format json
+
+# 聊天消息转 DING
+dws ding message send-by-message \
+  --group <OPEN_CONVERSATION_ID> --message-id <OPEN_MESSAGE_ID> \
+  --users <OPEN_DINGTALK_ID> --type app --format json
+
+dws ding message recall-personal --id <OPEN_DING_ID> --format json
+dws ding message recall --id <OPEN_DING_ID> --format json
+```
+
+- 企业机器人命令只有在用户提供真实 code 时才追加 `--robot-code <ROBOT_CODE>`；否则
+  按“机器人写前门禁”决定省略参数执行或在写前 blocked。
+- `app` 免费；`sms` / `call` 有通信费用。费用知情与 Runtime 写确认分别处理。
+- 需要调用方控制幂等时，为个人发送或消息转 DING 生成一次稳定 `--uuid`；同一
+  逻辑请求的安全重试必须复用，不能为每次尝试生成新键。
+- 跨产品补偿由工作流所有者负责；DING 返回真实失败状态和已产生的稳定资源 ID。
+
+<!-- VISIBLE_SHORTCUTS_START -->
+## Shortcuts（无专用脚本/recipe 时优先）
+
+以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 `dws schema --cli-path "ding +<shortcut>" --compact --format json`），在当前 Cobra flags 不确定时读取 `dws ding <shortcut> --help`。只有参数映射、接口绑定或 provenance 审计才省略 `--compact`。仅当现有路由和 reference 都无法定位低频能力时，才用 `dws shortcut list --service ding --format json` 批量发现。
+
+| Shortcut | 风险 | 适用场景 |
+|---|---|---|
+| `dws ding +receiver-status` | read | 查询 DING 消息接收人已读状态 |
+<!-- VISIBLE_SHORTCUTS_END -->

package/skills/dws/dingtalk-misc/references/hrbrain.md

@@ -0,0 +1,67 @@
+# Hrbrain（组织大脑）
+
+> 本文件为 `dingtalk-misc` 内组织大脑产品入口。命令前缀：`dws hrbrain`。Distinct from `dingtalk-contact`（通讯录/组织架构）、考勤（本包 `attendance.md`）。
+
+## 产品说明
+
+Hrbrain 是钉钉组织大脑，提供人才池管理、员工档案查询、人才搜索三大能力。
+
+**CLI 前缀**: `dws hrbrain`
+
+## 命令总览
+
+### talent-pool (人才池管理)
+
+| 命令 | 用途 | 必填参数 | 备注 |
+|------|------|----------|------|
+| `talent-pool list` | 查询人才池列表 | - | 可选 `--keyword`、`--pool-type`、`--creator`、`--labels`（逗号分隔）、`--page`、`--page-size` |
+| `talent-pool detail` | 获取人才池详情 | `--pool-code` | - |
+| `talent-pool employees` | 查询人才池内人员列表 | `--pool-code` | 可选 `--page`、`--page-size` |
+
+### profile (员工档案管理)
+
+| 命令 | 用途 | 必填参数 | 备注 |
+|------|------|----------|------|
+| `profile metadata` | 查询员工档案元数据结构 | `--work-no` | 用于构造 `profile query` 的 `--data-queries` |
+| `profile query` | 按模块批量查询员工档案数据 | `--work-no` `--data-queries` | `--data-queries` 为 JSON 数组，每项含 `modelCode`、`fields` |
+| `profile labels` | 获取员工标签 | `--staff-ids` | 逗号分隔工号列表；可选 `--all-label` |
+| `profile career` | 查询员工公司内职业历程 | `--work-no` | - |
+| `profile performance` | 查询员工绩效记录 | `--work-no` | - |
+
+### search (人才搜索)
+
+| 命令 | 用途 | 必填参数 |
+|------|------|----------|
+| `search employees` | 人才搜索（简单条件） | - |
+| `search employees-structured` | 高级结构化搜索 | `--origin-json` `--fields` |
+| `search fields` | 获取高级搜索字段列表 | - |
+
+## 意图判断
+
+- "人才池/储备干部池" → `talent-pool list/detail/employees`
+- "员工档案/档案数据" → `profile metadata/query`
+- "员工标签" → `profile labels`
+- "职业历程/内部履历" → `profile career`
+- "绩效记录" → `profile performance`
+- "搜人/按条件找人" → `search employees`（简单）或 `search fields` + `search employees-structured`（复杂）
+
+## 常用命令
+
+```bash
+dws hrbrain talent-pool list --page 1 --page-size 20 --format json
+dws hrbrain talent-pool detail --pool-code POOL_CODE --format json
+dws hrbrain talent-pool employees --pool-code POOL_CODE --format json
+dws hrbrain profile metadata --work-no WORK_NO --format json
+dws hrbrain profile query --work-no WORK_NO --data-queries '[{"modelCode":"basic","fields":["name","dept"]}]' --format json
+dws hrbrain profile labels --staff-ids WORK_NO1,WORK_NO2 --format json
+dws hrbrain profile career --work-no WORK_NO --format json
+dws hrbrain profile performance --work-no WORK_NO --format json
+dws hrbrain search employees --keyword "张三" --format json
+dws hrbrain search fields --format json
+dws hrbrain search employees-structured --origin-json '{"rules":[{"field":"name","operator":"contains","value":"张"}],"combinator":"and"}' --fields '[{"label":"姓名","value":"name"}]' --format json
+```
+
+## 安全规则
+
+- `--data-queries`、`--fields`、`--origin-json` 必须是合法 JSON；`--staff-ids`、`--labels`、`--order-by` 是逗号分隔字符串。
+- `talent-pool list` 需要账号单独开通人才池查看权限（`errorCode=2002` 时提示用户联系管理员开通）。

package/skills/dws/dingtalk-misc/references/live.md

@@ -0,0 +1,23 @@
+# live — 直播
+
+## 查看我的直播列表
+```
+Usage:
+  dws live stream list [flags]
+Example:
+  dws live stream list --format json
+```
+
+## 意图判断
+
+- 用户说"直播 / 我的直播" → `live stream list`
+
+---
+
+## SKILL 摘要（原 dingtalk-live/SKILL.md 正文）
+
+## 意图表
+
+| 用户说 | 命令 |
+|--------|------|
+| "我的直播 / 直播列表" | `dws live stream list` |