pstack 完全指南：第一部分

在这个系列的文章中，我将向你展示如何使用 pstack（我个人的一套用于进行严谨工程工作的技能）。它让我能够每月自信地向生产环境交付 2,000 个 PR。

就我个人而言，我从未过分强调自己写了多少行代码或提交了多少个 PR。在 Agent 出现之前，没人关心这些，而且理所当然，因为原始生产力并不总是等同于质量或用户可见的成果。这只是一个虚荣指标。

但在构建 pstack 的过程中，我发现数量确实很重要，尤其是当你能够借助 Agent 保持甚至提升产品质量时。例如，大约两个月前，我开始在 Grok @Bot 上工作，当时它还处于早期阶段，代码库很新但开始增长。尽管团队在壮大，现在每天有数百个 PR 合并到 Grok @Bot 的代码库中，但 pstack 让我能够为所有人保持高代码质量，因为我持续监控代码、重构、添加新的 lint 和检查，同时也在开发功能。

https://x.com/poteto/status/2090546476464451907

https://x.com/poteto/status/2078527882499150286

成为 Grok @Bot 的园丁和维护者，是我只能通过 pstack 才能做到的事情。在构建原型后，我们早期的势头非常强劲，许多人加入了团队。我抓住了一个关键时机，在代码库被构建和扩展且不停机的情况下，对整个代码库进行了重构，使其拥有了坚实的基础。一个高质量、可扩展的代码库，无论有多少工程师（最重要的是，非工程师）为其贡献代码，都能保持稳定。所有这些工作都要求我在 Grok Bot 被构建的同时，重构和改进其基础，而只有当基础能够跟上贡献数量时，你才能做到这一点。

Grok Bot 是市场上最高效、性能最佳的 AI 桌面应用之一

证据就在 Grok @Bot 本身。在接下来的几周里，我将告诉你使用 pstack 构建和维护一个高质量应用所需的一切知识。

第一部分 – 验证即一切

你的工具箱中最关键的技能是一个高质量的验证技能。这个技能如此重要且需要维护，以至于我更愿意将其视为关键基础设施，而不仅仅是“一个”技能。一个好的验证技能将放大整个团队（包括非工程师）的产出。如果做得好，你整个团队的产出将提升 100 到 1000 倍。

如果你不熟悉这个术语，验证 意味着 Agent 可以验证自己的工作。它可以持续进行，直到成功完成任务，因为它现在可以闭环，而无需你成为瓶颈。如果你有兴趣了解更多关于我如何为 Cursor 创建第一个验证技能的故事，请查看我之前的文章 你可以信任的循环。

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

首先，安装 pstack，然后运行 /create-verification-skill。我还建议将 Dr Eggbot（我的一个帮助你创建高质量 Bot 的 Bot）添加到你的阵容中。Dr Eggbot 随 pstack 一起提供。它会教编码 Bot 如何使用它，并且它也可以用同样的严谨性创建非编码 Bot。

你可以让 Dr Eggbot 为你创建一个工程师 Bot，然后你可以要求该 Bot 运行 /create-verification-skill，并设置一个每日例行任务来运行 /maintain-verification-skill。

喜欢 Dr Eggbot

在它运行的同时，让我们来了解一下这个技能的作用以及它如何为你创建一个高质量的验证技能。

我将我们用于构建 Grok @Bot 和 Cursor 的所有验证技能提炼到这个技能中，作为一种元技能。它教会你的 Agent 如何为你的应用创建一个高质量的验证技能。

现在，技术栈的选择就很重要了。例如，如果你在 Electron 或 Web 上构建应用，你可以利用 JS 生态系统中丰富的调试工具。例如，Chrome DevTools 协议 (CDP) 允许你使用与浏览器开发者工具中相同的工具。或者，如果你在构建 iOS 应用，可以利用模拟器。

理想情况下，你需要能够与你的应用交互、调试它、进行性能追踪，以及任何你手动开发应用时通常会使用的其他调试和开发工具。如果你没有丰富的运行时可以利用，你可能需要让你的 Agent 为你创建工具（例如使用 lldb，或一个在开发环境中作为 sidecar 运行的自定义包），或者直接利用你现有的工具。

我个人认为，Agent 验证如此重要，以至于我会不遗余力地建议你构建自己丰富的调试工具，甚至选择不同的技术栈，以便在构建软件时获得不公平的优势和极高的生产力。正如我之前提到的，让 Agent 能够验证自己的工作，可以解锁组织中每个人的能力，使他们能够贡献并验证他们的更改是否真的有效。你的技术栈越难调试和控制，就越难高效地使用 Agent。

使其可重现

在 pstack 中，我们有一个原则叫做 "构建杠杆"。在创建技能的上下文中，这意味着我们更倾向于给 Agent 提供工具，而不仅仅是 Markdown。对于验证技能，这意味着创建一个小的 CLI，将应用的交互和调试脚本化到一个对 Agent 友好的小型实用程序中。这意味着 Agent 在执行任务时消耗更少的 Token（运行一个 CLI 命令，而不是编写一个一次性脚本来点击某个东西），并使你的验证技能更具可重现性和可测试性。

以下是一个假设的 CLI 示例，你的 Agent 可能会为 Electron 应用创建它：

1# 健康检查
2node .cursor/skills/verify-atlas/control-atlas.mjs doctor
3
4# 打开一个空白线程并发送
5node .cursor/skills/verify-atlas/control-atlas.mjs new-session
6node .cursor/skills/verify-atlas/control-atlas.mjs send "列出此项目中的开放任务"
7
8# 键盘路径
9node .cursor/skills/verify-atlas/control-atlas.mjs press "Meta+KeyN"
10
11# 实时 UI 的无障碍快照
12node .cursor/skills/verify-atlas/control-atlas.mjs snapshot
13
14# 截图作为证据
15node .cursor/skills/verify-atlas/control-atlas.mjs screenshot /tmp/atlas-proof.png
16
17# 等待流式传输 / 布局稳定
18node .cursor/skills/verify-atlas/control-atlas.mjs wait-settle
19
20# 为当前会话切换功能标志
21node .cursor/skills/verify-atlas/control-atlas.mjs feature-flag rooms_v2 on

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

• 为开发数据库填充种子数据
• 如何处理身份验证、测试用户、针对测试/预发布环境的 API 调用
• 以一致的方式安装和启动你的开发环境

所有这些都是你之前自己编写代码时可能需要考虑的事情。所以，把它看作是你的 Agent 在你的应用上进行开发工作的主要工具。保持它的良好维护和测试！

你可能还想考虑的其他一些示例命令：

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

一旦你完成了这个基本设置，你应该会开始看到你的 Agent 有了很大的改进。它们应该能够轻松地导航和调试你的应用。

我建议在尝试更高级的操作之前，花时间把这个 CLI 做好，确保它没有错误。你还需要考虑（或让你的 Agent 考虑）设计一个对 Agent 友好的 CLI。网上有很多资源可以供你的 Agent 参考，但我喜欢的关键特性是：

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

使用 Cloud Agents 实现并行化，速度更快，无需工作树

当你的验证技能成功运行并提交了几个 PR 后，你可能会开始思考是否可以进一步并行化。例如，如果一个 Agent 现在可以接受你的提示并将其驱动到可合并的状态，那不就解放了你，让你可以运行更多的 Agent 吗？

你的第一反应可能是添加工作树支持，这意味着你的 Agent 可以使用 Git 创建一个仓库的跟踪副本，在那里他们可以在与主检出隔离的情况下进行更改。理论上，这允许你同时运行多个 Agent，而不会让它们的更改相互冲突。

我建议不要这样做。首先，它会占用你机器上大量的存储空间和资源。根据你的仓库大小和机器性能，你可能最多能通过工作树并行运行 10 个 Agent。但还有更好的方法！

Cursor 的 cloud agents 是在 Cursor 基础设施上云端运行的 Agent。这些 Agent 可以访问一台真实的计算机，这意味着它们可以安装依赖项、运行你的应用、录制视频和截图，并像真实用户一样与你的应用交互。如果你在前一步中投入足够多，使你的开发体验良好，那么设置 Cloud Agents 应该不会太困难。当你首次设置云环境时，我们会派一个 Agent 来帮助你正确设置和运行。在首次构建之后，我们会拍摄一个 快照，这意味着后续的 Cloud Agent 运行总是能快速启动。

