From 4441248fb9ad0b809f69aff070e5b6e5a28e0aa7 Mon Sep 17 00:00:00 2001 From: JavaZeroo <71128095+JavaZeroo@users.noreply.github.com> Date: Wed, 28 Oct 2026 18:40:30 +0800 Subject: [PATCH] docs: confirm bundled Microsoft ConPTY product route --- AGENTS.md | 1 + README.md | 2 +- docs/EVIDENCE.md | 2 +- docs/FEATURES.md | 4 ++-- docs/PLAN.md | 2 ++ docs/README.md | 2 +- docs/TRACKING.md | 2 +- docs/adr/0004-presentation-backend.md | 2 +- docs/adr/0006-confirmed-project-direction.md | 3 ++- docs/adr/0007-bundled-microsoft-conpty.md | 22 ++++++++++++++++++++ docs/milestones/R2-local-terminal.md | 2 +- 11 files changed, 35 insertions(+), 9 deletions(-) create mode 100644 docs/adr/0007-bundled-microsoft-conpty.md diff --git a/AGENTS.md b/AGENTS.md index aeb2647f..0bfd51dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,6 +3,7 @@ - Read README.md, docs/PLAN.md, docs/FEATURES.md and the active milestone before making architecture decisions. - Follow docs/adr/0006-confirmed-project-direction.md: fully recreate WindTerm 2.7.0, with Windows 11 x64 as the first complete-version target and Windows/Linux/macOS as the final platform goal. Prioritize terminal foundations and performance before SSH/SFTP and the remaining features. - Preserve Alacritty as a candidate, not an approved product-core selection. Keep investigating the original code and mechanisms; internal implementation need not be identical. +- Follow docs/adr/0007-bundled-microsoft-conpty.md: the confirmed Windows local-shell product route bundles a fixed Microsoft ConPTY. Consolidate existing integration into this route; system ConPTY and WinPTY are diagnostic references rather than parallel product routes. Core and GUI choices remain unconfirmed, and route confirmation is not implementation acceptance. - Default to observed WindTerm 2.7.0 behavior when it conflicts with standards, third-party behavior or existing project policy. Unknown behavior requires investigation; important deviations and original-bug fixes require user confirmation. - The user confirms scope changes, major architecture/dependency choices, acceptance criteria and important behavior differences. Agents may autonomously research, experiment, implement, test and fix within confirmed scope. Record proposal/confirmed status and confirmation evidence in ADRs and issues; merged code or closed issues do not imply user approval. - Performance tolerances have no approved numeric values yet. Propose them from reliable baseline evidence and explicitly agree them with the user before using them for acceptance; keep existing diagnostic guards separate. diff --git a/README.md b/README.md index 6dedbe96..d8702972 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ An independent, fully open-source terminal project targeting WindTerm 2.7.0 feat 当前是有限 Windows 本地终端原型，**R1 基础文字交互已按限定合同验收，正在推进 R2 可靠本地终端与开发版**。主线已有 Alacritty 候选实验、首批流式字素、有限多会话和配置恢复；候选核心与实验 ConPTY 后端的联合配置、完整 TUI/输入、真实不同 DPI、性能预算和开发包仍需闭合。现状见[能力矩阵](docs/FEATURES.md)，接续顺序见 [R2 交付路线与验收](docs/milestones/R2-local-terminal.md)。SSH/SFTP 属于 R3，完整 UI 与 WindTerm 性能等价均未验收。`TermForge` 是暂名。 -方向已经用户确认，依据见 [ADR-0006](docs/adr/0006-confirmed-project-direction.md)：原版行为优先，内部结构不强求一致，但认真研究、借鉴原版；Alacritty 保留为候选，正式选型待证据和用户确认。关键性能指标分别验收，具体允许波动范围后续与用户明确。 +方向已经用户确认，依据见 [ADR-0006](docs/adr/0006-confirmed-project-direction.md)：原版行为优先，内部结构不强求一致，但认真研究、借鉴原版；Alacritty 保留为候选，正式核心与 GUI/呈现选型待用户确认；Windows 本地 Shell 后端已确认采用[随包固定微软 ConPTY](docs/adr/0007-bundled-microsoft-conpty.md)，整合与验收尚未完成。关键性能指标分别验收，具体允许波动范围后续与用户明确。 ## 开始使用 diff --git a/docs/EVIDENCE.md b/docs/EVIDENCE.md index 015f836d..e9163b4d 100644 --- a/docs/EVIDENCE.md +++ b/docs/EVIDENCE.md @@ -4,7 +4,7 @@ 每条证据仅支持其固定配置，不能把历史成功、局部模块、未合并分支拼成当前产品验收： -产品方向和确认依据见 [ADR-0006](adr/0006-confirmed-project-direction.md)。历史候选比较及限定合同保留事实身份，不构成用户批准正式选型或重要差异；关键性能容差仍待可靠基线后与用户明确。 +产品方向和确认依据见 [ADR-0006](adr/0006-confirmed-project-direction.md)。Windows PTY 路线已由用户确认采用[随包固定微软 ConPTY](adr/0007-bundled-microsoft-conpty.md)，整合与验收仍未完成。历史候选比较及限定合同保留事实身份，不构成用户批准正式选型或重要差异；关键性能容差仍待可靠基线后与用户明确。 | 配置 | 证据定位 | |---|---| diff --git a/docs/FEATURES.md b/docs/FEATURES.md index e87fc67f..b5b51a5c 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -4,7 +4,7 @@ 比较目标固定为 **WindTerm 2.7.0**。功能范围依据[固定提交的官方 README](https://github.com/kingToolbox/WindTerm/blob/a8336c1d1e3dd1a981500dae8ef9eb42066de95f/README.md)、[2.7.0 release](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0)及仓库内的发行物/运行时研究。官方声明说明目标包含什么，不证明已经在本机验证了其行为，更不证明 TermForge 已实现。各平台、版本限制和具体交互仍需逐项形成可重复场景。 -用户确认的目标和权限见 [ADR-0006](adr/0006-confirmed-project-direction.md)：首个完整版本验收 Windows 11 x64，最终覆盖 Windows/Linux/macOS；原版实际行为优先。Alacritty 保留为候选，正式核心和 GUI/后端选型待确认；关键性能指标逐项达标，具体波动范围后续与用户明确。以下历史限定验收描述实现证据，不自动表示用户批准了最终策略或已达到原版一致性。 +用户确认的目标和权限见 [ADR-0006](adr/0006-confirmed-project-direction.md)：首个完整版本验收 Windows 11 x64，最终覆盖 Windows/Linux/macOS；原版实际行为优先。Alacritty 保留为候选，正式核心和 GUI/呈现选型待确认；Windows PTY 已确认采用[随包固定微软 ConPTY](adr/0007-bundled-microsoft-conpty.md)，实现尚待整合验收；关键性能指标逐项达标，具体波动范围后续与用户明确。以下历史限定验收描述实现证据，不自动表示用户批准了最终策略或已达到原版一致性。 状态定义：**限定验收**指表中明确范围已有实现与独立回归；**实现中，未验收**指已有实现，但整项目标场景或整合验收未完成；**未实现**指尚无相应产品能力；**待取证**指目标行为或比较结论未知；**限定测量**仅说明已有指定范围的观测，不代表性能预算通过。每行的“路标”表示主要交付位置，不表示之前的路标已完成。 @@ -14,7 +14,7 @@ |---|---|---| | 默认 main：自研核心 + 系统 ConPTY | 默认构建与已发布 Alpha 的基础路线，不需要 Rust | 已有 R1 限定验收；VT/Unicode 能力仍为有限子集，不能引用候选核心的字素或 TUI 结果 | | 显式候选 main：`termforge.4` + 系统 ConPTY | `TERMFORGE_BUILD_CANDIDATE_ADAPTER=ON`；按 [ADR-0003](adr/0003-core-reference-and-reuse.md)保留为可评估实验，正式核心选型待用户确认 | [固定来源](../experiments/candidates/alacritty/PROVENANCE.md)、[适配边界](../experiments/core/CANDIDATE.md)与 [#39 字素合同](research/streaming-graphemes.md)；候选正确性通过不关闭系统 ConPTY 或 R2 父项 | -| 实验分支：`termforge.5` + 固定官方 ConPTY | [PR #50（Draft）](https://github.com/JavaZeroo/termforge/pull/50)，早期 `termforge.4` 联合源码 `3e5b96d` 的[原基线](research/joint-conpty-baseline.md)保留；后续限定修复已整合，尚未合入 main 或通过产品整体验收 | [#47](https://github.com/JavaZeroo/termforge/issues/47) 跟踪后端整合；终端 margin 与原生状态分列。[resize #51](https://github.com/JavaZeroo/termforge/issues/51) 与[工作区 #63](https://github.com/JavaZeroo/termforge/issues/63) 已在实验父分支限定闭合，完整 resize/历史由 [#29](https://github.com/JavaZeroo/termforge/issues/29) 接续；[GUI Vim #52](https://github.com/JavaZeroo/termforge/issues/52) 仍开放。[#53](https://github.com/JavaZeroo/termforge/issues/53) 的原 3MB/768B/16KiB 未完成粘贴取消/关闭、负例及八会话 data-only 两轮已限定验证并整合到实验父分支；同次真实 CF/IME 与完整官方矩阵未通过。fence 默认关闭，不由实验结果选择产品后端 | +| 已确认后端路线的整合分支：`termforge.5` + 固定官方 ConPTY | [PR #50（Draft）](https://github.com/JavaZeroo/termforge/pull/50)，早期 `termforge.4` 联合源码 `3e5b96d` 的[原基线](research/joint-conpty-baseline.md)保留；后续限定修复已整合，尚未合入 main 或通过产品整体验收 | [#47](https://github.com/JavaZeroo/termforge/issues/47) 跟踪后端整合；终端 margin 与原生状态分列。[resize #51](https://github.com/JavaZeroo/termforge/issues/51) 与[工作区 #63](https://github.com/JavaZeroo/termforge/issues/63) 已在实验父分支限定闭合，完整 resize/历史由 [#29](https://github.com/JavaZeroo/termforge/issues/29) 接续；[GUI Vim #52](https://github.com/JavaZeroo/termforge/issues/52) 仍开放。[#53](https://github.com/JavaZeroo/termforge/issues/53) 的原 3MB/768B/16KiB 未完成粘贴取消/关闭、负例及八会话 data-only 两轮已限定验证并整合到实验父分支；同次真实 CF/IME 与完整官方矩阵未通过。fence 默认关闭；[ADR-0007](adr/0007-bundled-microsoft-conpty.md)已记录用户正式后端选择，代码合入与完整验收仍未完成 | 以下能力默认指已合并实现；某个配置的通过结果不能转用于另一个配置。R1 的真实系统 CF/拼音验收属于固定自研核心配置，不外推到候选 `.4` 或实验后端联合配置。 diff --git a/docs/PLAN.md b/docs/PLAN.md index bc582c29..b397b26a 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -12,6 +12,8 @@ 官方 `2.7.0` tag 指向提交 `a8336c1d1e3dd1a981500dae8ef9eb42066de95f`。目标清单的公开来源是[固定提交 README](https://github.com/kingToolbox/WindTerm/blob/a8336c1d1e3dd1a981500dae8ef9eb42066de95f/README.md)与[2.7.0 发布说明](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0)。官方声明、发行物静态事实、实际运行观察和本项目实现结果分别记录，前一类不能替代后一类。 +Windows 本地 Shell 的正式 PTY 路线已确认采用[随包固定微软 ConPTY](adr/0007-bundled-microsoft-conpty.md)，集中整合已有成果；核心与 GUI/呈现仍待用户确认，后端选型不代表实现或性能已验收。 + 当前实现与证据以[功能矩阵](FEATURES.md)为准，执行任务以[任务跟踪](TRACKING.md)为准。本文件只维护路标、工作包、依赖和出口条件，不累计每批开发过程。 ## 当前站位与下一次交付 diff --git a/docs/README.md b/docs/README.md index 96a4f996..0b814f9b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,7 +6,7 @@ |---|---| | 已经能做什么，离目标差在哪里？ | [功能与差异矩阵](FEATURES.md) | | 最终目标是什么，如何分阶段完成？ | [五个路标，远到近](PLAN.md) | -| 用户确认了什么，哪些决策仍待确认？ | [ADR-0006：方向与决策权限](adr/0006-confirmed-project-direction.md) | +| 用户确认了什么，哪些决策仍待确认？ | [ADR-0006：方向与决策权限](adr/0006-confirmed-project-direction.md)、[ADR-0007：随包固定微软 ConPTY](adr/0007-bundled-microsoft-conpty.md) | | R2 分几步交付，当前先做什么、怎样验收？ | [R2 交付路线与验收](milestones/R2-local-terminal.md) | | 已验收的基础文字交互合同是什么？ | [R1 基础文字交互](milestones/R1-local-text.md) | | 字体、网格和真实显示如何验收？ | [R2 字体与显示合同](milestones/R2-font-display.md) | diff --git a/docs/TRACKING.md b/docs/TRACKING.md index 587f3bf9..0bfa0dad 100644 --- a/docs/TRACKING.md +++ b/docs/TRACKING.md @@ -2,7 +2,7 @@ 本页只导航到 GitHub 任务，不维护第二份进度表。能力与构建配置见 [FEATURES](FEATURES.md)，R1–R5 范围见 [PLAN](PLAN.md)，当前接续顺序与完成条件见 [R2 交付路线与验收](milestones/R2-local-terminal.md)。实时状态、原生父子/阻塞关系和验收记录以各 issue 为准。 -执行方向按 [ADR-0006](adr/0006-confirmed-project-direction.md)：优先终端基础能力与性能，首个完整版本为 Windows 11 x64，随后完成 Linux/macOS；原版行为优先。#34 负责提交核心/GUI/后端正式选型供用户确认，#4/#54 提供基线和预算提案，性能容差经用户明确后生效。候选实验和既有关闭任务均不自动构成用户确认。 +执行方向按 [ADR-0006](adr/0006-confirmed-project-direction.md)：优先终端基础能力与性能，首个完整版本为 Windows 11 x64，随后完成 Linux/macOS；原版行为优先。[ADR-0007](adr/0007-bundled-microsoft-conpty.md)已确认 Windows PTY 采用随包固定微软 ConPTY，#47 接续整合；#34 负责提交其余核心与 GUI/呈现选型供用户确认，#4/#54 提供基线和预算提案，性能容差经用户明确后生效。候选实验和既有关闭任务均不自动构成用户确认。 ## 产品路标 diff --git a/docs/adr/0004-presentation-backend.md b/docs/adr/0004-presentation-backend.md index 082d874c..94e1b21c 100644 --- a/docs/adr/0004-presentation-backend.md +++ b/docs/adr/0004-presentation-backend.md @@ -3,7 +3,7 @@ > A1/G1/G2 为历史代号；首个本地窗口已进入当前原型。后端与平台边界的重审归入 [R2 产品架构决策](../PLAN.md)，须在扩大远程和跨平台产品整合前完成，不能以本 ADR 将实验后端永久定案。 - 日期：2026-10-23 -- 状态：历史实验选择保留；仅覆盖 Windows 的 A1/G1 实验，产品 GUI/呈现/后端选型待用户确认。 +- 状态：历史实验选择保留；仅覆盖 Windows 的 A1/G1 实验，产品 GUI/呈现选型待用户确认。Windows 本地 Shell 的 PTY 后端已另由 [ADR-0007](0007-bundled-microsoft-conpty.md)确认。 - 前置：[V1 窗口探针](../../experiments/presentation/README.md)、[ADR-0001](0001-evidence-before-stack.md)、[ADR-0002](0002-automation-first-investigation.md)。 当前按 [ADR-0006](0006-confirmed-project-direction.md) 优先实现 Windows 11 x64 的完整复刻，最终覆盖 Windows/Linux/macOS。#34 必须给出原版行为、性能、跨平台可行性和维护取舍的具体方案，经用户确认后定案；保留本实验不等于用户选定 Win32、DirectWrite 或 Direct2D。具体性能容差尚待用户明确。 diff --git a/docs/adr/0006-confirmed-project-direction.md b/docs/adr/0006-confirmed-project-direction.md index b1bb98e7..8e897cd2 100644 --- a/docs/adr/0006-confirmed-project-direction.md +++ b/docs/adr/0006-confirmed-project-direction.md @@ -16,6 +16,7 @@ | 平台与首个完整版本 | 用户明确“最终目标是全平台，但是首要目标是我们的windows”，并确认以 Windows 11 x64 为首个完整版本验收环境。最终覆盖 Windows、Linux、macOS；其他系统版本、最低版本和架构仍需单独明确。 | | 推进顺序 | 先对齐终端基础能力与性能，再逐步接入 SSH、SFTP 和其余功能。平台可行性及独立调查可并行；Linux/macOS 的完整客户端验收不阻塞首个 Windows 完整版本。 | | Alacritty | 用户确认“可以保留”。保留已有代码与证据，重新作为待评估候选；比较目标行为、性能及维护成本后，再确认正式核心选型。 | +| Windows PTY 后端 | 2026-10-28 用户明确“现在明确 随包固定微软 ConPTY”。正式路线采用随应用分发的固定微软 ConPTY，集中整合与优化；具体范围和未验收项见 [ADR-0007](0007-bundled-microsoft-conpty.md)。该确认不包含终端核心或 GUI 选型。 | | 性能标准 | 吞吐、交互/滚动/搜索延迟、CPU、内存/长期增长及多会话关键指标分别达到原版同等水平。用户明确“具体的波动范围需要后续与我明确”；当前没有获得任何数值容差的批准。 | | 行为裁决 | 用户明确“原版优先”。与通用规范、第三方核心或既有项目策略冲突时，默认以固定原版的实际行为为准；明确缺陷的修正方案另由用户确认。未知目标行为继续调查，不计为匹配。 | | 决策权限 | 目标范围、主要技术路线、验收门槛和重要差异由用户确认；已确认方向内的研究、逆向调查、候选实验、具体实现、测试和修复由代理自主推进。 | @@ -23,7 +24,7 @@ ## 对现有路线的处理 - [ADR-0003](0003-core-reference-and-reuse.md) 的既有 Alacritty 实验及结果保留；2026-10-25 的路线选择不再作为当前正式选型依据。最终决定由 [#34](https://github.com/JavaZeroo/termforge/issues/34)提交证据和方案供用户确认。 -- [ADR-0004](0004-presentation-backend.md) 的 Win32/DirectWrite/Direct2D 路线继续作为实验实现，GUI、呈现及产品后端尚未正式选定。 +- [ADR-0004](0004-presentation-backend.md) 的 Win32/DirectWrite/Direct2D 路线继续作为实验实现，GUI 与呈现尚未正式选定；Windows 本地 Shell 的 PTY 后端已由 [ADR-0007](0007-bundled-microsoft-conpty.md)确认采用随包固定微软 ConPTY，整合与验收另行完成。 - [ADR-0005](0005-physical-row-resize.md)、字体/网格、字素、选择等现有合同仍用于准确描述实现和防止回归。它们与原版的匹配情况须另验；重要差异不因测试通过或写成合同而自动获准。 - 已完成的构建、实验和限定验收保留原来源、结果和历史状态。当前问题由现有责任 issue 接续；不因方向重审重开全部已关闭任务，也不关闭真实缺口。 diff --git a/docs/adr/0007-bundled-microsoft-conpty.md b/docs/adr/0007-bundled-microsoft-conpty.md new file mode 100644 index 00000000..b9c1953c --- /dev/null +++ b/docs/adr/0007-bundled-microsoft-conpty.md @@ -0,0 +1,22 @@ +# ADR-0007：Windows 正式采用随包固定微软 ConPTY + +- 状态：已确认路线；整合与验收未完成 +- 日期：2026-10-28 +- 决策者：项目负责人（用户） +- 确认依据：在比较系统 ConPTY、随包固定微软 ConPTY 和 WindTerm 2.7.0 使用的 WinPTY 后，用户明确“现在明确 随包固定微软 ConPTY”。 + +Windows 11 x64 产品的本地 Shell 后端采用随应用分发、版本和来源固定的 Microsoft ConPTY。集中整合和优化这一条产品路线；系统自带 ConPTY 和 WinPTY 可保留为诊断对照，不继续作为并行产品路线扩展。该决定只选择 PTY 后端，不确认 Alacritty 核心或 Windows GUI/绘制方案，也不宣布现有实验实现已经可交付。 + +## 依据与取舍 + +随包版本可固定行为和升级节奏，已有加载、API 生命周期、包身份及错误处理实现可复用。[固定后端对照](../research/conpty-margin-backends.md)证明它在指定输入下保留了系统版本丢失的滚动区域命令；代价是承担组件分发、升级及兼容回归。这是限定正确性依据，不是性能排名或 WindTerm 等价证明。 + +WindTerm 2.7.0 官方说明为避免 vi 的非法字符而改用 WinPTY，[已有本地 cmd 观察](../research/windterm-ui-typography-2026-10-23.md)也实际启动了 winpty-agent。用户在知悉该事实后选择不同的内部后端；[ADR-0006](0006-confirmed-project-direction.md)确认的原版行为优先、重要差异确认和性能容差约定继续生效。 + +## 实施与确认边界 + +- 复用 [#47](https://github.com/JavaZeroo/termforge/issues/47) / [Draft PR #50](https://github.com/JavaZeroo/termforge/pull/50) 已有固定包接入及限定修复，不另起一套后端。现有 `Microsoft.Windows.Console.ConPTY 1.25.260930003` 可作整合起点；具体版本、宽度 flags 和内部实现没有被本次用户确认永久锁定。 +- 保持同包 `conpty.dll` / `OpenConsole.exe`、来源与许可、构建/运行身份检查及完整生命周期；组件缺失或身份错误明确失败，不静默切回另一条产品路径。后续升级固定来源并复验实际行为。 +- 合并及切换产品默认前，验证声明配置的完整 shell/TUI、resize/历史、输入、工作区与回收合同；保留内部跳过、旧失败和环境缺口。正式路线与代码是否合入、是否通过验收分别记录。 +- 后端选择不自动批准与原版不同的滚动区域或原生控制台行为。#34 / #41 / #56 中的具体原版差异继续留证；按原版优先调查，接受重要差异或修正原版缺陷前取得用户确认。 +- 正式终端核心仍按 [ADR-0003](0003-core-reference-and-reuse.md)待用户确认；Windows GUI/呈现仍按 [ADR-0004](0004-presentation-backend.md)待确认。性能数值容差在可靠基线后另行商定。 diff --git a/docs/milestones/R2-local-terminal.md b/docs/milestones/R2-local-terminal.md index 5ae95e56..895b8031 100644 --- a/docs/milestones/R2-local-terminal.md +++ b/docs/milestones/R2-local-terminal.md @@ -4,7 +4,7 @@ 用户结果：在明确支持的 Windows 环境中，用固定本地 shell、分页器和编辑器完成连续工作；复杂文字、输入和会话互相一致；重启后恢复已声明的配置；最终下载包能从公开源码复建。 -方向约束见 [ADR-0006](../adr/0006-confirmed-project-direction.md)：优先对齐终端基础能力与性能，首个完整版本环境为 Windows 11 x64，R2 是其中的阶段性交付。原版行为优先；Alacritty 保留为候选，核心/GUI/后端正式方案及性能容差需用户确认。历史已验合同继续作为回归依据，原版未知和重要差异由相应任务取证及提交确认。 +方向约束见 [ADR-0006](../adr/0006-confirmed-project-direction.md)：优先对齐终端基础能力与性能，首个完整版本环境为 Windows 11 x64，R2 是其中的阶段性交付。原版行为优先；Alacritty 保留为候选，Windows PTY 已确认采用[随包固定微软 ConPTY](../adr/0007-bundled-microsoft-conpty.md)，其整合与完整验收仍由 #47 接续；核心与 GUI/呈现正式方案待用户确认，性能容差在可靠基线后另行明确。历史已验合同继续作为回归依据，原版未知和重要差异由相应任务取证及提交确认。 ## 当前站位