[R2][终端] 确定保留原合同的原生 API 与末端 margin 处理路径 #56

当前正式路线（2026-10-28）

用户已确认自主 C++ 终端核心＋当前 Qt Widgets GUI＋随包固定微软 ConPTY，依据见 ADR-0008。第一批整合由 #115 / PR #116承接。

Windows PTY 已选随包固定微软 ConPTY，终端状态由自主 C++ 维护。本项继续区分原生 API、运输和末端状态并调查原版；固定后端选择不批准 #34 所列样式/滚动区域差异或原版缺陷修正，不以规范/候选规则替代原版裁决。

以下原合同与固定检查点保留各自来源；路线确认不替代实现、完整R2或性能验收。

当前方向与确认边界（2026-10-26）

继续调查可保留行为的实现路径，参考行为以 WindTerm 2.7.0 实际观察为默认依据。未知原版行为不计通过；涉及范围、主要技术路线或重要差异的方案提交用户确认。原生 API/末端分层证据与原合同失败保留。

依据：已确认方向与决策权限。

问题与目标

#41 已观察到：同一固定175B源在系统 ConPTY 的原生控制台及末端 margin 恢复错误；固定官方1.25后端能保留必要 VT，候选末端正确，但四阶段原生 CHAR_INFO 的每屏 margin 结果仍存在差异。不能把末端成功当作原生 API 成功，也不能只以“新引擎本来不同”关闭原功能缺口。

形成有第一方依据、可维护且可复验的处理路径，使 #41 的原 R2 合同有明确可实现方案。当前任务不改变合同或支持范围。

范围与非目标

精确列出原合同必须满足的原生字段、每缓冲区 margin 与末端语义，核对实际差异及支持边界；比较受支持上游修复、许可明确且可维护的 MIT fork 或其他受支持路径。

本项不选择默认后端、不替代 #34 架构决定，不通过猜补 VT、删除原生检查或放宽目标取得通过；没有可行路径时保持缺口开放。

依赖

父项 #41；本项阻塞 #41。可直接使用已入库的原固定175B、四阶段探针与固定官方1.25包独立调查，无需等待 #47 或候选 .4 联合基线。后续产品整合须使用实际最终源码与后端重新验证。

验收条件

• 从 [R2-04][终端] 裁决 ConPTY 主/备用屏 margin 恢复差异 #41 与既有 R2 合同提取逐字段判据：原生 CHAR_INFO/文本/样式/光标、main 2;3r/alternate 4;5r、区域外保持、历史及 resize 交叉；区分硬合同、第一方声明、运行观察和未知，不因当前实现结果重写预期。
• 在固定 Windows、package/source/API/flags 身份下重放原175B与四阶段，保存原始源、实际 transport、原生状态和末端候选的独立结果；解释哪些信息保留/丢失、哪些 API 状态与末端分离，静态源码不替代运行证明。
• 以第一方文档、固定上游源码/公开问题或上游确认核对支持边界；把“未实现”“设计行为”“版本缺陷”与本项目政策分开，不凭观察差异直接推出平台豁免。
• 比较能保留原合同的受支持路径：上游修复、可维护 MIT fork 或其他受支持实现；逐项说明 API 族/模块生命期、部署身份、许可、更新成本及失败边界，不引入 WindTerm 专有代码或资源。
• 至少为拟采用路径给出同输入的可复验证据和必要反例，证明它如何满足原合同必须保留的原生字段与末端 margin；没有证据支持的方案仅列候选，不能据此结项。
• 将结果形成明确后续实现/上游工作和维护方案，关联 [R2-04][终端] 裁决 ConPTY 主/备用屏 margin 恢复差异 #41/[R2][Backend] 整合已确认的随包固定微软 ConPTY 正式路线 #47/[R2-04][终端] 实现备用屏、滚动区域及关联模式 #27/[R2-06][终端] 定义并验证 resize、逻辑行与历史语义 #29/[R2-11][架构] 提交核心、GUI/平台方案并取得用户确认 #34。若原合同确实无法保留，需要另行提出明确范围/架构决策并保留未完成项；本轮整理和本任务本身不批准该调整，也不以新合同证明旧合同完成。

验证方法与证据

沿用 margin A/B 调查及 experiments.conpty.margin_run，使用固定源、原期限、自有 Job、源控制台/transport/末端分层观测和清理断言。保持官方1.25来源与同包双 SHA，不下载不明构建或修改全局终端环境。

