dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-shared/references/capability-limits.md

@@ -0,0 +1,31 @@
+# 已知能力限制
+
+遇到以下操作时，**不要重试或变通**，直接告知用户当前不支持并建议在钉钉客户端操作。
+
+## chat
+
+| 不支持的操作 | 说明 |
+|------------|------|
+| 撤回个人身份发送的消息 | 只有 `send-by-bot` 发送的消息才能通过 `recall-by-bot` 撤回。个人身份 (`chat message send`) 发送的消息无法通过 API 撤回 |
+
+## doc
+
+| 不支持的操作 | 说明 |
+|------------|------|
+| 文档权限管理 | 不支持通过 CLI 设置文档分享/权限 |
+
+## aitable
+
+| 不支持的操作 | 说明 |
+|------------|------|
+| 创建公式/查找引用等高级字段类型 | 部分高级字段类型暂不支持 API 创建 |
+
+## minutes
+
+| 不支持的操作 | 说明 |
+|------------|------|
+| 跨听记的全局热词修正 | `replace-text` 仅修正**当前这一篇听记**的文字，不会影响后续新听记的语音识别结果。要让某个词长期不再被识别错，必须额外引导用户使用 `hot-word add` 添加个人热词 |
+
+---
+
+> 此文件随产品能力迭代更新。新增限制时按产品分类追加即可。

package/skills/dws/dingtalk-shared/references/channel-login.md

@@ -0,0 +1,26 @@
+# 受控渠道与阿里巴巴组织登录
+
+## 使用场景
+
+在以下任一场景读取本参考：
+
+- 目标组织是阿里巴巴；
+- 登录返回 `CHANNEL_REQUIRED`、`channel_not_allowed`、`enterprise_not_authorized` 或“应用暂不受信任”；
+- 用户提到渠道码、`DWS_CHANNEL`、渠道白名单或渠道归因；
+- 需要判断 `DWS_CHANNEL` 与 `DINGTALK_DWS_AGENTCODE` 的边界。
+
+## 核心契约
+
+- 将 `DWS_CHANNEL` 作为产品/分发渠道 `channelCode`。CLI 在登录权限检查和后续 MCP 请求中把它发送为 `x-dws-channel`。
+- 将 `DINGTALK_DWS_AGENTCODE` 作为执行 Agent 身份。两者是独立维度，禁止互相回填或复用。
+- 在受控渠道组织中，把 `DWS_CHANNEL` 同时加到 `auth login` 和每一条后续 `dws` 命令。只在单条命令作用域设置，禁止写入 shell profile 或对其他组织全局导出。
+- 仅使用与真实宿主/业务场景匹配的已登记渠道。禁止为了通过登录随机尝试其他渠道或伪装成别的产品。
+- 把静态 `channelCode` 视为公开路由标识，不视为密钥或可信归因凭证。长期方案必须由服务端校验宿主身份并签发短期、绑定组织和渠道的会话凭证。
+
+## 排查顺序
+
+1. 运行 `dws profile list --format json`，解析目标组织的稳定 `profile`。
+2. 确认当前宿主配置的渠道与真实业务场景匹配。
+3. 使用命令级 `DWS_CHANNEL` 重新执行 `dws auth login --profile ... --format json`。
+4. 使用相同 `DWS_CHANNEL` 和 `profile` 执行一个最小只读产品命令验证。
+5. 若仍失败，加 `--verbose` 重试一次并按原始服务端错误分类；禁止轮询尝试其他渠道。

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

