開発

テスト、フォーマット、Lint、ビルドの手順。

前提

Rust stable を使用します。Cargo.toml の rust-version は 1.88 で、 rust-toolchain.toml により rustfmt と clippy も自動で有効になります。

Rust の検証

リポジトリのルートで、次のコマンドを実行します。

cargo check --locked
cargo test --locked
cargo fmt --all -- --check
cargo clippy --all-targets --locked -- -D warnings
cargo build --release --locked

makers（cargo-make）を使う場合は、対応するタスクを実行できます。

makers check
makers test
makers fmt-check
makers clippy
makers build

macOS arm64 で ld: library not found for -liconv が発生する場合は、makers の cargo ラッパーが Apple Clang と Xcode SDK を設定して対応します。

実装の責務と拡張時の確認点

app は CLI 引数から実行環境を組み立て、結果の出力と履歴記録を調整します。モデルへの要求・ツール呼び出しは engine、workflow の制御構造は workflow が担当します。 app/workflow_run.rs はトップレベルの進捗・再開・チェックポイント・実行期限を管理します。
engine/context.rs の AppServices は設定に依存するレジストリ・キャッシュを共有し、 RunContext は実行ごとの変数・使用量・ポリシー・キャンセル元を保持します。共有サービスの終了は最上位の所有者が行い、個々の実行コンテキストから終了させません。 config::Endpoint は認証情報の取得方法を選ぶだけで、シークレット取得コマンドは実際の要求時に SecretResolver が非同期で実行します。
ワークフローは workflow/parse.rs が YAML を読み込み、ステップの種類キー・フィールドの組み合わせ・id の重複・スキーマ参照・jq/テンプレートの構文・break/stop/ask/write の配置をすべて検証してから、workflow/model.rs の Step/StepKind へ変換します。実行（workflow/exec.rs）・dry-run・graph・lint はこの検証済みの型だけを受け取ります。構文を変更する場合は schemas/workflow.json も更新し、パーサーと Schema の整合性テストを追加します。
workflow/exec.rs はステップ間の値を serde_json::Value のまま扱い、テキストが必要な境界（ユーザーメッセージ・標準入力・書き出し・最終出力）でだけ template::to_text で文字列にします。jq とテンプレートは jq::Globals（$steps/$inputs/$loop）という同じ文脈を共有します。
engine::ToolLoop はモデルとの会話履歴、ツール集合、ラウンド上限、ツール実行を管理します。ストリームの有無にかかわらず同じ状態管理を使います。
engine/stream.rs はストリームの集約と表示を扱います。出力先を AsyncWrite として渡せるため、標準出力の差し替えや実 API を使わずに reasoning、ツール呼び出し、キャンセルを検証できます。
frontmatter::parse は agent・skill の文書構造、async_cache::AsyncCache は同じキーの読み込み共有とキャンセル、registry は一覧表示を担当します。各ファイルの内容の検証やパス解決は agent・skill 側に残します。
error::Interrupted はキャンセルと実行期限超過を表します。中断を返すときはこの型をエラーチェーンに保持してください。終了コードはエラーの型から決まり、ファイル名やエラーメッセージに含まれる単語には依存しません。
lint はファイル・設定の検査結果を LintRun に集め、テキスト・JSON・GitHub 向けに表示します。検査項目を追加する際は、表示形式ごとに検査処理を追加せず、共通の解析結果に追加します。
storage::write_atomic は cache・cassette・checkpoint の保存を担当します。各書き込みが専用の一時ファイルを作り、完成後に同じディレクトリ内で rename します。同時に保存しても途中の内容を公開せず、一時ファイルの後始末も共通処理が行います。 fsync による電源断時の永続性保証は行いません。
process::run_process はコマンドとシークレット取得で共通のプロセス実行基盤です。出力上限、キャンセル、期限、子プロセスの回収と読み書きタスクの後始末を一か所で管理します。
cancellation は CancellationToken/AtomicBool それぞれの「キャンセル済みか」チェックと、キャンセルが配線されていない呼び出し元向けの never-cancelled sentinel (none()/NEVER_SET) を提供します。file_walk::DirWalker は lait lint/lait test のディレクトリ再帰探索 (決定的な順序・symlink 非追従・ドット始まりエントリの除外・重複排除) を共有し、 sync_cache::SyncCache は template/jq のコンパイル結果キャッシュ (ロック・poison 復帰込み) を共有します。report::note/warn は note:/warning: 接頭辞付きの標準エラー出力を一箇所に集約します。app::load_config/build_run_context は lait chat/prompt run/ agent run が共有するエントリポイントの定型セットアップ (Ctrl-C ハンドラの登録、設定読込、キャッシュポリシー解決、RunContext 構築) です。
workflow の出力は正規化したパスと、実際に開いた通常ファイルの二段階でロックします。 file_lock::ExclusiveLease を切り詰め前に取得し、書き込み完了まで保持することで、別名のハードリンクも直列化します。Unix のファイルロックは advisory であり、同じロックを使わない外部プログラムの書き込みまでは防止しません。

統合テストは tests/support::test_command を使い、実ユーザーのグローバル設定と履歴から隔離します。履歴を複数コマンド間で共有するテストでは、一時ディレクトリを用意して XDG_DATA_HOME を明示的に上書きします。並行処理の変更では、成功時だけでなく、待機中のキャンセル・初期化失敗後の再試行・保存失敗時の後始末も検証してください。

ドキュメントサイト

日本語ドキュメントの正本は docs/usage/ja/ です。文書を変更したら、サイト側の生成コピーを同期してから型チェックを実行します。

cd website
pnpm sync-docs
pnpm types:check

pnpm build は同期と Blume のチェック・リンク検証・ビルドをまとめて実行します。

GitHub Actions でも Rust の検証と pnpm build を実行します。