chenmingxuan/EP-Hub-Skill

Fork 0

Files

T

chenmingxuan 0c8fa2653e first commit

2026-09-02 11:44:52 +08:00

64 KiB

Raw Blame History

OA 审批 (oa) 命令参考

命令总览

查询待我处理的审批

Usage:
  dws oa approval list-pending [flags]
Example:
  dws oa approval list-pending --start "2026-03-10T00:00:00+08:00" --end "2026-03-10T23:59:59+08:00"
  dws oa approval list-pending --start "2026-03-10T00:00:00+08:00" --end "2026-03-10T23:59:59+08:00" --query 关键词
Flags:
      --end string   结束时间 ISO-8601 (如 2026-03-10T23:59:59+08:00) (必填)
      --page string  分页页码 (可选)
      --limit string  每页大小 (可选)
      --start string 开始时间 ISO-8601 (如 2026-03-10T00:00:00+08:00) (必填)
      --query string  关键字搜索 (可选)

**默认时间窗口：** 当用户未指定 --start / --end 时，默认查询最近 30 天的待处理审批。

> **IMPORTANT:** 当 `list-pending` 返回空时，必须明确告知用户"当前暂无待处理审批"，并建议扩大时间范围或检查关键词。

获取审批实例详情

Usage:
  dws oa approval detail [flags]
Example:
  dws oa approval detail --instance-id <processInstanceId>
Flags:
      --instance-id string   审批实例 ID (必填)

审批附件授权、上传与下载

先从 approval detail 的返回中取得审批实例 processInstanceId、附件 fileId，以及授权下载所需的 spaceId。根据目标选择命令：

需要单个附件的临时下载链接：attachment download-url
已有钉盘 spaceId/fileId，需要为当前用户批量开通下载权限：attachment authorize-download
需要在审批场景内批量预览附件：attachment authorize-preview
需要把本地文件上传为审批附件（自动完成初始化+PUT+提交）：attachment upload

获取审批附件临时下载链接

Usage:
  dws oa approval attachment download-url [flags]
Example:
  dws oa approval attachment download-url --instance-id <processInstanceId> --file-id <fileId> --format json
Flags:
      --instance-id string          审批实例 ID (必填)
      --file-id string              审批附件文件 ID (必填)
      --with-comment-attachment     是否包含评论中的附件 (可选，默认不包含)

该命令只返回临时下载链接，不会自动保存文件。链接包含 OSS 签名参数，应在生成后立即使用；JSON 输出中的 & 是签名参数分隔符，复制链接时必须完整保留。附件来自审批评论时增加 --with-comment-attachment。

批量授权下载审批钉盘文件

Usage:
  dws oa approval attachment authorize-download [flags]
Example:
  dws oa approval attachment authorize-download --file-infos '[{"spaceId":27827223951,"fileId":"232271651278"}]' --format json
Flags:
      --file-infos string   文件信息 JSON 数组 (必填)，每项包含数字类型 spaceId 和字符串类型 fileId，最多 10 项

该命令为当前用户开通文件下载权限，但不返回下载链接。需要链接时继续调用 attachment download-url。

批量授权预览审批附件

Usage:
  dws oa approval attachment authorize-preview [flags]
Example:
  dws oa approval attachment authorize-preview --instance-id <processInstanceId> --file-ids <fileId1>,<fileId2> --format json
Flags:
      --instance-id string          审批实例 ID (必填)
      --file-ids strings            附件 ID 列表，逗号分隔 (必填)，最多 20 项
      --with-comment-attachment     是否包含评论中的附件 (可选，默认不包含)

该命令只授权审批场景内的附件预览，不等同于下载授权。附件来自审批评论时增加 --with-comment-attachment。

上传本地文件为审批附件

Usage:
  dws oa approval attachment upload [flags]
Example:
  dws oa approval attachment upload --file ./合同.pdf --format json
Flags:
      --file string        本地文件路径 (必填)
      --file-name string   完整文件名，例如 合同.pdf (可选，默认取本地文件名)
      --md5 string         文件原始字节内容的 MD5，32位十六进制字符串 (可选，不传则自动计算)

该命令一条命令完成审批附件上传的全部三步：先调用 oa/init_attachment_upload_info 初始化获取 OSS 上传地址与签名凭证，再将本地文件二进制 HTTP PUT 上传到 OSS，最后调用 oa/commit_attachment_upload_info 提交入库；返回结果包含 fileId、spaceId、fileName、fileSize、fileType。--file-name 不传时默认使用本地文件名，--md5 不传时自动根据文件内容计算，无需手动初始化或提交。

同意审批

CAUTION: 审批决策不可撤回 — 执行前必须向用户确认。

Usage:
  dws oa approval approve [flags]
Example:
  dws oa approval approve --instance-id <id> --task-id <taskId>
  dws oa approval approve --instance-id <id> --task-id <taskId> --remark "同意"
Flags:
      --instance-id string   审批实例 ID (必填)
      --remark string        审批意见 (可选)
      --task-id string       审批任务 ID (必填)

拒绝审批

CAUTION: 审批决策不可撤回 — 执行前必须向用户确认。

Usage:
  dws oa approval reject [flags]
Example:
  dws oa approval reject --instance-id <id> --task-id <taskId> --remark "不同意"
Flags:
      --instance-id string   审批实例 ID (必填)
      --remark string        审批意见 (可选)
      --task-id string       审批任务 ID (必填)

撤销已发起的审批

Usage:
  dws oa approval revoke [flags]
Example:
  dws oa approval revoke --instance-id <id> --yes
  dws oa approval revoke --instance-id <id> --remark "误发起" --yes
Flags:
      --instance-id string   审批实例 ID (必填)
      --remark string        撤销说明 (可选)

获取审批操作记录

Usage:
  dws oa approval records [flags]
Example:
  dws oa approval records --instance-id <processInstanceId>
Flags:
      --instance-id string   审批实例 ID (必填)

查询我已发起的审批实例记录

Usage:
  dws oa approval list-initiated [flags]
Example:
  dws oa approval list-initiated --process-code <code> --start "2026-03-10T00:00:00+08:00" --end "2026-03-10T23:59:59+08:00" --cursor 0 --limit 20
Flags:
      --end string            结束时间 ISO-8601 (如 2026-03-10T23:59:59+08:00) (必填)
      --limit string    每页大小，最大 20 (必填)
      --cursor string     分页游标，首次传 0 (必填)
      --process-code string   表单 processCode (必填)
      --start string          开始时间 ISO-8601 (如 2026-03-10T00:00:00+08:00) (必填)

获取当前用户可见的审批表单列表

Usage:
  dws oa approval list-forms [flags]
Example:
  dws oa approval list-forms --cursor 0 --limit 100
Flags:
      --cursor string  分页游标，首次传 0 (默认 "0")
      --limit string    每页大小，最大 100 (默认 "100")

按关键字模糊搜索审批表单

Usage:
  dws oa approval search-forms [flags]
Example:
  dws oa approval search-forms --query AI
  dws oa approval search-forms --query 报销
Flags:
      --query string  关键字，匹配 processCode 或表单名称 (必填)

按模板 processCode 查询表单 Schema 信息

说明： 根据已知的 processCode 精确查询表单的完整 Schema，包括表单名称、状态、创建者、创建/修改时间以及表单组件 JSON（content 字段）。

Usage:
  dws oa approval form-schema [flags]
Example:
  dws oa approval form-schema --process-code PROC-594AE140-6AA5-4BA4-AF0C-9E6F66DB1E0B
Flags:
      --process-code string  表单模板 processCode (必填)

返回值字段：

