@minonl/dia 0.0.0-stage → 0.0.1

package/docs/acp-integration.md

@@ -0,0 +1,136 @@
+# ACP 集成与降级设计（2026-10）
+
+> 日期 2026-10-28。问题：通过 ACP 是否更好？fallback 怎么做？配置失败如何降级、体验如何？
+> 结论：**ACP 做主通道（会话级控制），CLI/HTTP/只读做分级回退；所有降级必须显式可见，不许静默。**
+
+---
+
+## 1. ACP vs 其他接法
+
+| 接法 | 能做什么 | 稳定性 | 适用 |
+|---|---|---|---|
+| **ACP（JSON-RPC stdio）** | 会话创建/提示/事件流/权限请求/恢复/分叉 | 协议 v1，仍在演进 | **交互式会话、跨宿主** |
+| CLI one-shot | 单次任务、退出码 | 高 | **基准/canary/批处理** |
+| HTTP API | 任意操作（opencode `api`） | 中（daemon 版本绑定） | 查询/管理 |
+| 只读会话库 | 观察历史 | 最高 | **采集/审计** |
+| 插件 hook | 深层拦截/观测 | 低（API 断代） | 仅观测 |
+
+**为什么 ACP 更好**：它把"会话"作为一等对象（new/prompt/update/permission/resume/fork），跨 opencode/dsh 通用；CLI 只能拿最终文本，HTTP 绑定单个宿主。
+
+**为什么不能只用 ACP**：批处理/canary 用 one-shot 更稳；观察历史不该依赖运行时；ACP 客户端本身可能坏。
+
+---
+
+## 2. 本机实测（2026-10-28）
+
+| 宿主 | 启动 | initialize | session/new | 关键能力 |
+|---|---|---|---|---|
+| **dsh**（`@deepseek-ai/dsh-acp-app`） | `dsh --profile dia-acp` 常驻等输入 | ✅ protocolVersion 1，agentInfo `deepseek-harness-acp 0.0.1` | ✅ 返回 sessionId + configOptions | session close/list/resume；mcp http；prompt 不支持 image/embedded |
+| **opencode**（`opencode acp`） | 常驻 | ✅ protocolVersion 1 | ✅ 返回 sessionId + configOptions | loadSession/fork/delete/list/resume；mcp http；prompt 支持 image/embedded |
+
+**实测坑（必须处理）**：
+
+1. **dsh stdout 会混入日志**：`[llm-deepseek-account] model listing ...` 出现在 JSON 之前 → 客户端必须**逐行过滤非 `{` 开头**，并为协议行设超时。
+2. dsh `session/new` 会触发模型目录网络请求；离线时可能阻塞/失败 → 需要超时 + `degraded_reason`。
+3. 两个服务端都**不主动输出**，必须先发 `initialize`；握手超时 = 不可用。
+
+---
+
+## 3. Fallback 阶梯（显式，不静默）
+
+```
+L0 ACP（首选，会话级）
+  ↓ 握手失败/超时/协议错
+L1 CLI one-shot（`dsh headless` / `opencode run`）
+  ↓ 命令缺失/版本不符
+L2 HTTP API（opencode `api`）
+  ↓ 服务未运行/鉴权失败
+L3 只读会话库（observe-only）
+  ↓ 连读都失败
+L4 拒绝执行（exit 30/31/32）
+```
+
+规则：
+- **每一级降级都写 `degraded_reason` + 审计**；`dia status` 可见，不许悄悄换。
+- **高危动作不降级**：写文件/外发/权限变更在 L1 以下一律拒绝（或转 draft）。
+- **只读永远可用**：采集/审计不依赖 ACP。
+- 用户可用 `--backend acp|cli|api|readonly` 强制指定；强制失败即报错，不回退。
+
+---
+
+## 4. 配置失败 → 怎么降级、体验如何
+
+### 4.1 失败分类与退出码
+
+| 码 | 含义 | 触发 | 降级 |
+|---|---|---|---|
+| 0 | OK | — | — |
+| 2 | 用法错误 | 参数缺失 | 无 |
+| 30 | **degraded** | ACP 失败已回退 | 继续，但标注 |
+| 31 | 配置/鉴权 | 缺凭据、版本不符 | 停用该后端 |
+| 32 | 协议 | 握手超时、非法 JSON、stdout 污染过多 | 回退一级 |
+| 33 | 能力缺失 | 需要的能力不在 capabilities 里 | 拒绝该动作 |
+
+### 4.2 用户体验（文字示意）
+
+```
+$ dia status
+dsh       ACP  ok      v0.2.1-rc.2  session/new ok   (last 10-28 11:03)
+opencode  ACP  ok      v2.1.3       loadSession ok   (last 10-28 11:04)
+model     base stale   指纹 14 天未更新（建议 dia model incident）
+
+$ dia run --session s1 -- bash -lc "npm test"
+! ACP 不可用（handshake timeout）→ 已回退 CLI one-shot
+! 本次为降级执行，写操作需人工确认
+exit=0
+
+$ dia doctor
+FAIL  dsh ACP: handshake timeout (3.0s)
+  → 修复：dsh --profile dia-acp --dump-config 检查 acp-app 是否在 bundles
+  → 或：dia run --backend cli 继续（只读/批处理可用）
+```
+
+原则：
+- **一句话说清降级**，再给**修复命令**；
+- 降级后**不假装完整**：`status` 标 `degraded`，报告里带 `degraded_reason`；
+- 不阻塞用户：采集/审计继续，执行转草稿或人工。
+
+### 4.3 配置形态
+
+```yaml
+backends:
+  dsh:
+    prefer: acp
+    acp: { profile: dia-acp, handshake_timeout_ms: 3000 }
+    fallback: [cli, readonly]
+  opencode:
+    prefer: acp
+    acp: { command: "opencode acp", handshake_timeout_ms: 3000 }
+    fallback: [api, readonly]
+```
+
+---
+
+## 5. 实现建议
+
+1. **自己写薄 ACP 客户端**（TS，约 200 行）：只需 `initialize` / `session/new` / `session/prompt` / 事件读取 / `session/close`；JSON-RPC over stdio。
+2. **容错**：逐行过滤非 JSON；握手/首事件/总预算超时；能力缓存到 `capabilities.json`（90 天）。
+3. **acpx 只做对照/兜底**：`acpx`（0.21.1，MIT）可验证我们的客户端行为，不作为主依赖（pre-1.0）。
+4. **配置探测**：启动时跑一次 `initialize`，把 `agentCapabilities` 落盘；能力缺失（如 image）直接标 `unsupported`，不猜。
+5. **降级可测**：人为杀掉 ACP 进程 / 注入日志行 / 改坏 profile，E2E 必须看到 `degraded` 与回退路径。
+
+---
+
+## 6. 与现有设计的关系
+
+- 与 `host-control-surface.md` 的 L0/L1 分层一致：ACP 是 L0 的会话接口。
+- 与 `model-baseline-sidecar.md` 的 canary 一致：canary 默认走 CLI one-shot（稳），交互走 ACP。
+- 与 `security-sandbox.md` 一致：降级不等于放开权限；高危动作仍需 waiver/人批。
+
+---
+
+## 7. 待验证
+
+- ACP `session/prompt` 的事件流格式与权限请求（`session/request_permission`）在两家是否一致。
+- dsh ACP 在离线（模型目录不可达）时的失败形态。
+- 长时间会话的 resume/fork 语义（两家能力不同：opencode 有 fork，dsh 只有 resume）。

