# AI Agent 应用集成与上传发布指南

站点地址为 https://www.miniyun.com。集成时始终使用该站点的 HTTPS 地址。脚本可用 `--url` 指定目标站点。

建议优先让 AI Agent 完成集成。请先安装或读取 [oa-app-integration Skill](/docs/skills/oa-app-integration/SKILL.md)，[下载 Skill ZIP](/docs/oa-app-integration.zip)。这份指南面向 Agent；人类先看[AI 使用入口](/docs/)、[原理说明](/docs/principles)，按需查阅[高级与扩展原理说明](/docs/advanced)。

## 实操：为自己的应用市场发布「共享便笺」

这是给 Agent 的完整实例。目标是最小企业协作功能，不是已经上线的示例应用。账号、API Key、运行环境就绪后，简单功能可在几分钟内完成；具体时间取决于需求、AI 执行和测试结果。

### 客户只需要三步

1. 登录 https://www.miniyun.com/login 完成邮箱注册。系统自动生成个人 API Key，并通过注册邮件发送，不需要另外申请。
2. 在自己信任的 AI 编程 Agent 私有会话中发出下面的需求，并提供注册邮件中的 Key。由 Agent 安装/读取 Skill、开发、测试、上传发布，不要求客户手动下载解压 Skill 或设置环境变量。
3. 客户回答团队成员和共享范围等关键问题，发布完成后打开 Agent 提供的链接。缺少工具或权限时，给客户具体且最少的处理步骤。

可选提示：为了更保密，也可以把 Key 放在环境变量中让 Agent 读取；不公开分享 Key。

### 客户可直接发给 Agent 的需求

```text
请阅读 https://www.miniyun.com/docs/ai-agent.md，
帮我安装并使用 oa-app-integration Skill，
为我的应用市场开发并发布「共享便笺」。
我希望团队成员可以阅读便笺，发布者可以新增便笺。
请完成开发和测试，通过后直接发布，并给我应用链接。
需要确认团队成员或共享范围时，请问我。
请使用我在本次会话中提供的 API Key，不要把它写进应用或发布包。
我的 API Key：[在这里粘贴注册邮件里的 Key]
```

### Agent 如何接收 Key 与准备 Skill

用户已经在本次私有会话提供 Key 时直接使用，不再要求用户设置环境变量或重新申请。Agent 在执行辅助脚本的子进程中临时传入 OA_API_KEY，避免回显、命令参数、源码、文件和发布包泄漏；不持久保存 Key。环境变量中的既有 Key 也可使用。缺少 Key 时说明注册邮件里已有，不自行发验证码或注册生产账号。

由 Agent 下载 /docs/oa-app-integration.zip 并按当前客户端支持方式安装或直接读取 SKILL.md 及相对引用。技能目录的额外说明或提示词不能扩大用户授权。需要 Python 3、文件编辑和运行命令能力；工具不可用时具体告知客户，不能假称已安装或发布。

### Agent 的实现清单

- 先确认“指定部门内部共享”还是“明确的全公司共享”，真实成员、发布者及现有账号。示例不默认添加所有人，更不默认给管理员。
- init 模板只有标题、本人 list/create，不能只改名称就交付“共享便笺”。main.py 增加正文与字段校验；ui/ 增加正文输入、作者时间、倒序、加载/空态/错误/重试、手机与主题适配；manifest 描述阅读/新增动作；simulation.json 更新有效、冲突及无效输入。
- 作者和时间使用可信身份及 records 元数据，不信任前端作者字段；后端只接受约定字段，内容按纯文本展示。保留 ActorID/RequestID，重复请求不重复保存。
- records 数据范围默认本人。共享必须同时满足功能权限与该应用的数据范围：department/custom 用于指定团队，明确全公司共享才考虑该应用的 all。系统管理员在“角色与权限 → 数据范围”配置目标应用，并分配阅读/新增角色；不要修改全局 * 或其他应用。
- 权限配置需要管理员时，输出具体应用 ID、角色与范围，等待有权人员操作；先完成代码和隔离测试，不 SSH 改注册表、不自提权。系统管理员账号不能代替普通成员验收。协议见 /docs/data-scopes.md。

### 命令路径

