空间智能微应用开发包

包内 CLI、校验器及 DEV 迁移/诊断/启动脚本的内置提示统一使用英文；错误码和结构化字段保持稳定。用户自填名称、业务数据和应用多语言内容保持原样。MOS 正式脚本使用相同的英文诊断约定。

页面开发由设计 Skill 先确认宿主标题归属、组件与 Token，再实现并分别做功能和视觉验收。模板内提供关键词/普通单选胶囊的本地源码；设计 Skill 提供浏览器取证工具，保存桌面/窄区截图并核验声明的样式与焦点，Agent 仍需打开截图复核。详见 视觉验收。

模板还提供从内部 smart2c 微应用提炼的开发包标准组件，统一从 @/components/MicroAppUI 导入：表单弹窗、受控表格、状态标记、文本省略、页内双栏、列表工具栏，以及已有胶囊。直接交付本地源码，不依赖原业务仓库或新增私有组件包。选型与接入见 组件目录。

把安装提示交给 Coding Agent，描述你的需求，再打开 Agent 返回的预览地址。获取开发包、准备环境、生成代码、诊断问题、打包和已开放的上传操作，都由 Agent 根据目标与当前状态处理。

开始使用

在 Coding Agent 中复制下面这段话：

请使用 npmjs 的 @xuqinghua/microapp-kit@<已核实的精确版本> 安装空间智能微应用开发包，运行 npx --yes --registry=https://registry.npmjs.org/ @xuqinghua/microapp-kit@<已核实的精确版本> setup --project <当前业务项目的绝对路径>，先读取包内 START-HERE.md，适配你当前的宿主并完成环境检查。能自动处理的步骤直接完成；需要我选择业务方案、操作系统界面或授权有风险的改动时，用简单的话说明并引导我。然后根据我的需求开发并启动预览。

随后直接描述需求，例如：

帮我做一个设备巡检应用，需要记录巡检结果，保存后可以查询和修改。

Agent 会在需要时询问数据组织方式、谁可以操作等业务选择。新建应用时，Agent 先展示关键页面草图或原型，并说明数据、接口和权限方案；你确认方向后，再实现并打开功能预览。UI 与技术方案可以合并确认，已有结论会直接复用。你无需选择数据库技术、填写连接串、复制 Skill 或记忆命令。宿主要求授权、重载或系统安装需要你操作时，Agent 会给出具体步骤。

开发按影响分级：文案、样式和明确的缺陷修复直接推进；已有应用的小功能只补设计差异；新建应用、主要流程或数据/权限边界变化先做完整设计。设计与确认规则见 设计流程。原型会标明模拟数据与未接入操作，正式功能预览另行验证。

继续使用

本发行版采用六个 Skill，Agent 按任务需要加载；用户仍从同一个开发入口表达目标：

| Skill | 职责 | |---|---| | micro-app-development | 需求澄清、复杂度判断、流程编排、项目身份、联合验收与交付发布 | | micro-app-design | UI、交互、原型与页面状态设计及审查 | | micro-app-solution-design | 整体技术方案，对齐页面、接口、数据、权限及实施拆分 | | micro-app-frontend-development | React 前端、宿主集成、请求与权限 UI、前端测试构建 | | micro-app-backend-development | 后端接口、业务逻辑、数据访问、迁移及测试 | | micro-app-cloud-integration | 平台及外部 API、调用身份和可信上下文契约 |

只要 UI 或技术方案时，Agent 止于设计交付；明确的小修复直接进入对应实现 Skill，不必加载全部六个或重新审批方案。

• “增加按日期筛选，并打开预览。”
• “这个保存按钮失败了，帮我排查并修好。”
• “继续上次的开发，保留测试数据。”
• “把当前版本打包。”
• “把这个版本上传。”（Agent 先检查上传能力和授权，完成已开放的流程。）

有风险的操作会先说明影响；已有明确授权的常规步骤不会反复确认。预览默认保留测试数据，清空数据需要你的明确要求。

当前交付状态

包版本以当前完整包的 package.json 为准；在线安装先核实 npm registry 中目标版本可获取，再替换命令中的精确版本占位符并锁定版本。不静默回退，离线安装直接使用可信完整包。安装器适配当前宿主，将完整资源缓存到用户目录并锁定项目版本。

