@fxri/toolkit 1.9.1 → 1.9.2

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

@@ -3,13 +3,15 @@ name: fxri-release-changelog
 description: 基于 changesets 的发版与多语言 CHANGELOG 维护流程：创建变更集、消费发版、把分组标题与条目转为项目语言风格、清理变更集、打标签发布；无 changesets 的项目提供同格式手工模式。当用户表达发版或记录变更意图——含创建变更集、changeset、发版、version、CHANGELOG 格式化等说法及其口语近义表达（如发一版、出个版本、记一下这次改动、生成更新日志）时使用。⚠️ 注意区分：用户说「提交个版本 / 先提交一版 / commit」通常指 git 提交当前改动（走任务收尾后提交），**不是发版**。不用于日常 commit message 撰写、git 提交操作或与发版无关的文档修改。
 license: MIT
 metadata:
-  version: "1.0.7"
+  version: "1.0.9"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 发版与 CHANGELOG
 
+> 本技能版本 1.0.9（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+
 ## 何时使用
 
 - 记录变更（创建变更集）、消费变更集发版、格式化 CHANGELOG（语义触发，不要求字面一致）：changeset / 变更集 / 发版 / version / CHANGELOG 格式化 / 发一版 / 出个版本 / 记一下这次改动 / 生成更新日志
@@ -27,9 +29,9 @@ metadata:
 
 ## changesets 流程
 
-1. 记录变更：`npx changeset`（或项目包管理器等价脚本），按影响选 patch / minor / major 并写变更描述
+1. 记录变更：`npx changeset`（或项目包管理器等价脚本）——**变更描述一律以 `类型：` 前缀开头**（如 `新增：` / `修复：` / `优化：`），并按类型选影响级别（重大→major、新增/修改→minor、优化/修复/清理/文档→patch，完整对照见 `references/changelog-format.md`）
 2. 消费发版：`npx changeset version`——自动写版本号与 CHANGELOG
-3. 格式化：按 `references/changelog-format.md` 转换分组标题、润色条目为项目语言风格（中文示例：`### Patch Changes` → `### 🐛 补丁修复`）
+3. 格式化：按 `references/changelog-format.md` 的语义分组规则归类条目、转换分组标题、润色为项目语言风格（中文示例：`### Patch Changes` 下的 `- 修复：xxx` → `### 🐛 问题修复`）；分组维度与 bump 维度正交，条目归组只看类型前缀
 4. 清理：删除已消费的 `.changeset/*.md`
 5. 发布：提交版本与 CHANGELOG 改动 → 打 `vX.Y.Z` 标签 → 按项目渠道发布（如 `npm publish`）
 
@@ -37,13 +39,13 @@ metadata:
 
 ## 手工模式（无 changesets 项目）
 
-版本号与 CHANGELOG 全部手工维护：版本标题、发布日期行、分组标题与条目格式见 `references/changelog-format.md`；多语言三段结构（标题替换映射 / 依赖更新文案 / 发布日期后缀）同文件。
+版本号与 CHANGELOG 全部手工维护：版本标题、发布日期行、分组标题与条目格式见 `references/changelog-format.md`；多语言四段结构（语义分组 / 标题替换映射 / 依赖更新文案 / 发布日期后缀）同文件。
 
 ## 失败模式
 
 | 症状 | 处置 |
 | --- | --- |
-| version 后 CHANGELOG 分组标题仍是英文 | 按 references 的映射表补一次格式化 |
+| version 后 CHANGELOG 分组标题仍是英文 | 按 references 的映射表补一次格式化 |
 | CHANGELOG 出现「- - 条目」双前缀伪影（变更集条目以 `- ` 开头） | `toolkit changelog version/format` 已自动还原为顶层条目；手工模式按 references 规则手动清理 |
 | 条目与仓库既有风格不一致 | 人工润色为项目语言与句式，勿保留机器直译 |
 | 变更集遗漏（发版后才发现功能未记录） | 补建变更集随下次发版；本次在发布说明中人工补充 |
@@ -55,5 +57,5 @@ metadata:
 - `toolkit changelog`：创建变更集（等价 changeset）
 - `toolkit changelog version`：发版并自动做中文分组标题格式化
 - `toolkit changelog format`：仅格式化既有 CHANGELOG
-- `toolkit changelog --lang <语言> …`：切换输出语言（内置 zh / en，其余可配置扩展）
-- `toolkit skills install` / `toolkit skills status`：把本包 fxri-* 技能分发到各 agent 全局技能目录 / 查看链接与副本现场（技能与 CLI 同源同版本）
+- `toolkit changelog --lang <语言> …`：切换输出语言（内置 zh / en，其余可配置扩展）
+- `toolkit skills install` / `toolkit skills status`：把本包 fxri-* 技能分发到各 agent 全局技能目录 / 查看链接与副本现场（技能随包同源分发，与 CLI 同一发布批次；技能内容版本独立编号，`skills status` 会打印各技能真源版本）

