homerail：從 README 讀懂流程與限制

HomeRail 為何選 DAG

HomeRail 的 README 第一段就把專案定位為：一個把一次性代理聊天轉變為可稽核、可重用工作流的 TypeScript 執行時。名字拆開看，Home 指它運行在你的家庭實驗室、NAS 或家用伺服器上，服務的是住在那裡的家人；Rail 指 DAG 的軌道形狀，代理工作沿著顯式邊在節點間流動，而不是堆積在單個聊天裡。README 明確說，設計賭注是人的注意力是任何自動化中最稀缺的資源，所以系統應該盡量少地索取注意力。

HomeRail 的檢查應鎖定 README 的安裝命令、DAG 定義、CLI 輸出和 audit trail；生成式 UI 被標成探索中，不能視作穩定介面。 本節編號1，只根據 README 與素材可確認的內容，未列出的版本相容性、效能和安全保證均視為未說明。

HomeRail 的檢查應鎖定 README 的安裝命令、DAG 定義、CLI 輸出和 audit trail；生成式 UI 被標成探索中，不能視作穩定介面。 先記錄首次啟動的終端輸出與返回碼；這次只改變一個條件，觀察輸出、日誌與程序狀態的差異，並把結果寫入xiaotianfotos-homerail-deep-analysis的測試紀錄。這個專案的輸入格式、執行環境、檔案位置、程序狀態、錯誤訊息、輸出內容與授權條件都要分開記錄，才能判斷文件描述是否適用於目前案例。

語音與生成式介面的狀態

README 的「目前可用」部分列出了四個元件。DAG 執行時被標記為最成熟，支援多代理編排、每次執行的獨立工作區、重放、評分卡和執行評估。CLI 命名為 hr，提供 start、config、doctor、run、smoke、dag supervise、scorecard、eval-run、replay 等子命令，被描述為操作 HomeRail 的主要方式。語音表面包含 ASR、TTS、VAD，預設中文，透過桌面語音外殼提供，代理會在行動前跨多輪收集意圖。生成式 UI 被明確標註為「探索中」，README 說其契約和元件集仍會繼續變化，目前形狀透過真實用例來設計。Docker Worker 方面，Manager 和 Node 作為本地服務執行，Node 使用 Docker 為每個 DAG 節點建立一個 Worker 容器，每次執行共享一個工作區。

HomeRail 的檢查應鎖定 README 的安裝命令、DAG 定義、CLI 輸出和 audit trail；生成式 UI 被標成探索中，不能視作穩定介面。 本節編號2，只根據 README 與素材可確認的內容，未列出的版本相容性、效能和安全保證均視為未說明。

HomeRail 的檢查應鎖定 README 的安裝命令、DAG 定義、CLI 輸出和 audit trail；生成式 UI 被標成探索中，不能視作穩定介面。 再比對設定檔中的鍵名和實際產物；這次只改變一個條件，觀察輸出、日誌與程序狀態的差異，並把結果寫入xiaotianfotos-homerail-deep-analysis的測試紀錄。這個專案的輸入格式、執行環境、檔案位置、程序狀態、錯誤訊息、輸出內容與授權條件都要分開記錄，才能判斷文件描述是否適用於目前案例。

從安裝到運行檢查

Quickstart 部分列出了三類環境要求：Node.js 20+ 和 npm 10+，Docker（由 Node 用來建立 Worker 容器），以及一個 Claude Agent SDK 相容的模型端點用於即時代理執行。平台說明提到 macOS 上 Docker Desktop 的 host.docker.internal 對映開箱即用，Windows 需要從 Git Bash 執行 CLI 因為部分指令碼假設 Unix 類 shell，Linux 上 Worker 到 Manager 的網路可能需要額外設定。安裝建置指令是 npm run install:all 和 npm run build，然後 cd homerail_cli && npm link 讓 hr 指令可用。之後 README 展示了 hr start、hr doctor、以及使用 offline-deterministic 配置檔案的 hr run 指令來執行本機拓撲檢查，該指令不需要模型提供者。

HomeRail 的檢查應鎖定 README 的安裝命令、DAG 定義、CLI 輸出和 audit trail；生成式 UI 被標成探索中，不能視作穩定介面。 本節編號3，只根據 README 與素材可確認的內容，未列出的版本相容性、效能和安全保證均視為未說明。

