@double-codeing/flow2spec 3.1.0 → 3.1.2

package/lib/init.js

@@ -106,6 +106,137 @@ function writeJson(filePath, data) {
   fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
 }
 
+function readPackageName(templatesDir) {
+  try {
+    return readJson(path.join(templatesDir, "..", "package.json")).name;
+  } catch (_) {
+    return "@double-codeing/flow2spec";
+  }
+}
+
+function writeHookScriptWithPackageName(destDir, templatesDir, scriptName) {
+  const src = path.join(templatesDir, "hooks", scriptName);
+  if (!fs.existsSync(src)) return { written: false, reason: "missing-template" };
+  ensureDir(destDir);
+  let body = fs.readFileSync(src, "utf8");
+  body = body.replace(/__FLOW2SPEC_PACKAGE_NAME__/g, readPackageName(templatesDir));
+  fs.writeFileSync(path.join(destDir, scriptName), body, "utf8");
+  return { written: true };
+}
+
+function hasHookCommand(groups, fragment) {
+  if (!Array.isArray(groups)) return false;
+  return groups.some((group) =>
+    Array.isArray(group?.hooks) &&
+    group.hooks.some(
+      (hook) =>
+        hook &&
+        hook.type === "command" &&
+        String(hook.command || "").includes(fragment),
+    ),
+  );
+}
+
+function mergeCodexUpdateCheckHook(existing) {
+  const next =
+    existing && typeof existing === "object" && !Array.isArray(existing)
+      ? JSON.parse(JSON.stringify(existing))
+      : {};
+  if (!next.hooks || typeof next.hooks !== "object" || Array.isArray(next.hooks)) {
+    next.hooks = {};
+  }
+  if (!Array.isArray(next.hooks.SessionStart)) {
+    next.hooks.SessionStart = [];
+  }
+  if (hasHookCommand(next.hooks.SessionStart, "f2s-update-check")) {
+    return { config: next, changed: false };
+  }
+  next.hooks.SessionStart.push({
+    matcher: "startup|resume",
+    hooks: [
+      {
+        type: "command",
+        command: "node .codex/hooks/f2s-update-check.js",
+        statusMessage: "Checking Flow2Spec knowledge version",
+      },
+    ],
+  });
+  return { config: next, changed: true };
+}
+
+function writeCodexUpdateCheckHook(cwd, templatesDir) {
+  const codexRoot = path.join(cwd, ".codex");
+  const hooksDir = path.join(codexRoot, "hooks");
+  const scriptResult = writeHookScriptWithPackageName(
+    hooksDir,
+    templatesDir,
+    "f2s-update-check.js",
+  );
+
+  const hooksJsonPath = path.join(codexRoot, "hooks.json");
+  let existing = {};
+  if (fs.existsSync(hooksJsonPath)) {
+    try {
+      existing = readJson(hooksJsonPath);
+    } catch (_) {
+      existing = {};
+    }
+  }
+  const { config, changed } = mergeCodexUpdateCheckHook(existing);
+  if (changed || !fs.existsSync(hooksJsonPath)) {
+    writeJson(hooksJsonPath, config);
+  }
+  return { scriptResult, hooksJsonChanged: changed };
+}
+
+function mergeCursorUpdateCheckHook(existing) {
+  const next =
+    existing && typeof existing === "object" && !Array.isArray(existing)
+      ? JSON.parse(JSON.stringify(existing))
+      : {};
+  next.version = Number.isFinite(Number(next.version)) ? Number(next.version) : 1;
+  if (!next.hooks || typeof next.hooks !== "object" || Array.isArray(next.hooks)) {
+    next.hooks = {};
+  }
+  if (!Array.isArray(next.hooks.sessionStart)) {
+    next.hooks.sessionStart = [];
+  }
+  const exists = next.hooks.sessionStart.some((hook) =>
+    hook && String(hook.command || "").includes("f2s-update-check"),
+  );
+  if (exists) return { config: next, changed: false };
+  next.hooks.sessionStart.push({
+    command: "node .cursor/hooks/f2s-update-check.js",
+    timeout: 10,
+  });
+  return { config: next, changed: true };
+}
+
+function writeCursorUpdateCheckHook(cwd, templatesDir) {
+  const cursorRoot = path.join(cwd, ".cursor");
+  const hooksDir = path.join(cursorRoot, "hooks");
+  const scriptResult = writeHookScriptWithPackageName(
+    hooksDir,
+    templatesDir,
+    "f2s-update-check.js",
+  );
+
+  const hooksJsonPath = path.join(cursorRoot, "hooks.json");
+  let existing = {};
+  if (fs.existsSync(hooksJsonPath)) {
+    try {
+      existing = readJson(hooksJsonPath);
+    } catch (_) {
+      existing = {};
+    }
+  }
+  const { config, changed } = mergeCursorUpdateCheckHook(existing);
+  if (changed || !fs.existsSync(hooksJsonPath)) {
+    writeJson(hooksJsonPath, config);
+  }
+  return { scriptResult, hooksJsonChanged: changed };
+}
+
 function buildDefaultMatcherPath(matcherId) {
   return `${KNOWLEDGE_ROOT}/matchers/${matcherId}.json`;
 }
