@double-codeing/flow2spec 3.0.14 → 3.0.15

package/docs/{usage-guide.en.md → en/usage-guide.md}

@@ -1,4 +1,4 @@
-[中文](./Flow2Spec使用说明.md) | [English](./usage-guide.en.md)
+[中文](../使用说明.md) | [English](./usage-guide.md)
 
 # Flow2Spec Usage Guide
 
@@ -32,7 +32,7 @@ Before executing any **`f2s-*` skill**, the Agent needs to obtain the actual val
 | **Codex** | `.codex/AGENTS.md` top-level mandatory step + `{{FLOW2SPEC_PROJECT_CONFIG}}` expansion table | **Read** is a hard requirement; the config table is a **snapshot from the last `flow2spec init`** — when it differs from disk, **Read** takes precedence. The adjacent **`.codex/topics/f2s-config-check.md`** shares its origin with the Cursor rule (including the **changeTracking** detail table); open it **as needed** — it does not need to be grouped with the three "topic long-form" examples as required reading. |
 | **Knowledge Base (optional)** | When `.Knowledge/manifest-routing` hits **`config-precheck`** | `.Knowledge/topics/f2s-config-precheck.md` is a **routing summary** that links to the Codex long-form article; Flow2Spec does **not** maintain a second full copy in `.Knowledge`, nor does it replace a `Read` of the JSON. |
 
-For field semantics and default value rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.en.md). For the design perspective, see [Design Principles § 4.5.1](./design-principles.en.md).
+For field semantics and default value rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.md). For the design perspective, see [Design Principles § 4.5.1](./design-principles.md).
 
 ---
 
@@ -40,33 +40,29 @@ For field semantics and default value rules, see [Commands Reference § 6) Sub-A
 
 Core distinction: `stock-docs/` holds solidified documents (driving knowledge routing), `req-docs/` holds technical designs (driving coding implementation); they are not interchangeable.
 
-See [Directory Conventions](./directory-conventions.en.md) for the full directory description.
+See [Directory Conventions](./directory-conventions.md) for the full directory description.
 
 ---
 
 ## 3. Typical Workflows
 
-### Requirements Planning and Implementation
+### Change Tracking and Cross-Session Continuation (Recommended)
 
-```
-f2s-req-plan
-```
-
-Provide a path to the technical design document or a requirements description. A draft task checklist is produced first and awaits confirmation. After confirmation, implementation proceeds according to the checklist. A `.task/` task checklist is always created — no `changeTracking` configuration is needed. Suitable for scenarios where you want to see the full picture before starting, or need cross-session progress tracking.
+Enable `changeTracking` per skill in `flow2spec.config.json` (each sub-field is independent):
 
-### Change Tracking and Cross-Session Continuation
-
-```
-# Automatic mode: enabled by config (independent per skill)
-flow2spec.config.json → changeTracking.feat / fix / implement: true
-
-# Explicit mode: call f2s-req-plan (planning + implementation, no config dependency)
-f2s-req-plan
+```json
+{
+  "changeTracking": {
+    "feat": true,
+    "fix": true,
+    "implement": true
+  }
+}
 ```
 
-**Automatic mode**: When enabled, `f2s-kb-feat` / `f2s-kb-fix` / `f2s-implement-tech-design` automatically create a task checklist under `.task/active/`, check off steps progressively, and archive upon completion. In subsequent sessions, when describing related content, the `f2s-task` rule automatically matches and loads the remaining checklist — no need to re-explain the context.
+When enabled, `f2s-kb-feat` / `f2s-kb-fix` / `f2s-implement-tech-design` automatically create a checklist under `.task/active/`, check off steps, and archive on completion. In later sessions, the `f2s-task` rule matches related wording and resumes the remaining steps — no need to re-explain context.
 
-**Explicit mode**: Call `f2s-req-plan` directly — regardless of the `changeTracking` configuration, a task checklist is always created and code is implemented against it. Suitable for scenarios where you want to confirm the full picture before taking action.
+If **`changeTracking` is off** but you still need a `.task/` checklist temporarily, call `f2s-req-plan` explicitly (always creates a checklist, ignores config) — a **fallback**, not the default path. See [Commands Reference § f2s-req-plan](./commands-reference.md).
 
 ### New Feature Development
 
@@ -80,18 +76,10 @@ When requirements are already clear, `f2s-req-clarify` can be skipped, starting
 
 ```
 New architecture document ingestion: f2s-doc-arch → f2s-doc-final → f2s-ctx-build
