assistant-ui…

在 assistant-ui 聊天应用中添加可管理多个对话的 ThreadList/ThreadListSidebar，并接入云端、后端适配器或外部存储的线程状态与事件。

适用场景

解决思路

1. 始终查阅 https://www.assistant-ui.com/llms.txt 获取最新 API。
2. 默认 runtime 只有一个内存对话；仅在用户需要创建、选择和管理多个对话时添加 thread list。
3. 选择 UI 前先决定多会话路径：managed cloud、backend adapter 或 external store。
4. 查阅 ./references/management.md，了解 CRUD、初始化、刷新、分页、metadata 和 identifiers。
5. 查阅 ./references/custom-ui.md，了解所有 thread list primitive、自定义布局、搜索、分组和安装元素组合。
6. 查阅 ./references/remote-adapter.md，了解 remote adapter contract、history adapter、store entries、authentication reload 和 external stores。
7. 用 npx assistant-ui@latest add thread-list 安装 runtime connected list，并生成 components/assistant-ui/elements/thread-list.aui.tsx。
8. 用 AssistantCloud 构造实例，传入 baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL 和 anonymous: true，再把 cloud 传给 useChatRuntime({ cloud }) 以获得 managed threads。
9. 在 AssistantRuntimeProvider 下渲染列表和 active thread，例如 aside 中放 ThreadList，main 中放 Thread。
10. 项目已使用 shadcn sidebar primitives 时，用 ThreadListSidebar 作为完整 sidebar shell；它自身渲染 runtime connected thread list，所以不要再在其中挂载 ThreadList。
11. ThreadListSidebar 仍需要 AssistantRuntimeProvider 祖先；其 SidebarProvider 是独立布局上下文。
12. 用 useAui() 执行线程命令；作用域访问器是属性，使用 aui.threads 和 aui.threadListItem，绝不要写成 aui.threads()。
13. 用 useAuiState 分别读取每个 state 值；selector 可以返回一个原始值或稳定 runtime reference，绝不能返回对象或数组字面量。
14. 读取列表状态时分别取 s.threads.mainThreadId、s.threads.threadIds、s.threads.isLoading 等值。
15. 通过 aui.threads.item({ id: threadId }) 获取单个线程条目，并调用 item.switchTo() 打开、item.rename("Project planning") 重命名、item.archive() 归档、item.delete() 删除。
16. 用 aui.threads.switchToNewThread() 创建新对话。
17. 在 thread item primitive 内，s.threadListItem 是作用域中的 item；行只需一个值时单独选择字段，例如 s.threadListItem.isRunning，不要选整个 state object。
18. 当安装元素的日期分组、搜索或视觉处理不符合产品时，从 ThreadListPrimitive、ThreadListItemPrimitive、ThreadListItemMorePrimitive 三个 primitive 命名空间组合自定义列表。
19. 用 ThreadListPrimitive.Items 提供当前 item scope；其 children render function 替代已弃用的 components prop。
20. 自定义列表组合：ThreadListPrimitive.Root 内放 New 和 Items；每个 item 用 ThreadListItemPrimitive.Root data-thread-id、Trigger、Title fallback；ThreadListItemMorePrimitive.Root 使用 sharedFocusGroup、Trigger、Content；Archive 和 Delete 用 asChild 包装到 MorePrimitive.Item，并用 Separator 分隔。
21. 查看 custom UI 参考以了解 archived rows、load more、custom search、grouping、keyboard behavior 和完整 part reference。
22. 多会话路径选择 AssistantCloud：需要 managed authentication、persistence、synchronization 和 titles，线程 metadata 存在 assistant-cloud。
23. 多会话路径选择 useRemoteThreadListRuntime 加 RemoteThreadListAdapter：LocalRuntime based runtime 使用应用数据库，线程 metadata 存在你的后端。
24. 多会话路径选择 ExternalStoreThreadListAdapter：ExternalStoreRuntime 已拥有 messages 和 selection，线程 metadata 存在你的 state store。
25. cloud quick start 是 managed path；remote 和 external store paths 有不同 ownership 和 lifecycle 要求，遵循 remote adapter 参考，不要混用它们的 API。
26. 用 threads.selectionChanged 观察选择变化；它替代旧的 per item switch events，每次 selection change 都运行并同时提供两个 ID，但 mount 初始选择不运行。
27. 用 useAuiEvent 订阅 threads.selectionChanged 事件，回调接收 threadId 和 previousThreadId，并调用 recordThreadSelection。
28. 当监听器位于 item row 内且只应响应本行成为 current 时，比较 threadId 与 s.threadListItem.id。
29. 修复列表渲染但不持久化：默认 runtime 是单个内存 thread；传入 cloud，使用 RemoteThreadListAdapter，或提供 ExternalStoreThreadListAdapter。
30. remote adapter 只管理 metadata；为每条对话消息添加 history adapter 或其他 message persistence layer。
31. 修复线程切换使用 stale messages：在 RemoteThreadList store entry 上，用 withKey(id, ...) 包装 thread factory，为选中 ID 挂载 history adapter。
32. 仅在 runs 应在 selection changes 后继续且可以接受将 visited threads 保留在内存中时，使用 backgroundThreads。
33. 修复侧边栏没有 runtime：ThreadList 和 ThreadListSidebar 需要 AssistantRuntimeProvider 祖先；ThreadListSidebar 还需要 shadcn SidebarProvider，因为它是 sidebar shell，不是 runtime provider。
34. 修复行因无关 store change 重渲染：用单独的 useAuiState 调用替换返回对象或数组字面量的 selector；直接返回 s.threads.threadIds 是安全的，因为它是 runtime supplied stable reference。
35. 修复升级后 switch handler 停止触发：订阅 threads.selectionChanged 并使用 previousThreadId；已退役的 threadListItem.switchedTo 和 switchedAway 事件不是当前集成点。
36. 相关技能：runtime 用于选择和配置拥有 active conversation 的 runtime；cloud 用于配置 AssistantCloud authentication、persistence 和 managed threads；elements 用于安装、样式化和定制 runtime connected registry components。

适用边界 · 注意事项

• 只需要一个内存中的对话、不需要创建、选择或管理多个会话时，不要添加 thread list。
• 没有 assistant-ui runtime/provider，或不想使用 assistant-ui 的 primitive 与适配器体系时，不适用。
• 使用 ThreadListSidebar 但不能提供 AssistantRuntimeProvider 祖先或 shadcn SidebarProvider 布局上下文时，不适用。