跳转到主要内容
需要帮助？
在 Discord 提问提交 GitHub Issue支持指南

​
概述

这份说明汇集了供撰写本地智能体系统内容的贡献者使用的官方来源输入：这些智能体在用户的文件、工具、项目状态和工作流指令附近运行，而不是仅作为远程聊天界面工作。 当草稿需要解释“本地”究竟意味着什么时，可以使用它。真正持久的模式不是某个模型所在的位置，而是以下要素的组合：
  • 执行环境或本地工具边界
  • 可复用的技能或工作流打包
  • 明确的文件系统或文档作用范围
  • 可被选择、搜索、读取或刷新的资源
  • 让边界对用户而言清晰可理解的权限规则

​
如何使用这份说明

这是一张来源图谱，不是一篇完整文章。后续贡献者应使用它来：
  • 在描述智能体之前先定义边界
  • 为所做的主张选择合适的来源
  • 将本地文件、所选资源、技能和连接器区分开来
  • 补充案例研究示例，展示智能体可以读取、写入和审阅什么

​
为什么它很重要

本地智能体相关话题很容易被夸大。一本有用的手册应当区分几个经常混在一起的关注点：
  • runtime: 工作执行在哪里进行？
  • skills: 可复用的任务知识如何打包？
  • roots: 工具面向的服务器可以看到哪些本地文件系统区域？
  • resources: 哪些文件、模式、记录或应用对象可以作为模型上下文暴露？
  • connectors: 本地和远程服务如何变成可调用的工具？
这种拆分有助于贡献者撰写案例研究和入门项目，而不会假装每一种集成都属于同一种智能体能力。
术语读者问题常见错误
runtime工作在哪里执行？把所有智能体工作都当作聊天回复
skills可复用的任务知识如何打包？把过时指令藏在一个很长的提示词里
roots哪些文件系统边界在作用范围内？不说明边界，只说“文件访问”
resources哪些被选中的对象可以变成上下文？假设每个后端对象都会自动可用
connectors哪些系统可以作为工具被调用？把集成访问等同于使用所有数据的权限

​
作用范围说明

包括：
  • 关于 Responses API 工具、文件搜索、远程 MCP 支持和计算环境的 OpenAI 官方来源材料
  • 关于 indirect prompt injection、沙箱、scope minimization 与本地智能体 信任边界的 OpenAI、Microsoft、Claude Code 与 MCP 官方安全指引
  • 关于 roots 和 resources 的官方 MCP 材料
  • 关于本地 stdio 服务器、项目/用户作用域以及 MCP resources 的官方 Claude Code 材料
不包括：
  • 第三方 MCP 服务器列表
  • 非官方的提示注入评论
  • 不会改变手册本地智能体心理模型的厂商比较
  • 生产环境电子邮件或 CRM 集成的实现细节

​
来源图谱

  • OpenAI Responses API tools and remote MCP support: 适用于关于托管工具、远程 MCP 支持、文件搜索和长时间运行后台工作的主张。
  • OpenAI computer environment for agents: 适用于关于执行环境、持久文件、shell 访问、压缩，以及作为运行时支持的智能体技能的主张。
  • Understanding prompt injections: 当草稿需要引用 OpenAI 当前对第三方指令、分层防御、沙箱以及智能体动作用户确认的通俗 framing 时使用。
  • Defend against indirect prompt injection attacks: 适用于需要引用当前企业级防御栈时：其中明确列出 prompt shields、spotlighting、plan-drift detection、critic agents、tool-chain analysis、information-flow control 和 least privilege。
  • MCP introduction: 适用于将 MCP 作为 AI 应用与外部系统之间连接层的稳定、高层级说明。
  • MCP roots: 当草稿需要解释本地文件系统边界时使用。
  • MCP resources: 当草稿需要解释由应用控制的上下文表面，例如文件、模式或应用特定对象时使用。
  • Claude Code MCP documentation: 适合作为本地 stdio 服务器、项目作用域 MCP 配置、插件提供的服务器，以及编码智能体工作流中 resources 的实践示例。
  • Claude Code security: 适用于关于权限检查、MCP server 信任校验，以及处理不可信内容的实践指导。
  • Claude Code sandboxing: 适用于关于文件系统与网络隔离如何在 prompt injection 成功时限制损害的主张。
  • MCP security best practices: 当草稿需要讨论本地 MCP server compromise、一键配置时的启动命令确认、scope minimization，以及为什么 stdio 或受认证传输很重要时使用。
  • modelcontextprotocol/modelcontextprotocol: 适合作为高信号的 MCP 实现与规范仓库，用于检查当前 adoption、issue 流向与 security surface 维护情况。
  • microsoft/BIPIA: 当草稿需要一个评估 indirect prompt-injection robustness 的具体 benchmark 仓库示例时使用。
  • promptfoo/promptfoo: 适合作为针对 agents、tools 与 RAG systems 的 red teaming 与 CI 级 prompt-injection 检查的高信号实现仓库。

