Pascal MCP 实战:如何让 AI Agent 从一句需求自动生成两居室公寓场景

原创2026-09-11 23:47:451,329 阅读
文章标签:3D建模前端3D渲染MCP 服务工具调用CLIAI 技能

Pascal MCP 实战:如何让 AI Agent 从一句需求自动生成两居室公寓场景

本文档基于 packages/mcp/examples/generate-apartment.md 完整流程,结合 @pascal-app/mcp 仓库源码,详细拆解一个真实可复现的 MCP 会话:用户只给出一句自然语言 brief("西班牙 80 m² 的两室一卫公寓"),AI Agent 通过 from_brief 提示词,借助 get_scene、apply_patch、set_zone、cut_opening、validate_scene 等工具,从空场景逐步构建出包含墙体、房间分区、门窗洞口的完整公寓,并支持后续通过 iterate_on_feedback 迭代修改。读完本文,你将掌握 Pascal MCP 从简短需求到完整建筑场景的完整调用链、每个关键工具的入参与输出约定,以及"批量变更 + 单步撤销"的底层设计原理。

背景:一次标准 MCP 驱动的建楼会话

本示例假设 MCP 宿主(Claude Desktop、Claude Code 或 Cursor)已经配置好 pascal-mcp(接入方式详见 packages/mcp/README.md)。Agent 使用 from_brief 提示词,将一段简短的文字需求转化为一个具体的建筑场景。

宿主 UI 允许用户选择 from_brief 提示词并填写两个参数:

brief: "2-bedroom 1-bath apartment in 80 m² in Spain, open-plan living /
         kitchen, bathroom on the interior wall"
constraints: "Spanish building regulations; ceiling height 2.5 m"

在源码中,from_brief 由 from-brief.ts 注册,其参数由 Zod 校验:

argsSchema: {
  brief: z.string(),
  constraints: z.string().optional(),
}

提示词内容由 buildFromBriefPrompt() 纯函数生成,由固定前言(PREAMBLE)、用户 brief、可选 constraints 与任务清单拼接而成。前言中的几条指令直接决定了 Agent 的行为方式,值得留意:

  • 绑定场景再动手:新建项目调用 create_project,已有场景用 list_scenes 后 load_scene,或用 create_house_from_brief 一步创建并加载起始场景;未绑定场景的变更仅存在于内存,既不持久化也不会出现在浏览器中;
  • 按语义工具优先:优先使用 create_story_shell、create_room、add_door、add_window、furnish_room 等语义化工具,apply_patch 用于需要精确控制的批量图编辑;
  • 遵守场景不变量:Level 必须在 Building 下;墙体、分区、楼板、天花板、屋顶、楼梯必须在 Level 下;门窗必须在 Wall 下(parentId = wallId);落地物品在 Level 下,贴墙/吊顶物品在对应 Wall/Ceiling 下,不得直接放在 Site 节点下;
  • 尺寸务实:使用米制真实尺寸,墙厚保持 0.1–0.3 m,层高 2.4–3.0 m(除非 brief 另有要求);
  • 只输出工具调用:不产生冗长叙述,解释性文字放进工具调用参数。

第一步:检查当前场景(get_scene)

from_brief 提示词要求 Agent "从空场地开始、读取当前场景、发出增量 apply_patch 调用"。Agent 的第一步是调用只读工具 get_scene:

// tool: get_scene
{ "name": "get_scene", "arguments": {} }

返回(已精简):

{
  "nodes": {
    "site-1": { "type": "site", "id": "site-1", "children": [/* ... */] },
    "building-1": { "type": "building", "id": "building-1", "parentId": "site-1" },
    "level-1":    { "type": "level",    "id": "level-1",    "parentId": "building-1",
                    "elevation": 0, "height": 2.5 }
  },
  "rootNodeIds": ["site-1"]
}

默认场景是一个 Site → Building → Level 的层级栈,没有任何墙体。level-1 的 elevation: 0, height: 2.5 正好呼应 brief 中"层高 2.5 m"的约束。Agent 决定在 level-1 上工作,目标轮廓为 10 m × 8 m = 80 m²。

get_scene 的返回值结构 { nodes, rootNodeIds, collections } 由 tools/get-scene.ts 实现,与 pascal://scene/current 资源(application/json)是同一份场景图快照的两种暴露方式。

第二步:创建外围墙体(apply_patch 批量创建)

Agent 选择原点在 (0, 0) 的矩形轮廓,用一次 apply_patch 调用同时创建四条外墙:

// tool: apply_patch
{
  "name": "apply_patch",
  "arguments": {
    "patches": [
      { "op": "create", "parentId": "level-1",
        "node": { "type": "wall", "start": [0, 0], "end": [10, 0],
                  "thickness": 0.2, "height": 2.5 } },
      { "op": "create", "parentId": "level-1",
        "node": { "type": "wall", "start": [10, 0], "end": [10, 8],
                  "thickness": 0.2, "height": 2.5 } },
      { "op": "create", "parentId": "level-1",
        "node": { "type": "wall", "start": [10, 8], "end": [0, 8],
                  "thickness": 0.2, "height": 2.5 } },
      { "op": "create", "parentId": "level-1",
        "node": { "type": "wall", "start": [0, 8], "end": [0, 0],
                  "thickness": 0.2, "height": 2.5 } }
    ]
  }
}

响应:

{ "applied": 4 }

apply_patch 的底层契约

apply_patch 的输入由 tools/schemas.ts 中的 PatchSchema 定义,是一个以 op 字段区分的联合类型:

export const CreatePatchSchema = z.object({
  op: z.literal('create'),
  node: z.record(z.string(), z.unknown()),   // 必须含 type,由 bridge 层 Zod 判别
  parentId: NodeIdSchema.optional(),
})

export const UpdatePatchSchema = z.object({
  op: z.literal('update'),
  id: NodeIdSchema,
  data: z.record(z.string(), z.unknown()),   // 部分合并
})

export const DeletePatchSchema = z.object({
  op: z.literal('delete'),
  id: NodeIdSchema,
  cascade: z.boolean().optional(),
})

export const PatchSchema = z.discriminatedUnion('op', [
  CreatePatchSchema, UpdatePatchSchema, DeletePatchSchema,
])

在 tools/apply-patch.ts 的实现中,每个 patch 会被映射为 bridge 层的操作并一次性提交:所有 patch 先整体校验(dry-run),全部合法后才提交,任何一步失败都不会产生部分变更。其输出除了 appliedOps 外还包含 deletedIds、createdIds 以及 live-sync 持久化负载。

坐标约定:为什么 2D 点写作 [x, z]

Pascal 是右手坐标系场景:X 和 Z 构成地面平面,Y 向上;长度单位是米。所有传给工具的 2D 点都是 level/building 局部的 [x, z] 地面坐标——包括 wall.start / wall.end,以及 slab、zone、ceiling 的 polygon / holes 数组。在默认的单位建筑变换下,它直接映射到世界坐标:

[x, z]  →  (x, y, z)      // 第 2 个分量是世界 Z(深度),不是 "up"

存储约定中没有符号翻转:工具直接消费第 2 个分量作为世界 Z。垂直方向的 y 从所属 level 的堆叠高度开始计算(由 level 系统按累计层高算出),再加上元素自身高度;slab 额外携带绝对 elevation。

需要注意的一个外部坐标陷阱:Pascal 的视口会在世界轴之上叠加自身旋转——2D 平面面板按用户视图旋转(正北对齐 = 0°),3D 俯视快照保留相机当前方位角,所以从等距默认视角调用时世界轴与屏幕轴大约偏移 45°,直到你环绕到轴对齐视图。因此,以"Y 朝北、俯视"方式绘制的外部坐标(测量图、正北朝上的场地平面图、2D 绘图库输出)在 Pascal 中观看时会相对于来源发生旋转。编辑器自己的 2D/3D 工具与其存储坐标内部一致,这个问题只影响程序化生成的几何。验证方法:在已知锚点放置一张带比例的参考图检查对齐。完整推导见 packages/mcp/examples/coordinate-conventions-demo.md 与配套 packages/mcp/examples/coordinate-conventions-demo.json,可用 bunx @pascal-app/mcp --stdio --scene packages/mcp/examples/coordinate-conventions-demo.json 加载验证。

第三步:创建内隔墙

布局意图:东侧两间卧室,浴室靠内墙,西侧开放起居/厨房。Agent 用第二次 apply_patch 创建四条内墙(厚度降到 0.15 m):

// tool: apply_patch
{
  "name": "apply_patch",
  "arguments": {
    "patches": [
      { "op": "create", "parentId": "level-1",
        "node": { "type": "wall", "start": [5.5, 0], "end": [5.5, 8],
                  "thickness": 0.15, "height": 2.5 } },
      { "op": "create", "parentId": "level-1",
        "node": { "type": "wall", "start": [5.5, 4], "end": [10, 4],
                  "thickness": 0.15, "height": 2.5 } },
      { "op": "create", "parentId": "level-1",
        "node": { "type": "wall", "start": [5.5, 5.5], "end": [8, 5.5],
                  "thickness": 0.15, "height": 2.5 } },
      { "op": "create", "parentId": "level-1",
        "node": { "type": "wall", "start": [8, 4], "end": [8, 5.5],
                  "thickness": 0.15, "height": 2.5 } }
    ]
  }
}

