AI Article

AI 技术文章写作

环境声明

执行前跑 date "+%Y年%m月%d日" 拿当前日期。

第一原则（最高优先级，覆盖一切规则）

读者应当感觉对面有一个具体的人。这个人知道一些事，也有不知道的地方。他愿意讲细节，敢下判断，说话自然。

“活人感”不是靠口头禅、网络梗、错别字装出来的。读者觉得对面是个真人，首先因为你手上有真东西（事实、数据、经历），其次因为你说得清楚自己为什么知道这件事，最后才是语气随不随意。

用校准句检验自己的写法：

他毕业后离开上海，去了成都。那套量化程序已经跑过一段时间，他觉得可以全职试试。收入会不会稳定，当时没人知道。

这比“他关掉一条好走的路，把命运押上赌桌”更接近目标。前一种写法告诉读者他做了什么、条件是什么、风险在哪里，后一种写法什么具体信息都没给，只是在摆造型。

写作优先级（从高到低，遇到冲突按此排序）

1. 读者能学到东西 — 内容有信息差、技术准确、读完能学到知识，或者 get 到具体的行动建议
2. 少即是多 — 写完砍掉三分之一，没有信息损失就说明原来是水分。一个技术方案挑最关键的一两个数字讲透，其余带过
3. 读完觉得作者是个真人 — 有判断、有情绪、有经验，不是知识点的搬运工
4. 格式规范 — 满足下面的格式硬规则

必须遵守的规则（违反就修改）

• 正文标题：## 01、标题，标题只写名称，不加冒号和后缀解释
• 段落要短，手机上阅读舒服。一个段落别超过三个句号
• 列表只用于短小并列的项目（工具清单、检查项、对照表），每项不超过两句话。超过两句话的内容用段落展开，不要压缩成列表项。全文列表控制在 4 处以内，连续两个章节都用列表会让文章像 PPT 大纲
• 冒号：叙述句和对话引导不用冒号，冒号只用于列表引导句、列表项的“术语：解释”格式、简历字段名
• 用“大家/我们/小伙伴”和读者拉近关系，少用“你”
• 禁止项目自定义类名（AgentBudget、McpServerManager），用通俗功能描述代替（“循环预算机制”、“MCP 管理模块”）。面试场景里面试官听到一串英文类名会懵，正文叙述中只用中文功能描述，类名只在代码块里出现
• 英文术语和专业缩写首次出现用“中文翻译（English term）”，后续直接用英文。MCP、RAG、LLM、SSE 等约定俗成的缩写直接用。判断标准：非本领域读者第一次看到，能不能立刻理解？不能就加说明或换通俗的表达（Pod → 实例，RPM → RPM（Requests Per Minute，每分钟请求数））
• 量化数据必须有出处（源码、文档、实测），没有出处就用模糊表达（“大部分”“差不多”），禁止编造精确数字（“60% 以上”“50 行堆栈其中 45 行”）。时间估算也算量化数据——在 AI Coding 时代开发速度很快，“两天写一个简单 MCP Server”不合理，时间估算必须和任务实际难度匹配，AI时代，半个小时就完成了
• 不生造术语（“抽象税”“数据回灌”），用直白描述代替（“抽象开销”“返回数据”）。判断标准：中文技术社区没有广泛使用记录的复合词才算生造；“胶水代码”等有国际通行对应词的术语可以用
• 不能缺字：主语、宾语、指代对象写全，不指望读者靠语境脑补。名词短语写全（“推理的准确性”），动词写全（“调用了什么工具”不写“调了什么工具”，“拆分”不写“拆”），用词不能产生歧义。语气要准确——“不要放在”比“不是放在”更准确（前者是建议，后者是陈述）；“记得设一个过期时间”比“设一个过期时间”更准确（前者有提醒语气）；“我做过三个项目”比“做过三个项目”更准确（前者有主语）
• 模型和产品举例用最新的（Opus 5、GPT-5.6、GLM-5.2），禁止用过时型号
• 热词的所指以当下业界实践为准，先查真实所指再用，不能望文生义
• 引文中的违禁项不享受豁免：直接引文含翻案腔、禁用词等违禁内容时，转为间接引述或省略该部分，不能用引号保护
• 截图占位符格式见下方「截图占位符」一节

写作原则（指导方向，不是逐条打勾的清单）

所谓的论坛感

论坛感不等于“老铁”“兄弟们”“谢邀”“泡杯茶慢慢说”。烟头、啤酒、冷馒头、深夜屏幕和突然响起的电话，也不能凭空替文章增加真实感。

没有来源的精确时间、神态、天气、房间摆设和对白都是假细节。假细节越具体，AI 味越重。

