makecindy / makecindy/cindy

feature: 在 Cindy Desktop 内嵌 iOS Simulator,支持 Agent / 用户实时协同

Open
#160 0 comments 0 reactions 0 assignees View on GitHub
feature
Dominant language
TypeScript
Stars
2.7k
Forks
395
Avg merge
21h 48m
Merged PRs (30d)
776

Description

## 背景

参考 X 上对 Claude Code Desktop iOS Simulator 能力的介绍:
https://x.com/xiaohu/status/2079768228897894467

核心体验包括:

- 直接对接 Apple 官方 iOS Simulator。
- 模拟器画面内嵌在桌面端会话旁边,不抢占前台屏幕。
- Agent 自动操作与用户手动点击、滑动、快捷键可以实时协同。
- 每个 Session 拥有隔离的模拟器实例,目标支持单个 Session 最多 4 个模拟器。
- 支持 Home、截图、录屏等操作,并可调 FPS、分辨率和编码格式降低资源占用。

Cindy 当前已经有仓库专用的 `pnpm mobile:sim:start`、`mobile:sim:rebuild`、`mobile:sim:whoami`,可以启动、重装和核对 Cindy Mobile 的 iOS development client;但这些仍是终端脚本 + 独立 Simulator.app 的开发链路,不是 Cindy Desktop 内面向任意 iOS 项目的 Session 级产品能力。

## 目标

在 macOS 版 Cindy Desktop 中加入 Session 级 iOS Simulator 能力。用户可以在会话里直接说“把 App 构建并运行到模拟器,检查注册流程”,Cindy 自动完成环境检查、构建、安装、启动,并在会话右侧打开可交互的模拟器面板。Agent 可以在后台操作,用户也可以随时接管或协同操作。

## 建议范围

### 1. Simulator 生命周期与项目编排

- 检测 Xcode、Simulator runtime、可用 device、当前项目类型与可构建 scheme。
- 支持创建、启动、安装、拉起、重启、停止和回收 Simulator 实例。
- 将实例绑定到 Cindy Session / worktree,展示实际工作目录、commit / source fingerprint、app bundle id,避免操作错分支或残留构建。
- 对 Cindy Mobile 项目复用现有 `mobile:sim:*` 契约;通用能力不能硬编码为 Cindy Mobile 专用脚本。
- main 进程负责系统调用、生命周期、资源仲裁和错误处理;renderer 只负责展示与交互,通过受控 IPC 通讯。

### 2. 内嵌画面与用户交互

- 在会话侧边提供可停靠、展开、收起的 Simulator 面板,切换会话时不出现空白帧或明显跳变。
- 支持鼠标点击、拖拽滑动、键盘输入、旋转、Home、锁屏等常用操作。
- 支持用户与 Agent 同时操作同一实例,输入实时同步,并明确展示当前操作来源。
- 不强制抢占系统前台;面板收起后 Agent 仍可继续执行测试。

### 3. Agent 工具能力

- 为 Agent 暴露确定性的 Simulator 工具:列设备、启动 / 停止、构建安装、打开 App、tap、swipe、输入文本、按键、截图、录屏、读取基础状态。
- 工具调用必须显式绑定 Session 和 simulator id,禁止跨 Session 误操作。
- 操作结果返回结构化状态与错误,不依赖 prompt 猜测成功与否。
- 截图和录屏等媒体落盘统一进入 `cindy-media` 媒体总仓,禁止新增专用缓存目录或绕过 ledger。

### 4. 多 Session / 多实例与资源控制

- 不同 Session 的 Simulator、App 状态和操作队列相互隔离。
- 目标支持单个 Session 最多 4 个 Simulator;可分阶段先交付单实例 MVP,再扩展多实例。
- 提供并发上限、空闲回收、后台降帧 / 暂停渲染和资源占用提示。
- 支持调整 FPS、分辨率、编码格式;配置按实例或 Session 生效。

### 5. 可观测性与失败恢复

- 对缺少 Xcode / runtime、scheme 不可构建、签名失败、安装失败、实例失联、画面流中断给出可执行的错误提示。
- 保留关键生命周期和工具调用日志,能够定位“连错 worktree / bundle / simulator”的问题。
- Cindy 重启后能够识别并选择恢复或清理遗留实例,不静默接管来源不明的 Simulator。

## 验收标准

- [ ] 仅在 macOS 且环境满足时展示 / 启用 iOS Simulator 能力,其他平台给出清晰说明。
- [ ] 在一个 iOS 项目会话中,用自然语言可以触发环境检查、构建、安装、启动,并自动打开内嵌面板。
- [ ] Agent 可以在不抢占前台的情况下完成 tap、swipe、文本输入、Home、截图和录屏。
- [ ] 用户可以在 Agent 测试期间直接在同一画面点击 / 滑动,双方看到同一实时状态。
- [ ] 两个 Session 同时运行时,设备归属、输入、App 状态和产物不会串线。
- [ ] 面板明确显示项目路径 / worktree、source fingerprint、bundle id、simulator id 和运行状态。
- [ ] 支持至少一档低资源模式;收起或后台状态下不会持续高负载刷新。
- [ ] 退出 Session 或主动停止后,相关进程、端口和实例能够安全回收。
- [ ] 截图 / 录屏按 `cindy-media` 规则落盘、读取和释放引用。
- [ ] 有覆盖生命周期、Session 隔离、工具路由、错误恢复的自动化测试,并完成真实 Simulator 黑盒验证。

## 非目标

- Android Emulator 支持。
- 云真机 / 云模拟器平台。
- iPhone 真机控制。
- 首期覆盖所有 Xcode 工程结构和第三方构建系统。

## 待调研

- Apple Simulator 画面嵌入、视频采集和输入注入可采用的稳定公开接口,以及对应的系统权限 / 兼容性边界。
- 现有 Android ADB / computer / browser control runtime 中哪些中性抽象可复用,哪些应保持平台隔离。
- 单 Session 多 Simulator 的 UI 布局、资源预算和默认并发数。
- Agent 自动化与用户手动输入发生冲突时的仲裁、暂停和接管语义。

Contributor guide

Open the contributing guide

Research direction

Start by reading the existing `pnpm mobile:sim:start`, `mobile:sim:rebuild`, and `mobile:sim:whoami` contracts, then trace the main-process, renderer, and controlled IPC boundaries. Research the stable public Apple Simulator interfaces and existing Android control abstractions before defining a staged MVP; done means the listed lifecycle, Session isolation, interaction, media, recovery, and automated/black-box validation criteria are met.

Written by the indexing model from the issue text.

Assessment

Tech stack
electron, ios, macos, typescript
Domain
desktop, devtools, mobile-dev, testing-qa
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.