Communitygithub.com

Observer Kit

一个本地仪表板和智能体技能,用于可见、可审查的数据转换工作流。

Observer Kit 是什么?

Observer Kit 是一个面向 AI 智能体(如 Codex、Claude、Goose)和 CLI 工作流的本地工具包,旨在为数据转换流程提供**可观察性**和**持久性**。它围绕两个核心保证构建:“存活性”(JSONL 事件在任务进行时实时推进,仪表板始终显示最新状态)和“持久性”(已完成结果写入可重读的持久化存储,重启后可从保存点继续)。该技能要求用户按照七个结构化步骤构建工作流:载入上下文、映射真实工作流、提议操作员视图、编排执行框架、验证样本、获得批准后运行完整数据集,以及审慎地恢复或调整运行。它支持通过仪表板、观察器和静态检查(如 lint_emit.py)监控行级别进度、暂停/停止控制、重复运行警告和错误管理。对于开发者而言,Observer Kit 能将缓慢循环、分页、重试、提供者调用和外部写入等操作编排为可审查、可恢复的运行,确保每次执行都有明确的边界、锁和检查点。该工具适用于本地开发环境,需要 Python 和执行脚本,并通过 CLI 命令(如 init、dashboard、run、watch)管理状态目录。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add edsmkt/observer-kit

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Observer Kit 是做什么的?

将 Observer Kit 用作本地工作流的执行框架。当前的 Codex、Claude、Pi、Command Code、Goose 或其他智能体会话仍作为大脑。该技能提供判断,CLI 提供可重复的管道,脚本执行实际工作,而观察器将操作员消息传回活动会话。

每个运行都围绕两个独立的保证构建:

  • 存活性:工作进行时 JSONL 事件持续推进,因此仪表板始终是最新的。
  • 持久性:完成的结果到达持久化边界处的可重读存储,因此重启可从已保存的工作继续。

1. 加载正确的上下文

从包含此 SKILL.md 的目录解析相对路径。

从第一个可用位置读取 Observer Kit README:

使用它来了解产品承诺、技能/CLI 分工、操作员旅程和仪表板期望。

选择活动分支并加载其参考:

  • 编写或调整生产工作流:完整阅读 references/pattern.md。它是源标识、行、持久化边界、外部写入、运行通道、控制、观察器、并发和仪表板事件的唯一真相来源。
  • 响应正在运行的工作流:阅读 references/pattern.md 的运行通道、控制、观察器和恢复部分,然后检查当前的 JSONL、持久化目标、进程状态和脚本。
  • 更改 Observer Kit 本身:阅读 references/build-guide.md,然后在更改后运行完整的验收测试套件。

在设计执行框架之前,读取目标脚本及其配置。

完成条件: 您能够说明哪个分支是活动的、用户期望监督什么,以及哪些文件定义了实现。

2. 映射真实工作流

从输入到目标跟踪脚本,并记录:

  • 不可变的源标识:解析后的路径、表格 ID、表加查询、导出 ID 或等效标识;
  • 每个源实体和每个派生实体的稳定键;
  • 每个慢循环、池、分页、重试、提供者调用和缓存填充;
  • 每个目标变更及其确认信号;
  • 恢复读取的持久化存储;
  • 开销、写入、速率、策略和质量上限;
  • 请求的运行通道:更新当前视图或创建单独视图。

保留脚本的工作业务逻辑和 CLI,同时将执行框架放置在这些实际执行路径上。

完成条件: 每个开销和变更都属于映射的循环、源、稳定键、持久化存储、目标和上限。

3. 提议操作员视图

在连接记录之前,提议一个紧凑的仪表板形状:

  • 表和稳定键;
  • 源、转换、推理、结果、目标和 error 字段;
  • 用于进度的源表;
  • 为此工作流选择的三到五个主要指标;
  • 代表性的试运行样本大小,通常为 5 到 25 行;
  • 后续充实是更新这些行还是打开一个比较通道。

邀请用户确认或编辑提议。将 error 设置为需要人工关注的行的简洁消息;成功的重试会发出 error='' 并更新行,以便“关注”视图反映当前行状态。

完成条件: 在执行开始前,用户可以想象出表、列、计数器、样本和通道。

4. 编排执行框架

在实际任务周围使用 start_observed_run(),并传递实际的 source=、dry_run、description、todo、progress_table 和简洁的 summary_metrics。

