mcpField
P
paseo-help

paseo-help

github.com/getpaseoAgent 工作流22.3k1.5k 次安装今天更新
代码仓库

关于 paseo-help

paseo-help 是用于解答 Paseo 配置和故障排查问题的技能。它会核对最新公开文档，并根据守护进程的运行位置及客户端连接方式开展诊断。

主要功能

  1. 01获取当前文档索引
  2. 02选择并核对相关文档
  3. 03确认守护进程与客户端连接拓扑
  4. 04使用只读诊断检查
  5. 05收集升级处理所需证据

适用场景

  1. 01排查 Paseo 连接问题
  2. 02检查提供方或守护进程配置
  3. 03为缺陷报告整理证据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/getpaseo/paseo --skill paseo-help

安装后在 Claude Code 中输入/paseo-help确认已加载。

详细介绍

Paseo 帮助

帮助用户了解、配置或排查 Paseo 本身的问题。直接回答用户的问题，根据当前公开文档核实答案，并附上相关文档链接。不要让用户自己去读文档，而不提供帮助。

用户的问题： $ARGUMENTS

使用当前文档

先获取 https://paseo.sh/llms.txt。这是 Paseo 文档的当前索引，包含每个页面的说明和 Markdown URL。

使用该索引选择与用户问题对应的页面，然后在回答前获取链接指向的 .md 页面。排查问题时，请从 常见问题 开始；如果问题属于更具体的页面，请继续查看该页面。

优先使用已部署的文档，不要依赖记忆。直接回答用户，然后将相关 .md 页面作为参考文档链接。

先确定拓扑结构

在诊断版本、路径、提供方、日志、更新或连接问题之前，先确定涉及哪个守护进程。不要根据客户端推断守护进程：Paseo Desktop 可以管理随附的本地守护进程，同时连接其他远程守护进程。

确定以下两点：

  1. 守护进程的运行位置和方式
    • 由桌面应用管理： Paseo Desktop 在该计算机上随附、启动并更新守护进程。无需单独安装守护进程。
    • 独立运行： 守护进程是单独安装的，通常通过 npm CLI 安装，并独立于桌面应用运行。
    • Docker： 守护进程及其主目录、提供方 CLI、凭据和代码挂载都位于容器运行时中。
  2. 受影响的客户端如何连接到它
    • 同一台计算机上的本地连接
    • 中继连接
    • 直接通过 LAN、VPN 或 Tailscale 连接
    • 由守护进程提供的 Web UI

使用 设置 → 关于，比较应用版本与每个已连接主机的版本。对于受影响的主机，打开 设置 → 你的主机 → 概览 → 完整状态。在守护进程所在的计算机上，paseo daemon status --json 会报告服务器 ID、主机名、版本、主目录、监听地址、进程所有者、日志路径，以及守护进程是否由桌面应用管理等信息。

记录用户正在查看哪个主机，以及运行该主机的计算机或容器。paseo daemon status 只描述该 CLI 本地 PASEO_HOME 对应的守护进程；它可能不是应用中显示的远程主机。

后续检查应针对守护进程的运行环境，而不是默认针对客户端设备：

  • 提供方二进制文件、凭据、PATH、工作区、配置和守护进程日志都位于守护进程所在的计算机或容器中。
  • 应用版本和应用日志位于客户端设备上。
  • 由桌面应用管理的守护进程遵循 Desktop 应用的生命周期和更新方式。
  • 独立守护进程遵循自身的 CLI/npm 生命周期，且可能使用不同的 PASEO_HOME 或监听地址。
  • Docker 守护进程使用容器路径、卷、用户权限、镜像版本和容器生命周期命令。

更改状态前先诊断

确定受影响的主机后，比较其守护进程版本与客户端应用版本。请用户根据对应的拓扑专用更新路径更新两者。旧版本以及应用与守护进程版本不一致会导致许多表面上的问题，而且修复会频繁发布。请参阅“更新”页面和对应安装方式的文档，了解当前说明。

使用最少且相关的只读检查：

paseo --version
paseo daemon status --json
paseo provider diagnostic <provider> --json

使用状态报告的主目录、监听地址和日志路径进行后续检查。只有当这些值与受影响的守护进程匹配时，才探测 http://127.0.0.1:6767/api/health 或读取 ~/.paseo/daemon.log。未经用户明确许可，不要重启守护进程、编辑配置、更新软件或开放网络监听器。重启守护进程可能会中断正在执行诊断的 Agent。

如果缺少提供程序或出现 command not found，请在受影响的主机上运行 paseo provider diagnostic <provider>，或打开 设置 → 你的主机 → 提供程序 → 提供程序 → 诊断。将其解析出的二进制文件、守护进程的 PATH 和提供程序版本与全新的登录 shell 进行比较。Shell 别名和函数不是可执行路径。

日志和本地文件

在守护进程或 Desktop 应用实际运行的机器上使用以下默认路径。不要在客户端设备上查找远程守护进程的文件。

  • 守护进程配置：~/.paseo/config.json
  • 守护进程日志：~/.paseo/daemon.log
  • Agent 状态目录：~/.paseo/agents/
  • 默认托管工作树根目录：~/.paseo/worktrees/
  • macOS 桌面日志：~/Library/Logs/Paseo/main.log
  • Linux 桌面日志：~/.config/Paseo/logs/main.log
  • Windows 桌面日志：%APPDATA%\Paseo\logs\main.log

将 ~/.paseo 替换为状态报告的 PASEO_HOME。在官方 Docker 镜像中，默认值为 /home/paseo/.paseo；其主机路径取决于卷挂载，容器标准输出可通过 Docker 查看。Desktop 应用日志描述 Desktop 进程；守护进程日志描述所选的守护进程。只读取最小范围内的相关内容，并在分享日志前删去凭据、配对邀请、令牌、密码和用户代码。

如果要诊断安装了 Paseo Desktop 的计算机上的捆绑守护进程，但 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

可以提出修复 PATH 或创建符号链接，但不要擅自更改 shell 配置。

提交问题并附上证据

如果当前文档和诊断无法解决问题，请收集应用和守护进程版本、操作系统、安装方式、连接方式、准确错误信息、最小复现步骤以及一小段脱敏日志。

评论

支持 Markdown