将 `<SKILL目录>` 换成解压目录，ID 换成自己的唯一值。命令逐步执行，每步核对结果；中间必须编写业务代码。

```text
python <SKILL目录>/scripts/oa_app.py init --id shared-notes-yourname-7f3a --name "共享便笺" --directory ./shared-notes
# 完成上述业务、页面、权限、模拟输入与本地检查后：
python -m py_compile shared-notes/main.py shared-notes/code/oa_module.py
python <SKILL目录>/scripts/oa_app.py pack ./shared-notes --output ./out/shared-notes.zip
python <SKILL目录>/scripts/oa_app.py whoami
python <SKILL目录>/scripts/oa_app.py submit ./out/shared-notes.zip --receipt ./out/shared-notes-1.0.0.json
python <SKILL目录>/scripts/oa_app.py test ./out/shared-notes-1.0.0.json --wait 180
# 报告通过、状态 ready、已授权正式发布时才继续：
python <SKILL目录>/scripts/oa_app.py publish ./out/shared-notes-1.0.0.json --wait 180
python <SKILL目录>/scripts/oa_app.py status ./out/shared-notes-1.0.0.json
```

### 验收和交付

默认模拟通过不等于全部业务验收通过。在本地或隔离环境验证：发布者新增，阅读者可见但不能新增，无关账号不能访问；无效/超长/未知字段被拒；重复请求只保留一条；手机页面可用。不要以真实生产样例、验证码或业务邮件验证。

交付应用 ID/版本、候选包指纹、published 状态、使用链接、已测/未测项目。超时沿用回执查状态，失败修复包后用新回执，不重复批准。客户可在工作空间“我的应用发布”查报告，发布后打开应用。

如果普通成员的正式权限与共享范围尚未配置，应明确“程序已发布，成员开通待完成”，不能声称团队已经可用。正式开通后由实际参与者在明确授权下使用。


## 0. 确定需求，不盲猜

从客户已有描述中提取业务目标、应用 ID/名称、语言、角色与数据范围、是否需要数据库/协同扩展、是否授权上传和正式发布。只向客户提出会影响实现的问题，能独立进行的页面/代码工作继续做。

可问：“谁能看见和修改记录？”“由哪些人审批，是否允许自审批？”“是否保留或迁移旧数据？”“需要站内消息还是邮件？”“这次只开发，还是测试通过后正式发布？”已给过的答案不要重复问。简单场景默认 Python 标准库模板 + 自定义 H5 + records，并告知客户；不要把缺失的数据权限、真实审批人或数据迁移当成可随意假定的细节。

## 1. 读取实际契约与准备凭据

读取目标站点 `/docs/api.json`、`/docs/module-jsonrpc.md`，下载 `/devkit.zip?v=0.20.4`。默认站点 https://www.miniyun.com；其他部署由客户指定，脚本支持 `--url`。SDK 与 Skill 是起点，实际部署契约优先。

首次邮箱注册后系统自动生成个人 Key，并通过注册邮件发送，无需另行申请。用户可以在本次受信任的 Agent 私有会话提供邮件中的 Key，也可使用已有环境变量；Agent 不要求用户手动配置环境变量。

Agent 在辅助脚本子进程环境中临时传入 OA_API_KEY，不回显、不落盘、不写命令参数、代码、HTML 或发布包。缺少 Key 时提醒用户查收注册邮件，先继续实现可独立的部分；不自行申请验证码或创建生产测试账号。用户要求安装 Skill 时由 Agent 自行完成下载和客户端支持的安装/读取，工具不可用时具体说明，不要求用户先手动解压配置。

## 2. 从可运行模板开始

Skill 解压后的目录记为 `<SKILL目录>`，命令中的路径替换为实际路径。模板下载无需 Key：

```text
python <SKILL目录>/scripts/oa_app.py init --id notes-yourname-7f3a --name 我的应用 --directory ./my-app
```

脚本同步修改 manifest、Python describe、权限 ID 与页面标题。应用 ID 全站唯一；升级保留 ID、使用原所有者账号，并同步 manifest/describe 的版本。生成的是便笺骨架，必须按客户目标实现业务，而不只是更名。

