ARTICLE · 1213459
看DeepSeekHarness源码学TypeScript编程04 从源码把 dsh 跑起来:环境、构建、启动
看DeepSeekHarness源码学TypeScript编程04 从源码把 dsh 跑起来:环境、构建、启动上节我们能用 npx tsx 跑自己写的 .ts 了。 这节干一件更野的事：把 dsh 的源码整个拿下来，用源码启动它，让它用 DeepSeek 帮你干件真事。 先说清楚这节的上法：这是一节纯操作手册课。 软件安装每个人机器情况千差万别，可能遇到各种奇葩问题，这里不演示安装过程，只给你整体的过程命令——遇到问题就把报错原文拿去问AI，如果装了Claude Code等，甚至能直接帮你完成所有工作。因此这里主要分享完成该工作的思路。
dsh 需要三样东西。已经装好的，跑命令验证一下版本就行；没装的，去官网下载安装包，装好重开终端再验证——安装步骤不展开。 ① Node.js：要求 22.19+ 的 22.x 或 24+（23.x 不支持，奇数版本号是实验性的）。 node -v 看到类似 v22.19.0 或 v24.x.x 就 OK。没装或版本不符：去 Node.js 官网 下载 LTS 版本安装，装完重开终端再跑上面的命令。 ② pnpm：dsh 用 pnpm 做 monorepo（单仓多包）管理，仓库在 package.json 里固定了 pnpm@11.7.0。 pnpm --version 提示找不到 pnpm 的话，启用 Node 自带的Corepack（专门管 pnpm/yarn 版本的工具）： corepack enable 启用后，进到 dsh 仓库里敲 pnpm 会自动用上仓库指定的 11.7.0，不用手动管版本。 ③ Git：用来拉源码。 这个上手有一定的难度，很多新手不会用，如果不想及时获取最新的代码，只想针对某个版本学习，可以先不装。 git --version 有版本号就行。不想装 Git 也没关系——下一步给了免 Git 的替代方案。 ④ （可选）一把 DeepSeek API Key：跑真实对话用，去 platform.deepseek.com 注册、实名、充值、生成 Key。这串sk-开头的字符串就是你的身份证，别发到任何公开地方。配 Key 那一步才用到它。
找一个你喜欢的目录，二选一： 方式 A：Git 克隆（推荐，方便以后跟进更新） git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness 方式 B：下载压缩包（免 Git） 在 GitHub 仓库页面点Code → Download ZIP，解压后进入目录： cd deepseek-harness-main
在仓库根目录依次执行： 1. 安装所有子包的依赖（第一次跑 3~10 分钟，取决于网速） pnpm install 2. 构建产物（把 TypeScript 编译成 JavaScript，首次 5~15 分钟） pnpm run build 每一步在干什么： pnpm install 读根目录的 pnpm-workspace.yaml，把 packages/*/*、apps/*、vendor/* 下所有子包的依赖一次性装齐。同时还会自动配置本地的 Git Hook（通过 Lefthook），为你提交代码时做格式校验。 pnpm run build 把所有 TypeScript 源码编译一遍，产物落在每个包的 lib/ 目录。dsh 代码量大，首次构建比较久，后续只会增量编译改动过的部分。
构建完成，直接起 dsh： pnpm dsh web pnpm dsh 是仓库里暴露的 TypeScript 入口（根 package.json 的 scripts 里有定义），走tsx 的 ESM 加载器——简单说就是“不用先 tsc 编译，直接拿 TS 源码跑”。你改一行 .ts，重启立刻生效，调试体验比跑 npm 包好一个量级。 启动成功后，终端打印： dsh web: http://127.0.0.1:3080 把地址复制到浏览器，就进入 dsh 主界面。
dsh 本身只是个“壳”，真正干活的是背后的大模型。本章用DeepSeek（便宜、够用、国内访问稳定）。两种配法二选一： 方式 A：命令行配（推荐，适合从源码跑） 在 dsh 仓库根目录新建 .env 文件（已被 .gitignore，不会误提交）： DEEPSEEK_API_KEY=sk-你的key DEEPSEEK_BASE_URL=https://... # 可选，默认走 DeepSeek 公共 API 然后重启pnpm dsh web，Key 就被自动读到了。 方式 B：Web 界面上填 浏览器里点“设置” → “模型” → 找到 DeepSeek → 粘贴 Key → “保存”。 注意：配置填完 ≠ 一定能调通，Key 对不对、网络通不通，得发一条真实消息才知道。
第一步：选工作区 点页面上的“选择工作区”，挑一个允许 dsh 读写的文件夹（可以新建一个空的叫 dsh-playground）。“工作区”就是 dsh 这次干活的作战地图——它只能在这个范围里读写文件。没选工作区，输入框是灰的发不出消息。 第二步：发条无聊的消息，确认链路通 模型：DeepSeek-V4-Flash（Flash = DeepSeek 的快速版，便宜响应快，这个可能） 推理等级：Max（dsh 把模型的“思考深度”分成几档，Max 最深、质量最好） 发送： 稍等几秒看到回复，就说明“浏览器 → dsh 源码进程 → DeepSeek”整条链路都通了。回复区上方有两块折叠记录： “上下文注入” dsh 发给模型的不只你那句话，还塞了系统提示词、工作区信息等背景。 “Think” 模型在正式答复前“想”了什么。 这两块现在只需要知道“有这个东西，点开能看”就行，后面的“轨迹”会把它们串起来。 输入框下方的状态栏会告诉你花了多少秒、用了多少token。补充一句：token是模型按“片段”计费的单位，一个汉字大概 1~2 token，一次调用的费用 = token 数 × 单价。 调用失败一般三个原因：Key 填错、Key 没余额、网络连不上 DeepSeek，按这个顺序排查。 第三步：让 dsh 干件实在事 同一个会话继续发： 这条提示词明确给了四件事：文件名、内容范围、篇幅、写法规范。好的提示词往往就是这样——不留模糊地带。 发送后，dsh 会调用一个叫Write的工具（dsh 把“写文件”这个能力封装成工具给模型用），执行完给你一个结果摘要。页面底部的“产物”（Deliverables）区域会列出本次生成的所有文件。 但要注意：dsh 说“任务完成”只是模型的汇报，不等于真做对了。要确认，必须去看实际文件。
先核对产物 点“产物”里的 about-dsh.md 预览。对照刚才的四个要求逐条勾：文件名对？内容在讲 dsh？篇幅两三段？全文有没有大写的 DSH？ 再看一眼“轨迹” 核对完产物只能说“结果对”，dsh 中间到底怎么走的？——看“轨迹”（Trace）。回到会话页顶部，切换到“轨迹”标签，你会看到按时间顺序排的事件流： SYSTEM — dsh 塞给模型的系统提示词 USER — 你发的那条消息 CONTEXT — 本次注入的上下文 ASSISTANT — 模型的回复（含“思考”） TOOL — 模型调用了哪个工具、传了什么参数、返回了什么 第一次看别逐条啃。就做一件事：找第二轮里的USER和TOOL两条记录——USER 是你发的“写文件”指令，TOOL 是 dsh 调用 Write 工具时的具体入参和返回。能把它们对上，你就建立了“提示词 → 工具调用 → 实际产物”这条心智链。以后 dsh 行为不符合预期，都是沿着轨迹倒着查。 两个小知识： 想把这段轨迹发给别人看？点顶部的“Session log”就能导出完整日志。 dsh 会把所有会话自动落地到$DSH_HOME/sessions/目录（$DSH_HOME 是 dsh 的数据主目录，默认在你的用户目录下）。下次启动历史会话还在，想清理就删这个目录。
我们本门课的重点是看里面的源码学习TS基础编程，而不是开发Agent应用，所以，我们先来瞅一瞅DSH的源码： packages/ 下 60 多个包一次看完会劝退。本阶段只记三个代表性的： packages/core/：Agent 的核心循环——收到任务 → 调模型 → 调工具 → 回复。整个项目的“大脑”。 packages/llm/：和各家大模型（DeepSeek、Claude、OpenAI 等）通信的适配层。“翻译官”，把 dsh 的请求翻译成每家模型自己的 API 格式。 packages/shell/：让 dsh 能执行 shell 命令的工具。给 Agent 装了一只“手”，可以敲命令。 剩下 60 多个包不用背，知道它们按能力领域拆开就行——fs/ 管文件、web/ 管联网搜索、mcp/ 管 MCP 协议对接、sandbox/ 管沙箱隔离……后面讲到具体话题再去对应的包里看。 apps/ 下只有 4 个入口，你刚才启动的 pnpm dsh web 本质上就是跑 apps/cli 的入口脚本去加载 web profile，页面来自 apps/web： apps/ ├── cli/ ← 命令行入口（dsh 命令本身） ├── web/ ← Web GUI 的 Vite 入口（刚才你打开浏览器用的那个） ├── desktop/ ← 打包成桌面 App（Electron） └── desktop-host/ ← Desktop 的宿主进程 关键认知：apps/只是壳，真正干活的逻辑都在 packages/ 里。Web、CLI、Desktop 共享同一个“大脑”（packages/core）和同一批工具。
环境三件套 Node.js（22.19+ 或 24+）、pnpm（corepack enable）、Git（可选）。安装过程不演示，遇错搜报错原文。 操作路线 获取源码（git clone 或下载 ZIP）→ pnpm install → pnpm run build → pnpm dsh web → 配 Key → 发消息；想自检就加跑 pnpm run typecheck。 验证任务是否真做对，必须看“产物”而不是模型的自夸；想知道中间过程，看“轨迹”。 dsh 源码结构 apps/（壳）、packages/（核心能力，60+ 个包，先记 core / llm / shell 三张脸）。 作业： 验证 Node 版本、用 corepack 把 pnpm 跑到 11.7.0，完成 pnpm install + pnpm run build，再跑一次 pnpm run typecheck，截图发评论区。卡在哪一步就把报错贴出来，评论区互助。 按本节步骤把 dsh 跑起来，让它在你的工作区里生成一个 about-dsh.md。 打开“轨迹”页，找到 Write 工具那条 TOOL 记录，截图发到评论区，并说出三个你看到的字段分别是什么意思。 （拓展作业）在编辑器里打开 packages/ 目录，说说除了 core / llm / shell，你最感兴趣哪个包，为什么。 下集预告：源码跑起来了，先别急着学语法——下节补一件新手保命装备：调试基本功。报错怎么看、断点怎么打，学会这两样，后面每一章你都少卡两小时。
我是纵横，全网第一个把 DSH 源码当教材的课程：从 DeepSeek Harness 源码学 TypeScript 编程。
环境检查：Node.js + pnpm + Git
什么是 pnpm？ 理解成 npm 的升级版：更快、更省磁盘。npm 给每个项目复制一份依赖，100 个项目 100 份；pnpm 通过硬链接共用一份。对 monorepo 友好是它另一个大招。
获取源码
安装依赖、构建
想验证环境就绪？ 跑一次 pnpm run typecheck，没报错就说明依赖、TypeScript 配置都没问题。
启动：pnpm dsh web
几个 dsh 的常用命令（现在先知道，后面章节会详细讲）：
pnpm dsh web 启动 Web 界面（本节用这个） pnpm dsh --profile headless "你的任务" 无界面跑一次任务，打印最终答案就退出 pnpm dsh --dump-config 不启动，只把最终组合出来的插件配置打印出来
什么叫 "profile"？ dsh 把一次运行的所有插件配置打包成一个 profile，web 和 headless 是官方自带的两个。这块是 dsh 的核心架构之一，后续高级课程会专门讲。
配 DeepSeek 的 API Key
配图：在模型设置中填写 DeepSeek API 密钥（截图待补）
发一句话打通链路，再让 dsh 写个文件
你好，请用一句话介绍你自己
配图：模型完成第一次调用并返回一句话介绍（截图待补）
配图：状态栏给出模型、推理等级与本次调用统计（截图待补）
帮我在这个文件夹里新建一个 about-dsh.md，写清楚 dsh 是什么、能做什么，两三段就行，不用太长。全文统一写作小写 dsh。
配图：dsh 调用 Write 创建 about-dsh.md 并给出结果摘要（截图待补）
核对产物，看一眼“执行轨迹”
配图：打开产物并核对 about-dsh.md 的实际内容（截图待补）
配图：轨迹页面按时间排列两轮对话和工具调用（截图待补）
