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

package/docs/model-behavior.md

@@ -0,0 +1,229 @@
+# 模型行为调控（客户端侧）
+
+> 日期 2026-10-28。
+> **边界（用户定）**：只使用各平台提供的通用模型；**不做本地构建/微调**；**不依赖**多数模型不支持的推理与输入输出控制参数；
+> 所有调控都在**客户端本地**完成。
+
+---
+
+## 0. 一句话
+
+> 不改变模型，只改变**模型看到什么、能做什么、输出要被怎样验收**。
+
+模型是黑盒；我们能控制的是它的**输入契约、工具契约、输出契约和过程契约**。
+
+---
+
+## 1. 模型抽象（ModelSpec）
+
+```yaml
+model:
+  id: provider/name            # e.g. example/Kimi-K2.7-Code
+  contextWindow: int           # 必填，缺省按最小安全值（如 32k）
+  maxOutput: int               # 可选，缺省按窗口的 1/4
+  tools: bool|unknown          # 是否支持工具调用
+  json: bool|unknown           # 是否支持结构化输出
+  vision: bool|unknown
+  streaming: bool|unknown
+  cache: bool|unknown          # 前缀缓存
+  source: declared|probed|assumed
+  verified_at: ISO
+```
+
+**规则**：
+- `unknown` 一律按**保守值**处理（不支持/最小窗口），不许"应该支持"。
+- 能力来源必须记录（declared/probed/assumed）；`assumed` 不得进主路径。
+- 本机实测：dsh 只暴露 `contextWindow` / `maxTokens`；opencode CLI 不暴露能力矩阵 → 必须自建探测。
+
+**探测策略（已定）**：声明 + **首次使用探针**（一个极小请求，验证 tools/json/vision），结果写入 `model_fingerprints.jsonl`，缓存 **90 天**；探针失败 → 按不支持处理，不阻断主流程但记录 `degraded_reason`。
+
+**配套**：`docs/host-control-surface.md`（宿主边界）、`docs/model-baseline-sidecar.md`（基准与监控）。
+
+---
+
+## 1.1 五家对照（源码/官方文档，A 级）
+
+| 维度 | opencode | dsh | OpenClaw | Hermes | Pi |
+|---|---|---|---|---|---|
+| 模型目录 | models.dev（232 家）+ 兼容矩阵 | adapter 声明 + 发现接口 | model manifest | `(provider,model)→api_mode/key` | catalog + 覆盖 |
+| 能力字段 | tools/input/output/limit/cache 价 | contextWindow/defaultMaxTokens/inputModalities | contextTokens | 基础 | capabilities/context/cache |
+| 上下文 | AGENTS.md 就近+instructions | maxBytes + omitted/truncated marker | 稳定前缀/易变后缀 | stable→context→volatile | base+context+skills |
+| 工具 | 按启用条件注入指引 | `toolUpdate=addition-only`、失败带 code | **定义跨 turn 冻结** | registry 自注册 | codemode 3000 token 预算 |
+| 输出 | JSON schema 输入修复 | `INVALID_TOOL_OUTPUT` | 未验证 | 强制角色交替 | outputSchema，坏值失败 |
+| 重试 | 10 次，2/4/8→10s 封顶+jitter | per-provider normal 5 次 | auth 轮换/冷却→模型链 | 429/5xx 重试，401/403 立即 | 429/5xx，2/4/8s |
+| 缓存 | cacheKey + cacheFormat | 工具增量声明 | cache boundary + retention | system_and_3 断点 | promptCache short/long |
+| 按模型回归 | **未验证** | **未验证** | **未验证** | **未验证** | **未验证** |
+
+来源：opencode `model-compatibility.ts` / `tool-input-repair.ts` / `model-retry.ts`；dsh 本机源码；OpenClaw `prompt-caching` / `model-failover`；Hermes `prompt-assembly` / `context-compression-and-caching`；Pi `models.md` / `CHANGELOG`。均为 2026-10 · A。
+
+**结论**：五家在"能力表 + 分层前缀 + 工具契约 + 错误码重试"上收敛；差异在缓存语义。
+**空档**：没有一家公开"按模型跑 golden 回归"——这是 dia 的增量（H13/H14 与指纹）。
+
+---
+
+## 2. 六类杠杆（全部与模型无关）
+
+### L1 上下文装配
+
+| 手段 | 做法 | 代价 |
+|---|---|---|
+| 指令层级 | 系统/人设 → 域规则 → 任务 → 工具说明 → 历史 | 层级混乱会被后文覆盖 |
+| 预算分配 | 给 system/tools/history/knowledge/output 分别定额（token 压力比） | 需按模型窗口换算 |
+| 稳定前缀 | 三段：**稳定（人设/规则）→ 上下文（项目/知识）→ 易变（任务/时间）**；时间戳只进末段 | 顺序错就命中率归零（Hermes/OpenClaw 实测） |
+| 截断策略 | 索引 + 按需读；截断留痕 | 检索失败会漏信息 |
+
+### L2 工具接口
+
+- 工具名与描述是**提示词的一部分**：名字动词化、描述写"何时用/何时不用"、参数带例子。
+- **定义跨 turn 冻结**：同一会话里工具列表只增不删、按名排序；增删/乱序会击穿前缀缓存（OpenClaw 做法）。
+- 失败回给模型时带 **code + 摘要**，让模型能自纠（dsh 的 `isError` 文本）；重复同参调用要检测并提醒（dsh `repeat-tool-reminder`）。
+- **参数级校验放在执行前**（不靠模型自觉）；错误信息回给模型时给"可修复提示"。
+- 角色按最小工具集发放（包络），不是给全集。
+
+### L3 输出契约
+
+```
+schema 定义 → 生成 → 解析 → 校验 → 失败则带错误重试（≤2 次）→ 仍失败则降级为自由文本 + 人工复核
+```
+
+- **输入修复**可做（字符串化对象、数字/布尔字符串、删多余键），但必须**回显原文**；坏值不允许被"猜到"（Pi #10897 的教训）。
+- 输出被截断的 tool call 必须显式失败，不能"丢调用留结果"（Pi #11227）。
+
+- **永不信任解析**：解析失败不是异常，是预期分支。
+- 重试必须带**具体错误位置**，不是"请重试"。
+
+### L4 过程控制
+
+- 计划 → 执行 → 自检 → 停止条件；步数/时长/成本预算。
+- 关键写操作前 checkpoint；失败可续跑（对齐 evolution 的 V 模型）。
+- 高风险步骤强制独立复核（不与执行同源）。
+
+### L5 重试与回退
+
+失败分类（必须分开计数）：
+
+| 类型 | 处理 |
+|---|---|
+| 网络/超时 | 指数退避 + jitter；同一请求重试（opencode 10 次、2/4/8→10s 封顶） |
+| 限流 | 读 `Retry-After`（封顶 15min）；否则退避；可切模型 |
+| 鉴权失败（401/403） | **不重试**，立即失败并报配置问题（Hermes 做法） |
+| 空响应/截断 | 缩小上下文或提高 maxOutput；重试一次 |
+| 解析失败 | 带错误位置修复重试（≤2） |
+| 工具报错 | 把 stderr 摘要回给模型；不自动重放破坏性命令 |
+| 模型不可用 | 走 fallback 链；**记录降级**，不静默 |
+
+本机证据：dsh `llm-retry` 已有 `maxRetries` / `delayMs` / `providerRetryAfterMs` / jitter —— 可复用，不重写。
+
+### L6 选择与路由（已定：四类）
+
+- **用户显式选模型 = strict**：不许静默换模型（OpenClaw 做法）；自动路由只在未指定时生效。
+- 会话级 **affinity**（session id）用于缓存路由（opencode）；换模型/换凭据 = 缓存归零，必须记录。
+
+| 类 | 判据 | 默认 | 备选 |
+|---|---|---|---|
+| 长上下文 | 输入接近窗口 / 大量检索 | 大窗口模型 | 压缩后换小窗 |
+| 工具密集 | 多步工具编排 | 工具调用稳的模型 | 单步化后降级 |
+| 低成本 | 批量/低风险 | 便宜模型 | 失败升级 |
+| 高可靠 | 验收/外发/不可逆 | 强模型 + 投票 | 人工接管 |
+
+- **健康闸门（修正）**：`gate(tier, health)`，`health={ok_rate_5m,p95_latency_5m,cost_1h,cooldown_until}`；
+  准入条件 `ok_rate_5m ≥ SLO` 且 `p95 ≤ L` 且 `cooldown_until < now`；回退目标写进审计行。
+- 路由变更必须走实验（H11），不许拍脑袋。
+
+### L7 验收投票（已定：全部验收）
+
+- **每个验收环节**默认 **2 个独立模型投票**（不同 provider 优先），结论不一致 → 回人裁决。
+- 成本护栏：月度投票预算上限；超限时**降级为单票 + 人工复核**，并写 `degraded_reason`，**不许静默单票**。
+- 便宜模型可作第二票，但不得与第一票同源（同一 provider/同一版本不算独立）。
+- 投票记录进 `runtime/calls.jsonl`（`vote_group` + `task_id`），可复算成本与一致率。
+- **tie-break**：两票不一致 → **人裁**，不许第三票自动决定。
+- **同源排除**：judge 不得与被评模型同源（同 provider/同版本），防 self-preference。
+
+---
+
+## 3. 明确不依赖的旋钮（非目标）
+
+| 旋钮 | 为什么不用 |
+|---|---|
+| temperature / top_p / top_k | 不同 provider 语义不同，有的不支持 |
+| frequency/presence penalty | 同上，且难复现 |
+| reasoning_effort / thinking budget | 只有部分模型有；字段名与语义都在变 |
+| seed / stop sequences | 支持度不一，不能作为正确性保证 |
+| logit_bias / logprobs | 多数托管模型不暴露 |
+
+若某个模型支持，只能作为**可选加速**，不能成为流程正确性的前提；使用必须记录在 ModelSpec。
+
+---
+
+## 4. 行为观测与漂移
+
+**失败分类**（每类单独计数，作为模型指纹）：
+
+```
+empty / refusal / schema_violation / tool_misuse / wrong_tool / loop /
+truncated / hallucinated_tool / language_drift / latency / rate_limited
+```
+
+- 每个模型维护**指纹**：失败分布 + 平均步数 + 解析成功率 + 工具参数错误率。
+- 模型版本变化（或 provider 静默升级）→ 跑同一组 golden 任务，指纹偏移超过阈值即告警。
+- 记录在 `deps.jsonl`（模型也属于依赖）+ `model_fingerprints.jsonl`。
+
+---
+
+## 5. 可移植性（跨模型）
+
+1. **提示词按能力类写**（长上下文类/工具类/推理类），不按具体模型写。
+2. **评测按模型跑**：同一 golden 集，每个模型一份结果；不许拿 A 的成绩推断 B。
+3. 模型特有 hack 只放 adapter，不进核心。
+4. 换模型 = 一次迁移实验（shadow），不是改配置。
+
+---
+
+## 5.1 机制归属（已定：只做策略层）
+
+| 机制 | 归属 | dia 的增量 |
+|---|---|---|
+| 重试/退避 | dsh `llm-retry` 或宿主 | 失败分类 + 指纹 |
+| 压缩 | dsh `compaction-basic` / opencode | 预算策略 + 截断留痕 |
+| 模型选择 UI | dsh / opencode | 四类路由规则 |
+| 投票 | **dia 新增** | 独立性与成本护栏 |
+| 指纹/漂移 | **dia 新增** | golden 集 + 告警 |
+| 成本记账 | **dia 新增** | tokens/金额/投票组 |
+
+> 原则同 sandbox：**宿主有的不重写，dia 只加策略与观测。**
+
+## 6. 成本与延迟（客户端可控）
+
+- 前缀稳定（缓存命中）、压缩（threshold/retain）、批处理、按任务预算限流。
+- 成本记账到 `runtime/calls.jsonl`：tokens in/out/cache + 金额（若有价目表）。
+- 预算超限 → 降级（换小模型/减少检索）或暂停请示人；不许静默继续烧。
+
+---
+
+## 7. 实验（待验证）
+
+| # | 假设 | 判据 | 成本 |
+|---|---|---|---|
+| H9 | 工具描述重写能降低参数错误 | 参数错误率 ↓≥20%（同任务集） | 低 |
+| H10 | 带错误位置的修复循环能提升结构化成功率 | 解析成功率 ↑≥15%，重试 ≤2 | 低 |
+| H11 | 任务路由能降成本不降质量 | 成本 ↓≥30%，盲评质量不降 | 中 |
+| H12 | fallback 链能提升限流下的完成率 | 完成率 ↑，降级次数可查 | 中 |
+| H13 | 全部验收双票能降低错误 | 错误率 ↓≥20%，成本 ↑≤2×；一致率可复算 | 中 |
+| H14 | 投票预算护栏不降质量 | 超限降级后错误率不升（盲评） | 低 |
+
+---
+
+## 7.1 我们的增量（五家都没有的）
+
+1. **按模型跑 golden 回归**：每模型一份结果，升级/静默变更时比对指纹。
+2. **投票独立性校验**：第二票必须异源（provider/版本），否则不算独立（Hermes 的 MOA 是多模型混合，但不是验收投票）。
+3. **成本护栏**：投票预算 + 降级留痕；现有五家都没有"投票成本"概念。
+
+## 8. 失败模式（诚实边界）
+
+1. **提示词脆弱**：模型升级后同一提示行为漂移 → 只能靠 golden 集发现。
+2. **能力误判**：把 `unknown` 当支持 → 运行时失败；必须 fail-closed。
+3. **缓存破坏**：动态内容放前缀，成本翻倍。
+4. **重试放大**：对破坏性操作自动重试 = 事故；只允许幂等操作自动重放。
+5. **投票成本**：多模型投票在高频任务上不可持续，只用于高 stakes。
+6. **评测过拟合**：golden 集太小会奖励"背题"；每季度从真实失败补题。

