Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
Cindy Mobile Desktop Source Inventory
自动化范围修订(2026-09-27):手机已移除旧 Scheduler 管理页和 Routines,包括「所有任务」下拉及伙伴资料入口;不再把查看、创建、编辑或运行规则列为手机交付、后续计划或验收项。PC 管理与执行、已有任务数据和运行历史保留。本文所有旧自动化管理实现、原型验证和计划记录仅作历史背景,不代表待恢复功能;当前边界以伙伴运行时合同为准。
日期: 2026-06-17 目标: 从桌面版源码逐项反推手机版远程控制需要覆盖的界面、内容、状态和测试条件。 V1 边界: 除完整协作 / Orca 编排外,把普通单会话远程控制和非协作附属能力做完整。协作会话 V1 只识别、只读、安全降级。
1. 使用方式
这份文档是实现清单,不是产品愿望清单。后续手机版开发按每个模块的“桌面源码真相 -> 手机实现方式 -> 验收条件”推进。
desktop-interaction-audit.md: 详细审计背景和桌面行为说明。mobile-v1-source-plan.md: 里程碑、开发顺序和自动化测试计划。shared-core-migration-plan.md: 共享展示模型、迁移顺序和跨端 fixture 测试门槛。- 本文档: 面向开发执行的功能矩阵,覆盖消息交互、选项卡、计划、文件页、协作模式和测试调优。
V1 的判断标准:
- 手机端看到的 session、message、queue、interaction、schedule 都来自电脑端真相源。
- 手机端不新建一套状态机,只做远程 invoke、topic subscribe、移动端 UI state 和短期缓存。
- 可复用的 session/message render model、pending interaction model、queue/input projection model、session controls/runtime options、file browser model、automation/schedule model 要沉到
packages/maker-shared,再由桌面端和手机版各自渲染。 - 桌面端已有的业务语义不改,只把 hover、右栏、split pane、侧边栏、tab bar 改成 stack、sheet、full-screen modal、segmented control。
- 遇到 Orca lead / worker / collaboration session 不崩溃,但不提供完整多 worker 编排。
2. 桌面源码入口总表
| 领域 | 桌面源码 | 手机版用途 |
|---|---|---|
| 路由和壳层 | router.tsx, CCAgentFeatureLayout.tsx, CCAgentSessionView.tsx |
定义登录、新建、会话、文件、计划、协作的一级结构。 |
| 设备远程 | useDeviceLinkRemoteProjects.ts, remoteProjectsStore.ts, refreshRemoteSessions.ts |
定义同账号电脑、可控状态、sessions bootstrap、reseed 和撤权。 |
| 远程传输 | makerTransport.ts, dispatch.ts, allowlist.ts, topics.ts |
定义手机可以调用什么、订阅什么、哪些能力必须拒绝。 |
| 会话头部 | SessionContentHeader.tsx, RemoteSessionBanner.tsx, ErrorBanner.tsx, UpgradeBanner.tsx |
定义连接状态、标题、置顶、归档、删除、错误、升级提示。 |
| 消息流 | MessageStream.tsx, MessageItem.tsx, UserMessage.tsx, AssistantMessage.tsx |
定义 raw messages 如何转成可渲染条目。 |
| 工作过程 | WorkGroupBlock.tsx, AgentActionsBlock.tsx, AgentActionRow.tsx, ThinkingCard.tsx, TodoListCard.tsx |
定义 thinking、tool、todo、work group 的折叠和内容展示。 |
| System cards | SystemCard.tsx |
定义 /context, /status, /cost, /pwd, /cmd, /compact, /help 的显示。 |
| 媒体和 payload | ChatImageView.tsx, ChatVideoView.tsx, ChatAudioCard.tsx, ImageLightbox.tsx, VideoLightbox.tsx, ToolPayloadLightbox.tsx |
定义图片、视频、音频、长 payload、文件 payload 的移动端映射。 |
| 输入器 | ChatInput.tsx, PendingQueuePanel.tsx, ModelSelector.tsx, PermissionSelector.tsx, FastModeToggle.tsx, ExtraDirsButton.tsx |
定义发送、停止、队列、附件、语音、slash、@、模型、权限、fast、extra dirs。 |
| Pending interactions | PermissionPrompt.tsx, AskUserQuestionPrompt.tsx, PlanViewerCard.tsx, PlanActionCard.tsx;IssueConfirmCard.tsx 仅作桌面反馈链路参考 |
定义权限、提问、计划确认的决策 shape;Issue 确认在 mobile V1 只做 desktop-only 降级识别。 |
| 自动化计划 | SchedulerPage.tsx, TaskListPane.tsx, RunHistoryPane.tsx, ScheduleFormDialog.tsx, TemplateGallery.tsx |
定义 schedules 列表、运行历史、运行/暂停/恢复/删除、创建/编辑。 |
| 文件和选项卡 | WorkdirBrowseRoute.tsx, FileBodyView.tsx, WorkdirBrowseSidebar.tsx, FileTabsBar.tsx, SessionTabsBar.tsx |
定义文件树、文件预览、文件 tab、同目录 session tab、chat rail。 |
| 协作 / Orca | ExtraDirsButton.tsx(「+」菜单协同项), OrcaWorkflowRoute.tsx, OrcaSplitView.tsx, CreateWorkerPopover.tsx, useWorkers.ts |
定义 lead + worker + focus + split/toggle 的真实协作模型。 |
3. V1/V1B/V2 分层
| 模块 | V1A | V1B | V2 |
|---|---|---|---|
| 设备 | 可控电脑发现、离线/撤权/同步失败、重新同步 | 设备详情和调试信息 | 多设备批量管理 |
| 会话列表 | 普通 session 列表、搜索、状态、归档/置顶/删除 | 自动化分组、项目分组、批量操作 | 桌面级侧边栏完整 parity |
| 会话详情 | 消息流、发送、停止、队列、pending interactions、基础会话动作 | diff、context/cost detail、fork/rewind、媒体增强 | 多窗/多 pane 级能力 |
| 新会话 | 选择远程电脑、工作区、agent/model/permission/fast、首条消息 | extra dirs、附件、slash、@、语音 | 项目模板和高级工作流 |
| 文件 | 工具引用文件卡、只读文件预览 | 文件树、文件 tabs、同目录 session tabs | 完整编辑器、dirty/conflict/save |
| 自动化管理 | 手机已移除,保留已有任务与运行历史 | 不再计划手机创建/编辑 | 不再计划手机高级管理;PC 功能保留 |
| 协作 | 识别 lead/worker,安全只读提示 | worker 快速跳转 | 完整 Orca 移动编排 |
4. 手机信息架构
4.1 一级入口
| 手机入口 | 桌面对应 | V1 设计 |
|---|---|---|
| Home | desktop sidebar + remote projects | 默认首页。直接合并展示所有可控电脑的 Pinned / Projects / Chats / sessions;电脑只作为轻量筛选、online/offline 归属和调试上下文。 |
| Devices | remote projects / controllable computers | 二级/调试入口。展示同账号电脑、不可控原因、撤权、同步失败和重新同步,不作为进入会话的必经路径。 |
| Session | /cc-agent/:sessionId |
主控制面。消息流常驻,底部根据 pending interaction 或 composer 切换。 |
| New | /cc-agent/new |
从选中电脑创建远程会话。手机不选择本机 cwd,只选择电脑端可用工作区。 |
| Automations(已移除) | 桌面 Scheduler 继续保留 | 手机无管理入口,旧链接仅跳转设备页。 |
| Files | /cc-agent/files/:sessionId |
V1B 只读文件页。完整编辑留 V2。 |
| Settings | 登录、设备、relay、debug | mock login / Feishu login / 退出、设备名、日志导出。手机版第一刀已拆成独立 /settings 主窗口;被控权限开关仍归桌面端设置。 |
4.2 会话详情层级
桌面 CCAgentSessionView 的真实层级需要被手机保留为语义,但改成交互更轻的移动形态。
| 桌面层 | 手机实现 |
|---|---|
RemoteSessionBanner |
顶部窄条: reconnecting、host offline、revoked、resync。不能挤掉消息流。 |
MessageStream |
主体虚拟列表。保持旧消息 anchor、自动跟随和 unread 语义。 |
| Running status bar | 贴近 composer 的运行态条,显示正在生成、停止、继续、token/context 简讯。 |
ErrorBanner |
inline banner,保留 retry/cancel/sync auth 等可行动作。 |
UpgradeBanner |
移动端低优先级卡片,不挡住输入。 |
InteractionPromptHost |
bottom sheet / full-screen modal,优先级高于 composer。 |
ChatInput |
底部输入区。只在没有 pending interaction 和阻塞态时可编辑。 |
| Diff panel | full-screen route 或 sheet,不做桌面右栏。 |
| TopRightChipStack | header 更多菜单 + 状态 chips。 |
Pending 区域优先级:
- Plan Review。
- Permission。
- Ask User。
- Issue Confirm。
- Takeover / Worktree creating 阻塞。
- Composer。
5. 消息流源码语义
5.1 Raw message 到 render item
桌面 MessageStream.tsx 不是简单按 message 渲染,而是先构造 render items。
| 桌面规则 | 手机必须对齐 |
|---|---|
RENDER_WINDOW_INITIAL_ITEMS = 80, RENDER_WINDOW_GROWTH_ITEMS = 80 |
手机同样按 render item 窗口增长,不要按 raw message 数量简单分页。 |
未回答的 ask_user 不直接出现在消息流 |
手机只通过 pending interaction 展示待回答问题。 |
AskUserQuestion 和 ExitPlanMode tool call 被过滤 |
手机不能把这些内部工具当普通 tool 卡片显示。 |
TodoWrite tool input 提取为 todo render item |
手机要展示 Todo 卡,不要显示原始 Tool JSON。 |
tool_use 和 tool_result 通过 toolUseId 配对,必要时用相邻 fallback |
手机端数据 reducer 要保留配对逻辑,否则 tool result 会错位。 |
tool result 中媒体被提取为 tool_media |
手机端媒体卡应从同一 payload 提取,不能只显示文本。 |
thinking/tool/todo/intermediate assistant 会被折进 work_group |
手机要有工作过程折叠卡,否则长工具链会淹没正文。 |
5.2 Message item 类型
| 类型 | 桌面显示 | 手机实现 |
|---|---|---|
| user | 用户消息 + action bar | 普通气泡,消息结束处轻量 action bar 提供复制、分叉、撤销、时间;完成态正文尽量在可见文本上直接选择。 |
| assistant | Markdown、代码块、引用、action bar | Markdown 渲染、代码横向滚动、消息结束处轻量 action bar;完成态正文尽量在可见文本上直接选择。 |
| thinking | ThinkingCard streaming/final/redacted/aborted |
默认折叠,流式时显示短摘要和时间。 |
| tool_use/result | AgentActionsBlock / AgentActionRow |
默认折叠为“工作过程”,点开看每个工具。 |
| todo | TodoListCard |
对齐桌面 inline checklist:completed/total + active item + 三态图标,不做单独 Todo sheet。 |
| system | SystemCard |
系统卡,按 card type 显示不同内容。 |
| media | ChatImageView, ChatVideoView, ChatAudioCard |
inline 缩略卡 + full-screen viewer/player。 |
| work_group | WorkGroupBlock |
一个折叠块承载 thinking/tools/todo/intermediate 输出。 |
5.3 滚动、窗口和未读
桌面滚动语义:
- 增量加载旧消息时保持 key anchor。
- 只有接近底部时自动跟随。
- 新 assistant / ask_user / plan_review 才计入 unread。
- 点击 jump-to-bottom 才清 unread。
- loading older 只在顶部补旧数据时出现。
手机验收:
- 长会话 1000+ render items 不能卡顿。
- 用户向上读旧消息时新消息不能把列表拉到底。
- 远程 reconnect 后 messages reseed 不应产生明显跳动。
- unread 计数和 jump 行为与桌面一致。
6. 消息内容和 payload
6.1 Assistant 内容
手机端要复用桌面 assistant message 的语义:
- Markdown 段落、列表、引用。
- fenced code block,支持复制。
- inline code。
- 链接打开确认或系统浏览器。
- 文件 path chip / mention chip。
- 中间态 assistant 内容如果属于 work group,按桌面规则折叠。
6.2 Tool row
AgentActionRow.tsx 说明 tool row 不是纯文本日志。
| Tool payload | 手机实现 |
|---|---|
Edit, Write, MultiEdit, Read 文件路径 |
文件 chip,点开移动文件预览或 payload 详情。 |
| diff/patch | full-screen diff viewer,支持文件头、统计、分段、复制。 |
| 长 input/result | 默认折叠,点开 ToolPayloadLightbox 等价详情。 |
| error result | 高亮错误,保留在工作过程里,不打断消息流。 |
| 非文件工具 | 展示工具名、状态、摘要、输入/输出详情。 |
6.3 媒体 payload
AgentActionRow 从 tool result 中提取这些字段:
xdt_image_url,xdt_image_urls。xdt_video_url,xdt_video_urls。xdt_audio_url,xdt_audio_urls。_xdt_audio_tracks。_xdt_model_files。_xdt_render_image。_xdt_actions。
手机实现:
- 图片: 缩略图、全屏预览、保存/分享、基础缩放。真 pinch zoom 作为后续增强。
- 视频: inline poster + 全屏播放。
- 音频: track card、播放/暂停、进度、标题/封面/lyrics 元数据。
- model 文件: V1 显示文件卡和“不支持手机预览”提示,V2 再评估 3D preview。
_xdt_actions: V1 先安全展示为不可用或二次确认按钮;V1B/V2 再接远程 UI trigger,并且必须有 inflight 锁避免重复触发。
6.4 Todo
TodoListCard 语义:
- 从
TodoWritetool input 提取 todo。 - 展示 completed/total。
- 展示当前
in_progress。 - 状态包括
pending,in_progress,completed。 - 折叠时显示进度条和 active item。
手机实现:
- 消息内对齐桌面
TodoListCard:completed/total、active item、三态图标和 inline list。 - 不做独立 Todo sheet、“查看全部任务”按钮或状态文字标签。
- 流式更新时保持 card 高度尽量稳定。
6.5 System cards
SystemCard.tsx 包含这些 card type:
| Card type | 手机显示 |
|---|---|
help |
简短帮助,移动端可折叠。 |
cost |
本轮/会话费用摘要,详情进 sheet。 |
context |
context usage、categories、mcpTools、memoryFiles、agents、skills、slashCommands、messageBreakdown、apiUsage。 |
pwd |
当前工作目录。 |
status |
agent/runtime 状态。 |
compact |
compact 结果和提示。 |
cmd |
slash command 运行结果。 |
V1 最低要求是能显示所有 system card,不能丢弃 /context 这类内容。复杂详情可以收进 sheet。
7. 输入器和发送链路
7.1 ChatInput 真实能力
ChatInput.tsx 不是 textarea,它包含:
- TipTap plain text。
- mention chip node。
- 附件: file、folder、clipboard image。
- 草稿存储。
- slash palette。
@resource panel。- model selector。
- effort selector。
- permission mode selector。
- fast mode toggle。
- extra dirs。
- folder/workdir picker。
- pending queue。
- voice input。
- collaboration toggle。
手机 V1:
- 输入框、发送、停止、继续。
- 多行文本和粘贴。
- 底部常驻入口使用桌面同族图标:附件/更多、输入框、语音、发送/停止;语音放在发送左侧。
- 附件先支持图片/文件引用,folder 作为 V1B。
- 模型、effort、permission、fast 放进“会话设置”sheet。
- slash 和 @ 放在 composer 上方的快捷入口。
- voice input 保留按钮,失败时不影响文本发送。
- collaboration toggle V1 只显示只读提示,不触发完整 Orca。
7.2 发送路径
桌面 CCAgentSessionView 发送前会处理:
- navigation command。
/context本地 system card。- desktop slash command dispatch。
- auth gate。
- folder picker / workingDir。
- archived session auto-unarchive。
- queue / send / steer。
手机实现:
- 普通文本发送走远程
makerApiFor(sessionId).send等价能力。 /context可走远程 context usage 并插入/展示 system card,不要手机本地伪造。- 其它 slash command 走被控电脑的 command dispatch,不在手机本机执行。
- archived session 发送前确认并远程 unarchive。
- running 时发送要走 queue 或 steer 语义,不能强行打断。
7.3 Queue
PendingQueuePanel.tsx 的产品规则:
- FIFO。
- 4 条以内完整显示。
- 5 条以上默认显示前 3 条,可 show more。
- Stop 负责 paused state。
- paused 状态提供 Continue 和 steer。
- 排序时安装全局 lock。
- 编辑某行时安装 row lock。
resolveSingleMove把最终 index 转成 makerChatStore insertion index。
手机实现:
- composer 上方显示 queue strip 或 chip。
- 点开 queue sheet。
- 支持删除、编辑、重排、继续、steer。
- 拖拽排序可先用上下移动按钮替代,但语义必须对应桌面排序。
- queue 操作要走远程 queue API,不能只改手机本地列表。
8. Pending interactions
8.1 Permission
PermissionPrompt.tsx 决策 shape:
- Allow once:
{ behavior: 'allow' }。 - Always allow for session:
{ behavior: 'allow', updatedPermissions, decisionClassification: 'user_permanent' }。 - Deny:
{ behavior: 'deny', message: 'User denied', decisionClassification: 'user_reject' }。
手机实现:
- 底部 sheet。
- 展示工具名、说明、关键 input。
- Allow once / Always allow / Deny 三个动作。
- 默认聚焦风险说明,但不改变桌面权限模型。
- resolve 后立即锁按钮,直到远程 interaction 更新。
8.2 Ask User
AskUserQuestionPrompt.tsx 语义:
- 多步骤 wizard。
- single-select 点击后立即进入下一步或提交。
- multi-select 最终编码为 JSON array string。
- Skip 是空字符串。
- draft 由 requestId 维度持久化。
- viewer 可 expand/minimize。
手机实现:
- full-screen 或 tall sheet wizard。
- 单选点击即前进。
- 多选有明确提交按钮。
- Skip 保持空字符串语义。
- 退出再进不丢当前 request 草稿。
8.3 Plan Review
PlanViewerCard.tsx 和 PlanActionCard.tsx 语义:
- viewer 状态: expanded、half、minimized、edit。
- outline 从 Markdown h1-h3 DOM 生成。
- edit 通过
onPlanContentChange写回。 - approve row 和 feedback row 分开。
- approve 支持 Enter。
- feedback 支持 Enter with text。
- submit 后冻结,避免重复响应。
手机实现:
- 默认 full-screen review。
- outline 用目录 sheet 或顶部 segmented。
- 编辑计划需要明确“编辑”模式,保存后回到 review。
- Approve 和 Send feedback 固定底部。
- 发送后冻结按钮,等待远程消息推进。
8.4 Issue Confirm
IssueConfirmCard.tsx 语义:
- title/body/type 可编辑。
- env info 只读。
- Confirm 发送
{ confirmed: true, title, body, type, uiLanguage }。 - Cancel 发送
{ confirmed: false }。 - Ctrl/Cmd+Enter 提交,Esc 取消。
手机实现:
- V1 不实现 GitHub Issue 表单。
- 只识别
issue_confirmpending interaction 并显示 desktop-only 降级说明。 - 不在手机端提交
{ confirmed: true },避免把桌面反馈链路误做成手机版主流程。
9. 会话列表和会话管理
9.1 Sidebar 语义
桌面 CCAgentSidebarUpper.tsx / SessionItem.tsx 提供:
- New session。
- Automations entry。
- pinned/dialogue/projects/date 分组。
- filters: archived/all 等。
- search。
- selection / bulk archive/delete。
- remote project sessions 合并显示。
- Orca worker 隐藏或按 lead 关系处理。
- session title、vendor icon、running/attached、attention、draft、PR tooltip、schedule badge、worktree badge。
- double click rename。
- context menu: pin/unpin、archive、delete、copy id/deep link 等。
手机 V1:
- 列表默认按 pinned、running/waiting、recent 分组。
- 搜索和 archived filter 必做。
- running、waiting permission/question/plan、draft、schedule badge 必须可见。
- 单条 swipe 或更多菜单支持 pin/archive/delete/rename。
- bulk operation 可 V1B。
- Orca worker V1 不直接混在普通列表里造成误点,至少标注“协作会话,手机版暂不支持完整操作”。
9.2 Header action
SessionContentHeader.tsx 行为:
- title inline rename。
- pin/unpin。
- copy deep link。
- copy XDT ID / SDK ID。
- open in new window。
- archive/delete/unarchive。
- running/attached 时阻止 archive。
手机实现:
- Header 显示 title,更多菜单承载操作。
- rename 用 sheet。
- copy id/deep link 可 V1B。
- open in new window 手机不需要,可隐藏。
- archive/delete/unarchive 需要遵守 running/attached 阻止规则。
10. 新建会话
桌面新建来自 NewMakerDraftRoute + ChatInput。
手机新建必须以被控电脑为上下文:
- 先选设备。
- 选工作区/项目,来源是被控电脑,不是手机文件系统。
- 选择 agent。
- 选择 model、effort、permission、fast。
- 输入首条消息。
- 可附加图片/文件。
- 发送后进入新 session detail。
V1 最小闭环:
- 默认使用电脑端最近工作区或项目。
- 允许切换工作区。
- 允许选择 agent/model/permission。
- 支持首条消息创建 session。
V1B:
- extra dirs。
- slash command。
- @ resource。
- project automation context。
11. 文件页和选项卡
11.1 WorkdirBrowseRoute
桌面 /cc-agent/files/:sessionId 的结构:
- file body + chat rail。
- sidebar 切换为 file tree。
?file表示选中文件。- remote SSH session 会 redirect 回普通 session。
- Orca worker redirect 到 lead。
- 同 workdir session tabs。
- file tabs open/close/reorder。
- dirty save/discard/cancel。
- chat rail resizable/collapsible。
手机 V1B 只读方案:
- 从 session 进入 Files。
- 文件树是 stack page。
- 文件内容全屏预览。
- chat rail 不并排,改为底部“回到会话”或分屏切换。
- file tabs 显示为顶部横向 tabs 或最近文件列表。
- session tabs 显示为“同目录会话”列表。
- dirty/edit/save/conflict 全部 V2。
11.2 FileBodyView
桌面支持:
- empty。
- text markdown/code/plain。
- image。
- PDF/drawio/binary unsupported。
- search。
- edit mode。
- auto save / dirty / external change。
- Ctrl/Cmd+S。
手机 V1B:
- text/code 只读,代码横向滚动。
- markdown 只读预览。
- image 预览。
- binary unsupported card。
- search 可 V1B。
- edit mode V2。
12. 自动化 / 计划(桌面事实与手机历史设计)
本节手机管理方案均已退役,不作为当前实现、后续排期或验收要求。桌面行为和已有任务运行历史不受影响。
12.1 SchedulerPage
桌面计划页真实行为:
- master-detail。
selectedId会根据 focus/pending/current/first 维护。- 切换 schedule 时
RunHistoryPane不 remount,避免空白跳变。 - 不靠轮询,靠 schedule event refresh。
statusFilteractive 包含 active + expired,paused 分开。- 排序: active/expired 优先,paused 其次,再按
lastFiredAt、updatedAt。 - run now。
- pause/resume,有 inflight confirmation。
- create/edit dialog。
- project automation clone/promote/reload/upsert/remove。
手机实现:
- Automations 首页为任务列表。
- Detail page 显示任务配置和运行历史。
- 切换任务保留旧历史直到新数据到达,避免白屏。
- active/paused/expired 分段筛选。
- run now、pause/resume、delete 放在 detail action menu。
- project automation 高级管理先只读或 V2。
12.2 TaskListPane
桌面任务分组:
- workingDir group。
- dialogue group。
- other group。
- project group actions: create/open config/reload。
- user/project schedules 的 action route 不同。
手机实现:
- 按 Project / Dialogue / Other 分组。
- 每条显示 name、next run、last run、status、agent/model、workdir。
- project automation 显示“项目自动化”标签。
- create/open config/reload V1B/V2,不要 V1A 挤进主闭环。
12.3 RunHistoryPane
桌面运行历史:
- schedule 切换时先保留旧 runs。
- 同一个 sessionId 的重复 run 会 fold。
- mark attention read。
- runNow/edit/pause/delete。
- delete run。
- restart interrupted。
手机实现:
- history list。
- 每个 run 展示时间、状态、session title、错误摘要、费用/时长。
- 点 run 跳到对应 session。
- failed/interrupted 提供 retry/restart。
- fold 重复 session run。
12.4 ScheduleFormDialog
桌面创建/编辑字段:
- create/edit/project automation mode。
- blank/template segmented。
- template gallery / params。
- name。
- schedule: cron/manual/once。
- run mode: fresh/persistent/bound。
- agent/model/effort/fast。
- notify。
- worktree。
- project chip。
- fast 只在 model 支持时可切。
- bound 隐藏 workspace fields。
手机 V1B:
- 基础 create/edit 支持 name、schedule、prompt、agent/model/effort、run mode。
- template gallery 作为独立 step。
- cron 输入需要预设 + raw cron advanced。
- worktree/project automation 高级字段可后置。
13. 协作 / Orca
桌面源码说明协作不是一个开关:
ExtraDirsButton中的协同模式项只是 controlled 入口。OrcaSplitView承载 lead + worker 双会话。- workerRatio 持久化。
- split/toggle layout。
- max pane。
- create worker popover。
- worker toolbar。
- worker focus。
- archive worker。
- stop collaboration。
- attention clear。
orcaWorkflowsFor区分 local/remote。CreateWorkerPopover有 role/custom role、agent tabs、model/effort/fast、initial task、记忆偏好。useWorkers依赖 listWorkersByLead 和ORCA_WORKER_CHANGED刷新。
V1 策略:
- 会话列表识别 lead/worker。
- 打开 worker 时给只读提示,提供“回到主会话/lead”。
- 普通消息流仍能展示,但不提供 create worker、focus、split、archive worker、stop collab。
- 不允许手机端误把 worker 当普通 session 做破坏性操作。
V2 需要单独设计:
- 手机端如何在 lead 和多个 worker 间切换。
- worker focus 的移动交互。
- create worker 表单。
- stop collaboration 的风险确认。
- worker attention 聚合。
14. 远程传输和权限边界
14.1 makerTransport
makerTransport.ts 的关键结论:
makerApiFor(sessionId)根据 session 是否远程选择 local/remote。- remote 支持 send、setModel、setEffort、setPermissionMode、setFastMode。
- remote 支持 resolveInteraction、getPendingInteractions。
- remote 支持 fork、rewind、context、extraDirs、closeSession。
- remote 支持 enable/disableOrca/input queue。
- remote 支持
getSessionFor,listMessagesFor,aroundMessagesFor。 orcaWorkflowsFor单独路由 Orca API。
手机实现:
- 建一个 typed mobile client,不要在组件里散落 string invoke。
- 每个 invoke 统一 timeout、错误码、重试、revoked/offline 映射。
- 对 session 级别操作全部带
deviceId/sessionId。 - 对 Orca API V1 只读或禁用。
14.2 Controlled dispatch
dispatch.ts 被控侧规则:
- 处理
link-open/close/invoke。 - 管理 subscription registry。
- topic-scoped push。
- 二次检查
remoteControlEnabled。 - 检查 revoked controllers。
- 检查 allowlist。
maker:create-session有 workingDir guard。- remote set model/effort/permission/fast 会回写 DB 并 broadcast。
手机验收:
- remote disabled 时所有控制动作都显示明确错误。
- controller revoked 后立即回到设备不可控状态。
- set model/effort/permission/fast 后桌面和手机列表都同步。
- create session 不能绕过电脑端 workingDir guard。
14.3 Allowlist
当前 allowlist 允许:
- agent lifecycle。
- input queue。
- interactions。
- runtime settings。
- capabilities。
- DB reads。
- patch meta。
- media/voice。
- scheduler。
- project automation。
- Orca。
- rewind/fork/context。
- usage。
- memory read。
- command/skill list。
- scan-at。
- plugin list。
- fs browse/stat/mkdir。
- text-file preview。
明确不应暴露给手机:
- window/UI 本机控制。
- shell / open external。
- account/global settings raw writes。
- local-db raw writes。
- updater。
- skillhub writes。
15. 自动化测试和调优
15.1 单元测试
优先补这些纯函数/状态测试:
- raw messages -> render items。
- tool/result pairing。
- media payload extraction。
- todo extraction。
- queue reorder index conversion。
- pending interaction decision shape。
- remote error mapping。
- schedule grouping/sort。
- Orca lead/worker safe degrade。
15.2 集成测试
需要一个本地三件套 harness:
- local relay/server mock。
- controlled desktop mock 或真实 desktop dev。
- mobile app。
覆盖:
- mock login。
- 设备上线。
- session list reseed。
- session detail subscribe。
- send message。
- streaming update。
- permission resolve。
- ask user resolve。
- plan approve/feedback。
- issue confirm/cancel。
- queue edit/reorder/continue。
- host offline/reconnect。
15.3 原生 E2E
目标工具:
- iOS Simulator。
- Android Emulator。
- Maestro 或 Detox。当前如果 Maestro CLI 不可用,先保留 smoke script 和 checklist。
核心用例:
- 登录 mock account。
- 看到本机电脑。
- 进入会话列表。
- 打开已有会话。
- 发送一条消息。
- 被控桌面收到消息并更新同一 session。
- 手机收到 assistant 流式消息。
- 触发 permission,手机 allow once。
- 触发 ask user,手机回答。
- 触发 plan review,手机 approve。
- 切后台再回来,订阅恢复。
- 断开桌面,手机显示 offline。
- 桌面恢复,手机 resync 后不丢状态。
15.4 视觉和性能
视觉基线:
- 对齐桌面黑白反色、低装饰、信息密度高的设计语言。
- 手机不做营销式 hero。
- 卡片只用于消息、工具、modal、列表项,不要卡片套卡片。
- 所有长文本、长路径、长按钮文案必须在小屏不溢出。
性能基线:
- 1000+ render items 会话可滚动。
- 远程 streaming 每秒多次更新时不重建全列表。
- 图片/视频懒加载。
- payload lightbox 延迟解析长 JSON。
- reconnect reseed 不造成整屏跳变。
调优指标:
- session list 首次可交互时间。
- session detail 首屏 message 可见时间。
- send tap 到 controlled desktop 收到 invoke 的延迟。
- streaming event 到手机渲染延迟。
- queue 操作 round trip。
- reconnect 后 resync 完成时间。
16. 实现顺序
Phase 1: 固化远程协议和测试基座
- typed mobile device-link client。
- mock login / mock account。
- local relay + desktop harness。
- remote error mapping。
- subscription lifecycle。
- smoke test 脚本。
验收:
- 不依赖飞书 secret 可本地登录。
- iOS Simulator 能看到本机 controlled desktop。
- host offline/reconnect 可复现并自动化验证。
Phase 2: 会话列表和会话详情骨架
- devices。
- sessions list。
- session detail。
- connection strip。
- message history load。
- basic send / stop。
验收:
- 手机和桌面打开同一 session,消息一致。
- running/offline/revoked 状态一致。
- 发送后桌面 session 实际收到。
Phase 3: 消息渲染 parity
- render item builder。
- assistant/user/system。
- thinking/work group/tool/todo。
- media extraction。
- payload/detail viewer。
验收:
- 用 fixture 覆盖每种 render item。
- 长工具链折叠后仍能展开查看完整输入/输出。
/contextsystem card 不丢字段。
Phase 4: Composer 和 Queue
- composer。
- model/effort/permission/fast settings。
- attachments。
- slash/@ 初版。
- pending queue sheet。
- edit/reorder/delete/continue/steer。
验收:
- running 时新输入进入 queue。
- queue 操作后桌面和手机顺序一致。
- set model/permission 后桌面 DB 和手机 UI 同步。
Phase 5: Pending interactions
- Permission。
- Ask User。
- Plan Review。
- Issue Confirm。
验收:
- 每种 interaction 的 resolve payload 与桌面源码一致。
- 提交后按钮冻结,不会重复 resolve。
- interaction 消失后 composer 恢复。
Phase 6: 非协作附属能力
- fork / rewind。
- diff。
- context/cost detail。
- file preview。
- 手机管理入口保持移除;既有任务与运行历史仍可保留。
验收:
- 非协作常用桌面能力在手机端有入口。
- 文件编辑、完整 Orca 明确降级;project automation 管理仅保留桌面端。
Phase 7: 自动化回归和调优
- render fixtures。
- local integration harness。
- iOS/Android smoke。
- performance budget。
- visual screenshots。
验收:
- 常用远程控制路径无需手工点。
- 每次改消息渲染、queue、interaction、schedule 都能跑对应测试。
17. V1 完成定义
V1 完成不是“能发消息”,而是以下条件全部成立:
- 手机能通过 mock login 和正式登录进入同账号设备。
- 手机能发现、进入、重新同步可控电脑。
- 会话列表可搜索、筛选、展示运行态和等待态。
- 会话详情能渲染桌面普通会话的所有核心 message item。
- 手机可发送、停止、排队、编辑队列、重排队列、继续队列。
- Permission / Ask User / Plan Review 都可完成;Issue Confirm 提示回桌面端处理。
- 模型、effort、permission、fast 与桌面 session 状态同步。
- fork/rewind/diff/context/cost 有移动入口或明确 V1B 完成项。
- 手机不提供 Scheduler / Routines 管理;旧链接安全跳转,已有任务和运行历史保留。
- 文件引用可查看;完整编辑器明确 V2。
- 协作 session 可识别并安全降级。
- iOS Simulator 和 Android Emulator 至少各有一条自动 smoke 路径。
- host offline、revoked、reconnect、resync 都有自动或半自动验证。