Scripts

EpisodicRAGプラグインのPython実装リファレンス

Overview
Architecture
Layers
Shell Scripts
Tests
See Also

Overview

対象	用途
ユーザー	CLIコマンド（`python -m interfaces.digest_*`）またはスキル経由で使用
開発者	各層のモジュールを直接インポートして拡張

📖 使い方: QUICKSTART.md / 技術仕様: ARCHITECTURE.md

Architecture (Clean Architecture)

v2.0.0 より、Clean Architecture（4層構造）を採用しています。

📖 詳細仕様（層構造・依存関係ルール・推奨インポートパス）: ARCHITECTURE.md

scripts/
├── domain/           # コアビジネスロジック（最内層）
│   └── config/       # 設定定数・バリデーション
├── infrastructure/   # 外部関心事（I/O、ロギング）
│   └── config/       # 設定ファイルI/O・パス解決
├── application/      # ユースケース
│   └── config/       # DigestConfig（Facade）
├── interfaces/       # エントリーポイント
├── tools/            # 開発ツール
│   ├── check_footer.py    # フッターチェック
│   ├── link_checker.py    # リンク検証
│   └── validate_json.py   # JSON検証
└── test/             # テスト

依存関係ルール

domain/           ← 何にも依存しない（純粋なビジネスロジック）
    ↑
infrastructure/   ← domain/ のみ
    ↑
application/      ← domain/ + infrastructure/
    ↑
interfaces/       ← application/

Note: v4.0.0より、設定管理機能（config）は各層のサブディレクトリに分散配置されています。詳細: ARCHITECTURE.md

Layers

domain/ - 定数・型・例外

Module	Purpose
`version.py`	バージョン定数（`__version__`, `DIGEST_FORMAT_VERSION`）
`constants.py`	`LEVEL_CONFIG`, `PLACEHOLDER_*`, `DEFAULT_THRESHOLDS`
`exceptions.py`	カスタム例外（`EpisodicRAGError`, `ValidationError`, etc.）
`protocols.py`	Protocol定義（型ヒント用インターフェース）
`types/`	TypedDict定義パッケージ（`BaseMetadata`, `DigestMetadata`, Literal型等）(v4.1.0+パッケージ化)
`validators/`	バリデーションパッケージ（`digest_validators`, `runtime_checks`, `helpers`, `type_validators`）
`file_naming.py`	ファイル命名ユーティリティ（`extract_file_number()`, `format_digest_number()`）
`file_constants.py`	ファイル関連定数
`validation.py`	バリデーションロジック
`validation_helpers.py`	バリデーションヘルパー関数
`text_utils.py`	テキスト処理ユーティリティ
`level_metadata.py`	レベルメタデータ定義
`level_behaviors.py`	レベル固有振る舞い定義
`level_registry.py`	レベル固有振る舞いのRegistry（Strategy Pattern）
`error_formatter/`	エラーメッセージの標準化パッケージ（`CompositeErrorFormatter`, `FormatterRegistry`）

from domain import LEVEL_CONFIG, __version__, ValidationError
from domain.file_naming import extract_file_number, format_digest_number
from domain.level_registry import get_level_registry
from domain.validators import digest_validators, runtime_checks

infrastructure/ - 外部I/O

Module	Purpose
`json_repository/`	JSON操作パッケージ（`load_json`, `save_json`, `ChainedLoader`）
`file_scanner.py`	ファイルスキャン（`scan_files`, `get_max_numbered_file`）
`logging_config.py`	ロギング設定（`log_info`, `log_warning`, `log_error`）
`structured_logging.py`	構造化ロギング
`error_handling.py`	エラーハンドリングユーティリティ
`user_interaction.py`	ユーザー確認プロンプト（`get_default_confirm_callback`）

from infrastructure import load_json, save_json, log_info, log_error
from infrastructure.file_scanner import scan_files, get_max_numbered_file
from infrastructure.user_interaction import get_default_confirm_callback
from infrastructure.error_handling import handle_error

application/ - ビジネスロジック

Package	Purpose
`validators.py`	バリデーション関数（`validate_dict`, `is_valid_list`）
`tracking/`	時間追跡（`DigestTimesTracker`）
`shadow/`	Shadow管理（`ShadowTemplate`, `ShadowUpdater`, `ShadowIO`, `FileDetector`, `CascadeProcessor`, `CascadeOrchestrator` (v4.1.0+), `CascadeComponents` (v5.2.0+), `FileAppender`, `PlaceholderManager`, `ProvisionalAppender`）
`grand/`	GrandDigest管理（`GrandDigestManager`, `ShadowGrandDigestManager`）
`finalize/`	Finalize処理（`ShadowValidator`, `ProvisionalLoader`, `RegularDigestBuilder`, `DigestPersistence`）

from application.shadow import ShadowTemplate, ShadowUpdater
from application.grand import GrandDigestManager, ShadowGrandDigestManager
from application.finalize import RegularDigestBuilder, DigestPersistence
from domain.validators import validate_type, is_valid_dict, is_valid_list

interfaces/ - エントリーポイント