result.processName — 表单名称
result.processCode — 表单 processCode
result.processStatus — 表单状态（如 PUBLISHED）
result.creator — 创建者 userId
result.gmtCreate / result.gmtModified — 创建/修改时间（毫秒时间戳）
result.processIconUrl — 表单图标 URL
result.processDescription — 表单描述
result.content — 表单组件 JSON 字符串，包含表单项（items）和标题等配置

流程预测

Usage:
  dws oa approval forecast-process [flags]
Example:
  # 简单预测
  dws oa approval forecast-process --process-code PROC-xxx --dept-id -1 --form-values '{"单行输入框":"测试内容"}'
  # 指定部门预测
  dws oa approval forecast-process --process-code PROC-xxx --dept-id 12345 --form-values '{"金额":"5000"}'
  # 高级用法：传入完整 JSON
  dws oa approval forecast-process --request '{"processCode":"PROC-xxx","deptId":-1,"formComponentValues":[[{"name":"单行输入框","value":"测试"}]]}'
Flags:
      --process-code string   审批模板 processCode（简单模式必填）
      --form-values string    表单值 JSON，格式 '{"控件名称":"值"}'（简单模式必填）
      --dept-id string        发起人所在部门 ID，根部门填 -1（简单模式必填）
      --request string        完整请求体 JSON（高级模式，与简单模式互斥）

注意： forecast 接口的 formComponentValues 比 create-instance 多一层数组包裹（[[{...}]]），CLI 简单模式已自动处理，高级模式需自行包裹。processCode、deptId、formComponentValues 三个字段均为必填，userId 由系统从登录态自动填充。

流程预测的作用

在 create-instance 之前调用 forecast-process，可以根据已填写的表单值预测审批流程走向，核心价值有两个：

展示流程路径 — 告诉用户这个审批会经过哪些节点（审批人、抄送人、条件分支），让用户在提交前就知道流程走向。
识别自选审批人节点 — 返回中 targetSelect: true 的节点需要用户手动选择审批人/抄送人，Agent 应提示用户选人，并将结果传入 create-instance 的 targetSelectActioners。

返回值关键字段

字段	含义
`result.forecastSuccess`	预测是否成功
`result.staticWorkflow`	是否为静态流程（无条件分支）
`result.workflowForecastNodes`	流程节点路径，每个节点包含 `activityId` 和 `outIds`（下一跳）
`result.workflowActivityRuleVOs`	重点：每个节点的详细规则，包含节点类型、审批人、是否自选等

`workflowActivityRuleVOs` 节点字段解读

字段	含义
`activityId`	节点 ID
`workflowActor.actorKey`	自选节点的规则 key，即 `targetSelectActioners` 中 `actionerKey` 的值
`activityName`	节点名称（如"审批人"、"抄送人"）
`activityType`	节点类型：`target_approval`（已指定审批人）、`target_select`（需自选）、`target_notifier`（抄送）
`targetSelect`	`true` 表示需要用户自选审批人/抄送人
`activityActioners`	已确定的处理人列表（含 `emplId`、`name`）
`workflowActor.actorType`	角色类型：`approver`（审批人）、`notifier`（抄送人）
`workflowActor.approvalMethod`	多人审批方式：`ONE_BY_ONE`（依次审批）
`workflowActor.actorSelectionType`	选人范围：`allStaff`（全员可选）等
`prevActivityId`	上一节点 ID

Agent 处理流程

1. 调用 forecast-process，传入 processCode + form-values
2. 遍历 workflowActivityRuleVOs：
   a. 向用户展示每个节点的名称、类型、已指定处理人
   b. 若 targetSelect == true：
      - 提示用户"节点「{activityName}」需要您自选{actorType}人"
      - 使用 dws aisearch person --query "<姓名>" --dimension name --format json 帮用户查找并选人
      - 记录 activityId 和用户选择的 userIds
3. 将自选结果组装为 targetSelectActioners，传入 create-instance 高级模式 --request

自选节点 → `targetSelectActioners` 组装示例

假设 forecast 返回两个自选节点：

{
  "targetSelectActioners": [
    {
      "actionerKey": "manual_33ff_89cb_da91_e3aa",
      "actionerStaffIds": ["userId_选人A"]
    },
    {
      "actionerKey": "manual_a29e_9633_f8b7_7291",
      "actionerStaffIds": ["userId_选人B"]
    }
  ]
}

此字段通过 create-instance --request 的高级模式传入。actionerKey 来自 forecast 返回的 workflowActor.actorKey。

发起审批实例

执行摘要

如果用户未明确给出 processCode，必须固定走 search-forms → form-schema → 收集表单值 → forecast-process → 自选节点选人 → create-instance，不要跳过 form-schema 直接拼请求。
如果用户明确给出 processCode，固定走 form-schema → 收集表单值 → forecast-process → 自选节点选人 → create-instance，不要跳过 form-schema 直接拼请求。
form-schema 返回的 content 不是创建 payload 的原样模板。 它主要用于识别控件 label（即 name）、id、控件类型（componentName）和选项值范围；真正的 formComponentValues 中 value 结构以本文的控件值格式表为准。
forecast-process 返回的自选节点必须在发起前让用户选人。 若 workflowActivityRuleVOs 中有 targetSelect: true 的节点，必须提示用户选择处理人，并将结果通过 targetSelectActioners 传入 create-instance。
所有人员类参数使用 userId。 若用户给的是姓名，先用 dws aisearch person --query "<姓名>" --dimension name --format json 解析成 userId。严禁把姓名直接写进 approvers、ccList、directAppointedApprovers、targetSelectActioners 或表单人员控件。
创建实例前一次性汇总确认。 create-instance 是写操作，执行前一次性展示模板、表单值、流程预测结果和审批人/抄送人供用户确认。

严禁行为

严禁跳过 form-schema。 未拿到表单 Schema 前，不得调用 create-instance。
严禁复用旧的 Schema 结果。 每次发起实例前都必须重新调用 form-schema，模板可能已被修改。
严禁在存在不支持必填控件时强行发起。 若 form-schema 返回的必填控件中有不支持类型（如计算公式、流水号、OCR 等），直接告知用户不支持通过 CLI 发起。注意：附件控件 DDAttachment 已支持通过 CLI 提交，先用 dws oa approval attachment upload --file <path> 获取字段再组装为 value 提交，不属于不支持类型。
严禁把 form-schema 返回的 content 当成可直接提交的 payload 模板。
严禁把姓名直接写进 approvers、ccList、directAppointedApprovers、targetSelectActioners 或表单人员控件。 必须先通过 dws aisearch person --query "<姓名>" --dimension name --format json 转成 userId。
严禁在未得到用户确认前直接执行真实提单。
严禁猜测控件名称或选项值。 必须从 form-schema 返回中提取。
严禁跳过 forecast-process 中的自选节点选人。 若预测返回 targetSelect: true 的节点，必须让用户选人后再发起。

最小判断表

你手上有什么	下一步
只有口语需求，比如"帮我发起请假审批"	先 `search-forms --query 请假`
已拿到 `processCode`	直接 `form-schema --process-code <code>`
已拿到 Schema	向用户展示控件列表，收集表单值
已收集表单值	`forecast-process` 预测流程走向
预测返回有 `targetSelect: true` 节点	让用户为自选节点选人（`dws aisearch person --query "<姓名>" --dimension name --format json` 解析姓名）
预测完成，自选节点已选人	汇总确认后 `create-instance --yes`
用户明确说"不走模板流程，直接指定审批人"	使用 `directAppointedApprovers`（高级模式）

工作流

