API 是什么（Press 语境下）
一句话总结
程序之间的”菜单”。Press UI 点按钮 → 调 API → API 查数据库或触发操作 → 返回结果。人和人之间用自然语言，程序和程序之间用 API。
🤔 为什么会有它 / 解决了什么问题
没有 API 的话，Press UI 的每个按钮背后都需要有人手动敲命令行。比如你在 UI 点”New Site”，得有人 SSH 到 f1 上跑 bench new-site。API 让 UI 可以直接调用后端函数——点按钮 → API 自动执行 → 返回结果。
它也解决了”不同程序之间怎么通信”的问题。Press UI（前端，JavaScript）和 Press 后端（Python，Frappe）是两个完全不同的程序，它们通过 API 对话。
🔍 具体原理 / 运作逻辑
API 就是一个 URL 地址，你访问它，它返回 JSON 数据或者执行操作。比如：
GET https://press.getgrowth.app/api/method/ping
→ {"message": "pong"}
POST https://press.getgrowth.app/api/method/press.api.site.new
→ 在 f1 上创建站点 → 返回 {"message": "Site created"}
Press 的 API 是 Frappe 框架自带的。site.py 里的每个带 @frappe.whitelist() 装饰器的函数，就是一个 API 端点。Press UI 的 JavaScript 代码调这些端点，拿到数据渲染页面。
更硬核的技术细节（点击展开）
Frappe 的 API 分两种：REST API（标准 HTTP GET/POST）和 RPC API（
/api/method/模块.函数）。Press UI 主要用 RPC 方式。API 函数里可以调用frappe.get_all()查数据库、frappe.get_doc()获取记录、frappe.db.commit()提交。site.py 补丁改的就是 API 函数内部的数据查询过滤条件。
🧭 什么情况下会用到 / 什么场景会遇到它
- 在 Press UI 点任何按钮 → 背后都是 API 调用
curl https://press.getgrowth.app/api/method/ping→ 手动测 API- 将来 Agent 调外部工具的 MCP 接口时 → 也是调 API
- bench console 里
frappe.get_all(...)→ 本质和 API 里查数据库是一样的操作
⚖️ 副作用 / 代价 / 取舍
- API 函数的过滤逻辑（如
public=1）如果写死了，数据查不到不会报错——只会返回空列表，不容易排查 - 自建 Press 绕过 UI 直接用 console 操作时，跳过了 API 层的创建函数，那些函数里写死的参数（如
public=1）就不会生效
🕰️ 来历
- 计算机领域的基础概念，不是某个公司发明的
- Press 的 API 基于 Frappe 框架的
@frappe.whitelist()机制 - site.py 里的 API 是
frappe/press仓库的一部分，官方和我们用的是同一份代码
🔗 关联 / 经常一起出现的概念
- site.py：Press app 里定义 API 函数的文件。
get_available_versions()、new()等都是 API 函数。补丁改的就是这个文件的 API 内部逻辑 - Frappe Whitelist：
@frappe.whitelist()装饰器，标记一个 Python 函数可以被外部 HTTP 请求调用 - Agent Job：Press 通过 API 创建 Agent Job，Agent 拉取后执行。API 是”传令的”，Agent 是”干活的”
⚠️ 注意事项 / 常见误区
- Press API 和 Agent 之间的 WebSocket 通信不是一回事。API 是 HTTP（请求-响应），Agent 是 WebSocket（长连接推送）
- API 函数里的过滤条件改动了，不会报错——只会静默返回空数据。site.py 下拉框全空的排查难点就在这里
📎 记忆锚点
API = 餐厅菜单。你（Press UI）看点菜（调 API），厨房（后端）做菜（查数据库/执行操作），做好端出来（返回 JSON）。你不用进厨房，厨房不用见你。
📝 更新日志
| 日期 | 改动 | 原因 |
|---|---|---|
| 2026-07-08 | 首次创建 | 名词科普 |