当前位置：首页 > news >正文

一天一个开源项目（第96篇）：OpenHarness - 轻量级 AI 代理基础设施框架

news 2026/5/9 20:51:27

引言

“Agent infrastructure should be lightweight, composable, and provider-agnostic.”

这是"一天一个开源项目"系列的第96篇文章。今天带你了解的项目是OpenHarness。

过去几篇文章，我们分别看到了 OpenAI 的 Symphony（代理编排规范）、Addy Osmani 的 Agent Skills（工程纪律技能集）和 Anthropic 的 Financial Services（金融行业代理套件）。它们共同描绘了一个趋势：AI 代理正在从"聊天助手"演进为"可执行工作流的工程基础设施"。

今天的OpenHarness正是这种基础设施层的一个优秀实现——来自香港大学数据科学实验室（HKUDS），用 Python 构建，提供工具调用、技能加载、记忆管理和多代理协调四大核心能力，并且支持从 Claude 到 DeepSeek、从 OpenAI 到 Ollama 的全谱系模型提供商。12.2k Stars 的背后，是开发者社区对"轻量、可组合、提供商无关"这一设计哲学的认可。

你将学到什么

OpenHarness 的五大核心支柱（Agent Loop、Harness Toolkit、Context & Memory、Governance、Swarm）
如何用一条命令安装并启动一个具备 43+ 工具的 AI 代理
什么是 MEMORY.md 持久记忆机制，以及它如何实现跨会话的上下文恢复
Governance（治理）层如何通过权限模式和钩子保障代理的安全执行
ohmo 个人代理如何在 Feishu、Slack、Telegram 上实现自动化代码任务

前置知识

Python 基础（pip install、命令行操作）
对 AI 代理概念有基本了解（知道 LLM 可以调用工具即可）
有 Anthropic 或 OpenAI 的 API Key（或订阅）

项目背景

项目简介

OpenHarness 是一个开源 Python 框架，目标是为 AI 代理提供核心轻量级基础设施：工具调用（Tool-Use）、技能（Skills）、记忆（Memory）和多代理协调（Multi-Agent Coordination）。

它的设计哲学有三个关键词：

轻量（Lightweight）：不引入复杂的 DSL 或大型框架，核心逻辑清晰可读
可组合（Composable）：43+ 工具、技能系统、MCP 集成都可以按需加载
提供商无关（Provider-Agnostic）：同一套代码，Claude 和 DeepSeek 和 Ollama 都能跑

项目还附带一个名为ohmo的个人代理实现——基于 OpenHarness 构建，可以直接桥接飞书、Slack、Telegram、Discord，在现有的 Claude Code 或 GitHub Copilot 订阅上运行，自动化代码分支创建、测试执行和 PR 提交等工作。

作者/团队介绍

团队：HKUDS（香港大学数据科学实验室，HKU Data Science）
背景：HKUDS 是香港大学的研究团队，在推荐系统、图神经网络、大模型应用等方向有丰富的研究积累，此前也开源过多个知名项目
项目定位：学术研究背景 + 工程落地实践的结合，既有严谨的系统设计，也有 114 个通过的测试用例和 6 套 E2E 测试套件

项目数据

⭐ GitHub Stars:12,200+
🍴 Forks:2,000+
📝 Commits:380+
🧪 测试:114 个通过的单元测试 + 6 套 E2E 测试
🔧 内置工具:43+
📄 License: MIT
🌐 仓库: HKUDS/OpenHarness

主要功能

核心作用

OpenHarness 扮演的角色是 AI 代理的"操作系统内核"——它不是一个面向最终用户的聊天界面，而是为开发者提供构建 AI 代理所需的最基础、最核心的运行时能力。

把它想象成 Linux 内核：你不直接用内核，但你构建的每一个应用都依赖内核提供的进程调度、文件系统、网络栈等基础能力。OpenHarness 为 AI 代理提供的就是：工具执行调度、持久化记忆、权限管控和子代理协调。

使用场景

个人开发者自动化工作流
- 用 ohmo 在 Telegram 发一条消息，AI 自动在 GitHub 创建分支、写代码、跑测试、提 PR。
构建领域专用代理
- 基于 OpenHarness 开发自己的代理应用，按需加载金融分析、代码审查、文档生成等技能模块。
多模型对比与切换
- 同一个代理应用，无缝切换 Claude、GPT-4、DeepSeek、Ollama 本地模型，对比不同模型的输出质量和成本。
企业级代理治理
- 通过权限模式和钩子机制，在团队环境中控制代理对文件系统和 Shell 命令的访问权限。
多代理协作系统
- 使用 Swarm 模块启动子代理团队，将复杂任务分解为并行执行的子任务，提升处理速度。

