在终端用 assistant-ui Ink 构建聊天 UI…

当需要用 @assistant-ui/react-ink 在终端中搭建聊天界面，并处理 Ink 输入、ANSI Markdown、后端 URL、本地/远端线程存储与终端键盘导航时使用。

适用场景

解决思路

1. 始终查阅 https://www.assistant-ui.com/llms.txt 获取最新 API。
2. 理解 @assistant-ui/react-ink 将 assistant-ui runtime 连接到 Ink 终端渲染器；它与 Web 应用共享 runtime、tools、state 和 AI SDK transport，但没有 DOM、CSS 或 copied elements；屏幕用 Ink 的 Box 和 Text 加上 runtime aware primitives 组合。
3. 查阅 ./references/primitives.md，了解每个终端 primitive namespace、其 parts、scoped contexts 以及受控 TextInput。
4. 查阅 ./references/hooks.md，了解 runtime、state、tool、notification、voice 和 checklist hooks。
5. 查阅 ./references/adapters.md，了解 file storage、attachment 和 title adapters。
6. 查阅 ./references/custom-backend.md，了解 local inference、local disk persistence 和 backend thread ownership。
7. 查阅 ./references/migration.md，了解 Web app 哪些内容可迁移到 Ink、哪些必须重建。
8. 从零创建终端应用：运行 npx assistant-ui@latest create --ink my-app，然后 cd my-app；--ink 对应 with-react-ink CLI 示例，示例库中还有 with-react-ink-web，但它不是 --ink 脚手架目标。
9. 在已有 Node 项目中一起安装 runtime、终端渲染器和 AI SDK transport：npm install @assistant-ui/react-ink @assistant-ui/react-ink-markdown ink react @assistant-ui/ai-sdk。
10. API 路由必须在单独的后端项目中运行；终端进程不能使用相对 /api/chat URL；给 AssistantChatTransport 一个进程可访问的完整 URL，例如 http://localhost:3000/api/chat。
11. 在 App 中：用 useChatRuntime 创建 runtime，transport 使用 new AssistantChatTransport({ api: CHAT_API_URL })；用 AssistantRuntimeProvider runtime={runtime} 包裹；在 Ink 的 Box flexDirection="column" 内放 TerminalThread。
12. 从 @assistant-ui/ai-sdk 导入 useChatRuntime 和 AssistantChatTransport；其后端使用 AI SDK v7 UI message stream；参考 runtime 的 AI SDK v7 guide 了解 route shape。
13. 组合终端线程时：ThreadPrimitive.Messages 会在每个子组件运行前创建当前消息 scope；在消息组件内读取 s.message；使用 Ink primitives 而不是 Web elements；用 AuiIf 做 runtime state gates；用 LoadingPrimitive 表示 active run。
14. 渲染消息示例：用 useAuiState((s) => s.message) 获取 message；从 content 过滤 text parts 并 join 文本；user role 用 Text color="green" 渲染 'You: {text}'；assistant 用 Box flexDirection="column" marginBottom={1}、Text color="blue" 和 MarkdownText 渲染。
15. 渲染 TerminalThread 示例：使用 ThreadPrimitive.Root flexDirection="column"；用 AuiIf condition={(s) => s.thread.isEmpty} 显示 'Send a message to begin.'；用 ThreadPrimitive.Messages 渲染 Message；在 LoadingPrimitive.Root gap={1} 内放 LoadingPrimitive.Spinner variant="bar"、LoadingPrimitive.Text、LoadingPrimitive.ElapsedTime；用 Box borderStyle="round" borderColor="gray" paddingX={1} 包裹 Text "> " 和 ComposerPrimitive.Input submitOnEnter placeholder="Message..." autoFocus。
16. 简单消息示例只渲染 text parts；当需要 tool calls、attachments、data、sources 或 reasoning 时使用 MessagePrimitive.Parts；其默认 terminal safe renderers 处理这些 part types，查 primitives 了解组件映射。
17. 使用 ComposerPrimitive.Input 作为 composer bound TextInput；它是受控行编辑器，不是 Ink 原生输入（Ink 没有原生 input）。submitOnEnter 发送当前 composer 文本；启用 multiLine 时，Enter 插入换行，除非启用 submitOnEnter；若启用 submitOnEnter 且终端能区分 Shift Enter，则 Shift Enter 插入换行；Ctrl J 仅在 multiline 模式插入换行，且绝不提交 single line input。
18. Left、Right、Backspace、Delete 和 Ctrl D 按一个 grapheme 操作，确保 emoji、ZWJ sequence、combining character 或 CJK ideograph 不被拆分。
19. Home 和 End 在 single line 模式选择整个 buffer，在 multiline 模式选择当前行；Ctrl A 和 Ctrl E 总是选择当前行边界。
20. Up 和 Down 导航 multiline rows，同时保留终端 display column；该列按 grapheme widths 计算，而不是 UTF-16 offsets。
21. Ctrl W、Alt B、Alt F 和 Alt D 按 Intl.Segmenter word boundaries 导航或删除；Ctrl U 和 Ctrl K 删除到当前 boundary；在 multiline end of line，Ctrl K 连接下一行。
22. Meta bindings 需要终端发出 Escape prefixed sequences；在 macOS Terminal 中为 Alt bindings 启用 “Use Option as Meta key”；Shift Enter 需要 CSI u 支持，包括 iTerm2 3.4 或更新版本、kitty 和 foot；其他终端将其视为 Enter 并使用 submitOnEnter 行为；查 primitives 了解 composer 之外的 TextInput。
23. 终端 Markdown：将累积文本传给 @assistant-ui/react-ink-markdown 的 MarkdownText；它产生 terminal styled output，而不是 HTML 或 React DOM tree。
24. @assistant-ui/react-ink-markdown 还导出 MarkdownTextPrimitive、useShikiHighlighter 和 theme types 用于自定义 renderer；除非需要改变渲染管线，否则从 MarkdownText 开始。
25. 修复 gotcha：终端应用向自身进程请求而不是后端时，给 AssistantChatTransport 绝对 api URL，例如 http://localhost:3000/api/chat；将 AI SDK route 与 Ink 进程分开托管。
26. 修复 gotcha：Web Thread 或 shadcn element 在 CLI 中渲染为空时，浏览器元素需要 DOM 和 CSS；用 Ink 的 Box、Text 和 @assistant-ui/react-ink primitives 重建 surface。
27. 修复 gotcha：primitive 或 state hook 抛出 missing runtime context 时，将其挂载在 AssistantRuntimeProvider runtime={runtime} 下；ThreadPrimitive.Messages 和 MessagePrimitive.Parts 也会创建其子组件读取的 item scopes。
28. 修复 gotcha：Enter 不发送或意外插入换行时，注意 submitOnEnter 默认 false；仅当 Enter 应发送且 Shift Enter 应在支持的终端插入换行时，才与 multiLine 组合使用。
29. 修复 gotcha：删除 emoji 破坏可见输入或垂直导航落错位置时，使用 ComposerPrimitive.Input 或导出的 TextInput；它们的 buffer 使用 grapheme segmentation 和 terminal display widths；不要用 character index arithmetic 替代。
30. 修复 gotcha：重启 CLI 后 thread 数据消失时，注意 useLocalRuntime 是进程内存；单个本地进程用 createFileStorageAdapter，后端拥有 metadata 用 RemoteThreadListAdapter。
31. 修复 gotcha：Markdown 从 Web package 导入时，从 @assistant-ui/react-ink-markdown 导入 MarkdownText，它发出 terminal formatting；Web markdown renderers 面向 DOM。

适用边界 · 注意事项

• 不要用于浏览器应用设置、web elements 或标准 web runtime；这些场景用 setup skill。
• 不要用于非终端目标或需要浏览器 unstyled primitives 的场景；这些场景用 primitives skill。
• 不要直接移植需要 DOM/CSS 的 Web Thread、shadcn 元素或 Web markdown renderer；它们在 CLI 中不会渲染，必须用 Ink 重建。