@minonl/dia 0.0.0-stage → 0.0.2-beta.0

package/docs/kit-install.md

@@ -0,0 +1,339 @@
+# Kit：内容包安装（persona 的第二个半边）
+
+> 日期 2026-10-30。前置：`docs/persona-install.md`（persona = 人格，kit = 内容）。
+> 本文只定 **kit 的清单格式、渲染规则、生命周期、边界**；实现拆到 P1/P2/P3。
+>
+> **2026-11-03 实现状态**：只有 `dia kit add / list / verify / remove`；本文出现的 `kit show`、`kit update`、
+> `kit gc`、`kit create` 仍是设计。persona 自带的 `files/skills/dirs/config` 内联内容已由 `persona add` 承担。
+
+---
+
+## 0. 一句话
+
+**persona 决定「你是谁」，kit 决定「你会什么」**：人格 md 之外的一切静态内容——知识树、skill、PATH 命令、
+宿主配置文件、运行时目录——都由 kit 声明式分发，dia 负责复制、记账、校验、回滚。
+
+---
+
+## 1. 现状缺口（为什么需要它）
+
+`dia persona add yan` 现在的产物只有 `~/.config/opencode/agents/yan.md`（3522 字节）。而 yan 的最小可用状态还差：
+
+| 缺的东西 | 现在由谁做 | 后果（干净机器上） |
+|---|---|---|
+| `core/knowledge`（2.3M） | `install.sh` 软链 `core/AGENTS.md` | 人格里写的「先查库」查不到 |
+| `yan-kb` / `yan-worktree` 等 PATH 命令 | `install.sh` → `scripts/install-cli` | `yan-kb --scene S1` 直接 command not found |
+| `core/skills/yan-onboarding` | 软链到各宿主 skill 目录 | onboarding 不会触发 |
+| `~/.config/opencode/AGENTS.md` | 软链 `core/AGENTS.md` | 全局规则不生效 |
+| 宿主配置（default_agent / permission） | `ensure-permission.py` 改 JSON | 权限白名单缺，读写被拦 |
+| 数据根目录树 | `install.sh` mkdir | 首次运行写失败 |
+
+结论：**persona 装完是"哑"的**；kit 就是把这些补上，且要能 `verify` / `remove`。
+
+---
+
+## 2. 清单：`dia.json`（kind=kit）
+
+```json
+{
+  "schema": 1,
+  "kind": "kit",
+  "id": "yan-core",
+  "version": "0.1.0",
+  "root": ".",
+  "files": [
+    { "from": "core/AGENTS.md", "to": "~/.config/opencode/AGENTS.md" },
+    { "from": "core/AGENTS.md", "to": "~/.codex/AGENTS.md" }
+  ],
+  "skills": [
+    { "from": "core/skills/yan-onboarding", "name": "yan-onboarding", "mode": "link" }
+  ],
+  "bin": [
+    { "from": "scripts/yan-kb", "name": "yan-kb" },
+    { "from": "scripts/yan-worktree", "name": "yan-worktree" }
+  ],
+  "dirs": [
+    "~/.yan-agent/cache",
+    "~/.yan-agent/backups",
+    "~/.yan-agent/tasks",
+    "~/.yan-agent/observability"
+  ],
+  "config": [
+    {
+      "file": "~/.config/opencode/opencode.json",
+      "jsonc": true,
+      "set": { "permission.external_directory": { "~/.yan-agent/**": "allow" } }
+    }
+  ],
+  "knowledge": ["core/knowledge"],
+  "requires": { "dia": ">=0.1.0" }
+}
+```
+
+字段语义：
+
+| 字段 | 语义 | 渲染方式 |
+|---|---|---|
+| `root` | 包内**运行根**：bin / knowledge / AGENTS.md 相对它解析 | 安装后 rider 根 = `<DATA>/kits/<id>/<version>/<root>` |
+| `files` | 单文件 → 目标路径 | **复制**（内容哈希记账） |
+| `skills` | 目录 → 宿主 skill 目录 | `mode: link` 软链回 kit 根（单源）；`copy` 独立复制 |
+| `bin` | 脚本 → `~/.local/bin/<name>` | **软链**回 kit 根（脚本靠自身 realpath 推根，见 §3.2） |
+| `dirs` | 运行时目录 | `mkdir -p`，**remove 时不删**（可能已有用户数据） |
+| `config` | 宿主 JSON 配置合并 | P2 实现；写前记录原值，remove 按记录还原 |
+| `knowledge` | 声明给 `dia kb` 用的知识根 | 不复制，只在 `dia kit show` 里暴露绝对路径 |
+
+**为什么 `root` 而不是逐文件列**：yan 的脚本自己解析 `REPO_DIR`（`scripts/yan-kb` 靠 `SELF_DIR/..`），
+如果只把 `scripts/yan-kb` 单文件搬到 `~/.local/bin`，它找不到 `core/knowledge`。整棵树进 kit 根，软链回原处，脚本零改动。
+
+---
+
+### 2.1 persona 可自带内容（内联 kit）——已定案（2026-10-30）
+
+```json
+{
+  "schema": 1, "kind": "persona", "id": "yan", "version": "0.1.0",
+  "entry": { "opencode": "platform/opencode/files/opencode-agent-yan.md" },
+  "files":   [{ "from": "core/AGENTS.md", "to": "~/.config/opencode/AGENTS.md" }],
+  "skills":  [{ "from": "core/skills/yan-onboarding", "name": "yan-onboarding", "mode": "link" }],
+  "dirs":    ["~/.yan-agent/cache", "~/.yan-agent/tasks"],
+  "knowledge": ["core/knowledge"],
+  "data_root": "~/.yan-agent",
+  "commands": [{ "name": "scene", "entry": "scripts/kb-domain.mjs", "env": { "YAN_DATA_ROOT": "~/.yan-agent" } }],
+  "kits": ["../shared/leyan-skills"]
+}
+```
+
+persona 与 kit 用**同一套内容字段**（`files/skills/bin/dirs/commands/knowledge/data_root`），差别只在所有者：
+
+| | 谁的内容 | 路径基准 | 生命周期 |
+|---|---|---|---|
+| persona 自带 | 该人格专属（规则、知识、域命令） | persona 根 | 随 persona 装/卸 |
+| 独立 kit | 跨人格/第三方复用（共享 skill 包） | kit 根 | 独立装/卸，可被多 persona 引用 |
+
+**为什么要有这一层**：把 `core/knowledge` 搬进 `kits/yan-core/` 要改 46 处脚本、65 个 md 的硬编码路径，
+收益只是"目录好看"。内联后 persona 根就是内容根，历史路径零改动；复用需求一旦出现，再拆独立 kit 即可。
+
+实现上两者共用 `kit.renderContent(baseDir, targetDir, manifest)`：persona 传 `baseDir = targetDir = persona 树`，
+kit 传 `baseDir = 包内目录, targetDir = DATA/kits/<id>/<version>`。
+
+---
+
+## 3. 安装管线
+
+```mermaid
+flowchart TD
+  A[dia persona add yan --from git+... --ref sha] --> B[clone 到缓存, 校验 dia.json]
+  B --> C{persona.kits 引用?}
+  C -- 无 --> D[渲染人格 md]
+  C -- 有 --> E[对每个 kit 解析: 包内相对路径 / git+ URL]
+  E --> F[校验 kit 清单: schema/id/version/路径不越界]
+  F --> G[复制整棵树到 DATA/kits/id/version]
+  G --> H{冲突检查: 目标存在且非 dia 管理?}
+  H -- 冲突 --> X[E_CONFLICT, 不写任何文件]
+  H -- 干净 --> I[files 复制 / skills 软链 / bin 软链 / dirs mkdir / config 合并]
+  I --> J[写 kit.lock: 每产物 sha256 + 原值快照]
+  J --> D
+  D --> K[写 persona dia.lock, 记录 kits 版本]
+  K --> L[dia persona verify: 内容哈希 + 产物哈希全对]
+```
+
+### 3.1 复制还是软链
+
+| 类别 | 选择 | 理由 |
+|---|---|---|
+| kit 内容树 | **复制**到 `DATA/kits/` | 与 persona 一致；源仓可移动/删除；`verify` 有稳定基准 |
+| `bin` | **软链**到 kit 根 | 脚本必须能反推 `REPO_DIR`；复制单文件会打断 |
+| 内部 skill | **软链**到 kit 根 | 与 `install.sh` 现有行为一致（`core/skills/yan-onboarding`） |
+| `files`（AGENTS.md 等） | **复制** | 宿主只读文件；软链会让宿主读到 `.git` 里的脏状态 |
+
+### 3.2 bin 软链为什么能工作
+
+`scripts/yan-kb` 解析真实路径链（`while [ -L ... ]`）→ `<DATA>/kits/yan-core/0.1.0/scripts/yan-kb`，
+`SELF_DIR/..` 即 kit 根，`core/knowledge` 就地可读。**不需要**任何 `YAN_REPO_DIR` 环境变量，也不需要 install-cli 生成启动器。
+
+### 3.3 幂等与升级
+
+- 同 `<id>@<version>` 重装：内容哈希一致 → 无写入，返回 `unchanged`；
+- 换版本（`dia kit update`）：旧目录保留（多版本共存），产物按 lock 备份后重写，`dia kit gc` 清理非当前版本；
+- persona 与 kit 版本联动：persona 的 `dia.lock` 记录 `kits: {"yan-core": "0.1.0"}`，`persona verify` 一并校验。
+
+---
+
+## 4. 生命周期与退出码
+
+| 命令 | 行为 | 关键约束 |
+|---|---|---|
+| `dia kit add <src> [--ref]` | 取回 → 校验 → 复制 → 渲染 → lock | 不执行任何脚本 |
+| `dia kit list` | 已装 kit + 版本 + 产物数 | 只读 |
+| `dia kit verify <id> [--version]` | 内容哈希 + 每个产物哈希 | 不一致 → exit 21（`E_HASH`） |
+| `dia kit update <id> --ref` | 新版本 → 备份旧产物 → 重渲染 | 破坏性变更提示 |
+| `dia kit remove <id>` | 只删 hash 匹配的产物；手改过的**拒绝删并列出** | exit 0 附 `skipped[]` |
+
+沿用 persona 的退出码：`E_MANIFEST` 20 / `E_HASH` 21 / `E_CONFLICT` 32 / `E_HOST` 33 / `E_SOURCE` 34（新增：源不可达）。
+
+---
+
+## 5. 边界（明确不做）
+
+1. **不执行安装脚本**：kit 里写 `install.sh` 也不跑（与 persona 同）。
+2. **不装第三方包**：`npx skills add` 出来的 leyan-skills 等**不由 kit 管**；kit 只声明 `requires.npx` 并在缺失时 `W_` 告警。
+3. **不管卸载服务**：launchd/cron 任务归 `dia job`，kit 不创建任务。
+4. **不写默认 agent**：`default_agent` 只允许通过 `config` 显式声明（P2），且必须可回滚；kit 不猜。
+5. **不碰用户手改**：产物哈希不匹配一律 skip，不覆盖、不删除。
+
+安全（沿用 persona §4）：来源白名单（git host + owner）、`--ref` 解析成 commit sha 落 lock、路径不得越出包根、`--dry-run` 列出将写入的每个路径。
+
+---
+
+## 6. 命令面：装完之后的命令不是 `yan-kb`
+
+安装只是让内容到位；**入口也要归一**，否则 kit 只是把旧脚本换个地方放。
+
+### 6.1 原则：一个入口 `dia`，加 persona 作用域
+
+```bash
+dia --persona yan kb query "MR 合并"      # 显式作用域
+DIA_PERSONA=yan dia kb query "MR 合并"    # 会议/脚本里设一次
+```
+
+作用域解析链（`--persona` > `DIA_PERSONA` > 唯一已装 persona）：
+
+```text
+--persona yan
+  → DATA/personas/yan/<ver>/dia.lock.kits          # 该人格引用了哪些 kit
+  → kit.knowledge → <kitroot>/core/knowledge        # 知识根
+  → kit.data_root → ~/.yan-agent                    # 运行时数据（db/backups/tasks）
+  → 不在 persona 作用域里时，退回 `--root` / cwd（旧行为）
+```
+
+**为什么要 `--persona` 而不是 `--root`**：`--root` 只解决"读哪棵树"，解决不了"用哪个数据根、哪些域命令可用、
+哪个 db 文件"。这些是人格的属性，不是目录的属性。
+
+### 6.2 映射表（旧 → 新）
+
+| 旧命令 | 新命令 | 备注 |
+|---|---|---|
+| `yan-kb "意图"` | `dia kb query "意图"` | 默认 path：KB 物理进 dia，命令名跟着进 |
+| `yan-kb --scene S1` | `dia kb scene S1` | 域语义，经委派（§6.3） |
+| `yan-kb --rule R25` | `dia kb rule R25` | 同上 |
+| `yan-kb --auto "…"` | `dia kb auto "…"` | 同上；UNKNOWN 仍 exit 5 |
+| `yan-kb record gap\|decision\|note` | `dia kb record …` | 委派到 yan 实现（写入目标文件是域事实） |
+| `yan-kb report` / `path` / `claims` / `baseline` / `alerts` | `dia kb <同名>` | 前两个内置，其余委派 |
+| `yan-kb doctor` | `dia doctor --persona yan` | 组合自检归 dia |
+| `yan-worktree create\|clean\|check\|scope\|route` | `dia wt create\|clean\|check\|…` | `packages/wt`，§7 |
+| `yan-task list\|status\|install…` | `dia job <同名>` | 已完成（`packages/job`） |
+| `yan-version` | `dia persona show yan` | 版本 = persona 版本 + lock 里的 commit |
+
+### 6.3 域语义怎么落：子命令委派（`git-foo` 机制）
+
+内置子命令之外，`dia kb` 查 persona 已装 kit 的 `commands` 声明，命中就委派：
+
+```json
+"commands": [
+  { "name": "scene",    "entry": "core/knowledge/scripts/kb-scene.mjs",    "runtime": "bun|node" },
+  { "name": "rule",     "entry": "core/knowledge/scripts/kb-rule.mjs" },
+  { "name": "auto",     "entry": "core/knowledge/scripts/kb-auto.mjs" },
+  { "name": "record",   "entry": "core/knowledge/scripts/kb-record.mjs" }
+]
+```
+
+行为约定：`argv` 原样透传、`cwd` 不变、`YAN_*` 等 persona 环境变量由 dia 注入、**子进程 exit code 原样返回**
+（`--auto` 的 UNKNOWN=5 语义不能丢）。
+
+好处：`dia` 不需要认识 scene/rule/claims；域实现仍住在 yan 仓，随 kit 版本走；命令面只有一个。
+
+### 6.4 不做 shim：一步切换
+
+**决策（2026-10-30，用户拍板）**：不留 `yan-*` 转发 shim，安装产物里**没有任何 `yan-` 前缀命令**。
+
+1. `yan-kb` / `yan-worktree` / `yan-task` / `yan-doctor` 等脚本从 yan 仓**删除**，逻辑进 dia（`packages/*`）或作为
+   kit 的 `commands` 扩展；不是保留转发。
+2. 因此迁移验证只在**开发侧**做一次对照（同一份数据新旧各跑一遍，比对输出），对照脚本随老代码一起删，不随包分发。
+3. 文档引用就地改写（`yan-kb` 131 处 / `yan-worktree` 99 处 / `yan-task` 282 处），与代码删除同一个 MR/commit。
+4. **扫描门禁**：yan 仓 CI 加一条 `grep -rE "\byan-(kb|worktree|task|doctor|env|ref|mr|schedule|version)\b"`
+   白名单外命中即失败——防止回潮。
+
+---
+
+## 7. worktree：`dia wt`（`packages/wt`）
+
+`yan-worktree` 1160 行、5 套测试（`check`/`clean`/`prune-merged`/`route`/`scope`）。归属 `packages/wt`（monorepo 先例：`packages/job`）。
+
+| 抽取项 | 处理 |
+|---|---|
+| `YAN_DATA_ROOT` / `tasks/scopes` | 参数化为 `DIA_WT_DATA_ROOT`（persona 注入 `~/.yan-agent`） |
+| `~/repos/leyan` 默认 | `DIA_WT_REPOS_ROOT`，缺失时不猜、报错 |
+| `YAN_SESSION_ID` | `DIA_SESSION` |
+| 直推 vs MR（`my_namespaces`/`direct`/`mr`） | **留 yan 域**，经 §6.3 委派（`dia wt route` → yan 扩展） |
+| `route_config_json` 里的 python3 heredoc | 换 Node JSON（`packages/job` 同款，dia 禁止 python） |
+
+**已落地（2026-10-30）**：`packages/wt/bin/dia-wt`（bash，与 `packages/job` 同模式）+ `packages/cli` 的 `dia wt` 转发 + `install.sh` 分发。
+env 全部改 `DIA_WT_*` / `DIA_SESSION`；7 处 python3 全部换成 Node（含 node_modules 扫描器），包内 python 归零。
+测试 4 套原样迁移全绿（check 27 / clean 20 / prune-merged 31 / route 26）；`scope` 16 项全绿，**其中「与 yan 权限层串联判定」1 项已移出**——
+那是 yan 域契约，不属于 dia wt。levm 上 `create → status → clean` 实跑通过。
+
+验收：**开发侧一次性对照**（旧脚本 vs `dia wt`，同仓同分支跑一遍
+`create/check/clean` 比对输出与 `git worktree list`）——因为 worktree 有分支与文件系统副作用，切错不便宜。
+对照完成后旧脚本即删，不随包分发。
+
+---
+
+## 8. 与 yan-agent@next 的对接（迁移顺序）
+
+```mermaid
+flowchart LR
+  subgraph 现在
+    Y1[yan-agent@next<br/>install.sh 装全部]
+  end
+  subgraph 目标
+    P[dia.json persona: yan<br/>entry = 人格 md]
+    K[dia.json kit: yan-core<br/>files/skills/bin/dirs/config]
+    D[dia persona add yan]
+    D --> P
+    D --> K
+  end
+  Y1 -.拆.-> P
+  Y1 -.拆.-> K
+```
+
+| 阶段 | 动作 | 门禁 |
+|---|---|---|
+| **K1** | kit 清单 + 复制/软链/记账/verify/remove（不含 `config`） | 隔离 HOME：`kit add` → `verify` → `remove` 无残留 |
+| **K2** | `config` 合并（opencode.json permission / default_agent），带原值快照回滚 | remove 后 opencode.json 与装前逐字节一致 |
+| **K3** | yan@next 落地 `dia.json`(persona) + `kits/yan-core/dia.json`（含 `commands` 委派） | 干净 VM：`dia persona add yan --from <gitlab> --ref <sha>` 后 `dia --persona yan kb scene S1` 可跑 |
+| **K4** | 删 `install.sh` / `uninstall.sh` / `scripts/yan-*`，入口只剩 `dia persona add` + `dia job bootstrap` | 仓内 `grep -rE "\byan-(kb|worktree|task)\"` 仅剩知识文档里的新命令名 |
+
+**验收（K3 定义「装好了」）**：
+1. 干净 HOME（无 `~/.yan-agent`、无 `yan-kb`、无 `agents/yan.md`）；
+2. `dia persona add yan --from <gitlab-url> --ref <sha>` 单命令完成；
+3. `cd /tmp && dia --persona yan kb scene S1` 出场景卡（证明知识根 + 数据根 + 委派都对）；
+4. `dia persona verify yan` → ok；`dia kit verify yan-core` → ok；
+5. `dia persona remove yan` → `~/.yan-agent` 运行数据保留、所有渲染产物消失、无断链。
+
+---
+
+## 9. 实施状态（2026-10-30）
+
+| 阶段 | 状态 | 证据 |
+|---|---|---|
+| K1 kit 安装器 | ✅ | `src/kit.ts` + 9 例单测 |
+| K1.5 作用域 + 委派 | ✅ | `src/scope.ts`、`dia --persona yan kb scene S1` |
+| K2 persona 内联内容 | ✅ | `renderContent(baseDir, targetDir)` 两处复用 |
+| K3 yan@next 形态 | ✅ | `feat/dia-persona` 分支；levm 实装通过 |
+| K4 worktree → `packages/wt` | ✅ | 7 处 python→node；5 套测试；`dia wt create/status/clean` levm 通过 |
+| K4 删旧命令面 | ✅（部分） | 删 yan-kb / yan-worktree / yan-task / 旧安装器；CI 门禁上线 |
+| K4 未迁移项 | ⏳ | `yan-mr` / `yan-release` / `yan-env` / `yan-ref` / `yan-schedule` / `yan-doctor` / `yan-version` / `yan-data-root` 仍在仓内、不随 persona 安装 |
+| P2 默认 agent | ✅ | `dia persona default <id>`（备份 + 原值记录 + `--unset`） |
+| P2 生效版本指针 | ✅ | `dia persona use <id>[@ver]` + `state/active.jsonl` 审计；scope 先读指针 |
+| P2 组合自检 | ✅ | `dia doctor`（0 全绿 / 1 warn / 2 fail） |
+| P2 凭据注入 | ✅ | `dia env list\|check\|run`（白名单、不回显、redact、不进 argv） |
+| P2 上游比对 | ✅ | `dia persona check`（same/differs/unknown/local-only）+ `update` 从记录源重装 |
+
+---
+
+## 10. 待拍板（实现前需要人确认）
+
+1. **kit 与 persona 是否同仓**：本文假设同仓、persona 用相对路径引用（`"kits": ["./kits/yan-core"]`）。若要支持独立 kit 仓（`git+…`），清单里就写 URL，实现多一条解析分支。
+2. **`config` 合并放 P1 还是 P2**：放 P1 能一次装到「开箱可用」，但要引入 JSONC 读写与回滚记账；放 P2 则先装内容、权限靠用户手动或旧 install.sh 兜一次。
+3. ~~命令面切换的节奏~~ **已定**：不留 shim，一步切（§6.4）。
+4. **`dirs` 的 remove 语义**：本文取「不删」（可能已有任务/备份数据）。若要删，需 `--purge-data` 且二次确认。

