Draw2Code 多宿主 Workflow Contract

这份契约同时约束 DSH guidance、Codex Skill 和 MCP instructions。宿主 Adapter 只负责输入、选择题与展示；Create、Update、Generate 的状态、存储、冲突和验收由共享 Runtime 决定。

唤醒与会话

• 仅在用户明确说 Draw2Code、画码，或意图明确为“画原型”时进入 Draw2Code。普通“做一个 App / 写一个页面”不自动拦截。
• 同一任务首次唤醒后保持 Draw2Code 会话；后续“改首页”“生成页面”不要求重复唤醒词。
• “打开 Draw2Code / 画码”“我自己画一下”“我画个示意给你”只调用 draw2code_open：有 active board 就恢复；没有则展示空状态与创建入口，不能擅自开始 Create。
• “我画好了”“按我画的看看”先调用 draw2code_read 读取当前可见画板并复述页面、组件和交互；用户没有要求时不自动修改或生成。

工具顺序

• 新产品先走 draw2code_create 的可恢复状态机。start 返回 discovery 后，Agent 根据已明确事实、历史回答和 recommendedDimensions 选择当前最高影响的未知项；第一题必须优先采用推荐维度，不能先问模块、页面或通用信息架构。普通待办优先深挖触发场景或现有替代，雷达社交优先深挖信任与独特连接机制，穿搭产品优先深挖推荐依据或使用时刻。信息不足时调用 propose_question，每次只展示一个带 insight、取舍说明和推荐项的结构化问题；信息足够或用户要求停止时调用 synthesize。禁止固定询问平台、用户、目标、流程、模块和页面，最多提问 10 次。
• synthesize 提交一份结构化 PrototypeBrief；工具校验后确定性生成完整 briefMarkdown、pageBlueprints 和 pageMockData。ready 时必须完整展示该 Markdown，不能自行缩写；随后用最后一张页面范围确认卡明确列出将绘制的页面，只进行一次“确认这些页面并绘制 / 调整页面范围 / 调整产品方向”确认。
• 每道原生问题卡片都保留“直接整理项目简报”；选择后按 synthesize-now 回答，工具明确返回 nextAction=synthesize。用户跳过当前问题时调用 skip 并把该项保留为待验证假设；即使已有待答问题也可调用 synthesize。ready 后选择调整时直接调用 propose_question 追问受影响的一项，旧简报失效，回答后必须重新生成完整简报。
• Create 返回 confirmed 后，按 boardName 和同一份 brief 调用 draw2code_update。首轮有 3 个及以上页面时先画一个代表页并在可见画板检查，再带 phase=representative 的 visualReview 添加其余页面；复核必须携带最近一次 update 返回的 rev 与 revealRequestId，不能重放旧结果。全部页面完成后用空 ops 提交覆盖所有 page id 的 phase=final 复核。已有画板修改必须先 draw2code_read 再 draw2code_update。
• 省略 board / DSH 的 name 始终表示用户当前可见 active board。只有用户明确点名另一块画板时才显式传入。
• MCP/Codex 从 workspace 内的子目录调用时，所有画板操作统一归到宿主注册的 workspace root；不能因当前 cwd 是子仓库而悄悄创建第二套画板。
• Update 返回 requiresConfirmation=true 时停止写入并只询问冲突覆盖；得到确认后才以 force=true 重试。不得直接写 .excalidraw.json 绕过 CAS、布局门禁和回读验证。
• Generate 开始前先用普通对话询问用户是否有参考风格图片，不使用宿主选择题；用户已附图时不重复问。有图则查看后把简洁摘要或路径传为 referenceStyle，没有则传 none。随后必须沿用工具返回的 session、revision、question 与 confirmation；第一张结构化选择题仍然是页面多选，只有 status=completed 且验证证据通过后才能报告生成完成。

展示与共同编辑

• 第一次创建、读取或用户明确打开时展示画板：支持 MCP UI 就内嵌；否则本地图形环境打开 daemon 的短期 URL；headless 只返回 URL。不要根据宿主产品名分支。
• 宿主具有自己的侧边栏浏览器时使用 presentation=handoff：工具只准备短期 URL 并返回 displayState=handoff-ready，宿主负责在侧边栏导航和验证可见性。只有画布在侧边栏真正可见后，Agent 才能报告“已打开”；不能把 URL 就绪或 daemon 启动成功当作可见性证据。
• 同一 workspace 的外部浏览器只首次打开一次；后续依靠事件刷新，不能反复抢焦点。
• verified=true / writeVerified=true 只证明目标画板写盘并回读，不代表原型已经完成。成功更新会把目标设为 active board、发布带目标 revision 的 reveal request 并自动打开画码；Canvas 实际加载到同一 board + revision 后才回传消费确认。只有此后提交的 completionReady=true 才说明最终视觉复核已覆盖全部页面，即使如此，仍应把 prototypeQuality.warnings 作为继续打磨依据。
• 用户拖动产生的 scene write 与 Agent update 都通过 daemon；WebSocket 是主通知通道，revision polling 是断线降级。

数据与安全

• 原位使用 draw2code/、.active-board.json、.projects/、.generations/、.generate-settings/ 与 draw2code-pages/，不得复制、导入或主动迁移旧数据。
• 所有 root 都必须 realpath 后落在 HostContext 注册 workspace 内。daemon 只监听 loopback；主 bearer 不进入画板页面，页面只收到短期、活动续期的 workspace-scoped token，可在该 root 内管理多个画板但不能跨 root 访问。
• 不上传画板、brief、页面或验证证据。单画板元素数、UTF-8 byte 上限、历史版本与生成证据门禁保持有效。