@fxri/toolkit 1.13.1 → 1.14.1

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # 方弦工具集
 
+## 1.14.1
+
+> 2026-11-03 发布
+
+### ✨ 新增功能
+
+- `toolkit changelog doc` 将根 CHANGELOG 同步为文档站镜像页，支持 `--check`、路径 / 标题 / outline / frontmatter 配置
+- `changelog version` 发版后自动同步镜像页，失败只告警不阻断
+- 文档站推荐技能包页面，汇总本仓内置技能源与 playbook 外部来源
+- `skills install --mode package` 纯包管理器模式，允许零选择且 core 不再强制
+- `--no-skills` 仅本次零装，不改模式与已保存选择
+- `skills install --from` 支持 Git 远程地址与 `#ref`，本地与远程共用一套来源解析
+- 远程来源浅克隆到用户级缓存，项目面状态只记地址与 ref，不写本机缓存路径
+
+### ⚡ 优化改进
+
+- 镜像逻辑收敛进 CLI，各项目不再维护本地 `sync-changelog-doc.mjs`
+- 对外文档大标题去掉英文副标题，规则页与变更集说明改用中文主题
+- 状态与安装报告输出当前模式，零选择时 `selection` 为空数组
+- 临时 `--from` 来源不写选择集与来源配置
+
+### 🐛 问题修复
+
+- 项目层配置查找止于 home，避免把全局层 `~/.toolkitrc.json` 误当项目层读取
+
+## 1.14.0
+
+> 2026-11-02 发布
+
+### ✨ 新增功能
+
+- `skills install --from <path>` 纳入外部本地技能源（根 SKILL.md / skills/\*/SKILL.md / skills.json 清单三种格式），临时来源只写副本，`--save [name]` 登记为永久来源并默认软链
+- `skills sources` 查看来源、`skills sources remove <name> --prune` / `skills remove --source` 按来源注销与清理
+- 安装 / 卸载操作锁（pid / host / startedAt，5 分钟过期接管），避免多进程同时改写状态与产物
+- 外部来源同名、目录越界与清单 `formatVersion` 非 1 时明确报错，不静默回退
+- 技能按 `metadata.tier` 分层（`core` 必装、`optional` 可选），安装时 TTY 方向键多选，支持 `--skills` / `--all` / `--no-optional` / `--yes`，首次只装 core
+- 按 `SKILL.md` frontmatter `metadata.requires` 自动补全依赖技能，缺失依赖告警后跳过
+- 技能选择后选择目标——全局面按 canonical + 已检测 agent 多选，项目面按候选薄壳目录多选；只用 `--agent` / `--all-agents` 可显式指定，`--no-save-agents` 只影响本次，`--dir` 始终一次性
+- 全局层 `skillsInstall` 与项目层 `projectSkills` 安装偏好（技能选择 + 目标选择），误写层告警并忽略；`prepare` 非交互按已保存目录刷新
+- `skills install --prune` 清理未选择（技能或目标）且内容与本包真源一致的旧产物；`skills remove --skills` 只清指定技能
+
+### 🔧 功能调整
+
+- 技能状态文件改为 `format` + `schemaVersion` + `sources` 结构，旧结构首次读取时一次性导入并备份 `.bak`
+- `skills status` 的 `missing` 只表示已选择但缺失，新增「未选择但已安装」单列（技能与目标两级）且不计入问题
+- `skills remove` 按「配置 → 产物 → 状态」顺序清理
+- `fxri-text-encoding` 触发判据改为上下文中可观测的写入 / 生成 / 执行通道与症状，显式取消临时、一次性、不入库任务豁免
+- 技能描述与规则层同步，写脚本、配置、数据交换文本及跨进程管道前按读取方定字节形态
+- 判据改为按读取方默认解码与字节形态推导，不按语言 / 扩展名白名单，补 PHP 与按平台编码编译的源文件
+- 补命令行参数、环境变量、API 请求体、模板渲染与远端元数据的跨边界判据，故障判定以与原文比对为准
+
 ## 1.13.1
 
 > 2026-11-01 发布

package/README.md

