AI 技术文章写作

硬性规则

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

前言

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

截图占位符

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

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

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

简历包装

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

工作流程

1. 确定输入模式

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

2. 调查

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

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

3. 确定风格和参考文章

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

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

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

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

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

5. 撰写

扫一眼 Skill 目录下的 inbox.md，看有没有能用的素材。字数不设下限，讲清楚就停，不为凑字数加内容。

头部模板如下。

---
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 <稿件路径>，字数写进自检报告，不因为字数多少增删内容
• python3 <Skill 目录>/scripts/check_prose.py <稿件路径>，“需要修改”的必须改，“需要人工判断”的逐条确认
• 当成第一次接触这个话题的读者通读一遍，哪里要多想一步才懂、哪个结论超出了材料能支撑的范围，都改掉

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

7. 落盘和交付

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

交付时附上项目升级计划的更新情况、截图来源清单（有链接给链接，需要自己操作的标注“需自行操作”）、事实来源清单（关键数字和技术细节逐条对应源码位置或原始链接），以及 5 个候选标题（素材里有现成标题直接用；没有就参考 biaoti.md 里打开率高的标题）。

作者与项目

• 作者：沉默王二（二哥），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/ 下