larksuite/cliContrôle réussi
SKILL DETAIL
lark-approval
larksuite/cli/lark-approval
This skill handles Lark approval operations, including querying and processing approval tasks, done tasks, and instances; searching startable approval definitions; viewing definition details; and initiating native approval instances. Use it when users need to handle approval tasks, view approval instances, search or initiate approvals. Approval tasks are not Lark tasks; non-approval tasks should use lark-task. This skill does not create approval definitions; third-party approval definitions do not use native initiation. Key capabilities include: searching startable approval definitions, viewing approval definition details, initiating native approval instances, querying pending/done tasks, viewing forms/progress/current nodes, approving/rejecting/transferring/adding sign/rolling back/reminding approvals, canceling initiated approvals, and adding CC to approval instances.
Installations · 507Voir la source
Installation
npx skills add https://github.com/larksuite/cli --skill lark-approval
Fichiers du skill
SKILL.md
Dernière synchronisation · 29 août 2026
references/lark-approval-approvals-get.md›
# approval approvals get
获取单个审批定义详情（用户级只读操作）。适合在发起审批实例前，先确认审批名称、表单控件结构、选项值范围以及流程节点信息。
需要的 scopes: ["approval:approval:read"]
## 命令
```bash
# 按 approval_code 查询审批定义详情
lark-cli approval approvals get --params '{"approval_code":"<APPROVAL_CODE>"}' --as user
# 表格格式输出，便于快速浏览顶层字段
lark-cli approval approvals get --params '{"approval_code":"<APPROVAL_CODE>"}' --format table --as user
# 预览 API 调用，不执行
lark-cli approval approvals get --params '{"approval_code":"<APPROVAL_CODE>"}' --as user --dry-run
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--params '{...}'` | 是 | 查询参数，使用 JSON 传入 |
| `approval_code` | 是 | 审批定义 Code；通常来自 `approval approvals search` 的结果 |
| `locale` | 否 | 返回语言，例如 `zh-CN`、`en-US`、`ja-JP` |
| `--as user` | 否 | 建议显式指定用户身份；审批定义详情通常按当前用户可见范围读取 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 常见输入来源
如果你已经有 `approval_code`，可直接查询：
```bash
lark-cli approval approvals get --params '{"approval_code":"<APPROVAL_CODE>"}' --as user
```
如果你还没有 `approval_code`，先搜索可发起审批定义：
```bash
lark-cli approval approvals search --data '{"keyword":"请假"}' --as user
```
## 输出重点字段
返回结果中，优先关注以下字段：
| 字段 | 说明 |
|------|------|
| `approval_code` | 审批定义 Code |
| `approval_name` | 审批定义名称；确认是不是用户想发起的那张单 |
| `form` | 表单定义快照；用于识别控件 `id`、`type`、选项值范围、明细子控件结构 |
| `node_list` | 流程节点列表；用于识别节点 key、是否需要补充审批人、是否允许多人 |
## form 的使用重点
`form` 最重要的作用是帮助 agent **识别怎么组装 `instances.create.data.form`**，而不是直接把它原样提交出去。
重点看：
| 字段 / 结构 | 说明 |
|------|------|
| `form[].id` | 控件 ID；后续创建实例时必须使用 |
| `form[].type` | 控件类型，例如 `input`、`date`、`radio`、`checkbox`、`fieldList` |
| `form[].value` / 选项定义 | 用来识别可选值范围、默认值或选项值 |
| 明细 / 子控件结构 | 用于识别 `fieldList`、控件组等复杂控件的子字段结构 |
**注意：`approvals.get.form` 不是 `instances.create` 可直接复用的 payload 模板。** 它是“定义快照”，主要用于识别字段结构与选项值范围。
## node_list 的使用重点
`node_list` 主要用于后续决定是否要补 `node_approver_list` / `node_cc_list`。
重点看：
| 字段 | 说明 |
|------|------|
| `node_list[].custom_node_id` | 自定义节点标识；后续补节点参数时优先作为 key |
| `node_list[].node_id` | 节点 ID；若没有 `custom_node_id`，通常退回用它做 key |
| `node_list[].need_approver` | 是否要求发起人补充审批人 |
| `node_list[].approver_chosen_multi` | 是否允许为该节点选择多个审批人 |
## 使用建议
- **这是发起原生审批实例前的必要只读步骤。** 推荐固定走：`approvals search` -> `approvals get` -> `instances create`。
- **如果用户已经明确给了 `approval_code`，直接用这个命令。** 不必再走 `approvals search`。
- **先确认 `approval_name`。** 避免把相似名称的审批定义搞混。
- **先用 `form` 识别控件结构，再组装创建 payload。** 不要在未看详情时猜控件 `id`、`type` 或选项值。
- **先用 `node_list` 看是否需要补审批人。** 若某节点 `need_approver=true`，创建实例时通常要补 `node_approver_list`。
- **`node_list` 的 key 优先取 `custom_node_id`。** 若不存在，再使用 `node_id`。
- **`approver_chosen_multi=false` 时，一个节点通常只能补一个审批人。**
## 输出与后续操作
读取定义详情后，常见下一步：
```bash
# 发起原生审批实例
lark-cli approval instances create --data '{"approval_code":"<APPROVAL_CODE>","form":"[...]"}' --as user --yes
```
如果需要进一步理解控件取值与节点参数，优先参考：
- `lark-approval-instance-form-control-parameters.md`
- `lark-approval-instance-value-sourcing.md`
- `lark-approval-initiate.md`
## 结果整理方式
**将结果整理为“审批定义概览 + 表单结构摘要 + 节点要求摘要”。**
建议输出成下面这种结构：
```text
审批定义：请假申请
approval_code: 7C468A54-8745-2245-9675-08B7C63E7A85
表单控件摘要：
- leave_type: radio，可选值 [annual_leave, sick_leave]
- reason: textarea
- start_end: dateInterval
节点要求摘要：
- manager_node：need_approver=true，approver_chosen_multi=false
- hr_node：need_approver=false
```
references/lark-approval-approvals-search.md›
# approval approvals search
搜索**当前用户可发起**的审批定义（launchable approvals）。只读操作，不会创建审批实例。
需要的 scopes: ["approval:approval:read"]
## 命令
```bash
# 按关键词搜索可发起审批定义
lark-cli approval approvals search --data '{"keyword":"请假"}' --as user
# 使用 page_token 翻页
lark-cli approval approvals search --data '{"keyword":"请假", "page_token":"example_page_token"}' --as user
# 表格格式输出，便于快速浏览候选定义
lark-cli approval approvals search --data '{"keyword":"出差"}' --format table --as user
# 预览 API 调用，不执行
lark-cli approval approvals search --data '{"keyword":"请假"}' --as user --dry-run
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--data '{...}'` | 是 | 查询参数，使用 JSON 传入 |
| `keyword` | 是 | 搜索关键词，例如 `请假`、`报销`、`出差`、`采购` |
| `locale` | 否 | 返回语言，例如 `zh-CN`、`en-US`、`ja-JP` |
| `page_size` | 否 | 分页大小 |
| `page_token` | 否 | 翻页标记；首次请求不填，后续使用上一次返回的 `page_token` |
| `--as user` | 否 | 建议显式指定用户身份；“可发起审批定义”是面向当前用户的查询 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 这个命令解决什么问题
当用户只有自然语言意图，还没有 `approval_code` 时，先用它把“可发起的审批定义候选项”找出来。
典型场景：
- “帮我找一下请假审批”
- “有哪些可以发起的报销单？”
- “先搜一下出差审批，再帮我提单”
## 输出重点字段
返回结果里，优先关注以下字段：
| 字段 | 说明 |
|------|------|
| `approval_code` | 审批定义 Code；后续 `approvals get` 和 `instances create` 都要用它 |
| `approval_name` | 审批定义名称；给用户做候选选择时最关键 |
| `is_external` | 是否为三方审批定义；`true` 表示不能走原生 `instances.create` |
| `create_link` | 三方审批定义的发起链接；`is_external=true` 时优先返回给用户 |
## 使用规则
- **这是发起审批工作流的第一步。** 标准顺序是：`approvals search` -> `approvals get` -> `instances create`。
- **搜索结果为空时，不要猜。** 直接告诉用户当前关键词下没有可发起定义，并建议用户换关键词。
- **命中多个结果时，不要替用户拍板。** 先把候选定义列出来，让用户选择目标审批定义。
- **`is_external=true` 时不要调用 `approval instances create`。** 这类定义属于三方审批，优先返回 `create_link` 并说明需要通过链接发起。
- **只有 `is_external=false` 的原生定义，才继续 `approvals get`。**
- **如果用户已经明确给出 `approval_code`，不要再 search。** 直接执行 `approval approvals get`。
## 结果整理方式
**将结果整理为候选清单，优先展示“名称 + approval_code + 是否三方定义 + 下一步建议”。**
建议输出成下面这种结构：
```text
找到 3 个可发起审批定义：
1. 请假申请
- approval_code: 7C468A54-8745-2245-9675-08B7C63E7A85
- is_external: false
- next: 可继续读取 definitions 详情（approvals get）
2. 差旅报销
- approval_code: 99887766-xxxx
- is_external: true
- next: 返回 create_link，引导用户通过链接发起
```
## 常见后续操作
### 1）用户选中了某个定义，继续查看详情
```bash
lark-cli approval approvals get --params '{"approval_code":"<APPROVAL_CODE>"}' --as user
```
### 2）确认是原生定义后，再准备发起审批实例
```bash
lark-cli approval instances create --data '{"approval_code":"<APPROVAL_CODE>","form":"[...]"}' --as user --yes
```
### 3）确认是三方定义时，直接返回链接
当 `is_external=true` 时，优先向用户返回 `create_link`，说明该审批需在三方系统或跳转页面中发起，而不是通过原生 `instances.create`。
references/lark-approval-initiate.md›
# 审批提单工作流
## 执行摘要
- **原生审批提单如果用户未明确给出 `approval_code`，必须固定走 `approvals search` -> `approvals get` -> `instances create`** 不要跳过 `get` 直接拼请求。
- **原生审批提单如果用户明确给出 `approval_code`，固定走 `approvals get` -> `instances create`** 不要跳过 `get` 直接拼请求。
- **`is_external=true` 的定义是三方定义。** 这类定义不要调用 `instances create`，应优先使用 `create_link`。
- **所有人员类参数默认使用 `open_id`。** 若用户给的是姓名、邮箱或其他身份，先用 [`../../lark-contact/SKILL.md`](../../lark-contact/SKILL.md) 解析。
- **先读控件参数 reference 和值来源 reference，再读本文里的创建参数规则。** 提单前必须先阅读 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 和 [`lark-approval-instance-value-sourcing.md`](./lark-approval-instance-value-sourcing.md)。
- **`approvals.get.form` 不是创建 payload 的原样模板。** 它主要用于识别控件 `id`、`type`、选项值范围和明细子控件结构；真正的 `instances create --data.form` 中，控件 `value` 结构以 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 为准。
- **节点参数只从 `node_list` 和本文里的节点参数规则里取。** 节点 key 必须来自定义详情返回的节点标识；审批人/抄送人列表传用户 ID 时，不要混用姓名或其他身份标识。
- **看到 `need_approver=true` 就说明该节点需要发起人补充审批人。** 如果 `approver_chosen_multi=false`，该节点只允许一个 `open_id`。
- **创建实例前先确认。** `approval instances create` 是写操作，执行前，让用户确认最终定义、表单值和节点参数；真正执行时显式传 `--yes`。
## 适用场景
- “帮我提交一个请假审批”
- “帮我发起报销审批”
- “我想提一个出差审批”
- “先搜可发起的审批，再帮我提单”
## 严禁行为
- **严禁在未先阅读本文中的创建参数规则、[`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 和 [`lark-approval-instance-value-sourcing.md`](./lark-approval-instance-value-sourcing.md) 的情况下直接提单。**
- **严禁跳过 `approvals.get`。** 未拿到 `form` 和 `node_list` 前，不得调用 `instances create`。
- **严禁把姓名直接写进 `node_approver_list`、`node_cc_list` 或表单人员控件。** 必须先转成 `open_id`。
- **严禁对三方定义调用 `instances create`。**
- **严禁对 API 不支持的控件硬提单。** 如果目标定义包含创建实例 API 不支持的控件，应明确告诉用户该定义不能仅通过 API 完整发起。
- **严禁把 `approvals.get.form` 当成可直接提交的原样模板。**
- **严禁在未得到用户确认前直接执行真实提单。**
## 工作流
### 1. 搜索可发起审批定义
先搜索定义：
```bash
lark-cli approval approvals search --data '{"keyword":"请假"}'
```
处理规则：
- 若结果为空，告诉用户当前关键词下没有可发起定义。
- 若命中多个定义，必须把候选项列给用户选择，不要自行猜测。
- 若目标定义 `is_external=true`，优先返回 `create_link`，说明这是三方定义，不能走原生 `instances create`。
- 只有 `is_external=false` 的原生定义才继续下一步。
### 2. 获取审批定义详情
拿到 `approval_code` 后，读取定义详情：
```bash
lark-cli approval approvals get \
--params '{"approval_code":"7C468A54-8745-2245-9675-08B7C63E7A85"}'
```
重点关注返回：
- `approval_name`: 当前发起的是哪个审批定义。
- `form`: 表单定义快照，用于识别控件 `id`、`type`、选项值范围以及明细子控件结构；不是创建实例时可直接原样提交的 payload 模板。
- `node_list`: 流程节点信息，是后续 `node_approver_list` / `node_cc_list` 的唯一可靠来源。
### 3. 创建请求参数速查
输入参数如下：
| 参数 | 必填 | 说明 |
|---|---|---|
| `--data '{...}'` | 是 | 请求体，使用 JSON 传入 |
| `approval_code` | 是 | 审批定义 Code；必须先通过 `approvals search` / `approvals get` 确认 |
| `form` | 否 | 表单值，**JSON 数组字符串**，不是普通对象；API 层非必填，但审批定义存在必填控件或用户需要提交表单值时必须传 |
| `node_approver_list` | 否 | 节点审批人列表；仅在定义要求补充审批人时传 |
| `node_cc_list` | 否 | 节点抄送人列表；仅在用户明确需要补充节点抄送人时传 |
| `uuid` | 否 | 幂等标识；重复重试同一请求时建议显式传入 |
| `--as user` | 否 | 建议显式指定用户身份；审批发起通常应使用用户身份 |
| `--yes` | 是 | 写操作确认；真实执行时必须显式传入 |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
### 4. 组装 `form`
`instances create --data.form` 是可选字段；传入时必须是一个 JSON 数组字符串。无表单或无需填写表单值的审批可省略 `form`，但只要审批定义包含需要提交的控件，就必须按控件结构组装后传入。组装原则：
- 先用 `approvals.get.form` 识别有哪些控件、每个控件的 `id` / `type` / 可选值范围，再按本文中的创建参数规则与 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 重新组装创建 payload。
- 提交时必须至少保证每个控件的 `id`、`type` 与 `value` 符合当前接口要求；不要假设定义快照里出现的其他字段都能直接照搬。
- 如果用户提供的是人员信息，优先转换成 `open_id` 后再写入对应控件。
- 单选/多选控件提交的是选项 `value`，该值可从 `approvals.get.form` 的选项定义中取得。
- `contact`、`department`、`fieldList`、`dateInterval`、`amount`、`telephone`、`document` 等控件的 `value` 结构各不相同，必须按 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 单独组装，不要套用文本控件的写法。
- 值本身从哪里拿，优先按 [`lark-approval-instance-value-sourcing.md`](./lark-approval-instance-value-sourcing.md) 处理；不要把“知道结构”误当成“已经拿到可提交值”。
- 若 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 标明某控件不支持通过创建实例 API 提交，则不要硬猜绕过；应明确告诉用户该定义当前无法仅通过 API 提单。
- 若遇到当前 skill 未明确覆盖的复杂控件，不要硬猜；先依据 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 判断支持性与传值结构，再向用户确认。
## API 不支持的控件
根据 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md)，创建审批实例 API 不支持的控件至少包括：
- `text`
- `mutableGroup`
- `account`
- `serialNumber`
- `tripGroup`
- `apaascorehrOnboardingGroup`
- `apaascorehrRegularateGroup`
- `remedyGroupV2`
- `apaascorehrJobAdjustGroup`
- `apaascorehrOffboardingGroup`
如果目标审批定义包含上述控件，不要继续硬拼 `form`；应直接告诉用户该定义不能仅通过当前 API 完整提单。
## 高频控件速查
优先按 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 组装，下面只保留最常用、最容易出错的格式：
- `input` / `textarea`: `value` 是字符串
- `date`: `value` 是 RFC3339 时间字符串
- `dateInterval`: `value` 是对象，包含 `start` / `end` / `interval`
- `radio` / `radioV2`: `value` 是单个选项值，取定义详情里的 `option.value`；关联外部选项时传 `options.id`
- `checkbox` / `checkboxV2`: `value` 是选项值数组
- `number`: `value` 是数字
- `amount`: `value` 是数字，还要带 `currency`
- `formula`: `value` 必须与定义中的公式结果匹配，否则会报错
- `contact`: 只推荐写 `open_ids`，由人员信息先转换成 `open_id`
- `connect`: `value` 是关联审批实例 `instance_code` 数组，当前默认要求用户直接提供 `instance_code`
- `document`: `value` 是对象，至少含 `token` 和 `type=docx`
- `attachmentV2` / `image` / `imageV2`: `value` 是 file code 数组，当前默认要求用户直接提供
- `fieldList`: `value` 是二维数组，子项继续按各自控件类型组装
- `department`: `value` 是对象数组，元素字段名为 `open_id`，其值填写部门的 `open_department_id`
- `telephone`: `value` 是对象，包含 `countryCode` 和 `nationalNumber`
- `address`: `value` 是对象数组，至少包含地理库 `id`，可选 `detailAddress`；当前默认要求用户直接提供该 `id`
## 特殊控件组
[`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 还明确给出了若干特殊控件组的提单格式，至少包括：
- `leaveGroupV2`
- `workGroup`
- `outGroup`
- `shiftGroup`
这类控件组不是简单文本控件，通常内部还嵌套 `radioV2`、`date`、`fieldList`、`image`、`contact` 等子控件。遇到这些控件组时：
- 先从 `approvals.get.form` 找到控件组及其子控件 ID
- 再严格按 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 的示例组装 `value`
- 不要把控件组整体当成普通字符串或扁平对象提交
### 5. 组装节点参数
从 `node_list` 推导节点参数：
- 若某节点 `need_approver=true`，则必须在 `node_approver_list` 中补该节点的审批人。
- `key` 优先取 `custom_node_id`；若不存在，再用 `node_id`。
- `value` 是审批人 `open_id` 列表。
- 若 `approver_chosen_multi=false`，该节点只允许一个审批人 `open_id`。
- `node_cc_list` 仅在用户明确需要补充节点抄送人时才填写；其 `key/value` 规则与 `node_approver_list` 相同。
### 6. 创建审批实例
创建命令使用 `approval instances create`，需要的 scopes: ["approval:instance:write"]
确认最终表单值和节点参数后再执行：
```bash
lark-cli approval instances create \
--data '{
"approval_code":"7C468A54-8745-2245-9675-08B7C63E7A85",
"form":"[{\"id\":\"widget1\",\"type\":\"input\",\"value\":\"请假半天\"}]",
"node_approver_list":[
{
"key":"manager_node_id",
"value":["ou_xxx"]
}
]
}' \
--as user \
--yes
```
执行规则：
- 执行前先向用户确认：目标审批定义、核心表单值、节点审批人/抄送人。
- 若需要幂等，可补 `uuid`。
- 成功后回报 `instance_code` 与 `instance_link`。
## 组装时优先依据的资料
优先级固定如下：
1. 本文中的创建请求参数、节点参数和返回结果说明：决定 `instances create` 要传哪些字段、怎么执行、成功后回什么。
2. [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md)：决定每种控件的 `value` 结构与支持范围。
3. [`lark-approval-instance-value-sourcing.md`](./lark-approval-instance-value-sourcing.md)：决定每类值应该从哪里拿，以及当前哪些值必须由用户直接提供。
4. `approvals.get.form`：提供当前审批定义里实际有哪些控件、控件 `id`、控件 `type`、选项值范围、明细子控件结构。
5. `approvals.get.node_list`：提供节点 key 与是否需要补充审批人/抄送人的线索。
不要反过来把 `approvals.get.form` 当成第一优先级，更不要把它当成可直接提交的 JSON 模板。
## 最小判断表
| 你手上有什么 | 下一步 |
|---|---|
| 只有口语需求，比如“帮我提个请假审批” | 先 `approvals.search` |
| 已经拿到 `approval_code` | 直接 `approvals.get` |
| 已拿到 `form` / `node_list`，且用户已给出表单值和审批人 | 组装 `instances create` |
| `is_external=true` | 返回 `create_link`，不要调 `instances create` |
## 返回结果
完成创建后，至少向用户返回：
- `approval_name`
- `instance_code`
- `instance_link`
建议整理为下面这种结构：
```text
审批已创建成功：
- approval_name: 请假申请
- instance_code: 19EAC829-F1CB-527F-BE2A-1330422E60C0
- instance_link: https://...
```
references/lark-approval-instance-form-control-parameters.md›
# 审批实例表单控件参数
> 说明：本文尽量保留上游参数文档的原始结构与示例，用于回答“控件 `value` 长什么样”。
> 当前 `lark-cli` 的推荐取值口径以 [`lark-approval-instance-value-sourcing.md`](./lark-approval-instance-value-sourcing.md) 为准；如果两份文档在“值从哪里拿”上存在差异，以后者为准。
在调用创建审批实例接口时需要使用表单控件参数，你可以通过本文了解审批实例内各表单控件的参数说明。
## 准备工作
审批实例的表单控件参数依据审批定义表单来配置，例如，审批定义的表单设计包括了 **单行文本** 和 **日期区间** 控件，则审批实例的表单控件参数就需要为 **单行文本** 和 **日期区间** 控件进行赋值。因此，在操作审批实例表单的控件参数前，应先通过审批定义详情确认表单控件结构。
## 审批实例 API 不支持的控件
创建审批实例 API 未完全支持所有的审批表单控件，不支持的控件如下表所示。如果你必须使用 API 不支持的控件，则不能仅通过当前 API 完成提单。
**控件/控件组** | **Type** |
| ---------- | --------------------------- |
| 说明 | text |
| 引用多维表格 | mutableGroup |
| 收款账户 | account |
| 流水号 | serialNumber |
| 出差控件组 | tripGroup |
| 录用控件组 | apaascorehrOnboardingGroup |
| 转正控件组 | apaascorehrRegularateGroup |
| 补卡控件组 | remedyGroupV2 |
| 调岗控件组 | apaascorehrJobAdjustGroup |
| 离职控件组 | apaascorehrOffboardingGroup
## 通用参数
审批实例的表单控件均包含的参数如下表所示。
参数 | 类型 | 是否必填 | 描述
---|---|---|---
id | string | 是 | 控件的 ID，需要与审批定义中的控件 ID 保持一致。
type | string | 是 | 控件类型。各控件类型取值参见下文 **不同控件的参数** 章节。
value | 不同控件的类型不同 | 是 | 控件的取值。不同控件 value 数据类型也不同，例如单行文本控件的 value 为字符串、联系人的 value 为数组。详情参见下文 **不同控件的参数** 章节。
## 不同控件的参数
本章节提供不同控件的 type 参数值、JSON 示例以及非通用参数说明。
### 单行文本
控件 type 为 input，JSON 数据示例：
```json
{
"id": "widget1",
"type": "input",
"value": "data" // string 类型
}
```
### 多行文本
控件 type 为 textarea，JSON 数据示例：
```json
{
"id": "widget1",
"type": "textarea",
"value": "data" // string 类型
}
```
### 日期
控件 type 为 date，JSON 数据示例：
```json
{
"id": "widget1",
"type": "date",
"value": "2019-10-01T08:12:01+08:00" // 需满足 RFC3339 格式的 string 类型
}
```
### 日期区间
控件 type 为 dateInterval，JSON 数据示例：
```json
{
"id": "widget1",
"type": "dateInterval",
"value": {
"start":"2019-10-01T08:12:01+08:00",
"end":"2019-10-02T08:12:01+08:00",
"interval": 1.0
}
}
```
value 参数为 object 类型，包含参数说明：
参数 | 类型 | 是否必填 | 描述
---|---|---|---
start | string | 是 | 开始时间，需满足 RFC3339 格式。
end | string | 是 | 结束时间，需满足 RFC3339 格式。
interval | float | 是 | 时长（天）。
### 单选
控件 type 为 radio/radioV2，JSON 数据示例：
```json
{
"id": "widget1",
"type": "radioV2",
"value": "k2b8mkx0-h71x5gl1234-1" // string 类型
}
```
其中， value 表示选项值，取值范围需要参考相应审批定义中 **单选** 控件 option 的 value 参数。你可以通过审批定义详情返回的 `form` 参数，获取单选控件 option 的 value 取值。如果控件关联了外部选项，则 value 需要传入外部选项的 `options.id`。
### 多选
控件 type 为 checkbox/checkboxV2，JSON数据示例：
```json
{
"id":"widget1",
"type":"checkboxV2",
"value": ["k2b8mkx0-h71x5gl4321-1"] // string 类型的数组
}
```
其中， value 表示选项值，取值范围需要参考相应审批定义中 **多选** 控件 option 的 value 参数。你可以通过审批定义详情返回的 `form` 参数，获取多选控件 option 的 value 取值。如果控件关联了外部选项，则 value 需要传入外部选项的 `options.id`。
### 数字
控件 type 为 number，JSON 数据示例：
```json
{
"id": "widget1",
"type": "number",
"value": 1234.5678 // float 类型
}
```
### 金额
控件 type 为 amount，JSON 数据示例：
```json
{
"id": "widget1",
"type": "amount",
"value": 1234.5678, // float 类型
"currency":"USD"
}
```
其中，currency 表示货币种类，取值范围需要参考相应审批定义中 **金额** 控件的 value 参数。你可以通过审批定义详情返回的 `form` 参数，获取金额控件可设置的货币种类。
### 计算公式
控件 type 为 formula，JSON 数据示例：
```json
{
"id": "widget1",
"type": "formula",
"value": 1234.5678 // 该值由审批定义内配置的公式计算出取值，若不匹配则返回报错。
}
```
### 联系人
控件 type 为 contact，JSON 数据示例：
```json
{
"id":"widget1",
"type":"contact",
"value": ["f8ca557e"], // string 类型的数组
"open_ids": ["ou_12345"] // string 类型的数组
}
```
其中，value 包含的是用户 `user_id`；open_ids 包含的是用户 `open_id`。
### 关联审批
控件 type 为 connect，JSON 数据示例：
```json
{
"id":"widget1",
"type":"connect",
"value": ["19EAC829-F1CB-527F-BE2A-1330422E60C0"] // string 类型的数组
}
```
其中，value 包含的是被关联的审批实例 Code，你可以通过审批实例详情能力根据实例 Code 获取实例详情。
### 文档控件
控件 type 为 document，JSON 数据示例：
```json
{
"id": "widget1",
"type": "document",
"value": {
"token":"TLLKdcpDro9ijQxA33ycNMabcef",
"type":"docx",
}
}
```
value 参数为 object 类型，包含参数说明：
参数 | 类型 | 是否必填 | 描述
---|---|---|---
token | string | 是 | 文档的 document_id。
type | string | 是 | 文档类型，支持 `docx`。
### 附件
控件 type 为 attachmentV2，JSON 数据示例：
```json
{
"id":"widget1",
"type":"attachmentV2",
"value": ["D93653C3-2609-4EE0-8041-61DC1D84F0B5"] // string 类型的数组
}
```
其中，value 包含的是上传文件后返回的文件 code。
### 图片
控件 type 为 image/imageV2，JSON 数据示例：
```json
{
"id":"widget1",
"type":"image",
"value": ["D93653C3-2609-4EE0-8041-61DC1D84F0B5"] // string 类型的数组
}
```
其中，value 包含的是上传文件后返回的文件 code。
### 明细/表格
控件 type 为 fieldList，JSON 格式示例：
```json
{
"id": "widget1",
"type": "fieldList",
"value": [
[
{
"id": "widget1",
"type": "checkbox",
"value": ["jxpsebqp-0"]
}
]
]
}
```
其中 value 是二维数组，根据审批定义内 **明细/表格** 控件所包含的控件，依次设置控件 JSON 值。
### 部门
控件 type 为 department，JSON 数据示例：
```json
{
"id":"widget1",
"type":"department",
"value":[
{
"open_id": "od-xxx"
}
]
}
```
其中 value 为对象数组，通过 open_id 设置部门的 open_department_id。
### 电话
控件 type 为 telephone，JSON 数据示例：
```json
{
"id":"widget1",
"type":"telephone",
"value": {
"countryCode":"+86",
"nationalNumber":"13122222222"
}
}
```
value 参数为 object 类型，包含参数说明：
参数 | 类型 | 是否必填 | 描述
---|---|---|---
countryCode | string | 是 | 区号。
nationalNumber | string | 是 | 电话号。
### 地址
控件 type 为 address，JSON 数据示例：
```json
{
"id": "widget1",
"type": "address",
"value": [{
"id": "290557",
"detailAddress": "详细的地址"
}]
}
```
value 参数为 []object 类型，参数说明如下：
参数 | 类型 | 是否必填 | 描述
---|---|---|---
value | []object | 是 | 非出差控件组场景地址控件仅支持单个地址，传入多个时默认只取第一个
└ id | string | 是 | 区域ID, 可通过审批的地理库接口获取
└ detailAddress | string | 否 | 详细的地址，若表单配置中未开启填写详细地址，则会忽略该参数，即使传入也不会生效
### 换班控件组
控件 type 为 shiftGroup，JSON 数据示例：
```json
{
"id": "widget1",
"type": "shiftGroup",
"value": {
"shiftTime": "2019-10-01T08:12:01+08:00",
"returnTime": "2019-10-02T08:12:01+08:00",
"reason": "ask for leave"
}
}
```
value 参数为 object 类型，包含参数说明：
参数 | 类型 | 是否必填 | 描述
---|---|---|---
shiftTime | string | 是 | 换班时间，需满足 RFC3339 格式。
returnTime | string | 是 | 对调日期，需满足 RFC3339 格式。
reason | string | 是 | 换班原因。
### 请假控件组
**请假控件组请求示例**
```json
{
"id": "widgetLeaveGroupV2",
"type": "leaveGroupV2",
"value": [
{
"id": "widgetLeaveGroupType",
"type": "radioV2",
"value": "7488925543484620819"
},
{
"id": "widgetLeaveGroupStartTime",
"type": "date",
"value": "2025-08-25T11:30:00+08:00"
},
{
"id": "widgetLeaveGroupEndTime",
"type": "date",
"value": "2025-08-26T11:35:00+08:00"
},
{
"id": "widgetLeaveGroupReason",
"type": "textarea",
"value": "123123"
},
{
"id": "widgetLeaveCertification",
"type": "image",
"value": [
"B69F8E26-0EAA-4A92-9B80-DA613CD36136"
]
},
{
"id":"widgetLeaveCertification",
"type":"image",
"value": ["D93653C3-2609-4EE0-8041-61DC1D84F0B5"]
},
{
"id": "widgetLeaveGroupFeedingArrivingLate",
"type": "radioV2",
"value": "30"
},
{
"id": "widgetLeaveGroupFeedingOffLeaveEarly",
"type": "radioV2",
"value": "30"
}
]
}
```
**请假控件组包含参数说明：**
id | 类型 | JSON示例 | 描述
---|---|---|---
id | string | 是 | 控件组ID，固定为widgetLeaveGroupV2
type | string | 是 | 控件组类型，固定为leaveGroupV2
value | object[] | 是 | 控件组的值，值为多个子控件值的列表
value中包含的子控件值说明:
id | 类型 | JSON示例 | 描述
---|---|---|---
widgetLeaveGroupType | radioV2 | ```<br>{<br>"id": "widgetLeaveGroupType",<br>"type": "radioV2",<br>"value": "7488925543484620819"<br>}<br>``` | 假期类型，具体格式可参考单选控件，选项由假勤接口获取，提单时必须包含该控件
widgetLeaveGroupStartTime | date | ```<br>{<br>"id": "widgetLeaveGroupStartTime",<br>"type": "date",<br>"value": "2019-10-01T08:12:01+08:00", // 需满足 RFC3339 格式的 string 类型<br>} <br>``` | 请假开始时间，具体格式可参考日期控件，会根据假期类型自动取整,其中半天假小于12点则认为是上午，小时假则以半小时为粒度向前取整, 提单时必须包含该控件
widgetLeaveGroupEndTime | date | ```<br>{<br>"id": "widgetLeaveGroupEndTime",<br>"type": "date",<br>"value": "2019-10-01T08:12:01+08:00", // 需满足 RFC3339 格式的 string 类型<br>}<br>``` | 请假结束时间，具体格式可参考日期控件，会根据假期类型自动取整，其中半天假小于12点则认为是上午，小时假则以半小时为粒度向后取整
widgetLeaveGroupReason | textarea | ```<br>{<br>"id": "widgetLeaveGroupReason",<br>"type": "textarea",<br>"value": "123123"<br>}<br>``` | 请假事由，具体格式可参考多行文本控件，哺乳假无需填写，其他情况则根据控件组配置中该控件是否可见以及必填判断
widgetLeaveCertification | image | ```<br>{<br>"id":"widgetLeaveCertification",<br>"type":"image",<br>"value": ["D93653C3-2609-4EE0-8041-61DC1D84F0B5"]<br>}<br>``` | 请假证明，具体格式可参考图片控件，如果所选假期类型配置要求补充证明则必须传递该值，缺失会报错
widgetLeaveGroupFeedingArrivingLate | radioV2 | ```<br>{ <br>"id": "widgetLeaveGroupFeedingArrivingLate",<br>"type": "radioV2",<br>"value": "30"<br>}<br>``` | 上班晚到的分钟数，具体格式可参考单选控件，仅哺乳假需要填写，取值范围是0-120分钟，粒度是15分钟，选项从审批定义中该控件的option中获取
widgetLeaveGroupFeedingOffLeaveEarly | radioV2 | ```<br>{ <br>"id": "widgetLeaveGroupFeedingOffLeaveEarly",<br>"type": "radioV2",<br>"value": "30"<br>} <br>``` | 下班早走的分钟数，具体格式可参考单选控件，仅哺乳假需要填写，取值范围是0-120分钟，粒度是15分钟，选项即是分钟对应的字符串
**特殊的参数校验报错信息**
message | 说明 |
| -------------------------------------------------- | ---------------------------- |
| leave type id parse error | 请假类型不是int64 |
| group value is invalid | 当前控件组的值无效，请校验是否为空或者校验类型是否为数组 |
| start time format is not RFC3339 | 开始时间日期格式非*RFC3339格式* |
| end time format is not RFC3339 | 结束时间日期格式非*RFC3339格式* |
| start time is after end time | 开始时间晚于结束时间 |
| user not in gray | 申请用户不在假勤灰度内 |
| leave type not found | 请假类型不存在 |
| reason is required | 请假原因未填写 |
| leave quote should be bigger than 0 | 请假时长需要大于0 |
| leave is conflict | 所选时间内已有请假记录，请选择其他时间 |
| balance is not enough | 当前假期类型下假期余额不足 |
| certification is required | 需要上传请假证明 |
| arriving late is required | 哺乳假需要填写上班晚到时长 |
| arriving late value is not in the optional items | 晚到时间不在可选范围内 |
| leaving early is required | 哺乳假需要填写下班提前时长 |
| leaving early value is not in the optional items | 下班提前时间不在可选范围内 |
| feeding rest daily is 0 | 哺乳假每日休息时长为0，请重新选择 |
| the operation is prohibited by the workforce rules | 当前账户已在假勤侧封账，无法提交
### 加班控件组
**加班控件组请求示例**
```json
{
"id": "widgetWorkGroup",
"type": "workGroup",
"value":[
{
"id":"widgetWorkGroupOvertimeWorkers",
"type":"contact",
"value": ["f8ca557e"],
"open_ids": ["ou_12345"]
},
{
"id": "widgetWorkGroupType",
"type": "radioV2",
"value": "7259635026038505475"
},
{
"id":"widgetWorkGroupTimeRangeFieldList",
"type":"fieldList",
"value":[
[
{
"id":"widgetWorkGroupStartTime",
"type":"date",
"value":"2019-10-01T08:12:01+08:00"
},
{
"id":"widgetWorkGroupEndTime",
"type":"date",
"value":"2019-10-01T08:12:01+08:00"
}
]
]
},
{
"id": "widgetWorkGroupReason",
"type": "textarea",
"value": "111"
}
]
}
```
**加班控件组参数说明：**
参数 | 类型 | 是否必填 | 描述
---|---|---|---
id | string | 是 | 控件组ID，固定为widgetWorkGroup
type | string | 是 | 控件组类型，固定为workGroup
value | object[] | 是 | 控件组的值，值为多个子控件值的列表
value中包含的子控件值说明:
id | 类型 | JSON示例 | 描述
---|---|---|---
widgetWorkGroupOvertimeWorkers | contact | ```<br>{<br>"id":"widgetWorkGroupOvertimeWorkers",<br>"type":"contact",<br>"value": ["f8ca557e"], <br>"open_ids": ["ou_12345"]<br>}<br>``` | 加班人员列表，具体格式可参考联系人控件，如果定义中配置「允许代多人提交」则该字段必填，如果是提交人给自己提交需填写提交人的ID
widgetWorkGroupType | radioV2 | ```<br>{<br>"id": "widgetWorkGroupType",<br>"type": "radioV2",<br>"value": "7259635026038505475" // 对应的类型选项ID<br>}<br>``` | 加班类型，具体格式可参考单选控件，如果定义中关闭「关联加班规则」则需要填写该字段
widgetWorkGroupTimeRangeFieldList | fieldList | ```<br>{<br>"id":"widgetWorkGroupTimeRangeFieldList",<br>"type":"fieldList",<br>"value":[<br>[<br>{<br>"id":"widgetWorkGroupStartTime",<br>"type":"date",<br>"value":"2019-10-01T08:12:01+08:00"<br>},<br>{<br>"id":"widgetWorkGroupEndTime",<br>"type":"date",<br>"value":"2019-10-01T08:12:01+08:00"<br>}<br>]<br>]<br>}<br>``` | 加班时段，具体格式可参考明细控件，如果定义中打开「允许提交多个加班时段」则可以传多个，最多支持30个，否则只会取第一个，单次加班时长不可超过两天
widgetWorkGroupReason | textarea | ```<br>{<br>"id": "widgetWorkGroupReason",<br>"type": "textarea",<br>"value": "111"<br>}<br>``` | 加班事由，如果定义中配置了「加班事由」必填，则必须填写该字段
**特殊的参数校验报错信息**
message | 说明 |
| ---------------------------------------------------------------------------------- | ---------------------------- |
| the time range list has more than 30 items | 加班时段数量超过30 |
| group value is invalid | 当前控件组的值无效，请校验是否为空或者校验类型是否为数组 |
| overtime type is required | 未关联加班规则时，加班类型必填 |
| work time range is required | 至少需要一个加班时段 |
| start time is after end time | 开始时间晚于结束时间 |
| start time or end time of range is required | 加班时间段的开始时间和结束时间必填 |
| overtime duration is over 2 days | 单次加班时长不可超过两天 |
| overtime date time zone not support | 加班时段的日期时区信息无法识别 |
| {date} can not apply overtime | 所选时间不可申请加班 |
| {date} already apply overtime | 所选时间已经有加班记录 |
| {date} no need approval | 所选日期加班无需申请 |
| apply reason is required | 定义中设置了加班事由为必填，不可为空 |
| {users} user follow different overtime rules, cannot be submitted in the same form | 所选加班人不在同一个考勤组内，无法同时提交加班 |
| invalid overtime work application | 没有有效的加班申请，请重新选择加班日期 |
| the overtime duration cannot be 0 | 加班时长不能是0 |
| the number of apply workers cannot exceed 50 | 单次申请加班人数量不可大于50 |
| apply worker is required | 必须有加班人，配置置可代多人提交时必须指定加班人 |
| resigned worker can not apply | 离职人员不可申请加班 |
| overtime duration is over limit | 加班时长超过限制
### 外出控件组
**外出控件组请求体示例**
```json
{
"id": "widgetOutGroup",
"type": "outGroup",
"value":[
{
"id": "widgetOutGroupType",
"type": "radioV2",
"value": "me15yqrf-gmjgbml2vhp-0"
},
{
"id": "widgetOutGroupStartTime",
"type": "date",
"value":"2019-10-01T08:12:01+08:00"
},
{
"id": "widgetOutGroupEndTime",
"type": "date",
"value":"2019-10-01T08:12:01+08:00"
},
{
"id": "widgetOutGroupReason",
"type": "textarea",
"value":"123213"
},
{
"id":"widgetOutGroupImage",
"type":"image",
"value": ["D93653C3-2609-4EE0-8041-61DC1D84F0B5"]
}
]
}
```
**外出控件参数说明**
参数 | 类型 | 是否必填 | 描述
---|---|---|---
id | string | 是 | 控件组ID，固定为widgetOutGroup
type | string | 是 | 控件组Type，固定为outGroup
value | object[] | 是 | 控件组的值，值为多个子控件值的列表
value中包含的子控件值说明:
id | 类型 | JSON示例 | 描述
---|---|---|---
widgetOutGroupType | radioV2 | ```<br>{<br>"id": "widgetOutGroupType",<br>"type": "radioV2",<br>"value": "me15yqrf-gmjgbml2vhp-0" <br>}<br>``` | 外出类型，具体格式可参考单选控件，如果配置了「外出类型」则必填，外出时长单位会选取所选外出类型关联的单位，如果没有配置「外出类型」，则该字段无需填写，计算外出时长时会选取「外出时长」配置的单位
widgetOutGroupStartTime | date | ```<br>{<br>"id": "widgetOutGroupStartTime",<br>"type": "date",<br>"value":"2019-10-01T08:12:01+08:00"<br>}<br>``` | 外出开始时间，具体格式可参考日期控件，如果外出时长单位是半天假，则小于12点则认为是上午，否则认为是下午；如果单位是小时，则会按半小时的粒度向前取整
widgetOutGroupEndTime | date | ```<br>{<br>"id": "widgetOutGroupEndTime",<br>"type": "date",<br>"value":"2019-10-01T08:12:01+08:00"<br>}<br>``` | 外出结束时间，具体格式可参考日期控件，如果外出时长单位是半天假，则小于12点则认为是上午，否则认为是下午；如果单位是小时，则会按半小时的粒度向后取整
widgetOutGroupReason | textarea | ```<br>{<br>"id": "widgetOutGroupReason",<br>"type": "textarea",<br>"value":"123213"<br>}<br>``` | 外出事由，具体格式可参考多行文本控件，如果定义中「外出事由」必填，则必须填写该控件，如果定义配置无需填写，则无需填写该控件
widgetOutGroupImage | image | ```<br>{<br>"id":"widgetOutGroupImage",<br>"type":"image",<br>"value": ["D93653C3-2609-4EE0-8041-61DC1D84F0B5"]<br>} <br>``` | 外出证明，具体格式可参考图片控件，如果定义中「外出拍照」必填，则必须填写该控件，如果定义配置无需填写，则无需填写该控件
**特殊的参数校验报错信息**
message | 说明 |
| ----------------------------------------------------- | ---------------------------- |
| group value is invalid | 当前控件组的值无效，请校验是否为空或者校验类型是否为数组 |
| start time format is not RFC3339 | 开始时间日期格式非*RFC3339格式* |
| end time format is not RFC3339 | 结束时间日期格式非*RFC3339格式* |
| start time and end time must be in the same time zone | 开始时间与结束时间必须是同一时区 |
| out type is required | 如果定义中设定了「外出类型」，则外出类型必填 |
| out start time is required | 外出开始时间必填 |
| out end time is required | 外出结束时间必填 |
| out duration must be greater than 0 | 外出间隔不能为0，请检查起止时间并重新选择 |
| out reason is empty | 如果定义中勾选「外出事由」同时设定必填，则该字段必填 |
| photo is required | 如果定义中勾选「外出拍照」同时设定必填，则该字段必填 |
| out time is conflict | 外出时间有冲突，请确认是否已在该时段申请外出
references/lark-approval-instance-value-sourcing.md›
# 审批提单值来源
## 目的
本文用于回答一个固定问题：在调用 `approval instances create` 发起原生审批实例时，**每个要填写的值从哪里拿**。
阅读顺序固定如下：
1. [`lark-approval-initiate.md`](./lark-approval-initiate.md) 中的创建请求参数、节点参数和返回结果说明
2. `approval approvals get` 返回的 `form` / `node_list`
3. [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md)
4. 本文
## 总原则
- `lark-approval-initiate.md` 决定创建请求字段名、字段层级、节点参数结构。
- `approvals.get.form` 决定控件 `id`、`type`、选项值范围、子控件结构。
- `approvals.get.node_list` 决定节点 key、是否必须补审批人、是否允许多人。
- [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 决定各控件 `value` 的最终结构。
- 除非本文明确允许，否则不要猜值来源，不要把展示文案直接当成可提交值。
## 默认来源
- 审批定义、`approval_code`、`is_external`、`create_link` 等基础信息，默认从 `approval approvals search` 获取。
- 控件 `id`、`type`、选项值、子控件结构，默认从 `approval approvals get.form` 获取。
- 节点 key、`need_approver`、`approver_chosen_multi` 等节点信息，默认从 `approval approvals get.node_list` 获取。
- 本文只补充 **这些默认来源之外** 的取值规则，以及当前必须由用户直接提供的值。
## 控件值来源规则
### 联系人 `contact`
- 只推荐写 `open_ids`。
- 不再推荐双写 `value(user_id)` + `open_ids`，避免复杂度继续上升。
- 如果用户给的是姓名、邮箱或账号，先用 `lark-contact` 解析成 `open_id`。
### 部门 `department`
- 最优先：用户直接提供 `open_department_id`。
- 若用户说“我的部门”或“张三的部门”，先用 `lark-contact` 查询对应人员信息，再取其所属部门里的 `open_department_id`。
- 如果查到该人员只有一个部门，可直接使用。
- 如果查到多个部门，不自动猜，必须让用户明确选一个，或直接输入 `open_department_id`。
- 如果仍无法确定，则明确告知当前不支持自动决定部门值。
### 附件 `attachmentV2`
- 当前 `lark-approval` 不负责上传文件。
- 用户必须直接提供 file code。
- 如果用户无法提供 file code，应明确告知当前无法仅通过 `lark-approval` 完成该控件提单。
### 图片 `image` / `imageV2`
- 当前 `lark-approval` 不负责上传图片。
- 用户必须直接提供 file code。
- 如果用户无法提供 file code，应明确告知当前无法仅通过 `lark-approval` 完成该控件提单。
### 文档 `document`
- 用户可直接提供 `token` / `document_id`。
- 如果用户给的是飞书文档链接，应先尝试从链接中提取 token。
- 若链接提取失败，再要求用户手动输入 token。
### 关联审批 `connect`
- 用户直接提供目标审批实例的 `instance_code`。
- 当前不默认做“搜索关联实例再反查 code”的自动流程。
### 地址 `address`
- 用户直接提供地理库 `id`。
- 若用户无法提供该 `id`，当前不支持自动取值。
## 特殊控件组
以下控件组的结构仍按 [`lark-approval-instance-form-control-parameters.md`](./lark-approval-instance-form-control-parameters.md) 组装：
- `leaveGroupV2`
- `workGroup`
- `outGroup`
- `shiftGroup`
补充规则：
- 控件组自身和子控件的 `id` / `type` 从 `approval approvals get.form` 中识别。
- 组内单选/多选或业务枚举值，优先从 `approval approvals get.form` 返回的选项结构中取。
- 不要把控件组整体当成普通字符串或扁平对象提交。
## 不支持自动准备的值
以下值当前不建议由 `lark-approval` 自动准备：
- 文件上传后的 file code
- 图片上传后的 file code
- 地址控件的地理库 `id`
- 无法唯一确定的部门 `open_department_id`
遇到这类值时，应明确告诉用户需要提供什么，而不是继续猜测。
## 最小决策表
| 场景 | 处理 |
|---|---|
| 用户说“找张三当审批人” | 用 `lark-contact` 解析张三，取 `open_id` |
| 用户说“我的部门” | 先查当前用户部门；若多个部门，让用户选 |
| 用户给了文档链接 | 先尝试提取 token |
| 用户要填图片/附件 | 要求直接提供 file code |
| 用户要填关联审批 | 要求直接提供 `instance_code` |
| 用户要填地址 | 要求直接提供地理库 `id` |
references/lark-approval-instances-cancel.md›
# approval instances cancel
撤回一个已发起的审批实例（用户级写操作）。通常先通过 `instances initiated`、`tasks query` 或 `instances get` 确认目标审批实例，拿到 `instance_code` 后再执行撤回。
> [!CAUTION]
> 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览；真正执行时，如果用户已明确要撤回该审批实例且目标实例无误，再带 `--yes` 运行。不要在未获用户明确同意时静默追加 `--yes`。
需要的 scopes: ["approval:instance:write"]
## 命令
```bash
# 先预览请求，不实际执行
lark-cli approval instances cancel \
--data '{"instance_code":"<INSTANCE_CODE>"}' \
--as user \
--dry-run
# 撤回一个审批实例
lark-cli approval instances cancel \
--data '{"instance_code":"<INSTANCE_CODE>"}' \
--as user \
--yes
# 通过文件传入请求体
lark-cli approval instances cancel \
--data @./cancel-body.json \
--as user \
--yes
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--data '{...}'` | 是 | 请求体 JSON，使用 JSON 传入 |
| `instance_code` | 是 | 审批实例 Code；通常先通过 `instances initiated`、`tasks query` 或 `instances get` 获取 |
| `--as user` | 否 | 建议显式指定用户身份；审批实例撤回通常必须以用户身份执行 |
| `--yes` | 否 | 确认执行高风险写操作；未带时可能返回 `confirmation_required` / exit 10 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 典型前置步骤
如果你要找“我发起的审批实例”，可先查询已发起列表：
```bash
lark-cli approval instances initiated --params '{"page_size":20}' --as user
```
如果你已经在任务列表中定位到某个审批，也可以从任务里拿到实例 Code：
```bash
lark-cli approval tasks query --params '{"topic":"1"}' --as user
```
常用到的字段：
| 字段 | 说明 |
|------|------|
| `instances[].instance_code` | 审批实例 Code；撤回时必须提供 |
| `tasks[].instance_code` | 审批任务关联的审批实例 Code；也可作为撤回输入 |
| `tasks[].instance_status` | 审批实例状态；可用于判断是否仍处于可撤回阶段 |
如需先确认审批表单、当前节点、流转状态，可继续查看实例详情：
```bash
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
```
## 使用建议
- **撤回的是审批实例，不是单个任务**：`instances cancel` 只需要 `instance_code`，不需要 `task_id`。
- **优先确认实例是否仍可撤回**：已经通过、已拒绝、已撤销或已终止的实例通常不适合继续撤回。
- **优先从 `instances initiated` 获取目标实例**：因为撤回通常针对“我发起的审批”，这个入口最直接。
- **也可从 `tasks query` 反查 `instance_code`**：当你是从某个待办/已办上下文进入时，这样更方便。
- **先 `--dry-run` 再执行**：尤其在实例来源不明确、用户只给了标题关键字，或一次要核对多个实例时，先预览更安全。
references/lark-approval-instances-cc.md›
# approval instances cc
给一个审批实例追加抄送人（用户级写操作）。通常先通过 `instances initiated`、`tasks query` 或 `instances get` 确认目标审批实例，拿到 `instance_code` 后，再提供抄送人的用户 ID 执行抄送。
> [!CAUTION]
> 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览；真正执行时，如果用户已明确要抄送该审批实例且目标实例、抄送对象都无误，再带 `--yes` 运行。不要在未获用户明确同意时静默追加 `--yes`。
需要的 scopes: ["approval:instance:write"]
## 命令
```bash
# 先预览请求，不实际执行
lark-cli approval instances cc \
--data '{"instance_code":"<INSTANCE_CODE>","cc_user_ids":["ou_xxx"],"comment":"抄送给项目 owner 了解进展"}' \
--params '{"user_id_type":"open_id"}' \
--as user \
--dry-run
# 按 open_id 抄送一个人
lark-cli approval instances cc \
--data '{"instance_code":"<INSTANCE_CODE>","cc_user_ids":["ou_xxx"],"comment":"抄送给你知悉"}' \
--params '{"user_id_type":"open_id"}' \
--as user \
--yes
# 一次抄送多个人
lark-cli approval instances cc \
--data '{"instance_code":"<INSTANCE_CODE>","cc_user_ids":["ou_xxx","ou_yyy"],"comment":"请相关同学同步关注"}' \
--params '{"user_id_type":"open_id"}' \
--as user \
--yes
# 按 user_id 抄送
lark-cli approval instances cc \
--data '{"instance_code":"<INSTANCE_CODE>","cc_user_ids":["123456789"],"comment":"抄送给财务负责人"}' \
--params '{"user_id_type":"user_id"}' \
--as user \
--yes
# 通过文件传入请求体
lark-cli approval instances cc \
--data @./cc-body.json \
--params '{"user_id_type":"open_id"}' \
--as user \
--yes
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--data '{...}'` | 是 | 请求体 JSON，使用 JSON 传入 |
| `instance_code` | 是 | 审批实例 Code；通常先通过 `instances initiated`、`tasks query` 或 `instances get` 获取 |
| `cc_user_ids` | 是 | 抄送人的用户 ID 数组；需要和 `user_id_type` 保持一致 |
| `comment` | 否 | 抄送留言，例如 `抄送给你知悉`、`请同步关注该审批进展` |
| `--params '{"user_id_type":"..."}'` | 否 | 查询参数 JSON；用于声明 `cc_user_ids` 内用户 ID 的类型 |
| `user_id_type` | 否 | 用户 ID 类型：`user_id`、`union_id`、`open_id`；未显式指定时要特别确认抄送人的 ID 类型 |
| `--as user` | 否 | 建议显式指定用户身份；审批实例抄送通常必须以用户身份执行 |
| `--yes` | 否 | 确认执行高风险写操作；未带时可能返回 `confirmation_required` / exit 10 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 典型前置步骤
如果你要找“我发起的审批实例”，可先查询已发起列表：
```bash
lark-cli approval instances initiated --params '{"page_size":20}' --as user
```
如果你已经在任务列表中定位到某个审批，也可以从任务里拿到实例 Code：
```bash
lark-cli approval tasks query --params '{"topic":"1"}' --as user
```
常用到的字段：
| 字段 | 说明 |
|------|------|
| `instances[].instance_code` | 审批实例 Code；抄送时必须提供 |
| `tasks[].instance_code` | 审批任务关联的审批实例 Code；也可作为抄送输入 |
| `tasks[].title` | 任务标题，可用于确认是否是要操作的那个审批 |
| `tasks[].instance_status` | 审批实例状态；可用于判断当前审批是否仍处于进行中 |
如果你手里只有姓名或邮箱，建议先通过联系人能力解析出正确的用户 ID，再执行抄送。
如需先确认审批表单、当前节点、流转状态，可继续查看实例详情：
```bash
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
```
## 使用建议
- **抄送的是审批实例，不是单个任务**：`instances cc` 只需要 `instance_code`，不需要 `task_id`。
- **`cc_user_ids` 与 `user_id_type` 必须匹配**：例如传 open_id 就把 `user_id_type` 设为 `open_id`；不要混用。
- **`cc_user_ids` 是数组**：即使只抄送一个人，也要按数组形式传入。
- **优先显式传 `user_id_type`**：这样 agent 更容易判断参数含义，也能减少 ID 类型不匹配带来的失败。
- **优先从 `instances initiated` 获取目标实例**：因为抄送常见于“我发起的审批”场景，这个入口最直接。
- **也可从 `tasks query` 反查 `instance_code`**：当你是从某个审批上下文进入时，这样更方便。
- **`comment` 建议简洁明确**：例如 `抄送给你知悉`、`请同步关注审批进展`。避免过长或模糊描述。
- **先 `--dry-run` 再执行**：尤其在抄送对象较多、抄送人来源不明确，或需要让用户先核对实例标题时，先预览更安全。
references/lark-approval-instances-get.md›
# approval instances get
获取单个审批实例详情（用户级只读操作）。适合在执行 approve / reject / transfer / rollback / cancel / cc / remind 之前，先查看审批表单、当前节点、任务列表、审批动态和整体状态。
需要的 scopes: ["approval:instance:read"]
## 命令
```bash
# 按实例 Code 查询详情
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
# 表格格式输出，便于快速浏览顶层字段
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --format table --as user
# 预览 API 调用，不执行
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user --dry-run
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--params '{...}'` | 是 | 查询参数，使用 JSON 传入 |
| `instance_code` | 是 | 审批实例 Code |
| `locale` | 否 | 返回语言，例如 `zh-CN`、`en-US`、`ja-JP` |
| `user_id_type` | 否 | 用户 ID 类型：`user_id`、`union_id`、`open_id` |
| `--as user` | 否 | 建议显式指定用户身份；审批实例详情查询通常应使用用户身份 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 常见输入来源
如果你已经有实例 Code，可直接查询：
```bash
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
```
如果你还没有实例 Code，可先从以下命令获取：
```bash
# 查询我发起的审批实例
lark-cli approval instances initiated --params '{"page_size":20}' --as user
# 或从任务列表里拿到关联实例 Code
lark-cli approval tasks query --params '{"topic":"1"}' --as user
```
## 输出重点字段
返回结果中常见字段：
| 字段 | 说明 |
|------|------|
| `instance_code` | 审批实例 Code |
| `serial_number` | 审批单编号 |
| `definition_code` | 审批定义 Code |
| `definition_name` | 审批名称 |
| `user_id` | 发起审批的用户 ID |
| `department_id` | 发起人所在部门 ID |
| `status` | 审批实例状态，见下方“status 枚举” |
| `reverted` | 单据是否已被撤销 |
| `start_time` | 审批创建时间 |
| `end_time` | 审批完成时间，未完成时通常为 `0` |
| `form` | 表单数据，JSON 字符串 |
| `current_nodes` | 当前审批节点列表 |
| `tasks` | 审批任务列表 |
| `operation_records` | 审批动态，例如通过、拒绝、转交、加签、回退、撤回、抄送 |
| `comments` | 评论列表 |
## status 枚举
| 值 | 含义 |
|----|------|
| `PENDING` | 审批中 |
| `APPROVED` | 已通过 |
| `REJECTED` | 已拒绝 |
| `CANCELED` | 已撤回 |
| `DELETED` | 已删除 |
## current_nodes 重点字段
`current_nodes` 常用于判断审批流当前卡在哪一层：
| 字段 | 说明 |
|------|------------------------------------------|
| `current_nodes[].node_id` | 当前审批节点 ID |
| `current_nodes[].node_name` | 当前审批节点名称 |
| `current_nodes[].type` | 审批方式：`AND` 会签、`OR` 或签、`SEQUENTIAL` 依次审批等 |
| `current_nodes[].approvers[].task_id` | 当前审批人关联任务 ID |
| `current_nodes[].approvers[].user_id` | 当前审批人用户 ID |
## tasks 重点字段
`tasks` 常用于把实例和具体审批任务关联起来：
| 字段 | 说明 |
|------|------|
| `tasks[].id` | 审批任务 ID |
| `tasks[].node_id` | 任务所属节点 ID |
| `tasks[].node_name` | 任务所属节点名称 |
| `tasks[].user_id` | 审批人用户 ID |
| `tasks[].status` | 任务状态：`PENDING`、`APPROVED`、`REJECTED`、`TRANSFERRED`、`DONE` |
| `tasks[].start_time` | 任务开始时间 |
| `tasks[].end_time` | 任务完成时间 |
## operation_records 重点字段
`operation_records` 常用于审计审批过程：
| 字段 | 说明 |
|------|------|
| `operation_records[].type` | 事件类型，如 `PASS`、`REJECT`、`TRANSFER`、`ROLLBACK`、`CANCEL`、`CC` |
| `operation_records[].create_time` | 事件发生时间 |
| `operation_records[].user_id` | 触发该事件的用户 ID |
| `operation_records[].task_id` | 关联任务 ID |
| `operation_records[].node_id` | 关联节点 ID |
| `operation_records[].comment` | 理由 / 备注 |
| `operation_records[].cc_user_ids` | 被抄送人列表（抄送事件时） |
## 使用建议
- **这是最适合做“详情确认”的只读命令**：当你已经拿到 `instance_code`，需要确认表单、当前节点、任务状态、审批动态时，优先使用它。
- **在执行写操作前先看详情**：例如做 `tasks rollback` 前确认可退回节点，做 `instances cancel` 前确认实例状态，做 `tasks remind` 前确认当前任务是否仍待处理。
- **`form` 是 JSON 字符串**：调用方通常还需要再解析一层，才能拿到表单字段值。
- **`current_nodes` 和 `tasks` 可以联动看**：前者看“当前卡在哪个节点”，后者看“每个任务目前由谁处理、状态如何”。
- **`operation_records` 适合做时间线回溯**：例如排查谁转交过、谁加签过、什么时候撤回或抄送过。
- **优先显式传 `locale` 和 `user_id_type`**：这样 agent 更容易理解返回文本和 ID 语义，减少歧义。
## 输出与后续操作
读取详情后，常见下一步：
```bash
# 同意审批任务
lark-cli approval tasks approve --data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>"}' --as user --yes
# 撤回审批实例
lark-cli approval instances cancel --data '{"instance_code":"<INSTANCE_CODE>"}' --as user --yes
# 催办审批任务
lark-cli approval tasks remind --data '{"instance_code":"<INSTANCE_CODE>","task_ids":["<TASK_ID>"]}' --as user --yes
```
references/lark-approval-instances-initiated.md›
# approval instances initiated
查询当前用户已发起的审批实例列表（用户级只读操作）。适合在需要查看“我发起了哪些审批”、筛选某类审批定义、获取 `instance_code` 供后续 `instances get` / `instances cancel` / `instances cc` 等命令使用时调用。
需要的 scopes: ["approval:instance:read"]
## 命令
```bash
# 查询我发起的审批列表
lark-cli approval instances initiated --params '{"page_size":20}' --as user
# 只看某个审批定义下我发起的实例
lark-cli approval instances initiated --params '{"definition_code":"<DEFINITION_CODE>","page_size":20}' --as user
# 按关键词搜索我发起的实例
lark-cli approval instances initiated --params '{"keyword":"测试","page_size":10}' --as user
# 按发起时间范围筛选（秒级时间戳）
lark-cli approval instances initiated --params '{"start_timestamp":"<START_SECONDS>","end_timestamp":"<END_SECONDS>","page_size":20}' --as user
# 使用 page_token 翻页
lark-cli approval instances initiated --params '{"page_size":20,"page_token":"example_page_token"}' --as user
# 表格格式输出，便于快速浏览
lark-cli approval instances initiated --params '{"page_size":20}' --format table --as user
# 预览 API 调用，不执行
lark-cli approval instances initiated --params '{"page_size":20}' --as user --dry-run
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--params '{...}'` | 否 | 查询参数，使用 JSON 传入；不传时使用默认分页与筛选 |
| `definition_code` | 否 | 审批定义 Code，用于只查看某个审批定义下我发起的实例 |
| `keyword` | 否 | 搜索关键词；非空时走搜索链路，空或仅空格时保持普通列表链路 |
| `start_timestamp` | 否 | 按发起时间筛选，时间范围开始值，秒级时间戳 |
| `end_timestamp` | 否 | 按发起时间筛选，时间范围结束值，秒级时间戳 |
| `locale` | 否 | 返回语言：`zh-CN`、`en-US`、`ja-JP` |
| `page_size` | 否 | 分页大小 |
| `page_token` | 否 | 翻页标记；首次请求不填，后续使用上一次返回的 `page_token` |
| `user_id_type` | 否 | 用户 ID 类型：`user_id`、`union_id`、`open_id` |
| `--as user` | 否 | 建议显式指定用户身份；已发起审批列表查询通常应使用用户身份 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 输出重点字段
返回结果中常见字段：
| 字段 | 说明 |
|------|------|
| `count` | 列表计数，只在第一页返回；大于等于 100 个实例时返回 `99` |
| `has_more` | 是否还有更多数据 |
| `page_token` | 下一页翻页 Token |
| `instances[].instance_code` | 审批实例 Code；后续查询详情或执行撤回 / 抄送时通常需要 |
| `instances[].definition_code` | 审批定义 Code |
| `instances[].definition_name` | 审批定义名称 |
| `instances[].definition_group_id` | 审批定义分组 ID |
| `instances[].definition_group_name` | 审批定义分组名称 |
| `instances[].initiator` | 发起人 ID |
| `instances[].initiator_name` | 发起人姓名 |
| `instances[].instance_status` | 审批实例状态，见下方“instance_status 枚举” |
| `instances[].instance_external_id` | 第三方审批实例 ID（仅第三方审批实例存在） |
| `instances[].link` | 三方审批跳转链接 |
| `instances[].summaries` | 摘要字段列表 |
## instance_status 枚举
| 值 | 含义 |
|----|------|
| `0` | 无流程状态，不展示对应标签 |
| `1` | 流程实例流转中 |
| `2` | 已通过 |
| `3` | 已拒绝 |
| `4` | 已撤销 |
| `5` | 已终止 |
## 常见使用场景
### 1) 找到我要操作的审批实例
```bash
lark-cli approval instances initiated --params '{"page_size":20}' --format table --as user
```
拿到 `instances[].instance_code` 后，可继续：
```bash
# 查看审批实例详情
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
# 撤回审批实例
lark-cli approval instances cancel --data '{"instance_code":"<INSTANCE_CODE>"}' --as user --yes
```
### 2) 只看某类审批
```bash
lark-cli approval instances initiated \
--params '{"definition_code":"<DEFINITION_CODE>","page_size":20}' \
--as user
```
## 使用建议
- **这是定位“我发起的审批实例”的首选命令**：如果你的目标是撤回、抄送、查看某个已发起审批，优先从这里拿 `instance_code`。
- **优先用 `definition_code` 缩小范围**：当你已知审批定义时，先筛掉无关实例，可显著提升可读性。
- **需要搜索时传入 `keyword`**：搜索排序和普通列表排序不同，按搜索服务结果为准。
- **按时间排查时使用 `start_timestamp` / `end_timestamp`**：这两个值都是秒级时间戳，用于按发起时间缩小结果范围。
- **结果很多时优先 `--format table`**：适合人工快速浏览。
- **`count` 只在第一页返回**：做分页处理时不要假设后续页还会带总数。
- **`instance_status` 可直接判断下一步**：例如状态为 `1` 时通常可继续查看详情或考虑撤回，状态为 `4` 表示已经撤销，无需重复撤回。
- **摘要字段 `summaries` 很适合做列表预览**：当审批标题不够明确时，可结合摘要值帮助识别目标实例。
## 输出与后续操作
拿到列表后，常见下一步：
```bash
# 查看单个审批实例详情
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
# 撤回审批实例
lark-cli approval instances cancel --data '{"instance_code":"<INSTANCE_CODE>"}' --as user --yes
# 给审批实例追加抄送人
lark-cli approval instances cc --data '{"instance_code":"<INSTANCE_CODE>","cc_user_ids":["<USER_ID>"]}' --params '{"user_id_type":"open_id"}' --as user --yes
```
references/lark-approval-tasks-add-sign.md›
# approval tasks add_sign
给一个审批任务加签（用户级写操作）。通常先通过 `tasks query` 拿到 `task_id` 和 `instance_code`，确认目标任务后，再提供被加签人的用户 ID、加签方式等参数执行加签。
> [!CAUTION]
> 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览；真正执行时，如果用户已明确要对该审批任务加签且目标任务、加签对象、加签方式都无误，再带 `--yes` 运行。用户已明确要求立即执行且列清本轮的加签、转交对象时，该确认覆盖这两个已明确的动作，不要逐条重复询问；不要在未获用户明确同意时静默追加 `--yes`。
需要的 scopes: ["approval:task:write"]
## 先选择加签类型
`add_sign_type` 会影响当前用户的审批任务是否继续可操作，不能只按示例顺序或任意选择：
| 用户意图 | `add_sign_type` | 处理方式 |
|----------|-----------------|----------|
| 明确说前加签 / “先让某人审核，我再审” | `1` | 前加签，并按用户要求选择 `approval_method` |
| 明确说后加签 / “我处理完，再让某人审核” | `2` | 后加签，并按用户要求选择 `approval_method` |
| “拉进来一起审” / “共同审核” / “一并确认” | `3` | 并加签；不传 `approval_method` |
| 同一请求要求先加签、再转交当前用户这一环 | `3` | **必须并加签**；加签成功后再转交当前任务 |
前加签或后加签可能推动当前用户的 task 流转，使原 `task_id` 不再支持后续转交。因此，“先加签，再把我这一环转交给其他人”不能使用前加签或后加签；先以 `add_sign_type: 3` 并加签，确认 `tasks add_sign` 成功后，再使用同一组 `instance_code` + `task_id` 执行 `tasks transfer`。
只有在上下文完全无法判断是哪种加签方式、且不同选择会改变审批流程时，才向用户二次询问。用户已经说“一起审”或已经要求“加签后转交当前环节”时，信息足够，不要再询问加签类型。
## 再选择 approval_method
只有前加签、后加签需要 `approval_method`；并加签不传。先遵循用户明确指定的审批方式；用户未指定时，按人数和语义选择：
| 加签人数与语义 | `approval_method` | 处理方式 |
|----------------|-------------------|----------|
| 只有 1 名加签人 | `1` | 使用或签；单人时或签、会签的实际效果相同，不再询问 |
| 多人，明确“任一人审批即可” / “一人通过即可” | `1` | 或签；任一加签人完成审批即可 |
| 多人，明确“所有人都要审批” / “全部确认” | `2` | 会签；所有加签人都必须完成审批 |
| 多人，明确“依次审批” / “先 A 后 B” | `3` | 依次审批；每个人按 `add_sign_user_ids` 的数组顺序逐一审批 |
| 多人，无法从上下文推断 | 不预设 | 询问用户选择或签、会签或依次审批，并说明三者效果 |
依次审批必须保留用户给出的人员顺序。如果已经确定要依次审批，但上下文无法判断先后顺序，先询问人员顺序，再构造 `add_sign_user_ids`；不要自行排序。
## 命令
```bash
# 先预览并加签请求，不实际执行
lark-cli approval tasks add_sign \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":3,"add_sign_user_ids":["ou_xxx"],"comment":"请项目 owner 一起审核"}' \
--params '{"user_id_type":"open_id"}' \
--as user \
--dry-run
# 单人前加签：未指定方式时使用或签
lark-cli approval tasks add_sign \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":1,"add_sign_user_ids":["ou_xxx"],"approval_method":1,"comment":"请先补充审核"}' \
--params '{"user_id_type":"open_id"}' \
--as user \
--yes
# 多人后加签：所有人都需要审批，使用会签
lark-cli approval tasks add_sign \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":2,"add_sign_user_ids":["ou_xxx","ou_yyy"],"approval_method":2,"comment":"当前审批完成后请两位都完成审核"}' \
--params '{"user_id_type":"open_id"}' \
--as user \
--yes
# 多人前加签：按数组中的人员顺序依次审批
lark-cli approval tasks add_sign \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":1,"add_sign_user_ids":["ou_first","ou_second"],"approval_method":3,"comment":"请先由第一位审核，再由第二位审核"}' \
--params '{"user_id_type":"open_id"}' \
--as user \
--yes
# 同一请求要求先加签、再转交：必须并加签；两条命令按顺序执行
lark-cli approval tasks add_sign \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","add_sign_type":3,"add_sign_user_ids":["ou_reviewer"],"comment":"请一起审核"}' \
--params '{"user_id_type":"open_id"}' \
--as user \
--yes
# 仅在上面的 add_sign 成功后，转交同一当前任务
lark-cli approval tasks transfer \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","transfer_user_id":"ou_transferee","comment":"出差期间请代为处理"}' \
--params '{"user_id_type":"open_id"}' \
--as user \
--yes
# 通过文件传入请求体，适合较长 comment 或较多加签人
lark-cli approval tasks add_sign \
--data @./add-sign-body.json \
--params '{"user_id_type":"open_id"}' \
--as user \
--yes
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--data '{...}'` | 是 | 请求体 JSON，使用 JSON 传入 |
| `instance_code` | 是 | 审批实例 Code；通常先通过 `tasks query` 或 `instances initiated` / `instances get` 获取 |
| `task_id` | 是 | 审批任务 ID；通常先通过 `tasks query` 获取 |
| `add_sign_type` | 是 | 加签类型：`1` 前加签、`2` 后加签、`3` 并加签 |
| `add_sign_user_ids` | 是 | 被加签人 ID 数组；需要和 `user_id_type` 保持一致 |
| `approval_method` | 否 | 审批方式：`1` 或签、`2` 会签、`3` 依次审批；**仅在前加签、后加签时需要填写**。单人未指定时使用 `1`；多人无法从语义推断时先询问用户 |
| `comment` | 否 | 审批意见或加签说明，例如 `前加签给财务复核`、`请项目 owner 一并确认` |
| `--params '{"user_id_type":"..."}'` | 否 | 查询参数 JSON；用于声明 `add_sign_user_ids` 内用户 ID 的类型 |
| `user_id_type` | 否 | 用户 ID 类型：`user_id`、`union_id`、`open_id`；未显式指定时要特别确认被加签人的 ID 类型 |
| `--as user` | 否 | 建议显式指定用户身份；审批加签通常必须以用户身份执行 |
| `--yes` | 否 | 确认执行高风险写操作；未带时可能返回 `confirmation_required` / exit 10 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 枚举说明
### add_sign_type
| 值 | 含义 | 对当前任务的影响 |
|----|------|------------------|
| `1` | 前加签 | 在当前审批前插入审批人，可能推动当前用户的 task 流转 |
| `2` | 后加签 | 在当前审批后追加审批人，可能推动当前用户的 task 流转 |
| `3` | 并加签 | 增加并行审批人；需要随后转交当前环节时使用 |
### approval_method
仅适用于前加签、后加签；并加签不传。
| 值 | 含义 | 完成条件 |
|----|------|----------|
| `1` | 或签 | 任一加签人完成审批即可 |
| `2` | 会签 | 所有加签人都必须完成审批 |
| `3` | 依次审批 | 所有加签人按 `add_sign_user_ids` 数组顺序逐一审批 |
## 典型前置步骤
先查到待办任务：
```bash
lark-cli approval tasks query --params '{"topic":"1"}' --as user
```
常用到的字段：
| 字段 | 说明 |
|------|------|
| `tasks[].instance_code` | 审批实例 Code；执行 approve / reject / transfer / rollback / add_sign 等操作时通常都需要 |
| `tasks[].task_id` | 审批任务 ID；与 `instance_code` 配对使用 |
| `tasks[].support_api_operate` | 是否支持通过 API 处理该任务；加签前建议先检查 |
如果你手里只有姓名或邮箱，建议先通过联系人能力解析出正确的用户 ID，再执行加签。
如需先确认表单、节点、审批流进度，可继续查看实例详情：
```bash
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
```
## 使用建议
- **`instance_code` 和 `task_id` 要成对使用**：仅有实例 ID 或仅有任务 ID 都不足以准确执行加签操作。
- **`add_sign_user_ids` 与 `user_id_type` 必须匹配**：例如传 open_id 就把 `user_id_type` 设为 `open_id`；不要混用。
- **优先显式传 `user_id_type`**：这样 agent 更容易判断参数含义，也能减少 ID 类型不匹配带来的失败。
- **`add_sign_type` 要和业务意图一致**：前加签是在当前审批前插入审批人，后加签是在当前审批后追加审批人，并加签则是增加并行审批人。
- **加签后还要转交当前环节时必须并加签**：使用 `add_sign_type: 3`，等待加签成功后再用同一组任务参数转交；不要用前加签或后加签导致当前 task 提前流转。
- **无法推断类型时才询问**：如果用户没有说明先后或并行关系，且后续动作也不能帮助判断，再请用户选择；不要对“一起审”或“加签后转交”重复提问。
- **前加签 / 后加签要补 `approval_method`**：单人未指定时使用或签；多人优先按语义选择，无法推断时询问用户，不要静默默认。
- **依次审批保留人员顺序**：按用户指定的先后顺序构造 `add_sign_user_ids`；顺序不明确时先询问，不要自行排序。
- **优先从 `tasks query` 的待办列表拿任务参数**：尤其是 `topic=1` 的待办审批，最适合作为 add_sign 的输入来源。
- **先检查是否支持 API 操作**：如果 `tasks[].support_api_operate` 为 `false`，说明该任务可能不支持通过 API 执行处理动作，加签前应谨慎验证。
- **`comment` 建议写明加签原因**：例如 `增加财务复核`、`增加项目 owner 并行确认`，方便相关人员理解上下文。
- **先 `--dry-run` 再执行**：尤其在多人加签、跨部门加签或加签对象来源不明确时，先预览更安全。
references/lark-approval-tasks-approve.md›
# approval tasks approve
同意一个审批任务（用户级写操作）。通常先通过 `tasks query` 拿到 `task_id` 和 `instance_code`，必要时再用 `instances get` 查看详情，然后再执行同意。
> [!CAUTION]
> 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览；真正执行时，如果用户已明确同意审批且目标任务无误，再带 `--yes` 运行。不要在未获用户明确同意时静默追加 `--yes`。
需要的 scopes: ["approval:task:write"]
## 命令
```bash
# 先预览请求，不实际执行
lark-cli approval tasks approve \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","comment":"同意"}' \
--as user \
--dry-run
# 同意审批任务，并附带审批意见
lark-cli approval tasks approve \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","comment":"同意"}' \
--as user \
--yes
# 需要回填表单时，传入 form（按当前命令定义，form 为字符串化 JSON）
lark-cli approval tasks approve \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","comment":"同意并补充信息","form":"[{\"id\":\"user_name\",\"type\":\"input\",\"value\":\"Alice\"}]"}' \
--as user \
--yes
# 通过文件传入请求体，适合较长 comment / form
lark-cli approval tasks approve \
--data @./approve-body.json \
--as user \
--yes
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--data '{...}'` | 是 | 请求体 JSON，使用 JSON 传入 |
| `instance_code` | 是 | 审批实例 Code；通常先通过 `tasks query` 或 `instances initiated` / `instances get` 获取 |
| `task_id` | 是 | 审批任务 ID；通常先通过 `tasks query` 获取 |
| `comment` | 否 | 审批意见，例如 `同意`、`已确认` |
| `form` | 否 | 表单数据；按当前命令定义，字段类型为 `string`，通常传字符串化 JSON；仅在审批动作需要同时回填表单时使用 |
| `--as user` | 否 | 建议显式指定用户身份；审批同意通常必须以用户身份执行 |
| `--yes` | 否 | 确认执行高风险写操作；未带时可能返回 `confirmation_required` / exit 10 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 典型前置步骤
先查到待办任务：
```bash
lark-cli approval tasks query --params '{"topic":"1"}' --as user
```
常用到的两个字段：
| 字段 | 说明 |
|------|------|
| `tasks[].instance_code` | 审批实例 Code；执行 approve / reject / rollback 等操作时通常都需要 |
| `tasks[].task_id` | 审批任务 ID；与 `instance_code` 配对使用 |
如需先确认表单、节点、审批流进度，可继续查看实例详情：
```bash
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
```
## 使用建议
- **`instance_code` 和 `task_id` 要成对使用**：仅有实例 ID 或仅有任务 ID 都不足以准确执行同意操作。
- **优先从 `tasks query` 的待办列表拿参数**：尤其是 `topic=1` 的待办审批，最适合作为 approve 的输入来源。
- **先检查是否支持 API 操作**：如果上一步 `tasks query` 返回的 `tasks[].support_api_operate` 为 `false`，说明该任务可能不支持通过 API 同意/拒绝。
- **`comment` 建议简洁明确**：例如 `同意`、`同意，信息已核对`。没有审批意见要求时可省略。
- **`form` 只在确有需要时传**：大多数简单同意场景只传 `instance_code`、`task_id`、可选 `comment` 即可。
- **先 `--dry-run` 再执行**：尤其在批量处理、表单回填或任务来源不明确时，先预览更安全。
references/lark-approval-tasks-query.md›
# approval tasks query
查询当前用户的审批任务列表，可用于查看待办、已办、知会等分组。只读操作，不会修改审批状态。
需要的 scopes: ["approval:task:read"]
## 命令
```bash
# 查询待办审批
lark-cli approval tasks query --params '{"topic":"1"}' --as user
# 查询已办审批
lark-cli approval tasks query --params '{"topic":"2"}' --as user
# 按关键词搜索任务列表
lark-cli approval tasks query --params '{"topic":"1","keyword":"测试","page_size":10}' --as user
# 按任务时间范围筛选（秒级时间戳）
lark-cli approval tasks query --params '{"topic":"1","start_timestamp":"<START_SECONDS>","end_timestamp":"<END_SECONDS>"}' --as user
# 使用 page_token 翻页
lark-cli approval tasks query --params '{"topic":"1","page_token":"example_page_token"}' --as user
# 表格格式输出，便于快速浏览
lark-cli approval tasks query --params '{"topic":"1"}' --format table --as user
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--params '{"topic":"..."}'` | 是 | 查询参数，使用 JSON 传入 |
| `topic` | 是 | 任务分组主题，见下方“topic 枚举” |
| `definition_code` | 否 | 审批定义 Code，用于仅查询某个审批定义下的任务 |
| `keyword` | 否 | 搜索关键词；非空时走搜索链路，空或仅空格时保持普通列表链路 |
| `start_timestamp` | 否 | 按任务时间筛选，时间范围开始值，秒级时间戳 |
| `end_timestamp` | 否 | 按任务时间筛选，时间范围结束值，秒级时间戳 |
| `locale` | 否 | 返回语言：`zh-CN`、`en-US`、`ja-JP` |
| `page_size` | 否 | 分页大小 |
| `page_token` | 否 | 翻页标记；首次请求不填，后续使用上一次返回的 `page_token` |
| `user_id_type` | 否 | 用户 ID 类型：`user_id`、`union_id`、`open_id` |
| `--as user` | 否 | 建议显式指定用户身份；审批任务查询通常应使用用户身份 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## topic 枚举
| 值 | 含义 |
|----|------|
| `1` | 待办审批 |
| `2` | 已办审批 |
| `17` | 未读知会 |
| `18` | 已读知会 |
## 输出重点字段
返回结果中常见字段：
| 字段 | 说明 |
|------|------|
| `count` | 列表计数，只在第一页返回；当任务数大于等于 100 时返回 `99` |
| `has_more` | 是否还有更多数据 |
| `page_token` | 下一页翻页 Token |
| `tasks[].task_id` | 任务 ID，全局唯一 |
| `tasks[].instance_code` | 审批实例 Code；后续执行 approve / reject / rollback 等操作时通常需要与 `task_id` 成对使用 |
| `tasks[].title` | 任务标题 |
| `tasks[].status` | 任务状态：`1` 待办、`2` 已办、`17` 未读、`18` 已读、`33` 处理中、`34` 撤回 |
| `tasks[].topic` | 任务所属分组主题 |
| `tasks[].instance_status` | 审批实例状态：`0` 无状态、`1` 流转中、`2` 已通过、`3` 已拒绝、`4` 已撤销、`5` 已终止 |
| `tasks[].definition_code` | 审批定义 Code |
| `tasks[].definition_name` | 审批定义名称 |
| `tasks[].initiator` | 发起人 ID |
| `tasks[].initiator_name` | 发起人姓名 |
| `tasks[].summaries` | 表单摘要字段列表 |
| `tasks[].support_api_operate` | 是否支持通过 API 同意或拒绝该任务 |
| `tasks[].user_id` | 任务所属用户 ID |
| `tasks[].instance_external_id` | 三方审批实例 ID，仅第三方审批实例存在 |
| `tasks[].task_external_id` | 三方审批任务 ID，仅第三方审批任务存在 |
| `tasks[].link` | 三方审批跳转链接 |
## 使用建议
- 常见处理链：先用 `tasks query` 拿到 `task_id` 和 `instance_code`，若用户需要查看详情、当前节点、表单内容、流程进度等内容，则调用 `instances get` 查看详情，最后执行 `tasks approve` / `tasks reject` / `tasks transfer` / `tasks add_sign` / `tasks rollback`。
- 如果你只想看“已发起的审批实例”，使用 `instances initiated`；`tasks query` 更适合围绕“任务分组”来拉取列表。
- 需要搜索任务标题、摘要或相关内容时传入 `keyword`；搜索排序和普通列表排序不同，按搜索服务结果为准。
- 按时间排查任务时使用 `start_timestamp` / `end_timestamp` 缩小范围；这两个值都是秒级时间戳。
- 需要继续翻页时，直接把上一次返回的 `page_token` 放回 `--params`。
- 当结果量较大时，优先使用 `--format table` 提升可读性。
references/lark-approval-tasks-reject.md›
# approval tasks reject
拒绝一个审批任务（用户级写操作）。通常先通过 `tasks query` 拿到 `task_id` 和 `instance_code`，必要时再用 `instances get` 查看详情，然后再执行拒绝。
> [!CAUTION]
> 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览；真正执行时，如果用户已明确要拒绝该审批且目标任务无误，再带 `--yes` 运行。不要在未获用户明确同意时静默追加 `--yes`。
需要的 scopes: ["approval:task:write"]
## 命令
```bash
# 先预览请求，不实际执行
lark-cli approval tasks reject \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","comment":"拒绝"}' \
--as user \
--dry-run
# 拒绝审批任务，并附带审批意见
lark-cli approval tasks reject \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","comment":"拒绝，信息不完整"}' \
--as user \
--yes
# 通过文件传入请求体，适合较长 comment
lark-cli approval tasks reject \
--data @./reject-body.json \
--as user \
--yes
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--data '{...}'` | 是 | 请求体 JSON，使用 JSON 传入 |
| `instance_code` | 是 | 审批实例 Code；通常先通过 `tasks query` 或 `instances initiated` / `instances get` 获取 |
| `task_id` | 是 | 审批任务 ID；通常先通过 `tasks query` 获取 |
| `comment` | 否 | 审批意见，例如 `拒绝`、`拒绝，信息不完整` |
| `--as user` | 否 | 建议显式指定用户身份；审批拒绝通常必须以用户身份执行 |
| `--yes` | 否 | 确认执行高风险写操作；未带时可能返回 `confirmation_required` / exit 10 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 典型前置步骤
先查到待办任务：
```bash
lark-cli approval tasks query --params '{"topic":"1"}' --as user
```
常用到的两个字段：
| 字段 | 说明 |
|------|------|
| `tasks[].instance_code` | 审批实例 Code；执行 approve / reject / rollback 等操作时通常都需要 |
| `tasks[].task_id` | 审批任务 ID；与 `instance_code` 配对使用 |
如需先确认表单、节点、审批流进度，可继续查看实例详情：
```bash
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
```
## 使用建议
- **`instance_code` 和 `task_id` 要成对使用**：仅有实例 ID 或仅有任务 ID 都不足以准确执行拒绝操作。
- **优先从 `tasks query` 的待办列表拿参数**：尤其是 `topic=1` 的待办审批，最适合作为 reject 的输入来源。
- **先检查是否支持 API 操作**：如果上一步 `tasks query` 返回的 `tasks[].support_api_operate` 为 `false`，说明该任务可能不支持通过 API 同意/拒绝。
- **`comment` 建议写清拒绝原因**：例如 `拒绝，缺少合同附件`、`拒绝，预算字段填写不完整`。这有助于发起人理解原因并补充材料。
- **先 `--dry-run` 再执行**：尤其在批量处理或任务来源不明确时，先预览更安全。
references/lark-approval-tasks-remind.md›
# approval tasks remind
对审批实例中的指定任务发起催办（用户级写操作）。通常先通过 `tasks query` 找到待办任务，拿到 `instance_code` 和要催办的 `task_ids`，必要时再用 `instances get` 查看详情，然后执行催办。
> [!CAUTION]
> 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览；真正执行时，如果用户已明确要催办该审批且目标实例、目标任务都无误，再带 `--yes` 运行。不要在未获用户明确同意时静默追加 `--yes`。
需要的 scopes: ["approval:instance:write"]
## 命令
```bash
# 先预览请求，不实际执行
lark-cli approval tasks remind \
--data '{"instance_code":"<INSTANCE_CODE>","task_ids":["<TASK_ID>"],"comment":"请尽快处理"}' \
--as user \
--dry-run
# 催办单个审批任务
lark-cli approval tasks remind \
--data '{"instance_code":"<INSTANCE_CODE>","task_ids":["<TASK_ID>"],"comment":"请尽快审批该单据"}' \
--as user \
--yes
# 同一实例下催办多个任务
lark-cli approval tasks remind \
--data '{"instance_code":"<INSTANCE_CODE>","task_ids":["<TASK_ID_1>","<TASK_ID_2>"],"comment":"请相关审批人尽快处理"}' \
--as user \
--yes
# 通过文件传入请求体，适合较长 comment 或多个 task_ids
lark-cli approval tasks remind \
--data @./remind-body.json \
--as user \
--yes
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--data '{...}'` | 是 | 请求体 JSON，使用 JSON 传入 |
| `instance_code` | 是 | 审批实例 Code；通常先通过 `tasks query` 或 `instances get` 获取 |
| `task_ids` | 是 | 被催办的任务 ID 数组；应与 `instance_code` 属于同一审批实例 |
| `comment` | 否 | 催办说明，例如 `请尽快处理`、`该单据较急，请优先审批` |
| `--as user` | 否 | 建议显式指定用户身份；审批催办通常必须以用户身份执行 |
| `--yes` | 否 | 确认执行高风险写操作；未带时可能返回 `confirmation_required` / exit 10 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 典型前置步骤
先查到待办任务：
```bash
lark-cli approval tasks query --params '{"topic":"1"}' --as user
```
常用到的字段：
| 字段 | 说明 |
|------|------|
| `tasks[].instance_code` | 审批实例 Code；催办时必须提供 |
| `tasks[].task_id` | 审批任务 ID；放入 `task_ids` 数组中 |
| `tasks[].title` | 任务标题，可用于确认催办对象是否正确 |
| `tasks[].status` | 任务状态；一般优先催办仍处于待处理状态的任务 |
如需进一步确认当前审批流、节点和人员信息，可继续查看实例详情：
```bash
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
```
## 使用建议
- **`instance_code` 和 `task_ids` 要对应同一个审批实例**：不要把不同实例下的任务 ID 混在同一次催办请求中。
- **`task_ids` 是数组**：即使只催办一个任务，也要按数组形式传入。
- **优先从 `tasks query` 的待办列表拿参数**：尤其是 `topic=1` 的待办审批，最适合作为 remind 的输入来源。
- **催办前先确认任务仍需处理**：已经审批完成、已撤回或已终止的任务一般不适合继续催办。
- **`comment` 建议简洁且明确**：例如 `该单据较急，请优先审批`、`请今天内处理`。避免过长或模糊描述。
- **先 `--dry-run` 再执行**：尤其在一次催办多个任务、任务来源不明确或需让用户复核催办对象时，先预览更安全。
references/lark-approval-tasks-rollback.md›
# approval tasks rollback
将一个审批任务退回到指定节点（用户级写操作）。通常先通过 `tasks query` 拿到 `task_id` 和 `instance_code`，再结合实例详情确认可退回的目标节点 `node_ids`，最后执行退回。
> [!CAUTION]
> 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览；真正执行时，如果用户已明确要退回该审批且目标任务、退回节点都无误，再带 `--yes` 运行。不要在未获用户明确同意时静默追加 `--yes`。
需要的 scopes: ["approval:task:write"]
## 命令
```bash
# 先预览请求，不实际执行
lark-cli approval tasks rollback \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","node_ids":["<NODE_ID>"],"comment":"退回补充材料"}' \
--as user \
--dry-run
# 退回到单个节点
lark-cli approval tasks rollback \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","node_ids":["<NODE_ID>"],"comment":"请补充附件后重新提交"}' \
--as user \
--yes
# 退回到发起节点（发起节点 ID 为 START）
lark-cli approval tasks rollback \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","node_ids":["START"],"comment":"退回发起人补充材料"}' \
--as user \
--yes
# 传多个候选节点 ID（以实际审批定义支持情况为准）
lark-cli approval tasks rollback \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","node_ids":["<NODE_ID_1>","<NODE_ID_2>"],"comment":"退回上一处理节点"}' \
--as user \
--yes
# 通过文件传入请求体，适合较长 comment 或较多 node_ids
lark-cli approval tasks rollback \
--data @./rollback-body.json \
--as user \
--yes
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--data '{...}'` | 是 | 请求体 JSON，使用 JSON 传入 |
| `instance_code` | 是 | 审批实例 Code；通常先通过 `tasks query` 或 `instances initiated` / `instances get` 获取 |
| `task_id` | 是 | 审批任务 ID；通常先通过 `tasks query` 获取 |
| `node_ids` | 是 | 退回目标节点 ID 数组；发起节点 ID 为 `START`；执行前应先确认这些节点确实可作为退回目标 |
| `comment` | 否 | 审批意见或退回说明，例如 `请补充附件后重新提交`、`预算说明不完整，请补充` |
| `--as user` | 否 | 建议显式指定用户身份；审批退回通常必须以用户身份执行 |
| `--yes` | 否 | 确认执行高风险写操作；未带时可能返回 `confirmation_required` / exit 10 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 典型前置步骤
先查到待办任务：
```bash
lark-cli approval tasks query --params '{"topic":"1"}' --as user
```
常用到的字段：
| 字段 | 说明 |
|------|------|
| `tasks[].instance_code` | 审批实例 Code；执行 approve / reject / transfer / rollback 等操作时通常都需要 |
| `tasks[].task_id` | 审批任务 ID；与 `instance_code` 配对使用 |
| `tasks[].support_api_operate` | 是否支持通过 API 处理该任务；退回前建议先检查 |
如需确认流程节点、当前进度和可退回位置，可先查看实例详情：
```bash
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
```
## 使用建议
- **`instance_code` 和 `task_id` 要成对使用**：仅有实例 ID 或仅有任务 ID 都不足以准确执行退回操作。
- **`node_ids` 是必填项**：退回并不是“自动退回上一步”，而是要明确给出目标节点 ID 数组；退回发起节点时传 `START`。
- **先确认节点是否可退回**：不同审批定义支持的退回目标可能不同；在不确定时，先通过 `instances get` 或业务侧流程信息核实。
- **优先从 `tasks query` 的待办列表拿任务参数**：尤其是 `topic=1` 的待办审批，最适合作为 rollback 的输入来源。
- **先检查是否支持 API 操作**：如果 `tasks[].support_api_operate` 为 `false`，说明该任务可能不支持通过 API 执行处理动作，退回前应谨慎验证。
- **`comment` 建议写清退回原因**：例如 `附件缺失，请补齐后重新提交`、`费用说明不完整，请补充明细`，方便发起人或上一步处理人理解原因。
- **先 `--dry-run` 再执行**：尤其在节点来源不明确、审批链路复杂或批量处理时，先预览更安全。
references/lark-approval-tasks-transfer.md›
# approval tasks transfer
转交一个审批任务给其他用户处理（用户级写操作）。通常先通过 `tasks query` 拿到 `task_id` 和 `instance_code`，确认目标任务后，再提供被转交人的用户 ID 执行转交。
> [!CAUTION]
> 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览；真正执行时，如果用户已明确要转交该审批且目标任务、转交对象都无误，再带 `--yes` 运行。不要在未获用户明确同意时静默追加 `--yes`。
需要的 scopes: ["approval:task:write"]
## 命令
```bash
# 先预览请求，不实际执行
lark-cli approval tasks transfer \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","transfer_user_id":"ou_xxx","comment":"请你继续处理"}' \
--params '{"user_id_type":"open_id"}' \
--as user \
--dry-run
# 按 open_id 转交审批任务
lark-cli approval tasks transfer \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","transfer_user_id":"ou_xxx","comment":"转交给你处理"}' \
--params '{"user_id_type":"open_id"}' \
--as user \
--yes
# 按 user_id 转交审批任务
lark-cli approval tasks transfer \
--data '{"instance_code":"<INSTANCE_CODE>","task_id":"<TASK_ID>","transfer_user_id":"123456789","comment":"请补充审核"}' \
--params '{"user_id_type":"user_id"}' \
--as user \
--yes
# 通过文件传入请求体，适合较长 comment
lark-cli approval tasks transfer \
--data @./transfer-body.json \
--params '{"user_id_type":"open_id"}' \
--as user \
--yes
```
## 参数
| 参数 | 必填 | 说明 |
|------|------|------|
| `--data '{...}'` | 是 | 请求体 JSON，使用 JSON 传入 |
| `instance_code` | 是 | 审批实例 Code；通常先通过 `tasks query` 或 `instances initiated` / `instances get` 获取 |
| `task_id` | 是 | 审批任务 ID；通常先通过 `tasks query` 获取 |
| `transfer_user_id` | 是 | 被转交人的用户 ID；需要和 `user_id_type` 保持一致 |
| `comment` | 否 | 审批意见或转交说明，例如 `转交给你处理`、`请继续审核该单据` |
| `--params '{"user_id_type":"..."}'` | 否 | 查询参数 JSON；用于声明 `transfer_user_id` 的 ID 类型 |
| `user_id_type` | 否 | 用户 ID 类型：`user_id`、`union_id`、`open_id`；未显式指定时要特别确认 `transfer_user_id` 的真实类型 |
| `--as user` | 否 | 建议显式指定用户身份；审批转交通常必须以用户身份执行 |
| `--yes` | 否 | 确认执行高风险写操作；未带时可能返回 `confirmation_required` / exit 10 |
| `--format` | 否 | 输出格式：`json`（默认）、`ndjson`、`table`、`csv` |
| `--dry-run` | 否 | 预览 API 调用，不执行 |
## 典型前置步骤
先查到待办任务：
```bash
lark-cli approval tasks query --params '{"topic":"1"}' --as user
```
常用到的字段：
| 字段 | 说明 |
|------|------|
| `tasks[].instance_code` | 审批实例 Code；执行 approve / reject / transfer / rollback 等操作时通常都需要 |
| `tasks[].task_id` | 审批任务 ID；与 `instance_code` 配对使用 |
| `tasks[].support_api_operate` | 是否支持通过 API 处理该任务；转交前建议先检查 |
如果你手里只有姓名或邮箱，建议先通过联系人能力解析出正确的用户 ID，再执行转交。
如需先确认表单、节点、审批流进度，可继续查看实例详情：
```bash
lark-cli approval instances get --params '{"instance_code":"<INSTANCE_CODE>"}' --as user
```
## 使用建议
- **`instance_code` 和 `task_id` 要成对使用**：仅有实例 ID 或仅有任务 ID 都不足以准确执行转交操作。
- **`transfer_user_id` 与 `user_id_type` 必须匹配**：例如传 open_id 就把 `user_id_type` 设为 `open_id`；不要混用。
- **优先显式传 `user_id_type`**：这样 agent 更容易判断参数含义，也能减少 ID 类型不匹配带来的失败。
- **优先从 `tasks query` 的待办列表拿任务参数**：尤其是 `topic=1` 的待办审批，最适合作为 transfer 的输入来源。
- **先检查是否支持 API 操作**：如果 `tasks[].support_api_operate` 为 `false`，说明该任务可能不支持通过 API 执行同意/拒绝等处理动作，转交前也应谨慎验证。
- **`comment` 建议写明转交原因**：例如 `你更熟悉该项目，请继续处理`、`转交给预算 owner 审核`，方便接收人理解上下文。
- **先 `--dry-run` 再执行**：尤其在跨部门转交、批量处理或转交对象来源不明确时，先预览更安全。
SKILL.md›
---
name: lark-approval
version: 1.2.0
description: "飞书审批：查询和处理审批待办/已办/实例，搜索可发起审批定义、查看定义详情并发起原生审批实例。当用户要处理审批任务、查看审批实例、搜索或发起审批时使用。审批待办不是飞书任务；非审批类待办走 lark-task。不负责创建审批定义；三方审批定义不走原生提单。"
metadata:
requires:
bins: ["lark-cli"]
cliHelp: "lark-cli approval --help"
---
**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
所有命令默认 `--as user`（审批是人的动作）。调用前先按需读取 references 下对应的文件，查参数结构，不要猜字段；**references 是第一信息源**，只有在 reference 未覆盖的原生 / 高级场景下，才额外用 `lark-cli ... --help`、`lark-cli schema` 等方式补充确认字段。
## 路由优先级（先判断是不是审批，再选命令）
审批待办不是飞书任务。**只要用户的核心对象是审批单据 / 审批待办 / 审批实例，就优先使用 `lark-approval`，不要让渡给 `lark-task`。**
### 明确归 `lark-approval` 的高优先级语义
出现以下任一语义时，优先走 `lark-approval`：
- 审批待办 / 审批单据 / 审批实例 / 审批意见 / 审批定义
- 同意 / 拒绝 / 转交 / 退回 / 撤回 / 催办 / 加签 / 抄送
- 待办列表 / 待办单据 / 已发起审批 / 已办审批 / 审批详情 / 同意可编辑
**判定规则：** 只要最终动作是对审批单据做同意、拒绝、转交、退回、撤回、催办、加签、抄送、查详情、查已发起/已办/待办，就归 `lark-approval`。只有当用户处理的是**非审批类任务/待办**时，才走 [`lark-task`](../lark-task/SKILL.md)。
## 选哪个命令
| 想做什么 | 命令 | 按需读取 reference |
|---|---|---------------------------------------------------------------------------------|
| 搜可发起定义 | `approvals search` | [`lark-approval-approvals-search.md`](references/lark-approval-approvals-search.md) |
| 看审批定义详情/提单前确认表单与流程 | `approvals get` | [`lark-approval-approvals-get.md`](references/lark-approval-approvals-get.md) |
| 发起原生审批实例/提交请假审批/提交报销审批/创建审批实例 | `instances create` | [`lark-approval-initiate.md`](references/lark-approval-initiate.md) |
| 查/搜待办、已办 | `tasks query`（`topic`：1待办 2已办 17未读 18已读） | [`lark-approval-tasks-query.md`](references/lark-approval-tasks-query.md) |
| 看表单/进度/当前节点 | `instances get` | [`lark-approval-instances-get.md`](references/lark-approval-instances-get.md) |
| 同意审批 | `tasks approve` | [`lark-approval-tasks-approve.md`](references/lark-approval-tasks-approve.md) |
| 拒绝审批 | `tasks reject` | [`lark-approval-tasks-reject.md`](references/lark-approval-tasks-reject.md) |
| 转交审批 | `tasks transfer` | [`lark-approval-tasks-transfer.md`](references/lark-approval-tasks-transfer.md) |
| 加签审批 | `tasks add_sign` | [`lark-approval-tasks-add-sign.md`](references/lark-approval-tasks-add-sign.md) |
| 退回审批 | `tasks rollback` | [`lark-approval-tasks-rollback.md`](references/lark-approval-tasks-rollback.md) |
| 催办审批 | `tasks remind` | [`lark-approval-tasks-remind.md`](references/lark-approval-tasks-remind.md) |
| 撤回已发起审批 | `instances cancel` | [`lark-approval-instances-cancel.md`](references/lark-approval-instances-cancel.md) |
| 给审批实例追加抄送 | `instances cc` | [`lark-approval-instances-cc.md`](references/lark-approval-instances-cc.md) |
| 按定义/关键词查已发起审批 | `instances initiated` | [`lark-approval-instances-initiated.md`](references/lark-approval-instances-initiated.md) |
处理链：
- 发起审批：`approvals search` -> `approvals get` -> `instances create`
- 处理审批：`tasks query` 拿 `instance_code` + `task_id`（操作必须成对带上）→ 只有用户明确需要查看详情、当前节点、表单内容、或流程进度时，再 `instances get` → 执行操作
## 执行原则（减少误路由、误重试和无效消耗）
### 1) 先拿最小必要信息，再执行
- 目标只是处理待办时，优先 `tasks query` 获取 `instance_code` + `task_id`
- **只有**用户明确要看详情、当前节点、表单内容、流程进度时，才调用 `instances get`
- 用户已经明确给出 `instance_code` / `task_id` 时，不要先查列表再过滤
### 2) 已知对象时直达动作
- 已拿到 `instance_code` + `task_id` 后，优先直接执行 `tasks approve/reject/transfer/add_sign/rollback/remind`
- 同一轮里如果已有足够的新鲜查询结果，不要重复 `tasks query`
- 不要默认走 `list -> filter -> detail -> write` 全链路；对象已明确时应压缩步骤
### 3) 错误码驱动，而不是盲目重试
- 写操作失败后，先看错误码和报错语义，再决定是否补查或结束
- **除非错误明确提示可恢复或需要补充参数，否则不要重复刷同一个写操作**
- 同一个失败原因不要连续多次重试，避免 token 和耗时失控，最多重试1次
## 写操作失败处理：1395001 决策树
当拒绝 / 转交 / 退回 / 撤回 / 同意等写操作返回 `1395001`（任务状态异常 / 写前置校验失败）时，按下面规则处理：
1. **先停止盲目重试**，不要连续重复提交相同写操作，最多重试1次
2. 优先从以下角度解释：
- 任务可能已被他人处理
- 单据状态已变化，当前动作已不再允许
- 当前用户已不具备该任务的操作资格
- 当前节点或单据状态不支持该操作
3. 如需确认，只补 **一次** 状态查询（`tasks query` 或 `instances get`），不要陷入 query/write 循环
4. 最终给用户明确结论和下一步建议，而不是继续无意义重试
**特别注意：** 对拒绝 / 转交 / 撤回场景更要严格执行上述规则；这些场景最容易因状态切换而失败。
```bash
lark-cli approval approvals search --data '{"keyword":"请假"}' --as user
lark-cli approval approvals get --params '{"approval_code":"<code>"}' --as user
lark-cli approval instances create --data '{"approval_code":"<code>","form":"[...]"}' --yes --as user
lark-cli approval tasks query --params '{"topic":"1"}' --as user
lark-cli approval tasks approve --data '{"instance_code":"<ic>","task_id":"<tid>","comment":"同意"}' --as user
```
## 不在本 skill 范围
创建审批定义（走飞书客户端或审批管理后台）；三方定义发起（返回 `create_link`，引导用户通过链接发起）；非审批类待办 → [`lark-task`](../lark-task/SKILL.md)