write-tbp

撰写技术博客文章

本技能介绍如何撰写关于 tldraw 实现细节的技术博客文章。

流程

1. 创建工作区

在本技能目录中为该主题创建一个 assets 文件夹：

assets/<topic>/
├── research.md   # Gathered context and notes
└── draft.md      # The blog post draft

使用简短、kebab-case 形式的主题名称（例如 scribbles、arrow-routing、dash-patterns）。

2. 研究主题

使用 Explore 子 Agent 收集所有相关信息：

Task (subagent_type: Explore, thoroughness: very thorough)

Find all code, documentation, and context related to [TOPIC] in the tldraw codebase.

Look for:
- Implementation files in packages/editor and packages/tldraw
- Type definitions in packages/tlschema
- Related examples in apps/examples
- Any existing documentation in apps/docs/content
- Tests that reveal behavior
- Comments explaining why things work the way they do

For each relevant file, note:
- What it does
- Key functions/classes
- Interesting implementation details
- Any "why" comments or non-obvious decisions

Output a comprehensive summary of how [TOPIC] works. This document will be read by another agent. No need to over-optimize for human readability.

将研究输出保存到 assets/<topic>/research.md。

3. 找出有趣的角度

在写作之前，根据研究回答以下问题：

• 这解决了什么问题？ 不是 "它做了什么"，而是 "如果没有它，会出什么问题？"
• 有什么令人惊讶或反直觉的地方？ 那个行不通的显而易见的方法，或者隐藏的复杂性。
• 关键洞察是什么？ 让解决方案奏效的那个 "啊哈" 时刻。
• 我们最初尝试了什么？ 代码或注释中可见的任何历程或迭代。

如果你找不到有趣的角度，这个主题可能不适合写成技术博客文章。

4. 撰写草稿

按照 blog-guide 的结构创建 assets/<topic>/draft.md：

1. 陈述问题 — 系统做什么，以及如果没有它会出什么问题
2. 展示洞察 — 让它奏效的关键思路
3. 逐步讲解实现 — 代码与解释，逐步增加复杂度
4. 收尾 — 它位于何处、权衡取舍、相关文件的链接

目标为 800-1500 字。

平实地撰写

草稿是供人类编辑使用的原材料，而不是成稿。保持它干净，让内容本身来支撑。编辑会在他们希望的地方加入个性、轶事和冲击力；在一个平实、正确的草稿上做这些，比从一篇过度修饰的稿子中删减要容易得多。

具体来说：

• 开篇直接说明系统做什么以及本文涵盖什么。不要用场景、轶事或假设的用户（"你的火车驶入隧道……"）开头。这些读起来像 AI 填充内容，编辑会删掉它们。
• 从机制出发构建故事：每个部分解决什么问题，按照各部分相互依赖的顺序。张力来自设计（一次扫描看不到删除；修剪器过去会留下一个空洞），而不是来自文字。
• 平实地陈述历程和 bug。"修剪器的早期版本没有推进水位线，因此过期的客户端收到了不含删除的 diff" 就够了。跳过 "我们是吃了苦头才学到这一点" 之类的叙述。
• 不要金句、不要回文对偶、不要结尾的妙语。如果一句话的存在是为了好听而不是为了表达内容，就删掉它。
• 每段最多一个破折号；通常为零。
• 把观点留在收尾部分，并保持简短、具体（"我们接受让离开时间足够长的客户端进行完整重新下载，以换取有界的元数据"）。
• 在属于人类创作的部分（开篇、来龙去脉、权衡取舍），让段落保持平实，而不是编造色彩。在你的交接说明中指出这些位置。

5. 自我评估

对照 blog-guide 检查清单检查草稿：

• 开篇 — 是否在给出解决方案之前平实地陈述了问题，而没有编排的轶事？
• 洞察 — 是否有一个清晰的关键思路，结构是否朝着它构建？
• 具体性 — 是否扎根于 tldraw 的实际实现？
• 代码 — 示例是否有助于理解，而不只是展示语法？
• 语气 — 平实而直接？没有煽情、没有妙语，没有任何编辑会认作 AI 垃圾的东西？
• 链接 — 是否指向仓库中的实际代码？
• 长度 — 深度是否与主题相称？

修改草稿以弥补任何不足。

6. 输出

将最终草稿呈现给用户审阅，并指出人类编辑最可能想要添加色彩的地方（通常是开篇、任何来龙去脉或 bug 故事，以及权衡取舍）。草稿保留在 assets/<topic>/draft.md 中，直到用户满意，届时他们可以将其移动到合适的位置。

参考资料

• 风格指南：有关语气、语调和结构，请参阅 ../shared/blog-guide.md。
• 写作指南：有关通用写作规范，请参阅 ../../VOICE.md。