@minonl/dia 0.0.0-stage → 0.0.1

package/docs/migrations/yan-agent-next.md

@@ -0,0 +1,168 @@
+# yan-agent@next：迁移到 dia 框架
+
+> 日期 2026-10-29。目标：yan-agent 的“通用能力”沉到 dia，“工作域内容”留在 yan-agent；
+> `yan-task` 作为独立私有包/仓维护。本文只定迁移边界与阶段，不搬代码。
+
+---
+
+## 1. 结论（先给判断）
+
+1. **调度器单独建私有仓 `dia-job`**，不塞进 dia 内核：
+   - 它不是“知识/审计/任务账本”，而是 **OS 调度适配器**（launchd / cron / schtasks）；
+   - 1075 行、4 后端、测试会真实操作 launchd，生命周期与 dia 不同；
+   - yan-agent 与 dabo 都要用；放 dia 内核会让“瘦框架”重新变胖。
+2. **dia 只吸收“调度契约”**：`dia.json` 声明 jobs，`dia job`/`dia schedule` 调外部 `yan-task` 包；
+   dia 不实现 launchd/cron。
+3. **yan-agent@next 只留域内容 + shim**：知识、技能、工作域 CLI（`yan-mr` 等）和安装入口；
+   通用实现一律委托 dia 或独立包。
+4. **先做 phase 1（抽取 yan-task）**，通过双跑与契约测试后再动 yan-kb/yan-worktree。
+
+---
+
+## 2. 现状盘点（2026-10-29）
+
+| 脚本 | 行数 | 性质 | 归属判断 |
+|---|---:|---|---|
+| `scripts/yan-task` | 1075 | OS 调度 + 任务登记 + 自愈 | **独立私有包** |
+| `scripts/yan-worktree` | 1160 | git worktree 生命周期 | 先留域，phase 3 评估进 dia/包 |
+| `scripts/yan-kb` | 130 + 4561 mjs | 知识检索 shim + 域语义 | 通用 `index/query/get/lint` 进 dia；`scene/rule/claims/baseline/alerts/record` 留 yan；见 `docs/migrations/yan-kb.md` |
+| `scripts/yan-env` | 231 | env 白名单注入 | 通用安全能力，phase 3 进 dia |
+| `scripts/yan-version` | 323 | yan 版本/发布流程 | 留 yan 域（工作发布语义） |
+| `scripts/yan-ref` | 30 + 446 mjs | 稳定路径/生效指针 | 通用，phase 3 评估进 dia |
+| `scripts/yan-mr` | 20 + mr-wait | GitLab MR 等待 | 留 yan 域（工作 GitLab） |
+| `scripts/yan-schedule` | 19 + schedule.mjs | 节假日/大促窗口（不是后台任务） | 留 yan 域 |
+| `scripts/yan-data-root`/`sync` | 64 | 数据根/同步 | 进 dia 数据根契约 |
+| `scripts/yan-doctor` | 138 | 组合自检 | yan 域组合；单项检查调 dia |
+| `core/knowledge` / `core/skills` | 2.3M / 12K | 工作域知识与技能 | **留 yan 域**（可打 kit） |
+| `platform/dsh` / `opencode` | 219M | 宿主渲染与运行时 | 留域；通用渲染进 dia persona |
+| `core/perm` / `dws-hub` / `channel` | — | 工作域权限/通道 | 留 yan 域 |
+
+---
+
+## 3. 三层归属（迁移后）
+
+```
+dia（框架）
+  kb / ingest / audit / freeze / run / task ledger / persona / team / pricing
+  + data-root 契约 + job 契约（声明式；不实现 OS 调度）
+      ↑ 被依赖
+dia-job（独立私有 GitHub 仓：`minonl/dia-job`）
+  list/status/install/uninstall/run/stop/logs/doctor/selfcheck/bootstrap/registry/gc
+  macOS launchd / Linux cron / Windows schtasks；无 yan 业务知识
+      ↑ 被 yan-agent / dabo 调用
+yan-agent@next（工作域入口）
+  core/knowledge、core/skills、工作域策略、yan-mr/yan-schedule
+  只保留 shim：yan-kb → dia kb；yan-task → 独立包；yan-* 安装入口
+dabo-agent（个人域入口）
+  个人知识/人格/策略；复用同一 dia + yan-task
+```
+
+**硬规则**：
+- framework 不出现 `local.dia-job`、`yan-`、工作域路径、工作知识；
+- dia-job 不出现 yan 业务任务名（`failed-task-report`/`nm-check` 留在 yan-agent 的 manifest）；
+- yan-agent@next 不复制通用实现，只做参数/策略/内容。
+
+---
+
+## 4. yan-task 抽取设计
+
+### 4.1 先解耦
+
+当前硬编码（需参数化）：
+
+| 现状 | 目标 |
+|---|---|
+| `YAN_DATA_ROOT` / `~/.yan-agent` | `DIA_JOB_ROOT` 或 `~/.local/share/dia-job`；旧根用全局 config 显式指定 |
+| `local.dia-job-<name>` label | `--label-prefix`（默认 `local.task-`）；迁移时映射旧 label |
+| `yan_main_checkout_of` / `yan_path_stability` / `yan_cmd_path_class` | 路径策略回调/参数；默认“当前 checkout” |
+| `yan-ref` 调用 | 可选 resolver；未配置时用绝对路径 |
+| `yan-task` 自有任务（selfcheck/update/...） | 移到 yan-agent manifest，不进包 |
+
+### 4.2 契约（v1，兼容现有 CLI）
+
+```text
+yan-task list|status|doctor|platform
+yan-task install <name> --cmd '<shell>' [--interval N|--calendar HH:MM] [--desc D] [--type periodic|bounded|service]
+yan-task uninstall <name>
+yan-task run|stop|logs <name> [-n N]
+yan-task selfcheck [--dry-run]
+yan-task bootstrap
+yan-task registry
+yan-task gc [--days N] [--dry-run]
+```
+
+退出码保持 0/1/2/3/4/5（现有契约）；`--json` 后补。
+
+### 4.3 迁移阶段
+
+| 阶段 | 动作 | 门禁 |
+|---|---|---|
+| P0 | 冻结 CLI/退码/state 格式；把现有测试作为 golden | 现有 `yan-task-*.test.sh` 全绿；记录 `list/status/doctor` 输出 |
+| P1 | 新私有仓 `dia-job`：拷脚本 + `platform.sh` 子集 + 测试；参数化 root/label/path | 新仓测试全绿；旧仓 shim 委托；双跑输出 diff 为空 |
+| P2 | dia 接 job 契约：`dia.json.jobs` + `dia job list/status` 调外部包 | dia 测试；未装包时明确报错，不静默 |
+| P3 | 迁移已安装 launchd：旧 label → 新 label（保留映射/回滚） | 本机 `selfcheck` 不重建重复任务；`launchctl print` 对账 |
+| P4 | yan-agent@next 去通用实现，只留 shim/manifest | `grep` 无 launchctl/cron；旧命令全部转发 |
+| P5 | 双跑 1 周，默认切 next；旧分支保留回滚 | 任务成功率/漏跑率不升；回滚演练通过 |
+
+---
+
+## 5. yan-agent@next 的代码边界
+
+**保留**：
+- `core/knowledge/**`（工作规则/流程/坑）
+- `core/skills/**`（工作技能）
+- `core/perm`、`core/dws-hub`、`core/channel`（工作域通道/权限）
+- `scripts/yan-mr`、`scripts/yan-schedule`（工作语义）
+- `platform/{dsh,opencode}/**`（宿主渲染内容）
+- `install.sh` / `install-cli`（只装 shim + 域内容）
+
+**迁出**：
+- `scripts/yan-task` → 私有 `yan-task` 仓
+- `scripts/yan-kb` 的通用实现（index/query/get/lint 基础项）→ dia `kb`；`scene/rule/claims/baseline/alerts/record` 留 yan；yan 只留路由 shim
+- `scripts/yan-env` → dia 通用 env 注入（phase 3）
+- `scripts/yan-ref`、`yan-worktree` → 评估后进 dia 或独立包（phase 3）
+- 通用数据根逻辑 → dia 契约
+
+**验收（next 分支）**：
+1. 同一份 `core/knowledge` 下，`yan-kb --scene S1` 输出与旧版逐字节一致；
+2. `yan-task list/status/doctor` 输出与旧版一致（除路径前缀）；
+3. `yan-mr` 仍能等 MR（工作域）；
+4. `install.sh` 后 `PATH` 里的 `yan-*` 全部是 shim，`grep -R launchctl scripts/` 为空；
+5. 回滚：`git switch main` + `install.sh` 恢复旧链接，任务不重复。
+
+---
+
+## 6. 风险
+
+| 风险 | 处理 |
+|---|---|
+| launchd 测试会操作真实用户域 | 保留 `YAN_TASK_NO_LAUNCHD=1` 测试开关；迁移阶段先 dry-run |
+| 旧 label 迁移产生重复任务 | 先 `list` 对账；新 label 前缀可配；提供 `adopt`/回滚 |
+| bash 3.2 / Windows 差异 | 包内保留现有平台探测；CI 加 macOS + Linux；Windows 只做模板 |
+| yan-ref / 路径稳定性耦合 | 抽成可选 resolver；默认绝对路径，不强制依赖 |
+| 两个域重复维护 | yan-task 独立版本；dia 只声明 job，不复制实现 |
+| 历史数据/任务名 | manifest 留在 yan-agent；包只认 name/cmd/schedule |
+
+---
+
+## 7. 下一步（需要人拍板）
+
+1. **是否现在创建私有 GitHub 仓 `yan-task`**（推荐）：
+   - 先放 P0 的契约测试与脚本副本，不接生产；
+   - 保持 private，CI 只跑无 launchd 的单测。
+2. 若同意，phase 1 的验收命令：
+   - 新仓 `bash tests/run.sh`（从旧 `yan-task-*.test.sh` 迁）；
+   - 旧仓 `scripts/yan-task list|status|doctor` 与新仓输出 diff；
+   - `YAN_TASK_NO_LAUNCHD=1` 下 install/uninstall 幂等。
+3. yan-agent@next 分支/仓库命名与默认切换时间，另定。
+
+
+---
+
+## 8. 命名落定（2026-10-30）
+
+- 仓/包/CLI：**`dia-job`**（私有 `minonl/dia-job`）
+- `yan-task` 保留一个 release 的兼容 shim：`exec dia-job "$@"`
+- P1 基线已推送：`8720aed`（`yan-task` 行为兼容 fork；`tests/bootstrap.test.sh` 16 PASS、`tests/ref-cmd.test.sh` 25 PASS）
+- P2.1（完成，`9bfead8`）：`DIA_JOB_ROOT` / `DIA_JOB_LABEL_PREFIX` / `DIA_JOB_OWN_TASKS` / 路径策略全部参数化；`lib/policy.sh` 不再依赖 yan `platform.sh`；`install.sh` 装到全局 `~/.local/share/dia-job`，配置读 `~/.config/dia-job/config`。
+- 2026-10-30：yan-agent `scripts/yan-task` 已换成 shim，只转发全局 `dia-job`；拒绝 worktree 路径。只读验证 `list/status/doctor/selfcheck --dry-run` 通过，未执行写 launchd 的任务。