package/docs/monorepo.md

@@ -0,0 +1,83 @@
+# dia monorepo：框架模块的归属
+
+> 日期 2026-10-30。结论：**dia-job 回 dia monorepo，作为 `packages/job`；kb 作为 `packages/kb`。**
+> 域语义（yan 的 scene/claims、dabo 的个人知识）仍留各自域，不因 monorepo 回流。
+
+---
+
+## 1. 为什么改
+
+- `dia-job` 是框架能力（调度适配器），不是独立产品；独立仓导致：
+  - 安装/版本/CI 两套；
+  - `dia` 与 `dia-job` 的契约变更不能原子提交；
+  - shim 需要跨仓找 binary。
+- 但“放回 dia”不等于塞进 `src/`：OS 适配器与核心引擎生命周期不同，必须有**包边界**。
+- monorepo 让两者共享版本、测试、发布，同时保留独立包/可选安装。
+
+## 2. 目标结构
+
+```text
+dia/
+  package.json                 # workspaces: packages/*
+  packages/
+    core/                      # 现有 src：ingest/audit/freeze/task/persona/team
+    kb/                        # 通用 KB：index/query/get/lint/review/path/observe
+    job/                       # 调度适配器：launchd/cron/schtasks
+      bin/dia-job
+      lib/{config,policy}.sh
+      tests/
+      install.sh
+    cli/                       # 可选：dia 命令聚合 core/kb/job
+  docs/
+```
+
+- 初期可保留 `src/` 作为 core，不急着搬；先加 `packages/job`、`packages/kb`，CLI 用 re-export 兼容旧导入。
+- 包管理/工作区：**pnpm workspace**（`pnpm-workspace.yaml`）；运行时/测试/构建仍是 Bun。
+- 任务编排：**Turborepo 后置**（M2 后按需）；不在 M0 引入。
+- Nx：不选（见 §2.1）。
+
+## 2.1 工具选型
+
+| 工具 | 角色 | 适配 | 结论 |
+|---|---|---|---|
+| **pnpm workspace** | 包管理器 + workspace 链接/过滤 | 严格依赖边界、`--filter`、lockfile；与 Bun 运行时不冲突 | **选** |
+| **Turborepo** | 任务图 + 本地/远程缓存 | 配置轻；当前 3 个包、测试很快，缓存收益低 | **M2 后再加** |
+| **Nx** | 全功能 monorepo 平台（生成器/图/插件） | 偏前端/大型全栈；bash 包集成差；引入 daemon/插件体系 | **不选** |
+| Bun workspaces | Bun 原生 workspace | 零额外工具；但过滤/发布/版本生态不如 pnpm 成熟 | 备选 |
+| npm workspaces | 原生 workspace | 慢，功能少 | 不选 |
+| Changesets | 多包版本/发布 | 当前 private、不独立发包 | 需要发布时再加 |
+
+**为什么不是 Bun workspaces**：Bun 负责 `test/build`，但 monorepo 的“包边界/过滤/发布”用 pnpm 更成熟；两者可以共存（pnpm 只做链接与脚本调度，`bun test` / `bun build` 照旧）。
+**为什么 Turborepo 后置**：现在 `bun test` 秒级、包少；Turbo 的价值在缓存和 affected tasks，等包数/CI 时长上来再加，避免先背一层 hash/配置。
+**为什么 Nx 不选**：我们不是前端大仓，不需要 generator/plugin graph；bash `packages/job` 也不是 Nx 的强项。
+
+## 3. 包边界（硬规则）
+
+1. `core` 不依赖 `job`/`kb` 的具体实现；通过接口/CLI 调用。
+2. `job` 不依赖任何域（yan/dabo）路径、知识、任务名；全局配置走 env/`~/.config/dia-job`。
+3. `kb` 只做通用知识引擎；**scene/rule/claims/baseline/alerts/record 留域**（见 `docs/migrations/yan-kb.md`）。
+4. 域（yan-agent/dabo-agent）只依赖包契约，不反向被包依赖。
+5. `job` 的 launchd/cron 写入必须有测试隔离开关；默认 dry-run。
+
+## 4. 迁移阶段
+
+| 阶段 | 动作 | 门禁 |
+|---|---|---|
+| M0 | ✅ 完成：`pnpm-workspace.yaml` + `packageManager` + `packages/job` 空壳 | `pnpm install` 成功；68 tests / build / smoke / e2e（node+bun）通过 |
+| M1 | ✅ 完成：`dia-job` 用 `git subtree` 合入 `packages/job`（保留历史）；根加 `dia job` 路由 | job 4 个测试文件通过；`dia job platform` 可用；独立仓已归档 |
+| M2 | ✅ 完成：`src/kb.ts`/`sqlite.ts` 抽到 `packages/kb`，根做 re-export；K1 query/review 已补 | `bun test` 73；`@dia/kb` 5；build/smoke/e2e |
+| M3a | ✅ 全局安装：`install.sh` 复制 `bin/dist/packages/job`，链接 `~/.local/bin/dia`；job 可选 | `dia version` / `dia job platform` 通过；CI 加 install 测试 |
+| M3b | ✅ CLI 聚合到 `packages/cli`；根 `src/cli.ts` 兼容 re-export | `bun test` 88、build、install、e2e 通过 |
+| M4 | ✅ 已归档 `minonl/dia-job`，README 指向 monorepo | 独立仓 archived |
+
+## 5. 不做
+
+- 不把 yan 的 scene/claims 搬进 `packages/kb`；
+- 不把 dabo 的个人知识搬进 framework；
+- 不为“monorepo”引入 nx/turbo；Bun workspaces 足够；
+- 不在 M1 同时大改 `src` 目录，避免迁移噪音盖过行为回归。
+
+## 6. 当前决定
+
+- `dia-job` 不再作为长期独立仓；先保留到 M1 完成，随后 archive。
+- `yan-kb` 不独立建仓；通用引擎进 `packages/kb`，域语义留 yan-agent@next。

