Marico's space

这是"每日开源项目"系列的第60期。最近在折腾 AI Agent 这块，试了几个框架下来，OpenHarness 让我觉得挺有意思的，今天把它说清楚。

之前几期聊过 OpenAI 的 Symphony（Agent 编排规范）、Addy Osmani 的 Agent Skills（工程技能集），还有 Anthropic 的金融行业 Agent 套件。这些项目传递出一个明确信号：AI Agent 正在从"聊天助手"进化成"能执行工作流的工程基础设施"。

OpenHarness 正是对标这个基础设施层的实现。它由香港大学数据科学实验室（HKUDS）用 Python 开发，提供了四个核心能力：工具调用、技能加载、记忆管理和多 Agent 协调。支持从 Claude 到 DeepSeek 再到本地运行的 Ollama，12.2k Stars 说明开发者社区对这个"轻量、可组合、模型无关"理念的认可。

• OpenHarness 的五大核心支柱（Agent Loop、Harness 工具包、上下文与记忆、治理、Swarm）
• 一条命令启动带 43+ 内置工具的 AI Agent 有多简单
• MEMORY.md 持久化记忆机制是什么，如何实现跨会话上下文恢复
• 治理层如何通过权限模式和钩子确保 Agent 安全执行
• ohmo 个人 Agent 如何通过飞书、Slack、Telegram 自动化编码任务

• 熟悉 Python 基本操作（pip install、命令行）
• 了解 AI Agent 的基本概念（知道大语言模型可以调用工具就行）
• 准备一个 Anthropic 或 OpenAI 的 API Key（或者已有订阅）

项目背景

项目介绍

OpenHarness 是一个开源 Python 框架，为 AI Agent 提供核心轻量级基础设施：工具调用、技能系统、记忆管理和多 Agent 协调。

设计哲学围绕三个关键词：

• 轻量：没有复杂的 DSL 或重型框架依赖，核心逻辑干净易懂
• 可组合：43+ 工具、技能系统、MCP 集成全部按需加载
• 模型无关：同一套代码跑在 Claude、DeepSeek、Ollama 上无需任何修改

项目还自带 ohmo，一个基于 OpenHarness 的个人 Agent。它打通了飞书、Slack、Telegram、Discord，调用你现有的 Claude Code 或 GitHub Copilot 订阅，自主完成创建分支、写代码、跑测试、开 PR 全流程。

团队介绍

• 团队：HKUDS（香港大学数据科学实验室）
• 背景：HKUDS 是港大研究团队，在推荐系统、图神经网络、大模型应用方面积累深厚手上还有多个知名的开源项目
• 项目定位：学术严谨 + 工程实用，114 个通过的单元测试和 6 套 E2E 测试做背书

项目数据

• GitHub Stars：12,200+
• Forks：2,000+
• Commits：380+
• Tests：114 个通过的单元测试 + 6 套 E2E 测试
• Built-in Tools：43+
• License：MIT
• 仓库：HKUDS/OpenHarness

核心功能

核心定位

OpenHarness 在 AI Agent 领域扮演的是"操作系统内核"的角色。它不是给终端用户用的聊天界面——它给开发者提供构建 AI Agent 所需的基础、核心的运行时能力。

可以类比 Linux 内核：你不会直接使用内核，但你在上面跑的每个应用都依赖内核来完成进程调度、文件系统访问、网络通信。OpenHarness 给 AI Agent 提供等价的能力：工具执行调度、持久化记忆、权限控制、子 Agent 协调。

典型使用场景

1. 个人开发者工作流自动化

   • 在 Telegram 上给 ohmo 发条消息，AI 自动创建 GitHub 分支、写代码、跑测试、开 PR。

2. 构建领域专属 Agent

   • 以 OpenHarness 为底座开发自己的 Agent 应用，按需加载金融分析、代码审查、文档生成的技能。

