安装与更新

普通用户可以从桌面「应用市场」安装官方的「随记」「待办」，或通过「构建应用」创建自己的应用。开发者也可以使用下面的 HTTP 接口管理应用源码。接口要求登录态，生产环境还要求已经验证的邮箱，仅用于开发工具或宿主集成；用户应用内部仍然只使用 platform.*，不要直接请求这些接口。

应用市场与发布

GET /api/marketplace 返回官方应用与用户发布的应用。每项包含 id、name、description、version、is_official、author_name、author_avatar_url、icon_url 和 installed_app_id（未安装时为 null）。版本用于内部记录，市场界面不展示。作者昵称与头像读取当前用户资料；只有 is_official: true 的条目显示蓝色认证徽章。

POST /api/marketplace/:appId/publish 发布当前用户拥有的应用，无需请求体。返回 { id, name, version, published: true }，市场 ID 格式为 user:应用ID。重复发布更新同一条市场记录。也可以在「构建应用」会话中明确要求 Agent 发布；Agent 不会在创建后自动上架。

发布内容包含名称、描述、设计理念、源码、图标与绑定的表结构，不复制使用记录、登录会话或模型配置。应用源码通过不可变快照保存，作者的昵称与头像不作为快照冻结。

POST /api/marketplace/:id/install 安装应用，无需请求体。官方 ID 为 notes、tasks；用户应用使用列表返回的 user:... ID。首次安装返回 HTTP 201 和应用元数据；重复安装返回同一个应用（官方条目 HTTP 200，用户条目 HTTP 201），不会重置记录、修改过的源码或图标。安装创建独立的空数据集，并要求用户在首次运行时确认数据访问权限。

GET /api/marketplace/:id/avatar 与 GET /api/marketplace/:id/icon 返回用户发布条目的作者头像与应用图标，要求登录；没有对应图片时返回 HTTP 404。客户端使用名称首字作为后备显示。当前不支持已安装应用自动跟随市场版本升级。

账号与邮箱验证

本地开发环境跳过邮箱验证。生产环境注册时发送 6 位邮箱验证码，10 分钟有效。每次验证码最多尝试 5 次，重发间隔至少 60 秒，每小时最多 5 次。发送失败或过期时，可在验证页面重新发送。未验证账户可以查看验证状态、重发和退出登录，不能访问应用和个人数据。

验证邮件由 Cloudflare Email Sending 发送。验证码绑定当前登录账号，验证成功后更换 session，并撤销这个账号的其他旧 session。生产 Cookie 使用 HttpOnly、Secure 和 SameSite=Lax。

创建应用

POST /api/apps 创建应用，成功返回 HTTP 201 和应用元数据。

POST /api/apps
Content-Type: application/json

{
  "name": "你好",
  "table_ids": [],
  "files": {
    "app.json": "{\"name\":\"你好\",\"entry\":\"index.js\"}",
    "index.js": "export default function render(root, platform) { root.replaceChildren(platform.ui.title('你好')); }"
  }
}

请优先传入完整的 files，不要同时使用 source 和 files 表达两份入口代码。省略 app.json 时平台会自动生成基础配置。

HTTP 创建接口保存资料但不会自动调用图片模型；创造模式会在创建后自动生成图标。名称修改、上传图标和重新生成请参考应用名称与图标。

table_ids 非空时，data.list() 和 data.get() 只发现绑定的数据集；空数组会列出当前用户的全部数据集。应用首次运行需要用户确认该范围，记录读写也由统一应用网关强制校验。空绑定代表整个个人空间，授权界面会说明包含今后创建的数据集。创建应用时仍应明确绑定所需的数据集。用户之间的数据隔离由服务端处理。

读取应用包

GET /api/apps/:id 返回应用元数据，以及 entry、files、source、revision。其中 source 是入口文件内容，files 包含完整文件包。

GET /api/apps 返回当前用户的应用列表，不包含完整源码。

更新应用包

PUT /api/apps/:id 要求至少提供 source 或 files，可以同时提供新的 table_ids。

PUT /api/apps/APP_ID
Content-Type: application/json

{
  "files": {
    "app.json": "{\"entry\":\"index.js\"}",
    "index.js": "export default function render(root, platform) { root.replaceChildren(platform.ui.title('已经更新')); }"
  },
  "table_ids": ["DATASET_ID"]
}

更新文件包会替换原有文件集合，不是只修改请求中出现的文件。请先读取原包，修改目标文件，再提交完整 files。省略 table_ids 会保留原有绑定；传入空数组会恢复发现全部数据集。

已经打开的应用不会自动热更新。关闭应用标签后重新打开，才能加载新源码。当前没有面向用户的版本回滚 API，请在自己的项目中保留源码版本。旧源码快照会保留，更新失败不切换当前引用。

应用授权

首次打开会显示数据范围与读写能力；在桌面「管理应用」中可以撤销。扩大数据绑定或修改能力声明后，需要再次确认。撤销会阻止旧实例继续调用；重新授权不会恢复旧授权实例，必须重新打开。已送达服务端的写入不能假设被撤回。

宿主通过 /api/runtime/apps/:id/bootstrap 读取授权描述；用户确认后以 policyHash 调用 PUT .../grant。授权后的 bootstrap 返回 grantId、固定 revision 的包和能力集合；宿主 invoke 必须同时携带 grantId 和 revision。这些是宿主接口，用户应用只使用 platform.*，不得自行保存凭据或直接请求 HTTP。