feat(core): 可配置 artifact root 与 CadQuery STL 预览导出

- config: 引入 ARTIFACT_ROOT，支持通过 AIGC_ARTIFACT_ROOT 环境变量
指向工作区外的持久化目录（容器/HF Spaces 场景）
- outputs: safe_path 与 workspace_relative 允许 ARTIFACT_ROOT
之下的路径，manifest 增补 generator/preview_path/warning 字段
- cadquery_tool: 每次导出 STEP 的同时生成 preview.stl，供 Web UI
的 3D 预览使用；导出失败以 warning 返回，不影响主流程
- prompts & lux3d_tool: 放宽 image_path 描述，覆盖 workspace 与
artifact 目录两类来源

agent_core/config.py

@@ -15,8 +15,13 @@ if os.getenv("ANTHROPIC_BASE_URL"):
 
 
 WORKDIR = Path.cwd()
-DEFAULT_CADQUERY_OUTPUT_PATH = "outputs/model.step"
-DEFAULT_LUX3D_OUTPUT_PATH = "outputs"
+ARTIFACT_ROOT = Path(os.getenv("AIGC_ARTIFACT_ROOT", "outputs"))
+if not ARTIFACT_ROOT.is_absolute():
+    ARTIFACT_ROOT = WORKDIR / ARTIFACT_ROOT
+ARTIFACT_ROOT = ARTIFACT_ROOT.resolve()
+
+DEFAULT_CADQUERY_OUTPUT_PATH = str(ARTIFACT_ROOT / "model.step")
+DEFAULT_LUX3D_OUTPUT_PATH = str(ARTIFACT_ROOT)
 STEP_SUFFIXES = (".step", ".stp")
 IMAGE_SUFFIXES = (".png", ".jpg", ".jpeg", ".webp")
 
@@ -35,4 +40,3 @@ def get_client():
 
 def get_model_id() -> str:
     return os.environ["MODEL_ID"]
-

agent_core/outputs.py

@@ -1,20 +1,26 @@
 import json
+import os
 from datetime import datetime
 from pathlib import Path
 from uuid import uuid4
 
-from agent_core.config import DEFAULT_LUX3D_OUTPUT_PATH, STEP_SUFFIXES, WORKDIR
+from agent_core.config import ARTIFACT_ROOT, DEFAULT_LUX3D_OUTPUT_PATH, STEP_SUFFIXES, WORKDIR
 
 
 def safe_path(p: str) -> Path:
-    path = (WORKDIR / p).resolve()
-    if not path.is_relative_to(WORKDIR):
+    raw_path = Path(p)
+    path = (raw_path if raw_path.is_absolute() else WORKDIR / raw_path).resolve()
+    if not path.is_relative_to(WORKDIR) and not path.is_relative_to(ARTIFACT_ROOT):
         raise ValueError(f"Path escapes workspace: {p}")
     return path
 
 
 def workspace_relative(path: Path) -> str:
-    return str(path.relative_to(WORKDIR))
+    absolute = path if path.is_absolute() else WORKDIR / path
+    normalized = Path(os.path.normpath(str(absolute)))
+    if normalized.is_relative_to(WORKDIR):
+        return str(normalized.relative_to(WORKDIR))
+    return str(normalized)
 
 
 def new_run_id() -> str:
@@ -92,13 +98,16 @@ def write_manifest(
     manifest = {
         "run_id": run_id,
         "created_at": datetime.now().astimezone().isoformat(timespec="seconds"),
+        "generator": "cadquery",
         "prompt": prompt,
         "requested_output_path": requested_output_path,
         "output_path": workspace_relative(output_path),
+        "preview_path": payload.get("preview_path"),
         "format": output_path.suffix.lstrip(".").lower(),
         "code": code,
         "stdout": payload.get("stdout", ""),
         "stderr": payload.get("stderr", ""),
+        "warning": payload.get("warning"),
     }
     manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
     return manifest_path
@@ -135,4 +144,3 @@ def write_lux3d_manifest(
     }
     manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
     return manifest_path
-

agent_core/prompts.py

@@ -17,7 +17,7 @@ For CadQuery tasks:
 - If execute_cadquery returns ok=false, inspect the structured error, fix the code, and call execute_cadquery again.
 
 For image-to-3D tasks:
-- The user must provide a workspace-relative image path.
+- The user must provide an image path from the workspace or configured artifact directory.
 - If the user asks for image-to-3D generation but does not provide an image path, ask for the image path. Do not guess.
 - Call generate_3d_model with the image_path and optional output_path.
 - Do not ask the user to read files, convert images to base64, call APIs, or download results manually.
@@ -26,4 +26,3 @@ When a tool returns ok=true, report output_path, run_dir, and manifest_path to t
 
 Do not ask the user to run commands or create files manually.
 """.strip()
-

agent_core/tools/cadquery_tool.py

@@ -44,6 +44,7 @@ try:
     request = json.loads(sys.stdin.read())
     code = request["code"]
     output_path = Path(request["output_path"])
+    preview_path = Path(request["preview_path"])
 except Exception as exc:
     fail("input", exc)
     sys.exit(0)
@@ -107,10 +108,19 @@ except Exception as exc:
     fail("export", exc)
     sys.exit(0)
 
+preview_error = None
+try:
+    preview_path.parent.mkdir(parents=True, exist_ok=True)
+    cq.exporters.export(result, str(preview_path))
+except Exception as exc:
+    preview_error = str(exc)
+
 payload = {
     "ok": True,
     "stage": "done",
     "output_path": str(output_path),
+    "preview_path": str(preview_path) if preview_path.exists() else None,
+    "warning": f"Failed to export STL preview: {preview_error}" if preview_error else None,
     "stdout": tail(stdout_buffer.getvalue()),
     "stderr": tail(stderr_buffer.getvalue()),
 }
@@ -132,6 +142,7 @@ def run_execute_cadquery(code: str, output_path: str = DEFAULT_CADQUERY_OUTPUT_P
             })
 
         run_dir, output, run_id = resolve_run_output(output_path)
+        preview = run_dir / "preview.stl"
         output_root = run_dir.parent.parent
     except Exception as exc:
         return json_response({
@@ -147,6 +158,7 @@ def run_execute_cadquery(code: str, output_path: str = DEFAULT_CADQUERY_OUTPUT_P
     request = {
         "code": code,
         "output_path": str(output),
+        "preview_path": str(preview),
     }
 
     try:
@@ -231,6 +243,8 @@ def run_execute_cadquery(code: str, output_path: str = DEFAULT_CADQUERY_OUTPUT_P
         payload["run_id"] = run_id
         payload["run_dir"] = workspace_relative(run_dir)
         payload["output_path"] = workspace_relative(exported_path)
+        if payload.get("preview_path"):
+            payload["preview_path"] = workspace_relative(Path(payload["preview_path"]))
         payload["manifest_path"] = workspace_relative(manifest_path)
         payload["latest_path"] = workspace_relative(output_root / "latest")
         if latest_warning:
@@ -263,4 +277,3 @@ TOOL_SCHEMA = {
         "required": ["code"],
     },
 }
-

agent_core/tools/lux3d_tool.py

@@ -285,7 +285,7 @@ TOOL_SCHEMA = {
     "name": "generate_3d_model",
     "description": textwrap.dedent("""
         Generate a non-precise 3D model from a local image using the Lux3D image-to-3D API.
-        The input is a workspace-relative image path, not image bytes or base64 text.
+        The input is a workspace or artifact image path, not image bytes or base64 text.
         The tool reads the image, creates a Lux3D task, polls for completion, downloads the result, and writes a manifest.
     """).strip(),
     "input_schema": {
@@ -293,7 +293,7 @@ TOOL_SCHEMA = {
         "properties": {
             "image_path": {
                 "type": "string",
-                "description": "Workspace-relative path to a source image file. Supported formats: .png, .jpg, .jpeg, .webp.",
+                "description": "Path to a source image file in the workspace or artifact directory. Supported formats: .png, .jpg, .jpeg, .webp.",
             },
             "output_path": {
                 "type": "string",
@@ -303,4 +303,3 @@ TOOL_SCHEMA = {
         "required": ["image_path"],
     },
 }
-