企业官网建设流程全解析

1. 项目概述：这不是一个“玩具”，而是一套面向真实Agent开发场景的轻量级验证工具链

你有没有遇到过这样的情况：刚写完一个Agent的逻辑，想快速验证它能不能调用天气API、能不能解析PDF里的表格、能不能把用户问题拆解成三个子任务再并行执行——但每次都要搭Flask服务、写前端页面、配CORS、处理跨域、调试WebSocket连接？或者更糟，你只是想在本地终端里敲几行命令，看看这个Agent在给定输入下会输出什么思考链、调用哪个工具、最终返回什么结果，结果发现连CLI入口都找不到，文档里只有一堆抽象概念和架构图？DeepSeek-Harness就是为解决这类“最后一公里”验证痛点而生的。它不是另一个从零造轮子的Agent框架，也不是一个需要部署K8s集群才能跑起来的庞然大物；它是一个聚焦于“可观察性”与“可调试性”的Harness（测试夹具），核心目标就一个：让开发者在写完Agent代码后，能在5分钟内，用一条命令或点开一个网页，看到这个Agent的完整执行轨迹——从原始输入、内部推理步骤、工具调用参数与返回值，到最终输出，全部透明、可追溯、可复现。关键词里反复出现的“CLI”和“Web UI”，绝不是锦上添花的功能点缀，而是整个设计哲学的具象化：CLI面向快速迭代与自动化集成，Web UI面向深度调试与协作评审。它不替代LangChain、LlamaIndex或AutoGen这些上层框架，而是像一个精密的“显微镜”和“示波器”，插在你的Agent和真实世界之间，帮你看清每一个信号毛刺。如果你正在做Agent的单元测试、集成测试、效果回归，或者需要向产品经理演示一个新技能（Skill）的实际能力边界，又或者只是想搞清楚为什么某个复杂Prompt会让模型在第三步就“幻觉”出一个根本不存在的工具名——那么DeepSeek-Harness的CLI和Web UI，就是你此刻最该打开的两个终端窗口。

2. 核心设计思路拆解：为什么是Harness，而不是Framework？

2.1 “Harness”与“Framework”的本质区别：控制权归属决定开发体验

很多初学者会混淆Harness和Framework。简单说，Framework（框架）是“主语”，它定义了整个应用的生命周期、数据流向和执行模型，你作为开发者，是“宾语”，必须遵循它的规则去填空、注册、继承。比如LangChain要求你定义AgentExecutor，配置Tool列表，选择LLM和Memory，所有这些组件都得按它的契约来组装。而Harness（夹具）是“宾语”，它本身不拥有控制权，它只是被你调用的一个工具。你写好自己的Agent类，它可能是一个纯Python函数，也可能是一个继承自某个轻量基类的实例，甚至就是一个用@agent装饰器标记的函数——只要它能接收一个dict输入并返回一个dict输出，DeepSeek-Harness就能把它“夹住”，注入可观测性。这种设计带来的直接好处是零侵入式集成。你不需要为了测试而重构生产代码，也不需要在业务逻辑里硬塞进一堆print()或日志埋点。Harness通过标准的输入/输出接口与你的Agent通信，中间所有的“黑盒”行为——比如模型调用、工具执行、状态保存——都由Harness自身负责记录和呈现。这就像给你的Agent装上了一个飞行数据记录仪（FDR），它不改变飞机的飞行方式，但能完整记录下每一次起飞、爬升、巡航和降落的所有参数。

2.2 CLI与Web UI的分工逻辑：终端是工程师的“手术刀”，浏览器是团队的“会诊室”

