pstack 完全指南（第一部分）

在本系列文章中，我将向您展示我如何使用 pstack——这是我个人用于进行严谨工程实践的技能集。它使我能够每月向生产环境部署 2,000 个 PR，并保持高度信心。就我个人而言，我从未过分关注自己写了多少行代码或提交了多少个 PR。在智能体出现之前，没人在乎这些，这理所当然，因为原始生产力并不总是等同于产品质量或为用户带来可见成果。那仅仅是一个虚荣指标。但在构建 pstack 的过程中，我发现了数量确实很重要，尤其是当你能够借助智能体保持甚至提升产品质量时。例如，我大约两个月前开始开发 Grok @Bot，当时它还处于早期阶段，代码库虽然新鲜但已开始增长。尽管团队不断壮大，每天有数百个 PR 合入 Grok @Bot 代码库，pstack 使我能够持续监控代码、重构、增加新的 lint 规则和检查，同时也开发新功能，从而为所有人保持代码的高质量。

lauren@poteto · 8月21日
每个团队都需要一位园丁。静静注视着涌入代码库的 PR 流，察觉那些“异味”：本周第三个 isRecord，像常春藤一样蔓延的 lint 抑制。稳健之手修剪着杂草，它们会吞噬…

lauren@poteto · 7月19日
有机架构：好的代码库一直拥有坚实的基础和约束。这些文件放这里。那类代码放那里。代码库要么通过迎合使用传统框架和语言的最低标准开发者来维系，要么…

作为 Grok @Bot 的园丁和维护者，我唯有通过 pstack 才能做到这一点。在构建原型之后，我们初期势头非常强劲，许多人加入了团队。我有一个关键的机会窗口，在代码库被构建和扩展且无停机时间的情况下，将其重构为具有坚实基础的结构。一个无论有多少工程师（更重要的是非工程师）参与贡献，都能保持高质量的可扩展代码库。所有这些工作都要求我在构建 Grok Bot 的同时重构和改进其基础，而唯有当基础架构能够跟上贡献数量时，你才能做到这一点。Grok Bot 是市场上最高效、性能最优的 AI 桌面应用之一。Grok Bot 是市场上最高效、性能最优的 AI 桌面应用之一。证据就在 Grok @Bot 本身。在接下来的几周里，我将告诉你使用 pstack 构建和维护一个高质量应用所需的一切。

第一部分：验证是你的全部所需

你工具箱中最关键的技能是一项高质量的验证技能。这项技能如此重要且值得维护，我更倾向于将其视为关键基础设施，而不仅仅是“一项”技能。一个优秀的验证技能能提升你整个团队的产出，包括非工程师。做好了，你将使整个团队的产出提升 100 到 1000 倍。如果你不熟悉这个术语，验证意味着智能体可以验证自己的工作。它能够持续运行直到成功完成任务，因为它现在可以闭环工作，无需你成为瓶颈。如果你有兴趣了解更多关于我如何为 Cursor 创建第一个验证技能的故事，请查看我之前的文章《可信赖的循环》。

让我们一起构建一个验证技能

首先，安装 pstack，然后运行 /create-verification-skill。我还建议将 Dr Eggbot（我的助手机器人，帮助你创建高质量机器人）添加到你的阵容中。Dr Eggbot 随 pstack 提供。它会教编码机器人如何使用它，也能以同样的严谨度创建非编码机器人。你可以让 Dr Eggbot 为你创建一个工程师机器人，然后让它运行 /create-verification-skill 并设置每日任务来运行 /maintain-verification-skill。

love Dr Eggbot
love Dr Eggbot

当它运行时，让我们来了解一下这个技能的作用，以及它如何为你创建一个高质量的验证技能。我将我们用于构建 Grok @Bot 和 Cursor 的所有验证技能提炼成了这个技能，它是一种元技能。它教你自己的智能体如何为你的应用创建一个高质量的验证技能。

现在，这里技术栈的选择就很重要了。例如，如果你正在构建一个基于 Electron 或 Web 的应用，你可以利用 JS 生态系统丰富的调试工具。例如，Chrome DevTools Protocol (CDP) 允许你使用与浏览器开发者工具相同的工具。或者，如果你正在构建一个 iOS 应用，可以利用模拟器。你理想中需要的是与应用交互、调试、获取性能跟踪以及任何其他调试和开发工具的能力，就像你手动开发应用时会使用的那样。如果你没有丰富的运行时环境可供使用，你可能需要要求你的智能体为你创建工具（例如，使用 lldb，或在开发环境中作为 sidecar 运行的自定义包），或者就利用你现有的资源。我个人认为智能体验证如此重要，以至于我会认真地建议构建自己的丰富调试工具，甚至选择不同的技术栈，以在构建软件方面获得不公平的优势和极高的生产力。正如我之前提到的，赋予智能体验证自己工作的能力，能让你组织中的每个人都能够贡献并验证他们的更改是否确实有效。你的技术栈越难调试和控制，使用智能体高效工作就越困难。

