LiteScope

Litescope

让 AI Agent 安全地操作生产环境中的 SQLite。 写入前先诊断，写入后可回退。支持 Cloudflare D1、Turso 和本地文件。

网站 · 路线图 · 赞助

让 Claude 修改你的 D1 数据库——如果结果不对，还能撤销。默认情况下，每次写入都会先进行试运行，准确显示影响范围，并且只需一次调用即可回退。

免费且开源（AGPL-3.0）——所有命令和所有集群操作均可自托管，无需许可证密钥。唯一收费的部分是由我们托管的仪表板。

---

为什么需要 SQLite 工具？

“它只不过是个文件——有什么可运维的？”

SQLite 过去确实只是本地开发用的小玩意儿。如今已不再如此。D1、Turso、 LiteFS 和 Litestream 将 SQLite 带入了大规模集群生产环境——数千个 数据库，每个租户一个。但工具支持一直没有跟上：

• sqlite3 假设只有一个数据库。 生产环境却有数千个。没有 pg_stat，没有 APM，也没有标准方式从外部查看数据库为何被锁定、WAL 为何不断膨胀，或哪个租户不再活跃。
• 嵌入式意味着无法观测。 SQLite 的优势恰恰在于没有服务器，但这也让你在生产环境中无从了解其内部状况。
• Agent 现在会写入你的数据。 没有 SQLite 工具是以 AI 会执行迁移为前提设计的。Litescope 则是。

Postgres 的每种问题都有成熟的工具。SQLite 却一个也没有——因此 Litescope 用一个二进制文件解决所有问题：集群可观测性、文件级超能力（细分排查 / 回退 / 抢救）、锁与 WAL 诊断，以及为 Agent 提供的安全接口。这些都是通用数据库客户端从架构上就无法做到的。

---

MCP——让 Claude 直接访问你的 D1

Claude Code——安装插件，即可获得 MCP 服务和五项技能（锁问题诊断、安全写入、迁移审查、集群扫描、损坏恢复），帮助 Agent 在遇到问题时学会如何使用这些功能：

/plugin marketplace add croc100/Litescope
/plugin install litescope@litescope

或者只安装 MCP 服务，一行命令（只读）：

claude mcp add litescope -- litescope mcp

启用写入和 D1（Litescope 仍会对每次写入进行试运行，并在应用前创建回退点）：

claude mcp add litescope \
  -e CLOUDFLARE_API_TOKEN=your-token \
  -e CLOUDFLARE_ACCOUNT_ID=your-account-id \
  -- litescope mcp --allow-writes

Cursor——一键安装： ➕ 将 litescope 添加到 Cursor （以只读模式安装；要启用写入，请在 mcp.json 中添加 --allow-writes 和 Cloudflare 环境变量）。

Claude Desktop / Windsurf / 任意 MCP 客户端——直接添加到配置文件中：

{
  "mcpServers": {
    "litescope": {
      "command": "litescope",
      "args": ["mcp", "--allow-writes"],
      "env": {
        "CLOUDFLARE_API_TOKEN": "your-token",
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id"
      }
    }
  }
}

也已列入 MCP Registry，名称为 io.github.croc100/litescope。

然后可以向 Claude 提出类似这样的请求：

"List my D1 databases"
"Show me the schema of the users table in d1://abc-123"
"Delete every inactive user from d1://prod-db-id"     ← dry-run first: shows the
                                                        exact blast radius before
                                                        you approve the write
"Undo that — put it back the way it was"              ← one-call revert via the
                                                        rewind_token from the write
"The deploy at 2pm broke something — rewind prod to 1:45pm"
"Diff my local dev.db against d1://prod-db-id and show me the migration SQL"

只读工具（始终可用）

工具	功能
litescope_d1_list	列出账户中的所有 D1 数据库（UUID、名称、DSN）
litescope_query	在任意 D1 数据库或本地 SQLite 文件上运行 SELECT 查询
litescope_schema	查看表、列和索引
litescope_health	检查损坏、WAL 膨胀和碎片化情况
litescope_diff	比较任意两个数据源的架构和行数差异
litescope_migrate_plan	生成迁移 SQL 和影响范围分析
litescope_migrate_diff	仅生成迁移 SQL（不含影响范围分析）
litescope_advise	性能分析：缺失索引、全表扫描
litescope_check	根据参考数据库验证备份
litescope_fingerprint	根据架构指纹对整个数据库集群进行分组
litescope_fleet_health	对整个数据库集群的故障进行分类
litescope_locks	诊断 database is locked / SQLITE_BUSY（静态和实时）
litescope_snapshot_list	列出本地数据库的时间点快照

