DeepSeekHarness（番外01)：装MCP与Skill还靠手改YAML？一条命令搞定15个服务器

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

dsh-install 实战：把 MCP 与 Skill 安装变成一条命令

Windows 10/11 · DeepSeek Harness v0.1.0-rc.5 · dsh-install v0.1.1 · Node.js ^22.19.0 或 ≥24 / pnpm 11.7.0 · 最后更新 2026-08-15

版本提示：npm registry 上 @deepseek-ai/dsh latest 已到 0.1.0-rc.6（2026-08-15 实测），本文全部实测基于本地 clone 的 rc.5 源码，与（05）期一致；rc.6 发布链缺陷见（05）期 Debug #2。

一、这篇教程解决什么问题

一句话定位：（05）期《MCP 与 Skill 安装——把 Claude Code 的装备搬进 dsh》讲的是手工路线：每个 MCP 服务器都要手写 insert patch（12 个字段）、每个 Skill 都要手工建目录改 frontmatter。本番外篇把这个手工流程做成了一个开源插件 dsh-install（npm 包 @dsh-tools/dsh-install，MIT 协议，136 个自动化测试），把 MCP 服务器与 Skill 的安装、启停、改配置、诊断、迁移全部变成一条命令。本文带你 5 分钟装上它、接入第一个 MCP 服务器，并给出 5 个真实踩坑的完整排查。这也是（06）期《插件开发入门》的实战落地：我们用 Cordis 范式真写了一个插件。

跳读指南：环境已就绪的读者直接跳到四、安装 dsh-install。只想看它怎么用、不关心原理，跳到五、实战 MCP。对「为什么装个插件还要重启一次」这类机制问题感兴趣的，先看二、三件套架构，这是本文所有 Debug 的理论基础。

阅读前提：

已完成（01）期安装，dsh 命令全局可用（任意目录 dsh –version 能输出版本号，源码路线见（01）期 3.8 节 shim）
全部命令在 PowerShell 中执行（Windows 10/11）
不需要任何 TypeScript 基础——本文一行代码都不写，只敲命令

读完能得到什么：

装好 dsh-install 的 dsh 环境：MCP 服务器与 Skill 从此增删改查全靠命令，改配置免重启
会用 15 个内置目录条目一行命令装服务器，也会用 — 形式装任意 npm 包
一份能直接复制的 zai-mcp-server（智谱视觉 MCP）完整接入命令，含免重启换模型
5 个真实报错（& 截断、工具不出现、1113 余额、密钥进启动参数、junction 迁移）的定位方法

二、dsh-install 是什么：三件套与一条命令

2.1 它取代了（05）期的哪些手工操作

（05）期手工路线的完整清单：服务器要写 insert patch（id、command、args、env、transport、reconnect……12 个字段）、密钥要逐条清理、Skill 要手工建 <DSH_HOME>\\skills\\<name>\\SKILL.md 并改写 frontmatter。每加一个装备都要开文件、改 YAML、重启验证。

dsh-install 的做法：把这一切收进一个注册表 JSON 文件，用命令读写它，用一个聚合器插件把它翻译回 harness 认识的形态。手工路线是（05）期的知识底座，本番外是它的命令化封装——知道手工怎么做，才能理解 Debug 里的每一条报错。

2.2 三件套架构

组件形态职责对应（06）期概念

注册表（数据面）	<DSH_HOME>\\mcp.json 等 JSON 文件	一切状态的唯一事实源：装了什么、怎么启动、密钥引用	无状态服务 + 外部存储
聚合器 mcp-registry（运行面）	cordis 插件行，默认停用	监视注册表，差分地把服务器挂进会话工具表（工具名 mcp__<server>__<tool>）	服务注入 + 可逆副作用
CLI 管理面 install-cli（交互面）	cordis 插件行	dsh –profile install mcp … 等命令，读写注册表	命令挂载

三件套之间只通过注册表 JSON 沟通：CLI 改文件，聚合器热感知，差分重挂。这就是「改配置免重启」的机制来源——一次 boot 之后，注册表的一切改动都在运行期生效。

2.3 能力一览

命令作用例子

