Files
ThearchyHelios 5a341b48e9 文档:新增 analysis 一篇(中英各一,标题层级一致)——分析能力是什么、为什么(判定由系统算、判定语由系统写、照实说、留痕)、五种分析各回答什么问题与判定标准(括号里是缺省阈值)、算不了的情形与调用写错、期次的写法、两个入口(Agent 的分析工具、分析卡)、引用写法、分析说法核对(判断词的类、check / strict / off、来源与因果的分界)、分析范围、设置、限制。更新:证据与出具(按引用核对的血缘口子与分析说法复核、口径卡指标的两期可比性、引用标记加 a: 与 v:A / table:A、点开一个分析结论看到什么、两种导出认分析结论、运行对比按分析卡对齐、复核套件加分析说法核对)、工作流(内置模板 11 个、节点类型表加分析卡、G3 加分析说法核对、agent 可绑分析工具)、问数据(分析类问题怎么走、复核只写说明的几种缺口、分析结论的数不标口径、自查提醒)、回归评测与口径账本(贡献、判定两种期望与评分,细节待评测包交付后校对;分析结论的数不比对口径)、配置(偏好设置里的分析一节,17 项的叫法、缺省、范围)、工具(内置工具 23 个、分析工具一节;原来写的 15 个早已对不上)、升级说明(本轮);README 中英加一条主要功能、文档索引加 analysis,节点 19 种、模板 11 个。development.md 的检查项数没动,等前端包的数
2026-10-21 18:25:46 +08:00

