Communitygithub.com

ed smkt/observer-kit

データ変換ワークフローのためのローカルダッシュボードとエージェントスキル。可視化とレビューが可能なデータ処理パイプラインを構築します。

observer-kit とは?

Observer Kitは、AIエージェント(Codex、Claude、Gooseなど)と連携するローカルワークフローハーネスです。データ変換パイプラインにおいて、**ライブネス**(JSONLイベントのリアルタイム更新)と**耐久性**(再開可能な永続ストレージ)の2つの保証を提供します。ワークフローの設計から実行、監視、復旧までを一貫して支援し、ダッシュボードで進行状況を可視化します。主な機能には、パターン参照によるワークフローマッピング、サンプル実行による検証、明示的な承認後のフル実行、障害発生時の意図的な復旧とデータ整合性の維持が含まれます。対応プラットフォームは、CLIツールとしてObserver Kit自体が提供され、AIエージェントスキルとしてREADMEやパターンドキュメントを参照しながら実装をガイドします。

対応✓Claude Code✓Codex CLI~Cursor
npx skills add edsmkt/observer-kit

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Observer Kit

Observer Kitをローカルワークフローのハーネスとして使用します。現在のCodex、Claude、Pi、Command Code、Goose、その他のエージェントセッションは引き続き頭脳として機能します。スキルは判断力を提供し、CLIは反復可能な配管を提供し、スクリプトが実際の作業を実行し、ウォッチャーがオペレーターのメッセージをアクティブセッションに戻します。

すべての実行を2つの別々の保証に基づいて構築します。

  • ライブネス: 作業中にJSONLイベントが進行するため、ダッシュボードは最新の状態を保ちます。
  • 耐久性: 完了した結果は、耐久性のある境界にある再読み取り可能なシンクに到達するため、再起動は保存された作業から継続されます。

1. 適切なコンテキストを読み込む

このSKILL.mdを含むディレクトリからの相対パスを解決します。

利用可能な最初の場所からObserver KitのREADMEを読み取ります。

これを使用して、製品の約束、スキル/CLIの分割、オペレーターのジャーニー、ダッシュボードの期待事項を学びます。

アクティブブランチを選択し、そのリファレンスを読み込みます。

  • プロダクションワークフローを作成または適応する場合: references/pattern.md を全文読んでください。これは、ソースID、行、耐久性のある境界、外部書き込み、実行レーン、制御、ウォッチャー、同時実行性、ダッシュボードイベントに関する唯一の信頼できる情報源です。
  • 実行中のワークフローに応答する場合: references/pattern.md の実行レーン、制御、ウォッチャー、リカバリーのセクションを読み、次に現在のJSONL、耐久性のある宛先、プロセス状態、スクリプトを検査します。
  • Observer Kit自体を変更する場合: references/build-guide.md を読み、変更後に完全な受理テストスイートを実行します。

ハーネスを設計する前に、対象のスクリプトとその設定を読みます。

完了条件: どのブランチがアクティブか、ユーザーが何を監視したいか、どのファイルが実装を定義しているかを述べられること。

2. 実際のワークフローをマッピングする

スクリプトを入力から宛先までトレースし、以下を記録します。

  • 不変のソースID: 解決されたパス、シートID、テーブルとクエリ、エクスポートID、または同等のもの。
  • 各ソースエンティティと各派生エンティティの安定したキー。
  • すべての低速ループ、プール、ページ、リトライ、プロバイダーコール、キャッシュフィル。
  • すべての宛先の変更とその確認信号。
  • 再開時に読み取る耐久性のあるストア。
  • 支出、書き込み、レート、ポリシー、品質の上限。
  • 要求された実行レーン: 現在のビューを更新するか、別のビューを作成するか。

ハーネスをこれらの実際の実行パスに配置しながら、スクリプトの動作するビジネスロジックとCLIを維持します。

完了条件: すべての支出と変更が、マッピングされたループ、ソース、安定したキー、耐久性のあるストア、宛先、上限に属していること。

3. オペレータービューを提案する

レコードを配線する前に、コンパクトなダッシュボード形状を提案します。

  • テーブルと安定したキー。
  • ソース、変換、推論、結果、宛先、errorフィールド。
  • 進行状況に使用するソーステーブル。
  • このワークフローに選択された3~5つの主要メトリクス。
  • 代表的なドライランのサンプルサイズ(通常5~25行)。
  • 後続のエンリッチメントがこれらの行を更新するか、比較レーンを開くか。

