@minonl/dia 0.0.0-stage → 0.0.1

package/docs/ecosystem-integration.md

@@ -0,0 +1,155 @@
+# 生态与组合：可复用性调研（2026-10）
+
+> 日期 2026-10-28。问题：dia 的包和集成面应该长什么样，才能同时服务 opencode / dsh（未来 OpenClaw/Hermes/Pi）？
+> 结论先行：**没有可执行插件的统一 ABI；唯一跨家通用的是 `SKILL.md`。跨家项目全是"manifest → codegen"，且都很年轻。dia 只做两只宿主 + codegen。**
+
+---
+
+## 1. 五家扩展模型
+
+| 宿主 | 插件形态 | 技能形态 | 安装 | 版本/锁 | 证据 |
+|---|---|---|---|---|---|
+| **opencode** 2.1.3 | JS/TS 包（V2 分 server/tui/gui/rpc 四 part）；npm 或本地目录 | AgentSkills 目录（`.opencode/skills`、`.claude/skills`、`.agents/skills`） | `opencode plugin add/list/check/update/remove` | 精确版本即 pin；无签名（未找到） | A（本机 help + 官方 docs） |
+| **OpenClaw** | 代码包 `openclaw.plugin.json`，可自带 skills | AgentSkills + `metadata.openclaw`（gating/installer） | `openclaw plugins install`、`skills install` | `.clawhub/lock.json` + `--pin` + digest | A/C |
+| **Hermes** | Python 目录 `plugin.yaml` + `__init__.py`；平台插件在 `plugins/platforms/` | `.hermes/skills`、`.agents/skills`（需 trust） | `hermes plugins install`；skills `search/update/tap` | **40 位 commit SHA 钉死**、official/verified/community 分级、`removed.yaml` | A |
+| **Pi** | TS extension（jiti 同进程加载） | `~/.pi/agent/skills`、`.agents/skills` | `pi install npm:@x@1.2.3` | project trust + tag | A |
+| **dsh** 0.2.1-rc.2 | bundle = npm/本地包 + `cordis.patch.yml` 声明层（纯声明可无代码） | 自有 skills 目录 + skill-discovery 插件 | `dsh plugin --profile P add <pkg>`（转发 pnpm）；plugin_manager 每次审批 | `pnpm-lock.yaml` | A（本机源码） |
+
+**关键事实**：
+- opencode **V1→V2 是断代**（"V1 implementations do not run in V2"），配置键与 hook API 全变。
+- Pi 的扩展**与宿主同进程、同 OS 权限**（官方 security.md 自认）。
+- dsh 的 bundle 可以**纯声明**（只有 `cordis.patch.yml`，无代码），也可以带 npm 依赖；yan 已用它装了 5 个包。
+- 本机 dsh 事故（yan 侧记录）：patch 覆写 preset 会导致全部 agent 掉工具，需冷启动。
+
+---
+
+## 2. 跨家复用项目（都在很早期）
+
+| 项目 | 连接 | 机制 | ★ / 下载 | 日期 | 备注 |
+|---|---|---|---|---|---|
+| **AgentPlugins**（sigilco，Apache-2.0） | Claude / Codex / OpenCode / Pi | 统一 manifest → 生成各家插件 | 11★ / npm 11 周下载 | 2026-10-08 | 目标最接近我们；**不含 dsh** |
+| **everyharness** | 12 家（含 Hermes/OpenCode/Pi） | manifest + drift validate | 38★ / 10 周下载 | 2026 | 有 validate 概念，可借鉴 |
+| **plugsdk** | 多宿主 | 18 类 hook 抽象 | 101 周下载 | 2026 | — |
+| **pluxx** | MCP → 4 家 | 把 MCP 转成宿主原生 | 小 | 2026 | — |
+| **Tome** | 17 家 | MCP + rules | 小 | 2026 | — |
+| **rulesync** | OpenCode / Claude 等 | 配置/规则**双向同步**（非可执行插件） | **1558★** | 2026-10-27 | 成熟度最高，但只同步配置，且有损 |
+| `hermes-opencode-acp` | Hermes ↔ opencode | `opencode acp` 子进程后端 | 10★ | 2026 | 本文档 §4 |
+
+**结论**：
+1. **可执行插件没有统一 ABI**，所有跨家方案都是"编译/生成"，不是"运行时加载"。
+2. 这些项目全在 10–40★ 量级，**唯一成熟的是配置同步（rulesync）**。
+3. **没有任何项目支持 dsh** —— 这是我们的空位，但空位小，不值得为它发明标准。
+
+---
+
+## 3. 安装与信任（决定包设计）
+
+| 宿主 | 安装时是否执行代码 | 签名/哈希 | 已知事故 |
+|---|---|---|---|
+| opencode | **是**（npm 启动即执行） | 无（未找到） | #59251 插件名被当包安装、#58574 静默丢弃、#58045 V2 模块无效 |
+| OpenClaw | 是（installer 真跑 brew/npm/go/uv/download） | ClawHub digest + pin | **ClawHavoc**：341→824 恶意 skill，靠"伪造前置依赖"诱导执行 |
+| Hermes | 是 | SHA pin + 分级 + 拉黑 + capability 声明 | Desktop 插件**无沙箱** |
+| Pi | 是（同进程） | project trust | 官方："full system access" |
+| dsh | 是（pnpm） | lockfile | patch 覆写 preset 事故 |
+
+**对 dia 的硬规则**：
+- 包**默认无执行权**；安装只落盘（不跑 install script）。
+- 必须声明 `capabilities`（tools/hooks/env/network），启用需人工批准。
+- 内容哈希进 `dia.lock`；`dia persona verify` / `dia kit verify` 可复现。
+
+---
+
+## 4. 集成面：ACP 是事实标准，MCP 只是工具层
+
+### 4.1 ACP 服务端（谁能被驱动）
+
+| 宿主 | 入口 | 状态 | 证据 |
+|---|---|---|---|
+| opencode | `opencode acp`（stdio） | 官方，可用 | A（本机 help） |
+| OpenClaw | `openclaw acp`（stdio → Gateway WS） | 官方；`loadSession` 部分实现、per-session MCP 不支持 | A |
+| Hermes | `hermes acp` | 官方，可用 | A |
+| dsh | `dsh-acp-app`（JSON-RPC stdio） | 官方包；社区另有 `deepseek-harness-acp`(53★)、`dsh-acp-interactive`(87★) | A/C |
+| Pi | 需 `pi-acp`（747★，MVP）→ 内部 `pi --mode rpc` | 社区，可用但会小破坏 | C |
+
+### 4.2 ACP 客户端（谁能驱动别人）
+
+- **openclaw/acpx（3395★，MIT）**：通用 ACP 客户端，内置 `opencode`（`npx opencode-ai acp`）、`pi`（`npx pi-acp`）、`openclaw` 目标。**这是最成熟的一块，不该重写。**
+- 编辑器/客户端生态：Zed、`vscode-acp`(406★)、`obsidian-agent-client`(2462★)、`acp-ui`(502★)、`agentic.nvim`(643★)、`wechat-acp`(851★)。
+- SDK：TS(266★) / Python(341★) / Rust(230★) / Kotlin(97★) / Java(78★)，另有 TCK。
+
+### 4.3 编排器（多引擎）
+
+| 项目 | 连接 | 机制 | ★ | 状态 |
+|---|---|---|---|---|
+| **AionUi** | OpenClaw/Hermes/opencode/Pi + 20 余 CLI，Team Mode | ACP + MCP stdio | 33832 | 桌面应用，可用 |
+| **orca** | Codex/Claude/opencode/Pi，每任务独立 worktree | CLI + worktree | 108130 | 可用 |
+| **cc-switch** | 五家 provider/MCP/Skills 配置 | 纯配置渲染 | 149424 | 可用（不是桥） |
+| **codeg** | 20 个 agent + 任意 ACP，会话聚合 | ACP + 结构化渲染 | 4156 | 可用 |
+| **claw-orchestrator** | 六引擎含 dsh | `engine:'acp'` 预设 + 验收判据 | 601 | 可用 |
+| **harness-remote** | 六家，远程接管原生 session | 会话控制面 | 425 | 可用 |
+
+### 4.4 空位（没人做）
+
+1. **Hermes ↔ dsh / Pi ↔ dsh / Hermes ↔ Pi**：没有专用桥。
+2. **跨引擎会话移交**（A 引擎的 session 交给 B 续跑）：只有 `harness-remote` 在单引擎内做。
+3. **纯 CLI 的多引擎团队编排**：AionUi 是桌面应用，其余多是单任务启动器；**没有一个"无 GUI、按角色分工、带验收判据"的 CLI 编排器**。
+
+### 4.5 风险
+
+- `acpx` 自述 **pre-1.0**，CLI 会变。
+- `pi-acp`、dsh 的两个 ACP 桥都是单人/低星项目，不能当硬依赖。
+- **ACP 同名歧义**：Agent Client Protocol vs Virtuals 的 Agent Commerce Protocol（后者 `openclaw-acp` 已废弃）。选型只认 `agentclientprotocol`。
+
+### 4.6 对 dia 的位置
+
+- **先做 ACP server**（能被任何客户端驱动），而不是自己实现 client 去驱动五家。
+- 需要调用别人时，**用 `acpx` 作为外部可执行**，dia 只负责策略/审计/会话记录，不内嵌 ACP 协议栈。
+- dia 的机会是 **4.4 的第 3 条**：CLI-only、按角色、带验收判据的编排——但这是"编排层"，不是框架核心，应放在 dia 之上而不是 dia 里面。
+
+## 5. Persona / Kit 格式（v0）
+
+```
+persona/
+├── dia.json                  # schema/kind=persona/id/version/hosts/capabilities/entry/kits
+├── agents/<id>.md            # opencode agent
+├── platform/dsh/<id>-persona/  # dsh bundle
+└── dia.lock                  # 生成物：逐文件 sha256
+
+kit/
+├── dia.json                  # kind=kit
+├── skills/<name>/SKILL.md    # AgentSkills 原样
+├── knowledge/**.md
+├── bin/                      # 可选工具（默认无执行权）
+└── dia.lock
+```
+
+命令：
+
+```
+dia persona add <id> --from <git-url> --ref <sha>
+dia persona render <id> --host opencode|dsh
+dia persona verify|remove|list
+dia kit add|verify|remove|list
+```
+
+**渲染而非运行时适配**：只维护 opencode 与 dsh 两只宿主；每次 render 比对哈希，宿主 API 变了就重渲染，而不是写兼容层。
+
+## 6. 明确不做
+
+1. 不做运行时插件适配层（opencode V2 仍在动，等于给自己加第二个漂移源）。
+2. 不做公共市场（ClawHavoc 的教训）。
+3. 不为 dsh 发明私有标准；dsh 就用它的 bundle 格式。
+4. 不在安装时执行任何脚本。
+
+---
+
+## 7. 待验证 / 缺口
+
+| 项 | 状态 |
+|---|---|
+| dsh bundle 的 `cordis.patch.yml` 完整 schema 与冲突规则 | 部分（本机 yan-preset/watchdog 可参考） |
+| opencode V2 插件 API 的稳定性 | 已知在动（三条 issue） |
+| ACP client 侧成熟度 | 仅社区项目（10★） |
+| 跨家可执行插件的真实需求 | **未验证**（没有用户案例） |
+
+> 结论：**包格式现在就该定，但只做"manifest + skills + knowledge + lock"四件；执行交给宿主的原生机制。**

