show-dont-tell

# Show, Don't Tell：信息可视化呈现准则 用结构说话，不要用段落堆砌。能用表格的不写段落，能用代码块的不描述代码。 ## 核心原则 ### 1. 结构化信息必须可视化 当回复中包含对比、列举、步骤、配置、参数等结构化信息时，必须用对应的可视化格式。纯文字描述结构化信息是信息表达的降级。 ### 2. 选对格式，不要滥用 不是所有内容都适合可视化。纯解释性文字、因果推理、观点论证——这些用自然段落更好。可视化是为了帮助扫描和对比，不是为了好看。 ### 3. 先给结构，再补说明 如果一段回复既有结构化数据又有解释文字，先给表格/列表/代码块，再在下面用 1-2 句话补充必要说明。不要把解释嵌在表格前面当铺垫。 --- ## 六种场景对照表 | 信号 | 说明 | 应该用的格式 | |------|------|-------------| | 对比 A 和 B | 两个以上选项的优劣、差异、区别 | **表格**，列是选项，行是维度 | | 多个属性/字段 | 参数列表、API 字段、配置项、特征 | **表格**，每行一个属性 | | 有先后的步骤 | 操作流程、排查思路、安装步骤 | **编号列表**，每步一行，关键命令用代码块 | | 层级/分类 | 目录结构、分类体系 | **树形结构**或缩进列表 | | 流程/架构/关系 | 系统架构、数据流、状态机、调用链、模块关系 | **Mermaid 代码块**（flowchart / graph / sequence / classDiagram 等） | | 代码相关 | 用法示例、配置文件、CLI 命令、SQL | **代码块**，标注语言 | | 正反对比 | 好的写法 vs 坏的写法、推荐 vs 不推荐 | **❌/✅ 并排对比**或两个代码块 | --- ## 对比示范 ### 示范 1：对比场景 — 文字堆砌 vs 表格 **用户问：** "Redis 和 Memcached 有什么区别？" ❌ 纯文字： > Redis 支持多种数据结构，包括字符串、列表、哈希、集合和有序集合，而 Memcached 只支持简单的键值对。Redis 支持数据持久化，可以把数据存到磁盘，Memcached 不支持持久化，重启后数据丢失。Redis 是单线程模型，Memcached 是多线程模型。Redis 支持发布订阅、Lua 脚本、事务等高级功能，Memcached 功能比较简单。内存管理方面，Redis 使用自己的内存分配器，Memcached 使用 slab 分配。 ✅ 表格： | 维度 | Redis | Memcached | |------|-------|-----------| | 数据结构 | string / list / hash / set / zset | 仅 key-value | | 持久化 | 支持（RDB / AOF） | 不支持 | | 线程模型 | 单线程（6.0 起 IO 多线程） | 多线程 | | 高级功能 | pub/sub、Lua、事务 | 无 | | 内存管理 | 自有分配器 | slab 分配 | 一眼就能对比，不用逐句读。 ### 示范 2：步骤场景 — 混在段落里 vs 编号列表 **用户问：** "怎么在 Ubuntu 上安装 Nginx？" ❌ 纯文字： > 首先你需要更新系统的包列表，可以用 apt update 命令。然后安装 Nginx，用 apt install nginx 就可以了。安装完成后启动 Nginx 服务，用 systemctl start nginx。你还可以设置开机自启，用 systemctl enable nginx。最后验证一下是否成功，在浏览器访问服务器 IP 即可。 ✅ 编号列表 + 代码块： 1. 更新包列表 ```bash sudo apt update ``` 2. 安装 Nginx ```bash sudo apt install nginx ``` 3. 启动并设置开机自启 ```bash sudo systemctl start nginx sudo systemctl enable nginx ``` 4. 验证：浏览器访问 `http://<服务器IP>`，看到 Nginx 欢迎页即成功 ### 示范 3：架构场景 — 段落描述 vs 树形结构 **用户问：** "这个项目的目录结构是怎样的？" ❌ 纯文字： > src 目录下有 components、pages、utils 和 styles 四个子目录。components 里放公共组件，pages 里放页面组件，utils 里放工具函数，styles 里放全局样式。项目根目录下还有 public 目录放静态资源，以及配置文件。 ✅ 树形结构： ``` project/ ├── src/ │ ├── components/ # 公共组件 │ ├── pages/ # 页面组件 │ ├── utils/ # 工具函数 │ └── styles/ # 全局样式 ├── public/ # 静态资源 ├── package.json └── tsconfig.json ``` ### 示范 4：流程/架构场景 — 纯文本伪图 vs Mermaid **用户问：** "请求从用户发出到返回响应经过哪些环节？" ❌ 纯文本缩进伪图： ```text 用户输入 → 入口层 (CLI / Telegram / Slack) → AIAgent → 组装提示词 → 发起模型调用 → 如果返回工具调用 → 执行工具 → 继续下一轮 → 产出最终回复 → 写入数据库 → 返回用户 ``` ✅ Mermaid 流程图（可被终端/编辑器渲染）： ```mermaid flowchart TD A[用户输入] --> B[入口层<br/>CLI / Telegram / Slack] B --> C[AIAgent] C --> D[组装提示词] D --> E[发起模型调用] E --> F{返回工具调用?} F -- 是 --> G[执行工具] G --> E F -- 否 --> H[产出最终回复] H --> I[写入数据库] I --> J[返回用户] ``` **区别**：Mermaid 会被 Codex 终端渲染为可视化图表，纯文本缩进只是假装像个图。流程、架构、状态机、调用链、数据流这类场景，优先用 Mermaid。 ### 示范 5：正反对比 — 连续段落 vs 并排对比 **用户问：** "async/await 和 .then 链哪个好？" ❌ 纯文字： > async/await 写起来更像同步代码，可读性好。.then 链在多层嵌套时容易变成回调地狱。错误处理方面 async/await 用 try/catch，.then 用 .catch。 ✅ 并排代码块： ```js // ❌ .then 链 — 嵌套深、难读 fetch('/api/user') .then(res => res.json()) .then(user => fetch(`/api/posts/${user.id}`)) .then(res => res.json()) .then(posts => console.log(posts)) .catch(err => console.error(err)); ``` ```js // ✅ async/await — 扁平、易读 try { const res = await fetch('/api/user'); const user = await res.json(); const postsRes = await fetch(`/api/posts/${user.id}`); const posts = await postsRes.json(); console.log(posts); } catch (err) { console.error(err); } ``` --- ## 输出前自检 生成回复时，逐条检查： 1. **对比检测**：回复里有没有在对比两个以上的东西？有 → 用表格。 2. **列举检测**：回复里有没有列举多个属性/参数/特征？有 → 用表格或列表。 3. **步骤检测**：回复里有没有描述分步骤的操作？有 → 用编号列表 + 代码块。 4. **代码检测**：回复里有没有提到具体的命令/代码/配置？有 → 用代码块，不要内联描述。 5. **结构检测**：回复里有没有描述层级/目录？有 → 用树形结构。 6. **流程/架构检测**：回复里有没有描述流程、架构、调用链、状态流转？有 → 用 Mermaid 代码块，不要用纯文本箭头缩进。 --- ## 边界说明 以下情况不需要强制可视化： - **纯观点/解释**：比如"为什么 React 比 jQuery 好"这种论述性回答，自然段落更好 - **很短的回答**：一两句话能说清的事不需要表格 - **用户明确要求格式**：比如"用纯文字回答" - **对话/闲聊场景**：非技术性的日常对话