第3讲 · 四种运行形态

《DeepSeek Harness 从上手到精通》系列 · 第一阶快速上手篇

🎯 目标：掌握 Web GUI 之外的调用方式，嵌入脚本与系统难度 ★☆☆ ⏱ 约 25 分钟前置：第 1 讲已跑起 dsh

系列基于 deepseek-ai/deepseek-harness（0.1.0-rc.5，MIT）。preview 阶段命令与参数可能微调，请以官方 README 为准。

一、为什么需要四种形态

第 2 讲我们泡在了 Web UI 里。但真实工程里，你不会总开着浏览器盯着 agent 干活。有时要一行命令跑完、有时要在终端里交互、有时要用 Python 把它塞进自己的脚本，还有时要让别的系统把它当 Agent 后端调用。这就是 dsh 的四种运行形态。

四种运行形态总览 — **图 1** dsh 的四种运行形态：CLI、TUI、Python SDK、ACP。

二、Headless：一次性命令运行

Headless 模式就是"无头"运行：给任务、拿结果、退出。最适合 CI、定时脚本、批处理。

# 非交互式运行：让 agent 完成一次任务
npx @deepseek-ai/dsh headless \
  --prompt "分析当前目录的 README.md，给出 3 条改进建议" \
  --profile headless

要点 1：Headless 默认按预设策略执行审批，适合无人值守场景；
要点 2：可接 STDIN 传入大段上下文，结果走 STDOUT/文件输出；
适用：GitHub Actions、 nightly 脚本、自动化报告。

三、TUI：终端里的交互体验

不喜欢浏览器，又想要交互？TUI（Terminal UI）模式在命令行里给你一个可操作的界面。

npx @deepseek-ai/dsh tui

TUI 保留了会话列表、消息流、工具卡片和审批弹窗，只是全部在终端里渲染。适合：

远程服务器上不方便开浏览器；
喜欢键盘驱动、不想被鼠标打断。

四、Python SDK：把 dsh 当成一个库

Python 工程师的友好入口。python/sdk 提供了声明式的调用方式。

# 需要先安装：pip install deepseek-harness-sdk
from deepseek_harness import Agent

agent = Agent(profile="headless")
result = agent.run("帮我总结这篇文章的要点。", context="...")
print(result)

当前 Python SDK 仍处于早期封装阶段，接口变化较快。建议先用 CLI/TUI 验证行为，再用 SDK 封装进自己的流程。

五、ACP：让 dsh 成为其他系统的 Agent 后端

ACP（Agent Communication Protocol）是 dsh 对外暴露的协议层。启动 ACP 服务后，IDE、聊天客户端、网页前端都能把 dsh 当作一个 Agent 后端来调用。

ACP 协议接入示意 — **图 2** ACP 让 dsh 成为多客户端共享的 Agent 后端。

# 启动 ACP 服务
npx @deepseek-ai/dsh acp --port 3081

ACP 是路线 B/C 读者的重点，第 15–17 讲会结合 subagent/workflow 做更深入编排。

六、一张表看懂适用场景

形态	触发命令	最像什么	何时用
Headless	`dsh headless`	脚本命令	CI、批处理
TUI	`dsh tui`	终端 App	服务器、键盘党
Python SDK	`Agent.run()`	Python 库	嵌入 Python 项目
ACP	`dsh acp`	后端服务	被 IDE/前端/其他客户端调用

七、动手练习

分别用 Headless 和 TUI 完成同一个任务：让 dsh 列出当前目录下所有 .md 文件，并生成一段摘要。

# Headless 版本
npx @deepseek-ai/dsh headless \
  --prompt "列出当前目录的 .md 文件并总结内容" \
  --profile headless

# TUI 版本
npx @deepseek-ai/dsh tui
# 然后在界面里输入同样的 prompt

对比两者的输出体验和速度差异，你就知道自己更适合哪种形态。

八、常见坑

Headless 权限不足：无人值守时建议提前配置好 permission preset，否则每个敏感操作都会卡住；
TUI 终端不支持：Windows 自带 cmd 体验较差，建议用 Windows Terminal / iTerm2 / alacritty；
Python SDK 装不上：项目用 hatch/uv 构建，确保 Python ≥ 3.10 且 uv 已安装；
ACP 端口冲突：默认 3081，若被占用加 --port 参数换一个。

九、官方文档对应章节

README 中 Running 相关章节
docs/ 中 CLI、TUI、SDK、ACP 入口文档

本讲内容基于 DeepSeek Harness 官方文档与项目源码整理，仅供学习参考，具体命令与配置请以官方最新版本为准。源码仓库：https://github.com/deepseek-ai/deepseek-harness

咨询 DeepSeek Harness 相关问题，请加微信：A0qingfengyuan_01

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

DeepSeek Harness 教程 · 第3讲 四种运行形态