记录真实通过、失败和未知；原件私有、公开仅审核后的合成材料和脱敏摘要。完整产品、真实显示、长期资源、实际呈现和 WindTerm 等价不由本项推断。

来源、限制与已知差异

• #41 原合同与固定现象
• R2 出口合同
• Draft PR #50

#41 继续开放；本项不允许以“原生API/末端语义不同”的描述替代功能修复或显式合同决策。

已交付的调查与下一步

PR #60已合入：原175B四阶段的逐字段独立oracle、固定上游单margin状态的MIT补丁候选、真实重建/维护路径与原始失败分列。纯4/4、两条CI和独立双轴审查通过；复算实际capture仍为前三阶段绿、final红，官方80列原5秒自然退出失败也保留。

PR #60 当时补丁仅通过可应用检查，未编译或运行 fork 后端；该历史状态不再当作当前结果。后续真实构建与原175B的同源原生对照见下文；本项/#41继续开放。

原版原生字段的补充观察

PR #95、四份观测及限制、白名单记录已以 3adec0b49947257c3f02207b743d6de9f1ab168f 合入实验父分支。实际WinPTY本地shell在可见60×12时，原size helper及独立GetConsoleScreenBufferInfo一致记录dwSize60×3000、srWindow[0,0,59,11]；另一样本Vim应用报告60×12。它们证明必须区分原生缓冲区与可见窗口，不能将当前ConPTY的两者相等默认为所有原版路径的事实。

原CPR入口未完成，独立输出模式3→7变体得到回复；旧失败样本模式与CPR生产方未测，不能回填根因。现有175B四阶段margin原合同、修补候选、原失败与本项验收均保持；本次没有验证WinPTY margin或选择替代后端。该原版观测批次没有执行 fork margin；后续固定上游构建与同源原生/末端验证另列，不用新结果回填原版未知。

固定上游重建的当前状态

Draft PR #96提供独立 hosted 构建入口。固定 Terminal/vcpkg checkout 已按源身份核对；实际 triplet 要求 v145，本机仅有 v143，未修改本机安装。本地 NuGet 的命名及网络准备失败保留；真实构建移至 GitHub-hosted Windows，已核对 VS18/MSVC14.51.36231/SDK26100 和原 vcpkg 工具 SHA。

前三次失败各自的完整 job 日志和 summary ZIP/SHA 已核对，保存在local/r56-conpty-build；artifact分别为12708535299、12708272075、12708971439。没有重复同一配置取绿，后续运行对应具体构建入口修正。纯判据6/6，初审的TAEF高位错误问题及各次增量已分别通过Standards/Spec复审。

入口仍要求单测试补丁的明确 margin 断言 red、实现补丁后的 focused/full adapter green，再构建同源 EXE/DLL；框架错误或超时不能计 red。即使上游测试通过，仍须独立 fork 身份及原175B的原生/运输/末端和反例证据；本项及 #41 继续开放。PR96 的独立Windows准备失败已补到 #81，后续默认/system或candidate CI成功不替代本项。

首次成功构建的实际checkout为 eb88c25fea343cff92bd7d5c03e74c55df6bafff，状态 adapter-verified-runtime-unverified；该次只生成patched pair。后续 v2构建40449292015 已成功保存同源 baseline/patched；实际checkout ad857d448dfe64c0c11d10254043a8b893e7546a。baseline focused为预期1fail/exit1，patched focused1/1、full adapter412/412零skip；variant各自绑定补丁状态、测试边界与双文件SHA。三个artifact均已核对，baseline完整adapter未验。

PR96当前HEAD 5c073e4 的PR default/candidate及push default成功，但push candidate出现原20秒退出超时，单独由 #97（#38子项）承接；没有重跑取绿。#97不是本项175B输入，也未证明同因。PR96继续Draft。

同源原生运行对照已完成的限定范围

Draft PR #98 基于PR96，发布源码 678804ff5201fab4296b133af9457b7120739b68；运行说明与复验及脱敏验证保存实际运行源码、探针、trace、来源与原件身份。

Windows11 x64 build26200，baseline/patched × 80×24/12×7 × VT-on/off，各一次，共8次；原175B、四阶段独立oracle、5/15/5秒预算保持。VT-on两尺寸的baseline原生final均红，patched四阶段文字/格属性/光标全绿；两版实际运输回放后的末端均正确，VT-off原生格/文本/光标和末端文本保持一致。全部自然37、EOF109、Job0，无force。15个实际API/身份场景与8个清单拒绝也通过；两路审查各0发现。

