drive9-ai/drive9-dsh

适用于 DeepSeek Harness 的 Drive9

为 DeepSeek Harness 提供持久化智能体工作区以及持久、有界的工具证据。

@drive9/drive9-dsh 是一个标准 DSH 包，包含四个相互独立的 Cordis 组件：

- 一个 Drive9 修订版 CAS 文件系统，用于 Harness 的 read、write 和 edit 工具；
- 一个隔离的证据后端，用于存放超大工具结果；
- 模型可见的 result_search 和 result_read 工具，具有硬性输出限制；
- 针对可选启用最终挂载配置的模型可见运行时上下文警告。

该架构将四个生命周期保持分离：

| 层 | 所有者 |
| --- | --- |
| 智能体循环 | DeepSeek Harness |
| 会话与对话历史 | DeepSeek Harness |
| 持久化工作区与不可变证据 | Drive9 |
| Shell、沙箱、语言服务器与计算运行时 | 用户的 DSH 部署 |

Drive9 挂载仅在现有运行时内部暴露持久化工作区。它不会创建、拥有或维持该运行时的存活。即使运行时或工作区消失，证据仍可读取，因为它存储在单独的、未挂载的 Drive9 根目录下。

Drive9 不提供 shell 或沙箱。V1 暴露两种明确的挂载一致性配置：

- strong（默认且推荐）在与 Harness 进程工具相同的执行世界中使用 Linux Drive9 FUSE 挂载。启动时会证明 SDK 到挂载以及挂载到 SDK 的一致性，写入会等待精确的已挂载字节后才返回。
- eventual 是可选启用的 WebDAV 配置。面向模型的读取、写入、修订 CAS 和证据仍使用 Drive9 SDK，但进程工具在 SDK 写入后可能会观察到过期挂载字节超过 30 秒。

该集成绝不会将 strong 静默降级为 eventual。在真实的 macOS WebDAVFS 验证中，Drive9 桥接立即观察到了 SDK 写入，而挂载的 open/stat 视图在超过 30 秒内仍保持过期或阻塞。

为什么

智能体工作有两种不同类型的状态：

model filesystem tools ── Drive9 SDK + revision CAS ── persistent workspace
│
process tools ── /mnt/drive9 ─────┘

large tool output ── isolated Drive9 evidence root ── exact result_id
├─ result_search
└─ result_read

工作区保持进程可见，而证据留在工作区挂载之外。shell 命令、工作区删除或工作区回滚都无法访问证据命名空间。

先决条件

- 带有 Node.js 22.19 或更高版本的 Linux，且 PATH 中有 npm 和 pnpm；
- DeepSeek Harness 0.1.0-rc.6，包括标准 dsh CLI；
- 当前版本的 Drive9 CLI，支持 drive9 token issue，并可访问 Drive9 服务器；
- 对于推荐的 strong 配置，需要 /dev/fuse 和 fusermount3；对于可选启用的 eventual 配置，需要 WebDAV 挂载；
- 独立、按路径限定作用域的工作区和证据凭据。仅创建根目录并签发这些限定作用域的凭据时，才需要所有者凭据。

在继续之前，请安装 Harness CLI 和 pnpm：

npm install --global @deepseek-ai/dsh@0.1.0-rc.6 pnpm

从公开的 Drive9 仓库安装 Drive9 CLI，并验证两个 CLI：

dsh --version
drive9 version

快速开始

通过你常用的密钥注入器提供所有者凭据，然后一次性配置非机密路径。如果密钥缺失，断言会在预配之前失败：

: "${DRIVE9_OWNER_API_KEY:?inject the Drive9 owner credential}"

export DRIVE9_BASE_URL="https://api.drive9.ai"
export DRIVE9_EVIDENCE_BASE_URL="$DRIVE9_BASE_URL"
export DRIVE9_MOUNT_ROOT="/mnt/drive9"
export DRIVE9_REMOTE_ROOT="/workspace"
export DRIVE9_EVIDENCE_ROOT="/evidence/dsh"
export DRIVE9_MOUNT_CONSISTENCY="strong"

1. 预配隔离的根目录和凭据

一次性创建两个根目录。保持证据根目录未挂载，这样工作区工具和 shell 命令就无法访问它：

drive9 ctx add \
--name dsh-owner \
--server "$DRIVE9_BASE_URL" \
--api-key "$DRIVE9_OWNER_API_KEY"
drive9 ctx use dsh-owner

drive9 fs mkdir :/workspace
drive9 fs mkdir :/evidence/dsh