package/docs/ecosystem-positioning.md

@@ -0,0 +1,95 @@
+# 生态定位：我们落在哪，接谁、不接谁
+
+> 日期 2026-10-28。
+> 一句话：**dia 不做通道、不做运行时、不做记忆产品；dia 做"进化的控制面"——观测、审计、基准、门禁。**
+> 长期形态（superagent / agent-team 工厂、fleet 对接）见 [`vision.md`](vision.md)；本文的"不做"边界仍然有效。
+> 通道用 dws-hub，执行用 dsh/opencode，其他 agent 只当可选后端。
+
+---
+
+## 1. 各家真正擅长什么（不是宣传语）
+
+| 工具 | 真正擅长 | 代价 / 风险 | 证据 |
+|---|---|---|---|
+| **dws-hub**（本地） | 钉钉 Stream 长连接、消息落盘、launchd 常驻 | 只覆盖钉钉；需桥接层 | 本机 launchd + plist |
+| **dsh** | 插件树（Cordis）、事件溯源会话、沙箱/审批/断点、ACP | 生态小、文档少 | 本机源码 |
+| **opencode v2** | 会话 daemon、project/location 作用域、TUI/客户端生态、SDK | 单点共享 daemon、版本断代 | 本机 + 官方文档 |
+| **OpenClaw** | **多通道接入**（WhatsApp/Telegram/Slack/Discord…）、常驻 gateway、automations | 重；供应链事故（ClawHavoc）；CVE-2026-25253 | 取证文档 |
+| **Hermes** | **长期记忆 + 自建技能闭环**（3575 字符硬顶、Curator） | 重；两套执行路径；CVE 未修复、厂商未回应 | 取证文档 |
+| **Pi** | **极简 coding harness**：核心小、扩展优先、TS 原生、prompt cache、ACP（`pi-acp`） | 无内建沙箱/审批；fail-open；无通道 | 取证文档 |
+
+**Pi 的好点**（回答你的问题）：不是记忆，也不是通道，而是**"薄内核 + 扩展"**：
+- 核心极小，能力靠 extension 拼；
+- 同进程扩展（灵活但危险）；
+- 模型目录 + prompt cache 做得细；
+- `pi-acp` 让它能被 ACP 驱动。
+它适合当**编码执行体**，不适合当常驻消息入口。
+
+---
+
+## 2. 常驻入口：用 dws-hub，不用别的
+
+| 方案 | 能给你什么 | 代价 | 结论 |
+|---|---|---|---|
+| **dws-hub + launchd + dsh/opencode** | 本地、已在跑、可控、可审计 | 需要写一个 bridge（消息→任务→回复） | **推荐** |
+| OpenClaw | 多通道开箱即用 | 引入第二套运行时/技能/安全面 | 不现在接 |
+| Hermes | 通道 + 记忆 + 技能 | 同上，且有未修复 CVE | 只做研究参考 |
+| Pi | 极简编码 | 无通道、无审批 | 可当编码后端（ACP） |
+
+**推荐链路**：
+
+```
+钉钉消息 → dws-hub（已有长连接）→ inbox 落盘
+        → dia bridge（launchd/定时或事件触发）
+        → 任务（ledger）+ 审计（dia run）
+        → 执行后端：dsh headless（批处理）/ opencode 会话（交互）
+        → 草稿回复（draft-only）→ 人工确认 → dws 发送
+```
+
+**为什么不直接用 OpenClaw 的 gateway**：
+- 它的价值是"多通道"，我们只需要钉钉一条；
+- 它自带运行时/技能/记忆，会和 dia 的策略层重复；
+- 安全面大（CVE + 供应链），与我们"审计优先"冲突。
+
+---
+
+## 3. dia 的生态位
+
+```
+通道（dws-hub）→ 控制面（dia）→ 执行体（dsh/opencode/ACP 后端）→ 证据/基准/知识
+```
+
+dia 只做四件事：
+1. **观测与记录**：会话、工具、失败、成本（不复制真相，只索引）。
+2. **审计与止血**：seam 上的判定、冻结、豁免、证据。
+3. **基准与漂移**：ModelSpec、baseline、事故 canary、观察名单。
+4. **门禁与进化**：判据、独立验证、假设台账、回滚。
+
+**不做**：通道实现、会话运行时、模型服务、技能市场、记忆产品。
+
+---
+
+## 4. 未来对接策略：适配，不吞并
+
+| 对象 | 怎么接 | 前提 |
+|---|---|---|
+| OpenClaw | 当 **ACP 端点/通道适配器**；只读收消息，草稿回复 | 不引入其技能市场；审计覆盖其工具调用（做不到就只观测） |
+| Hermes | 当 **ACP 端点**；只借鉴记忆/技能机制，不接管 | 版本固定；CVE 未修复前不跑高权限 |
+| Pi | 当 **编码执行体**（`pi-acp`） | 只跑隔离任务；无审批，需外层 gate |
+| dsh | 主执行体 | 已定 |
+| opencode | 交互式会话后端 | 已定 |
+
+**接入判据（任一条不满足就不接）**：
+1. 能被 ACP 或 CLI 黑盒驱动；
+2. 工具调用可被审计（至少可观测）；
+3. 版本可钉、可回滚；
+4. 不要求我们复制它的记忆/技能体系。
+
+---
+
+## 5. 一句话回答
+
+- **常驻启动**：用 **dws-hub + launchd + dsh/opencode**，不引入 OpenClaw/Hermes/Pi。
+- **会话转发**：dws-hub 负责通道，dia 负责策略与证据；转发是 bridge 的活，不是 agent 的活。
+- **生态位**：**个人进化的控制面**，不是又一个 agent 框架。
+- **未来对接**：只做 ACP/CLI 适配器，不吞并它们的运行时。

