installing-posthog-from-chat

在聊天中安装 PostHog

Wizard 是 PostHog 的设置 Agent。使用 wizard-install-start 后，它会在 GitHub 仓库的云工作区中运行、修改代码并创建拉取请求。用户审核并合并该拉取请求。在用户完成这些操作之前，默认分支不会发生任何变化。

按顺序完成以下步骤。如果对话中已知某个步骤的结果，则跳过该步骤。

1. 连接 GitHub

运行会使用项目的 GitHub 连接，因此项目需要先连接 GitHub。

1. 调用 integrations-list，查找 kind 为 github 的集成。
2. 如果没有此类集成，请根据上下文中的基本 URL 和项目 ID 为用户提供以下链接：<base URL>/integrations/connect/github/?project_id=<project id>&connect_from=mcp。用户安装 PostHog GitHub App 并选择它可以访问的仓库。等待用户表示已完成，然后再次调用 integrations-list。

2. 选择仓库

使用 GitHub 集成的 ID 调用 integrations-github-repos-retrieve。如果用户指定了仓库名称，则使用 search；当 has_more 为 true 时，使用 offset 翻页。

• 只有一个明确匹配项：用一行文字向用户确认。
• 有多个匹配项：列出这些仓库，并询问用户选择哪一个。
• 没有匹配项：GitHub App 无法访问该仓库。请用户在 GitHub 中将该仓库添加到应用的仓库访问权限中，然后重新搜索。

将仓库作为 full_name（owner/name）传入。

设置 Agent 会在仓库根目录中运行。如果用户说明应用位于单体仓库的子目录中，请告知他们运行可能无法找到该应用，并询问是否仍要尝试。

3. 启动运行

调用 wizard-install-start，并传入：

• repository：第 2 步中的 owner/name。
• branch：仅当用户希望使用非默认分支时传入。拉取请求将以该分支为目标。
• idempotency_key：为此请求生成一个全新的唯一值。如果网络错误后重试，请复用相同的值，以便重试返回同一次运行。

用户可以采取行动的错误：

错误代码	操作
github_not_connected	返回第 1 步。
repository_not_accessible	请用户将该仓库添加到 PostHog GitHub App，然后使用新的 idempotency_key 重试。
run_already_active	用户在此项目中已有正在运行的任务。请用户等待任务完成，或在 PostHog 中查看任务。
HTTP 429	用户已达到设置运行的每小时或每日限额。转告用户相关消息。不要立即重试。

告知用户运行已启动，并分享响应中的 url，供用户在 PostHog 中查看运行进度。

4. 轮询运行状态

当 status 为 created 或 running 时，大约每 30 秒使用 run_id 调用 wizard-install-status。运行通常需要几分钟。

• next_step 发生变化时，将其转告用户。该内容可直接转发。
• 如有帮助，可告知用户 tasks 中的进度，但不要在每次轮询后都发送更新。
• 当 status 为 completed、failed 或 cancelled 时，停止轮询。

如果客户端无法在一次对话中等待这么久，请告知用户运行仍在进行，并在用户回来时再次检查。

5. 分享结果

• completed 且包含 pull_request_url：分享链接。告知用户应审核更改并合并拉取请求，以完成 PostHog 设置。
• completed 但不包含 pull_request_url：设置 Agent 未进行任何更改，通常是因为 PostHog 已经设置完毕。转告用户 next_step。
• failed：转告用户 next_step 和 error_message。如果 next_step 建议重新运行，则提出启动新运行。