基于角色分析的 Harness 过程方法：从 Agent 工具调用到工程化落地

前阵子团队里做 AI Agent 的同事往群里甩了一句话：“agent harness 可以发起工具调用，而不是自己就是工具。”我看着这句话愣了一下，紧接着意识到，这其实把很多人对 harness 的理解给纠正过来了。我们团队内部一直习惯把“基于角色分析的 Harness 过程方法”叫做 K2 方法，核心就一句话：先问清楚“这个任务里到底有哪几类角色在协作”，再让 harness 去承载这些角色的规则、技能和工具权限，而不是把一个复杂任务直接丢给模型让它自由发挥。

这篇文章就是把这套方法完整拆开讲一遍：Harness 到底解决了什么问题，角色分析怎么做，rules 和 skills 该怎么配，落到 deepseek harness、codex harness 这类具体工程环境里又该怎么跑。同时我会把部署和运行阶段高频出现的几个报错，比如插件注册失败、局域网访问不了、模型不支持图片、md 文件读取不到这些，全部按排查链路复盘一遍。适合正在用或准备用 harness 做 AI 应用的人，也适合对“harness engineering”“agent harness”这个概念好奇、想知道它和普通 Agent 编程有什么区别的读者。

1. Harness 的定位：它不是工具，而是能让工具被正确调用的“驾驶舱”

1.1 Harness 与 Agent、Tool 的本质区别

很多人第一次接触 harness 这个词，都是从“deepseek harness”“codex harness”这类开源项目开始的。装完之后最大的困惑是：这不就是一个能调用工具的 Agent 吗？为什么非要起一个新名字？

我用一个类比来解释。把模型当成一个刚入职的高潜力新人，业务能力强，但没人告诉他公司流程、资源边界、该用哪些系统、事情做完交给谁。Agent 就是这个新人本身，Tool 是他手里能用的各种工具，而 Harness 是那套完整的“入职手册 + 工位权限 + 项目管理流程 + 质量验收标准”。

所以“agent harness 可以发起工具调用，而不是自己就是工具”这句话说得非常准确。工具是锤子、螺丝刀、电钻，harness 是那个决定“现在该用哪个、用完怎么归位、哪些地方绝对不能碰”的施工负责人。它自身不产出具体能力，但它控制着能力被调用的全过程。

“harness 和 agent 区别”这个问题，答案就藏在上面这张表里。Agent 是运行在模型之上的决策单元，而 Harness 是把 Agent、工具、规则、上下文、权限全部包起来的执行环境。没有 harness 的 Agent 就像没有规则的自由搏击，能打，但不可控；有了 harness，才变成有裁判、有护具、有回合限制的正式比赛。

1.2 为什么“角色分析”是 Harness 过程方法的第一步

知道 Harness 是什么之后，下一个问题就是：怎么设计一套好用的 Harness 配置？

我们团队早期的做法非常粗暴，把工具列表全部写进配置，然后把任务丢给一个 Agent。结果很快就翻车了。工具一多，Agent 开始自我冲突：它在同一个上下文里既当数据分析师又当文件编辑器还当质量审核员，经常出现“分析到一半顺手改了源文件”“报告生成完忘了校验数据”这类问题。最麻烦的是，出问题之后你不知道该改哪里，因为你根本没有给整个执行过程定义过“谁在什么阶段该干什么”。

后来我们借用了团队管理里的思路：一个任务能顺利推进，是因为有人负责拆解需求、有人负责查资料、有人负责写代码、有人负责验收。这些人各管一摊，有明确的职责边界和交接物。AI 任务也是一样，所以我们提出了“基于角色分析的 Harness 过程方法”。

这个方法的核心是：在写任何一条 rules、配任何一个 skill 之前，先完成角色分析。角色不是凭空想出来的，而是从任务描述中“主语化提取”出来的。你把任务里的每个动作都问一遍“谁来做这件事”，答案就是角色雏形。然后对角色做合并、裁剪、定边界，最后再映射到 harness 配置里去。