package/docs/entrypoints.md

@@ -0,0 +1,83 @@
+# 用户入口：人在哪进，agent 叫什么
+
+> 日期 2026-10-28。
+> 一句话：**入口仍是 opencode/dsh（和 yan 一样），但 agent 名是 `dabo`，不是 `dia`；`dia` 是控制面命令，不是人格。**
+>
+> **2026-11-03 复核**：终端入口已落地（`~/.config/opencode/agents/dabo.md` + `~/.dsh/profiles/dabo`）；
+> IM bridge 仍未写；文中出现的 `dia status` / `dia model` **不存在**，观测入口目前是 `dia doctor`。
+
+---
+
+## 0. 三个名字别混
+
+| 名字 | 是什么 | 用户会怎么遇到 |
+|---|---|---|
+| **dabo** | 个人域 agent（人格 + 域知识 + 工具） | 在 opencode/dsh 里选 agent |
+| **yan** | 工作域 agent | 同上（已有） |
+| **dia** | 框架/控制面（知识、审计、基准、门禁） | 命令行 `dia ...`，不是聊天对象 |
+
+所以：**不会出现"选 dia agent 聊天"**；用户选的是 `dabo` 或 `yan`。
+
+---
+
+## 1. 入口矩阵
+
+| 入口 | 形态 | 跑什么 | 现状 |
+|---|---|---|---|
+| **终端（主）** | `opencode`（agent=dabo）/ `dsh`（profile=dabo） | 交互式会话 | **已渲染**（yan 同构，profile 3091；dabo 端口动态） |
+| **IM（异步）** | 钉钉 → dws-hub → dia bridge | 建任务 → 后端执行 → 草稿回复 | bridge 未写 |
+| **自动化** | launchd → `dsh headless` / `dia run` | 批处理、canary、巡检 | 部分有 |
+| **控制面** | `dia doctor` / `audit` / `kb` / `price` | 观测、审计、知识、计价 | 已有（`status` / `model` 未实现） |
+
+**没有第四种"dia 自带界面"**：dia 不拥有运行时，也不做 TUI。
+
+---
+
+## 2. 终端入口：和 yan 完全同构
+
+```
+opencode:  ~/.config/opencode/agents/dabo.md     （persona + 工具 + permission）
+dsh:       profile bundle: dabo-preset           （dsh-agent-preset + persona + 域插件）
+```
+
+选择方式：
+- opencode：切 agent 到 `dabo`（或 `opencode --agent dabo`）。
+- dsh：profile 选择 / preset `dabo`。
+
+**与 yan 的差别只在内容**：`dabo` 用个人域知识与策略；机制一样。
+
+---
+
+## 3. IM 入口：不是另一个 agent
+
+```
+钉钉消息 → dws-hub（通道，常驻）
+        → dia bridge（消息 → 任务；不做语义）
+        → 选后端（dsh/opencode/ACP）
+        → 产出草稿 → 人工确认 → 发送
+```
+
+- bridge 不扮演 agent，不写人格；
+- 回复默认 **draft-only**；
+- 会话记录进同一套 episodes/audit。
+
+---
+
+## 4. 配置失败时的入口体验
+
+| 失败 | 用户看到 | 行为 |
+|---|---|---|
+| dabo preset 未渲染 | `dia doctor` 报 `preset dabo missing`；opencode 里看不到 `dabo` | **不静默回退到默认 agent**；提示渲染命令 |
+| ACP 不可用 | `dia run` 报错，不静默回退 | 交互可用，审计降级（degraded 状态未实现） |
+| dws-hub 未运行 | bridge 未写，无入口 | IM 入口不可用，终端入口不受影响 |
+| 策略未加载 | **拒绝高风险动作**（不是回退到无策略） | 只读/草稿可用 |
+
+原则：**入口可以少，策略不能悄悄没。**
+
+---
+
+## 5. 落地顺序
+
+1. 渲染 `dabo` preset（opencode md + dsh bundle），先能在终端里选到；
+2. 写 `dia bridge`（IM 入口），默认 draft-only；
+3. `dia doctor` 增加入口自检：preset 是否存在、ACP 是否握手、dws-hub 是否心跳。

