> ## Documentation Index > Fetch the complete documentation index at: https://labs.prompthon.io/llms.txt > Use this file to discover all available pages before exploring further. # 本地智能体工具链来源图谱
需要帮助？
在 Discord 提问 提交 GitHub Issue 支持指南
## 概述 这份说明汇集了供撰写本地智能体系统内容的贡献者使用的官方来源输入：这些智能体在用户的文件、工具、项目状态和工作流指令附近运行，而不是仅作为远程聊天界面工作。 当草稿需要解释“本地”究竟意味着什么时，可以使用它。真正持久的模式不是某个模型所在的位置，而是以下要素的组合： * 用于寻找相关能力的 discovery 路径 * 执行环境或本地工具边界 * 可复用的技能或工作流打包 * 明确的文件系统或文档作用范围 * 可被选择、搜索、读取或刷新的资源 * 让边界对用户而言清晰可理解的权限规则 ## 如何使用这份说明 这是一张来源图谱，不是一篇完整文章。后续贡献者应使用它来： * 先判断草稿讨论的是 discovery、connection 还是 execution * 在描述智能体之前先定义边界 * 为所做的主张选择合适的来源 * 将本地文件、所选资源、技能和连接器区分开来 * 补充案例研究示例，展示智能体可以读取、写入和审阅什么 ## 为什么它很重要 本地智能体相关话题很容易被夸大。一本有用的手册应当区分几个经常混在一起的关注点： * `discovery`: 智能体如何在运行时找到相关能力？ * `runtime`: 工作在哪里执行？ * `skills`: 可复用的任务知识如何打包？ * `roots`: 工具面向的服务器可以看到哪些本地文件系统区域？ * `resources`: 哪些文件、模式、记录或应用对象可以作为模型上下文暴露？ * `connectors`: 本地和远程服务如何变成可调用的工具？ 这种拆分有助于贡献者撰写案例研究和入门项目，而不会假装每一种集成都属于同一种智能体能力。 | 术语 | 读者问题 | 常见错误 | | ------------ | ---------------- | ---------------------------- | | `discovery` | 智能体如何找到新的能力？ | 把搜索或 registry 结果直接当作使用该工具的权限 | | `runtime` | 工作在哪里执行？ | 把所有智能体工作都当作聊天回复 | | `skills` | 可复用的任务知识如何打包？ | 把过时指令藏在一个很长的提示词里 | | `roots` | 哪些文件系统边界在作用范围内？ | 不说明边界，只说“文件访问” | | `resources` | 哪些被选中的对象可以变成上下文？ | 假设每个后端对象都会自动可用 | | `connectors` | 哪些系统可以作为工具被调用？ | 把集成访问等同于使用所有数据的权限 | ## 作用范围说明 包括： * 关于 catalogs、registries 和 trust metadata 的官方 ARD 材料 * 关于 Responses API 工具、文件搜索、远程 MCP 支持和计算环境的 OpenAI 官方来源材料 * 关于需要审批的 connectors 与远程 MCP servers 的当前 OpenAI 官方文档 * 关于 indirect prompt injection、沙箱、scope minimization 与本地智能体信任边界的 OpenAI、Microsoft、Claude Code 与 MCP 官方安全指引 * 关于 roots 和 resources 的官方 MCP 材料 * 关于本地 stdio 服务器、项目/用户作用域以及 MCP resources 的官方 Claude Code 材料 不包括： * 第三方 MCP 服务器列表 * 非官方的提示注入评论 * 不会改变手册本地智能体心理模型的厂商比较 * 生产环境电子邮件或 CRM 集成的实现细节 ## 来源图谱 * [Hugging Face: Agentic Resource Discovery - Let agents search](https://huggingface.co/blog/agentic-resource-discovery-launch): 适用于说明当前 discovery layer 的 framing、为什么 install-first 的 agent wiring 无法扩展，以及 registry 如何让智能体在运行时搜索相关能力。 * [Google Developers: Announcing the Agentic Resource Discovery specification](https://developers.googleblog.com/announcing-the-agentic-resource-discovery-specification/): 适用于解释 catalogs、registries、trust metadata，以及 discovery 如何把能力交回其原生协议。 * [Microsoft: Introducing the Agentic Resource Discovery specification](https://commandline.microsoft.com/agentic-resource-discovery-specification-ard/): 当草稿需要一个清晰的问题陈述，说明为什么随着 agentic resources 增多，手工 wiring 会失效时使用。 * [OpenAI Responses API tools and remote MCP support](https://openai.com/index/new-tools-and-features-in-the-responses-api/): 适用于关于托管工具、远程 MCP 支持、文件搜索和长时间运行后台工作的主张。 * [OpenAI MCP and Connectors guide](https://developers.openai.com/api/docs/guides/tools-connectors-mcp): 当草稿需要审批规则、远程服务器传输细节、tool list 缓存机制，或需要解释受信任 connectors 与第三方 MCP servers 之间的实际边界时使用。 * [OpenAI computer environment for agents](https://openai.com/index/equip-responses-api-computer-environment/): 适用于关于执行环境、持久文件、shell 访问、压缩，以及作为运行时支持的智能体技能的主张。 * [Understanding prompt injections](https://openai.com/safety/prompt-injections/): 当草稿需要引用 OpenAI 当前对第三方指令、分层防御、沙箱以及智能体动作用户确认的通俗 framing 时使用。 * [Defend against indirect prompt injection attacks](https://learn.microsoft.com/en-us/security/zero-trust/sfi/defend-indirect-prompt-injection): 适用于需要引用当前企业级防御栈时：其中明确列出 prompt shields、spotlighting、plan-drift detection、critic agents、tool-chain analysis、information-flow control 和 least privilege。 * [MCP introduction](https://modelcontextprotocol.io/docs/getting-started/intro): 适用于将 MCP 作为 AI 应用与外部系统之间连接层的稳定、高层级说明。 * [MCP roots](https://modelcontextprotocol.io/specification/2025-06-18/client/roots): 当草稿需要解释本地文件系统边界时使用。 * [MCP resources](https://modelcontextprotocol.io/specification/draft/server/resources): 当草稿需要解释由应用控制的上下文表面，例如文件、模式或应用特定对象时使用。 * [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp): 适合作为本地 stdio 服务器、项目作用域 MCP 配置、插件提供的服务器，以及编码智能体工作流中 resources 的实践示例。 * [Claude Code security](https://code.claude.com/docs/en/security): 适用于关于权限检查、MCP server 信任校验，以及处理不可信内容的实践指导。 * [Claude Code sandboxing](https://code.claude.com/docs/en/sandboxing): 适用于关于文件系统与网络隔离如何在 prompt injection 成功时限制损害的主张。 * [MCP security best practices](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices): 当草稿需要讨论本地 MCP server compromise、一键配置时的启动命令确认、scope minimization，以及为什么 `stdio` 或受认证传输很重要时使用。 * [modelcontextprotocol/modelcontextprotocol](https://github.com/modelcontextprotocol/modelcontextprotocol): 适合作为高信号的 MCP 实现与规范仓库，用于检查当前 adoption、issue 流向与 security surface 维护情况。 * [microsoft/BIPIA](https://github.com/microsoft/BIPIA): 当草稿需要一个评估 indirect prompt-injection robustness 的具体 benchmark 仓库示例时使用。 * [promptfoo/promptfoo](https://github.com/promptfoo/promptfoo): 适合作为针对 agents、tools 与 RAG systems 的 red teaming 与 CI 级 prompt-injection 检查的高信号实现仓库。 * [ards-project/ard-spec](https://github.com/ards-project/ard-spec): 适合作为 ARD 的标准草案仓库，用于查看 schemas、conformance artifacts 与 trust-model 表述。 * [huggingface/hf-discover](https://github.com/huggingface/hf-discover): 适合作为具体的 ARD client/server 实现，用于搜索 skills、spaces 与 MCP servers。 ## 综合归纳 最强的本地智能体主干是分层的： 1. 用户或宿主应用选择一个运行边界。 2. discovery 表面帮助智能体找到相关能力。 3. 工具和服务器在该边界内暴露能力。 4. resources 和 roots 描述哪些上下文可以被读取或选择。 5. skills 打包可重复的任务知识。 6. 智能体生成可供审阅的产物或动作。 就手册而言，这比简单说“智能体可以访问文件”更有用。本地访问应始终附带边界来说明：哪些文件、哪个服务器、哪种传输、哪些权限，以及什么产物。 同样的原则也适用于 skills 和 connectors。skill 可以告诉智能体如何执行某项任务，但不应被当作最新证据。connector 可以暴露一个有用的系统，但不应暗示有权读取或操作该系统中的所有对象。 agentic resource discovery 又补上了一个贡献者需要单独命名的边界。discovery 回答的是“有什么可用？”，并不回答“这里允许做什么？”。catalog 或 registry 的结果仍然需要经过 approval、pinning、auth 与 scope review，智能体才应连接或执行。 这次 2026 年 6 月的刷新也提醒我们，一个更稳定的手册术语并不只是 “local agent tooling”，而是 `local agent discovery and execution boundaries`：工作在哪里运行、如何发现新能力、有哪些审批、哪些 roots 或 resources 在作用范围内，以及动作完成后还留下了什么可审阅的表面。 ## 生产就绪提示 当前七日窗口里关于 prompt injection 的 signal 提醒我们：本地智能体应当被描述为 authority system，而不只是 capability system。真正需要回答的不只是“智能体能读什么”，而是“一旦它能调用工具、接触文件或向外发送数据，不可信输入会带着什么 authority 一起流动”。 * 除非经过人工审阅的策略明确说明，否则应把检索到的文件、网页、邮件和 connector 输出都视为不可信内容。 * 要分清 source 和 sink：不可信内容可以为智能体提供信息，但敏感 tool call、credential 使用和对外数据传输应继续放在额外审批、沙箱或两者共同保护之后。 * 连接任何 MCP server 之前都要先做信任校验。对本地 server，应优先采用明确的 scope 选择、完整启动命令审阅，以及 `stdio` 或受认证的传输方式。 * 对发送消息、修改工单、向第三方系统迁移数据等后果明确的动作，应把人工确认保留在写路径中。 * 在称一个本地智能体配置达到 production-ready 之前，应把 prompt injection 和 tool misuse 检查纳入 eval 或 red-team workflow。 ## 执行边界矩阵 当贡献者把不同本地智能体表面并排比较，而不是都笼统当作“tool access”时，这份来源图谱会更容易落地。 | 表面 | 运行位置 | 主要边界信号 | 主要失效模式 | 基线防御 | | ------------------------- | ---------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | 直接本地脚本 | 作为用户机器上的进程运行 | 仓库路径、shell 命令和显式读写范围 | 过宽的 shell authority 会把一条坏指令立刻放大成文件或凭证访问。 | 最小默认权限、显式输入审阅、隔离运行时，以及可审计的输出。 | | 本地 `stdio` MCP server | 作为由客户端启动的本地进程运行 | 启动命令审阅、project scope、`CLAUDE_PROJECT_DIR` 和 `roots/list` | 看似可信的本地 server 也可能执行不透明的启动命令，或越权读取本地文件。 | 完整启动命令审阅、沙箱、受限文件系统访问，以及窄目录范围。 | | 远程 MCP server 或 connector | 运行在远程服务上 | `server_url`、allowed tools、auth scope 和 approval requirements | 过宽 token 或薄弱认证会让不可信内容触发高影响远程动作。 | scope minimization、短时 token、受认证传输、逐动作确认，以及请求日志。 | | ARD 风格 discovery registry | 运行在可搜索的 catalog 或 federated registry 服务上 | catalog provenance、trust metadata、registry URL 和 pinning rules | discovery 结果看起来足够可信，容易让人跳过真正的 scope review，或把智能体路由到错误的能力类型。 | 校验 publisher identity、pin 住选中的 capability、把 discovery 与 execution approval 分离，并记录选用了哪个 registry 结果。 | | 托管计算环境 | 运行在 provider 托管的容器工作区里 | 隔离文件系统、受限网络访问和显式工具输出 | 平台隐藏了传输层，因此 prompt injection 往往会表现成 plan drift、静默数据越界，或让运行时逐渐偏离开发者的本地机器。 | 分层 prompt-injection 防御、tool-chain analysis、人工确认，以及高风险动作的策略级审查。 | ## 在手册中继续展开的位置 * [参考说明](/zh-Hans/contributor-kit/reference-notes)：在起草长期页面前，先把 source-map 与 contributor briefing 这一层讲清楚。 * [协议与互操作性](/zh-Hans/systems/protocols-and-interoperability)：当草稿需要 MCP、A2A、ARD 与远程边界的对比时使用。 * [Agent Runtime Building Blocks](/zh-Hans/patterns/agent-runtime-building-blocks)：当草稿需要一个关于 execution、memory、interface 与 action layers 的可复用拆解时使用。 * [智能体 UI 协议与生成式 UI](/zh-Hans/systems/agent-ui-protocols-and-generative-ui)：当草稿需要把工具权限与 UI 状态分开时使用。 * [Weather MCP Server Starter](/zh-Hans/systems/examples/weather-mcp-server-starter)：适合作为解释 MCP 边界的仓库内可运行示例表面。 * [Codex 工作坊](/zh-Hans/workshops/codex)：当草稿需要从本地设置进入真实仓库级 coding-agent loop 的最短仓库原生路径时使用。 * [2026 年 4 月助手安全升级观察](/zh-Hans/radar/2026-04-assistant-safety-escalation-watch)：当草稿需要把本地 authority boundary 与人工升级、审计路径联系起来时使用。 * [GitHub Issue Guide](/zh-Hans/contributor-kit/github-issue-guide)：当这份说明要落成一个范围清晰的贡献提案或 issue claim 时使用。 ## 案例研究切入点 好的本地智能体案例研究应当让边界可见： * 客户支持邮件智能体：传入消息路径 + 本地政策文档路径 * 编码智能体：仓库根目录 + issue、测试和分支权限 * 基于 registry 的编码智能体：ARD 或 catalog 搜索结果 + 在执行前对远程 MCP 或 skill 的 pinning 决策 * 运维智能体：仪表盘或数据库资源 + 只读查询规则 * 研究智能体：来源文件夹 + 引用产物输出 每个案例都应说明智能体可以读取什么、可以写入什么，以及什么需要人工审阅。 ## 缺口与后续工作 * 一旦 starter code 包含真实邮箱或 Gmail 适配器，扩展客户支持案例研究。 * 增加一个未来的 starter 或案例研究说明，展示 source-aware authority enforcement 或 prompt-injection red teaming 如何嵌入本地智能体工作流。 * 增加一份狭义 walkthrough，说明如何把 indirect prompt injection 发现转成仓库原生的 eval 检查或可认领的 issue 模板。 ## 更新日志 * 2026-06-21：加入 agentic resource discovery 来源，明确 discovery 与 connection 的边界，并把执行边界矩阵扩展到 ARD 风格 registry。 * 2026-06-06：加入当前 OpenAI MCP/connectors 指引，并围绕显式的本地与托管执行边界刷新矩阵。 * 2026-05-27：把较旧的 prompt-injection 来源替换为当前的 OpenAI 与 Microsoft 指引，补上 authority-boundary matrix，并把这份说明连接到相关手册表面。 * 2026-05-17：为本地智能体来源图谱补充了 prompt injection、沙箱、信任边界和 red-teaming 指引。 * 2026-04-24：通过使用指导、术语边界和更清晰的来源到主张映射，提升了该说明对贡献者的可理解性。 * 2026-04-23：新增面向贡献者的本地智能体工具链、skills、roots、resources 和 file-grounded workflows 来源图谱。