create-windy 0.6.11 → 0.6.14

package/template/docs/architecture/agent-harness.md

@@ -0,0 +1,464 @@
+# Windy Agent Harness：移除 ADK 与可插拔演进方案
+
+状态：AH-0 仓库实现完成，候选集中验证与发布证据待执行
+
+更新时间：2026-08-27
+
+## 1. 决策摘要
+
+Windy 不再把 Google ADK 作为 Agent Runtime 的默认或可选内置实现。现有生产 Run 改由
+Windy 自有的 OpenAI-compatible Loop 执行；完成兼容迁移后，删除 `google-adk`、ADK
+Adapter、ADK Web、专用调试身份和 Starter 生成物。保留稳定的 `AgentEngineAdapter`、
+canonical Run/Event、Provider 与 Tool Host 接缝，未来可以接入其它 Loop，但平台基线不再
+携带 ADK。
+
+长期 Session、Memory、Workflow、多 Agent 和可视化仍是明确需求。它们建立在 Windy 自有、
+可持久化和受治理的 Harness 契约上，不再借用 ADK Session、Event 或 Web UI 作为事实源。
+
+以下能力明确不进入本路线：
+
+- Gemini Live 双向音视频；
+- Google Cloud Agent Runtime、Vertex AI Agent Engine 及其部署生态；
+- 生产 ADK Web 或 ADK 专属协议兼容层；
+- 为迁移保留一个无人使用的 ADK sidecar 或第二套 Session Store。
+
+## 2. 为什么现在移除
+
+迁移前的 Windy 只使用 ADK 的 `Runner`、单个 `LlmAgent`、每 Run 新建的
+`InMemorySessionService` 和 `Event`。Provider 请求、数据出网治理、Tool 执行、审批、用量、
+错误、取消、持久化与 SSE 都由 Windy 自己实现，再通过 Model/Tool/Event Bridge 转入转出
+ADK。ADK 因而没有成为事实源，只在 Windy 已有模型循环外再增加一层语义转换。
+
+仓库已经存在 `OpenAiCompatibleEngineAdapter`，覆盖模型轮次、Tool Call、审批等待、取消、
+Usage、结构化输出和输出上限。迁移的主要工作不是重写 Agent，而是冻结两套 Engine 的行为
+差异、补足直接 Engine 的契约测试，并安全删除 ADK 专属入口。
+
+移除后的直接收益：
+
+- 降低 Python 依赖、镜像、SBOM、离线 wheel 和漏洞审查范围；
+- 避免 ADK Event 与 Windy canonical Event、ADK Session 与 Windy Store 双重语义；
+- Provider、Tool、审批、Session 和 Workflow 的版本演进只维护一套契约；
+- 调试和轨迹查看回到 Windy 主 Web，不再要求开发者打开独立网站；
+- 模型与部署继续保持 OpenAI-compatible，不绑定 Google 运行时。
+
+## 3. Harness 定义与插件原则
+
+Windy 采用 `Agent = Model + Harness` 的理解：模型负责推理，Harness 提供环境理解、上下文、
+工具、执行、状态、恢复、约束和观察能力。DeepSeek Harness 的“一切皆插件”可作为设计参考，
+但其当前仍是 developer preview；Windy 不直接依赖或复制其 Cordis 内核。
+
+### 3.1 不可替换的治理内核
+
+以下能力必须保持在 Windy 核心，不能由普通插件替换或绕过：
+
+- Actor、Tenant、RBAC、Data Scope、Feature、License 与审批决策；
+- Manifest 组合、Schema 校验、稳定 Key、版本与依赖闭包；
+- canonical Session/Run/Turn/Step/Event 身份与追加顺序；
+- Execution Grant、Provider Data Policy、Tool Network Policy 和 Secret 边界；
+- Audit、幂等、租约、取消、留存、删除传播和安全失败语义；
+- 插件装配校验、健康状态、超时、资源预算和 fail-closed 行为。
+
+### 3.2 可替换的能力插件
+
+插件不是任意进程内代码注入，而是通过类型化 Registry 装配的受治理实现。优先复用已有
+Module Host 与 Manifest，不再创建平行的通用插件容器。
+
+| 插件能力                   | 责任                                         | 首个实现                                   |
+| -------------------------- | -------------------------------------------- | ------------------------------------------ |
+| Model Provider             | 模型协议、流式响应、Usage                    | OpenAI-compatible Provider                 |
+| Agent Loop                 | Turn/Tool 循环与停止条件                     | Windy Direct Loop                          |
+| Tool Provider              | 业务能力与副作用                             | 现有 Manifest Tool Registry/Host           |
+| Context Source             | 指令、最近事件、Skill、Artifact 摘要         | Windy Context Builder                      |
+| Session Store              | 追加 Event、恢复、fork/replay                | PostgreSQL Event Store                     |
+| Memory Projector/Retriever | 从事件派生记忆并按权限检索                   | 结构化投影 + 现有 Search/Embedding Adapter |
+| Workflow Node              | LLM、Tool、审批、等待、分支、子 Agent 等节点 | Windy 内置节点 + 模块扩展节点              |
+| Execution Runtime          | Workspace、Shell、Python/Node                | 隔离执行 Adapter                           |
+| Client Agent               | 页面等宿主本地循环                           | PageAgent Adapter                          |
+| UI Projection              | 聊天、Trajectory、Workflow 图                | Windy Web 投影                             |
+
+插件只能声明能力，不能自行授予权限、解析平台 Secret、直连 Repository 或改变 canonical
+Event。依赖缺失、Key 重复、版本不兼容或策略未声明时，Composition 必须在启动前失败。
+
+### 3.3 开源复用而非复制核心实现
+
+- 页面理解、页面 Tool Call 和 DOM 节点操作使用 PageAgent；Windy 只实现 Client Session、
+  安全 Adapter、业务 Tool 与结果投影，不重写 PageAgent Loop。
+- Workflow 画布优先评估成熟 Vue 3 节点编辑器，例如 Vue Flow；V1 只需要只读预览时可使用
+  已有图可视化依赖。Windy 不自研缩放、拖拽、连线、MiniMap 和布局引擎。
+- 持久任务复用现有 Durable Job；人工批准复用 `system.workflow` 的最小审批原语。二者是
+  Workflow Node 的 Adapter，不再各自创建新的 Job/Approval 状态机。
+- Memory 检索复用 SearchProvider、Embedding Runtime 和数据库 Adapter；不在 Agent 模块内
+  自研向量数据库。
+- 引入任何新框架前记录许可证、活跃度、安全、离线交付、升级与退出成本。框架只能位于
+  Adapter 后方，不能成为业务 Manifest 或 canonical 数据格式。
+
+## 4. 目标运行架构
+
+```mermaid
+flowchart LR
+  UI["Windy Web / Client"] --> API["Canonical Agent API"]
+  API --> Guard["Identity / RBAC / Scope / License"]
+  Guard --> Harness["Agent Harness Core"]
+  Harness --> Session["Session Event Store"]
+  Harness --> Context["Context Builder"]
+  Harness --> Loop["Agent Loop Plugin"]
+  Loop --> Model["Model Provider Plugin"]
+  Loop --> Tools["Governed Tool Host"]
+  Loop --> Workflow["Workflow Runtime"]
+  Workflow --> Jobs["Durable Job"]
+  Workflow --> Approval["Approval Work Item"]
+  Workflow --> Children["Child Agent"]
+  Harness --> Memory["Memory Projection / Retrieval"]
+  Session --> Projection["Chat / Trajectory / Workflow Projection"]
+  Projection --> UI
+```
+
+外部 HTTP/SSE 客户端只依赖 canonical API。Engine、Provider、Workflow 或 UI 插件更换不得
+改变既有 Run 创建、cursor 重放、取消、唯一终态和 Tool 授权语义。
+
+## 5. ADK 移除迁移
+
+### 5.1 阶段 A：冻结兼容基线
+
+先把当前 ADK Engine 的外部可观察行为固化为共享 Contract Suite。至少覆盖：
+
+- 无 Tool、单 Tool、多 Tool 和多轮 Tool；
+- Tool allowlist、参数拒绝、审批 pending/approved/rejected；
+- 文本 delta、结构化输出、Citation/Source、Vision Artifact；
+- Provider Data Policy、请求大小、输出上限和最大模型轮次；
+- Usage attempt、Provider report、readiness、capacity 与 deployment attestation；
+- 用户取消、deadline timeout、Provider 失败、Tool 失败和进程任务取消；
+- canonical Event 顺序、SSE cursor 重放、最终结果和错误码。
+
+测试只比较公共 Engine Signal 和 HTTP/Event 契约，不把 ADK 私有 Event 当快照。固定一组
+真实 OpenAI-compatible Provider 录制 fixture 与确定性 Tool Host fixture，作为切换门禁。
+
+### 5.2 阶段 B：直接 Engine 补齐并切换
+
+`runtime_factory` 改为默认创建 `OpenAiCompatibleEngineAdapter`。未配置 Provider 时使用明确的
+`UnavailableEngineAdapter` fail closed，不再利用“空 ADK Adapter”表达未配置状态。
+
+切换要求：
+
+- 不修改 `POST /api/agent/runs`、SSE、结果、取消和健康检查的公共 DTO；
+- 不修改 Manifest Operation/Tool 定义及 Execution Grant；
+- 不改变 Tool Host 的二次授权、command receipt 和审批恢复；
+- 新 Run 的 runtime attestation 使用新的稳定 Engine ID；历史 Run 的旧 ADK attestation
+  保持可读，不回填、不伪造为直接 Engine；
+- Client Agent Session、PageAgent 和其它宿主本地 Loop 继续走自己的受治理端点，不被服务端
+  Engine 切换改写；
+- 暂不增加 `AI_ENGINE` 长期配置。迁移分支可有测试开关，发布基线只保留一个默认 Engine，
+  避免形成永久双实现。
+
+### 5.3 阶段 C：删除生产 ADK Bridge
+
+直接 Engine 通过 Contract Suite 后删除：
+
+- `adk_adapter.py`、`adk_model.py`、`adk_tools.py`、`adk_event_merge.py`、
+  `adk_failure.py` 及其专属测试；
+- `google-adk` 和仅由它引入的传递依赖；
+- ADK 类型、版本号与 deployment facts 文案；
+- 只验证 ADK Runner 的测试，保留并迁移所有平台治理与回归场景。
+
+执行依赖裁剪后重新生成锁文件，构建联网和离线镜像，比较 wheel 清单、镜像体积、SBOM 和
+启动 readiness。不得手工删锁文件条目。
+
+### 5.4 阶段 D：用 Windy 主站替代 ADK Web
+
+在删除 ADK Web 前，先让开发者能从 Windy 主 Web 查看同一 canonical Run 的聊天结果和
+Trajectory。V1 是只读投影，不要求完整 Workflow 编辑器：
+
+- 使用当前登录身份，不创建 `service_adk_debug`；
+- 复用正常 Run、Session、Audit 与权限，不签发第二种调试 Token；
+- 展示 Turn、Model、Tool、Approval、Artifact、失败、取消和受控摘要；
+- 不显示 chain-of-thought、Secret、原始未脱敏 Provider body 或完整 Tool 参数；
+- 可从业务会话进入 Run，也可按有权限的 Run ID 打开；独立开发站点不再存在。
+
+随后删除 ADK Web agents、debug Session Service、Compose wrapper、启动脚本、专用路由、专用
+身份和 `ADK_DEBUG_*`/`WINDY_ADK_DEBUG_*` 配置。
+
+现有 `registerDebugSessionProviders()` 不应突然破坏下游模块。先提供与 ADK 无关的
+`registerAgentSessionProviders()`，让主站投影消费同一 Provider；旧方法作为 deprecated alias
+保留一个兼容发布周期，但实现不再依赖 ADK。下一次明确的破坏性版本再移除旧名称。
+
+### 5.5 阶段 E：Starter 与下游升级
+
+`create-windy` 停止为新项目生成 ADK 依赖、`dev:adk-web`、debug compose、debug JSON、Token
+说明和相关文档。升级 recipe 按 ownership 处理：
+
+- 对内容未漂移的 windy-managed 文件执行删除或替换；
+- 对客户修改过的 managed 文件 fail closed 并输出人工迁移说明；
+- project-owned `apps/agent-server/project/adk-web-debug.json` 不自动删除，只报告为无效遗留，
+  由项目所有者确认后移除；
+- 普通 `.env` 中已有非空 ADK Token 不自动改写或删除；`windy doctor` 只提示它已弃用；
+- 数据库不需要删除式 Migration。旧 Run、Event、Report、Audit 和业务会话继续可读；
+- 生成矩阵覆盖未选 `system.agent`、选择 Agent、从上一公开版本升级和客户文件漂移四种情况。
+
+升级后的下游项目继续使用 `bun run dev:agent`。原 `dev:adk-web` 不静默指向另一项行为；命令
+应被移除，并在升级报告中给出主站 Trajectory 的替代入口。
+
+## 6. 长期 Session 与 Memory
+
+### 6.1 Session 是追加事实源
+
+Session 使用稳定的 Session/Run/Turn/Step ID 和 append-only Event Log。聊天消息、摘要、
+Trajectory 和 UI 都是投影，不各自保存互相漂移的“完整历史”。每次模型请求记录实际使用的
+Context 来源、版本和 digest；进程重启后从持久事实恢复，而不是依赖进程内对象。
+
+Session 必须支持：
+
+- 多 Run/Turn、并发控制、steering、cancel、resume；
+- checkpoint、只读 replay 和 fork；
+- Schema 版本迁移与未知事件安全拒绝；
+- Actor/Scope 变化后的重新授权；
+- 删除、归档和 retention 向投影、索引与 Artifact 传播。
+
+副作用 Tool 默认不因 replay/fork 重做。重新执行必须显式选择策略，并继续通过当前授权、审批、
+幂等和 command receipt。
+
+AH-1 的平台实现使用 `agent_sessions` 保存当前头指针和治理绑定，使用
+`agent_session_events` 保存加密 Event payload、明文事件类型、sequence 与 digest。Event ID
+用于提交重试去重，Session `head_sequence` 用作 CAS；Checkpoint、Fork 与归档均与对应 Event
+在同一事务内提交。重启后只从 PostgreSQL 事实恢复，不从 Run Event、Client Agent Session、
+浏览器缓存或内存对象重建长期 Session。
+
+现有 Agent Run 启动请求可显式携带 `sessionId`。Server 在调用 Runtime 前按当前 Actor 与 Scope
+重新授权并追加 `turn.started`，Runtime 返回真实 Run ID 后追加 `run.linked`；启动失败追加受控
+Turn 终态。Run 仍是一次执行，Session 仍是跨 Run 的事实容器，两者不得互换。
+
+业务 `prepare` 给出的单一 `caseId` 由 Host 规范化为 Memory Scope，并同时固化到 Run 授权绑定、
+`turn.started` 与 Context Version。相同幂等坐标不能切换案件；Agent Server 的 prepare、commit、
+abort 回调必须与绑定完全一致。V1 不接受隐式跨案合并，也没有跨案 grant 时，缺失案件坐标表示
+不得恢复或检索任何案件绑定内容。
+
+终态结果遵循“幂等投影、持久 Receipt、关闭 Turn”的顺序。`turn.completed` 不能先于
+`Terminal Projection Receipt`；若进程在投影或关闭之间崩溃，Reconciler 同时扫描开放 Turn 与
+closed-but-unprojected 状态，按固定 Run/terminal sequence/result digest 重建或拒绝坐标漂移。
+Receipt 证明投影步骤完成，但不拥有对应 Memory；用户删除单项投影不会被 Receipt 反向恢复。
+失败、取消和 attach 都走同一持久 Run binding，纯 SSE `/events` 只做既有 Run read Guard，任何
+会写长期 Session 的终态路径才额外要求 `system.agent-session.manage`。
+
+`ContextBuilder` 为每个 Model attempt 装配受治理来源，但只有数据出网治理完成后的 Provider
+实际输入才能形成不可变 Context Version。调用分成两阶段：prepare 在当前 Actor、Scope、Feature、
+License 和对象授权下返回允许治理的来源；Agent Server 完成 DLP、Provider policy 和消息归一化后，
+commit 持久化最终消息顺序、角色、来源关系、每条消息 digest、工具与输出 schema digest，以及实际
+Provider request digest。commit 必须在 Provider 看到输入前成功；治理拒绝、prepare 过期、来源
+复核失败或持久化失败都不得留下 `active` 版本，也不得声称请求已经发送。
+
+恢复工作线时，Builder 读取此前已提交 Context Version 的白名单消息投影、已完成 Run 的最终结果、
+Session Summary、可用 Memory、ArtifactRef 与 Tool receipt。它不读取或保存模型原始推理链、隐藏
+Provider 字段、原始 Tool 参数或未经治理的二进制；二进制输入只保留 ArtifactRef。最终 Context
+必须包含 instructions、当前 user prompt、Artifact、历史 assistant/tool 结果和 Memory 等实际发送
+来源，不能只记录当前 `turn.started` 的引用元数据。
+
+历史消息只从相同 Memory Scope 的 active Context Version 恢复；案件坐标缺失或不同的版本一律
+排除。Context 同时持久化被消费 Memory 投影自身的 ID/version/sequence/digest 与其底层权威来源链；
+后续 Memory 的 TTL 或删除失效可以直接命中消费它的 Context，派生 Memory 也保留该直接依赖并沿
+来源链收敛。Memory-to-Memory 复核允许有界递归，但环、深度或坐标上限都会 fail closed。
+
+每个来源必须包含 moduleKey、kind、ID、version、sequence、模型可见投影 digest、核验时间、TTL
+和有效性；录入失败时 Model attempt fail closed。Agent Server 的 Provider 循环经内部认证端口回调
+Server；普通未绑定长期 Session 的 Run 不调用该端口。平台只提供 module-authoritative Adapter
+注册 seam；当前 `system.agent` 来源由生产 Adapter 提供，业务来源必须由所属模块注册权威对象
+Adapter，缺少 Adapter 或无法确认对象时稳定 fail closed，不能构造假的业务对象授权。
+
+### 6.2 Memory 是受治理投影
+
+Memory 不等于把全部聊天和网页永久塞回 Prompt。V1 分为：
+
+| 层级            | 内容                                   | 默认留存           |
+| --------------- | -------------------------------------- | ------------------ |
+| Working Context | 当前 Turn 临时材料                     | Run/Turn 生命周期  |
+| Session Summary | 可解释的会话压缩与待办                 | 随 Session         |
+| User Preference | 展示和工作偏好，不含案件事实           | 用户可查看/删除    |
+| Business Memory | 带来源、范围、置信与复核状态的业务事实 | 由业务模块策略决定 |
+
+Memory Projector 只能从已授权 Event、Artifact 和业务事实生成结构化候选；业务 Memory 必须保留
+来源引用，不能把模型总结自动提升为领域真相。Retriever 每次按当前 Actor、Scope、Feature、
+License、TTL 和对象授权查询。撤权、删除、归档或来源失效必须传播到搜索与 Context。
+
+AH-1 将 Working Context、Session Summary、User Preference、Case Memory Candidate 与
+Verified Fact Reference 建成互斥类型。候选只有 `pending`/`rejected`，不能原地变成 Verified Fact；
+Verified Fact 只保存权威业务对象引用。Memory 检索在每次调用时重新检查 Feature、Permission、
+License、Scope、TTL 与对象授权，跨案候选不会自动合并。
+
+五类 Memory 均通过生产 Projector 的显式 append 入口生成，不以“已有表结构”冒充闭环：Turn/Run
+结果可派生 Working Context，Session 事实边界可派生 Session Summary，用户确认可写 User
+Preference，业务模块可提交 Case Memory Candidate，权威业务模块核验后可写 Verified Fact
+Reference。每次长期 Session attempt 都调用 Retriever；只有当前 Actor、Scope、Feature、License、
+TTL、复核状态和逐来源对象授权全部通过的投影才可进入 prepare。Case candidate 与 Verified Fact
+不是永久排除项，但缺少所属模块权威 Adapter 时必须拒绝。
+
+业务模块通过当前 `ModuleRequestContext.sessionMemory` 的 V1 端口触发 User Preference、Case
+Memory Candidate 与 Verified Fact Reference；Host 固定当前模块的 `moduleKey` 并绑定当前请求
+Actor/Scope。模块不能声明其它模块身份。Working Context 与 Session Summary 由 Context commit 和
+Run 终态投影触发；若客户端只消费 SSE 后断开，下一次长期 Session prepare 会先读取持久
+`run.linked`，向 Agent Runtime 复核终态、补投最终结果并关闭 Turn，再构建 Context。
+
+Working Context 无论调用方是否指定过期时间，都被限制在 Run/Turn 生命周期内，当前上限为 24 小时；
+调用方只能缩短，不能延长，Host 配置超过 24 小时会在 Composition 阶段直接拒绝。过期 Worker 先以
+条件更新收敛投影，再在同一事务追加 `source-expired`
+Outbox，使 Context、Memory、Search、Embedding 与 UI 复用既有五路失效传播。
+
+Case Memory 的检索必须携带业务 `prepare` 显式给出的当前 `caseId`；Session 血缘不能充当当前案件。
+Host 仍通过所属业务模块的权威对象 Adapter 复核来源、案件和当前 Actor/Scope。没有 `caseId`、没有
+Adapter 或无法确认授权时，Case Memory Candidate 与 Verified Fact Reference 均被安全排除，不会
+跨案自动混合。
+
+业务来源生命周期通过 `ModuleRequestContext.sourceInvalidation` 发布 deleted、expired、superseded
+或 authorization-revoked。Host 固定 Module Key 和当前授权坐标；调用方只提供本模块对象及领域事件
+坐标。底层 Producer 可绑定业务事务的 append seam。用户、角色和数据范围变更在平台身份事务内
+追加撤权 Outbox；读取路径同时重新解析当前 Actor，因而异步投影尚未收敛时仍 fail closed。
+
+来源失效使用版本化 Outbox，一条因果事实拆成 Search、Embedding、Context、Memory 与 UI 五个独立
+Delivery。权威来源生命周期或 Session 归档与 Outbox 写入同一数据库事务；各 Delivery 使用
+Lease、重试和幂等 ID。Memory 投影自身删除只删除该 projection，不发布 `source-deleted`，也不
+影响同源其它投影。Context 以自身 `sessionId` 标识派生 Session；Memory 另存
+`derivedFromSessionId` 与派生时覆盖的事实序列，其使用范围仍可独立为 session、user 或 case。
+Session 归档发布 `session-derived` 范围，并按派生
+坐标收敛该 Session 产生的所有投影；不能只匹配 `scopeKind=session`，也不能冒充业务来源删除。
+
+生产 Composition Root 已装配 Context/Memory 失效 Adapter、共享 canonical Memory 投影的
+Search/Embedding Adapter、UI Adapter 和 Outbox Worker 调度。读取路径仍逐来源调用权威对象
+Guard 并 fail closed，不能等待异步索引收敛后才拒绝。若部署引入独立 Search/Embedding 索引，
+必须用真实索引删除 Adapter 替换共享投影 Adapter；队列未清空时不得声称传播完成。
+
+主站 `/admin/system/agent-sessions` 只展示白名单投影：Session 状态、公共 Run/Turn/Step 引用、
+Context 来源坐标和受控 Memory 摘要。它不返回原始 Prompt、Tool 参数、Memory content/value/claim
+或模型原始推理链。
+
+## 7. Workflow 与多 Agent
+
+### 7.1 Workflow 事实模型
+
+Agent Workflow 是版本化有向图，不扩展现有 `system.workflow` 审批状态机来承载。当前
+`system.workflow` 只作为 Approval Node Adapter；Durable Job 作为等待、后台执行和恢复
+Adapter。
+
+首批节点类型：
+
+- `model`：一次受治理模型调用；
+- `tool`：调用 Manifest Tool；
+- `subagent`：创建受限子 Agent；
+- `condition`：对类型化结果做确定性分支；
+- `parallel` / `join`：有界并行与汇合；
+- `approval`：创建并等待审批工作项；
+- `job` / `wait`：提交 Durable Job 或等待外部事实；
+- `artifact`：校验并封存输出；
+- `final`：生成符合 Output Schema 的最终结果。
+
+定义以代码或 YAML/JSON Schema 为事实源，发布后形成不可变 Workflow Release。每个 Run 固定
+Workflow、Prompt、Tool Schema、Route 与 Runtime 版本。模型不能生成未知节点、提升自己的 Tool
+集合或改写执行预算。
+
+### 7.2 预设优先，在线编排后置
+
+先交付由开发者审核的预设 Workflow，例如“检索证据 → 时间线/关系/资金并行分析 → 来源校验
+→ 人工复核 → 报告草稿”。业务模块只组合稳定 Tool/API，不把领域 Repository 暴露给 Agent。
+
+第一阶段在 Windy 主 Web 提供只读 Workflow 图与实时节点状态。第二阶段才提供可编辑画布、
+Schema 校验、diff、试跑、审批、发布和回滚。画布使用成熟开源组件；UI layout 不是 Runtime
+事实，拖拽坐标变化不能产生新的业务 Release。
+
+### 7.3 多 Agent 是受限委派
+
+子 Agent 是带独立身份坐标、预算、Context、Tool allowlist、Workspace 和终态的 Session/Run，
+不是函数内递归调用。父 Agent 只能传递明确 Artifact/摘要并等待类型化结果；子 Agent 不继承父
+Agent 的全部权限、Secret、网络或数据范围。父子关系写入 canonical Event，取消、deadline 和
+预算向下传播，失败由 Workflow 的显式策略处理。
+
+AH-2 的完整事实模型、side-effect command fence、评测 identity 与只读 Vue Flow 边界见
+[Agent Workflow、委派与评测](./agent-workflow.md)。该实现继续把审批和 Durable Job 保持为
+Adapter，并以 fresh-deploy 0061 建立结构性 schema，不包含旧开发数据兼容 DML。
+
+## 8. 兼容、发布与回滚门槛
+
+### 8.1 不允许变化的公共行为
+
+- Run、SSE、Result、Cancel、Health/Readiness 的 URL 和 DTO；
+- Manifest Operation/Tool Schema、Feature/Permission/License 与审计动作；
+- Execution Grant、Tool Host、审批、command receipt、ArtifactRef；
+- Client Agent Session 与 PageAgent 的受治理模型端点；
+- 历史 Run、Report、Usage、Audit 和 Citation 的读取能力。
+
+### 8.2 发布门禁
+
+每个阶段使用独立小提交。最终候选至少通过：
+
+1. Python ruff、mypy 和 Agent Server 单元/合约测试；
+2. TypeScript lint、typecheck 与受影响模块测试；
+3. Agent 生成矩阵、update recipe、pack consumer 和离线构建；
+4. ADK 与 Direct Contract Suite 行为对照；
+5. 真实 PostgreSQL 的 Run/Event/Report 兼容读取；
+6. OpenAI-compatible 文本、Tool、Vision、审批、取消和 Provider 失败集成；
+7. 现有利剑 PageAgent/Client Agent Session 消费验证；
+8. SBOM、镜像、无公网依赖启动和旧环境变量容忍检查。
+
+### 8.3 回滚
+
+切换发布前保留上一版本镜像与数据库备份。迁移只追加或保持 Schema，不删除历史事实，因此
+应用回滚不需要数据降级。若 Direct Engine 在候选阶段出现行为差异，回滚整个应用候选，不在
+生产环境用动态开关切回 ADK。ADK 文件和依赖只有在 Direct Engine 已通过全部门禁后才从下一
+候选删除。
+
+AH-1 Session/Context/Memory 在本版本定义为 fresh-deploy baseline：不迁移、不读取旧开发期 Agent
+聊天历史或 AH-1 派生日志。首次验收从清空旧开发 Docker 容器及其数据卷后的空 PostgreSQL 启动，
+由 0058、0059、0060 顺序建立当前 schema；正式既有 Run 审计、Client Agent Session、Artifact、
+审批、上传和业务数据不属于这项开发期数据边界。
+
+## 9. 实施顺序
+
+AH-0 已完成前五项的仓库实现：兼容 Contract、Direct 默认 Engine、Bridge/依赖删除、主站
+Trajectory/Agent Session Provider，以及 create-windy 生成与升级 recipe。第 5 项中的下游利剑
+升级和所有候选/发布验证由发布流程执行，不属于本次仓库实现证据。
+
+AH-1 已建立 Session Event Log、PostgreSQL Checkpoint/Replay/Fork、Context/Memory 契约、来源失效
+Outbox、生产 ContextVersion 回调、失效 Worker 和主站只读投影。仓库装配不能替代真实
+PostgreSQL/Provider、容器重启、并发 CAS、撤权传播和独立 Search/Embedding 索引评测。
+
+后续顺序保持为：
+
+1. 完成 AH-1 真实 Provider attempt、真实部署传播与恢复演练；
+2. 发布预设 Workflow、只读图和节点运行状态；
+3. 增加受限子 Agent 与 Harness 级评估；
+4. 有真实非开发人员编辑需求后，再接入成熟画布实现在线编排。
+
+ADK 移除不等待长期 Session/Workflow 完成；但删除 ADK Web 前必须有主站 Run/Trajectory 的替代
+入口。Session、Memory、Workflow 和多 Agent 按上述顺序增量交付，不能以一次大重写替换现有
+可用 Run。
+
+### 9.1 建议提交切片
+
+当前 Windy 工作区若还有 Client Agent Session 或其它未提交实现，先把它们完成并独立提交；
+不要把 ADK 迁移混入同一 diff。随后按以下可单独回滚的切片执行：
+
+1. `test(agent): freeze engine compatibility contract`：只增加共享 fixture 与 Contract Suite；
+2. `feat(agent): make direct engine canonical`：补 unavailable Engine、切换工厂和 attestation；
+3. `refactor(agent): remove google adk runtime bridge`：删除生产 Bridge、依赖并刷新锁文件；
+4. `feat(agent): expose native run trajectory`：主站投影与通用 Session Provider；
+5. `refactor(agent): remove adk web debug surface`：删除专用身份、路由、Compose 和脚本；
+6. `feat(create-windy): migrate projects off adk`：生成矩阵、recipe、doctor 和 pack consumer；
+7. `docs(agent): make windy harness framework independent`：把现状文档、README 和 ADR 更新为
+   Direct Engine 与 Windy Session/Workflow 事实。
+
+每个切片先运行直接相关的静态检查和测试；最终合并候选运行 `bun run test:merge`，发布候选运行
+`bun run release:verify`。Agent Server 至少运行：
+
+```bash
+uv run --directory apps/agent-server ruff check .
+uv run --directory apps/agent-server ruff format --check .
+uv run --directory apps/agent-server mypy
+uv run --directory apps/agent-server pytest
+```
+
+依赖删除后再运行一次联网构建和使用固定 wheel/镜像缓存的离线构建。最后执行全仓搜索；除迁移
+说明、Changelog 与历史兼容 fixture 外，不得再存在 `google-adk`、`google.adk`、ADK Web
+Compose、`service_adk_debug` 或活跃 `ADK_DEBUG_*` 配置。
+
+## 10. 参考
+
+- [DeepSeek Harness](https://deepseek.com/harness/en/)：插件化 Harness 与追加 Session Log
+  的设计参考；当前 developer preview，不作为 Windy 生产依赖。
+- [DeepSeek Harness Architecture](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)
+- [Vue Flow](https://vueflow.dev/)：Vue 3 Workflow 画布候选；采用前仍需完成依赖评估与固定版本。
+- [PageAgent](https://github.com/alibaba/page-agent)：页面理解与浏览器动作复用边界。

package/template/docs/architecture/agent-workflow.md

@@ -0,0 +1,99 @@
+# Agent Workflow、委派与评测
+
+## 边界
+
+AH-2 在 `system.agent` 内提供预设 Workflow 的发布、持久运行、恢复、受限委派和只读投影。
+它不把 `system.workflow` 审批状态机改造成图引擎：Approval Work Item 和 Durable Job 都只是
+类型化 Node Adapter。PageAgent 仍只通过 Client Agent Session 在浏览器宿主运行，不能嵌入
+服务端 Workflow Runtime。
+
+`system.agent-workflow` Feature 依赖 `system.agent`，仅 Advanced License 可用；读取与管理分别
+要求 `system.agent-workflow.read`、`system.agent-workflow.manage`。API、菜单、路由和审计动作
+都引用这些 Manifest Key。每次创建、委派、恢复和 Artifact 打开还要重新执行 Actor、Scope、
+Feature、Permission、License 与对象授权，客户端提交的授权摘要只能用于冲突检测，不能授予权限。
+
+## 事实模型与不变量
+
+- Workflow Definition 是版本化有向图；节点只允许 `model`、`tool`、`subagent`、`condition`、
+  `parallel`、`join`、`approval`、`job`、`wait`、`artifact`、`final`。每个节点必须声明失败策略：
+  fail run、有限次数带 backoff 重试，或显式 skip。
+- Immutable Release 固定规范化 Definition，以及 prompt、route、manifest、tool schema 和 runtime
+  坐标。`releaseDigest` 由二者计算；Repository 只允许 insert，同 digest 重放返回原 Release，
+  任何 identity 或 JSON 漂移都拒绝，禁止更新 `release_json`。
+- Workflow Run 固定 Release、Actor、Scope、Budget，以及 authorization、tool、workspace、execution
+  policy digest。Run 与 Node Run 只允许共享契约声明的转换；终态必须同时写 `finishedAt`。
+- Budget 使用预留账本控制 duration、模型尝试、Tool、子 Agent、并行度、token 和 cost。Usage
+  明确区分 measured 与 unknown；存在对应上限而 Provider 未上报时 fail closed，不能把 unknown
+  当作零。
+- Cancellation 向未终结 Node 与子级传播；Recovery 不是重放整个 Run，而是在当前授权与剩余
+  Budget 下协调未决 command、receipt 和可恢复 Node。恢复次数、Run/Node version 与 Event sequence
+  都使用 CAS。
+- Side-effect command fence 在调用 Tool、Approval、Job、Subagent Adapter 前持久化 prepared
+  command。Adapter 用稳定 idempotency key 提交；返回后持久化外部 receipt。若进程在外部提交后
+  崩溃，Recovery 先按同一 command coordinate 查询或协调 Adapter，再提交 Node 终态，绝不盲目
+  重做副作用。
+- condition 的选择、小型类型化结果、result digest 与 ArtifactRef 形成 Node result receipt，
+  并与 Node 终态、canonical Event 在一个原子提交中落库。这样在选择分支后、调度后继前崩溃
+  仍能从事实恢复。
+
+`0061_agent_workflow.sql` 只为清空旧 Docker 容器和数据卷后的 fresh deploy 增加结构性 DDL。
+它不清理、搬迁或兼容旧 Agent 会话、聊天与开发日志。Run 下游 Node、Event、Delegation、Budget、
+side-effect 与 Evaluation 使用 `RESTRICT` 或独立 retention，不允许删除 Run 顺带抹除审计与恢复
+事实。
+
+## 委派
+
+Delegation 固定 `childAgentRunId`；父子 Workflow 因果 Event 使用独立的
+`childWorkflowRunId`，两类坐标不能混用。子 Agent 的 capability、Tool allowlist、Budget、
+Workspace、Scope 与 policy 都独立冻结。
+
+有效委派策略必须同时满足：
+
+1. Immutable Release 声明的 required Feature/Permission 原样继承，调用请求不能删除；
+2. 父级 ceiling 与当前 Host 授权都包含全部 required guards；
+3. Tool allowlist 是 Release、父级、当前 Host 与请求收窄集合的交集；
+4. Scope、Workspace、capability 和执行策略不比 Release 或父级更宽；
+5. Budget admission 在同一串行化边界内比较父级剩余量并预留；恢复时再次比较当前授权。
+
+父子只通过 canonical Parent/Child Event、受控摘要、Node result receipt 与 ArtifactRef 交付。
+不复制原始推理链、Provider body 或大对象。子 Agent 结果是待核验输出，不会自动成为业务事实；
+写 Tool 仍走现有审批、对象授权、幂等 command 和 receipt。
+
+## ArtifactRef
+
+持久 ArtifactRef 只保存稳定 coordinate：artifactId、hash、size、media type、retention policy、
+source module/kind/id/version。`expiresAt`、authorization status、下载 URL、Bearer token 和其它
+短期引用不得成为持久业务事实。每次打开 Artifact 都以当前 Actor/Scope/Object 重新授权，并由
+Storage Host 签发短期下载凭据。
+
+## 固定评测 contract
+
+Evaluation 在完全相同的 case input、模型/部署配置、Tool schema/runtime policy/allowlist、Budget、
+Scope、authorization、Workspace、execution policy、runtime 与 rubric 下，对比单 Agent 与多 Agent。
+identityDigest 同时覆盖两臂 releaseDigest，以及各自 route、prompt、manifest 坐标；任一组合变化
+都会形成新评测。
+
+每个 arm 独立保存 status、nullable Run、metrics 和 evidence。`unavailable` 不伪造 Run；服务端在
+同一事务或一致快照中确认 Run 固定对应 Immutable Release。指标记录完成率、时延、成本、token、
+失败、人工接管、evidence quality、安全拒绝和恢复能力。Provider 未上报的 token/cost 必须为
+unknown/null，并带 measurement/source/status，不能写零。只有真实 Provider、真实 Tool/Artifact/
+receipt 与可复核 rubric evidence 才能形成结果；仓库契约、fixture 或本地空数据库不能冒充评测。
+
+## 只读图与第三方依赖边界
+
+主站使用 `@vue-flow/core` `1.48.2` 的 MIT 许可版本，仅呈现由 canonical Run/Node 投影生成的
+只读图。依赖锁定在 Bun lockfile 并随 Web 静态资源离线交付，不使用运行时 CDN。允许 pan、zoom、
+fit view 与选择 Node；禁止连接、拖动、删除、在线编辑或把布局坐标回写业务事实，同时提供语义化
+节点列表作为键盘与读屏替代。
+
+采用前的最小评估结论是：该 Vue 3 组件仍有维护中的正式发布，许可证与当前分发兼容；图交互
+属于 UI Adapter，不进入 Workflow Definition、Release 或 Event。升级时检查 changelog、依赖漏洞
+与离线 bundle；若维护或安全条件不再满足，可替换单一图组件，列表投影与 Runtime 事实保持不变。
+没有真实编辑需求前不引入 Dagre/ELK、Minimap、Controls 或在线编辑器能力。
+
+## Composition 与 Adapter
+
+Composition Root 为 Workflow Repository、Evaluation Repository、Approval Adapter、Durable Job
+Adapter、Governed Tool Host 与 Subagent Adapter 各绑定一个实现。生产使用 PostgreSQL Repository；
+进程内 Repository 只用于受限开发或契约验证，不能作为可恢复运行事实源。未知 Node、缺失 Adapter、
+重复 Key、Release 漂移或未声明 Manifest guard 必须在启动或接收命令时 fail closed。