package/docs/migrations/kb-golden.md

@@ -0,0 +1,32 @@
+# K0：kb 查询 golden（20 条）
+
+> 2026-10-30。原始 query 只落在 yan 数据根，不提交到 dia 仓。
+
+- 来源：`~/.yan-agent/observability/kb-calls-2026-10.jsonl`（3002 条）
+- 抽样：`seed=30`，按 mode 分层（query/scene/rule/auto）
+- 输出：`~/.yan-agent/observability/kb-golden-20.json`
+- 本仓只记录方法、计数、哈希：
+  - 数量：20
+  - mode：query 9 / scene 6 / rule 3 / auto 2
+  - `query_hash`：`7279ffeea514…`
+- 用途：K1 `dia kb query` 的 parity 基准；**不是** CI 固定夹具（避免把工作域文本带进 public 仓）。
+
+复现：
+
+```sh
+bun experiments/kb-golden.ts <kb-calls.jsonl> <out.json>
+```
+
+
+## K2.2 100 条基准（2026-10-30）
+
+- 命令：`bun experiments/kb-bench.ts <kb-calls.jsonl> 100`
+- 样本：100 条真实 query；原始数据只在 `~/.yan-agent/observability/kb-bench-100.json`
+- 结果：
+  - answerable 87
+  - 规则召回 **121/132 = 91.67%**
+  - answerable zero-hit **0**
+  - top1 与旧实现一致 **75/87 = 86.21%**
+  - dia top1 落在旧命中集合 **84/87 = 96.55%**
+  - CLI p50/p95：旧 51.0/114.6ms，dia 57.1/82.2ms
+- 结论：召回/排序达到 K2.2 质量门槛；绝对 p95 60ms 未达，但相对旧实现更快，延迟门槛需按环境改为相对基线，不能静默改口径。