-PDF document ingestion:          f2s-doc-pdf  → f2s-doc-final → f2s-ctx-build
-```
-
-Integrate architecture descriptions or PDF technical designs into the knowledge routing (generates topics/matchers/manifest-routing).
-
-### PDF-Based Implementation
-
-```
-f2s-doc-pdf → implement-tech-design
+PDF/draft ingestion:               f2s-doc-final → f2s-ctx-build
 ```
 
-Convert a PDF technical design to Markdown and place it in `req-docs/`, then let the `implement-tech-design` rule drive coding.
+Integrate architecture descriptions or PDF final drafts into knowledge routing (generates topics/matchers/manifest-routing). To ingest a PDF into the knowledge base, use `f2s-doc-final` then `f2s-ctx-build`. `f2s-doc-pdf` only converts a PDF to Markdown under `req-docs/` for editing; it is **not** the recommended path for "PDF straight to coding."
 
 ### Backfilling Existing Capabilities
 
@@ -122,7 +110,7 @@ f2s-kb-upgrade (Current V2+: already has .Knowledge; includes npm v3.x projects,
 
 ## 4. Agent Execution Configuration
 
-Controlled via the project root `flow2spec.config.json`. For complete field rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.en.md). **How each client is reminded to read the config, and why `Read` remains authoritative** — see **§ 1** (this § only explains **when** to toggle each switch).
+Controlled via the project root `flow2spec.config.json`. For complete field rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.md). **How each client is reminded to read the config, and why `Read` remains authoritative** — see **§ 1** (this § only explains **when** to toggle each switch).
 
 **When to enable `subAgent: true`**: When the task is large (multi-module parallel implementation, batch document ingestion, large-scale migration). When enabled, each skill decides whether to actually split based on its own size threshold; tasks below the threshold are still completed within the main agent.
 
@@ -140,7 +128,7 @@ Controlled via the project root `flow2spec.config.json`. For complete field rule
 }
 ```
 
-If you prefer not to rely on configuration and want to explicitly plan tasks on demand, use `f2s-req-plan` directly.
+Use `f2s-req-plan` only when all `changeTracking` sub-fields are off and you still need a checklist (see § 3 footnote).
 
 ---
 
@@ -159,7 +147,7 @@ Skills are triggered by matching `name` and `description`. Files are located und
 
 ## 7. Related Documents
 
-- [Commands Reference](./commands-reference.en.md)
-- [Directory Conventions](./directory-conventions.en.md)
-- [Architecture](./architecture.en.md)
-- [Usage Scenarios](./usage-scenarios.en.md)
+- [Commands Reference](./commands-reference.md)
+- [Directory Conventions](./directory-conventions.md)
+- [Architecture](./architecture.md)
+- [Usage Scenarios](./usage-scenarios.md)

package/docs/{usage-scenarios.en.md → en/usage-scenarios.md}

@@ -1,4 +1,4 @@
-[中文](./Flow2Spec-使用案例-模拟对话.md) | [English](./usage-scenarios.en.md)
+[中文](../使用案例-模拟对话.md) | [English](./usage-scenarios.md)
 
 # Flow2Spec Usage Scenarios (Simulated Dialogues)
 
@@ -123,33 +123,7 @@ The following examples revolve around the same e-commerce project, covering the
 
 ---
 
-## Scenario 4: PDF Design -> Implementation
-
-**You**
-
-> /f2s-doc-pdf /Users/me/Downloads/marketing-coupon-v2.pdf
-
-**Agent**
-
-> Converted and saved as `.Knowledge/req-docs/marketing-coupon-v2.md`. Filled in the idempotency handling flow description and error code explanations that were missing in the PDF.
-
-**You**
-
-> Implement according to `.Knowledge/req-docs/marketing-coupon-v2.md`
-
-**Agent**
-
-> I have read the design document. Task list for implementation:
->
-> 1. Create `CouponController` (coupon claim, redemption, and return endpoints)
-> 2. Create `CouponService` with inventory deduction and idempotency checks
-> 3. ...
->
-> Before proceeding, I need to confirm: is the coupon inventory managed via Redis or database row locks?
-
----
-
-## Scenario 5: Post-Implementation Knowledge Base Recording
+## Scenario 4: Post-Implementation Knowledge Base Recording
 
 **You**
 
@@ -177,7 +151,7 @@ The following examples revolve around the same e-commerce project, covering the
 
 ---
 
-## Scenario 6: Non-compliant Implementation Found, Fix and Sync Knowledge Base
+## Scenario 5: Non-compliant Implementation Found, Fix and Sync Knowledge Base
 
 **You**
 
@@ -191,7 +165,7 @@ The following examples revolve around the same e-commerce project, covering the
 
 ---
 