drive9 token issue dsh-workspace \
--ttl 24h \
--allow /workspace:read,list,write,delete \
--print

drive9 token issue dsh-evidence \
--ttl 24h \
--allow /evidence/dsh:read,write \
--print

每条命令只打印 bearer token，并保存其本地名称，以便后续轮换或撤销。将打印出的值存入你的密钥管理器，不要留在磁盘上，然后将这些值作为不同的凭据注入。该包会拒绝共享凭据：

: "${DRIVE9_WORKSPACE_API_KEY:?inject the workspace-scoped credential}"
: "${DRIVE9_EVIDENCE_API_KEY:?inject the separate evidence-scoped credential}"

有关生产环境的 token 作用域、TTL 和轮换指南，请参阅凭据和部署指南。

2. 挂载工作区

将工作区挂载到 Harness 运行时中。默认的 strong 配置文件要求 Linux 且具备 /dev/fuse 和 fusermount3：

mkdir -p "$DRIVE9_MOUNT_ROOT"

DRIVE9_API_KEY="$DRIVE9_WORKSPACE_API_KEY" \
drive9 mount --mode=fuse --profile=none :/workspace "$DRIVE9_MOUNT_ROOT"

该挂载必须与 Harness 子进程处于同一执行环境中。如果 Harness 在容器内运行，请在容器内挂载 Drive9，或在 Harness 启动前将挂载绑定到容器中。

--profile=none 是 strong 配置文件的一部分。编码代理挂载配置文件可以将进程路径路由到本地 overlay，而 SDK 调用仍然访问 Drive9，从而将 revision-CAS 契约的两端割裂。不要使用本地 overlay 配置文件，也不要为了让它启动而禁用启动证明。

若要改为选择宽松的 WebDAV 语义，请使用 WebDAV 挂载并显式选择 eventual：
DRIVE9_API_KEY="$DRIVE9_WORKSPACE_API_KEY" \
drive9 mount --mode=webdav --profile=none :/workspace "$DRIVE9_MOUNT_ROOT"

export DRIVE9_MOUNT_CONSISTENCY="eventual"

此配置文件在 SDK CAS 提交后即从写入返回；它不会等待挂载路径收敛。请勿将其用于通过 Harness 写入后立即用 cat、rg、测试、语言服务器或其他子进程进行验证的工作流。

3. 安装 bundle

推荐的发布渠道是预构建的 npm 包：

dsh plugin --profile web add @drive9/drive9-dsh

若要在注册表发布前验证未发布的检出或安装，请从公共仓库构建相同的预构建 tarball，而不是直接从 Git 安装 TypeScript 源码：

git clone https://github.com/drive9-ai/drive9-dsh.git
cd drive9-dsh
npm ci
PACKAGE_TARBALL="$(npm pack --silent)"
dsh plugin --profile web add "$PWD/$PACKAGE_TARBALL"
cd ..

此源码构建路径会运行该包正常的 prepack 构建，并为 DSH 提供一个包含 dist/ 的 tarball。直接使用 github:drive9-ai/drive9-dsh 依赖不包含构建产物，不是受支持的安装路径。

该包声明了一个 DSH bundle，因此标准的 dsh plugin 命令会安装它，并将其 cordis.patch.yml 层添加到所选配置文件。该 bundle 会禁用自带的 fs-sandbox 和 spill-local 存储提供程序，然后安装 Drive9 文件系统、证据后端和结果工具。Harness 自带的文件系统工具、子进程运行时、沙箱策略、观察策略和 spill 策略保持不变。Drive9 文件系统实现了与被替换的文件系统提供程序所执行的相同的每次调用 read-only、workspace-write 和 danger-full-access 变更策略。

4. 配置并运行

cd "$DRIVE9_MOUNT_ROOT"
dsh web --dump-config
dsh web

dsh web --dump-config 是推荐的预检。其组合树必须恰好包含一个活动的 fs 提供程序：@drive9/drive9-dsh/filesystem。自定义配置文件使用等效的 dsh --profile  --dump-config 和 dsh --profile  命令；无需 Drive9 专用的启动器。

若要移除该 bundle 及其配置文件层：

dsh plugin --profile web remove @drive9/drive9-dsh

在默认的 strong 配置文件中，当出现以下情况时，启动会失败，而不是回退或弱化契约：

- 挂载缺失或不可写；
- 远程根目录缺失或不是目录；
- SDK 写入未通过挂载显现；
- 挂载写入未通过 SDK 产生更新的 Drive9 修订版本。

