> ## Documentation Index > Fetch the complete documentation index at: https://docs.meoo.com/llms.txt > Use this file to discover all available pages before exploring further. # 源码导入 API 把一个源码 ZIP 导入为新的 Web 项目，可选使用 AI 适配或修复。导入和发布是两个操作：导入不会部署，发布失败时可以单独重试发布。 首期**不支持覆盖已有项目**，不接受 `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` | 可以导入；补齐协议前不能发布 | 完整项目要求与最小示例见[项目导入与发布](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/2c3751d3-8fbe-4d53-a71b-f992e96c7044)。如果已经有构建好的静态产物，也可以选择现有的[直接上传静态产物](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/e0c02cae-8c7f-4fda-b17b-ca6303fe4903)流程。 源码 ZIP 通过 multipart 直接上传到本接口，当前不接受 OSS URL，也不提供源码导入的 prepare/complete。静态产物的 OSS 直传是独立发布流程。 导入入口只创建一个新的 Web 项目，不提供覆盖、合并多个工程、自动发布或按导入提交 ID 发布的能力。已识别为 App、小程序的导出包不支持；也不承诺把任意语言、框架或依赖服务自动转成可部署应用。AI 适配是可选的工程修改过程，不是发布成功保证。 ## 导入新项目 ```text theme={null} POST /open/v1/projects/import Authorization: Bearer Idempotency-Key: import-source-001 Content-Type: multipart/form-data; boundary=... ``` 需要 `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` | ZIP 会经过路径、文件类型和实际解压大小检查，最多 10,000 条目，单文件展开后最大 20 MiB，展开总量最大 200 MiB。源码可以直接放在 ZIP 根目录，也可以统一放在一个顶层目录；不要把多个独立项目一起打包。请使用常规 ZIP 工具生成未加密的 ZIP，文件名使用 UTF-8，不要包含链接、特殊文件或路径穿越。导入复用现有的 ZIP 读取和源码内容审核流程；内容审核不通过时不会创建项目。 Meoo 导出包与首页使用相同的识别规则，平台通过导出标识校验后保留原有运行方式：旧 Meoo Web 项目不需要补 `mise.toml`，原本使用 mise 的项目继续使用现有配置。请保留原始导出包中的 manifest；无法验证导出标识的包会按普通外部源码处理。 普通外部源码导入时不要求包含 `mise.toml`，但发布前需要补齐有效的 mise 配置。不要依赖上传 `.git`、`node_modules`、本地虚拟环境或 `.env` 来恢复运行环境：这些内容会被过滤或被安全检查拒绝。依赖应通过工程配置重建，环境变量另行配置。导入仍会执行内容安全检查；关闭 AI 不会跳过检查，也不意味着 ZIP 按字节原样恢复。 ```text theme={null} curl -N 'https://meoo.com/open/v1/projects/import' \ -H 'Authorization: Bearer ' \ -H 'Idempotency-Key: import-source-001' \ -F 'file=@./project.zip;type=application/zip' \ -F 'name=导入的项目' \ -F 'ai_adapt=false' ``` 不要手动设置 curl 的 `Content-Type`，让它生成匹配的 multipart boundary。 ## 导入事件和结果 成功建立连接后返回 `text/event-stream`，使用命名事件；客户端应忽略注释心跳和未知事件。 | 事件 | 含义 | | :----------------- | :----------------------------------------------------------------------------------- | | `import.started` | 已受理导入，包含 `import_id` | | `import.progress` | 导入阶段或进度更新 | | `import.completed` | 源码已导入、提交并持久化；同时返回可选 AI 的启动结果 | | `import.failed` | 导入失败或执行结果无法确认，包含 `import_id`、`code`、`message`；已经创建项目时包含 `project_id` | 关闭 AI 的完成示例： ```text theme={null} event: import.completed data: {"import_id":"imp_example","project_id":"demo","conversation_id":"123","ai":{"status":"skipped"}} ``` `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](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/0cacadf2-712b-4a08-9c29-550e056ef249)： ```text theme={null} GET /open/v1/projects/{project_id}/agent/runs/{run_id}/events GET /open/v1/projects/{project_id}/agent/runs/current ``` 按 Agent 协议处理交互、完成或失败事件。AI 运行失败时，继续处理该项目即可，无需再次导入并创建新项目。 ## 单独发布 导入完成且可选 AI 适配完成后，调用现有 [发布 API](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/b31b1b0b-7d62-41df-a2f9-3643354ac937)： ```text theme={null} curl -N 'https://meoo.com/open/v1/projects/demo/releases' \ -H 'Authorization: Bearer ' \ -H 'Idempotency-Key: publish-demo-001' \ -H 'Content-Type: application/json' \ --data '{}' ``` 该操作发布项目**当前源码**，沿用 Meoo 项目的原有构建方式；使用 mise 的项目由 `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 不会重新执行或自动恢复为成功 | 详细错误包装、追踪 Header 和通用重试规则见[通用协议](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/de50f6a7-356b-405b-9dbe-374db0e46b3e)。