CLI和Web UI并非功能重复的两种界面，它们服务于完全不同的工作流和用户角色。CLI的设计哲学是“极简、可脚本化、可管道化”。它的核心命令只有三个：harness run（执行单次）、harness batch（批量运行）、harness serve（启动本地Web服务）。每一个命令都接受标准的JSON输入文件，并能将结构化的执行日志（包含时间戳、步骤ID、输入、输出、耗时、错误堆栈）直接输出到stdout，方便你用| jq '.steps[0].tool_calls'这样的管道命令进行即时分析，或者用> results.json重定向到文件供后续自动化比对。这是工程师在深夜调试一个诡异的超时问题时最顺手的武器。而Web UI则是一个交互式执行追踪器。它不是静态的HTML页面，而是一个基于React构建的单页应用（SPA），其后端API完全由harness serve提供。当你在Web UI里上传一个JSON输入、点击“Run”，它背后触发的正是harness run命令。但UI的价值在于它把冰冷的JSON日志，转化成了一个可视化的“执行时间线”。你可以点击任意一个步骤，展开查看它的详细输入/输出、高亮显示模型生成的思考链（Thought Chain）、折叠/展开工具调用的嵌套层级，甚至可以复制某一步的原始响应文本，粘贴到另一个调试工具里做进一步分析。更重要的是，当你的团队需要一起评审一个Agent的决策过程时，你只需要分享一个http://localhost:8000/run/abc123这样的链接，所有人看到的都是同一份、带时间戳、可交互的执行快照。这种“所见即所得”的协作效率，是任何CLI日志滚动都无法比拟的。

2.3 为何选择“轻量级”而非“全功能”：避免过早优化的陷阱

当前Agent生态里充斥着大量“大而全”的平台，它们集成了模型网关、向量数据库、工作流编排、监控告警、权限管理……功能不可谓不强大。但DeepSeek-Harness反其道而行之，刻意保持“轻量”。它的源码仓库里没有models/目录，不内置任何LLM客户端；没有vectorstores/目录，不对接任何向量库；甚至没有auth/目录，不做任何用户登录。这种“缺失”不是缺陷，而是深思熟虑后的克制。因为绝大多数早期Agent项目，最大的瓶颈从来不是模型调用的并发数，也不是向量检索的毫秒级延迟，而是开发者无法清晰地理解Agent在特定输入下的行为逻辑。一个agent.run({"query": "帮我查一下北京明天的天气"})调用，背后可能涉及：1）意图识别为“查询天气”；2）提取实体“北京”、“明天”；3）调用get_weather工具，传入参数{"city": "北京", "date": "2024-05-20"}；4）工具返回{"temperature": 28, "condition": "晴"}；5）Agent将结果格式化为自然语言。如果第3步失败，是参数拼错了？还是工具函数本身有Bug？抑或是模型在步骤2里就把“北京”错识别成了“北平”？一个重量级平台可能会让你在几十个监控面板里来回切换，试图拼凑出真相；而DeepSeek-Harness则直接在CLI输出或Web UI里，用一个清晰的、带编号的步骤列表，把这五步原原本本地展示出来，并在第3步旁边标红一个ERROR: KeyError: 'city'。它把“定位问题”的成本降到了最低，从而把开发者的精力，真正聚焦在“修复问题”和“优化逻辑”上。这是一种典型的“先做对，再做好”的工程实践。

3. 快速开始实操：从零到CLI运行与Web UI访问的完整路径

3.1 环境准备与依赖安装：避开Python版本与包冲突的深坑

DeepSeek-Harness的官方推荐环境是Python 3.9+，但实际踩坑经验告诉我，强烈建议使用Python 3.10。原因在于，它底层依赖的pydanticv2.x系列对Python 3.11的某些新特性支持尚不完善，而Python 3.9又过于陈旧，会导致asyncio相关库的兼容性问题。我试过在Mac M1上用Homebrew安装的Python 3.11.6，pip install deepseek-harness后，运行harness --help会报ImportError: cannot import name 'cached_property' from 'functools'，这个错误源于pydantic与typing_extensions的版本错配。解决方案不是升级typing_extensions，而是降级到Python 3.10。具体操作如下：

# Mac用户（使用pyenv） pyenv install 3.10.13 pyenv local 3.10.13 python -m venv .venv source .venv/bin/activate pip install --upgrade pip setuptools wheel

# Windows用户（使用官方Python安装器） # 下载 Python 3.10.13 安装包，安装时务必勾选 "Add Python to PATH" # 然后在CMD中 python -m venv .venv .venv\Scripts\activate.bat pip install --upgrade pip

安装Harness本身非常简单，但有一个关键细节常被忽略：必须安装deepseek-harness[web]这个额外依赖组。如果你只运行pip install deepseek-harness，那么CLI功能是完整的，但harness serve命令会报错，提示ModuleNotFoundError: No module named 'fastapi'。这是因为Web UI的后端依赖FastAPI、Uvicorn、Jinja2等，它们被归类为可选依赖（Optional Dependencies），需要显式声明。所以正确的安装命令是：

