Skip to content

👾 Open Computer Use – Open-Source Alternative to Codex Computer Use

feat: rename cursor motion demo and add dmg release

Leoa731061302cb
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index ced1893..510f0aa 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -19,7 +19,7 @@ on:
type: string
permissions:
- contents: read
+ contents: write
id-token: write
jobs:
@@ -69,3 +69,47 @@ jobs:
--skip-build \
--out-dir dist/release/npm-staging \
--tag "${NPM_DIST_TAG}"
+
+ release-cursor-motion-dmg:
+ if: ${{ github.event_name == 'push' }}
+ runs-on: macos-26
+
+ steps:
+ - name: Check out repository
+ uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd
+
+ - name: Make DMG build script executable
+ run: chmod +x ./scripts/build-cursor-motion-dmg.sh
+
+ - name: Build Cursor Motion DMG
+ env:
+ RELEASE_TAG: ${{ github.ref_name }}
+ run: |
+ version="${RELEASE_TAG#v}"
+ ./scripts/build-cursor-motion-dmg.sh \
+ --configuration release \
+ --arch universal \
+ --version "${version}"
+
+ - name: Upload Cursor Motion release artifact
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+ with:
+ name: cursor-motion-release-artifact
+ path: dist/release/cursor-motion/*.dmg
+ if-no-files-found: error
+
+ - name: Publish Cursor Motion DMG to GitHub Releases
+ env:
+ GH_TOKEN: ${{ github.token }}
+ RELEASE_TAG: ${{ github.ref_name }}
+ run: |
+ version="${RELEASE_TAG#v}"
+ dmg_path="dist/release/cursor-motion/CursorMotion-${version}.dmg"
+
+ if gh release view "${RELEASE_TAG}" >/dev/null 2>&1; then
+ gh release upload "${RELEASE_TAG}" "${dmg_path}" --clobber
+ else
+ gh release create "${RELEASE_TAG}" "${dmg_path}" \
+ --title "${RELEASE_TAG}" \
+ --generate-notes
+ fi
diff --git a/Package.swift b/Package.swift
index eeef4c6..32ecdf1 100644
--- a/Package.swift
+++ b/Package.swift
@@ -25,8 +25,8 @@ let package = Package(
targets: ["OpenComputerUseSmokeSuite"]
),
.executable(
- name: "StandaloneCursorLab",
- targets: ["StandaloneCursorLab"]
+ name: "CursorMotion",
+ targets: ["CursorMotion"]
),
.executable(
name: "StandaloneCursor",
@@ -54,8 +54,8 @@ let package = Package(
path: "apps/OpenComputerUseSmokeSuite/Sources/OpenComputerUseSmokeSuite"
),
.executableTarget(
- name: "StandaloneCursorLab",
- path: "experiments/StandaloneCursorLab/Sources/StandaloneCursorLab"
+ name: "CursorMotion",
+ path: "experiments/CursorMotion/Sources/CursorMotion"
),
.target(
name: "StandaloneCursorSupport",
diff --git a/README.md b/README.md
index 02e6a3a..8399e8b 100644
--- a/README.md
+++ b/README.md
@@ -56,18 +56,14 @@ open-computer-use doctor
open-computer-use -h
```
-## Cursor Demos
+## Cursor Motion
-This repo now includes two standalone cursor-motion demos so the reconstructed model and the more speculative lab work can evolve separately:
+Cursor Motion is an open-source cursor motion system for macOS, based on public information shared by members of the Software.Inc team. You can run it from source or download the app from the [Releases page](https://github.com/iFurySt/open-codex-computer-use/releases).
```bash
-swift run StandaloneCursor
-swift run StandaloneCursorLab
+swift run CursorMotion
```
-- [`experiments/StandaloneCursor`](./experiments/StandaloneCursor) is the cleaner binary-guided viewer built directly from `scripts/cursor-motion-re/official_cursor_motion.py`. It focuses on the recovered 20-candidate pool, score model, and raw spring timeline.
-- [`experiments/StandaloneCursorLab`](./experiments/StandaloneCursorLab) remains the more experimental lab for UI-heavy tuning, candidate overlays, and visual-dynamics exploration.
-
## License
[MIT](./LICENSE)
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 0c38069..0180032 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -61,18 +61,14 @@ open-computer-use doctor
open-computer-use -h
```
-## Cursor Demos
+## Cursor Motion
-仓库里现在有两条独立的 cursor motion demo 线路,把“基于重建脚本的直接实现”和“更自由的实验室版本”拆开维护:
+Cursor Motion 是一个面向 macOS 的开源光标运动系统,基于 Software.Inc 几位大佬的公开信息实现的开源版本,可以代码里运行,也可以到 [Releases 页面](https://github.com/iFurySt/open-codex-computer-use/releases) 下载 app 运行。
```bash
-swift run StandaloneCursor
-swift run StandaloneCursorLab
+swift run CursorMotion
```
-- [`experiments/StandaloneCursor`](./experiments/StandaloneCursor) 是一条更干净的 binary-guided viewer,直接对应 `scripts/cursor-motion-re/official_cursor_motion.py` 里的候选路径池、score 和 raw spring timeline。
-- [`experiments/StandaloneCursorLab`](./experiments/StandaloneCursorLab) 继续保留为更偏实验的 lab,用来做 UI、candidate overlay 和 visual dynamics 调参。
-
## License
[MIT](./LICENSE)
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 689f893..33ed49f 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -18,7 +18,7 @@
- 键鼠输入模拟
- software cursor overlay
- fixture test bridge
-- `experiments/StandaloneCursorLab`
+- `experiments/CursorMotion`
独立的 Swift cursor motion lab,用于试验 `Bezier + arc + spring` 参数模型、调参 UI 和独立渲染,不直接耦合主 MCP runtime。
- `experiments/StandaloneCursor`
新的独立 Swift cursor viewer,直接复用 `scripts/cursor-motion-re/official_cursor_motion.py` 里收敛出来的候选路径、score 与 raw spring timeline,用来观察更贴近 binary lift 的表现。
@@ -82,8 +82,8 @@
- `StandaloneCursor` 是一个新的独立 SwiftUI/AppKit demo target,可通过 `swift run StandaloneCursor` 本地启动。
- 这条线优先验证 Python 重建脚本已经收敛出来的核心:`20` 条候选路径、`measure + score`、`prefer in-bounds then lowest-score` 选路,以及 `response=1.4` / `dampingFraction=0.9` / `dt=1/240` 的 raw spring timeline。
-- 当前它刻意不引入 speculative 的 wall-clock duration 映射,也不复用 `StandaloneCursorLab` 里更偏视觉手感试验的 pose dynamics。
-- `StandaloneCursorLab` 是一个单独的 SwiftUI demo target,可通过 `swift run StandaloneCursorLab` 本地启动。
+- 当前它刻意不引入 speculative 的 wall-clock duration 映射,也不复用 `CursorMotion` 里更偏视觉手感试验的 pose dynamics。
+- `CursorMotion` 是一个单独的 SwiftUI demo target,可通过 `swift run CursorMotion` 本地启动。
- 这条线优先验证 motion model 本身:当前主线是 heading-driven 的 turn / brake / orbit / direct candidate 族、spring progress、独立 visual dynamics 和 debug UI;moving 阶段真正画出来的箭头角度会持续跟随 visual dynamics 的主 heading,接近停住后再平滑回到默认 resting pose,并在 idle 阶段保留原地小摆角。
- lab 的 cursor 视觉当前单独参考 `scripts/render-synthesized-software-cursor.swift`:优先使用仓库里保存的官方 `252x252` runtime baseline 图,缺失时再退回脚本里的 procedural pointer/fog 近似;settle 态也改成中心固定的小幅摆角,而不是继续沿 XY 轻微漂移。
- 当前它不接真实 tool call,也不回写主 `SoftwareCursorOverlay`,目的是把实验噪音与产品行为边界隔离开。
@@ -100,7 +100,7 @@
- 单元测试:`swift test`
- standalone cursor 构建:`swift build --product StandaloneCursor`
-- cursor lab 构建:`swift build --product StandaloneCursorLab`
+- cursor lab 构建:`swift build --product CursorMotion`
- 端到端 smoke:`./scripts/run-tool-smoke-tests.sh`
- app 打包:`./scripts/build-open-computer-use-app.sh debug`
- npm staging:`node ./scripts/npm/build-packages.mjs`
diff --git a/docs/CICD.md b/docs/CICD.md
index 9c87b33..bae3915 100644
--- a/docs/CICD.md
+++ b/docs/CICD.md
@@ -5,7 +5,8 @@
## 当前 release 入口
- `scripts/release-package.sh`:构建 universal `Open Computer Use.app`,stage 三个 npm 包目录,并产出 `dist/release/npm/*.tgz` 与 `dist/release/release-manifest.json`。
-- `.github/workflows/release.yml`:支持 push semver tag 自动发布,也支持手动触发;它会调用仓库内的 npm release 打包逻辑,并优先兼容 GitHub Actions OIDC / npm Trusted Publishing,同时支持仓库 `NPM_TOKEN` secret 作为发布兜底。
+- `scripts/build-cursor-motion-dmg.sh`:本地构建 `Cursor Motion.app` 并封装 `dist/release/cursor-motion/CursorMotion-<version>.dmg`,支持 `native` / `arm64` / `x86_64` / `universal`。
+- `.github/workflows/release.yml`:支持 push semver tag 自动发布,也支持手动触发;tag push 时会同时跑 npm release 打包逻辑与 `Cursor Motion` 的 DMG 打包,并把 `.dmg` 上传到对应的 GitHub Releases 页面。当前 `Cursor Motion` 这条链路只做 ad-hoc codesign,不包含 notarization。
## 设计原则
@@ -31,6 +32,8 @@
- `dist/release/npm/open-computer-use-<version>.tgz`
- `dist/release/npm/open-computer-use-mcp-<version>.tgz`
- `dist/release/npm/open-codex-computer-use-mcp-<version>.tgz`
+- `dist/release/cursor-motion/CursorMotion-<version>.dmg`
- GitHub Actions 中上传的 npm release artifact
+- GitHub Releases 中和 tag 对齐的 `CursorMotion-<version>.dmg`
-也就是说,即使项目还没进入更复杂的部署阶段,仓库现在也已经具备了一条真实可复用的 npm 制品封装链路。
+也就是说,即使项目还没进入更复杂的部署阶段,仓库现在也已经同时具备了一条真实可复用的 npm 制品封装链路,以及一条由 git tag 驱动的 macOS app DMG 交付链路。
diff --git a/docs/exec-plans/active/20260418-standalone-cursor-lab.md b/docs/exec-plans/active/20260418-standalone-cursor-lab.md
index 7cd0ae9..b78f924 100644
--- a/docs/exec-plans/active/20260418-standalone-cursor-lab.md
+++ b/docs/exec-plans/active/20260418-standalone-cursor-lab.md
@@ -1,4 +1,4 @@
-# Standalone Cursor Lab
+# Cursor Motion
## 目标
@@ -74,7 +74,7 @@
- 2026-04-20:对照用户提供的官方视频抽帧后,确认 moving 阶段的可见箭头确实会持续跟随当前 move heading,而不是只保留一个轻微 lean;lab 现已撤回那层 `displayRotation` 分离,glyph 渲染重新直接使用 visual dynamics 的主 `rotation`。
- 2026-04-20:继续对照 `official-software-cursor-window-252.png` 与独立脚本的静止朝向后,确认 lab 之前额外加的 `-26.5°` glyph 补偿会让 moving heading 固定偏掉;当前已把静止基线收敛到和主运行时一致的“零旋转即左上朝向”,也就是 y-down 画布里的 `-3π/4`。
- 2026-04-20:继续排查“屁股超前”后,确认真正的问题是 lab 的 motion/heading 运行在 SwiftUI 的 y-down 坐标,但 glyph 渲染落在 AppKit 默认 y-up `NSView`;当前已在 glyph 渲染层对 angle、body offset 和 fog offset 统一做 y-down -> y-up 转换,避免 moving 姿态被垂直镜像。
-- 2026-04-20:把刚确认的 slider 语义进一步收回到 `StandaloneCursorLab` 主线上;`START HANDLE` 现在主要调起步段的 guide / reach / normal,`END HANDLE` 主要调收尾段的 guide / reach / normal,不再只是对整条曲线做对称缩放。同时移除了过紧的 corridor clipping,改用内缩 canvas bounds,避免默认样例里 `END HANDLE` 被提前裁没。
+- 2026-04-20:把刚确认的 slider 语义进一步收回到 `CursorMotion` 主线上;`START HANDLE` 现在主要调起步段的 guide / reach / normal,`END HANDLE` 主要调收尾段的 guide / reach / normal,不再只是对整条曲线做对称缩放。同时移除了过紧的 corridor clipping,改用内缩 canvas bounds,避免默认样例里 `END HANDLE` 被提前裁没。
- 2026-04-20:继续按同样方法收紧 `ARC SIZE`;当前它明确表示轨迹弧度而不是 cursor 大小,并且已经同时接到局部 path 的弧高/控制点侧向偏移,以及 chooser 对 `direct` 和 `arched` family 的偏好。默认点位采样下,`arcSize=0.04 -> 0.12` 会让 `curveScale` 从约 `10.3` 提升到 `47.7`,中段 `y` 也从约 `326.8` 抬到 `345.5`。
- 2026-04-20:继续收紧 `ARC FLOW`;当前它明确表示“最宽弧段在 chord 上更靠前还是更靠后”,实现上不再只是改 start/end reach 的抽象 bias,而是改到单段 cubic 控制点的前后相位偏置。
- 2026-04-20:继续收紧 `SPRING`;当前它明确表示 progress spring 的 `response / damping` 与 endpoint-lock 时间,默认 `spring=0.5` 会精确回到官方 `.official` 配置。采样下,`spring=0.25 / 0.5 / 0.75` 分别对应约 `1.0958s / 1.4292s / 1.8750s` 的 endpoint-lock,语义已经收成稳定的“左快右慢”。
@@ -83,6 +83,8 @@
- 2026-04-20:继续收口右上角控件;当前只保留 `DEBUG` 一个 switch,`MAIL` / `CLICK` 已移除,click pulse 默认常开,同时把 switch 的 on/off 底色拉开到和左侧 slider 一致的高对比语义。
- 2026-04-20:继续收口左右 panel 的容器样式;当前左上 slider 面板和右上 `DEBUG` 面板已经统一复用同一套 card shell,不再分别维护不同的 padding / frame 包装。
- 2026-04-20:继续修正 panel 在浅背景上的识别度;当前 card fill 已收成更实的灰白底,并加强描边和阴影,减少背景渐变直接透到 panel 上导致的“看起来像不同底色”问题。
+- 2026-04-20:已把独立 demo 的对外命名统一收口到 `Cursor Motion` / `CursorMotion`;Swift Package product、实验目录、README 入口和相关文档现在都以 `swift run CursorMotion` 为准,不再保留 `StandaloneCursorLab` 旧名。
+- 2026-04-20:已补一条 tag 驱动的 `Cursor Motion` 分发链路;本地可以通过 `scripts/build-cursor-motion-dmg.sh` 构建 DMG,GitHub Actions 在推送 release tag 后会自动生成 `CursorMotion-<version>.dmg` 并上传到 GitHub Releases。
## 决策记录
@@ -91,10 +93,11 @@
- 2026-04-18:第一版 demo 先用独立 SwiftUI target + `CVDisplayLink` 驱动模拟,优先验证参数语义和轨迹手感,再考虑与主 overlay 合流。
- 2026-04-19:在拿到更完整的 binary-backed 路径与视觉层实现后,lab 改为直接演示 recovered 结构,不再把未经确认的 slider 语义继续当成主实现。
- 2026-04-19:对 `swift_once` 恢复出的 guide 系数,当前默认采用“常量已确认、世界坐标解释不成立、局部基底投影更贴近官方视频”的实现策略;后续如果拿到更强的二进制级证据,再继续下沉这层解释。
-- 2026-04-19:raw binary lift 的 `20` candidate pool 保留在 `StandaloneCursor` 这条分析线;`StandaloneCursorLab` 和主 runtime overlay 则统一切到 heading-driven 主线,实现上优先保证“朝向约束 + 单侧转弯”这个更贴近官方视频的结构行为。
+- 2026-04-19:raw binary lift 的 `20` candidate pool 保留在 `StandaloneCursor` 这条分析线;`CursorMotion` 和主 runtime overlay 则统一切到 heading-driven 主线,实现上优先保证“朝向约束 + 单侧转弯”这个更贴近官方视频的结构行为。
- 2026-04-20:恢复 slider UI 时,继续把“调参入口”和“binary-confirmed 结构”分开表述;lab 可以暴露 `start/end handle`、`arc size/flow`、`spring` 这些测试旋钮,但文档和代码都不把它们说成官方一一字段对照。
- 2026-04-20:对 `start/end handle` 这两个旋钮,当前实验线采用“作用在局部 start/end control 几何,而不是全局统一缩放”的策略;这更接近 binary lift 里 `startControl/endControl` 与 `startExtent/endExtent` 的边界。
- 2026-04-20:对 `ARC SIZE`,当前实验线采用“作用在局部 arc height / normal bias / family chooser,而不是 cursor glyph 尺寸”的策略;这更接近 binary lift 里 `handleExtent / arcExtent / tableA / tableB` 对曲线宽度的作用边界。
- 2026-04-20:对 `ARC FLOW`,当前实验线采用“作用在单段 cubic 控制点的前后相位,而不是单纯抽象 reach bias”的策略;这更接近 reverse-engineering 里“最宽弧段被沿 guide 方向推前/推后”的边界。
- 2026-04-20:对 `SPRING`,当前实验线采用“围绕官方 `.official` 的 centered response/damping remap,而不是再叠加额外 distance-based duration 层”的策略;这更接近当前 binary-backed 证据里“主链直接吃 `1.4 / 0.9` spring config”的边界。
- 2026-04-20:调左上角 slider 时,path 重建现在统一基于当前会话里最近一次 move 的 reference origin / startRotation / `queuedTarget`,而不是外层 `@State start/end` 或 settled 后的 live endpoint;这样参数调节既不会把曲线起点误拉回初始位置,也不会把 DEBUG 反馈线消成零长度。
+- 2026-04-20:对 `Cursor Motion` 的对外交付,当前采用“源码运行 + GitHub Releases 分发 ad-hoc signed DMG”的策略;先把 tag 驱动的可复现封装链路稳定下来,不在这一轮提前引入 notarization 和 Developer ID 签名复杂度。
diff --git a/docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md b/docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md
index e8e3d34..2d1ef56 100644
--- a/docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md
+++ b/docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md
@@ -2,7 +2,7 @@
## 目标
-继续逆向官方 `Codex Computer Use.app` 的 cursor motion 实现,在不触碰现有 `StandaloneCursorLab` 的前提下,于 `scripts/` 下落一套独立的二进制分析与 demo 脚本,能够基于指定起终点输出候选路径、采样点和几何测量结果。
+继续逆向官方 `Codex Computer Use.app` 的 cursor motion 实现,在不触碰现有 `CursorMotion` 的前提下,于 `scripts/` 下落一套独立的二进制分析与 demo 脚本,能够基于指定起终点输出候选路径、采样点和几何测量结果。
## 范围
@@ -12,7 +12,7 @@
- 实现一版 binary-guided 的 path sampling / measurement / candidate generation demo,输出 JSON 坐标样本与测量数据。
- 把新的函数级分析和脚本使用方式沉淀到 `docs/` 与 history。
- 不包含:
- - 不修改 `experiments/StandaloneCursorLab/`。
+ - 不修改 `experiments/CursorMotion/`。
- 不把这次脚本直接下沉到主 MCP runtime。
- 不宣称已经 100% 还原闭源算法中所有 scoring / timing 细节。
@@ -26,7 +26,7 @@
- `scripts/`
- `~/.codex/plugins/cache/openai-bundled/computer-use/1.0.750/Codex Computer Use.app`
- 已知约束:
- - 当前仓库已有另一条 session 在持续修改 `experiments/StandaloneCursorLab`,本任务应避免与之冲突。
+ - 当前仓库已有另一条 session 在持续修改 `experiments/CursorMotion`,本任务应避免与之冲突。
- 官方 bundle 为闭源二进制,当前主要依赖 `otool`、`llvm-objdump`、Swift metadata 和常量表恢复。
- 这次 demo 优先做成纯脚本 / JSON 输出,不依赖 GUI。
@@ -67,7 +67,7 @@
## 决策记录
-- 2026-04-19:这条线不继续改 `StandaloneCursorLab`,而是单独在 `scripts/` 下做纯脚本 demo,避免与另一条 session 冲突。
+- 2026-04-19:这条线不继续改 `CursorMotion`,而是单独在 `scripts/` 下做纯脚本 demo,避免与另一条 session 冲突。
- 2026-04-19:优先实现已从二进制函数级确认的 path sampling 和 measurement,再在此基础上做 candidate generation reconstruction,而不是反过来直接猜整套参数模型。
- 2026-04-19:`0x100060da0` 已确认 score 公式为 `320 * excessLengthRatio + 140 * angleEnergy + 180 * maxAngle + 18 * totalTurn + 45 * outOfBounds`,并确认“优先选 in-bounds 再取最小 score”的策略;duration 仍保留为未完全恢复。
- 2026-04-19:`0x10005fd98` 已进一步 lift 到字段级,当前脚本能按 bundled binary 生成完整 `20` 条候选,包含两条 base candidate、两段 cubic 的 arched candidate、真实 `CursorMotionPath/Segment` 布局,以及 guide vector `(-0.6946583704589973, 0.7193398003386512)`;runtime bounds 发现与 timing 仍单独保留为未完全恢复。
diff --git a/docs/exec-plans/active/20260420-cursor-slider-binary-investigation.md b/docs/exec-plans/active/20260420-cursor-slider-binary-investigation.md
index 75ac630..94918eb 100644
--- a/docs/exec-plans/active/20260420-cursor-slider-binary-investigation.md
+++ b/docs/exec-plans/active/20260420-cursor-slider-binary-investigation.md
@@ -23,7 +23,7 @@
- `docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md`
- 相关代码路径:
- `scripts/cursor-motion-re/`
- - `experiments/StandaloneCursorLab/`
+ - `experiments/CursorMotion/`
- 已知约束:
- 当前本机可用的官方 binary 为 `~/.codex/plugins/cache/openai-bundled/computer-use/1.0.750/Codex Computer Use.app/Contents/MacOS/SkyComputerUseService`。
- 用户看到的 slider 来自视频 / 调试构建,不代表 shipping bundle 一定保留相同 UI 文案。
diff --git a/docs/exec-plans/completed/20260419-overlay-official-cursor-motion-alignment.md b/docs/exec-plans/completed/20260419-overlay-official-cursor-motion-alignment.md
index 7c4e60f..b2d7e2d 100644
--- a/docs/exec-plans/completed/20260419-overlay-official-cursor-motion-alignment.md
+++ b/docs/exec-plans/completed/20260419-overlay-official-cursor-motion-alignment.md
@@ -16,7 +16,7 @@
- 保留当前仓库已有的 target-window 命中优先策略,但把它降为官方候选集合上的 tie-break,而不是继续使用旧的 7 条固定候选。
- 补单元测试、history 和架构文档。
- 不包含:
- - 不修改 `experiments/StandaloneCursorLab/`。
+ - 不修改 `experiments/CursorMotion/`。
- 不把这次变更扩展到 pulse / fog / idle sway 的完整官方 choreography。
- 不宣称已经恢复官方 `finished` gate 的全部字段语义命名。
diff --git a/docs/exec-plans/completed/20260419-standalone-cursor-from-python-reconstruction.md b/docs/exec-plans/completed/20260419-standalone-cursor-from-python-reconstruction.md
index 94de81e..f58365a 100644
--- a/docs/exec-plans/completed/20260419-standalone-cursor-from-python-reconstruction.md
+++ b/docs/exec-plans/completed/20260419-standalone-cursor-from-python-reconstruction.md
@@ -2,7 +2,7 @@
## 目标
-新增一条不依赖现有 `StandaloneCursorLab` 的独立 Swift demo 线路,把 `scripts/cursor-motion-re/official_cursor_motion.py` 已经收敛出来的候选路径、score、selection policy 和 raw spring timeline 直接搬进一个可运行的 `swift run StandaloneCursor` app。
+新增一条不依赖现有 `CursorMotion` 的独立 Swift demo 线路,把 `scripts/cursor-motion-re/official_cursor_motion.py` 已经收敛出来的候选路径、score、selection policy 和 raw spring timeline 直接搬进一个可运行的 `swift run StandaloneCursor` app。
## 范围
@@ -12,7 +12,7 @@
- 新增最小可交互 app UI,用于拖动起终点、选 candidate、重放路径。
- 补充 README、架构文档和 history。
- 不包含:
- - 不修改现有 `StandaloneCursorLab` 的代码和 UI 逻辑。
+ - 不修改现有 `CursorMotion` 的代码和 UI 逻辑。
- 不把这条 demo 直接接回主 `SoftwareCursorOverlay`。
- 不宣称已经恢复官方 wall-clock duration 映射。
@@ -27,7 +27,7 @@
- `experiments/StandaloneCursor/`
- `Package.swift`
- 已知约束:
- - 当前 worktree 里 `StandaloneCursorLab` 相关文件已经处于脏状态,应避免继续踩那条线。
+ - 当前 worktree 里 `CursorMotion` 相关文件已经处于脏状态,应避免继续踩那条线。
- 这次目标是“更贴 Python 脚本的独立 viewer”,不是再堆一版可调参数实验室。
## 风险
@@ -35,7 +35,7 @@
- 风险:把 Python 脚本里“已确认的核心”和“仍未恢复的 duration 映射”混在一起。
- 缓解方式:UI 和文档里显式写明只复用 raw spring timeline,不假装已经恢复 wall-clock duration。
-- 风险:与当前 `StandaloneCursorLab` 的本地改动发生冲突。
+- 风险:与当前 `CursorMotion` 的本地改动发生冲突。
- 缓解方式:新建完全独立的 target、源码目录和测试目录。
## 里程碑
@@ -55,7 +55,7 @@
- 点击右侧 candidate,确认能切到手动锁定并重放。
- 观测检查:
- UI 中能看到 endpoint lock / close-enough 时间以及 raw progress。
- - 文档明确区分 `StandaloneCursor` 与 `StandaloneCursorLab` 的职责。
+ - 文档明确区分 `StandaloneCursor` 与 `CursorMotion` 的职责。
## 进度记录
@@ -65,6 +65,6 @@
## 决策记录
-- 2026-04-19:不继续改当前 `StandaloneCursorLab`,改为新增 `StandaloneCursor` target,避免与现有脏 worktree 冲突。
+- 2026-04-19:不继续改当前 `CursorMotion`,改为新增 `StandaloneCursor` target,避免与现有脏 worktree 冲突。
- 2026-04-19:support model 直接按 Python 脚本命名和结构翻译,优先保证候选路径、评分和 timeline 的可对照性。
- 2026-04-19:新 app 刻意不做 speculative 的视觉 pose dynamics,只展示 binary-guided path pool 与 raw spring playback。
diff --git a/docs/exec-plans/completed/20260419-visual-cursor-pose-dynamics-refactor.md b/docs/exec-plans/completed/20260419-visual-cursor-pose-dynamics-refactor.md
index 7ad1665..2189014 100644
--- a/docs/exec-plans/completed/20260419-visual-cursor-pose-dynamics-refactor.md
+++ b/docs/exec-plans/completed/20260419-visual-cursor-pose-dynamics-refactor.md
@@ -12,7 +12,7 @@
- 调整 `SoftwareCursorView` 的渲染输入,增加 velocity-driven 的姿态与 fog/offset 表现。
- 补单元测试、架构文档和 history。
- 不包含:
- - 不修改 `experiments/StandaloneCursorLab/`。
+ - 不修改 `experiments/CursorMotion/`。
- 不宣称已经精确恢复官方 `FogCursorViewModel` 的全部字段公式。
- 不把这次改动扩展到完整 host choreography 或加载态 token。
@@ -26,7 +26,7 @@
- `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/CursorMotionModel.swift`
- `packages/OpenComputerUseKit/Sources/OpenComputerUseKit/SoftwareCursorOverlay.swift`
- 已知约束:
- - 另一条 session 仍在推进 `StandaloneCursorLab`,这次不能去碰实验 target。
+ - 另一条 session 仍在推进 `CursorMotion`,这次不能去碰实验 target。
- `CursorMotionPath.sample(progress)` 的 endpoint clamp 已经 binary-confirmed。
- `Style.velocityX / velocityY / angle`、`currentInterpolatedOrigin`、`FogCursorViewModel._velocityX / _velocityY / _angle`、`CursorView._animatedAngleOffsetDegrees` 这些状态存在,但还没有完整公式级 lift。
diff --git a/docs/histories/2026-04/20260418-1430-standalone-cursor-lab.md b/docs/histories/2026-04/20260418-1430-standalone-cursor-lab.md
index bb962ca..3a4bc8a 100644
--- a/docs/histories/2026-04/20260418-1430-standalone-cursor-lab.md
+++ b/docs/histories/2026-04/20260418-1430-standalone-cursor-lab.md
@@ -9,10 +9,10 @@
> 结合官方视频和已分析到的 cursor overlay 线索,在当前仓库里单独开一个目录,实现一版可独立开源的软件鼠标曲线,并继续推进分析与落地。
### 🛠 Changes Overview
-**Scope:** `Package.swift`、`experiments/StandaloneCursorLab/`、`docs/`、`README`
+**Scope:** `Package.swift`、`experiments/CursorMotion/`、`docs/`、`README`
**Key Actions:**
-- **[新增独立 target]**: 把 `StandaloneCursorLab` 加入 Swift Package,可通过 `swift run StandaloneCursorLab` 单独运行。
+- **[新增独立 target]**: 把 `CursorMotion` 加入 Swift Package,可通过 `swift run CursorMotion` 单独运行。
- **[实现 motion demo]**: 新增参数化 cursor motion model、Bezier 路径生成、spring/timing 模拟和 SwiftUI 调参界面。
- **[补齐点击交互]**: 支持点击画布任意位置生成多条候选路径,并选中一路径驱动 cursor 动画。
- **[收敛候选曲线与显示逻辑]**: 扩展为多组 descriptor 驱动的轨迹族,并让主路径在关闭 `DEBUG` 时继续可见。
@@ -30,7 +30,7 @@
- **[加强末段刹车 timing]**: 把 weighted effort lookup 从单一 edge profile 拆成 start/end 两段;前段更重掉头 effort,后段更重 braking effort,并略微拉长高加权路径的总时长,让最后一小段减速和收束更明显。
- **[重构为官方双层模型]**: 把 standalone lab 从旧的“路径 sample + 末端 rotation settle”实现,切到 recovered 的 `20` 条官方候选路径、官方风格 spring progress,以及和主运行时一致的独立 visual dynamics。
- **[移除 speculative 调参主线]**: lab 控制面板不再把 `START HANDLE` / `ARC FLOW` / `SPRING` 这类未完全确认语义的 slider 当成主入口,而是直接展示选中的 candidate id、score 和测量值。
-- **[实机跑独立 app 验证]**: 实际启动 `swift run StandaloneCursorLab` 对应的 app,确认 `REPLAY` 与画布点击都会切换候选路径,并看到末段不是原地翻角,而是路径层先形成回接弧线,再由 visual dynamics 做姿态滞后和 idle sway。
+- **[实机跑独立 app 验证]**: 实际启动 `swift run CursorMotion` 对应的 app,确认 `REPLAY` 与画布点击都会切换候选路径,并看到末段不是原地翻角,而是路径层先形成回接弧线,再由 visual dynamics 做姿态滞后和 idle sway。
- **[同步仓库知识]**: 补 motion model 逆向分析文档、active execution plan、架构说明、README 入口和 history。
### 🧠 Design Intent (Why)
@@ -44,13 +44,13 @@
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
- `docs/references/codex-computer-use-reverse-engineering/README.md`
- `docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md`
-- `experiments/StandaloneCursorLab/README.md`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/StandaloneCursorLabApp.swift`
+- `experiments/CursorMotion/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionApp.swift`
### 🔁 Follow-up (2026-04-19)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[同步主运行时的 recovered motion model]**: standalone lab 现在直接使用 recovered 的 base/arched candidate 生成策略、`VelocityVerlet` progress spring 和独立 visual dynamics。
@@ -64,7 +64,7 @@
- **[补方向约束回归测试]**: 新增测试,显式验证“朝向已对齐时优先近直线”和“起步朝向反向时优先掉头大弧”两类行为,避免后续再次回到怪异扭曲曲线。
### 🔁 Follow-up (2026-04-20, synthesized overlay style)
-**Scope:** `experiments/StandaloneCursorLab/`、`Package.swift`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`Package.swift`、`docs/`
**Key Actions:**
- **[改回脚本同款视觉]**: 对照用户给出的 `render-synthesized-software-cursor.swift` 参考图后,确认 lab 当前复用的亮白 asset 风格不对;改为优先显示仓库中的官方 `252x252` runtime baseline 图,并在缺失时退回脚本同款 procedural pointer/fog。
@@ -73,16 +73,16 @@
### 📁 Additional Files Modified
- `Package.swift`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorGlyphCalibration.swift`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/SynthesizedCursorGlyphView.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorGlyphCalibration.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/SynthesizedCursorGlyphView.swift`
+- `experiments/CursorMotion/README.md`
- `docs/ARCHITECTURE.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, decouple visible arrow angle)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[分离内部 heading 与可见角度]**: 保留 motion model 内部 `rotation` 给下一段选路参考,但新增单独的 `displayRotation` 给 glyph 渲染,避免箭头在移动时像车头一样持续指向轨迹方向。
@@ -90,81 +90,81 @@
- **[同步文档说法]**: README、架构说明和 active plan 不再把 lab 当前表现描述成“箭头主朝向明显跟随运动方向”。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/README.md`
- `docs/ARCHITECTURE.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
-- **[移除起始点残留白点]**: `StandaloneCursorLab` 画布不再常驻渲染起始点白色 marker,避免 cursor 沿曲线移动后仍在起点留下误导性的白点。
+- **[移除起始点残留白点]**: `CursorMotion` 画布不再常驻渲染起始点白色 marker,避免 cursor 沿曲线移动后仍在起点留下误导性的白点。
- **[收紧 DEBUG 关闭态]**: `DEBUG` 关闭后不再保留选中主轨迹或目标点 marker,整层调试 overlay 会一起隐藏,避免非调试模式下仍残留轨迹线和圆点。
- **[主视觉改为中性灰紫]**: 把 lab 的背景渐变、调试高亮和控件 accent 从原先偏粉色的方案切到接近 `#E3E2E6` 的中性灰紫配色,避免画面继续带明显粉色倾向。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/README.md`
### 🔁 Follow-up (2026-04-20, align glyph baseline heading with official cursor artwork)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[回收多余的局部旋转补偿]**: 对照独立 `render-synthesized-software-cursor.swift` 脚本和官方 `252x252` runtime baseline 图后,确认 lab 里额外的 `restingRotation = -26.5°` 会把 moving 期间的可见 heading 固定偏开。
- **[静止朝向改为左上基线]**: `CursorGlyphCalibration` 现在直接把零旋转基线定义成官方箭头的天然静止朝向;在 lab 的 y-down 坐标里用 `neutralHeading = -3π/4`,`restingRotation = 0`,让 path heading 和 glyph 朝向共用同一套基准。
-- **[对齐主运行时语义]**: 这次调整也把 `StandaloneCursorLab` 的 heading 标定方式收回到和 `SoftwareCursorOverlay` 一致的思路,不再额外维护一层实验性局部偏角。
+- **[对齐主运行时语义]**: 这次调整也把 `CursorMotion` 的 heading 标定方式收回到和 `SoftwareCursorOverlay` 一致的思路,不再额外维护一层实验性局部偏角。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorGlyphCalibration.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorGlyphCalibration.swift`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, fix y-axis mismatch in glyph rendering)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
-- **[定位到渲染坐标系不一致]**: 继续对照用户反馈的“屁股超前”现象后,确认 `StandaloneCursorLab` 的 path / heading 在 SwiftUI y-down 坐标里推进,但 `SynthesizedCursorGlyphView` 实际使用的是 AppKit 默认 y-up 绘制坐标。
+- **[定位到渲染坐标系不一致]**: 继续对照用户反馈的“屁股超前”现象后,确认 `CursorMotion` 的 path / heading 在 SwiftUI y-down 坐标里推进,但 `SynthesizedCursorGlyphView` 实际使用的是 AppKit 默认 y-up 绘制坐标。
- **[统一翻转 angle 与 offset]**: 在 glyph 渲染层新增显式转换,把 screen-space 的 `rotation`、`cursorBodyOffset`、`fogOffset` 统一映射到 AppKit drawing space,避免 moving 期间可见姿态被垂直镜像。
- **[保持 motion model 不动]**: 这次没有继续改候选路径或 spring,只修复显示层坐标映射,让 heading-driven 选路和 visual dynamics 仍维持原来的 y-down 几何语义。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/SynthesizedCursorGlyphView.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/SynthesizedCursorGlyphView.swift`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, restore visible heading during moves)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[按官方抽帧撤回轻微 lean 假设]**: 对照用户提供的官方 1-9 帧后,确认 moving 阶段箭头主朝向会持续跟随当前 move heading,而不是只保留一个很小的 turn lean。
-- **[移除多余的 displayRotation 分层]**: `StandaloneCursorLab` 的 glyph 渲染重新直接使用 visual dynamics 主 `rotation`;之前额外加的 `displayRotation / visibleRotationOffset` 已移除,避免把主 heading 丢掉。
+- **[移除多余的 displayRotation 分层]**: `CursorMotion` 的 glyph 渲染重新直接使用 visual dynamics 主 `rotation`;之前额外加的 `displayRotation / visibleRotationOffset` 已移除,避免把主 heading 丢掉。
- **[保留小幅 idle wobble]**: idle 阶段仍沿用 `_animatedAngleOffsetDegrees` 对应的小摆角近似,但这层 offset 重新回到主 heading 之上,而不是替代 moving 期间的可见朝向。
- **[同步当前文档口径]**: README、架构说明和 active execution plan 统一改回“moving 阶段箭头跟随 heading,停住后再回 resting pose”的表述。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/README.md`
- `docs/ARCHITECTURE.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, restore slider tuning surface)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
-- **[恢复左上角 slider 面板]**: 把用户指出被删掉的 `START HANDLE`、`END HANDLE`、`ARC SIZE`、`ARC FLOW`、`SPRING` 五个滑块重新加回 `StandaloneCursorLab` 左上角,并保留 `REPLAY` / candidate metrics 作为辅助观察面板。
+- **[恢复左上角 slider 面板]**: 把用户指出被删掉的 `START HANDLE`、`END HANDLE`、`ARC SIZE`、`ARC FLOW`、`SPRING` 五个滑块重新加回 `CursorMotion` 左上角,并保留 `REPLAY` / candidate metrics 作为辅助观察面板。
- **[重新接回参数语义]**: `CursorMotionParameters` 不再只是空壳默认值;现在这些 slider 会直接驱动 heading-driven path builder 的 start/end handle、arc size/flow,以及 progress spring 配置和 travel duration。
- **[补自定义滑块样式]**: 用更接近用户截图的细轨道 + 白色圆形 thumb 实现本地调参控件,避免直接退回系统默认控件风格。
-- **[同步文档边界]**: `StandaloneCursorLab` README 和 active execution plan 都改成显式说明“slider 是本地调参入口,不等于已 binary-confirmed 的官方字段映射”。
+- **[同步文档边界]**: `CursorMotion` README 和 active execution plan 都改成显式说明“slider 是本地调参入口,不等于已 binary-confirmed 的官方字段映射”。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/README.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, apply arc-size semantics from slider investigation)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[明确 ARC SIZE 不是 cursor 大小]**: `ARC SIZE` 这次明确收口为“轨迹弧度”旋钮,不再给出任何会让人误解成 cursor glyph 尺寸的语义空间。
@@ -173,12 +173,12 @@
- **[补默认样例采样]**: 用 lab 默认点位验证后,`arcSize=0.04` 时选中 `brake-primary-tight`、`curveScale≈10.3`、中段 `y≈326.8`;调到 `0.12` 后仍在主 family 内,但 `curveScale≈47.7`、中段 `y≈345.5`,能直接看出弧度抬高。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift`
+- `experiments/CursorMotion/README.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, remove mid-curve point feel introduced by arc-flow)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[定位到不是 SPRING 问题]**: 重新检查后确认 `SPRING` 只影响 progress timing,不参与路径几何;用户看到的“中间多了一个点”来自 `ARC FLOW` 首轮实现。
@@ -187,12 +187,12 @@
- **[保留 ARC FLOW 的作用边界]**: 修完后 `ARC FLOW` 仍然会影响路径前后相位,但不再靠一条显式 join 来表达。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, apply spring semantics from slider investigation)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[把 SPRING 收回官方中心档]**: `SPRING` slider 不再走之前那套“拖高以后反而更快收口”的映射;现在改成围绕官方 `response=1.4 / damping=0.9` 的 centered remap,并在 `spring=0.5` 时精确返回 `.official`。
@@ -201,12 +201,12 @@
- **[补默认档验证]**: 额外验证了 `spring=0.5` 时 `progressSpringConfiguration == .official`,因此默认档会继续命中 `343/240` 的官方 endpoint-lock 快路,而不是只算出一个近似值。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift`
+- `experiments/CursorMotion/README.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, apply arc-flow semantics from slider investigation)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[明确 ARC FLOW 不是改弧度大小]**: `ARC FLOW` 这次明确收口为“最宽弧段沿主轴的前后相位位置”,不再和 `ARC SIZE` 混成同一个“弯曲程度”旋钮。
@@ -215,26 +215,26 @@
- **[随后收回成单段 cubic]**: 用户确认显式中间锚点会让曲线读起来像“中间多了一个点”后,`ARC FLOW` 已收回到单段 cubic 的前后相位偏置;当前继续保留相位控制,但不再通过可见 join 来实现。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift`
+- `experiments/CursorMotion/README.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, align default move speed with official endpoint-lock timing)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
-- **[移除距离驱动时长压缩]**: `StandaloneCursorLab` 的默认 move 不再用本地经验公式根据路径长度压缩 wall-clock 时长,避免中长距离移动明显快于官方。
+- **[移除距离驱动时长压缩]**: `CursorMotion` 的默认 move 不再用本地经验公式根据路径长度压缩 wall-clock 时长,避免中长距离移动明显快于官方。
- **[默认档对齐官方 1.429s timeline]**: 基于最新逆向确认的 `343 / 240 = 1.4291667s` endpoint-lock 时间,把默认 `response=1.4 / damping=0.9` 档位直接对齐到官方 spring timeline。
- **[保留 spring slider 但收紧语义]**: `SPRING` slider 继续只改变 progress spring 的 response / damping 与对应 settle 时间,不再叠加独立的 distance-based duration fudge factor。
- **[同步文档口径]**: README 和 active plan 现在都明确写出默认档的官方 endpoint-lock 时长,避免继续把 move 速度表述成不稳定的本地校准结果。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift`
+- `experiments/CursorMotion/README.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, simplify slider panel styling)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[移除左上角多余文案]**: 把 slider 面板里的 `REPLAY`、`RESET`、heading-driven 标题和 candidate metrics 全部移除,只保留 5 个调参 slider。
@@ -242,12 +242,12 @@
- **[同步说明文档]**: README 和 active plan 不再把左上角 panel 描述成带 `REPLAY` 的观察面板,而是明确为纯 slider 调参入口。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/README.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, preserve cursor state on resize)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[修正 resize 回跳]**: 窗口尺寸变化时不再重新调用 `configure(...)+snap(to: start)`;现在只更新 canvas bounds,避免 cursor 因为 resize 被强制拉回起始点。
@@ -255,11 +255,11 @@
- **[同步记录]**: active plan 补充这次 resize bugfix,明确“调窗口大小不应改变当前 cursor 位置”已经收口。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, preserve live path origin while tuning sliders)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[修正 slider 调参回跳]**: `motionParameters` 变化时不再把外层 `@State start/end` 重新喂回 `updateParameters`;当前会话的调试曲线现在改由最近一次真实 move 的 reference origin 和 `queuedTarget` 重建,避免曲线起点偶发回到初始点。
@@ -267,11 +267,11 @@
- **[同步记录]**: active plan 补充这次 bugfix,明确“参数调节不应改写当前会话位置”已经和此前的 resize 修复收口到同一原则。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, keep debug path visible while tuning sliders)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[修正 DEBUG 线消失]**: 上一轮把 slider 调参直接绑到 `currentState.point -> queuedTarget` 后,在 settled 态会退化成 `target -> target` 的零长度 path;现在把“cursor 当前点位”和“reference path”分离,DEBUG 模式下调参仍会显示完整曲线反馈。
@@ -279,12 +279,12 @@
- **[同步文档口径]**: active plan 和 README 都补充这次调整,明确 slider 的可视反馈来自当前 session path,而不是简单拿 live endpoint 直接重建。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/README.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, simplify top-right debug controls)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[移除多余 toggle]**: 右上角只保留 `DEBUG` switch,`MAIL` / `CLICK` 的本地测试开关已移除,避免和左上角参数面板一起制造额外噪音。
@@ -292,12 +292,12 @@
- **[拉开开关视觉差]**: `DEBUG` switch 的开启态改成左侧 slider 同款 accent 渐变,关闭态收成浅灰底和深色 knob,避免两档底色太接近看不出切换状态。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/README.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, reduce background gradient bleed through panel cards)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[收紧 card 底色]**: `CursorPanelBackground` 不再使用偏透明的浅灰渐变,而是收成更实的灰白卡片底,减少底层 BG 渐变直接把 panel 染成不同色相。
@@ -305,12 +305,12 @@
- **[同步文档口径]**: README 和 active plan 现在都明确写成“更实的灰白卡片”,避免继续把 panel 理解成半透明浮层。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/README.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, align top-left and top-right panel shells)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[统一 panel 外壳]**: 左上 slider 面板和右上 `DEBUG` 面板现在都改成复用同一个 `CursorPanelShell`,统一内边距、圆角、描边和阴影,避免继续靠两套近似但不完全一致的容器样式拼出来。
@@ -318,21 +318,65 @@
- **[同步文档口径]**: README 和 active plan 补充这次 panel shell 对齐,明确左右控件区现在属于同一套视觉组件。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/README.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
### 🔁 Follow-up (2026-04-20, apply start/end handle semantics from slider investigation)
-**Scope:** `experiments/StandaloneCursorLab/`、`docs/`
+**Scope:** `experiments/CursorMotion/`、`docs/`
**Key Actions:**
- **[收紧 START HANDLE 语义]**: `START HANDLE` 不再只是参与全局 curve reach 的对称缩放;现在优先改变起步段的 guide line/heading mix、start reach 和 start-side normal 偏置,让前段轨迹能更明确地体现“先甩出去多远、多久才回咬主轴”。
- **[收紧 END HANDLE 语义]**: `END HANDLE` 也改为只优先作用在 end guide / end reach / end-side normal 上,使末段收束钩子的长度和贴回目标的时机能单独变化,而不是跟起步段一起等比例变化。
- **[放宽默认样例的 bounds clipping]**: lab 选路不再使用过紧的 corridor bounds,而是改用画布内缩后的实际 canvas bounds;这样默认样例下 `END HANDLE` 不会因为提前 clipping 而看起来“几乎没反应”。
-- **[补验证采样]**: 除了 `swift build --product StandaloneCursorLab` 之外,还用默认点位做了小脚本采样,确认 `START HANDLE` 和 `END HANDLE` 在接近默认档的小范围调节下也会改变 early/late path sample 与 control geometry。
+- **[补验证采样]**: 除了 `swift build --product CursorMotion` 之外,还用默认点位做了小脚本采样,确认 `START HANDLE` 和 `END HANDLE` 在接近默认档的小范围调节下也会改变 early/late path sample 与 control geometry。
### 📁 Additional Files Modified
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift`
-- `experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift`
-- `experiments/StandaloneCursorLab/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift`
+- `experiments/CursorMotion/README.md`
- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
+
+### 🔁 Follow-up (2026-04-20, rename standalone lab to Cursor Motion)
+**Scope:** `Package.swift`、`README*`、`experiments/CursorMotion/`、`docs/`
+
+**Key Actions:**
+- **[统一独立 demo 命名]**: 把原来的 `StandaloneCursorLab` 全量收口到 `CursorMotion`;Swift Package product、实验目录、入口 app 名称和运行命令统一改成 `swift run CursorMotion`。
+- **[同步中英文 README 入口]**: 仓库根 README 的 `Cursor Motion` 段落现在统一描述为“一个面向 macOS 的开源光标运动系统”,并明确支持源码运行和从 Releases 页面下载 app。
+- **[同步仓库知识]**: 架构说明、实验 README、active/completed plan、references 与 history 中残留的旧名称都同步替换,避免文档继续混用旧名。
+
+### 📁 Additional Files Modified
+- `Package.swift`
+- `README.md`
+- `README.zh-CN.md`
+- `docs/ARCHITECTURE.md`
+- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
+- `docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md`
+- `docs/exec-plans/active/20260420-cursor-slider-binary-investigation.md`
+- `docs/exec-plans/completed/20260419-overlay-official-cursor-motion-alignment.md`
+- `docs/exec-plans/completed/20260419-standalone-cursor-from-python-reconstruction.md`
+- `docs/exec-plans/completed/20260419-visual-cursor-pose-dynamics-refactor.md`
+- `docs/histories/2026-04/20260419-1333-add-binary-guided-cursor-motion-re-demo.md`
+- `docs/histories/2026-04/20260419-2300-add-standalone-cursor-from-python-reconstruction.md`
+- `docs/histories/2026-04/20260420-1151-investigate-cursor-slider-binary-mapping.md`
+- `docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md`
+- `docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-reconstruction.md`
+- `experiments/CursorMotion/README.md`
+- `experiments/CursorMotion/Sources/CursorMotion/CursorMotionApp.swift`
+- `scripts/cursor-motion-re/README.md`
+
+### 🔁 Follow-up (2026-04-20, add tag-driven Cursor Motion DMG release)
+**Scope:** `.github/workflows/release.yml`、`scripts/`、`docs/`
+
+**Key Actions:**
+- **[补本地 DMG 构建脚本]**: 新增 `scripts/build-cursor-motion-dmg.sh`,支持 `native` / `arm64` / `x86_64` / `universal`,会构建 `Cursor Motion.app` 并封装 `CursorMotion-<version>.dmg`。
+- **[补 GitHub Releases 上传]**: `release.yml` 在 push release tag 时新增 `release-cursor-motion-dmg` job,构建 `CursorMotion` 的 universal DMG,并用 `gh release create/upload` 自动发布到对应 tag 的 GitHub Releases 页面。
+- **[同步 release 文档]**: `docs/CICD.md` 和 `docs/releases/RELEASE_GUIDE.md` 已补充这条分发链路、版本来源以及当前只做 ad-hoc codesign 的边界。
+- **[补本地验证]**: 已本地验证 `./scripts/build-cursor-motion-dmg.sh --configuration release --arch native --version 0.0.0-local` 和 `--arch universal --version 0.0.0-local-universal` 都能成功产出 `.dmg`。
+
+### 📁 Additional Files Modified
+- `.github/workflows/release.yml`
+- `docs/CICD.md`
+- `docs/exec-plans/active/20260418-standalone-cursor-lab.md`
+- `docs/releases/RELEASE_GUIDE.md`
+- `scripts/build-cursor-motion-dmg.sh`
diff --git a/docs/histories/2026-04/20260419-1333-add-binary-guided-cursor-motion-re-demo.md b/docs/histories/2026-04/20260419-1333-add-binary-guided-cursor-motion-re-demo.md
index 7b4f71f..fb4ed21 100644
--- a/docs/histories/2026-04/20260419-1333-add-binary-guided-cursor-motion-re-demo.md
+++ b/docs/histories/2026-04/20260419-1333-add-binary-guided-cursor-motion-re-demo.md
@@ -6,13 +6,13 @@
* **Runtime**: `Codex CLI`
### 📥 User Query
-> 继续深挖官方 cursor motion,并在独立目录里做一个不和 `StandaloneCursorLab` 冲突的 demo,最好能指定起终点输出路线和速度相关采样。
+> 继续深挖官方 cursor motion,并在独立目录里做一个不和 `CursorMotion` 冲突的 demo,最好能指定起终点输出路线和速度相关采样。
### 🛠 Changes Overview
**Scope:** `scripts/cursor-motion-re/`、`docs/exec-plans/active/`、`docs/references/`、`docs/histories/`
**Key Actions:**
-- **[新增独立执行计划]**: 在 `docs/exec-plans/active/` 下为这条逆向 + 脚本化 demo 线路单独建 plan,并显式声明不触碰 `StandaloneCursorLab`。
+- **[新增独立执行计划]**: 在 `docs/exec-plans/active/` 下为这条逆向 + 脚本化 demo 线路单独建 plan,并显式声明不触碰 `CursorMotion`。
- **[实现脚本化逆向工具]**: 新增 `scripts/cursor-motion-re/`,用纯 Python 实现最小 Mach-O section 解析、Swift field metadata 恢复和官方 binary 中的常量 / 候选系数表提取。
- **[实现 binary-guided demo]**: 新增 CLI,支持 `inspect` 和 `demo` 两个子命令;`demo` 可对指定起终点生成候选路径、measurement 和采样点 JSON,并默认输出精简版 `candidate_summaries + chosen_candidate`。
- **[确认候选打分与选择]**: 把 `0x100060da0` 中的 score 公式和 “prefer in-bounds, then choose minimum score” 策略回填进脚本输出,不再沿用之前的猜测权重。
@@ -24,7 +24,7 @@
- **[同步目录导航]**: 更新 reverse-engineering README,把新的 reconstruction 文档纳入索引。
### 🧠 Design Intent (Why)
-当前已有另一条 session 在持续推进 `StandaloneCursorLab`,直接继续改实验 target 风险太高。这次改成 `scripts/` 下的独立脚本,一方面能继续深挖闭源实现,另一方面也能把“已确认”和“仍在 reconstruction”的部分明确分层,便于后续逐步替换。
+当前已有另一条 session 在持续推进 `CursorMotion`,直接继续改实验 target 风险太高。这次改成 `scripts/` 下的独立脚本,一方面能继续深挖闭源实现,另一方面也能把“已确认”和“仍在 reconstruction”的部分明确分层,便于后续逐步替换。
### 📁 Files Modified
- `docs/exec-plans/active/20260419-official-cursor-motion-reconstruction.md`
diff --git a/docs/histories/2026-04/20260419-2300-add-standalone-cursor-from-python-reconstruction.md b/docs/histories/2026-04/20260419-2300-add-standalone-cursor-from-python-reconstruction.md
index 26a3b92..6a2ec61 100644
--- a/docs/histories/2026-04/20260419-2300-add-standalone-cursor-from-python-reconstruction.md
+++ b/docs/histories/2026-04/20260419-2300-add-standalone-cursor-from-python-reconstruction.md
@@ -6,19 +6,19 @@
* **Runtime**: `Codex CLI`
### 📥 User Query
-> 现在有一个 `swift run StandaloneCursorLab` 的版本,但是感觉做得很不理想。基于单独的 `scripts/cursor-motion-re/reconstruct_cursor_motion.py` 去实现一个新的 `StandaloneCursor` 版本出来看看。
+> 现在有一个 `swift run CursorMotion` 的版本,但是感觉做得很不理想。基于单独的 `scripts/cursor-motion-re/reconstruct_cursor_motion.py` 去实现一个新的 `StandaloneCursor` 版本出来看看。
### 🛠 Changes Overview
**Scope:** `Package.swift`、`experiments/StandaloneCursor/`、`README*`、`docs/`
**Key Actions:**
-- **[新增独立 target]**: 在 `Package.swift` 里增加 `StandaloneCursor` executable target、`StandaloneCursorSupport` support module 和对应测试 target,避免继续改当前脏着的 `StandaloneCursorLab` 线路。
+- **[新增独立 target]**: 在 `Package.swift` 里增加 `StandaloneCursor` executable target、`StandaloneCursorSupport` support module 和对应测试 target,避免继续改当前脏着的 `CursorMotion` 线路。
- **[Swift 版重建模型]**: 在 `experiments/StandaloneCursor/Sources/StandaloneCursorSupport/StandaloneCursorModel.swift` 里按 Python 脚本重建 `20` 条 candidate、`measure + score`、selection policy,以及 `response=1.4` / `dampingFraction=0.9` / `dt=1/240` 的 raw spring timeline。
- **[新独立 viewer]**: 新增 `StandaloneCursor` app,支持拖动起终点、切换 candidate、重放路径,并把 endpoint lock / close-enough 时间直接展示在 UI 上。
- **[验证与文档]**: 新增 `StandaloneCursorSupportTests`,并补齐 `experiments/StandaloneCursor/README.md`、顶层 README、`docs/ARCHITECTURE.md` 和执行计划。
### 🧠 Design Intent (Why)
-现有 `StandaloneCursorLab` 更偏视觉和交互实验,不适合继续承载“基于 Python 脚本直接对照 binary lift”的诉求。这次把新 viewer 做成独立 target,一方面能保留旧 lab 的实验自由度,另一方面也能给后续对照脚本、继续往主运行时收敛时提供一个更干净的中间层。
+现有 `CursorMotion` 更偏视觉和交互实验,不适合继续承载“基于 Python 脚本直接对照 binary lift”的诉求。这次把新 viewer 做成独立 target,一方面能保留旧 lab 的实验自由度,另一方面也能给后续对照脚本、继续往主运行时收敛时提供一个更干净的中间层。
### 📁 Files Modified
- `Package.swift`
diff --git a/docs/histories/2026-04/20260420-1151-investigate-cursor-slider-binary-mapping.md b/docs/histories/2026-04/20260420-1151-investigate-cursor-slider-binary-mapping.md
index def68e1..2d3f973 100644
--- a/docs/histories/2026-04/20260420-1151-investigate-cursor-slider-binary-mapping.md
+++ b/docs/histories/2026-04/20260420-1151-investigate-cursor-slider-binary-mapping.md
@@ -16,7 +16,7 @@
- **[补 shipping bundle 证据边界]**: 明确记录当前 release bundle 未命中 `START HANDLE`、`END HANDLE`、`ARC SIZE`、`ARC FLOW` 这些完整 phrase;`SPRING` / `DEBUG` / `MAIL` / `CLICK` 仅作为歧义 token 命中,不再被误写成“debug UI 仍然随 release shipping”。
- **[沉淀 slider 映射文档]**: 新增 `software-cursor-slider-parameter-investigation.md`,把 `start/end handle`、`arc size/flow`、`spring` 各自对应的 binary-confirmed 几何 / timing 量,以及默认样例 / 居中样例下的实际曲线影响单独沉淀。
- **[同步旧文档口径]**: `software-cursor-motion-model.md` 不再只写“视频里有 slider UI”,而是补充说明当前 shipping bundle phrase scan 没有直接命中这组 label。
-- **[新增独立执行计划]**: 为这轮参数映射调查新增 active execution plan,避免继续挤在之前的 cursor reconstruction 或 StandaloneCursorLab UI 任务里。
+- **[新增独立执行计划]**: 为这轮参数映射调查新增 active execution plan,避免继续挤在之前的 cursor reconstruction 或 CursorMotion UI 任务里。
### 🧠 Design Intent (Why)
这轮的关键不是继续猜 5 个 slider 在 UI 上长什么样,而是把“release binary 里还能直接确认什么”和“我们如何基于这些量推断 slider 对曲线的影响”明确分层。这样后续继续挖 `ARC FLOW` 或 spring remap 时,就不会把 shipping 证据、视频证据和本地 lab 调参混成一团。
diff --git a/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md b/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md
index 2438768..49347cf 100644
--- a/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md
+++ b/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-model.md
@@ -386,7 +386,7 @@ CursorView
为了后续独立开源更干净,这块建议先作为单独目录推进,而不是直接和 MCP runtime 耦合:
-- 目录建议:`experiments/StandaloneCursorLab/`
+- 目录建议:`experiments/CursorMotion/`
- 第一阶段先做一个纯本地 demo app,不接真实 tool call。
- 等参数模型稳定后,再决定是否把其中的 `Motion Parameters` / `Path Builder` 下沉回 `packages/` 复用。
diff --git a/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-reconstruction.md b/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-reconstruction.md
index 92d39cb..1837e55 100644
--- a/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-reconstruction.md
+++ b/docs/references/codex-computer-use-reverse-engineering/software-cursor-motion-reconstruction.md
@@ -496,7 +496,7 @@ else:
## 脚本化落点
-这次为了避开 `StandaloneCursorLab`,在 `scripts/cursor-motion-re/` 下落了一套独立脚本:
+这次为了避开 `CursorMotion`,在 `scripts/cursor-motion-re/` 下落了一套独立脚本:
- `reconstruct_cursor_motion.py inspect`
- 读取官方 binary,输出已恢复的 motion 类型、字段、常量和候选系数表。
diff --git a/docs/releases/RELEASE_GUIDE.md b/docs/releases/RELEASE_GUIDE.md
index 9afa54f..520cf6e 100644
--- a/docs/releases/RELEASE_GUIDE.md
+++ b/docs/releases/RELEASE_GUIDE.md
@@ -14,6 +14,7 @@
## 当前 release 入口
- 本地 staging / 打 tgz:`./scripts/release-package.sh`
+- 本地构建 Cursor Motion DMG:`./scripts/build-cursor-motion-dmg.sh --configuration release --arch universal --version <version>`
- 本地 stage npm 包目录:`node ./scripts/npm/build-packages.mjs`
- 本地 publish:`node ./scripts/npm/publish-packages.mjs`
- CI workflow:`.github/workflows/release.yml`
@@ -21,13 +22,17 @@
## 当前版本源
-这个仓库的 npm staging 包版本,当前以 `plugins/open-computer-use/.codex-plugin/plugin.json` 里的 `version` 为准。
+这个仓库当前有两类 release 版本源:
+
+- npm staging 包版本:以 `plugins/open-computer-use/.codex-plugin/plugin.json` 里的 `version` 为准。
+- `CursorMotion-<version>.dmg` 文件名与 GitHub Release asset 版本:以 release tag 为准;workflow 会把 `vX.Y.Z` 规范化成 `X.Y.Z` 写进 DMG 文件名,也可以在本地显式传 `--version`。
也就是说:
- 只改 git tag,不改这个 manifest,不会得到新 npm 版本。
- `scripts/npm/build-packages.mjs` 会从这个 manifest 读取版本,再生成三个 staging 包。
- 所以 release 前必须先把这份 manifest bump 到目标版本。
+- 如果要让 `CursorMotion` 的 DMG 文件名和 release 页面资产名正确落到目标版本,也必须使用目标 tag 推送,或本地显式传入同样的 `--version`。
## Release Checklist
@@ -48,20 +53,22 @@
### 2. 本地验证版本源已经生效
-至少跑这两步:
+至少跑这三步:
```bash
swift test
node ./scripts/npm/build-packages.mjs --skip-build --out-dir dist/release/npm-staging-check
+./scripts/build-cursor-motion-dmg.sh --configuration release --arch universal --version 0.1.12
```
-然后直接检查 staging 包版本:
+然后直接检查 staging 包版本和 DMG 文件名:
```bash
node -p "require('./dist/release/npm-staging-check/open-codex-computer-use-mcp/package.json').version"
+ls dist/release/cursor-motion/CursorMotion-0.1.12.dmg
```
-如果这里打印的不是目标版本,不要打 tag。
+如果这里打印的不是目标版本,或者 DMG 没按目标版本名产出,不要打 tag。
### 3. 提交版本 bump
@@ -78,6 +85,11 @@ git push origin main
git push origin v0.1.12
```
+tag push 后,`.github/workflows/release.yml` 会自动做两件事:
+
+- 发布 npm 包。
+- 构建 `CursorMotion-0.1.12.dmg`,并创建或更新同名 tag 的 GitHub Release asset。
+
## Release 失败时怎么查
### 1. 先看最新 run
@@ -93,10 +105,17 @@ gh run view -R iFurySt/open-codex-computer-use <run-id> --log-failed
- 通常不是 token 权限问题,而是 staging 包版本仍然是旧版本。
- 先回头检查 `plugin.json` 的 `version`,再检查 staging 包实际产出的 `package.json`。
- 构建阶段失败
- - 优先看 `Build npm release artifacts` 或 Swift 编译错误。
+ - 优先看 `Build npm release artifacts`、`Build Cursor Motion DMG` 或 Swift 编译错误。
+- GitHub Release 资产上传失败
+ - 优先看 `Publish Cursor Motion DMG to GitHub Releases`,确认 tag 是否存在、`GH_TOKEN` 权限是否正常,以及生成的 `CursorMotion-<version>.dmg` 路径是否匹配。
- publish 认证失败
- 再去看 `.github/workflows/release.yml`、`scripts/npm/publish-packages.mjs` 和 npm trusted publishing / token fallback 配置。
+## 当前已知边界
+
+- `Cursor Motion` 当前 release 资产只做 ad-hoc codesign,不包含 Apple Developer ID 签名和 notarization。
+- 如果后续要把下载体验收口成更标准的 macOS 分发流程,还需要继续补 Developer ID signing、notarization 和对应 secret / keychain 流程。
+
## 如果 tag 已经打错了
如果远端 tag 已经指向错误 commit,先删 tag,再修版本源,再重打。
diff --git a/experiments/StandaloneCursorLab/README.md b/experiments/CursorMotion/README.md
similarity index 97%
rename from experiments/StandaloneCursorLab/README.md
rename to experiments/CursorMotion/README.md
index 03a089e..9cc311a 100644
--- a/experiments/StandaloneCursorLab/README.md
+++ b/experiments/CursorMotion/README.md
@@ -1,4 +1,4 @@
-# Standalone Cursor Lab
+# Cursor Motion
这个目录用于实现一个可独立演进、后续可单独开源的软件 cursor motion demo。
@@ -32,7 +32,7 @@
当前已经有一个可运行的 SwiftUI demo target:
```bash
-swift run StandaloneCursorLab
+swift run CursorMotion
```
现阶段支持:
@@ -67,5 +67,5 @@ swift run StandaloneCursorLab
- 当前 `ARC FLOW` 的实现边界是“单段 cubic 的前后相位偏置”;它更接近 reverse-engineering 里 `arcAnchorBias` 这类几何前后偏置,不宣称已经和 release binary 内部某个独立 `flow` 字段一一对应。
- 当前 `SPRING` 的实现边界是“围绕官方 `1.4 / 0.9` 的 centered spring remap”;它直接改变 progress spring 的 `response / damping` 与 endpoint-lock 时间,但不宣称已经恢复出 release app 内部 debug slider 的精确 remap helper。
- 路径层、progress 层和 visible pose 层继续保持分离。
-- 没有真实 target window 的场景里,要明确区分 `StandaloneCursor` 的 raw reverse-engineered pool 和 `StandaloneCursorLab` 的 heading-driven 主线实现。
+- 没有真实 target window 的场景里,要明确区分 `StandaloneCursor` 的 raw reverse-engineered pool 和 `CursorMotion` 的 heading-driven 主线实现。
- demo host 可以替换,但 motion model 和 visual dynamics 应保持可单独复用。
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorGlyphCalibration.swift b/experiments/CursorMotion/Sources/CursorMotion/CursorGlyphCalibration.swift
similarity index 100%
rename from experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorGlyphCalibration.swift
rename to experiments/CursorMotion/Sources/CursorMotion/CursorGlyphCalibration.swift
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift b/experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift
similarity index 100%
rename from experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorLabRootView.swift
rename to experiments/CursorMotion/Sources/CursorMotion/CursorLabRootView.swift
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/StandaloneCursorLabApp.swift b/experiments/CursorMotion/Sources/CursorMotion/CursorMotionApp.swift
similarity index 81%
rename from experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/StandaloneCursorLabApp.swift
rename to experiments/CursorMotion/Sources/CursorMotion/CursorMotionApp.swift
index 8d60e6e..c00426a 100644
--- a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/StandaloneCursorLabApp.swift
+++ b/experiments/CursorMotion/Sources/CursorMotion/CursorMotionApp.swift
@@ -2,19 +2,19 @@ import AppKit
import SwiftUI
@main
-enum StandaloneCursorLabMain {
+enum CursorMotionMain {
static func main() {
let application = NSApplication.shared
application.setActivationPolicy(.regular)
- let delegate = StandaloneCursorLabAppDelegate()
+ let delegate = CursorMotionAppDelegate()
application.delegate = delegate
application.run()
}
}
@MainActor
-final class StandaloneCursorLabAppDelegate: NSObject, NSApplicationDelegate {
+final class CursorMotionAppDelegate: NSObject, NSApplicationDelegate {
private var window: NSWindow?
func applicationDidFinishLaunching(_ notification: Notification) {
@@ -26,7 +26,7 @@ final class StandaloneCursorLabAppDelegate: NSObject, NSApplicationDelegate {
backing: .buffered,
defer: false
)
- window.title = "Standalone Cursor Lab"
+ window.title = "Cursor Motion"
window.center()
window.isReleasedWhenClosed = false
window.minSize = NSSize(width: 1120, height: 760)
@@ -50,7 +50,7 @@ final class StandaloneCursorLabAppDelegate: NSObject, NSApplicationDelegate {
mainMenu.addItem(appMenuItem)
let appMenu = NSMenu()
- appMenu.addItem(withTitle: "Quit Standalone Cursor Lab", action: #selector(NSApplication.terminate(_:)), keyEquivalent: "q")
+ appMenu.addItem(withTitle: "Quit Cursor Motion", action: #selector(NSApplication.terminate(_:)), keyEquivalent: "q")
appMenuItem.submenu = appMenu
NSApp.mainMenu = mainMenu
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift b/experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift
similarity index 100%
rename from experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/CursorMotionModel.swift
rename to experiments/CursorMotion/Sources/CursorMotion/CursorMotionModel.swift
diff --git a/experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/SynthesizedCursorGlyphView.swift b/experiments/CursorMotion/Sources/CursorMotion/SynthesizedCursorGlyphView.swift
similarity index 100%
rename from experiments/StandaloneCursorLab/Sources/StandaloneCursorLab/SynthesizedCursorGlyphView.swift
rename to experiments/CursorMotion/Sources/CursorMotion/SynthesizedCursorGlyphView.swift
diff --git a/experiments/StandaloneCursor/README.md b/experiments/StandaloneCursor/README.md
index c9099dc..b4478b2 100644
--- a/experiments/StandaloneCursor/README.md
+++ b/experiments/StandaloneCursor/README.md
@@ -10,7 +10,7 @@
- `prefer in-bounds, then lowest score`
- `response=1.4`、`dampingFraction=0.9`、`dt=1/240` 的 raw spring timeline
- 刻意不引入当前还没恢复出来的 wall-clock duration 映射。
-- 刻意不复用 `StandaloneCursorLab` 那套更偏实验性的 visual dynamics / knob 调参结构。
+- 刻意不复用 `CursorMotion` 那套更偏实验性的 visual dynamics / knob 调参结构。
## 运行方式
@@ -29,4 +29,4 @@ swift run StandaloneCursor
- 想看 Python 重建逻辑换成 Swift 之后的实际轨迹和时序表现。
- 想快速核对候选路径池、score 和 endpoint lock / close-enough 时间,而不是继续调视觉手感。
-- 想和 `StandaloneCursorLab` 做对照,区分“脚本级 binary lift”与“更自由的实验 demo”。
+- 想和 `CursorMotion` 做对照,区分“脚本级 binary lift”与“更自由的实验 demo”。
diff --git a/scripts/build-cursor-motion-dmg.sh b/scripts/build-cursor-motion-dmg.sh
new file mode 100755
index 0000000..450824e
--- /dev/null
+++ b/scripts/build-cursor-motion-dmg.sh
@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+configuration="release"
+arch_mode="native"
+version=""
+output_dir=""
+
+usage() {
+ cat <<'EOF'
+Usage: ./scripts/build-cursor-motion-dmg.sh [--configuration debug|release] [--arch native|arm64|x86_64|universal] [--version X.Y.Z] [--output-dir PATH]
+
+Examples:
+ ./scripts/build-cursor-motion-dmg.sh
+ ./scripts/build-cursor-motion-dmg.sh --configuration release --arch universal --version 0.1.0
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --configuration)
+ configuration="${2:-}"
+ if [[ -z "${configuration}" ]]; then
+ echo "--configuration requires a value" >&2
+ exit 1
+ fi
+ shift 2
+ ;;
+ --arch)
+ arch_mode="${2:-}"
+ if [[ -z "${arch_mode}" ]]; then
+ echo "--arch requires a value" >&2
+ exit 1
+ fi
+ shift 2
+ ;;
+ --version)
+ version="${2:-}"
+ if [[ -z "${version}" ]]; then
+ echo "--version requires a value" >&2
+ exit 1
+ fi
+ shift 2
+ ;;
+ --output-dir)
+ output_dir="${2:-}"
+ if [[ -z "${output_dir}" ]]; then
+ echo "--output-dir requires a value" >&2
+ exit 1
+ fi
+ shift 2
+ ;;
+ -h|--help)
+ usage
+ exit 0
+ ;;
+ *)
+ echo "Unknown argument: $1" >&2
+ usage >&2
+ exit 1
+ ;;
+ esac
+done
+
+if [[ "${configuration}" != "debug" && "${configuration}" != "release" ]]; then
+ echo "Unsupported configuration: ${configuration}" >&2
+ exit 1
+fi
+
+if [[ "${arch_mode}" != "native" && "${arch_mode}" != "arm64" && "${arch_mode}" != "x86_64" && "${arch_mode}" != "universal" ]]; then
+ echo "Unsupported arch mode: ${arch_mode}" >&2
+ exit 1
+fi
+
+if [[ -z "${version}" ]]; then
+ if tag="$(git -C "${repo_root}" describe --tags --exact-match 2>/dev/null)"; then
+ version="${tag#v}"
+ else
+ version="0.0.0-dev"
+ fi
+fi
+
+if [[ -z "${output_dir}" ]]; then
+ output_dir="${repo_root}/dist/release/cursor-motion"
+fi
+
+build_binary() {
+ local triple="${1:-}"
+ local scratch_path="${2:-}"
+ local -a args=(-c "${configuration}")
+
+ if [[ -n "${triple}" ]]; then
+ args+=(--triple "${triple}")
+ fi
+
+ if [[ -n "${scratch_path}" ]]; then
+ args+=(--scratch-path "${scratch_path}")
+ fi
+
+ local binary_dir
+ binary_dir="$(swift build "${args[@]}" --show-bin-path)"
+ swift build "${args[@]}" --product CursorMotion >&2
+ printf '%s/CursorMotion\n' "${binary_dir}"
+}
+
+app_name="Cursor Motion.app"
+bundle_identifier="com.ifuryst.cursormotion"
+bundle_version="${CURSOR_MOTION_BUNDLE_VERSION:-${GITHUB_RUN_NUMBER:-$(git -C "${repo_root}" rev-list --count HEAD 2>/dev/null || echo 1)}}"
+app_root="${output_dir}/${app_name}"
+contents_dir="${app_root}/Contents"
+macos_dir="${contents_dir}/MacOS"
+dmg_root="${output_dir}/dmg-root"
+dmg_path="${output_dir}/CursorMotion-${version}.dmg"
+
+rm -rf "${output_dir}"
+mkdir -p "${macos_dir}" "${dmg_root}"
+
+cd "${repo_root}"
+
+case "${arch_mode}" in
+ native)
+ cp "$(build_binary "" "")" "${macos_dir}/CursorMotion"
+ ;;
+ arm64)
+ cp "$(build_binary "arm64-apple-macosx14.0" ".build/cursor-motion-arm64-${configuration}")" "${macos_dir}/CursorMotion"
+ ;;
+ x86_64)
+ cp "$(build_binary "x86_64-apple-macosx14.0" ".build/cursor-motion-x86_64-${configuration}")" "${macos_dir}/CursorMotion"
+ ;;
+ universal)
+ arm_binary="$(build_binary "arm64-apple-macosx14.0" ".build/cursor-motion-arm64-${configuration}")"
+ x86_binary="$(build_binary "x86_64-apple-macosx14.0" ".build/cursor-motion-x86_64-${configuration}")"
+ lipo -create -output "${macos_dir}/CursorMotion" "${arm_binary}" "${x86_binary}"
+ ;;
+esac
+
+chmod +x "${macos_dir}/CursorMotion"
+
+cat > "${contents_dir}/Info.plist" <<PLIST
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+ <key>CFBundleDevelopmentRegion</key>
+ <string>en</string>
+ <key>CFBundleExecutable</key>
+ <string>CursorMotion</string>
+ <key>CFBundleIdentifier</key>
+ <string>${bundle_identifier}</string>
+ <key>CFBundleInfoDictionaryVersion</key>
+ <string>6.0</string>
+ <key>CFBundleName</key>
+ <string>Cursor Motion</string>
+ <key>CFBundleDisplayName</key>
+ <string>Cursor Motion</string>
+ <key>CFBundlePackageType</key>
+ <string>APPL</string>
+ <key>CFBundleShortVersionString</key>
+ <string>${version}</string>
+ <key>CFBundleVersion</key>
+ <string>${bundle_version}</string>
+ <key>LSMinimumSystemVersion</key>
+ <string>14.0</string>
+ <key>NSPrincipalClass</key>
+ <string>NSApplication</string>
+</dict>
+</plist>
+PLIST
+
+plutil -lint "${contents_dir}/Info.plist" >/dev/null
+codesign --force --deep --sign - "${app_root}" >/dev/null 2>&1 || true
+
+cp -R "${app_root}" "${dmg_root}/"
+ln -s /Applications "${dmg_root}/Applications"
+
+hdiutil create \
+ -volname "Cursor Motion" \
+ -srcfolder "${dmg_root}" \
+ -ov \
+ -format UDZO \
+ "${dmg_path}" \
+ >/dev/null
+
+echo "${dmg_path}"
diff --git a/scripts/cursor-motion-re/README.md b/scripts/cursor-motion-re/README.md
index 5155862..69de69c 100644
--- a/scripts/cursor-motion-re/README.md
+++ b/scripts/cursor-motion-re/README.md
@@ -1,6 +1,6 @@
# Cursor Motion RE Scripts
-这个目录承载和官方 `Codex Computer Use.app` cursor motion 逆向相关的独立脚本,不依赖 `StandaloneCursorLab`,也不接入主运行时。
+这个目录承载和官方 `Codex Computer Use.app` cursor motion 逆向相关的独立脚本,不依赖 `CursorMotion`,也不接入主运行时。
当前脚本优先做两件事: