企业官网建设流程全解析

飞书 CLIlark approval approvals search实战指南：从自然语言到可发起审批定义的精准定位

【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200+ commands and 20+ AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli

本指南以 larksuite CLI（lark-cli）审批技能lark-approval中的approvals search命令为对象，讲解如何通过关键词把"用户可发起的审批定义候选项"找出来，为后续查看定义详情（approvals get）与发起原生审批实例（instances create）铺路。读完本文，你将掌握该命令的完整参数用法、返回字段的业务含义、Agent 场景下的使用规则与结果整理方式，并理解它与审批提单工作流的衔接关系及底层--dry-run预览机制。

一、命令定位：审批提单工作流的"第一步"

在飞书 CLI 的审批技能中，approvals search承担的是一个非常具体的职责：搜索当前用户可发起的审批定义（launchable approvals）。它是一次只读操作，不会创建审批实例，也不产生任何写副作用，因此可以放心地反复调用、用来探测用户的真实意图。

从 skills/lark-approval/SKILL.md 的命令选型表可以看到，lark-approval按"想做什么"划分命令：搜可发起定义走approvals search，看定义详情走approvals get，发起原生审批实例走instances create。三者构成固定的处理链：

approvals search -> approvals get -> instances create

而approvals search正是这条链的入口：当用户只有自然语言意图、还没有approval_code时，先用它把"可发起的审批定义候选项"找出来，再进入后续步骤。典型场景包括：

• "帮我找一下请假审批"
• "有哪些可以发起的报销单？"
• "先搜一下出差审批，再帮我提单"

需要强调的是，审批待办不是飞书任务，只要用户的核心对象是审批单据/审批待办/审批实例，就应优先走lark-approval，不要让渡给lark-task。

二、命令语法与核心参数

approvals search的基本形态如下：

# 按关键词搜索可发起审批定义 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

参数一览

两个细节值得展开：

--as user与身份语义。审批是"人的动作"，lark-approval的所有命令默认按用户身份执行，SKILL.md 也明确要求"所有命令默认--as user"。对approvals search而言，可发起的定义集合本来就依赖当前用户的可见范围与权限（需要的 scopes 为["approval:approval:read"]），因此显式传--as user能让返回结果更贴近"当前用户到底能发起哪些单"。

--dry-run的预览机制。--dry-run并不会真正发起 API 调用，而是把将要发出的 HTTP 请求原样预览出来。从源码 internal/cmdutil/dryrun.go 可以看到，PrintDryRun会基于client.RawApiRequest组装一个DryRunAPI：把请求方法、URL、查询参数、请求体（request.Data）以及调用身份（app_id / user_open_id）一并输出；当Format == "pretty"时在 stdout 打出# dry-run: request not sent标记，随后逐行展示METHOD url与请求体 JSON。这意味着你可以在正式执行前确认：请求打到了哪个端点、keyword等参数是否按预期携带、以什么身份发起。对 Agent 场景来说，这是低成本、零副作用的安全校验手段。

三、返回结果重点字段解读

approvals search返回的是可发起审批定义的候选列表。虽然字段可能较多，但优先关注以下四个即可完成绝大多数决策：

这四个字段共同决定了下一步动作的分叉：

• approval_name用于确认候选定义是不是用户想要的那张单（避免把"请假申请"和"请假销假"等相似名称搞混）；
• approval_code是后续所有操作的"钥匙"，必须原样保留；
• is_external是"能不能走原生提单"的判定开关；
• create_link则是三方定义的出口，需要直接交给用户。

四、使用规则与决策边界

approvals search的正确用法不是"搜到就提单"，而是遵循一整套决策规则，避免 Agent 替用户拍板或误操作：

1. 这是发起审批工作流的第一步。标准顺序是approvals search->approvals get->instances create。
2. 搜索结果为空时，不要猜。直接告诉用户当前关键词下没有可发起定义，并建议用户换关键词。
3. 命中多个结果时，不要替用户拍板。先把候选定义列出来，让用户选择目标审批定义。
4. is_external=true时不要调用approval instances create。这类定义属于三方审批，优先返回create_link并说明需要通过链接发起。
5. 只有is_external=false的原生定义，才继续approvals get。
6. 如果用户已经明确给出approval_code，不要再 search。直接执行approval approvals get。