使其可复现 在 pstack 中，我们有一个名为“构建杠杆”的原则。在创建技能的语境下，这意味着我们更倾向于给智能体工具，而不仅仅是 markdown 文档。对于验证技能，这意味着创建一个小的 CLI 工具，将应用交互和调试脚本化，使其成为一个小型、对智能体友好的实用程序。这意味着智能体在执行任务时消耗更少的 token（运行一个 CLI 命令而不是编写一个临时脚本来点击某处），并使你的验证技能更具可复现性和可测试性。这里有一个假设的例子，展示了智能体可能为 Electron 应用创建的 CLI：

# 健康检查
node .cursor/skills/verify-atlas/control-atlas.mjs doctor

# 打开一个空白线程并发送消息
node .cursor/skills/verify-atlas/control-atlas.mjs new-session
node .cursor/skills/verify-atlas/control-atlas.mjs send "列出此项目中的待处理任务"

# 键盘快捷键
node .cursor/skills/verify-atlas/control-atlas.mjs press "Meta+KeyN"

# 实时 UI 的无障碍快照
node .cursor/skills/verify-atlas/control-atlas.mjs snapshot

# 截图作为证据
node .cursor/skills/verify-atlas/control-atlas.mjs screenshot /tmp/atlas-proof.png

# 等待流式处理/布局稳定
node .cursor/skills/verify-atlas/control-atlas.mjs wait-settle

# 为会话切换功能开关
node .cursor/skills/verify-atlas/control-atlas.mjs feature-flag rooms_v2 on

现在，所有智能体都可以使用这个 CLI 来快速导航和调试你的应用。你还需要开始思考构建应用时的开发体验：

• 填充开发数据库
• 如何处理认证、测试用户、对测试/预发环境的 API 调用
• 以一致的方式安装并启动你的开发环境 所有这些都是你自己写代码时可能已经需要考虑的事情。所以，把这当作智能体在你应用上进行开发工作的主要实用工具。保持它的良好维护和测试！你可能还想考虑的其他示例命令：

- ****检查：**** `info`、`snapshot`、`screenshot`、`components`
- ****导航：**** `home`、`new-session`、`select-project`、`select-runtime`、`scroll`
- ****交互：**** `send`、`click`、`click-xy`、`aria-click`、`type`、`press`、`eval`、`upload-image`、`add-context`、`feature-flag`
- ****性能：**** `trace`、`profile`、`record`、`perf-metrics`、`wait-settle`
- ****流式处理：**** `console`、`network-log`、`network-summary`
- ****健康与清理：**** `doctor`、`cleanup`、`watch --restart`

一旦你有了这个基础设置，你应该就能看到智能体能力的显著提升。它们应该能够轻松地在你的应用中导航和调试。我建议在这里花时间把这个 CLI 做好并确保无错误，然后再进行任何更高级的操作。你还需要思考（或要求你的智能体）设计一个对智能体友好的 CLI。网上有很多资源可以提供给你的智能体，但我喜欢的关键属性是：

• API 易于组合（想想 John Ousterhout 的深度模块哲学）
• 任何可能有破坏性副作用的命令都应有 --dry-run 选项
• 利用子命令逐步暴露功能，而不是一次全部展示
• 错误消息应非常清晰，告诉智能体它应该做什么而不是什么
• 丰富的 --help 文本
• 输出以机器可读的形式返回（例如 JSON）

使用云智能体并行化，而非工作树，从而加速 当你在使用验证技能成功提交了几个 PR 后，你可能会开始思考是否可以进一步并行化。例如，如果一个智能体现在能够接受你的提示并将其大部分推进到可合并状态，这不就让你可以运行更多智能体了吗？你的第一直觉可能是添加工作树支持，这意味着你的智能体可以使用 git 创建一个仓库的跟踪副本，在其中进行与主检出隔离的更改。理论上，这让你可以同时运行多个智能体，而他们的更改不会相互冲突。我建议不要这样做。首先，它占用大量的存储空间和机器资源。根据你的仓库大小和机器性能，你或许可以同时运行最多 10 个使用工作树的智能体。但有一个好得多的方法！Cursor 的云智能体是在云端、Cursor 基础设施上运行的智能体。这些智能体可以访问真实的计算机，这意味着它们可以安装依赖项、运行你的应用、录制视频和截图，并像真实用户一样与你的应用交互。如果你在上一步投入足够多，让开发体验变得良好，设置云智能体就不会有太大困难。当你首次设置云环境时，我们会派一个智能体帮助你正确设置和运行。第一次构建后，我们会创建一个快照，这意味着后续的云智能体运行总是能快速启动。我强烈建议花时间设置云智能体，因为它能解锁生产力的巨大提升和并行化。在后面的文章中，我将展示我如何在云端并行运行数百个子智能体！但现在，请设置你的环境，并让它达到一个你可以开始有信心在云端运行所有智能体的状态。

