DeepSeek Harness保姆级教程：从安装到精通的Agent框架

什么是 DeepSeek Harness？

DeepSeek^广告 Harness 是一个开源的智能体运行池与开放框架，核心公式是 Agent = Model + Harness。大模型负责思考和推理，Harness 则充当大模型的“手和脚”，负责上下文管理、工具调用、编排、全线审批、会话持久化等。两者结合，才是一个能连续干活的 Agent。

正如“Harness”（马具）的英文含义，模型这匹马需要套上马具，才能真正骑出去干活。据 B 站 UP 主教程介绍，该项目发布仅三个月 GitHub Star 就超过 27 万，堪称今年最好玩也最强大的开源 Harness。

需要区分几个易混淆点：DeepSeek Harness 不是新模型，不是单纯的 API 客户端，也不是聊天网页。虽然界面看起来和网页端 DeepSeek 相似，但它能连接到你自己的环境并使用各种工具——网页产出的是一个回答，而 Harness 产出的是工作结果。

Agent（智能体） 是指能自主感知环境、做出决策并执行动作以完成目标的软件实体。与单轮问答的聊天机器人不同，Agent 强调“连续干活”：它需要记住上下文、调用外部工具（读写文件、执行命令、访问网络）、在多个步骤间编排任务，并在关键节点请求人工确认。业界常把 Agent 的能力拆成“大脑”和“手脚”两部分——大模型提供推理与生成能力，而运行框架提供执行环境、工具接口、状态管理与安全审批。DeepSeek Harness 正是后者，它本身不产生智能，而是把模型的输出转化为对真实环境的操作。理解这一分工，有助于区分“模型能力不足”与“框架配置不当”两类问题：前者换模型解决，后者调模式、权限或插件解决。

为什么说它“最好玩”？一切皆插件

DeepSeek Harness 并非第一个 Harness，它的前辈包括 Codex、WorkBody 等。但它最吸引人的设计在于“一切皆插件”。

普通 Agent 项目像一台已经装好的电脑，机箱封死，想换显卡可能得换整台机箱。DeepSeek Harness 则像乐高，模型、工具、界面、存储、策略等都是一个一个的拼块，你可以根据自己的构想拼装。后文讲到插件时，会对这一点有更深的理解。

安装与配置：新手入门第一步

安装 DeepSeek Harness 可以选择桌面安装包，也可以通过 NPX 命令启动，开发者还能从源码启动。对于一般办公用户，推荐使用桌面版，简单易用。

打开 DeepSeek 官网，点击 Harness 桌面端，根据操作系统选择对应安装包。Windows 用户注意不要装到 C 盘，最好放到其他盘；Mac 则没有太多要求。

安装完成后，需要连接一个可用的模型。最新版本支持使用 DeepSeek 官方账号登录，按界面提示授权即可。如果没有账号，需要先注册。在官方控制台点击 API Key，桌面端会自动创建一个 Key；如果通过 NPX 或源码启动 Web 端，则需要手动创建 Key 并在设置中配置。

Harness 不止支持自家模型，其他主流模型提供商的 API Key 也可以直接配置。需要注意的是，模型目录中可能没有最新的 K3.1 Pro，此时需要手动添加模型才能使用。

费用方面，Harness 通过 API 调用实现模型能力，因此需要花钱。价格分为输入缓存命中、输入缓存未命中和输出，命中与未命中的价格差距很大，所以实际成本并不稳定。不过实际使用中缓存命中率非常高，加上 DeepSeek 有闲时优惠，整体费用较为低廉。建议一开始少充一点，不够再补。

配置完成后，选默认模型发一条消息，确认能正常收到回复即表示可用。如果跑不通，先查看错误提示，再排查认证、余额、模型或网络问题。

界面与四大核心概念

Harness 整体界面与网页端 DeepSeek 非常相似：左侧是工作区域和会话历史，中间是核心对话区，右上角按钮可打开右侧区域查看文件、任务、浏览器等工具。围绕对话区，有四个新手必须了解的重点。

工作区：Agent 的工作桌面

工作区是 Agent 接下来读写文件、跑命令的目录。建议新建一个本地空目录作为工作空间，不要用已有杂乱内容的文件夹——Agent 执行时会读取文件夹内容，可能产生不必要的影响，也存在潜在的数据泄露风险。

模型选择与推理强度

如果觉得 Agent “笨笨的”或不认识图片，很可能是模型没选对。比如 DeepSeek 可选择支持多模态的 Flash 1017；配置了其他家模型时，也要切换到正确的模型。

