@fxri/toolkit 1.10.4 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # 方弦工具集
 
+## 1.11.0
+
+> 2026-09-27 发布
+
+### ✨ 新增功能
+
+- `toolkit tasks stats` 支持 `--view` / `--status` 过滤（与 `tasks list` 口径一致，`--view` 默认 `all` 含归档），并补齐 `--date` 与 `--since` / `--until` 的互斥校验
+- `toolkit tasks check` 补「`updated` 早于 `created`」与「归档块完成日期与所属月份目录不符」两项校验，并对 BOM、行尾空白、同文件 CRLF/LF 混用给出软告警（只报不改，修复走 `tasks normalize`）
+- 新增 `toolkit conventions` 命令域：`upgrade` 把 v1 规范载体升级为 v2（发稳定 ID `C-<n>`、演进记录切独立 `history.md`、内部引用改稳定 ID），`status` 做只读体检（形态 / 索引 / 入口层三块，只报不改；体检不阻断、退出码恒 0）
+- `upgrade` 幂等、先判后写，异常形态在写盘前拒绝；已为 v2 时返回 `already-v2`；`--dry-run` 可预演
+- 规范载体引入结构 v2：`index.md` 首行为形态标记、索引表首列改为稳定 ID `C-<n>`（去补零、只追加不重排不回收）、演进记录抽为独立 `history.md`（只追加、不改旧行）；v1 三态兼容读取
+- `toolkit init` 生成 v2 载体骨架（`index.md` + `history.md`）与项目级技能入口壳，并逐项报告实际动作（新建 / 保持 / 追加 / 跳过）
+- `toolkit tasks check` 对载体形态异常与技能入口壳给出软告警（壳标记版本不一致、或被 gitignore 覆盖不会随 git 分发）
+- `toolkit tasks check` 增扫 `.changeset/` 下待发布变更集的缺类型前缀条目（逐文件报出缺前缀条数与首条行号），把「变更集缺前缀」的检测前移到归档前；不再等到发版、变更集源被消费删除后才由 changelog 侧兜底告警。前缀识别取全局表与各配置语言自有前缀的并集，缩进续行随父条目迁属、不参与识别
+- `toolkit init` 在检测到尚未安装全局技能时，「下一步」中补一行 `toolkit skills install` 指引（规范触达第一层，不依赖项目内文件；已安装则不重复提示）
+
+### 🔧 功能调整
+
+- `toolkit init` 生成的规范入口壳改为落在**已存在的**项目级技能目录的每一处（多 agent 混用团队各写一份、互不覆盖），一个候选目录都没有时回落 `.agents/skills`；不再为使用者未安装的 agent 凭空创建目录
+- `init` 写入 `AGENTS.md` 的规范入口指针块改为**去路径化**措辞，只描述入口壳形态、不写死具体落点，避免误导只读其他候选技能目录的 agent
+
+### ⚡ 优化改进
+
+- `toolkit changelog format` 由全量重建改为只重组识别到的语义分区——未识别分组标题连同条目原样保留、不臆造归属，不再丢内容；`--history format` 恢复幂等（不再逐次注入空行）
+- `toolkit changelog format` 归类前后做条目数自检，减少即 stderr 告警提示人工核对（归类只应搬移、不应减少）
+- 升级检查前置到提前返回之前，所有子命令路径一致触发，不再有路径漏检
+- 项目无 `AGENTS.md` 时，`init` 的跳过提示补充说明：本项目规范仍可经全局技能 `fxri-plan-to-task` 触达
+- 入口壳告警合并：多落点并存时「壳标记与当前 toolkit 不一致」「壳被 gitignore 覆盖」各只告警一条并内联全部落点路径，不再按壳逐条重复（5 处壳由 10 条降为 2 条）；告警中的落点路径改用**仓库根相对路径**，不再泄露本机绝对路径，与 `check` 其余项口径一致
+- 入口壳版本告警补回定位信息：多落点场景原本文案逐字相同、无路径可定位，现内联各落点的标记版本，`toolkit conventions status` 与 `toolkit tasks check` 文案保持一致
+- `toolkit skills status` 人读输出折叠：全部正常的目标聚合为一行（`<目标>：<目录>　N 项正常`），仅含问题项的目标逐条展开；`--format json` 输出不变、信息不丢
+- 入口壳告警文案中性化：单壳与多壳分支统一为「入口壳标记与当前 toolkit 不一致」（原「落后」措辞在壳标记超前时失真），统一 `标记 v1` / `标记 无` 前缀
+- 入口壳 gitignore 判定由逐壳一次子进程改为一次性批量（`git check-ignore --stdin`），多落点项目的 `toolkit tasks check` 耗时回落
+
+### 🐛 问题修复
+
+- `toolkit tasks export --redact` 改为全部文本列统一脱敏，消除 `任务名` 之外的漏网列
+- `toolkit tasks normalize` 对无法识别完成时间的归档不再落「垃圾路径」，改为告警并跳过该项；`check` / `normalize` 分工在 help 中互相指引（check 只报不修、normalize 负责修）
+- `toolkit skills status` 纳入状态文件登记的目标（不只统计现场目录），软链目标不存在时判为悬空、不再误报 `link-ok`
+- `toolkit skills install --force` 不再把已登记的副本落点翻回软链（冲突解除与落点形态解耦，保留用户既有落点形态）
+- `toolkit skills remove` 回收残留空目录；`skills status` 对软链落点标注「写入将穿透至源目录，改内容请改真源」
+- `toolkit tasks --import` 生成的归档块不再重复 H1，并保留来源 `updated` 字段（缺省时才用当天）
+- `toolkit tasks archive` 同源多落点告警合并为一条；`depends_on` 裸标量按单元素接收、不可解析形态告警（不再静默丢依赖）
+- 未知 `--lang` 值回落默认语言时 stderr 告警，配置项类型不符回落默认值时同样告警（降级不静默）
+- `tasks list` / `tasks stats` 全部 `--status` 取值非法时报错退出（退出码 1），不再静默忽略
+- `tasks archive` / `check` / `normalize` / `stats` 传入不受支持的 `--export`（前三者再传 `--format`）时 stderr 告警忽略、命令继续（降级不静默）
+- 修复技能链接误报与误重指：判定改为「路径不等时比对内容」，链接锚在 pnpm 稳定入口（或另一同内容安装）而内容与真源逐字一致时不再报错，`autoLink` 也不会再把健康链接重指到当前运行源
+- `toolkit init` 重复执行改为按入口壳标记版本分流：标记落后或无标记时就地更新为当前版本（报告为「更新」），标记不旧于当前版本保持不变、不降级覆盖——使告警中「重跑 `toolkit init` 补齐」成为真实可用的修复路径
+- 修复 `toolkit conventions status` 在 @fxri/toolkit 源仓库内误提示「未找到入口壳：执行 toolkit init 可生成」的问题：源仓库本就不生成入口壳（靠 fxri-\* 技能自举），现不再给出补生成建议
+
+## 1.10.5
+
+> 2026-09-21 发布
+
+### 🐛 问题修复
+
+- 技能软链锚点在 pnpm 全局布局下解析失效，升级后链接仍会悬空
+
+  - 稳定入口解析原以「`.pnpm` 所在层目录名为 `node_modules`」为判据，该条件只在项目内安装时成立；pnpm 全局安装下 `.pnpm` 与 `node_modules` 并列（同在 `<pnpm 全局>/<global 段>/` 内），判据恒假 → 解析不出候选而静默回落含版本段的包实体路径，1.10.4 声称的悬空修复对全局安装实际未生效
+  - 改为按目录名判定并补齐 `node_modules` 层：项目内取 `<项目>/node_modules/@fxri/toolkit`，全局取 `<pnpm 全局>/<global 段>/node_modules/@fxri/toolkit`，两种布局都锚在 pnpm 稳定入口（升级时由 pnpm 重写该入口）
+  - 1.10.4 的发布描述与全局安装实际行为不符，建议直接升级至本版，勿停留在 1.10.4
+
 ## 1.10.4
 
 > 2026-09-21 发布

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

