SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场technical-blog-writing

technical-blog-writing

写作与研究

查看项目

更新于 10-16 12:54

技能介绍

用途

Technical Blog Writing 是一套面向开发者读者撰写技术博客文章的技能与方法指南，覆盖文章结构、代码示例规范以及开发者受众的写作惯例：文章类型、代码格式、讲解深度等。它同时给出一套可执行的命令流程，用于在写作过程中做主题调研、生成配图与发布。

主要能力

该技能围绕五类技术博客文章给出结构模板：

  1. 教程 / How-To：分步说明，读者能跟着动手构建东西。结构包括：要构建什么（截图/演示）、前置条件、步骤 1 搭建、步骤 2 核心实现、后续步骤、完整代码（GitHub 链接）、下一步/扩展。规则包括：先展示最终结果、明确列出前置条件、每个代码块都应可运行、解释“为什么”而不只是“怎么做”、包含错误处理、链接到完整代码仓库。
  2. 深度解析 / Explainer：深入解释一个概念、技术或架构决策。结构包括：什么是[概念]以及为什么重要、工作原理（简化心智模型）、工作原理（详细机制）、真实案例、权衡取舍与何时不该使用、延伸阅读。
  3. 事故复盘 / Postmortem：描述出了什么问题、为什么、修了什么。结构包括：概述（发生了什么、影响、持续时间）、事件时间线、根因分析、已实施的修复、防止复发的措施、经验教训。
  4. 基准对比 / Benchmark：基于数据的工具、方法或架构对比。结构包括：对比什么及为什么、方法论（保证结果可复现）、带图表/表格的结果、分析（数字意味着什么）、建议（含注意事项）、原始数据/复现说明。
  5. 架构 / 系统设计：解释系统如何搭建以及为何做这些决策。结构包括：需要解决的问题、约束与需求、考虑过的方案、选定的架构（含架构图）、接受的权衡、结果与教训。

面向开发者的写作规则

语气与语调：要直接（如“Use connection pooling”），不要“你可能会考虑使用……”；承认权衡（“这会增加复杂度”），不要假装方案完美；团队决策用“我们”；用具体数字（如“把 p99 从 800ms 降到 90ms”），不要说“显著提升性能”；引用来源与基准；承认替代方案。

开发者讨厌的表达：填充式开场（“在当今快节奏的技术世界里……”）、“众所周知……”（既然众所周知为何还要写）、“只需做 X”（读教程时没有什么是简单的）、“很容易……”（轻视读者经验）、“显然……”、技术内容里的营销语言、把重点埋在好几段背景之后。

代码示例要求：每个代码块必须可运行；展示完整可工作的示例；围栏代码块标注语言标识以启用语法高亮；代码后展示输出/结果；使用真实变量名（如 calculateTotalRevenue 而非 foo）；示例中包含错误处理；固定依赖版本（写“Works with React 18.2”而非“React”）。

讲解深度按受众信号调整：如“Getting started with X”解释一切、假定无前置知识；“Advanced X patterns”跳过基础、深入细节；“X vs Y”假定两者都熟悉、聚焦差异；“How we built X”面向技术受众、可跳过基础。并明确在开头说明假定的读者水平，例如“本文假定你熟悉 Docker 和基本 Kubernetes 概念。如果你不熟悉容器，请先读我们的入门文章。”

理想结构与字数

推荐的博客结构模板：标题（含主关键词、说明成果）→ 主图或示意图 → 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 图；性能对比用柱状/折线图；前后对比用并排对比。

使用方式

需先安装 belt CLI 技能：npx skills add belt-sh/cli，并需要 inference.sh CLI（belt）。登录命令：

belt login

主题调研：

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

生成头图：belt app run infsh/html-to-image --input 传入 HTML 内容。生成架构图、基准图表分别通过 infsh/html-to-image 与 infsh/python-executor 完成（python-executor 支持 matplotlib 生成图表并保存为图片）。发布推文：belt app run x/post-create --input 传入文本。查看全部应用：belt app list。

分发渠道

开发者常读的地方：自有博客（全文，主阵地，拥有内容所有权）；Dev.to（交叉发布，带 canonical URL 回链，Markdown 导入）；Hashnode（交叉发布，canonical URL，Markdown 导入）；Hacker News（链接提交，项目用 Show HN，故事用 tell HN）；Reddit（r/programming、r/webdev 等，链接或讨论，遵守子版规则）；Twitter/X（线程摘要 + 链接）；LinkedIn（改写版本 + 链接）。

常见错误与修正

常见错误包括：没有 TL;DR（忙碌开发者看不到重点就离开，修正：顶部放 2-3 句摘要）；代码示例损坏（摧毁可信度，修正：发布前测试每个代码块）；不固定版本（代码半年后失效，修正：写“Works with 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

适用场景与限制

适用于开发者技术长文、教程、工程博客、事故复盘与基准对比类文章的撰写与分发。限制方面：具体收费、价格与平台限制等事实资料暂未提供。