1. search-forms --query <关键词>     → 拿到 processCode（若已有则跳过）
2. form-schema  --process-code <code> → 拿到控件列表、类型、选项值
3. 检查 Schema 中是否有不支持的必填控件  → 若有则直接告知用户不支持发起
4. 收集表单值                       → 向用户展示控件列表，收集用户填写的表单值
5. forecast-process                  → 根据表单值预测流程走向，识别自选节点
6. 自选节点选人                       → 若预测返回 targetSelect=true 的节点，让用户选人（用 dws aisearch person --query "<姓名>" --dimension name --format json 解析姓名）
7. 汇总确认后 create-instance --yes  → 展示完整信息（表单值 + 流程路径 + 审批人），用户确认后执行发起

IMPORTANT：每次发起实例前都必须重新调用 form-schema 查询模板。 即使用户之前查询过同一个 processCode，模板可能已被修改（控件增减、选项变更、必填属性调整等），不得复用旧的 Schema 结果。

交互优化原则

核心目标：流程清晰，步骤有序，避免重复询问。

先查 Schema 再收集表单值（步骤 2→4）： form-schema 后向用户展示需要填写的控件列表，然后一次性收集全部表单值。不要在未拿到 Schema 前就问用户填什么。
流程预测后再选自选审批人（步骤 5→6）： forecast-process 返回流程路径和自选节点后：
- 先向用户展示完整的流程路径（经过哪些节点、各节点处理人）
- 对 targetSelect: true 的节点，提示用户"节点「{activityName}」需要您自选{actorType}人"
- 用 dws aisearch person --query "<姓名>" --dimension name --format json 帮用户查找并选人
- 若有多个自选节点，一次性收集所有自选节点的选人结果
单次汇总确认（步骤 7）： 发起前一次性展示完整信息供用户确认：
- 审批模板名称
- 表单各控件值
- 流程预测结果（审批路径）
- 各节点审批人/抄送人（含自选节点选人结果）

反例（禁止）：

未查 Schema 就直接问用户填什么表单值
流程预测后逐个节点分别询问选人，而非一次性收集
用户确认前直接执行发起

Usage:
  dws oa approval create-instance [flags]
Example:
  # 简单发起（Agent 在汇总确认后需加 --yes）
  dws oa approval create-instance --process-code PROC-xxx --form-values '{"单行输入框":"测试内容"}' --yes
  # 指定审批人（OR=或签，AND=会签，NONE=单人）
  dws oa approval create-instance --process-code PROC-xxx --form-values '{"单行输入框":"测试"}' --approvers "userId1,userId2" --approvers-action-type OR --yes
  # 指定抄送人
  dws oa approval create-instance --process-code PROC-xxx --form-values '{"单行输入框":"测试"}' --cc-list "userId1" --cc-position START --yes
  # 高级用法：传入完整 JSON（支持 directAppointedApprovers、targetSelectActioners 等全部字段）
  dws oa approval create-instance --request '{"processCode":"PROC-xxx","deptId":-1,"formComponentValues":[{"name":"单行输入框","value":"测试"}]}' --yes
Flags:
      --process-code string              审批模板 processCode（简单模式必填）
      --form-values string               表单值 JSON，格式 '{"控件名称":"值"}'（简单模式必填）
      --dept-id string                   发起人所在部门 ID，根部门填 -1（可选，默认 -1）
      --originator-user-id string        审批发起人 userId（可选，MCP 工具可从登录态获取）
      --approvers string                 审批人 userId 列表，多个用逗号分隔（可选）
      --approvers-action-type string     审批类型：AND（会签）、OR（或签）、NONE（单人）（可选，默认 OR）
      --cc-list string                   抄送人 userId 列表，多个用逗号分隔（可选）
      --cc-position string               抄送时间点：START/FINISH/START_FINISH（可选，默认 START）
      --request string                   完整请求体 JSON（高级模式，与简单模式互斥）
      --yes                              显式确认并发起审批；未提供时命令直接拒绝，不进入交互确认（Agent 必须先汇总并获得用户确认）

两种模式

简单模式： 通过 --process-code + --form-values + 可选 flags 发起，适合大多数场景
高级模式： 通过 --request 传入完整 JSON 请求体，支持 directAppointedApprovers、targetSelectActioners 等复杂字段

组装 form-values

form-values 是简单模式下的核心入参；传入时必须是一个 JSON 对象字符串，key 为控件 label，value 为该控件的提交值。组装原则：

先用 form-schema 识别有哪些控件、每个控件的 label（name）、componentName（type）、选项值范围以及明细子控件结构。
form-schema 返回的 content 不是可直接提交的原样模板。 它提供控件定义，value 结构须按下方控件值格式表组装。
提交时必须保证每个控件的 name（即 label）与 Schema 中的 props.label 完全一致。
如果用户提供的是人员信息，先用 dws aisearch person --query "<姓名>" --dimension name --format json 转成 userId 后再写入对应控件。
单选/多选控件提交的是选项文本（option value），该值从 form-schema 返回的选项定义中取得。
InnerContactField、DepartmentField、TableField、DDDateRangeField、DDAttachment 等控件的 value 结构各不相同，必须按下方格式表单独组装，不要套用文本控件的写法。
TextNote（文字说明）不收集数据，不要出现在 formComponentValues 中。

表单控件值格式速查

重要： formComponentValues 中每条记录的 name 必须与审批模板中控件的 label（即 form-schema 返回的 content.items[].props.label）完全一致。value 为字符串类型，最大 65535 字符。

详细参考： 每种控件的完整属性、约束和示例见 oa-form-components.md。组装前必须先阅读该文档。

控件类型	componentName	value 格式	示例	备注
单行输入框	`TextField`	纯文本	`"测试内容"`
多行输入框	`TextareaField`	纯文本	`"第一行\n第二行"`
数字输入框	`NumberField`	数字字符串	`"100"`
单选框	`DDSelectField`	选项文本	`"同意"`	必须与模板 options 中的 value 完全匹配
多选框	`DDMultiSelectField`	JSON 数组字符串	`'["选项A","选项B"]'`	每个选项须与模板 options 匹配；
日期控件	`DDDateField`	`yyyy-MM-dd`	`"2026-07-27"`
时间区间	`DDDateRangeField`	JSON 数组字符串	`'["2026-07-27","2026-07-30"]'`	label 为数组 `["开始","结束"]`，用开始时间 label 作 name
金额控件	`MoneyField`	数字字符串	`"1500.50"`	自动显示大写金额
电话控件	`PhoneField`	手机号字符串	`"13800138000"`
联系人控件	`InnerContactField`	userId	`"user123"`	多人时传 JSON 数组 `'["user1","user2"]'`；choice="0"单选/"1"多
部门控件	`DepartmentField`	部门 ID	`"12345"`	多部门传 JSON 数组；multiple=true 时支持多选
省市区控件	`AddressField`	JSON 数组字符串	`'["浙江省","杭州市","西湖区"]'`	三级联动；needDetail=true 时末尾加详细地址
图片控件	`DDPhotoField`	URL 数组转义字符串	`"[\"http://example.com/img1.jpg\"]"`	支持 URL 直接提交；不支持本地文件上传
附件控件	`DDAttachment`	JSON 数组转义字符串	`"[{\"spaceId\":\"xxx\",\"fileName\":\"a.pdf\",\"fileSize\":\"333\",\"fileType\":\"pdf\",\"fileId\":\"xxx\"}]"`	支持通过 CLI 提交：先用 `dws oa approval attachment upload --file <path>` 获取 fileId/spaceId/fileName/fileSize/fileType，再组装为 DDAttachment value 提交
评分控件	`StarRatingField`	数字字符串	`"4"`	limit 控制最大星数（默认 5）
关联审批单	`RelateField`	审批实例 ID	`"q-xxx"`	须为当前组织下已存在的实例
明细控件	`TableField`	JSON 数组字符串	`'[{"子控件名":"值1"},{"子控件名":"值2"}]'`	不可嵌套 TableField；不可含 DDMultiSelectField/DDPhotoField；最大 100 行
身份证控件	`IdCardField`	身份证号	`"330102199001011234"`	内置格式校验
文字说明	`TextNote`	—	—	不收集数据，不会出现在 formComponentValues 中

