dsh-crwu-workbench 0.0.10

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

@@ -0,0 +1,139 @@
+---
+name: dingtalk-aitable
+description: 钉钉 AI 表格（多维表）。Use when 用户说 AI表格/多维表/数据表/base/table/建表/查记录/写数据/字段/记录增删改查/筛选/排序/公式/模板搜索/批量导入CSV或JSON/导出/仪表盘/图表/上传附件到表格/按字段类型建表/数据源/创建数据源/更新数据源配置/触发数据源同步/按任务 ID 查询同步状态/获取数据源配置/列出数据源可用来源/获取数据源可同步字段/审批数据同步。不做电子表格单元格读写（走 dingtalk-misc）、文档编辑（走 dingtalk-doc）；听记待办入表先用 dingtalk-minutes 提取，再由本 skill 写入。命令前缀：dws aitable。
+metadata:
+  cli_version: ">=0.2.14"
+  category: product
+  requires:
+    bins:
+      - dws
+---
+
+# 钉钉 AI 表格 Skill
+
+<!-- DWS_RUNTIME_CONTRACT_START -->
+## 最小 DWS 执行契约
+
+- 钉钉业务操作只通过 `dws` CLI；本 Skill 明确发布的脚本可编排 `dws` 并完成预签名文件上传。结构化读取使用 `--format json`，按真实返回判断结果。
+- 已知 leaf 直接执行。只有参数或安全语义不确定时，最多读取一次 `dws schema --cli-path "aitable <leaf>" --compact --format json`；仅当该 compact leaf Schema 与 Cobra 实际不一致时，才读取同一 leaf 的 `dws aitable <leaf> --help`。禁止通过父级 Help、产品 Help 或完整 Catalog 探索命令。
+- 不猜命令、flag、字段、ID、账号或时间。后续 ID 必须来自真实返回；零命中、多候选或类型不明时停止并消歧。
+- 解析目标、读取上下文和最终执行必须使用同一 profile；不得跨组织复用 userId、openDingTalkId 或 openConversationId。多账号组织只使用明确的 `isOrgCurrent=true` 默认账号；没有默认账号时要求用户指定，禁止选择第一项、最近登录或最近使用账号。
+- 不输出或记录 token、refresh token、appSecret、webhook token 等凭据；宿主已注入认证时不要索要凭据。
+- 写操作必须符合用户明确意图。是否需要确认以最终 Runtime gate 和 Schema 为准；本轮用户已明确要求执行、目标与影响无歧义的非破坏性写操作时，该明确指令就是本次确认，首次调用直接携带 Runtime 所需的 `--yes`，不先制造 `confirmation_required`。删除、停用自动化等破坏性或高风险动作仍须先说明对象、动作与影响并取得独立确认。
+- 写后按任务结果契约验证；不能仅凭退出码宣称成功。部分结果、未知投递状态和失败项必须如实保留。
+- 时间戳面向用户展示时转换为带时区的可读时间；默认使用当前会话时区，必要时同时保留原值。
+- 遇到认证、权限、profile、confirmation 或未知错误时，只加载 `dingtalk-shared` 中对应 reference；不要连续猜测替代命令。
+<!-- DWS_RUNTIME_CONTRACT_END -->
+
+<!-- VISIBLE_SHORTCUTS_START -->
+## Shortcut 发现（按需）
+
+`aitable` 当前有 100 条公开 shortcut，完整清单保留在 Runtime Catalog 与 Schema，不在高频产品根 Skill 中重复展开。已知 leaf 直接执行。只有参数不确定时，最多读取一次 `dws schema --cli-path "aitable <leaf>" --compact --format json`；仅当该 compact leaf Schema 与 Cobra 实际不一致时，才读取同一 leaf 的 `dws aitable <leaf> --help`。禁止用父级 Help、产品 Help 或完整 Catalog 探索命令；一个 Case 一旦读取 Reference，就不再读取 Help 或第二个 Reference。
+
+仅当根路由、精确 task reference 和 `references/aitable.md` 的低频原子索引都无法定位能力时，才执行 `dws shortcut list --service aitable --format json` 做最终回退；不要为已知意图加载完整 Shortcut Catalog 或产品级 Schema。
+<!-- VISIBLE_SHORTCUTS_END -->
+
+## Golden Route（高频复合任务）
+
+已有 ID 直接使用；完整 URL 先解析；名称先唯一解析为稳定 ID。零命中或多候选时停止，不默认选第一项。
+
+| 用户意图 | 唯一推荐入口 | 关键边界 |
+|---|---|---|
+| 从 URL 解析稳定 ID | `dws aitable +url-resolve --url <URL>` | 只解析 URL 中已有的 baseId/tableId/viewId/recordId，不做远端名称搜索 |
+| 按名称唯一定位并操作 Base/Table | `dws aitable +resolve-base --name <名称>` → `dws aitable +resolve-table --base <ID> --name <表名>` | 默认精确匹配；只有用户明确接受模糊匹配时才加 `--fuzzy` |
+| 搜索 Base 候选或检查是否存在 | `dws aitable +base-search --query <关键词>` | 用户说“搜索/找一下/候选/如果没有就创建”时直接走本入口，不先调用 `+resolve-base`；返回 `hasMore/nextCursor`，仅 `hasMore=true` 时续页；AITable Base 名称不得路由到 `dws aisearch person` |
+| 浏览 Base 下的数据表 | `dws aitable +list-tables --base <ID>` | 只返回 tableId/tableName，不加载字段 |
+| 新建 Base 与整套表字段 | `dws aitable +base-bootstrap --name <名称> --tables '[{"name":"<表名>","fields":[{"fieldName":"<字段名>","type":"text"}]}]'` | 表对象键必须是 `name`，不是 `tableName`；字段使用 `fieldName/type/config`；参数已足够时直接执行 |
+| 复制 Base 到文档目录 | `dws aitable +base-copy --base-id <B> --target-folder-id <FOLDER_NODE_ID> [--only-struct] [--new-name <名称>]`；只有 URL 时先用 `dws doc info --node <URL> --format json` 解析 `nodeId`，然后仍传 `--target-folder-id <NODE_ID>` | `target-folder-id` 必须是文件夹 `nodeId`，不接受 URL、路径、纯数字 dentryId 或 rootFolderId；若 Runtime 返回 `target_not_supported/retryable=false`，立即报告，不查 Help、不换 ID、不建测试文件夹，也不手工降级复制 |
+| 已有 Base 新建一张表与字段 | `dws aitable +table-bootstrap --base-id <ID> --name <表名> --fields '<JSON数组>'` | 字段使用 `fieldName/type/config`；自动按 15 个字段分片并读回验证 |
+| 读取字段目录或完整配置 | `dws aitable field list --base-id <B> --table-id <T>` / `dws aitable +field-get --base-id <B> --table-id <T>` | 只需 fieldId/name/type 用 `field list`；需要 config 用 `+field-get`；不存在 `+field-list` 或 `+list-fields` |
+| 查询记录、记录筛选/排序或字段投影 | `dws aitable +record-query --base-id <ID> --table-id <ID> [--record-ids <IDs>] [--field-ids <IDs>] [--filters <JSON>] [--sort <JSON>] [--query <关键词>]` | 用户要求“只返回/仅查看”指定字段时必须传对应 `--field-ids`，不能只在最终文本删列；明确要求全量时改用原子 `record query --all --page-limit <N>` |
+| 新增单条或批量记录 | `dws aitable record create --base-id <ID> --table-id <ID> --records <JSON>` | 当前无 `+record-create`；写前取字段定义，写后按新 ID 回读 |
+| 更新已知 recordId | `dws aitable +record-update --base-id <ID> --table-id <ID> --records <JSON>` | 自动分片并读回；只传需修改字段 |
+| 查询一条记录的变更历史 | `dws aitable +record-history-list --base-id <ID> --table-id <ID> --record-id <ID>` | 已知 recordId 时直接执行，不探测 Help、Catalog 或全量 Schema |
+| 按业务键同步或按条件批改 | 唯一键用 `dws aitable +record-upsert-by-key ...`；有界批改用 `dws aitable +record-bulk-patch ... --max-matches <N>` | upsert 仅允许 0 条创建、1 条更新；批改必须有 query/filters/record-ids 边界。普通 update/upsert 直接执行；只有历史、分享、删除恢复、空行或特殊字段值才读 [record-ops](references/aitable-record-ops.md)；明确 AND/OR、日期或比较操作符只读 [filter-sort](references/aitable/aitable-filter-sort.md) |
+| 生成记录分享链接并发送给联系人 | `dws aitable +record-share-links --base <B> --table <T> --record-ids <IDs>` → `dws chat +dm --to <姓名> --text <完整链接文本>` | AITable 只生成链接；用户要求“发送”时还必须完成真实发送，不能停在联系人解析 |
+| 创建或复制视图 | 创建用 `dws aitable view create --base-id <B> --table-id <T> --view-type <Grid|FormDesigner|Gantt|Calendar|Kanban|Gallery> [--name <名称>]`；复制用 `dws aitable +view-duplicate --base-id <B> --table-id <T> --view-id <V> [--new-name <名称>]` | 创建和复制直接执行；需要配置时按下方“按需加载”选择一个 View Reference |
+| 创建并验证 Dashboard，按需创建 Chart | `dws aitable dashboard create --base-id <B> --name <名称>` → `dws aitable +dashboard-get --base-id <B> --dashboard-id <D>`；需要 Chart 时按下方“按需加载”处理 | 只使用创建返回的真实 dashboardId；失败时不要猜同义命令或更换 dashboardId |
+| Base 内创建 Section 并移动节点 | `dws aitable +section-create --base-id <B> --name <名称>` → `dws aitable +section-move-node --base-id <B> --node-id <N> --new-parent-section-id <S>` → `dws aitable +section-list-nodes --base-id <B>` | Table、Dashboard、Section 都是 AITable 的 nsheet 节点；禁止改走 Wiki/Drive 文件夹或移动命令 |
+| 将本地 CSV/XLSX/XLS 导入新表 | `python scripts/aitable_import_via_task.py <BASE_ID> <FILE_PATH>` | 首选本 Skill 自带脚本，一次完成申请凭证、空 Content-Type PUT 和 `import data`；不要猜 `+import-csv` 或给 `import upload` 传 `--file` |
+| 接入外部数据源（审批等） | `dws aitable +datasource-list-sources --base-id <ID> --datasource-type OA` → 解析 result 构造 sourceConfig → `dws aitable +datasource-create --base-id <ID> --datasource-type OA --source-config '<JSON>'` | 当前仅支持 OA 审批；processCode/name/iconUrl/url 从 list-sources 原样透传，创建后用 `+datasource-sync-status` 查同步结果 |
+
+### 简单 leaf
+
+意图明确时直接使用；参数不确定才读 leaf Schema：
+
+| 用户意图 | 入口 |
+|---|---|
+| 查看 / 改名 / 删除 Base | `+base-get` / `+base-update` / `+base-delete` |
+| 搜索模板 | `+template-search` |
+| 查看 / 跨 Base 复制 / 改名 / 删除 Table | `+table-get` / `+table-copy` / `+table-update` / `+table-delete` |
+| 创建 / 更新 / 删除普通字段 | `field create` / `field update` / `field delete` |
+| 查看 / 删除 View | `+view-get` / `+view-delete` |
+| 查看 / 改名 / 删除 Dashboard | `+dashboard-get` / `+dashboard-update` / `+dashboard-delete` |
+
+命令接在 `dws aitable` 后；资源 ID 使用 `--base-id/--table-id/--field-id/--view-id/--dashboard-id`，改名使用 `--name`。`+table-copy` 参数不规则，执行前只读其 leaf Schema。不读操作 Reference、Help 或产品 Catalog。
+
+数据源查看来源用 `+datasource-list-sources`，获取字段用 `+datasource-get-fields`，创建、更新、同步、查状态和查配置用 `+datasource-create` / `+datasource-update` / `+datasource-sync` / `+datasource-sync-status` / `+datasource-get-config`。
+
+## 执行约束
+
+- 记录 filter/sort 缺 fieldId 时才读取字段目录。
+- record filter/sort 与 view filter/sort/group 的协议和 Reference 互斥。普通 record query/create/update/upsert 直达；只有历史、分享、删除恢复、空行或特殊字段值读 `record-ops`。
+- 普通字段 type 使用 `text/number/date/singleSelect/currency`；`singleSelect` 的 config 为 `{"options":[{"name":"<选项>"}]}`，人民币 `currency` 为 `{"currencyType":"CNY","formatter":"FLOAT_2"}`。
+- 仅任务包含 4 个及以上独立业务步骤或用户明确要求时使用 TodoWrite；不按单条 CLI 拆步，只在阶段切换时更新。
+- 多个资源名要求同一时间戳时，只取一次并复用。
+- 复用 JSON 已返回字段，不以 `--verbose/raw/pretty` 重复请求。
+- 数据源创建前必须先 `+datasource-list-sources` 获取 processCode 等透传字段，不凭记忆构造 sourceConfig。
+
+## 记录稳定约束
+
+- 记录 `cells` 使用当前 fieldId，按真实字段类型写值，只读字段不得写入。
+- 新增或更新只使用真实返回的 ID 回读；写入效果未知时回读，不重放成功批次。
+- 全量查询检查 `hasMore`，批量写检查最终状态；分页未结束或 `partial_success` 都不得声称完整完成。
+
+## 安全边界
+
+- 删除不可逆，按 Runtime confirmation 核对真实目标；`base list` 只是最近访问。字段零/多候选、类型不明时停止；多批写保留已完成批次和续跑位置。
+- 数据源 `+datasource-create` / `+datasource-update` 会触发真实数据同步；执行前确认目标 Base 和 sourceConfig。`+datasource-sync` 单次最多 5 张表。
+
+## 按需加载（复杂 JSON 与恢复语义）
+
+Golden/次级直达覆盖时不读 Reference；否则按最终专有能力读取一个精确 Reference。读取后直接执行，不再读取其他 AITable Reference。
+
+| 触发条件 | Reference |
+|---|---|
+| `+record-query`、upsert、bulk patch 的记录 filters/sort/date/AND/OR/比较操作符 | [filter-sort](references/aitable/aitable-filter-sort.md) |
+| 记录历史、分享、删除恢复、空行或特殊字段值 | [record-ops](references/aitable-record-ops.md) |
+| 记录统计、分组聚合或去重率 | [record-stats](references/aitable/aitable-record-stats.md) |
+| 查询记录的主键文档，或为记录创建主键文档 | 首次建表前读取 [primary-doc](references/aitable/aitable-primary-doc.md)；普通 Base/Table/字段/记录创建与导入不读取 |
+| AI 字段、关联字段、lookup/filterUp 或其他复杂 config | [field](references/aitable/aitable-field.md) |
+| formula 字段或公式语法 | [formula-guide](references/aitable/aitable-formula-guide.md) |
+| 导入导出任务恢复 | [export-import](references/aitable/aitable-export-import.md) |
+| 视图列顺序、移到/放到/固定在最左、filter、sort、group（不得转读记录 `filter-sort`） | [view-config](references/aitable/aitable-view-config.md) |
+| Kanban/Gallery 的 card、Gantt 的 timebar、Grid 的 aggregate | [view-types](references/aitable/aitable-view-types.md) |
+| 视图锁定、明确冻结前 N 列、行高或填色 | [view-extras](references/aitable/aitable-view-extras.md) |
+| Base 内 Section/节点移动或清理 | [section](references/aitable-section.md) |
+| Chart 创建或更新所需 config，或 Dashboard 完整 config/arrange；普通 Dashboard CRUD 走上方直达 | [dashboard-chart](references/aitable/aitable-dashboard-chart.md) |
+| 表单创建、题目或分享 | [form](references/aitable/aitable-form.md) |
+| 附件上传或移除 | [attachment](references/aitable/aitable-attachment.md) |
+| 自动化工作流 | [workflow](references/aitable/aitable-workflow.md) |
+| 普通角色或高级权限 | [advperm](references/aitable/aitable-advperm.md) |
+| 数据源接入、同步管理、sourceConfig 构造或审批数据同步 | [datasource](references/aitable/aitable-datasource.md) |
+| 产品边界不明确 | [intent-guide](references/intent-guide.md) |
+| 只有上述 Reference 仍无法定位的低频原子能力 | [aitable.md](references/aitable.md) 的对应章节 |
+
+不要预加载这些 Reference。
+
+## 错误最短路径
+
+1. 零/多候选、字段歧义或分页不完整：停止并返回证据；需要后续页时只透传真实 `nextCursor`。
+2. 类型错误只复核目标字段，不删字段或丢输入；`partial_success` 从 checkpoint 续跑，未知写入先回读。
+3. 错误提供 `actions` / `available_flags` 时只按其中的 `next_command` 修正一次；`retryable=false` 或目标 ID 类型不符时停止。
+4. 数据源同步 `errorCode=4014` 表示同步运行中重复触发，可稍后重试；非数据源表触发同步前先用 `+base-get` 确认 `sync=true`。
+
+## 跨产品边界
+
+- Excel 式单元格、区域和公式操作 → `dingtalk-misc` 的 Sheet。
+- Base 作为整体在普通文件夹间移动或做外层存储重命名 → Drive；Base 结构复制/删除，以及 Base 内 Table、Dashboard、Section 的创建、复制、移动、重命名、删除 → AITable。
+- 记录主键文档正文 → 取得真实 nodeId 后切 `dingtalk-doc`。

package/skills/dws/dingtalk-aitable/references/06-data-analytics.md

@@ -0,0 +1,11 @@
+# 数据分析
+
+> 本场景所有 recipe 均为 full。
+
+| Recipe | 行动指南（固定路线） |
+|--------|-------------------|
+| read-aitable | 1. `aitable base search --query "<表格名>"` → 取 `baseId`/`tableId`<br>2. `aitable field get --base-id <baseId> --table-id <tableId>` → 取 `fieldId`<br>3. `aitable record query --base-id <baseId> --table-id <tableId>` → 取记录（分页）<br>　　需要筛选时 `--filters` 格式见 [aitable-filter-sort.md](./aitable/aitable-filter-sort.md)，根节点必须是 `{"operator":"and\|or","operands":[...]}`<br>4. 总结数据 |
+| generate-data-report | 1. 同 read-aitable 步骤 1-3<br>2. 按[「多源并行采集」](recipes/conventions.md#多源并行采集公共模式)执行 → 补充背景<br>3. `doc create --name "<报告名>" --content "<分析报告>"` |
+| create-aitable-record | **批量导入优先**：`python scripts/import_records.py <baseId> <tableId> data.csv\|data.json [batch_size]`（自动分批创建）<br>单条/少量：1. `aitable base search --query "<表格名>"` → 取 `baseId`/`tableId`<br>2. `aitable field get --base-id <baseId> --table-id <tableId>` → 取 `fieldId` 与类型<br>3. `aitable record create --base-id <baseId> --table-id <tableId> --records '[{"cells":{"<fieldId>":"值"}}]'` |
+| update-aitable-record | 1. `aitable base search --query "<表格名>"` → 取 `baseId`/`tableId`<br>2. `aitable record query --base-id <baseId> --table-id <tableId>` → 取 `recordId`，**先展示让用户确认**<br>3. `aitable record update --base-id <baseId> --table-id <tableId> --records '[{"recordId":"<recordId>","cells":{...}}]'` |
+| search-aitable-template | 1. `aitable template search --query "<关键词>"` → 取 `templateId`<br>2. 用户选定<br>3. `aitable base create --name "<表格名>" --template-id <templateId>` → 取 `baseId` |

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

@@ -0,0 +1,251 @@
+# advperm — 高级权限管理
+
+控制 Base 的高级权限总开关，并管理自定义角色（增删改查 + 子角色权限规则）。
+适用场景："如何控制谁能看/改 Base 数据"、"开启/关闭高级权限"、"新建/修改/删除角色"、"按字段或行配置权限"。
+
+## 命令一览
+
+| 命令 | 用途 |
+|------|------|
+| `advperm enable` | 开启 Base 高级权限总开关 |
+| `advperm disable` | 关闭 Base 高级权限总开关（高危） |
+| `advperm role-list` | 列出 Base 下全部角色 |
+| `advperm role-get` | 获取单角色完整配置 |
+| `advperm role-create` | 创建自定义角色 |
+| `advperm role-update` | 增量更新自定义角色（PATCH 语义） |
+| `advperm role-delete` | 删除自定义角色（不可逆） |
+
+> 所有子命令的 `--base-id` 必填，可用隐藏别名 `--base`。
+
+## 命令详情
+
+### advperm enable — 开启高级权限
+
+```bash
+dws aitable advperm enable --base-id BASE_ID --format json
+```
+
+返回 `{baseId, enabled: true}`。
+
+只有开启后角色配置才会真正限制成员的可访问范围；关闭状态下角色配置仍可读但不生效。
+
+### advperm disable — 关闭高级权限（高危）
+
+```bash
+dws aitable advperm disable --base-id BASE_ID --yes --format json
+```
+
+返回 `{baseId, enabled: false}`。关闭后所有角色配置即刻失效，全员回退到默认权限。涉及多人协作或敏感数据务必和用户二次确认，建议先 `role-list` 留底。
+
+### advperm role-list — 列出全部角色
+
+```bash
+dws aitable advperm role-list --base-id BASE_ID --format json
+```
+
+返回结构：
+
+```json
+{
+  "data": {
+    "enabled": true,
+    "defaultRole": { "mode": 0 },
+    "roles": [
+      {
+        "roleId": "10685308981",
+        "name": "可查看角色",
+        "roleType": "custom",
+        "system": false,
+        "subRoles": [
+          {
+            "authLevel": "read",
+            "targetId": "HMEaRQ4",
+            "targetType": "sheet",
+            "config": { "actions": 268435455 },
+            "display": {
+              "authLevelLabel": "仅查看",
+              "targetTypeLabel": "数据表",
+              "permissionScopeNote": "...",
+              "actionsLabels": ["新增视图", "删除视图", "修改视图"],
+              "actionsNote": "..."
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+关键字段：
+
+- `roleType`：`custom`（自定义） / `system_editor` / `system_reader` / `5000`（owner） / `4000`（manager）。
+- `system`：boolean，true 表示系统角色（不可删）。
+- `subRoles[].display.*`：服务端返回的人类可读标签，可直接拼接给用户阅读，无需自行映射枚举。
+- 不返回角色成员列表；如需"成员-角色"映射请去 AI 表格 Web 端。
+- 新建 Base 默认 `enabled=false`，开启后只有 `owner` / `manager` 两个 meta 角色；`system_editor` / `system_reader` 需要在 Web UI 给成员授权"可编辑/可查看"后才会被服务端自动生成。
+
+`role-list` / `role-get` 不需要管理员权限，普通成员也可读。
+
+### advperm role-get — 获取单角色配置
+
+```bash
+dws aitable advperm role-get --base-id BASE_ID --role-id ROLE_ID --format json
+```
+
+返回结构同 `role-list` 中单个 role 对象（含完整 `subRoles[].config` 字段/行级规则与 `display.*` 标签）。
+
+### advperm role-create — 创建自定义角色
+
+```bash
+# 仅指定 name，子角色由服务端按默认（none）填充
+dws aitable advperm role-create --base-id BASE_ID --name "市场可读" --format json
+
+# 创建时即指定 sub-roles（推荐——避免再走一次 role-update）
+dws aitable advperm role-create --base-id BASE_ID --name "市场可读" \
+  --sub-roles '[{"targetId":"<sheetId>","targetType":"sheet","authLevel":"read"}]' --format json
+```
+
+| flag | 必填 | 说明 |
+|------|:---:|------|
+| `--name` | ✅ | 角色名称 |
+| `--role-type` | | 角色类型字符串（留空由服务端决定默认值，如 `custom`） |
+| `--flow-type` | | 流程类型字符串（按业务需要） |
+| `--sub-roles` | | JSON 数组：`[{targetId, targetType, authLevel, appId?, config?}]`，详见下方"sub-roles 子字段"段 |
+
+返回新建角色的完整配置（同 `role-get` 出参格式，含自动生成的 default subRoles）。
+系统角色无法通过本命令创建。
+
+### advperm role-update — 增量更新自定义角色（PATCH 语义）
+
+```bash
+# 只改名
+dws aitable advperm role-update --base-id BASE_ID --role-id ROLE_ID --name "新名字"
+
+# 只改 sheet 子角色 authLevel，name 不传保持不变
+dws aitable advperm role-update --base-id BASE_ID --role-id ROLE_ID \
+  --sub-roles '[{"targetId":"<sheetId>","targetType":"sheet","authLevel":"edit-own"}]'
+```
+
+| flag | 必填 | 说明 |
+|------|:---:|------|
+| `--role-id` | ✅ | 目标自定义角色 ID（数字 long 字符串） |
+| `--name` | | 新角色名称；不传不修改 |
+| `--role-type` / `--flow-type` | | 可选 |
+| `--sub-roles` | | JSON 数组，**PATCH 合并语义**：按 `(targetId, targetType)` 合并到现有 subRoles，入参中的 sub 整体替换该 sub，**入参未提及的 sub 保留不变**（无需先调 `role-get` 自行 merge） |
+
+**系统角色禁止更新**（包括 owner / manager / system_editor / system_reader）。
+
+### sub-roles 子字段
+
+每个 sub-role 描述「角色对某个权限目标的访问粒度」：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `targetId` | string | 目标资源 ID（数据表 → `tableId`；仪表盘 → `dashboardId`；应用 → `appId`） |
+| `targetType` | string | `sheet` / `dashboard` / `app` |
+| `authLevel` | string | `manage` / `edit-own` / `edit-custom-field` / `edit-field-range` / `read` / `none` |
+| `appId` | string（可选） | 仅 `targetType=app` 时使用 |
+| `config` | object（可选） | 字段/行级细化规则；含 `actions`（位图）/ `rows` / `cells`。结构与 `role-get` 出参 `subRoles[].config` 对齐 |
+
+### advperm role-delete — 删除自定义角色（不可逆）
+
+```bash
+dws aitable advperm role-delete --base-id BASE_ID --role-id ROLE_ID --yes --format json
+```
+
+要求同时满足：
+
+1. 该 Base 已开启高级权限（`role-list` 返回 `enabled=true`）。
+2. 当前 dws 登录用户是该 Base 的管理员/Owner。
+3. `--role-id` 是 `role-list` 返回的数字 long 字符串（如 `"10685308981"`），且对应角色 `system=false`。
+
+不可逆，删前先 `role-get` 留底。
+
+## 能力边界
+
+| 能力 | 状态 |
+|------|------|
+| 开/关高级权限 | ✅ 需管理员 |
+| 列出 / 读取角色 | ✅ 普通成员也可读 |
+| 创建自定义角色 | ✅ 需管理员 |
+| 增量修改角色（PATCH 语义，不清空未传字段） | ✅ 需管理员 |
+| 删除自定义角色 | ✅ 需管理员 |
+| 修改/删除系统角色 | ❌ 服务端禁止；只能在 AI 表格 Web 端操作 |
+| 角色 ↔ 成员绑定 | ❌ CLI 暂不支持，需在 AI 表格 Web 端 → Base 设置 → 高级权限 → 角色管理面板手动完成 |
+
+## 错误码速查
+
+| 场景 | code | type | message |
+|------|------|------|---------|
+| advperm 关闭时调用写接口（如 `role-delete` / `role-create` / `role-update`） | `ADVANCED_PERMISSION_DISABLED` | `USER_ERROR` | `Advanced permission is disabled for base <BASE>, please enable it via setAdvancedPermission before managing roles` |
+| 非管理员调用 `enable` / `disable` / `role-create` / `role-update` / `role-delete` | `401` | `AUTH_ERROR` | `the current user must be a manager (administrator) of this base to manage roles or advanced permission` |
+| 删除/更新系统角色（`system=true`） | `600` | `USER_ERROR` | `Illegal argument` |
+| 操作不存在的数字 roleId（get/update/delete） | `600` | `USER_ERROR` | `Illegal argument` |
+| 传非数字 roleId（如 `owner` / `manager`） | `INVALID_PARAMS` | `INPUT_ERROR` | `roleId is required` |
+| `role-create` 缺 `--name` | `INVALID_PARAMS` | `INPUT_ERROR` | `name is required` |
+| `--sub-roles` JSON 不是数组 / 解析失败 | （CLI 层拦截） | — | `--sub-roles 解析失败 ...` / `--sub-roles 必须是 JSON 数组` |
+| `--base-id` 无法解析 | `INVALID_BASE_ID` | `INPUT_ERROR` | `baseId cannot be resolved to docId` |
+
+> `600 / Illegal argument` 同时覆盖"操作系统角色"和"操作不存在 roleId"两种情况。拿到 `600` 时先 `role-list` 自查目标 roleId 是否存在、是否 `system=true`，再据此引导用户。
+
+## 典型工作流
+
+### 排查"成员看不到某些字段/记录"
+
+```bash
+dws aitable advperm role-list --base-id BASE_ID --format json
+# 若 enabled=false：高级权限未开，所有规则不生效，与用户确认是否需要 enable
+
+dws aitable advperm enable --base-id BASE_ID --format json
+dws aitable advperm role-list --base-id BASE_ID --format json
+# 看 roles[] 里有哪些自定义角色
+
+dws aitable advperm role-get --base-id BASE_ID --role-id ROLE_ID --format json
+# 检查 subRoles[].config 中的字段/行级权限规则
+```
+
+### 新建一个"市场可读"角色
+
+```bash
+# 1. 确保高级权限已开
+dws aitable advperm enable --base-id BASE_ID --format json
+
+# 2. 拿目标 sheet 的 tableId
+dws aitable table get --base-id BASE_ID --format json
+
+# 3. 创建角色 + 指定 sheet 子角色 authLevel=read
+dws aitable advperm role-create --base-id BASE_ID --name "市场可读" \
+  --sub-roles '[{"targetId":"<tableId>","targetType":"sheet","authLevel":"read"}]' \
+  --format json
+# → 返回新角色完整配置，含 roleId，记下后续 patch / delete 使用
+```
+
+### 升级角色权限（read → edit-own），保留其他配置
+
+```bash
+# 只传 sub-roles，name 等其他字段保持不变（PATCH 语义）
+dws aitable advperm role-update --base-id BASE_ID --role-id ROLE_ID \
+  --sub-roles '[{"targetId":"<tableId>","targetType":"sheet","authLevel":"edit-own"}]' \
+  --format json
+```
+
+### 改角色名（不影响权限规则）
+
+```bash
+dws aitable advperm role-update --base-id BASE_ID --role-id ROLE_ID --name "新名字"
+```
+
+### 清理废弃角色
+
+```bash
+dws aitable advperm role-list --base-id BASE_ID --format json
+dws aitable advperm role-delete --base-id BASE_ID --role-id ROLE_ID --yes --format json
+```
+
+### 关闭高级权限（恢复全员可见）
+
+```bash
+dws aitable advperm role-list --base-id BASE_ID --format json > /tmp/roles-backup.json
+dws aitable advperm disable --base-id BASE_ID --yes --format json
+```

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

@@ -0,0 +1,49 @@
+# attachment — 附件上传
+
+> **STOP — 不要使用钉盘 (drive) 上传！** 钉盘 fileId 无法写入 attachment 字段。必须使用以下流程。
+>
+> **STOP — 严禁在 record create/update 的 cells 里直接传图片 URL！** 直传 `{"url":"https://..."}` 会导致服务端同步下载图片，批量写入时触发 TIMEOUT_ERROR。正确做法：先 `attachment upload` 获取 `fileToken`，再用 `{"fileToken":"ft_xxx"}` 写入。
+
+## 准备附件上传
+
+```
+Usage:
+  dws aitable attachment upload [flags]
+Example:
+  dws aitable attachment upload --base-id <BASE_ID> --file-name report.xlsx --size 204800
+  dws aitable attachment upload --base-id <BASE_ID> --file-name photo.png --size 1024 --mime-type image/png
+Flags:
+      --base-id string     Base ID (必填)
+      --file-name string   文件名，必须含扩展名 (必填)
+      --size int           文件大小（字节），>0 (必填)
+      --mime-type string   MIME type（不传时根据扩展名推断）
+```
+
+## 附件上传完整流程（推荐：使用脚本，2 步完成）
+
+```bash
+# 步骤 1: 使用脚本一键上传（内部自动完成 prepare + PUT）
+python3 scripts/upload_attachment.py <BASE_ID> /path/to/report.pdf
+# 输出: { "fileToken": "ft_xxx", "fileName": "report.pdf", "size": 204800 }
+
+# 步骤 2: 在 record create/update 中使用 fileToken 写入
+dws aitable record create --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --records '[{"cells":{"fldAttachId":[{"fileToken":"ft_xxx"}]}}]' --format json
+```
+
+> `uploadUrl` 有时效性（`expiresAt`），脚本会自动在获取后立即上传。
+
+## 手动流程（不使用脚本）
+
+```bash
+# 1. 获取上传凭证
+dws aitable attachment upload --base-id <BASE_ID> --file-name report.pdf --size 204800 --format json
+# → 返回 uploadUrl、fileToken
+
+# 2. PUT 上传（Content-Type 必须是文件的具体 MIME type）
+curl -X PUT "<uploadUrl>" -H "Content-Type: application/pdf" --data-binary @report.pdf
+
+# 3. 写入记录
+dws aitable record update --base-id <BASE_ID> --table-id <TABLE_ID> \
+  --records '[{"recordId":"recXXX","cells":{"fldAttachId":[{"fileToken":"ft_xxx"}]}}]' --format json
+```

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

@@ -0,0 +1,48 @@
+# AI 表格最佳实践
+
+## 1. 字段可写性分类
+
+| 字段类型 | 可写 | 正确方式 |
+|----------|------|----------|
+| 文本/数字/日期/单选/多选/复选框/URL | ✅ | record create/update |
+| 附件 | ⚠️ | 必须先走 [attachment upload 流程](./aitable-attachment.md) |
+| 创建人/修改人/创建时间/修改时间 | ❌ | 系统字段，只读 |
+| 公式/查找引用 | ❌ | 只读，由系统计算 |
+| AI 字段 | ❌ | 只读，由 AI 自动计算 |
+
+## 2. 查询执行契约
+
+1. **不要拉全量后在 context 里手动统计** — 标量聚合用 `record stats`，分组/去重用 `record group-stats`
+2. **has_more=true 时不能做全局结论** — 数据可能不完整
+3. **优先用 `--filters` 在服务端过滤** — 不要拉全量后在本地 jq/grep
+4. **fieldId 必须来自 `field get` 真实返回** — 不要猜测 fieldId
+5. **减少响应体积** — 用 `--field-ids` 仅返回需要的字段
+
+## 3. 任务选路
+
+| 用户诉求 | 优先方案 | 不要误走 |
+|---------|----------|----------|
+| 查看几条数据 | `record query` | 不要用 `--all` |
+| 全量拉取明细 | `record query --all` | 不要手动循环 cursor |
+| 标量统计 | `record stats` | 不要先拉全量再本地计算 |
+| 分组/去重统计 | `record group-stats` | 不要先拉全量再本地 groupby |
+| 全量导出为文件 | `export data` | 不要 `--all` 拉全量再写文件 |
+| 批量写入 | `record create`（分批 100 条） | 不要一次传超过 100 条 |
+| 附件/图片上传 | `attachment upload` 获取 fileToken → `record create/update` 用 fileToken 写入 | **严禁直接传图片 URL 到附件字段**（服务端同步下载会超时） |
+| 文件级导入 | `import upload` + `import data` | 不要手动解析 xlsx 再逐条写入 |
+
+## 4. 创建/修改后回读确认
+
+执行写操作后，建议立即回读确认结果：
+
+| 写操作 | 建议回读命令 | 确认内容 |
+|--------|-------------|----------|
+| `table create` | `table get --table-ids <新tableId>` | 表名、字段列表是否符合预期 |
+| `field create` | `field get --table-id <tableId>` | 新字段是否出现在字段列表中 |
+| `record create/update` | `record query --record-ids <新recordId>` | 写入值是否正确 |
+
+## 5. AI 字段注意事项
+
+- AI 字段的 prompt **必须至少包含一个 `fieldRef` 引用**，纯文本 prompt 会被后端拒绝
+- 先创建/确认被引用字段的 fieldId，再在 prompt 中引用
+- `outputType` 必须与字段类型一致（如 `outputType=text` 配 `--type text`）