@minonl/dia 0.0.15 → 0.0.16

package/docs/design/graph-web.md

@@ -1,5 +1,8 @@
 # dia graph Web 视觉设计稿（v0.3）
 
+> **落地状态（2026-11-06）**：M1 已实现 `dia graph --export-html`（真实账本 → 单文件静态 HTML，无网络）；
+> 数据模型/契约/安全边界见 [graph-web-m1.md](graph-web-m1.md)。live 服务（M2）未做。
+
 > 静态 mockup：[`graph-web-mockup.html`](graph-web-mockup.html)（浏览器直接打开，无网络/无依赖）
 > 数据契约：`dia graph --json`（schema 1）；时间线所需 start/end 为后续扩展字段。
 
@@ -144,10 +147,12 @@ mockup 数据改为 **100 个任务、时间跨度 30 天**，用来验证真实
 
 - **时间窗（默认近 7 天，按开始时间，结束时间不限）**：只显示 `start >= 今天 - N` 的任务，
   长任务即使结束在很久以后也照常显示；时间线轴自动从 `-N` 延伸到最晚的 `end`；
-- **搜索**：聚焦输入框就出下拉（空时列出当前可见任务，按优先级/开始时间排序），输入 ID / 名称 / owner 实时过滤；
-  `↑↓` 选择、`Enter` 聚焦、`Esc` 清空；命中卡片高亮描边、其余置灰，下拉项点击也可聚焦；
-- **聚焦（类 nx graph focus）**：双击卡片或点搜索结果 → 只保留该任务的依赖邻域，
-  芯片可切 `1 层 / 2 层 / 全链路`，「退出」回全量；聚焦状态写进 URL（`focus=t-003&fd=2`）；
+- **搜索即选择（token 输入框）**：聚焦就出下拉（列出当前时间窗全部任务，按优先级/开始时间排序），
+  输入 ID / 名称 / owner 实时过滤；选中项**回显成 tag**（`t-003 ×`）留在输入框里，可多选；
+  `↑↓` 选择、`Enter` 加入、`Esc` 收起、`Backspace` 删除最后一个 tag、点 `×` 删除单个；
+  已选 tag 用蓝底高亮，下拉里带 `✓`；选择状态写进 URL（`sel=t-003,t-006`，向后兼容旧的 `focus=`）；
+- **邻域聚焦（类 nx graph focus）**：选中任务后只保留这些任务的依赖邻域（多个取并集），
+  深度可切 `1 层 / 2 层 / 全链路`，`清空` 回全量；双击卡片等同于点选该任务；
 - 被过滤掉的任务不计入概览统计，标题显示 `显示 N / 总数`。
 
 ## 11. 时间线滚动与缩放

package/docs/design/seat-scheduling-m2.md