API 不支持的控件

以下控件不支持通过创建实例 API 提交：

TextNote（文字说明）— 纯展示，不收集数据
CalculateField（计算公式）— 由系统自动计算
SeqNumberField（流水号）— 由系统自动生成
OcrTextField / OcrIdCardField（OCR 识别）— 需要客户端交互
套件类控件（暂不支持） — InvoiceField（发票）、RecipientAccountField（收款账户）等业务套件控件当前暂不支持通过 CLI 发起，包含这些控件的审批模板请直接在钉钉客户端操作

DDAttachment（附件控件）已支持通过 CLI 提交： 采用两步流程——先用 dws oa approval attachment upload --file <path> 上传本地文件，返回 fileId、spaceId、fileName、fileSize、fileType；再将这些字段组装为 DDAttachment value（JSON 数组转义字符串）随 create-instance 提交。示例：
# 1) 上传附件，拿到 fileId/spaceId/fileName/fileSize/fileType
dws oa approval attachment upload --file ./a.pdf
# 2) 组装 value 后先向用户展示提单汇总；确认前不要追加 --yes
dws oa approval create-instance --process-code PROC-xxx \
  --form-values '{"附件":"[{\"spaceId\":\"163xxx\",\"fileName\":\"a.pdf\",\"fileSize\":\"333\",\"fileType\":\"pdf\",\"fileId\":\"643xxx\"}]"}'
# 用户确认模板、表单值、流程路径和人员后，才可在同一命令末尾追加 --yes

部分支持的控件： DDPhotoField（图片控件）支持通过 URL 直接提交（见上方速查表），仅不支持本地文件上传（CLI 未封装钉盘 CDN 上传流程）。若用户只有本地文件，需告知在钉钉客户端补充。

如果目标审批模板包含上述控件，不要硬拼 form-values；应告知用户这些字段无需填写或需要在钉钉客户端补充。

必填不支持控件判断规则： 检查 form-schema 返回的控件列表，若存在上述不支持控件且其 props.required 为 true（必填项），则直接告知用户该审批模板不支持通过 CLI 发起，请在钉钉客户端操作。只有不支持控件为非必填时，才可跳过该控件继续发起。

高级模式请求体字段（`--request` JSON 完整结构）

字段	类型	必填	说明
`processCode`	String	是	审批模板唯一码
`originatorUserId`	String	是	发起人 userId（MCP 工具可从登录态自动获取）
`deptId`	Long	否	发起人部门 ID，根部门填 -1；approvers 已传时可不填
`formComponentValues`	Array	是	表单控件值列表，最大 150 条
`approvers`	Array	否	指定审批人列表（覆盖模板流程），最大 20 条
`approvers[].actionType`	String	否	`AND`（会签）/ `OR`（或签）/ `NONE`（单人）
`approvers[].userIds`	Array	否	审批人 userId 列表
`ccList`	Array	否	抄送人 userId 列表，最大 50
`ccPosition`	String	否	`START` / `FINISH` / `START_FINISH`
`directAppointedApprovers`	Array	否	指定审批人组（覆盖模板流程），结构见下方
`targetSelectActioners`	Array	否	自选审批人（模板中有自选节点时必填），最大 20 条

节点参数组装

详细参考： 流程节点类型、审批模式、条件分支和 10 种审批人选择规则的完整说明见 oa-process-nodes.md。

directAppointedApprovers（指定审批人覆盖模板流程）：

当用户明确说"不走模板默认流程"或"直接指定 XX 审批"时使用。

[
  {
    "staffIds": ["userId1", "userId2"],
    "taskActionType": "NONE",
    "staffId": ""
  }
]

staffIds：审批人 userId 列表（必须通过 dws aisearch person --query "<姓名>" --dimension name --format json 获取，严禁填姓名）
taskActionType：NONE（单人审批）/ AND（会签）/ OR（或签）

targetSelectActioners（模板有自选审批节点时使用）：

当 form-schema 返回的模板流程中存在自选审批节点（target_select 类型）时必填。

[
  {
    "actionerKey": "manual_nodeId_xxxx_yyyy",
    "actionerStaffIds": ["userId1"]
  }
]

actionerKey：自选节点的规则 key，可通过获取审批单流程节点信息接口获取 actorKey
actionerStaffIds：操作人 userId 列表

审批类型（approvers actionType）说明：

值	含义	说明
`AND`	会签	所有审批人都必须审批通过
`OR`	或签	任一审批人审批即可
`NONE`	单人审批	只有一个审批人

抄送时间点（ccPosition）说明：

值	含义
`START`	审批发起时抄送
`FINISH`	审批完成时抄送
`START_FINISH`	发起和完成时都抄送

表单控件约束

单个表单最多 200 个控件
控件 label（name）和 placeholder 最大 50 字符
DDSelectField / DDMultiSelectField 的选项 value 必须与模板中配置的选项文本完全一致
TableField（明细）内不可嵌套 TableField，不可包含 DDMultiSelectField 和 DDPhotoField
TextNote（文字说明）不收集数据，无需在 formComponentValues 中传入
InnerContactField 的 userId 应为当前组织下在职成员
DepartmentField 应传入当前组织下存在的部门 ID
RelateField 传入的审批实例 ID 应为当前组织下已存在的实例

返回结果

创建成功后，返回的 result 字段即为新审批实例的 processInstanceId。建议向用户展示：

审批已创建成功：

- 审批模板: <processName>（来自 form-schema）
- 审批实例 ID: <processInstanceId>（来自 create-instance 返回的 result）

后续可用该 processInstanceId 执行 detail、tasks、records、revoke 等操作。

获取审批任务的被催办人 userId

催办必须两步串联： ① ding-info 获取被催办人 userId → ② ding message send 发送催办消息。禁止跳过第一步直接猜测 userId。

Usage:
  dws oa approval ding-info [flags]
Example:
  dws oa approval ding-info --task-id <taskId>
Flags:
      --task-id string  审批任务 ID (必填)，来自 list-pending 或 tasks

返回值字段：

userId — 被催办人用户 ID（必取），作为 ding message send 的 --users 入参，多个以逗号拼接

不返回 robotCode 和 content，需由 agent 自行处理：

--robot-code：优先取环境变量 $DINGTALK_DING_ROBOT_CODE；若无则向用户确认
--content：由 agent 根据审批上下文撰写催办文案，建议格式 "请尽快审批《{表单名}》（提交人：{发起人}，提交时间：{时间}）"
--users：取本接口返回的 userId

叮消息类型（--type）：

默认不发 --type → 应用内 DING 提醒（免费，推荐）
--type sms → 短信提醒（有成本，需向用户确认）
--type call → 电话提醒（有成本，需向用户确认）

完整催办流程：

# Step 1: 获取被催办人 userId
dws oa approval ding-info --task-id <taskId> --format json
# Step 2: 发送催办消息（robotCode 优先走环境变量，content 由 agent 撰写）
dws ding message send --robot-code $DINGTALK_DING_ROBOT_CODE --users <userId逗号拼接> --content "请尽快审批《XXX》" --format json
# Step 3 (可选): 如需短信/电话提醒，加 --type sms 或 --type call
dws ding message send --robot-code $DINGTALK_DING_ROBOT_CODE --users <userId逗号拼接> --content "请尽快审批《XXX》" --type sms --format json

获取任务可回退的节点信息

