# pi-lingual

Pi Coding Agent のためのバイリンガル・ターミナル HUD ＆ プロンプト最適化エンジン。

母国語で思考し、コードを書く。入力欄の上にシリコンバレーの自然な口語表現と公式ドキュメント英語をリアルタイム表示。さらにプロンプトを自動で標準的な技術英語へと書き換え、コード・コメント・コミットログの英語品質を一貫して保ちます。

[![npm version](https://img.shields.io/npm/v/pi-lingual?color=blue)](https://www.npmjs.com/package/pi-lingual)
[![npm downloads](https://img.shields.io/npm/dm/pi-lingual?color=22c55e&label=downloads)](https://www.npmjs.com/package/pi-lingual)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/Tests-146%2F146%20Pass%20(100%25)-brightgreen)](tests/engine.test.ts)
[![TypeScript](https://img.shields.io/badge/TypeScript-Strict%20Zero%20Error-blue)](tsconfig.json)

[English](./README.md) | [简体中文](./README_zh.md) | **日本語**

<p align="center">
  <img src="https://raw.githubusercontent.com/3ZEROS12/pi-lingual/main/assets/demo.gif" alt="pi-lingual ターミナル伴走 HUD デモ" width="840">
</p>

```text
  · [原文] このアプローチは少し過剰設計気味なので、素直に標準ライブラリで実装した方が良い
  ┌ [口語] This feels a bit over-engineered; we'd be much better off sticking with the standard library.
  │        (少し過剰設計な気がします。標準ライブラリを使う方がずっと自然です)
  ├ [文書] The proposed approach introduces unnecessary complexity. Leveraging native standard library implementations is preferred.
  │        (提案されたアプローチは不要な複雑性を招くため、標準ライブラリの実装を採用することが推奨されます)
  └ [重要] over-engineered (過剰設計の) · be better off (〜した方が良い) · stick with (〜を使い続ける) · leverage (活用する)
```

## クイックスタート

Pi ターミナルから直接インストールできます：

```bash
pi install npm:pi-lingual
```

インストール後すぐに使用可能。セッション起動時に OS の言語環境（`ja ⇄ en` や `zh ⇄ en`）を自動検出し、初回起動時の対話プロンプトなしで起動します。現在のセッション認証情報をそのまま活用するため、追加の API キー設定は不要です。

> 💡 **推奨ターミナルモード**:  
> 伴走学習と過去ログの確認には、`~/.pi/agent/settings.json` で `"tuiMode": "regular"` を設定することをおすすめします。翻訳カードと語彙学習履歴が会話ストリームとともに自然にスクロールし、いつでも過去の表現を振り返ることができます。
>
> ⚡ **レイテンシ特性**: デフォルトの伴走モード（Companion）では、プロンプトは遅延 0ms でコーディングエージェントに直接パススルーされます。書き換えモード（`direct` や `live-flow`）では、モデルの応答速度に応じた単一のリクエストでプロンプトを変換します。

---

## 開発者が直面する 4 つの課題を解決

ターミナル AI コーディングエージェントを日常的に使う中で生じる、以下の摩擦を解消します：

### 1. チームや OSS リポジトリで求められる英語の統一
グローバルなオープンソースや英語ベースのチームでは、コード内コメント、コミットメッセージ、PR の説明文はすべて英語で記述する必要があります。
母国語で AI に指示を出すと、生成されるコードのコメントや解説まで母国語になってしまい、プッシュ前に手動で修正する手間が発生します。
仕様変換モード（`direct` / `lazy`）を使えば、日本語で普段通りに思考・入力するだけで、`pi-lingual` が指示を正確な技術英語へと自動整形してからエージェントに渡します。**生成されるコード、コメント、ドキュメントは最初から美しい英語に統一されます。**

### 2. コード生成中の 5 秒間を活用する伴走学習
Enter キーを押した後、LLM がコードを生成するまでには通常 5〜15 秒ほどの待機時間があります。
ブラウザを開くには短すぎ、何もしないには手持ち無沙汰な時間です。
`pi-lingual` は入力欄のすぐ上に、認知負荷の低い視覚的カードを表示します。生成を待つわずかな合間に、同じ思考が日米の開発現場（Slack やスタンドアップ）でどう口語表現され、設計書や PR でどうフォーマルに書かれるのかを自然とインプットできます。

### 3. 会話コンテキストを汚さない（余計なトークン消費ゼロ）
一般的な翻訳拡張機能は、プロンプトの末尾に英訳を結合してエージェントに送ります。
会話ターンが重なるにつれて重複したテキストが履歴に蓄積し、コンテキスト枠を圧迫してモデルの推論精度を鈍らせてしまいます。
`pi-lingual` はエージェントの会話履歴の外側で動作する独立した TUI オーバーレイです。**プロンプト履歴は 100% クリーンな状態を保ち、無駄なトークンを一切消費しません。**

### 4. 枠崩れのない堅牢なターミナルレイアウト
全角文字（日本語や漢字）はターミナル上で 2 カラム分の表示幅を占有します。
従来の四角いボックス枠（`│ ... │`）は文字幅の計算ズレで枠線がちぎれ、行ズレやカーソルの乱れを引き起こします。
`pi-lingual` は閉じた外枠を廃止し、Unicode UAX #11 に準拠したオープンな左レールツリー構造（`· ┌ ├ └`）を採用。幅の狭い分割ペインでもレイアウトが破綻しません。

---

## 3 つのコア動作モード

| モード番号・識別子 | 実行動作 | HUD 表示 | ユースケース |
| :--- | :--- | :--- | :--- |
| **[1] 伴走モード (`companion`)** | 0ms 原文パススルー | 開放型ツリー伴走カード | 日本語で素早く思考しながら、裏で自然な口語・文書表現をストックする（デフォルト） |
| **[2] 仕様変換 (`direct`)** | プロンプト自動英語化 | 1 行コンパクト表示 | 日本語の雑なメモを、エージェントが最も誤解なく動く厳密な技術英語指示に変換 |
| **[3] ライブ校正 (`live-flow`)** | 英語プロンプトの誤脱修正 | 修正前後の差分カード | 自分で書いた英語プロンプトの前置詞・語順・構文ミスを自動修復 |
| **[0] オフ (`off`)** | 完全スルー | 非表示 | 0 ピクセル、0 リスナー、0 トークン消費 |

---

## 2 層の操作モデル：日常のシンプルさ ＋ AI による自動設定

「日常の操作は 5 秒で覚えられ、細かなカスタマイズは AI エージェントに任せる」という設計思想を徹底しています。

### 1. 第 1 層：日常の操作（覚えるコマンドは実質 1 つ）
* **モード切替**: `/lingual`（または短縮エイリアス `/l`）と入力すると、インタラクティブなカプセル選択画面が表示されます。数字キー `1` / `2` / `3` / `0` を押すだけで、Enter キーなしで即座に切り替わります（`/lingual 1` など直接指定も可能）。
* **言語切替**: `/lang ja` や `/lingual lang ja` で、翻訳先の言語を即座に変更できます。
* **スマートバイパス**: 母国語を入力すれば伴走カードが展開され、純粋な英語（英数字・記号のみ）を入力した場合は 0ms でエージェントへ直接パススルーされます。

### 2. 第 2 層：AI スキルを通じた自然言語カスタマイズ
カスタム設定を行いたい場合も、**設定ファイルを直接編集する必要はありません。Pi エージェントに普段の言葉で指示するだけです**。内蔵の `lingual-tuner` スキルが意図を理解し、設定を安全に更新します：
* *「コミットメッセージ専用のモードを追加して」* ➔ Conventional Commits に準拠した設定を自動構成
* *「伴走カードの高さを抑えて、1 行のコンパクト表示にして」* ➔ `compact` レイアウトへ自動変更
* *「解説言語を日本語から英語に変えて」* ➔ 言語ペアと認知補助言語を自動調整

---

## ダブルクリック検索：履歴の中で引く辞書

全画面モードで単語をダブルクリック（またはドラッグ選択）すると、コピーはそのままに行われ、入カエリアの上に伴走カードとは逆方向の検索カードが現れます（**外国語 → 母語**）。言語ペアは `/lang` の設定をそのまま使うため、別の設定は不要です。

```text
  · [検索] over-engineered
  ┌ 過剰設計；実際に必要な以上に複雑な設計を指すこともある
  └ クリックで閉じる · 12s
```

- **既定はキー不要の Google 辞書**：単語検索は数百ミリ秒で返り、モデルの消費はゼロです。`/lingual lookup model` でモデル経路（`/lingual model` のサイドカーモデル）に切り替えられます。
- **検索に適した選択だけ反応**：コードブロック全体、パス、URL、シェルコマンド、母語の文は反応しません。粒度は `maxWords` / `maxChars` で調整できます。
- **入力フォーカスを奪わない**：カードは non-capturing のオーバーレイなので、タイピングはそのままエディタに入ります。クリックかタイムアウトで消えます。
- **全画面モード限定**：regular モードでは端末が選択を所有するため、`/lingual lookup <テキスト>` を利用してください。
- **無効化**：`/lingual lookup off`（リスナーもリクエストもゼロ）。

---

## デイリー Markdown ジャーナル：学習の振り返りと蓄積

ターミナルがスクロールされても、伴走カードを見失うことはありません。`pi-lingual` は追加のモデル呼び出しなしで、生成された伴走カードを日別の Markdown ノート（`~/lingual-log/YYYY-MM-DD.md`）へ自動記録します。

- **いつでも有効化**：環境変数 `LINGUAL_LOG=1` を設定するか、Pi 内で `/lingual log on` を実行。
- **モデル呼び出しゼロ**：そのターンの翻訳結果とローカライズされたスロット名（`[原文]`、`[口語]`、`[書面語]`、`[重要表現]`）から直接追記。
- **日別自動重複排除**：同日内の同一プロンプトは 1 回のみ記録され、ノートをすっきり保ちます。
- **保存先の変更**：`LINGUAL_LOG_DIR=/path/to/notes` または `/lingual log dir <path>` で指定可能。

---

---

## 整理されたコマンド構成（単一スーパーコマンド `/lingual` ＆ `/l`）

Pi の `/` コマンドメニューを汚さないよう、登録されるトップレベルコマンドは `/lingual`（および超短縮エイリアス `/l`）と `/lang` のみに絞り込まれています：

| コマンド | 引数・サブコマンド | 説明 |
| :--- | :--- | :--- |
| **`/lingual`** / **`/l`** | *(引数なし)* | カプセル選択 UI を開く（`1`/`2`/`3`/`0`、矢印キー、`Esc` でキャンセル） |
| ↳ 直接切替 | `/lingual 1` \| `2` \| `3` \| `0` | モード番号または ID（`companion`, `direct`, `live-flow`, `off`）で直接切替 |
| ↳ オン／オフ | `/lingual on` \| `off` | 伴走モードの即時有効化または完全オフ（0 ピクセル、0 トークン） |
| ↳ 言語ペア | `/lingual lang [pair]` または `/lang` | 翻訳方向の切替（例：`/lang ja`, `/lingual lang ja en`） |
| ↳ 再表示 | `/lingual last` \| `replay` | 直前に生成された伴走カードや差分カードを再表示 |
| ↳ 単語検索 | `/lingual lookup [on\|off\|google\|model\|status\|<テキスト>]` | 全画面で単語をダブルクリックすると外国語→母語の検索カードを表示（既定は Google、モデル経路も可） |
| ↳ デイリー手帳 | `/lingual log [on\|off\|status\|dir <パス>]` | 伴走カードを日別 Markdown 手帳（`~/lingual-log/YYYY-MM-DD.md`）へ追記 |
| ↳ レイアウト | `/lingual compact` | 1 行カプセル表示と開放型ツリー HUD のトグル切替 |
| ↳ モードロック | `/lingual lock` \| `unlock` | 現在の動作モードを固定し、外部スクリプト等による予期せぬ変動を防止 |
| ↳ 推論深度 | `/lingual reasoning [low\|medium\|high]` | モードごとの推論思考レベルを設定（日常は `low`、仕様策定は `medium`） |
| ↳ 設定チューナー | `/lingual tuner [要求]` | 自然言語によるプロンプト設計ウィザードを起動 |
| ↳ 状態診断 | `/lingual status` | キャッシュヒット率や現在の動作状態を表示 |

*キーボードショートカット：`Alt+.`（次の候補）、`Alt+,`（前の候補）。スタンドアロン CLI：`lingual "prompt"`。*

---

## 動的スロットアーキテクチャ（表示項目の自由な組み換え）

伴走カードに表示される各スロットは完全にモジュール化されており、自由に増減・並び替えが可能です：

- **原文の行を非表示にする**:  
  `/lingual slots rm source` を実行すると、原文行が非表示になり、翻訳結果のみがスマートに表示されます。
- **好みのトーンやカスタムスロットを追加する**:  
  `/lingual slots add twitter Tweet 280文字以内の洗練されたツイート` のように追加すると、プロンプトのスキーマと HUD レイアウトがリアルタイムに追従します。
- **一時的なミュートと初期化**:  
  `/lingual slots toggle <id>` で一時的にスロットを非表示にし、`/lingual slots reset` でいつでも初期状態に戻せます。

---

## 専用モデルとプライバシー配慮

### 推論深度の動的調整 (`/lingual reasoning`)
`pi-lingual` では、用途に応じてモデルを切り替える代わりに、モードごとの推論深度（Reasoning Effort）を調整できます：
```bash
/lingual reasoning low       # 応答速度を最優先（日常の仕様書き換えや校正向け）
/lingual reasoning medium    # 思考の深さを重視（複雑な仕様書へのブレインダンプ展開向け）
/lingual reasoning high      # 厳密な多重制約プロンプト向け
```

### 上位モデルのトークン枠を保護する
高推論モデルで作業している際、伴走翻訳の処理を軽量モデルにオフロードして枠を節約できます：
```bash
/lingual model <軽量モデルID>    # 伴走処理のみ特定モデルに委譲
/lingual model auto              # メインセッションのモデルに追従
```

ローカルの Ollama や OpenAI 互換エンドポイントも `~/.pi/agent/lingual.json` から設定可能です：
```json
{
  "endpoint": "http://127.0.0.1:11434/v1/chat/completions",
  "model": "qwen2.5:3b"
}
```

> 🔒 **プライバシーの保証**: `pi-lingual` は外部依存ゼロ（`dependencies: {}`）で設計されており、テレメトリや外部収集サーバーは一切存在しません。リクエストはお手元の認証済みモデルエンドポイントのみに送信されます。

---

## 開発者のノート

翻訳モデルのシステムプロンプトは現在デフォルトで調整済みですが、`/lingual tuner` コマンドや内蔵の `lingual-tuner` スキルを使って、いつでもご自身の好みに合わせてカスタマイズできます。

単なる設定の変更にとどまらず、ご自身が本当に欲しい出力スタイルをぜひ考えてみてください：
* **重要語句の分解はどの程度の細かさが心地よいか？**
* **文法やエンジニアリング背景の補足説明は必要か？**
* **一度に目にする重要表現は、何個くらいが認知負荷として適切か？**

これらを自分に合わせてチューニングすることで、はじめて最高の効果が得られます。日常のコーディングで Enter を押し、AI がコードを生成するまでの数秒間、入力欄の上にふと目を向けてみてください。

このプロジェクトを着想した背景には、従来の辞書引きや単語帳アプリに対する個人的な挫折がありました。基礎的な単語はすでに知っており、難解な語彙は文脈のない辞書をいくら眺めても身につかないというジレンマです。実際に言葉を身につけ、使えるようになるために必要なのは、現実の開発現場の文脈に即した自然なフレーズと生きたコロケーションです。

自分にとって最も心地よいプロンプトを整え、コード生成の合間の時間を味方につけて、無理なく続けていただければ幸いです。

---

## 品質検証とテスト

```bash
npm run typecheck   # TypeScript 厳格型チェック (0 エラー)
npm test            # 全自動単体テスト (146/146 全件パス)
npm run build       # 多重エントリビルド (拡張機能 + コアエンジン)

---

## エコシステム：Pi ターミナル＆デスクトップ連携

各拡張機能は互いに干渉しない独立したスロット（`aboveEditor`、`belowEditor`、ステータスバー、Windows デスクトップ）で動作します：

| パッケージ | 動作環境・スロット | 役割とメカニズム | インストール / リンク |
| :--- | :--- | :--- | :--- |
| **[`pi-lingual`](https://github.com/3ZEROS12/pi-lingual)** *(本拡張)* | ターミナル `aboveEditor` HUD | デュアルレジスター伴走カード（≤9 行、UAX #11 ツリー）＆ 0 トークン仕様変換 | `pi install npm:pi-lingual` |
| **[`lingual-desktop`](https://github.com/3ZEROS12/lingual-desktop)** | Windows デスクトップ Dynamic Island | 低レベルキーボードフック（`WH_KEYBOARD_LL`）、原位 3 秒カード ＆ システム全体入力ブリッジ | [GitHub Release](https://github.com/3ZEROS12/lingual-desktop/releases) |
| **[`toolflow`](https://github.com/3ZEROS12/toolflow)** | ターミナルツールサンドボックス | 段階的ツールマウント ＆ 40 行超ログの自動脱水（コンテキスト消費 -95%） | `pi install npm:toolflow` |
| **[`pi-tui-status-beautifier`](https://github.com/3ZEROS12/pi-tui-status-beautifier)** | ターミナルフッターステータスバー | 6 種のプリセットバッジ、80 桁未満の自動折りたたみ、ディスク I/O ゼロ | `pi install npm:pi-tui-status-beautifier` |
| **[`pi-anchor`](https://github.com/3ZEROS12/anchor)** | ターミナル `belowEditor` ドック | 1 行常駐付箋、0ms `pin:` 割り込み、進捗バー ＆ セッション復帰 | `pi install npm:pi-anchor` |

---

## ライセンス

MIT © [Jason Song](https://github.com/3ZEROS12)
