technical-blog-writing

安装 belt CLI 技能： npx skills add belt-sh/cli

技术博客写作

通过 inference.sh CLI 撰写面向开发者的技术博客文章。

快速开始

需要 inference.sh CLI（belt）。安装说明

belt login

# Research topic depth
belt app run exa/search --input '{
  "query": "building REST API Node.js best practices 2024 tutorial"
}'

# Generate header image
belt app run infsh/html-to-image --input '{
  "html": "<div style=\"width:1200px;height:630px;background:linear-gradient(135deg,#0f172a,#1e293b);display:flex;align-items:center;padding:60px;font-family:ui-monospace,monospace;color:white\"><div><p style=\"font-size:18px;color:#38bdf8;margin:0\">// engineering blog</p><h1 style=\"font-size:48px;margin:16px 0;font-weight:800;font-family:system-ui;line-height:1.2\">How We Reduced API Latency by 90% with Edge Caching</h1><p style=\"font-size:20px;opacity:0.6;font-family:system-ui\">A deep dive into our CDN architecture</p></div></div>"
}'

文章类型

1. 教程 / 操作指南

分步骤讲解。读者应该能够跟着操作并构建出某个东西。

Structure:
1. What we're building (with screenshot/demo)
2. Prerequisites
3. Step 1: Setup
4. Step 2: Core implementation
5. Step 3: ...
6. Complete code (GitHub link)
7. Next steps / extensions

规则	原因
先展示最终效果	让读者知道是否值得继续阅读
明确列出前置条件	不要浪费不适合的读者的时间
每个代码块都应该可以运行	能复制、粘贴并运行才算合格
不只解释“怎么做”，还要解释“为什么”	讲清原理的教程更容易被分享
包含错误处理	真实代码会遇到错误
链接到完整代码仓库	供读者在阅读教程后参考

2. 深入解析 / 解读

深入解释某个概念、技术或架构决策。

Structure:
1. What is [concept] and why should you care?
2. How it works (simplified mental model)
3. How it works (detailed mechanics)
4. Real-world example
5. Trade-offs and when NOT to use it
6. Further reading

3. 复盘 / 事件报告

说明出了什么问题、原因是什么，以及采取了哪些修复措施。

Structure:
1. Summary (what happened, impact, duration)
2. Timeline of events
3. Root cause analysis
4. Fix implemented
5. What we're doing to prevent recurrence
6. Lessons learned

4. 基准测试 / 对比

以数据为依据，对比工具、方法或架构。

Structure:
1. What we compared and why
2. Methodology (so results are reproducible)
3. Results with charts/tables
4. Analysis (what the numbers mean)
5. Recommendation (with caveats)
6. Raw data / reproducibility instructions

5. 架构 / 系统设计

介绍系统的构建方式及其设计决策背后的原因。

Structure:
1. Problem we needed to solve
2. Constraints and requirements
3. Options considered
4. Architecture chosen (with diagram)
5. Trade-offs we accepted
6. Results and lessons

面向开发者的写作规则

语气与风格

应该	不应该
直接表达：“使用连接池”	“你也许可以考虑使用……”
坦承权衡：“这会增加复杂性”	假装自己的方案完美无缺
用“我们”描述团队决策	“我一手设计了……”
使用具体数字：“将 p99 从 800ms 降至 90ms”	“显著提升了性能”
引用来源和基准测试	提出没有来源支持的说法
承认存在其他方案	假装自己的方案是唯一选择

开发者最反感的内容

