preflight

---

为什么你的 AI 工具需要可观测性

你的 AI 编码助手每次会话都会做出数百个决定——读取什么、编辑什么、何时运行命令。但你看不到这些过程。你知道它很快，但它_高效_吗？你合并了一个 PR，但这花了多少钱？你修复了一个错误，但它之前是否陷入了循环？

Preflight 为 Agent 编码提供可观测性——记录 AI 编码助手工作时的操作、成本和效率。准确了解正在发生什么、花费多少，以及 AI 在哪些地方浪费时间。

从设计上以本地优先。 Preflight 完全在你的计算机上运行，默认不会向任何地方发送数据。localhost:7777 上的实时仪表板会显示你的会话，完全离线也能使用。只有在需要更多功能时，才连接 New Relic 账户——例如团队汇总、告警和跨会话历史记录。由你选择：仅本地、New Relic，或两者兼用。

---

演示

了解成本明细、效率评分、反模式检测和实时会话跟踪的实际效果。

---

你将获得

可见性

• 记录每项操作——文件读取、编辑、命令和搜索
• 实时会话仪表板——查看当前正在发生的事情
• 历史趋势——分析数周或数月内的模式

成本控制

• 美元支出跟踪——按会话、天和周统计
• 按模型和缓存细分——了解哪些模型成本最高，以及上下文复用效率如何
• 预算告警——在超支之前收到通知
• 成本预测——预测月度支出速度

效率洞察

• 效率评分——根据 AI 工作的直接程度，为每项任务评出 0–100 分
• 反模式检测——发现重复读取、盲目编辑和卡住的循环
• 个性化建议——优化你的 AI 工作流
• 每周辅导报告——将叙述式分析与你的历史基准进行比较

仪表板

• 本地仪表板——在 localhost:7777 查看实时会话，无需账户
• 8 个预构建的 New Relic 仪表板——几秒钟即可部署 (New Relic 模式)：
  • 概览——会话统计、成本摘要和常用工具
  • 个人视图——仅显示你自己的 30 天自我回顾数据
  • 会话详情——深入查看单个会话的工具调用
  • 团队视图——汇总开发者的成本和效率
  • 经理视图——团队高级指标，不包含工具调用内容
  • 采用情况与成本——采用进展、支出、MCP 使用情况，以及面向工程经理的开发者成果明细
  • 平台对比——Claude Code、Cursor、Windsurf 等平台对比
  • 安全审计——敏感文件访问的审计跟踪

---

快速开始

1. 安装

npm install -g @newrelic/preflight

使用 Smithery？ 从 Smithery MCP 注册表安装 Preflight 会自动配置 MCP 服务，但 Smithery 无法写入 Claude Code 钩子。安装后，请在终端运行 preflight install，或在 Preflight 配置中设置 "allowHeadlessInstall": true（或设置 NEW_RELIC_AI_ALLOW_HEADLESS_INSTALL=true），然后让 Claude Code 调用 nr_observe_install_hooks MCP 工具。默认情况下，该工具会拒绝执行，因为任何已连接的 MCP 客户端都可以调用它。启用该标志后，当 nr_observe_health 报告 setup_required: true 时，该工具会主动询问是否自动执行安装。然后重启 Claude Code 以启用监控。

2. 运行设置向导

preflight setup

向导默认使用本地模式——按提示一路按 Enter 键即可完成设置。它会将 Preflight 接入你的 AI 工具（钩子 + MCP 服务），并将配置写入 ~/.newrelic-preflight/。不到一分钟即可完成，无需账户。

使用 GitHub Copilot？ 向导还会询问是否安装 Copilot 钩子——选择是即可自动配置 Copilot CLI 和 VS Code Copilot Chat（钩子、MCP 注册，以及修复 VS Code 钩子重复捕获的问题），让 Copilot 也能像 Claude Code 一样记录工具调用和成本指标。你也可以随时单独运行 preflight install --copilot。详情请参阅 docs/ADAPTERS.md。

出现提示时，选择一种模式：

模式	作用	需要 New Relic 账户？
local (默认)	所有数据都保留在本机；可在 localhost:7777 查看实时仪表板	不需要
cloud	将遥测数据发送到 New Relic	需要
both	本地仪表板和 New Relic	需要

3. 开始编码

重启你的 AI 工具——钩子和 MCP 服务会在会话启动时加载。每次工具调用都会自动捕获。打开 http://localhost:7777 即可实时查看会话。

使用 Kiro？ 将 Preflight 添加为 Kiro Power，以使用 nr_observe_* 查询工具——请参阅文档了解安装步骤，以及如何在此基础上添加 自动工具调用捕获功能。

使用 Claude Code？ 你可以跳过上面的 npm 安装，改为将 Preflight 添加为 Claude Code 插件：

/plugin marketplace add newrelic-experimental/preflight
/plugin install newrelic-preflight@newrelic-preflight-marketplace

其他安装方式

Cursor — 添加到 Cursor 可通过一键深层链接安装 MCP 服务；之后运行 preflight setup 以捕获钩子。

Homebrew（macOS）：

brew tap newrelic-experimental/preflight
brew trust newrelic-experimental/preflight
brew install preflight

之后运行 preflight setup 以捕获钩子。

---

兼容工具

