Skip to content

Pinvou/pinvou-agent / pinvou3-app/src-tauri/resources/common/bundle/dingtalk-skills/dws

【何时用:仅当用户明确指向钉钉/DingTalk(钉钉文档、钉钉日程等)时使用;泛指做文档/表格/待办/审批默认走本地工具,不要误用钉钉】用 dws CLI 管理钉钉:AI表格/AI搜问(找人首选)/目标管理(Agoal)/组织大脑/日历/通讯录/群聊与机器人消息/待办/审批/智能合同/考勤/日志(日报周报)/DING消息/钉钉文档/云盘/Markdown文件/HTML文件/AI听记/邮箱/在线电子表格(axls)/知识库/白板/开放平台文档/个人IM与OA事件订阅。用户要求操作上述钉钉产品时使用。

FileKindSize
LICENSEother9.9 KB
NOTICEother666 B
SKILL.mdskill md38.4 KB
references/best_practices/01-messaging.mdmarkdown3.2 KB
references/best_practices/02-task.mdmarkdown2.8 KB
references/best_practices/03-meeting.mdmarkdown11.6 KB
references/best_practices/04-document.mdmarkdown11.0 KB
references/best_practices/05-reporting.mdmarkdown6.2 KB
references/best_practices/06-data-analytics.mdmarkdown5.4 KB
references/best_practices/07-minutes.mdmarkdown8.3 KB
references/best_practices/08-directory.mdmarkdown8.0 KB
references/best_practices/09-mail.mdmarkdown5.2 KB
references/best_practices/10-minutes-speaker-match.mdmarkdown9.0 KB
references/best_practices/11-minutes-speaker-correct.mdmarkdown4.4 KB
references/best_practices/_common/conventions.mdmarkdown3.4 KB
references/best_practices/_common/recipe-conventions.mdmarkdown1.8 KB
references/best_practices/lite-recipes.mdmarkdown15.7 KB
references/capability-limits.mdmarkdown2.9 KB
references/error-codes.mdmarkdown4.0 KB
references/field-rules.mdmarkdown5.4 KB
references/global-reference.mdmarkdown5.1 KB
references/intent-guide.mdmarkdown47.8 KB
references/products/agoal.mdmarkdown12.1 KB
references/products/aisearch.mdmarkdown14.1 KB
references/products/aitable-record-ops.mdmarkdown4.8 KB
references/products/aitable.mdmarkdown30.1 KB
references/products/aitable/aitable-advperm.mdmarkdown10.2 KB
references/products/aitable/aitable-api-key.mdmarkdown1.7 KB
references/products/aitable/aitable-attachment.mdmarkdown3.5 KB
references/products/aitable/aitable-best-practices.mdmarkdown3.5 KB
references/products/aitable/aitable-cell-value.mdmarkdown9.1 KB
references/products/aitable/aitable-comment.mdmarkdown2.8 KB
references/products/aitable/aitable-dashboard-chart.mdmarkdown4.5 KB
references/products/aitable/aitable-data-analysis-sop.mdmarkdown5.6 KB
references/products/aitable/aitable-error-recovery.mdmarkdown6.9 KB
references/products/aitable/aitable-export-import.mdmarkdown9.8 KB
references/products/aitable/aitable-field-properties.mdmarkdown8.5 KB
references/products/aitable/aitable-field.mdmarkdown6.6 KB
references/products/aitable/aitable-filter-sort.mdmarkdown12.4 KB
references/products/aitable/aitable-form.mdmarkdown15.1 KB
references/products/aitable/aitable-formula-guide.mdmarkdown8.2 KB
references/products/aitable/aitable-primary-doc.mdmarkdown2.3 KB
references/products/aitable/aitable-psql.mdmarkdown14.7 KB
references/products/aitable/aitable-record-create.mdmarkdown2.2 KB
references/products/aitable/aitable-record-delete.mdmarkdown582 B
references/products/aitable/aitable-record-history.mdmarkdown4.0 KB
references/products/aitable/aitable-record-name-key.mdmarkdown2.4 KB
references/products/aitable/aitable-record-query.mdmarkdown15.0 KB
references/products/aitable/aitable-record-share.mdmarkdown1.6 KB
references/products/aitable/aitable-record-stats.mdmarkdown3.8 KB
references/products/aitable/aitable-record-update.mdmarkdown3.2 KB
references/products/aitable/aitable-record-upsert.mdmarkdown3.3 KB
references/products/aitable/aitable-view-config.mdmarkdown11.8 KB
references/products/aitable/aitable-view-extras.mdmarkdown8.0 KB
references/products/aitable/aitable-workflow.mdmarkdown14.4 KB
references/products/attendance-report.mdmarkdown29.9 KB
references/products/attendance-schedule.mdmarkdown27.5 KB
references/products/attendance-vacation.mdmarkdown9.4 KB
references/products/attendance.mdmarkdown102.0 KB
references/products/calendar.mdmarkdown50.3 KB
references/products/chat-emoji-list.mdmarkdown8.4 KB
references/products/chat.mdmarkdown158.3 KB
references/products/chat/a2ui.mdmarkdown4.2 KB
references/products/contact.mdmarkdown30.5 KB
references/products/contract.mdmarkdown15.2 KB
references/products/dev.mdmarkdown14.7 KB
references/products/devdoc.mdmarkdown1.8 KB
references/products/ding.mdmarkdown9.9 KB
references/products/dingtalk-tag/capability.mdmarkdown5.7 KB
references/products/dingtalk-tag/dingtalk-tag-index.mdmarkdown3.9 KB
references/products/dingtalk-tag/manage-and-connect.mdmarkdown8.2 KB
references/products/dingtalk-tag/manage.mdmarkdown9.7 KB
references/products/dingtalk-tag/run.mdmarkdown5.4 KB
references/products/doc.mdmarkdown65.2 KB
references/products/doc/doc-block.mdmarkdown14.6 KB
references/products/doc/doc-comment.mdmarkdown9.9 KB
references/products/doc/doc-create.mdmarkdown6.6 KB
references/products/doc/doc-export.mdmarkdown3.5 KB
references/products/doc/doc-file-ops.mdmarkdown9.4 KB
references/products/doc/doc-import.mdmarkdown2.8 KB
references/products/doc/doc-info.mdmarkdown9.9 KB
references/products/doc/doc-list.mdmarkdown1.3 KB
references/products/doc/doc-media.mdmarkdown4.7 KB
references/products/doc/doc-permission.mdmarkdown4.9 KB
references/products/doc/doc-read.mdmarkdown8.5 KB
references/products/doc/doc-search.mdmarkdown1.4 KB
references/products/doc/doc-update.mdmarkdown15.5 KB
references/products/doc/doc-whiteboard.mdmarkdown3.9 KB
references/products/doc/format/doc-jsonml-cookbook.mdmarkdown25.0 KB
references/products/doc/format/doc-jsonml-schema.jsonconfig16.5 KB
references/products/doc/format/doc-jsonml-schema.mdmarkdown29.1 KB
references/products/doc/style/doc-create-workflow.mdmarkdown23.1 KB
references/products/doc/style/doc-style-guideline.mdmarkdown21.1 KB
references/products/doc/style/doc-update-workflow.mdmarkdown16.4 KB
references/products/drive.mdmarkdown65.4 KB
references/products/drive/drive-export.mdmarkdown2.6 KB
references/products/drive/drive-storage.mdmarkdown2.1 KB
references/products/drive/drive-task.mdmarkdown2.4 KB
references/products/event.mdmarkdown29.7 KB
references/products/hrbrain.mdmarkdown7.5 KB
references/products/html.mdmarkdown6.4 KB
references/products/mail.mdmarkdown88.1 KB
references/products/markdown.mdmarkdown11.4 KB
references/products/minutes.mdmarkdown173.8 KB
references/products/oa-template-write.mdmarkdown8.1 KB
references/products/oa.mdmarkdown61.7 KB
references/products/oa/oa-form-components.mdmarkdown33.7 KB
references/products/oa/oa-goout.mdmarkdown7.5 KB
references/products/oa/oa-leave.mdmarkdown7.2 KB
references/products/oa/oa-overtime.mdmarkdown10.1 KB
references/products/oa/oa-process-nodes.mdmarkdown11.6 KB
references/products/oa/oa-supply.mdmarkdown6.2 KB
references/products/oa/template/components/AddressField.mdmarkdown718 B
references/products/oa/template/components/CalculateField.mdmarkdown2.0 KB
references/products/oa/template/components/CascadeField.mdmarkdown1.1 KB
references/products/oa/template/components/ColumnLayout.mdmarkdown746 B
references/products/oa/template/components/DDAttachment.mdmarkdown586 B
references/products/oa/template/components/DDDateField.mdmarkdown857 B
references/products/oa/template/components/DDDateRangeField.mdmarkdown1.6 KB
references/products/oa/template/components/DDMultiSelectField.mdmarkdown1.3 KB
references/products/oa/template/components/DDPhotoField.mdmarkdown699 B
references/products/oa/template/components/DDSelectField.mdmarkdown1.2 KB
references/products/oa/template/components/DepartmentField.mdmarkdown789 B
references/products/oa/template/components/ExternalContactField.mdmarkdown751 B
references/products/oa/template/components/FormRelateField.mdmarkdown2.1 KB
references/products/oa/template/components/IdCardField.mdmarkdown709 B
references/products/oa/template/components/InnerContactField.mdmarkdown819 B
references/products/oa/template/components/InvoiceField.mdmarkdown1.1 KB
references/products/oa/template/components/MoneyField.mdmarkdown811 B
references/products/oa/template/components/NumberField.mdmarkdown807 B
references/products/oa/template/components/OcrIdCardField.mdmarkdown1.7 KB
references/products/oa/template/components/OcrTextField.mdmarkdown900 B
references/products/oa/template/components/PhoneField.mdmarkdown760 B
references/products/oa/template/components/RecipientAccountField.mdmarkdown746 B
references/products/oa/template/components/RelateField.mdmarkdown804 B
references/products/oa/template/components/SeqNumberField.mdmarkdown1.1 KB
references/products/oa/template/components/SignatureField.mdmarkdown722 B
references/products/oa/template/components/StarRatingField.mdmarkdown774 B
references/products/oa/template/components/TableField.mdmarkdown1.2 KB
references/products/oa/template/components/TextField.mdmarkdown775 B
references/products/oa/template/components/TextNote.mdmarkdown675 B
references/products/oa/template/components/TextareaField.mdmarkdown754 B
references/products/oa/template/components/TimeAndLocationField.mdmarkdown719 B
references/products/oa/template/example/form_components.jsonconfig7.3 KB
references/products/oa/template/example/process_config.jsonconfig22.7 KB
references/products/oa/template/form-components.mdmarkdown11.5 KB
references/products/oa/template/nodes/approver.mdmarkdown3.7 KB
references/products/oa/template/nodes/cc.mdmarkdown2.6 KB
references/products/oa/template/nodes/condition.mdmarkdown10.8 KB
references/products/oa/template/nodes/handler.mdmarkdown2.4 KB
references/products/oa/template/nodes/originator.mdmarkdown941 B
references/products/oa/template/nodes/parallel.mdmarkdown2.7 KB
references/products/oa/template/nodes/payer.mdmarkdown1.6 KB
references/products/oa/template/process-nodes.mdmarkdown8.8 KB
references/products/oa/template/rules/target_approval.mdmarkdown3.3 KB
references/products/oa/template/rules/target_connect_approval.mdmarkdown3.2 KB
references/products/oa/template/rules/target_formcomponent_approval.mdmarkdown1.2 KB
references/products/oa/template/rules/target_formula_managerOfDept.mdmarkdown1.5 KB
references/products/oa/template/rules/target_formula_reportLineManager.mdmarkdown1.5 KB
references/products/oa/template/rules/target_label.mdmarkdown3.9 KB
references/products/oa/template/rules/target_management.mdmarkdown1.3 KB
references/products/oa/template/rules/target_managers_labels.mdmarkdown1.3 KB
references/products/oa/template/rules/target_matrix_approval.mdmarkdown2.4 KB
references/products/oa/template/rules/target_originator.mdmarkdown698 B
references/products/oa/template/rules/target_select.mdmarkdown1.6 KB
references/products/openapi-explorer.mdmarkdown3.9 KB
references/products/pat.mdmarkdown1.8 KB
references/products/report.mdmarkdown29.9 KB
references/products/sheet.mdmarkdown16.2 KB
references/products/sheet/sheet-batch-operations.mdmarkdown7.7 KB
references/products/sheet/sheet-chart.mdmarkdown3.9 KB
references/products/sheet/sheet-comment.mdmarkdown7.9 KB
references/products/sheet/sheet-conditional-format.mdmarkdown4.5 KB
references/products/sheet/sheet-dimension-operations.mdmarkdown3.7 KB
references/products/sheet/sheet-dropdown.mdmarkdown6.7 KB
references/products/sheet/sheet-export.mdmarkdown8.6 KB
references/products/sheet/sheet-filter-view.mdmarkdown3.7 KB
references/products/sheet/sheet-filter.mdmarkdown10.0 KB
references/products/sheet/sheet-formula.mdmarkdown10.0 KB
references/products/sheet/sheet-import.mdmarkdown2.6 KB
references/products/sheet/sheet-media-image.mdmarkdown13.9 KB
references/products/sheet/sheet-pivot-table.mdmarkdown12.6 KB
references/products/sheet/sheet-range-operations.mdmarkdown8.7 KB
references/products/sheet/sheet-read-data.mdmarkdown4.0 KB
references/products/sheet/sheet-revision-changeset.mdmarkdown3.2 KB
references/products/sheet/sheet-search-replace.mdmarkdown6.3 KB
references/products/sheet/sheet-style-format.mdmarkdown4.5 KB
references/products/sheet/sheet-version.mdmarkdown5.0 KB
references/products/sheet/sheet-workbook.mdmarkdown4.3 KB
references/products/sheet/sheet-write-data.mdmarkdown7.8 KB
references/products/simple.mdmarkdown2.6 KB
references/products/todo.mdmarkdown21.0 KB
references/products/whiteboard.mdmarkdown19.7 KB
references/products/whiteboard/compose.mdmarkdown5.7 KB
references/products/whiteboard/diff.mdmarkdown3.7 KB
references/products/whiteboard/open-nodes-v1.mdmarkdown4.0 KB
references/products/whiteboard/open-nodes-v1/01-overview.mdmarkdown3.3 KB
references/products/whiteboard/open-nodes-v1/02-query.mdmarkdown7.3 KB
references/products/whiteboard/open-nodes-v1/03-update.mdmarkdown8.6 KB
references/products/whiteboard/open-nodes-v1/04-text-style.mdmarkdown11.8 KB

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`。
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall