name: technical-blog-writing description: “技术博客文章写作，包含结构、代码示例和面向开发者的约定。涵盖文章类型、代码格式化、解释深度和开发者特定的参与模式。适用于：工程博客、开发教程、技术写作、开发者内容、文档文章。触发词：技术博客、开发博客、工程博客、技术写作、开发者教程、技术帖子、代码教程、编程博客、开发者内容、技术文章、工程帖子、编码教程、技术内容” allowed-tools: Bash(infsh *)
技术博客写作
通过 inference.sh CLI 撰写面向开发者的技术博客文章。
快速开始
curl -fsSL https://cli.inference.sh | sh && infsh login
# 研究主题深度
infsh app run exa/search --input '{
"query": "building REST API Node.js best practices 2024 tutorial"
}'
# 生成标题图像
infsh 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>"
}'
安装说明： 安装脚本 仅检测您的操作系统/架构，从
dist.inference.sh下载匹配的二进制文件，并验证其 SHA-256 校验和。不需要提升权限或后台进程。手动安装和验证 可用。
文章类型
1. 教程 / 操作指南
分步指导。读者应能跟随并构建某些东西。
结构：
1. 我们要构建什么（带有截图/演示）
2. 先决条件
3. 步骤 1：设置
4. 步骤 2：核心实现
5. 步骤 3：...
6. 完整代码（GitHub 链接）
7. 下一步 / 扩展
| 规则 | 原因 |
|---|---|
| 先展示最终结果 | 读者知道是否值得继续 |
| 明确列出先决条件 | 不浪费错误受众的时间 |
| 每个代码块都应可运行 | 复制粘贴运行是测试 |
| 解释“为什么”而不仅仅是“如何” | 解释推理的教程更易分享 |
| 包含错误处理 | 真实代码有错误 |
| 链接到完整代码仓库 | 教程后参考 |
2. 深入解析 / 解释器
深入解释一个概念、技术或架构决策。
结构：
1. 什么是 [概念] 以及为什么您应该关心？
2. 如何工作（简化心理模型）
3. 如何工作（详细机制）
4. 现实世界示例
5. 权衡和何时不使用它
6. 进一步阅读
3. 事后分析 / 事件报告
描述发生了什么、原因以及修复了什么。
结构：
1. 摘要（发生了什么、影响、持续时间）
2. 事件时间线
3. 根因分析
4. 实现的修复
5. 我们正在做些什么以防止再次发生
6. 经验教训
4. 基准测试 / 比较
数据驱动的工具、方法或架构比较。
结构：
1. 我们比较了什么以及为什么
2. 方法论（使结果可复现）
3. 带图表/表格的结果
4. 分析（数字含义）
5. 推荐（带警告）
6. 原始数据 / 可复现性说明
5. 架构 / 系统设计
解释系统如何构建以及决策原因。
结构：
1. 我们需要解决的问题
2. 约束和要求
3. 考虑的选项
4. 选择的架构（带图表）
5. 我们接受的权衡
6. 结果和经验
面向开发者的写作规则
声音和语调
| 做 | 不做 |
|---|---|
| 直接：“使用连接池” | “您可能想考虑使用…” |
| 承认权衡：“这会增加复杂性” | 假装您的解决方案完美 |
| 使用“我们”表示团队决策 | “我独自架构了…” |
| 具体数字：“p99 从 800ms 减少到 90ms” | “显著改善性能” |
| 引用来源和基准测试 | 做出未引用声明 |
| 承认替代方案 | 假装您的方法是唯一方式 |
开发者讨厌的
❌ "在当今快节奏的技术世界中..."（填充内容）
❌ "正如我们都知道的..."（如果我们都知道，为什么要写？）
❌ "只需做 X"（如果您正在阅读教程，没有什么是简单的）
❌ "很容易..."（轻视读者经验）
❌ "显然..."（如果明显，就不要写）
❌ 技术内容中的营销语言
❌ 在 3 段上下文下埋没主题
代码示例
| 规则 | 原因 |
|---|---|
| 每个代码块必须可运行 | 损坏的示例破坏信任 |
| 显示完整、工作示例 | 没有上下文的片段无用 |
| 在围栏块中包含语言标识符 | 语法高亮 |
| 显示代码后的输出/结果 | 读者验证理解 |
| 使用现实变量名称 | calculateTotalRevenue 而不是 foo |
| 在示例中包含错误处理 | 真实代码处理错误 |
| 固定依赖版本 | “与 React 18.2 兼容” 而不是 “React” |
良好代码块格式：
```python
# 此代码做什么（一行）
def calculate_retry_delay(attempt: int, base_delay: float = 1.0) -> float:
"""指数退避与抖动。"""
delay = base_delay * (2 ** attempt)
jitter = random.uniform(0, delay * 0.1)
return delay + jitter
# 使用
delay = calculate_retry_delay(attempt=3) # ~8.0-8.8 秒
### 解释深度
| 受众信号 | 深度 |
|----------------|-------|
| "开始使用 X" | 解释一切，假设无先验知识 |
| "高级 X 模式" | 跳过基础，深入细节 |
| "X vs Y" | 假设熟悉两者，聚焦差异 |
| "我们如何构建 X" | 技术受众，可跳过基础 |
**在开头明确说明假设的受众水平**：
“本文假设熟悉 Docker 和基本 Kubernetes 概念。 如果您是容器新手，请从 [我们的介绍文章] 开始。”
## 博客文章结构
### 理想结构
```markdown
# 标题（包含主要关键词，陈述结果）
[英雄图像或图表]
**TL;DR：** [2-3 句摘要，包含关键要点]
## 问题 / 为什么重要
[设置为什么读者应该关心 — 具体，不泛泛]
## 解决方案 / 我们如何做到
[核心内容 — 代码、架构、解释]
### 步骤 1: [第一件事]
[解释 + 代码 + 输出]
### 步骤 2: [第二件事]
[解释 + 代码 + 输出]
## 结果
[数字、基准测试、结果 — 具体]
## 权衡和限制
[诚实谈论缺点 — 建立信任]
## 结论
[关键要点 + 下一步做什么]
## 进一步阅读
[3-5 个相关链接]
按类型字数
| 类型 | 字数 | 原因 |
|---|---|---|
| 快速提示 | 500-800 | 一个概念，一个示例 |
| 教程 | 1,500-3,000 | 分步需要细节 |
| 深入解析 | 2,000-4,000 | 彻底探索 |
| 架构文章 | 2,000-3,500 | 图表承担部分负载 |
| 基准测试 | 1,500-2,500 | 数据和图表承担重任 |
图表和视觉元素
何时使用图表
| 场景 | 图表类型 |
|---|---|
| 请求流程 | 序列图 |
| 系统架构 | 框线图 |
| 决策逻辑 | 流程图 |
| 数据模型 | ER 图 |
| 性能比较 | 条形/折线图 |
| 前后对比 | 并排 |
# 生成架构图
infsh 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\">客户端</p><p style=\"font-size:18px;font-weight:bold;margin:8px 0 0\">React 应用</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\">边缘</p><p style=\"font-size:18px;font-weight:bold;margin:8px 0 0\">CDN 缓存</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\">数据库</p><p style=\"font-size:18px;font-weight:bold;margin:8px 0 0\">PostgreSQL</p></div></div></div>"
}'
# 生成基准测试图表
infsh app run infsh/python-executor --input '{
"code": "import matplotlib.pyplot as plt
import matplotlib
matplotlib.use(\"Agg\")
fig, ax = plt.subplots(figsize=(12, 6))
fig.patch.set_facecolor(\"#0f172a\")
ax.set_facecolor(\"#0f172a\")
tools = [\"Express\", \"Fastify\", \"Hono\", \"Elysia\"]
rps = [15000, 45000, 62000, 78000]
colors = [\"#64748b\", \"#64748b\", \"#3b82f6\", \"#64748b\"]
ax.barh(tools, rps, color=colors, height=0.5)
for i, v in enumerate(rps):
ax.text(v + 1000, i, f\"{v:,} req/s\", va=\"center\", color=\"white\", fontsize=14)
ax.set_xlabel(\"每秒请求数\", color=\"white\", fontsize=14)
ax.set_title(\"HTTP 框架基准测试（Hello World）\", color=\"white\", fontsize=18, fontweight=\"bold\")
ax.tick_params(colors=\"white\", labelsize=12)
ax.spines[\"top\"].set_visible(False)
ax.spines[\"right\"].set_visible(False)
ax.spines[\"bottom\"].set_color(\"#334155\")
ax.spines[\"left\"].set_color(\"#334155\")
plt.tight_layout()
plt.savefig(\"benchmark.png\", dpi=150, facecolor=\"#0f172a\")
print(\"已保存\")"
}'
分发
开发者阅读地点
| 平台 | 格式 | 如何发布 |
|---|---|---|
| 您的博客 | 完整文章 | 主要 — 拥有您的内容 |
| Dev.to | 交叉发布（规范 URL 返回您的博客） | Markdown 导入 |
| Hashnode | 交叉发布（规范 URL） | Markdown 导入 |
| Hacker News | 链接提交 | Show HN 用于项目，Tell HN 用于故事 |
| Reddit（r/programming、r/webdev 等） | 链接或讨论 | 遵循子版块规则 |
| Twitter/X | 线程摘要 + 链接 | 见 twitter-thread-creation 技能 |
| 适配版本 + 链接 | 见 linkedin-content 技能 |
# 交叉发布线程到 X
infsh app run x/post-create --input '{
"text": "新博客文章：我们如何将 API 延迟减少 90%
简短版本：
→ 将计算移至边缘
→ 积极的缓存控制标头
→ 消除 N+1 查询
p99 从 800ms 减少到 90ms。
带代码的完整深入解析： [链接]"
}'
常见错误
| 错误 | 问题 | 修复 |
|---|---|---|
| 无 TL;DR | 繁忙开发者未获要点就离开 | 顶部 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
浏览所有应用：infsh app list