有用的是信息来源——作者在哪里知道的这件事，起初哪里想错了，哪条材料改变了判断，哪一块到现在仍拿不准。

不要用分类代替文章

除非用户明确要求清单或教程，不要先把题目命名成两个成本、三层原因、四个阶段。

每段新增一件东西

新段落必须增加一件新东西——事实、动作、例子、区别、后果都算。同一观点改换说法不算推进。一个技术概念解释一遍够了，不要换三种比喻再各讲一遍。

技术内容走书面表达

承载技术信息的句子（机制、原理、参数、步骤、结论）用词要准确无歧义，读者看一遍就懂。技术陈述和个人判断分开写——先说事实，再给观点。每个技术断言要么有出处（源码、文档、实测），要么标注“我的推断是”。出处要写明——论文标注作者和年份，数值标注来源（源码文件、文档章节、实测条件），算法名标注在哪里用的。用户拿到稿子不应该还需要自己去核实技术细节的准确性。

情感表达走真人口吻

不承载技术信息的句子（感受、态度、经历），用自然口语。“有一说一，不黑不吹”“太用心了兄弟”“我都想给它鞠个躬”——这些好，因为真实。自嘲、预判读者反驳、情绪直给都欢迎，但不要硬造。

直抒胸臆

一句话能说清楚的事，不要两句话绕来绕去。尤其禁止同义反复和无信息量的过渡（“说完了 A，接下来看看 B”）。

前后连贯，有起承转合

“三层原因”“五个维度”“分三步”是最典型的 AI 大纲体。真人回答问题不会先宣布“有三个要点”再一条一条展开，而是直接开始讲第一件事，讲完自然过渡到第二件事。

去掉编号之后仍然可能读着像罗列——只是换了个连接词的并列结构。好的回答有起承转合：前一个点的结论引出后一个点的问题，点和点之间有因果、递进或转折，读起来像一段连贯的叙述，不像一组各自独立的要点拼接在一起。

前言写法

前言是一篇独立的短文，读者只看前言就应该觉得“这个作者有东西”。

三个要素

1. 钩子 — 热点事件、反差冲突或直击痛点的问题
2. 声明 — 一句话说清楚为这篇文章做了什么
3. 姿态 — 前言里的“我”是带大家一起学习的人，带着读者往前走。讲事实要克制，对读者热情、正能量。全文都是在对读者说话，不是在自言自语。

三个要素是骨架，决定前言质量的是每个要素展开的深度。正例拆解和反面模式见 references/preface-examples.md，撰写前必读。

核心立场（强制）

作者是读者的同行者。引导读者学新东西的动机是“在稳定的状态下变得更好”。

去 AI 味

判断方法只有一个：读出来像不像人说的话，人写的词语、成语、句子。 写完每一段，默读一遍，问自己：“如果我在群里发这段文字，朋友会不会觉得是 AI 写的？”觉得别扭就改，改到自然为止。

高频 AI 味特征和禁用词替换表见 references/human-tone.md，全篇适用。

特色元素

简历包装

文章涉及实战项目时加一段：项目名称、项目简介、技术栈、核心职责（5 条，用了什么技术栈 + 解决了什么问题 + 量化数据，不能出现自定义类名）。

截图占位符

每个章节（二级、三级、四级标题各算一个章节）至少 1 个占位符，四级标题也不例外——面试类文章的 #### 往往是追问展开，信息密度高，更需要配图帮助读者理解。超过 500 字的章节安排 2 个，保证图文密度——读者看了一会没看到配图就容易走神。占位符紧贴它可视化的内容，不能只出现在章节末尾。格式：

【截图：<名称>；风格：<风格>；截图目标：<证明什么>；关键词：<关键词1>、<关键词2>、<关键词3>】

风格只选 6 种：whiteboard（架构图）、skill-card（技能卡片）、data-board（数据对比）、three-layer（层级关系）、swimlane（泳道流程）、checklist-card（注意事项）。

工作流程

步骤 1：读素材 + 选题质检

精读 ./sucai.md，提取关键信息、数据、观点、截图。用 IKR 三维度快速评估：

• I (Insight) 有信息差吗？
• K (Knowledge) 读者读完能学到什么？
• R (Resonance) 能戳中读者什么情绪？

素材充分：数一数手上有多少条真实材料（用户经历、具体事实、可引用的数据、直接引用的描述、明确的判断），每 1200 字至少需要 5 条。不够就缩短篇幅，或在步骤 2 补充调研。

步骤 2：调查

项目相关内容必须先调查再写，不能凭通用知识猜。

事实核查：调查到的材料按可信度排序——直接证据（源码、文档、实测）> 官方声明 > 第三方转述 > 自己的推断（标注“我的推断是”）> 不确定的（直接说“没查到”）。核心论点必须有前两级证据支撑。

