dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-aitable/references/aitable-record-ops.md

@@ -0,0 +1,80 @@
+# AI 表格记录操作
+
+仅在任务涉及记录历史、分享、删除恢复、空行或特殊字段值时读取。普通 query/create/update/upsert 走根 Skill；复杂 filter/sort、附件上传和主键文档由根 Skill 分别选择对应终点 Reference。
+
+本文不负责 Base/Table/Field 选路；读取后不要继续加载其他 AITable Reference。
+
+## 查询
+
+```bash
+dws aitable +record-query --base-id <B> --table-id <T> --record-ids <R1,R2>
+dws aitable +record-query --base-id <B> --table-id <T> --record-ids <R1,R2> --field-ids <F_NAME,F_STATUS>
+dws aitable +record-query --base-id <B> --table-id <T> --query "关键词" --limit 100
+dws aitable +record-query --base-id <B> --table-id <T> --filters '<JSON>' --sort '<JSON>'
+dws aitable record query --base-id <B> --table-id <T> --filters '<JSON>' --all --page-limit 50
+```
+
+- `record-ids` 用于稳定 ID 精确读取；`query` 用于全文搜索；复杂条件用 `filters`。
+- 用户要求“只返回/仅查看”指定列时，查询必须在工具层传 `--field-ids <ID1,ID2>`。不要先拉取全部字段再只在最终答复中删列；字段投影既是结果契约，也是降低响应 token 的手段。
+- filters 使用 `{"operator":"and|or","operands":[...]}`，字段引用使用 fieldId。明确出现 AND/OR、日期或比较操作符时，应由根 Skill 直接选中记录筛选 reference；不要先读本文件再跳到第二个 reference。
+- `+record-query` 必须传真实 `base-id` 和 `table-id`。URL 先用 `+url-resolve`；名称先用 `+resolve-base` / `+resolve-table` 唯一解析，禁止自动选第一项。
+- 单页 `limit` 为 1-100。返回 `data.records`、`data.hasMore`，存在后续页时还会返回 `data.nextCursor`；把该值原样传给下一次 `--cursor`。
+- `+record-query` 不提供 `--all`；明确要求全量时改用原子 `record query --all --page-limit <N>`。达到页上限后仍有 `hasMore=true` 代表截断，应从返回 cursor 续跑；只有 `hasMore=false`，或按 `record-ids` 查询且所有请求 ID 均已返回时，才能声称结果完整。
+- 出现 `pagination_cursor_cycle`、相同 cursor 或重复页时，保留已取记录并立即停止；不要用相同参数重跑，也不要更换查询命令把不完整结果误报为完整。
+
+## 新增
+
+当前没有 `+record-create`，使用原子命令：
+
+```bash
+dws aitable record create --base-id <B> --table-id <T> \
+  --records '[{"cells":{"fldText":"内容"}}]' --format json
+```
+
+长 JSON 写到 cwd 内相对文件后使用 `--records-file ./records.json`。从真实返回的 `data.newRecordIds[]` 取 recordId，再用 `+record-query --record-ids` 回读；用户限定返回列时同时传 `--field-ids`。不要从输入顺序、名称或行号推断 ID。
+
+## 更新、同步与批量修改
+
+已知 recordId：
+
+```bash
+dws aitable +record-update --base-id <B> --table-id <T> \
+  --records '[{"recordId":"<R>","cells":{"fldStatus":"完成"}}]'
+```
+
+`+record-update` 自动按 100 条分片并逐批回读；该 shortcut 只接受 `--records`。超长文件输入需要改用原子 `record update --records-file`，不要给 shortcut 猜造 flag。
+
+批量 shortcut 必须检查 `completed/failed`、`verification` 和 `checkpoint`；`partial_success` 不是完成。存在失败项时保留已完成批次和续跑位置；写入效果未知时只按真实 recordId 回读，不重放成功批次。
+
+单选、多选等字段的写入值可能是名称字符串，读回则是 `{id,name}` 或对象数组。若 shortcut 因原始类型不同返回 commit-unknown/read-back mismatch，禁止重放更新；只按返回的 recordId 做一次 `+record-query`，把单选按 `name`、多选按名称集合归一化比较。归一化后与目标一致时，按“独立读回已确认写入”报告，并保留 shortcut 的误报信息供排障。
+
+按业务唯一键同步使用 `+record-upsert-by-key`：0 条创建、1 条更新、多条冲突停止。按条件批改使用 `+record-bulk-patch`，必须提供 filters/query/record-ids 中至少一种选择条件，或显式 `--all`，并设置合理 `--max-matches`。
+
+## 删除
+
+```bash
+dws aitable +record-delete --base-id <B> --table-id <T> --record-ids <R1,R2>
+```
+
+删除不可逆。只使用已确认的真实 recordId；shortcut 自动分片并验证记录已不存在。未知结果按 recordId 回读，不重放已完成批次。
+
+## 常用字段值
+
+| 字段类型 | 写入值 |
+|---|---|
+| 文本、单选 | 字符串；单选使用已有选项名称 |
+| 多选 | 选项名称数组 |
+| 数字、评分 | JSON number |
+| 复选框 | boolean |
+| 日期 | 按字段配置要求的时间值；不凭展示文本猜格式 |
+| URL | 按当前字段 Schema 要求的对象或字符串 |
+| 人员、关联记录 | 使用真实 userId/recordId，不用姓名代替 |
+| 附件 | 先用 `+attachment-put` 获得 AITable 附件 token，再写字段 |
+
+公式、查找引用、创建人/时间、修改人/时间等只读字段不得写入。字段类型不明时只读取目标字段配置一次。
+
+## 历史与分享
+
+- 记录历史：`dws aitable +record-history-list --base-id <B> --table-id <T> --record-id <R>`。已有真实 recordId 直接执行，不扫描 Help 或产品 Catalog。
+- 批量记录分享：`dws aitable +record-share-links --base <B> --table <T> --record-ids <R1,R2>`；单条也可用 `+record-share-url`。
+- 用户要求把分享链接“发给”联系人时，AITable 的职责在链接生成后结束；随后加载 `dingtalk-chat`，用 `dws chat +dm --to <姓名> --text <包含全部链接的文本>` 对每位收件人分别发送并检查真实回执。只解析联系人或只生成 URL 都不算完成。

