WidgetStore CLI：讓其它 AI Agent 用命令操作組件世界

組件世界電腦版自帶一個命令行工具 widgetstore。其它 AI Agent（Claude Code、Codex、Gemini CLI、Cursor…）和你的腳本都能用它操作組件世界：

• 雲端能力（和我們的 MCP 伺服器 是同一套工具）：讀我的空間、改組件、往「我的資料」加記錄、加待辦、記專注、AI 打造空間……網站新增的能力會自動出現在命令裡。
• 這臺電腦的能力：開始 / 結束專注計時、把組件釘到桌面、打開頁面或啟動器、發系統通知、讀 AI 用量、讓本機的 Agent 跑一個任務。

安裝

打開電腦版 → 側欄 Agents →「命令行」→ 安裝命令行工具：

• macOS：放到 /usr/local/bin/widgetstore（會彈出系統密碼框）；取消的話放到 ~/.local/bin，並告訴你怎麼加到 PATH。
• Windows：把安裝目錄加到你這個使用者的 PATH（不需要管理員），新開的終端裡就能用。
• Linux：.deb / .rpm 安裝的本來就有 /usr/bin/widgetstore；AppImage 會連結到 ~/.local/bin/widgetstore。

裝好後新開一個終端，執行 widgetstore status 看看。

登入

• 有電腦版的電腦（推薦）：在「命令行」裡點 連線帳號，瀏覽器裡確認要給的權限（可以去掉不想給的）。授權儲存在系統鑰匙串裡（Linux 是隻有你能讀的檔案），命令行進程拿不到令牌，由電腦版代為調用。在網站「設定 → API 與 AI 連線 → 已連線的 AI 應用」裡隨時可以斷開。
• 沒有電腦版的機器（伺服器 / CI）：在網站「設定 → API 與 AI 連線」新建一個個人令牌，設成環境變量 WIDGETSTORE_TOKEN=wsp_…；或者 widgetstore login --token -（從輸入讀入，存進鑰匙串）。

用法

widgetstore tools                    # 列出所有命令（雲端 + 這臺電腦）
widgetstore get_my_space --json      # 機器可讀的輸出
widgetstore add_record --help        # 某個命令的引數
widgetstore focus_start --minutes 25 --task "寫周報"
widgetstore ask claude "根據最近的提交寫釋出說明" --cwd ~/code/app --wait
widgetstore mcp                      # 本機 MCP 伺服器（stdio）

• 引數來自每個工具的 JSON Schema：--名字 值、--開關 / --no-開關、數組可以重複寫，--args '{"…":…}' 一次給全部；值寫 @檔案 或 @-（從輸入讀）。
• 加 --json 輸出固定格式：成功 {"ok":true,"tool":…,"data":…,"text":…}，失敗 {"ok":false,"error":{"code","message","exit"}}。
• 退出碼：0 成功 · 1 工具 / 服務端錯誤 · 2 用法錯誤 · 3 沒有登入或權限不夠 · 4 電腦版沒在執行（本機命令）· 5 你在電腦版裡拒絕了。

接到你的 Agent 裡

一行把 widgetstore mcp 接成本機 MCP 伺服器（同一套工具）：

Agent	命令 / 配置
Claude Code	claude mcp add widgetstore -- widgetstore mcp
Codex CLI	codex mcp add widgetstore -- widgetstore mcp
Gemini CLI	gemini mcp add widgetstore widgetstore mcp
Cursor	~/.cursor/mcp.json：{"mcpServers":{"widgetstore":{"command":"widgetstore","args":["mcp"]}}}
opencode	opencode.json：{"mcp":{"widgetstore":{"type":"local","command":["widgetstore","mcp"]}}}

也可以不用 MCP，直接在項目的 AGENTS.md / CLAUDE.md 裡寫一段（「命令行」頁有現成的可以複製）：

## WidgetStore
- The `widgetstore` CLI is installed. Run `widgetstore tools --json` to see every command and its JSON schema.
- Call a tool with `widgetstore <tool> --option value --json` (exit code 0 = ok).
- Local actions (opening pages, pinning widgets, agent tasks) need the user to confirm in the WidgetStore desktop app. Cloud writes are logged and can be undone with `widgetstore undo`.

安全

• 權限在服務端按令牌的範圍執行；每一次修改都記在「操作日誌」裡，可以撤銷（widgetstore undo）。沒有任何命令能刪除資料、改帳號或花錢；會花火花的工具在命令行裡預設關閉（「命令行」→ 安全裡可以打開）。
• 這臺電腦上的命令走本機通道：只有你這個系統使用者能連，還要帶電腦版每次啟動生成的隨機口令。
• 打開頁面 / 啟動器、釘組件、讓 Agent 跑任務都會在電腦版裡彈出確認視窗，寫清要做什麼，你點「允許」才繼續。可以在「命令行」→ 安全裡信任「打開類」的請求和只讀的 Agent 任務；會改檔案或「全部自動批準」的任務永遠要確認。
• 命令行進程看不到你的登入態和令牌；電腦版讓 Agent 執行時也不會把它們傳過去。