package/docs/architecture.md

@@ -0,0 +1,166 @@
+# 架构：框架 / 场景入口 / kit
+
+> 日期 2026-10-27。本文回答一个问题：**什么该留在 dabo-agent，什么该抽到独立框架。**
+> 依据：yan-agent 实测数据 + `dabo-agent:docs/research/system-survey.md`（外部引用）。
+
+---
+
+## 0. 结论
+
+三层，各管一件事：
+
+```
+framework（独立项目）  ← 通用能力，无业务数据
+   ↑ 被订阅                    ↑ 被订阅
+yan-agent（工作场景入口）   dabo-agent（个人场景入口）  ← 只放本域数据、人格、工具、策略
+   ↓ 订阅                      ↓ 订阅
+kits（知识 / 技能 / 工具内容）  ← 可被两个域共同订阅，默认无执行权
+```
+
+**判定口径**：
+- 两个域都要用 → 进 framework；
+- 只有一个域用 → 留在该域；
+- 可以被不同域按需装 → 打成 package。
+
+---
+
+## 1. 现状测量（yan-agent，2026-10-27）
+
+| 指标 | 值 | 说明 |
+|---|---|---|
+| 知识文件 | 103 个 / 910KB | rules 26 / workflows 16 / repos 1 / tools 等 |
+| 全库 token 估算 | **≈245k** | 不可能全量注入 |
+| 索引 `index.md` | 87 行 / 15.6KB / **≈4.2k tokens** | 可注入 |
+| **索引覆盖** | **74/103（72%）** | **28% 的文件从索引走不到** |
+| **`review_by`** | **0/103** | 复审机制设计了，**从未落地** |
+| 内部链接 | 118 条，**断 9 条（7.6%）** | 链接会烂 |
+| 近重复内容 | **0 组** | 不是"重复"问题 |
+| 常驻 daemon | 16 个 launchd | 已有独立调度的事实标准 |
+
+> 结论：你说的"人读 md 不行了"，实测根因是**索引覆盖不全 + 复审没执行 + 链接会烂**，
+> **不是文件格式**。换数据库解决不了这三件事。
+
+---
+
+## 2. 职责矩阵（谁拥有什么）
+
+| 能力 | framework | yan | dabo | package |
+|---|---|---|---|---|
+| 预设注入（opencode/dsh 渲染） | ✅ 实现 | 提供 preset 内容 | 提供 preset 内容 | — |
+| 知识索引 / 检索 / 复审队列 | ✅ 实现 | 提供知识 | 提供知识 | ✅ 知识 kit |
+| 定时任务 / 调度 | ✅ 实现（launchd 生成） | 声明任务 | 声明任务 | — |
+| 安全：预算 / 审计 / 冻结 / 豁免 | ✅ 实现 | 声明策略 | 声明策略 | — |
+| 会话采集与脱敏 | ✅ 实现 | 可选开 | 默认开 | — |
+| kit 管理（add/lock/verify） | ✅ 实现 | 订阅清单 | 订阅清单 | ✅ 被订阅 |
+| 人格 / 域规则 | ❌ | ✅ | ✅ | 可提供片段 |
+| 业务工具 | ❌ | ✅ | ✅ | ✅ 工具 kit（无执行权） |
+| 业务数据（公司/个人） | ❌ **永不** | ✅ | ✅ | ❌ |
+
+硬约束：
+1. framework **不存业务数据**，读路径由域传参。
+2. 域**不实现通用能力**（不自己写检索/审计/调度）。
+3. kit **默认无执行权**；装包只落盘，执行需显式批准（ClawHavoc 教训）。
+
+### 2.1 宿主适配（entry adapter，H0 补）
+
+H0 抽样发现三层缺一个承接处：**宿主客户端/插件/本机环境**。它归**入口层的 adapter 子层**，不是第四层内核：
+
+```
+framework ← adapter → domain/kit
+（framework 永不反向依赖 adapter）
+```
+
+- **职责**：Electron/DSH 客户端插件、宿主配置页、编辑器/浏览器插件安装、宿主专属 UI 适配。
+- **不放进 framework**：adapter 依赖宿主版本，生命周期与引擎不同；放内核会让框架重新变胖。
+- **不放进 kit**：kit 默认无执行权；宿主插件需要显式授权与宿主 API。
+- **版本**：adapter 随宿主版本走；framework/domain 只暴露稳定契约。
+- **验收**：`docs/research/h0/report.md` 的 3 条宿主任务必须有明确 adapter 归属；50 样本复验时按此口径重跑。
+
+---
+
+## 3. 知识存储：md 还是 sqlite？
+
+| 方案 | 优点 | 缺点 | 适配度 |
+|---|---|---|---|
+| **A. md + 索引（现状）** | git diff 可审、人可改、可移植、LLM 直读、零依赖 | 无排名/元数据查询；索引靠人维护（实测 72%）；复审靠自觉（实测 0/103） | 中 |
+| **B. sqlite 作主存** | FTS5 排名、结构化查询、原子更新、多域 tag | **无 diff、无法 PR 审阅、合并冲突、需要工具才能读、迁移成本、LLM 不能直读**、备份变二进制 | 低 |
+| **C. md 为唯一事实源 + 派生 sqlite/FTS5 索引** | 保住 A 的优点，补上检索/元数据/复审队列；索引可删可重建 | 需要构建步骤；存在"索引过期"风险（可用"删库重建结果一致"测试消除） | **高** |
+
+**推荐 C**，规则写死：
+
+1. **只有 md 可写**；`index.db` 是派生物，删掉必须能重建，且重建结果可复现（测试断言）。
+2. 检索、复审队列、断链检查、索引覆盖统计，全部由工具生成，不靠人手维护。
+3. SQLite 只放两类东西：**派生索引** + **会话/回合等状态数据**，不放"人类知识"。
+4. 复审不再要求人写 `review_by`：用 `git log -1` 的修改时间 + 显式 `review_by` 覆盖，自动生成到期队列。
+
+**行业佐证**：Hermes 用 SQLite 存消息、用 md 存记忆与技能；OpenClaw 用 SQLite 存会话、md 存记忆。
+**没有一家把人类知识的主存放进数据库**。
+
+---
+
+## 4. 抽取顺序：先在 yan 上"绞杀"，dabo 做第二消费者
+
+不做"先写完框架再迁移"（那是瀑布，且没有真实使用）。用 strangler：
+
+1. **定义契约**（framework 对外接口）：`kb search/get/lint`、`task add/list/due`、`audit append/verify`、`freeze/thaw`、`persona render`、`kit add/verify`。
+2. **新项目里实现最小版**，直接读 yan 的现有知识目录（只读），跑出与现状一致的索引/检索结果。
+3. **yan 切换**：先把 `yan-kb` 的检索切到 framework，其余保持不变（可回退）。
+4. **dabo 接入**：只写自己的 preset + 域知识 + 策略，通用能力全部来自 framework。
+5. **出 kit**：把 yan 里可复用的知识/技能打成 kit，两个域按 lockfile 订阅。
+
+判据：
+- 切换前后同一查询结果集一致（抽样 20 条）；
+- 索引重建两次结果哈希一致；
+- yan 的一周真实使用无回归；
+- dabo 能只靠"preset + 域数据"跑通同一套门禁。
+
+---
+
+## 4.1 执行后端模式（2026-10-28 补充）
+
+dia 不拥有运行时；执行后端按场景选：
+
+| 模式 | 后端 | 适用 |
+|---|---|---|
+| 共享 daemon | opencode 用户级 server | 交互式、长会话 |
+| 私有 server | `opencode serve --standalone` | 需要隔离 |
+| 嵌入式 | `@opencode/sdk`（内存 router） | 无端口、版本锁定 |
+| one-shot | `dsh headless` | 批处理 / canary / 基准 |
+
+判据：同一任务在任一后端跑出的审计/成本/结果必须可比较（同一 `task_id`）。
+
+## 5. 第一个真实任务（解决"零使用"）
+
+**采集本机 dsh / opencode 会话 → 脱敏 → 归一化为回合 → 生成知识候选**。
+
+| 步 | 做法 | 判据 |
+|---|---|---|
+| 读 | dsh: `~/.dsh/sessions/*/session-*/session.v4.jsonl.zstd`；opencode: `~/.local/share/opencode/opencode.db` | 能列出会话数与时间范围 |
+| 脱敏 | 凭据/token/内网域名/工号 → 占位符；规则可测试 | 样例集 100% 命中；误伤 <5% |
+| 归一 | 统一成 `episode{ts, domain, task, actions[], outcome}` | schema 校验 |
+| 候选 | 只产"候选"，不自动写知识 | 候选必须人工确认 |
+
+隐私边界：**dabo 域默认开采集；yan 域默认关**（工作会话不出本域）；跨域只共享方法，不共享数据。
+
+---
+
+## 6. 对现有 dabo 设计的影响
+
+| 现 design 章节 | 处理 |
+|---|---|
+| §5 团 / §5.2 档位 | **移出**或删；先做"预设组合"，H4/H5 未过不动 |
+| §6 四层记忆 | 压成 **knowledge（md）+ evidence（episodes/logs）**；预算逻辑进 framework |
+| §7.1 gateway 形态 | 通用调度进 framework；dabo 只声明任务 |
+| §10 安全（审计/冻结/豁免） | **进 framework**；dabo 只写策略值 |
+| §15 拥抱变化（adapter/probe/migration） | **进 framework**；dabo 只选目标 |
+| 人格 / 协议 / 域知识 / 业务工具 | **留在 dabo** |
+
+---
+
+## 7. 早期待定 → 2026-11-03 结论
+
+1. **名字 / 位置**：叫 `dia`，仓库 `minonl/dia`（private），装到 `~/.local/share/dia` + `~/.local/bin/dia`。
+2. **知识存储**：按 C 方案落地——md 主存 + 派生 sqlite/FTS5 索引（`dia kb index/search/query`），索引可删可重建。
+3. **抽取顺序**：yan 先行、dabo 第二消费者，均已成 dia persona（`dia persona add`），工作域 / 个人域各一套知识根与数据根。
+4. **kit 最小粒度**：**仍未定**。实际只用到 `add/list/verify/remove`，大部分内容由 persona 的
+   `files/skills/dirs/config` 内联承担；`kit show/update/gc` 未实现。

