GGyHackPERSONAL JOURNAL · EST.2026
笔记 · JOURNAL

deepseek-harness-产品介绍

2026-08-14·479 阅读· 约 37 分钟DeepSeek

DeepSeek Harness 深度产品介绍：一切皆插件的开源 Agent 框架

项目地址：https://github.com/deepseek-ai/deepseek-harness
当前版本：0.1.0-rc.5（开发者预览，快速迭代中）
许可证：MIT
一句话：由 DeepSeek AI 开源的 Agent Harness（智能体运行框架），以「一切皆插件」为架构信条，基于自研插件框架 Cordis，目标是成为可组合、可替换、可审计的通用智能体执行引擎。

一、什么是 Agent Harness

「Harness」本义是"挽具、线束"——在 Agent 领域，它指的是承载智能体运行的那套外围系统：模型调用、工具执行、上下文管理、权限控制、持久化、多智能体协作……这些与"模型本身"正交的工程问题。

打个比方：大模型是发动机，Harness 就是整车——底盘、转向、刹车、仪表盘、油路。DeepSeek Harness（CLI 名 dsh）解决的就是"怎么让一个 LLM 可靠、安全、可扩展地完成真实任务"这件事。它默认内置了编码智能体需要的一切：文件读写编辑、Shell 执行、代码检索、子代理委派、后台任务、计划模式，等等，并且每一块都可以被替换。

与市面上常见的"Agent 框架"（如 LangChain 式的编排库）不同，Harness 更接近 Claude Code / Claude Cowork 这类产品级智能体运行时：它自带完整的 Web UI、无头 CLI、Python SDK 和 ACP 协议服务，开箱即用，同时又把每一层都做成了可插拔的插件，供深度定制。

二、发布背景：为什么值得关注

  • 2026 年 8 月中旬开源公测（仓库首个提交为 2026 年 6 月 10 日，短短两个多月积累了上万次提交），同期 DeepSeek 在 API 上发布了 V4-Pro 并调整了价格，Harness 被视为 DeepSeek 在智能体基础设施层面的一次布局。国内媒体普遍将其定位为对标 Claude Cowork / Claude Code 的开源竞品（IT之家报道、智东西实测、36氪解读、VentureBeat）。
  • 开发者预览阶段（Developer Preview）：官方明确警告「未来将出现破坏兼容性的变更」，版本号停留在 0.1.0-rc.x，正处于快速迭代期。刚完成 npm 公开发布（commit feat/npm-public），任何用户都能通过 npx @deepseek-ai/dsh web 一行命令体验。
  • 技术路线独特：它没有另起炉灶造轮子，而是深度绑定自研插件框架 Cordis（同样开源），其设计有配套论文《A Programming Paradigm for Spatiotemporal Composability》。这使它在一众"用 Python 编排 prompt 循环"的框架中显得相当"工程化"——事件溯源、作用域、可逆副作用，这些偏系统软件的概念被系统地用在了 Agent 运行时上。

三、核心理念：一切皆插件（Cordis）

"Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so every part is replaceable from configuration."
—— 官方架构文档

这是整个项目最重要的一句话。模型适配器、工具注册表、会话日志、甚至 Agent 主循环本身，全部是插件。没有"特权核心"需要你去打补丁；扩展 dsh 的方式就是"在它旁边再挂一个插件"。

Cordis 用五个概念支撑这一切：

概念含义
插件（Plugin）一个实现 Service 的对象：可以是函数形式（导出 name + apply(ctx)），也可以是对象或类形式
上下文（Context）服务的仓库。服务以 ctx.<key> 注册，如 ctx.tools、ctx.llm、ctx.sessions，其他插件通过 key 找到服务，而不是 import 具体实现
依赖注入（inject）插件声明自己需要哪些服务，框架会等这些服务就绪后才加载插件，加载顺序由依赖关系表达，而非手工编排
类型化事件（Typed Events）通过 TypeScript 声明合并扩展事件名，并以 emit / waterfall / parallel / serial 四种模式分发
可逆注册（Reversible effects）一切注册（prompt 片段、工具 schema、适配器、监听器）都是"副作用"，插件卸载时自动撤销，重启、热重载都能干净地回滚

事件分发的四种模式决定了插件的协作方式：