IMPORTANT: 退回任务前必须先调用此命令获取可回退节点列表，从中提取 activityId 和 revertAction 作为 revert-task 的入参。若无返回值，明确告知用户"当前任务无可回退节点"。

Usage:
  dws oa approval revert-activities [flags]
Example:
  dws oa approval revert-activities --task-id <taskId>
Flags:
      --task-id string  审批任务 ID (必填)

返回字段说明：

instRevertActivities[] — 可回退的节点列表
- activityId — 节点 ID，即 revert-task 的 --target-activity-id
- activityName — 节点名称（如"发起人"、"审批人"），用于向用户展示
- revertAction — 退回方式，即 revert-task 的 --action
  - REVERT_FOR_RESUBMIT → 退回到发起人重交（此时 activityId 为 sid-startevent）
  - REVERT_FOR_APPROVAL → 退回到某审批节点重新审批
- activityActioners[] — 该节点的审批人列表
- actualActioners[] — 该节点的实际处理人列表
- approvalIndex — 审批节点序号（仅审批节点有）
- actType — 审批类型（如 one_by_one 依次审批）

无返回值处理： 若 instRevertActivities 为空或不存在，必须明确告知用户"当前任务无可回退节点"，不得继续执行退回操作。

查询待我审批的任务 ID

Usage:
  dws oa approval tasks [flags]
Example:
  dws oa approval tasks --instance-id <processInstanceId>
Flags:
      --instance-id string   审批实例 ID (必填)

查询我处理过的审批单

Usage:
  dws oa approval list-executed [flags]
Example:
  dws oa approval list-executed --limit <pageSize> --page <pageNumber> --query 关键词
Flags:
      --page string   分页页码，可选，默认是 1
      --limit string   分页大小，可选，默认是 20
      --query string   查询关键词，可选

查询我已经提交的审批单

Usage:
  dws oa approval list-submitted [flags]
Example:
  dws oa approval list-submitted --limit <pageSize> --page <pageNumber> --query 关键词
Flags:
      --page string   分页页码，可选，默认是 1
      --limit string   分页大小，可选，默认是 20
      --query string   查询关键词，可选

查询抄送我的审批单

Usage:
  dws oa approval list-cc [flags]
Example:
  dws oa approval list-cc --limit <pageSize> --page <pageNumber> --query 关键词
Flags:
      --page string   分页页码，可选，默认是 1
      --limit string   分页大小，可选，默认是 20
      --query string   查询关键词，可选

以管理员身份查询审批实例列表

IMPORTANT： 需要当前用户具备 OA 审批管理员权限，否则查不到数据。只查个人维度的审批时改用 list-pending / list-executed / list-initiated / list-cc。

Usage:
  dws oa approval list-by-admin [flags]
Example:
  dws oa approval list-by-admin --process-code <code> --start "2026-03-10T00:00:00+08:00" --cursor 0 --limit 20
  dws oa approval list-by-admin --process-code <code> --start "2026-03-10T00:00:00+08:00" --end "2026-03-10T23:59:59+08:00" --statuses RUNNING,COMPLETED --user-ids "userId1,userId2"
  # 高级用法：传入完整 JSON（startTime/endTime 为 yyyy-MM-dd HH:mm:ss 格式字符串）
  dws oa approval list-by-admin --request '{"processCode":"PROC-xxx","startTime":"2026-03-10 00:00:00","cursor":0,"pageSize":20}'
Flags:
      --process-code string   审批模板 processCode（简单模式必填）
      --start string          开始时间 ISO-8601 (如 2026-03-10T00:00:00+08:00)（简单模式必填）
      --end string            结束时间 ISO-8601 (如 2026-03-10T23:59:59+08:00)（可选）
      --cursor string         分页游标，首次传 0（默认 "0"）
      --limit string          每页大小，最大 20（默认 "20"）
      --user-ids string       按发起人 userId 过滤，多个用逗号分隔（可选）
      --statuses string       按审批状态过滤，多个用逗号分隔（可选，如 RUNNING、TERMINATED、COMPLETED）
      --request string        完整请求体 JSON（高级模式，与简单模式互斥）

MCP 工具: get_process_instances_by_admin；参数封装在 ProcessInstanceListQueryRequest（processCode、startTime 必填，endTime、userIds、statuses、cursor、pageSize 可选；startTime/endTime 为 yyyy-MM-dd HH:mm:ss 格式字符串，简单模式的 ISO-8601 入参会自动转换）。processCode 可从 list-forms / search-forms 获取，返回的 processInstanceId 可用于 detail / records / tasks。

转交审批任务

Usage:
  dws oa approval redirect-task [flags]
Example:
  dws oa approval redirect-task --task-id <taskId> --to-actioner-id <userId>
  dws oa approval redirect-task --task-id <taskId> --to-actioner-id <userId> --remark "请帮忙处理"
Flags:
      --task-id string          审批任务 ID (必填)
      --to-actioner-id string   转交目标用户 ID (必填)
      --remark string           转交说明 (可选)

对审批实例添加评论

Usage:
  dws oa approval oa-comments [flags]
Example:
  dws oa approval oa-comments --instance-id <processInstanceId> --content "同意，请尽快处理"
Flags:
      --instance-id string   审批实例 ID (必填)
      --content string          评论内容 (必填)

对审批实例进行抄送

Usage:
  dws oa approval oa-cc-noticer [flags]
Example:
  dws oa approval oa-cc-noticer --instance-id <processInstanceId> --users "68674200835816"
  dws oa approval oa-cc-noticer --instance-id <processInstanceId> --users "userId1,userId2"
Flags:
      --instance-id string   审批实例 ID (必填)
      --users string     抄送用户 ID 列表，多个用逗号分隔 (必填)

对审批任务进行加签

CAUTION: 加签操作不可撤回 — 执行前必须向用户确认加签类型、被加签人和激活方式。

Usage:
  dws oa approval append-task [flags]
Example:
  dws oa approval append-task --instance-id <processInstanceId> --task-id <taskId> --type before --appender-user-ids "userId1,userId2" --activate-type ALL --agree-all true
  dws oa approval append-task --instance-id <processInstanceId> --task-id <taskId> --type after --appender-user-ids "userId1" --activate-type ONE_BY_ONE --agree-all false
Flags:
      --instance-id string        审批实例 ID (必填)
      --task-id string            审批任务 ID (必填)
      --type string               加签类型：before（前加签），after（后加签），Parallel（并加签）(必填)
      --appender-user-ids string  被加签用户 ID 列表，多个用逗号分隔 (必填)
      --activate-type string      任务激活类型：ALL（或签），ONE_BY_ONE（依次审批）(必填)
      --agree-all                 是否需要全部同意 (必填) 是 true 否 false

退回审批任务

CAUTION: 退回操作不可撤回 — 执行前必须向用户确认退回方式及目标节点。 前置步骤： 必须先调用 revert-activities 获取可回退节点列表，从中提取 activityId 和 revertAction。若无返回值，明确告知用户"当前任务无可回退节点"。

Usage:
  dws oa approval revert-task [flags]
Example:
  # 退回到发起人（targetActivityId 固定传 sid-startevent）
  dws oa approval revert-task --instance-id <processInstanceId> --task-id <taskId> --target-activity-id sid-startevent --action REVERT_FOR_RESUBMIT --remark "补充说明后重提"
  # 退回到某个审批节点（targetActivityId 从 revert-activities 返回中获取 activityId）
  dws oa approval revert-task --instance-id <processInstanceId> --task-id <taskId> --target-activity-id <activityId> --action REVERT_FOR_APPROVAL --remark "重新审批"