使用功能地图保持智能体的智能 随着你的应用变得越来越复杂，智能体需要更多指导才能找到功能并与之交互。为此，我想出了一个叫做“功能地图”的东西。顾名思义，它是你应用中所有可用功能的易于搜索的地图，包括功能描述以及从用户视角如何访问它。这里有一个我为虚构应用 Atlas 准备的功能地图示例。它只是几个 markdown 文件，在验证技能的 SKILL.md 中被引用。你可以把这个文件放在任何地方，但在 /create-verification-skill 中，我们会自动在 references/features 目录下创建一个 README.md。这个 README 本身就是地图：所有主要功能的高级概览，并链接到具体细节。一个功能条目看起来像这样：

# 偏好设置
全屏偏好设置覆盖层及其选项卡集。

## 子功能
- settings-overlay：从齿轮图标或 Cmd/Ctrl+, 打开的全屏覆盖层。
- settings-nav：左侧的选项卡导航（通用、外观、模型、计划与用量等）。
- settings-search：覆盖层内搜索（设置打开时按 Cmd/Ctrl+K）。
- theme-picker：外观设置中的快速主题控制。

## 如何访问（用户视角）
点击账户头像旁的齿轮图标，或按 Cmd/Ctrl+,。从左侧导航中选择一个选项卡。在偏好设置搜索框中输入以跳转。按 Escape 或关闭控件可关闭。

## 使用 control-atlas 驱动
bash
node .cursor/skills/verify-atlas/control-atlas.mjs press "Meta+Comma"
node .cursor/skills/verify-atlas/control-atlas.mjs snapshot
node .cursor/skills/verify-atlas/control-atlas.mjs press "Escape"

• 覆盖层根节点：在无障碍树中查找名为 Preferences 的对话框/区域。
• 选项卡：按可见名称点击。计划与用量可能因账户状态而缺失。
• 当设置打开时，Cmd/Ctrl+K 是偏好设置搜索，而非全局命令面板（参见 multi-surface-journeys.md）。

注意事项

• 在测试套件中途关闭设置可能导致焦点停留在无用位置。new-session 或 home 可恢复。
• 某些选项卡受权限限制。可使用明确的账户原因跳过。

不用担心自己编写这些！当你运行 /create-verification-skill 时，你的智能体会自动遍历你的应用，对所有功能进行编目并创建这些参考文件。功能地图与 CLI 结合，是 pstack 验证技能如此出色的主要原因之一。智能体现在拥有了关于每个功能以及如何访问它的上下文，节省了宝贵的上下文窗口 token，并准确地教会了它功能是什么以及如何访问。你可以将功能地图视为一种“物化记忆”。如果你使用智能体有一段时间了，你可能熟悉记忆的概念——通常这些记忆存储为简单的 markdown 文件（如 Obsidian 库），甚至是更复杂的东西如向量数据库。就我个人而言，我认为你的代码库是记忆的终极形式。代码是你和团队所做决策的投射，代表了发生的事情以及事物实际如何运作的真实来源。功能地图只是其更紧凑的形式，旨在节省 token。并且因为它只是技能内的 markdown，所以所有为代码库做贡献的人都能受益于这种共享记忆。这意味着维护验证技能非常重要。我建议至少每天运行一次 /maintain-verification-skill，以确保你的智能体始终拥有控制应用的最新细节。你可能也会发现，随着你更多地使用验证技能，智能体在你的应用上工作时会自动更新它们。/maintain-verification-skill 会捕获所有遗漏的内容。

如何使用你的验证技能

供参考，这里有一个为虚构应用创建的验证技能示例：https://github.com/poteto/verification-skill-example。再次提醒，运行 /create-verification-skill 来创建一个，它包括一个基本的 CLI 和功能地图。以下是我通常如何使用它配合 pstack。首先，当然是用 /poteto-mode 开始你的提示。如果你通过 Cursor 使用 pstack，你也可以在自动补全 /poteto-mode 时按 Opt + Enter 而不是仅按 Enter——这会将该技能添加为自定义模式，从而固定该技能，让你的智能体在每个新回合都得到提醒去使用它。输入 /poteto-mode 并按 Opt + Enter 将其固定为自定义模式。在 Grok @Bot 中，安装插件，然后输入 /poteto-mode。你也可以在 Grok Bot 中使用 pstack！你也可以在 Grok Bot 中使用 pstack！

示例：构建新功能 对于构建新功能，我通常会结合使用验证技能和 /poteto-mode，让智能体验证其工作。例如，我可能会提示…