litescope_query 会执行令牌预算控制——通过 max_rows 限制行数、使用 columns 指定列，并报告截断情况——因此，即使表很大，也不会撑爆 Agent 的 上下文窗口。

写入工具（--allow-writes）

工具	功能
litescope_query_write	执行可修改数据的 SQL——默认试运行，并准确报告受影响的行数和影响范围差异（D1 试运行在拉取的副本上测量）；应用更改时，先捕获撤销点（本地：快照；D1：Time Travel 书签），并将其作为 rewind_token 返回
litescope_write_undo	使用 rewind_token 一次调用即可撤销写入——适用于本地文件和 D1；令牌与生成它的数据库绑定
litescope_migrate_apply	应用迁移——可逆机制与 litescope_query_write 相同
litescope_autopilot	自动执行优化（ANALYZE、索引、VACUUM）——默认试运行
litescope_snapshot	对本地数据库进行时间点备份
litescope_restore	从快照恢复本地数据库
litescope_rewind	将 D1 数据库恢复到某个时间点（Time Travel）
litescope_d1_pull	将 D1 数据库下载到本地 SQLite 文件
litescope_d1_create	创建新的 D1 数据库
litescope_d1_delete	删除 D1 数据库（不可逆）

除非使用 --allow-writes 启动服务，否则写入工具处于关闭状态；每次写入默认都以试运行方式执行，且任何写入提交前都会自动捕获撤销点。完整的安全边界说明请参阅安全模型，了解各层防护的内容及其局限。

提示词和资源

除了工具，MCP 服务还提供提示词——例如 diagnose_locked_database、review_migration、safe_optimize 和 health_checkup 等预设工作流，可将上述工具串联成安全计划——以及 资源：数据库的架构、数据字典、实时健康状况和实时锁诊断。这些内容可供 Agent 读取，无需调用工具；底层文件每次发生更改时，还可订阅推送更新。使用 litescope mcp ./app.db 绑定数据库，或通过 litescope://schema/{source}、litescope://dictionary/{source}、 litescope://health/{source} 和 litescope://locks/{source} 指定任意数据源。

该服务实现了MCP 2026-07-28这一无状态版本：server/discover、 每个请求的协议元数据、resultType、缓存提示（ttlMs / cacheScope）以及 subscriptions/listen 流；同时还支持工具注释 （只读／破坏性提示）、结构化输出（structuredContent + outputSchema）和参数补全。该服务支持双时代协议：仍使用 initialize 握手启动的客户端会继续使用未作更改的 MCP 2025-06-18，因此 较旧的 MCP 客户端也能继续工作。

交互式视图（MCP Apps）

四个工具会通过 MCP Apps 扩展 (io.modelcontextprotocol/ui)，在对话中渲染交互式面板并返回结果：

工具	视图
litescope_locks	锁诊断器 — 判定结果、每项发现对应的精确 PRAGMA/DSN 修复方案、实时锁探测
litescope_health	健康面板 — 完整性、WAL、碎片情况、快照覆盖范围
litescope_query_write / litescope_migrate_apply	影响范围 — 每条语句影响的行数、架构影响、回退令牌
litescope_fleet_health	数据库集群网格 — 按最差状态优先展示每个数据库，并支持下钻查看

这些视图是编译进二进制文件的独立文档，不会从网络加载任何内容，因此适用宿主最严格的 CSP，数据库内容也不会离开 iframe。它们也绝不会写入数据：如果某个按钮会应用或撤销写入操作，就会将请求交还给对话，因为在嵌入式面板中点击按钮并不代表用户批准了生产环境写入。不支持该扩展的宿主会获得相同的文本结果。

远程 / 托管（Streamable HTTP）

默认情况下，litescope mcp 使用 stdio 通信。对于托管、远程或多客户端设置，请改用 Streamable HTTP 传输方式：

litescope mcp --http :7577 --http-token "$LITESCOPE_MCP_TOKEN"

向端点（默认为 /mcp）发送 JSON-RPC 消息。现代客户端以无状态方式提供服务 — 不使用会话 — 每个请求都携带自己的协议元数据和标准的 MCP-Protocol-Version / Mcp-Method / Mcp-Name 标头，变更通知则通过 subscriptions/listen 响应流传送。握手时代的客户端仍会通过 Mcp-Session-Id 标头获取会话，并使用 GET SSE 流。

公开此服务之前，请先做好安全防护：--http-token（或 LITESCOPE_MCP_TOKEN 环境变量）要求每个请求都携带 Authorization: Bearer <token>，而 --http-origin 会将浏览器 Origin 加入允许列表（始终允许 localhost），以防范 DNS 重绑定攻击。不设置令牌时，端点处于开放状态，服务会打印警告。

