ai-article

name	ai-article
description	用于AI类内容的撰写。支持四种风格：安装教程类（手把手教学）、产品评测类（有观点有数据）、面试对话类（面试场景）、深度拆解类（读源码/读官方博客，用一手证据拆解技术机制）。专注于AI Coding工具的实测（比如Claude Code、Qoder、Codex等）；AI开发框架的应用（比如SpringAI、LangChain等）；大模型（GLM、通义千问、DeepSeek、MiniMax、Kimi等）的测评；各种 Agent、Skills、RAG 等 AI 技术栈的讲解，力求透彻、详细、手把手。

AI 技术文章的生成工作流

环境声明

执行前跑 date "+%Y年%m月%d日" 拿当前日期。联网搜索关键词、frontmatter 的 date、正文时间描述，都用这个日期。

---

写作原则

语气和称呼

用"大家/我们/小伙伴"和读者拉近关系，少用"你"。

表达直抒胸臆（全文强制）

一句话能说清楚的事，不要用两句话绕弯弯。读者来看文章是为了拿到信息、学到知识、感受到情绪价值，不是听你做铺垫。

禁止的绕弯模式：先铺垫再说正事（"在介绍 X 之前，先了解一下 Y"）、假设式开场（"如果你遇到过 X，那么一定知道 Y"）、定义式起手（"所谓 X，就是指 Y"）、层层递进废话（"要理解 X，需要先明白 Y"）、同义反复（同一个判断换说法再说一遍）、无信息量的过渡（"说完了 A，接下来看看 B"）。

书面表达还是口语表达（全文强制）

判断方法：这句话和技术相关吗？ 只要句子承载了技术信息（机制、原理、参数、数据、操作步骤、技术结论），一律走书面表达。

书面表达——所有技术相关的句子：

• 准确无误，清清楚楚：用词准确无歧义，读者看一遍就懂。禁止用网络梗、模糊比喻、生僻词描述技术行为——读者看完觉得莫名其妙的词，一律换成书面表达
• 不要缺字：主语、宾语、限定条件写全，不指望读者靠语境脑补。"压缩策略优先保留前缀部分，因为命中前缀缓存的 token 成本只有未命中的十分之一"——原因、对象、数据都在句子里
• 描述事实：技术陈述句不要叠加修辞手法，判断和事实分开写——先陈述源码/文档怎么写的，再单独一句给自己的判断
• 可验证性：每个技术断言要么有出处（源码、文档、实测），要么明确标注"我的推断是"，不把推断写成事实
• 禁止网络腔、拟人

情感表达——不承载技术信息，陈述的是我的情感、遭遇、感受：

• 允许真实的情感："有一说一，不黑不吹""太用心了兄弟"

前言表达（强制）

1. 打招呼：「大家好，我是二哥呀。」独立成段
2. 钩子：热点事件、反差冲突或直击痛点的问题（"有没有想过？Claude Code 的代码搜得又快又准，到底是怎么实现的？"）
3. 声明：一句话说清楚为这篇文章付出了什么——"我花了一早上时间，翻了翻 Boris Cherny 的播客、亚马逊的论文、Claude Code 源码，把这件事从头到尾捋了一遍"。

正文结构

## 01、标题 / ## 02、标题。标题只写名称，不加冒号后缀解释，错误例子：## 01、标题：解释。三级标题 ### xxx，不加分类前缀。

问题驱动（深度拆解类强制）

好的技术文章不是"我知道什么就写什么"，而是"读者会问什么，我按什么顺序回答"。

操作方法：

1. 确定主题后，先列出读者最可能问的 5-8 个问题（从"这是什么"到"怎么用好"逐步深入）
2. 砍掉太基础或太偏门的，保留 4-7 个串联起来
3. 每个章节标题就是一个问题（或问题的答案），章节内容就是回答这个问题
4. 问题之间可以有递进关系：前一个问题的答案自然引出下一个问题

每个问题的回答结构：先给结论（一句话）→ 展开论证（证据+解读）→ 收一句实操建议。问题链示例见 references/deep-analysis.md「结构模板」。

技术术语尺度（全文强制）

