# 表单与确认

每次变更只走一条路。创建或修改的请求会打开你页面自己的表单并预先填好；提交的内容变成一张绑定确切参数的确认卡；只有用户确认后才会执行调用。

![对话中出现的产品自己的创建表单](/images/host-form.png "用户写了「create a server」。路由选中 create_vm，控制台自己的表单随即打开；模型从没有用文字询问各个字段。")

<ol class="steps">
<li><b>提问</b>「创建一台 GPU 服务器，叫 train-01。」</li>
<li><b>路由</b>一次静默的模型调用选中 create_vm，并保留用户说过的内容：名称。</li>
<li><b>表单</b>你的创建表单在对话中打开，名称已经填好。</li>
<li><b>解析</b>提交的内容经过校验，名称换成 ID。</li>
<li><b>确认</b>卡片原样展示提交的内容，用户确认。</li>
<li class="host"><b>执行</b>你的 API 收到带确认 ID 的调用，并进行授权。</li>
</ol>

## 为什么只有一条路

让模型去创建东西，它往往会即兴发挥：用文字列出字段、猜一个可用区，或者连问三个问题，下一次运行又换一种做法。你的产品早就有做这件事的表单，带着选项、默认值和校验。指定了表单的操作，只从那个表单获得输入；每个写操作都要等一张确认卡，而这张卡由运行时展示，不由模型展示。同样的请求，每次都走同样的路。

## 声明表单

操作指向你的 API 中一个 `role: form` 的操作：

```json
"/api/vms": {
  "post": { "x-rungent": { "name": "create_vm", "description": "Create a cloud server (VM).", "form": "vm_form" } }
},
"/api/vms/form": {
  "post": { "x-rungent": { "name": "vm_form", "role": "form" } }
}
```

表单操作是一个不改变任何东西的 `POST`，所以 rungent 把它当作无需确认的读操作。rungent 把目前已知的参数发给它，它返回表单的通用描述，因此可以只列出用户配额允许的可用区：

```json
{
  "prompt": "Create a server",
  "questions": [
    { "id": "name", "prompt": "Name", "kind": "text", "required": true },
    { "id": "zone_id", "prompt": "Zone", "kind": "choice", "required": true,
      "options": [{ "id": "z1", "label": "Beijing A", "recommended": true }, { "id": "z2", "label": "Beijing B" }] }
  ]
}
```