Flags:
      --instance-id string          审批实例 ID (必填)
      --task-id string              审批任务 ID (必填)
      --target-activity-id string   退回到的节点 ID；退回发起人时固定传 sid-startevent (必填)
      --action string               退回方式：REVERT_FOR_APPROVAL（退回到审批人）/ REVERT_FOR_RESUBMIT（退回到发起人）(必填)
      --remark string               退回说明 (可选)

意图判断

用户说"待审批/待处理审批/查询XX审批/查XX审批/有没有XX审批/XX的审批单" → approval list-pending，将 XX 作为 --query 关键字传入（可搜索表单名称或表单详情内容）

示例："帮我查询补卡的审批单" → approval list-pending --query 补卡
示例："有没有外出申请的审批" → approval list-pending --query 外出申请
示例："待审批"（无关键词）→ approval list-pending 用户说"审批详情/看审批" → approval detail 用户说"下载审批附件/获取审批附件下载链接" → approval attachment download-url（需 --instance-id 和 --file-id；评论附件增加 --with-comment-attachment）用户说"授权下载审批钉盘文件/批量开通附件下载权限" → approval attachment authorize-download（需 --file-infos，最多 10 项）用户说"预览审批附件/批量授权预览附件" → approval attachment authorize-preview（需 --instance-id 和 --file-ids，最多 20 项；评论附件增加 --with-comment-attachment）用户说"上传审批附件/把文件上传为审批附件" → approval attachment upload（需 --file；可选 --file-name 默认本地文件名、--md5 自动计算；一条命令完成 init+put+commit）用户说"同意审批/批准" → 先 tasks 获取 taskId，再 approve 用户说"拒绝审批/驳回" → 先 tasks 获取 taskId，再 reject 用户说"撤回审批/取消审批" → approval revoke 用户说"审批记录/操作历史" → approval records 用户说"我发起的审批" → approval list-initiated（需 --process-code，可从 list-forms 或 detail 获取）用户说"有哪些审批表单/可见表单" → approval list-forms 用户说"搜索审批表单/查找xx审批表单/有没有xx表单" → approval search-forms（需 --query）用户说"查表单schema/查表单结构/表单模板信息/查表单组件/查表单定义/表单有哪些字段/表单的字段信息" → approval form-schema（需 --process-code，可从 list-forms / search-forms / detail 获取）用户说"预测审批流程/流程预测/审批走向/这个审批走哪些人/审批流程预览" → approval forecast-process（需 --process-code、--dept-id、--form-values）
在 form-schema 之后、create-instance 之前调用
返回的 workflowActivityRuleVOs 中 targetSelect: true 的节点需要用户自选审批人
自选结果组装为 targetSelectActioners 传入 create-instance 用户说"发起审批/提交审批/帮我发起XX审批/新建审批单/提一个XX审批/帮我提XX申请" → 五步流程：① search-forms --query XX 获取 processCode → ② form-schema --process-code <code> 获取表单字段定义 → ③ 阅读 oa-form-components.md 和 oa-process-nodes.md 后组装表单值 → ④ forecast-process 预测流程走向并识别自选节点 → ⑤ 若有自选节点让用户选人，确认后 create-instance --yes 发起
如果用户已知 processCode，可跳过第①步
--form-values 的 key 必须与 form-schema 返回的控件 label 一致
forecast-process 返回自选节点时必须让用户选人，不得跳过
执行前必须向用户确认表单内容、流程预测结果、审批人和抄送人
示例："帮我发起一个AI审批单" → ① search-forms --query AI → ② form-schema --process-code <code> → ③ 组装表单值 → ④ forecast-process → ⑤ 向用户确认流程走向和自选审批人后 create-instance --yes 用户说"催办审批/DING 一下审批人/提醒审批/催一下审批/催批/提醒审批人" → 先 approval ding-info（拿到被催办人 userId），再 ding message send（将 userId 作为 --users 传入；--robot-code 优先走 $DINGTALK_DING_ROBOT_CODE 或向用户确认；--content 由 agent 根据审批上下文撰写）
禁止跳过 ding-info： 不得自行猜测或编造 userId，必须先调用 ding-info 获取
机器人编码获取顺序： ① $DINGTALK_DING_ROBOT_CODE 环境变量 → ② 用户显式提供 → ③ 询问用户
催办内容建议： "请尽快审批《{表单名}》（提交人：{发起人}，提交时间：{时间}）"
ding-info 返回空： 若接口返回空或报错，告知用户"无法获取该任务的被催办人信息"并停止用户说"我有哪些待审的任务" → approval tasks 用户说"我发起的审批单/我发起的XX审批/我提交的XX审批/查我发起的XX" → approval list-submitted，将 XX 作为 --query 关键字传入（可搜索表单名称或表单详情内容）
示例："查我发起的补卡审批单" → approval list-submitted --query 补卡
示例："我发起的审批单"（无关键词）→ approval list-submitted 用户说"我审批/处理过的审批单/我处理过的XX审批/我审批过的XX/查我处理过的XX" → approval list-executed，将 XX 作为 --query 关键字传入（可搜索表单名称或表单详情内容）
示例："查我处理过的补卡审批单" → approval list-executed --query 补卡
示例："我审批过的审批单"（无关键词）→ approval list-executed 用户说"抄送我的审批单/抄送我的XX审批/CC我的XX/查抄送我的XX" → approval list-cc，将 XX 作为 --query 关键字传入（可搜索表单名称或表单详情内容）
示例："查抄送我的补卡审批单" → approval list-cc --query 补卡
示例："抄送我的审批单"（无关键词）→ approval list-cc 用户说"以管理员身份查审批/全员审批单/统计某个模板的审批单/企业内审批记录" → approval list-by-admin（需 --process-code 和 --start，且当前用户需具备 OA 管理员权限）用户说"转交审批/转交任务" → approval redirect-task（需 --task-id 和 --to-actioner-id）用户说"评论审批/添加评论/写评论" → approval oa-comments（需 --instance-id 和 --content）用户说"抄送审批/添加抄送人" → approval oa-cc-noticer（需 --instance-id 和 --users）用户说"加签/前加签/后加签/并加签/增加审批人/追加审批人" → approval append-task（需 --instance-id, --task-id, --type, --appender-user-ids, --activate-type, --agree-all）
--type 映射：前加签 → before，后加签 → after，并加签 → Parallel
--activate-type 映射：或签 → ALL，依次审批 → ONE_BY_ONE
--appender-user-ids 可通过 dws aisearch person 获取目标用户 userId 用户说"退回审批/退回发起人/退回到XX节点/打回重交/重新审批/回退/退回到" → approval revert-task（需 --instance-id, --task-id, --target-activity-id, --action）
前置步骤： 必须先调用 approval revert-activities --task-id <taskId> 获取可回退节点列表，提取 activityId 和 revertAction
无节点处理： 若 revert-activities 返回空 (instRevertActivities 为空)，必须明确告知用户"当前任务无可回退节点"，不得继续执行退回操作
--action 映射：退回发起人/打回重交 → REVERT_FOR_RESUBMIT；退回到审批人/重新审批 → REVERT_FOR_APPROVAL
--target-activity-id：退回发起人时固定传 sid-startevent；退回到审批人时从 revert-activities 返回中获取 activityId

核心工作流

# 1. 查看待我处理的审批 — 提取 processInstanceId
dws oa approval list-pending --start "2026-03-10T00:00:00+08:00" --end "2026-03-10T23:59:59+08:00" --format json

# 2. 查看审批详情 — 了解审批内容
dws oa approval detail --instance-id <processInstanceId> --format json

# 3. 获取待审批任务 ID — 提取 taskId
dws oa approval tasks --instance-id <processInstanceId> --format json

# 4a. 同意审批
dws oa approval approve --instance-id <id> --task-id <taskId> --remark "同意" --format json