package/docs/overview.md

@@ -0,0 +1,126 @@
+# dia / yan / dabo 现状总览
+
+> **2026-11-03 实测**。本条是三方合起来的「现在长什么样」；`docs/status.md` 管 dia 的阶段与证据，
+> 各域仓库管自己的知识与协议。**没跑过的不写「已验证」**；结论都能用 §6 的命令复验。
+> 长期方向（不是现状）见 [`vision.md`](vision.md)。
+
+---
+
+## 0. 一句话
+
+**dia 是控制面，不是 agent。** 宿主（opencode / dsh）里能选的只有 `yan`（工作域）和 `dabo`（个人域）；
+dia 负责「装谁、跑哪版、知识在哪、动作留不留痕」。
+
+```
+dia （控制面：persona / kit / kb / audit / job / wt）
+ ├── yan   工作域：工作域流程、仓库坑、技能；数据根 ~/.yan-agent    （宿主默认 agent）
+ └── dabo  个人域：个人知识、工具、策略；数据根 ~/.dabo-agent
+```
+
+---
+
+## 1. 三方对照（2026-11-03）
+
+| 维度 | dia | yan | dabo |
+|---|---|---|---|
+| 角色 | superagent / agent-team 生成与维护工具（控制面，无业务数据、无运行时） | 工作域 superagent（工作域 · 偏前端） | 个人助理 superagent（游戏 / 生活 / 个人项目） |
+| 仓库 | `~/repos/github/dia`（`minonl/dia`，private） | `~/.yan-agent/repos/yan-agent` | `~/repos/github/dabo-agent` |
+| 安装产物 | `~/.local/share/dia` + `~/.local/bin/dia` | `~/.local/share/dia/personas/yan/0.1.0` + `~/.config/opencode/agents/yan.md` + `~/.dsh/profiles/yan` | 同构：`personas/dabo/0.1.0` + `agents/dabo.md` + `~/.dsh/profiles/dabo` |
+| 版本 | `0.0.1`（package `private`） | persona `0.1.0` | persona `0.1.0` |
+| 知识根 | —（只读别人的） | persona 树 `core/knowledge` | persona 树 `core/knowledge` |
+| 数据根 | `~/.local/share/dia`（安装/台账/备份） | `~/.yan-agent` | `~/.dabo-agent` |
+| 宿主 | —（被调用） | opencode + dsh（profile 3091） | opencode + dsh（profile；webserver 端口动态，默认回退 1111） |
+| 域命令 | 见 §2 | 16 个（`kb scene/rule/query/...`、`mr`、`release`、`schedule`、`data`） | 2 个（`todo`、`welcome`） |
+| 生效方式 | 命令直跑 | opencode `default_agent=yan`；dsh profile | 显式选 agent / `dsh --profile dabo` |
+| 装态 | — | **落后来源仓 1 个提交**（见 §4-1） | 与来源仓一致 |
+
+---
+
+## 2. dia 能力面（2026-11-03 实测）
+
+**已实现**
+
+| 组 | 命令 |
+|---|---|
+| 知识 | `kb index / search / query / get / lint / path / review`；`--persona` 作用域下自动重建过期索引 |
+| 采集 | `ingest sessions（dsh/opencode）/ ingest git`，脱敏 + 幂等 |
+| 审计 | `audit append / verify / score / tail`；`freeze / thaw`；`guard`；`run / resume` |
+| persona | `add / create / render / list / verify / remove / show / use / path / check / update / default`（含 `--force`、`--dry-run`、`--check`） |
+| 内容包 | `kit add / list / verify / remove` |
+| 自检 | `doctor`（多 persona 逐个自检；`--persona` 单查；exit 0/1/2） |
+| 运行面 | `env list/check/run`、`deps list/record`、`wt …`、`cmd` / 一级委派、`task`、`team run/gate/accept/reject/next`、`job`、`price`、`version` |
+
+**未实现（有设计、无命令）**
+
+| 项 | 现状 | 出处 |
+|---|---|---|
+| `patch …` | `unknown command` | `docs/patching.md` |
+| `persona activation` | 无（只能 `use` / `default`，下次会话生效） | `docs/versioning.md` |
+| `kit create / update / show / gc` | 只有 `add/list/verify/remove` | `docs/kit-install.md` |
+| ~~deps 校验（M1）~~ | **已完成**：`deps.jsonl` + `doctor` 的 `deps` 项（required 缺失 fail / 漂移 warn / 可选未装 note） | `docs/dependency-registry.md` |
+| audit 哈希链（M3） | 未做 | `docs/status.md` D1 |
+| ModelSpec / 基准 sidecar（D2） | 未做（已有 `price` 计价） | `docs/model-*.md` |
+| state 事件 / `(T,D,O)` 视图（D3） | 未做 | `docs/evolution-process.md` |
+| PR canary（D4） | 未做 | `docs/status.md` |
+| IM bridge / ACP server / npm 发布 | 未做 | `docs/entrypoints.md`、`docs/acp-integration.md` |
+
+> 曾经写进文档但**不存在**的命令：`dia status`、`dia model`（观测入口目前只有 `dia doctor`）。
+
+---
+
+## 3. 本机实际状态（复验过的）
+
+```
+$ dia doctor                     → verdict: ok（dabo.* / yan.* 逐项 + default_agent + wt）
+$ dia persona list               → dabo: 0.1.0 / yan: 0.1.0
+$ dia persona check dabo         → same（git main d6b3ff77）
+$ dia persona check yan          → local-only（本地 83fbaa9，来源仓 main 已是 8d10cc5）
+$ dia persona default --show     → yan
+$ dia job list                   → 5 个 launchd 任务（session-diary sync/gc、task selfcheck、job update、yan-reviewer）
+$ dia --persona dabo kb query …  → 只命中 dabo 自己的 core/knowledge
+$ dia --persona yan kb scene S1  → 正常出场景卡
+```
+
+测试与 CI：`bun run test` = 188 tests / 28 files 全绿 + smoke + E2E-1；GitHub Actions ubuntu+macOS 双绿（`4998a1b`）。
+
+---
+
+## 4. 已知缺口（按优先级）
+
+1. **yan 安装落后来源仓 1 个提交**（`83fbaa9` vs `8d10cc5`，内容是 dsh profile 根 `cordis.yml` 修复）。
+   修法：`dia persona add yan --from ~/.yan-agent/repos/yan-agent --force`（先备份）。
+2. **`dia doctor` 的 knowledge 项只查目录存在**，不校验索引新鲜度；`kb` 索引过期要等查询时才自愈。
+3. ~~`deps.jsonl` 与真实环境脱节~~ → 已改为按 `command:` 探测并接入 `doctor`；**追加动作仍手工**（`dia deps record` 未做）。
+4. **本地源 persona 不能 `update`**（`E_SOURCE`），只能用 `add --force` 刷新；`update` 尚未支持本地源。
+5. **yan 旧脚本未迁**：`yan-env`、`yan-version`、`yan-ref`、`yan-data-root`、`yan-data-sync` 仍是仓库脚本
+   （`dia env` / `persona show/use` 已有等价能力，未收口）。
+6. **`verify` 只看内容哈希**，宿主产物漂移要靠 `render --check`（两个命令给不同答案，容易误判）。
+7. **凭据放行粒度**：bw 按账号/collection 分组，任务级最小权限与调用审计都缺；调研见 `docs/security/credentials.md`。
+8. 公开 release 仍 BLOCKED（脱敏 + 历史清洁 + `dia-security` pass，见 `docs/security/public-release.md`）。
+
+---
+
+## 5. 文档地图（按现状分级）
+
+| 级别 | 文档 | 说明 |
+|---|---|---|
+| **现状（可依赖）** | `overview.md`（本文）、`status.md`、`cli.md §4.1`、`persona-install.md`、`monorepo.md`、`team.md`、`pricing.md`、`migrations/yan-agent-current.md` | 与代码/本机一致 |
+| **设计（部分未实现）** | `architecture.md`、`entrypoints.md`、`kit-install.md`、`versioning.md`、`patching.md`、`team-automation.md`、`security-sandbox.md`、`dependency-registry.md`、`acp-integration.md`、`proposals.md` | 保留意图，文首/文中标注实现范围 |
+| **迁移与发版** | `migrations/llm-migration.md`、`../scripts/release.sh` | 迁移用 LLM 任务（不写 migration 代码）；发版打 tag + GitHub Release |
+| **方向（不是现状）** | `vision.md` | 长期定位：superagent/team 工厂、平台版本经验库、fleet（openrig）边界 |
+| **平台经验** | `platforms/registry.json`（数据）+ `platforms/index.md`（规则/用法） | 单一事实源；`dia doctor` 派生人读视图；不记录设备 |
+| **理论 / 研究** | `evolution-process.md`、`model-behavior.md`、`model-baseline-sidecar.md`、`host-control-surface.md`、`ecosystem-*.md`、`research/*` | 供推导，不作为现状 |
+| **留痕** | `migrations/*`（除 current）、`review/*`、`research/h0/*` | 当时结论，可能被后续推翻 |
+
+---
+
+## 6. 复验命令（照抄可跑）
+
+```bash
+dia version && dia doctor
+dia persona list && dia persona check dabo && dia persona check yan
+dia persona render dabo --check && dia persona render yan --check
+dia --persona dabo kb query "边界"        # 必须只命中 dabo 的知识根
+dia --persona yan kb scene S1             # 工作域场景卡
+cd ~/repos/github/dia && bun run test     # 188 tests + smoke + E2E-1
+```

