@fxri/toolkit 1.5.6 → 1.6.0

package/SPEC.md

@@ -1,117 +1,119 @@
-# 任务文件规范（SPEC）
-
+# 任务文件规范（SPEC）
+
 > 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
-
-## 0. 协作模型
-
-任务区是**多写者共享**的：同一 `.tasks/` 可能被多人或多个 AI 参与。为避免互相覆盖，归档、归一化修复等工具内部写操作以排他锁（`.archive.lock`）防并发覆盖；人 / AI 的直接编辑遵循「先查后写」约定。约定：
-
-1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；已有则更新原文件，禁止重复建档。
-2. **任务唯一键**：`{年月日}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
-3. **归档与提交同批**：任务完成后先归档、再提交，保证任务记录与代码变更落在同一 git 提交。
-4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
-
-## 1. 目录结构
-
-```
-.tasks/
-├── active/                    # 实时任务（未完成）
-│   └── {年月}/                # YYYYMM，如 202609
-│       └── {年月日}-{用户名}-{任务简述}.md
-└── archive/                   # 任务归档（已完成）
-    └── {年月}/
-        └── {年月日}.md        # 某天归档
-```
-
-## 2. active 任务文件
-
-### 2.1 命名
-
-`{年月日}-{用户名}-{任务简述}.md`，示例 `20260902-唐启云-忘记密码.md`
-
-- `年月日` = 任务创建日，`YYYYMMDD` 直接拼（不加 `-`）
-- `用户名` = git 用户名
-- `任务简述` = 简短中文短语（不加空格）
-
-### 2.2 内容
-
-文件顶部为 frontmatter（两行 `---` 包裹的 YAML 键值块），随后为正文。
-
-```markdown
----
-owner: 唐启云
-status: 进行中
-created: 20260902
-updated: 20260902
-completed: ''
-depends_on: []
-scope: app
----
-
-# 任务标题
-```
-
-| 字段 | 类型 | 说明 |
-| --- | --- | --- |
-| owner | string | 负责人（git 用户名）；缺失时 `check` 软告警 |
-| status | enum | `待办` / `进行中` / `已完成` / `阻塞` / `已放弃` |
-| created | string | 创建日 `YYYYMMDD`，应等于文件名日期前缀；缺失/不一致/格式错误时 `check` 软告警 |
-| updated | string | 更新日 `YYYYMMDD` |
-| completed | string | 完成时间 `YYYY-MM-DD HH:mm`，`status` 为 `已完成`/`已放弃` 时必填；纯日期写法（`YYYY-MM-DD`）会被补齐 `00:00`，仅日期未补全完整时间会软告警 |
-| depends_on | array | 依赖任务文件名，引用可带 `.md` 扩展名（校验时自动归一为不含扩展名的 basename） |
-| scope | string | 影响范围 |
-
-> 文件名命名 `{年月日}-{用户名}-{任务简述}.md`（`年月日` = 创建日），不符规范或与 created 不一致时 `check` 软告警。
-
-## 3. archive 归档文件
-
-### 3.1 命名
-
-`{年月日}.md`，按任务**完成时间**的日期（`YYYYMMDD`）划分。
-
-### 3.2 内容
-
-同一天完成的任务整合进同一文件，**按完成时间降序排序**（最新在前），任务之间用 `---` 分隔。每个任务块必须含**元数据行**（`> ` 开头，四字段：负责人 / 状态 / 范围 / 完成时间），缺失或不完整时可由 `toolkit tasks normalize --fix` 补齐：
-
-```markdown
-# 20260902 归档
-
-## 20260902-唐启云-忘记密码
-
-> 负责人：唐启云　状态：已完成　范围：app　完成时间：2026-09-02 14:30
-
-# 忘记密码
-（正文）
-
----
-
-## 20260902-唐启云-其他任务
-
-> 负责人：唐启云　状态：已完成　范围：-　完成时间：2026-09-02 15:00
-
-（正文）
-```
-
-## 4. 归档规则
-
-1. 归档触发是**人工 / 事件驱动**，非定时任务；常见触发时机为任务完成、相关变更提交版本控制之前，此时应先行归档再提交。
-2. **任务级归档**：`status ∈ {已完成, 已放弃}` 且带 `completed` 的任务可归档。
-3. `待办` / `进行中` / `阻塞` 均不归档。
-4. 归档文件按 `completed` 的日期（`YYYYMMDD`）划分。
-5. 归档文件内任务按 `completed` **降序**排序（最新在前，`YYYY-MM-DD HH:mm` 定宽字符串比较即时间序）。
-6. **完成时间口径**：`completed` 只填真实收工时间，日期应与归档文件日期一致；不一致属「日期漂移」，`toolkit tasks normalize` 会检出，`--fix` 自动把漂移块迁移到对应日期文件（迁移前可用 `normalize` 只读检查）；归档文件放错月份目录（如 `archive/202608/20260903.md`）时 `--fix` 会将其移动到正确月份目录。
-7. **疑似任务块**：任务块判定要求标题后首个非空行为含「完成时间」的元数据行；形如 `{年月日}-{负责人}-{简述}` 的 `## ` 标题后跟 `> ` 元数据但缺「完成时间」时，会被视为疑似任务块并在 `normalize` 检出提示人工确认（不自动修复）。
-8. **并发归档防护**：归档采用排他锁（`.archive.lock`），检测到并发归档时跳过并告警；`--dry-run` 可预演归档动作而不落盘。
-
-## 5. 其他语言实现要点
-
-按本规范实现时，需覆盖：
-
-1. **frontmatter 解析**：读取文件顶部 `---` 之间的 `key: value` 行。
-2. **目录遍历**：`active/` 下仅一层年月子目录，收集 `.md` 文件。
-3. **完成时间提取**：从 frontmatter 的 `completed` 字段读取。
-4. **归档合并**：读取已有归档文件的任务块，与新任务合并后按 `completed` 排序，重写归档文件。
-5. **任务块分隔**：归档文件内任务以 `---` + `## ` 为边界，勿将正文内部的 `## ` 小节误判为任务边界。
-6. **敏感信息脱敏（可选）**：如需保护隐私，可在写归档前对正文自由文本做掩码；`owner` 等结构化字段保留原值。
-7. **校验（check）**：校验 active 任务 frontmatter 合法性（status 枚举、completed 必填与格式）、跨文件重名、`depends_on` 依赖存在性与成环。
-8. **归一化（normalize）**：校验归档块元数据四字段完整性、完成时间与归档日期一致性、降序排序；`--fix` 可补齐缺失元数据并重排。
+>
+> AI 工作流的技能化封装见 [skills/fxri-plan-to-task](./skills/fxri-plan-to-task/SKILL.md)（零依赖、跨项目复用）；本规范仍是任务文件格式的单一事实源。
+
+## 0. 协作模型
+
+任务区是**多写者共享**的：同一 `.tasks/` 可能被多人或多个 AI 参与。为避免互相覆盖，归档、归一化修复等工具内部写操作以排他锁（`.archive.lock`）防并发覆盖；人 / AI 的直接编辑遵循「先查后写」约定。约定：
+
+1. **先查后写**：新建、更新或归档任务前，先 `toolkit tasks` 查看 active 总览，并核对 archive 是否已有同主题任务；已有则更新原文件，禁止重复建档。
+2. **任务唯一键**：`{年月日}-{用户名}-{任务简述}` 唯一标识一个任务；多人对同一需求不得各自建档，应共用同一文件。
+3. **归档与提交同批**：任务完成后先归档、再提交，保证任务记录与代码变更落在同一 git 提交。
+4. **可执行项必须落地为任务**：方案正文里的「待办 / 待实施 / 待核对」等子项，应拆分为独立 active 任务，不留游离待办；`toolkit tasks check` 会扫描此类未闭合标记。
+
+## 1. 目录结构
+
+```
+.tasks/
+├── active/                    # 实时任务（未完成）
+│   └── {年月}/                # YYYYMM，如 202609
+│       └── {年月日}-{用户名}-{任务简述}.md
+└── archive/                   # 任务归档（已完成）
+    └── {年月}/
+        └── {年月日}.md        # 某天归档
+```
+
+## 2. active 任务文件
+
+### 2.1 命名
+
+`{年月日}-{用户名}-{任务简述}.md`，示例 `20260902-唐启云-忘记密码.md`
+
+- `年月日` = 任务创建日，`YYYYMMDD` 直接拼（不加 `-`）
+- `用户名` = git 用户名
+- `任务简述` = 简短中文短语（不加空格）
+
+### 2.2 内容
+
+文件顶部为 frontmatter（两行 `---` 包裹的 YAML 键值块），随后为正文。
+
+```markdown
+---
+owner: 唐启云
+status: 进行中
+created: 20260902
+updated: 20260902
+completed: ''
+depends_on: []
+scope: app
+---
+
+# 任务标题
+```
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| owner | string | 负责人（git 用户名）；缺失时 `check` 软告警 |
+| status | enum | `待办` / `进行中` / `已完成` / `阻塞` / `已放弃` |
+| created | string | 创建日 `YYYYMMDD`，应等于文件名日期前缀；缺失/不一致/格式错误时 `check` 软告警 |
+| updated | string | 更新日 `YYYYMMDD` |
+| completed | string | 完成时间 `YYYY-MM-DD HH:mm`，`status` 为 `已完成`/`已放弃` 时必填；纯日期写法（`YYYY-MM-DD`）会被补齐 `00:00`，仅日期未补全完整时间会软告警 |
+| depends_on | array | 依赖任务文件名，引用可带 `.md` 扩展名（校验时自动归一为不含扩展名的 basename） |
+| scope | string | 影响范围 |
+
+> 文件名命名 `{年月日}-{用户名}-{任务简述}.md`（`年月日` = 创建日），不符规范或与 created 不一致时 `check` 软告警。
+
+## 3. archive 归档文件
+
+### 3.1 命名
+
+`{年月日}.md`，按任务**完成时间**的日期（`YYYYMMDD`）划分。
+
+### 3.2 内容
+
+同一天完成的任务整合进同一文件，**按完成时间降序排序**（最新在前），任务之间用 `---` 分隔。每个任务块必须含**元数据行**（`> ` 开头，四字段：负责人 / 状态 / 范围 / 完成时间），缺失或不完整时可由 `toolkit tasks normalize --fix` 补齐：
+
+```markdown
+# 20260902 归档
+
+## 20260902-唐启云-忘记密码
+
+> 负责人：唐启云　状态：已完成　范围：app　完成时间：2026-09-02 14:30
+
+# 忘记密码
+（正文）
+
+---
+
+## 20260902-唐启云-其他任务
+
+> 负责人：唐启云　状态：已完成　范围：-　完成时间：2026-09-02 15:00
+
+（正文）
+```
+
+## 4. 归档规则
+
+1. 归档触发是**人工 / 事件驱动**，非定时任务；常见触发时机为任务完成、相关变更提交版本控制之前，此时应先行归档再提交。
+2. **任务级归档**：`status ∈ {已完成, 已放弃}` 且带 `completed` 的任务可归档。
+3. `待办` / `进行中` / `阻塞` 均不归档。
+4. 归档文件按 `completed` 的日期（`YYYYMMDD`）划分。
+5. 归档文件内任务按 `completed` **降序**排序（最新在前，`YYYY-MM-DD HH:mm` 定宽字符串比较即时间序）。
+6. **完成时间口径**：`completed` 只填真实收工时间，日期应与归档文件日期一致；不一致属「日期漂移」，`toolkit tasks normalize` 会检出，`--fix` 自动把漂移块迁移到对应日期文件（迁移前可用 `normalize` 只读检查）；归档文件放错月份目录（如 `archive/202608/20260903.md`）时 `--fix` 会将其移动到正确月份目录。
+7. **疑似任务块**：任务块判定要求标题后首个非空行为含「完成时间」的元数据行；形如 `{年月日}-{负责人}-{简述}` 的 `## ` 标题后跟 `> ` 元数据但缺「完成时间」时，会被视为疑似任务块并在 `normalize` 检出提示人工确认（不自动修复）。
+8. **并发归档防护**：归档采用排他锁（`.archive.lock`），检测到并发归档时跳过并告警；`--dry-run` 可预演归档动作而不落盘。
+
+## 5. 其他语言实现要点
+
+按本规范实现时，需覆盖：
+
+1. **frontmatter 解析**：读取文件顶部 `---` 之间的 `key: value` 行。
+2. **目录遍历**：`active/` 下仅一层年月子目录，收集 `.md` 文件。
+3. **完成时间提取**：从 frontmatter 的 `completed` 字段读取。
+4. **归档合并**：读取已有归档文件的任务块，与新任务合并后按 `completed` 排序，重写归档文件。
+5. **任务块分隔**：归档文件内任务以 `---` + `## ` 为边界，勿将正文内部的 `## ` 小节误判为任务边界。
+6. **敏感信息脱敏（可选）**：如需保护隐私，可在写归档前对正文自由文本做掩码；`owner` 等结构化字段保留原值。
+7. **校验（check）**：校验 active 任务 frontmatter 合法性（status 枚举、completed 必填与格式）、跨文件重名、`depends_on` 依赖存在性与成环。
+8. **归一化（normalize）**：校验归档块元数据四字段完整性、完成时间与归档日期一致性、降序排序；`--fix` 可补齐缺失元数据并重排。

