使用 PostHog MCP Dashboard Widgets 工具集管理看板瓦片：原子化批量操作与源码级原理解析

导读

Dashboard（看板）是 PostHog 中最常用的指标聚合载体，而看板上的 widget 瓦片（如"最新事件""Top Issues""最近录制"等动态列表）正在取代部分传统 insight 图表。本文基于 PostHog 仓库中 manage-dashboard-widgets 技能文档 及其配套的 MCP 工具定义（products/dashboards/mcp/tools.yaml）与后端实现（products/dashboards/backend/api/dashboard.py），系统讲解 Agent 如何通过 6 个原子化 MCP 工具完成 widget 瓦片的发现、添加、更新、查询、复制与移动，并剖析其底层 REST 端点、权限模型与发布流程。读完本文，你将掌握一套可直接用于 Agent 对话或脚本调用的完整看板瓦片操作工作流。

一、设计哲学：为什么是"原子化 MCP 工具"而不是 REST 直调

PostHog 的 Agent（包括 Slack、桌面端与 MCP 客户端中的 AI）通过一组原子化（atomic）MCP 工具管理看板瓦片，而不是直接拼接 REST 调用。这种设计的核心原因有两个：

1. 避免上下文爆炸：工具响应经过字段裁剪，例如 dashboard-get/dashboard-update 的响应中会剥离 insight 的 result、filters、query_status 等重型字段（见 tools.yaml 中每个工具下的 response.exclude 列表），只保留 id、query 等标识性元数据，以节省 LLM 上下文。
2. 操作语义收敛：看板瓦片的增删改查被封装为 6 个语义清晰的工具，Agent 无需记忆 REST 路径细节，只需按目标选择工具。

关键约束（原文档明确说明）：不存在独立的单瓦片创建端点，也不存在逐瓦片的 PATCH .../widgets/:tile_id/ REST 端点——UI 与 MCP 统一使用批量添加（batch add）与看板 PATCH 两种通道。这一点在 集成测试 中有直接体现：测试通过 dashboard-widgets-batch-add 添加瓦片，再通过 dashboard-get 读取瓦片 ID。

二、工具总览：6 个工具与目标映射

目标	MCP 工具	说明
发现 widget 类型与配置 schema	dashboard-widget-catalog-list	只读目录；每个类型附带 config_schema（Pydantic JSON Schema，含边界、选项、默认值）
读取看板瓦片与 widget 配置	dashboard-get	瓦片包含 widget.widget_type 与 widget.config；不含实时数据
添加 widget 瓦片	dashboard-widgets-batch-add	通过 POST .../widgets/batch/ 原子批量添加（1–10 个瓦片；单瓦片传单元素 widgets 数组）
更新 widget 瓦片	dashboard-update	PATCH 看板并携带 tiles[]：每个瓦片包含 id + widget.id + 需变更的字段
运行 widget 查询	dashboard-widgets-run	以 dashboard-get 返回的 tile_ids（逗号分隔）执行实时查询
复制瓦片到其他看板	dashboard-tile-copy	深拷贝 widget；目标看板为路径中的看板 ID
在看板间移动瓦片	dashboards-move-tile-partial-update	源看板为路径 id；传入 to_dashboard 与来自 dashboard-get 的 tile.id

补充说明：上述"6 个工具"指的是原文档聚焦的 widget 瓦片操作；tools.yaml 中 Dashboards 分类还包含 dashboard-create、dashboard-delete-tile、dashboard-reorder-tiles、dashboard-widgets-batch-update 等配套工具，它们与 widget 生命周期共同构成完整的看板编排能力。例如 dashboard-widgets-batch-update 可以在不删除重建的前提下原地原子更新 1–10 个 widget 的 config/name/description，且 widget_type 不可变。

三、典型 Agent 工作流：从发现到实时数据

原文档给出了一条 4 步的典型 Agent 流程，可直接复制为对话指令模板：

1. dashboard-widget-catalog-list —— 挑选 widget_type，依据 config_schema 构造 config（与 batch-add / PATCH 的 OpenAPI 形状一致；支持的类型会包含 widgetFilters）。
2. dashboard-widgets-batch-add —— 一次请求添加 1 至 10 个瓦片。
3. dashboard-get —— 确认瓦片 ID、widget 行 id 与布局信息。
4. dashboard-widgets-run —— 为 tile_ids 拉取实时数据（仅限私有看板——公开/共享视图不会调用 run_widgets）。

更新场景的固定套路：

dashboard-update 传入 tiles = [{ id, widget: { id, config?, name?, description? } }]

随后在需要刷新实时数据时调用 dashboard-widgets-run。

