bklit-changelog

Bklit 更新日志技能

为 bklitui.com/changelog 撰写发布说明：一篇 Markdown 文章，以及一张或多张单色抽象 SVG 封面。最终条目应像一篇简短、有信心的产品文章（以 Linear 的更新日志为标准），而不是提交记录。

文件位置

内容	路径
条目（每个条目对应一个 .mdx 文件）	apps/web/content/changelog/YYYY-MM-DD-<slug>.mdx
封面图	apps/web/public/changelog/YYYY-MM-DD-<slug>.svg
封面生成器	.agents/skills/bklit-changelog/scripts/cover.mjs
Schema（frontmatter）	apps/web/source.config.ts → changelog
加载器／排序／搜索文本	apps/web/lib/changelog.ts
动态、时间轴、文章、图片	apps/web/components/changelog/
路由	apps/web/app/(site)/(home)/changelog/ — /changelog、/changelog/page/<n>、/changelog/<slug>、/changelog/rss.xml
SEO（元数据、JSON-LD）	apps/web/lib/changelog-seo.ts
Open Graph 卡片	apps/web/lib/changelog-og.tsx → /api/og/changelog/<slug>

路由 slug 是不带 .mdx 的文件名。每个条目都会自动获得独立的永久链接、站点地图条目、RSS 项目、BlogPosting JSON-LD 和深色 Open Graph 卡片（封面会在深色背景上重新着色为浅色）；无需进行其他注册。动态每页显示 20 个条目，并提供“更新”和“较旧”链接；地址栏会跟随当前阅读的条目更新。

工作流

1. 收集事实。 撰写每周总结时，列出所有已合并的内容：git log --since=<date> --oneline，然后阅读每个 PR 的正文。重要功能单独成篇，其余内容归入一篇 修复与改进 条目（按类别整理项目符号：图表／安装／文档和网站）。阅读已合并的 PR——git log --grep="(#NNN)"、gh pr view NNN——以及你提到的每个 API 对应的文档页面。切勿编造属性：对代码块中写入的每个属性名，都要在 apps/web/content/docs 中使用 grep 搜索。
2. 确定 slug 和日期。 格式为 YYYY-MM-DD-short-kebab-name，日期使用合并当天。若同一天有多个条目，为 date 添加 UTC 时间（2026-10-22T18:00:00Z）——时间较晚的排在前面。
3. 制作封面（见下文封面图）。
4. 撰写文章（见下文写作）。
5. 检查内容。 使用 pnpm dev，在 /changelog 和 /changelog/<slug> 页面检查浅色和深色主题，以及手机宽度下的显示效果。搜索正文中的一个词，确认该词已被索引。

Frontmatter

---
title: Jittered scatter plots
description: Spread overlapping points into a readable strip plot, with deterministic offsets.
date: 2026-10-22
image: /changelog/2026-10-22-scatter-jitter.svg
imageAlt: Columns of dots scattered around vertical guide lines
tags: [scatter-chart, breaking]
---

• title — 功能名称，而非动词：“线性仪表”、“Band 和 TrendLine”。使用句首字母大写格式，不加句末句号，不超过 6 个词。
• description — 一句话，不超过 100 个字符。用于 SEO 和搜索。说明用户现在可以做什么。
• image / imageAlt — public/ 下的封面路径；alt 应描述形状（“由刻度线组成的半圆……”），而非功能。
• tags — 使用小写 kebab 格式；适用时使用图表 slug（bar-chart），重大变更还需添加 breaking。标签可用于搜索。

写作

结构：

1. 导语段落（1–3 句话）。 说明有什么新变化，以及为何重要。前面不要加标题，也不要写“我们很高兴……”
2. ## 分节，每节围绕一个主题，各用 1–3 个简短段落。标题使用名词或短语（“悬停跟随数据点”“新的默认值”）。
3. 结尾附上文档链接：参阅 [散点图文档](/docs/components/scatter-chart)。

代码：先写说明文字。 用文字说明用户现在能做什么，并在行内提及属性（showValue、exit={false}）。每篇最多使用一个代码块，且仅在代码片段本身就是新闻内容时使用（例如安装命令，或能替代大量工作的单行 API）。大多数内容无需代码块——文档链接会提供代码。

风格：

