@fxri/toolkit 1.12.3 → 1.12.5

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # 方弦工具集
 
+## 1.12.5
+
+> 2026-10-19 发布
+
+### ✨ 新增功能
+
+- `skills status` 单列「经 canonical 共读的 agent」，DeepSeek Harness 等共读 agent 不再被误判为不支持（JSON 输出新增 `canonicalReaders` 字段）
+- 项目面候选目录增加 eve 的 `agent/skills`，该目录已存在时落入口薄壳
+- `skills status` 识别 Codex / Pi 的历史落点残留（`~/.codex/skills`、`~/.pi/agent/skills`），标注为「历史落点」并在报告末尾单列提示清理，JSON 输出新增 `legacyTargets` 字段
+- 项目级技能目录候选补充 15 个上游专用配置目录（`.augment/skills`、`.codebuddy/skills`、`.continue/skills`、`.crush/skills`、`.devin/skills`、`.goose/skills`、`.grok/skills`、`.hermes/skills`、`.iflow/skills`、`.junie/skills`、`.kiro/skills`、`.openhands/skills`、`.qwen/skills`、`.roo/skills`、`.windsurf/skills`），已在用的项目级目录都会收到入口壳
+
+### 🐛 问题修复
+
+- Codex 与 Pi 的全局技能目录对齐上游 canonical（`~/.agents/skills`），不再分别写到 `~/.codex/skills`、`~/.pi/agent/skills`，避免与共读面重复分发
+- `CODEX_HOME` 改为仅参与安装探测，不再改写 Codex 的写入落点
+- 项目级技能目录候选移除 `.cursor/skills`、`.trae-cn/skills`（二者为对应 agent 的全局目录，收录会把入口壳写到错误位置）
+- 各 agent 全局技能目录跟随 home 类环境变量（`XDG_CONFIG_HOME`、`CLAUDE_CONFIG_DIR`、`VIBE_HOME`、`HERMES_HOME`、`AUTOHAND_HOME`、`GROK_HOME`），改写基准目录后不再分发到错误位置
+- `SARVAM_HOME`、`APPDATA`、`FLATPAK_XDG_CONFIG_HOME` 参与已安装探测，自定义目录的 agent 不再误判为未安装
+
+### 📝 文档更新
+
+- 补充 canonical 共读 agent 清单，以及 DeepSeek Harness 全局 / 项目级技能目录说明
+- 更新 canonical 共读 agent 清单与环境变量说明
+- 同步项目级技能目录与入口壳落点的枚举，写明拒绝收录的裸 `skills` 与 `data/skills` 理由
+- `skills install --dir` 的 help 说明补充「不参与后续自动同步，技能变化后需带相同 `--dir` 重跑」，与文档口径一致
+- 补充 `--dir` 自定义技能目录的同步说明——只在当次安装时写入，技能增删后不会自动同步，需带相同 `--dir` 重跑 `toolkit skills install`
+- 补充全局技能目录的环境变量覆盖说明
+
+## 1.12.4
+
+> 2026-10-19 发布
+
+### ✨ 新增功能
+
+- `docs/ai-rules.md` 补「规划先行」「逐仓逐任务建档」「按序交付、逐任务提交」三条稳定纪律，多任务方案先出纯展示计划表再逐仓逐任务建档
+
+### 🔧 功能调整
+
+- `fxri-plan-to-task` 新增任务分解与展示型计划表步骤，建档改为逐仓逐任务，交付改为按序推进、逐任务提交；任务粒度判据与反例下沉 `task-spec.md`
+- `fxri-session-recap` 收尾时按仓逐任务建档，恢复时按任务正文的顺序线索重建执行顺序
+
+### ⚡ 优化改进
+
+- `fxri-plan-to-task` 的 references 改为按场景读取，普通建档不再提前加载迁移与模板细则
+- `fxri-plan-to-task` 1.9.0 压缩正文，`conventions-spec.md` 拆出存量迁移（`conventions-migration.md`）与文风模板（`conventions-templates.md`）两份按需加载 references，日常只读主文件
+- `fxri-session-recap` 1.5.0 合并重复纪律，规范载体细节改为指针，不再复述 `conventions-spec.md` 内容
+- `fxri-release-changelog` 1.2.0 精简触发词与失败模式说明，`changelog-format.md` 自查说明改为指向检测入口
+- `fxri-session-recap` 1.6.0 将模式二（恢复上下文）与模式三（历史时间修正）下沉为 `references/mode-2-recovery.md` / `mode-3-time-fix.md` 按需加载，主文件只留概要、关键护栏与读取指针，常用且高风险的模式一仍内联
+- `fxri-plan-to-task` 1.9.1 与 `fxri-session-recap` 的存量迁移、载体升级细节压缩为触发条件 + 指针，细则只在 `conventions-migration.md` 维护
+
+### 🐛 问题修复
+
+- 修正文档触达面清单的过期枚举，改为遍历 docs 全量页面，避免新增页面漏检
+- `fxri-release-changelog` 1.2.1 修正 `changelog-format.md` 文件结构示例仍带类型前缀、与「归类后剥离前缀」规则冲突
+
+### 📝 文档更新
+
+- `SPEC.md`、`README.md`、`docs/getting-started.md`、`docs/handbook.md`、`docs/guide.md` 同步开工门槛与逐任务交付口径
+- 移除全局规则页中重复的升级说明措辞
+- 明确不要把 SKILL.md 链接为常驻规则，并修正兄弟技能 references 的引用纪律
+- `skills/README.md`、`docs/guide.md` 技能版本表随各技能内容改动同步（当前 1.9.2 / 1.2.1 / 1.6.0）
+- `skills/README.md`、`docs/guide.md`、`docs/faq.md` 澄清技能加载口径——`description` 常驻用于匹配触发、正文触发时加载、`references/` 按需读取，不再声称「零上下文占用」「未声明不会自动介入」
+- 发布核对清单与单元测试新增加载体积守卫——主干 `SKILL.md` 不超过 8,000 字符
+
+### 🧹 清理移除
+
+- `AGENTS.md` 发版链路删除与「验收方式」重复的步骤定义指针，`docs/ai-rules.md` 删除与「规划先行」重复的稳定纪律条目
+
 ## 1.12.3
 
 > 2026-10-18 发布

