@double-codeing/flow2spec 3.0.12 → 3.0.13

package/cli.js

@@ -50,11 +50,11 @@ init 会:
      传 --yes 时所有缺失字段使用默认值（均为 false）。
   3. 默认仅补齐 .Knowledge 缺失模板，并对路由清单做包级/结构增量对齐（manifest-routing + matcherPath 分片；关键词仅写在 matchers/*.json）；不替代 f2s-* 对业务文档与路由内容的写入。
      传 --reset-knowledge 时才会强制用模板覆盖 .Knowledge 中模板承载部分。
-  4. 在各 agent 配置根写入 rules、skills（Claude 规则自动转 .md；Codex 生成 AGENTS.md 汇总）。
+  4. 在各 agent 配置根写入 rules、skills（Claude 规则自动转 .md；Codex 在仓库根写入完整 AGENTS.md，.codex/ 写入指针）。
      Claude 额外写入 .claude/hooks/f2s-config-inject.js 与 .claude/settings.json（PreToolUse hook），
      在调用 f2s-* Skill 时注入配置摘要；配置缺失、JSON 无效或 hook 异常时也会注入默认语义说明，避免静默。
      Cursor 额外写入 f2s-config-check.mdc（alwaysApply），强制在技能首步读取配置文件。
-     Codex 的 AGENTS.md 顶部包含强制前置步骤说明。
+     Codex：仓库根 AGENTS.md（CLI 自动发现，完整条令）；.codex/AGENTS.md 为指针。
   5. 每次 init 将包内 templates/knowledge/index.md 复制到 .Knowledge/template/index.template.md，供 f2s-kb-upgrade 技能与 .Knowledge/index.md 对照；不自动改写 index.md。（「知识库升级」指 f2s-kb-upgrade 技能，init 本身不是升级命令。）
   6. 规则与技能在各 agent 配置根加载；其他模版类文件在 .Knowledge/template/ 等目录。
 
@@ -293,7 +293,7 @@ if (sub === "init") {
       const lines = ids.map((id) => {
         const { root, label } = AGENTS[id];
         if (id === "codex")
-          return `  - ${root}/：（${label}）AGENTS.md、skills/`;
+          return `  - ${root}/：（${label}）skills/、topics/、AGENTS.md（指针）；仓库根 AGENTS.md（完整）`;
         if (id === "claude") {
           const hookLine = claudeHooksResult?.settingsChanged
             ? "rules/、skills/、hooks/f2s-config-inject.js、settings.json（已写入 f2s PreToolUse hook）"

package/lib/codexAgentsAdapter.js

@@ -67,4 +67,16 @@ function buildCodexAgentsMd(templatesDir, projectConfig) {
   return renderCodexAgents(templateBody, skillLines, projectConfig);
 }
 
-module.exports = { buildCodexAgentsMd, renderProjectConfigBlock };
+function buildCodexAgentsStubMd(templatesDir) {
+  const stubPath = path.join(templatesDir, "AGENTS.codex-stub.md");
+  if (!fs.existsSync(stubPath)) {
+    throw new Error(`缺少 Codex 指针模板：${stubPath}`);
+  }
+  return fs.readFileSync(stubPath, "utf8");
+}
+
+module.exports = {
+  buildCodexAgentsMd,
+  buildCodexAgentsStubMd,
+  renderProjectConfigBlock,
+};

package/lib/init.js

@@ -11,7 +11,10 @@ const {
   adaptRuleMdcToClaudeMd,
   shouldWriteClaudeStyleRules,
 } = require("./claudeRulesAdapter");
-const { buildCodexAgentsMd } = require("./codexAgentsAdapter");
+const {
+  buildCodexAgentsMd,
+  buildCodexAgentsStubMd,
+} = require("./codexAgentsAdapter");
 const {
   loadFlow2specConfig,
   ensureFlow2specProjectConfig,
@@ -700,9 +703,15 @@ function writeCodexTopicMirrors(cwd, templatesDir) {
   }
 }
 
+/**
+ * Codex 官方从仓库根向下扫描 AGENTS.md（见 developers.openai.com/codex/guides/agents-md）。
+ * 完整条令写仓库根；.codex/AGENTS.md 仅为指针，避免双份全文重复与 cwd 在 .codex 时双倍拼接。
+ */
 function writeCodexEntry(cwd, templatesDir, projectConfig) {
-  const out = buildCodexAgentsMd(templatesDir, projectConfig);
-  fs.writeFileSync(path.join(cwd, ".codex", "AGENTS.md"), out, "utf8");
+  const full = buildCodexAgentsMd(templatesDir, projectConfig);
+  const stub = buildCodexAgentsStubMd(templatesDir);
+  fs.writeFileSync(path.join(cwd, "AGENTS.md"), full, "utf8");
+  fs.writeFileSync(path.join(cwd, ".codex", "AGENTS.md"), stub, "utf8");
   writeCodexTopicMirrors(cwd, templatesDir);
 }
 

