creating-ai-subscription

创建提示词订阅

适用场景

订阅会按周期将 PostHog 报告发送到电子邮件、Slack 或 Microsoft Teams。订阅分为三种类型，具体取决于你设置的字段；类型会自动推导，并作为只读字段 resource_type 返回：

• insight — 定期快照一个现有洞察（resource_type: "insight"）
• dashboard — 定期快照某个仪表板的图块（resource_type: "dashboard"）
• prompt — 根据自由文本提示词定期生成AI 报告：大模型会规划并运行 HogQL 查询项目数据，然后在每个周期生成一份全新的 Markdown 报告（resource_type: "ai_prompt"）

当用户希望定期获得关于 X 的 AI 摘要（可以是每天、每周、每月或每年），而不是定期获取某个现有洞察或仪表板的快照，或只获取一次报告时，请使用此技能创建提示词类型订阅。当价值在于_分析本身_（由大模型决定查询内容并撰写报告），而不是用户已经制作好的固定图表时，应选择提示词订阅。对于洞察/仪表板订阅，请设置 insight/dashboard，而非 prompt，且无需满足下述 AI 条件。

优先考虑仪表板或洞察订阅。 提示词订阅的开销最大，而且大模型会自行编写 HogQL，因此其数据可能与已保存的洞察或仪表板有所出入。仅在以下情况下使用：(a) 用户明确要求自由文本/AI 撰写的报告；或 (b) 现有洞察或仪表板无法满足需求，且价值确实在于分析本身。如果用户希望按计划收到现有仪表板或洞察中的关键数据——即使他们说的是“设置一个 scout/bot，每天发布这些内容”——通常也更适合使用设置了 summary_enabled: true 的仪表板（或洞察）订阅。尊重确定要创建提示词订阅的用户；但如果需求不明确，请先提出这一建议并确认。顺利完成操作的流程请参阅 managing-subscriptions。

本技能介绍如何创建订阅。订阅创建后，可使用相同的 subscriptions-* 工具管理其生命周期（见下文）：查看订阅列表、编辑/停用/重新启用订阅、发送测试投递或删除订阅。

工具

工具	用途
posthog:subscriptions-create	创建定期提示词订阅
posthog:subscriptions-list	确认订阅已创建；查看现有订阅
posthog:subscriptions-partial-update	编辑、停用（enabled: false）或重新启用订阅
posthog:subscriptions-test-delivery-create	立即向目标位置发送测试投递
posthog:subscriptions-delete	软删除订阅（停止所有后续投递）
posthog:integrations-list	查找 Slack integration_id（筛选条件为 kind=slack）
posthog:integrations-channels-retrieve	列出 Slack 集成的频道（ID + 名称）

调用前的准备工作

该端点设有三项创建时的门槛，任何一项不满足都会返回 400：

1. PostHog Cloud，或 DEBUG=true — 不符合自托管生产部署的条件（LLM 调用会通过 PostHog 管理的密钥路由）。
2. 组织级“已批准 AI 数据处理” — 必须在 Org settings → Data → AI data processing 中开启。组织必须先选择加入 AI 功能。
3. 为组织启用提示词订阅 — 这是由 PostHog 管理的推出标志。如果未开启，说明该组织尚未获得访问权限；请告知用户联系 PostHog 开通（没有自助开关）。

如果缺少上述任一项，请停止并告知用户需要修正哪一项——再次调用工具无济于事。

除了 subscription:write，你的访问令牌还需要 query:read 范围：提示词订阅会对项目数据运行 LLM 生成的 HogQL，因此后端要求创建、编辑／重新启用、测试投递或删除订阅时具备查询权限。仅有 subscription:write 的令牌会被拒绝并返回 403。

必需参数

prompt: "..."                         # ≤4000 chars; setting this (with no insight/dashboard) makes it a prompt sub → resource_type "ai_prompt"
target_type: "email" | "slack" | "teams"  # the only delivery channels the API accepts
target_value: "..."                   # comma-separated emails, "<channel_id>|<channel_name>", or a Microsoft Teams webhook URL
frequency: "daily" | "weekly" | "monthly" | "yearly"
interval: 1                            # 1 = every tick; 2 = every other tick; etc.
start_date: "2026-09-15T09:30:00Z"   # anchors the recurrence + time-of-day; hour and half-hour slots are supported; need not be in the future
title: "..."                          # display name in the subscriptions list
send_test_now: false                   # set true only after the user approves an immediate delivery

无需传入 resource_type 参数——其类型会根据你设置的字段推导（prompt ⇒ AI 报告），并作为只读的 resource_type 返回。

可选参数

byweekday: ['monday', 'wednesday'] # weekly only — days the rrule fires
bysetpos: 1 # most useful with monthly; requires byweekday — e.g. byweekday:['monday']+bysetpos:-1 = last Monday
count: 10 # limit scheduled recurrence occurrences; manual and immediate deliveries do not count
until_date: '2026-12-31T00:00:00Z' # stop on/before this date
integration_id: 42 # Slack only — required; from integrations-list (see "Slack target")

Slack 目标

target_value 必须为 <channel_id>|<channel_name>（集成返回的格式）。分三步构造：