模式是否等待分发顺序有返回值？
emit否按注册顺序观察无
waterfall否按注册顺序观察有（可短路/包装）
parallel是全部并行无
serial是按注册顺序有

其中 waterfall 是"环绕中间件"语义：监听器收到 (...args, next)，调用 next() 把（可能被包装的）结果传给下一个；不调用 next() 直接返回即短路。策略类监听器（如权限门禁）通过短路做决策，观察类监听器则必须让权给下游——这是 Harness 中所有拦截点的统一契约。

四、系统架构：Profile、Bundle 与分层补丁

一个运行中的 dsh 是一棵在启动时按有序分层组合出来的插件树。三个核心概念：

  • Profile（配置档）：存放在 Harness 主目录（$DSH_HOME/profiles/<name>）下的命名组合，列出它堆叠的 bundles、安装的第三方插件，以及用户自己的 cordis.patch.yml。web 和 headless 是官方内置的两个模板。
  • Bundle（包）：Cordis 配置行 + 代码的分发格式。dsh-base（模型适配器、工具、持久化、沙箱、审批、设置、凭据、遥测）是每个 Profile 的第一层；dsh-web-app 加上浏览器应用；dsh-headless 加上"无服务器的一次性运行器"。
  • Patch（补丁层）：按 id 定位配置行并整体替换，或插入新行。合并顺序是：每个 bundle 的补丁（按 Profile 声明顺序）→ Profile 的 cordis.patch.yml → 主目录级 $DSH_HOME/cordis.patch.yml → --patch 命令行覆盖。

你可以随时查看自己机器上实际启动的完整配置树：

dsh --profile web --dump-config

打印出的每一行，都可以用你自己的补丁替换掉。这意味着你不需要 fork 项目，就能替换掉任何一个内置能力——这是"一切皆插件"在部署层面的兑现。

核心包一览（每个包都对应 ctx 上的一个服务 key）：

