深入 AgentHandover 12 阶段 Pipeline:从屏幕截图到可执行 Skill 的完整代码实现原理

原创2026-11-01 10:12:031,872 阅读

深入 AgentHandover 12 阶段 Pipeline:从屏幕截图到可执行 Skill 的完整代码实现原理

AgentHandover 是一款开源的本地 AI 工作流学习工具,它能自动观察你在 Mac 上的操作,经过一条 12 阶段 Pipeline,把原始屏幕截图、点击、剪贴板等事件加工成 AI Agent(如 Claude Code、Codex、OpenClaw)可以直接执行的 Skill。本文带你逐阶段拆解这条 Pipeline 的完整代码实现原理,帮你理解"屏幕活动 → 可执行技能"到底是怎么发生的。

一、AgentHandover 是什么?

想象一下:你每天重复做某些工作流——登录系统、填写报表、处理邮件。AgentHandover 会在后台观察你的操作(完全本地运行,隐私优先),自动学会这些流程,并生成一份结构化的 Skill 文件交给你的 AI Agent 执行。你不需要写提示词,它"看会了"就能教。

AgentHandover 吉祥物与本地 Skill 学习概念图

整个系统由四个角色协作完成,架构定义在 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 都不能执行

AgentHandover 采集的终端屏幕帧示例

三、采集阶段(阶段 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 脱敏——密钥、密码、卡号会被清除。

AgentHandover 对 Slack 屏幕的文本优先标注示例

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:

  1. 选关键帧——select_keyframes 无需模型,纯靠规则打分:会话首尾帧、每个"停留段"的首尾帧(应用/标题/URL 变化点)、点击附近 5 秒内的帧、OCR 变化最大的帧。最多 60 帧进标注,20 帧进生成提示词
  2. 标注关键帧——生成 Skill 前先切换 Ollama 到生成模型
  3. 生成语义 SOP——sop_generator.py 用本地生成模型带着思维链从标注时间线写出结构化步骤

被动路径则从 2 次以上观察到的任务片段归纳,并跨演示比较来识别变量参数。

AgentHandover 对 Xcode 界面的关键帧标注

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/ 开始的源码,值得逐行读一遍。

登录后查看全文
AgentHandover