package/docs/migrations/llm-migration.md

@@ -0,0 +1,49 @@
+# 配置迁移：用 LLM 任务，不写 migration 代码
+
+> 2026-11-04。适用：dia / persona / kit 的**声明式格式**升级（`dia.json`、`lock`、`registry.json`、`deps.jsonl` 等）。
+> 原则：**升级 = 改声明 + 文档；旧数据迁移交给带判据的 LLM 任务**，不在代码里堆版本分支。
+
+## 1. 为什么
+
+- migration 代码要长期背兼容矩阵，测试面指数增长；
+- 声明式格式的迁移大多是"文本改写 + 语义校验"，正是 LLM 擅长的；
+- 用任务 + 判据驱动，迁移过程本身可审计、可回滚。
+
+## 2. 流程（每版一次）
+
+1. **定版**：在 `docs/` 写清「旧格式 → 新格式」的对照表与判据（机器可执行命令优先）。
+2. **生成迁移任务**（模板见 §3）：一个版本一个任务，**幂等**、带 `--dry-run` 演练。
+3. **LLM 执行**：任务只允许改声明文件（`dia.json` / `dia.lock` / `projects/*.json`），不改代码。
+4. **判据校验**：`dia persona verify <id>` + `dia doctor --persona <id>` + 目标命令自检。
+5. **回滚**：迁移前 `dia persona use <id>@<old>` 或保留 `backups/`；失败即回滚，不半迁移。
+
+## 3. 任务模板
+
+```bash
+dia task add "迁移 <persona> 到 <schema vN>" --judge "dia persona verify <id> && dia doctor --persona <id> && bun run test"
+# 任务描述里必须带：
+#   - 旧格式样例（脱敏）
+#   - 新格式要求（字段/必填/默认值）
+#   - 只允许改的文件清单
+#   - dry-run 方式 + 回滚方式
+```
+
+LLM 侧执行约束（写进任务描述）：
+
+- 只改清单里列出的文件；**不碰** 代码、`docs/`、其它 persona；
+- 每步先 `--dry-run` 或 `git diff` 自证，再落盘；
+- 遇到无法判定的字段 → 停，不猜；
+- 完成后贴判据命令与输出。
+
+## 4. 禁止 / 要求
+
+| 禁止 | 要求 |
+|---|---|
+| 在代码里写 `if (schema === 1) ... else if (schema === 2)` 链 | schema 只做**校验**（不认识的版本直接报错） |
+| 迁移脚本自动改用户数据 | 迁移必须是一次显式任务，人可见 |
+| 迁移不可逆 | 先备份 + 记录旧版本指针 |
+| 一次迁多个版本 | 一版一任务，逐版迁移 |
+
+## 5. 例外
+
+当迁移是**安全敏感**（凭据、路径越界检查）或**必须原子**（审计链格式）时，才写代码，并在本文件登记理由与判据。