package/docs/cli.md

@@ -0,0 +1,117 @@
+# dia CLI 词表（动作规范）
+
+> 日期 2026-10-28。原则：**动作成对、名词分层、不混轴。**
+> 名词：`persona`（可被选中的 agent 定义）、`kit`（知识/技能/工具内容）、`profile`（dsh 宿主组合，不对外当命令）。
+
+---
+
+## 1. 动词矩阵
+
+| 动作 | 含义 | 反义/配套 | 示例 |
+|---|---|---|---|
+| **add** | 从 git/本地取回 → 校验 → 渲染 → 登记 lock/deps | **remove** | `dia persona add dabo --from git+... --ref <sha>` |
+| **remove** | 注销 + 删除带 `managed-by: dia` 的产物 | add | `dia persona remove dabo` |
+| **create** | **本地生成**一个新骨架（`dia.json` + 最小文件） | （无；不是安装） | `dia persona create mybot` |
+| **update** | **换内容**（ref→新 commit）+ 重渲染；旧版本备份；运行中会话不切换 | — | `dia persona update dabo --ref <sha>` |
+| **render** | **不换内容**，只把已安装版本重渲染到宿主（宿主升级/文件漂移） | — | `dia persona render dabo --host dsh` |
+| **verify** | 清单/哈希/版本校验 | — | `dia persona verify dabo` |
+| **list / show** | 列出 / 看详情 | — | `dia persona list` |
+| **path** | 打印**生效版本目录**（服务/脚本取代码的稳定入口） | — | `dia persona path yan` |
+| **add / remove**（kit） | 同上，作用于内容 | — | `dia kit add git+...` |
+
+**不要用**：
+- `install/uninstall`（与 add/remove 重复，且暗示系统级安装）；
+- `preset`（宿主概念，不当作名词）；
+- `pkg`（npm 语义，暗示依赖/执行）。
+
+---
+
+## 2. 名词与子命令
+
+> **2026-11-03 注**：下面的 `kit create/update/show`、`patch`、`persona activation` 是**目标态**；
+> 实际已实现的命令与证据见 §4.1（`persona activation`、`patch` 当前是 `unknown command`）。
+
+```
+dia persona add|remove|create|update|render|verify|list|show
+dia kit     add|remove|create|update|verify|list|show
+dia patch   create|add|list|verify|revert|export
+dia persona activation <id> --mode next-session|active-additive|active-all|manual
+```
+
+**默认行为约束**：
+- `add` 只新增/渲染，**不改默认 agent**、不碰 yan；
+- `remove` 只删 `managed-by: dia` 的文件，用户手改过的拒绝删除；
+- `create` 不联网、不执行脚本，只写骨架；
+- 所有写动作支持 `--dry-run`。
+- **按能力热更新**：T3 增量可 `--apply active`；破环性变更只允许 `--apply next-session`；`--activate-now` 需 `--i-am-human`。
+
+---
+
+## 3. 退出码
+
+| 码 | 含义 |
+|---|---|
+| 0 | OK |
+| 2 | 用法错误 |
+| 30 | degraded（已回退/部分宿主缺失） |
+| 31 | 配置/鉴权失败 |
+| 32 | 清单/冲突（E_MANIFEST / E_CONFLICT） |
+| 33 | 能力缺失（capabilities 不支持该动作） |
+
+---
+
+## 4. 示例
+
+```bash
+# 安装 dabo 人格（只新增，不改默认）
+dia persona add dabo --from git+https://github.com/minonl/dabo-agent.git --ref <sha> --dry-run
+dia persona add dabo --from git+... --ref <sha>
+
+# 从零写一个新人格
+dia persona create mybot --dir ~/repos/mybot
+
+# 宿主升级后重渲染
+dia persona render dabo --host dsh
+
+# 校验/卸载
+dia persona verify dabo
+dia persona remove dabo
+```
+
+---
+
+## 4.1 实现状态（2026-11-03 复核）
+
+> 判定方式：命令实跑 + `bun test tests`（286 tests / 39 files 全绿）+ 代码入口。写"未实现"的项当前是 `unknown command`。
+
+| 命令 | 状态 | 证据 / 备注 |
+|---|---|---|
+| `persona add` | **已实现** | 本地目录、`git+https://…`、`--ref`、`--host opencode\|dsh`、`--dry-run`、`--force`（覆盖已存在产物，覆盖前备份）；渲染 + `dia.lock` |
+| `persona list / verify / remove` | **已实现** | verify 校验内容哈希 + 自带内容产物（files 复制、skills 软链）；remove 按 lock 回收，手改的 skip |
+| `persona show <id>` | **已实现** | 生效版本 + 最近 5 次切换审计 |
+| `persona use <id>[@ver]` | **已实现** | 生效指针 `state/active.json` + 审计 `active.jsonl`；scope 先读指针，无指针回退最新 |
+| `persona path [<id>[@ver>]]` | **已实现** | 生效版本目录；`--json` 出 `{id,version,dir,source,commit}`；未装即非 0 退出（消费方大声失败） |
+| `persona check <id>` | **已实现** | 上游比对 same / differs / unknown / local-only；exit 0/1/3，内容被改 exit 2 |
+| `persona update <id>` | **已实现** | 从 lock 记录的 source+ref 重装，并把 active 指向新版本；本地源亦可 |
+| `persona default <id>` | **已实现** | 改宿主 `default_agent`：备份原文件 + 记原值，`--unset` 精确还原；非严格 JSON 直接拒绝 |
+| `persona create / render` | **已实现** | `create` 出骨架；`render --check` 只比对不写盘（跳过宿主自写文件，如 dsh `cordis.yml` / `package.json` / 锁文件）；`render` 只覆盖 persona 产物，不整树重建宿主 profile |
+| `kit add / list / verify / remove` | **已实现** | 复制/软链/记账；冲突写盘前全量检查（`E_CONFLICT`）；`src/kit.ts` + `tests/kit.test.ts` |
+| `env list / check / run` | **已实现** | 白名单注入、不回显值、`--redact`、密钥不进 argv；清单由 persona 声明（`src/env.ts` + `tests/env.test.ts`） |
+| `deps list / record` | **已实现** | `list` = 登记 + 实测派生视图（required 缺失 exit 2）；`record` = 只追加一行（`--id/--kind/--version` 必填）；`src/deps.ts` + `tests/deps*.test.ts` |
+| `doctor` | **已实现** | 组合自检：persona verify / **persona.render（宿主产物只读漂移，warn + 修复命令）** / default_agent / kit / knowledge（**索引新鲜度三态**，过期给重建命令）/ dsh preset / **deps 登记校验** / **platform 版本（读 `docs/platforms/registry.json`）** / wt；exit 0/1/2。不指定 persona 且装了多个 → **逐个自检**（条目加 `<id>.` 前缀），不再整体 `E_SCOPE` |
+| `wt …` | **已实现（需安装包）** | 转发 `packages/wt/bin/dia-wt`；未装时 `E_WT`（exit 33），`install.sh` 会分发 |
+| `kb index/search/query/get/lint/path/review` | **已实现** | persona 作用域下索引过期自动重建；显式 `--root` 保持「缺索引即报错」 |
+| `kb <域命令>` | **已实现（委派）** | 未命中内置 → persona `commands` → 委派；argv 透传、exit code 原样 |
+| `<persona-cmd>` / `cmd <name>` | **已实现** | 一级委派（内置优先）；`dia cmd` 只查外部命令，可绕开同名内置 |
+| `task add/list/status/done` | **已实现** | done 需 judge + evidence |
+| `team run --mock / --acp / --dsh`、`team gate/accept/reject` | **已实现** | 状态机 + 门禁；成功/失败路径均跑通 |
+| `job …` | **已实现** | 转发 `packages/job`（launchd/cron/schtasks） |
+| `patch …` | **未实现** | 当前 `unknown command`；设计见 `docs/patching.md` |
+| `ingest / audit / freeze / run / resume / price` | **已实现** | D0 阶段交付 |
+
+证据入口：`bun test tests`；`tests/kit.test.ts`、`tests/scope.test.ts`、`tests/env.test.ts`、`tests/active-doctor.test.ts`。
+
+## 5. 与安装文档的关系
+
+- 清单格式与安全规则见 `docs/persona-install.md`；
+- 入口与默认 agent 规则见 `docs/entrypoints.md`。

