AgentSkillsCN

feishu-approval

飞书审批流管理 Skill。获取审批定义、提交审批实例、添加评论、转办、撤回。当需要自动化提交审批或管理审批流程时使用此 Skill。

中文原作
SKILL.md
--- frontmatter
name: feishu-approval
description: 飞书审批流管理 Skill。获取审批定义、提交审批实例、添加评论、转办、撤回。当需要自动化提交审批或管理审批流程时使用此 Skill。
required_permissions:
  - approval:definition
  - approval:approval
  - docs:permission.member:transfer

飞书审批流管理

你是飞书审批自动化专家，负责通过 Approval v4 API 实现审批的提交、监控、评论与数据检索。

一、API 基础信息

项目值
Base URLhttps://open.feishu.cn/open-apis/approval/v4
认证方式Authorization: Bearer {tenant_access_token}
Content-Typeapplication/json

二、 审批流开发核心指南 (New)

1. 消息驱动协作 (Bot Messages)

机器人不仅可以发起审批，还能发送/更新审批相关的卡片消息，实现异步处理：

  • •发送审批机器人消息：POST /open-apis/approval/v4/messages
  • •更新审批机器人消息：PUT /open-apis/approval/v4/messages/{message_id}
    • •场景：当审批状态改变时，动态更新用户收到的卡片状态（如“已通过”），减少干扰。

2. 高级数据检索与审计 (Audit & Search)

针对大规模审批数据的管理能力：

  • •搜索审批定义：POST /open-apis/approval/v4/approvals/search
  • •批量获取审批实例：POST /open-apis/approval/v4/instances/query
  • •查询抄送列表：POST /open-apis/approval/v4/instances/search_cc
  • •查看审批详情 (专用)：POST /open-apis/approval/v4/instances/query (支持通过 ID 定位)
  • •精准搜索审批实例：POST /open-apis/approval/v4/instances/search (支持状态、发起人、时间范围等多维审计)

3. 事件实时监听 (Events)

订阅以下事件实现自动化闭环：

  • •approval.instance.status_changed_v4：全量感知实例状态变化。
  • •approval.task.status_changed_v4：感知具体节点任务的状态流转。

三、 典型业务操作

1. 获取审批定义

code
GET /open-apis/approval/v4/approvals/{approval_code}

实测心法：approval_code 在管理后台导出。必须先解析表单控件 ID（如 widget177...），提交时必须精准匹配。

2. 提交审批实例

code
POST /open-apis/approval/v4/instances?user_id_type=user_id
json
{
  "approval_code": "xxx",
  "user_id": "ou_xxx",
  "form": "[{\"id\":\"widget1\",\"type\":\"input\",\"value\":\"说明\"}]"
}

注意：user_id 类型建议优先使用 user_id（企业内唯一码）。

3. 审批实例检索与审计

code
POST /open-apis/approval/v4/instances/search

Payload 示例：

json
{
  "user_id": "ou_xxx",
  "approval_code": "7CC60280...",
  "instance_start_time_from": "1770259200",
  "instance_start_time_to": "1770739200"
}

四、最佳实践

  1. •写后必审 (AI Audit)：机器人发起审批后，应紧随一条评论说明 AI 自动核验的结果，增强审批人的信任感。
  2. •状态全链路追踪：结合 Search 接口定期巡检 P0 级审批，若超时未处理，通过 IM 技能加急提醒。
  3. •表单扁平化：控件 ID 极其冗长（如 widget177...），建议在 Skill 配置中硬编码 ID 映射表，提高代码可读性。

feishu-approval 技能总结 (教程脱敏版)

一、 核心功能清单

功能维度具体能力说明
实例自动发起零代码填单提交支持通过 API 自动填充复杂的审批表单控件（文本、数字、日期等）并一键发起流程。
高级审计检索多维实例搜索支持按时间范围、状态（审批中/通过/拒绝）、发起人等多维度批量检索审批记录，实现自动化审计。
动态消息管理审批卡片更新支持发送审批通知并动态更新已有消息卡片的状态，确保审批流状态与用户通知实时同步。
审计留痕AI 决策评论支持在审批单下自动追加 AI 审计评论，提供核验建议，增强人工审批的决策信心。
全链路监听事件实时感知通过订阅实例状态变更事件，实现从发起、审批到反馈的自动化全闭环。

二、 典型业务场景

差旅/费用自动审计与报销：

  • •场景：员工发送报销指令后，AI 自动生成审批单。同时，AI 利用高级检索接口查询该员工当月已有的报销总额，若超过阈值，自动在审批单下添加“超额预警”评论。
  • •价值：将报销从“被动接收”变为“主动预审”，极大降低了财务部的初审工作量。

自动化权限巡检与回收：

  • •场景：IT 管理员定期触发任务，AI 通过审批搜索接口拉取所有已过期的“临时权限申请单”，自动发起对应的权限回收流程。
  • •价值：确保公司数字资产的访问安全性，实现权限生命周期的闭环管理。

项目预算动态追踪：

  • •场景：当新项目立项审批通过时，AI 自动监听状态变更事件，实时同步该项目的预算配额到多维表格看板。
  • •价值：消除跨部门信息不对称，实现预算执行进度的实时可视化。

三、 实测注意事项（教程必写 · 尽量详细）

控件 ID 的“唯一标识” (Critical)：

  • •风险：审批表单的控件 ID（如 widget177...）是随机生成的。禁止在自动化逻辑中硬编码 ID。
  • •对策：教程必须强调「定义先行」原则。开发时应先调用 get_approval_definition 接口动态获取 Widget ID 列表。

消息 ID 的“生命周期管理”：

  • •坑点：在执行“更新机器人消息卡片”时，必须缓存发送时的 message_id。
  • •建议：建议在数据库或多维表格中建立 Instance_Code <-> Message_ID 的映射表，以便后续状态更新时能够精准定位卡片。

时间戳的“精确审计”：

  • •注意：在调用高级搜索接口（instances/search）时，时间范围参数需使用秒级时间戳。
  • •技巧：在教程中建议用户在搜索时预留 5-10 分钟的冗余量，以应对服务器间可能存在的同步延迟。

ID 类型的“全局一致性”：

  • •注意：飞书审批对 user_id 类型极其挑剔。在调用所有搜索、提交接口时，务必显式声明 user_id_type（推荐优先使用企业内唯一的 user_id）。

注：以上内容已脱敏。已保存至：opensource/feishu-skills/feishu-approval/SUMMARY.md