package/skills/dws/dingtalk-aitable/references/aitable-section.md

@@ -0,0 +1,30 @@
+# AI 表格 Section 与内部节点
+
+只在用户操作 Base 内文件夹（Section）或把 Table/Dashboard 移入、移出 Section 时读取。这里的节点是 nsheet 业务节点，不是独立 Drive dentry；不要加载 Drive Skill 或尝试 Drive move。
+
+## 高频闭环
+
+创建 Section 并移动节点：
+
+```bash
+dws aitable +section-create --base-id <B> --name "归档区" --format json
+dws aitable +section-move-node --base-id <B> --node-id <TABLE_OR_DASHBOARD_ID> --new-parent-section-id <S> --format json
+dws aitable +section-list-nodes --base-id <B> --format json
+```
+
+移动回 Base 根目录时显式传空字符串，不能省略该参数或改用 Drive：
+
+```bash
+dws aitable +section-move-node --base-id <B> --node-id <N> --new-parent-section-id '' --format json
+```
+
+后续操作只使用本次创建真实返回的 sectionId。若列表、移动或重命名对同一 sectionId 返回不存在或父节点无效，保留创建返回与后续错误并停止；不要创建替代 Section、更换 ID、重读本文或查询 Help/Catalog，也不要修改无关节点。
+
+## 删除空 Section
+
+1. 用 `+section-list-nodes` 核对目标 Section 内节点；需要移出的节点逐个 `+section-move-node`。
+2. 用 `+section-list-empty --base-id <B>` 验证目标 sectionId 确实为空。
+3. 执行 `+section-delete --base-id <B> --section-id <S>`；按 Runtime confirmation 处理。
+4. 再次 `+section-list-nodes` 或 `+section-list-empty`，确认 Section 已不存在且被移动节点仍在预期父级。
+
+Table 本身的创建、复制、改名、删除分别使用 `+table-*`；Section 只管理 Base 内目录关系。

