選單路徑: 儀表板 > 任務 > 本機
本機 Worker (CLI)
概述
本機 Worker 是你電腦上某個檔案中的函式。3Min API CLI（npm 套件 @3minapi/cli）在那台電腦上執行，取走 AI 傳送的任務，以每個任務的輸入執行函式並回報結果。AI 與你的電腦不會直接通訊 — 中間由 3Min API 居中處理。
- 不需要公開 URL，也不需要開放連接埠。 CLI 只會發出對外請求
- 函式讀取的內容都留在你的電腦上，只有它回傳的內容例外
- 一個檔案 = 一個函式 = 一個 Worker
公開 URL 上的伺服器請參閱任務（公開 Worker）。
| 用語 | 意義 |
|---|---|
| 主機 | 執行 CLI 的電腦。在儀表板 → 任務 → 本機 中為每台電腦新增一個 |
| 主機權杖 | tm_host_…。讓那台電腦上的 CLI 登入。只顯示一次 |
| 專案資料夾 | 預設為 ~/3minapi：3minapi.json、workers/、data.db、.gitignore。每個主機一個 |
data.db |
專案中的 SQLite 檔案。所有結果都儲存在這裡；你的 Worker 也可以保存自己的資料 |
| 結果讀取 | CLI 註冊的內建本機 Worker，讓你的 AI 可以讀取儲存在 data.db 中的結果 |
| 種類 | worker_list 中的 kind |
任務如何送達 | Free 方案 | API 呼叫 |
|---|---|---|---|---|
| 公開 Worker | "public" |
3Min API 以 POST 傳送到你的 URL | 1 | 傳遞計 0 次 |
| 本機 Worker | "local" |
CLI 取走（預設即時通知，或定期檢查） | 無限制 | 即時：閒置時不計呼叫。定期檢查：每次取得都計 1 次，即使沒有任務 |
安裝與更新
指令在你電腦上的終端機中執行 — Windows 為 終端機 或 PowerShell（開始功能表），macOS 為 終端機（應用程式 → 工具程式）。
- Node.js 24.12 以上版本。
node -v會顯示版本。如果沒有安裝或版本較舊，請從 nodejs.org 安裝 LTS 版（Windows 也可以用winget install OpenJS.NodeJS.LTS），然後開啟新的終端機 - CLI：
npm install -g @3minapi/cli
3minapi --version
- Windows PowerShell 可能會以 "running scripts is disabled on this system" 拒絕執行。請輸入
3minapi.cmd代替3minapi—— 不必更改任何設定即可執行。若想為自己的帳戶允許腳本，可以使用Set-ExecutionPolicy -Scope CurrentUser RemoteSigned（該設定會一直保留，直到你改回） npx @3minapi/cli <command>可以不安裝直接執行- 更新使用相同的指令：
npm install -g @3minapi/cli 3minapi doctor會檢查 Node.js、設定、權杖、網路與 Proxy 設定，並告訴你需要修正什麼。位於 Proxy 後方時，請設定NODE_USE_ENV_PROXY=1
快速開始
順序與 本機 分頁上的設定卡片相同。
npm install -g @3minapi/cli
3minapi init
3minapi worker new hello
3minapi worker run hello --input '{"message":"hi"}'
3minapi login
3minapi start
3minapi init會在~/3minapi建立專案（用3minapi init <folder>指定位置）。之後指令可以在任何資料夾執行3minapi worker new hello會從範本建立workers/hello.mjs。先修改描述，再修改 handler3minapi worker run hello --input '…'在你的電腦上執行一次 — 不建立任務，也不使用 API 呼叫。反覆執行直到它正確運作- 儀表板 → 任務 → 本機 →
新增主機，複製權杖，然後執行3minapi login並在提示處貼上 3minapi start會把你的 Worker 檔案註冊為本機 Worker 並執行它們的任務。你的 AI 現在可以在worker_list中看到它們，kind: "local"
如果沒有 Worker 檔案，start 會立即結束。
指令
所有指令都可以在任何資料夾執行。--json 提供機器可讀的輸出；3minapi help <command> 會顯示所有旗標。
主機
| 指令 | 作用 |
|---|---|
3minapi init [folder] |
建立主機的專案。可以安全地重複執行。沒有終端機時需要 --yes；--move 會移動專案 |
3minapi login |
儲存主機權杖（遮罩輸入提示）。--with-token 會從 stdin 讀取，供腳本使用 |
3minapi logout |
只從這台電腦移除已儲存的權杖 |
3minapi start |
註冊 Worker 檔案並執行它們的任務，直到停止為止。--mode poll 會改為按間隔取得，而非預設的即時模式。按 Ctrl+C 停止 |
3minapi start --detach |
同上，但在背景執行。重新開機後不會自動啟動 |
3minapi reload |
讓執行中的 start 重新讀取 Worker 檔案並註冊。執行中的任務會繼續。1 次呼叫 |
3minapi stop |
停止這台電腦的 start，無論它是從哪裡啟動的 |
3minapi status |
start 是否在執行、本機 Worker、重複任務、剩餘額度。1 次呼叫 |
3minapi logs [-f] |
CLI 自身的日誌 — 取得、停止、錯誤 |
3minapi doctor |
環境檢查。不傳送權杖，不使用額度 |
3minapi paths |
專案檔案與 CLI 自身資料夾的絕對路徑 |
Worker
| 指令 | 作用 |
|---|---|
3minapi worker new <name> [--ts] |
建立 workers/<name>.mjs（加上 --ts 則為 .mts）。如果 start 正在執行，會立即註冊（--no-reload 可略過） |
3minapi worker run <name> --input '<json>' |
在本機執行一次。--input-file <file> 可以避免 Windows 上的 shell 引號問題 |
3minapi worker list |
專案中的 Worker，逐一檢查能否載入。不使用 API 呼叫 |
3minapi worker logs <name> [-f] |
單一 Worker 的日誌：ctx.log、主控台輸出、含堆疊追蹤的錯誤 |
3minapi worker delete <name> |
從 3Min API 刪除本機 Worker 及其任務紀錄，然後刪除其檔案。無法復原 |
結果與紀錄
| 指令 | 作用 |
|---|---|
3minapi worker results list |
已儲存的結果，最新的在前。--worker、--since、-n |
3minapi worker results show <task_id> |
完整顯示一筆已儲存的結果。--run <n> 指定重複任務的某次執行 |
3minapi worker results runs <task_id> |
重複任務的各次執行 |
3minapi worker results describe <task_id> |
一筆結果所含的路徑。--worker <name> 會依結構分組某個 Worker 的結果 |
3minapi worker results query "<SQL>" |
對已儲存結果執行唯讀 SQL。不使用 API 呼叫 |
3minapi worker results prune --before <date> |
從 data.db 刪除早於該日期的已儲存結果 |
3minapi tasks prune --before <date> |
刪除此主機上在該日期之前結束的任務紀錄。最近與未結束的任務會保留 |
3minapi dashboard |
在瀏覽器中開啟唯讀頁面：執行紀錄、結果、Worker、日誌。無需登入，不使用 API 呼叫 |
dashboard --detach讓它在背景持續執行；dashboard url會再次輸出連結；dashboard stop會結束它dashboard --lan也會以純 HTTP 提供給網路上的其他裝置。只在你信任的網路中使用- 具破壞性的指令與
--lan會要求確認。 沒有終端機時（或使用--json時）需要--yes
撰寫 Worker
workers/ 中的一個檔案就是一個 Worker，以檔名命名。
- 名稱：小寫字母、數字、
_與-，最多 50 個字元，不能以_開頭，也不能是 Windows 裝置名稱（con、aux等）。在你所有的 Worker 中唯一 — 包含公開 Worker 與你其他電腦上的 Worker — 不分大小寫 .mjs（預設）或.mts/.ts— TypeScript 不需建置即可執行（不支援enum或namespace）
// workers/rename_photos.mjs
export const description =
'Renames the photos in a folder by the date taken. input: { folder: string }';
export const timeoutMs = 10 * 60_000; // 選填 — 預設 60 秒，最長 23 小時
export async function handler(input, ctx) {
await ctx.report('Scanning the folder'); // 進度 — task_get 看得到
if (ctx.signal.aborted) return; // 已取消，或即將逾時
// … 實際工作 …
return { renamed: 42 }; // → completed；這就是結果
// throw new Error('Folder not found') // → failed；訊息即為錯誤
}
| 匯出 | 規則 |
|---|---|
description |
必填。AI 在 worker_list 中看到的內容，最多 500 個字元。請在這裡寫明輸入的結構 |
timeoutMs |
選用。預設 60 秒，最長 23 小時 |
inputSchema |
選用。JSON Schema 的小型子集（type、properties、required、enum、items），只在你的電腦上檢查 |
handler |
必填。async (input, ctx) => result |
ctx |
內容 |
|---|---|
ctx.report(message) |
進度訊息，超過 256 個字元會被截斷。每次 1 次呼叫 |
ctx.log(message) |
只寫入 Worker 日誌 |
ctx.env |
系統環境變數 + 專案的 .env（以 .env 為準）。以 THREEMINAPI_ 開頭的變數會被移除 |
ctx.signal |
在取消或逾時時觸發的 AbortSignal |
| handler 的結束方式 | 任務變為 |
|---|---|
return value |
completed。值必須是 JSON |
throw |
failed。訊息（包含 cause），權杖會被遮罩，超過 4,000 個字元會被截斷。堆疊只保留在本機日誌中 |
| 逾時 | failed（timeout） |
| 取消 | ctx.signal 觸發；2 秒後結束執行。其回傳值不會被傳送 |
- 套用變更：修改 handler 的程式碼與
.env會從下一個任務開始生效。新增或重新命名檔案、修改描述則需要3minapi reload（或下一次start）；worker new會自動重新載入 - 移除檔案不會從 3Min API 移除 Worker — 它的任務會失敗。請使用
3minapi worker delete <name> - 密鑰（你自己的 API 金鑰）放在專案的
.env中，.gitignore已經涵蓋它。請以 UTF-8 儲存（UTF-16 會被拒絕） - 同一任務可能到達兩次（at-least-once）。有副作用的 Worker 應能承受重複執行
- 頂層含有
_3minapi鍵的結果會以reserved_result_key失敗 - 你的 Worker 可以在
data.db中保存自己的資料：以node:sqlite開啟new URL('../data.db', import.meta.url)。以_3minapi_開頭的資料表屬於 CLI — 僅供讀取
從 AI 執行
start 執行後，照常向 AI 提出要求即可 — 不需要知道工具名稱。
- 「把 D:\Photos\2026 裡的照片依日期重新命名」
- 「每分鐘查一次 BTC 價格，共 10 次」
- 「停止查價格」
AI 會依序使用 worker_list → task_create → task_get。任務會在 3Min API 上等待，直到 CLI 取走它——以即時模式（預設）執行中的 CLI 收到通知後取走，定期檢查模式則在下一次檢查時取走。在此之前 task_get 顯示 delivery: "pending"，之後為 "delivered"。
重複任務
僅限本機 Worker，task_create 可以接受 repeat，以固定間隔用相同的輸入執行 — 一個任務，所有執行共用同一個任務 ID。
{
"worker": "price-feed",
"input": { "symbol": "BTC" },
"repeat": { "interval_seconds": 60, "max_runs": 10 }
}
| 欄位 / 規則 | 值 |
|---|---|
interval_seconds |
10 到 604,800（7 天）。下一次執行時間到時，若上一次仍在執行，就略過該次 |
max_runs |
選用。省略時會一直重複直到取消 — 請 AI 取消即可停止 |
| 狀態 | 維持 working；repeat 顯示 runs、failed 與 last_run_at。最後一次執行後變為 completed，並附上摘要 |
| 失敗 | 單次執行失敗不會停止重複。連續 5 次失敗 → failed（repeat_failed） |
| 費用 | 除了 CLI 接收任務所用的呼叫之外，每次執行計 1 次呼叫。每分鐘執行且不設上限 ≈ 每月 43,200 次 |
| 變更 | 取消後重新建立 |
| CLI 關閉時 | 暫停。24 小時加上一個間隔內沒有回報任何執行 → failed |
| 公開 Worker | 不允許 — repeatRequiresLocalWorker |
每次執行的結果會以獨立的一列（run_no 1、2、…）儲存在你的電腦上。
讀取結果
所有結果都儲存在你電腦上的 data.db 中。 約 100 KB 以內的結果也會傳送到 3Min API，並透過 task_get 送達 AI。較大的結果不會傳送：任務會以 result._3minapi 中的替代內容完成（stored_locally: true、任務 ID、大小、shape 摘要與 reader 名稱）。
AI — 透過主機的結果讀取，也就是名為 _results_ + 主機 ID 後 8 個字元的內建本機 Worker。worker_list 會把它列在 hosts 中該主機的 results_reader，而不是列在 Worker 之中。它在你的電腦上運算，只回傳答案。下方的 task_result_* 工具會把每一步交給它，並依給定的 task_id 或 worker 選擇電腦，因此 AI 不需要知道它的名稱。
| 順序 | 工具 | 用途 |
|---|---|---|
| 1 | task_result_describe (task_id 或 worker) |
先了解結構。 結果中沒有的路徑會讀成 NULL，因此結構混雜時加總會出錯 |
| 2 | task_result_query (sql, worker) |
對檢視表 results 執行唯讀 SQL。彙總後只回傳答案 |
| 3 | task_result_read (task_id, path, offset) |
約 90 KB 的原始片段，只在需要原始資料本身時使用 |
- 每個讀取任務至少計 4 次呼叫，並會等待 CLI 取走它
- 讀取 Worker 會在
start執行且至少有一個 Worker 檔案時註冊
你自己 — 3minapi worker results list/show/describe/query 或 3minapi dashboard。data.db 永遠不會自動清理；請使用 worker results prune。其中可能包含個人資料。
讓 AI 執行 CLI
有些 AI 用戶端在你允許後可以在你的電腦上執行指令 — 例如 Claude Code、Codex 等程式設計代理，以及部分桌面應用程式。其他用戶端（例如網頁版 ChatGPT）則無法：請自行執行指令，再把輸出內容貼回去。
| AI 可以 | AI 不應該碰觸 |
|---|---|
編輯 workers/*.mjs（描述、handler）與 3minapi.json |
主機權杖 — 絕不放在對話或命令列中（3minapi login 會提示輸入） |
執行 worker new、worker run、reload、status、doctor、logs、worker results … |
CLI 自身的資料夾（credentials.json、control.db）— 見 3minapi paths |
先詢問位置後執行 init <folder> 或 init --yes |
data.db 中以 _3minapi_ 開頭的資料表 |
- 沒有終端機時，具破壞性的指令需要
--yes，因此--yes是唯一的確認。執行worker delete --yes前請先向使用者確認 — 它會刪除 Worker 及其任務紀錄 --json提供 AI 可以解析的輸出。錯誤以{ "error": { "kind", "message", "exitCode", "code"?, "resetAt"? } }的形式回傳。因配額停止且已知重設時間時，還會附上resetAt
主機與權杖
| 情況 | 處理方式 |
|---|---|
| 多台電腦 | 每台電腦新增一個主機。一台電腦 = 一個主機 = 一個專案。不同電腦上的 Worker 名稱必須不同 |
| 權杖遺失或外洩 | 在主機頁面上輪替權杖。舊權杖立即失效，使用它的 CLI 會停止 |
| 移轉到另一台電腦 | 輪替權杖 → 複製專案資料夾 → 用新權杖執行 3minapi login → 3minapi start。Worker 與紀錄都會保留 |
| 刪除主機 | 會刪除其本機 Worker 及其任務紀錄。只在想從頭開始時使用；執行中的 CLI 會停止 |
| 移動資料夾 | 3minapi stop → 移動 → 在資料夾內執行任一指令，或執行 3minapi init <folder> --move |
主機頁面會顯示 CLI 接收任務的方式（即時或定期檢查）、最近一次連線或檢查、檢查間隔（僅定期檢查）、並行數、版本與平台 — 這些是 CLI 回報的事實，不是目前狀態。
限制與額度
| 項目 | 值 |
|---|---|
| 本機 Worker | 所有方案皆無限制 |
| 接收（即時，預設） | 維持連線本身不產生呼叫。 每次連線或重新連線計 1 次，之後的補取取得再計 1 次，收到任務或取消通知而取得時每次計 1 次。連線會因網路因素每天中斷幾次並自動重新連線，所以即使沒有任務也會用掉一些呼叫——每天中斷 6 次約為每天 12 次、每月 360 次 |
| 接收（定期檢查） | 即使沒有等待中的任務，每次取得也計 1 次呼叫。 預設每 60 秒 ≈ 每天 1,440 次 ≈ 每月 43,200 次 |
| 其他呼叫 | 每次接收確認 1 次、每次回報 1 次（ctx.report 與最終結果）、每次重複執行 1 次、每次 reload/status 1 次 |
| 同時執行 | concurrency，預設 4（1–50）。每次取得最多 concurrency 個任務 |
| 期限 | 建立後 24 小時內未被取走 → failed（每小時檢查一次，最長約 25 小時） |
| 任務紀錄 | 付費方案至少 60 天。Free 方案的本機 Worker 及其執行紀錄會在 Worker 註冊 7 天後刪除；reload 或下一次 start 會再次註冊 |
| 額度用盡 | CLI 會自行停止（結束代碼 5），且不會重新啟動。回報永遠不會被阻擋 |
| 傳送到 3Min API 的結果 | 約 100 KB；較大的結果保留在你的電腦上（傳送替代內容） |
| 本機日誌 | 預設保留 30 天 / 300 MB（logRetentionDays、logMaxBytes） |
若要減少呼叫，請使用預設的即時模式。如果網路環境需要定期檢查，請調高 3minapi.json 中的 pollIntervalMs（任務會較晚被取走）並重新啟動。
concurrency 個任務全部在執行時，CLI 不會取走新任務——這些任務維持 pending（仍會收到取消通知）。由此決定的處理量會顯示在 3minapi start 與 3minapi status 中。
狀態與疑難排解
是否正在執行？ 請在那台電腦上用 3minapi status 確認。網頁上的 CLI 接收，以及 worker_list 提供給 AI 的最後檢查或連線時間，都是過去的事實，不是目前狀態。
| 症狀 | 原因與解決方式 |
|---|---|
任務一直是 working 且 delivery: "pending"（網頁上顯示 等待電腦） |
CLI 尚未取走任務。請在那台電腦上執行 3minapi start |
3minapi start 顯示無法開啟即時連線 |
公司的代理或防火牆擋住了它。用 3minapi doctor 檢查；以 --mode poll 啟動（或設定 receiveMode: "poll"）即可按間隔取得 |
Not picked up within 24 hours — the 3Min API CLI on the user's PC did not fetch it. |
CLI 關閉超過 24 小時。啟動 CLI 後重新傳送任務 |
No run was reported for 24 hours — the 3Min API CLI on the user's PC stopped running it. |
重複任務失去了它的 CLI。啟動 CLI 後重新建立任務 |
Worker did not respond within 24 hours. |
CLI 已取走但始終未回報結果的本機任務——當機後電腦一直沒有開機。不會再次執行 |
以 host_stopped 失敗 |
你在執行期間停止了 CLI（Ctrl+C 或 stop）。重複任務只會失去該次執行 |
以 host_restarted 失敗 |
電腦或 CLI 在任務執行中停止運作。無法確定是否已執行，且不會重新執行 |
| AI 以舊的結構傳送輸入 | 你修改了描述但沒有執行 3minapi reload |
worker_list 中沒有某個 Worker |
新增檔案後沒有 reload、載入錯誤（3minapi worker list），或 Free 7 天刪除（reload） |
CLI 以 worker_name_taken 拒絕某個名稱 |
其他 Worker（公開 Worker 或其他電腦上的 Worker）已使用該名稱。請重新命名檔案 |
| CLI 以代碼 4 或 5 結束 | 4：權杖無效或沒有方案 — 請重新 login。5：每月額度已用盡 |
結束代碼
| 代碼 | 意義 |
|---|---|
| 0 | 正常 |
| 1 | 失敗 |
| 2 | 用法錯誤（包含缺少 --yes） |
| 3 | 環境或設定錯誤 |
| 4 | 已停止：權杖無效，或帳號沒有方案（Free 也算方案） |
| 5 | 已停止：每月額度已用盡 |
| 130 | 已中斷（Ctrl+C） |
結束代碼為 4 或 5 時，不會自動重新啟動。
失敗的本機 Worker 任務的 error.data.reason
| 原因 | 意義 |
|---|---|
handler_error |
handler 拋出了錯誤 |
timeout |
執行超過 timeoutMs |
invalid_input |
不符合 inputSchema — 未執行 |
invalid_worker |
檔案存在但無法使用 — 沒有 handler、名稱重複或匯入錯誤 |
worker_not_found |
那台電腦上沒有這個檔案 |
unsupported_syntax |
CLI 無法在不建置的情況下執行的 TypeScript（例如 enum） |
result_too_large |
超過約 100 KB，且無法儲存在電腦上 |
reserved_result_key |
結果的頂層含有 _3minapi 鍵 |
host_stopped |
CLI 在執行中被停止 |
host_restarted |
電腦或 CLI 在執行中停止運作；於下一次 start 時回報 |
repeat_failed |
重複任務連續 5 次執行失敗 |
協定摘要
CLI 與 3Min API 如何協作，供參考。
傳遞
- Pull：即時模式下 CLI 保持連線，收到通知時（以及每次連線後一次）向 3Min API 詢問等待中的任務；定期檢查模式下每隔
pollIntervalMs詢問一次。兩種方式都只取走目前能執行的數量 - Ack：立即確認接收（
delivery變為"delivered"）。60 秒內未確認時，任務會再次送出 — 最多 6 次，之後為failed - At-least-once：同一任務可能到達兩次
- 取消：即時模式透過通知傳達，定期檢查模式在下一次取得時通知 →
ctx.signal。任務維持cancelled - 回報：進度與最終結果以主機權杖傳回。因網路失敗的回報會重試，最長 24 小時
大小
| 項目 | 限制 |
|---|---|
input |
100 KB |
| 傳送的結果 | 約 100 KB（100 KiB 減去 1 KiB 的封裝） |
ctx.report |
256 個字元 |
| 錯誤訊息 | 4,000 個字元 |
| Worker 描述 | 500 個字元 |
| Worker 名稱 | 50 個字元 |
3minapi.json（優先順序：旗標 > 環境變數 > 專案檔案 > 預設值）
| 鍵 | 預設值 | 範圍 | 環境變數 |
|---|---|---|---|
workersDir |
workers |
專案內 | — |
receiveMode |
live |
live 或 poll |
THREEMINAPI_RECEIVE_MODE |
pollIntervalMs |
60000 | 5000–3600000（僅定期檢查模式） | THREEMINAPI_POLL_INTERVAL_MS |
concurrency |
4 | 1–50 | THREEMINAPI_CONCURRENCY |
localServerPort |
3180 | 1024–65535 | THREEMINAPI_LOCAL_SERVER_PORT |
logRetentionDays |
30 | 1–365 | THREEMINAPI_LOG_RETENTION_DAYS |
logMaxBytes |
300 MB | 10 MB–1 GB | THREEMINAPI_LOG_MAX_BYTES |
變更 receiveMode、pollIntervalMs 或 concurrency 需要重新啟動。未知的鍵只會產生警告。
資料夾 — 3minapi paths 會輸出它們。
| OS | 權杖與設定 | 控制資料庫與日誌 |
|---|---|---|
| macOS | ~/Library/Application Support/3minapi |
~/Library/Application Support/3minapi、~/Library/Logs/3minapi |
| Windows | %APPDATA%\3minapi |
%LOCALAPPDATA%\3minapi |
| Linux | $XDG_CONFIG_HOME/3minapi（~/.config） |
$XDG_STATE_HOME/3minapi（~/.local/state） |
權杖存放在這些資料夾中，而不是專案中，因此複製專案不會複製權杖。
隱私說明
- Worker 的
result與error會原樣進入 AI 對話。只回傳需要的內容 data.db會把所有結果（包含其中的個人資料）保存在你的電腦上，直到你清理為止