@fxri/toolkit 1.11.8 → 1.12.1

package/skills/README.md

@@ -1,102 +1,102 @@
-# fxri Skills
-
-零依赖 AI 技能包：纯 Markdown 规范 + 流程指令，不绑定编程语言、框架或任何工具，AI 仅凭文件读写即可完整执行；`@fxri/toolkit` 仅作为可选加速器出现（各 SKILL.md 末尾「可选加速」节）。
-
-遵循 [Agent Skills 开放标准](https://agentskills.io)（`SKILL.md` = YAML frontmatter + Markdown 正文），可被 Claude Code、Cursor、Codex、Gemini CLI 等兼容 agent 按需加载。
-
-## 技能列表
-
-| 技能 | 版本 | 用途 |
-| --- | --- | --- |
-| [fxri-plan-to-task](./fxri-plan-to-task/SKILL.md) | 1.7.1 | 方案落盘：建档评估（先查后写）→ 建档 → 校验 → 归档 → 任务级规范沉淀（能力终点）；规范载体迁移与升级 |
-| [fxri-release-changelog](./fxri-release-changelog/SKILL.md) | 1.1.8 | changesets 发版与多语言 CHANGELOG 维护 |
-| [fxri-session-recap](./fxri-session-recap/SKILL.md) | 1.3.0 | 会话收尾全量沉淀 + 规范沉淀 / 新会话三层恢复 / 历史任务时间批量修正 |
-
-版本号取自各 SKILL.md 的 frontmatter `metadata.version`（`toolkit skills status` / `skills install` 打印的真源版本），与正文首部版本声明双写一致。
-
-## 安装
-
-### 方式一：内置命令（推荐，技能随包分发）
-
-安装了 CLI 后，技能取自包内 `skills/`，随包同源分发（与 CLI 同一发布批次；技能内容版本独立编号，看的是各 SKILL.md 自己的版本），**不需要第二条供应链、不需要访问 GitHub**：
-
-```bash
-pnpm add -g @fxri/toolkit   # 1. 装 CLI（npm 用户 npm i -g @fxri/toolkit）
-toolkit skills install      # 2. 把包内技能装到各 agent 的全局技能目录
-                            #    --scope project 换项目面：真源落 <仓库根>/.agents/skills/、其余候选目录落入口薄壳
-toolkit skills status       # 查现场状态（悬空 / 指向其他版本 / 副本漂移 / 缺失 / 同名冲突；--scope project 查项目面）
-                            # 前四类重跑 toolkit skills install 补齐，同名冲突需 toolkit skills install --force 覆盖
-toolkit skills remove       # 卸载本包装的产物（只清自己装的，不碰用户自装技能；--scope project 清项目面）
-```
-
-- 真源唯一：技能取自已装 CLI 包内的 `skills/`；软链锚在 pnpm 稳定入口，升级 CLI 后自动指向新版（副本形式需重跑 `toolkit skills install`）
-- 目标三层：主目标 `~/.agents/skills/`（多家 agent 共读）→ 内置表内**已安装**的各 agent 全局技能目录 → `--dir <path>` 兜底（可多次指定，给表外 agent 用）
-- 默认软链（锚在 pnpm 稳定入口，升级不失效）；链接创建失败自动降级为副本并打印 ⚠️（如无权限建链）；`--copy` 强制副本、`--dry-run` 预演、`--force` 覆盖同名非本包产物（不改本包已登记副本的形态）
-- 产物记录在状态文件 `~/.agents/.toolkit-skills.json`；卸载 CLI 前先跑 `toolkit skills remove`，避免留下悬空链接（清理后目标目录若已空会一并回收）
-- **项目面（`--scope project`）**：`--scope` 缺省时按 CLI 安装位置自动判定（项目内装 CLI → 项目面）。真源落 `<仓库根>/.agents/skills/`（完整副本），其余**已存在**的候选目录（`.trae/skills/`、`.trae-cn/skills/`、`.cursor/skills/`、`.claude/skills/`）各放每个技能一份入口薄壳指向真源；产物记录在 `<仓库根>/.toolkit/state.json`（与真源、薄壳一并入库）。`toolkit init` 会写入 `prepare` 刷新钩子，`pnpm install` 时自动补齐/刷新，队友 clone 即用；`--copy` 仅全局面生效，项目面恒为副本
-
-### 方式二：上游安装器 `npx skills`（需锁定文件或覆盖表外 agent 时）
-
-本仓库遵循 Agent Skills 开放标准，兼容 [vercel-labs/skills](https://github.com/vercel-labs/skills) 安装器（自动识别本机 agent、写锁定文件；技能从 GitHub 拉取）：
-
-```bash
-pnpm dlx skills add fxri-net/toolkit                           # pnpm 用户（官方命令为 npx skills）
-pnpm dlx skills add fxri-net/toolkit --skill fxri-plan-to-task # 只装单个技能
-pnpm dlx skills list / update / remove                         # 查看 / 升级 / 卸载
-# npm 用户把上述 pnpm dlx 换成 npx 即可
-```
-
-- 项目级安装默认写 `.agents/skills/` 并对各 agent 目录建立符号链接；团队项目把生成的 `skills-lock.json` 提交进仓库以对齐版本；单人多项目加 `-g` 全局安装
-- 内置命令已覆盖的场景优先用方式一：方式二的技能走 GitHub、CLI 走 npm，两条供应链易出现版本漂移
-- ⚠️ 两条路径不要混用：上游安装器把技能落成**实体副本**，且不在本包状态文件 `~/.agents/.toolkit-skills.json` 的登记内，内置命令会把它判为「同名非本包产物」——混用后 `toolkit skills status` 报「同名冲突」，且再跑一次 `pnpm dlx skills update -g` 会把 `~/.agents/skills/` 重写回实体副本，冲突复发
-- 已用方式二装过、想换回方式一：`toolkit skills install --force` 一键接管同名旧副本，详见 [FAQ](https://fxri-net.github.io/toolkit/faq)
-
-#### GitHub 拉取受限时（国内网络 / 内网）
-
-`npx skills` 只认 GitHub 源与本地路径；GitHub 不稳时改从 [Gitee 镜像](https://gitee.com/fxri/toolkit)（同源同步）克隆后走本地路径源：
-
-```bash
-git clone https://gitee.com/fxri/toolkit fxri-toolkit
-pnpm dlx skills add fxri-toolkit --global       # npm 用户把 pnpm dlx 换成 npx
-```
-
-完全离线场景：先用 `pnpm pack @fxri/toolkit` 打出 tgz 拷进内网 `pnpm add -g <tgz>` 离线装 CLI，再 `toolkit skills install`（技能随包分发，全程不碰 GitHub）；详见 [FAQ · 内网或离线环境怎么装](https://fxri-net.github.io/toolkit/faq)。
-
-### 方式三：手工复制 / 软链
-
-- 已安装 `@fxri/toolkit` 的项目可直接使用包内自带的技能目录：`node_modules/@fxri/toolkit/skills/`，复制或软链到 agent 的 skills 目录即可
-- 复制或软链技能目录到 agent 的 skills 目录（如 Claude Code 的 `.claude/skills/`）
-- 支持自定义 rules 的工具（如 Trae）：链接 SKILL.md 为规则
-- 通用兜底：在项目根 `AGENTS.md` 中引用本目录路径
-
-复制副本以 frontmatter `metadata.version` 判断是否需要同步上游（`metadata.source` 指向本仓库）。
-
-## 版本声明与一致性
-
-每个 SKILL.md 的版本写两处，须保持一致：
-
-- frontmatter `metadata.version`：机器读取位，`toolkit skills status` / `skills install` 打印的真源版本取自这里
-- **正文首部**的 `> 本技能版本 x.y.z（随 @fxri/toolkit 同批分发）`：进上下文的自证位——agent 加载技能正文即见到它，被问版本时报这个值（不读磁盘、不跑 CLI），与 `toolkit skills status` 的磁盘基准值一比对，就能判断当前会话上下文是否已过期
-
-两处不一致会误导版本比对，故内容变更时同步递增、发布前逐项核对（见下方核对清单）。
-
-## 与其他 skills 共存
-
-每个技能是独立目录、独立激活单元：agent 按 `description` 匹配任务按需加载，不用到的技能零上下文占用。唯一约束是目录名（即 `name`）不重复；`description` 已含反向排除，与常见通用技能重叠概率低。
-
-## 命名约定
-
-- `fxri-` 前缀为组织级命名空间（对应 npm scope `@fxri/`），fxri 生态新技能沿用；不使用产品级 `toolkit-` 前缀，避免暗示工具依赖
-- name 全小写 kebab-case，与目录名一致，≤64 字符
-
-## 发布前核对清单
-
-- [ ] name：kebab-case、与目录名一致、≤64 字符
-- [ ] description：≤1024 字符，含做什么 + 何时用 + 正向触发词 + 反向排除
-- [ ] metadata.version：内容变更即递增，且与正文首部版本声明一致
-- [ ] 主干 SKILL.md < 200 行，细节下沉 `references/`，可复制资产放 `assets/`
-- [ ] 引用的 references / assets 相对路径有效
-- [ ] 技能用途描述已同步 docs/guide 技能表与本文「技能列表」表（含版本标注）
-- [ ] 涉规范载体（conventions）的改动：`fxri-session-recap/SKILL.md` 的 R3 压缩要点已与 `fxri-plan-to-task/references/conventions-spec.md` 同步（跨 skill 不可引用，只能受控重复，两处不一致即失一致）
-- [ ] 涉规范载体（conventions）的改动：`src/init.ts` 的 `index.md` / `history.md` 骨架模板与入口壳版本分流、`src/tasks/validate.ts` 的形态告警口径、`src/conventions/` 的形态识别与升级链路、`src/conventions/entry.ts` 的入口壳生成与版本告警已同步（CLI 侧与 skills 细则同源）
-- [ ] 变更已走本仓库质量门：三方一致 + tasks check + pnpm test
+# fxri Skills
+
+零依赖 AI 技能包：纯 Markdown 规范 + 流程指令，不绑定编程语言、框架或任何工具，AI 仅凭文件读写即可完整执行；`@fxri/toolkit` 仅作为可选加速器出现（各 SKILL.md 末尾「可选加速」节）。
+
+遵循 [Agent Skills 开放标准](https://agentskills.io)（`SKILL.md` = YAML frontmatter + Markdown 正文），可被 Claude Code、Cursor、Codex、Gemini CLI 等兼容 agent 按需加载。
+
+## 技能列表
+
+| 技能 | 版本 | 用途 |
+| --- | --- | --- |
+| [fxri-plan-to-task](./fxri-plan-to-task/SKILL.md) | 1.8.7 | 方案落盘：建档评估（先查后写）→ 建档 → 校验 → 归档 → 任务级规范沉淀（能力终点）；规范载体迁移与升级 |
+| [fxri-release-changelog](./fxri-release-changelog/SKILL.md) | 1.1.9 | changesets 发版与多语言 CHANGELOG 维护 |
+| [fxri-session-recap](./fxri-session-recap/SKILL.md) | 1.4.1 | 会话收尾全量沉淀 + 规范沉淀 / 新会话三层恢复 / 历史任务时间批量修正 |
+
+版本号取自各 SKILL.md 的 frontmatter `metadata.version`（`toolkit skills status` / `skills install` 打印的真源版本），与正文首部版本声明双写一致。
+
+## 安装
+
+### 方式一：内置命令（推荐，技能随包分发）
+
+安装了 CLI 后，技能取自包内 `skills/`，随包同源分发（与 CLI 同一发布批次；技能内容版本独立编号，看的是各 SKILL.md 自己的版本），**不需要第二条供应链、不需要访问 GitHub**：
+
+```bash
+pnpm add -g @fxri/toolkit   # 1. 装 CLI（npm 用户 npm i -g @fxri/toolkit）
+toolkit skills install      # 2. 把包内技能装到各 agent 的全局技能目录
+                            #    --scope project 换项目面：真源落 <仓库根>/.agents/skills/、其余候选目录落入口薄壳
+toolkit skills status       # 查现场状态（悬空 / 指向其他版本 / 副本漂移 / 缺失 / 同名冲突；--scope project 查项目面）
+                            # 前四类重跑 toolkit skills install 补齐，同名冲突需 toolkit skills install --force 覆盖
+toolkit skills remove       # 卸载本包装的产物（只清自己装的，不碰用户自装技能；--scope project 清项目面）
+```
+
+- 真源唯一：技能取自已装 CLI 包内的 `skills/`；软链锚在 pnpm 稳定入口，升级 CLI 后自动指向新版（副本形式需重跑 `toolkit skills install`）
+- 目标三层：主目标 `~/.agents/skills/`（多家 agent 共读）→ 内置表内**已安装**的各 agent 全局技能目录 → `--dir <path>` 兜底（可多次指定，给表外 agent 用）
+- 默认软链（锚在 pnpm 稳定入口，升级不失效）；链接创建失败自动降级为副本并打印 ⚠️（如无权限建链）；`--copy` 强制副本、`--dry-run` 预演、`--force` 覆盖同名非本包产物（不改本包已登记副本的形态）
+- 产物记录在状态文件 `~/.agents/.toolkit-skills.json`；卸载 CLI 前先跑 `toolkit skills remove`，避免留下悬空链接（清理后目标目录若已空会一并回收）
+- **项目面（`--scope project`）**：`--scope` 缺省时按 CLI 安装位置自动判定（项目内装 CLI → 项目面）。真源落 `<仓库根>/.agents/skills/`（完整副本），其余**已存在**的候选目录（`.trae/skills/`、`.trae-cn/skills/`、`.cursor/skills/`、`.claude/skills/`）各放每个技能一份入口薄壳指向真源；产物记录在 `<仓库根>/.toolkit/state.json`（与真源、薄壳一并入库）。`toolkit init` 会写入 `prepare` 刷新钩子，`pnpm install` 时自动补齐/刷新，队友 clone 即用；`--copy` 仅全局面生效，项目面恒为副本
+
+### 方式二：上游安装器 `npx skills`（需锁定文件或覆盖表外 agent 时）
+
+本仓库遵循 Agent Skills 开放标准，兼容 [vercel-labs/skills](https://github.com/vercel-labs/skills) 安装器（自动识别本机 agent、写锁定文件；技能从 GitHub 拉取）：
+
+```bash
+pnpm dlx skills add fxri-net/toolkit                           # pnpm 用户（官方命令为 npx skills）
+pnpm dlx skills add fxri-net/toolkit --skill fxri-plan-to-task # 只装单个技能
+pnpm dlx skills list / update / remove                         # 查看 / 升级 / 卸载
+# npm 用户把上述 pnpm dlx 换成 npx 即可
+```
+
+- 项目级安装默认写 `.agents/skills/` 并对各 agent 目录建立符号链接；团队项目把生成的 `skills-lock.json` 提交进仓库以对齐版本；单人多项目加 `-g` 全局安装
+- 内置命令已覆盖的场景优先用方式一：方式二的技能走 GitHub、CLI 走 npm，两条供应链易出现版本漂移
+- ⚠️ 两条路径不要混用：上游安装器把技能落成**实体副本**，且不在本包状态文件 `~/.agents/.toolkit-skills.json` 的登记内，内置命令会把它判为「同名非本包产物」——混用后 `toolkit skills status` 报「同名冲突」，且再跑一次 `pnpm dlx skills update -g` 会把 `~/.agents/skills/` 重写回实体副本，冲突复发
+- 已用方式二装过、想换回方式一：`toolkit skills install --force` 一键接管同名旧副本，详见 [FAQ](https://fxri-net.github.io/toolkit/faq)
+
+#### GitHub 拉取受限时（国内网络 / 内网）
+
+`npx skills` 只认 GitHub 源与本地路径；GitHub 不稳时改从 [Gitee 镜像](https://gitee.com/fxri/toolkit)（同源同步）克隆后走本地路径源：
+
+```bash
+git clone https://gitee.com/fxri/toolkit fxri-toolkit
+pnpm dlx skills add fxri-toolkit --global       # npm 用户把 pnpm dlx 换成 npx
+```
+
+完全离线场景：先用 `pnpm pack @fxri/toolkit` 打出 tgz 拷进内网 `pnpm add -g <tgz>` 离线装 CLI，再 `toolkit skills install`（技能随包分发，全程不碰 GitHub）；详见 [FAQ · 内网或离线环境怎么装](https://fxri-net.github.io/toolkit/faq)。
+
+### 方式三：手工复制 / 软链
+
+- 已安装 `@fxri/toolkit` 的项目可直接使用包内自带的技能目录：`node_modules/@fxri/toolkit/skills/`，复制或软链到 agent 的 skills 目录即可
+- 复制或软链技能目录到 agent 的 skills 目录（如 Claude Code 的 `.claude/skills/`）
+- 支持自定义 rules 的工具（如 Trae）：链接 SKILL.md 为规则
+- 通用兜底：在项目根 `AGENTS.md` 中引用本目录路径
+
+复制副本以 frontmatter `metadata.version` 判断是否需要同步上游（`metadata.source` 指向本仓库）。
+
+## 版本声明与一致性
+
+每个 SKILL.md 的版本写两处，须保持一致：
+
+- frontmatter `metadata.version`：机器读取位，`toolkit skills status` / `skills install` 打印的真源版本取自这里
+- **正文首部**的 `> 本技能版本 x.y.z（随 @fxri/toolkit 同批分发）`：进上下文的自证位——agent 加载技能正文即见到它，被问版本时报这个值（不读磁盘、不跑 CLI），与 `toolkit skills status` 的磁盘基准值一比对，就能判断当前会话上下文是否已过期
+
+两处不一致会误导版本比对，故内容变更时同步递增、发布前逐项核对（见下方核对清单）。
+
+## 与其他 skills 共存
+
+每个技能是独立目录、独立激活单元：agent 按 `description` 匹配任务按需加载，不用到的技能零上下文占用。唯一约束是目录名（即 `name`）不重复；`description` 已含反向排除，与常见通用技能重叠概率低。
+
+## 命名约定
+
+- `fxri-` 前缀为组织级命名空间（对应 npm scope `@fxri/`），fxri 生态新技能沿用；不使用产品级 `toolkit-` 前缀，避免暗示工具依赖
+- name 全小写 kebab-case，与目录名一致，≤64 字符
+
+## 发布前核对清单
+
+- [ ] name：kebab-case、与目录名一致、≤64 字符
+- [ ] description：≤1024 字符，含做什么 + 何时用 + 正向触发词 + 反向排除
+- [ ] metadata.version：内容变更即递增，且与正文首部版本声明一致
+- [ ] 主干 SKILL.md < 200 行，细节下沉 `references/`，可复制资产放 `assets/`
+- [ ] 引用的 references / assets 相对路径有效
+- [ ] 技能用途描述已同步 docs/guide 技能表与本文「技能列表」表（含版本标注）
+- [ ] 涉规范载体（conventions）的改动：`fxri-session-recap/SKILL.md` 的 R3 压缩要点已与 `fxri-plan-to-task/references/conventions-spec.md` 同步（跨 skill 不可引用，只能受控重复，两处不一致即失一致）
+- [ ] 涉规范载体（conventions）的改动：`src/init.ts` 的 `index.md` / `history.md` 骨架模板与入口壳版本分流、`src/tasks/validate.ts` 的形态告警口径、`src/conventions/` 的形态识别与升级链路、`src/conventions/entry.ts` 的入口壳生成与版本告警已同步（CLI 侧与 skills 细则同源）
+- [ ] 变更已走本仓库质量门：三方一致 + tasks check + pnpm test

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

@@ -1,122 +1,123 @@
----
-name: fxri-plan-to-task
-description: 将已确认的实施方案落盘为标准任务文件并跟踪至归档：动手前建档评估（查 active/archive 判同主题）、按模板建档、状态机更新、四级时间源取证、自查校验、任务级规范沉淀与手工归档。当用户确认方案后表达「开始落地/登记记录」的意图，或即将动手改仓库文件时使用——含建档、任务登记、落盘、归档、任务校验、规范载体迁移与升级（conventions 单文件升目录形态、v1 升 v2）等说法及其口语近义表达（如按这个做吧、记一下、建个任务跟踪）均触发。不用于方案未确认的对话、会话收尾整场沉淀（fxri-session-recap 模式一）、与任务记录无关的普通 TODO、issue 管理或日常提交信息撰写。
-license: MIT
-metadata:
-  version: "1.7.1"
-  author: fxri
-  source: https://github.com/fxri-net/toolkit
----
-
-# 方案落盘：任务建档与归档
-
-> 本技能版本 1.7.1（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
-
-## 何时使用
-
-- 用户确认实施方案后，表达开始落地/登记记录的意图（语义触发，不要求字面一致）：建档 / 任务登记 / 落盘 / 归档 / 任务校验 / 规范载体迁移与升级 / 按这个做吧 / 记一下 / 建个任务跟踪
-- **即将动手改仓库文件前**（方案已确认、准备执行改动）也是本技能适用场景——动手前先做建档评估（见工作流第 1 步），避免跳过建档直接执行
-- 触发前置条件：**方案已确认**。用户说「开始/开工」但方案尚未确认时，先出方案等确认，不建档
-- **何时不使用**：方案未确认的对话；会话收尾的整场沉淀与归档（那是 fxri-session-recap 模式一）；收尾动作（提交、发版、推送、部署）本身——动作不算、改动才算（见工作流第 1 步）；与方案落盘无关的普通 TODO、issue 管理、日历待办、日常提交信息撰写
-
-## 核心约定
-
-任务文件规范（目录结构、命名、frontmatter 字段、归档格式、手工归档步骤、自查清单）全部以 `references/task-spec.md` 为准；规范载体（conventions）的结构、形态标记与稳定 ID、归属判定、读写判定、内容修订、表格形态（紧凑）、存量迁移与 v1→v2 升级、入口壳以 `references/conventions-spec.md` 为准。本文件只写流程。执行任何写操作前先读它们。
-
-## 核心规则
-
-### 四级时间源（completed 取证唯一口径）
-
-终结态补 `completed` 时按以下优先级取证，禁止凭记忆估算或做时区换算：
-
-| 级 | 时间源 | 取证 |
-| --- | --- | --- |
-| 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 | 系统当前时间兜底 | 当场取时 + 正文标注「时间为收尾补记」 |
-
-详细口径与告警语义见 `references/task-spec.md`。
-
-## 工作流
-
-### 1. 动手前置：建档评估（先查后写的流程落点，所有仓库文件改动前必做，防漏建档/重复建档）
-
-- 无 `.tasks/` 任务区时先执行 `toolkit init` 建骨架（幂等，已存在不覆盖）
-- 列出任务目录 `active/` 下全部 `.md`（含一层 `{YYYYMM}/` 月份子目录），并核对 `archive/` 是否已有同主题任务
-- 读 conventions 载体（存在时）：先找 `.tasks/conventions/index.md`，不存在再看旧单文件 `.tasks/conventions.md`（兼容期读取，并在对话中提示可迁移）；常驻只读 `index.md`（`history.md` 与各分册按需读），再按本任务 `scope` 命中加载 `common` 与端分册（形态识别与读写判定见 `references/conventions-spec.md`）——载体也可能经项目级技能入口壳（如 `.agents/skills/toolkit-conventions/`）把 agent 引到此处；项目协作规范在建档与执行时须遵守；规范载体本身不属于任务，不为其建档
-- **同主题判别表**（建档前必须按此决策）：
-  | 现状 | 本次是否产生仓库文件改动 | 处理 |
-  | --- | --- | --- |
-  | active 有同主题 | 补充/细化（同需求未完） | **更新原文件**正文，updated 同步，不新建 |
-  | active 有同主题 | 已分叉成不同范围 | 问用户：拆新任务 or 合并更新 |
-  | active 无、archive 有（已归档完成） | 否（重复提议 / 重复执行同一件事） | 提示「同主题任务已归档于 {日期}」，不重复建档，直接执行 |
-  | active 无、archive 有 | 是（延续 / 扩展 / 重新实现） | **重新建档**，正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）` |
-  | active 无、archive 有 | 否，仅修正旧记录的时间/内容 | 走 fxri-session-recap 模式三（历史修正），**不是建档** |
-  | active 与 archive 均无 | — | **建档后再动手**（硬前置，不建档不许改文件） |
-- **仓库文件改动口径**（客观判据，不靠感觉）：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入）；纯读取、纯执行、纯汇报不计入；拿不准 → 列出差异问用户，不猜
-- **动作不算，改动才算**：收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不作为建档对象；这些动作过程中若出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误），该修复按普通任务建档
-- **跨仓库改动各自归档（本仓自述）**：任务档是仓库自述，只记本仓的改动与动机；跨仓库是会话属性而非仓库属性，同一会话涉及多仓时各仓各自建档归档，不在一仓记录里承载另一仓的工作痕迹。判据取**视角**（描述的是不是本仓的改动与动机），非词表——依赖包名 / 被调接口名等属本仓事实者照写
-- **归档块不可变**：已归档块不追加新的工作内容（追加新工作内容会破坏完成时间/范围的可信度）；延续需求一律走新任务。唯一例外是**事实更正**：后续核实推翻原块结论、或协作口径变更导致历史事实字段需更正时，在其正文末尾追加「修订记录」（保留原结论、附更正时刻与依据）；口径变更类更正可改受影响的**事实字段**（如 `scope`），但唯一键 / 完成时间 / 状态 / 负责人仍冻结
-- 任务唯一键：`{YYYYMMDD}-{用户名}-{任务简述}`；多人对同一需求共用一个文件
-
-### 2. 建档
-
-- 整段复制 `assets/active-task-template.md` 再填空，不要凭记忆组装 frontmatter
-- 文件放入 `active/{YYYYMM}/`；目录不存在时按规范创建
-- `created` 必须等于文件名日期前缀；`updated` 随每次修改同步
-
-### 3. 过程更新
-
-- status 五态流转：待办 → 进行中 → 阻塞 →（已完成 | 已放弃）；后两者为终结态
-- **阻塞解除归属**：进入阻塞须在正文记录阻塞原因；解除阻塞须用户确认，确认后转回进行中并在正文记录解除原因
-- 进入终结态必须补 `completed: YYYY-MM-DD HH:mm`（按四级时间源取证）
-- 方案正文出现「待实施 / 待核对 / 待评估」等游离子项时，拆分为独立任务文件，不在正文留游离待办
-
-### 4. 校验
-
-按 `references/task-spec.md` 的「自查清单」逐项核对，发现问题当场修复后再进入下一步。
-
-### 5. 归档
-
-按 `references/task-spec.md` 的「手工归档步骤」执行：合并归档块 → 降序重排 → 写回 → 删 active 源文件 → 清理空月份目录。可 `toolkit tasks archive` 自动化。
-
-### 5.5 任务级规范沉淀（归档后执行）
-
-归档完成后按以下轻量步骤提炼本任务产出的规范（与会话收尾的会话级提炼同落点、互不重复）：
-
-- 读 conventions 载体（`index.md` 常驻 + 按本任务 `scope` 命中加载分册），判断本任务是否产出可升格规范：用户明示「以后都要这样」的规则、与已有规范重复印证的决策
-- **归属判定**：先问「是否**所有端都适用**」→ 是则归 `common`；否则逐端确认 → 写入命中的端分册（禁止跨端合并归属；`common` 不得用作「不确定归哪端」的暂存区）
-- 有候选 → 输出给用户确认 → 写索引行（首列稳定 ID `C-<n>`、带「确立来源任务」）并把条文归位；无候选 → **完全静默**
-- 变更已有规范语义时，先在 `history.md` 追加一行留痕，再更新索引行「当前语义」（细则见 `references/conventions-spec.md`）
-- 一次性决策不进规范，留在任务正文
-- **存量迁移与升级**：发现旧单文件 `conventions.md` 时按迁移三段式执行（建目录搬原文 → 逐条提归属建议 → 用户确认后拆分册）；载体为 v1 或 `check` / `toolkit conventions status` 报形态告警时，按 `references/conventions-spec.md` 的 v1→v2 链路升级（优先 `toolkit conventions upgrade`，可 `--dry-run` 预演）；均可中断不丢内容
-
-### 6. 收尾边界（硬约束到沉淀）
-
-**归档 + 规范沉淀即本技能流程终点**（先归档、后沉淀）。提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则；若提交代码，按「归档与沉淀 → 跑项目验收命令 → 提交」的顺序执行，任务归档文件与规范载体变更、代码变更落在**同一个 git 提交**（顺序不可颠倒），避免任务完成却滞留 `active/` 未归档，或归档单独成一条提交。
-
-⚠️ **验收须晚于归档**：归档会改写 `.tasks/`（写归档文件、删 active 源文件、清理空月份目录），而归档本身不做阻断式校验——早于归档跑验收就覆盖不到终态，归档产物等于无人校验。同理，归档块「完成情况」只记改动事实与所用验证命令，不逐条抄写验收输出。
-
-## 失败模式
-
-| 症状 | 处置 |
-| --- | --- |
-| active 下出现同名任务文件 | 重复建档，合并为一个后删除多余 |
-| completed 日期与文件名创建日不一致 | 核对是否填错；确为跨天完成则以 completed 日期归档 |
-| depends_on 引用的任务已归档 | 正常，依赖随之解除；引用拼写错误则修正 |
-| 并发写归档文件互相覆盖 | 归档前确认无其他写者同时操作；多人同天归档 `pull` 后归档文件残留 git 冲突标记时，跑 `toolkit tasks normalize --fix` 按并集去重 + 完成时间降序**确定性**解决（保留两侧任务块、丢弃 diff3 的 `\|\|\|\|\|\|\|` base 段与全部标记行） |
-| completed 填了收尾时刻而非真实完成时刻 | 按四级时间源重新取证（git log / 聊天记录时间戳） |
-
-## 可选加速（不构成依赖）
-
-⚠️ 工具探测顺序（先项目内、后全局）：先 `pnpm exec toolkit --help`（项目 devDependency，npm 项目等价 `npx toolkit`），失败再 `toolkit --help`（全局安装）；两者都不可用即工具未安装，按各步手工继续，**不安装、不阻塞**。探测成功后用对应前缀执行下列命令：
-
-- `toolkit tasks`：查 active 总览（替代第 1 步人工翻目录）
-- `toolkit tasks check`：自动校验（替代第 4 步自查清单）
-- `toolkit tasks archive`：自动归档（替代第 5 步，含排他锁防并发；可 `--dry-run` 预演）
-- `toolkit tasks normalize`：归档后核验归档块（元数据完整性/日期漂移/排序/git 冲突标记），可 `--fix` 自动修复（含按并集去重 + 降序解决冲突标记）
-- `toolkit conventions status`：只读体检载体形态与入口壳现场（替代第 1 步人工判形态、第 5.5 步沉淀前后自查）
-- `toolkit conventions upgrade`：v1 → v2 结构升级（第 5.5 步，纯机械、幂等；可 `--dry-run` 预演）
-- `toolkit conventions format`：表格形态归一为紧凑形态（手工写表后自查；只动空白层与分隔行横线长度、不改语义；幂等、跳过代码块；可 `--dry-run` 预演）
-- 任务目录非默认 `.tasks` 时加 `--dir <path>`
+---
+name: fxri-plan-to-task
+description: 将已确认的实施方案落盘为标准任务文件并跟踪至归档：动手前建档评估（查 active/archive 判同主题）、按模板建档、状态机更新、四级时间源取证、自查校验、任务级规范沉淀与手工归档。当用户确认方案后表达「开始落地/登记记录」的意图，或即将动手改仓库文件时使用——含建档、任务登记、落盘、归档、任务校验、规范载体迁移与升级（conventions 单文件升目录形态、v1 / v2 升 v3）等说法及其口语近义表达（如按这个做吧、记一下、建个任务跟踪）均触发。不用于方案未确认的对话、会话收尾整场沉淀（fxri-session-recap 模式一）、与任务记录无关的普通 TODO、issue 管理或日常提交信息撰写。
+license: MIT
+metadata:
+  version: "1.8.7"
+  author: fxri
+  source: https://github.com/fxri-net/toolkit
+---
+
+# 方案落盘：任务建档与归档
+
+> 本技能版本 1.8.7（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+
+## 何时使用
+
+- 用户确认实施方案后，表达开始落地/登记记录的意图（语义触发，不要求字面一致）：建档 / 任务登记 / 落盘 / 归档 / 任务校验 / 规范载体迁移与升级 / 按这个做吧 / 记一下 / 建个任务跟踪
+- **即将动手改仓库文件前**（方案已确认、准备执行改动）也是本技能适用场景——动手前先做建档评估（见工作流第 1 步），避免跳过建档直接执行
+- 触发前置条件：**方案已确认**。用户说「开始/开工」但方案尚未确认时，先出方案等确认，不建档
+- **何时不使用**：方案未确认的对话；会话收尾的整场沉淀与归档（那是 fxri-session-recap 模式一）；收尾动作（提交、发版、推送、部署）本身——动作不算、改动才算（见工作流第 1 步）；与方案落盘无关的普通 TODO、issue 管理、日历待办、日常提交信息撰写
+
+## 核心约定
+
+任务文件规范（目录结构、命名、frontmatter 字段、归档格式、手工归档步骤、自查清单）全部以 `references/task-spec.md` 为准；规范载体（conventions）的三分区结构、形态标记与稳定 ID、归属判定、分层读写判定、内容修订（含作废的三层清理）、表格形态（紧凑）、存量迁移与 v1 / v2→v3 升级、分类标签分册、入口壳以 `references/conventions-spec.md` 为准。本文件只写流程。执行任何写操作前先读它们。
+
+## 核心规则
+
+### 四级时间源（completed 取证唯一口径）
+
+终结态补 `completed` 时按以下优先级取证，禁止凭记忆估算或做时区换算：
+
+| 级 | 时间源 | 取证 |
+| --- | --- | --- |
+| 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 | 系统当前时间兜底 | 当场取时 + 正文标注「时间为收尾补记」 |
+
+详细口径与告警语义见 `references/task-spec.md`。
+
+## 工作流
+
+### 1. 动手前置：建档评估（先查后写的流程落点，所有仓库文件改动前必做，防漏建档/重复建档）
+
+- 无 `.tasks/` 任务区时先执行 `toolkit init` 建骨架（幂等，已存在不覆盖）
+- 列出任务目录 `active/` 下全部 `.md`（含一层 `{YYYYMM}/` 月份子目录），并核对 `archive/` 是否已有同主题任务
+- 读 conventions 载体（存在时）：先找 `.tasks/conventions/index.md`，不存在再看旧单文件 `.tasks/conventions.md`（兼容期读取，并在对话中提示可迁移）；常驻只读 `index.md`（`history.md` / `retired.md` 属归档面、各分册按需读），再按本任务 `scope` 命中加载端分册 / 分类标签分册并**恒叠加 `common`**（形态识别与分层读写判定见 `references/conventions-spec.md`）——载体也可能经项目级技能入口壳（如 `.agents/skills/toolkit-conventions/`）把 agent 引到此处；项目协作规范在建档与执行时须遵守；规范载体本身不属于任务，不为其建档
+- **同主题判别表**（建档前必须按此决策）：
+  | 现状 | 本次是否产生仓库文件改动 | 处理 |
+  | --- | --- | --- |
+  | active 有同主题 | 补充/细化（同需求未完） | **更新原文件**正文，updated 同步，不新建 |
+  | active 有同主题 | 已分叉成不同范围 | 问用户：拆新任务 or 合并更新 |
+  | active 无、archive 有（已归档完成） | 否（重复提议 / 重复执行同一件事） | 提示「同主题任务已归档于 {日期}」，不重复建档，直接执行 |
+  | active 无、archive 有 | 是（延续 / 扩展 / 重新实现） | **重新建档**，正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）` |
+  | active 无、archive 有 | 否，仅修正旧记录的时间/内容 | 走 fxri-session-recap 模式三（历史修正），**不是建档** |
+  | active 与 archive 均无 | — | **建档后再动手**（硬前置，不建档不许改文件） |
+- **仓库文件改动口径**（客观判据，不靠感觉）：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入）；纯读取、纯执行、纯汇报不计入；拿不准 → 列出差异问用户，不猜
+- **动作不算，改动才算**：收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不作为建档对象；这些动作过程中若出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误），该修复按普通任务建档
+- **跨仓库改动各自归档（本仓自述）**：任务档是仓库自述，只记本仓的改动与动机；跨仓库是会话属性而非仓库属性，同一会话涉及多仓时各仓各自建档归档，不在一仓记录里承载另一仓的工作痕迹。判据取**视角**（描述的是不是本仓的改动与动机），非词表——依赖包名 / 被调接口名等属本仓事实者照写
+- **归档块不可变**：已归档块不追加新的工作内容（追加新工作内容会破坏完成时间/范围的可信度）；延续需求一律走新任务。唯一例外是**事实更正**：后续核实推翻原块结论、或协作口径变更导致历史事实字段需更正时，在其正文末尾追加「修订记录」（保留原结论、附更正时刻与依据）；口径变更类更正可改受影响的**事实字段**（如 `scope`），但唯一键 / 完成时间 / 状态 / 负责人仍冻结
+- 任务唯一键：`{YYYYMMDD}-{用户名}-{任务简述}`；多人对同一需求共用一个文件
+
+### 2. 建档
+
+- 整段复制 `assets/active-task-template.md` 再填空，不要凭记忆组装 frontmatter
+- 文件放入 `active/{YYYYMM}/`；目录不存在时按规范创建
+- `created` 必须等于文件名日期前缀；`updated` 随每次修改同步
+
+### 3. 过程更新
+
+- status 五态流转：待办 → 进行中 → 阻塞 →（已完成 | 已放弃）；后两者为终结态
+- **阻塞解除归属**：进入阻塞须在正文记录阻塞原因；解除阻塞须用户确认，确认后转回进行中并在正文记录解除原因
+- 进入终结态必须补 `completed: YYYY-MM-DD HH:mm`（按四级时间源取证）
+- 方案正文出现「待实施 / 待核对 / 待评估」等游离子项时，拆分为独立任务文件，不在正文留游离待办
+
+### 4. 校验
+
+按 `references/task-spec.md` 的「自查清单」逐项核对，发现问题当场修复后再进入下一步。
+
+### 5. 归档
+
+按 `references/task-spec.md` 的「手工归档步骤」执行：合并归档块 → 降序重排 → 写回 → 删 active 源文件 → 清理空月份目录。可 `toolkit tasks archive` 自动化。
+
+### 5.5 任务级规范沉淀（归档后执行）
+
+归档完成后按以下轻量步骤提炼本任务产出的规范（与会话收尾的会话级提炼同落点、互不重复）：
+
+- 读 conventions 载体（`index.md` 常驻 + 按本任务 `scope` 命中加载端分册 / 分类标签分册并恒叠加 `common`），判断本任务是否产出可升格规范：用户明示「以后都要这样」的规则、与已有规范重复印证的决策
+- **归属判定**：先问「是否**所有端都适用**」→ 是则归 `common`；否则逐端确认 → 写入命中的端分册（禁止跨端合并归属；`common` 不得用作「不确定归哪端」的暂存区）
+- 有候选 → 输出给用户确认 → 写索引行（首列稳定 ID `C-<n>`）并把条文归位；无候选 → **完全静默**
+- 变更已有规范语义时，先在 `history.md` 追加一行留痕，再更新索引行「当前语义」（细则见 `references/conventions-spec.md`）
+- **规则作废**：走「迁出 + 三层清理」——索引行删除并迁入 `retired.md`（冻结语义）、物理删除分册内该条小节、外部单一事实源同步删改；不把状态改个标记留在原位
+- 一次性决策不进规范，留在任务正文
+- **存量迁移与升级**：发现旧单文件 `conventions.md` 时按迁移三段式执行（建目录搬原文 → 逐条提归属建议 → 用户确认后拆分册）；载体为 v1 / v2 或 `check` / `toolkit conventions status` 报形态告警时，按 `references/conventions-spec.md` 的 v1 / v2→v3 链路升级（优先 `toolkit conventions upgrade`，可 `--dry-run` 预演）；均可中断不丢内容
+
+### 6. 收尾边界（硬约束到沉淀）
+
+**归档 + 规范沉淀即本技能流程终点**（先归档、后沉淀）。提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则；若提交代码，按「归档与沉淀 → 跑项目验收命令 → 提交」的顺序执行，任务归档文件与规范载体变更、代码变更落在**同一个 git 提交**（顺序不可颠倒），避免任务完成却滞留 `active/` 未归档，或归档单独成一条提交。
+
+⚠️ **验收须晚于归档**：归档会改写 `.tasks/`（写归档文件、删 active 源文件、清理空月份目录），而归档本身不做阻断式校验——早于归档跑验收就覆盖不到终态，归档产物等于无人校验。同理，归档块「完成情况」只记改动事实与所用验证命令，不逐条抄写验收输出。
+
+## 失败模式
+
+| 症状 | 处置 |
+| --- | --- |
+| active 下出现同名任务文件 | 重复建档，合并为一个后删除多余 |
+| completed 日期与文件名创建日不一致 | 核对是否填错；确为跨天完成则以 completed 日期归档 |
+| depends_on 引用的任务已归档 | 正常，依赖随之解除；引用拼写错误则修正 |
+| 并发写归档文件互相覆盖 | 归档前确认无其他写者同时操作；多人同天归档 `pull` 后归档文件残留 git 冲突标记时，跑 `toolkit tasks normalize --fix` 按并集去重 + 完成时间降序**确定性**解决（保留两侧任务块、丢弃 diff3 的 `\|\|\|\|\|\|\|` base 段与全部标记行） |
+| completed 填了收尾时刻而非真实完成时刻 | 按四级时间源重新取证（git log / 聊天记录时间戳） |
+
+## 可选加速（不构成依赖）
+
+⚠️ 工具探测顺序（先项目内、后全局）：先 `pnpm exec toolkit --help`（项目 devDependency，npm 项目等价 `npx toolkit`），失败再 `toolkit --help`（全局安装）；两者都不可用即工具未安装，按各步手工继续，**不安装、不阻塞**。探测成功后用对应前缀执行下列命令：
+
+- `toolkit tasks`：查 active 总览（替代第 1 步人工翻目录）
+- `toolkit tasks check`：自动校验（替代第 4 步自查清单）
+- `toolkit tasks archive`：自动归档（替代第 5 步，含排他锁防并发；可 `--dry-run` 预演）
+- `toolkit tasks normalize`：归档后核验归档块（元数据完整性/日期漂移/排序/git 冲突标记），可 `--fix` 自动修复（含按并集去重 + 降序解决冲突标记）
+- `toolkit conventions status`：只读体检载体形态与入口壳现场（替代第 1 步人工判形态、第 5.5 步沉淀前后自查）
+- `toolkit conventions upgrade`：v1 / v2 → v3 结构升级（第 5.5 步，纯机械、幂等；可 `--dry-run` 预演）
+- `toolkit conventions format`：表格形态归一为紧凑形态（手工写表后自查；只动空白层与分隔行横线长度、不改语义；幂等、跳过代码块；可 `--dry-run` 预演）
+- 任务目录非默认 `.tasks` 时加 `--dir <path>`