eventual 配置文件仍会验证本地挂载目录和远程 Drive9 根目录，记录一条醒目的警告，将相同的警告添加到模型的持久运行时上下文快照中，并默认跳过双向证明。显式设置 verifyCoherence: true 仍会运行完整证明并传播任何失败。

组件

@drive9/drive9-dsh/filesystem
Drive9FileSystem 实现了完整的 Harness FileSystem 契约。

| 操作 | Drive9 行为 |
| --- | --- |
| resolve | 规范的挂载解析，拒绝词法逃逸和符号链接逃逸 |
| processPath / fileUrl | 经过身份验证的提供方目标，映射到真实挂载点之下 |
| stat | Drive9 元数据；修订号变为不透明的 Harness 版本 |
| readText / streamText | 严格 UTF-8，拒绝 NUL，不进行静默二进制强制转换 |
| readBytes | 元数据预检加有界范围读取 |
| listDir | 稳定排序，batchStat 请求上限为 256 个路径 |
| 受保护的写入/编辑 | 精确的 Drive9 修订号 CAS |
| 无条件的写入/编辑 | 有界的读取/修改/CAS 重试 |
| 变更策略 | DSH 每次调用的沙箱策略，针对最新的规范目标重新检查 |

在 strong 模式下，普通成功仅在 SDK 写入提交且挂载路径暴露相同字节后才返回。如果 Drive9 已提交但在有界一致性截止时间之前无法确认挂载，操作会抛出
DRIVE9_WORKSPACE_COMMITTED_MOUNT_UNCONFIRMED，并带有 workspaceCommitted: true、已提交版本以及原因 timeout、aborted 或 io。这既不是成功，也不是写入未发生的证据；调用方必须检查/协调，而不是盲目重试。在 eventual 模式下，它在 SDK CAS 成功后返回；processPath() 和
fileUrl() 仍然可用，但其挂载视图不保证读己之写。两种方法都会拒绝未经该文件系统实例身份验证的目标。

@drive9/drive9-dsh/evidence

Drive9EvidenceStore 实现了 Harness SpillStore：

1. 生成一个随机的 256 位能力；
2. 创建内容对象；
3. 创建带有字节数和 SHA-256 的规范清单；
4. 仅在两次写入都成功后，才发布 result_id 和来源凭证。

读取会验证稳定修订号、精确字节数、清单结构、SHA-256 和严格
UTF-8。清单写入失败则不返回定位符。不可达的内容孤儿可以由操作方保留策略回收，而不会向模型暴露部分证据。

@drive9/drive9-dsh/result-tools

该捆绑包注册：

result_search(result_id, query, max_matches?, context_lines?)
result_read(result_id, offset?, limit?)

两个工具都要求一个精确的定位符，该定位符已经签发到当前会话的持久工具历史中，或者从其显式播种的直接父级继承而来。猜测、枚举、纯文本回显、未播种的父级引用以及同级引用都会被拒绝。

硬性包限制：

- 返回 1,000 行；
- 返回 64 KiB UTF-8 文本；
- 100 个搜索匹配；
- 每个请求扫描 64 MiB；
- 64 KiB 搜索查询。

配置

随附的捆绑包读取以下环境变量：

| 变量 | 必需 | 默认值 | 用途 |
| --- | ---: | --- | --- |
| DRIVE9_BASE_URL | 否 | Drive9 SDK 默认值 | 用于工作区 SDK 调用的 Drive9 API 基础地址 |
| DRIVE9_WORKSPACE_API_KEY | 是 | — | 工作区范围的 SDK 凭据 |
| DRIVE9_MOUNT_ROOT | 否 | /mnt/drive9 | 进程可见的 Drive9 挂载点 |
| DRIVE9_REMOTE_ROOT | 否 | / | 挂载点所表示的远程子树 |
| DRIVE9_MOUNT_CONSISTENCY | 否 | strong | strong Linux FUSE 或显式 eventual WebDAV 语义 |
| DRIVE9_EVIDENCE_BASE_URL | 否 | DRIVE9_BASE_URL | 用于证据的 Drive9 API 基础地址 |
| DRIVE9_EVIDENCE_API_KEY | 是 | — | 单独的证据范围凭据 |
| DRIVE9_EVIDENCE_ROOT | 否 | /evidence/dsh | 未挂载的证据根目录 |

在以编程方式组合时，也支持在已提供标准 sandboxPolicy、systemPrompt 和 tools 服务的 DSH 上下文中进行：

import { Context } from '@deepseek-ai/cordis'
import * as Drive9Dsh from '@drive9/drive9-dsh'

