企业官网建设流程全解析

上一篇文章把 Harness 和 Agent 的区别掰扯清楚了，很多朋友看完还是觉得差点意思：概念懂了，下一步怎么跑起来？这次直接从 DeepSeek-Harness 最常用的两个入口讲起——CLI 和 Web UI。一个是纯命令行操作，适合脚本化、自动化、快速验证；另一个是本地仪表盘，适合肉眼观察 Agent 的每一步思考、工具调用和 token 消耗。这篇文章适合两类人：一类是刚接触 Agent 开发的新手，想找一个能快速上手又不花哨的调试框架；另一类是已经在做 Agent 工程、但被可观测性和复现问题折腾得够呛的开发者。读完你会明白 Harness 在 Agent 生命周期里到底扮演什么角色，以及怎么用最短路径跑通你的第一个 Agent 任务。

另外先打个预防针：DeepSeek-Harness 这类项目处于快速迭代期，不同小版本的命令面貌可能有差异。我下面写的命令和参数，按社区常见实践补全，具体以你本机deepseek-harness --help的输出为准。接下来直接进入正题。

1. 为什么先聊 Harness，再聊 CLI 和 Web UI

1.1 一句话区分 Harness 和 Agent

还没看过前一篇的朋友，先花三十秒理解一个核心概念：我们常说的 Agent 是那个会思考、会调用工具、能完成多步任务的智能体；而 Harness 是承载它运行的外部框架，负责编排循环、管理上下文、记录工具调用、控制预算，并且把每一次运行变成可以追溯的数据。简单类比，Agent 是赛车，Harness 是赛道管理、数据采集、维修区调度那套系统。

所以与其说 Harness 是 Agent 的升级版，不如说它是 Agent 的“驾驶舱”和“黑匣子”。这也能解释为什么很多 Agent 项目跑着跑着就失控了：你只关注模型本身的能力，却没给运行过程装任何仪表。DeepSeek-Harness 这类工具的价值，恰恰是把那些平时看不见的中间环节全部显性化。你会看到 Agent 每轮思考消耗了多少 token、调用了哪个工具、返回结果被截断在哪、哪一步触发了提前终止。有了这些原始数据，“模型表现不稳定”这种抽象抱怨，就能被拆成具体的可修复问题。

1.2 CLI 和 Web UI 的分工逻辑

CLI 的优势是干净、直接、适合自动化。你在终端里敲一条命令，任务就跑完，输出是结构化的 JSON 或简洁的日志，方便接入 CI/CD、定时任务、批量评测。Web UI 则把一次运行拆成任务列表、轨迹时间线、token 消耗、错误堆栈这几个维度，适合在做方案分析、团队协作、给非技术同学展示成果时使用。

一个容易被忽略的点是：CLI 和 Web UI 通常共享同一个底层数据文件或数据库。也就是说，你完全可以用 CLI 去批量跑任务，再用 Web UI 打开同一个结果文件，逐条检查失败样例。这样把“跑”和“看”分离，是 Agent 开发中很实用的一种工作流。后面第 5 章我会专门展开三种协作场景，这里你只需要记住一个结论：两个入口不是互相替代的关系，而是同一套运行体系的不同观察角度。

2. 动手前的准备工作：环境、配置、鉴权

2.1 从 Python 3.10 起步，安装加验证

DeepSeek-Harness 本身是 Python 生态的项目，所以安装前先确认有 Python 3.10 以上版本。推荐用虚拟环境，避免污染系统 Python。安装命令很简单：

pip install deepseek-harness

如果你平时用 uv 管理 Python 工具链，也可以这样装：

uv tool install deepseek-harness

安装完成后先验证两件事：

deepseek-harness --version deepseek-harness --help

我的建议是，别急着把所有依赖一次装齐。先用一个纯文本问答的 Agent 跑通流程，再加代码执行器、RAG 这些工具。很多新手一上来就配齐 Web 搜索、代码解释器、向量数据库，结果报错都不知道是哪个环节出的问题。你想想，一个 HTTP 连接超时和一个工具入参格式错误，排查思路完全不一样，混在一起只会让人头皮发麻。

2.2 配置文件三区块怎么看

安装好后，第一步是初始化配置。通常会在当前目录生成一个 YAML 文件（比如harness.yaml），包含以下三个区块：

model: provider: deepseek name: deepseek-chat api_base: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY agent: max_steps: 20 max_tokens: 8000 temperature: 0.2 tools: - code_interpreter - rag observability: trace_dir: ./runs/traces log_level: info

第一块 model 是模型接入信息，第二块 agent 是运行时的行为参数，第三块 observability 是观测配置。注意api_key_env这里写的是环境变量的名字，而不是密钥本身。这个习惯我后面还会专门强调。如果配置文件里允许写字面密钥，也请务必不要提交到 Git 仓库。

