adongwanai/learn-workbuddy

解決する課題

デスクトップAIアシスタントの構築は、コマンドラインエージェントよりもはるかに難しい。ツールを呼び出す単純なループはターミナルで問題なく動作するが、デスクトップアプリはセッションをまたいで存続し、コンテキストウィンドウを壊さずに巨大なツール出力を管理し、長期的なメモリを安全に保存し、エージェントがバックドアにならないように権限を制御し、多数の可動部品を分離する必要がある。このプロジェクトは、これらの問題を24の構造化されたレッスンに変換し、各レッスンで動作するPythonコードと図を使って、メカニズムを1つずつ追加する。

仕組み

このプロジェクトは、本番ソースコードではなく、教育用の設計図である。デスクトップエージェントをUI、エージェント推論、ツール実行、拡張システム、メモリシステム、安全ガバナンスの6つのレイヤーに分解する。各レッスン（s01〜s24）は前のレッスンに基づいて、基本エージェントループ、ツールディスパッチ、パーミッションフックから、Electronシェル、サイドカーサーバー、セッション管理、モデルルーティング、JSONLトランスクリプト、ワークスペース/ユーザー/クラウドメモリ、出力外部化、プロンプトアセンブリ、スキル、MCPコネクタ、エキスパート、可視化、SQLite、自動化、ハッシュチェーン付き監査サンドボックスまで、一度に1つのコアメカニズムを追加する。

Mini WorkBuddyと呼ばれる最小限のリファレンス実装が含まれており、Python標準ライブラリのみで構築されているため、エージェントループ、権限ガード付きツール、JSONLストレージ、外部化出力、追記専用監査ログ、REST/ACPライクなサーバー、DeepSeek、Anthropic、OpenAI、OpenAI互換ゲートウェイを単一のToolCall/ModelTurnインターフェースに正規化するプロバイダーアダプターなど、完全なリクエストパスを検査できる。

各章のcode.pyを--demoフラグ付きで実行すると、APIキーを必要とせず、多くのデモを完全にオフラインで実行できる。実モデルのレッスンでは、DEEPSEEK_API_KEY（またはAnthropic/OpenAIキー）を入力し、モデル/ツールのJSONLトレースを書き込むインタラクティブな教育CLIや統合評価モードを実行できる。scripts/verify.pyは、構文、テスト、オフラインデモ、ドキュメント、クリーンルームコンプライアンスをチェックする。

対象読者

基本的なCLIエージェント（関連するlearn-claude-codeプロジェクトなど）をすでに理解しており、デスクトップ製品エンジニアリングをさらに深く学びたい開発者向け。長時間実行プロセスのアーキテクチャ、メモリとコンテキストの管理、マルチエージェントコラボレーションの処理、安全性の強化、複数のモデルプロバイダーとの統合を学ぶことができる。また、依存関係を最小限に抑えたハンズオン、章ごとのアプローチを好む教育者や自習者にも適している。

ハイライト

• 実行可能なPythonコードと28の図を備えた24章。各レッスンでメカニズムを1つだけ追加
• UI、推論、ツール、拡張機能、メモリ、安全性の責任境界を示す6層アーキテクチャ
• プロバイダーアダプターレイヤーによるマルチプロバイダーサポート（DeepSeek、Anthropic、OpenAI、OpenAI互換ゲートウェイ）。ループは安定したまま、モデルを交換可能
• ほとんどの例で完全オフラインのデモ。標準ライブラリのMini WorkBuddyハーネスを含み、APIキーなしで完全なパイプラインを実行および検査可能
• メモリシステムを5つのレイヤー（ワークスペース、ユーザー、リモートプロファイル、トランスクリプト、ツール結果スワップ）に詳細に分割。重要なアイデア：コンテキストウィンドウはRAM、JSONL、SQLite、メモリファイル、ツール結果はディスク
• クリーンルーム保証：オリジナルの教育コードと公開されたアーキテクチャの観察のみを含み、WorkBuddyのクローズドソースコード、キー、プライベートプロンプトは一切含まない
• メモリ耐性、エビデンスに基づくRAG、検索ルーティング、すべてのレッスンでプロバイダーを比較できるモデルベンチマークなどの高度な評価例を含む