❌ "In today's fast-paced world of technology..." (filler)
❌ "As we all know..." (if we all know, why are you writing it?)
❌ "Simply do X" (nothing is simple if you're reading a tutorial)
❌ "It's easy to..." (dismissive of reader's experience)
❌ "Obviously..." (if it's obvious, don't write it)
❌ Marketing language in technical content
❌ Burying the lede under 3 paragraphs of context

代码示例

规则	原因
每个代码块都必须可以运行	有问题的示例会摧毁信任
展示完整、可运行的示例	没有上下文的代码片段毫无用处
在围栏代码块中注明语言标识符	启用语法高亮
在代码后展示输出 / 结果	让读者验证自己的理解
使用贴近实际的变量名	使用 calculateTotalRevenue，而不是 foo
在示例中加入错误处理	真实代码会处理错误
固定依赖版本	写“适用于 React 18.2”，而不是“适用于 React”

Good code block format:

```python
# What this code does (one line)
def calculate_retry_delay(attempt: int, base_delay: float = 1.0) -> float:
    """Exponential backoff with jitter."""
    delay = base_delay * (2 ** attempt)
    jitter = random.uniform(0, delay * 0.1)
    return delay + jitter

# Usage
delay = calculate_retry_delay(attempt=3)  # ~8.0-8.8 seconds

### Explanation Depth

| Audience Signal | Depth |
|----------------|-------|
| "Getting started with X" | Explain everything, assume no prior knowledge |
| "Advanced X patterns" | Skip basics, go deep on nuances |
| "X vs Y" | Assume familiarity with both, focus on differences |
| "How we built X" | Technical audience, can skip fundamentals |

**State your assumed audience level explicitly** at the start:

“本文假设你熟悉 Docker 和 Kubernetes 的基本概念。 如果你刚接触容器，请从[我们的入门文章]开始阅读。”

## Blog Post Structure

### The Ideal Structure

```markdown
# Title (contains primary keyword, states outcome)

[Hero image or diagram]

**TL;DR:** [2-3 sentence summary with key takeaway]

## The Problem / Why This Matters
[Set up why the reader should care — specific, not generic]

## The Solution / How We Did It
[Core content — code, architecture, explanation]

### Step 1: [First thing]
[Explanation + code + output]

### Step 2: [Second thing]
[Explanation + code + output]

## Results
[Numbers, benchmarks, outcomes — be specific]

## Trade-offs and Limitations
[Honest about downsides — builds trust]

## Conclusion
[Key takeaway + what to do next]

## Further Reading
[3-5 relevant links]

不同类型文章的字数

类型	字数	原因
快速提示	500-800	一个概念，一个示例
教程	1,500-3,000	分步骤讲解需要详细说明
深入解析	2,000-4,000	需要全面探索
架构文章	2,000-3,500	图表可以分担部分说明工作
基准测试	1,500-2,500	数据和图表承担主要说明工作

图表与视觉内容

何时使用图表

场景	图表类型
请求流程	时序图
系统架构	方框箭头图
决策逻辑	流程图
数据模型	ER 图
性能对比	柱状图 / 折线图
前后对比	并排展示

# Generate architecture diagram
belt app run infsh/html-to-image --input '{
  "html": "<div style=\"width:1200px;height:600px;background:#0f172a;display:flex;align-items:center;justify-content:center;padding:40px;font-family:system-ui;color:white\"><div style=\"display:flex;gap:40px;align-items:center\"><div style=\"background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px\"><p style=\"font-size:14px;color:#94a3b8;margin:0\">Client</p><p style=\"font-size:18px;font-weight:bold;margin:8px 0 0\">React App</p></div><div style=\"color:#64748b;font-size:32px\">→</div><div style=\"background:#1e293b;border:2px solid #3b82f6;border-radius:8px;padding:24px;text-align:center;width:160px\"><p style=\"font-size:14px;color:#94a3b8;margin:0\">Edge</p><p style=\"font-size:18px;font-weight:bold;margin:8px 0 0\">CDN Cache</p></div><div style=\"color:#64748b;font-size:32px\">→</div><div style=\"background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px\"><p style=\"font-size:14px;color:#94a3b8;margin:0\">API</p><p style=\"font-size:18px;font-weight:bold;margin:8px 0 0\">Node.js</p></div><div style=\"color:#64748b;font-size:32px\">→</div><div style=\"background:#1e293b;border:2px solid #334155;border-radius:8px;padding:24px;text-align:center;width:160px\"><p style=\"font-size:14px;color:#94a3b8;margin:0\">Database</p><p style=\"font-size:18px;font-weight:bold;margin:8px 0 0\">PostgreSQL</p></div></div></div>"
}'

# Generate benchmark chart
belt app run infsh/python-executor --input '{
  "code": "import matplotlib.pyplot as plt\nimport matplotlib\nmatplotlib.use(\"Agg\")\n\nfig, ax = plt.subplots(figsize=(12, 6))\nfig.patch.set_facecolor(\"#0f172a\")\nax.set_facecolor(\"#0f172a\")\n\ntools = [\"Express\", \"Fastify\", \"Hono\", \"Elysia\"]\nrps = [15000, 45000, 62000, 78000]\ncolors = [\"#64748b\", \"#64748b\", \"#3b82f6\", \"#64748b\"]\n\nax.barh(tools, rps, color=colors, height=0.5)\nfor i, v in enumerate(rps):\n    ax.text(v + 1000, i, f\"{v:,} req/s\", va=\"center\", color=\"white\", fontsize=14)\n\nax.set_xlabel(\"Requests per second\", color=\"white\", fontsize=14)\nax.set_title(\"HTTP Framework Benchmark (Hello World)\", color=\"white\", fontsize=18, fontweight=\"bold\")\nax.tick_params(colors=\"white\", labelsize=12)\nax.spines[\"top\"].set_visible(False)\nax.spines[\"right\"].set_visible(False)\nax.spines[\"bottom\"].set_color(\"#334155\")\nax.spines[\"left\"].set_color(\"#334155\")\nplt.tight_layout()\nplt.savefig(\"benchmark.png\", dpi=150, facecolor=\"#0f172a\")\nprint(\"Saved\")"
}'

