术语表与常见问题
本教程共 32 篇 · 第 32 篇 · 更新于 2026-08-15 · 约 9 分钟阅读
本节目标：用一张表复习全书术语，记住版本基线，能照着排查安装、配置、运行的常见问题，并知道下一步该看哪些官方文档。
全书术语速查表
| 术语 | 英文 | 一句话解释 |
|---|---|---|
| dsh | DeepSeek Harness 命令名 | 启动和管理 Harness 的命令行工具，如 dsh web |
| Harness | — | 驾驭模型的框架层，上下文、工具、循环、权限都归它管 |
| 插件 | Plugin | 挂到插件树上的能力单元；模型、工具、UI 全是插件 |
| Cordis | — | dsh 底层的插件元框架，管插件的加载、卸载与依赖 |
| Bundle | Bundle | 打包一组配置与代码的分发格式，可被上层补丁覆盖（不译） |
| Profile | Profile | 命名组合清单，声明叠加哪些 bundle；官方有 web、headless 两套（不译） |
| Patch | Patch | 按 id 定位配置行并覆盖的补丁层，层层叠加 |
| 能力缝 | Capability Seam | 可替换能力的完整模型：Service Definition + Provider + Consumer |
| 核心服务 | Core Service | 通过 ctx.<key> 暴露的内置服务，如 ctx.tools、ctx.sandbox |
| ctx | Context | 插件的共享上下文，服务、事件、注册都挂在它上面 |
| Agent 预设 | Agent Preset | 官方内置的 standard / minimal / code / cordis 四套预设 |
| 作用域 | Scope | 按 agent 划分的注册单位，带作用域的能力只对归属 agent 可见 |
| 会话 | Session | 一次独立对话，附带一份只追加的会话日志 |
| 轮次 | Turn | 会话中处理一次输入的过程，到模型和工具停手为止 |
| 步骤 | Step | 一次模型请求加上它引发的工具执行；一个轮次含多个步骤 |
| 事件 | Event | 插件间通信的类型化消息，如 session、agent/、fs/ |
| 工具 | Tool | agent 可调用的能力入口，如执行命令、读写文件 |
| 沙箱 | Sandbox | 限制子进程权限的隔离机制，Linux 用 Landlock、macOS 用 Seatbelt |
| 审批 | Approval | 敏感操作先征求你同意的机制，默认失败关闭 |
| 凭据 | Credentials | API Key 等敏感信息的本地存储服务 |
| 提供方 | Provider | 模型服务接入，DeepSeek、Anthropic、OpenAI 等都可配 |
| 会话日志 | Session Log | 模型看到的一切都写入的 append-only 日志，可回放、可分叉 |
| 持久化 | Persistence | 会话存储后端，官方提供 JSONL 与 SQLite |
| 遥测 | Telemetry | 会话用量与事件统计 |
| Token 计量 | Token Meter | 回放计量当前请求/响应压力，供压缩与溢出重试决策（非账单） |
| 压缩 | Compaction | 把超长上下文摘要压缩，续上更长对话 |
| 无头模式 | Headless | 非交互运行，一次任务跑完即退出，适合脚本 |
| 子 Agent | Subagent | 委派出去干活的子会话，可嵌套、可并行 |
| Python SDK | — | 官方 Python 客户端，连接运行中的 dsh |
Note术语红线：官方叫法是 Agent Presets，不是「四种运行模式」；架构是 Capability Seams + Core Services，不是「八层架构」。读文档、写配置时用官方叫法，能少走弯路。
版本基线速查
| 组件 | 版本 | 说明 |
|---|---|---|
| Node.js | ^22.19.0 || >=24.0.0 | 22.19+ 或 24+，版本低了启动报错 |
| @deepseek-ai/dsh | 0.1.0-rc.6 | npm latest，2026-08-13 发布 |
| Cordis | 4.0.0-rc.8 | 底层元框架 |
| pnpm | 11.7.0 | 源码构建用的包管理器 |
实测命令：
node -v
npx @deepseek-ai/dsh --versionWarning项目处于 Developer Preview，版本快速变化，会有破坏性变更。本表是 2026-08-15 基线，任何时候以
dsh --version实测为准。
常见问题排查
启动失败
Q：npx 找不到 @deepseek-ai/dsh，或拉到的版本很旧。
先确认 Node 版本满足要求：
node -v再强制拉最新版，跳过 npx 缓存：
npx --yes @deepseek-ai/dsh@latest webQ：提示 Node 版本不满足 engines 要求。
装 Node 22.19+ 或 24+。Windows 推荐 nvm-windows，macOS/Linux 用 nvm 或 fnm，一条命令切版本。
Q：源码安装时 pnpm install / build 失败。
先确认 pnpm 装好了（npm install -g pnpm）。网络受限时给 npm/pnpm 配镜像源。Windows 上 node-pty 等原生模块编译失败，需要装 Visual Studio Build Tools（勾选 C++ 桌面开发）。
端口占用
Q：浏览器打不开 http://127.0.0.1:3080。
先确认终端里 dsh 进程还在、没报错。再看端口被谁占了：
# Windows
netstat -ano | findstr 3080
# macOS / Linux
lsof -i :3080端口被占就换一个：
dsh --profile web --port 8080启动参数在前、应用参数在后，--port 属于 Web 应用参数。防火墙也要确认放行了本地端口。
模型连不上
对照报错查：
| 报错 | 含义 | 处理 |
|---|---|---|
| MISSING_CREDENTIAL | 缺提供方密钥 | 设置 → 模型里存密钥，或配好环境变量 |
| UNKNOWN_MODEL | 请求的模型没配置 | 选已配置的模型，或给自定义提供方补模型 |
| 获取模型返回 401 | 密钥无效 | 检查 API Key 是否正确、有没有过期、余额够不够 |
| 图片在发送前被拒绝 | 模型没声明图片能力 | DeepSeek 是纯文本路由，看图用社区视觉插件 |
网络方面：公司内网或代理环境连不上 API，检查代理设置；换了网络后重启 dsh 再试。
API Key 配置错误
- Key 以
sk-开头，复制时别带空格和换行 - 在 Web UI 的 设置 → 模型 里保存后立即生效，不用重启
- 也可以走环境变量：macOS/Linux 用
export DEEPSEEK_API_KEY="***"，Windows 用$env:DEEPSEEK_API_KEY="***" - 别把 Key 提交进 git、发到群里
升级后配置不兼容
rc 阶段升级可能出现：配置项改名、插件加载失败、启动报错。按顺序处理：
- 升级前备份
~/.dsh主目录和 profile 目录 - 看发布说明（GitHub Releases / npm 页面）有没有破坏性变更说明
- 用
dsh --profile web --dump-config检查实际生效的配置树 - 实在起不来，恢复备份，或重建 profile 后逐个装回插件
输入框不可用
Web UI 打开后输入框是灰的，多半是没选工作区：点「选择工作区」添加并选中项目目录即可。模型没配好也会让 agent 无法正常工作，两项一起查。
其他高频问题
Q：Python SDK 提示找不到 Node.js。
SDK 自带运行时，正常情况下不需要系统 Node.js。如果报运行时缺失，确认装的是完整包（python -m pip install deepseek-harness-sdk），且平台符合官方要求：Linux x64/arm64 或 macOS 14+（arm64）。
Q：安装插件失败。
dsh plugin 会把参数转发给 pnpm 执行。先确认 pnpm 可用（pnpm -v），网络受限时配好镜像源，再看报错里有没有给出具体包名。插件装不上或装完不生效，把完整报错贴到 GitHub Discussions，附上 dsh --version 输出，社区才能帮你定位。
Q：agent 动不动要求审批，嫌烦。
审批默认失败关闭是安全设计，不是 bug。觉得频繁，可以在权限预设里放宽级别（第 16 章讲过），或者装一个自动审批类的社区插件，用独立审查 Agent 替你逐次把关。
Q：上次会话去哪了？
Web UI 左侧会话列表能找到历史会话。模型看到的一切都写进只追加的会话日志，恢复、分叉、检索都基于同一份事件流（第 10、18 章讲过）。升级前想带走数据，先备份 ~/.dsh 主目录。
下一步学习路径
教程读完，主线知识齐了。想深入，按官方文档的层次走：
用户指南 docs/user/guide/：使用 Web UI、模型 Provider 配置、Python SDK，日常使用看这里。
开发文档 docs/user/develop/：分 basic（工具、配置、发布）、framework（服务、事件）、practice（LLM 适配器）三块，插件开发进阶全在这。
扩展食谱 docs/cookbook/：加一个包、加一个工具、加一个 LLM 适配器，每篇都是带完整代码的实操例子。
子系统参考 docs/subsystems/：46 篇，会话、沙箱、审批、凭据、持久化、遥测、Token 计量等，按需查。
事故复盘 docs/postmortem/：官方把真实故障写成复盘，每篇讲发生了什么、为什么、怎么防。读这个比读十篇教程学得多。
顶层概念 docs/：architecture（架构）、capability-seams（能力缝）、config-catalog（配置目录）、tool-catalog（工具目录）、glossary（术语表）、testing（测试）、defensive-patterns（防御性模式）。
底层框架 docs/cordis-tutorial/ 和 docs/cordis-api/：想真正理解「一切皆插件」的机制，Cordis 的插件、服务、事件教程是必读；写插件遇到 API 问题查 cordis-api。
社区渠道：GitHub Discussions 和 Discord 是官方交流地；awesome-dsh-plugin 看插件风向；hello-dsh 仓库有 22 个中文技能示例，适合边写边学；想深挖实现细节，直接读主仓库 packages/ 下各包的 README。
Tip官方文档在 GitHub 仓库的 docs/ 目录，中英双语。rc 阶段文档和代码都在快速变，先确认你的版本和文档对得上。
小结
这一章把全书浓缩成三样东西：术语表帮你读文档，版本基线帮你对版本，FAQ 帮你排错。到此 32 章全部读完，你已经从零建立了对 DeepSeek Harness 的完整认知。工具还在快速进化，常回官方文档看看，保持好奇心。