Skip to content

feat(desktop): Windows 本地终端改用随客户端携带的 ConPTY - #2003

Merged
xiaoyumuxi merged 1 commit into
mainfrom
feat/terminal-modern-conpty
Nov 15, 2026
Merged

xiaoyumuxi merged 1 commit into
mainfrom
feat/terminal-modern-conpty

Conversation

@xiaoyumuxi

Copy link
Copy Markdown
Collaborator

关联 Issue / Linked issue

PR 类型 / Type

  • feat:新功能或用户可见的改进
  • fix:缺陷修复
  • docs:文档、Agent Note、Skill 等规则文件
  • release:稳定版发布准备

改动说明 / What changes

背景 / Why

Viva 桌面客户端的 Windows 本地终端运行在系统自带的 ConPTY(kernel32 里的伪控制台)上。它不直接转发程序输出,而是先解析再重绘,于是在终端里运行 Codex、Claude Code、vim 等程序时:

  • 程序用 OSC 10/11 查询终端前景色、背景色,查询被吃掉,程序拿不到配色;
  • 同步更新(DECSET 2026,“这一段一次画完”)结束后又被重绘一次,画面撕裂;
  • 全屏程序开启的鼠标上报丢失;
  • Windows 10 的系统宿主丢弃 Shift+Enter 等增强键盘序列,TUI 中 Shift+Enter 变成提交。

Motty d61d1910 改用 Microsoft 发布的 ConPTY 解决了这些问题,本 PR 同步它。不同之处在于放置方式:Motty 把文件放在可执行文件旁边,并改了安装器、便携包和更新器;Lithe 的安装目录是签名和增量更新的基线、运行时只读,所以这里把文件编进程序,运行时装到用户缓存目录。

改动 / Changes

1. 随客户端携带的 ConPTY(desktop/internal/localshell/conpty/,新增)

  • 未修改的 Microsoft.Windows.Console.ConPTY 1.25.260930003(microsoft/terminal v1.25.2733.0,MIT)二进制:win-x64/conpty.dll、win-arm64/conpty.dll、x64/OpenConsole.exe、arm64/OpenConsole.exe,以及 LICENSE.txt。
  • NOTICE.md:来源、包和每个文件的 SHA-256、架构说明、加载方式和升级步骤。
  • files_windows_amd64.go / files_windows_arm64.go:go:embed 本架构的文件组。conpty.dll 跟随程序架构,OpenConsole.exe 跟随内核架构,所以 x64 构建同时带上 arm64 宿主,供 Windows on ARM 上运行的 x64 Lithe 使用。files_other.go:其他平台和 386 不携带。
  • conpty.go:
    • DefaultRoot() 返回 <user cache>\Lithe\conpty(Windows 上即 %LocalAppData%)。
    • Install(root) 把文件组写到 <root>\<digest>\;<digest> 是所有文件路径、长度和内容 SHA-256 的前 16 字节,不同版本不会写同一文件夹。
    • 已是正确字节的文件不重写;缺失或内容不同的文件经同目录临时文件 Sync 后改名,原子替换;目录权限 0700。
    • 改名失败时(另一个客户端已加载同一文件),确认现有文件字节正确就视为成功。
    • 没有携带文件组的构建返回 ErrUnavailable。

2. 加载与回落(desktop/internal/localshell/)

  • conpty_windows.go(新增):
    • bundledConPTY() 每个进程只执行一次(sync.Once):安装,再用 LoadLibraryEx(LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR | SYSTEM32)加载,取 CreatePseudoConsole、ResizePseudoConsole、ClosePseudoConsole。
    • createPseudoConsole 先用随附的 ConPTY;安装、加载或创建控制台失败时改用系统 ConPTY,并通过 degraded 回调报告原因。ErrUnavailable 不算降级;两者都失败时返回合并后的错误。
  • backend_windows.go:伪控制台的创建、调整大小和关闭都改走所选的那一套函数。
  • shell.go:Config 新增 Degraded func(error),说明 Shell 在回落路径上运行的原因。

3. 降级日志(termview、workbench、core)

  • termview/view.go:Failure 新增 Operation 字段;常量 eventBackgroundFailed = "app.background.operation_failed"、operationConPTY = "terminal_conpty"。
  • termview/session.go:启动本地 Shell 时传入 Degraded,回落时上报一条 Warn 级 Failure;Shell 继续运行,日志是唯一能看出“正在降级运行”的地方。
  • workbench/terminal.go:terminalFailed 在 Operation 非空时写入 operation 字段。
  • core/log_sites_test.go:在 forwardedLogEvents 登记 terminalFailed 转发的新事件(WARN,必填 operation、error)。

