CherryHQ-cherry-studio/v2-refactor-temp/docs/ai

AI Refactor — Reviewer Guide

The AI domain is the largest single surface in the v2 refactor. The renderer's src/renderer/src/aiCore/ tree (~80 files) is deleted in full; its logic ports into src/main/ai/ (~150 files). The transport becomes IPC + a Main-owned active-stream registry. This directory breaks the change into clusters reviewable in parallel — one cluster per agent.

How to read this

Each cluster doc:

• States the scope (file list + ownership boundary).
• States the intent — what the cluster is solving, what it intentionally is not.
• Lists the key changes with file:line references and the design rationale that would otherwise live in PR descriptions.
• Lists invariants the reviewer should check are preserved.
• Lists validation — which tests cover the change and current status.
• Lists known follow-ups that are out of scope here but tracked.

Cluster index

Cluster	What it covers	Doc
Stream Manager	AiStreamManager, listeners, persistence backends, lifecycle, dispatcher, context providers	stream-manager-cluster.md
Agent Loop	Agent class, hooks composition, single-pass stream, observers, tool-execution events	agent-cluster.md
Params Pipeline	buildAgentParams, RequestFeature set, capability resolution, system-prompt assembly	params-cluster.md
Tool Registry	Registry, built-in tools, MCP sync, meta-tools, defer exposition, tool-call repair	tool-cluster.md
Provider Resolution	provider/config.ts, endpoint.ts, extensions, custom providers (aihubmix, newapi), Claude Code runtime helpers	provider-cluster.md
Messages & Observability	UI part conversion, file processor, OTel span adapter	messages-observability-cluster.md
AiService & IPC	AiService lifecycle wiring, IPC handlers, request-type schemas	ai-service-cluster.md
Renderer Transport	IpcChatTransport, dispatch coordinator, topic-level subscription, awaiting-approval bridge	renderer-transport-cluster.md
Renderer V2 Chat UI	Parts-based rendering, approval cards, branch navigation, execution overlay	renderer-ui-cluster.md
Composer Tool Surface	+ menu, / panel, active chips, assistant/agent tool discoverability and disabled-state rules	composer-tool-surface-design.md
Package Changes	packages/aiCore, packages/provider-registry, shared types	packages-cluster.md
Data Layer	Agent / session / workspace schema rewrite, MessageService, migrators, DataApi handlers, shared types/schemas	data-cluster.md
Agents Core Carve	Renderer agent-session stack onto main (types/agent.ts enriched shape + hooks/agents + pages/agents + v2 utils/export); the history page rides this — measured not an independent page split	agents-core-carve.md

Already-documented sub-features

Three smaller, self-contained sub-features have their own design docs that pre-date this index — these stay where they are and the cluster docs above reference them:

• adapter-family.md — endpoint → @ai-sdk/* routing. (Covered also at Provider Resolution.)
• translate-on-main.md — translate flow, why it's not chat-shape.
• branch-navigation.md — UX for branched DAG history; UX-side, not on the AiService critical path.
• token-estimator-p0.md — backend token estimation behind the input-bar badge.
• large-file-upload-port.md — outstanding port from renderer for Gemini/OpenAI File APIs.
• tool-approval-defer-fix.md — fix design for the defer-exposition approval-gate bypass (review #1).
• tool-approval-state-consolidation.md — diagnosis + target design + phased refactor plan for the approval split-brain (stream / DB / renderer state can't be simultaneously consistent); single-authority (DB parts) model, collapsing the main-side multi-write into one authoritative write (Phase 1 = CR-002, done).
• steer-state-machine-consolidation.md — steer-queue state machine (#15935 fresh-eyes review): delete the lastTerminalKind shadow, drive chaining / enqueue / approve-gate off the single authority (stream.status on the in-grace stream). Blockers 1–3 implemented on codex/main-3 (+ S5 removed for free); blocker 4 (renderer executionId reuse) handed off to the renderer slice.
• channel-ingress-security.md — security model + gaps for externally-triggered (inbound IM) agent runs (review D1).
• stream-ipc-validation.md — scheme to validate the untrusted-renderer AI stream IPC payloads (review D2).
• declarative-tool-registry.md — one declarative registry for Claude Code agent tools (policy + catalog UI + chat rendering): exposure/category/pairGroup, opt-out disabledTools, SDK 0.3.168 upgrade, 7-PR sequence.

Suggested review order

The clusters are not strictly independent — but the listed order roughly matches dependency depth (later clusters consume earlier ones). For solo review, take them in order. For agent-parallel review, assign the first six clusters in any order; renderer clusters last since they consume the Main contract.

Out of scope here

• v1 deletion artefacts (file removals only, no logic) — those are part of the renderer cleanup chain and reviewed at git level.
• Quick assistant / API server lifecycle — separate PRs with their own docs.