教程中演示了一个小例子：在工作空间放入一份会议记录（其中故意加入“吃什么、点外卖”等干扰噪音），要求 Harness 整理成包含结论、决议、待办、风险的会议简报，待办需写明责任人和截止时间。Harness 会自行读取文件并产出简报，这就是它在自己的工作空间中结合环境完成工作的过程。

Agent 模式：四种预设

Harness 提供标准、PTC、极简、创造四种模式，相当于同一台电脑安装不同软件做不同配置。标准模式覆盖日常处理文件、整理资料、写代码等绝大部分场景，前面的会议记录整理用的就是它。PTC 全称 Programmatic Tool Calling，会写一段程序批量调用工具，适合处理上百份会议记录这类批量任务。极简模式只留一两个工具，适合做对比测试，减少干扰。创造模式是最新加入的，在标准基础上加入插件管理和开发指引，用于开发插件。模式没有好坏之分，关键是适合当前工作，一般情况下标准模式就能适配绝大部分工作。

Programmatic Tool Calling（PTC，程序化工具调用） 是一种让模型生成代码、由代码批量驱动工具调用的执行范式。传统工具调用是“一次决策调用一个工具”，模型需要逐步推理、逐步等待结果，步数多、开销大；PTC 则让模型先写出一段程序（如循环遍历文件列表、批量读取、汇总输出），再由运行时执行这段程序，一次性完成大量同构操作。其优势在于大幅减少模型往返次数、降低 token 消耗、提高批量任务的一致性与可复现性；代价是对模型写代码能力要求更高，且出错时调试链路更长。因此它特别适合“上百份会议记录整理”“批量文件重命名与归档”这类重复度高、单步逻辑简单的场景，而不适合需要频繁根据中间结果改变策略的探索性任务。

权限：决定哪些操作被允许

权限决定哪些工作允许执行、哪些操作被禁止，共四种。仅可查看适合读材料、分析问题给建议，没有写入权限。工作区内修改是练习中使用的类型，材料和输出集中在指定目录便于检查，但它不会限制误改文件，所以务必做好备份。完全权限下智能体会减少确认步骤，直接执行更多操作，包括文件修改和外部命令等敏感操作，适合确实需要更大范围工作的场景，同时也要承担更多风险。Auto Review 会自动授权审查，但目前是实验性能力，建议观望。日常使用最多的是第二种。

快捷指令与进阶用法

除了页面选择，输入斜杠可以看到多个快捷命令。教程结合会议纪要例子做了升级：希望把纪要做成项目进度页面，能按负责人筛选，还能点开原文查看依据，并且先看准备怎么做再开工。

按斜杠选择 plan，描述需求后，Harness 会列出详细工作计划，包括验收标准、数据模型、页面设计等，等待确认。不满意可以继续修改方案，满意后再执行。

八个快捷指令各有用途：go 管理持续目标，适合需要持续推进且有明确完成条件的任务；export 导出当前会话记录，便于存档、复盘或与他人讨论；file 附加文件，效果等同于直接拖入文件；permission 是调整权限的快捷入口；model 是切换模型的快捷入口；compact 压缩上下文，当发现 Harness 开始忘记最初要求或上下文窗口快满时使用；feedback 用于提交产品反馈。

最终，会议记录演变成了可交互的网页版本，更加直观。

上下文窗口（Context Window） 指模型单次推理能够“看到”的 token 总量上限，包括系统提示、历史对话、工具返回结果和当前输入。Agent 连续执行任务时，文件内容、命令输出会不断堆积，很容易触及上限，表现为模型忘记最初的要求、遗漏早前的约束或重复劳动。compact 指令的作用就是对历史上下文做摘要压缩：保留目标、关键结论与未完成事项，丢弃冗余的中间过程，从而在不丢失任务主线的前提下腾出窗口空间。与之配套的实践是：把重要约束写进持续目标（go）、把大文件改为按需读取而非全量载入、在阶段性任务完成后主动 compact，而不是等到模型明显“失忆”才补救。

上手建议

到这里，新手已经可以基本上手 DeepSeek Harness。下一步是在自己的工作中用它完成各种任务。最重要的是不要光看教程，马上亲手实践，这才是提升最快的方式。教程作者还配套准备了文档网站和交流群，下一节将围绕插件和 Skill 展开，讲解如何用得更好、在任务中取得更好表现。