@fxri/toolkit 1.9.1 → 1.9.2

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # 方弦工具集
 
+## 1.9.2
+
+> 2026-09-14 发布
+
+### ✨ 新增功能
+
+- 新增：CHANGELOG 按变更类型语义分组，分组维度与版本号维度解耦
+
+  - 变更集条目以 `类型：` 前缀开头（`新增：`/`修改：`/`修复：`/`优化：`/`清理：`/`文档：`/`重大：`），`toolkit changelog version/format` 据此把条目归入语义分组；`文档：` 条目出现在 patch 版本里即进「📝 文档更新」，不再被版本号绑架
+  - 分组标题由 4 组扩为 8 组 + 1 兜底组，空组省略：🚨 重大变更 / ✨ 新增功能 / 🔧 功能调整 / ⚡ 优化改进 / 🐛 问题修复 / 📝 文档更新 / 🧹 清理移除 / 🔗 依赖变更 / 📦 其他变更
+  - 无前缀条目按所属源组标题兜底：Major 块 → 重大变更、Minor 块 → 新增功能、Patch 块 → 其他变更；⚠️ patch 无前缀条目的落点由「🐛 补丁修复」改为中性的「📦 其他变更」，不再把非修复改动误标为修复
+  - 历史版本块保留当时口径，`changelog format` 不追溯改写；前缀识别与输出语言解耦（全局前缀表全语言共用），变更集条目语言与输出语言不一致时仍正确归组
+  - 自定义语言新增可选 `groups`（`[{ slot, title, prefixes? }]`）声明本语言标题与自有前缀；未声明时退化为纯替换，既有配置无需改动
+  - ⚠️ 对外契约变化：`--lang en` 的组标题文本变化（如 `### ✨ Minor Changes` → `### ✨ Added`）；`--warn` / `FX_CHECK_WARN` / `check.warnings` 适用范围由任务校验告警扩为「任务校验告警 + 变更集条目缺类型前缀告警」，同一开关一并开关闭；新增公共导出 `SLOT_PREFIXES` / `SemanticSlot`
+  - 修复：发布日期行识别由硬编码「发布/released」改为「当前语言 `released` ∪ 全部内置语言 `released`」后缀集合——自定义语言（日文等）按自身 `released` 识别，内置 zh / en 互跑（如中文日志用 `--lang en` 输出）也不再重复追加日期行
+- 新增：技能版本可视化，旧会话可自校验技能内容是否过期
+
+  - `toolkit skills status` 常驻打印包内各技能真源版本，`--format json` 新增 `skillVersions` 字段与逐项 `version`，作为磁盘基准值；`toolkit skills install` 报告同样逐项带版本
+  - 每个 SKILL.md 正文首部显式声明版本（与 frontmatter `metadata.version` 一致），版本随技能内容进会话上下文；被问版本时报上下文声明值，与 `skills status` 打印的磁盘值对照，不一致即说明会话上下文已过期，开新会话即可
+  - 措辞澄清：技能随包同源分发（与 CLI 同一发布批次），技能内容版本独立编号
+
+### 🔧 功能调整
+
+- 修改：任务统计 JSON 输出补齐 schemaVersion 锚点
+
+  - `toolkit tasks stats --format json` 顶层新增 `schemaVersion: 1`，与 `tasks --export`、`skills --format json` 统一口径；既有统计字段保持原位与语义不变，按旧 key 读取的消费方不受影响
+  - 序列化收敛为技能域与任务统计域共用的单一出口，schemaVersion 锚点位置不再分散维护
+
 ## 1.9.1
 
 > 2026-09-13 发布

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright © 2026 唐启云
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright © 2026 唐启云
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -1,9 +1,9 @@
-@fxri/toolkit
-Copyright © 2026 唐启云. All rights reserved.
-
-出品方：方弦研究所（唐启云个人项目品牌，非独立法人实体）
-
-商标声明：
-"方弦®"为第42类注册商标（注册号89648411），核定服务项目：计算机出租、计算机软件设计、为他人研究和开发新产品、计算机软件维护、把有形的数据或文件转换成电子媒体、为他人创建和维护网站、网络服务器出租、提供互联网搜索引擎、托管计算机站（网站）、云计算。
-本开源许可（MIT License）不授予商标使用权。
-详见 TRADEMARK.md 了解完整商标信息。
+@fxri/toolkit
+Copyright © 2026 唐启云. All rights reserved.
+
+出品方：方弦研究所（唐启云个人项目品牌，非独立法人实体）
+
+商标声明：
+"方弦®"为第42类注册商标（注册号89648411），核定服务项目：计算机出租、计算机软件设计、为他人研究和开发新产品、计算机软件维护、把有形的数据或文件转换成电子媒体、为他人创建和维护网站、网络服务器出租、提供互联网搜索引擎、托管计算机站（网站）、云计算。
+本开源许可（MIT License）不授予商标使用权。
+详见 TRADEMARK.md 了解完整商标信息。

