调试Agent的时候我经常遇到一种尴尬日志太长、上下文不够、Agent抓不住重点。于是有人提出与其让Agent读完一大段文本不如让它把关键内容画出来。这个思路并不新但当我在Hacker News上看到/show-me这个 agent skill 的时候还是觉得它的命名点破了一个被严重低估的问题——Agent需要的不是更多文字而是更友好的表示。/show-me想做的并不是一个画图命令而是把Agent消化复杂信息的成本压缩到一条斜杠命令里。往深了说它背后是一种信息表示方式的设计当模型上下文越来越贵、任务链路越来越长如何把“项目结构、依赖关系、调用链、统计分布”这类信息从几千字的文本压缩成一张人机都能快速读取的紧凑视觉表示。这篇文章想聊的是为什么这类 skill 值得被单独提出来以及如果要动手实现类似能力应该从哪些环节开始。1. 为什么Agent越来越需要“给我看一眼”1.1 一个最常见的“看不懂”场景我一直觉得Agent 开发里最消耗耐心的不是模型能力不够而是它经常把时间浪费在“读一篇很长的东西”上。举个例子。你让Agent分析一次线上调用的失败原因它拿到的是几十条堆栈日志、三个服务模块的部署目录、一张配置文件里涉及的连接项。纯文本状态下Agent需要反复在上下文里翻找“哪个服务调了哪个服务”“哪条日志对应哪个模块”。模型确实能做但代价是大量token消耗而且顺序一长前面的关键信息就容易被稀释。这时候如果有一个/show-me这样的能力它可以把同样的信息转成一张调用链示意图或者一张标注了异常位置的流程图。Agent不需要在文字迷宫里来回走它可以从图里直接获得结构关系。这不是“好看”的问题而是信息密度的问题。1.2 紧凑视觉表示压缩的到底是什么很多人觉得“视觉表示”就是把文字变成图片其实压缩的不只是篇幅。它真正压缩的是这三类信息关系信息谁依赖谁、谁调用了谁、节点之间是什么连接方式。层次信息哪些内容属于同一个模块、父级和子级的关系怎么划分。状态与路径流程走到哪一步失败故障发生在哪个环节。这三类信息如果用文本表达通常需要大量描述性句子“服务A在收到请求后调用服务B服务B再查询数据库如果超时则返回错误码……”这样的表述Markdown列表可以拆但读起来依然很散。而视觉表示可以在一屏之内把这些关系稳定呈现出来。比如一个 Mermaid 时序图事件顺序、参与对象、失败节点一目了然。对于Agent来说这种表示还有一个额外好处它的注意力不会被大段文本里的无关细节带走。1.3 为什么要单独做成一个 skill既然LLM本身可以画Mermaid、可以生成图表为什么还需要show-me这样一个独立的agent skill原因在于画图不是难点画对才是。一个独立的 skill 可以把“判断要展示什么—抽取关键信息—选择表示类型—生成渲染—回填上下文”这一整条链路固定下来。不定制skill的话Agent每次都要重新思考用户说“看看这个项目结构”到底是要目录树、依赖图还是模块关系图是从当前文件位置开始扫还是要递归扫描全部子目录输出是要SVG文件还是直接在对话里返回Mermaid代码这些决策看起来小但每次都从头推理不仅慢而且不稳定。把它封装成/show-me这样的斜杠命令等于给Agent预装了一条“遇到这类需求就用这个流程”的路径。这里可以先把判断说清楚/show-me这类 skill 的价值不是画图能力而是把“信息怎么被快速理解”这件事流程化了。2./show-me到底封装了什么能力2.1 表层看输入和输出是什么先从最外面看。按照项目标题的语义/show-me是一个 agent skill核心产出是紧凑视觉表示。那它接收什么、返回什么常见输入类型是一组日志片段或筛选后的诊断信息一个目录路径或仓库地址一段调用链、依赖列表、配置文件用户直接提出的“展示一下这个模块的边界”“把这个流程可视化”常见输出类型则取决于表示方式Mermaid 代码块可以直接被Agent理解或渲染渲染后的 SVG / PNG 图片文件ASCII 风格的目录树或流程图适合放回纯文本上下文一个自包含的单文件 HTML方便在浏览器里打开需要注意这并不一定是我上面列的某种确定实现。原始标题没有描述具体支持哪些输入输出格式所以更合理的理解是它定义了一套“如何把信息变成紧凑视觉表示”的通用范式具体细节可以按环境扩展。2.2 底层看它走的是四步流程不管具体实现用什么语言、什么模型这类 skill 的内部流程基本可以拆成四步第一步信息抽取。从原始输入里去掉噪声抽取出关键实体、关系、事件顺序。这一步最关键因为后面图的质量完全取决于抽取结果。如果日志里有大量重复异常抽取时要考虑去重和聚合。第二步表示选择。根据抽取结果判断该用什么图。是流程类信息就选流程图是调用关系就选时序图是模块归属就选架构图是数据分布就选小型统计图。第三步生成与渲染。生成对应的图定义代码比如Mermaid然后调用渲染器转成图片。如果Agent不需要看图片也可以直接把代码作为输出让它自己理解结构。第四步上下文回填。把视觉表示放回对话上下文或者存储到指定路径让后续任务可以继续引用。这四步听起来不复杂但真正落地时每一步都有不少细节。2.3 为什么一定要强调“compact”标题里有一个词很容易被忽略compact。这个词意味着输出必须克制而不是把信息铺满一整张图。Agent的上下文窗口是有限的如果每次展示都生成一张几千节点的大流程图那这个能力反而成了负担。更合理的策略是只突出用户当前最需要看到的局部。比如分析线上故障时调用链可能很长但/show-me应该只展示“出错的这条路径”以及相邻节点而不是把整个服务拓扑全部画出来。信息密度的取舍是这类 skill 和“一次性可视化脚本”之间最大的区别。3. Agent Skill 和 MCP 不是一回事3.1 MCP 是连接层解决的是“怎么碰到外部资源”聊/show-me的时候一定避不开agent skill和MCP的区别。这两个概念很容易被混在一起因为它们在很多Agent框架里同时出现。MCP即 Model Context Protocol解决的是模型如何以稳定的方式连接到外部工具和数据源。它定义了一套标准化的工具发现方式、调用格式和返回结构。一个MCP Server可以暴露各种工具比如读取文件、查数据库、调用某个API。Agent通过MCP Client去发现和调用这些工具。MCP更接近“协议层”。它不关心任务怎么做得好只关心调用是否规范、连接是否可靠、返回是否符合约定。3.2 Agent Skill 是能力层解决的是“怎么把一件事做得像样”Agent Skill 则不一样。它封装的是“完成某类任务所需的完整方法论”。它可能包含提示词模板、多步骤的编排逻辑、使用的工具组合、输出规范、甚至领域经验。回到/show-me一个视觉表示能力如果只是提供一个“生成Mermaid”的工具调用那它只是有了一个工具。但show-me作为 skill意味着它需要自己决定从哪一层开始做信息抽取用什么图类型输出内容控制在多大范围以及在渲染失败时怎么降级。这就是能力层和协议层的区别。3.3 对比一下就能看清维度MCPAgent Skill定位标准化连接协议任务级能力封装关注点工具发现、调用规范、返回格式任务理解、流程编排、领域经验典型载体Server/Client、工具定义、协议消息提示词模板、执行流程、工具组合是否独立存在可以被多个Agent复用通常运行在一个Agent框架之内与工具的关系直接暴露工具自己决定调用哪些MCP工具失败的粒度一次调用失败整个任务流程可能需要降级一个直观类比MCP是传输管道和插座标准Agent Skill是电器本身。你要用电需要有插座但没有电器插座就是空壳。反过来电器再好如果插座标准不统一换一个环境就要重接。/show-me作为一个 agent skill可以依赖一个或多个MCP工具来读取文件和渲染图片但实际的判断逻辑、抽取规则、输出控制都发生在skill这一层。3.4 实际协作时怎么分工在落地时它们的关系通常是协作的Agent 接收到用户指令“展示一下这个模块的调用关系”。Skill 层开始工作解析指令确定要展示的边界。Skill 调用 MCP 工具读取文件目录、解析依赖列表。Skill 内部用LLM抽取关键节点和边。Skill 生成图表定义再调用渲染工具输出图片。返回视觉表示或者把图片路径回填给Agent继续处理。也就是说MCP让skill“够得着”外部世界skill让调用这些工具的方式“有脑子”。4. 从零实现一个紧凑视觉表示 skill4.1 先定义输入边界不要一开始就追求万能动手实现类似/show-me的能力时我的建议是先从单一场景开始不要一开始就设计成一个通用可视化引擎。比如先只处理三类输入一个文件目录输出目录树式架构图一段调用日志输出时序图一份配置文件输出依赖关系图每类输入单独定义数据格式。目录扫描用不到LLM直接遍历文件系统即可日志解析则可能先用规则提取时间、事件、服务名再把无法归类的文本交给LLM抽取。输入边界清晰后面的答案才是可调试的。4.2 信息抽取环节LLM 只做两件事很多人做这类 skill 时习惯把整份日志或整个目录树都塞给LLM让它直接生成图。这是最大的坑。正确的做法是先压缩再交给LLM。把原始数据分成两段处理规则负责看得见的压缩去掉重复行、排除干扰目录、统计日志频率把百万字的数据缩到几千字。LLM负责看得懂的抽取从压缩后的文本里提取实体、关系、事件路径输出为结构化的JSON。比如“服务A调用服务B失败”这件事LLM应该输出{ type: sequence, participants: [ServiceA, ServiceB], steps: [ { from: ServiceA, to: ServiceB, action: request, status: failed } ] }这个JSON再进入表示选择环节而不是让LLM直接写图表代码。中间加一层结构化数据能显著提升后续生成的稳定性和可调试性。4.3 表示选择靠一张判断表就可以表示选择不需要复杂模型一组规则就能解决大部分需求内容类型合适的表示说明调用顺序、事件时间线时序图适合展示谁先谁后、谁调用谁模块层级、目录结构树形图 / 架构图父子关系明确流程分支、决策路径流程图适合展示条件分支和异常路径实体间多对多关系关系图 / 依赖图适合依赖、数据流向数值分布、统计摘要小表格或条形图数据量少时表格更紧凑规则可以写成有from/to/action结构优先时序图。有路径层级优先树形结构。有大量条件判断优先流程图。其他情况默认返回一个精简表格。这样“紧凑”的含义在规则层面就保证了——它不会把一个流程图硬生生画成架构图。4.4 生成、渲染与回填上下文生成层建议直接输出Mermaid或其他文本图表语言。原因很简单方便回填。Agent可以直接“读”Mermaid代码不需要额外图片解析。如果用户需要图片再调渲染器生成SVG或PNG。输出路径要约定好建议统一放到artifacts/show-me/下并按时间戳命名避免覆盖。artifacts/show-me/20250101_103000_call_graph.mmd artifacts/show-me/20250101_103000_call_graph.svg生成完成后把Mermaid代码放回上下文把图片路径附在response里。这样Agent既能看到整个图的结构也能知道图片存在哪里便于后续引用。4.5 验证时先小样本再批量扩这个环节我想多说几句。很多人在第一次跑通之后马上就往真实环境里塞大批数据结果各种抽风。更稳妥的顺序是先拿一个最小样本跑通比如两个服务、一次调用。验证生成的JSON是否符合预期结构。再验证Mermaid能否被正确渲染。拿一个常见但稍复杂的样本比如十次调用带一次失败分支。确定稳定后再做目录级别的批量输入。不要一上来就把批量数和并发数拉满。先用一条样例确认输入、抽取、生成、渲染、回填全链路正常再逐步加数据。5. 适用边界与容易踩的坑5.1 适合谁不适合谁/show-me这类 compact visual representation skill 并不是万能的。它有清晰的使用边界。适合的场景Agent开发调试让Agent快速理解项目结构、调用链、运行状态。内部文档生成快速把模块关系变成示意图插入团队文档。故障定位把日志压缩成带失败标记的时序图辅助人机共同分析。学习理解面对一个陌生仓库时先生成一张架构图再深入代码。不适合的场景对外交付的规范图需要公司标准、统一风格、严格配色这类skill做不到。精确数据报表需要精确到小数点、严格口径的统计图不适合用LLM做抽取。超大复杂系统的完整拓扑图能做到可视化但一旦节点数量过大就偏离了“compact”的初衷。5.2 排查链路从现象倒推问题如果发现生成结果不对建议按照这个顺序排查看输入原始数据有没有被截断路径对不对编码是不是UTF-8日志是不是只取了一部分看抽取结果中间产生的JSON是否丢失了关键节点有没有把“错误日志”误当成“正常事件”看表示选择是不是把本该画成时序图的内容硬画成了流程图看渲染Mermaid代码语法有没有问题渲染器版本是否支持你用的图类型看回填图片路径是否正确Agent是不是引用了过期的上下文内容在这五层里最常出问题的是第二层的抽取规则。因为规则会不断遇到新数据形态需要持续补充过滤条件和聚合策略。5.3 长期使用还需要补齐工程化能力如果想把这个能力长期放在Agent工作流里前面说的最小实现还不够。至少还要补上三块日志与可观测性打印每次抽取的JSON、渲染耗时、输出路径出了问题才能复盘。缓存与幂等同一份目录、同一组日志如果短时间内重复请求不应该反复扫描和渲染。权限与路径安全如果skill允许访问文件系统必须限制扫描范围避免读取敏感目录或泄露路径信息。这些工作在早期很容易被忽略因为它们不会影响单次demo的效果。但一旦进入真实任务文件权限、输出目录冲突、缓存失效、上下文更新不及时都会变成日常麻烦。6. 回到最开始的问题/show-me让我重新想了一遍Agent真正缺的是什么。很多人以为Agent缺的是更长的上下文、更强的推理、更多的工具。但一条调试链路的真实瓶颈往往在信息表示一旦关键信息被淹没在无关文本里再长的上下文也只是让模型“能找到却不一定看得清”。compact visual representation的提出等于给了Agent一个“先抓重点、再看细节”的工作方式。它把复杂的目录、日志、调用链压缩成人和模型都能快速理解的结构化视觉语言。这个过程需要信息抽取的能力、表示选择的判断、渲染工具的配合——它值得被设计成一个独立的agent skill而不是每次临时拼凑。如果你也想实现类似能力我的建议只有一句不要想着一次做完整先从最小样本、单一类型、单条链路跑通再慢慢加规则。过程中会不断遇到新的数据形态每一次都是对抽取规则和表示规则的补充。这类能力真正的长期价值不是让Agent“会画图”而是让Agent在信息爆炸的时候依然知道该看什么。而这个判断力才是未来所有Agent工程都绕不开的核心问题。