👾 Open Computer Use – Open-Source Alternative to Codex Computer Use
Swift accessibilityai-agentai-agentsclaude-codecodexcodex-computer-usecomputer-usecomputer-use-agentcross-platformcuadesktop-automationgemini-cligui-automationmacosmcpmodel-context-protocolopen-computer-useopen-computer-use-mcpopenai-codexopencode
docs: document background click research workflow
Leoa00ebbef146c
diff --git a/.gitignore b/.gitignoreindex 960377f..f86bf78 100644--- a/.gitignore+++ b/.gitignore@@ -4,5 +4,6 @@.swiftpm/dist/artifacts/codex-dumps/+research/__pycache__/*.pycdiff --git a/docs/histories/2026-04/20260422-1737-add-bgclick-free-research.md b/docs/histories/2026-04/20260422-1737-add-bgclick-free-research.mdnew file mode 100644index 0000000..ca13197--- /dev/null+++ b/docs/histories/2026-04/20260422-1737-add-bgclick-free-research.md@@ -0,0 +1,23 @@+# document-bgclick-free-research-workflow++## 用户诉求++用 Ghidra 等免费工具替代 IDA Pro,对 bundled computer-use app 做后台点击方向的反编译研究;研究目录太大,不提交 `research/`,只把后续 Agent 可复跑的方法论沉淀到 docs。++## 本次改动++- 将 `research/` 加入仓库级 `.gitignore`,避免提交一次性 Ghidra project、反汇编大文件和临时 Swift 构建产物。+- 新增后台点击免费工具链研究方法论文档,记录 Ghidra/radare2/Apple CLI/Swift 原型的复跑步骤。+- 更新 reverse-engineering docs 入口,说明大体积分析产物应在本地 `research/` 下重新生成。+- 保留本轮已经验证过的关键结论:`NSEvent -> CGEvent`、window id fields、私有 `CGEventSetWindowLocation` 和 `postToPid` 是后台点击复现的核心路径。++## 设计动机++官方二进制是 stripped Swift/ObjC Mach-O,无法直接恢复原始源码;一次性反编译产物体积过大,长期价值也不如可复跑方法论。将方法、关键证据形状和验证矩阵写进 docs,可以让后续开发者按需让 AI 重新生成本地研究目录,同时保持仓库轻量。++## 影响文件++- `.gitignore`+- `docs/references/README.md`+- `docs/references/codex-computer-use-reverse-engineering/README.md`+- `docs/references/codex-computer-use-reverse-engineering/background-click-free-tooling.md`diff --git a/docs/references/README.md b/docs/references/README.mdindex 8da9630..4291d10 100644--- a/docs/references/README.md+++ b/docs/references/README.md@@ -14,7 +14,7 @@## 当前目录- `codex-computer-use-reverse-engineering/`- - 官方 `Codex Computer Use.app` / `SkyComputerUseClient` 的持续逆向分析资料。+ - 官方 `Codex Computer Use.app` / `SkyComputerUseClient` 的持续逆向分析资料;大体积一次性分析产物默认在本地 `research/` 下重新生成,不提交进仓库。- `codex-network-capture.md`- 用 `mitmdump` + `scripts/codex_dump.py` 抓 Codex 上游 HTTP / WebSocket 流量,并把对应 `session_id` 的本地 `function_call` / `function_call_output` 摘要一起沉淀到 `artifacts/codex-dumps/` 做持续分析。- `codex-local-runtime-logs.md`diff --git a/docs/references/codex-computer-use-reverse-engineering/README.md b/docs/references/codex-computer-use-reverse-engineering/README.mdindex 6167aae..faf4552 100644--- a/docs/references/codex-computer-use-reverse-engineering/README.md+++ b/docs/references/codex-computer-use-reverse-engineering/README.md@@ -14,6 +14,8 @@- 当前已确认的 client-service 内部 IPC 类型、sender authorization、skyshot 模型和 service 生命周期线索。- `tool-call-samples-2026-04-17.md`- 2026-04-17 对 9 个公开 `computer-use` tools 的实测 request / response 样本。+- `background-click-free-tooling.md`+ - 用 Ghidra、radare2、Apple CLI 和 Swift 原型替代 IDA Pro 研究后台点击路径的方法论,供后续 Agent 在本地 `research/` 目录重新生成大体积分析产物。- `software-cursor-overlay.md`- 对黄色虚拟鼠标 overlay 的资源、字符串和运行时窗口证据分析。- `software-cursor-motion-model.md`diff --git a/docs/references/codex-computer-use-reverse-engineering/background-click-free-tooling.md b/docs/references/codex-computer-use-reverse-engineering/background-click-free-tooling.mdnew file mode 100644index 0000000..7480725--- /dev/null+++ b/docs/references/codex-computer-use-reverse-engineering/background-click-free-tooling.md@@ -0,0 +1,196 @@+# Background Click Free Tooling Workflow++这份文档记录一次用免费工具替代 IDA Pro 研究官方 bundled `computer-use` 后台点击路径的方法论。它不是要把一次性 Ghidra project、反汇编大文件或临时 Swift 原型提交进仓库,而是让后续开发者或 AI 可以按同样步骤重新生成本地研究目录。++## 适用场景++当需要研究官方闭源 `Codex Computer Use.app` 的鼠标点击、后台窗口投递、`CGEvent` 字段或 AppKit / AX 交互路径时,优先按本文新建一个本地 `research/<topic>-<date>/` 目录。仓库级 `.gitignore` 已忽略 `research/`,避免把大体积二进制分析产物带进提交。++## 工具链++免费工具组合:++```bash+brew install ghidra radare2+python3 -m pip install --user frida-tools lief capstone+```++常用系统工具:++```bash+xcrun -f otool+xcrun -f nm+xcrun -f swift-demangle+xcrun -f llvm-objdump+codesign --help+```++如果 Ghidra headless 找不到 Java,显式设置:++```bash+export JAVA_HOME="$(brew --prefix openjdk@21)/libexec/openjdk.jdk/Contents/Home"+```++Ghidra headless 入口通常是:++```bash+"$(brew --prefix ghidra)/libexec/support/analyzeHeadless"+```++## 目标定位++默认从 bundled plugin 中取目标二进制。不要在文档里写机器绝对路径;本地运行时用环境变量拼出来:++```bash+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"+APP="$CODEX_HOME/plugins/cache/openai-bundled/computer-use/1.0.755/Codex Computer Use.app"+SERVICE="$APP/Contents/MacOS/SkyComputerUseService"+CLIENT="$APP/Contents/SharedSupport/SkyComputerUseClient.app/Contents/MacOS/SkyComputerUseClient"+```++先确认 bundle、签名和 Mach-O 类型:++```bash+file "$SERVICE" "$CLIENT"+codesign -dv --verbose=4 "$APP" > raw/codesign-service-app.txt 2>&1+codesign -dv --verbose=4 "$APP/Contents/SharedSupport/SkyComputerUseClient.app" > raw/codesign-client-app.txt 2>&1+```++## 静态信息采集++建议先把原始输出落到 `research/<topic>/raw/`,方便 AI 后续 grep 和引用:++```bash+mkdir -p raw+nm -u "$SERVICE" > raw/nm-u-service.txt+nm -u "$CLIENT" > raw/nm-u-client.txt+otool -L "$SERVICE" > raw/otool-L-service.txt+otool -Iv "$SERVICE" > raw/otool-Iv-service.txt+rabin2 -I "$SERVICE" > raw/rabin2-I-service.txt+rabin2 -i "$SERVICE" > raw/rabin2-imports-service.txt+rabin2 -zz "$SERVICE" > raw/rabin2-strings-service.txt+strings "$SERVICE" | swift-demangle > raw/strings-demangled-service.txt+```++对后台点击方向,优先搜索这些关键词:++```bash+rg "mouseEventWithType|eventWithCGEvent|CGEvent|buttonNumber|clickCount|windowNumber|AXUIElement|CGWindowList|dlopen|dlsym" raw+```++高价值命中通常包括:++- `mouseEventWithType:location:modifierFlags:timestamp:windowNumber:context:eventNumber:clickCount:pressure:`+- `eventWithCGEvent:`+- `AXUIElementCopyElementAtPosition`+- `AXUIElementPerformAction`+- `AXUIElementSetAttributeValue`+- `CGWindowListCopyWindowInfo`+- `CGWindowListCreateDescriptionFromArray`+- `dlopen` / `dlsym`++## Ghidra Headless 导出策略++不要手工在 GUI 里逐个点函数。写一个 headless script,按符号名和字符串命中收集 candidate functions,再批量 decompile 到 `ghidra-service/`。++推荐脚本能力:++- 输入关键词列表,例如 `AXUIElement`、`CGWindowList`、`NSEvent`、`CGEvent`、`mouseEventWithType`、`windowNumber`。+- 遍历 symbol table、defined strings 和 references。+- 将命中函数 decompile 成独立 `.c` 文件。+- 额外支持按地址导出,方便二次追踪 wrapper / resolver。++运行形态:++```bash+mkdir -p ghidra-project ghidra-service tools+"$(brew --prefix ghidra)/libexec/support/analyzeHeadless" \+ "$PWD/ghidra-project" ComputerUseService \+ -import "$SERVICE" \+ -scriptPath "$PWD/tools" \+ -postScript FocusExport.java "$PWD/ghidra-service"+```++如果已经知道关键地址,再用单独脚本导出:++```bash+"$(brew --prefix ghidra)/libexec/support/analyzeHeadless" \+ "$PWD/ghidra-project" ComputerUseService \+ -process SkyComputerUseService \+ -scriptPath "$PWD/tools" \+ -postScript ExportAddresses.java "$PWD/ghidra-service/address-decompiled" \+ 10050d404 100569a5c 1000ae328 1000ae398 1000b8830+```++## 后台点击核心判断++本轮已经验证出的关键路径如下。后续 AI 重新生成代码时,应以这个调用形状为优先方向:++1. 用 `CGWindowListCopyWindowInfo` 找到目标进程的 layer 0 窗口、bounds 和 `CGWindowID`。+2. 用 `NSEvent.mouseEvent(...)` 创建 down/up 事件,`windowNumber` 传目标 `CGWindowID`。+3. 从 `NSEvent.cgEvent` 取出底层 `CGEvent`。+4. 设置字段:+ - field `3`: button number,也就是公开的 `kCGMouseEventButtonNumber`+ - field `7`: 观察值为 `3`+ - field `91`: window under pointer+ - field `92`: event target window+5. 设置 screen-space `CGEvent.location`。+6. 把 screen point 转成 window-local point。+7. 调用私有符号 `CGEventSetWindowLocation(event, localPoint)`。+8. 用 `CGEvent.postToPid(pid)` 定向投递到目标进程。++在 AppKit 测试目标上,`CGEventSetWindowLocation` 是关键对照项:保留它时后台窗口能收到 `mouseDown/mouseUp`;跳过它时没有新点击到达。官方二进制的某个后台分支会把 flags 置为 `0x100000`,但简单 AppKit fixture 上它不是事件到达的必要条件。++## 最小 Swift 复现方向++让 AI 生成本地原型时,建议建一个 Swift package,包含两个 executable target:++- `BackgroundClickProbe`+ - 参数支持 `--pid`、`--bundle-id`、`--app`、`--window-id`、`--point`、`--dry-run`。+ - 用 `dlsym(RTLD_DEFAULT, "CGEventSetWindowLocation")` 解析私有符号。+ - 输出 JSON,包含 pid、window id、bounds、screen point、local point、flags 和是否 dry run。+- `EchoApp`+ - 一个最小 AppKit 窗口。+ - override `mouseDown` / `mouseUp`。+ - 同时打印 stdout 并写 `/tmp/bgclick-echoapp.log`,方便用 `open` 或后台进程验证。++验证矩阵至少覆盖:++```bash+swift build+ECHOAPP_LOG=/tmp/bgclick-echoapp.log .build/debug/EchoApp+.build/debug/BackgroundClickProbe --app EchoApp+.build/debug/BackgroundClickProbe --app EchoApp --no-background-flag+.build/debug/BackgroundClickProbe --app EchoApp --skip-window-location+.build/debug/BackgroundClickProbe --app EchoApp --nsevent-location local+tail -n 20 /tmp/bgclick-echoapp.log+```++期望看到目标在 `active=false`、`key=false` 时仍收到 `mouseDown` / `mouseUp`。如果默认命令失败,优先检查:++- `AXIsProcessTrusted()` 是否为 true。+- `dlsym` 是否能解析 `CGEventSetWindowLocation`。+- `CGWindowID` 是否来自目标进程的 layer 0 on-screen window。+- `window-local` 坐标是否按 `screenPoint - windowBounds.origin` 计算。+- 是否误用了全局 HID post,而不是 `postToPid`。++## 提交边界++不要提交这些内容:++- `research/` 下的一次性 Ghidra project。+- 大体积 `llvm-objdump` / `rabin2 -zz` / strings 原始输出。+- 临时 Swift package 的 `.build/`。+- 从官方 bundle 直接导出的二进制或大资源,除非明确放到 `docs/references/.../assets/` 并配合 Git LFS 规则。++可以提交这些内容:++- 经过整理的结论文档。+- 小型、通用、可复跑的 Ghidra script 或采集脚本。+- 已经产品化并进入主 runtime / smoke 的开源实现代码。++## 已知限制++- Ghidra 伪代码不是源码,Swift async、ObjC message send 和动态 resolver 处需要靠调用形状、字符串和运行验证共同判断。+- `CGEventSetWindowLocation` 是私有 API,只适合研究和本地对照,不应直接作为发布产品依赖。+- 行为依赖 macOS 版本、TCC 权限、目标 App toolkit 和签名/宿主环境。