所有风格的文章都禁止出现项目自定义类名。读者不认识这些类名，堆砌只会让人困惑。

• 禁止：项目内部的类名、方法名、变量名（如 AgentBudget、McpServerManager、ToolInvocation、doExecuteTool、buildStepContext）
• 保留：Java 标准库（ConcurrentHashMap、CompletableFuture、LinkedHashMap）、业界公认术语（JSON-RPC、MCP、Function Calling、ReAct、toolCalls、system prompt）
• 替换方式：用通俗的功能描述代替。AgentBudget → "循环预算机制"、ToolRegistry → "工具注册表"、McpServerManager → "MCP 管理模块"、doExecuteTool → "在执行工具时"

英文术语首次标注：英文术语首次出现时用"中文翻译（English term）"格式，如"异步生成器（async generator）"，后续直接用英文。MCP、RAG 等已约定俗成的缩写直接用，不展开全称。

Case 创意

尽可能有趣，让读者眼前一亮。

涉及 Agent 可以和 PaiAgent 结合、RAG 可以和派聪明结合、CLI可以和 PaiCLI 结合（路径见步骤 2）。

段落与列表各得其所

正文默认用段落表达，用完整句子和自然过渡，长短句交替，符合公众号阅读习惯。一个段落最多两个句号——公众号在手机上读，段落一长读者就划走，到第二个句号就换段。能用一段话说清楚的事，不用列表。

冒号纪律（对话体也不豁免）：对话引导一律用句号（“老王点点头。”+ 独立引号段），禁止“老王问：”式冒号引导；叙述句里的冒号改成逗号、句号或拆句。只有三处允许用冒号：列表引导句（“做了三件事：”）、列表项的“术语：解释”格式、简历包装的字段名。

但是，出现 3 个以上并列项时必须用列表（第一/第二/第三、一是/二是/三是、方式一/方式二/方式三）。用"第一...第二...第三...第四..."的段落形式写多个并列项，读起来既累又有浓重的 AI 味。

判断顺序（从上往下，命中即停）：

1. 并列项能用"，"或"、"连成通顺的一句话（如"支持 A、B、C 三种格式"）→ 段落
2. 并列项 ≥ 3 个 → 列表
3. 并列项只有 2 个，且每项不超过一句话 → 段落

特色元素

简历包装环节

文章涉及实战项目/GitHub 仓库时加一段：

项目名称：xxx 项目简介：xxx 技术栈：xxx、yyy 核心职责：

• （5 条，公式：用了什么技术栈，解决了什么问题、实现了什么业务、有哪些量化数据，不能出现自定义类名）

截图占位符（强制）

每个章节（包括二级标题、三级标题、四级标题）至少 1 个占位符，超过 500 字的章节安排 3 个占位符（前中后），格式：

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

风格只能选以下 6 种之一，不能自造：

风格	适用场景
whiteboard	默认白板架构图，适合系统架构、模块关系、数据流
skill-card	技能卡片、目录树、少文字的结构展示
data-board	统计看板、柱状图、热力表、数据对比
three-layer	三层结构、金字塔、台阶、层级关系
swimlane	泳道流程、多人协作、并行时序
checklist-card	注意事项、准备清单、避坑卡片

示例：

【截图：Skill 的结构；风格：skill-card；截图目标：展示 Skill 目录里 SKILL.md 必需，references/scripts/assets 可选，并且按需加载；关键词：SKILL.md、references、scripts、assets、按需加载】

---

工作流程

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

精读 ./sucai.md，提取关键信息、数据、观点、截图。素材中的截图可以直接搬进正文，减少改稿成本。

选题质检（读完素材后立即执行）：

用 IKR 三维度评估素材是否撑得起一篇好文章：

• I (Insight) 有没有读者不知道的信息差？（源码发现、实测数据、反直觉事实、从未有人做过的横向对比）
• K (Knowledge) 读完能带走什么？（可执行的操作、可复用的认知框架）
• R (Resonance) 能戳中什么情绪？（"原来如此"的恍然、"我也遇到过"的共鸣、"竟然可以这样"的惊叹）

步骤 2：调查真实细节（强制）

