飞书 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 CLIlark-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参数一览参数必填说明--data {...}是查询参数使用 JSON 传入keyword是搜索关键词例如请假、报销、出差、采购locale否返回语言例如zh-CN、en-US、ja-JPpage_size否分页大小page_token否翻页标记首次请求不填后续使用上一次返回的page_token--as user否建议显式指定用户身份可发起审批定义是面向当前用户的查询--format否输出格式json默认、ndjson、table、csv--dry-run否预览 API 调用不执行两个细节值得展开--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_code审批定义 Code后续approvals get和instances create都要用它approval_name审批定义名称给用户做候选选择时最关键is_external是否为三方审批定义true表示不能走原生instances.createcreate_link三方审批定义的发起链接is_externaltrue时优先返回给用户这四个字段共同决定了下一步动作的分叉approval_name用于确认候选定义是不是用户想要的那张单避免把请假申请和请假销假等相似名称搞混approval_code是后续所有操作的钥匙必须原样保留is_external是能不能走原生提单的判定开关create_link则是三方定义的出口需要直接交给用户。四、使用规则与决策边界approvals search的正确用法不是搜到就提单而是遵循一整套决策规则避免 Agent 替用户拍板或误操作这是发起审批工作流的第一步。标准顺序是approvals search-approvals get-instances create。搜索结果为空时不要猜。直接告诉用户当前关键词下没有可发起定义并建议用户换关键词。命中多个结果时不要替用户拍板。先把候选定义列出来让用户选择目标审批定义。is_externaltrue时不要调用approval instances create。这类定义属于三方审批优先返回create_link并说明需要通过链接发起。只有is_externalfalse的原生定义才继续approvals get。如果用户已经明确给出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 userapprovals 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 --yesinstances create是写操作需要的 scopes 为[approval:instance:write]。执行前必须让用户确认最终定义、表单值和节点参数真正执行时显式传--yes如需要幂等可补uuid。成功后至少回报approval_name、instance_code与instance_link。3确认是三方定义时直接返回链接当is_externaltrue时优先向用户返回create_link说明该审批需在三方系统或跳转页面中发起而不是通过原生instances.create。最小判断表你手上有什么下一步只有口语需求比如帮我提个请假审批先approvals search已经拿到approval_code直接approvals get已拿到form/node_list且用户已给出表单值和审批人组装instances createis_externaltrue返回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之间的桥梁也是整条审批提单链上唯一需要面向用户做候选选择的节点。用好它只需记住三件事参数极简必填只有--data {keyword:...}配合--as user、--format、--dry-run即可覆盖绝大多数场景决策靠is_externaltrue走create_linkfalse才继续approvals get-instances create结果要整理输出名称 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考