docs/LOCAL_AGENT_SETUP.md

Rama main · réplica de lectura del repositorio original.

# 在一个入口配置本地智能体

[English](LOCAL_AGENT_SETUP.en.md) | 简体中文

希望让用户在本地智能体里操作已有业务系统时，打开 **智能体客户端 → 接入配置**，在应用行点击“配置接入”。面板把授权入口、系统说明、工具与审批、连接检查放在一起，按四步完成即可。

这些设置继续保存在原接入方和业务路由中。旧页面保留高级配置，并提供返回集中入口的链接；无需重复创建一套接入方或业务能力。

## 先分清三个角色

| 名称 | 决定什么 | 例子 |
| --- | --- | --- |
| 接入方（Client） | 哪个应用来连接、去哪里确认业务身份、最多能连接哪些工作空间 | 客服应用的接入标识与固定授权页 |
| 工作空间（workspace，对应业务路由） | 这个业务范围负责什么、使用哪些工具源、允许本地智能体怎样调用 | 客服工单空间、库存空间 |
| 用户的业务授权（Agent Session） | 当前是谁、属于哪个租户或账户、这次实际允许哪些业务范围 | 某位操作员在某个账户下的授权 |

接入方允许连接一个空间，不等于其中每个用户都拥有全部业务权限。调用时仍使用原业务身份，经过范围裁剪、审批与业务系统最终授权。

一个工作空间可以被多个接入方使用。修改其中的工具源或系统说明会影响所有使用这条路由的入口；如果需要独立配置，应先由管理员明确是否使用不同工作空间。

## 第一步：授权入口

在应用列表找到已有接入方，点击“配置接入”。尚未登记应用时，先通过“新建接入方”完成登记。

确认接入方启用，填写业务系统提供的固定 HTTPS 授权页，再选择允许连接的工作空间，点击“保存授权入口”。授权页应由业务系统负责登录、选择业务账户并确认权限；不为每个用户或门店复制一个中枢接入方。

“允许此接入方连接中枢”是接入方的共用开关。关闭它也可能影响同一接入方的网页聊天或其他入口；只想停止本地工具调用时，应调整第三步的工具开关。

## 第二步：系统说明

选择要配置的工作空间，开启“启用本地智能体”，填写四项说明：

- **业务系统名称**：产品或业务模块的正式名称，例如“客户服务系统”。
- **一句话介绍**：它通常负责什么，例如“处理客户咨询、服务工单和售后跟进”。
- **典型业务方向**：几项便于理解的业务领域，例如“工单查询”“回复准备”。
- **系统边界**：哪些事情应交给其他系统，例如“库存调整由库存系统处理”。

保存后，支持此功能的客户端会在首次搜索工具之前，把本会话已选目标的说明提供给智能体。它就能先分清目标，再查询具体允许的动作。单授权、同系统多授权和跨系统授权都使用同一套说明结构。

说明没有填写、旧版本尚不支持或暂时读取失败时，可以显示“系统用途未知”；已有授权和按需工具查询继续使用原流程。说明不是权限承诺，也不能写成要求模型绕过规则的指令。详细字段见[系统说明契约](AGENT_SYSTEM_INFO.md)。

## 第三步：工具与审批

打开“允许本地智能体调用工具”，选择已经登记的业务工具源和允许使用的 scope，再按需要勾选精确的写操作。

| 设置 | 实际含义 |
| --- | --- |
| 本地智能体已启用 | 允许本地会话编排；工具通道还需单独开启 |
| 允许调用工具 | 开放工具发现和调用通道；仍需有效工具源与授权 |
| 工具源的 scope 范围 | 从业务声明中筛选可进入此空间的能力 |
| 允许的写操作 | 精确指定写动作；留空不开放写入，不能填 `*` |
| 额外要求审批 | 在原规则上进一步收紧，不会取消业务声明中的审批 |

如果原工作空间的权限档是只读，即使选择写操作仍不会开放写入。页面会显示这个状态，原权限档与受众规则继续在路由高级配置中管理。

点击“读取工具目录”后，简表会列出每项业务动作的说明和操作标识、类型是查询还是写入，以及当前配置状态。可以先看懂动作，再调整 scope、写入清单和审批设置。

读取目录不会执行业务动作，也不等于最终用户已获准执行。补充编排规则和每轮工具上限放在“高级运行设置”，与第二步的产品介绍分别维护。