UI 与 MCP 的一致性：UI 中多瓦片添加使用 POST .../widgets/batch/（前端函数 addWidgetTiles），与 MCP 的 batch add 走完全相同的端点——因此 Agent 添加瓦片的行为与用户在界面上添加瓦片完全等价。

四、REST 等价映射：每个 MCP 工具背后的端点

MCP 工具	对应 REST 端点
dashboard-widget-catalog-list	GET .../dashboards/widget_catalog/
dashboard-widgets-batch-add	POST .../dashboards/:id/widgets/batch/（1–10 瓦片，原子化）
dashboard-update（widget 瓦片）	PATCH .../dashboards/:id，携带 tiles[] 与嵌套 widget
dashboard-widgets-run	GET .../dashboards/:id/run_widgets/?tile_ids=
dashboard-tile-copy	POST .../dashboards/:id/copy_tile/
dashboards-move-tile-partial-update	PATCH .../dashboards/:id/move_tile/

原文档强调：UI 多选添加使用 POST .../widgets/batch/（创建时不使用 PATCH 看板 tiles[]）。也就是说，创建瓦片一律走批量端点，PATCH 只用于更新已有瓦片。

4.1 源码佐证：后端端点结构

这些端点定义在 products/dashboards/backend/api/dashboard.py 中，关键方法包括：

• run_widgets（dashboard.py#L3223）：首先通过 dashboard_widgets_enabled 校验项目是否启用 widgets 功能；然后解析 tile_ids 查询参数为整数列表（去重、限制在 MAX_WIDGETS_BATCH_SIZE 之内），再按 dashboard + widget__isnull=False 条件批量加载 DashboardTile，逐个执行查询并返回按瓦片聚合的结果（tile_id、widget_type、result 三元组）。
• widget_catalog（dashboard.py#L3352）：返回注册的 widget 类型目录。
• widgets_batch（dashboard.py#L3361）：批量化创建 widget 瓦片。

五、权限模型：作用域与产品级访问控制

原文档给出了两条清晰的权限规则，并结合实际看板页面的共享/公开模式做了约束：

• 写操作（add / update / copy / move）需要 Dashboard edit scope（对应工具配置中的 dashboard:write）。
• 读操作（get / catalog / run）需要 Dashboard read scope（dashboard:read）。
• 每个 widget 类型可能额外要求产品级访问权限——请在 dashboard-widget-catalog-list 的结果中检查 required_product_access 字段；被拒绝的瓦片会在 run / add 路径中返回逐瓦片错误。

5.1 源码佐证：注册表中的产品访问要求

在 products/dashboards/backend/widget_specs/registry.py 中，每个 WidgetSpec 都声明了 required_product_access 与 required_scopes：

widget_type	required_product_access	required_scopes
activity_events_list（Recent events）	无	query:read
error_tracking_list（Top issues）	error_tracking	error_tracking:read
session_replay_list（最近录制）	session_recording	—
experiments_list / experiment_results	experiment	—
survey_results	survey	—
logs_list	logs	—
conversations_recent_tickets	ticket	—

WidgetSpec 还携带 group_id/group_label（用于分类展示）、config_model（Pydantic 配置模型）、query_fn（实际查询执行函数）、form_fields（表单字段列表）与 filter_fields 等元信息，这些信息共同驱动目录、表单与查询的执行。

六、配置契约：Pydantic 单一事实来源（SSOT）

widget 配置的底层契约是 Pydantic 模型（widget_specs/configs.py + WidgetSpec 注册表），而不是手写的 OpenAPI。从 registry.py#L100 的 validate_widget_config 可以看到执行时的校验逻辑：

1. 按 widget_type 查找 WidgetSpec，未知类型抛出 DRFValidationError({"widget_type": ...})；
2. 用 spec.config_model.model_validate(config) 做类型与边界校验；
3. 返回 model_dump(mode="json", exclude_none=True) 的规范化配置。

也就是说，你在 config_schema 里看到的"边界、选项、默认值"就是 Pydantic 字段定义（如 limit 默认 10、orderBy 默认 start_time 等）自动生成的 JSON Schema。修改配置契约后，通过 hogli build:openapi 即可把变更同步到 OpenAPI、前端 Zod schema 与 MCP 工具 schema（详见 config-and-codegen.md 与 architecture.md）。

6.1 常见 config 键

dashboard-widget-catalog-list 的描述中给出了一组共享配置键，适用于大多数 widget 类型：

• limit：列表条数上限
• orderBy / orderDirection：排序字段与方向
• dateRange：时间范围
• filterTestAccounts：是否过滤测试账号
• widgetFilters（可选）：filter id -> property filter entries 的映射

在集成测试 dashboards.integration.test.ts 中，可以找到最小可用的添加负载：

