@fxri/toolkit 1.9.2 → 1.9.4

package/README.md

@@ -16,7 +16,7 @@
 AI 参与开发后，方案与决策散落在对话记录里，会话一关什么都不剩；任务记录零散，谁在做、做到哪，无从查起；发版 CHANGELOG 还要人肉维护多语言。本工具把这条链路沉淀为**仓库内可检索、可校验、可归档的文件**——人离开会话，记忆留在仓库里。
 
 - **零依赖 AI 技能包（skills）**：方案落盘、发版 CHANGELOG 两套工作流沉淀为 Agent Skills，不绑定任何 AI 工具；skills 可以独立工作，CLI 是可选加速——推荐都装，体验最完整（[什么关系？](./docs/faq.md#工具和-skills-都得装吗)）
-- **不懂 AI 也能用**：任务管理与 CHANGELOG 是纯 CLI 能力；术语都说了人话（[先看术语表](./docs/getting-started.md#几个术语先说人话)）
+- **不懂 AI 也能用**：任务管理与 CHANGELOG 是纯 CLI 能力；术语都说了人话（[先看术语表](./docs/getting-started.md#几个术语-先说人话)）
 
 ## 🚀 30 秒上手
 
@@ -38,7 +38,7 @@ pnpm exec toolkit tasks
 | 能力 | 适用场景 | 文档 |
 | --- | --- | --- |
 | 任务管理（tasks） | 方案落盘、总览过滤、校验归档、导入导出 CSV / XLSX / JSON | [CLI 参考](./docs/cli.md) · [任务文件规范](./docs/guide.md#任务文件规范) |
-| 多语言 CHANGELOG（changelog） | 封装 changesets 发版、分组标题本地化 | [CLI 参考](./docs/cli.md#changelog-changelog) |
+| 多语言 CHANGELOG（changelog） | 封装 changesets 发版、分组标题本地化 | [CLI 参考](./docs/cli.md#changelog) |
 | Node API | 把上述能力嵌进脚本或平台 | [API 参考](./docs/api.md) |
 | 隐私脱敏 | 落盘前自动掩码邮箱、手机号、密钥等 | [配置参考](./docs/config.md) |
 | AI 技能包（skills） | 不装本工具也能让 AI 按同一套规范干活；装了可一键分发技能 | [完整攻略](./docs/guide.md#ai-技能包-skills) · [FAQ](./docs/faq.md#工具和-skills-都得装吗) |
@@ -54,8 +54,10 @@ pnpm exec toolkit tasks
 | [CLI 参考](./docs/cli.md) | 查命令、参数、默认值、退出码 |
 | [API 参考](./docs/api.md) | 作为库引入 Node 项目 |
 | [配置参考](./docs/config.md) | 查 `.toolkitrc.json` 字段 |
+| [更新日志](./docs/changelog.md) | 查各版本变更内容 |
 | [FAQ](./docs/faq.md) | 遇到问题先来这里找 |
 | [推荐 AI 全局规则](./docs/ai-rules.md) | 想让 AI 助手按本工具的最佳实践协作 |
+| [推荐提交信息规则](./docs/commit-rules.md) | 想让 AI 按统一格式写 git 提交信息 |
 | [完整文档站](https://fxri-net.github.io/toolkit/) | 在线阅读体验 |
 
 ## 🧩 AI 技能包（skills）

package/SPEC.md

@@ -1,6 +1,6 @@
 # 任务文件规范（SPEC）
 
-> 规范版本 1.0。本规范内容变更时同批递增此版本号，实现方与规范快照据此对照是否失同步。
+> 规范更新时间 2026-09-14 15:17。本规范内容变更时以变更时刻更新此值，实现方与规范快照据此对照是否失同步。
 
 > 本规范**全语言支持**，面向**多人 + AI 跨项目协作**，定义任务文件的目录结构、文件格式与归档规则。任何编程语言均可按本规范实现读写；@fxri/toolkit 的 `tasks` 域仅为参考实现。
 >
@@ -105,8 +105,8 @@ scope: app
 4. 归档文件按 `completed` 的日期（`YYYYMMDD`）划分。
 5. 归档文件内任务按 `completed` **降序**排序（最新在前，`YYYY-MM-DD HH:mm` 定宽字符串比较即时间序）。
 6. **完成时间口径**：`completed` 只填真实收工时间（四级时间源取证），日期应与归档文件日期一致；不一致属「日期漂移」，`toolkit tasks normalize` 会检出，`--fix` 自动把漂移块迁移到对应日期文件（迁移前可用 `normalize` 只读检查）；归档文件放错月份目录（如 `archive/202608/20260903.md`）时 `--fix` 会将其移动到正确月份目录。⚠️ 补档 / 历史时间修正场景下，归档块的完成时间早于归档动作时间是正常的——修正块时间后执行 `normalize --fix` 即完成迁移。
-7. **疑似任务块**：任务块判定要求标题后首个非空行为含「完成时间」的元数据行；形如 `{年月日}-{负责人}-{简述}` 的 `## ` 标题后跟 `> ` 元数据但缺「完成时间」时，会被视为疑似任务块并在 `normalize` 检出提示人工确认（不自动修复）。
-8. **并发归档防护**：归档采用排他锁（`.archive.lock`），检测到并发归档时跳过并告警；`--dry-run` 可预演归档动作而不落盘。
+7. **任务块边界与疑似任务块**：任务块边界以块间 `---` 分隔符为唯一权威边界，`## 标题` 与 `> 元数据` 行仅作校验项（缺失或不全时仍解析为块，由 `normalize` 检出并提示）；正文内部形如 `{年月日}-{负责人}-{简述}` 的 `## ` 标题会被视为疑似任务块并在 `normalize` 检出提示人工确认（不自动修复）。
+8. **并发归档防护**：归档采用排他锁（`.archive.lock`），检测到并发归档时跳过并告警；`--dry-run` 可预演归档动作而不落盘。锁须具备自愈语义——持有进程已退出，或锁龄超过实现约定的绝对上限（兜底 pid 复用导致的「假存活」）时，后续写操作接管该锁而非永久阻塞；正常的并发写者仍按跳过处理。
 
 ## 5. 其他语言实现要点
 
@@ -116,7 +116,7 @@ scope: app
 2. **目录遍历**：`active/` 下仅一层年月子目录，收集 `.md` 文件。
 3. **完成时间提取**：从 frontmatter 的 `completed` 字段读取。
 4. **归档合并**：读取已有归档文件的任务块，与新任务合并后按 `completed` 排序，重写归档文件。
-5. **任务块分隔**：归档文件内任务以 `---` + `## ` 为边界，勿将正文内部的 `## ` 小节误判为任务边界。
+5. **任务块分隔**：归档文件内任务以块间 `---` 为唯一权威边界（`## 标题` 与 `> 元数据` 行仅作校验项），勿将正文内部的 `## ` 小节误判为任务边界。
 6. **敏感信息脱敏（可选）**：如需保护隐私，可在写归档前对正文自由文本做掩码；`owner` 等结构化字段保留原值。
 7. **校验（check）**：校验 active 任务 frontmatter 合法性（status 枚举、completed 必填与格式）、跨文件重名、`depends_on` 依赖存在性与成环、范围字段形态软告警（顿号/逗号/括号）。
 8. **归一化（normalize）**：校验归档块元数据四字段完整性、完成时间与归档日期一致性、降序排序、范围字段形态（顿号/逗号疑似多值分隔可 `--fix` 归一为半角加号，括号疑似注释仅提示人工）；`--fix` 可补齐缺失元数据并重排。

package/TRADEMARK.md

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