核心参数快速解释：max_steps是 Agent 最多能执行多少轮“思考-行动”循环，防止死循环烧钱；max_tokens是单次模型调用的 Token 上限；temperature控制输出随机性，Agent 任务通常用 0.2～0.4 比较稳定；trace_dir是运行轨迹输出目录，Web UI 和 debug 命令都依赖它。

注意：不同版本的默认参数可能不同，请在配置文件里显式写清楚，不要依赖隐式默认值，否则升级版本后行为会变。

2.3 防止密钥泄露的两条底线动作

这是做 Agent 工程最容易翻车的地方。我看过很多项目，配置文件里直接写 api key，跑完任务就把整个目录推到 GitHub，几分钟内密钥就被爬走了。所以我的底线动作有三条。

第一，配置文件中只写环境变量名，不写密钥字面量。第二，把.env文件加进.gitignore，密钥统一放到.env里，启动时自动加载。第三，给密钥设置最小权限，能用只读的就不用写权限，能限定模型用途的就不要全量授权。

如果你在 Web UI 或日志里看到模型请求的完整 headers，记得开启脱敏配置。很多框架提供--redact-secrets之类的选项，日志里会把授权头替换成掩码。别小看这一步，一旦团队里几个人一起调试，日志到处传，密钥泄露往往就是这么发生的。运行前可以用一条命令做自检：

deepseek-harness check --env

它会检查环境变量是否到位、配置是否合法、版本是否有已知问题。相当于起飞前的绕机检查，值得每次换环境都跑一遍。

3. CLI 快速上手指南：五个命令跑通全流程

3.1 第一步永远是 init，不是 run

CLI 的第一步永远是 init，而不是 run。init 会根据你选择的模板生成目录结构、最小配置和示例任务：

deepseek-harness init --example quickstart

生成的目录大概长这样：

my_agent/ ├── harness.yaml ├── .env ├── .gitignore ├── tasks/ │ └── demo_task.json └── runs/

tasks 目录放任务定义，runs 目录放运行产物。这样从第一天开始，你的任务、配置、观测数据就是分离的，后面做评测和追溯会非常轻松。init 之后立刻打开.env，把DEEPSEEK_API_KEY填上，并把.env加进.gitignore，不要心存侥幸。

有人会觉得 init 多此一举，自己手工创建目录也一样。但实际上，模板里的目录结构和示例任务是有讲究的，它会让你一开始就养成任务、配置、运行数据分离的习惯，后面接 Web UI 和批量评测时几乎不需要改动目录。这个前期成本很值得付。

3.2 跑任务时我常用的 run 参数组合

跑任务的核心命令非常直白：

deepseek-harness run "用 Python 写一个脚本，统计当前目录下所有 .md 文件的总字数"

这会把你的问题当作一个一次性任务，加载默认配置，跑完后输出结果。但实际开发中我更推荐显式指定参数和任务文件：

deepseek-harness run tasks/demo_task.json \ --model deepseek-chat \ --max-steps 30 \ --max-tokens 12000 \ --trace \ --output result.json

每个参数都有它的存在理由：--model确保你用对了模型，避免默认模型不是你想要的；--max-steps是兜底防线，防止 Agent 在一个任务上无限循环；--trace会把每一步轨迹写进 runs 目录，之后可以用 debug 或 Web UI 复盘；--output是机器可读的结构化结果，方便后续脚本处理。

第一次跑任务时，我建议控制在一个尽量简单的任务上。先让 Agent 只回答纯文本问题，别加工具调用，确认链路通了再加代码解释器。别问为什么，这是被无数次混乱报错教育出来的习惯。等你熟悉了运行节奏，再逐步放开工具列表，这时候出问题你也能快速锁定是哪一层的问题。

3.3 任务坏了之后：debug、list、eval 三板斧

任务跑坏了才是 CLI 真正的主场。先看当前有哪些失败任务：

deepseek-harness list --status failed

找到失败的运行 ID 后，进入调试模式：

deepseek-harness debug --run-id RUN_ID

debug 模式会逐条打印 Agent 的思考、工具调用、返回结果，你可以在任意步骤暂停，也可以手动注入一条消息看模型反应。这个交互方式比翻日志高效得多，相当于给一次 Agent 运行装上了断点。我通常的做法是，先看最后一步的工具返回，再看模型基于返回做的下一轮决策，往往问题就出在“工具给了错误输入”或“模型错误解释了输出”这两类。

批量评测是另一个高频场景。把一组评测用例整理成 JSONL，然后跑：

deepseek-harness eval --config eval_benchmark.yaml

