---
name: oa-app-integration
description: 为自己的应用市场开发或集成自定义 H5 应用，接入公共能力并打包、隔离测试、上传发布本人应用。适用于 www.miniyun.com 及兼容部署的普通业务模块；公共提供者的运维安装另按平台流程处理。
---

# OA 应用集成与发布

优先用 SDK 完成一个可运行的最小应用，再扩展业务。默认站点 `https://www.miniyun.com`，用户指定其他部署时使用其明确指定的站点。开始读取站点 `/docs/ai-agent.md` 和 `/docs/api.json`；本地参考是快照，实际部署契约不同则说明差异并采用实际契约。

## 先确定任务

从会话提取目标、语言、应用 ID/版本、角色、数据归属及是否授权正式发布，不重复询问已说明的信息。只问影响实现的问题：谁能看/改/审批、实际审批人是谁、是否迁移旧数据、是否需要 PostgreSQL/公共扩展/外部系统。缺少实际人员或敏感数据规则时不要猜测；列出问题，同时继续不依赖答案的开发。简单应用可声明默认 Python 模板 + 自定义 H5 + records。

只开发/集成不自动扩大为正式发布；用户已经要求发布时，测试通过后继续执行，不额外重复索取相同批准。生产样例写入、业务邮件、真实迁移等应有对应授权，不能为了测试自行创建生产账号/Key/验证码。

用户要求 Agent 安装本 Skill 时，由 Agent 按客户端支持方式安装，或直接读取 SKILL.md 与引用文件并运行配套脚本，不把下载解压和环境变量设置转交给小白用户。工具或权限缺失时说明具体阻碍，不假称安装成功。

## 执行步骤

1. **预检。** 公共文档/SDK 不需要 Key。首次注册会自动生成 Key 并通过注册邮件发送，无需另行申请。接受用户在本次受信任的私有会话提供的 Key，或读取已有环境变量；不要强迫用户配置环境变量。Agent 仅在辅助脚本子进程环境中临时传入 `OA_API_KEY`，调用 whoami 核对账号，不回显、不落盘、不放命令参数、H5、源码、包或日志。缺少 Key 时提醒查收注册邮件，独立开发继续，不要求公开粘贴秘密。
2. **初始化。** `init` 下载 SDK 并生成 Python 骨架，自动同步 manifest/describe/权限 ID。选择唯一 ID；升级保留原 ID、使用所有者账号，并同步版本。不要覆盖已有目录。其他语言按 [协议与能力](references/integration.md) 选择实际启用的运行配置。
3. **实现业务。** H5 只通过 PlatformUI.execute/request 访问本模块，不自建登录或直连数据库。后端检查输入、状态、归属、版本和幂等；修改字段时同步页面、校验、manifest 及 simulation.json。模板只是便笺演示，不能只改标题就宣称实现了合同/报销。
4. **按需集成。** 简单记录优先 records；需要关系查询/事务再申请 PG，声明随包 SQL。公共能力要声明 capabilities + dependencies，经 host.call 保留可信 ActorID/RequestID；按需读取站点协议，见参考文件。不要承诺现有工作流支持条件会签或通知支持业务邮件。
5. **验证与打包。** 检查语法/编译、有效及无效输入、重复请求、角色/记录越权和页面错误/空态/手机宽度；pack 只加入声明文件。ZIP 根是 manifest.json，不夹带凭据和正式业务数据。语法检查不等于端到端通过。
6. **上传和测试。** 已授权上传时 submit 并保存回执，再 test，等待 ready 且报告通过。回执保存稳定提交请求号和指纹，不含 Key；网络中断保留同一回执重试。失败检查修复后以新包、新回执提交，不绕过失败项。
7. **发布。** 已授权正式发布时 publish；脚本核对站点、账号、包指纹、测试报告及完整能力列表。不能把“上传成功”当成“已发布”。轮询到时先 status，不新建候选包或改请求号重发。未授权发布则交付已测试候选包和具体链接。
8. **交付。** 给出站点、应用 ID/版本、候选包 ID/指纹、真实状态、使用入口、已测和未验证项。业务验收使用本地或隔离数据。

## 辅助脚本

仅用 Python 3 标准库。在 Skill 目录运行，或把 scripts 路径换成绝对路径；全局 `--url` 放在子命令前。Key 只从环境读取，带凭据的重定向会被拒绝。

```text
python scripts/oa_app.py init --id notes-yourname-7f3a --name 我的应用 --directory ./my-app
# 修改业务代码、页面、声明和测试输入后：
python scripts/oa_app.py pack ./my-app --output ./out/my-app.zip
python scripts/oa_app.py whoami
python scripts/oa_app.py submit ./out/my-app.zip --receipt ./out/submission-1.0.0.json
python scripts/oa_app.py test ./out/submission-1.0.0.json --wait 180
python scripts/oa_app.py publish ./out/submission-1.0.0.json --wait 180
python scripts/oa_app.py status ./out/submission-1.0.0.json
```

## 错误与边界

- 401 检查 Key 过期/撤销和账号；403 检查动作、归属、能力与 Key 限权，不靠扩大角色或直连他库绕过。
- ID 已占用：新应用换 ID，升级恢复原所有者，不覆盖他人应用。
- 运行配置未启用/缺依赖：交运维处理，不上传自选镜像、Docker 参数，不在容器内联网安装。
- 429 适当退避；写入超时不代表回滚，先查询并保留请求号。禁止无界重发写请求。
- 普通发布不能创建或覆盖公共提供者。不要为完成业务集成而 SSH 改底座、注册表、权限或既有应用，这属于另外的运维范围。