@fxri/toolkit 1.14.1 → 1.14.2

package/skills/fxri-release-changelog/SKILL.md

@@ -3,7 +3,7 @@ name: fxri-release-changelog
 description: 基于 changesets 的发版与多语言 CHANGELOG 维护流程：创建变更集、消费发版、把分组标题与条目转为项目语言风格、清理变更集、打标签发布；无 changesets 的项目提供同格式手工模式。用户表达发版或记录变更意图时使用——含创建变更集、changeset、发版、version、CHANGELOG 格式化等说法及口语近义表达（发一版、出个版本、记一下这次改动、生成更新日志）。⚠️ 注意区分：用户说「提交个版本 / 先提交一版 / commit」通常指 git 提交当前改动（走任务收尾后提交），**不是发版**。不用于日常 commit message 撰写、git 提交操作或与发版无关的文档修改。
 license: MIT
 metadata:
-  version: "1.2.3"
+  version: "1.2.4"
   tier: optional
   author: fxri
   source: https://github.com/fxri-net/toolkit
@@ -11,7 +11,7 @@ metadata:
 
 # 发版与 CHANGELOG
 
-> 本技能版本 1.2.3（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.2.4（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 
@@ -34,7 +34,7 @@ metadata:
 
 1. 记录变更：`npx changeset`（或项目包管理器等价脚本）——**变更描述一律逐条以 `- 类型：描述` 书写**：既要 `类型：` 前缀（如 `新增：` / `修复：` / `优化：`）作归类信号，也要 `- ` 列表标记把每条独立成项（缺标记的裸行会被 changesets 并入相邻条目作缩进续行，整段塌成单一条目、只有首行归组剥前缀）；并按改动的**能力量级**选影响级别（破坏性→major、全新大功能/独立新能力→minor、存量能力上的修补与增量→patch，完整对照见 `references/changelog-format.md`）。写完可跑 `toolkit tasks check` 早期自查：它扫 `.changeset/` 下待发布变更集，逐文件报出缺前缀条目与未加 `- ` 标记的裸行及条数（免得到发版、变更集源被消费删除后才由 changelog 侧兜底告警——那时已无从补写）
 2. 消费发版：`npx changeset version`——自动写版本号与 CHANGELOG
-3. 格式化：按 `references/changelog-format.md` 的语义分组规则归类条目、转换分组标题、润色为项目语言风格（中文示例：`### Patch Changes` 下的 `- 修复：xxx` → `### 🐛 问题修复` 下的 `- xxx`——归类后类型前缀被剥离，类型由分组标题承接）；分组维度与 bump 维度正交，条目归组只看类型前缀
+3. 格式化：按 `references/changelog-format.md` 的语义分组规则归类条目、转换分组标题、润色为项目语言风格（中文示例：`### Patch Changes` 下的 `- 修复：xxx` → `### 🐛 问题修复` 下的 `- xxx`——归类后类型前缀被剥离，类型由分组标题承接）；分组维度与 bump 维度正交，条目归组只看类型前缀；无 `###` 分组的版本块（如手工维护的更新记录）同样按前缀生成规范分组并剥离前缀，默认只处理最新一块
 4. 归一：润色后跑一次 `toolkit changelog --history format`——人工润色（含补写历史块明细）容易在条目之间留空行，该命令按「同组顶层条目逐行相邻」重排历史块；项目另有更新日志镜像页（如 `docs/changelog.md`）时再跑一次 `toolkit changelog doc`，否则镜像一致性校验会失败
 5. 清理：删除已消费的 `.changeset/*.md`
 6. 门禁：发布前跑一次项目的验收命令（如 `pnpm verify`）——**关卡设在发布前而非推送前**：发布到包仓库 / 制品库不可逆，推送失败重推即可，故必须拦在不可逆动作之前；任一步失败即中止发版，不进入提交、打标签、发布

package/skills/fxri-release-changelog/references/changelog-format.md

@@ -24,7 +24,7 @@
 - ⚠️ **务必逐条写成 `- 类型：描述`**：变更集正文里列 0 起首、无 `- ` 标记的裸行会被 changesets 并入相邻条目作缩进续行——整段正文塌成**单一条目**，只有首行参与前缀识别与归类，其余行既不归组也不剥前缀，最终全挤在首行所属的单组里（本仓 v1.12.0 块的成因）；自查入口见 §2「缺前缀与裸行的检测入口」
 - 同一分组内顶层条目**逐行相邻输出**（条目之间不留空行，缩进子项紧随父条目），分组之间与日期行前后各留一个空行——这是格式化的**不动点**：合规文件重复执行 `toolkit changelog format` 应零改动，`--history` 归一之后同理
 - ⚠️ 变更集条目以 `- ` 开头时，changesets 会写入 `- - 条目` 首行并把后续行缩进 2 空格（伪影）；`toolkit changelog version/format` 会自动还原为顶层条目，手工模式需手动清理
-- 分组标题集合随版本演进而变化；**历史版本块保留当时口径，`toolkit changelog format` 不追溯改写**（只归类 changesets 本次新写入的英文源标题块）
+- 分组标题集合随版本演进而变化；**历史版本块保留当时口径，`toolkit changelog format` 不追溯改写**——默认只处理 changesets 本次新写入的英文源标题块与无 `###` 分组的最新版本块，其余历史块原样保留（`--history` 才追溯全部版本块）
 - ⚠️ **人工事实更正**：已发布版本块原则上不追溯改写；确需更正**事实性错误**（归组误判、错别字等）时允许人工修改——仓库 `CHANGELOG.md` 为真源，已发布的包产物与版本标签是**不可变快照**、不回补，正确版随下次发版由整份 CHANGELOG 带入
 
 ## 2. 语义分组归类
