OpenHarness - 技术发现报告

OpenHarness 是一个用 Python 实现的超轻量级 AI Agent 基础框架（Agent Harness），以 Claude Code 约 2.3% 的代码量（~11,733 行）复现了其核心功能（43 个工具、54 个命令、多 Agent 协调、权限控制等），定位为开源、可扩展的 AI Agent 驾驶基础设施。

OpenHarness - 技术发现报告

基本信息

  • 名称： OpenHarness（命令行别名 oh）
  • 官方地址： 无独立官网，项目主页为 GitHub 仓库
  • GitHub 仓库： https://github.com/HKUDS/OpenHarness
  • 当前版本： v0.1.0（2026-04-01 首次发布）
  • License： MIT
  • 主要编程语言： Python（后端/核心）、TypeScript/React（终端 UI）
  • 首次发布日期： 2026-04-01
  • 创建者/维护团队： 香港大学数据智能实验室（HKUDS, Data Intelligence Lab @ HKU）

一句话定位

OpenHarness 是一个用 Python 实现的超轻量级 AI Agent 基础框架（Agent Harness），以 Claude Code 约 2.3% 的代码量（~11,733 行）复现了其核心功能（43 个工具、54 个命令、多 Agent 协调、权限控制等），定位为开源、可扩展的 AI Agent 驾驶基础设施。

核心特性

  1. 完整的 Agent Loop 引擎 — 实现"提示→模型流式响应→工具调用→观察结果→循环"的核心 Agent 循环，支持流式输出、API 指数退避重试、并行工具执行、Token 计数与成本追踪。

  2. 43+ 工具生态 — 涵盖文件 I/O（Bash、Read、Write、Edit、Glob、Grep）、搜索（WebFetch、WebSearch、LSP）、Jupyter Notebook 编辑、子 Agent 生成与协调、后台任务管理、MCP（Model Context Protocol）集成、定时调度等。每个工具均具备 Pydantic 输入验证、JSON Schema 自描述、权限检查和 Hook 支持。

  3. Skills + Plugins 扩展体系 — 技能系统（Skills）基于 Markdown 文件按需加载领域知识；插件系统（Plugins）兼容 Claude Code 的插件格式（已验证 12 个官方插件），支持命令、Hooks、Agent 的热插拔。

  4. 多模型提供商兼容 — 同时支持 Anthropic 格式（默认，覆盖 Anthropic Claude、Moonshot/Kimi、Vertex、Bedrock 等）和 OpenAI 兼容格式（--api-format openai，覆盖 DashScope、DeepSeek、OpenAI、GitHub Models、SiliconFlow、Groq、Ollama 本地模型等）。

  5. 多级权限治理 — 提供 Default（写操作前询问）、Auto（全部允许）、Plan Mode（禁止所有写入）三种权限模式，支持路径级规则和命令黑名单，以及 PreToolUse/PostToolUse 生命周期 Hook。

  6. 多 Agent 协调（Swarm） — 内置子 Agent 生成与委派、团队注册与任务管理、后台任务生命周期管理，支持 ClawTeam 风格的多 Agent 协作模式。

  7. React/Ink 终端 UI — 提供交互式终端界面，支持命令选择器、权限对话框、模式切换、会话恢复、实时动画反馈和上下文感知快捷键。

社区生态

  • GitHub Stars： ~3,500+（截至 2026-04-05，数据来源：知乎专栏报道）
  • Contributors： 主要由 HKUDS 团队维护，社区贡献者持续增长中
  • 最近更新日期： 2026-04-01（v0.1.0 初始发布）
  • 社区讨论热度： 知乎专栏、CSDN、阿里云开发者社区、X/Twitter 均有报道和讨论，中文社区关注度较高
  • PyPI 下载量： 未找到相关信息（项目通过 uv sync 安装，尚未发布到 PyPI）

技术栈定位

  • 所属领域： AI Agent 基础设施 / AI 编码助手 / Agent Harness 框架
  • 解决的核心问题： 为 LLM 提供"手、眼、记忆和安全边界"——将纯文本输出的聊天模型转变为能执行文件操作、运行命令、搜索网络、管理记忆的功能性 Agent
  • 替代/竞品技术：
  • Claude Code（Anthropic 官方，TypeScript 实现，512,664 行代码）— 主要对标对象
  • OpenCode（开源 Claude Code 替代品，Go 实现）
  • Cline（VS Code 插件形式的 AI 编码助手）
  • Goose（本地开源 AI 编码工具）
  • 同属 HKUDS 生态的 Nanobot（22k Stars 的轻量 AI 助手）和 OpenClaw
  • 依赖的上游技术： Python 3.10+、uv 包管理器、Node.js 18+（可选，用于 React TUI）、LLM API（Anthropic/OpenAI 兼容格式）
  • 下游使用者/集成方： 兼容 anthropics/skills 和 claude-code/plugins 生态；可集成到 CI/CD 流水线（支持 JSON/stream-json 输出格式）

架构概览

OpenHarness 实现了 10 个核心子系统：

openharness/
  engine/          # Agent Loop — 查询 → 流式响应 → 工具调用 → 循环
  tools/           # 43 个工具 — 文件 I/O、Shell、搜索、Web、MCP
  skills/          # 知识 — 按需加载技能文件（.md）
  plugins/         # 扩展 — 命令、Hook、Agent、MCP 服务器
  permissions/     # 安全 — 多级权限模式、路径规则、命令黑名单
  hooks/           # 生命周期 — PreToolUse/PostToolUse 事件 Hook
  commands/        # 54 个命令 — /help、/commit、/plan、/resume 等
  mcp/             # MCP — Model Context Protocol 客户端
  memory/          # 记忆 — 跨会话持久化知识
  tasks/           # 任务 — 后台任务管理
  coordinator/     # 多 Agent — 子 Agent 生成、团队协调
  prompts/         # 上下文 — 系统提示组装、CLAUDE.md、技能注入
  config/          # 配置 — 多层配置、迁移
  ui/              # React TUI — 后端协议 + 前端界面

核心理念："The model is the agent. The code is the harness."（模型是 Agent，代码是 Harness）

与 Claude Code 的对比

维度 Claude Code OpenHarness 比例
代码量 512,664 行 11,733 行 2.3%
文件数 1,884 163 8.6%
工具数 ~44 43 98%
命令数 ~88 54 61%
实现语言 TypeScript Python —
开源协议 未完全开源 MIT —

关键链接汇总

官方资源

教程资源

社区资源

信息来源