4. 测试

  • conpty/conpty_test.go:核对文件夹与 NOTICE 的哈希、PE 机器类型、多余文件;每个构建携带的文件组;按摘要命名安装、保留正确文件(mtime 不变)、修复错误字节、不同文件组并存、根目录不可建时报错、无文件组时 ErrUnavailable、摘要覆盖路径与内容。
  • localshell/conpty_windows_test.go(仅 Windows):
    • 子进程探针确认随附 ConPTY 送达 OSC 10/11 应答,同步块中的标记只出现在 2026h…2026l 之间、不被重绘;Motty 测试里的 sleep 换成 cmd 在子进程退出后打印的确定标记。
    • 确认全屏程序开启的鼠标上报被转发。
    • 安装根目录建在普通文件下面时,Shell 回落到系统 ConPTY 正常运行,且 Degraded 只调用一次;正常路径不调用 Degraded。
    • 测试通过 conptyRootOverride 使用系统临时目录下固定的 lithe-localshell-test-conpty,不写用户的 %LocalAppData%。用固定目录,是因为已加载的 DLL 删不掉。
  • termview/pluginterm_test.go:TestAShellStartedOnAFallbackIsLoggedAndKeepsRunning。
  • workbench/terminal_test.go(新增):TestTerminalFailuresAreLoggedWithTheirEventsFields,核对级别、事件和 operation 字段。

5. 记录与文档

  • .gitattributes:ConPTY 的 .dll、.exe 标为 binary,LICENSE.txt、NOTICE.md 设为 -text(保持与哈希一致的字节)。
  • termview/NOTICE:记录 Motty d61d1910。
  • scripts/resources/worktree-resources.json:登记不可复用资源 windows-conpty-binaries(Git 跟踪、编进程序、运行时副本在用户缓存);test-reuse-worktree-resources.mjs 补对应用例;docs/ci-builds.md“独立工作树的本地编译”补说明。
  • 功能矩阵:terminal-extended-keyboard 的 Windows 由 partial 改为 implemented(验证保持 pending),重写 Windows 验证动作和备注;terminal-canvas-compositing 补充 OSC 10/11 在 Windows 上的送达条件和证据。
  • Agent Note:.agents/notes/implemented/architecture/2026-11-16-windows-bundled-conpty-in-user-cache.md,记录“编进程序、装到用户缓存”与附带文件、构建标签、运行时下载、临时目录等方案的取舍;conpty.go 包注释加 Note 引用。

不在本 PR 范围内 / Out of scope


类型专属:feat

多平台对齐

  • 两端都具备:合入后 macOS 与 Windows 都具备该能力(本 PR 同时实现,或本 PR 补齐另一端)。macOS 本地终端使用 POSIX pty,没有系统 ConPTY 那层重绘,颜色查询、同步更新、鼠标上报和增强键盘本来就能送达程序(terminal-extended-keyboard 的 macOS 已是 implemented,本 PR 未改动);本 PR 补齐 Windows 端。
  • 只实现了 macOS:已为 Windows 提交跟进 Issue:#
  • 只实现了 Windows:已为 macOS 提交跟进 Issue:#
  • 刻意只属于某个平台(功能矩阵中另一端记为 platform-specific),理由:

范围检查 / Scope checks

功能矩阵 / Feature matrix

  • 已更新 shared/platform-feature-matrix/features/<id>.json:两端的实现状态和验证状态、证据路径、owner、验证动作都如实填写;没有运行验证的保持 pending(terminal-extended-keyboard、terminal-canvas-compositing)
  • 已运行 ./scripts/platform-feature-matrix/verify-platform-feature-matrix.sh;改了平台实现路径的,还运行了 ./scripts/platform-feature-matrix/verify-platform-feature-matrix-change.sh origin/main HEAD
  • 没有提交 .artifacts/ 下生成的矩阵视图
  • [N/A] 没有更新矩阵的,理由:已更新

插件归属 / Plugin ownership

  • 已在仓库根目录运行 develop-lithe 第三节“插件归属与宿主零依赖”的自查命令,结果为空
  • 新增或修改的测试只使用测试内联的合成插件、Core 契约 fixture 或插件市场索引快照;没有读取具体插件的插件包、仓库检出、构建产物或清单,没有使用真实插件 ID,没有“缺少插件时跳过”的测试(本 PR 测试不涉及插件)
  • 没有为具体插件提供的能力新建或更新宿主功能矩阵条目;宿主条目的证据和验证动作不引用插件的测试、插件包或插件仓库
  • 插件文案没有写进 shared/i18n/;插件的构建步骤、资源路径和补丁没有写进 scripts/resources/、docs/ci-builds.md、Agent Note 或 Skill
  • [N/A] 修改了通用扩展点、可能影响已发布插件的,已在受影响插件的仓库运行它的测试:没有修改扩展点,只改了本地 Shell 的伪控制台后端

