dsh-crwu-workbench 0.0.10

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

@@ -0,0 +1,195 @@
+# 视图扩展操作（lock / frozen-cols / row-height / fill-color-rule / duplicate）
+
+本文档讲 5 项视图操作命令：
+
+- 锁定 / 解锁视图：`view lock` / `view get lock`
+- 冻结列：`view update frozen-cols` / `view get frozen-cols`
+- 行高：`view update row-height` / `view get row-height`
+- 数据高亮规则（条件填色）：`view update fill-color-rule` / `view get fill-color-rule`
+- 复制视图：`view duplicate`
+
+本文只负责上面 5 项额外能力。普通列顺序/filter/sort/group/列宽，以及 card/timebar/aggregate，均由根 Skill 直接路由到各自 reference；选中本文后不要再加载其他视图 reference。这 5 项**不能**通过 `view update --config '{...}'` 写入，必须用各自专属子命令。
+
+## 命令矩阵
+
+| 子命令 | 用途 | 必填参数 | 适用 viewType |
+|---|---|---|---|
+| `view lock [--off]` | 锁定（默认）/ 解锁视图 | `--base-id --table-id --view-id` | 全部 |
+| `view get lock` | 读取锁定状态 | `--base-id --table-id --view-id` | 全部 |
+| `view update frozen-cols --count N` | 冻结左侧 N 列（0 取消） | `--base-id --table-id --view-id --count` | Grid |
+| `view get frozen-cols` | 读取冻结列数 | `--base-id --table-id --view-id` | Grid |
+| `view update row-height --cell-height N` | 设置单元格高度（像素） | `--base-id --table-id --view-id --cell-height` | Grid |
+| `view get row-height` | 读取单元格高度 | `--base-id --table-id --view-id` | Grid |
+| `view update fill-color-rule --json '[...]'` | 全量覆盖条件填色规则 | `--base-id --table-id --view-id --json` | Grid |
+| `view get fill-color-rule` | 读取条件填色规则 | `--base-id --table-id --view-id` | 全部（其他视图返回 `[]`） |
+| `view duplicate [--new-name X]` | 复制视图 | `--base-id --table-id --view-id` | 全部 |
+
+## 视图锁定 / 解锁
+
+```bash
+# 锁定（默认）
+dws aitable view lock --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID
+
+# 解锁
+dws aitable view lock --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --off
+
+# 查询当前是否锁定
+dws aitable view get lock --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+# → {"data": {"baseId": ..., "tableId": ..., "viewId": ..., "locked": true|false}}
+```
+
+锁定的视图禁止他人修改其配置（filter/sort/group/字段顺序等），但记录读写不受影响。锁定状态可重复 set，幂等。
+
+## 冻结列（仅 Grid）
+
+```bash
+# 冻结从首列起 1 列
+dws aitable view update frozen-cols --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --count 1
+
+# 取消冻结
+dws aitable view update frozen-cols --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --count 0
+
+# 查询当前冻结列数
+dws aitable view get frozen-cols --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+# → {"data": {..., "count": 1}}    count 为 null 表示视图未显式设置
+```
+
+`--count` 必须 ≥ 0；负数会被拒绝。
+
+## 行高（仅 Grid）
+
+⚠️ **`--cell-height` 只接受 4 档枚举：32 / 56 / 88 / 128**（与前端 CELL_HEIGHTS 约定一致），其他值会被拒绝。默认值为 32。
+
+```bash
+# 设置行高 — 推荐档位 32 / 56 / 88 / 128
+dws aitable view update row-height --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --cell-height 56
+
+# 查询当前行高
+dws aitable view get row-height --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+# → {"data": {..., "cellHeight": 56}}    cellHeight 为 null 表示视图未显式设置（前端按 32 渲染）
+```
+
+## 数据高亮规则（条件填色，仅 Grid）
+
+`view update fill-color-rule` **整组覆盖**，传 `--json '[]'` 清空所有规则。
+
+### 规则结构
+
+每条规则 JSON 结构：
+
+```jsonc
+{
+  "type": "cell" | "row" | "column" | "preRow",
+  "formatFieldId": "fldX",                     // 命中规则后被高亮的字段（cell/column 类型有意义）
+  "format": { "color": "firstLine5" },         // ⚠️ 必须用 FORMAT_COLORS 代号，不接受 hex
+  "filters": [                                 // 当前固定 1 条
+    {
+      "fieldId": "fldX",                       // ⚠️ 不是 operands[0]
+      "symbol": "GT",                          // ⚠️ 不是 operator；大写枚举
+      "value": 100                             // 部分 symbol（EXIST/UN_EXIST）不需要 value
+    }
+  ]
+}
+```
+
+### color 合法值（FORMAT_COLORS）
+
+`firstLine1` ～ `firstLine11`（共 11 档色码，对应前端调色盘）。**不接受 `#FF0000` 这种 hex**。
+
+### filter.symbol 合法值
+
+| 类别 | symbol |
+|---|---|
+| 数值/通用比较 | `GT` / `LT` / `GTE` / `LTE` / `EQ` / `NE` |
+| 文本 | `CONTAIN` / `EXCLUSIVE` |
+| 存在性（无 value） | `EXIST` / `UN_EXIST` |
+| 多选 / 集合 | `ALL_OF` / `ANY_OF` / `NONE_OF` |
+| 日期 | `BEFORE` / `AFTER` / `NOT_BEFORE` / `NOT_AFTER` / `DATE_EQ` / `FROM_NOW` / `DATE_BETWEEN` |
+
+> **与 `record query --filters` / `view update filter` 的格式不同**：那两处用 `{operator, operands}` 结构；这里是 `{fieldId, symbol, value}`。不要混用。
+
+### 典型用法
+
+```bash
+# 1) 给金额字段 > 100 的单元格上 firstLine5 色
+dws aitable view update fill-color-rule --base-id BASE_ID --table-id TABLE_ID --view-id GRID_ID --json '[
+  {
+    "type":"cell",
+    "formatFieldId":"fldAmount",
+    "format":{"color":"firstLine5"},
+    "filters":[{"fieldId":"fldAmount","symbol":"GT","value":100}]
+  }
+]'
+
+# 2) 清空所有规则
+dws aitable view update fill-color-rule --base-id BASE_ID --table-id TABLE_ID --view-id GRID_ID --json '[]'
+
+# 3) 查询当前规则
+dws aitable view get fill-color-rule --base-id BASE_ID --table-id TABLE_ID --view-id GRID_ID --format json
+# → {"data": [...]} 数组
+```
+
+> **写入后请用 `view get fill-color-rule` 二次确认实际生效**，以读到的 `data` 数组为准。
+
+## 复制视图
+
+```bash
+# 显式命名
+dws aitable view duplicate --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --new-name "副本视图"
+
+# 系统自动命名（一般是 "原视图名 (副本)"）
+dws aitable view duplicate --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+# → {"data": {..., "viewId": "<新视图ID>", "sourceViewId": "<原视图ID>", "viewName": "..."}}
+```
+
+复制会保留源视图的 filter / sort / group / visible-fields / card / timebar 等全部配置；新视图的 viewId 与源视图独立。
+
+## 这些字段不能用 `view update --config '{...}'` 写
+
+下列字段必须用对应的专属子命令；如果错塞进 `view update --config`，CLI 会在 stderr 提示对应子命令并拒绝把字段当 view config 处理：
+
+| 错误用法 | 应改用 |
+|---|---|
+| `--config '{"flags":1}'` | `view lock` / `view lock --off` |
+| `--config '{"frozenColCount":2}'` | `view update frozen-cols --count N` |
+| `--config '{"cellHeight":56}'` | `view update row-height --cell-height N` |
+| `--config '{"rowHeightLevel":"tall"}'` | `view update row-height --cell-height N`（合法档位 32/56/88/128） |
+| `--config '{"conditionalFormats":[...]}'` | `view update fill-color-rule --json '[...]'` |
+
+## 典型工作流
+
+### 配置一个"金额超阈值红色高亮"的 Grid 视图
+
+```bash
+BASE=baseXXX; TABLE=tblYYY; VIEW=viwGridZZ; FLD=fldAmount
+
+# 1) 关键字段冻结，避免横向滚动看不到
+dws aitable view update frozen-cols --base-id $BASE --table-id $TABLE --view-id $VIEW --count 1
+
+# 2) 加大行高让数据更易读
+dws aitable view update row-height --base-id $BASE --table-id $TABLE --view-id $VIEW --cell-height 56
+
+# 3) 金额 > 100 的单元格上色
+dws aitable view update fill-color-rule --base-id $BASE --table-id $TABLE --view-id $VIEW --json "[
+  {\"type\":\"cell\",\"formatFieldId\":\"$FLD\",\"format\":{\"color\":\"firstLine5\"},
+   \"filters\":[{\"fieldId\":\"$FLD\",\"symbol\":\"GT\",\"value\":100}]}
+]"
+
+# 4) 锁定视图，防止他人改坏
+dws aitable view lock --base-id $BASE --table-id $TABLE --view-id $VIEW
+```
+
+### 复制一个"金牌客户"视图给销售团队
+
+```bash
+dws aitable view duplicate --base-id BASE_ID --table-id TABLE_ID --view-id viw_VIP_template --new-name "金牌客户-华东区"
+# 取返回里 data.viewId 进一步定制
+```
+
+### 排查"我设置了高亮规则为啥没生效"
+
+```bash
+# 看实际生效的 conditionalFormats
+dws aitable view get fill-color-rule --base-id BASE_ID --table-id TABLE_ID --view-id VIEW_ID --format json
+# → 如果是 [] 说明上次写入失败；常见原因：color 用了 hex（必须 firstLineN）/ filter 用了 operator（必须 symbol）
+```

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

