iterating-with-ai-and-mcp

使用 AI 和 MCP 迭代：让 Agent 编辑、重新加载、截屏并迭代

Compose HotSwan 在 IntelliJ 插件中内置了 HTTP MCP 服务。任何兼容 MCP 的 AI 客户端（Claude Code、Cursor，以及任何支持 Model Context Protocol 的工具）都可以调用其工具来驱动迭代循环。Agent 编辑 Kotlin 文件，调用 hotswan_reload，截取正在运行的设备屏幕，然后根据设计意图评估结果，并决定下一步修改。迭代周期与人工循环相当，每次只需几秒，因此 Agent 无需人工逐步指导，就能逐渐调整好 UI。

本技能介绍标准的 Agent 循环、七个 MCP 工具（名称必须原样使用），以及确保循环可靠运行的安全习惯（先检查状态、用快照包裹操作以便回滚、架构变更时回退到完整安装）。

何时使用此技能

• 开发者想要通过 AI 驱动 UI 迭代：“调整此屏幕，直到它与设计稿一致”“让 Agent 选择一种颜色”。
• 开发者希望 AI 通过视觉方式验证自己的修改，而不是猜测修改是否生效。
• 开发者正在设置 Claude Code 或 Cursor 工作流，需要访问正在运行的应用的 MCP 工具。
• 用户询问“AI 能看到哪些地方变了吗？”“AI 能截取设备屏幕吗？”“Claude Code 如何驱动 HotSwan？”。
• 用户提到“MCP 服务”“hotswan_reload”“hotswan_take_screenshot”“Agent 循环”或“快照回滚”。

何时不应使用此技能

• 纯代码审查，不需要运行时反馈（完全不需要 MCP 工具）。
• 发布级视觉回归测试。请使用 Macrobenchmark 和截图差异测试框架，而不是 HotSwan 快照。交叉链接 ../../measurement/generating-baseline-profiles/SKILL.md。
• 相关修改会导致完整重建（添加参数、修改构造函数、新增资源 ID）。使用 MCP 循环前，请先阅读 ../understanding-hot-reload-limits/SKILL.md，判断修改属于哪一类。
• 重新加载不断升级到第 2 或第 3 级并导致状态丢失。请先通过 ../preserving-state-across-reloads/SKILL.md 解决此问题，再在此基础上添加自主循环。

前置条件

• 已安装 Compose HotSwan，且 IDE 插件处于启用状态。安装说明位于 ../setting-up-compose-hotswan/SKILL.md。
• 目标应用已在连接的设备或模拟器上运行，且 HotSwan 监视器状态显示为 WATCHING。
• 已启用 MCP 服务发现并指向 HotSwan 插件的 HTTP MCP 端点的 MCP 兼容 AI 客户端（Claude Code、Cursor）。

MCP 工具（名称必须原样使用）

HotSwan MCP 服务准确提供以下七个工具。Agent 不得编造其他工具名称。

• hotswan_get_status()：返回设备、应用和监视器状态。每次循环开始时调用一次，确认 Agent 已连接目标设备，且监视器状态为 WATCHING。
• hotswan_reload(filePaths)：显式触发所列文件路径的重新加载。返回已执行的级别（1 / 2 / 3）。Agent 根据级别判断上一次修改是否让循环保持快速。
• hotswan_take_screenshot()：截取当前设备屏幕。返回图像字节数据或可供 Agent 读取和检查的路径。
• hotswan_start_snapshot()：开始快照会话。调用后，HotSwan 会在每次重新加载后自动截取屏幕并记录源代码状态，因此 Agent 可以回滚到任意中间版本。
• hotswan_stop_snapshot()：结束当前快照会话并完成历史记录。
• hotswan_select_variant()：从记录的历史中选择一个首选快照。Agent 认定较早的某次迭代效果最好时，可用此工具将源代码回滚到所选版本。
• hotswan_build_and_install()：回退到完整安装。Agent 检测到架构变更（新增参数、修改构造函数、新增资源 ID）而热重载流程无法处理时使用。请将其视为回退方案，而非常规默认选项。

工作流

标准的 Agent 循环：

1. 执行任何编辑前检查状态

调用 hotswan_get_status()。如果 watcher 不是 WATCHING，请将问题告知人工操作人员并停止。如果 watcher 未运行，重新加载工具会静默地不执行任何操作，Agent 便会白白耗费时间，不明白屏幕上为什么毫无变化。

2. 开启快照会话

调用 hotswan_start_snapshot()，以便为循环留下可视化记录。会话中的每次重新加载都会自动捕获快照，方便 Agent（或之后进行审核的人工操作人员）比较各次迭代，并回滚到任意变体。

3. 编辑目标文件

使用 Agent 可用的任意文件编辑工具编辑 Kotlin 文件。尽可能将更改限制在一个可组合项作用域内，使重新加载保持在第 1 级（交叉参考 ../preserving-state-across-reloads/SKILL.md）。

4. 触发重新加载并查看级别

