Pascal MCP 实战:如何让 AI Agent 从一句需求自动生成两居室公寓场景
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 深度解读)
示例结尾给出的三条经验,结合源码可以展开为更深的理解:
-
批量变更 + 单步撤销。
apply_patch的原子性来自两层:输入层用PatchSchema(discriminated union)做整批校验,bridge 层先 dry-run 全部合法才提交;undo 粒度来自 Zundo temporal 中间件把整个 batch 记为一步。这也是 Agent 工作流中"一次逻辑操作 = 一次工具调用 = 一步可撤销"的根本保证。 -
Zone 不是墙体,而是多边形标注。
set_zone创建的是ZoneNode而非几何墙体:它让find_nodes({ zoneId })这类按房间查询、以及后续规划步骤(如furnish_room把家具放进多边形)变得简单。墙体负责围合物理空间,zone 负责语义命名——两者职责分离。 -
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 会话中自由混用。