快速开始

安装：

# 方法 1：一键安装脚本curl-fsSLhttps://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.sh|bash# 方法 2：pip 安装pipinstallopenharness-ai

首次配置：

# 交互式配置提供商（Claude / OpenAI / DeepSeek 等）oh setup# 示例：配置 Claude# Provider: anthropic# API Key: sk-ant-...# Model: claude-opus-4-6

基本使用：

# 启动交互式终端 UIoh# 单次任务执行（非交互式）oh-p"分析当前目录的 Python 代码，找出所有未处理的异常"# JSON 格式输出（适合管道和脚本集成）oh-p"列出所有 TODO 注释"--output-format json# 干跑模式（预览配置，不执行任何操作）oh --dry-run

ohmo 个人代理：

# 安装 ohmopipinstallohmo# 配置消息平台（Feishu / Slack / Telegram / Discord）ohmo setup--platformtelegram# 启动代理监听ohmo start# 现在在 Telegram 发消息：# "帮我在 feature/login-fix 分支修复登录 bug，改完提一个 PR"# ohmo 会自动：fork 分支 → 写代码 → 跑测试 → 开 PR

核心特性（五大支柱）

1. Agent Loop（代理循环引擎）

这是 OpenHarness 的心脏——一个流式工具调用循环，处理与 LLM 的每一轮交互：

# Agent Loop 的核心逻辑（概念示意）whilenotdone:response=llm.stream(messages,tools=available_tools)ifresponse.has_tool_calls:# 并行执行多个工具调用results=parallel_execute(response.tool_calls)messages.append(tool_results(results))else:# 模型给出最终回复，循环结束done=Trueyieldresponse.text

关键特性：

流式输出：边生成边展示，降低感知延迟
指数退避重试：API 限速时自动重试，不打扰用户
并行工具执行：多个工具调用同时执行，大幅提速
Token 计数与成本追踪：实时显示每次调用的 Token 消耗和费用

2. Harness Toolkit（工具集）

43+ 内置工具，覆盖日常代理任务的绝大多数场景：

类别	工具示例
文件操作	读文件、写文件、搜索文件、目录树
Shell 命令	执行 Bash、Python 脚本运行
Web 搜索	DuckDuckGo 搜索、网页抓取
MCP 集成	连接任意 MCP 服务器（HTTP/SSE 传输）
按需技能	从 Markdown 文件动态加载专业技能

3. Context & Memory（上下文与记忆）

这是 OpenHarness 最有工程匠心的模块之一：

CLAUDE.md 发现与注入：启动时自动扫描工作目录，找到 CLAUDE.md 文件并注入为系统上下文（如果你用过 Claude Code，这个机制会非常熟悉）
Auto-Compaction（自动压缩）：当上下文接近模型限制时，自动压缩历史消息，保留关键信息
MEMORY.md 持久记忆：代理在会话中学到的重要信息会写入 MEMORY.md，下次启动时自动恢复——实现真正的跨会话记忆
会话恢复：可以从上次中断的地方继续，不需要重新解释背景

# MEMORY.md 示例（代理自动维护） ## 项目记忆 ### 用户偏好 - Python 必须使用 conda 的 dev_base 环境运行 - 代码提交信息用英文 - 测试覆盖率要求 > 80% ### 已知问题 - `auth.py:142` 存在一个已知的 race condition，待修复 - PostgreSQL 连接池在高并发下需要调整 max_conn 参数

4. Governance（治理层）

在生产环境中，放任代理随意访问文件系统和执行命令是危险的。OpenHarness 的 Governance 模块提供：

多级权限模式：从只读模式到完全自主模式，可按场景配置
路径级命令规则：精确控制代理可以读写哪些目录、执行哪些命令
PreToolUse/PostToolUse 钩子：在工具执行前后插入自定义逻辑（日志、审计、二次确认）
交互式确认对话框：对于高风险操作（如删除文件、执行部署命令），弹出确认框请求用户批准

# 治理配置示例（概念）governance:mode:restricted# 限制模式allowed_paths:read:["./src","./docs"]write:["./output"]forbidden_commands:-"rm -rf"-"git push --force"hooks:pre_tool_use:-log_tool_call# 记录所有工具调用post_tool_use:-validate_output# 验证工具输出require_approval:-shell_execute# Shell 执行需要用户确认

5. Swarm Coordination（蜂群协调）

对于需要并行处理的复杂任务，单个代理太慢，Swarm 模块提供多代理协作能力：

