Tech Article — 技术分享文章创作#

从一个模糊的想法到一篇让读者记住的技术文章。

不是模板填空。是帮你想清楚"我到底要说什么"，然后把它说清楚。

When to Use#

• 要写技术分享但不知从何下手
• 有技术实践想分享但组织不好结构
• 草稿写完了但读起来像流水账
• 需要把一个技术决策/方案写成分享稿
• 准备技术会议演讲稿

When NOT to Use#

• API 参考文档 → doc-gen
• README → readme-craft
• 文章写完去 AI 味 → deslop（本 skill 在 Phase 5 自动调用 deslop）
• 纯调研报告 → deep-research

场景: 团队做了一次 API 迁移，想写团队内部技术分享 输入: /tech-article "我们把 50 个微服务从 REST 迁到 gRPC，花了 3 个月" Phase 1: 识别为"案例复盘型"，核心问题="为什么迁移 + 怎么迁的 + 踩了什么坑" Phase 2: 大纲 = 开头(迁移动机和结果数据) → 决策过程(为什么选gRPC) → 实施路径(分批策略) → 踩坑实录(3个具体故事) → 结果(性能数据对比) Phase 3: 逐段草稿，每段先写核心论点再补充证据 Phase 4: 结构审查 + 细节补充 Phase 5: deslop 两次 pass 去 AI 味 输出: 一篇 15000 字的技术分享稿，评分 8.5/10

错误用法: 直接让 AI 写一篇"关于微服务最佳实践的文章" 没有具体经历、没有真实数据、没有踩坑故事 = 只能产出泛泛的"总结"文 tech-article 需要真实素材作为输入，它帮你组织和表达，不帮你编造 MUST 提供真实经历/数据/代码。NEVER 让 AI 凭空生成技术文章。

Usage#

text

/tech-article "一句话描述你要写什么"     # 端到端，从选题到成稿
/tech-article --outline-only "..."       # 只生成大纲，自己写
/tech-article --review <file>            # 审查已有草稿，给改进建议
/tech-article --type tutorial "..."      # 指定文章类型

模式路由#

模式触发执行 Phase端到端（默认）/tech-article "topic"Phase 1 → 2 → 2.5 → 3 → 4 → 5只出大纲/tech-article --outline-only "topic"Phase 1 → 2，输出大纲后停止审查草稿/tech-article --review <file>读取文件 → Phase 4 审查 → 输出改进建议（不重写）指定类型/tech-article --type tutorial "topic"跳过 Phase 1 类型判断，直接用指定类型进 Phase 2

--review 模式

读取用户提供的草稿文件，按 Phase 4 的结构审查清单逐项检查，输出：

1. 每个检查项的 PASS/FAIL 结果，标注严重度：Critical（阻塞发布——比如全文无具体数据）、Moderate（明显削弱文章）、Polish（微调）
2. 具体的改进建议（带行号引用）
3. 整体质量评分

MUST 不修改原文件。只输出审查报告。

--outline-only 模式

完成 Phase 1（定题）和 Phase 2（搭骨架）后，输出大纲并停止。不进入 Phase 3 写草稿。

Phase 1: 定题 — 想清楚再动笔#

MUST 在动笔前回答这 4 个问题。NEVER 跳过直接写。

text

1. 核心问题: 读者看完能回答什么问题？（一句话）
2. 文章类型: 匹配下方类型表
3. 目标读者: 谁会读？他们已经知道什么？
4. 独特价值: 这篇文章有什么是网上搜不到的？

文章类型#

类型适用场景核心结构读者期待案例复盘做完了一件事动机→决策→实施→踩坑→结果"他们怎么做的，我能学到什么"问题深潜解决了一个难题症状→排查→根因→修复→防护"原来是这个原因"技术选型做了一个技术决策需求→候选→评估→选择→验证"为什么选这个不选那个"原理解析搞懂了一个东西是什么→为什么这样设计→怎么工作→实际表现"终于懂了"教程实战教别人做一件事目标→环境→步骤→验证→常见坑"跟着做就能跑通"趋势观点对某个技术趋势有看法现状→变化→我的判断→依据→行动建议"这个人怎么看"

如果用户输入模糊或缺乏具体素材，按以下顺序提问：

1. 核心经历: "你具体做了什么？解决了什么问题？"（提取真实故事）
2. 数据证据: "有没有具体的数据、代码、截图可以用？"（提取证据）
3. 目标读者: "这篇文章写给谁看？他们的技术水平如何？"（确定深度）
4. 独特价值: "这件事有什么是别人没写过的？"（确定差异化角度）

如果用户在 4 个问题后仍无法提供具体素材，SHOULD 建议用户先积累素材再写文章，或切换到 --outline-only 模式先搭框架。

最后一问——如果读者只看一个段落就转发，会是哪个？答不上来说明文章还没找到核心。这个段落就是你的 scope 锚点，其他内容围绕它展开。

Phase 2: 搭骨架 — 大纲是文章的一半#

万能骨架（所有类型通用）#

text

TL;DR — 3-5 条核心判断，30 秒内让读者知道这篇值不值得读完（可选但强烈推荐）
  ↓
HOOK — 具体数据 + 悬念/冲突/意外，让读者决定继续读
  ↓
CONTEXT — 最少量的背景，让读者能跟上
  ↓
BODY — 2-4 个核心段落，每段一个论点
  ↓
EVIDENCE — 代码/数据/截图/架构图，证明你说的
  ↓
CLOSE — 不是总结，是延伸（反模式表/反思/开放问题）

万能骨架是通用结构。当使用具体文章类型时（见 references/article-types.md），类型模板的 BODY 结构优先于万能骨架的 BODY。HOOK 和 CLOSE 的写法指导始终适用。

大纲不是目录。"一、背景 / 二、方案 / 三、实现 / 四、总结"是目录结构——每个标题是分类标签，读者看完标题不知道你要论证什么。 好的大纲每个标题是一个论点："结构评分预测不了执行效果"、"失败了就别再试同一招"、"40% 的 session 被 agent 自己停掉了"。读者只看标题就能跟上你的论证链。

TL;DR 写判断句不写描述句、HOOK 用具体数据+悬念、小节标题要有信息量——详细写法规则和正反例见 references/writing-guide.md。

大纲模板#

输出格式（给用户确认）：

markdown

## 大纲

**标题**: [标题]
**类型**: [案例复盘/问题深潜/技术选型/原理解析/教程实战/趋势观点]
**预估字数**: [N] 字
**核心问题**: [一句话]

### 1. HOOK (~100字)
[具体的开头]

### 2. [段落标题] (~N字)
- 论点: [这段要证明什么]
- 证据: [用什么证明——代码/数据/截图]

### 3. [段落标题] (~N字)
...

### N. CLOSE (~100字)
[结尾方向——下一步/反思/开放问题]

MUST 等用户确认大纲后再进 Phase 3。

Phase 2.5: 素材调研（可选但强烈推荐）#

大纲确认后、动笔前，做一次素材盘点。好文章的 80% 来自好素材，不是好文笔。

text

□ 竞品内容: 搜一下这个话题已有的文章，看别人写了什么、缺了什么
□ 你的独特素材: 列出你有而别人没有的——内部数据/真实故障/决策过程/代码
□ 可引用来源: 官方文档、论文、基准测试——"studies show" 不行，得说哪个 study
□ 视觉素材: 架构图、监控截图、代码 diff、性能对比表

意图匹配检查：你的文章角度和读者搜索意图一致吗？

读者搜索模式他们想要的你应该写的"X 是什么" / "X 怎么用"学习原理解析 / 教程实战"X vs Y" / "X 替代品"比较技术选型"X 踩坑" / "X 故障"别人的教训案例复盘 / 问题深潜Reddit/论坛出现你的话题真实观点趋势观点（带强观点）

如果你的角度和读者期待不匹配，文章会被跳过——即使写得很好。

Phase 3: 写草稿 — 先完成后完美#

每段先写论点句再补证据。每个技术决策追问 why。每个核心概念配 图/表/代码 至少两种。架构图用 HTML+CSS 色块（见 references/html-diagram-style.md）。

写作节奏、证据优先级、对比表格用法、句级打磨、人味注入的详细规则见 references/writing-guide.md。

Phase 4: 结构审查#

草稿完成后，做一次结构审查。审查分两个维度，分别打分后合并为综合分：

维度 A: 内容质量（50%权重）#

text

□ 主线检查（最重要）：回到 Phase 1 的核心问题，逐章问"这一章在回答核心问题吗？"
  不在回答的章节——要么砍掉，要么移到文章后半部分作为补充。
  前 1/3 的篇幅必须让读者知道"问题是什么"和"方案大致是什么"。
  支线故事（origin story、背景介绍）放在验证/结果之后，读者已有上下文时才插入。
□ 信息不重复：标题说过的结论、TL;DR 说过的数据，正文第一节不要再重复。直接进新信息。
□ 标题：读标题就知道这篇文章讲什么（不要"浅谈/深入/详解"）
□ TL;DR：长文(>20000字)有 3-5 条判断句概括全文核心？
□ HOOK：前 3 句有具体数据或冲突点
□ 小节标题：有信息量，关键转折处用问句（30-50% 为宜）
□ 每段有论点句：遮住证据只看论点句，文章逻辑通吗？
□ 证据三件套：每个核心概念有 图/表/代码 中至少两种？
□ 对比表格：有好做法 vs 差做法 / 方案对比表吗？（目标 5+ 个）
□ Why 追问：每个技术决策后面有解释"为什么"吗？
□ 内容均匀度：各 section 展开深度是否均衡？有没有某个 section 明显单薄？
□ 无废话段落：删掉一段，文章缺了什么？如果什么都不缺就删
□ 结尾不是总结：有反模式表/反思/开放问题（见下方 CLOSE 指导）
□ 长度合适：内部技术分享 10000-20000字 / 掘金 1500-3000字 / 会议演讲 3000-6000字

评分锚定：14/14 项通过 + 每段有具体数据 = 10分；11-13 项 = 8分；8-10 项 = 6分；5-7 项 = 4分；<5 项需要重写。

维度 B: AI 味（50%权重）#

由 deslop 的模式清单覆盖（Tier 1/2/3 + 中文特有 + 结构性模式）。在 Phase 5 中通过调用 @deslop 获取此维度分数。在 --review 模式中，按 deslop 的评分标准手动检查。

综合评分#

text

综合分 = 内容质量分 × 0.5 + AI味分 × 0.5

输出时 MUST 同时展示三个分数，不能只给综合分。示例：

text

内容质量: 7.5/10（轴 3-6 展开偏薄，对比表只有 1 个）
AI 味:    9.2/10（词汇干净，但轴间过渡结构对称）
综合分:   8.4/10

关键原则：一篇干净但单薄的文章不应该拿高分。 内容质量 < 7 时，即使 AI 味 = 10，综合分也不会超过 8.5。这是刻意的——没有内容的"人味"没有意义。

CLOSE 不写总结（三种结尾模式）和标题优化的详细规则见 references/writing-guide.md。

Phase 5: 润色 — 调用 deslop + 合并评分#

草稿通过结构审查后，MUST 调用 @deslop 做两次 pass 去 AI 味。

text

@deslop <draft-file>

deslop 做两件事：Pass 1 逐条去 AI 模式（词汇、句式、hedging），Pass 2 全文鸟瞰检查结构性残留（段落对称、情感平坦、句式齐步走）。评分目标 >= 8/10。

deslop 返回的分数是 AI 味分（维度 B）。MUST 与 Phase 4 的 内容质量分（维度 A）合并，输出综合分：

text

综合分 = 内容质量分 × 0.5 + AI味分 × 0.5

如果 deslop 评分 < 7，回 Phase 4 重新审查结构，可能是内容本身的问题不是表达的问题。如果 deslop 评分 ≥ 8 但内容质量分 < 7， 不要被 deslop 高分误导——文章干净但单薄，需要补内容而不是继续润色。

deslop 不可用时的 fallback#

如果 deslop skill 不可用或调用失败：

1. 按 Phase 3 的"句子级打磨"规则手动检查一遍
2. 按 references/zh-tech-writing.md 的自查清单逐项过
3. 在质量报告中注明 "deslop 未执行，已用手动规则替代"

场景适配#

详见 references/platform-guide.md，包含各平台的字数、格式、SEO、发布时间等完整指南。

Output Artifacts#

text

## 文章信息
- 标题: [标题]
- 类型: [类型]
- 字数: [N]
- 目标平台: [内部博客/掘金/InfoQ/会议]

## 文章正文
[完整文章]

## 质量报告
- 内容质量: [X/10]（维度 A: 主线/证据/对比表/why追问/内容均匀度）
- AI 味:    [Y/10]（维度 B: deslop 评分）
- 综合分:   [Z/10]（= A×0.5 + B×0.5）
- 改进建议: [如有]

文件已保存: [path]

Related#

• @deslop — 反 AI 味（Phase 5 自动调用）
• @deep-research — 技术调研（为文章收集素材）
• @doc-gen — API/模块文档生成
• @readme-craft — README 写作
• @diagram-expert — 架构图/流程图

References#

• 文章类型详细指南和模板: references/article-types.md
• 中文技术写作常见问题和修复: references/zh-tech-writing.md
• 好标题 vs 坏标题对比库 + 句子级打磨: references/title-examples.md
• 平台适配指南（内部博客/掘金/演讲）: references/platform-guide.md
• HTML 图表风格规范（容器/颜色/药丸/对比图）: references/html-diagram-style.md