本包提供六个 Skill、终端凭据向导、账号显式复用、项目级发布恢复、update/rollback、独立 Node24 后端绑定及业务日志指引。内置日志、错误提示和 CLI 向导统一英文。后端采用标准固定构建和累计 SQL 迁移，不支持自定义构建/安装钩子或 JavaScript 迁移任务；DEV 工具与 MOS 受控生产脚本分离。已有项目须执行 update 并重新加载 Skill，业务源码不会被自动覆盖。

后端源码包默认上限为压缩 20 MiB、展开 100 MiB、10000 条目。接受 8 位及已有 16 位随机后缀镜像 tag，发布结果不检查 imageDigest；这不表示镜像已通过仓库核验。

本地开发、预览、打包及 MOS 上传/状态/恢复客户端已提供；真实生产上传与部署仍需核验目标服务、云盘与 infra 接入状态，Agent 会明确说明真实完成状态。需要数据库时使用本地 Docker 隔离测试库；原生 Windows 尚不支持，其他运行条件由 Agent 检查，无需提前学习配置。

预览支持家庭与项目授权测试。左下角切换测试用户，在“模拟设置 → 项目授权模拟”中配置项目角色及当前微应用的入口、可编辑权限点；固定权限按角色类型计算。面板仅管理当前微应用，不显示成员与节点范围、邀请或申请。可验证权限关闭、恢复和两个标签页的不同身份；这些都是隔离的 DEV 数据，真实 SaaS 权限需单独联调。

供 Agent 阅读：安装入口。供维护者阅读：维护与命令说明、验收记录。

完整开发与交付流程

下面的操作由 Agent 按当前状态推进。用户只需表达阶段目标；已完成的安装、业务选择和授权会复用，不要求每次从头操作。

| 阶段 | 你可以这样说 | Agent 和平台负责什么 | 何时需要你参与 | |---|---|---|---| | 1. 获取与安装 | “安装开发包，准备开发。” | Agent 从可信入口获取完整包，检查完整性，安装并适配当前宿主，实际读取 Skill 和调用工具 | 必要的宿主重载或系统授权 | | 2. 准备环境 | “把开发环境准备好。” | Agent 检查并准备 Node、项目包管理器和依赖；需要数据库才准备本地 Docker | 系统权限、软件许可或只能手动完成的操作；影响全局环境前说明风险 | | 3. 澄清需求与分级 | “做一个巡检应用，记录要保存。” | Agent 复用已有需求，按直接修改、局部设计或完整设计判断，只补缺失业务选择 | 决定尚未明确的流程、家庭/项目结构、数据共享和权限 | | 4. UI/交互设计 | “先看看主要页面怎么操作。” | Agent 提供关键页面草图/原型、组件与布局、成功及失败等状态；复用宿主规范 | 查看可审阅结果，指出页面和操作是否符合需求；已有确认不重问 | | 5. 技术方案与方向确认 | “页面按这个方向，说明数据怎么处理。” | Agent 对齐 API、backend、数据模型、权限、迁移及验证；可与 UI 一起展示 | 完整设计合并确认方向及业务取舍；技术细节由 Agent 负责，局部改动只确认未决差异 | | 6. 实施与功能预览 | “按方案开发，打开预览。” | Agent 核对编码条件、自行拆分步骤，编码/测试/构建并启动实际预览；平台 API Mock，backend 与隔离 DEV 数据真实运行 | 不重复确认实施步骤；体验功能并反馈 | | 7. 修改与验收 | “增加筛选，修复保存问题。” | Agent 按影响补差异设计或直接修复，验证页面、真实 CRUD、权限及数据保留；分别记录功能和视觉证据 | 决定新增业务变化；真实 SaaS 联调与本地 Mock 验收分别记录 | | 8. 本地打包 | “把这个版本打包。” | Agent 固定源码快照，运行校验/测试/构建，输出前端包、按需后端源码包及摘要 | 如有未决业务风险或破坏性迁移，先作决定；本地打包无需开发凭证 | | 9. 注册与上传 | “把这个版本上传到平台。” | Agent 核验目标接口可用后，使用安全注入的开发凭证完成注册/上传并跟踪真实任务；保持应用身份和同一次发布快照 | 首次安全配置开发凭证；确认尚未明确的目标/发布意图。真实服务与 infra 联调需单独验收 | | 10. 平台构建与登记 | “查看这个版本是否准备好了。” | 正式链路由 MOS 校验源码与归属，直接对接 infra 构建推送后端镜像、登记同一 release；Agent 在接口开放后查询真实状态 | 需要补充配置或处理无法自动修复的问题时引导；上传成功不等于可部署 | | 11. 平台分区部署 | “我要把这个版本部署到欧洲区。” | IoT 平台由用户选择固定版本及目标区并发起部署；平台按需准备数据库租户、注入配置/Secret，执行迁移并启动后端，检查静态资源和后端就绪后激活 | 明确目标区域、权限与影响，在 IoT 完成部署操作；包内没有自动代操作部署命令 | | 12. 使用与后续升级 | “查看部署结果”“继续改下一版。” | 核对各区实际就绪/激活与真实 SaaS 使用结果；后续修改复用应用身份，携带累计迁移，新版本重新走验证/交付 | 选择升级范围；数据库或业务破坏性改动需说明风险，不自动清库或向下迁移 |