ユーザーに提案の確認または編集を促します。errorを、人間の注意が必要な行に対する簡潔なメッセージに設定します。成功したリトライは、更新された行とともにerror=''を発行し、Attentionビューが現在の行の状態を反映するようにします。

完了条件: ユーザーが実行開始前にテーブル、列、カウンター、サンプル、レーンをイメージできること。

4. ハーネスを配線する

実際のジョブの周りでstart_observed_run()を使用し、実際のsource=、dry_run、description、todo、progress_table、簡潔なsummary_metricsを渡します。

references/pattern.mdからのプロダクション契約を適用します。

  1. 最初の支出または変更の前に、ソース派生のロックを取得します。
  2. マニフェストに入力スナップショット、スクリプト/設定のID、宛先、変換バージョンを記録します。
  3. --dry-runとサンプル制限を必須とし、--full-runを意図的なものにします。
  4. 各エンティティを、その作業が着地するループまたは完了コールバックからの安定したtable=とkey=の値で発行します。
  5. 耐久性のある境界の順序を使用します。作業を実行し、実際の結果を永続化し、行を発行し、完了したキーまたはチャンクをチェックポイントします。
  6. 各外部配信を、検証、ポリシーチェック、書き込み意図、確認済みシンクコール、書き込み受領でラップします。同じビジネス行の宛先フィールドをpendingから確認済みの結果に更新します。
  7. ループ境界と書き込み完了後にダッシュボードコントロールをチェックします。
  8. 共有プロバイダーアカウントをthrottle()でペース調整し、コードでハードな支出/書き込み上限を適用します。

フェーズバッチパイプラインの場合、各確定アイテムまたは境界チャンクを、そのフェーズが信頼できる出力を生成した時点で永続化します。再開は同じストアを読み取り、残りの作業を選択します。

1つの境界ユニットが内部ページネーションを使用する場合、アキュムレータをそのユニットにスコープし、次のユニットが開始する前に、最終ページの直後に永続化します。スタートアップのリプレイは、この耐久性のあるストアから作業マップを再構築する場合があります。この読み取りは完了した作業を復元し、既存のチェックポイントを保持します。

完了条件: 最終ステートメントの1行前でプロセスを停止すると、アクティブなアイテムまたは境界チャンクのみが失われ、再開は確認済みの支出と書き込みを保持しながら残りの作業を選択すること。

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イベントとダッシュボード行がすべての低速フェーズ中に進行すること。
  • 耐久性のある結果ストアが完了した作業とともに進行すること。
  • 安定したキーが既存の行を更新し、以前のフィールドを保持すること。
  • 宛先受領が実際の宛先状態と一致すること。
  • 強制的なサンプル途中の障害が同じレーンで保存された作業から再開すること。
  • 同じソースでの同時開始が重複実行警告を受信すること。
  • 一時停止または停止がスクリプトのチェックポイントに到達し、確認を記録し、オペレーターコンテキストのチャネルを開くこと。
  • レコード到着中もダッシュボードが使用可能であること(スクロール位置、フィルター、タイムライン、カウンター、Attention行を含む)。

計画された書き込み、スキップ、エラー、スキーマの発見事項、推定支出、観測された再開境界を要約します。

完了条件: リンターがゼロで終了し、上記の各検証に直接的な証拠があり、ユーザーがサンプルダッシュボードをレビュー済みであること。

6. 明示的な承認後に実行する

サンプルサマリーを提示した後、明示的な確認を求めます。承認後、意図的なフル実行フラグを使用して完全なデータセットを開始します。

1つのダッシュボードサーバーを状態ディレクトリにアタッチしたままにします。observer-kit runにそれをアタッチさせ、実行スコープのウォッチャーを開始させるか、長期プロジェクト用に1つの全実行ウォッチャーを維持します。

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: 1つの状態ディレクトリ用のlocalhostダッシュボードサーバー。
  • watch_chat.py: アクティブなエージェントハーネス用のダッシュボードメッセージトランスポート。
  • EXPLAIN.md: オペレーターに表示されるプロジェクト固有の意図表明。

プロジェクトセットアップ後にobserver-kit doctor .を実行します。Observer Kitのランタイム、CLI、リンター、ウォッチャー、またはダッシュボードを変更した後はobserver-kit testを実行します。

関連スキル