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