FlutterSDK Telescope

Telescope

Flutter 的被动运行时检查器。供人阅读，也可由 AI Agent 查询。
通过 VM Service 扩展捕获 HTTP、日志、异常、debugPrint、数据库查询和 Magic 事件，并以 telescope:* CLI 命令以及面向 Claude Code 的 10 个 MCP 工具呈现。

文档 · pub.dev · 问题

---

为什么选择 Telescope？

别再把堆栈跟踪粘贴到 Claude 中了。让你的 Agent 自己读取。

调试正在运行的 Flutter 应用，一直以来都需要结合使用 print 语句、自定义日志接收器和网络代理，而它们各自只能呈现事情的一部分。出现问题时，你得把日志文件、Charles 捕获记录和 Flutter DevTools 窗口拼在一起，才能还原发生了什么。AI 工作流更糟：你从控制台复制堆栈跟踪，粘贴到 Claude Code，再复制失败的 HTTP 响应，粘贴回去，如此反复。

Telescope 打通了这一流程。 被动监听器和 14 个 VM Service 扩展会在启动时注册。每个 HTTP 请求、日志行、异常、debugPrint 调用、数据库查询和 Magic 框架生命周期事件都会写入环形缓冲区。CLI 命令（telescope:tail、telescope:requests）会将缓冲区内容流式传输给开发者；10 个 MCP 工具（telescope_requests、telescope_exceptions、telescope_tail 等）则将相同的缓冲区内容提供给 Claude Code、Cursor 和 Codex 等 AI 编码 Agent。无需复制粘贴，无需截图，也无需 SaaS 账户。仅用于开发；在调用处使用 kDebugMode 或 !kReleaseMode 守卫，即可在发布构建中通过 tree-shaking 移除整个子系统。

# One-shot self-bootstrap install (works from a fresh consumer)
flutter pub add fluttersdk_telescope
dart run fluttersdk_telescope telescope:install

安装命令会在缺少使用方 artisan harness 时为其搭建，运行 plugin:install fluttersdk_telescope，并修改 lib/main.dart，确保 TelescopePlugin.install() 在 Magic.init() 之前运行（对于原生 Flutter，则在 runApp 之前运行）。所有功能都受 kDebugMode 控制；发布构建会通过 tree-shaking 移除整个子系统。

安装后，使用方即可通过 ./bin/fsa 使用 artisan fast-cli（原生 AOT，温启动约 110ms）运行后续所有 Telescope 命令。dart run fluttersdk_telescope <cmd> 仍可作为较慢的备用方式（冷启动约 3 秒）。

功能

	功能	描述