package/skills/fxri-release-changelog/references/changelog-format.md

@@ -1,42 +1,68 @@
-# CHANGELOG 格式规范
-
-## 1. 文件结构（中文示例）
-
-```markdown
-## 1.5.3
-
-> 2026-09-03 发布
-
-### 🐛 补丁修复
-
-- 修复 xxx：……
-```
-
-规则：
-
-- 版本标题 `## {版本号}`；隔一行后接引用行 `> {YYYY-MM-DD} 发布`（标题与日期行之间保留一个空行）
-- 分组标题 = emoji + 组名，一行一组，按 major → minor → patch 顺序
-- 条目一行一条，项目语言句式（中文条目句末不加句号），与仓库既有风格一致
-- ⚠️ 变更集条目以 `- ` 开头时，changesets 会写入 `- - 条目` 首行并把后续行缩进 2 空格（伪影）；`toolkit changelog version/format` 会自动还原为顶层条目，手工模式需手动清理
-
-## 2. 分组标题映射（zh 内置）
-
-| 源标题（changesets 输出） | 目标标题 |
-| --- | --- |
-| `### Major Changes` | `### 🚨 重大变更` |
-| `### Minor Changes` | `### ✨ 新增功能` |
-| `### Patch Changes` | `### 🐛 补丁修复` |
-| `### Dependent Changes` | `### 🔗 依赖变更` |
-| `- Updated dependencies` | `- 更新依赖` |
-
-英文基准分组：`### Major Changes` / `### Minor Changes` / `### Patch Changes` / `### Dependent Changes`。
-
-## 3. 多语言扩展
-
-每种语言约定三段结构：
-
-- `replacements`：源标题 → 目标标题映射表（覆盖分组标题与依赖条目）
-- `deps`：依赖更新条目固定文案
-- `released`：发布日期行后缀（中文为「发布」，英文为「released」）
-
-新增语言时先补全三段，再按映射转换标题、润色条目。
+# CHANGELOG 格式规范
+
+## 1. 文件结构（中文示例）
+
+```markdown
+## 1.5.3
+
+> 2026-09-03 发布
+
+### 🐛 问题修复
+
+- 修复xxx：……
+
+### 📦 其他变更
+
+- 补齐某处兜底逻辑
+```
+
+规则：
+
+- 版本标题 `## {版本号}`；隔一行后接引用行 `> {YYYY-MM-DD} 发布`（标题与日期行之间保留一个空行）
+- 分组标题 = emoji + 组名，一行一组，按**语义分组顺序**输出——重大变更 → 新增功能 → 功能调整 → 优化改进 → 问题修复 → 文档更新 → 清理移除 → 依赖变更 → 其他变更；空组省略
+- 条目一行一条，项目语言句式（中文条目句末不加句号），与仓库既有风格一致
+- ⚠️ 变更集条目以 `- ` 开头时，changesets 会写入 `- - 条目` 首行并把后续行缩进 2 空格（伪影）；`toolkit changelog version/format` 会自动还原为顶层条目，手工模式需手动清理
+- 分组标题集合随版本演进而变化；**历史版本块保留当时口径，`toolkit changelog format` 不追溯改写**（只归类 changesets 本次新写入的英文源标题块）
+
+## 2. 语义分组归类
+
+分组维度（条目**变更类型**）与版本号维度（bump）正交：条目归入哪一组，只看条目自带的**类型前缀**，与它来自 `Major/Minor/Patch Changes` 哪一块无关。
+
+**类型前缀 → 语义槽位**（全局一份、全语言共用，故任一语言的条目在任何输出语言下都能正确归组）：
+
+| 类型前缀（中 / 英） | 语义槽位 | zh 组标题 | en 组标题 |
+| --- | --- | --- | --- |
+| `重大：` / `Breaking:` | `breaking` | `### 🚨 重大变更` | `### 🚨 Breaking Changes` |
+| `新增：` / `Added:` | `added` | `### ✨ 新增功能` | `### ✨ Added` |
+| `修改：` / `Changed:` | `changed` | `### 🔧 功能调整` | `### 🔧 Changed` |
+| `优化：` / `Improved:` | `improved` | `### ⚡ 优化改进` | `### ⚡ Improved` |
+| `修复：` / `Fixed:` | `fixed` | `### 🐛 问题修复` | `### 🐛 Fixed` |
+| `文档：` / `Docs:` | `docs` | `### 📝 文档更新` | `### 📝 Docs` |
+| `清理：` / `Removed:` | `removed` | `### 🧹 清理移除` | `### 🧹 Removed` |
+| 源文本 `- Updated dependencies` | `deps` | `### 🔗 依赖变更` | `### 🔗 Dependency Updates` |
+| 无前缀兜底 | `other` | `### 📦 其他变更` | `### 📦 Other` |
+
+**无前缀条目的兜底规则**：按条目**所属源组标题**声明的影响级别归组——`### Major Changes` → `breaking`、`### Minor Changes` → `added`、`### Patch Changes` → `other`；不从版本号推导。
+
+**依赖条目不走前缀解析**：源组标题 `### Dependent Changes` 整块，以及源文本 `- Updated dependencies`（含缩进子项）一律归入 `deps` 槽位。
+
+同一槽位来自多个源块时合并为单组，组内保持条目原出现顺序；缩进续行随父条目整体迁移。
+
+**类型 → 建议 bump**（撰写变更集时按此选影响级别）：
+
+| 类型前缀 | 建议 bump |
+| --- | --- |
+| `重大：` | major |
+| `新增：` / `修改：` | minor |
+| `优化：` / `修复：` / `清理：` / `文档：` | patch |
+
+## 3. 多语言扩展
+
+每种语言约定四段结构：
+
+- `groups`（可选）：语义分组表，每项 `{ slot, title, prefixes? }`——`slot` 取自全局语义槽位，`title` 为本语言组标题，`prefixes` 为本语言自有前缀（可选，识别时与全局前缀表取并集）；缺省时退化为纯替换（仅 `replacements` 生效）
+- `replacements`：兜底替换映射表（源标题 → 目标标题）
+- `deps`：依赖更新条目固定文案
+- `released`：发布日期行后缀（中文为「发布」，英文为「released」；同时用于识别既有日期行，故自定义语言填非「发布/released」值也能幂等）
+
+新增语言时先补全四段，再按映射转换标题、润色条目。

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

