Harness（Agent 驾驭层）文件后端完整解析

Harness 架构：Agent 运行外壳，文件后端 (File‑Backend) 就是 AI 智能体的虚拟文件系统层，负责所有文件：增、删、改、查、执行五大操作；多 Agent 之间全局共享，子 Agent 不隔离文件后端资源。

一、为什么 Harness 必须要有文件后端

裸大模型只能把全部数据塞进上下文窗口，存在致命缺陷：

文件后端的本质：把内存里的状态，卸载到「虚拟 / 物理文件」；用文件路径字符串代替大段文本，送入 LLM 上下文，只占用极少 Token。

二、核心架构：CompositeBackend 综合动态路由后端

最主流实现是 CompositeBackend（组合后端 / 路由后端），一个调度入口，内部挂载 3 种不同存储后端，根据文件路径前缀自动路由分发，一套统一的读写接口，底层存储可切换。

三大后端实例

表格

路由逻辑伪代码：

ts

function resolveBackend(path:string){
if(path.startsWith("memory://")) return memoryBackend
if(path.startsWith("store://")) return storeBackend
return sandboxBackend // 默认沙箱磁盘后端
}

三、文件后端提供的统一接口（5 大原语）

所有后端必须实现同一套接口，上层 Agent 无需关心底层是内存 / 磁盘 / 对象存储：

上层工具调用、Agent 读写全部走这套抽象接口，实现存储层与 Agent 业务解耦。

四、文件后端在 Harness 六层架构中的位置

Harness 完整六层结构：

关键点：文件后端挂载在主 Agent，全局共享，所有子 Agent 共用同一套文件后端实例，以此实现多 Agent 文件协作通信。子 Agent 不会创建独立文件后端。

五、沙箱后端安全机制（重中之重）

SandboxBackend 最核心价值就是安全围栏

六、典型运行流程示例

七、Workspace 标准目录约定（文件后端沙箱目录）

plaintext

workspace/
├── AGENTS.md # Agent角色约束
├── MEMORY.md # 长期记忆文件
├── output/ # Agent产出报告、导出文件
├── src/ # AI生成代码
└── logs/ # 会话运行日志

这套目录就是沙箱后端在磁盘映射出来的真实文件夹。

八、文件后端衍生技术：文件化状态管理

这是 Harness 架构标志性设计：

Brain‑Hands‑Session 三层解耦 Brain (Harness 调度层) + Hands (沙箱执行层‑文件后端) + Session (事件日志) 文件后端作为 Harness 调度层和沙箱执行层之间通信桥梁，所有执行结果通过文件传递，而非内存变量，任务中断后可从文件恢复继续跑，支持断点续跑、回滚重试。

九、简易代码骨架（TS 版 CompositeBackend 参考实现）

typescript

运行

// 文件后端统一接口
interface IFileBackend{
read(path:string):Promise<string>
write(path:string,content:string):Promise<void>
list(path:string):Promise<string[]>
remove(path:string):Promise<void>
}

// 综合路由后端
class CompositeBackend implements IFileBackend{
sandbox:SandboxBackend
memory:MemoryBackend
store:StoreBackend

getBackend(path:string):IFileBackend{
if(path.startsWith("memory://")) return this.memory
if(path.startsWith("store://")) return this.store
return this.sandbox
}

async read(path:string){
const backend=this.getBackend(path)
return backend.read(path)
}
}