gracker 技术文章写作
面向技术从业者的写作 skill，尤其适合 Android、性能优化、工程工具和系统机制类内容。 写作定位:工程师视角,技术精确、结构清楚、判断明确、实战痕迹重,不卖弄不端着。 长文按本文件写；X/Twitter、社交总结、定时任务可发布稿先按对应平台 skill 搭结构，再按
references/social-output-gate.md把关。
技术文章的核心是三件事:
- 准确:术语、版本、路径、代码、数据都能对上。
- 有用:读者看完知道怎么观察、怎么判断、怎么落手。
- 易读:不是把信息塞满,而是把复杂问题讲顺。
不是资讯搬运,不是情绪发泄,不是 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 工作稿整份发出去。不怕写长，怕写乱——有材料就写开，每段一个中心、有顺序；不要为了整齐压成提纲，也不要堆散点。
一、写作原则
核心目标
让读者真的看懂、能拿去用、知道边界——不是让读者觉得作者很懂。
六条底盘
- 工程师视角先于情绪视角:先讲问题、系统、工具、路径,再讲感受和态度。
- 作者必须真的在场:文章里能看到真实工作流痕迹——为什么碰到、怎么观察、用了什么工具/trace/命令/代码路径、哪步最易误判、自己怎么下判断。
- 结构感强,标题自己会说话:读者扫标题就应该知道全文骨架。
- 判断明确,但必须交代依据和边界:给出判断后必须跟依据、条件、适用范围。
- 技术表达敢写实:工具名、模块名、类名、轨道名、参数、版本、路径、命令都敢写具体。
- 结尾克制,不做空洞升华:技术文章收束即可,不要硬拔高度。
信息密度
目标不是"每句都很满",而是"每句都推进理解"。
- 一段只做一件事:下定义、解释机制、展示证据、下判断,不要乱炖。
- 高密度解释段中间要插入短结论句/列表/图表/代码观察点,给读者换气。
- 不要连续塞 4 个以上新概念,必要时拆段。
- 核心观点全文只出现 2 次:定义 + 总结。中间段落直接使用,不再反复解释。
- 删掉后不影响理解的段,就是"正确的废话",删。
呼吸感
呼吸感不是抒情,是认知负担控制:
- 长解释段后面跟一句短判断。
- 复杂机制前先给全景图。
- 长代码块前先说"重点看哪几行"。
- 关键节点加读者引导,例如:
先记住一个结论:.../到这里,A 和 B 的区别已经清楚。
可读性优先于表面完整
展开顺序:问题是什么 → 为什么值得看 → 先建立整体图 → 再下钻细节 → 最后给判断和边界。不是所有东西都要一次讲完,按读者的理解顺序讲。
二、文章结构
常见 5 类长文
- 技术深度/系列解析:讲清机制、观测方法、分析路径。结构:问题定义 → 背景概念 → 系统流程 → trace/代码/图示 → 实战建议。
- 工具实战/架构复盘:说明为什么这样设计、怎么落地、踩过什么坑。结构:起因 → 关键判断 → 方案拆解 → 取舍 → 边界。
- FAQ/Q&A:把读者最关心的问题逐个说透。结构:问题列表 → 逐题结论 → 证据/误区/边界。
- 方法论/行业观察/判断型:把分散经验提炼成判断框架。结构:现实问题 → 作者判断 → 拆维度 → 反例/代价/边界。
- 工具体验/读书/社群/人物:有个人色彩但仍然交付实用价值。结构:缘起 → 内容/工具/观点 → 作者补充理解 → 推荐/总结。
默认骨架
【开头】直接交代问题、场景、文章任务
↓
【背景】为什么值得聊,读者能带走什么,需要哪些前置知识
↓
【主体】按 3 到 8 个板块展开,每块只解决一个问题
↓
【判断】把局部观察提炼成更高一层的理解
↓
【结尾】压缩结论、补边界、给后续阅读或行动建议
开头
三句内必须完成三件事:这篇在讲什么、为什么值得看、读者看完能带走什么。
四种常用开头:
- 系列定位型:
本文是 XXX 系列的第 N 篇,主要讲 YYY。 - 近期事件/读者反馈型:
上一篇发出去之后,大家最常问的是... - 认知修正型:先说原先怎么想,再说真正用过后发现什么。
- 先给判断型:开头先给判断,再展开理由和边界。
开头禁区:
- 不要从"在这个时代""随着技术发展"开讲。
- 不要先讲大背景,再慢慢靠近主题。
- 不要先端一个正确废话当帽子。
- 不要把目录感写成汇报感。
主体
- 一段一义:每段只承担一个任务,不要在一个段里同时做 3 件事。
- 先给全景图,再下钻:整体图景 → 关键模块 → trace/代码/数据 → 结论。
- 关键节点做读者引导:
先建立整体图景。/到这里先记住一个区别。/下面再看这个结论是怎么来的。 - 顺序设计:先放基线,再放进阶例子,最后放最能改写理解的例子。
- 概要和详述分工:如果有"概要"和"展开"两个章节,概要只点结论(2-4 行),展开负责细节。同一内容不在两处各写一遍。
- 系列文章不重述:前文已定义的概念,后文引用即可,不重新展开。
- 模仿别人时模仿结构不模仿句式:借鉴的是判断组织方式、证据编排顺序,不是表面句式和历史排版噪音。
- 项目规则不混进通用规则:项目专属术语、版本展示、品牌语气和信息架构放到项目覆盖规则里,不要写进通用写作规范。
句式与节奏
- 先直说,再展开:第一两句就把中心说出来,不要兜圈。
- 长句装信息,短句落锤:长句交代背景/边界/对象,短句下判断。
- 不用第一人称:不写"我认为"/"我建议"/"我通常会"。直接给结论或步骤。
- 真实细节可借,表演感不可借:犹豫、取舍、踩过的坑可以出现;强情绪喷发、网络口癖、戏剧化段子感不可以。
结尾
优先四种收法:
- 一句判断收尾。
- 正文后给 references/延伸阅读。
- 给读者下一步动作。
- 回扣开头问题一次,不做文学化回环。
结尾禁区:
- 不要突然上价值。
- 不要把结论写成口号。
- 不要假装开放式结尾其实什么也没说。
- 不要把全文又空泛复述一遍。
三、禁用词与句式
完整规则见 references/style-rules.md、references/copy-editing.md 和 references/human-feel.md。写作、改写、质检前必须按需读取，尤其是：禁用词库、意义通胀、顺手补分析、否定-纠正结构、假想读者错误、冗余确认副词、翻译腔动词、结构性元叙述、抽象名词主语、同义词轮换、硬换行、中英文空格、机器可读内容边界、术语大小写和中文错词规则。
Android、性能优化、Perfetto、系统机制类文章还要读取 references/android-terminology.md。这类文章里，渲染链路、输入链路、Binder 调用链、BufferQueue、fence 等词可能是准确术语，不能因为命中黑话词库就机械替换。
四、展示规范
代码
- 代码块前必须有"用途句":交代这段要证明什么、读者重点看哪里、看完要得到什么结论。
- 代码块内要可读:用标准 Markdown 代码块并标注语言,命名/缩进/换行遵循语言 style guide。
- 可以省略但要明确:用该语言的注释标明,别用含糊的
...。例如// Several unrelated lines are omitted. - 代码后必须有"解释句":解释为什么这里关键、如何和上文结论对应、读者实战里怎么观察。
- 大段代码的处理:正文只保留骨架和关键路径,过长代码放仓库/Gist/附录。
- 代码质量:能运行的给可运行版本;不能运行的明确说明是"示意/伪代码/节选";不准编造不存在的 API/类名/方法名。
数据
- 先决定表达形式:一句话能说清用文字,少量对比用列表,多指标对比用表格,趋势/波动用图表,时序关系用流程图。
- 数据必须有参照物:任何数字都要补单位、测试条件、对比基线、是否稳定复现、样本范围。
- 表格不是堆料区:只放读者需要横向比较的字段。
- 图表不是装饰:要回答一个明确问题。
- 结论必须回连数据:图表/表格后面必须补一句解释这组数据支持/不支持什么。
列表
**核心原则:列表不能是目录,必须是内容。**每个列表项必须自带信息增量,读者读完该项就知道"这是什么/为什么/怎么用"。
❌ 禁止的写法:
- 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。精修只动词句和格式，不改结构、事实判断或新增论点。