package/skills/dws/dingtalk-aitable/references/aitable.md

@@ -0,0 +1,59 @@
+# AITable 低频原子能力索引
+
+> 返回入口：[DingTalk AITable Skill](../SKILL.md)
+
+本文件只用于根 Skill 和精确操作 Reference 都未覆盖的低频底层能力。Base/Table 创建、记录 CRUD、筛选排序、视图、导入导出和 Dashboard 等已覆盖能力必须返回根 Skill；本文件不直接导航到其他 AITable Reference。
+
+## 使用边界
+
+1. 只有任务确实需要 Shortcut 未发布的底层字段、原始响应或运维控制时才读取本文件；
+2. 若任务已由根 Skill 或某个精确 Reference 覆盖，立即返回根 Skill 重新选路，不在本文件继续导航到另一个 Reference；
+3. 已知命令且参数完整时直接执行；只有 leaf 参数或安全语义不确定时才读精确 Schema，只有 Cobra flag 不确定时才读该 leaf Help；
+4. 名称或 URL 目标仍必须解析为当前 profile 下的唯一稳定 ID，禁止选择第一个候选；
+5. 原子写 leaf 的 confirmation 与对应 Golden Shortcut 不一致时停止，以 Runtime gate 和精确 leaf Schema 为准；
+6. 完成后保留稳定 ID、验证证据、partial failure、checkpoint 和真实错误。
+
+## 返回规则
+
+Base、Table、普通 Field、普通 Record、View、Dashboard、筛选排序、导入导出等已覆盖能力全部返回根 Skill；本索引不重复维护高频路由，也不作为 Reference 之间的中转站。
+
+## 低频底层命令族
+
+下表只是最后回退的导航，不是可预加载的命令目录。命中后若参数或安全语义仍不确定，才读取精确 leaf Schema。
+
+| 原子命令或命令族 | 仅用于 |
+|---|---|
+| `base get-primary-doc-id` | 统一 Base/Record 路由未投影所需底层主文档 ID 时 |
+| `record get` | 必须获取单条记录原始响应，且 `+record-query --record-ids` 不能交付所需字段时 |
+| `field search-options` | 只需在已知选项字段中搜索选项，不需要完整字段配置时 |
+
+## 低频批处理脚本
+
+只有根 Skill 已定位到对应低频任务、且原生命令需要重复编排时才使用；脚本参数以 `--help` 和脚本内校验为准，不因脚本存在而跳过目标解析、确认或结果验证。
+
+| 脚本 | 仅用于 |
+|---|---|
+| `python scripts/aitable_export_via_task.py <baseId> --scope all` | 已由根 Skill 选中导出任务，需要轮询 `taskId` 并下载结果时；表或视图范围使用稳定 `tableId` / `viewId` |
+| `python scripts/bulk_add_fields.py <baseId> <tableId> fields.json` | 已完成字段类型与配置校验后批量创建大量字段；少量普通字段走根 Skill 次级直达 |
+
+## 稳定 ID 传递
+
+| 来源 | 只可用于 |
+|---|---|
+| `+url-resolve` / `+resolve-base` / `+base-search` 唯一结果 | 当前 profile 下的 `baseId` |
+| `+resolve-table` / `+list-tables` | 当前 Base 下的 `tableId` |
+| `field list` / `+field-get` | 当前 Table 下的 `fieldId` |
+| `record create` / `+record-query` | 当前 Table 下的 `recordId` |
+| `view create` / `+view-get` | 当前 Table 下的 `viewId` |
+| Dashboard 或 Chart 创建结果 | 当前 Base 下的 `dashboardId` / `chartId` |
+
+`baseId` / `tableId` / `fieldId` / `recordId` / `viewId` 是不同类型，不得轮流代入试错。Base 复制目标按根 Skill 的 Golden Route 解析。
+
+## 故障处理
+
+- `unknown command` / `unknown flag`：读取精确 leaf Help，最多做一次有证据的修正；
+- confirmation 或参数约束不清：读取精确 leaf Schema，以 Runtime gate 为准；
+- `partial_success`：保留已完成项和 checkpoint，只执行结果给出的继续或恢复命令；
+- 写入结果为 `unknown`：先按稳定 ID 或业务唯一键回读，未确认前不重试非幂等写；
+- `retryable=false` 或 ID 类型错误：停止，不换同义原子命令或其他 ID 类型试错；
+- 部分成功：保留 completed/failed/unknown 明细，不表述为完整成功。

