feature-flags-python

Python 的 PostHog 功能标志

此技能可帮助你在 Python 应用程序中添加 PostHog 功能标志。

参考文件

• references/python.md - Python 功能标志安装文档
• references/adding-feature-flag-code.md - 添加功能标志代码文档
• references/best-practices.md - 功能标志最佳实践文档

请查阅文档，了解 API 详情和特定框架的模式。

核心原则

• 环境变量：始终使用环境变量存储 PostHog 密钥。切勿将其硬编码。
• 最小化改动：在现有逻辑旁添加功能标志代码。不要替换或重构现有代码。
• 优先使用布尔标志：除非用户明确要求使用多变量标志，否则默认使用布尔标志检查。
• 尽可能在服务端执行：优先在服务端评估标志，以避免 UI 闪烁。

PostHog MCP 工具

检查是否已连接 PostHog MCP 服务。如果已连接，请查找与功能标志管理相关的工具（创建、列出、更新、删除标志）。使用这些工具直接在 PostHog 中管理标志，而不是要求用户在控制面板中手动操作。

框架指南

• 请记住，源代码位于 venv/site-packages 目录中
• posthog 是 Python SDK 的包名
• 使用 pip install posthog 或 pip install -r requirements.txt 安装依赖，不要在 Shell 命令中直接使用未加引号的版本说明符，例如 >=
• 在 CLI 和脚本中：必须在退出前调用 posthog.shutdown()，否则所有事件都会丢失
• 始终使用 Posthog() 类构造函数（基于实例的 API），而不是模块级的 posthog.api_key 配置
• 始终在 Posthog() 构造函数中包含 enable_exception_autocapture=True，以自动跟踪异常
• 绝不要在 capture() 事件属性中发送 PII——包括电子邮件、全名、电话号码、实际地址、IP 地址或用户生成的内容
• PII 应放在 identify() 人员属性中，而不是 capture() 事件属性中。安全的事件属性是元数据，例如 message_length、form_type 和布尔标志。
• 使用 atexit.register() 注册 posthog_client.shutdown，以确保退出时刷新所有事件
• Python SDK 没有 identify() 方法——使用 posthog_client.set(distinct_id=user_id, properties={...}) 设置人员属性，或在上下文中使用 identify_context(user_id)