name: tech-article
description: Writes polished Chinese technical articles for WeChat or blog publication, then optionally generates matching illustrations. Use when user wants to write, draft, optimize, or illustrate a technical article. Handles the full pipeline: type selection → research → draft → fact-check → illustration.
Tech Article Writing Skill
Full pipeline: Type Selection → Research → Draft → Self-Check → Fact-Check → Illustration (optional)
Stage 0: Article Type Selection
首先判断文章类型（如果用户没有明说，根据内容推断并告知）：
| 类型 | 触发条件 | 核心目标 | 典型转发率 |
|---|
| 工具型 (Tool) | 用户做了工具/方法/skill 解决了某个问题 | 读者能立即动手复现 | 15–25% |
| 洞察型 (Insight) | 用户深入研究某技术，发现了规律/反直觉结论 | 读者带走一个认知框架 | 5–12% |
两种类型用不同的结构模板（见 Stage 2）。共用同一套研究流程和行文风格。
Stage 0.5: Pain Point Discovery (Optional)
如果用户还不确定写什么，提供以下引导（最多问 2 个问题）：
痛点挖掘问卷（按可靠性排序）：
- 自己的重复劳动：最近有没有手动做了 3 次以上的事？（最可靠来源）
- 新工具的使用门槛：有没有新发布的工具，中文踩坑教程还缺失？
- 读者/社区的重复问题：有没有人反复在问同一个问题？
- 顿悟时刻：最近有没有"我才明白 ___ ，之前我以为 ___"的时刻？
- "要是有个工具能做 ___ 就好了"：最近有没有这样的念头？
发现痛点后 → 用最小成本验证（脚本/skill 能解决吗？）→ 做出来 → 回到 Stage 1。
Stage 1: Research & Context
Ask at most 2 questions upfront. Assume reasonable defaults for everything else.
| Question | Default if not specified |
|---|
| Topic / Subject + source URL or repo? | — (required) |
| Article type (Tool / Insight) | Inferred from content |
| Target platform | WeChat 公众号 |
| Target audience | 有一定技术基础的读者 |
| Key message / angle | Inferred from content |
| Length | Medium (~1500字) |
If user provides a GitHub repo or URL → use WebFetch to read it before drafting. Do not rely on training knowledge for technical specifics.
研究阶段额外注意：
- 找出反直觉核心观点——这往往是标题和开头的最佳素材
- 收集具体数字（token 数、工具数、性能指标等）——数字是最强的标题锚点
- 记录踩坑细节——真实的失败案例比成功案例更有可信度
- 记录原始引语（代码、原文语录）——后续直接引用，不要全部转述
有大量量化数据时（评测/实验/性能报告）：
- 找出最戏剧性的一对对比——不是平均分，而是"同一个参数改一行，分数从 3.27 变成 8.39"这种
- 确定叙事脊梁：整篇文章只需要一个核心故事线（如"一个 bug 如何改变排名"），其他数据围绕它展开，不要把所有维度摊平成并列关系
- 量化数据必须转化为人能感知的单位——"生成一道代码题需要 48 分钟"比"12,784 个 thinking token"更有冲击力；先写人的感受，再带出原始数字
- 数据图表：matplotlib 生成的图优先用于文章，不要只引用原始数字表格
Stage 2: Draft
Write in Chinese. Use the template matching the article type.
通用风格规则
- 口语化、直接——像跟朋友喝酒时聊技术，不是在台上做分享
- 第一人称，说自己的真实感受，允许有粗糙的边角
- 少用列表，能用散文的地方用散文
- 加粗克制：每节最多一处
- 代码块：始终带语言标签
去 AI 味（强制，每篇文章必须遵守）
AI 生成的中文技术文章有明显的腔调，读者一眼能认出来。以下是具体的禁用规则：
禁用词表——出现即改：
- 填充收尾词：总的来说、综上所述、不得不说、毋庸置疑、值得一提的是
- 互联网黑话：赋能、抓手、打通、闭环、沉淀、链路、底层逻辑
- 伪学术腔：认知框架、可迁移的原则、维度（抽象用法）、可复用（当形容词修饰"教训/框架/认知"时）、深度（当形容词，如"深度解析"）
- 过度归纳：反直觉（偶尔可用，但一篇文章最多出现 1 次；不能当万能标签）、核心发现、关键洞察、最关键的发现、最重要的是
- AI 过渡句："这让我想到一个更普遍的规律"、"这说明了一个重要的事实"、"让我们来看看"、"接下来我们将探讨"
- 煽情定性句："这是整个[评测/过程/项目]里最[X]的[Y]"——这类句式用来放大戏剧性，实际上是作者替读者下判断，删掉让数据自己说话
- 道德总结句："这是一个值得记住的教训"、"这值得所有做[X]的人注意"——事实讲完就讲完，不需要告诉读者这件事重不重要
禁用结构模式：
- "发现一/发现二/发现三"式机械编号——用自然的小标题代替，每个标题说具体的事而不是编号
- 开篇的论文式摘要——不要写"这篇文章讲三件事：第一……第二……第三……"；也不要写"这篇文章写的不只是结论，而是整个过程"这类"预告片"句，让读者自己读到
- 每节末尾的"总结升华"——节的最后一句话应该是具体的事实或观点，不是对本节的复述
- 前后呼应的排比句——"不是因为 A，而是因为 B；不是因为 C，而是因为 D"用一次可以，用两次就有味道了
- 同一层级下多个等权重 H3——5 个问题不需要 5 个等重的 H3 小节；小问题合并进散文段落，只有真正独立且值得展开的才单独成节
- 结论用 bullet 列举——3-4 条 bullet 的结论段是最典型的 AI 腔，改成 1-2 段散文，用因果或转折把要点串起来
应该怎么写：
- 标题用具体的事，别用抽象概括："账对不上才是最大的敌人" > "统计一致性挑战"
- 过渡靠内容自然衔接，别靠连接词硬转——上一节讲完了一个事实，下一节从新的事实开始就行
- 允许不整齐——不是每一节都要有相同的结构，不是每个观点都要配一个例子
- 结尾可以短，一两句话把问题抛出去就行，别搞仪式感
模板 A：工具型文章（Tool Article）
用于：我做了某个工具/方法/skill 解决了一个具体问题
结构（严格按此顺序）：
# 标题
· 格式：[具体动作] + [解决的问题]
· 示例："一句话复刻公众号排版" / "三步本地部署翻译模型"
· 避免："介绍一个 XX 工具" / "探索 XX 的可能性"
## 先给结论（必须，≤100字）
· 解决什么（用户原来怎么做，有什么痛点）
· 怎么做（你的方案是什么）
· 效果是什么（可量化最好）
## 为什么需要它（痛点共鸣）
· 描述用户原来的工作方式——麻烦在哪里
· 不要只说"效率低"，要说具体的麻烦（"每次都要手动对齐段距"）
## 它是怎么工作的（最小可理解版本）
· 拆成 2-4 个步骤，每步说明做什么 + 为什么这样设计
· 关键技术决策 + 背后理由（不只是"怎么做"，还要"为什么这么做"）
· 核心代码/命令可以展示，但只展示关键部分
## 真正解决了哪些"会反复发生的问题"
· 列出 2-4 个具体踩坑细节（增加可信度）
· 每个问题：是什么问题 → 怎么解决的
· 真实失败经历比成功经历更有说服力
## 边界说明（必须）
· 它做了什么（范围内）
· 它不做什么（范围外，明确说）
· 适合谁 / 不适合谁
## 行动项（必须，至少一个）
· 下载链接 / GitHub 地址 / 可直接复制的命令 / Prompt 模板
· 没有行动项 = 丢失 50% 转发动力
工具型文章成功指标：读者读完后有"我要发给 ___ 用" 的冲动。
模板 B：洞察型文章（Insight Article）
用于：做了一件事、研究了一个东西，过程中发现了一些意料之外的事
结构指引（不是死板模板，按需调整）：
# 标题
· 用具体的事说话，不要抽象概括
· ✅ "用 AI 写了 916 个 Zig 算法后，我发现最难的不是写代码"
· ✅ "把 X 推荐算法做成了可视化模拟器"
· ❌ "深度解析 XX" / "全面了解 XX" / "关于 XX 的几点思考"
## 开场（≤150字）
· 先说让人意外的结论或事实，再交代背景
· 不要写"这篇文章讲三件事"——读者会自己发现你讲了什么
## 主体（分 H2 节，每节讲一个具体的事）
· 每节标题必须是具体的事，不是"发现一""发现二"
✅ "账对不上才是最大的敌人" / "最后 25% 花了跟前 60% 差不多的时间"
❌ "发现一：统计一致性问题" / "核心发现 A"
· 每节的展开方式不需要一样——有的节靠数据说话，有的节靠故事，有的节靠代码
· 不要在每节末尾写总结句。节讲完了就完了，读者不需要你帮他归纳
· 重要数据或原话用 blockquote（>），比加粗更有分量
## 收获/教训（靠后但不是必须单独成节）
· 可以融入主体的最后一两节，不用非得单独拎出来叫"可复用的 XX"
· 用大白话说：你之后会怎么做、你觉得别人可以借鉴什么
· 不要用"原则一/原则二"的格式——改成"两件值得记住的事"或直接融进散文里
## 结尾（必须简短）
· 一个问题、一句话，不要超过两行
· ✅ "下次你打算用 AI 批量生成代码的时候，时间表里给管理留了多少？"
· ❌ "本文介绍了 XX，希望对大家有所启发。"
洞察型文章成功指标：读者读完有"我之前没这么想过"的感觉。
WeChat Length Guide
| Type | Target | 适用场景 |
|---|
| Short post | 800–1200字 | 单一技巧、快速分享 |
| Standard | 1200–2000字 | 工具介绍、一般洞察 |
| Deep dive | 2000–3500字 | 多维比较、系统研究 |
| 深度报告 | 4000–8000字 | 有大量原始数据（评测/实验）、踩坑记录详细、需要图表支撑；篇幅由数据密度决定，不要为凑字数而拉长 |
深度报告的额外要求：
- 每个主要章节要有实际数据或原始代码支撑，不能只是叙述
- 章节节奏要有起伏——不是每节都同样长，重要发现多写，周边细节少写
- 图表（matplotlib/数据可视化）是标配，而非可选
Stage 3: Self-Check（写完必做）
工具型文章检查清单
洞察型文章检查清单
Stage 4: Fact-Check & Output
Fact-Check（当提供了来源 URL/仓库时必做）
草稿完成后，对照来源重新核验：
- 配置文件名、环境变量名、CLI 语法
- 功能行为描述
- 安装步骤和前置条件
Output
Save to ./drafts/<slug>.md
# [Article Title]
> **平台**: WeChat / Blog | **字数**: ~XXX字 | **类型**: 工具型/洞察型 | **状态**: Draft
---
[Article content]
---
## ⚠️ 核查记录
| 内容 | 来源 | 状态 |
|------|------|------|
| config filename: foo.yml | source repo | ✅ |
Stage 5: Article Illustration (optional)
After the draft is complete, offer to generate illustrations.
"要不要为这篇文章配图？我可以分析文章结构，推荐插图位置，并生成风格一致的配图。"
Full illustration workflow: references/illustration-guide.md
Style options & compatibility: references/styles.md
Quick Summary
Step 1 — Analyze: Identify 3-5 positions where illustrations add value (core arguments, abstract concepts, processes, data comparisons). Never illustrate metaphors literally — visualize the underlying concept.
Step 2 — Confirm settings (one AskUserQuestion, max 3 questions):
- Illustration type:
infographic / flowchart / comparison / framework / timeline / scene / mixed
- Density: minimal (1-2) / balanced (3-5) / per-section
- Style:
vector / minimal-flat / sci-fi / hand-drawn / editorial / scene
Step 3 — Save outline: Write ./drafts/<slug>/outline.md with position, purpose, visual content, and filename for each illustration.
Step 4 — Save prompt files: For each illustration, save ./drafts/<slug>/prompts/NN-{type}-{slug}.md using the templates in references/illustration-guide.md. Do NOT generate images before all prompt files are saved.
Step 5 — Generate: 使用以下方案生成图片（按优先级）：
方案 A：qwen-image-plus（推荐，文字渲染最佳）
需要 DASHSCOPE_API_KEY，读取 .env 获取。用 Python 脚本调用：
import os, re, urllib.request, dashscope
from dashscope import MultiModalConversation
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'
def gen_image(prompt_file, out_path):
with open(prompt_file) as f:
prompt = re.sub(r'^---\n.*?\n---\n', '', f.read(), flags=re.DOTALL).strip()
resp = MultiModalConversation.call(
api_key=os.getenv("DASHSCOPE_API_KEY"),
model="qwen-image-plus-2026-01-09",
messages=[{"role": "user", "content": [{"text": prompt}]}],
result_format='message', stream=False,
watermark=False, prompt_extend=True, size='1920*1080'
)
if resp.status_code == 200:
url = resp.output.choices[0].message.content[0]['image']
urllib.request.urlretrieve(url, out_path)
return True
return False
⚠️ DashScope 默认模型（z-image-turbo）不适合文字渲染，必须指定 qwen-image-plus-2026-01-09。
每张生成后输出：已生成 X/N。失败时自动重试一次，仍失败则跳过并记录。
Step 6 — Insert: Add  after the corresponding paragraph in the article.
Output Directory
drafts/<slug>/
├── <slug>.md # Article
├── outline.md # Illustration plan
├── prompts/ # Prompt files
│ └── 01-infographic-concept.md
└── 01-infographic-concept.png
