Agent编排Agent Devs

OpenHarness：港大开源的轻量级 Agent 框架

by admin

最近香港大学数据科学研究所（HKUDS）开源了 OpenHarness 项目。这是一个基于 Python 的轻量级 Agent 框架，定位为”Agent Harness 的开源实现”。

项目核心数据：

维度Claude CodeOpenHarness比例
代码量512,664 行11,733 行2.3%
文件数1,8841638.6%
工具数~444398%
命令数~885461%
语言TypeScriptPython–

44 倍的代码量差距，接近 100% 的工具兼容，这一数据对比引发了开发者社区的关注。

架构设计：Harness 的本质

OpenHarness 的核心理念可以概括为一句话：

The model is the agent. The code is the harness.

这一理念将 Agent 系统拆分为两个层次：

  • 模型层（Agent）：提供推理、规划、决策能力
  • 框架层（Harness）：提供工具调用、权限控制、记忆存储、多 Agent 协调

一个纯聊天模型只能输出文本。当模型接入 Harness 后，它获得了文件读写、命令执行、网络请求、持久记忆等能力——从”会说”变成”能做”。

OpenHarness 实现的就是这个 Harness 层。

10 大子系统

OpenHarness 的架构由 10 个核心子系统组成：

子系统职责
EngineAgent 主循环：query → stream → tool-call → loop
Tools43 个工具：文件 I/O、Shell、搜索、Web、MCP 协议
Skills按需加载的领域知识（.md 文件）
Plugins扩展机制：命令、钩子、Agent 定义
Permissions三级权限模式、路径规则、命令黑名单
HooksPreToolUse/PostToolUse 生命周期钩子
Commands54 个斜杠命令
MCPModel Context Protocol 客户端
Memory跨会话持久记忆（MEMORY.md）
Coordinator多 Agent 协调、子 Agent 派发

Agent Loop 实现

Engine 是整个框架的核心。其运行逻辑如下：

while True:
    response = await api.stream(messages, tools)
    
    if response.stop_reason != "tool_use":
        break  # 模型完成任务
    
    for tool_call in response.tool_uses:
        # 权限检查 → 钩子 → 执行 → 钩子 → 结果
        result = await harness.execute_tool(tool_call)
        messages.append(tool_results)
    # 循环继续，模型根据结果决定下一步

模型决定”做什么”，Harness 负责”怎么做”——包括权限校验、执行、结果格式化。

核心能力分析

1. 工具体系

OpenHarness 提供的 43 个工具覆盖以下类别：

  • 文件 I/O：Read、Write、Edit、Glob、Grep
  • Shell：Bash 执行，支持权限控制
  • 搜索：WebFetch、WebSearch、ToolSearch
  • Agent：Agent（子 Agent）、SendMessage、TeamCreate
  • 任务：TaskCreate/Get/Update/Stop/Output
  • MCP：MCPTool、ListMcpResources

每个工具具备：

  • Pydantic 输入验证
  • JSON Schema 自描述
  • 权限集成
  • 钩子支持

2. 权限控制

三级权限模式：

模式行为适用场景
Default写入/执行前询问日常开发
Auto全部允许沙箱环境
Plan阻止所有写入代码审查

支持路径级规则配置：

{
  "permission": {
    "mode": "default",
    "path_rules": [{"pattern": "/etc/*", "allow": false}],
    "denied_commands": ["rm -rf /", "DROP TABLE"]
  }
}

3. 多模型支持

OpenHarness 支持多种模型后端：

  • 本地 Ollama（免费、私密）
  • OpenAI API
  • Claude API
  • Deepseek、Qwen 等

配置示例：

# 使用本地 Ollama
export ANTHROPIC_BASE_URL=https://api.moonshot.cn/anthropic
export ANTHROPIC_API_KEY=your_api_key
export ANTHROPIC_MODEL=kimi-k2.5

4. 无头模式

支持非交互式运行：

# 单次执行，输出 JSON
oh -p "分析这个项目的依赖关系" --output-format json

# 流式 JSON 事件
oh -p "修复这个 bug" --output-format stream-json

适用于 CI/CD 集成和自动化场景。

5. Git 安全机制

AI 的每次编辑自动创建 git commit。用户可通过 /undo 命令快速回滚。

这一设计解决了”AI 改坏了代码怎么办”的问题。

生态兼容性

Skills 兼容

OpenHarness 兼容 anthropics/skills 格式。用户只需将 .md 文件复制到 ~/.openharness/skills/ 目录即可加载。

内置技能包括：

  • commit：创建 git 提交
  • review：代码审查
  • debug：调试辅助
  • plan：实现规划
  • test：测试编写

Plugins 兼容

官方测试了 12 个 Claude Code 插件：

插件类型功能
commit-commandsCommandsGit 工作流
security-guidanceHooks安全警告
hookifyCommands + Agents自定义钩子
feature-devCommands功能开发
code-reviewAgents多 Agent PR 审查

这意味着 OpenHarness 可以直接复用 Claude Code 已有的生态积累。

适用场景

根据项目特性，OpenHarness 适合以下场景：

1. 学习 Agent 架构

对于想理解 Agent 内部机制的开发者，OpenHarness 的代码量足够小（1.1 万行），核心模块可在数日内读完。

相比 Claude Code 的 50 万行代码，OpenHarness 的学习曲线更平缓。

2. 构建定制化 Agent

OpenHarness 提供了完整的骨架。开发者只需：

  • 定义领域知识（Skills）
  • 实现专用工具
  • 配置权限规则

即可快速构建特定领域的 Agent。

3. 本地模型部署

对于有数据隐私要求或成本控制需求的场景，OpenHarness 支持 Ollama 本地运行，无需 API 密钥，无需联网。

4. 自动化流水线

无头模式和 JSON 输出使 OpenHarness 可以集成到 CI/CD 流程中，实现代码审查、测试生成、文档更新等自动化任务。

局限性

OpenHarness 的设计取舍也带来一些限制：

  1. 功能覆盖：54 个命令 vs Claude Code 的 88 个，部分高级功能缺失
  2. 边缘场景：较少的代码量意味着某些边界情况处理不完善
  3. 生态规模：作为新项目，社区规模和第三方资源有限

这些局限性反映了 OpenHarness 的设计哲学：用最小代码实现核心能力，牺牲覆盖广度换取可理解性。

技术栈

  • 语言：Python 3.11+
  • 终端 UI：React + Ink
  • 验证：Zod（JSON Schema）
  • 流式输出：异步生成器
  • 测试：114 单元测试 + 6 E2E 套件

快速开始

# 克隆项目
git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness

# 安装依赖
uv sync --extra dev

# 启动
oh

总结

OpenHarness 的价值在于”解构”而非”替代”。

它将一个 50 万行的商业化产品，拆解为可理解、可修改、可扩展的开源框架。对于想深入理解 Agent 技术的开发者，或是需要构建定制化 Agent 的团队，OpenHarness 提供了一个足够轻量的起点。

44 倍的代码差距，在功能覆盖和可理解性之间做出了明确的选择。

项目地址：https://github.com/HKUDS/OpenHarness

文档：项目 README 包含完整的架构说明和使用指南

Related Posts