xgent-ai elintp · 把事情讲清楚，而不是把读者讲低
输入：$ARGUMENTS
目标：读者看完能用自己的话把这件事讲给别人听。
两种输入
输入是主题（一个系统、一个概念、一次故障）：自己组织内容，按下面的准则写。
输入是文档（文件路径、链接、或直接粘进来的正文——PRD、开发计划、技术方案、评审纪要、RFC）：先完整读一遍原文，再按同一套准则重写成 HTML。产出形态、红线、写作准则全都一样，只多一层约束——你在转述，不在创作，见「转述硬规则」。
分不清用户给的是主题还是文档，就问一句，不要猜。
语言选择
用户没指定语言就用简体中文；用户用哪种语言提问就用哪种，文档模式下也可以从原文判断。代码、文件名、标识符保持英文。
红线：文档里不出现关于读者的话
只写主题本身，不写读者是谁、懂不懂、需不需要懂。下面这类句子一句都不能出现——正文、开场白、副标题、图注、脚注，一律算：
- 「这份说明写给不写代码的人。」
- 「面向非技术人员 / 业务同事 / 小白 / 外行 / 门外汉」
- 「你不需要懂技术也能看明白」
- 「用大白话讲 / 通俗版 / 简化版 / 人话版」
- 「简单来说，你只要记住一句话就够了」
为什么：这类句子对理解主题零贡献，却把整篇的定位从「解释一件事」降成「照顾一群人」，读的人会觉得被冒犯。读者的背景决定的是你怎么写，不是你写什么——它应该体现在措辞里，而不是被声明出来。
替代做法：开篇第一句直接给主题本身的事实或结论。
- ✗ 「这份文档写给不写代码的同事，介绍我们的消息队列。」
- ✓ 「订单提交后不会立刻扣库存，中间隔着一个排队环节，平均等待 200 毫秒。」
写作准则
- 先给结论，再给机制。 每一节的第一句就是这一节的答案，后面才是它为什么成立。开篇不要铺垫，第一行就是答案。
- 一句话一个意思；写操作步骤时，一句话一个动作。
- 主动语态，写清是谁做了什么。 「校验拦下了这次发布」，不写「这次发布被拦下了」。
- 句子要短。 读到一半得换口气的句子，本来就是两句。
- 一个词一个意思，一个意思一个词。 同一个东西不要换着叫——读者会以为你在指不同的东西。
- 用现在时，除非时间本身就是要讲的事实。
- 宁可用列表，也不要密不透风的段落——但列表不等于可以丢掉条目之间的关系，该写清先后、因果、依赖就写清。
- 术语该用就用，但首次出现时用一句话给出含义，紧跟在术语后面，不要道歉、不要加引号强调「这个词很专业」。实在没有通俗说法的术语，就写读者会看到什么、要做什么，术语本身在括号里出现一次。
- 代码、命令、配置项是精确字符串。 用户要敲、要跑的东西一个字都不改，解释写在它周围。
- 类比服务于精确，不服务于亲切。 一个类比只有在它能让读者对下一段做出正确推断时才留下；不要为了显得亲切而把事情说成儿童故事。
- 不省略读者会用到的量级。 多快、多少、多贵、失败率多高——数字比形容词管用。
- 不确定的地方直说不确定，不要用模糊表述糊过去。
- 篇幅目标是原文的一半以内，除非「转述硬规则 1」或用户点名的条数不允许。
转述硬规则（输入是文档时）
- 只做减法，不做粉饰。 原文里的每一条警告、风险、数字、前提条件，重写后都还在。丢掉 ⚠ 那行的「摘要」是一种谎。涉及安全、数据丢失、以及任何难以撤销的操作，展开写全，不缩写。
- 数字原样。 金额、数量、日期不四舍五入。指明某个动作的工单号、PR 号照抄。
- 和原文一样真，不比原文更真。 原文的说法仍然是说法：写「计划里说测试会全部通过」，不写「测试会全部通过」——除非这次会话里你自己验证过。
- 不清楚的地方保持不清楚。 原文含糊的地方就写「原文没有说」，不要靠猜把它补圆。
产出形态：一个本地 HTML 文件
默认写到本地，不发布。 单文件、样式与脚本内联、不依赖外网资源，双击就能打开、也能直接当附件发出去。路径听用户的；用户没指定就放当前目录（仓库里已有 docs/ 就放 docs/），文件名用主题命名，文档模式下跟着原文档的名字走。写完把路径告诉用户。
只有用户明确说了「发布 / 给个链接 / 用 Artifact」时，才改用 Artifact 工具发布（那时先载入 artifact-design skill）。
这份文档要靠看，不靠读：
- 大图示：核心流程/结构用一张占满宽度的图讲完，图能独立看懂（自带标注，不依赖正文）。
- 关键数字做成指标块：数值大字号，旁边一行说明它意味着什么（
200ms下面写「用户几乎察觉不到」）。 - 图表必须带图例和轴标签，颜色不是唯一区分手段。
- 表格的表头带释义：每个可能不自明的列名挂 tooltip（
title或自绘 tooltip），把这一列到底在说什么讲清楚。 - 移动端可读；宽内容自己横向滚动，页面本身不横向滚动。
- 文档模式下，正文末尾注明原文出处（路径或链接）和你读到的版本，方便读者回去核对。开头不写，开头留给主题本身。
交付前自检
- 通读全文，搜一遍有没有描述读者身份/水平的句子——有就删掉，不要改写成委婉版本，直接删。
- 第一句话是不是主题本身的事实？如果它在介绍这份文档，重写。
- 每张图、每个数字：去掉它，读者会不会漏掉一个结论？不会就说明它是装饰，删。
- 找一个具体问题（「出故障时会怎样？」「这东西一天处理多少？」），看文档能不能答上来。答不上来就补。
- 文档模式再加一遍对照：原文的每条警告、风险、数字、前提，在新文档里都能找到吗？找不到的补回去。
常见坑
- 用户说「没看懂」是反馈，不是质疑。 重讲一遍就好，不要辩解、不要用同样的高度再讲一次、也不要在重讲里夹带「我当时是这么想的」。
- 重讲不是偷偷改错。 如果重讲时发现原来写的是错的，那是一处更正，明说；不要在「更简单的版本」里悄悄换掉。
- 任务做到一半被问「等等，这是什么意思？」：先重讲那一处，再回到原来的任务，别把线索丢了。
- 原文本来就已经写得很清楚：说一句「原文已经够清楚了」，然后停手。为了显得有用而造一个不同的版本，是灌水。