skip to content
Liu Yang's Blog
Table of Contents

pstack 是 poteto（Lauren Tan）的个人 Skill 集。她是 React Compiler 核心团队成员，之前在 Cursor、Meta、Netflix，现在在做 Grok Bot。按她的说法，pstack 让她每个月往生产环境合入 2000 多个 PR（8 月是 2462 个），同时还担任 Grok Bot 代码库的“园丁”：团队每天合入几百个 PR，她一边做功能，一边持续重构、加 lint 和检查，让代码质量跟得上贡献的速度。

PR 数量本身是虚荣指标，她自己也这么说。值得学的是：在量上去的同时，质量怎么守住。她在 X 上写了一个系列 The Complete Guide to pstack，目前出了两篇，这篇按顺序整理我的阅读笔记，并把观点对到 pstack 里的具体 Skill。

安装

Cursor 里直接 /add-plugin pstack。Claude Code：

Terminal window
/plugin marketplace add cursor/plugins
/plugin install pstack@cursor-plugins

Claude Code 下命令会带前缀，/poteto-mode 变成 /pstack:poteto-mode。第一次用先跑 /pstack:setup-pstack 选模型和推理预算。社区还有一个移植版 michael-denyer/pstack-claude，额外适配了 Codex、Copilot 等 harness。

日常入口只有一个：/poteto-mode。它内部有 23 个 playbook（bug fix、feature、prototype、perf、multi-phase plan……），这些不是 Skill，而是 poteto-mode 下的参考文件，按任务类型按需加载，省 Token。大多数时候只需要 /poteto-mode 做某件事，剩下的它会自己挑。

第一部分：Verification is all you need

原文：The Complete Guide to pstack Pt. 1

验证是基础设施，不只是一个 Skill

验证的意思是：Agent 能自己检查自己的工作，于是可以一直跑到成功为止，人不再是瓶颈。作者把验证 Skill 看作关键基础设施，甚至建议给它排 oncall。

入门方式是运行 /create-verification-skill，它是一个“元 Skill”，提炼了 Grok Bot 和 Cursor 内部的验证 Skill，教 Agent 为你的应用生成一个专属的验证 Skill（文中叫 /control-app）。

这里技术栈很重要。Web / Electron 有 Chrome DevTools Protocol，iOS 有模拟器，Agent 能像人一样操作、调试、抓性能 trace。作者的观点相当激进：为了让 Agent 能验证，值得自己造调试工具，甚至换技术栈。越难调试和控制的技术栈，越难用好 Agent。

Build the Lever：给工具，而不是给 Markdown

pstack 有一条原则叫 build-the-lever：与其写一堆 Markdown 教 Agent 怎么做，不如给它一个工具。落到验证上，就是一个小 CLI，把“打开应用、点击、截图、抓 a11y 快照、等待渲染稳定、切 feature flag”这些操作脚本化。

好处有两个：Agent 跑一条命令就行，不用每次临时写脚本去点按钮，省 Token；操作固定下来，验证就可复现、可测试。

这和我自己“把命令固化下来”的想法一致：模型需要知道的是跑哪条命令、看什么输出，而不是一堆与当前任务无关的实现细节。

我做 TAAC 2026（腾讯 × KDD 广告算法大赛）时就是这么干的。比赛用的太极平台只有网页端，没有公开的 API 文档。我先手动把平台流程走了一遍，在 Chrome DevTools 里把请求抓下来，再交给 Agent 生成一个 CLI：taac2026-cli。

Terminal window
python taiji.py task create --name my_exp --file model.py --dry-run
python taiji.py task start <id>
python taiji.py inst log <id> --tail 200 --grep 'AUC|ERROR'
python taiji.py eval create --mould-id <id> --dry-run
python taiji.py rank --size 20

提交实验、看训练日志、发起评估、查排行榜，每一步都固化成了一条命令。Agent 不用去操作网页，也不用读一堆页面内容，跑一条命令就能拿到反馈，再决定下一步改什么。手动走的那一遍也没白费：它让我先建立了对平台流程的心智模型，Agent 后面也省了不少 Token。

