# 0.7.0 计划：范式卡包（Paradigm Pack）

> 状态：**已实现（0.7.0）** · 目标版本：`0.7.0` · 前置：`0.6.8`
> 目标：让“用户满意 + 四维审计通过”的版本成为可检索、可复用、可继续学习的**范式卡包**，而不是只冻结一份 README 或 HTML。

## 1. 结论

**是，`cards/*.meta.json` 必须成为卡包的一等公民；但只靠它不够。**

- `cards/*.meta.json` 是**可移植的规则源**：DSH 能检索、过滤、引用、去重、反馈；
- `pack.json` 是**组合与证据**：记录“这次为什么把这些卡放在一起”、审计/确认、适用模块、预览；
- `README.md` 是**给 DevEco/用户读的表达层**；
- `preview/index.html` 是**视觉参考**，不是生产代码。

0.6.8 已经落地了核心闭环：inbox 兼容 `cards/*.meta.json`、四维审计 + 用户确认门禁、pack 证据、范式卡、recommend 包优先。0.7.0 只保留扩展项：

## 2. 0.7.0 落地结果

| 项目 | 0.6.8 | 0.7.0 已实现 |
| --- | --- | --- |
| 卡片格式 | inbox schema，可投回空库 | `schemaVersion: 2` + `pack migrate` |
| 组合信息 | pack.json 有 roles/why/cost/evidence | 独立 `index.json` registry + `supersedes`/`supersededBy` |
| 审计门禁 | audit + confirmation + confirmed | 保持；迁移无证据的包只能是 draft |
| 推荐粒度 | 范式卡（packRef/componentIds） | registry 过滤 superseded、包级 feedback 进排序 |
| 可移植 | cards meta 可 re-ingest | import 复制 preview 并重写 card preview 路径 |
| 学习信号 | 范式卡 weight 1.2 | `pack-feedback` 调包 score + 学习卡权重（上限 1.35） |
| 质量回归 | 无 | `benchmark` 输出 top-3 包命中率 + 漏检行 |

## 3. 卡包格式（v2）

```text
.shared/design-packs/sculptural-member-v1/
├─ pack.json                 # 组合、证据、版本
├─ README.md                 # 人读：需求、选择、为什么、代价、验收
├─ cards/
│  ├─ 01-home.meta.json      # inbox schema，可重新 ingest
│  ├─ 02-card.meta.json
│  ├─ 03-pr-material.meta.json
│  └─ 04-ap-mirror.meta.json
└─ preview/
   └─ index.html             # 可选，仅视觉参考
```

`cards/*.meta.json` 必须是 **inbox 可读取的格式**：

```jsonc
{
  "kind": "pattern",
  "title": "银白极简 · 会员中心首页",
  "summary": "...",
  "tokens": { ... },
  "moduleTags": ["member-center"],
  "tone": ["calm"],
  "density": "low",
  "stylePriority": ["银白极简"],
  "checklist": ["..."],
  "antiPatterns": ["AP-0001"],
  "dimensions": { "appType": "会员", "platform": "harmonyos", "style": "银白极简" },
  "source": { "kind": "project", "ref": "design-pack:sculptural-member-v1", "license": "internal" }
}
```

不写入 `id / status / weight / createdAt / ingestKey`；这些由导入项目重新分配。

`pack.json` v2 示例：

```jsonc
{
  "schemaVersion": 2,
  "name": "sculptural-member-v1",
  "status": "paradigm",
  "createdAt": "...",
  "engineVersion": "0.7.0",
  "specVersion": 3,
  "requirement": "会员中心首屏...",
  "module": "member-center",
  "appType": "会员",
  "platform": "harmonyos",
  "tone": "calm",
  "density": "low",
  "brandColors": ["#E8DED2", "#2A2320"],
  "cards": [
    { "file": "cards/01-home.meta.json", "sourceId": "DSG-0001", "role": "anchor" },
    { "file": "cards/02-card.meta.json", "sourceId": "DSG-0002", "role": "support" },
    { "file": "cards/03-pr-material.meta.json", "sourceId": "PR-0001", "role": "principle" },
    { "file": "cards/04-ap-mirror.meta.json", "sourceId": "AP-0001", "role": "anti-pattern" }
  ],
  "why": ["模块匹配...", "品牌色温度匹配..."],
  "cost": ["色值需替换为品牌色..."],
  "preview": "preview/index.html",
  "evidence": {
    "auditReport": "artifacts/audit-4.json",
    "auditSha256": "...",
    "auditPass": true,
    "confirmation": "artifacts/confirmation-4.json",
    "confirmationSha256": "...",
    "userDecision": "accept"
  },
  "supersedes": "sculptural-member-v0"
}
```

## 4. 范式门禁

`capture-pack` 默认 `stage: "paradigm"`，必须同时满足：

1. 任务包存在且 `specVersion` 匹配；
2. `audit-<n>.json` 的 `gate.pass === true`，且四维判据齐全（沿用 0.6.x 审计闸门）；
3. `confirmation-<n>.json` 属于当前 `specVersion`，用户决定为 `accept` 或 `new_round`；
4. `confirmed: true`（工具参数，防止 Agent 自说自话）；
5. 锚点卡/组合仍 active；preview 在 `.shared` 内合法。

