Starlight_Lancher/.agents/skills/lark-approval/references/lark-approval-instance-value-sourcing.md

审批提单值来源

目的

本文用于回答一个固定问题：在调用 approval instances create 发起原生审批实例时，每个要填写的值从哪里拿。

阅读顺序固定如下：

1. lark-approval-initiate.md 中的创建请求参数、节点参数和返回结果说明
2. approval approvals get 返回的 form / node_list
3. 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 决定各控件 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 组装：

• 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