分发

开发者在哪里阅读

平台	格式	发布方式
你的博客	完整文章	首选——掌控自己的内容
Dev.to	交叉发布（规范 URL 指回你的博客）	导入 Markdown
Hashnode	交叉发布（规范 URL）	导入 Markdown
Hacker News	提交链接	项目使用 Show HN，故事使用 Tell HN
Reddit（r/programming、r/webdev 等）	链接或讨论	遵守子版块规则
Twitter/X	帖子串摘要 + 链接	参见 twitter-thread-creation 技能
LinkedIn	改编版本 + 链接	参见 linkedin-content 技能

# Cross-post thread to X
belt app run x/post-create --input '{
  "text": "New blog post: How We Reduced API Latency by 90%\n\nThe short version:\n→ Moved computation to edge\n→ Aggressive cache-control headers\n→ Eliminated N+1 queries\n\np99 went from 800ms to 90ms.\n\nFull deep dive with code: [link]"
}'

常见错误

错误	问题	改进方法
没有概要	忙碌的开发者还没抓住重点就离开了	在顶部用 2-3 句话总结
代码示例有误	彻底损害可信度	发布前测试每个代码块
未固定版本	6 个月后代码就会失效	“适用于 Node 20、React 18.2”
“只需执行 X”	显得轻率、居高临下	删掉“只需”“仅仅”“轻松”等词
架构部分没有图示	用大段文字描述系统	一张图胜过 500 字的描述
营销腔调	开发者会立刻失去兴趣	直接、专业、诚实
没有权衡取舍部分	看起来像带有偏见的营销内容	务必讨论缺点
正文前有冗长的引言	读者会直接离开	用 2-3 段直奔主题
依赖项未固定版本	教程会让未来的读者无法使用	固定版本，并注明撰写日期
没有“延伸阅读”	内容没有后续，也缺少背景	提供 3-5 个链接，加深理解

相关技能

npx skills add inference-sh/skills@seo-content-brief
npx skills add inference-sh/skills@content-repurposing
npx skills add inference-sh/skills@og-image-design

浏览所有应用：belt app list