mcp add/list/get/remove	服务器增删查	mcp add github
mcp on/off/update	启停与改配置（免重启）	mcp update zai -e Z_AI_VISION_MODEL=…
mcp doctor	运行时/环境变量诊断	mcp doctor zai
mcp import	迁移 Claude Code / Codex / mcp.json 配置	mcp import –from claude
skills add/list/remove/update	Skill 管理	skills add github:owner/repo#subdir
search / marketplace	内置目录搜索 / 社区市场	search playwright
uninstall	整体卸载（带预览）	uninstall –dry-run

2.4 与 dsh plugin 的分工

dsh plugin add 装的是插件包本身（bundle 层，boot 时读入，改动需重启）；dsh-install 的 mcp/skills 命令装的是装备数据（注册表层，运行期热生效）。两者千万别混：把 MCP 服务器名敲给 dsh plugin add 是装不上的。

三、环境准备

3.1 依赖清单

组件最低版本说明

DeepSeek Harness	v0.1.0-rc.5（本地 clone）	本文实测版本；rc.6 有发布链缺陷，见文首版本提示
Node.js	^22.19.0 或 ≥24	dsh 自身硬门槛（（01）期 2.1 节），npx 随 Node 自带
npx / uvx / docker	按需	装哪种运行时的服务器才需要哪个：node 系用 npx、Python 系用 uvx、docker-* 条目用 docker
git	任意较新版本	可选，skills add github:… 的 git 源需要

运行时是检测而非安装：doctor 只报告 npx/uvx/docker 在不在 PATH，不会替你装——缺什么装什么，插件不擅自往系统里塞运行时。

3.2 逐条验证

dsh —version # 应输出 0.1.0-rc.5
npx —version # 应输出 10.x 或更高（装 node 系 MCP 需要）
uvx —version # 可选，装 Python 系 MCP 需要；没有就 pip install uv 或 pipx install uv
docker —version # 可选，装 docker-* 条目需要

本机实测输出：

0.1.0-rc.5

如果 dsh 不是命令：回到（01）期 3.8 节配 shim（源码路线）或改走 npx @deepseek-ai/dsh。

四、安装 dsh-install（三步，5 分钟）

4.1 装包到两个 profile

dsh plugin —profile install add @dsh-tools/dsh-install # CLI 管理面住这里
dsh plugin —profile web add @dsh-tools/dsh-install # 聚合器在这里给会话挂工具

预期输出（节选，本机实测 2026-08-15）：

✓ Lockfile passes supply-chain policies (verified 536ms ago)
[WARN] Issues with peer dependencies found. Run "pnpm peers check" to list them.

dependencies:
+ @dsh-tools/dsh-install ^0.1.0

Packages: +3
+++
Progress: resolved 3, reused 3, downloaded 0, added 3, done
Done in 406ms using pnpm v11.7.0

在这里插入图片描述

为什么两个 profile 各装一份：install profile 承载命令行（dsh –profile install mcp …），web profile 承载聚合器（会话工具挂载）。职责分离，管理动作不进会话。headless 场景同理：哪个 profile 跑会话，就在哪个启用聚合器。

[WARN] Issues with peer dependencies found 无害：插件故意把 cordis / dsh-mcp-client 等声明为 peer dependency，复用 harness 自己安装的那份，避免版本漂移——这是有意的架构选择，不是安装失败。

4.2 启用聚合器行（唯一一次手改 YAML）

记事本打开 <DSH_HOME>\\profiles\\web\\cordis.patch.yml，初始内容只有一段注释说明，改成：

– id: mcp–registry
disabled: false

机制：bundle 自带的 cordis.patch.yml 里，mcp-registry 行默认 disabled: true（聚合器默认不打扰任何人）；你的 profile patch 层优先级更高，写 disabled: false 即覆盖启用。保存即热生效，这是 harness patch 热重载的机制（详见（07）期《Profiles 与配置体系》预告）。

为什么默认停用？因为不装任何 MCP 服务器的用户不需要在会话里挂一个空聚合器。启用只此一次，之后再也不碰这个文件。

4.3 重启一次 web（只此一次）

# 在启动 web 的窗口按 Ctrl+C，然后重新启动
dsh web

