Backlot

Backlot

在本地运行企业 SaaS API。

Backlot 是 Slack、Gmail、Google Drive、GitHub、Jira、Notion、S3 及其他企业 API 的本地模拟器。它基于由你控制的确定性语料，复现集成必须处理的响应结构、分页、身份验证、错误和逐文档访问控制——让你无需供应商账号、无需OAuth 审批、无需在 CI 中保存密钥，也无需联网，即可使用官方供应商 SDK 进行构建和测试。

60 秒快速体验

pip install backlot
backlot import --bundled   # a corpus ships with the package; nothing to fetch or write
backlot serve              # every supported API, at http://127.0.0.1:8000

只需更改一个基础 URL，即可让官方 SDK 指向它：

from slack_sdk import WebClient  # pip install slack_sdk

slack = WebClient(token="admin-service-token", base_url="http://127.0.0.1:8000/slack/api/")
print(slack.conversations_list()["channels"])

同一调用在生产环境中访问 Slack，在开发环境中访问 Backlot。Backlot 提供数据和凭据；你的代码仍使用供应商的请求与响应约定。

测试也可以在空闲端口上启动自己的服务，无需事先启动或事后清理：

import backlot
from slack_sdk import WebClient

with backlot.serve() as s:  # no arguments: a tiny hello-world corpus
    slack = WebClient(token=s.token, base_url=f"{s.base_url}/slack/api/")
    channels = slack.conversations_list()["channels"]

让你的编码 Agent 即刻运行 Backlot

此仓库本身就是一个插件市场，因此无需克隆仓库，也无需先运行 pip install，即可安装Agent 技能。或者，将所有资源作为 MCP 工具交给 Agent：如果服务尚未运行，backlot mcp 会启动它，并通过 stdio 提供所有资源；添加 --user <email> 后，服务会以该用户身份响应。

claude plugin marketplace add brekkylab/backlot && claude plugin install backlot@brekkylab
codex plugin marketplace add brekkylab/backlot && codex plugin add backlot@brekkylab
pip install "backlot[mcp]" && claude mcp add backlot -- backlot mcp   # every source as MCP tools

并使用这样的提示词：

模拟我们的 Slack 工作区，在 #incidents 频道中创建三条消息，启动服务，然后告诉我 conversations.history 对该频道实际返回了什么。

为什么不用模拟对象？

手写模拟对象会返回你的代码已经预期的响应。Backlot 实现的是集成的另一端，因此会暴露模拟对象可能掩盖的假设——当你需要测试的是 API 的行为，而不只是单个响应的内容时，就该使用它。

❌ 手写模拟对象	✅ Backlot
针对测试的响应字典	通过 HTTP 提供符合供应商结构的响应
通常只覆盖正常路径	分页、验证、身份验证和符合供应商结构的错误
自定义测试辅助工具	官方供应商 SDK 和常规 HTTP 客户端
几乎没有或完全没有身份模型	自动生成的用户、令牌、组和文档 ACL
测试之间的固定数据会逐渐偏离	一套确定性语料，可在本地和 CI 中共享
每个 API 的模拟方式各不相同	所有 API 由同一进程提供

服务内容

每个数据源都通过一个本地端口提供服务，并挂载在各自 SDK 所需的路径前缀下；所有数据源读取同一个 SQLite 语料库。

语料库定义事实：消息、文件、问题、作者、时间戳、线程、评论、标签和读者。Backlot 会据此派生稳定的 ID、用户、群组和令牌，因此每次运行提供的都是相同记录、相同的 ACL 筛选视图和相同页面。

它模拟所支持 API 中有文档说明的子集，而非每个供应商的所有端点。逐端点对照表列出了支持情况；已实现的端点若与真实 API 不一致，就是一个缺陷。

