OpenHarness 深度解析：HKUDS 如何用 1 万行 Python 复刻 Claude Code

项目概述

OpenHarness 是香港大学数据智能实验室（HKUDS）推出的开源 Agent Harness 框架，用极简的 Python 代码实现了 Claude Code 的核心功能。

核心突破：44 倍轻量化

这是 OpenHarness 最引人注目的数字：

2.3% 的代码量，98% 的核心工具 —— 剥离了企业级开销（遥测、OAuth 复杂度、数百个 React 组件），专注于 Harness 架构本质。

什么是 Agent Harness？

OpenHarness 给出了清晰的定义：

Agent Harness = 包裹 LLM 的完整基础设施，让 LLM 成为功能性 Agent。

模型提供智能；Harness 提供 手（工具）、眼（观察）、记忆和安全边界。

┌─────────────────────────────────────────────────────────────┐
│                    Agent Harness 公式                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   Harness = Tools + Knowledge + Observation + Action        │
│             + Permissions                                   │
│                                                              │
│   • Tools: 43+ 工具（文件、Shell、搜索、Web、MCP）           │
│   • Knowledge: Skills 系统（.md 按需加载）                   │
│   • Observation: 上下文注入、CLAUDE.md 发现                  │
│   • Action: Agent Loop 执行工具调用                          │
│   • Permissions: 多级权限、路径规则、命令拦截                │
│                                                              │
└─────────────────────────────────────────────────────────────┘

10 子系统架构

openharness/
├── engine/          # 🧠 Agent Loop — query → stream → tool-call → loop
├── tools/           # 🔧 43 Tools — file I/O, shell, search, web, MCP
├── skills/          # 📚 Knowledge — on-demand skill loading (.md files)
├── plugins/         # 🔌 Extensions — commands, hooks, agents, MCP servers
├── permissions/     # 🛡️ Safety — multi-level modes, path rules, command deny
├── hooks/           # ⚡ Lifecycle — PreToolUse/PostToolUse event hooks
├── commands/        # 💬 54 Commands — /help, /commit, /plan, /resume, ...
├── mcp/             # 🌐 MCP — Model Context Protocol client
├── memory/          # 🧠 Memory — persistent cross-session knowledge
├── tasks/           # 📋 Tasks — background task management
├── coordinator/     # 🤝 Multi-Agent — subagent spawning, team coordination
├── prompts/         # 📝 Context — system prompt assembly, CLAUDE.md, skills
├── config/          # ⚙️ Settings — multi-layer config, migrations
└── ui/              # 🖥️ React TUI — backend protocol + frontend

五大核心特性

1. 🔄 Agent Loop（引擎）

Agent 的心脏，一个无限可组合的循环：

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

关键能力：

• Streaming Tool-Call Cycle（流式工具调用）
• API Retry with Exponential Backoff（指数退避重试）
• Parallel Tool Execution（并行工具执行）
• Token Counting & Cost Tracking（Token 计数和成本追踪）

2. 🔧 Harness Toolkit（43+ 工具）

每个工具具备：

• Pydantic input validation（结构化、类型安全输入）
• Self-describing JSON Schema（模型自动理解工具）
• Permission integration（每次执行前权限检查）
• Hook support（PreToolUse/PostToolUse 生命周期钩子）

3. 🧠 Context & Memory（上下文与记忆）

4. 🛡️ Governance（治理）

路径级规则（settings.json）：

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

生命周期钩子：

• PreToolUse：工具执行前拦截
• PostToolUse：工具执行后处理

5. 🤝 Swarm Coordination（群体协调）

多模型支持

Anthropic 格式（默认）

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

OpenAI 格式（--api-format openai）

生态系统兼容

1. 与 anthropics/skills 兼容

Skills 是按需加载的知识 —— 仅在模型需要时加载：

Available Skills:
- commit: 创建清晰、结构良好的 git 提交
- review: 审查代码缺陷、安全问题和质量
- debug: 系统性地诊断和修复 bug
- plan: 编码前设计实现计划
- test: 为代码编写和运行测试
- simplify: 重构代码使其更简单可维护
- pdf: PDF 处理（来自 anthropics/skills）
- xlsx: Excel 操作（来自 anthropics/skills）
... 40+ more

兼容方式：直接将 .md 文件复制到 ~/.openharness/skills/

2. 与 claude-code/plugins 兼容

已测试 12 个官方插件：

使用场景

与 HKUDS 其他项目的关联

核心启示

1. 最小可行 Harness

OpenHarness 证明了：生产级 Agent 功能不需要 50 万行代码。剥离企业级开销后，核心 Harness 可以用 1 万行 Python 实现。

2. 兼容性优先

通过与 anthropics/skills 和 claude-code/plugins 兼容，OpenHarness 直接继承了 Claude Code 的生态资产。

3. 多模型是趋势

原生支持 Anthropic、OpenAI、Kimi、DeepSeek、DashScope、Ollama 等多种后端，体现了模型无关的设计理念。

4. HKUDS 的 Agent 版图

从 LightRAG → OpenSpace → CLI-Anything → OpenHarness，HKUDS 正在构建一个完整的 Agent 基础设施生态。

参考链接

• GitHub: https://github.com/HKUDS/OpenHarness
• HKUDS 主页: https://github.com/HKUDS

#OpenHarness #HKUDS #AgentHarness #ClaudeCode #开源Agent