仅开启默认OFF的独立探针，不替换官方身份或配置产品后端。原source未设置SGR，本次属性结果只证明初始属性保持；样式、历史、无备用屏/重复h/l/默认margin的真实交叉、resize、查询/API、完整产品和升级维护仍须推进。上游focused中的重复h/l不代替原生交叉；flags0 margin与flags24 API也不拼为联合验收。

原官方80列5秒失败、未知WindTerm margin行为、#52及#97均保留。本项仅勾选固定175B分层运行记录这一条，其余验收和 #41 继续开放；正式采用仍由 #34 的证据提案及用户确认决定。

PR98 的两条candidate及PR default检查成功，但push default为51/52，独立ui-clipboard-system占用反馈后45秒超时由 #99 承接。#98继续Draft；该失败没有改变本项原175B实验结果，也不被它覆盖。当前源码margin的后续样式/历史/resize交叉可独立推进，完整产品可靠性保持未完成。

原生补充对照：固定入口与实际结果

在 #98 源码上独立增加 controls 探针，复用已定义的原生 Console API快照、真实transport与末端回放边界；原175B及其oracle不改。预定VT-on下 main-only、default-alt、repeat-alt 三场景 × baseline/patched × 80×24/12×7，共12次，每格一次，无自动重试；仍为5秒child wait、15秒外期限、5秒cleanup。

预期在运行前固定：main-only两版均正确；default-alt中新备用屏默认全屏滚动，baseline继承主屏区域导致备用屏结果错误而patched正确；repeat-alt再次创建备用屏时仍默认全屏，返回主屏及重复离开后仍恢复主屏2;3r。所有原生阶段分别核对文本、完整字符/属性和光标；两版实际运输的最终主屏另核对。基线失败必须符合具体旧状态预测，任意异常或生命周期失败不计red。样式变化、历史压力、resize/查询/API交叉仍另列。以上入口在运行前冻结，实际结果如下。

Draft PR #100 基于 #98，发布源码 2e24fe31e57313d18451c1d536b03748c8b4f5cd；补充对照报告及脱敏验证记录实际运行源码 edec26b、干净状态与原件身份。

预定12次全部完成，无重试：main-only两版所有阶段正确；default-alt的baseline仅alt错误，repeat-alt的baseline仅alt2/final错误，均精确符合运行前旧状态预测；patched所有阶段的文本、完整格/属性、光标、viewport均正确。两版实际transport最终主屏文字正确。全部自然37、EOF109、flags0、outer Job active0/total4/terminated0，无force，5/15/5期限保持。

新旧margin/GO/回收回归17/17、原loader/API/清理14/14、零skip，stdout日志已保存；默认配置下纯CTest入口1/1。两路审查Standards硬规则0/异味0，Spec0。PR100四条CI均成功：PR default 40458226252（Windows53/53、272.23s；Linux34/34、10.82s），push default 40458205181（Windows53/53、280.85s），PR/push candidate 40458226273/40458205140。系统配置CI与本地source探针结果分列，不代表fork产品后端验收；#50/#96/#98/#100保持Draft，原175B历史结果与#52/#97/#99不变。本项/#41仍开放，继续补显式样式、非零光标、历史/resize/查询/API、完整产品及维护方案，未知WindTerm行为不计匹配。

样式与非零光标对照（执行前固定）

基于PR100独立增加显式 styled-cursor 入口，原三controls及175B默认入口保持。单一场景 × 80×24/12×7 × 同源baseline/patched，共4次，每格一次，无自动重试，仍为5/15/5秒及自有Job。

固定五个原生快照：before、alt、restored、after-write、final。主屏2;3r后选择SGR31;44并把光标放到第3行第6列；备用屏4;5r使用SGR32;45滚动，再将光标移到第5行第8列；返回主屏应恢复第3行第6列，直接写M验证恢复后的实际字符属性，再进行原主屏区域滚动。每阶段独立核对全文、完整CHAR_INFO字符/属性、光标和viewport；源字节独立绑定。固定上游的CursorSaveState/RestoreState提供保存图形属性与位置的来源线索，运行结果仍另验。

预期baseline前四阶段正确，final保留旧错误区域及REGION_CIXED残尾；patched五阶段均正确。基线必须符合具体旧状态和属性预测，任意失败不计red。两版实际transport的末端最终文本、主屏状态、光标、显式前景/背景及current_style另行核对；native的颜色索引位与末端ANSI索引分开。此片只涉及默认及两组16色SGR，没有bold/underline/真彩色。终端中间阶段、历史、resize、查询/API、完整产品、性能和未知WindTerm行为仍未验收；不变更默认后端或关闭#56/#41。

