源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)

AGENT_GUI_CONTROLLER_REFACTOR_HANDOFF.md

@@ -0,0 +1,95 @@
+# Agent GUI 基建重构交接说明
+
+> 更新时间：2026-07-11
+>
+> 状态：架构重构已完成。协议、provider descriptor、canonical engine、消费方
+> selector 与纵向模块均已落地；只保留有明确发布窗口的私有持久化迁移读取。
+
+## 当前结论
+
+Agent 基建已经完成最危险的数据所有权迁移：Session、Turn、Interaction、
+queue、pending intent、activation、cancel、error 与 reconcile 由 workspace
+`AgentSessionEngine` 持有。Claude Code、Codex、OpenCode 以及其余注册 provider
+都通过同一份 descriptor/strategy/capability seam 接入；Claude Code 只走 SDK
+sidecar，Codex 走专属协议，OpenCode 走标准 ACP，但 GUI 不再按这三种传输形态
+选择业务行为。
+
+`useAgentGUINodeController.ts` 在本轮从 2,034 行降到 800 行以内，conversation-list
+projection、UI-local/deletion state、engine sync、operations 和 view assembly 均由
+独立纵向 hook 持有。controller 已低于 800 行硬限制，只保留模块装配。degradation
+终值基线已锁定；切片 7 只剩客户端覆盖窗口结束后删除私有 migration reader，
+该 reader 不属于公共契约、运行时 owner 或新写路径。
+
+## 已完成
+
+- OpenAPI v2、durable Turn/Interaction、exact-turn cancel、operation outbox 和
+  canonical session normalization 已落地。
+- engine 是 session/turn/interaction/queue/pending/error/reconcile 的生产 owner；
+  activation hook 只 dispatch engine intents，不再直调 runtime 并维护 React 状态机。
+- submit/queue optimistic overlay、conversation-list submit-pending 双轨、旧 queued
+  prompt coordinator 与旧 overlay 符号已删除。
+- `AgentGUINodeProps` 与 `AgentGUINodeViewModel` 已按语义职责分组；真实
+  view-model hook、垂直模块边界和 render-budget contract tests 已落地。
+- `AgentComposer.tsx` 为 597 行，`AgentGUINodeView.tsx` 为 783 行；旧 2,000+
+  行 conversation-list store 已退役。
+- `AgentHostWorkspaceAgentSession`、`AgentHostWorkspaceAgentMessage`、
+  `AgentHostWorkspaceAgentTimeline*` 的生产镜像扫描为零。旧 session write methods
+  已从 AgentHost seam 删除。
+- provider 行为分支扫描在 Agent GUI 和 desktop workspace-agent 生产代码中为零；
+  managed provider 集合、启动探测顺序、可见性、安装 bootstrap、账号刷新与 runtime
+  probe fallback 均来自 daemon descriptor 生成的 desktop strategy catalog。
+- persisted `providerTargetId` 只在私有 workbench/launch migration reader 中读取并
+  立即提升为 `agentTargetId`；新状态与 launch payload 只写 `agentTargetId`。
+
+## 延后清理
+
+当前审计未发现 Agent 基建 P0。非诊断消费方不再直读 `snapshot.sessions`；Host
+Session/activation/pin DTO、`providerTargetRef`、desktop canonical-to-Host session
+投影和合成 `session_update` 均已删除；activation settings/result 使用 core typed
+contract；`service_helpers.go` 已按 Codex status 职责拆到 769 行。
+
+切片 7 仍有一个按发布窗口执行的清理项：workbench 的 `providerTargetId` 读取是 persisted-state
+migration，必须保持私有、只读且不回写，并在客户端覆盖窗口结束后删除。
+Agent 作用域生产文件扫描已无超过 800 行的业务文件；通用 image download 命名与
+下载副作用也已从 `ZoomableImage.tsx` 拆为独立窄模块。
+
+## Provider 接入状态
+
+| Provider                    | Runtime seam         | Descriptor 状态                           |
+| --------------------------- | -------------------- | ----------------------------------------- |
+| Claude Code                 | SDK sidecar          | 已收口，不存在 ACP 注册                   |
+| Codex                       | 专属 app-server 协议 | 已收口                                    |
+| OpenCode                    | 标准 ACP             | 已收口                                    |
+| Cursor                      | 标准 ACP             | 已收口                                    |
+| Tutti Agent                 | 专属协议族           | 已收口                                    |
+| Nexight / Hermes / OpenClaw | 标准 ACP             | 已收口；不可用项显式 disabled/unsupported |
+
+传输协议不是 GUI seam。新增或修改 provider 行为必须经 daemon
+ProviderDescriptor 和 typed strategy/capability/catalog，不得在 controller、composer
+或 view 中新增 identity branch。
+
+## 最近验证
+
+本轮 controller 顶部切片验证：
+
+- `@tutti-os/agent-gui` `tsgo --noEmit` 通过；
+- scoped Oxlint 通过；
+- `AgentGUINode.spec.tsx` 161/161 通过；
+- 主 controller 从 2,034 行降到 800 行以内，只保留模块装配。
+
+当前工作树验证：Agent GUI 129 files / 1,827 tests、Desktop 1,193 tests、
+activity-core/GUI/desktop typecheck、provider strategy 与 activity-runtime boundary
+checker、provider catalog 生成检查、provider registry/daemon/store/tuttid tests、
+agentstatus tests/build、Go lint、desktop build 与 `git diff --check` 均通过。
+
+## 下一步顺序
+
+1. 完成持久化 migration 窗口后删除 `providerTargetId` 私有 reader 与其测试夹具。
+2. 后续变更持续执行 architecture review 与 `pnpm check:full`，不得提高已锁定基线。
+
+## 完成判定
+
+只有以下条件全部成立才能关闭本重构：controller 不超过 800 行且只是薄装配层；
+所有消费方通过 selectors 读取；兼容 seam 有明确删除或已删除；provider 行为只读
+descriptor/capabilities/catalog；无 Agent 业务文件违反 800 行规则；durable docs 与
+真实数据流一致；架构复审无 finding；`pnpm check:full` 通过。