@amaster.ai/pi-lark 0.1.4 → 0.1.6

package/skills/lark-approval/references/lark-approval-instance-value-sourcing.md

@@ -0,0 +1,108 @@
+# 审批提单值来源
+
+## 目的
+
+本文用于回答一个固定问题：在调用 `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` |

package/skills/lark-approval/references/lark-approval-instances-cancel.md

@@ -0,0 +1,78 @@
+
+# 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` 再执行**：尤其在实例来源不明确、用户只给了标题关键字，或一次要核对多个实例时，先预览更安全。

package/skills/lark-approval/references/lark-approval-instances-cc.md

@@ -0,0 +1,105 @@
+
+# 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` 再执行**：尤其在抄送对象较多、抄送人来源不明确，或需要让用户先核对实例标题时，先预览更安全。

package/skills/lark-approval/references/lark-approval-instances-get.md

@@ -0,0 +1,145 @@
+
+# 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
+```

package/skills/lark-approval/references/lark-approval-instances-initiated.md

@@ -0,0 +1,128 @@
+
+# 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 '{"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，用于只查看某个审批定义下我发起的实例 |
+| `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` 缩小范围**：当你已知审批定义时，先筛掉无关实例，可显著提升可读性。
+- **按时间排查时使用 `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
+```