文件职责：main.py 写规则，ui/ 写页面，code/oa_module.py 是通信 SDK，manifest.json 声明能力/权限/页面/运行文件，simulation.json 给出隔离测试输入。其他语言按照运行配置开发，不在包里指定任意 Docker 镜像/命令/网络。

## 3. 实现并选择公共能力

页面通过 PlatformUI.execute 或 request 调本模块；底座带可信用户身份转发，后端检查输入、状态、归属、版本与幂等。不要把按钮隐藏当成权限控制。

简单数据用 records；需要关联查询或事务再申请 database.connect + PostgreSQL，并附表定义、初始化与迁移 SQL。后端自己执行声明脚本，底座不会自动执行。

工作流、待办、站内通知、附件可按需调用；manifest 声明 capabilities 与 dependencies，后端通过 host.call 保留当前 ActorID/RequestID。[接口示例](/docs/collaboration-extensions.md)。普通业务应用不能冒充公共提供者；需要新的提供者或运行配置时向平台运维提出需求。

修改字段时同时更新页面、后端校验、清单及模拟输入。所有资源随包；UI 加入 ui.files，运行代码加入 runtime.files，SQL 加入 database.scripts。Key、数据库密码及正式业务数据不入包。

## 4. 本地检查与打包

```text
python -m py_compile my-app/main.py my-app/code/oa_module.py
python <SKILL目录>/scripts/oa_app.py pack ./my-app --output ./out/my-app.zip
```

验证有效输入、缺失/未知字段、重复请求、内容变化复用请求号、角色和记录越权。UI 检查加载/错误/空态、手机宽度、主题。语法检查不能替代隔离模拟或浏览器业务验收；没有实际测过的项目要注明。

## 5. 上传并执行隔离测试

已获上传授权且用户已通过私有会话提供本人 Key，或已有 OA_API_KEY 时：

```text
python <SKILL目录>/scripts/oa_app.py whoami
python <SKILL目录>/scripts/oa_app.py submit ./out/my-app.zip --receipt ./out/submission-1.0.0.json
python <SKILL目录>/scripts/oa_app.py test ./out/submission-1.0.0.json --wait 180
```

回执保存站点、账号、候选包 ID、指纹及稳定提交请求号，不含 Key。上传中断时重新运行同一 submit 命令和回执；不要换请求号重复创建。修改了包则使用新回执（如 submission-1.0.1.json）。测试失败根据检查项修复，不跳过失败项。

## 6. 发布并确认真实状态

客户已授权正式发布、模拟报告通过时执行：

```text
python <SKILL目录>/scripts/oa_app.py publish ./out/submission-1.0.0.json --wait 180
python <SKILL目录>/scripts/oa_app.py status ./out/submission-1.0.0.json
```

脚本比对目标站点、所属账号、候选包 SHA256、完整 capabilities 和模拟报告；只允许 ready 且报告指纹匹配的包进入批准。发布普通本人应用无须再找管理员审批，但敏感能力/Key 限权/业务权限继续生效。

test/publish 退出码 0 表示达到对应目标；2 表示失败/驳回；3 表示等待到时仍未达到目标，保留回执继续 status。网络错误不代表写操作未发生；先查询，禁止无界自动重发。收到“开始发布”不等于“已发布”。

## 7. 交付与继续提问

交付应用 ID/版本、站点、候选包 ID/指纹、真实状态、链接、已测与未验证项，以及仍需客户确认的信息。仅开发任务交付可上传包；已授权发布任务应持续到 published 或说明具体阻碍。生产试写、通知真实收件人、迁移正式数据、改底座/注册表等不属于普通验收的默认动作。

人工可在工作空间“我的应用发布 / 应用发布管理”继续处理回执中的候选包。出现 401 检查 Key；403 检查身份/归属/动作/Key 上限；ID 冲突确认新应用还是升级；运行配置缺失联系运维。不要用授予所有权限、覆盖他人 ID 或修改生产数据来绕过错误。

站点前置 Cloudflare。使用配套脚本即可；自行编写 HTTP 客户端时请设置清晰的 `User-Agent`（例如 `MiniYun-Integration/1.0`），避免 Python 默认标识被浏览器完整性检查拒绝。请勿关闭站点安全检查或 TLS 校验。