@@ -0,0 +1,138 @@
+# 固定席位 + 上下文亲和（M2 设计）
+
+> 状态：设计定稿（2026-11-06，未实现）｜依赖：`graph-prio-dag.md`（eff/rank）、`graph-ui-m1.md`（面板）
+> 红线：**只读建议；不写 tasks 账本、不常驻守护、不抢占、不自动 force 接管**。
+
+## 1. 目标 / 非目标
+
+**目标**：席位（并发会话）数量固定时，回答「每个席位现在接哪件」——同时考虑价值（rank）、约束（依赖/claim）与**断链成本**（上下文）。
+
+**非目标**：自动领取/自动开工；跨机席位发现；任务级分布式锁；把 rank 变成门禁。
+
+## 2. 名词与事实源
+
+| 名词 | 定义 | 事实源 |
+|---|---|---|
+| seat | 一个在线会话（opencode/dsh 进程） | `~/.dia/collab/sessions/*.json` 的 `last_seen` |
+| presence | `now - last_seen <= TTL`（默认 30m，`--presence-ttl`） | 同上 |
+| claim | **路径**租约（谁在改哪个文件） | `~/.dia/collab/claims.jsonl`（TTL 默认 4h） |
+| owner | 任务声明的负责人（不发租约） | `tasks/ledger.jsonl` 的 add/plan |
+| busy | 席位有 `doing` 任务 | 任务 status |
+| 亲和 | 任务与该席位近期工作面的重叠度 | 任务 touches + 席位最近任务 |
+
+**分工写死**：`rank` 只回答「先做什么」；`claim` 只回答「谁能改哪条路径」；`owner` 只回答「谁负责」，三者不得互相替代。
+
+## 3. 席位状态机（全派生，零写入）
+
+```
+        online & 无 doing            online & doing(todo/doing)
+   ┌──────── idle ◄────────┐        ┌──────── busy
+   │                       │        │
+   │  (接新任务即 busy)     └────────┤
+   └──────── holding ◄──────┘   doing 但 status∈{review,blocked}（释放执行位，保留上下文）
+                 │
+          last_seen 超 TTL
+                 ▼
+              offline（不再分配；其 doing 任务标 stale，需人确认）
+```
+
+- `holding` 仍可接新任务（执行位空闲），但提示「上下文占用 N 个」；N>3 建议先 handoff；
+- `offline` 的 `doing` 任务**回候选集**但标 `reason:'seat_offline'`，不自动改 status/owner；
+- 无自动回收路径：busy→idle 只在任务状态变化时派生，进程退出即 offline（靠 TTL）。
+
+## 4. 亲和度（affinity）
+
+```
+aff(t, seat) = 3 * ownerMatch      # seat.session == t.owner
+             + 2 * splitGroup      # 与席位最近任务共享 split_from 或同一父
+             + 2 * jaccard         # touches 的 Jaccard，[0,1]，0/0 = 0
+             + 1 * moduleOverlap   # 路径前 2 段前缀相同
+cost(t, seat) = 1 - aff/8            # ∈ [0,1]，越小越省
+```
+
+- `seatTouches` = 该席位最近 H=5 个任务（doing/review/done）的 touches 并集；
+- 分量量纲固定：owner/split/module 为 0/1，jaccard 归一化到 [0,1]；`aff` 最大 8；
+- **算例**（必须进单测）：
+
+| 场景 | aff | cost | 结论 |
+|---|---|---|---|
+| 同 owner（3） | 3 | 0.625 | 可接，但不算强亲和 |
+| 同 split 组（2）+ jaccard 0.5（1） | 3 | 0.625 | 同上 |
+| 同 owner + 同模块（4） | 4 | 0.5 | 达到「续做」阈值 |
+| 完全同 touches（jaccard=1，2） | 2 | 0.75 | 单靠路径重叠不续做 |
+| owner+split+jaccard1+module（8） | 8 | 0 | 强续做 |
+
+> 阈值：**续做** `cost ≤ 0.5`；**换人** 当 `cost > 0.5` 且存在另一席位 `cost 低 ≥ 0.25`。单靠「路径重叠」不足以免换人——避免把不相关任务硬塞给同一席位。
+
+## 5. 分配算法（rank 优先，亲和定席位）
+
+```
+候选 = startable ∧ rank≠null ∧ 无「路径 claim 冲突」
+对候选按 rank 升序：
+    在空闲/持有席位中，选 (cost, seat.id) 最小者
+    若该席位 busy → 跳过（不抢占）
+输出 assignments；未被分配的进入 unassigned，带原因
+```
+
+- 复杂度 `O(N·S)`（N 候选、S 席位），500×3 < 1ms；
+- 确定性 tiebreak：`(cost, declared prio index, task.id, seat.id)`；
+- **不做**「全局最优分配」：席位小、账本变动频繁，贪心 + 可解释优先；
+- 显式反例（写入文档，防止误读）：rank 1 但亲和极差的任务仍会被先分配——这是「价值优先」的代价；若需要「上下文优先」模式，M3 再加 `--by=affinity`。
+
+## 6. CLI 契约
+
+```bash
+dia graph --next [n] --seats 2 --presence-ttl 30m --now 2026-11-06T10:00:00 --json
+```
+
+```json
+{
+  "schema": 1,
+  "policy": "seats-v1",
+  "seats": [{"seat":"ses_a","state":"idle","presence_at":"2026-11-06T09:58:12Z","focus":null}],
+  "assignments": [{"seat":"ses_a","task":"t-3c1f","rank":1,"eff":"P0","cost":0.25,"affinity":{"owner":1,"split":0,"jaccard":1,"module":0},"why":"同 owner + 路径重叠 1.0"}],
+  "unassigned": [{"task":"t-9","rank":4,"reason":"no_seat|seat_offline|claim_conflict"}],
+  "conflicts": [{"task":"t-9","kind":"claim_overlap","detail":"src/x.ts 被 ses_b claim"}],
+  "metrics": {"switches": 1, "handoff_rate": 0.0, "idle_slots": 0}
+}
+```
+
+- **不含墙钟**：只出 `presence_at`（ISO）；`--now` 仅用于计算 state/交接判断，不落输出；
+- 同一 `--now` + 同一账本 → 字节相等；打乱任务顺序结果不变；
+- 退出码：0 正常（含无任务）、2 参数错、3 依赖环（排序不可用）。
+
+## 7. 链式续做与 handoff
+
+默认**续做**（cost ≤ 0.5 且席位非 busy）。**必须打断**的四条：
+1. 出现更高 `rank` 且其它席位都接不住的任务（价值让位）；
+2. 下一环 touches 与席位工作面**无重叠**（模块切换，cost > 0.5）；
+3. 当前任务进入 review/blocked（执行位空出，可换手）；
+4. 上下文将满（启发式：本会话完成任务数 ≥K 或已有 1 次 handoff 建议）。
+
+handoff 内容固定五段：目标状态 / 已完成 / 未完成 / 触碰文件 / 下一步命令；通道用 `dia msg send --kind handoff`，交接后**人工重新 claim**，不自动转移。
+
+## 8. 指标（只读派生）
+
+- `switches`：同一任务换席位的次数；
+- `handoff_rate`：有 handoff 消息的任务 / 被接手任务；
+- `idle_slots`：在线但无任务的席位数；
+- 采样窗口由调用方传 `--since`，不落账本；用于评估「固定席位是否够用」。
+
+## 9. 边界
+
+- **claim 与 presence 冲突**：claim 4h 有效但会话 30m 离线 → 标 `conflicts: claim_held_offline`，任务进 unassigned 且**不自动 force**（人工 `dia claim --force` 或等 TTL）；
+- 席位掉线：`offline`，其任务回候选并标 stale；
+- S > 任务数：多余席位 idle，不为填满降低门槛；
+- S=0：纯建议模式，全量 unassigned，exit 0；
+- 跨机：只读本机 `~/.dia`，其它机器会话视为离线；
+- 空 touches：jaccard=0，不除零；
+- 环内/终态任务不进候选。
+
+## 10. 验收
+
+- 打乱任务顺序、固定 `--now` 两次输出字节一致；
+- busy 席位不被二次分配；holding 可接新任务；
+- affinity 五个算例硬断言（含 0/0）；
+- claim 冲突进 conflicts 且不抢占；
+- `--seats 1` 与 `graph --next` 单项一致（同一排序源）；
+- e2e：两会话（`DIA_SESSION_ID`）跑 `whoami` + doing → 各得一任务；杀一个会话超 TTL 后任务回落。

