CLI · 第三層
工具
提供給 AI agents、workbench 以及除錯使用的實用程式 — search, replace, inspect, doctor, upgrade, skills:sync。這些是已實作的指令，但它們不屬於日常建置循環的一部分。
第三層 CLI 工具支援 workspace 操作、結構檢查與狀態更新。這些工具獨立於日常建置生命週期。
原始碼操作
於 MDX 來源執行全文搜尋。回傳符合項目的檔案路徑、行號、欄位與預覽字串。
open-press search . <query> [--json]參數 (Flags)
| Name | Type | Default | Description |
|---|---|---|---|
<query> required | string | 搜尋目標。支援純文字或正規表示式。 | |
--json | flag | 輸出機器可讀之 JSON 格式。 | |
--scope | string | "content" | 指定搜尋範圍。`content` (僅 MDX 內文) 或 `all` (包含 frontmatter 與 metadata)。 |
--case-sensitive | flag | 強制區分大小寫。預設為不區分大小寫。 |
範例：JSON 搜尋
open-press search . "Figure" --json | jq '.matches[] | {file: .path, line, preview}'於 MDX 來源執行批次字串替換操作。預設模式為唯讀預覽。
open-press replace . <from> <to> [--apply]參數 (Flags)
| Name | Type | Default | Description |
|---|---|---|---|
<from> required | string | 搜尋目標字串或正規表示式。 | |
<to> required | string | 替換用字串。 | |
--apply | flag | 套用變更並寫入檔案。未提供此旗標時僅輸出預覽。 | |
--scope | string | "content" | 同 `search` 指令之範圍設定。 |
--include-code | flag | 擴大替換範圍至程式碼區塊 (fenced code blocks)。預設略過以防誤改程式碼。 | |
--case-sensitive | flag | 強制區分大小寫。 | |
--json | flag | 輸出機器可讀之 JSON 報告。 |
範例：執行替換
open-press replace . "舊片語" "新片語" --apply渲染檢查
執行建置後內省。調用無頭版 Chrome 分析已建置專案之區塊幾何尺寸與註解標記。
open-press inspect . [--json]參數 (Flags)
| Name | Type | Default | Description |
|---|---|---|---|
--json | flag | 輸出機器可讀之 JSON 報告。 | |
--no-build | flag | 繞過建置階段，分析現有的 `dist-react/` 目錄。 | |
--host | string | "127.0.0.1" | 無頭版 Chrome 連接之伺服器 IP。 |
--port | string | "5186" | 無頭版 Chrome 連接之伺服器連接埠。 |
--dry-run | flag | 僅輸出執行鏈指令，不啟動伺服器或調用 Chrome。 |
環境與狀態管理
回報 workspace 相依性與套件版本狀態。檢查 framework 版本與 agents skills。結果快取 24 小時。
open-press doctor .參數 (Flags)
| Name | Type | Default | Description |
|---|---|---|---|
--json | flag | 輸出機器可讀之 JSON 報告。 | |
--no-cache | flag | 繞過本機快取，直接向 npm 查詢最新資訊。 |
doctor 指令退出碼恆為 0。自動化流程應解析 JSON 輸出之 report.stale 或 report.coreUpdateAvailable 判斷執行邏輯。
升級 workspace 依賴與 agents skills。source migration 與 QA 請使用 `openpress-upgrade` skill。
open-press upgrade .請與 doctor 配合使用，在執行前確保已建立 Git 版本控制快照。此指令會刷新套件與 skills；workspace source migration 由 agent 負責：使用 openpress-upgrade 讀取適用的 migration docs、掃描 press/、套用已確認的 source edits，並循環執行 Migration QA checkpoints。
同步技能套件包至 .agents/skills/ 目錄及相關平台鏡像。依據 skills-lock.json 執行更新。
open-press skills:sync .參數 (Flags)
| Name | Type | Default | Description |
|---|---|---|---|
--source | string | 新增並安裝指定之技能套件包。格式：`owner/repo` 或 `github:owner/repo`。 | |
--dry-run | flag | 僅印出底層之 `npx skills` 指令，不執行安裝。 |