-## Scenario 7: Knowledge Base Conflicts After Git Merge
+## Scenario 6: Knowledge Base Conflicts After Git Merge
 
 **You**
 
@@ -216,7 +190,7 @@ The following examples revolve around the same e-commerce project, covering the
 
 ## Related Documentation
 
-- [Usage Guide](./usage-guide.en.md)
-- [Commands Reference](./commands-reference.en.md)
-- [Directory Conventions](./directory-conventions.en.md)
-- [Architecture](./architecture.en.md)
+- [Usage Guide](./usage-guide.md)
+- [Commands Reference](./commands-reference.md)
+- [Directory Conventions](./directory-conventions.md)
+- [Architecture](./architecture.md)

package/docs/{README- → }/344/275/223/347/263/273/344/270/216/345/216/237/347/220/206.md

@@ -1,22 +1,63 @@
 # 体系与原理
 
-Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开：
+[English](./en/architecture.md)
 
-- **知识层**：`.Knowledge`（文档与索引）
-- **执行层**：配置根 `rules/skills`（供各工具原生加载）
+Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开，并在仓库里用 **Memory Coding（记忆编码）** 把「要记住的东西」落盘为可 diff、可评审的 Git 资产。
+
+- **知识环**（`.Knowledge/`）：业务文档与机读路由（见下文多层结构）
+- **任务环**（`.task/`）：跨会话续作清单
+- **规则环**（各工具 `rules` / `AGENTS.md`）：规定 Agent **怎么读、怎么做**
+- **技能环**（`f2s-*`）：维护知识、触发流程
+
+> Flow2Spec ≠ 只有知识库；上述四环同属 Memory Coding，下文「两层结构」描述的是**知识环 vs 工具侧执行落点**的生命周期分工。
+
+---
+
+## 1. Memory Coding 与仓内四环
+
+**Memory Coding**：把必须长期记住的上下文**编码进可提交仓库**——不押在模型私有 Memory、不只在聊天里重复，也不靠全仓向量概率猜。
+
+仓内拆成 **四环**（勿说成「三环」把规则与技能合并）：
+
+| 环 | 落点 | 记什么 |
+| --- | --- | --- |
+| **知识环** | `.Knowledge/` | 路由、主题、存量/需求文档（见 §2 多层） |
+| **任务环** | `.task/` | `todo.json`、checklist、用户代办 |
+| **规则环** | `.cursor/.claude/.codex` 下 rules、`AGENTS.md` | 读取顺序、缺口闸门、实现约束 |
+| **技能环** | 配置根 `skills/*/SKILL.md` | `f2s-kb-feat/fix/sync` 等维护与触发 |
+
+与「两层结构」的关系：**知识环**对应「随项目走」的知识层；**规则环 + 技能环**落在各工具配置根，随工具升级迭代；**任务环**与 `.Knowledge/` 并列于仓内，不属于 `.Knowledge/` 目录。
+
+---
+
+## 2. 知识环内的多层记忆结构
+
+`.Knowledge/` 不是扁平「一堆 Markdown」，而是 **横读（渐进式路由）+ 纵链（主题依赖）** 的多层记忆：
+
+| 层级 | 路径 / 机制 | 记什么 | 典型读法 |
+| --- | --- | --- | --- |
+| **L0 路由索引** | `manifest-routing.json` | task→topic、`topicDependencies`、`topicPaths` | 会话首读（机读事实源） |
+| **L1 关键词分片** | `matchers/<id>.json` | `includeAny` 触发词 | **match**：只打开命中的一个分片 |
+| **L2 主题摘要** | `topics/<topic>.md` | 硬约束摘要、边界、下一步指针 | **expand**：拉齐依赖主题 |
+| **L3 长文档** | `stock-docs/`、`req-docs/` | 架构终稿、技术方案全文 | 按需下钻背景 |
+| **纵链（横切）** | `topicDependencies` | 通用约定 → 子域 → 白名单 → 本域细则 | **expand** 时按依赖顺序叠层 |
+
+**渐进式读取**（`match → expand → verify → act`）作用在 L0–L2（必要时再到 L3）：先收窄入口，再展开依赖与缺口检查，最后才改代码。主题级依赖挂一次、所有任务共享，避免每个任务重复声明前置约束。
+
+人读导航：`index.md` 仅作语义边界校验，**不**替代 `manifest-routing` 机读链。
 
 ---
 
-## 1. 两层结构
+## 3. 知识层与执行层（两层结构）
 
 | 层 | 位置 | 作用 |
 | --- | --- | --- |
