gauss-mcp

基于 uv 管理的 Python MCP server，用于把本地图片导入为方案，并通过 job 协议提供可轮询的进度与结果。

当前 MVP 范围

• 输入本地图片路径
• 上传图片
• 判断普通图/全景图
• 普通图转全景图
• 可选清家具
• 全景图转点云
• 空间调整
• 导入方案
• 返回 design link

核心设计

• 普通 tool 调用保持短切片，不等待整条 job 结束
• 对外主流程暴露 7 个 job tools：
  • gauss_start_image_job
  • gauss_update_job_inputs
  • gauss_wait_current_stage
  • gauss_poll_job
  • gauss_get_job
  • gauss_resume_job
  • gauss_list_jobs
• gauss_wait_current_stage 是默认等待手段：服务端内部执行 poll + wait，只等待“当前阶段结束”或一个 timeout_sec 切片，默认 60 秒；超时返回 status=in_progress
• gauss_poll_job 保留给 debug 或细粒度观察，不再要求 agent 自己 Bash sleep
• 对于用户未提前给出的阶段参数，可以在 gauss_start_image_job 时显式传 null，等进入对应阶段前再通过 gauss_update_job_inputs 补齐
• clear_furniture 只在 pano_clear 阶段生效，level_height_mm 只在 gauss_import 阶段生效
• 当 job 进入缺参数阶段时，紧凑 job.required_user_input 会给出结构化提问信号，default_allowed=false 表示调用方必须先问用户，不能自行默认
• gauss_wait_current_stage 在这种场景下会返回 status=needs_user_input，而不是继续自动等待
• 通过阶段事件与阶段摘要给 skill 提供进度展示依据，而不是 fake percent
• 紧凑 job 返回会在已有可展示全景图时携带 pano_url，供 skill 直接展示图片反馈
• Claude Code skill 不会在任务一开始统一追问参数；只有在 pano_clear / gauss_import 开始前才会询问对应设置
• 长耗时阶段按 15-30 秒节奏推进；同步 wait tool 会复用阶段轮询间隔，减少 transcript 噪音
• gauss_import 完成后会立即产出 design_url，用户可以先打开方案预览；gauss_show_info 继续补齐 splat_url / drc_url
• job 状态落盘到 IMAGE_TO_DESIGN_JOB_STATE_DIR，支持中断后继续查询或恢复

阶段顺序

1. upload
2. image_type
3. img2pano
4. pano_clear
5. pano2pointcloud
6. spatial_tune
7. gauss_import
8. gauss_show_info

开发

uv sync --dev
uv run pytest
uv run ruff check src tests

运行 MCP Server

uv run gauss-mcp

本地 smoke test

默认使用同步 wait tool：

uv run python scripts/e2e_image_to_plan.py /absolute/path/to/image.png

可选参数：

uv run python scripts/e2e_image_to_plan.py /absolute/path/to/image.png \
  --floor-plan-name demo-plan \
  --level-height-mm 2800 \
  --no-clear-furniture \
  --wait-timeout-sec 60

如需切回细粒度 poll 调试：

uv run python scripts/e2e_image_to_plan.py /absolute/path/to/image.png --mode poll

Claude Code Skill

Skill 位于：

.claude/skills/gauss-image-to-plan/SKILL.md

它基于 gauss_* job tools 做阶段式编排：

• 启动新任务时可先把未知的 clear_furniture / level_height_mm 置为 null，不阻塞上传与前置处理
• 当 job.current_stage == pano_clear 且 job.clear_furniture == null 时，再询问是否清家具，并调用 gauss_update_job_inputs
• 当 job.current_stage == gauss_import 且 job.level_height_mm == null 时，再询问层高，并调用 gauss_update_job_inputs
• 主路径优先使用 gauss_wait_current_stage，不再要求 agent 自己 Bash sleep
• 长耗时阶段默认按 60 秒切片同步等待，减少 transcript 噪音
• 每次阶段推进都要同步当前阶段与阶段进度，不要只说“继续等待”
• 如果 status=needs_user_input 或 job.required_user_input 非空，说明当前阶段在等用户补齐输入，必须先问用户，不能自行默认
• job.pano_url 首次可用时，会在对话里展示全景图反馈
• gauss_import 完成后先返回可预览的 design_url
• gauss_show_info 继续补齐 splat_url / drc_url
• gauss_poll_job 只保留给 debug 或细粒度观察