@@ -0,0 +1,59 @@
+# 确认门禁协议
+
+写操作与高风险操作必须以最终 Runtime gate / leaf Schema 的 `confirmation` 为准。
+本文件是 multi 布局下的**全局协议**；各产品危险表示例索引见文末，细节仍以产品
+reference 为准。
+
+## 确认流程
+
+```text
+Step 1 → 展示操作摘要（操作类型 + 目标对象 + 影响范围）
+Step 2 → 用户明确回复确认（如「确认」/「好的」）
+Step 3 → 在原始命令末尾追加 --yes 执行（不改动业务参数）
+```
+
+## `confirmation_required` 识别与重试
+
+非交互环境（Agent/CI，stdin 非 TTY）下，写命令不带 `--yes` 时 CLI **不打印交互提示语**，
+直接失败并输出结构化错误。识别方式：
+
+- `--format json` 输出（或 stderr）中 `error.reason == "confirmation_required"`
+- 错误信息通常含「当前环境无法交互确认」
+
+遇到 `confirmation_required` 时：
+
+1. **不要当普通错误放弃**：把命令、风险等级与关键参数展示给用户，明确这是写/高风险操作
+2. 用户显式同意 → 在**原始命令**末尾追加 `--yes` 重试（不改动任何业务参数）
+3. 用户拒绝 → 终止，不得改写参数绕过门禁
+4. 想先让用户 review 具体请求：加 `--dry-run` 重试——它**不触发确认门禁**，会输出完整调用预览（`invocation.params`），用户确认预览后再换 `--yes` 执行
+
+**禁止**：
+
+- 看到 `confirmation_required` 就未经用户同意自动追加 `--yes` 静默重试
+- 把 `confirmation_required` 当网络/权限错误处理或重试
+- 用 `echo yes | dws ...` 等管道方式喂答案代替 `--yes`（技术上可能被接受，但违背显式知悉意图）
+- 换成确认更弱的底层命令来「绕过」门禁
+
+## 与 Schema 的关系
+
+- leaf Schema / Shortcut 中 `confirmation=user_required` → 必须先向用户确认再加 `--yes`
+- 不要根据 `effect` 或 `risk` 的值自行改写最终 confirmation winner
+- 字段解读见 [schema-usage.md](./schema-usage.md)
+
+`error-codes.md` 中对 `reason=confirmation_required` 的一行提示指向本协议；完整步骤以本文为准。
+
+## 高影响操作索引（入口）
+
+完整命令与边界在对应产品 skill；此处只给冷启动索引：
+
+| 产品面 | multi skill | 危险/确认细节落点 |
+|---|---|---|
+| AI 表格删除类 | `dingtalk-aitable` | 产品 `SKILL.md` / aitable references |
+| 日历删除/取消 | `dingtalk-calendar` | calendar references |
+| 群成员移除 / 机器人撤回 | `dingtalk-chat` | chat references |
+| 文档删除 / 块删除 / 权限降权 | `dingtalk-doc` | doc references |
+| 待办删除 | `dingtalk-todo` | todo references |
+| 听记全文替换 | `dingtalk-minutes` | minutes references |
+| DING 撤回 / OA 拒绝撤销等 | `dingtalk-misc` | `ding` / `oa` 等 references |
+
+不确定时：先 `dws schema --cli-path "<path>" --compact --format json` 看 `confirmation`，再按本协议执行。

package/skills/dws/dingtalk-shared/references/error-codes.md