---

D1 — 命令行操作

Rewind — D1 时间旅行

# Restore to a previous point in time
litescope rewind d1://DB_ID --to "2h ago"
litescope rewind d1://DB_ID --to "yesterday"
litescope rewind d1://DB_ID --to "2024-01-15T10:30:00Z"

# List available restore points (30-day window + migration timestamps)
litescope rewind list d1://DB_ID

Pull / Push — 在 D1 与本地 SQLite 之间同步

# Download D1 → local (for inspection, backup, or diffing)
litescope d1 pull d1://DB_ID ./snapshot.db

# Upload local → D1 (seed a fresh database or restore from snapshot)
litescope d1 push ./seed.db d1://DB_ID
litescope d1 push ./seed.db d1://DB_ID --drop-existing

Migrate — 更改 D1 架构

# Diff local dev schema against live D1 — generate migration SQL
litescope migrate local.db d1://DB_ID

# Apply a migration directly to D1
litescope migrate apply d1://DB_ID migration.sql

Bisect — 找出哪个提交导致 D1 数据库出错

通过二分搜索 D1 时间旅行，精确定位查询开始返回错误结果的快照：

litescope bisect d1://DB_ID \
  --good "3d ago" \
  --bad now \
  --check "SELECT COUNT(*) FROM orders WHERE status = 'paid'" \
  --expect "gt:0"

检查 gt:0（大于）、lt:N、eq:N 或字面值。将范围缩小到条件首次失败的快照区间，然后即可检查或回退。

---

本地 SQLite

doctor — 一次性检查

litescope doctor app.db
litescope doctor app.db --deep            # exhaustive integrity_check
litescope doctor app.db --format html -o report.html

通过一条命令完成完整性检查、WAL/碎片健康检查、索引建议和架构检查。需要处理问题时以 1 退出 — 可将其用作 CI 质量门禁。

snapshot / restore — 时间点备份

litescope snapshot app.db                     # consistent VACUUM INTO copy
litescope snapshot app.db --label before-migration
litescope snapshot app.db --keep 7            # retain only the 7 newest
litescope snapshot list app.db
litescope restore app.db                      # restore the newest snapshot
litescope restore app.db --from <snapshot.db>

快照存储在同级 .litescope-snapshots/ 目录中。恢复操作会检查完整性，并先创建恢复前安全快照 — 这与 D1 通过时间旅行获得的“是否已备份？”安全网相同，适用于本地数据库和 Turso。

autopilot — 自动优化

litescope autopilot app.db                    # dry-run: show the plan
litescope autopilot app.db --apply            # apply the safe actions
litescope autopilot app.db --apply --aggressive
litescope autopilot --fleet litescope.fleet.yaml --apply

运行 ANALYZE + PRAGMA optimize，为缺失的外键添加索引，并且（使用 --aggressive 时）运行 VACUUM 并删除冗余索引 — 每项操作都会用通俗语言说明。默认执行试运行；每次实际变更之前都会自动创建快照。

locks — 诊断“数据库已锁定”

litescope locks app.db                        # static config diagnosis
litescope locks app.db --live                 # is a writer holding the lock now?
litescope locks app.db --watch                # stream lock-state changes
litescope locks app.db --timeline             # recorded contention history
litescope locks app.db --timeline --since 24h

检查日志模式、busy_timeout、锁定模式和 WAL 膨胀情况，并给出精确的 PRAGMA/DSN 修复方案。--live 会识别当前持有锁的进程。--watch 会将每次观测记录到本地历史存储；随后 --timeline 会将记录汇总成每个数据库的争用视图 — 显示数据库何时被阻塞、持续多久、哪些进程持有锁、等待时间百分位数，以及 WAL 检查点是否及时跟上。

diff — 架构和数据差异

litescope diff old.db new.db
litescope diff old.db new.db --format json
litescope diff local.db d1://DB_ID        # local vs live D1
litescope diff local.db turso://TOKEN@ORG/prod

migrate — 生成并应用迁移

litescope migrate before.db after.db --output migration.sql
litescope migrate apply prod.db migration.sql --dry-run
litescope migrate apply prod.db migration.sql --verify after.db

migrate apply 安全流程：预检完整性 → VACUUM INTO 备份 → 单个事务 → 验证外键 → 失败时自动回滚。

lint — 检查架构反模式

litescope lint app.db
litescope lint app.db --strict   # exit 1 on info findings too

规则：no-primary-key、untyped-column、not-strict、autoincrement-overhead、non-integer-pk。