作者列的“对 Agent 友好的 CLI”特征，我觉得可以直接拿来当清单：

  • API 易组合（参考 John Ousterhout 的 deep modules）；
  • 有破坏性副作用的命令提供 --dry-run；
  • 用子命令逐步暴露功能，而不是一次全摊开；
  • 错误信息要具体，并告诉 Agent 应该改做什么；
  • 详细的 --help；
  • 输出机器可读（如 JSON）。

另外，种子数据、测试账号和鉴权、开发环境的一键拉起，这些开发体验问题以前人也要面对，现在同样是 Agent 的基础设施。

用云端 Agent 并行，而不是 worktree

验证跑通后，自然想并行跑更多 Agent。第一反应是 git worktree，但作者不推荐：太占磁盘和本机资源，视仓库和机器大小，大概并行到 10 个就到头了。

她的做法是用云端 Agent：每个都有一台真实的机器，能装依赖、跑应用、录视频截图，首次构建后有快照，后续启动很快。前面在开发体验上的投入，这里直接变现。

我也觉得合理。worktree 只隔离了代码，本机的 CPU、端口、数据库还是共享的；云端环境天然隔离，并行规模也不受本机限制。

这其实也是一种延迟满足：快就是慢。直接开十个 worktree 看起来最快，但很快会被资源和环境问题拖住；先把架构和开发环境理顺，种子数据、测试账号、一键拉起都准备好，当下慢一点，速度才真正提得上去。

Feature Map：从用户视角描述功能

这是我觉得最有收获的一点。应用变复杂后，Agent 需要知道有哪些功能、怎么找到它们。Feature Map 就是一份可检索的功能地图：references/features/README.md 是总览，每个功能一个文件，写清楚：

  • 子功能有哪些；
  • 用户怎么到达它（点哪里、按什么快捷键）；
  • 用验证 CLI 怎么驱动它；
  • 有哪些坑。

作者给了一个示例仓库。这些文件不用手写，/create-verification-skill 会遍历应用自动生成。

她把 Feature Map 称为一种“物化的记忆”：代码库本身就是最终极的记忆，Feature Map 只是它的一个压缩版本，专为省 Token 设计；又因为放在 Skill 里，所有贡献者共享。代价是要维护，建议每天跑一次 /maintain-verification-skill。

拿我最近写的 ProCon2DSU 举例：它把 Switch 2 Pro 手柄的按键、摇杆和体感通过 DSU 协议提供给 Cemu 模拟器。如果按这个格式给它写一条 Feature Map，大概是这样：

# 体感输入


把手柄的加速度、陀螺仪数据通过 DSU 提供给 Cemu。


## Sub-features


- gyro-calibration: 静止时自动校准陀螺仪零偏，窗口里可重新校准
- dsu-server: 只监听 127.0.0.1:26760，供 Cemu 的 DSUController 连接


## How to get to it (user POV)


USB 连接手柄，运行 ProCon2DSU.exe 并允许 UAC。手柄放稳等待校准完成。
在 Cemu「选项 → 输入设置」加载 ProCon2DSU 配置，勾选 Use motion。


## Driving it


- ./tools/test.ps1：DSU 协议、校准、摇杆的自动化测试，不需要真实手柄
- 合成数据服务器 + portable 版 Cemu：验证 Cemu 能连上并识别配置
- ProCon2DSU.log：报告格式、IMU 是否有效、DSU 客户端数


## Gotchas


- 普通权限打开 WinUSB 会返回错误码 5，必须管理员权限
- Zadig 只给 Interface 1 装 WinUSB，别选中 Interface 0
- Cemu 的摇杆 Deadzone 设为 0，避免和工具的 8% 死区重复处理

写下来就会发现，这类硬件项目的验证边界很清楚：协议、校准和 Cemu 接入，Agent 可以靠测试和合成数据自己闭环；游戏里的体感方向和手感，还是得人拿着手柄去试。Feature Map 把这条边界也一并记了下来。