const addResult = await batchAddWidgetTool.handler(context, {
    id: dashboard.id,
    widgets: [
        {
            widget_type: 'error_tracking_list',
            config: { limit: 5 },
        },
    ],
})

测试同时验证了 catalog.results 中 error_tracking_list.config_schema.properties.limit.default === 10、session_replay_list.config_schema.properties.orderBy.default === 'start_time'，这些默认值即来自注册表配置模型。

七、发布新 widget_type 后的维护清单

当你（作为 PostHog 工程师）在仓库中发布了一个新的 widget_type，原文档给出了 3 步收尾流程，确保 MCP 工具 schema 与测试保持同步：

# 1. 重新生成 OpenAPI —— 同步 MCP 工具 schema 中内嵌的类型列表
hogli build:openapi

# 2. 运行 Dashboards MCP 集成测试
hogli test services/mcp/tests/tools/dashboards.integration.test.ts

# 3. 若 batch-add 的帮助文本包含类型列表，则更新单元 schema 快照
hogli test services/mcp/tests/unit/tool-schema-snapshots.test.ts

如果只改了配置契约（widget_specs/ 下的文件），还需要运行配置 schema 一致性测试：

hogli test products/dashboards/backend/api/test/test_widget_config_schema_parity.py
hogli test products/dashboards/frontend/widgets/widgetConfigSchemaParity.test.ts

（新增类型另需 test_widget_openapi_enums.py。）这条流程与 manage-dashboard-widgets/SKILL.md 中"Ship gate"的定义一致：发布前必须完成 hogli build:openapi 与对应测试，保证后端注册表、OpenAPI 与前端 schema 三者一致。

八、与"ship a new widget_type"的边界

需要特别区分两类工作，避免误用本文的工具集：

• 使用现有类型往看板加瓦片（Agent 日常操作）：走 MCP dashboard-widget-catalog-list → dashboard-widgets-batch-add，即本文主体内容。
• 在代码仓库中新增/修改 widget 类型（工程师开发工作）：走 manage-dashboard-widgets 技能 的"Ship a new widget_type"流程（含 intake、WIDGET_REGISTRY、widget_specs/、前端 registry.tsx、Storybook 与测试）。

此外，图表类（trend/graph）看板瓦片应使用 insight tile 而非 widget——widget 平台的设计约束是"不做图表主型的 widget"（见 architecture.md 的 Charts 章节），这也是判断"该用哪个工具"的关键分界线。

九、实战建议与常见坑

1. 先 catalog 后 batch-add：不要凭记忆猜 widget_type 字符串与 config 形状，config_schema 是唯一权威。
2. 单瓦片也是数组：widgets 必须传数组，单瓦片传单元素数组 [{ widget_type, config }]；layouts 缺省时瓦片会堆叠在看板底部。
3. 更新走 PATCH，添加走 batch：给已有瓦片改配置用 dashboard-update（或 dashboard-widgets-batch-update，后者只传 tile_id 更省事）；新增瓦片永远用 batch add，不要尝试用 PATCH tiles[] 来创建。
4. 实时数据靠 run：dashboard-get 返回的 widget 瓦片只有 widget_type 与 config，没有数据；要拿实时结果必须调 dashboard-widgets-run，且仅限私有看板（公开/共享视图不执行 run_widgets）。
5. 权限逐瓦片失败：当 Agent 缺少某个 widget 类型的 required_product_access 时，run / add 会返回逐瓦片错误而不是整体失败——解析响应时要按 tile_id 维度处理错误。
6. 发布后三连：新类型上线后务必按第七章执行 OpenAPI 重新生成 + 集成测试 + schema 快照更新，否则 MCP 工具暴露的 schema 会与后端实际行为不一致。

十、结语

PostHog 通过"原子化 MCP 工具 + Pydantic 配置 SSOT + 注册表驱动 RBAC"三件套，把看板 widget 瓦片的生命周期管理变得对 Agent 完全可编程：工具层屏蔽 REST 细节，注册表统一类型与权限元数据，OpenAPI/前端/MCP schema 由代码生成保持同源同步。无论你是想在自己的 Agent 流程里编排看板，还是作为 PostHog 工程师扩展新的 widget 类型，本文的工具映射表、REST 等价表与发布清单都可以直接作为操作手册使用。

进一步阅读：

• MCP 工具定义全集：products/dashboards/mcp/tools.yaml
• widget 注册表与配置模型：products/dashboards/backend/widget_specs/registry.py
• 看板后端端点实现：products/dashboards/backend/api/dashboard.py
• MCP 集成测试：services/mcp/tests/tools/dashboards.integration.test.ts
• 技能主文档：.agents/skills/manage-dashboard-widgets/SKILL.md