输出会按用例粒度给出通过率、Token 消耗、失败原因分类。CLI 的 eval 模式适合在 CI 里卡回归，Web UI 的评测面板则适合人工核查失败样本，各管一段。你可以把 eval 结果文件提交到代码仓库里，每次改完 prompt 或工具定义，跑一遍对比前后差异，这是 Agent 工程化里性价比最高的动作。

4. Web UI 快速上手指南：本地观测 Agent 全链路

4.1 启动 Web UI 时别忽略 host 绑定

Web UI 的启动命令一般是 serve：

deepseek-harness serve --host 127.0.0.1 --port 8080

这里要特别强调 host 参数。不要默认绑定0.0.0.0，除非你明确知道自己在做什么。一旦绑到0.0.0.0，局域网内任何机器都能访问你的仪表盘，而仪表盘上很可能带着全部任务记录、prompt 内容、甚至日志里的密钥信息。本地调试一律绑127.0.0.1，需要团队协作再考虑内网穿透或反向代理。

启动后，浏览器打开http://127.0.0.1:8080，你应该能看到一个任务列表页。它读取的就是 runs 目录下的轨迹数据。也就是说，你没有用 Web UI 跑过任务也没关系，只要之前用 CLI 跑的时候开了--trace，这里就会自动出现历史任务。这个设计很贴心，省去了手动导入导出的麻烦。

4.2 打开仪表盘先看这三块

第一次打开 Web UI，重点看三块：任务列表、轨迹时间线、资源消耗。

任务列表解决的是“我到底跑过什么”的问题。按状态筛选是最常用的操作：成功、失败、运行中、被手动终止。列表里每一行都会显示任务名、模型、耗时、Token 消耗，这本身就是一份很好的实验记录。你可以按时间排序，也能按模型筛选，批量对比不同模型的输出成本。

轨迹时间线是 Web UI 的灵魂。你可以像看视频一样，把一次运行从头到尾过一遍：Agent 收到什么指令，调用了哪个工具，工具的返回内容是什么，模型基于该返回做了哪些下一步决策。哪个步骤开始出错、哪一步出现语义漂移，一目了然。资源消耗面板则把 token 拆成输入、输出、工具返回等类别，方便定位“钱烧在哪里”。如果你发现某个任务 tokens 消耗异常高，先看是不是某次工具返回特别长，往往能找到答案。

4.3 用轨迹时间线定位一次失败任务

真正上手时，定位一次失败任务的流程是这样的：在任务列表里筛选 failed，点开某条轨迹；先看时间线最后一步的报错信息；如果是工具调用失败，再点开工具的入参和出参，判断是参数拼错了还是服务端返回了异常结构。

我踩过的典型例子是，Agent 调用了代码解释器，但脚本里引用了不存在的文件，工具返回一个 RuntimeError，模型把这个报错原封不动地复述了一遍，然后任务终止。用 Web UI 看轨迹时，问题非常清晰：工具输出是干扰项，真实原因是任务描述里没有把文件路径说清楚。这种问题在纯日志里要翻半天，在可视化时间线下基本一眼定位。

所以说，Web UI 不是给新手准备的玩具，它是给 Agent 开发省时间的武器。以后你写周报、复盘线上事故、跟同事对齐问题，都可以直接从 Web UI 导出截图，大家对着轨迹讨论比对着聊天记录争论高效得多。

5. CLI 和 Web UI 怎么选：三个实际场景

5.1 自动化流水线默认选 CLI

如果你要把 Agent 任务接入 CI/CD，或者做成定时脚本，CLI 是唯一选项。没人会在一台构建机上开一个浏览器点按钮，对吧？CLI 的退出码会反映任务成败，输出 JSON 给后面脚本消费，日志打到 stdout 或文件，一切都能被标准工具接管。这是 Web UI 做不到的。

我在实际项目中是这样用的：代码合并前，强制跑一组评测用例，通过率低于阈值就不允许合入。任务由 CLI 执行，结果写成 JSON 上传到团队的看板系统。整个过程没有任何人工介入，但每一次 prompt 改动是否带来了回归，都有据可查。

5.2 人工分析场景让 Web UI 上场

反过来，当你需要在几十分钟里搞清楚一个失败任务的来龙去脉，或者要给同事演示一个 Agent 的思考过程时，Web UI 明显更合适。轨迹时间线比终端输出直观得多，特别是在多轮工具调用场景下，滚动日志看得人头皮发麻，时间线只需顺着箭头往下看。

我自己遇到复杂 bug 时的流程是：先按失败状态筛选，打开最可疑的任务，直接跳到报错前几步，观察工具输入输出。很多时候不需要重新跑任务，旧的 trace 就能解释问题。也就是说，Web UI 不仅仅是个监控面板，它其实承担了一部分事后审计的功能。

5.3 我常用的混合工作流

