tech-blog

name	tech-blog
description	产出中文技术博客，重点解释工具/库/框架/技术路线背后的设计动机与哲学，而不只是功能说明。适用于“写一篇关于 X 的技术博客”“介绍 X 的设计思想”“解释 X 为什么这样设计”等请求。

Tech Blog Writer

产出一篇中文技术博客，回答“它为什么存在、为什么这样设计”，而不是停留在“它能做什么”。

工作流

1. 研究阶段

在动笔前，先建立对项目的深入理解：

• 克隆或直接阅读源码。 不要只看 README；需要读核心模块、梳理关键数据流、定位结构里隐含的设计决策。
• 阅读可获得的文档（architecture、design、contributing、AGENTS.md 等）。
• 找出“一个核心思想（one big idea）”：优秀项目通常在某个核心张力上，给出区别于主流方案的解法。
• 收集 4-6 段代码证据：优先短小、自包含、能体现设计取舍的函数；避免模板化样板代码。

2. 找到对照面

文章必须有显式或隐式的比较锚点：

• 主流方案通常如何解决这个问题？
• 该工具哪里不一样？背后体现了什么取舍？
• 不要写泛泛的“Tool A vs Tool B”表格；应聚焦一个具体设计决策点，展示双方处理方式的差异。

示例框架：

• “多数 agent 用滑窗管理上下文，X 选择 append-only tape。”
• “多数框架提供 DSL，X 坚持 plain Python。”
• “多数 CLI 会猜你想做什么，X 要求显式前缀字符。”

3. 写作阶段

先阅读 references/example-pi-post.md 作为黄金样例。重点学习：如何以个人经验切入、如何在叙述中自然植入对照、如何让代码片段承担论据角色。

随后遵循 references/style-guide.md 的结构与风格规则。

关键规则：

• 全文中文。 代码注释可保留英文；术语保留英文原词并补充中文语境。
• 第一人称，技术向对话体。 不写成学术论文，也不写成口语闲聊。
• 先给代码，再做解释。 代码是证据，文字是论证。
• 每一节都服务于 one big idea。 无法回扣核心思想的段落直接删掉。
• 区分项目原话与作者推断。 项目明确表达的内容要引用或注明来源；自行推断必须明确标注“这是我的判断”。

4. 交付前自检

在输出最终文章前逐项检查：

• 所有代码片段都来自真实源码，没有臆造示例。
• 前 3 段内能让读者明确感知 one big idea。
• 存在具体、可验证的主流方案对照。
• 没接触过该工具的读者也能理解“它做什么”和“它为何这么做”。
• 项目陈述与个人分析边界清晰。