AI FIRST / PLATFORM V0.20.4

建立自己的应用市场，优先让 AI Agent 帮你创建应用

把业务需求交给 Agent，让它开发团队需要的工具，测试后发布到你的应用市场。下面以共享便笺为例，按步骤完成第一次发布。你负责说明业务规则、回答关键问题，以及提供自己账号的凭据配置。

实操：让 AI 为你的应用市场发布「共享便笺」

不用先学完整协议。你提供业务需求和自己的账号，Agent 使用 Skill 完成代码、页面、测试和上传发布。这个例子实现一个最小的企业协作功能：团队阅读便笺，发布者新增便笺，记录保留作者与时间。账号、Key、运行环境就绪时，简单功能可在几分钟内完成；具体耗时以实现和测试为准。

第一步：登录市场，准备自己的 API Key

打开登录 / 注册，通过邮箱验证码进入自己的账号。
进入工作空间的“我的 API Key”，使用有效的个人 Key。Key 的限权必须覆盖本人应用提交、测试、发布操作；遇到 403 先核对账号和 Key 范围。
在你使用的 Agent 客户端或本地进程的私密环境配置 OA_API_KEY，然后启动或重新启动 Agent，使它能读取该变量。不要把真实 Key 放进下面的需求文本、聊天、源码或应用包。

第二步：让 Agent 读取指南和 Skill

打开能编辑文件、运行 Python 3 命令的 AI 编程 Agent。下载 Skill并解压，支持 Skills 的客户端将 oa-app-integration/ 放入其技能目录；Codex 可放在 ~/.codex/skills/。如果客户端不支持安装 Skill，直接让它读取SKILL.md及相对路径引用的参考文件，并运行配套脚本。仅能聊天、无法运行工具的 AI 可以生成代码，上传发布还需要本地 Agent 或你执行命令。

第三步：复制这段完整需求给 Agent

请阅读 https://www.miniyun.com/docs/ai-agent.md，
使用 oa-app-integration Skill，为我的应用市场开发并发布「共享便笺」。

1. 使用 Python 3、自定义 H5 和底座 records；应用 ID 选择未被占用的唯一值。
2. 每条便笺包含标题（必填，去空格后 1–120 字）、正文（最多 2000 字），
   展示可信作者和创建时间；记录按时间倒序显示，内容按纯文本显示。
3. 已获本应用阅读权限的成员可以阅读共享范围内的便笺；
   发布者另有新增权限。第一版只做列表和新增，不做编辑、删除、邮件。
4. 共享范围限定为本次确认的团队。先问我团队范围及成员/发布者是谁；
   不把“所有人”扩展成公网匿名访问，不自行给用户增加管理员权限。
5. 后端校验字段与权限，禁止伪造作者，重复请求不产生重复记录；
   H5 有加载、空态、提交失败与重试提示，适配手机。
6. 模板目前只有本人标题便笺；请补齐正文、共享权限、作者时间显示、
   simulation.json 和隔离测试，不能只改名字就宣布完成。
7. API Key 从私密环境 OA_API_KEY 读取。请先开发、打包、隔离测试；
   测试通过后上传并发布本人应用，等待 published，再交付使用链接和验证结果。
8. 只问影响实现且我尚未说明的问题；其余独立工作继续进行。
   正式用户授权或共享范围配置需要管理员时，给出具体配置项，等待有权人员处理。
   不向生产写入测试便笺，不创建生产测试账号。

如果只想试开发，将第 7 条改成“交付代码、可上传包和测试报告，暂不上传或正式发布”。“几分钟”从准备就绪的简单示例开始计算；复杂权限、正式迁移或外部系统接入需要额外工作。

第四步：回答 Agent 的关键问题

例如回答：“这是销售团队的内部便笺；团队成员可阅读，指定的两位发布者可新增；不迁移旧数据。”具体人员使用已有账号，不让 AI 编造用户 ID。对于全公司共享，明确仅限有此应用权限的登录成员；对于指定部门，提供真实部门和人员。

能打开应用，不等于能读到别人的记录。records 默认按本人范围过滤。共享便笺必须同时配置阅读动作权限与数据范围：团队可使用 department 或 custom；明确全公司共享才使用本应用的 all。系统管理员在“角色与权限 → 数据范围”针对该应用配置，再分配阅读/新增角色。不要把全局 * 改为全部，也不要用系统管理员账号代替普通成员验收。普通开发者可先完成代码与隔离测试，向管理员提供具体角色、应用 ID 和范围，不绕过授权。详见数据范围原理。

第五步：Agent 实际执行哪些命令？

以下由 Agent 执行；<SKILL目录> 替换为解压目录，示例 ID 要换成自己的唯一 ID。init 只生成骨架；中间必须实现上述业务与共享规则，不能把这些命令当成无需开发的一键发布。

python <SKILL目录>/scripts/oa_app.py init --id shared-notes-yourname-7f3a --name "共享便笺" --directory ./shared-notes

# Agent 修改 main.py、ui/、manifest.json、simulation.json，完成本地业务与权限检查
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

