Repository navigation
feat(desktop): Windows 本地终端改用随客户端携带的 ConPTY - #2003
Merged
Merged
Conversation
系统 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
1 task done
xiaoyumuxi
marked this pull request as ready for review
November 15, 2026 20:25
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
关联 Issue / Linked issue
localshell.Start在界面线程执行;本 PR 的首次安装也发生在其中,见“性能与内存”)PR 类型 / Type
改动说明 / What changes
背景 / Why
Viva 桌面客户端的 Windows 本地终端运行在系统自带的 ConPTY(kernel32 里的伪控制台)上。它不直接转发程序输出,而是先解析再重绘,于是在终端里运行 Codex、Claude Code、vim 等程序时:
Motty d61d1910 改用 Microsoft 发布的 ConPTY 解决了这些问题,本 PR 同步它。不同之处在于放置方式:Motty 把文件放在可执行文件旁边,并改了安装器、便携包和更新器;Lithe 的安装目录是签名和增量更新的基线、运行时只读,所以这里把文件编进程序,运行时装到用户缓存目录。
改动 / Changes
1. 随客户端携带的 ConPTY(
desktop/internal/localshell/conpty/,新增)Microsoft.Windows.Console.ConPTY1.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):2026h…2026l之间、不被重绘;Motty 测试里的 sleep 换成 cmd 在子进程退出后打印的确定标记。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 上的送达条件和证据。.agents/notes/implemented/architecture/2026-11-16-windows-bundled-conpty-in-user-cache.md,记录“编进程序、装到用户缓存”与附带文件、构建标签、运行时下载、临时目录等方案的取舍;conpty.go包注释加 Note 引用。不在本 PR 范围内 / Out of scope
vivaui/viva@647c2069打包改动在这种放置方式下不需要)。localshell.Start移出界面线程,由 [Feature] 终端在界面线程上启动 Shell 进程:首次绘制时同步执行 localshell.Start 与默认 Shell 探测,应移到后台 #1988 处理。cargo、swiftpm、bun、conpty四项下载缓存,已建 [Feature] 资源复用清单中 cargo、swiftpm、bun、conpty 四项下载缓存的校验依赖已删除的文件,无法复用,需清理 #2002,本 PR 不动。类型专属:feat
多平台对齐
terminal-extended-keyboard的 macOS 已是 implemented,本 PR 未改动);本 PR 补齐 Windows 端。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/下生成的矩阵视图插件归属 / Plugin ownership
develop-lithe第三节“插件归属与宿主零依赖”的自查命令,结果为空shared/i18n/;插件的构建步骤、资源路径和补丁没有写进scripts/resources/、docs/ci-builds.md、Agent Note 或 SkillUI 验证 / UI evidence
N/A:没有布局、控件、样式或文案变化。降级只写日志,不显示界面提示;用户可见的效果是 Windows 终端里程序的配色、刷新和鼠标行为,需要在 Windows 实机验收(见“验证”)。
统一日志系统 / Structured logging
app.background.operation_failed(WARN,必填operation、error),经termview.Failure→workbench.terminalFailed转发,并在core/log_sites_test.go登记;没有NSLog、os_log/Logger、直接写 stderr、print或手写事件 IDpath、错误用error类型,动态通道段来自已校验的 ID(只记录error与固定的operation)scripts/logging/)已移除,等价检查恢复前在“验证”一节写明日志门禁未完成,不记为通过(见“验证”末尾)界面文案 / i18n
node scripts/i18n/verify-app-language-localization.mjs和node scripts/i18n/generate-i18n.mjs --check,没有放宽脚本或扩大豁免名单逻辑归属 / Logic placement
性能与内存 / Performance and memory
localshell.Start本来就在界面线程执行([Feature] 终端在界面线程上启动 Shell 进程:首次绘制时同步执行 localshell.Start 与默认 Shell 探测,应移到后台 #1988,本 PR 之前已存在,Shell 进程也在那里启动)。本 PR 在其中加入每进程一次的安装:计算约 2.4 MB 的摘要并逐字节比较;首次还要写入并Sync3~4 个文件(arm64 为 3 个,x64 为 4 个),再LoadLibraryEx。之后打开的终端不再做这些。[Feature] 终端在界面线程上启动 Shell 进程:首次绘制时同步执行 localshell.Start 与默认 Shell 探测,应移到后台 #1988 把Start移到后台后,这部分随之移出;已在 [Feature] 终端在界面线程上启动 Shell 进程:首次绘制时同步执行 localshell.Start 与默认 Shell 探测,应移到后台 #1988 留言说明。%LocalAppData%\Lithe\conpty\每个版本增加约 2.4 / 1.3 MB;应用启动时间不变(首次打开终端前不做任何事);常驻内存增加一个已加载的conpty.dll(约 120 KB),每个终端一个OpenConsole.exe进程,代替系统 ConPTY 的 conhost 进程。设置 / Settings
N/A:没有新增或修改设置。
插件契约 / Plugin contract
N/A:不涉及插件契约、能力版本、插件函数协议或宿主方法。
发行包与资源 / Bundle and resources
conpty.go包注释、NOTICE.md、Agent Note),并运行./scripts/desktop/verify/verify-runtime-bundle-immutability.shscripts/resources/worktree-resources.json、scripts/resources/reuse-worktree-resources.mjs的校验路由、对应测试和docs/ci-builds.md“独立工作树的本地编译”一节(登记为不可复用的 Git 内资源,不需要校验路由)无用代码与重构 / Dead code and refactoring
refactor标签的 Issue,没有在本 PR 顺手处理:[Feature] 资源复用清单中 cargo、swiftpm、bun、conpty 四项下载缓存的校验依赖已删除的文件,无法复用,需清理 #2002验证 / Verification
./scripts/desktop/desktop-go.sh test ./internal/... -count=1./scripts/desktop/desktop-go.sh test -race -count=1 ./internal/localshell/... ./internal/termview/,以及 workbench 的TestTerminalFailuresAreLoggedWithTheirEventsFields./scripts/desktop/desktop-go.sh test -count=1 ./internal/core/ -run LogGOOS=windows GOARCH={amd64,arm64,386} CGO_ENABLED=0 go vet ./internal/localshell/...gofmt -l受影响包.agents/skills/write-stable-tests/scripts/verify-test-stability.sh --base origin/maintest-stability-macos.sh计时新增用例(conpty 9 个、termview 1 个、workbench 1 个)verify-platform-feature-matrix.sh、verify-platform-feature-matrix-change.sh origin/main HEADnode scripts/i18n/verify-app-language-localization.mjs、node scripts/i18n/generate-i18n.mjs --checkscripts/desktop/verify/verify-runtime-bundle-immutability.shnode scripts/resources/test-reuse-worktree-resources.mjs./scripts/agent-notes/verify-agent-notes.sh未能执行的检查和原因:
conpty_windows_test.go的三组用例(颜色查询与同步块、鼠标上报、回落到系统 ConPTY)只在 Windows 编译,本地只做了交叉 vet。标记 ready 后,GitHub Actions 的 Windows 检查(windows-2022,amd64,scripts/desktop/check.sh)会首次运行它们;arm64 的运行时路径仍没有自动化覆盖。%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 个提交).build/、target/、dist/、.artifacts/等产物,没有凭据、个人路径和未脱敏的日志或截图(ConPTY 二进制是有意纳入 Git 的发行输入,哈希见NOTICE.md)