@@ -217,7 +348,7 @@ function mergeTopicMetadata(templateMetadata, existingMetadata, topicPaths) {
   return out;
 }
 
-function buildMergedRouting(templateRouting, existingRouting) {
+function buildMergedRouting(templateRouting, existingRouting, pkgVersion) {
   const mergedTaskRules = unionByKey(
     templateRouting.taskToTopicRules,
     existingRouting.taskToTopicRules,
@@ -242,7 +373,7 @@ function buildMergedRouting(templateRouting, existingRouting) {
   );
 
   const knownMerged = {
-    version: templateRouting.version || existingRouting.version,
+    version: pkgVersion || templateRouting.version || existingRouting.version,
     knowledgeRoot:
       existingRouting.knowledgeRoot || templateRouting.knowledgeRoot,
     generatedFrom:
@@ -466,7 +597,13 @@ function upgradeKnowledgeRoutingAndMatchers(cwd, templatesDir, options = {}) {
   const existingRouting = hadRouting ? readJson(routingPath) : {};
   const existingMatchers = hadMatchers ? readJson(matchersPath) : {};
 
-  const mergedRouting = buildMergedRouting(templateRouting, existingRouting);
+  // 读包版本号，用于写入 manifest-routing.json 的 version 字段
+  let pkgVersion;
+  try {
+    pkgVersion = readJson(path.join(templatesDir, "..", "package.json")).version;
+  } catch (_) {}
+
+  const mergedRouting = buildMergedRouting(templateRouting, existingRouting, pkgVersion);
   const mergedMatchers = buildMergedMatchers(
     templateMatchers,
     existingMatchers,
@@ -879,6 +1016,14 @@ async function run(cwd, agentIds, options = {}) {
       claudeHooksResult.hookScriptWritten = result.hookScriptResult?.written ?? false;
       claudeHooksResult.settingsChanged = result.settingsChanged;
     }
+    // Cursor：写入官方 hooks.json，使 sessionStart 自动运行更新检测。
+    if (id === "cursor") {
+      writeCursorUpdateCheckHook(cwd, templatesDir);
+    }
+    // Codex：写入官方 hooks.json，使 SessionStart 自动运行更新检测。
+    if (id === "codex") {
+      writeCodexUpdateCheckHook(cwd, templatesDir);
+    }
   }
   return {
     ids,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@double-codeing/flow2spec",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "description": "在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。",
   "homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
   "repository": {

package/templates/AGENTS.codex-stub.md

@@ -14,6 +14,8 @@
 | --- | --- |
 | `skills/` | Flow2Spec 技能（`f2s-*`） |
 | `topics/` | 规则长文镜像（与 Cursor/Claude `rules` 同源） |
+| `hooks.json` | Codex SessionStart hook 配置，用于启动时检测 Flow2Spec 知识库版本 |
+| `hooks/` | hook 脚本目录 |
 | `config.toml` | 项目级 Codex 配置（若已创建） |
 
 配置真值：仓库根 **`flow2spec.config.json`**（须 Read）；init 快照表见根 **`AGENTS.md`**。

package/templates/AGENTS.md

@@ -93,6 +93,19 @@
 
 执行 Flow2Spec 相关任务时，先读本文件（**`./AGENTS.md`**）与 **`./.Knowledge/manifest-routing.json`**，再按需打开上列 **`./.codex/topics/*.md`** 文件。
 
+## 知识库版本自检（SessionStart 自动触发；每日首次，仅 updateCheck.enabled=true 时）
+
+Codex 由 `flow2spec init codex` 写入 **`.codex/hooks.json`**，在 `SessionStart` 的 `startup|resume` 事件自动执行 `node .codex/hooks/f2s-update-check.js`；首次生成或 hook 内容变化后，Codex 可能要求通过 `/hooks` 审核并信任该项目 hook。
+
+**规则层双保险**（若 hook 未运行，则按本节补检；与脚本缓存互为备份）：
+
+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. 上述两步均未跳过时：执行 `node .codex/hooks/f2s-update-check.js`，解析标准输出的 JSON：
+   - 若含 `hookSpecificOutput.additionalContext`：**告知用户**该内容（建议执行 `/f2s-kb-upgrade`）。
+   - 无输出或解析失败：静默，不提示。
+4. 以上步骤出现任何错误，静默跳过，不影响正常对话。
+
 ## 可用 Flow2Spec 技能（自动生成）
 
 {{FLOW2SPEC_CODEX_SKILLS_SUMMARY}}

package/templates/flow2spec.config.json

@@ -2,8 +2,11 @@
   "subAgent": false,
   "switchAgentVerification": false,
   "changeTracking": {
-    "feat": false,
+    "feat": true,
     "fix": false,
-    "implement": false
+    "implement": true
+  },
+  "updateCheck": {
+    "enabled": true
   }
 }

package/templates/hooks/f2s-config-inject.js

@@ -1,26 +1,10 @@
 #!/usr/bin/env node
 'use strict';
 /**
- * flow2spec PreToolUse hook — 在任何 f2s-* Skill 执行前自动注入 flow2spec.config.json。
+ * flow2spec PreToolUse guard — 仅在调用 f2s-* Skill 前提示必须先 Read flow2spec.config.json。
+ * 不在 PreToolUse 中反复注入完整配置；配置摘要由 SessionStart hook 一次性提供。
  * 由 flow2spec init --claude 写入 .claude/hooks/f2s-config-inject.js。
  */
-const fs = require('fs');
-const path = require('path');
-
-const DEFAULT_CFG = {
-  subAgent: false,
-  switchAgentVerification: false,
-  changeTracking: { feat: false, fix: false, implement: false },
-};
-
-/** 与 lib/flow2specConfig.js 一致，避免 hook 依赖包内路径 */
-function normalizeBool(value, fallback) {
-  if (value === true || value === 'true' || value === 1 || value === '1')
-    return true;
-  if (value === false || value === 'false' || value === 0 || value === '0')
-    return false;
-  return fallback;
-}
 
 function emitAdditionalContext(lines) {
   process.stdout.write(
@@ -29,85 +13,8 @@ function emitAdditionalContext(lines) {
         hookEventName: 'PreToolUse',
         additionalContext: lines.join('\n'),
       },
-    }),
-  );
-}
-
-function normalizeCfg(raw) {
-  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-    return { ...DEFAULT_CFG, changeTracking: { ...DEFAULT_CFG.changeTracking } };
-  }
-  const ct = raw.changeTracking;
-  let changeTracking = { ...DEFAULT_CFG.changeTracking };
-  if (typeof ct === 'boolean') {
-    changeTracking = {
-      feat: normalizeBool(ct, DEFAULT_CFG.changeTracking.feat),
-      fix: normalizeBool(ct, DEFAULT_CFG.changeTracking.fix),
-      implement: normalizeBool(ct, DEFAULT_CFG.changeTracking.implement),
-    };
-  } else if (ct && typeof ct === 'object' && !Array.isArray(ct)) {
-    changeTracking = {
-      feat: normalizeBool(ct.feat, DEFAULT_CFG.changeTracking.feat),
-      fix: normalizeBool(ct.fix, DEFAULT_CFG.changeTracking.fix),
-      implement: normalizeBool(ct.implement, DEFAULT_CFG.changeTracking.implement),
-    };
-  }
-  const switchRaw = Object.prototype.hasOwnProperty.call(raw, 'switchAgentVerification')
-    ? raw.switchAgentVerification
-    : raw.subAgentVerification;
-  return {
-    subAgent: normalizeBool(raw.subAgent, DEFAULT_CFG.subAgent),
-    switchAgentVerification: normalizeBool(
-      switchRaw,
-      DEFAULT_CFG.switchAgentVerification,
-    ),
-    changeTracking,
-  };
-}
-
-function buildChangeTrackingLines(skillName, cfg) {
-  const lines = [];
-  const ctKeyMap = {
-    'f2s-kb-feat': 'feat',
-    'f2s-kb-fix': 'fix',
-    'f2s-implement-tech-design': 'implement',
-  };
-  const ctKey = ctKeyMap[skillName];
-  if (ctKey === undefined) return lines;
-  const ctValue = normalizeBool(
-    (cfg.changeTracking ?? {})[ctKey],
-    DEFAULT_CFG.changeTracking[ctKey],
+    }) + '\n',
   );
-  lines.push('');
-  if (ctValue) {
-    const stepMap = {
-      feat: '步骤 0',
-      fix: '步骤 0',
-      implement: '步骤 2.5（写入任务清单）、2.6（随步打钩 task.md）、步骤 5（归档门禁后归档）',
-    };
-    lines.push(
-      `changeTracking.${ctKey}=true → 本技能变更追踪【必须执行】：在 ${stepMap[ctKey]} 创建或续作 .task/active/ 任务，禁止跳过。`,
-    );
-  } else {
-    lines.push(
-      `changeTracking.${ctKey}=false → 本技能变更追踪步骤跳过，不得创建 .task/ 目录。`,
-    );
-  }
-  return lines;
-}
-
-function buildCoreLines(cfg, sourceLabel) {
-  const lines = [
-    `[flow2spec] ${sourceLabel}`,
-    `  subAgent = ${cfg.subAgent}`,
-    `  switchAgentVerification = ${cfg.switchAgentVerification}`,
-    `  changeTracking = ${JSON.stringify(cfg.changeTracking)}`,
-    '',
-    'subAgent=true  → 按技能 SKILL.md 中 B/C 模式派子 agent 并行扫描，主 agent 合并落盘。',
-    'subAgent=false → 全部在主 agent 内完成，不派子 agent。',
-    'switchAgentVerification=true → 子 agent 落盘的由主 agent 校验；主 agent 落盘的由子 agent 校验（须 subAgent=true 且实际拆出子任务）。',
-  ];
-  return lines;
 }
 
 const chunks = [];
@@ -116,7 +23,7 @@ process.stdin.on('end', () => {
   let skillName = '';
   try {
     const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
-    skillName = String(input?.tool_input?.skill || '');
+    skillName = String(input?.tool_input?.skill || input?.tool_input?.name || '');
   } catch (_err) {
     process.exit(0);
     return;
@@ -127,55 +34,10 @@ process.stdin.on('end', () => {
     return;
   }
 
-  const configPath = path.resolve(process.cwd(), 'flow2spec.config.json');
-
-  try {
-    if (!fs.existsSync(configPath)) {
-      const cfg = { ...DEFAULT_CFG, changeTracking: { ...DEFAULT_CFG.changeTracking } };
-      const lines = [
-        '[flow2spec] 项目根不存在 flow2spec.config.json；按统一入口约定，缺失字段均视为 false。',
-        '',
-        ...buildCoreLines(cfg, '等价配置预览（建议随后 Read 或 flow2spec init 补齐该文件）：'),
-        '',
-        '可执行：flow2spec init（或从包模板复制 flow2spec.config.json 到项目根）。',
-        ...buildChangeTrackingLines(skillName, cfg),
-      ];
-      emitAdditionalContext(lines);
-      process.exit(0);
-      return;
-    }
-
-    let raw;
-    try {
-      raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    } catch (parseErr) {
-      const cfg = { ...DEFAULT_CFG, changeTracking: { ...DEFAULT_CFG.changeTracking } };
-      const lines = [
-        `[flow2spec] flow2spec.config.json 存在但 JSON 解析失败：${parseErr.message || String(parseErr)}`,
-        '在修复文件前，请按以下默认安全语义执行本技能（与「文件不存在」一致）：',
-        '',
-        ...buildCoreLines(cfg, '等价配置（解析失败回退）'),
-        ...buildChangeTrackingLines(skillName, cfg),
-      ];
-      emitAdditionalContext(lines);
-      process.exit(0);
-      return;
-    }
-
-    const cfg = normalizeCfg(raw);
-    const lines = [
-      ...buildCoreLines(cfg, 'flow2spec.config.json 已自动注入，执行本 f2s-* 技能前必须遵守以下配置：'),
-      '',
-      '仍建议用 Read(flow2spec.config.json) 与磁盘核对，尤其在刚编辑过该文件时。',
-      ...buildChangeTrackingLines(skillName, cfg),
-    ];
-    emitAdditionalContext(lines);
-  } catch (err) {
-    const msg = err && err.message ? err.message : String(err);
-    emitAdditionalContext([
-      `[flow2spec] f2s-config-inject hook 未预期异常：${msg}`,
-      '请手动 Read("flow2spec.config.json") 后再执行本技能；若持续失败请检查 hook 脚本与项目根路径。',
-    ]);
-  }
+  emitAdditionalContext([
+    `[flow2spec] 即将调用 ${skillName}。进入该 Skill 正文前，首个动作必须 Read("flow2spec.config.json")。`,
+    'SessionStart 中的配置摘要仅作提醒；若摘要与磁盘不一致，以本次 Read 结果为准。',
+    '读取后再按 subAgent / switchAgentVerification / changeTracking 的实际值执行后续步骤。',
+  ]);
   process.exit(0);
 });

package/templates/hooks/f2s-config-session.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * flow2spec SessionStart hook — 会话开始时一次性注入 flow2spec.config.json 摘要。
+ * 该摘要不替代 f2s-* Skill 正文前的 Read("flow2spec.config.json")。
+ * 由 flow2spec init --claude 写入 .claude/hooks/f2s-config-session.js。
+ */
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_CFG = {
+  subAgent: false,
+  switchAgentVerification: false,
+  changeTracking: { feat: true, fix: false, implement: true },
+};
+
+function normalizeBool(value, fallback) {
+  if (value === true || value === 'true' || value === 1 || value === '1')
+    return true;
+  if (value === false || value === 'false' || value === 0 || value === '0')
+    return false;
+  return fallback;
+}
+
+function normalizeCfg(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ...DEFAULT_CFG, changeTracking: { ...DEFAULT_CFG.changeTracking } };
+  }
+  const ct = raw.changeTracking;
+  let changeTracking = { ...DEFAULT_CFG.changeTracking };
+  if (typeof ct === 'boolean') {
+    changeTracking = {
+      feat: normalizeBool(ct, DEFAULT_CFG.changeTracking.feat),
+      fix: normalizeBool(ct, DEFAULT_CFG.changeTracking.fix),
+      implement: normalizeBool(ct, DEFAULT_CFG.changeTracking.implement),
+    };
+  } else if (ct && typeof ct === 'object' && !Array.isArray(ct)) {
+    changeTracking = {
+      feat: normalizeBool(ct.feat, DEFAULT_CFG.changeTracking.feat),
+      fix: normalizeBool(ct.fix, DEFAULT_CFG.changeTracking.fix),
+      implement: normalizeBool(ct.implement, DEFAULT_CFG.changeTracking.implement),
+    };
+  }
+  const switchRaw = Object.prototype.hasOwnProperty.call(raw, 'switchAgentVerification')
+    ? raw.switchAgentVerification
+    : raw.subAgentVerification;
+  return {
+    subAgent: normalizeBool(raw.subAgent, DEFAULT_CFG.subAgent),
+    switchAgentVerification: normalizeBool(
+      switchRaw,
+      DEFAULT_CFG.switchAgentVerification,
+    ),
+    changeTracking,
+  };
+}
+
+function emit(lines) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: lines.join('\n'),
+      },
+    }) + '\n',
+  );
+}
+
+function main() {
+  const configPath = path.resolve(process.cwd(), 'flow2spec.config.json');
+  if (!fs.existsSync(configPath)) {
+    const cfg = { ...DEFAULT_CFG, changeTracking: { ...DEFAULT_CFG.changeTracking } };
+    emit([
+      '[flow2spec] 本会话未找到 flow2spec.config.json；f2s-* Skill 前仍必须尝试 Read("flow2spec.config.json")，缺失字段按默认值处理。',
+      `配置摘要：subAgent=${cfg.subAgent}, switchAgentVerification=${cfg.switchAgentVerification}, changeTracking=${JSON.stringify(cfg.changeTracking)}`,
+    ]);
+    return;
+  }
+
+  try {
+    const cfg = normalizeCfg(JSON.parse(fs.readFileSync(configPath, 'utf8')));
+    emit([
+      '[flow2spec] SessionStart 配置摘要（仅作提醒，执行 f2s-* Skill 前仍必须 Read 磁盘文件）：',
+      `subAgent=${cfg.subAgent}`,
+      `switchAgentVerification=${cfg.switchAgentVerification}`,
+      `changeTracking=${JSON.stringify(cfg.changeTracking)}`,
+    ]);
+  } catch (err) {
+    emit([
+      `[flow2spec] flow2spec.config.json 解析失败：${err.message || String(err)}`,
+      '执行 f2s-* Skill 前必须先修复或 Read 该文件；无法读取时按缺失字段默认值处理。',
+    ]);
+  }
+}
+
+main();