release-notes

Release Notes Skill

在 src/ts/docs/help/whatsNew.ts 中编写和更新发布说明。此技能可以根据对话上下文、Git 分支变更或 Linear 问题生成发布说明内容。

文档结构

文件 src/ts/docs/help/whatsNew.ts 导出一个函数，该函数返回一个由区块元素组成的数组。每个版本都是一个“页面”，结构如下：

// Helper definitions at top of file (lines 1-24)
const hl = (t: string) => `<span class="highlight">${t}</span>`;
const text = (t: string) => block(I.TextStyle.Paragraph, t);
const h1 = (t: string) => block(I.TextStyle.Header1, t);
const h2 = (t: string) => block(I.TextStyle.Header2, t);
const bullet = (t: string) => block(I.TextStyle.Bulleted, t);
const img = (src: string) => text(`<img src="..." />`);
const link = (url: string, t: string) => `<a href="${url}">${t}</a>`;
const div = () => ({ type: I.BlockType.Div, style: I.DivStyle.Dot });

// Release pages start after helpers (~line 25)
return [
    { type: I.BlockType.IconPage, icon: '...' },

    title(`Catchy Release Title`),           // PAGE START
    h4(`<span>Release 0.XX.0</span>`),
    text(''),
    text('Intro paragraph...'),
    text(''),

    // Big Feature Sections (h2)
    h2(`Feature Name`),
    text(`Feature description...`),
    img(`XX/1.png`),
    text(``),

    // Quality of Life Improvements
    h2(`Quality of Life Improvements`),
    text(``),
    text(`<b>Improvement Name</b>`),
    text(`Description...`),
    text(``),

    // Bug Fixes
    h2(`Bug Fixes`),
    text(``),
    text(`<b>Category Name</b>`),
    bullet(`Fix description. Thanks to @${link('url', 'user')}!`),
    text(``),

    div(),                                   // PAGE END
    // --------------------------------------------//

    // Next release page...
];

多部分发布

一次发布可能拆分到多个 Linear 根问题（部分）中，例如：

• JS-8571 “Release 18 | 0.54.0 | Desktop | Part 1” — 包含 Features、Design、Tech
• JS-8672 “Release 18 | 0.54.0 | Desktop | Part 2” — 包含 Bugs、Quality

接受问题 ID 的命令（all、from-parent、docx）支持多个 ID。提供多个根问题时，分别获取每个问题，并按类型（功能、生活质量改进、错误）合并其子问题。每个部分中的项目保留各自在 Linear 中的相对顺序；第 1 部分的项目排在第 2 部分之前。

排除规则

处理来自 Linear 的问题（通过 from-parent、all、docx）时，跳过符合以下任一条件的问题：

1. 仅分析类 — 标签仅包含 📈 analytics（没有 bug/quality/feature 标签）

2. 内部项 — 标签仅包含 🖌️ design 或 ⚙️ tech（没有面向用户的标签）

3. 提及 Alpha 版本 — 问题的标题或描述包含带有 -alpha 后缀的版本字符串（例如 0.53.28-alpha、0.50.29-alpha）。这些问题是在预发布版本中报告的，并且在公开发布之前就已修复；将它们纳入说明会让从未遇到该错误的用户感到困惑。

   检测方式：在 title 或 description 字段中匹配正则表达式 \d+\.\d+\.\d+-alpha。

命令

解析用户的命令以确定操作：

/release-notes feature "Title" [context]

向当前版本添加一个大型功能（h2 区块）。

