港大新开源 OpenHarness，两天斩获 1.9K Star！它把 Agent 从黑盒变成了白盒！

这两天，GitHub 上突然出现了一个新项目，短短两天就斩获了 1.9K Star。

点进去一看，是香港大学数据科学研究所（HKUDS）新开源的 AI 项目：OpenHarness。

这个团队之前已经有不少知名项目了，比如 LightRAG、AutoAgent、还有上个月刚火的Nanobot、CLI-Anything，可以说是开源界的"明星团队"。

这次的 OpenHarness，定位非常有意思：它不是一个新的Agent，而是一个"Agent Harness"——也就是给模型穿上的"马甲"。

模型负责思考，Harness给模型提供手、眼、记忆和安全边界。这个理念，一下子把 Agent 的架构说透了。

什么是Agent Harness？

OpenHarness 的核心理念可以用一句话概括：The model is the agent. The code is the harness.

这句话把 Agent 系统清晰地拆成了两个层次：

• • 模型层（Agent）：提供推理、规划、决策能力
• • 框架层（Harness）：提供工具调用、权限控制、记忆存储、多Agent协调

一个纯聊天模型只能输出文本。当模型接入Harness后，它获得了文件读写、命令执行、网络请求、持久记忆等能力——从"会说"变成"能做"。

OpenHarness实现的就是这个Harness层。

为什么要做OpenHarness？

先看一组数据对比，你就明白这个项目的意义了：

Claude Code 是 Anthropic 官方的代码助手，功能非常强大，但 51 万行代码、1884 个文件，对于想学习Agent架构的开发者来说，简直是天书。

很多人想研究 Agent 内部是怎么工作的，但看到这么大的代码库，直接就放弃了。

OpenHarness 做的事情就是：用 1.1 万行 Python 代码，重新实现 Claude Code 的核心架构。砍掉了遥测、OAuth、重型React UI这些企业级功能，只保留最核心的Harness架构。

10大核心子系统

OpenHarness的架构由10个核心子系统组成，每个都有明确的职责：

1、Engine（智能体循环）

这是整个框架的心脏。一个简洁的循环，却能处理无限的组合：

while True:
    response = await api.stream(messages, tools)
    
    if response.stop_reason != "tool_use":
        break  # 模型完成任务
    
    for tool_call in response.tool_uses:
        # 权限检查 → 钩子 → 执行 → 钩子 → 结果
        result = await harness.execute_tool(tool_call)
    
    messages.append(tool_results)
    # 循环继续，模型根据结果决定下一步

模型决定"做什么"，Harness负责"怎么做"——包括权限校验、执行、结果格式化。

2、Tools（43个工具）

涵盖文件I/O、Shell、搜索、Web、MCP协议等：

• • 文件操作：Read、Write、Edit、Glob、Grep
• • Shell执行：Bash命令，带权限控制
• • 搜索：WebFetch、WebSearch、ToolSearch
• • Agent协作：Agent、SendMessage、TeamCreate
• • 任务管理：TaskCreate/Get/Update/Stop/Output
• • MCP协议：MCPTool、ListMcpResources

每个工具都自带Pydantic输入验证、JSON Schema自描述、权限集成、钩子支持。

3、Skills（按需加载的技能）

Skills是按需加载的领域知识，只用.md文件就能定义。

OpenHarness兼容anthropics/skills格式，你只需把.md文件复制到~/.openharness/skills/目录即可。

内置技能包括：

• • commit：创建清晰的git提交
• • review：代码审查
• • debug：系统地诊断和修复bug
• • plan：编码前设计实现方案
• • test：编写和运行测试
• • simplify：重构代码使其更简洁可维护

4、Plugins（插件系统）

OpenHarness 兼容 claude-code 插件生态。官方测试了12个官方插件：

这意味着OpenHarness可以直接复用Claude Code已有的生态积累。

5、Permissions（权限管控）

三级权限模式，给你充分的安全感：

还支持路径级规则配置：

{
  "permission": {
    "mode": "default",
    "path_rules": [{"pattern": "/etc/*", "allow": false}],
    "denied_commands": ["rm -rf /", "DROP TABLE"]
  }
}

6、Hooks（生命周期钩子）

支持PreToolUse/PostToolUse生命周期钩子，让你可以在工具执行前后插入自定义逻辑。

7、Commands（54个斜杠命令）

像聊天一样控制Agent，支持/help、/commit、/plan、/resume等常用命令。

8、MCP（Model Context Protocol）

支持Model Context Protocol客户端，可以接入外部MCP服务器。

9、Memory（持久记忆）

用MEMORY.md存储跨会话的持久知识，支持会话恢复和历史记录。

10、Coordinator（多Agent协调）

支持子Agent派发、团队管理、任务调度，ClawTeam集成也在路线图中。

快速上手

安装

# 克隆项目
git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness

# 安装依赖（包含开发工具）
uv sync --extra dev

配置模型

以Kimi为例：

export ANTHROPIC_BASE_URL=https://api.moonshot.cn/anthropic
export ANTHROPIC_API_KEY=your_kimi_api_key
export ANTHROPIC_MODEL=kimi-k2.5

一键启动

# 如果激活了虚拟环境
oh

# 或者直接用uv运行
uv run oh

非交互式模式（脚本和管道）

# 单次提示 → 标准输出
oh -p "Explain this codebase"

# JSON输出，用于编程使用
oh -p "List all functions in main.py" --output-format json

# 实时流式JSON事件
oh -p "Fix the bug" --output-format stream-json

插件管理

# 列出插件
oh plugin list

# 安装插件
oh plugin install <source>

# 启用插件
oh plugin enable <name>

扩展OpenHarness

添加自定义工具

from pydantic import BaseModel, Field
from openharness.tools.base import BaseTool, ToolExecutionContext, ToolResult

class MyToolInput(BaseModel):
    query: str = Field(description="Search query")

class MyTool(BaseTool):
    name = "my_tool"
    description = "Does something useful"
    input_model = MyToolInput

    async def execute(self, arguments: MyToolInput, context: ToolExecutionContext) -> ToolResult:
        return ToolResult(output=f"Result for: {arguments.query}")

添加自定义技能

创建~/.openharness/skills/my-skill.md：

---
name: my-skill
description: Expert guidance for my specific domain
---

# My Skill

## When to use
Use when the user asks about [your domain].

## Workflow
1. Step one
2. Step two
...

添加自定义插件

创建.openharness/plugins/my-plugin/.claude-plugin/plugin.json：

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom plugin"
}

在commands/*.md中添加命令，在hooks/hooks.json中添加钩子，在agents/*.md中添加Agent。

写在最后

OpenHarness 的出现，让我想起了Linux刚诞生时的那句话："Just for fun"。

它不是要取代Claude Code，而是给开发者一个可理解、可修改、可扩展的Agent框架参考。

在AI Agent这个领域，我们需要的不只是好用的产品，更需要清晰的架构、可学习的代码、开放的生态。

OpenHarness正是朝着这个方向迈出的重要一步。

模型是Agent，代码是Harness。OpenHarness把Agent从黑盒变成了白盒——现在，你终于可以看清Agent内部是怎么工作的了。

如果你对AI Agent架构感兴趣，或者想构建自己的Agent，不妨去看看这个项目。代码不长，但信息量很大。

GitHub：https://github.com/HKUDS/OpenHarness

如果本文对您有帮助，也请帮忙点个 赞👍 + 在看 哈！❤️

在看你就赞赞我！