我强烈建议花时间设置 Cloud Agents，因为它能极大地提升并行化带来的生产力提升。在后续的文章中，我将向你展示如何在云端并行运行数百个子 Agent！但现在，请先设置好你的环境，使其达到一个你可以开始有信心将所有 Agent 运行在云端的程度。

使用功能地图让 Agent 保持智能

随着你的应用变得越来越复杂，Agent 需要更多的指导才能找到功能并与它们交互。为此，我提出了一个我称之为“功能地图”的概念。顾名思义，它是一个易于搜索的地图，列出了你应用中所有可用的功能、它们的作用以及从用户角度如何访问它们。

这里有一个 示例功能地图，是我为一个名为 Atlas 的虚构应用准备的。它只是几个在验证技能的 SKILL.md 中引用的 Markdown 文件。

你可以把这个文件放在任何地方，但在 /create-verification-skill 中，我们会自动创建一个 references/features 目录，里面包含一个 README.md。这个 README 就是地图本身：所有主要功能的高级概述，并包含指向具体细节的链接。一个示例功能看起来像这样：

1# 偏好设置
2
3全屏偏好设置覆盖层及其选项卡集。
4
5## 子功能
6
7- settings-overlay: 从齿轮图标或 Cmd/Ctrl+, 打开的全屏覆盖层
8- settings-nav: 左侧的选项卡导航（通用、外观、模型、计划与用量、...）
9- settings-search: 覆盖层内的搜索（在设置打开时按 Cmd/Ctrl+K）
10- theme-picker: 外观选项卡上的快速主题控制
11
12## 如何访问（用户视角）
13
14点击账户头像旁边的齿轮图标，或按 Cmd/Ctrl+,。从左侧导航中选择一个选项卡。在偏好设置搜索框中输入以跳转。按 Escape 或点击关闭控件可关闭。
15
16## 使用 control-atlas 驱动
17
18bash
19node .cursor/skills/verify-atlas/control-atlas.mjs press "Meta+Comma"
20node .cursor/skills/verify-atlas/control-atlas.mjs snapshot
21node .cursor/skills/verify-atlas/control-atlas.mjs press "Escape"
22
23- 覆盖层根节点：在无障碍树中查找名为 Preferences 的对话框/区域。
24- 选项卡：通过可见名称点击。对于某些账户状态，“计划与用量”可能不存在。
25- 当设置打开时，Cmd/Ctrl+K 是偏好设置搜索，而不是全局命令面板（参见 `multi-surface-journeys.md`）。
26
27## 注意事项
28
29- 在套件中间关闭设置可能会导致焦点无处可去。`new-session` 或 `home` 可以恢复。
30- 某些选项卡受权限控制。如果遇到，请使用明确的账户原因跳过。

不用担心自己编写这些！当你运行 /create-verification-skill 时，你的 Agent 会自动遍历你的应用，对所有内容进行编目，并为你创建这些参考文件。

功能地图与 CLI 相结合，是 pstack 的验证技能如此出色的主要原因之一。Agent 现在拥有了关于每个功能以及如何访问它的上下文，从而节省了其上下文窗口中宝贵的 Token，并精确地教会了它该功能是什么以及如何访问。

你可以将功能地图视为一种“物化记忆”。如果你已经使用 Agent 一段时间，你可能对“记忆”的概念很熟悉——通常这些记忆可能以简单的 Markdown 文件（例如 Obsidian 仓库）甚至更复杂的东西（如向量数据库）的形式存储。就我个人而言，我认为你的代码库是记忆的终极形式。代码是你和你的团队所做决策的投影，代表了已发生事情和事物实际运作方式的真相来源。功能地图只是它的一个更紧凑的形式，旨在节省 Token。而且因为它只是技能中的 Markdown，所以每个为你的代码库做贡献的人都能从这个共享记忆中受益。

这意味着维护验证技能非常重要。我建议每天至少运行一次 /maintain-verification-skill，以确保你的 Agent 始终拥有控制你的应用的最新细节。你也可能会发现，随着你更多地使用验证技能，Agent 会在处理你的应用时自动更新它们。/maintain-verification-skill 会捕获所有遗漏的更新。

如何使用你的验证技能

作为参考，这里有一个为虚构应用创建的示例验证技能：https://github.com/poteto/verification-skill-example。提醒一下，运行 /create-verification-skill 来创建一个，它会包含一个基本的 CLI 和功能地图。