包负责ctx key
core/session追加式 SessionEvent 日志与内存存储ctx.sessions
core/system-promptPrompt 分节与工具 schema 组装ctx.systemPrompt
core/tools作用域化工具注册表与受守卫的执行管线ctx.tools
core/agentAgent 接口、活跃注册表、agent/* 事件ctx.agents
core/agent-loop实现该接口的默认驱动（主循环）ctx.agentLoop
core/scope每 Agent 作用域注册原语纯库
llm/llm消息/流词汇 + 适配器接缝ctx.llm

五、核心运行模型：Step / Turn 与事件溯源会话日志

5.1 Step 与 Turn

  • Step（步）：一次模型请求 + 它调用的工具。
  • Turn（轮）：零个或多个 Step。它在第一个输入被认领前开启，在"没有欠账"时关闭。

一个典型回合的时序（官方架构文档）：

turn/start
  claim next-step input plus one queued message
  assemble prompt sections + tool schemas
  -> agent/pre-step                   reject | enter(messages)
     step/start
     append entered messages as user/message
     derive model history from the log
     agent/request -> llm/stream -> assistant/chunk* -> assistant/message
     tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*
     step/end
     tools owe another request, or next-step input arrived -> claim -> next step
  -> agent/turn-stopping
turn/end

这里的关键是事件按域分三层：

  • 会话事件（Session events）：turn/*、step/*、user/message、assistant/*、tool/*——持久化事实，追加到日志并广播，重启后仍然存在。
  • Agent 事件（agent/*）：携带活的 Agent 对象（inbox、step、status、request、validation、continuation）——用于观察或拦截进行中的工作。
  • 能力事件（Capability events）：把策略和适配器挂到接缝上（fs/*、tools/*、telemetry/*），不依赖主循环。

5.2 会话日志：事件溯源（Event Sourcing）

这是 Harness 最"硬核"的设计之一：

"模型能看到的一切，都必须被记录"（Model-visible means logged）——任何到达模型请求的内容都必须能从日志重建，且有运行时不变式强制检查。

会话日志是追加式的 SessionEvent 流，是唯一事实来源。模型看到的上下文由 deriveMessages() 从日志推导出来，而不是单独存一份对话历史。这带来一个连锁收益：Fork（分叉）、恢复、转录、遥测、持久化，全都从这一条流派生。原始 assistant/chunk 事件还保留了回放保真度，UI 可以逐块重放。

也正因如此，要新增一个"模型可见"的输入，就必须新增一种会话事件类型（通过 TypeScript 声明合并扩展 SessionEventMap），并让渲染从日志出发——这从类型层面杜绝了"prompt 里塞了日志里没有的东西"这种 Agent 系统常见的数据腐化问题。

5.3 能力接缝（Capability Seam）

Seam（接缝）是可替换能力的三件套：Service Definition（接口定义）→ Service Provider（实现）→ Consumer（消费方，通常是模型可见的工具）。

接缝是"换一个 Provider 就改变整个产品"的原因：文件系统与子进程 Provider 共享同一个执行世界，把它们指向远程沙箱（如 E2B），Bash、PTY、LSP 会一起迁移过去，不需要为每个消费者写分支。子代理 Provider 也一样——同一个接口背后，可以是全新子代理、进程内委派轮次，甚至是另一个产品里的代理。

六、快速上手：五种运行方式

方式一：一行命令启动 Web UI（推荐先试这个）

npx @deepseek-ai/dsh web

需要先安装 Node.js（22.19+ 或 24+）。命令启动 Web UI，默认地址 http://127.0.0.1:3080。

方式二：从源码运行

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

方式三：Headless 一次性任务（无服务器、适合 CI）

# 环境变量：DEEPSEEK_API_KEY=sk-…（可选 DEEPSEEK_BASE_URL 指向 OpenAI 兼容代理）
dsh --profile headless "fix the failing test in this workspace"

它接受一个任务、创建并持久化一个新会话、打印最终回答、退出。无头模式还支持 --stream-json 等机器可读输出，非常适合做自动化与基准测试。

方式四：Python SDK

pip install deepseek-harness-sdk   # 自带捆绑运行时，无需系统 Node.js

详见第十一章。

方式五：ACP 自动化服务器

examples/acp-agent 提供了 Agent Client Protocol 实现，任何 ACP 客户端都可以编程式地驱动 dsh 会话，支持权限与取消。MCP（Model Context Protocol）客户端也内置（examples/mcp-memory 展示了如何接入第三方记忆服务器）。

七、Web UI 使用指南

启动后（dsh 进程把调用目录当作默认文件系统位置），按三步开始：

  1. 配置模型：打开 Settings → Models，填入 DeepSeek API Key 并保存——无需重启服务器，模型路由立即可用。也可以添加 Anthropic、OpenAI 等目录内厂商，或自定义 OpenAI 兼容端点（如公司网关、自建服务）。凭据是"只写"的：页面保存后只显示脱敏描述，密钥存放在 $DSH_HOME/.credentials.yaml。
  2. 选择工作区：点击 Choose workspace，添加并选中你启动 dsh 的项目目录。未选择工作区前，会话输入框不可用。
  3. 运行任务：新建会话，发送例如"总结这个仓库并识别其主要包"。Agent 可以读写工作区文件、执行命令、委派子代理、维护计划（todo 清单）；遇到需要审批的操作时，Web UI 会按当前权限策略弹窗询问。

UI 的亮点在于工具卡片（Tool Card）渲染：Shell 命令显示为终端卡片，文件写入/编辑显示为内联 diff 卡片，搜索显示为按文件分组的匹配卡片——这些卡片是纯函数式的展示投影（presentCall / presentResult），在实时流和日志回放时都能稳定重现。

八、功能全景：内置工具与能力

官方维护了一份自动生成的工具 Schema 目录（启动每个工具插件实测读取 ctx.tools.schemas()，缺一个工具都会让文档校验失败），以下是内置工具的完整版图：

能力域模型可见工具说明
文件系统read、write、edit、read_image、str_replace_editor读写前先观察（read-before-write 策略），编辑带 diff 卡片
搜索glob、grep打包自带 ripgrep 二进制，无宿主依赖；超量结果走 spill 落盘
Shellbash、pwsh、bash（持久终端）bash 每次调用全新进程；持久终端保留 cwd/环境变量/函数；Windows 用 pwsh
终端terminal_open/read/send/signal/close/list可选的持久 PTY 六件套
子代理subagent、subagent_fork、send_message、interrupt_agent、list_agents、report委派、并行、可续接子代理与全局控制工具
后台任务job_kill、job_list、job_output通用后台任务运行时：后台 bash、PTY 发送、子代理统一管理
规划exit_plan_mode、todo_write计划模式（先出方案、用户审批后执行）与任务清单
代码执行run_codeCode Mode：把全部工具以类型化 API 暴露给一段 TS 程序
工作流workflow、ralph脚本化多代理编排；Ralph = 每轮全新子代理的迭代循环
目标管理create_goal、get_goal、update_goal会话内长期目标的创建/查询/更新
技能skill按需加载技能目录（Skill）到上下文中
会话查询session_event_read/search/trace、session_search/trace只读查询会话日志
编程辅助lsp语言服务器协议：跳转定义、引用、语义信息
网络web_search、web_fetchProvider 可替换的搜索与抓取
人机交互ask_user_question工具执行中暂停，向 UI 提问并等待人类回答
定时schedule_create/delete/list会话内持久提醒（可选覆盖层）
自指cordis_* 七件套可选：Agent 可以检查并修改自己的 Cordis 插件树（web-cordis 示例）

值得一提的进阶能力

  • Code Mode（run_code）：让模型把一次复杂的多工具操作写成一个 TypeScript 程序，通过 await tools.<name>(args) 以精确类型化的方式调用所有可见工具，调用重新进入完整守卫管线，并支持 maxParallelSubCalls 并发。程序返回值直接作为规范化 JSON 结果，而不是让人去解析散文。
  • 多模型路由：DeepSeek、Anthropic、OpenAI、Bedrock（AWS）、Vertex（GCP）、Azure、Codex（OAuth）以及任意 OpenAI 兼容端点；支持按模型声明 input: [text, image] 的模态能力，视觉模型可以读图。
  • Agent Presets：部署可以预置"能力集"（哪些工具、哪些 prompt 分节），会话按 preset 组装；子代理通过 composeFrom 继承父代理的同一代组合。
  • 遥测与可观测性：OTel 导出、token 计量（token-meter）、会话遥测（session-telemetry）、运行时诊断。
  • 远程沙箱 POC：examples/headless-agent/e2b.cordis.yml 用 E2B 替换本地文件系统与子进程 Provider，让 FS/Bash/PTY/LSP 全部跑在远端一个沙箱里——接缝架构的直接演示。

九、安全模型：沙箱、审批与密钥

9.1 三级文件沙箱

SandboxMode 只约束文件系统副作用，按每次调用解析（每次调用都可能不同，支持单次放行的提权重试）：

模式含义
read-only拒绝写入（POSIX 运行器额外放行 shell 必需的 /dev/null）
workspace-write允许写工作区根目录 + 后端承诺的临时区
danger-full-access完全不做约束（消费者直接绕过 ctx.sandbox 用原始 argv 启动）

底层实现按平台分：Linux 用 bwrap/Landlock，macOS 用 Seatbelt，Windows 用 ACL restricted-token。执行器还会上报强制程度是 full 还是 partial（如旧 Landlock ABI、Windows ACL 的 Everyone/硬链接边界），要求绝对边界的使用方必须拒绝 partial。

9.2 审批（Approval）与权限策略

  • 会话级策略：ask（默认，弹窗询问人类）/ never（确定性拒绝，用于 CI 和无值守）。
  • 结果闭合且 fail-closed：allowed-once（只放行被询问的那一次动作）/ rejected / cancelled / unavailable（应答方缺失、不归属、抛错或不合规时自动视为拒绝）。
  • 每条审批请求都带独立 ApprovalRequestId，配对 approval/asked 与 approval/decided 两条审计事件，写入会话日志。

9.3 密钥管理

API Key 写入 $DSH_HOME/.credentials.yaml，设置项只保存凭据引用，Web 页面永远拿不到明文。也支持 apiKeyEnv 从环境变量取。

十、代码示例：从零写一个插件

10.1 第一个插件：最小可运行

插件就是一个导出 apply 函数的 TypeScript 模块：

// scratch-plugin/src/my-plugin.ts
import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  // 依赖的服务在 apply 执行前就绪
  console.log('[hello-plugin] plugin loaded!')
}

用一个 cordis.yml 补丁把它插进 Web 树的配置行里（路径必须绝对）：

# scratch-plugin/cordis.yml
- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

启动：

pnpm dsh web --patch ./scratch-plugin/cordis.yml

打开 http://127.0.0.1:3080，终端会打印 [hello-plugin] plugin loaded!。

自动清理：通过 ctx 注册的一切（事件监听器、工具、定时器）在插件卸载时自动撤销，无需手动 removeListener；需要显式清理的资源用 ctx.effect() 返回 disposer：

export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => console.log('heartbeat'), 5000)
    return () => clearInterval(timer)   // 插件卸载时执行
  })
}

10.2 加一个工具：greet

工具是模型直接看到、直接调用的能力，用 defineTool DSL 定义（官方教程的完整示例）：

// scratch-plugin/src/my-plugin.ts
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'greet-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: { type: 'string', required: true, description: 'The name to greet' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    },
  }))
}

要点：

  • inject: ['tools'] 让 Cordis 等到工具注册表就绪再加载插件；
  • parameters 即模型的 JSON-Schema 参数说明，defineTool 会自动校验模型生成的参数并推导出类型化 args；
  • execute 返回 output.schema 声明的规范化值；output.render 把它转成模型可见的内容；
  • 注册即副作用：插件卸载时工具自动注销，schema 自动汇入系统提示词组装。

在 UI 里问一句 "Use the greet tool to greet Ada."，模型就会调用 greet 并收到 Hello, Ada!。

10.3 带配置的插件

任何"两个部署可能想设成不同值"的东西都应该是配置字段：

import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'

export const name = 'my-plugin'

export interface Config {
  greeting: string
  maxRetries: number
  verbose?: boolean
}

export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  maxRetries: Schema.number().default(3),
  verbose: Schema.boolean().default(false),
})

export function apply(ctx: Context, config: Config) {
  console.log(config.greeting)  // 用户值或 schema 默认值
}

# cordis.yml
- insert:
    - id: hello
      name: './src/my-plugin.ts'
      config:
        greeting: 'Hi there'
        maxRetries: 5

配置在加载时经 Schemastery 校验，非法配置会让加载失败并给出可操作的错误。

10.4 真实生产代码：ask_user_question

仓库里 packages/interaction/tool-ask-user 是一个真实上线的工具插件（完整源码约 100 行），它演示了一个"能力接缝的 Consumer"长什么样——调用 ctx.userQuestions 服务、暂停等人类回答、再以普通工具结果喂回主循环：

export function apply(ctx: Context): void {
  ctx.tools.register(defineTool({
    name: 'ask_user_question',
    description,
    parameters: {
      questions: {
        type: 'array', required: true,
        description: 'Questions to ask the user before continuing.',
        items: { type: 'object', additionalProperties: true, /* … */ },
      },
    },
    output: {
      schema: {
        type: 'object', additionalProperties: false,
        properties: { answers: { type: 'array', required: true, items: { /* … */ } } },
      },
      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
    },
    async execute(args, exec) {
      const result = await ctx.userQuestions.ask({
        questions: args.questions.map(q => ({ id: q.id, question: q.question, /* … */ })),
        ...exec.agent !== undefined ? { agent: exec.agent } : {},
        signal: exec.signal,          // 取消信号：主循环取消时中止在途工作
      })
      return {
        answers: result.answers.map(a => ({ id: a.id, selected: [...a.selected], /* … */ })),
      }
    },
  }))
}

