内容阅读

从 0 跑起来：first run 全流程

这一篇不讲架构，只讲一件事：让 dsh 在你机器上真正跑起来，配好模型，选好工作区，发出第一条任务，并看懂它回来时带着什么。看完你应该能独立完成一次完整的 Web UI 会话，并对"一个 agent harness 在第一次运行时到底做了哪些事"有体感——这体感是整个系列架构拆解的地基。

前置条件

Node.js。npx 方式只需要一个能跑的 Node。官方没有钉死最低版本，但 dsh 是活跃迭代的 ESM/TypeScript 工程，建议用较新的 LTS（18 或 20 以上），避免老版本的 fetch、原生 ESM 边界问题。
一个模型 API Key。默认路径是 DeepSeek 官方 API key；如果你想用别的，dsh 支持任意 OpenAI 兼容端点（见下文"配模型"）。
一个工作目录。dsh 启动时，会用你执行命令的当前目录作为默认的文件系统位置。所以"在哪个目录启动"是有意义的，不是随便挑的。

满足这三条就能开始。不需要先 clone 仓库、不需要装 pnpm、不需要编译——npx 会拉取已发布的包。

两种启动方式

方式一：`npx`（推荐第一次用）

第一次跑只需一句 npx @deepseek-ai/dsh web。这句命令做三件事：拉取 @deepseek-ai/dsh 包、用 web profile 启动、起一个 Web UI 服务。命令执行后会打印一个本地地址，默认是 http://127.0.0.1:3080，浏览器打开它，就进了 Web UI。这是绝大多数人第一次接触 dsh 的姿势，也是本文主讲的路径。

方式二：从源码跑（想读代码 / 改代码再用）

如果你打算读源码、写插件、或跟踪 master 最新改动，从仓库跑：先 git clone https://github.com/deepseek-ai/deepseek-harness.git 拿到仓库，cd deepseek-harness 进目录，pnpm install 装依赖，pnpm run build 构建一遍，最后 pnpm dsh web 启动。

这个方式需要 pnpm，且要跑一遍 build。它的好处是你拿到了完整源码——本系列后面所有"源码导读"篇（06、08、10、14、16）都默认你手上有一份 checkout。第一次跑通选 npx 即可，等读到源码篇再切到这种方式。

顺带说一句：web 和 headless 是两个内置 profile 模板。web 起带界面的服务；headless 是一次性 runner，不开 server，接一个任务跑完就退出（40 篇讲自动化集成时会用它）。本文只讲 web。

第一步：配模型

打开 Web UI 后，第一件事不是发消息——是配模型。一个全新的 dsh 没有任何可用的模型路由，发消息会失败。

路径：Settings → Models。

填入你的 DeepSeek API key 并保存。这里有个细节值得记住：保存后模型路由立即生效，不需要重启服务。 这不是 UX 上的小聪明，而是架构决定的——dsh 的凭证（ctx.credentials）是每次操作时解析的，所以一个轮换过的 key 会在下一次请求就生效。这套机制的代价和细节在 35 篇讲，这里你只要知道：改完 key 直接用，别等重启。

用别的模型（OpenAI 兼容端点）

dsh 不锁 DeepSeek 模型。在模型配置里，你可以填任意 OpenAI 兼容的端点（base URL + key + 模型名）。官方把它设计成 ctx.llm 接缝上的多个 provider——llm-deepseek、llm-pi-ai 都是这么挂上去的，你自己挂一个兼容适配器也是同一条路（18 篇带你写一个）。

第一次跑，建议先用 DeepSeek 官方 key，把链路打通；之后再换别的模型对比。

第二步：选工作区（workspace）

这是新手最容易卡的一步。

dsh 进程虽然用启动目录作默认文件系统位置，但一个全新的 Web UI 没有选中任何工作区，在你添加并选中一个之前，会话输入框是不可用的。

路径：点 Choose workspace，把你启动 dsh 时所在的那个项目目录加进来，然后选中它。

为什么要有这一步？因为 dsh 的文件系统（ctx.fs）是个可替换接缝（20 篇专讲），"agent 能动哪些文件"是一个被显式管理的边界，不是"当前目录随便扫"。选 workspace 就是在划这条边界。选好之后，会话输入框才可用，agent 才能在那个目录里读文件、编辑文件、跑命令。

一个实用建议：第一次拿一个你不在乎被改的小项目练手，或者直接拿 dsh 自己的仓库。别一上来就拿生产仓库试——即便有审批，第一次跑先建立对行为的信任更重要。

第三步：发第一个任务

