大家好，我是何三，独立开发者
今天刷到一个港大（HKUDS）开源的项目——OpenHarness，Star 已经冲到 3.5k。刚看到名字，我以为是某个测试框架，仔细看了 README 才发现，这是个AI Agent 基础设施项目，而且定位很有意思。
它不是另一个聊天机器人包装器，不是又一个 LangChain 替代品。它做的是一件更底层的事：给大模型套上"马具"（Harness），让它变成一个真正能干活的 Agent。
这个概念我觉得挺值得聊一聊。
什么 Agent Harness？
说人话：大模型本身只是脑子，聪明但没手没脚。你要让它帮你改代码、查文件、跑脚本、上网搜索……就得给它装上一整套工具链和安全边界。
这就是 Harness。
公式大概是这样：
Agent = LLM（智能）+ Harness（双手 + 双眼 + 记忆 + 安全边界）
OpenHarness 就是这个 Harness 的开源实现。用 Python 写的，代码 96.5%，剩下 3.5% 是 React 写的终端 UI。
有什么不一样？
市面上 Agent 框架不少，LangChain、AutoGen、CrewAI……各有各的玩法。OpenHarness 跟它们比，有几个地方比较突出。
第一，极简启动。
一条命令就能跑起来：
ANTHROPIC_API_KEY=your_key uv run oh -p "检查这个仓库，列出 Top 3 优化建议"
装好之后，终端里输入 oh 就进入交互模式，跟 Claude Code 的体验几乎一样。
第二，43 个内置工具。
文件读写、Shell 执行、代码搜索（Grep/Glob/LSP）、Web 抓取、MCP 协议……该有的都有。每个工具都带 Pydantic 输入校验和 JSON Schema 自描述，模型能自动理解工具的用途和参数。
第三，模型兼容性非常广。
默认走 Anthropic 格式，但也支持 OpenAI 兼容格式。也就是说，通义千问、DeepSeek、Kimi、Ollama 本地模型、Groq、SiliconFlow……统统可以接。切模型只需要改几个环境变量。
第四，多 Agent 协作。
这是我觉得最炸裂的功能。OpenHarness 内置了 Swarm 协调机制，可以动态生成子 Agent、注册团队、分配后台任务。简单的说就是：主 Agent 可以派小弟去干活，还能管理一群小弟。
快速上手
动手试试。前置条件很简单：Python 3.10+ 和 uv 包管理器。
# 克隆安装
git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness
uv sync --extra dev
# 配置模型（以 Kimi 为例）
export ANTHROPIC_BASE_URL=https://api.moonshot.cn/anthropic
export ANTHROPIC_API_KEY=your_kimi_api_key
export ANTHROPIC_MODEL=kimi-k2.5
# 启动
oh
如果你用的是国产模型，比如通义千问，那就用 OpenAI 兼容格式：
uv run oh --api-format openai \
--base-url "https://dashscope.aliyuncs.com/compatible-mode/v1" \
--api-key "sk-xxx" \
--model "qwen3.5-flash"
非交互模式也很实用：
# 单次执行，输出到 stdout
oh -p "解释这个代码库"
# JSON 输出，方便脚本处理
oh -p "列出 main.py 里所有函数" --output-format json
# 实时流式输出
oh -p "修复这个 bug" --output-format stream-json
最后这种 stream-json 模式特别适合集成到自动化流水线里。
核心架构拆解
OpenHarness 的代码组织得很清晰，10 个子系统各司其职：
openharness/
├── engine/ # Agent Loop 核心
├── tools/ # 43+ 工具
├── skills/ # 按需加载知识
├── plugins/ # 插件系统
├── permissions/ # 权限控制
├── hooks/ # 生命周期钩子
├── commands/ # 54 个命令
├── mcp/ # MCP 协议客户端
├── memory/ # 持久记忆
├── coordinator/ # 多 Agent 协调
├── prompts/ # 上下文组装
├── config/ # 多层配置
└── ui/ # React 终端 UI
Agent Loop 是心脏。 整个运转逻辑很直白：
while True:
response = await api.stream(messages, tools)
if response.stop_reason != "tool_use":
break # 模型干完了
for tool_call in response.tool_uses:
# 权限检查 → 前置Hook → 执行 → 后置Hook → 返回结果
result = await harness.execute_tool(tool_call)
messages.append(tool_results)
# 继续循环，模型看到结果后决定下一步
模型决定做什么，Harness 决定怎么做。安全、高效、全程可观测。
Skills 系统也值得一提。 技能是按需加载的 .md 文件——模型只在需要的时候才读取对应领域的知识。内置 40+ 技能（commit、review、debug、plan、test……），而且兼容 Anthropic 官方的 skills 格式，直接复制过来就能用。
权限系统比较细致。 三种模式：默认模式（写操作前询问）、自动模式（全部放行，适合沙箱）、计划模式（禁止所有写操作，先规划再动手）。还支持路径级别的规则和命令黑名单。
扩展性
OpenHarness 的扩展方式很友好：
自定义工具——继承 BaseTool，实现 execute 方法就行：
from pydantic import BaseModel, Field
from openharness.tools.base import BaseTool, ToolExecutionContext, ToolResult
class MyToolInput(BaseModel):
query: str = Field(description="搜索查询")
class MyTool(BaseTool):
name = "my_tool"
description = "做点有用的事"
input_model = MyToolInput
async def execute(self, arguments: MyToolInput,
context: ToolExecutionContext) -> ToolResult:
return ToolResult(output=f"结果: {arguments.query}")
自定义技能——写个 .md 文件放进 ~/.openharness/skills/ 目录：
---
name: my-skill
description: 我的专业领域指导
---
# My Skill
## 什么时候用
用户问到 [你的领域] 的时候使用。
## 工作流
1. 第一步
2. 第二步
插件——兼容 claude-code 插件格式，支持命令、Hook、Agent 三种扩展类型。
测试覆盖
作为一个开源项目，OpenHarness 的测试做得不错：
- 114 个单元/集成测试，全部通过
- 6 个 CLI 标志 E2E 测试（真实模型调用）
- 9 个 Harness 特性 E2E 测试
- 3 个 React TUI E2E 测试
- 4 个 TUI 交互 E2E 测试
- 12 个真实 Skills + Plugins E2E 测试
总共 148 个测试，说明项目的工程化程度比较高。
适合谁用？
几个典型的场景：
- 想搞懂 Agent 底层原理的人——代码结构清晰，是最好的学习材料
- 需要本地化 Agent 方案的开发者——支持 Ollama 本地模型，数据不出域
- 做多 Agent 协作研究——内置 Swarm 机制，省得自己搭
- 要搭建自动化流水线——
stream-json输出模式，跟 CI/CD 天然亲和 - 插件和技能开发者——兼容 Anthropic 和 claude-code 生态
总结
OpenHarness 给我的感觉是：它不是来替代谁的，而是来补位的。
补的是 Agent 基础设施这块空白——一个轻量、可扩展、多模型兼容、工程化程度高的开源 Harness。港大团队把生产级 Agent 的核心架构拆解、简化、开源了，让研究者和开发者可以站在这个基础上做自己的事。
MIT 协议，Python 写的，文档齐全。如果你正在研究 Agent 或想搭自己的 Agent 工具链，这个项目值得仔细看看。
项目地址：https://github.com/HKUDS/OpenHarness
本文使用 MGO 编辑并发布
关注"何三笔记"，回复"mgo" 免费下载使用