UI 验证 / UI evidence

N/A:没有布局、控件、样式或文案变化。降级只写日志,不显示界面提示;用户可见的效果是 Windows 终端里程序的配色、刷新和鼠标行为,需要在 Windows 实机验收(见“验证”)。

统一日志系统 / Structured logging

  • 已接入统一日志系统:复用 Core 目录中已有的 app.background.operation_failed(WARN,必填 operation、error),经 termview.Failure → workbench.terminalFailed 转发,并在 core/log_sites_test.go 登记;没有 NSLog、os_log/Logger、直接写 stderr、print 或手写事件 ID
  • 一个操作只有一条终态,错误只在处理它的边界记录一次;高频路径没有用 INFO 逐项输出(每个终端启动最多一条 WARN;安装与加载每个进程只做一次,之后的终端复用同一结果,回落时每个终端各记一条)
  • 没有记录源码、编辑内容、环境变量值、命令输出、凭据;路径用 path、错误用 error 类型,动态通道段来自已校验的 ID(只记录 error 与固定的 operation)
  • 旧日志生成和使用校验脚本(scripts/logging/)已移除,等价检查恢复前在“验证”一节写明日志门禁未完成,不记为通过(见“验证”末尾)

界面文案 / i18n

  • [N/A] 宿主文案都走共享 i18n:没有新增界面文字
  • [N/A] 插件提供的文字由插件自己翻译:不涉及插件
  • 已运行 node scripts/i18n/verify-app-language-localization.mjs 和 node scripts/i18n/generate-i18n.mjs --check,没有放宽脚本或扩大豁免名单

逻辑归属 / Logic placement

  • [N/A] 可共享的逻辑在 Rust Core:ConPTY 的安装、加载和回落都是 Windows 原生 I/O,属于平台适配层
  • [N/A] 修改平台层已有的可共享逻辑时已迁入 Core:没有修改可共享逻辑
  • 工具或运行时专属的知识放在插件或成熟上游,宿主和 Core 没有按工具名加分支

性能与内存 / Performance and memory

设置 / Settings

N/A:没有新增或修改设置。

插件契约 / Plugin contract

N/A:不涉及插件契约、能力版本、插件函数协议或宿主方法。

发行包与资源 / Bundle and resources

  • 运行时不向已安装的 app bundle 或 Windows 安装目录写入;新增的资源路径已说明生命周期、所有权和可写位置(conpty.go 包注释、NOTICE.md、Agent Note),并运行 ./scripts/desktop/verify/verify-runtime-bundle-immutability.sh
  • 新增或修改宿主自身的下载、解压、生成或缓存资源的,已同步 scripts/resources/worktree-resources.json、scripts/resources/reuse-worktree-resources.mjs 的校验路由、对应测试和 docs/ci-builds.md“独立工作树的本地编译”一节(登记为不可复用的 Git 内资源,不需要校验路由)

无用代码与重构 / Dead code and refactoring


验证 / Verification

命令或操作 平台 结果
./scripts/desktop/desktop-go.sh test ./internal/... -count=1 macOS arm64 通过(57 个包 ok)
./scripts/desktop/desktop-go.sh test -race -count=1 ./internal/localshell/... ./internal/termview/,以及 workbench 的 TestTerminalFailuresAreLoggedWithTheirEventsFields macOS arm64 通过
./scripts/desktop/desktop-go.sh test -count=1 ./internal/core/ -run Log macOS arm64 通过
GOOS=windows GOARCH={amd64,arm64,386} CGO_ENABLED=0 go vet ./internal/localshell/... macOS 交叉 通过(含仅 Windows 编译的测试)
gofmt -l 受影响包 macOS 无输出
.agents/skills/write-stable-tests/scripts/verify-test-stability.sh --base origin/main macOS 通过
test-stability-macos.sh 计时新增用例(conpty 9 个、termview 1 个、workbench 1 个) macOS arm64 11 个全部通过,单个 ≤ 40 ms
verify-platform-feature-matrix.sh、verify-platform-feature-matrix-change.sh origin/main HEAD macOS 通过(193 项能力)
node scripts/i18n/verify-app-language-localization.mjs、node scripts/i18n/generate-i18n.mjs --check macOS 通过
scripts/desktop/verify/verify-runtime-bundle-immutability.sh macOS 通过(macOS 与 Windows 源码静态检查)
node scripts/resources/test-reuse-worktree-resources.mjs macOS 通过(35/35,含新增 ConPTY 用例)
./scripts/agent-notes/verify-agent-notes.sh macOS 通过(161 篇)
插件归属自查命令 macOS 无输出

