@fxri/toolkit 1.8.2 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # 方弦工具集
 
+## 1.9.0
+
+> 2026-09-12 发布
+
+### ✨ 新增功能
+
+- 新增 `toolkit skills` 命令域：技能随包分发、与 CLI 同源同版本，升级只需 `pnpm add -g @fxri/toolkit`，告别「CLI 走 npm、技能走 GitHub」两条供应链的版本漂移
+
+  - `toolkit skills install [--copy] [--dir <path>] [--dry-run] [--force] [--format json]`：取自包内 `skills/` 唯一真源，默认软链（升级自动跟随）；链接创建失败自动降级为副本并打印 ⚠️。目标三层：主目标 `~/.agents/skills/`（多家 agent 共读）→ 内置表内已安装的各 agent 全局技能目录 → `--dir` 兜底表外 agent
+  - `toolkit skills status [--format json]`：报告链接与副本现场——软链正常 / 悬空 / 指向别处 / 副本已同步 / 副本已漂移 / 缺失 / 同名冲突
+  - `toolkit skills remove [--dry-run] [--format json]`：只清理本包状态文件登记的产物，绝不误删用户自装技能；卸载 CLI 前先跑它可避免留下悬空链接
+  - `toolkit skills path [--format json]`：输出包根路径，便于委托上游安装器覆盖表外 agent
+  - `--format json` 输出机器可读报告到 stdout，四个子命令统一携带 `schemaVersion: 1` 锚点；`install` / `remove` 另带 `dryRun` 字段区分预演与实跑
+  - 新增配置 `skills.autoLink`（默认 `true`）：每次运行 CLI 时自动补链并修复指向错误的链接（CI 环境跳过、失败静默，可用 `.toolkitrc.json` 关闭）
+  - 新增配置 `skills.autoLinkReplaceForeign`（默认 `true`）：自愈遇到同名实体目录 / 普通文件时先清理再重建为软链；设为 `false` 则一律不动，交由 `toolkit skills install --force` 显式处置
+  - 升级提示与文档口径统一为一条命令：升级后开新会话即可加载最新技能
+  - 文档补充「从上游安装器迁移到内置命令」的指引：旧流程在 `~/.agents/skills/` 残留的实体副本会被报为同名冲突，`toolkit skills install --force` 一键接管；并提示不要与上游安装器混用，否则升级时冲突复发
+
+### 🐛 补丁修复
+
+- 优化技能链接自愈的开销与稳定性，并修正 `toolkit skills status` 的处置指引
+
+  - 自愈改为一次列目录取现场条目类型，不再逐条 `lstatSync`，稳态开销明显下降
+  - `toolkit skills status` 末尾汇总按型给出指引：缺失 / 悬空 / 指向错误 / 副本漂移用 `install` 补齐，同名冲突用 `install --force` 覆盖
+  - 收窄状态分类口径：同名实体目录只有登记为本包副本时才算「副本已漂移」（裸 `install` 即可刷新），未登记的属用户 / 上游产物，报「同名冲突」并需 `--force` 覆盖
+  - 修复自愈「重建失败」时状态记录被静默写掉的问题：失败条目保留在 `~/.agents/.toolkit-skills.json`，下次运行仍会重试
+
+- 修复诊断提示污染机器可读输出：链接自愈提示与升级提示改走 stderr，stdout 保持纯 JSON
+
+  - `toolkit tasks --format json` 等机器可读输出不再被追加提示文本，可安全 `JSON.parse` 与管道消费
+  - `updateCheck` 的缓存文件带 BOM 时不再误判为损坏而重复联网（与配置文件、技能状态文件同口径剥离 BOM）
+
+## 1.8.3
+
+> 2026-09-07 发布
+
+### 🐛 补丁修复
+
+- 修复：范围字段多值口径落地——scope 多值以半角加号分隔（如 `toolkit+lxgl-web`），`--scope` 过滤改按任一段命中，`tasks stats` 按范围拆段统计
+- 修复：`tasks check` 对范围含顿号/逗号/括号软告警并给修复指引
+- 修复：`tasks import` 对范围列含顿号/逗号/括号提示按单值写入（不自动转换）
+- 修复：`tasks normalize` 检出历史归档范围污染，顿号/逗号分隔可 `--fix` 自动归一为半角加号，括号注释仅提示人工确认
+
 ## 1.8.2
 
 > 2026-09-06 发布

package/README.md