package/README.md

@@ -31,7 +31,7 @@ pnpm exec toolkit init
 pnpm exec toolkit tasks
 ```
 
-之后：方案确认后登记为 `.tasks/` 任务文件 → `pnpm exec toolkit tasks check` 校验 → 完成后 `pnpm exec toolkit tasks archive` 归档并做规范沉淀。完整步骤见 [新手指南](./docs/getting-started.md)。
+之后：方案确认后登记为 `.tasks/` 任务文件 → `pnpm exec toolkit tasks check` 校验 → 完成后 `pnpm exec toolkit tasks archive` 归档并做规范沉淀。多任务 / 多仓方案先出纯展示计划表，再逐仓逐任务建档、按序逐个交付提交。完整步骤见 [新手指南](./docs/getting-started.md)。
 
 ## ✨ 能力矩阵
 
@@ -71,7 +71,7 @@ pnpm dlx skills add fxri-net/toolkit                  # 也可用上游安装器
 
 技能随包分发（真源为包内 `skills/`），与 CLI 同一发布批次（技能内容版本独立编号）；`toolkit skills install` 默认软链，链接创建失败自动降级副本，`toolkit skills status` 查现场，`toolkit skills remove` 卸载。`--scope project` 换项目面——真源落 `<仓库根>/.agents/skills/`、其余候选目录落入口薄壳，随 git 入库后队友 clone 靠 `toolkit init` 写入的 `prepare` 钩子自动补齐。
 
-- [fxri-plan-to-task](./skills/fxri-plan-to-task/SKILL.md)：方案确认后落盘为任务文件（动手前建档评估、check、归档 + 任务级规范沉淀为强制终点）
+- [fxri-plan-to-task](./skills/fxri-plan-to-task/SKILL.md)：方案确认后落盘为任务文件（任务分解与纯展示计划表、逐仓逐任务建档、check、归档 + 任务级规范沉淀为强制终点）
 - [fxri-release-changelog](./skills/fxri-release-changelog/SKILL.md)：发版时创建变更集、格式化多语言 CHANGELOG
 - [fxri-session-recap](./skills/fxri-session-recap/SKILL.md)：会话收尾全量沉淀、新会话三层恢复、历史任务时间批量修正（1.7.0 新增技能）
 

package/SPEC.md

@@ -1,6 +1,6 @@
 # 任务文件规范（SPEC）
 
-> 规范更新时间 2026-10-16 16:57。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
+> 规范更新时间 2026-10-19 15:35。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
 
 > 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
 >
@@ -12,9 +12,10 @@
 
 1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；active 已有同主题任务则更新原文件，禁止重复建档；已分叉成不同范围时问用户（拆新任务 or 合并更新）。archive 已有同主题任务（已归档完成）时按**改动判别**：本次不产生仓库文件改动（重复提议 / 重复执行）则不重复建档，仅提示「同主题任务已归档于 {日期}」；本次产生仓库文件改动（延续 / 扩展 / 重新实现）则重新建档，并在正文首行标注来源链 `延续 {原归档任务名}（见 archive/{YYYYMM}/{YYYYMMDD}.md）`；仅修正旧记录的时间或内容走历史修正（fxri-session-recap 模式三），不建档。**仓库文件改动口径**：需写入版本控制的工作区文件的增 / 改 / 删（源码、配置、文档、技能、任务区自身均计入），纯读取、纯执行、纯汇报不计入；拿不准时列出差异问用户，不猜。**归档块不可变**：已归档块不追加新的工作内容，延续需求一律走新任务；唯一例外是**事实更正**——后续核实推翻原块结论、或协作口径变更导致历史事实字段需更正时，在其正文末尾追加「修订记录」（保留原结论、附更正时刻与依据）；口径变更类更正可改受影响的**事实字段**（如 `scope`），但唯一键 / 完成时间 / 状态 / 负责人仍冻结。
 2. **任务唯一键**：`{YYYYMMDD}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
