iAs/docs/TOOLKIT_WORKFLOW.md

# TOOLKIT WORKFLOW — YAML 驱动的 HTTP 工具链引擎

## 概述

TOOLKIT WORKFLOW 让你通过编写 YAML 文件来定义外部 HTTP 能力。一个 YAML 文件描述一个能力：它接受哪些参数、调用哪些外部 HTTP API、如何从响应中提取数据、以及最终返回什么给 LLM。

模型初始只暴露三个入口工具：`query_capabilities`、`query_capability_detail` 和 `call_capability`。YAML 能力不会直接出现在初始 tools 数组中，必须先查询能力列表或详情，再通过 `call_capability` 按能力名称和参数调用。

核心能力：
- 一个 YAML 文件 = 一个完整的 HTTP 能力，无需写代码
- 支持多步 HTTP 请求链，步骤之间可以传递变量
- 流程控制：`next` 跳转步骤、`jump` 降级到备源、`abort` 终止执行
- 键级缓存：`cache` 缓存变量，同一调用中缺键自动重请求
- 统一提取：`extract` 字段，语法自描述引擎（路径 / 正则）
- 工具分类：`api` 能力用于发现和调用 iAs 内部 HTTP API；`http` 能力来自 `tools/*.yaml` 外部 API 配置。
- 内部 HTTP API 不再为每个 endpoint 维护一个重复 AI 能力。模型应先调用 `query_api_docs` 查询功能分组、endpoint_id、参数和请求体，再调用 `call_http_api` 执行具体 endpoint。

---

## YAML 顶层结构

一个工具 YAML 文件包含以下顶层字段：

| 字段 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `name` | 是 | string | 能力名，对应 `call_capability.name` |
| `desc` | 是 | string | 能力描述，会出现在 `query_capabilities` 和能力详情中 |
| `params` | 否 | array | 能力参数定义，映射为 `query_capability_detail` 返回的 JSON Schema |
| `env` | 否 | array[string] | 该工具依赖的环境变量名列表，仅作文档和校验 |
| `steps` | 是 | array | 请求步骤链，按顺序执行 |

---

## `params` — 参数定义

定义 LLM 可以传入的参数，映射为 function calling 的 parameters schema。

| 字段 | 必填 | 类型 | 说明 |
|------|------|------|------|
| `name` | 是 | string | 参数名，在模板中通过 `${param:key}` 引用 |
| `type` | 是 | string | 取值：`string` / `number` / `integer` / `boolean` |
| `required` | 是 | boolean | 是否必填 |
| `description` | 是 | string | 参数说明，LLM 据此理解参数含义 |
| `default` | 否 | any | 默认值，LLM 未传时自动使用 |

---

## `steps` — 请求步骤

每个步骤定义一个 HTTP 请求及其后续处理。

### 步骤字段

| 字段 | 必填 | 类型 | 默认值 | 说明 |
|------|------|------|--------|------|
| `url` | 是 | string | — | 请求 URL，支持模板语法 |
| `method` | 否 | string | `GET` | HTTP 方法：`GET` / `POST` / `PUT` / `DELETE` / `PATCH` |
| `headers` | 否 | map | — | 请求头键值对，值支持模板语法 |
| `query` | 否 | array | — | URL 查询参数，格式为 `[{key, value}]` 元组列表，值支持模板语法 |
| `body` | 否 | string | — | 请求体，支持模板语法 |
| `timeout` | 否 | integer | 30 | 超时时间（秒） |
| `cache` | 否 | boolean | false | 是否对该步骤启用键级缓存 |
| `next` | 否 | integer | — | 步骤成功后跳转到第几个步骤（0-based），不设则顺序执行下一步 |
| `var` | 否 | array | — | 变量提取列表 |
| `result` | 否 | string | — | 最终返回模板，有此字段则该步为终步 |

### 步骤示例

```yaml
steps:
  - url: ${env:BASE_URL}/auth/token
    method: POST
    headers:
      Content-Type: application/json
    body: |
      {"client_id": "${env:CLIENT_ID}", "client_secret": "${env:CLIENT_SECRET}"}
    timeout: 15
    cache: true
    var:
      - name: token
        extract: access_token
        abort: true
    next: 1

  - url: ${env:BASE_URL}/orders/${param:order_id}
    method: GET
    headers:
      Authorization: Bearer ${step0:token}
    var:
      - name: status
        extract: data.status
      - name: amount
        extract: data.amount
    result: |
      订单号: ${param:order_id}
      状态: ${step1:status}
      金额: ${step1:amount}
```

---

## `var` — 变量提取