pip install "deepseek-harness[web]"

注意引号的使用，这是为了防止Shell将方括号解释为通配符。安装完成后，验证是否成功：

harness --version # 应输出类似：deepseek-harness 0.3.2 harness --help # 应列出所有可用子命令

提示：如果你在一个已经存在大量其他Python项目的虚拟环境中安装，强烈建议创建一个全新的、干净的虚拟环境。我曾在一个装有langchain==0.1.0的环境中安装Harness，结果因为langchain依赖的tenacity==8.2.2与Harness所需的tenacity>=8.3.0冲突，导致harness run命令在重试逻辑上出现异常。干净的环境是稳定性的第一道防线。

3.2 编写你的第一个Agent：一个无需任何框架的“裸机”实现

Harness的强大之处，在于它对Agent的实现方式几乎没有任何约束。我们来写一个最简单的、符合Harness输入/输出规范的Agent。它不依赖LangChain，不引入任何外部框架，就是一个纯粹的Python函数。创建一个文件my_simple_agent.py：

import json import time from typing import Dict, Any def my_simple_agent(input_data: Dict[str, Any]) -> Dict[str, Any]: """ 一个极简的Agent示例：根据输入中的'query'字段，返回一个固定格式的响应。 这个函数就是Harness要“夹住”的目标。 """ query = input_data.get("query", "") # 模拟一些内部处理逻辑（比如调用模型、调用工具） if "天气" in query: # 模拟调用天气工具 tool_result = {"temperature": 26, "condition": "多云", "humidity": "65%"} return { "status": "success", "final_answer": f"北京明天的天气是{tool_result['condition']}，气温{tool_result['temperature']}摄氏度。", "steps": [ { "step_id": "1", "type": "intent_recognition", "input": query, "output": "query_weather" }, { "step_id": "2", "type": "tool_call", "tool_name": "get_weather", "input": {"city": "北京", "date": "tomorrow"}, "output": tool_result, "duration_ms": 120 } ] } else: return { "status": "success", "final_answer": "抱歉，我目前只支持查询天气信息。", "steps": [ { "step_id": "1", "type": "intent_recognition", "input": query, "output": "unknown_intent" } ] } # 这是Harness调用Agent的入口点 if __name__ == "__main__": # 用于本地测试 test_input = {"query": "北京明天的天气怎么样？"} result = my_simple_agent(test_input) print(json.dumps(result, ensure_ascii=False, indent=2))

这个Agent的核心价值在于它的契约清晰性。它只接收一个Dict，只返回一个Dict，且返回的Dict中必须包含final_answer（最终答案）和steps（执行步骤列表）这两个键。steps列表里的每一项，都描述了Agent在执行过程中的一次关键动作，包括类型、输入、输出和耗时。Harness正是通过解析这个steps列表，来构建CLI的文本输出和Web UI的可视化时间线。你完全可以把这个函数换成一个调用OpenAI API的真实LLM Agent，或者一个集成requests库调用内部HTTP服务的Agent，只要它遵守这个输入/输出契约，Harness就能无缝接入。

3.3 CLI模式：用一条命令完成单次执行与结果解析

现在，让我们用Harness的CLI来运行这个Agent。首先，我们需要一个标准的JSON输入文件。创建input.json：

{ "query": "上海后天的天气如何？" }

然后，在终端中执行：

harness run --agent my_simple_agent:my_simple_agent --input input.json

这条命令的含义是：

• harness run: 启动一次单次执行。
• --agent my_simple_agent:my_simple_agent: 指定Agent模块和函数。冒号前是Python文件名（不带.py后缀），冒号后是模块内的函数名。Harness会动态导入这个模块并调用该函数。
• --input input.json: 指定输入文件路径。

执行后，你会看到类似如下的结构化输出：

[INFO] Starting harness run with agent 'my_simple_agent:my_simple_agent' [INFO] Loading input from 'input.json' [INFO] Executing agent function... [INFO] Agent execution completed in 0.123s [INFO] Final Answer: 上海后天的天气是多云，气温26摄氏度。 === Execution Trace === Step 1 (intent_recognition): Input: "上海后天的天气如何？" Output: "query_weather" Step 2 (tool_call): Tool: get_weather Input: {"city": "上海", "date": "后天"} Output: {"temperature": 26, "condition": "多云", "humidity": "65%"} Duration: 120ms [INFO] Run completed successfully.

