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

引言

"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 模块启动子代理团队，将复杂任务分解为并行执行的子任务，提升处理速度。

快速开始

安装：

bash 复制代码

# 方法 1：一键安装脚本
curl -fsSL https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.sh | bash

# 方法 2：pip 安装
pip install openharness-ai

首次配置：

bash 复制代码

# 交互式配置提供商（Claude / OpenAI / DeepSeek 等）
oh setup

# 示例：配置 Claude
# Provider: anthropic
# API Key: sk-ant-...
# Model: claude-opus-4-6

基本使用：

bash 复制代码

# 启动交互式终端 UI
oh

# 单次任务执行（非交互式）
oh -p "分析当前目录的 Python 代码，找出所有未处理的异常"

# JSON 格式输出（适合管道和脚本集成）
oh -p "列出所有 TODO 注释" --output-format json

# 干跑模式（预览配置，不执行任何操作）
oh --dry-run

ohmo 个人代理：

bash 复制代码

# 安装 ohmo
pip install ohmo

# 配置消息平台（Feishu / Slack / Telegram / Discord）
ohmo setup --platform telegram

# 启动代理监听
ohmo start

# 现在在 Telegram 发消息：
# "帮我在 feature/login-fix 分支修复登录 bug，改完提一个 PR"
# ohmo 会自动：fork 分支 → 写代码 → 跑测试 → 开 PR

核心特性（五大支柱）

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

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

python 复制代码

# Agent Loop 的核心逻辑（概念示意）
while not done:
    response = llm.stream(messages, tools=available_tools)
    
    if response.has_tool_calls:
        # 并行执行多个工具调用
        results = parallel_execute(response.tool_calls)
        messages.append(tool_results(results))
    else:
        # 模型给出最终回复，循环结束
        done = True
        yield response.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，下次启动时自动恢复------实现真正的跨会话记忆
会话恢复：可以从上次中断的地方继续，不需要重新解释背景

shell 复制代码

# MEMORY.md 示例（代理自动维护）
## 项目记忆

### 用户偏好
- Python 必须使用 conda 的 dev_base 环境运行
- 代码提交信息用英文
- 测试覆盖率要求 > 80%

### 已知问题
- `auth.py:142` 存在一个已知的 race condition，待修复
- PostgreSQL 连接池在高并发下需要调整 max_conn 参数

4. Governance（治理层）

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

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

yaml 复制代码

# 治理配置示例（概念）
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 模块提供多代理协作能力：

python 复制代码

# Swarm 使用示例（概念）
from openharness import Swarm, 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 = await swarm.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）：

bash 复制代码

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

OpenAI 兼容层（使用 OpenAI SDK）：

bash 复制代码

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

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

bash 复制代码

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

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

2. 43 工具深度解析

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

makefile 复制代码

文件系统类（~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 就是基于这个引擎的"第一辆量产车"：

markdown 复制代码

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

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

项目地址与资源

官方资源

🌟 GitHub : github.com/HKUDS/OpenH...
🤖 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 的最佳实践展示，从"基础设施框架"到"可用产品"的完整路径

一句话评价

OpenHarness 做了 AI 代理领域最不性感但最重要的事：把工具调用、记忆、权限和多代理协调这些"脏活累活"做得干净可靠，让上层应用得以优雅地站在它的肩膀上。

欢迎来我的个人主页找到更多有用的知识和有趣的产品