装/卸插件包属于 bundle 层改动，只在 boot 时读入，所以必须重启一次。此后所有 mcp/skills 命令的改动（增删、开关、换模型、换密钥引用）全部免重启——热重载矩阵见 8.3。

4.4 验证

dsh —profile install mcp list

预期输出：没有报错，列表为空（刚装好还没有任何服务器，空是正常的）：

在这里插入图片描述

web 侧两处确认：

输入框敲 /，命令面板出现 /mcp、/skills 两个斜杠命令；

后续每装一个服务器，模型新会话的工具列表自动出现 mcp__<server>__* 工具。在这里插入图片描述

到这里如果 mcp list 报「未知命令」或模型看不到工具，先别乱试，直接跳 Debug #2 的三查清单。

五、实战：安装并接入一个 MCP 服务器

5.1 内置目录：15 个一行命令

内置目录随插件离线发布，mcp add <名字> 即可，不用记任何 npx 命令：

名字运行时说明特殊要求

github	npx	官方 GitHub 服务器：Issue/PR/仓库搜索	-e GITHUB_TOKEN
filesystem	npx	读写指定目录下的文件	需 — 形式补路径参数
everything	npx	官方集成测试服务器：echo/sum/probe	—
memory	npx	知识图谱记忆（本地持久化）	—
sequential-thinking	npx	分步推理	—
fetch	uvx	网页转 Markdown（Python）	需 uvx
git	uvx	Git 仓库操作（Python）	需 uvx
sqlite	uvx	SQLite 查询（Python）	需 — 形式补库路径
time	uvx	时间与时区换算（Python）	需 uvx
sentry	npx	Sentry 错误监控	需 — 形式补 –auth-token
context7	npx	实时库文档查询	—
playwright	npx	浏览器自动化（测试/抓取）	—
brave-search	npx	Brave 搜索 API	-e BRAVE_API_KEY
docker-git	docker	Git 操作（Docker 镜像）	需 docker
docker-fetch	docker	网页抓取（Docker 镜像）	需 docker

示例——装官方 GitHub 服务器：

dsh —profile install mcp add github –e GITHUB_TOKEN

预期输出（mcp list 应立即出现）：

githubstdio, usercli

三列含义：名字、传输方式 + 作用域（user=用户级 / project=项目级）、来源标签（cli=命令行添加，含内置简写 / import:claude=迁移自 Claude Code / slash:web=网页斜杠命令添加 / marketplace:<name>=社区市场）。

5.2 任意包：– 分界线与 -e 语法红线

目录里没有的服务器用 — 形式，后面跟完整启动命令。实战：智谱 Z.AI 的视觉理解 MCP（官方文档）：

dsh —profile install mcp add zai –e ZAI_API_KEY — npx –y @z_ai/mcp-server

语法红线（本文最重要的三条规则）：

— 是分界线：之后的内容原样成为服务器的启动命令，一个字都不改；

-e 等选项必须在 — 之前——放到后面就会变成启动参数的一部分，密钥明文进 args（惨案见 Debug #4）；

-e KEY=VALUE 存字面值，-e KEY 存环境变量引用。装密钥永远用第二种，注册表只落 ${KEY} 引用，挂载时才从环境展开。

验证存储内容（本机实测输出）：

dsh —profile install mcp get zai

{
"transport": "stdio",
"command": "npx",
"args": [
"-y",
"@z_ai/mcp-server"
],
"env": {
"Z_AI_VISION_MODEL": "GLM-4.6V-Flash",
"ZAI_API_KEY": "${ZAI_API_KEY}"
},
"cwd": "",
"toolCallTimeoutMs": 60000,
"enabled": true,
"origin": {
"source": "cli",
"addedAt": "2026-08-15T13:50:44.791Z"
}
}

注意 env 里是 "${ZAI_API_KEY}" 引用而非明文——这是 dsh-install 的安全底线，全文只有引用，没有密钥。

5.3 HTTP 传输

streamable-http 服务器也支持，一条命令：

dsh —profile install mcp add myapi —transport http —url https://host/mcp

5.4 生命周期命令：list / get / on / off / update / remove