@@ -0,0 +1,155 @@
+# 错误与恢复说明
+
+只查当前错误对应章节。先读取结构化字段，再决定修正、重试、请求用户介入或停止。
+
+## 错误返回格式
+
+```json
+{
+  "error": {
+    "code": 3,
+    "category": "validation",
+    "message": "missing required flag(s): --base-id",
+    "reason": "...",
+    "retryable": false,
+    "hint": "...",
+    "actions": ["..."]
+  }
+}
+```
+
+错误写到 stderr。`code` 是 CLI 退出码，`category` 是稳定大类：`api`、`auth`、
+`validation`、`discovery`、`internal`。其他字段按错误类型出现，不保证每次都有。
+
+## 错误分类与 Agent 行为
+
+### 可自行修复
+
+- `category=validation` 且 `available_flags`/`hint` 给出明确修正：核对 leaf Help，修正
+  一次；不要猜 flag。
+- 自然目标返回 `details.candidates`：零命中或多候选都停止并消歧，禁止选择第一项。
+- `reason=confirmation_required`：完整协议见 [confirmation.md](./confirmation.md)
+  （展示摘要 → 用户显式同意 → 原始命令追加 `--yes`；禁止静默重试、管道喂答案、换成更弱命令）。
+
+### 需用户介入
+
+- 权限不足、资源不存在、配额/权益不足：报告 `server_error_code`、`trace_id`、`hint`
+  和 `action_url`（如有），不自行改身份或尝试替代接口。
+- profile 不存在或同组织多账号无默认：让用户指定 `corpId:userId`，不要选最近账号。
+- 未知投递状态：停止重发，先查询状态；没有状态查询能力时如实报告未知。
+
+## 重试规则
+
+- `retryable=true`：遵守 `retry_after_seconds` 或 `next_retry_at`；运行时可能已经完成
+  HTTP 重试，调用方只做一次有界重试并保留相同幂等键。
+- `retryable=false`：不要重试。
+- 未出现 `retryable`：不要从 `category`、HTTP 文案或“看起来像临时错误”推断可重试；
+  使用 `--verbose` 收集诊断后停止。
+- 超时不会因为盲目增大 `--timeout` 自动变安全。只有任务确实允许更长等待且操作状态可判定时，
+  才显式调整超时。
+
+## 认证与权限
+
+- 精确的 access-token 拒绝信号会由 Runtime 自动刷新并最多重放一次；不要再包一层“重试两次”。
+- `reason=auth_refresh_failed` 或 `auth status` 返回 `authenticated=false`：保留原错误，运行
+  `dws auth status --profile <same-profile> --format json`；按返回 `hint` 恢复，必要时请用户登录。
+- HTTP/RPC 403 与普通权限不足不会触发 token 刷新；不要通过切 profile、bot 或 webhook
+  身份绕过。
+- AppKey/AppSecret 缺失只用于应用凭据配置问题；不要向普通业务用户索要凭据。
+
+---
+
+## aitable 高频错误
+
+> 参数体系: `baseId / tableId / fieldId / recordId`。CLI flag 用 kebab-case（`--base-id`），JSON 内用 camelCase（`baseId`）。
+
+- 参数缺失 / 无效请求 — 还在用旧参数 `dentryUuid` / `--doc` / `--sheet` → 改用 `--base-id` / `--table-id` / `--field-id` / `--record-ids`
+- 参数传了但服务端没收到 — flag 用了 camelCase（如 `--baseId`）→ flag 用 kebab-case: `--base-id <ID>`
+- `record query --filters` 无结果 — 单选/多选过滤用了 option name 而非 id → 先 `field get` 读取 options，用 option id 过滤
+- record create/update 失败 — `cells` key 用了字段名（应为 fieldId）；特殊字段格式错误 → 先 `field get` 拿字段目录；url 传 `{"text":"..","link":".."}`
+- 更新选项后历史数据异常 — 更新 options 没传完整列表 / 没保留原 id → 先 `field get` 取完整配置，保留已有 option 的 id
+- `cannot delete the last table` — 该表是 Base 最后一张表 → 先新建表再删旧表，或用 `base delete`
+- `formula` 类型 `not supported yet` — 部分字段类型暂不支持 API 创建 → 复杂字段拆开单独创建，先建基础结构
+
+**排查链路**: `base list` → `base get`(→tableId) → `field get`(→fieldId) → `record query`(→recordId)。别跳步，别猜 ID。
+
+**批量上限**: record 100 条 / field 15 个 / table·field 详情 10 个。
+
+---
+
+## doc 高频错误
+
+- 文档不存在 / nodeId 无效 — nodeId 或 URL 不正确、文档已删除 → `drive search` / `wiki node search` 或 `wiki node list` 重新获取正确 nodeId
+- 无下载权限 — 文档分享设置不允许 → 报告用户，建议联系文档所有者
+- `update --mode overwrite` 意外清空 — overwrite 会清空原内容后重写 → 默认用 `--mode append`，overwrite 前必须跟用户确认
+- 块编辑 blockId 无效 — blockId 过期或文档结构已变 → 先 `block list` 刷新获取最新 blockId
+- `doc_write_commit_unknown` — 某个分片写入超时，服务端是否已提交无法判断 → 不会自动重试（重放会重复追加）。`details` 给出 `chunksWritten` / `chunksTotal` / `failedStage`；先用 `doc read --node <ID>` 回读确认实际写到哪一片，只有确认未提交才重新执行，再从断点处用 `doc update --mode append` 继续追加
+
+---
+
+## calendar 高频错误
+
+- **误用顶层 `dws calendar` / 臆造 `calendar list`** — 只输入 `dws calendar` 或尝试不存在的 `calendar list` 会打印大段 Usage，易导致上下文暴涨与响应变慢 → **改用** `dws calendar event list --start "<ISO>" --end "<ISO>" --format json`，或加载 `dingtalk-calendar` 后按其日程查询 recipe 执行；详见 `dingtalk-calendar`「CLI 命令树与黄金路径」「反模式（禁止）」
+- 时间格式错误 — 未使用 ISO-8601 格式 → 标准格式: `2026-03-10T14:00:00+08:00`
+- 会议室搜索报错 / 返空 — 企业会议室超 100 条未分组查询 → 先 `room list-groups` → 按 `--group-id` 逐组搜索
+- 参与者 / 会议室添加失败 — eventId 不正确 → 先 `event list` 或 `event create` 获取正确 eventId
+- `roomId invalid` / 订房失败 — 把会议室**展示名**或用户口语当成了 `roomId` → **只能**使用 `room search` 返回 JSON 中的 `rooms[].roomId` 填入 `room add --rooms`；不得以中文名、楼层编号文案充当 ID
+- `unknown flag: --query`（会议室）— `room search` **不支持**按名称搜索 → 先 `room list-groups` 再按分组 `room search`，在返回列表中匹配名称后取 `roomId`（见 calendar.md）
+
+---
+
+## chat 高频错误
+
+- 群聊读取优先 `chat +chat-messages --group <群名或ID>`；单聊先解析唯一用户 ID 再读取。
+  自然群名多候选时读取 `details.candidates` 并让用户消歧，不取第一项。
+- 普通发送优先 `chat +dm`、`chat +send-to-group` 或 `chat +messages-send`；发送类 Shortcut
+  的最终 Schema 要求确认时，必须先确认再加 `--yes`。
+- `--group`、`--user`、`--open-dingtalk-id` 等目标参数互斥：按 leaf Help 只传一类目标。
+- `+messages-send` 的 `--text`/`--markdown`/`--media-id`/`--file` 互斥；身份、目标、
+  凭据和幂等参数还受 user/bot/webhook 能力矩阵约束。
+- `ok=false`、`partial=true`、非空 `failures` 或分页仍有 continuation 都不是完整成功；
+  必须保留 ledger，不能只返回已成功部分。
+- 机器人不在群或当前用户无管理权限：报告真实失败，需要群管理员处理；不改用当前用户身份发送。
+- 原子 `chat message send` 只用于 Shortcut 未覆盖的底层消息类型/原始字段。其正文可用
+  `--text`，不要把某个历史位置参数写法当成所有发送入口的规则。
+
+---
+
+## oa 高频错误
+
+- approve/reject 缺少 taskId — 未先获取审批任务 → 先 `approval tasks --instance-id <ID>` 获取 taskId
+- list-initiated 缺少 processCode — 未查询审批表单 → 先 `approval list-forms` 或 `detail` 获取 processCode
+- 撤销审批失败 — 非本人发起的审批 → `revoke` 只能撤销自己发起的审批
+
+---
+
+## report 高频错误
+
+> 参数体系：`templateId / reportId`。CLI flag 用 kebab-case（`--template-id` / `--contents-file`）。`contents` 数组每项含 `key/sort/content/contentType/type` 五个字段，`key/sort/type` 必须严格对齐 `template get` 返回的 `field_name/field_sort/field_type`。
+
+- `INPUT_INVALID_JSON` — `--contents` 或 `--contents-file` 内容非合法 JSON → 检查数组结构 `[{key, sort, content, contentType, type}]`
+- `INPUT_FILE_NOT_FOUND` — `--contents-file` 路径错 / sandbox OS 风格不匹配 → 先确认 sandbox OS（Windows: `C:\...` / macOS|Linux: `/...`）后改写
+- `INPUT_MISSING_PARAM` — `--template-id` 或 contents 必填缺失 → 先跑 `dws report template list --format json` 取 templateId
+- `MCP_TOOL_ERROR` + `server_error_code: PARAM_ERROR` — 服务端业务校验失败（templateId 错 / `key` 不在模版定义 / 类型不匹配 / 必填空 等多种形态都返回这一个码，且服务端不区分子原因）→ 不要靠错误信息排查具体字段，按提交链路重新走 `template list → template get → entry submit`；连续 ≥ 2 次失败必须停止重试，降级 final_reply
+- `MCP_TOOL_ERROR` + 其他 server_error_code — 查看 `technical_detail`；如出现不可读错误（仅含 `root.success当前值`），降级 final_reply 引导用户手动操作
+
+**排查链路**：`template list` → `template get`（取 `result.report_template_fields[]`，每项含 `field_name/field_sort/field_type`）→ 拼 `--contents`：`field_name → key`、`field_sort → sort`、`field_type → type`，再填 `content` 与 `contentType` → `entry submit`。**别跳步、别猜字段名、别自己改写 key 名。**
+
+---
+
+## contact / drive / mail 高频错误
+
+- contact: `dept list-children` 报错 — `--id` 传了非整数值 → deptId 必须为整数，从 `dept search` 获取
+- drive: 文件不存在 — dentryUuid 不正确 → `drive list` 逐级浏览获取正确 ID
+- drive: 上传失败 / uploadId 无效 — 跳过了 `upload-info` 步骤 → 必须先 `upload-info` 获取上传凭证，再 `commit`
+- drive: 文件名报错 — `--file-name` 缺少扩展名 → 必须包含扩展名: `report.pdf`
+- mail: 发件地址不正确 — 未先查询可用邮箱 → 先 `mailbox list` 获取邮箱地址
+- mail: KQL 搜索无结果 — 查询语法错误 → 字段值含空格用双引号: `subject:\"周报\"`
+
+---
+
+## 通用排查三步法
+
+1. **确认 ID** — 从最顶层资源逐级获取，不猜 ID、不跳步
+2. **确认参数** — flag 用 kebab-case，JSON 用 camelCase；特殊字段查产品参考文档确认格式
+3. **确认限制** — 检查批量上限和已知约束（各产品注意事项见对应产品参考文档）