-| 知识层 | `.Knowledge/` | 保存业务文档、索引、路由 |
-| 执行层 | `.cursor/.claude/.codex` | 保存规则与技能入口 |
+| 知识层（知识环） | `.Knowledge/` | 保存业务文档、索引、路由（§2 多层） |
+| 执行层（规则环 + 技能环） | `.cursor/.claude/.codex` | 保存规则与技能入口 |
 
 ---
 
-## 2. 渐进式读取
+## 4. 渐进式读取
 
 统一建议顺序：
 
@@ -33,7 +74,7 @@ Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开：
 
 ---
 
-## 3. 关键链路
+## 5. 关键链路
 
 - 文档沉淀链：`f2s-doc-arch` → `f2s-doc-final` → `f2s-ctx-build`
 - 实现链：`.Knowledge/req-docs/*.md` → `implement-tech-design` → 代码
@@ -44,13 +85,13 @@ Flow2Spec 的目标是把"业务知识沉淀"与"Agent 能力加载"拆开：
 
 ---
 
-## 4. Agent 执行模型
+## 6. Agent 执行模型
 
 Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentVerification` 两个字段控制执行行为。
 
-**Agent 如何读到上述真值**：多端提示 + **Read** 权威，见 [Flow2Spec使用说明 § 一（唯一详表）](./Flow2Spec使用说明.md)；设计归纳见 [Flow2Spec-设计说明 § 四、5.1](./Flow2Spec-设计说明.md)。
+**Agent 如何读到上述真值**：多端提示 + **Read** 权威，见 [使用说明 § 一（唯一详表）](./使用说明.md)；设计归纳见 [设计说明 § 四、5.1](./设计说明.md)。
 
-### 4.1 主/子 Agent 职责划分原则
+### 6.1 主/子 Agent 职责划分原则
 
 **`subAgent: false`（默认）**：全部 `f2s-*` 技能在主 agent 内顺序完成，无并行拆分。
 
@@ -63,7 +104,7 @@ Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentV
 
 子 agent 的拆分边界由各 `f2s-*` 技能正文逐步约定（如模块数、文档数、代码行数等门槛），**当前尚未在模板层给出统一阶段表**，以技能正文为准。
 
-### 4.2 验证归属原则
+### 6.2 验证归属原则
 
 **默认（谁落盘谁验）**：落盘或变更后的验证在落盘侧 agent 内完成。子 agent 落盘则子 agent 自验，主 agent 落盘则主 agent 自验。
 
@@ -81,7 +122,7 @@ Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentV
 
 设计意图：交叉验证引入外部视角，降低落盘侧的自验盲区，但增加执行开销，因此设为显式 opt-in 而非默认行为。
 
-### 4.3 变更追踪（changeTracking）
+### 6.3 变更追踪（changeTracking）
 
 `changeTracking` 是独立于 `subAgent` / `switchAgentVerification` 的第三个维度，控制技能执行时是否自动创建可跨会话续作的任务清单。
 
@@ -102,7 +143,7 @@ Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentV
 
 ---
 
-## 5. 设计收益
+## 7. 设计收益
 
 1. 跨工具共享同一业务知识源
 2. 不破坏 Claude/Cursor/Codex 的规则加载习惯
@@ -112,9 +153,9 @@ Flow2Spec 通过项目根 `flow2spec.config.json` 的 `subAgent`、`switchAgentV
 
 ---
 
-## 6. 相关文档
+## 8. 相关文档
 
-- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
-- [README-命令说明](./README-命令说明.md)
-- [README-目录与路径约定](./README-目录与路径约定.md)
-- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [使用说明](./使用说明.md)
+- [命令说明](./命令说明.md)
+- [目录与路径约定](./目录与路径约定.md)
+- [使用案例-模拟对话](./使用案例-模拟对话.md)

package/docs/{Flow2Spec- → }/344/275/277/347/224/250/346/241/210/344/276/213-/346/250/241/346/213/237/345/257/271/350/257/235.md

@@ -1,5 +1,7 @@
 # Flow2Spec 使用案例（模拟对话）
 
+[English](./en/usage-scenarios.md)
+
 以下示例围绕同一个电商项目展开，贯穿从需求澄清到上线后维护的完整流程。
 
 **前提**：项目已执行 `flow2spec init`，`flow2spec.config.json` 使用默认配置（`subAgent: false`）。`f2s-*` 技能不改动配置根 `rules/`、`skills/` 文件。
@@ -121,33 +123,7 @@
 
 ---
 
