From 780a4a4483ebed3c8a3324ce7904704f1d01b7d1 Mon Sep 17 00:00:00 2001
From: Cooper-X-Oak <Cooper-X-Oak@users.noreply.github.com>
Date: Sat, 2 May 2026 05:15:32 +0800
Subject: [PATCH] docs(tracking): add windows clipboard restore handoff

---
 ...ssue-windows-terminal-clipboard-restore.md | 77 +++++++++++++++++++
 .../pr-windows-terminal-clipboard-restore.md  | 70 +++++++++++++++++
 2 files changed, 147 insertions(+)
 create mode 100644 docs/github-tracking/issue-windows-terminal-clipboard-restore.md
 create mode 100644 docs/github-tracking/pr-windows-terminal-clipboard-restore.md

diff --git a/docs/github-tracking/issue-windows-terminal-clipboard-restore.md b/docs/github-tracking/issue-windows-terminal-clipboard-restore.md
new file mode 100644
index 00000000..6a89f60f
--- /dev/null
+++ b/docs/github-tracking/issue-windows-terminal-clipboard-restore.md
@@ -0,0 +1,77 @@
+## 现象 / Symptom
+
+Windows 终端文本输入场景里，用户曾观察到这样一类问题：
+
+- 光标位于终端输入行
+- 触发 OpenLess 听写
+- 会话结束后，目标最终拿到的不是本次识别/润色后的文本
+- 体感像是 OpenLess 先把本次结果写进剪贴板，随后又恢复成听写前的旧剪贴板，导致目标实际 paste 的是旧内容
+
+### 证据 / Evidence
+
+- `openless-all/app/src-tauri/src/insertion.rs`
+  - Windows 路径把 synthetic paste 视为 `PasteSent`，旧实现会在固定 `150ms` 后恢复旧剪贴板
+- `docs/2026-05-02-windows-terminal-clipboard-restore-investigation.md`
+  - 已沉淀完整隔离实验、真实目标回归与整链路自动化证据
+- 隔离时序实验已确认 race 模型存在：
+  - 快消费者 + `150ms` restore：通过
+  - 慢消费者 + `150ms` restore：读到旧剪贴板
+  - 慢消费者 + `750ms` restore：恢复正常
+- 稳定化完整生命周期自动化已覆盖：
+  - `wt-cmd`
+  - `wt-powershell`
+  - `notepad`
+- 当前机器上的稳定化整链路回归结果：
+  - 三类目标都收到本次 `finalText`
+  - 三类目标都没有收到旧剪贴板哨兵值
+
+### 5 Whys / 根因分析
+
+1. 为什么会怀疑是 clipboard lifecycle 问题？
+   - 因为 `PasteSent` 只能证明发出了 synthetic `Ctrl+V`，不能证明目标已经消费完 clipboard。
+2. 为什么固定 `150ms` restore 有风险？
+   - 因为较慢的目标会在 restore 之后才读取 clipboard，于是会读到旧内容。
+3. 为什么用户会在 terminal 里感知到这个问题？
+   - terminal 是最容易怀疑的目标类型，但当前证据说明它不是“必现目标”，而是可能触发 race 的一种环境。
+4. 为什么现在不能把问题定义成“Windows terminal 通用必现”？
+   - 因为稳定化整链路自动化下，`wt-cmd` 和 `wt-powershell` 当前都没有复现该问题。
+5. 现阶段最合理的结论是什么？
+   - race 模型真实存在，但用户报告的问题具有条件性，还依赖额外环境因子。
+
+### 平台边界 / Platform Scope
+
+- 直接范围：Windows
+- 关注层次：`clipboard lifecycle`、`insertion lifecycle`
+- 非主因：`focus restore`
+- 当前判断：不是“所有 Windows terminal 一定复现”，也不是单纯的全局 Windows clipboard bug
+
+### 认领 / Ownership
+
+- owner intent：`@Cooper-X-Oak`
+- 当前对应 draft PR：待创建
+
+## 影响 / Impact
+
+- 会削弱用户对 Windows 听写插入可靠性的信任
+- 会让 `PasteSent` 的用户语义与目标实际行为产生偏差
+- 会增加 Windows terminal / 文本输入场景下的排障复杂度
+
+## 建议接受标准 / Proposed Acceptance Criteria
+
+- [x] 明确 `PasteSent` 与“实际 paste 已完成”不是同一语义
+- [x] 完成最小修复：Windows clipboard restore 从 `150ms` 提高到 `750ms`，并异步 restore
+- [x] 提供隔离时序实验，证明 race 条件存在
+- [x] 提供稳定化整链路自动化，覆盖：
+  - [x] `wt-cmd`
+  - [x] `wt-powershell`
+  - [x] `notepad`
+- [x] 明确当前机器上的稳定化整链路回归未复现用户原始问题
+- [ ] 若后续继续追用户原始问题，需要补充更具体的环境条件（terminal host/profile、输入法、焦点切换时序等）
+
+## TODO / 不确定项
+
+- 用户最初复现场景是否依赖特定 terminal host / profile / session state
+- 是否存在当前自动化未覆盖的输入法、前台切换或第三方软件干扰
+- 是否需要后续把 `PasteSent` 的用户提示文案进一步收紧，避免被理解为“已确认粘贴成功”
+
+建议 issue 标题：`[windows][insertion] 终端旧剪贴板粘贴问题具有条件性，当前整链路回归未复现`
diff --git a/docs/github-tracking/pr-windows-terminal-clipboard-restore.md b/docs/github-tracking/pr-windows-terminal-clipboard-restore.md
new file mode 100644
index 00000000..e4e4b3d6
--- /dev/null
+++ b/docs/github-tracking/pr-windows-terminal-clipboard-restore.md
@@ -0,0 +1,70 @@
+## 摘要
+
+Closes: 待关联 issue
+
+这个 draft PR 用来收敛 Windows 插入路径里的剪贴板恢复时序问题，并补齐从隔离时序实验到完整 OpenLess 生命周期的回归证据。
+
+当前结论不是“terminal 一定会 paste 旧剪贴板”，而是：
+
+- race 模型在隔离实验里真实存在
+- 最小修复已经落地
+- 当前机器上的稳定化整链路回归未在 `wt-cmd` / `wt-powershell` / `notepad` 上复现用户报告的问题
+- 因此该问题应被视为条件性问题，而不是所有 terminal 场景下的通用必现问题
+
+## 修复 / 新增 / 改进
+
+- Windows clipboard restore 从 `150ms` 提高到 `750ms`
+- clipboard restore 改为后台线程执行，不阻塞插入返回
+- 新增 Windows clipboard timing smoke，用于证明慢消费者 race
+- 新增稳定化整链路自动化脚本，覆盖：
+  - `wt-cmd`
+  - `wt-powershell`
+  - `notepad`
+- 调整目标读回方式：
+  - terminal 走 UIA 读取 `TermControl`
+  - notepad 走 UIA 直接读取文本
+- 新增 debug-only transcript override，用于桌面音频路由不稳定时继续覆盖真实 insertion 尾链
+- 更新调查文档，沉淀隔离实验与整链路回归结论
+
+## 兼容
+
+- 正常用户路径不依赖 debug transcript override
+- debug transcript override 仅在 `debug_assertions` / test 构建下参与
+- Linux restore delay 保持原行为
+- 不涉及 UI/视觉顺手修改
+- 不涉及 QA hotkey / selection 主线逻辑修改
+
+## 测试计划
+
+- [x] `cargo fmt --all`
+- [x] `cargo check --lib`
+- [x] `python -m py_compile openless-all/app/scripts/windows-openless-lifecycle-e2e.py`
+- [x] `windows-real-asr-insertion-smoke.ps1` 脚本解析通过
+- [x] 隔离时序实验：
+  - [x] 快消费者 + `150ms`
+  - [x] 慢消费者 + `150ms`
+  - [x] 慢消费者 + `750ms`
+- [x] 稳定化整链路自动化：
+  - [x] `wt-cmd`
+  - [x] `wt-powershell`
+  - [x] `notepad`
+- [x] 证据路径：
+  - `docs/2026-05-02-windows-terminal-clipboard-restore-investigation.md`
+  - `docs/github-tracking/issue-windows-terminal-clipboard-restore.md`
+
+## 当前结论
+
+- root cause：
+  - `PasteSent` 被误当成“paste 已完成”
+  - 旧实现会在目标实际消费 clipboard 前恢复旧剪贴板
+- 但当前稳定化整链路回归表明：
+  - `wt-cmd`、`wt-powershell`、`notepad` 在本机都能拿到本次 `finalText`
+  - 因此用户原始问题仍然依赖额外环境条件
+
+## 剩余风险
+
+- `750ms` 仍是启发式保护，不是目标确认式握手
+- 条件性 race 仍可能在更慢或更特殊的目标环境下出现
+- 如果后续要继续追原始问题，建议单独 follow-up 到更窄的环境变量，而不是继续扩大当前 PR 范围
+
+建议 PR 标题：`fix(windows): 延后剪贴板恢复并补齐插入回归覆盖`