Claude Code • Amazon Kiro • Amazon Q Developer CLI • Factory Droid • OpenAI Codex • opencode • Kilo Code • Pi • GitHub Copilot • GitHub Copilot SDK • GitHub Copilot app • Google Gemini CLI • Cursor • Windsurf • Google Antigravity • Zed • Continue.dev • Cline

各平台的支持范围并不相同——有些平台会捕获所有内置工具调用；另一些平台（Zed、Continue.dev、Cline）只能看到发往 Preflight 自有 MCP 工具的调用。请参阅 ADAPTERS.md，了解各平台能够和无法观察到的内容，以及各平台的设置步骤。

---

连接 New Relic（可选）

本地模式本身已具备完整功能。连接 New Relic 账户即可解锁：

• 团队和经理仪表板，覆盖多位开发者
• 针对成本激增、效率低下和循环卡住的告警
• 跨会话历史记录、趋势和每周辅导报告

重新运行 preflight setup 并选择 cloud 或 both，或以非交互方式配置：

preflight install \
  --mode cloud \
  --license-key YOUR_LICENSE_KEY \
  --account-id YOUR_ACCOUNT_ID

EU 账户请添加 --eu。FedRAMP 账户请添加 --fedramp。日本账户请添加 --jp。

然后部署预构建的仪表板：

NEW_RELIC_API_KEY=NRAK-... NEW_RELIC_ACCOUNT_ID=12345 \
  preflight deploy-dashboards --all

你需要一个许可证密钥（用于遥测数据摄取）和你的账户 ID，以及一个用户 API 密钥（NRAK-…），用于部署仪表板和告警。有关告警、向其他后端导出 OTLP 和 Terraform 的信息，请参阅 ADVANCED.md。

运行 deploy-dashboards 之前不会有仪表板。 配置云模式后，遥测数据会立即发送到 New Relic，但不会自动创建任何仪表板——这需要单独执行上述步骤，并且需要不同的凭据（用户 API 密钥，而不是许可证密钥）。在运行该命令之前，没有可供查看的 UI。与此同时，你可以直接在 New Relic 的查询构建器中查询原始事件，例如：

SELECT * FROM AiToolCall SINCE 1 hour ago

deploy-dashboards 成功运行后，可在 New Relic 账户的仪表板部分找到这些仪表板。

数据摄取说明： 发送到 New Relic 的遥测数据会计入账户的数据摄取量。付费套餐适用标准摄取费率。请在 NR One → Data Management → Data Ingestion 中监控使用情况。

---

要求

必需

• Node.js v22 或更高版本（获取或使用 nvm）
• AI 编码工具（推荐使用 Claude Code，以获得最深入的集成）

可选

• New Relic 账户——仅 cloud/both 模式需要。跳过此项即可仅在本地运行（默认设置）。
• 用户 API 密钥（NRAK-…）——仅部署仪表板和告警时需要

---

其他命令

preflight doctor               # Run 10 diagnostic checks and print actionable fix commands
preflight validate             # Check config for syntax errors and unknown keys
preflight update               # Pull latest version, rebuild, and offer to restart a running dashboard (source installs only — npm installs: npm install -g @newrelic/preflight@latest; Homebrew installs: brew upgrade preflight)
preflight local                # List running --local dashboard processes and live --stdio MCP processes
preflight local --clean        # Kill orphaned --local processes and --stdio processes with a missing binary (prompts for confirmation)
preflight uninstall            # Remove hooks and MCP config (prompts with a summary first)
preflight uninstall --yes      # Skip the confirmation prompt (for scripts and CI)
preflight uninstall --daemon   # Remove only the background dashboard daemon

在 install/uninstall 中添加 --project，可将更改限定在当前目录。

WSL 用户： preflight setup 会询问你正在运行哪个 Claude Code。你也可以明确指定：

• --windows-cc — Windows Claude Code（桌面应用）；使用 wsl.exe 挂钩和 Windows 路径
• --linux-cc — 通过 npm 安装在 WSL 内的 Linux Claude Code

---

文档

• ADVANCED.md — 配置、仪表板、告警、Terraform
• SCORECARDS.md — 用于团队归属的 New Relic 评分卡规则
• ARCHITECTURE.md — 数据流、组件参考和运行模式
• ADAPTERS.md — 各平台集成机制、设置步骤和已知缺口
• FLEET_DEPLOYMENT.md — 使用托管设置和 MDM，将 Claude Code 插件部署到多台机器
• TROUBLESHOOTING.md — 常见设置和连接问题及其解决方法
• CONTRIBUTING.md — 开发、测试和提交 PR
• SECURITY.md — 安全指南和最佳实践
• PRIVACY.md — 数据收集清单和云端使用前检查清单

---

从源代码运行

开发、测试或运行最新的未发布版本：

git clone https://github.com/newrelic-experimental/preflight
cd preflight
nvm use              # Switch to Node v24
npm ci               # Install dependencies from the lockfile
npm run build        # Build the server and the dashboard bundle
npm link             # Register preflight on PATH

然后按常规方式运行 preflight setup。

---

许可证

Preflight 采用 Apache License 2.0 开源。

---

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解如何开始。加入 New Relic 社区，分享想法、提出问题或讨论功能。

---