dsh-llm-agent-virtualization

English | 中文

本包把本地安装的 CLI Agent 注册为 DeepSeek Harness 可选模型，提供方 id 为 agent-virtualization。它实现正常 LLM seam；既不是工具插件，也不是 subagent 提供方。

职责明确拆分在两个仓库中：

• agent-virtualization 是与宿主无关的 CLI Agent 运行时、沙箱、能力网关和模型提供方协议。
• 本包只负责该协议的 DeepSeek Harness adapter。

安装

pnpm add dsh-llm-agent-virtualization

agent-virtualization 是直接运行时依赖，因此 adapter 安装后已经包含 bridge CLI；DeepSeek Harness 只需提供 adapter 面向 Harness 的 peer dependency。

DeepSeek Harness 拥有外层执行链：

User input → Inbox → Agent Loop → assemble Context/Tools → LLM
           → Tool Scheduler → Tool Result → Session → next Step → Turn completion

在 LLM 节点，本 adapter 启动 agent-virtualization model，由后者持有一个原生 CLI Agent loop。CLI 请求工具时，该进程暂停，请求转化为普通 DSH tool-call 响应。DSH Tool Scheduler 执行并记录工具，下一 DSH Step 再把匹配的 tool-result 返回同一进程。CLI 最终回答成为当前 DSH Turn 的模型输出。

配置

在 DeepSeek Harness 项目中添加依赖后，需要在 Cordis patch 或 bundle 中把它挂载为 LLM Provider：

- id: llm-agent-virtualization
  name: dsh-llm-agent-virtualization

这就是完整的默认配置，会注册两个可选模型：

• agent-virtualization/local-codex：使用 PATH 中的 codex 命令。
• agent-virtualization/local-claude-code：使用 PATH 中的 claude 命令。

选择前需要安装并登录相应 CLI。两个运行时 JSON 预设由本包直接携带，不需要额外克隆仓库，也不需要填写绝对 configPath。

只有需要替换默认模型目录时才配置 models：

- id: llm-agent-virtualization
  name: dsh-llm-agent-virtualization
  config:
    graceMs: 5000
    models:
      - id: codex-work
        name: Codex Work
        preset: codex
        contextWindow: 200000
      - id: claude-work
        name: Claude Code Work
        preset: claude-code
      - id: custom-cli
        configPath: /absolute/path/to/custom-agent-virtualization.json

模型选择使用 provider: agent-virtualization 和对应模型 id。models 是精确的替换 catalog：未知 id 以 UNKNOWN_MODEL 失败。每个自定义模型至少要填写 preset 或 configPath 之一；两者同时存在时以 configPath 为准，Web Models 页面据此在保留 preset 行的同时覆盖其路径。由于该页面会把解析后的包内路径持久化，preset 行的路径若已不存在会重新解析其 preset 而非直接失败；没有 preset 的行则原样保留路径。自定义配置文件可选择原生 CLI runtime、sandbox、timeout、环境变量白名单和 audit sink。

内置目录会作为设置的 base 层发布，因此未做任何配置的安装在 Web Models 页面上也能看到本地 CLI Agent；页面只渲染设置段，不读取实时模型目录。

内置目录只列出本机已安装的 CLI Agent，解析走的是与 bridge 启动进程相同的 PATHEXT 感知查找，因此不会把不存在的 CLI 作为可选模型暴露出来。探测发生在配置解析时，所以 DSH 运行期间新装的 CLI 需要下一次设置变更或重启后才出现。显式配置的 models 目录则原样保留——不会丢弃用户明确要求的条目，缺失的 CLI 由 bridge 自己报错。

adapter 默认使用当前 Node 启动直接依赖中安装的 agent-virtualization CLI。command 与 args 仍可作为高级覆盖项，并位于 adapter 自己追加的 model --config <configPath> 之前。env 在 subprocess seam 的净化环境之上添加显式子进程变量。graceMs 限制优雅终止进程树的窗口，maxProtocolLineBytes 限制不受信 stdout frame，stderrMaxBytes 限制 stderr 捕获。

活动 Agent session 的 cwd 会作为 workspace 发送给 Agent Virtualization。config.cwd 是没有发起 Agent 的直接 LLM 调用的回退；可调用工具的模型请求若既无 session workspace 又无回退，会默认拒绝。

执行语义

adapter 把 DSH system prompt 和当前消息历史序列化为确定性的模型 Step 任务，并把恰好 GenerateOptions.tools 投影到 bridge。独立包用这些投影工具替换配置中的可见 capability 集合，并为该次运行关闭 capability escalation。

