@double-codeing/flow2spec 3.0.15 → 3.0.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/docs/en/commands-reference.md +1 -1
  2. package/docs/en/directory-conventions.md +0 -2
  3. package/docs/en/usage-guide.md +5 -1
  4. package/docs//344/275/277/347/224/250/350/257/264/346/230/216.md +21 -12
  5. package/docs//345/221/275/344/273/244/350/257/264/346/230/216.md +1 -1
  6. package/docs//347/233/256/345/275/225/344/270/216/350/267/257/345/276/204/347/272/246/345/256/232.md +0 -2
  7. package/package.json +1 -1
  8. package/templates/skills/f2s-ctx-build/SKILL.md +5 -3
  9. package/templates/skills/f2s-doc-arch/SKILL.md +16 -3
package/docs/en/commands-reference.md CHANGED
@@ -17,7 +17,7 @@
17
17
 
18
18
  **Relationships**:
19
19
  - **Prerequisite**: None
20
- - **Next Step**: `f2s-doc-final` (normalized final draft) or direct use with `f2s-ctx-build`
20
+ - **Next Step**: `f2s-doc-final` (normalized final draft) → `f2s-ctx-build` (**final draft input only**; do not run build on `_draft` / `_初稿` files)
21
21
  - **Output**: `.Knowledge/stock-docs/<Architecture Overview>_draft.md`
22
22
 
23
23
  **Sub-Agent Invocation**:
package/docs/en/directory-conventions.md CHANGED
@@ -16,8 +16,6 @@ See [architecture.md §1](./architecture.md) for Memory Coding four rings.
16
16
 
17
17
  | Path | Responsibility |
18
18
  | --- | --- |
19
- | `docs/` | Product docs (**Chinese**): usage guide, commands reference, design principles, etc. |
20
- | `docs/en/` | Product docs (**English**): six paired documents; see [README.md](./README.md) |
21
19
  | `.Knowledge/stock-docs/` | **L3** Architecture, final drafts, reference documents |
22
20
  | `.Knowledge/req-docs/` | **L3** Requirement clarification, technical proposals |
23
21
  | `.Knowledge/topics/` | **L2** Topic summaries (hard constraints, boundaries, pointers) |
package/docs/en/usage-guide.md CHANGED
@@ -67,7 +67,11 @@ If **`changeTracking` is off** but you still need a `.task/` checklist temporari
67
67
  ### New Feature Development
68
68
 
69
69
  ```
70
- f2s-req-clarify → f2s-req-backend → implement-tech-design → f2s-kb-feat
70
+ f2s-req-clarify (one-line requirement or doc) → f2s-req-backend → implement <technical design> (strictly follows implement-tech-design rule)
71
+ After implementation, new capability → f2s-kb-feat
72
+ After implementation, bug fix → f2s-kb-fix
73
+ After debugging → f2s-kb-sync
74
+ Finally → f2s-git-commit
71
75
  ```
72
76
 
73
77
  When requirements are already clear, `f2s-req-clarify` can be skipped, starting directly from `f2s-req-backend`. After the technical design is written into `req-docs/`, the `implement-tech-design` rule drives coding.
package/docs//344/275/277/347/224/250/350/257/264/346/230/216.md CHANGED
@@ -12,25 +12,29 @@ flow2spec init [cursor|claude|codex ...]
12
12
  flow2spec init [cursor|claude|codex ...] --reset-knowledge