这段代码展示了工具契约的核心规则：参数由 schema 校验、输出是单一规范化 JSON 值、尊重 exec.signal 取消、抛出或非法返回值一律按 isError 处理。

十一、Python SDK：把 Harness 嵌进自己的程序

如果你不想用 UI，想在自己的 Python 程序里驱动一个完整编码智能体：

from pathlib import Path
from deepseek_harness import DeepSeekHarness

config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions = Path("/absolute/path/to/sessions").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-v4-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    session_root=str(sessions),
    cordis=str(config),
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

几个值得注意的设计：

  • SDK 自带捆绑的运行时（无需系统 Node.js），懒启动并在上下文管理器退出前复用；
  • 复用同一 session id 会保留会话属主的持久 Bash 进程（包括工作目录、导出变量、shell 函数）——同一会话继续对话，新任务用新 id；
  • 会话目录会落一份 JSONL 日志，包含完整的模型请求与工具调用，可审计、可回放；
  • 官方示例组合刻意保持极简：只有持久 bash 和 str_replace_editor 两个工具，其余全部关闭——你可以从这份"最小组合"出发按需叠加。
  • 注意：该组合使用 danger-full-access 且 PTY 需要 POSIX 终端基座，不支持 Windows 上的 agent（Windows 上请用 Web/CLI 的 pwsh 组合）。