package/skills/dws/dingtalk-shared/references/global-reference.md

@@ -0,0 +1,122 @@
+# 全局运行时参考
+
+只在认证、profile、公开全局 flag 或输出格式不确定时读取本文件。命令与参数事实以当前
+分支的 leaf Schema 和 Cobra Help 为准。
+
+## 认证与 profile
+
+日常业务命令会使用本地 OAuth 登录态，并在明确的 access-token 拒绝信号下自动刷新、
+最多重放当前调用一次。不要从错误文本猜测 token 状态，也不要自行循环重试。
+
+```bash
+# 查看当前 profile 的登录态；读取 authenticated/token_valid 等真实字段
+dws auth status --format json
+
+# 列出全部账号及 isCurrent/isOrgCurrent
+dws profile list --format json
+
+# 本机浏览器登录；无头环境使用 --device
+dws auth login --recommend --format json
+dws auth login --device --recommend --format json
+
+# 只指定本次组织/账号，不持久切换默认 profile
+dws auth status --profile <corpId>:<userId> --format json
+```
+
+- 同一条 IM 链路的目标解析、读取与写入必须使用同一 `--profile`。
+- `profile list` 本身不刷新 token；`auth status --profile ...` 只检查/刷新选中的 token
+  slot，不修改 `currentProfile`。
+- `auth logout` 默认退出全部账号；传 `--profile` 才缩小范围。`auth reset` 会清除本地
+  token，只有确认登录态需要重建时才使用。
+- 宿主已注入认证时不要向用户索要 token、refresh token、AppSecret 或 webhook token。
+
+### 可迁移认证包
+
+只有用户明确要求迁移登录态时才使用：
+
+```bash
+dws auth export --output dws-auth.tar.gz
+dws auth import --input dws-auth.tar.gz
+dws auth status --format json
+```
+
+认证包包含敏感凭据和解密材料；不得打印其内容，迁移完成后按用户的安全策略删除。
+平台/密钥后端限制以 `dws auth export --help` 与命令返回为准，不自行绕过。
+
+## 公开全局 flag
+
+| flag | 语义 | 默认/约束 |
+|---|---|---|
+| `--format`, `-f` | `json\|table\|raw\|pretty\|ndjson\|csv` | `json` |
+| `--fields` | 逗号分隔的输出字段筛选 | 空 |
+| `--jq` | jq 表达式过滤输出 | 空 |
+| `--profile` | 一次性指定组织或账号；支持 CSV 多选的命令由运行时决定 | 当前 profile |
+| `--timeout` | HTTP 请求超时秒数 | `30` |
+| `--dry-run` | 请求预览 | 只有 leaf 明确支持时才代表可执行预览 |
+| `--yes`, `-y` | 通过 Runtime confirmation gate | 仅在用户确认且最终 Schema 要求时追加 |
+| `--verbose`, `-v` | 增加诊断信息 | `false` |
+| `--debug` | 输出内部调试诊断 | `false`；不得泄露凭据 |
+| `--mock` | 开发调试 Mock | `false`；不得当作业务成功 |
+| `--client-id` / `--client-secret` | OAuth 应用凭据覆盖 | 必须成对、仅在明确配置任务使用 |
+
+公开 Help 不提供通用业务 `--token` flag。Webhook token 等凭据只传给声明该 leaf
+参数的命令；不要把某个 leaf 的 `--token` 推广成全局认证方式。
+
+## 输出契约
+
+### 成功输出
+
+`--format json` 直接序列化命令的真实 payload；不存在适用于所有产品的固定
+`{"success":true,"body":...}` 包装。读取 leaf 声明的字段，并保留以下完整性信号：
+
+- 分页：`hasMore`、`nextCursor`、`nextPageToken` 等当前响应字段；
+- 批量/编排：`ok`、`partial`、`failures`、`results` 等当前 Shortcut ledger；
+- 写入：返回的稳定资源 ID、投递状态或逐项失败，不用退出码代替结果验证。
+
+`table`/`pretty` 面向人工阅读，`raw` 保留原始文本，`ndjson`/`csv` 面向列表流转。
+Agent 默认使用 JSON；只有确定列表形状与下游需求时才切换格式。
+
+### 错误输出
+
+JSON 模式下，失败写到 stderr，稳定外层结构为：
+
+```json
+{
+  "error": {
+    "code": 3,
+    "category": "validation",
+    "message": "...",
+    "reason": "...",
+    "retryable": false,
+    "hint": "...",
+    "actions": ["..."]
+  }
+}
+```
+
+除 `code/category/message` 外的字段按错误类型出现。优先消费 `reason`、`retryable`、
+`retry_after_seconds`、`next_retry_at`、`details`、`available_flags`、`trace_id`、
+`server_error_code`、`hint` 和 `actions`；不要依赖自由文本子串做自动修复。
+
+## 相关环境变量
+
+| 变量 | 用途 |
+|---|---|
+| `DWS_CONFIG_DIR` | 覆盖默认 `~/.dws` 配置目录 |
+| `DWS_CLIENT_ID` + `DWS_CLIENT_SECRET` | 成对覆盖 OAuth 应用凭据；只设置一个时不会作为完整凭据对使用 |
+| `DWS_CHANNEL` | 受控分发渠道；仅在明确渠道任务中按 [channel-login.md](channel-login.md) 使用 |
+
+不要把内部调试/兼容环境变量写进普通业务流程，也不要把凭据持久写入 shell profile。
+
+## 命令自省
+
+```bash
+# 决定 Agent 选路、参数映射与确认语义
+dws schema --cli-path "chat +messages-send" --compact --format json
+
+# 核对当前二进制真实接受的 flag
+dws chat +messages-send --help
+```
+
+已知 leaf 直接执行。只有 selection、安全或参数映射不确定时查精确 Schema；只有 flag
+拼写不确定时查精确 Help。不要为一个 leaf 加载产品级全量 Catalog。