怎么用

  • 做功能：/poteto-mode 描述需求，要求用 /control-app 验证，并给出视频和截图作为证据；
  • 做性能：先用 /control-app 抓现状的 trace，找优化点，修完再用 /swarm 铺开多个云端 Agent 重复测量，用足够的样本确认收益；
  • 自动复现用户反馈：把验证 Skill 接到定时任务或事件触发上，用户在 Slack 报问题，就自动派 Agent 去复现，验证足够可靠时甚至自动修。

另一个细节：在 Grok Bot 里，她让 bot 派云端 Agent 去干活，而不是 bot 自己做。bot 是协调者，保持自己的上下文干净。这正好对应 pstack 的 guard-the-context-window 原则：上下文快满时，把大块工作交给 subagent，主线程只保留精简结论。

对应的 Skill

观点 pstack 里的 Skill / 原则
生成和维护验证 Skill、Feature Map /create-verification-skill、/maintain-verification-skill
给工具而不是 Markdown build-the-lever
用证据说话 prove-it-works、/benchmark-checklist、explain-the-number
并行验证 /swarm
保护上下文 guard-the-context-window

第二部分：如何监督比自己更聪明的 Agent

原文：The Complete Guide to pstack Pt. 2

验证解决了“怎么知道做对了”，下一个问题是：到底该做什么。

以前改一个系统，得先读足够多的代码建立心智模型；现在 Agent 抹平了这个门槛，不懂代码也能改。但要守住代码质量和用户体验依然很难。作者观察到前沿模型反复出现两种失败：

  1. 需求描述不足，Agent 无法完全理解你的意图；
  2. Agent 缺少把事情做对所需的上下文。

两者其实是一回事：用好 Agent，取决于你能不能把高质量的上下文放进它的 Context Window。下面的做法可以分成三类。

对齐意图：让 Agent 用自己的话说出来

模型的编码能力已经很强，不必像以前那样事无巨细地指挥。要在“告诉它目标”和“给它自由”之间找平衡。

作者常用的是间接提问：有人在 Slack 报问题，她先让 Agent 读完讨论串，用大白话重述它认为的根本问题，再动手。这样做有三个好处：

  • 逼 Agent 把嘈杂的讨论压缩成结构化的问题描述；
  • 它要是被讨论里的干扰信息带偏，在写代码前就能纠正；
  • 自己没有先抛出假设，就不会把 Agent 带上可能错误、或者限制它发挥的路。

补充上下文：建立心智模型，回溯历史

/teach 帮你建立心智模型。 它让 Agent 用直观的方式把事情讲给你听，内部调用两个 Skill：

  • /how 追踪运行时机制，子系统跨多个目录或服务时，会并行派出探索 Agent；
  • /why 追查动机和意图。代码只告诉你发生了什么，很少告诉你为什么这样写，所以它并行查 Git 历史和 PR 评论、工单、设计文档、Slack、监控和错误记录等来源。

一个有意思的发现：这个“讲给你听”的过程对 Agent 自己也有用。模型经常不读代码、不拿数据就很自信地下结论，逼它先解释，它就得先把功课做足。

/recall 从历史对话中找回上下文。 很多工作会跨好几个会话，每开一个新对话都要从头建立上下文。作者意识到历史对话是一座金矿：之前遇到过类似的问题，就先用 /recall 把当时的上下文找回来，让新的 Agent 直接回到之前的状态。

三思而后行：用代码做计划

“我不相信计划”，其实是用代码做计划。 作者认为多数 harness 的 plan mode 过度描述实现细节，却对其他方面描述不足，所以 pstack 没有规划类 Skill。