• 使用第二人称和现在时：“传入 jitter，将它们分散开。”
• 具体描述，少用形容词。写明属性、默认值和数字。
• 破坏性变更需单独放在 ## 新的默认值 / ## 破坏性变更 分节中，写明恢复旧行为所需的确切属性，并添加 breaking 标签。
• 开篇先说明问题或用户遇到的情形（“许多行共享同一个日期时……”），再介绍功能。
• 150–350 词（汇总修复时可使用更长的项目符号列表）。删去读者无法据此采取行动的内容（重构、内部重命名、测试变更）。
• 仅使用 ## 和 ###——页面已将条目标题设为 h2。标题不会生成锚点（许多条目共用一个页面）。
• 使用根相对路径进行内部链接（/docs/...、/charts、/studio）。

封面图

封面图应为抽象几何绘图，用来暗示功能——例如数据形状或运动轨迹——而不是截图、徽标、UI 装饰或文字。可以参考 Linear 的博客插图：细线条、大量留白，每张图只表达一个概念。

技术规则（必需）

网站会将封面图作为前景色的 CSS 遮罩（ChangelogImage）渲染，因此同一文件可同时用于浅色和深色模式：

• viewBox="0 0 1600 900"（16:9），背景透明——不要添加背景 rect。
• 仅使用黑色绘制（#000）。通过 stroke-opacity / fill-opacity 表现深度（约 0.15 → 0.9），不要使用其他颜色或颜色渐变。
• 保留约 160px 的安全边距；将构图置于中央。
• 描边为 2–3px（页面上会缩放到约 40%），stroke-linecap="round"。虚线：stroke-dasharray="6 10"。
• 不要使用 <text>、栅格 <image>、滤镜或模糊效果，也不要使用外部引用。文件尽量小于 30 KB。

使用脚本生成

node .agents/skills/bklit-changelog/scripts/cover.mjs --list
node .agents/skills/bklit-changelog/scripts/cover.mjs <motif> apps/web/public/changelog/<slug>.svg [seed]

每种主题和种子组合都会生成确定性的输出——更换种子，直到构图看起来平衡为止。

主题	暗示内容	适用场景
bar-steps	增长、柱形	柱状图、柱形上的标签、堆叠
scatter-jitter	分布	散点图、条带图、点
band	范围、包络	带状图、置信区间、区域范围
step-trend	噪声中的信号	趋势线、回归、预测
gauge	进度	仪表、加载、完成
dot-grid	密度	热力图、贡献网格
radial-bars	比较、评分	基准测试、性能、指标
hue-discs	混合、重叠	调色板、主题、颜色令牌
halo	悬停、焦点	工具提示、悬停状态、交互
swatches	纹理、风格	配方、图案、视觉风格
rails	结构	网站和文档设计、布局
migrate	化混乱为有序	迁移、Agent 技能、工具
waves	从锯齿变平滑	修复和润色汇总

绘制自定义封面

如果没有合适的图案，可以手写 SVG（或在 cover.mjs 中添加一个可复用的图案）。从以下内容开始：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1600 900" fill="#000" stroke="#000" stroke-linecap="round">
  <g>
    
  </g>
</svg>

借鉴风格，而非图画。 Linear 的博客是 风格 参考（细线条、留白、单色），但绝不要复刻 Linear 的某幅具体插画——不要画压缩的竖线条、循环往复的螺旋、从一个角落发散的线条扇形，或带游标的刻度轨道。请使用 Bklit 自身的视觉语言：图表标记（条形、点、色带、弧线）、网站界面元素（导轨、铆钉、边框），以及功能本身的实际形状。

优秀的封面：一个主导形态；通过单一变化（密度、长度、不透明度）形成动感的重复元素；略微偏离中心的视觉焦点；充足的留白。避免：带标签的具象图表坐标轴、超过两个创意、密集的杂乱元素、大面积填充区域（它们在遮罩中看起来像灰色方块）。

内嵌图片

正文中的额外示意图使用普通 Markdown——任何 .svg 都会以相同的遮罩边框渲染：

![A stepped line with a straight line running through it](/changelog/2026-10-20-trend-line.svg)

每个条目最多使用一张内嵌图片，放在它所说明的章节下方。

检查清单

• 文件命名为 YYYY-MM-DD-<slug>.mdx；date 与之匹配（如果同一天需要排序，可添加时间）
• apps/web/content/docs 中存在所有提及的属性 / 组件；代码块最多一个
• 封面为原创（不是对参考插画的复刻）
• 封面 SVG 符合技术规范；在浅色和深色模式以及 OG 卡片（/api/og/changelog/<slug>）上都显示正常
• 描述不超过 100 个字符；标题使用句子式大小写
• 使用恢复属性并添加 breaking 标签，标明破坏性变更
• 以文档链接结尾
• pnpm --filter web check-types 检查通过（构建时会根据 schema 验证 frontmatter）