点击“保存工作空间”。第二步和第三步编辑的是同一工作空间配置；切换工作空间前先保存需要保留的修改。

## 第四步：检查连接

检查已保存的接入方、授权页和各工作空间状态，再点击“生成连接配置”。生成内容用于告诉客户端 **中枢在哪里、连接哪个应用和工作空间**，以及本机连接的显示名称；它不包含 Token，也不会自动替用户完成业务授权。

把这些公开连接参数交给本地客户端，随后由用户在业务授权页登录并确认。新会话显式选择授权范围，首消息后保持原范围；更换范围时按客户端规则新建会话。

“连接条件已配置”不表示工具一定可用，更不表示已经执行了业务。客户端仍要重新核对身份和实际授权。业务授权确认完成后，再按自己的测试流程验证一个允许的查询、一个受控动作及需要时的审批。

授权设备、运行记录和用量仍在同页的“设备与运行”查看。

## 保存或连接没有成功时

| 页面状态 | 下一步 |
| --- | --- |
| 系统说明未提供 | 可先使用原工具查询，再补充定位说明 |
| 可连接，但工具通道未开启 | 在第三步检查工具开关、工具源和范围 |
| 工作空间已停用或权限档只读 | 在原路由高级配置中核对；集中面板不会暗中改变它们 |
| 没有读取或保存权限 | 使用具备对应接入方、路由权限的管理员账户 |
| 配置已被其他操作更新 | 关闭面板重新打开，核对最新值后再保存 |
| 当前宿主不支持集中保存 | 升级配套宿主实现；不要回退为整行覆盖配置 |

## 接口附录：集中配置的保存边界

下列接口仅供管理控制台使用，沿用管理员认证与 RBAC，不使用终端用户的 Agent bearer。两类配置分别保存，不是跨接入方和路由的整体事务。

### 接入方设置

`GET /admin/api/clients/:app_id/agent-setup` 返回 `app_id`、`name`、`enabled`、`agent_authorize_url`、`allowed_routes`、`revision`。响应不包含 Client Token。

`PUT` 同一路径必须且只能提供以下四个字段：

```json
{
  "expected_revision": "<GET 返回的 revision>",
  "enabled": true,
  "agent_authorize_url": "https://business.example.com/agent/authorize",
  "allowed_routes": ["helpdesk"]
}
```

`agent_authorize_url` 可设为 `null` 清除。`allowed_routes` 最多 256 项，沿用现有 workspace 与 `*` 语义；显式选择空间便于判断影响范围。`revision` 比较上述三个可编辑设置，保存只更新这三项，不轮换 Token，不改其他接入方属性。

GET 需要 `clients:read`，PUT 需要 `clients:write`。无权限为 403 `forbidden`；不存在为 404 `client_not_found`；格式错误为 400 `invalid_agent_setup` 或现有配置校验错误。

### 工作空间设置

`GET /admin/api/routes/:route_key/agent-setup` 返回 `route_key`、`name`、`enabled`、`permission`、`revision`、`agent_client`、`tool_sources`、`agent_direct`。`permission` 是只读展示字段，不允许随 PUT 修改。

`PUT` 同一路径必须且只能提供 `expected_revision`、`agent_client`、`tool_sources`、`agent_direct`。`agent_client` 和 `agent_direct` 可以为 `null`；`tool_sources: []` 清除工具源选择。请求应基于刚读取的值编辑，保留已有指令、工具上限及工具源附加选项。完整示例见[系统说明接口](AGENT_SYSTEM_INFO.md#控制台集中配置接口)。

GET 需要 `routes:read`，PUT 需要 `routes:write`。保存比较完整路由修订，仅更新 `agent_client`、`tools` 和更新时间；路由目标、权限档、受众、记忆、知识与其他配置保持原值。不存在为 404 `route_not_found`；无效输入为 400 `invalid_request` 或现有路由配置校验错误。

两类保存的修订均为 64 位十六进制字符串。并发冲突返回 409 `agent_setup_conflict`；缺少对应宿主原子保存实现返回 503 `agent_setup_unsupported`，不会静默覆盖。成功返回最新投影与修订。

集中配置和系统说明沿用现有存储字段，本轮功能不新增数据库迁移，不改变业务 API、审批、固定会话范围或归档协议。