diff --git a/skills/lark-approval/SKILL.md b/skills/lark-approval/SKILL.md index 8bf2e7d61..dbac5cf33 100644 --- a/skills/lark-approval/SKILL.md +++ b/skills/lark-approval/SKILL.md @@ -14,14 +14,19 @@ metadata: ## 选哪个命令 -| 想做什么 | 命令 | -|---|---| -| 查待办/已办 | `tasks query`（`topic`：1待办 2已办 17未读 18已读）| -| 看表单/进度/当前节点 | `instances get` | -| 同意/拒绝 | `tasks approve` / `tasks reject` | -| 转交/加签/退回 | `tasks transfer` / `tasks add_sign` / `tasks rollback` | -| 催办 | `tasks remind` | -| 撤回/抄送/按定义查已发起 | `instances cancel` / `instances cc` / `instances initiated` | +| 想做什么 | 命令 | 按需读取 reference | +|---|---|---| +| 查待办/已办 | `tasks query`（`topic`：1待办 2已办 17未读 18已读） | [`lark-approval-tasks-query.md`](references/lark-approval-tasks-query.md) | +| 看表单/进度/当前节点 | `instances get` | [`lark-approval-instance-get.md`](references/lark-approval-instance-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-instance-cancel.md`](references/lark-approval-instance-cancel.md) | +| 给审批实例追加抄送 | `instances cc` | [`lark-approval-instance-cc.md`](references/lark-approval-instance-cc.md) | +| 按定义查已发起审批 | `instances initiated` | [`lark-approval-instance-initiated.md`](references/lark-approval-instance-initiated.md) | 处理链：`tasks query` 拿 `instance_code` + `task_id`（操作必须成对带上）→ 需要细节再 `instances get` → 执行操作。 diff --git a/skills/lark-approval/references/lark-approval-instance-cancel.md b/skills/lark-approval/references/lark-approval-instance-cancel.md new file mode 100644 index 000000000..c58bbbac2 --- /dev/null +++ b/skills/lark-approval/references/lark-approval-instance-cancel.md @@ -0,0 +1,106 @@ + +# approval instances cancel + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +撤回一个已发起的审批实例（用户级写操作）。通常先通过 `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":""}' \ + --as user \ + --dry-run + +# 撤回一个审批实例 +lark-cli approval instances cancel \ + --data '{"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":""}' --as user +``` + +## 使用建议 + +- **撤回的是审批实例，不是单个任务**：`instances cancel` 只需要 `instance_code`，不需要 `task_id`。 +- **优先确认实例是否仍可撤回**：已经通过、已拒绝、已撤销或已终止的实例通常不适合继续撤回。 +- **优先从 `instances initiated` 获取目标实例**：因为撤回通常针对“我发起的审批”，这个入口最直接。 +- **也可从 `tasks query` 反查 `instance_code`**：当你是从某个待办/已办上下文进入时，这样更方便。 +- **先 `--dry-run` 再执行**：尤其在实例来源不明确、用户只给了标题关键字，或一次要核对多个实例时，先预览更安全。 + +## 输出与后续验证 + +- 该命令的成功响应重点在于“调用成功”，实际业务上通常还应继续验证审批实例状态是否已变为撤销。 +- 推荐在执行后再次调用以下命令确认结果： + +```bash +# 查看审批实例当前状态 +lark-cli approval instances get --params '{"instance_code":""}' --as user + +# 或重新查看我发起的审批列表 +lark-cli approval instances initiated --params '{"page_size":20}' --as user +``` + +## 相关 API 信息 + +基于当前 CLI schema： + +- HTTP Method: `POST` +- Path: `instances/recall` +- 资源 ID: `instances.cancel` + +## 参考 + +- [lark-approval](../SKILL.md) -- 审批技能说明 +- [lark-shared](../../lark-shared/SKILL.md) -- 认证、权限和高风险写操作协议 diff --git a/skills/lark-approval/references/lark-approval-instance-cc.md b/skills/lark-approval/references/lark-approval-instance-cc.md new file mode 100644 index 000000000..32d1095f3 --- /dev/null +++ b/skills/lark-approval/references/lark-approval-instance-cc.md @@ -0,0 +1,130 @@ + +# approval instances cc + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +给一个审批实例追加抄送人（用户级写操作）。通常先通过 `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":"","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":"","cc_user_ids":["ou_xxx"],"comment":"抄送给你知悉"}' \ + --params '{"user_id_type":"open_id"}' \ + --as user \ + --yes + +# 一次抄送多个人 +lark-cli approval instances cc \ + --data '{"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":"","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":""}' --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` 再执行**：尤其在抄送对象较多、抄送人来源不明确，或需要让用户先核对实例标题时，先预览更安全。 + +## 输出与后续验证 + +- 该命令的成功响应重点在于“调用成功”，实际业务上通常还应继续确认抄送是否生效。 +- 推荐在执行后再次调用以下命令确认结果： + +```bash +# 查看审批实例当前状态 +lark-cli approval instances get --params '{"instance_code":""}' --as user +``` + +## 相关 API 信息 + +基于当前 CLI schema： + +- HTTP Method: `POST` +- Path: `instances/add_cc` +- 资源 ID: `instances.cc` + +## 参考 + +- [lark-approval](../SKILL.md) -- 审批技能说明 +- [lark-shared](../../lark-shared/SKILL.md) -- 认证、权限和高风险写操作协议 diff --git a/skills/lark-approval/references/lark-approval-instance-get.md b/skills/lark-approval/references/lark-approval-instance-get.md new file mode 100644 index 000000000..01291534b --- /dev/null +++ b/skills/lark-approval/references/lark-approval-instance-get.md @@ -0,0 +1,166 @@ + +# approval instances get + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +获取单个审批实例详情（用户级只读操作）。适合在执行 approve / reject / transfer / rollback / cancel / cc / remind 之前，先查看审批表单、当前节点、任务列表、审批动态和整体状态。 + +需要的 scopes: ["approval:instance:read"] + +## 命令 + +```bash +# 按实例 Code 查询详情 +lark-cli approval instances get --params '{"instance_code":""}' --as user + +# 指定返回语言 +lark-cli approval instances get --params '{"instance_code":"","locale":"zh-CN"}' --as user + +# 指定用户 ID 类型 +lark-cli approval instances get --params '{"instance_code":"","user_id_type":"open_id"}' --as user + +# 表格格式输出，便于快速浏览顶层字段 +lark-cli approval instances get --params '{"instance_code":""}' --format table --as user + +# 预览 API 调用，不执行 +lark-cli approval instances get --params '{"instance_code":""}' --as user --dry-run +``` + +## 参数 + +| 参数 | 必填 | 说明 | +|------|------|------| +| `--params '{...}'` | 是 | 查询参数，使用 JSON 传入 | +| `instance_code` | 是 | 审批实例 Code | +| `locale` | 否 | 返回语言，例如 `zh-CN`、`en-US`、`ja-JP`、`zh-HK`、`zh-TW` | +| `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":""}' --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":"","task_id":""}' --as user --yes + +# 撤回审批实例 +lark-cli approval instances cancel --data '{"instance_code":""}' --as user --yes + +# 催办审批任务 +lark-cli approval tasks remind --data '{"instance_code":"","task_ids":[""]}' --as user --yes +``` + +## 相关 API 信息 + +基于当前 CLI schema： + +- HTTP Method: `GET` +- Path: `instances/detail` +- 资源 ID: `instances.get` + +## 参考 + +- [lark-approval](../SKILL.md) -- 审批技能说明 +- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数 diff --git a/skills/lark-approval/references/lark-approval-instance-initiated.md b/skills/lark-approval/references/lark-approval-instance-initiated.md new file mode 100644 index 000000000..702240f0b --- /dev/null +++ b/skills/lark-approval/references/lark-approval-instance-initiated.md @@ -0,0 +1,140 @@ + +# approval instances initiated + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +查询当前用户已发起的审批实例列表（用户级只读操作）。适合在需要查看“我发起了哪些审批”、筛选某类审批定义、获取 `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":"","page_size":20}' --as user + +# 指定语言 +lark-cli approval instances initiated --params '{"page_size":20,"locale":"zh-CN"}' --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，用于只查看某个审批定义下我发起的实例 | +| `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":""}' --as user + +# 撤回审批实例 +lark-cli approval instances cancel --data '{"instance_code":""}' --as user --yes +``` + +### 2) 只看某类审批 + +```bash +lark-cli approval instances initiated \ + --params '{"definition_code":"","page_size":20}' \ + --as user +``` + + +## 使用建议 + +- **这是定位“我发起的审批实例”的首选命令**：如果你的目标是撤回、抄送、查看某个已发起审批，优先从这里拿 `instance_code`。 +- **优先用 `definition_code` 缩小范围**：当你已知审批定义时，先筛掉无关实例，可显著提升可读性。 +- **结果很多时优先 `--format table`**：适合人工快速浏览。 +- **`count` 只在第一页返回**：做分页处理时不要假设后续页还会带总数。 +- **`instance_status` 可直接判断下一步**：例如状态为 `1` 时通常可继续查看详情或考虑撤回，状态为 `4` 表示已经撤销，无需重复撤回。 +- **摘要字段 `summaries` 很适合做列表预览**：当审批标题不够明确时，可结合摘要值帮助识别目标实例。 + +## 输出与后续操作 + +拿到列表后，常见下一步： + +```bash +# 查看单个审批实例详情 +lark-cli approval instances get --params '{"instance_code":""}' --as user + +# 撤回审批实例 +lark-cli approval instances cancel --data '{"instance_code":""}' --as user --yes + +# 给审批实例追加抄送人 +lark-cli approval instances cc --data '{"instance_code":"","cc_user_ids":[""]}' --params '{"user_id_type":"open_id"}' --as user --yes +``` + +## 相关 API 信息 + +基于当前 CLI schema： + +- HTTP Method: `GET` +- Path: `instances/initiated` +- 资源 ID: `instances.initiated` + +## 参考 + +- [lark-approval](../SKILL.md) -- 审批技能说明 +- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数 diff --git a/skills/lark-approval/references/lark-approval-tasks-add-sign.md b/skills/lark-approval/references/lark-approval-tasks-add-sign.md new file mode 100644 index 000000000..6354dcab3 --- /dev/null +++ b/skills/lark-approval/references/lark-approval-tasks-add-sign.md @@ -0,0 +1,149 @@ + +# approval tasks add_sign + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +给一个审批任务加签（用户级写操作）。通常先通过 `tasks query` 拿到 `task_id` 和 `instance_code`，确认目标任务后，再提供被加签人的用户 ID、加签方式等参数执行加签。 + +> [!CAUTION] +> 这是 **high-risk-write** 写操作。建议先用 `--dry-run` 预览；真正执行时，如果用户已明确要对该审批任务加签且目标任务、加签对象、加签方式都无误，再带 `--yes` 运行。不要在未获用户明确同意时静默追加 `--yes`。 + +需要的 scopes: ["approval:task:write"] + +## 命令 + +```bash +# 先预览请求，不实际执行 +lark-cli approval tasks add_sign \ + --data '{"instance_code":"","task_id":"","add_sign_type":1,"add_sign_user_ids":["ou_xxx"],"approval_method":1,"comment":"前加签给财务复核"}' \ + --params '{"user_id_type":"open_id"}' \ + --as user \ + --dry-run + +# 前加签（需要 approval_method） +lark-cli approval tasks add_sign \ + --data '{"instance_code":"","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 + +# 后加签（需要 approval_method） +lark-cli approval tasks add_sign \ + --data '{"instance_code":"","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 + +# 并加签（常见场景可不传 approval_method） +lark-cli approval tasks add_sign \ + --data '{"instance_code":"","task_id":"","add_sign_type":3,"add_sign_user_ids":["123456789"],"comment":"并加签给项目 owner"}' \ + --params '{"user_id_type":"user_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` 依次审批；**仅在前加签、后加签时需要填写** | +| `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` | 前加签 | +| `2` | 后加签 | +| `3` | 并加签 | + +### approval_method + +| 值 | 含义 | 适用场景 | +|----|------|----------| +| `1` | 或签 | 前加签 / 后加签 | +| `2` | 会签 | 前加签 / 后加签 | +| `3` | 依次审批 | 前加签 / 后加签 | + +## 典型前置步骤 + +先查到待办任务： + +```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":""}' --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` 要和业务意图一致**：前加签是在当前审批前插入审批人，后加签是在当前审批后追加审批人，并加签则是增加并行审批人。 +- **前加签 / 后加签要补 `approval_method`**：不要遗漏，否则请求可能无法准确表达审批方式。 +- **优先从 `tasks query` 的待办列表拿任务参数**：尤其是 `topic=1` 的待办审批，最适合作为 add_sign 的输入来源。 +- **先检查是否支持 API 操作**：如果 `tasks[].support_api_operate` 为 `false`，说明该任务可能不支持通过 API 执行处理动作，加签前应谨慎验证。 +- **`comment` 建议写明加签原因**：例如 `增加财务复核`、`增加项目 owner 并行确认`，方便相关人员理解上下文。 +- **先 `--dry-run` 再执行**：尤其在多人加签、跨部门加签或加签对象来源不明确时，先预览更安全。 + +## 输出与后续验证 + +- 该命令的成功响应重点在于“调用成功”，实际业务上通常还应继续验证加签结果是否已反映到审批流中。 +- 推荐在执行后再次调用以下命令确认结果： + +```bash +# 复查待办 / 审批流状态是否变化 +lark-cli approval tasks query --params '{"topic":"1"}' --as user + +# 查看审批实例当前状态与节点变化 +lark-cli approval instances get --params '{"instance_code":""}' --as user +``` + +## 相关 API 信息 + +基于当前 CLI schema： + +- HTTP Method: `POST` +- Path: `tasks/add_sign` +- 资源 ID: `tasks.add_sign` + +## 参考 + +- [lark-approval](../SKILL.md) -- 审批技能说明 +- [approval tasks query](./lark-approval-tasks-query.md) -- 先查待办、再执行加签 +- [lark-shared](../../lark-shared/SKILL.md) -- 认证、权限和高风险写操作协议 diff --git a/skills/lark-approval/references/lark-approval-tasks-approve.md b/skills/lark-approval/references/lark-approval-tasks-approve.md new file mode 100644 index 000000000..0a2f4b700 --- /dev/null +++ b/skills/lark-approval/references/lark-approval-tasks-approve.md @@ -0,0 +1,110 @@ + +# approval tasks approve + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +同意一个审批任务（用户级写操作）。通常先通过 `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":"","task_id":"","comment":"同意"}' \ + --as user \ + --dry-run + +# 同意审批任务，并附带审批意见 +lark-cli approval tasks approve \ + --data '{"instance_code":"","task_id":"","comment":"同意"}' \ + --as user \ + --yes + +# 需要回填表单时，传入 form（按当前 schema，form 为字符串化 JSON） +lark-cli approval tasks approve \ + --data '{"instance_code":"","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` | 否 | 表单数据；按当前 `schema approval.tasks.approve`，字段类型为 `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":""}' --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` 再执行**：尤其在批量处理、表单回填或任务来源不明确时，先预览更安全。 + +## 输出与后续验证 + +- 该命令的成功响应重点在于“调用成功”，实际业务上通常还应继续验证审批状态是否已推进。 +- 推荐在执行后再次调用以下命令确认结果： + +```bash +# 复查待办是否已消失 / 状态是否变化 +lark-cli approval tasks query --params '{"topic":"1"}' --as user + +# 查看审批实例当前状态 +lark-cli approval instances get --params '{"instance_code":""}' --as user +``` + +## 相关 API 信息 + +基于当前 CLI schema： + +- HTTP Method: `POST` +- Path: `tasks/pass` +- 资源 ID: `tasks.approve` + +## 参考 + +- [lark-approval](../SKILL.md) -- 审批技能说明 +- [approval tasks query](./lark-approval-tasks-query.md) -- 先查待办、再执行同意 +- [lark-shared](../../lark-shared/SKILL.md) -- 认证、权限和高风险写操作协议 diff --git a/skills/lark-approval/references/lark-approval-tasks-query.md b/skills/lark-approval/references/lark-approval-tasks-query.md new file mode 100644 index 000000000..f69836df3 --- /dev/null +++ b/skills/lark-approval/references/lark-approval-tasks-query.md @@ -0,0 +1,89 @@ + +# approval tasks query + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +查询当前用户的审批任务列表，可用于查看待办、已办、知会等分组。只读操作，不会修改审批状态。 + +需要的 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":"17"}' --as user + +# 指定语言与分页大小 +lark-cli approval tasks query --params '{"topic":"1","locale":"zh-CN","page_size":20}' --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，用于仅查询某个审批定义下的任务 | +| `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 query` 拿到 `task_id` 和 `instance_code`，再根据需要调用 `instances get` 查看详情，最后执行 `tasks approve` / `tasks reject` / `tasks transfer` / `tasks add_sign` / `tasks rollback`。 +- 如果你只想看“已发起的审批实例”，也可以优先考虑 `instances initiated`；`tasks query` 更适合围绕“任务分组”来拉取列表。 +- 需要继续翻页时，直接把上一次返回的 `page_token` 放回 `--params`。 +- 当结果量较大时，优先使用 `--format table` 提升可读性。 + +## 参考 + +- [lark-approval](../SKILL.md) -- 审批技能说明 +- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数 diff --git a/skills/lark-approval/references/lark-approval-tasks-reject.md b/skills/lark-approval/references/lark-approval-tasks-reject.md new file mode 100644 index 000000000..6f07b1075 --- /dev/null +++ b/skills/lark-approval/references/lark-approval-tasks-reject.md @@ -0,0 +1,102 @@ + +# approval tasks reject + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +拒绝一个审批任务（用户级写操作）。通常先通过 `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":"","task_id":"","comment":"拒绝"}' \ + --as user \ + --dry-run + +# 拒绝审批任务，并附带审批意见 +lark-cli approval tasks reject \ + --data '{"instance_code":"","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":""}' --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` 再执行**：尤其在批量处理或任务来源不明确时，先预览更安全。 + +## 输出与后续验证 + +- 该命令的成功响应重点在于“调用成功”，实际业务上通常还应继续验证审批状态是否已更新为拒绝。 +- 推荐在执行后再次调用以下命令确认结果： + +```bash +# 复查待办是否已消失 / 状态是否变化 +lark-cli approval tasks query --params '{"topic":"1"}' --as user + +# 查看审批实例当前状态 +lark-cli approval instances get --params '{"instance_code":""}' --as user +``` + +## 相关 API 信息 + +基于当前 CLI schema： + +- HTTP Method: `POST` +- Path: `tasks/refuse` +- 资源 ID: `tasks.reject` + +## 参考 + +- [lark-approval](../SKILL.md) -- 审批技能说明 +- [approval tasks query](./lark-approval-tasks-query.md) -- 先查待办、再执行拒绝 +- [lark-shared](../../lark-shared/SKILL.md) -- 认证、权限和高风险写操作协议 diff --git a/skills/lark-approval/references/lark-approval-tasks-remind.md b/skills/lark-approval/references/lark-approval-tasks-remind.md new file mode 100644 index 000000000..602c7f47a --- /dev/null +++ b/skills/lark-approval/references/lark-approval-tasks-remind.md @@ -0,0 +1,111 @@ + +# approval tasks remind + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +对审批实例中的指定任务发起催办（用户级写操作）。通常先通过 `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":"","task_ids":[""],"comment":"请尽快处理"}' \ + --as user \ + --dry-run + +# 催办单个审批任务 +lark-cli approval tasks remind \ + --data '{"instance_code":"","task_ids":[""],"comment":"请尽快审批该单据"}' \ + --as user \ + --yes + +# 同一实例下催办多个任务 +lark-cli approval tasks remind \ + --data '{"instance_code":"","task_ids":["",""],"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":""}' --as user +``` + +## 使用建议 + +- **`instance_code` 和 `task_ids` 要对应同一个审批实例**：不要把不同实例下的任务 ID 混在同一次催办请求中。 +- **`task_ids` 是数组**：即使只催办一个任务，也要按数组形式传入。 +- **优先从 `tasks query` 的待办列表拿参数**：尤其是 `topic=1` 的待办审批，最适合作为 remind 的输入来源。 +- **催办前先确认任务仍需处理**：已经审批完成、已撤回或已终止的任务一般不适合继续催办。 +- **`comment` 建议简洁且明确**：例如 `该单据较急，请优先审批`、`请今天内处理`。避免过长或模糊描述。 +- **先 `--dry-run` 再执行**：尤其在一次催办多个任务、任务来源不明确或需让用户复核催办对象时，先预览更安全。 + +## 输出与后续验证 + +- 该命令的成功响应重点在于“调用成功”，实际业务上通常还应继续观察审批任务是否被处理。 +- 推荐在执行后再次调用以下命令确认结果： + +```bash +# 复查待办是否仍存在 +lark-cli approval tasks query --params '{"topic":"1"}' --as user + +# 查看审批实例当前状态 +lark-cli approval instances get --params '{"instance_code":""}' --as user +``` + +## 相关 API 信息 + +基于当前 CLI schema： + +- HTTP Method: `POST` +- Path: `instances/remind` +- 资源 ID: `tasks.remind` + +## 参考 + +- [lark-approval](../SKILL.md) -- 审批技能说明 +- [approval tasks query](./lark-approval-tasks-query.md) -- 先查待办、再执行催办 +- [lark-shared](../../lark-shared/SKILL.md) -- 认证、权限和高风险写操作协议 diff --git a/skills/lark-approval/references/lark-approval-tasks-rollback.md b/skills/lark-approval/references/lark-approval-tasks-rollback.md new file mode 100644 index 000000000..9d9d6656d --- /dev/null +++ b/skills/lark-approval/references/lark-approval-tasks-rollback.md @@ -0,0 +1,112 @@ + +# approval tasks rollback + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +将一个审批任务退回到指定节点（用户级写操作）。通常先通过 `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":"","task_id":"","node_ids":[""],"comment":"退回补充材料"}' \ + --as user \ + --dry-run + +# 退回到单个节点 +lark-cli approval tasks rollback \ + --data '{"instance_code":"","task_id":"","node_ids":[""],"comment":"请补充附件后重新提交"}' \ + --as user \ + --yes + +# 传多个候选节点 ID（以实际审批定义支持情况为准） +lark-cli approval tasks rollback \ + --data '{"instance_code":"","task_id":"","node_ids":["",""],"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 数组；执行前应先确认这些节点确实可作为退回目标 | +| `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":""}' --as user +``` + +## 使用建议 + +- **`instance_code` 和 `task_id` 要成对使用**：仅有实例 ID 或仅有任务 ID 都不足以准确执行退回操作。 +- **`node_ids` 是必填项**：退回并不是“自动退回上一步”，而是要明确给出目标节点 ID 数组。 +- **先确认节点是否可退回**：不同审批定义支持的退回目标可能不同；在不确定时，先通过 `instances get` 或业务侧流程信息核实。 +- **优先从 `tasks query` 的待办列表拿任务参数**：尤其是 `topic=1` 的待办审批，最适合作为 rollback 的输入来源。 +- **先检查是否支持 API 操作**：如果 `tasks[].support_api_operate` 为 `false`，说明该任务可能不支持通过 API 执行处理动作，退回前应谨慎验证。 +- **`comment` 建议写清退回原因**：例如 `附件缺失，请补齐后重新提交`、`费用说明不完整，请补充明细`，方便发起人或上一步处理人理解原因。 +- **先 `--dry-run` 再执行**：尤其在节点来源不明确、审批链路复杂或批量处理时，先预览更安全。 + +## 输出与后续验证 + +- 该命令的成功响应重点在于“调用成功”，实际业务上通常还应继续验证审批是否已退回到预期节点。 +- 推荐在执行后再次调用以下命令确认结果： + +```bash +# 复查待办是否已变化 +lark-cli approval tasks query --params '{"topic":"1"}' --as user + +# 查看审批实例当前状态与节点变化 +lark-cli approval instances get --params '{"instance_code":""}' --as user +``` + +## 相关 API 信息 + +基于当前 CLI schema： + +- HTTP Method: `POST` +- Path: `tasks/rollback` +- 资源 ID: `tasks.rollback` + +## 参考 + +- [lark-approval](../SKILL.md) -- 审批技能说明 +- [approval tasks query](./lark-approval-tasks-query.md) -- 先查待办、再执行退回 +- [lark-shared](../../lark-shared/SKILL.md) -- 认证、权限和高风险写操作协议 diff --git a/skills/lark-approval/references/lark-approval-tasks-transfer.md b/skills/lark-approval/references/lark-approval-tasks-transfer.md new file mode 100644 index 000000000..79aa45633 --- /dev/null +++ b/skills/lark-approval/references/lark-approval-tasks-transfer.md @@ -0,0 +1,120 @@ + +# approval tasks transfer + +> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 + +转交一个审批任务给其他用户处理（用户级写操作）。通常先通过 `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":"","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":"","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":"","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":""}' --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` 再执行**：尤其在跨部门转交、批量处理或转交对象来源不明确时，先预览更安全。 + +## 输出与后续验证 + +- 该命令的成功响应重点在于“调用成功”，实际业务上通常还应继续验证任务是否已从当前人待办中转出。 +- 推荐在执行后再次调用以下命令确认结果： + +```bash +# 复查待办是否已转出 / 状态是否变化 +lark-cli approval tasks query --params '{"topic":"1"}' --as user + +# 查看审批实例当前状态 +lark-cli approval instances get --params '{"instance_code":""}' --as user +``` + +## 相关 API 信息 + +基于当前 CLI schema： + +- HTTP Method: `POST` +- Path: `tasks/forward` +- 资源 ID: `tasks.transfer` + +## 参考 + +- [lark-approval](../SKILL.md) -- 审批技能说明 +- [approval tasks query](./lark-approval-tasks-query.md) -- 先查待办、再执行转交 +- [lark-shared](../../lark-shared/SKILL.md) -- 认证、权限和高风险写操作协议