dsh —profile install mcp list [—format json] # 列表；–format json 出完整 JSON
dsh —profile install mcp get zai # 查看单条完整配置
dsh —profile install mcp on zai | off zai # 启停（免重启，off 的服务器不挂工具）
dsh —profile install mcp remove zai [—all] [—dry-run] # 删除；–dry-run 先预览

免重启换模型（本番外最实用的一条）：zai 默认视觉模型是付费的 glm-4.6v，账户余额不足会报 1113（见 Debug #3）。换成免费视觉模型 GLM-4.6V-Flash，不需要重启 web、不需要改任何文件：

dsh —profile install mcp update zai –e Z_AI_VISION_MODEL=GLM-4.6V-Flash –e ZAI_API_KEY — npx –y @z_ai/mcp-server

update 会整体重写该条目的启动配置，所以原来带过的 -e 要重新声明一遍（如上面的 -e ZAI_API_KEY），否则会丢。这是 update 的语义，不是 bug。

5.5 doctor 诊断

服务器挂了先跑 doctor，不用瞎猜。本机实测输出（节选）：

dsh —profile install mcp doctor zai

✅ runtime "npx" found at D:\\Program Files (x86)\\nodejs\\npx
⚠️ env var ZAI_API_KEY is not set

两条信息直击要害：运行时在不在 PATH、env 里引用的环境变量在不在当前环境。上例的 ⚠️ 意味着注册表写的是 ${ZAI_API_KEY}，但当前终端环境里没有这个变量——挂载时服务器拿到空密钥，工具必然认证失败。补上 setx ZAI_API_KEY "你的Key"（新终端生效）再跑 doctor 即可。

六、实战：安装 Skill

dsh —profile install skills add .\\my-skill # 本地目录
dsh —profile install skills add github:owner/repo#subdir@v1.0 # git 源（可指定子目录与版本）
dsh —profile install skills add <path> —link # 符号链接（开发模式：改源目录即时生效）
dsh —profile install skills list | remove <n> [—all] [—dry-run] | update <n> <src>

落位即生效：装进 <DSH_HOME>\\skills 或 <project>\\.dsh\\skills，harness 的 skill 提供方自带 watcher 自动发现，免重启。本机实测 skills list 输出：

skill-cn-annotateuserC:\\Users\\<用户名>\\.claude\\skills\\skill-cn-annotate
tutorial-promo-writer-cnuserC:\\Users\\<用户名>\\.claude\\skills\\tutorial-promo-writer-cn

三列含义：名字、作用域（user/project）、落位路径。

remove 只删自己装过的：每次安装都记录在 skills-manifest.json 里，来源可追溯；手工放进 skills 目录的第三方技能不受影响，避免误删。

七、迁移：把 Claude Code / Codex 的旧配置搬进来

（05）期的迁移是手工对照表；这里一条命令把旧 agent 的 MCP 配置翻译成注册表条目：

dsh —profile install mcp import —from claude # ~/.claude.json / .mcp.json
dsh —profile install mcp import —from codex # ~/.codex/config.toml
dsh —profile install mcp import —from mcp-json [—path <p>] # 任意 .mcp.json
dsh —profile install mcp import —from auto # 自动探测

迁移的是服务器定义（命令、参数、传输方式）；密钥字段一律以 ${VAR} 引用形式落盘，与全插件的安全模型一致。无法映射的载荷不会硬塞，归档到 <DSH_HOME>\\install\\leftover\\ 等你处置。

八、数据与安全模型

8.1 数据落点

<DSH_HOME>\\mcp.json # user 级注册表（密钥只存 ${VAR} 引用）
<project>\\.dsh\\mcp.json # project 级注册表（git 可共享，同名覆盖 user 级）
<DSH_HOME>\\skills-manifest.json # Skill 来源追踪（remove 只删自己装过的）
<DSH_HOME>\\marketplaces.json # 社区市场注册
<DSH_HOME>\\logs\\install.jsonl # 审计日志（每次操作逐条裁决，可重放）
<DSH_HOME>\\install\\work\\ # 克隆过客区（每次 git 克隆前重置，用完即清）
<DSH_HOME>\\install\\leftover\\ # 未迁移载荷的存档（uninstall 清）
<DSH_HOME>\\profiles\\<name>\\node_modules\\ # 插件代码（与数据分离）