README 驱动开发。 对共享代码和公共包，先写 README，从使用者的角度描述 API，再倒推实现和架构。她做内部桌面应用框架时，先写了一份教程。第一版很难读：教程、操作指南、架构说明、API 参考全混在一起，还是一股 AI 腔。于是她先做了 /technical-writing，用 Diátaxis 把文档分成四类：

  • 教程（Tutorial）：带新手一步步做出看得见的东西；
  • 操作指南（How-to）：给有经验的用户解决具体问题；
  • 参考（Reference）：完整、权威、干巴巴的技术描述；
  • 说明（Explanation）：背景、设计取舍与权衡。

再配合 /unslop 去掉 AI 腔。这样写出来的文档本身就是计划：Agent 有了可以对照检查的具体目标，人也更容易看懂它要做什么。

几个 Skill 在设计阶段会叠加起来用：先 /recall 最近修过的 bug，用 /how 和 /why 理解现有实现；再用 /technical-writing 从一份使用教程出发设计新方案；最后用 /teach 让 Agent 证明新方案为什么更好。

先做原型，不要接受第一个设计。 规划时两个最常见的错误是：直接接受 Agent 给的第一个设计；以及在没有实证的情况下过度打磨计划。prototype playbook 会让 Agent 做几个一次性的变体（UI 的话放在一个切换开关后面），用 /control-app 截图、测时间和布局，再供你挑选。原型就是用代码做计划，Agent 能用实证回答自己的问题，而不是等你拍板。

更大的改动用 /architect。 分五个阶段：

  1. 落地问题：用 /how 和 /why 弄清现有系统的归属和约束；
  2. 草图：并行派出多个候选（常常跨不同模型家族），各自从“调用方希望怎么用”出发，写出类型定义和函数签名；
  3. 交叉评审与综合：用另一个模型按严格标准评审，合成一版；
  4. 按草图实现：实现中发现需要额外参数或状态，就把差异暴露出来；
  5. 设计错了就推倒重来：同一个 workaround 在不相关的调用点反复出现，或者类型需要 any、强制转换这类逃生口，就是架构错了的实证。

作者也因此从不对抽象计划做对抗式评审：Agent 会开始幻想理论风险，为永远不会发生的问题设计复杂防护。计划还抽象的时候别过度打磨，让 Agent 通过原型和验证自己回答开放问题。

真要计划文档的话。 设计定下来之后，用 multi-phase plan playbook 生成执行计划。每一项都围绕证据和验证来组织：测试通过不算数，真正跑过代码、确认能用才算。计划的结构和格式由自动化脚本检查，通过后逐项执行，每个 PR 小而独立、易于 review。特别大的项目（比如要做一周的），计划会临时提交进代码库让其他 Agent 知道进展，做完就删，不长期保留。

她的结论是：plan mode 常被用来说服自己 Agent 会做对，但抽象的计划只是进度的幻觉。把调查、实证和验证结合起来，用 Agent 做工程就不再像赌博。

对应的 Skill

观点 pstack 里的 Skill / 原则
让 Agent 重述意图 /in-your-own-words、/bro
建立心智模型 /teach（内部调用 /how、/why）
从历史中找回上下文 /recall
README 驱动 /technical-writing、/unslop
原型 prototype playbook、/arena
架构 /architect
执行计划 multi-phase plan playbook、sequence-verifiable-units

我的收获

1. 先做好基建。 一是验证基建：验证 CLI 和 Feature Map，让 Agent 能自己判断做没做对；二是 Agent 运行的基建：开发环境一键拉起、测试数据和账号、云端运行环境，让 Agent 能放心地并行跑。两者都是“快就是慢”，前期投入看起来慢，后面的并行和自动化都建立在它们之上。

2. 提供高质量、干净的上下文。 不是给得越多越好，而是给对的、给得刚好。CLI 用子命令渐进式披露，需要时才展开；Feature Map 把代码库压缩成一份按用户路径组织的地图；大块工作交给 subagent，主线程只留结论。上下文干净了，模型才不会被无关信息带偏。

3. 让模型说出自己的意图。 不要随便许愿，丢一句需求就让它开工。先让它用自己的话重述问题和目标，意图对齐了再动手；理解偏了，在写代码之前就能纠正，成本最低。

链接