package/docs/evolution-process.md

@@ -0,0 +1,298 @@
+# 进化：dia 的第一性定位
+
+> 日期 2026-10-28。本文不是功能清单，是**过程定义**。
+> 生态位（框架/插件/ACP）是自然落点，不是目标；能力只有在过程需要时才被引入。
+
+---
+
+## 1. 一句话
+
+> dia 维护的不是"一个 agent"，而是一个**可观测、可回溯、可自我调整的进化过程**。
+> 人和电子脑是这个过程的两个引擎，长期磨合的产物才是产出。
+
+判据不是"功能做完了"，而是：**下一次同类问题，系统是否比上次少犯一次错、少花一次时间、少一次人工介入。**
+
+---
+
+## 2. 循环（七段，缺一段就不叫进化）
+
+```
+        ┌────────────── 意图锚点 Intent（人工，只读）──────────────┐
+        │                                                          │
+        ▼                                                          │
+   观测 Observe ──> 记录 Record ──> 蒸馏 Distill ──> 评审 Review ──┤
+        ▲                                              │           │
+        │                                              ▼           │
+   调整 Adjust <── 度量 Measure <── 尝试 Try <──────────┘           │
+        │                                                          │
+        └────────────── 历史锚点 History（只追加）──────────────────┘
+```
+
+| 段 | 做什么 | 产物 | 归属 |
+|---|---|---|---|
+| **观测** | 会话、失败、用户纠正、外部生态变化 | `observations`（原始，脱敏） | agent |
+| **记录** | 归一为 episode；不可变 | `episodes.jsonl` | agent |
+| **蒸馏** | 从 episode 提候选经验/假设，**不是结论** | `candidates` / `hypotheses` | agent 起草 |
+| **评审** | 双引擎：证据分级 + 对抗 + 裁决 | `review` 记录 | 人 + agent |
+| **尝试** | 最小改动/实验，可回滚 | `experiments` / `evo-*` | agent 执行 |
+| **度量** | 指标 + 回归 + 意图漂移 | `metrics` | 脚本 |
+| **调整** | 采纳/回滚/归档；写回历史 | `history` | 人批 |
+
+**两个锚点**：
+- **意图**（为什么做）：人工维护，agent 只读；任何改动与意图冲突 → 必须人工裁决。
+- **历史**（发生过什么）：只追加，不覆盖；"铭记历史"不是口号，是**不可变日志 + 可检索**。
+
+---
+
+## 2.1 V 型协作结构（补充模型）
+
+```
+                人（顶端：意图 / 价值 / 裁决 / 停手）
+               /                                  \
+      下降臂（尝试/探索/试错）          上升臂（请示/汇报/交还决策）
+               \                                  /
+                谷底：任务目标（可能触底，也可能永远触不到）
+```
+
+- **AI 在两臂之间跑线**：下降 = 推进尝试；遇到无法绕开的障碍 = 沿上升臂回到人请示；人给决策后再下降。
+- **触底**不是唯一成功：到达某一深度并**记录障碍类型**，也是有效产出。
+- **上升不是失败**，是**决策采样**：每次请示都在标注"哪类障碍必须由人裁定"。
+- **深度**是连续量（0–100%），不是二元成败；同一任务族的历史深度分布，比"成功/失败"更有信息。
+
+### 2.1.1 多维状态：角色 × 任务图 × 观测效应
+
+V 型是二维投影。真实状态至少是三元组：
+
+```
+State = (T, D, O)
+  T：任务图（不是任务列表）
+  D：深度矩阵 D[观测者][任务节点] ∈ [0,1]
+  O：观测事件及其对 T/D 的影响
+```
+
+#### 维度一：角色 = 观测角度
+
+| 观测者 | 看到什么 | 常见偏差 |
+|---|---|---|
+| 人 | 目标价值、外部约束、停手时机 | 低估实现细节的深度 |
+| 主 agent | 计划与已完成步骤 | 高估推进（把"做了"当"有效"） |
+| 子 agent | 自己负责的分量 | 局部最优、看不到全局权重 |
+| 系统/脚本 | 可度量指标 | 只测可测的，漏掉意图 |
+
+**规则**：不取平均。`Δ = max(D[o][t]) - min(D[o][t])`。
+对齐优先级 = **`Δ × 该判定的错误成本`**（Horvitz 1999），阈值**预注册**；
+**不设拍脑袋的 0.3**（原阈值无文献依据，已撤回）。
+另：`Δ≈0` 不能证明"都对"——也可能是**共谋**（Lee & See 2004）；必须配合盲复核。
+
+#### 深度不是标量：按四类功能分别记
+
+Parasuraman/Sheridan/Wickens (2000) 的 types×levels：**信息获取 / 信息分析 / 决策 / 执行**各自定级。
+禁止输出单一"深度分"；矩阵必须是 `D[observer][task][function]`。
+
+#### 维度二：任务图（会生长、会消失、会聚合、会发散）
+
+任务不是固定列表，是有生命周期的图：
+
+```yaml
+task:   { id, parent, origin, weight, status }
+# origin: original | derived | merged | split | observation-induced
+# weight: 该节点占目标的比例（可随时间变化）
+```
+
+- **新增**：agent 发现的新前提（如"先修 CI 才能发版"）；
+- **消失**：前提被证伪、或目标变更；
+- **聚合**：其他任务并入（范围变大）；
+- **发散**：一个节点裂成多个（范围变大但更清晰）；
+- **观测诱发**：因为我们观察/度量而新增的任务（见下）。
+
+**规则**：`派生比 = Σweight(derived + observation-induced) / Σweight(original)`。
+派生比持续升高 = 目标在漂移，必须先压缩/收敛，不许继续扩张。
+
+#### 维度三：观测效应（系统自己成为变量）
+
+观测不是免费的：一次度量可能
+1. 改变任务图（新增"验证/记录/清理"任务）；
+2. 改变深度估计（看到更多细节 → 深度反而下降）；
+3. 改变后续行为（被观测者知道被观测）。
+
+因此每次观测都记一条事件：
+
+```yaml
+event: { type: observe|add|remove|merge|split|reweight, cause, actor, ts,
+         intent_id, judge_id, upstream_artifact_ids,   # provenance（MHC tracing）
+         sa_level: L1|L2|L3,                            # 情境意识层级（可选）
+         effect: { added: [], removed: [], reweighted: [] } }
+```
+
+**规则**：`观测诱发变更率 = 有 effect 的观测 / 总观测`。
+过高 → 降低观测频率或改成抽样；否则系统会陷入"为了看清楚而制造更多工作"的循环。
+
+#### 由此新增的指标
+
+| 指标 | 公式 | 用途 |
+|---|---|---|
+| 观测分歧 Δ | max-min 深度（按任务×功能） | 按 `Δ × 错误成本` 排序对齐 |
+| 派生比 | derived+observation-induced 权重 / original 权重 | 升高 = 目标漂移 |
+| 任务图 churn | (add+remove+merge+split) / 周 | 过高 = 结构不稳 |
+| 观测诱发变更率 | 有 effect 的观测 / 总观测 | 过高 = 观测成本失控 |
+| 聚焦熵 | 注意力在各节点上的分布熵 | 过高 = 失焦 |
+
+### 2.1.2 存储原则：不重复存放会话
+
+```
+真相层（不归 dia 所有）：
+  opencode  session/message/part  →  ~/.local/share/opencode/opencode.db
+  dsh       session.v4.jsonl.zstd →  ~/.dsh/sessions/<workspace>/
+
+索引层（dia 所有，可重建）：
+  state/events.jsonl     只追加：任务图变更 / 深度上报与复核 / 观测影响 / 决策
+  state/index.db         派生索引（FTS/聚合视图），删掉可重建
+  state/snapshots/       有期限的完整备份（默认 30 天，只为回放/回填）
+
+引用：raw_ref = {source, session_id, part_id?}
+```
+
+**规则**：
+
+1. **不复制 transcript**：dia 只存引用 + 事件；原文永远回源读。
+2. **索引可重建**：删除 `index.db` 与 `snapshots/`，能从"源会话 + events"重建出同样的视图（哈希一致）。
+3. **备份有期限**：完整备份只为"源被删/升级不兼容"时回放，默认 30 天，到期自动清；它不是事实源。
+4. **视图是聚合**：`task_graph` / `depth_matrix` / `Δ` / `derived_ratio` / `obs_effect_rate` 都是事件流上的投影，不单独存事实。
+
+事件 schema（v0）：
+
+```yaml
+id: <hash>
+ts: ISO
+actor: human | agent | subagent | system
+type: task.added | task.removed | task.merged | task.split | task.reweighted
+    | depth.reported | depth.reviewed
+    | observation.effect
+    | decision.made
+task: { id, parent, origin, weight }
+depth: { observer, task, value, basis }
+effect: { added: [], removed: [], reweighted: [] }
+ref: { source, session, part? }
+```
+
+### 2.2 不完整过程也是产出
+
+每次 attempt 记录：`{task, depth, obstacle, decision_needed, human_decision, cost, evidence, judge_version}`。
+
+三类可复用资产：
+1. **深度先验**：这类任务通常能到多深、在哪一层卡住；
+2. **障碍清单**：哪类障碍必须回人（而不是继续试）；
+3. **决策日志**：人当时怎么裁定、依据是什么。
+
+**判据公开（"公示"）**：同一套判据可以对历史 attempt 重新评分——所以旧的失败在新判据下可能变成有效证据。
+这也是"铭记历史"的实际用法：不是留着日志，而是**能重打分**。
+
+### 2.3 实例爆炸 → 系统性索引压缩
+
+三层，越往下越贵、越少：
+
+| 层 | 内容 | 保留 | 压缩方式 |
+|---|---|---|---|
+| **原始** | observations / episodes | TTL 30 天 | 按签名去重 |
+| **先验** | 聚类后的深度/障碍先验 | 长期 | 同族 ≥N 触发；保留深度分布 + 代表样例指针 |
+| **决策** | 人的裁定与理由 | 永久 | 只追加，不改写 |
+
+压缩后只保留：`签名 / 深度分布 / 障碍类型 / 代表样例指针 / 判据版本`。
+目标：存储 O(instances) → O(priors)，检索与决策成本不随实例数线性增长。
+
+## 3. 两个引擎的分工
+
+| | 人脑 | 电子脑 |
+|---|---|---|
+| 强项 | 意图、价值判断、阈值、承担责任 | 规模观测、一致性检查、快速起草、反复重试 |
+| 职责 | 定"为什么"、批"能不能"、裁决冲突 | 做"看见"、"记录"、"提候选"、"跑实验" |
+| 失败模式 | **忘记初心**（意图漂移）、疲劳漏看 | **优化代理指标**（刷分）、讨好人类、记忆腐烂 |
+| 对策 | 意图锚点 + 定期复核 | 对抗审计 + 独立证据 + 回归门禁 |
+
+**磨合**的定义：不是"人机对话变顺"，而是**同样的判断，第二次比第一次更快、更一致、更有据**。
+
+---
+
+## 4. 进化指标（不做 productivity 指标）
+
+| 指标 | 定义/公式（必须能从事件算） | 健康信号 |
+|---|---|---|
+| 观测覆盖率 | 被记录的事件 / 实际发生的事件 | ↑ |
+| 经验产出率 | candidates / 100 episodes | 稳定，不追求高 |
+| **推翻质量** | `有效推翻 / (有效推翻 + 误报)`；单看推翻率不采纳（防 Goodhart） | 稳定且 >50% |
+| 重试成功率 | 失败后重试成功 / 总重试 | ↑ |
+| 回归率 | 改动导致旧能力退化 / 总改动 | ↓ |
+| **意图漂移** | 与意图锚点冲突的决策数；**意图变更的 actor 必须是人**（agent 写入数 >0 即失败） | 0 |
+| 信任度 | 审计通过率、豁免率、冻结次数 | 豁免率 ↓ |
+| 人工介入率 | 需要人处理的步骤 / 总步骤 | ↓，但**意图变更 100% 由人发起** |
+| **校准** | 自报 vs 盲复核的 ECE / Brier；ICC(2,k) | 替代"深度达成"；盲复核必须异源 |
+| 深度达成 | 任务族的四类功能中位深度 | 分开报，不合成单一分数 |
+| 请示质量 | 回人的障碍里"必须人裁定"的比例（其余应继续试） | ↑ |
+| 部分产物复用率 | 被后续 attempt 引用的失败 attempt / 总失败 | ↑，但需配下游返工率 |
+| 压缩比 | 先定义"信息量 vs token"，否则不测 | ↑，但检索命中率不能掉 |
+| 检索命中率 | 先验被正确召回 / 总召回请求 | ≥90% |
+| 边际深度 | 每次尝试带来的深度增量 | 趋近 0 时应停止/换路 |
+| 共谋信号 | ①人推翻"秤"通过结论的次数 ②人回答 agent 问题的平均字数 ③连续无分歧任务数 | ①=0；②≥20 字；③<10 |
+
+> 不进指标的东西：功能数量、代码行数、提交数。
+> **规则**：没有对应事件（`core/events.yaml`）与公式的指标，不进表；宁可不测，不测空话。
+
+---
+
+## 5. 能力引入的规矩（针对"拿来主义"）
+
+**任何外部能力（库、插件、协议、别人的引擎）都先当假设，不当结论。**
+
+引入前必须有一份 **REUSE ADR**（见 `docs/review/reuse-review.md`），至少包含：
+
+1. 主张（我们要复用它做什么）
+2. 证据级别（A 源码/官方 / B 官方博客 / C 第三方 / D 传闻）
+3. **本地探测结果**（命令 + 输出；没跑就写"未验证"）
+4. 失败模式（它坏了/变了/被弃用，我们怎么办）
+5. 耦合代价（版本、许可证、维护者数量、退出成本）
+6. 裁决：`adopt` / `adapt` / `reject` / `defer`（defer 必须写复查日期）
+
+没有本地探测的复用，只能标 `defer`，**不许进主路径**。
+
+---
+
+## 4.1 请示与打断（理论约束）
+
+- **请示三件套**：不确定性 / 候选及代价 / 推荐项（Horvitz 1999）。
+- **打断预算**：每人每时段上限，超限转异步队列。
+- **顶端只保留三类决策**：目标选择、冲突裁决、异常接管。
+- **自动化升级时**同步提高人的手动演练配额（Bainbridge 1983 / OOTL）。
+
+## 4.2 共谋（必须可判）
+
+`Δ≈0` 有两种解释：都准，或都错。判别只能靠**盲复核 + 第三方抽检**；
+"人推翻秤结论的次数"必须为 0，但该指标**不得进个人考核**（Campbell 定律）。
+
+## 5.1 认知分工：知其然，不知其所以然
+
+- 人负责 **why**：什么值得做、什么算好、什么时候停。
+- 电子脑负责 **how**：试、量、记、压缩。
+- 系统**不承诺理解因果**，只承诺"可复用的行为先验"；因果解释由人补，或作为假设去验证。
+- 这不是缺陷，是分工：**局部优化由机器做，全局意图由人守**。
+
+## 6. 与现有能力的关系（能力是仪器，不是目的）
+
+| 已有/在建 | 在循环里的位置 |
+|---|---|
+| ingest（会话采集） | 观测 |
+| episodes + 脱敏 | 记录 |
+| candidates（候选） | 蒸馏的输入 |
+| hypotheses（H1–H8） | 蒸馏的产物 / 评审对象 |
+| audit / freeze | 信任与边界（度量的一部分） |
+| kb（知识库） | 历史锚点的检索面 |
+| pkg / render | 把"调整"落到宿主 |
+| ACP / 编排 | 让两个引擎能接上，不是目的 |
+
+---
+
+## 7. 失败判据（什么时候承认定位错了）
+
+1. 连续 4 周，观测覆盖率不升、候选采纳率为 0 → 过程没跑起来。
+2. 连续 4 周，人工介入率 100% 且没有下降 → 电子脑没形成能力。
+3. 出现"为了用框架而用框架"的功能 → 生态位变成了目的，回到本文 §1。
+4. 意图锚点 3 个月没被引用过一次 → 初心已经丢了。