AI 技术文章写作

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

目标

读者读完能学到东西，并且觉得对面是一个真懂行、敢下判断的人。真实感来自手上的真东西（源码、数据、实测、经历）和说清楚自己为什么知道，不来自语气词和编造的细节。

硬规则

• 正文标题 ## 01、标题，标题只写名称，不加冒号和后缀解释
• 段落要短，适合手机阅读
• 列表只用于短小并列的项目（工具清单、检查项、对照表），成段的内容用段落展开，不要连续几个章节都用列表
• 叙述句和对话引导不用冒号，冒号只用于列表引导句、列表项的“术语：解释”和简历字段名；不用破折号
• 用“大家/我们/小伙伴”称呼读者，少用“你”
• 正文叙述不出现项目自定义类名（AgentBudget、McpServerManager），用中文功能描述代替，类名只在代码块里出现
• 读者是有经验的 Java 后端，Kafka 消费者、位移、死信队列、CAS、Full GC、令牌桶、熔断、topK 这类常见概念直接用，不加解释。只解释项目自定义的东西和不常见的术语，工具名、角色名、参数名第一次出现时说清是什么、谁在用
• 全文零歧义，读者不需要多想一步。指代写成具体对象，主语、宾语写全，不用需要先翻译一遍的比喻，不生造术语
• 用户纠正过的用词收在 scripts/wording_rules.py，由检查脚本执行，新的纠正追加进去，同时补进 references/human-tone.md「词语」表
• 量化数据和时间估算必须有出处（源码、文档、实测），没有出处就用模糊表达，禁止编造精确数字
• 技术断言要么有出处，要么标注“我的推断是”。正文直接讲消化后的事实，不复述“帖子里说”“官方介绍”，出处放进交付给用户的来源清单
• 模型和产品举例用最新的（Opus 5.5、Sonnet 5.5、GPT-6 Astra、DeepSeek V4、GLM-5.3）；热词先查清当下业界的真实所指
• 不写没有来源的场景细节（时间、天气、神态、对白）
• 不用翻案腔（先立一个读者没有的误解再推翻），定义见 references/human-tone.md；直接引文里的违禁内容改成间接引述
• 章节和答案按因果往前推进，前一段的结论引出后一段的问题，不用“三层原因”“分三步”这类分类代替叙述（题目本身问的就是分层结构时除外）
• 不写总结段和升华句，事情讲完就停

前言

前言是一篇独立的短文：钩子（热点、反差或痛点）、一句话说清这篇文章做了什么、作者作为同行者带读者往前走。情感方向是“在稳定的状态下变得更好”，不制造焦虑、不功利化。正例和反面模式见 references/preface-examples.md。

截图占位符

每个二、三、四级标题下至少 1 个，长章节 2 个，紧贴它可视化的内容。格式：

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

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

简历包装

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

工作流程

1. 确定输入模式

• 新写：从 ./sucai.md 出发
• 重构优化：用户指定已有文章，结合最新源码重写。保留真实截图和准确的代码，校正和最新实现对不上的内容，删掉废话；章节顺序按读者的问题链重组，不默认沿用原文目录。JobClaw 教程以重构优化为主

2. 调查

项目相关内容先调查再写，不凭通用知识猜。安装教程看官方文档，产品评测看 README、issue、PR，面试八股和深度拆解要读源码、用代码证明观点。

• 先查 ./knowledge/ 缓存，用 git log --since="<调研日期>" 判断要不要增量补充，没有缓存就全量调研并写回 ./knowledge/
• 读源码交给 Sub-agent，主对话只收结论
• 源码实现不够好时，答案直接按面试官期望的方案写，正文不承认项目现状的不足。大纲里标注哪些基于源码、哪些是理想方案；交付时把差距写进项目仓库的升级计划（派聪明是 PaiSmart/docs/interview-upgrade-plan.md，其他项目放在 docs/ 下同名文件），每条写清现状（源码位置）和目标，用户会据此迭代源码
• 公开数据从原始来源获取，访问不到的注明“截至 YYYY-MM-DD”

3. 确定风格和参考文章

自己决定，写进大纲让用户把关。选题不属于任何一种时按素材的问题链组织。

• 安装教程类：参考 references/OpenClaw-install.md
• 产品评测类：规范见 references/review-style.md，参考 deepseek-tui-review.md、deepseek-v4.md
• 面试八股类：规范见 references/interview-style.md，参考 agent-mianshi-xiaomi.md、anshui-yin-mianshi.md
• 深度拆解类：规范见 references/deep-analysis.md，参考 claude-code-grep-vs-rag.md

参考文章学判断力和节奏，不照搬句式。

4. 出大纲，用户确认后再写

大纲包含：风格和参考文章（各一句理由）、章节结构和每章的推进线（用一句话串起来，不分条）、源码参考策略、完整前言样本（默认约 800 字，素材冲击力强时可以缩到两三百字）。

5. 撰写

扫一眼 inbox.md 看有没有能用的素材。正文不少于 4000 字，JobClaw 这类项目教程不少于 3000 字，面试题的答案以讲清楚为准，不限字数。

头部模板：

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

6. 自检

• python3 <Skill 目录>/scripts/check_body_length.py <稿件路径>（项目教程加 --min 3000）
• python3 <Skill 目录>/scripts/check_prose.py <稿件路径>，“需要修改”的必须改，“需要人工判断”的逐条确认
• 正文（代码块除外）没有半角双引号
• 当成第一次接触这个话题的读者通读一遍：哪里要多想一步才懂、哪段删掉也不少什么、哪个结论超出了材料能支撑的范围，都改掉

给用户一份简短的自检报告。

7. 落盘和交付

• toBeBetterJavaer 新写：保存到 docs/src/sidebar/itwanger/ai/，文件名用主题关键词
• JobClaw 新写：放进 docs/ 对应章节目录，拿不准就问
• 重构优化：覆盖原文件，保留文件名和序号前缀

交付时附上项目升级计划的更新情况、截图来源清单（有链接给链接，需要自己操作的标注“需自行操作”）、事实来源清单（关键数字和技术细节逐条对应源码位置或原始链接），以及 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 的智能项目管理系统
  • 求职派（JobClaw）：OpenClaw 风格的多 Agent 求职系统，教程在仓库的 docs/ 下