feat(app): 新增 Gradio Web UI 作为 MVP 交互入口

- app.py: Gradio Blocks 页面，左侧对话 + 多模态输入（文本/图片），
右侧 3D 预览（Model3D）+ 文件下载 + 运行状态，支持会话隔离与重置
- service.py: run_chat_turn 封装一次对话闭环，从 agent_loop 消息流
抽取 assistant 文本、工具 payload、预览/下载路径，供 Web 层直接消费
- 保留终端入口 cli.py 不受影响

agent_core/service.py

@@ -0,0 +1,75 @@
+import json
+from pathlib import Path
+
+from agent_core.agent import agent_loop
+from agent_core.config import WORKDIR
+
+
+def content_to_text(content) -> str:
+    if isinstance(content, str):
+        return content
+    if not isinstance(content, list):
+        return ""
+
+    texts = []
+    for block in content:
+        text = getattr(block, "text", None)
+        if text:
+            texts.append(text)
+    return "\n".join(texts).strip()
+
+
+def resolve_display_path(path: str | None) -> str | None:
+    if not path:
+        return None
+
+    candidate = Path(path)
+    if not candidate.is_absolute():
+        candidate = WORKDIR / candidate
+    candidate = candidate.resolve()
+    return str(candidate) if candidate.exists() else None
+
+
+def latest_tool_payload(messages: list) -> dict:
+    latest = {}
+    for message in messages:
+        content = message.get("content")
+        if not isinstance(content, list):
+            continue
+        for item in content:
+            if not isinstance(item, dict) or item.get("type") != "tool_result":
+                continue
+            try:
+                payload = json.loads(item.get("content", ""))
+            except json.JSONDecodeError:
+                continue
+            if isinstance(payload, dict):
+                latest = payload
+    return latest
+
+
+def run_chat_turn(messages: list, user_text: str, image_path: str | None = None) -> dict:
+    text = user_text.strip()
+    if image_path:
+        text = f"{text}\n\nUploaded image path for image-to-3D generation: {image_path}".strip()
+
+    messages.append({"role": "user", "content": text})
+    agent_loop(messages)
+
+    assistant_text = content_to_text(messages[-1].get("content"))
+    tool_payload = latest_tool_payload(messages)
+    output_path = tool_payload.get("output_path")
+    preview_path = tool_payload.get("preview_path") or output_path
+
+    return {
+        "messages": messages,
+        "assistant_text": assistant_text,
+        "tool_payload": tool_payload,
+        "preview_path": resolve_display_path(preview_path),
+        "download_path": resolve_display_path(output_path),
+        "run_id": tool_payload.get("run_id"),
+        "run_dir": tool_payload.get("run_dir"),
+        "manifest_path": tool_payload.get("manifest_path"),
+        "ok": tool_payload.get("ok"),
+        "error": tool_payload.get("error"),
+    }

app.py