知识库优先：调查前先检查 ./knowledge/ 目录下是否有缓存调研文件。有缓存时用 git log --since="<调研日期>" 判断变更量：无变更直接用，少量变更增量补充，大量变更或无缓存则派 Sub-agent 全量调研并写入 ./knowledge/。

源码调研用 Sub-agent：读源码、grep 关键参数这些事情，交给 Sub-agent（Explore 或 general-purpose）去做，不要在主对话里直接读源码文件。源码文件动不动就几百行，在主对话里读多个文件会把上下文窗口撑满。

源码只是参考：源码实现如果不够好（设计粗糙、缺少关键机制），答案按业界最佳实践写，按面试官期望的高标准来。大纲里标注哪些答案是基于源码的、哪些是按理想方案写的，用户后续会根据这个来迭代源码。

步骤 3：搜集公开信息

补充可引用的公开数据（榜单、基准测试、第三方评测）。数据必须从原始来源获取，不能二手转述。访问不到的注明“截至 YYYY-MM-DD”。

步骤 4：选择风格 + 参考文章

分两步，都由用户决定。

第一步：选风格。用 AskUserQuestion 让用户三选一：

• 安装教程类
• 产品评测类
• 面试八股类 — 都是有深度的面试题，区别在入口形式。选定后再选形式：
  • 对话体：标题直接“面试官问……”，直问直答节奏（专属规范见 references/interview-style.md）
  • 爆料体：员工爆料/内部消息引入，再展开面试题（写法指南见 references/deep-analysis.md）

第二步：选参考文章。风格确定后，列出所有可选的参考文章，推荐最合适的一篇，但由用户最终决定。可选参考文章：

• references/agent-mianshi-xiaomi.md — 面试对话体，直问直答节奏，Agent工程化方向，读者高赞验证
• references/claude-code-grep-vs-rag.md — 深度拆解体，证据-解读交织，读者高赞验证
• references/deepseek-tui-review.md — 产品评测体，有观点有数据
• references/deepseek-v4.md — 产品评测体，实测对比
• references/OpenClaw-install.md — 安装教程体，手把手教学

用户选定后，写之前先通读这篇参考文章，学它的判断力和节奏感，不是照搬模板。

步骤 5：出大纲（用户确认后再写）

写大纲前先想清楚这几个问题（内部思考，不输出给用户）：

1. 谁在说话？凭什么知道这件事？
2. 什么事件或发现触发了这篇文章？
3. 手上最硬的 3 条素材是什么？
4. 我对哪个点有明确判断？
5. 读者看完这一段，自然会问什么？

想清楚后，用 AskUserQuestion 或直接输出大纲，等用户确认后才进入步骤 6 撰写。大纲必须包含：

1. 风格和参考文章：说清楚本文参考哪篇文章学节奏（比如“参考 agent-mianshi-xiaomi.md 的对话体节奏”），让用户知道写出来大概什么样
2. 结构骨架：章节标题、每道题的题型判断和答案要点（一两句话说清楚核心论点）
3. 源码参考策略：标注哪些答案基于源码、哪些按业界最佳实践写（源码实现不合理时，按面试官期望的高标准来，用户后续会迭代源码）
4. 前言样本：写出完整前言，默认 ~800 字。前言本身就是一篇独立的短文——读者只看前言就应该有收获、有共鸣、有想继续学下去的动力。不包括 sucai.md 里提供的内容。素材本身冲击力足够时（比如压力面开场、强冲突场景），可以缩到 200-300 字直接进正题（参见正例 5、正例 6）。

用户确认大纲后再动手全文撰写，避免返工。

步骤 6：撰写

写之前先看一遍 references/human-tone.md，找找语感。扫一眼 inbox.md 看有没有能用的素材。

文件格式 Markdown，正文目标 4400 字（给删改留余量），最终不少于 4000 字。面试文章每道题的回答目标就一个：回答清楚，让面试官认可，不限字数。

头部模板：

---
title: # 写完后回填
shortTitle: # 写完后回填
description: # 50-120 字 SEO 描述，含 2-3 个核心关键词
keywords: # 5 个搜索关键词
tag:
  - Agent  # 面试对话类用：- 面试
category:
  - AI
author: 沉默王二
date: # YYYY-MM-DD
---

面试八股类

根据第一步选定的形式：

• 对话体：通读 references/interview-style.md 后再写
• 爆料体：通读 references/deep-analysis.md 后再写。核心要点：
  • 问题驱动结构：每个章节回答一个问题，问题之间有递进
  • 证据-解读交织：抛出问题 → 展示一手证据 → 用自己的话解读
  • 每个核心观点必须有一手证据（源码/文档/实测），禁止无来源表述

