原理说明：底座与应用如何协作
面向希望理解设计的人：页面、后端、数据和权限如何协作，以及一个应用从编写到发布的过程。建议实际开发优先使用 AI Agent 集成与发布指南，让 Agent 按步骤完成集成；本页提供原理和便笺实例。
先理解：你写业务，底座管入口
一个应用通常包含三部分：页面、后端程序、应用说明文件。页面画表单和按钮，后端判断“谁能做什么”并读写数据，说明文件告诉底座如何启动、页面在哪里、需要哪些能力。
页面通过模板里的 PlatformUI 调用后端。你不必自己编写登录系统，也不用把 API Key 放进页面。底座转发请求，是为了带上可信的当前用户身份并执行权限检查；业务逻辑仍由你自己的后端决定。
例如“保存便笺”：页面提交标题 → 底座调用本应用的 create 动作 → 后端校验标题 → 调用底座提供的 records.create 保存 → 页面显示结果。这就是一次完整业务操作。
三个层次，记住各自做什么
| 层次 | 通俗理解 | 开发时怎么用 |
|---|---|---|
| 核心底座 | 统一入口和管理规则：账号、权限、请求转发、运行隔离 | 直接使用，不必为每个应用重写 |
| 公共能力扩展 | 多个应用可复用的服务，如工作流、待办、站内通知、附件和定时任务 | 有需要再申请和调用；先看下方协同组件使用入口 |
| 业务应用 | 你开发的便笺、CMS、报销、资产等 | 编写自己的页面、规则和数据操作 |
“模块”就是应用或公共扩展打包运行时的单元，不是额外一层。这个教程只开发一个普通业务应用，不需要先开发公共扩展。
开始前准备
- 一个能登录 工作空间的邮箱账号。
- 本机安装 Python 3，用于检查代码和打包。命令示例中的
python如不可用，可改为本机的python3或py -3。 - 一个文本编辑器。服务器运行环境由平台提供，完成此例不用自己部署 Docker、Web 服务或数据库。
这里选 Python 是因为模板不需要编译或安装第三方依赖。底座也支持 Go、Java 等实现同一接口的程序；不同语言的开发方式见高级与扩展原理说明。
1. 下载并认识模板
下载开发模板 ZIP 解压后，打开 python-example 文件夹。本例有六份应用文件：
python-example/ manifest.json 应用 ID、版本、启动方式、权限和页面清单 main.py 后端：列出便笺、校验标题并保存 simulation.json 发布前的模拟测试输入 code/oa_module.py 通信 SDK，通常不用修改 ui/index.html 页面结构：输入框、保存按钮和列表 ui/app.js 页面行为：加载列表、调用保存动作
解压目录外层还有 package-example.py，用于打包。先保留模板的全部文件，只做下一步的少量修改。
2. 换成自己的应用身份
应用 ID 在网站上必须唯一。例如用 notes-你的英文名-随机后缀，实际填写 notes-liming-7f3a 这样的英文 ID。不要直接发布大家共用的 python-notes。
- 打开
manifest.json，将所有python-notes替换为你的 ID。注意权限 ID 也要改，如notes-liming-7f3a.read和notes-liming-7f3a.create。 - 打开
main.py，把描述信息里的python-notes改成同一个 ID。 - 把
manifest.json、main.py、ui/index.html中的“Python 便笺”改为自己的应用名称，如“李明的便笺”。版本都先保留1.0.0。
检查点：manifest 与后端 describe 返回的 ID、名称、版本、协议必须一致。第一遍先不增加字段、不改能力列表，确保完整走通流程。
代码里最关键的两处
前端在 ui/app.js 中调用动作：
await ui.execute('list', {}); // 加载便笺
await ui.execute('create', {title}, pending.id); // 保存便笺
后端 main.py 的 execute 根据动作处理：list 读取列表；create 检查标题非空、不超过 120 字，再保存。模板通过 records.* 使用底座的模块隔离记录服务，这个例子没有独立 PostgreSQL 数据库。
simulation.json 已带有效输入和冲突输入。以后增加必填字段，要一起更新测试输入；校验必须写在后端，不能只依赖页面控件。
3. 检查并打包
在解压目录打开终端，该目录下应该同时看得到 python-example 文件夹和 package-example.py。执行：
python -m py_compile python-example/main.py python-example/code/oa_module.py python package-example.py python-example my-notes.zip
第一行没有报错，表示 Python 语法检查通过；第二行显示 Created …my-notes.zip，表示打包完成。打包器只加入声明的应用文件，不会把本机缓存、整个 SDK 或数据目录装进去。
检查点：打开 ZIP 应直接看到 manifest.json，不能在外面再套一层 python-example/。这个打包器专用于入门的 records 示例；接入 SQL 后请按高级指南包含声明的数据库脚本。
不要直接运行 main.py 当作网站，也不要双击 HTML 作为完整验收。后端通信和页面桥接需要底座环境，下一步的隔离模拟与工作空间才是完整运行入口。
4. 在网页上传、测试、发布
- 登录工作空间，打开“我的应用发布”（管理员看到“应用发布管理”）。
- 点击“上传应用包”，选择刚生成的
my-notes.zip。上传后只是候选包，尚未上线。 - 点击“运行模拟测试”，确认后等待结果。底座在独立环境运行程序与输入检查，不使用正式业务数据。
- 如果失败，进入“查看详情”阅读失败项，修改代码、重新打包并上传。全部通过后再发布。
- 状态变成“测试通过，待批准”后，点击“批准正式发布”。核对应用、版本和能力；本模板只需要
identity.get、records.list、records.create，勾选后确认。 - 等待状态变成“已发布”。这是本人应用的自助发布，不用再找管理员审批。提交和发布结果也会通知本人邮箱。
应用首次提交后绑定提交账号。以后升级同一个 ID，应继续使用同一账号；不能使用别人的应用 ID 覆盖其应用。平台敏感能力、公共扩展提供者不属于本例的自助发布范围。
API Key 什么时候需要？
以上网页流程不需要手动填写 Key。如果让 Agent 或终端代为提交，可以使用注册邮件中的个人 API Key，或在“我的 API Key”创建一把。Key 代表你的权限，保存在 Agent 的私密配置中，不能写进 H5、源码仓库或安装包。完整接口示例见自助发布说明。
5. 打开应用，确认真的可用
- 回到工作空间并刷新应用目录，打开你刚发布的便笺应用。
- 输入“我的第一条便笺”，点击“保存”，应看到“已保存”和列表中的标题。
- 刷新页面后这条便笺仍在，说明保存和读取已连通。
- 确认模拟测试用的便笺没有混进正式列表；模拟数据与正式数据分开。
发布成功后，所有者会获得本应用的操作权限。需要同事使用时，由管理员给对应用户或角色配置本应用的权限；应用出现在目录里不代表所有人都能读写其业务数据。
接下来：修改和升级
先试着修改页面提示或布局。改完后，把 manifest.json 和 main.py 中的版本都升为 1.0.1，保留应用 ID，用同一账号重新打包、上传、模拟并发布。正式升级不会自动清空已有记录。
增加业务字段时，要同时修改页面输入、后端校验、列表展示和模拟输入。像 CMS“提交审核、发布”这样的新动作，还要声明动作权限，并在后端检查当前用户、记录归属和业务状态。需要独立关系库时再申请 PostgreSQL，准备表结构、初始化和迁移脚本。
遇到问题，先查这里
| 现象 | 优先检查 |
|---|---|
| ID 已存在或无权访问候选包 | 是否用了别人的 ID？查看当前登录邮箱；首次开发换唯一 ID，升级则登录原所有者账号。 |
| 描述信息不一致 | manifest 与 main.py 的 ID、名称、版本、协议是否同步修改。 |
| 缺少文件或存在未声明文件 | 用模板打包器生成 ZIP；新增 JS/CSS 或 code/ 文件须同时加入 manifest 对应文件清单。 |
| 模拟失败 | 查看详情中的具体检查。核对必填字段、重复请求处理及 simulation.json，不要跳过测试。 |
| 页面空白或 PlatformUI 不存在 | 从工作空间打开应用；检查包内相对资源路径、ui.files 和浏览器报错。 |
| 应用可见但操作无权限 | 确认当前账号、本应用动作权限及能力批准情况。使用 API Key 时还要核对 Key 的限权范围。 |
| 模块繁忙 / 429 | 稍后重试，避免页面同时发出大量请求。写入超时先查状态；需要重试时保留原请求号。 |
| 运行配置未启用或缺少依赖 | 联系运维确认 python3 运行配置。容器不能运行时联网 pip 安装依赖，依赖须提前审核准备。 |
直接使用现成的协同组件
现在可从工作空间打开工作流中心、统一待办、站内通知、附件中心；业务应用也可申请对应公共能力。按步骤学习四个组件怎么用，需要代码接口再看接入说明。