package/TRADEMARK.md

@@ -1,47 +1,47 @@
-# 商标声明
-
-## 基本信息
-
-| 项目 | 内容 |
-|---|---|
-| 商标名称 | 方弦™ |
-| 商标类型 | 文字商标 |
-| 商标说明 | 商标由文字"方弦"组成 |
-| 商标类别 | 第 42 类（共 10 项） |
-| 注册号 | 89648411 |
-| 申请人 | 唐启云 |
-| 递交商标局 | 2026-01-12 |
-| 版本 | 基础版 |
-
-## 第 42 类服务项目
-
-计算机出租；计算机软件设计；为他人研究和开发新产品；计算机软件维护；把有形的数据或文件转换成电子媒体；为他人创建和维护网站；网络服务器出租；提供互联网搜索引擎；托管计算机站（网站）；云计算。
-
-## 权利状态
-
-本商标已向中国国家知识产权局商标局递交注册申请（申请号：89648411，递交日：2026-01-12），**目前尚未核准注册**。
-
-在核准注册前，本商标标注为"方弦™"，仅用于指明该名称的归属，不构成注册商标声明。
-
-## 授权范围
-
-本仓库的开源许可证（MIT License）仅授予代码的使用、修改和分发权利，**不构成对任何商标、服务标记或品牌名称的授权许可**。
-
-任何派生作品、修改版本、商业产品均不得使用"方弦"名称、Logo 或相关标识，除非获得书面授权。
-
-## 使用规范
-
-- 在开源社区讨论、文档引用中提及本项目时，可使用"方弦™"指代本项目名称
-- 未经书面授权，不得在任何商业产品、服务或宣传材料中使用"方弦"标识
-
-## 获取授权
-
-如需将"方弦"商标用于商业用途，请联系：唐启云 <tqy@fxri.net>
-
-## 侵权处理
-
-如发现未经授权使用"方弦"商标的行为，请通过上述联系方式举报。
-
----
-
-*本声明随商标审查进度更新。*
+# 商标声明
+
+## 基本信息
+
+| 项目 | 内容 |
+|---|---|
+| 商标名称 | 方弦™ |
+| 商标类型 | 文字商标 |
+| 商标说明 | 商标由文字"方弦"组成 |
+| 商标类别 | 第 42 类（共 10 项） |
+| 注册号 | 89648411 |
+| 申请人 | 唐启云 |
+| 递交商标局 | 2026-01-12 |
+| 版本 | 基础版 |
+
+## 第 42 类服务项目
+
+计算机出租；计算机软件设计；为他人研究和开发新产品；计算机软件维护；把有形的数据或文件转换成电子媒体；为他人创建和维护网站；网络服务器出租；提供互联网搜索引擎；托管计算机站（网站）；云计算。
+
+## 权利状态
+
+本商标已向中国国家知识产权局商标局递交注册申请（申请号：89648411，递交日：2026-01-12），**目前尚未核准注册**。
+
+在核准注册前，本商标标注为"方弦™"，仅用于指明该名称的归属，不构成注册商标声明。
+
+## 授权范围
+
+本仓库的开源许可证（MIT License）仅授予代码的使用、修改和分发权利，**不构成对任何商标、服务标记或品牌名称的授权许可**。
+
+任何派生作品、修改版本、商业产品均不得使用"方弦"名称、Logo 或相关标识，除非获得书面授权。
+
+## 使用规范
+
+- 在开源社区讨论、文档引用中提及本项目时，可使用"方弦™"指代本项目名称
+- 未经书面授权，不得在任何商业产品、服务或宣传材料中使用"方弦"标识
+
+## 获取授权
+
+如需将"方弦"商标用于商业用途，请联系：唐启云 <tqy@fxri.net>
+
+## 侵权处理
+
+如发现未经授权使用"方弦"商标的行为，请通过上述联系方式举报。
+
+---
+
+*本声明随商标审查进度更新。*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fxri/toolkit",
-  "version": "1.5.6",
+  "version": "1.6.0",
   "description": "专为多人 + AI 跨项目协作打造：任务管理 + 多语言 CHANGELOG。",
   "license": "MIT",
   "author": {
@@ -32,6 +32,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "SPEC.md",
     "CHANGELOG.md",
@@ -40,6 +41,19 @@
     "NOTICE",
     "package.json"
   ],