注意墙体端点的几何关系:竖向分户墙在 x = 5.5 贯穿全深;横向墙从 (5.5, 4) 到 (10, 4) 划分卧室 1 与浴室;浴室上边界由 (5.5, 5.5) → (8, 5.5) 与 (8, 4) → (8, 5.5) 围合,形成 2.5 m × 1.5 m 的浴室空间。

第四步:定义房间分区(set_zone)

Agent 声明房间区域,目的是让后续的查询和物品摆放可以按名称定位:

// tool: set_zone  (called once per zone)
{
  "name": "set_zone",
  "arguments": {
    "levelId": "level-1",
    "label": "Living / Kitchen",
    "polygon": [[0, 0], [5.5, 0], [5.5, 8], [0, 8]]
  }
}
// → { "zoneId": "zone-living" }

{
  "name": "set_zone",
  "arguments": {
    "levelId": "level-1",
    "label": "Bedroom 1",
    "polygon": [[5.5, 0], [10, 0], [10, 4], [5.5, 4]]
  }
}
// → { "zoneId": "zone-bed1" }

{
  "name": "set_zone",
  "arguments": {
    "levelId": "level-1",
    "label": "Bedroom 2",
    "polygon": [[5.5, 5.5], [10, 5.5], [10, 8], [5.5, 8]]
  }
}
// → { "zoneId": "zone-bed2" }

{
  "name": "set_zone",
  "arguments": {
    "levelId": "level-1",
    "label": "Bathroom",
    "polygon": [[5.5, 4], [8, 4], [8, 5.5], [5.5, 5.5]]
  }
}
// → { "zoneId": "zone-bath" }

set_zone 的入参由 tools/set-zone.ts 定义:polygon 至少 3 个顶点(z.array(Vec2Schema).min(3)),label 非空字符串,可选 properties 元数据合并进 zone 的 metadata。实现中还会校验目标必须是 level,且拒绝在 role === 'roof' 的屋顶支撑层上创建分区(报错提示 "Roof support level is not an occupied story; create zones on an occupied level instead"),因为屋顶专用层不是可居住楼层。

set_zone 底层创建的是 ZoneNode(来自 @pascal-app/core/schema),label 直接存入节点 name。

第五步:开门窗洞口(cut_opening)

Agent 用 cut_opening 在每个内隔墙上加入户门,并在南立面与东立面开窗:

// tool: cut_opening  (called once per opening)
{
  "name": "cut_opening",
  "arguments": {
    "wallId": "wall-south",       // perimeter wall [0,0] → [10,0]
    "type": "window",
    "position": 0.25,             // 25% along centerline
    "width": 1.2,
    "height": 1.2
  }
}
// → { "openingId": "window-south-1" }
{
  "name": "cut_opening",
  "arguments": {
    "wallId": "wall-bed1",        // partition wall to Bedroom 1
    "type": "door",
    "position": 0.4,
    "width": 0.9,
    "height": 2.1
  }
}
// → { "openingId": "door-bed1" }

Agent 随后对卧室 2 的门、浴室门以及东立面另两扇窗重复此操作。

cut_opening 的参数语义与实现细节

从 tools/cut-opening.ts 可以看到几个关键点:

  • position 是 0..1 的归一化参数,表示沿墙体中心线的比例位置(z.number().min(0).max(1)),但门/窗节点内部存储的是墙局部米数 position[0],所以实现中用 wallLocalXFromT(wall, position, width) 做换算后再写入;
  • 工具会先校验墙体存在且 type === 'wall',并检查墙长是否容纳得下洞口宽度(墙比洞口短会直接报错);
  • type === 'window' 时,节点 position[1] 会被设为 0.9 + height / 2,即窗台(sill)默认 0.9 m 高;
  • 创建的门窗节点用 DoorNode / WindowNode(@pascal-app/core/schema)做 Zod 解析,确保结构合法;
  • 输出 { openingId, ... } 与 live-sync 负载。

第六步:校验并汇报(validate_scene + summary 资源)

// tool: validate_scene
{ "name": "validate_scene", "arguments": {} }

响应:

{ "valid": true, "errors": [] }

validate_scene 由 tools/validate-scene.ts 实现:对场景中每个节点运行 Zod 校验并检查父子完整性,返回 { valid, errors },每条错误包含 { nodeId, path, message }。它属于只读工具(READ_ONLY_TOOL_ANNOTATIONS)。

随后 Agent 读取场景摘要用于向用户汇报:

// resource: pascal://scene/current/summary
{ "uri": "pascal://scene/current/summary" }

宿主展示返回的 Markdown:1 个 site、1 个 building、1 个 level、8 面墙、4 个分区、3 扇门、3 扇窗;可用面积约 78 m²;周长约 36 m。