应用来自 references/pattern.md 的生产合同:

  1. 在第一次开销或变更之前获取源派生的锁。
  2. 在清单中记录输入快照、脚本/配置标识、目标和转换版本。
  3. 要求 --dry-run 加上样本限制,并使 --full-run 有明确意图。
  4. 从工作落地的循环或完成回调中,为每个实体发出带有稳定 table= 和 key= 值的消息。
  5. 使用持久化边界顺序:执行工作、持久化实际结果、发出行,然后检查点已完成键或块。
  6. 将每个外部交付包装为验证、策略检查、写入意图、确认的存储调用和写入回执。将同一业务行的目标字段从 pending 更新为其确认的结果。
  7. 在循环边界和完成写入后检查仪表板控制。
  8. 使用 throttle() 对共享提供者账户进行限速,并在代码中强制执行硬性的开销/写入上限。

对于阶段批处理管道,在阶段产生权威输出后立即持久化每个已完成的项目或有边界块。恢复时读取同一个存储并选择剩余工作。

当一个有边界单元使用内部分页时,保持累加器作用域在该单元内,并在其最后一页之后、下一个单元开始之前立即持久化。启动重放可以从该持久化存储重建工作映射;该读取恢复已完成的工作并保留现有的检查点。

完成条件: 在进程结束前的最后一条语句处停止,最多丢失当前活动项目或有边界块,且恢复时选择剩余工作,同时保留已确认的开销和写入。

5. 验证样本

在样本之前启动长期运行的仪表板,以便用户看到行到达:

observer-kit init .
observer-kit dashboard .runguard
observer-kit run --state-dir .runguard -- python3 workflow.py --dry-run --limit 10

从技能目录运行静态发射/持久性检查:

python3 references/lint_emit.py /absolute/path/to/workflow.py

执行实际样本并验证以下所有方面:

  • JSONL 事件和仪表板行在每个缓慢阶段持续推进;
  • 持久化结果存储随已完成工作推进;
  • 稳定键更新现有行并保留较早的字段;
  • 目标回执与实际目标状态匹配;
  • 强制的中途样本失败从已保存的工作在同一通道恢复;
  • 对同一源的同时启动收到重复运行警告;
  • 暂停或停止到达脚本检查点,记录确认,并为操作员上下文打开通道;
  • 仪表板在记录到达时仍然可用,包括滚动位置、过滤、时间线、计数器和“关注”行。

总结计划中的写入、跳过、错误、模式发现、预估开销和观察到的重启边界。

完成条件: 检查器退出码为 0,上述每个验证都有直接证据,并且用户已查看样本仪表板。

6. 获得明确批准后运行

在呈现样本摘要后请求明确确认。在获得批准后,通过完整的运行标志开始完整数据集。

保持一个仪表板服务器连接到状态目录。让 observer-kit run 连接到它并启动运行范围内的观察器,或者为长期项目保持一个全运行观察器:

observer-kit watch .runguard --all --follow
observer-kit run --state-dir .runguard -- python3 workflow.py --full-run

将观察器输出视为进入当前智能体会话的传输。在回复或更改运行之前,检查脚本、JSONL、持久化存储和目标。

完成条件: 完整运行已获得操作员明确批准、实时监控、终端账本事件、已核对回执和简洁的结果摘要。

7. 审慎地调整或恢复

使用相同的源、通道、表和键来重试失败、修复脚本,或对已显示的行增添充实内容。追加更新字段,以便仪表板保留历史并呈现最新行状态。

为完全重做、比较或真正的独立批次,使用新的稳定会话名称或 --session auto。当记录的键空间可证明是不相交时,并行运行多个源;在这些运行之间使用共享提供者限速。

当存在待定写入时,在继续之前核对目标并追加匹配的回执。当存在活动源锁时,等待该进程或有意停止命名 PID 后再重新开始。

完成条件: 重试重用权威的持久化状态,当前行更改在原位显示,并且有意区分的工作出现在其自己的仪表板视图中。

参考映射

  • references/pattern.md:生产集成和操作合同;为工作流设计和调整完整阅读。
  • references/lint_emit.py:最终刷新和进度的静态检查,与内存缓冲结果配对;在每次完整数据集之前运行。
  • references/build-guide.md:Observer Kit 核心、仪表板、打包和验收测试合同。
  • runguard.py:工作流脚本使用的捆绑运行时。
  • run_dashboard.py:为一个状态目录提供本地服务仪表板服务器。
  • watch_chat.py:活动智能体框架的仪表板消息传输。
  • EXPLAIN.md:向操作员展示的项目特定意图说明。

在项目设置后运行 observer-kit doctor .。在更改 Observer Kit 的运行时、CLI、检查器、观察器或仪表板后运行 observer-kit test。

相关技能