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

项目概述

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

属性	内容
开发方	HKUDS（香港大学数据智能实验室）
发布时间	2026-04-01（v0.1.0）
GitHub Stars	2.4k+（截至 2026-04）
许可证	MIT
技术栈	Python 3.10+，uv，React/Ink（TUI）
核心口号	"The model is the agent. The code is the harness."

---

核心突破：44 倍轻量化

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

指标	Claude Code	OpenHarness	对比
代码行数	512,664	11,733	44× 更轻
文件数	1,884	163	11× 更少
开发语言	TypeScript/Bun	Python	更简洁
工具数量	~44	43	98% 覆盖
命令数量	~88	54	61% 覆盖
技能兼容	anthropics/skills	✅ 兼容	互通
插件兼容	claude-code/plugins	✅ 兼容	互通

> 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+ 工具）

类别	工具	说明
File I/O	Bash, Read, Write, Edit, Glob, Grep	核心文件操作
Search	WebFetch, WebSearch, ToolSearch, LSP	Web 和代码搜索
Notebook	NotebookEdit	Jupyter notebook 编辑
Agent	Agent, SendMessage, TeamCreate/Delete	子 Agent 和协调
Task	TaskCreate/Get/List/Update/Stop/Output	后台任务管理
MCP	MCPTool, ListMcpResources, ReadMcpResource	Model Context Protocol
Mode	EnterPlanMode, ExitPlanMode, Worktree	工作流模式切换
Schedule	CronCreate/List/Delete, RemoteTrigger	定时和远程执行
Meta	Skill, Config, Brief, Sleep, AskUser	知识加载、配置、交互

每个工具具备：

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

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

功能	说明
CLAUDE.md Discovery & Injection	自动发现和注入 CLAUDE.md
Context Compression (Auto-Compact)	自动压缩上下文
MEMORY.md Persistent Memory	持久化跨会话记忆
Session Resume & History	会话恢复和历史

4. 🛡️ Governance（治理）

模式	行为	使用场景
Default	写入/执行前询问	日常开发
Auto	允许所有操作	沙箱环境
Plan Mode	阻止所有写入	大规模重构、先审查

路径级规则（settings.json）：

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

生命周期钩子：

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

5. 🤝 Swarm Coordination（群体协调）

功能	说明
Subagent Spawning & Delegation	子 Agent 生成和委托
Team Registry & Task Management	团队注册和任务管理
Background Task Lifecycle	后台任务生命周期
ClawTeam Integration (Roadmap)	ClawTeam 集成（路线图）

---

多模型支持

Anthropic 格式（默认）

Provider	检测信号
Anthropic	默认（无自定义 ANTHROPIC_BASE_URL）
Moonshot / Kimi	ANTHROPIC_BASE_URL 包含 moonshot 或模型以 kimi 开头
Vertex-compatible	Base URL 包含 vertex 或 aiplatform
Bedrock-compatible	Base URL 包含 bedrock
Generic Anthropic-compatible	其他显式 ANTHROPIC_BASE_URL

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）

Provider	Base URL
Alibaba DashScope	`https://dashscope.aliyuncs.com/compatible-mode/v1`
DeepSeek	`https://api.deepseek.com`
OpenAI	`https://api.openai.com/v1`
GitHub Models	`https://models.inference.ai.azure.com`
SiliconFlow	`https://api.siliconflow.cn/v1`
Groq	`https://api.groq.com/openai/v1`
Ollama (local)	`http://localhost:11434/v1`

---

生态系统兼容

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

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

---

使用场景

场景	说明
Repo coding assistant	读取代码、修补文件、本地运行检查
Headless scripting tool	JSON 和 stream-json 输出的自动化
Plugin and skill testbed	实验 Claude-style 扩展
Multi-agent prototype harness	任务委托和后台执行
Provider comparison sandbox	跨 Anthropic-compatible 后端比较

---

与 HKUDS 其他项目的关联

项目	定位	关系
LightRAG	RAG 框架	同实验室早期作品
MiniRAG	轻量 RAG	同实验室
AutoAgent	Agent 框架	同实验室
OpenSpace	Agent 技能进化	同实验室
CLI-Anything	CLI 生成	同实验室
GATr	几何代数 Transformer	同实验室
OpenHarness	Agent Harness	本文主角

---

核心启示

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