新建一个会话，发一句足够具体、又能让 agent 真正动手的任务。官方 guide 给的例子是：

Summarize this repository and identify its main packages.

这是一个好选择：它要求 agent 读文件、形成判断、输出结构化结论，但又不会改任何东西，适合第一次观察。如果你在 dsh 自己的仓库里跑，agent 应该能读出 packages/、docs/、apps/ 这些顶层结构，并按职责归类。

发出去之后，观察几件事——这些观察比"任务做对了没"更重要，因为它们是你理解 agent 内部行为的窗口：

1. 它在"读"，不是在"猜"。 一个健康的 agent harness，回答仓库结构类问题前会真的去读目录、读文件，而不是凭模型先验瞎编。你会看到它调用读文件/列目录的工具。如果它不读就直接长篇大论，说明上下文或工具出了问题。

2. 需要审批的操作会停下来问你。 dsh 在当前权限策略下，对需要批准的操作会先询问。读操作通常顺畅通过；写文件、跑命令这类有副作用的操作，取决于你的权限预设（19 篇讲 workspace-write / danger-full-access 这些预设）。第一次跑，让它多问几次是好事——你能借此看清它的行为边界。

3. 它的输出是可以"复盘"的。 一个 turn 结束后，你看到的不是一段孤立的文字，而是一串有结构的动作：读了哪些文件、调了哪些工具、每步结果是什么。这些都会被记进会话日志（09 篇讲为什么"模型可见即可重建"）。换句话说，它的回答是可审计的，不是黑盒。

看懂你刚看到的东西

第一次跑完，你大概会对 dsh 形成一个直觉：它不是"聊天框 + 代码补全"，而是一个会主动读文件、跑命令、在你授权下改东西的代理。这个直觉是对的，但还很粗。本系列剩下的文章，就是在把这个直觉拆成可理解的机制。

对应到你刚才那次会话，发生的事情大致是（07 篇详拆）：

你发的消息进入一个 inbox，唤醒了驱动器（agent-loop）。
驱动器开了一个 turn，取出你的输入，组装系统提示和工具 schema，向模型发请求。
模型决定调用工具（比如读文件），于是产生 tool/call → 工具执行管线（13 篇）→ tool/result。
工具结果回到模型，模型可能再调一次工具，或者给出最终回答。
整个过程的事件被追加到会话日志，UI 从日志渲染出你看到的那串动作。

而那个"需要审批时停下来问你"的行为，背后是 tools/pre-execute 关卡和 ctx.approval 接缝（13、19 篇）。

所以第一次跑的意义，不在于"任务完成得多漂亮"，而在于你亲眼看到了一个 agent harness 的那些子系统在协作。后面每一篇，都是在单独拎出一个子系统讲清楚。

常见卡点

卡点一：发了消息没反应 / 报模型错误。 几乎总是模型没配好——key 没存、key 失效、或端点填错。回到 Settings → Models 检查。记住改完即生效，不用重启。

卡点二：会话输入框灰着不能用。 没选 workspace。回到 Choose workspace，添加并选中一个目录。

卡点三：agent 改不了文件 / 命令被拒。 权限预设太严。dsh 默认偏保守，写操作和命令执行可能被拦。第一次跑如果是只读任务（如总结仓库），不影响；如果要它改东西，留意审批提示，或在权限设置里调整（19、37 篇讲怎么调）。

卡点四：npx 拉包慢或失败。 网络/镜像问题，和 dsh 本身无关。换镜像源或用源码方式跑。

卡点五：端口 3080 被占。 启动时会打印实际地址；若要换端口，查 CLI 参数（40 篇讲 headless/CLI 模式时覆盖）。

第一次跑之后

跑通一次完整会话，你就拿到了本系列所有架构拆解的"参照物"。后面读到 turn/step、会话日志、工具管线、接缝这些概念时，随时可以回来对照："我那次会话里，这一步对应的是哪个机制？"

一个建议：保留你第一次跑的那个会话。dsh 的会话是可 fork、可 resume 的（09 篇），第一次的会话日志是个现成的样本，后面读源码导读时可以拿它当例子对照。

如果你想立刻往深里走，下一篇 03 开始讲 Cordis——那是"一切皆插件"能成立的底层框架，也是整个系列的认知门槛。如果你想先停在"能用"，把第一次会话的每个行为和本文的"看懂你刚看到的东西"对照一遍，就足够建立后续阅读的直觉了。

还没有评论

欢迎留下第一条评论，帮助这篇内容更快形成讨论。

从 0 跑起来：first run 全流程