我目前比较依赖的是混合模式。批量跑评测用 CLI，跑完打开 Web UI 刷失败样本；日常写实验用 CLI，晚上统计实验结果时打开 Web UI 的聚合面板。两者共享 runs 数据，所以无缝衔接。

提示：不要让团队每个人都单独维护一份 runs 目录。提交代码前，用共享存储或固定路径保存关键轨迹，否则过两天想找某次实验记录会非常痛苦。

6. 常见问题速查：我从报错里攒下来的经验

6.1 连接超时和鉴权失败怎么查

症状通常是 CLI 刚跑就报连接超时或 401。先检查 API key 是否真的注入到了环境变量，很多人在.env里写了 key，但忘了 source 或忘了重启终端。再用 curl 或项目自带的连通性检查工具打一下模型服务，确认网络可达。注意有些公司内网环境需要额外配置代理或白名单。

如果网络没问题，再看是不是模型名称写错了。不同版本的模型服务对模型标识的写法有差异，deepseek-chat和deepseek-reasoner这类名称不小心写错，服务端会返回 model not found。检查配置文件比检查代码更有效，因为这一类报错八成是配置问题。

6.2 最常见的“任务被终止”报错

Agent execution terminated due to error是很常见的一条报错，看到它先不要慌。它只是告诉你 Agent 的某一步抛出了致命异常，真正的原因在 trace 日志或 Web UI 轨迹的最后几步里。常见原因有三类：工具入参类型不对、上下文长度超限、模型返回了无法解析的 JSON。

先打开轨迹看一眼再动手改，别从配置文件开始一顿乱猜。我曾见过有人遇到这个报错后把 temperature 从 0.2 调到 0.8，结果越调越乱。正确的做法是看轨迹最后几步，确认是哪一步产生了异常，然后针对性修复。如果轨迹显示模型输出格式异常，再考虑加输出解析兜底逻辑。

6.3 工具返回内容太长引发的连锁问题

这个问题在接数据库和知识库时特别典型。你把一堆 SQL 查询结果或检索片段一股脑塞给模型，上下文瞬时膨胀，模型开始前言不搭后语。症状表现为：前面的推理还正常，后面的步骤开始答非所问，甚至直接因超长被终止。

解决办法是控制工具返回体量：限制查询行数、对长文本做截断或摘要、给工具增加max_rows和max_chars参数。另一个办法是提升max_tokens预算，但这只是缓解，不是根治。本质问题是你的工具输出设计不够克制。你想想，模型每轮能处理的上下文是有限的，喂进去一百行无关日志，真正被用的可能只有最后几行，白白浪费成本还拉低稳定性。

6.4 端口、日志、磁盘占用的细节处理

Web UI 起不来，多半是端口被占用，换一个端口即可。磁盘占用问题容易被忽视，runs 目录里的 trace 文件多了之后会很占空间，记得定期归档。日志出现敏感信息时，优先看有没有脱敏开关，没有的话升级版本或自己包一层日志过滤器。

还有一个细节：如果 Web UI 打开后页面空白，先看终端输出有没有静态资源加载失败。这类问题通常和浏览器缓存、服务版本不匹配有关，刷新一次或换无痕窗口往往能解决。别急着重装环境，很多时候只是小问题。

7. 几个值得长期坚持的习惯

7.1 把 trace 和 eval 当成默认操作

我现在跑任何任务都会带上 trace，不管任务是成功还是失败。因为 trace 是唯一能回放 Agent 决策过程的数据，没有它，一次成功的运行也只是“碰巧成功”。同理，eval 也不是上线前才做的动作，每次改配置、换模型、加工具，都应该先跑一组小评测看看变化方向。你把这些动作内化成默认操作，后面调优才有据可循。

7.2 给常用命令做一层薄封装

把常用的一组参数写成一个 Makefile 或 shell 脚本，比如make run、make ui、make eval，团队新成员看到后能立刻上手，不用翻文档。我用的封装很简单，本质上是把上面那几条命令藏起来，加上固定的 trace 和输出目录。维护成本极低，但收益很明显：大家跑出来的目录结构是一致的，后续分析不必猜某次任务到底用了什么参数。

7.3 最后想说的经验

CLI 和 Web UI 只是入口，真正的价值在于建立“可观测、可复现、可控预算”的工作习惯。我个人的体会是，只要每次跑任务都把 trace 打开，把配置显式写明，把密钥隔离在环境变量里，后面省下的调试时间会远超你花在这些动作上的五分钟。

最后再分享一个小技巧：定期从 Web UI 导出几份“教科书级”的成功轨迹和失败轨迹，存成文档。下次遇到类似问题，先翻历史轨迹而不是重新跑一遍，你会发现自己排查问题的速度快得惊人。