待办

优先级：

P0：第一版能跑起来的最低要求。
P1：日常工作流可用所必需。
P2：核心闭环跑通之后再补。

记录约定：

已完成的条目不要删，改成 [x]，保留实现轨迹。
一个实现任务暴露出阻塞、设计冲突或 bug 时，父条目继续保持开放状态，在其下用缩进的 sub-todo: 记录。
任何非琐碎的 sub-todo: 都要链接到 docs/problems/ 里对应的记录，让上下文和决策痕迹挂在父条目上。

2026-05-18 当前优先级队列

当前统计：共 178 个状态标记，其中 176 个完成、0 个开放、2 个取消不再追踪；当前待处理队列已清空。
P0 已清空：基础设施、terminal 主渲染/history 真相源、agent 会话生命周期、浏览器位置/路由/网络代理设置均已完成第一版验收。
P1 已清空：管理中心、workspace 体验、安全可靠性和日常工作流必需项均已完成第一版验收。
P2 当前无开放项：M2Terminal logo 与 app icon wiring 已完成第一轮接入。
不再作为当前 TODO 阻塞项：完整 libghostty Metal/GPU surface 直连属于后续 renderer backend 架构升级；旧命令面板和活跃端口显示已取消追踪。
已完成但仍要防回归的重点模块：Rust core PTY ownership、Ghostty-backed viewport/history source、AI session management、workspace browser tabs、Git diff workspace tab、tab history/workspace restore、app-owned window style。
本文件下方保留完整历史 checklist；新工作优先从本队列进入，不再从旧审计段落反向推断。

按优先级排列

Rank	Priority	Status	Area	Item	Definition of done
1	P0	None open	Release blocker	第一版最低可运行要求	无剩余开放项；只做回归保护，不从历史完成项重开任务。
2	P1	None open	Daily workflow	日常工作流必需项	无剩余开放项；只做回归保护，不从历史完成项重开任务。
3	P2	Done	Branding	M2Terminal logo	`logo.png` 与生成的 `logo.icns` 已接入 About、运行时 app icon 和 app bundle `CFBundleIconFile`，并完成视觉验收。

2026-06-30 性能扫描修复攻坚

父条目，详见 docs/problems/2026-06-30-performance-scan.md（顶部 §0.0 进度表为主清单）。

P1 性能扫描攻坚：31/43 已修复并通过 Gate 1（cargo test 全绿 / swift test 875 全绿 / scripts/build_app.sh 全绿）；Gate 2 以 app-control 聚焦走查覆盖核心断言（text.dump=ghostty-formatter、CJK 命令往返、browser.check_connection 异步不阻塞主 actor、pkill 关闭）。提交逻辑组见 scan §0.0.1。
- sub-todo: 12 条高风险 / Low 项带理由延后（见 scan §0.0.2），均为有界、非崩溃风险、需独立改造 + before/after 基准 + 专项验收的后续项：
  - P2 T1 终端每帧全量重建可见网格 NSAttributedString → 给 Ghostty 快照加 per-row dirty 协议（动 formatter 真相源，text.dump=ghostty-formatter 回归伞风险高）。
  - P2 W1 tab routing 派生属性全量重建 → 每逻辑操作算一次 layout + 在 tab mutation 上精确失效（受 maxTabs=30 有界）。
  - P2 W2 / G4 Trash 视图 / Git 侧栏文件列表未虚拟化 NSStackView → view-based NSTableView（沿用分支列表范式；分别受 100/文件数有界）。
  - P2 W4 sidebar 每按键全量 reloadData → reloadData(forRowIndexes:) 行级 delta（与 W3 缓存叠加后单次成本已降）。
  - P2 其余 Low（W8 / B7 / B8 / T6 / T7 / R6 / R7）：边际收益，逐条理由见 scan §0.0.2。
- sub-todo: 已知 flaky（非本轮引入）：crates/m2terminal-core/tests/rpc.rs 的 hooks_and_runbooks_work_via_rpc、rpc_dispatch_events_record_request_id_duration_and_error_status 在全套并行高负载下偶发失败（baseline 即偶发；隔离/单跑稳定通过）。

2026-07-01 体验质量攻坚（交互/渲染缺陷 + 自动体验验证）

父条目，详见 docs/EXPERIENCE_QUALITY_GOAL.md（§0.0 进度表为主清单）与 docs/problems/2026-07-01-experience-verification-gap.md（方法论缺口 = 为什么「修了还在」）。