​
综合归纳

最强的本地智能体主干是分层的：
  1. 用户或宿主应用选择一个运行边界。
  2. 工具和服务器在该边界内暴露能力。
  3. resources 和 roots 描述哪些上下文可以被读取或选择。
  4. skills 打包可重复的任务知识。
  5. 智能体生成可供审阅的产物或动作。
就手册而言，这比简单说“智能体可以访问文件”更有用。本地访问应始终附带边界来说明：哪些文件、哪个服务器、哪种传输、哪些权限，以及什么产物。 同样的原则也适用于 skills 和 connectors。skill 可以告诉智能体如何执行某项任务，但不应被当作最新证据。connector 可以暴露一个有用的系统，但不应暗示有权读取或操作该系统中的所有对象。

​
生产就绪提示

当前七日窗口里关于 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。

​
Authority Boundary Matrix

当贡献者把不同本地智能体表面并排比较，而不是都笼统当作“tool access”时，这份来源图谱会更容易落地。
表面主要边界问题主要失效模式基线防御
直接本地脚本哪个用户或服务账号在执行命令？过宽的 shell authority 会把一条坏指令立刻放大成文件或凭证访问。最小默认权限、显式输入审阅、隔离运行时，以及可审计的输出。
本地 stdio MCP server哪条启动命令和哪些本地目录在作用范围内？看似可信的本地 server 也可能执行不透明的启动命令，或越权读取本地文件。完整启动命令审阅、沙箱、受限文件系统访问，以及窄目录范围。
远程 MCP server委派了哪些远程 scope、token 和对外动作？过宽 token 或薄弱认证会让不可信内容触发高影响远程动作。scope minimization、短时 token、受认证传输、逐动作确认，以及请求日志。
平台托管工具模型与动作之间有哪些产品层 guardrails？平台隐藏了传输层，因此 prompt injection 往往会表现成 plan drift 或静默数据越界。分层 prompt-injection 防御、tool-chain analysis、人工确认，以及高风险动作的策略级审查。

​
在手册中继续展开的位置

​
案例研究切入点

好的本地智能体案例研究应当让边界可见：
  • 客户支持邮件智能体：传入消息路径 + 本地政策文档路径
  • 编码智能体：仓库根目录 + issue、测试和分支权限
  • 运维智能体：仪表盘或数据库资源 + 只读查询规则
  • 研究智能体：来源文件夹 + 引用产物输出
每个案例都应说明智能体可以读取什么、可以写入什么，以及什么需要人工审阅。

​
缺口与后续工作

  • 一旦 starter code 包含真实邮箱或 Gmail 适配器，扩展客户支持案例研究。
  • 增加一个未来的 starter 或案例研究说明，展示 source-aware authority enforcement 或 prompt-injection red teaming 如何嵌入本地智能体工作流。
  • 增加一份狭义 walkthrough，说明如何把 indirect prompt injection 发现转成仓库原生的 eval 检查或可认领的 issue 模板。

​
更新日志

  • 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 来源图谱。