-## 场景四：PDF 方案 → 实现
-
-**你**
-
-> /f2s-doc-pdf /Users/me/Downloads/营销优惠券_v2.pdf
-
-**Agent**
-
-> 已转换并保存为 `.Knowledge/req-docs/营销优惠券_v2.md`，补全了 PDF 中缺失的幂等处理流程描述和错误码说明。
-
-**你**
-
-> 按方案实现：`.Knowledge/req-docs/营销优惠券_v2.md`
-
-**Agent**
-
-> 已读取方案，输出实现任务列表：
->
-> 1. 新建 `CouponController`（领券、核销、退券接口）
-> 2. 新建 `CouponService`，含库存扣减与幂等校验
-> 3. …
->
-> 实现前确认：优惠券库存是用 Redis 还是数据库行锁？
-
----
-
-## 场景五：实现后补录知识库
+## 场景四：实现后补录知识库
 
 **你**
 
@@ -175,7 +151,7 @@
 
 ---
 
-## 场景六：发现违规实现，修复并同步知识库
+## 场景五：发现违规实现，修复并同步知识库
 
 **你**
 
@@ -189,7 +165,7 @@
 
 ---
 
-## 场景七：Git 合并后知识库冲突
+## 场景六：Git 合并后知识库冲突
 
 **你**
 
@@ -214,7 +190,7 @@
 
 ## 相关文档
 
-- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
-- [README-命令说明](./README-命令说明.md)
-- [README-目录与路径约定](./README-目录与路径约定.md)
-- [README-体系与原理](./README-体系与原理.md)
+- [使用说明](./使用说明.md)
+- [命令说明](./命令说明.md)
+- [目录与路径约定](./目录与路径约定.md)
+- [体系与原理](./体系与原理.md)

package/docs/{Flow2Spec → }/344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -1,5 +1,7 @@
 # Flow2Spec 使用说明
 
+[English](./en/usage-guide.md)
+
 ## 一、init 做了什么
 
 在业务仓库根执行：
@@ -30,7 +32,7 @@ flow2spec init [cursor|claude|codex ...] --reset-knowledge
 | **Codex** | `.codex/AGENTS.md` 顶部强制步骤 + `{{FLOW2SPEC_PROJECT_CONFIG}}` 展开表 | **Read** 为硬要求；配置表为 **最近一次 `flow2spec init` 的快照**，与磁盘不一致时以 **Read** 为准。同目录 **`.codex/topics/f2s-config-check.md`** 与 Cursor 规则同源（含 **changeTracking** 细表），**按需**打开即可，不必与「专题长文」三条示例并列必读。 |
 | **知识库（可选）** | `.Knowledge/manifest-routing` 命中 **`config-precheck`** 时 | `.Knowledge/topics/f2s-config-precheck.md` 为**路由摘要**，链向 Codex 长文；**不**在 `.Knowledge` 再维护第二份全文，也**不**替代 Read JSON。 |
 
-字段语义与默认值规则见 [README-命令说明 § 6) 子 Agent 配置说明](./README-命令说明.md)。设计视角见 [Flow2Spec-设计说明 § 四、5.1](./Flow2Spec-设计说明.md)；口述见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)。
+字段语义与默认值规则见 [命令说明 § 6) 子 Agent 配置说明](./命令说明.md)。设计视角见 [设计说明 § 四、5.1](./设计说明.md)；口述见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)。
 
 ---
 
@@ -38,33 +40,29 @@ flow2spec init [cursor|claude|codex ...] --reset-knowledge
 
 核心区分：`stock-docs/` 放沉淀文档（驱动知识路由），`req-docs/` 放技术方案（驱动编码实现），两者不互换。
 
-完整目录说明见 [README-目录与路径约定](./README-目录与路径约定.md)。
+完整目录说明见 [目录与路径约定](./目录与路径约定.md)。
 
 ---
 
 ## 三、典型工作场景
 
-### 需求规划并实现
-
-```
-f2s-req-plan
-```
-
-输入技术方案文档路径或需求描述，先输出任务清单草稿并等待确认，确认后按清单实现代码。始终创建 `.task/` 任务清单，不需要配置 `changeTracking`。适合希望先看清全貌再动手、或需要跨会话追踪进度的场景。
+### 变更追踪与跨会话续作（推荐）
 
-### 变更追踪与跨会话续作
+在 `flow2spec.config.json` 按技能开启 `changeTracking`（各子项独立）：
 
