这应该是本系列里最值得细读的一篇。前面几讲拆了入口路由、任务循环、会话管理但都是单模块的逐行解读。而文件、命令、审批、沙箱这四块是 DeepSeek Harness 里耦合最紧、最容易把人绕晕的地方。它们各自的代码单拎出来都不难难的是“一条命令从用户敲下回车到沙箱里真正执行中间到底经过了哪些关卡每个模块分别在什么时候插手、什么时候放手”。这期就把整条链路捋清楚顺便把我在源码里看到的一些值得注意的细节分享出来。1. 整体架构一条命令从输入到执行的完整链路在真正读这四个模块之前得先在脑子里搭一张全局图。DeepSeek Harness 不是把“能执行命令”这件事交给某一个模块而是拆成四段接力文件负责准备环境、命令负责理解意图、审批负责判断风险、沙箱负责隔离执行。每个模块都有明确的边界但也正因为边界清晰协作时的时序和状态传递就成了关键。1.1 四个模块各自的职责边界先给这四个模块画个像方便后面看代码时对照文件模块FS Manager管的是“沙箱里能看到什么”。它负责把用户工作目录的内容同步进沙箱再把沙箱里产生的结果同步出来。它还管着哪些路径可读、哪些路径可写、哪些路径干脆不可见。命令模块Command Runner管的是“这条命令怎么执行”。它负责解析用户输入的命令行做基础校验把命令发送给沙箱里的执行器然后接管输出流和退出码。它是用户意图和沙箱执行之间的翻译官。审批模块Approval Gate管的是“这条命令允不允许执行”。它根据命令的风险等级、用户的历史行为、当前会话的状态决定是直接放行、自动拒绝、还是弹给用户人工确认。沙箱模块Sandbox Runtime管的是“命令在哪里执行”。它负责启动隔离环境、配置网络、挂载文件系统、执行命令、回收资源。它是整个链条里最底层的执行底座。1.2 调用链路与关键事件流看源码时我一开始犯了个错误想按调用顺序从上往下捋。结果发现这四块根本不是简单的“A调用B、B调用C”的线性关系而更像是一个事件驱动的协作网络。核心链路大致是这样的用户输入命令 ↓ 命令模块解析生成 CommandRequest ↓ 文件模块检查命令涉及的文件路径准备沙箱工作目录 ↓ 审批模块评估命令风险决定放行/拒绝/人工确认 ↓ 沙箱模块启动或复用隔离环境 ↓ 沙箱执行命令流式回传输出 ↓ 文件模块将结果文件同步回宿主机 ↓ 命令模块汇总退出码结束一次请求这里有一个很多人容易忽略的重点审批不一定要在沙箱启动之前完成。源码里做了优化——如果当前会话已经有运行中的沙箱审批会和沙箱启动并行进行。因为审批要等用户操作延迟不可控而沙箱启动是纯机器操作时间基本固定两者并行能省下不少等待时间。这种细节如果不看源码光靠“调用链”思路是理解不了的。1.3 为什么需要这种分层设计有读者可能会想一个执行命令的功能搞四个模块是不是过度设计了我起初也有这个疑问但看完代码后理解了这样的拆分不是“为了架构而架构”而是每个模块都对应一个独立的变化维度文件系统同步的策略会变同步哪些目录、用增量还是全量、要不要走压缩通道。命令解析的规则会变不同平台的路径规则、参数通配符的处理方式。审批策略一定会变每个人对“危险命令”的认定标准都不同产品上还需要支持自定义规则。沙箱技术栈更会变可能从 Docker 切到 Firecracker或者换内核运行时。如果这些逻辑写在一个模块里任何一处变动都要牵动全局。拆开之后只要接口稳定单模块替换不影响其他部分。这个思路本身我认为比四个模块的具体实现更有借鉴价值。2. 文件模块沙箱内外如何安全交换数据文件模块是所有协作的基础——命令要跑得先有文件结果要拿回来也得靠文件同步。这个模块的设计重点是怎么在保证隔离的前提下让数据在宿主机和沙箱之间顺畅流动。2.1 只读镜像与可写覆盖层的设计沙箱里的文件系统不是直接把宿主机的目录挂进去那么简单的。源码里采用的是“只读基座 可写覆盖层”的模式跟 Docker 的 overlayfs 思路一致只是实现上更轻量。具体来说沙箱的根文件系统是一个只读镜像里面是基础的运行环境工具链、运行时库、常用命令。而工作目录是一个单独的可写层挂在固定的路径下。这样做有两个直接好处安全即使沙箱里的命令跑出问题把系统文件搞坏了也只影响可写层。重启一个沙箱就是全新状态不需要重新拉镜像镜像只读且已被宿主机校验过。性能多个沙箱可以共享同一份只读镜像只有可写层是每个沙箱独享的。内存和磁盘开销都能控制得很低。我在代码里看到一个关键参数叫FS_ROOT它指向只读镜像的挂载点。初始化沙箱时会先只读挂载这个根再在指定路径下建一个临时目录作为可写层。这个可写层在你主动销毁沙箱或者会话超时回收时会被直接删掉不需要做额外的清理。2.2 文件同步机制单向、双向与增量传输文件同步是我花时间最长的一个模块因为它要处理的情况太多了。源码里其实支持三种模式分别对应不同场景同步进沙箱宿主机 → 沙箱在命令执行前把用户当前工作目录里的必要文件传进去。简单做法是直接打包传整个目录但代码里做了增量处理——只传自上次同步以来有变动的文件判断依据是mtime size的组合哈希。同步出沙箱沙箱 → 宿主机命令执行完毕后把沙箱内工作目录中新增或修改的文件传回宿主机。这里有个很挫但很有效的策略先传全部文件再用rsync --checksum的方式做比对覆盖。实时双向同步这个只在特定模式下启用比如用户开启了交互式开发模式。它走的是文件系统事件监听fsnotify 捕获到变更后触发同步而不是轮询。这里我要特别提醒一个容易踩的坑同步方向搞反了。我一开始理解成“宿主机是主、沙箱是从”所有改动都以宿主机为准。但在实际的项目里AI 生成的代码经常是在沙箱内修改的所以沙箱内的文件版本可能比宿主机新。如果同步策略做成单向覆盖就会把沙箱里刚生成的结果冲掉。源码里对同步方向的判断逻辑写得很清楚命令执行前以宿主机为准命令执行后以沙箱为准。这个“谁写算谁”的规则贯穿在同步实现里。2.3 文件访问的权限控制与路径隔离文件模块的另一项重要职责是判断沙箱里的命令能访问哪些路径。这部分虽然看起来跟“文件管理”关系不大但它是整个权限模型的地基。FilePolicy这个类管着这件事。初始化时它会读三张表只读路径白名单、可写路径白名单、完全隐藏路径黑名单。执行命令前Command Runner会带着命令里出现的路径去问 FilePolicy 做校验如果访问了黑名单里的路径命令会在执行前就被拦下来。让我印象很深的一个细节是路径归一化的处理。代码里不是简单地做字符串前缀匹配而是先做filepath.Clean、filepath.Abs、再解析软链接filepath.EvalSymlinks最后才跟策略表比对。一开始我觉得这是多此一举直到自己写了一个 demo 试试——随便加一个../就能绕过一个字符串前缀检查。在权限判断里不做路径归一化等于没做。这个细节值得任何做安全相关功能的同学记在小本子上。2.4 实操心得处理大文件与并发读写冲突文件同步这块我在实际调试中碰到过一个典型的性能问题工作目录里放了一个很大的node_modules或.venv每次命令执行前都要同步导致一次简单的“查看文件”操作都要等十几秒。后来我翻源码发现文件同步逻辑里其实预留了忽略规则接口只是默认配置里只忽略了.git和.hg。我在自己的配置里把这几个目录加了进去exclude: - .git - .hg - .svn - node_modules - .venv - __pycache__加完之后同步耗时的变化是肉眼可见的级别。不要相信“默认配置就是最优配置”尤其是文件同步这类和具体项目强相关的功能默认配置一定是保守的、普适的不一定适合你的使用场景。关于并发读写冲突还要提醒一件事如果同时启动两个沙箱并对同一个文件做了修改最后写回宿主机时后完成的那个会覆盖先完成的那个。源码里目前没有做文件级别的冲突合并它采用的是“基于目录的同步快照”每个沙箱在启动时都会记录当时的文件状态快照写回时以快照为基准做增量更新。这个机制对你的数据安全其实是够用的——它保证的是“不丢失上次同步后产生的文件”但不保证“两个沙箱改同一个文件不丢失一份”。3. 命令模块执行、拦截与超时控制命令模块是整个链路的入口和出口——它接收用户的原始输入经过解析、校验后发送给沙箱执行再回收执行结果。这部分对应到源码里的CommandRunner和CommandRequest。3.1 命令解析与白名单策略命令模块首先要回答的问题是“用户输入的这一行文本到底是一条什么命令”源码里没有直接把它丢给 shell 去执行而是先做了一层结构化解构。CommandParser会把输入拆成命令名、参数列表、环境变量前缀、重定向目标。这一步不是简单的空格分割而是要正确处理引号、转义符、管道符号。作者用了shellwords这个库来解析而不是自己写正则——这个选型很关键因为 shell 的转义规则极其复杂自己写解析器很容易在边缘 case 上翻车。解析完成后命令模块会拿命令名去查一张白名单。这张白名单不是说只有白名单里的命令才能执行而是用来做风险预分级的。比如ls、cat、grep这类命令被标记为“只读安全”而rm、curl、eval这类被标记为“高风险动作”。这个分级结果会作为参数传给审批模块它决定这条命令是走自动放行还是人工审批。这里有一个很值得学习的细节分级不是只看命令名还会看参数。同样一条bash命令bash --version是只读安全的而bash -c rm -rf /就是极高风险。源码里对常见的危险模式和参数组合做了特征匹配命中就直接升级风险等级。我最初以为这是用复杂的 AI 模型做的结果一看实现——是一组精心维护的模式匹配规则简单但有效。3.2 拦截规则的实现思路拦截规则在代码里叫BlockRule。每条规则有两个核心组成部分一个匹配模式一个拦截动作。匹配模式可以是命令名的前缀匹配、参数的包含匹配、甚至是指定路径的访问尝试。拦截动作只有三种拒绝执行、标记人工确认、仅记录日志。给我启发最大的是rm命令的拦截规则实现。它对rm -rf这个组合做了单独的、严格的限制并且会解析rm后面的路径参数如果解析结果包含根目录/或者家目录~就会触发高风险标记。但只针对-rf组合单独的rm file.txt不会触发任何拦截。此外命令模块还处理了一个开发中经常遇到的问题别名和 PATH 污染。如果沙箱里装了某些工具它可能自带一个rm的 alias指向一个更危险的命令。源码里的解决方法是使用command -v cmd查到的绝对路径来做规则匹配而不是直接匹配字符串。这样rm就不会被 alias 影响拦截规则始终基于真实的可执行文件。3.3 超时、资源限制与日志采集命令执行时最怕的就是“挂死”。源码里对超时的处理非常保守——每条命令都有默认超时时间我记得是 120 秒超时后主动杀掉进程并返回一个超时错误码。超时实现用的不是简单的time.Aftercommand.Process.Kill()而是考虑到了进程组的问题。因为 shell 命令经常派生子进程管道、后台任务如果只杀主进程子进程会变成孤儿进程继续跑把系统资源吃光。原理上是给整个命令的进程组单独建一个进程会话Setpgid超时的时候直接杀掉整个进程组。这个细节的处理方式值得写进你自己的命令行工具里。日志采集这块标准输出和标准错误是分开处理的。源码里有OutputSink这个抽象它是多路广播的——一路写给会话的日志文件一路写给交互终端的实时输出流还有一路给到事件系统用于后续的文件同步触发判断。多路输出的好处很明显用户能实时看到输出同时日志也被完整记录下来而且文件同步模块还能监听输出的文件名来做智能触发。3.4 常见问题命令挂死与僵尸进程处理即使有了超时机制我还是在实际使用中遇到过命令挂死的情况最典型的是执行一个交互式命令比如vim或者top。命令模块解析后没有检测出它需要 TTY执行时也没有给伪终端导致命令直接在非交互模式下挂起。源码里对这个问题的方法比较聪明它判断命令名是否是“已知交互式程序列表”中的一员vim、top、htop、python REPL 等如果是就自动为它分配一个伪终端PTY并且把用户的输入流接入到 PTY 的 master 端。这让vim这类命令能正常工作。另一个跟僵尸进程相关的细节是命令模块在杀掉超时进程后还要等待(wait())进程结束回收退出码防止它变成僵尸进程。即使超时了也要等到Wait()返回后才会把执行结果返回给上层。杀进程和回收进程是两件事中间隔着一个异步等待的过程。这个细节对我来说是这次源码阅读里比较大的一个收获。4. 审批模块风险分级与状态机设计审批模块的价值不在于“拒绝危险命令”而在于“在安全与效率之间找到平衡点”。如果每条命令都要人工确认体验会非常糟糕但如果直接放行所有命令沙箱的安全性就无从谈起。4.1 审批流程的状态机审批状态机是四个模块里代码结构最清晰的。它定义了这几个状态INITIATED: 审批请求已创建等待决策。AUTO_APPROVED: 系统根据策略自动放行。AUTO_DENIED: 系统根据策略自动拒绝。PENDING_HUMAN: 已被升级到人工审批等待用户确认。HUMAN_APPROVED: 人工审批通过命令可以执行。HUMAN_DENIED: 人工审批拒绝命令不执行。TIMEOUT: 审批请求超时默认按拒绝处理。CANCELLED: 审批请求被取消比如用户主动撤销了命令。这些状态的定义保证了整个审批过程是确定性的——不管发生什么情况最终都会落到一个终态。状态转移的逻辑集中在一个approve()方法里核心逻辑用伪代码看就是这样def evaluate(request): if request.is_cancelled(): return State.CANCELLED risk request.risk_level if risk auto_approve_threshold: return State.AUTO_APPROVED if risk auto_deny_threshold: return State.AUTO_DENIED # 进入人工审批 human_result await request.ask_human(timeoutapproval_timeout) if human_result is None: return State.TIMEOUT return State.HUMAN_APPROVED if human_result else State.HUMAN_DENIED这里有一个细节特别值得注意ask_human函数不是简单的同步等待而是注册了一个“如果超时则自动拒绝”的定时器。审批超时的默认策略是拒绝而不是通过。这是一个安全优先的设计选择宁可让用户重新执行一次命令也不能让高危命令在无人确认的情况下跑了。4.2 风险分级与自动审批策略风险分级是审批模块的核心。源码里用一个RiskLevel枚举来描述风险等级一共有四档风险等级典型场景默认策略SAFE只读操作ls、pwd、cat自动放行LOW修改文件但不影响系统自动放行带审计日志MEDIUM涉及网络、可执行文件投递人工确认HIGH删除目录、写入系统路径、拉取并执行远程脚本人工确认 二次确认这个分级不是拍脑袋定的。我在代码里看到它跟命令模块的解析结果是联动的——命令模块把解析出的命令名、参数、涉及的路径传给审批模块审批模块再根据规则库计算风险等级。两级模块通过一个数据结构对接而不是相互调用函数这样设计的好处是如果你需要支持新的命令类型只需要在解析层增加规则审批层不用改动。关于自动审批源码里的策略是“白名单 黑名单 用户自定义规则”三层。默认情况下只读命令自动放行但如果你曾经在这个会话里执行过rm -rf后续所有rm命令都会被要求人工确认。4.3 用户交互与超时回退人工审批的交互设计直接影响使用体验。源码里用户交互的通道是通过消息协议对接终端 UI 的——在非交互模式下它会自动降级为“等待命令行确认”。我实际体验中的感受是审批的超时时间是一个需要根据使用场景调优的参数。默认值 60 秒对我这种经常同时开多个任务的场景来说太短了我在配置里改成了 300 秒。这个参数在配置文件的approval.timeout字段下。如果你是跑批处理任务并且希望尽量不被打断可以考虑调大它但要注意超时时间越长高危命令的潜在风险窗口就越大。4.4 常见问题审批卡死与重复触发审批模块最常见的问题是“审批一直没有弹出来”。我排查了很久才发现根因审批的事件消息发到了 UI 前端但前端的弹层组件在沙箱全屏模式下会挡住底层 UI导致审批框渲染不出来。源码里对这个问题有一个比较巧妙的处理审批请求除了会推送给 UI 事件流之外还监听了一个 “UI 通道就绪” 的信号。如果这个信号超时未到审批模块会退回到终端渲染模式——直接在终端里打印一条高亮的确认请求等待用户输入y/n。另一个重复触发的问题出现在“同一个会话里的连续命令”。如果前一条命令还在等审批用户又发了新命令新命令不会进入审批队列而是直接返回一个“已有审批在进行中”的提示。这是刻意设计的——避免用户在修改审批规则时多条高危命令同时涌入造成混乱。5. 沙箱模块轻量级虚拟化与生命周期管理沙箱是整个体系的“底座”也是保证安全边界的关键。审批模块发出的“执行许可”最终要落到沙箱模块命令模块也要依赖沙箱模块才能真正执行命令。5.1 运行时选型为什么用轻量级虚拟机代码里默认的沙箱运行时是 Firecracker 或类似内核虚拟化技术驱动的轻量级 VM而不是简单起一个 Docker 容器。两者的核心区别是Firecracker 这类轻量级 VM 有自己的内核跟宿主机是硬隔离。即使沙箱里的进程拿到 root 权限它也只能破坏自己的虚拟机影响不到宿主机。Docker 容器共享宿主机内核隔离边界靠 namespace / cgroup / seccomp 维持安全性比 VM 弱一个量级。DeepSeek Harness 的场景是执行 AI 生成的代码这些命令很可能是不受信任的。在这种威胁模型下安全边界必须放在内核级别。所以选型用了轻量级 VM而不是 Docker 容器。但轻量级 VM 也付出了一些代价启动时间比 Docker 容器长。代码里对沙箱启动做了优化——沙箱是复用池化的而不是每条命令都新建一个。启动的几个沙箱空闲着等着有新任务进来直接挂载工作目录用。资源占用更重一个沙箱默认吃 2 CPU 2GB 内存。如果你的机器配置不高开多个沙箱确实会有点吃力。5.2 沙箱启动与销毁的细节沙箱生命周期的入口在SandboxPool这个类里。它的工作流程是根据配置的池大小预启动若干沙箱实例。接到任务后从空闲队列取出一个沙箱把工作目录挂载进去。在沙箱内执行命令完成后卸载工作目录把沙箱放回空闲队列。如果有沙箱崩溃或者空闲超时重新创建。这个池化思路本身不复杂但有几个细节值得注意挂载点隔离沙箱并发执行时两个沙箱的工作目录是互相隔离的。即使两个沙箱跑在同一台机器上它们之间的文件系统也互不可见。网络策略沙箱的默认网络策略是“出网需审批”。命令模块会把网络访问请求转给审批模块处理。我试过在沙箱里直接pip install第一次会弹审批同意之后后面的命令就正常放行了。销毁回收空闲超过一定时间默认 30 分钟的沙箱会被自动销毁释放资源。如果你开着htop看到几个空闲进程不用惊讶那是沙箱在看门狗的超时检查。沙箱崩溃处理是另一个容易出问题的地方。源码里做了一个崩溃自愈机制如果沙箱在执行命令过程中崩溃了命令模块会收到一个SandboxCrashError自动重启一个新沙箱并重新执行一次同类命令。不过这里要小心这条命令不会重新经过审批模块因为审批在崩溃之前已经完成了。如果你希望更严格的安全控制可以关掉这个自愈重试。5.3 网络隔离与资源配额沙箱默认工作在 NAT 网络模式下只有出网权限不会被宿主机直接访问到。如果需要让宿主机访问沙箱内启动的服务比如在沙箱里跑了一个 Web 应用需要显式开启端口转发。我本地测试时发现端口转发配置在沙箱创建时固定不支持运行期修改。这意味着如果你想在沙箱里启动一个随机端口的服务然后让宿主机访问它会有点麻烦。不过好在这个限制有明确的报错不会让你盲目排查。资源配额在代码里是这样配置的sandbox: cpu: 2 memory_mb: 2048 disk_mb: 4096CPU 和内存是硬限制超过之后沙箱里的进程会被强制杀掉。磁盘配额走的是 overlayfs 的大小限制写超出配额会报Disk quota exceeded。这三个参数是沙箱稳定性的底线——如果你跑的构建任务经常被 OOM 杀死确认一下是不是配的 2GB 内存不够用。5.4 实操心得沙箱冷启动优化沙箱的冷启动时间是我在使用中最关注的一个指标。源码里有两处优化让我印象深刻第一镜像的预拉取。在 Harness 启动时镜像就已经开始后台拉取了不会等到第一次需要沙箱时才去下载。这样第一次命令执行可能不用等网络下载但前提是你配置了预拉取的镜像列表。第二内核页缓存的共享。因为多个沙箱复用同一个只读根这些镜像文件会在宿主机内存中做缓存后启动的沙箱就不需要重新从磁盘读镜像了。如果你的磁盘是机械硬盘这个优化的感知会非常明显。如果你对启动时间特别敏感还有一个取巧的办法在配置里把沙箱池的最小空闲数量提高比如min_idle: 2让更多沙箱常驻空闲。代价是更多的驻留内存占用。这本质上是一个“冷启动时间”和“内存占用”的取舍直接看你更在意哪个资源了。6. 四模块协作的完整拆解从请求到执行的时序与状态传递前面几节分别讲了四个模块的职责和内部机制这一节把四者串起来按照一次完整的请求一步步看它们是怎么协作的。6.1 一次命令请求的完整时序假设用户在交互界面输入了这样一条命令curl -fsSL https://sh.example.com/install.sh | sh这条命令在四个模块之间是这样流转的命令模块接管CommandRunner 接收到原始字符串调用 Shellwords 解析。命令名curl参数-fsSL https://sh.example.com/install.sh管道符号被识别为命令组合。解析完成后命令模块把它包装成CommandRequest这个对象里包含解析结果、命令文本、请求 ID。文件模块介入CommandRunner 把 CommandRequest 发给文件模块的PathResolver做路径检查。这里检测到命令本身没有访问任何本地文件路径但sh会执行从网络下载的脚本——这属于“动态文件投递”文件模块将这条命令标记为“涉及不可信内容执行”并在请求里附加一个requires_network标志。审批模块决策CommandRequest 带着命令模块的解析结果和文件模块的附加标记进入审批模块。审批模块计算风险等级curl 从网络下载 管道给 sh 执行 高危HIGH。风险等级高于自动放行阈值审批模块进入人工确认模式等待用户确认。沙箱模块执行用户同意后命令模块从沙箱池中取一个空闲沙箱把工作目录挂载进去然后把命令发送给沙箱内的执行代理。沙箱执行完后退出码和输出流回传。文件模块收尾命令执行完毕后文件模块做一次“以沙箱为准”的同步。如果沙箱里产生了新文件比如脚本下载了一个工具包它会把这个目录同步回宿主机。命令模块汇总命令模块把退出码、输出流、执行时间、文件变更记录汇总成一个CommandResult交给上层。一次请求到此结束。这个链路里有几个值得注意的设计考量文件模块和审批模块都参与了风险判断但判断的角度不同。文件模块偏重“数据流向的安全”审批模块偏重“命令本身的风险”。沙箱在选择的时候并不关心命令内容它只接受“执行这个命令”的指令。这种“无状态”设计大大简化了沙箱模块的复杂度。6.2 模块间传递的关键数据结构模块间的数据结构设计对协作清晰度影响很大。代码里核心的几个数据结构是class CommandContext: id: str command: str parsed: ParsedCommand working_dir: str env: dict class ApprovalContext: command_id: str risk_level: RiskLevel reason: str actor: str class SandboxRequest: command_id: str context: CommandContext sync_from_host: SyncQuery sync_to_host: bool这三个数据结构贯穿了整条链路CommandContext是命令模块的输出ApprovalContext是审批模块的输入/输出SandboxRequest则是传给沙箱模块的“执行委托书”。我在读代码时注意到CommandContext在传给沙箱模块之前会被“瘦身”——去掉与执行无关的信息比如解析时的中间状态只保留执行必需字段。这既是出于效率考虑减小序列化开销也减少了沙箱内代码的信息暴露面。有助于减少模块间耦合的设计哪怕是信息传递时的删减都值得借鉴。6.3 错误处理与异常恢复一次请求可能出现的异常情况不少让我按阶段列举一下命令解析失败原始输入不符合 shell 语法。这直接返回给用户一个解析错误不进入后续流程。文件同步失败网络断了或者磁盘写满。这是最高优先级的错误——因为它可能导致数据丢失。源码里的策略是“命令不执行直接返回错误”不让命令在一个文件系统不完整的环境下运行。审批超时默认返回“审批未在时限内完成”按拒绝处理。沙箱崩溃重启一个新沙箱重新执行一次命令。沙箱内命令异常退出退出码非零。这不是系统错误命令模块会正常返回给用户由用户判断是否需要处理。在处理这些错误时代码遵循一个原则不掩盖错误但也要提供恢复路径。错误信息会通过结构化的ErrorType字段传给上层方便 UI 层根据不同类型渲染不同的恢复按钮。7. 常见问题与排查技巧实录这部分集中整理我在使用和二次开发中遇到的问题有些是从源码里读出来的有些是自己在调试时踩过的坑。7.1 高频问题速查表现象可能原因排查思路命令执行前卡住几十秒文件同步耗时过久检查工作目录是否有大型依赖目录配置 exclude 规则命令执行时报“无法访问路径”路径不在权限白名单查看 FilePolicy 配置确认路径是否覆盖高危命令没弹审批直接跑没有配置审批规则检查 approval.rules 配置确认 risk_threshold 是否过高沙箱内命令偶发超时沙箱资源耗尽查看沙箱 CPU/内存配额适当调高多个沙箱同步文件互相覆盖相同工作目录被多处挂载避免同一工作目录同时挂载多个活跃沙箱审批弹窗不出来UI 与审批服务消息通道断开查看审批事件流是否正常确认是否触发终端回退模式命令执行后结果丢失文件同步方向配置错误确认同步策略是“执行后以沙箱为准”7.2 调试沙箱崩溃的实战方法沙箱崩溃这个问题排查起来最费劲因为崩溃后能拿到的现场很少。我自己摸索出了几个有效的方法第一步查内核日志。如果沙箱是因为内核 panic 崩溃的宿主机日志里会有痕迹。dmesg -T | grep -i “kernel panic”是一个快速定位入口。第二步看沙箱退出码。源码里对不同崩溃原因定义了不同退出码128signal 表示被信号杀死139 是段错误137 是 OOM 杀死。从退出码能初步判断方向。第三步复现现场。如果崩溃是稳定复现的可以通过打开debug日志把沙箱启动的完整过程打出来。我建议在本地复现时加一层strace抓沙箱执行命令时的系统调用基本能定位到具体是哪一步出的问题。7.3 性能与稳定性的平衡经验最后分享一些我在调优过程中的经验。沙箱的资源配额不是越大越好——配额越大单机可承载的沙箱数量越少并发能力就会下降。我现在的经验值是普通文件操作、构建任务2 CPU 2GB 内存是起步线不够再加。需要跑 npm install、Gradle 等重型构建任务至少 4 CPU 4GB 内存。数据库类任务预留足够的内存给缓冲池内存配额量到 6GB 比较稳妥。另外沙箱池的大小建议按“峰值并发需求 1”来配置。多留一个空闲沙箱能显著降低高并发场景下的排队等待时间。同时要配合空闲超时回收避免沙箱长期驻留吃资源。还有一个非常实用的小技巧——如果你的 AI 编码工具在工作时总感觉“越用越卡”很可能就是沙箱池的自动扩容逻辑不够给力。我建议在配置里观察一下沙箱池的idle数量和waiting数量如果waiting经常大于 0就说明池容量不够可以适当上调。8. 写在最后的实践建议如果要给这次源码阅读画个句号我最想说的是这个系统的协作设计比任何单个模块的代码都更值得借鉴。文件、命令、审批、沙箱各自的实现都是见过很多次的设计模式但把它们组合在一起、让它们协同工作时才真正体现出架构的功力。回到实际使用我给同样在折腾这类 AI 编码助手源码的读者三条建议第一改造之前先把日志打开。我最初阅读时最大的失误是只看了代码没看运行日志。日志里有完整的请求流转记录每一步的耗时一目了然。通过这些日志你能很快判断瓶颈在哪、哪个模块拖慢了整条链路。第二修改默认配置前先做一次最小实验。比如你想调整审批超时时间先在测试环境把超时调成 10 秒试试效果再上线到日常用的配置里。这类系统牵一发动全身稳妥一点不亏。第三理解“安全”与“效率”的此消彼长。审批越严格安全性越高但中断频率也越高。你需要在配置里找到一个适合自己的平衡点对我来说这个平衡点是“只读命令自动放行写操作人工确认高危命令直接拒绝”。你可以按自己的使用场景摸索出一套最顺手的策略。最后分享一个小技巧如果你使用 Harness 时发现命令复现跟不上你的操作速度可以去检查一下文件同步的exclude规则。我把自己工作目录里的node_modules和.venv排除掉之后整个响应速度有明显提升。这不是什么高深的技巧但恰恰是这类实践里最实在的收获。 
长河君 · 2026/9/12 19:23:40 · 阅读 1.2k DeepSeek Harness核心链路拆解：文件、命令、审批与沙箱如何协作
这应该是本系列里最值得细读的一篇。前面几讲拆了入口路由、任务循环、会话管理但都是单模块的逐行解读。而文件、命令、审批、沙箱这四块是 DeepSeek Harness 里耦合最紧、最容易把人绕晕的地方。它们各自的代码单拎出来都不难难的是“一条命令从用户敲下回车到沙箱里真正执行中间到底经过了哪些关卡每个模块分别在什么时候插手、什么时候放手”。这期就把整条链路捋清楚顺便把我在源码里看到的一些值得注意的细节分享出来。1. 整体架构一条命令从输入到执行的完整链路在真正读这四个模块之前得先在脑子里搭一张全局图。DeepSeek Harness 不是把“能执行命令”这件事交给某一个模块而是拆成四段接力文件负责准备环境、命令负责理解意图、审批负责判断风险、沙箱负责隔离执行。每个模块都有明确的边界但也正因为边界清晰协作时的时序和状态传递就成了关键。1.1 四个模块各自的职责边界先给这四个模块画个像方便后面看代码时对照文件模块FS Manager管的是“沙箱里能看到什么”。它负责把用户工作目录的内容同步进沙箱再把沙箱里产生的结果同步出来。它还管着哪些路径可读、哪些路径可写、哪些路径干脆不可见。命令模块Command Runner管的是“这条命令怎么执行”。它负责解析用户输入的命令行做基础校验把命令发送给沙箱里的执行器然后接管输出流和退出码。它是用户意图和沙箱执行之间的翻译官。审批模块Approval Gate管的是“这条命令允不允许执行”。它根据命令的风险等级、用户的历史行为、当前会话的状态决定是直接放行、自动拒绝、还是弹给用户人工确认。沙箱模块Sandbox Runtime管的是“命令在哪里执行”。它负责启动隔离环境、配置网络、挂载文件系统、执行命令、回收资源。它是整个链条里最底层的执行底座。1.2 调用链路与关键事件流看源码时我一开始犯了个错误想按调用顺序从上往下捋。结果发现这四块根本不是简单的“A调用B、B调用C”的线性关系而更像是一个事件驱动的协作网络。核心链路大致是这样的用户输入命令 ↓ 命令模块解析生成 CommandRequest ↓ 文件模块检查命令涉及的文件路径准备沙箱工作目录 ↓ 审批模块评估命令风险决定放行/拒绝/人工确认 ↓ 沙箱模块启动或复用隔离环境 ↓ 沙箱执行命令流式回传输出 ↓ 文件模块将结果文件同步回宿主机 ↓ 命令模块汇总退出码结束一次请求这里有一个很多人容易忽略的重点审批不一定要在沙箱启动之前完成。源码里做了优化——如果当前会话已经有运行中的沙箱审批会和沙箱启动并行进行。因为审批要等用户操作延迟不可控而沙箱启动是纯机器操作时间基本固定两者并行能省下不少等待时间。这种细节如果不看源码光靠“调用链”思路是理解不了的。1.3 为什么需要这种分层设计有读者可能会想一个执行命令的功能搞四个模块是不是过度设计了我起初也有这个疑问但看完代码后理解了这样的拆分不是“为了架构而架构”而是每个模块都对应一个独立的变化维度文件系统同步的策略会变同步哪些目录、用增量还是全量、要不要走压缩通道。命令解析的规则会变不同平台的路径规则、参数通配符的处理方式。审批策略一定会变每个人对“危险命令”的认定标准都不同产品上还需要支持自定义规则。沙箱技术栈更会变可能从 Docker 切到 Firecracker或者换内核运行时。如果这些逻辑写在一个模块里任何一处变动都要牵动全局。拆开之后只要接口稳定单模块替换不影响其他部分。这个思路本身我认为比四个模块的具体实现更有借鉴价值。2. 文件模块沙箱内外如何安全交换数据文件模块是所有协作的基础——命令要跑得先有文件结果要拿回来也得靠文件同步。这个模块的设计重点是怎么在保证隔离的前提下让数据在宿主机和沙箱之间顺畅流动。2.1 只读镜像与可写覆盖层的设计沙箱里的文件系统不是直接把宿主机的目录挂进去那么简单的。源码里采用的是“只读基座 可写覆盖层”的模式跟 Docker 的 overlayfs 思路一致只是实现上更轻量。具体来说沙箱的根文件系统是一个只读镜像里面是基础的运行环境工具链、运行时库、常用命令。而工作目录是一个单独的可写层挂在固定的路径下。这样做有两个直接好处安全即使沙箱里的命令跑出问题把系统文件搞坏了也只影响可写层。重启一个沙箱就是全新状态不需要重新拉镜像镜像只读且已被宿主机校验过。性能多个沙箱可以共享同一份只读镜像只有可写层是每个沙箱独享的。内存和磁盘开销都能控制得很低。我在代码里看到一个关键参数叫FS_ROOT它指向只读镜像的挂载点。初始化沙箱时会先只读挂载这个根再在指定路径下建一个临时目录作为可写层。这个可写层在你主动销毁沙箱或者会话超时回收时会被直接删掉不需要做额外的清理。2.2 文件同步机制单向、双向与增量传输文件同步是我花时间最长的一个模块因为它要处理的情况太多了。源码里其实支持三种模式分别对应不同场景同步进沙箱宿主机 → 沙箱在命令执行前把用户当前工作目录里的必要文件传进去。简单做法是直接打包传整个目录但代码里做了增量处理——只传自上次同步以来有变动的文件判断依据是mtime size的组合哈希。同步出沙箱沙箱 → 宿主机命令执行完毕后把沙箱内工作目录中新增或修改的文件传回宿主机。这里有个很挫但很有效的策略先传全部文件再用rsync --checksum的方式做比对覆盖。实时双向同步这个只在特定模式下启用比如用户开启了交互式开发模式。它走的是文件系统事件监听fsnotify 捕获到变更后触发同步而不是轮询。这里我要特别提醒一个容易踩的坑同步方向搞反了。我一开始理解成“宿主机是主、沙箱是从”所有改动都以宿主机为准。但在实际的项目里AI 生成的代码经常是在沙箱内修改的所以沙箱内的文件版本可能比宿主机新。如果同步策略做成单向覆盖就会把沙箱里刚生成的结果冲掉。源码里对同步方向的判断逻辑写得很清楚命令执行前以宿主机为准命令执行后以沙箱为准。这个“谁写算谁”的规则贯穿在同步实现里。2.3 文件访问的权限控制与路径隔离文件模块的另一项重要职责是判断沙箱里的命令能访问哪些路径。这部分虽然看起来跟“文件管理”关系不大但它是整个权限模型的地基。FilePolicy这个类管着这件事。初始化时它会读三张表只读路径白名单、可写路径白名单、完全隐藏路径黑名单。执行命令前Command Runner会带着命令里出现的路径去问 FilePolicy 做校验如果访问了黑名单里的路径命令会在执行前就被拦下来。让我印象很深的一个细节是路径归一化的处理。代码里不是简单地做字符串前缀匹配而是先做filepath.Clean、filepath.Abs、再解析软链接filepath.EvalSymlinks最后才跟策略表比对。一开始我觉得这是多此一举直到自己写了一个 demo 试试——随便加一个../就能绕过一个字符串前缀检查。在权限判断里不做路径归一化等于没做。这个细节值得任何做安全相关功能的同学记在小本子上。2.4 实操心得处理大文件与并发读写冲突文件同步这块我在实际调试中碰到过一个典型的性能问题工作目录里放了一个很大的node_modules或.venv每次命令执行前都要同步导致一次简单的“查看文件”操作都要等十几秒。后来我翻源码发现文件同步逻辑里其实预留了忽略规则接口只是默认配置里只忽略了.git和.hg。我在自己的配置里把这几个目录加了进去exclude: - .git - .hg - .svn - node_modules - .venv - __pycache__加完之后同步耗时的变化是肉眼可见的级别。不要相信“默认配置就是最优配置”尤其是文件同步这类和具体项目强相关的功能默认配置一定是保守的、普适的不一定适合你的使用场景。关于并发读写冲突还要提醒一件事如果同时启动两个沙箱并对同一个文件做了修改最后写回宿主机时后完成的那个会覆盖先完成的那个。源码里目前没有做文件级别的冲突合并它采用的是“基于目录的同步快照”每个沙箱在启动时都会记录当时的文件状态快照写回时以快照为基准做增量更新。这个机制对你的数据安全其实是够用的——它保证的是“不丢失上次同步后产生的文件”但不保证“两个沙箱改同一个文件不丢失一份”。3. 命令模块执行、拦截与超时控制命令模块是整个链路的入口和出口——它接收用户的原始输入经过解析、校验后发送给沙箱执行再回收执行结果。这部分对应到源码里的CommandRunner和CommandRequest。3.1 命令解析与白名单策略命令模块首先要回答的问题是“用户输入的这一行文本到底是一条什么命令”源码里没有直接把它丢给 shell 去执行而是先做了一层结构化解构。CommandParser会把输入拆成命令名、参数列表、环境变量前缀、重定向目标。这一步不是简单的空格分割而是要正确处理引号、转义符、管道符号。作者用了shellwords这个库来解析而不是自己写正则——这个选型很关键因为 shell 的转义规则极其复杂自己写解析器很容易在边缘 case 上翻车。解析完成后命令模块会拿命令名去查一张白名单。这张白名单不是说只有白名单里的命令才能执行而是用来做风险预分级的。比如ls、cat、grep这类命令被标记为“只读安全”而rm、curl、eval这类被标记为“高风险动作”。这个分级结果会作为参数传给审批模块它决定这条命令是走自动放行还是人工审批。这里有一个很值得学习的细节分级不是只看命令名还会看参数。同样一条bash命令bash --version是只读安全的而bash -c rm -rf /就是极高风险。源码里对常见的危险模式和参数组合做了特征匹配命中就直接升级风险等级。我最初以为这是用复杂的 AI 模型做的结果一看实现——是一组精心维护的模式匹配规则简单但有效。3.2 拦截规则的实现思路拦截规则在代码里叫BlockRule。每条规则有两个核心组成部分一个匹配模式一个拦截动作。匹配模式可以是命令名的前缀匹配、参数的包含匹配、甚至是指定路径的访问尝试。拦截动作只有三种拒绝执行、标记人工确认、仅记录日志。给我启发最大的是rm命令的拦截规则实现。它对rm -rf这个组合做了单独的、严格的限制并且会解析rm后面的路径参数如果解析结果包含根目录/或者家目录~就会触发高风险标记。但只针对-rf组合单独的rm file.txt不会触发任何拦截。此外命令模块还处理了一个开发中经常遇到的问题别名和 PATH 污染。如果沙箱里装了某些工具它可能自带一个rm的 alias指向一个更危险的命令。源码里的解决方法是使用command -v cmd查到的绝对路径来做规则匹配而不是直接匹配字符串。这样rm就不会被 alias 影响拦截规则始终基于真实的可执行文件。3.3 超时、资源限制与日志采集命令执行时最怕的就是“挂死”。源码里对超时的处理非常保守——每条命令都有默认超时时间我记得是 120 秒超时后主动杀掉进程并返回一个超时错误码。超时实现用的不是简单的time.Aftercommand.Process.Kill()而是考虑到了进程组的问题。因为 shell 命令经常派生子进程管道、后台任务如果只杀主进程子进程会变成孤儿进程继续跑把系统资源吃光。原理上是给整个命令的进程组单独建一个进程会话Setpgid超时的时候直接杀掉整个进程组。这个细节的处理方式值得写进你自己的命令行工具里。日志采集这块标准输出和标准错误是分开处理的。源码里有OutputSink这个抽象它是多路广播的——一路写给会话的日志文件一路写给交互终端的实时输出流还有一路给到事件系统用于后续的文件同步触发判断。多路输出的好处很明显用户能实时看到输出同时日志也被完整记录下来而且文件同步模块还能监听输出的文件名来做智能触发。3.4 常见问题命令挂死与僵尸进程处理即使有了超时机制我还是在实际使用中遇到过命令挂死的情况最典型的是执行一个交互式命令比如vim或者top。命令模块解析后没有检测出它需要 TTY执行时也没有给伪终端导致命令直接在非交互模式下挂起。源码里对这个问题的方法比较聪明它判断命令名是否是“已知交互式程序列表”中的一员vim、top、htop、python REPL 等如果是就自动为它分配一个伪终端PTY并且把用户的输入流接入到 PTY 的 master 端。这让vim这类命令能正常工作。另一个跟僵尸进程相关的细节是命令模块在杀掉超时进程后还要等待(wait())进程结束回收退出码防止它变成僵尸进程。即使超时了也要等到Wait()返回后才会把执行结果返回给上层。杀进程和回收进程是两件事中间隔着一个异步等待的过程。这个细节对我来说是这次源码阅读里比较大的一个收获。4. 审批模块风险分级与状态机设计审批模块的价值不在于“拒绝危险命令”而在于“在安全与效率之间找到平衡点”。如果每条命令都要人工确认体验会非常糟糕但如果直接放行所有命令沙箱的安全性就无从谈起。4.1 审批流程的状态机审批状态机是四个模块里代码结构最清晰的。它定义了这几个状态INITIATED: 审批请求已创建等待决策。AUTO_APPROVED: 系统根据策略自动放行。AUTO_DENIED: 系统根据策略自动拒绝。PENDING_HUMAN: 已被升级到人工审批等待用户确认。HUMAN_APPROVED: 人工审批通过命令可以执行。HUMAN_DENIED: 人工审批拒绝命令不执行。TIMEOUT: 审批请求超时默认按拒绝处理。CANCELLED: 审批请求被取消比如用户主动撤销了命令。这些状态的定义保证了整个审批过程是确定性的——不管发生什么情况最终都会落到一个终态。状态转移的逻辑集中在一个approve()方法里核心逻辑用伪代码看就是这样def evaluate(request): if request.is_cancelled(): return State.CANCELLED risk request.risk_level if risk auto_approve_threshold: return State.AUTO_APPROVED if risk auto_deny_threshold: return State.AUTO_DENIED # 进入人工审批 human_result await request.ask_human(timeoutapproval_timeout) if human_result is None: return State.TIMEOUT return State.HUMAN_APPROVED if human_result else State.HUMAN_DENIED这里有一个细节特别值得注意ask_human函数不是简单的同步等待而是注册了一个“如果超时则自动拒绝”的定时器。审批超时的默认策略是拒绝而不是通过。这是一个安全优先的设计选择宁可让用户重新执行一次命令也不能让高危命令在无人确认的情况下跑了。4.2 风险分级与自动审批策略风险分级是审批模块的核心。源码里用一个RiskLevel枚举来描述风险等级一共有四档风险等级典型场景默认策略SAFE只读操作ls、pwd、cat自动放行LOW修改文件但不影响系统自动放行带审计日志MEDIUM涉及网络、可执行文件投递人工确认HIGH删除目录、写入系统路径、拉取并执行远程脚本人工确认 二次确认这个分级不是拍脑袋定的。我在代码里看到它跟命令模块的解析结果是联动的——命令模块把解析出的命令名、参数、涉及的路径传给审批模块审批模块再根据规则库计算风险等级。两级模块通过一个数据结构对接而不是相互调用函数这样设计的好处是如果你需要支持新的命令类型只需要在解析层增加规则审批层不用改动。关于自动审批源码里的策略是“白名单 黑名单 用户自定义规则”三层。默认情况下只读命令自动放行但如果你曾经在这个会话里执行过rm -rf后续所有rm命令都会被要求人工确认。4.3 用户交互与超时回退人工审批的交互设计直接影响使用体验。源码里用户交互的通道是通过消息协议对接终端 UI 的——在非交互模式下它会自动降级为“等待命令行确认”。我实际体验中的感受是审批的超时时间是一个需要根据使用场景调优的参数。默认值 60 秒对我这种经常同时开多个任务的场景来说太短了我在配置里改成了 300 秒。这个参数在配置文件的approval.timeout字段下。如果你是跑批处理任务并且希望尽量不被打断可以考虑调大它但要注意超时时间越长高危命令的潜在风险窗口就越大。4.4 常见问题审批卡死与重复触发审批模块最常见的问题是“审批一直没有弹出来”。我排查了很久才发现根因审批的事件消息发到了 UI 前端但前端的弹层组件在沙箱全屏模式下会挡住底层 UI导致审批框渲染不出来。源码里对这个问题有一个比较巧妙的处理审批请求除了会推送给 UI 事件流之外还监听了一个 “UI 通道就绪” 的信号。如果这个信号超时未到审批模块会退回到终端渲染模式——直接在终端里打印一条高亮的确认请求等待用户输入y/n。另一个重复触发的问题出现在“同一个会话里的连续命令”。如果前一条命令还在等审批用户又发了新命令新命令不会进入审批队列而是直接返回一个“已有审批在进行中”的提示。这是刻意设计的——避免用户在修改审批规则时多条高危命令同时涌入造成混乱。5. 沙箱模块轻量级虚拟化与生命周期管理沙箱是整个体系的“底座”也是保证安全边界的关键。审批模块发出的“执行许可”最终要落到沙箱模块命令模块也要依赖沙箱模块才能真正执行命令。5.1 运行时选型为什么用轻量级虚拟机代码里默认的沙箱运行时是 Firecracker 或类似内核虚拟化技术驱动的轻量级 VM而不是简单起一个 Docker 容器。两者的核心区别是Firecracker 这类轻量级 VM 有自己的内核跟宿主机是硬隔离。即使沙箱里的进程拿到 root 权限它也只能破坏自己的虚拟机影响不到宿主机。Docker 容器共享宿主机内核隔离边界靠 namespace / cgroup / seccomp 维持安全性比 VM 弱一个量级。DeepSeek Harness 的场景是执行 AI 生成的代码这些命令很可能是不受信任的。在这种威胁模型下安全边界必须放在内核级别。所以选型用了轻量级 VM而不是 Docker 容器。但轻量级 VM 也付出了一些代价启动时间比 Docker 容器长。代码里对沙箱启动做了优化——沙箱是复用池化的而不是每条命令都新建一个。启动的几个沙箱空闲着等着有新任务进来直接挂载工作目录用。资源占用更重一个沙箱默认吃 2 CPU 2GB 内存。如果你的机器配置不高开多个沙箱确实会有点吃力。5.2 沙箱启动与销毁的细节沙箱生命周期的入口在SandboxPool这个类里。它的工作流程是根据配置的池大小预启动若干沙箱实例。接到任务后从空闲队列取出一个沙箱把工作目录挂载进去。在沙箱内执行命令完成后卸载工作目录把沙箱放回空闲队列。如果有沙箱崩溃或者空闲超时重新创建。这个池化思路本身不复杂但有几个细节值得注意挂载点隔离沙箱并发执行时两个沙箱的工作目录是互相隔离的。即使两个沙箱跑在同一台机器上它们之间的文件系统也互不可见。网络策略沙箱的默认网络策略是“出网需审批”。命令模块会把网络访问请求转给审批模块处理。我试过在沙箱里直接pip install第一次会弹审批同意之后后面的命令就正常放行了。销毁回收空闲超过一定时间默认 30 分钟的沙箱会被自动销毁释放资源。如果你开着htop看到几个空闲进程不用惊讶那是沙箱在看门狗的超时检查。沙箱崩溃处理是另一个容易出问题的地方。源码里做了一个崩溃自愈机制如果沙箱在执行命令过程中崩溃了命令模块会收到一个SandboxCrashError自动重启一个新沙箱并重新执行一次同类命令。不过这里要小心这条命令不会重新经过审批模块因为审批在崩溃之前已经完成了。如果你希望更严格的安全控制可以关掉这个自愈重试。5.3 网络隔离与资源配额沙箱默认工作在 NAT 网络模式下只有出网权限不会被宿主机直接访问到。如果需要让宿主机访问沙箱内启动的服务比如在沙箱里跑了一个 Web 应用需要显式开启端口转发。我本地测试时发现端口转发配置在沙箱创建时固定不支持运行期修改。这意味着如果你想在沙箱里启动一个随机端口的服务然后让宿主机访问它会有点麻烦。不过好在这个限制有明确的报错不会让你盲目排查。资源配额在代码里是这样配置的sandbox: cpu: 2 memory_mb: 2048 disk_mb: 4096CPU 和内存是硬限制超过之后沙箱里的进程会被强制杀掉。磁盘配额走的是 overlayfs 的大小限制写超出配额会报Disk quota exceeded。这三个参数是沙箱稳定性的底线——如果你跑的构建任务经常被 OOM 杀死确认一下是不是配的 2GB 内存不够用。5.4 实操心得沙箱冷启动优化沙箱的冷启动时间是我在使用中最关注的一个指标。源码里有两处优化让我印象深刻第一镜像的预拉取。在 Harness 启动时镜像就已经开始后台拉取了不会等到第一次需要沙箱时才去下载。这样第一次命令执行可能不用等网络下载但前提是你配置了预拉取的镜像列表。第二内核页缓存的共享。因为多个沙箱复用同一个只读根这些镜像文件会在宿主机内存中做缓存后启动的沙箱就不需要重新从磁盘读镜像了。如果你的磁盘是机械硬盘这个优化的感知会非常明显。如果你对启动时间特别敏感还有一个取巧的办法在配置里把沙箱池的最小空闲数量提高比如min_idle: 2让更多沙箱常驻空闲。代价是更多的驻留内存占用。这本质上是一个“冷启动时间”和“内存占用”的取舍直接看你更在意哪个资源了。6. 四模块协作的完整拆解从请求到执行的时序与状态传递前面几节分别讲了四个模块的职责和内部机制这一节把四者串起来按照一次完整的请求一步步看它们是怎么协作的。6.1 一次命令请求的完整时序假设用户在交互界面输入了这样一条命令curl -fsSL https://sh.example.com/install.sh | sh这条命令在四个模块之间是这样流转的命令模块接管CommandRunner 接收到原始字符串调用 Shellwords 解析。命令名curl参数-fsSL https://sh.example.com/install.sh管道符号被识别为命令组合。解析完成后命令模块把它包装成CommandRequest这个对象里包含解析结果、命令文本、请求 ID。文件模块介入CommandRunner 把 CommandRequest 发给文件模块的PathResolver做路径检查。这里检测到命令本身没有访问任何本地文件路径但sh会执行从网络下载的脚本——这属于“动态文件投递”文件模块将这条命令标记为“涉及不可信内容执行”并在请求里附加一个requires_network标志。审批模块决策CommandRequest 带着命令模块的解析结果和文件模块的附加标记进入审批模块。审批模块计算风险等级curl 从网络下载 管道给 sh 执行 高危HIGH。风险等级高于自动放行阈值审批模块进入人工确认模式等待用户确认。沙箱模块执行用户同意后命令模块从沙箱池中取一个空闲沙箱把工作目录挂载进去然后把命令发送给沙箱内的执行代理。沙箱执行完后退出码和输出流回传。文件模块收尾命令执行完毕后文件模块做一次“以沙箱为准”的同步。如果沙箱里产生了新文件比如脚本下载了一个工具包它会把这个目录同步回宿主机。命令模块汇总命令模块把退出码、输出流、执行时间、文件变更记录汇总成一个CommandResult交给上层。一次请求到此结束。这个链路里有几个值得注意的设计考量文件模块和审批模块都参与了风险判断但判断的角度不同。文件模块偏重“数据流向的安全”审批模块偏重“命令本身的风险”。沙箱在选择的时候并不关心命令内容它只接受“执行这个命令”的指令。这种“无状态”设计大大简化了沙箱模块的复杂度。6.2 模块间传递的关键数据结构模块间的数据结构设计对协作清晰度影响很大。代码里核心的几个数据结构是class CommandContext: id: str command: str parsed: ParsedCommand working_dir: str env: dict class ApprovalContext: command_id: str risk_level: RiskLevel reason: str actor: str class SandboxRequest: command_id: str context: CommandContext sync_from_host: SyncQuery sync_to_host: bool这三个数据结构贯穿了整条链路CommandContext是命令模块的输出ApprovalContext是审批模块的输入/输出SandboxRequest则是传给沙箱模块的“执行委托书”。我在读代码时注意到CommandContext在传给沙箱模块之前会被“瘦身”——去掉与执行无关的信息比如解析时的中间状态只保留执行必需字段。这既是出于效率考虑减小序列化开销也减少了沙箱内代码的信息暴露面。有助于减少模块间耦合的设计哪怕是信息传递时的删减都值得借鉴。6.3 错误处理与异常恢复一次请求可能出现的异常情况不少让我按阶段列举一下命令解析失败原始输入不符合 shell 语法。这直接返回给用户一个解析错误不进入后续流程。文件同步失败网络断了或者磁盘写满。这是最高优先级的错误——因为它可能导致数据丢失。源码里的策略是“命令不执行直接返回错误”不让命令在一个文件系统不完整的环境下运行。审批超时默认返回“审批未在时限内完成”按拒绝处理。沙箱崩溃重启一个新沙箱重新执行一次命令。沙箱内命令异常退出退出码非零。这不是系统错误命令模块会正常返回给用户由用户判断是否需要处理。在处理这些错误时代码遵循一个原则不掩盖错误但也要提供恢复路径。错误信息会通过结构化的ErrorType字段传给上层方便 UI 层根据不同类型渲染不同的恢复按钮。7. 常见问题与排查技巧实录这部分集中整理我在使用和二次开发中遇到的问题有些是从源码里读出来的有些是自己在调试时踩过的坑。7.1 高频问题速查表现象可能原因排查思路命令执行前卡住几十秒文件同步耗时过久检查工作目录是否有大型依赖目录配置 exclude 规则命令执行时报“无法访问路径”路径不在权限白名单查看 FilePolicy 配置确认路径是否覆盖高危命令没弹审批直接跑没有配置审批规则检查 approval.rules 配置确认 risk_threshold 是否过高沙箱内命令偶发超时沙箱资源耗尽查看沙箱 CPU/内存配额适当调高多个沙箱同步文件互相覆盖相同工作目录被多处挂载避免同一工作目录同时挂载多个活跃沙箱审批弹窗不出来UI 与审批服务消息通道断开查看审批事件流是否正常确认是否触发终端回退模式命令执行后结果丢失文件同步方向配置错误确认同步策略是“执行后以沙箱为准”7.2 调试沙箱崩溃的实战方法沙箱崩溃这个问题排查起来最费劲因为崩溃后能拿到的现场很少。我自己摸索出了几个有效的方法第一步查内核日志。如果沙箱是因为内核 panic 崩溃的宿主机日志里会有痕迹。dmesg -T | grep -i “kernel panic”是一个快速定位入口。第二步看沙箱退出码。源码里对不同崩溃原因定义了不同退出码128signal 表示被信号杀死139 是段错误137 是 OOM 杀死。从退出码能初步判断方向。第三步复现现场。如果崩溃是稳定复现的可以通过打开debug日志把沙箱启动的完整过程打出来。我建议在本地复现时加一层strace抓沙箱执行命令时的系统调用基本能定位到具体是哪一步出的问题。7.3 性能与稳定性的平衡经验最后分享一些我在调优过程中的经验。沙箱的资源配额不是越大越好——配额越大单机可承载的沙箱数量越少并发能力就会下降。我现在的经验值是普通文件操作、构建任务2 CPU 2GB 内存是起步线不够再加。需要跑 npm install、Gradle 等重型构建任务至少 4 CPU 4GB 内存。数据库类任务预留足够的内存给缓冲池内存配额量到 6GB 比较稳妥。另外沙箱池的大小建议按“峰值并发需求 1”来配置。多留一个空闲沙箱能显著降低高并发场景下的排队等待时间。同时要配合空闲超时回收避免沙箱长期驻留吃资源。还有一个非常实用的小技巧——如果你的 AI 编码工具在工作时总感觉“越用越卡”很可能就是沙箱池的自动扩容逻辑不够给力。我建议在配置里观察一下沙箱池的idle数量和waiting数量如果waiting经常大于 0就说明池容量不够可以适当上调。8. 写在最后的实践建议如果要给这次源码阅读画个句号我最想说的是这个系统的协作设计比任何单个模块的代码都更值得借鉴。文件、命令、审批、沙箱各自的实现都是见过很多次的设计模式但把它们组合在一起、让它们协同工作时才真正体现出架构的功力。回到实际使用我给同样在折腾这类 AI 编码助手源码的读者三条建议第一改造之前先把日志打开。我最初阅读时最大的失误是只看了代码没看运行日志。日志里有完整的请求流转记录每一步的耗时一目了然。通过这些日志你能很快判断瓶颈在哪、哪个模块拖慢了整条链路。第二修改默认配置前先做一次最小实验。比如你想调整审批超时时间先在测试环境把超时调成 10 秒试试效果再上线到日常用的配置里。这类系统牵一发动全身稳妥一点不亏。第三理解“安全”与“效率”的此消彼长。审批越严格安全性越高但中断频率也越高。你需要在配置里找到一个适合自己的平衡点对我来说这个平衡点是“只读命令自动放行写操作人工确认高危命令直接拒绝”。你可以按自己的使用场景摸索出一套最顺手的策略。最后分享一个小技巧如果你使用 Harness 时发现命令复现跟不上你的操作速度可以去检查一下文件同步的exclude规则。我把自己工作目录里的node_modules和.venv排除掉之后整个响应速度有明显提升。这不是什么高深的技巧但恰恰是这类实践里最实在的收获。