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/oa.md
View on GitHub# OA 审批 (oa) 命令参考
## 命令总览
### 查询待我处理的审批
```
Usage:
dws oa approval list-pending [flags]
Example:
dws oa approval list-pending --create-time-from 2026-03-10 --create-time-to 2026-03-31
dws oa approval list-pending --query 关键词 --process-code <code> --page 1 --limit 20
Flags:
--page int 分页页码(默认 1)
--limit int 每页大小(默认 20,最大 100)
--query string 关键字搜索
--process-code string 审批模板 code
--originator-user-id string 审批单发起人 userId
--create-time-from string 发起时间起始(yyyy-MM-dd)
--create-time-to string 发起时间截止(yyyy-MM-dd,含当日)
--finish-time-from string 完成时间起始(yyyy-MM-dd)
--finish-time-to string 完成时间截止(yyyy-MM-dd,含当日)
--create-before string 创建时间
```
### 获取审批实例详情
```
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:** 审批决策不可撤回 — 执行前必须向用户确认,确认后加 `--yes`。
```
Usage:
dws oa approval approve [flags]
Example:
dws oa approval approve --instance-id <id> --task-id <taskId> --yes
dws oa approval approve --instance-id <id> --task-id <taskId> --remark "同意" --yes
Flags:
--instance-id string 审批实例 ID (必填)
--remark string 审批意见 (可选)
--task-id string 审批任务 ID (必填)
--yes 跳过确认(用户已同意后使用)
```
### 拒绝审批
> **CAUTION:** 审批决策不可撤回 — 执行前必须向用户确认,确认后加 `--yes`。
```
Usage:
dws oa approval reject [flags]
Example:
dws oa approval reject --instance-id <id> --task-id <taskId> --remark "不同意" --yes
Flags:
--instance-id string 审批实例 ID (必填)
--remark string 审批意见 (可选)
--task-id string 审批任务 ID (必填)
--yes 跳过确认(用户已同意后使用)
```
### 撤销已发起的审批
> **CAUTION:** 撤销不可恢复 — 危险操作,执行前必须向用户确认,确认后加 `--yes`。
```
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 撤销说明 (可选)
--yes 跳过确认(用户已同意后使用)
```
### 获取审批操作记录
```
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),与 start 间隔不超过120天 (必填)
--limit string 每页大小,最大 20 (必填)
--cursor string 分页游标,首次传 0 (必填)
--process-code string 表单 processCode (必填)
--start string 开始时间 ISO-8601 (如 2026-03-10T00:00:00+08:00),与 end 间隔不超过120天 (必填)
```
### 查询可管理的审批模板及详情
```bash
dws oa approval template list --format json
dws oa approval template detail --process-code PROC-EXAMPLE --format json
```
- `template list` 无业务参数,调用 `oa/list_manage_templates`,查询当前用户在当前组织可管理的模板。
- `template detail` 只接收一个必填的 `--process-code`,调用 `oa/get_template_detail` 时转换为单元素 `processCodes` 数组。
- 两个命令通过统一输出的 `data.templates` 返回模板数组;详情中的 `schemaContent` 和 `processConfig` 保留为服务端 JSON 字符串,其余模板字段原样保留。
- 管理权限列表与 `list-forms` 的可发起模板列表语义不同。查看审批实例使用 `oa approval detail`;读取发起审批所需字段定义使用 `form-schema`。
- 服务端 `success=false`(例如 `dingOpenErrcode=830001`)会使命令失败。
### 获取当前用户可见的审批表单列表
```
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")
```
MCP 工具: `list_user_visible_process`;参数: cursor, pageSize(对应 --cursor/--limit)。返回结果含 processCode,可用于 list-initiated 的 --process-code。
### 按关键字模糊搜索审批表单
```
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)和标题等配置
考勤套件发起链路的服务端前置命令(`dws attendance approve` 组与 `+` shortcut)见 attendance.md 对应章节;四个套件的发起工作流与纪律见下方「套件发起工作流(独立文档)」指针表。
### 流程预测
```
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`,可以根据已填写的表单值预测审批流程走向,核心价值有两个:
1. **展示流程路径** — 告诉用户这个审批会经过哪些节点(审批人、抄送人、条件分支),让用户在提交前就知道流程走向。
2. **识别自选审批人节点** — 返回中 `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 返回两个自选节点:
```json
{
"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` 直接拼请求。
- **`forecast-process` 返回的自选节点必须在发起前让用户选人。** 见「流程预测」节与「严禁行为」。
- **创建实例前一次性汇总确认。** `create-instance` 是写操作,执行前一次性展示模板、表单值、流程预测结果和审批人/抄送人供用户确认。
#### 严禁行为
- **严禁跳过 `form-schema`。** 未拿到表单 Schema 前,不得调用 `create-instance`。
- **严禁在存在不支持必填控件时强行发起。** 若 `form-schema` 返回的必填控件中有不支持类型(如计算公式、流水号、OCR 等),直接告知用户不支持通过 CLI 发起。**注意:附件控件 `DDAttachment` 已支持通过 CLI 提交**,先用 `dws oa approval attachment upload --file <path>` 获取字段再组装为 value 提交,不属于不支持类型。
- **严禁把 `form-schema` 返回的 `content` 当成可直接提交的 payload 模板。**
- **严禁把姓名直接写进 `approvers`、`ccList`、`directAppointedApprovers`、`targetSelectActioners` 或表单人员控件。** 必须先经 aisearch person 按姓名解析为 userId。
- **严禁在未得到用户确认前直接执行真实提单。**
- **严禁猜测控件名称或选项值。** 必须从 `form-schema` 返回中提取。
- **严禁在发起后的验收环节重复执行写命令。** `create-instance` 成功后,验收只用只读的 `tasks --instance-id` / `detail --instance-id` 核对状态与表单存储;重复执行 `create-instance` 会直接产生重复审批单。
- **严禁跳过 `forecast-process` 中的自选节点选人。** 若预测返回 `targetSelect: true` 的节点,必须让用户选人并将结果通过 `targetSelectActioners` 传入 `create-instance`。
#### 模板不支持 CLI 发起时:submitUrl 链接引导
当模板不支持 CLI 发起(含不支持必填控件、请假套件特例哺乳假/需上传证明材料、补卡模板含需上传证据的图片控件等)时,引导用户点击 `dws attendance +get-approve-template` 返回的 `submitUrl` 提交。链接展示规范:使用 Markdown 可点击链接格式 `[formName](submitUrl)`(如 `[员工请假](https://...)`);如存在更匹配的模板可放在列表前面,但不要只返回推荐模板,必须同时返回其它可用模板供用户选择,且每个模板都应是用户可直接点击的 Markdown 链接。
#### 最小判断表
| 你手上有什么 | 下一步 |
|---|---|
| 只有口语需求,比如"帮我发起请假审批" | 请假/补卡/外出/加班走 `dws attendance +get-approve-template`(--type leave / repair-check / travel / overtime)定位模板(见 [oa/oa-leave.md](oa/oa-leave.md) / [oa/oa-supply.md](oa/oa-supply.md) / [oa/oa-goout.md](oa/oa-goout.md) / [oa/oa-overtime.md](oa/oa-overtime.md));其他审批先 `search-forms --query <关键词>` |
| 已拿到 `processCode` | 直接 `form-schema --process-code <code>` |
| 已拿到 Schema | 向用户展示控件列表,收集表单值 |
| 已收集表单值 | `forecast-process` 预测流程走向 |
| 预测返回有 `targetSelect: true` 节点 | 让用户为自选节点选人(经 aisearch person 解析姓名) |
| 预测完成,自选节点已选人 | 汇总确认后 `create-instance` |
| 用户明确说"不走模板流程,直接指定审批人" | 使用 `directAppointedApprovers`(高级模式) |
#### 工作流
```
1. search-forms --query <关键词> → 拿到 processCode(若已有则跳过)
2. form-schema --process-code <code> → 拿到控件列表、类型、选项值
3. 检查 Schema 中是否有不支持的必填控件 → 若有则直接告知用户不支持发起
4. 收集表单值 → 向用户展示控件列表,收集用户填写的表单值
5. forecast-process → 根据表单值预测流程走向,识别自选节点
6. 自选节点选人 → 若预测返回 targetSelect=true 的节点,让用户选人(经 aisearch person 解析姓名)
7. 汇总确认后 create-instance → 展示完整信息(表单值 + 流程路径 + 审批人),用户确认后执行发起
```
> **IMPORTANT:每次发起实例前都必须重新调用 `form-schema` 查询模板。** 即使用户之前查询过同一个 processCode,模板可能已被修改(控件增减、选项变更、必填属性调整等),不得复用旧的 Schema 结果。
#### 交互优化原则
> **核心目标:流程清晰,步骤有序,避免重复询问。**
1. **先查 Schema 再收集表单值(步骤 2→4):** `form-schema` 后先展示控件列表,再一次性收集全部表单值;未拿到 Schema 前不得问用户填什么。
2. **流程预测后再选自选审批人(步骤 5→6):** `forecast-process` 后先展示完整流程路径(各节点与处理人);对 `targetSelect: true` 节点提示「节点「{activityName}」需要您自选{actorType}人」,用 `dws aisearch person --query "<姓名>" --dimension name --format json` 帮用户查找并选人;多个自选节点一次性收集,禁止逐个询问。
3. **单次汇总确认(步骤 7):** 发起前一次性展示模板名称、各控件值、预测审批路径、各节点审批人/抄送人(含自选选人结果),并遵守:
- **单选确认**:一个单选问题(如「确认发起 / 取消发起」),完整汇总置于问题或选项描述中一并展示;附属决策(如非必填自选节点是否留空)须在确认前收集或按默认值并入汇总,禁止拆成多个并列问题。
- **零括号主干形态**:汇总主干只写字段名与核心值,禁止括号内描述——模板编码、userId、多选/服务端裁决/窗口类型/通道验收等技术细节不入正文,选项描述同样不加括号尾注(写「加 --yes 真实提交」不写「加 --yes 真实提交(服务端已验证)」);技术证据留档于命令字符串、临时文件或技术报告。示例:「模板:加班-new / 加班人:文疏、公 元yt / 时间:2026-09-01 21:00 → 23:00 / 时长:每人 2.00 小时」
- **空条目控件不进汇总**:汇总只展示有业务值的控件;服务端自动处理、以空条目组装的控件(如加班补偿自动配置)不展示该字段,技术结论需告知时另用说明句,不与表单值并列
4. **开放信息统一收集(请假/外出起止范围,请假/补卡/外出/加班事由):**
- **时间范围(请假与外出;补卡时刻由意图词与班次推导,不走此交互)**:按天计 → 日期即全天,无需此问;按半天/小时计且用户未限定上/下午/时刻时,问「全天 / 仅上午 / 仅下午」,按有效单位展示口径(小时计 → 全天 09:00→18:00、仅上午 09:00→12:00、仅下午 12:00→18:00;半天计 → 全天上午至下午、仅上午/仅下午),须保留自定义起止时刻通道;跨多天时起止日分别确定口径;选项时刻仅为示意,以用户实际班次为准;禁止默认全天。
- **事由/理由**:常见快捷选项 + **必须有自由输入通道**(不得只给选项变相预筛),命中即用、未命中自由输入。常见选项:请假(身体不适/家中有事/处理私事)、补卡(忘记打卡/考勤设备故障/外出办公未打卡)、外出(拜访客户/参加会议/外勤办事)、加班(赶项目进度/客户需求/临时任务)。
- **纯对话环境**(无选择组件):退化为文本提问并结束回合等用户输入,属合规模式;但半天/小时计的时间范围仍须明确问,禁止默认全天。
- **话术硬约束**:选项与提问一律纯中文,技术字段与英文枚举不进入用户可见文案。
5. **选择澄清优先(交互形态硬约束):** 凡有离散选项或预设取值的澄清与确认(模板、类型/班次、时间范围、加班逐日时长、事由等),宿主有选择交互组件时必须用**选择澄清**(快捷预设 + 「其他」自由输入),禁止退化为纯文本 `___` 填空;仅纯对话宿主才用文本提问。快捷预设只是加速项,不得变相预筛或替代用户裁决。
**反例(禁止):** 未查 Schema 就问表单值;预测后逐个节点询问选人;确认前直接发起;半天/小时计未问时间范围默认全天;发起确认拆成多个并列问题;汇总或选项描述夹带括号内技术描述(如「加班人(userId)」);宿主有选择组件时把时长/事由等离散澄清退化为纯文本填空。
```
Usage:
dws oa approval create-instance [flags]
Example:
# 简单发起(Agent 在汇总确认后需加 --yes)
dws oa approval create-instance --process-code PROC-xxx --form-values '{"单行输入框":"测试内容"}'
# 指定审批人(OR=或签,AND=会签,NONE=单人)
dws oa approval create-instance --process-code PROC-xxx --form-values '{"单行输入框":"测试"}' --approvers "userId1,userId2" --approvers-action-type OR
# 指定抄送人
dws oa approval create-instance --process-code PROC-xxx --form-values '{"单行输入框":"测试"}' --cc-list "userId1" --cc-position START
# 高级用法:传入完整 JSON(支持 directAppointedApprovers、targetSelectActioners 等全部字段)
dws oa approval create-instance --request '{"processCode":"PROC-xxx","deptId":-1,"formComponentValues":[{"name":"单行输入框","value":"测试"}]}'
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` **完全一致**。
- 如果用户提供的是人员信息,先经 aisearch person 按姓名解析为 userId 后再写入对应控件。
- 单选/多选控件提交的是选项文本(option value),该值从 `form-schema` 返回的选项定义中取得。
- `InnerContactField`、`DepartmentField`、`TableField`、`DDDateRangeField`、`DDAttachment` 等控件的 `value` 结构各不相同,必须按下方格式表单独组装,不要套用文本控件的写法。
- `TableField` 的 `value` 必须序列化为二维数组字符串,每行是子控件 `name/value` 对象数组;不是以子控件 label 为 key 的行对象数组。`--form-values` 只转换顶层字段映射,和 `--request` 一样原样传递该字符串,不转换明细内部结构。完整示例见 [TableField 控件说明](oa/oa-form-components.md#tablefield明细控件)。
- `TextNote`(文字说明)不收集数据,**不要**出现在 `formComponentValues` 中。
#### 表单控件值格式速查
> **重要:** `formComponentValues` 中每条记录的 `name` 必须与审批模板中控件的 `label`(即 `form-schema` 返回的 `content.items[].props.label`)**完全一致**。`value` 为字符串类型,最大 65535 字符。
>
> **详细参考:** 每种控件的完整属性、约束和示例见 [oa-form-components.md](oa/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` | 二维 name/value 数组的 JSON 字符串 | `'[[{"name":"子控件名","value":"值1"}],[{"name":"子控件名","value":"值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` 提交。示例:
>
> ```bash
> # 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 条 |
#### 节点参数组装
> **详细参考:** 流程节点类型、审批模式、条件分支和 11 种审批人选择规则的完整说明见 [oa-process-nodes.md](oa/oa-process-nodes.md)。
**directAppointedApprovers(指定审批人覆盖模板流程):**
当用户明确说"不走模板默认流程"或"直接指定 XX 审批"时使用。
```json
[
{
"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` 类型)时必填。
```json
[
{
"actionerKey": "manual_nodeId_xxxx_yyyy",
"actionerStaffIds": ["userId1"]
}
]
```
- `actionerKey`:自选节点的规则 key,可通过获取审批单流程节点信息接口获取 `actorKey`
- `actionerStaffIds`:操作人 **userId** 列表(userId 即员工工号,**不是员工 uid**——传 uid 短号会导致审批人节点异常,实测;姓名解析 userId 见上方执行摘要)
#### 表单控件约束
- 单个表单最多 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` 等操作。
### 套件发起工作流(独立文档)
四个考勤套件的发起工作流已拆分为独立文档(均不走 search-forms):
| 套件 | 触发意图 | 工作流文档 |
|---|---|---|
| 请假(DDHolidayField) | "请假/请X天假/请年假/请事假/请病假/提交请假" | [oa/oa-leave.md](oa/oa-leave.md) |
| 补卡(DDBizSuite · attendance.supply) | "补卡/忘打卡/补打卡/帮我补上次的卡" | [oa/oa-supply.md](oa/oa-supply.md) |
| 外出(DDBizSuite · attendance.goout) | "外出/公出/提交外出/帮我提外出申请" | [oa/oa-goout.md](oa/oa-goout.md) |
| 加班(DDBizSuite · attendance.batchovertime) | "加班/提交加班/帮我提加班申请/代XX提交加班"(无歧义窗口自算 + 歧义窗口两阶段,时长结果须经用户手动确认) | [oa/oa-overtime.md](oa/oa-overtime.md) |
出差仍按 attendance 域 `+get-approve-template` 的提交链接引导(`--type out`,与外出 `--type travel` 注意分流)。
### 获取审批任务的被催办人 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` → 电话提醒(有成本,需向用户确认)
**完整催办流程:**
```bash
# 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 (必填)
```
MCP 工具: `list_pending_tasks`。
### 查询我处理过的审批单
```
Usage:
dws oa approval list-executed [flags]
Example:
dws oa approval list-executed --limit <pageSize> --page <pageNumber> --query 关键词
Flags:
--page int / --limit int / --query string
--process-code / --originator-user-id string
--process-instance-status string
--create-time-from / --create-time-to string(yyyy-MM-dd)
--finish-time-from / --finish-time-to string(yyyy-MM-dd)
```
### 查询我已经提交的审批单
```
Usage:
dws oa approval list-submitted [flags]
Example:
dws oa approval list-submitted --limit <pageSize> --page <pageNumber> --query 关键词
Flags:
--page int / --limit int / --query string
--process-code / --originator-user-id string
--process-instance-status string
--create-time-from / --create-time-to string(yyyy-MM-dd)
--finish-time-from / --finish-time-to string(yyyy-MM-dd)
```
### 查询抄送我的审批单
```
Usage:
dws oa approval list-cc [flags]
Example:
dws oa approval list-cc --limit <pageSize> --page <pageNumber> --query 关键词
Flags:
--page int / --limit int / --query string
--process-code / --originator-user-id string
--create-time-from / --create-time-to string(yyyy-MM-dd)
--finish-time-from / --finish-time-to string(yyyy-MM-dd)
--unread-only bool 仅查询未读抄送审批
```
以上四类个人审批列表(list-pending / list-executed / list-submitted / list-cc)均使用当前登录身份;切换账号请使用全局 `--profile`,不支持通过 `--user-id` 覆盖当前用户。
### 以管理员身份查询审批实例列表
> **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 转交说明 (可选)
```
MCP 工具: `redirect_task`;参数: taskId, toActionerId, remark(对应 --task-id/--to-actioner-id/--remark)。taskId 可通过 `tasks` 命令获取,toActionerId 可通过 `dws contact user search` 获取。
### 对审批实例添加评论
```
Usage:
dws oa approval oa-comments [flags]
Example:
dws oa approval oa-comments --instance-id <processInstanceId> --content "同意,请尽快处理"
Flags:
--instance-id string 审批实例 ID (必填)
--content string 评论内容 (必填)
```
MCP 工具: `dingflow_comments`;参数: processInstanceId, text(对应 --instance-id/--content)。processInstanceId 可通过 `list-pending` 或 `detail` 获取。
### 对审批实例进行抄送
```
Usage:
dws oa approval oa-cc-noticer [flags]
Example:
dws oa approval oa-cc-noticer --instance-id <processInstanceId> --users "<userId>"
dws oa approval oa-cc-noticer --instance-id <processInstanceId> --users "userId1,userId2" --operator-id "123123"
Flags:
--instance-id string 审批实例 ID (必填)
--users string 抄送用户 ID 列表,多个用逗号分隔 (必填)
--operator-id string 操作人 ID (可选)
```
MCP 工具: `oa_cc_noticer`;参数: processInstanceId, userList(对应 --instance-id/--users)。processInstanceId 可通过 `list-pending` 或 `detail` 获取,抄送用户 ID 可通过 `dws contact user search` 获取。
### 对审批任务进行加签
> **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 string 是否需要全部同意 (必填) 是 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 退回说明 (可选)
```
## 意图判断
用户说"待审批/待处理审批" → `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 / search-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`
用户说"请假/请X天假/请年假/请事假/请病假/提交请假/帮我请假" → 请假套件工作流(见 [oa/oa-leave.md](oa/oa-leave.md)):`dws attendance +get-approve-template --type leave` 定位模板(不走 search-forms),后续按套件文档执行
用户说"补卡/忘打卡/补打卡/帮我补上次的卡" → 补卡套件工作流(见 [oa/oa-supply.md](oa/oa-supply.md)):`dws attendance +get-approve-template --type repair-check` 定位模板(不走 search-forms),后续按套件文档执行
用户说"外出/公出/提交外出/帮我提外出申请" → 外出套件工作流(见 [oa/oa-goout.md](oa/oa-goout.md)):`dws attendance +get-approve-template --type travel` 定位模板(不走 search-forms;出差是 --type out,注意分流),后续按套件文档执行
用户说"加班/提交加班/帮我提加班申请/代XX提交加班" → 加班套件工作流(见 [oa/oa-overtime.md](oa/oa-overtime.md)):`dws attendance +get-approve-template --type overtime` 定位模板(不走 search-forms);无歧义窗口自算 + 歧义窗口两阶段,时长结果须经用户手动确认,后续按套件文档执行
用户说"发起审批/提交审批/帮我发起XX审批/新建审批单/提一个XX审批/帮我提XX申请" → 五步流程:① `search-forms --query XX` 获取 processCode(请假/补卡/外出除外,见上方条目)→ ② `form-schema --process-code <code>` 获取表单字段定义 → ③ 阅读 [oa-form-components.md](oa/oa-form-components.md) 和 [oa-process-nodes.md](oa/oa-process-nodes.md) 后组装表单值 → ④ `forecast-process` 预测流程走向并识别自选节点 → ⑤ 若有自选节点让用户选人,确认后 `create-instance` 发起
- 如果用户已知 processCode,可跳过第①步
- `--form-values` 的 key 必须与 `form-schema` 返回的控件 label 一致
- `forecast-process` 返回自选节点时必须让用户选人,不得跳过
- 执行前**必须向用户确认**表单内容、流程预测结果、审批人和抄送人
- 示例:"帮我发起一个AI审批单" → ① `search-forms --query AI` → ② `form-schema --process-code <code>` → ③ 组装表单值 → ④ `forecast-process` → ⑤ 向用户确认流程走向和自选审批人后 `create-instance`
用户说"我有哪些待审的任务" → `approval tasks`
用户说"我发起的审批单" -> `approval list-submitted`
用户说"我审批/处理过的审批单" -> `approval list-executed`
用户说"抄送我的审批单" -> `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)
## 核心工作流
```bash
# 1. 查看待我处理的审批 — 提取 processInstanceId
dws oa approval list-pending --create-time-from 2026-03-10 --create-time-to 2026-03-10 --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. 同意审批(先向用户确认,同意后加 --yes 执行)
dws oa approval approve --instance-id <id> --task-id <taskId> --remark "同意" --yes --format json
# 4b. 拒绝审批(先向用户确认,同意后加 --yes 执行)
dws oa approval reject --instance-id <id> --task-id <taskId> --remark "不符合要求" --yes --format json
# 5. 撤销自己发起的审批(高危;非交互环境不带 --yes 会 confirmation_required 失败)
dws oa approval revoke --instance-id <id> --remark "误发起" --yes --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 / search-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 来自 contact user search)
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> --users "<userId>" --format json
dws oa approval oa-cc-noticer --instance-id <processInstanceId> --users "userId1,userId2" --format json
# 15. 发起审批(完整流程:搜表单 → 查 Schema → 收集表单值 → 流程预测 → 自选节点选人 → 发起)
# 15a. 模糊搜索表单获取 processCode
dws oa approval search-forms --query AI --format json
# 15b. 查询表单 Schema 获取字段定义
dws oa approval form-schema --process-code <code> --format json
# 15c. 收集表单值(向用户展示控件列表,用户填写后组装 form-values)
# 15d. 流程预测(根据表单值预测审批走向,识别自选审批人节点;processCode/deptId/formValues 必填,userId 由登录态自动填充)
dws oa approval forecast-process --process-code <code> --dept-id -1 --form-values '{"单行输入框":"测试内容"}' --format json
# 15e. 若 forecast 返回 targetSelect=true 的节点,经 aisearch person 解析姓名帮用户选人
# 15f. 发起审批实例(form-values 的 key 须与 Schema 中控件 label 一致)
dws oa approval create-instance --process-code <code> --form-values '{"单行输入框":"测试内容"}' --format json
# 15g. 发起并指定审批人和抄送人
dws oa approval create-instance --process-code <code> --form-values '{"单行输入框":"测试"}' --approvers "userId1,userId2" --approvers-action-type OR --cc-list "userId3" --cc-position START --format json
# 15h. 发起并使用 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"]}]}' --format json
# 16. 套件发起(请假/补卡/外出/加班):各套件工作流见上方「套件发起工作流(独立文档)」指针表
```
## 上下文传递表
| 操作 | 从返回中提取 | 用于 |
|------|-------------|------|
| `list-pending` | `processInstanceId` | detail / tasks / records / revoke / oa-comments / oa-cc-noticer 的 --instance-id |
| `tasks` | `taskId` | approve / reject / redirect-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,可跟踪已发起的审批 |
| `list-by-admin` | `processInstanceId` | detail / records / tasks 的 --instance-id |
## 注意事项
- `list-pending` 使用 `--create-time-from/to`、`--finish-time-from/to` 日期筛选,格式为 `yyyy-MM-dd`;不再接受旧 `--start` / `--end`
- `list-initiated` / `list-by-admin` 的 `--start` / `--end` 仍使用 ISO-8601 格式(如 2026-03-10T00:00:00+08:00)
- `approve` / `reject` / `redirect-task` 需先通过 `tasks` 获取 `taskId`
- `redirect-task` 的 `--to-actioner-id` 可通过 `dws contact user search` 获取目标用户 userId
- `revoke` 只能撤销自己发起的审批
- `--remark` 审批意见虽为可选,但建议填写以留存审批痕迹
- `list-initiated` 的 `--process-code` 可从 `list-forms`、`search-forms` 或 `detail` 返回中提取。当 `list-forms` 返回 `processCodeList` 为空(`totalCount -1`)时,用 `search-forms --query <表单名>`(如 `--query 报销`)按名称精准拿 `processCode` 更稳
- `list-initiated` 的 `--start` / `--end` 区间有后端上限(约 120 天)。超过上限会返回误导性的 `business_error: 时间戳无效`(实为区间过长,不是时间格式问题)。跨度大时请拆成多段短区间分别查询
- `list-by-admin` 需要当前用户具备 OA 审批管理员权限,否则查不到数据;只查个人维度审批时改用 `list-pending` / `list-executed` / `list-initiated` / `list-cc`。高级模式 `--request` 中 `startTime`/`endTime` 为 `yyyy-MM-dd HH:mm:ss` 格式字符串(不再接受毫秒时间戳);`pageSize` 上限为 20,超过会报错(简单模式为 `--limit`)
## 自动化脚本
| 脚本 | 场景 | 用法 |
|------|------|------|
| [oa_pending_review.py](../../scripts/oa_pending_review.py) | 查看待审批列表+逐条显示详情 | `python3 oa_pending_review.py --days 7` |
| [oa_batch_approve.py](../../scripts/oa_batch_approve.py) | 批量同意/拒绝审批项。**确认语义**:不带 `--yes` 且非 `--dry-run` 时脚本会 `input()` 交互确认——Agent 非交互环境(stdin 非 TTY)裸跑会 `EOFError`,必须先向用户确认、同意后加 `--yes` 执行;`--dry-run` 仅预览命令不执行 | `python3 oa_batch_approve.py --action approve --days 7 --yes` |
> 单命令速查形态(每命令一条 Usage/Example,无说明文字)见 [simple.md](./simple.md);完整口径(Flags 全列、错误处理、脚本语义)以本文件为准。
### 创建和更新模板路由
用户要创建或更新审批模板时,继续读取 [oa-template-write.md](oa-template-write.md)。不要凭本文件直接组装 `--schema-content` 或 `--process-config`。
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 |