# Swarm 使用示例（概念）fromopenharnessimportSwarm,Agent swarm=Swarm()# 注册专家代理团队swarm.register("code_analyst",Agent(skills=["code-review"]))swarm.register("security_auditor",Agent(skills=["security"]))swarm.register("doc_writer",Agent(skills=["documentation"]))# 委派任务，并行执行results=awaitswarm.delegate({"code_analyst":"分析 src/ 目录的代码质量","security_auditor":"扫描潜在安全漏洞","doc_writer":"生成 API 文档草稿"})

项目优势

对比项	OpenHarness	LangChain / LlamaIndex	AutoGen
学习曲线	低（直接用`oh`命令）	高（大量抽象层）	中
核心代码量	轻量级	数十万行	中等
提供商支持	10+ 提供商（含本地模型）	多，但配置复杂	主要 OpenAI
记忆机制	原生 MEMORY.md 持久记忆	需要额外集成	有限
多代理	Swarm 原生支持	通过 Agent 框架	核心特性
治理/权限	内置多级权限 + 钩子	无内置	有限
MCP 支持	原生（HTTP/SSE 传输）	插件形式	无

项目详细剖析

1. 多提供商支持：真正的"提供商无关"

OpenHarness 支持的模型提供商分为三类：

Anthropic 兼容层（使用 Anthropic SDK）：

oh setup# Provider: anthropic → 支持 Claude 系列# Provider: moonshot → 支持 Kimi# Provider: glm → 支持 智谱 GLM# Provider: minimax → 支持 MiniMax

OpenAI 兼容层（使用 OpenAI SDK）：

# Provider: openai → GPT-4, GPT-4o# Provider: openrouter → 聚合多家模型# Provider: dashscope → 阿里云通义千问# Provider: deepseek → DeepSeek 系列# Provider: groq → Llama 等超快推理# Provider: ollama → 本地开源模型# Provider: github → GitHub Models

订阅桥接（无需 API Key，复用现有订阅）：

# Provider: claude-code → 复用 Claude Code 订阅# Provider: codex → 复用 GitHub Copilot (Codex CLI)

这意味着你不需要额外的 API 费用——如果你已经订阅了 Claude Code 或 GitHub Copilot，直接复用即可。

2. 43 工具深度解析

OpenHarness 内置 43+ 工具，让 AI 代理能够真正"动手做事"：

文件系统类（~10个）: read_file, write_file, edit_file, list_dir, search_files, create_dir, delete_file, move_file, copy_file, get_file_info Shell 类（~5个）: bash_execute, python_execute, node_execute, get_env, set_env Web 类（~8个）: web_search, web_fetch, web_screenshot, parse_html, download_file, check_url, get_headers 代码类（~8个）: lint_code, format_code, run_tests, build_project, git_status, git_commit, git_diff, git_log MCP 类（~5个）: mcp_connect, mcp_list_tools, mcp_call_tool, mcp_list_resources, mcp_read_resource 其他（~7个）: token_count, cost_estimate, task_spawn, memory_read, memory_write, skill_load, context_compress

3. ohmo：从框架到产品的一步

如果说 OpenHarness 是"引擎"，那么 ohmo 就是基于这个引擎的"第一辆量产车"：

用户在 Telegram 发消息 ↓ ohmo 接收消息 ↓ OpenHarness Agent Loop ↓ 调用工具（git、bash、文件操作等） ↓ 自动创建分支 → 写代码 → 跑测试 → 提 PR ↓ 在 Telegram 回复任务完成通知

这个流程展示了 OpenHarness 的真正价值：它把繁琐的"让 AI 代理真正能动手"的基础设施问题都封装好了，让上层应用（如 ohmo）可以专注于业务逻辑。

项目地址与资源

官方资源

🌟GitHub: https://github.com/HKUDS/OpenHarness
🤖ohmo 个人代理: 包含在主仓库中
🛠️安装脚本: scripts/install.sh

适用人群

Python 开发者：想构建自己的 AI 代理但不想从零搭建基础设施
AI 应用探索者：想在不同模型提供商之间对比效果，寻找性价比最高的选择
企业架构师：需要一套可治理、可审计的 AI 代理运行时
个人效率极客：用 ohmo 实现"发一条消息，AI 自动完成代码任务"的梦想

总结与展望

核心要点回顾

五大支柱：Agent Loop、Harness Toolkit（43+ 工具）、Context & Memory（MEMORY.md 持久记忆）、Governance（多级权限 + 钩子）、Swarm（多代理协调）
真正的提供商无关：10+ 提供商，包括直接复用 Claude Code 和 GitHub Copilot 订阅
MEMORY.md 机制是最有特色的设计，让代理真正具备"长期记忆"
来自香港大学 HKUDS 团队，学术严谨性与工程实用性兼备（114 测试 + 6 E2E 套件）
ohmo是 OpenHarness 的最佳实践展示，从"基础设施框架"到"可用产品"的完整路径