8.2 密钥安全三原则

注册表永不存明文：-e ZAI_API_KEY 存入的是 ${ZAI_API_KEY} 引用（5.2 的真实输出已实证）；

密钥只住在环境变量里：setx ZAI_API_KEY "…"，新终端生效；

泄漏即轮换：一旦明文误入启动参数或聊天记录（见 Debug #4），先去服务商后台轮换密钥，再 mcp remove 重装——改注册表救不了已泄漏的密钥。

8.3 热重载矩阵

改动是否需重启

dsh plugin add/remove（装/卸插件包本体）	需要（bundle 层只在 boot 读入）
改 patch 启用/停用聚合器行	免重启（harness patch 热重载，保存即生效）
mcp add/remove/on/off/update	免重启（聚合器监视注册表，差分重挂）
skills add/remove	免重启（skill 提供方自带 watcher）

8.4 审计日志

每次增删改都向 <DSH_HOME>\\logs\\install.jsonl 追加一条 JSON 记录（时间、命令、裁决结果），出问题可以 Get-Content 按时间回放——「谁在什么时候动了什么」永远可查。

九、Debug

Debug #1 — 本地路径装插件：& 被截断，目录装成普通依赖

报错日志

从源码构建后，用本地路径安装：

dsh plugin —profile install add D:\\Workspace\\DSH-Install-MCP&Skill\\packages\\dsh-install

本机实测输出（路径在 & 处被截断）：

[WARN] Installing a dependency from a non-existent directory: D:/Workspace/DSH-Install-MCP

dependencies:
+ DSH-Install-MCP link:D:/Workspace/DSH-Install-MCP

Already up to date
Done in 346ms using pnpm v11.7.0

根因

两层问题叠加：

dsh 启动器（.cmd 转发 %*）与 shell 的分词规则里 & 是元字符，路径 DSH-Install-MCP&Skill 在 & 处被切断，后半段被当成另一个命令——于是 dsh 拿到一个不存在的目录 D:/Workspace/DSH-Install-MCP；

即使路径没有 &，目录安装是 link 安装：pnpm 只建符号链接、不把依赖装进 profile，且不带 dsh.bundle 声明时会被当成普通依赖——不是 profile 层，聚合器行根本不会出现。

一览对比表

对比维度目录路径（错误）tarball / 包名（正确）

依赖安装	link 符号链接，依赖不进 profile	完整解包，依赖进 profile
bundle 行	无声明时退化为普通依赖	正常成为 profile 层
路径含 &	被 shell 截断	npm 包名无此问题

代码修复

文件：打包命令（项目根执行）

# 修复前：直接 add 目录
dsh plugin —profile install add D:\\Workspace\\DSH-Install-MCP&Skill\\packages\\dsh-install

# 修复后：pack 成 tarball 再 add；或直接用 npm 包名（最省心）
pnpm —dir packages/dsh-install pack —pack-destination .\\.local\\dist
dsh plugin —profile install add D:\\...\\dsh-install\\.local\\dist\\dsh-tools-dsh-install-0.1.0.tgz

# 最省心：正式用户直接装 npm 包
dsh plugin —profile install add @dsh-tools/dsh-install

验证

add 输出出现 + @dsh-tools/dsh-install 且无 link: 字样；dsh –profile install mcp list 不再报「未知命令」。

Debug #2 — 装好了，模型却看不到任何 MCP 工具

报错日志

没有报错——这正是最坑的地方。一切命令都正常，但 web 会话里就是没有 mcp__* 工具，/ 面板里也没有 /mcp、/skills。

根因

工具挂载链上有两个 boot 期闸门：

聚合器行没启用：bundle 自带 patch 里 mcp-registry 默认 disabled: true，没有在 profile patch 里覆盖成 false，聚合器从未启动；

装包后没重启过 web：bundle 层只在 boot 读入，装完包直接继续用旧会话，插件代码还没加载。

两者都表现为「静默无工具」，但修复点完全不同。

一览对比表

检查项命令/位置期望

