@fxri/toolkit 1.14.0 → 1.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fxri/toolkit",
-  "version": "1.14.0",
+  "version": "1.14.2",
   "description": "专为多人 + AI 跨项目协作打造：任务管理 + 多语言 CHANGELOG。",
   "license": "MIT",
   "author": {
@@ -86,7 +86,7 @@
     "test:repo-guard": "vitest run src/__tests__/warn-threshold.test.ts",
     "verify": "node scripts/verify.mjs",
     "changeset": "changeset",
-    "sync:changelog-doc": "node scripts/sync-changelog-doc.mjs",
+    "sync:changelog-doc": "node dist/cli.js changelog doc",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",

package/skills/README.md

@@ -9,11 +9,11 @@
 | 技能 | 版本 | 用途 | 层级 |
 | --- | --- | --- | --- |
 | [fxri-plan-to-task](./fxri-plan-to-task/SKILL.md) | 1.9.5 | 方案落盘：任务分解与纯展示计划表 → 逐仓逐任务建档 → 校验 → 归档 → 任务级规范沉淀（能力终点）；规范载体迁移与升级 | core |
-| [fxri-release-changelog](./fxri-release-changelog/SKILL.md) | 1.2.2 | changesets 发版与多语言 CHANGELOG 维护 | optional |
+| [fxri-release-changelog](./fxri-release-changelog/SKILL.md) | 1.2.4 | changesets 发版与多语言 CHANGELOG 维护 | optional |
 | [fxri-session-recap](./fxri-session-recap/SKILL.md) | 1.6.3 | 会话收尾全量沉淀 + 规范沉淀 / 新会话三层恢复 / 历史任务时间批量修正 | core |
 | [fxri-text-encoding](./fxri-text-encoding/SKILL.md) | 1.2.1 | 文本编码：写脚本 / 配置 / 数据交换文本与跨进程 / 跨机器传递前按「生产者 × 消费者」定字节形态（临时任务同样适用），含非 ASCII 丢失 / 变形、乱码反查与首行报错 | optional |
 
-版本号取自各 SKILL.md 的 frontmatter `metadata.version`（`toolkit skills status` / `skills install` 打印的真源版本），与正文首部版本声明双写一致；层级取自 frontmatter `metadata.tier`（`core` 必装不可取消，`optional` 安装时可选，缺省按 `optional` 处理）。
+版本号取自各 SKILL.md 的 frontmatter `metadata.version`（`toolkit skills status` / `skills install` 打印的真源版本），与正文首部版本声明双写一致；层级取自 frontmatter `metadata.tier`（`skills` 模式 `core` 必装不可取消，`package` 模式全部可选、允许零选；`optional` 安装时可选，缺省按 `optional` 处理）。
 
 ## 安装
 
@@ -24,11 +24,11 @@
 ```bash
 pnpm add -g @fxri/toolkit   # 1. 装 CLI（npm 用户 npm i -g @fxri/toolkit）
 toolkit skills install      # 2. 把包内技能装到各 agent 的全局技能目录
-                            #    先按 tier 选技能：core 必装、optional 可选（TTY 下方向键多选）
+                            #    先按 tier 选技能：core 必装、optional 可选（TTY 下方向键多选；--mode package 时 core 也可取消）
                             #    再选目标：canonical + 已检测 agent（--agent / --all-agents / --no-save-agents）
                             #    --skills <names> / --all / --no-optional / --yes 可跳过技能与目标交互
                             #    --scope project 换项目面：真源落 <仓库根>/.agents/skills/、其余候选目录落入口薄壳
-                            #    --from <path> 临时外部来源（副本）；--save [name] 登记永久来源（默认软链）
+                            #    --from <path|url> 临时外部来源（副本）；--save [name] 登记永久来源（默认软链）
 toolkit skills status       # 查现场状态（悬空 / 指向其他版本 / 副本漂移 / 缺失 / 同名冲突 / 未选择但已安装；历史落点残留单列提示；--scope project 查项目面）
                             # 前五类重跑 toolkit skills install 补齐，同名冲突需 toolkit skills install --force 覆盖，未选择产物加 --prune 清理
 toolkit skills remove       # 卸载本包装的产物（只清自己装的，不碰用户自装技能；--skills 只清指定技能；--scope project 清项目面）

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.2"
+  version: "1.2.4"
   tier: optional
   author: fxri
   source: https://github.com/fxri-net/toolkit
@@ -11,7 +11,7 @@ metadata:
 
 # 发版与 CHANGELOG
 
-> 本技能版本 1.2.2（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.2.4（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 
@@ -34,8 +34,8 @@ 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 维度正交，条目归组只看类型前缀
-4. 归一：润色后跑一次 `toolkit changelog --history format`——人工润色（含补写历史块明细）容易在条目之间留空行，该命令按「同组顶层条目逐行相邻」重排历史块；项目另有更新日志镜像页（如 `docs/changelog.md`）时再跑一次同步脚本，否则镜像一致性校验会失败
+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`）——**关卡设在发布前而非推送前**：发布到包仓库 / 制品库不可逆，推送失败重推即可，故必须拦在不可逆动作之前；任一步失败即中止发版，不进入提交、打标签、发布
 7. 发布：提交版本与 CHANGELOG 改动 → 打 `vX.Y.Z` 标签 → 按项目渠道发布（如 `npm publish`）
@@ -55,9 +55,9 @@ metadata:
 | 条目与仓库既有风格不一致 | 人工润色为项目语言与句式，勿保留机器直译 |
 | 变更集遗漏（发版后才发现功能未记录） | 补建变更集随下次发版；本次在发布说明中人工补充 |
 | `toolkit tasks check` 报「变更集条目缺类型前缀」 | 打开所列文件，给缺前缀的**顶层条目**按「类型：描述」补前缀（缩进续行随父条目迁属、无需加）；补前缀只改分类信号，不改变 bump 级别 |
-| `toolkit tasks check` 报「变更集条目未加「- 」列表标记」 | 打开所列文件，把裸行逐条改为 `- 类型：描述`（成因见 changesets 流程第 1 步）；若已发版才发现，说明该版本块条目可能已挤在单组且前缀未剥离，按 references 的「人工事实更正」修 `CHANGELOG.md` 并重跑镜像页同步 |
+| `toolkit tasks check` 报「变更集条目未加「- 」列表标记」 | 打开所列文件，把裸行逐条改为 `- 类型：描述`（成因见 changesets 流程第 1 步）；若已发版才发现，说明该版本块条目可能已挤在单组且前缀未剥离，按 references 的「人工事实更正」修 `CHANGELOG.md` 并重跑 `toolkit changelog doc` |
 | 改动已发布却无归档记录（有提交、无任务档） | 先补归档（fxri-session-recap 模式一）再继续发布后续步骤；发版本身不补建档 |
-| 发版后历史块内出现多余空行（`自举一致性` 类零改动用例失败） | 跑 `toolkit changelog --history format` 归一（**必须带 `--history`**，默认模式不动历史块），再补跑一次镜像页同步脚本 |
+| 发版后历史块内出现多余空行（`自举一致性` 类零改动用例失败） | 跑 `toolkit changelog --history format` 归一（**必须带 `--history`**，默认模式不动历史块），再补跑一次 `toolkit changelog doc` |
 | 格式化时 stderr 报「归类后条目数由 N 降为 M，疑似丢失内容」 | 归类只应搬移条目，减少即疑似丢内容：核对该版本块是否含非纯条目分组（标题下先出现正文）或被保留分组；确认属正常去重可忽略，否则按 references 的归类规则修回 |
 | 一批改动含新增能力 / 参数，却整批按 `修复：` 前缀登记（整块落 `问题修复` 组）——常见于 bump 判定为 patch 时，误以为级别与条目前缀绑定 | 前缀按**变更本身性质**逐条定：新增命令 / 参数 / 产物用 `新增：`、缺陷纠正用 `修复：`。分组只看前缀、与 bump 正交，**patch 也可挂 `新增：`**——bump 按改动的能力量级判（存量能力上的小新增即 patch），口径见 references |
 

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」值也能幂等）