package/skills/dws/dingtalk-aitable/references/field-rules.md

@@ -0,0 +1,17 @@
+# Field 兼容规则终点
+
+这是保留给 Mono/Multi 历史内容映射的兼容文件，根 Skill 不主动路由到这里。普通字段操作可直接使用下列事实；AI、关联、lookup、filterUp 或复杂 config 应由根 Skill 直接选择唯一 `references/aitable/aitable-field.md`，不要从本文件继续跳转。
+
+| 用户意图 | 正确命令/边界 |
+|---|---|
+| 读取字段目录 | `dws aitable field list --base-id <B> --table-id <T>`；只取 fieldId/name/type |
+| 读取完整字段配置 | `dws aitable +field-get --base-id <B> --table-id <T>`；需要 config/options 时使用 |
+| 创建普通字段 | `dws aitable field create --base-id <B> --table-id <T> --name <N> --type <T> [--config <JSON>]` |
+| 批量创建字段 | `field create ... --fields '<JSON_ARRAY>'`；与 `--name/--type/--config/--ai-config` 互斥 |
+| 重命名/改配置 | `field update ... --field-id <F> --name <N>` 或 `--config <JSON>`；不能改字段类型 |
+| 删除字段 | `dws aitable +field-delete --base-id <B> --table-id <T> --field-id <F>`；主字段和最后一个字段不可删除 |
+| 调整列顺序 | 使用 `view update visible-fields`；没有 `field reorder` / `field move` |
+
+创建 Table 时第一个字段自动成为主字段，且必须是 text。singleSelect/multipleSelect 创建时在 `config.options` 中声明选项；记录写入使用已存在的选项名称。公式、引用、创建/修改人和创建/修改时间等只读字段不得写入。
+
+本文件是终点：不读取 cell-value、field-properties 或 Help。只有 Runtime 实际返回 `unknown command` / `unknown flag` 时才读取精确 leaf Help，并最多修正一次。

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

@@ -0,0 +1,17 @@
+# AITable 局部意图消歧
+
+| 用户表达 | 归属 | 理由 |
+|---|---|---|
+| AI 表格、多维表、Base、Table、字段、记录、视图、表单、仪表盘、自动化 | AITable | 操作 AITable 的业务数据与配置 |
+| 搜索 Base 候选、按关键词找 Base、检查某 Base 是否存在 | AITable | 直接使用 `+base-search --query`；即使关键词像人名，只要对象是 Base，也不得改走 `aisearch person` |
+| 表格链接，需要读取记录 | AITable | 先用 `+url-resolve` 取稳定 ID，再用 `+record-query` |
+| 只有 Base/Table 名称，需要读取记录 | AITable | 先用 `+resolve-base` / `+resolve-table` 唯一解析，再查询记录 |
+| 只复制 Base 结构、删除整个 Base | AITable | 复制到已知文档文件夹用 `+base-copy --target-folder-id ... --only-struct`；删除用真实 baseId。不要 Drive 完整复制后逐表删数据 |
+| Base 整体移动到普通文件夹、外层存储重命名 | Drive | 这是 Base 作为单个存储节点的外层位置/名称动作 |
+| Base 内 Table、Dashboard、Section 的复制/移动/重命名/删除 | AITable | 这些是 Base 内 nsheet/业务结构，不是独立 Drive dentry |
+| Base 角色、高级权限 | AITable | `+role-*` / `+advperm-*`；仅普通文件 ACL 才走 Drive |
+| 记录主键文档正文 | Doc | AITable 只取/建关联，正文由 Doc 处理 |
+| Excel 式单元格、区域、工作表、公式 | Sheet（dingtalk-misc） | 二维电子表格，不是多维表记录模型 |
+| CSV/JSON 数据进入现有 AI 表格 | AITable import 或 record create | 需要保留导入任务语义时用 import；已映射字段时直接写记录 |
+
+若链接类型不明确，先做 URL 类型预检；不要仅凭 URL 文本猜产品。明确是 AI 表格后才加载本 Skill。

