摘要:dsh 是面向 Agent 开发者的本地运行时环境,并非传统 CLI 工具。它提供结构化任务调度、跨插件状态共享内存和统一 CLI 协议,插件分层为三层:基础能力层(如 context、llm-router)、领域适配层(如 code-diagnostic、zotero-sync)、交互增强层(如 web-ui、cursor-pro)。 本文基于 2026-11-11 发布的公开文档与实机验证整理。

1. dsh 不是 CLI 工具:定位先讲清

多数人第一次看到 DeepSeek Harness(下称 dsh),第一反应是“又一个命令行小工具”,装完就能敲命令。这个误判几乎是后续所有问题的起点。

dsh 的实质是面向 Agent 开发的本地运行时环境(Local Runtime for Agent Development)。它不提供“功能”,它提供“能力容器”:你装的每个插件都不是独立进程,而是被注入 dsh 统一上下文的可执行单元。这个上下文自带三样东西:

  • 结构化任务调度器
  • 跨插件状态共享内存
  • 统一 CLI 入口协议

反过来说,dsh 像一台微型操作系统架构,并非“工具集合”。你装的插件是它的驱动和系统服务。

这解释了热词里反复出现的两类提示:

dsh web authentication required; reopen the url printed by dsh web.

这不是登录失败,是 dsh 在启动 Web 交互层时主动触发的一次 OAuth2.0 授权流程,目的是把当前终端会话与你的个人配置空间(Profile)绑定。绑定的不只是 token,还承载插件间共享的 context state、默认模型路由策略、agent 调用链的 trace ID 生成规则。

另一类是加载期报错:

dsh plugin tree failed to load: failed to apply loader entry include

这从来不是插件本体坏了,而是 loader 在尝试把插件的 include 声明(比如引用某个 shared schema 或 config template)注入 runtime context 时,发现目标 profile 缺少对应依赖项。它不报 “missing module”,而报 “failed to apply loader entry”——因为 dsh 的 loader 在 runtime context 内部做符号解析,不在文件系统层面做路径查找。

给一个准确的定义:dsh 是 Agent 开发的最小可执行环境(MVE)。它的价值不在单个插件多强,而在让十个插件能像同一进程里的线程那样协同工作。它要解决的是“如何让多个 AI 功能模块在一次用户请求中自动协商、分工、传递中间结果”,而非“怎么调 API”。

harness 与 agent 的区别也该讲清:Harness 是 runtime,Agent 是 workload。

2. 安装路径只有一个

官方明确要求:

curl -sSL [https://install.deepseek.com/dsh.sh](https://install.deepseek.com/dsh.sh) | sh

不要用 `npm install -g dsh` 或 `pip install deepseek-harness`。 安装脚本会做三件事:校验系统 glibc 版本、检测 /usr/local/bin/dsh 符号链接是否存在、创建 ~/.dsh/profiles/default/ 目录结构。跳过这一步,后续约 80% 的插件加载失败都源于 profile 初始化不完整。

3. 插件生态的真实分层

社区流传的“dsh 插件市场”截图多半只展示扁平的图标墙:代码诊断、网页下载、Zotero 同步、Linux 文件操作。看起来像扩展商店。但实际使用中,有些插件装上就能用,有些必须搭配 profile 配置才生效,还有些根本无法独立启用。原因是 dsh 天然分三层,每层解决不同维度的问题。

层代表插件职责缺失后果
基础能力层context、llm-router状态序列化、模型路由与 fallback所有上层插件退化或直接失败
领域适配层code-diagnostic、zotero-sync、linux-cli、sql-assistant具体场景能力对应场景不可用,不影响其他层
交互增强层web-ui、cursor-pro、vscode-integration可视化、多 Tab、编辑器联动界面能力缺失,CLI 仍可用

3.1 dsh-plugin-context

负责管理全局 context state 的序列化与反序列化。它定义 context.json 的 schema,规定哪些字段可跨插件读写(如 user_intent、current_file_path、last_search_result),哪些字段仅限本插件作用域(如 code_linter_issues)。

没有它,所有插件状态彼此隔离。网页下载插件下完文件,代码诊断插件根本不知道该分析哪个文件。

3.2 dsh-plugin-llm-router

它不是调用某个具体模型,而是一套轻量级模型路由策略引擎。它读取 ~/.dsh/profiles/default/routing.yaml,按任务类型(code_generation、text_summarization、sql_query)自动选择最优模型 endpoint,并处理 fallback 逻辑。

实测结论:若禁用 `llm-router`,所有依赖 LLM 的插件都会退化成硬编码调用 [https://api.deepseek.com/v1/chat/completions](https://api.deepseek.com/v1/chat/completions),且无法响应 --model claude-3-haiku 这类参数。这也是插件市场页面底部那行小字的含义:“基础能力插件已预装,不可卸载”。

关键配置示例,至少配置一个 default 路由:

default:
  model: deepseek-coder-33b-instruct
  endpoint: [https://api.deepseek.com/v1/chat/completions](https://api.deepseek.com/v1/chat/completions)
  api_key: sk-xxxxxx
code_generation:
  model: claude-3-haiku
  endpoint: [https://api.anthropic.com/v1/messages](https://api.anthropic.com/v1/messages)
  api_key: $ANTHROPIC_API_KEY   # 支持环境变量

--force 参数是必需的,它会覆盖默认 profile 中的空 context schema。安装后应检查 ~/.dsh/profiles/default/context.schema.json 是否存在,且包含 "user_intent": {"type": "string"} 等核心字段。

排障技巧:dsh llm route --list 查看当前生效的路由表。若 code_generation 显示 disabled,说明该路由的 endpoint 无法连通。此时不要急着改配置,先运行 dsh llm route --health-check code_generation,它会返回具体的 connection timeout 或 SSL error。

这里有一个与多模型接入相关的工程点:路由表本身就是一层抽象,default 与 code_generation 可以指向不同厂商的端点。若团队已经把多个模型 endpoint 收敛到统一入口,路由表里只需要替换 base URL 与密钥变量,插件代码不必改动。TreeRouter 在这一环节充当的是统一接入层,让 routing.yaml 的每个分支指向同一套凭证与配额策略,减少多端点并发时的密钥分散问题。

版本依赖是高频坑:dsh code diagnose 一直报 “No file specified”,排查半小时后才发现是 dsh-plugin-context 版本为 v1.2.0,而 dsh-plugin-code-diagnostic 要求 v1.3.0+。dsh 不做 semver 自动升级,必须手动 dsh plugin update dsh-plugin-context。建议养成习惯:每次装新插件前,先跑 dsh plugin list --outdated。

3.3 dsh-plugin-web-ui

它的 dsh web 命令会触发 profile 初始化流程,生成 ~/.dsh/profiles/web/ 目录,并自动创建 web profile 的 context schema。这个过程会覆盖 default 的 schema 吗?不会。但前提是 context 与 llm-router 已经就绪。

安装后自测:创建 test.py:

def fetch_data():
    import requests
    return requests.get("[http://example.com](http://example.com)").json()

运行 dsh code diagnose --file test.py --line 2。正常返回结构应为:

{
  "severity": "error",
  "suggestion": "Use async HTTP client like httpx.AsyncClient for non-blocking I/O",
  "fix_code": "import httpx\nasync def fetch_data():\n    async with httpx.AsyncClient() as client:\n        ..."
}

若返回空或报错,90% 是 llm-router 的 default 路由未配置。原因是 code-diagnostic 的 prompt template 很长(>2000 tokens),需要模型支持大 context window。deepseek-coder-33b-instruct 是目前唯一被 fully tested 的模型,其他模型可能因 truncation 导致解析失败。

3.4 dsh-plugin-zotero-sync

Zotero 官方 CLI 只能导出 bibliography,无法做语义分析。此插件在同步 PDF 时自动调用 LLM 提取 research_question、methodology、key_findings,并存入 Zotero item 的 extra 字段,供后续 dsh research query 检索。

依赖关系明确:必须在 llm-router 配好 research 路由(指向适合长文本理解的模型,如 qwen2-72b-instruct),且 context 的 schema 中已定义 pdf_metadata 字段。

操作三步:

  1. dsh zotero login 绑定账号
  2. dsh zotero sync --collection "AI Papers"
  3. 在 Zotero Desktop 查看对应文献的 Extra 字段是否已填入结构化摘要

经验值:同步速度取决于 PDF 大小与 endpoint 延迟。建议为 research 路由设置 timeout: 120,并启用 streaming: false,因为 PDF 解析需要完整响应。

3.5 dsh-plugin-cursor-pro

它依赖 web-ui 提供的 SSE channel 接收 context state 更新事件。没有 web-ui,cursor-pro 只能显示静态 tab 列表,无法实时同步状态。

dsh cursor create --name "Backend Refactor"
dsh cursor switch "Backend Refactor"
dsh cursor list

真实场景是四个 Tab 并行:

  • Tab API Design:dsh openapi validate --file spec.yaml
  • Tab Frontend:dsh react suggest --component Header
  • Tab Infra:dsh terraform plan --dir ./infra
  • Tab Research:dsh research query "best practices for async logging in Python"

切换 Tab 时,每个插件的 current_working_dir 与 last_used_model 自动恢复,不必重复输入参数。

3.6 dsh-plugin-linux-cli

它不替代 bash,而是把 Linux CLI 封装成可组合的 agent action。例如 dsh linux run --command "find . -name '*.py' | xargs grep TODO" 会返回结构化结果 {"files": ["main.py", "utils.py"], "matches": 3},供上层插件消费。

dsh linux clear 会清空当前 terminal 的 scrollback buffer,但保留 runtime context。这比 clear 更安全,因为它不影响 cursor-pro 的 tab state。

linux.yaml 支持自定义 alias:

aliases:
  pycheck: "find . -name '*.py' -exec flake8 {} \;"

之后 dsh linux run --alias pycheck 即可执行。

3.7 dsh-plugin-vscode-integration

在 VS Code 中按 Ctrl+Shift+P → Dsh: Run Agent → 选择 Code Diagnostic,它会自动把当前 editor content 发给 code-diagnostic,并将结构化结果渲染为 CodeLens(在代码上方显示 Fix this)。

依赖 web-ui 的本地服务提供 WebSocket endpoint。安装后 VS Code 输出面板应显示 Dsh Integration: Connected to [http://localhost:8080/ws](http://localhost:8080/ws)。若报 “Connection refused”,先 dsh web 确保服务启动,再检查设置中 dsh.webUrl 是否为 [http://localhost:8080](http://localhost:8080)。不要用 `127.0.0.1`,某些 macOS 版本的 loopback 解析有问题。

3.8 dsh-plugin-sql-assistant

它更像数据库语义解释器,而不是 SQL linter。连接 PostgreSQL 后运行 dsh sql explain "show me users with high engagement",它会:

  1. 解析自然语言意图
  2. 查询 pg_catalog 获取表结构
  3. 生成带注释的 SQL:SELECT * FROM users WHERE engagement_score > 0.8 /* 'high engagement' mapped to score > 0.8 */

已知缺陷:dshmarket 的 installer 没有把模板文件复制到 profile 目录。临时绕过:

cp ~/.dsh/plugins/dshmarket/templates/* ~/.dsh/profiles/web/templates/

永久修复是向其仓库提 PR,在 install.sh 中加入:

cp -r templates/* "$PROFILE_DIR/templates/"

4. 终极排障:dsh plugin tree --verbose

它会输出完整的 loader log,包括 Resolve Phase 的依赖图、Validate Phase 的版本检查结果、Apply Phase 的每个 include 符号的查找路径。信息量比 dsh plugin list 高出一个量级。任何“插件装了但没生效”的问题,都应先跑这一条。

5. 从命令到 Agent:workflow 的形态变化

传统工作流是线性的:git pull → npm install → npm run test → npm run build。每个命令孤立,输出是非结构化文本,下一个命令的输入需要人工 parse。

dsh 工作流是声明式的:你声明一个 agent,描述它的 input 和 output,dsh 自动编排所有插件,构建 execution graph。一个 CI Pipeline Agent 的 agent.yaml 大致如此:

input:
  type: object
  properties:
    pr_url: {type: string}
output:
  type: object
  properties:
    status: {type: string, enum: ["success", "failure"]}
    comments: {type: array, items: {type: string}}
steps: ...

运行 dsh agent run --input '{"pr_url": "[https://github.com/xxx/pull/123](https://github.com/xxx/pull/123)"}',dsh 会:

  1. 调用 github 插件获取 PR 信息
  2. 将 files 字段传给 code-diagnostic
  3. 将 patch 字段传给 sql-assistant
  4. 合并两个插件结果,交给 llm-router 生成 summary
  5. 返回结构化 JSON

整个过程不需要敲任何中间命令,插件间的 data passing 通过 context state 自动完成。context 定义的 schema 就是 contract,llm-router 提供的 routing 就是 service discovery。

这也解释了 agent 项目、ai agent 成为热词的原因。它要减少的是 glue code 的数量,并非让你写更多代码。以前需要写 Python 脚本串联 git、eslint、psql,现在只需要一份 YAML 描述 agent 的行为。

实际项目中的一个对照数据:用 dsh 替代了原本 300 行的 CI 脚本。最大的收益是可维护性,而非省时间——当需要新增一个 security_scan 步骤时,只需在 agent.yaml 的 steps 列表里加一行,不用碰任何 Python 代码。dsh agent validate 还能静态检查整个 graph 的 input/output 兼容性,这在传统脚本里无法实现。

最后一个技巧:dsh agent export --format dot 可将 agent 的 execution graph 导出为 DOT 格式,用 Graphviz 渲染成流程图。团队每周站会可用这张图 review agent 设计,比任何文字文档都直观。

dsh 的本质,是把软件开发从“写代码”升级为“编排能力”,而插件就是你的能力原子库。