以下是我通常如何将其与 pstack 一起使用。

首先，当然是用 /poteto-mode 开始你的提示。如果你通过 Cursor 使用 pstack，当自动补全 /poteto-mode 时，你也可以按 Opt + Enter 而不是仅按 Enter——这会将技能添加为 自定义模式，这会固定该技能，以便你的 Agent 在每次新的交互时都能收到使用该技能的提醒。

输入 /poteto-mode 并按 Opt + Enter 将其固定为自定义模式

在 Grok @Bot 中，安装 插件，然后输入 /poteto-mode。

你也可以在 Grok Bot 中使用 pstack！

示例：构建新功能

对于构建新功能，我通常将验证技能与 /poteto-mode 一起使用，让 Agent 验证其工作。例如，我可能会提示类似这样的内容：

/poteto-mode 构建 <功能描述，任何有用的上下文>。使用 /control-app 验证你的更改，并向我展示视频和截图作为证据

其中 /control-app 是 /create-verification-skill 的结果。在 Grok @Bot 中，我会提示类似这样的内容：

生成一个 Cloud Agent 使用 /poteto-mode 来构建 <功能描述，任何有用的上下文>。使用 /control-app 验证你的更改，并向我展示视频和截图作为证据

这里微小的区别在于，在 Grok @Bot 中，你告诉你的 Bot 生成一个 Cloud Agent 而不是自己完成工作。我更喜欢这样做的主要原因是，它可以释放你的 Bot 去做其他事情，并保持其上下文窗口的清洁。从这个意义上说，我更倾向于将我的 Bot 视为管理和监督 Cloud Agents 的协调者。Cloud Agents 还意味着你可以利用 Cursor 中可用的全套模型，这些模型拥有自己独立的机器，因此你的 Bot 的计算机可以腾出来做其他事情。

示例：性能工作

生成一个 Cloud Agent 使用 /poteto-mode 来改进我们应用的初始加载时间。首先使用 /control-app 对现状进行追踪，并识别改进机会。然后进行有针对性的修复，并使用 /control-app +

/swarm 来确认改进效果

/swarm 是与你的验证技能结合使用的最佳技能之一。它可以派出任意数量的 Cloud Agents 来运行你的验证技能，这样你就可以做诸如用足够大的样本量确认性能改进，或对你的应用进行模糊测试以确保你没有破坏或回退任何功能。

示例：自动复现用户报告

当你对你的验证技能感到满意时，你可以将它们放入 Grok @Bot 的例行任务或 Cursor 自动化 中。例行任务和自动化允许你按计划运行任务，或在事件发生时触发。

例如，如果你将用户反馈导入 Slack，和/或拥有自己的内部反馈渠道，你可以让你的 Bot 监听每份报告，并自动尝试使用 Cloud Agent 复现它们。如果你的验证技能和功能地图足够好，你甚至可能决定同时自动修复问题。

这就是为什么我之前说验证是你工具箱中最重要的技能之一。它为你构建新的技能和例行任务提供了基础。最重要的是，你团队中的每个人都能从中受益。

投资于你的验证技能

一旦你创建了验证技能，请使用 /maintain-verification-skill 保持其锐利。不断改进 CLI，并像对待关键基础设施一样投资于这个技能。你甚至可能想为其设置一个轮值待命制度——这就是它对于解锁团队 100-1000 倍生产力的重要性。

这个技能是我们在 pstack 指南中将涵盖的许多其他技能的基础，并且与所有这些技能都能完美地组合使用。

• pstack: https://x.ai/bot/plugin/9717366 (GitHub 链接
• Dr Eggbot: https://x.ai/bot/93gOz3op1UQdBdbekQFLK

我建议将 Dr Eggbot（我的一个帮助你创建高质量 Bot 的 Bot）添加到你的阵容中。Dr Eggbot 随 pstack 一起提供。它会教编码 Bot 如何使用它，并且它也可以用同样的严谨性创建非编码 Bot。

你可以让 Dr Eggbot 为你创建一个工程师 Bot，然后你可以要求该 Bot 运行 /create-verification-skill，并设置一个每日例行任务来运行 /maintain-verification-skill。

感谢阅读，敬请期待第二部分！