@fxri/toolkit 1.11.3 → 1.11.4

package/package.json

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

package/skills/README.md

@@ -8,9 +8,9 @@
 
 | 技能 | 版本 | 用途 |
 | --- | --- | --- |
-| [fxri-plan-to-task](./fxri-plan-to-task/SKILL.md) | 1.4.4 | 方案落盘：建档评估（先查后写）→ 建档 → 校验 → 归档 → 任务级规范沉淀（能力终点）；规范载体迁移与升级 |
-| [fxri-release-changelog](./fxri-release-changelog/SKILL.md) | 1.1.4 | changesets 发版与多语言 CHANGELOG 维护 |
-| [fxri-session-recap](./fxri-session-recap/SKILL.md) | 1.2.4 | 会话收尾全量沉淀 + 规范沉淀 / 新会话三层恢复 / 历史任务时间批量修正 |
+| [fxri-plan-to-task](./fxri-plan-to-task/SKILL.md) | 1.4.5 | 方案落盘：建档评估（先查后写）→ 建档 → 校验 → 归档 → 任务级规范沉淀（能力终点）；规范载体迁移与升级 |
+| [fxri-release-changelog](./fxri-release-changelog/SKILL.md) | 1.1.5 | changesets 发版与多语言 CHANGELOG 维护 |
+| [fxri-session-recap](./fxri-session-recap/SKILL.md) | 1.2.5 | 会话收尾全量沉淀 + 规范沉淀 / 新会话三层恢复 / 历史任务时间批量修正 |
 
 版本号取自各 SKILL.md 的 frontmatter `metadata.version`（`toolkit skills status` / `skills install` 打印的真源版本），与正文首部版本声明双写一致。
 