聚合器行	<DSH_HOME>\\profiles\\web\\cordis.patch.yml	含 – id: mcp-registry 且 disabled: false
bundle 加载	重启一次 web 后的启动日志	出现 mcp-registry 相关行
服务器自身	mcp doctor <n>	runtime ✅、env 无 ⚠️

代码修复

# 1. 查聚合器行（记事本打开确认，缺了就补）
notepad $env:DSH_HOME\\profiles\\web\\cordis.patch.yml

# 2. 补全后的正确内容
# – id: mcp-registry
# disabled: false

# 3. 重启一次 web（Ctrl+C 后）
dsh web

# 4. 新会话验证（旧会话不重挂工具，必须开新会话）

验证

新会话里模型工具列表出现 mcp__<server>__*；/ 面板出现 /mcp、/skills。三查顺序记牢：行启用 → 重启过 → doctor 无警告。

Debug #3 — zai 调用报 1113 insufficient balance：默认模型是付费的

报错日志

zai 服务器接入成功后，模型调用 mcp__zai__analyze_image 返回：

code 1113 insufficient balance

根因

@z_ai/mcp-server 默认视觉模型是 glm-4.6v——付费模型。账户余额不足时服务侧直接拦截（1113），请求根本没到模型推理环节。这不是配置错误，是「默认模型要花钱」的默认值陷阱。

一览对比表

对比维度默认 glm-4.6vGLM-4.6V-Flash

计费	付费	免费
余额不足时	1113 insufficient balance	不会（但免费档有并发限流）
切换方式	—	mcp update 一条命令，免重启

代码修复

dsh —profile install mcp update zai –e Z_AI_VISION_MODEL=GLM-4.6V-Flash –e ZAI_API_KEY — npx –y @z_ai/mcp-server
dsh —profile install mcp get zai # 确认 env 已写入

验证

mcp get zai 的 env 出现 "Z_AI_VISION_MODEL": "GLM-4.6V-Flash"。再次调用报错从 1113 变成 1305 service temporarily overloaded——错误码变化证明请求已进入免费模型的限流逻辑（换模型成功），1305 是免费档高峰限流，错峰重试即可。

Debug #4 — 密钥写进了 — 后面：明文进 args 还带进聊天记录

报错日志

把 -e 和密钥一起放到了 — 之后：

dsh —profile install mcp add zai — npx –y @z_ai/mcp-server –e ZAI_API_KEY=sk-xxxx

后果不是报错，而是两处「看似正常」：服务器拿到了错误的启动参数（-e 没被识别成 env，认证照样失败），而 mcp get zai 里 args 躺着明文密钥——这串字符随后还可能被模型带进聊天记录。

根因

— 之后的每一段都原样成为启动命令的一部分。-e 是 dsh-install 的选项，只认 — 之前的位置；放到后面，它就不是「配置环境变量」，而是「传给 npx 的参数」。密钥明文同时落进注册表 args 和会话上下文。

一览对比表

对比维度错误：-e 在 — 后正确：-e 在 — 前

注册表 env	空	{"ZAI_API_KEY": "${ZAI_API_KEY}"}
注册表 args	含明文密钥	只有启动参数
密钥实际生效	否（被当启动参数）	是（挂载时从环境展开）

代码修复

# 1. 先删掉带明文的条目
dsh —profile install mcp remove zai

# 2. 去服务商后台轮换密钥（明文已泄漏，改注册表救不了）

# 3. 用正确姿势重装：-e 在 — 前，且 -e 后只写变量名
setx ZAI_API_KEY "轮换后的新Key" # 新终端生效
dsh —profile install mcp add zai –e ZAI_API_KEY — npx –y @z_ai/mcp-server

验证

mcp get zai 里 env 是 "${ZAI_API_KEY}"、args 无任何 sk- 字串；mcp doctor zai 的 env 检查变 ✅。

Debug #5 — 迁移 DSH_HOME 后 dsh 启动报错：junction 被解引用

报错日志

把 <DSH_HOME>（如 C:\\Users\\<用户名>\\.dsh）整个复制到 D 盘后，dsh web 启动即报错，提示 profiles\\node_modules 下链接结构异常（跨盘复制把 195 个 junction 全部解引用成了普通目录副本）。