插入位置： h2(\Quality of Life Improvements`)` 之前

格式：

h2(`Feature Title`),
text(`Description paragraph 1.`),
text(`Description paragraph 2 if needed.`),
text(``),

/release-notes qol "Title" [context]

添加一项生活质量改进。

插入位置： h2(\Quality of Life Improvements`) 之后、h2(`Bug Fixes`)` 之前

格式：

text(`<b>Improvement Title</b>`),
text(`Description. Can mention shortcuts like ${hl('Cmd+V')}.`),
text(``),

排序： 添加多项生活质量改进时，按影响从大到小排序：

1. 主要新能力 — 几乎可以独立成为功能的项目（例如 Toggle Headings、Pinned Tabs、Spell Checking in Chat）
2. 新设置和偏好选项 — 会改变工作流的面向用户选项（例如 File Block Default Style、Click to Edit Title 开关）
3. 有意义的工作流改进 — 能显著改善体验的项目（例如 Collections 中的全文搜索、Chat 中的 Jump to Message）
4. 细小但受欢迎的优化 — 轻微的 UX 改进（例如全屏预览点击关闭、可在标题栏中打开的 URL 属性）
5. 类似生活质量改进的微小修复 — 细微的体验提升（例如清空输入框、选项排序、剪贴板边界情况）

社区贡献者署名的项目可根据其影响归入任意级别——不要将它们单独分组。

/release-notes fix "Category" [context]

在指定类别下添加错误修复。

插入位置： 在 h2(\Bug Fixes`)` 下，查找或创建相应类别

格式：

text(`<b>Category Name</b>`),  // Only if category doesn't exist
bullet(`Fix description. Thanks to @${link('https://community.anytype.io/t/XXXXX', 'username')}!`),

现有类别：

• Chat & Messaging
• Editor & Blocks
• UI & Rendering
• Objects & Views
• Queries & Views
• Widget Sidebar
• Navigation & Window Management
• Keyboard & Shortcuts
• Modal Window Mode
• Miscellaneous

/release-notes from-parent JS-XXXX

根据 Linear 父问题及其子问题批量创建条目。

1. 从 Linear API 获取父问题及其所有子问题
2. 根据标签确定每个子问题的类型：
   • bug 标签 → fix
   • feature 标签 → feature
   • improvement 标签 → qol
3. 为每个问题创建相应条目
4. 如果父问题属于大型功能，则使用其标题作为 h2 区块

/release-notes new "0.XX.0" "Title"

在文件顶部创建一个新的发布页面。

插入位置： IconPage 区块之后、第一个 title() 调用之前

格式：

title(`Catchy Title`),
h4(`<span>Release 0.XX.0</span>`),
text(''),
text('Intro paragraph describing the release highlights.'),
text(''),

h2(`Quality of Life Improvements`),
text(``),

h2(`Bug Fixes`),
text(``),

div(),
// --------------------------------------------//

/release-notes all JS-XXXX [JS-YYYY ...]

根据一个或多个根 Linear 问题（通常是冲刺／里程碑问题）生成完整的发行说明页面。当一次发布拆分为多个部分时，传入所有根问题 ID——它们的子问题会按类型合并。

工作原理：

1. 从 Linear API 获取根问题及其所有直接子问题：

curl -s -X POST "https://api.linear.app/graphql" \
  --header "Content-Type: application/json" \
  --header "Authorization: $(printenv LINEAR_API_KEY)" \
  --data '{"query":"query{issue(id:\"JS-XXXX\"){title description labels{nodes{name}}children(first:250){nodes{identifier title description state{name}labels{nodes{name}}children(first:250){nodes{identifier title description state{name}labels{nodes{name}}}}}}}}"}' | jq .

2. 根据子问题的标签进行分类：

子问题标签	分类	操作
📁 folder + 🐛 bug	Bug 文件夹	按 from-parent 处理：获取孙级问题，将其归类到 bug 修复类别，并撰写项目符号条目
📁 folder + 👌 quality	QoL 文件夹	按 from-parent 处理：获取孙级问题并撰写 QoL 条目。带有 💫 feature 标签的项目改为 h2 功能
💫 feature（无文件夹）	独立功能	撰写 h2 功能章节
仅 📈 analytics	分析（内部）	完全跳过——不面向用户

3. 创建发行说明页面结构（如果尚不存在）：

   • 使用 new 页面，包含版本和标题
   • 所有 h2 功能章节
   • 在 h2('Quality of Life Improvements') 下列出所有 QoL 条目
   • 在 h2('Bug Fixes') 下按类别整理所有 bug 修复
   • 通过 intro 添加介绍段落

4. 对于孙级问题（文件夹问题的子问题），应用相同的基于标签的规则：

   • 🐛 bug → bug 修复项目符号
   • 👌 quality → QoL 条目
   • 💫 feature → 根据范围归为 h2 功能或 QoL
   • 仅 📈 analytics → 跳过
   • 无相关标签 → 根据父文件夹类型推断
   • 👨‍💻 feedback → 社区反馈，提取描述中的用户名和链接

5. 操作顺序：

   1. 创建新的发行说明页面（如有需要）
   2. 插入功能（h2 章节）
   3. 插入 QoL 改进
   4. 按类别插入 bug 修复
   5. 撰写介绍段落

社区致谢： 当子问题带有 👨‍💻 feedback 标签时，在描述中查找社区链接（https://community.anytype.io/t/XXXXX）并提取反馈者的姓名。在对应条目中添加 Thanks to @${link('url', 'name')}!。

示例：

User: /release-notes all JS-8500

Root issue "Sprint 18" has children:
  JS-8574 "Bugs | 18"         [📁 folder, 🐛 bug]     → process 81 bug sub-issues
  JS-8573 "Quality | 18"      [📁 folder, 👌 quality]  → process 25 QoL sub-issues
  JS-292  "[epic] Tabs"        [💫 feature]             → h2 feature
  JS-4551 "[epic] Filters"    [💫 feature]             → h2 feature
  JS-8725 "Chat Search"       [💫 feature]             → h2 feature
  JS-8703 "Transfer Ownership" [💫 feature]            → h2 feature

Result: Complete release page with features, QoL, bug fixes, and intro.

/release-notes docx JS-XXXX [JS-YYYY ...]

将当前版本说明导出为 .docx 文件，并添加指向 Linear 问题的超链接。条目遵循 Linear 的排序方式（即子项在其父问题下的显示顺序），而非 whatsNew.ts 中按类别分组的方式。

接受一个或多个根问题 ID。如果某个版本拆分为多个 Linear 问题（“部分”），请传入所有问题——它们的子项会按类型（功能、易用性改进、Bug）合并，并且每个部分中的条目在合并后的区段中保留其相对顺序。

工作原理：

1. 从 Linear 获取每个根问题及其完整子项树（使用 first:250）：

curl -s -X POST "https://api.linear.app/graphql" \
  --header "Content-Type: application/json" \
  --header "Authorization: $(printenv LINEAR_API_KEY)" \
  --data '{"query":"query{issue(id:\"JS-XXXX\"){title description labels{nodes{name}}children(first:250){nodes{identifier title description state{name}labels{nodes{name}}children(first:250){nodes{identifier title description state{name}labels{nodes{name}}}}}}}}"}' | jq .

2. 按以下规则收集并分类所有根问题的子项：

子项标签	分类	操作
💫 feature（带或不带 📁 folder）	功能	如果是文件夹：将孙项作为单独功能。如果是独立条目：作为单个功能条目
📁 folder + 👌 quality	易用性改进文件夹	孙项 → 易用性改进条目。带有 💫 feature 标签的条目改为归类为功能
🐛 bug（带或不带 📁 folder）	Bug 文件夹	孙项 → Bug 修复
仅 📈 analytics	分析	跳过
仅 🖌️ design / ⚙️ tech	内部	跳过——不面向用户

合并多个部分时，在各区段中将第 2 部分的条目追加到第 1 部分条目之后（保留每个部分内部的排序）。

3. 从 whatsNew.ts 中读取当前版本页面，获取每个条目的用户可见说明文本。

4. 将每个 Linear 问题与其 whatsNew.ts 条目匹配。匹配策略：

   • 对于功能：按 h2 标题关键词匹配（例如，JS-292“Tabs” → h2(\Tabs`)`）
   • 对于易用性改进条目：按粗体标题关键词匹配（例如，“Toggle Headings” → text(\Toggle Headings`)`），并收集其后面的描述段落
   • 对于Bug 修复：按社区链接 URL（community.anytype.io/t/XXXXX）、问题标题中的关键词，或同一类别中的位置匹配
   • 如果未找到匹配项，则使用 Linear 问题标题作为备用文本，格式为 **Title** – <Linear title>.

5. 构建具有以下结构的 JSON 数据文件，并保留各区段中 Linear 子项的排序：

{
    "version": "0.54.0",
    "title": "Focus & Flow",
    "sections": [
        {
            "heading": "Features",
            "items": [
                {"id": "JS-292", "text": "Note text from whatsNew.ts (cleaned of HTML)."},
                {"id": "JS-4551", "text": "..."}
            ]
        },
        {
            "heading": "Quality of Life Improvements",
            "items": [
                {"id": "JS-XXXX", "text": "**Toggle Headings** – H1, H2, H3 can now be collapsible toggles..."}
            ]
        },
        {
            "heading": "Bug Fixes",
            "items": [
                {"id": "JS-8845", "text": "Action icons now look consistent across light and dark modes."}
            ]
        }
    ]
}

6. 从 whatsNew.ts 提取文本时的清理规则：

   • 去除 HTML 标签：<span class="highlight">X</span> → X，<b>X</b> → **X**，<i>X</i> → X
   • 去除 <a href="...">text</a> → text
   • 解析模板表达式：${hl('Cmd+F')} → Cmd+F，${link('url', 'name')} → name
   • 对于易用性改进条目，将粗体标题和描述段落合并为一个文本字符串：**Title** – Description text.
   • 对于功能，将所有文本段落合并为一个字符串

7. 将 JSON 写入临时文件，然后运行生成器脚本：

python3 .claude/skills/release-notes/generate_docx.py /tmp/release_data.json <output_path>

输出位置： 将 .docx 保存到项目根目录，文件名为 release-<version>.docx（例如，release-0.54.0.docx）。

条目排序： 每个区段中的条目必须与它们在 Linear 中父问题下的顺序相同。此顺序由 Linear API 的 children 字段返回。不要按类别、字母顺序或任何其他标准重新排序。合并多个部分时，第 1 部分的条目排在最前，其次是第 2 部分，依此类推。

示例（多部分）：

User: /release-notes docx JS-8571 JS-8672

1. Fetch JS-8571 (Part 1) children:
   - JS-8575 [💫 + 📁] → Features folder → 4 feature grandchildren
   - JS-8630 [🖌️ + 📁] → Design folder → skip (internal)
   - JS-8594 [⚙️ + 📁] → Tech folder → skip (internal)

2. Fetch JS-8672 (Part 2) children:
   - JS-8573 [👌 + 📁] → QoL folder → 33 grandchildren → QoL items
   - JS-8574 [🐛]       → Bug folder → 82 grandchildren → Bug Fixes

3. Merge: Features from Part 1, QoL from Part 2, Bugs from Part 2
4. Read whatsNew.ts, match each issue to its note text
5. Write JSON with items in Linear order
6. Run generate_docx.py → release-0.54.0.docx
7. Report: "Generated release-0.54.0.docx with 4 features, 33 QoL items, 82 bug fixes."

/release-notes intro

为当前版本撰写或更新引言段落。

工作原理：

1. 阅读 whatsNew.ts 中当前版本的页面
2. 找出所有 h2 功能区段
3. 撰写 2–3 句话，突出主要功能的核心价值
4. 替换 h4(...) 与第一个 h2(...) 之间的空引言 text('') 行

插入位置： h4(<span>Release ...</span>) 与第一个内容区段之间的 text('') 行

格式：

text('Intro sentence one. Intro sentence two.'),
text('Intro sentence three if needed.'),

风格：

• 使用 2–3 句话，简洁而有热情，但不过分夸张
• 按名称提及最重要的功能
• 重点说明用户现在可以做什么，而非实现细节
• 与文件中之前版本引言的语气保持一致

/release-notes show

显示当前发行说明（文件中的第一页）。

上下文解析

当用户提供上下文提示而非明确文本时：

today 或 session

1. 分析当前对话历史
2. 确定讨论或实现了哪些功能／变更
3. 提炼对用户的主要益处
4. 按发行说明的风格撰写描述

branch

1. 运行 git log main..HEAD --oneline 查看提交
2. 运行 git diff main --stat 查看变更的文件
3. 分析分支名称以了解上下文（例如：feature/JS-8826-advanced-filters）
4. 根据变更生成描述

JS-XXXX（Linear 工单）

1. 使用以下内容从 Linear API 获取工单：

curl -s -X POST "https://api.linear.app/graphql" \
  --header "Content-Type: application/json" \
  --header "Authorization: $(printenv LINEAR_API_KEY)" \
  --data '{"query":"query{issue(id:\"JS-XXXX\"){title description state{name}priority labels{nodes{name}}}}"}' | jq .

2. 提取标题和描述
3. 如果未指定类别，则根据标签确定类别
4. 按发行说明的格式编写

明确文本

直接使用提供的文本，但确保符合风格指南。

写作风格指南

语气

• 简洁但信息充分
• 说明变更了什么，以及这对用户有什么帮助
• 使用主动语态：“你现在可以……”而不是“现在可以……”
• 关注用户收益，而非实现细节

功能标题

使用以行动为导向、含义明确的名称：

• “直接频道”
• “高级筛选”
• “查询中的手动排序”
• “更新后的导航”

描述

• 以用户收益或已解决的问题开头
• 使用 ${hl('Cmd+V')} 语法提及键盘快捷键
• 每段聚焦于一个要点
• 在文本中使用 <b>粗体</b> 强调内容

社区致谢

修复用户报告的问题时：

bullet(`Fix description. Thanks to @${link('https://community.anytype.io/t/12345', 'username')}!`)

标点

• 括号补充说明和范围使用短横线（–），而非长横线（—）

避免事项

• 技术术语（API、重构、组件名称）
• 实现细节（文件名、函数名）
• 被动语态
• 含糊的描述（“提升了性能”）

工作流

1. 解析命令 - 确定操作类型和参数
2. 解析上下文 - 根据对话、分支、Linear 或明确文本生成内容
3. 读取 whatsNew.ts - 找到当前发行版本和插入位置
4. 格式化条目 - 使用正确的 TypeScript 语法和风格
5. 插入条目 - 在正确的位置编辑文件
6. 确认 - 向用户展示添加的内容

示例

根据会话上下文添加功能

User: /release-notes feature "Advanced Filters" today

Action:
1. Review conversation - user worked on advanced filters with AND/OR logic
2. Find insertion point before h2(`Quality of Life Improvements`)
3. Insert:
   h2(`Advanced Filters`),
   text(`Need more control over what shows in your Views? You can now create Advanced Filters that combine multiple conditions using AND or OR logic. Group related rules together to build precise queries – like finding all tasks that are either high priority or due this week.`),
   text(``),

添加易用性改进

User: /release-notes qol "Filter Bar Redesign" branch

Action:
1. Analyze git changes on current branch
2. Find insertion point after h2(`Quality of Life Improvements`)
3. Insert:
   text(`<b>Filter Bar Redesign</b>`),
   text(`Filters and Sorts in Queries and Collections got a fresh look. Active filters now appear in a dedicated bar above your View, showing the property name, condition, and value at a glance.`),
   text(``),

添加错误修复

User: /release-notes fix "Objects & Views" "Filter items now show correct active state"

Action:
1. Find h2(`Bug Fixes`)
2. Find text(`<b>Objects & Views</b>`) category (or create if missing)
3. Insert bullet after category header:
   bullet(`Filter items now show correct active state.`),

撰写发行说明导语

User: /release-notes intro

Action:
1. Read whatsNew.ts — find h2 feature sections: "Tabs", "Advanced Filters", "Chat Search", "Transfer Channel Ownership"
2. Write 2–3 sentences covering the highlights
3. Replace empty text('') lines after h4(`<span>Release 0.54.0</span>`):
   text('This release brings Tabs to Anytype — open multiple Objects side by side and pin the ones you use most. Advanced Filters let you combine conditions with AND/OR logic, Chat Search helps you find any message instantly, and Channel Owners can now transfer ownership to another member.'),

根据根工单生成完整发行说明

User: /release-notes all JS-8500

Action:
1. Fetch root issue JS-8500 — "Sprint 18" with 6 children
2. Classify children:
   - JS-8574 [📁 + 🐛] → bug folder, fetch 81 grandchildren → bug fixes
   - JS-8573 [📁 + 👌] → QoL folder, fetch 28 grandchildren → QoL entries + features
   - JS-292  [💫]       → standalone feature "Tabs"
   - JS-4551 [💫]       → standalone feature "Advanced Filters"
   - JS-8725 [💫]       → standalone feature "Chat Search"
   - JS-8703 [💫]       → standalone feature "Transfer Ownership"
3. Create new release page with `new "0.54.0" "Focus & Flow"`
4. Insert 4 feature h2 sections
5. Insert 25 QoL entries
6. Insert 80 bug fixes across categories
7. Write intro paragraph