每个步骤执行完 HTTP 请求后，按顺序处理 `var` 列表中的条目，从响应中提取命名变量。提取的变量通过 `${stepN:var_name}` 在后续步骤中引用。

### `extract` — 提取表达式

一个字段覆盖所有提取场景。值的语法决定使用的引擎：

| 语法 | 引擎 | 说明 |
|------|------|------|
| 不以 `/` 开头 | 路径引擎 | 对 JSON/YAML 响应执行结构化路径导航 |
| 以 `/` 开头且以 `/` 结尾 | 正则引擎 | 对原始响应文本执行正则匹配，取捕获组 1 |

**路径引擎**：自动检测响应格式（先 JSON，失败则 YAML），然后按路径导航取值。

| 语法 | 含义 | 示例 |
|------|------|------|
| `key` | 访问对象字段 | `data.status` |
| `key[N]` | 访问数组第 N 个元素 | `items[0].name` |
| `key[]` | 遍历数组所有元素 | `books[]` |
| `key[].field` | 遍历数组，对每个元素取字段 | `books[].title` |

> 键名建议仅使用 `[a-zA-Z0-9_]`，避免含 `.` `[` `]` 的特殊键名。

**正则引擎**：`/pattern/` 形式，对原始响应文本执行正则匹配，取第一个捕获组。

```yaml
# 路径：从 JSON 响应中提取
var:
  - name: token
    extract: auth.access_token

# 正则：从任意文本中提取
var:
  - name: session
    extract: /session[= ]([a-f0-9]+)/
```

### 提取失败处理（每个条目最多选一种）

| 配置 | 提取成功 | 提取失败 |
|------|---------|---------|
| 不设任何失败处理 | 存入变量 | 存入空字符串 `""`，继续执行 |
| `default: "值"` | 存入变量 | 存入默认值，继续执行 |
| `abort: true` | 存入变量 | 终止整个工具，返回错误给 LLM |
| `jump: N` | 存入变量 | 跳转到第 N 个步骤执行，N 从 0 开始 |

### var 条目完整字段

| 字段 | 必填 | 类型 | 默认值 | 说明 |
|------|------|------|--------|------|
| `name` | 是 | string | — | 变量名，通过 `${stepN:name}` 引用 |
| `extract` | 否 | string | — | 提取表达式，语法自描述引擎（路径 / 正则） |
| `default` | 否 | string | — | 提取失败时的默认值 |
| `abort` | 否 | boolean | false | 提取失败时是否终止工具 |
| `jump` | 否 | integer | — | 提取失败时跳转到第几个步骤（0-based） |



---

## 流程控制

三种流程控制机制，覆盖顺序执行、条件跳转和异常终止。

### `next` — 成功后跳转

- 位置：步骤级别
- 触发条件：步骤所有 var 都没有因 abort/jump 而失败
- 效果：跳转到指定步骤号（0-based），不设则顺序执行下一步
- 用途：跳过某些步骤、实现条件分支

### `jump` — 提取失败时降级

- 位置：var 条目级别
- 触发条件：该条目的提取失败且未设置 default
- 效果：跳转到指定步骤号（0-based），当前步骤剩余 var 不再执行
- 用途：主数据源失败时自动切换到备数据源

### `abort` — 提取失败时终止

- 位置：var 条目级别
- 触发条件：该条目的提取失败
- 效果：终止整个工具执行，返回错误信息给 LLM
- 用途：关键变量（如认证 token）获取失败时立即报错

---

## `cache` — 键级缓存

当步骤设置 `cache: true` 时，该步骤提取的所有变量会被缓存。

缓存行为：
- **命中**：缓存中存在该步骤所有 var.name → 跳过 HTTP 请求，直接返回缓存值
- **未命中**：任意一个 var.name 缺失 → 发起 HTTP 请求，提取所有变量，全部存入缓存
- **生命周期**：单次工具调用期间（内存级），工具返回后释放
- **缓存键**：由步骤的 `url + method + headers + body` 模板展开后的哈希确定

典型用法：第一步获取认证 token 并缓存，后续多步复用 token 时不会重复请求认证接口。

---

## 模板语法

以下字段支持模板语法：`url`、`headers` 的值、`body`、`result`。

### 三种引用

| 语法 | 来源 | 示例 |
|------|------|------|
| `${param:key}` | `call_capability.parameters` 传入的能力参数 | `${param:city}`、`${param:order_id}` |
| `${env:VAR}` | 系统环境变量 | `${env:API_KEY}`、`${env:BASE_URL}` |
| `${stepN:var_name}` | 第 N 个步骤提取的变量，N 从 0 开始 | `${step0:token}`、`${step1:status}` |