项目相关内容必须先调查再写，不能凭通用知识猜。编出来的细节一眼假，浪费时间。

角色边界

文章以二哥第一人称写作。

AI 负责做的（放心生成）：

• 补充技术背景知识（框架原理、API 文档、源码解读）
• 找证据和佐证（官方数据、GitHub 星标、基准测试）
• 按确定的角度扩写段落内容
• 梳理逻辑结构、调整章节顺序
• 调查公开信息（仓库、文档、博客）

调查深度分层（按文章类型选择最低层次）

如果执行到此步骤时尚未确定风格，默认按中层调查。步骤 4 确定为「深度拆解类」后，必须回到本步骤补充深层调查。

层次	做什么	举例	适用风格
表层	搜官方博客、文档、公开榜单	"官方说支持 X 功能"	安装教程类（最低要求）
中层	去 GitHub 看 README、issue、PR、commit 历史	"这个 PR 的讨论里提到了设计取舍"	产品评测类（最低要求）
深层	读源码，找到具体实现，用代码片段证明观点	"源码里这个常量是 0.01，意味着只占 1% context"	深度拆解类（最低要求）

深层调查的 5 步操作方法和代码片段筛选标准，见 references/deep-analysis.md「深层调查操作方法」，深度拆解类撰写前读。

证据-解读交织写法（深度拆解类强制，其他类型鼓励）：

不要只给结论。正确的节奏是：抛出问题 → 展示一手证据（源码/数据/官方原文）→ 用自己的话解读证据的含义。读者看到证据才会信服你的结论。正反示范见 references/deep-analysis.md「示范2：源码证据 + 解读」。

步骤 3：搜集资料 + 整理证据清单

补充可引用的公开信息（公开榜单、官方基准、第三方测试）。准确数据必须访问原始来源：GitHub 星标去仓库、榜单去 HuggingFace/LMSYS、跑分去官方发布。禁止二手转述，避免"听说""网友表示"。无法访问时注明"截至 YYYY-MM-DD"。

写正文前必须整理"引用证据清单"，至少包含：结论 + 来源链接 + 发布时间 + 为什么可以相信。未检索到证据时，清单里明确标记"未检索到有效证据"。禁止伪造数据。

步骤 4：文章风格选择

用 AskUserQuestion 让用户四选一：

• 安装教程类（参考 references/OpenClaw-install.md）：手把手教学，注重实操指导
• 产品评测类（参考 references/deepseek-tui-review.md 和 references/deepseek-v4.md，均为读者高赞验证过的正例）：有观点有数据，真实体验实况叙事
• 面试对话类（参考 references/anshui-yin-mianshi.md，读者高赞验证过的正例）：要硬核，有技术支撑，对话体面试场景
• 深度拆解类（写法指南 references/deep-analysis.md + 高赞正例全文 references/claude-code-grep-vs-rag.md）：读源码/官方博客，用一手证据拆解技术内幕，问题驱动结构

选择判断：如果素材的核心卖点是"好不好用、值不值得装"→ 产品评测类；如果核心卖点是"它内部怎么工作的、为什么这么设计"→ 深度拆解类。前者读者看完决定"装不装"，后者读者看完理解"为什么"。

重要说明：

1. 风格参考 ≠ 内容照搬：参考对应文章学习语气、节奏、表达方式，内容必须大胆创新
2. 内容可以大胆：基于你的理解和调查给真实场景、使用体验、case，不局限于 sucai.md
3. 开头结尾别老生常谈：不要每次都套路化，根据内容特点设计有新意的开头结尾
4. 风格与素材不匹配时回退：选定风格后发现素材深度不够支撑，退回步骤 1 重新评估 IKR，或请用户补充素材

步骤 5：撰写文章

⚠️ 撰写前必须扫一眼「写作原则」「特色元素」的硬性约束。读 ./references/human-tone.md 找语感；human-tone.md 里「词语」一节的替换规则全篇适用。

金句主动安排（强制）：按 human-tone.md「金句用法」的触发时机和句式模板，撰写时主动铺设金句，一篇 5-10 处都可以，不设“宁缺毋滥”的心理上限。金句只进情感表达轨，硬禁区（证据、参数、推理链条附近）和遮句测试照旧生效——放开的是数量，不是位置。

