把一个源码 ZIP 导入为新的 Web 项目，可选使用 AI 适配或修复。导入和发布是两个操作：导入不会部署，发布失败时可以单独重试发布。
首期不支持覆盖已有项目，不接受
完整项目要求与最小示例见项目导入与发布。如果已经有构建好的静态产物，也可以选择现有的直接上传静态产物流程。
源码 ZIP 通过 multipart 直接上传到本接口，当前不接受 OSS URL，也不提供源码导入的 prepare/complete。静态产物的 OSS 直传是独立发布流程。
导入入口只创建一个新的 Web 项目，不提供覆盖、合并多个工程、自动发布或按导入提交 ID 发布的能力。已识别为 App、小程序的导出包不支持；也不承诺把任意语言、框架或依赖服务自动转成可部署应用。AI 适配是可选的工程修改过程，不是发布成功保证。
需要
ZIP 会经过路径、文件类型和实际解压大小检查，最多 10,000 条目，单文件展开后最大 20 MiB，展开总量最大 200 MiB。源码可以直接放在 ZIP 根目录，也可以统一放在一个顶层目录；不要把多个独立项目一起打包。请使用常规 ZIP 工具生成未加密的 ZIP，文件名使用 UTF-8，不要包含链接、特殊文件或路径穿越。导入复用现有的 ZIP 读取和源码内容审核流程；内容审核不通过时不会创建项目。
Meoo 导出包与首页使用相同的识别规则，平台通过导出标识校验后保留原有运行方式：旧 Meoo Web 项目不需要补
不要手动设置 curl 的
成功建立连接后返回
关闭 AI 的完成示例：
按 Agent 协议处理交互、完成或失败事件。AI 运行失败时，继续处理该项目即可，无需再次导入并创建新项目。
导入完成且可选 AI 适配完成后，调用现有 发布 API：
该操作发布项目当前源码，沿用 Meoo 项目的原有构建方式；使用 mise 的项目由
详细错误包装、追踪 Header 和通用重试规则见通用协议。
project_id、override、发布选项或已有项目凭证。需要更新已导入项目时，可以使用项目编辑或 Agent 能力。
先选择接入方式
| 手里的项目 | 导入选项 | 后续操作 |
|---|---|---|
| Meoo 导出的 Web 项目 | ai_adapt=false（默认） | 保留原有运行方式，等待 import.completed 后单独发布 |
| 已准备好符合平台协议的外部 Web 源码 | ai_adapt=false（默认） | 等待 import.completed，再单独发布 |
| Web 源码需要识别、补齐运行配置 | ai_adapt=true | 等待导入完成，再等 AI Run 完成，最后单独发布 |
暂时只保存外部源码，没有 mise.toml | ai_adapt=false | 可以导入；补齐协议前不能发布 |
导入新项目
project.write 和 source.write。ai_adapt=true 还需要 agent.run；后续查询 AI 状态和事件需要 agent.read，发布需要 release.write。
请求是 multipart 表单，所有普通字段以字符串传递，每个字段只提交一次；不定义重复普通字段的取值行为：
| 字段 | 必填 | 说明 |
|---|---|---|
file | 是 | 一个 .zip 源码文件，压缩包最大 100 MiB；不能传多个文件 |
name | 否 | 新项目名称，去除首尾空白后为 1–100 个字符；省略时从 ZIP 文件名推导 |
ai_adapt | 否 | 字符串 true 或 false，默认 false |
mise.toml，原本使用 mise 的项目继续使用现有配置。请保留原始导出包中的 manifest；无法验证导出标识的包会按普通外部源码处理。
普通外部源码导入时不要求包含 mise.toml，但发布前需要补齐有效的 mise 配置。不要依赖上传 .git、node_modules、本地虚拟环境或 .env 来恢复运行环境：这些内容会被过滤或被安全检查拒绝。依赖应通过工程配置重建，环境变量另行配置。导入仍会执行内容安全检查；关闭 AI 不会跳过检查，也不意味着 ZIP 按字节原样恢复。
Content-Type，让它生成匹配的 multipart boundary。
导入事件和结果
成功建立连接后返回 text/event-stream，使用命名事件；客户端应忽略注释心跳和未知事件。
| 事件 | 含义 |
|---|---|
import.started | 已受理导入，包含 import_id |
import.progress | 导入阶段或进度更新 |
import.completed | 源码已导入、提交并持久化；同时返回可选 AI 的启动结果 |
import.failed | 导入失败或执行结果无法确认，包含 import_id、code、message；已经创建项目时包含 project_id |
project_id 是新项目的公开 URL ID，后续发布使用它即可，无需处理 Git 提交 ID，也无需调用 NAS 保存或 push 接口。初始化流程会完成源码持久化；import.completed 之后才可进入后续步骤。
调用顺序要求： 创建项目和写入源码在同一个导入接口内执行，但项目记录会先于源码写入完成。在收到 import.completed 前，请勿通过网页、CLI 或其他接口编辑该项目、启动 Agent、发布或删除项目。服务端不对这些入口额外加锁，并发操作可能导致源码不完整或导入失败。若开启 AI，收到完成事件后还应等待 AI Run 结束再发布。导入失败时请核对项目状态，确认原任务结束后删除遗留项目，再重新导入。
可选 AI 适配
ai_adapt=true 在源码导入成功后启动现有 Agent Run。旧 Meoo 项目沿用原框架和构建发布方式，AI 按需修复依赖、源码和运行配置；使用 mise 的项目通过 mise-import 补齐配置并验证预览。开启此选项即允许这类配置和源码修改。该适配任务禁用平台云服务开通，不执行正式发布。
import.completed.data.ai 有三种状态：
| 状态 | 字段 | 后续操作 |
|---|---|---|
skipped | status | 未请求 AI，按需检查发布配置后发布 |
started | status、run_id | AI 已启动，订阅 Run 事件并等待完成 |
failed | status、error.code、error.message | 源码导入成功，但 AI 启动失败或无法确认；先查询当前 Run，再通过现有 Agent 接口继续处理 |
started 不表示 AI 已完成。使用现有 Agent API：
单独发布
导入完成且可选 AI 适配完成后，调用现有 发布 API：
mise.toml 决定构建方式。调用方可以封装「导入 → 等待 AI（可选）→ 发布」的一键流程。
重试和错误
Idempotency-Key 必填，允许 1–128 个字母、数字、下划线或连字符。在 24 小时幂等窗口内，同一凭证、同一用户以相同 ZIP 和表单选项重试相同 Key，会接续最新进度或返回最终结果，不重复创建项目或启动 AI。不同文件或选项应使用新 Key；改变 Key 会创建另一个项目。
幂等窗口不会延长凭证有效期。重新签发的团队成员 Token 属于新的凭证，不能依靠旧 Key 跨 Token 去重。请及时保存 project_id、import_id 和终态；凭证过期后先核对已创建的项目，不要用新 Token 盲目重传旧请求。正常断线重连应复用仍有效的原凭证。
客户端断开不会取消后台导入。重连时重新提交同一请求，包括文件和 Key；接口只保留最新进度及最终结果，不提供完整历史事件回放，也不使用 Last-Event-ID。超过幂等窗口后不要把同一个 Key 当作永久查询句柄，应保存成功返回的项目 ID。
建流前的参数、权限、上传大小和幂等检查错误使用标准 application/problem+json。项目额度、ZIP 结构和内容审核属于导入任务阶段，失败通过 import.failed 返回，不能仅凭 HTTP 200 判断成功。若连接异常关闭且未收到终态，用同一请求重连确认结果。
源码内容审核失败时，import.failed.data.code 为 forbidden；超出扫描支持范围为 artifact_invalid；审核服务异常为 service_unavailable。前两种情况需修改源码包后用新 Key 导入；审核服务异常可稍后用新 Key 重试，原 Key 仍返回原失败结果。
已有记录但执行长时间无进展时，返回 import.failed，错误码为 import_interrupted，表示结果无法确认，不代表源码一定未保存。接口不会查询项目数据库来推断成功，同一 Key 的重试只返回已有结果，不重新执行导入。有 project_id 时检查该项目；没有时通过项目列表按名称和创建时间查找。若请求了 AI，也要检查当前 Agent 任务。确认无需保留且任务已结束后，再删除遗留项目、用新 Key 导入。
幂等依赖缓存记录。记录完全丢失或过期后，同一 Key 再次提交也可能被当作新请求，不能保证去重。遇到结果无法确认或状态记录过期时，先核对项目和 Agent 任务，不要盲目重传。
单次导入最长运行 24 小时；超时后停止后续写入。未收到明确结果前，优先使用同一请求重连核对，避免删除仍在导入的项目。
| HTTP 状态 / 错误码 | 处理方式 |
|---|---|
400 invalid_request | 检查 multipart、ZIP 文件字段、表单选项及幂等 Key |
403 insufficient_scope / forbidden | 检查权限，导入必须使用可创建新项目的身份 |
403 quota_exceeded | 检查项目或相关服务额度 |
409 import_conflict | 同一 Key 已绑定其他输入，确认是否确实需要创建另一个项目 |
409 import_state_expired | 幂等状态不完整或已过期，先核对已有项目再决定是否重新导入 |
413 artifact_too_large | 缩小源码包 |
import.failed: import_interrupted | 结果无法确认，检查已创建项目和 Agent 任务；同一 Key 不会重新执行或自动恢复为成功 |