3. 多模型对比和切换

   • 同一套 Agent 代码无缝切换 Claude、GPT-4、DeepSeek、本地 Ollama 模型，对比输出质量和成本。

4. 企业级 Agent 治理

   • 在团队环境中使用权限模式和钩子，控制 Agent 对文件系统和 Shell 命令的访问。

5. 多 Agent 协作系统

   • 用 Swarm 模块启动一组子 Agent，把复杂任务分解成并行子任务执行。

快速上手

安装：

# Method 1: One-command install script
curl -fsSL https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.sh | bash # Method 2: pip install
pip install openharness-ai

初始配置：

# Interactive provider configuration (Claude / OpenAI / DeepSeek / etc.)
oh setup # Example: configure Claude
# Provider: anthropic
# API Key: sk-ant-...
# Model: claude-opus-4-6

基本用法：

# Launch interactive terminal UI
oh # Single-task execution (non-interactive)
oh -p "Analyze the Python code in the current directory and find all unhandled exceptions" # JSON output format (for pipes and script integration)
oh -p "List all TODO comments" --output-format json # Dry-run mode (preview config, execute nothing)
oh --dry-run

ohmo 个人 Agent：

# Install ohmo
pip install ohmo # Configure messaging platform (Feishu / Slack / Telegram / Discord)
ohmo setup --platform telegram # Start listening
ohmo start # Now send a message on Telegram:
# "Fix the login bug on the feature/login-fix branch and open a PR when done"
# ohmo automatically: creates branch → writes code → runs tests → opens PR

核心特性：五大支柱

1. Agent Loop（循环引擎）

OpenHarness 的心脏——处理每次与大语言模型交互的流式工具调用循环：

# Conceptual Agent Loop structure
while not done: response = llm.stream(messages, tools=available_tools) if response.has_tool_calls: # Execute multiple tool calls in parallel
 results = parallel_execute(response.tool_calls) messages.append(tool_results(results)) else: # Model delivers final response — loop ends
 done = True yield response.text

核心能力：

• 流式输出：边生成边展示结果，降低感知延迟
• 指数退避重试：API 触发限流时自动重试，用户无感知
• 并行工具执行：多个工具调用同时执行，显著提速
• Token 计数和成本追踪：实时显示 token 消耗和单次 API 调用成本

2. Harness Toolkit（工具套件）

43+ 内置工具，覆盖日常 Agent 任务的大部分场景：

类别	示例工具
文件操作	read_file, write_file, edit_file, list_dir, search_files
Shell 命令	bash_execute, python_execute, node_execute
Web	web_search, web_fetch, web_screenshot, parse_html
MCP 集成	连接任意 MCP 服务器（HTTP/SSE 传输）
按需技能	从 Markdown 技能文件动态加载专业知识

3. 上下文与记忆

OpenHarness 设计最用心的模块之一：

• CLAUDE.md 发现和注入：启动时自动扫描工作目录，找到 CLAUDE.md 文件注入为系统上下文（熟悉 Claude Code 的开发者不会陌生）
• 自动压缩：当上下文逼近模型上限时，自动压缩对话历史同时保留关键信息
• MEMORY.md 持久化记忆：Agent 在会话中学习到的重要信息会写入 MEMORY.md，下次启动时自动恢复——这是真正的跨会话记忆
• 会话恢复：上次停在哪，这次就从哪继续，无需重新解释背景

# Example MEMORY.md (auto-maintained by the agent)
## Project Memory ### User Preferences
- Python must run in the conda `dev_base` environment
- Commit messages should be in English
- Test coverage requirement: > 80% ### Known Issues
- `auth.py:142` has a known race condition — pending fix
- PostgreSQL connection pool needs max_conn adjustment under high concurrency

4. 治理层

在生产环境中，让 Agent 自由访问文件系统和执行 Shell 命令是危险的。OpenHarness 的治理模块提供了：

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