👁	10 个监视器	LogWatcher、ExceptionWatcher、DumpWatcher、FramePerfWatcher，以及 6 个 Magic 专用适配器，涵盖 HTTP、模型、缓存、事件、门控和数据库查询
🤖	10 个 MCP 工具	telescope_requests、telescope_tail、telescope_exceptions、telescope_events、telescope_gates、telescope_dumps、telescope_queries、telescope_caches、telescope_frames、telescope_clear
🖥	11 个 CLI 命令	telescope:install、telescope:tail、telescope:requests、telescope:queries、telescope:caches、telescope:events、telescope:gates、telescope:dumps、telescope:frames、telescope:clear、telescope:files
🔌	适配器契约	TelescopeHttpAdapter（抽象类，包含 3 个方法）可接入任意 HTTP 客户端；内置适用于原生 Dio 的 DioHttpAdapter
📋	10 种记录类型	不可变类型：HttpRequestRecord、LogRecordEntry、ExceptionRecord、MagicModelRecord、MagicCacheRecord、EventRecord、GateRecord、DumpRecord、QueryRecord、FramePerfRecord
📡	VM Service 扩展	14 个扩展：ext.telescope.requests、.console、.exceptions、.events、.gates、.dumps、.queries、.caches、.frames、.clear、.pause、.resume、.files、.file。.console 和 .events 接受 since 并返回 cursor；.events 还接受 type，.console 还接受 logger
✨	Magic 集成	MagicTelescopeIntegration.install() 一次调用即可连接 Http facade 适配器以及模型、缓存、事件和门控监视器（随 magic_devtools 开发依赖提供）
🙈	凭据脱敏	HTTP 记录在缓冲前会进行屏蔽（遵循 Laravel Telescope 的模式）：Authorization、Cookie、X-Api-Key 请求头以及 password / token 风格的 JSON 键会显示为 ********；可使用 TelescopeRedaction.hide* 扩展列表
🧽	文本脱敏器	TelescopeRedaction.redactor 是宿主提供的 String Function(String) 钩子，会在插入时对每条日志、事件、异常和 HTTP 记录（包括负载键）运行。脱敏器抛出异常时会丢弃该记录；记录带有只读的 redacted 标志
💾	文件接收器	TelescopeFileSink.start(directory:, maxFileBytes:, maxFiles:) 会写入轮转的 JSONL 时间线，其中包含已脱敏的日志、事件和异常记录；可使用 telescope:files、ext.telescope.files 和 ext.telescope.file 读取。它只写入已脱敏的记录，写入失败时会停止运行
🔒	调用点门控	消费方的保护条件安装在调用点：kDebugMode（telescope:install 写入的内容）或 !kReleaseMode（也保留 profile 构建）；在所有平台上，release 构建都会通过 tree-shake 移除整个 telescope 分支
🔄	幂等安装	每次 registerExtension 调用都会通过 registerExtensionIdempotent 路由；支持热重启，重复注册不会触发 ArgumentError

快速开始

选项 A（推荐）：一键安装

添加依赖，然后通过 telescope 自带的 CLI 入口完成引导。无需预先配置 fluttersdk_artisan；telescope 的二进制文件内含 artisan 基础组件，因此全新的消费方也能完成安装：

flutter pub add fluttersdk_telescope
dart run fluttersdk_telescope telescope:install

该命令会在缺少消费方 artisan 框架时创建它（bin/dispatcher.dart + lib/app/_plugins.g.dart），运行 plugin:install fluttersdk_telescope，并修补 lib/main.dart，使 TelescopePlugin.install() 在 Magic.init() 之前运行（原生 Flutter 项目中则在 runApp 之前运行）。该操作是幂等的，可安全重复执行。

日常重复使用时，消费方的 ./bin/fsa（安装期间构建的 artisan 原生 AOT 二进制文件）可提供约 110 ms 的热启动时间：

./bin/fsa telescope:tail
./bin/fsa telescope:requests

dart run fluttersdk_telescope <cmd> 仍可作为速度较慢（冷启动约 3 秒）的备用方案，无需 AOT 包即可正常工作。

选项 B：手动配置

1. 添加依赖

# pubspec.yaml
dependencies:
  fluttersdk_telescope: ^0.0.4

2. 在 main.dart 中安装

在 Magic.init() 之前安装 Telescope（对于普通 Flutter 项目，则在 runApp 之前安装）。在调用处为每个安装调用添加模式守卫，这样整个工具分支就会在发布构建中被摇树优化掉：使用 kDebugMode（telescope:install 写入的内容），或 !kReleaseMode（也会保留 profile 构建，性能测量需要如此，magic_devtools 也使用此方式）。

import 'package:flutter/foundation.dart';
import 'package:fluttersdk_telescope/telescope.dart';
import 'package:magic_devtools/telescope.dart'; // magic_devtools dev_dependency (Magic-stack apps only)

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. Install Telescope core (auto-installs LogWatcher + registers VM extensions).
  if (!kReleaseMode) {
    TelescopePlugin.install();

    // 2. Opt-in watchers registered after install().
    TelescopePlugin.registerWatcher(ExceptionWatcher());
    TelescopePlugin.registerWatcher(DumpWatcher());
  }

  // 3. Magic-side adapters run AFTER Magic.init() because they resolve
  //    framework internals (Http facade, Gate manager) from the IoC container.
  await Magic.init(configFactories: [...]);

  if (!kReleaseMode) {
    // MagicTelescopeIntegration ships in magic_devtools (not magic core).
    // Add magic_devtools to dev_dependencies in pubspec.yaml.
    MagicTelescopeIntegration.install();
  }

  runApp(MyApp());
}

3. 注册 Artisan provider（MCP 工具）

在使用方的 bin/dispatcher.dart 中（由 dart run fluttersdk_artisan install 生成），执行 plugin:install fluttersdk_telescope 后，telescope 会通过 lib/app/_plugins.g.dart 自动发现。如果你要手动连接 providers，请将 FluttersdkTelescopeArtisanProvider() 添加到 baseProviders 列表中，这样 Claude Code 和其他 MCP 客户端就能看到这 10 个 telescope_* MCP 工具：

import 'package:fluttersdk_artisan/artisan.dart';
import 'package:fluttersdk_telescope/cli.dart' show FluttersdkTelescopeArtisanProvider;

exit(await runArtisan(
  args,
  baseProviders: [
    FluttersdkTelescopeArtisanProvider(),
    // ...other providers (DuskArtisanProvider, etc.)
  ],
));

监听器

监听器	捕获内容	自动安装？	备注
LogWatcher	所有 package:logging Logger 调用	是	由 TelescopePlugin.install() 自动安装。
ExceptionWatcher	通过 FlutterError.onError + PlatformDispatcher.onError 捕获未处理的异常	否	安装后调用 TelescopePlugin.registerWatcher(ExceptionWatcher())。这两个钩子都会链式保留之前注册的处理程序（Sentry、Bugsnag 等）。
DumpWatcher	debugPrint + print 输出	否	全局覆盖 debugPrint；链式保留之前的覆盖。仅在调试模式下激活。
MagicHttpFacadeAdapter	通过 Magic Http facade 传输的 HTTP 流量	否	通过 TelescopePlugin.registerHttpAdapter(MagicHttpFacadeAdapter()) 注册。需要 Magic 框架。
MagicModelWatcher	Magic Eloquent 模型 create、save、delete 生命周期事件	否	通过 TelescopePlugin.registerWatcher(MagicModelWatcher()) 注册。需要 Magic 框架。
MagicCacheWatcher	Cache.get / put / forget / flush（hit + miss + put + forget + flush 操作）	否	订阅 magic 端的 CacheHit / CacheMiss / CachePut / CacheForget / CacheFlush 事件。需要 Magic 框架。
MagicEventWatcher	通过 Magic Event facade 分发的事件	否	通过 TelescopePlugin.registerWatcher(MagicEventWatcher()) 注册。需要 Magic 框架。
MagicGateWatcher	Gate.allows / Gate.denies 授权检查	否	通过 TelescopePlugin.registerWatcher(MagicGateWatcher()) 注册。需要 Magic 框架。
MagicQueryWatcher	Magic SQLite + 远程数据库查询（sql、bindings、timeMs、connection）	否	订阅由数据库连接器分发的 magic 端 QueryExecuted 事件。需要 Magic 框架。
FramePerfWatcher	每帧的 build/raster/vsync-overhead 计时，并与 FlutterTimeline 块归因关联	否	通过 TelescopePlugin.registerWatcher(FramePerfWatcher()) 注册。每次读取时都会一并公开静态 livenessCounter。

MCP 工具

当使用者注册 TelescopeArtisanProvider 时，通过该提供程序公开（由 telescope:install 通过 lib/app/_plugins.g.dart 和 bin/dispatcher.dart 自动接线）。所有工具都通过 ext.telescope.* VM Service 扩展进行路由，并且需要 Flutter 应用正在运行。