+  "scripts": {
+    "dev": "pnpm build:debug && node ./dist/cli.js",
+    "build": "cross-env NODE_ENV=production tsup",
+    "build:debug": "cross-env NODE_ENV=development tsup --config tsup.dev.config.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --cache",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "changeset": "changeset",
+    "release": "pnpm build && pnpm publish"
+  },
   "keywords": [
     "toolkit",
     "task",
@@ -63,24 +77,12 @@
     "typescript-eslint": "^8.69.0",
     "vitest": "^4.1.11"
   },
+  "packageManager": "pnpm@10.34.4",
   "engines": {
     "node": ">=20"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
-  },
-  "scripts": {
-    "dev": "pnpm build:debug && node ./dist/cli.js",
-    "build": "cross-env NODE_ENV=production tsup",
-    "build:debug": "cross-env NODE_ENV=development tsup --config tsup.dev.config.ts",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint . --cache",
-    "lint:fix": "eslint . --fix",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "changeset": "changeset",
-    "release": "pnpm build && pnpm publish"
   }
-}
+}

package/skills/README.md

@@ -0,0 +1,52 @@
+# 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`
+
+### 方式二：手工复制 / 软链
+
+- 复制或软链技能目录到 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,72 @@
+---
+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` 预演）
+- 任务目录非默认 `.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，任务记录与代码变更落在同一提交