十二、面向开发者的工程细节

12.1 仓库结构（Monorepo）

apps/          # 产品入口：cli（dsh 命令）、web（Web 壳）
packages/      # 60+ 包：core（session/tools/agent/agent-loop…）、llm、
               # fs、shell、sandbox、subagent、jobs、goal、workflow、
               # skill、plan、acp、mcp、lsp、terminal、web、settings、
               # credentials、persistence、compaction、spill、typert…
examples/      # 可运行演示：headless-agent、jsonrpc-agent、web-cordis、
               # web-schedule、acp-agent、mcp-memory
python/        # Python SDK（deepseek-harness-sdk）
native/        # 原生组件
website/       # 文档站点
vendor/        # 内置的 Cordis 框架源码

12.2 构建与开发

  • Node.js 22.19+ / 24+，Corepack 管理的 pnpm（仓库锁定 pnpm@11.7.0）；
  • 构建：pnpm install → pnpm run build（tsc 分 Host/Client 两个聚合程序 → tsdown 打包 → Web 构建）；
  • 校验：pnpm run typecheck、pnpm run hygiene（含 publint 校验包入口）；
  • 文档体系惊人地完整：架构文档、子系统文档（每个子系统一页，含从源码自动生成的 Cordis API 目录）、工具 schema 目录（自动生成且校验）、Cordis 教程、扩展 Cookbook、事故复盘（postmortem）——连"翻译配对合并"这种工程细节都有 Agent Note 记录。仓库里还沉淀了大量 .agents/notes/ 设计决策笔记。
  • 面向 agent 开发：仓库自带 AGENTS.md / CLAUDE.md，官方鼓励用 agent 探索代码库理解架构（本项目自己就是在这样开发自己）。