Draft PR #102 已发布，源码 dc5c631ffdf83dfbdfcb8b359137e0d87212ac6d；完整报告、脱敏验证。实际运行源码485c3e2、干净工作树；预定四次均完成，baseline前四阶段正确、final精确符合旧区域错误，patched五阶段全文/格属性/光标/viewport全通过。全部自然37、EOF109、flags0、outer Job0/4/0、无force；原5/15/5期限保持。

完整末端属性比较仍失败：四份transport均为254B，文字、背景、光标和current_style通过，滚动产生的空白格前景期望1、实际-1；80列每次144格，12列每次8格。首次oracle把默认空单元误写为space/width1，离线按原trace合同修为empty/width0（6e52e69），只排除1731/31格编码错误；显式前景预期及失败结论保持，原summary不改，原生不重跑。固定候选上游Cell::reset保留背景、重置前景的源码观察不证明WindTerm行为，也不批准产品策略或自动认定用户可见缺陷。

新判据7/7，编码反例先red后green；旧12份controls捕获离线复查通过。Standards硬规则0/实质异味0，Spec0；两路独立核对原件和身份，审查tree36b21cd。常规CI四条均成功、attempt1，无重跑：PR default40473755050（Windows53/53、257.60s；Linux34/34、15.45s），push default40473694804（Windows53/53、276.52s；Linux成功），PR/push candidate40473755055/40473694770均成功。PR实际checkout c3ebdc73的tree与发布/审查tree一致。系统配置CI与source原生实验分列。本项/#41仍开放，下一步补原版样式/空白格行为；其他SGR、历史/resize/API、完整产品及维护合同继续推进。

原版样式参考：下一次执行前边界

使用官方WindTerm2.7.0固定包、全新合成本地cmd、独立非输入window station和自有Job，只运行一次；同一个controls EXE（SHA ca19645b65aea8ac74b56d1e59837cb7514c3acf5932d24112411725b92206d7）的原styled-cursor客户端，保持211B及五阶段原生capture。先用实际WinPTY尺寸、UI容量和原生viewport核对80×24；最多两次有界几何校准，不调整原生buffer高度。读取原生buffer/window区别、原生字段和最终UI文字；只枚举已暴露的样式/光标接口名，不将接口存在计为颜色已观察。原生等待5秒、清理5秒，独立wrapper最多保留最终画面8秒供观察，REA30秒、外监督45秒；一次失败即停止，无重试。该原版模式/代码页变更仅在自有console内，并记录恢复和shell自然退出/外回收区别。

若末端样式接口仍不可用，颜色、终端光标和当前属性继续记未知；不把原生CHAR_INFO替代末端颜色。无剪贴板、个人配置、物理显示或性能操作；不改变产品门槛，不以此单例关闭原合同。

上述原版计划已执行一次，无重试。Draft PR #103，发布源码 dce2ca799a25cf32f3cf2bacf1b9f7c915945a57；原版观察及边界、脱敏记录。 同一个211B和同EXE的五阶段捕获完整；原生及UI合成文字尾部都含 REGION_CIXED。实际WinPTY80×24、UI容量24、原生viewport80×24一致，主buffer为80×3000。before/restored/after-write/final的top=4，原绝对光标/top合同仍失败；只作解释的相对窗口坐标投影与未修补版五阶段预测匹配。原生/shell分别自然37、外回收Job0/11/0，模式/代码页恢复API成功但未重读。末端颜色、终端光标/current_style仍未知，没有transport捕获或组件根因归因。

Standards硬规则0/实质异味0，Spec0，完整包4047项及原件已独立复核。PR103两条default CI均成功、attempt1：PR40476438414的Windows53/53（268.84s）、Linux34/34（12.99s）；push40476273943的Windows53/53（275.19s）、Linux成功。candidate按既有路径过滤未触发；PR实际checkout9feb5a69与审查/发布tree一致，无重跑，不是原版场景重复执行。按原版优先，这成为修补路线的具体原版行为差异；既有实验和原失败保留，不能因“修后正确”直接采用为产品。由#34承接保持该原版行为或明确修复这一行为的取舍，未获决定前不改原合同，不关闭本项/#41。后续原版颜色、历史/resize/API与维护范围继续开放。