@hupan56/wlkj 3.1.3 → 3.1.5

package/templates/qoder/contracts/README.md

@@ -0,0 +1,184 @@
+# 模块契约中枢（CONTRACTS）
+
+> 本目录是整个工作流的**单一事实源**：定义每个模块「吃什么 / 吐什么 / 怎么算合规」。
+> 模块之间**不依赖上游是否执行**，只依赖**一份符合契约的文件**。
+> 谁都能单独开机，靠标准文件互相对接。
+
+---
+
+## 设计原则：契约网，不是流水线
+
+```
+                 自然语言 / 截图（零输入也能开工）
+                       │
+            ┌──────────┼──────────┐
+            ▼          ▼          ▼
+         [prd]     [design]    [test]      ← 7 个独立黑盒
+            │          │          │          都能单独开机
+            ▼          ▼          ▼
+        REQ-*.md   *-spec.json  cases.json   ← 标准契约文件（唯一耦合点）
+            │    ↗     │     ↖
+            ▼  ╱       ▼       ╲ ▼
+         [task]    [spec]    [code]          ← 吃契约文件，不认上游
+            │          │          │
+            └──────────┼──────────┘
+                       ▼
+                   [commit]
+```
+
+- **箭头 = 可以消费**，不是必须等待。没有强制顺序。
+- **任何模块缺上游 → 手动喂个契约文件，照样开工。**
+- **文件就是接口**：上游是谁、跑没跑、人还是 AI，都不重要。
+
+---
+
+## 降级链路：从完整输入到「一句话」
+
+每个模块的输入都有一条降级链，越往下越能独立作战，代价是产出精度下降：
+
+```
+完整输入（契约文件）          产出最稳，可复现性最高
+   ↓ 降级 1
+部分契约（PRD 或 截图）
+   ↓ 降级 2
+一句话描述（口语需求）
+   ↓ 降级 3 ★ 最终兜底
+自然语言 + 全索引自检索       AI 自己用 context_pack / search_index 找上下文硬干
+```
+
+**降级 3 的做法**（本仓库特有）：
+模块没拿到任何契约文件时，AI 用业务关键词跑一次
+`python .qoder/scripts/orchestration/wlkj.py context <业务词> --platform <web|app>`，
+一次性拿到 7 段上下文（代码 / 页面示例 / 字段 / 历史 PRD / API / 设计 token / Wiki），
+再叠上 `search_index.py --prd <关键词>` 查历史 PRD，**自己凑出最小输入开工**。
+
+> 注：知识图谱（`data/index/`）正在持续更新，context_pack 会自动用最新索引，
+> 不需要等它跑完。索引是只读消费，这边不抢写资源。
+
+---
+
+## 七模块契约速查表
+
+| 模块 | 吃什么（Input） | 吐什么（Output） | 校验 | 详细契约 |
+|------|----------------|------------------|------|----------|
+| **prd** | 一句话需求 / 任意业务描述 | `REQ-{YYYY}-{NNN}-{标题}.md` + 原型 html | eval_prd.py ≥80% | [prd.md](prd.md) |
+| **design** | PRD / Figma 截图 / 一句话 | `{需求}-design-spec.json` + 原型 html | design-review checklist | [design.md](design.md) |
+| **task** | 任意一份 PRD | 任务目录 `task.json` + RICE | 无 | [task.md](task.md) |
+| **spec** | PRD（必需） | `REQ-{ID}-{module}.spec.md` | 无（待建） | [spec.md](spec.md) |
+| **code** | spec（必需）/ PRD（降级） | 源码写入 `data/code/` | 自检清单 | [code.md](code.md) |
+| **test** | PRD / spec / 一句话 | 用例 json / JUnit | 自检清单 | [test.md](test.md) |
+| **commit** | 任意改动文件 | git 提交 | 提交前门禁 | [commit.md](commit.md) |
+
+> 每个模块的 Output 契约 = 下游的 Input 契约。这是唯一的耦合方式。
+
+---
+
+## 用户认知面：只需记 7 个 /wl-* 命令
+
+小而美的核心——**对外只暴露 7 个命令，每个是一道工序站，每个带模式参数路由到背后的 skill。**
+
+| 命令 | 工序站 | 模式参数 | 背后的 skill | 自动批准？ |
+|------|--------|---------|-------------|-----------|
+| `/wl-init` | 身份 | （无） | wl-init | ✅ |
+| `/wl-prd-full` | 需求（完整档） | 支持`参考:<报告>` | prd-generator | ✅ |
+| `/wl-prd-quick` | 需求（小改动） | （无） | prd-generator | ✅ |
+| `/wl-prd-review` | 需求（评审） | （无） | prd-review | ✅ |
+| `/wl-design` | 设计 | `import`/`generate`/`review` 或默认(import) | design-import/prototype-generator/design-review | ✅ |
+| `/wl-task` | 任务 | `create`/`list`/`start`/`finish` | wl-task | ✅ |
+| `/wl-code` | 编码 | （无，按 spec 实现） | spec-coder | ⚠️ 需确认 |
+| `/wl-test` | 测试 | `quick`/`browser`/`unit` 或默认(quick) | wl-test / test-generator | ⚠️ 需确认 |
+| `/wl-commit` | 提交 | （无） | wl-commit | ⚠️ 需确认 |
+
+> **模式参数 = 一个命令当多个用。** 不记住参数也没关系，自然语言一样路由
+> （"快速加个字段" → prd 快速；"录入设计稿" → design import；"补单测" → test unit）。
+
+### 为什么是 7 个不是 11 个
+
+现有 11 个 `/wl-*` 命令里，有 4 个是「长大了再开」的可选层，不进主干认知：
+
+| 命令 | 为什么可选 | 何时启用 |
+|------|-----------|---------|
+| `/wl-search` | 全员共用基础设施（不是工序站，是工具） | 随时用，但不用专门记 |
+| `/wl-spec` | 小团队 PMD 直接给开发讲也行 | 需求复杂度上来再开 |
+| `/wl-status` | 需要管理汇报时 | 团队有 PMO/汇报需求 |
+| `/wl-report` | 写日报周报时 | 需要向上汇报 |
+| `/wl-insight` | 需要埋点数据 | 接了埋点/反馈源 |
+
+**核心 7 个是执行链路必经**，可选 5 个是按需开启。新人只记 7 个就能把活干完。
+
+---
+
+## 核心 skill vs 可选 skill
+
+skill 层保持完整（19+ 个），但分主次。**重复对已标注主入口**（skill 顶部 `📌 主入口`）：
+
+### 核心层（7 命令的实现层，必有）
+
+| 命令 | 主 skill | 实现 skill（被路由） |
+|------|---------|---------------------|
+| /wl-prd-full | wl-prd-full | prd-generator |
+| /wl-prd-quick | wl-prd-quick | prd-generator |
+| /wl-prd-review | wl-prd-review | prd-review |
+| /wl-design | wl-design | design-import, prototype-generator, design-review |
+| /wl-task | wl-task | — |
+| /wl-code | wl-code | spec-coder |
+| /wl-test | wl-test | test-generator（unit 模式） |
+| /wl-commit | wl-commit | — |
+| /wl-init | wl-init | — |
+
+### 可选层（长大了再开）
+
+| skill | 用途 | 启用条件 |
+|-------|------|---------|
+| prd-review | PRD 质量评审 | PRD 量大 / 团队 >5 人 |
+| wl-insight | 反馈+埋点分析 | 接了数据源 |
+| wl-status | 项目健康度 | 有 PMO |
+| wl-report | 日报周报 | 需要汇报 |
+| spec-generator | 技术规格 | 需求复杂 |
+| wl-search | 代码搜索 | 全员工具（随时可用，非工序站） |
+
+---
+
+## 契约强度：软契约（warn 不 block）
+
+本工作流采用**软契约**：
+
+- 契约文件**应该**带一个 `@contract` 头（见 [contract-header.md](contract-header.md)）。
+- 缺关键字段时：**只警告（`⚠️ 缺少 platform 字段`），不拦截执行**。
+- 原因：软契约保证「独立作战时不被格式卡死」，下游能降级跑通。
+- 例外：**prd 模块是唯一硬门禁**（`eval_prd.py` < 80% 不让发布），因为它是最上游的契约源。
+
+> 如果你发现某个模块产出老是不合规，可以把它的契约从「软」升到「硬」——
+> 给它加个校验脚本即可（参考 eval_prd.py）。
+
+---
+
+## 给新人 / 新模块的两条铁律
+
+1. **写新模块前，先在这里登记它的 Input/Output 契约。** 没登记 = 不算工作流成员。
+2. **改某个模块的输出格式，必须同步改下游的 Input 契约。** 契约是双方签的，不能单方面改。
+
+---
+
+## 与现有文档的关系
+
+| 文档 | 角色 | 关系 |
+|------|------|------|
+| **本目录 CONTRACTS** | 模块间接口规范 | 「模块吃什么吐什么」的唯一事实源 |
+| `AGENTS.md` | 项目入口 + 命令清单 | 给人看的导航；细节回引这里 |
+| `.qoder/rules/wl-pipeline.md` | 工作流规则（always_on） | 执行约束；输出格式回引这里 |
+| `.qoder/skills/*/SKILL.md` | 单模块实现细节 | 每个 skill 顶部应声明「本模块契约见 `.qoder/contracts/{模块}.md`」 |
+
+**优先级**：契约冲突时，以本目录为准；本目录没覆盖的，以 skill 实际行为为准，并回填到这里。
+
+---
+
+## 待统一项（KNOWN GAPS）
+
+> 这些是现状里发现的矛盾，记在这里追踪，不掩盖：
+
+- [ ] **spec 输出文件名两处不一致**：`spec-generator` 用 `REQ-{ID}-{module}.spec.md`，
+      `wl-spec` 用 `spec-{REQ-ID}-{desc}.md`。→ 契约统一为 `REQ-{ID}-{module}.spec.md`。
+- [ ] **design spec.json 尚无实际产出**：`data/style/` 当前只有 2 个 PDF，
+      design-import 声明的 `{需求}-design-spec.json` 是预期而非现状。
+- [ ] **task / spec / code / test / commit 无独立校验脚本**：当前靠 skill 内自检清单。