package/README.md

@@ -1,108 +1,108 @@
-<p align="center">
-  <img src="./docs/public/logo.png" width="128" alt="方弦工具集">
-</p>
-
-# 方弦工具集
-
-[![CI](https://github.com/fxri-net/toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/fxri-net/toolkit/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@fxri/toolkit)](https://www.npmjs.com/package/@fxri/toolkit)
-[![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)](./docs/getting-started.md#安装)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
-
-> 国内网络建议优先 [Gitee 镜像](https://gitee.com/fxri/toolkit)（与 GitHub 同源同步，仓库/文档/issues/skills 全渠道可用）；问题反馈走 [GitHub Issues](https://github.com/fxri-net/toolkit/issues) 或 [Gitee Issues](https://gitee.com/fxri/toolkit/issues)。
-
-专为**多人 + AI 跨项目协作**打造：任务管理 + 多语言 CHANGELOG。
-
-AI 参与开发后，方案与决策散落在对话记录里，会话一关什么都不剩；任务记录零散，谁在做、做到哪，无从查起；发版 CHANGELOG 还要人肉维护多语言。本工具把这条链路沉淀为**仓库内可检索、可校验、可归档的文件**——人离开会话，记忆留在仓库里。
-
-- **零依赖 AI 技能包（skills）**：方案落盘、发版 CHANGELOG 两套工作流沉淀为 Agent Skills，不绑定任何 AI 工具；skills 可以独立工作，CLI 是可选加速——推荐都装，体验最完整（[什么关系？](./docs/faq.md#工具和-skills-都得装吗)）
-- **不懂 AI 也能用**：任务管理与 CHANGELOG 是纯 CLI 能力；术语都说了人话（[先看术语表](./docs/getting-started.md#几个术语先说人话)）
-
-## 🚀 30 秒上手
-
-```bash
-# 1. 项目内安装（推荐，团队共享版本）
-pnpm add -D @fxri/toolkit
-
-# 2. 初始化任务区（生成 .tasks/ 骨架，1.7.0 新增）
-pnpm exec toolkit init
-
-# 3. 查看任务总览
-pnpm exec toolkit tasks
-```
-
-之后：方案确认后登记为 `.tasks/` 任务文件 → `pnpm exec toolkit tasks check` 校验 → 完成后 `pnpm exec toolkit tasks archive` 归档并做规范沉淀。完整步骤见 [新手指南](./docs/getting-started.md)。
-
-## ✨ 能力矩阵
-
-| 能力 | 适用场景 | 文档 |
-| --- | --- | --- |
-| 任务管理（tasks） | 方案落盘、总览过滤、校验归档、导入导出 CSV / XLSX / JSON | [CLI 参考](./docs/cli.md) · [任务文件规范](./docs/guide.md#任务文件规范) |
-| 多语言 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-都得装吗) |
-| 配置文件 | 按项目定制脱敏、告警、导入列映射、语言表 | [配置参考](./docs/config.md) |
-
-## 📚 文档
-
-| 文档 | 适合谁 |
-| --- | --- |
-| [新手指南](./docs/getting-started.md) | 第一次接触，想 30 秒跑起来（含零基础术语表） |
-| [操作手册](./docs/handbook.md) | 日常照着做：每个场景该说什么、做什么 |
-| [完整攻略](./docs/guide.md) | 日常使用：工作流、Git 纳管、项目级激活、多语言 CHANGELOG |
-| [CLI 参考](./docs/cli.md) | 查命令、参数、默认值、退出码 |
-| [API 参考](./docs/api.md) | 作为库引入 Node 项目 |
-| [配置参考](./docs/config.md) | 查 `.toolkitrc.json` 字段 |
-| [FAQ](./docs/faq.md) | 遇到问题先来这里找 |
-| [推荐 AI 全局规则](./docs/ai-rules.md) | 想让 AI 助手按本工具的最佳实践协作 |
-| [完整文档站](https://fxri-net.github.io/toolkit/) | 在线阅读体验 |
-
-## 🧩 AI 技能包（skills）
-
-```bash
-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 扩展）
-
-skills 与工具的关系、只在公司项目激活等说明见 [FAQ](./docs/faq.md) 与 [完整攻略](./docs/guide.md#ai-技能包-skills)。
-
-## 📦 安装
-
-```bash
-pnpm add -D @fxri/toolkit        # 项目 devDependency（团队项目推荐，版本随仓库锁定）
-pnpm i -g @fxri/toolkit          # 全局（个人多项目推荐；pnpm 不受 nvm 切版本影响）
-pnpm dlx @fxri/toolkit tasks     # 不安装临时执行
-```
-
-npm / yarn / bun 用户与各方式对比见 [新手指南 · 安装](./docs/getting-started.md#安装)。
-
-## 🔒 隐私脱敏
-
-落盘记录默认脱敏敏感信息：内置邮箱、手机号、身份证、IPv4、内网 URL、JWT、AWS / GitHub / OpenAI / Slack 密钥等 13 类规则，支持自定义规则与禁用。开关三档（CLI 参数 > 环境变量 > 配置文件），详见 [配置参考](./docs/config.md)。
-
-## ⚙️ 环境要求
-
-- Node.js >= 20（Node 18 可安装，changesets 相关子命令不可用，见 [FAQ](./docs/faq.md#node-18-能用吗)）
-
-## 📄 版权信息
-
-作者：唐启云 <tqy@fxri.net>
-
-出品：方弦研究所
-
-版权：Copyright © 2026 唐启云. All rights reserved.
-
-网站：[方弦研究信息网](https://fxri.net:444/)
-
-协议：[MIT License](./LICENSE)
-
-商标："方弦®"为第42类注册商标（注册号89648411），本开源许可不授予商标使用权，详见 [TRADEMARK.md](./TRADEMARK.md)
-
-> 方弦研究所为唐启云个人项目品牌与出品方，非独立法人实体；本软件著作权归唐启云所有。
+<p align="center">
+  <img src="./docs/public/logo.png" width="128" alt="方弦工具集">
+</p>
+
+# 方弦工具集
+
+[![CI](https://github.com/fxri-net/toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/fxri-net/toolkit/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@fxri/toolkit)](https://www.npmjs.com/package/@fxri/toolkit)
+[![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)](./docs/getting-started.md#安装)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+> 国内网络建议优先 [Gitee 镜像](https://gitee.com/fxri/toolkit)（与 GitHub 同源同步，仓库/文档/issues/skills 全渠道可用）；问题反馈走 [GitHub Issues](https://github.com/fxri-net/toolkit/issues) 或 [Gitee Issues](https://gitee.com/fxri/toolkit/issues)。
+
+专为**多人 + AI 跨项目协作**打造：任务管理 + 多语言 CHANGELOG。
+
+AI 参与开发后，方案与决策散落在对话记录里，会话一关什么都不剩；任务记录零散，谁在做、做到哪，无从查起；发版 CHANGELOG 还要人肉维护多语言。本工具把这条链路沉淀为**仓库内可检索、可校验、可归档的文件**——人离开会话，记忆留在仓库里。
+
+- **零依赖 AI 技能包（skills）**：方案落盘、发版 CHANGELOG 两套工作流沉淀为 Agent Skills，不绑定任何 AI 工具；skills 可以独立工作，CLI 是可选加速——推荐都装，体验最完整（[什么关系？](./docs/faq.md#工具和-skills-都得装吗)）
+- **不懂 AI 也能用**：任务管理与 CHANGELOG 是纯 CLI 能力；术语都说了人话（[先看术语表](./docs/getting-started.md#几个术语先说人话)）
+
+## 🚀 30 秒上手
+
+```bash
+# 1. 项目内安装（推荐，团队共享版本）
+pnpm add -D @fxri/toolkit
+
+# 2. 初始化任务区（生成 .tasks/ 骨架，1.7.0 新增）
+pnpm exec toolkit init
+
+# 3. 查看任务总览
+pnpm exec toolkit tasks
+```
+
+之后：方案确认后登记为 `.tasks/` 任务文件 → `pnpm exec toolkit tasks check` 校验 → 完成后 `pnpm exec toolkit tasks archive` 归档并做规范沉淀。完整步骤见 [新手指南](./docs/getting-started.md)。
+
+## ✨ 能力矩阵
+
+| 能力 | 适用场景 | 文档 |
+| --- | --- | --- |
+| 任务管理（tasks） | 方案落盘、总览过滤、校验归档、导入导出 CSV / XLSX / JSON | [CLI 参考](./docs/cli.md) · [任务文件规范](./docs/guide.md#任务文件规范) |
+| 多语言 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-都得装吗) |
+| 配置文件 | 按项目定制脱敏、告警、导入列映射、语言表 | [配置参考](./docs/config.md) |
+
+## 📚 文档
+
+| 文档 | 适合谁 |
+| --- | --- |
+| [新手指南](./docs/getting-started.md) | 第一次接触，想 30 秒跑起来（含零基础术语表） |
+| [操作手册](./docs/handbook.md) | 日常照着做：每个场景该说什么、做什么 |
+| [完整攻略](./docs/guide.md) | 日常使用：工作流、Git 纳管、项目级激活、多语言 CHANGELOG |
+| [CLI 参考](./docs/cli.md) | 查命令、参数、默认值、退出码 |
+| [API 参考](./docs/api.md) | 作为库引入 Node 项目 |
+| [配置参考](./docs/config.md) | 查 `.toolkitrc.json` 字段 |
+| [FAQ](./docs/faq.md) | 遇到问题先来这里找 |
+| [推荐 AI 全局规则](./docs/ai-rules.md) | 想让 AI 助手按本工具的最佳实践协作 |
+| [完整文档站](https://fxri-net.github.io/toolkit/) | 在线阅读体验 |
+
+## 🧩 AI 技能包（skills）
+
+```bash
+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 扩展）
+
+skills 与工具的关系、只在公司项目激活等说明见 [FAQ](./docs/faq.md) 与 [完整攻略](./docs/guide.md#ai-技能包-skills)。
+
+## 📦 安装
+
+```bash
+pnpm add -D @fxri/toolkit        # 项目 devDependency（团队项目推荐，版本随仓库锁定）
+pnpm i -g @fxri/toolkit          # 全局（个人多项目推荐；pnpm 不受 nvm 切版本影响）
+pnpm dlx @fxri/toolkit tasks     # 不安装临时执行
+```
+
+npm / yarn / bun 用户与各方式对比见 [新手指南 · 安装](./docs/getting-started.md#安装)。
+
+## 🔒 隐私脱敏
+
+落盘记录默认脱敏敏感信息：内置邮箱、手机号、身份证、IPv4、内网 URL、JWT、AWS / GitHub / OpenAI / Slack 密钥等 13 类规则，支持自定义规则与禁用。开关三档（CLI 参数 > 环境变量 > 配置文件），详见 [配置参考](./docs/config.md)。
+
+## ⚙️ 环境要求
+
+- Node.js >= 20（Node 18 可安装，changesets 相关子命令不可用，见 [FAQ](./docs/faq.md#node-18-能用吗)）
+
+## 📄 版权信息
+
+作者：唐启云 <tqy@fxri.net>
+
+出品：方弦研究所
+
+版权：Copyright © 2026 唐启云. All rights reserved.
+
+网站：[方弦研究信息网](https://fxri.net:444/)
+
+协议：[MIT License](./LICENSE)
+
+商标："方弦®"为第42类注册商标（注册号89648411），本开源许可不授予商标使用权，详见 [TRADEMARK.md](./TRADEMARK.md)
+
+> 方弦研究所为唐启云个人项目品牌与出品方，非独立法人实体；本软件著作权归唐启云所有。

package/SPEC.md

@@ -1,120 +1,122 @@
-# 任务文件规范（SPEC）
-
-> 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
->
-> 本文是**摘要**。字段说明、示例与各语言实现要点不变，交互式阅读与逐条校验说明见文档站 [完整攻略 · 任务文件规范](https://fxri-net.github.io/toolkit/guide.html#任务文件规范)；规范内容的单一事实源即本文件。
-
-## 0. 协作模型
-
-任务区是**多写者共享**的：同一 `.tasks/` 可能被多人或多个 AI 参与。为避免互相覆盖，归档、归一化修复等工具内部写操作以排他锁（`.archive.lock`）防并发覆盖；人 / AI 的直接编辑遵循「先查后写」约定。约定：
-
-1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；active 已有同主题任务则更新原文件，禁止重复建档。archive 已有同主题任务（已归档完成）时按增量判别：无增量（重复提议）不建档、有增量（延续/扩展）则重新建档并在正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）`、仅修正旧记录错误走历史修正（fxri-session-recap 模式三）不建档。**归档任务不可变**：已归档块是终结记录，不追加新内容，延续需求一律走新任务。
-2. **任务唯一键**：`{年月日}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
-3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions.md），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
-4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
-
-## 1. 目录结构
-
-```
-.tasks/
-├── active/                    # 实时任务（未完成）
-│   └── {年月}/                # YYYYMM，如 202609
-│       └── {年月日}-{用户名}-{任务简述}.md
-├── archive/                   # 任务归档（已完成）
-│   └── {年月}/
-│       └── {年月日}.md        # 某天归档
-└── conventions.md             # 项目协作规范（可选）：从任务提炼的规范沉淀地，非任务文件
-```
-
-`conventions.md` 由 AI 协作流程（fxri-plan-to-task 归档时 / fxri-session-recap 收尾时）维护，写入前需用户确认；tasks 命令不读取它、check 不因它告警。
-
-## 2. active 任务文件
-
-### 2.1 命名
-
-`{年月日}-{用户名}-{任务简述}.md`，示例 `20260902-唐启云-忘记密码.md`
-
-- `年月日` = 任务创建日，`YYYYMMDD` 直接拼（不加 `-`）
-- `用户名` = git 用户名
-- `任务简述` = 简短短语（不加空格；建议团队统一语言）
-
-### 2.2 内容
-
-文件顶部为 frontmatter（两行 `---` 包裹的 YAML 键值块），随后为正文。
-
-```markdown
----
-owner: 唐启云
-status: 进行中
-created: 20260902
-updated: 20260902
-completed: ''
-depends_on: []
-scope: app
----
-
-# 任务标题
-```
-
-| 字段 | 类型 | 说明 |
-| --- | --- | --- |
-| owner | string | 负责人（git 用户名）；缺失时 `check` 软告警 |
-| status | enum | `待办` / `进行中` / `已完成` / `阻塞` / `已放弃` |
-| created | string | 创建日 `YYYYMMDD`，应等于文件名日期前缀；缺失/不一致/格式错误时 `check` 软告警 |
-| updated | string | 更新日 `YYYYMMDD` |
-| completed | string | 完成时间 `YYYY-MM-DD HH:mm`，`status` 为 `已完成`/`已放弃` 时必填；按四级时间源取证：当场打点（任务完成时取真实时间，首选）/ 聊天记录准确时间戳 / 任务改动 git 提交时间 / 系统当前时间兜底（须标注「收尾补记」）；纯日期写法（`YYYY-MM-DD`）会被补齐 `00:00`，仅日期未补全完整时间会软告警 |
-| depends_on | array | 依赖任务文件名，引用可带 `.md` 扩展名（校验时自动归一为不含扩展名的 basename） |
-| scope | string | 影响范围；一任务多归属时以半角加号分隔（如 `toolkit+lxgl-web`），标签内不使用加号，顿号/逗号列表写法会被 check 软告警、`normalize --fix` 自动归一 |
-
-## 3. archive 归档文件
-
-### 3.1 命名
-
-`{年月日}.md`，按任务**完成时间**的日期（`YYYYMMDD`）划分。
-
-### 3.2 内容
-
-同一天完成的任务整合进同一文件，**按完成时间降序排序**（最新在前），任务之间用 `---` 分隔。每个任务块必须含**元数据行**（`> ` 开头，四字段：负责人 / 状态 / 范围 / 完成时间），缺失或不完整时可由 `toolkit tasks normalize --fix` 补齐：
-
-```markdown
-# 20260902 归档
-
-## 20260902-唐启云-忘记密码
-
-> 负责人：唐启云　状态：已完成　范围：app　完成时间：2026-09-02 14:30
-
-# 忘记密码
-（正文）
-
----
-
-## 20260902-唐启云-其他任务
-
-> 负责人：唐启云　状态：已完成　范围：-　完成时间：2026-09-02 15:00
-
-（正文）
-```
-
-## 4. 归档规则
-
-1. 归档触发是**人工 / 事件驱动**，非定时任务；常见触发时机为任务完成、相关变更提交版本控制之前，此时应先行归档再提交。
-2. **任务级归档**：`status ∈ {已完成, 已放弃}` 且带 `completed` 的任务可归档。
-3. `待办` / `进行中` / `阻塞` 均不归档。
-4. 归档文件按 `completed` 的日期（`YYYYMMDD`）划分。
-5. 归档文件内任务按 `completed` **降序**排序（最新在前，`YYYY-MM-DD HH:mm` 定宽字符串比较即时间序）。
-6. **完成时间口径**：`completed` 只填真实收工时间（四级时间源取证），日期应与归档文件日期一致；不一致属「日期漂移」，`toolkit tasks normalize` 会检出，`--fix` 自动把漂移块迁移到对应日期文件（迁移前可用 `normalize` 只读检查）；归档文件放错月份目录（如 `archive/202608/20260903.md`）时 `--fix` 会将其移动到正确月份目录。⚠️ 补档 / 历史时间修正场景下，归档块的完成时间早于归档动作时间是正常的——修正块时间后执行 `normalize --fix` 即完成迁移。
-7. **疑似任务块**：任务块判定要求标题后首个非空行为含「完成时间」的元数据行；形如 `{年月日}-{负责人}-{简述}` 的 `## ` 标题后跟 `> ` 元数据但缺「完成时间」时，会被视为疑似任务块并在 `normalize` 检出提示人工确认（不自动修复）。
-8. **并发归档防护**：归档采用排他锁（`.archive.lock`），检测到并发归档时跳过并告警；`--dry-run` 可预演归档动作而不落盘。
-
-## 5. 其他语言实现要点
-
-按本规范实现时，需覆盖：
-
-1. **frontmatter 解析**：读取文件顶部 `---` 之间的 `key: value` 行。
-2. **目录遍历**：`active/` 下仅一层年月子目录，收集 `.md` 文件。
-3. **完成时间提取**：从 frontmatter 的 `completed` 字段读取。
-4. **归档合并**：读取已有归档文件的任务块，与新任务合并后按 `completed` 排序，重写归档文件。
-5. **任务块分隔**：归档文件内任务以 `---` + `## ` 为边界，勿将正文内部的 `## ` 小节误判为任务边界。
-6. **敏感信息脱敏（可选）**：如需保护隐私，可在写归档前对正文自由文本做掩码；`owner` 等结构化字段保留原值。
-7. **校验（check）**：校验 active 任务 frontmatter 合法性（status 枚举、completed 必填与格式）、跨文件重名、`depends_on` 依赖存在性与成环、范围字段形态软告警（顿号/逗号/括号）。
-8. **归一化（normalize）**：校验归档块元数据四字段完整性、完成时间与归档日期一致性、降序排序、范围字段形态（顿号/逗号疑似多值分隔可 `--fix` 归一为半角加号，括号疑似注释仅提示人工）；`--fix` 可补齐缺失元数据并重排。
+# 任务文件规范（SPEC）
+
+> 规范版本 1.0。本规范内容变更时同批递增此版本号，实现方与规范快照据此对照是否失同步。
+
+> 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
+>
+> 本文是**摘要**。字段说明、示例与各语言实现要点不变，交互式阅读与逐条校验说明见文档站 [完整攻略 · 任务文件规范](https://fxri-net.github.io/toolkit/guide.html#任务文件规范)；规范内容的单一事实源即本文件。
+
+## 0. 协作模型
+
+任务区是**多写者共享**的：同一 `.tasks/` 可能被多人或多个 AI 参与。为避免互相覆盖，归档、归一化修复等工具内部写操作以排他锁（`.archive.lock`）防并发覆盖；人 / AI 的直接编辑遵循「先查后写」约定。约定：
+
+1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；active 已有同主题任务则更新原文件，禁止重复建档。archive 已有同主题任务（已归档完成）时按增量判别：无增量（重复提议）不建档、有增量（延续/扩展）则重新建档并在正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）`、仅修正旧记录错误走历史修正（fxri-session-recap 模式三）不建档。**归档任务不可变**：已归档块是终结记录，不追加新内容，延续需求一律走新任务。
+2. **任务唯一键**：`{年月日}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
+3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions.md），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
+4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
+
+## 1. 目录结构
+
+```
+.tasks/
+├── active/                    # 实时任务（未完成）
+│   └── {年月}/                # YYYYMM，如 202609
+│       └── {年月日}-{用户名}-{任务简述}.md
+├── archive/                   # 任务归档（已完成）
+│   └── {年月}/
+│       └── {年月日}.md        # 某天归档
+└── conventions.md             # 项目协作规范（可选）：从任务提炼的规范沉淀地，非任务文件
+```
+
+`conventions.md` 由 AI 协作流程（fxri-plan-to-task 归档时 / fxri-session-recap 收尾时）维护，写入前需用户确认；tasks 命令不读取它、check 不因它告警。
+
+## 2. active 任务文件
+
+### 2.1 命名
+
+`{年月日}-{用户名}-{任务简述}.md`，示例 `20260902-唐启云-忘记密码.md`
+
+- `年月日` = 任务创建日，`YYYYMMDD` 直接拼（不加 `-`）
+- `用户名` = git 用户名
+- `任务简述` = 简短短语（不加空格；建议团队统一语言）
+
+### 2.2 内容
+
+文件顶部为 frontmatter（两行 `---` 包裹的 YAML 键值块），随后为正文。
+
+```markdown
+---
+owner: 唐启云
+status: 进行中
+created: 20260902
+updated: 20260902
+completed: ''
+depends_on: []
+scope: app
+---
+
+# 任务标题
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| owner | string | 负责人（git 用户名）；缺失时 `check` 软告警 |
+| status | enum | `待办` / `进行中` / `已完成` / `阻塞` / `已放弃` |
+| created | string | 创建日 `YYYYMMDD`，应等于文件名日期前缀；缺失/不一致/格式错误时 `check` 软告警 |
+| updated | string | 更新日 `YYYYMMDD` |
+| completed | string | 完成时间 `YYYY-MM-DD HH:mm`，`status` 为 `已完成`/`已放弃` 时必填；按四级时间源取证：当场打点（任务完成时取真实时间，首选）/ 聊天记录准确时间戳 / 任务改动 git 提交时间 / 系统当前时间兜底（须标注「收尾补记」）；纯日期写法（`YYYY-MM-DD`）会被补齐 `00:00`，仅日期未补全完整时间会软告警 |
+| depends_on | array | 依赖任务文件名，引用可带 `.md` 扩展名（校验时自动归一为不含扩展名的 basename） |
+| scope | string | 影响范围；一任务多归属时以半角加号分隔（如 `toolkit+lxgl-web`），标签内不使用加号，顿号/逗号列表写法会被 check 软告警、`normalize --fix` 自动归一 |
+
+## 3. archive 归档文件
+
+### 3.1 命名
+
+`{年月日}.md`，按任务**完成时间**的日期（`YYYYMMDD`）划分。
+
+### 3.2 内容
+
+同一天完成的任务整合进同一文件，**按完成时间降序排序**（最新在前），任务之间用 `---` 分隔。每个任务块必须含**元数据行**（`> ` 开头，四字段：负责人 / 状态 / 范围 / 完成时间），缺失或不完整时可由 `toolkit tasks normalize --fix` 补齐：
+
+```markdown
+# 20260902 归档
+
+## 20260902-唐启云-忘记密码
+
+> 负责人：唐启云　状态：已完成　范围：app　完成时间：2026-09-02 14:30
+
+# 忘记密码
+（正文）
+
+---
+
+## 20260902-唐启云-其他任务
+
+> 负责人：唐启云　状态：已完成　范围：-　完成时间：2026-09-02 15:00
+
+（正文）
+```
+
+## 4. 归档规则
+
+1. 归档触发是**人工 / 事件驱动**，非定时任务；常见触发时机为任务完成、相关变更提交版本控制之前，此时应先行归档再提交。
+2. **任务级归档**：`status ∈ {已完成, 已放弃}` 且带 `completed` 的任务可归档。
+3. `待办` / `进行中` / `阻塞` 均不归档。
+4. 归档文件按 `completed` 的日期（`YYYYMMDD`）划分。
+5. 归档文件内任务按 `completed` **降序**排序（最新在前，`YYYY-MM-DD HH:mm` 定宽字符串比较即时间序）。
+6. **完成时间口径**：`completed` 只填真实收工时间（四级时间源取证），日期应与归档文件日期一致；不一致属「日期漂移」，`toolkit tasks normalize` 会检出，`--fix` 自动把漂移块迁移到对应日期文件（迁移前可用 `normalize` 只读检查）；归档文件放错月份目录（如 `archive/202608/20260903.md`）时 `--fix` 会将其移动到正确月份目录。⚠️ 补档 / 历史时间修正场景下，归档块的完成时间早于归档动作时间是正常的——修正块时间后执行 `normalize --fix` 即完成迁移。
+7. **疑似任务块**：任务块判定要求标题后首个非空行为含「完成时间」的元数据行；形如 `{年月日}-{负责人}-{简述}` 的 `## ` 标题后跟 `> ` 元数据但缺「完成时间」时，会被视为疑似任务块并在 `normalize` 检出提示人工确认（不自动修复）。
+8. **并发归档防护**：归档采用排他锁（`.archive.lock`），检测到并发归档时跳过并告警；`--dry-run` 可预演归档动作而不落盘。
+
+## 5. 其他语言实现要点
+
+按本规范实现时，需覆盖：
+
+1. **frontmatter 解析**：读取文件顶部 `---` 之间的 `key: value` 行。
+2. **目录遍历**：`active/` 下仅一层年月子目录，收集 `.md` 文件。
+3. **完成时间提取**：从 frontmatter 的 `completed` 字段读取。
+4. **归档合并**：读取已有归档文件的任务块，与新任务合并后按 `completed` 排序，重写归档文件。
+5. **任务块分隔**：归档文件内任务以 `---` + `## ` 为边界，勿将正文内部的 `## ` 小节误判为任务边界。
+6. **敏感信息脱敏（可选）**：如需保护隐私，可在写归档前对正文自由文本做掩码；`owner` 等结构化字段保留原值。
+7. **校验（check）**：校验 active 任务 frontmatter 合法性（status 枚举、completed 必填与格式）、跨文件重名、`depends_on` 依赖存在性与成环、范围字段形态软告警（顿号/逗号/括号）。
+8. **归一化（normalize）**：校验归档块元数据四字段完整性、完成时间与归档日期一致性、降序排序、范围字段形态（顿号/逗号疑似多值分隔可 `--fix` 归一为半角加号，括号疑似注释仅提示人工）；`--fix` 可补齐缺失元数据并重排。