PhantomAPI

Compile any software into an API.

你公司的 ERP 没有 API。你的 CRM 的 API 要加钱才开放。那个 2009 年的内部系统永远不会有 API。

你不需要 API 文档。你需要一个编译器。

phantom learn https://your-legacy-crm.example

浏览器打开，你演示一遍：搜索客户、打开详情、修改标签、导出报表。PhantomAPI 同步分析四层信息 —— DOM/无障碍树、网络请求、应用状态、操作语义 —— 编译出 Typed Action Graph：

Generated capabilities:
  customer.search(query)
  customer.get(id)
  customer.update_tags(id, tags)
  report.export(type, dateRange)

然后：

phantom serve

✓ REST API + OpenAPI 3.1        http://localhost:7777
✓ MCP server                    phantom mcp
✓ TypeScript SDK                phantom sdk -o crm.ts
✓ Recorded regression tests     phantom test
✓ Permission manifest           phantom serve --allow read

从此 Agent 不再"寻找右上角的按钮、点击坐标 812,147、等待页面变化"，而是：

await crm.report.export({ type: 'sales', dateRange: 'last_month' });

学习一次，之后零模型调用。 LLM 只在编译期出现；运行期是确定性执行引擎 —— 零 token 成本、毫秒级延迟、可版本化、可 code review。

与浏览器 Agent 的区别

	浏览器 Agent	PhantomAPI
每次调用	模型看页面、逐步点击	直接网络请求（UI 仅兜底）
延迟	数十秒	毫秒级
成本	每次都烧 token	仅编译时一次
稳定性	每次都可能翻车	回归测试守护，改版即 CI 红灯
产物	无	API + MCP + SDK + 测试，可进 git

快速开始

pnpm install && npx playwright install chromium
pnpm demo-crm &                                    # 启动一个"故意没有 API"的演示 CRM（带登录+CSRF）

# 编译：打开浏览器，演示一遍你的操作，关闭窗口即完成
pnpm phantom learn http://localhost:4010 -o my-crm --refine

# 产物即刻可用
DEMO_USER=admin DEMO_PASS=secret123 \
PHANTOM_USERNAME=admin PHANTOM_PASSWORD=secret123 \
pnpm phantom serve my-crm                          # REST + OpenAPI
curl -X POST localhost:7777/actions/customer.search \
  -H 'content-type: application/json' -d '{"query":"alice"}'

pnpm phantom test my-crm                           # 重放录制的回归测试（改版检测）
pnpm phantom sdk  my-crm -l ts -o crm.ts           # TypeScript SDK
pnpm phantom sdk  my-crm -l py -o crm_sdk.py       # Python SDK
pnpm phantom mcp  my-crm                           # 接入 Claude Code / Cursor

--refine 是差分录制：同一流程用不同的值再演示一遍，两遍中变化的值被证明是参数， 相同且无数据流证据的折叠为常量 —— 参数推断靠证据，不靠猜。

会话与凭据：演示中的登录流程（密码框数据流）被自动识别为内部动作 session.refresh， 录制值脱敏、凭据经环境变量注入、TAG 文件零 secret。运行时 401/403 自动重登录并重试； 登录响应中的 CSRF token 被识别为"先取后用"依赖链，自动捕获并注入后续请求。

LLM 是可选的：参数、类型、依赖链全部来自确定性分析（数据流追踪 + 差分 + 时间窗因果对齐）。 --llm 仅用于润色命名（任何 OpenAI 兼容端点，经 PHANTOM_LLM_BASE_URL 配置），不接也完全可用。

核心概念：Typed Action Graph (TAG)

TAG 是"对一个软件的一次操作"的声明式中间表示（spec）。每个 action 同时携带网络层执行（首选，快且稳）与 UI 层执行（兜底，多选择器 + 自修复），运行时自动降级。TAG 是纯结构、零凭据，可提交进 git、发 PR、社区共享。

路线图

• M0 ✅ TAG spec v0.1 · REST/OpenAPI · MCP · TS SDK · 回归测试 · 权限白名单 · demo CRM
• M1 ✅ phantom learn：录制 → 因果关联 → 数据流参数推断 · 差分录制（--refine）· 会话管理（登录识别为 session.refresh，凭据脱敏）
• M2 ✅ CSRF/token 依赖链 · UI 兜底执行器（多候选选择器）· GraphQL 识别（operation 即动作，variables 即参数）· 分页参数（可选 + 默认值）· Python SDK · 可选 LLM 命名（--llm）
• M3 Phantom Registry：phantom install jira · 桌面应用（accessibility API）

伦理边界

PhantomAPI 面向你有权访问的软件：内部系统、遗留 ERP、自有 SaaS 后台、授权自动化。我们不做也不接受：验证码破解、反爬对抗、指纹伪装、绕过访问控制。

License

Apache-2.0