schema — 检查架构 + ERD

litescope schema app.db
litescope schema app.db --erd    # Mermaid ER diagram

dump — 导出可移植的 SQL

litescope dump app.db -o backup.sql
litescope dump app.db --schema-only
litescope dump app.db --table users

import / export — 电子表格和 SQLite

litescope import sales.csv              # → sales.db, table "sales"
litescope import budget.xlsx            # first sheet → budget.db
litescope export shop.db --table orders -o orders.xlsx
litescope export shop.db --query "SELECT city, COUNT(*) FROM users GROUP BY city"

格式：CSV、TSV、JSON、Excel（.xlsx）。无需外部依赖。

monitor — 检测架构漂移

litescope monitor snapshot prod.db --output baseline.json
litescope monitor check prod.db --baseline baseline.json     # exits 1 on drift
litescope monitor watch prod.db --baseline baseline.json --interval 1h --webhook https://hooks.slack.com/...

serve — 本地 Web 仪表板

litescope serve                   # opens http://127.0.0.1:7575
litescope serve --config litescope.fleet.yaml

集群拓扑图、运行状况排查、架构指纹、交互式 ERD、带可视化查询构建器的分页数据浏览器、拖放导入，以及可视化差异面板——选择任意两个数据库，在应用更改前查看架构和行数的变化。完全在本地运行，无需账户。

---

集群

一次管理数百个数据库。专为使用 Turso 和 D1 的多租户应用打造。

# Discover all databases
litescope fleet discover turso --org my-org --token $TURSO_API_TOKEN
litescope fleet discover d1 --account $CF_ACCOUNT_ID --token $CF_API_TOKEN

# Triage the whole fleet
litescope fleet health
litescope fleet locks         # roll up "database is locked" contention, worst-first
litescope fleet fingerprint   # cluster by schema — find drift before it bites

# Stage a migration across the fleet
litescope fleet migrate migration.sql --dry-run
litescope fleet migrate migration.sql --canary 5
litescope fleet migrate migration.sql

---

CI — GitHub Action

在每个拉取请求上运行 Litescope——检查架构、与基准分支进行差异比较，并评论影响范围，避免未经审核的高风险迁移被合并。

- uses: croc100/Litescope@v1
  with:
    args: "lint app.db --strict"
    comment: "true"          # post the result as a sticky PR comment

args 可以是任意 Litescope 命令；当 Litescope 标记出问题时，作业会以非零状态退出，从而使检查失败。完整的 lint + diff 工作流请参阅 examples/github-actions/migration-ci.yml。

输入	默认值	说明
args	—	要运行的 Litescope 命令（必填）
version	latest	要安装的发布标签，或 latest
comment	false	将输出作为固定的 PR 评论发布
working-directory	.	要在其中运行的目录

---

安装

Homebrew

brew install croc100/tap/litescope

npm / npx — 适用于 JS 和 wrangler 用户，无需单独安装：

npx litescope doctor app.db
npm install -g litescope

Go 安装

go install github.com/croc100/litescope/cmd/litescope@latest

下载二进制文件

macOS、Linux、Windows — Releases。

---

远程数据源

DSN	提供方
./app.db 或 /path/to/file.db	本地 SQLite 文件
d1://DB_UUID	Cloudflare D1（环境变量：CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID）
d1://TOKEN@ACCOUNT_ID/DB_UUID	Cloudflare D1（显式凭据）
turso://TOKEN@ORG/DBNAME	Turso

---

定价 — 免费内容

工具免费。我们只对替你托管仪表板收费。

	免费（OSS，AGPL-3.0）	云端（付费）
所有 CLI 命令、MCP 服务、集群运维	✅	✅
litescope serve — 本地 Web 仪表板	✅	✅
在你自己的基础设施上自托管仪表板	✅	✅
由我们托管和维护的仪表板	—	✅
托管元数据导入、保留和告警	—	✅
组织身份验证、团队、SSO	—	✅
支持 SLA	—	✅

**界限很简单：软件及所有功能永久免费，并且可自托管。只有当你希望我们托管和运维仪表板，让你省去这些工作时，才需要付费。**没有任何功能需要许可证密钥才能使用。

托管方案请参阅 litescope-site.pages.dev/pricing。

---

许可证

Litescope 采用 AGPL-3.0 许可证。可免费使用、修改和自托管。如果你将其作为网络服务提供，AGPL 要求你公开自己的修改。组织可申请商业许可证（AGPL 例外 + 支持 SLA）——请参阅 COMMERCIAL.md 或发送邮件至 [email protected]。