コンテンツにスキップ

未翻訳のページは英語で開き、英語と表示されます。

このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.

リポジトリガイド

トップレベルの各ディレクトリに何が置かれているか、server/ 内のどこに各関心事があるか、コードを読む順序、そしてこれを守らないとプルリクエストが通らない規約を説明します。

トップレベルの構成

パス 内容
server/ FastAPI サーバー:ドメインパッケージ(メモリ、コード、トラッカーなど)、オペレーションレジストリ、ワーカー、トランスポート、CLI、設定
extractor/ リファレンス抽出サービス(loom_extractor/):形式の検出とドキュメントパーサー。サーバーの外で実行する。イメージ(Dockerfile、ghcr.io/clickhouse/loom-extractor としてリリース)とロック(uv.lock)を含む。ドキュメント抽出を参照
sdk/python/ Python SDK。clickhouse-loom として公開(sdk/python/loom/)
sdk/typescript/ TypeScript SDK。@clickhouse/loom として公開(sdk/typescript/src/)
frontend/ / で配信される React ダッシュボード(Vite + Tailwind)。src/、e2e/ 内の Playwright スペック、scripts/bundle_budget.mjs
schemas/ migrations/(番号付き SQL)、schema.sql(生成された現在のスキーマ)、otel/(ClickStack OTel テーブル)、ops/(手動実行用 SQL)。schemas/README.mdを参照
dev/ compose スタック、運用スクリプト(loom_ingest.py、loom_init.py、onboard_tenant.py、バックアップとリストア、verify_audit_chain.py)、ci_start_clickhouse.sh、redeploy_preflight.sh
deploy/ ClickHouse サーバー設定(clickhouse-config/)、Lemmagen3 モデル(lemmagen3/)、ブルー/グリーンプロキシ(proxy/)、Helm チャート(helm/)、リポジトリジョブのサンドボックス用 AppArmor プロファイル(apparmor/)、スタンドアロン用の env テンプレート(standalone/)、定期的な名前空間コピーの CronJob(okf-sync/)、ダッシュボード(dashboards/、hyperdx_dashboards.md、clickstack_sources.sh)
bench/ ベンチマークのハーネスとゲート、そのフィクスチャ(fixtures/)、データセット、ルーブリック、受け入れ評価とスキル評価。ベンチマークを参照
integrations/ クライアント統合:Claude Code と Codex のプラグイン、Cline のフック、grep shim、Cursor と汎用のトランスクリプトフック、OKF CI ゲート
skills/ スタンドアロンの Agent Skills:loom-code と loom(サーバーイメージに同梱され mentor.guide が返すエージェント向けガイド)
scripts/ codegen/(ジェネレーター)、gates/(CI のラチェットとガード)、ops/(運用ツール)、scip_harness/(コンパイラティアのプロデューサー)、docs_site/(ドキュメントサイトのフック、テーマのオーバーライド、固定されたビルダー、IndexNow への送信)、i18n/(翻訳ジェネレーターとその鮮度チェック)
tests/ unit/、integration/、analyzer/、code_lanes/、fixtures/(後述)
examples/ 実行可能な統合例(claude_agent_loop.py、ledger_run.py、log_conversation.py、onboarding_walkthrough.py)と、教師が自分のリポジトリにコピーするコースのスターター(course-starter/、教育)
i18n/ README、クイックスタート、ユースケースページの機械翻訳。LANGUAGES の言語ごとに 1 フォルダー。scripts/i18n/translate.py(.github/workflows/i18n.yml)で生成され、手動では編集しない
docs/ このドキュメント。mkdocs.yml と scripts/docs_site/ がドキュメントサイトとしてビルドする(.github/workflows/docs-site.yml)
.github/ CI、リリース、スキャンのワークフロー(workflows/)、issue とプルリクエストのテンプレート、social-preview.png(Settings → General → Social preview でアップロードする画像。GitHub はアップロードされたコピーのみを読む)
.devcontainer/ GitHub Codespaces のお試し環境:インストーラーで最新リリースをインストールし Claude Code を接続する dev container。開発環境ではない(クイックスタート)
Dockerfile, Makefile, redeploy.sh, pyproject.toml, uv.lock サーバーのイメージ、タスクランナー、ブルー/グリーンのデプロイスクリプト、サーバーパッケージとそのロックファイル
server.json, context7.json, CITATION.cff, gemini-extension.json, .claude-plugin/, .cursor-plugin/, plugin.json, mcp.json, .agents/plugins/ MCP Registry のリスト、ドキュメントインデックスの設定、GitHub が「Cite this repository」として表示する引用情報、Gemini CLI 拡張のマニフェスト、loom-code スキルのマニフェストを含む Claude Code マーケットプレイス、Cursor のマーケットプレイスとプラグイン、GitHub Copilot CLI がインストールする Agent Plugins パッケージ、Codex マーケットプレイス
llms-install.md コーディングエージェントが Loom をインストールし MCP サーバーとして追加する手順
AGENTS.md, CLAUDE.md すべてのコーディングエージェントが読む指示。CLAUDE.md は AGENTS.md をインポートする
.claude/, .agents/skills/ エージェントのスキル、パス単位のルール、読み取り専用のレビュアーサブエージェントとそのフック、プロジェクトの権限設定。.agents/skills/ は各スキルを Codex 向けにリンクする

server/ の内部

server/ はドメインごとに構成されています。リクエストはトランスポートから入り、オペレーションレジストリによってドメインの app/ にあるハンドラへディスパッチされます。ハンドラは domain/ の純粋なロジックを実行し、そのドメインの SQL を保持する store/ のリポジトリを通じて読み書きします。サーバーのレイアウトには、コントラクトテストが強制する import ルールを含む全体マップがあります。リクエストの経路はシステム概要にあります。