package/docs/migrations/yan-kb-parity.md

@@ -0,0 +1,159 @@
+# yan-kb 兼容设计 v2（grill 后）
+
+> 2026-10-30。触发：9 条 query golden 上，旧实现规则召回 10/12、top1 5/9；
+> dia top1 5/9、1/9 零命中。现有方案只能证明“调用切换”，不能证明“能力兼容”。
+> 本文件定义兼容边界、质量门禁、单引擎架构与 K2.1–K2.4 计划。
+>
+> **2026-11-03 复核**：`yan-agent` main 已切 dia 引擎（`dia.json` 的 `kb` 命令委派到 `scripts/kb-domain.mjs`，
+> 默认 `YAN_KB_ENGINE=dia`），文中「仅切 next / main 仍旧」是当时状态；`YAN_KB_ENGINE=old` 保留为临时回滚。
+
+---
+
+## 1. 先定义“兼容”
+
+不能把三个层混成一个：
+
+| 层 | 目标 | 判据 |
+|---|---|---|
+| **CLI 契约** | 必须兼容 | 子命令、退出码、`--json` 字段、`--full/--bytes` |
+| **检索质量** | 必须不倒退 | 必召回、recall@3、zero-hit、top1 不降 |
+| **数据/插件契约** | 真正目标 | 索引 schema、query 原语、稳定输出 schema |
+
+**不要求**：命中顺序逐字一致。旧实现的排序依赖域知识（规则/场景卡），逐字一致等于把域搬进 dia。
+**要求**：旧实现能命中的 query，dia 不能变成零命中；answerable golden 上 zero-hit 必须为 0。
+
+---
+
+## 2. grill 发现的真问题
+
+| # | 问题 | 证据 | 结论 |
+|---|---|---|---|
+| G1 | `query` 把整句当 FTS phrase，fallback 按 token 数排序 | `search()` 引号 phrase + `LIKE '%q%' ORDER BY tokens DESC` | 中文长句结构性零命中；top1 上不去 |
+| G2 | 索引缺失被当成“零命中” | `openDb` 新开空库；`search` 不校验 `docs`/`indexed_at` | 假零命中，必须 unknown |
+| G3 | 非原子建索引 | `DROP` 后逐条 insert，无事务/无 rename | 并发读可见空/半截 |
+| G4 | 9 条样本不足 | top1 ±1 就翻盘；旧 zero-hit 在全量 query 中 23.5% | 至少 40 条，最好 100 条 |
+| G5 | 双跑只看 exit code | `yan-kb-engine.test.sh` 只验调用 | 必须比较路径集合/必召回，不得静默 pass |
+| G6 | 索引正文落在 `~/.cache` | 全量正文、明文、路径不可配 | 迁到可配数据根；public 前审核 |
+
+---
+
+## 3. 目标架构
+
+```text
+yan-kb (domain adapter, 留 yan-agent)
+  ├─ scene/rule/auto/claims/baseline/alerts/record   → domain mjs
+  ├─ index/get/lint/review/path                      → dia kb
+  └─ query:
+       generic query → dia kb query
+       scene/rule     → 生成 dia 查询原语（--id / --weight），不重排
+
+dia packages/kb (single engine)
+  ├─ query planner: 归一化 → ID 直通 → term AND/OR → FTS / fallback → 加权排序
+  ├─ index: meta(schema/docs/built_at/max_mtime/tokenizer/root_hash)
+  ├─ atomic build: temp db + transaction + rename
+  └─ output: engine_version + hits[{path,score,why,tier}] + index{...}
+```
+
+**单一引擎铁律**：迁移期后，query 算法只能存在于 `packages/kb`；`yan-kb` 不得保留第二份打分。
+`YAN_KB_ENGINE` 改名/收窄为 `YAN_KB_QUERY_ENGINE=old|dia`，只控制 query；`index/get/lint` 固定 dia。
+
+---
+
+## 4. 质量门禁（切默认前必须全绿）
+
+### 4.1 golden 集
+
+- 从真实调用抽 **60 条 query + 20 scene/rule + 20 对抗样本（短词/同义/跨域）**；
+- 两人独立标 expected，分歧仲裁；
+- 原始 query 只放域数据根；dia 仓只存 hash + 结构性断言。
+
+### 4.2 指标
+
+| 指标 | 门槛 |
+|---|---|
+| 必召回（旧有命中 → dia 不得零命中） | **100%** |
+| answerable golden zero-hit | **0/40** |
+| recall@3 | ≥ 旧基线，且 ≥0.90 |
+| top1 | ≥ 旧基线；目标 ≥0.75（40+ 样本） |
+| MRR | ≥0.75 |
+| p95（热、端到端） | ≤60ms |
+| 冷首查 | ≤400ms |
+| 输出 token/次 | 中位 ≤ 旧值 +20% |
+| 确定性（3 次 Jaccard） | ≥0.9 |
+
+### 4.3 kill criteria
+
+任一触发 → **停止切默认**，保留旧 query：
+
+- top1 改善 <5pp 或 recall@3 <0.90；
+- 任何旧有命中变 dia 零命中；
+- p95 热 >80ms 或冷首查 >500ms；
+- 索引 >30MB 或 109 篇构建 >1s；
+- 并发读出现空/半截；
+- 输出 token 中位 >旧+20%。
+
+---
+
+## 5. 分阶段
+
+| 阶段 | 动作 | 门禁 |
+|---|---|---|
+| K2.1 | ✅ 完成：索引 meta、原子构建、`DIA_CACHE_DIR`、stat 指纹（docs+mtimeMs+size）、缺/陈旧索引报 `E_INDEX_MISSING/STALE` | 空/陈旧/root 不符/同秒矩阵通过；85 tests |
+| K2.2 | 🟡 100 query 质量过线；延迟口径待重定 | 召回 121/132=91.67%；零命中 0；top1_equal 75/87=86.21%；p95 dia 82.2 vs old 114.6ms；1 个 waiver |
+| K2.3 | ✅ 双跑脚本 `yan-kb-dual.sh`（yan-agent@next）；默认仍 old | 发现 1 个 known diff：旧命中 `rules/design-doc.md`，dia 未召回；**不切默认** |
+| K2.4 | 🟡 观察期：人工 waiver 已批准（旧 design-doc 误排）；默认仍 old | 2026-10-30→11-06：非 waiver miss=0 且指标不降；否则不切 |
+
+---
+
+## 6. 必须拍板的 3 个决策
+
+1. **兼容定义**：接受“契约 + 质量”而非“命中顺序逐字一致”。（推荐）
+2. **单引擎死线**：给定日期前 query 只保留 dia；不切须书面 blocker + 新日期。
+3. **域语义归属**：scene/rule/claims 不迁 dia；只给 dia 两个通用原语 `--id` 与 `--weight`，等第二个域消费者再抽 `kb-policy` 包。
+
+---
+
+## 7. 不做什么
+
+- 不把 scene/rule/claims/record 搬进 `packages/kb`；
+- 不为排序一致复制一份旧算法；
+- 不用 9 条样本做切换结论；
+- 不在索引缺失/陈旧时返回空列表冒充“无命中”；
+- 不先做 K2.4 再补 K2.1/K2.2。
+
+
+## 8. K2.3 双跑记录（2026-10-30）
+
+- 9 条 golden query：`old_hits` 全部被 dia 覆盖 8/9；`top1_equal` 7/9；
+- 唯一 miss：query `R30.5 评审请求消息模板`，旧实现命中 `rules/design-doc.md`，
+  dia 命中 `rules/notify.md`。旧实现的 R33/design-doc 与 R30.5 语义不一致，疑似旧误排；
+- 在人工裁决前 **不切默认**，旧 query 继续服务。
+- 原始 query 只写本地 `~/.yan-agent/observability/kb-dual-*.jsonl`，不进 dia 仓。
+
+
+## 9. K2.4 观察期（2026-10-30 → 2026-11-06）
+
+- 人工裁决（用户 2026-10-30）：`R30.5 评审请求消息模板` 的旧 `rules/design-doc.md` 命中判为旧实现误排；
+- waiver 记录在 `yan-agent@next:scripts/kb-dual-waivers.json`（query hash + old path + 到期日）；
+- 双跑脚本把该条标为 `WAIVED`，不再计入 miss；
+- **默认仍走 old**；观察 7 天（至 2026-11-06），非 waiver miss 必须为 0，且 top1/zero 不降；
+- 观察期满另立 K2.5 切换任务，不在本轮自动切。
+
+
+## 10. K2.2 100 条结论（2026-10-30）
+
+- 召回 91.67%、answerable zero 0、top1 一致 86.21% → 质量门禁通过；
+- CLI p95 82.2ms（旧 114.6ms），绝对 60ms 门槛未过；**不把它偷偷改成 pass**，延迟口径需按环境改为“相对旧实现不退化”；
+- K2.4 观察期继续，K2.5 不切默认。
+
+
+## 11. K2.5 提前切换（2026-10-30）
+
+用户决定跳过 7 天观察，**仅切 `yan-agent@next`**，main/现网不动：
+
+- `yan-kb query` 默认 `dia`；`YAN_KB_ENGINE=old` 可回滚；
+- 无 `DIA_BIN` 时自动回退 old；
+- `scene/rule/auto/claims` 继续旧实现；
+- `dia kb query --auto-index`：缺/陈旧索引先重建，避免切换后首次查询直接报错；
+- 验证：next 分支 `yan-kb-engine.test.sh` 7 PASS；main 仍为旧实现；
+- 回滚：`YAN_KB_ENGINE=old yan-kb query ...` 或切回 main。