未能执行的检查和原因:

  • Windows 运行时测试未在本地运行:本机 Parallels 只有 Fedora 和 Ubuntu 虚拟机,没有 Windows 来宾。conpty_windows_test.go 的三组用例(颜色查询与同步块、鼠标上报、回落到系统 ConPTY)只在 Windows 编译,本地只做了交叉 vet。标记 ready 后,GitHub Actions 的 Windows 检查(windows-2022,amd64,scripts/desktop/check.sh)会首次运行它们;arm64 的运行时路径仍没有自动化覆盖。
  • Windows 实机验收 pending:cmd、PowerShell、Git Bash、WSL 下的 Shift+Enter、Codex 配色、vim/less 鼠标与刷新;%LocalAppData%\Lithe\conpty\<digest>\ 的生成与再次启动不重写;x64 程序在 Windows on ARM 上选用 arm64 宿主;AppLocker/WDAC 限制下回落并记录 WARN。功能矩阵相应保持 pending。
  • 日志门禁:旧的 scripts/logging/ 校验已移除,等价的事件使用检查尚未恢复;本 PR 只以 core/log_sites_test.go 的转发登记作为依据,不把日志门禁记为通过。

提交前确认 / Final checks

  • 分支从最新的 main 创建;目标分支:feat、fix、docs 为 main,release 以发布流程要求为准(已变基到 c5e8fee,落后 0 个提交)
  • 以 Draft 提交,本地验证通过后才标记 ready
  • 没有无关改动,没有提交 .build/、target/、dist/、.artifacts/ 等产物,没有凭据、个人路径和未脱敏的日志或截图(ConPTY 二进制是有意纳入 Git 的发行输入,哈希见 NOTICE.md)
  • 本次构建、测试或预览启动的 Lithe 应用和子进程已全部关闭,没有进程残留(只运行了 Go 测试,没有启动 Lithe 应用)

系统 ConPTY 会先解析再重绘程序输出:OSC 10/11 颜色查询被吃掉、同步更新
(DECSET 2026)在结束后又重绘一次、全屏程序的鼠标上报丢失,Windows 10
还会丢弃 Shift+Enter 等增强键盘序列。改用 Microsoft.Windows.Console.ConPTY
1.25.260930003(MIT)的 conpty.dll 与 OpenConsole.exe,它们直接转发字节流。

- localshell/conpty:二进制、LICENSE.txt 与 NOTICE.md 由 Git 跟踪,NOTICE
  记录每个文件的 SHA-256,测试核对哈希、PE 机器类型和多余文件。go:embed
  编进 windows/amd64(含 arm64 宿主,供 Windows on ARM 上的 x64 程序)与
  windows/arm64 可执行文件;其他构建不携带,Install 返回 ErrUnavailable。
- 安装:每个进程首次打开终端时把整组文件写到
  %LocalAppData%\Lithe\conpty\<digest>\(按路径、长度、内容摘要命名,0700),
  相同字节不重写,不同字节经临时文件原子替换;安装目录不放任何文件。
- 加载:LoadLibraryEx 只在 DLL 目录和 System32 中找依赖;安装、加载或创建
  控制台失败时回落到系统 ConPTY,Shell 照常运行,并经 Config.Degraded
  记一条 WARN 级 app.background.operation_failed(operation terminal_conpty)。
  termview.Failure 新增 Operation,workbench.terminalFailed 带出 operation 字段,
  log_sites_test 登记新转发事件。
- 测试:Windows 测试指向固定的临时根目录,不写用户缓存;颜色查询与同步块
  用确定的结束标记代替 Motty 的 sleep;覆盖回落路径与不回落路径。
- 记录:termview/NOTICE 记 d61d1910;.gitattributes 把二进制标为 binary;
  worktree-resources.json 登记不可复用资源 windows-conpty-binaries,补对应
  测试与 docs/ci-builds.md 说明;功能矩阵 terminal-extended-keyboard 的
  Windows 改为已实现(验证 pending),terminal-canvas-compositing 补充说明;
  新增 Agent Note 记录“编进程序、装到用户缓存”的取舍。

Closes #2001
@ghfind-review ghfind-review Bot added the review: high ghfind author score; see https://ghfind.com label Nov 15, 2026
@xiaoyumuxi xiaoyumuxi changed the title feat(desktop): Windows 本地终端改用随客户端携带的 ConPTY(Motty d61d1910) feat(desktop): Windows 本地终端改用随客户端携带的 ConPTY Nov 15, 2026
@xiaoyumuxi
xiaoyumuxi marked this pull request as ready for review November 15, 2026 20:25
@xiaoyumuxi
xiaoyumuxi merged commit 10c04bf into main Nov 15, 2026
7 of 10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review: high ghfind author score; see https://ghfind.com

Projects

None yet

1 participant