@@ -23,15 +23,17 @@
 ```bash
 pnpm add -g @fxri/toolkit   # 1. 装 CLI（npm 用户 npm i -g @fxri/toolkit）
 toolkit skills install      # 2. 把包内技能装到各 agent 的全局技能目录
-toolkit skills status       # 查现场状态（悬空 / 指向其他版本 / 副本漂移 / 缺失 / 同名冲突）
+                            #    --scope project 换项目面：真源落 <仓库根>/.agents/skills/、其余候选目录落入口薄壳
+toolkit skills status       # 查现场状态（悬空 / 指向其他版本 / 副本漂移 / 缺失 / 同名冲突；--scope project 查项目面）
                             # 前四类重跑 toolkit skills install 补齐，同名冲突需 toolkit skills install --force 覆盖
-toolkit skills remove       # 卸载本包装的产物（只清自己装的，不碰用户自装技能）
+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 时）
 

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

@@ -3,14 +3,14 @@ name: fxri-plan-to-task
 description: 将已确认的实施方案落盘为标准任务文件并跟踪至归档：动手前建档评估（查 active/archive 判同主题）、按模板建档、状态机更新、四级时间源取证、自查校验、任务级规范沉淀与手工归档。当用户确认方案后表达「开始落地/登记记录」的意图，或即将动手改仓库文件时使用——含建档、任务登记、落盘、归档、任务校验、规范载体迁移与升级（conventions 单文件升目录形态、v1 升 v2）等说法及其口语近义表达（如按这个做吧、记一下、建个任务跟踪）均触发。不用于方案未确认的对话、会话收尾整场沉淀（fxri-session-recap 模式一）、与任务记录无关的普通 TODO、issue 管理或日常提交信息撰写。
 license: MIT
 metadata:
-  version: "1.4.4"
+  version: "1.4.5"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 方案落盘：任务建档与归档
 
-> 本技能版本 1.4.4（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.4.5（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 

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

@@ -21,7 +21,7 @@
 - 目录与任务目录同在 `.tasks/` 根层，纯 Markdown 随 git 走；默认 `.tasks` 目录名可随任务区自定而变，内部结构不变
 - 非任务文件：`toolkit tasks` 各子命令不读其内容，`check` 不因内容告警；仅在**载体形态异常**时给软告警（旧单文件残留、缺 `index.md`、标记与结构不一致）；**入口层现场异常**（壳标记与当前 toolkit 不一致、壳被 gitignore 覆盖）另见下段入口壳
 
-载体可另配套**入口壳（一阶触发面）**：在**已存在的**项目级技能目录（`.agents/skills/`、`.trae/skills/`、`.trae-cn/skills/`、`.cursor/skills/`、`.claude/skills/`；多 agent 混用团队多个并存时**每处各写一份**、互不覆盖，一个都不存在时回落 `.agents/skills/`）下生成 `toolkit-conventions/SKILL.md`，目录名与 frontmatter `name` 同名（Agent Skills 标准要求）。壳只作入口、不承载条文，正文指回任务区 `conventions/index.md`；由 `toolkit init` 幂等生成（可安全删除，重跑补回；已存在壳按标记版本分流——标记不旧于当前版本保持不变，落后或无标记就地更新为当前版本），只在已有目录内落盘、不为使用者未安装的 agent 凭空建目录，本包源仓库自身不生成。壳首部为 frontmatter，故其形态标记 `<!-- toolkit-conventions-entry: v2 -->` 退居其后、须全文件扫描（区别于载体标记只看首行）；壳标记与当前 toolkit 不一致、或被 `.gitignore` 覆盖时，`toolkit conventions status` 与 `toolkit tasks check` 软告警——标记不一致可重跑 `toolkit init` 就地更新为当前版本；同类告警在多落点并存时**合并为一条**并内联全部落点路径（仓库根相对路径），不按壳逐条重复。体检只扫上述 5 个内置候选目录（`findEntryShells`）：用户手工把壳拷到未收录目录（如 `.windsurf/skills`）不参与体检。
+载体可另配套**入口壳（一阶触发面）**：在**已存在的**项目级技能目录（`.agents/skills/`、`.trae/skills/`、`.trae-cn/skills/`、`.cursor/skills/`、`.claude/skills/`；多 agent 混用团队多个并存时**每处各写一份**、互不覆盖，一个都不存在时回落 `.agents/skills/`）下生成 `toolkit-conventions/SKILL.md`，目录名与 frontmatter `name` 同名（Agent Skills 标准要求）。壳只作入口、不承载条文，正文指回任务区 `conventions/index.md`；由 `toolkit init` 幂等生成（可安全删除，重跑补回；已存在壳按标记版本分流——标记不旧于当前版本保持不变，落后或无标记就地更新为当前版本），只在已有目录内落盘、不为使用者未安装的 agent 凭空建目录，本包源仓库自身不生成。壳首部为 frontmatter，故其形态标记 `<!-- toolkit-conventions-entry: v2 -->` 退居其后、须全文件扫描（区别于载体标记只看首行）；壳标记与当前 toolkit 不一致、或被 `.gitignore` 覆盖时，`toolkit conventions status` 与 `toolkit tasks check` 软告警——标记不一致可重跑 `toolkit init` 就地更新为当前版本；同类告警在多落点并存时**合并为一条**并内联全部落点路径（仓库根相对路径），不按壳逐条重复。体检只扫上述 5 个内置候选目录（`findEntryShells`）：用户手工把壳拷到未收录目录（如 `.windsurf/skills`）不参与体检。⚠️ 同一批候选目录还承载**项目面技能薄壳**（`toolkit skills install --scope project` 在真源 `<仓库根>/.agents/skills/` 之外的其他已存在候选目录生成 `fxri-*` 薄壳），与 `toolkit-conventions/` 入口壳**不同名并存、互不覆盖**；两者机制独立——入口壳由 `toolkit init` 生成、技能薄壳由技能分发生成。
 
 规范触发面共三层，**任一层可用即可触达**：① 全局技能 `fxri-plan-to-task`（随包分发到各 agent 全局技能目录，其工作流第 1 步即要求读 `conventions/index.md`）——**不依赖项目内任何文件、恒在兜底**；② 上述项目级入口壳（用户不主动发问也能被 agent 读到）；③ `AGENTS.md` 指针块（仅在文件已存在时幂等追加，不存在不新建，跳过时提示仍有第 1 层可触达）。三层同时缺席的唯一情形：装包后未跑 `toolkit skills install`（或 agent 不加载全局技能），且项目既无 `AGENTS.md` 又未跑 `toolkit init`——`init` 检测到尚未安装全局技能时会在「下一步」中补一行 `toolkit skills install` 指引（已安装则不重复提示），把这一情形收敛为「用户忽略了 `init` 的提示」。
 

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.1.4"
+  version: "1.1.5"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 发版与 CHANGELOG
 
-> 本技能版本 1.1.4（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.1.5（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 
@@ -69,4 +69,4 @@ metadata:
 - `toolkit changelog --lang <语言> …`：切换输出语言（内置 zh / en，其余可配置扩展）
 - `toolkit tasks check`：扫 `.changeset/` 下待发布变更集并逐文件报出缺前缀条目（流程第 1 步的早期自查入口，归档前的 `tasks check` 即含此项）
 - ⚠️ `changelog` 域开了选项透传，自有选项（`--lang` / `--history` / `--redact` / `--warn`）必须写在子命令**之前**：`toolkit changelog --history format` 生效，写成 `toolkit changelog format --history` 会被 changesets 静默忽略（表现为「无 CHANGELOG 需要更新」）
-- `toolkit skills install` / `toolkit skills status`：把本包 fxri-* 技能分发到各 agent 全局技能目录 / 查看链接与副本现场（技能随包同源分发，与 CLI 同一发布批次；技能内容版本独立编号，`skills status` 会打印各技能真源版本）
+- `toolkit skills install` / `toolkit skills status`：把本包 fxri-* 技能分发到目标技能目录（`--scope` 缺省按 CLI 安装位置自动判定全局面 / 项目面；项目面真源落 `<仓库根>/.agents/skills/`、其余候选目录落入口薄壳，随仓库入库后队友 clone 即用）/ 查看链接、副本与项目面现场（技能随包同源分发，与 CLI 同一发布批次；技能内容版本独立编号，`skills status` 会打印各技能真源版本）

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.4"
+  version: "1.2.5"
   author: fxri
   source: https://github.com/fxri-net/toolkit
 ---
 
 # 会话归档、上下文恢复与历史修正
 
-> 本技能版本 1.2.4（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
+> 本技能版本 1.2.5（随 @fxri/toolkit 同批分发）。被问版本时即报此值——不读磁盘、不跑 CLI：报出的值就是本会话上下文里已加载内容的版本，可与 `toolkit skills status` 打印的磁盘基准值对照，不一致即说明会话上下文已过期，开新会话即可。
 
 ## 何时使用
 
@@ -138,4 +138,4 @@ metadata:
 - `toolkit tasks normalize`：模式三迁移核验（`--fix` 迁移 / 只读检查）
 - `toolkit tasks check`：落盘后校验
 - 任务目录非默认 `.tasks` 时加 `--dir <path>`
-- `toolkit skills install` / `toolkit skills status`：把本包 fxri-* 技能分发到各 agent 全局技能目录 / 查看链接与副本现场（技能随包同源分发，与 CLI 同一发布批次；技能内容版本独立编号，`skills status` 会打印各技能真源版本）
+- `toolkit skills install` / `toolkit skills status`：把本包 fxri-* 技能分发到目标技能目录（`--scope` 缺省按 CLI 安装位置自动判定全局面 / 项目面；项目面真源落 `<仓库根>/.agents/skills/`、其余候选目录落入口薄壳，随仓库入库后队友 clone 即用）/ 查看链接、副本与项目面现场（技能随包同源分发，与 CLI 同一发布批次；技能内容版本独立编号，`skills status` 会打印各技能真源版本）