# AI Article

> AI 类文章撰写。三种风格：安装教程、产品评测、面试八股。覆盖 AI Coding 工具实测、AI 开发框架应用、大模型测评、Agent/Skills/RAG 技术讲解。

- Skill: `itwanger/ai-article` (Agent Skill, multi-file: 26 files)
- Install (CLI): `npx skillmds@latest add itwanger/ai-article`
- Raw SKILL.md: https://api.skillmd.com/api/skills/itwanger/ai-article/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: itwanger (https://skillmd.com/u/itwanger)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/itwanger/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：调查

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

| 文章类型 | 最低调查深度 |
|---------|------------|
| 安装教程类 | 表层：官方博客、文档、公开榜单 |
| 产品评测类 | 中层：GitHub README、issue、PR、commit 历史 |
| 面试八股类 | 深层：读源码，找到具体实现，用代码片段证明观点 |

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

**知识库优先**：调查前先检查 `./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 字。面试文章每道题的回答目标就一个：回答清楚，让面试官认可，不限字数。

头部模板：
```yaml
---
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 的智能项目管理系统

---