OpenCode + Harness：构建可复现的智能体数据分析流水线

我最近在整理一套数据分析项目的时候发现之前的处理流程特别笨先手动写 Python 清洗脚本再逐个排查异常值最后还要把结论复制进报告里。正好那阵子在深入折腾 OpenCode 智能体 和 Harness 这套架构索性把整个分析链路交给了它们。跑通之后回头梳理了一下从 Harness 核心架构到真正完成一次数据分析实操这个过程中的关键点、踩过的坑、以及配置上的细节我认为值得完整记录下来。这篇东西会从为什么选这套组合讲起再拆两个核心部分Harness 的架构逻辑以及 OpenCode 在数据分析场景里的完整落地方式。我的目标读者很明确已经知道智能体能写代码、能调工具但还没有系统地把它们组合成一条数据分析流水线的人。或者你已经试过 LangChain、Dify 之类的平台想在更轻量的终端智能体方向上找一条可控、可复现的路径。这篇文章不打算做全量教程但会把真正影响结果的关键环节讲透。1. 为什么是 OpenCode Harness终端派和编排派的互补组合1.1 终端智能体和框架智能体的区别先说个大背景现在市面上的智能体工具大致可以分成两派。一派是平台型比如 Dify、Coze 这种给你可视化的编排界面拖拽节点搭工作流好处是上手快坏处是离开平台之后整个体系就很难迁移。另一派是终端型典型代表是 OpenCode 这类跑在 CLI 里的智能体它直接在文件系统、Git 仓库、命令行环境里工作。你给它一个任务它自己读代码、写代码、执行命令、看报错、再修改整个循环都在终端里完成。OpenCode 最打动我的一点是它的“就近操作”能力。数据分析场景里原始数据、清洗脚本、可视化代码、最终报告全是散落在本地目录里的文件。平台型智能体要操作这些文件通常得先上传、建知识库、配插件链路很长。而 OpenCode 直接在项目目录里跑它天然拥有文件系统访问能力、命令执行能力甚至能自己调用 Python 写分析脚本再跑一遍。这种模式省掉了大量“搬运数据”的环节。但终端智能体也有短板它通常只有一个主循环适合完成“一条主线”的任务。一旦任务变成“数据清洗、特征探索、异常归因、报告生成”四条线并行单靠一个对话循环会很乱上下文容易互相污染。这就轮到 Harness 这类框架出场了。1.2 Harness 在整套组合里补的是什么位置Harness 在我理解里是一个偏“硬编码逻辑”的智能体编排框架。它和 LangGraph 有点像但又不太一样LangGraph 强调的是图结构的灵活性而 Harness 更强调“约定优于配置”它用一套明确的核心原语帮你把智能体层面的协作关系固定下来。你可以这样理解OpenCode 是手脚负责执行Harness 是躯干和神经系统负责把“谁来做、按什么顺序做、做完了给谁”这条链路定死。数据清洗的那个 Agent 不该突然去生成图表生成图表的 Agent 也不该自作主张去改写原始数据这些约束正是 Harness 的核心价值。我当前实验环境的组合是这样的OpenCode 作为主交互入口和模型调度层负责跟本地文件系统、命令行工具交互Harness 作为编排层管理多个专项 Agent每个 Agent 有独立的任务描述、可用工具和输出位置底层的模型调用则根据任务类型混用官方模型和 OpenRouter 上的路由模型。后面我会具体写配置。这套组合真正解决的是我实际工作中一个很现实的痛点单模型智能体太“黏糊”。用一套上下文做完清洗再做可视化前期清洗阶段的细节会严重影响后段的风格和判断。拆成多个 Agent 由 Harness 编排之后每个 Agent 的上下文范围被限定任务边界清晰最后合起来反而更像一个稳定的流水线。2. Harness 核心架构拆解三个原语和一条决策循环2.1 Agent、Workflow、Attachment 各管什么我在学习 Harness 的时候最先梳理清楚的是它三个最核心的原语Agent、Workflow、Attachment。Agent 是执行单元。每个 Agent 有自己的系统提示词、模型配置和工具列表。在数据分析场景里我会定义一个清洗器Agent它的系统提示词只包含列名约定、清洗规则和质量标准再定义一个分析器Agent它的提示词则专门关注统计方法和结论口径。两个 Agent 可以共享同一个底层模型但它们的“行为约束”完全不同。不要小看这个差异智能体应用里很多失控问题根源就是“一个提示词想干所有事”。Workflow 是流程骨架。它定义了 Agent 之间的连接关系可以是简单的顺序链也可以带分支判断。Harness 支持把 Workflow 写成可读的声明式配置我通常用 YAML 或 JSON 维护。比如“数据清洗完成后如果字段缺失率超过 30%就转到数据质量报告分支否则进入主分析链路”。这种基于结果的跳转比单纯靠对话让模型自己“悟”要靠谱得多。Attachment 则是挂在 Agent 上的附加资源和上下文。比如给某个分析 Agent 挂上一份字段字典、一份指标口径说明、甚至一段历史分析结论。Attachment 的好处是它不占用主对话上下文而是在 Agent 真正需要时按需加载。这让我可以把大量背景知识挂在工作流里又不会导致每次调用都把所有内容塞给模型。2.2 规划-执行-反思LLM 驱动循环的底层逻辑Harness 的每个 Agent 内部跑的是一个经典的“规划-执行-反思”循环这也是它跟普通函数调用的本质区别。规划阶段Agent 拿到任务输入之后不是立刻写代码而是先生成一份简短行动计划。我在实际运行里经常看到它输出类似“第一步读取 sales_2024.csv 并检查列名第二步检查缺失值比例第三步决定是否需要插补”这样的计划。这个步骤的隐藏价值在于它让 Agent 在动手前先把思路固定下来后续如果执行结果不对劲对比计划能更快定位是哪一步出了问题。执行阶段Agent 开始调用工具。在 OpenCode 的场景下工具就是终端命令、文件读写、代码执行这些能力。这里有个经验给 Agent 的执行工具不要贪多。工具列表越长模型做选择的负担越重误调用概率也越高。我通常只开放 4 到 6 个高频工具其他通过 Workflow 在外部解决。反思阶段Agent 会看成败结果。比如脚本报错、输出不符合预期它会自己读错误信息和分析结果然后调整策略重新执行。这个循环的次数需要设上限我在 Harness 里通常会限制单任务最多重试 3 次。超过上限就直接降到人工处理避免模型在同一个坑里反复打转既烧 token 又浪费时间。2.3 Harness 和 LangGraph 这类通用框架的定位差异很多人会问Harness 和 LangGraph 到底有什么区别包括我最初也纠结过。LangGraph 是一个通用图框架相当于给你一盒乐高积木节点、边、状态、条件分支你想怎么拼就怎么拼。灵活性极高但代价是很多工程化的东西——比如模型配置、上下文管理、错误重试、输出校验——需要你自己搭一套约定。团队合作时不同人拼出来的“图风格”差别很大维护成本不会低。Harness 更像一套“带规则的乐高说明书”。它把 Agent 之间常见的协作模式抽象成了约定好的原语比如上面说的 Agent、Workflow、Attachment。你用 Harness 搭出来的结构团队里的另外一个人一眼就能看懂哪个 Agent 负责什么、数据怎么流动、在哪一步做质量检查。个人体会是如果你是做探索性实验LangGraph 的自由度是优势如果你要把智能体流程固化成一个可以被反复执行、还要给别人维护的“数据产品”Harness 的约束反而是效率来源。我目前所有“要跑很多次”的分析模板全部用 Harness 固化而一次性探索仍然会用 OpenCode 直接面对模型对话。3. OpenCode 环境搭建和配置避坑从免费额度到 skills 编写3.1 安装与初始化OpenCode 是 Go 写的单一二进制分发安装不算复杂但版本演进比较快踩坑集中在配置层面而非安装环节。我当时的做法是直接到官方仓库的 Releases 页面下载对应平台的二进制放到/usr/local/bin下然后跑一次opencode init做初始化。这个交互式初始化会问你默认模型、Provider 等信息会生成一份配置文件。需要注意不同版本的初始化和配置项有一定差异如果你照着网上已经过时的教程操作很可能在模型调用阶段跑不通。我的建议是以你安装的这个版本的官方文档为准配置文件结构以 init 生成的实际内容为基准来改。初始化完成之后OpenCode 会要求你配置模型 Provider。这一步是后面所有事情的地基如果 Provider 配不对后面所有 Agent 的“智能”都无从谈起。3.2 模型 Provider 配置官方免费额度的限制与 API Key 方案OpenCode 官方对免费试用额度有很明确的限制提示。我在实际使用中遇到过控制台返回这样的错误error from provider (console): opencodes free tier can only be used from wi...后面半句基本就是告诉你免费额度只能在特定环境下用。这不算 bug官方对免费额度的使用地点和行为有严格约束。我的处理是不依赖免费额度做任何实际项目直接配置自己的 API Key。目前我比较稳的配置方案是走 OpenRouter把多种模型统一通过一个 Key 接入切换模型时只改配置不改代码。下面是一个典型的 OpenCode 配置文件片段作用是注册 OpenRouter Provider 并指定默认的推理模型。{ $schema: https://opencode.ai/config.json, provider: { openrouter: { models: [ anthropic/claude-3.5-sonnet, deepseek/deepseek-chat, qwen/qwen2.5-vl-72b-instruct ] } }, model: anthropic/claude-3.5-sonnet }这里想多说一句模型选型。数据分析链路里编码和清洗环节用通用能力强的模型涉及多模态图表的环节比如要判断一张可视化图的排版是否合理、坐标轴标签是否完整可以切到支持视觉输入的模型像 Qwen 的 VL 系列。通过 OpenRouter 一个 Key 就能在这几类模型之间切换这个灵活性对我这种“不同环节用不同模型”的需求很关键。如果你对把数据发给第三方接口比较敏感也可以用本地模型。OpenCode 配置本地模型通常是配一个兼容 OpenAI 协议的服务地址比如 Ollama。下面是一个示例{ provider: { ollama: { models: [qwen3-vl:latest] } }, model: qwen3-vl:latest }本地模型的优势是数据不出机器劣势也很明显分析质量明显依赖机器配置且复杂推理任务的速度和效果不如云端模型。我自己的权衡标准是涉敏感数据时用本地模型非敏感且追求质量时走云端。3.3 skills 怎么写才算“真会用”OpenCode 的 skills 机制简单说就是给智能体预置一套“专业技能包”。每个 skill 是一个带描述头和正文说明的 Markdown 文件里面写清楚该技能的使用场景、步骤、注意事项甚至可以附带示例代码。这比你在对话里临时说“帮我分析数据”要可靠得多因为技能包里的步骤是经过验证的固定流程。以数据分析场景为例我第一个建议封装的 skill 叫“数据画像”。它的作用不是直接做分析而是先快速生成数据集的结构化画像为后续 Agent 提供决策依据。--- name:>