摘要: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 字段。
操作三步:
dsh zotero login绑定账号dsh zotero sync --collection "AI Papers"- 在 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",它会:
- 解析自然语言意图
- 查询
pg_catalog获取表结构 - 生成带注释的 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 会:
- 调用
github插件获取 PR 信息 - 将
files字段传给code-diagnostic - 将
patch字段传给sql-assistant - 合并两个插件结果,交给
llm-router生成 summary - 返回结构化 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 的本质,是把软件开发从“写代码”升级为“编排能力”,而插件就是你的能力原子库。






