PostHog 的 LLM Prompting 指南：从 Prompt 结构到生产级 Agent 的完整实践-北京尧图网络

PostHog 的 LLM Prompting 指南从 Prompt 结构到生产级 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 开源仓库中的 LLM prompting guide系统梳理 PostHog 在构建 Max AI Agent 时沉淀下来的提示词工程方法论如何通过MaxChatOpenAI统一注入项目上下文、如何用结构化 XML 标签组织 system prompt、如何借助 Mustache 模板做动态内容拼接以及如何通过 Prompt Caching 和 Braintrust 评测让 Agent 既便宜又可靠。读完本文你将掌握一套可以直接复用的、面向数据分析类 LLM Agent 的提示词设计模式并能在 ee/hogai 目录下的真实源码中找到每一处原则的落地实现。一、标准积木为什么永远用MaxChatOpenAI而不是裸的ChatOpenAIPostHog 内部第一条硬性规范是永远使用MaxChatOpenAI或MaxChatAnthropic不要直接使用 LangChain 原生的ChatOpenAI。原文档给出了正反两例from ee.hogai.llm import MaxChatOpenAI # ✅ Correct - auto-injects user/project/org context llm MaxChatOpenAI(useruser, teamteam, modelgpt-4.1) # ❌ Wrong - missing PostHog context llm ChatOpenAI(modelgpt-4.1)其背后的原因是MaxChatOpenAI会在每次生成时自动注入一组“项目/组织/用户上下文”包括项目名称与项目时区组织名称用户姓名与邮箱项目当前时间按项目时区换算这段上下文会被追加到system message 的末尾这是刻意为之原因见后文性能与成本一节。源码级实现上下文注入是如何完成的在 ee/hogai/llm.py 中MaxChatOpenAI继承自MaxChatMixin与 LangChain 的ChatOpenAI核心注入逻辑由MaxChatMixin承担_get_project_org_user_variables()llm.py负责从team、team.organization、user拉取数据并把项目时间换算到项目时区最终输出一组 Mustache 变量project_name、project_timezone、project_datetime、organization_name、user_full_name、user_email、deployment_region、person_on_events_enabled。_enrich_messages()llm.py会把上下文 prompt 插到每个消息子列表的system messages 区块末尾即第一个非 system 消息之前确保上下文紧随用户可见的指令之后。对于 OpenAI 的 Responses API则通过_enrich_responses_api_model_kwargs()llm.py把上下文写进model_kwargs[instructions]已有 instructions 时追加在其后。实际注入的上下文模板定义在同一个文件的PROJECT_ORG_USER_CONTEXT_PROMPTllm.py中它远不止叫什么名字这么简单还包含了大量对 Agent 行为有实质约束的规则例如所有 PostHog 应用链接必须使用以/开头的根相对路径/cohorts、/insights/short_id禁止带域名、禁止出现/-/、禁止../或./这类相对路径当前时间以项目时区展示Current time in the projects timezone, {{{project_timezone}}}: {{{project_datetime}}}依据person_on_events_enabled条件段落动态说明本项目是事件时点属性还是查询时属性语义——这直接决定了 Agent 在person.properties.*上的回答口径是否正确。MaxChatMixin还顺带处理了两件对生产至关重要的杂事默认max_retries3、默认开启stream_usagellm.py当billableTrue时会把$ai_billable、team_id等属性写进 metadata用于 AI 计费核算_with_posthog_propertiesllm.py。如果某些场景确实不需要注入上下文例如工具内部的一次性 LLM 调用可以显式设置inject_contextFalse。二、PostHog Prompt 的解剖结构化 XML 标签 Mustache 模板统一的 Prompt 骨架PostHog 的 system prompt 几乎都遵循同一个骨架——用非嵌套的 XML 风格标签划分语义区块SYSTEM_PROMPT agent_info You are PostHogs AI agent... Your role and personality description. /agent_info instructions Specific task instructions and guidelines. /instructions constraints What the agent should and shouldnt do. /constraints examples Few-shot examples demonstrating the expected behavior. /examples {{{dynamic_context}}} .strip()这种非嵌套 XML 标签设计有两个优点一是对 LLM 而言区块边界清晰、指令与约束不易混淆二是对工程而言模板字符串可以按区块拆分、独立维护、单独做单元测试。在源码中可以看到大量真实范例。例如 ee/hogai/chat_agent/prompts/base.py 里最终拼装出的AGENT_PROMPTbase.py就是由role、tone_and_style、writing_style、proactiveness、basic_functionality、slash_commands、switching_modes、task_management、doing_tasks、product_advocacy、tool_usage_policy、billing_context、groups_prompt等十余个 Mustache 变量组合而成而每个变量对应的区块如tone_and_style、writing_style、tool_usage_policy都是独立的常量由 prompt_builder.py 中的ChatAgentPromptBuilder._get_system_prompt()统一渲染。TONE_AND_STYLE_PROMPT tone_and_style Use PostHogs distinctive voice - friendly and direct without corporate fluff. ... Do NOT compliment the user with fluff like Great question! or Youre absolutely right! ... /tone_and_style .strip()这些区块连禁止说什么都写得非常具体tool_usage_policy里甚至规定web_search只能单独调用、不能与其他工具并行可见 PostHog 把 system prompt 当成了一等代码资产来维护。Mustache 变量模板化PostHog 使用Mustache而非 f-string来做动态内容替换因为它天然支持三花括号不转义 HTML、条件区块和列表迭代# Basic variable substitution The project name is {{{project_name}}} # Conditional sections {{#show_advanced}}Advanced options: {{{options}}}{{/show_advanced}} # Lists/iterations {{#events}}Event: {{{name}}}{{/events}}工程侧的统一入口是 ee/hogai/utils/prompt.py 中的format_prompt_string()它基于 LangChain 的PromptTemplatetemplate_formatmustache实现常被工具用来按运行时上下文权限、团队设置动态拼接工具描述。MaxChatMixin注入的上下文 prompt 也显式使用了template_formatmustachellm.py。{{#person_on_events_enabled}}...{{/person_on_events_enabled}}与{{^person_on_events_enabled}}...{{/person_on_events_enabled}}正反条件区块的用法在上面提到的PROJECT_ORG_USER_CONTEXT_PROMPT里就是现成案例。三、写出能干活的 Prompt四条核心写作原则1. 具体性Specificity模糊的指令只会得到模糊的输出。原文档对比了两段 prompt# ✅ Good - specific and actionable Generate a trends query that shows daily active users for the last 30 days, filtered to exclude internal users, displayed as a line chart. # ❌ Bad - vague and ambiguous Create a user trend analysis.源码中的TRENDS_SYSTEM_PROMPTee/hogai/chat_agent/trends/prompts.py把具体性推到了极致它逐条规定了 series 怎么构建、属性运算符何时要equals换成contains人名/公司名这类大小写敏感的取值、如何根据语义选图表类型时间动态用ActionsLineGraph、单个数字用BoldNumber、分类数据用ActionsBar、单系列且按国家分布用WorldMap、比率类指标必须用 0-1 原始比值加percentage_scaled轴格式、且严禁在公式里再乘 100否则会渲染成 5000%。这些不写清楚就会踩坑的细节正是具体性 prompt 的价值所在。2. 上下文与约束Context and constraints给模型明确的边界输出才会落在 schema 内# ✅ Good - includes constraints and context Act as an expert product analyst. Generate a JSON schema for funnel insights. - Only use events and properties provided in the taxonomy - Filter internal users by default - Use reasonable date ranges when not specified - Return valid JSON that matches the schema exactly # ❌ Bad - no constraints or context Create a funnel query.同样的约束在FUNNEL_SYSTEM_PROMPTee/hogai/chat_agent/funnels/prompts.py中以更细的规则出现funnel 类型steps/time_to_convert/trends的选择条件、optionalInFunnel只能用于中间步骤首尾步骤不可标记为 optional、默认聚合方式为 unique users、以及结尾的三条硬规则——日期范围未指定时默认取最近 30 天未指定时默认过滤内部用户绝不能发明 plan 之外的新事件或新属性。3. 少样本示例Few-shot examples好的示例应当是输入 → 输出配对并且刻意覆盖边界情况。原文档的 funnel 示例展示了从简单转化率到带 breakdown 的完整 JSONEXAMPLES ### Example 1: Simple conversion rate Question: Whats the signup to purchase conversion rate? Output: {kind:FunnelsQuery,series:[{event:user signed up},{event:purchase}]} ### Example 2: With filters and breakdown Question: Conversion rate by country for mobile users? Output: {kind:FunnelsQuery,series:[{event:user signed up,properties:[{key:$device_type,value:Mobile}]},{event:purchase}],breakdownFilter:{breakdown:$geoip_country_name}} 仓库里的少样本示例更具实战深度TRENDS_SYSTEM_PROMPT内嵌了 9 组问题 → JSON 输出对覆盖 DAU/MAU 比率、p99 时长分位数、action series、unique_group、多 breakdown、排除国家等场景FUNNEL_SYSTEM_PROMPT则有 5 组包括严格顺序漏斗funnelOrderType:strict、带排除步骤、可选步骤optionalInFunnel等边界情况。摘要类的ACTIONS_SUMMARIZER_SYSTEM_PROMPTee/hogai/summarizers/prompts.py则用autocaptured_events区块专门向模型解释$autocapture的匹配维度。示例不是装饰而是把隐性规则显式化的最有效手段。4. 防御歧义Guarding against ambiguity当用户问题模棱两可时不要替用户做假设 If the users question is ambiguous: - Ask for clarification using the foo tool - Dont make assumptions about missing parameters - Suggest common alternatives: Did you mean daily active users or total events? 四、架构模式单次调用 vs 多调用 Agent单次调用任务Single-call tasks适用于查询生成、摘要这类一次 LLM 调用即可完成的任务。原文档给出两个模板QUERY_GENERATOR_PROMPT带role_context、task_instructions、schema_definitions区块schema 示例经{{{schema_examples}}}注入和SUMMARIZER_PROMPT要求最多三句话、用业务语言而非技术黑话总结 action。仓库中ACTIONS_SUMMARIZER_SYSTEM_PROMPT正是后者的完整落地版。多调用任务Multi-call tasks——真正的 Agent当让 LLM 自行调用工具并消费工具结果时它就变成了 Agent。原文档的TOOL_AGENT_PROMPT展示了先用工具查证、再给最终答案的强制流程TOOL_AGENT_PROMPT You have access to these tools: 1. search_events - Find events matching patterns 2. get_property_values - Get possible values for properties 3. final_answer - Provide the final query plan Before generating a query: - Use search_events to find relevant events - Use get_property_values to validate filter values - Call final_answer with your complete plan Never guess event names or property values - always verify using tools. Never guess, always verify这一条在 PostHog 中不止是口头约定——从 ee/hogai/chat_agent 目录结构可以看到真实的 Agent 编排graph.py、runner.py、toolkit.py以及按领域拆分的funnels/、trends/、retention/、query_planner/、query_executor/、taxonomy/、sql/等子模块工具侧ee/hogai/tools则提供了read_taxonomy、execute_sql、search、manage_memories、switch_mode、subagent_executor等一组可组合的原语。taxonomy Agent 的实现模式在 ee/hogai/README.md 的 Taxonomy Agent 一节有完整可复制的代码TaxonomyAgentToolkitfinal_answer 自定义工具 TaxonomyAgent图编排并给出了products/replay/backend/max_tools.py作为真实接入范例。五、性能与成本让 Prompt Caching 真正生效PostHog 对 OpenAI 的prompt caching依赖很重——缓存命中既能省成本也能降延迟。而缓存能否命中取决于 system prompt 的前缀稳定性因此一条铁律是静态内容放在前面动态内容放在最后。# ✅ Good - static content first, dynamic last SYSTEM_PROMPT You are an expert analyst... static_instructions These instructions never change... /static_instructions examples Static examples... /examples {{{dynamic_user_context}}} {{{current_data}}} .strip() # ❌ Bad - dynamic content breaks caching SYSTEM_PROMPT Current user: {{{user_name}}} Current project: {{{project_name}}} You are an expert analyst... static_content .strip()这正是上下文注入放在 system messages 末尾见第一节的根本原因如果动态上下文放在前面每一条新消息都会产生不同的前缀缓存直接失效放在末尾则前缀始终稳定命中率高。类似地ee/hogai/core/shared_prompts.py 中的CORE_MEMORY_PROMPT也把core_memory设计成独立区块尽量让变化的记忆内容与稳定的指令分离。六、评估用 Braintrust 守住质量底线提示词是代码就必须有测试。PostHog 使用Braintrust作为评测平台对 LLM 输出做持续回归测试。原文档的指引是新的用例场景要在ee/hogai/eval/下补评测用例。ee/hogai/eval/README.md 提供了完整的实操细节CI evals导出BRAINTRUST_API_KEY后执行pytest ee/hogai/eval/ci必须指定该目录以激活 pytest.ini 中的 eval 专用配置也可加--eval sql只跑含sql的用例结果与 traces 会上传到 Braintrust 并在终端汇总。离线 evals先在数据集页收集input/expected_output/metadatametadata 必须含team_id格式的数据集再在 ee/hogai/eval/offline 下实现评测模块——用capture_score装饰 scorer如 scorers 里的SQLSemanticsCorrectness、SQLSyntaxCorrectness用generate_test_cases把数据集条目变成EvalCase最终通过MaxPrivateEval跑整条图AssistantGraph(...).compile_full_graph().ainvoke(...)。该 README 中还给出了完整的eval_offline_sql示例代码以及通过 Dagster Cloud 的run_evaluationjob 按数据集 revision 运行评测的配置方式。原文档还建议LLM 相关的 PR 打上team-posthog-ai请求专家评审但前提是先用各种用户 prompt尤其是刁钻的自测——评测与人工评审互为补充共同构成 PostHog AI 的质量闭环。七、把原则串起来一条真实的生产 Prompt 长什么样将以上所有原则合而观之TRENDS_SYSTEM_PROMPT 就是最完整的样板——它同时体现了结构化 XML 区块action_series、逐条指令series/math/breakdown 规则、边界规避大小写敏感名称、百分比双重缩放、9 组少样本示例覆盖 DAU/MAU、分位数、分组、多 breakdown、以及末尾的兜底规则默认 30 天、默认过滤内部用户、不得发明新事件。再叠加MaxChatOpenAI自动追加在末尾的项目/组织/用户上下文就构成了一个静态指令在前、动态上下文在后、缓存友好、约束明确、有例可循的完整生产级 Agent Prompt。结语与延伸阅读PostHog 的这套方法论可迁移性很强用统一封装类解决上下文注入与计费埋点用非嵌套 XML 标签 Mustache 把 prompt 变成可维护的代码资产用静态前、动态后的结构吃满 prompt caching再用 Braintrust 评测兜底。想继续深入建议按以下路径在仓库内阅读上下文注入与计费ee/hogai/llm.py主 Agent 的区块化 system promptee/hogai/chat_agent/prompts/base.pyPrompt 组装流水线ee/hogai/chat_agent/prompt_builder.py查询生成类 prompt 的深度范例ee/hogai/chat_agent/trends/prompts.py、ee/hogai/chat_agent/funnels/prompts.py评测体系ee/hogai/eval/README.md原文档末尾还附有 OpenAI 官方的 GPT-4.1 与 o3/o4-mini 提示词指南链接可结合阅读以获取通用最佳实践。【免费下载链接】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），仅供参考

PostHog 的 LLM Prompting 指南：从 Prompt 结构到生产级 Agent 的完整实践

相关推荐

阿里钱盾卸载了还弹验证？千牛登录验证链路与指纹环境治理

Screenpipe Commitments Pipe 实战指南：从散落上下文到一份可收敛的承诺收件箱

Rust 面向 NVIDIA GPU 的 nvptx64-nvidia-cuda 目标平台：工具链配置、PTX 约束与源码级原理

更多资讯

GaN驱动器集成电流隔离技术深度解析

Cua Driver 加密 Computer History 实战指南：安装、启用、审计与加密删除

WTK6900FC硬件级鼾声检测原理与工程落地指南

在 ESP32-P4 上运行 Slint：use cases 示例的 ESP-IDF 构建与部署实战

如何用 Mastra 的 Agent.stream() 流式输出代理响应并消费 textStream

Screenpipe SDK 的 Electron 集成：构建一个可运行的最小屏幕录制桌面应用

今日更新

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？