这个输出的价值在于它的可解析性。每一行都有明确的前缀（[INFO]、Step X），并且关键数据（如Duration: 120ms、Output:）都位于固定的文本位置。这意味着你可以轻松地用grep、awk或Python脚本来自动化分析。例如，要统计所有工具调用的平均耗时：

harness run --agent my_simple_agent:my_simple_agent --input input.json 2>&1 | \ grep "Duration:" | awk '{sum += $2; count++} END {print "Avg:", sum/count "ms"}'

注意：2>&1是将stderr（Harness的日志）重定向到stdout，这样才能被grep捕获。这是CLI模式下进行自动化分析的基石技巧。

3.4 Web UI模式：启动服务、上传输入、交互式追踪执行全过程

CLI适合快速验证，而Web UI则适合深度调试。启动Web服务只需一条命令：

harness serve --agent my_simple_agent:my_simple_agent

默认情况下，它会在http://localhost:8000启动一个FastAPI服务。打开浏览器，访问该地址，你会看到一个简洁的Web界面。界面上有一个文件上传区域和一个“Run”按钮。将我们之前创建的input.json文件拖拽进去，然后点击“Run”。

几秒钟后，页面会跳转到一个全新的URL，例如http://localhost:8000/run/7a8b9c0d1e2f。这个URL是本次执行的唯一ID，可以分享给同事。页面主体是一个垂直的时间线（Timeline），从上到下依次是：

1. Input Section: 显示原始的JSON输入，格式化为可读的树状结构。
2. Steps Section: 这是核心。每个steps数组中的元素，都渲染为一个独立的卡片。卡片顶部是步骤类型（intent_recognition），中间是输入（Input）和输出（Output）的JSON块，底部是耗时（Duration）。你可以点击卡片右上角的“Expand”按钮，展开查看更详细的元数据，比如该步骤的精确开始/结束时间戳。
3. Final Answer Section: 在时间线下方，用醒目的大字体显示final_answer的内容。

最强大的功能是交互式编辑与重放。假设你在Step 2里发现，模型传给get_weather工具的date参数是"后天"，但你的工具函数只接受ISO格式的日期字符串。你可以在Web UI里，直接点击Step 2的InputJSON块，它会变成一个可编辑的文本框。你把"date": "后天"改成"date": "2024-05-22"，然后点击旁边的“Rerun Step”按钮。Harness会跳过前面的Step 1，直接用这个修改后的输入，重新执行Step 2，并将新的输出（以及新的耗时）实时更新到页面上。这个“局部重放”功能，是调试复杂Agent工作流的神器，它让你能像调试一个函数一样，精准地隔离、修改、验证单个环节，而无需重新运行整个长链条。

4. 核心技术点深度解析：Harness如何实现无侵入式观测

4.1 输入/输出契约（Contract）的精妙设计：JSON Schema驱动的灵活性

Harness之所以能“夹住”任何Agent，其核心在于它定义了一个极其精简但又足够表达力的JSON Schema。这个Schema不是强制你继承某个基类，而是规定了你的Agent函数返回值的结构。其核心部分如下（简化版）：

{ "type": "object", "properties": { "status": {"type": "string", "enum": ["success", "error"]}, "final_answer": {"type": "string"}, "steps": { "type": "array", "items": { "type": "object", "properties": { "step_id": {"type": "string"}, "type": {"type": "string"}, "input": {"type": ["object", "string", "number", "boolean", "null"]}, "output": {"type": ["object", "string", "number", "boolean", "null"]}, "duration_ms": {"type": "number"}, "error": {"type": "string"} } } } } }

这个Schema的精妙之处在于：