P0 体验缺陷攻坚：用户报告的 4 项（切回乱像素 EXP-R1/R2 / 软换行复制硬换行 EXP-S1 / 拖选闪烁 EXP-S2 / 拼音光标跳 EXP-I1/I3）全部已修复 + 双门验收（swift test 全绿 / harness PASS=7 FAIL=0）。两次 instrumentation 推翻扫描假设（EXP-R1 真因是 atlas upload identity 非 lastScene；EXP-I1 inline 本就正确、真因是 firstRect actualRange）——印证 goal §1 论点。
- sub-todo: [x] 证明 app-control socket 可无授权驱动真机（M2TERMINAL_APP_CONTROL=1 + nc -U，绕过 [[gui-verification-blocked]] 的 computer-use 限制）；落地 harness scripts/experience-soak.sh（三态 PASS/FAIL/BLOCKED）。
- sub-todo: [x] 补 5 个 instrumentation：terminal.gpu_diagnostics（渲染计数 + outcome）、terminal.capture_pixels（离屏像素回读）、terminal.present_log（per-present 事件流）、selection.drag（网格坐标真鼠标选择）、pane.set_marked_text/unmark_text/commit_text（真 IME 合成注入）。
- sub-todo: [x] 修 4 项并把 harness 场景从 BLOCKED 升级为真 PASS：EXP-R2（atlas instanceID + 去掉 remount 重建）、EXP-S1（on-screen 拖拽走 unwrap-aware mapper）、EXP-S2（storage swap 期间静音选区通知 + 一次性结算）、EXP-I3（firstRect actualRange 报 marked range）。各带回归单测。
- sub-todo: [x] /simplify 审查验收：4 agent（reuse/simplification/efficiency/altitude）并行复审 diff；应用 3 项清理（applier 选区赋值加等值守卫消除每帧冗余 needsDisplay、删 gridSelectDragForTesting 死赋值、selectedTerminalText 合并重复 guard）；swift test 全绿、harness 复跑 PASS=7。
- sub-todo: [x] EXP-P1 多行粘贴逐行执行+尾段丢失（台账闭环后用户新报告）—— 已修复 + 双门验收（2026-07-02）。根因 paste(_:) 裸发字节（不查 DECSET 2004 / 不包 ESC[200~/201~ / \n 不转 \r）；修复 = 绑定 dylib 现成 ghostty_terminal_mode_get+ghostty_paste_encode 走 mode-aware 编码（+纯 Swift fallback），「发送到 pane」链穿 asPaste 同走编码器并删 browser 无条件包裹（反向孪生 bug），PtySession.write 部分写丢尾改 poll 重试。新 instrumentation #11（pane.paste 真 pasteboard 路径 + terminal.bracketed_paste 探针）；harness 新增 E15（修前 FAIL"paste executed before Enter"、修后原子性+字节保真双 PASS），E13 顺手改自清理（恢复初始 workspace）。swift test 895/0（+9 测）、experience-soak.sh --once = PASS=23 FAIL=0 BLOCKED=0。见 goal §4.G、docs/problems/2026-07-02-multiline-paste-fidelity.md。
- sub-todo: [x] P1/P2 体验台账全闭环 + harness 零 BLOCKED（2026-07-02 收官）。§4 每个 EXP-* 项均落地：真修 9（R1/R2、S1、S2、I1/I3、拼音频闪、B1、T1、T2、G1、S4，各带 harness 修前FAIL修后PASS + 单测）、证伪 12（T3/T4/G2·G3/G6/T6/B7/T5/S6/B4/I7 + 早期 R1/I1，instrumentation/代码追踪证据在案 + 回归守卫）、吸收 1（S5←S1）、NEEDS-HUMAN §6.5（IME 候选窗、I2、R3、B2·B3·B5、I4·I5·I6、B6·B8·B9、T7、S3、G4、G5——均写明为何 headless 不可验 + 真机验收步骤 + fix 方向）、deferred §6.6（R4 结构类专项、R5..R8 内存/部分重绘 latent）。harness 终态 PASS=21 FAIL=0 BLOCKED=0、swift test 884/0。下方各 P2 子项即逐项证据。剩余非 headless 待办 = §6.5 人工验收清单 + §6.6 后续专项（均已显式列举、非本闭环范围）。EXP-S1 深层项（屏外 scrollback 拖拽仍走 formatter 不 unwrap，待统一两个抽取器）另立 goal §4.B 显式条目跟进。
  - sub-todo: [x] P2 EXP-S4 选到内容下方空行带多余换行 —— 已修复 + 双门验收（swift test 883/0；harness 新增 E11 拖进空行尾随换行=0，修前 row1→row16 尾随 11、修后 0）。selectedText 对齐 spans（同在 lastSelectableRowOffset break + 边界）。experience-soak.sh --once=PASS=17 FAIL=0 BLOCKED=0。见 goal §4.B。
  - sub-todo: [x] P2 EXP-G6 极窄 pane 列数 1↔80 抖动 —— 实测证伪（NSSplitView min-thickness + 窗口 min 内容尺寸把 viewport 宽钉在远高于 1，80×24 fallback 不可达；divider 拖 998pt 列恒 29、窗口 60pt viewport 仍 299pt）。加 harness 守卫（小窗口列 clamp 到 31 非 80）。experience-soak.sh --once=PASS=18 FAIL=0 BLOCKED=0。见 goal §4.E。
  - sub-todo: [x] P2 EXP-T6 后台 resize 后切回 grid stale —— 实测证伪（切回时 view 重布局 + viewDidAppear 的 resizePty 读到新 gridSize 正常 resize；1200w→560w 后台切回列数正确跟到新窗宽非 stale）。加 harness 守卫 E12（自比较同一 tab 前后列数）。experience-soak.sh --once=PASS=19 FAIL=0 BLOCKED=0。见 goal §4.D。
  - sub-todo: [x] P2 EXP-B7 拖入 - 文件名选项注入 —— 可达性证伪（format(urls:) 只喂 file URL 的绝对 path，恒以 / 开头，三处 caller 全走它；扫描假设的相对文件名 file URL 不产生）。无 socket 路径，单测守卫安全不变量。swift test 884/0。见 goal §4.F。
  - sub-todo: [x] P2 EXP-S5 pin-vs-mapper 可见选区文本分歧 —— 已被 EXP-S1 修复吸收（S1 让完全在屏选区只走 mapper 一条路径，无分歧；socket 实测含内部空格行拖选复制字节一致）。残留屏外 scrollback formatter 是 §4.B 已列 S1 深层项。可见路径一致性由 E3/E11 守卫。见 goal §4.B。
  - sub-todo: [x] P2 EXP-I2 合成中途 overlay 锚 transient cursor —— → NEEDS-HUMAN（append_output 会把光标推到新行，overlay 正确跟 settled 光标非 transient；无法模型「compose 时 shell 流式输出 prompt 留底部」，transient 光标只在真 TUI 重绘出现，headless 不可忠实复现）。归 goal §6.5 人工验收清单。差点上假断言，查证 FAIL 后撤掉。
  - sub-todo: [x] P2 EXP-T5 workspace 缓存子 VC 泄漏 —— 实测证伪（补 workspace.children_count 探针，真机切 workspace 触发 detachForCaching，子 VC 数稳定在 3、连切 10 次恒 3 不增长）。harness 守卫 E13（8 次切换增量≤2）。swift test 884/0，experience-soak.sh --once=PASS=20 FAIL=0 BLOCKED=0。见 goal §4.D。
  - sub-todo: [x] P2 EXP-S6 no-move click 清选区不清 GPU mirror —— 代码追踪证伪（gridSelectionEnd 无移动分支 gridSelectionClear() 后紧接 setSelectedRange({0,0}) 同步 fire onSelectedRangeChanged → metalGridView.setSelectionRange({0,0})，mirror 同一调用栈清空无残留；扫描漏了 setSelectedRange 路径）。no-move click 无 socket 原语，构造级同步保证，据代码追踪归档。见 goal §4.B。
  - sub-todo: [x] P2 EXP-R3..R8 渲染簇成簇归类 —— R3（backing-scale 双读，单屏两读恒同、触发需第二屏）→ §6.5 NEEDS-HUMAN；R4（多入口每 turn 多 present）= deferred-structural（render-model 类修复，是拼音频闪深层类修复，留专门一轮，§6.6）；R5（framebufferOnly readback 已被 #1 解除）+ R6..R8（内存 purge 无重建路径，harness 造不出）→ deferred-latent（§6.6）。见 goal §4.A/§6.5/§6.6。
  - sub-todo: [x] P2 EXP-B2/B3/B5 浏览器/启动视觉簇 —— 均高信心真 bug 但 headless 不可验（B2 WKWebView 白闪真 compositing、B3 系统光标、B5 启动瞬间窗口跳）→ §6.5 NEEDS-HUMAN，带 fix 方向留真机验收 + 未来专项。见 goal §4.F/§6.5。
  - sub-todo: [x] P2 EXP-I4/I5/I6 IME 合成视觉簇 —— 均合成期视觉 + 真焦点（I4 第二 caret、I5 predicted echo 时序、I6 真失焦提交）；headless set_marked_text 只验 app 侧不变量（E5 已覆盖 block-cursor 抑制 + markedRange），真 IME 会话不可 emulate → §6.5 NEEDS-HUMAN，带 fix 方向。见 goal §4.C/§6.5。
  - sub-todo: [x] P2 EXP-B4 软换行 URL 下划线断裂 —— socket 实测证伪（补 terminal.url_hover+terminal.url_underlines，窄窗跨 3 行 URL rangeCount=1 单条连续；mirror 把软换行当一条逻辑行）。harness 守卫 E14，experience-soak.sh --once=PASS=21 FAIL=0 BLOCKED=0。见 goal §4.F。
  - sub-todo: [x] P2 EXP-I7 可见-未聚焦 pane 渲染抢主线程 —— 代码追踪证伪（render() 门控是正确可见性判据：detached pane 完全跳过=O(visible) + damage tracking 跳重复帧；可见 pane 渲染是对的，对标 ghostty/iTerm2；扫描"未聚焦不该渲染"前提错）。残留同步渲染争主线程是固有边界，彻底消除需 off-main-thread=§7 non-goals。见 goal §4.C。
  - sub-todo: [x] P2 EXP-G1 divider 拖拽 PTY-resize 风暴 —— 已修复 + 双门验收（swift test 883/0；harness E4 divider 从 BLOCKED 毕业，11 步拖动 winsize +5→+1）。落 #8 terminal.pty_resize_count+divider.step；resizePty 拆同步视觉 + 子 PTY winsize 32ms 防抖合并。experience-soak.sh --once=PASS=16 FAIL=0 BLOCKED=0（harness 首次零 BLOCKED）。见 docs/problems/2026-07-02-divider-drag-pty-resize-storm.md。
  - sub-todo: [x] P1 EXP-B1 关内嵌 browser pane 丢焦点 —— 已修复 + 双门验收（swift test 882/0；harness 新增 E6 PASS，experience-soak.sh --once=PASS=9 FAIL=0）。落地 instrumentation #6 window.first_responder + browser.open_embedded/browser.focus_embedded/pane.close_active；下沉共用 closeEmbeddedBrowser() 同时修 Cmd-W 与 X 按钮两条路径。见 docs/problems/2026-07-01-browser-close-focus-loss.md。
  - sub-todo: [x] P1 EXP-T3 切 tab 焦点落空 —— 扫描假设经 #6 证伪（终端 tab 选择焦点走两道 viewDidAppear+focusActivePane 且都 window-present，6 次切换 first responder 恒为终端）；无生产代码修复，加 harness 回归守卫 E7 tab-switch-focus（现即 PASS）。见 goal §4.D。
  - sub-todo: [x] P1 EXP-T1 tab.snapshot 多个 isActive —— 已修复 + 双门验收（swift test 882/0；harness 新增 E8 修前计数 2→修后 1，experience-soak.sh --once=PASS=11 FAIL=0）。窄修 tabSnapshot() 用选中 group 唯一全局 active id（不动被生产选择器消费的跨 group paneSummaries）；顺手加固 E1 冷启动 baseline 竞态。见 goal §4.D。
  - sub-todo: [x] P1 EXP-T2 多 pane tab 重挂载 active pane 跳 —— 已修复 + 双门验收（swift test 882/0；harness 新增 E9 修前跳→修后留，experience-soak.sh --once=PASS=12 FAIL=0）。只有 active pane 才 appear 时抢焦点（claimsFocusOnAppear 逐 pane 判断，跨 TerminalViewController/chrome/group 三层接线）；补 pane.split/pane.focus 驱动。见 docs/problems/2026-07-02-active-pane-jumps-on-tab-remount.md。
  - sub-todo: [x] P1 EXP-T4 mount thrash —— 「重选/风暴」经 #10 证伪（重选被 store.select guard；每次 mount 都先改选中 tab；8 类操作实测无冗余重挂载）。顺手补 mounter 幂等 defense-in-depth（单测证同视图连挂 2→1+skip）+ harness 守卫 E10 + E1 冷启动改 poll-until-atlas-built。swift test 883/0，experience-soak.sh --once=PASS=13 FAIL=0。见 goal §4.D。
  - sub-todo: [x] P1 EXP-G2/G3 resize/按键丢滚动锚点 —— 扫描假设经 #7 证伪（ghostty C 引擎已保留 viewport pin，resize 不跳；输入滚到底=标准正确行为；输出跟随已正确抑制）。落 #7 terminal.viewport_top+terminal.scroll，把 E4 resize-anchor 从 BLOCKED 毕业为 2 条真断言。swift test 883/0，experience-soak.sh --once=PASS=15 FAIL=0 BLOCKED=1（仅剩 G1）。见 goal §4.E。P1 全部收官：3 修 3 证。

2026-07-14 全项目审查修复（渲染/IME/性能）

父条目，详见 docs/problems/2026-07-14-project-audit-fixes.md（五维审查 ≥80 置信度的六项发现逐项修复，每项独立 commit + 双门验收）。

P2 OSC 133 semantic prompt（shell integration）：命令高亮的 prompt 定位目前是终结符启发式（% /$ /# /❯ /> ，审查修复 4 的临时方案，agent TUI 激活时跳过）。正解 = OSC 133 A/B 标记 + shell integration 脚本（Ghostty/iTerm2/kitty/WezTerm 同款机制），需要 vt shim 透出 per-row semantic prompt 状态；落地后删除启发式。

历史复审记录

2026-05-13 架构优化复审

本地 .build/libghostty-vt runtime 已可用，SwiftPM/dev 启动默认请求 Ghostty-backed renderer；swift test --filter TerminalMVPTests 全量通过。
普通 app pane 的 PTY ownership 已切到 Rust core 优先，active Ghostty 下的文本查询已切到 libghostty-vt formatter。
修复 app 首次打开 terminal pane 早于 Rust core socket ready 导致的短暂 core PTY failed 闪屏，CorePtySession 对启动期临时连接错误做短重试。
当前剩余差距不是 VT 语义接入，而是完整 libghostty Metal/GPU renderer 直连、Ghostty-backed history 真相源和真实 terminal 兼容性矩阵。（2026-05-18 复审后：Ghostty-backed history 真相源和兼容性矩阵已收口；Metal/GPU renderer 直连保留为 P0 之后架构升级。）
问题记录：docs/problems/2026-05-13-architecture-optimization-audit.md；docs/problems/2026-05-13-core-pty-and-ghostty-truth-source.md。

2026-05-12 TODO 状态复审

当时统计：共 175 个 checkbox 条目，167 个完成，8 个开放。
只核对当前代码和现有测试，不做功能实现；已有未提交代码改动保持不动。
可以确认已落地但缺少完整 app acceptance 记录：terminal 空输入点击光标修复、terminal 宽度几何修复、app 内 browser split shell。对应条目已补状态备注；只有空输入点击这一项因问题记录已有 Resolution 且 targeted scripted validation 通过，改为完成。
当时仍开放：Ghostty 主渲染/scrollback 真相源收口、terminal 宽度真实 app 对照、terminal 兼容性矩阵、browser split 真实 terminal-click 验收、browser 网络/代理设置、M2Terminal logo。
本次验证：swift test --filter WorkspaceExperienceTests/testTerminalWorkspaceGroupOpensBrowserInsideActiveTabSplitPane 通过；swift test --filter TerminalMVPTests/testTerminalTextViewPlainClickDoesNotMoveTerminalCursor、testTerminalGeometryNeverAllocatesColumnsPastViewportWidth、testTerminalGeometryDoesNotForceTwentyColumnsInNarrowPanes、testTerminalTextViewUsesExactGridWidthWithoutFragmentPadding 通过。swift test --filter TerminalMVPTests 全量失败在强制 Ghostty renderer 的 3 个用例；当时测试环境 libghostty-vt runtime 不可用，相关 snapshot tests 被 skip，但 controller 级 Ghostty renderer tests 没有自动 skip，需后续修正测试前置条件或补 runtime。

2026-05-05 TODO 状态审计

当前统计：共 161 个 checkbox 条目，112 个完成，49 个开放；开放项包含未开始、阻塞中、以及已有部分实现但未通过完整验收的任务。（2026-05-12 复审已有新统计，见上。）
完成：P0 基础设施、基础 PTY shell、基础 agent 生命周期、基础浏览器位置、管理中心基础能力、安全可靠性、自动化基础、agent context routing 基础能力、打包/更新等已保留为完成项。
未完成：libghostty 真正接入、terminal 兼容性矩阵、app 内浏览器 split pane、内置浏览器网络/代理设置、workspace/tab 垃圾箱、M2Terminal logo、App menu 完整重做、所有 app-owned window 风格统一、完整国际化、accessibility 完整走查等仍是开放项。
没完成好：分屏、app 内浏览器 split pane、workspace 侧栏打磨、Git 变动阅览、workspace shell dark-mode 一致性、部分窗口样式、pane 布局预设、国际化都已有部分实现，但当前状态不满足完整验收；对应父项已在本次审计中改回开放状态或补了备注。
已取消/不再追踪：状态栏旧辅助入口（ports、attention、quick switcher、command palette、Search Terminal Output）后续已按产品方向删除；TODO 中仅保留历史实现记录，不代表当前 UI 仍应存在。

P0：基础设施

P0：终端原型

P0：Agent 会话生命周期

定义支持的 agent 类型：Codex、Claude Code、通用命令。
在选中的 workspace 里启动 Codex。
在选中的 workspace 里启动 Claude Code。
跟踪进程状态。
跟踪 cwd、命令、启动时间、退出码。
显示一个会话是 running、exited 还是 waiting for attention。
App 重启后保留会话元数据。

P0：浏览器位置

加 WKWebView pane。
支持把浏览器开在右侧。
支持把浏览器开在底部。
支持把浏览器开在新的 app 窗口。
支持用系统默认浏览器打开 URL。
把浏览器位置按 workspace 持久化。
支持在当前 workspace 内以一等 tab 打开内置浏览器；显式 New Browser Tab、app-control browser.open、以及 WKWebView target=_blank / window.open 会追加新的 browser tab，不替换旧 tab，且 browser tab 不计入 terminal tab 上限。2026-05-15 验证：swift test --filter WorkspaceExperienceTests/testTerminalWorkspaceGroupOpensBrowserTabsInsideWorkspaceWithoutReplacingExistingTabs、testBrowserTabsCanOpenBeyondTerminalTabLimit、swift test --filter WorkspaceExperienceTests、git diff --check、scripts/build_app.sh 通过；真实 app 以 M2TERMINAL_APP_CONTROL=1 启动后，browser.open https://www.google.com/ 返回 title=Google/loading=false。2026-06-01 路由调整后，terminal URL 只有 Command-click 会打开；功能设置可选择 browser tab、browser pane 或系统默认浏览器。问题记录：docs/problems/2026-05-15-workspace-browser-tabs.md、docs/problems/2026-05-25-terminal-url-copy-and-routing.md、docs/problems/2026-06-01-terminal-url-cmd-only-browser-routing.md。
修复 app 内分屏打开浏览器功能未真正实现的问题；浏览器应能作为当前 workspace/tab 的 split pane 打开，并支持与 terminal pane 同屏布局。（功能设置可将 Command-click terminal URL 的默认目标设为 pane 或系统默认浏览器；browser pane 已补 URL 输入框、导航按钮、关闭按钮、转移到新 Tab 按钮和加载/失败状态。2026-05-12 代码复审：TerminalPaneGroupViewController.openEmbeddedBrowser 已把 right/bottom browser pane 放进当前 workspace tab，且 swift test --filter WorkspaceExperienceTests/testTerminalWorkspaceGroupOpensBrowserInsideActiveTabSplitPane 通过；2026-05-25 决策：active terminal-tab embedded split 是可配置的 terminal-origin URL open 路径；显式 New Browser Tab / app-control browser.open 继续使用一等 workspace browser tab。）问题记录：docs/problems/2026-05-03-browser-split-pane.md、docs/problems/2026-05-25-terminal-url-copy-and-routing.md、docs/problems/2026-06-01-terminal-url-cmd-only-browser-routing.md。
- sub-todo: [x] 补内置浏览器网络/代理设置：参考 cmux、VS Code、JetBrains 和 Electron 的做法，提供 terminal link behavior host allowlist、always-open-external URL rules、WKWebView 网络模式（System / explicit HTTP CONNECT proxy / SOCKS proxy / no proxy）和 Check Connection；遇到 198.18/198.19 fake-ip/TUN 场景时不要偷偷绕过用户代理策略，应让用户显式配置代理或选择系统浏览器。2026-05-18 收口：Settings/Browser 页已提供 embedded host allowlist、always-open-external rules、HTTP host allowlist、System/HTTP CONNECT/SOCKS/No Proxy 网络模式和 Check Connection；browser.settings_*、browser.route_preview、browser.check_connection app-control 动作覆盖真实 app 验收。脚本验证 swift test、git diff --check、scripts/build_app.sh 通过；真实 app 验收在 .build/M2Terminal.app 中确认 Browser 设置页可见、路由预览符合 allowlist/external/HTTP/system-browser 规则、https://example.com/ 连接检测返回 HTTP 200，且 browser.snapshot 显示 title=Example Domain、networkMode=system。问题记录：docs/problems/2026-05-03-browser-split-pane.md。

P1：管理中心

加 API Token 引用的设置区。
Token 存进 macOS Keychain。
加 Token 校验，且不把 token 值写进日志。 Management Center 加 Tokens 页；Rust core 只保存 secret_refs 元数据并提供 secret_ref.upsert/list/delete RPC，Swift 用 Keychain service dev.m2terminal.tokens 保存 token 值，校验空值和控制字符。问题记录：docs/problems/2026-05-01-api-token-keychain-management.md。
建 MCP server 注册表 UI。
加 MCP server 启动 / 停止生命周期。
建 skills 注册表 UI。
支持 per-workspace 的 MCP 启用开关。
支持 per-workspace 的 skills 启用开关。
加非密配置的导入 / 导出。 Rust core 增加 config.export / config.import RPC 和 CLI m2terminal config export/import，只导出 workspace/settings/MCP/skills/browser/export-target 等非密元数据；secret-like settings 与 MCP env 值会被跳过并返回 warnings。问题记录：docs/problems/2026-05-02-p1-reliability-data-safety.md。

P1：Workspace 体验

P1：安全与可靠性

从日志里屏蔽已知的密钥模式。
默认禁止把含密值写入生成的 agent 配置。
加 Rust core 的崩溃恢复。
加孤儿进程清理策略。 PtySession 注册所有活跃 PTY 进程组；pane 关闭 / session 重启时先按终端语义发送 SIGHUP，再用 SIGKILL 兜底，并通过 proc_listchildpids 递归清掉 shell 产生的后台子进程。app 退出时统一清理仍注册的 PTY 进程。2026-05-13 第二轮优化：普通 app pane 已改为 Rust core PtySupervisor 优先拥有 PTY 和进程组；Swift PtySession 保留为本地 fallback/test 路径。问题记录：docs/problems/2026-05-01-orphan-process-cleanup.md；docs/problems/2026-05-13-core-pty-and-ghostty-truth-source.md。
加针对死掉会话的 app 重启行为。 Rust core 增加 session.recover_stale，App 启动 core 后会把无 PID 或 PID 已不存在的 running 会话标记为 exited，并记录 session.recovered_stale 事件。问题记录：docs/problems/2026-05-02-p1-reliability-data-safety.md。
加配置校验，错误信息要清晰。 workspace、MCP、skills、export targets、secret refs、settings 统一走文本/path/env/settings 校验；RPC 将校验失败映射为 invalid_params，错误里包含具体字段。问题记录：docs/problems/2026-05-02-p1-reliability-data-safety.md。
加 workspace 元数据的备份 / 导出路径。 config.export --path 会创建父目录并写出 JSON 备份；config.import --dry-run 可先预览 counts/warnings，正式导入按 workspace 名称映射并重建关联。问题记录：docs/problems/2026-05-02-p1-reliability-data-safety.md。

P2：自动化

暴露本地 Unix socket API。
加 CLI 包装。
加打开 workspace 的命令。
加启动 agent 的命令。
加向 pane 发送文本的命令。
加按位置打开浏览器的命令。
加进程完成 / 需要关注事件的 hook 系统。 Core 增加 hook.upsert/list/delete/run.list RPC 与 CLI m2terminal hook ...；支持 session.exited / session.attention，hook command 通过环境变量拿 session 元数据，执行记录写入 hook_runs。问题记录：docs/problems/2026-05-02-automation-hooks-runbooks-packaging.md。
加可重复工作流的 runbook 格式。 JSON v1 runbook 支持 workspace.open / agent.start / pane.send_text / browser.open 步骤，runbook.enqueue 可 dry-run 或批量写入 automation queue；CLI 为 m2terminal runbook run --path ...。文档：docs/RUNBOOKS.md。

P2：进阶 agent 工作流

把选中的终端输出路由给 agent。 Edit 菜单加 "Send Selection to Pane"，默认 ⌘⇧Return（可改 Shortcut.SendSelectionToActivePane）。在任一 pane 选中文本后，触发即弹出目标 pane picker；只有一个 pane 时直接 write 到该 pane 的 PTY。无选区时菜单灰、按键 beep。（审计备注 2026-05-05：文档里的 Edit 菜单路径已过期，当前菜单重组后需要在 App menu 审计中重新确认入口归属。）
- sub-todo: [x] 加目标 pane 选择器（弹出 picker 列出所有 pane 的 kind/label，让用户挑发往哪个），不再仅限于 active pane。问题记录：docs/problems/2026-05-01-agent-context-target-pane-picker.md。
把浏览器 URL / 页面摘要路由给 agent。 BrowserPlacementCoordinator 持有 currentBrowser 指向最近一次打开的 BrowserViewController；BrowserViewController 暴露 currentURL 和 capturePageSummary(_:)（后者跑 document.title + body.innerText JS，主线程回调）。Edit 菜单加两条 "Send Browser URL to Pane" / "Send Browser Summary to Pane"，没有内置默认快捷键，但有 Shortcut.SendBrowserUrlToActivePane / Shortcut.SendBrowserSummaryToActivePane 两个 UserDefaults key 可绑。无浏览器开着时菜单灰。（审计备注 2026-05-05：文档里的 Edit 菜单路径已过期，当前菜单重组后需要在 App menu 审计中重新确认入口归属。）
- sub-todo: [x] 给 summary 加可配置的字符上限 / 选区裁剪策略。Management Center 的 Agent Env 页可配置 BrowserSummary.MaxChars 与 BrowserSummary.SelectionStrategy，支持 prefer-selection / full-page / selection-only。问题记录：docs/problems/2026-05-01-browser-summary-capture-controls.md。
- sub-todo: [x] 浏览器 url 改变时刷新 currentBrowser 元信息（目前只取 init 时记录）。BrowserViewController 观察 WKWebView.url/title 并回调 coordinator，standalone window 标题随当前页面刷新。问题记录：docs/problems/2026-05-01-browser-current-metadata-refresh.md。
给 agent 会话挂文件或目录附件。 File 菜单加 "Attach Files / Folders to Pane…"（默认无快捷键，可绑 Shortcut.AttachFilesToActivePane）。点击弹 NSOpenPanel，允许文件 + 目录、多选；提交后把每个 URL 的 .path 用 BrowserWorkspaceViewController.shellQuote 单引号转义、空格拼接、补尾随空格，再弹目标 pane picker 写到选中 pane 的 PTY。（审计备注 2026-05-05：文档里的 File 菜单路径已过期，当前菜单重组后需要在 App menu 审计中重新确认入口归属。）
- sub-todo: [x] 终端 pane 接受 Finder drag-and-drop 文件，也走相同的格式化路径。问题记录：docs/problems/2026-05-01-terminal-file-drag-attachments.md。
加 per-agent 的环境模板。 Management Center 加 "Agent Env" 页，支持 Codex / Claude Code / generic 的 JSON 环境模板；CLI env-template set 与 Swift 运行时都校验 key 形状和值类型，自动以 env KEY='value' ... 前缀应用到 automation 启动的 agent。问题记录：docs/problems/2026-05-01-agent-env-templates.md。
加会话标签与置顶。 Session schema / RPC 增加 label、tags、pinned；quick switcher pinned 优先并显示标签，状态栏提供 "sessions/pinned N" 入口编辑 label、逗号分隔 tags 与 pinned 状态。（审计备注 2026-05-05：quick switcher 与 sessions/pinned N 旧状态栏入口后续已删除；底层 session metadata 能力保留。2026-05-06 重建为 Sessions > Edit Session Label & Tags... picker→editor 流程 + Sessions > Pinned Sessions picker;tab strip 行级 📌 / [label] 渲染作为后续工作另列。问题记录：docs/problems/2026-05-06-b-class-rebuild.md。）
加跨会话输出搜索。状态栏和命令面板增加 "Search Terminal Output"，跨当前 workspace 的所有 tabs/panes 搜索可见终端输出，结果 picker 展示匹配片段并可跳回 pane。（审计备注 2026-05-05：Search Terminal Output 用户入口后续已按产品方向删除；底层 searchTerminalOutput helper 仍在。2026-05-06 重建为 Sessions > Search Terminal Output 菜单 + 默认 ⌘⇧F,WorkspacePickerWindowController 增加 enableLiveSearch 模式按 keystroke 重新调 helper。问题记录：docs/problems/2026-05-06-b-class-rebuild.md。）
加 agent 事件时间线。 Core 增加 session_events 和 session.timeline RPC，自动记录 session start / status change / metadata update；状态栏和命令面板提供 "Agent Event Timeline" picker。（审计备注 2026-05-05：命令面板入口后续已删除；当前只保留 status bar / picker 路径,是否继续保留需要随新 App menu 一起验收。2026-05-06 在 Sessions > Event Timeline 菜单加薄 wrapper 转 status bar 的 showAgentTimeline,空 events 现在显示"无事件"占位行而不再 beep 退出。问题记录：docs/problems/2026-05-06-b-class-rebuild.md。）

P2：打磨

搁置：Agent 配置导出

加 per-agent 的 MCP servers 与 skills 导出开关。
从 M2Terminal 配置生成 Codex 兼容的 MCP / skills 配置。
从 M2Terminal 配置生成 Claude Code 兼容的 MCP / skills 配置。 MCP 端：按 agent / workspace 范围筛选启用项，Codex 渲染为 config.toml 风格 TOML，Claude Code 渲染为 {"mcpServers": {...}} JSON，写入目标路径并附 SHA-256 checksum 入历史表。 Skills 端：把启用的 skill 在 <target_dir>/skills/<name> 处建符号链接指向 Skill.source_path；找不到 source 的发 warning 跳过。入口：RPC export.run {id, workspace_id?, dry_run?} 与 CLI m2terminal export run --target-id N / m2terminal export run-agent --agent-kind codex|claude-code --target-path PATH（实现：crates/m2terminal-core/src/export.rs）。
- sub-todo: [x] 加 per-workspace 的导出范围，不只导全局。
- sub-todo: [x] 与 P1 "Prevent secret values from being written" 串起来：把 env_refs 里的 $secret:* 引用替换或剔除。
写出生成的 agent 配置之前先做 dry-run 与 diff 预览。
检测生成的 Codex 或 Claude Code 配置文件被手动改动后的漂移。
加导出指定 agent 目标配置的命令。
MCP CRUD 收口为“名称 + 创建后不可变唯一标识 + stdio JSON 配置”模型，Codex / Claude Code 导出使用唯一标识作为外部 key，并补 Playwright MCP 真实配置 smoke 脚本。问题记录：docs/problems/2026-05-19-mcp-json-crud-agent-export.md。

FilesExpand file tree

TODO.md

Latest commit

History