mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-15 00:51:59 +00:00
ThearchyHelios
2714890d0d
README.zh-CN.md / README.md 只留：这是什么、为什么用它、主要功能（按领域一行一条，链到文档）、快速开始、部署、文档索引、 开发与测试、许可（原文不动）。原来的每一节按读者和任务分到 17 篇主题文档：ask-data、workflows、evidence、 data-sources（新增：接入数据库、只读保证、上传表格、跨库合并、遮罩列）、data-catalog、tools（新增：工具、审批档位、 能力登记、端点、网络规则——它们管所有工作流，不只应用）、apps、evaluation-and-ledger、schedules（含通知）、deployment、 configuration、postgresql-and-scaling、identity-and-security、architecture、development、upgrade-notes（按时间倒序， 每波先写要做的事）、faq。删掉的只有模块名（api/copilot_gen.py、chat/drive.py、data/schema_view.py）、重复的话和 「以前…现在…」的叙述；操作步骤、命令、配置名、限制、权限边界都有归宿。中文是原文，英文按新的中文写；英文里界面文字 只写英文名，开头注明界面目前只有简体中文，中文占位符换成英文占位符，中文数字的例子改成不依赖中文的说法。 数据剖析可以同时剖析 2–3 张表（baf23998）收进 data-catalog。 新增 scripts/check-docs.py：英文文档（README.md、docs/en/**）不许有中日韩字符和全角符号（代码块也算）， README、docs/**、deploy/README.md 的相对链接和锚点都要通，docs/zh-CN 与 docs/en 文件一一对应、标题层级相同。 中文提示里指向 README 章节的地方改指新文档：cluster/guard.py、cluster/version.py、db/base.py 两处报错， data/schema_view.py 文档串，.env.example 三处，scripts/prod.sh、scripts/test-postgres.sh，terms.ts 两处、 DataSourcesTab.tsx、check-manage.mjs 注释，deploy/README.md 三处链接。deploy/agentlab.env 未动。 验收：check-docs 0 问题（英文文档 18 个 0 处中文，相对链接 369 条 0 断链，18 对标题层级一致）；相关后端测试 117 通过、7 跳过；tsc -b、check-copy 通过。
75 lines
5.2 KiB
Markdown
75 lines
5.2 KiB
Markdown
[English](../en/tools.md) | 简体中文
|
||
|
||
# 工具、MCP 与能力登记
|
||
|
||
这篇讲工作流能调用的工具：内置工具、自定义工具和 MCP，它们的审批档位，管理员怎么在能力登记里管住它们，以及怎么登记外部系统的端点。给搭建者和管理员看。
|
||
|
||
## 工具种类
|
||
|
||
- **内置工具**：15 个。
|
||
- **自定义工具**：HTTP 模板，或沙箱里的 Python。
|
||
- **MCP**：接入 MCP server（stdio 或 http）。
|
||
- **数据源工具**：每个数据源的查询工具 `db_query__<源>`，以及运行时查结构的 `db_schema__`（见[数据源](data-sources.md)）。
|
||
|
||
谁能配：MCP 的 stdio、端点和凭据、能力治理只有管理员能改，搭建者只读，使用者看不到（见[权限表](identity-and-security.md#权限表)）。
|
||
|
||
## 审批档位
|
||
|
||
平台看不出 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 的环境变量与请求头、端点的认证头都加密存，只回掩码。
|