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

package/docs/research/collaboration-theory.md

@@ -0,0 +1,85 @@
+# 人机协作与评估：理论依据（2026-10）
+
+> 目的：给 dia 的 `(T, D, O)` 模型与指标找**可引用的理论出处**，并明确哪些是"有依据"、哪些是"我们拍的"。
+> 结论先行：V 型与控制回路 / 类型×层级 / 抽象层级**对得上**；但 **Δ 阈值**和**自报深度**两处是直觉，不是理论。
+
+---
+
+## A. 理论表
+
+| 理论 | 核心主张 | 对我们的映射 | 出处 | 级 |
+|---|---|---|---|---|
+| 混合主动交互 | 主动权在人与系统间流动，由「不确定性 × 错误成本 × 打断成本」决定谁发起 | 请示触发条件 | Horvitz 1999, CHI '99, `10.1145/302979.303030` | A |
+| 监督控制 / 10 级自动化 | 自动化是 1–10 连续谱；人成为监督者 | D 的刻度来源 | Sheridan & Verplank 1978；Sheridan 1992 | A |
+| 类型 × 层级 | 自动化按四类功能（信息获取/分析/决策/执行）**分别**定级 | **深度必须是矩阵，不是标量** | Parasuraman, Sheridan & Wickens 2000, `10.1109/3468.844354` | A |
+| 抽象层级 | means-end：目的在顶、形式在底，约束自上而下 | V 型的形状依据 | Rasmussen 1985, `10.1109/TSMC.1985.6313353` | A |
+| 联合认知系统 | 分析单元是「人＋技术」的控制回路整体 | **警告：不能按功能切两臂** | Hollnagel & Woods 2005, `10.1201/9781420038194` | A |
+| 情境意识 | SA 三级（感知/理解/预测）；自动化导致 OOTL 退化 | 观测事件应标 L1/L2/L3 | Endsley 1995, `10.1518/001872095779049543` | A |
+| 信任校准 | trust 应与能力匹配；complacency/bias 使监督失效 | Δ=0 也可能是共谋 | Lee & See 2004, `10.1518/hfes.46.1.50_30392`；Parasuraman & Riley 1997 | A |
+| 有意义的人类控制 | 需 tracking（响应理由）＋ tracing（理由可追溯） | O 必须记依据与 provenance | Santoni de Sio & van den Hoven 2018, `10.3389/frobt.2018.00015` | A |
+| 构念效度 / 指标腐蚀 | 指标须有构念定义与效度证据；成为目标即失效 | 覆盖率/压缩比目前**无构念定义** | Cronbach & Meehl 1955, `10.1037/h0040957`；Jacobs & Wallach 2021, `10.1145/3442188.3445901` | A |
+| 人-AI 团队 | 团队绩效非线性可加，需 common ground 与 directability | 请示质量须含可指挥性 | NASEM 2022, `10.17226/26355` | B |
+
+---
+
+## B. 站得住的三条
+
+1. **顶端 = 意图**：Rasmussen 的抽象层级把目的置顶、形式置底，约束自上而下——"人守顶端"与其同构。
+2. **深度做成矩阵**：Parasuraman 的 types×levels 明确四类功能各自定级；标量会掩盖"信息获取 9 级、决策 2 级"这类错配。
+3. **Δ 是有效信号**：Lee & See 的校准需要"预期 vs 实际"偏差；Δ 是其代理。
+
+## C. 站不住的四条（必须改）
+
+1. **请示没有成本模型**：违反 Horvitz 的"错误成本/打断成本"。叠加 Bainbridge 1983（`10.1016/0005-1098(83)90046-8`）的 ironies——自动化越多，人越少练手，回给人的恰是最难的部分 → **请示风暴 + 顶端能力退化**。
+2. **自报 + 同源复核 ≠ 校准**：自报是自信的代理，不是能力；同源复核对同源错误零功效（Skitka 1999 automation bias 同构）。**Δ≈0 无法区分"都对"与"共谋"**。
+3. **按功能切 V 的两臂违反 JCS**：Hollnagel & Woods 要求分析单元是回路整体；按功能切会在交接处留下无人的失效地带。
+4. **"人守顶端" ≠ 有意义的人类控制**：只做最终批准既不满足 tracking 也不满足 tracing；只记深度不记依据 = **名义控制**。
+
+---
+
+## D. 指标修正（按构念效度重写）
+
+| 现指标 | 问题 | 配对/替代 |
+|---|---|---|
+| 观测覆盖率 | 多写事件即可刷高 | ＋**复核后仍成立的观测率**＋每千事件人工复核工时 |
+| 深度达成 | 自报 ≠ 能力 | 改为 **calibration**：ECE / Brier（自报 vs 盲复核），报 ICC(2,k) |
+| 部分产物复用 | activity 指标，奖励囤积 | ＋复用产物在下游的返工率/缺陷率（结果侧） |
+| 压缩比 | 无操作定义 | 先定义"压缩信息量 vs token"，做不到就删 |
+| 意图漂移 | 缺可判定 rubric | 双人独立盲标 + kappa ≥0.61（Landis & Koch 1977） |
+| 请示质量 | 无结果侧 | ＝改变决策的比例 × 节省的错误成本 |
+| 共谋信号 | 单一来源自指 | 第三方盲评；且**不得**进个人考核（Campbell 定律） |
+
+**三问闸门**（Jacobs & Wallach）：构念被操作化了吗？有效度证据吗？对谁有效？
+
+---
+
+## E. 可执行规则（替代原来的直觉规则）
+
+1. **撤回"Δ>0.3 必须先对齐"**：无出处。改为**成本加权**：`优先级 = Δ × 该判定的错误成本`，阈值**预注册**。
+2. 请示三件套：不确定性 / 候选及代价 / 推荐项（Horvitz）。
+3. **打断预算**：每人每时段上限，超限降级为异步队列（注意力成本）。
+4. 顶端只保留三类决策：目标选择、冲突裁决、异常接管（Rasmussen + 监督控制）。
+5. 深度按**四类功能**分别记录，**禁止**输出单一深度分（Parasuraman 2000）。
+6. 复核必须**盲**且**异源**（automation bias / 独立性）。
+7. 每 N 次自报抽 5% 盲复核，公开 ECE（校准）。
+8. 每个观测事件必带 provenance：`intent_id / judge_id / upstream_artifact_ids`（MHC tracing）。
+9. 自动化升级时同步提高人的手动演练配额（Bainbridge / OOTL）。
+10. 指标上线前须有构念定义 + 反例测试；指标不得进个人考核（Cronbach & Meehl；Goodhart/Campbell）。
+11. 子 agent 不得自签验收——**弱支持**（Klein directability 只提供类比）。
+
+---
+
+## F. 参考文献分级
+
+**A（同行评审/一手）**：Horvitz 1999；Parasuraman/Sheridan/Wickens 2000；Rasmussen 1985；Hollnagel & Woods 2005；Endsley 1995；Lee & See 2004；Parasuraman & Riley 1997；Parasuraman & Manzey 2010；Santoni de Sio & van den Hoven 2018；Cronbach & Meehl 1955；Jacobs & Wallach 2021；Bainbridge 1983；Landis & Koch 1977；Skitka et al. 1999；Cohen 1960；Fleiss 1971；Shrout & Fleiss 1979。
+
+**B（权威机构）**：NASEM 2022《Human-AI Teaming》`10.17226/26355`。
+
+**C（二手/未验证）**：Article 36 的 meaningful human control 倡议文本（年份未验证）；"in/on the loop"术语溯源（未验证）。
+
+---
+
+## G. 对 dia 的两条硬结论
+
+1. **先加 provenance，再加深度**：没有 `intent_id / judge_id / upstream` 的观测，不满足 tracing，深度再准也是名义控制。
+2. **先把"共谋"做成可判**：盲复核 + 第三方抽检；否则 Δ 小只会被误读成"对齐良好"。

package/docs/research/dsh-superagent.md

@@ -0,0 +1,97 @@
+# dsh-superagent-prototype 评审
+
+> 2026-11-02。仓库：<https://github.com/deepseek-ai/dsh-superagent-prototype>
+> 研究原型，MIT；约 8.9k stars；DSH bundle（`@deepseek-ai/dsh-*` alpha 依赖）。
+> 结论：**产品哲学很像，架构不是同一个东西**；借概念与约束，不直接依赖/复制。
+
+---
+
+## 1. 它是什么
+
+一个面向**单个 GitHub 仓库**的主动式 coding agent：
+
+```text
+Source（GitHub / Feishu）
+  → Trigger（不可变事件）
+  → Thread（按时间聚合）
+  → Eval（Gate + Assessment）
+  → Decision（accept / stop / ignore / unavailable）
+  → Ticket（授权后的工作单元）
+  → Assignment（绑定到一个 Executor Session）
+  → Executor（独立目录 / DSH Session）
+  → Channel（回复 PR/Issue/Feishu）
+```
+
+核心原则：**用最少的人类注意力换取最大价值**。只在被请求或已有书面规则允许时行动；只在人必须行动或结果可用时说话。
+
+它带一个 Web panel，展示“需要人处理的事项”、系统健康和历史；支持 GitHub/Feishu 两个 Source，每个 Ticket 一个 worker Session/目录，有并发槽位、持久化 outbox、恢复与幂等。
+
+---
+
+## 2. 和 dia 的对照
+
+| 维度 | dsh-superagent | dia 当前 |
+|---|---|---|
+| 定位 | 单仓 proactive agent 产品原型 | 通用框架 + 多角色团队 |
+| 入口 | DSH bundle + panel | CLI/ACP + opencode/dsh |
+| 领域模型 | Source/Trigger/Thread/Eval/Ticket/Assignment/Mandate | task/team/run/verify/gate（较扁平） |
+| 授权 | Policy version + Mandate + gate + revalidate | accept/gate + 人工确认；无版本化 Mandate |
+| 执行 | 一个 Ticket 一个 worker Session/目录 | 4 角色 team + ACP/dsh 多会话 |
+| 验证 | worker 自验 + PR review；没有独立 verifier 角色 | builder/verifier/redteam 分离 |
+| 知识 | 无通用 KB；prompt/skills | kb/ingest/audit/freeze 是核心 |
+| 人类介入 | 结构化 Attention，panel 优先展示 | team `accept` + gate；无 attention panel |
+| 持久化/恢复 | SQLite store + durable effects/outbox + slots | ledger/runs 文件；恢复能力较弱 |
+| Prompt 版本 | 不可变版本 + override/base/升级提示 | persona/patch + next-session |
+| 可移植性 | 强绑 DSH alpha | 目标跨 opencode/dsh，但仍有耦合 |
+| 成熟度 | research prototype，明确不 production-ready | 早期框架，测试/门禁在补 |
+
+---
+
+## 3. 值得吸收的
+
+1. **Attention 是一等公民**
+   - “需要人”的结构化状态（answer/review/blocked/failed）比 `accept` 一个终态更细；
+   - panel 先列“需要人”的事项，健康状态不占空间；
+   - dia 可以把它落成 task/team 的 `attention` 投影，而不是加聊天消息。
+
+2. **显式领域状态机**
+   - Ticket 的 stage 由事实（report/input/assignment）推导，不靠自由文本；
+   - 这比我们 `run` 里的临时状态更可测，能减少“看起来完成”。
+
+3. **Policy version + Mandate**
+   - 每个接受记录依据的 policy 版本、scope、strength；
+   - policy 变化只通知受影响的 Ticket，不撤销已发 Mandate；
+   - dia 的 gate/accept 可以参考，但不要一开始做全套。
+
+4. **Durable effects / outbox / idempotence**
+   - 外部动作先落库，再执行；失败退避；重启恢复；
+   - worker slot / 并发上限 / 人类消息优先；
+   - 这是 team 自动化从“能跑”到“可运营”的关键。
+
+5. **Prompt 版本化**
+   - immutable versions、override/base、默认更新提示；
+   - 和 dia 的 persona patch 可以对齐。
+
+---
+
+## 4. 不该直接照搬的
+
+- **不要替换 dia 为 DSH bundle**：它强绑 DSH alpha，和我们的 opencode/ACP/跨域目标冲突。
+- **不要退化成单仓单 worker**：dia 的 builder/verifier/redteam 分离是刻意设计。
+- **不要复制它的实现代码**：research prototype，工程一致性自述不保证；借概念即可。
+- **不要先做 panel**：我们的宿主适配层（H0 的 adapter 缺口）还没定，先做 attention 状态和 CLI/API 更稳。
+- **不要一次上全量 Ticket/Mandate 状态机**：先映射到现有 task/run，避免大爆炸重构。
+
+---
+
+## 5. 对 dia 路线的影响
+
+优先级建议：
+
+1. **attention 投影**：task/team 输出“等人工”的结构化状态（answer/review/blocked/failed），先 CLI，不先 UI。
+2. **durable team run**：把 `team.ts` 的外部动作（ACP prompt、快照、gate）落成可恢复的 effect/outbox；先做最小重试与恢复。
+3. **Mandate-lite**：accept 记录 policy/版本/scope/证据，policy 变化可追踪，不急着做完整 revalidation。
+4. **panel 等宿主适配层**：H0 的 adapter 子层落地后再做 Web/宿主 panel。
+5. **kb/job 继续按现有模块推进**，不要因为参考项目改方向。
+
+一句话：**借它的“注意力优先 + 显式状态 + durable effects”，不借它的 DSH 绑定和单仓单 worker 形态。**

package/docs/research/frameworks-survey-2.md

@@ -0,0 +1,75 @@
+# 主流 Agent 框架设计对照（2026-10）
+
+> 日期 2026-10-28。对象 13 个：LangGraph、CrewAI、AutoGen/AG2、OpenAI Agents SDK、Google ADK、AWS Strands、Semantic Kernel/MAF、LlamaIndex、Mastra、PydanticAI、smolagents、Claude Agent SDK、Codex SDK。
+> 用途：给"零重依赖、审计优先、进化过程"的个人框架做设计校验。
+
+---
+
+## A. 对照表（摘要）
+
+| 框架 | 定位 | 模型抽象 | 中间件/钩子 | 状态/恢复 | HITL | 多 agent | 评测 | 许可 |
+|---|---|---|---|---|---|---|---|---|
+| **LangGraph** | 图运行时 | BaseChatModel + `with_fallbacks()` | before/after_model、wrap_model/tool_call | checkpointer+thread，**replay/fork**（副作用会重放） | `interrupt()`+resume | 子图/supervisor/handoff | 无内建 | MIT |
+| **CrewAI** | 角色团队 | `LLM("provider/model")`，无 fallback | task/step callback、guardrail | `@persist` 方法级 | Flow 人工反馈 | sequential/hierarchical | 弱（`crewai test`） | MIT |
+| **AutoGen/AG2** | 群聊 | ChatCompletionClient+model_info | hookable message | save/load_state | UserProxy（无 interrupt） | GroupChat/Swarm | AutoGenBench | MIT/Apache |
+| **OpenAI Agents SDK** | 轻 loop | Model/ModelProvider，**无 fallback** | guardrails+RunHooks | Session+**RunState 可序列化** | `needs_approval`→interruptions | handoff/agents-as-tools | 平台 tracing | MIT |
+| **Google ADK** | 企业 agent+图 | BaseLlm 子类 | **6 类 callback** + Plugins | 事件溯源 + `app:/user:/temp:` | workflow 节点 | 层级/graph/A2A | **`adk eval`+evalset** | Apache-2.0 |
+| **AWS Strands** | model-first | Model ABC + **ModelRouter(Fallback/Classifier)** | Hook（invocation/model/tool）+Plugin | SessionManager（File/S3/Snapshot） | 无一级中断 | Swarm/Graph/Workflow | 无内建 | Apache-2.0 |
+| **SK → MAF** | 企业 .NET/Py | IChatCompletionService | Filters | MAF checkpoint | MAF workflow | GroupChat/Handoff | 无 | MIT |
+| **LlamaIndex** | 事件驱动+RAG | Settings.llm + metadata | step 边界 | WorkflowCheckpointer（at-least-once） | `InputRequired` 事件 | AgentWorkflow | RAG 评测 | MIT |
+| **Mastra** | TS 全栈 | 路由串+能力表 | processors(input/output/error) | snapshot+thread，**suspend/resume** | **suspend()/resume()** | workflow+supervisor | **scorers+datasets** | Apache-2.0 |
+| **PydanticAI** | 类型安全 | Model+profile，**FallbackModel** | capabilities（before/after model、tool hook） | **无内建 session** | deferred tool 审批 | agent 委派 | pydantic-evals+Logfire | MIT |
+| **smolagents** | 极简 | Model 类 | step_callbacks | 仅内存 | 无 | ManagedAgent | 无 | Apache-2.0 |
+| **Claude Agent SDK** | Claude Code 当库 | 仅 Claude | hooks（PreToolUse/PostToolUse/PreCompact/SubagentStop） | **resume/fork**+checkpoint | permissions 回调 | subagents（≤20 并行） | 无 | Py MIT/TS 商业 |
+| **Codex SDK** | Codex CLI 当库 | 固定 Codex | 无 hook | **resume(threadId)**，无 fork | approval_policy | 无 | 无 | Apache-2.0 |
+
+**三个结构性事实**：
+1. AutoGen 与 SK 已进维护模式，微软的答案是 MAF（2026-04）。
+2. 真正"能中断再恢复"的只有 LangGraph / OpenAI / Mastra / Claude / Codex（Pydantic 靠 deferred tool）。
+3. 内建评测完整的只有 ADK 与 Mastra。
+
+---
+
+## B. 该借的五条
+
+1. **事件溯源会话**（ADK delta / Strands session）：消息与工具调用 append；state 分作用域；视图可重建 → 审计免费、可 fsck。
+2. **双闸口**（LangGraph wrap_model/tool_call + Codex 审批）：`gate-model` / `gate-tool` 两个可执行钩子，stdin JSON、stdout 决策；绕过即失败。
+3. **可序列化中断**（OpenAI RunState / Mastra suspend）：落 `runs/<id>/{state,interrupt}.json`，`resume` 跨进程续跑，不阻塞 stdin。
+4. **模型 profile 声明化**（PydanticAI/Mastra）：`models.yaml` 写 context/tools/vision/价格/`verified_at`；路由 = fallback 链 + 预算，决策落审计。
+5. **判据当门禁**（ADK evalset / Mastra scorers）：`evals/*.case.json` = 输入 + 期望工具轨迹 + 断言命令；收尾自动跑，不退步才允许 tag。
+
+---
+
+## C. 不该借的五条
+
+1. **图 DSL 当唯一编排**：个人任务九成线性，节点/边/Reducer 成本高于收益。
+2. **重型 durable runtime**（Temporal/DBOS 级）：违背零重依赖；文件 journal + 幂等键够。
+3. **角色群聊多 agent**：token 贵、路径不可预测、责任链糊。
+4. **平台绑定 tracing**：默认上行，离线/隐私不可控；本地 jsonl + 可选 OTLP。
+5. **"SDK 包 CLI"的伪库**（Claude/Codex SDK）：模型锁死、行为随 CLI 漂移。
+
+---
+
+## D. 三个空位（我们有机会）
+
+1. **审计即数据模型**：没人把"为什么"（判据、拒绝理由、成本、模型版本）做成一等字段；
+   我们让每条决策带 `judge` 指针 + 证据哈希，可离线校验、可 diff。
+2. **进化可回滚**：现有最多给分数，缺"候选→对抗→回归→落地→tag→rollback"生命周期与配额。
+3. **零依赖可移植**：全部要包树 runtime；个人 agent 应 `git clone && bash install.sh` 即跑，配置纯文本可 grep/diff。
+
+---
+
+## E. 对 dia 的结论
+
+| 我们的设计 | 对照结果 |
+|---|---|
+| 审计/门禁/证据一等公民 | **空位 1，方向正确** |
+| 进化生命周期（候选→评审→落地→回滚） | **空位 2，方向正确** |
+| 零依赖 + 纯文本配置 | **空位 3，方向正确** |
+| 团/档位 | 与"角色群聊"同风险，**继续 defer** |
+| 事件溯源会话 | 已有 dsh session；补"视图可重建"判据 |
+| 可序列化中断 | 我们只有 resume 卡片，**应补 interrupt 文件** |
+| 模型 profile | 已有 ModelSpec，补 `verified_at/price_ver` |
+| 评测门禁 | 已有 H 体系，补 `evals/*.case.json` 形态 |
+
+**一句话**：13 个框架验证了"审计/证据/可移植"是空位，也验证了"团/群聊/重运行时"是坑。

package/docs/research/h0/report.md

@@ -0,0 +1,135 @@
+# H0 报告：三层架构覆盖分类实验
+
+> 日期 2026-10-29。判据来自 `dabo-agent/docs/hypotheses.md` H0：
+> “三层瘦架构（框架/入口/包）能覆盖 ≥90% 真实任务，维护成本减半。”
+> 本报告只回答**覆盖**；**维护成本减半无法判定**（没有改造前基线）。
+
+---
+
+## 1. 结论
+
+**按严格口径，H0 的覆盖预测未成立：17/20 = 85%，低于 90%。**
+
+失败集中在同一类：**宿主客户端/插件/本机环境**（3 条）。它们既不属于 framework 的通用引擎，
+也不属于 domain 的域内容，也不属于 kit 的可复用内容——三层里没有“宿主适配”这个承接处。
+
+- 若把“DSH 配置页调研”算作 kit 的知识产出，覆盖率是 **18/20 = 90%**，正好卡在边界；
+- 另外两条（Electron 客户端插件、本机编辑器/浏览器插件安装）仍然无归属；
+- **维护成本减半**：无改造前数据，**无法判定**；只能给出代理指标（见 §4）。
+
+**建议**：不要回到单仓单层；把“宿主适配”显式补进入口层（adapter 子层，已落到
+`docs/architecture.md` §2.1）。然后按 50 样本、双人独立分类重跑；本报告只完成 20 样本严格口径。
+
+---
+
+## 2. 方法
+
+### 数据
+
+- 本机 `dia ingest sessions --full` 产出：**322 条 episode**（不是假设里的 257；旧数字已过时）。
+- 过滤测试夹具（`headless`、`Implement this task`、`verify-ws`、`team-data`、`Return only JSON`、
+  `You are teammate`、`YAN-OK` 等）后剩 **140 条**。
+- 固定 `seed=11` 抽 20 条；样本与逐条标注见 `sample.json`。
+- 复现：`bun experiments/h0-sample.ts <episodes.jsonl> 11`。
+
+### 分类口径
+
+| 层 | 承接什么 |
+|---|---|
+| framework | 与域无关的引擎能力：ingest/audit/kb/team/版本/渲染/沙箱 |
+| domain | 单个入口的内容与策略：yan 工作域、dabo 个人域、宿主入口适配 |
+| kit | 可复用知识/技能/工具内容；默认无执行权 |
+
+- `fits=true`：任务能被三层之一**唯一承接**，不需要新增第四种职责；
+- `framework_change=true`：任务会逼 dia 改框架代码/契约；
+- `host_coupled=true`：依赖 Electron/DSH 客户端、本机编辑器/浏览器等宿主环境。
+
+---
+
+## 3. 结果
+
+| # | 任务 | 主责层 | 改框架 | 落入三层 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 迁移 example-service 到 example-repo | domain | 否 | ✅ | 工作域项目迁移 |
+| 2 | yan 版本管理：服务/引用路径生命周期 | framework | 是 | ✅ | 版本/渲染生命周期 |
+| 3 | 只读沙箱 touch 测试 | framework | 否 | ✅ | 验证既有沙箱 |
+| 4 | 企业知识库智能体场景本地同构 | domain | 否 | ✅ | 产品域实现 |
+| 5 | GitLab MR lgtm 轮询 | kit | 否 | ✅ | 可复用轮询 skill |
+| 6 | DSH watchdog 权限日志分析 | framework | 否 | ✅ | 沙箱/权限观测 |
+| 7 | 图片菜单项识别 | framework | 否 | ✅ | 视觉/读图能力 |
+| 8 | 图片标题文字识别 | framework | 否 | ✅ | 同上 |
+| 9 | 网络安全短信改造 | domain | 否 | ✅ | 业务域改造 |
+| 10 | DSH 文档预览 Mermaid 客户端插件 | none | 是 | ❌ | 需宿主 Electron 插件机制 |
+| 11 | 超级本 LDAP 登录跳转修复 | domain | 否 | ✅ | 业务登录域 |
+| 12 | 平台感知 + 并行会话收尾 | framework | 是 | ✅ | 跨平台会话生命周期 |
+| 13 | DSH 配置页前端能力调研 | none | 是 | ❌ | 服务宿主配置页；边界可争议 |
+| 14 | 钉钉反馈分析：商品分组升级 | domain | 否 | ✅ | 工作域反馈分析 |
+| 15 | example-repo 知识库批量导入接口优化 | domain | 否 | ✅ | 产品接口优化 |
+| 16 | yan-agent 更新与生效版本机制 | framework | 是 | ✅ | 自更新/版本 |
+| 17 | 企业知识库回复诊断页内置改造 | domain | 否 | ✅ | 产品页面改造 |
+| 18 | 服务生命周期治理（续） | framework | 是 | ✅ | 同 #2 能力 |
+| 19 | iTerm2 Markdown 与浏览器插件安装 | none | 否 | ❌ | 本机宿主环境安装 |
+| 20 | 企业知识库领域知识出现商品 | domain | 否 | ✅ | 业务过滤规则 |
+
+### 计数
+
+- 覆盖：**17/20 = 85%**（严格）；**18/20 = 90%**（把 #13 算 kit 知识产出）
+- 主责层：framework 8 / domain 8 / kit 1 / none 3
+- 需要改框架：**6/20 = 30%**；不需要改框架：14/20 = 70%
+- 宿主耦合：**3/20 = 15%**
+
+---
+
+## 4. 解释
+
+### 4.1 失败不是“分层错了”，是少了一个承接处
+
+3 条失败全部与**宿主**有关：
+
+- DSH 是 Electron 应用，客户端插件（Mermaid 预览、配置页）需要宿主插件代码；
+- iTerm2/浏览器插件属于本机环境安装，不是 agent 的 persona/kit。
+
+这说明三层对“agent 能力类任务”覆盖良好（17 条里 17 条有主责层），
+但对“宿主集成类任务”没有位置。把这类任务硬塞进 domain，会让域仓库承担宿主 UI 代码，
+维护成本反而上升。
+
+### 4.2 “维护成本减半”没有证据
+
+- 没有改造前/后的维护成本基线；
+- 没有每个任务的 diff、变更包数、review 时长；
+- 只有“70% 任务不需要改框架”这一代理指标，能说明**变更局部化**，不能证明成本减半。
+
+### 4.3 这个结果对架构的含义
+
+- **不要**因为 85% 就回到单仓单层——失败面很窄，且集中在宿主；
+- **要**补一个明确的“宿主适配”职责（放在入口层或独立第四层），并规定：
+  - 宿主插件代码不进 framework；
+  - 宿主适配可以依赖 framework，但 framework 不反向依赖宿主；
+  - kit 仍默认无执行权，宿主插件需显式授权。
+
+---
+
+## 5. 限制
+
+1. **单评价者**：分类由我一人完成，没有双人独立标注/一致性系数；
+2. **样本偏差**：全部来自本机会话，工作域/框架开发占比高；不是用户任务总体；
+3. **episode 是摘要**，不是完整任务描述，分类依赖摘要信息；
+4. **257 → 322**：假设里的数据版本已过时，旧样本不可复现；
+5. **“fits”口径较宽**：把“能在现有能力上执行”与“有唯一主责层”分开后，结论对口径敏感（85% vs 90%）；
+6. **成本未测**：没有改造前后对照。
+
+---
+
+## 6. 决定
+
+| 选项 | 结论 |
+|---|---|
+| H0 原样支持 | ❌ 严格口径 85%，不成立 |
+| 回到单仓单层 | ❌ 失败面窄，代价过大 |
+| 补宿主适配后重跑 | ✅ 推荐 |
+| 维护成本减半 | ⏸ 无法判定，需先埋点 |
+
+**下一步（建议）**：
+1. 在 `docs/architecture.md` 明确“宿主适配”归属与依赖方向；
+2. 用 50 样本 + 双人独立分类重跑，报告 Cohen's κ；
+3. 在每个 MR 记录“改动层”（framework/domain/kit/host）与变更行数，积累 4 周后再判“成本减半”。

package/docs/research/h0/sample.json

@@ -0,0 +1,34 @@
+{
+  "schema": 1,
+  "seed": 11,
+  "source": "episodes.jsonl (322 rows; 140 after excluding test fixtures)",
+  "rubric": {
+    "framework": "domain-agnostic engine capability (ingest/audit/kb/team/version/render/sandbox)",
+    "domain": "one entry's content/policy (yan work, dabo personal, host entry adapters)",
+    "kit": "reusable knowledge/skill/tool content, no execution by default",
+    "fit": "task can be owned by one of the three without a fourth responsibility",
+    "framework_change": "task would require changing dia framework code/contracts"
+  },
+  "items": [
+    {"episode_id":"c1ec930868d80ceb1483033ac56edaa5b2e6265795b5746c3190984ae7aa6a20","task":"迁移 example-service 到 example-repo","primary":"domain","framework_change":false,"fits":true,"host_coupled":false,"why":"工作域项目迁移；复用现有工具，不改引擎。"},
+    {"episode_id":"754568d01fb03a2c8e4ff4b71d30ce470a480c7cd4fec7641736e48b082eac36","task":"yan 版本管理：服务/引用路径生命周期治理","primary":"framework","framework_change":true,"fits":true,"host_coupled":false,"why":"persona/kit 版本与渲染生命周期是通用能力。"},
+    {"episode_id":"da4efeeb3bd2dc6908e79b3f546f663576537f36747599a0c402de8f2e960262","task":"只读沙箱 touch 测试","primary":"framework","framework_change":false,"fits":true,"host_coupled":false,"why":"验证既有沙箱能力，不需要新层。"},
+    {"episode_id":"efd4522712124eafd887225a8f36977742d408fd26e1f920117340c31c483f64","task":"企业知识库智能体场景本地同构实现","primary":"domain","framework_change":false,"fits":true,"host_coupled":false,"why":"产品域实现；团队/工具由框架提供。"},
+    {"episode_id":"912dc3f457de50dc696eb04f50afa3ae06c6fed4a5eb5dce32ec26bebfd4b0e9","task":"GitLab MR lgtm 轮询","primary":"kit","framework_change":false,"fits":true,"host_coupled":false,"why":"轮询流程是可复用 skill；不需要引擎改动。"},
+    {"episode_id":"e2118ba3336077dc927d748f1f04434e8f29c10a2a101b6a03a950645c245c2c","task":"DSH watchdog 权限日志分析","primary":"framework","framework_change":false,"fits":true,"host_coupled":false,"why":"沙箱/权限分析，属引擎观测能力。"},
+    {"episode_id":"59f18b53f5b1e2f994552338304a75a0868dd975cb63b085da6e49e4e7935df8","task":"图片菜单项识别","primary":"framework","framework_change":false,"fits":true,"host_coupled":false,"why":"模型视觉/读图能力，框架已有。"},
+    {"episode_id":"7967c01bb3da5ffab022b6c414a55f78c773a02876b4bf1e41505e4d9af987d2","task":"图片标题文字识别","primary":"framework","framework_change":false,"fits":true,"host_coupled":false,"why":"同图片识别，框架能力覆盖。"},
+    {"episode_id":"7c1fe9510076c124b84d8ad1c58b7755160f081e83025d5dff0628b6f5321aff","task":"网络安全短信改造","primary":"domain","framework_change":false,"fits":true,"host_coupled":false,"why":"业务产品改造；域内完成。"},
+    {"episode_id":"74d470457788397d901dd984548eabae07a9bdda1a33ec15f29643c38e478a60","task":"DSH 文档预览 Mermaid 客户端插件","primary":"none","framework_change":true,"fits":false,"host_coupled":true,"why":"需要宿主 Electron 客户端插件机制；三层都没有承接处。"},
+    {"episode_id":"62d818b447ae3cc0d346b33fcde764f2487b28adbcdb4902f7a333584af4a4f9","task":"超级本 LDAP 登录跳转修复","primary":"domain","framework_change":false,"fits":true,"host_coupled":false,"why":"业务登录域问题。"},
+    {"episode_id":"f82db27c013c0012725267f48c1c1e16f22ab7525b67e2bf36e10ed8853900ab","task":"平台感知 + 并行会话收尾","primary":"framework","framework_change":true,"fits":true,"host_coupled":false,"why":"跨平台会话生命周期属框架。"},
+    {"episode_id":"2b37c73e83cb697b07b146010d4fe04d85fea6b25abbb2d664365648526c2366","task":"DSH 配置页前端能力调研","primary":"none","framework_change":true,"fits":false,"host_coupled":true,"why":"宿主配置页设计/调研，输出服务宿主插件，不属三层任一。"},
+    {"episode_id":"a92d84035c3185d62d6a66e3000034e99603adc801294b0c0de7bc3f33f21911","task":"钉钉反馈分析：商品分组升级","primary":"domain","framework_change":false,"fits":true,"host_coupled":false,"why":"工作域反馈分析；消息通道另有工具。"},
+    {"episode_id":"62ff3e9920701b6512943847b0cd4f5a72c037af2e79c274982836ca303cfc3d","task":"example-repo 知识库批量导入接口优化","primary":"domain","framework_change":false,"fits":true,"host_coupled":false,"why":"产品接口优化，域内完成。"},
+    {"episode_id":"7588f0ea35adae84defb920dfbb5b28f7cda5a4c54e49bdc30e317c7ea28aad8","task":"yan-agent 更新与生效版本机制","primary":"framework","framework_change":true,"fits":true,"host_coupled":false,"why":"自更新/生效版本是框架生命周期。"},
+    {"episode_id":"ba7540301101e3cbd98e5b3fe60d2333936bfc488b32942fea52120f758df84b","task":"企业知识库回复诊断页内置改造","primary":"domain","framework_change":false,"fits":true,"host_coupled":false,"why":"产品页面改造，域内完成。"},
+    {"episode_id":"f8d118e7c02dffb70cd72fa07a42a9bb0e2e54d740a6be3a26a03c6b6aef180b","task":"服务生命周期治理（续）","primary":"framework","framework_change":true,"fits":true,"host_coupled":false,"why":"同版本生命周期，框架能力。"},
+    {"episode_id":"05dad476c47c83981937fcb08c3f9ca7c1072a4ccc2e1fb689f87c19249d4b14","task":"iTerm2 Markdown 与浏览器插件安装","primary":"none","framework_change":false,"fits":false,"host_coupled":true,"why":"本机宿主环境安装，不属框架/域/kit 的职责。"},
+    {"episode_id":"29a32a0f00ad1287adf2b361a0eb1853e53fbb3bafaaa02387ec38b584d62994","task":"企业知识库领域知识出现商品","primary":"domain","framework_change":false,"fits":true,"host_coupled":false,"why":"业务数据/过滤规则，域内修复。"}
+  ]
+}

package/docs/research/model-boundary-patterns.md

@@ -0,0 +1,99 @@
+# 模型边界控制与调优：模式与修正（2026-10）
+
+> 日期 2026-10-28。范围：客户端侧（适配/中间件/路由/护栏/评测/监控），不做训练与 provider 私有参数。
+> 结论先行：**不做学习型路由、不做在线 bandit、不自造 telemetry 命名**；引入"档位纯函数 + 健康闸门"、"spec_id + 指纹"、"Kayenta 式 canary 判据"。
+
+---
+
+## A. 模式表
+
+| 模式 | 代表 | 解决什么 | 代价 | 级 |
+|---|---|---|---|---|
+| 别名 + 部署池 | LiteLLM Router（`order`/`weight`/`allowed_fails`/`cooldown_time`/`num_retries`） | 多 provider 统一；失败隔离到部署 | 别名膨胀、语义被抹平 | A |
+| 声明式网关 | Portkey config（`single/loadbalance/fallback/conditional`） | 策略与代码解耦 | 配置即代码，需 schema | A |
+| 客户端中间件 | Vercel AI SDK `wrapLanguageModel`；LangChain `@before_model/@after_model` | 请求/响应两侧插重试/日志/脱敏 | 流式改写要缓冲到块结束 | A |
+| Provider 抽象 | OpenAI Agents SDK `ModelProvider` | 换 provider 不改业务 | 能力差异靠探测 | A |
+| 学习型路由 | RouteLLM（`mf/sw_ranking/bert/causal_llm`） | 成本降 35–85% @ 同质量 | 需标定集；漂移后静默失效 | A |
+| 商业 Pareto 路由 | NotDiamond `tradeoff` | 免训练起步 | 黑盒 | A/C |
+| 统计式 canary | **Kayenta**（Mann-Whitney + pass/marginal 阈值 + 0–100 分） | 区分抖动与真退化 | 需基线时序与样本量 | A |
+| 阈值式 canary | Flagger / Argo Rollouts（`threshold`/`failureLimit`/`consecutiveErrorLimit`） | 简单、回滚时间可算 | 长尾不敏感 | A |
+| SLO 燃烧率 | Google SRE（14.4×/1h、6×/6h、1×/3d） | 少误报 | 低流量失效 | A |
+| 输入/输出护栏 | NeMo Guardrails / Guardrails AI / Llama Guard | "不许"变可执行 | **额外模型调用**（示例约 2×延迟、3.7×token） | A |
+| 遥测标准 | OTel `gen_ai.*`（仍 Development，已改名一次） | trace/指标/成本同键 | 上游会变 | A |
+| 按模型回归 | promptfoo / DeepEval / Inspect AI | 同题多模型 | 判分器自身要评；成本线性 | A |
+| 在线 bandit | 仅论文 | 在线学习 | 非稳态 + 反馈延迟 | C |
+
+**空档**：drift 检测在评测工具里不是一等公民（promptfoo/DeepEval/Inspect 只有矩阵对比）。
+
+---
+
+## B. 我们缺的六项（已确认）
+
+| # | 缺口 | 修正 |
+|---|---|---|
+| 1 | ModelSpec 只有名字 | 加 `spec_id = sha256(provider\|model_id\|snapshot\|tokenizer\|tool_protocol\|price_ver)` |
+| 2 | baseline 指纹未定义 | `fingerprint = sha256(suite_id\|n\|judge_id\|judge_ver\|temperature\|seed\|spec_id)`；判据改为**逐题 pass 集合 Jaccard ≥0.95**，flaky 题单列 |
+| 3 | 路由无健康度 | `gate(tier, health)`：`ok_rate_5m ≥ SLO`、`p95 ≤ L`、`cooldown_until < now`；回退目标写进审计 |
+| 4 | sidecar 缺症状分类 | `symptom_class ∈ {truncated, tool_arg_bad, refusal, hallucination, timeout}` |
+| 5 | 投票无 tie-break / 同源风险 | 不一致 → 人裁；judge 不得与被评模型同源（self-preference） |
+| 6 | 预算无单位经济 | 每任务 p50/p95、每档 ceiling、**重试计入同一 `task_id`** |
+
+---
+
+## C. 三条最值得引入
+
+### C1 档位纯函数 + 健康闸门（两级）
+
+```
+route(req) -> tier                         # 纯函数，可快照
+gate(tier, health) -> deployment | REFUSE  # 第二参数
+health(d) = { ok_rate_5m, p95_latency_5m, cost_1h, cooldown_until }
+准入: ok_rate_5m >= SLO_d 且 p95 <= L_d 且 cooldown_until < now
+```
+
+回退链显式声明，**"回退到谁"必须写进审计行**（LiteLLM 的 `fallbacks` + `allowed_fails` 语义）。
+
+### C2 ModelSpec + 指纹 baseline
+
+- 同 `fingerprint` 重跑才算对比；改了 judge/温度/题集 = 新实验体。
+- 判据：**Jaccard ≥0.95**，而不是"差 <5%"（后者无法钉住噪声源）。
+
+### C3 Kayenta 式降质检测
+
+```
+per_metric: pass | high | low        # Mann-Whitney 或比率比较
+final = Σ w_i·pass_i / Σ w_i         # 0–100
+fail  = final < marginal OR 任一 critical = high
+critical: 工具参数合法率（failureLimit = 1）
+```
+
+四个指标够：**参数合法率、任务完成率、p95 轮数、单任务成本**。
+参数合法率是唯一 critical——它掉就是硬伤，不看总分。
+
+---
+
+## D. 三条不该引入
+
+1. **学习型路由**（RouteLLM/NotDiamond 自训）：需上千偏好标注 + 稳定分布；我们一天几十任务，标定集比流量大。
+2. **在线 bandit**：反馈延迟以天计、奖励稀疏非稳态；用离线 A/B + 冻结集。
+3. **自造 telemetry 命名**：OTel `gen_ai.*` 仍在变（`gen_ai.system` 已改名）；只写 `gen_ai.*` + `dabo.task_id` 关联键。
+
+---
+
+## E. 对 dia 的落地清单
+
+| 动作 | 落点 |
+|---|---|
+| ModelSpec 字段 + spec_id | `docs/model-baseline-sidecar.md` §2 |
+| fingerprint + Jaccard 判据 | 同上 §2.2 |
+| gate(tier, health) | `docs/model-behavior.md` L6 |
+| symptom_class | sidecar 数据结构 |
+| 投票 tie-break + 异源 | `docs/model-behavior.md` L7 |
+| 成本按 task_id 归集 | `runtime/calls.jsonl` |
+| OTel `gen_ai.*` 字段 | 遥测（后续） |
+
+---
+
+## F. 参考文献（节选）
+
+LiteLLM Router、Portkey Config、Vercel AI SDK Middleware、LangChain Middleware、OpenAI Agents SDK Models、RouteLLM（LMSYS 博客 + arXiv:2406.18665）、Kayenta Judge、Flagger、Argo Rollouts Analysis、Google SRE Workbook（Alerting on SLOs）、NeMo Guardrails Rail Types、Guardrails AI `OnFailAction`、Llama Guard 4、OTel GenAI semconv、promptfoo CI、DeepEval、Inspect AI。均 2026-10 复核，A 级为主。

package/docs/research/opencode-session-scoping.md

@@ -0,0 +1,84 @@
+# opencode v2 会话分区调查（Project / Location / Workspace）
+
+> 日期 2026-10-28。问题：`opencode ./` 只看到当前目录的会话，是否是专门设计？和 workspace 有什么关系？
+> 结论：**是设计，不是 UI 过滤**。Project = 工作目录的身份；Workspace 是另一层（可选、实验性）。
+
+---
+
+## 1. 三层概念
+
+| 层 | 定义 | 行为 | 证据 |
+|---|---|---|---|
+| **Project** | 工作目录身份：Git 仓跟随 worktree 根；非 Git 目录在 V2 各自成 project（V1 统一 `global`） | 决定 `session list` / TUI picker 的范围 | 官方指南；本机 DB `project_id` |
+| **Location** | 每次请求的目录上下文：fs/tools/agents/providers/MCP 都在 `LocationServiceMap` 下 | 同一 server 可服务多个 location | V2 spec |
+| **Workspace** | 可选、实验性：session 可绑定 `workspace_id`（worktree） | 本机 34 条 session 全为 NULL | 测试代码 + 本机 DB |
+
+**一句话**：Project 管"看到哪些会话"，Location 管"用哪套文件/工具"，Workspace 管"绑哪个 worktree"。
+
+---
+
+## 2. CLI 行为（实测）
+
+| 命令 | 行为 |
+|---|---|
+| `opencode ~/proj` | 切到该 project |
+| `opencode`（不指定） | 默认 location（server cwd） |
+| `opencode session list` | **只列当前 project 的顶层会话**（子会话不出现），默认 100 条，`--format json` 可看 directory/project |
+| `--continue` | 只挑"记录目录 = 当前目录"的最新顶层会话 |
+| 跨 project | **没有 `--all`**；走 `GET /api/session`（支持 `scope/directory/path/workspaceID/roots`）或直接读 DB |
+
+`cli.json` 的 `session.new_location: inherit` 可让新会话跟随当前活动会话的位置。
+
+---
+
+## 3. 数据模型（本机 opencode.db）
+
+`session` 表关键列：
+
+```
+id, project_id, workspace_id, parent_id, directory, path, title,
+agent, model, time_created, time_updated, ...
+```
+
+- `project_id`：本机分布为 `global`（20）+ 两个具体 project（13/1）；V1 非 Git 目录统一 `global`。
+- `workspace_id`：本机全 NULL（实验特性）。
+- `directory` / `path`：记录会话发生的位置；`path` 是相对/项目内路径。
+
+---
+
+## 4. 坑
+
+1. **V1 迁移**：V1 非 Git 目录的会话挂在 `global` project，V2 picker 看不到；`GET /api/session` 能取到；修复用 `opencode api post /api/session/<id>/move --data '{"directory":...}'`。
+2. **目录改名/删除**：V2 已修（2026-09-02 #23248），但旧会话可能显示 "Session location unavailable"。
+3. **不是隔离**：共享 daemon 拥有全部会话；project 只是选择范围。隔离要用 `--standalone` / `--server`。
+4. **子会话**：`session list` 不列子会话，采集时要单独取或用 DB。
+
+---
+
+## 5. 对 dia ingest 的影响（已实现）
+
+episode 新增字段：
+
+```yaml
+project: string|null        # hash(project_id)，12 位
+workspace_id: string|null   # 原样（可能 null）
+directory_hash: string      # hash(directory)
+path_hash: string           # hash(path)
+```
+
+- **默认跨 project 全采**（直接读 DB）；`--project <id>` 只采一个。
+- 不依赖 `opencode session list`（会漏 global/跨 project/子会话）。
+- 仍不存原始路径，只存哈希；需要回源时用 source + session id。
+
+实测：27 条顶层会话分成 3 个 project；`workspace_id` 全 NULL。
+
+---
+
+## 6. 参考
+
+- opencode v2 CLI Intro（传目录切项目）· 2026-10 · A
+- opencode v2 session list 帮助（"current project, newest first"）· 本机实测 · A
+- opencode v2 API `POST /api/session`（location）· 2026-10 · A
+- opencode v2 session spec（LocationServiceMap、durable inbox）· dev 分支 · A
+- 社区指南《Where did my OpenCode session go?》· 2026 · C
+- 本机 DB 查询（project_id/workspace_id 分布）· 2026-10-28 · A