深入 AgentHandover 12 阶段 Pipeline:从屏幕截图到可执行 Skill 的完整代码实现原理
深入 AgentHandover 12 阶段 Pipeline:从屏幕截图到可执行 Skill 的完整代码实现原理
AgentHandover 是一款开源的本地 AI 工作流学习工具,它能自动观察你在 Mac 上的操作,经过一条 12 阶段 Pipeline,把原始屏幕截图、点击、剪贴板等事件加工成 AI Agent(如 Claude Code、Codex、OpenClaw)可以直接执行的 Skill。本文带你逐阶段拆解这条 Pipeline 的完整代码实现原理,帮你理解"屏幕活动 → 可执行技能"到底是怎么发生的。
一、AgentHandover 是什么?
想象一下:你每天重复做某些工作流——登录系统、填写报表、处理邮件。AgentHandover 会在后台观察你的操作(完全本地运行,隐私优先),自动学会这些流程,并生成一份结构化的 Skill 文件交给你的 AI Agent 执行。你不需要写提示词,它"看会了"就能教。
整个系统由四个角色协作完成,架构定义在 README.md 中:
| 组件 | 语言 | 职责 |
|---|---|---|
| Daemon | Rust | 常驻观察者:截图、OS 事件、剪贴板、隐私区检查 |
| Worker | Python | 大脑:运行 12 阶段 Pipeline、向量知识库、Skill 生成 |
| Extension | TypeScript | Chrome 扩展,提供 DOM 快照与点击目标 |
| App | SwiftUI | 菜单栏界面:状态、录屏、审批、摘要 |
📌 核心思想:Daemon 只负责"看",Worker 负责"想",12 阶段 Pipeline 全部运行在本地 Ollama 模型上,不经过任何云 API。
二、12 阶段 Pipeline 总览
官方在 README.md 的技术章节中给出了完整阶段表。Worker 的调度入口在 stages/__init__.py 的 tick() 函数中——每一轮控制循环按顺序执行 control(请求处理)→ ingest(事件摄入)→ submit_model_jobs(提交模型任务)→ recognize(实时识别)→ export(状态导出)。
| 阶段 | 名称 | 作用 |
|---|---|---|
| 1 | 事件驱动采集 | 只在"有事发生"时截一帧:应用切换、导航、表单提交、点击后屏幕变化、复制,或慢速心跳 |
| 2 | 文本优先标注 | 小模型先读 OCR 文本和页面元素,文本不够才看图片 |
| 3 | 算力上限 | 被动标注每小时 ≤ 60 帧、10 模型分钟,每天 ≤ 1500 帧 |
| 4 | 活动分类 | 8 类分类法把"工作"和"娱乐"分开 |
| 5 | 向量化 | 每条标注嵌入向量知识库 |
| 6 | 会话与重复 | 按天分组为工作会话,度量任务的重复频率 |
| 7 | 识别 | 新会话匹配已有 Skill 则记为一次运行,差异记为分支 |
| 8 | Skill 生成 | 写入 Skill,语义去重防止重复 |
| 9 | 落地校验(Grounding) | 逐步对照录屏核验:帧引用、UI 目标、顺序、键入内容 |
| 10 | 行为合成 | 提取策略、筛选标准、护栏、决策分支和时序 |
| 11 | 知识账本 | 逐槽位记录"已知/假设/未知",对缺口提出有预算的问题 |
| 12 | 人工审核 | 你批准之前,任何 Agent 都不能执行 |
三、采集阶段(阶段 1-3):聪明地"看"
1. 事件驱动采集,而不是逐帧录屏
Daemon(Rust)在 crates/daemon/src/observer/ 中实现事件循环:只有当焦点窗口、URL 或屏幕内容发生变化时才截一帧。截帧前先检查隐私区(capture_policy.rs),截完后如果 dHash 显示屏幕没变化就直接丢弃,连 OCR 都不跑。
这就是"事件驱动"的含义——你连续敲 30 分钟键盘,屏幕只变了 5 处,那就只产生 5 帧,而不是每秒一帧。
2. 文本优先标注(Text-first annotation)
这是整个 Pipeline 最精巧的成本优化,实现在 scene_annotator.py。核心逻辑:
- 提示词由窗口信息(应用、标题、URL)+ 浏览器 DOM 元素(Chrome 扩展)+ 排序后的 OCR 行构建,先不带图片
- 只有当屏幕文字太少、应用是画布类(如 Figma),或模型主动回答
needs_vision时,才追加一次视觉调用 - 一张图约消耗 1400 个提示 token,而纯文本标注输出被约束在约 120 token 内(12 叶 JSON Schema),成本相差数倍
每条标注最终是一个紧凑结构:app、location、task_context(在做什么、是否可重复工作流、下一步可能是什么)、ui_state、visible_items。所有进入提示词和存储的内容都会先过 redaction.py 脱敏——密钥、密码、卡号会被清除。
3. 算力上限:被动学习不打扰你
标注任务在推理线程中以 P2 优先级排队(stages/annotate.py)。预算由调度器持久化,重启不丢失;超过预算的帧进入等待队列,超过 24 小时仍未标注的旧帧会被放弃并删除截图。Focus 录制(你手动录制的演示)则豁免这些限制。
四、理解阶段(阶段 4-7):从帧到"任务"
4. 活动分类:工作与噪音的边界
activity_classifier.py 采用四段式分类:关键词+URL 启发式 → 基于用户画像的先验混合 → (可选)LLM 精化模糊类别 → 用户策略规则覆盖。8 类分类法让"报销填表"被标记为工作、"刷视频"被标记为娱乐——只有工作类帧才可能进入 Skill 生成。
5. 向量化与语义搜索
vector_kb.py 用 nomic-embed-text 把每条标注嵌入为 768 维向量,以 BLOB 形式存入 SQLite。搜索是两步走:先用 8-bit 向量的字节点积做粗筛,再对候选精确重打分——这样全库搜索几乎零解析成本。
6. 会话与重复检测
workflow_mining.py 把非噪音帧切分为工作会话(空闲超过阈值才断开会话),为每个会话计算"步骤签名":(app, host_or_doc, action_verb) 三元组序列,URL 路径会模板化(/reports/123 → /reports/{id}),再取 SHA-256 作为 workflow_key。同一工作流在不同天重复出现,才会成为候选 Skill。跨天的重复任务识别由 session_linker.py 用 Jaccard 相似度完成。
7. 识别:新活动是"老 Skill"的运行吗?
procedure_matcher.py 用结构指纹(应用、域名、动作动词)先做确定性匹配,有向量库时优先做语义匹配。匹配成功的新会话会成为该 Skill 的一次"运行",与已有版本不同的地方则被记录为"分支"——这是 Skill 自我改进的原料。
五、生成阶段(阶段 8-12):写出可信的 Skill
8. Skill 生成:从一次演示到完整 SOP
Focus 路径(你点击菜单栏"Record"录制的演示)由 stages/synthesize.py 以最高优先级 P0 处理。编排核心是 focus_processor.py:
- 选关键帧——select_keyframes 无需模型,纯靠规则打分:会话首尾帧、每个"停留段"的首尾帧(应用/标题/URL 变化点)、点击附近 5 秒内的帧、OCR 变化最大的帧。最多 60 帧进标注,20 帧进生成提示词
- 标注关键帧——生成 Skill 前先切换 Ollama 到生成模型
- 生成语义 SOP——sop_generator.py 用本地生成模型带着思维链从标注时间线写出结构化步骤
被动路径则从 2 次以上观察到的任务片段归纳,并跨演示比较来识别变量参数。
9. 落地校验:模型说的话要"有帧为证"
这是 AgentHandover 防止 Skill 幻觉的关键设计,实现在 step_grounding.py。文档开头就引用了一个真实事故:模型曾把后发生的 TextEdit 文档排到 Safari 之前,还虚构了一步"选择已输入文本"。
ground_steps 在生成之后用代码核验,不依赖模型自觉:
- 每一步必须引用它来源的帧,无引用的步骤直接丢弃
- 点击某链接/按钮的步骤,被点名称必须出现在所引帧的内容中
- 键入内容必须由按键计数佐证,复制/粘贴必须由剪贴板事件佐证
无法确认的内容不会被猜测,而是转化为"待回答的问题"(阶段 11)。
10. 行为合成:不止"做什么",还有"为什么"
behavioral_synthesizer.py 在 SOP 生成之后做第二遍 VLM 分析:提取整体策略、选择标准、内容模板、决策分支、护栏和时序。它把已生成的步骤作为上下文,让模型聚焦"为什么"而不是"做什么"。触发条件是程序积累 3 次以上观察,之后每增加 3 次重跑一次——单次演示不会强行合成。
11. 知识账本:显式记录"我知道什么"
ledger.py 为每个槽位维护三态:known(有证据支撑)、hypothesis(推测未确认)、unknown(Agent 必须问,不许假设)。每条记录都挂着证据指针(帧 ID、运行 ID 或你的回答)。缺口问题受每周预算限制,不会反复打扰你。
12. 人工审核:没有你的签字,Skill 不生效
Skill 的生命周期由 lifecycle_manager.py 管理,7 个状态从 draft 逐步走到 agent_ready。在菜单栏 App 的 Workflows 里审查策略、步骤与护栏,点击"Approve for Agents"才真正交付给 Agent;每次交接前还有一道闸门复检。CLI 侧对应命令是 agenthandover skills approve <SLUG>。
六、代码地图:去哪里读这些实现
想深入源码,建议按这条路径阅读:
| 想理解什么 | 从这里开始 |
|---|---|
| 主循环与调度 | stages/__init__.py、main.py |
| 事件摄入管道 | stages/ingest.py、main.run_pipeline |
| 截图采集与隐私 | crates/daemon/src/observer/ |
| 文本优先标注 | scene_annotator.py |
| Focus 录制全流程 | stages/synthesize.py、focus_processor.py |
| 语义 SOP 生成 | sop_generator.py、sop_dedup.py |
| 知识账本与生命周期 | ledger.py、lifecycle_manager.py |
| 记忆帧(Memory 功能) | memory.py、memory_frames 测试夹具 |
七、常见问题
问:Pipeline 每一步都需要调用大模型吗?
不需要。控制线程(control/ingest/export 阶段)完全不调模型;模型任务集中在推理线程按 P0→P2 优先级排队。关键帧选择、指纹去重、会话切分都是纯代码逻辑,模型只用于标注、生成和精化。
问:Skill 会重复生成吗?
不会。sop_dedup.py 用应用、域名、动作动词、标题词元构建指纹,Jaccard 相似度超过 0.7 就判定为同一个工作流并合并,而不是新建;步骤级冲突有 LLM 时交给 LLM 裁决。
问:数据会上传吗?
不会。所有模型经本地 Ollama 运行,截图在标注后删除,原始事件默认 14 天后清理,向量库与 Skill 全部存放在本机,无遥测。
结语
AgentHandover 的 12 阶段 Pipeline 展现了一条务实的本地 AI 工程路线:事件驱动采集控制成本,文本优先标注压低 token 消耗,帧级落地校验抑制模型幻觉,知识账本把"知道什么"变成可审计的数据,人工审核守住最后一道闸。如果你想在自己的 Agent 项目里加入"看会了就会教"的能力,这套从 worker/src/agenthandover_worker/stages/ 开始的源码,值得逐行读一遍。