13
13
  ```
14
14
 
15
- | init 做 | init 不做 |
16
- |---------|----------|
17
- | 补齐缺失的目录与模板文件 | 撰写或更新业务文档内容 |
18
- | 落盘各 agent 配置根 `rules/` `skills/` | 更新 `includeAny` 业务词条 |
19
- | `manifest-routing` + `matchers/` 包级结构对齐 | 替代 `f2s-*` 技能对业务语义的书写 |
15
+
16
+ | init 做 | init 不做 |
17
+ | ------------------------------------------- | ---------------------------- |
18
+ | 补齐缺失的目录与模板文件 | 撰写或更新业务文档内容 |
19
+ | 落盘各 agent 配置根 `rules/` `skills/` | 更新 `includeAny` 业务词条 |
20
+ | `manifest-routing` + `matchers/` 包级结构对齐 | 替代 `f2s-*` 技能对业务语义的书写 |
20
21
  | `--reset-knowledge` 时强制覆盖 `.Knowledge` 模板文件 | （不加此参数时）覆盖已有 `.Knowledge` 内容 |
21
22
 
23
+
22
24
  > **`init` 与「知识库升级」是两件事**：`init` 只做结构补齐，业务语义（topics 内容、路由词条、stock-docs/req-docs）由 `f2s-doc-add`、`f2s-kb-fix`、`f2s-kb-feat`、`f2s-kb-sync`、`f2s-ctx-build` 等技能维护。跨版本升级用 `f2s-kb-upgrade`，**不要把单独 `init` 当作升级命令**。
23
25
 
24
26
  ### `f2s-*` 与 `flow2spec.config.json`：多端多重提示（权威仍为磁盘 JSON）
25
27
 
26
28
  执行任意 **`f2s-*` 技能**前，需要让 Agent 拿到 **`subAgent` / `switchAgentVerification` / `changeTracking`** 等实际值。Flow2Spec 在 **不同客户端** 用 **不同机制** 强化这一点；它们彼此**补充**，**不**互相替代，**权威始终**是项目根 **`flow2spec.config.json`**（须用 **Read** 与磁盘一致后再进技能正文）。
27
29
 
28
- | 端 | `init` 落盘与行为 | 说明 |
29
- | --- | --- | --- |
30
- | **Cursor** | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`） | 规则要求：技能正文前先 **Read(`flow2spec.config.json`)**。 |
31
- | **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json`（PreToolUse，`Skill` 匹配） | 在调用 **`f2s-*` Skill** 时注入配置摘要；**文件缺失、JSON 无效或 hook 未预期异常**时也会注入**说明 + 与「文件不存在」一致的默认语义**，避免静默；仍建议在存疑或刚改过配置时 **Read** 核对。 |
32
- | **Codex** | `.codex/AGENTS.md` 顶部强制步骤 + `{{FLOW2SPEC_PROJECT_CONFIG}}` 展开表 | **Read** 为硬要求；配置表为 **最近一次 `flow2spec init` 的快照**，与磁盘不一致时以 **Read** 为准。同目录 **`.codex/topics/f2s-config-check.md`** 与 Cursor 规则同源（含 **changeTracking** 细表），**按需**打开即可，不必与「专题长文」三条示例并列必读。 |
33
- | **知识库（可选）** | `.Knowledge/manifest-routing` 命中 **`config-precheck`** 时 | `.Knowledge/topics/f2s-config-precheck.md` 为**路由摘要**，链向 Codex 长文；**不**在 `.Knowledge` 再维护第二份全文，也**不**替代 Read JSON。 |
30
+
31
+ | 端 | `init` 落盘与行为 | 说明 |
32
+ | --------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
33
+ | **Cursor** | `.cursor/rules/f2s-config-check.mdc`（`alwaysApply`） | 规则要求：技能正文前先 **Read(`flow2spec.config.json`)**。 |
34
+ | **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json`（PreToolUse，`Skill` 匹配） | 在调用 **`f2s-*` Skill** 时注入配置摘要；**文件缺失、JSON 无效或 hook 未预期异常**时也会注入**说明 + 与「文件不存在」一致的默认语义**，避免静默；仍建议在存疑或刚改过配置时 **Read** 核对。 |
35
+ | **Codex** | `.codex/AGENTS.md` 顶部强制步骤 + `{{FLOW2SPEC_PROJECT_CONFIG}}` 展开表 | **Read** 为硬要求；配置表为 **最近一次 `flow2spec init` 的快照**，与磁盘不一致时以 **Read** 为准。同目录 **`.codex/topics/f2s-config-check.md`** 与 Cursor 规则同源（含 **changeTracking** 细表），**按需**打开即可，不必与「专题长文」三条示例并列必读。 |
36
+ | **知识库（可选）** | `.Knowledge/manifest-routing` 命中 **`config-precheck`** 时 | `.Knowledge/topics/f2s-config-precheck.md` 为**路由摘要**，链向 Codex 长文；**不**在 `.Knowledge` 再维护第二份全文，也**不**替代 Read JSON。 |
37
+
34
38
 
35
39
  字段语义与默认值规则见 [命令说明 § 6) 子 Agent 配置说明](./命令说明.md)。设计视角见 [设计说明 § 四、5.1](./设计说明.md)；口述见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)。
36
40
 
@@ -67,7 +71,11 @@ flow2spec init [cursor|claude|codex ...] --reset-knowledge
67
71
  ### 新需求开发
68
72
 
