🎯 目标：跑起 dsh，完成第一轮对话 难度 ★☆☆ ⏱ 约 15 分钟 前置：会用命令行
本系列基于代码库 deepseek-ai/deepseek-harness（版本 0.1.0-rc.5，MIT 协议）。项目处于 developer preview 阶段，界面与命令可能随版本微调，请以官方 README 为准。仓库：github.com/deepseek-ai/deepseek-harness

一、环境准备

DeepSeek Harness（简称 dsh）是一个 Agent 运行时框架，你需要先有一台装好 Node.js ≥ 22.19 的电脑。Windows、macOS、Linux 均可。

先确认你的 Node.js 版本：

bash
$ node -v v22.19.0 $ npm -v 10.9.0
如果版本号低于 22.19，请先到 nodejs.org 升级到 LTS 或更新版本，再继续。这是唯一硬性前置条件。

二、一键启动

无需克隆仓库、无需手动编译，直接通过 npx 启动。第一次运行会自动下载依赖，耐心等它完成即可：

bash
$ npx @deepseek-ai/dsh web Need to install the following packages: @deepseek-ai/dsh@0.1.0-rc.5 Ok to proceed? (y) y ... DeepSeek Harness web app running at http://127.0.0.1:3080

看到 http://127.0.0.1:3080 就说明启动成功。用浏览器打开这个地址，你会看到 dsh 的 Web 界面。

图 1 · 从启动到打开界面 💻 你的电脑 Windows/macOS/Linux Node.js ≥ 22.19 npx @deepseek-ai /dsh web dsh 进程 监听 :3080 🌐 浏览器 127.0.0.1:3080
图 1 启动链路：命令在本地起一个 dsh 进程，浏览器连的是你本机的 3080 端口。

三、首次配置模型

dsh 本身不带模型，需要接入一个 LLM。以基座的 DeepSeek 模型为例，你需要在配置面板里填入 API Key 并选择模型。

  • 在界面中找到 配置（Settings） 面板；
  • 填入你的模型 API Key（DeepSeek 官方开放平台可申请）；
  • 选择或填写模型名（如 deepseek-chat）；
  • 保存后回到对话界面。
    • dsh 通过「能力接缝（seam）」设计支持任意 OpenAI 兼容模型——第 21 讲会教你如何替换成其他模型。现在先用 DeepSeek 基座跑通即可。

    四、认识 Web UI 五大区域

    界面主要分五个区域，先混个脸熟，后面几讲会逐区深入：

    图 2 · Web UI 布局示意（五大区域） http://127.0.0.1:3080 ① 会话列表 当前会话 历史会话 1 历史会话 2 ② 消息流 帮我看看这个项目的 README 好的，我先用 read 工具读取文件… 📄 read("README.md") ③ 工具调用卡片 read / write / bash / web_search / 终端… ④ 审批弹窗（ApprovalRequest） 同意 拒绝 ⑤ 配置面板
    图 2 五大区域：①会话列表 ②消息流 ③工具调用卡片 ④审批弹窗 ⑤配置面板。图中为抽象示意，实际布局以版本为准。
    区域作用你会在第几讲深入 ① 会话列表新建 / 切换 / 恢复（resume）/ 分支（fork）会话第 2、6 讲 ② 消息流你与 agent 的对话主舞台第 2 讲 ③ 工具调用卡片模型每次"伸手干活"都可见第 5、11 讲 ④ 审批弹窗敏感操作征求你同意（可配策略）第 10、18 讲 ⑤ 配置面板模型、密钥、插件、权限预设第 8、9 讲

    五、看懂一轮对话：工具调用与审批

    dsh 不是"一问一答"的聊天机器人，而是会动手干活的 agent。你发一句话后，它会经历"思考 → 调用工具 → （可能征求你同意）→ 执行 → 再思考 → 回答"的循环。理解这个闭环，是后续所有内容的钥匙：

    图 3 · 一轮对话的工具调用闭环 👤 用户发消息 🧠 模型思考 🛠 决定调用工具 🚦 审批请求 ⚙️ 执行工具 ✅ 回答用户 ✅ 同意 → 继续执行 结果回填给模型 ⛔ 拒绝 → 中止操作 回到模型
    图 3 闭环：模型每次动手前先"思考"，敏感操作会停下征求你同意——同意则执行、拒绝则中止并让模型换个思路。

    六、动手练习

    现在做一次真实任务，体会完整的闭环。在消息框里输入：

    请在当前目录新建一个 hello.md 文件，写入"Hello, DeepSeek Harness!"，然后告诉我你做了什么。

    你会依次看到：模型调用 write 工具 → 可能弹出审批框 → 你点「同意」→ 文件被创建 → 模型汇报结果。整个过程对应图 3 的每一个节点。

    第一次跑请留意：让 agent 写文件属于敏感操作，默认会触发审批。这是 dsh 的安全机制，不是 bug——第 18 讲会教你如何按需放宽。

    七、常见坑

  • Node 版本不够：npx 报错或运行异常，先 node -v 确认 ≥ 22.19；
  • 端口被占用：3080 已被别的程序占用时，按官方文档指定其他端口；
  • 首次启动很慢：npx 在下载依赖，属正常现象，请勿中途 Ctrl+C；
  • 模型没反应：检查配置面板里的 API Key 是否正确、是否还有额度；
  • 界面和我截图不一样：preview 阶段界面会变，认准"五大区域"的功能而非具体按钮位置。

    • 八、官方文档对应章节

  • README 的 Quickstart（安装与启动）
  • docs/ 安装与配置章节
    • 下一讲预告 · 第 2 讲「Web UI 完全指南」：把五大区域逐个吃透，学会用 fork 做"分支实验"，让 agent 在多步骤任务里如臂使指。
    — 扫码关注 / 加微信 —
    公众号二维码
    公众号
    「A0清风远技术服务」
    微信二维码
    微信
    技术交流 · 反馈

    个人观点，仅供参考，如有不对之处，请多包涵，欢迎指出。本文由AI协助完成！