package/templates/qoder/contracts/code.md

@@ -0,0 +1,81 @@
+# 模块契约：code（编码）
+
+> 编码模块。按 spec 写源码，直接落到 `data/code/`。
+> **DANGEROUS**：执行前必须用户确认。
+
+---
+
+## Input（吃什么）
+
+| 优先级 | 输入 | 怎么用 |
+|--------|------|--------|
+| **完整** | 一份 spec（`workspace/specs/REQ-{ID}-*.spec.md`） | 照接口/数据结构实现 |
+| 完整 2 | 任务目录的 spec（`workspace/tasks/{task-id}/spec.md`） | 同上 |
+| 降级 1 | 只有 PRD（无 spec） | 降级：从 PRD 推断接口，标 `source: prd-degraded` |
+| 参考 | 现有代码风格 | `search_index.py <模块关键词>` 找 top 2-3 相似文件 |
+| 参考 | 架构 / 数据字典 | `.qoder/context/architecture.md`、`data-dictionary.md`（不存在则跳过） |
+
+**目标代码库**：`data/code/`
+- fywl-ics（后端 Java）
+- fywl-ui（前端 Vue）
+- Carmg-H5（移动端）
+
+---
+
+## Output（吐什么）
+
+**直接写入源码**，无中间产物文件。
+
+```
+data/code/{项目}/{模块}/...    ← Java / Vue 源码
+```
+
+### 实现结构约定（后端）
+
+```
+Entity → Mapper → Service → Controller
+接口：RESTful + JSR-303 校验 + Result<T>
+金额：一律 BigDecimal
+```
+
+### 契约头（写进源码注释）
+
+实现的关键文件顶部应标注它对接的 spec：
+
+```java
+/**
+ * @contract code
+ * @source-spec REQ-2025-0042-policy.spec.md
+ * @source-req REQ-2025-0042
+ */
+```
+
+---
+
+## 校验
+
+- ❌ **无独立校验脚本**。靠自检清单：
+  - [ ] Spec 所有接口已实现
+  - [ ] 数据库字段与 Spec 一致
+  - [ ] 命名跟周围代码一致（不发明新风格）
+  - [ ] 无 TODO/FIXME 残留
+  - [ ] 金额用 BigDecimal
+- 软契约：缺 `@source-spec` 只警告。
+
+---
+
+## 与上下游的接口
+
+| 方向 | 接口 |
+|------|------|
+| 上游 spec | 读接口/数据结构 |
+| 上游 prd（降级） | 从验收标准推断 |
+| 下游 test | 改动的接口 → test 模块生成用例 |
+| 下游 commit | 改动文件 → commit 模块提交 |
+
+---
+
+## 现状提醒
+
+- ✅ 实现约定清晰（Java 全栈 + RESTful）。
+- ⚠️ 降级吃 PRD 时，产出质量取决于 PRD 的字段规格是否详细；建议优先补 spec。

