OpenHarness – 港大开源的轻量级 AI Agent 框架

OpenHarness是什么

OpenHarness 是香港大学数据智能实验室（HKUDS）开源的轻量级 AI Agent 框架，用纯 Python 实现，仅 11,733 行代码（为 Claude Code 的 1/44 体积），复刻了其 98% 的核心工具能力（43 个工具）和 61% 的命令集（54 个命令）。项目采用 MIT 许可证，提炼「Agent Harness」架构，围绕 LLM 提供工具调用、持久记忆、权限治理和多 Agent 协调，完美兼容 Anthropic Skills 与 Claude Code 插件生态，支持通过环境变量切换至任意 OpenAI 兼容模型（如 Kimi、DeepSeek、Ollama）。

OpenHarness的主要功能

• Agent 核心循环：实现流式工具调用、指数退避重试、并行执行、实时 Token 计数与成本追踪，支持上下文自动压缩和断点续聊。
• 工具集（43+）：涵盖文件 I/O、Shell 命令、Web 搜索、浏览器自动化、MCP 协议、Notebook 编辑、任务管理、Cron 定时任务等，复刻 Claude Code 98% 的工具能力。
• 技能系统：支持 Markdown 文件按需加载技能，兼容 anthropics/skills 生态，内置 Pydantic 类型校验，可复用 1000+ 官方和社区技能库。
• 记忆与上下文：自动注入 CLAUDE.md 项目规则，跨会话持久化 MEMORY.md 记忆文件，支持 MEMORY_PLACEHOLDER 模板化上下文管理。
• 多 Agent 协调：支持子 Agent 生成与任务委派、团队注册表管理、后台任务生命周期管理，未来路线图含 ClawTeam 集成。
• 权限治理：提供多级权限模式（默认/自动/计划/严格模式），支持路径级规则、命令白名单、交互式审批对话框和预/后工具钩子。
• 插件扩展：兼容 claude-code/plugins 格式，支持自定义命令、钩子、Agent 类和 MCP 服务器扩展，允许通过环境变量切换至任意 OpenAI 兼容模型（如 Kimi、DeepSeek、Ollama）。

OpenHarness的技术原理

• Agent Harness 架构：采用「Harness」设计模式，将 LLM 的智能层（模型）与执行层（工具、记忆、安全边界）分离，模型负责决定做什么（What），Harness 负责安全高效地执行（How），提供完整的可观测性。
• 核心 Agent 循环：实现标准的 ReAct 工具调用循环——LLM 输出 JSON 格式工具规格 → Harness 解析并并行执行 → 流式返回结果。循环持续直到模型停止调用工具（stop_reason != "tool_use"），期间自动处理指数退避重试和 Token 计数。
• 模块化子系统架构：由 10+ 个独立子系统组成，包括 Engine（循环引擎）、Tools（43 个工具注册表）、Skills（Markdown 技能加载器）、Plugins（扩展钩子）、Permissions（权限治理）、Hooks（生命周期事件）、Memory（持久记忆）、Coordinator（多 Agent 协调）、MCP（模型上下文协议客户端）等，各层通过明确定义的接口解耦。
• 上下文与记忆管理：采用 Token 预算机制（如 128k 限制压缩至 80k），自动注入 CLAUDE.md 项目规则，使用 SQLite 持久化 MEMORY.md 跨会话记忆，支持上下文自动压缩和断点续聊。
• 权限与治理钩子：通过 PreToolUse/PostToolUse 生命周期钩子实现拦截，支持多级权限模式（默认/自动/计划/严格）、路径级规则匹配、命令白名单和交互式审批对话框，确保敏感操作可控。
• 多 Agent 协调机制：Swarm 模式通过注册表管理子 Agent ID，使用 JSON Payload 进行任务委派，基于 Python Asyncio 协程管理生命周期，支持后台任务和并行研究子任务（如 Deep Research 场景）。
• 模型中立与兼容性：通过环境变量（ANTHROPIC_BASE_URL/ANTHROPIC_MODEL）支持任意 OpenAI 兼容端点（Kimi、DeepSeek、Ollama 等），工具调用采用标准 JSON Schema，技能和插件格式兼容 anthropics/skills 和 claude-code/plugins 生态。
• 轻量级工程实现：纯 Python 3.10+ 实现，使用 uv 包管理器实现零锁文件安装，11,733 行代码（Claude Code 的 1/44），剔除企业级开销（遥测、OAuth、数百个 React 组件），保留 React TUI 作为可选前端，通过标准输入输出协议与后端通信。

如何使用OpenHarness

• 环境准备：确保系统已安装 Python 3.10+，通过 pip install uv 安装 uv 包管理器，同时准备好 LLM API 密钥（支持 Anthropic 或任意 OpenAI 兼容端点）。
• 安装项目：在项目目录执行 uv init my-project && cd my-project 初始化项目，然后运行 uv add "hkuds/openharness[cli]" 安装 OpenHarness 及其 CLI 依赖。
• 配置密钥：通过 export ANTHROPIC_API_KEY=sk-... 设置 API 密钥；若使用 Moonshot、DeepSeek 等其他模型，需额外设置 export ANTHROPIC_BASE_URL=... 指向对应端点。
• 初始化项目：执行 oh init 命令自动生成 CLAUDE.md 项目规则文件和 MEMORY.md 记忆文件模板，完成项目初始化配置。
• 启动交互：运行 oh run --model claude-3.5-sonnet 进入交互式会话，或执行 oh demo 运行内置演示任务体验核心功能。
• 加载技能：将 .md 技能文件放入 skills/ 目录或 ~/.openharness/skills/，系统会自动识别 frontmatter 元数据并按需加载，兼容 anthropics/skills 生态。
• 权限管理：使用 oh run --permissions strict 开启严格治理模式，或通过 oh -p "提示词" --output-format json 实现无头/CI 模式输出结构化结果。
• 多 Agent 协调：通过 Swarm 模式创建子 Agent 并委派任务，利用 Asyncio 协程管理后台任务生命周期，支持并行研究子任务。

OpenHarness的项目地址

• GitHub仓库：https://github.com/HKUDS/OpenHarness