📖 系列说明：本篇是动手实操篇，跟着做就行，不需要提前了解任何背景知识。需要准备：Node.js 18+、一个 DeepSeek API Key（没有的话文章里有申请入口）。
🎁 读完你会得到：一个真正跑起来的 dsh 实例，以及对 Web UI 各个功能区的基本认知。
上一篇聊了不少 dsh 的设计哲学，这篇不再展开，直接动手。
文档看再多，不如自己跑一遍。10 分钟，让 Agent 真正动起来。
先把环境准备好
dsh 基于 Node.js，所以第一件事是确认你的 Node.js 版本够不够。
node -v
输出 v18.x.x 或更高就行。低于 18 的话，去 nodejs.org 装一个 LTS 版本，5 分钟的事。
API Key 也要提前准备好。dsh 默认接 DeepSeek 的模型，去 platform.deepseek.com 注册，新用户有免费额度，够你把这篇文章跑完。
方式一：npx 一行启动（推荐先试这个）
不需要安装任何东西，直接跑：
npx @deepseek-ai/dsh web
第一次运行会下载依赖，大概等 30 秒。看到这行输出就说明起来了：
Web UI running at http://127.0.0.1:3080
打开浏览器，访问 http://127.0.0.1:3080，你会看到 dsh 的 Web UI。
这就是 dsh 的"身体"——Agent 通过这个界面和你交互，读你的文件，跑你的命令，告诉你它在做什么。
配置 API Key：两分钟搞定
Web UI 打开后，先别急着发消息。右上角有个设置图标，点进去，找到模型选项卡。
把你的 DeepSeek API Key 粘贴进去，点保存。
不需要重启，模型路由立刻生效。
💡 用其他模型也行：dsh 支持任何 OpenAI 兼容的 API。如果你有 OpenAI、Claude、Qwen 的 Key，在模型配置里填上 Base URL 和 Key 就能切换。这就是"一切皆插件"的好处——换模型不需要改代码。
选工作区：告诉 Agent 它能碰哪些文件
配置好模型，还有一步——选工作区。
工作区就是 Agent 的"操作范围"。它能读哪些文件、改哪些代码、跑哪些命令，都限定在这个目录里。
点击界面上的选择工作区，把你想让 Agent 操作的项目目录加进去，然后选中它。
选中之前，会话输入框是灰色的，没法发消息。这不是 bug，是设计——没有工作区，Agent 不知道该在哪里干活。
发第一条指令，看 Agent 动起来
工作区选好了，可以发消息了。
先试个简单的，让 Agent 认识一下你的项目：
帮我总结一下这个仓库的结构，主要有哪些模块？
发出去之后，你会看到 Agent 开始工作——它会读文件、分析目录结构，然后给你一个总结。
这个过程可能要 10-30 秒，取决于项目大小。你能看到它在做什么：读了哪个文件、发现了什么、下一步打算干什么。这就是 dsh 的 Trajectory 视图——模型的每一步都可见，不是黑盒。
试完这个，可以发一个更有挑战性的：
找一下项目里有没有明显的代码重复，给我列出来
这次 Agent 会自己决定：先搜索文件、再读内容、再分析、再汇总。整个过程你不用管，它自己跑。
遇到"需要审批"怎么办
有时候 Agent 要做某些操作——比如修改文件、跑命令——界面会弹出一个确认框，问你"允许吗"。
这是 dsh 的审批策略在起作用。不是所有操作都需要审批，只有被标记为"敏感"的操作才会问你。
点允许，Agent 继续。点拒绝，Agent 会换个方式或者告诉你它做不了。
对于刚上手的人，建议先保持默认设置——遇到审批就看一眼，确认没问题再放行。等熟悉了 Agent 的行为模式，再考虑调整哪些操作可以自动放行。
方式二：从 源码 安装（想深入研究的看这里）
npx 方式够用了，但如果你想改 dsh 的源码、开发插件、或者研究它的内部实现，就需要从源码安装。
# 克隆仓库
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
# 安装依赖（需要 pnpm，没有的话先装：npm install -g pnpm）
pnpm install
# 构建
pnpm run build
# 启动
pnpm dsh web
源码安装之后，你可以：
- 直接修改
packages/ 下的核心包代码
- 用
--patch 参数加载本地插件（后面第 03 篇会详细讲）
- 跑
pnpm dsh --dump-config 看完整的配置树，了解 dsh 启动时加载了哪些插件
对于只是想用 dsh 的人，npx 就够了。对于想开发插件或者研究框架的人，源码安装是必须的。
几个常见问题
Q：启动后访问 http://127.0.0.1:3080 打不开？
检查端口有没有被占用：lsof -i :3080。如果有其他进程占了，换个端口：npx @deepseek-ai/dsh web --port 3081。
Q：配置了 API Key，但发消息没有回复？
打开浏览器开发者工具看网络请求，确认 API 请求有没有发出去、返回了什么错误。常见原因：Key 填错了、账户余额不足、网络问题。
Q：工作区选了，但 Agent 说找不到文件？
确认工作区路径是绝对路径，而且 dsh 进程有读取该目录的权限。macOS 上有时候需要在系统设置里给终端授权"完全磁盘访问"。
Q：想同时用多个工作区怎么办？
可以在工作区管理里添加多个目录，然后在会话里切换。不过 Agent 一次只能操作一个活跃工作区。
Q：npx 每次都要重新下载吗？
不会，npm 会缓存。但如果 dsh 发布了新版本，npx 会自动拉取最新版。如果不想自动更新，可以固定版本：npx @deepseek-ai/dsh@0.x.x web。
跑起来之后，可以试试这些
Web UI 跑起来了，API Key 配好了，工作区选好了。接下来可以试试这些场景，感受一下 dsh 能做什么：
代码理解：
解释一下 src/core/agent-loop.ts 这个文件的主要逻辑
代码修改：
帮我给 utils/helper.ts 里的所有函数加上 JSDoc 注释
问题排查：
项目跑 npm test 报错了，帮我看看是什么问题
文档生成：
根据 README.md 的现有内容，帮我补充一个"快速上手"章节
每个任务发出去之后，注意观察 Agent 的工作过程——它读了哪些文件、做了哪些判断、调用了哪些工具。这个过程比最终结果更值得看，因为它告诉你 Agent 是怎么思考的。
一个值得注意的细节
dsh 启动时所在的目录，会被当作默认的文件系统位置。
这意味着：如果你在 /Users/me/projects/my-app 目录下启动 dsh，Agent 默认就能访问这个目录下的文件。如果你在 / 根目录下启动，理论上 Agent 能访问整个文件系统（当然，沙箱和权限策略会限制它）。
所以养成一个习惯：在你想让 Agent 操作的项目目录下启动 dsh，而不是随便找个地方启动。
📝 小结
- dsh 启动只需要一行：
npx @deepseek-ai/dsh web，Node.js 18+ 即可
- 启动后三步走：配置 API Key → 选工作区 → 发第一条指令
- 工作区是 Agent 的操作范围，没选工作区就没法发消息
- 审批策略会在敏感操作前弹出确认，这是安全机制，不是 bug
- 想开发插件或研究源码，用
git clone + pnpm install 的方式安装
- 在项目目录下启动 dsh，而不是随便找个地方启动
🔮 下一篇预告
dsh 跑起来了，但你现在用的是它的默认能力。
如果你想给 Agent 加一个自定义工具——比如让它能查你们公司的内部 API、或者操作你的数据库——怎么做？
下一篇，我们从最简单的插件开始写起，搞清楚 dsh 的插件机制是怎么运转的。
📚 系列导航
- 第 01 篇：凭什么说它是下一代 Agent 框架？
- 第 02 篇：10 分钟跑起来：从安装到第一个任务 ⬅️ 你在这里
- 第 03 篇：插件开发入门：从 Hello World 到真正有用的插件
- 第 04 篇：工具开发实战：给 Agent 装上你自己的工具
- 第 05 篇：架构深度解析：轮次、事件、会话日志的运转机制
- 第 06 篇：多 Agent 协作：子代理、工作流与 Teams
- 第 07 篇：研发场景落地：代码审查、CI 集成与自动化测试
- 第 08 篇：安全与权限：沙箱配置、审批策略与审计日志
- 第 09 篇：业务流程自动化：审批流、数据处理与报告生成
- 第 10 篇：中小企业实战（一）：从 0 搭一个能上线的智能客服系统
- 第 11 篇：中小企业实战（二）：内部知识库问答 Agent，让文档真正被用起来
- 第 12 篇：中小企业实战（三）：销售流程自动化，报价跟进周报一键搞定
引用链接
更多 Agent 开发与 AI 工程化的实战资源，可以在 云栈社区 找到。
发表于 前天 20:16
|
查看: 0|
回复: 0