69
73
  ```
70
- f2s-req-clarify → f2s-req-backend → implement-tech-design → f2s-kb-feat
74
+ f2s-req-clarify 一句话需求或文档 → f2s-req-backend → 实现xx技术方案 （会严格按照implement-tech-design规则走）
75
+ 实现完成后需新增能力→ f2s-kb-feat
76
+ 实现完成后需修bug→ f2s-kb-fix
77
+ 调试完成后-> f2s-kb-sync
78
+ 最后->f2s-git-commit
71
79
  ```
72
80
 
73
81
  需求已明确时可跳过 `f2s-req-clarify`，直接从 `f2s-req-backend` 开始。技术方案落入 `req-docs/` 后，由 `implement-tech-design` 规则驱动编码。
@@ -151,3 +159,4 @@ f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，
151
159
  - [目录与路径约定](./目录与路径约定.md)
152
160
  - [体系与原理](./体系与原理.md)
153
161
  - [使用案例-模拟对话](./使用案例-模拟对话.md)
162
+
package/docs//345/221/275/344/273/244/350/257/264/346/230/216.md CHANGED
@@ -19,7 +19,7 @@
19
19
  **关联关系**：
20
20
 
21
21
  - **前置**：无
22
- - **后续**：`f2s-doc-final`（规范化终稿）或直接用于 `f2s-ctx-build`
22
+ - **后续**：`f2s-doc-final`（规范化终稿）→ `f2s-ctx-build`（**须终稿入参**；初稿不可直驱 build）
23
23
  - **输出**：`.Knowledge/stock-docs/<架构说明>_初稿.md`
24
24
 
25
25
  **子 agent 调用**：
package/docs//347/233/256/345/275/225/344/270/216/350/267/257/345/276/204/347/272/246/345/256/232.md CHANGED
@@ -16,8 +16,6 @@ Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。
16
16
 
17
17
  | 路径 | 职责 |
18
18
  | --- | --- |
19
- | `docs/` | 产品说明（**中文**）：使用说明、命令说明、设计说明等 |
20
- | `docs/en/` | 产品说明（**英文**）：与上表一一对应的 6 篇文档，见 [en/README.md](./en/README.md) |
21
19
  | `.Knowledge/stock-docs/` | **L3** 架构、终稿、沉淀长文档 |
22
20
  | `.Knowledge/req-docs/` | **L3** 需求澄清、技术方案长文档 |
23
21
  | `.Knowledge/topics/` | **L2** 主题摘要（硬约束、边界、路由指针） |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@double-codeing/flow2spec",
3
- "version": "3.0.15",
3
+ "version": "3.0.16",
4
4
  "description": "在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则 f2s-karpathy-guidelines，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。",
5
5
  "homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
