把DeepSeek Harness装好并跑通第一个Demo之后，大部分人的下一步是直接开写，然后卡在“为什么模型不按我的想法做事”上。这问题十有八九不是模型笨，而是通用设置和Agent预设还没调明白。我最初上手时也在这里耗了两天，后来把设置面板逐项过一遍、手写了几套Agent预设，才算真正把Harness用起来。上一篇讲了安装和基础运行，这篇继续往深走，专门拆解DeepSeek Harness的通用设置和Agent预设，适合已经装好插件、想在项目里稳定使用的人。
1. 配置别乱放：三处设置位置的优先级与使用场景
1.1 用户级、工作区、项目级配置文件到底有什么区别
DeepSeek Harness在VSCode里的通用设置，和大多数扩展一样，分成三个层级：用户级、工作区级、项目级。用户级配置写在VSCode的settings.json，作用于你电脑上的所有项目；工作区级配置写在当前打开的文件夹下的.vscode/settings.json；项目级配置则存在于Harness自己管理的配置目录中，通常是一个类似.deepseek-harness/config的隐藏文件夹。
为什么要把简单的事情拆成三层？关键原因是你对不同项目的预期不一样。举一个真实场景：我做Java后端项目时，希望默认模型是偏代码生成的参数组合，温度低一点、输出稳定一点；但写文案或做技术调研时，又希望模型脑洞大一些。如果全部写在用户级设置里，切换项目就必须反复改全局配置，改完还容易忘记还原。把项目相关的设置放在项目级，把通用偏好放在用户级，这样切换项目时配置自动跟着走，互不污染。
1.2 先确认当前到底生效的是哪一份配置
被配置搞晕的人，十有八九是没确认“当前生效值”。Harness在命令面板里提供了一个查看有效配置的入口，一般是“Harness: Show Effective Config”，会把三层配置合并后的最终结果以只读面板展示出来。我第一次找设置不生效的Bug时，全靠它定位到了问题——当时我在工作区设置里写了一个模型参数，但用户级设置里也有一份旧值，导致我改的工作区配置完全不生效。
实际排查时遵循这个顺序：先看全局开关能不能打开，再看单独项目有没有被限制。任何一个配置项，当前真正生效的值取决于这样一条链路：用户级的默认值，被工作区级覆盖，再被项目级覆盖。也就是说，项目里如果设置了同名参数，就会盖掉上面的。这一点非常关键，因为很多时候你在设置面板里看到开关处于打开状态，但项目配置里却把它关掉了，界面不会显示出层级关系，只有“Show Effective Config”能看到真相。
2. 通用设置面板逐项拆解：从模型参数到调试日志
2.1 模型接入与默认参数：temperature、top_p、max_tokens怎么配合
通用设置里第一块必调的就是模型接入。Harness默认连接DeepSeek官方API，但你可以在设置项中修改api_base和model，指向私有化部署的服务或兼容OpenAI协议的其他网关。这里的关键在于：Harness把“接入地址”和“默认模型”分开配置，接入地址决定流量发到哪里，默认模型决定你打开会话时初始加载的是哪个模型。如果只改地址不改模型名，调用时会直接报模型不存在，这一点我踩过。
模型参数里，最常用的是temperature、top_p和max_tokens三个。我给出一个自己实际使用的参考：
| 参数 | 建议值范围 | 使用场景 |
|---|---|---|
| temperature | 0.1-0.3 | 代码生成、代码评审、需要稳定输出的任务 |
| temperature | 0.7-1.0 | 头脑风暴、方案生成、文案润色 |
| top_p | 0.8-0.9 | 配合temperature使用，一般不需要单独调到1 |
| max_tokens | 512-2048 | 短问答；长文档生成适当调大 |
| max_tokens | 4096以上 | 长代码文件补全、大规模重构建议 |
temperature和top_p都是控制随机性的参数，区别在于temperature影响的是整个词汇概率分布的平滑程度，top_p影响的是只从累计概率达到阈值的候选词中采样。不建议同时大改这两个值，常规做法是固定top_p在0.9附近，重点调temperature。
2.2 上下文管理是设置里的隐藏重点
很多人忽略的是context_limit和上下文压缩策略。Harness在处理长会话时，不是把全部历史对话都发给模型，而是只保留一个滑动窗口内的消息。窗口太小时，模型会“失忆”；窗口太大时，API超时和费用都会涨。我的做法是：普通项目保持20条消息左右的历史窗口；涉及多文件排查时拉到40条；如果确实需要完整分析长文档，把文档作为外部文件引入，而不是全部塞进对话窗口。
auto_compress这个参数开启后，Harness会在历史记录接近上限时自动把旧消息压缩成摘要。这个功能建议始终打开，不然你会在长对话的中段发现模型突然开始一本正经地回答“刚才的内容我已经记不清了”。不过要注意，压缩会丢失细节，遇到需要精确追溯的排查场景，宁可手动定期新建会话，也不要一味依赖自动压缩。
2.3 输出行为与调试开关：流式输出、代码块、日志级别
输出相关的设置直接影响使用体验。stream_output建议打开，可以像ChatGPT那样逐字看到回复，尤其是长输出时能判断模型是否还在正常工作。另一个容易被忽视的是“代码块智能识别”，Harness默认在输出中按语言标注代码块，但如果你把输出粘贴到非Markdown场景，这个标注反而碍事，可以在输出设置里关闭。
日志级别log_level平时保持info，遇到问题再调到debug。调成debug之后，Harness会在输出面板打印每次请求的耗时、Token消耗以及预设加载情况。判断一个Agent预设是否真的被加载，看debug日志比看界面状态更可靠。日志文件的位置在VSCode的扩展输出通道里，通常叫做“DeepSeek Harness”输出频道，打开后选择满级日志复制给排查工具即可。
2.4 API密钥别直接写进配置文件
密钥管理这块我特别想强调。不要把API key硬编码在settings.json里，因为很多人会把.vscode/settings.json提交到Git仓库，一个不小心就泄露了。正确做法是把密钥写到环境变量里，比如DEEPSEEK_API_KEY，然后在Harness设置项中填入${DEEPSEEK_API_KEY}。这样做还有个附带好处：公司内部如果有多套环境，可以按环境变量区分，不需要改动配置文件。
3. Agent预设到底预设了什么：结构、字段与作用边界
3.1 一个预设就是一个“人格+工具箱+边界”的打包单元
Agent预设是DeepSeek Harness最有价值的功能。它本质上是把系统提示词、模型参数、可用工具、上下文策略、输出约束打包成一个配置单元，在会话中可以一键切换。你可以把它理解成给模型“换人设”：代码评审时它是一个严格的Reviewer，写方案时它是幕僚，处理日志时它是运维专家。不是靠反复在对话里“请你现在扮演一个……”来引导，而是在预设里一次性框定所有行为。
预设还负责划定能力边界。比如“代码评审Agent”只允许使用读取文件、搜索函数调用、执行静态检查这三类工具，不允许调用API或修改文件。这样设计是为了防止模型在评审过程中顺手改了你的代码。我在配置预设时一直遵循一个原则：给模型的最小可用权限，而不是最大权限。
3.2 预设文件存放在哪里，怎么被识别
Harness的预设通常以YAML文件形式存放在项目根目录的.deepseek-harness/agents/文件夹下，一个文件对应一个预设，文件名就是预设ID。安装插件后首次运行，Harness会自动创建这个目录并放入几个示例预设。如果你发现这个目录不存在，可以在命令面板执行“Harness: Open Agents Folder”，它会直接打开正确目录。
加载预设的规则很简单：启动会话时，Harness会扫描该目录下的所有YAML文件，把文件内的name字段显示在会话顶部和命令面板里。修改预设文件后，当前会话不会自动重载，需要新建会话或在命令面板里执行“Harness: Reload Agents”才能生效。这个细节经常被忽略，改完预设发现没变化，就以为是写错了。
3.3 预设核心字段的语义与作用
我整理了一份我写预设时基本都会用到的字段说明。
| 字段 | 类型 | 作用 |
|---|---|---|
| name | string | 预设显示名称，必须唯一 |
| description | string | 描述预设用途，列在切换面板里 |
| system_prompt | string | 核心系统提示词，规定模型角色和行为 |
| tools | list | 允许使用的工具列表，不声明则继承默认 |
| temperature | number | 覆盖全局设置的采样温度 |
| context_policy | string | 上下文策略，可选adaptive/fixed |
| output_style | string | 输出风格，如markdown/plain |
| variables | map | 预设内置变量，供prompt引用 |
| enabled | boolean | 是否启用该预设 |
context_policy值得单独解释。设置为fixed时，预设会用固定的消息窗口大小，行为可预期；设为adaptive时，Harness会根据输入内容长度动态调整窗口，适合处理不定长输入。计划任务类场景用fixed，总结文档类场景用adaptive。
3.4 预设与全局设置的覆盖关系
预设里的参数会覆盖通用设置里的同名参数，但只覆盖预设声明的那几项。比如预设里写了temperature: 0.2，那本次会话的temperature就用0.2；如果没写，则沿用通用设置里的值。这个“按字段覆盖”的机制很好用，让我不需要在预设里重复所有配置，只需写差异项即可。
需要注意的是，这种覆盖是静态的。你在会话中途手动调整的temperature属于临时覆盖，只影响当前这条消息，不会写回预设文件。想要长期固定某个参数，要改预设文件本身。
4. 手写一个“代码评审Agent”预设的完整过程
4.1 先明确这个预设要解决什么问题
以代码评审为例。常规的代码评审需要人肉来回看Diff，关注点很多：逻辑漏洞、边界条件、安全风险、命名规范、复杂度。我用通用对话让模型做评审时，输出往往太笼统，比如“整体结构清晰，注意一下空指针”，没有任何定位信息，根本没法直接用于修复。
我的目标预设要有以下表现：能先读取相关文件，对照变更求出上下文，再列出“问题文件-行号-问题等级-修改建议”的结构化输出，且不允许直接修改源码。为了达到这个效果，我需要预设具备三个要素：严格角色定义、结构化输出约束、受限的工具列表。
4.2 预设文件写出来是什么样
我在.deepseek-harness/agents/code-reviewer.yaml中写了这样一个预设：
name: code-reviewer description: 严格代码评审，输出结构化问题清单，不做修改 enabled: true temperature: 0.1 context_policy: fixed output_style: markdown system_prompt: | 你是资深代码评审专家。你的任务是对当前变更进行静态评审。 评审规则： 1. 只发现问题，不修改代码。 2. 每个问题必须包含文件路径、行号、严重级别和修复建议。 3. 严重级别使用 BLOCKER / MAJOR / MINOR / INFO 四级。 4. 关注：空指针、资源泄漏、并发安全、边界条件、重复代码、命名规范。 5. 如果未发现问题，明确输出“未发现明显缺陷”，禁止敷衍性赞美。 tools: - read_file - search_symbol - view_diff variables: reviewer_focus: "backend"逐段解释一下。temperature: 0.1让输出尽量稳定，评审场景不需要创造力。context_policy: fixed保证每次评审的上下文窗口一致，不会因为对话拉长而忽多忽少。tools里只给了read_file、search_symbol、view_diff三个读操作工具，不给任何写操作权限。variables里定义了一个后续在prompt中可以引用的变量，如果需要扩展成前端评审预设，只需把reviewer_focus换成frontend并调整system_prompt。
4.3 在会话中启用并验证效果
在Harness会话界面顶部的Agent下拉框里选择code-reviewer，或者在命令面板里输入“Harness: Switch Agent”选到这个ID。之后我正在做的事情是：打开一个改动较大的Git分支，先选中要评审的Diff文件，然后以会话形式发起评审请求。
实际效果让我比较满意：模型输出了一个Markdown表格，列出了问题文件、行号、级别和建议。其中有一条BLOCKER级别的建议指出某个函数在空集合状态下会触发未初始化变量，还给出了具体行号。相比于之前“这段代码存在风险”这种空泛回复，这种输出可以直接贴到Issue里。当然不是每次都能准确定位，但评审结果相比默认无预设时可用性高了一个量级。
4.4 复用和参数化预设的小技巧
如果团队里有多个项目，评审关注点不同，不必每个项目各写一份预设。可以通过变量区分项目类型，甚至可以在预设里引用环境变量：
variables: root_path: "{{workspaceFolder}}"这个{{workspaceFolder}}是DeepSeek Harness内置的占位变量，会在加载预设时替换为当前项目根目录路径。有了这类变量，一个预设就可以在不同项目间复用，而不需要改动YAML内容。同理还有{{projectName}}、{{language}}这类占位，写prompt时非常有用。
5. 设置和预设不生效的排查链路：按这个顺序查
5.1 问题一：改了设置，模型行为完全没变
我遇到过一个奇怪情况：在通用设置里把temperature调到了0.1，对话里也确认设置面板显示0.1，但模型输出依然天马行空。最后用“Show Effective Config”一看，项目级配置里赫然写着temperature: 0.9。问题根源就是项目级配置覆盖了用户级设置，而设置面板只显示当前项，不显示来源。
排查链路：打开命令面板，执行“Harness: Show Effective Config”，查看实际生效值；如果和预期不符，看是哪一层覆盖了；再打开对应的配置文件修正。如果Effective Config显示的值是对的但行为仍异常，那就要考虑是不是会话级别的临时设置污染了后续请求——这个只需要新建会话即可确认。
5.2 问题二：预设加载不出来，或者被静默跳过
有时候YAML语法看起来没问题，Harness界面里就是看不到预设。排查时先看文件名是否违反规则：预设文件名不能有空格，不能以点开头，必须位于agents目录下。另外一个常见原因是YAML里的enabled: false，写的时候手滑设成了禁用状态，它在面板里根本不会显示。
看debug日志是更准确的定位方式。把日志级别调到debug，重启会话，在输出通道里搜索“agents”。正常情况下能看到“loaded agent xxx”的日志；如果看到“failed to parse”，日志里会带上具体行列。这里要提醒一个容易忽略的点：预设文件里如果用了Tab缩进，YAML解析会直接失败，必须统一成空格缩进。
5.3 问题三：上下文过长导致请求超时
设置里context_limit拉得很大，结果执行复杂任务时频繁超时。这不是设置“不生效”，而是请求体已经超过了模型服务的单次限制。你配置的上下文窗口是Harness允许保留的消息数量，但最终请求Token上限还受API侧约束。长会话时，Harness会尝试将消息裁剪到模型限制内，但如果单条消息本身就很大，裁剪也救不了。
我的缓解办法：关掉“自动摘要压缩”却保持“大文档单独加载”的模式，不把整个文件全文粘贴进对话；对于大仓库，先让Agent用工具搜索定位关键文件，再针对性地读取局部内容。这个习惯让我的成功率明显提升。
5.4 问题四：工具权限没生效
预设里定义了tools后，模型还是会调用未授权的工具。出现这种情况，通常是因为当前会话的Agent并不是你改的那个预设——Harness切换Agent后，如果旧会话模型仍持有之前的工具列表，你要新建会话才会用新预设。另一个可能是默认Agent的tools字段为空，空字段表示“使用Harness默认全部工具”，不会自动变成“无工具”。想要限制权限必须显式写出允许的工具列表。
6. 几个我实际使用后觉得值得分享的进阶配置习惯
6.1 把预设纳入版本管理，建立团队共享的起点
.deepseek-harness/agents/里的YAML是纯文本，天然适合纳入Git版本管理。我们团队现在已经把预设文件放在仓库里，新人克隆项目后直接可用。好处不仅是统一评审标准，更在于预设的改动可以通过Merge Request审查，避免有人在本地悄悄改了评审规则。对于单兵作战，这也意味着换电脑后一条命令恢复全部Agent配置。
6.2 一个主题对应一套预设，预设之间不堆叠
我最初犯过把“代码生成+测试生成+重构建议”全塞进一个预设的毛病。这种大而全的预设，输出中规中矩，但每个任务都不够深入。拆分成“coder”“test-writer”“refactor”三个预设后，每个预设都更纯粹，输出质量反而更高。需要组合能力时，我就在对话中顺序切换预设，而不是让一个预设试图覆盖所有场景。
6.3 共享预设的命名与描述习惯
预设的name建议用英文短横线命名，因为它在命令面板中作为ID检索；description则用一句话说明适用场景和输出约定。这两个字段会在切换Agent时显示在列表里，写清楚后，一周之后你回来也能一眼知道这个预设是干什么的。
最后说一个我自己的使用习惯：不要试图一次把所有设置的参数全部填满。先保持默认值，只调整温度、流式输出、上下文窗口这三个性价比最高的项，把项目跑顺，再逐个引入新开关。Agent预设也一样，从一个极简的“评审只用读工具、低温度、结构化输出”开始，迭代几轮之后，你自然知道该往里面补什么。在这个板块里，真正花时间的不是配置语法，而是你对自己工作流的整理。
 演示深度解析)