每个问题的 `id` 是它所填参数的点分路径（`zone_id`、`network.cidr`）。一个表单有 1 到 24 个问题，每个是 `text` 或 `choice`（需要时加 `multiple` 和 `allowCustom`）；完整结构见 [HTTP API](http-api.md#form-rungent-form)。你的 Web 应用会改为显示自己的表单组件，没有自己组件的客户端显示这份描述。

## 路由把请求送到表单

当目录里有带表单的操作时，每条新的用户消息都先经过**路由**：一次静默的模型调用，它只看得到这些操作和一个 `continue` 工具。如果消息要创建或修改的东西正是其中某个操作做的，rungent 立即打开它的表单，Agent 循环不会运行。即使请求还要求先问一问，或者提到了一个可能不存在的选项，也照样送到表单：这些问题就该在表单里回答。

其他请求，比如一个问题、一次查询，或者「stop gpu-train-01」，都交给 Agent。路由不发出任何事件，也不往对话里加任何内容。

## 显示页面自己的表单

在 `RungentProvider` 上用 `forms` 按操作名注册你创建页面所用的组件：

```tsx
import { RungentDock, RungentProvider, type HostFormProps } from 'rungent/react';
import { CreateVmForm } from './vms/create-vm-form';

function CreateVm({ arguments: args, issues, submit, cancel }: HostFormProps) {
  return <CreateVmForm initial={args} errors={issues} onSubmit={submit} onCancel={cancel} />;
}

<RungentProvider client={client} forms={{ create_vm: CreateVm }}>
  <RungentDock>{page}</RungentDock>
</RungentProvider>
```

| 属性 | 含义 |
|---|---|
| `op` | 表单对应的操作 |
| `arguments` | 起始值：用户说过的内容，或他们上一次提交的内容 |
| `issues` | `{path, message}[]`：上一次提交被拒的原因；第一次打开时为空 |
| `submit(args)` | 提交操作的完整参数 |
| `cancel()` | 关闭表单；调用不会执行 |

表单从用户说过的参数开始填；模型弄错的参数会被丢掉。rungent 按操作的输入 schema 校验提交的内容。不符合的会重新打开表单，每个问题对应一条 issue（`{"path": "zone_id", "message": "required"}`），什么也不会执行。符合的继续进入名称解析和确认卡。

## 问清是哪一个

Agent 还有一种提问方式：内置的 `request_input` 工具，用来以选项的形式问清用户指的是哪个对象、哪个动作。有两台名字相近的服务器时，「停掉那台 gpu 服务器」会问是哪一台，而不是去猜。它从不用来收集操作的输入，那是表单的事。

## 由什么决定一次调用需要确认

只由目录里操作的 `approval` 决定：每个写操作默认是 `always`，读操作是 `never`（[目录](catalog.md#effects-approval-and-surfaces)）。这个决定写在运行时的代码里，提示词和模型输出都不参与，所以模型没法靠说服绕过确认卡。你的 API 还会再检查一次：`approval: always` 的调用，其断言必须以 `apr` 带上确认的 ID。

在确认卡出现之前，rungent 依次校验输入（或通过表单收集输入）、解析名称、查出目标的名称。任何一步失败，调用就停下，不会有写请求到达你的 API。

![助手面板里的确认卡：Stop server gpu-train-01?](/images/approval.png "用户要求停止 gpu-train-01。rungent 找到了服务器，查到了它的名称，然后等待；此时还没有任何请求到达 API。")

## 编写确认卡

操作上的 `confirmation` 决定卡片的样子：

```json
"confirmation": {
  "title": "Stop server {resource_name}?",
  "target": "{resource_name} ({vm_id})",
  "fields": [{ "key": "forced", "label": "Force", "values": { "true": "Yes", "false": "No" } }],
  "lookup": { "path": "/api/vms/{vm_id}", "labelPath": "name" },
  "risk": "medium",
  "costHint": "Billing drops to storage only, about ¥0.4/hour."
}
```

模板里可以用 `{参数名}` 占位符和 `{resource_name}`。有 `lookup` 时，rungent 在出卡片前以用户身份对 `path` 发一次 `GET`，从返回里读出 `labelPath` 作为 `{resource_name}`，这样模型传的是 `vm-42`，用户看到的是 `gpu-train-01`。这个路径必须由目录里的某个 `GET` 操作提供，查询失败就停止调用。没有 `confirmation` 时，卡片标题是操作的 `title`。所有键见 [x-rungent](x-rungent.md#confirmation)。

## 确认绑定到确切参数

卡片出现时，rungent 冻结它展示的参数，并把确认连同这些参数的哈希 `argsHash` 一起存下：参数按规范 JSON（[RFC 8785](https://www.rfc-editor.org/rfc/rfc8785)）序列化后的 SHA-256，用 base64url 编码。客户端回答时带上它展示过的哈希。

- 哈希和存下的不一致就拒绝，什么也不执行。
- rungent 执行的是冻结的参数；回答无法换成别的参数。
- 每个确认最多执行一次，即使两个 rungent 副本同时收到回答。
- 已确认的调用一定会执行完并被记录，即使用户关掉了页面。
- 确认在卡片出现 15 分钟后过期。之后再确认、拒绝，或者改发一条新消息，都不会执行任何东西，模型会告诉用户这一点。

## 助手之外

表单只属于助手：MCP 客户端和 CLI 传入操作的完整参数，由同一份输入 schema 校验。但每个入口在写操作前都会先问：

- **MCP。** `mcp` 入口上的写操作通过 MCP elicitation 询问用户，标题、对象和变更都一样。不支持 elicitation 的客户端会收到 `not_executed`，什么也不会执行。
- **CLI。** CLI 在终端上问 `[y/N]`；脚本里用 `--yes` 确认。既没有终端也没有 `--yes` 时，写操作会被拒绝。

两者都在断言里带上确认 ID，所以你的 API 在哪里都是同一套检查。

## 接下来

[搜索与知识](search.md)讲 Agent 如何找到用户叫不出名字的东西。
