@fxri/toolkit 1.10.0 → 1.10.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 方弦工具集
 
+## 1.10.1
+
+> 2026-09-16 发布
+
+### 🔧 功能调整
+
+- 建档同主题判别改用客观口径——判据由主观的「有无增量」改为「本次是否产生仓库文件改动」（需写入版本控制的工作区文件增 / 改 / 删计入，纯读取、纯执行、纯汇报不计入），任何项目、任何人或 AI 均可按同一标准得到同一结论
+- 收尾动作边界明确——提交、发版、推送、部署等收尾动作本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档；这些动作过程中暴露的需改仓库文件才能修复的缺陷按普通任务建档
+- 归档块补「事实更正」唯一例外——归档块仍不可追加新的工作内容，但后续核实推翻原块结论时可在正文末尾追加「修订记录」（保留原结论、不动元数据行、附更正时刻与依据）
+
+### 📝 文档更新
+
+- 同步 `SPEC.md`、`docs/guide.md`、`docs/ai-rules.md`、`AGENTS.md` 与 fxri-plan-to-task / fxri-session-recap / fxri-release-changelog 三技能措辞；规则层锚点随内容变更同批更新
+
 ## 1.10.0
 
 > 2026-09-16 发布

package/SPEC.md

@@ -1,6 +1,6 @@
 # 任务文件规范（SPEC）
 
-> 规范更新时间 2026-09-16 09:52。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
+> 规范更新时间 2026-09-16 13:11。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
 
 > 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
 >
@@ -10,9 +10,9 @@
 
 任务区是**多写者共享**的：同一 `.tasks/` 可能被多人或多个 AI 参与。为避免互相覆盖，归档、归一化修复等工具内部写操作以排他锁（`.archive.lock`）防并发覆盖；人 / AI 的直接编辑遵循「先查后写」约定。约定：
 