pascal://scene/current/summary 是注册在 packages/mcp/src/resources/index.ts 下的 text/markdown 资源(人类可读的节点计数、包围盒与楼层面积摘要)。同组的其他资源还包括:pascal://scene/current(完整场景 JSON 快照)、pascal://agent/guide(面向 Agent 的 MCP 优先建造流程、场景不变量与工具偏好,注册于 resources/agent-guide.ts)、pascal://catalog/items(内置住宅家具目录子集)与 pascal://constraints/{levelId}(指定楼层的 slab 足迹与墙体多边形,适合作为规划上下文)。

第七步:根据反馈迭代(iterate_on_feedback + undo)

用户跟进:

User: Swap the bathroom and bedroom 2 — I want the bathroom near the entrance.

Agent 加载 iterate_on_feedback 提示词,发出单次 apply_patch:更新 zone-bath 与 zone-bed2 的多边形,并移动对应的隔墙。由于所有变更都经由 Zustand store,用户可以撤销:

{ "name": "undo", "arguments": { "steps": 1 } }
// → { "undone": 1 }

iterate_on_feedback 的设计原则

从 iterate-on-feedback.ts 的实现可以看到这个提示词的核心规则,与示例行为一一对应:

  • 先通过 pascal://scene/current 资源读取当前状态,再针对反馈提出最小变更集;
  • 优先 update 而非 create+delete(能改字段就不重建);
  • 不重建已存在的节点、不触碰与反馈无关的节点;
  • 匹配需求时优先用语义工具(create_room、add_door、add_window、furnish_room、place_item);
  • 把相关变更打包进一次 apply_patch,共享同一个撤销步骤;
  • 多房间变更后调用 verify_scene 并修复上报的问题。

为什么一次 apply_patch = 一步撤销

apply_patch 描述中明确写着:"Apply a batch of create/update/delete operations atomically. All patches are validated before any are applied; the entire batch forms a single undo step." 在 bridge 层(bridge/scene-bridge.ts)中,所有变更都通过 Zustand store 的 temporal(Zundo)中间件提交,undo/redo 工具实际调用的是 useScene.temporal.getState().undo(steps) / redo(steps),通过 pastStates / futureStates 长度推算实际撤销/重做的步数。这正解释了示例中的 Takeaway:把变更批量放进单个 apply_patch,undo 就能回滚整个逻辑变更,而不是一步步退回。

关键设计要点(Takeaways 深度解读)

示例结尾给出的三条经验,结合源码可以展开为更深的理解:

  1. 批量变更 + 单步撤销。apply_patch 的原子性来自两层:输入层用 PatchSchema(discriminated union)做整批校验,bridge 层先 dry-run 全部合法才提交;undo 粒度来自 Zundo temporal 中间件把整个 batch 记为一步。这也是 Agent 工作流中"一次逻辑操作 = 一次工具调用 = 一步可撤销"的根本保证。

  2. Zone 不是墙体,而是多边形标注。set_zone 创建的是 ZoneNode 而非几何墙体:它让 find_nodes({ zoneId }) 这类按房间查询、以及后续规划步骤(如 furnish_room 把家具放进多边形)变得简单。墙体负责围合物理空间,zone 负责语义命名——两者职责分离。

  3. Agent 全程不需要与 @pascal-app/viewer 交互。宿主看到的一切都通过 tools + resources + prompts 流动:工具完成变更(apply_patch、cut_opening、set_zone……),资源提供只读上下文(pascal://scene/current、pascal://scene/current/summary、pascal://agent/guide),提示词注入工作流约束(from_brief、iterate_on_feedback)。这也是 MCP 架构将能力与渲染解耦的核心价值:同样的场景图可以被任意 MCP 兼容宿主无头驱动。

完整工具链速查

以下是本示例用到的工具及其输入要点(完整工具表见 packages/mcp/README.md):

工具 用途 关键输入
get_scene 返回完整场景图 —
apply_patch 批量 create/update/delete,整批校验、单步撤销 { patches: Patch[] }
set_zone 在楼层创建分区/房间多边形 { levelId, polygon, label, properties? }
cut_opening 在墙内切出门/窗洞口,position 为 0..1 沿墙参数 { wallId, type: 'door'|'window', position, width, height }
validate_scene 对每个节点做 Zod 校验与父子完整性检查 —
find_nodes 按 type / parent / zone / level 过滤节点 { type?, parentId?, zoneId?, levelId? }
undo / redo 在时间旅行历史中前进/后退 { steps? }
verify_scene 高层布局检查(校验状态、逐层计数、空楼层、实际问题) —

如果你希望跳过逐墙手写、走更语义化的路径,from_brief 提示词也推荐了 create_story_shell(一次生成整层外墙 + 可选楼板/天花板)、create_room(由多边形一次生成 zone + slab + ceiling + walls)、add_door / add_window(参数化放置)、furnish_room(按房间类型填充家具)等高级工具;本示例之所以手写 apply_patch,是为了展示最底层的精确控制能力——两种路径都可以在同一个 MCP 会话中自由混用。

登录后查看全文
editor