> Aholo 国内开放平台（api.aholo3d.cn）3D 任务技能，非 2D 文生图。默认由 Agent 代跑 aholo_reconstruct.py，用户仅需配置 AHOLO_API_KEY。
适用： 3D 重建（reconstruction）、3D 生成（generation）、查询/轮询 worldId、获取 PLY/SPZ/SOG。
不适用： 2D 效果图/文生图；未要求 3D 结果（worldId、模型文件、在线预览）。
歧义必先澄清（2D vs 3D）： 例如「按参考图生成房间」→ 问用户要 2D 单图还是 3D 任务（worldId 可轮询）；仅选 3D 时进入本 skill。
| 项 | 说明 |
|---|---|
| ---- | ------ |
| 环境变量 | AHOLO_API_KEY（api-keys） |
| 鉴权 | Authorization: ，无 Bearer |
| 创建请求头 | x-source: skills → 平台 OPEN_API_SKILL |
| 网关 | https://api.aholo3d.cn；上传凭证 GET /asset/v1/token；世界任务 /world/v1/* |
| 查看链接 | https://studio.aholo3d.cn/3dgs-model/{worldId} |
| 脚本动作 | create / create-reconstruction / create-generation / status / poll / list |
| 创建成功 | WorldAsyncOperation 仅含 worldId |
| 积分不足 | bizCode 11003 或 insufficient credits → 告知积分不足，引导前往 www.aholo3d.cn/pricing 购买积分；禁止编造链接；禁止对同一视频/同一笔意图重复 create* 重试 |
缺 AHOLO_API_KEY： 说明如何配置环境变量，请用户回复「继续」后由 Agent 代跑；禁止把「用户自己执行 python 命令」作为主路径。
AHOLO_INSECURE_SKIP_VERIFY=1（或 true / yes / on）可显式关闭校验；更推荐用 REQUESTS_CA_BUNDLE 指定企业 CA 证书。CERTIFICATE_VERIFY_FAILED 时，优先配置 CA 证书；仅在确认网络环境安全时再使用 AHOLO_INSECURE_SKIP_VERIFY。WorldAsyncOperation，仅含 worldId。ApiError：code、message、status、details.metaData.bizCode（如未登录 10004、积分不足 11003）。| # | 约束 |
|---|---|
| --- | ------ |
| 0 | 2D 出图诉求 → 禁止本 skill 的 create/status/poll |
| 7 | 未明确要 3D → 先做 2D/3D 二选一（与 §1 一致），再创建 |
| 1–3 | 仅 reconstruction：未确认 scene（model/space）与 taskQuality（low/normal/high）→ 禁止 create；禁止默认 model/high 等替用户下单 |
| 1–4 | 仅 reconstruction：初始 AskQuestion 确认轮中必须同时包含 useMask 选项（注明"仅 scene=model 时生效，选 space 时忽略"）；禁止默认 false 跳过询问；禁止在单独的第二轮中延后询问 |
| 4 | generation：不问 scene/taskQuality；prompt 与 imagePaths 就绪后 create-generation |
| 8 | 图片目录 → 必须 imageDir 上传全部图片；禁止只传部分（如前 20 张） |
| 11 | 多个视频：创建前必须问用户（禁止代选）：A 合并为一个 3DGS（一次 create，videoPaths 含全部）；B 每个视频各一个 3DGS（见 #9 多笔例外）。仅 1 个视频不必问 |
| 9 | 创建 POST（高成本） — 默认：用户单笔 3D 诉求（一个 worldId 目标）在本轮对话中 最多 1 次 create；成功/失败/超时/未解析 worldId 均禁止在同意图下再次 create，除非用户明确重新下单。上传前失败（未发出 POST）→ 修正后可发该笔的首次 create。疑似已扣费无 worldId → 引导任务列表或 status/list，禁止用再 create 排错。多视频选 B：用户已明确「各建」时，按视频数量依次 create（每视频 videoPaths 仅 1 个）；开始前告知 N 笔任务/扣费；禁止对同一视频重复 create；单次失败不得重试该视频，可对尚未创建的视频继续。误防重复：仅在对已完成的那一笔误触时再传 forbidCreate: true |
| 10 | projectName：用户未明确要求 → 禁止传入；禁止用目录名/时间戳编造 |
| 5–6 | 每个 worldId 创建后 → 必须先问是否等待；愿等则同步 poll 至终态；不愿等则返回 worldId + studio 链接。禁止后台 poll 并承诺「完成后通知」；禁止未问就 poll |
taskQuality 展示名（传参仍用枚举）| 枚举 | 展示 |
|---|---|
| ------ | ------ |
low | 极速预览 |
normal | 标准 |
high | 专业（推荐） |
reconstruction 或 generation。AskQuestion 优先，一轮内同时确认 scene、taskQuality、useMask（见 §5 模板）；自由文本先映射再确认。useMask 须注明"仅 scene=model 时生效，选 space 时忽略"；禁止拆成两轮询问。token → 上传素材 → create（遵守 §3 #9、#11）。worldId；询问是否等待（§5 模板）。poll（建议 intervalSeconds=60，timeoutSeconds=14400）；不等 → 仅返回链接，后续可 status/poll。重建 — 初始确认（scene、taskQuality、useMask 一轮完成）：
用 AskQuestion 同时询问以下三题，不拆轮：
| 题 | 选项 |
|---|---|
| ---- | ------ |
| scene（场景） | 物体 model / 场景 space |
| taskQuality（质量） | 极速预览 low / 标准 normal / 专业 high（推荐） |
| useMask（是否抠图） | 开启（自动去背景，适合纯色背景）/ 不开启（保留原始背景，默认）— 仅 scene=model 时生效，选 space 时忽略 |
多视频（2–3 个）：
你提供了 N 个视频，请确认（不要替我选）：
A) 合并为一个 3DGS — 一个 worldId
B) 每个视频单独一个 3DGS — N 个 worldId（将创建 N 笔任务，按视频逐个处理）
创建成功后：
任务已创建，worldId: {worldId}
完成后查看: https://studio.aholo3d.cn/3dgs-model/{worldId}
（完成前链接可能不可用）
是否等待任务完成？
- 等待 / yes — 本会话内同步 poll 直到结束
- 不等 / no — 稍后 poll 或自行打开链接
videoPaths（数量不限）或 imagePaths / imageDir（≥20 张），二选一.mp4 / .mov → type=video；.insv（Insta360 全景视频）→ type=insv；按扩展名自动区分scene、taskQualityuseMask（boolean，是否对上传资源抠图；仅 scene=model 时生效，默认 false，scene=space 时忽略）imageDir 扫描 jpg/jpeg/png/webp（不含 bmp/gif）prompt 与图不能都空；无 videoPaths；无 scene/taskQuality| 参数 | 说明 |
|---|---|
| ------ | ------ |
action / workflow | 见 §2 |
imageDir | 目录重建首选 |
videoPaths | 数量不限；.insv 自动识别为 type=insv，其余为 type=video |
useMask | boolean，是否抠图（可选，仅 reconstruction + scene=model，默认 false） |
worldId | status / poll |
pageNum / pageSize / statusList | list 分页查询参数 |
forbidCreate | 防止同一笔误重复 create；多视频 B 的下一视频不要误开 |
python -u）JSON 参数作为第二个 argv、单行传入（与下方示例一致）。Windows PowerShell 见下节。
# 重建（图片目录）
python -u .cursor/skills/aholo-3dgs-reconstruction/aholo_reconstruct.py '{"action":"create","workflow":"reconstruction","imageDir":"D:/images","scene":"space","taskQuality":"high"}'
# 重建（Insta360 全景视频，自动识别 .insv → type=insv）
python -u .cursor/skills/aholo-3dgs-reconstruction/aholo_reconstruct.py '{"action":"create","workflow":"reconstruction","videoPaths":["D:/room.insv"],"scene":"space","taskQuality":"high"}'
# 重建（开启抠图）
python -u .cursor/skills/aholo-3dgs-reconstruction/aholo_reconstruct.py '{"action":"create","workflow":"reconstruction","videoPaths":["D:/obj.mp4"],"scene":"model","taskQuality":"normal","useMask":true}'
# 生成
python -u .cursor/skills/aholo-3dgs-reconstruction/aholo_reconstruct.py '{"action":"create-generation","imagePaths":["D:/seed.jpg"],"prompt":"modern minimal interior"}'
# 轮询
python -u .cursor/skills/aholo-3dgs-reconstruction/aholo_reconstruct.py '{"action":"poll","worldId":"xxx","intervalSeconds":60,"timeoutSeconds":14400}'
# 查询列表（运行中+成功）
python -u .cursor/skills/aholo-3dgs-reconstruction/aholo_reconstruct.py '{"action":"list","pageNum":0,"pageSize":20,"statusList":["RUNNING","SUCCEEDED"]}'
用户在 Windows 上时，Agent 用终端跑脚本须遵守：
&& 链式命令）；多条命令用 ; 分隔，或只发一条 python -u ...。'{ ... }' 折行写法（PowerShell 会拆参失败）。D:/images/0001.jpg，避免未转义反斜杠。cd 到含 .cursor/skills/aholo-3dgs-reconstruction/ 的项目根后再执行相对路径。-u，以便创建/上传/poll 进度实时刷出。$env:AHOLO_API_KEY="..."，再执行与上文相同的单行 python -u ...；仍优先由 Agent 代跑。OpenAPI 路径： GET /asset/v1/token · POST /world/v1/reconstructions · POST /world/v1/generations · GET /world/v1/{worldId} · POST /world/v1/list
终态： SUCCEEDED · FAILED · CANCELED · TIMEOUT · REJECTED
产物字段（SUCCEEDED 后）： plyPath · spzPath · lodMetaPath（LOD 分块元数据，可选）· panoUrl（AI 生成全景图，仅 generation）
$env:AHOLO_API_KEY="your_api_key"
# 内网自签证书场景（不推荐）：$env:AHOLO_INSECURE_SKIP_VERIFY="1"
# 或指定 CA：$env:REQUESTS_CA_BUNDLE="D:/certs/corp-ca.pem"
仍建议由 Agent 代跑脚本；用户配置 Key 后回复「继续」即可。
共 13 个版本