| 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、正文时间描述,都用这个日期。
目录结构
ai-article/
├── SKILL.md # 本文件
├── sucai.md # 本次写作素材(临时)
├── biaoti.md # 标题风格参考(含面试类标题)
├── references/
│ ├── OpenClaw-install.md # 安装教程类参考
│ ├── web-access.md # 产品评测类参考
│ ├── PaiAgent.md # 面试对话类参考范文
│ └── human-tone.md # 活人说话语感
└── scripts/
└── check_body_length.py
⚠️ 「写作原则」「去 AI 味」「特色元素」三章是写正文时的强制约束,尤其是「步骤 4 撰写文章」阶段必须严格遵守。
写作原则
语气和称呼
用"大家/我们/小伙伴"和读者拉近关系,少用"你"。敢于表达你的情绪和认知。技术描述/技术细节保持准确直白,不拟人,不加比喻。
文章开头
前 3 段内完成冲突(痛点/争议)→ 结果(一句高价值结论)→ 收益(读者读完能收获到什么)。
正文结构
## 01、标题 / ## 02、标题。标题只写名称,不加冒号后缀解释,错误例子:## 01、标题:解释。三级标题 ### xxx,不加分类前缀。
Case 创意
尽可能有趣,让读者眼前一亮。
涉及 Agent 可以和 PaiAgent 结合、RAG 可以和派聪明结合、CLI可以和 PaiCLI 结合(路径见步骤 1.5)。
段落优先(强制)
正文默认采用段落表达,用完整句子和自然过渡表达观点。能用一段话说清楚的事,尽量不用列表。
如果段落太长,并且有一、二、三这种情况再考虑使用列表。
检查方法:如果列表项之间能用","或"、"连成通顺的话,说明应该用段落。
ending 规则
用 ## ending 作为结尾,短句换行制造节奏。用具体场景代替抽象道理。
可以用排比。金句用【xxx】框起来。可以往这些方向靠近:工作的意义不只是赚钱、技术是为了让生活更美好。
我们必须保持更年轻的心态,什么是更年轻的心态?就是在内心深处还相信,自己的成长空间至少还有 100 倍,而不是世界已经糟糕这么多年了,我这份工作还不错,虽然不喜欢,但凑合过吧。
去 AI 味
读者看二哥是因为有判断、有喜好、有人情味。
1. 禁止"定义→好处→意义"三段式。不要"说白了/本质上/核心在于"开头下定义。
2. 禁用 AI 味词汇:
- 总结性套话:值得注意的是、需要指出的是、综上所述、由此可见、不难发现、此外、与此同时
- 夸大意义:标志着、见证了、是……的体现/证明/提醒、凸显/彰显了其重要性、为……奠定基础
- 宣传性语言:充满活力的、深刻的、令人叹为观止的、开创性的
- 模糊归因:行业报告显示、观察者指出、专家认为、多个来源表明、官方发布、网友表示
- 互联网黑话:赋能、抓手、闭环、打通、沉淀、对齐、拉通、链路、收敛、咬合、回灌、透传
3. 禁用 AI 句式:
- 否定式排比:不仅……而且……、这不仅仅是……而是……
- -ing 结尾肤浅分析:……,确保了……、……,体现了……、……,彰显了……
- 过度限定软化词:可以说、在某种程度上、从某种意义上讲
- 通用积极结论:未来可期、前景光明、值得期待
- 综艺话术:听起来 X 好像更优雅?别急、这哪是 X,这分明是 Y
- 终局论:可能就是 X 最终的样子、未来一定会 X
- 自我吹嘘过渡:这一点对...特别有启发、我越来越深刻地体会到
- 三段式法则:强行凑三组显得全面,两项或四项更自然
- 原因很直接、格式很直白
4. 禁止编造虚假案例凑字数。不知道的去调查(步骤 1.5),调查不到主动问。
5. 句式节奏:长短句交替,不要连续同结构句(别连续三句"xxx是xxx"判断句)。适当用反问、设问调节节奏,但不要每段都加。段落结尾多样化,不要每段都总结句收尾。一个段落尽量不出现超过 3 个句号。
6. 技术表达不拟人:描述技术概念和系统行为时,用准确直白的表述,不要给技术组件加拟人化动作(如"攥在手里""裸奔""抓瞎""石沉大海")。通顺清晰就够了。
- 技术部分不加拟人,不口语化,不加比喻,保持书面书写规范,力求让小白、新手看完就能明白;在技术描述之外的部分可以适当加点情绪和认知表达,增加可读性和趣味性。
- 技术部分要保持硬核、深度。
- 不要把正常词语强行删减。用正常的书写标准,比如"深度思考"不要写成"深思考","不强制压缩"不要写成"不硬缩","技术报告"不要写成"技报"。用词准确,没有歧义,不需要思考才能懂。
特色元素
简历包装环节
文章涉及实战项目/GitHub 仓库时加一段:
项目名称
项目简介
技术栈
核心职责(5 条,公式:用了什么技术栈,解决了什么问题、实现了什么业务、有哪些量化数据)
截图占位符(强制)
每个章节至少 1 个占位符,章节长的话,可以安排3个占位符(前中后)每个二级标题的内容至少有一个,三级/四级标题也要有,格式:
【此处插入<名称>:截图目标:<证明什么>;关键词:<关键词1>、<关键词2>、<关键词3>;建议位置:<位置>】
位置只能有 1 个,不能写"A/B"这种二选一,可以是命令行、网页、架构图、白板。
示例:
【此处插入Claude Code 执行截图:截图目标:证明模型先拆解再执行;关键词:任务拆解、执行计划、变更说明;建议位置:架构图】
工作流程
步骤 1:读素材
精读 ./sucai.md,提取关键信息、数据、观点、截图。素材中的截图可以直接搬进正文,减少改稿成本。
步骤 1.5:调查真实细节(强制)
项目相关内容必须先调查再写,不能凭通用知识猜。编出来的细节一眼假,浪费时间。调查不到的用 AskUserQuestion 问用户,不要编造。
步骤 2:搜集资料 + 数据溯源
补充可引用的公开信息(公开榜单、官方基准、第三方测试)。外部引用必须保留来源链接和日期,避免"听说""网友表示"。
准确数据必须访问原始来源:GitHub 星标去仓库、榜单去 HuggingFace/LMSYS、跑分去官方发布。禁止二手转述。无法访问时注明"截至 YYYY-MM-DD"。
步骤 3:整理证据清单(先于写作)
写正文前必须整理"引用证据清单",至少包含:结论 + 来源链接 + 发布时间 + 为什么可以相信。
未检索到证据时,清单里明确标记"未检索到有效证据"。禁止伪造数据。
步骤 3.5:文章风格选择
用 AskUserQuestion 让用户三选一:
- 安装教程类(参考
references/OpenClaw-install.md):手把手教学,注重实操指导
- 产品评测类(参考
references/web-access.md):有观点有数据
- 面试对话类(参考
references/PaiAgent.md):要硬核,有技术支撑,真实面试场景
重要说明:
- 风格参考 ≠ 内容照搬:参考对应文章学习语气、节奏、表达方式,内容必须大胆创新
- 内容可以大胆:基于你的理解和调查给真实场景、使用体验、case,不局限于 sucai.md
- 开头结尾别老生常谈:不要每次都套路化,根据内容特点设计有新意的开头结尾
步骤 4:撰写文章
⚠️ 撰写前必须扫一眼「写作原则」「去 AI 味」「特色元素」的硬性约束。在表达观点和情绪时,读 ./references/human-tone.md,采用二哥喜欢的用词表达和句子表述方式。
文件格式 Markdown。正文目标 5500 字,初稿按 5500 字写,给自检删改留出 500 字余量,确保最终 ≥ 5000。
- 初稿完成跑
./scripts/check_body_length.py 检查
- ≥ 5000 字:达标,进步骤 5
- < 5000 字:不得交付。计算差额,单次补充量必须 ≥ 差额 × 1.5(例如差 800 字则一次至少补 1200 字),直接瞄 5300 以上,一轮补完。
文章头部模板:
---
title:
shortTitle:
description:
keywords:
tag:
- Agent
category:
- AI
author: 沉默王二
date:
---
4.2 面试对话类专属规范
以下规范仅在步骤 3.5 选择「面试对话类」时生效,安装教程类和产品评测类忽略本章。
正文结构(覆盖通用规则)
## content 包裹所有面试题 → 每题 ### 01、问题、### 02、问题。
追问用四级标题:老王的追问直接写 #### 追问的问题内容,不要用"老王追问:""老王继续问:"这种对话体。
不要加"我说:"前缀,直接写回答内容。正文本来就是"我"在讲,不需要反复标注。
示例:
### 03、MCP 的 JSON-RPC 通信协议是怎么工作的
JSON-RPC 2.0,很简洁,只有三种消息类型。第一种是 Request,有 id 字段,需要对方响应……
#### 请求和响应的配对怎么实现的
用一个 ConcurrentHashMap,key 是自增的请求 id,value 是 CompletableFuture……
技术细节尺度(面试类强制)
讲原理和思路,禁止出现项目自定义类名。
- 禁止:堆砌类名(如
McpSchemaSanitizer、NotificationRouter、BrowserGuard),面试时不可能记这些
- 保留:Java 标准库 / 业界公认的技术名词可以用(如 ConcurrentHashMap、CompletableFuture、JSON-RPC、SSE、CDP、MCP、Function Calling),这些大家都认识
- 重点讲为什么这样设计、解决了什么问题,而不是用了哪个自定义类
SEO 元数据规范(强制)
生成 SEO 友好的 frontmatter 字段,目标是让文章能被 Google/百度/bing 搜索命中。
keywords 字段:
填写 5 个与本文内容强相关的搜索关键词,覆盖三类:
- 品牌词/项目名:文章涉及的工具、项目、框架的正式名称(如
Claude Code、Spring AI)
- 技术栈:文章讲解的核心技术概念(如
Function Calling、MCP、RAG、Agent Harness)
- 搜索意图词:用户实际会搜索的长尾词(如
Claude Code 教程、Agent 开发、MCP 面试题)
description 字段(SEO 描述):
50-120 字,必须包含 2-3 个核心搜索关键词。写搜索引擎能理解的内容摘要。
"拆解 learn-claude-code 开源项目,12 层架构从 Agent 循环到上下文压缩,理解 Claude Code 核心原理。"
步骤 4.5:交付前自检(强制)
落盘前必须逐项自检,任何一项未通过,回到步骤 4 改稿,不得进入步骤 5。自检完成后向用户展示清单,格式如下(未通过用 - [ ] 标记并说明修复计划,全部 [x] 后才能进入步骤 5):
## 交付前自检清单
- [x] 称呼:少用"你",用"大家/我们/小伙伴/兄弟姐妹们"(全文检查) → (说明实际情况)
- [x] 标点符号:少用"——",正常叙事(全文检查) → (说明"——"出现次数)
- [x] 开头:别老生常谈,根据内容特点设计(查前 3 段) → (说明开头用了什么手法)
- [x] 标题层级:`## 01、标题`,不加冒号后缀解释(查所有二级标题) → (说明是否合规)
- [x] 截图占位符:每章至少1个,长章节至少3个(查各章节) → (说明各章节占位符数量)
- [x] 字数:正文 ≥ 5000 字,不含代码(`./scripts/check_body_length.py`) → (说明实际字数)
- [x] 引用溯源:外部结论有来源链接和日期(查引用证据清单) → (说明引用数量)
- [x] 原始数据:GitHub 星标/榜单/跑分必须来自原始来源(查数据段落) → (说明数据来源)
- [x] AI 味:通过"去 AI 味"章节全部检查(全文检查) → (说明是否有禁用词)
- [x] 替换规则:`human-tone.md` 禁用词未出现(grep 全文) → (说明 grep 结果)
- [x] CDN图片:禁止捏造 CDN 链接,图片不存在用截图占位符(查所有图片链接) → (说明情况)
步骤 5:落盘
文件命名用主题关键词,保存到 docs/src/sidebar/itwanger/ai/。
截图链接汇总(强制):落盘后,把文中所有截图占位符对应的原始来源链接整理成一份清单,方便二哥去截图。格式如下:
## 截图来源链接
1. 【占位符名称】→ 来源链接
2. 【占位符名称】→ 来源链接
...
如果截图来源是论文、官方页面、GitHub 仓库等有明确 URL 的,直接给链接。如果是需要自己操作才能截到的(比如终端运行截图、手机录屏),标注"需自行操作"。