package/skills/dws/dingtalk-aitable/references/recipes/conventions.md

@@ -0,0 +1,44 @@
+# 业务域通用规范
+
+> 仅服务本 skill 已迁入的行动指南。安全门控、危险操作确认、`--format json` 等已在本 skill 的 `SKILL.md` 中定义，此处不重复。
+
+## 批量查询规范
+
+| # | 规范 |
+|---|------|
+| 1 | **并行查详情**：拿到多个 ID 后，用 `&` 合并到同一条 Shell 命令并行执行 + `wait`，**严禁逐条串行** |
+| 2 | **翻页**：分页接口须拉全直至无更多 |
+| 3 | **优先批量 API**：有批量接口则用批量；无则按 #1 并行 |
+| 4 | **群消息**：必须先 `chat search --query` 得 `openConversationId`，再 `chat message list --group <openConversationId> --time "<yyyy-MM-dd HH:mm:ss>" --direction older`；多群同条命令并行 |
+| 5 | **列表少轮次**：带条件搜索/列表 → 一次采全详情；**禁止**无新参数时重复同一 `list` / `search` |
+
+## 多源并行采集（公共模式）
+
+> recipe 引用方式：`按「多源并行采集」执行（关键词=<X>，时间=<Y>至<Z>）`。
+
+- 同条 Shell：`&` 并行 + `wait`；分页须采全。
+- 只保留与主题相关的数据，无关丢弃。
+- 有批量详情接口优先；否则并行拉详情（见上表 #1）。
+- 具体采哪些产品列表由对应 **行动指南 recipe** 与当前产品参考决定；不要引入本文档未覆盖的产品路线。
+
+## 字段术语与 ID 传递
+
+> list 返回 JSON 后，必须提取下表字段传给后续命令。**禁止用其他字段替代。**
+
+| 字段 | 来源 | 传递给 |
+|------|------|--------|
+| `taskUuid` | `minutes list` | `minutes get summary/info/batch --id(s)` |
+| `userId` | `aisearch person` / `contact user search` / `contact dept list-members` | `contact user get --ids`、`todo --executors`、`calendar --users` |
+| `deptId` | `contact dept search` | `contact dept list-members --ids <deptId1,deptId2...>`；多子部门时对每个子部门分别 `dept search` 取 id |
+| `nodeId` | `drive search` / `wiki node search` | `doc read/update --node`、`drive copy/move/rename/delete --node` |
+| `nodeId` | `wiki node list` 中的 folder 类型节点 / `wiki node create --type folder` | `wiki node list --folder`、`wiki node create --folder`、`drive upload --folder`、`drive copy/move --folder` |
+| `eventId` | `calendar event list` | `calendar event get/update --id` |
+| `processInstanceId` | `oa approval list-*` | `oa approval detail/approve --instance-id` |
+| `openConversationId` | `chat search` | `chat message list/send --group` |
+| `todoTaskId` | `todo task list` | `todo task update/done --task-id` |
+| `reportId` | `report inbox list` / `report outbox list` | `report entry get/stats --report-id` |
+| `baseId` / `tableId` | `aitable base search` | `aitable record query --base-id --table-id` |
+| `dentryUuid` | `drive list` / `drive mkdir` | `drive info/download/copy/move/rename/delete --node`、`drive list/mkdir/upload/copy/move --folder` |
+| `dentryId` | `drive info` 的数字字段 | 仅用于 `chat message send --dentry-id` |
+
+**ID 边界硬约束**：`dentryId` 通常是纯数字，只表示聊天文件消息需要的钉盘条目数字 ID；它不是父目录 ID。遇到 `drive --node/--folder`、`doc --node`、`wiki node --folder` 时，只能使用 `dentryUuid` / `nodeId` / 文档 URL。若当前上下文只有数字型 `dentryId`，必须先重新 `drive list` / `drive search` / `wiki node list` 获取正确 ID，不能把该数字直接代入后续命令。

