当前位置：首页 » AI开源项目

港大开源 OpenHarness：1.1 万行代码实现 Claude Code 核心架构，Agent 从黑盒变白盒

2小时前 AI开源项目 9 0

项目概述

香港大学数据科学研究所（HKUDS）近期开源了一个新项目 OpenHarness，短短两天就获得了 1.9K Star。这个团队之前已经有不少知名项目，包括 LightRAG、AutoAgent、Nanobot 和 CLI-Anything。

OpenHarness 的定位非常独特：它不是一个新的 Agent，而是一个"Agent Harness"——给模型穿上的"马甲"。模型负责思考，Harness 提供手、眼、记忆和安全边界。

什么是 Agent Harness？

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

这个理念把 Agent 系统清晰地拆分为两个层次：

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

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

苏米注：这个设计思路非常清晰，把模型和框架的职责边界划分得很明确，便于开发者理解和扩展。

为什么需要 OpenHarness？

看看这组数据对比：

Claude Code：Anthropic 官方代码助手，51 万行代码、1884 个文件
OpenHarness：1.1 万行 Python 代码，重新实现核心架构

Claude Code 功能强大，但庞大的代码库让想学习 Agent 架构的开发者望而却步。OpenHarness 砍掉了遥测、OAuth、重型 React UI 等企业级功能，只保留最核心的 Harness 架构，让开发者能够真正理解 Agent 内部是如何工作的。

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 个官方插件：

插件	类型	功能
commit-commands	Commands	Git 工作流
security-guidance	Hooks	文件编辑安全警告
hookify	Commands + Agents	创建自定义行为钩子
feature-dev	Commands	功能开发工作流
code-review	Agents	多 Agent PR 审查
pr-review-toolkit	Agents	专业 PR 审查 Agent

5. Permissions（权限管控）

三级权限模式：

模式	行为	适用场景
Default	写入/执行前询问	日常开发
Auto	全部允许	沙箱环境
Plan	阻止所有写入	代码审查

还支持路径级规则配置：

{
  "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 

# 启用插件
oh plugin enable

扩展 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 从黑盒变成了白盒，用 1.1 万行代码重新实现了 Claude Code 的核心架构。对于想学习 Agent 开发或构建自己 Agent 的开发者来说，这是一个非常宝贵的学习资源。代码不长，但信息量很大，值得深入研读。

项目地址：https://github.com/HKUDS/OpenHarness

声明：本站原创文章文字版权归本站所有，转载务必注明作者和出处；本站转载文章仅仅代表原作者观点，不代表本站立场，图文版权归原作者所有。如有侵权，请联系我们删除。

未经允许不得转载：港大开源 OpenHarness：1.1 万行代码实现 Claude Code 核心架构，Agent 从黑盒变白盒

请登录后发表评论