第3章 三个关键词:API、Agent、Harness

第 3 节 / 共 13 节 课程:DeepSeek Harness 实战课

API、Agent、Harness 经常被混为一谈。这一章用一张分层图和三个类比,把它们各自的职责、边界和协作关系讲清楚。

Harness(DSH):会话 / 工作区 / 权限 / 工具 / 插件 / 日志Agent计划 → 行动 → 验证决定下一步做什么工具:文件 / 命令 / 搜索 / MCP / 子代理接触真实世界,也带来真实风险DeepSeek API · 模型提供思考能力,按 token 计费调用推理
图 3-1 Harness 是外壳,Agent 是循环,API 是大脑接口

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:

# pip install openai
from openai import OpenAI
 
client = OpenAI(
    api_key="sk-你的key",
    base_url="https://api.deepseek.com",
)
 
resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "system", "content": "你是一个严谨的技术编辑。"},
        {"role": "user", "content": "用三句话解释什么是 API。"},
    ],
)
 
print(resp.choices[0].message.content)

也提供 Anthropic 兼容入口:https://api.deepseek.com/anthropic 。很多现成工具和框架可以低成本接进来。

计费:按 token,不按“次数”。截至 2026 年 11 月,官方文档的主力模型与价格如下(元/百万 tokens,实际以官网价格页为准):

模型定位缓存命中(空闲/高峰)未命中(空闲/高峰)输出(空闲/高峰)
deepseek-flash日常主力,快、便宜,支持图片理解0.02 / 0.041 / 24 / 8
deepseek-v4-pro更强推理,复杂任务0.15 / 0.304.5 / 9.013.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 的工程质量,主要不在“模型多聪明”,而在这套结构。

维度ChatbotAgent
输入一句话目标 + 上下文 + 约束
输出一段文字文件、代码、报告、操作结果
过程一次生成多步循环,可回退
工具基本没有文件、命令、搜索、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 扩展的是行动半径,不是正确性保证。

三者关系

┌──────────────────────────────────────────────┐
│ Harness(DSH) │
│ 会话 / 工作区 / 权限 / 工具 / 插件 / 日志 │
│ │
│ ┌──────────────┐ ┌─────────────────┐ │
│ │ Agent │─────▶│ 工具(文件/命令/ │ │
│ │ 计划-行动-验证│◀─────│ 搜索/MCP/子代理)│ │
│ └──────┬───────┘ └─────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ DeepSeek API│ ← 模型(deepseek-flash) │
│ └──────────────┘ │
└──────────────────────────────────────────────┘
  • API 提供思考能力;
  • Agent 把思考变成多步行动;
  • Harness 把行动装进可管理、可扩展、可审计的外壳。

只有 API:得到一个会说话的模型;API + Agent:得到一个能动手的脚本;三者齐全:得到一个能日常使用、能扩展、能交付的系统。

五个常见误解

  1. DSH 是一个模型:不是,它是运行台,模型可以是 DeepSeek 或第三方。
  2. 用了 Harness 就不会幻觉:不会,只是更容易验证和拦截。
  3. Agent 越自主越好:不对,自主性越高,越需要权限、审批、回滚、监控。
  4. API 和网页版是一回事:不是,API 按量计费、要 key、要自己写调用。
  5. 有了 Agent 就不用学编程:见第 2 章。结论是:语法记忆贬值,读代码、拆问题、验证结果升值。

本章练习

用一句话分别解释 API、Agent、Harness,不能使用“智能”“强大”;画出你理解的模型—工具—人关系图;列出 3 个“API 能帮上忙但 API 本身做不到”的环节。