Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/dingtalk-skills/dws
dws
Unverified【何时用:仅当用户明确指向钉钉/DingTalk(钉钉文档、钉钉日程等)时使用;泛指做文档/表格/待办/审批默认走本地工具,不要误用钉钉】用 dws CLI 管理钉钉:AI表格/AI搜问(找人首选)/目标管理(Agoal)/组织大脑/日历/通讯录/群聊与机器人消息/待办/审批/智能合同/考勤/日志(日报周报)/DING消息/钉钉文档/云盘/Markdown文件/HTML文件/AI听记/邮箱/在线电子表格(axls)/知识库/白板/开放平台文档/个人IM与OA事件订阅。用户要求操作上述钉钉产品时使用。
references/products/aitable/aitable-workflow.md
View on GitHub# workflow — 自动化工作流管理
创建 / 更新 / 启停 / 手动执行 / 查询执行历史 / 查看 / 列出 Base 下的自动化工作流("当 X 时自动 Y" 流程)。
适用场景:用户要求创建自动化、修改流程、停掉或恢复流程、立即执行流程、核对执行结果或查询已有流程。
## 命令一览
| 命令 | 用途 |
|------|------|
| `workflow edit-example` | 获取工作流编辑文档与 workflow-dsl/v1 示例 |
| `workflow create` | 创建并发布自动化工作流 |
| `workflow update` | 更新并发布已有自动化工作流 |
| `workflow list` | 列出 Base 下所有工作流(含状态/创建人/最后修改时间),支持分页 |
| `workflow get` | 获取单个工作流详情(含 flowSchema 完整节点定义) |
| `workflow enable` | 启用指定工作流(按配置的触发条件自动执行) |
| `workflow disable` | 禁用指定工作流(高危,必须先取得用户明确确认) |
| `workflow run` | 立即执行指定工作流(会产生真实副作用,需确认) |
| `workflow history` | 按状态、时间和分页条件查询工作流执行历史 |
> `workflow edit-example` 无参数;其他子命令的 `--base-id` 必填(可用隐藏别名 `--base`)。
## DSL 入参格式与最小 Demo
先运行 `workflow edit-example` 获取服务端提供的最新编辑文档和示例。`workflow create/update` 的 `--dsl` 接收完整的 `workflow-dsl/v1` JSON object,不是局部 patch。支持内联 JSON、`@文件路径` 或 `-` 从 stdin 读取。
复杂工作流应先用 `table get` / `field get` / `view list` 确认真实 `sheetId`、`fieldId`、`viewId`,并检查所有 `next`、`loopEntry`、branch `to` 和 ref。下面是一个不依赖数据表字段的最小定时消息工作流:
```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"}]}
}
}
}
}
```
create 和 update 都必须同时满足 `status=success`、`data.valid=true`、`data.issues=[]` 才表示发布成功。
## 命令详情
### workflow edit-example — 获取编辑文档与示例
```bash
dws aitable workflow edit-example --format json
```
该命令无业务参数,优先调用 `aitable/get_workflow_dsl_docs`;若当前 MCP 仅注册了历史名称,则在明确收到 `TOOL_NOT_FOUND` 后回退到 `aitable/edit_workflow_example`。创建或更新复杂工作流前优先调用它,避免依赖可能过期的本地 DSL 结构。
### workflow create — 创建并发布工作流
```bash
dws aitable workflow create \
--base-id BASE_ID \
--dsl @workflow.json \
--locale zh-CN \
--format json
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;支持内联、`@filepath`、`-` stdin |
| `--locale` | 否 | 请求语言,如 `zh-CN` / `zh_CN` |
`create` 非幂等,CLI 不自动重试。若网络中断导致结果不确定,先 `workflow list` 按名称确认是否已经创建,再决定是否重试。`status=success` 只说明服务正常返回;`data.valid=false` 仍是发布失败,必须读取 `issues`。
### 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` |
update 返回结构与 create 相同,并会对瞬态错误重试。成功时 `data.flowId` 应与传入的工作流 ID 一致;随后用 `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
```
记录类触发器必须同时传 `--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
```
`--status` 接受 `success` / `failed` / `running` / `break` / `untrigger`;时间参数是 Unix 毫秒且 after 必须小于 before;`--page` 从 0 开始,`--size` 默认 20、最大 100。返回 `totalCount` 与 `list`,其中 `running` 为非终态。
### 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 --format json
```
返回 `{workflowId, disabled: true}` —— 同样是动作确认。禁用后该工作流不再自动触发。
**风险**:直接影响业务自动化(如停掉「记录创建后自动发通知」会让通知断流)。建议:
- 操作前先 `workflow get` 留底当前配置
- 首次调用保留 Runtime 确认门禁;收到 `confirmation_required` 后说明目标和影响,只有取得本次明确确认才按 Runtime 指引重试
## 能力边界
| 能力 | 状态 |
|------|------|
| 新建工作流 | ✅ 创建并发布 |
| 修改工作流配置 | ✅ 更新并发布 |
| 列出工作流 | ✅ |
| 看工作流详情(含 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
# dws 内置 --jq 过滤输出,无需本地 jq(Windows 等环境不保证 jq 可用)
dws aitable workflow create --base-id BASE_ID --dsl @/tmp/workflow.json --locale zh-CN \
--jq '{valid: .data.valid, flowId: .data.flowId, issues: .data.issues}'
# 确认时把拿到的 flowId 直接写进 --jq 表达式(dws --jq 只接一个表达式,不支持 jq 的 --arg 等 CLI 选项)
dws aitable workflow list --base-id BASE_ID --format json \
--jq '.data.list[] | select(.flowId == "<flowId>") | {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 --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(调试 / 迁移前清场)
每个 workflow 单独执行;不需要 shell 循环或本地 jq,直接按 flowId 逐条 disable:
先列出将被停用的 workflow 并取得用户对本批次的明确确认。下列命令保留 Runtime 门禁;确认后由执行方为同一批次逐条附加确认参数。
```bash
# 1. 先列出 RUNNING 的 flowId(从输出逐条读取)
dws aitable workflow list --base-id BASE_ID --limit 100 --format json \
--jq '[.data.list[] | select(.status == "RUNNING") | .flowId]'
# 2. 对每个 flowId 执行(逐条替换 <flowId>)
dws aitable workflow disable --base-id BASE_ID --workflow-id <flowId> --jq '.status'
```
## 注意事项
- `--workflow-id` 接受的就是 `list` 返回里的 `flowId`(同值,CLI 屏蔽了服务端字段名差异)。
- create / update 的 `--dsl` 必须是 JSON object,不能传数组、二次字符串化 JSON 或 `flowSchema`。
- `status=success` 且 `data.valid=false` 仍是 DSL 校验失败;`issues` 才是下一步修复依据。
- create / update 都不在原子调用层自动重试;结果不确定时先用 `workflow list/get` 检查真实状态,不重放已发布的定义。
- enable / disable 出参里的 `enabled` / `disabled` 是 **动作确认 flag**,不是当前状态字段。要确认真生效请走 `workflow list` 查 `status`。
- `workflow get` 的 `flowSchema` 结构随触发器/动作类型变化,不要假设固定字段。
- `workflow run` 不自动重试;结果不确定时用 `workflow history` 按 executionId / instanceId 核对。
- 删除工作流当前仍未开放。
- 每个任务只读一次 `workflow edit-example` 和当前 leaf Schema,从真实示例构造 DSL;不凭记忆复用旧结构。
- DSL 中的 boolean(如 `onceClick`)必须保持 JSON boolean。读回为 `"True"/"False"` 或 `"true"/"false"` 字符串时判定为 MCP 类型污染,停止该分支;不用字符串或删除语义规避。
- `ConditionBranch` 的每个 `to` 必须指向当前 DSL 中真实节点,不使用 `to:null` 表示结束。业务需要空分支但 Schema 没有合法表达时停止,不改写成其他触发语义。
- 本次新建且未经用户专门确认启用的工作流,最终必须用 `workflow list` 证明为 `STOP`。如创建后意外为 `RUNNING`,立即停止依赖步骤;先调用 `workflow disable` 触发 Runtime 确认门禁并向用户说明影响,只有取得本次明确确认后才按 Runtime 指引重试并读回 `STOP`,同时如实说明曾短暂启用和可能副作用。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |