@minonl/dia 0.0.0-stage → 0.0.1

package/docs/history/framework-bootstrap.md

@@ -0,0 +1,109 @@
+> **已归档（2026-11-03）**：本文的启动/分发方案（release tarball + `agentctl` + `framework.lock`）未采用；
+> 实际是 `bun run build` + `bash install.sh`。保留作为早期决策记录，不要按它部署。
+
+# 框架启动方案（bootstrap）
+
+> 日期 2026-10-27。配合 `docs/architecture.md`。
+> 目标：先把"会话采集 + 知识检索"这条最小闭环跑起来，再谈其他。
+>
+> **2026-11-03 现状**：分发**没有**按本文的 A 方案做（无 release tarball、无 `agentctl`、无 `framework.lock`）。
+> 实际是 `bun run build` + `bash install.sh` → `~/.local/share/dia` + `~/.local/bin/dia`；
+> 版本只有 `package.json` 的 0.0.1，未发布。本文保留早期选型过程，**不要按它部署**。
+
+## 1. 仓库与分发
+
+### 1.1 布局
+
+```
+framework/
+├── bin/dia.js                # 唯一入口（Node/Bun）
+├── packages/                 # TS 包：core / kb / job / cli
+├── packages/                 # 内置包（可选）
+├── tests/                    # unittest + shell
+└── docs/
+```
+
+### 1.2 分发选项
+
+| 方案 | 优点 | 缺点 | 适合 |
+|---|---|---|---|
+| **A. GitHub Release tarball + `install.sh` + sha256** | 零依赖、离线可用、私有仓用 `gh` 下载、版本可钉 | 需要 `gh` 或 token；无自动更新 | **当前首选** |
+| B. 私有 npm（GitHub Packages） | 版本语义清晰、可锁 | 需要 npm 登录与 token；对 bash/TS 项目是多余依赖 | 以后出 TS 插件时 |
+| C. 公开 npm | 安装最省事 | 代码公开 | 若决定开源 |
+| D. git submodule / subtree | 无发布流程 | 两个域版本耦合，回滚困难 | 不推荐 |
+
+**推荐 A**：`gh release download <tag> -R <org>/framework` → 解压到 `~/.local/share/framework/<version>` → `~/.local/bin/agentctl` 软链。
+每个域持有 `framework.lock`：`{version, sha256}`；`agentctl self-check` 校验完整性。
+
+## 2. 第一个任务：会话采集（ingest）
+
+### 2.1 输入（本机实测）
+
+| 源 | 位置 | 规模 | 读取方式 |
+|---|---|---|---|
+| dsh | `~/.dsh/sessions/<escaped-workspace>/session-<uuid>/session.v4.jsonl.zstd` | 241 个 / 146MB | `node:zlib` zstd 流式解压后逐行 JSON |
+| opencode | `~/.local/share/opencode/opencode.db`（SQLite） | 449MB / 34 会话 / 7377 消息 / 30201 片段 | `sqlite3` **只读 URI**，按 session 逐条流式读 |
+
+依赖兜底：`zstd` CLI 优先；没有则用 Python ≥3.14 的 `compression.zstd`；都没有 → 跳过并写 `degraded_reason`。
+
+### 2.2 流程
+
+```
+读 → 脱敏 → 归一（episode）→ 去重 → 候选
+```
+
+- **脱敏（必须先于落盘）**：token/密码/私钥/内网域名/邮箱/手机号/工号 → 占位符。
+  规则集放 `rules/redact.txt`，每条形如 `正则 → 标签`；样例集 100 条，命中率与误伤率进测试。
+- **归一 schema**：
+  ```json
+  {"schema_v":1,"episode_id":"sha256","source":"dsh|opencode","domain":"dabo|yan",
+   "workspace":"<hash>","project":"<hash|null>","workspace_id":"<id|null>",
+   "directory_hash":"<hash>","path_hash":"<hash>",
+   "ts_start":"...","ts_end":"...","turns":N,
+   "tools":[{"name":"bash","count":2,"ok":1}],
+   "summary":"<脱敏后摘要>","raw_ref":"<source>:<session-id>"}
+  ```
+- **不存原始消息**：只存脱敏摘要 + 指针；要看原文按 `raw_ref` 回源（默认关闭）。
+- **去重**：`episode_id = sha256(source|session_id|first_ts|last_ts)`；同一会话重跑不重复。
+- **候选**：只产出 `candidates.jsonl`（"可能值得沉淀的做法"），**不自动写知识库**。
+
+### 2.3 域与隐私
+
+| 域 | 默认 | 说明 |
+|---|---|---|
+| dabo | **开** | 个人会话，默认采集 |
+| yan | **关** | 工作会话，需 `--domain yan --i-own-this` 显式开启；产物不出本域 |
+
+跨域只共享**方法**（代码/规则），不共享**数据**（episodes 分目录、不同密钥可选）。
+
+### 2.4 判据
+
+1. 能列出两个源的会话总数与时间范围，且与源一致（±0）。
+2. 抽样 20 个 episode：`raw_ref` 能回源、时间戳落在原会话区间内。
+3. 脱敏样例 100 条：命中率 100%，误伤 <5%（误伤 = 正常文本被替换）。
+4. 同一输入跑两遍：`episode_id` 集合完全一致（幂等）。
+5. 只读验证：跑完后源文件 mtime 与大小不变（`stat` 前后对比）。
+6. 无网络：`ingest` 期间零出网（用 `lsof` 或审计断言）。
+
+## 3. 第二个任务：知识检索（kb）
+
+最小接口：
+
+```
+agentctl kb index [--root <dir>]        # 重建派生索引（可重复执行，结果哈希一致）
+agentctl kb search "<q>" [--tag ...]    # FTS5 检索，返回路径+片段
+agentctl kb lint                        # 索引覆盖/断链/复审到期/超预算
+agentctl kb get <path> [--section ...]  # 取正文（按需读）
+```
+
+判据：
+- 与 yan 现状抽样 20 条查询结果一致（路径集合相同，顺序可不同）；
+- 删除 `index.db` 后重建两次，`sha256` 一致；
+- lint 能准确报出当前 yan 库的 29 个未索引文件与 9 条断链（作为基线测试）。
+
+## 4. 首个里程碑（1–2 天）
+
+1. 建 framework 私有仓 + 骨架 + CI（ubuntu + macos）。
+2. `agentctl kb index/search/lint` 指向 yan 知识目录（只读），跑出基线数字。
+3. `agentctl ingest` 采集 dabo 域会话（先小样本 5 个），产出脱敏 episode。
+4. 把上面 6 条判据写成测试。

package/docs/host-control-surface.md

@@ -0,0 +1,213 @@
+# 宿主控制面：黑盒边界与内部 seam（2026-10）
+
+> 日期 2026-10-28。问题：把 opencode（含 v2）与 dsh 当"黑盒宿主"时，我们能在哪些边界上控制它们？
+> 结论先行：**优先黑盒（CLI/HTTP/ACP/配置/会话只读）；插件 seam 只用于观测；永不 patch 宿主。**
+
+---
+
+## 0. 三层边界
+
+| 层 | 形态 | 稳定性 | 用途 |
+|---|---|---|---|
+| **L0 黑盒** | CLI、HTTP API、ACP、配置文件、会话存储（只读） | 高（有版本契约） | 启动、查询、注入配置、读真相 |
+| **L1 插件 seam** | 宿主内部的 hook/事件/生命周期 | 中（API 会断代） | 观测、轻量改写、审批 |
+| **L2 侵入** | patch 宿主源码 / fork | 低 | **禁止** |
+
+---
+
+## 1. opencode（v2 为重点）
+
+### 1.0 v2 拓扑（重要修正）
+
+opencode v2 **不是"TUI 里跑 agent"**，而是 daemon 化：
+
+```
+TUI / CLI / Web / SDK  ← 都是客户端
+        │  同一 HTTP 契约（OpenAPI 3.1）
+        ▼
+用户级共享后台 server（daemon）
+  ├─ sessions / config / permissions / tool execution
+  ├─ LocationServiceMap（每 workspace 的 fs/tools/agents/providers/MCP）
+  └─ durable event log + projections + pending inbox
+```
+
+- 默认自动发现/启动**一个用户级共享 server**；`--standalone` 起私有 server；`--server` 连远端。
+- 桌面版用 **Electron utility-process sidecar** 跑同一个 server（不是通用插件沙箱）。
+- 官方 issue #43898 明确："one shared OpenCode process for all workspaces and clients"，并承认多 workspace 隔离/公平性**没有契约**。
+- `opencode-forge`（第三方，13★，MIT）是 server+TUI 双面插件，做自主循环/worktree 沙箱；**不是核心能力**。
+
+**含义**：
+1. 会话与 TUI 进程分离 → 我们读会话不必附着 TUI。
+2. 共享 daemon 是单点：一个 workspace 的重负载会影响所有客户端（#43898 实测 TUI 卡顿）。
+3. 需要隔离时只有三种选择：`--standalone`（私有 server）、`--server` 远端、或嵌入式 SDK（`@opencode/sdk`，内存 router，无监听）。
+
+### 1.0.1 会话分区：Project / Location / Workspace
+
+| 概念 | 定义 | 证据 |
+|---|---|---|
+| **Project** | 工作目录的身份：Git 仓跟随 worktree 根；非 Git 目录在 V2 各自成 project（V1 统一为 `global`） | 官方指南 + 本机 DB `project_id` 分布 |
+| **Location** | 每次请求的目录上下文：fs/tools/agents/providers/MCP 都挂在 `LocationServiceMap` 下 | V2 spec |
+| **Workspace** | 可选、实验性：session 可绑定 `workspace_id`（worktree） | 测试代码 + 本机 `workspace_id` 全为 NULL |
+
+**行为**：
+- `opencode ~/proj` → 切到该 project；`opencode`（不指定）→ 默认 location（server cwd）。
+- TUI 的 `/sessions` 与 `opencode session list` 都**只列当前 project 的顶层会话**；子会话不出现。
+- `session list` **没有 `--all`**；要跨 project 只能走 API：`GET /api/session`（支持 `scope/directory/path/workspaceID/roots`）。
+- `--continue` 只挑"记录目录 = 当前目录"的最新顶层会话。
+- V1 的 `global` project 会话在 V2 picker 里**看不到**，需要 `GET /api/session` 或 move API 修。
+
+**对 dia 的含义**：
+1. 采集不能只靠 `session list`——会漏跨 project/迁移会话；必须用 API 或直接读 DB，并记录 `project_id/directory/path/workspace_id`。
+2. **Project 不是安全边界**：共享 daemon 拥有全部会话，API 可跨 project 读；隔离要靠 `--standalone`/`--server`。
+3. `workspace_id` 目前为空（实验特性）；不要把"session 绑定 worktree"当成现成能力。
+
+### L0 黑盒
+
+| 能力 | 入口 | 证据 |
+|---|---|---|
+| 任意 API 调用 | `opencode api <operation | METHOD path>`（OpenAPI 操作） | 本机 `--help` · A |
+| 会话管理 | `opencode session ...` | 本机 · A |
+| MCP 管理 | `opencode mcp ...` | 本机 · A |
+| 插件管理 | `opencode plugin add/list/check` | 本机 · A |
+| ACP 服务 | `opencode acp` | 本机 · A |
+| 配置 | `opencode.jsonc`、`agents/*.md`、`plugins/` | 本机 · A |
+| 真相读取 | `~/.local/share/opencode/opencode.db`（只读） | 本机 · A |
+
+### L1 插件（V2）
+
+| 能力 | 形式 | 状态 |
+|---|---|---|
+| 工具前后 | `ctx.tool.hook("execute.before"/"after")` | 官方 V2 |
+| 会话上下文/压缩 | `ctx.session.hook("context"/"compaction")` | 官方 V2 |
+| 事件订阅 | `ctx.event.subscribe()` | 官方 V2 |
+| Agent 注册/改写 | `ctx.agent.transform()` | 官方 V2 |
+| 权限 | `permission.hook("evaluate")` | **实测返回值不生效**（yan-oc-guard 注释，A 级） |
+| shell 前后 | `shell.hook("before")` | 本机插件在用 |
+
+**结论**：opencode 只适合做**观测 + 审计**，不适合做强制拦截；强制控制必须由外部（dia run / dsh）承担。
+V1→V2 是断代（"V1 implementations do not run in V2"），插件 API 必须按版本探测。
+
+---
+
+## 2. dsh
+
+### 1.0 v2 拓扑（重要修正）
+
+opencode v2 **不是"TUI 里跑 agent"**，而是 daemon 化：
+
+```
+TUI / CLI / Web / SDK  ← 都是客户端
+        │  同一 HTTP 契约（OpenAPI 3.1）
+        ▼
+用户级共享后台 server（daemon）
+  ├─ sessions / config / permissions / tool execution
+  ├─ LocationServiceMap（每 workspace 的 fs/tools/agents/providers/MCP）
+  └─ durable event log + projections + pending inbox
+```
+
+- 默认自动发现/启动**一个用户级共享 server**；`--standalone` 起私有 server；`--server` 连远端。
+- 桌面版用 **Electron utility-process sidecar** 跑同一个 server（不是通用插件沙箱）。
+- 官方 issue #43898 明确："one shared OpenCode process for all workspaces and clients"，并承认多 workspace 隔离/公平性**没有契约**。
+- `opencode-forge`（第三方，13★，MIT）是 server+TUI 双面插件，做自主循环/worktree 沙箱；**不是核心能力**。
+
+**含义**：
+1. 会话与 TUI 进程分离 → 我们读会话不必附着 TUI。
+2. 共享 daemon 是单点：一个 workspace 的重负载会影响所有客户端（#43898 实测 TUI 卡顿）。
+3. 需要隔离时只有三种选择：`--standalone`（私有 server）、`--server` 远端、或嵌入式 SDK（`@opencode/sdk`，内存 router，无监听）。
+
+### 1.0.1 会话分区：Project / Location / Workspace
+
+| 概念 | 定义 | 证据 |
+|---|---|---|
+| **Project** | 工作目录的身份：Git 仓跟随 worktree 根；非 Git 目录在 V2 各自成 project（V1 统一为 `global`） | 官方指南 + 本机 DB `project_id` 分布 |
+| **Location** | 每次请求的目录上下文：fs/tools/agents/providers/MCP 都挂在 `LocationServiceMap` 下 | V2 spec |
+| **Workspace** | 可选、实验性：session 可绑定 `workspace_id`（worktree） | 测试代码 + 本机 `workspace_id` 全为 NULL |
+
+**行为**：
+- `opencode ~/proj` → 切到该 project；`opencode`（不指定）→ 默认 location（server cwd）。
+- TUI 的 `/sessions` 与 `opencode session list` 都**只列当前 project 的顶层会话**；子会话不出现。
+- `session list` **没有 `--all`**；要跨 project 只能走 API：`GET /api/session`（支持 `scope/directory/path/workspaceID/roots`）。
+- `--continue` 只挑"记录目录 = 当前目录"的最新顶层会话。
+- V1 的 `global` project 会话在 V2 picker 里**看不到**，需要 `GET /api/session` 或 move API 修。
+
+**对 dia 的含义**：
+1. 采集不能只靠 `session list`——会漏跨 project/迁移会话；必须用 API 或直接读 DB，并记录 `project_id/directory/path/workspace_id`。
+2. **Project 不是安全边界**：共享 daemon 拥有全部会话，API 可跨 project 读；隔离要靠 `--standalone`/`--server`。
+3. `workspace_id` 目前为空（实验特性）；不要把"session 绑定 worktree"当成现成能力。
+
+### L0 黑盒
+
+| 能力 | 入口 | 证据 |
+|---|---|---|
+| 启动 profile | `dsh --profile <name>` | 本机 · A |
+| 组合树查询 | `--dump-config` / `--dump-default-config` | 本机 · A |
+| 插件安装 | `dsh plugin --profile <p> add <pkg>`（转发 pnpm） | 本机 · A |
+| ACP | `dsh-acp-app`（JSON-RPC stdio） | 包描述 · A |
+| 会话真相 | `~/.dsh/sessions/**/session.v4.jsonl.zstd` | 本机 · A |
+| 会话控制 | `dsh-api-session-controller`（remote commands / cold reads / live transport） | 包描述 · A |
+
+### L1 插件 seam（Cordis bundle）
+
+| 能力 | 包 | 说明 |
+|---|---|---|
+| 执行前决策 | `tools/pre-execute`（watchdog） | 可判定/记账 |
+| 审批拦截 | `approval/request` | 可回 `allowed-once` |
+| 结果处理 | `tools/result` | 清理/记录 |
+| 循环控制 | `dsh-agent-loop` | 步数/停止条件 |
+| 重试 | `dsh-llm-retry` | 次数/退避/`providerRetryAfterMs` |
+| 压缩 | `dsh-compaction-basic` + `tool-result-pruner` | 阈值/保留/无模型裁剪 |
+| 权限预设 | `dsh-permission-presets` | sandbox-mode + approval 两轴 |
+| 沙箱 | `dsh-sandbox*` | 文件效果，fail-closed |
+| 断点 | `dsh-session-checkpoint-policy` | 模型请求/工具副作用前 |
+| 重复调用 | `dsh-repeat-tool-reminder` | 防死循环 |
+| 会话事件 | `dsh-session`（event-sourced，fold/fork） | 只追加、可重放 |
+
+**结论**：dsh 是**可强制**的一侧：pre-execute + approval + sandbox + checkpoint 都在插件边界上，且 fail-closed。
+
+---
+
+## 3. 能力矩阵（我们要的控制 × 宿主）
+
+| 控制需求 | opencode L0 | opencode L1 | dsh L0 | dsh L1 |
+|---|---|---|---|---|
+| 启动/停止会话 | ✅ `session` / `api`（共享 daemon） | — | ✅ CLI | — |
+| 读会话真相 | ✅ sqlite 只读 / API | ✅ 事件 | ✅ 文件 | ✅ event store |
+| 注入配置 | ✅ config/agents | ✅ transform | ✅ profile/patch | ✅ bundle |
+| **拦截工具调用** | ❌ | ❌（hook 不生效） | ⚠️ 外部 wrapper | ✅ pre-execute/approval |
+| 观测工具调用 | ❌ | ✅ | ⚠️ | ✅ |
+| 强制沙箱（文件） | ❌ | ❌ | ⚠️ 仅 dsh 内 | ✅ sandbox |
+| 断点续跑 | ❌ | ⚠️ | ⚠️ | ✅ checkpoint |
+| 成本/重试控制 | ❌ | ⚠️ | ⚠️ | ✅ llm-retry |
+| ACP 驱动 | ✅ server | — | ✅ server | — |
+
+---
+
+## 4. 决策规则
+
+1. **能走 L0 就不走 L1**：配置/CLI/ACP 有版本契约；插件 API 会断代。
+2. **强制控制放 dsh**：opencode 的 permission hook 只能观测（实测），不要把安全承诺建在它上面。
+3. **L1 只做观测与审计**：除非有官方文档明确"可阻断"，否则一律按"观测"实现，并用一次实跑验证。
+4. **永不 L2**：patch 宿主会导致升级即坏（dsh patch 覆写 preset 已出过事故）。
+5. **每条控制面都要登记**：进 `deps.jsonl` 的 `kind: host_cli` 条目，记 version + verified_at。
+
+---
+
+## 4.1 轻量复用的两种接法（推荐）
+
+| 接法 | 做法 | 优点 | 代价 |
+|---|---|---|---|
+| **A. 共享 daemon**（默认） | dia 调 `opencode api` / `service status`；不自己起进程 | 零额外进程、会话可复用 | 单点、公平性无契约、版本耦合 |
+| **B. 嵌入式 SDK** | `@opencode/sdk` 的 `OpenCode.create()`，内存 router，无 HTTP 监听 | 无端口、隔离好 | 依赖 TS/Bun + 版本锁定 |
+| **C. 私有 server** | `opencode serve --port ...` 每域一个 | 隔离与故障边界清晰 | 多进程、资源占用 |
+| **D. dsh one-shot** | `dsh headless` 每任务一次 | 最轻、无常驻 | 无会话连续性 |
+
+**选择规则**：
+- 交互式长会话 → A（共享 daemon）或 C（需要隔离时）；
+- 批处理/canary/基准 → D（dsh one-shot）；
+- 需要"无端口" → B（嵌入式 SDK），但只在版本锁定时用。
+
+## 5. 对 dia 的直接含义
+
+- **控制层**：dia 的 `run`/freeze/audit 走 L0（CLI + 配置 + 会话读取）；dsh 内用 L1 观测。
+- **opencode 侧**：只承诺"观测与审计"，不承诺拦截；文档必须写清（doctor 待实现）。
+- **跨版本**：opencode V1/V2、dsh rc 版本都进能力探测；探测失败 → 降级为 L0 只读。

package/docs/index.md

@@ -0,0 +1,80 @@
+# dia 文档菜单
+
+> 本文件由 `scripts/docs-index.mjs` 生成，**不要手改**；改完文档跑 `bun run docs:index`。
+
+Agent 入口：[`llms.txt`](../llms.txt)（按需全量：[`llms-full.txt`](../llms-full.txt)）
+
+## 现状
+
+| 文档 | 一句话 |
+|---|---|
+| [ACP 集成与降级设计（2026-10）](acp-integration.md) | 问题：通过 ACP 是否更好？fallback 怎么做？配置失败如何降级、体验如何？ |
+| [架构：框架 / 场景入口 / kit](architecture.md) | 本文回答一个问题：什么该留在 dabo-agent，什么该抽到独立框架。 |
+| [dia CLI 词表（动作规范）](cli.md) | 原则：动作成对、名词分层、不混轴。 |
+| [外部依赖索引与原始记录维护（2026-10）](dependency-registry.md) | 回答两件事：依赖怎么登记/验证/淘汰，原始记录怎么保留/重建/删除。 |
+| [生态与组合：可复用性调研（2026-10）](ecosystem-integration.md) | 问题：dia 的包和集成面应该长什么样，才能同时服务 opencode / dsh（未来 OpenClaw/Hermes/Pi）？ |
+| [生态定位：我们落在哪，接谁、不接谁](ecosystem-positioning.md) | 一句话：dia 不做通道、不做运行时、不做记忆产品；dia 做"进化的控制面"——观测、审计、基准、门禁。 |
+| [用户入口：人在哪进，agent 叫什么](entrypoints.md) | 一句话：入口仍是 opencode/dsh（和 yan 一样），但 agent 名是 dabo，不是 dia；dia 是控制面命令，不是人格。 |
+| [进化：dia 的第一性定位](evolution-process.md) | 本文不是功能清单，是过程定义。 |
+| [宿主控制面：黑盒边界与内部 seam（2026-10）](host-control-surface.md) | 问题：把 opencode（含 v2）与 dsh 当"黑盒宿主"时，我们能在哪些边界上控制它们？ |
+| [Kit：内容包安装（persona 的第二个半边）](kit-install.md) | 前置：docs/persona-install.md（persona = 人格，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。 |
+| [dia / yan / dabo 现状总览](overview.md) | 2026-11-03 实测。本条是三方合起来的「现在长什么样」；docs/status.md 管 dia 的阶段与证据， |
+| [Patch：对已安装 persona / kit 的本地补丁](patching.md) | 参考 npm/patch-package，但只作用于本地安装副本，不改上游。 |
+| [Persona / Kit 安装：用 dia 从 git 地址装](persona-install.md) | 命名已定：persona = 可被选中的 agent 定义，kit = 知识/技能/工具内容，profile = 宿主运行环境（dsh）。 |
+| [价目表（tokens → 金额）](pricing.md) | 原则：没有价格就不编造；unpriced 明确记录，预算按 tokens 兜底。 |
+| [目标提案（team next）](proposals.md) | 定位：团队可以提候选，不能定目标。 |
+| [Sandbox 细化设计（dia）](security-sandbox.md) | 依据：dsh 本机源码实测、Hermes/Pi 取证、[/tmp/dia-sbx 实验]。 |
+| [dia 状态页（单一事实源）](status.md) | 任何"现在做到哪了"的问题，以本页为准；其他文档是细节。 |
+| [全自动团队：人只在验收介入](team-automation.md) | 目标：计划→实现→验证→对抗→修复全自动循环；人只在验收阶段拍板。 |
+| [团队章程：谁来做 dia（开发团队）](team.md) | 2026-10-28 升级：开发团队执行模式改为全自动循环（计划→实现→验证→对抗→修复），人只在验收阶段介入； |
+| [版本与多会话（persona / kit）](versioning.md) | 问题：dia 要支持升级/本地迭代期间不同会话用不同版本 persona；kit 是否也要会话级版本？ |
+| [dia 长期定位：从"安装器"到 superagent / agent-team 工厂](vision.md) | 2026-11-03，方向性文档。它不是现状——现状看 overview.md 与 status.md； |
+
+## 平台与宿主
+
+| 文档 | 一句话 |
+|---|---|
+| [AI 工具平台经验库（规则与用法）](platforms/index.md) | 单一事实源 = registry.json：平台支持范围、实测版本、已知坑全部只在 JSON 里。 |
+
+## 安全与审计
+
+| 文档 | 一句话 |
+|---|---|
+| [凭据管理（现状 + 调研待办）](security/credentials.md) | 2026-11-03。待调研，不是方案定稿。触发：bw CLI 已用于入库，但"按账号分组"决定放行粒度， |
+| [dia Public Release Gate](security/public-release.md) | 状态：BLOCKED until audit（2026-10-30） |
+
+## 迁移
+
+| 文档 | 一句话 |
+|---|---|
+| [K0：kb 查询 golden（20 条）](migrations/kb-golden.md) | 2026-10-30。原始 query 只落在 yan 数据根，不提交到 dia 仓。 |
+| [配置迁移：用 LLM 任务，不写 migration 代码](migrations/llm-migration.md) | 2026-11-04。适用：dia / persona / kit 的声明式格式升级（dia.json、lock、registry.json、deps.jsonl 等）。 |
+| [Python 清理：Node/Bun 项目不收 Python](migrations/no-python.md) | 目标：dia 仓库不把 Python 作为运行时/工具链依赖。 |
+| [yan-agent 切到 dia：本机现状与剩余迁移](migrations/yan-agent-current.md) | 2026-11-02 初版，2026-11-03 复核。yan-agent 远端 main 已合入 yan-agent@next（dia persona 形态）。 |
+| [yan-agent@next：迁移到 dia 框架](migrations/yan-agent-next.md) | 目标：yan-agent 的“通用能力”沉到 dia，“工作域内容”留在 yan-agent； |
+| [yan-kb 兼容设计 v2（grill 后）](migrations/yan-kb-parity.md) | 2026-10-30。触发：9 条 query golden 上，旧实现规则召回 10/12、top1 5/9； |
+| [yan-kb → dia kb：能力矩阵与迁移计划](migrations/yan-kb.md) | v2 修订（2026-10-30）：兼容边界、质量门禁、单引擎架构见 yan-kb-parity.md。 |
+
+## 留痕
+
+| 文档 | 一句话 |
+|---|---|
+| [开源评测与基准：可用清单（2026-10）](research/benchmarks-survey.md) | 回答：哪些开源项目的真实任务能直接用；哪些只能做首次 baseline（已污染）；私有 canary 怎么建。 |
+| [人机协作与评估：理论依据（2026-10）](research/collaboration-theory.md) | 目的：给 dia 的 (T, D, O) 模型与指标找可引用的理论出处，并明确哪些是"有依据"、哪些是"我们拍的"。 |
+| [dsh-superagent-prototype 评审](research/dsh-superagent.md) | 2026-11-02。仓库：<https://github.com/deepseek-ai/dsh-superagent-prototype> |
+| [主流 Agent 框架设计对照（2026-10）](research/frameworks-survey-2.md) | 对象 13 个：LangGraph、CrewAI、AutoGen/AG2、OpenAI Agents SDK、Google ADK、AWS Strands、Semantic Kernel/MAF、LlamaIndex、Mastra、PydanticAI、smolagents、Claude Agent SDK、Codex SDK。 |
+| [H0 报告：三层架构覆盖分类实验](research/h0/report.md) | 判据来自 dabo-agent/docs/hypotheses.md H0： |
+| [模型边界控制与调优：模式与修正（2026-10）](research/model-boundary-patterns.md) | 范围：客户端侧（适配/中间件/路由/护栏/评测/监控），不做训练与 provider 私有参数。 |
+| [opencode v2 会话分区调查（Project / Location / Workspace）](research/opencode-session-scoping.md) | 问题：opencode ./ 只看到当前目录的会话，是否是专门设计？和 workspace 有什么关系？ |
+| [复用评审（REUSE REVIEW）— 2026-10-28](review/reuse-review.md) | 触发：用户指出"思考过程有很多拿来主义，没有验证就决定复用"。 |
+| [独立验证报告 — 2026-10-28（pilot）](review/verification-2026-10-28.md) | 验证者：独立子 agent（只读仓库，不共享实现者上下文）。 |
+
+## 归档
+
+| 文档 | 一句话 |
+|---|---|
+| [框架启动方案（bootstrap）](history/framework-bootstrap.md) | 已归档（2026-11-03）：本文的启动/分发方案（release tarball + agentctl + framework.lock）未采用； |
+