CopilotKit：AI 改了待办，页面上的清单也能跟着更新

在应用旁边加一个聊天框，用户可能还要把 AI 的建议逐条复制回原页面。CopilotKit 提供另一种接法：让智能体和应用共用一份状态。AI 添加待办后，清单组件读取这份状态并更新；用户在界面改了设置，智能体也能读取变化。它适合希望 AI 真正参与已有工作界面的产品团队与开发者。

当前项目包含聊天交互、共享状态、生成式界面和用户参与的工具流程。下面沿官方内置智能体示例说明。认识它可以先从一个小问题开始：如果 AI 说“我已经加好了”，用户能否在原来的清单里找到那一项？这比聊天回复是否流畅，更能看清应用整合做到了哪一步。

官方待办示例里，变化落在同一份数据上

当前共享状态文档给出一个协作待办例子。列表组件从 agent.state.todos 读取条目，聊天框与它放在同一页面。官方用“添加一条购买食品的任务”解释：智能体更新共享状态，清单便重新渲染相应条目。

值得留意的是，列表不是从聊天气泡中抽取文字。页面读取结构化的待办数据，任务文字与完成状态各有位置。随后给任务加上划线样式，也是依据完成字段处理。这个分工让应用能够继续提供原来的按钮、筛选和显示方式，而不必要求用户始终待在对话里。

猫目编辑依据官方 v2 内置智能体示例绘制，双向箭头表示应用与智能体对共享状态的读写。它不是待办应用的运行画面，状态更新也不自动等于数据库已经保存。打开清晰原图。

沿这条关系，可以理解一个中文教学情境：准备周末读书会，请 AI“加上借投影仪、确认到场人数两项待办”。应用若接好了共享状态，结果应该是清单中出现两条可继续操作的记录。用户再把“借投影仪”标为完成，之后询问尚未完成的工作时，智能体需要读取更新后的状态，而不是沿用先前那段对话中的旧清单。

这里的判读重点很具体：是否真有两条记录，完成状态是否仍能被原界面修改，后续回答是否读取了最新内容。它解释的是应怎样理解这套交互，不是本文运行该中文任务后的成绩报告。

界面读得见，智能体也要知道哪些能改

文档中的另一个例子，是用户点击深色或浅色按钮，通过 agent.setState 更新偏好。状态流动因此有两个方向：智能体的变化进入界面，用户在界面的选择也成为后续上下文。

但页面信息并非都应交给智能体修改。当前状态指南区分了共享状态与只读上下文：当前用户、选中记录或页面位置等由界面拥有的信息，可以采用只读上下文提供给智能体。开发者需要先决定数据的职责，再决定同步方式。

这会影响一项功能的产品边界。任务草稿允许 AI 提议和修改；用户身份、访问权限或系统计算出的事实，则不能因为放进了聊天上下文就任其改写。共享状态解决数据衔接，权限与持久化仍需要应用自身实现。页面实时变化，也不自动证明内容已经写入数据库。

需要用户拍板时，可以让流程停下来等答复

CopilotKit 的用户参与工具文档说明，useHumanInTheLoop 会注册一个交互工具，让智能体暂停，等待用户通过自定义界面回应。渲染函数可以得到当前状态和回应回调；用户作出选择后，工具才把结果交回流程。

官方还用选时间的卡片解释这种交互：用户看见可选时段并选择，系统再继续处理。它提供的是一处真正的交接点。用于应用时，应把会影响决定的信息放进卡片，例如对象、数量或时间，而不只给一个缺少上下文的确认按钮。

把它接到读书会教学情境中，可以让 AI 先拟出安排，邀请用户选择时段，然后再继续后续任务。发送通知或写入日历仍要有相应业务接口和权限，不能因为界面出现了确认卡就宣称整件事已经完成。

它适合已经有页面和数据的应用

如果需求只是打开一个聊天窗口，现成产品往往更快。CopilotKit 更适合这样的阶段：应用已有清单、表单或画布，希望 AI 能读取相关状态、提出修改，并让用户继续用熟悉的控件参与。

可以从当前快速入门开始，先接一个待办列表或设置项，再扩展到更多业务动作。本文依据 v2 文档介绍，其中使用 @copilotkit/react-core/v2；旧文常见的 useCoAgent、useCopilotAction 等写法应先核对对应版本，不能直接与当前示例拼接。

开源仓库采用 MIT 许可，模型调用、托管与另外提供的商业服务仍有各自条件。选它时，最有价值的检验是让一个动作真正回到原页面：用户能看见变化、改得回去，智能体也能据此继续工作。