港大开源 【OpenHarness】 深度剖析：1.1 万行代码解构 Agent 架构，把黑盒变白盒

港大开源 【OpenHarness】 深度剖析1.1 万行代码解构 Agent 架构把黑盒变白盒写在前面香港大学数据科学研究所HKUDS开源的 OpenHarness 项目上线两天斩获 1.9K Star10 天突破 9.5K Star——这个速度在 AI Agent 领域极为罕见。为什么因为它用1.1 万行 Python 代码实现了 Claude Code 50 万行代码的98% 核心功能而且开源、白盒、可定制。OpenHarness 的核心定位是Agent Harness——围绕 LLM 构建的完整基础设施让 LLM 从只会说话变成能做事。今天我们从概念定义、核心机制到生态定位彻底拆解 OpenHarness。 文章目录 一、什么是 Agent Harness从模型到智能体的关键一跃⚙️ 二、OpenHarness 核心机制五大子系统 三、Ohmo、多 Provider 与白盒化 Agent 的未来 一、什么是 Agent Harness从模型到智能体的关键一跃1.1 模型 ≠ 智能体很多人把 LLM 和 Agent 混为一谈——这是根本性的误解。**LLM大语言模型**是一个只会说话的系统。你给它一段文本它返回一段文本。它不能读写文件、不能执行命令、不能搜索网页、不能记住昨天做了什么。LLM 是大脑——能推理、规划、决策但没有手和记忆。**Agent智能体**是一个能做事的系统。它不仅能推理还能调用工具执行操作、维护持久化记忆、遵守安全规则、协调多个子 Agent。Agent LLM Harness。**Harness基础设施层**就是让 LLM 从只会说话变成能做事的关键一跃。OpenHarness 给出了精确定义Agent Harness 是围绕 LLM 构建的完整基础设施使 LLM 成为一个功能完备的智能体。模型提供智能Harness 提供手、记忆和安全规则。1.2 两层架构模型层 框架层OpenHarness 将 Agent 系统清晰地拆分为两个层次模型层Agent。提供推理、规划和决策能力。这一层就是 LLM 本身——Claude、GPT-4o、DeepSeek、Llama 等。模型层不关心怎么做只关心做什么和为什么做。框架层Harness。提供工具调用、权限控制、记忆存储、多 Agent 协调。这一层是 OpenHarness 的核心——它定义了 Agent “能做什么”工具、“记住什么”记忆、“不能做什么”安全规则、“怎么协作”多 Agent。这种分离的好处是显而易见的模型可以随时替换框架保持不变。你今天用 Claude明天换 DeepSeek后天换本地 Ollama——Harness 层的工具、记忆、安全策略完全复用。1.3 为什么 OpenHarness 能用 1.1 万行代码实现 98% 功能Claude Code 约 50 万行代码OpenHarness 约 1.1 万行——代码量差 45 倍但核心功能覆盖 98%。为什么原因一不做模型训练。OpenHarness 不碰模型层——它只做 Harness 层。模型训练、微调、对齐的代码量巨大但 OpenHarness 完全不需要。原因二不做 UI 渲染。Claude Code 有完整的 VS Code 扩展和 Web 界面OpenHarness 只有一个轻量 React/Ink TUI——终端界面。原因三Python 生态复用。OpenHarness 大量复用 Python 生态——文件操作用标准库、Shell 执行用 subprocess、搜索用 grep/find、Web 用 httpx。不需要从零实现。原因四精炼而非简陋。1.1 万行代码不是砍功能而是精炼设计。每个模块只做一件事做好一件事——Unix 哲学。⚙️ 二、OpenHarness 核心机制五大子系统2.1 工具系统43 个工具 54 个命令OpenHarness 内置 43 个工具、54 个命令覆盖 Agent 日常操作的绝大部分需求文件操作。读写文件、创建目录、搜索文件内容、移动/复制/删除文件。这是 Agent 最基础的能力——没有文件操作Agent 无法与代码库交互。Shell 执行。执行任意命令行命令、运行脚本、管理进程。Shell 是 Agent 的万能工具——任何没有专用工具的操作都可以通过 Shell 完成。搜索工具。grep 搜索文件内容、find 搜索文件路径、代码搜索支持正则表达式。搜索是 Agent 的眼睛——没有搜索Agent 只能盲目操作。Web 访问。HTTP 请求、网页抓取、API 调用。Web 工具让 Agent 能访问互联网——获取文档、查询 API、下载资源。MCP 协议。Model Context Protocol 集成——连接外部工具服务器。MCP 是 Agent 工具生态的USB 接口——任何 MCP 兼容的工具都可以即插即用。Skills技能文件。Markdown 格式的技能定义——把重复工作流封装成可复用能力。例如代码审查 Skill、“部署 Skill”、“测试 Skill”。2.2 安全系统三层防护Agent 的安全是生产环境的头等关切——一个没有安全约束的 Agent 可能删除重要文件、泄露敏感信息、执行危险命令。OpenHarness 提供三层安全防护第一层路径和命令白名单。基于路径和命令的访问控制——Agent 只能在允许的目录中操作只能执行允许的命令。这是硬约束——即使 Agent 想越界系统也会阻止。第二层PreToolUse / PostToolUse 钩子。工具调用前后的拦截点——在工具执行前检查参数、在工具执行后检查结果。这是软约束——可以基于上下文动态决定是否允许。第三层交互式审批。敏感操作弹出确认提示——Agent 想执行rm -rf先问用户。这是人机协作——把最终决定权交给人类。三层防护不是互斥的而是叠加的——路径白名单是基础防线钩子是动态防线交互审批是最后防线。2.3 记忆系统MEMORY.mdLLM 的上下文窗口有限——长对话中早期信息会被遗忘。OpenHarness 的记忆系统通过MEMORY.md文件实现持久化记忆自动记忆。Agent 在工作过程中自动将重要信息写入 MEMORY.md——项目结构、关键决策、已完成的任务、待办事项。跨会话持久化。MEMORY.md 存储在文件系统中不是上下文窗口中——即使关闭终端、重启 Agent记忆也不会丢失。项目级记忆。每个项目有自己的 MEMORY.md——不同项目的记忆互不干扰。Agent 进入新项目时自动读取该项目的 MEMORY.md 恢复上下文。CLAUDE.md 约定。项目根目录的 CLAUDE.md 文件定义项目约定——代码风格、架构决策、工具偏好。Agent 自动发现并遵守这些约定。2.4 多 Agent 协调复杂任务需要多个 Agent 协作——一个 Agent 写代码另一个 Agent 审查代码第三个 Agent 运行测试。OpenHarness 支持多 Agent 协调子 Agent 创建和委派。主 Agent 可以创建子 Agent将子任务委派给子 Agent 执行。子 Agent 完成后结果返回给主 Agent。团队注册和任务管理。Agent 可以注册为团队成员接受任务分配。任务管理器跟踪每个 Agent 的状态和进度。后台任务生命周期管理。长时间运行的任务可以在后台执行——Agent 不需要等待可以继续处理其他任务。2.5 插件生态hooks skills agentsOpenHarness 的插件系统是三层扩展架构第一层内置工具。43 个开箱即用的工具——文件、Shell、搜索、Web、MCP。新手直接用零配置。第二层Skills。Markdown 技能文件——把重复工作流封装成可复用能力。例如代码审查 Skill定义了审查流程、检查项、输出格式。第三层Plugins。hooks skills agents 的完整插件包——完全自定义 Agent 的行为。可以添加新工具、修改安全策略、定义新的工作流。三层扩展的设计哲学新手用内置工具就能上手高手用 Skills 封装工作流专家用 Plugins 构建生态。 三、Ohmo、多 Provider 与白盒化 Agent 的未来3.1 Ohmo内置个人 AgentOpenHarness 内置了一个名为Ohmo的个人 Agent——一条命令启动即刻可用$ oh# 启动 OhmoOhmo: Hi!Im Ohmo, your personal agent.帮我重构这个模块搜索所有 TODO 注释运行测试并修复失败的用例Ohmo 的核心特性自动发现 CLAUDE.md。进入项目目录时Ohmo 自动读取 CLAUDE.md 项目约定——代码风格、架构决策、工具偏好。不需要手动配置。持久化 MEMORY.md。Ohmo 自动维护 MEMORY.md——记录项目结构、关键决策、已完成的任务。跨会话保持上下文。React TUI 终端界面。基于 React/Ink 的终端 UI——命令选择器CtrlP、权限确认、模型切换/model、Provider 切换、会话恢复。非交互模式。oh --non-interactive适合 CI/CD 和自动化场景——不需要人工干预Agent 自主完成任务。3.2 多 Provider 工作流OpenHarness 不绑定单一模型提供商——它将 Provider 抽象为工作流 配置文件组合Claude / Anthropic 兼容。原生支持 Claude 系列模型——Claude Sonnet、Claude Opus。OpenAI 兼容。支持 GPT-4o、o3 等 OpenAI 模型。DeepSeek 兼容。支持 DeepSeek V3、R1 等模型。Ollama 本地模型。支持通过 Ollama 运行本地模型——Llama、Qwen、Mistral 等。Codex 订阅模式。支持 OpenAI Codex 订阅。GitHub Copilot 兼容。支持 Copilot 后端。国产模型。兼容 MoonshotKimi、GLM、MiniMax 等国产模型。多 Provider 的核心价值不同任务用不同模型。简单任务用便宜模型DeepSeek V3复杂推理用强模型Claude Opus本地敏感任务用 Ollama——成本和性能的最优平衡。3.3 白盒化 AgentOpenHarness 的真正价值Claude Code 是黑盒——你不知道它内部怎么决策、怎么调用工具、怎么处理错误。你只能信任它。OpenHarness 是白盒——每一行代码都可审查、每一步执行都可追踪、每一个工具都可定制。你可以验证它。这不是开源情怀而是生产必需安全审计。企业必须知道 Agent 在做什么——它访问了哪些文件执行了哪些命令发送了哪些网络请求黑盒 Agent 无法回答这些问题。定制化。不同场景需要不同的工具和安全策略——开发 Agent 需要文件和 Shell 工具研究 Agent 需要 Web 和搜索工具运维 Agent 需要监控和部署工具。黑盒 Agent 的工具集是固定的。成本控制。白盒才能优化 Token 消耗和工具调用——你可以看到每一步的 Token 用量、工具调用次数、延迟分布。黑盒 Agent 的成本是盲盒。可复现。白盒才能复现和调试 Agent 行为——同样的输入同样的工具同样的安全策略应该得到同样的输出。黑盒 Agent 的行为不可复现。3.4 四大应用场景软件开发。代码生成、重构、调试、测试。43 个工具覆盖完整开发流程。CLAUDE.md 保持项目约定。MEMORY.md 积累项目知识。研究分析。文献搜索、数据分析、报告生成。Web 工具 文件工具 搜索工具组合。MEMORY.md 积累领域知识。运维自动化。日志分析、部署脚本、监控配置。Shell 工具 安全沙箱。权限控制防止误操作。数据处理。ETL 流程、数据清洗、可视化。文件工具 Shell 工具。多 Agent 并行处理大数据集。 总结速查卡OpenHarness 核心概念概念一句话解释Agent Harness围绕 LLM 构建的完整基础设施——让 LLM 从说话到做事两层架构模型层推理/规划/决策 框架层工具/安全/记忆/协作1.1 万行代码实现 Claude Code 50 万行的 98% 核心功能——精炼而非简陋43 工具 / 54 命令文件/Shell/搜索/Web/MCP/Skills——覆盖日常操作三层安全路径白名单 PreToolUse/PostToolUse 钩子 交互式审批MEMORY.md持久化记忆——跨会话、项目级、自动维护Ohmo内置个人 Agent——一条命令启动即刻可用多 ProviderClaude/OpenAI/DeepSeek/Ollama/Codex/Copilot/国产模型一句话总结OpenHarness 是港大 HKUDS 开源的 Agent Harness——用 1.1 万行 Python 代码实现了 Claude Code 50 万行的 98% 核心功能。核心定位是模型提供智能Harness 提供能力——两层架构模型层框架层将 LLM 和基础设施解耦。五大子系统工具系统 43 工具/54 命令、安全系统三层防护、记忆系统 MEMORY.md、多 Agent 协调、插件生态三层扩展覆盖 Agent 开发的完整需求。内置 Ohmo 个人 Agent 一条命令启动兼容 Claude/OpenAI/DeepSeek/Ollama 等 6 Provider。OpenHarness 的真正价值不是开源替代而是白盒化 Agent——每一行代码可审查、每一步执行可追踪、每一个工具可定制。Agent 的未来不是更强的黑盒而是更透明的白盒。参考链接OpenHarness GitHubOpenHarness 深入浅出OpenHarness 功能介绍 (KnightLi)Agent Harness Survey (Preprints)