package/docs/patching.md

@@ -0,0 +1,91 @@
+# Patch：对已安装 persona / kit 的本地补丁
+
+> 日期 2026-10-28。参考 npm/patch-package，但**只作用于本地安装副本**，不改上游。
+>
+> **状态（2026-11-03）**：**未实现**，`dia patch` 仍是 `unknown command`。本文是设计。
+> 用途：本地迭代、紧急修复、试验性调整；不替代 `update`。
+
+---
+
+## 1. 命令
+
+```bash
+dia patch create dabo --file changes.diff --reason "..."   # 生成 patch 元数据
+dia patch add dabo --file <patch-dir|diff>                 # 应用到当前安装版本
+dia patch list dabo
+dia patch verify dabo
+dia patch revert dabo --id <patch-id>
+```
+
+- patch 只作用于 `~/.local/share/dia/personas/<id>/<version>/`（或 kits）；
+- **不改上游 git**；升级到新版本时尝试重放，失败即冲突。
+
+---
+
+## 2. 格式
+
+```
+patches/<id>/<patch-id>/
+├── patch.json      # base_version, base_hash, author, reason, files[], created_at
+└── changes.diff    # 统一 diff（仅文本文件）
+```
+
+`patch.json` 必填：
+
+```json
+{
+  "id": "p-20261028-1",
+  "persona": "dabo",
+  "base_version": "1.2.0+abc1234",
+  "base_hash": "sha256:...",
+  "files": ["agents/dabo.md"],
+  "reason": "本地实验：调整排障口吻",
+  "author": "min",
+  "created_at": "2026-10-28T12:00:00Z"
+}
+```
+
+---
+
+## 3. 应用流程（双重闸门）
+
+```
+verify base（版本+hash 必须匹配）
+  → dry-run（只显示 diff）
+  → 硬检查（文件白名单/大小/无二进制/不改 capabilities）
+  → 模型审查（diff 是否引入越权、注入、策略弱化）
+  → 应用 → 更新 dia.lock（记录 patch id）→ render
+  → 审计事件
+```
+
+- **硬检查不过 = 拒绝**；模型只做补充，**不能推翻硬失败**。
+- 允许 patch 改：提示词、知识、技能实现。
+- **不允许** patch 改：`capabilities`、安全策略、版本号、签名/凭据字段（需走 waiver + 人批）。
+
+---
+
+## 4. 升级时重放
+
+`persona update` 到新版本时：
+
+1. 先应用新版本；
+2. 逐个 patch 尝试 `git apply --3way`（无 git 时用自有 3-way）；
+3. 成功 → 记录新 base；失败 → **冲突**，该 patch 标记 `stale`，新版本仍可用，但提示"patch 未应用"；
+4. 冲突不阻断新版本，但 `dia status` 显示 `patch conflict`，并保留旧版本可回滚。
+
+---
+
+## 5. 安全与审计
+
+- patch 文件大小上限（如 256KB）；只允许文本扩展名。
+- patch 内容过 secret 扫描；命中即拒绝。
+- 每个 patch 记录 `applied_at / applied_by / base_hash`；`dia patch list` 可查。
+- patch 也是"变更"，进入审计与回滚链；**不因是本地 patch 就免审计**。
+
+---
+
+## 6. 与版本号的关系
+
+- patch **不改变** persona 版本号；它是本地覆盖层。
+- 若要进入上游：导出 diff → 提 PR → 上游 bump patch/minor → 撤销本地 patch。
+- `dia patch export dabo --id <id>` 输出可提交的 diff。