package/docs/index.md

@@ -17,7 +17,9 @@ Agent 入口：[`llms.txt`](https://github.com/minonl/dia/blob/main/llms.txt)（
 | [用户入口：人在哪进，agent 叫什么](entrypoints.md) | 一句话：入口仍是 opencode/dsh（和 yan 一样），但 agent 名是 dabo，不是 dia；dia 是控制面命令，不是人格。 |
 | [进化：dia 的第一性定位](evolution-process.md) | 本文不是功能清单，是过程定义。 |
 | [宿主控制面：黑盒边界与内部 seam（2026-10）](host-control-surface.md) | 问题：把 opencode（含 v2）与 dsh 当"黑盒宿主"时，我们能在哪些边界上控制它们？ |
+| [安装防呆：脚本安装不许抢走 npm 全局安装](install-guard-design.md) | 日期：2026-11-06 ｜ 状态：已实现（D0.65） ｜ 触发：同一台 Linux 机器 3 次出现 ~/.local/bin/dia 被指回脚本安装 |
 | [Kit：内容包安装（persona 的第二个半边）](kit-install.md) | 前置：docs/persona-install.md（persona = 人格，kit = 内容）。 |
+| [Kit 层：把「经验」从 persona 里抽出来（设计 v0.1）](kit-layer.md) | 2026-11-06 用户定调：dws-hub 作为 channel 层重构，同时把 git / node 这类通用工程经验抽成 kit 层， |
 | [模型基准与 Sidecar 监控（A+B 一起）](model-baseline-sidecar.md) | A：首次使用先跑基准，用数据决定配置。 |
 | [模型行为调控（客户端侧）](model-behavior.md) | 边界（用户定）：只使用各平台提供的通用模型；不做本地构建/微调；不依赖多数模型不支持的推理与输入输出控制参数； |
 | [dia monorepo：框架模块的归属](monorepo.md) | 结论：dia-job 回 dia monorepo，作为 packages/job；kb 作为 packages/kb。 |
@@ -92,5 +94,10 @@ Agent 入口：[`llms.txt`](https://github.com/minonl/dia/blob/main/llms.txt)（
 
 | 文档 | 一句话 |
 |---|---|
-| [dia graph Web 视觉设计稿（v0.3）](design/graph-web.md) | 静态 mockup：graph-web-mockup.html（浏览器直接打开，无网络/无依赖） |
+| [优先级 × 依赖：任务编排语义（M1）](design/graph-prio-dag.md) | 状态：已实现（2026-11-06）｜代码：src/plan.ts（派生纯函数）、src/task.ts（split）、src/graph.ts（契约） |
+| [关系图界面：派生量上屏（M1 UI）](design/graph-ui-m1.md) | 状态：设计定稿（2026-11-06）｜实现：src/graph-html/（待接）｜上游：graph-prio-dag.md |
+| [dia graph Web（M1）设计：真实数据 → 单文件静态导出](design/graph-web-m1.md) | 状态：M1 设计（2026-11-06）｜前置：graph-web.md（视觉稿 v0.3）、graph-web-mockup.html（交互原型） |
+| [graph live 服务（M2 设计，可选包）](design/graph-web-m2.md) | 状态：设计定稿（2026-11-06，未实现）｜前置：graph-web-m1.md（静态导出）、graph-ui-m1.md、seat-scheduling-m2.md |
+| [dia graph Web 视觉设计稿（v0.3）](design/graph-web.md) | 落地状态（2026-11-06）：M1 已实现 dia graph --export-html（真实账本 → 单文件静态 HTML，无网络）； |
+| [固定席位 + 上下文亲和（M2 设计）](design/seat-scheduling-m2.md) | 状态：设计定稿（2026-11-06，未实现）｜依赖：graph-prio-dag.md（eff/rank）、graph-ui-m1.md（面板） |
 

package/docs/install-guard-design.md

@@ -0,0 +1,148 @@
+# 安装防呆：脚本安装不许抢走 npm 全局安装
+
+> 日期：2026-11-06 ｜ 状态：**已实现（D0.65）** ｜ 触发：同一台 Linux 机器 3 次出现 `~/.local/bin/dia` 被指回脚本安装
+> 上游：三名独立子会话的 grill（架构/契约、红队、兼容迁移），结论一致 ｜ 判据：`bash tests/install-guard.test.sh`
+
+---
+
+## 1. 现象与根因
+
+**现象**：`~/.local/bin/dia` 从 npm 包 bin 被改成 `~/.local/share/dia/bin/dia.js`，随后：
+
+- `paths.installDir()` 按 `import.meta.url` 反推安装根 → 落在脚本安装目录
+- 内置能力包 `kits/dia-msg` 去旧目录找 → `missing-kit` / `E_KIT_EMPTY`
+- `dia doctor` 红、`dia update` 走脚本模式（自己 `git pull && bun run build && bash install.sh`，再抢一次）
+
+**根因**：`install.sh` 第 58 行 **无条件** `ln -sfn "$DIA_INSTALL_DIR/bin/dia.js" "$DIA_BIN_DIR/dia"`。
+两种安装共存本身不是错误（npm 可以装在别的 prefix），错误是**后来者覆盖了正在生效的那条链接**。
+
+```mermaid
+graph LR
+  A[install.sh 运行] --> B{目标 bin 现在指向谁}
+  B -->|npm 包 bin| C[拒绝 exit 3<br/>不动任何文件]
+  B -->|脚本安装 / 不存在| D[正常安装]
+  D --> E[打印实际生效的 dia + version]
+  E --> F{生效路径 == 目标?}
+  F -->|否| G[warn：不在 PATH 或 PATH 顺序靠后]
+```
+
+## 2. 被否掉的初版方案
+
+初版设想是「检测到 npm 全局包存在就拒绝」。grill 三方一致否掉，理由：
+
+| 问题 | 证据 |
+|---|---|
+| 两种安装可以合法共存 | 本机 `npm prefix -g` 有 `@minonl/dia`，同时 `~/.local/bin/dia` 是脚本安装，两者并存且脚本版更新 |
+| npm 包可能是**旧残留** | npm 0.0.13 + 脚本 0.0.15 时，拒绝安装等于**永久锁死升级** |
+| 多 Node 前缀 | fnm/nvm 切版本后 `npm ls -g` 结果就变，检测不稳定 |
+| 依赖 npm 命令 | 无 npm 的容器/离线场景会误伤；且 `npm ls` 有 0.5s 启动成本 |
+
+## 3. 决定（三条）
+
+**D1 判据 = 抢链接，不是「包存在」**
+
+```
+pkgOwned(p)：三种形态任一命中即算包管理器全局安装
+  A 软链/拷贝：逐级解析符号链接后，真实路径匹配 (/|\\)node_modules(/|\\)@minonl(/|\\)dia
+  B shim 脚本：目标文件不是软链，内容含 @minonl/dia 或 node_modules/(@minonl/)?dia/
+  C 二进制 shim：所在目录是已知包管理器全局 bin（~/.volta/bin、PNPM_HOME 等）
+```
+
+只在这些情况拒绝（且该路径正是 `command -v dia` 会命中的那条）：
+
+1. `$DIA_BIN_DIR/dia` 的 realpath 落在 `node_modules/@minonl/dia`（npm / bun 全局安装）；
+2. bin 是 **shim 脚本/拷贝**且内容带包路径（pnpm / yarn-berry）；
+3. bin 所在目录属于已知包管理器全局 bin（volta 这类不含包路径的同名 shim）。
+
+包存在但 bin 未被占 → **只 warn 一行，继续安装**。
+
+> 红队回灌（2026-11-06，实现后）：`--home` 独占**不算**沙箱（链接仍写默认 bin，守卫照旧生效）；
+> 链接落位失败必须退 1（不再谎报装好）；`--migrate` 改为**只搬数据**（不装、不改 bin）。
+
+> 为什么要有 B/C：pnpm / yarn-berry / volta 的全局 bin 是 **shim 脚本或同名二进制**，不是指向
+> `node_modules/@minonl/dia` 的软链。只认软链时守卫会把这些安装判成「脚本安装」并静默覆盖，
+> 事故形态与 npm 完全一致（本仓库 packageManager 就是 pnpm）。
+
+**D2 退出码 3 + 显式逃生舱**
+
+| 码 | 含义 |
+|---|---|
+| 0 | 装好（含「已警告但仍安装」） |
+| 1 | 前置缺失（缺 `dist/cli.js` / `bin/dia.js`） |
+| 2 | usage |
+| **3** | **守卫拒绝：未改动任何文件**（可安全重试，重试必然同样结果） |
+
+放行条件（任一命中即跳过守卫）：
+
+- `DIA_ALLOW_SCRIPT_INSTALL=1`（人类显式意图）
+- `--dry-run`（只演练）
+- **生效 bin 目录被重定向**：`--bin DIR` / `DIA_BIN_DIR=DIR`，且不等于默认 `~/.local/bin`
+
+> **只改安装目录不算沙箱**（`--home` / `--install-dir` / `DIA_INSTALL_DIR` / `DIA_HOME_INSTALL`）：
+> 链接仍写在默认 `~/.local/bin/dia`，照样会抢走生效安装，守卫必须照旧生效（exit 3）。
+> 想要「不碰生效路径」的沙箱，必须同时指定 `--bin`。
+
+**D3 `dia update` 不硬失败**
+
+脚本模式下**保持现状**（打印升级指引、exit 0），不升级为错误：否则「脚本安装的机器」会彻底无法升级，且 CI 里 `update` 测试会红。只加一条：若检测到 npm 包与当前安装不一致，多打印一行 `dia doctor` 提示。
+
+## 4. 配套
+
+**D4 安装后自检**：`install.sh` 结束时打印
+
+```
+dia installed: <install dir> → <bin dir>/dia
+effective: <realpath of $(command -v dia)> (<version>)
+```
+
+生效路径 != 目标时 warn（这正是「npm 装到不在 PATH 的 prefix」的可见化）。
+
+**D5 `dia doctor` 新增 `install_shadow`（fail）**
+
+判定：`installDir()` 不是包管理器安装 + `command -v dia` 解析到包管理器安装（或反过来）→ 报不一致，附修复命令。
+包管理器安装的 bin 是 shim（pnpm/yarn）时按脚本内容识别，不只看 realpath：
+
+```bash
+ln -sfn "$(npm prefix -g)/bin/dia" ~/.local/bin/dia
+```
+
+**D6 原子写**（低成本顺带）：`cp` 落 `<file>.tmp` 再 `mv -f`；`ln -sfn` 改「先建临时链接再 rename」，避免并发会话看到半截文件/短暂无命令。
+
+## 5. 失败模式（红队保留项）
+
+| 场景 | 处理 |
+|---|---|
+| npm 包在别的 Node 前缀 | 不检测 npm 列表，只判真实路径 → 天然不受影响 |
+| pnpm/yarn/bun/volta 全局装 | 软链看 realpath（`node_modules/@minonl/dia`）；shim 看内容（`@minonl/dia`）；volta 二进制 shim 看全局 bin 目录归属 |
+| 只改安装目录当沙箱 | 不算沙箱：链接仍写默认 bin，守卫照旧 exit 3；沙箱必须重定向 `--bin`/`DIA_BIN_DIR` |
+| `readlink -f` 在 macOS 不存在 | 用 `cd "$(dirname x)" && pwd -P` 逐级解析，两边同构 |
+| 本机测试被守卫误拦 | 测试全部用临时 `DIA_INSTALL_DIR` + 临时 `DIA_BIN_DIR`（= 沙箱放行），不探测真机环境；只给安装目录的用例应得 rc=3（`tests/install-guard-strict.test.sh` ①） |
+| 上层脚本把 exit 3 当致命 | 文案给出三条出路（显式放行 / 回 npm / 换 `--bin` 沙箱）；`docs/` 里所有 `bash install.sh` 用法补注「默认路径已被包管理器占用时会拒绝」 |
+| 老版本 dia 没有防呆 | `doctor install_shadow` 负责发现，修复命令一条 |
+
+## 6. 判据（可执行）
+
+```bash
+# 1) 目标 bin 被包管理器占用（**默认路径**）→ 拒绝，且链接字节不变
+#    自动化等价物：tests/install-guard.test.sh ①（临时 HOME + 临时 PATH + 伪 npm 包）
+# 1b) shim 形态（pnpm/yarn/volta）→ 同样拒绝；只改安装目录（--home 等）→ 同样拒绝
+#    自动化等价物：tests/install-guard-strict.test.sh ①②
+# 2) 真沙箱（**bin 目录**被重定向）→ 放行
+DIA_INSTALL_DIR=/tmp/x DIA_BIN_DIR=/tmp/xbin bash install.sh; test $? -eq 0
+# 3) npm 包存在但 bin 未被占 → warn 但安装（install-guard.test.sh ③）
+# 4) doctor：真实路径与 installDir 不一致 → install_shadow fail
+dia doctor | grep -q install_shadow
+# 5) npm 安装的机器上：installDir 含 node_modules/@minonl，且 kits/dia-msg 可解析
+dia doctor --paths | grep -q 'node_modules/@minonl'
+```
+
+## 7. 不做的
+
+- **不做 `dia install repair`**：新增命令面大于收益；doctor 给一行可复制命令即可。
+- **不改 `dia update` 退出码语义**：`--check` 的 0/1 语义保持不变。
+- **不引入 npm 依赖检测**（`npm ls -g` / `npm prefix -g`）：确定性优先。
+
+## 8. 文档同步
+
+`README.md`（安装章节）、`docs/cli.md`（`doctor` 检查项）、`docs/kit-install.md`（install.sh 分发说明）、
+`docs/status.md`（新增条目）、`docs/index.md` + `llms.txt`（新文档索引，改完跑 `npm run docs:index`）。

package/docs/kit-install.md

@@ -30,6 +30,13 @@
 
 结论：**persona 装完是"哑"的**；kit 就是把这些补上，且要能 `verify` / `remove`。
 
+> **install.sh 分发守卫（2026-11-06）**：`~/.local/bin/dia` 当前属于包管理器全局安装
+> （npm/bun 的 `node_modules/@minonl/dia` 软链、pnpm/yarn 的 shim 脚本、volta 的 bin）且正是 `command -v dia`
+> 命中的那条时，`install.sh` **exit 3 且不改动任何文件**（避免脚本安装抢链接后 kit 去旧目录找、
+> `missing-kit` / `E_KIT_EMPTY`）。逃生舱：`DIA_ALLOW_SCRIPT_INSTALL=1`、`--dry-run`，
+> 或**把生效 bin 目录重定向**（`--bin DIR` / `DIA_BIN_DIR=DIR`）。注意：`--home` / `DIA_INSTALL_DIR`
+> 只改安装目录，链接仍写默认 `~/.local/bin`，**不算沙箱**（守卫照旧生效）。包存在但 bin 未被占 → 只 warn 一行。
+
 ---
 
 ## 2. 清单：`dia.json`（kind=kit）

package/docs/kit-layer.md

@@ -0,0 +1,78 @@
+# Kit 层：把「经验」从 persona 里抽出来（设计 v0.1）
+
+> 2026-11-06 用户定调：dws-hub 作为 **channel 层**重构，同时把 git / node 这类**通用工程经验**抽成 **kit 层**，
+> 让 yan-agent 更薄、更专业，dabo 等其它 persona 直接复用。本文定 kit 的边界、清单、检索、治理与迁移顺序。
+
+## 0. 三层模型
+
+| 层 | 回答的问题 | 例子 | 归属 |
+|---|---|---|---|
+| **persona** | 你是谁、怎么干活（身份/语气/工作流编排） | yan、dabo | 各自 persona 仓 |
+| **kit** | 你会什么（可复用的经验、工具、知识页） | `kit/git`、`kit/node`、`kit/compose-delivery` | kit 源仓 / registry |
+| **channel** | 消息怎么进出 | dws-hub（钉钉 channel+） | dws-hub 仓 |
+
+约束：
+
+- kit **不带人格**、不写人设与语气；只放「换个 agent/换个人也用得上」的内容。
+- persona 只保留：身份、规则（must/must-not）、流程编排、**对 kit 的引用**。
+- channel 只管传输与协议，不承载业务经验。
+
+## 1. 双标签：一份内容、多领域可检索
+
+同一条经验经常跨领域（本次实例：hook manager 共存 = git × node）。做法：
+
+- kit 清单与知识页 front-matter 都支持 `tags: string[]`；
+- 检索按 tag 命中**同一份内容**，不复制两套；
+- tag 命名：`git` / `node` / `pnpm` / `hooks` / `worktree` / `channel` / `delivery` …（扁平，不做层级）。
+
+示例：
+
+```json
+{ "id": "git", "version": "0.1.0", "tags": ["git", "worktree", "hooks"], "knowledge": ["knowledge/**"] }
+```
+
+## 2. 清单（`dia.json`，kind=kit）增量
+
+在现有字段（files / skills / bin / dirs / commands / knowledge / data_root / requires）上新增：
+
+| 字段 | 说明 |
+|---|---|
+| `tags: string[]` | 检索标签（双/多标签） |
+| `provides: string[]` | 提供的知识主题（供 persona 引用与 doctor 校验，如 `git.hooks`） |
+| `requires: { "<kit>": "<semver>" }` | 依赖其它 kit（如 `dingtalk` requires `node`） |
+
+## 3. 检索：kb 必须同时搜 persona KB 与已装 kit
+
+现状：`dia kb` 只索引 persona 自带 knowledge。抽 kit 后若不同时索引 kit，会出现「装了解析不到」的假空。
+
+要求：
+
+- `dia kb query --tag git "hook"` → 命中 persona KB + 所有已装 kit 的 knowledge；
+- 结果标注来源（`persona:yan` / `kit:git@0.1.0`），便于追踪；
+- 0 命中时显式告警（沿用现规则，别当「没有知识」）。
+
+## 4. 治理（doctor）
+
+| 检查 | 级别 |
+|---|---|
+| kit 已安装且版本满足 persona 的 `requires` | FAIL |
+| kit 内容哈希与 lock 一致（drift） | FAIL（可 `dia kit verify` 修复） |
+| kit 声明的 bin/skills/files 落点仍在 | FAIL |
+| tag 索引与实际知识页 front-matter 一致 | WARN |
+| 同一 tag 下存在重复内容（hash 相同） | WARN（提示合并） |
+
+## 5. 迁移顺序（小步，不搬家式重写）
+
+1. **P0**：本设计 + `dia kit` 支持 `tags`（本 PR）
+2. **P1（pilot）**：抽 `kit/git` 与 `kit/node`
+   - `kit/git`：worktree 纪律、adopt/doctor/gate、守卫模型、对外无逃生口原则
+   - `kit/node`：pnpm 11 `allowBuilds`、lockfile 最小变更、frozen-lockfile、hook manager（husky→simple-git-hooks）
+   - 交叉页（hook manager 共存）挂在 `kit/git`，`tags` 双写 `[git, node, hooks]`
+3. **P2**：yan-agent 变薄 —— git/node 页面移入 kit，persona 只留身份 + 工作流 + 索引；`install.sh` 改 `dia kit add <src>`
+4. **P3**：dabo 装同一套 kit，验证「换 persona 不换经验」；doctor 校验 kit 版本约束
+
+## 6. 非目标
+
+- 不做 kit 市场/评分；kit 来源先支持 git ref 与本地路径。
+- 不把 persona 规则（must/must-not）塞进 kit —— 规则仍归 persona，kit 只提供「怎么做」与「踩过什么坑」。
+- channel 层不因 kit 化而承担知识分发。

package/docs/migrations/data-root-2026-11.md

@@ -9,7 +9,7 @@
 # 1) 备份（可选但建议）
 mv ~/.local/share/dia ~/.local/share/dia.bak-$(date +%Y%m%d)
 
-# 2) 用新安装器迁（自动 mv 旧根 → ~/.dia 并装新版）
+# 2) 用新安装器迁数据（只 mv 旧数据根 → ~/.dia；不装、不改 bin 链接）
 cd ~/repos/github/dia
 bun run build
 bash install.sh --migrate
@@ -52,9 +52,10 @@ tar czf ~/backups/dia-job-$TS.tgz -C ~ .local/share/dia-job
 crontab -l > ~/backups/crontab-$TS.txt
 # 把所有 `dia-job:` 行注释掉（记下原样，后面恢复）
 
-# 1) 装新版 + 迁数据（只搬数据子目录，不动安装物）
+# 1) 只迁数据（2026-11-06 起 --migrate 不再顺带安装/改 bin 链接，避免抢走 npm 安装）
 #    源码来自 mac 构建产物：tar 传 bin/dist/packages/docs/install.sh/package.json
 bash install.sh --migrate
+# 装新版走 npm（推荐）：npm i -g @minonl/dia@latest
 
 # 2) cache（install.sh 不搬）
 mkdir -p ~/.dia/cache && [ -d ~/.cache/dia/index ] && mv ~/.cache/dia/index ~/.dia/cache/

package/docs/status.md

@@ -28,6 +28,7 @@
 | `history/framework-bootstrap.md` | 早期启动与分发选型（已归档） | **归档**：方案未采用，实际分发是 `install.sh`，不要按它部署 |
 | `entrypoints.md` | 用户入口矩阵 | **部分过时**：终端 dabo preset 已渲染；IM bridge 未写；`dia status` / `dia model` 不存在 |
 | `kit-install.md` | kit 清单、渲染、生命周期 | **设计**：实现只有 `add/list/verify/remove`；`show/update/gc/create` 未做 |
+| `install-guard-design.md` | **安装防呆**：脚本安装 vs npm 全局安装的抢链接判据、exit 3 逃生舱、`doctor install_shadow` | **实现**（D0.65 + `tests/install-guard.test.sh`） |
 | `patching.md` | 本地 patch | **未实现**（`unknown command`） |
 | `team-automation.md` | 计划→实现→验证全自动循环 | **未实现**（D0.6–D0.9 只跑通 mock / ACP 驱动） |
 | `proposals.md` | `team next` 目标候选 | **v0 已实现**（`dia team next`，纯规则打分） |
@@ -90,6 +91,7 @@
 | D0.21 | worktree 抽取 `packages/wt` | **完成** | 7 处 python→node；`dia wt`；4 套测试原样迁移全绿 |
 | D0.23 | doctor 平台版本自检 | **完成** | `platform:opencode` / `platform:dsh` 报版本（缺宿主 = warn，不判红）；`tests/active-doctor.test.ts` |
 | D0.44 | 配置迁移走 LLM 任务 | **完成** | `docs/migrations/llm-migration.md`：升级只改声明；迁移=任务+判据+回滚；禁止代码里堆版本分支（安全敏感/原子场景例外） |
+| D0.65 | 安装防呆：脚本安装不抢包管理器全局安装 | **完成** | `install.sh` 守卫（目标 bin 属于包管理器全局安装且为 `command -v dia` 命中项 → exit 3，零改动）：npm/bun 软链看 `node_modules/@minonl/dia`，pnpm/yarn shim 看内容，volta 看 bin 目录；放行 = `DIA_ALLOW_SCRIPT_INSTALL=1` / `--dry-run` / **bin 目录被重定向**（`--home` 等只改安装目录不算沙箱）；装完打印 `effective:`；`doctor install_shadow` 双向一致判定（含 shim）；`tests/install-guard.test.sh` + `tests/install-guard-strict.test.sh` |
 | D0.64 | 复制过滤按相对路径判断 | **完成** | 绝对路径匹配 `node_modules` 会误伤 npm 全局安装（kit 整树被过滤 → `E_KIT_EMPTY`）；改 `copyFilter(base)` 用相对路径，persona/kit 共用 |
 | D0.63 | 运行时数据 `.data/` 不进快照、不参与哈希 | **完成** | `TREE_SKIP`（kit/persona 共用）：安装复制与 `hashTree`/verify 都跳过 `.data`，防运行时写入造成 verify 假漂移 |
 | D0.62 | persona 旧版技能软链视为受管 | **完成** | `linkManaged` 同时认 `~/.dia/kits/**` 与 `~/.dia/personas/**`；`persona update` 升级不再需要 `--force` |

package/kits/git/dia.json

@@ -0,0 +1,10 @@
+{
+  "schema": 1,
+  "kind": "kit",
+  "id": "git",
+  "version": "0.1.0",
+  "root": ".",
+  "tags": ["git", "worktree", "hooks"],
+  "knowledge": ["knowledge"],
+  "requires": { "dia": ">=0.0.2" }
+}

package/kits/git/knowledge/hooks.md

@@ -0,0 +1,30 @@
+---
+title: hook 模型与管理器共存（git × node）
+tags: [git, node, hooks]
+---
+
+# 守卫钩子与 hook 管理器共存
+
+## 三种模式（dia wt adopt 自动判定）
+
+| 仓类型 | 做法 | 效果 |
+|---|---|---|
+| 普通仓 | 钩子写 `<common>/dia/hooks`，仓库本地 `core.hooksPath` 指过去，并链式调用原钩子目录 | 守卫 + 原钩子都执行 |
+| simple-git-hooks 仓 | 不改 `.git/hooks` / `package.json`；守卫写进 `SIMPLE_GIT_HOOKS_RC`，由管理器钩子 source | install 不会覆盖守卫 |
+| 其它管理器（husky / `.githooks`） | 不抢占，doctor WARN | 守卫不生效，建议迁移 |
+
+## 为什么不能接管 simple-git-hooks
+
+它只读**仓库本地** `core.hooksPath`：有值就写到那里 → 一旦把 hooksPath 指向 dia 目录，`pnpm install` 就会把守卫文件覆盖掉。
+**正确做法是 RC 注入**：钩子模板会 `source "$SIMPLE_GIT_HOOKS_RC"`，守卫在那一步执行。
+
+## RC 自递归（已修复，务必保留标记）
+
+管理器钩子 → source RC → `dia wt guard` → 守卫末尾又链回 `<common>/hooks/<name>`（同一文件）→ 死循环，表现为 `git commit` 卡死。
+RC 必须 `export DIA_WT_IN_MANAGER_HOOK=1`，守卫看到标记只判定、不再链式。
+
+## husky → simple-git-hooks 迁移
+
+1. `.husky/*` 内容搬进 `package.json` 的 `simple-git-hooks` 配置；
+2. 删 `.husky/` 与 husky 依赖，加 `simple-git-hooks` devDependency + `"postinstall": "simple-git-hooks"`；
+3. 清理失效的本地 `core.hooksPath=.husky`，再 `pnpm install` 重建钩子。

package/kits/git/knowledge/worktree.md

@@ -0,0 +1,34 @@
+---
+title: worktree 纪律（adopt / doctor / gate）
+tags: [git, worktree, discipline]
+---
+
+# worktree 纪律
+
+## 一次性接管
+
+```bash
+dia wt adopt <repo>            # dry-run
+dia wt adopt <repo> --apply
+dia wt adopt --all --apply     # 仓根下所有主 checkout（跳过 *-worktree--*）
+```
+
+- 策略写在 `<git-common-dir>/dia/config.json`（defaultBranch / template / hooksManager）
+- 普通仓：钩子写 `<common>/dia/hooks`，仓库本地 `core.hooksPath` 指过去
+- simple-git-hooks 仓：走 `SIMPLE_GIT_HOOKS_RC`（见 hooks 页），不改仓内文件
+- **不写全局 git 配置**（外溢；D20 会检查残留）
+
+## 巡检与门禁
+
+```bash
+dia wt doctor <repo>... [--all] [--fix]
+dia wt gate <repo> <feature>     # 提 MR 前：check → doctor → 工作区干净 → ahead>0
+```
+
+判据要点：D01 配置 / D02 钩子或 RC 就绪 / D03 守卫探针 / D04 主 checkout 干净 / D05–D07 worktree 卫生 / D11 默认分支 / D20 全局残留 / D21 本地 hooksPath 与模式一致。
+
+## 纪律
+
+- 任何 git 改动先 `dia wt create`；主 checkout 只 `pull --ff-only` / 看代码。
+- 守卫没有「跳过」开关：钩子慢就先量化再优化（增量 lint、`nx affected`、缓存、下沉 CI）。
+- worktree 内依赖必须**真装**（R20）：跨 checkout 软链 `node_modules` 会让 pnpm 改写主仓链接，删 worktree 后整片悬空。

package/kits/node/dia.json

@@ -0,0 +1,10 @@
+{
+  "schema": 1,
+  "kind": "kit",
+  "id": "node",
+  "version": "0.1.0",
+  "root": ".",
+  "tags": ["node", "pnpm", "hooks"],
+  "knowledge": ["knowledge"],
+  "requires": { "dia": ">=0.0.2" }
+}

package/kits/node/knowledge/hook-managers.md

@@ -0,0 +1,17 @@
+---
+title: node 侧 hook 管理器（husky / simple-git-hooks）
+tags: [node, git, hooks]
+---
+
+# node 项目管理 git 钩子的两种主流方式
+
+| 方案 | 落点 | 特点 |
+|---|---|---|
+| husky v6+ | `.husky/`（提交进仓），`core.hooksPath=.husky` | 钩子内容进版本库，团队一键生效；但会覆盖任何外部 hooksPath |
+| simple-git-hooks | 生成到 `core.hooksPath`（默认 `.git/hooks`） | 配置在 `package.json`，`postinstall` 自动生成；有 `SIMPLE_GIT_HOOKS_RC` 注入点 |
+
+## 统一建议
+
+- 新仓/可改的仓：用 **simple-git-hooks**（配置集中、可被 RC 注入、不占 `.husky`）。
+- 已有 husky 的仓：按 git kit 的「husky → simple-git-hooks 迁移」执行；迁移属于提交改动，团队仓走 MR。
+- 任何情况下**不要**在主 checkout 用跳过开关绕钩子；钩子慢就优化（增量 lint / 缓存 / 下沉 CI）。

package/kits/node/knowledge/pnpm.md

@@ -0,0 +1,34 @@
+---
+title: pnpm 11 与构建脚本（allowBuilds）
+tags: [node, pnpm, ci]
+---
+
+# pnpm 11 要点
+
+## 构建脚本默认被忽略
+
+pnpm 10+ 默认不执行依赖的 `postinstall`。表现：
+
+- 本机：`ERR_PNPM_IGNORED_BUILDS`（退出码 1）
+- CI：`Job failed: command terminated with exit code 1`
+
+放行方式（**写在 `pnpm-workspace.yaml`**，pnpm 11 起 `package.json` 的 `pnpm` 字段不再读取）：
+
+```yaml
+allowBuilds:
+  simple-git-hooks: true
+```
+
+旧版本写法是 `onlyBuiltDependencies: ["simple-git-hooks"]`。
+
+## lockfile 只做最小增删
+
+团队仓加/删依赖时，别用新版 pnpm 全量重解析（会重写上万行、把无关依赖升级）：
+
+1. 手工改 `pnpm-lock.yaml`：`importers` 段 + `packages` 段 + `snapshots` 段各一处；
+2. 用 `pnpm install --frozen-lockfile`（不带 `--lockfile-only`）验证：通过即说明 lockfile 满足约束，且不会回写。
+
+## 其它
+
+- `pnpm install --frozen-lockfile` 是 CI 的硬门槛，本地也要真装（1~2s 很正常），不要用「借二进制」替代。
+- worktree 里安装依赖 = 在**该 worktree** 内安装，不要软链主仓 `node_modules`（见 git kit 的 worktree 页）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minonl/dia",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "type": "module",
   "description": "dia (嗲) — lightweight agent framework: knowledge index, audit, session ingest",
   "bin": {