# 4b. 拒绝审批
dws oa approval reject --instance-id <id> --task-id <taskId> --remark "不符合要求" --format json

# 5. 撤销自己发起的审批
dws oa approval revoke --instance-id <id> --remark "误发起" --format json

# 6. 查看审批操作记录
dws oa approval records --instance-id <processInstanceId> --format json

# 7. 获取可见审批表单（得到 processCode）
dws oa approval list-forms --cursor 0 --limit 100 --format json

# 7b. 按关键字模糊搜索表单（快速定位 processCode）
dws oa approval search-forms --query AI --format json

# 7c. 按 processCode 查询表单 Schema（获取表单结构、组件定义）
dws oa approval form-schema --process-code <code> --format json

# 8. 查看自己发起的审批列表（--process-code 来自 list-forms 或 detail）
dws oa approval list-initiated --process-code <code> \
  --start "2026-03-10T00:00:00+08:00" --end "2026-03-10T23:59:59+08:00" \
  --cursor 0 --limit 20 --format json

# 9. 我处理过的审批单
dws oa approval list-executed --limit <pageSize> --page <pageNumber> --query 关键词 --format json
# 10. 我发起的审批单
dws oa approval list-submitted --limit <pageSize> --page <pageNumber> --query 关键词 --format json
# 11. 抄送我的审批单
dws oa approval list-cc --limit <pageSize> --page <pageNumber> --query 关键词 --format json

# 11b. 以管理员身份跨用户查询某模板的审批实例列表（需 OA 管理员权限）
dws oa approval list-by-admin --process-code <code> --start "2026-03-10T00:00:00+08:00" --cursor 0 --limit 20 --format json

# 12. 转交审批任务（taskId 来自 tasks，toActionerId 来自 aisearch person）
dws oa approval redirect-task --task-id <taskId> --to-actioner-id <userId> --format json
dws oa approval redirect-task --task-id <taskId> --to-actioner-id <userId> --remark "请帮忙处理" --format json

# 13. 对审批实例添加评论（processInstanceId 来自 list-pending 或 detail）
dws oa approval oa-comments --instance-id <processInstanceId> --content "同意，请尽快处理" --format json

# 14. 对审批实例进行抄送（processInstanceId 来自 list-pending 或 detail）
dws oa approval oa-cc-noticer --instance-id <processInstanceId> --user-list "68674200835816" --format json
dws oa approval oa-cc-noticer --instance-id <processInstanceId> --user-list "userId1,userId2" --format json

# 15. 催办审批（必须两步串联：先拿被催办人 userId，再发 DING）
# 15a. Step 1: 调用 ding-info 拿到被催办人 userId（来自 list-pending 或 tasks 中的 taskId）
dws oa approval ding-info --task-id <taskId> --format json
# 15b. Step 2: 将 userId 填入 --users；robot-code 优先走环境变量 $DINGTALK_DING_ROBOT_CODE（或向用户确认）；content 由 agent 根据审批上下文撰写
dws ding message send --robot-code $DINGTALK_DING_ROBOT_CODE --users <userId1,userId2> --content "请尽快审批《XXX》" --format json
# 15c (可选): 如需短信/电话提醒，加 --type sms 或 --type call
dws ding message send --robot-code $DINGTALK_DING_ROBOT_CODE --users <userId1,userId2> --content "请尽快审批《XXX》" --type sms --format json

# 16. 对审批任务进行加签（instanceId 来自 list-pending/list-submitted/list-executed/detail，taskId 来自list-pending/list-submitted/list-executed/detail中 ，appenderUserIds 来自 aisearch person）
dws oa approval append-task --instance-id <processInstanceId> --task-id <taskId> --type before --appender-user-ids "userId1,userId2" --activate-type ALL --agree-all --format json
dws oa approval append-task --instance-id <processInstanceId> --task-id <taskId> --type Parallel --appender-user-ids "userId1" --activate-type ONE_BY_ONE --agree-all --format json

# 17. 退回审批任务（instanceId/taskId 来自 list-pending、tasks；targetActivityId 和 action 来自 revert-activities）
# 17a. 获取可回退节点（必须先调用，从此返回中提取 activityId 和 revertAction）
dws oa approval revert-activities --task-id <taskId> --format json
# 17b. 退回到发起人重提（targetActivityId 固定 sid-startevent，action=REVERT_FOR_RESUBMIT）
dws oa approval revert-task --instance-id <processInstanceId> --task-id <taskId> --target-activity-id sid-startevent --action REVERT_FOR_RESUBMIT --remark "补充说明后重提" --format json
# 17c. 退回到某个审批节点重新审批（targetActivityId 和 action 从 revert-activities 返回中获取）
dws oa approval revert-task --instance-id <processInstanceId> --task-id <taskId> --target-activity-id <activityId> --action REVERT_FOR_APPROVAL --remark "重新审批" --format json

# 18. 发起审批（完整流程：搜表单 → 查 Schema → 收集表单值 → 流程预测 → 自选节点选人 → 发起）
# 18a. 模糊搜索表单获取 processCode
dws oa approval search-forms --query AI --format json
# 18b. 查询表单 Schema 获取字段定义
dws oa approval form-schema --process-code <code> --format json
# 18c. 收集表单值（向用户展示控件列表，用户填写后组装 form-values）
# 18d. 流程预测（根据表单值预测审批走向，识别自选审批人节点；processCode/deptId/formValues 必填，userId 由登录态自动填充）
dws oa approval forecast-process --process-code <code> --dept-id -1 --form-values '{"单行输入框":"测试内容"}' --format json
# 18e. 若 forecast 返回 targetSelect=true 的节点，用 dws aisearch person --query "<姓名>" --dimension name --format json 帮用户选人
# 18f. 发起审批实例（form-values 的 key 须与 Schema 中控件 label 一致）
dws oa approval create-instance --process-code <code> --form-values '{"单行输入框":"测试内容"}' --yes --format json
# 18g. 发起并指定审批人和抄送人
dws oa approval create-instance --process-code <code> --form-values '{"单行输入框":"测试"}' --approvers "userId1,userId2" --approvers-action-type OR --cc-list "userId3" --cc-position START --yes --format json
# 18h. 发起并使用 forecast 自选审批人结果（高级模式）
dws oa approval create-instance --request '{"processCode":"PROC-xxx","deptId":-1,"formComponentValues":[{"name":"单行输入框","value":"测试"}],"targetSelectActioners":[{"actionerKey":"manual_33ff_89cb_da91_e3aa","actionerStaffIds":["userId_选人A"]}]}' --yes --format json

上下文传递表

操作	从返回中提取	用于
`list-pending`	`processInstanceId`	detail / tasks / records / revoke / oa-comments / oa-cc-noticer / append-task / revert-task 的 --instance-id
`tasks`	`taskId`	approve / reject / redirect-task / append-task / revert-task 的 --task-id
`detail`	`processCode`	list-initiated 的 --process-code
`list-forms`	`processCode`	list-initiated 的 --process-code
`search-forms`	`processCode`	list-initiated 的 --process-code
`form-schema`	`processCode`, `processName`, `content`	查看表单结构定义；`content` 字段包含表单组件 JSON，可解析获取字段列表；控件 label 作为 create-instance --form-values 的 key
`search-forms` → `form-schema`	`processCode` → 表单字段定义	forecast-process / create-instance 的 --process-code 和 --form-values 填写依据
`forecast-process`	`workflowActivityRuleVOs`（`activityId`, `targetSelect`, `activityActioners`, `workflowActor`）	① 向用户展示流程走向和各节点处理人；② `targetSelect: true` 的节点需用户自选审批人，`workflowActor.actorKey` 作为 `targetSelectActioners` 的 `actionerKey` 传入 create-instance
`search-forms` → `form-schema` → `forecast-process`	`processCode` → 字段定义 → 流程走向 + 自选节点	create-instance 的完整上下文：表单值 + 流程路径 + targetSelectActioners
`create-instance`	`result`（processInstanceId）	detail / tasks / records / revoke 等的 --instance-id，可跟踪已发起的审批
`ding-info`	`userId`	ding message send 的 --users（多个逗号拼接）；robotCode 优先走 `$DINGTALK_DING_ROBOT_CODE` 环境变量，content 由 agent 根据审批上下文撰写；返回空时报错并停止
`revert-activities`	`activityId`, `revertAction`, `activityName`	revert-task 的 --target-activity-id 和 --action；返回空时必须告知用户"无可回退节点"
`list-by-admin`	`processInstanceId`	detail / records / tasks 的 --instance-id