-```
-# 自动模式：配置开启（各技能独立）
-flow2spec.config.json → changeTracking.feat / fix / implement: true
-
-# 显式模式：调用 f2s-req-plan（规划 + 实现，不依赖配置）
-f2s-req-plan
+```json
+{
+  "changeTracking": {
+    "feat": true,
+    "fix": true,
+    "implement": true
+  }
+}
 ```
 
-**自动模式**：开启后，`f2s-kb-feat` / `f2s-kb-fix` / `f2s-implement-tech-design` 执行时自动在 `.task/active/` 创建任务清单，逐步勾选，完成后归档。下次会话描述相关内容，`f2s-task` 规则自动匹配并加载剩余清单，无需重新说明上下文。
+开启后，`f2s-kb-feat` / `f2s-kb-fix` / `f2s-implement-tech-design` 执行时会在 `.task/active/` 自动创建任务清单，逐步勾选，完成后归档。下次会话描述相关内容时，`f2s-task` 规则会匹配并加载剩余步骤，无需重复交代上下文。
 
-**显式模式**：直接调用 `f2s-req-plan`，不管 `changeTracking` 配置，始终创建任务清单并按清单实现代码，适合希望先确认全貌再动手的场景。
+若你**关闭了** `changeTracking` 但仍临时需要 `.task/` 清单，可显式调用 `f2s-req-plan`（不读配置、始终建清单）——这是兜底用法，非常规主路径；详见 [命令说明 § f2s-req-plan](./命令说明.md)。
 
 ### 新需求开发
 
@@ -78,18 +76,10 @@ f2s-req-clarify → f2s-req-backend → implement-tech-design → f2s-kb-feat
 
 ```
 新增架构文档沉淀：f2s-doc-arch → f2s-doc-final → f2s-ctx-build
-PDF 文档沉淀：    f2s-doc-pdf  → f2s-doc-final → f2s-ctx-build
-```
-
-把架构说明或 PDF 技术方案纳入知识路由（生成 topics/matchers/manifest-routing）。
-
-### PDF 方案实现
-
-```
-f2s-doc-pdf → implement-tech-design
+PDF/初稿沉淀：     f2s-doc-final → f2s-ctx-build
 ```
 
-拿到 PDF 技术方案后直接转 Markdown 落入 `req-docs/`，再由 `implement-tech-design` 规则驱动编码。
+把架构说明或 PDF 终稿纳入知识路由（生成 topics/matchers/manifest-routing）。若仅有 PDF 且要入库，先用 `f2s-doc-final` 转为终稿再 `f2s-ctx-build`；`f2s-doc-pdf` 仅把 PDF 转为 `req-docs/` 下的 Markdown 便于编辑，**不**作为「PDF 直驱编码」的推荐路径。
 
 ### 存量能力补录
 
@@ -120,7 +110,7 @@ f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，
 
 ## 四、Agent 执行配置
 
-通过项目根 `flow2spec.config.json` 控制，字段完整规则见 [README-命令说明 § 6) 子 Agent 配置说明](./README-命令说明.md)。**各端如何被提示读到配置、为何仍以 Read 为权威**见 **§ 一**（本 § 仅说明**何时**打开各开关）。
+通过项目根 `flow2spec.config.json` 控制，字段完整规则见 [命令说明 § 6) 子 Agent 配置说明](./命令说明.md)。**各端如何被提示读到配置、为何仍以 Read 为权威**见 **§ 一**（本 § 仅说明**何时**打开各开关）。
 
 **何时开启 `subAgent: true`**：任务规模较大时（多模块并行实现、批量文档入库、大规模迁移）。开启后各技能按自身规模门槛决定是否实际拆分，未达门槛的仍在主 agent 内完成。
 
@@ -138,7 +128,7 @@ f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，
 }
 ```
 
-不想依赖配置、希望按需显式规划任务时，直接使用 `f2s-req-plan`。
+`changeTracking` 全关且仍要任务清单时，再考虑 `f2s-req-plan`（见 § 三「变更追踪」脚注）。
 
 ---
 
@@ -157,7 +147,7 @@ f2s-kb-upgrade（流程现行库 V2+：已有 .Knowledge；含 npm v3.x 等，
 
 ## 七、相关文档
 
-- [README-命令说明](./README-命令说明.md)
-- [README-目录与路径约定](./README-目录与路径约定.md)
-- [README-体系与原理](./README-体系与原理.md)
-- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [命令说明](./命令说明.md)
+- [目录与路径约定](./目录与路径约定.md)
+- [体系与原理](./体系与原理.md)
+- [使用案例-模拟对话](./使用案例-模拟对话.md)

package/docs/{README- → }/345/221/275/344/273/244/350/257/264/346/230/216.md

@@ -1,5 +1,7 @@
 # 工作流与技能说明
 
+[English](./en/commands-reference.md)
+
 ## 1) 文档沉淀（stock-docs 链路）
 
 ### `f2s-doc-arch`