为什么强调“过程方法”而不是“提示词技巧”？因为提示词技巧只解决“让模型说得更好”的问题，而 Harness 方法解决的是“整个任务在可控的流程里跑完”的问题。角色分析关注的不只是最后的输出，更是执行过程中的每个阶段：谁发起了调用、调了什么工具、产出物交给谁、哪个节点需要人来确认。过程中每一步都可以被观测、被审计、被回滚，这才能叫工程化。

1.3 一个任务从想法到 Harness 配置的完整路径

我们内部现在跑任务的固定路径是六步：需求澄清、角色识别、边界定义、协作编排、配置映射、运行复盘。

需求澄清解决“到底要做什么”；角色识别解决“有哪些参与者”；边界定义解决“每个参与者能碰什么、不能碰什么”；协作编排解决“先后顺序和交接物”；配置映射解决“角色怎么翻译成 rules、skills、tools”；运行复盘解决“跑完一遍后哪些角色设计不合理”。这篇文章接下来会按这条路径展开，重点放在角色识别到配置映射这一段，因为这是最容易被跳过、又最影响成败的部分。

2. 从零拆解“角色分析”：四个建模步骤决定 Harness 质量

2.1 从任务描述中抽角色，而不是拍脑袋设计

角色分析的第一步不是去翻 Harness 文档，而是把用户需求原话拿出来做“主语提取”。

举个例子，一个任务描述是：“请读取 docs 目录下的项目说明文档，统计每个项目的技术栈，对比异同，输出一份 markdown 报告。”这个描述里的动作有“读取”“统计”“对比”“输出”。每个动作的主语是谁？如果按最原始状态，动作的主语全是同一个 Agent，但这样就会出现前面说的混乱局面。

正确做法是先把动作分组。读取和统计偏向“资料整理”，对比和输出偏向“报告生成”，中间还可以加一个“质量校验”角色。提取出来的原始角色是：文档阅读者、技术栈提取者、对比分析者、报告撰写者、质量校验者。五个角色对于一个简单任务来说太碎了，于是进行合并：文档阅读者加技术栈提取者合并为“资料整理者”，对比分析者加报告撰写者合并为“报告生成者”，质量校验者保留。

合并的原则是：两个角色如果使用的工具高度重叠、且先后顺序固定，就可以合并；如果它们使用的工具完全不同，或者需要互相牵制，就必须分开。技术栈提取和报告生成使用的工具完全不同，前者要读文档、跑命令，后者要写文件、组织排版，所以分开是合理的。

2.2 角色边界的设定：最小权限原则

角色拆完之后，下一步是给每个角色划定边界。这一条我们直接借用了信息安全领域的最小权限原则：每个角色只拥有完成自身任务所必需的最小权限，不相关的一律不给。

还是用上面那个例子。

边界的作用有两个。第一，防止模型“越权”。模型天然有讨好用户的倾向，用户说“帮我看看文档”，它可能顺手就把文档里的 TODO 注释当成结论写进报告。第二，让问题可追溯。某一环节出错了，你只需要检查对应角色的输入输出，不需要从头到尾重读一遍整个上下文。

没有边界的设定，不如不设角色。因为角色之间的制衡关系才是流程稳定性的来源，如果每个角色都能写文件，那“报告生成者”的权限就没有意义了，质量校验也失去了独立第三方的属性。

2.3 协作编排：串行、并行与人工确认点

角色边界定义完之后，要定义角色之间怎么协作。协作方式有三种基本形态：串行、并行、带人工确认的暂停。

串行是指前一个角色的输出作为后一个角色的输入，比如资料整理者的技术栈清单就是报告生成者的输入。并行是指多个角色在同一阶段同时工作，例如同时读取三份文档，最后汇总。带人工确认的暂停是指流程跑到关键节点时停下来，请用户确认产物符合预期后再继续往下走。

一个典型的编排是这样的：需求澄清完成后，资料整理者并行读取多份文档，产出技术栈清单；然后进入人工确认点，用户确认清单无误；接着报告生成者基于清单生成报告；最后质量校验者做一致性检查，输出校验意见和最终报告。整个过程不是把所有角色全部混在一个上下文中，而是让每一个角色专注于自己那一段，交接物是显式的文件或数据结构。

在 Harness 配置里，这些交接物会成为角色之间的“契约”。你不需要关心模型内部怎么想的，只需要保证交接物的格式稳定，角色切换就不会乱。这也是为什么我们把“角色分析”放在配置之前：不先定义交接物，后面写 rules 的时候根本没有抓手。

