pstack 架构拆解
H03 / 十层

50 份文件不会同时
进入上下文

这一层回答一个很实际的问题:装了这么多说明书,agent 什么时候真的去读它? 答案是分两段——启动时只读索引(name + description),命中后才读正文。 上游还有一个反直觉的选择:50 个技能里 49 个禁止模型自己触发,只能你亲手喊。

图 3-1两段式装载

磁盘 50 目录 SKILL.md × 50 合计 2,247 行 + references/ × 9 + scripts/ × 2 + playbooks/ × 23 静止,不占任何资源 阶段一 · 启动 只读索引键 name description 50 条一行摘要 进系统提示 ≈ 2–3k token,不是 2,247 行 阶段二 · 命中 读整份正文 用户敲 /why 或 poteto-mode 的 某一步点名调用它 此时才付 158 行 (why 的实际长度) 阶段三 顺链接取附件 epistemics.md investigator-prompt.md sources/datadog.md 正文里的相对路径 就是这一层的指针 这套"渐进披露"是 Agent Skills 格式的核心机制:体积不累加,只有命中的那份累加。没有它,50 个技能根本装不下。
图 3-1 · 从磁盘到上下文的三段。每往右一步,进入上下文的文字才变多。

图 3-2三道闸门,和上游把它们各自开到多大

闸门 A · 主路 人敲斜杠命令 /poteto-mode · /why · /arena /unslop · /interrogate … 开放给 50 / 50 最可靠,意图明确。 整套设计就假设你走这条。 闸门 B · 几乎全关 模型自己匹配摘要 49 份写着 disable-model- invocation: true,不让它自动触发 开放给 1 / 50 唯一开着的是 setup-pstack。 它需要被"我不知道该配什么"接住。 闸门 C · 常驻提示 reminder 字段 poteto-mode 带一句原文: New task? Playbook match or rigor needed -> apply /poteto-mode. 只此一份 它不注入正文,只提醒 "该不该去敲那条命令"。 读法:上游把自动触发几乎关死了。它宁可你显式喊,也不让模型凭摘要自作主张。代价是记不住命令的人用不起来——所以官方补了 docs/guide/ 十章教程。
图 3-2 · 实测依据:50 份 SKILL.md 的 frontmatter 键计数(disable-model-invocation 命中 49 份,缺的那份是 setup-pstack)。这两个键是 Cursor 的技能元数据约定,同仓库其他官方插件也在用;pstack 自己没有解释它们的语义。

3-3这一层最值得学的东西

不是机制,是写法。pstack 把"什么时候该用我"写进 description,而且写得很具体:

摘要写法
列触发词,不列功能
interrogate 的摘要里直接写了 "challenge this"、"find blind spots"、"tear this apart"——把用户可能说的话抄进索引。
摘要写法
声明和宿主的冲突
Cursor 自带一个 babysit 技能,触发词撞车。根文件里专门写"任何 PR 状态请求走剧本,不走宿主那个"。冲突是提前设计掉的。
代价
显式即门槛
闸门 B 关掉以后,"agent 主动想到用某个技能"这件事不会发生。全部靠人记得住命令,或靠 poteto-mode 替你去点。
代价
摘要也要花钱
50 条摘要常驻上下文。技能装到几百个时,这一层自己会变成瓶颈。
本层的检验问题:既然 49 个技能都不许模型自己触发,description 为什么还要写得那么讲究? 答:它服务两批读者——人(在命令列表里挑)和 poteto-mode(读摘要决定这一步派谁)。 下一层 H04 进入 pstack 的根文件,看它怎么做这个决定。
上一站← H02 载体格式