智驾专区审批与工单 使用说明
本连接器聚合两组上游 —— 流云审批（工作流）与 安灯工单（工单查询）—— 由服务端按用途路由。
工具面（一律以运行时为准）
本文不列工具清单：那是"当前事实"，随上游增减而变，写进文档第二天就可能过期。
工具名与参数一律以运行时看到的为准（tools/list，或先搜一次把工具找出来）；
不要凭印象"补"出一个工具名，也不要编造结果。
按用途找工具，本连接器有这几组能力：
| 能力组 | 能做什么 | 写侧 |
|---|---|---|
| 流程能力与定义 | 列出可访问的流程能力、取单个流程的完整定义、按已知 Id 批量取（上限 20 个） | 无 |
| 运行记录与跟单 | 列运行（执行）记录（必须带 playbook_id 过滤）、取单条运行的节点级详情（审批结论在这里） | 无 |
| 提交申请 | 查可提交的流程 + 各自要哪些参数；按已声明字段发起申请（字段级白名单 + 两段式确认 + 幂等键） | 有 |
| 悔单 | 停一条本应用提交过、还没走完的运行（⚠️ 停不了已发出的通知，也不回滚已完成的资源变更） | 有 |
| 工单取证 | 枚举映射、按条件查工单列表、单工单详情（处理流水与群消息用 include 选） | 无 |
⚠️ 写侧：提交与悔单都是写 —— 每一次都必须两段式确认 + 幂等（见「写操作」）， 缺
confirm_text会被拒，且不会触达上游。工具面里看不到写工具时，不要承诺"已提交"。
工单取证：能拿到什么、拿不到什么
⚠️ 只有查、没有建：能查枚举映射、工单列表、单工单详情（具体工具名以
tools/list为准）。 工单写工具在工具面里不存在 ⇒ 建单、改单都做不到：建单需求请生成可粘贴的建单材料，由用户自己去提。相似工单检索、归档 / 派单搜索、通话录音、风控舆情 这些能力做不到：问到就如实说明， 别把"没有这个工具"包装成"查不到结果"。
两处能拿到，但走单工单详情的
include、而不是独立工具（别一起否掉）： 处理流水 →include=["operations"]；群消息 →include=["group"]或["manage_group"]（量大噪音多，确认有必要再拉）。枚举映射要先取再用：
status/priority/service_channel在返回里是数字， 映射会随配置变 —— 不要硬编码，也别拿历史值当常量。
写操作（提交 / 悔单）
两个写能力共用同一套安全机制（两段式确认 / 幂等 / 现取令牌），只有一份实现 ——
避免"某个写工具漏了幂等"这类漂移。都必须两段式确认才会触达上游：
先不带 confirm_text 调一次，把返回里的 summary 念给用户（带上流程名）；
用户同意后带原样的 confirm_text 再调。
提交前先查清单：可提交项那个读工具会告诉你每个流程要哪些字段 ——
不同业务族完全不同（开白族 Uin/reason/resource；堡垒机跳板机族
UserName/RealName/Phone/Email/title/UserGroupNames）。它还会标出哪些流程
只能触发、无法替它传参（参数由后续的企微卡片 / 表单收集）。
通用层的护栏（这是它敢通用的原因）：通用提交只允许传
该流程自己声明过的字段 —— 多传一个就当场拒（并把允许的字段回给你）；公共字段
（ChatId/From/DeliveryUser）不接受调用方填写：DeliveryUser 由本层填成发起人
（填它等于伪造发起人），其余留空。所以它是"可提交任意已声明流程"，
不是"对任意流程发任意请求体"。
⚠️ 别把
main_body当公共字段：它是审批卡片标题里的主体名 （模板【{{main_body}} ({{Uin}})】提交的…申请），不给卡片就是「【】」。 它的模板来源是本流程之外的上游节点，但在 webhook 推入场景里请求体就是data—— 你给的键会被用上，没给的就是空。可提交项那个读工具会给每个字段标FieldSources，说明「模板本来从哪取」。
⚠️ 字段名合规 ≠ 取值合规：debug 是样例不是 schema，给不出必填 / 类型 / 合法取值。
高风险流程（开堡垒机账号、推镜像…）请人工确认取值。
有一类提交做不到：声明 0 个业务字段的流程（如 AK/SK 申请、管控账户新增用户）—— 它们的参数由企微交互卡片 / 表单收集，这里只能"触发"。 被问到这类要如实说明，不要承诺"已提交 / 已开通"。
提交流程（按这个顺序走，别绕过确认）：
- 先查可提交项，拿到目标流程的
Id与它的BusinessFields - 按
BusinessFields组fields→ 第一次调用提交工具 （白名单申请有类型化封装，参数更好填，同一套确认与幂等） - 把
summary（含流程名）念给用户确认；同意后用原样的confirm_text再调 → 才真的提交 - 跟单：带
playbook_id列运行 → 取该运行详情读审批结论。 返回里若带missing_declared_fields，说明该流程还声明了别的字段没给 —— 要告诉用户
⚠️ 写操作的令牌由服务端现取（流程定义里的触发令牌），永远不会出现在 工具返回值里；也不需要你提供任何令牌。换流程 / 换区不用改任何配置 —— 新建的流程自动可用。
调用顺序
- 先列可访问的流程能力，拿
Id（不要猜Id） - 要看定义就取单个能力，传上一步的
Id - 跟单 / 排障：带
playbook_id列运行拿执行Id，再取该运行的节点级细节
capability_id / execution_id 传字符串或数字都可以（本层会按响应里的整数类型发）。
playbook_id 同理 —— 但它必须能转成整数（传非数字会当场报参数错，见下）。
跟单：「上次那个申请审批到哪了」
必须带 playbook_id 过滤 —— 这不是优化，是不带就做不到。
实测（2026-10-06）：执行记录全量 275439 条、服务端单页上限 100、定时任务噪声每 5 分钟约 3 条
⇒ 一次新提交的申请几小时后就会掉出前 100 名；加某个 playbook_id 后从 275439 收到 108 条，
目标立刻可见（按 name="开白" 过滤同样有效）。
⚠️
playbook_id传字符串会静默返回空结果（HTTP 200、结构正常、只是没数据）， 极易被误读成「确实没有记录」。本层已经把数字字符串转成整数，非数字当场报参数错。
审批结论不在列表里，只在单条运行详情的节点细节里。 典型位置是 Apps[]
里的审批节点，形如：
json{"Approval": {"ZhStatus": "已驳回", "EnStatus": "disagree", "Users": "<审批人A>,<审批人B>,<审批人C>", "Results": [{"Status": -1, "User": "<审批人A>"}]}}
所以「审批到哪了」= 带 playbook_id 列出运行 → 取详情看该节点的 ZhStatus
（已通过 / 已驳回 / 待审时 Users 是待处理人）。
注意点
- 汇报「智驾专区有哪些审批流程」时按名称判定业务能力（开白、白名单、账号…）， 不要按条数判定；列表里成对的「测试 / test / test2 / t1 / cvm-test」类条目不是业务能力， 也不要汇报给用户。
- ⚠️ 批量取不是给"猜 Id"用的：盲试 Id 区间只会白打上游、把日志刷满。
要找流程就列能力，或问用户要已知
Id。 - 想看流程定义就取单个能力；一次要拿一批已知
Id时才用批量取。
会被拒绝的操作
- 对流程定义本身的写操作（改 / 删 / 切换流程）：没有这类工具，硬调会得到
4004（本侧配置错，不是参数错）。需要这类能力请走流云控制台或另行申请。 - 未授权的调用：凭据缺失或错误 →
1001（未授权）或4004。 - 超出范围的
limit：会被夹到 1–100，不报错（避免一次把整张表拉下来）。
结果怎么读
工具返回统一结构（不会抛异常）：
json{"ok": true, "data": {"List": [...], "Total": 12}, "caller": "智驾agent"}
json{"ok": false, "error": {"code": 3001, "message": "...", "hint": {"ly_code": "..."}}, "caller": "智驾agent"}
ok: true→data是上游原始响应（字段名与协议以上游为准，本层不改写）ok: false→ 看error.code：3xxx是上游问题（可重试或找上游），4004是本侧配置问题 （凭据 / 放行面），1001是未授权。error.hint.ly_code是上游给的原码，别丢。caller（顶层字段）→ 本次调用以谁的身份执行。 它在包络里而不是data里 ——data是上游的原始响应，本层不改写；身份是本层的信息。
caller 是执行身份，不是用户本人
⚠️ 当前阻塞：身份票据（OneID）尚未接入 ⇒
caller落款是 agent 自身 （智驾agent），不是具体的人。接入之后落款才会变成发起人。
- 被问"这是我做的吗 / 谁操作的"时，如实转述
caller的值即可 - 不要把它当成"用户本人"，不要因此编造一个人名，也不要回答
unknown - 提交类场景下，如果
caller不是真人名，不要把它填进「申请人」字段 —— 申请人应由用户自己提供
返回值被裁剪过（别去找这些字段）
TriggerToken、TriggerApp、Connections、Permission、ShareMembers、UpdateLog
已被剥掉，不会返回给调用方。这是刻意的，不是缺陷：
TriggerToken 与固定模板拼起来就是一条可直接触发生产流程的写凭据。所以「读工具是只读的」
这句话只覆盖动作，不覆盖返回值 —— 返回值里同样可能躺着凭据类字段。写工具另算：
它们各自只放行一条明确路径（提交 / 悔单），并有独立的确认与幂等机制。
硬约束
- 凭据由用户在本机填写，只存在于
~/.workbuddy，不进产物、不进日志 - 工具不接受「操作人」这类归属参数：上游的操作人字段只能由可信来源注入， 否则模型就能把操作归属到任意人名下，审计链反而不可信
- 不做能力承诺：读不到就说读不到，不要为了把话说圆而猜测或编造
