AI Skills
paseo

paseo

熱門

用於管理工作區、工作區腳本、Agent、排程與心跳（heartbeat）的 Paseo 參考指南。

1.2萬星標
1186分支
更新於 2026/8/1
獲取技能源代碼

相關技能

archify-review6.5萬agent-base-template-generator7.2萬github-triage6.8萬
SKILL.md
唯讀
名稱
paseo
描述

用於管理工作區、工作區腳本、Agent、排程與心跳（heartbeat）的 Paseo 參考指南。

Paseo 是一套在你的電腦上監控與管理 AI 程式碼 Agent 的背景服務（daemon）。你可以透過工具或命令行介面（CLI）來控制它。

工作區

create_workspace — 建立一個獨立於任何 Agent 之外的工作區。必填：isolation（local 或 worktree）。Worktree 隔離模式支援 mode: "branch-off" | "checkout-branch" | "checkout-pr"：建立新分支請使用 branchName/baseBranch，切換至既有分支請使用 branch，拉取 Change Request 請使用 prNumber 搭配可選的 forge/projectPath。worktreeSlug 用於控制受管路徑。回傳以 workspaceId 為中心的工作區描述符（descriptor）。

list_workspaces — 列出目前活躍的工作區。

archive_workspace — { workspaceId }。封存該工作區及其旗下的 Agent 和終端機。本機目錄會保留；只有在最後一個指向該 Worktree 的活躍工作區引用被封存後，Paseo 才會移除其所擁有的 Worktree。

Worktree 的建立與引用計數（reference accounting）屬於 isolation: "worktree" 的實作細節。

工作區腳本

在 paseo.json 中設定的腳本，無論是透過工具或 CLI 操作，均遵循相同的受管生命週期。

list_workspace_scripts — { workspaceId }。列出已設定的腳本及其生命週期、服務連接埠（port）、代理 URL、健康狀況、結束代碼（exit code）與終端機 ID。

start_workspace_script — { workspaceId, scriptName }。透過 Paseo 的受管工作區腳本啟動器執行指定的設定腳本，並回傳其狀態元資料。

stop_workspace_script — { workspaceId, scriptName }。透過其受管終端機停止正在執行的腳本，並回傳停止後的狀態元資料。

對應的 CLI 操作可接受明確指定的工作區 ID，或是直接解析目前所在目錄：

paseo script ls [--cwd <path> | --workspace <workspace-id>]
paseo script start <name> [--cwd <path> | --workspace <workspace-id>]
paseo script stop <name> [--cwd <path> | --workspace <workspace-id>]

Agents

create_agent — 必填：title、provider（claude/opus、codex/gpt-5.4…）、initialPrompt。選填：workspaceId、notifyOnFinish、settings、labels。回傳 { agentId, workspaceId, … }。

初始執行階段設定需放在 settings 之下：modeId、thinkingOptionId 以及各 Provider 特有的 features。若要啟用 Codex 的高速模式（fast mode），建立 Agent 時請傳入 settings: { features: { "fast_mode": true } }。

在 Agent 上下文中呼叫建立指令時，永遠會建立為你的 Subagent（子 Agent）。省略 workspaceId 代表使用當前工作區；傳入由 create_workspace 回傳的工作區則可用於獨立委派任務。存放位置（Placement）絕不會改變父子階層關係。

分離（Detach）是使用者在 Subagent 介面上明確執行的操作，並非 Agent 工具。即使跨工作區的子 Agent 顯示在其工作區的普通分頁中，它依然是你的 Subagent。

在 Agent 上下文中呼叫 create_agent 時，notifyOnFinish 預設為 true。只有在完全不需要追蹤後續（fire-and-forget）的任務時，才將其改為 false。

send_agent_prompt — { agentId, prompt }。用於向既有的 Agent 發送後續 Prompt。在 Agent 上下文中發送 Prompt 預設為 background: true 與 notifyOnFinish: true；頂層（top-level）呼叫則預設為阻塞模式（blocking）且不提供回呼。若需同步進行後續溝通，請傳入 background: false 並直接使用回傳結果。

update_agent — { agentId, name?, labels?, settings? }。利用 settings 來動態修改既有 Agent 的執行階段設定：modeId、model、thinkingOptionId 以及 Provider 特有的 features。若要開啟 Codex 的高速模式，請傳入 settings: { features: { "fast_mode": true } }。

list_agents — 可依 cwd、statuses、sinceHours、includeArchived 進行篩選。

archive_agent — { agentId }。若 Agent 正在執行中則進行中斷，並將其從活躍列表中移除。

Provider 探索

list_providers — 精簡列出可用 Provider 及其模式。

list_models — 列出特定 Provider 的完整模型清單。僅在需要獲取模型 ID 或思考選項（thinking options）時才使用，因為這份清單內容可能相當龐大。

inspect_provider — 精簡檢視 Provider 的功能與特性（features）。必填：provider；若非處於 Agent 上下文會話中，需傳入 cwd。選填：包含草稿版 model、modeId、thinkingOptionId 與 features 的 settings。

請僅設定由 inspect_provider 回傳的 Feature ID。如需啟用 Codex 高速模式，請確認回應中包含 fast_mode，並在呼叫 create_agent 或 update_agent 時傳入 settings: { features: { "fast_mode": true } }。

排程與心跳（Heartbeats）

create_schedule — 依照 Cron 週期啟動全新的 Agent。必填：prompt、cron、provider。選填：timezone、name、cwd、maxRuns、expiresIn。適合用在每次定期任務都應在全新 Agent 中執行的情境。