package/templates/qoder/contracts/commit.md

@@ -0,0 +1,86 @@
+# 模块契约：commit（提交）
+
+> 提交模块。把改动推到远端。
+> **DANGEROUS**：推远端代码前必须用户确认提交信息。
+
+---
+
+## Input（吃什么）
+
+| 来源 | 内容 |
+|------|------|
+| `.qoder/.developer` | 当前开发者身份 |
+| `.qoder/.current-task` | 关联的任务 ID（若有） |
+| `git status` / `git diff --stat` | 当前改动 |
+| 用户确认 | 提交信息文案（必须用户点头） |
+
+**两类改动走不同路**：
+
+| 改动类型 | 走哪个 |
+|----------|--------|
+| **源码**（data/code/ 下的 Java/Vue） | 本模块 `/wl-commit` |
+| **产出**（PRD / 任务 / 索引 / 原型 / spec） | `team_sync.py push`（不是 commit） |
+
+---
+
+## Output（吐什么）
+
+```
+git 提交（远端可见）
+```
+
+### 提交信息格式
+
+```
+[ai-generated] <type>: <简述>
+
+<body 可选>
+```
+
+`type` ∈ feat / fix / refactor / docs / test / chore
+
+### 流程
+
+```
+git add <精确文件>     ← 不用 git add .，精确到文件
+git commit
+git pull --rebase
+git push
+```
+
+记录到 `data/learning/`（供 /wl-report、/wl-status 统计）。
+
+---
+
+## 校验（提交前质量门禁）
+
+**无脚本，逐项 AI/人工自检**：
+
+- [ ] 无 TODO/FIXME 残留
+- [ ] 金额用 BigDecimal
+- [ ] 命名风格一致
+- [ ] Spec 接口/字段已覆盖
+- [ ] 测试通过
+- [ ] 提交信息用户已确认
+
+**失败处理**：
+- 门禁不过 → 默认修复后提交（不硬拦，但要提示）
+- push 被拒 → `git pull --rebase` 后重试
+- 冲突 → 列出文件问用户（不让用户碰 git 命令，但要让用户拍板冲突解法）
+
+---
+
+## 与上下游的接口
+
+| 方向 | 接口 |
+|------|------|
+| 上游 code | 改动的源码文件 |
+| 上游 所有模块 | 产出文件（走 team_sync，不走本模块） |
+| 下游 report | commit 记录 → 日报周报 |
+
+---
+
+## 现状提醒
+
+- ✅ 提交流程清晰，身份 + 任务关联齐全。
+- ⚠️ 「门禁不过默认修复后提交」是软策略——质量责任在人，不在脚本。

