第 3 章 Tool、Skill、MCP 与执行安全
3.1 Tool、Skill、MCP
Tool 是一次可执行的动作,Skill 是处理某类任务的方法,MCP 是让客户端发现和调用工具或资源的协议。
| 概念 | 做什么 |
|---|---|
| Tool | 一次可执行的动作,例如读取文件、查询数据库 |
| Skill | 处理某类任务的方法、步骤及可选脚本 |
| MCP | 让客户端发现、调用工具或资源的协议 |
我踩过的坑
- 2026-06-20 我以为:“飞书或微信其实是 MCP,而不是网关。”
正确理解
- Skill 可以组合多个 Tool,Tool 也可以通过 MCP 暴露。MCP 不是模型,更不能替代全部网关和业务服务。
- 飞书、微信属于消息入口,由平台 Adapter 把消息转成内部请求;Agent 执行过程中仍可以通过 MCP 调用工具。消息接入、MCP 工具协议和 API 网关处理的是不同问题,可以同时存在。
- MCP 的某个方法不受支持,不代表整个服务不可用。 要按能力分别判断:先确认服务声明了哪些工具或资源,再验证对应的调用。案例见附录 A.3.1。
3.2 工具注册、Schema 与执行器
工具有名称、描述、输入结构和执行实现;模型提出调用后,程序还要校验字段、授权目标、执行并回传结果。
图解:模型提出动作,程序决定能否执行
读图: 顺着箭头读,权限检查位于工具执行之前。Skill 是方法,MCP 是接入协议,两者都不能替代这里的执行授权。
正确理解
-
工具使用策略不是新的工具。 工具回答“能做什么”;策略规定什么场景能用、允许调用哪些、最多几轮、多久超时、何时停下;Skill 记录一类任务怎样分析与验证。初版有少量稳定、版本化的流程即可,不必马上做 Skill 自进化。
-
同一轮提出多个 Tool Call,不等于都能并发。 互不依赖的读取可以考虑并发;涉及同一文件、会话状态或数据库写入的动作,通常要保留先后关系。工具标了
isConcurrencySafe也只是声明,仍要验证它会不会改共享游标、连接或外部资源。并发结果按调用 ID 归位,不要把完成顺序当成请求顺序。 -
一种可行设计是按依赖把工具调用分成并行批次和串行步骤,汇合后校验并合并对共享 Context 的改动。这是调度选项,不是所有 Agent 固定执行的算法。
-
工具多时可以先检索,再按需提供 Schema。 “RAG for Tools”检索的是工具目录和能力说明,让模型发现候选动作;发现 Tool 不等于有权限执行,执行层仍要校验用户身份、资源范围、参数和副作用。向量检索也可能漏掉正确工具,必要时用关键词、分类目录或确定性白名单兜底。省多少 Prompt Token,要把检索调用、Schema 加载和额外轮次的成本一起算;旧稿“无限工具零成本”是未经验证的宣传。
-
流式 Tool Use 要等结构完整才执行。 输出前半段像某个工具调用,不代表最终参数已经完整、通过 Schema 校验或获得授权。工具调用事件和参数确定完成后,可以并发调度互不冲突的只读或幂等操作,减少 I/O 等待;写文件、发消息和外部事务必须核对最终调用内容、权限和副作用,避免模型后续变更或流中断时留下半次操作。并发收益要按整个回合实测,不是无条件把耗时变成两者的最大值。
-
工具报错也要有可理解的结果契约。 不要只回一个模糊的“Error”,也不要把含令牌、隐私或内部路径的原始异常栈塞进模型 Context。可以返回错误类别、被拒绝的参数字段、能否重试和下一步建议,完整诊断留在有权限的日志里。模型据此修正参数后,程序重新做 Schema、授权和预算校验;模型理解了错误,不等于获得了操作权限。
-
评测工具能力要看真实调用记录。 检查调用 ID、参数、退出状态和结果,不能在回答里搜到命令或正确字符串就算通过。案例见附录 A.3.2。
-
工具返回要区分成功、有意为空、部分失败、全部失败。 附实际来源、查询时间、结果数量和错误类别;所有异常都回
[],模型就会把“没查成”误当“没有”。上游支持的范围与本产品开放的白名单也分开,不能因为适配器支持更多能力就自动全部开放。 -
中间大对象可以用受控引用传递。 图片向量留在执行器,模型只传本次运行的引用 ID;引用要绑定运行身份、有效期和数量上限。进程内存适合同一进程的短任务,跨 Worker 或重启后继续使用要另做存储与恢复。也可让后端合成一个高层比较工具,但不要借此擅自把通用图片比较改成另一种业务。
-
一次外层工具调用可能藏着多次搜索或一个内部 Agent。 同时记外层调用数、内层请求、耗时和费用,程序执行预算;“最多几轮”是上限,不会强制模型按提示词搜满,也不保证检索范围。
历史依据:工具契约与临时引用 · 请求次数与实际检索范围。以上提炼为待学习的工程判断,不沿用当时的工具名单或预算。
- 适配工具事件时要核对消息类型。 修复优先校验“一次调用、一次结果、正确配对”;协议历史损坏时先停自动重试,不要把这种 400 当网络波动。案例见附录 A.3.3。
- 模型调用、工具调用和独立搜索 API 是三层能力。 模型生成文本、Agent 发起 toolCall、直接请求搜索 API 是三条不同的执行链。替换搜索服务时先画出实际路由和请求/响应契约;“模型能聊天”和“独立搜索接口可用”不能互相证明。
参数保真也是工具契约(课程摘记,待学习)。读取工具看到中文弯引号,替换工具却在中间层改成直引号,会出现“明明读到了,却匹配不到”。同理,执行层静默追加命令参数也可能让诊断偏离。必须核对模型提交、传输后和执行时的实际参数;确需规范化时,在工具说明与返回结果中明确告知,写后再回读。课程的具体 IDE 故障只作历史例子,不推断当前版本仍有该问题。
3.3 执行权限
模型说“可以删除”不代表系统允许删除。身份、资源归属、敏感操作、只读/可写权限和必要的二次确认,要在确定性代码中检查。
我踩过的坑
- 学 Claude Code 源码时,我把权限规则(rule)和实际询问用户(ask)看成同一个动作,还回答过“工具执行之后再检查权限”。
正确理解
- 我曾考虑按风险分级的执行 Hook:常规只读操作自动通过,可疑动作先问用户,严重危险的操作直接拒绝。关键是执行前拦住,不是执行后才提醒。
- 程序先判断允许、拒绝,还是需要问用户;需要确认时再暂停等用户授权。预防危险副作用的权限检查必须在执行前,执行后的 Hook 和日志用于审计和结果处理。Hook 能否覆写具体权限判断,要看对应产品、版本和配置,不能把某份学习源码的规则当成现行统一行为。
- 沙箱等级要匹配任务风险,但工具标签不是隔离本身。 可以按实际权限和风险,把操作放在本地受控环境、容器或专用远程执行环境。无论哪种环境,都要核对文件系统可访问范围、网络出口、凭据、进程身份,以及主/子 Agent 的权限继承。参数 Schema 校验(例如 Zod)只保证格式符合契约,不能代替命令的安全判断和用户授权;用正则拦截危险命令也不是完整的安全边界。历史教材里的分级沙箱和 Hook 行为没有在本项目逐一实测。
- 后台子代理申请危险权限时不能无限等待。 跨进程审批要带上明确的请求 ID、实际执行者、目标资源和一次性动作范围,经可信通道送到用户,收到批准才能执行。无响应、主会话断连或审批超时,应进入拒绝或待人工恢复状态,不能悄悄继承主 Agent 的更高权限,也不能把长期挂起当作自动化成功。旧 PermissionBridge 只是一种候选架构,不能推定所有 Agent 产品都实现了。
- 阻止越权分“拒绝单次动作”和“限制整个会话”两级。 连续的未经许可操作可以触发告警、暂时冻结执行或升级人工审查,但不能只凭连续两次被拒绝就断定恶意。审批超时和文件 Mailbox 轮询不会产生新的授权:权限状态必须由可信系统记录、范围明确、过期即拒绝。旧稿的“固定 100ms 轮询/必定自愈”不是通用机制。
- 多层工具策略只能在已授权范围内收紧。 用户、项目、渠道、Agent、群组、沙箱、子代理各有规则时,实际可执行的工具要满足所有适用层的限制。插件未启用、Allowlist 写错工具名或缺配置时,不能因为“过滤后没有工具了”就静默放宽成所有工具可用。Hook 在授权之后改写了路径或参数,要在最终执行参数上复核权限;审批超时或无法确认身份时,按拒绝或人工恢复处理。旧 OpenCLAW 的分层数量、具体顺序和 Hook 覆盖行为是教学资料里的某个版本,不是当前统一标准。
- 旧笔记里互相矛盾的规则要先查官方。 案例见附录 A.3.4。
- 网页里的强模型可以当顾问,但发问、取回建议和本地执行要分权。 本地 Agent 负责筛选建议和执行。发问前审查有没有泄露私有上下文;网页建议不能直接获得本机删除、修改、发布权限;读取回复时要确认确实取到了 assistant 的内容。
- Prompt 禁令和系统调用层拒绝不是一个安全等级。 Prompt 写“禁止删除”只是行为规则,匹配 rm 的 Hook 也不是系统级保护,Python、Node 照样能删文件。真正的写权限要靠目录白名单、系统调用或沙箱边界、变更预览、备份和恢复;防住了删除,也挡不住覆写或错误同步。
来源
旧库 90-归档/20-个人/概念/CC-Hooks钩子.md 第 53—68 行;Claude Code Hook 官方参考,核对日期 2026-10-22。
先测默认权限和审批边界(待学习)
试装 Agent 时,先查新建实例默认拿到的权限,再看界面上的审批选项实际映射到哪个沙箱。某版工作台的文档显示,开启询问后仍允许写工作区。首次试验可以用专用目录,分别检查工作区内写入、越界拦截、等待批准和拒绝后的行为。该记录来自指定版本的文档,实际权限待验证。
3.4 Prompt Injection 与不可信输入
网页、仓库、Skill 描述、MCP 工具返回值都应当视作数据,而不是最高优先级的命令。
正确理解
- 这些内容都可能带有恶意指令;同名工具也可能试图遮蔽可信工具。工具来源、权限、沙箱、网络出口和审计要一起设计,单靠“提醒模型注意安全”不够。
- 仓库元数据也是不可信输入。 外来代码库可能带着影响后续工具执行的配置或自动化脚本;某些宿主机 Git 操作可能受仓库本地配置或扩展影响,所以**“只读查看一个陌生仓库”也不应默认完全无风险**。在高权限环境检视不可信仓库前,隔离执行身份和工作目录,限制可运行的脚本和扩展,核实信任边界。不要因为防护脚本发现可疑内容,就直接“清洗”或删除别人原有的 Git 元数据。这里只保留威胁和防护原则,不宣称某个旧攻击细节适用于所有 Git 版本。
- MCP 配置冲突按实际客户端的优先级和权限核对。 用户级、项目级、本机本地设置都能定义工具服务器,但不是“任何客户端都按深度 JSON 合并、Local 必定覆盖 User”。同名工具、命令、环境变量、密钥是合并还是替换,要查对应客户端和版本;最小权限限制也不会因高优先级配置自动继承。读取不可信项目里的 MCP 配置时,不能直接启动它声称的命令。
多轮探测要检查累计泄露(待学习)
单轮拒绝直接索取内部实现,还要测试换成行为表现、角色扮演或“只是假设”后,多轮是否拼出受保护的信息。模型顺着提问说“确实如此”,仍可能是迎合或编造;只有和可信配置、代码独立核对,才能确认泄露了真实实现。公开的能力说明与内部敏感信息按明确边界区分,不把所有产品限制一概藏起来。
历史素材:多轮探测记录 · 过程展示与信息边界。原报告的“满分”和架构推断不作为完整安全验收。
3.5 服务端请求伪造(SSRF)
不可信网页或搜索结果可能诱导云端浏览器或服务端访问其所在网络的内部资源,只检查初始域名不够。
正确理解
- DNS 解析结果、跳转后的目标都可能指向内网。要由实际发起连接的环境限制可访问地址,并隔离网络和凭据。
- 证据边界:相关学习只讨论了浏览器所在网络的潜在风险,没有验证攻击者已进入公司内网,也没有完成网络层防护的线上验收。
- 安全工具的拦截也可能是误伤,要先核对 DNS、代理模式和实际目的地址,再决定怎么处理。案例见附录 A.3.5。
来源
机制与源码回查:[Claude Code 理解](辅助材料/批次00-旧/理解-Claude Code.md)。
3.6 动态工具发现与 Prompt Cache
动态发现会改变模型可见的工具目录、Schema 和权限;为了命中缓存重放过期工具定义,会让模型调用已经不存在或已撤权的工具。
正确理解
- 旧框架学习中看到过“连接 MCP 后重组工具池”的线索,但没有稳定的跨版本性能数据,不能断言所有 Agent 框架的缓存都被禁用。
- 工程上可以把稳定的系统规则和工具目录摘要与版本化的动态工具定义分层处理。工具权限、Schema 或用户作用域一变,就明确新的缓存身份和失效条件;执行时仍由当前权限层重新验证。
- 算节省的 Token 时,要把发现调用、Schema 加载、缓存命中、误调用和额外回合一起算,不能只看静态 Prompt 比以前短多少。
- Skill 失效不都是路由 Prompt 的问题。 诊断顺序是:文件语法 → 实际加载胜出的路径 → 是否进入可见的工具/技能集 → 实际选用与执行。不能看到文件存在就证明已生效。案例见附录 A.3.6。
- 改了规则旧规则仍生效时,检查真正进入上下文的所有来源:系统配置、扩展、Skill 描述、镜像副本及其版本。两个技能组合起来可能在真实上下文里互相矛盾,要用同一输入分别测单独启用和组合启用。
来源
10-wiki/personal/wiki/queries/mcp动态工具池如何与prompt-cache共存.md。旧源码线索与设计方向,不是当前 Codex/Claude/Hermes 默认行为说明。
3.7 Explore、Propose、Apply、Archive
探索、方案、应用、归档是不同的过程阶段,不能互相冒充。
我踩过的坑
- 旧目录里 OpenSpec 有探索、方案、应用、归档几类 Skill,同一份 Skill 还同时出现在
.agent、.agents和.claude的工具适配目录里。这不是三套要分别学的技术,而是同一个外部流程在不同 Agent 入口的配置副本。
正确理解
- Explore 只定义问题和证据,可以讨论多个方案;Propose 把决策、范围和验收写清;Apply 在明确授权和适用的工作区里改动并执行检查;Archive 在真实验收完成后保存决策和版本。
- 探索时看到解决思路,不等于代码已经改了;写了规范文件,也不证明真实 UI 和数据已通过验证。
- 第三方 Skill 的固定触发词和“永远必须停在探索阶段”之类的话,不要直接升级成对用户的强制限制。用户已明确批准的安全低风险动作可以执行;高风险的发布、删除和越权操作按真实审批边界判断。
来源
旧库 .agent/skills/openspec-explore/SKILL.md、.agent/skills/openspec-propose/SKILL.md、.agent/skills/openspec-apply-change/SKILL.md 和 .agent/skills/openspec-archive-change/SKILL.md,OpenSpec 历史配置,不代表目前已安装。
3.8 工具目录刷新与 OAuth 授权分别验收(待学习)
服务端 tools/list 已有工具,账号 scope 已授权,旧客户端仍可能只加载旧目录;重新授权也未必刷新。一轮接入在新增统一插件后才看到全部工具,再走公开 OAuth→MCP 的写、读、改和重放。以后分别核对服务端、账号和客户端目录,刷新时机仍待学习。
来源与当时边界
3.9 设备连接、输入控制和数据权限逐层确认(待学习)
手机连上 Mac 不等于 Agent 能操作全部 App。分别查连接、屏幕、输入和应用数据权限;设备列表没发现手机,只能说明当前通道未发现。scrcpy、AnyDesk 是候选,机型插件与授权另验。截图→点击输入→结果回读要真机跑通;能点屏幕不代表能读私有数据库。本次未完成真机控制。
来源与当时边界
3.10 安全错误可诊断,例外范围仍要收窄(待学习)
代理 fake-ip 会触发默认 SSRF 拦截,包装层丢错误码后只剩“上游失败”,会误导排障。固定错误码和脱敏原因传到 CLI 与 MCP,原 URL、具体 IP、堆栈不直接回显。
显式开关只豁免指定 fake-ip 网段,其他私网、回环、链路本地、混合 DNS 仍拦;每次重定向和实际连接都同样检查。假 resolver 只能测逻辑边界,真实代理与网络另测,当前原理仍待学习。