PostHog Desktop 开发指南从源码运行桌面/移动应用与 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/posthogPostHog Desktop 是 PostHog 官方桌面端与移动端应用及其底层 Agent 框架的源码所在地。本篇基于 products/desktop/README.md 展开覆盖从零搭建开发环境、pnpm dev的多进程开发模式、连接本地 PostHog 实例的 OAuth 配置并结合 package.json、mprocs.yaml 等仓库源码剖析实际脚本行为与多进程编排细节。读完你可以独立把 Desktop 开发环境跑起来并理解每个开发命令背后的调用链。项目定位与目录PostHog Desktop 的源码位于 PostHog 主仓库的products/desktop目录下没有独立的 clone如果你已经检出了 posthog 主仓库直接cd products/desktop即可。它是一个独立的 pnpm workspace拥有自己的 lockfile 和 Node 版本见 .node-version值为22。仓库官方给出的目录结构如下原文档骨架products/desktop/ ├── apps/ │ ├── code/ # Electron desktop app (React, Vite) │ ├── mobile/ # React Native mobile app (Expo) │ └── web/ # Web host (cloud-only) ├── packages/ │ ├── agent/ # TypeScript agent framework │ ├── core/ # Shared business logic │ ├── ui/ # Shared React UI │ ├── workspace-server/ # Local filesystem, git, and process services │ └── platform/ # Host capability interfaces └── docs/ # Development and operational guides从源码结构看packages/下实际还包含更多职责细分的包例如agent-shadow、api-client、di依赖注入、electron-trpc、enricher、git、harness、host-router、host-trpc、quick-ask、shared、workspace-client等。这些包由 pnpm-workspace.yaml 的packages: [apps/*, packages/*, tooling/*, tools/*]统一纳入工作区管理。前置条件与环境搭建前置要求Node.js 22根 package.json 中engines声明为22.19.0且.node-version固定为22pnpm 10.23.0packageManager字段锁定了精确版本pnpm10.23.0工作区入口package.json通过preinstall脚本执行node scripts/enforce-pnpm.mjs强制使用 pnpm禁止 npm/yarn 直接安装。Setup 步骤原文档给出的完整安装流程# Install pnpm if you havent already npm install -g pnpm # Install dependencies for all packages pnpm install # Optional: copy environment config # Only needed for code signing (APPLE_*) or PostHog analytics (VITE_POSTHOG_*). # The app runs fine in dev without it. cp .env.example .env.env是可选的不配置也能正常开发。查看 .env.example 可知它包含两类变量变量前缀用途APPLE_*APPLE_CODESIGN_IDENTITY、APPLE_TEAM_ID、APPLE_ID、APPLE_APP_SPECIFIC_PASSWORD、APPLE_CODESIGN_CERT_BASE64、APPLE_CODESIGN_CERT_PASSWORDmacOS 代码签名与发布VITE_POSTHOG_API_KEY/VITE_POSTHOG_API_HOST/VITE_POSTHOG_UI_HOST应用自身的 PostHog 分析/功能标志客户端注意VITE_POSTHOG_API_HOST控制的是分析/功能标志客户端而不是数据后端。数据后端由登录时选择的 region 决定详见 docs/LOCAL-DEVELOPMENT.md。另外pnpm install的postinstall钩子会自动执行bash scripts/ensure-phrocs.sh --update本地bin/phrocs二进制会与最新phrocs-latestrelease 的校验和比对不一致时重新下载离线或 CI 环境跳过。开发模式运行pnpm dev 与 phrocs 多进程编排默认情况下pnpm dev使用 phrocsPostHog 自研的进程运行器类似 mprocs并行启动 agent 与桌面应用并读取 mprocs.yaml 配置。原文档说明的核心命令# Run both agent (watch mode) and code app in parallel pnpm dev # Or run them separately: pnpm dev:agent # Run agent in watch mode pnpm dev:code # Run code app # Use mprocs instead of phrocs pnpm dev:mprocs从源码看命令的真实调用链对照根 package.json 的 scripts 字段这些命令的实际执行序列是dev→node scripts/dev-with-skills.mjs pnpm dev:app先用 skills 同步脚本包装一层dev:app→pnpm build:deps bash scripts/ensure-phrocs.sh bin/phrocs --config mprocs.yaml即先通过 turbo 构建posthog/code的所有上游依赖包build:deps为turbo build --filterposthog/code^...确保 phrocs 二进制存在后再按mprocs.yaml拉起全部进程dev:agent→pnpm --filter agent dev只跑 agent watch 模式dev:code→node scripts/dev-with-skills.mjs pnpm --filter code startdev:mprocs→ 同样先build:deps但用社区版mprocs替代 phrocs 运行mprocs.yaml 定义了 8 个可启动进程及依赖关系code桌面应用声明了depends_on: [agent, git, enricher, platform]即这 4 个后台服务先就绪后才启动 Electron 主进程。其余进程默认不自动启动autostart: false按需拉起进程说明codeElectron 桌面应用--filter code run start前缀wait-for-electron-exit.mjs处理退出等待agent/git/platform/enricher各 packages 下的 watch 模式开发进程storybookcode 包的 Storybook手动启动mobile-ios移动端 iOS 调试进程手动启动chromium-logtail -F ~/.posthog-code/logs-dev/chromium.log实时查看 Chromium 日志web/web-playwright/desktop-playwrightWeb host 开发、Web e2e、桌面 e2e需先package再test:e2e注释说明 e2e fixture 会启动out/下的打包应用侧边栏默认按layer维度分组default_group: layer分组顺序为Application、Packages、Tools按g键可切换/关闭分组。常用工作区命令除开发命令外package.json 还暴露了一批常用脚本可随需使用命令作用pnpm buildturbo build全量构建pnpm packageturbo build pnpm --filter code package构建并打包桌面应用pnpm test/pnpm test:bun/pnpm test:vitest分别以 turbo、buncore/cli、vitestcode/electron-trpc方式跑测试pnpm test:e2e/pnpm test:e2e:web桌面端 / Web 端 Playwright e2epnpm typecheckturbo typecheckpnpm lint/pnpm formatBiome 检查与格式化pnpm boundariesnode scripts/check-host-boundaries.mjs校验宿主能力边界pnpm knip用 knip 检测无用依赖/导出配置见 knip.jsonpnpm rebuild:sqlite-node/pnpm rebuild:sqlite-electron分别针对 Node / Electron 重新编译 better-sqlite3 原生模块连接本地 PostHog 实例如果想让开发版 Desktop 连接你本地跑起来的 PostHoghttp://localhost:8010完整流程在 products/desktop/docs/LOCAL-DEVELOPMENT.md 中。要点如下在 PostHog 中注册 OAuth 应用。两种方式任选在主仓库执行python manage.py generate_demo_data自动生成一个预配置好的 OAuth 应用或手动到http://localhost:8010/admin/posthog/oauthapplication/创建Client ID 必须为DC5uRLVbGI02YQ82grxgnK6Qn12SXWpCqdPb60oZ该值即源码 packages/shared/src/oauth.ts 中导出的POSTHOG_DEV_CLIENT_ID常量Client type 为Public授权类型Authorization codeRS256Redirect URIs 包含http://localhost:8237/callback与http://localhost:8239/callback。配置 RSA 密钥OAuth token 签名需要OIDC_RSA_PRIVATE_KEY可从主仓库.env.example中拷出或用openssl genrsa 2048生成新的。连接流程在登录界面选择Local developmentlocalhost:8010或Dev Cloudapp.dev.posthog.dev应用打开对应 host 完成 OAuth 授权并选择项目/组织级别PostHog 回跳到 Desktop 的 localhost callback 端口。开发构建中存在两个独立的开发 region 值dev本地 8010使用POSTHOG_DEV_CLIENT_ID和dev-cloudapp.dev.posthog.dev专用 client IDAgent 请求走https://gateway.dev.posthog.dev。生产构建只显示 US/EU CloudCustom region指向任意自托管实例只出现在开发/测试构建中。region → OAuth client ID 的映射逻辑可在 packages/shared/src/regions.test.ts 的测试用例中得到印证如getOauthClientIdFromRegion(dev)返回POSTHOG_DEV_CLIENT_ID。LOCAL-DEVELOPMENT.md 还覆盖了大量排障细节invalid_scope/ Couldnt check Desktop access需要用seed_oauth_app_scopes为应用补上llm_gateway:read特权 scope 上限、Redirect URI mismatch、431 错误localhost cookie 过大、以及通过posthog.featureFlags.override(...)在渲染进程控制台一次性覆盖功能标志等遇到对应报错时可按图索骥。开发调试辅助脚本README 列出的scripts/工具脚本脚本说明scripts/clean-posthog-code-macos.sh从 macOS 删除全部 PostHog 应用数据缓存、偏好设置、日志、保存状态加--app参数会同时删除 /Applications 下的 PostHog.appscripts/test-access-token.js通过调用 API 端点验证 PostHog OAuth access token。用法node scripts/test-access-token.js token project_id [region]从源码结构看scripts/目录还有更多开发辅助工具例如use-local-posthog.mjs把.env中VITE_POSTHOG_*改写为本地实例让本地创建的功能标志在 dev 构建中生效详见 LOCAL-DEVELOPMENT.md 的 Feature flags in local dev 一节、electron-cdp.mjs以 CDP 模式启动 Electron配合pnpm app:cdp使用、dev-with-skills.mjspnpm dev入口包装处理 skills 来源选择、wait-for-electron-exit.mjs与pnpm-run.mjsmprocs.yaml 中各进程 shell 实际调用的两个辅助脚本。依赖工作区的关键细节products/desktop/pnpm-workspace.yaml 对跨包版本一致性做了大量约束理解它有助于排查依赖类构建问题catalog统一了核心依赖版本react 19.2.6、typescript ^5.5.0、hono ^4.6.14、tanstack/react-query ^5.100.14、trpc/* ^11.17.0、inversify ^7.10.6依赖注入容器以及earendil-works/pi-* 0.84.1agent 相关 SDK等overrides强制单 React 运行时、去重 zod 4.x、把vite换成 rolldown 分支以提升 dev 启动速度并针对多个安全通告锁定了补丁版本protobufjs、axios、hono、node-forge、simple-git等onlyBuiltDependencies白名单了允许执行构建脚本的原生模块electron、better-sqlite3、node-pty、parcel/watcher等patchedDependencies则对node-pty、app-builder-lib、react-hotkeys-hook打了本地补丁还设置了minimumReleaseAge: 100807 天最小发布年龄以规避新发布包的风险例外清单集中在 agent/claude SDK 等快速迭代依赖上。文档索引与进一步阅读README 给出的官方文档导航均为仓库内相对路径文件说明docs/README.md开发、架构、测试、运维与功能指南总索引apps/code/README.md桌面应用构建、签名、分发与 workspace 配置apps/mobile/README.mdExpo 环境搭建、EAS 构建与 TestFlight 部署AGENTS.md架构、代码风格与测试规则的事实来源CONTRIBUTING.md贡献指南此外 docs/ 目录下还有ARCHITECTURE.md、TESTING.md、TROUBLESHOOTING.md、PERFORMANCE.md、LOCAL-DEVELOPMENT.md等专题文档涉及架构分层、测试策略与性能分析时可直接查阅。小结PostHog Desktop 的开发体验核心可以概括为三点一是一个独立的 pnpm workspaceNode 22 pnpm 10.23.0engines/preinstall双重强制二是pnpm dev背后由phrocs 驱动的 8 进程编排桌面应用依赖 agent/git/platform/enricher 四个后台包进程先行就绪三是基于 OAuth 的本地/云端连接模型dev、dev-cloud、custom三个开发 region 各有独立的 client ID 与回调端口约定。配合scripts/下的调试工具与 docs 目录的专题文档足以支撑从日常开发到 e2e 测试、再到本地联调完整 PostHog 后端的全链路工作。【免费下载链接】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），仅供参考