OpenHarness 开源 Agent Harness 专题

OpenHarness（PyPI 包名 openharness-ai）定位为轻量 Agent 基础设施：流式 tool-use 循环、四十余类工具、CLAUDE.md / 压缩 / MEMORY.md、多级权限与 Hooks、Swarm 多智能体协作等。上游由社区维护；与 Anthropic 官方 Claude Code 无隶属关系，实现语言与发布形态亦不同。

本页是本站对 OpenHarness 的专题导读：帮助读者在「读 TS 源码课」之外，多一条直接跑 Python Harness 的对照轴。首页「12 主题全景」Mermaid 中已用虚线标注与 OpenHarness 的对照关系。

源码课（架构对照）：OpenHarness 源码课；OH01–OH12 与 S01–S12 逐讲对标，见讲稿目录。

快速上手（摘自上游文档）

以下命令与说明以 HKUDS README.zh-CN ↗ 为准；此处仅作入口摘录。

安装

curl -fsSL https://raw.githubusercontent.com/HKUDS/OpenHarness/main/scripts/install.sh | bash

贡献者可选 bash -s -- --from-source；需要 IM 通道时加 --with-channels。

源码运行（`uv`）

git clone https://github.com/HKUDS/OpenHarness.git
cd OpenHarness
uv sync --extra dev
uv run oh

模型与 Provider 推荐走交互向导：oh setup（profile 级凭据、workflow 视角）。

与 Source Map 源码课、Harness 长文的关系

入口	你主要得到什么
Source Map 源码专题	围绕重建的 TypeScript 树讲 S01–S12：Agent Loop、工具、权限、MCP 等实现向阅读。
知乎 / 仓库 Harness 工程向稿（如 14–20）	从架构与产品角度拆子 Agent、写盘安全、上下文预算等，不必绑定某一语言。
本专题 · OpenHarness	完整开源可跑的 Harness 代码库（Python），适合改配置、加工具、对照测试与二次开发。

十二章（S01–S12）↔ OpenHarness 源码路径（节选）

路径均相对上游仓库 src/openharness/，便于你读完一课就跳进一目录。映射是教学向近似，非逐 API 等价。

课程	建议优先打开的目录 / 文件
S01 Agent Loop · 细讲 OH01	`engine/query_engine.py`、`engine/query.py`、`engine/stream_events.py`、`engine/cost_tracker.py`
S02 工具系统 · 细讲 OH02	`tools/`（`base.py` 与各类 `*_tool.py`）
S03 权限 · 细讲 OH03	`permissions/`、`ui/permission_dialog.py`
S04 CLI 命令 · OH04	`commands/`、`cli.py`、`__main__.py`
S05 上下文压缩 · OH05	`services/compact/`、`prompts/context.py`
S06 Subagent / Fork · OH06	`coordinator/`、`swarm/`、`tools/agent_tool.py`
S07 MCP · OH07	`mcp/`、`tools/mcp_tool.py`、`tools/read_mcp_resource_tool.py`
S08 任务管理 · OH08	`tasks/`、`tools/task_*_tool.py`
S09 Bridge / IDE · OH09	`bridge/`、`ui/backend_host.py`、`ui/react_launcher.py`
S10 Hooks · OH10	`hooks/`
S11 Vim · OH11	`vim/`、`keybindings/`
S12 Git 工作流 · OH12	`tools/enter_worktree_tool.py`、`tools/exit_worktree_tool.py`、`tools/bash_tool.py`（常见 Git 操作经 Shell / worktree）

更多模块（Skills、Memory、Cron、多通道等）见 skills/、memory/、services/cron*、channels/。

能力分层（示意）

与上游 README 的模块叙事一致；下图便于和 S01 Agent Loop、S07 MCP 等章节脑内对齐。

OpenHarness 栈（示意）

上游亮点（摘自官方自述）

Agent Loop：流式 tool 调用、重试、并行工具、token / 成本统计。
Harness Toolkit：40+ 工具（文件、Shell、检索、Web、MCP 等）；Skills / 插件生态；与 anthropics/skills 等形态兼容表述。
Context & Memory：CLAUDE.md 发现与注入、自动压缩、MEMORY.md、会话恢复与历史。
Governance：多级权限、路径与命令规则、Pre/Post Tool Hooks、交互审批。
Swarm：多 Agent 协调；上游含大量 pytest 与 E2E 说明。

细节与徽章以 HKUDS/OpenHarness 为准。

在本仓库中的位置

为便于与课程、reference 其它快照统一治理，OpenHarness 以目录快照形式置于（注意顶层文件夹名有一处历史拼写 rererence）：

reference/rererence_harness/OpenHarness/

该树与上游开源仓库同源对照使用；若需提 PR 或拉 Issue，请优先指向 HKUDS 官方仓库。本课程站不负责同步上游每个 commit，读者以 git 或上游 Release 为准。

若克隆本仓库后没有 OpenHarness/ 子目录，请阅读 reference/rererence_harness/README.md ↗，按说明自行拉取上游到同一路径。

OpenHarness 完全开源的 Agent Harness