SuperAPI AI 工具集

bklit-changelog

写作与研究

查看项目

更新于 10-24 02:37

技能介绍

用途

bklit-changelog 是 bklit-ui 单体仓库贡献者专用的技能,用于为 bklitui.com/changelog 撰写发布说明:一篇 Markdown 文章,加一张或多张抽象、单色 SVG 封面。目标风格是简短、自信的产品短文,而非提交日志。

文件位置

条目(每条一个 .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。Frontmatter 模式定义在 apps/web/source.config.ts 的 changelog 部分;加载、排序与搜索文本在 apps/web/lib/changelog.ts;Feed、列表、文章、图片组件在 apps/web/components/changelog/;路由覆盖 /changelog、分页、单条、rss.xml;SEO 在 apps/web/lib/changelog-seo.ts;Open Graph 卡片在 apps/web/lib/changelog-og.tsx → /api/og/changelog/<slug>。

路由 slug 即去掉 .mdx 的文件名。每条自动获得独立永久链接、站点地图条目、RSS 项、BlogPosting JSON-LD 和深色 OG 卡片,无需额外注册。Feed 每页 20 条,带较新/较旧链接。

使用流程

  1. 收集事实:用 git log --since=<date> --oneline 列出合并内容并阅读 PR 正文;大功能单独成条,其余汇总为“修复与改进”;用 git log --grep="(#NNN)"、gh pr view NNN 阅读 PR,并核对 apps/web/content/docs 中提及的每个 API 属性,不得臆造。
  2. 选择 slug 与日期:YYYY-MM-DD-short-kebab-name,日期用合并当天;同日多条可加 UTC 时间(如 2026-10-22T18:00:00Z),较晚时间排前。
  3. 制作封面。
  4. 撰写文章。
  5. 在 pnpm dev 下检查 /changelog 与 /changelog/<slug>,明暗主题和手机宽度均需检查,并用正文中的词确认已被索引。

Frontmatter

字段包括 title(功能名、句式大小写、无句号、≤6 词)、description(一句话、≤100 字符,用于 SEO 与搜索)、date、image、imageAlt(描述图形而非功能)、tags(小写 kebab,可含图表 slug 和 breaking)。

写作规范

结构:1–3 句导语说明新增内容与意义,不用“我们很高兴”开头;每个想法一个 ## 小节,1–3 段短段落,标题为名词或短语;结尾链接到文档页。代码方面以文字优先,属性内联提及,每条最多一个代码块且仅在代码本身是新闻时使用。风格:第二人称、现在时;具体优于形容词,点名属性、默认值和数字;破坏性变更单独成 ## 小节并给出恢复旧行为的属性与 breaking 标签;先讲问题再讲功能;150–350 词(修复汇总可为更长列表);只用 ## 和 ###;内部链接用根相对路径。

封面图

封面是暗示功能(数据形状或运动)的抽象几何图,不出现截图、Logo、UI 或文字,风格参考 Linear 博客(细线、留白、一图一想法),但不得复刻具体插画。技术要求:viewBox="0 0 1600 900"、透明背景、仅用黑色 #000,以 stroke-opacity / fill-opacity 表现层次;保留约 160px 安全边距并居中;描边 2–3px、stroke-linecap="round"、虚线 stroke-dasharray="6 10";不含 <text>、位图、滤镜或外部引用,目标 < 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]

输出对 motif + seed 确定性,可调 seed 至构图平衡。提供的 motif 包括 bar-steps、scatter-jitter、band、step-trend、gauge、dot-grid、radial-bars、hue-discs、halo、swatches、rails、migrate、waves,分别对应柱状、散点、区间、趋势、进度、密度、基准、调色、悬停、纹理、结构、迁移、修复等场景。

无合适 motif 时可手写 SVG,或向 cover.mjs 添加新 motif。正文内联图最多一张,使用普通 Markdown,同样套用遮罩框。

检查清单

文件名与日期匹配;提及的每个属性/组件都存在于文档中且代码块不超过一个;封面为原创并符合技术规则,在明暗主题和 OG 卡片下显示正常;description ≤100 字符、标题句式大小写;破坏性变更标注恢复属性与标签;以文档链接结尾;pnpm --filter web check-types 通过。

限制

该技能仅面向 bklit-ui 单体仓库的贡献者,依赖仓库内路径、脚本与工具链;不适用于仓库外的独立项目。