@@ -179,21 +181,19 @@
 
 **作用**：将 PDF 技术方案转为 Markdown 格式，保存到 `req-docs/`，可补全流程说明。
 
-**工作原理**：面向「按方案实现代码」的前置环节——将 PDF 中的接口定义、数据模型、时序流程等结构化内容提取为 Markdown 格式并落盘 `req-docs/`。与 `f2s-doc-final` 的区别在于目标路径和用途：`doc-pdf` 输出到 `req-docs/` 供 `implement-tech-design` 规则消费驱动编码，`doc-final` 输出到 `stock-docs/` 供 `ctx-build` 入库。
+**工作原理**：将 PDF 中的接口定义、数据模型、时序流程等提取为 Markdown 并落盘 `req-docs/`，便于后续编辑或与 `f2s-req-clarify` / `f2s-req-backend` 衔接。与 `f2s-doc-final` 的区别：`doc-pdf` 输出到 `req-docs/`（实现侧文档目录），`doc-final` 输出到 `stock-docs/` 供 `ctx-build` 入库。**不推荐**把「PDF 转 MD」当作跳过澄清与后端技术方案的直驱编码路径。
 
 **使用场景**：
 
-- 收到 PDF 格式技术方案需要实现
-- 历史 PDF 文档需要纳入管理
-- 跨团队交付物为 PDF 时需要转换
+- 跨团队交付物为 PDF，需转为可编辑的 Markdown
+- 历史 PDF 技术方案需纳入 `req-docs/` 管理
+- 为后续 `f2s-req-clarify` / `f2s-req-backend` 提供可读底稿
 
 **关联关系**：
 
 - **前置**：PDF 文档
 - **输出**：`.Knowledge/req-docs/<方案>.md`
-- **下一步**：
-  - 1. 如果是需求实现：提供转换后的方案路径并说明"按技术方案实现"，由 `implement-tech-design` 规则驱动编码
-  - 1. 如果是转存知识库：走转换终稿流程 `f2s-doc-final` → `f2s-ctx-build`
+- **下一步**（推荐）：`f2s-req-clarify` → `f2s-req-backend` → 按 `req-docs/` 中技术方案 MD 触发 `implement-tech-design`；若目标是知识库沉淀则 `f2s-doc-final` → `f2s-ctx-build`
 
 **子 agent 调用**：
 
@@ -694,7 +694,7 @@
 
 ### 多端如何「看到」配置（与下文字段表配合）
 