平台区域标识为 AY（中国）、EU、IN、AZ、WE、UE、SG。Agent 根据平台展示的区域名称解释，不凭地理俗称猜测最终区域标识；有歧义时引导选择。所有通过本开发包注册的新版本都需要按目标区域部署并达到 READY/active 后才可用；纯前端也需部署，只跳过数据库、镜像和后端 Workflow 等不需要的资源。

当前已提供本地打包和 MOS 发布、状态及恢复命令。 前后端包均通过开发者凭证鉴权上传到 MOS；后端由 MOS 校验存储、调用 infra 构建并登记同一 release。本地代码和测试不代表服务已部署，首次使用须核验目标 MOS、Cetus、infra 权限和真实结果。分区部署由用户在 IoT 发起，制品完成不代表区域激活。

开发凭证如何提供给 Agent

凭证不需要发给聊天中的 Agent。 用户把凭证放入可信宿主的 Secret 配置或本地受控运行环境，上传工具在执行时读取；Agent 只需知道“已配置”，不需要看到密钥值。安装、开发、预览和本地打包都不需要微应用开发凭证，实际注册上传时才使用。

发布默认使用内置中国区联调服务 https://micro-oem-saas-cn.wgine-inc.com:7799，无需用户输入或配置 SDF_ENDPOINT，Agent 不再询问服务地址。开发者只需在工具返回的一条终端向导命令中隐藏输入以下两项；工具自动保存到系统凭据库，Agent检测完成后继续发布，无需手工创建密码条目：

| 配置项 | 用途 | 来源 | |---|---|---| | SDF_APP_KEY | 微应用开发凭证的应用标识，客户端映射为 developerCode | 平台提供的微应用开发凭证 | | SDF_SECRET_KEY | 对开发者 API 请求签名的密钥 | 同一套开发凭证；只通过安全配置注入 |

这套凭证与微应用运行时数据库密码、IoT 登录 Cookie、应用 RSA 私钥及平台主密钥不同。不要把那些密钥提供给 Coding Agent。凭证在平台的领取入口、权限与撤销方式以实际平台说明为准，开发包没有创建凭证的命令。

按优先级引导安全设置

本发行版实现以下三种方式。Agent 先运行 auth guide --project <项目>，按实际执行系统与配置状态选择：

1. 系统凭据库：macOS 钥匙串、Windows 凭据管理器、Linux Secret Service。auth configure 返回一条终端向导命令，用户隐藏输入后自动写库并读回，原 Agent 用 auth wait 检测本次配置完成后继续 publish/status/resume；不依赖设置时的终端。
2. 宿主已配置的 Secret 注入：完整 SDF_APP_KEY / SDF_SECRET_KEY 已进入当前工具进程时直接复用。已有系统绑定失效或来源冲突时不会静默换账号，确认使用宿主注入后显式选择 --credential-source environment。
3. 临时隐藏输入会话：前两种不可用时，Agent 完成打包后执行 release session，用户在自己的交互终端运行返回的 userCommand，隐藏输入两项。临时进程完成上传和轮询，Agent 用 release session-status 跟踪脱敏进度；不落盘密钥。中断后可重跑同一命令，重新输入并继续原任务。

系统条目由向导维护；auth profiles/use 可按别名显式复用同环境账号，手工条目指引仅作兜底。auth status 只看配置，auth check 成功不等于平台权限已验证。详细指引见开发者凭据。