@@ -45,19 +45,19 @@
 | `依赖：` / 源文本 `- Updated dependencies` | `deps` | `### 🔗 依赖变更` | `### 🔗 Dependency Updates` |
 | 无前缀兜底 | `other` | `### 📦 其他变更` | `### 📦 Other` |
 
-**无前缀条目的兜底规则**：按条目**所属源组标题**声明的影响级别归组——`### Major Changes` → `breaking`、`### Minor Changes` → `added`、`### Patch Changes` → `other`；不从版本号推导。
+**无前缀条目的兜底规则**：按条目**所属源组标题**声明的影响级别归组——`### Major Changes` → `breaking`、`### Minor Changes` → `added`、`### Patch Changes` → `other`；不从版本号推导。无 `###` 分组的块没有源组可依，无前缀条目归入 `other`。
 
 **缺前缀与裸行的检测入口**：`toolkit tasks check` 扫 `.changeset/` 下待发布变更集（`.md` 且非 `README.md`），逐文件报出两类软告警——**缺类型前缀**的顶层条目数与首条行号、以及**未加 `- ` 列表标记**的裸行数与首条行号（后者取列 0 起首、以已识别前缀开头且连续 2 行起的行，阈值 2 避开正常正文误报）；归档前的早期自查，发版时 changelog 侧另有兜底告警。前缀识别取全局表与各配置语言 `prefixes` 的并集（自定义语言不误报），依赖源条目归 `deps` 不计缺前缀，缩进续行随父条目迁属、不参与识别。
 
-**追溯历史块的兜底规则**（`--history`）：历史块没有英文源组标题，改按**所属既有组标题**查槽位——先查当前语言组标题，再查历史组标题表（如 `### 🐛 补丁修复` → `fixed`）；两处都识别不出则整组连同标题保留、不臆造归属。
+**追溯历史块的兜底规则**（`--history`）：历史块按条目前缀归位，无前缀条目再按**所属既有组标题**查槽位——先查当前语言组标题，再查历史组标题表（如 `### 🐛 补丁修复` → `fixed`）；无 `###` 分组的块按前缀生成规范分组、无前缀条目归 `other`；两处都识别不出则整组连同标题保留、不臆造归属。
 
 **依赖条目不走前缀解析**：源组标题 `### Dependent Changes` 整块，以及源文本 `- Updated dependencies`（含缩进子项）一律归入 `deps` 槽位。
 
-**归类后剥离类型前缀**：条目归入槽位后，其已被识别的 `类型：` 前缀被剥离（`- 修复：xxx` → `- xxx`）——前缀只是归类信号，类型已由分组标题承接，留在明细里属冗余。未识别的前缀（如正文里的 `说明：`）与依赖源条目原样保留，剥离后文本为空也不改动。默认模式与 `--history` 追溯模式同此规则。
+**归类后剥离类型前缀**：条目归入槽位后，其已被识别的 `类型：` 前缀被剥离（`- 修复：xxx` → `- xxx`）——前缀只是归类信号，类型已由分组标题承接，留在明细里属冗余。未识别的前缀（如正文里的 `说明：`）与依赖源条目原样保留，剥离后文本为空也不改动。默认模式与 `--history` 追溯模式同此规则；语言未声明 `groups` 时不改分组结构，只剥离可识别前缀。
 
 同一槽位来自多个源块时合并为单组，组内保持条目原出现顺序；缩进续行随父条目整体迁移。
 
-**归类只搬移、不删内容**：归类只重组「纯条目分组」——分组标题下若在首个条目之前出现非空正文，判据不成立，整块保持原样以免丢内容；未参与归位的分组连同标题按原相对顺序附于块末，不臆造归属、不静默丢弃。CLI 在归类前后做条目数自检，减少即告警（正常合并发生在自检之后、不误报）。
+**归类只搬移、不删内容**：归类只重组「纯条目块」——分组标题下若在首个条目之前出现非空正文，判据不成立，整块保持原样以免丢内容；无 `###` 分组的块在首个条目之前出现说明性正文时同样整块不动；未参与归位的分组连同标题按原相对顺序附于块末，不臆造归属、不静默丢弃。CLI 在归类前后做条目数自检，减少即告警（正常合并发生在自检之后、不误报）。
 
 **能力量级 → bump**（撰写变更集时按此选影响级别）——版本号由变更集 frontmatter 的 bump 声明决定，**与条目前缀正交**：前缀只负责把条目归入哪一组，不决定版本号。
 
@@ -77,7 +77,7 @@
 
 每种语言约定四段结构：
 
-- `groups`（可选）：语义分组表，每项 `{ slot, title, prefixes? }`——`slot` 取自全局语义槽位，`title` 为本语言组标题，`prefixes` 为本语言自有前缀（可选，识别时与全局前缀表取并集）；缺省时退化为纯替换（仅 `replacements` 生效）
+- `groups`（可选）：语义分组表，每项 `{ slot, title, prefixes? }`——`slot` 取自全局语义槽位，`title` 为本语言组标题，`prefixes` 为本语言自有前缀（可选，识别时与全局前缀表取并集）；缺省时不改分组结构，只剥离可识别前缀并应用 `replacements`
 - `replacements`：兜底替换映射表（源标题 → 目标标题）
 - `deps`：依赖更新条目固定文案
 - `released`：发布日期行后缀（中文为「发布」，英文为「released」；同时用于识别既有日期行，故自定义语言填非「发布/released」值也能幂等）