把一次开发留下来：从工作记录到博客笔记

做完一个模块之后，我希望留下的不只是提交记录，还能有一篇以后找得到、别人看得懂的笔记。真正准备动笔时，先碰到的却是几个很具体的问题：文件放哪儿，开头填什么，写到什么程度可以公开，保存以后网站会不会自动出现。

这次我把这些约定整理成了本地 blog-content-note skill。它服务于一个很短的请求：“把今天这项工作整理成一篇博客笔记。”文章仍然是普通文件，保存在独立的 blog-content 仓库里。

#先找到网站真正读取的文件

内容库和网站代码分开以后，写作入口是 Blog_Content/content/。本地网站读取同级内容库；线上网站从 GitHub 的 main 读取正文。写文章时，只需要修改内容库。

我先对照仓库 README、现有文章和写作手册，再核对网站的内容解析与渲染代码。这个顺序暴露了一处容易照抄的旧说明：手册还在建议把图片放进 public/，但那个目录属于网站工程。向内容仓库新建一个 public/，图片不会因此被网站托管。

因此这次也修正了图片说明。新文章可以引用允许公开、能够访问的 HTTPS 图片；如果要新增网站自身的静态资源，就需要改网站仓库并部署。内容规则必须跟着实际读取方式更新。

#分类取决于这篇文章能留下什么

同一次开发，可以产生两种不同的文章。

如果重点是这次改了哪些功能、为什么发这个版本，它适合成为开发日志。如果重点是一个下次还能复用的办法，例如如何判断某个模块的输出是否正确，它更适合成为经验笔记。

这里的“鲁班”只是项目名称示例，不代表已经完成了某个模块。实际写作时，需要用真实的工作材料替换。

一般先复用已有分类。一个主题积累到需要单独浏览时，再建子目录，用 _folder.json 描述分类名称、排序和编号前缀。没有必要为一篇短笔记先规划一棵复杂目录树。

路径同时决定网址。例如：

content/archive/notes/luban-module-validation.md
→ /archive/notes/luban-module-validation

所以文件名宜短而稳定。文章后续有新结论，就在原文件里补充，保留最初的 date，增加 updated；重命名和移动文件会改变访问地址。

#一份能直接开始写的骨架

普通技术笔记使用 .md 就够了。确实需要提示框、带图注的图片或快捷键组件时，再使用 .mdx。详细样式见写作样式手册。

下面是一份草稿模板。日期要换成实际写作日期，说明文字要替换成实际材料：

---
title: "项目名：一个具体问题与解决办法"
date: "2026-10-05"
summary: "说明问题、采用的办法和适用范围。"
tags: [项目名, 技术主题, 经验笔记]
draft: true
---

先用一段话说清这次做出了什么。

## 问题与条件
环境、版本、触发条件，以及希望解决的问题。

## 实现与取舍
关键步骤、必要的命令或代码，以及选择这个办法的原因。

## 验证结果与限制
实际做过哪些检查、结果是什么，还有哪些情况没有验证。

## 可以复用的经验
下一次遇到同类问题时可以直接采用的做法。

title 和 date 是网站要求的字段；我也会填写 summary 和 tags，让卡片与检索有足够的信息。标题和摘要加引号，可以减少 YAML 把特殊符号识别成语法的意外。文章编号通常由网站生成，不需要每次人工维护。

这些小标题只是起点。很短的排障笔记可以合并章节，复杂的实现则可以增加必要的小节；文章长度取决于需要解释的东西。

#从执行记录里挑出判断依据

工作记录往往按时间排列：试了一个命令，遇到报错，又改了一处。读者更关心触发条件、选择理由和验证结果。

整理时，我会先找出最值得保留的那个问题，再把相关证据放到它旁边。失败尝试只有在解释取舍时才需要保留；代码只截取能让读者复现或理解的部分。

例如，手头只有一次本地测试通过，就应写明环境、输入和这次结果。它不能自动变成“模块已经稳定”或者“所有场景都没有问题”。计划、推断和已验证结果也要分别写清楚。

原始聊天、机器绝对路径、内网地址和完整日志可以留在本地工作材料中。公开文章保留必要的技术条件，引用可访问的源码与文档，让读者不依赖作者的电脑也能理解。

#保存、推送与显示是三个状态

目前的发布链路是：

本地写入文章
  → 检查内容并 commit / push 到 main
  → 网站收到通知，使相关内容缓存过期
  → 后续访问重新生成页面

截至 2026-10-05，这套流程已经有内容推送后的刷新机制；本地文件的每日自动提交、上传尚未启用。因此，编辑器里的“已保存”只说明文件留在本机。

draft: true 会让文章在生产网站中隐藏。它不负责保护敏感信息：文件一旦推送，仍然存在于仓库及其历史中。只想先存一篇未完成的笔记时，就保留草稿状态；准备公开且已获得发布授权时，再改为 draft: false。

手动发布时，只提交本次文章和必要的配套文档。推送成功以后，还要打开文章网址，核对标题、正文和归档入口。这样才能区分“远端已经收到文件”和“读者已经能够看到文章”。

#把容易忘的约定交给 skill

这个 skill 放在本地个人 skills 的共享目录里，便于在不同项目结束工作时调用。它保留内容仓库位置、分类规则、最小模板和发布检查，详细样式继续引用仓库内的手册。

以后可以这样提出请求：

用 $blog-content-note，把今天鲁班项目的这项改动
整理成经验笔记，先保存草稿，并写明目前的验证范围。

明确要求发布时，就沿用已有授权完成提交和推送，再核对网站实际显示。后续配置每日自动上传时，还需要定义哪些文件可以发布、怎样处理草稿，以及上传失败如何反馈；这些留在自动化任务里处理。

下一次开发结束，我只需要提供这次解决的问题、关键改动和验证证据。文章就有了明确的落点，几个月后再回看时，也能知道当时的结论建立在什么条件上。