ai-article

# AI 技术文章写作 ## 硬性规则 - 正文标题 `## 01、标题`，标题只写名称，不加冒号和后缀解释 - 列表只用于短小并列的项目（工具清单、检查项、对照表），成段的内容用段落展开，不要连续几个章节都用列表 - 叙述句和对话引导不用冒号，冒号只用于列表引导句、列表项的“术语：解释”和简历字段名；不用破折号 - 正文叙述不出现项目自定义类名（`AgentBudget`、`McpServerManager`）以及偏自定义的行内代码（如内部字段或参数 `hardGate=true`、自定义方法名 `withStorageLock`、内部状态标签 `[LSP 诊断注入]`、私有路径 `~/.paicli/PAI.md`、自定义工具名 `grep_code` 等）；转述源码类名时严禁生硬直译成自造组件名（如把 `SessionLedger` 译成“会话账本”、把 `AutoFactExtractor` 译成“自动事实提取器 / 持久事实抽离”、把内部类译成“某某卸载器 / 协调器 / 守卫”），优先用后端通用工程概念（如“只追加写的会话日志 Append-only Log，配合 Checkpoint 重放”）或“主语 + 直白动词”代替 - 读者是有经验的 Java 后端开发，熟悉 AI Agent，Kafka 消费者、位移、死信队列、CAS、Full GC、令牌桶、熔断、topK 这类常见概念直接用，不加解释；约定俗成的英文术语（如 Token、Skill、MCP、DAG、Checkpoint、WAL、JSON Schema、user 消息、assistant 消息、tool 结果、Worker 等）直接使用，不生硬翻译成“词元”“助手消息”。只解释项目自定义的东西和不常见的术语，工具名、角色名、参数名第一次出现时说清是什么、谁在用 - 零歧义，读者不需要多想一步。指代写成具体对象，主语、宾语写全，技术描述用正常的书面表达，不用无缘无故的拟人或口语化比喻（如“模型偷懒写了一段笼统的流水账”“用户原话”改为“生成了丢失关键信息的笼统摘要”“用户的输入”），不生造术语，也不用“把协议结构抹平”“为了不断开当前推理脉络”这类抽象概括词，直接写具体丢失了什么字段、触发了什么报错或模型如何接着往下执行 - 用户纠正过的用词和禁用词收在 `scripts/wording_rules.py`，由检查脚本执行，新的纠正追加进去，同时补进 `references/human-tone.md`「词语」表 - 量化数据和时间估算必须有出处（源码、文档、实测），没有出处就用模糊表达，禁止编造精确数字 - 技术断言要么有出处，要么标注“我的推断是”。正文直接讲消化后的事实，不复述“帖子里说”“官方介绍”，出处放进交付给用户的来源清单 - 模型和产品举例用最新的（如 Opus 5.5、GPT-6.1 Sol、DeepSeek-V4.1-Flash、Gemini 4 Argon，按需挑选举例即可，无需全部列举），AI Coding 工具用 Claude Code、Codex、Qoder 举例；热点词汇先查清当下业界的真实所指 - 不写没有来源的场景细节（时间、天气、神态、对白） - 员工系列先查 `knowledge/employee-series-published.md` 和 `knowledge/china-ai-company-checklist.md` 的公司别称表，标题优先用菊厂、鹅厂、猪厂等有依据的常见别称；没有稳定别称时不硬造。不把身份不明的员工原声归给某家公司，也不承诺别称可以防止追溯。 - 不用翻案腔，也就是先立一个读者并没有的误解，再推翻它给下文抬价。“不是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` 出发。`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. 出大纲，用户确认后再写 大纲包含风格和参考文章（各一句理由）、章节结构和每章的推进线（用一句话串起来，不分条）、源码参考策略、完整前言样本（通常 300–500 字，短句短段快速切入，素材冲击力强时可以缩到两三百字）。 ### 5. 撰写 扫一眼 Skill 目录下的 `inbox.md`，看有没有能用的素材。字数不设下限，讲清楚就停，不为凑字数加内容。 头部模板如下。 ```yaml --- 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/` 下