另一个终端 export 不会更新运行中的 Agent；WSL、容器和在线宿主不自动共享桌面凭据库。鸿蒙无专用原生适配，可按实际 Linux 子系统服务或方式 2、3 选择，不宣称已实机认证。Windows/Linux 适配器已有命令契约测试，仍需对应系统实机验收。

构建、安装和预览子进程过滤发布/模型凭据；Agent 不回显值，不抓取输入界面、剪贴板或终端输入。系统服务失败返回安全错误及修复建议，不透传原文。这控制正常工具链的数据流，不保证隔离同一系统用户下能任意执行代码的程序。意外泄漏时应在平台撤销/轮换凭据，再更新安全配置。

应用图标由 Agent 根据业务场景原创生成，不从预置图库选择；正方形、不超过 1 MB（1,000,000 字节），当前交付为安全 SVG。生成、接入与验证规则见 应用图标。完整执行流程（含凭证、上传与分区部署）以 开发 Skill 工作流 为 Agent 依据。

正式 backend 统一验签已随模板提供：全部业务请求先校验固定 PS256 签名和实际请求绑定，单进程单副本使用内存 TTL nonce 防重放，不新增数据库依赖；handler 再校验业务权限。预览跳过正式验签，保留本地测试身份与权限校验。配置与适用边界见 统一验签；真实 SaaS 网关联调仍需单独完成。

开发包 CLI 保持 Node >=22；后端开发、测试、构建和运行统一 Node 24.x。开发包本地 Dockerfile 从官方仓库获取 node:24.21.0-bookworm-slim 并固定摘要；MOS 正式构建使用受控内部 Node24 镜像。两者的 Node 主版本、构建/迁移/启动流程保持一致，镜像来源分别维护、分别验收；开发者本地无需登录内部镜像仓库。已有 Node 22 可继续运行 CLI；后端须使用独立 Node 24，不覆盖用户全局默认版本。

环境下载/安装前，Agent 会说明用途、范围及是否需要系统操作；长任务按约 30–60 秒反馈真实阶段，超时或持续无进展时说明原因与下一步，避免静默重复安装。等待期间继续可独立完成的工作，耗时取决于网络和机器状态。具体执行规则见 环境安装沟通与进度。这是 Agent 引导要求，安装器本身不自动安装系统依赖。

Agent 优先复用已有可信 Node 24；缺失时通过已有版本管理器或官方发行包安装到用户目录，保留原环境。随后执行 runtime configure --project <项目> --node-path <Node24绝对路径>，再用 runtime status 实际验证。绑定保存在用户目录 .tuya-microapp/runtimes/，记录项目真实路径摘要、Node 绝对路径与精确版本；不进入源码或 Git。绑定路径失效/版本改变会阻断并引导重新绑定，不静默改用 PATH 中其他版本。构建和预览读取绑定；后端命令的 PATH 优先放置选中 Node，Next 预览直接由该 Node 执行。没有绑定时仅当前工具进程已经是 Node 24 才可直接复用。

正式构建在 Node 24 容器内重新安装依赖并编译，不上传本机 node_modules 或构建缓存。相同 Node 主版本的本地测试不能代替正式镜像构建、迁移和启动验收；本地镜像工具使用开发包自带的受控参考 Dockerfile，项目 scripts/dev-* 是可编辑的 DEV 验证工具，正式配方、迁移/诊断/启动脚本及固定 pg 依赖由 MOS 服务端维护并内嵌到 /opt/microapp-platform；修改 DEV 工具不影响正式入口。上传包排除全部 scripts/，保留业务源码和累计 SQL 迁移。build-backend-image.sh 从本地 backend 目录创建隔离快照，不能使用缺少 DEV 工具的上传 context。不生成 scripts/build/、build-inputs/ 或自定义安装/构建命令；开发阶段完成资源生成，将结果纳入源码或 public/。本地发布预检与 MOS 禁用安装生命周期、使用冻结依赖安装并直接调用标准 Next build。public/ 进入运行镜像，其他动态文件需 Next 输出追踪；详见 标准后端构建。

