用途：让 PostHog 画布正确获取并展示数据。画布只能通过平台提供的 @posthog/canvas-sdk 中的 ph 对象与 PostHog 通信，也可用 window.ph 全局对象，新代码建议用 import。不要初始化它，凭证留在宿主；沙箱内 fetch、posthog-js 或自建客户端都无法访问 PostHog。外部请求需在 capabilities.network.origins 声明非 PostHog 来源，且仅在已发布画布生效，编辑预览会阻止直接网络访问。
数据层级：优先用 PostHog MCP 洞察工具创建并保存洞察，确认数字后记下 short_id，再用 await ph.loadInsight(shortId, { dateRange }) 渲染，数字与 PostHog UI 一致。其次用类型化节点 ph.query({ kind: "TrendsQuery", ... })。最后才用内联 HogQL ph.query("SELECT …")。Web 分析看板应使用 web-analytics 查询类型。发布前须在 capabilities 中声明所用洞察、捕获事件和 inlineQueries。
可验证性：洞察支撑的指标应提供“View in PostHog”链接，用 ph.openExternal(insightUrl) 打开，URL 由 generate-app-url 生成；临时查询需就地展示实际执行的查询。
结果形状：Trends 类结果 results 是序列对象数组，含 data、days、labels、count、aggregated_value、compare_label；SQL 结果为 { columns, results }。
加载策略：独立查询并发发起，每个查询各自维护 { loading, error, data } 状态，渐进渲染；错误与空结果要区分。日期窗口直接传入 dateRange，窗口变化时重跑查询。
其他能力：ph.state 提供按画布的用户级或共享键值存储，需声明 scope；ph.actions.invoke 以查看者身份写入 PostHog，须绑定用户手势并声明 verb；ph.connectors.call 用查看者自己的连接读取第三方数据，仅限只读工具。
限制：未声明的调用在运行时被拒绝；状态每 scope 最多 256 键、单值 64 KB；system.tasks 不含私有、个人、未归档和内部任务，channel_id 不可查询，无法按当前空间或当前用户过滤；画布源码对所有查看者可见，不应写入密钥或 PII。