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

一天一个开源项目(第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 或大型框架核心逻辑清晰可读可组合Composable43 工具、技能系统、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# 方法 2pip 安装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-runohmo 个人代理# 安装 ohmopipinstallohmo# 配置消息平台Feishu / Slack / Telegram / Discordohmo setup--platformtelegram# 启动代理监听ohmo start# 现在在 Telegram 发消息# 帮我在 feature/login-fix 分支修复登录 bug改完提一个 PR# ohmo 会自动fork 分支 → 写代码 → 跑测试 → 开 PR核心特性五大支柱1. Agent Loop代理循环引擎这是 OpenHarness 的心脏——一个流式工具调用循环处理与 LLM 的每一轮交互# Agent Loop 的核心逻辑概念示意whilenotdone:responsellm.stream(messages,toolsavailable_tools)ifresponse.has_tool_calls:# 并行执行多个工具调用resultsparallel_execute(response.tool_calls)messages.append(tool_results(results))else:# 模型给出最终回复循环结束doneTrueyieldresponse.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 --forcehooks:pre_tool_use:-log_tool_call# 记录所有工具调用post_tool_use:-validate_output# 验证工具输出require_approval:-shell_execute# Shell 执行需要用户确认5. Swarm Coordination蜂群协调对于需要并行处理的复杂任务单个代理太慢Swarm 模块提供多代理协作能力# Swarm 使用示例概念fromopenharnessimportSwarm,Agent swarmSwarm()# 注册专家代理团队swarm.register(code_analyst,Agent(skills[code-review]))swarm.register(security_auditor,Agent(skills[security]))swarm.register(doc_writer,Agent(skills[documentation]))# 委派任务并行执行resultsawaitswarm.delegate({code_analyst:分析 src/ 目录的代码质量,security_auditor:扫描潜在安全漏洞,doc_writer:生成 API 文档草稿})项目优势对比项OpenHarnessLangChain / LlamaIndexAutoGen学习曲线低直接用oh命令高大量抽象层中核心代码量轻量级数十万行中等提供商支持10 提供商含本地模型多但配置复杂主要 OpenAI记忆机制原生 MEMORY.md 持久记忆需要额外集成有限多代理Swarm 原生支持通过 Agent 框架核心特性治理/权限内置多级权限 钩子无内置有限MCP 支持原生HTTP/SSE 传输插件形式无项目详细剖析1. 多提供商支持真正的提供商无关OpenHarness 支持的模型提供商分为三类Anthropic 兼容层使用 Anthropic SDKoh setup# Provider: anthropic → 支持 Claude 系列# Provider: moonshot → 支持 Kimi# Provider: glm → 支持 智谱 GLM# Provider: minimax → 支持 MiniMaxOpenAI 兼容层使用 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_compress3. ohmo从框架到产品的一步如果说 OpenHarness 是引擎那么 ohmo 就是基于这个引擎的第一辆量产车用户在 Telegram 发消息 ↓ ohmo 接收消息 ↓ OpenHarness Agent Loop ↓ 调用工具git、bash、文件操作等 ↓ 自动创建分支 → 写代码 → 跑测试 → 提 PR ↓ 在 Telegram 回复任务完成通知这个流程展示了 OpenHarness 的真正价值它把繁琐的让 AI 代理真正能动手的基础设施问题都封装好了让上层应用如 ohmo可以专注于业务逻辑。项目地址与资源官方资源GitHub: https://github.com/HKUDS/OpenHarnessohmo 个人代理: 包含在主仓库中️安装脚本: scripts/install.sh适用人群Python 开发者想构建自己的 AI 代理但不想从零搭建基础设施AI 应用探索者想在不同模型提供商之间对比效果寻找性价比最高的选择企业架构师需要一套可治理、可审计的 AI 代理运行时个人效率极客用 ohmo 实现发一条消息AI 自动完成代码任务的梦想总结与展望核心要点回顾五大支柱Agent Loop、Harness Toolkit43 工具、Context MemoryMEMORY.md 持久记忆、Governance多级权限 钩子、Swarm多代理协调真正的提供商无关10 提供商包括直接复用 Claude Code 和 GitHub Copilot 订阅MEMORY.md 机制是最有特色的设计让代理真正具备长期记忆来自香港大学 HKUDS 团队学术严谨性与工程实用性兼备114 测试 6 E2E 套件ohmo是 OpenHarness 的最佳实践展示从基础设施框架到可用产品的完整路径一句话评价OpenHarness 做了 AI 代理领域最不性感但最重要的事把工具调用、记忆、权限和多代理协调这些脏活累活做得干净可靠让上层应用得以优雅地站在它的肩膀上。欢迎来我的个人主页找到更多有用的知识和有趣的产品