Agent 应同步修改后端、页面、字段声明与模拟输入；作者/时间来自可信身份和 records 元数据，不能信任前端提交。数据使用当前应用自己的 records 集合，不与其他应用混存。默认模拟通过后，还要用隔离的不同身份验证共享权限，平台模拟不自动证明全部业务正确。

第六步：确认交付，打开已发布应用

状态必须为 published；若仍在 testing/publishing 或等待超时，沿用回执查询，不重复上传。测试失败则修复包、使用新回执重测。
Agent 交付应用 ID、版本、候选包与指纹、使用链接、已测和未验证项。你可在工作空间“我的应用发布”查看候选包和报告，发布后从应用入口打开。
验收使用本地或隔离身份：发布者新增 → 阅读者可见；阅读者不能新增；无关账号不能访问；超长/未知字段被拒绝；重复请求只保存一次；手机显示正常。
普通成员的正式权限与共享范围需由有权人员配置完成；未完成时标为“程序已发布，成员开通待完成”，不能宣称团队已可使用。生产操作由实际参与者在明确授权后完成。

现在你可以复用同样的步骤，再为应用市场增加通讯录、资产台账或其他工具。更复杂的审批和附件需求，再接入相应公共组件。

1. 复制这段需求给 AI Agent

把下面的业务目标和规则补充完整，交给能够编写代码、运行命令的 Agent。Agent 可以向你提出影响实现的问题，不必先读完全部架构文档。

请阅读 https://www.miniyun.com/docs/ai-agent.md，使用网站提供的
oa-app-integration Skill，为我开发并发布一个应用。

业务目标：填写要解决的问题、字段和主要操作。
使用角色与规则：填写谁能看、谁能修改、谁能审批。
现有数据与集成：说明是否有旧数据，是否需要数据库或协同组件。

请先提取已有需求，只针对影响实现的缺失信息向我提问；
其余步骤采用并说明合理默认，继续可独立完成的工作。
请完成实现、打包、隔离测试；测试通过后再发布本人应用，
交付真实状态、应用链接、已测试与未验证项目。
API Key 从 Agent 的私密环境 OA_API_KEY 读取，不要放入代码或包。

如果这次只想开发，把“开发并发布”改成“开发并交付可上传包，暂不正式发布”。

2. 使用配套 Skill 和脚本

下载集成 Skill 直接读取 SKILL.md · AI 简明指南 · 下载 SDK 与模板（也含 Skill）

解压后得到 oa-app-integration/，其中有 SKILL.md、参考协议和标准库辅助脚本。支持 Skills 的 Agent 将它放入自己的技能目录；Codex 可放到 ~/.codex/skills/oa-app-integration/。其他 Agent 可直接读取 SKILL.md，并按相对路径读取参考和运行脚本。安装后可让 Agent 使用 $oa-app-integration；有些客户端需要重新加载技能。

脚本提供 init、pack、whoami、submit、test、publish、status。回执保存候选包和指纹，断线后可继续查询；Key 只从私密环境读取。普通本人应用可自行测试和发布，不用另行申请发布令牌。

3. Agent 应按哪些步骤完成？

确认任务：识别业务目标、角色、数据范围及是否允许上传/正式发布；缺少关键信息时提问。
读契约、取模板：读取实际站点协议，用 init 生成最小可运行应用，选择唯一 ID。
实现与集成：编写 H5 和后端规则，按需接入 records、PostgreSQL 或工作流/待办/通知/附件。
验证与打包：同步清单、资源、SQL、权限及模拟输入，验证有效/错误/越权/重复请求等路径。
上传与隔离测试：核对账号，保存稳定请求号和回执，等待 ready；失败则修复，不绕过检查。
正式发布：已授权时核对包指纹、完整能力与通过的报告，等待 published；未授权时交付具体候选包。
交付：给出版本、使用链接、实际状态与验证边界，不能把“已上传”当成“已发布”。

读取完整命令和错误处理 →。流程与脚本不是免检通道，账号权限、应用归属、Key 限权、隔离模拟继续生效。

Agent 可能需要你回答什么？

问题	为什么需要
谁可以查看、修改和审批？	决定后端规则、权限与记录可见范围
由哪些实际人员审批，是否允许自审批？	避免编造用户 ID 或错误分配处理人
有旧数据需要迁移吗？	决定数据结构、备份与迁移范围
需要哪些外部系统或公共能力？	确认已有接口、运行配置和授权条件
只交付代码，还是通过测试后正式发布？	明确 Agent 可以执行到哪一步

你已经给过答案时，Agent 应直接使用，不要反复确认。没有 Key 也能先开发和打包；需要上传时再在 Agent 凭据配置中补充。不要把真实密钥写进需求描述、页面或应用包。

现成协同组件与原理文档

先看工作流、待办、站内通知、附件使用指南，需要接入时由 Agent 按公共能力协议调用。希望理解架构，可阅读原理说明；要了解数据库、RPC、扩展和运行隔离，阅读高级与扩展原理说明。