文件格式 Markdown。正文目标 4400 字，初稿按 4400 字写，给自检删改留出 400 字余量，确保最终 ≥ 4000。

1. 初稿完成跑 ./scripts/check_body_length.py 检查
2. ≥ 4000 字：达标，进步骤 6
3. < 4000 字：不得交付。计算差额，单次补充量必须 ≥ 差额 × 1.5（例如差 800 字则一次至少补 1200 字），直接瞄 4300 以上，一轮补完。

文章头部模板：

---
title: # 4.6 起标题后回填
shortTitle: # 4.6 起标题后回填
description: # SEO 友好描述，见下方 SEO 规范
keywords: # 页面级关键词列表，见下方 SEO 规范
tag:
  - Agent  # 安装教程类/产品评测类用实际技术标签
  # 面试对话类用：- 面试
category:
  - AI
author: 沉默王二
date: # 用 date 命令拿到的实际日期，YYYY-MM-DD
---

5.1 面试对话类专属规范

仅在步骤 4 选择「面试对话类」时生效。完整规范——对话体框架（老王出场方式、场景描写密度、回答起手交替）、对话体与双轨表达的边界、技术细节尺度（禁自定义类名）、推荐池导向四条硬规则（第一屏续演标题对话、可收藏干货负载、前 600 字关注钩子、自家项目推广限额）、写法示例——全部在 references/interview-style.md，撰写前通读，不在此重复。

5.2 深度拆解类专属规范

以下规范仅在步骤 4 选择「深度拆解类」时生效，其他风格忽略本章。

正文写法的完整规范——问题链结构、章节级四拍节奏、代码片段规范、章节过渡、6 段写法示范、常见失败模式与禁忌——全部在 references/deep-analysis.md（重点看「写作硬规范」一节），撰写前通读，不在此重复。

核心硬约束（不满足不得交付）：每个核心观点必须有一手证据支撑（源码片段 / 官方博客文档原文 / 实测数据 / GitHub issue·PR 讨论），禁止"据说""业内普遍认为""有人发现"这类无来源表述。

5.3 SEO 元数据规范（强制）

• keywords：5 个强相关搜索关键词，覆盖三类——品牌词/项目名（Claude Code）、技术栈（MCP、RAG）、搜索意图长尾词（Claude Code 教程、MCP 面试题）
• description：50-120 字内容摘要，包含 2-3 个核心搜索关键词。示例："拆解 learn-claude-code 开源项目，12 层架构从 Agent 循环到上下文压缩，理解 Claude Code 核心原理。"

步骤 6：三层自检（强制）

落盘前必须跑完三层质检。任何一层有未通过项，回到步骤 5 改稿，不得进入步骤 7。自检完成后向用户展示报告。

L1 机械扫描（可自动检查，零容忍）

这一层检查硬性规则，出现即修复，无例外。

**L1 机械扫描** ✅/❌
- [ ] 禁用词：`human-tone.md`「词语」+「AI 味禁用词汇」两份清单 grep 全文 → （命中数）
- [ ] 标点符号："——"全篇不超过 10 次；"："在叙述句和对话引导中为 0（仅允许列表引导、列表项"术语：解释"、简历字段三处）→ （破折号次数 | 违规冒号次数）
- [ ] 段落长度：每段最多 2 个句号，超出即拆段 → （超标段落数）
- [ ] 半角双引号：正文（代码块和行内代码除外）grep 半角 `"` → （命中数，必须为 0，一律换全角“”）
- [ ] 称呼："你"字不超过 5 次，用"大家/我们/小伙伴" → （实际次数）
- [ ] 标题层级：`## 01、标题`，无冒号后缀 → （是否合规）
- [ ] 开场第一句："大家好，我是二哥呀。"独立成段 → （是否存在）
- [ ] 字数：`./scripts/check_body_length.py` ≥ 4000 → （实际字数）
- [ ] CDN 图片：无捏造链接，不存在的用截图占位符 → （情况）
- [ ] 截图占位符：每章 ≥ 1 个，超 500 字章节 3 个 → （各章节数量）
- [ ] 自定义类名：全文 grep 大驼峰非标准库词（排除 Java 标准库和业界术语），必须为 0 → （命中数）
- [ ] 英文术语首次标注：首次出现的英文术语是否标了中文翻译 → （情况）