-3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions 载体），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。**动作不算，改动才算**：任务 = 已确认的方案 + 它落地的仓库文件改动；收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档，但当这些动作过程中出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误）时，该修复按普通任务建档。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。
+3. **收尾边界到沉淀**：强制约束到「归档 + 规范沉淀」为止——终结态任务归档后做任务级规范沉淀（写入 conventions 载体），归档 + 沉淀即流程终点；提交、发版、推送不是必经步骤，是否执行取决于用户的全局 / 个人 / 项目规则。**动作不算，改动才算**：任务 = 已确认的方案 + 它落地的仓库文件改动；收尾动作（提交、发版、推送、部署）本身及其固有产物（版本号、更新日志、标签）不构成任务、不单独建档，但当这些动作过程中出现需改仓库文件才能解决的缺陷（如打包配置错误、发布渠道错误）时，该修复按普通任务建档。若提交代码，先归档与沉淀、后提交，任务记录与代码变更落在同一 git 提交。**逐任务交付**：一个任务至少一次提交、允许多次；不得把多个任务攒成一个提交，也不得为凑一次提交塞入无关改动。
 4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
 5. **跨仓库改动各自归档**：任务档是**仓库自述**，只记本仓的改动与动机；跨仓库是**会话属性而非仓库属性**，同一会话涉及多仓时各仓各自建档归档，不在一仓记录里承载另一仓的工作痕迹。判据取**视角**（描述的是不是本仓的改动与动机），非词表——依赖包名 / 被调接口名等属本仓事实者照写。故 `scope` 只标本仓内的端 / 面（见第 2 节）。通用裁剪版见技能包 `task-spec.md`。
+6. **开工门槛与任务分解**：方案确认后、动手前先做任务分解——一个任务 = 可独立验收、可独立回滚、单独提交后仓库自洽的最小交付单元，且不跨仓库。涉及两个及以上任务时，先给出一张**纯展示的开发计划表**（跨端、跨仓同表，标明所属仓库与执行先后）；表只作展示与排序，不落档、不写入任务正文。随后**逐仓逐任务建档**：每个将产生仓库文件改动的仓库按任务清单各自独立建档，只读参与的仓库不建档，全部建档后再改第一处文件。按表顺序推进，前置未完成或阻塞未解除时下游不开工；计划调整先更新展示表再继续。任务粒度判据、表结构与反例见技能包 `task-spec.md`；状态以任务 frontmatter 为唯一真源。
 
 ## 1. 目录结构