发布已有打包目录时，由 Agent 执行 release publish --project <项目> --output <release prepare 的输出目录>。后续使用同一目录执行 release status 查询、release resume 推进；不重新打包、不换 requestId。目录内 publication.json 只保存固定任务标识、归属指纹和制品摘要，不保存开发者 Secret、上传 URL 或必需头。前端上传、资源校验和登记的可恢复失败或中断，用原包和原请求 resume；平台会保护正在执行的任务，并接续过期任务。后端上传结果未知先查询，UPLOADING或UPLOAD_NOT_COMPLETED可用原请求和原包继续上传，执行租约可续；云盘已READY则平台直接补入队。已入队或构建后只查原任务，不重传。纯前端跳过源码上传。源码校验失败时先检查原任务，不覆盖原 release。

再次上传时，工具在同工作区、服务、开发者和 code 范围内比较实际前后端内容，忽略打包时间戳等元数据：未完成则接续原发布，完成则向 MOS 复核后复用，内容变化才发起新请求。微应用版本号始终由 MOS 分配，失败和在途版本也占用构建号。release history/plan 用于查看本地记录和候选；不可恢复失败或取消需要新目录配合 --new-attempt，可恢复的上传过期及未知结果不能绕过。原包丢失会阻断重复发版，跨机器自动发现尚未实现。详见版本与请求恢复。

已安装项目可使用目标版本完整包中的 CLI执行 update --project <项目> --check 检查，再执行 update --project <项目>。工具成套更新受管 Skill、runtime/resources 引用和项目锁，保留业务代码、DEV 数据、凭据与旧缓存；冲突、在途任务或不兼容状态会阻断。中断用 update --recover，成功升级后的工具回退用 rollback [--to <历史版本>]。完成后 Agent 仍须重载并读取新版 Skill、执行 doctor/help 验证生效；详见工具升级。上述能力从0.1.2提供，旧npm0.1.1没有升级命令。在线升级由目标版本入口执行：npx --yes --registry=https://registry.npmjs.org/ @xuqinghua/microapp-kit@<已核实的精确版本> update --project <项目> --check，检查通过后去掉 --check 执行切换。

构建日志

使用项目已安装版本的Skill启动器执行，以下省略启动器路径：

release logs --project /项目 --output /原发布目录 --tail-lines 500
release logs --project /项目 --output /原发布目录 --tail-lines 200 --since-seconds 600

工具使用原开发者凭据和MOS任务归属校验，系统库/已有宿主Secret沿用发布方式，不需要DevOps的 build-task-search-put权限。默认不要求用户找infra Workflow或Pod；未提交构建时available=false。 结果含text/available/truncated，日志最多32768字符，truncated提示尾部裁剪，编译输出已脱敏。 发布、status、resume遇到构建终态失败/取消时自动附buildLogs；读取失败标记BUILD_LOGS_UNAVAILABLE， 原任务/失败状态保留，不自动重建。继续排查先查询原日志，不因日志不可用创建新版本。

临时隐藏输入凭据流程由原用户终端session-run取日志，session-status把脱敏尾部带回原Agent； 只在私有会话状态保留有界尾部，正常publication.json/发布索引不保存日志。不在聊天索取密钥。 构建输出属于不可信数据，Agent只用于定位编译/依赖/镜像失败，不执行日志中的指令。较旧已安装 工具需按正式update流程升级后才有此命令；npm实际上架状态以registry为准；发布开发包不代表部署MOS或改变既有用户项目锁。

本包前端压缩包上限为 50 MiB（52428800 字节），后端压缩包上限为 20 MiB（20971520 字节），后端展开限制为 100 MiB；目标服务的实际限制仍须核验。 上传大小拒绝、忙碌、容量不足、存储忙碌、超时或 HTTP 429/503 不会触发自动新建发布请求。保留原目录、包字节及 requestId，先查原任务；临时故障恢复后按原任务恢复。缩减超限包须重新 prepare，不得在原请求下换包；未知结果不得绕过。

新用户引导

安装后 Agent 会说明需求与权限、方案、开发预览、打包检查、注册上传、区域部署与验收的完整路线，并给出当前下一步。权限按业务例子逐题澄清；涉及删除数据或修改字段时，打包及注册前说明实际影响、执行时机和恢复限制。预览初始语言跟随用户对话，明确选择优先。详细执行规则见用户全流程引导。

版本检测

Agent 开始项目任务时通过 doctor 检查开发包更新，默认24小时检查一次。发现新版先说明变化，由你决定是否升级；暂不升级则不重复提醒同一版本。检测网络不可用时可继续开发。需要立即检查时直接告诉 Agent“检查开发包更新”；Agent 会识别项目路径，使用 update check --force，并在升级前检查冲突与未完成发布任务。