@@ -24,7 +24,7 @@ AI 参与开发后，方案与决策散落在对话记录里，会话一关什
 # 1. 项目内安装（推荐，团队共享版本）
 pnpm add -D @fxri/toolkit
 
-# 2. 初始化任务区（生成 .tasks/ 骨架，1.7.0 新增）
+# 2. 初始化任务区（生成 .tasks/ 骨架、conventions/ 规范载体与技能入口壳）
 pnpm exec toolkit init
 
 # 3. 查看任务总览
@@ -39,6 +39,7 @@ pnpm exec toolkit tasks
 | --- | --- | --- |
 | 任务管理（tasks） | 方案落盘、总览过滤、校验归档、导入导出 CSV / XLSX / JSON | [CLI 参考](./docs/cli.md) · [任务文件规范](./docs/guide.md#任务文件规范) |
 | 多语言 CHANGELOG（changelog） | 封装 changesets 发版、分组标题本地化 | [CLI 参考](./docs/cli.md#changelog) |
+| 协作规范载体（conventions） | 把任务里提炼的规范收进 `.tasks/conventions/`，成为可检索、可校验的项目规范源；支持结构升级与只读体检 | [CLI 参考](./docs/cli.md) · [完整攻略](./docs/guide.md#conventions-规范沉淀地) |
 | Node API | 把上述能力嵌进脚本或平台 | [API 参考](./docs/api.md) |
 | 隐私脱敏 | 落盘前自动掩码邮箱、手机号、密钥等 | [配置参考](./docs/config.md) |
 | AI 技能包（skills） | 不装本工具也能让 AI 按同一套规范干活；装了可一键分发技能 | [完整攻略](./docs/guide.md#ai-技能包-skills) · [FAQ](./docs/faq.md#工具和-skills-都得装吗) |
@@ -71,7 +72,7 @@ pnpm dlx skills add fxri-net/toolkit                  # 也可用上游安装器
 
 - [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 扩展）
+- [fxri-session-recap](./skills/fxri-session-recap/SKILL.md)：会话收尾全量沉淀、新会话三层恢复、历史任务时间批量修正（1.7.0 新增技能）
 
 skills 与工具的关系、只在公司项目激活等说明见 [FAQ](./docs/faq.md) 与 [完整攻略](./docs/guide.md#ai-技能包-skills)。
 

package/SPEC.md

@@ -1,6 +1,6 @@
 # 任务文件规范（SPEC）
 
-> 规范更新时间 2026-09-16 13:11。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
+> 规范更新时间 2026-09-26 16:56。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
 
 > 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
 >
@@ -26,12 +26,13 @@
 │   └── {年月}/
 │       └── {年月日}.md        # 某天归档
 └── conventions/               # 项目协作规范载体（可选）：从任务提炼的规范沉淀地，非任务文件
-    ├── index.md               # 唯一入口与唯一权威：端清单 + 每条规范一行指针
+    ├── index.md               # 唯一入口与唯一权威（常驻读）：首行为形态标记；端清单 + 每条规范一行指针（首列为稳定 ID）
+    ├── history.md             # 规范演进记录（只追加、不改旧行；按需读）
     ├── common.md              # 全端通用条文（按需创建）
     └── {端名}.md              # 各端专有条文，端名 = 任务 scope 取值（按需创建）
 ```
 
-`conventions/` 由 AI 协作流程（fxri-plan-to-task 归档时 / fxri-session-recap 收尾时）维护，写入前需用户确认；tasks 命令不读其内容、check 不因内容告警（仅在载体形态异常时软告警）。端名与任务 `scope` 取值共用同一套词表、逐字一致，`index.md` 顶端的端清单是端的唯一权威（不扫目录）；分册按需创建，判据是「该归属下有无需独立承载的条文」。旧版单文件 `conventions.md` 兼容读取，检测到残留时软告警提示迁移。
+`conventions/` 由 AI 协作流程（fxri-plan-to-task 归档时 / fxri-session-recap 收尾时）维护，写入前需用户确认；tasks 命令不读其内容、check 不因内容告警（仅在载体形态异常时软告警）。载体结构分两版：v1（无首行形态标记、索引表首列为序号 `#`、演进记录与索引同文件）与 v2（首行形态标记、索引表首列改为稳定 ID `C-<n>`、演进记录抽独立 `history.md`），v1 存量可用 `toolkit conventions upgrade` 升 v2。端名与任务 `scope` 取值共用同一套词表、逐字一致，`index.md` 顶端的端清单是端的唯一权威（不扫目录）；分册按需创建，判据是「该归属下有无需独立承载的条文」。旧版单文件 `conventions.md` 兼容读取，检测到残留时软告警提示迁移。
 
 ## 2. active 任务文件
 

package/TRADEMARK.md

@@ -1,41 +1,41 @@
-# 商标声明
-
-## 基本信息
-
-| 项目 | 内容 |
-|---|---|
-| 商标名称 | 方弦® |
-| 商标类型 | 文字商标 |
-| 商标说明 | 商标由文字"方弦"组成 |
-| 商标类别 | 第42类（共10项） |
-| 注册号 | 89648411 |
-| 申请人 | 唐启云 |
-| 递交商标局 | 2026-01-12 |
-| 版本 | 基础版 |
-
-## 第42类服务项目
-
-计算机出租；计算机软件设计；为他人研究和开发新产品；计算机软件维护；把有形的数据或文件转换成电子媒体；为他人创建和维护网站；网络服务器出租；提供互联网搜索引擎；托管计算机站（网站）；云计算。
-
-## 权利状态
-
-"方弦®"商标（注册号89648411）已获中国国家知识产权局商标局核准注册，核定使用于第42类上述服务项目，现为注册商标。
-
-## 授权范围
-
-本仓库的开源许可证（MIT License）仅授予代码的使用、修改和分发权利，**不构成对任何商标、服务标记或品牌名称的授权许可**。
-
-任何派生作品、修改版本、商业产品均不得使用"方弦"名称、Logo 或相关标识，除非获得书面授权。
-
-## 使用规范
-
-- 在开源社区讨论、文档引用中提及本项目时，可使用"方弦®"指代本项目名称
-- 未经书面授权，不得在任何商业产品、服务或宣传材料中使用"方弦"标识
-
-## 获取授权
-
-如需将"方弦"商标用于商业用途，请联系：唐启云 <tqy@fxri.net>
-
-## 侵权处理
-
-如发现未经授权使用"方弦®"商标的行为，请通过上述联系方式举报。
+# 商标声明
+
+## 基本信息
+
+| 项目 | 内容 |
+|---|---|
+| 商标名称 | 方弦® |
+| 商标类型 | 文字商标 |
+| 商标说明 | 商标由文字"方弦"组成 |
+| 商标类别 | 第42类（共10项） |
+| 注册号 | 89648411 |
+| 申请人 | 唐启云 |
+| 递交商标局 | 2026-01-12 |
+| 版本 | 基础版 |
+
+## 第42类服务项目
+
+计算机出租；计算机软件设计；为他人研究和开发新产品；计算机软件维护；把有形的数据或文件转换成电子媒体；为他人创建和维护网站；网络服务器出租；提供互联网搜索引擎；托管计算机站（网站）；云计算。
+
+## 权利状态
+
+"方弦®"商标（注册号89648411）已获中国国家知识产权局商标局核准注册，核定使用于第42类上述服务项目，现为注册商标。
+
+## 授权范围
+
+本仓库的开源许可证（MIT License）仅授予代码的使用、修改和分发权利，**不构成对任何商标、服务标记或品牌名称的授权许可**。
+
+任何派生作品、修改版本、商业产品均不得使用"方弦"名称、Logo 或相关标识，除非获得书面授权。
+
+## 使用规范
+
+- 在开源社区讨论、文档引用中提及本项目时，可使用"方弦®"指代本项目名称
+- 未经书面授权，不得在任何商业产品、服务或宣传材料中使用"方弦"标识
+
+## 获取授权
+
+如需将"方弦"商标用于商业用途，请联系：唐启云 <tqy@fxri.net>
+
+## 侵权处理
+
+如发现未经授权使用"方弦®"商标的行为，请通过上述联系方式举报。