工具	扩展方法	捕获内容
telescope_tail	ext.telescope.console	日志环形缓冲区（package:logging 记录）；按级别和数量限制筛选。
telescope_requests	ext.telescope.requests	HTTP 请求环形缓冲区（方法、URL、状态、耗时、标头、正文片段）。
telescope_exceptions	ext.telescope.exceptions	未捕获异常环形缓冲区（类型、消息、堆栈跟踪）。
telescope_clear	ext.telescope.clear	原子清除所有环形缓冲区。无参数。
telescope_events	ext.telescope.events	应用内事件环形缓冲区（Magic Event.dispatch 调用；事件类型和负载）。
telescope_gates	ext.telescope.gates	Gate 授权检查环形缓冲区（能力、结果、用户 ID、参数类型）。
telescope_dumps	ext.telescope.dumps	debugPrint 输出环形缓冲区（消息和时间戳）。
telescope_queries	ext.telescope.queries	数据库查询环形缓冲区（sql、bindings、timeMs、connectionName）。
telescope_caches	ext.telescope.caches	缓存操作环形缓冲区（操作：hit / miss / put / forget / flush；键；ttlMs）。
telescope_frames	ext.telescope.frames	逐帧性能环形缓冲区（build/raster/vsync-overhead/total-span 微秒数、区块归因），以及 livenessCounter。

CLI 命令

通过 TelescopeArtisanProvider.commands() 注册。运行 telescope:install 后，可通过以下三种方式调用任意命令：使用者的 fast-cli（./bin/fsa <command>，推荐）、Telescope 的独立 bin（dart run fluttersdk_telescope <command>），或使用者的 dispatcher 回退方式（dart run fluttersdk_artisan <command>）。