@@ -50,6 +50,7 @@ pnpm exec toolkit tasks
 | 文档 | 适合谁 |
 | --- | --- |
 | [新手指南](./docs/getting-started.md) | 第一次接触，想 30 秒跑起来（含零基础术语表） |
+| [推荐技能包](./docs/packages.md) | 按场景选择技能源（含 playbook 等外部来源） |
 | [操作手册](./docs/handbook.md) | 日常照着做：每个场景该说什么、做什么 |
 | [完整攻略](./docs/guide.md) | 日常使用：工作流、Git 纳管、项目级激活、多语言 CHANGELOG |
 | [CLI 参考](./docs/cli.md) | 查命令、参数、默认值、退出码 |
@@ -69,12 +70,12 @@ toolkit skills install --scope project                # 项目面分发：真源
 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` 卸载。`--scope project` 换项目面——真源落 `<仓库根>/.agents/skills/`、其余候选目录落入口薄壳，随 git 入库后队友 clone 靠 `toolkit init` 写入的 `prepare` 钩子自动补齐。
+技能随包分发（真源为包内 `skills/`），与 CLI 同一发布批次（技能内容版本独立编号）；`toolkit skills install` 默认软链，链接创建失败自动降级副本，`toolkit skills status` 查现场，`toolkit skills remove` 卸载。安装分两步交互：先按 `metadata.tier` 选技能（`fxri-plan-to-task`、`fxri-session-recap` 为 `core`，`skills` 模式必装、`package` 模式可选；`fxri-release-changelog`、`fxri-text-encoding` 为 `optional`），再选目标（`canonical` 主目标 + 已检测 agent；项目面为候选薄壳目录）；`--skills` / `--all` / `--no-optional` / `--agent` / `--all-agents` / `--yes` 可跳过交互，首次按模式默认（`skills` 装 `core`、`package` 零装）与全部可用目标，`--no-save-agents` 只影响本次；`--mode package` 切纯包管理器模式（core 也可不装、允许零选），`--no-skills` 仅本次零装。选择集分别写入 `~/.toolkitrc.json` 的 `skillsInstall` 与项目层 `.toolkitrc.json` 的 `projectSkills`。外部技能源用 `--from <path|url>` 临时纳入（副本、只写本次），加 `--save [name]` 登记为永久来源（默认软链）；`toolkit skills sources` 查看 / 注销来源。`--scope project` 换项目面——真源落 `<仓库根>/.agents/skills/`、其余候选目录落入口薄壳，随 git 入库后队友 clone 靠 `toolkit init` 写入的 `prepare` 钩子自动补齐。
 
 - [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 新增技能）
-- [fxri-text-encoding](./skills/fxri-text-encoding/SKILL.md)：文本文件的 UTF-8 / BOM / 行尾基线，脚本中文乱码、终端与重定向输出乱码、首行报错的定位与修复
+- [fxri-text-encoding](./skills/fxri-text-encoding/SKILL.md)：文本字节形态基线（文件、管道、命令行、API 请求体，含临时脚本与一次性命令），非 ASCII 文本丢失 / 乱码与首行报错的定位与修复
 
 skills 与工具的关系、只在公司项目激活等说明见 [FAQ](./docs/faq.md) 与 [完整攻略](./docs/guide.md#ai-技能包-skills)。
 

package/SPEC.md

@@ -1,10 +1,12 @@
-# 任务文件规范（SPEC）
+# 任务文件规范
 
-> 规范更新时间 2026-10-19 15:35。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
+> 规范更新时间 2026-11-03 02:30。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
 
 > 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
 >
 > 本文件是规范内容的**单一事实源**；派生载体有文档站 [完整攻略 · 任务文件规范](https://fxri-net.github.io/toolkit/guide.html#任务文件规范)（供交互式阅读与逐条校验）与技能包 `task-spec.md`（面向非 toolkit 项目的通用裁剪版），与本文件冲突时一律以本文件为准。
+>
+> 英文缩写 `SPEC`（Specification）即本规范的简称，正文首次出现处说明。
 
 ## 0. 协作模型