# 0.6.4 计划：AP 硬闸门 + 语义重排 + 以图搜图 + 跨项目模板

> 状态：**已实现（0.6.4）** · 目标版本：`0.6.4` · 前置：`0.6.3`（结构化卡片 / 品牌卡 / 预算 / 返工桥）
> 范围：AP-* 反模式引用接入验收闸门、可选 hybrid 语义重排、PNG pHash + 颜色直方图以图搜图、
> 跨项目审美模板（全局目录 export/import）。

## 1. AP 反模式引用 → 硬闸门

- 判据/检查新增 `antiPatternRefs: ["AP-0001"]`（仅审美判据，格式 `AP-<4 位数字>`）；
- `dwguard_spec` 写入时校验 AP 卡存在且 `active`；不存在/被 block 直接拒绝；
- `dwguard_audit` 闸门同样拒绝缺失/blocked 的 AP 引用；
- 验收报告与审计报告新增「反模式对照」列；`audit-<n>.json` 写入
  `design.antiPatterns[{ criterionId, antiPatternRef, status, title }]`；
- `library ingest` 对「pattern 卡引用了未 ingest 的 AP」给 warning（不阻断建库顺序）。

## 2. Hybrid 语义重排

- 配置（全部可选，默认关闭网络）：
  - `designRanker: hybrid`
  - `designEmbeddingEndpoint`（OpenAI-compatible `/embeddings`；空 = 回退 lexical）
  - `designEmbeddingModel`（默认 `text-embedding-3-small`）
  - `designEmbeddingApiKeyEnv`（默认 `DWG_DESIGN_EMBEDDING_KEY`）
  - `designEmbeddingTimeoutMs`（默认 8000）
  - `designEmbeddingWeight`（0–1，默认 0.35）
- 流程：lexical 取 top-30 候选 → query/chunk 文本 embedding（带 `embeddings.json` 缓存）→
  `final = (1-w)·归一化BM25 + w·(cos+1)/2` → 取 topK；
- 端点缺失/超时/返回格式异常 → 显式 note + 回退 lexical，不阻断检索；
- **`query.mjs` 保持 lexical**（CLI 没有端点/凭据），简报会注明「以 DSH 工具排序为准」；
- 审计可复现性：向量缓存按 `model + sha256(text)` 键，报告/结果携带模型名与权重。

## 3. PNG pHash + 颜色直方图「以图搜图」

- 零依赖 PNG 解码（`src/image.ts`）：非隔行 8-bit，支持 gray / RGB / palette / gray+alpha / RGBA；
  CRC 校验、不支持的类型给明确错误；
- 特征：
  - **pHash**：32×32 灰度 → 2D DCT → 低频 8×8 → 中位数 → 64-bit hex；
  - **颜色直方图**：4×4×4 RGB 分箱（64 维，归一化）；
  - 相似度 = `0.6 × (1 - 汉明距离/64) + 0.4 × 直方图交集`；
- `dwguard_design` 的 `search` 新增 `image` 参数（`.shared/` 内 PNG，路径越界拒绝）；
- 卡片图片按 sha256 缓存特征到 `image-features.json`；查询图不入库、不写库；
- 仅 DSH 侧支持；`query.mjs` 不提供以图搜图（保持零依赖只读 CLI）。

## 4. 跨项目审美模板

- `dwguard_aesthetic` 新增 `template`：`list / get / export / import`；
- 全局目录：`aestheticTemplatesDir`，默认 `~/.dsh/dwguard/aesthetic-templates`；
- 格式：`{ schemaVersion, name, createdAt, entries }`，只导出 `active` 条目；
- `import` 必须 `confirmed: true`：
  - `merge`（默认）：同领域同取值跳过；同领域不同取值 **supersede** 本地 active；id 冲突重新编号；
  - `replace`：用模板整体替换当前档案；
- 导入写 `knowledge/aesthetic-history.jsonl`（applied / superseded），可追溯。

## 验收标准（可证伪）

| ID | 判据 | 验证方式 |
| --- | --- | --- |
| AP-1 | spec 拒绝不存在/格式错误的 `antiPatternRefs` | 单测：`AP-9999` 与非法格式 |
| AP-2 | audit 闸门拒绝缺失/blocked 的 AP 引用 | 单测：改 spec.json + block 卡片 |
| AP-3 | 报告有「反模式对照」列，audit JSON 有 `design.antiPatterns` | 单测：读 acceptance/audit JSON |
| H-1 | 语义重排会改变排序并保留 BM25 分解 | 单测：stub embed + 检查 `semanticScore`/`breakdown` |
| H-2 | embedding 缓存避免重复请求 | 单测：计数 stub |
| H-3 | 真实 HTTP（loopback stub）下 hybrid 生效并写缓存 | 单测：本地 http server |
| H-4 | 端点缺失/不可达时回退 lexical 并给 note | 单测 |
| I-1 | PNG 解码 + pHash/直方图确定性；同图相似度 1、反色/纯灰更低、坏 CRC 报错 | 单测 |
| I-2 | 以图搜图命中正确卡片、写特征缓存、坏图/越界路径被拒 | 单测 |
| T-1 | 模板 export/list/get/import（merge/replace）与 confirmed 闸门 | 单测 |

## 不做什么 / 已知边界

- 不做 dense-only 向量库；hybrid 仍是 BM25 + 可选 rerank，默认离线。
- 图片相似仅 pHash + 颜色，不做语义/CLIP 以图搜图；不支持隔行 / 16-bit / 动画 PNG。
- 模板只覆盖审美档案，不含设计库卡片与基线（跨项目卡片可用 `library` 目录拷贝，后续再产品化）。
- CLI 与 DSH 工具在 hybrid/以图搜图下**不保证同序**；词法检索仍 parity。

## 兼容性

- 所有新字段/配置可选；旧任务包与旧库无需迁移；
- `DESIGN_ENGINE_VERSION` → `0.6.4`；旧 `embeddings.json` / `image-features.json` 缺失会自动重建；
- 默认不联网：hybrid 端点为空时行为与 0.6.3 一致。