1. 使用 kind=slack 筛选 posthog:integrations-list → 选择 Slack 集成的 id。
2. 使用该 id 调用 posthog:integrations-channels-retrieve → 选择一个频道；它会返回每个频道的 id 和 name，将二者组合成 <id>|<name>，作为 target_value。
3. 将该集成的 id 作为 integration_id 传入——订阅会绑定到特定的 Slack 集成，避免在其他位置重新连接时意外更改投递路径。

Teams 目标

target_value 必须是你要接收报告的频道的完整 webhook URL。用户将 Workflows 应用添加到该频道，选择收到 webhook 请求时向频道发帖的模板，然后将 URL 粘贴给你。若使用其他模板生成的 URL，保存时不会报错，但报告永远不会到达该频道。无需查找 Teams 集成，因此请省略 integration_id。

URL 必须使用 https。如果 subscriptions-create 拒绝 target_value，说明该 URL 不是 Teams webhook——请用户使用相同模板重新创建，并粘贴完整 URL。之后更新时，请省略 target_value 以保留已保存的 URL，因为 API 读回的 URL 只包含主机名，并会拒绝这个经过遮蔽的值。

创建前

创建前，请列出匹配的订阅。 比较提示词、标题、目标、计划和启用状态。 提示词文本和标题都会参与 search 匹配。

创建操作不是幂等的。 如果创建请求超时或结果不确定，请在重试前列出匹配的订阅。 不要使用经过遮蔽的 Teams webhook 主机名来判断是否存在重复项。

询问用户是否批准立即投递。 除非用户批准，否则将 send_test_now: false。

示例

通过电子邮件发送每周一早间 AI 摘要

prompt: 'Top events week over week, with the biggest drops and any new failure modes called out.'
target_type: email
target_value: [email protected]
frequency: weekly
interval: 1
byweekday: ['monday']
start_date: '2026-09-14T08:00:00Z'
title: 'Weekly product pulse'
send_test_now: false

每天上午 9 点发送 Slack 报告

prompt: "Yesterday's sign-ups, where they came from, and any errors they hit during onboarding."
target_type: slack
target_value: 'C0123456789|growth-updates' # <channel_id>|<channel_name>; only the channel id is used, the name is cosmetic
integration_id: 42
frequency: daily
interval: 1
start_date: '2026-09-15T09:00:00Z'
title: 'Daily onboarding watch'
send_test_now: false

注意事项

• Teams webhook URL 是一项凭证。 任何拥有它的人都可以在频道中发帖，因此 API 始终只返回其主机名。只将它作为 target_value 传入。不要将它回显给用户，也不要将它复制到确认消息、摘要或错误报告中。
• 类型不可变。 类型由设置的关联关系决定，因此无法事后将洞察或仪表板订阅切换为提示词订阅（反之亦然）——向洞察订阅的 PATCH 请求中添加 prompt 会被拒绝。创建时就选对类型。
• 重新启用之前被自动禁用的提示词订阅有两个前提条件，PATCH 请求会检查这两个条件：(1) prompt 有效——它可以是已保存在该行中的提示词，也可以是 PATCH 请求体中的新提示词（因此，当已存储的提示词仍然有效时，单独发送 {"enabled": true} 即可；但如果禁用原因是提示词无效，则必须先提供有效提示词，否则请求会被拒绝）；(2) 原始创建者仍是活跃用户——如果该账号已停用，则该订阅无法重新启用（任何提示词都无济于事；请改为重新创建订阅）。
• next_delivery_date 由服务器根据 rrule 计算。 不要尝试手动设置——它是只读的。首次投递会在未来第一个距离当前时间至少有一小段缓冲时间（目前约为 15 分钟）的 start_date 时刻触发，因此，如果 start_date 只比当前时间晚几秒，就会顺延到下一次触发。
• 临时发送失败会重试；只有永久性失败才会自动禁用。 临时失败（Slack 速率限制、SMTP 短暂故障、网络问题）会导致该次投递失败，并由 Temporal 在本次运行中重试，之后会在下一个计划触发点再次发送——订阅不会因此自动禁用，所以持续发生故障的频道会在每个触发点不断重试，直到你修复问题。只有永久性／结构性原因才会导致自动禁用：Slack 集成断开、频道权限被撤销、提示词无效，或 AI 数据处理授权被撤销。（对于多收件人邮件，只有在_所有_收件人都发送失败时，投递才会失败；部分发送成功仍会继续发送。）在单次投递运行中，渲染后的 Markdown 会被缓存，因此 Temporal 对该次运行的重试不会重新运行 LLM 流水线——但每个新的计划触发点都会生成一份新的报告。

部署完成后

subscriptions-list 会返回新行。确认 resource_type: "ai_prompt"、enabled: true、next_delivery_date 在未来，并且 prompt 与你发送的内容一致。首次计划触发时会运行 planner → HogQL → synthesis 流水线，并将渲染后的 Markdown 发送到你选择的频道。

相关技能

• managing-subscriptions — 洞察和仪表板订阅，包括附加到这些订阅的 AI 摘要
• building-a-dashboard — 当用户需要图表而不是书面报告时，构建仪表板