OpenHarness作为claude code开源的python版本很值得初学者学习研究其中包括内循环、会话系统、工具机制、记忆机制、Hook、多智能体系统在此记录本人的学习笔记。源码链接GitHub - HKUDS/OpenHarness: OpenHarness: Open Agent Harness with a Built-in Personal Agent--Ohmo! · GitHub第 1 课数据模型核心概念Agent 与 LLM 的通信基于 Anthropic 消息协议只有user和assistant两种角色没有独立的tool角色。4 种内容块TextBlock文本内容ImageBlock图片内容ToolUseBlock工具调用请求包含 id、name、inputToolResultBlock工具执行结果包含 tool_use_id、content、is_error核心规则每个ToolUseBlock的id必须与一个ToolResultBlock的tool_use_id一一对应否则 API 拒绝整个会话。关键函数sanitize_conversation_messages()清理孤儿tool_use中断导致缺少tool_result的情况防止恢复会话时 API 报错。第 2 课核心循环核心概念run_query()是 Agent 的心脏实现 ReAct 模式的工具循环。事件流设计run_query是异步生成器通过yield吐出事件AssistantTextDelta、ToolExecutionStarted、ToolExecutionCompleted等UI 层用async for订阅实现引擎与 UI 解耦。主循环结构关键机制max_turns熔断默认 8QueryEngine/ 200QueryContext防止死循环asyncio.gather(return_exceptionsTrue)多工具并发时防止级联取消工具执行管线hook → 校验 → 权限 → 执行 → 卸载 → carryover → hook图解 完整数据流第 3 课会话引擎核心概念QueryEngine是会话的所有者跨多轮用户输入管理历史。submit_message流程记录用户目标到短期记忆remember_user_goal准备会话检查点_prepare_session_memory净化会话历史sanitize_conversation_messages追加用户消息触发USER_PROMPT_SUBMIThook构造QueryContext调用run_queryfinally 块记忆三连_update_session_memory()→ 会话检查点落盘_extract_durable_memories()→ LLM 抽取持久记忆_schedule_auto_dream()→ 后台整理调度continue_pending中断恢复机制当会话末尾是待应答的 tool_result时无用户输入续跑。浅拷贝query_messages list(self._messages)防止run_query中途修改self._messages。图解 1QueryEngine 的角色图解 2submit_message 完整流程图解 3finally 块记忆三连图解 4浅拷贝与消息同步图解 5continue_pending 中断恢复图解 6Coordinator 模式瞬态注入图解 7QueryEngine 与 run_query 的关系第 4 课工具系统核心概念所有工具继承BaseTool通过ToolRegistry注册和管理。BaseTool 接口name工具名description描述给模型看input_modelpydantic 模型自动校验输入execute()执行逻辑is_read_only()是否只读影响权限检查to_api_schema()转成 API 格式工具分类内置工具40Python 实现继承BaseToolMCP 工具外部服务器用McpToolAdapter包装权限检查PermissionChecker敏感路径保护硬编码不可覆盖工具黑名单/白名单路径规则命令黑名单权限模式FULL_AUTO / DEFAULT / PLANCarryovertool_metadata短期携带状态在工具循环的每一轮之间传递记录当前目标、已验证工作、活跃工件等。模型看不到引擎和工具可以读取。工具系统完整清单第 5 课Hook 系统核心概念Hook 是在特定时机自动执行的回调实现可扩展性。10 种事件SESSION_START、SESSION_END、PRE_COMPACT、POST_COMPACT、PRE_TOOL_USE最重要可阻断、POST_TOOL_USE、USER_PROMPT_SUBMIT、NOTIFICATION、STOP、SUBAGENT_STOP。4 种 Hook 类型command执行 Shell 命令http发送 HTTP 请求promptLLM 快速判断max_tokens512agentLLM 深度分析timeout60s关键机制matcher过滤条件只匹配特定工具如matcherbashblock_on_failure失败时是否阻断$ARGUMENTS参数占位符被 payload JSON 替换AggregatedHookResult.blocked任意一个 Hook 阻断 → 整体阻断第 6 课记忆系统核心概念四层记忆模型从短到长。L1 工作记忆tool_metadata工具循环期间的短期状态内容当前目标、已验证工作、活跃工件生命周期会话期间不持久化L2 会话记忆session_memory当前会话的结构化快照存储~/.openharness/data/session-memory/*.md写入时机每次用户输入结束后用途压缩时替代早期历史L3 持久记忆memory/Markdown 库跨会话永久保存的事实、偏好、项目知识存储project/.openharness/memory/*.md格式带 frontmatter 元数据的 Markdown关键字段id、name、type、scope、signature去重用写入方式LLM 抽取每次用户输入最多 3 条 手动添加边界限制索引 200 行 / 25KB最多 200 个文件TTL 过期L4 记忆整理autodream后台异步整理记忆库触发条件距上次 ≥24h 且期间 ≥5 个会话操作合并、去重、删除过期记忆图解 1四层记忆的时间尺度图解 2单次用户输入的记忆时间线图解 3记忆生命周期图解 4Autodream 触发条件图解 5记忆文件的时间演化图解 6记忆层级间的数据流动图解 7记忆边界限制第 7 课多智能体系统核心概念一个 Agent 可以派生子 Agent让它们并行工作。两种后端Subprocess进程级隔离文件邮箱通信跨平台资源消耗高In-Process协程级隔离ContextVar文件邮箱 内存队列仅 POSIX资源消耗低ContextVar为每个 asyncio Task 提供上下文副本实现任务本地存储让多个子 Agent 并行运行时互不干扰。邮箱通信存储~/.openharness/data/teams/team/agent/inbox/格式JSON 文件消息类型user_message、shutdown、idle、permission_request、permission_response权限同步子 Agent 请求危险操作 → 发送permission_request到主 Agent 邮箱主 Agent 决策规则 / LLM / 用户交互→ 发送permission_response子 Agent 收到响应后继续执行生命周期TeammateAbortControllercancel_event优雅取消force_cancel强制终止状态starting→running→idle→stopping→stopped完成后写idle消息到主 Agent 邮箱触发SUBAGENT_STOPhook图解 1整体架构图解 2Agent 派生流程图解 3邮箱通信系统图解 4权限审批流程图解 5子 Agent 生命周期图解 6ContextVar 隔离