不满足时：

- 拒绝写 `status: paradigm`；
- 若需要早期预览，可 `stage: "draft"`（只写 README/preview，不进 recommend、不进学习索引），明确标注“未审计、未确认”。

## 5. recommend 的包级推荐

0.7.0 的 `recommend` 先查范式包，再查单卡：

```text
候选池 = 范式包（module/appType/platform/tone/density 匹配）
       + 单卡（0.6.8 逻辑）
```

包级评分：

- 模块 +0.40、App 类型 +0.20、平台 +0.12、气质 +0.18、密度 +0.12；
- 证据完整（audit pass + confirmation）+0.15；
- 用户反馈 `useful` +0.10 / `off` -0.20；
- 新近度轻微加权（不压倒匹配度）；
- 同一 `stylePriority/tone` 去重，保证 3 套多样性。

输出：

```jsonc
{
  "id": "pack:sculptural-member-v1",
  "title": "Sculptural Minimalism · 会员中心",
  "cards": ["DSG-0001", "DSG-0002", "PR-0001", "AP-0001"],
  "preview": "design-packs/sculptural-member-v1/preview/index.html",
  "evidence": { "auditPass": true, "confirmed": true },
  "why": ["..."],
  "cost": ["..."]
}
```

不足 3 套时，用单卡候选补足，但明确标「单卡参考，非范式组合」。

## 6. 学习规则（防止越学越窄）

- **只学“审计通过 + 用户确认”的范式包**；draft/中间稿不入库；
- 包级 feedback：`useful` 提升该包排序，`off` 降权；不直接大幅改单卡权重；
- 组件卡可小幅加权（每张 ≤ +0.05，总权重上限 1.3），避免一张卡因一次组合被永久神化；
- 同模块出现多个范式包时，优先展示“最近被确认”和“反馈更好”的，但保留旧包作为备选；
- 每次 recommend 输出必须带 `why/cost/evidence`，用户仍可要求“不要用旧范式，给我新方向”；
- 定期跑基准：`benchmarks/recommendation-*.json`，检查 top-3 命中与人工偏好，避免只靠记忆。

## 7. 审计与证据契约

范式包不是“免死金牌”：

- 包里的 audit/confirmation 只是**来源证据**，新项目仍必须重新审计四维；
- `designRefs` 可以引用包内卡片；包级 `packRef` 作为额外对照，不替代判据；
- 审计报告可以标「参考自范式包 X」，但结论仍以本轮证据为准；
- 预览 HTML 永远不是验收证据。

## 8. 迁移与兼容

- 0.6.8 的 v1 包仍可读，但 `status` 视为 `draft`，不进 recommend 学习池；
- 新增 `pack migrate <name>`：把 v1 的内部卡转换为 inbox meta，补 `schemaVersion: 2`；缺审计/确认的包不能升级为 paradigm；
- `pack import` 保留 `moduleTags/tone/density/preview`，重写 preview 为本项目相对路径；不复制内部 id/status；
- `pack export` 输出 inbox meta + pack.json，不再依赖原始 library 的内部结构。

## 9. 验收标准（可证伪）

| ID | 判据 | 验证 |
| --- | --- | --- |
| PP-1 | 范式卡的 `cards/*.meta.json` 可直接投回空库 inbox 并成功 ingest，kind/tokens/metadata 不丢 | 单测：空 workspace ingest + 断言 |
| PP-2 | 无 audit pass 或 confirmation 时 capture-pack 拒绝 `status: paradigm`；draft 不写学习索引 | 单测：缺审计/缺确认/缺 confirmed |
| PP-3 | `pack.json` 记录 audit/confirmation 路径 + sha256、角色、module/tone/density、preview | 单测：读取 pack.json |
| PP-4 | recommend 对匹配模块优先返回范式包，带 evidence/why/cost；不足再补单卡 | 单测：构造 2 包 + 2 卡 |
| PP-5 | 包级 feedback useful/off 改变下一次排序；组件卡权重变化有上限 | 单测：两次 recommend 比较 |
| PP-6 | 0.6.8 v1 包迁移后字段完整，未审计包仍是 draft | 单测：migrate |
| PP-7 | `pack import` 保留元数据与 preview，不复制 id/status | 单测：导出→导入新 workspace |
| PP-8 | 预览 HTML 不进入验收证据链 | 代码检查 + 审计报告断言 |

## 10. 不做什么

- 不自动学习每次中间调整；
- 不把 preview HTML 当生产代码或验收证据；
- 不让范式包绕过四维审计；
- 不引入向量库；包级推荐仍是确定性检索 + 可解释加权；
- 不把“用户满意”简化为 Agent 的 `confirmed: true`——必须有 `dwguard_confirm` 记录。

## 11. 实施顺序

1. Schema v2 + inbox meta 导出（PP-1/3）；
2. 范式门禁（PP-2）；
3. recommend 包级候选（PP-4）；
4. 包级 feedback + 权重上限（PP-5）；
5. 迁移与 import/export（PP-6/7）；
6. 文档、README、CHANGELOG、基准；
7. 用真实板块（会员中心）跑完整闭环，再决定是否发布。