@@ -1,131 +1,133 @@
----
-name: fxri-session-recap
-description: 会话收尾的工作记忆沉淀 + 新会话开场恢复 + 历史任务时间修正：收尾时把整场会话的全部任务完整建档归档，按四级时间源还原真实完成时间，沉淀规范进 conventions.md；新会话开场按三层恢复（全量索引 + active 精读 + 近窗归档）重建现场并核对规范；也可批量修正历史归档时间。当用户表达会话收尾意图（如今天先到这、收个尾、归档本次会话、把结论记下来）、接续意图（如恢复上下文、继续上次、上次做到哪）、或修正历史任务时间时使用。不用于会话中途的常规方案建档（那是 fxri-plan-to-task 的职责）、与工作交接无关的代码技术总结。
-license: MIT
-metadata:
-  version: "1.1.1"
-  author: fxri
-  source: https://github.com/fxri-net/toolkit
----
-
-# 会话归档、上下文恢复与历史修正
-
-## 何时使用
-
-- **沉淀模式（模式一）**：会话接近尾声，用户表达收尾意图——「今天先到这 / 收个尾 / 先这样吧 / 把结论记下来 / 归档本次会话 / 总结本次」，或其近义表达（不要求字面一致）
-- **恢复模式（模式二）**：新会话开场，用户表达接续意图——「恢复上下文 / 继续上次 / 上次做到哪了 / 接着上次的干」，或其近义表达
-- **修正模式（模式三）**：用户发现历史任务时间不准，要批量修正——「修正历史任务时间 / 历史归档时间不对」
-- ⚠️ 触发识别靠语义不靠字面：用户说「收个尾」可能指收尾工作也可能指会话收尾，需结合上下文判断；无法判断时向用户确认，不猜
-
-**何时不使用**：会话中途的常规方案建档与归档（fxri-plan-to-task）；对某段代码的技术总结（与会话交接无关，不落 .tasks）；日常对话。
-
-## 能力边界
-
-- 所有 agent 的共性约束：新会话读不到其他会话的内部上下文，对话记录本身不可跨会话传递
-- 本技能解法是把记忆**沉淀进仓库文件**（`.tasks/`）；个别 agent 可直读历史会话转录，属非通用高级路径，不依赖
-- 本技能**不直接执行 git 提交**：归档 + 沉淀即流程终点，提交/推送/发版由用户全局规则决定（见「收尾边界」）
-
-## 核心规则（先读这段）
-
-### R1 四级时间源（沉淀一切时间字段的唯一口径）
-
-「会话当时的真实时间」不可凭空估算。任何时间字段（created/completed/updated）按以下优先级取证：
-
-| 级 | 时间源 | 取证 | 适用 |
-| --- | --- | --- | --- |
-| 0 | 任务完成当场打点 | 任务完成时立即执行命令取时间（Windows `Get-Date -Format "yyyy-MM-dd HH:mm"`，macOS/Linux `date "+%Y-%m-%d %H:%M"`） | 会话内即时归档（首选，源头消灭补记） |
-| 1 | 聊天记录可见的准确时间戳 | 用户贴过的日志/终端输出时间戳、用户口述的确定时刻 | 收尾补档且上下文有可信时间 |
-| 2 | 任务改动的 git 提交时间 | `git log --format="%h %ci" <file>` 按提交时间取证 | 任务有对应提交 |
-| 3 | 系统当前时间兜底 | 当场执行命令取时，**正文标注「时间为收尾补记」** | 前三级皆不可得 |
-
-规则：
-- 第 3 级是兜底不是默认——能用前三级必须用；用第 3 级必须显式标注，避免「看似精确实则编造」的时间
-- 归档块完成时间可以早于归档动作时间，这是特性不是异常（补档/历史修正场景）
-- 完成时间晚于当前系统时间或恰为零点整会被 CLI 告警，说明时间源取错，需重新取证
-
-### R2 统一收尾链路（能力终点 = 沉淀）
-
-```
-任务终结 → 归档 → 规范沉淀（硬终点） → 提交/发版/推送（可选，需用户确认）
-```
-
-- 归档是中间步骤，**规范沉淀才是流程终点**
-- 沉淀时机固定：归档完成后、任何 git 操作前，规范与归档文件同批落盘
-- 提交、发版、推送**不是必经步骤**，是否执行取决于用户全局/个人/项目规则；若提交代码：先归档、后提交，归档文件与代码变更落在同一 git 提交
-
-### R3 规范落点：`.tasks/conventions.md`（两级沉淀同一文件）
-
-- 唯一落点 `conventions.md`（`.tasks/` 根层，纯 Markdown 随 git 走）；每条规范带来源任务与日期，可审计
-- **任务级**（fxri-plan-to-task 归档时）：单任务产出可升格规范才追加，无则完全静默
-- **会话级**（本技能收尾时）：聚合全会话候选，与已有规范**合并去重**——跨任务重复模式在此补，用户明示规则兜底
-- 写前**必须用户确认**；同义规范不重复记录，只补差异或合并增强
-- 一次性决策留在任务正文，不进规范（升格标准：重复出现 ≥2 次，或用户明示「以后都要这样」）
-
-### 规范提炼子流程（三模式共用）
-
-1. 对照 conventions.md 收集候选：会话中用户明示的规则、与已有规范重复印证的决策、跨任务重复模式
-2. 输出候选清单（每条含来源任务与建议），交用户确认
-3. 用户确认后写入 conventions.md（按现有条目归组，带 `来源：{任务文件}` 标注）
-4. 无候选时完全静默，不强加流程
-
-## 模式一：沉淀本次会话
-
-> 目标：会话结束后，任何人（或新会话 AI）只看仓库就能还原本次做了什么、为什么、还剩什么，且时间与会话真实发生时刻一致。
-
-1. **全量回放**：按时间线完整回放本会话，产出**全部任务候选清单**（含结论、决策及理由、代码改动、未尽事项、用户明示要求记录的内容；与工作产出无关的闲聊不记）。⚠️ 决策及其理由必须记——决策散在对话里，会话一关就丢
-2. **事前核对（新增，防漏档的关口）**：把任务候选清单（每条附时间证据来源：0/1/2/3 级）**先输出给用户确认无遗漏**，确认后才开始落盘——用户切会话漏档的痛点在结构上解决
-3. **逐条落盘**（先查后写；格式与目录规范见 `../fxri-plan-to-task/references/task-spec.md`，技能独立安装时按仓库根 SPEC.md）：
-   - 会话工作有对应任务 → 更新原文件：正文追加结论与决策，时间字段按 R1 校准
-   - 无对应任务但有独立成果 → 按 fxri-plan-to-task 规范建档，created 取任务真实创建日
-   - 未尽事项 → 拆独立任务文件（status: 待办），不在正文留游离待办
-4. **归档**：终结态任务按 task-spec「手工归档步骤」执行（合并归档块 → 降序重排 → 写回 → 删源文件 → 清理空月份目录），或 `toolkit tasks archive` 自动化
-5. **规范沉淀（终点）**：按「规范提炼子流程」执行会话级提炼，写入 conventions.md
-6. **收尾边界**：沉淀即本技能流程终点。提交、发版、推送不是必经步骤，是否执行取决于用户规则；若提交代码，先归档、后提交，任务归档文件 + conventions.md 与本次代码变更落在**同一个 git 提交**；提交前向用户展示待提交内容供确认
-7. **回报**：向用户列出本次沉淀的任务清单、归档位置与规范变更，确认无遗漏后再结束
-
-## 模式二：恢复上下文
-
-> 目标：新会话快速重建现场。恢复范围覆盖全部任务（含已归档），但按层级控制上下文成本。
-
-1. **L0 全量索引**：`toolkit tasks --view all`（无 CLI 时读目录）——active 全部 + archived 全部历史一行一条 + `toolkit tasks stats` 周期统计；一眼看清全貌，不漏任何历史任务
-2. **L1 工作层精读**：逐文件读 `.tasks/active/` 全部任务（决策、进展、阻塞）。⚠️ **搁置识别**：active 任务 `updated` 距今 >1 年时标注「疑似搁置（距今 X 年）」，建议用户确认收尾或放弃，不当「进行中」呈现
-3. **L2 近窗精读**：读最近归档。**近窗按时间连续性判定，不按数量**：先定位最新归档块的完成时间，只精读从该时刻向前连续活跃的归档（归档月份 ≤ 6 个月或归档块 ≤ 200 条时精读全文）；**被 ≥1 年空洞隔断的旧归档一律只入 L0 索引，不精读、不列为「最近完成」**；超阈值降级为统计（按月/负责人汇总 + 近期明细），防止历史膨胀撑爆上下文
-4. **按需拉取**：更早历史（含空洞隔断的旧归档）不主动展开，在 L0 索引可见；用户点名、或 AI 判断相关时用 `--owner`/`--date` 过滤检索；用户明确说「全部恢复」才全量列出
-5. **规范核对与提炼**：读 conventions.md（存在时）纳入现场；对照近期任务按「规范提炼子流程」提议增改——⚠️ 恢复主体只读，写 conventions.md 是用户确认后的独立动作
-6. **输出**：全部任务索引摘要 → 进行中/阻塞任务（含搁置标注）→ 最近完成（连续活跃期内，不含空洞旧档）→ 未完事项 → 规范现场 → **建议的下一步**
-7. 全程不写任务区文件；对存疑内容向用户确认后再动
-
-## 模式三：批量修正历史任务时间
-
-> 目标：旧规则沉淀的归档时间与真实发生时刻不符时批量修正。识别靠证据，CLI 只做结构迁移不推断时间。
-
-1. **取证**：对照 git log（`git log --format="%h %ci"`）与聊天记录时间戳，列出疑似错时任务清单，每条附证据（属于 R1 哪一级）
-2. **确认**：清单交用户逐条确认正确时间，不自行推断
-3. **改值**：active 任务直接改文件 completed；已归档任务改归档块元数据行的完成时间
-4. **迁移核验**：`toolkit tasks normalize --fix` 自动把改动后的归档块迁移到正确日期文件（已完成能力：按 completed 合并降序、清理空文件空目录）；再 `toolkit tasks normalize` 只读核验 0 漂移
-5. **规范观察**：批量回读历史任务时发现的重复模式，按「规范提炼子流程」列为候选（确认后写入，与修正动作同批）
-6. **收尾边界**：同上（沉淀终点，提交可选需确认）
-
-## 失败模式
-
-| 症状 | 处置 |
-| --- | --- |
-| 会话收尾时多个任务混在一起说不清 | 按任务逐条对应拆开写；对应不上的问用户 |
-| 未尽事项塞进已完成任务正文 | 必须拆独立任务，保持已完成任务归档块干净 |
-| completed 填了收尾时刻而非真实完成时刻 | 按 R1 四级时间源重新取证（git log / 聊天记录时间戳） |
-| 恢复时 active 有游离文件（不在月份目录） | 先按规范移入 `active/{YYYYMM}/` 再读 |
-| 归档历史量太大撑爆上下文 | 走 L2 降级：只出统计 + 近期明细，按需拉取更早 |
-| 新会话仍说「找不到上下文」 | 先查磁盘文件是否存在、是否落在正确月份目录、conventions.md 是否同目录；跨环境场景（换机 / 工作区被 git 清理）才需查是否已 git 提交 |
-| 归档未提交，新会话能恢复吗 | 同机同目录**能恢复**（恢复读磁盘 `.tasks/` 文件，与提交状态无关）；仅跨环境（换机 / checkout、clean 清掉工作区）时未提交内容会丢，恢复才依赖提交 |
-
-## 可选加速（不构成依赖）
-
-⚠️ 工具探测顺序（先项目内、后全局）：先 `pnpm exec toolkit --help`（项目 devDependency，npm 项目等价 `npx toolkit`），失败再 `toolkit --help`（全局安装）；两者都不可用即工具未安装，按各步手工继续，**不安装、不阻塞**。探测成功后用对应前缀执行下列命令：
-
-- `toolkit tasks`：模式二 L0 全量索引（替代人工翻目录）
-- `toolkit tasks stats`：模式二周期统计
-- `toolkit tasks archive`：模式一第 4 步自动化（含排他锁防并发；可 `--dry-run` 预演）
-- `toolkit tasks normalize`：模式三迁移核验（`--fix` 迁移 / 只读检查）
-- `toolkit tasks check`：落盘后校验
-- 任务目录非默认 `.tasks` 时加 `--dir <path>`
-- `toolkit skills install` / `toolkit skills status`：把本包 fxri-* 技能分发到各 agent 全局技能目录 / 查看链接与副本现场（技能与 CLI 同源同版本）
+---
+name: fxri-session-recap
+description: 会话收尾的工作记忆沉淀 + 新会话开场恢复 + 历史任务时间修正：收尾时把整场会话的全部任务完整建档归档，按四级时间源还原真实完成时间，沉淀规范进 conventions.md；新会话开场按三层恢复（全量索引 + active 精读 + 近窗归档）重建现场并核对规范；也可批量修正历史归档时间。当用户表达会话收尾意图（如今天先到这、收个尾、归档本次会话、把结论记下来）、接续意图（如恢复上下文、继续上次、上次做到哪）、或修正历史任务时间时使用。不用于会话中途的常规方案建档（那是 fxri-plan-to-task 的职责）、与工作交接无关的代码技术总结。
+license: MIT
+metadata:
+  version: "1.1.2"
+  author: fxri
+  source: https://github.com/fxri-net/toolkit
+---
+
+# 会话归档、上下文恢复与历史修正
+
+> 本技能版本 1.1.2（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+
+## 何时使用
+
+- **沉淀模式（模式一）**：会话接近尾声，用户表达收尾意图——「今天先到这 / 收个尾 / 先这样吧 / 把结论记下来 / 归档本次会话 / 总结本次」，或其近义表达（不要求字面一致）
+- **恢复模式（模式二）**：新会话开场，用户表达接续意图——「恢复上下文 / 继续上次 / 上次做到哪了 / 接着上次的干」，或其近义表达
+- **修正模式（模式三）**：用户发现历史任务时间不准，要批量修正——「修正历史任务时间 / 历史归档时间不对」
+- ⚠️ 触发识别靠语义不靠字面：用户说「收个尾」可能指收尾工作也可能指会话收尾，需结合上下文判断；无法判断时向用户确认，不猜
+
+**何时不使用**：会话中途的常规方案建档与归档（fxri-plan-to-task）；对某段代码的技术总结（与会话交接无关，不落 .tasks）；日常对话。
+
+## 能力边界
+
+- 所有 agent 的共性约束：新会话读不到其他会话的内部上下文，对话记录本身不可跨会话传递
+- 本技能解法是把记忆**沉淀进仓库文件**（`.tasks/`）；个别 agent 可直读历史会话转录，属非通用高级路径，不依赖
+- 本技能**不直接执行 git 提交**：归档 + 沉淀即流程终点，提交/推送/发版由用户全局规则决定（见「收尾边界」）
+
+## 核心规则（先读这段）
+
+### R1 四级时间源（沉淀一切时间字段的唯一口径）
+
+「会话当时的真实时间」不可凭空估算。任何时间字段（created/completed/updated）按以下优先级取证：
+
+| 级 | 时间源 | 取证 | 适用 |
+| --- | --- | --- | --- |
+| 0 | 任务完成当场打点 | 任务完成时立即执行命令取时间（Windows `Get-Date -Format "yyyy-MM-dd HH:mm"`，macOS/Linux `date "+%Y-%m-%d %H:%M"`） | 会话内即时归档（首选，源头消灭补记） |
+| 1 | 聊天记录可见的准确时间戳 | 用户贴过的日志/终端输出时间戳、用户口述的确定时刻 | 收尾补档且上下文有可信时间 |
+| 2 | 任务改动的 git 提交时间 | `git log --format="%h %ci" <file>` 按提交时间取证 | 任务有对应提交 |
+| 3 | 系统当前时间兜底 | 当场执行命令取时，**正文标注「时间为收尾补记」** | 前三级皆不可得 |
+
+规则：
+- 第 3 级是兜底不是默认——能用前三级必须用；用第 3 级必须显式标注，避免「看似精确实则编造」的时间
+- 归档块完成时间可以早于归档动作时间，这是特性不是异常（补档/历史修正场景）
+- 完成时间晚于当前系统时间或恰为零点整会被 CLI 告警，说明时间源取错，需重新取证
+
+### R2 统一收尾链路（能力终点 = 沉淀）
+
+```
+任务终结 → 归档 → 规范沉淀（硬终点） → 提交/发版/推送（可选，需用户确认）
+```
+
+- 归档是中间步骤，**规范沉淀才是流程终点**
+- 沉淀时机固定：归档完成后、任何 git 操作前，规范与归档文件同批落盘
+- 提交、发版、推送**不是必经步骤**，是否执行取决于用户全局/个人/项目规则；若提交代码：先归档、后提交，归档文件与代码变更落在同一 git 提交
+
+### R3 规范落点：`.tasks/conventions.md`（两级沉淀同一文件）
+
+- 唯一落点 `conventions.md`（`.tasks/` 根层，纯 Markdown 随 git 走）；每条规范带来源任务与日期，可审计
+- **任务级**（fxri-plan-to-task 归档时）：单任务产出可升格规范才追加，无则完全静默
+- **会话级**（本技能收尾时）：聚合全会话候选，与已有规范**合并去重**——跨任务重复模式在此补，用户明示规则兜底
+- 写前**必须用户确认**；同义规范不重复记录，只补差异或合并增强
+- 一次性决策留在任务正文，不进规范（升格标准：重复出现 ≥2 次，或用户明示「以后都要这样」）
+
+### 规范提炼子流程（三模式共用）
+
+1. 对照 conventions.md 收集候选：会话中用户明示的规则、与已有规范重复印证的决策、跨任务重复模式
+2. 输出候选清单（每条含来源任务与建议），交用户确认
+3. 用户确认后写入 conventions.md（按现有条目归组，带 `来源：{任务文件}` 标注）
+4. 无候选时完全静默，不强加流程
+
+## 模式一：沉淀本次会话
+
+> 目标：会话结束后，任何人（或新会话 AI）只看仓库就能还原本次做了什么、为什么、还剩什么，且时间与会话真实发生时刻一致。
+
+1. **全量回放**：按时间线完整回放本会话，产出**全部任务候选清单**（含结论、决策及理由、代码改动、未尽事项、用户明示要求记录的内容；与工作产出无关的闲聊不记）。⚠️ 决策及其理由必须记——决策散在对话里，会话一关就丢
+2. **事前核对（新增，防漏档的关口）**：把任务候选清单（每条附时间证据来源：0/1/2/3 级）**先输出给用户确认无遗漏**，确认后才开始落盘——用户切会话漏档的痛点在结构上解决
+3. **逐条落盘**（先查后写；格式与目录规范见 `../fxri-plan-to-task/references/task-spec.md`，技能独立安装时按仓库根 SPEC.md）：
+   - 会话工作有对应任务 → 更新原文件：正文追加结论与决策，时间字段按 R1 校准
+   - 无对应任务但有独立成果 → 按 fxri-plan-to-task 规范建档，created 取任务真实创建日
+   - 未尽事项 → 拆独立任务文件（status: 待办），不在正文留游离待办
+4. **归档**：终结态任务按 task-spec「手工归档步骤」执行（合并归档块 → 降序重排 → 写回 → 删源文件 → 清理空月份目录），或 `toolkit tasks archive` 自动化
+5. **规范沉淀（终点）**：按「规范提炼子流程」执行会话级提炼，写入 conventions.md
+6. **收尾边界**：沉淀即本技能流程终点。提交、发版、推送不是必经步骤，是否执行取决于用户规则；若提交代码，先归档、后提交，任务归档文件 + conventions.md 与本次代码变更落在**同一个 git 提交**；提交前向用户展示待提交内容供确认
+7. **回报**：向用户列出本次沉淀的任务清单、归档位置与规范变更，确认无遗漏后再结束
+
+## 模式二：恢复上下文
+
+> 目标：新会话快速重建现场。恢复范围覆盖全部任务（含已归档），但按层级控制上下文成本。
+
+1. **L0 全量索引**：`toolkit tasks --view all`（无 CLI 时读目录）——active 全部 + archived 全部历史一行一条 + `toolkit tasks stats` 周期统计；一眼看清全貌，不漏任何历史任务
+2. **L1 工作层精读**：逐文件读 `.tasks/active/` 全部任务（决策、进展、阻塞）。⚠️ **搁置识别**：active 任务 `updated` 距今 >1 年时标注「疑似搁置（距今 X 年）」，建议用户确认收尾或放弃，不当「进行中」呈现
+3. **L2 近窗精读**：读最近归档。**近窗按时间连续性判定，不按数量**：先定位最新归档块的完成时间，只精读从该时刻向前连续活跃的归档（归档月份 ≤ 6 个月或归档块 ≤ 200 条时精读全文）；**被 ≥1 年空洞隔断的旧归档一律只入 L0 索引，不精读、不列为「最近完成」**；超阈值降级为统计（按月/负责人汇总 + 近期明细），防止历史膨胀撑爆上下文
+4. **按需拉取**：更早历史（含空洞隔断的旧归档）不主动展开，在 L0 索引可见；用户点名、或 AI 判断相关时用 `--owner`/`--date` 过滤检索；用户明确说「全部恢复」才全量列出
+5. **规范核对与提炼**：读 conventions.md（存在时）纳入现场；对照近期任务按「规范提炼子流程」提议增改——⚠️ 恢复主体只读，写 conventions.md 是用户确认后的独立动作
+6. **输出**：全部任务索引摘要 → 进行中/阻塞任务（含搁置标注）→ 最近完成（连续活跃期内，不含空洞旧档）→ 未完事项 → 规范现场 → **建议的下一步**
+7. 全程不写任务区文件；对存疑内容向用户确认后再动
+
+## 模式三：批量修正历史任务时间
+
+> 目标：旧规则沉淀的归档时间与真实发生时刻不符时批量修正。识别靠证据，CLI 只做结构迁移不推断时间。
+
+1. **取证**：对照 git log（`git log --format="%h %ci"`）与聊天记录时间戳，列出疑似错时任务清单，每条附证据（属于 R1 哪一级）
+2. **确认**：清单交用户逐条确认正确时间，不自行推断
+3. **改值**：active 任务直接改文件 completed；已归档任务改归档块元数据行的完成时间
+4. **迁移核验**：`toolkit tasks normalize --fix` 自动把改动后的归档块迁移到正确日期文件（已完成能力：按 completed 合并降序、清理空文件空目录）；再 `toolkit tasks normalize` 只读核验 0 漂移
+5. **规范观察**：批量回读历史任务时发现的重复模式，按「规范提炼子流程」列为候选（确认后写入，与修正动作同批）
+6. **收尾边界**：同上（沉淀终点，提交可选需确认）
+
+## 失败模式
+
+| 症状 | 处置 |
+| --- | --- |
+| 会话收尾时多个任务混在一起说不清 | 按任务逐条对应拆开写；对应不上的问用户 |
+| 未尽事项塞进已完成任务正文 | 必须拆独立任务，保持已完成任务归档块干净 |
+| completed 填了收尾时刻而非真实完成时刻 | 按 R1 四级时间源重新取证（git log / 聊天记录时间戳） |
+| 恢复时 active 有游离文件（不在月份目录） | 先按规范移入 `active/{YYYYMM}/` 再读 |
+| 归档历史量太大撑爆上下文 | 走 L2 降级：只出统计 + 近期明细，按需拉取更早 |
+| 新会话仍说「找不到上下文」 | 先查磁盘文件是否存在、是否落在正确月份目录、conventions.md 是否同目录；跨环境场景（换机 / 工作区被 git 清理）才需查是否已 git 提交 |
+| 归档未提交，新会话能恢复吗 | 同机同目录**能恢复**（恢复读磁盘 `.tasks/` 文件，与提交状态无关）；仅跨环境（换机 / checkout、clean 清掉工作区）时未提交内容会丢，恢复才依赖提交 |
+
+## 可选加速（不构成依赖）
+
+⚠️ 工具探测顺序（先项目内、后全局）：先 `pnpm exec toolkit --help`（项目 devDependency，npm 项目等价 `npx toolkit`），失败再 `toolkit --help`（全局安装）；两者都不可用即工具未安装，按各步手工继续，**不安装、不阻塞**。探测成功后用对应前缀执行下列命令：
+
+- `toolkit tasks`：模式二 L0 全量索引（替代人工翻目录）
+- `toolkit tasks stats`：模式二周期统计
+- `toolkit tasks archive`：模式一第 4 步自动化（含排他锁防并发；可 `--dry-run` 预演）
+- `toolkit tasks normalize`：模式三迁移核验（`--fix` 迁移 / 只读检查）
+- `toolkit tasks check`：落盘后校验
+- 任务目录非默认 `.tasks` 时加 `--dir <path>`
+- `toolkit skills install` / `toolkit skills status`：把本包 fxri-* 技能分发到各 agent 全局技能目录 / 查看链接与副本现场（技能随包同源分发，与 CLI 同一发布批次；技能内容版本独立编号，`skills status` 会打印各技能真源版本）