pstack 架构拆解
Lauren Tan(poteto)的 agent 工作流套件 · 逐层拆解 · 事实取自上游仓库

把「agent 该怎么干活」
写成可以读的文件

pstack 不是一个可执行程序,也搜不到 pstack 这个命令。它是 50 个纯文本技能目录, 住在 cursor/plugins 仓库的 pstack/ 下,用 /add-plugin pstack 装进 Cursor。 它做的事只有一件:把一位工程师对"什么叫干得干净"的判断, 拆成 agent 每次都能重新加载的说明书。本页是整张剖面图,往下共十层,一层一页。

上游实测
50
技能目录总数,共 2,247 行 SKILL.md
第 06 层
24 条
principle-* 原则,官方指南称它们为"24 个名字"
第 05 层
23 个
poteto-mode/playbooks/ 里的剧本数
第 08 层
17 行
模型覆盖表的角色行数,一台机器一张表

图 0-1十层剖面:一个请求怎么穿过 pstack

读法从上往下。最上面是它为什么要存在,最下面是它留在磁盘上的东西。中间四层是它的身体:总调度、剧本、原则、扇出。

REQUEST IN STATE OUT H01 问题与定位 agent 的输出有固定的毛病:啰嗦、爱加抽象、自称完成、什么都问人 H02 载体格式 Agent Skills 规范:一个目录 + 一份带 frontmatter 的 SKILL.md,零依赖 H03 装载与入口 启动时只把 name/description 放进上下文,正文按名字或斜杠命令现取 H04 总编排 · poteto-mode 一份 147 行的说明书:不可协商触发器 + 原则索引 + 自主权边界 + 写法纪律 H05 Playbook 路由 23 个剧本把"这类活分几步"写死,每步都点名调用下层技能 H06 原则层 24 条判断标准,不给流程只给判据;agent 必须说出哪条改了什么决定 H07 扇出层 swarm 铺开覆盖 · arena 赛马选优 · interrogate 多模型对抗审 H08 模型配置 把"每个角色该用哪个模型"外置成一张表,防止扇出规模失控 H09 宿主绑定 正文只写 Cursor 方言:Task 工具、.mdc 规则、/add-plugin 安装 H10 磁盘状态 决策链 TSV、pause-safely 停机备忘、orchestrate 状态仓 —— 文本层留不下的东西 WHY + FORMAT 为什么存在 BODY 编排身体 JUDGMENT + MUSCLES 判断与执行 CONFIG 配置 HOST 宿主 DISK 落盘
图 0-1 · pstack 十层剖面。橙色 = 编排身体,青色 = 判断与执行,黄色 = 配置,玫红 = 落盘。

图 0-2一句话先认识每一层

H01 · l01
问题与定位 →
它反对的是"agent 看起来很努力"。四个毛病,四组对策。
H02 · l02
载体格式 →
Agent Skills 规范:目录、frontmatter、渐进加载。
H03 · l03
装载与入口 →
50 份文件不会同时进上下文;49 份只能你亲手喊。
H04 · l04
总编排 poteto-mode →
整个套件唯一的"根"。七节结构解剖。
H05 · l05
Playbook 路由 →
23 个剧本,用 feature.md 的八步做解剖样本。
H06 · l06
原则层 24 条 →
分五组:Core 10 / Architecture 6 / Verification 5 / Delegation 2 / Meta 1。
H07 · l07
扇出层 →
subagent 并行的四种形态与各自的取舍。
H08 · l08
模型配置 →
17 行角色表怎么生成、四档预算怎么改写它。
H09 · l09
宿主绑定 →
它绑死 Cursor 的哪些接口,端口版又换成了什么。
H10 · l10
磁盘状态 →
决策链、停机备忘、编排状态仓:让长任务可被接手。

读之前一个必须记住的区分

pstack 里绝大多数的"功能"其实是文字。它没有编译产物、没有守护进程、没有数据库。 真正的代码只在最底下两层:poteto-mode/scripts/ 与 show-me-your-work/scripts/ 里那 17 个脚本与测试文件(orch/、watch-pr/、check-plan.mjs、worktree-audit.sh、log.sh), 和插件根目录 agents/ 里两份 subagent 定义。 所以下面每一层,你看到的框图都不是模块调用图,而是「agent 读文件的顺序」。 这一点想通了,整套东西就不神秘了。
事实来源:上游仓库 github.com/cursor/plugins 的 pstack/ 目录(作者 Lauren Tan / poteto,MIT,版本 0.15.9)。 本页所有数字取自该仓库提交 e43c7ee(2026-10-03),核对日期 2026-10-05。 安装入口是 /add-plugin pstack,宿主是 Cursor。
和你机器的差异:你本地 ~/.qoder/skills/ 装的不是这份原版,而是社区移植版 michael-denyer/pstack-claude(同一作者作品,改成 Claude Code / Codex / Pi / OpenCode / Gemini 可用)。 移植版有 73 个技能目录、23 条原则、163 行根文件。原版是 50 / 24 / 147。 本站按原版讲,凡两处不同步的地方,都在对应页面标了"端口版"。