Dropstone CLI

故障排查指南

系统性地诊断 Dropstone CLI 问题。收集正确的信息，找到日志，并在联系支持之前隔离原因。

大多数问题都可以归结为以下四种原因之一：旧版本构建、过期的缓存、错误的凭据或网络问题。本页面列出了检查这些问题的顺序，以及当问题不属于其中任何一种时应该收集哪些信息。

对于特定的错误消息，请先查看常见问题。有关运行时行为和按功能调试的信息，请参阅CLI 故障排查。

首先尝试的三件事

在进行其他操作之前，先运行以下命令。它们能解决相当一部分报告的问题。

# 1. 获取最新版本
dropstone update

# 2. 查看 Dropstone 实际在做什么
dropstone --log-level DEBUG --print-logs
  1. 如果失败发生在会话中途且原因不明，请清除缓存并重新启动：
rm -rf ~/.cache/dropstone

在 Windows 上，按 WIN+R 并删除 %USERPROFILE%\.cache\dropstone。

在删除其他内容之前

上述三个命令是安全的。删除 ~/.local/share/dropstone 则不安全——那里存放着你的凭据和会话历史。在删除该目录之前，请参阅状态存储位置。

状态存储位置

Dropstone 在磁盘上保存的所有内容都位于两个目录中。

内容macOS / LinuxWindows
凭据和会话~/.local/share/dropstone/%USERPROFILE%\.local\share\dropstone
日志~/.local/share/dropstone/log/%USERPROFILE%\.local\share\dropstone\log
缓存~/.cache/dropstone/%USERPROFILE%\.cache\dropstone

在数据目录内：

  • auth.json — 你的凭据。仅在你需要强制重新登录时删除此文件。
  • log/ — 带时间戳的日志。保留最近十条。
  • project/ — 会话历史，按项目范围划分。

日志文件以其写入时间命名，例如 2026-05-23T123456.log。最新的那个就是你需要的。

获取一份值得阅读的日志

默认情况下，日志级别是安静的。两个标志可以改变这一点：

# 将详细输出写入日志文件
dropstone --log-level DEBUG

# 将相同输出实时流式传输到终端
dropstone --print-logs

当你希望观察失败发生的过程并同时保留日志文件时，可以将两者一起使用。

如果问题是启动时崩溃，--print-logs 是更有帮助的那个：在进程退出前，日志文件可能根本不会被写入，但 stderr 始终会被写入。

报告中应包含的内容

一份包含以下五项内容的报告通常只需要一次回复就能解决。缺少这些内容的报告通常需要四次回复。

  1. 你运行的确切命令。 不是转述——而是逐字逐句的命令行，包括所有标志。

  2. 你期望的结果，以及实际发生的情况。 两部分都需要。"它失败了"并不能缩小任何范围。

  3. 你的版本和平台。

    dropstone --version

    再加上你的操作系统和版本，以及你是在原生 Windows 上还是在 WSL 内运行。

  4. 相关的日志摘录。 错误前后各几行，而不是整个文件。请对任何敏感内容进行脱敏处理——会话日志可能包含文件路径和代码。

  5. 问题是否可以重现。 总是、有时，还是仅一次。"有时"值得说明；它指向的是时序或状态问题，而不是错误输入。

将其发送至 dropstone.io/contact。

逐步缩小范围

如果原因仍然不明显，请逐一消除变量。以下每一项都能排除一整类问题。

是项目的问题吗？ 在空目录中运行 Dropstone。如果在那里正常工作，则问题与项目相关——很可能是配置文件、规则文件或代理正在读取的仓库中的某些内容。

是你的配置问题吗？ 暂时将 dropstone.json 移开并重新启动。有关全局和项目配置文件的位置，请参阅配置。

是 MCP 服务器的问题吗？ 启动时挂起的服务器会拖慢整个会话。列出它们并禁用，然后逐一重新启用：

dropstone mcp list

是网络问题吗？ 公司代理是导致看似其他问题的最常见原因。检查：

curl -I https://dropstone.io

如果该命令失败或返回意外结果，请参阅网络和代理。通常的解决方法是设置 HTTPS_PROXY，并且重要的是设置 NO_PROXY=localhost,127.0.0.1——Dropstone 在交互式会话期间使用本地回环，将其路由到代理会导致循环。

是凭据问题吗？ 退出并重新登录：

dropstone auth logout
dropstone auth login

是终端的问题吗？ 在 Linux 上，复制和粘贴需要安装剪贴板工具。请参阅CLI 故障排查。

是 Windows 的问题吗？ 原生 Windows 上的文件访问缓慢、终端故障和路径问题通常在 WSL 下会消失。请参阅Windows 和 WSL。

联系支持之前

相关链接

Ctrl+I