理脈 limai

理華與理月的共享神經系統——從角色中按第一性原理提取的獨立器官。

第一性原理推導

角色裡的樣子	本質	模組	MCP 工具
心跳輪詢＋錯誤退避（on_idle.mjs）	節律	heartbeat.mjs	heartbeat_now・vitals_latest・vitals_history
截圖/視窗/剪貼簿（screenshot.mjs）	視覺	vision.mjs	screen_capture(回圖片)・list_windows・read_clipboard
todo-tasks.json＋權重融合心跳	意圖	todo.mjs	todo_add・todo_list・todo_update
長期記憶（名×關鍵字×內容）	記憶	memory.mjs	memory_add・memory_search・memory_list・memory_forget
o-pi 六文件工具	檔案行動	filesys.mjs	fs_ls/read/write/edit/find/grep
o-pi websearch/webfetch	網路行動	web.mjs	web_search・web_fetch

捨棄的：角色的 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 agent 而設計

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"] } } }

區網／同機 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=<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 字元預覽）；像素截圖僅限明確呼叫 screen_capture

心跳語義（沿襲理華）

15 分鐘一跳（可調 heartbeat.intervalMin）。每跳收集：前景視窗・視窗清單(top8)・閒置秒數・剪貼簿變化・開放待辦數。失敗時間隔 ×2（上限 8×），成功復位。日誌滾動於 vitals.ndjson。

上游同步（o-pi）

• 2026-08-23 檢查：上游當日大量提交為內部重構（file-tools/web-tools/filesystem/lsp 簡化），六工具＋兩網頁工具的行為契約不變；duckduckgo-html-provider 仍為零-key 備援路徑——理脈提取依然忠實。
• 新能力 read 支援 PDF 頁面圖像（d762209）：理脈已對齊實作——fs_read 加 pages 參數（N / N-M / N-），回傳頁面 PNG 的 MCP 圖像內容塊；CLI 用 fs read <pdf> --pages "1-5"。主路線 PDF.js（pdfjs-dist legacy）＋@napi-rs/canvas 跨平臺渲染；Windows 上依賴無法載入時自動降級內建 WinRT Windows.Data.Pdf。預設單次上限 20 頁，含總頁數與續讀位置。
• 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-or-later）發佈，完整條款見 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／記憶／視覺等能力原語的提取藍本，來自 steve02081504/fount 生態中「理華」角色的能力設計（MIT 授權）。僅參考其架構思想（閒置輪詢退避、加權任務、名稱×關鍵字×內容記憶），未複製其程式碼。
• MCP 協議實作基於官方 @modelcontextprotocol/sdk。
• PDF 渲染依賴 pdf.js（Apache-2.0）與 @napi-rs/canvas（MIT）。