-1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；active 已有同主题任务则更新原文件，禁止重复建档。archive 已有同主题任务（已归档完成）时按增量判别：无增量（重复提议）不建档、有增量（延续/扩展）则重新建档并在正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）`、仅修正旧记录错误走历史修正（fxri-session-recap 模式三）不建档。**归档任务不可变**：已归档块是终结记录，不追加新内容，延续需求一律走新任务。
+1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；active 已有同主题任务则更新原文件，禁止重复建档；已分叉成不同范围时问用户（拆新任务 or 合并更新）。archive 已有同主题任务（已归档完成）时按**改动判别**：本次不产生仓库文件改动（重复提议 / 重复执行）则不重复建档，仅提示「同主题任务已归档于 {日期}」；本次产生仓库文件改动（延续 / 扩展 / 重新实现）则重新建档，并在正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）`；仅修正旧记录的时间或内容走历史修正（fxri-session-recap 模式三），不建档。**仓库文件改动口径**：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入），纯读取、纯执行、纯汇报不计入；拿不准时列出差异问用户，不猜。**归档块不可变**：已归档块不追加新的工作内容，延续需求一律走新任务；唯一例外是**事实更正**——后续核实推翻原块结论时，在其正文末尾追加「修订记录」（保留原结论、不动元数据行、附更正时刻与依据）。
 2. **任务唯一键**：`{年月日}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
-3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions 载体），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
+3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions 载体），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。**动作不算，改动才算**：任务 = 已确认的方案 + 它落地的仓库文件改动；收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档，但当这些动作过程中出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误）时，该修复按普通任务建档。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
 4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
 
 ## 1. 目录结构

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fxri/toolkit",
-  "version": "1.10.0",
+  "version": "1.10.1",
   "description": "专为多人 + AI 跨项目协作打造：任务管理 + 多语言 CHANGELOG。",
   "license": "MIT",
   "author": {

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

@@ -3,21 +3,21 @@ name: fxri-plan-to-task
 description: 将已确认的实施方案落盘为标准任务文件并跟踪至归档：动手前建档评估（查 active/archive 判同主题）、按模板建档、状态机更新、四级时间源取证、自查校验、任务级规范沉淀与手工归档。当用户确认方案后表达「开始落地/登记记录」的意图，或即将动手改仓库文件时使用——含建档、任务登记、落盘、归档、任务校验、规范载体迁移（conventions 单文件升目录形态）等说法及其口语近义表达（如按这个做吧、记一下、建个任务跟踪）均触发。不用于方案未确认的对话、会话收尾整场沉淀（fxri-session-recap 模式一）、与任务记录无关的普通 TODO、issue 管理或日常提交信息撰写。
 license: MIT
 metadata:
-  version: "1.2.0"
+  version: "1.3.0"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 方案落盘：任务建档与归档
 
-> 本技能版本 1.2.0（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.3.0（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 
 - 用户确认实施方案后，表达开始落地/登记记录的意图（语义触发，不要求字面一致）：建档 / 任务登记 / 落盘 / 归档 / 任务校验 / 规范载体迁移 / 按这个做吧 / 记一下 / 建个任务跟踪
 - **即将动手改仓库文件前**（方案已确认、准备执行改动）也是本技能适用场景——动手前先做建档评估（见工作流第 1 步），避免跳过建档直接执行
 - 触发前置条件：**方案已确认**。用户说「开始/开工」但方案尚未确认时，先出方案等确认，不建档
-- **何时不使用**：方案未确认的对话；会话收尾的整场沉淀与归档（那是 fxri-session-recap 模式一）；与方案落盘无关的普通 TODO、issue 管理、日历待办、日常提交信息撰写
+- **何时不使用**：方案未确认的对话；会话收尾的整场沉淀与归档（那是 fxri-session-recap 模式一）；收尾动作（提交、发版、推送、部署）本身——动作不算、改动才算（见工作流第 1 步）；与方案落盘无关的普通 TODO、issue 管理、日历待办、日常提交信息撰写
 
 ## 核心约定
 
@@ -46,16 +46,17 @@ metadata:
 - 列出任务目录 `active/` 下全部 `.md`（含一层 `{YYYYMM}/` 月份子目录），并核对 `archive/` 是否已有同主题任务
 - 读 conventions 载体（存在时）：先找 `.tasks/conventions/index.md`，不存在再看旧单文件 `.tasks/conventions.md`（兼容期读取，并在对话中提示可迁移）；常驻只读 `index.md`，再按本任务 `scope` 命中加载 `common` 与端分册（判定见 `references/conventions-spec.md`）；项目协作规范在建档与执行时须遵守；规范载体本身不属于任务，不为其建档
 - **同主题判别表**（建档前必须按此决策）：
-  | 现状 | 增量情况 | 处理 |
+  | 现状 | 本次是否产生仓库文件改动 | 处理 |
   | --- | --- | --- |
   | active 有同主题 | 补充/细化（同需求未完） | **更新原文件**正文，updated 同步，不新建 |
   | active 有同主题 | 已分叉成不同范围 | 问用户：拆新任务 or 合并更新 |
-  | active 无、archive 有（已归档完成） | 无增量（重复提议同一件事） | 提示「同主题任务已归档于 {日期}」，不重复建档，直接执行 |
-  | active 无、archive 有 | 有增量（延续/扩展） | **重新建档**，正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）` |
-  | active 无、archive 有 | 仅修正旧记录的时间/内容 | 走 fxri-session-recap 模式三（历史修正），**不是建档** |
+  | active 无、archive 有（已归档完成） | 否（重复提议 / 重复执行同一件事） | 提示「同主题任务已归档于 {日期}」，不重复建档，直接执行 |
+  | active 无、archive 有 | 是（延续 / 扩展 / 重新实现） | **重新建档**，正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）` |
+  | active 无、archive 有 | 否，仅修正旧记录的时间/内容 | 走 fxri-session-recap 模式三（历史修正），**不是建档** |
   | active 与 archive 均无 | — | **建档后再动手**（硬前置，不建档不许改文件） |
-- **增量判别口径**（不靠感觉）：新方案含原任务中不存在的新需求点/变更点/范围 = 有增量；完全同描述同范围 = 无增量；拿不准 → 列出差异问用户，不猜
-- **归档任务不可变**：已归档块是终结记录，不向其追加新内容（追加会破坏完成时间/范围的可信度）；延续需求一律走新任务
+- **仓库文件改动口径**（客观判据，不靠感觉）：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入）；纯读取、纯执行、纯汇报不计入；拿不准 → 列出差异问用户，不猜
+- **动作不算，改动才算**：收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不作为建档对象；这些动作过程中若出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误），该修复按普通任务建档
+- **归档块不可变**：已归档块不追加新的工作内容（追加新工作内容会破坏完成时间/范围的可信度）；延续需求一律走新任务。唯一例外是**事实更正**：后续核实推翻原块结论时，在其正文末尾追加「修订记录」（保留原结论、不动元数据行、附更正时刻与依据）
 - 任务唯一键：`{年月日}-{用户名}-{任务简述}`；多人对同一需求共用一个文件
 
 ### 2. 建档

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

@@ -98,6 +98,8 @@ scope: app            # 影响范围；多值以半角加号分隔（toolkit+lxg
 ## 6. 协作约定
 
 - 任务区是多写者共享区：先查后写，同一需求共用一个任务文件；建档与执行时遵守 conventions 载体（`.tasks/conventions/index.md`，存在时）中的项目规范，旧单文件 `conventions.md` 亦兼容读取
-- **动手前置建档评估**：涉及仓库文件改动的任务，动手前先查 active/archive 判同主题（完整判别表见 SKILL.md 工作流第 1 步）；active 有同主题则更新原文件，archive 有同主题且无增量则不重复建档
-- **归档任务不可变**：已归档块是终结记录（唯一键 + 完成时间已固定），不向其追加新内容；延续/扩展需求走新任务并标注来源链
+- **动手前置建档评估**：涉及仓库文件改动的任务，动手前先查 active/archive 判同主题（完整判别表见 SKILL.md 工作流第 1 步）；active 有同主题则更新原文件；archive 有同主题且本次不产生仓库文件改动（重复提议 / 重复执行）则不重复建档，本次产生仓库文件改动（延续 / 扩展 / 重新实现）则重新建档并标注来源链
+- **仓库文件改动口径**：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入）；纯读取、纯执行、纯汇报不计入；拿不准时列出差异问用户，不猜
+- **动作不算，改动才算**：收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档；这些动作过程中若出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误），该修复按普通任务建档
+- **归档块不可变**：已归档块是终结记录（唯一键 + 完成时间已固定），不追加新的工作内容；延续 / 扩展需求走新任务并标注来源链。唯一例外是**事实更正**——后续核实推翻原块结论时，在其正文末尾追加「修订记录」（保留原结论、不动元数据行、附更正时刻与依据），与 conventions 载体「废弃不删行」同属留痕优于抹除
 - 强制约束到**沉淀**为止：归档 + 规范沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则；若提交代码，先归档与沉淀、后 git commit，任务记录（归档文件 + conventions 载体）与代码变更落在同一提交

package/skills/fxri-release-changelog/SKILL.md

@@ -3,14 +3,14 @@ name: fxri-release-changelog
 description: 基于 changesets 的发版与多语言 CHANGELOG 维护流程：创建变更集、消费发版、把分组标题与条目转为项目语言风格、清理变更集、打标签发布；无 changesets 的项目提供同格式手工模式。当用户表达发版或记录变更意图——含创建变更集、changeset、发版、version、CHANGELOG 格式化等说法及其口语近义表达（如发一版、出个版本、记一下这次改动、生成更新日志）时使用。⚠️ 注意区分：用户说「提交个版本 / 先提交一版 / commit」通常指 git 提交当前改动（走任务收尾后提交），**不是发版**。不用于日常 commit message 撰写、git 提交操作或与发版无关的文档修改。
 license: MIT
 metadata:
-  version: "1.0.12"
+  version: "1.1.0"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 发版与 CHANGELOG
 
-> 本技能版本 1.0.12（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.1.0（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 
@@ -23,7 +23,9 @@ metadata:
 ## 前置检查
 
 - ⚠️ 发版不是必经步骤：仅在用户明确要求，或用户全局 / 个人 / 项目规则约定时才进入本技能，不主动发版
+- ⚠️ **发版是收尾动作，不是任务**：本技能不为发版本身建档——发版的输入是「已归档的任务改动」，发版过程及其固有产物（版本号、更新日志、标签）不构成任务、不作为建档对象。例外：过程中暴露的、需改仓库文件才能修复的缺陷（打包配置错误、发布渠道错误、版本号冲突）→ 走 fxri-plan-to-task 先建档再改
 - `.tasks/active/` 存在未归档任务 → 先完成归档再发版（任务归档是发版的前置顺序）
+- **覆盖核对**：本次待发布的改动逐项确认已有归档记录；出现「有改动却无归档记录」→ 先补归档（fxri-session-recap 模式一）再发版
 - 项目根存在 `.changeset/` 目录 → 走「changesets 流程」
 - 不存在 → 走「手工模式」（规范见 `references/changelog-format.md`）
 
@@ -50,6 +52,7 @@ metadata:
 | CHANGELOG 出现「- - 条目」双前缀伪影（变更集条目以 `- ` 开头） | `toolkit changelog version/format` 已自动还原为顶层条目；手工模式按 references 规则手动清理 |
 | 条目与仓库既有风格不一致 | 人工润色为项目语言与句式，勿保留机器直译 |
 | 变更集遗漏（发版后才发现功能未记录） | 补建变更集随下次发版；本次在发布说明中人工补充 |
+| 改动已发布却无归档记录（有提交、无任务档） | 先补归档（fxri-session-recap 模式一）再继续发布后续步骤；发版本身不补建档 |
 | 发版后历史块内出现多余空行（`自举一致性` 类零改动用例失败） | 跑 `toolkit changelog --history format` 归一（**必须带 `--history`**，默认模式不动历史块），再补跑一次镜像页同步脚本 |
 
 ## 可选加速（不构成依赖）

package/skills/fxri-session-recap/SKILL.md

@@ -3,14 +3,14 @@ name: fxri-session-recap
 description: 会话收尾的工作记忆沉淀 + 新会话开场恢复 + 历史任务时间修正：收尾时把整场会话的全部任务完整建档归档，按四级时间源还原真实完成时间，沉淀规范进 conventions 载体；新会话开场按三层恢复（全量索引 + active 精读 + 近窗归档）重建现场并核对规范；也可批量修正历史归档时间。当用户表达会话收尾意图（如今天先到这、收个尾、归档本次会话、把结论记下来）、接续意图（如恢复上下文、继续上次、上次做到哪）、或修正历史任务时间时使用。不用于会话中途的常规方案建档（那是 fxri-plan-to-task 的职责）、与工作交接无关的代码技术总结。
 license: MIT
 metadata:
-  version: "1.2.0"
+  version: "1.2.1"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 会话归档、上下文恢复与历史修正
 
-> 本技能版本 1.2.0（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.2.1（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 
@@ -53,7 +53,8 @@ metadata:
 
 - 归档是中间步骤，**规范沉淀才是流程终点**
 - 沉淀时机固定：归档完成后、任何 git 操作前，规范与归档文件同批落盘
-- 提交、发版、推送**不是必经步骤**，是否执行取决于用户全局/个人/项目规则；若提交代码：先归档、后提交，归档文件与代码变更落在同一 git 提交
+- 提交、发版、推送**不是必经步骤**，是否执行取决于用户全局/个人/项目规则；若提交代码：先归档、后提交，归档文件与代码变更落在同一 git 提交
+- **动作不算、改动才算**：收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档；其所依据的改动须有归档记录，缺则补档
 
 ### R3 规范落点：`.tasks/conventions/` 载体（两级沉淀同一载体）
 
@@ -84,7 +85,8 @@ metadata:
 3. **逐条落盘**（先查后写；格式与目录规范见 `../fxri-plan-to-task/references/task-spec.md`；fxri-plan-to-task 未一并安装、该兄弟路径不存在时，改读包内真源——`toolkit skills status` 打印的「技能源」目录下 `fxri-plan-to-task/references/task-spec.md`）：
    - 会话工作有对应任务 → 更新原文件：正文追加结论与决策，时间字段按 R1 校准
    - 无对应任务但有独立成果 → 按 fxri-plan-to-task 规范建档，created 取任务真实创建日
-   - 未尽事项 → 拆独立任务文件（status: 待办），不在正文留游离待办
+   - 未尽事项 → 拆独立任务文件（status: 待办），不在正文留游离待办
+   - 收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不单独成档；其所依据的改动缺归档记录时须补档
 4. **归档**：终结态任务按 task-spec「手工归档步骤」执行（合并归档块 → 降序重排 → 写回 → 删源文件 → 清理空月份目录），或 `toolkit tasks archive` 自动化
 5. **规范沉淀（终点）**：按「规范提炼子流程」执行会话级提炼，写入 conventions 载体
 6. **收尾边界**：沉淀即本技能流程终点。提交、发版、推送不是必经步骤，是否执行取决于用户规则；若提交代码，先归档、后提交，任务归档文件 + conventions 载体与本次代码变更落在**同一个 git 提交**；提交前向用户展示待提交内容供确认