@@ -0,0 +1,153 @@
+import os
+import shutil
+from pathlib import Path
+from uuid import uuid4
+
+import gradio as gr
+
+from agent_core.config import ARTIFACT_ROOT
+from agent_core.service import run_chat_turn
+
+
+def new_session_state() -> dict:
+    return {
+        "session_id": uuid4().hex[:12],
+        "agent_messages": [],
+        "chat_messages": [],
+    }
+
+
+def copy_uploaded_image(image_path: str | None, session_id: str) -> str | None:
+    if not image_path:
+        return None
+
+    source = Path(image_path)
+    suffix = source.suffix or ".png"
+    upload_dir = ARTIFACT_ROOT / "uploads" / session_id
+    upload_dir.mkdir(parents=True, exist_ok=True)
+    target = upload_dir / f"{uuid4().hex[:8]}{suffix}"
+    shutil.copy2(source, target)
+    return str(target)
+
+
+def parse_user_message(message) -> tuple[str, str | None]:
+    if message is None:
+        return "", None
+    if isinstance(message, str):
+        return message.strip(), None
+
+    text = (message.get("text") or "").strip()
+    files = message.get("files") or []
+    image_path = files[0] if files else None
+    return text, image_path
+
+
+def format_status(result: dict) -> str:
+    payload = result.get("tool_payload") or {}
+    if not payload:
+        return "No model generated yet."
+
+    if payload.get("ok"):
+        return "\n".join([
+            f"Run: `{payload.get('run_id')}`",
+            f"Output: `{payload.get('output_path')}`",
+            f"Preview: `{payload.get('preview_path') or payload.get('output_path')}`",
+            f"Manifest: `{payload.get('manifest_path')}`",
+        ])
+
+    return "\n".join([
+        "Generation failed.",
+        f"Stage: `{payload.get('stage')}`",
+        f"Error: `{payload.get('error')}`",
+        f"Manifest: `{payload.get('manifest_path')}`" if payload.get("manifest_path") else "",
+    ]).strip()
+
+
+def submit_message(message, state):
+    state = state or new_session_state()
+    text, image_path = parse_user_message(message)
+    uploaded_image = copy_uploaded_image(image_path, state["session_id"])
+
+    if not text and not uploaded_image:
+        return state["chat_messages"], state, None, None, "Enter a message or upload an image.", {"text": "", "files": []}
+
+    display_text = text or "Generate a 3D model from the uploaded image."
+    if uploaded_image:
+        display_text = f"{display_text}\n\n[uploaded image]"
+    state["chat_messages"].append({"role": "user", "content": display_text})
+
+    try:
+        result = run_chat_turn(
+            messages=state["agent_messages"],
+            user_text=text or "Generate a 3D model from the uploaded image.",
+            image_path=uploaded_image,
+        )
+        state["agent_messages"] = result["messages"]
+        assistant_text = result["assistant_text"] or "Done."
+        if result.get("error") and not assistant_text:
+            assistant_text = result["error"]
+        state["chat_messages"].append({"role": "assistant", "content": assistant_text})
+        status = format_status(result)
+        return (
+            state["chat_messages"],
+            state,
+            result.get("preview_path"),
+            result.get("download_path"),
+            status,
+            {"text": "", "files": []},
+        )
+    except Exception as exc:
+        state["chat_messages"].append({"role": "assistant", "content": f"Failed: {exc}"})
+        return state["chat_messages"], state, None, None, f"Failed: `{exc}`", {"text": "", "files": []}
+
+
+def reset_session():
+    state = new_session_state()
+    return [], state, None, None, "New session started.", {"text": "", "files": []}
+
+
+with gr.Blocks(title="AI CAD Agent", fill_height=True) as demo:
+    gr.Markdown("# AI CAD Agent")
+
+    state = gr.State(new_session_state())
+
+    with gr.Row():
+        with gr.Column(scale=5):
+            chatbot = gr.Chatbot(height=560, label="Conversation")
+            composer = gr.MultimodalTextbox(
+                sources=["upload"],
+                file_types=["image"],
+                file_count="single",
+                lines=2,
+                max_lines=6,
+                label="Message",
+                placeholder="Describe a CAD model, ask for an edit, or upload an image as reference.",
+                submit_btn="Send",
+            )
+            with gr.Row():
+                clear = gr.Button("New Session")
+
+        with gr.Column(scale=4):
+            preview = gr.Model3D(label="Model Preview", height=560)
+            download = gr.File(label="Download Latest Model")
+            status = gr.Markdown("No model generated yet.")
+
+    composer.submit(
+        submit_message,
+        inputs=[composer, state],
+        outputs=[chatbot, state, preview, download, status, composer],
+    )
+    clear.click(
+        reset_session,
+        outputs=[chatbot, state, preview, download, status, composer],
+    )
+
+
+if __name__ == "__main__":
+    server_name = os.getenv("GRADIO_SERVER_NAME", "127.0.0.1")
+    server_port = int(os.getenv("GRADIO_SERVER_PORT", "7860"))
+    demo.queue(default_concurrency_limit=1).launch(
+        server_name=server_name,
+        server_port=server_port,
+        allowed_paths=[str(ARTIFACT_ROOT)],
+    )