package/docs/dependency-registry.md

@@ -0,0 +1,105 @@
+# 外部依赖索引与原始记录维护（2026-10）
+
+> 日期 2026-10-28。回答两件事：**依赖怎么登记/验证/淘汰**，**原始记录怎么保留/重建/删除**。
+> 依据：CycloneDX 1.7 / SPDX 3.0.1 / npm lockfile / semver / PEP 387 / PostgreSQL PITR / Prometheus storage / GDPR 17 / NIST AU-11。
+
+---
+
+## 1. 依赖登记（`deps.jsonl`，只追加）
+
+每个依赖一行；**升级不改旧行，追加新行**（历史可追溯）。
+
+| 字段 | 类型 | 必填 | 说明 | 依据 |
+|---|---|---|---|---|
+| `id` | `kind:name@ver` | ✓ | 全局唯一 | CycloneDX `bom-ref` / SPDX `spdxId` |
+| `kind` | enum | ✓ | `host_cli / npm / bundle / endpoint / model / datastore / daemon` | CycloneDX 区分服务与组件 |
+| `version` / `resolved` | str / uri | ✓ | 实际解析结果 | npm lockfile |
+| `integrity` | `sha512-…` / commit | ✓（有产物时） | 内容哈希；**不能只靠名字** | npm `integrity`；semver §3 |
+| `role` | `required/optional/degradable` | ✓ | 缺失时的行为 | 设计"可缺，缺了降级" |
+| `fallback` | str | degradable 必填 | 降级路径 | 同上 |
+| `verified_at/by/method/result/evidence` | RFC3339/str/enum/pass\|fail\|unknown/path | ✓ | **验证三元组 + 证据** | SPDX `verifiedUsing`；CycloneDX citations |
+| `support` / `removal_after` | `active|deprecated|eol|unknown` / date | ✓ / deprecated 必填 | 淘汰宽限期 | npm deprecate；PEP 387 |
+| `depends_on` | [id] | ✓（可空） | 依赖图 | CycloneDX dependency graph |
+
+**局限（必须写进 README）**：SBOM 只回答"有什么、谁引入"，不回答"能不能跑"；lockfile 有 hash 无来源证明；`dpkg -V` 只做 md5 且依赖已有记录。
+
+### 单一事实源：`docs/deps.jsonl`
+
+一行一个 JSON 对象，**只追加**；同一 `id` 以最后一行为准（升级/复核都追加新行，不改旧行）。
+字段即上表；没有的字段省略，不写占位。
+
+```json
+{"id":"host_cli:opencode@2.2.5","kind":"host_cli","version":"2.2.5","resolved":"command:opencode","integrity":"unknown","role":"required","verified_at":"2026-11-03","verified_by":"min","method":"smoke","result":"pass","support":"active","evidence":"docs/platforms/registry.json"}
+```
+
+规则：
+
+1. `resolved` 用**可移植写法**（`command:opencode`、`~/...`），不写死某台机器的绝对路径。
+2. 人读视图由 `dia doctor` 派生（`deps` 项，`--json` 给机器）；**本文不抄登记数据**。
+3. `dia doctor` 判定：required 缺失 = `fail`；版本/路径漂移 = `warn`；可选未装 = note（不拉红）。
+4. 追加用 `dia deps record`（`--id/--kind/--version` 必填；`verified_at` 自动填当天，`method=manual`）；
+   看现状用 `dia deps list [--json]`（登记 + 实测，required 缺失 exit 2）。
+
+---
+
+## 2. 生命周期判据
+
+| 步 | 判据 |
+|---|---|
+| 登记 | id 唯一 + source + integrity；缺就记 `unknown`，不猜 |
+| 探测 | 存在 + 版本符合 + smoke 通过 → `active`；版本不符 → `degraded`；required 缺失 → **非 0 退出**（exit 30） |
+| 启用 | `verified_at` ≤90 天 且 integrity 复核一致 |
+| 升级 | 新 id（版本/hash 变），旧行保留；**禁止原地改写** |
+| 废弃 | `support=deprecated` + `removal_after` ≥1 个 minor 周期 + 有替代 |
+| 移除 | 无 inbound `depends_on` + 有回滚路径 + 写审计 |
+
+---
+
+## 3. 原始记录维护
+
+```
+raw（不可变，只追加） → derived（可重建索引/摘要） → pointer（可删）
+```
+
+| 策略 | 做法 | 依据 |
+|---|---|---|
+| 压缩 | 事件日志 + 周期 checkpoint；重建 = 快照 + 重放 | PostgreSQL PITR |
+| 保留 | **按类别设期限**，不是全局一刀切；到期先降采样再删 | NIST AU-11 |
+| 删除 | 加密擦除（销毁密钥）+ tombstone，不改链；不可豁免时走 GDPR 17(3) 例外 | GDPR 17 |
+| 校验 | `prev_hash` 哈希链 + 每日摘要（可检出删行/回填） | 日志完整性实践 |
+| 验证 | 月度 replay + **restore drill**（临时 HOME 恢复 → doctor 全绿 → 重放 N 条） | PostgreSQL PITR |
+
+**本机现状（2026-10-28）**：dsh sessions 146MB/244 个、opencode.db 477MB/34 会话，**都没有统一保留策略**；先登记，再定 TTL。
+
+---
+
+## 4. 失败模式
+
+| # | 失败 | 触发 | 对策 |
+|---|---|---|---|
+| D1 | 漂移 | 只按命令名探测 | 用 hash/resolved 判定，不用名字 |
+| D2 | 静默升级 | unpinned + 无 hash | pin + 记录升级与验证 |
+| D3 | 源被删 | unpublish | 本地镜像 + hash；弃用优于下架 |
+| D4 | 哈希不符 | 内容被改 | 按篡改处理，隔离 + 审计，**不重算后接受** |
+| D5 | 保留过度 | 无到期动作 | `review_by` + 降采样 + 删除演练 |
+
+---
+
+## 5. 对 dia 现有设计的 5 条修正
+
+| # | 现状 | 修正 | 判据 |
+|---|---|---|---|
+| M1 | doctor（**待实现**）目前只看"命令在不在 + 版本" | 输出 `verified_at / method / by`；>90 天标 `STALE`；缺 integrity 标 `UNVERIFIED` | doctor 输出可被 `--json` 解析 |
+| M2 | **现状：冻结只写元数据快照，不含任何文件**；目标才是打包会话 | SQLite 需 `VACUUM INTO` 或连同 `-wal/-shm` 一起打包，否则丢已提交事务 | 恢复后行数一致 |
+| M3 | audit 只 append-only，无防篡改（**未实现**） | 加 `prev_hash` 链 + 每日摘要；删行/回填可检出 | 删一行后 `audit verify` 报链断 |
+| M4 | 截断只留索引，无重建路径 | 截断前先落 raw 归档（只写一次）+ 定义 replay 判据 | 能从归档还原被截条目的索引行 |
+| M5 | 工具只有 retired，无 deprecated 宽限 | 补 `support` + `removal_after`，禁止直接删 | 移除前必须有替代 + 回滚 |
+
+---
+
+## 6. 未验证 / 缺口
+
+- SLSA provenance 逐字段（本机不可达）
+- NIST SP 800-92 保留章节原文（PDF 不可读）
+- Nix 输入寻址原文（未验证）
+- opencode/dsh 自身是否有 TTL/GC：**未找到官方保留策略**