パッケージ / モジュール 役割
memory/, code/, tracker/, knowledge/, erasure/, tasks/, identity/, insights/ ドメインパッケージ。それぞれ最大 5 つのレイヤーを持ちます。api/(ワイヤモデル models*.py と Operation リスト ops*.py)、app/(ハンドラとオーケストレーション)、domain/(純粋なロジック)、store/(ClickHouse リポジトリと行ビルダー。memory/store/rows.py にバージョン行ビルダーがあります)、workers/(バックグラウンドループ)
operations/ レジストリのコア。Operation と Role(base.py)、registry.py(すべてのドメインの op グループを import し、ALL_OPERATIONS と OPERATIONS_BY_NAME を構築します)、toolsets.py、読み取りプロジェクション、リーチ集計
transport/ HTTP(http.py)と MCP(mcp.py および mcp_schemas、mcp_config、mcp_tools、mcp_identity)、引数フィードバック、ボディ制限
workers/ ワーカーレジストリ(registry.py、_WORKERS)と、それを実行するスーパーバイザー(supervisor.py)。各ループはそのドメインの workers/ にあります
settings/ すべての設定を catalog.py に集約。領域ごとに 1 セクションで、Settings に合成されます
auth/ JWT の発行と検証、ロールと権限付与、ログイン、OIDC、セルフサインアップ、失効
embedding/, llm/ 差し替え可能なプロバイダーのインターフェース(OpenAI、Anthropic、Gemini、local、fake)、キャッシュ、フォールバック
observability/ レジャーエミッター、監査ログ、コスト集計と予算、OTel のメトリクスとスパン、/v1/health が報告する problems リスト
clients/ 外部サービス向けの HTTP クライアント(共有プロバイダープール、GitHub)
storage/ テーブルごとの TTL の合成
cli/ loom コマンドツリー(app.py が組み立てます)
main.py, boot.py, health.py, wiring.py FastAPI アプリとそのライフスパン(ワーカー、トランスポート)、起動・シャットダウンの手順(起動時マイグレーション、失効スナップショット)、/v1/health、wire()
core/ch.py ClickHouse クライアント、プーリング、クエリの帰属(set_query_tag)
core/errors.py 型付きエラー(LoomServerError のサブクラス)とその HTTP ステータス
core/ratelimit.py, core/ratelimit_shared.py, core/idempotency.py, memory/app/blacklist_guard.py リクエスト経路のガード
core/schema/ マイグレーションランナー(migrate.py)とコンテナ間ロック(migrate_lease.py)、およびランナーと再構築ツールが共有するスキーマ書き換え(table_rebuild.py、vector_codec_ddl.py)

tests/ の内容

パス 内容
tests/unit/ ClickHouse を必要としない高速なテスト。snapshots/(CLI のツリーとヘルプ、ワーカーレジストリ、SDK の公開 API)、fixtures/、共有ヘルパーを含む
tests/integration/ 実行中のサーバーと ClickHouse に対するテスト(tests/conftest.py と tests/integration/conftest.py が接続を設定する)。プリンシパル間のリークを調べるプローブを含む
tests/analyzer/ ステートメントコーパス。マイグレーション済みの空のテーブルに対して、すべての SQL ビルダーの形を EXPLAIN QUERY TREE で確認する。詳細は README を参照
tests/code_lanes/ SQL とシェルのレーンのコーパス。コードインデックスが tests/fixtures/code_lanes/ から導出する内容を、コミット済みの期待値と比較する
tests/fixtures/ 複数のスイートで共有する入力

各スイートの実行方法、スキップ条件、CI でのゲートについては、テストを参照してください。

新しいコントリビューター向けの読む順序

  1. README と システム概要:製品の外面とシステムの構成。
  2. server/operations/registry.py:すべてのトランスポートが走査するワイヤ op のレジストリ。
  3. server/main.py の lifespan:マイグレーション、ワーカー、トランスポートがどのように接続されるか。
  4. 変更対象に対応する server/<domain>/api/ops*.py の op グループ。続けて server/<domain>/app/ にあるそのハンドラと、ハンドラが呼び出す server/<domain>/store/ のリポジトリ。
  5. 読み書きするテーブルについては schemas/schema.sql。
  6. AGENTS.md と .claude/rules/:規約とその理由。

自明ではない規約

CONTRIBUTING.md に規約の一覧があり、その理由は AGENTS.md と .claude/rules/ 配下のルールに記載されています。次のテストとゲートがこれらの規約を強制します。

ゲート 守られる内容
生成された SDK テーブル、到達範囲の集計(コード生成) op はレジストリの行である
tests/integration/test_cross_principal_leakage.py 組織全体 ID の op は、他者の行を found=False として隠す
test_memory_versions_schema.py loom.memory の列が loom.memory_versions に反映される
test_migrations_additive.py、台帳のチェックサム(マイグレーション) マイグレーションは追加のみで、編集しない
test_every_table_is_classified.py すべてのテーブルが消去に関して分類されている
test_settings_attribute_access.py、test_settings_reference.py 設定は settings.<field> として読み取られ、リファレンスは最新である
test_worker_registry_snapshot.py、test_worker_registry_parity.py ワーカーはレジストリの行である
ruff BLE001 広範な except には理由を記す
scripts/gates/function_length_gate.py どの関数もベースラインを超えて長くならない
tests/unit/test_public_copy.py リポジトリのテキストは製品中立である

基盤となる構造(唯一のエンジンとしての ClickHouse、アイデンティティタプル、行ごとのコンテンツハッシュ監査、5 つの信念改訂操作)については、プルリクエストに設計上の根拠を記載し、対応するアーキテクチャのページを更新する必要があります(重要な変更)。

関連ドキュメント