根因

harness 的 profiles 依赖大量目录链接（junction）做模块共享；Windows 的普通复制（含资源管理器拖拽、Copy-Item、不带参数的 robocopy）会把 junction 解引用成真实目录，链接拓扑被破坏。harness 启动时检测到结构异常，直接拒绝运行——这是自我保护，不是数据损坏。

一览对比表

对比维度普通复制（错误）robocopy /XJ（正确）

junction 处理	解引用成真实目录	原样保留
迁移后启动	报错拒绝启动	正常
数据完整性	文件都在，拓扑坏了	完整迁移

代码修复

# 已用普通复制搬完、启动报错的：改名触发自愈
Rename-Item $env:DSH_HOME\\profiles\\node_modules node_modules.bak
dsh web # harness 自愈重建全部链接（实测 195/195 重建），确认正常后删除 .bak

# 还没搬的：直接用正确姿势，避免踩坑
robocopy C:\\Users\\<用户名>\\.dsh D:\\Agents\\.dsh /E /XJ

验证

改名后 dsh web 正常启动；Get-ChildItem $env:DSH_HOME\\profiles\\node_modules -Force 里重新出现带链接标记的目录；确认无误后 Remove-Item …\\node_modules.bak -Recurse -Force（实测残留约 11MB）。

十、日常维护

10.1 开关与改配置

dsh —profile install mcp off zai # 临时停用（免重启，工具立即消失）
dsh —profile install mcp on zai # 恢复
dsh —profile install mcp update ... # 改配置（注意 -e 要重新声明全量）

10.2 升级插件本体

npm 发布新版本后，重装一次包（bundle 层改动，需重启一次；数据面注册表不动）：

dsh plugin —profile install add @dsh-tools/dsh-install
dsh plugin —profile web add @dsh-tools/dsh-install
# 重启 web 一次

截至 rc.5，dsh plugin 只有 add/remove/list 没有 update 子命令，升级 = 再次 add 拉新版本；开发者请以实际发布时的 harness 文档为准。

10.3 卸载

dsh —profile install uninstall —dry-run # 先预览：会删什么、留什么
dsh —profile install uninstall [—purge-log] # 清数据面（日志默认保留）
dsh plugin —profile install remove @dsh-tools/dsh-install # 卸包本体，每个 profile 一次
dsh plugin —profile web remove @dsh-tools/dsh-install

10.4 诊断入口

想查什么命令/位置

服务器健康	mcp doctor <n>
整体报告	report
历史操作	<DSH_HOME>\\logs\\install.jsonl（Get-Content 按时间回放）

十一、速查卡

11.1 文件路径汇总

文件/目录绝对路径

user 级 MCP 注册表	D:\\Agents\\.dsh\\mcp.json
project 级 MCP 注册表	<project>\\.dsh\\mcp.json
Skill 来源清单	D:\\Agents\\.dsh\\skills-manifest.json
审计日志	D:\\Agents\\.dsh\\logs\\install.jsonl
聚合器启用开关	D:\\Agents\\.dsh\\profiles\\web\\cordis.patch.yml
插件代码	D:\\Agents\\.dsh\\profiles\\<name>\\node_modules\\@dsh-tools\\dsh-install
未迁移载荷存档	D:\\Agents\\.dsh\\install\\leftover\\

（示例安装目录 D:\\Agents 与（01）期一致，换目录全局替换；用户目录一律 <用户名> 占位。）

11.2 版本/配置字段

字段值出处

harness 实测版本	v0.1.0-rc.5	dsh –version
插件版本	v0.1.1	npm
聚合器行 id	mcp-registry（默认 disabled: true）	包内 cordis.patch.yml
密钥引用格式	${VAR}（永不存明文）	注册表 env 字段
工具命名	mcp__<server>__<tool>	聚合器挂载规则

11.3 常见报错 → 解决方案

报错解决