Module	Class	Purpose
`finalize_from_shadow.py`	`DigestFinalizerFromShadow`	メインエントリーポイント
`save_provisional_digest.py`	`ProvisionalDigestSaver`	Provisional保存
`digest_setup.py`	-	初期セットアップCLI (`python -m interfaces.digest_setup`)
`digest_config.py`	-	設定変更CLI (`python -m interfaces.digest_config`)
`digest_auto/`	-	健全性診断CLIパッケージ (`python -m interfaces.digest_auto`) (v5.2.0+パッケージ化)
`auto_dream_scan.py`	-	auto-memory 所在スキャンCLI（足す dream＝`/digest` Step 11）
`dream_defrag.py`	-	dream-defrag CLI（引く dream＝GC、`scan`/`snapshot`/`rebuild-index`）(v5.6.0+)
`shadow_state_checker.py`	-	Shadow状態チェッカー
`config_cli.py`	-	設定CLIエントリーポイント
`interface_helpers.py`	-	ヘルパー関数（`sanitize_filename`, `get_next_digest_number`）
`cli_helpers.py`	-	CLI共通ヘルパー（`output_json`, `output_error`）(v4.1.0+)
`digest_entry.py`	-	Digestエントリーポイント
`digest_readiness.py`	-	Digest準備状態チェック
`update_digest_times.py`	-	Digestタイムスタンプ更新
`update_shadow_overall.py`	`OverallDigestUpdater`	SGD overall_digest 4要素の更新（source_files 不変）
`add_shadow_sources.py`	`ShadowSourceAdder`	SGD source_files へのファイル名追加（冪等。既存分析は保持、PLACEHOLDER は件数で更新）(v5.10.0+)
`provisional/`	-	Provisionalマージ処理（`file_manager`, `input_loader`, `merger`, `validator`）

from interfaces import DigestFinalizerFromShadow, ProvisionalDigestSaver
from interfaces.interface_helpers import sanitize_filename, get_next_digest_number
from interfaces.provisional import ProvisionalMerger

設定管理（各層のconfig/）

v4.0.0より、設定管理機能は各層のサブディレクトリに分散配置されています。

層	Package	Purpose
domain	`domain/config/`	設定定数（`REQUIRED_CONFIG_KEYS`, `THRESHOLD_KEYS`）、バリデーションヘルパー
infrastructure	`infrastructure/config/`	設定ファイルI/O（`ConfigLoader`, `ConfigRepository`）、パス解決（`PathResolver`）、永続化パス（`get_persistent_config_dir`）
application	`application/config/`	DigestConfig（Facade）、サービスクラス（`ConfigValidator`, `LevelPathService`, `ThresholdProvider`）

# アプリケーション層のFacade経由で使用（推奨）
from application.config import DigestConfig

config = DigestConfig()
print(config.loops_path)
print(config.get_threshold("weekly"))

# 永続化パス取得（v5.2.0+）
from infrastructure.config import get_persistent_config_dir, get_config_path

config_dir = get_persistent_config_dir()   # ~/.claude/plugins/.episodicrag/
config_file = get_config_path()            # ~/.claude/plugins/.episodicrag/config.json

# 層別に直接使用する場合
from domain.config import REQUIRED_CONFIG_KEYS
from infrastructure.config import ConfigLoader
from application.config import ThresholdProvider

Shell Scripts

Note: シェルスクリプトは廃止されました。Python CLI を使用してください。

セットアップ: python -m interfaces.digest_setup

Digest生成: /digest コマンド（commands/digest.md 参照）

Tests

test/ ディレクトリにユニットテストがあります。

📊 最新のテスト数は CI バッジを参照してください。バッジの件数は CI メイン job の選択分（-m "not slow and not performance"）です——壁時計テストは専用の performance job で実行されるため、この数には含まれません（→ TESTING.md）。

テストディレクトリ構造

test/
├── conftest.py              # 共通フィクスチャ
├── test_constants.py        # 定数テスト
├── test_helpers.py          # ヘルパーテスト
├── TESTING.md               # テスト方針ドキュメント
├── domain_tests/            # domain層テスト
├── infrastructure_tests/    # infrastructure層テスト
├── application_tests/       # application層テスト
├── interfaces_tests/        # interfaces層テスト
├── config_tests/            # config層テスト（v4.0.0+）
├── cli_integration_tests/   # CLI統合テスト（v4.0.0+）
├── integration_tests/       # 統合テスト
├── performance_tests/       # パフォーマンステスト
└── tools_tests/             # 開発ツールテスト（v4.1.0+）

テスト実行

# 全テスト実行（ローカルの既定。壁時計テストも含む）
cd scripts
python -m pytest test/ -v

# 層別テスト実行
python -m pytest test/domain_tests/ -v
python -m pytest test/application_tests/ -v
python -m pytest test/integration_tests/ -v

# CI メイン job の再現（決定論ゲート。slow / performance を除外）
python -m pytest test/ -m "not slow and not performance"

# CI performance job の再現（壁時計テストのみ）
python -m pytest test/ -m "slow or performance" --no-cov

# 層別インポート確認
python -c "from domain import LEVEL_CONFIG, __version__; print(__version__)"
python -c "from infrastructure import load_json, log_info; print('OK')"
python -c "from application import ShadowGrandDigestManager; print('OK')"
python -c "from interfaces import DigestFinalizerFromShadow; print('OK')"

Navigation Menu

Scripts

Table of Contents

Overview

Architecture (Clean Architecture)

依存関係ルール

Layers

domain/ - 定数・型・例外

infrastructure/ - 外部I/O

application/ - ビジネスロジック

interfaces/ - エントリーポイント

設定管理（各層のconfig/）

Shell Scripts

Tests

テストディレクトリ構造

テスト実行

See Also

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Scripts

Table of Contents

Overview

Architecture (Clean Architecture)

依存関係ルール

Layers

domain/ - 定数・型・例外

infrastructure/ - 外部I/O

application/ - ビジネスロジック

interfaces/ - エントリーポイント

設定管理（各層のconfig/）

Shell Scripts

Tests

テストディレクトリ構造

テスト実行

See Also