命令	用途
telescope:install	一次性引导：搭建使用者的 artisan harness，运行 plugin:install fluttersdk_telescope，并将 TelescopePlugin.install() 注入 lib/main.dart。通过 await Magic.init( 锚点检测 Magic-stack 应用，并在 Magic.init 之前注入；对于原生 Flutter，则回退到 runApp(。
telescope:tail	输出日志缓冲区。可使用 --level、--limit、--since <atUs> 和 --logger <name> 筛选；--json 每行输出一个 JSON 对象；--follow 会从返回的游标持续轮询，直到中断。
telescope:requests	输出 HTTP 请求缓冲区（分页）。
telescope:queries	输出数据库查询缓冲区（分页）。
telescope:caches	输出缓存操作缓冲区（分页）。
telescope:events	输出应用内事件缓冲区。可使用 --limit、--since <atUs> 和 --type <prefix> 筛选；--json 和 --follow 与 telescope:tail 中的用法相同。
telescope:gates	输出 Gate 授权检查缓冲区（分页）。
telescope:dumps	输出 debugPrint 转储缓冲区（分页）。
telescope:frames	输出逐帧性能缓冲区（分页）。
telescope:clear	原子清空所有缓冲区。
telescope:files	列出正在运行的文件接收器中的时间线文件；也可使用 --name=<file> 和 --offset=<n> 输出其中一个文件的行（0 或先前的 next；-v 显示下一个偏移量）。

followCursor 是两个 --follow 标志背后的纯 Dart 循环，已从 package:fluttersdk_telescope/cli.dart 导出。

示例

example/

原生 Flutter 应用（不使用 Magic 框架），用于测试所有与框架无关的捕获面：通过 Telescope Dio 拦截器捕获 HTTP 流量，通过 package:logging 捕获日志输出，通过 ExceptionWatcher 捕获未捕获异常，以及通过 DumpWatcher 捕获 debugPrint 输出。演示最精简的安装模式和应用内叠加仪表板。

cd example && flutter run -d chrome

架构

Telescope 采用以子系统为先的组织方式，位于 lib/src/ 下，每个目录负责单一关注点：

lib/
├── telescope.dart              # Single barrel, re-exports the full public API
├── cli.dart                    # Flutter-free codegen barrel (FluttersdkTelescopeArtisanProvider typedef, followCursor)
└── src/
    ├── watchers/               # TelescopeWatcher abstract contract + LogWatcher, ExceptionWatcher, DumpWatcher
    ├── adapters/               # TelescopeHttpAdapter abstract contract + DioHttpAdapter concrete impl
    ├── records/                # Immutable record types: HttpRequestRecord, LogRecordEntry, ExceptionRecord, etc.
    ├── extensions/             # registerAllTelescopeExtensions() aggregator + per-concern VM Service handlers
    ├── commands/               # TelescopeInstallCommand + 10 read/clear/files commands
    ├── telescope_store.dart    # 10-buffer ring store (singleton); Queue<T> per buffer + broadcast StreamController<T>
    ├── telescope_redaction.dart # credential lists + the host text redactor applied at insert
    ├── telescope_file_sink.dart # TelescopeFileSink: rotating JSONL timeline of redacted records
    ├── cursor_follow.dart      # followCursor, the loop behind --follow (exported from cli.dart)
    ├── telescope_plugin.dart   # TelescopePlugin.install() entry + registerHttpAdapter() + registerWatcher()
    └── telescope_artisan_provider.dart  # TelescopeArtisanProvider: 11 commands + 10 MCP tool descriptors

启动流程：

TelescopePlugin.install()
    ↓
Register default watchers (LogWatcher auto-installs)
    ↓
registerAllTelescopeExtensions()   # 14 ext.telescope.* VM Service extensions, idempotent
    ↓
Consumer registers TelescopeArtisanProvider (auto-wired by `telescope:install` via bin/dispatcher.dart + _plugins.g.dart)
    ↓
artisan mcp:serve   ->   10 telescope_* tools surface to MCP clients (Claude Code, Cursor, etc.)

每个具体的 watcher 和记录类型都是 final class。两个适配器契约（TelescopeWatcher、TelescopeHttpAdapter）是 abstract class，其 3 个方法的签名（name、install、uninstall）已冻结。Magic 侧的胶合代码（MagicHttpFacadeAdapter、MagicModelWatcher 等）依赖这些契约；任何签名变更都需要两个仓库协调升级。

对比

工具	功能	Telescope 的优势
Sentry Flutter	通过外部 SaaS 报告生产环境崩溃和性能数据	仅本地运行；仅用于调试；可通过 CLI 和 MCP 从你的 Agent 查询；无需 DSN 或 SaaS 账号
Talker / talker_flutter	应用内日志浮层、Dio 拦截器	VM Service 接口（可通过工具查询）；面向 AI Agent 的 MCP 服务；能感知框架的模型、缓存、事件和门控 watcher
Alice	应用内 HTTP 请求浮层界面	捕获 10 类缓冲区（不只是 HTTP）；被动运行（无需摇动设备打开浮层）；支持 CLI 流式传输；支持 AI Agent 访问；调试模式下可通过 tree-shake 移除
Flutter DevTools	官方的浏览器式检查器	支持编程访问（CLI 和 MCP），而不只是通过浏览器供人查看；采用环形缓冲的记录，可在迭代间查询；具备领域感知能力的（Magic）watcher
mcp_flutter	用于 AI 驱动 UI 交互（点击、滚动、快照）的 MCP 工具包	互补而非竞争：telescope 负责运行时遥测（HTTP、异常、查询）；mcp_flutter 负责 UI 自动化

AI Agent 集成

Telescope 是首个专注于运行时可观测性（HTTP、异常、查询、缓存）而非 UI 自动化的 Flutter MCP 服务。10 个 telescope_* 工具可让 Claude Code、Cursor、Codex 或任何兼容 MCP 的 Agent 直接读取每个运行时缓冲区：无需代理即可检查 HTTP 流量，无需 grep 输出即可读取日志，无需滚动浏览 DevTools 即可捕获异常。

一行命令安装 .mcp.json

telescope:install 会自动为你写入 .mcp.json。你也可以手动为任何兼容 MCP 的客户端进行配置：

// .mcp.json (project root) — Claude Code / Codex / Cursor / Goose / VS Code Copilot
{
  "mcpServers": {
    "fluttersdk": {
      "command": "./bin/fsa",
      "args": ["mcp:serve"],
      "cwd": "."
    }
  }
}

完成后，重启 MCP 客户端。10 个 telescope_* 工具（以及 substrate 的 artisan_* 工具）会自动显示在 /mcp 中。

使用前后对比

不使用 telescope	使用 telescope
堆栈跟踪出现在控制台中。你复制它，再粘贴到 Claude 中。Claude 询问触发问题的 HTTP 响应。你滚动查找、复制、粘贴。	Claude 调用 telescope_exceptions → 读取最近捕获的 500 个异常及其时间戳和堆栈跟踪。Claude 调用 telescope_requests → 读取匹配的 HTTP 记录。Claude 提出修复方案。
你执行热重载、重试，再次粘贴。	Claude 在每次迭代之间调用 telescope_clear。修复循环无需你介入即可完成。

典型的 Agent 会话

[agent] artisan_start { device: chrome }          // launch the app
[agent] <exercise the feature under inspection>
[agent] telescope_requests {}                     // inspect all HTTP calls made
[agent] telescope_tail { level: warning }         // filter logs to warnings and above
[agent] telescope_exceptions {}                   // check for any uncaught exceptions
[agent] telescope_queries {}                      // review DB queries and timings
[agent] telescope_clear {}                        // flush buffers before the next scenario
[agent] artisan_stop                              // tear down

对于在连接时读取结构化项目上下文的 Agent，规范入口是仓库根目录下的 llms.txt（也发布在 https://fluttersdk.com/telescope/llms.txt）。它以 Agent 可读的形式列出 watcher 接口、VM 扩展目录以及每个 MCP 工具的输入架构。

文档

完整文档和在线示例请访问 fluttersdk.com/telescope。

主题
快速入门	概览、要求、首次安装
观察器	全部 10 个观察器：设置、链式保留模式、Magic 适配器
MCP 工具	每个工具、每种输入架构、筛选参数
脱敏	凭据列表、TelescopeRedaction.redactor、redacted 标志
文件接收器	TelescopeFileSink、轮换、失败时关闭写入、telescope:files
缓冲区	TelescopeStore.setCapacity、TelescopeKind、atUs、limit 和 minLevel 语义
游标和筛选器	读取扩展中的 since / type / logger / cursor、--follow、followCursor

参与贡献

git clone https://github.com/fluttersdk/telescope.git
cd telescope && dart pub get
flutter test && dart analyze

基线为 497 项测试全部通过。新增行为需附带相应测试（红、绿、重构）。dart format lib/ test/ bin/ 不得产生差异，且 dart analyze 必须确认 lib/、test/ 和 bin/ 中没有任何问题。

提交拉取请求前，还请运行：

dart format lib/ test/ bin/         # zero diff
dart analyze                         # zero issues
dart pub publish --dry-run           # validate the publish archive

报告错误 · 请求新功能

灵感来源

Telescope 的灵感来自 Laravel Telescope，这是一款优雅的 Laravel 开发工具助手，可将每个请求、异常、日志、查询、缓存命中和事件记录到可查询的时间线中。我们将同样的模式移植到了 Flutter，并加入了两项适合 2026 年的功能：面向终端原生开发者的 CLI 优先界面，以及一个包含 10 个工具的 MCP 服务，让 AI 编码 Agent 可以直接读取时间线。

属于 Magic SDK 套件

Telescope 是 FlutterSDK Magic 套件中七个软件包之一，这是一个受 Laravel 启发的 Flutter 生态系统：

• magic — Laravel 风格的框架（门面、ORM、提供程序、控制器、路由）
• wind — 面向 Flutter 的 Tailwind 风格 className UI 基元
• fluttersdk_artisan — 纯 Dart 命令行 + MCP 基础层，telescope 在此基础上扩展
• fluttersdk_dusk — 通过 VM 扩展实现的端到端手势 / 快照驱动器
• fluttersdk_telescope（本软件包）— 通过 VM 扩展 + MCP 实现运行时可观测性
• magic_tinker — 连接到运行中应用的 REPL
• magic_starter — 身份验证 / 个人资料 / 团队脚手架

许可证

MIT 许可证，详情请参阅 LICENSE。

---

_{由 FlutterSDK 用心打造
如果 Telescope 为你节省了调试时间，请点个星标，帮助其他人发现它。}