L2 风格一致性（模式匹配，需逐段扫）

**L2 风格一致性** ✅/❌
- [ ] 开场三件套：打招呼 + 钩子 + 调查投入声明齐全，声明与实际调查一致 → （用了什么钩子）
- [ ] 双轨边界：技术强相关句子全部书面准确表达——无省略、无网络梗/模糊比喻、无让读者猜的词，读一遍就懂；体验叙事句来自真实素材；（情况）
- [ ] 实测细节（产品评测类）：花费/卡顿/第一反应/最终态度四项来自采集，无编造 → （各项来源）
- [ ] 金句登记：列出全文每一处金句，触发时机以 `human-tone.md`「金句用法」为准；总数少于 3 处视为密度不足，回步骤 5 按触发时机补铺 → （位置 | 命中的触发时机 | 总数）
- [ ] 硬禁区核查：证据展示中、参数/定义/步骤/表格前后、推理链条中间无金句 → （情况）
- [ ] 科学表达：技术细节部分量化优先、一句一事实、断言有出处或标注推断 → （情况）
- [ ] 表达直给：无绕弯复述，逐段"删掉这句少知道什么" → （情况）
- [ ] 句式节奏：无连续 3 句同结构，长短交替 → （情况）
- [ ] AI 句式：`human-tone.md`「AI 味禁用句式」清单逐段扫 → （命中数）
- [ ] 引用溯源：外部结论有来源链接和日期 → （引用数量和来源）
- [ ] 证据密度（深度拆解类）：每个核心观点有一手证据 → （各章节证据类型）
- [ ] 问题链递进（深度拆解类）：章节间有递进，前答引出后问 → （递进逻辑）
- [ ] 推荐池四件套（面试对话类）：第一屏续演标题对话并兑现悬念；中段有可收藏干货负载；前 600 字有系列感关注钩子；自家项目推广 ≤ 一屏且不在最后一屏 → （各项位置）
- [ ] 结尾四拍（面试对话类）：时代对比句绑定本篇话题 + 加粗金句 + 展望升华 + “加油吧，兄弟姐妹们。”固定收尾，对标 `anshui-yin-mianshi.md` 的 ending → （情况）

L3 内容质量（需要判断力，读者视角通读）

这一层不是逐项扫描，是以读者视角通读全文回答：

**L3 内容质量** ✅/❌
- [ ] 信息差：读完能带走什么新东西？有没有段落删掉读者不少知道任何信息？ → （核心信息差是什么）
- [ ] 人味技巧：是否使用了 `human-tone.md`「命名技巧」（扣主线句/逐一展示/回环呼应等）至少 2 种？ → （用了哪些）
- [ ] 心流：从头读到尾，有没有哪里注意力断掉需要回头理逻辑？ → （断点位置）
- [ ] 独特性：换一个 AI 博主能写出差不多的东西吗？哪些段落是"只有调查过才写得出"的？ → （列出独特段落）
- [ ] 遮句测试：把每处金句遮住重读，读者少了信息或情绪共鸣吗？两样都不少的金句是装饰，删 → （各金句判定结果）
- [ ] 活人感终审：以陌生读者视角从头扫一遍，有没有哪一段"一看就是 AI 写的"？ → （标出可疑段落并修复）

总评格式：L1 ✅ | L2 ✅ | L3 ✅ → 进入步骤 7 或 L2 ❌（2项待修复）→ 返回步骤 5

步骤 7：落盘

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

截图链接汇总（强制）：落盘后，把文中所有截图占位符对应的原始来源链接整理成一份清单，方便二哥去截图。格式如下：

## 截图来源链接

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

如果截图来源是论文、官方页面、GitHub 仓库等有明确 URL 的，直接给链接。如果是需要自己操作才能截到的（比如终端运行截图、手机录屏），标注"需自行操作"。