mastro-hq/mastro-connect

│ openapi.yaml + auth.manifest.json └───────────────┘ ``` 设计理念： ### 四个关键组件 #### 1. 捕获扩展程序 —— [`extension/`](extension) 一个**通用的** MV3 Chrome 扩展程序。它没有针对特定连接器的代码：它只会解析 CLI 传给它的 `auth.manifest.json`。在执行 `mastro login` 期间，它会观察 目标标签页（通过 `chrome.cookies` 获取 cookie，通过 `webRequest` 获取 header，通过注入的页面桥接获取页面 fetch/XHR），根据 manifest 中的声明式规则判断何时捕获完成，序列化最小的凭证包，并将其 传回给 loopback receiver。点击其工具栏图标可查看实时状态。 它只会观察与活跃捕获会话相关的标签页；绝不会触碰 普通的浏览行为，且会话仅存在于内存中并很快过期。 #### 2. 核心 —— [`@mastro/core`](packages/core) 引擎。**broker** 运行捕获会话：它建立一个 localhost **receiver**，打开浏览器，等待凭证包，验证它，并通过 **credential store**（位于 `~/.mastro/` 的文件存储， 模式为 `0600`；该接口可插拔以支持 keychain/secret-manager 后端）写入最小凭证。它 还加载并验证每个 provider 的 **OpenAPI spec**。 #### 3. SDK —— [`@mastro/sdk`](packages/sdk) 重放层。给定一个已登录的连接器，它会根据 OpenAPI 操作和你的 CLI flag（query/path/body 参数，数组 `style`/`explode`， enum，默认值）构建请求，应用 `x-mastro-auth` 绑定（header、cookie、 每个请求的 `${uuid}` 值），针对应用的 分类 endpoint 解析动态过滤值（已缓存），通过正确的 **transport** 运行请求，并 映射响应。它还运行多步骤的 **workflow**。 #### 4. CLI —— [`@mastro/cli`](packages/cli) `mastro` 二进制程序。内置动词（`login`、`logout`、`status`、`providers`） 加上**根据 OpenAPI 操作生成的特定于 provider 的命令**。Flag 来自 操作的参数；它们的允许值来自 `schema.enum`； 帮助是自动生成的。CLI 是规范的一个轻量级、忠实的投影。 ## 为什么使用 OpenAPI（以及 `x-mastro-*` 扩展） 连接器的 API 被描述为一个**有效的 OpenAPI 3.1 文档**。标准的 工具链会对其进行验证和代码生成 —— `providers/depop/openapi.yaml` 可以 顺利通过 `redocly lint`。 OpenAPI 原生涵盖了每个 API 共有的接口：path、method、 多选字段（`enum`）、可重复参数（`array` + `style`/`explode`）， 以及认证清单。它真正**无法**表达的三件事 —— 而这些 正是逆向工程的部分 —— 存在于规范合法的 `x-mastro-*` 扩展中 （合规的验证器会忽略未知的 `x-` 键，因此该文档仍然是有效的 OpenAPI）： | 扩展 | 解决的问题 | | --- | --- | | `x-mastro-auth` | 捕获的凭证如何变成活跃请求：header/cookie 模板和**每次请求生成的值**（`${uuid}`、`${now}`）。 | | `x-mastro-resolve` | **动态 enum**，其有效值来自另一个 endpoint 的响应，或打包的参考数据（例如 Depop 的尺码/品牌分类）。 | | `x-mastro-replay` | OpenAPI 未建模的 transport 调优：浏览器模拟/浏览器代理、重试和重新捕获状态码、速率限制。 | | `x-mastro-workflow` | 不属于单个请求的多步骤有状态流程（上传 → 轮询 → 创建）。 | | `x-mastro-command` / `-result` / `-hidden` | CLI 投影：子命令名称、要打印的响应路径、隐藏仅元数据的 endpoint。 | 请参阅 [`docs/AUTHORING.md`](docs/AUTHORING.md) 获取完整参考。 ## 显著功能 这些是框架的通用功能，而不是 Depop 特有的技巧 —— 每个 连接器都可以免费获得它们。 ### 突破机器人防护 —— 浏览器代理 一些网站（如 Depop）位于 Cloudflare **托管挑战**（即“请稍候”的 JS 插页）之后。仅靠 TLS 模拟无法解决它。因此，当 provider 设置了 `x-mastro-replay.via_browser` 时，mastro 会在你**已经登录的浏览器标签页内**运行请求 —— Cloudflare 已经信任该标签页 —— 并将 JSON 传回。无需无头浏览器，无需挑战解决服务；它_本身就是_一个真实的 浏览器。 → [`docs/BROWSER-PROXY.md`](docs/BROWSER-PROXY.md) ### 人性化的过滤器 —— 分类解析 一个 flag 可以接受传输的 id _或_ 人类可读的标签，并根据应用 自身的过滤器元数据 endpoint（获取一次，缓存在 `~/.mastro/cache/` 下）或 打包的 JSON 文件进行解析。因此，`--sizes M` 会自动变成正确的内部 id， 并且 `mastro depop search --help` 会显示真实的、最新的选项。 ### 多步骤流程 —— workflow 一个命令可以是包含在它们之间流动的数据的声明式步骤序列 （带有索引配对的 `foreach`、`poll` 直到完成、二进制上传、按步骤 transport、 纯转换步骤以及类型化/派生的 body 字段）。Depop 的“上架商品”是 上传每张照片 → 轮询直到处理完成 → 创建列表，完全在 OpenAPI 文档中表达。`--dry-run` 会在不发送任何内容的情况下打印出每个计划好的请求 body。 → [`docs/WORKFLOWS.md`](docs/WORKFLOWS.md) ## Agent 技能 每个连接器都附带 **agent 技能** —— `SKILL.md` 操作手册，用于教导 AI agent 何时以及如何驱动它（前置条件、`--json` 格式、速率限制、 诸如“在花钱之前先进行 dry-run”的安全规则）。它们位于 provider 定义中（`providers//skills//SKILL.md`），因此针对 API 偏移的修复和记录它的操作手册可以在同一个 PR 中提交。 ``` mastro skills list # what's available mastro skills add depop # install into ./.claude/skills (project) mastro skills add amazon/search --global # ~/.claude/skills (everywhere) mastro skills add depop --dir .agents/skills mastro skills update # refresh everything installed here ``` 每次安装还会植入根 `mastro` 技能 —— 每个 provider 技能所构建的会话模型 约定（login、`status --json`、退出代码）。 已安装的技能带有 `.mastro.json` 来源戳记，以便 `update` 知道 它拥有什么。 由于技能是公共 GitHub 仓库中标准格式的 `SKILL.md` 目录，因此通用的技能安装程序（例如 `npx skills add`）也可以获取它们 —— `mastro skills add` 只是一条已经了解你已安装 provider 的便捷路径。 当网站的变化速度快于 npm 包的更新时，可以直接从 GitHub 拉取连接器的最新 定义（spec + 技能）： ``` mastro providers add depop # → ~/.mastro/providers/depop (pinned to a commit) mastro providers update # re-fetch everything you've added ``` 用户获取的 provider 会覆盖（shadow）打包的 provider，因此无需等待 发布即可应用修复。 ## 添加连接器 连接器是 `providers/` 下的一个文件夹，包含两个文件（加上文档）。**无需代码。** ``` providers// auth.manifest.json # what the extension captures in the browser openapi.yaml # the API surface — OpenAPI 3.1 + x-mastro-* extensions README.md # how it works, how it was reverse-engineered, drift notes reference/ # optional bundled lookup data (taxonomies) skills// # agent skills: SKILL.md (frontmatter: name, description) ``` 简短版本： 1. 登录应用，打开 DevTools → Network，执行你想自动化的操作。 2. 记录**认证工件**（cookie？bearer token？）、**base origin**、 **endpoint**（path、参数、header），以及它是否位于机器人防护之后。 3. 编写 `auth.manifest.json`（捕获规则）和 `openapi.yaml`（API，包含 用于 auth/replay/动态过滤器的 `x-mastro-*`）。 4. `mastro providers` 应该列出它；`mastro --help` 应该显示其 命令。使用任何 OpenAPI 验证器验证 spec。 完整演练：**[`docs/AUTHORING.md`](docs/AUTHORING.md)**。实践示例： **[`providers/depop`](providers/depop)**。 通过 `MASTRO_PROVIDERS=/path/to/dir` 将 mastro 指向仓库外的 provider。 ## 项目布局 ``` mastro-connect/ ├── packages/ │ ├── core/ @mastro/core — schemas, OpenAPI loader, registry, │ │ credential store, broker, receiver, proxy server │ ├── sdk/ @mastro/sdk — connector, transports, taxonomy resolver, │ │ workflow runner, templating │ └── cli/ @mastro/cli — the `mastro` binary ├── extension/ generic MV3 capture + browser-proxy runtime (plain JS, type-checked) ├── providers/ │ ├── depop/ first connector (search, me, list) + skills │ └── amazon/ search, detail, Buy Now order + skills ├── skills/ │ └── mastro/ the root agent skill (session model, conventions) ├── bin/ node launcher shim for npx/global installs └── docs/ AUTHORING · BROWSER-PROXY · WORKFLOWS ``` 全面采用 Bun + TypeScript（严格模式；扩展 JS 通过 `checkJs` 验证）。 从检出中，一切都直接在 Bun 上运行 —— 唯一的构建步骤是 `bun run build`，它将 CLI 打包到 `dist/` 中以用于 npm 包。 ``` bun test # run the test suite bun run typecheck # type-check everything (TS + extension) bun run mastro … # run the CLI from source ``` ## 文档 | 文档 | 涵盖内容 | | --- | --- | | [`docs/AUTHORING.md`](docs/AUTHORING.md) | 构建连接器：manifest + OpenAPI + `x-mastro-*` 参考。 | | [`docs/BROWSER-PROXY.md`](docs/BROWSER-PROXY.md) | 请求如何在真实的浏览器标签页内运行以击败托管挑战。 | | [`docs/WORKFLOWS.md`](docs/WORKFLOWS.md) | 多步骤流程：步骤、`foreach`、`poll`、dry-run。 | | [`extension/README.md`](extension/README.md) | 捕获扩展程序内部机制。 | | [`providers/depop/README.md`](providers/depop/README.md) | Depop 连接器，端到端。 | ## 道德与范围 mastro 专为合法的个人自动化而构建 —— 在_你_的授权下，驱动_你_已登录的 应用。 - 它****在当前用户已经控制的浏览器会话中运行。 它不会绕过授权或同意，也绝不会输入或存储 密码。 - 它只持久化重放所需的**最小**凭证，并以 严格的权限存储在本地；所有的 token 和 cookie 在所有日志中都会被脱敏。 - 在存在且合适的官方 API 的情况下，请优先使用官方 API。非官方 API 是带有 偏移检测的操作契约 —— 而不是稳定的保证，也不是 滥用服务的许可证。 - 尊重每个服务的服务条款和速率限制。你对 如何使用它负责。 ## 贡献 欢迎贡献 —— 尤其是新连接器。一个优秀的连接器 PR 包括经过验证的 `openapi.yaml`、`auth.manifest.json`、记录 逆向工程和偏移症状的 `README.md`，并且**不提交凭证或 未经脱敏的 HAR**（`.gitignore` 会保护明显的情况 —— 请仔细检查）。 在打开 PR 之前，请运行 `bun test` 和 `bun run typecheck`。 ## License [MIT](LICENSE) © Giulio Colleluori