@fxri/toolkit 1.14.7 → 1.15.0

package/package.json

@@ -1,15 +1,24 @@
 {
   "name": "@fxri/toolkit",
-  "version": "1.14.7",
+  "version": "1.15.0",
   "description": "专为多人 + AI 跨项目协作打造：任务管理 + 多语言 CHANGELOG。",
   "license": "MIT",
-  "author": "唐启云 <tqy@fxri.net> (https://fxri.net:444/)",
+  "author": {
+    "name": "唐启云",
+    "email": "tqy@fxri.net",
+    "url": "https://fxri.net:444/"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fxri-net/toolkit.git"
   },
+  "bugs": {
+    "url": "https://github.com/fxri-net/toolkit/issues"
+  },
+  "homepage": "https://fxri-net.github.io/toolkit/",
   "type": "module",
   "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": {
@@ -43,8 +52,12 @@
     "task",
     "changelog",
     "changesets",
-    "i18n"
+    "i18n",
+    "fxri"
   ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
   "dependencies": {
     "@changesets/cli": "^2.31.1",
     "@inquirer/prompts": "^8.7.5",
@@ -63,21 +76,10 @@
     "vitepress": "^1.6.4",
     "vitest": "^4.1.11"
   },
-  "engines": {
-    "node": ">=20.19.0"
-  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
-  "directories": {
-    "doc": "docs"
-  },
-  "types": "./dist/index.d.ts",
-  "bugs": {
-    "url": "https://github.com/fxri-net/toolkit/issues"
-  },
-  "homepage": "https://github.com/fxri-net/toolkit#readme",
   "scripts": {
     "dev": "pnpm build:debug && node ./dist/cli.js",
     "build": "cross-env NODE_ENV=production tsup",

package/skills/README.md

@@ -8,9 +8,10 @@
 
 | 技能 | 版本 | 用途 | 层级 |
 | --- | --- | --- | --- |
-| [fxri-plan-to-task](./fxri-plan-to-task/SKILL.md) | 1.9.5 | 方案落盘：任务分解与纯展示计划表 → 逐仓逐任务建档 → 校验 → 归档 → 任务级规范沉淀（能力终点）；规范载体迁移与升级 | core |
+| [fxri-plan-to-task](./fxri-plan-to-task/SKILL.md) | 1.9.6 | 方案落盘：任务分解与纯展示计划表 → 逐仓逐任务建档 → 校验 → 归档 → 任务级规范沉淀（能力终点）；规范载体迁移与升级 | core |
 | [fxri-release-changelog](./fxri-release-changelog/SKILL.md) | 1.2.4 | changesets 发版与多语言 CHANGELOG 维护 | optional |
 | [fxri-session-recap](./fxri-session-recap/SKILL.md) | 1.6.3 | 会话收尾全量沉淀 + 规范沉淀 / 新会话三层恢复 / 历史任务时间批量修正 | core |
+| [fxri-plan-review](./fxri-plan-review/SKILL.md) | 1.0.0 | 复核已落档任务拆分：输出新增疏漏、建议与修订计划表，按 `无需确认 / 需要确认 / 仅作提示` 落档 | core |
 | [fxri-text-encoding](./fxri-text-encoding/SKILL.md) | 1.2.1 | 文本编码：写脚本 / 配置 / 数据交换文本与跨进程 / 跨机器传递前按「生产者 × 消费者」定字节形态（临时任务同样适用），含非 ASCII 丢失 / 变形、乱码反查与首行报错 | optional |
 
 版本号取自各 SKILL.md 的 frontmatter `metadata.version`（`toolkit skills status` / `skills install` 打印的真源版本），与正文首部版本声明双写一致；层级取自 frontmatter `metadata.tier`（`skills` 模式 `core` 必装不可取消，`package` 模式全部可选、允许零选；`optional` 安装时可选，缺省按 `optional` 处理）。

package/skills/fxri-plan-review/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: fxri-plan-review
+description: 复核已落档的开发计划与任务拆分是否合理，输出新增疏漏、建议与修订计划表。方案已落档或已拆分任务后，用户表达「继续评估 / 再评估一下 / 这些任务合理吗 / 是不是拆得太细或太粗 / 有没有漏掉 / 复核任务 / 重新评估开发计划」等复核意图时使用；被动语义触发为主，显式话术为辅。不用于初次方案讨论、单纯建档 / 归档、会话收尾、发版动作，也不用于评估技术方案性能、依赖版本等非任务集场景；方案尚未落档时只提示先建档。
+license: MIT
+metadata:
+  version: "1.0.0"
+  tier: core
+  author: fxri
+  source: https://github.com/fxri-net/toolkit
+---
+
+# 任务方案复核
+
+> 本技能版本 1.0.0（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
+
+## 何时使用
+
+- 方案已落档、任务已拆分后，用户说「继续评估 / 再评估一下 / 落档，继续评估」；
+- 用户问「这些任务拆分合理吗 / 是不是拆得太细 / 太粗 / 有没有漏掉的地方」；
+- 用户明确说「复核任务 / 审查任务拆分 / 重新评估开发计划」。
+- 触发前提：上下文里已有落档任务或明确的任务清单；方案尚未落档时只提示「先建档再复核」。
+- 不加载：初次方案讨论、单纯建档、单纯归档、会话收尾、发版动作本身，以及「评估技术方案性能 / 依赖版本」等非任务集评估。
+
+## 输入
+
+当前计划、`.tasks/active/` 任务、conventions 载体与仓库规则。复核前先跑 `toolkit tasks check`（不可用则手工核对），结构问题以命令结果为准，语义问题再按清单判断。
+
+## 复核清单
+
+1. 每个任务是否可独立验收、独立回滚、单独提交后仓库自洽。
+2. 是否按用户可感知的交付结果拆分，而不是按文件、步骤或实现层拆分。
+3. 是否存在单组件特例：跨切面能力只落在一个命令或一个技能上。
+4. 是否覆盖全部触达面：命令、技能、来源、文档、变更集、发版。
+5. 任务顺序与依赖是否成立，是否存在下游先于上游。
+6. 是否与 active / archive 既有任务重复。
+7. 任务粒度不等于发版粒度：一次发版可包含多个任务、多个变更集；细则以 `SPEC.md` 与 `task-spec.md` 的显式条款为准。
+8. 哪些规则可以落成 CLI / `pnpm verify` 的自动检查，避免长期靠人工复核。
+
+## 输出
+
+统一为单表，列为「疏漏 / 建议 | 说明 | 默认处置」。默认处置取三个 4 字标签，单独成列、不用括号：
+
+- `无需确认`：安全、可逆、不改用户语义的修正；用户表达明确接受语义（落档 / 开始 / 可以 / 继续 / 都按这个来 / 全部接受）时自动跟随写入；
+- `需要确认`：涉及任务范围、版本、任务合并 / 删除、用户正文语义的改动；先问再写，只有用户逐条确认或明确说「全部接受 / 都落档」时才应用；
+- `仅作提示`：后续增强、超出本次范围的风险与建议；只展示，不写入任务档。
+
+输出纪律：
+
+- 只列**新增**的疏漏与建议；已确认、已落档的内容不重复；没有新增时明确说「无新增疏漏」并停止。
+- 结论为「合理」或「需调整」；无问题时明确输出「未发现需调整项」，不硬凑问题。
+- 建议项不自动拆任务，需用户确认后另行建档。
+- 触发不依赖字面「落档」，以明确接受语义为准；含糊回应（嗯、再说、再看看）不自动落档。
+- 只应用 `无需确认` 项；`需要确认` 逐条问；`仅作提示` 不动；未标记条目一律按 `仅作提示` 处理。
+- 写入前后都列出将被改 / 已改的文件与变更摘要，禁止静默改用户内容。
+
+## 不做
+
+不自动建档、不自动改任务文件、不替代 `fxri-plan-to-task` 的建档与归档流程；落档执行仍由 `fxri-plan-to-task` 完成。
+
+## 参考
+
+- 复核清单、反例与输出模板：`references/review-checklist.md`
+- 该触发 / 不该触发样例：`references/trigger-examples.md`
+- 任务粒度与提交边界：仓库 `SPEC.md`、`fxri-plan-to-task/references/task-spec.md`

package/skills/fxri-plan-review/references/review-checklist.md

@@ -0,0 +1,41 @@
+# 复核清单、反例与输出模板
+
+> 由 `../SKILL.md` 按需加载。任务粒度与提交边界以仓库 `SPEC.md`、`fxri-plan-to-task/references/task-spec.md` 为准，本文件不复制细则。
+
+## 一、复核清单
+
+| 检查项 | 通过标准 | 常见不通过 |
+| --- | --- | --- |
+| 独立交付 | 每个任务可独立验收、独立回滚，单独提交后仓库自洽 | 编码 / 测试 / 文档各建一个任务；拆出的中间态仓库验收不过 |
+| 拆分维度 | 按用户可感知的交付结果拆，不按文件、步骤、实现层拆 | 按 `src/a.ts`、`src/b.ts` 拆；把文档 + 技能 + 变更集从代码任务里拆出 |
+| 单组件特例 | 跨切面能力要么全局覆盖，要么明确只覆盖某范围 | 版本自检只写进一个技能，其他技能没有；新命令只在一条路径提示 |
+| 触达面 | 命令、技能、来源、文档、变更集、发版均有交代 | 只改代码不改文档；只改一个技能漏掉其他技能；漏变更集 |
+| 顺序与依赖 | 前置未完成时下游不开工；串行写在正文「批次 / 前置」行 | 下游任务先于上游；串行依赖被误写成 `depends_on` |
+| 重复 | 与 active / archive 同主题任务有判别结论 | 同主题重复建档；已有归档任务却重新开一条 |
+| 版本范围 | 发版可包含多个任务与多个变更集；任务粒度不约束发版范围 | 把同一版本的能力硬拆到后续版本；或反过来把多个任务攒成一个提交 |
+| 自动化 | 能自动检出的规则指出应落到 `tasks check` / `pnpm verify` | 长期靠人工复核、无检测入口 |
+
+## 二、默认处置判定
+
+- `无需确认`：只改文档措辞、补测试、补一致性断言、补边界说明等安全可逆项；不改用户已确认的范围、版本、任务结构。
+- `需要确认`：改任务范围、改版本号、合并 / 删除任务、改用户正文语义、改变交付顺序。
+- `仅作提示`：后续增强、超出本次版本范围、需要新依赖或新分发机制的建议。
+- 不确定时一律归 `需要确认`；未标记时按 `仅作提示`。
+
+## 三、输出模板
+
+| 疏漏 / 建议 | 说明 | 默认处置 |
+| --- | --- | --- |
+| 示例：任务 2 缺少失败路径测试 | 只覆盖成功分支，建议补 CI 失败用例 | 无需确认 |
+| 示例：是否把能力 A 并入本版本 | 涉及版本范围，需用户拍板 | 需要确认 |
+| 示例：未来支持系统代理 | 需引入代理依赖，超出本次范围 | 仅作提示 |
+
+结论：合理 / 需调整。无新增问题时只输出「未发现需调整项」或「无新增疏漏」。
+
+## 四、落档协议
+
+1. 用户表达明确接受语义（落档 / 开始 / 可以 / 继续 / 都按这个来 / 全部接受）时，应用 `无需确认` 项；只说「开始」不自动应用 `需要确认`。
+2. 用户明确说「全部接受 / 都落档」时才应用 `需要确认` 项。
+3. `仅作提示` 永不写入；未标记项按 `仅作提示`。
+4. 写入前列出将改文件与变更摘要；写入后列出已改文件与未应用项。
+5. 落档执行由 `fxri-plan-to-task` 完成；本技能不直接改任务文件。

package/skills/fxri-plan-review/references/trigger-examples.md

@@ -0,0 +1,21 @@
+# 触发样例
+
+> 供人工回归：被动语义触发为主，显式话术为辅。样例非穷举。
+
+## 该触发
+
+- 「落档了，继续评估」
+- 「这些任务拆分合理吗？」
+- 「是不是拆得太细 / 太粗？」
+- 「有没有漏掉的地方？」
+- 「复核一下任务」
+- 「重新评估开发计划」
+- 用户先明确「全部接受」，随后说「开始」——应用 `无需确认` 项，`需要确认` 仍逐条问
+
+## 不该触发
+
+- 初次方案讨论、还没有任务清单
+- 单纯说「落档」「归档任务」「开始发版」
+- 「评估技术方案性能」「评估依赖版本」
+- 「帮我写个 README」等与任务集无关的请求
+- 含糊回应「嗯」「再说」「再看看」——不自动落档

package/skills/fxri-plan-to-task/SKILL.md

@@ -3,7 +3,7 @@ name: fxri-plan-to-task
 description: 将已确认的实施方案分解为可独立交付的任务并给出计划表，再落盘为标准任务文件并跟踪至归档：建档评估（查 active/archive 判同主题）、按模板建档、状态机更新、四级时间源取证、自查、任务级规范沉淀与归档。方案确认后表达「开始落地/登记记录」的意图，或即将改仓库文件时使用——含任务分解、建档、任务登记、落盘、归档、任务校验、规范载体迁移与升级（conventions 单文件升目录、v1 / v2 升 v3）等说法及口语近义表达（如按这个做吧、记一下、建个任务跟踪）均触发。不用于方案未确认的对话、会话收尾整场沉淀（fxri-session-recap 模式一）、与任务记录无关的普通 TODO、issue 管理或日常提交信息撰写。
 license: MIT
 metadata:
-  version: "1.9.5"
+  version: "1.9.6"
   tier: core
   author: fxri
   source: https://github.com/fxri-net/toolkit
@@ -11,7 +11,7 @@ metadata:
 
 # 方案落盘：任务建档与归档
 
-> 本技能版本 1.9.5（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.9.6（随 @fxri/toolkit 同批分发）。被问版本时即报此值（不读磁盘、不跑 CLI）；与 `toolkit skills status` 的磁盘值不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 
@@ -43,7 +43,7 @@ metadata:
 
 ### 0. 任务分解与展示型计划表（方案确认后、建档前；两个及以上任务才出）
 
-- 先按任务粒度拆解：一个任务 = 可独立验收、可独立回滚、单独提交后仓库自洽的最小交付单元，且不跨仓库（判据、判定顺序与反例见 `references/task-spec.md` 协作约定）
+- 先按任务粒度拆解：一个任务 = 可独立验收、可独立回滚、单独提交后仓库自洽的最小交付单元，且不跨仓库（不约束发版范围；判据、判定顺序与反例见 `references/task-spec.md` 协作约定）
 - 两个及以上任务时，在对话中给出唯一一张顺序计划表：列为「序号 | 仓库 | 任务 | 前置」，跨端、跨仓同表，按执行先后排列；单任务方案不出表
 - 表只作展示与排序：不落档、不写入任务正文、不设状态列（状态以任务 frontmatter 为唯一真源）；计划调整时先更新该表再继续
 - 串行先后写在展示表与各任务正文的「批次 / 计划位置 / 前置」行，不写 `depends_on`（`depends_on` 只用于仍 active 的并行依赖）

package/skills/fxri-plan-to-task/assets/active-task-template.md

@@ -1,13 +1,13 @@
----
-owner: <负责人 git 用户名>
-status: 待办
-created: <创建日 YYYYMMDD>
-updated: <创建日 YYYYMMDD，随每次修改同步>
-completed: ''
-depends_on: []
-scope: <影响范围>
----
-
-# 任务标题
-
-（方案正文：背景、实施方案、影响范围、验证方式）
+---
+owner: <负责人 git 用户名>
+status: 待办
+created: <创建日 YYYYMMDD>
+updated: <创建日 YYYYMMDD，随每次修改同步>
+completed: ''
+depends_on: []
+scope: <影响范围>
+---
+
+# 任务标题
+
+（方案正文：背景、实施方案、影响范围、验证方式）

package/skills/fxri-plan-to-task/references/task-spec.md

@@ -108,7 +108,7 @@ scope: app            # 影响范围；只标本仓内的端 / 面（跨仓库
 - **仓库文件改动口径**：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入）；纯读取、纯执行、纯汇报不计入；拿不准时列出差异问用户，不猜
 - **动作不算，改动才算**：收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档；这些动作过程中若出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误），该修复按普通任务建档
 - **跨仓库改动各自归档（本仓自述）**：任务档是仓库自述，只记本仓的改动与动机；跨仓库是会话属性而非仓库属性，同一会话涉及多仓时各仓各自建档归档，不在一仓记录里承载另一仓的工作痕迹。判据取**视角**（描述的是不是本仓的改动与动机），非词表——依赖包名 / 被调接口名等本仓事实者照写
-- **任务粒度（按序判定）**：一个任务 = 可独立验收、可独立回滚、单独提交后仓库自洽的最小交付单元，且不跨仓库。判定顺序：① 跨仓库必拆——一个任务只属于一个仓库；② 拆出的中间态仓库验收不过则合并回去；③ 写不出一句独立的验收结论则合并；④ 单独回滚会破坏其他交付则合并。常见反例：按文件拆、按步骤拆（编码 / 测试 / 文档各建一档）、把文档 + 技能 + 变更集从代码任务里拆出、按人拆、把重构与依赖它的功能随意拆开。任务数通常不超过 7，超过多半是把步骤当成了任务
+- **任务粒度（按序判定）**：一个任务 = 可独立验收、可独立回滚、单独提交后仓库自洽的最小交付单元，且不跨仓库。判定顺序：① 跨仓库必拆——一个任务只属于一个仓库；② 拆出的中间态仓库验收不过则合并回去；③ 写不出一句独立的验收结论则合并；④ 单独回滚会破坏其他交付则合并。常见反例：按文件拆、按步骤拆（编码 / 测试 / 文档各建一档）、把文档 + 技能 + 变更集从代码任务里拆出、按人拆、把重构与依赖它的功能随意拆开。任务数通常不超过 7，超过多半是把步骤当成了任务。任务粒度只约束任务与提交单元，不约束发版范围；一次发版可包含多个任务与多个变更集，但每个任务仍按逐任务提交
 - **触发建档的改动不含任务区自身**：建档评估与「本次是否产生仓库文件改动」的判别中，`.tasks/` 下的读写不单独构成建档理由（否则建档本身即为改动，形成自证循环）；archive 同主题判别仍按上一条「任务区自身均计入」的完整口径
 - **纯展示开发计划表**：方案确认后、建档前，若涉及两个及以上任务，先在对话中给出唯一一张顺序表，列为「序号 | 仓库 | 任务 | 前置」——跨端、跨仓同表，按执行先后排列；表只作展示与排序，不落档、不写入任务正文、不设状态列（状态以任务 frontmatter 为唯一真源）。单任务方案不出表；计划调整时先更新该表再继续
 - **逐任务交付**：按计划表顺序推进，前置未完成或阻塞未解除时下游不开工；每个任务完成即走完该仓库的「归档 → 验收 → 提交」，不跨任务攒批。一个任务至少一次提交、允许多次；不得把多个任务攒成一个提交，也不得为凑一次提交塞入无关改动