@fxri/toolkit 1.5.6 → 1.6.1

package/skills/README.md

@@ -0,0 +1,53 @@
+# 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) | 方案落盘：先查后写 → 建档 → 校验 → 归档 → 归档提交同批 |
+| [fxri-release-changelog](./fxri-release-changelog/SKILL.md) | changesets 发版与多语言 CHANGELOG 维护 |
+
+## 安装
+
+### 方式一：`npx skills` 自动安装（推荐）
+
+本仓库遵循 Agent Skills 开放标准，兼容 [vercel-labs/skills](https://github.com/vercel-labs/skills) 安装器（自动识别本机 agent、写锁定文件）：
+
+```bash
+npx skills add fxri-net/toolkit                          # 安装全部技能
+npx skills add fxri-net/toolkit --skill fxri-plan-to-task # 只装单个技能
+npx skills list / update / remove                        # 查看 / 升级 / 卸载
+```
+
+- 项目级安装默认写 `.agents/skills/` 并对各 agent（Claude Code / Cursor / Codex 等 75+）目录建立符号链接；团队项目把生成的 `skills-lock.json` 提交进仓库以对齐版本，单人可加 `-g` 全局安装
+- ⚠️ 已知上游行为（v1.5.x）：项目级安装时若 `.claude/` 目录不存在，Claude Code 目标会被静默跳过——先创建 `.claude/skills/` 空目录或改用 `-g`
+
+### 方式二：手工复制 / 软链
+
+- 已安装 `@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` 指向本仓库）。
+
+## 与其他 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 相对路径有效

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

@@ -0,0 +1,73 @@
+---
+name: fxri-plan-to-task
+description: 将已确认的实施方案落盘为标准任务文件并跟踪至归档：先查后写防重复建档、按模板建档、状态机更新、自查校验、手工归档与归档提交同批。当用户确认方案后要求登记或落盘任务、提到建档、任务登记、归档、任务校验时使用。不用于与方案落盘无关的普通 TODO、issue 管理或日常提交信息撰写。
+license: MIT
+metadata:
+  version: "1.0.0"
+  author: fxri
+  source: https://github.com/fxri-net/toolkit
+---
+
+# 方案落盘：任务建档与归档
+
+## 何时使用
+
+- 用户确认实施方案后，需要把方案登记为任务文件持续跟踪
+- 触发词：方案落盘 / 建档 / 任务登记 / 归档 / 任务校验
+
+**何时不使用**：与方案落盘无关的普通 TODO、issue 管理、日历待办。
+
+## 核心约定
+
+任务文件规范（目录结构、命名、frontmatter 字段、归档格式、手工归档步骤、自查清单）全部以 `references/task-spec.md` 为准，本文件只写流程。执行任何写操作前先读它。
+
+## 工作流
+
+### 1. 先查后写（防重复建档）
+
+- 列出任务目录 `active/` 下全部 `.md`（含一层 `{YYYYMM}/` 月份子目录），并核对 `archive/` 是否已有同主题任务
+- 已有同主题任务：更新原文件，禁止新建
+- 任务唯一键：`{年月日}-{用户名}-{任务简述}`；多人对同一需求共用一个文件
+
+### 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 源文件 → 清理空月份目录。
+
+### 6. 归档提交同批（硬约束）
+
+先归档、后提交：任务归档文件必须与本次代码变更落在**同一个 git 提交**，顺序不可颠倒。避免任务完成却滞留 `active/` 未归档，或归档单独成一条提交。
+
+## 失败模式
+
+| 症状 | 处置 |
+| --- | --- |
+| active 下出现同名任务文件 | 重复建档，合并为一个后删除多余 |
+| completed 日期与文件名创建日不一致 | 核对是否填错；确为跨天完成则以 completed 日期归档 |
+| depends_on 引用的任务已归档 | 正常，依赖随之解除；引用拼写错误则修正 |
+| 并发写归档文件互相覆盖 | 归档前确认无其他写者同时操作；冲突时以重排后完整合并为准 |
+
+## 可选加速（不构成依赖）
+
+项目已安装 @fxri/toolkit 时，可用命令替代对应手工步骤，缺失不影响主流程：
+
+- `toolkit tasks`：查 active 总览（替代第 1 步人工翻目录）
+- `toolkit tasks check`：自动校验（替代第 4 步自查清单）
+- `toolkit tasks archive`：自动归档（替代第 5 步，含排他锁防并发；可 `--dry-run` 预演）
+- `toolkit tasks normalize`：归档后核验归档块（元数据完整性/日期漂移/排序），可 `--fix` 自动修复
+- 任务目录非默认 `.tasks` 时加 `--dir <path>`

package/skills/fxri-plan-to-task/assets/active-task-template.md

@@ -0,0 +1,13 @@
+---
+owner: <负责人 git 用户名>
+status: 待办
+created: <创建日 YYYYMMDD>
+updated: <创建日 YYYYMMDD，随每次修改同步>
+completed: ''
+depends_on: []
+scope: <影响范围>
+---
+
+# 任务标题
+
+（方案正文：背景、实施方案、影响范围、验证方式）

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

@@ -0,0 +1,85 @@
+# 任务文件规范（通用版）
+
+> 面向多人 + AI 协作，任何语言项目可直接使用，仅依赖文件读写能力。本文件为 SKILL.md 的配套规范；fxri 生态内实现级权威版本见 toolkit 仓库 SPEC.md。
+
+## 1. 目录结构
+
+```
+.tasks/
+├── active/                    # 进行中的任务
+│   └── {YYYYMM}/              # 月份子目录，如 202609
+│       └── {YYYYMMDD}-{用户名}-{任务简述}.md
+└── archive/                   # 已终结任务归档
+    └── {YYYYMM}/
+        └── {YYYYMMDD}.md      # 按完成日期归组的归档文件
+```
+
+目录名 `.tasks` 为默认约定，项目可自定（如集中式任务库按项目分子目录），内部子结构不变。
+
+## 2. active 任务文件
+
+### 2.1 命名
+
+`{YYYYMMDD}-{用户名}-{任务简述}.md`
+
+- 年月日 = 任务创建日，`YYYYMMDD` 直接拼接（不加 `-`）
+- 用户名 = git 用户名；任务简述 = 不含空格的短语
+
+### 2.2 frontmatter
+
+```yaml
+---
+owner: 唐启云          # 负责人（git 用户名）
+status: 进行中         # 待办 / 进行中 / 阻塞 / 已完成 / 已放弃
+created: 20260902     # 创建日 YYYYMMDD，须等于文件名日期前缀
+updated: 20260902     # 最近更新日 YYYYMMDD
+completed: ''         # 完成时间 YYYY-MM-DD HH:mm；仅终结态必填
+depends_on: []        # 依赖的任务文件名（可带 .md），目标必须存在且不得成环
+scope: app            # 影响范围
+---
+```
+
+- `已完成` / `已放弃` 为终结态：进入时必须补 `completed`（真实收工时间）
+- 正文以 `# 任务标题` 开头；游离待办子项必须拆为独立任务文件
+
+## 3. 归档文件
+
+- 命名 `{YYYYMMDD}.md`，日期 = 任务完成时间日期；放入 `archive/{YYYYMM}/`
+- 文件头：`# {YYYYMMDD} 归档` + 引言（如自动生成说明）
+- 每个任务块：
+
+```markdown
+## {年月日}-{用户名}-{任务简述}
+
+> 负责人：{owner}　状态：{status}　范围：{scope}　完成时间：{completed}
+
+（任务正文）
+```
+
+- 块间以 `---` 分隔；**全文件按完成时间降序**（最新在前）
+- 元数据行以 `> ` 开头、四字段齐全、以全角空格分隔
+
+## 4. 手工归档步骤（有序）
+
+1. 确认任务 status 为终结态且 `completed` 已填
+2. 计算目标文件 `archive/{completed 的 YYYYMM}/{completed 的 YYYYMMDD}.md`
+3. 读取已有归档文件（不存在则新建含文件头），把任务块加入
+4. 全文件按 `completed` 降序重排，块间补 `---` 分隔
+5. 写回归档文件
+6. 删除 active 源文件；月份子目录与 `active/` 若已空则一并删除
+
+## 5. 自查清单（校验）
+
+- [ ] frontmatter 存在且七字段齐全
+- [ ] status 为五枚举之一；终结态已填 completed
+- [ ] completed 为 `YYYY-MM-DD HH:mm` 且日期真实存在
+- [ ] created 为 YYYYMMDD 且等于文件名日期前缀
+- [ ] 文件名符合 `{YYYYMMDD}-{用户名}-{任务简述}.md`
+- [ ] active 内无跨文件同名任务
+- [ ] depends_on 目标存在且无循环依赖
+- [ ] 正文无「待实施 / 待核对 / 待评估 / TODO」等游离标记与未勾选的 `- [ ]`
+
+## 6. 协作约定
+
+- 任务区是多写者共享区：先查后写，同一需求共用一个任务文件
+- 归档与提交同批：先归档、后 git commit，任务记录与代码变更落在同一提交

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

@@ -0,0 +1,54 @@
+---
+name: fxri-release-changelog
+description: 基于 changesets 的发版与多语言 CHANGELOG 维护流程：创建变更集、消费发版、把分组标题与条目转为项目语言风格、清理变更集、打标签发布；无 changesets 的项目提供同格式手工模式。当用户提到创建变更集、changeset、发版、version、整理或格式化 CHANGELOG 时使用。不用于日常 commit message 撰写或与发版无关的文档修改。
+license: MIT
+metadata:
+  version: "1.0.0"
+  author: fxri
+  source: https://github.com/fxri-net/toolkit
+---
+
+# 发版与 CHANGELOG
+
+## 何时使用
+
+- 记录变更（创建变更集）、消费变更集发版、格式化 CHANGELOG
+- 触发词：changeset / 变更集 / 发版 / version / CHANGELOG 格式化
+
+**何时不使用**：日常 commit message 撰写、与发版无关的文档修改。
+
+## 前置检查
+
+- 项目根存在 `.changeset/` 目录 → 走「changesets 流程」
+- 不存在 → 走「手工模式」（规范见 `references/changelog-format.md`）
+
+## changesets 流程
+
+1. 记录变更：`npx changeset`（或项目包管理器等价脚本），按影响选 patch / minor / major 并写变更描述
+2. 消费发版：`npx changeset version`——自动写版本号与 CHANGELOG
+3. 格式化：按 `references/changelog-format.md` 转换分组标题、润色条目为项目语言风格（中文示例：`### Patch Changes` → `### 🐛 补丁修复`）
+4. 清理：删除已消费的 `.changeset/*.md`
+5. 发布：提交版本与 CHANGELOG 改动 → 打 `vX.Y.Z` 标签 → 按项目渠道发布（如 `npm publish`）
+
+⚠️ 自动生成的条目必须人工核对润色，与仓库既有 CHANGELOG 风格保持一致。
+
+## 手工模式（无 changesets 项目）
+
+版本号与 CHANGELOG 全部手工维护：版本标题、发布日期行、分组标题与条目格式见 `references/changelog-format.md`；多语言三段结构（标题替换映射 / 依赖更新文案 / 发布日期后缀）同文件。
+
+## 失败模式
+
+| 症状 | 处置 |
+| --- | --- |
+| version 后 CHANGELOG 分组标题仍是英文 | 按 references 的映射表补一次格式化 |
+| 条目与仓库既有风格不一致 | 人工润色为项目语言与句式，勿保留机器直译 |
+| 变更集遗漏（发版后才发现功能未记录） | 补建变更集随下次发版；本次在发布说明中人工补充 |
+
+## 可选加速（不构成依赖）
+
+项目已安装 @fxri/toolkit 时，可用命令替代对应手工步骤，缺失不影响主流程：
+
+- `toolkit changelog`：创建变更集（等价 changeset）
+- `toolkit changelog version`：发版并自动做中文分组标题格式化
+- `toolkit changelog format`：仅格式化既有 CHANGELOG
+- `toolkit changelog --lang <语言> …`：切换输出语言（内置 zh / en，其余可配置扩展）

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

@@ -0,0 +1,40 @@
+# CHANGELOG 格式规范
+
+## 1. 文件结构（中文示例）
+
+```markdown
+## 1.5.3
+> 2026-09-03 发布
+
+### 🐛 补丁修复
+
+- 修复 xxx：……
+```
+
+规则：
+
+- 版本标题 `## {版本号}`；紧随引用行 `> {YYYY-MM-DD} 发布`
+- 分组标题 = emoji + 组名，一行一组，按 major → minor → patch 顺序
+- 条目一行一条，项目语言句式（中文条目句末不加句号），与仓库既有风格一致
+
+## 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」）
+
+新增语言时先补全三段，再按映射转换标题、润色条目。