# Hugo Tech Blog Writer

> 调研用户的问题，提供有来源的回答，并写成带必要配图的 Hugo Markdown 文章。用于研究技术或概念、阅读论文与源码、创建或更新 content/Work、content/Thinking、content/OutOfWork 中的博客、补充解释图与论文证据、上传图片及执行明确授权的提交推送。文章默认作为 Dev 内容；写完后必须由独立子代理使用 article-readability-check 审核，通过不自动转为 Public。

- Skill: `kirrito-k423/hugo-tech-blog-writer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add kirrito-k423/hugo-tech-blog-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kirrito-k423/hugo-tech-blog-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Kirrito-k423 (https://skillmd.com/u/kirrito-k423)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kirrito-k423/hugo-tech-blog-writer

---


# Hugo 技术博客写作器

先调研用户真正的问题，形成有证据的直接回答，再沉淀为脱离会话仍可阅读的文章。已有文章承载同一主题时优先更新；只有独立主题才新建。

**开始前必须阅读并执行 [独立审核与 Dev 发布约定](references/dev-review-contract.md)。** 默认设置 `review_status: pending`，写完后由未参与写作的独立子代理使用 $article-readability-check 终审。可读性通过与 Public 发布授权分开处理。

## 开始前

1. 阅读仓库 AGENTS.md，遵守 Markdown 规则。
2. 新建文章前读取 archetypes/default.md，沿用 front matter 风格。
3. 只检查主题相关的 content/ 文件；用户未要求整理目录时不大范围扫描。
4. 涉及源码定位且仓库存在 .codegraph/ 时优先使用 CodeGraph；纯 Markdown 定位使用定向 rg。
5. 记录 git status --short --branch，把已有改动视为无关内容，除非用户明确纳入范围。

## 完整流程

### 1. 明确问题

把请求收束成一个研究目标，明确用户需要的判断、机制、比较或解释，以及读者背景、技术深度、新建或更新位置、图片上传与 Git 发布授权。

不影响长期范围的选择自行作合理假设。只有缺失信息会实质改变结论、落盘位置、隐私或公开范围时才询问；不要重复请求已经获得的授权。

### 2. 先研究再写作

围绕问题收集足够的一手证据，不为填满模板搜集材料。来源优先级：

1. 本地源码和仓库文档，用于判断实现行为。
2. 官方文档、规范、项目主页、发布说明和源码仓库，用于判断 API 与产品行为。
3. 原始论文和正式会议资料，用于研究结论。
4. 高质量二手来源，仅用于背景或一手材料缺失的情况。

用户要求调研、事实可能变化、引用的论文或网页尚未读取、把握不足时联网核实；技术研究优先一手来源，必要时使用机器已配置的代理。

内部维护简短证据账本：主张 → 来源 → 来源日期或版本 → 置信程度 → 文章位置。区分来源事实与推断，记录冲突和未验证处，核对关键数字、实验设置、模型版本与日期。不得编造引用、实验结果、代码路径或论文结论。

### 3. 先形成回答

先给结论，再展开文章。交付必须回答原始问题，不能只报告创建了文件。按结论、机制或证据、必要条件与取舍、文档和发布结果组织回答。

### 4. 写作与配图

按下文规则选择新建或更新，维护元数据，从直觉讲到证据。先写稳定的主线，再用少量高价值图像降低理解成本，不为每节强制配图。

### 5. 自检、独立审核与发布

检查 Markdown、图片链接、引用和差异；完成全部内容后按共享约定派发独立子代理，等待真实可读性结论，修订后复审。默认保留 Dev，审核通过不会自动公开。仅在“Git 发布流程”允许的授权范围内提交和推送。

## 新建或更新

优先更新：用户指定文件；已有文章讲相同概念、项目、论文、工具或工作流；请求补充笔记、例子、引用、修正或段落；拆成新文会割裂同一论点。

适合新建：没有现成文章；主题的读者目标、抽象层次或长期系列不同；用户明确要求新文；加入现有文章会使其失焦或过长。

不确定时简短说明判断并继续；仅在落盘选择影响长期组织时询问。

## 按主线选目录

- content/Work/：技术、编程、AI、工程、论文、工作方法、业务学习和研究笔记。
- content/Thinking/：认知、规划、方法论、价值判断和长期思考。
- content/OutOfWork/：生活、健康、设备、娱乐、旅行和个人事务。

更深层目录表达文章的主要概念轴，例如 Work/Artificial Intelligence/ 对应模型、训练、推理和 Agent；Work/Programming/ 对应语言、工具和软件实践；Work/HPC/ 对应性能、系统、加速器、kernel 与并行计算。

尊重已有目录与系列命名，仅在能明确长期主题时增加层级。

## 调研与引用

- 引用贴近它支持的判断，指向官方文档、仓库、项目页、论文摘要或会议页面，不引用搜索结果页。
- 关键论文结论尽量标明论文及 Figure、Table、章节或实验。
- 源码结论标明可获得的仓库版本、文件、符号、PR 或提交。
- 文末可设“参考资料”，但关键归因不能只藏在文末。
- 优先转述，直接引文短而必要。
- 自绘图标明“自绘示意图”，不能当作原始实验依据。
- 跨来源综合推断需说明推断身份。
- 来源冲突时解释分歧，优先采用最接近原始事实的证据。

涉及论文时，按方法、任务、数据集和机制检索，覆盖必要的奠基工作、直接相关的新研究及有意义的反例。优先正式发表版本，记录 arXiv 或会议 URL、年份与版本。阅读支持文章结论所需的方法、设置、结果、消融及限制，不只看摘要。区分论文证明了什么与本文推断了什么；只保留改变解释、证据或实践结论的论文，完成调研后再决定配图。

## Front matter

沿用 archetypes/default.md 的字段与风格：

- title：简练英文关键词，不写完整句。
- categories：少量稳定大类。
- series：连续主题使用统一名称。
- tags：可检索关键词，专名保留正确大小写。
- summary：简洁并与导言一致。
- review_status：新建或修改默认 pending，保留已有 private / withdrawn；按共享约定确保 Dev 隔离。
- toc、date、hidden、comments、authors 等已有字段：除受本次内容修改影响或用户要求外保留。

修改既有文章时保持结构，只更新相关字段；元数据保全不意味着沿用旧版本的公开资格。

## 文章结构与风格

1. 使用导言块时以 `!!! abstract "导言"` 开头，其后紧跟 `<!-- more -->`。
2. 先直觉与动机，再按需给定义、推导、例子或实现。
3. 中文文章使用短而清楚的中文小节标题，层级通常不超过三层，不为层级而层级。
4. 顺序、流程与优先级使用有序列表；并列观点、条件与取舍使用无序列表。
5. 嵌套列表使用四个空格缩进；适量加粗关键判断、概念、结论与行动。

背景、核心概念、分析、实践、常见误区、总结与参考资料按主题需要选择，不强制套齐章节。默认中文写作，英文术语统一、混排留空格。偏技术与学术，但从直觉讲清，使用有解释力的例子、对比与反例，避免口号、表情、套话与装饰。必要时说明未验证判断和来源条件，不堆砌免责声明。

## 技术密度

工程文章每段应提供理解主线所需的事实、机制或判断依据，例如源码、API、配置、指标、约束、数据与控制流，或必要的验证方法。删除只表达“重要”“有前景”“值得研究”的空话。

PR 或源码分析围绕变更状态、关键执行路径、迁移影响及验证结论组织；文件清单、命令、排障过程与回滚信息只有帮助读者理解或操作时才保留。内部研究账本可以详尽，读者正文应提炼理念与效果。只在测量模板中使用“待测”，不能拿它替代结论。

## 源码证据

重要结论依赖源码、PR、算子封装、模型补丁或运行分支时，提供最小有用片段：

- 标明文件或函数、关键分支、tensor shape 或配置，以及最终 API 或算子调用。
- 关键逻辑优先原始源码；适配草图与跨框架归一表达可用伪代码。
- 通常截取 5 至 25 行，省略不改变语义的导入、注释和控制流。
- 紧接着解释应观察什么：构造哪个 tensor、选择哪个分支、调用哪个算子，以及该处尚未处理什么。
- 算子迁移文在资料可用时至少保留一个真实调用点，图、公式与概述不能代替调用证据。
- 两阶段路径应展示两阶段，例如从 position_ids 构造 MRoPE 的 cos/sin，再调用 torch_npu.npu_rotary_mul 处理 q/k。
- 关键片段附内联来源或脚注，不能只放入文末参考资料。

## 公式、图与提示块

先讲什么从哪里移动到哪里、哪个路径消费它、哪个字段决定行为，再按需给公式。

- 公式只用于消除歧义，附近定义全部符号，并配合 shape 例子、短伪代码、tip 或图。
- 算子或 kernel 文章说明模型位置、运行路径和相关的并行上下文：替换哪个子路径、输入与控制 tensor、分组顺序、前反向行为，以及 DP/TP/EP/CP 中的通信位置。
- 图与代码附近明确读者应注意什么，不让它们独自承担解释。
- 出现 T_e、offset_e、W_e 等多组索引时补一个小例子，例如 token 如何进入 expert 桶、group_list 如何映射行与权重。
- 使用 tip、example 和短表格解释直觉与必要条件，复杂公式放在直觉之后。

Material for MkDocs 提示块按用途选择：abstract 概览、note 补充、tip 实践、question 提问、warning 误区、example 例子、failure 反例。不连续堆叠，每个提示块服务一个清楚的目的。

## 图像证据流程

### 通用解释图

核心机制、前后对比、失败模式、数据流、反馈、瓶颈或概念关系难以仅靠文字理解时，调用 $ian-xiaohei-illustrations，遵循其分镜和生成流程。

选择少量高价值图，最终文件放入 `assets/<article-slug>-illustrations/`。保留生成原图与仓库副本一致，上传前用 shasum -a 256 核对。找不到原始生成文件时不要换工具重画冒充原图。

### 论文证据图

只为实质支撑主线的论文或概念调用 $paper-figure-supplement，补充一张解释方法、架构或流程的逻辑图，以及一张最有力的实验图或表。

优先裁取论文原图。论文没有清楚可用的逻辑图或需要简化中文解释时才使用小黑自绘图；真实实验证据不得用生成图替代。阅读选图周边文字，解释测量对象、基线和控制条件，以及它支持的结论与必要边界。

使用简短 `<figure markdown>` 图注，标明论文 Figure/Table 编号或“自绘”。

### 上传与链接替换

文章远程引用的最终生成图或裁图使用 $image-cloud-uploader：

1. 以绝对路径上传仓库中的图片。
2. 优先 PicGo/PicList，正常路径失败时才用该 Skill 的 R2 后备流程。
3. 核对 success: true、文件与 URL 一一对应，以及公开 URL 可访问。
4. 只替换目标链接，保留 alt text 与图注。
5. 上传后保留本地图。
6. 不显示、编辑或提交图床凭据。

论文配图 Skill 已上传的图片不重复上传；其余图片可批量上传。替换后验证文章全部远程图片，不提交失败或私有上传链接。

## 修改既有文章

1. 尽量保留作者声音与结构。
2. 在最窄的合适位置补充，不把所有内容堆在文末。
3. 仅在主题范围变化时更新标题、标签、系列或摘要；审核状态遵守 Dev 默认规则。
4. 保留导言及 `<!-- more -->`。
5. 除非文章逻辑失效或用户要求润色，避免大幅改写。

过时、不确定或冲突的内容优先简短更正或说明，不默默删除有效历史。独立审核提出越出修改授权范围的建议时，保留 Dev 并如实报告。

## Git 发布流程

只有用户明确要求推送、发布或完整流程时才提交和推送；研究、回答、草稿或文档编辑本身不授权推送。**推送部署默认仍是 Dev，Public 需要明确授权与最终版本独立审核通过。**

提交前：

1. 回看初始 git status。
2. 审阅 `git diff -- <target-markdown> <intended-assets>`。
3. 对目标文件运行 git diff --check。
4. 执行可用的 Hugo/MkDocs 或 Markdown 验证，并按共享约定检查 Public/Dev 可见性。
5. 确认没有私人临时路径、坏链接、凭据或未归因的关键论文图。
6. 核对独立子代理审核针对最终版本；审核后内容或合并发生变化则重新审核。
7. 只暂存文章和必要资源，不暂存无关改动。

提交信息简练，例如 `docs: add <topic>` 或 `docs: update <topic>`。向当前分支配置的 upstream 非强制推送；缺少 upstream、认证失败、远端拒绝或分叉无法安全处理时如实报告，不改写历史或扩大范围。

推送后验证提交哈希与分支。报告文档路径、生成图与论文图数量、图片 URL 或上传摘要、实际验证、独立可读性结论、Dev/Public 状态、提交与分支，以及未解决的证据或渲染问题。

## 完成检查

- [ ] 文章直接回答用户的问题，关键结论有一手来源或明确标为推断。
- [ ] 目录合适，元数据沿用模板，标题、分类、系列与标签有检索价值。
- [ ] 导言之后保留 `<!-- more -->`，中文标题简洁，层级适当。
- [ ] 列表、加粗和提示块克制，嵌套列表四空格缩进，无表情或装饰性施工标记。
- [ ] Markdown 兼容 Hugo/MkDocs，新增内容可正确渲染。
- [ ] 解释图解决阅读问题，选中的论文配有逻辑图和真实证据图或表。
- [ ] 远程图片来自验证成功的上传结果，自绘与论文证据归因准确。
- [ ] 最终正文经过独立子代理的 $article-readability-check，缺失或未通过时如实标为 Dev 草稿与未完成项。
- [ ] 文章默认 Dev，不因审核通过或推送 main 自动公开。
- [ ] 获得授权时，Git 暂存与推送仅包含本次文章和资源。