For AI agents: the complete documentation index is available at https://scriptedalchemy.github.io/agent-bundle/zh/llms.txt, the full documentation bundle is available at https://scriptedalchemy.github.io/agent-bundle/zh/llms-full.txt, and this page is available as Markdown at https://scriptedalchemy.github.io/agent-bundle/zh/reference/security.md.
跳至主要内容
agent-bundle
  • 简体中文

      • 安全

      下面大多数内容是一种拒绝，而不是一项功能。它们是框架恪守的契约，不是你能用某个标志放宽的默认值。

      提供方凭据

      本包绝不接受、索取、注入或持久化任何模型提供方 API key。

      原生 Claude 与 Codex harness 使用已经安装并已登录的 CLI，并且是在提供方 key 相关的环境变量被移除之后 运行的。evals 配置块中形似凭据的材料会被直接拒绝而不是被忽略：Agent Bundle 复用宿主 CLI 已有的会话， 并且不存在任何从配置中读取 API key 的回退路径。

      每次 Codex 试验都会设置一个临时的 CODEX_HOME，并只把已安装 CLI 那份不透明的 auth.json 复制进去。 你日常的 Codex home、配置与已安装插件状态不会被用作试验状态，也不会被改动。贡献者冒烟命令会移除提供方 API key 与形似凭据的环境取值，并在所选宿主的日常配置、设置或已安装插件状态发生变化时失败。对 Claude 而言，这个范围是 ~/.claude/config.json、settings.json、settings.local.json 与 plugins/， 另外原生契约冒烟还会检查 ~/.claude.json 里用户作用域的 mcpServers 注册。~/.claude.json 的其余 内容是 Claude Code 每次启动都会重写的宿主记账数据（缓存的特性开关、首次启动与机器标识、使用计数、 按项目的会话统计），有意不在守护范围内。

      原生的已认证冒烟测试被排除在默认与日常本地测试运行之外，而运行它们的那个可信自托管 CI 工作流使用既有的 订阅会话，且不使用任何工作流 secret。

      开发服务器

      agent-bundle dev 只绑定 loopback，并且是一个前台开发会话，而不是托管服务。浏览器不是可信输入源： 它绝不提供命令、工作目录、原生模型或凭据，且由浏览器提供的原生模型与凭据会被拒绝。所有操作都只是可信 本地操作。

      前台服务器的浏览器路由，会话引导、变更与项目事件流，带有一道 Origin 守卫：Origin 不是前台 URL 的请求会以 AB8003 被拒绝（不带 Origin 的请求只有作为 Sec-Fetch-Site: same-origin 才能通过）， 因为其他任何 origin，包括另一个 loopback origin，例如在自己的 loopback 端口上运行第三方插件代码的 MCP App 沙箱 iframe，否则都可能对它伪造请求。贡献者 HMR 放行列表 agent-bundle dev --workbench-dev-origin <origin> 是唯一的例外：显式、仅限 loopback（不是裸 loopback http/https origin 的任何取值都会在启动时被拒绝）、默认关闭，因此不带该标志时这道守卫保持 不变。该循环中的 Rsbuild 代理刻意绝不改写 Origin：前台始终看到浏览器真实的 origin，并且只放行被明确 列出的那一个，而不是信任代理转发过来的任何内容。见 贡献者 UI 的 HMR。

      Skill Markdown 中的原始 HTML、JSX/MDX 与 Mermaid 在 Workbench 渲染器中是惰性的。Skill 文档是用于 展示的内容，而不是用于执行的标记。

      agent-bundle serve-app 对单个 MCP App 遵循同一模型：只绑定 loopback、只在一个进程生命期内、只绑定一个 服务器。它的 /api/mcp/... 路由要求一个只有被提供的文档持有的每次启动令牌，外加同源与 loopback Host 检查；App 文档运行在框架沙箱内的第二个 loopback origin 上，并且每一个 App 动作仍与 Workbench 一样经过同一 个同意授权（--allow 代操作者预先批准指定能力）。它是本地预览宿主，不是部署目标。

      App 文档内的 agent-bundle/app 客户端也不会信任任意 postMessage 发送者。 每一帧入站消息都必须来自完全相同的 configured parent（event.source === parent），并通过严格的 JSON-RPC 校验。省略 targetOrigin 时，客户端遵循 MCP Apps transport contract：每一帧出站消息都以 '*' 发送到该 parent，event.origin 不参与入站消息认证。完全相同的 parent WindowProxy 身份是承担 安全性的认证控制。

      能够给出可信 origin 的宿主可以传入 targetOrigin。它必须是精确的 http: 或 https: origin； '*'、"null"、自定义 scheme 与非 origin 字符串都会被拒绝。此时客户端会对每一帧出站消息使用该精确 origin，并要求每一帧入站消息的 event.origin 与之匹配。Workbench 与 serve-app 在其独立的 loopback HTTP sandbox proxy 中继续保留这道更强的宿主侧边界：proxy 会先校验 source 与 origin，再 relay 到 MCP。 rebind() 与 dispose() 仍会拒绝 pending work，并使旧 connection generation 失效。

      这条桥接以宿主 relay 为安全边界：App 客户端只与预期 parent 通信；Workbench、serve-app 或嵌入式 MCP 宿主负责把允许的请求转发到所绑定的那一个服务器，并继续执行各自的认证、能力与同意策略。App 不会绕过 relay 直接访问前台路由或 MCP 后端，relay 也不会把另一个 App、服务器或浏览器 origin 的权限合并进来。 取消也遵循同一边界：框架宿主桥只处理 App 自己发起且仍在进行中的 request 所对应的 notifications/cancelled，中止这一项操作并拒绝其仍待决定的同意挑战，因此取消既不能绕过同意，也不能 触碰不是该 App 发起的 request。

      Agent API

      Agent API 默认关闭。启用时，它是挂载在同一个 loopback 前台服务器 /mcp 路径上、经过认证的 Streamable HTTP MCP 端点，拥有恰好十三个固定且有序的工具。

      • 若在没有 AGENT_BUNDLE_AGENT_API_TOKEN 的情况下启用该端点，启动会在开始服务之前失败。
      • 这个固定 token 只被读取一次，绝不会被记录日志、持久化或返回。
      • 必须使用标准的 Authorization: Bearer 认证。
      • 客户端可以省略 Origin；一旦提供，它必须与前台 URL 完全一致。
      • 当该端点被禁用时，它是不存在的，而不只是未授权。

      操作细节见开发者 Workbench。

      安装

      安装一个包绝不会改动宿主的插件状态：任何 npm 生命周期都不会执行安装。独立的 install.mjs 会复制到 ~/.cursor/plugins/local/<name> 且不覆盖冲突内容，对内容相同的情况是幂等的，会拒绝版本或内容冲突， 绝不调用 sudo，也绝不修改 PATH。

      agent-bundle doctor 在构造上就是只读的。它只按目录条目与文件系统元数据清点持久状态，绝不打开数据 库，并且绝不修复任何东西。

      产物完整性

      对于被分发出去的捆绑包，内容寻址就是信任锚。每个输出文件都在 agent-bundle.manifest.json 中携带一份 SHA-256，因此被修改过的产物会校验失败，而不是被悄悄装上；当源码、已构建产物、已安装产物与运行中进程的 版本不一致时，host-install 证明级别会以失败告终。

      路径包含性在两个方向上都被强制：逃逸出部署树的声明式 logo（AB6025）、解析到 Cursor 捆绑包之外的符号 链接（AB6028）、符号链接逃逸出 ~/.cursor/plugins/local 的已安装本地插件（AB7320）、离开项目根目录 的 eval runsDir，以及会穿出自身状态根目录的 MCP 服务器名，全都会被拒绝。createProjectContext 与项目 准备在悬空或循环符号链接走出项目根、或形成环（ELOOP）时同样失败关闭；项目相对身份若不是可重定位的 POSIX 路径也会被拒绝。POSIX 文件名里的反斜杠会被拒绝，而不会被改写成斜杠分隔路径，因此不会与另一文件 碰撞，也不会进入 agent-bundle.manifest.json。

      未作出的声明

      本包不发布示例 RSC provider，也不发布宿主凭据。原生 Claude 与 Codex 评测 harness（runClaudeTrial、 runCodexEvalTrial、--harness claude|codex）驱动的是你已经安装并登录的 CLI，自身不携带任何凭据。 打包进 Workbench 的第三方材料，其声明随已发布的包一同交付。

      各证据表面不能证明什么，见已知限制。