2.4 从角色到 Harness 配置的映射关系

角色分析做完之后，最后一步才是写配置。映射关系大致是这样的：角色对应 Harness 里的一组 rules 和一组 skills；角色的职责边界对应工具白名单；角色的输入输出对应交接物格式；协作编排对应 workflow 的触发顺序；人工确认点对应 Harness 的暂停/恢复机制。

Rules 负责“不能做什么”，Skills 负责“能做什么、怎么做”，Tools 负责“实际动作”，Workflow 负责“什么时候做”。四个机制配合起来，才能把一个抽象的角色变成可执行的程序结构。

3. 落地配置：rules、skills 与工具权限的具体写法

3.1 一份可以直接参考的 Harness 配置骨架

下面是一份简化但结构完整的配置示例，运行环境是命令行版 harness，配置格式为 YAML。

yaml复制harness:
  name: report-runner
  model:
    default: deepseek-chat
  workspace: ./workspace

  roles:
    - name: data_collector
      rules:
        - rules/file-access.md
        - rules/no-modify-source.md
      skills:
        - skill/doc-reader
        - skill/tool-extractor
      tools:
        - read_file
        - list_files
        - grep
      inputs:
        - docs/
      outputs:
        - workspace/tech_stack.md

    - name: report_writer
      rules:
        - rules/markdown-style.md
      skills:
        - skill/report-render
      tools:
        - write_file
      inputs:
        - workspace/tech_stack.md
      outputs:
        - workspace/final_report.md

  workflow:
    - stage: collect
      role: data_collector
      action: run
    - stage: confirm
      role: human
      action: approve
    - stage: write
      role: report_writer
      action: run

几个关键点说明一下。model 字段可以按角色覆盖，后面会讲图像识别任务的模型切换。roles 里的 inputs 和 outputs 是角色间的交接物契约，Harness 跑的时候会检查这些文件是否存在，避免角色之间“空对空”对话。workflow 里插了一个 role 为 human 的 stage，作用是暂停执行，等人确认后再继续。

3.2 Rules 和 Skills 的区别与正确写法

很多新手搞不清 rules 和 skills 的区别，经常把所有约束全塞进 rules，把所有示例全塞进 skills，结果两边都很臃肿。

Rules 是“无论什么时候都必须遵守/必须避免”的约束，它的特点是跨任务复用。比如“不要修改源文件”“所有报告输出使用中文”“任何删除操作前必须请求用户确认”。Rules 的粒度要细，一条规则只讲一件事，方便 trace。一条好的 rule 示例是：“data_collector 阶段禁止调用 write_file 工具”。这个规则直接和角色边界挂钩，比“请小心操作文件”这种模糊描述有效得多。

Skills 是“可复用的能力包”，通常是一个目录，里面包含技能说明、使用步骤、few-shot 示例和输出模板。例如：

text复制skills/report-render/
├── SKILL.md
├── examples/
│   └── report_example.md
└── templates/
    └── report_template.md

SKILL.md 的开头要写清楚这个技能什么时候该触发、什么时候不该触发，避免模型在错误的场景调用。然后给出操作步骤，最后附上一个完整的输出模板。模板的价值在于稳定输出格式，报告生成这种任务尤其需要。模型通过 few-shot 才能稳定产出同样结构的 markdown，光靠 instructions 描述格式是不够的。

3.3 让 Harness 正确读取 md 文件

“deepseek harness 怎么读取 md 文件”这个问题被问得特别多，很多人的卡点不是写配置，而是路径认知不一致。

Harness 进程的工作目录和你当前命令行所在的目录不一定一致。如果你在配置里写的是相对路径“docs/项目说明.md”，那它解析这个路径时是相对于 Harness 进程的工作目录，而不是你执行命令时所在的目录。解决方案有两种：一是在配置里写绝对路径；二是在启动命令里显式指定工作目录，例如通过 --workspace 参数。

