在 Flows/Fusion 应用中集成…

当需要给 Flows/Fusion 应用添加 AI、Agent、聊天 UI 或 LLM 功能时，通过 @cognite/app-sdk 接入平台 Atlas 侧边栏。

适用场景

解决思路

1. 默认走平台 Atlas 侧边栏（EOS / Fusion PAIA），通过 @cognite/app-sdk 接入；不要内嵌 useAtlasChat、不要 vendor atlas-agent、不要调用第三方 LLM API。
2. 仅当用户明确要求应用内聊天且 connectToHostApp 无法提供侧边栏（独立应用，总是 reject）时，才使用 integrate-atlas-chat；没有对应的 manifest 字段。
3. 只实现所需能力：Open（顶栏 Atlas 按钮；应用内触发用 sendAgentLayoutMode）、Message（用 sendAgentMessage 注入上下文）、Server（resources 表示应用状态，actions 表示工具）。
4. Step 0：读取 package.json（确认包管理器、@cognite/app-sdk）和 src/App.tsx（结构、现有 SDK 用法），并询问需要三种能力中的哪些；除非用户已坚持，否则不要主动提供应用内聊天。
5. Step 1：安装 @cognite/app-sdk（pnpm add / npm / yarn），最低版本 0.3.1。
6. Step 2：用 connectToHostApp 连接宿主；它在 Fusion 之外（独立 vite dev）会 reject，需捕获该错误，并在 api 为 null 时隐藏 agent 触发入口。
7. Step 2：Comlink 代理是可调用的，setApi(proxy) 会让 React 把代理当作 updater 并存入 Promise；必须写成 setApi(() => resolvedApi)。
8. Step 2：在根组件调用 useHostApp，把 api 向下传递或用 context 传递；不要用 typeof proxy.method === 'function' 做特性检测（永远为 true），要用 try/catch。
9. Step 3：主启动入口是 Aura Topbar Atlas（systemActions.atlas.visible: true，见 use-topbar），不要再加第二个 “Open Assistant” 控件。
10. Step 3：sendAgentLayoutMode 仅用于上下文触发（sidebar | fullscreen | closed），例如 await api.sendAgentLayoutMode({ mode: 'sidebar' })。
11. Step 4：发送消息时与 sendAgentLayoutMode 配对；从某个条目发起新任务用 newSession: true，继续线程则省略；把名称/ID/状态放进消息里，一次侧边栏回合完成，而不是对查询行做 N 次补全。
12. Step 5：Agent server 在 mount 时注册、unmount 时注销；工厂函数以 services 作为参数，便于不依赖 React 做单元测试；目录结构为 src/features/agent/ 下的 agentActions.ts（(deps) => Action[]）、agentResources.ts（(deps) => Resource[]）、useAgentServer.ts（register / unregister）。
13. Step 5：Resource 的 read() 返回 { type: 'json', data }（首选）或 { type: 'text', text }；description 要像 docstring 一样写清楚。
14. Step 5：Action 名称用 snake_case，参数用 Zod，每个字段加 .describe()；agent 调用前不会确认，所以变更类 action 必须在 description 中说明，并要求用户事先批准。
15. Step 5：用 createAgentServer 创建 server（uri 如 'my-app'，Fusion 会加实例 ID 命名空间），registerAgentServer 和 unregisterAgentServer 都要 .catch() 处理错误。
16. Step 6：在 App 中组合 useHostApp 与 useAgentServer，并在触发时先 sendAgentLayoutMode({ mode: 'sidebar' }) 再 sendAgentMessage({ message, newSession: true })。
17. Step 6：直接测试工厂函数，例如用 vi.fn() mock service 后调用 action.handler 并断言 result.content[0].data。
18. 硬性门槛：不要对 DMS/SDK 查询结果逐行做 chat completions（Atlas agents/chat、OpenAI/Anthropic、useAtlasChat().send）；优先一次 sendAgentMessage 或让侧边栏 agent 读取 resource。
19. 若逐条补全是明确的产品需求（默认否），遵守：默认每次用户发起动作最多 5 次补全；上限 50，绝不生成可能超过该值的代码；缓存键 space:externalId:lastUpdatedTime，命中不消耗预算；批量用一个 prompt 覆盖 N 个条目而非 N 次调用；仅用户主动触发，绝不在 render、轮询或无界列表上触发；被上限截断时要在 UX 中说明。
20. 禁止写法：items.map((row) => complete(row))、对查询页做 Promise.all 的补全。
21. 检查清单：顶栏 Atlas 启动器（use-topbar），无应用内聊天控件；@cognite/app-sdk@0.3.1+；setApi(() => resolvedApi)；捕获 Fusion 外 reject；api 为 null 时隐藏触发入口；server 注册/注销带 .catch()；resource description 说明是什么/何时用；action 名 snake_case；变更类 action 需事先批准；工厂函数以 services 为参数；若存在逐行 LLM 调用则限制在 5/最多 50 并缓存。

适用边界 · 注意事项

• 不要内嵌 useAtlasChat、vendor atlas-agent 或调用第三方 LLM API，除非用户明确要求应用内聊天且 connectToHostApp 无法提供侧边栏。
• 不要在 Fusion 之外（独立 vite dev）假设 connectToHostApp 可用，它会 reject。
• 不要对查询结果逐行做 chat completions（如 items.map((row) => complete(row)) 或对查询页做 Promise.all），除非是明确的产品需求并遵守 5/50 上限与缓存规则。