• input和output字段被定义为anyOf类型，这意味着它们可以是任意合法的JSON值：一个复杂的嵌套对象（如工具调用的完整响应）、一个纯字符串（如模型的原始生成文本）、一个数字（如计算结果）或一个布尔值（如判断结果）。这避免了框架强加的“必须是字符串”或“必须是字典”的僵化限制。
• steps数组是可选的。如果你的Agent是一个极简的、无内部步骤的函数，你完全可以只返回{"status": "success", "final_answer": "Hello World"}，Harness依然能正常工作，只是Web UI里不会显示任何步骤卡片。这种“渐进式增强”的设计，让开发者可以从最简单的形态起步，随着Agent逻辑的复杂化，再逐步添加steps信息。
• error字段的存在，为错误处理提供了标准化通道。当Agent内部发生异常时，你不应该让Python抛出未捕获的Exception，而是应该捕获它，并在返回的steps中，为最后一步添加一个"error": "详细错误信息"。Harness会识别这个字段，并在CLI和Web UI中以红色高亮显示，同时将整个执行状态标记为"status": "error"。这比让程序崩溃然后看一屏幕的Traceback，要友好和可控得多。

4.2 CLI命令的底层实现：Subprocess与动态导入的双保险

当你运行harness run --agent my_simple_agent:my_simple_agent --input input.json时，Harness内部发生了什么？它并没有直接import my_simple_agent然后调用函数。相反，它采用了更健壮的子进程（Subprocess）隔离策略。其流程如下：

1. Harness主进程读取--input文件，将其内容解析为Pythondict。
2. Harness启动一个新的Python子进程，命令行类似于：python -m deepseek_harness._runner --agent my_simple_agent:my_simple_agent --input-json '{"query": "..."}。
3. _runner模块在子进程中，使用importlib.util.spec_from_file_location动态加载my_simple_agent.py文件，并用spec.loader.exec_module执行它。
4. _runner模块查找模块中名为my_simple_agent的可调用对象（函数或类），并用步骤1中解析的dict作为参数调用它。
5. _runner模块捕获函数的返回值，将其序列化为JSON，并通过sys.stdout打印出来。
6. Harness主进程捕获子进程的stdout，解析JSON，并格式化为用户看到的CLI输出。

这个设计带来了两大关键优势：

• 进程隔离：你的Agent代码中的任何全局状态（比如一个意外的global counter = 0）或内存泄漏，都不会污染Harness主进程。每次run都是一个全新的、干净的Python进程。这对于测试那些有副作用的Agent（比如会修改全局配置、会打开文件句柄）至关重要。
• 错误隔离：如果Agent代码中有语法错误（SyntaxError）或导入错误（ImportError），子进程会以非零退出码结束，Harness主进程能优雅地捕获这个错误，并给出清晰的提示，例如[ERROR] Failed to import agent module 'my_simple_agent': ModuleNotFoundError: No module named 'requests'，而不是让整个Harness崩溃。

4.3 Web UI的实时性保障：Server-Sent Events (SSE) 的轻量级流式传输

Web UI的“实时”体验，并非来自轮询（Polling），也不是复杂的WebSocket，而是采用了更轻量、更易实现的Server-Sent Events (SSE)。当你在Web UI中点击“Run”按钮时，前端JavaScript会发起一个EventSource连接到/api/run/stream?run_id=7a8b9c0d1e2f。Harness的FastAPI后端则会为这个请求建立一个长期连接，并在Agent执行的每一个关键节点（比如步骤开始、步骤结束、最终答案生成），向这个连接推送一个格式化的事件消息。例如：

event: step_start data: {"step_id": "1", "type": "intent_recognition", "timestamp": "2024-05-20T10:30:45.123Z"} event: step_end data: {"step_id": "1", "output": "query_weather", "duration_ms": 15.2} event: final_answer data: {"answer": "上海后天的天气是多云，气温26摄氏度。"}

前端的EventSource监听器会实时接收这些事件，并立即更新DOM。这种SSE方案的优势在于：

• 低开销：相比WebSocket，SSE是单向的（服务器→客户端），协议更简单，服务器端的资源消耗更低。
• 自动重连：EventSource浏览器原生支持断线自动重连，网络抖动时用户体验无感。
• 易于调试：你可以在浏览器的Network面板中，直接看到这些纯文本的SSE事件流，方便排查问题。而WebSocket的二进制帧则需要专门的工具才能解读。

5. 常见问题与独家避坑指南：来自真实战场的经验总结

5.1 “Unable to locate the codex cli binary or required runtime components” 类错误的根源与解法

