trvs-lab/eudic-to-anki-skills

Eudic Anki パイプライン（統合スキル）

対象読者

このファイルは実行エージェント向けです。ユーザーは自然言語で目標を伝え、エージェントがエンドツーエンドで実行します。

配布

このスキルはソースリポジトリの skills/eudic-to-anki/ 配下にあり、Vercel Skills CLI（npx skills add <owner>/<repo> --skill eudic-to-anki）でインストールできます。インストール後は、このディレクトリ（SKILL.md がある場所）を以下のすべてのコマンドのカレントワーキングディレクトリ（cwd）として扱ってください。正確なインストールコマンドは、リポジトリがGitHub上で公開された後、リポジトリルートの README.md を参照してください。

スコープ

単一のスキルですが、内部はモジュール化されています：

• エクスポートモジュール: modules/export/README.md
• コーチモジュール: modules/coach/README.md
• インポートモジュール: modules/import/README.md
• 音声モジュール: modules/audio/README.md
• ワークフロープレイブック: workflows/*.md

以下のコマンドはすべて、cwdがこのスキルルート eudic-to-anki/ であることを前提としています。

デフォルト値

• 日付: ユーザーが範囲を指定しない限り、昨日（ローカルタイムゾーン）
• ソース: ユーザーがカテゴリを指定しない限り、すべてのEudicカテゴリ
• デッキ: ユーザーが指定しない限り words
• ノートタイプ: TRVS-Lab
• 中間成果物: ユーザー専用のDocuments成果物ディレクトリのみ。<ABS_TEMP_DIR> のような正規の絶対パス形式（例：/Users/alice/Documents/eudic-to-anki-temp）を使用します。
• ローカルテスト/カスタムセットアップ用のオプション上書き: EUDIC_TO_ANKI_TEMP_DIR=/path/to/temp
• ルールに影響を受ける実行では、成果物パスを /Users/alice/Documents/eudic-to-anki-temp のような絶対ディレクトリに展開してください。~ や $HOME で実行しないでください。

実行規則

以下、<ABS_TEMP_DIR> はユーザーの展開された成果物ディレクトリ（例：/Users/alice/Documents/eudic-to-anki-temp）を意味します。

• ルール対象のコマンドは、直接のargvコマンドとしてのみ実行してください。
• /bin/zsh -lc ...、zsh -lc ...、bash -lc ...、env ...、FOO=bar ... でラップしないでください。
• ルール対象のコマンドの前に &&、||、;、パイプ、サブシェルでチェーンしないでください。準備とメインコマンドは別々のツール呼び出しとして実行してください。
• cwdがこのスキルルートの場合は、python3 scripts/eudic_export.py ... のような相対スクリプトパスを使用します。
• cwdが別の場所にある場合は、python3 /Users/alice/.agents/skills/eudic-to-anki/scripts/eudic_export.py ... のような絶対インストール済みスキルパスを使用します。
• トークンの読み込みにログインzshが必要な場合、直接 python3 scripts/run_with_login_zsh.py python3 scripts/eudic_export.py ... を呼び出してください。その上に別のシェルラッパーを追加しないでください。
• <ABS_TEMP_DIR> が存在しない場合は、最初に別の直接コマンド mkdir -p /Users/alice/Documents/eudic-to-anki-temp で作成してください。

クイックスタート（エージェントフロー）

1. テンプディレクトリが存在することを確認：
   • mkdir -p <ABS_TEMP_DIR>
2. 環境チェック：
   • bash scripts/check_env.sh
3. 単語をエクスポート：
   • python3 scripts/eudic_export.py --all-categories --start-date <D> --end-date <D> --format csv --output <ABS_TEMP_DIR>/_day_<D>_export.csv
4. プレースホルダー + 作成者コーチを構築：
   • python3 scripts/build_dia_json_from_csv.py --csv <ABS_TEMP_DIR>/_day_<D>_export.csv --output <ABS_TEMP_DIR>/_day_<D>_partial.json --batch-date <D> --eudic-words-only
   • エージェントが洗練されたコーチJSONを作成します。各ノートには part_of_speech を含め、すべての meaning 行は n.、vt.、vi.、adj.、adv. などのPOSマーカーで始まる必要があります。その後、マージします（単一ファイル、またはバッチと scripts/merge_coach_with_partial.py を使用）。
5. バリデーション：
   • python3 scripts/validate_trvs_coach_json.py <ABS_TEMP_DIR>/_day_<D>_import.json
6. 音声付きでインポート（インポート成功時、デフォルトでAnki同期が実行されます。スキップする場合は --no-sync を使用）：
   • python3 scripts/ankiconnect_import.py --input <ABS_TEMP_DIR>/_day_<D>_import.json --deck words --create-deck --dia-upsert --audio-provider command --audio-format mp3 --audio-command 'python3 scripts/edge_tts_runner.py --text "{word}" --output "{output}"'
   • --audio-command はargvとして解析され、シェルなしで実行されます。パイプやリダイレクトなどのシェル演算子はサポートされていません。
7. 成功後のクリーンアップ：
   • bash scripts/cleanup_import_artifacts.sh

品質ゲート

• エージェントがコーチコンテンツを作成します。デフォルトでEudicの exp/phon をコーチフィールドに一括コピーしないでください。
• コーチJSONはPOSを明示的に保持する必要があります。各ノートに part_of_speech を含め、各中国語 meaning 行の先頭にPOSマーカーを維持してください。
• 大量のリストの場合は、バッチ化されたサブエージェントを使用し、マージ前に各バッチをバリデーションしてください。
• サブエージェントの出力がbase64の場合、以下でデコードします：
  • python3 scripts/decode_subagent_transcript_b64.py <subagent.jsonl> -o <ABS_TEMP_DIR>/coach_batch_01.json
• バリデータエラー（U+FFFD、mojibakeマーカー、フィールドタイプの誤り、meaning 内のPOSマーカー欠落、または part_of_speech 欠落）がある場合はインポートをブロックします。
• インポート成功後、ankiconnect_import.py はデフォルトでAnki同期を実行します。スキップするには --no-sync を渡します。
• バリデーションが失敗した場合（特に root 形式）、失敗したバッチ/単語のみを再生成し、マージ/インポートの前にバリデータを再実行してください。

プレイブック

• 昨日のフロー: workflows/yesterday.md
• 日付範囲のフロー: workflows/date-range.md
• ユーザー単語リストのフロー: workflows/word-list.md

安全性

• トークン値を追跡ファイルに保存しないでください。
• 環境変数 EUDIC_TOKEN を優先してください。
• AnkiConnectが利用できない場合は、停止してセットアップ手順を提供してください。