integrating-with-posthog-ai

将产品与 PostHog AI 集成

面向用户的文档是 products/posthog_ai/README.md。本技能讲的是如何 做 这件事：选对接缝，避开两个关键错误，并在深入之前停下来。

首先：这到底是不是前端工作？

这里没有后端集成 API。一个集成有两半，前端那半依赖后端那半：

1. 能力 — Agent 通过 MCP 工具读写你的实体。如果没有工具能解析你想谈论的东西，就从那里开始：/implementing-mcp-tools、products/<name>/mcp/tools.yaml。
2. 协作 — 下面这些前端接缝。

注入的上下文携带的是_引用_，不是数据。Agent 无法用工具解析的引用是死路一条，所以在注入引用之前先确认工具存在。

选择接缝

任务	接缝	从何处导入	是否使用？	参考
Agent 应知道用户正在看什么，包括未保存的工作	附加上下文	api/logics	推荐	injecting-context.md
引导 Agent 在此处的行为 — 优先使用哪些工具、本页上"this"指什么，或交给它一个技能	受信任指令	api/logics	推荐	injecting-instructions.md
当 Agent 做某事时页面应更新	工具事件总线	api/logics	推荐	reacting-to-tool-calls.md
你的工具的调用应渲染为真正的卡片，而不是通用回退	工具注册表	api/tools	推荐	rendering-widgets.md
用线程、输入框和流式原语构建你自己的 Agent UI	运行原语	api/runSurface、api/primitives	不推荐 — 见下文	products/posthog_ai/frontend/README.md

前四个是产品集成。第五个是为_托管_ Agent 运行的那三个界面而存在的 — Max 场景、signals 收件箱和 tasks 运行器 — 而不是为想要与之协作的产品而存在。默认就想用它，是这件事出错的主要方式。

一次性处理整个场景：来自 frontend/src/scenes/max/useSceneAgentPanel.ts 的 useSceneAgentPanel({ sceneKey, contextItems, headlines }) 打包了上下文、欢迎标题和侧边栏的受控自动打开。为一个场景就从这里开始；为一个组件则下探到各个单独的 hook。products/workflows/frontend/Workflows/WorkflowScene.tsx 是范例。

导入规则

始终是域范围的 api/<module> 入口，绝不用深层路径，并且刻意没有根 barrel：

import { useAttachedContext, useMcpToolApplyBack } from 'products/posthog_ai/frontend/api/logics'

选择最窄的模块。api/logics 和 api/types 是无头的；api/primitives 会拖入 markdown 和虚拟化；api/tools 在模块加载时从内置组件和中央清单初始化注册表，所以导入它是一个不会被 tree-shaking 的副作用。一个导入了错误层级的 status 徽章会让它的 chunk 翻倍。

两个真正重要的问题

1. 把可变数据放进可信上下文。 type: 'instructions' 项会落入 <posthog_trusted_context> —— 这是 Agent 会遵循的指引。其他所有内容都会落入 <posthog_untrusted_context>，并置于强化说明之后。因此：

• 指令中只能包含你自己构建期的字符串。绝不要包含用户输入的姓名、摄入的值，或任何由此插值而来的内容。可信上下文中一个精心构造的实体名称，就是对下一个读取该会话的人发起的提示词注入。
• 不可信上下文才是用户数据该待的地方，自由地注入这些数据正是其意义所在 —— 用户未保存的编辑器状态通常是你手头最有用的东西。
• 如果某个指针必须变化（哪个 id 处于打开状态、选中了哪一步），就把它放在不可信项上，并让静态指令通过字段名来引用它。

2. 发送对象结构而不是标识符。 上下文块会附在对话中的每一条消息上。发送 { type, key, label }，让 Agent 通过你的 MCP 工具去获取详情。例外是 Agent 无法获取的未保存状态 —— 要为其设定预算（workflowAgentContext.ts 上限为 64k 字符，并且是省略而非截断），并遮盖敏感信息，这些信息在活动表单状态中以明文存在，尽管已保存的敏感信息从不会到达前端。

止步于接缝 4

运行原语是公开的 —— RunSurface、ReadonlyRunSurface、EmbeddedRunner、Thread 原子、runStreamLogic —— 但在它们之上构建自定义 Agent UI 并不是产品集成。这意味着你要自己负责流绑定、输入框和队列状态、权限路由，以及决定打包体积的 eager-vs-lazy 层级选择。没有默认布局。

如果这确实是你要做的任务，请先阅读 products/posthog_ai/frontend/README.md 和 AGENTS.md，并复制两个参考实现之一（signals 收件箱详情视图，或 scenes/TaskTracker/components/TaskRunChat.tsx），而不是从零开始组合。

不要触碰

• LangGraph 运行时已冻结。 不要新增 useMaxTool 注册、不要新增 MaxUIContext 字段、不要在各 scene logic 上新增 maxContext 选择器。改用附加上下文和工具事件总线。
• 耦合闸门。 products/posthog_ai/frontend 下的任何内容都不得导入 scenes/max、maxThreadLogic、maxContextLogic 或 conversations API。Max 是该表面的消费者，而不是它的依赖项。如果该表面缺少你需要的东西，就把它提升为该处的通用 prop 或选择器 —— 绝不要在其中为某个消费者做特例处理。

验证

• 用 pnpm --filter=@posthog/frontend typescript:check 检查类型。
• 运行应用，并在你的页面上打开侧边面板。上下文在设计上是不可见的，所以要检查它是否已落地：一个已附加且未标记为 hidden 的项会显示为输入框上下文栏中的一个 chip，并且 Agent 应该能够在你未告知其 id 的情况下回答关于你所附加内容的问题。
• 对于响应式接缝，让 Agent 进行更改并确认打开的页面会更新。然后重新加载页面 —— 你的处理器绝不能再次触发，因为重放事件默认会被抑制。