更推荐的做法是把 md 文件作为 Skill 的一部分，纳入 skills 目录管理，然后在 rules 里只允许特定角色读取这个目录。这比把整篇文档塞进系统提示词要稳健得多。整篇塞进去的后果是 token 消耗急剧上升，而且文档一长，模型反而抓不住重点。正确的做法是：在 SKILL.md 里只写文档的摘要和索引，需要细节时再通过 read_file 工具按需读取对应章节。

3.4 模型切换：图片识别任务怎么配置

配置过程中最容易出现的模型问题，就是“当前模型不支持图片，请切换支持图片的模型”。原因很简单：纯文本模型没有视觉编码器，输入图片要么报错，要么被忽略。

解决方案是按角色指定模型。图像识别任务里，图片分析这个角色要绑定到视觉模型，其他文字处理角色仍然用通用模型。

yaml复制roles:
  - name: image_analyzer
    model:
      type: vision
      name: deepseek-vl
    tools:
      - read_image
      - describe_image
    outputs:
      - workspace/image_notes.md

  - name: report_writer
    model:
      type: text
      name: deepseek-chat
    inputs:
      - workspace/image_notes.md
    tools:
      - write_file

这里说句题外话。有人问能不能用 harness 直接“生成一个图像识别软件”，我的回答是：Harness 能做的是把图像识别模型、规则、脚本、报告流程编排起来，跑出一条自动化的图像识别任务链。它不是一个 IDE，不会替你打包发布软件，但它完全可以当一个快速原型工具，把“读图、识别、出报告”这条链路自动跑通。你甚至可以让它读取识别结果并自动生成测试用例，但真正发布成产品，还是得有工程化的打包、部署和监控环节。

4. 实战走查：多角色报告生成任务从拆解到验收

4.1 任务设定与实际角色分析产物

下面用一个我们真实跑过的任务来走一遍完整流程。任务描述是：“读取 docs 目录下的三份项目说明，梳理每个项目的技术栈，对比三者的差异，输出对比表格并给出选型建议。”

角色分析产物如下：

这个表就是整个 Harness 配置的蓝图。配置里每个 role 的 rules、skills、tools、inputs、outputs，都可以直接从这张表里抄出来。发现没有？角色分析做完了，写配置其实只是翻译工作。

4.2 从启动到验收的关键节点

启动命令很简单，类似这样：

bash复制harness run --config report-runner.yaml --task "读取 docs 目录下的三份项目说明，梳理技术栈并对比选型"

跑起来之后，要关注几个关键节点。第一个节点是“文档索引者”的输出，如果文件清单里缺了文件，后面所有环节都会缺数据。第二个节点是“技术栈抽取者”写出的 tech_stack.md，它决定整个报告的数据基础。第三个节点是“对比分析师”的结论是否支持选型建议。最后一个节点是人工确认，也就是 workflow 里的 human approve。

运行日志里会有每个角色的 start 和 finish 标记，工具调用记录会显示每个角色实际用了哪些工具。验收的时候不要只看 final_report.md 有没有生成，而要反过来验证：报告里的每一项对比结论，能不能在 tech_stack.md 里找到原始依据。这一步是质量校验者角色的核心工作，也是很多 automated workflow 最容易省略的部分。

4.3 第一版配置必然踩到的三个坑

第一个坑是角色拆得过细导致上下文和 token 爆炸。我们第一版把文档索引者和技术栈抽取者拆成了两个独立角色，各自都要读一遍完整的 docs 目录。文档一多，token 消耗直接翻倍。后来合并成“资料整理者”，只读一次文档，把索引和抽取合并到同一个角色内部，token 消耗大幅下降。合并原则很简单：如果两个角色读取的数据源完全重叠、且顺序固定，就合并。

第二个坑是读取 md 文件失败，原因正是前面说的路径歧义。配置里写的是 docs/，但 harness 的工作目录不对，结果返回 file not found。排查链路也很短：先看日志里实际拼接出来的路径，再用 pwd 确认进程工作目录，最后改配置或者显式指定 --workspace。

第三个坑是模型不支持图片。任务里带了几张架构图，默认模型直接报错“当前模型不支持图片，请切换支持图片的模型”。解决方式是给图片分析单独指定视觉模型，同时把图片描述转成文字后重新注入上下文，这样后面的报告生成角色就不需要直接接触图片了。