package/docs/migrations/no-python.md

@@ -0,0 +1,52 @@
+# Python 清理：Node/Bun 项目不收 Python
+
+> 日期 2026-10-30。目标：dia 仓库不把 Python 作为运行时/工具链依赖。
+
+## 现状
+
+| 区域 | 状态 |
+|---|---|
+| `experiments/*.py` | ✅ 已迁到 `experiments/*.ts`（Bun） |
+| `src/` / `packages/kb` / `packages/cli` | ✅ 无 Python |
+| `packages/job/bin/dia-job` | ✅ 已改用 `lib/json.mjs`（Node/Bun 内置 JSON） |
+| `packages/job/tests` | ✅ 测试夹具已改 Node |
+
+## 迁移记录
+
+`packages/job` 是从 bash 调度器继承的 OS 适配层，原先用 `python3` 做 JSON 解析。
+现已改为 `lib/json.mjs`：只用 Node/Bun 内置 JSON，不新增 workspace 包/解析器。
+
+## P3 完成（2026-10-30）
+
+1. ✅ `packages/job/lib/json.mjs`：labels/entries/get/set/del/rows/fields/backfill/selfcheck-rows/expected/bootstrap-rows；
+2. ✅ `packages/job/bin/dia-job` 无 `python3`；
+3. ✅ `packages/job/tests` 夹具改 Node；
+4. ✅ `rg -n 'python3?|\.py\b' packages/job` 为 0；
+5. 运行时要求：Node 或 Bun（`engines` 已声明）。
+
+## 当前结论
+
+- dia 全部 Python 清零（含 job）；
+- JSON 适配层不新增包，只用内置 JSON；
+- JSONC/JSON5 未默认引入，按 `no-python` 策略按需 opt-in。
+
+
+## JSON / JSONC / JSON5 兼容策略
+
+不新写 JSON 解析器，也不把 JSON 支持做成 workspace 包；只用 Node/Bun 内置 JSON + 一层薄适配。
+
+| 文件 | 规则 |
+|---|---|
+| `*.json`（registry/state/`dia.json`） | **严格 JSON**；机器写入，不接受注释/尾逗号 |
+| `*.jsonc`（人工配置，若引入） | 允许注释/尾逗号；读取兼容，写回 canonical JSON 并提示“注释会丢失” |
+| `*.json5` | **不默认支持**；单引号/无引号键/NaN 会扩大歧义面，只在明确需求时 opt-in |
+| `key=value` 配置 | 继续用现有 env/config 格式，不改成 JSON |
+
+实现约束：
+
+- 不写自定义 parser，不用 `eval`；
+- JSONC 若落地，使用固定版本的成熟解析器（如 `jsonc-parser`），并只对 `.jsonc` 生效；
+- job 的 `registry.json` / `state.jsonl` 永远 strict JSON，JSONC 只用于用户配置；
+- 写入始终原子化，不能因为兼容格式破坏状态文件。
+
+**结论**：兼容优先做 `JSON` + `JSONC`；`JSON5` 先不做，避免为了“宽松”把机器状态也弄脏。

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