package/docs/deps.jsonl

@@ -0,0 +1,7 @@
+{"id":"host_cli:opencode@2.1.3","kind":"host_cli","version":"2.1.3","resolved":"/opt/homebrew/bin/opencode","integrity":"unknown","role":"required","verified_at":"2026-10-28","verified_by":"min","method":"smoke","result":"pass","support":"active","evidence":"docs/ecosystem-integration.md"}
+{"id":"host_cli:dsh@0.2.1-rc.2","kind":"host_cli","version":"0.2.1-rc.2","resolved":"fnm/node_modules/@deepseek-ai/dsh","integrity":"unknown","role":"required","verified_at":"2026-10-28","verified_by":"min","method":"smoke","result":"pass","support":"active","evidence":"docs/security-sandbox.md"}
+{"id":"npm:acpx@0.21.1","kind":"npm","version":"0.21.1","resolved":"npm:acpx","integrity":"pending","role":"optional","fallback":"shell 驱动各宿主 CLI","verified_at":"2026-10-28","verified_by":"min","method":"smoke","result":"pass","support":"active","evidence":"docs/review/reuse-review.md"}
+{"id":"bundle:@example/dsh-watchdog@0.1.0","kind":"bundle","version":"0.1.0","resolved":"link:~/.yan-agent/repos/yan-agent/platform/dsh/files/dsh-watchdog","integrity":"unknown","role":"optional","verified_at":"2026-10-28","verified_by":"min","method":"source-review","result":"unknown","support":"unknown","removal_after":"2026-11-04","evidence":"docs/review/reuse-review.md"}
+{"id":"datastore:opencode.db","kind":"datastore","version":"unknown","resolved":"~/.local/share/opencode/opencode.db","integrity":"unknown","role":"optional","verified_at":"2026-10-28","verified_by":"min","method":"smoke","result":"pass","support":"active","evidence":"docs/evolution-process.md"}
+{"id":"datastore:dsh-sessions","kind":"datastore","version":"v4","resolved":"~/.dsh/sessions/**/session.v4.jsonl.zstd","integrity":"unknown","role":"optional","verified_at":"2026-10-28","verified_by":"min","method":"smoke","result":"pass","support":"active","evidence":"docs/evolution-process.md"}
+{"id":"host_cli:opencode@2.2.5","kind":"host_cli","version":"2.2.5","resolved":"command:opencode","integrity":"unknown","role":"required","verified_at":"2026-11-03","verified_by":"min","method":"smoke","result":"pass","support":"active","evidence":"docs/platforms/registry.json"}