OpenHarness

OpenHarness 是由 香港大学 (HKU) 最新开源的一款极致轻量级 AI 智能体框架。它仅用 1.1 万行 Python 代码，就实现了与拥有 50 万行代码的 Claude Code 相媲美的核心能力，体积缩小了 44 倍。

OpenHarness 剥离了企业级的遥测、复杂的 OAuth 流程和重型 React UI，只保留了让大模型变成“智能体”所必需的核心基础设施：工具使用、技能系统、记忆机制、多智能体协调与安全治理。它将智能体从“黑盒”变为“白盒”，让开发者能看懂、能修改、能基于此构建自己的专属 Agent。

核心优势：为何选择 OpenHarness？

💡 核心理念：模型负责思考，Harness 负责执行

OpenHarness 定义了一个清晰的边界：

• LLM (大脑)：负责推理、规划、决策。
• Harness (身体)：提供手（工具）、眼（感知）、记忆（上下文）和安全边界（权限）。
  这种解耦设计让开发者可以随意更换后端模型（Claude, Kimi, Vertex, Bedrock 等），而无需重写业务逻辑。

核心功能全景

OpenHarness 在极简的代码中集成了生产级智能体所需的十大子系统：

1. 智能体循环 (Agent Loop)

• 流式执行：支持实时流式输出，响应迅速。
• 自愈机制：内置指数退避重试策略，应对 API 波动。
• 并行处理：支持并行工具调用，大幅提升复杂任务效率。
• 成本追踪：实时监控 Token 消耗与费用。

2. 强大的工具包 (43+ Tools)

涵盖开发全流程，所有工具均具备 Pydantic 类型验证 和 权限检查：

• 文件操作：Read, Write, Edit, Bash, Glob, Grep.
• 网络搜索：WebFetch, WebSearch, ToolSearch.
• 代码辅助：LSP 集成，NotebookEdit.
• 智能体协作：Agent (子智能体), TeamCreate, SendMessage.
• 任务调度：Task 管理，Cron 定时任务.
• 协议支持：完整的 MCP (Model Context Protocol) 客户端。

3. 技能系统 (Skills)

• 按需加载：技能以 .md 文件形式存在，仅在需要时注入上下文，节省 Token。
• 完全兼容：直接复用 anthropics/skills 生态（如 commit, review, debug, pdf, xlsx 等 40+ 技能）。
• 自定义简单：只需在 ~/.openharness/skills/ 下添加 Markdown 文件即可。

4. 插件生态 (Plugins)

• 无缝迁移：完美兼容 claude-code/plugins 格式。
• 丰富扩展：已测试支持 commit-commands, security-guidance, code-review 等 12+ 官方插件。
• 生命周期钩子：支持 PreToolUse/PostToolUse 钩子，拦截并修改工具行为。

5. 多级安全治理

• 权限模式：
  • Default: 写/执行前询问。
  • Auto: 全自动（适合沙箱）。
  • Plan Mode: 禁止所有写入，仅做规划。
• 细粒度规则：支持路径黑名单（如 /etc/*）和命令黑名单（如 rm -rf）。
• 交互式审批：TUI 界面提供清晰的工具详情供用户确认。

6. 多智能体协调

• 子智能体生成：主智能体可动态创建子智能体处理特定子任务。
• 团队管理：内置团队注册表与任务分发机制。
• 后台任务：支持长时间运行的后台任务，主会话可分离。

快速开始

环境准备

• Python 3.10+
• uv (推荐包管理器)
• 大模型 API Key (Anthropic, Moonshot/Kimi 等)

一键运行

# 克隆项目
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

# 启动智能体
uv run oh

非交互模式 (CLI & 脚本)

OpenHarness 非常适合集成到自动化流程中：

# 单次提问，输出文本
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

架构揭秘：如何扩展？

OpenHarness 的代码结构极其清晰，扩展性极强：

1. 添加自定义工具

只需继承 BaseTool 并实现 execute 方法：

class MyTool(BaseTool):
    name = "my_tool"
    description = "Do something useful"
    
    async def execute(self, arguments, context):
        return ToolResult(output=f"Result: {arguments.query}")

2. 添加自定义技能

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

---
name: my-skill
description: Expert guidance for my domain
---
# Workflow
1. Step one...
2. Step two...

3. 开发插件

遵循 claude-code 插件规范，在 .openharness/plugins/ 目录下定义 plugin.json、命令和钩子即可。

适用场景

1. 🔬 AI 研究与教学：代码量少，逻辑透明，是理解生产级 Agent 架构的最佳教材。
2. 🏗️ 定制化 Agent 开发：基于成熟的 Harness 架构，快速构建垂直领域的专用智能体（如法律、医疗、金融）。
3. 🧪 插件/技能实验场：在不污染主开发环境的情况下，测试新的 Skills 和 Plugins。
4. 🤖 多智能体原型：利用内置的协调原语，快速验证 Swarm/Team 工作流。
5. 🔄 模型对比沙箱：轻松切换不同提供商（Anthropic, Kimi, Vertex），评估同一任务在不同模型下的表现。