-`subAgent` 等写在 **磁盘 JSON**；各产品不保证自动打开文件，故用 **Cursor 规则 / Claude hook / Codex AGENTS 快照表 / 知识库 `config-precheck` 摘要** 多层提示，**权威仍为 Read(`flow2spec.config.json`)**（设计意图见 [Flow2Spec-设计说明 § 四、5.1](./Flow2Spec-设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[Flow2Spec使用说明 § 一、`f2s-`* 与 `flow2spec.config.json](./Flow2Spec使用说明.md)`。
+`subAgent` 等写在 **磁盘 JSON**；各产品不保证自动打开文件，故用 **Cursor 规则 / Claude hook / Codex AGENTS 快照表 / 知识库 `config-precheck` 摘要** 多层提示，**权威仍为 Read(`flow2spec.config.json`)**（设计意图见 [设计说明 § 四、5.1](./设计说明.md)，演讲口径见 [Flow2Spec-演讲稿 Slide 13b](./Flow2Spec-演讲稿.md)）。**完整路径与表格只维护一处**：[使用说明 § 一、`f2s-`* 与 `flow2spec.config.json](./使用说明.md)`。
 
 ### `subAgent` 字段
 
@@ -738,22 +738,22 @@
 
 > `f2s-req-plan` 不受此配置约束，始终创建任务清单。旧版布尔值（`"changeTracking": true/false`）向下兼容，自动展开为三项全开/全关。
 
-完整原则与设计意图见 [README-体系与原理 § 4. Agent 执行模型](./README-体系与原理.md)。
+完整原则与设计意图见 [体系与原理 § 4. Agent 执行模型](./体系与原理.md)。
 
 ---
 
 ## 7) 快速参考
 
-典型工作场景与完整链路见 [Flow2Spec使用说明 § 三、典型工作场景](./Flow2Spec使用说明.md)。
+典型工作场景与完整链路见 [使用说明 § 三、典型工作场景](./使用说明.md)。
 
-目录完整说明见 [README-目录与路径约定](./README-目录与路径约定.md)。
+目录完整说明见 [目录与路径约定](./目录与路径约定.md)。
 
 ---
 
 相关文档：
 
-- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
-- [README-目录与路径约定](./README-目录与路径约定.md)
-- [README-体系与原理](./README-体系与原理.md)
-- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [使用说明](./使用说明.md)
+- [目录与路径约定](./目录与路径约定.md)
+- [体系与原理](./体系与原理.md)
+- [使用案例-模拟对话](./使用案例-模拟对话.md)
 

package/docs/{README- → }/347/233/256/345/275/225/344/270/216/350/267/257/345/276/204/347/272/246/345/256/232.md

@@ -1,9 +1,14 @@
 # 目录与路径约定
 
+[English](./en/directory-conventions.md)
+
 ## 核心边界
 
-- `.Knowledge/`：只放业务知识文档与索引
-- `配置根`（`.cursor/.claude/.codex`）：放规则与技能入口
+- `.Knowledge/`：**知识环**——业务知识文档与机读路由（见 [体系与原理 §2 多层记忆](./体系与原理.md)）
+- `.task/`：**任务环**——变更追踪与跨会话续作（不在 `.Knowledge/` 内）
+- `配置根`（`.cursor/.claude/.codex`）：**规则环 + 技能环**入口
+
+Memory Coding 四环总览见 [体系与原理 §1](./体系与原理.md)。
 
 ---
 
@@ -11,13 +16,15 @@
 
 | 路径 | 职责 |
 | --- | --- |
-| `.Knowledge/stock-docs/` | 架构、终稿、沉淀文档 |
-| `.Knowledge/req-docs/` | 需求澄清、技术方案 |
-| `.Knowledge/topics/` | 主题路由文档（用于规则与流程执行） |
+| `docs/` | 产品说明（**中文**）：使用说明、命令说明、设计说明等 |
+| `docs/en/` | 产品说明（**英文**）：与上表一一对应的 6 篇文档，见 [en/README.md](./en/README.md) |
+| `.Knowledge/stock-docs/` | **L3** 架构、终稿、沉淀长文档 |
+| `.Knowledge/req-docs/` | **L3** 需求澄清、技术方案长文档 |
+| `.Knowledge/topics/` | **L2** 主题摘要（硬约束、边界、路由指针） |
 | `.Knowledge/template/` | 终稿/技术方案模板 |
 | `.Knowledge/index.md` | 人类可读索引 |
-| `.Knowledge/manifest-routing.json` | 机器可读路由骨架（task/topic/dependencies） |
-| `.Knowledge/matchers/*.json` | 关键词分片（`id/includeAny`），由 `manifest-routing.taskToTopicRules[].matcherPath` 直链指向 |
+| `.Knowledge/manifest-routing.json` | **L0** 机读路由骨架（task/topic/`topicDependencies`） |
+| `.Knowledge/matchers/*.json` | **L1** 关键词分片（`id/includeAny`），由 `matcherPath` 直链；**match** 只读一片 |
 | `.Knowledge/migration-report.md` | `f2s-kb-migrate` 落盘的迁移对照表与拟删除路径列表 |
 | `.task/` | 变更追踪任务清单目录（`active/` 进行中，`completed/` 已归档且目录名为 **`<YYYYMMDD>-<task-name>`**（日期在前），`todo.json` 活跃任务索引）；仅当 `changeTracking.*` 为 `true` 或显式调用 `f2s-req-plan` 时创建 |
 | `配置根/rules/` | 规则文件（Cursor `.mdc`，Claude `.md`） |
@@ -26,7 +33,7 @@
 | `.codex/AGENTS.md` | Codex 统一入口与加载说明 |
 | `flow2spec.config.json` | 项目根配置，控制 `subAgent`、`switchAgentVerification`、`changeTracking`（嵌套对象，含 `feat` / `fix` / `implement` 三个子项） |
 
-> 多端提示与路径表见 [Flow2Spec使用说明 § 一](./Flow2Spec使用说明.md)（详表单点维护）；**权威仍为 Read(`flow2spec.config.json`)**。
+> 多端提示与路径表见 [使用说明 § 一](./使用说明.md)（详表单点维护）；**权威仍为 Read(`flow2spec.config.json`)**。
 
 ---
 
@@ -41,7 +48,7 @@
 
 ## 相关文档
 
-- [Flow2Spec使用说明](./Flow2Spec使用说明.md)
-- [README-命令说明](./README-命令说明.md)
-- [README-体系与原理](./README-体系与原理.md)
-- [Flow2Spec-使用案例-模拟对话](./Flow2Spec-使用案例-模拟对话.md)
+- [使用说明](./使用说明.md)
+- [命令说明](./命令说明.md)
+- [体系与原理](./体系与原理.md)
+- [使用案例-模拟对话](./使用案例-模拟对话.md)