Skip to content

一个文件读取请求怎样获得一次执行 ​

当远端智能体需要读取工程中的文件或执行命令时,云端认证先确认客户端身份和权限,但连接器不会把云端鉴权直接等同于本机执行权,仍须由本机对精确参数人工放行后再交给容器运行。以下用测试中的中性文件请求,把云端、本机与容器三个阶段的交接串联起来。

真正的难点在于,即使客户端已持有效令牌,也可能提出未预期的路径操作或重复投递同一个网络请求,因此本机批准、账本登记和隔离执行必须按不可颠倒的顺序交接。

Step 1: 身份确认与信封装箱 ​

远端客户端向 /mcp 发送 JSON-RPC 请求后,云端入口先按配置域名和协议版本拦截畸形或超大请求体,再由授权协调器核对单人密码登录取得的令牌与所需作用域(读取文件至少需要 computer:read)。随后,中继对象把调用方身份、授予权限、请求原文和 110 秒截止时间封装进内部信封,通过唯一的设备 WebSocket 发往连接器。

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "read_file",
    "arguments": { "path": "/workspace/canary.txt" }
  }
}

这是脱敏的中性示例;实际挂载的工程目录仍可能含本地敏感文件,批准前应核对实际路径与请求意图。云端并发通道、刷新令牌家族撤销与心跳窗口判据,详见云端网关、OAuth 2.1 与中继交接。

Step 2: 本地二审与未批准入队 ​

连接器收到帧后,先运行本地请求策略(仓库文件:local/request-policy.mjs)中的 validateRequestEnvelope 重新核查截止时间、嵌套深度、作用域和 10 项工具白名单,同时预先核对持久防重放账本,确认该桥接请求 ID 未曾执行过。除了查看环境、查询已有命令与停止命令三项豁免工具外,其余敏感文件与命令调用若尚无匹配批准,即向客户端返回 LOCAL_APPROVAL_REQUIRED,实际操作尚未启动。

待批准记录会把网关源、客户端标识、已授权作用域、方法与完整参数一起规范化计算 SHA-256 摘要(故意排除外层客户端 JSON-RPC ID,从而允许审批后用新的 RPC ID 重试),在核对紧凑 UTF-8 字节数不超过 1,200,000 字节上限后原子落盘。用户在 %USERPROFILE%\.agentdock-bridge 运行 Approve.cmd,即可在批准终端界面(仓库文件:local/approval-cli.mjs)看到经过控制字符与双向排版转义的完整请求参数,输入精确确认口令后生成有效期 5 分钟的一次性批准文件。

Step 3: 同参数重试消费批准并记账 ​

客户端以相同工具和参数再次发起调用时,连接器主流程(仓库文件:local/connector.mjs)按固定顺序完成交接:

请求情形可观察结果源码边界依据
首次请求,尚未在本机确认返回 LOCAL_APPROVAL_REQUIRED,待批准文件落盘批准状态机(仓库文件:local/approvals.mjs)
同一客户端、同参数在 5 分钟内重试先删除批准文件,再写入 24 小时执行账本,随后仅执行一次防重放账本(仓库文件:local/receipts.mjs)
重试时改动路径或开启 network: "outbound"参数摘要失配,拒绝旧批准并生成新的待批记录批准存储(仓库文件:local/approval-store.mjs)
完整待批记录超过 1,200,000 字节上限拒绝入队并返回 APPROVAL_RECORD_TOO_LARGE批准预算测试(仓库文件:test/approval-budget.test.mjs)
重复使用已经登记的桥接请求 ID返回 already_attempted 或冲突拒绝,不重放执行连接器测试(仓库文件:test/connector.test.mjs)

先删除批准文件、再写入持久账本、最后进入运行器的顺序非常关键:即便执行途中发生断线或超 110 秒超时,已消费的批准与已落盘的账本都不会允许同一次请求自动二次运行,但超时也不能自动推定容器内毫无副作用。完整批准预算、控制通道隔离与 Windows DPAPI/ACL 保护,见本地精确批准与防重放账本。

Step 4: 容器执行与清理故障退守 ​

登记完成后,请求进入沙箱运行时(仓库文件:local/sandbox.mjs),通过固定 SHA-256 摘要的开发镜像启动一次性容器(只绑定单一工作区到 /workspace,只读根文件系统、丢弃多余内核权能并默认断网)。文件任务走标准输入交给容器内的文件运行器(仓库文件:container/file-worker.mjs)执行,该运行器内部固定禁用命令执行并逐级核查符号链接、多硬链接、UTF-8 编码与 Windows 自定义 ACL;命令任务则在 5 秒宿主心跳租约监控下由 命令监督入口(仓库文件:container/runner.mjs) 降权为普通开发用户跑起 Bash。

例如,一旦某个任务结束后的容器清理失败(cleanup_confirmed 为 false),连接器立即把全局运行状态置为关闭,拒绝之后所有新的命令和文件操作;与此同时,检查任务归属客户端的控制分支仍保持在关闭拦截之前,因此原客户端依然可以查询或停止自己尚未结束的其余容器任务,只是未确认清理的任务会继续上报未知运行状态,等待人工本机检查 Docker。容器加固参数与文件替换守卫的细节,见容器沙箱与文件安全策略。

Step 5: 局部回归验证与证据界限 ​

在完成依赖安装后的任意开发环境中,可以直接复现批准交接、预算超限和清理故障下的归属控制逻辑(真实 Docker 容器与 Windows ACL 测试会按环境条件自动启用或跳过):

sh
node --test test/connector.test.mjs test/approval-budget.test.mjs test/sandbox-recovery.test.mjs
pnpm run check

上述局部回归分别使用临时状态目录、本地回环 WebSocket 和沙箱受控模拟边界,不能自动替代真实 Windows 宿主 ACL 校验、固定开发镜像内集成回归或公网端到端验收;历史上随安全修复记录在案的真实部署、镜像校验与公网回归快照统一保存于修复与验证快照(仓库文件:SECURITY-FIXES.md)。需要按目录快速找到其他模块或测试文件时,继续浏览代码地图寻找源码与测试入口;要核对每项断言对应的源码依据与排除项,查看源码证据审计与边界。

证据状态:除特别标注外,本页基于当前源码已确认。