DeepSeek Harness FS/Shell/Sandbox：本机能力如何被策略化

模块定位

Agent 能读写文件、执行命令后，风险等级立刻变高。DeepSeek Harness 没有把这些能力写成一个“大工具”，而是拆成 filesystem、subprocess、shell、terminal、sandbox、permission 多层。

源码入口：

packages/fs/*
packages/subprocess/*
packages/shell/*
packages/terminal/*
packages/sandbox/*
packages/interaction/permission-presets
docs/subsystems/filesystem.md
docs/subsystems/shell.md
docs/subsystems/subprocess.md

文件系统能力家族

FS 分层：

包	职责
`fs/`	Service Definition：路径、URI、读写、atomic mutation、policy events
`fs-local/`	本地文件系统 provider
`fs-sandbox/`	在本地 provider 上加 write/edit fence
`fs-observation-policy/`	read-before-edit、observed-state、version guard
`tool-fs/`	`read` / `write` / `edit` 模型工具
`tool-fs-search/`	`glob` / `grep`，通过 ripgrep + subprocess 实现

注意 tool-fs-search 没有把 search 加到 FS provider contract。搜索是进程型工作，由 packaged rg 通过 ctx.subprocess 执行。这样 FS service 不需要承诺所有 backend 都有统一 search 能力。

Read-before-edit 为什么重要

文件编辑类工具通常需要先观察文件，再写入版本保护。否则模型可能基于旧内容修改新文件，造成覆盖。

FS observation policy 通过 fs/* event gate 参与，而不是变成 tool 的硬依赖。部署如果不挂它，工具还能跑，但失去该策略。

Shell 与 Subprocess

Shell 不是直接 spawn。它依赖 subprocess capability。这样 Bash、PowerShell、本地进程、远程 E2B 进程可以组合替换。

flowchart TD
  A["tool-bash / tool-pwsh"] --> B["ctx.shell"]
  B --> C["bash-local / pwsh-local / sandboxed shell"]
  C --> D["ctx.subprocess"]
  D --> E["local process tree or remote provider"]
  E --> F["sandbox backend"]

这种分层让“模型工具”和“执行世界”解耦。换执行环境不需要改工具 schema。

Terminal

Terminal family 提供持久 PTY。它不同于一次性 shell command，适合保留进程状态、交互式命令或需要持续输出的任务。Web UI 或工具可以按 session owner 管理 terminal。

Sandbox

Sandbox family 是进程隔离 seam。不同平台有不同 backend：

POSIX 可用 bwrap / Seatbelt / Landlock 等路线。
Windows 使用 ACL restricted-token runner 路径。

基础 bundle 根据平台启用 Bash 或 PowerShell 栈。两套 shell family 注册同一个 shell service，所以覆盖配置时必须只保留一个。

权限 preset

权限不是散在各个工具里的 if。interaction/permission-presets、approval service、sandbox policy、fs-sandbox 共同决定当前操作能否执行。

典型模式：

read-only：不允许写。
workspace-write：只允许 workspace 和 temp root 内写。
更高权限：需要用户显式切换或审批。

常见坑

第一，文件 IO 没有工具 timeout。OS 层写操作超时后仍可能完成，贸然杀 deadline 会造成状态不明。

第二，search 不走 ctx.fs。它通过 subprocess 跑 ripgrep。

第三，read-before-edit 与 sandbox write fence 是正交策略，两者都需要。

第四，Windows shell 覆盖不完整会导致同一 service key 双注册或缺失。

继续读源码

packages/fs/README.md
packages/shell/README.md
packages/subprocess/README.md
packages/sandbox/README.md
packages/terminal/README.md