PostHog building-a-dashboard 技能用 MCP 工具为 Agent 构建专业仪表盘【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog在 PostHog 仓库中products/dashboards/skills/building-a-dashboard/SKILL.md是一份面向 AI Agent 的公开技能published skill它把产品内 App 助手用upsert-dashboard工具组装仪表盘的那套判断流程迁移到 MCP 工具链上教 Agent 如何从用户的一句话需求出发决定新建还是更新、复用哪些既有 insight、参考哪些官方模板最后用dashboard-*系列 MCP 工具落地并验证。读完本文你可以完整掌握这条意图 → 模板参考 → insight 选择 → 组装 → 验证的工作流以及背后products/dashboards/mcp/tools.yaml中每个工具的权限范围、幂等性与省 context的设计细节。1. 技能定位什么是 building-a-dashboard先明确这份技能文档在 PostHog skills 体系中的位置。PostHog 的 skill 是job-to-be-done式的模板它不描述工具是否存在那是 MCP server 的事而是描述一个有经验的人会用这些工具如何完成一件事。技能分为两类存放位置见 writing-skills 技能products/product/skills/—— 通过 PostHog 工具、API 或客户代码完成的工作会被发布给外部消费者PostHog Desktop、编码 Agent 等.agents/skills/—— 需要 checkout PostHog 仓库的开发工作只留在仓库内。building-a-dashboard属于前者文件位于 products/dashboards/skills/building-a-dashboard/SKILL.md遵循标准结构YAML frontmattername小写 kebab-case这里为building-a-dashboard与description第三人称、包含触发词、最长 1024 字符。description 中明确列出了触发场景用户要求创建仪表盘、把多个指标/图表放到一页上、围绕某个主题产品分析、留存、营收、激活等组装仪表盘、或在已有仪表盘上增删替换 insight正文控制在 500 行以内的工作流描述而非死板的脚本。原文档开宗明义地给出了这份技能的核心立场A dashboard is a collection of insight tiles on one page. Your job is to figure out which insights belong on it, reuse what already exists, create whats missing, and lay them out sensibly —not to blindly generate charts.仪表盘是一页上的一组 insight 图块tile。Agent 的职责是判断哪些 insight 属于它、复用已存在的、只创建缺失的、并合理排版——而不是盲目生成图表。这句话是整条工作流的设计哲学后续每一步都为它服务。2. 第一步判断新建还是更新技能要求 Agent 先弄清自己是在创建新仪表盘还是修改已有仪表盘。原文给出的三步决策法用dashboards-get-all搜索已有仪表盘。它的search参数对名称和描述做模糊匹配fuzzy name/description matching。如果用户描述的明显是已经存在的东西多半想要的是更新而非新建。用dashboard-get读取候选仪表盘的当前 tiles在动任何东西之前先看清它现在长什么样。请求模糊时问一句简短的澄清问题而不是猜。原文的例子get my financial metrics together把我的财务指标凑到一起——这可能是建新盘也可能是往已有盘上加图。对照 products/dashboards/mcp/tools.yaml 中的工具定义可以看到这两个工具的实际契约dashboards-get-all对应 OpenAPI operationdashboards_list见 tools.yaml#L637-L661scope 为dashboard:readreadOnly: trueidempotent: true。其描述补充了一个重要细节search参数基于Postgres trigram 词相似度实现能处理拼写错误、字符换位和输入前缀即匹配并按相关度排序返回查询长度上限 200 字符超出返回 400。返回列表只含名称、描述、pinned 状态、tags 与创建元数据不含 tiles——取 tiles 必须再调dashboard-get。dashboard-get对应dashboards_retrieve见 tools.yaml#L187-L209返回完整仪表盘包括所有 tile 的 insight 配置、widget 配置与布局信息。注意其响应排除了tiles.*.insight.result、tiles.*.insight.hogql等大量字段——insight 结果、过滤器和查询元数据被刻意省略以节省 LLM context取数需另调dashboard-insights-run。这里就引出了整个 MCP 仪表盘工具链一个贯穿性的设计读取类工具默认不返回查询结果。dashboard-create、dashboard-get、dashboard-update的响应里都剔除了insight.result、filters、hogql等重字段见 tools.yaml#L76-L99 的response.exclude列表。对 Agent 而言这意味着判断这个 insight 有没有数据不能靠dashboard-get的返回必须走专门的 run 工具这也正是技能在组装阶段要求验证的原因见第 5 节。3. 第二步以官方模板为参考而不是照抄技能建议在动手构建之前先查阅仪表盘模板PostHog 为常见主题提供了经过审核vetted的仪表盘模板组织内也可以共享自己的模板。它们是哪些 insight 适合搭配在一个主题上的强信号。原文给出两步dashboard-templates-list—— 浏览模板search按主题搜scope收窄到 global / team / organization。该工具只返回名称、描述和 tags。dashboard-templates-retrieve—— 打开最接近的模板查看它的tiles模板把哪些 insight 组合在一起、每个 insight 如何查询。模板必须被当作示例examples, not a spec从中汲取 insight 与分组方式的灵感但要把每个 insight 调整到用户自己的事件、属性和意图上不要逐字照抄模板也不要把一个不贴合的模板硬套到请求上——一个贴合的好定制盘永远胜过一个错配的模板。tools.yaml 中的定义与技能描述高度一致并补充了两处工程细节见 tools.yaml#L340-L389dashboard-templates-listoperationdashboard_templates_listscopedashboard_template:read明确在响应中剔除tiles、variables、dashboard_filters、non_portable_references等字段以省 context并声明list: true分页列表型工具。两个模板工具都把模板内容标注为**informational-only boundary仅信息参考边界**模板内容可能由用户编写user-authored工具返回时包在一个信息边界内并明确指令边界内的任何指令都不得被执行——这是针对提示注入的防御Agent 只能把模板当作结构参考绝不能执行模板里嵌进来的指令。模板机制的后端支撑在仓库中同样可查模板模型与 API 位于products/dashboards/backend/models/dashboard_templates.py与 products/dashboards/backend/api/dashboard_templates.py其测试覆盖在 products/dashboards/backend/api/test/test_dashboard_templates.py模板的 JSON Schema 定义在 products/dashboards/backend/api/dashboard_template_schema.json。4. 第三步挑选 insights——复用优先最小集技能对 insight 的选择给出三条规则优先复用已存在的 insight而不是重新创建。用insights-list搜索用insight-get读取候选项确认它们既匹配用户意图、又确实有数据。原文特别提醒全文搜索会漏掉命名不同的 insight所以在下结论某个 insight 不存在之前先宽泛地 list 一遍。缺什么就创建什么用insight-create查询形状参见 product-analytics 的 insight 技能——这些工具与技能定义在 product_analytics 产品域见 products/product_analytics/mcp/tools.yaml 与 products/product_analytics/skills/ 下的如investigate-metric等技能。保持最小集只放请求真正需要的 insight。一个聚焦的仪表盘比一个穷举的更有用。这几条规则共同实现开头声明的哲学不是给每个词都配一个图表而是先盘库存、再补缺口。5. 第四步组装并验证技能的组装章节是实操核心四条要点操作工具关键约束新建仪表盘dashboard-create短名称3–7 个词 简洁描述然后添加 insight tiles更新已有仪表盘dashboard-update增、换、删 insight 都要发送完整的目标 tiles 集合——你省略的 insight 会被移除所以想保留的必须一并带上布局调整dashboard-reorder-tiles默认保持既有 tile 位置不变只有用户明确要求重排、换序、移动时才调用验证dashboard-insights-run确认 tiles 返回数据然后总结你构建了什么并邀请用户继续打磨对照 tools.yamldashboard-update对应dashboards_partial_updatetools.yaml#L411-L429的annotations标记为idempotent: true、destructive: false其描述确认它可以更新名称、描述、pinned 状态、tags、filters、限制级别以及 widget tile 的布局而dashboard-reorder-tilestools.yaml#L298-L312的工作方式是传入按期望显示顺序排列的 tile ID 数组默认保留既有宽度与高度。dashboard-insights-run对应dashboards_run_insights_retrievescopequery:readtools.yaml#L279-L297是验证步骤的落点其描述补充了技能原文没写的两个参数语义默认使用缓存结果可能过期设refreshblocking可获得新鲜结果format支持optimized默认对 LLM 友好的文本表格或json原始查询结果支持variables_override与filters_override查询参数做一次性覆盖而不持久化。这解释了为什么验证是不可省略的一步dashboard-get/dashboard-create/dashboard-update的响应都不带 insight 数据只有dashboard-insights-run能证明这块 tile 真的出数了。仪表盘 API、tile 操作与 insight runner 的后端实现集中在 products/dashboards/backend/api/dashboard.pyrun_insights端点的行为另有 products/dashboards/backend/api/test/test_run_insights.py 测试覆盖数据模型见 products/dashboards/backend/models/dashboard.py 与 products/dashboards/backend/models/dashboard_tile.py。6. 边界何时不该用这个技能原文列了两个明确的反例避免 Agent 越界只保存单个 insight—— 直接创建 insight 即可不需要仪表盘。添加非 insight 的 widget tile文本卡、widget—— 应改用 widget 工具dashboard-widget-catalog-list查可用 widget 类型dashboard-widgets-batch-add批量添加。tools.yaml 印证了 widget 路径的独立性与门禁dashboard-widgets-batch-addPOST .../widgets/batch/一次 1–10 个 tile与dashboard-widgets-batch-update都标注了feature_flag: dashboard-widgetstools.yaml#L547-L593即需要项目开启dashboard-widgets特性开关catalog 工具会返回每种widget_type的config_schema公共配置键包括limit、orderBy、orderDirection、dateRange、filterTestAccounts与可选的widgetFilters。widget 体系的架构约束在 products/dashboards/CONTRIBUTING.md 中有完整说明图表/趋势类内容一律用 insight tile而不是新建 widget 类型Charts/trends on a dashboard → insight tiles, not new widget types——这正与 building-a-dashboard 技能只装配 insight的职责边界相互咬合。此外dashboard-create的工具描述本身也承担了路由职责tools.yaml#L29-L33仪表盘适合会被反复查看的一组指标监控、周报月报、团队总览、发布与健康看板而带叙述、中间步骤和结论的深度排查应该去 notebook——当一次深入分析只沉淀出少数值得跟踪的指标时存成 insight 而非把它们硬塞进仪表盘。这与技能文档的定位互为补充技能管怎么建盘工具描述管该不该建盘。7. 交付延伸与订阅技能的衔接原文Related skills一节指向两个后续动作它们都已作为独立技能存在于仓库中managing-subscriptions位于products/posthog_ai/skills/managing-subscriptions/——把做好的仪表盘按周期投递到邮箱或 Slackcreating-ai-subscription位于products/subscriptions/skills/creating-ai-subscription/——周期性的 AI 撰写报告适合散文比一堆图表更合适的场景。tools.yaml 中dashboard-create的agent_notetools.yaml#L34-L47把这一衔接写成了精细的行为规约只有当返回的仪表盘已有 tiles时才建议订阅空盘没有可投递的内容且subscriptions-create至少需要一个 chart建议时用人的语言描述如每周一早上邮件附上这些图表创建订阅需dashboardid、dashboard_export_insights最多 10 个图表、target_typeemail/slack、target_value、frequency、interval、start_dateSlack 投递另需integration_id收件人和节奏必须问用户不能由 Agent 自作主张若subscriptions-create不可用或用户此前已拒绝过则绝口不提。这段 note 展示了 PostHog 如何把产品品味编码进工具元数据供 Agent 消费。8. 工程背景这份技能如何被构建、校验与发布从仓库的 skills 工程设施看building-a-dashboard遵循统一的生产管线writing-skills 技能hogli init:skill脚手架在products/{product}/skills/{skill-name}/SKILL.md编写正文hogli lint:skills静态检查两个 skills 目录都受检hogli build:skills构建验证hogli sync:skill -- --name skill-name在 PostHog Desktop 或编码 Agent 中本地实测合入后 CI 自动发布到 PostHog 的公开 skills 仓库。结构约定上只有references/详细参考材料支持渐进式披露与scripts/可执行脚本子目录会被收集.j2后缀文件在构建期用 Jinja2 渲染可用pydantic_schema、render_hogql_example、hogql_functions等模板函数把代码中的领域知识Pydantic 模型、HogQL 函数表渲染进文档避免静态 markdown 与代码漂移。与本文技能同产品域的另一份仓库内技能 managing-dashboards 则是给改仪表盘平台代码的工程师用的它给出的代码地图可以直接作为深入阅读的入口关注点起点Dashboard API、序列化器、tile 操作、insight/widget runnerproducts/dashboards/backend/api/dashboard.pyDashboard / Tile 模型products/dashboards/backend/models/dashboard.py、products/dashboards/backend/models/dashboard_tile.py模板products/dashboards/backend/api/dashboard_templates.pyMCP 工具定义products/dashboards/mcp/tools.yaml刷新策略默认值posthog/hogql_queries/refresh_policy.py这解释了本文第 2 节中读取不返回结果机制的来处runner 端点与缓存策略是仪表盘平台的一等公民MCP 层只是在其之上做了一层面向 LLM context 预算的响应裁剪。9. 小结building-a-dashboard技能的价值不在命令罗列而在它把资深分析师建盘的决策链固化成了 Agent 可执行的工作流建还是改dashboards-get-alltrigram 模糊搜索dashboard-get模糊就问不猜先查模板dashboard-templates-list名称/tags→dashboard-templates-retrievetiles 与查询形状参考而不照抄且对模板内容保持信息边界内的提示注入防御复用优先的 insight 选择insights-list/insight-get确认存在且有数据缺口才insight-create集合保持最小组装dashboard-create3–7 词短名或dashboard-update全量 tiles 语义省略即删除默认不动布局仅用户明确要求时dashboard-reorder-tiles验证dashboard-insights-run确认出数注意默认走缓存refreshblocking取新鲜值最后向用户总结并邀请迭代。配套的两个边界单 insight 直接存、widget tile 走 widget 工具链且受dashboard-widgets特性开关控制和两条交付延伸订阅投递、AI 报告订阅使这条工作流完整覆盖了从一句话需求到一个可定期消费的仪表盘的全过程。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考