@fxri/toolkit 1.9.4 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # 方弦工具集
 
+## 1.10.0
+
+> 2026-09-16 发布
+
+### ✨ 新增功能
+
+- 规范载体目录化与端分类——`.tasks/conventions.md` 单文件升级为 `.tasks/conventions/` 目录形态（`index.md` 唯一入口 + `common.md` 全端通用条文 + `<端名>.md` 各端专属条文，分册按需创建），端名与任务 `scope` 取值逐字一致、`index.md` 顶部端清单为端的唯一权威，读取分层为「常驻只读 index + 按 scope 命中加载分册与 common」
+- 存量迁移支持——旧单文件可整体搬为 `index.md` 后逐条给归属建议、用户确认后拆分册，迁移三段式可中断不丢内容；新旧形态兼容读，两者并存时以目录形态为准
+- 内容修订路径——旧条目过时走「演进记录留痕 + index 行更新 + 状态置 `已废弃`」，不删行
+
+### 🔧 功能调整
+
+- `toolkit init` 预生成 `conventions/index.md` 骨架（含端清单模板）；`toolkit tasks check` 在旧单文件残留或 `conventions/` 缺 `index.md` 时给软告警，即迁移入口
+
+### ⚡ 优化改进
+
+- fxri-plan-to-task 升级 1.2.0（写入归属判定 + 存量迁移触发）、fxri-session-recap 升级 1.2.0（R3 落点、读取分层、内容修订与形态迁移分流）、fxri-release-changelog 升级 1.0.12（发版流程补「润色后跑一次 `changelog --history format` 归一历史块」步骤与失败模式，references 补格式化不动点口径）
+
+### 📝 文档更新
+
+- 补迁移教程——guide 新增「存量规范载体迁移」节，handbook 新增「四、规范载体迁移」节，faq 新增迁移问答
+- 修正文档承诺未实现——guide 原称 conventions.md「两种形态 skill 均支持」，实际 SPEC.md / task-spec.md / 两个 SKILL.md 均无「形态」概念，已按实际能力改写
+
+## 1.9.5
+
+> 2026-09-16 发布
+
+### 🔧 功能调整
+
+- CLI 解析错误文案改为中文并附帮助指引
+
+  - 未知命令、未知选项、参数个数不符统一输出 `⚠️` 开头的中文提示（如「未知命令「zzzz」。」），并附一行 `运行 toolkit --help 查看可用命令`；相似命令/选项提示（原 `(Did you mean skills?)`）一并转中文，退出码仍为 `1`
+  - 修掉 commander 自行写 stderr 导致的英文原文残留，解析错误不再出现英文与中文两行并排
+  - `changelog` 透传给 changesets 的英文输出不受影响
+
+### ⚡ 优化改进
+
+- CLI 帮助清单条目与子命令自身 Usage 行对齐
+
+  - 帮助清单条目统一为「命令名 + 该命令自身 Usage 行」，消除同一命令两套渲染规则：无自有选项但有子命令的域（如 `skills`）不再只剩光杆名字，现与 `skills --help` 的 Usage 行同形（`skills [options] [command]`）
+  - 帮助选项与隐式帮助子命令的描述由 commander 英文默认值改为中文：`-h, --help` 与 `help [command]` 均为「显示帮助」，与 `-v, --version 显示版本号` 及 `docs/cli.md` 既有表述对齐
+- 根描述文案收敛为单一真源
+
+  - 新增 `src/about.ts` 导出 `DESCRIPTION`，CLI 根描述、站点 `description` 与 `og:description` 改为引用该常量，消除同一句话多处手写
+  - `toolkit --help` 首行描述补上句末句号，与 `package.json` / 文档既有文案对齐（原缺句号即由此漂移导致）
+  - 文档一致性用例新增根描述断言：`package.json`、`README.md` 与 `docs/index.md` 首页 tagline 的共用文案改一处漏改其余即失败
+
+### 🐛 问题修复
+
+- 修复 changelog 与 tasks 两条静默误执行路径
+
+  - `toolkit changelog version --help` / `toolkit changelog format --help`：`--help` 原本被选项透传语义当作操作数丢弃，命令照跑——`version` 会真发版、`format` 会真改写 CHANGELOG；现改为打印 changelog 本域帮助并正常退出。`changelog --help` 与 `changelog add --help` 等不受影响，仍交由 changesets 输出其帮助
+  - `toolkit tasks <未知子命令>`：原本静默回落为「任务总览」且 exit 0 无任何提示，现报 `⚠️ 非法子命令「x」，仅支持 archive / check / normalize / stats（留空查看任务总览）` 并 exit 1
+
 ## 1.9.4
 
 > 2026-09-15 发布

package/SPEC.md

@@ -1,6 +1,6 @@
 # 任务文件规范（SPEC）
 
-> 规范更新时间 2026-09-14 15:17。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
+> 规范更新时间 2026-09-16 09:52。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
 
 > 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
 >
@@ -12,7 +12,7 @@
 
 1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；active 已有同主题任务则更新原文件，禁止重复建档。archive 已有同主题任务（已归档完成）时按增量判别：无增量（重复提议）不建档、有增量（延续/扩展）则重新建档并在正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）`、仅修正旧记录错误走历史修正（fxri-session-recap 模式三）不建档。**归档任务不可变**：已归档块是终结记录，不追加新内容，延续需求一律走新任务。
 2. **任务唯一键**：`{年月日}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
-3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions.md），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
+3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions 载体），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
 4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
 
 ## 1. 目录结构
@@ -25,10 +25,13 @@
 ├── archive/                   # 任务归档（已完成）
 │   └── {年月}/
 │       └── {年月日}.md        # 某天归档
-└── conventions.md             # 项目协作规范（可选）：从任务提炼的规范沉淀地，非任务文件
+└── conventions/               # 项目协作规范载体（可选）：从任务提炼的规范沉淀地，非任务文件
+    ├── index.md               # 唯一入口与唯一权威：端清单 + 每条规范一行指针
+    ├── common.md              # 全端通用条文（按需创建）
+    └── {端名}.md              # 各端专有条文，端名 = 任务 scope 取值（按需创建）
 ```
 
-`conventions.md` 由 AI 协作流程（fxri-plan-to-task 归档时 / fxri-session-recap 收尾时）维护，写入前需用户确认；tasks 命令不读取它、check 不因它告警。
+`conventions/` 由 AI 协作流程（fxri-plan-to-task 归档时 / fxri-session-recap 收尾时）维护，写入前需用户确认；tasks 命令不读其内容、check 不因内容告警（仅在载体形态异常时软告警）。端名与任务 `scope` 取值共用同一套词表、逐字一致，`index.md` 顶端的端清单是端的唯一权威（不扫目录）；分册按需创建，判据是「该归属下有无需独立承载的条文」。旧版单文件 `conventions.md` 兼容读取，检测到残留时软告警提示迁移。
 
 ## 2. active 任务文件