多框架抽象：CopilotKitCore 与框架绑定层分离

多框架抽象：CopilotKitCore 与框架绑定层分离

学习目标

理解 CopilotKit 的多框架架构：

• CopilotKitCore 的框架无关设计
• React 绑定：Context Provider + Hooks
• Angular 绑定：DI + Signals
• Vue 绑定：Composition API 适配

前置知识

无特定前置知识。

项目实践

CopilotKitCore：框架无关的核心

CopilotKitCore 是纯 TypeScript 类，无框架依赖：

核心功能	API
Agent 管理	addAgent(), registerProxiedAgent(), getAgent()
工具管理	getTool(), runTool()
上下文管理	ContextStore.set(), ContextStore.delete(), ContextStore.getAll()
事件订阅	subscribe(), subscribeToAgentWithOptions()
线程管理	ThreadStoreRegistry.register(), unregister()
运行控制	runAgent(), connectAgent(), stopAgent()
错误处理	onError 回调，CopilotKitCoreErrorCode 枚举

React 绑定层

Provider：<CopilotKit> 组件创建 CopilotKitCore 实例并通过 React Context 共享：

层级结构：
<CopilotKit runtimeUrl="...">     ← 创建 Core 实例
  <CopilotContext.Provider>      ← 通过 Context 共享
    {children}
  </CopilotContext.Provider>
</CopilotKit>

Hooks 桥接：每个 Hook 从 Context 获取 Core 实例，调用 Core API 并管理 React 状态：

Hook	桥接的 Core API	React 状态
useCopilotAction	registerTool() / unregisterTool()	工具调用状态
useCopilotReadable	ContextStore.set() / delete()	—
useAgent	getAgent() + subscribe()	messages, isRunning
useCopilotChat	runAgent() + subscribe()	聊天消息
useFrontendTool	registerTool()	—
useLangGraphInterrupt	监听 Interrupt 事件	interrupt 对象
useCoAgent	Agent 状态同步	Agent 状态 + 渲染桥接

关键设计模式：useRef 保持 handler 引用稳定

问题：useEffect 依赖变化时重新注册工具，但 handler 可能引用旧的闭包
解决：
const handlerRef = useRef(handler);
useEffect(() => { handlerRef.current = handler; }, [handler]);
// 注册时使用稳定引用，执行时通过 ref 调用最新 handler

Angular 绑定层

Angular 使用不同的模式：

概念	React	Angular
依赖注入	Context Provider	inject() + DI Token
状态管理	useState/useReducer	Signals
Agent 存储	内部 Map	AgentStore 服务
生命周期	useEffect	lifecycle hooks

框架绑定层的共性

所有框架绑定层都处理以下问题：

1. 实例生命周期：组件 mount 时创建 Core，unmount 时清理
2. 状态同步：Core 的事件回调 → 框架状态更新 → UI 重新渲染
3. 依赖管理：Hook 的依赖数组 / Angular Signal 的自动追踪
4. 工具注册/注销：组件 mount 注册，unmount 注销

问题与规避

问题	规避策略
多个 Provider 嵌套导致 Core 实例混乱	每个 <CopilotKit> 创建独立 Core；子组件通过最近的 Provider 获取
Hook 依赖数组遗漏导致状态不更新	严格检查 useEffect 依赖项；使用 useRef 避免函数引用变化
Angular Signal 与 RxJS Observable 的桥接	Signal 的 effect() 监听 Observable 事件
框架特定错误泄露到 Core	Core 层只定义通用错误码（CopilotKitCoreErrorCode）；框架层处理框架特定错误

设计取舍

框架无关核心 vs 框架原生

框架无关核心（CopilotKit 的选择）：

• 优势：核心逻辑只维护一份；新框架只需实现绑定层
• 代价：核心 API 需要足够通用，可能不够贴合某个框架的最佳实践

框架原生（如仅支持 React）：

• 优势：可以深度利用框架特性（React 的 Concurrent Features、Angular 的 DI）
• 代价：每个框架独立实现，维护成本高

Context Provider vs 全局单例

Context Provider（React 的选择）：

• 优势：支持多实例（同一页面多个独立聊天）
• 代价：需要 Provider 包裹

全局单例：

• 优势：随处可用，无需 Provider
• 代价：只能有一个实例，难以隔离

参考来源

• packages/core/src/core/core.ts（CopilotKitCore）
• packages/react-core/src/context/copilot-context.tsx（React Context）
• packages/angular/（Angular 绑定）