@double-codeing/flow2spec 3.1.0 → 3.1.2

package/templates/hooks/f2s-update-check.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * flow2spec SessionStart hook — 每天第一次对话时检查版本更新。
+ * 比较本地知识库 manifest-routing.json 的 version 与 npm 最新版本：
+ *   - 一致或本地更新 → 静默退出
+ *   - 落后 → 向 Agent 上下文注入一行提示（建议执行 f2s-kb-upgrade）
+ * 已检查过且无需升级则静默；已检查且仍需升级时，每个新会话继续注入提醒。
+ * 由 flow2spec init 写入对应 agent 的 hooks/f2s-update-check.js。
+ */
+const fs   = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const MANIFEST_PATH = path.join(process.cwd(), '.Knowledge', 'manifest-routing.json');
+const CACHE_DIR    = path.join(process.cwd(), '.Knowledge');
+const CACHE_FILE   = path.join(CACHE_DIR, 'update-check.json');
+const PACKAGE_NAME_PLACEHOLDER = '__FLOW2SPEC_' + 'PACKAGE_NAME__';
+const PACKAGE_NAME = '__FLOW2SPEC_PACKAGE_NAME__';
+
+// ── 缓存 ────────────────────────────────────────────────────────────────────
+
+function readCache() {
+  if (!fs.existsSync(CACHE_FILE)) return null;
+  try {
+    const d = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+    if (!d || typeof d !== 'object') return null;
+    const checkedAt = Number(d.checkedAt || 0);
+    if (!checkedAt) return null;
+    if (new Date(checkedAt).toDateString() !== new Date().toDateString()) return null;
+    return d;
+  } catch (_) { return null; }
+}
+
+function getProjectName() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+    if (pkg && pkg.name) return String(pkg.name);
+  } catch (_) {}
+  return path.basename(process.cwd());
+}
+
+function buildNotice(latestNpm, manifestVersion) {
+  const userMsg = `📦 [flow2spec] 当前项目「${getProjectName()}」知识库版本 v${manifestVersion}，低于最新包版本 v${latestNpm}。可执行 f2s-kb-upgrade skill 对齐模板与路由。`;
+  return [
+    `[flow2spec/agent-instruction] 你必须在本轮回复开头将下列升级提示原文转告用户，不得省略、不得仅在内部判断后跳过：`,
+    ``,
+    userMsg,
+  ].join('\n');
+}
+
+function emitNotice(notice) {
+  process.stdout.write(
+    JSON.stringify({
+      additional_context: notice,
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: notice,
+      },
+    }) + '\n'
+  );
+}
+
+function writeCache(latestNpm, manifestVersion) {
+  try {
+    const needsUpgrade = cmpVer(manifestVersion, latestNpm) < 0;
+    fs.writeFileSync(
+      CACHE_FILE,
+      `${JSON.stringify({
+        latestNpm,
+        manifestVersion,
+        needsUpgrade,
+        notice: needsUpgrade ? buildNotice(latestNpm, manifestVersion) : '',
+        checkedAt: Date.now(),
+      }, null, 2)}\n`,
+      'utf8'
+    );
+  } catch (_) {}
+}
+
+function deleteCache() {
+  try {
+    if (fs.existsSync(CACHE_FILE)) fs.unlinkSync(CACHE_FILE);
+  } catch (_) {}
+}
+
+// ── 版本比较 ─────────────────────────────────────────────────────────────────
+
+function parseVer(v) {
+  return String(v || '').replace(/^v/, '').split(/[.-]/).slice(0, 3).map((p) => {
+    const n = Number.parseInt(p, 10);
+    return Number.isFinite(n) ? n : 0;
+  });
+}
+
+/** a < b → 负数；a === b → 0；a > b → 正数 */
+function cmpVer(a, b) {
+  const av = parseVer(a), bv = parseVer(b);
+  for (let i = 0; i < 3; i++) {
+    const d = (av[i] || 0) - (bv[i] || 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+// ── 读取 ─────────────────────────────────────────────────────────────────────
+
+function getManifestVersion() {
+  if (!fs.existsSync(MANIFEST_PATH)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8')).version || null;
+  } catch (_) { return null; }
+}
+
+function getPackageName() {
+  if (PACKAGE_NAME && PACKAGE_NAME !== PACKAGE_NAME_PLACEHOLDER) {
+    return PACKAGE_NAME;
+  }
+  return '@double-codeing/flow2spec';
+}
+
+function queryNpmLatest(pkgName) {
+  return execFileSync('npm', ['view', pkgName, 'version'], {
+    encoding: 'utf8',
+    timeout: 5000,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+}
+
+// ── 配置开关 ──────────────────────────────────────────────────────────────────
+
+function isEnabled() {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(
+      path.join(process.cwd(), 'flow2spec.config.json'), 'utf8'
+    ));
+    const uc = cfg && cfg.updateCheck;
+    if (uc && typeof uc.enabled === 'boolean') return uc.enabled;
+    return true;
+  } catch (_) { return true; }
+}
+
+// ── 主流程 ────────────────────────────────────────────────────────────────────
+
+function main() {
+  if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) return;
+  if (!isEnabled()) return;
+  const cache = readCache();
+  if (cache) {
+    // 今天已检查过则不重复查 npm；若缓存显示仍需升级，每个新会话继续提醒。
+    const needsUpgrade = cache.needsUpgrade === true ||
+      cmpVer(cache.manifestVersion, cache.latestNpm) < 0;
+    if (needsUpgrade) {
+      const currentManifestVersion = getManifestVersion();
+      if (currentManifestVersion && cache.latestNpm &&
+          cmpVer(currentManifestVersion, cache.latestNpm) >= 0) {
+        deleteCache();
+        return;
+      }
+      // SessionStart 进入新会话：缓存命中且仍需升级，直接 emit。
+      const notice = buildNotice(cache.latestNpm, cache.manifestVersion);
+      emitNotice(notice);
+    }
+    return;
+  }
+
+  const manifestVersion = getManifestVersion();
+  if (!manifestVersion) return;  // 无知识库，跳过
+
+  let latestNpm;
+  try {
+    const pkgName = getPackageName();
+    latestNpm = queryNpmLatest(pkgName);
+  } catch (_) {
+    return;  // 网络不通，静默退出，不写缓存（下次还会重试）
+  }
+
+  // 写缓存（无论是否需要升级，今天不再重复检查）
+  writeCache(latestNpm, manifestVersion);
+
+  if (cmpVer(manifestVersion, latestNpm) >= 0) return;  // 已是最新
+
+  const notice = buildNotice(latestNpm, manifestVersion);
+  emitNotice(notice);
+}
+
+main();

package/templates/knowledge/topics/f2s-config-precheck.md

@@ -11,7 +11,7 @@
 | --- | --- |
 | Codex（init 镜像，与模板同源） | [f2s-config-check.md](../../.codex/topics/f2s-config-check.md) |
 | Cursor | 仓库根 `.cursor/rules/f2s-config-check.mdc`（`flow2spec init cursor`） |
-| Claude | `.claude/rules/f2s-config-check.md`；PreToolUse：`templates/hooks/f2s-config-inject.js` |
+| Claude | `.claude/rules/f2s-config-check.md`；SessionStart：`.claude/hooks/f2s-config-session.js`；PreToolUse 守门：`.claude/hooks/f2s-config-inject.js` |
 | 包模板 | `templates/rules/f2s-config-check.mdc` |
 
 ## 必备步骤
@@ -21,4 +21,4 @@
 
 ## 禁止项
 
-- 禁止在未读 **`flow2spec.config.json`** 的情况下进入 **`f2s-*`** 技能正文步骤（与 `AGENTS`、`.codex/topics/f2s-config-check.md` 一致）。
+- 禁止在未读 **`flow2spec.config.json`** 的情况下进入 **`f2s-*`** 技能正文步骤（与 `AGENTS`、`.codex/topics/f2s-config-check.md` 一致）；Claude 的 SessionStart 摘要与 PreToolUse 守门提示不替代本次 Read。

package/templates/rules/f2s-config-check.mdc

@@ -19,7 +19,9 @@ alwaysApply: true
 | `switchAgentVerification: false` | 落盘侧自验，不交叉 |
 | 文件不存在 | 所有字段均视为 `false` |
 
-**Claude Code**：若已启用 `f2s-config-inject` PreToolUse hook，调用 `f2s-*` Skill 时会注入配置摘要；**文件缺失、JSON 损坏或 hook 异常时也会注入说明与默认语义**，不静默。仍建议在存疑或刚改过配置时用 `Read` 与磁盘核对。
+**Claude Code**：`f2s-config-session` 在 `SessionStart` 注入一次配置摘要；`f2s-config-inject` 在 `PreToolUse` 仅作为守门提示，提醒调用 `f2s-*` Skill 前首步必须 `Read("flow2spec.config.json")`。两者都**不替代**本条 Read 要求。
+
+**Cursor / Codex**：配置读取仍走文本约束（Cursor：本规则 `alwaysApply`；Codex：根 `AGENTS.md` 与 `.codex/topics/f2s-config-check.md`），不依赖 hook 自动读取配置。
 
 ### changeTracking（变更追踪）
 

package/templates/rules/f2s-flow2spec-unified-entry.mdc

@@ -89,6 +89,19 @@ alwaysApply: true
 
 **例外（应显式否定）**：A、B 两种做法在逻辑上均正确，但项目已做出**排他性选择**时，须写出「不用 B」——不说清楚，读者无法判断 B 是否仍可选。
 
+## 知识库版本自检（hook 自动触发；每日首次，仅 updateCheck.enabled=true 时）
+
+三端均采用 **SessionStart 单脚本**架构：Cursor 由 `flow2spec init cursor` 写入 **`.cursor/hooks.json`** 在 `sessionStart` 执行 `node .cursor/hooks/f2s-update-check.js`；Codex 由 `flow2spec init codex` 写入 **`.codex/hooks.json`** 在 `SessionStart` 的 `startup|resume` 事件执行 `node .codex/hooks/f2s-update-check.js`；Claude 由 `flow2spec init claude` 写入 **`.claude/settings.json`** 在 `SessionStart` 执行 `node .claude/hooks/f2s-update-check.js`。脚本完成版本比对与缓存写入后，需升级时通过 `additional_context` 注入命令式升级提示（agent-instruction 文案要求 agent 必须原文转告用户）。
+
+**规则层双保险**（与脚本缓存互为备份）：
+
+1. 读 `flow2spec.config.json` → 若 `updateCheck.enabled` 不为 `true`，跳过，不做任何提示。
+2. 读 `.Knowledge/update-check.json` → 若文件存在且 `checkedAt` 与今日为同一自然日（`new Date(checkedAt).toDateString() === new Date().toDateString()`），不重复查 npm；但若 `needsUpgrade=true` 或 `latestNpm > manifestVersion`，本会话首次回复用户时仍须提醒执行 `f2s-kb-upgrade`；若当前 `.Knowledge/manifest-routing.json.version` 已不低于 `latestNpm`，删除该缓存并不再提示。
+3. 上述两步均未跳过时：执行当前 agent 配置根下的更新检测脚本（Claude：`node .claude/hooks/f2s-update-check.js`；Cursor：`node .cursor/hooks/f2s-update-check.js`；Codex：`node .codex/hooks/f2s-update-check.js`），解析标准输出的 JSON：
+   - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `f2s-kb-upgrade` skill）。
+   - 无输出或解析失败：静默，不提示。
+4. 以上步骤出现任何错误，静默跳过，不影响正常对话。
+
 ## 主题创作（Topic Authoring）指针
 
 新增或修改 `.Knowledge/topics/<topic>.md`、调整 `manifest-routing.topicDependencies`、删除 / 迁移 topic 时，**创作侧** 准则以 **`rules/f2s-topic-authoring.*`** 为单一事实源（**Cursor/Claude**：`rules/f2s-topic-authoring.mdc`；**Codex**：`.codex/topics/f2s-topic-authoring.md`）。本入口为**消费侧**（如何按已有 topic 路由 / 读取 / 兜底），与之并存；硬冲突时以本入口为准。`f2s-kb-build` / `f2s-kb-add` / `f2s-kb-feat` / `f2s-kb-fix` / `f2s-kb-sync` / `f2s-kb-migrate` / `f2s-kb-rm` 在涉及 topic 落盘前须 Read 该条全文。

package/templates/skills/f2s-git-commit/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: f2s-git-commit
-description: 代码写完后提交 Git：检查变更与知识库覆盖；生成带 emoji 首行的提交说明后**可直接 commit**（须在当条回复展示首行，不要求用户单独确认 commit）；**git pull 类拉取须用户先确认**。触发：f2s-git-commit、提交代码、git commit、帮我提交
+description: 代码写完后提交 Git：默认检查变更与知识库覆盖；用户明确要求“快捷提交”时跳过知识库覆盖检查；生成带 emoji 首行的提交说明后**可直接 commit**（须在当条回复展示首行，不要求用户单独确认 commit）；**git pull 类拉取须用户先确认**。触发：f2s-git-commit、提交代码、快捷提交、git commit、帮我提交
 ---
 
-> 执行口径：本技能代用户执行 git 操作；不使用 `git add -A` / `git add .`，不跳过 hooks（`--no-verify`），不自动 push。**`git pull` / `git fetch` 合并入本地前必须取得用户对「拉取」的明确确认**；`git commit` 不要求单独一轮「确认」交互（见步骤 3–4）。
+> 执行口径：本技能代用户执行 git 操作；不使用 `git add -A` / `git add .`，不跳过 hooks（`--no-verify`），不自动 push。**`git pull` / `git fetch` 合并入本地前必须取得用户对「拉取」的明确确认**；`git commit` 不要求单独一轮「确认」交互（见步骤 3–4）。用户明确要求“快捷提交”时，仅跳过步骤 2 知识库覆盖检查，其余安全步骤照常执行。
 
 ## 编排（主 / 子 agent）
 
@@ -14,6 +14,17 @@ description: 代码写完后提交 Git：检查变更与知识库覆盖；生成
 
 ## 强制流程
 
+### 快捷提交模式
+
+当用户本轮明确说出 **“快捷提交”**、**“快速提交”** 或 **“quick commit”** 时，进入快捷提交模式：
+
+- 跳过 **步骤 2：知识库覆盖检查**，不读取 `.Knowledge/topics/` / `.Knowledge/stock-docs/` 做覆盖判断。
+- 不提示用户先运行 `f2s-kb-sync` / `f2s-kb-feat`。
+- **不跳过**步骤 1 的变更读取与冲突标记检查。
+- **不跳过**步骤 3 的提交信息生成与展示。
+- **不跳过**步骤 4 的精确 `git add <文件列表>`、正常 `git commit` 与 git hooks。
+- **不得**因快捷提交使用 `git add -A` / `git add .` / `--no-verify` / 自动 push。
+
 ### 步骤 1：读取变更（只读）
 
 ```bash
@@ -38,7 +49,9 @@ git diff HEAD
 请先解决冲突后再提交。
 ```
 
-### 步骤 2：知识库覆盖检查（必须）
+### 步骤 2：知识库覆盖检查（默认必须；快捷提交跳过）
+
+若处于**快捷提交模式**，本步骤直接跳过，并在步骤 5 收尾提示中说明“已按快捷提交跳过知识库覆盖检查”。
 
 **先判断 `.Knowledge/` 是否存在：**
 
@@ -160,6 +173,9 @@ git commit -m "<步骤 3 定稿的完整提交信息>"
 
 [若跳过了步骤 2（.Knowledge 不存在）]
 💡 项目尚未初始化 Flow2Spec 知识库，如需接入可运行：flow2spec init
+
+[若快捷提交跳过了步骤 2]
+⚡ 已按快捷提交跳过知识库覆盖检查。
 ```
 
 ## 约束
@@ -168,7 +184,7 @@ git commit -m "<步骤 3 定稿的完整提交信息>"
 - 禁止 `--no-verify`，hook 失败须修复后重试。
 - 禁止 `--amend` 已推送的 commit，除非用户明确要求。
 - 禁止自动 push，commit 完成后停止。
-- 知识库未覆盖时必须提示，但最终是否补录由用户决定（选 B 不阻塞）。
+- 默认模式下知识库未覆盖时必须提示，但最终是否补录由用户决定（选 B 不阻塞）；快捷提交模式下跳过知识库覆盖检查，不提示补录选项。
 - **`git pull` / `git pull --rebase` / 会改写当前分支工作区内容的 `git fetch` 后续合并操作**：**必须**先向用户说明目的与风险，**取得用户对「拉取」的明确确认**（如用户回复「确认 pull」）后再执行；**禁止**为 commit 而顺带静默 pull。
 - **`git commit`**：**不要求**用户单独回复「确认」；但**禁止完全不展示**拟提交首行就执行 commit（须在当条回复中可见首行后再执行）。
 - 提交信息**首行**须符合步骤 3 的 **emoji + type** 格式（用户已合规给出时可保留）。
@@ -179,7 +195,7 @@ git commit -m "<步骤 3 定稿的完整提交信息>"
 1. 步骤 1 是否检查了 merge conflict（必须为是）。
 2. 是否区分了 staged / unstaged / untracked 三类文件（必须为是）。
 3. 是否用了 `git add -A` / `git add .`（必须为否）。
-4. 知识库检查是否执行或有明确跳过理由（必须为是）。
+4. 知识库检查是否执行或有明确跳过理由（快捷提交 / `.Knowledge` 不存在）（必须为是）。
 5. 步骤 3 是否基于 `git diff` 实际内容生成提交信息（必须为是，而非仅 `--stat`）。
 6. 执行 commit 前是否在当条回复中**展示了拟提交首行**（必须为是）；**不得**要求用户单独「确认 commit」才执行（与策略一致）。
 7. 提交信息**首行**是否为 `<emoji> <type>[(scope)]: <简述>` 且 emoji 与 type 与上表一致（合并 revert 等例外须在展示中说明）。

package/templates/skills/f2s-kb-upgrade/SKILL.md

@@ -182,6 +182,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V
 5. 配置根产物是否存在：
    - Cursor/Claude：`rules/`、`skills/`
    - Codex：`.codex/AGENTS.md`、`skills/`
+6. 本技能成功完成后，删除 `.Knowledge/update-check.json`（若存在），让下一次新会话重新检测并清除旧升级提示；若删除失败，在步骤 5 摘要中写明。
 
 ### 步骤 5：输出结果摘要（必须）
 
@@ -195,6 +196,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V
 - **SKILL 自更新**：`init` 后是否重读 `f2s-kb-upgrade/SKILL.md`；是否因文件变化 **整技能重跑**及轮次（见「init 与技能自更新」）
 - manifest / matchers 对齐结论（随 init 输出）
 - 关键文件校验结论
+- `.Knowledge/update-check.json` 清理结论（已删除 / 不存在 / 删除失败）
 - 如失败，给出下一步可执行修复建议
 
 ## 输出摘要模板（建议）
@@ -215,6 +217,7 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V
 - manifest-routing / matchers 分片：`已与模板对齐` / `已是最新` / `reset 覆盖`
 - topics.path：`全部存在` / `存在缺失（见下）`
 - agent 产物：`通过` / `异常（见下）`
+- update-check 缓存：`已删除` / `不存在` / `删除失败`
 
 ### 备注
 - <失败原因或后续建议>
@@ -239,3 +242,4 @@ description: 知识库模板升级技能（仅指本 SKILL）：**流程分流 V
 8. 是否输出了 manifest 与关键路径校验结果。
 9. 若失败，是否给出下一步具体命令建议。
 10. 步骤 3b 的 `index.md` 融合由主 agent 完成并落盘，无子 agent 越权写入。
+11. 成功升级后是否删除 `.Knowledge/update-check.json`，避免当天新会话继续提示旧升级信息。