package/docs/migrations/yan-kb.md

@@ -0,0 +1,120 @@
+# yan-kb → dia kb：能力矩阵与迁移计划
+
+> **v2 修订（2026-10-30）**：兼容边界、质量门禁、单引擎架构见 [`yan-kb-parity.md`](yan-kb-parity.md)。
+> 本文的 K2 仅保留为历史阶段；query 切换必须先过 v2 的 K2.1–K2.3。
+
+> 日期 2026-10-30。回答：**当前 dia kb 能替代 yan-kb 的哪些工具？**
+> 结论：能替代 `index/get/lint` 的通用部分；`query` 需要补 parity；
+> `scene/rule/auto/claims/baseline/alerts/record/scene sync` 是 yan 域语义，不迁 dia，也不单独建仓。
+
+---
+
+## 1. 计划原文（先对齐）
+
+`docs/architecture.md`：
+
+- §2 职责矩阵：**知识索引 / 检索 / 复审队列 → framework**；域只提供知识。
+- §3 存储：md 唯一事实源；sqlite **派生索引**；检索、复审队列、断链、覆盖统计由工具生成。
+- §4 抽取顺序：定义契约 `kb search/get/lint` → framework 最小版 → **先切 yan-kb 的检索** → dabo → kit。
+- 判据：同一查询 20 条结果集一致；索引重建哈希一致；yan 一周无回归。
+
+`docs/history/framework-bootstrap.md` §3：
+
+```text
+kb index [--root]
+kb search "<q>"
+kb lint
+kb get <path> [--section]
+```
+
+所以计划从一开始就是：**framework 接管通用 KB 工具，yan-kb 保留域编排**。不是把整个 `yan-kb` 搬进 dia。
+
+---
+
+## 2. 当前实现对照
+
+dia `src/kb.ts` 现在只有：`index / search / lint / get`。
+
+| yan-kb 工具 | dia 现状 | 能否替代 | 说明 |
+|---|---|---|---|
+| `query "<意图>"` | `search` | ⚠️ 部分 | dia 是 FTS/LIKE；yan 有意图路由、排序、digest/full、observe |
+| `--scene` / `--scene-list` | 无 | ❌ | 场景卡属于 yan 知识语义 |
+| `--rule <ID>` | 无 | ❌ | 规则 ID 解析属于 yan 知识语义 |
+| `--auto "<一句话>"` | 无 | ❌ | dispatch/场景路由属于 yan |
+| `path <addr>` | 无 | ⚠️ 可抽 | 知识地址解析可做通用契约 |
+| `claims` | 无 | ❌ | 承诺台账是 yan 域 |
+| `baseline` / `alerts` | 无 | ❌ | dispatch 基线/告警是 yan 域 |
+| `report` / observe | 无 | ⚠️ 可抽 | 调用观测是通用 telemetry，但 schema 未定 |
+| `record gap/decision/note` | 无 | ❌ | 写知识是域策略；不能进 framework 默认写 |
+| `scene sync` | 无 | ❌ | 场景不变量是 yan 域 |
+| `doctor` | 无 | ❌ | yan 组合自检 |
+| `index` | ✅ | ✅ | 通用 |
+| `lint` | ✅（基础） | ⚠️ 部分 | dia 有覆盖/复审/断链；yan 还查 scene/rule 引用、承诺等 |
+| `get` | ✅ | ✅ | 通用 |
+
+**一句话**：`index/get` 可直接替代；`lint` 替代基础部分；`query` 是下一个 parity 项；其余是域语义，不该进 dia。
+
+---
+
+## 3. 修正后的迁移计划
+
+### K0：冻结查询集（无模型，1 天）✅
+
+- 从 yan 真实 `kb-calls.jsonl` 抽 20 条查询（含 scene/rule/auto）；
+- 记录 `path 集合 + 顺序 + exit code` 为 golden；
+- 只读，不改 yan。
+
+### K1：dia kb 补通用契约 ✅
+
+- ✅ `dia kb query`：兼容 `search`，加 `--json/--full/--bytes`；
+- ✅ 复审队列：`dia kb review`（缺失/到期/stale）；
+- ✅ `dia kb path`：doc/workflow/skill/tool 地址 → 绝对路径；可配 `--repo/--skills-dir`；
+- `dia kb observe/report`：可选；先定义 JSONL schema，不急着迁。
+- 判据：20 条查询路径集合一致；索引重建两次哈希一致。
+
+### K2：yan-kb thin shim（进行中）
+
+```text
+yan-kb index   → exec dia kb index --root <yan-core/knowledge>   ✅
+yan-kb lint    → exec dia kb lint --root ...                     ✅
+yan-kb get     → exec dia kb get --root ...                      ✅
+yan-kb query   → 默认旧实现；YAN_KB_ENGINE=dia 显式走 dia       ⚠️ parity 未达
+yan-kb --scene/--rule/--auto/claims/baseline/alerts/record → 本地实现（不动）
+```
+
+> 2026-10-30 实测：`YAN_KB_ENGINE=dia` 对真实 query `R30.5 评审请求消息模板` 返回空，
+> 旧实现有 R33 命中。因此 **query 默认继续走旧实现**，K2 只完成 index/get/lint 路由；
+> query parity 归入 K2.1，不得切默认。
+
+- 不复制实现；`yan-kb` 只做路由和域参数；
+- `index/get/lint` 已切；`query` 双跑显示路径/语义未对齐，暂不切默认。
+
+### K3：一周双跑 + 回滚
+
+- 同一查询新旧输出对比；
+- `YAN_KB_ENGINE=old|dia` 开关；
+- 有回归立即切回；一周无回归才默认 dia。
+
+### K4：只有 dabo 也需要 scene/claims 时才抽包
+
+- 抽 `kb-policy`（私有包）而不是 `yan-kb` 整仓；
+- 否则 scene/claims 永远留 yan-agent@next。
+
+---
+
+## 4. 边界
+
+**迁 dia**：index、query/search、get、lint 基础项、review queue、path、observe（schema 稳定后）。
+
+**留 yan-agent@next**：scene、rule ID、auto dispatch、claims、baseline、alerts、record 写入策略、scene sync、doctor。
+
+**不建 `yan-kb` 独立仓**：它不是一个通用工具，而是“dia kb 引擎 + yan 知识语义”的组合入口。独立会把 yan 的 scenes/rules/claims 一起拖走，dabo 又不需要。
+
+---
+
+## 5. 下一步
+
+1. 先做 K0：20 条真实查询 golden；
+2. ✅ K1 `dia kb query/review/path` 已完成；
+3. K2 只切 `query/index/get`，`--scene` 等不动；
+4. 每次变更附命令与输出，不用“应该可以”结案。