第 6 条对应 skills/lark-approval/references/lark-approval-approvals-get.md 中的"常见输入来源"：如果你手上已经有approval_code，可以绕过搜索直达详情：

lark-cli approval approvals get --params '{"approval_code":"<APPROVAL_CODE>"}' --as user

这背后的原则是"先拿最小必要信息，再执行"——对象已明确时应压缩步骤，不要默认走list -> filter -> detail -> write全链路。

五、结果整理：输出成候选清单

approvals search的结果不应原样倾倒给用户，而应整理为候选清单，优先展示"名称 + approval_code + 是否三方定义 + 下一步建议"。建议输出成下面这种结构：

找到 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，引导用户通过链接发起

这样的结构让用户（或上层 Agent 编排）一眼就能看到：每个候选是什么、它的 code 是什么、能不能走原生提单、下一步该做什么。配合--format table使用，命令行下快速浏览多个候选定义会更直观。

六、常见后续操作：search 之后怎么办

1）用户选中了某个定义，继续查看详情

lark-cli approval approvals get --params '{"approval_code":"<APPROVAL_CODE>"}' --as user

approvals get返回的form（表单定义快照）和node_list（流程节点列表）是后续组装提单 payload 的"唯一可靠来源"：form用于识别控件id、type、选项值范围以及fieldList等明细子控件结构；node_list用于识别节点 key、need_approver（是否要求发起人补充审批人）、approver_chosen_multi（是否允许多人）。注意approvals.get.form不是instances.create可直接复用的 payload 模板，它主要用于识别字段结构与选项值范围。

2）确认是原生定义后，再准备发起审批实例

lark-cli approval instances create --data '{"approval_code":"<APPROVAL_CODE>","form":"[...]"}' --as user --yes

instances create是写操作，需要的 scopes 为["approval:instance:write"]。执行前必须让用户确认最终定义、表单值和节点参数，真正执行时显式传--yes；如需要幂等可补uuid。成功后至少回报approval_name、instance_code与instance_link。

3）确认是三方定义时，直接返回链接

当is_external=true时，优先向用户返回create_link，说明该审批需在三方系统或跳转页面中发起，而不是通过原生instances.create。

最小判断表

七、与相关 reference 的配合：搜到之后的值来源

approvals search本身只解决"找到哪个定义"，而提单时"每个值从哪里拿"由 skills/lark-approval/references/lark-approval-instance-value-sourcing.md 定义。它的默认来源规则与本命令直接相关：

• 审批定义、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获取。

也就是说，approvals search产出的正是整条值来源链的第一环。在此基础上，skills/lark-approval/references/lark-approval-initiate.md 给出了完整的提单工作流与"严禁行为"清单（如严禁跳过approvals.get、严禁对三方定义调用instances create、严禁把姓名直接写进node_approver_list等），建议在编排完整流程时一并阅读。

八、小结：一条命令，一个清晰的分叉点

approvals search的价值在于：它是自然语言意图与结构化approval_code之间的桥梁，也是整条审批提单链上唯一需要"面向用户做候选选择"的节点。用好它只需记住三件事：

1. 参数极简：必填只有--data '{"keyword":"..."}'，配合--as user、--format、--dry-run即可覆盖绝大多数场景；
2. 决策靠is_external：true走create_link，false才继续approvals get->instances create；
3. 结果要整理：输出"名称 + approval_code + 是否三方定义 + 下一步建议"的候选清单，而不是把原始 JSON 直接丢给用户。

如果需要进一步了解控件取值结构（input/date/radio/fieldList等）与节点参数组装，可继续阅读 lark-approval-instance-form-control-parameters.md 与 lark-approval-initiate.md，它们与本文共同构成"搜索定义 -> 查看详情 -> 发起实例"的完整闭环。

【免费下载链接】cliThe official Lark/飞书 CLI tool, maintained by the larksuite team — built for humans and AI Agents. Covers core business domains including Messenger, Docs, Base, Sheets, Calendar, Mail, Tasks, Meetings, and more, with 200+ commands and 20+ AI Agent Skills.项目地址: https://gitcode.com/gh_mirrors/cli414/cli