6
6
  "repository": {
package/templates/skills/f2s-ctx-build/SKILL.md CHANGED
@@ -25,6 +25,8 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
25
25
 
26
26
  - 接收一个参数：URL 或本地路径。
27
27
  - 本地路径必须位于 `.Knowledge/stock-docs/`。
28
+ - **须为终稿**：推荐文件名含 `_终稿.md`，或已由 **`f2s-doc-final`** 规范化；**禁止**以 `f2s-doc-arch` 产出的 `*_初稿.md` 作为入参直接执行本技能。
29
+ - 若入参路径含 **`_初稿`**、或用户刚完成架构初稿尚未执行 `f2s-doc-final`：**停止**，回复须先执行 **`f2s-doc-final <初稿路径>`**，待终稿落盘后再以终稿路径调用本技能。
28
30
  - 若传入 `.Knowledge/req-docs/`，提示用户先整理为 `stock-docs` 终稿后再执行。
29
31
 
30
32
  ## 生成原则
@@ -89,10 +91,10 @@ description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索
89
91
 
90
92
  ## 复杂场景示例
91
93
 
92
- 用户输入：`f2s-ctx-build .Knowledge/stock-docs/回调改造_终稿.md`，且现有 `topics/callback.md` 已存在。
94
+ 用户输入：`f2s-ctx-build .Knowledge/stock-docs/<能力>_终稿.md`，且现有 `topics/<能力>.md` 已存在。
93
95
 
94
- - 若新文档与现有 `callback` 主题高度重合：原位更新 `topics/callback.md`，不要新建 `callback-v2.md`。
95
- - 若新文档新增「重试补偿」子能力：可新增 `topics/callback-retry.md`，并在 `manifest-routing.topicDependencies` 中声明 `callback-retry -> callback`。
96
+ - 若新文档与现有 `<能力>` 主题高度重合：原位更新 `topics/<能力>.md`，不要新建 `<能力>-v2.md`。
97
+ - 若新文档新增子能力：可新增 `topics/<能力>-<子域>.md`，并在 `manifest-routing.topicDependencies` 中声明依赖关系。
96
98
  - 更新后同步 `index` 与路由清单，确保 `topicPaths`、`fallbackTopic`、`matcherId` 仍有效。
97
99
 
98
100
  ## 完成后自检
package/templates/skills/f2s-doc-arch/SKILL.md CHANGED
@@ -25,7 +25,7 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
25
25
  ## 入参（均可选）
26
26
 
27
27
  | 参数 | 说明 |
28
- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
28
+ | -------------- | -------------------------- |
29
29
  | **第一个参数** | 可选。可为以下之一：**一段纯文字说明**（直接写在命令后）、**本地文档路径**（如 `.Knowledge/stock-docs/xxx.md`、`.Knowledge/req-docs/README.md`、`README.md`）。不传则进入「无输入」流程。 |
30
30
  | **第二个参数** | 可选。输出文件路径；若不传，默认写入 `.Knowledge/stock-docs/架构说明_初稿.md`（项目名可从 package.json 的 name 或目录名推断，做合法文件名处理）。 |
31
31
 
@@ -68,7 +68,20 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
68
68
  ## 引导与迭代
69
69
 
70
70
  - 用户说明若**范围较大**（如「整个中台」），可提示：建议补充**主要代码路径、子模块/包名、对外入口、依赖关系**等，并可在本次或后续对话中分批补充，再重新执行本技能更新初稿。
71
- - 生成初稿后，可提示用户：可根据需要修改 `.Knowledge/stock-docs/xxx架构说明_初稿.md`，若需转为《终稿模版》规范格式，可再按 **f2s-doc-final** 技能，以该路径为入参得到终稿，再按 **f2s-ctx-build** 同步知识路由主题与索引。
71
+
72
+ ## 完成后的下一步（硬约束）
73
+
74
+ 本技能**只产出初稿**；结束时须按下列顺序引导，**禁止**让用户跳过终稿直接 `f2s-ctx-build`：
75
+
76
+ 1. 告知初稿路径，建议用户先审阅、补充内容。
77
+ 2. **下一步必须为 `f2s-doc-final`**：以初稿路径为入参，产出 `.Knowledge/stock-docs/<方案名>_终稿.md`（《终稿模版》规范格式）。
78
+ 3. **仅在终稿落盘后**再引导 **`f2s-ctx-build`**，且入参须为终稿路径（含 `_终稿` 或由 `f2s-doc-final` 刚生成）。
79
+ 4. **禁止**在完成回复中单独写「请执行 `f2s-ctx-build`」且入参指向 `*_初稿.md`；**禁止**将 `f2s-ctx-build` 与 `f2s-doc-final` 并列成「二选一」。
80
+ 5. **唯一例外**：用户**明确要求**跳过终稿、且初稿已人工符合终稿模版——须先说明跳过终稿的风险，再允许指向 `f2s-ctx-build`。
81
+
82
+ **完成回复模板**（须同时包含 `f2s-doc-final` 与 `f2s-ctx-build`，且 ctx-build 在终稿之后）：
83
+
84
+ > 已生成架构说明初稿：`<初稿路径>`。请先审阅修改；下一步请执行 **`f2s-doc-final <初稿路径>`** 转为终稿，再执行 **`f2s-ctx-build <终稿路径>`** 同步知识路由主题与索引。
72
85
 
73
86
  ---
74
87
 
@@ -84,4 +97,4 @@ description: 根据用户说明或文档（或扫描代码）生成项目架构
84
97
 
85
98
  - **不强制格式**：本技能产出为「架构说明初稿」，以描述清楚为主，不要求符合《终稿模版》或固定章节结构。
86
99
  - **无参数时必须确认**：用户未传任何参数时，必须先提示「是否确认不传递参数，仍使用 AI 扫描代码生成？（不保证质量）」，仅当用户明确确认后才执行扫描与生成。
87
- - 完成后用一句话总结：已生成架构说明初稿的路径，并视情况提示可补充的内容或下一步（如 f2s-doc-final、f2s-ctx-build）。
100
+ - 完成后按上文「完成回复模板」总结：初稿路径 + **必须先 `f2s-doc-final` 再 `f2s-ctx-build`**；不得仅推荐 build。