CLI 请求工具时，adapter 发出正常 block-start、tool-call-delta、block-end 和 finish {kind: 'tool-calls'} chunk。它不执行工具。DSH 记录 assistant 工具调用、调度工具并记录结果期间，bridge 按 sessionId 和 request purpose 保持存活。下一 LLM Step 中，adapter 找到匹配的已记录 tool-result，向 bridge stdin 写入 tool.result，并恢复同一原生 loop。

model.result 结束逻辑模型调用并关闭整个 CLI 进程树。Abort、协议失败、缺失结果、provider dispose，或待处理工具调用期间切换模型，也会终止进程树并等待退出。已完成 DSH Turn 不会残留 CLI bridge。

协议边界

adapter 和独立包使用 agent-virtualization/model-provider/v1，它是带大小限制的 NDJSON stdio 协议，包含 model.run、tool.call、tool.result、model.event、model.result、model.error 和 model.cancel。一个进程接受一个 model.run，完成前可以进行多次宿主工具往返。

bridge stdout 被视为不受信协议输入。adapter 会校验消息所有权与形状，限制完整行和残缺行大小，独立捕获有界 stderr，使用共享 subprocess seam 的净化环境和可执行文件解析，并通过 subprocess 进程树生命周期终止后代进程。

模型体验

CLI Agent 请求

模型看到的内容

CLI Agent 会收到两条稳定 adapter 指令以及已组装的 DSH system prompt 和 conversation：Complete the following model step inside the DeepSeek Harness Agent Loop. 与 Use only the supplied Action Space. Tool calls return to DeepSeek Harness for scheduling, execution, and session recording.。bridge 还会单独暴露当前 DSH tool 的精确名称、描述、输入 schema 和发起 workspace。

Token 影响

原生 CLI 决定 tokenization 和上游模型调用。序列化后的 DSH 历史与 tool schema 会贡献输入；CLI 私有上下文处理可能增加 DSH 无法计量的 token。

KV Cache 影响

同一 CLI 进程会跨 DSH 工具 Step 存活，因此 CLI 可以在恢复期间保留内部上下文和提供方 cache。完成或失败会关闭进程；后续 DSH Turn 会启动新 bridge，adapter 不保证跨 Turn KV 连续性。

CLI Agent 响应

模型看到的内容

宿主工具结果只会在 DSH scheduler 执行并由 Session 记录后返回。文本与推理事件通过普通 LLM chunk 流式传递；CLI 工具意图成为普通 DSH tool call，最终结果完成当前 DSH 模型 Step。

Token 影响

只有 DSH Agent Loop 保留的响应 block 会进入之后组装的 DSH context。adapter 当前不发出 usage chunk，因此 CLI 私有 input、output、cache-read 和 cache-write token 不进入 DSH usage 统计。

KV Cache 影响

工具结果恢复既有 CLI 进程，并可以扩展其私有可缓存前缀。外层 DSH context 仍在每个 Step 根据 Session event 独立重建。

已知限制与暂缓事项

• 公布的输入 modality 只有文本——image block 在序列化任务中表现为 attachment 引用；bridge 协议尚未实现二进制附件传输。
• 没有提供方 usage 统计——原生 CLI token 和 cache 指标尚未归一化为 DSH usage chunk。
• 不跨 Turn 复用 bridge——一个 CLI 进程属于一个逻辑 DSH Turn／模型运行，并在完成时关闭。
• 运行时配置绑定进程——修改自定义 configPath 文件后，新启动的 CLI 进程会使用新配置；已经暂停等待工具结果的进程继续使用启动时的配置。
• 工具结果展平为文本——恢复 CLI 前，DSH result block 会渲染为字符串；结构化 result-block 保真暂缓实现。
• 待处理工具调用需要 sessionId——没有持久 session 的直接 LLM 消费方可以使用最终文本调用，但无法暂停和恢复 CLI 工具往返。
• Windows preset 不强制沙箱——Agent Virtualization 在 Windows 上没有强隔离后端，因此内置 preset 在该平台解析为 *.windows.json 变体，其 requireEnforcement 为 false；除该开关外与其他平台的 preset 完全一致，运行会以 enforcement: "none" 上报。需要强制隔离时请在容器或 VM 中运行 DSH，或提供自定义 configPath。

开发

pnpm install
pnpm run check
AGENT_VIRTUALIZATION_ROOT=../agent-virtualization pnpm run test:integration