85 lines
6.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
[English](../en/tools.md) | 简体中文
# 工具、MCP 与能力登记
这篇讲工作流能调用的工具:内置工具(含分析工具)、自定义工具和 MCP,它们的审批档位,管理员怎么在能力登记里管住它们,以及怎么登记外部系统的端点。给搭建者和管理员看。
## 工具种类
- **内置工具**:23 个,其中 5 个是分析工具(见下文)。
- **自定义工具**:HTTP 模板,或沙箱里的 Python。
- **MCP**:接入 MCP server(stdio 或 http)。
- **数据源工具**:每个数据源的查询工具 `db_query__<源>`,以及运行时查结构的 `db_schema__`(见[数据源](data-sources.md))。
谁能配:MCP 的 stdio、端点和凭据、能力治理只有管理员能改,搭建者只读,使用者看不到(见[权限表](identity-and-security.md#权限表))。
## 分析工具
五个分析工具是平台的确定性分析:`analysis_decompose`(变化拆解)、`analysis_baseline`(波动基线)、`analysis_trend`(趋势判断)、`analysis_differ`(差异检验)、`analysis_comparable`(可比性检查)。它们不查库,只分析绑了它的 agent 这次执行里查过的结果,判定由平台按固定的方法和阈值算,判定语由系统写(见[Agent 的分析工具](analysis.md#agent-的分析工具))。
- 参数里没有阈值。绑了任一个,平台就把内置的分析方法注入 agent 的系统提示,同一份只注入一次。
- 只读、不写任何东西,不算危险工具:缺省的审批策略下不用等审批;使用者的问数据里也能用。
- 只能绑给 agent:放进「调用工具」节点时画布校验报错,模板里要固定做的分析用分析卡(见[分析卡](analysis.md#分析卡))。
- 每个 Agent 每次执行最多分析 12 次(「设置 → 偏好设置 → 分析」里改)。
- 它们不连数据源:读的是这次执行里已经查回来的快照,交回的是分析结论,不是查询结果。
## 审批档位
平台看不出 MCP 和自定义工具做什么,所以它们默认每次调用都等审批。审批档位有三档:`ask`、`gated`、`always`。
- 在工具页可以逐个改成「始终允许 · 门控把关」:每次调用先由门控模型审一遍参数,拿不准、出错、超时都交还给人。
- 也可以改成「始终允许」。审批卡上的「始终允许」等于「始终允许 · 门控把关」。
- 档位在发起运行时快照,恢复和接着跑沿用同一份。
- 正式运行不看档位,一律等审批;例外是能力登记里声明为只读、审批设为免审批的能力(见下文)。
## 能力登记
「工具 → 能力」把内置工具、数据源、自定义工具、MCP 工具登记在一处,名字就是图里的工具名。
- 启动时和各对象增删改时自动同步。来源删掉的标为「缺失」,不删除。
- 管理员可以逐项治理:效果(只读 / 写入 / 视参数而定)、审批(跟随信任设置 / 总要确认 / 免审批)、是否允许无人值守写入、返回的表格位置、字段语义(形状和数据目录的「项」相同,推断的项进「待审阅」)、遮罩字段、凭据模式、查询能力。
- 每改一次,版本号加一。正式运行在发起时固定版本,发布时记下版本,之后有变化只提醒。
### 正式运行免审批
声明为只读、审批设为免审批的能力,在正式运行里直接执行。带 MCP、自定义工具的 Agent 因此不会停在半路等审批。可写数据源上的写语句,不会因为一句声明而免审批。
### 写入只能经调用工具节点
写入能力只能放在「调用工具」节点里:
- Agent 或多 Agent 协作的工具清单里有写入能力时,发布检查在各级都报错,运行时也拒绝。
- 工具页的试运行、工具库里的执行,碰到写入能力一律演练:不发送,交回将要发送的方法、地址、请求头名和请求体。
- 试运行没保存的草稿时,请求按草稿的配置拼;读写按已保存的治理和草稿的方法里更严的一个认。
- 试运行和端点的「测试连接」按 HTTP 状态说成败:2xx 才算成功;能连上但回 404、401 的,照实写状态码。
- 查询能力(用来核实写入结果)只能选同一端点上、绑定这个端点的只读能力。
写外部系统的完整规则见[应用](apps.md#写外部系统)。
## 登记端点
管理员按测试、生产两个环境,登记外部系统的地址和认证头。认证头加密存,界面上只回掩码。
- 只有登记过、开了「允许访问内网」的端点能连内网。元数据地址和高危端口照样拦。
- 绑定端点的 HTTP 工具只填方法、路径模板、查询参数和请求体;路径参数逐段编码后代入。模型拿不到任意地址,请求也不跟随跳转。
- 正式运行走生产环境。探索运行里,写入走测试环境(没有测试环境就演练),读取走生产环境。
- 凭据模式选「服务凭据 + 身份断言」时,请求另带 `X-AgentLab-Assertion`:EdDSA JWT,5 分钟有效;`aud` 是端点名,`sub` 是运行发起人,确认动作的人在 `act` 里。公钥在 `/api/auth/jwks`。
- 指向本机或内网的 http MCP,要管理员先在「工具 → 端点」登记。
### 端点读取可以作证
给只读的、绑定端点的工具声明表格(行的位置、各列的位置)后,结果落成和查询快照形状相同的端点快照:
- 报告里照样编号 Q1…,单元格点得开出处;
- 运行对比照样比,比的是请求;
- 遮罩按列名。
Python 工具和 MCP 不在此列。
## 网络和凭据
- HTTP 工具先解析域名,再逐个 IP 检查,拦截内网、回环与云元数据地址;不跟随重定向,每一跳重新校验。模型给出的地址照样做完整的 SSRF 检查。
- 本机代理开了 fake-ip 时,解析结果是 198.18 段的假地址。在 `AGENTLAB_HTTP_TOOL_FAKE_IP_RANGES` 里配上这个网段(例如 `198.18.0.0/15`)后,这类结果改向公共 DNS(DoH)核实真实地址再判断;核实不了按拦截处理。DoH 地址由 `AGENTLAB_HTTP_TOOL_DOH_URLS` 指定,逗号分隔(见[常见问题](faq.md))。
- 文件工具的路径 `resolve()` 后必须仍在工作区内。
- 自定义工具的请求头、MCP 的环境变量与请求头、端点的认证头都加密存,只回掩码。