### 约束

1. 禁止嵌套引用：`${step0:${env:KEY}}` 不允许
2. 禁止原始步骤引用：`${step:0}` 不允许，必须先通过 var 提取为命名变量


---

## `result` — 最终返回

步骤的 `result` 字段定义该工具最终返回给 LLM 的内容。

- 如果某步设置了 `result`，该步即为**终步**，执行后不再继续后续步骤
- 如果所有步骤都未设置 `result`，默认返回最后一步的原始响应体
- `result` 支持模板语法，可以拼接多个变量和文字

```yaml
# 返回单个变量
result: ${step1:status}

# 多行模板拼接
result: |
  订单号: ${param:order_id}
  状态: ${step1:status}
  金额: ${step1:amount}
```

---

## 执行流程

```
1. 加载 YAML → 解析为 YamlToolDef
2. 解析 LLM 参数 → params HashMap
3. 加载 env 声明的环境变量 → env HashMap
4. 初始化 cache = {}

5. step_idx = 0
   while step_idx < steps.len():

   ┌─ 当前步骤执行 ──────────────────────────────┐
   │                                              │
   │  [cache: true?]                              │
   │    ├─ 缓存命中（所有 var 键都存在）→ 跳过HTTP  │
   │    └─ 缓存未命中 → 继续                       │
   │                                              │
   │  展开 url/headers/body 中的模板               │
   │    ${param:key} → params["key"]              │
   │    ${env:VAR}    → env["VAR"]                │
   │    ${stepN:var}  → ctx.vars[(N, var)]        │
   │                                              │
   │  HttpRequest 执行 → HttpResponse             │
   │    保存到 ctx.steps[step_num]                 │
   │                                              │
   │  for each var:                               │
   │    extract 语法分发:                          │
   │    ├─ /.../ → 正则引擎，取捕获组1             │
   │    └─ 其他  → 路径引擎（JSON→YAML 自动检测）  │
   │    ├─ 成功 → 存入 ctx.vars + step_vars       │
   │    └─ 失败 →                                  │
   │        ├─ abort:true  → 终止，返回错误        │
   │        ├─ default:x   → 使用默认值            │
   │        ├─ jump:N      → step_idx = N, break  │
   │        └─ (无)        → 空字符串              │
   │                                              │
   │  [cache: true?] → 将 step_vars 存入 cache     │
   │                                              │
   │  [result 存在?]                               │
   │    └─ 展开 result 模板 → 返回给 LLM → 结束    │
   │                                              │
   │  [next 存在?]                                 │
   │    ├─ next:N  → step_idx = N                 │
   │    └─ (无)    → step_idx += 1                │
   │                                              │
   └──────────────────────────────────────────────┘

6. 循环结束 → 返回最后一步原始响应体
```

---

## 错误处理

| 场景 | 处理方式 |
|------|---------|
| YAML 文件格式错误 | 启动时打印警告，跳过该文件 |
| 模板引用了未定义的参数 | 替换为空字符串，记录警告日志 |
| 环境变量未设置 | 替换为空字符串，记录警告日志 |
| HTTP 请求失败（连接/超时） | 返回错误详情给 LLM |
| `var.abort: true` 且提取失败 | 终止，返回 "变量 xxx 提取失败" |
| `var.jump: N` 且提取失败 | 跳转到第 N 个步骤，N 从 0 开始，不报错 |
| `var.default` 且提取失败 | 使用默认值，不报错 |
| 路径语法错误（空段、非法索引） | 返回错误给 LLM，附带路径表达式 |
| 路径键不存在 / 索引越界 | 提取失败，触发 default/abort/jump |
| 正则语法错误 | 返回错误给 LLM，附带正则表达式 |
| 正则无匹配 | 提取失败，触发 default/abort/jump |
| 响应体非 JSON 也非 YAML（路径引擎） | 返回错误给 LLM |
| `next` / `jump` 目标步骤不存在 | 终止，返回配置错误 |

---

## 扩展预留

以下字段预留供后续版本实现：

| 字段 | 位置 | 用途 |
|------|------|------|
| `retry` | `steps[]` | 失败重试次数与退避策略 |
| `cache.ttl` | `steps[]` | 缓存有效期（秒） |
| `validate` | `params[]` | 参数级正则校验 |
| `sensitive` | `env[]` | 标记敏感环境变量，日志脱敏 |
| `loop` | `steps[]` | 条件循环（分页自动翻页） |
| `export` | `steps[]` | 将变量导出为环境变量供子进程使用 |
| `pre_request` | 顶层 | 工具级别的前置请求（全局认证） |