package/skills/dws/dingtalk-aitable/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 实际类型可能不一致（如说"文档"但实际是表格）

package/skills/dws/dingtalk-aitable/scripts/aitable_export_via_task.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""
+通过 MCP 导出任务（export_data）导出 AI 表格，并可自动下载文件。
+
+与普通命令的区别：
+- 自动处理 taskId 轮询（直到拿到 downloadUrl 或达到轮询上限）。
+- 自动保存导出文件到本地（可选 --output）。
+
+用法:
+    python scripts/aitable_export_via_task.py <baseId> --scope all
+    python scripts/aitable_export_via_task.py <baseId> --scope table --table-id <tableId>
+    python scripts/aitable_export_via_task.py <baseId> --scope view --table-id <tableId> --view-id <viewId>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+RESOURCE_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]{8,128}$")
+ALLOWED_FORMATS = {"excel", "attachment", "excel_and_attachment", "excel_with_inline_images"}
+
+
+def validate_resource_id(resource_id: str) -> bool:
+    return bool(resource_id and RESOURCE_ID_PATTERN.match(resource_id.strip()))
+
+
+def run_dws(dws_bin: str, args: list[str], timeout_sec: int = 120) -> Tuple[int, str, str]:
+    cmd = [dws_bin] + args
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout_sec)
+        return result.returncode, result.stdout.strip(), result.stderr.strip()
+    except subprocess.TimeoutExpired:
+        return 124, "", f"dws command timeout after {timeout_sec}s"
+    except FileNotFoundError:
+        return 127, "", f"dws binary not found: {dws_bin}"
+
+
+def parse_json_output(raw: str) -> Optional[Dict[str, Any]]:
+    try:
+        obj = json.loads(raw)
+        return obj if isinstance(obj, dict) else None
+    except json.JSONDecodeError:
+        return None
+
+
+def normalize_download_url(url: str) -> str:
+    if url.startswith("http://") or url.startswith("https://"):
+        return url
+    return f"https://{url}"
+
+
+def download_file(url: str, output_path: Path) -> Tuple[bool, str]:
+    req = Request(url, method="GET")
+    try:
+        with urlopen(req, timeout=180) as resp:
+            if resp.status != 200:
+                return False, f"download http status: {resp.status}"
+            output_path.write_bytes(resp.read())
+            return True, ""
+    except HTTPError as e:
+        body = e.read().decode("utf-8", "ignore")
+        return False, f"HTTP {e.code}: {body[:300]}"
+    except URLError as e:
+        return False, f"URL error: {e.reason}"
+
+
+def fail(msg: str, code: int = 1) -> None:
+    print(f"错误：{msg}", file=sys.stderr)
+    sys.exit(code)
+
+
+def build_start_args(args: argparse.Namespace) -> list[str]:
+    cmd = [
+        "aitable",
+        "export",
+        "data",
+        "--base-id",
+        args.base_id,
+        "--scope",
+        args.scope,
+        "--format",
+        args.export_format,
+        "--timeout-ms",
+        str(args.timeout_ms),
+    ]
+    if args.table_id:
+        cmd.extend(["--table-id", args.table_id])
+    if args.view_id:
+        cmd.extend(["--view-id", args.view_id])
+    return cmd
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="通过 MCP 导出任务导出 AI 表格")
+    parser.add_argument("base_id", help="目标 AI 表格 baseId")
+    parser.add_argument("--scope", choices=["all", "table", "view"], required=True, help="导出范围")
+    parser.add_argument("--table-id", help="scope=table/view 时必填")
+    parser.add_argument("--view-id", help="scope=view 时必填")
+    parser.add_argument("--export-format", default="excel", choices=sorted(ALLOWED_FORMATS), help="导出格式")
+    parser.add_argument("--timeout-ms", type=int, default=1000, help="单次等待毫秒数，默认 1000")
+    parser.add_argument("--poll-timeout-ms", type=int, default=3000, help="轮询等待毫秒数，默认 3000")
+    parser.add_argument("--max-polls", type=int, default=10, help="最大轮询次数，默认 10")
+    parser.add_argument("--output", help="本地保存路径（不传则按 fileName 保存到当前目录）")
+    parser.add_argument("--dws", default="dws", help="dws 可执行文件路径，默认 dws")
+    parser.add_argument("--no-download", action="store_true", help="仅返回 downloadUrl，不下载文件")
+    args = parser.parse_args()
+
+    if not validate_resource_id(args.base_id):
+        fail("无效的 baseId 格式")
+    if args.scope in ("table", "view") and not args.table_id:
+        fail("scope=table/view 时必须传 --table-id")
+    if args.scope == "view" and not args.view_id:
+        fail("scope=view 时必须传 --view-id")
+
+    print("[1/2] start export task", file=sys.stderr)
+    rc, out, err = run_dws(args.dws, build_start_args(args), timeout_sec=120)
+    if rc != 0:
+        fail(f"export_data 启动失败: {err or out}", rc)
+    obj = parse_json_output(out)
+    if not obj:
+        fail(f"export_data 返回非 JSON: {out[:300]}")
+
+    data = obj.get("data", {}) or {}
+    status = obj.get("status")
+    if status == "error":
+        fail(f"export_data 返回失败: {json.dumps(obj, ensure_ascii=False)}")
+
+    download_url = data.get("downloadUrl")
+    task_id = data.get("taskId")
+    file_name = data.get("fileName") or "export_result.bin"
+
+    polls = 0
+    while not download_url and task_id and polls < args.max_polls:
+        polls += 1
+        print(f"[2/2] polling task ({polls}/{args.max_polls})", file=sys.stderr)
+        rc2, out2, err2 = run_dws(
+            args.dws,
+            [
+                "aitable",
+                "export",
+                "data",
+                "--base-id",
+                args.base_id,
+                "--task-id",
+                task_id,
+                "--timeout-ms",
+                str(args.poll_timeout_ms),
+            ],
+            timeout_sec=max(120, int(args.poll_timeout_ms / 1000) + 60),
+        )
+        if rc2 != 0:
+            fail(f"export_data 轮询失败: {err2 or out2}", rc2)
+        obj2 = parse_json_output(out2)
+        if not obj2:
+            fail(f"export_data 轮询返回非 JSON: {out2[:300]}")
+        if obj2.get("status") == "error":
+            fail(f"export_data 轮询返回失败: {json.dumps(obj2, ensure_ascii=False)}")
+        d2 = obj2.get("data", {}) or {}
+        download_url = d2.get("downloadUrl") or download_url
+        file_name = d2.get("fileName") or file_name
+        task_id = d2.get("taskId") or task_id
+        if not download_url:
+            time.sleep(0.2)
+
+    result: Dict[str, Any] = {
+        "baseId": args.base_id,
+        "scope": args.scope,
+        "exportFormat": args.export_format,
+        "taskId": task_id,
+        "fileName": file_name,
+        "downloadUrl": download_url,
+        "polledTimes": polls,
+    }
+
+    if not download_url:
+        result["status"] = "pending"
+        result["summary"] = "导出任务仍在处理中，请继续用 taskId 轮询。"
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        sys.exit(3)
+
+    if args.no_download:
+        result["status"] = "success"
+        result["summary"] = "导出完成（未下载文件）。"
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return
+
+    norm_url = normalize_download_url(download_url)
+    output_path = Path(args.output).expanduser().resolve() if args.output else Path.cwd() / file_name
+    ok, dl_err = download_file(norm_url, output_path)
+    if not ok:
+        fail(f"downloadUrl 下载失败: {dl_err}")
+
+    result["status"] = "success"
+    result["summary"] = "导出完成并已下载。"
+    result["savedPath"] = str(output_path)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()