步骤 7：自检

保存之前做一轮自检。分两级：P0 必须全部通过，P1 提升质量但不影响交付。

P0：必须通过（不通过不保存）

机械检查（跑脚本或 grep）：

• ./scripts/check_body_length.py 检查字数 ≥ 4000
• python3 ./scripts/check_prose.py <稿件路径> 检查翻案腔、破折号、冒号、连词密度、句子长短变化、名词化动词等（失败的必须修，警告的自己判断）
• grep references/human-tone.md「词语」里的禁用词
• grep 正文半角双引号（代码块除外），必须为 0

推进检查（每段问一句“这段新增了什么”）：

• 同一个观点换了种说法重讲的段落，合并或删掉
• ending 是不是在概括全文？概括段删掉，前文已经讲明白了

结尾压力测试：试着删掉最后两段，文章还完整吗？如果删完反而更好，就在那里收住。最后一段如果在概括全文、或者上升到时代意义、人类命运这种高度的，拉回来，回到这篇文章讲的具体的人和具体的事。

P1：建议执行（提升质量）

中文韵律检查（默读一遍，感受句子的节奏）：

• 句子主干出来得够早吗？有没有让读者先读完一大串定语才知道在说什么？
• 句子有长有短吗？连续几段句子长度都差不多的话，就要压短几句、放长几句
• 连词是不是太多？“因为”“所以”“但是”“同时”删掉一半，读不断才补回来
• 有没有把动词变成名词的？“进行了优化”改成“改顺了”，“实现了提升”改成“快了多少”
• 有没有翻案腔？翻案腔的定义和改法见 references/human-tone.md「翻案腔禁止」一节

通读检查（假装自己是第一次看这个话题的读者）：

• 哪里读着卡了、需要回头重读？那里就是不通顺，改掉
• 哪里一看就是 AI 写的？改到自然
• “循环”“它”“这个”——读者知道指的是什么吗？指代不清楚的补全
• 有没有段落删掉后读者也不会少知道什么？那就是废话，删
• 有没有生造的词、生造的比喻？换成日常说法

检查有没有在演（逐段问“这段在表演吗”）：

• 假深度：句子单独看很好看，但其实没有提供事实、解释或情绪。连续几段都用短判断句收尾的，留最好的一句，其他改成平收
• 假细节：没有来源的精确时间、天气、表情、房间摆设、对白。真正有用的细节留，纯装饰的删
• 假口语：“老铁”“兄弟们”“泡杯茶慢慢说”——除非确实是角色的说话方式，否则删。不要靠错别字、脏话、省略号来装真实

段落压力测试：逐段检查——删掉这一段，读者会少知道什么？如果答案是“什么都不少”或者“只是换了种说法”，合并或者删掉。

最后通读（放下规则，当读者来读一遍）：

1. 哪些段落让我觉得作者真懂这件事？——没有这种感觉的段落可能缺材料
2. 哪里读着想跳过？——那里就是水分
3. 哪些结论超过了手上材料能支撑的范围？——缩回去，说到材料能撑住的程度
4. 文章在哪里其实已经讲完了？——后面如果只是在总结或者拔高，删掉

自检完成后给用户一个简短的报告。P0 的问题当场改，P1 的问题列出来让用户决定改不改。

步骤 8：落盘

文件命名用主题关键词，保存到 docs/src/sidebar/itwanger/ai/。

保存后整理截图来源链接清单：

## 截图来源链接

1. 【占位符名称】→ 来源链接
2. 【占位符名称】→ 来源链接

有链接的直接给链接，需要自己操作截图的标注“需自行操作”。

步骤 9：起标题

直接生成 5 个候选标题，不调用 title-generator Skill。素材里有现成标题直接用。

作者与项目

• 作者：沉默王二（二哥），程序员，GitHub：https://github.com/itwanger
• 网站：javabetter.cn（本仓库的部署站点）、paicoding.com（技术派社区）
• 实战项目源码都在 /Users/itwanger/Documents/GitHub/ 下，文章涉及项目细节时直接读源码，不要编造：
  • 技术派（paicoding）— 前后端分离的技术社区系统，即 paicoding.com
  • PaiCLI（paicli）— 对标 Claude Code 的 Java Agent 命令行工具
  • PaiAgent（PaiAgent-one）— LangGraph4j + Spring AI 的工作流编排平台
  • 派聪明（PaiSmart）— 基于 ES 混合搜索的 RAG 知识库
  • PaiFlow（PaiFlow）— 可视化 AI Agent 工作流编排平台，类 Dify/Coze/n8n
  • PmHub（pmhub）— 基于 SpringCloud & LLM 的智能项目管理系统