@@ -0,0 +1,52 @@
+# yan-agent 切到 dia：本机现状与剩余迁移
+
+> 2026-11-02 初版，**2026-11-03 复核**。yan-agent 远端 main 已合入 `yan-agent@next`（dia persona 形态）。
+> 本文记录本机切换结果和**还没迁完**的部分；事实源仍是本机实际路径。
+
+## 已完成
+
+- yan-agent 本地备份：`~/.yan-agent/backups/yan-agent-<ts>/repo.bundle`
+- `dia persona add yan --from ~/.yan-agent/repos/yan-agent` 成功
+- `~/.config/opencode/agents/yan.md` 为 dia 渲染版
+- `~/.config/opencode/AGENTS.md`、`~/.codex/AGENTS.md` 已切到 dia 版
+- `opencode default_agent` 仍为 `yan`
+- `dia doctor --persona yan`：`verdict: ok`
+- `dia --persona yan kb scene S1/S2`、`query` 实测可用
+- 本地兼容 shim（不进仓库）：
+  - `yan-kb` → `dia --persona yan kb`
+  - `yan-worktree` → `dia wt`
+  - `yan-mr` / `yan-release` / `yan-schedule` → `dia --persona yan cmd ...`
+  - `yan-task` → `dia-job`
+
+## 还没完成
+
+| # | 缺口 | 影响 | 下一步 |
+|---|---|---|---|
+| 1 | ✅ dsh host 已补：`platform/dsh/yan-persona`（端口 3091），`doctor` preset 可加载 | — | — |
+| 2 | `yan-env` 仍是旧实现 | 凭据注入仍走旧脚本，未接 `dia env`（`dia env list/check/run` 已可用，白名单/redact/不进 argv） | 评估 `dia env` 后 shim/迁移 |
+| 3 | `yan-version` / `yan-ref` 仍是旧实现 | `dia persona show/use/path` 已覆盖"生效版本"；旧脚本未收口 | 按 `active-ref-design.md` 的剩余消费方迁移 |
+| 4 | `yan-data-root` / `yan-data-sync` 仍是旧脚本 | 数据根契约未统一（`dia` 的 scope 已能注入 `DIA_DATA_ROOT_SCOPE`） | 评估是否进 dia 或保留域脚本 |
+| 5 | 本地 untracked `scripts/yan-kb|yan-task|yan-worktree` | 旧文件仍可能被误用 | 观察一轮后删除，统一走 shim |
+| 6 | 仓库 README/rules 仍写旧命令 | 文档与 AGENTS 漂移 | 批量改 `yan-kb`→`dia --persona yan kb`、`yan-worktree`→`dia wt` |
+| 7 | ✅ launchd 已复核：清 `--help`/`demo-isolated`，selfcheck 指向稳定 shim | 缺失 0；`dia job list` 无测试残留 | — |
+| 8 | `dia persona check` 显示 local-only | 未跟踪上游 commit | 需要上游 ref/更新策略 |
+| 9 | **安装落后来源仓**：persona 装的是 `83fbaa9`，`~/.yan-agent/repos/yan-agent` main 已是 `8d10cc5` | 差的提交是 dsh profile 根 `cordis.yml` 修复 | `dia persona add yan --from ~/.yan-agent/repos/yan-agent --force`（先备份） |
+
+## 本机验证命令
+
+```sh
+dia persona list
+dia persona show yan
+dia doctor --persona yan
+dia --persona yan kb scene S1
+dia --persona yan kb query "评审请求"
+dia --persona yan cmd mr --help
+dia wt status
+dia job list
+```
+
+## 原则
+
+- 不再恢复 legacy-yan-cli；已经切到 dia。
+- 旧命令只保留稳定 shim，不直接依赖仓库里的 untracked 文件。
+- 每次迁移一项，跑上面的验证命令，不一次改完。