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 的心脏，一个无限可组合的循环： ```python 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）： ```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 配置示例**： ```bash 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