第3章 三个关键词:API、Agent、Harness
API、Agent、Harness 经常被混为一谈。这一章用一张分层图和三个类比,把它们各自的职责、边界和协作关系讲清楚。
本章共 7 节,另附练习,建议按顺序阅读:
DeepSeek API 是什么
一句话:API 是“调用模型”的接口。 你给它 messages,它返回 completion,按 token 计费。它不是 App,不是 Agent,也不是 Harness。它像电源插座:通电的是后面的模型,插座本身不会替你干活。
身份:在 https://platform.deepseek.com/ 创建 API Key,调用时带上。Key 就是钱袋子,泄露了别人可以拿你的额度跑任务。
协议:基础地址是 https://api.deepseek.com ,兼容 OpenAI Chat Completions,所以可以直接用 OpenAI SDK:
也提供 Anthropic 兼容入口:https://api.deepseek.com/anthropic 。很多现成工具和框架可以低成本接进来。
计费:按 token,不按“次数”。截至 2026 年 11 月,官方文档的主力模型与价格如下(元/百万 tokens,实际以官网价格页为准):
| 模型 | 定位 | 缓存命中(空闲/高峰) | 未命中(空闲/高峰) | 输出(空闲/高峰) |
|---|---|---|---|---|
| deepseek-flash | 日常主力,快、便宜,支持图片理解 | 0.02 / 0.04 | 1 / 2 | 4 / 8 |
| deepseek-v4-pro | 更强推理,复杂任务 | 0.15 / 0.30 | 4.5 / 9.0 | 13.5 / 27.0 |
高峰是北京时间周一至周五(非法定节假日)9:00–12:00、14:00–18:00;其余时间(含周末、节假日全天)为空闲,空闲价通常是高峰的一半。两个直接含义:上下文不是免费的;缓存能省钱(重复使用同一段长前缀,命中后价格大幅下降)。
能力与限制:deepseek-flash 上下文 1M tokens、最大输出 384K,支持文本、图片理解、JSON、Tool Calls、前缀续写、FIM(仅非思考);deepseek-v4-pro 同样 1M/384K,但不支持图片。思考模式默认开启,可关闭或调强度。
模型名会更新。官方文档里的 deepseek-v4-flash 是旧名,可能被映射到新模型。写代码以模型页/价格页为准,不要死记。
API 不做什么:
| 你以为 API 会 | 实际 |
|---|---|
| 自己上网查最新资料 | 不会,联网要外层搜索/抓取工具 |
| 读你电脑里的文件 | 不会,文件要由宿主程序读入 |
| 记住上次对话 | 不会,每次请求都要带历史 messages |
| 自动执行代码 | 不会,执行要沙箱/运行器 |
| 保证说的都是真的 | 不会,它生成概率上合理的文本 |
| 替你登录网站、点按钮 | 不会,那要浏览器自动化或专用连接器 |
所以,API 是“大脑的接口”,不是“完整的人”。
Agent 是什么
一句话:Agent = 模型 + 循环 + 工具 + 上下文 + 约束。
- 模型负责想;
- 循环负责做—看—改;
- 工具负责接触世界;
- 上下文负责知道什么;
- 约束负责不闯祸。
一个类比:模型是知识面广但只能坐在房间里说话的顾问;API 是电话线;工具是手、眼睛、计算器、文件柜;Agent 是顾问加电话线加手加流程;Harness 是整间办公室,包括工位、门禁、监控、档案柜、工具箱。
顾问再聪明,没有手也只能说;有了手没流程会乱翻;有流程没门禁可能把房子点了。Agent 的工程质量,主要不在“模型多聪明”,而在这套结构。
| 维度 | Chatbot | Agent |
|---|---|---|
| 输入 | 一句话 | 目标 + 上下文 + 约束 |
| 输出 | 一段文字 | 文件、代码、报告、操作结果 |
| 过程 | 一次生成 | 多步循环,可回退 |
| 工具 | 基本没有 | 文件、命令、搜索、API、子代理 |
| 验证 | 靠人看 | 跑测试、对照、抽查、自检 |
| 失败 | 说错话 | 可能改错文件、执行错命令 |
| 责任 | 你判断 | 仍然是你,但多了审批点 |
四种常见失败:幻觉式行动(没读文件就说改好了);局部最优(修了报错,破坏别的功能);循环(同一命令反复失败);越权(删了不该删的)。好的 Harness 不会让这些消失,但会让它们更早暴露、更容易回滚。
Harness 是什么
一句话:Harness 是 Agent 的运行外壳。 它把模型、工具、会话、权限、界面、日志、扩展组织成可用产品。
没有 Harness 也能用 API 写 Agent,但你要自己解决:模型怎么接、key 怎么存;工具怎么注册、参数怎么校验;会话怎么保存、上下文怎么压缩;哪些操作要审批、记录在哪;前端怎么显示、文件怎么传;插件怎么装、怎么隔离。
DSH 把这些做成可组装的运行时。官方描述它基于 Cordis:一切皆插件,模型适配器、工具注册表、会话日志、agent loop 本身都是插件;profile 组合,一个运行中的 dsh 就是一棵按 profile 组装的插件树;可替换,换模型、加工具、改 UI、接 MCP 不必改核心;多入口,Web UI、TUI、headless、Python SDK、ACP。
DSH 能做什么
- 读写工作区文件、搜索文件内容;
- 执行命令、跑测试、跑构建;
- 浏览/抓取网页(在工具与网络允许范围内);
- 维护任务计划;
- 委派子代理并行处理独立子任务;
- 通过 MCP 连接数据库、知识库、内部 API;
- 通过插件扩展工具与界面;
- 用 Schedule 创建定时提醒/自动化任务;
- 用 headless 做一次性脚本化任务;
- 用 Python SDK 把 Agent 集成进应用;
- 记录会话、压缩上下文、恢复历史。
DSH 不能做什么
| 不能 | 原因 | 你该怎么做 |
|---|---|---|
| 保证答案正确 | 概率生成,不是数据库 | 要依据、跑测试、做对照 |
| 替你承担后果 | 责任在人 | 关键操作自己审批、复核 |
| 访问你没给它的东西 | 权限与上下文边界 | 明确提供文件/目录/连接器 |
| 默认拥有长期记忆 | 记忆 MCP 默认关闭 | 重要结论写进文件,或配置记忆服务 |
| 电脑关机时执行定时任务 | 调度依赖宿主进程 | 用常开机器,或接受补跑 |
| 自动安装所有依赖 | 环境问题需要判断 | 先检查环境、给出安装命令 |
| 突破沙箱/审批 | 安全边界 | 不要绕过,调整权限策略 |
| 替代法务/安全/财务审计 | 专业责任 | 当助手,不当签字人 |
| 把模糊需求自动变清晰 | 它只能猜或反问 | 你先写验收标准 |
| 保证一次成功 | 复杂任务天然多轮 | 小步走、早验证、留回滚 |
一句话:Harness 扩展的是行动半径,不是正确性保证。
三者关系
- API 提供思考能力;
- Agent 把思考变成多步行动;
- Harness 把行动装进可管理、可扩展、可审计的外壳。
只有 API:得到一个会说话的模型;API + Agent:得到一个能动手的脚本;三者齐全:得到一个能日常使用、能扩展、能交付的系统。
五个常见误解
- DSH 是一个模型:不是,它是运行台,模型可以是 DeepSeek 或第三方。
- 用了 Harness 就不会幻觉:不会,只是更容易验证和拦截。
- Agent 越自主越好:不对,自主性越高,越需要权限、审批、回滚、监控。
- API 和网页版是一回事:不是,API 按量计费、要 key、要自己写调用。
- 有了 Agent 就不用学编程:见第 2 章。结论是:语法记忆贬值,读代码、拆问题、验证结果升值。
本章练习
用一句话分别解释 API、Agent、Harness,不能使用“智能”“强大”;画出你理解的模型—工具—人关系图;列出 3 个“API 能帮上忙但 API 本身做不到”的环节。
《DeepSeek Harness 实战课》课程目录
面向应用者的 DeepSeek Harness 实战课:讲清 API、Agent、Harness 三者关系,带你安装 DSH、写出可验收任务、让 Agent 读文件改代码跑测试、接 MCP/插件、做定时任务,并划清安全边界