package/package.json

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

package/templates/AGENTS.codex-stub.md

@@ -0,0 +1,19 @@
+# Flow2Spec（`.codex/` 目录说明）
+
+> 本文件为 **指针**，非完整条令。`flow2spec init` 写入；**请勿只读本文件**。
+
+## 完整条令
+
+仓库根 **[`AGENTS.md`](../AGENTS.md)** 为 Flow2Spec 完整项目说明。在仓库根启动 Codex 时会 [自动加载](https://developers.openai.com/codex/guides/agents-md) 该文件。
+
+若当前会话未包含根 `AGENTS.md` 全文，**必须先 Read 仓库根 `AGENTS.md`**，再执行 `f2s-*` 或改动 `.Knowledge/`。
+
+## 本目录用途
+
+| 路径 | 说明 |
+| --- | --- |
+| `skills/` | Flow2Spec 技能（`f2s-*`） |
+| `topics/` | 规则长文镜像（与 Cursor/Claude `rules` 同源） |
+| `config.toml` | 项目级 Codex 配置（若已创建） |
+
+配置真值：仓库根 **`flow2spec.config.json`**（须 Read）；init 快照表见根 **`AGENTS.md`**。

package/templates/AGENTS.md

@@ -1,6 +1,6 @@
 # Flow2Spec 项目入口
 
-本文件由 `flow2spec init` 写入 **`./.codex/AGENTS.md`**（相对仓库根）。你正在使用 Flow2Spec 的项目中工作；知识库在 **`./.Knowledge/`**，请渐进式读取，避免一次性加载大量无关文档。
+本文件由 `flow2spec init` 写入仓库根 **`./AGENTS.md`**（完整条令，供 [Codex 自动发现](https://developers.openai.com/codex/guides/agents-md)）。**`./.codex/AGENTS.md`** 仅为指向本文件的短说明，不含完整规则。你正在使用 Flow2Spec 的项目中工作；知识库在 **`./.Knowledge/`**，请渐进式读取，避免一次性加载大量无关文档。
 
 ## ⚠️ f2s-* 技能前置强制步骤
 
@@ -14,7 +14,7 @@
 
 ## Flow2Spec 项目开关（`./flow2spec.config.json`；缺失时由 `flow2spec init` 从 npm 包模板补齐）
 
-**`flow2spec init` 的定位**：把 Flow2Spec **包内模板**落到当前仓库——包括 **`./.Knowledge/`**（含路由结构、快照等）与 **`./.codex/`**（本文件 **`./.codex/AGENTS.md`**、**`./.codex/skills/`**、经 init 写入的 **`./.codex/topics/*.md`**），**不负责**撰写业务 **`./.Knowledge/stock-docs/`**、**`./.Knowledge/topics/`** 正文或替代 **`f2s-*` 技能**；即 **模板与目录落盘 / 形态对齐**，不是「知识库升级命令」（升级见 **`f2s-kb-upgrade`** 技能）。
+**`flow2spec init` 的定位**：把 Flow2Spec **包内模板**落到当前仓库——包括 **`./.Knowledge/`**（含路由结构、快照等）、仓库根 **`./AGENTS.md`**（完整）、**`.codex/AGENTS.md`**（指针）及 **`./.codex/`**（**`./.codex/skills/`**、经 init 写入的 **`./.codex/topics/*.md`** 等），**不负责**撰写业务 **`./.Knowledge/stock-docs/`**、**`./.Knowledge/topics/`** 正文或替代 **`f2s-*` 技能**；即 **模板与目录落盘 / 形态对齐**，不是「知识库升级命令」（升级见 **`f2s-kb-upgrade`** 技能）。
 
 执行任意 **`f2s-*` 技能**前，必须读取 `./flow2spec.config.json` 中的布尔字段（缺省或文件不存在均视为 `false`）。下表由 **最近一次 `flow2spec init`** 根据当时配置写入，**以磁盘上的文件为准**。
 
@@ -51,7 +51,7 @@
    - 禁止跳过 **`./.Knowledge/manifest-routing.json`**、按需 `matcherPath` 分片与 **`./.Knowledge/topics/`** 直接全仓检索或直接编码；**`./.Knowledge/index.md`** 按需读取，不可替代上述机读链。
    - 同一任务线内避免重复全文读取 **`./.Knowledge/manifest-routing.json`**（除非用户说明已通过 `f2s-ctx-build` / `f2s-kb-sync` / `f2s-doc-add` 等更新路由或知识、或手动改了 manifest；**勿将**仅执行 `flow2spec init` 当作业务知识库已更新）；禁止为枚举而遍历整个 **`./.Knowledge/matchers/`**；禁止 **`./.Knowledge/index.md`** 与 routing 交替「刷清单」。
    - 禁止把 **`./.Knowledge/stock-docs/`** 作为“按方案实现代码”的直接输入文档。
-   - Flow2Spec 执行条令仅以 **`./.codex/AGENTS.md`**（本文件）、**`./.codex/topics/f2s-*.md`** 与 **`./.codex/skills/`** 为准；勿使用仓库内 **非上述路径** 的同名条令文件作为执行依据，以免口径分叉。
+   - Flow2Spec 执行条令以 **`./AGENTS.md`**（完整）、**`./.codex/topics/f2s-*.md`** 与 **`./.codex/skills/`** 为准；**`.codex/AGENTS.md`** 仅为目录指针，不可替代根 `AGENTS.md`；勿使用仓库内 **非上述路径** 的同名条令文件作为执行依据，以免口径分叉。
    - 禁止把 `fallbackTopic` 当作最终命中直接实施改动；`fallbackTopic` 仅作安全兜底与澄清前置上下文。
    - 禁止在不满足触发门槛时做跨 matcher 全量补检索。
 10. **检索与作答节奏**：在 KB 已形成可答结论时，控制 `grep`/读盘范围与轮次；优先按 topic 给出的目录做单点 `Read`。用户未要求「全仓 / 通读依赖」时，允许**先短答再按需下钻**。细则见 **`./.codex/topics/f2s-knowledge-preflight.md`** 中 **「检索体积与作答节奏」**。
@@ -91,7 +91,7 @@
 - **`./.codex/topics/f2s-config-check.md`**：内容与上文「先 Read **`./flow2spec.config.json`**」一致并含 **changeTracking** 细表；**仅**在需核对细表时按需打开，不必与上列三条并列必读。
 - **`./.codex/topics/f2s-karpathy-guidelines.md`**：通用编码行为准则（先澄清、极简、手术式修改、可验证目标）；与 f2s 路由/任务条令**并行**，硬冲突时以 **f2s 条令**为准。
 
-执行 Flow2Spec 相关任务时，先读本 **`./.codex/AGENTS.md`** 与 **`./.Knowledge/manifest-routing.json`**，再按需打开上列 **`./.codex/topics/*.md`** 文件。
+执行 Flow2Spec 相关任务时，先读本文件（**`./AGENTS.md`**）与 **`./.Knowledge/manifest-routing.json`**，再按需打开上列 **`./.codex/topics/*.md`** 文件。
 
 ## 可用 Flow2Spec 技能（自动生成）