[WARN] … non-existent directory / 路径在 & 处截断	用 tarball 或 npm 包名 → Debug #1
无报错但模型看不到 mcp__* 工具	三查：行启用 / 重启过 / doctor → Debug #2
zai 调用 code 1113 insufficient balance	mcp update 换 GLM-4.6V-Flash → Debug #3
mcp get 里 args 出现明文密钥	删条目 + 轮换密钥 + -e 放 — 前 → Debug #4
迁移 DSH_HOME 后启动报链接异常	改名 node_modules 触发自愈 / robocopy /XJ → Debug #5
doctor 报 env var XXX is not set	setx XXX "…" 后新终端再验证 → 5.5
[WARN] Issues with peer dependencies found	无害，peer 复用 harness 依赖的设计 → 4.1

十二、扩展阅读

本系列相关文章（本文为番外篇，不占正篇编号，建议在（05）（06）之间阅读）：

DeepSeek Harness 从入门到精通（05）MCP 与 Skill 安装——把 Claude Code 的装备搬进 dsh — 手工路线全景，本文的命令化封装对照底本
DeepSeekHarness高手进阶（06）：DeepSeek Harness 只会用不会改？5 个概念 + 1 个插件 + 3 种装法，一次跑通 — Cordis 范式与双聚合构建，本文正是其实战落地
DeepSeek Harness 从入门到精通（04）CLI 与 Headless 模式 — –profile install 这类 CLI 入口的机制，本文所有命令都跑在它上面
DeepSeek Harness 在 Windows 上的安装与调试指南 — 环境底座与 shim 配置，本文的阅读前提

参考文献

deepseek-ai/deepseek-harness（官方仓库） — dsh 本体、plugin/bundle/patch 机制

Friend-Xu/dsh-install（本番外项目仓库） — 完整源码、136 个测试、DESIGN 文档

@dsh-tools/dsh-install（npm） — 安装包与版本信息

modelcontextprotocol/servers（内置目录来源） — 15 个内置条目的官方定义

视觉理解 MCP — 智谱 AI 开放文档 — zai-mcp-server 的模型与环境变量（Z_AI_VISION_MODEL 等）

dsh-install 实战：把 MCP 与 Skill 安装变成一条命令

一、这篇教程解决什么问题

二、dsh-install 是什么：三件套与一条命令

2.1 它取代了（05）期的哪些手工操作

2.2 三件套架构

2.3 能力一览

2.4 与 dsh plugin 的分工

三、环境准备

3.1 依赖清单

3.2 逐条验证

四、安装 dsh-install（三步，5 分钟）

4.1 装包到两个 profile

4.2 启用聚合器行（唯一一次手改 YAML）

4.3 重启一次 web（只此一次）

4.4 验证

五、实战：安装并接入一个 MCP 服务器

5.1 内置目录：15 个一行命令

5.2 任意包：– 分界线与 -e 语法红线

5.3 HTTP 传输

5.4 生命周期命令：list / get / on / off / update / remove

5.5 doctor 诊断

六、实战：安装 Skill

七、迁移：把 Claude Code / Codex 的旧配置搬进来

八、数据与安全模型

8.1 数据落点

8.2 密钥安全三原则

8.3 热重载矩阵

8.4 审计日志

九、Debug

Debug #1 — 本地路径装插件：& 被截断，目录装成普通依赖

报错日志

根因

一览对比表

代码修复

验证

Debug #2 — 装好了，模型却看不到任何 MCP 工具

报错日志

根因

一览对比表

代码修复

验证

Debug #3 — zai 调用报 1113 insufficient balance：默认模型是付费的

报错日志

根因

一览对比表

代码修复

验证

Debug #4 — 密钥写进了 — 后面：明文进 args 还带进聊天记录

报错日志

根因

一览对比表

代码修复

验证

Debug #5 — 迁移 DSH_HOME 后 dsh 启动报错：junction 被解引用

报错日志

根因

一览对比表

代码修复

验证

十、日常维护

10.1 开关与改配置

10.2 升级插件本体

10.3 卸载

10.4 诊断入口

十一、速查卡

11.1 文件路径汇总

11.2 版本/配置字段

11.3 常见报错 → 解决方案

十二、扩展阅读

参考文献

相关推荐

评论 抢沙发

评论前必须登录！

热门标签

置顶推荐

热门文章

最新文章

评论抢沙发