@@ -0,0 +1,95 @@
+# 视图类型专属配置（card / timebar / aggregate）
+
+仅在任务明确涉及 Kanban/Gallery 卡片、Gantt 时间轴或 Grid 聚合时读取。本文件自包含这三类属性的命令与工作流；普通列顺序、筛选、排序、分组和列宽由根 Skill 直接路由到通用视图配置 reference，不要连读两个视图 reference。
+
+所有命令都必须同时传 `--base-id`、`--table-id`、`--view-id`。`view get/update card` 会先读取一次 viewType，再按 Kanban/Gallery 分发；timebar 仅 Gantt，aggregate 仅 Grid。
+
+## 支持矩阵
+
+| viewType | card | timebar | aggregate |
+|---|:---:|:---:|:---:|
+| Grid |  |  | ✅ |
+| Kanban | ✅ |  |  |
+| Gallery | ✅ |  |  |
+| Gantt |  | ✅ |  |
+| Calendar |  |  |  |
+
+## 读取专属属性
+
+```bash
+dws aitable view get card --base-id <B> --table-id <T> --view-id <V> --format json
+dws aitable view get timebar --base-id <B> --table-id <T> --view-id <V> --format json
+dws aitable view get aggregate --base-id <B> --table-id <T> --view-id <V> --format json
+```
+
+## card（Kanban / Gallery）
+
+服务端按 viewType 分发到 `kanbanCard` 或 `galleryCard`。typed flag 与 `--json` 同时存在时 typed flag 优先；`--no-cover` 与 `--cover-field-id` 互斥。
+
+| flag | 适用范围 | 说明 |
+|---|---|---|
+| `--cover-field-id` | Kanban / Gallery | 封面字段 ID |
+| `--no-cover` | Kanban / Gallery | 清除封面 |
+| `--cover-resize-mode` | Kanban / Gallery | `cover` / `contain` / `stretch` |
+| `--hidden-field-title` | Kanban | 隐藏字段名标题 |
+| `--cover-mode` | Gallery | `none` / `auto` / `custom` |
+| `--display-field-name` | Gallery | 是否显示字段名 |
+| `--json` | Kanban / Gallery | 完整 card 子块对象 |
+
+```bash
+dws aitable view update card --base-id <B> --table-id <T> --view-id <KANBAN_V> \
+  --cover-field-id <ATTACHMENT_FIELD_ID> --cover-resize-mode contain
+dws aitable view update card --base-id <B> --table-id <T> --view-id <KANBAN_V> --no-cover
+dws aitable view update card --base-id <B> --table-id <T> --view-id <GALLERY_V> --cover-mode auto
+dws aitable view update card --base-id <B> --table-id <T> --view-id <GALLERY_V> \
+  --json '{"coverMode":"custom","coverFieldId":"fldX","displayFieldName":true}'
+```
+
+排查 Kanban 封面时先读取 card：`coverFieldId` 为 `NONE` 或缺失表示未配置封面；否则再检查 `coverResizeMode`。
+
+## timebar（仅 Gantt）
+
+`view create --view-type Gantt` 只创建空壳，必须紧跟 `view update timebar --start-field <日期字段ID>`；`view create --config` 不接受 `ganttTimebar`。
+
+| flag | 说明 |
+|---|---|
+| `--start-field` | 开始日期 fieldId |
+| `--end-field` | 结束日期 fieldId |
+| `--display-field-id` | 时间条标题 fieldId |
+| `--timeline-scale` | `year` / `quarter` / `month` / `weeks` |
+| `--color-configs` | 颜色配置 JSON 数组；清空传 `[]` |
+| `--official-holiday` | 是否标注法定节假日 |
+| `--json` | 完整 ganttTimebar 子块 |
+
+```bash
+# 第一步：创建并取得真实 viewId
+dws aitable view create --base-id <B> --table-id <T> --view-type Gantt --name "项目甘特图" --format json
+
+# 第二步：绑定日期字段，否则视图为空
+dws aitable view update timebar --base-id <B> --table-id <T> --view-id <GANTT_V> \
+  --start-field <START_DATE_FIELD_ID> --end-field <END_DATE_FIELD_ID> --timeline-scale month
+
+# 后续只改时间尺度和节假日
+dws aitable view update timebar --base-id <B> --table-id <T> --view-id <GANTT_V> \
+  --timeline-scale quarter --official-holiday=true
+```
+
+## aggregate（仅 Grid）
+
+值是 `map[fieldId]→AggregateAction`；传 `null` 清除某字段聚合。常用 action 包括 `SUM`、`AVG`、`MAX`、`MIN`、`MEDIAN`、`RANGE`、`TOTAL`、`DISTINCT`、`EXIST`、`UN_EXIST`、`CHECKED`、`EARLIEST_DATE`，实际可用项受字段类型限制。
+
+```bash
+dws aitable view update aggregate --base-id <B> --table-id <T> --view-id <GRID_V> \
+  --field-id <FIELD_ID> --action SUM
+dws aitable view update aggregate --base-id <B> --table-id <T> --view-id <GRID_V> \
+  --clear-field-id <FIELD_ID_1,FIELD_ID_2>
+dws aitable view update aggregate --base-id <B> --table-id <T> --view-id <GRID_V> \
+  --json '{"fldAmount":"AVG","fldObsolete":null}'
+```
+
+## 写后验证与停止条件
+
+- 每次 update 后只用同一属性的 `view get card|timebar|aggregate` 回读，不加载其他 reference。
+- viewType 不匹配时停止并保留真实错误，不更换 viewId 猜测。
+- Gantt 未取得真实日期 fieldId 时停止，不用字段名代替。
+- typed flag 与 `--json` 冲突时以 typed flag 为准；不要重复提交同一写操作。

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