package/templates/qoder/contracts/contract-header.md

@@ -0,0 +1,76 @@
+# 契约头规范（@contract）
+
+> 每个契约文件**应该**在最顶部带一个 `@contract` 注释块，用于自描述。
+> **软契约**：缺了只警告，不拦截。
+
+---
+
+## 格式
+
+### Markdown 文件（PRD / spec / 任务说明等）
+
+文件**第一行**放 HTML 注释（不渲染、不污染正文）：
+
+```markdown
+<!-- @contract prd v1
+platform: web
+req-id: REQ-2025-0042
+title: 保单批改功能
+acceptance: [批改后实时生效, 批改需审批, 批改记录可查]
+source: context_pack:保单批改,web
+-->
+
+# 保单批改功能 PRD
+...正文...
+```
+
+### JSON 文件（design-spec / test-cases 等）
+
+顶层加一个 `_contract` 字段：
+
+```json
+{
+  "_contract": {
+    "type": "design-spec",
+    "version": 1,
+    "platform": "app",
+    "requirement": "保单批改",
+    "source": "figma:截图1+截图2"
+  },
+  "design_tokens": { ... }
+}
+```
+
+---
+
+## 字段说明
+
+| 字段 | 类型 | 作用 | 必填？ |
+|------|------|------|--------|
+| `type` / 第一行模块名 | string | 声明这是哪类契约：`prd`/`design`/`spec`/`task`/`test` | ✅ |
+| `version` / `v1` | int | 契约版本，将来格式演进用 | ✅ |
+| `platform` | `web`/`app`/`both` | 决定下游用哪套模板/风格真源 | ✅（prd/design 必填） |
+| `req-id` | string | 需求编号，贯穿全链路的唯一 key | ✅（prd/spec/code 必填） |
+| `title` | string | 人类可读标题 | 推荐 |
+| `acceptance` | string[] | 验收标准列表 | ✅（prd 必填） |
+| `source` | string | 这份文件怎么来的：`context_pack:词,平台` / `figma:截图` / `manual` | 推荐 |
+
+---
+
+## 软契约的判读规则
+
+下游模块读到一份文件时：
+
+1. **有 `@contract` 头** → 直接读取 `platform` / `req-id` / `acceptance`，不依赖外部记忆。
+2. **没有 `@contract` 头** → 不报错，**降级**：从头文件名 / 正文推断（比如文件名 `REQ-2025-0042-xxx.md` 推出 req-id），并打印一条 `⚠️ <文件> 缺少 @contract 头，已从文件名推断`。
+3. **推断也推不出来** → 走「语言描述兜底」：把文件内容当自然语言，跑 context_pack 自检索补全。
+
+**核心：永远不因为格式问题让模块停摆。** 停摆比降级产出更糟。
+
+---
+
+## 为什么用 HTML 注释而不是 frontmatter？
+
+- frontmatter（`---`）会跟 PRD 模板正文的 `---`（分割线）打架。
+- HTML 注释 `<!-- -->` 在 Markdown 里不渲染、对人透明、对机器可解析。
+- JSON 文件用 `_contract` 字段（下划线前缀表「元数据」）。