# Governance configuration example (conceptual)
governance: mode: restricted allowed_paths: read: ["./src", "./docs"] write: ["./output"] forbidden_commands: - "rm -rf" - "git push --force" hooks: pre_tool_use: - log_tool_call # Log all tool calls post_tool_use: - validate_output # Validate tool outputs require_approval: - shell_execute # Require user approval for shell execution

5. Swarm 协调

对于需要并行处理的复杂任务，单个 Agent 速度太慢。Swarm 模块支持多 Agent 协作：

# Swarm usage example (conceptual)
from openharness import Swarm, Agent swarm = Swarm() # Register a team of specialist agents
swarm.register("code_analyst", Agent(skills=["code-review"]))
swarm.register("security_auditor", Agent(skills=["security"]))
swarm.register("doc_writer", Agent(skills=["documentation"])) # Delegate tasks—execute in parallel
results = await swarm.delegate({ "code_analyst": "Analyze code quality in the src/ directory", "security_auditor": "Scan for potential security vulnerabilities", "doc_writer": "Generate an API documentation draft"
})

项目优势

特性	OpenHarness	LangChain / LlamaIndex	AutoGen
学习曲线	低（跑个 oh 就完事）	高（抽象层太多）	中等
核心代码量	轻量	数十万行	中等
模型支持	10+ 提供商（含本地模型）	多但配置复杂	以 OpenAI 为主
记忆机制	原生 MEMORY.md 持久化	需外部集成	有限
多 Agent	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) 订阅

这意味着：如果你已经有 Claude Code 或 GitHub Copilot 订阅，零额外成本直接用。

2. 43+ 工具库

OpenHarness 的内置工具赋予 AI Agent 真正"干活"的能力：

File System (~10 tools): read_file, write_file, edit_file, list_dir, search_files, create_dir, delete_file, move_file, copy_file, get_file_info Shell (~5 tools): bash_execute, python_execute, node_execute, get_env, set_env Web (~8 tools): web_search, web_fetch, web_screenshot, parse_html, download_file, check_url, get_headers Code (~8 tools): lint_code, format_code, run_tests, build_project, git_status, git_commit, git_diff, git_log MCP (~5 tools): mcp_connect, mcp_list_tools, mcp_call_tool, mcp_list_resources, mcp_read_resource Other (~7 tools): 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 ↓ ohmo 在 Telegram 回复："任务完成，PR #47 已开，等你 review。"

这个流程展示了 OpenHarness 的真正价值：它封装了"让 AI Agent 真正做事"背后那些繁琐、看起来不性感的基础设施工作，让上层应用（比如 ohmo）可以把全部精力放在业务逻辑上。

项目链接与资源

官方资源

• GitHub：
• ohmo 个人 Agent：包含在主仓库中
• 安装脚本：scripts/install.sh

目标用户

• Python 开发者：想构建自己的 AI Agent 但不想从零造基础设施轮子
• AI 应用探索者：想对比不同模型提供商的输出，找到性价比最优解
• 企业架构师：需要一个可治理、可审计的 AI Agent 运行时
• 个人效率爱好者：想实现"发个消息，AI 帮我写代码"的梦想

总结

核心要点

1. 五大支柱：Agent Loop、Harness 工具包（43+ 工具）、上下文与记忆（MEMORY.md 持久化）、治理（多级权限 + 钩子）、Swarm（多 Agent 协调）
2. 真正模型无关：10+ 提供商，还支持直接复用 Claude Code 和 GitHub Copilot 订阅
3. MEMORY.md 机制 是最独特的设计——让 Agent 拥有真正的长期记忆
4. 来自 HKUDS：学术严谨 + 工程实用（114 测试 + 6 E2E 套件）
5. ohmo 是最佳实践展示——从"基础设施框架"到"可用产品"的完整路径

一句话点评

OpenHarness 干的是 AI Agent 领域最不性感、但最重要的事：把工具调用、记忆、权限、多 Agent 协调做干净、做可靠——让构建在它上面的应用可以优雅地站在肩膀上。

原文链接：https://dev.to/...