const ctx = new Context()

await ctx.plugin(Drive9Dsh, {
filesystem: {
mountRoot: '/mnt/drive9',
remoteRoot: '/workspace',
baseUrl: process.env.DRIVE9_BASE_URL,
apiKey: process.env.DRIVE9_WORKSPACE_API_KEY,
mountConsistency: 'strong',
},
evidence: {
root: '/evidence/dsh',
baseUrl: process.env.DRIVE9_BASE_URL,
apiKey: process.env.DRIVE9_EVIDENCE_API_KEY!,
},
resultTools: {
maxScanBytes: 16 * 1024 * 1024,
},
})

该预设会拒绝缺失的凭据，并拒绝将同一凭据同时用于工作区和证据。

错误

文件系统故障使用 Harness 的 FS_ 代码，包括 FS_STALE_VERSION、
FS_NOT_OBSERVED、FS_PERMISSION_DENIED、FS_TOO_LARGE、FS_NOT_TEXT、
FS_ABORTED 和 FS_IO_ERROR。

DRIVE9_WORKSPACE_COMMITTED_MOUNT_UNCONFIRMED 是强配置挂载验证失败时特有的
提交后结果。它携带 workspaceCommitted: true，绝不能被视为可安全重试的
“写入未发生”错误。

证据检索使用稳定的 DRIVE9_RESULT_ 代码：

- DRIVE9_RESULT_INVALID_ID
- DRIVE9_RESULT_NOT_FOUND
- DRIVE9_RESULT_CORRUPT
- DRIVE9_RESULT_UNAUTHORIZED
- DRIVE9_RESULT_SCAN_LIMIT
- DRIVE9_RESULT_ABORTED
- DRIVE9_RESULT_IO

错误绝不会包含凭据或授权标头。

安全模型

- 工作区凭据和证据凭据必须不同，并且按路径限定范围。
- 证据没有路径、列表、挂载或文件系统目标 API。
- 定位符是随机能力，但仅凭持有并不获得授权。
- 带版本的签发回执、不可变清单和外围 Harness 工具事件必须在会话、工具名称、
调用 ID、定位符和清单摘要上保持一致。
- 当前会话以及显式播种的直接父级证据可读；同级和未播种的产物不可读。
- 从集成的角度来看，V1 是仅追加的。请为证据根目录配置 Drive9 保留策略或
管理性 GC。

参见 SECURITY.md 和完整的 V1 设计锁定。

限制

V1 有意不提供：

- shell、进程沙箱、终端或语言服务器；
- 自动挂载 Drive9；
- 通过 WebDAV 实现强子进程写后读；
- 对任一致性配置提供本地覆盖层支持；
- LayerFS 检查点或工作区回滚；
- 源流式或崩溃可恢复的工具捕获；
- 外部工具副作用的恰好一次语义；
- 证据枚举。

原生 Harness 溢出策略接收完全物化的工具结果。存储在引用之前即持久化，但在 V1 中工具输出不会在源头流式写入 Drive9。

开发

npm ci
npm run check
npm test
npm run test:race
npm run build
npm pack --dry-run

默认测试套件包含一个脚本化的真实 Harness 智能体循环：模型使用原生文件系统工具，/bin/cat 读取相同的已挂载字节，一个超大结果被溢出，随后的模型步骤调用 result_search 和 result_read。

对于使用 drive9 mount --mode=fuse --profile=none 创建的真实 Drive9 服务和 Linux FUSE 挂载：

DRIVE9_REAL_E2E=1 npm run test:real

所需的环境和清理行为记录在 docs/operations.md 中。发布检查清单见 CONTRIBUTING.md。真实测试会拒绝非 Linux 和非 FUSE 挂载根。

兼容性

| 组件或配置 | 支持的契约 |
| --- | --- |
| Node.js | 22.19 或更高版本 |
| DeepSeek Harness | 0.1.0-rc.6 |
| Drive9 JavaScript SDK | 0.1.4 |
| strong | Linux Drive9 FUSE；写入会等待进程可见的精确字节。当前真实服务验证观察到 SDK 到挂载的收敛时间为 1.3–1.5 秒，挂载关闭到新 SDK 修订版的收敛时间为 0.36–0.40 秒。这些观察结果并非 SLA。 |
| eventual | WebDAV；不保证子进程写后读，观察到陈旧数据超过 30 秒。 |

DeepSeek Harness 是开发者预览版。上游服务契约的变更需要发布新包并进行契约审查。