@@ -41,7 +41,7 @@ pnpm exec toolkit tasks
 | 多语言 CHANGELOG（changelog） | 封装 changesets 发版、分组标题本地化 | [CLI 参考](./docs/cli.md#changelog-changelog) |
 | Node API | 把上述能力嵌进脚本或平台 | [API 参考](./docs/api.md) |
 | 隐私脱敏 | 落盘前自动掩码邮箱、手机号、密钥等 | [配置参考](./docs/config.md) |
-| AI 技能包（skills） | 不装本工具也能让 AI 按同一套规范干活 | [完整攻略](./docs/guide.md#ai-技能包-skills) · [FAQ](./docs/faq.md#工具和-skills-都得装吗) |
+| AI 技能包（skills） | 不装本工具也能让 AI 按同一套规范干活；装了可一键分发技能 | [完整攻略](./docs/guide.md#ai-技能包-skills) · [FAQ](./docs/faq.md#工具和-skills-都得装吗) |
 | 配置文件 | 按项目定制脱敏、告警、导入列映射、语言表 | [配置参考](./docs/config.md) |
 
 ## 📚 文档
@@ -61,9 +61,12 @@ pnpm exec toolkit tasks
 ## 🧩 AI 技能包（skills）
 
 ```bash
-pnpm dlx skills add fxri-net/toolkit   # npm 用户：npx skills add fxri-net/toolkit
+pnpm add -g @fxri/toolkit && toolkit skills install   # 装了 CLI 一键分发（npm 用户：npm i -g @fxri/toolkit）
+pnpm dlx skills add fxri-net/toolkit                  # 也可用上游安装器（npm 用户：npx skills add fxri-net/toolkit）
 ```
 
+技能随包分发（真源为包内 `skills/`），与 CLI 同源、版本一致；`toolkit skills install` 默认软链，链接创建失败自动降级副本，`toolkit skills status` 查现场，`toolkit skills remove` 卸载。
+
 - [fxri-plan-to-task](./skills/fxri-plan-to-task/SKILL.md)：方案确认后落盘为任务文件（动手前建档评估、check、归档 + 任务级规范沉淀为强制终点）
 - [fxri-release-changelog](./skills/fxri-release-changelog/SKILL.md)：发版时创建变更集、格式化多语言 CHANGELOG
 - [fxri-session-recap](./skills/fxri-session-recap/SKILL.md)：会话收尾全量沉淀、新会话三层恢复、历史任务时间批量修正（1.7.0 新增，1.8.0 扩展）

package/SPEC.md

@@ -64,7 +64,7 @@ scope: app
 | updated | string | 更新日 `YYYYMMDD` |
 | completed | string | 完成时间 `YYYY-MM-DD HH:mm`，`status` 为 `已完成`/`已放弃` 时必填；按四级时间源取证：当场打点（任务完成时取真实时间，首选）/ 聊天记录准确时间戳 / 任务改动 git 提交时间 / 系统当前时间兜底（须标注「收尾补记」）；纯日期写法（`YYYY-MM-DD`）会被补齐 `00:00`，仅日期未补全完整时间会软告警 |
 | depends_on | array | 依赖任务文件名，引用可带 `.md` 扩展名（校验时自动归一为不含扩展名的 basename） |
-| scope | string | 影响范围 |
+| scope | string | 影响范围；一任务多归属时以半角加号分隔（如 `toolkit+lxgl-web`），标签内不使用加号，顿号/逗号列表写法会被 check 软告警、`normalize --fix` 自动归一 |
 
 ## 3. archive 归档文件
 
@@ -116,5 +116,5 @@ scope: app
 4. **归档合并**：读取已有归档文件的任务块，与新任务合并后按 `completed` 排序，重写归档文件。
 5. **任务块分隔**：归档文件内任务以 `---` + `## ` 为边界，勿将正文内部的 `## ` 小节误判为任务边界。
 6. **敏感信息脱敏（可选）**：如需保护隐私，可在写归档前对正文自由文本做掩码；`owner` 等结构化字段保留原值。
-7. **校验（check）**：校验 active 任务 frontmatter 合法性（status 枚举、completed 必填与格式）、跨文件重名、`depends_on` 依赖存在性与成环。
-8. **归一化（normalize）**：校验归档块元数据四字段完整性、完成时间与归档日期一致性、降序排序；`--fix` 可补齐缺失元数据并重排。
+7. **校验（check）**：校验 active 任务 frontmatter 合法性（status 枚举、completed 必填与格式）、跨文件重名、`depends_on` 依赖存在性与成环、范围字段形态软告警（顿号/逗号/括号）。
+8. **归一化（normalize）**：校验归档块元数据四字段完整性、完成时间与归档日期一致性、降序排序、范围字段形态（顿号/逗号疑似多值分隔可 `--fix` 归一为半角加号，括号疑似注释仅提示人工）；`--fix` 可补齐缺失元数据并重排。