AI Skills
paseo

paseo

热门

用于管理工作区、工作区脚本、Agent、定时任务（Schedule）和心跳检测（Heartbeat）的 Paseo 参考指南。

1.2万Star
1186Fork
更新于 2026/8/1
获取 Skill源代码

相关 Skills

archify-review6.5万agent-base-template-generator7.2万github-triage6.8万
SKILL.md
只读
名称
paseo
描述

用于管理工作区、工作区脚本、Agent、定时任务（Schedule）和心跳检测（Heartbeat）的 Paseo 参考指南。

Paseo 是一个用于在本地监督和管理 AI 编程 Agent 的后台守护进程（daemon）。你可以通过 Tool 接口或命令行（CLI）来控制它。

工作区（Workspaces）

create_workspace — 独立于任何 Agent 创建一个工作区。必填参数：isolation（取值为 local 或 worktree）。Worktree 隔离模式支持 mode: "branch-off" | "checkout-branch" | "checkout-pr"：新建分支使用 branchName/baseBranch，检出已有分支使用 branch，拉取变更请求（PR）使用 prNumber 并可选配置 forge/projectPath。worktreeSlug 用于控制托管路径。该方法返回以 workspaceId 为核心的工作区描述符。

list_workspaces — 列出所有活跃的工作区。

archive_workspace — { workspaceId }。归档工作区及其关联的 Agent 和终端。本地目录会被保留；对于 Paseo 托管的 worktree，只有在最后一个引用它的活跃工作区被归档后，Paseo 才会将其清理。

Worktree 的创建与引用计数属于 isolation: "worktree" 的内部实现细节。

工作区脚本（Workspace scripts）

在 paseo.json 中配置的脚本支持通过 Tool 接口或 CLI 进行统一的受控生命周期管理。

list_workspace_scripts — { workspaceId }。列出已配置的脚本，包含生命周期状态、服务端口、代理 URL、健康状况、退出码和终端 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>]

Agent 管理

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 上下文中创建 Agent 时，创建出的始终是你的子 Agent（subagent）。省略 workspaceId 时默认使用当前工作区；如果传入由 create_workspace 返回的工作区，则可实现隔离委派。存放位置不会改变父子层级关系。

脱离关联（Detach）是子 Agent 追踪链路中的显式用户操作，而非 Agent 自身的工具方法。即便跨工作区的子 Agent 在对应工作区中显示为一个普通标签页，它依然属于你的子 Agent。

在 Agent 上下文调用 create_agent 时，notifyOnFinish 默认值为 true。仅当任务真正属于无需关注结果的类型（fire-and-forget）时，才应将其设为 false。

send_agent_prompt — { agentId, prompt }。用于向现有的 Agent 追加提示词。在 Agent 上下文中调用时，默认 background: true 且 notifyOnFinish: true；顶层调用默认采用阻塞式（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 的能力与特性。必填参数：provider；在非 Agent 上下文会话中需传入 cwd。可选参数：settings（可包含草稿阶段的 model、modeId、thinkingOptionId 和 features）。

注意仅设置由 inspect_provider 返回的特性 ID。例如配置 Codex 极速模式，找到 fast_mode 后，向 create_agent 或 update_agent 传入 settings: { features: { "fast_mode": true } }。

定时任务与心跳检测（Schedules and 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 设计上故意未提供心跳更新工具；若任务或周期发生变更，请删除后重新创建。

Schedule 拥有完整的查询/探查/更新/暂停/恢复/单次运行/日志/删除接口；而 Heartbeat 则特意不提供这些复杂管理接口。

编排偏好设置（Orchestration preferences）

位于 ~/.paseo/orchestration-preferences.json 的用户个性化配置文件。任何 Paseo Skill 在选择 provider 或创建 Agent 前，都必须读取此文件。 这里的“读取”指的是真正的文件读取操作，而不是依赖文档里的示例或默认值。切勿在其他 Skill 中硬编码 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": [
    "对于艺术类或偏向人类人文技能的任务（如文案撰写、命名、UX 文案、视觉设计、样式排版），Claude Opus 是最佳选择；而 Codex 则是处理机械化工作的基石。"
  ]
}

若配置文件不存在，请使用合理的默认值并向用户提示一次。

本文档中展示的所有 provider 仅作示例，你必须使用在 preferences 中解析出的真实 provider，或通过调用 Paseo 的 provider 工具查找有效的 provider。

等待机制（Waiting）

Agent 执行需要时间 — 耗时 10 到 30 分钟以上十分常见。请优先选择异步工作流。

对于 Agent 作用域下的 create_agent 和后台运行的 send_agent_prompt，除非任务确实属于完全无需关注结果的类型（fire-and-forget），否则请保持 notifyOnFinish 缺省或显式设为 true。当目标 Agent 完成、报错或需要授权许可时，你会收到通知。此时你可以放心处理其他工作，通知届时会自动送达。

切勿通过轮询 list_agents 或 get_agent_status 来“检查”正在运行的 Agent，等待自动通知即可。

CLI 语义

即使 CLI 与 Tool 接口语法存在差异，两者的所有权语义是一致的：

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）会将该文件软链接至 ~/.local/bin/paseo（macOS/Linux），或者生成一个 .cmd 脚本（Windows），并通过 Shell 配置文件将 ~/.local/bin 添加至 PATH。如果该机制未生效，可以主动询问用户是否需要建软链接 — 绝不要静默替用户创建。

运维与调试（Ops and debugging）

系统采用 Daemon-Client 架构：Daemon 负责管理 Agent 的生命周期、状态和 WebSocket API。Tools、CLI、移动端及桌面端应用均作为客户端连接。

默认值
监听地址 127.0.0.1:6767（可用 PASEO_LISTEN 覆盖）
主目录 ~/.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
健康检查 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。