服务	基础路径	官方 SDK 示例
Slack	/slack/api	slack.py
Microsoft Teams	/msgraph/v1.0	msteams.py
Gmail	/gmail/v1	gmail.py
Google Drive（Docs、Sheets、Slides）	/drive/v3 /docs/v1 /sheets/v4 /slides/v1	gdrive.py
GitHub	/github	github.py
Jira	/atlassian/rest/api	jira.py
Confluence	/atlassian/wiki/rest/api	confluence.py
Notion	/notion/v1	notion.py
Linear	/linear/graphql	linear/
HubSpot	/hubspot	hubspot.py
Fireflies	/fireflies/graphql	fireflies.py
Amazon S3	/s3	s3.py

路线图见跟踪议题——如需支持某个数据源，请在那里提出。

适用场景

• 🔌 构建或升级集成。无需账户即可获取真实 API 返回的游标、分页结构和错误响应体。
• 🧪 测试并持续验证。在笔记本电脑和 CI 中使用同一份夹具，无需密钥，也不会出现不稳定的测试。语料库中的每位用户都有一个令牌，因此你也可以断言一个调用者的文档绝不会传给另一个调用者。
• 🤖 评估 RAG 流水线或 Agent。每次运行都使用相同的语料库、相同的 ID 和相同的答案，因此分数变化就意味着代码发生了变化。Slack 也支持写入，因此可以在这里运行会发帖、编辑或添加表情回应的 Agent，并根据其实际操作进行评分——一个端点会报告操作结果，另一个端点会将语料库恢复原状，以供下次运行使用（docs/write-overlay.md）。
• 🐛 复现无法查看的数据中的缺陷。别人工作区中的文档导致你的解析器出错。编写一份结构相似的文档，提供服务，并保留失败的测试。

使用自己的语料库

随附的语料库涵盖所有受支持的服务，但主要工作流是提供你自己的测试环境：一个 JSONL 文件，每行一份源文档。

{"source_type":"slack","channel":"incidents","author_email":"[email protected]","created":"2026-02-10T18:00:00Z","content":"Anyone seeing 502s from the gateway?","replies":[{"content":"Looking now.","author_email":"[email protected]","created":"2026-02-10T18:00:40Z"}]}

backlot import my-corpus.jsonl --dry-run   # validate against each service's schema, touch nothing
backlot import my-corpus.jsonl && backlot serve

每个导入的身份都会获得确定性凭据，可通过 GET /_meta/users 查看；使用另一位用户的令牌发送相同请求，即可测试该调用者获准查看的内容。准备语料库介绍了架构、用户名单、分片语料库和公开数据集；身份验证与令牌介绍了各服务的身份验证方式。

示例

用途	可运行示例
📦 官方供应商 SDK，每项服务一个脚本	examples/using-official-sdk/
🔗 供 Agent 使用的 MCP 工具：backlot mcp，或将供应商自带的 MCP 服务指向 Backlot	examples/using-mcp-with-agents/
🦙 将其加载为文档，使用官方 LlamaIndex 读取器	examples/using-llamaindex-readers/
🐍 通过 fsspec 文件系统，使用 pandas、pyarrow 或 dask 读取	examples/using-fsspec/
🗂️ 通过 mirage 的虚拟文件系统，使用 ls、cat 和 grep 读取	examples/using-mirage/
📥 从 JSONL 文件加载你自己的语料库	examples/bring-your-own-corpus/

文档

Backlot 提供的所有数据源及其各自的所有端点	docs/supported-sources.md
构建语料库和公共数据集	docs/corpus.md
身份验证方案和令牌	docs/auth.md
衡量 Backlot 与真实 API 的一致性	docs/fidelity.md
写入操作及其目标位置	docs/write-overlay.md
所有 BACKLOT_* 设置和 Docker	docs/configuration.md
使用情况遥测：收集原因、发送内容以及关闭方法	docs/telemetry.md
声明和商标	NOTICE.md

贡献

请参阅 CONTRIBUTING.md。与真实 API 保持一致是核心目标，因此任何偏差都是错误——请对照真实服务进行衡量，并提交一个在修复前会失败的测试。

Backlot 的存在离不开所有贡献者的支持。

许可证

Apache-2.0。NOTICE.md 说明了早期版本采用的 MIT License。