QORM MCP 工具

由 internal/mcp/tools.go (TestMCPDocInSync) 自动生成 —— 请勿手动修改。 请使用 QORM_UPDATE_DOCS=1 go test ./internal/mcp/ 重新生成。

QORM 暴露了一个 Model Context Protocol 服务端，使 AI 智能体可以读取、操作、设计并验证一个运行中的 QORM 应用。可以使用 qorm mcp <app-dir|bundle> 启动它（基于标准输入输出的 JSON-RPC），或在运行的 qorm run 中通过 HTTP 的 /mcp 访问相同的工具 —— 此时智能体与当前 canvas、浏览器或 WebView 宿主共享同一个运行时会话。

人类运行的应用，与智能体通过 MCP 读取的共享会话日志并列——同一个运行中的运行时。

DevTool 将你的点击与智能体在同一应用上的 MCP 调用按时间交错列出，并以颜色区分操作者。

安全模型：qorm_simulate_action、qorm_preview_patch 和 qorm_diff 均对应用副本运行，绝不触碰运行中的应用。qorm_apply_patch 提交修改，但它必须携带由相同操作的 qorm_preview_patch 返回的 previewToken —— 从而保证每次提交的编辑都有前置审查。qorm_undo 撤销最后一次提交的操作。

宿主窗口：应用打开时的窗口由 qorm.json 旁的可选文件 qorm.config.json 配置（宿主/构建期配置 —— 不会被打进 bundle，也不参与签名），并以 qorm.json 内的 display / platforms.desktop.window 作为清单内回退：width/height（初始尺寸）、title、resizable（默认 true）、chromeless（无标题栏/边框）、transparent（透明背景 → 异形/自定义形状窗口）、hideLog/hideTray。qorm.config.json 优先于清单；qorm_inspect 会回报解析后的最终取值。

工具分类

25 个工具按意图分为六组，按需取用：

• 理解（只读）： qorm_inspect、qorm_render_html、qorm_capture_subtree、qorm_capture_canvas、qorm_a11y_tree、qorm_capabilities、qorm_get_node、qorm_source_location、qorm_query、qorm_list_actions、qorm_activity、qorm_export_scene、qorm_export_bundle
• 操作（修改实时状态）： qorm_dispatch、qorm_set_state
• 模拟（无副作用）： qorm_simulate_action
• 设计（preview → apply，评审绑定）： qorm_preview_patch、qorm_diff、qorm_apply_patch、qorm_undo
• 验证（测试 + 解读实时渲染）： qorm_assert、qorm_validate、qorm_measure、qorm_check_layout
• 窗口控制（桌面）： qorm_window

带有 * 标记的参数为必填项；其余为选填项。

示例

代表性调用（JSON-RPC 2.0，方法 tools/call）：

理解 —— 读取应用，然后定位节点并跳转到其源码位置：

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"qorm_inspect","arguments":{}}}

{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"qorm_query","arguments":{"type":"button","textContains":"Save"}}}

{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"qorm_source_location","arguments":{"id":"saveBtn"}}}

操作 —— 分发动作、写入嵌套状态路径：

{"jsonrpc":"2.0","id":4,"method":"tools/call",
 "params":{"name":"qorm_dispatch","arguments":{"action":"increment"}}}

{"jsonrpc":"2.0","id":5,"method":"tools/call",
 "params":{"name":"qorm_set_state","arguments":{"path":"user.name","value":"Ada"}}}

设计 —— 预览补丁、评审差异，然后携带 token 提交：

{"jsonrpc":"2.0","id":6,"method":"tools/call",
 "params":{"name":"qorm_preview_patch","arguments":{"ops":[
   {"op":"setProp","target":"saveBtn","key":"text","value":"Save now"}]}}}

{"jsonrpc":"2.0","id":7,"method":"tools/call",
 "params":{"name":"qorm_apply_patch","arguments":{
   "ops":[{"op":"setProp","target":"saveBtn","key":"text","value":"Save now"}],
   "previewToken":"<来自 qorm_preview_patch 的 token>"}}}

验证 —— 断言状态并校验实时布局：

{"jsonrpc":"2.0","id":8,"method":"tools/call",
 "params":{"name":"qorm_assert","arguments":{"checks":[
   {"kind":"stateEquals","path":"count","value":3},
   {"kind":"htmlContains","text":"Saved"}]}}}

{"jsonrpc":"2.0","id":9,"method":"tools/call",
 "params":{"name":"qorm_check_layout","arguments":{"checks":[
   {"id":"saveBtn","type":"button","visible":true,"noOverflow":true}]}}}