这个错误信息虽然出现在热词列表中，但它与DeepSeek-Harness毫无关系。这是一个典型的“关键词污染”现象。codex cli是另一个完全独立的、由GitHub官方维护的CLI工具，用于与GitHub Copilot服务交互。而deepseek-harness是一个开源的、社区驱动的Agent测试工具。两者在代码库、作者、发布渠道、功能定位上均无任何交集。如果你在尝试安装DeepSeek-Harness时遇到了类似错误，那几乎可以100%确定，你是在一个错误的上下文中执行了命令。最常见的场景是：

• 场景A：在错误的虚拟环境中执行。你激活了一个之前用来安装codex-cli的虚拟环境，然后在这个环境中运行pip install deepseek-harness。由于codex-cli的安装可能修改了PATH或创建了某些系统级的符号链接，导致harness命令被错误地解析为codex的某个子命令。解法：退出当前虚拟环境，创建一个全新的、空白的虚拟环境，再从头开始安装Harness。
• 场景B：系统PATH中存在同名的旧二进制文件。你曾经手动下载过某个名为harness的二进制文件（可能来自其他项目），并把它放进了/usr/local/bin/。现在pip install安装的Python包中的harness脚本，被系统优先找到了那个旧的二进制文件。解法：运行which harness，查看它指向哪里。如果是/usr/local/bin/harness，那就用sudo rm /usr/local/bin/harness删除它。然后重新激活你的虚拟环境，pip install会正确地将harness脚本安装到虚拟环境的bin/目录下。

实操心得：永远用which <command>和<command> --version来确认你正在运行的，是你以为的那个命令。这是排查所有CLI工具冲突问题的第一步，也是最有效的一步。

5.2 Web UI启动后页面空白或报404：静态资源路径的隐秘陷阱

这是一个高频问题。你运行harness serve，终端显示INFO: Uvicorn running on http://localhost:8000，但浏览器打开后却是一片空白，或者显示404 Not Found。检查终端日志，你会发现类似WARNING: 404 GET /static/main.js的错误。这说明Uvicorn服务器找不到前端的静态资源文件（JS、CSS）。根本原因在于，deepseek-harness[web]这个额外依赖组，只安装了后端依赖（FastAPI等），但并没有安装或构建前端代码。前端代码是单独存放在一个frontend/子目录下的，需要你手动构建。

标准解法：

1. 克隆DeepSeek-Harness的官方仓库：git clone https://github.com/deepseek-ai/deepseek-harness.git
2. 进入仓库目录：cd deepseek-harness
3. 构建前端：cd frontend && npm install && npm run build
4. 构建完成后，frontend/dist/目录下会生成所有静态文件。
5. 然后，你需要告诉Harness后端这个dist目录的位置。有两种方式：
   • 方式一（推荐）：在启动服务时，用--static-dir参数指定：harness serve --agent my_simple_agent:my_simple_agent --static-dir ./frontend/dist
   • 方式二：设置环境变量：export DEEPSEEK_HARNESS_STATIC_DIR=./frontend/dist，然后运行harness serve

注意：npm run build需要你本地安装Node.js（v18+）。如果你不想折腾Node.js，官方也提供了预构建的Docker镜像，可以直接拉取使用：docker run -p 8000:8000 -v $(pwd):/app deepseekai/harness:latest serve --agent my_simple_agent:my_simple_agent。Docker镜像里已经包含了构建好的前端，省去了本地构建的麻烦。

5.3 Agent执行被终止（“agent execution terminated due to error.”）：如何从日志中定位真凶

这个错误信息非常笼统，它只告诉你“执行终止了”，但没告诉你为什么。此时，不要慌，Harness为你准备了两把“手术刀”：

• 第一把：CLI的详细日志模式。在harness run命令后，加上-v（verbose）或-vv（very verbose）参数。-v会显示更多的INFO级别日志，比如模块导入的详细路径；-vv则会显示DEBUG级别日志，包括子进程的完整启动命令、环境变量、以及最关键的——子进程的标准错误输出（stderr）。90%以上的“执行终止”问题，其根本原因都藏在子进程的stderr里。例如，你可能会看到：

  [DEBUG] Subprocess stderr: Traceback (most recent call last): File "/path/to/_runner.py", line 45, in <module> result = agent_func(input_data) File "/path/to/my_simple_agent.py", line 15, in my_simple_agent tool_result = get_weather(city="上海", date="后天") NameError: name 'get_weather' is not defined

  这个NameError就是真正的罪魁祸首。它告诉你，你的Agent代码里引用了一个不存在的函数get_weather。

