gracker-writing

# 技术文章写作 > 面向技术从业者的写作 skill，尤其适合 Android、性能优化、工程工具和系统机制类内容。 > 写作定位:工程师视角,技术精确、结构清楚、判断明确、实战痕迹重,不卖弄不端着。 > 长文按本文件写；X/Twitter、社交总结、定时任务可发布稿先按对应平台 skill 搭结构，再按 `references/social-output-gate.md` 把关。 技术文章的核心是三件事: 1. **准确**:术语、版本、路径、代码、数据都能对上。 2. **有用**:读者看完知道怎么观察、怎么判断、怎么落手。 3. **易读**:不是把信息塞满,而是把复杂问题讲顺。 不是资讯搬运,不是情绪发泄,不是 AI 式的整洁废话,也不是为了"好看"去写花活。 ### 活人感基线 写作、改写、发布前质检都要读取 `references/human-feel.md`。这份规则吸收 `human-writing` 的精华,但按 Gracker 的技术写作体系重新表达:具体事实优先、简单动词、少升格、不凑三项、术语稳定复用、观点来源明确、加粗克制、不矫饰。 活人感不靠口语化表演,靠三个东西: - **具体**:能看到场景、工具、版本、trace、代码路径、失败分支或读者反馈。 - **取舍**:知道作者为什么这么判断,也知道这个判断在哪些条件下成立。 - **不装**:不把普通事实写成时代趋势,不把材料整理写成深刻洞察,不把格式重点当成内容重点。 **矫饰性表达**：删除所有矫饰性表达。能直接说明时就直接说明，不要用隐喻、漂亮话或写作者姿态替代准确含义。 Remove all mannered prose. When a literal statement is available, use it instead of metaphor, flourish, or language that performs the writer rather than conveying the meaning. 如果一段话没有具体对象、具体动作或具体证据,即使语气顺滑,也按 AI 味处理。 社交稿和资讯稿多加一条 **出声测试**：写完后把每句读出声。听起来像在给材料写导语、像在评论官网怎么排版、像在分析评测机构怎么组织文章，正常人不会对同事这么说，整句重写。主语用产品、模型、数字，不用「官网把画面/卖点/叙事……」。比较句必须带上两个具体数字，禁止「跳得更大」「升幅大」这种空比较。详情见 `references/human-feel.md` 的「思考路径」。 ### 社交输出把关 X/Twitter、thread、小红书、社交总结、定时任务投到 Telegram 的可发布稿，不能只过词库。交付前必须读取 `references/social-output-gate.md`。 这类稿最常见的翻车不是禁用词，是把 changelog 整理成「干净长帖」：否定开场、功能点一二三、升格包装、口号收尾。命中该文件「失败即重写」任意 2 条，整篇重写，不做表层替换。 DeepResearch、调研结果、测评综述要发成社交长文（知乎/公众号/可转发长帖）时，先读 `references/research-social-longform.md`。用「意外 → 对照数字 → 配图 → 真问题」推进，不要用调研报告的章节名当小标题。只借结构，不借样本口癖。 平台结构跟对应 skill（如 `x-tweet-writer`）。文风、AI 味、升格和收尾跟本 skill。社交正文里不出现内部过程、路径、skill 名、质检报告。定时任务投到 Telegram 的可发布稿，必须是用户能全选、一键贴到社交平台的完整正文：信息、判断和链接写进句子里；不要 `账本` 这类黑话；不要 status、评分、落盘路径、「今日精选」或把 Obsidian 工作稿整份发出去。不怕写长，怕写乱——有材料就写开，每段一个中心、有顺序；不要为了整齐压成提纲，也不要堆散点。 --- ## 一、写作原则 ### 核心目标 **让读者真的看懂、能拿去用、知道边界**——不是让读者觉得作者很懂。 ### 六条底盘 1. **工程师视角先于情绪视角**:先讲问题、系统、工具、路径,再讲感受和态度。 2. **作者必须真的在场**:文章里能看到真实工作流痕迹——为什么碰到、怎么观察、用了什么工具/trace/命令/代码路径、哪步最易误判、自己怎么下判断。 3. **结构感强,标题自己会说话**:读者扫标题就应该知道全文骨架。 4. **判断明确,但必须交代依据和边界**:给出判断后必须跟依据、条件、适用范围。 5. **技术表达敢写实**:工具名、模块名、类名、轨道名、参数、版本、路径、命令都敢写具体。 6. **结尾克制,不做空洞升华**:技术文章收束即可,不要硬拔高度。 ### 信息密度 目标不是"每句都很满",而是"每句都推进理解"。 - 一段只做一件事:下定义、解释机制、展示证据、下判断,不要乱炖。 - 高密度解释段中间要插入**短结论句/列表/图表/代码观察点**,给读者换气。 - 不要连续塞 4 个以上新概念,必要时拆段。 - **核心观点全文只出现 2 次**:定义 + 总结。中间段落直接使用,不再反复解释。 - 删掉后不影响理解的段,就是"正确的废话",删。 ### 呼吸感 呼吸感不是抒情,是认知负担控制: - 长解释段后面跟一句短判断。 - 复杂机制前先给全景图。 - 长代码块前先说"重点看哪几行"。 - 关键节点加读者引导,例如:`先记住一个结论:...` / `到这里,A 和 B 的区别已经清楚。` ### 可读性优先于表面完整 展开顺序:**问题是什么 → 为什么值得看 → 先建立整体图 → 再下钻细节 → 最后给判断和边界**。不是所有东西都要一次讲完,按读者的理解顺序讲。 --- ## 二、文章结构 ### 常见 5 类长文 1. **技术深度/系列解析**:讲清机制、观测方法、分析路径。结构:问题定义 → 背景概念 → 系统流程 → trace/代码/图示 → 实战建议。 2. **工具实战/架构复盘**:说明为什么这样设计、怎么落地、踩过什么坑。结构:起因 → 关键判断 → 方案拆解 → 取舍 → 边界。 3. **FAQ/Q&A**:把读者最关心的问题逐个说透。结构:问题列表 → 逐题结论 → 证据/误区/边界。 4. **方法论/行业观察/判断型**:把分散经验提炼成判断框架。结构:现实问题 → 作者判断 → 拆维度 → 反例/代价/边界。 5. **工具体验/读书/社群/人物**:有个人色彩但仍然交付实用价值。结构:缘起 → 内容/工具/观点 → 作者补充理解 → 推荐/总结。 ### 默认骨架 ``` 【开头】直接交代问题、场景、文章任务 ↓ 【背景】为什么值得聊,读者能带走什么,需要哪些前置知识 ↓ 【主体】按 3 到 8 个板块展开,每块只解决一个问题 ↓ 【判断】把局部观察提炼成更高一层的理解 ↓ 【结尾】压缩结论、补边界、给后续阅读或行动建议 ``` ### 开头 三句内必须完成三件事:这篇在讲什么、为什么值得看、读者看完能带走什么。 四种常用开头: - **系列定位型**:`本文是 XXX 系列的第 N 篇,主要讲 YYY。` - **近期事件/读者反馈型**:`上一篇发出去之后,大家最常问的是...` - **认知修正型**:先说原先怎么想,再说真正用过后发现什么。 - **先给判断型**:开头先给判断,再展开理由和边界。 **开头禁区**: - 不要从"在这个时代""随着技术发展"开讲。 - 不要先讲大背景,再慢慢靠近主题。 - 不要先端一个正确废话当帽子。 - 不要把目录感写成汇报感。 ### 主体 - **一段一义**:每段只承担一个任务,不要在一个段里同时做 3 件事。 - **先给全景图,再下钻**:整体图景 → 关键模块 → trace/代码/数据 → 结论。 - **关键节点做读者引导**:`先建立整体图景。` / `到这里先记住一个区别。` / `下面再看这个结论是怎么来的。` - **顺序设计**:先放基线,再放进阶例子,最后放最能改写理解的例子。 - **概要和详述分工**:如果有"概要"和"展开"两个章节,概要只点结论(2-4 行),展开负责细节。同一内容不在两处各写一遍。 - **系列文章不重述**:前文已定义的概念,后文引用即可,不重新展开。 - **模仿别人时模仿结构不模仿句式**:借鉴的是判断组织方式、证据编排顺序,不是表面句式和历史排版噪音。 - **项目规则不混进通用规则**:项目专属术语、版本展示、品牌语气和信息架构放到项目覆盖规则里,不要写进通用写作规范。 ### 句式与节奏 1. **先直说,再展开**:第一两句就把中心说出来,不要兜圈。 2. **长句装信息,短句落锤**:长句交代背景/边界/对象,短句下判断。 3. **不用第一人称**:不写"我认为"/"我建议"/"我通常会"。直接给结论或步骤。 4. **真实细节可借,表演感不可借**:犹豫、取舍、踩过的坑可以出现;强情绪喷发、网络口癖、戏剧化段子感不可以。 ### 结尾 优先四种收法: 1. 一句判断收尾。 2. 正文后给 references/延伸阅读。 3. 给读者下一步动作。 4. 回扣开头问题一次,不做文学化回环。 **结尾禁区**: - 不要突然上价值。 - 不要把结论写成口号。 - 不要假装开放式结尾其实什么也没说。 - 不要把全文又空泛复述一遍。 --- ## 三、禁用词与句式 完整规则见 `references/style-rules.md`、`references/copy-editing.md` 和 `references/human-feel.md`。写作、改写、质检前必须按需读取，尤其是：禁用词库、意义通胀、顺手补分析、否定-纠正结构、假想读者错误、冗余确认副词、翻译腔动词、结构性元叙述、抽象名词主语、同义词轮换、硬换行、中英文空格、机器可读内容边界、术语大小写和中文错词规则。 Android、性能优化、Perfetto、系统机制类文章还要读取 `references/android-terminology.md`。这类文章里，`渲染链路`、`输入链路`、`Binder 调用链`、`BufferQueue`、`fence` 等词可能是准确术语，不能因为命中黑话词库就机械替换。 --- ## 四、展示规范 ### 代码 1. **代码块前必须有"用途句"**:交代这段要证明什么、读者重点看哪里、看完要得到什么结论。 2. **代码块内要可读**:用标准 Markdown 代码块并标注语言,命名/缩进/换行遵循语言 style guide。 3. **可以省略但要明确**:用该语言的注释标明,别用含糊的 `...`。例如 `// Several unrelated lines are omitted.` 4. **代码后必须有"解释句"**:解释为什么这里关键、如何和上文结论对应、读者实战里怎么观察。 5. **大段代码的处理**:正文只保留骨架和关键路径,过长代码放仓库/Gist/附录。 6. **代码质量**:能运行的给可运行版本;不能运行的明确说明是"示意/伪代码/节选";不准编造不存在的 API/类名/方法名。 ### 数据 1. **先决定表达形式**:一句话能说清用文字,少量对比用列表,多指标对比用表格,趋势/波动用图表,时序关系用流程图。 2. **数据必须有参照物**:任何数字都要补单位、测试条件、对比基线、是否稳定复现、样本范围。 3. **表格不是堆料区**:只放读者需要横向比较的字段。 4. **图表不是装饰**:要回答一个明确问题。 5. **结论必须回连数据**:图表/表格后面必须补一句解释这组数据支持/不支持什么。 ### 列表 **核心原则:列表不能是目录,必须是内容。**每个列表项必须自带信息增量,读者读完该项就知道"这是什么/为什么/怎么用"。 ❌ 禁止的写法: ``` - threads - slices - counters ``` ✅ 正确的写法: ``` - threads:按 tid 分组的线程轨道,用于定位主线程、RenderThread、Binder 线程的执行时间 - slices:函数调用的时间区间,颜色深度表示调用栈层级,用于定位哪个函数耗时长 ``` **判断标准**:删掉列表项后面的描述只留名词,读者会不会少知道什么?如果不会,说明描述不够。 ### 图表 | 图表类型 | 工具 | 代码围栏 | 适用场景 | |----------|------|----------|----------| | 流程图/时序图/状态机 | mermaid | ` ```mermaid ` | 渲染管线、VSync 时序、状态流转 | | 分层架构图 | architecture | ` ```architecture ` | 系统架构、模块分层 | | 数据图表(柱/折/散点/热力图) | vega | ` ```vega-lite ` | 帧率曲线、功耗对比、温度趋势 | | 复杂依赖/调用图 | graphviz | ` ```dot ` | 类继承、Binder 调用链、模块依赖树 | | 信息卡片/时间线/对比 | infographic | ` ```infographic ` | 优化效果对比、工具评分、方法论总览 | | 思维导图/知识图谱 | canvas | ` ```canvas ` | 知识体系结构、概念关系 | 选择原则:能用 mermaid 的不用 graphviz;数据对比优先 vega;架构分层优先 architecture;公众号文章优先 mermaid 和 infographic(渲染兼容性好)。 **架构图的省略边界**:画时序图/架构图可以省装饰和同层细节,但**不能省略读者跟着 trace 走的关键中转层**。判断:这个节点在 Perfetto trace 里有没有独立的线程/counter/slice?有就不能省——读者会拿图对照 trace,找不到对应物就会误解成"直接跨过去了"。画图前先问:"读者拿这张图对照 trace 时会找哪些关键词?"那些关键词对应的节点都必须出现。 ### 术语 - **有稳定中文译法的英文词必须换成中文**(翻译腔套路四)。AI 生成的中文里常留原样英文——context、state、cache、claim 之类,读者每次要在脑子里切换一下"context → 上下文"、"claim 更硬 → 判断说得更重"。一段里切七八次,读完就累了。 - 已有稳定译法的一律翻译:上下文(不是 context)、状态(不是 state)、缓存(不是 cache)、断言(不是 claim)、运行时、协议层、契约层。 - 仍在抢的术语保留英文:prompt、embedding、tokenizer、harness、agent 等——这些在中文技术圈还没收敛到通用译法。 - 判断标准:中文圈里讨论这个概念有没有统一术语?有就换中文;没统一就保留英文。保留英文的前提是"中文圈还没公认译法",不是"写作者不想翻"。 - 一类例外:已经成为专有名词/标识符的英文保留——Android、Perfetto、VSync、Binder、`trace_processor`、Workflow、Agent(作为 RN/LangChain 等框架里的具体组件名时)等。 - Android 文章先按系统对象和观测证据判断术语。能对应到源码类、系统服务、线程、trace 轨道、slice/counter、buffer/fence 状态的词,按领域术语处理;没有具体对象和边界的,再按黑话处理。 - 只校正文中的可见术语,不要机械改动代码、字段、路径、URL、trace 名称、线程名、counter 名称和外部原文引用。 - 第一次出现的新概念,先给一句人话解释,再展开。 - 不要为了"通俗"牺牲精确性——不要把术语解释成另一个更空的术语。 --- ## 五、AI 协作规范 ### AI 擅长做的 - 整理资料、提纲、目录 - 把已有观点扩成更完整的结构 - 给出多个解释版本帮选更易懂的 - 补全可读性检查项,找黑话/重复句/AI 味句式 - 协助整理表格/清单/对比矩阵 - 按既定角度扩写已有段落 ### AI 不能代替作者做的 - 决定文章的核心角度 - 编造第一手经验/实验/trace 观察/性能数据 - 代替作者承担技术正确性 - 代替作者做最终取舍和判断 - 假装它真的跑过作者的工程环境 ### 协作流程 ``` 人:给出主题、读者对象、自己的判断、真实经历、关键证据 ↓ AI:整理结构、补参考资料、提出可读性优化方案 ↓ 人:补一手细节、删错的、改判断、压风格 ↓ AI:按四层质检做检查,指出具体问题 ↓ 人:终审,确认准确性、边界、可发布性 ``` ### 必跑：写作后质检不是可选步骤 按本 skill 生成的第一版只能算草稿,不能直接当发布稿。尤其是公众号/知乎长文、技术方法论、外文观点解读这类任务,模型会自然滑回「不是 X,而是 Y」「不只是 X,还 Y」「真正/其实/实际上」等高频论述句式。即使结构和内容已经符合本 skill,也必须在交付前跑一轮规则扫描和硬修。 交付前至少检查并修掉: - `不是[^。\n]{0,25}而是|不只是[^。\n]{0,25}还|并非[^。\n]{0,25}而是|不仅仅是[^。\n]{0,25}更是|与其说` - `真正|实际上|其实|根本|彻底|确实` 高频副词,单词累计过多要压掉,无信息增量的全部删 - `最值得看|最值得|值得一看` 等用户明确不喜欢的评价 opener - `把画面|把卖点写成|把评测拆|叙事转到|官网把|跳得更|升幅大` 机构拟人/空比较；命中就改成「谁、数字、跟谁比」 - 结构性元叙述、假想读者错误、意义通胀、顺手补分析 - 社交稿再按 `references/social-output-gate.md` 扫一遍：changelog 综述、否定开场、`一、二、三` 功能并列、口号收尾、名人硬挂钩、导演句、空比较 - 社交稿出声测试：每句问「朋友之间会不会这么说」；不会就重写，不要只换词 工作顺序固定为:先按 skill 出完整稿 → 立刻扫描 → 硬修句式和禁用词 → 抽读关键段落 → 再交付可发布版。不要把“按 skill 写了”误当成“通过 skill 质检”。 ### 硬规则 - **不能把 AI 生成的"像真的"当成"真的"**——必须核实。 - **不能让 AI 自动补齐不存在的实验结论**。 - **不能把 AI 的平滑表述原样端上去**——必须二次改写。 - **不能一轮生成直接发布**。 - **不能抄别人的框架/观点不标来源**。 - **发布稿只面向读者,不留编辑痕迹**:正文中不出现"这一版"/"上一稿"/"按要求改过"等写作过程记录。 --- ## 六、质检体系 完整四层质检规则见 `references/quality-gate.md`。写完后按 L1 硬性规则、L2 可读性、L3 内容深度、L4 活人感逐层检查；L4 必须纳入 `references/human-feel.md` 的具体性、意义通胀、同义词轮换、格式用力过猛和矫饰性表达检查。社交稿还要过 `references/social-output-gate.md`。质检只输出报告，不自动修改内容；社交稿质检不通过则重写正文，再交可发布版。 --- ## 七、精修 mode 当用户要求“精修”“润色但不重写”“只改 AI 味”时，读取 `references/refinement-mode.md` 和 `references/human-feel.md`。精修只动词句和格式，不改结构、事实判断或新增论点。