@fxri/toolkit 1.5.5 → 1.6.0

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」）
+
+新增语言时先补全三段，再按映射转换标题、润色条目。