注意事项

--start / --end 使用 ISO-8601 格式（如 2026-03-10T00:00:00+08:00）
list-pending 默认时间窗口为最近 30 天；若用户未指定 --start / --end，自动使用当前时间往前推 7 天
list-pending 返回空时必须明确告知用户"当前暂无待处理审批"，不得沉默或跳过
approve / reject / redirect-task / append-task / revert-task 需先通过 tasks 获取 taskId
redirect-task 的 --to-actioner-id 可通过 dws aisearch person 获取目标用户 userId
append-task 的 --appender-user-ids 可通过 dws aisearch person 获取目标用户 userId 但不能是自己
append-task 的 --type 值：before（前加签）、after（后加签）、Parallel（并加签）
append-task 的 --activate-type 值：ALL（或签）、ONE_BY_ONE（依次审批）
append-task 的 --agree-all 值：true（需要全部同意）、false（不需要全部同意）
revert-task 的 --action 值：REVERT_FOR_APPROVAL（退回到某审批节点）、REVERT_FOR_RESUBMIT（退回到发起人）
revert-task 退回前必须先调用 revert-activities --task-id <taskId> 获取可回退节点列表
revert-task 的 --target-activity-id 和 --action 必须来自 revert-activities 返回，禁止自行编造或猜测
revert-activities 返回空 (instRevertActivities 为空) 时，必须明确告知用户"当前任务无可回退节点"，禁止继续执行退回
revert-task 是不可撤回操作，执行前必须向用户确认退回方式及目标节点
revoke 只能撤销自己发起的审批
--remark 审批意见虽为可选，但建议填写以留存审批痕迹
list-initiated 的 --process-code 可从 list-forms、search-forms 或 detail 返回中提取
已知表单名称关键字时优先用 search-forms；需枚举全部表单时用 list-forms
list-by-admin 需要当前用户具备 OA 审批管理员权限，否则查不到数据；只查个人维度审批时改用 list-pending / list-executed / list-initiated / list-cc。高级模式 --request 中 startTime/endTime 为 yyyy-MM-dd HH:mm:ss 格式字符串（不再接受毫秒时间戳）；pageSize 上限为 20，超过会报错（简单模式为 --limit）
催办必须两步串联：ding-info 仅返回被催办人 userId，不返回 robotCode/content；需再调用 dws ding message send，其中 --robot-code 优先使用环境变量 $DINGTALK_DING_ROBOT_CODE，若无则向用户确认；--content 由 agent 根据审批上下文撰写催办文案；严禁跳过 ding-info 直接猜测 userId
催办文案建议格式："请尽快审批《{表单名}》（提交人：{发起人}，提交时间：{时间}）"
ding-info 返回空或报错时，必须明确告知用户"无法获取该任务的被催办人信息"并停止
DING 默认发应用内提醒（无成本）；如需短信/电话提醒可加 --type sms 或 --type call（有成本，建议向用户确认）
form-schema 的 --process-code 可从 list-forms、search-forms 或 detail 返回中提取；返回的 content 字段为 JSON 字符串，需解析后查看表单组件（items）定义。
create-instance 发起前必须先阅读 oa-form-components.md（控件值格式）和 oa-process-nodes.md（流程节点规则），再调用 form-schema 获取表单字段定义，确保 --form-values 中的 key 与控件 label 完全一致。
create-instance 发起前应先调用 forecast-process 预测流程走向，识别自选审批人节点（targetSelect: true），让用户选人后再提交。
create-instance 的 --form-values 接受 JSON 格式 '{"控件名称":"值"}'，代码会自动转为 [{"name":"控件名称","value":"值"}]。
create-instance 简单模式适合常见场景；如需 directAppointedApprovers（指定审批人覆盖模板流程）或 targetSelectActioners（自选审批节点）等高级字段，使用 --request 传完整 JSON。--request 与简单模式 flags 互斥。
create-instance 会创建真实审批数据；Agent 只有在用户确认模板、表单值、流程路径和人员后才能传入 --yes。
create-instance 返回的 processInstanceId 可用于 detail、tasks、records、revoke 等后续操作。
forecast-process 的 processCode、deptId、formComponentValues 三个字段均为必填（userId 由系统自动填充）；formComponentValues 比 create-instance 多一层数组包裹（[[{...}]]），CLI 简单模式已自动处理。
forecast-process 返回 workflowActivityRuleVOs 中 targetSelect: true 的节点，其 workflowActor.actorKey 必须作为 targetSelectActioners 的 actionerKey 传入 create-instance。

自动化脚本

脚本	场景	用法
oa_pending_review.py	查看待审批列表+逐条显示详情	`python oa_pending_review.py --days 7`
oa_batch_approve.py	批量同意/拒绝审批项	`python oa_batch_approve.py --action approve --days 7`

SKILL 摘要（原 dingtalk-oa/SKILL.md 正文）

Shortcuts（无专用脚本/recipe 时优先）

以下 shortcut 同时进入公开 catalog 与 Runtime Schema。先按本 skill 的意图表、脚本和 recipe 路由：存在精确覆盖该场景的专用脚本/recipe 时按其执行；否则用户意图命中时，shortcut 优先于手写原子命令。命令已选中时直接执行；只在参数或安全语义不确定时读取 Agent leaf Schema（例如 dws schema --cli-path "oa +<shortcut>" --compact --format json），在当前 Cobra flags 不确定时读取 dws oa <shortcut> --help。只有参数映射、接口绑定或 provenance 审计才省略 --compact。仅当现有路由和 reference 都无法定位低频能力时，才用 dws shortcut list --service oa --format json 批量发现。

Shortcut	风险	适用场景
`dws oa +search-forms`	read	按关键字模糊搜索当前用户可见的审批表单

意图表

用户说	命令
"待我处理的审批 / 7 天内待审"	`python scripts/oa_pending_review.py --days 7`
"查审批详情"	`dws oa approval detail --instance-id <processInstanceId> --format json`
"同意 / 拒绝审批"	先 `dws oa approval tasks --instance-id <id> --format json` 取 `taskId`，再 `dws oa approval approve --instance-id <id> --task-id <taskId> --format json` / `reject --instance-id <id> --task-id <taskId> --format json`（需用户确认）
"批量同意 / 批量拒绝"	`python scripts/oa_batch_approve.py --action approve --days 7`
"撤销审批"	`dws oa approval revoke --instance-id <id> --format json`
"我已发起的审批"	`dws oa approval list-submitted --format json`

危险操作

approval approve / reject 不可撤回，必须先向用户展示摘要并获得明确同意，再执行审批命令。

跨产品协作

催别人审批 → 在群里 @对方（dingtalk-chat），不要走 #1 消息剧本里的 escalate-ding
审批通过后建待办 → 切到 dingtalk-todo

64 KiB Raw Blame History Unescape Escape