• 第二把：Web UI的“Raw Logs”视图。在Web UI的执行详情页面，通常会有一个“Raw Logs”或“Debug Logs”的Tab。点击它，你会看到一个巨大的、未经格式化的文本块，里面包含了从Harness启动到执行结束的所有日志，包括子进程的stdout和stderr。你可以用Ctrl+F搜索关键词Traceback、Error、Exception，快速定位到错误发生的位置。

实操心得：永远不要只看错误信息的第一行。真正的线索，永远在Traceback的最后一行，那里写着具体的异常类型和消息。把这一行复制下来，粘贴到搜索引擎里，99%的问题都能找到答案。

5.4 性能瓶颈排查：当“CLI运行很快，Web UI却卡顿”时该怎么办？

这是一个非常有意思的现象。有时候，你在终端里运行harness run，整个过程不到1秒就完成了，但当你在Web UI里点击“Run”，却要等待5-10秒，页面才开始加载。这通常不是Harness本身的问题，而是前端资源加载的网络问题。Web UI的index.html、main.js、main.css等文件，都是由Uvicorn服务器从--static-dir目录下读取并发送给浏览器的。如果这个目录下的文件体积很大（比如未压缩的开发版JS），或者你的本地网络环境比较特殊（比如某些企业防火墙会对HTTP响应头做深度检测），就可能导致加载缓慢。

快速诊断与解决：

1. 打开浏览器的Developer Tools（F12），切换到Network标签页。
2. 刷新Web UI页面。
3. 观察所有GET请求的Size和Time列。如果main.js的Size显示为1.2 MB，而Time显示为3.5 s，那问题就很明显了。
4. 终极解法：确保你使用的是npm run build生成的生产版（Production Build）静态文件。生产版会自动进行代码分割（Code Splitting）、Tree Shaking（移除未使用代码）、以及Uglify（代码压缩）。一个开发版的main.js可能是2MB，而生产版通常能压缩到300KB以内。npm run build默认就是生产模式，但如果你不小心运行了npm run dev，那得到的就是一个巨大的、未压缩的开发包。

小技巧：在Network面板里，右键点击任何一个JS/CSS文件，选择“Copy” -> “Copy response”，然后粘贴到一个文本编辑器里。如果看到的是一堆乱码（如var _0x3a1b=["\x73\x63\x72\x69\x70\x74","\x63\x72\x65\x61\x74\x65\x45\x6C\x65\x6D\x65\x6E\x74",...]），说明它是经过Uglify压缩的，这是好现象；如果看到的是清晰的、带缩进的ES6代码，那说明你用的是开发版，需要重新运行npm run build。

6. 从验证到生产：Harness在Agent开发生命周期中的演进路径

Harness的定位非常清晰：它是一个验证（Verification）与调试（Debugging）工具，而非一个部署（Deployment）工具。理解这一点，是避免误用的关键。在Agent项目的完整生命周期中，Harness扮演的角色，更像是一个“质量门禁（Quality Gate）”，它存在于开发与测试阶段，而不是生产阶段。

• 在开发阶段，你用Harness的CLI进行“TDD式”开发。每写完一个新功能（比如增加一个“查询股票价格”的Skill），你就立刻写一个对应的input.json，然后用harness run验证它是否按预期工作。这个过程是快速、迭代、私密的，发生在你的个人电脑上。
• 在测试阶段，你将Harness集成到CI/CD流水线中。例如，在GitHub Actions里，你可以添加一个步骤：

  - name: Run Agent Integration Tests run: | harness batch --agent my_agent:my_agent --inputs tests/integration/

  harness batch命令可以一次性运行一个目录下所有的JSON输入文件，并生成一个汇总报告（JSON格式）。CI系统可以解析这个报告，如果任何一次执行的status不是"success"，就让整个构建失败。这确保了，任何破坏现有功能的代码提交，都会被立刻拦截。
• 在交付与协作阶段，你用Web UI生成一个“执行快照（Execution Snapshot）”。当你要向产品经理演示一个新功能，或者要和后端同事联调一个工具API时，你不再发一段文字描述，而是发一个`http://localhost:8000