@fxri/toolkit 1.5.5 → 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>
+
+## 侵权处理
+
+如发现未经授权使用"方弦"商标的行为，请通过上述联系方式举报。
+
+---
+
+*本声明随商标审查进度更新。*