package/templates/qoder/contracts/design.md

@@ -0,0 +1,106 @@
+# 模块契约：design（设计）
+
+> 设计模块。确立**视觉单一真源**，让 AI 原型不再跟 Figma 打架。
+> 由 design-import + prototype-generator + design-review 三个 skill 承担。
+
+---
+
+## Input（吃什么）
+
+| 优先级 | 输入 | 怎么用 |
+|--------|------|--------|
+| **完整** | 设计师 spec.json（已录入的） | 优先级最高：`data/style/{需求}-design-spec.json` |
+| 完整 2 | PRD + 设计师 Figma/Axure 截图 | design-import 把截图转成 spec.json |
+| 降级 1 | 只有 PRD，无设计稿 | 用代码真源 / 系统风格做原型 |
+| 降级 2 | 只有截图 + 一句话 | design-import 直接从截图提取 |
+| 降级 2 ★ | 一句话描述 | fill_prototype.py + 风格真源硬干 |
+
+**风格真源优先级**（高 → 低）：
+
+```
+设计师 spec.json (data/style/*-design-spec.json)
+  > data/code/ 实际 Vue 源码
+  > data/index/ref-vben-style.json (Web) / Vant 变量 (APP)
+  > data/index/ref-chart-style.json (看板/大屏)
+  > data/style/*.pdf (规范文档，最后兜底)
+```
+
+**平台是硬约束**。
+
+---
+
+## Output（吐什么）
+
+### 主产物 1：设计规范（design-import 产出）
+
+```
+路径：data/style/{需求名}-design-spec.json
+格式：对齐 ref-vben-style.json 的结构
+```
+
+```json
+{
+  "_contract": {
+    "type": "design-spec", "version": 1,
+    "platform": "web|app",
+    "requirement": "{需求名}",
+    "source": "figma:截图1+截图2"
+  },
+  "source": "...",
+  "imported_at": "2026-06-16T...",
+  "platform": "web",
+  "requirement": "...",
+  "design_tokens": { "color": {}, "spacing": {}, "typography": {} },
+  "layout": {},
+  "components": {},
+  "notes": {}
+}
+```
+
+**契约头 `_contract`** 让下游原型/代码一眼识别这是设计师真源。
+
+### 主产物 2：原型（prototype-generator 产出）
+
+```
+单端：workspace/members/{developer}/drafts/prototype-{feature}.html
+两端：...-web.html + ...-app.html
+```
+
+起点必须是模板 `.qoder/templates/prototype-{web|app}.html`，
+预填充走 `python .qoder/scripts/fill_prototype.py <关键词> --platform <web|app> [--type table-page|form-page]`。
+
+**铁律**：data/style/ 里有同需求的 spec.json → 原型必须锚定它，不许另起炉灶。
+
+---
+
+## 校验
+
+design-review skill 用 checklist（**无独立脚本**）：
+
+- [ ] 组件规格完整
+- [ ] 交互流程闭环
+- [ ] 图标来自真源（`data/index/ref-icon.json`，**禁 emoji**）
+- [ ] 颜色来自真源
+- [ ] 匹配设计师 spec（若存在）
+- [ ] 匹配 PRD 验收点
+
+> 原型的颜色真源校验实际由 `eval_prd.py` 的 A2 分（30 分）承担——
+> 也就是说设计质量目前挂在 prd 门禁上。无独立 design 校验脚本（待建）。
+
+---
+
+## 与下游的接口
+
+| 下游模块 | 消费 design 的什么 |
+|----------|-------------------|
+| code | 原型的组件结构 / 交互 |
+| prototype 重生成 | design-spec.json 的 token / layout / components |
+
+---
+
+## 现状提醒（KNOWN GAP）
+
+- ⚠️ **`data/style/` 当前只有 2 个 PDF，没有任何 spec.json**。
+  design-import 声明会产出 spec.json，但目前是「预期」而非「已落地」。
+  首次有设计师录入前，原型只能走「代码真源」级降级。
+- ✅ 图标禁 emoji 这条已有 eval_prd A2 兜底。

