Adc Approval Usage

---
name: adc-approval-usage
description: >
  How to use the ADC approval connector correctly: how to find the capability you need,
  in what order to call things, what is intentionally unavailable, and how to read the results.
  Use when a task needs this connector capability inside the ADC zone.
  Boundary: this skill only explains tool usage and performs no actions itself. Approval
  submission IS open and every write needs a two-phase confirmation; ticket forensics is
  read-only. It never makes approval decisions and never widens the scope.
description_zh: >
  智驾专区审批 连接器的正确用法：能力怎么找、调用顺序、哪些操作做不到、结果怎么读。
  触发词：需要该连接器能力的智驾专区任务。边界：本技能只讲用法，不执行任何动作；
  审批提交**开放**（每次写都要两段式确认），工单侧**只读**；不做批准决策，也不扩大申请范围。
description_en: >
  How to use the ADC approval connector correctly, including how to find the capability you
  need, call order, unavailable operations and result semantics. Approval submission is open
  and gated by a two-phase confirmation; ticket forensics is read-only.
display_name: 审批域连接器用法
display_name_en: ADC Approval Connector Usage
version: 0.3.7
author: ADC Copilot Team
---

# 智驾专区审批与工单 使用说明

> 本连接器聚合两组上游 —— **流云审批**（工作流）与 **安灯工单**（工单查询）—— 由服务端按用途路由。

## 工具面（**一律以运行时为准**）

**本文不列工具清单**：那是"当前事实"，随上游增减而变，写进文档第二天就可能过期。
工具名与参数一律以**运行时**看到的为准（`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 申请、管控账户新增用户）——
> 它们的参数由**企微交互卡片 / 表单**收集，这里只能"触发"。
> 被问到这类要**如实说明**，不要承诺"已提交 / 已开通"。

**提交流程（按这个顺序走，别绕过确认）**：

1. 先查**可提交项**，拿到目标流程的 `Id` 与它的 `BusinessFields`
2. 按 `BusinessFields` 组 `fields` → 第一次调用提交工具
   （白名单申请有**类型化封装**，参数更好填，同一套确认与幂等）
3. 把 `summary`（含流程名）念给用户确认；同意后用**原样**的 `confirm_text` 再调 → 才真的提交
4. 跟单：带 `playbook_id` 列运行 → 取该运行详情读审批结论。
   返回里若带 `missing_declared_fields`，说明该流程还声明了别的字段没给 —— **要告诉用户**

> ⚠️ 写操作的**令牌由服务端现取**（流程定义里的触发令牌），**永远不会**出现在
> 工具返回值里；也不需要你提供任何令牌。换流程 / 换区不用改任何配置 —— 新建的流程自动可用。

## 调用顺序

1. 先列**可访问的流程能力**，拿 `Id`（**不要猜 `Id`**）
2. 要看定义就取单个能力，传上一步的 `Id`
3. 跟单 / 排障：带 `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`，不进产物、不进日志
- 工具**不接受**「操作人」这类归属参数：上游的操作人字段只能由可信来源注入，
  否则模型就能把操作归属到任意人名下，审计链反而不可信
- **不做能力承诺**：读不到就说读不到，不要为了把话说圆而猜测或编造