客户端 API

客户端 API 是 App 内部的本地服务，用于高级自动化。它不是公开云 API，不应暴露到不可信网络。

常见用途

本地 API 适合让可信脚本或本地工具：

• 触发卡包同步；
• 列出云端或本地卡包；
• 创建卡包；
• 从云端拉取卡包；
• 更新卡包信息；
• 删除本地卡包；
• 读取分类；
• 搜索、创建、更新或删除卡片；
• 上传或删除卡包资源；
• 与个人工作流集成。

认证

受保护端点需要 App 登录状态，并通过以下方式提供本地密钥：

• X-API-SECRET 请求头；
• 或 secret 查询参数。

请把密钥当成凭据，不要写入公开日志、浏览器历史、共享脚本或远程服务。

端点分组

App 包含以下端点组：

分组	用途
认证	检查登录和本地 API 访问状态。
同步	触发或检查卡包同步。
卡包	列表、创建、拉取、更新和删除卡包。
分类	读取卡包分类结构。
卡片	搜索、创建、更新和删除卡片内容。
资源	上传和删除卡片使用的媒体或文件。

具体 payload 可能随 App 版本变化。严格集成时应查看当前 App 实现。

安全规则

• 只在可信机器上使用。
• 不要绑定到公网。
• 不要分享本地密钥。
• 先在小卡包上测试。
• 大批量自动修改前后都要同步。
• 批量更新前先备份或导出重要卡包。
• 不理解同步行为时，不要同时用 UI 和脚本编辑同一卡包。

自动化适用场景

适合：

• 从本地数据管线创建卡包；
• 根据已审查 CSV 更新卡片；
• 附加生成的图片或音频；
• 控制导入后触发同步；
• 搜索卡片做本地质量检查。

高风险：

• 无备份删除大量卡片；
• 无预览重写整包字段；
• 上传未审查 AI 输出；
• 另一台设备同时编辑；
• 通过远程服务器暴露 API。

常见排查

问题	检查
请求未授权	登录状态和 X-API-SECRET。
卡包不可编辑	卡包归属、只读状态、卡包类型兼容性。
资源上传失败	Plus 附件限制、文件路径、大小和网络。
另一台设备未更新	两台设备都同步，并等待资源完成。
payload 错误	对照当前 App 实现。

相关：账号与同步 和 导入卡片。