create_heartbeat — 依照 Cron 週期向你發送 Prompt。必填：prompt、cron。選填：timezone、name、maxRuns、expiresIn。適用於提醒事項、PR/Build 狀態看護，以及希望結果回傳至當前對話的狀態檢查。

delete_heartbeat 用於停止心跳。MCP 特意未提供更新心跳的工具；當任務內容或執行週期改變時，請刪除後重新建立。

排程功能提供完整的介面（包含 list/inspect/update/pause/resume/run-once/log/delete）；而心跳功能則刻意簡化，不提供這些延伸介面。

編排偏好設定（Orchestration preferences）

使用者專屬的設定檔位於 ~/.paseo/orchestration-preferences.json。在任何 Paseo Skill 選擇 Provider 或建立 Agent 之前，都必須先讀取此檔案。 讀取指的是真正執行檔案讀取操作，而非依賴本文件的範例或預設值。切勿在其他 Skill 中硬編碼（hardcode）Provider 字串，請一律透過此檔案進行解析。

包含兩個主要部分：

  • providers — 角色類別對應至 Provider 字串的映射表。可直接傳入 create_agent 的 provider 欄位。
  • preferences — 自由格式的字串陣列。啟動時讀取，並根據上下文融入 Agent 的 Prompt 中。

角色類別包括：impl、ui、research、planning、audit。Skill 會選擇與其欲啟動角色相符的類別。

{
  "providers": {
    "impl": "codex/gpt-5.4",
    "ui": "claude/opus",
    "research": "codex/gpt-5.4",
    "planning": "codex/gpt-5.4",
    "audit": "codex/gpt-5.4"
  },
  "preferences": [
    "Claude Opus is the right choice for anything artistic or human-skill-oriented: copywriting, naming, UX copy, visual design, styling. Codex is the workhorse for mechanical work."
  ]
}

若該檔案不存在，請採用合理的預設值，並提示使用者一次。

本文件中展示的所有 Provider 僅供參考，你必須透過讀取偏好設定檔或呼叫 Paseo 的 Provider 工具來解析出實際有效的 Provider。

等待機制

Agent 執行任務需要時間，耗時 10 至 30 分鐘以上是常態。建議優先採用非同步工作流程。

在 Agent 上下文中呼叫 create_agent 或非同步發送 send_agent_prompt 時，除非任務完全不需要追蹤，否則請保持 notifyOnFinish 為預設值或設為 true。當目標 Agent 完成、發生錯誤或需要權限時，你都會收到通知。此時你可以先處理其他工作，通知會在適當時候自動送達。

切勿透過輪詢（poll）list_agents 或 get_agent_status 來「檢查」執行中的 Agent。系統會在有進度時透過通知告知你。

CLI 語意

即使 CLI 與工具在語義上有所不同，它們內部使用相同的權限與所有權語意：

paseo workspace create --isolation worktree --mode branch-off --new-branch fix-x --base main
paseo workspace create --isolation worktree --mode checkout-branch --branch existing-work
paseo workspace create --isolation worktree --mode checkout-pr --pr-number 42
paseo run --provider codex/gpt-5.4 --mode full-access --workspace <workspace-id> "<prompt>"
paseo run --provider codex/gpt-5.4 --mode full-access --new-workspace worktree --worktree-mode branch-off --new-branch fix-x --base main "<prompt>"
paseo send <agent-id> "<follow-up>"
paseo ls
paseo schedule create --cron "*/15 * * * *" "ping main build"
paseo heartbeat create --cron "*/15 * * * *" "check the build"

欲探索更多用法，請執行 paseo --help 與 paseo <cmd> --help。

若 paseo 未加入 PATH 中但已安裝桌面版應用程式，隨附的 CLI 工具位於：

  • macOS: /Applications/Paseo.app/Contents/Resources/bin/paseo
  • Linux: <install-dir>/resources/bin/paseo
  • Windows: C:\Program Files\Paseo\resources\bin\paseo.cmd

桌面版應用程式首次執行時（installCli）會將其建立符號連結（symlink）至 ~/.local/bin/paseo（macOS/Linux），或放置 .cmd 跳板檔（Windows），並透過 shell 的 rc 檔將 ~/.local/bin 新增至 PATH。若該機制未生效，請主動詢問使用者是否要協助建立符號連結 — 切勿默默直接執行。

運作維護與除錯

背景服務與用戶端架構（Daemon-client architecture）：Daemon 負責管理 Agent 的生命週期、狀態以及 WebSocket API。工具、CLI、行動端與桌面端應用程式皆屬於 Client 端。

項目 預設值
監聽位址 (Listen address) 127.0.0.1:6767 (可透過 PASEO_LISTEN 覆寫)
主目錄 (Home) ~/.paseo (可透過 PASEO_HOME 覆寫)
Daemon 日誌 $PASEO_HOME/daemon.log
Agent 狀態 $PASEO_HOME/agents/<id>.json
Worktrees $PASEO_HOME/worktrees/ (或 config.json 中的 worktrees.root)
PID 檔 $PASEO_HOME/paseo.pid
健康檢查 (Health) GET http://127.0.0.1:6767/api/health

除錯建議順序：

  1. 執行 tail -n 200 ~/.paseo/daemon.log。
  2. 執行 paseo daemon status 檢查運作狀態。
  3. 若懷疑 CLI 本身有問題，可執行 curl -s localhost:6767/api/health。

未獲得使用者明確同意前，切勿重啟 daemon — 這會強制中斷所有正在執行的 Agent，通常也包含正在發問的這個 Agent 本身。