HomeRail 的檢查應鎖定 README 的安裝命令、DAG 定義、CLI 輸出和 audit trail；生成式 UI 被標成探索中，不能視作穩定介面。 接著用最小輸入重跑並保留錯誤訊息；這次只改變一個條件，觀察輸出、日誌與程序狀態的差異，並把結果寫入xiaotianfotos-homerail-deep-analysis的測試紀錄。這個專案的輸入格式、執行環境、檔案位置、程序狀態、錯誤訊息、輸出內容與授權條件都要分開記錄，才能判斷文件描述是否適用於目前案例。

同步、監督與評分

執行 DAG 的文件路徑從 hr templates list 開始，可以直接用範本檔案執行，也可以先 hr dag sync 和 hr profile sync 把工作流同步進 Manager 資料庫。README 提醒，編輯 YAML 時要保持 workflow_id 穩定，改變它會建立新的工作流身份。執行後返回 run_id，可以用 hr dag supervise、hr scorecard、hr eval-run 檢查。多輪 DAG 的細節被指向 docs/multi-round-dags.md，包括嚴格的 WorkflowSpec v1 編寫、輪次隔離、CLI 和 HTTP 指令、恢復、過期和並發槽行為。另外還有 Manager 支撐的 DAG 模式庫，hr patterns list、show、instantiate 可以操作仲裁、有界棘輪、持續目標驗證、規劃者/工人扇出等模式。

HomeRail 的檢查應鎖定 README 的安裝命令、DAG 定義、CLI 輸出和 audit trail；生成式 UI 被標成探索中，不能視作穩定介面。 本節編號4，只根據 README 與素材可確認的內容，未列出的版本相容性、效能和安全保證均視為未說明。

CLI 與編碼代理路徑

除了對 Manager Agent 說話或自己輸入指令，README 還描述了一種替代用法：把 hr CLI 交給已經信任的編碼代理（如 Codex 或 Claude Code）直接驅動。這個流程跳過了 Manager Agent 層（即從請求規劃 DAG 的 AI），但沒有跳過 Manager 服務（即 DAG 協調器），編碼代理承擔規劃角色，讀取範本、決定修改、執行 DAG、檢查結果並迭代。README 用一張圖表示這個迴路：你 ↔ 編碼代理 ↔ hr CLI ↔ Manager 服務 ↔ DAG 節點。Manager Agent 仍然是用戶希望從單個請求端到端規劃和執行工作流時的選擇，尤其是透過語音。

HomeRail 的檢查應鎖定 README 的安裝命令、DAG 定義、CLI 輸出和 audit trail；生成式 UI 被標成探索中，不能視作穩定介面。 本節編號5，只根據 README 與素材可確認的內容，未列出的版本相容性、效能和安全保證均視為未說明。

包結構與探索中功能

架構表列出了六個包：homerail_protocol 負責共享訊息和驗證契約，homerail_manager 是 Manager 服務和 DAG 協調器並擁有語音表面和生成式 UI 契約，homerail_node 負責提供 Docker 支撐的 Worker 容器，homerail_worker 是 Worker 執行時，包含 Claude Agent SDK 和相容代理後端的 harness 介面卡，homerail_cli 是 hr 指令本身，agent-ui 是瀏覽器 UI。配置部分說明 HOMERAIL_HOME 是本地資料根目錄，預設 ~/.homerail，每次 DAG 執行的工件都寫入 ${HOMERAIL_HOME}/workspace/<run_id>/，README 建議把它指向容量足夠的磁碟。提供者憑據儲存在 Manager 加密設定儲存中，絕不在倉庫檔案中。Manager URL 的解析順序是 --base-url、HOMERAIL_MANAGER_URL、${HOMERAIL_HOME}/config.json，然後才是 http://localhost:19191。

HomeRail 的檢查應鎖定 README 的安裝命令、DAG 定義、CLI 輸出和 audit trail；生成式 UI 被標成探索中，不能視作穩定介面。 本節編號6，只根據 README 與素材可確認的內容，未列出的版本相容性、效能和安全保證均視為未說明。

編輯結論

適合願意依 xiaotianfotos/homerail 的 README 建立小型案例、檢查具體輸入輸出並承擔相依條件的人；不適合把文件中的能力當成未經驗證的效能或相容性承諾。採用前請執行專案明示的命令，記錄版本、設定、產物與錯誤，再按 MIT 檢查使用方式。

官方來源

1. Official README
2. Project repository
3. Release notes