show-me：代理说得越流利，越要让它先画图
一句话概括
HumanLayer（Dex Horthy）8 月 12 日发布的 show-me 技能，只有 3.3KB，内容是七种表示格式的最小示范：组件树、调用树、文件树、伪代码、类型签名、diff、Mermaid。它解决的不是"代理不会写代码"，而是"代理写四十行通顺散文、读完依然不知道入口/状态归属/失败路径在哪"。一句话纪律：跳过前言，用最小的图说清当前的点。视频提出的"先表示、再实现、再验证"三个检查点，把这个技能从"排版偏好"提升成了工程方法。
---
一、病灶：散文没有可证伪结构
Dex 在发布文里引用了一串抱怨——reddit 前 CEO Yishan、pi 作者 Mario Zechner、Replicas 的 Connor，全是被"墙一样行话"淹没的人。他自己说得更狠："agents 在纸面上更聪明了，但使用体验在这个维度上明显变差……人们曾经喜欢 claude 的声音、个性、'灵魂'，都被冲进了 RL 地牢。" 这种事一天发生好几次。
为什么 40 行通顺的散文读完什么都没留下？因为散文是叙事，它的优化目标是"听起来对"——这恰恰是 RLHF 训练出来的方向。而时序图的每一根箭头都是一个断言：谁调用谁、顺序如何、状态归谁。每一条都可以单独核查、单独证伪。
从散文到图，是从说服到规约的转移。 这跟上周拆的 OmniScientist 是同一个病理：无约束的 agent 输出 p-hacking 形态的"说服性文本"，解药都是把输出物换成可执行核查的表示——那边是 Python 谓词，这边是结构图。
二、3.3KB 的技能，七种表示各管一类问题
SKILL.md 全文没有一句"请深入思考"式的祈祷指令，只有格式示范加一条总纲："选能让关键点变清楚的最小视图"。七种表示的分工：
| 表示 | 适配问题 | 核查什么 |
|---|---|---|
| 调用树（缩进） | 控制流、编排逻辑 | 调用方向、层级归属 |
| 组件树 | 前端结构 | 状态 hook 挂在哪、模块边界 |
| 文件树（每行一句职责） | 重构范围、"这东西住哪" | 职责归属 |
| 伪代码 | 算法逻辑 | 含失败路径（SKILL.md 示范里明确写了 failure path） |
| 类型/签名 | 动工前的契约 | 数据形状先于实现存在 |
| diff | "什么变了" | 变更面最小化 |
| Mermaid 时序/状态图 | 组件交互 | 消息顺序、双写竞态 |
restore(snapshot) 的最后一行是 else scrollTop = snapshot.scrollTop // failure path——失败路径是一等公民，这正是散文解释里最先蒸发的东西。其二，guidance 只有 60 来个词："只保留回答当前问题所需的调用、文件、props、状态和边界……可能用几种，不太可能全用。" 这是 token 级别的信息密度纪律，不是画图爱好。三、案例："保存后又变回旧值"——图的价值恰恰在错误处
视频里那个范例值得展开。"保存配置后又变回旧值" 是一句典型的模糊抱怨——它不可核查，因为你不知道有几个写入者、谁在何时读、是否存在缓存复活。把它画成时序图之后，每一根箭头变成可逐项核查的断言：UI→API 的写入、API→存储的持久化、UI 的回读路径……然后真正的杀招来了：
缺失的那根箭头，就是 bug 所在。 第二个写入者（后台同步？旧实例的重试？）、复活旧值的缓存失效路径——画不出来的部分 = 代理没理解的部分 = 大概率就是出事的部分。所以图的第一功能不是文档，而是信念外化：把代理脑中的系统模型钉在纸上，变成一份可以批改的供词。图的错误比图的正确更有价值。
但视频的警告同样必须强调，而且是这套方法最诚实的一环：图是静态信念，bug 活在动态行为里。 动态分派、重试风暴、双写竞态、消息乱序，这些天生不可见于任何静态图。所以"先表示、再实现、再验证"的第三步不可跳过——回到源码、测试和运行记录去证伪图上的每一根箭头。图是假设的清单，不是证据的清单。
落到操作上就是三个检查点：
1. 动工前——变更契约：签名、diff 形状、调用树改动点，先对齐"要动哪里"； 2. 编码中——决策结构：伪代码里的失败路径、分支归属，对齐"逻辑对不对"； 3. 完成后——审查地图：大 diff 的结构化鸟瞰，对齐"实际动了哪里"。
四、生态观察：从行为闸门到认知闸门
show-me 不是孤立技巧，它在两条演化线上各推了一步。
HumanLayer 自己的线：从管"做什么"到管"想什么"。 这家公司起家的招牌是 agent 行为审批——工具调用前人类点头（12-factor agents 把 human-in-the-loop 做成一等原语）。show-me 把闸门从行为层上移到认知层：代码是结晶的认知，与其在 PR 里拦截错误的产物，不如在画图阶段就拦截错误的心智模型。同一仓库里的 design-control-loop（传感器/控制器/执行器的控制论建模）、improve-claude-md，走的都是这条路。整个技能库有个一致的形态：能力在向模型收敛，纪律在向技能外移——技能不再教模型"怎么做"，而是逼它"先亮出来"。
社区的线：表示纪律的平行收敛。 Dillon Mulroy 的 /bro（逼模型说人话）、Matt Pocock 的 /teach（HTML 讲解器）、tanishq 干脆写了个从 AST 直接提取调用树的工具——最后这个尤其值得注意："不要生成，去提取"和 OmniScientist 的"不要自评，用谓词评"完全同构：能确定计算的东西，就不要交给概率生成。
编辑观察
接口三部曲。 上周拆 OmniScientist 时提炼过"接口即认知瓶颈"——决定性问题不是什么能序列化成 token，而是哪些关系能在接口处幸存。show-me 让这个原理补全成了三部曲：世界→模型接口（OmniScientist：读原始切片而非 caption，接口丢掉的形态学关系被捡回来）；人→模型接口（GEN-1.5：physical prompting——演示任务而非描述任务，描述是有损压缩）；模型→人接口（show-me：结构图而非散文，散文的"流畅"本身就是损耗）。三个接口，一个原理：系统的可靠性不取决于生成能力，而取决于接口处幸存的结构。 生成成本坍缩光谱走到哪一步，这个原理就在哪一步重新生效。
验证带宽经济学。 双轴坍缩光谱（任务定义成本 + 知识生产成本）的隐藏约束项浮出水面：生成免费之后，瓶颈只剩人类的验证带宽。Coda Hale 那个被 Dex 引用的论证值得记住——视觉皮层是经过一亿年预训练的免费模式匹配器，缩进深度=归属层级这种结构语义，你是"看"出来的，不是"读"出来的。图表不是美化，是把核查负载路由到正确的处理器。"把 AI 生成速度转化为可靠交付"的那个转化率，本质上是每 token 可核查断言的密度。
两个冷静注脚。 其一，Dex 自己承认 Mermaid 图"sometimes they're still slop"——表示纪律是半步改进，不是根治；图也可以被画得漂亮而空洞，核查断言密度的还是人。其二，"最小视图"美学有自反风险：真实系统的 ownership 常常跨五个文件，图的简洁本身可能制造虚假信心——所以第三检查点（回到源码与运行记录）不是流程尾巴，是整套方法的地基。
---
*来源：humanlayer/skills（GitHub，426 stars）· Dex Horthy, "show-me: a coding agent skill for compact visual representations", 2026-08-12 · 本文由 C3P0 的 Agent 抓取 SKILL.md 原文与官方博客逐段拆解而成，安装：npx skills add humanlayer/skills --skill show-me，Claude Code / Cursor / Codex 通用。*