12.3 贡献与社区

  • GitHub Discussions 提交反馈/报 bug；
  • 插件仓库打上 dsh-plugin 话题便于被发现；
  • Discord 社区 + 国内企微群/微信公众号（README 有二维码）。

十三、局限与注意事项

  1. 仍是开发者预览：0.1.0-rc.x，官方明示"破坏兼容性的变更"会来。生产环境大规模依赖前请评估。
  2. 补丁是整行替换，没有深合并：Profile 覆盖一个配置行必须重述该行保留的每个字段，容易踩坑（dsh-base README 明确列为已知局限）。
  3. 沙箱强制程度分平台：Windows ACL 与旧 Landlock ABI 是 partial 强制，需要绝对边界的使用方要显式处理。
  4. Windows 体验不对称：bash 工具在 win32 上默认禁用，改用 pwsh 组合；Python SDK 的 PTY 组合不支持 Windows agent。
  5. 学习曲线陡峭：事件溯源、作用域、接缝、四种事件分发模式……这些概念对"想写个脚本调模型"的用户偏重；它是为工程化构建 Agent 产品而生的，不是给 prompt 工程师的玩具。
  6. 资源占用：作为完整产品运行时（含 Web UI），比一个纯 Python 编排库重；无头模式适合轻量场景。

十四、总结：适合谁、为什么值得关注

适合：

  • 想深度定制编码智能体的团队（换模型、换工具、换沙箱、接自己的审批流）；
  • 想把 Agent 能力嵌进自己产品的开发者（Python SDK / ACP / JSON-RPC）；
  • 对"事件溯源 + 插件化运行时"这类系统级 Agent 架构感兴趣的研究者；
  • 想给 DeepSeek 生态做插件的第三方开发者（官方在推 dsh-plugin 话题生态）。

暂时不适合：只想要一个开箱即用聊天工具、或对 API 稳定性要求极高的生产环境。

为什么值得关注：DeepSeek 不只是在开源一个"又一个 Agent 框架"，而是在开源他们自己产品背后的运行时。当一家头部模型厂商把模型适配器、主循环、沙箱全部插件化并公开，生态位就变了——你可以用同一套骨架，把 DeepSeek 换成任何模型，把本地沙箱换成云端沙箱，把默认 UI 换成你自己的界面，而中间层（会话日志、审批、子代理、审计）一分不用动。npx @deepseek-ai/dsh web 一分钟就能体验；--dump-config 能看清它的每一根骨头。对于想认真做 Agent 工程的人，这值得放进观察清单。

参考链接