调用 hotswan_reload(["app/src/main/kotlin/com/example/Foo.kt"])。查看返回的级别。第 1 级表示循环保持快速；第 2 级或第 3 级表示状态可能已丢失，Agent 应预期需要在下一张截图前重新建立导航状态或临时 UI 状态。

5. 截图并评估

调用 hotswan_take_screenshot()。将返回的图像与设计意图进行比较。如果可以接受，则退出循环；否则，返回第 3 步并完善编辑。

6. 架构变更时回退处理

如果计划进行的下一项编辑会更改函数签名、构造函数或接口，或添加新的资源 ID，请调用 hotswan_build_and_install() 执行完整安装，然后再继续。不要对违反架构约束的编辑反复调用 hotswan_reload；重新加载工具会报告失败，循环也会停滞。

7. 结束循环

迭代结果可以接受时，调用 hotswan_stop_snapshot()。如果最终状态不是最佳状态，也可以调用 hotswan_select_variant()，将源代码回滚到首选的中间变体。

模式

模式：跳过状态检查

// WRONG
1. Edit file
2. Call hotswan_reload
3. Wonder why nothing happened
// WRONG because: HotSwan needs the app running and the watcher in WATCHING state. If neither is true the reload silently no-ops. Always call hotswan_get_status first.

// RIGHT
1. status = hotswan_get_status()
2. require(status.watcher == "WATCHING")
3. edit, reload, screenshot, iterate

模式：未开启快照会话就重新加载

// WRONG (for visual iteration)
edit -> reload -> screenshot -> discard -> repeat
// WRONG because: the agent loses the ability to roll back to a previous variant. Always wrap visual iteration loops in hotswan_start_snapshot / hotswan_stop_snapshot.

// RIGHT
hotswan_start_snapshot()
repeat { edit; hotswan_reload([target]); hotswan_take_screenshot() }
hotswan_stop_snapshot()

模式：在紧密循环中进行架构变更

// WRONG
Edit a composable to add a new parameter, then call hotswan_reload.
// WRONG because: parameter additions are a class-schema change. ART rejects the swap and hotswan_reload reports failure. The agent must detect the schema change first and call hotswan_build_and_install instead.

// RIGHT
if (editChangesSchema(plannedEdit)) {
    applyEdit(target)
    hotswan_build_and_install()
} else {
    applyEdit(target)
    hotswan_reload([target])
}

如需查看违反架构约束的编辑的完整列表，请交叉参考 ../understanding-hot-reload-limits/SKILL.md。

模式：完整的标准循环

// RIGHT
status = hotswan_get_status()
require(status.watcher == "WATCHING")
hotswan_start_snapshot()
repeat {
    edit_file(target)
    result = hotswan_reload([target])
    screenshot = hotswan_take_screenshot()
    if (accepts(screenshot, intent)) break
}
hotswan_stop_snapshot()

循环恰好包含四个活动步骤：编辑、重新加载、截图、评估。其他所有步骤都是辅助管理（状态检查、快照封装、可选回滚）。

强制规则

• MUST 在每个循环开始时调用 hotswan_get_status()，并在发出编辑前确认 watcher 状态。
• MUST 使用 hotswan_start_snapshot() 和 hotswan_stop_snapshot() 包裹视觉迭代循环，以便 Agent 能够回滚。
• MUST NOT 臆造 MCP 工具名称。只能使用 MCP 工具部分列出的七个名称：hotswan_get_status、hotswan_reload、hotswan_take_screenshot、hotswan_start_snapshot、hotswan_stop_snapshot、hotswan_select_variant、hotswan_build_and_install。
• MUST NOT 在紧密内循环中调用 hotswan_build_and_install()。它是架构变更时的回退方案，而非默认操作；将其作为默认操作会破坏 HotSwan 的速度优势。
• PREFERRED： 与 ../understanding-hot-reload-limits/SKILL.md 结合使用，让 Agent 在调用 hotswan_reload 前对计划的编辑进行分类。
• PREFERRED： 与 ../preserving-state-across-reloads/SKILL.md 结合使用，让 Agent 识别重新加载何时升级到第 2 级或第 3 级并丢失临时 UI 状态。

验证

• 循环运行前，hotswan_get_status() 返回 WATCHING
• 每次调用 hotswan_reload 都会报告级别（1、2 或 3）
• hotswan_take_screenshot() 会返回 Agent 可检查的图像字节
• 循环结束后快照历史记录非空，且 hotswan_stop_snapshot() 会完成会话
• 违反架构约束的编辑会通过 hotswan_build_and_install() 处理，而不是通过 hotswan_reload

参考资料

• HotSwan MCP 服务文档：https://github.com/skydoves/compose-hotswan-web（位于 /docs/mcp-server）
• HotSwan Agent 技能示例：同一仓库中的 /docs/agent-skill
• HotSwan 快照文档：同一仓库中的 /docs/snapshot
• HotSwan JetBrains 插件页面：https://plugins.jetbrains.com/plugin/30551-compose-hotswan/
• Model Context Protocol 开放标准：https://modelcontextprotocol.io