理脈 limai

理華と理月の共有神経システム——キャラクターから第一原理で抽出した独立した器官。

第一原理による導出

破棄したもの：キャラクターの LLM タスクプロンプト（人格は移植しない）、メモリの JS eval トリガー（安全性）。 残した本質：重み付きランダムスケジューリングの思想→ハートビートバックオフ；STALE_READ ガード；SSRF 対策；有界読み取り。

起動

npm install
npm run start          # ① stdio → Claude Desktop / Cursor 等本地客戶端
npm run serve:http     # ② HTTP MCP → GPT 客戶端 / 區網 / 遠端
npm run tick           # ③ 手動跑一次心跳（驗證感知層）

CLI は AI エージェント向けに設計されている

limai shot                       # → {"file":...,"width":1920,"height":1080,"bytes":...}
limai win                        # → {"foreground":...,"windows":[{process,title},…]}
limai clip [--json]              # 剪貼簿原文走 stdout（利於管線）
limai tick                       # 心跳一次，生命徵象 JSON
limai web search <q>             # → [{title,url,snippet},…]
limai web fetch <url>            # 正文走 stdout、中繼 stderr；--json 得全包裝
limai fs ls|read|write|edit|find|grep …
limai mem … / limai todo …       # 同前

Agent 契約：

• 出力はデフォルトで JSON、エラー情報は stderr に接頭辞付きメッセージ（STALE_READ: …）として出力し、実行終了コードの非ゼロで失敗を表す

• fs edit の厳密な契約は MCP と同じ：先に fs read を実行すること。観測状態は fs-state.json に永続化され、「read プロセス → edit プロセス」は呼び出しをまたいで成立し、外部による変更が必ず遮断される（--force で回避可能）

• 成功した fs write も観測を構築するため、そのまま edit へつなげられる（o-pi の「成功した write の直後」ルールと同じ）

アーキテクチャ上、MCP はあくまでコアモジュールの上に立つひとつのインターフェースである。同じ vision/web/filesys/memory/todo/heartbeat を CLI サブコマンドと MCP ツールの両方から呼び出せ、両インターフェースは同じデータと同じ安全契約を共有する。`

初回実行時は自動的に ~/.limai/（config.json・memory.json・todo.json・vitals.*・screenshots/）を作成し、token を出力する。

クライアントの接続方法

ローカル（stdio）

// claude_desktop_config.json
{ "mcpServers": { "limai": { "command": "node", "args": ["F:\\fount開發項目\\理脈\\src\\cli.mjs", "serve", "--stdio"] } } }

同一 LAN／同一マシンの GPT クライアント（Cherry Studio、LobeChat、OpenWebUI…）

node src/cli.mjs serve --http                # 預設 127.0.0.1:8931
# 對區網開放：--host 0.0.0.0 --token <強密碼>

{ "type": "http", "url": "http://192.168.x.x:8931/mcp",
  "headers": { "Authorization": "Bearer <token>" } }

クラウド ChatGPT（Connectors／開発者モード）

ChatGPT からはあなたの localhost に届かないため、公網 HTTPS が必要になる——一行のトンネル：

cloudflared tunnel --url http://127.0.0.1:8931
# → https://xxxx.trycloudflare.com

接続 URL には https://xxxx.trycloudflare.com/mcp?token=ヒト を入れる（GPT 系クライアントは header を勝手に決められないことが多いため、query で token を渡す）。長期的な解：Tailscale Funnel（ポートで外部に開けなくてよい）あるいは Caddy で自サイトドメインをリバースプロキシする。

セキュリティ境界

• ファイル：config.json の allowedRoots に閉じ込める；.git は無期限にブロック；fs_edit は必ず fs_read の後であること（STALE_READ バージョン用ガーデ）；old テキストは一意であること

• ネットワーク：localhost／プライベートネットワーク解決/link-local を拒否（SSRF 対策）、リダイレクトはホップごとに再検証、2MB 上限、30 秒でタイムアウト

• 認証：HTTP は常に Bearer/query-token；初期状態では 127.0.0.1 のみにバインド（デフォルト）

• プライバシー：ビートビートではウィンドウタイトルとクリップボードのハッシュだけを記録（変更時には先頭60文字のプレビューを保存）；ピクセルのスケショット for **是的 -> 明示的な screen_capture 呼び出し時のみ

ハートビートの意味 (方針 (理華を受け継ぐ))

ハートビートの刻みは heartbeat.intervalMin で調整可の15分1回。毎回の遷移では：現在の画面ウィンドウ、ウィンドウの一覧（top8）、アイドルの秒数、クリップボードの変化、未完了の TODO 件数を取得する。失敗時には間隔が 2 倍に（上限 8 倍）、成功すればリセットし、ログは vitals.ndjson にローリングする。

上流との同期（o-pi）

• 2026-08-23 チェック：当日の上流の大量コミットを内部リファクタのみ（file-tools/web-tools/filesystem/lsp の整理）を確認。6ツール＋2ウェブツールの動作契約は変わらず。duckduckgo-html-provider を ゼロキーのフォールバックパスとして沿う、理脈の抽出はまだ忠実である。

• 新機能 read は PDF ページの画像をサポート（d762209）：理脈の fs_read は .pdf に対しては構造化エラー UNSUPPORTED_MEDIA_PDF を返す（pdfjs を取り込むとゼロ依存のポリシーを破る案であるため、ロードマップ候補）。

• skill URI／bash ツール／approval gate は Pi ホストでの特別機能で、抽出の対象外。

• 同日の再確認（d795f92 new approval UI）：変更は src/approval/* と TUI のみであり、file-tools / web-tools はゼロ変更。これを契機に grep 契約の整合を完了：不正確な正規である場合—— ヒットがあれば literal_fallback 警告を返す；ヒットゼロの場合 INVALID_REGEX を返して空結果を偽装しない。テスト済み。

ライセンスおよび出所（License & Attribution）

本プロジェクトは GNU Affero General Public License v3.0 またはそれ以降（AGPL 3.0 以降）で公開しています。完全な条件は LICENSE を参照してください。

コード出典の表示：

• ファイルツール（src/core/filesys.mjs：ls/read/write/edit/find/grep）とウェブツール（src/core/web.mjs：web_search / web_fetch）の振る舞い・設計は Orion-zhen/o-pi（Pi Agent の file-tools と web-tools 設計ドキュメント、AGPL 3.0 ライセンス）から派生したもの。理脈はその本質を、独立したNode.js・零依存実装したものであり、コード・複製はしない。AGPL と同じ条項で異ソース開に還元。

• ハートビート／todo／記憶／視覚などのむパワードの基本的な fokusu を利用は、 steve02081504/den の生態系における「理華」キャラクターの能力設計（MIT ライセンス）を元に、アイドル（アイドル）ポーリング退避・重み付きタスク・名前≡キーワード≡内容の記憶という、その構造的な考え方のみ参考にして得て、そのコードをコピーしていない。

• MCP の実装は、Uncover 公式 @modelcontextprotocol/sdk を素とさせた。