package/docs/model-baseline-sidecar.md

@@ -0,0 +1,220 @@
+# 模型基准与 Sidecar 监控（A+B 一起）
+
+> 日期 2026-10-28。
+> A：**首次使用先跑基准**，用数据决定配置。
+> B：**常驻 sidecar**，用同一套基准对比线上表现，及时发现模型降质/异常。
+> 两者共用一套任务集与指纹，缺一不可。
+
+---
+
+## 1. 为什么必须 A+B 一起
+
+- 只有 A：配置有据，但模型静默升级/降质无人发现。
+- 只有 B：有监控，但没有基线可比，阈值只能拍脑袋。
+- 合起来：**基准 → 配置 → 监控 → 异常 → 重跑基准 → 决策**，形成闭环。
+
+---
+
+## 2. A：首次使用基准
+
+### 2.1 任务来源（公共 + 私有）
+
+| 来源 | 用途 | 说明 |
+|---|---|---|
+| **公共基准 mini 子集** | 首次 baseline | BFCL 50 / τ² 10 / TB2 5；各用自己的 runner，dia 只**导入结果 JSON** |
+| **私有任务（PR + episode 结合）** | baseline + 长期 canary | PR：代码/终端；episode：问答/结构化/工具；自包含、判据脚本化、脱敏、季度轮换 30% |
+| **日期切片题**（LiveCodeBench 新月题） | 事故 canary 补充 | 训练集物理上不含 |
+
+**污染规则**：SWE-bench / Aider / BFCL / tau / GAIA 已高度污染 → **只做首次画像，不做长期健康度**；健康度只看私有 canary。
+详见 `docs/research/benchmarks-survey.md`。
+
+### 2.1.1 基准任务集
+
+每个任务类留 3–5 个 canary（合计 8–12 个），要求：
+
+| 要求 | 原因 |
+|---|---|
+| 有确定性判据（可脚本校验） | 不靠人打分 |
+| 输出短（≤500 token） | 控制成本 |
+| 覆盖四类：长上下文 / 工具密集 / 低成本 / 高可靠 | 与路由类对应 |
+| 不含敏感数据 | 不进第三方训练/日志 |
+| 可轮换（held-out 留 20%） | 防过拟合与缓存 |
+
+### 2.2 运行协议
+
+对每个模型、每个任务：**跑 3 次**（取中位数），记录：
+
+```yaml
+task: { id, class, hash, judge }
+runs: 3
+metrics:
+  success: bool
+  steps: int
+  tool_calls: int
+  tool_arg_errors: int
+  schema_errors: int
+  parse_repairs: int
+  tokens_in/out/cache: int
+  latency_ms: int
+  cost_usd: float
+```
+
+### 2.3 由基准推导配置
+
+| 配置 | 推导规则 |
+|---|---|
+| `context_budget` | `min(声明窗口, 实测安全窗口) × 0.8 − maxOutput` |
+| `max_steps` | 该类任务的 p90 步数 × 1.2 |
+| `retry_policy` | 按失败类型分布：限流多→退避；解析多→修复循环 |
+| `route_class` | 按实测（成功率/成本/延迟）落到四类之一 |
+| `vote_eligible` | 成功率 ≥ 阈值且稳定（用于验收双票） |
+
+**指纹与判据（修正）**：
+
+```
+fingerprint = sha256(suite_id|n|judge_id|judge_ver|temperature|seed|spec_id)
+判据：同 fingerprint 重跑，逐题 pass 集合 Jaccard ≥ 0.95；flaky 题单列
+```
+
+产物：`~/.local/share/dia/baselines/<provider>/<model>@<date>.json`（含 spec_id、fingerprint、任务 hash、指标、配置、判据版本）。
+
+---
+
+## 3. B：Sidecar 监控
+
+### 3.1 形态（已定：事故优先，定时默认关）
+
+- **默认不常驻**：定时任务只提供**模板**（launchd plist / `sidecar --once`），**默认不启用**。
+- **事故触发**：`dia model incident --model X` 立刻跑一轮 canary（3–5 个），对比基线，写 drift。
+- 确认降级后 → 进**观察名单**，再为该模型启用定时监控（模板 + 节拍）。
+- 独立进程，不共享主会话/上下文/凭据；只写监控数据，不改业务状态。
+
+### 3.1.1 观察名单（watchlist）
+
+状态机：
+
+```
+active ──drift──> watch ──确认降级──> degraded ──恢复──> active
+                    │                    │
+                    └── 启用定时监控 ────┘
+```
+
+- `watch`：已进观察名单，定时监控可开启；路由**仍可用**但标注风险。
+- `degraded`：确认降质；路由建议 fallback，**切换需人批**。
+- `retired`：不再使用，保留历史。
+
+状态变更只追加到 `model_state.jsonl`（`{ts, model, from, to, reason, evidence}`）。
+
+### 3.2 漂移判定（三个统计量，TS 自实现，零依赖）
+
+设基线窗口 `n0, p0, μ0, σ0`（冻结），当日窗口 `n1, x1`：
+
+| # | 用途 | 公式 | 判异 |
+|---|---|---|---|
+| 1 | 成功率漂移 | 双比例 z：`z=(p̂1−p0)/√(p̄(1−p̄)(1/n0+1/n1))` | `|z| > 2.58`（99%） |
+| 2 | 趋势（EWMA） | `z_t=λx_t+(1−λ)z_{t−1}`，`λ=0.2` | `|z_t−μ0| > 3σ0√(λ/(2−λ))` |
+| 3 | 降级起点（单侧 CUSUM） | `S⁺_t=max(0,S⁺_{t−1}+(x_t−μ0−kσ0))`，`k=0.5` | `S⁺ > 4σ0`；报警时刻即"由绿转黄"那一格 |
+
+- 类别型（token 分桶/错误类型）补 PSI：`Σ(pᵢ−qᵢ)ln(pᵢ/qᵢ)`，`>0.2` 显著。
+- 样本不足（`n1<10` 或基线 `n0<30`）→ 写"无法判定"，不下结论。
+- 阈值进代码常量（单一事实源），文档不得另写一套。
+
+**为什么不引入库**：Evidently/NannyML 需要 DataFrame + reference 窗口（≥1000 行），Alibi 是 BSL-1.1（非 OSI），whylogs 已停更；三个公式在 TS 里各 10 行，没有引入理由。
+
+### 3.3 异常处置
+
+```
+事故/怀疑 → dia model incident（立刻跑一轮）→ 对比基线
+        → 进 watch（观察名单）→ 启用定时监控 → 确认降级 → degraded
+        → 路由建议 fallback（不静默）→ 人决定：恢复 / 降级 / 替换
+```
+
+- **不自动切模型**：只标记 + 路由建议，切换需人批（与"用户显式选模型 = strict"一致）。
+- 事故模式保留现场：baseline 复跑结果 + 当轮 canary 明细 + 时间点。
+
+---
+
+## 4. 可视化（uptime 时间轴 + 日级热力图）
+
+### 4.1 uptime 时间轴（按模型）
+
+**定义**：`uptime = 当日 canary 通过率`；颜色三态：`≥0.99 绿 / ≥0.95 黄 / 其余红`。
+CUSUM 报警时刻 = 降级的起点，直接标在时间轴上。
+
+```
+Kimi-K2.7-Code   ██████████▓▓▓███  (▓ = watch, ▒ = degraded)
+GLM-5.3          ████████████████
+DeepSeek-V4-Pro  ███████████▒▒███
+```
+
+### 4.2 日级热力图（contribution 风格）
+
+每格一天，深浅 = 当日 drift 事件数 / 偏差幅度；点开（或 `--json`）看当日指标。
+
+### 4.3 输出形态（零依赖）
+
+- `dia model status --chart`：终端文本图；
+- `dia model status --json`：输出 **Vega-Lite spec**（`rect` 分面 = 热力图，`line+band` = uptime 时间轴），可嵌 HTML；
+- `dia model status --svg`：本地渲染静态 SVG（无需浏览器）；
+- 将来要仪表盘再加 `Grafana + Infinity`（读 `/metrics.json`），不是现在的必需。
+
+数据来源：`model_state.jsonl` + `drift_events.jsonl` + `baselines/*.json`。
+
+**不引入**：Alibi（许可）、whylogs（停更）、Phoenix（ELv2）、Braintrust（闭源）、Metabase/Superset/Cachet（ETL 重）。
+
+## 4. 数据结构
+
+```yaml
+baseline:
+  model: provider/name
+  version: <provider 声明或探测>
+  created_at: ISO
+  judge_version: v1
+  config: { context_budget, max_steps, retry_policy, route_class, vote_eligible }
+  tasks: [{ id, class, hash, metrics, runs }]
+  fingerprint: { success_rate, steps_p50, tool_arg_error_rate, schema_error_rate, latency_p50, cache_hit }
+
+drift_event:
+  ts, model, metric, baseline, observed, delta, samples, verdict, action
+```
+
+---
+
+## 5. 与现有组件的关系
+
+| 组件 | 关系 |
+|---|---|
+| `deps.jsonl` | 模型作为 `kind: model` 依赖登记（version/verified_at） |
+| `runtime/calls.jsonl` | 线上成本/延迟/工具错误的来源 |
+| `audit.jsonl` | 异常动作与人工裁决留痕 |
+| `dabo-agent:docs/hypotheses.md`（外部引用） | H13/H14 的判据来自 baseline + sidecar |
+| 路由 | 只用 baseline 得出的 `route_class`，不靠猜 |
+
+---
+
+## 6. 失败模式
+
+| 风险 | 对策 |
+|---|---|
+| canary 太小 → 噪声误报 | EWMA + 连续 N 次；样本不足判"无法判定" |
+| canary 太大 → 成本高 | 输出限 500 token；每天预算上限 |
+| 缓存命中导致假快 | canary 轮换、变化 prompt 前缀 |
+| provider 静默升级 | 记录 version/指纹变化；无法归因时标注"疑似" |
+| canary 泄漏敏感数据 | 任务集固定且脱敏；禁止用真实会话做 canary |
+| 过拟合 canary | 20% held-out；每季度从真实失败补题 |
+
+---
+
+## 7. 实现计划（A+B 同一批）
+
+1. `dia model list`：ModelSpec + 能力探测（声明 + 首次探针，缓存 90 天）。
+1.5 `dia model baseline --from <results.json>`：导入外部 benchmark runner 的结果（不重写 harness）。
+2. `dia model baseline --model X --tasks <yaml>`：跑基准、写 baseline、输出推导配置。
+3. `dia model sidecar --once`：跑 canary、对比基线、写 drift。
+4. `dia model status`：列出每个模型的配置、指纹、最近 drift。
+5. 接入路由与验收投票：只用有 baseline 且 `vote_eligible` 的模型。
+
+**判据**：
+1. 同 fingerprint 重跑，逐题 pass 集合 **Jaccard ≥0.95**；
+2. 人为注入降质（缩短输出上限）能在 **1 轮**内被检出（critical = 工具参数合法率）；
+3. 成本按 `task_id` 归集，重试计入同一任务。