package/templates/qoder/contracts/fallback.md

@@ -0,0 +1,126 @@
+# 语言描述兜底（最终降级策略）
+
+> 这是降级链路的**终点**：当模块连一份契约文件都没有、连截图都没有时，
+> 用户只用一句话描述，AI 靠**全索引 + PRD 历史**自己检索上下文，硬把活干出来。
+>
+> 哲学：**永远不因为缺输入让模块停摆。停摆比降级产出更糟。**
+
+---
+
+## 降级链路总览
+
+```
+完整输入（契约文件 + 截图）        产出最稳 ★★★★★
+   ↓ 降级 1
+部分契约（PRD 或 单截图）           产出较稳 ★★★★
+   ↓ 降级 2
+一句话描述（口语需求）              产出可用 ★★★
+   ↓ 降级 3 ★ 最终兜底
+自然语言 + 全索引自检索             产出需人工复核 ★★
+```
+
+**降级 3 的本质**：AI 把用户的一句话当成「检索 query」，用现有索引把上下文凑齐，
+再带着这些上下文进模块开干。用户感觉只是说了句话，AI 背后自己找齐了弹药。
+
+---
+
+## 兜底执行流程（任何模块通用）
+
+```
+用户一句话（"保单批改那块加个审批"）
+        │
+        ▼
+┌───────────────────────────┐
+│ Step 1: 提取业务关键词      │   common/terms.py 的 expand_chinese_query
+│   "保单批改" → 精确/分词    │   三级分词：精确 → 贪心 → 兜底
+└───────────────────────────┘
+        │
+        ▼
+┌───────────────────────────┐
+│ Step 2: 一次取全上下文 ★    │   python .qoder/scripts/orchestration/wlkj.py context
+│   context_pack.py <词>      │     <业务词> --platform <web|app>
+│     --platform <web|app>    │   返回 7 段（代码/页面/字段/PRD/API/token/Wiki）
+└───────────────────────────┘
+        │
+        ▼
+┌───────────────────────────┐
+│ Step 3: 补查历史 PRD        │   python .qoder/scripts/orchestration/wlkj.py search
+│   search_index.py --prd <词>│   看有没有同类需求做过，复用验收标准
+└───────────────────────────┘
+        │
+        ▼
+┌───────────────────────────┐
+│ Step 4: 补查字段/API        │   按 Step2 结果决定要不要 drill-down
+│   search_index.py --field  │   --field / --api 精确取
+└───────────────────────────┘
+        │
+        ▼
+┌───────────────────────────┐
+│ Step 5: 进模块开干          │   带着凑齐的上下文，正常走模块逻辑
+│   产出标 source: fallback   │   产物的契约头标 source: fallback:index
+└───────────────────────────┘
+```
+
+---
+
+## 关键设计点
+
+### 1. context_pack 是兜底的核心引擎
+
+一条命令拿 7 段，**不需要等图谱更新完**：
+- context_pack 只读 `data/index/`（只读消费，不抢写资源）
+- 图谱在另一个窗口更新，这边用最新 mtime 的索引，互不干扰
+- 有 24h 缓存（`.qoder/.runtime/ctx-cache-*.md`），重复问同一个词秒回
+
+### 2. 平台缺失时怎么办
+
+兜底场景下用户往往没说平台。**规则**：
+- context_pack 的 `--platform` 如果缺，默认跑 `both`（两端都查）
+- 但**进 prd / design 模块前必须补问平台**（这两块的硬约束不变）
+- 其它模块（code/test）能从代码库自动判断平台，不用问
+
+### 3. 产出必须标记 fallback
+
+走兜底产出的契约文件，`source` 字段标 `fallback:index`：
+
+```markdown
+<!-- @contract prd v1
+platform: web
+source: fallback:index
+acceptance: [...]   ← 这些验收点是 AI 从历史 PRD 推断的，需人工复核
+-->
+```
+
+**目的**：下游看到 `source: fallback` 就知道这是「AI 凑出来的」，**质量责任在人**，
+该人工复核就复核，别盲信。
+
+### 4. 兜底不是万能的
+
+兜底能补**上下文**（代码在哪、字段叫啥、历史怎么做），补不了**决策**：
+- ❌ 兜底不能决定「这个功能该不该做」
+- ❌ 兜底不能编造「用户没说但需要的验收点」（只能从历史 PRD 推断相似项）
+- ✅ 兜底能补「相关代码、字段命名、同类需求的写法」
+
+---
+
+## 各模块的兜底差异
+
+| 模块 | 兜底能凑出什么 | 凑不出什么（需人工） |
+|------|--------------|---------------------|
+| prd | 相关代码/字段/历史PRD/页面示例 | 业务决策、真实验收点 |
+| design | 系统风格token/同类页面/图标 | 设计师的视觉决策 |
+| task | 同类历史任务/估时参考 | 优先级决策 |
+| spec | 接口惯例/数据结构惯例 | PRD 没定义的功能 |
+| code | 周围代码风格/相似实现 | —— （兜底效果最好） |
+| test | 同类页面的验收点 | PRD 没写的边界 |
+
+**code 模块兜底效果最好**——因为代码风格、相似实现都在索引里，能直接照着写。
+**prd 模块兜底效果最差**——因为需求决策终究是人定的，索引只能给参考。
+
+---
+
+## 一句话
+
+> **用户说一句话，AI 用 context_pack 把全索引跑一遍、用 search_index 把历史 PRD 捞一遍，
+> 凑齐上下文后照常进模块开干。产出标 `source: fallback`，提示需人工复核。
+> 不卡、不报错、不等图谱。**