FixThis

用于 Android Compose 的 FixThis

指向 Jetpack Compose UI，写下要做的修改，然后把编码 Agent 所需的源代码上下文交给 Claude、Codex、 Cursor 或其他编码 Agent。

FixThis 仅用于调试。它会在 Compose 调试应用中附加一个辅助工具，将屏幕镜像到本地浏览器控制台，并将注释整理成精简的交接信息：屏幕截图边界、语义信息、源代码候选项和置信度警告。

点击组件即可选中。如果目标是间距、空白区域，或不是清晰 Compose 节点的内容，请拖动选择。

目前可用

• 大约五分钟即可试用示例应用。
• 使用 Homebrew、npm 或 GitHub Releases 安装桌面命令行工具/MCP。
• 使用 Gradle 插件 io.github.beyondwin.fixthis.compose 将其添加到外部应用。
• 让 Claude Code 或 Codex 使用 ./scripts/bootstrap-mcp.sh --sample 配置示例。
• 让 Agent 使用 fixthis install-agent 配置你的应用。
• 使用 Copy Prompt，配合 Cursor、ChatGPT 或任何聊天 Agent。
• 使用 Save to MCP，配合 Claude Code 或 Codex。
• Save to MCP 可以附加范围受限且经过脱敏的 Android 诊断基线。 如果不需要，请将会话切换为 Manual 或 Off。Copy Prompt 不会启动数据收集。
• 通过 ADB 和 127.0.0.1 在本地运行。不会调用外部 API。

快速开始：让 Agent 在你的应用中安装 FixThis

Claude Code / Codex 引导提示词

在 Jetpack Compose Android 应用的根目录中，将此内容粘贴到 Claude Code 或 Codex：

Install FixThis in this project and configure it for this agent.

Use this order:
1. Run `fixthis install-agent --project-dir . --target all --verify --json`.
2. Use the JSON `readiness.state` and `actions[]` as the source of truth.
3. If `requiresUserAction` is true, tell me the exact blocking action.
4. Do not call `fixthis_open_feedback_console` until `readyForMcpTooling` is true, or until the report's `agent_after_restart` action is reached after restart.

Restart Claude Code or Codex if the report asks for it.
Do not configure release builds. Do not commit `.fixthis/`.

Agent 应运行：

# macOS
brew install beyondwin/tools/fixthis

# Node
npm install -g @beyondwin/fixthis

# macOS/Linux fallback
curl -fsSL https://raw.githubusercontent.com/beyondwin/FixThis/main/scripts/install-fixthis.sh \
  | bash -s -- --version v1.5.0

fixthis install-agent --project-dir . --target all --verify --json

如果 Homebrew 中已安装，请运行 brew update && brew upgrade beyondwin/tools/fixthis 并检查 fixthis --version。

fixthis install-agent 会应用 Gradle 插件、写入 MCP 配置，并写入 .fixthis/project.json 和 .fixthis/agent-setup.*。如果 doctor 报告 NEEDS_INSTALL 或缺少元数据，请运行 ./gradlew fixthisSetup，然后重新运行 fixthis install-agent --project-dir . --target all --verify --json。 如果报告提示需要重启，请重启 Claude Code 或 Codex，然后调用 fixthis_open_feedback_console。如需手动检查，请使用 fixthis doctor --project-dir . --json。

已发布的插件：

plugins {
    id("io.github.beyondwin.fixthis.compose") version "1.5.0"
}

该插件会添加仅用于调试的辅助工具，并确保发布版本构建不受影响。

快速开始：从示例应用交接给 Agent

git clone <this-repo> && cd FixThis
./gradlew :fixthis-cli:installDist :fixthis-mcp:installDist
fixthis-cli/build/install/fixthis/bin/fixthis doctor --package io.github.beyondwin.fixthis.sample
fixthis-cli/build/install/fixthis/bin/fixthis run --package io.github.beyondwin.fixthis.sample

fixthis run 会安装示例调试 APK、启动应用，并在 http://127.0.0.1:<port> 打开 FixThis Studio。

在控制台中：

1. 点击 Annotate。
2. 点击一个 UI 元素，或拖动选择一个区域。
3. 输入你想要的修改。
4. 对此屏幕上的其他位置重复操作。
5. 对聊天 Agent 使用 Copy Prompt，或对 Claude Code / Codex 使用 Save to MCP。

当编号注释显示出来，且你已复制 Markdown 或保存本地 MCP 交接信息后，就完成了。

维护者可以在已连接的设备上验证 Copy Prompt 流程：

npm run real-copy-prompt:smoke -- --strict

选择你的路径

目标	从这里开始
不改动应用即可试用	示例快速入门
将其添加到调试构建中	添加到应用
连接 Agent	连接你的 Agent
从此仓库引导 MCP	MCP.md
使用控制台	控制台导览
了解产品	产品
诊断故障	故障排查
查看契约	文档索引
参与贡献	CONTRIBUTING.md

读者	从这里开始
首次使用的用户	示例快速入门
外部应用开发者	添加到应用
此仓库中的 Agent	AGENTS.md 和 项目概览
维护者	文档索引 和 项目概览
契约或 CLI 变更	参考契约

为什么不直接用截图？

当目标一目了然时，截图就足够了。如果 UI 密集、以列表形式呈现，或主要以可组合项命名，FixThis 就能派上用场：

• 排名前 3 的源代码候选项，附带行号和匹配原因
• editSurface 提示，指出问题位于调用点、组件、文案、布局还是互操作层
• 实例分组，确保相同的卡片仍可区分
• 屏幕指纹，防止旋转或变化后的屏幕被误存
• 如实呈现置信度：仅视觉判断、信息过期，或可能涉及 AndroidView/WebView
• 保存到 MCP 时提供有界的运行时诊断信息
• 支持安全重试的批次处理，不会重复执行工作

模块

模块	作用
:app (sample/)	验证示例
:fixthis-compose-core	纯 Kotlin 领域逻辑
:fixthis-compose-sidekick	Android 调试运行时
:fixthis-gradle-plugin	源码索引和调试接线
:fixthis-cli	桌面 CLI
:fixthis-mcp	MCP 服务和本地控制台

更多信息：产品、决策、 架构。

状态

公开安装方式：

• Gradle 插件 io.github.beyondwin.fixthis.compose
• Maven io.github.beyondwin:fixthis-compose-sidekick 和 fixthis-compose-core
• Homebrew brew install beyondwin/tools/fixthis
• GitHub Release fixthis-cli-mcp-vX.Y.Z.tar.gz
• npm @beyondwin/fixthis
• MCP Registry io.github.beyondwin/fixthis

实时仪表板：发布就绪情况。

main 分支可能领先于最新标签。请参阅 CHANGELOG 和发布说明。

此仓库中的 Agent 应阅读 AGENTS.md。

信任

FixThis 始终在你的设备上运行。sidekick 通过 ADB 通信，控制台绑定到 localhost，而保存到 MCP会写入 .fixthis/。截图仍可能包含敏感像素。 分享前请先检查。不要提交 .fixthis/。

详情：隐私、安全、 威胁模型。

V1 范围保持精简：Compose 调试构建、本地 ADB、MCP 优先的交接、尽力提供的 源码候选项，不上传到云端。请参阅路线图。

许可证

MIT。第三方声明见 NOTICE。