Adc Approval Usage

---
name: adc-approval-usage
description: >
  How to use the ADC approval and ticket capability 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 approval submission, whitelist requests, workflow follow-up or ticket
  forensics 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 and ticket capability 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 & Ticket Usage
version: 0.4.14
author: ADC Copilot Team
---

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

> 审批（流云工作流）与工单（安灯）能力，与运行域的工具（作业 / 主机排障 / TKE / 镜像构建 /
> 云 API）在**同一个连接器、同一个工具面**上 —— 按用途挑工具即可，不要以为"审批要换一个连接器"。
> 两组审批侧上游由服务端按用途路由。

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

**本文不列工具清单**：那是"当前事实"，随上游增减而变，写进文档第二天就可能过期。
工具名与参数一律以**运行时**看到的为准（`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` 过滤 —— 这不是优化，是不带就做不到。**
执行记录单页上限 100、定时任务噪声每 5 分钟约 3 条 ⇒ 一次新提交的申请几小时后就会掉出前 100 名；
带上目标 `playbook_id` 后范围会收敛到可读的几十条。

> ⚠️ `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` 与固定模板拼起来就是一条**可直接触发生产流程的写凭据**。所以「读工具是只读的」
这句话**只覆盖动作，不覆盖返回值** —— 返回值里同样可能躺着凭据类字段。写工具另算：
它们各自只放行一条明确路径（提交 / 悔单），并有独立的确认与幂等机制。

## 硬约束

- 工具**不接受**「操作人」这类归属参数：上游的操作人字段只能由可信来源注入，
  否则模型就能把操作归属到任意人名下，审计链反而不可信
- **不做能力承诺**：读不到就说读不到，不要为了把话说圆而猜测或编造