@@ -0,0 +1,384 @@
+# workflow — 自动化工作流管理
+
+创建 / 更新 / 启停 / 手动执行 / 查询执行历史 / 查看 / 列出 Base 下的自动化工作流（"当 X 时自动 Y" 流程）。
+适用场景：用户要求创建自动化、修改流程、停掉或恢复流程、立即执行流程、核对执行结果或查询已有流程。
+
+## 命令一览
+
+| 命令 | 用途 |
+|------|------|
+| `workflow edit-example` | 获取工作流编辑文档与 workflow-dsl/v1 示例 |
+| `workflow create` | 创建并发布自动化工作流 |
+| `workflow update` | 更新并发布已有自动化工作流 |
+| `workflow list` | 列出 Base 下所有工作流（含状态/创建人/最后修改时间），支持分页 |
+| `workflow get` | 获取单个工作流详情（含 flowSchema 完整节点定义） |
+| `workflow enable` | 启用指定工作流（按配置的触发条件自动执行） |
+| `workflow disable` | 禁用指定工作流（高危，建议 `--yes` 二次确认） |
+| `workflow run` | 立即执行指定工作流（会产生真实副作用，需确认） |
+| `workflow history` | 按状态、时间和分页条件查询工作流执行历史 |
+
+> `workflow edit-example` 无参数；其他子命令的 `--base-id` 必填（可用隐藏别名 `--base`）。
+
+## DSL 入参格式与最小 Demo
+
+先运行 `workflow edit-example` 获取服务端提供的最新编辑文档和示例。`workflow create/update` 的 `--dsl` 接收钉钉 AI 表格 `workflow-dsl/v1` JSON object。
+
+复杂工作流还应注意：
+
+1. 使用 `workflow edit-example` 获取最新 DSL Guide、结构和示例。
+2. 涉及数据表、字段或视图的节点，先用 `table get` / `field get` / `view list` 确认真实 `sheetId`、`fieldId`、`viewId`。
+3. create 和 update 都提交完整的 workflow-dsl/v1 JSON object，并检查所有 `next`、`loopEntry`、branch `to` 和 ref。
+
+以下 Demo 表示“每天 09:00 触发，并向 Base 所有者发送消息”，不依赖数据表、字段或视图 ID：
+
+```json
+{
+  "version": "workflow-dsl/v1",
+  "name": "每日提醒",
+  "description": "可选说明",
+  "trigger": "start",
+  "steps": {
+    "start": {
+      "type": "Scheduled",
+      "next": "send",
+      "data": {
+        "mode": "daily",
+        "time": "09:00",
+        "timezone": "GMT+08:00"
+      }
+    },
+    "send": {
+      "type": "SendMessage",
+      "data": {
+        "title": "定时任务已触发",
+        "to": {
+          "users": [{"ref": "$.system_node.ownerUserId"}]
+        }
+      }
+    }
+  }
+}
+```
+
+将上述 JSON 保存为 `workflow.json` 后创建工作流：
+
+```bash
+dws aitable workflow create \
+  --base-id BASE_ID \
+  --dsl @workflow.json \
+  --locale zh-CN \
+  --format json
+```
+
+保存创建结果中的 `data.flowId`。更新时修改 `workflow.json` 中的完整目标定义，例如修改 `name`、`description` 或消息 `title`，然后调用：
+
+```bash
+dws aitable workflow update \
+  --base-id BASE_ID \
+  --workflow-id FLOW_ID \
+  --dsl @workflow.json \
+  --locale zh-CN \
+  --format json
+```
+
+create 和 update 都必须同时满足 `status=success`、`data.valid=true`、`data.issues=[]` 才表示发布成功；update 返回的 `data.flowId` 应与传入的 `FLOW_ID` 一致。以上仅为最小 Demo，复杂节点的 `type` 和 `data` 结构以钉钉 AI 表格 MCP 最新 DSL 文档为准。
+
+## 命令详情
+
+### workflow edit-example — 获取编辑文档与示例
+
+```bash
+dws aitable workflow edit-example --format json
+```
+
+该命令无业务参数，调用 `aitable/edit_workflow_example` 返回服务端提供的工作流编辑文档和示例。创建或更新复杂工作流前优先调用它，避免依赖可能过期的本地 DSL 结构。
+
+### workflow create — 创建并发布工作流
+
+```bash
+# 大 DSL 推荐从文件读取
+dws aitable workflow create \
+  --base-id BASE_ID \
+  --dsl @workflow.json \
+  --locale zh-CN \
+  --format json
+
+# 也支持 stdin
+cat workflow.json | dws aitable workflow create --base-id BASE_ID --dsl - --format json
+```
+
+| flag | 必填 | 说明 |
+|------|------|------|
+| `--base-id` | 是 | 所属 Base ID |
+| `--dsl` | 是 | workflow-dsl/v1 JSON object；支持内联 JSON、`@filepath`、`-` stdin |
+| `--locale` | 否 | 请求语言，如 `zh-CN` / `zh_CN` |
+
+创建成功返回发布结果：
+
+```json
+{
+  "status": "success",
+  "data": {
+    "valid": true,
+    "flowId": "G-FLOW-XXXXXX",
+    "flowSchema": {},
+    "stepNodeIds": {},
+    "referenceMap": {},
+    "issues": []
+  }
+}
+```
+
+关键语义：
+
+- `create` 非幂等，CLI 不自动重试。若网络中断导致结果不确定，先 `workflow list` 按名称确认是否已创建，再决定是否重试。
+- `status=success` 只说明 workflow-edit 正常返回；如果 `data.valid=false`，仍表示 DSL 未通过校验或发布，必须读取 `issues` 修正。
+- 创建并发布后，用 `workflow list` 确认 `status`；需要运行但状态为 `STOP` 时再调用 `workflow enable`。
+
+### workflow update — 更新并发布工作流
+
+```bash
+# 先留底现有详情，再提交完整目标 DSL
+dws aitable workflow get --base-id BASE_ID --workflow-id WORKFLOW_ID --format json > /tmp/workflow-backup.json
+dws aitable workflow update \
+  --base-id BASE_ID \
+  --workflow-id WORKFLOW_ID \
+  --dsl @workflow.json \
+  --locale zh_CN \
+  --format json
+```
+
+| flag | 必填 | 说明 |
+|------|------|------|
+| `--base-id` | 是 | 所属 Base ID |
+| `--workflow-id` | 是 | 目标工作流 ID，对应 list 的 `flowId` |
+| `--dsl` | 是 | 完整目标 workflow-dsl/v1 JSON object；支持内联、`@filepath`、`-` stdin |
+| `--locale` | 否 | 请求语言，如 `zh-CN` / `zh_CN` |
+
+返回结构与 create 相同，成功时 `flowId` 应为目标工作流。update 使用 AI 表格瞬态错误重试；最终仍必须检查 `data.valid` 和 `issues`，并用 `workflow get/list` 验证发布结果与运行状态。
+
+### workflow run — 立即执行工作流
+
+```bash
+# 记录类触发器
+dws aitable workflow run --base-id BASE_ID --workflow-id WORKFLOW_ID \
+  --table-id TABLE_ID --record-ids RECORD_ID_1,RECORD_ID_2
+
+# 定时触发器不传 table-id / record-ids
+dws aitable workflow run --base-id BASE_ID --workflow-id WORKFLOW_ID
+```
+
+| flag | 必填 | 说明 |
+|------|------|------|
+| `--base-id` | 是 | 所属 Base ID |
+| `--workflow-id` | 是 | 目标工作流 ID |
+| `--table-id` | 条件必填 | 记录类触发器绑定的数据表；必须与触发器配置一致 |
+| `--record-ids` | 条件必填 | 记录类触发器的记录 ID，1–5 个、逗号分隔且不可重复 |
+
+`run` 启动真实异步执行，工作流中的发消息、写记录等动作会实际发生；执行前必须取得用户确认。返回项中的 `executionId` 是本次执行标识，可与 `workflow history` 项目的 `instanceId` 匹配。网络结果不确定时不要直接重复执行，先按该标识查询历史。
+
+### workflow history — 查询执行历史
+
+```bash
+dws aitable workflow history --base-id BASE_ID --workflow-id WORKFLOW_ID \
+  --status failed --after-time 1786000000000 --before-time 1787000000000 \
+  --page 0 --size 50
+```
+
+| flag | 说明 |
+|------|------|
+| `--base-id` | 必填 |
+| `--workflow-id` | 必填；CLI 会映射为 MCP 的 `flowId` |
+| `--status` | 可选：`success` / `failed` / `running` / `break` / `untrigger` |
+| `--after-time` | 可选，Unix 毫秒开始时间 |
+| `--before-time` | 可选，Unix 毫秒结束时间；与 after-time 同传时必须更大 |
+| `--page` | 可选，从 0 开始，默认 0 |
+| `--size` | 可选，默认 20，范围 `[1, 100]` |
+
+返回 `totalCount` 和 `list`。`running` 是非终态；`success`、`failed`、`break`、`untrigger` 是终态。
+
+### workflow list — 列出工作流
+
+```bash
+dws aitable workflow list --base-id BASE_ID --format json
+dws aitable workflow list --base-id BASE_ID --limit 50 --offset 100
+```
+
+| flag | 说明 |
+|------|------|
+| `--base-id` | 必填 |
+| `--limit` | 可选，分页大小 `[1, 100]`，不传走服务端默认 20 |
+| `--offset` | 可选，分页偏移量 `>= 0`，不传走服务端默认 0 |
+
+返回结构：
+
+```json
+{
+  "data": {
+    "list": [
+      {
+        "flowId": "G-FLOW-XXXXXX",            // ★ 注意字段名是 flowId
+        "name": "流程1",
+        "description": "当创建记录时，就更新记录",
+        "status": "RUNNING",                  // RUNNING / STOP
+        "creatorStaffId": "281493",
+        "lastModifier": { "name": "李普阳", "staffId": "281493" },
+        "gmtModified": 1780318540000,
+        "versionId": "G-FLOW-VER-XXXXXX",
+        "icons": ["..."],                     // 触发器+动作的图标
+        "isSubFlow": false,
+        "opPermissions": { "canEdit": true }
+      }
+    ],
+    "recordCount": 1,                         // Base 下总数
+    "runningCount": 1                         // RUNNING 状态的数量
+  }
+}
+```
+
+**注意**：
+- 标识字段服务端在 `list` 里叫 **`flowId`**，但在 `enable` / `disable` 出参里叫 **`workflowId`**。CLI `--workflow-id` 传任一即可（同值）。
+- `status` 是字符串枚举：`RUNNING`（启用中）/ `STOP`（已禁用），**不是** boolean。
+- `runningCount` 是当前 Base 下 status=RUNNING 的工作流数，方便快速判断「有几个流程在跑」。
+
+### workflow get — 获取单个工作流详情
+
+```bash
+dws aitable workflow get --base-id BASE_ID --workflow-id WORKFLOW_ID --format json
+```
+
+| flag | 说明 |
+|------|------|
+| `--base-id` | 必填 |
+| `--workflow-id` | 必填，对应 list 出参里的 `flowId` |
+
+返回完整工作流配置：
+
+```json
+{
+  "data": {
+    "name": "流程1",
+    "namespace": "...",
+    "status": "RUNNING",
+    "versionId": "G-FLOW-VER-XXXXXX",
+    "versionNo": 14,
+    "versionStatus": "...",
+    "accessor": {...},                  // 访问者信息
+    "corpId": "...",
+    "flowAttribute": {...},             // 流程顶层属性
+    "flowSchema": {...},                // ★ 流程节点定义（触发器/动作/分支等）
+    "gmtCreate": 1780317804000,
+    "gmtModified": 1780318540000
+  }
+}
+```
+
+`flowSchema` 是完整的节点 DAG，结构因流程而异（条件触发器 vs 定时触发器、单分支 vs 多分支等）。agent 应按需读取关心字段，不要试图建静态 schema。
+
+### workflow enable — 启用工作流
+
+```bash
+dws aitable workflow enable --base-id BASE_ID --workflow-id WORKFLOW_ID --format json
+```
+
+返回 `{workflowId, enabled: true}` —— **`enabled: true` 是动作确认，不是当前状态查询**。要确认真启用了，必须再 `workflow list` 看 `status` 是否变成 `"RUNNING"` 或 `runningCount` 是否加 1。
+
+### workflow disable — 禁用工作流（高危）
+
+```bash
+dws aitable workflow disable --base-id BASE_ID --workflow-id WORKFLOW_ID --yes --format json
+```
+
+返回 `{workflowId, disabled: true}` —— 同样是动作确认。禁用后该工作流不再自动触发。
+
+**风险**：直接影响业务自动化（如停掉「记录创建后自动发通知」会让通知断流）。建议：
+- 操作前先 `workflow get` 留底当前配置
+- 脚本场景显式传 `--yes`；交互场景让用户在 prompt 中再次确认
+
+## 能力边界
+
+| 能力 | 状态 |
+|------|------|
+| 新建工作流 | ✅ 创建并发布 |
+| 修改工作流配置 | ✅ 更新并发布 |
+| 列出工作流 | ✅ |
+| 看工作流详情（含 flowSchema） | ✅ |
+| 启用/禁用 | ✅ |
+| 查看运行历史/执行日志 | ✅ `workflow history` |
+| 手动触发/单次运行 | ✅ `workflow run`（需确认） |
+| 删除工作流 | ❌ 暂未开放 |
+
+## 错误码速查
+
+| 场景 | code | type | 备注 |
+|------|------|------|------|
+| create/update 返回 `valid=false` | — | success envelope | 读取 `data.issues` 修正 DSL，不能当作发布成功 |
+| create 下游失败 | `CREATE_WORKFLOW_ERROR` | `SYSTEM_ERROR` | create 不自动重试；先 list 排查是否已创建 |
+| update 下游失败 | `UPDATE_WORKFLOW_ERROR` | `SYSTEM_ERROR` | update 会重试瞬态错误，最终失败时保留 DSL 和 workflowId 排查 |
+| `workflow-id` 不存在调 get | `GET_WORKFLOW_ERROR` | `SYSTEM_ERROR` | message 可能为 null，先 `workflow list` 核对 ID |
+| `workflow-id` 不存在调 enable | `ENABLE_WORKFLOW_ERROR` | `SYSTEM_ERROR` | message 含 "场域中不存在该 namespace" |
+| `workflow-id` 不存在调 disable | `DISABLE_WORKFLOW_ERROR` | `SYSTEM_ERROR` | 同上 |
+| `--limit` < 1 或 > 100 | （CLI 层拦截） | — | `--limit 必须在 [1, 100] 范围内，got N` |
+| `--offset` < 0 | （CLI 层拦截） | — | `--offset 必须 >= 0，got N` |
+
+> 拿到 `*_WORKFLOW_ERROR / SYSTEM_ERROR` 时，先 `workflow list` 自查目标 ID 是否还存在、是否在当前 Base 下。
+
+## 典型工作流
+
+### 创建并确认一个工作流
+
+```bash
+# 1. 按本文 DSL Demo 生成 /tmp/workflow.json
+dws aitable workflow create --base-id BASE_ID --dsl @/tmp/workflow.json --locale zh-CN --format json \
+  | tee /tmp/workflow-result.json
+
+# 2. valid 必须为 true；保存 flowId
+jq '{valid: .data.valid, flowId: .data.flowId, issues: .data.issues}' /tmp/workflow-result.json
+
+# 3. 确认运行状态，需要时显式启用
+FLOW_ID=$(jq -r '.data.flowId' /tmp/workflow-result.json)
+dws aitable workflow list --base-id BASE_ID --format json \
+  | jq --arg id "$FLOW_ID" '.data.list[] | select(.flowId == $id) | {flowId, name, status}'
+```
+
+### 看看 Base 里有哪些自动化在跑
+
+```bash
+dws aitable workflow list --base-id BASE_ID --format json | jq '.data | {total: .recordCount, running: .runningCount, items: .list | map({name, status, flowId})}'
+```
+
+### 临时停掉某个流程做调试
+
+```bash
+# 1. 留底当前状态
+dws aitable workflow get --base-id BASE_ID --workflow-id WORKFLOW_ID --format json > /tmp/wf-backup.json
+
+# 2. 禁用
+dws aitable workflow disable --base-id BASE_ID --workflow-id WORKFLOW_ID --yes --format json
+
+# 3. 调试做完后重启
+dws aitable workflow enable --base-id BASE_ID --workflow-id WORKFLOW_ID --format json
+
+# 4. 确认 status=RUNNING
+dws aitable workflow list --base-id BASE_ID --format json | jq '.data.list[] | select(.flowId == "WORKFLOW_ID") | .status'
+```
+
+### 批量关掉某个 Base 下所有 workflow（调试 / 迁移前清场）
+
+```bash
+for WF in $(dws aitable workflow list --base-id BASE_ID --limit 100 --format json | jq -r '.data.list[] | select(.status == "RUNNING") | .flowId'); do
+  dws aitable workflow disable --base-id BASE_ID --workflow-id "$WF" --yes --format json | jq .status
+done
+```
+
+## 注意事项
+
+- `--workflow-id` 接受的就是 `list` 返回里的 `flowId`（同值，CLI 屏蔽了服务端字段名差异）。
+- create / update 的 `--dsl` 必须是 JSON object，不能传数组、字符串化的二次 JSON 或 FlowSchema。
+- 本文 Demo 可直接用于最小定时消息工作流；复杂节点应以钉钉 AI 表格 MCP 最新 DSL 文档为准。
+- `status=success` 且 `data.valid=false` 仍是 DSL 校验失败；`issues` 才是下一步修复依据。
+- create 不自动重试；update 仅对网络/5xx/`retryable:true` 瞬态错误自动重试。
+- enable / disable 出参里的 `enabled` / `disabled` 是 **动作确认 flag**，不是当前状态字段。要确认真生效请走 `workflow list` 查 `status`。
+- `workflow get` 的 `flowSchema` 结构随触发器/动作类型变化，不要假设固定字段。
+- `workflow run` 不自动重试；结果不确定时用 `workflow history` 按 executionId / instanceId 核对。
+- 删除工作流当前仍未开放。