5. 部署与运行阶段的三类高频报错和完整排查链路

5.1 插件注册失败：runtime codex is unavailable

这个报错常见于 codex runtime 相关的 Harness 配置，完整的提示会像这样：“error: agent harness runtime 'codex' is unavailable because its plugin registration failed”。看到这个报错，先别急着重装 harness，按下面的顺序排查。

第一步，看日志里 plugin 加载阶段的具体输出，确认是不是真的加载了插件。第二步，检查插件目录，确认 codex runtime 插件文件是否存在，权限是否可读。第三步，检查环境变量，很多插件注册失败的原因是 HARNESS_PLUGIN_PATH 或类似变量指向了错误目录。第四步，确认插件版本和 harness 主版本兼容，常见问题是主程序升级后插件没同步升级，导致 ABI 不匹配。

我用表格整理一下常见原因和对应动作：

这四步走完，98% 的插件问题都能定位。我见过最离谱的情况是用户同时装了两个版本的插件目录，环境变量指向旧的，插件文件还在但版本不匹配，日志里完全看不出文件缺失，只有注册失败。

5.2 局域网访问与本地连接配置

“deepseek harness 局域网访问”“deepseek harness 本地连接 ubuntu”这类搜索背后，通常是同一个需求：harness 跑在 Ubuntu 服务器上，想从笔记本的浏览器或桌面端连过去。

默认情况下 harness 服务只监听 127.0.0.1，局域网内其他设备自然访问不了。需要在服务配置里把监听地址改成 0.0.0.0，同时指定端口。这一步之后还要检查防火墙，Ubuntu 上如果开了 ufw，要放行对应端口。安全方面有一条必须强调：监听 0.0.0.0 意味着局域网内所有设备都能访问服务，务必设置访问令牌或认证，不要裸奔。

服务化运行建议用 systemd 而不是 nohup，这样崩溃后能自动重启，日志也统一管理。一个最小 systemd 单元文件大概长这样：

ini复制[Unit]
Description=Harness Service
After=network.target

[Service]
User=youruser
WorkingDirectory=/opt/harness
Environment=HARNESS_API_KEY=xxxx
ExecStart=/usr/local/bin/harness serve --host 0.0.0.0 --port 8080
Restart=on-failure

[Install]
WantedBy=multi-user.target

配置好之后，局域网内访问地址就是 http://服务器IP:8080，记得确认 IP 是内网地址还是通过路由器转发的地址。如果你只在本地调试，老老实实保持 127.0.0.1，没必要开放端口。

5.3 桌面版、Ubuntu 服务版与命令行版的选型

Harness 的几种使用方式，定位并不一样。桌面版适合日常调试、可视化查看工具调用过程、快速验证角色配置是否合理。命令行版适合脚本化、批处理、集成进 CI/CD。Ubuntu 服务版适合 7x24 小时挂机跑任务，或者给多个人共享同一套 harness 环境。

我建议刚开始不要直接上服务版。先在桌面版把角色分析、rules、skills 配好，跑通一个小任务，再迁到命令行版，最后再考虑服务化。跳过调试阶段直接上服务，遇到插件注册、路径、模型这类问题，排查成本会高很多。

另外，几个版本之间最容易出现的问题就是配置和插件版本不同步。桌面版自动更新后，命令行版没更新，两边配置格式开始分叉。解决办法是把配置和插件版本号锁进项目的 requirements 文件，每次升级显式确认一次，不要让工具静默升级。

回到这篇文章的主题，我最后想说的是，基于角色分析的 Harness 过程方法，真正的价值不在于配置写得多花哨，而在于逼着你在写配置之前，先把任务的协作结构想清楚。角色是谁、边界在哪、交接物是什么、哪里需要人来确认，这些想透了，rules 和 skills 只是翻译工作。我见过太多失败的 harness 配置，原因几乎都是角色混在一起，一个 agent 又当运动员又当裁判，最后输出质量没人负责。从一个小任务开始，把角色分析当成配置的前置步骤，你会明显感觉到整个过程比盲目堆 prompt 稳定得多。等这套流程跑顺了，再慢慢增加角色数量、技能包和自动路由，甚至去研究 hermes 这类协议层面的演进，都会顺手很多。