diff --git a/AGENTS.md b/AGENTS.md index e1779324..aeb2647f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,11 @@ # Working on TermForge - 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. +- 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. - The project has a limited Windows local-shell prototype. Do not claim a daily-use release, Linux/macOS client, complete WindTerm parity or measured performance equivalence. - Do not lock the stack or add a large application skeleton before benchmark evidence supports it. - Every performance claim needs workload identity, environment, correctness checks, raw samples and limitations. @@ -17,5 +22,5 @@ - Keep build configurations separate in claims: default core/system backend, main candidate/system backend, and an explicit experimental backend need their own source and validation identity. Do not combine their independent successes into a joint acceptance result. - Source comments explain responsibilities, invariants and policy. Put changing status, batch names and future work in the owning issue; retain fixed experiment/protocol identities when they define behavior or evidence. A TODO must point to a current task rather than duplicate the roadmap. - Start only an issue whose real blockers are resolved. Record source observations separately from TermForge policies, implement independently, and validate the complete user-visible behavior. An unknown target behavior is an investigation item, not a passed comparison. -- Before expanding terminal modes and common TUI implementation in R2, complete ADR-0003's actual external-core comparison; candidate build and adaptation feasibility can proceed during R1. Before product backend selection, revisit ADR-0004. Do not silently turn experimental choices into permanent architecture. +- ADR-0003's historical external-core comparison remains evidence for continued candidate work, not user confirmation of a permanent route. Before final product core/backend/GUI selection, revisit ADR-0003/0004 under ADR-0006 and obtain the user's confirmation of a concrete evidence-backed proposal. Do not silently turn experimental choices into permanent architecture. - Documentation is primarily Chinese; technical identifiers and concise English summaries are welcome. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74da831d..6b156746 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ R1 基础文字交互已按限定合同验收,当前推进 R2 的联合配置、兼容性、输入与交付验收,并行处理性能和环境缺口。 -开始前阅读[总体计划](docs/PLAN.md)、[当前能力](docs/FEATURES.md)、[R2 交付路线与验收](docs/milestones/R2-local-terminal.md)和[任务跟踪](docs/TRACKING.md)。已验基础合同见 [R1](docs/milestones/R1-local-text.md);先核对 issue 的真实阻塞、目标构建配置和工作树,再选取范围明确的任务。PR 说明问题、最终行为、验证方法和限制,并更新对应能力行。大型依赖或技术栈变更需要记录 ADR 和实验依据。 +开始前阅读[总体计划](docs/PLAN.md)、[当前能力](docs/FEATURES.md)、[R2 交付路线与验收](docs/milestones/R2-local-terminal.md)和[任务跟踪](docs/TRACKING.md)。已验基础合同见 [R1](docs/milestones/R1-local-text.md);先核对 issue 的真实阻塞、目标构建配置和工作树,再选取范围明确的任务。PR 说明问题、最终行为、验证方法和限制,并更新对应能力行。按 [ADR-0006](docs/adr/0006-confirmed-project-direction.md),目标范围、主要技术路线、验收门槛和重要差异需用户确认;ADR 记录提议、证据和确认依据。研究、候选实验及已确认方向内的实现和修复可自主推进。 规划文件各维护一种事实:能力在 FEATURES、路标范围在 PLAN、交付顺序和验收在当前路标、实时进度和依赖在 GitHub。TRACKING 和 EVIDENCE 分别提供任务与来源导航。源码注释说明机制与不变量,TODO 指向责任 issue;不要把“这一批已完成”“下一波”等动态进度写进实现。固定实验、协议和历史结果的身份应保留,不机械改名。 @@ -10,6 +10,8 @@ R1 基础文字交互已按限定合同验收,当前推进 R2 的联合配置 提供具体应用版本/构建、输入 SHA-256、环境、配置、重复样本和正确性检查。说明时间端点是生产完成、消费完成还是画面呈现;不能混为一谈。报告退化和波动,不只挑最佳结果。 +关键指标逐项对标 WindTerm 2.7.0,首个完整版本环境为 Windows 11 x64。先测可靠基线,再提出容差并与用户明确;未经确认的数值只作提案,不用于宣布性能验收通过。终端行为默认原版优先;与规范、第三方核心或项目策略冲突时保留原版证据和差异,明确缺陷的修正由用户确认。 + ## 来源与隐私 遵守 [PROVENANCE](docs/PROVENANCE.md)。使用自生成输入与隔离测试配置,上传前检查用户名、路径、主机名、地址和凭据。第三方实现单独说明许可证;项目 MIT 许可不覆盖未获授权的第三方材料。 diff --git a/README.md b/README.md index 1d748c26..6dedbe96 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,12 @@ # TermForge -**独立、完整开源地复刻 WindTerm 2.7.0,以可复现证据验证功能、交互和性能。** +**以完整开源、可独立构建的实现复刻 WindTerm 2.7.0,优先完成 Windows 11 x64,最终覆盖 Windows、Linux、macOS。** -An independent, fully open-source terminal project targeting WindTerm 2.7.0 feature, interaction and performance parity. Not affiliated with WindTerm or KingToolbox. +An independent, fully open-source terminal project targeting WindTerm 2.7.0 feature, behavior, UI and performance parity. Windows 11 x64 first; Windows, Linux and macOS ultimately. Not affiliated with WindTerm or KingToolbox. -当前是有限 Windows 本地终端原型,**R1 基础文字交互已按限定合同验收,正在推进 R2 可靠本地终端与开发版**。主线已有候选核心路线、首批流式字素、有限多会话和配置恢复;候选核心与实验 ConPTY 后端的联合配置、完整 TUI/输入、真实不同 DPI、性能预算和开发包仍需闭合。现状见[能力矩阵](docs/FEATURES.md),接续顺序见 [R2 交付路线与验收](docs/milestones/R2-local-terminal.md)。SSH/SFTP 属于 R3,完整 UI 与 WindTerm 性能等价均未验收。`TermForge` 是暂名。 +当前是有限 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 保留为候选,正式选型待证据和用户确认。关键性能指标分别验收,具体允许波动范围后续与用户明确。 ## 开始使用 @@ -24,16 +26,17 @@ An independent, fully open-source terminal project targeting WindTerm 2.7.0 feat |---|---| | 已经做了什么、还缺什么 | [当前能力与目标矩阵](docs/FEATURES.md) | | 最终目标与五个路标(从远到近) | [总体计划](docs/PLAN.md) | +| 哪些方向已确认、哪些决定仍需确认 | [方向与决策权限](docs/adr/0006-confirmed-project-direction.md) | | 官方发行平台、架构与声明的最低系统边界 | [2.7.0 平台范围台账](research/windterm-2.7.0-platform-scope.md) | | R2 分几步交付,每步还缺什么 | [R2 交付路线与验收](docs/milestones/R2-local-terminal.md) | | 已验收的基础文字交互合同 | [R1 基础文字交互](docs/milestones/R1-local-text.md) | | GitHub milestones、issues 和执行顺序 | [任务跟踪](docs/TRACKING.md) | | 结论依据、复现命令和全部文档 | [证据索引](docs/EVIDENCE.md) · [文档导航](docs/README.md) | -交付主线:**基础文字交互 → 可靠本地终端 → SSH/SFTP 远程日常版 → 高级功能/跨平台/性能 → 完整 2.7.0 复刻验收**。性能工程和定向逆向贯穿各路标,不把远期整块调查当作近期开发的前置。 +交付主线:**终端基础能力与性能 → SSH/SFTP 远程工作流 → Windows 高级功能与性能收敛 → Windows 11 x64 完整复刻验收 → Linux/macOS 扩展与全平台验收**。保留 R1–R5 编号,R5 分 Windows 和全平台两个出口;性能工程、原版研究和平台可行性调查持续推进。 ## 工程原则与来源 -功能先通过正确性验证;性能同时衡量吞吐、交互延迟、CPU、内存、稳定性和多会话公平性。不以丢数据、无界缓冲或积压呈现换取跑分,不预设某种语言或框架必然达标。优先复用许可明确的组件,以测量和可维护性决定产品架构。 +功能先通过正确性验证;性能同时衡量吞吐、交互延迟、CPU、内存、稳定性和多会话公平性。不以丢数据、无界缓冲或积压呈现换取跑分,不预设某种语言或框架必然达标。研究原版公开代码、运行行为与关键内部机制,并比较自主实现和许可明确的组件;主要技术路线、验收门槛和重要差异经用户确认后生效。 原创代码和文档采用 [MIT](LICENSE),第三方组件保留自身许可。实现不依赖 WindTerm 二进制或专有资源;观察、静态线索和推断分别记录。详见[来源规则](docs/PROVENANCE.md)与[性能规范](benchmarks/README.md)。 diff --git a/benchmarks/PROTOCOL.md b/benchmarks/PROTOCOL.md index f5a9f80c..02b85f3c 100644 --- a/benchmarks/PROTOCOL.md +++ b/benchmarks/PROTOCOL.md @@ -109,4 +109,4 @@ H01 搜索固定首部/中部/尾部命中及不存在目标各 10 次,冷/重 吞吐和资源报告中位数、最小/最大、IQR、所有样本与失败率;原始批次保留。异常样本只能按预先记录的外部故障理由排除,报告排除前后结果。校准运行不能混入正式样本。 -M0 不给出“追平”结论。完成基线后,按每个关键场景制定绝对/相对预算和可接受差异,冻结后用于 M1/M2 对照。吞吐提高但尾延迟或正确性退化不能视为整体达标;没有证据的组件成本(如黑盒布局/解析耗时)必须保持未知。 +本协议的历史 M0 基线阶段不给出“追平”结论;当前执行使用 R1–R5 路标。按 [ADR-0006](../docs/adr/0006-confirmed-project-direction.md),先建立 WindTerm 2.7.0 的可靠基线,提出每个关键场景的绝对/相对预算和允许波动范围,与用户明确并记录确认后冻结,用于后续验收。当前没有已批准的数值容差,采样噪声或自有回归护栏不能替代该确认,也不得根据待验结果反填门槛。首个完整版本对照环境为 Windows 11 x64,其他平台分别留证。吞吐提高但尾延迟或正确性退化不能视为整体达标;没有证据的组件成本(如黑盒布局/解析耗时)必须保持未知。 diff --git a/benchmarks/README.md b/benchmarks/README.md index 31e86d05..29a3edc0 100644 --- a/benchmarks/README.md +++ b/benchmarks/README.md @@ -1,5 +1,7 @@ # 性能基准 +当前优先建立 Windows 11 x64 上 WindTerm 2.7.0 的终端基础能力对照,吞吐、响应、CPU、内存及多会话分别留证。按 [ADR-0006](../docs/adr/0006-confirmed-project-direction.md),具体允许波动范围在可靠基线后与用户明确,当前没有已批准的数值容差;阶段性诊断与性能验收分开。 + > M0/M1/M2 是协议 v0.1 的历史阶段名称;场景和测量约束继续有效,当前交付路标与执行顺序以 [R1–R5 计划](../docs/PLAN.md)及 [#3/#4 跟踪](../docs/TRACKING.md)为准。 已定义 [M0 实验协议 v0.1](PROTOCOL.md)、[机器可读场景参数](cases.json) 与 [记录模板](run-template.json)。[工具使用说明](tools/README.md) 包含生成器、播放器、Windows 资源采样与自建窗口视觉诊断。已有[真实 WindTerm 诊断烟测](results/2026-10-21-windterm-smoke/README.md),#3 的实际终端端点适配及正式开销校准仍未完成,尚无正式 WindTerm 性能基线。执行以 PROTOCOL.md 为准,本页为导航摘要。 diff --git a/docs/EVIDENCE.md b/docs/EVIDENCE.md index ceb2cd6d..ed6644c6 100644 --- a/docs/EVIDENCE.md +++ b/docs/EVIDENCE.md @@ -4,6 +4,8 @@ 每条证据仅支持其固定配置,不能把历史成功、局部模块、未合并分支拼成当前产品验收: +产品方向和确认依据见 [ADR-0006](adr/0006-confirmed-project-direction.md)。历史候选比较及限定合同保留事实身份,不构成用户批准正式选型或重要差异;关键性能容差仍待可靠基线后与用户明确。 + | 配置 | 证据定位 | |---|---| | main 默认:自研核心 + 系统 ConPTY | R1 限定总验收和有限 VT/Unicode 子集;默认构建不需要 Rust | @@ -67,7 +69,7 @@ R1 固定总出口的源码为 `ce9b24d`,早期 `2dc8d6d` / `9b16acc` 仍分 |---|---|---| | 构建与 CI 入口 | [贡献指南](../CONTRIBUTING.md)、[根 CMake](../CMakeLists.txt)、[CI workflow](../.github/workflows/build.yml)、[Actions 39930814167](https://github.com/JavaZeroo/termforge/actions/runs/39930814167) | 历史 2dc8d6d 的 Windows/Ubuntu 构建记录;当前入口由根 CMake/CI 定义。Linux 核心 CI 不代表 Linux 客户端。 | | 核心有限子集与恢复 | [核心支持合同](../experiments/core/README.md)、[Recovery 合同](../experiments/core/RECOVERY.md)、[resize 决策](adr/0005-physical-row-resize.md) | 自研有限 VT 子集、恢复与物理行裁剪合同;手写预期和拆包不能替代完整 VT/Unicode/TUI 认证。 | -| R2 核心路线决定 | [ADR-0003](adr/0003-core-reference-and-reuse.md)、[平台/维护/接口审查](research/2026-10-25-core-route-review.md) | ADR-0003 决定 R2 新能力复用 Term/Processor,同时保留传输/呈现/自研差分。历史平台/维护评估不等于当前客户端支持;路线决定不等于整项交付。 | +| R2 候选比较与历史路线决定 | [ADR-0003](adr/0003-core-reference-and-reuse.md)、[平台/维护/接口审查](research/2026-10-25-core-route-review.md) | 历史 Term/Processor 实验及传输/呈现/自研差分证据保留。按 ADR-0006,Alacritty 当前为待评估候选,正式核心选择由 #34 提交用户确认;历史平台/维护评估不等于客户端支持或产品选型批准。 | | 初始外部核心可行性(历史) | [固定版本/许可与复现入口](../experiments/candidates/alacritty/README.md)、[本地 Windows 摘要](../experiments/candidates/alacritty/results/2026-10-24-windows/summary.json)、[构建验证](../experiments/candidates/alacritty/results/2026-10-24-windows/validation.json)、[Windows/Ubuntu CI](https://github.com/JavaZeroo/termforge/actions/runs/40117504346) | 初始 crates.io 0.26.0 的固定来源、许可、构建及 headless 可行性;不是当前补丁版或产品路线验收。 | | 独立语义参考 | [差分入口](../experiments/differential/README.md)、[固定依赖](../experiments/differential/requirements.txt)、[2026-10-25 摘要](../experiments/differential/results/2026-10-25/summary.json) | 固定 pyte/wcwidth 的共同轨迹、精确裁决与负例;参考差异不算兼容通过,不用于性能比较。 | | 初始共同轨迹(历史) | [差分说明](../experiments/differential/README.md)、[逐项裁决](../experiments/differential/decisions.md)、[2026-10-25 Windows 摘要](../experiments/differential/results/2026-10-25-candidate-common-v3/summary.json) | 旧候选共同矩阵及精确参考差异;semantic_acceptance=false,保持原版本身份。 | diff --git a/docs/FEATURES.md b/docs/FEATURES.md index c65269f1..3a4dbcfc 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -4,6 +4,8 @@ 比较目标固定为 **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/后端选型待确认;关键性能指标逐项达标,具体波动范围后续与用户明确。以下历史限定验收描述实现证据,不自动表示用户批准了最终策略或已达到原版一致性。 + 状态定义:**限定验收**指表中明确范围已有实现与独立回归;**实现中,未验收**指已有实现,但整项目标场景或整合验收未完成;**未实现**指尚无相应产品能力;**待取证**指目标行为或比较结论未知;**限定测量**仅说明已有指定范围的观测,不代表性能预算通过。每行的“路标”表示主要交付位置,不表示之前的路标已完成。 ## 构建配置与证据边界 @@ -11,7 +13,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)推进 R2 新终端能力 | [固定来源](../experiments/candidates/alacritty/PROVENANCE.md)、[适配边界](../experiments/core/CANDIDATE.md)与 [#39 字素合同](research/streaming-graphemes.md);候选正确性通过不关闭系统 ConPTY 或 R2 父项 | +| 显式候选 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.4` + 固定官方 ConPTY | [PR #50(Draft)](https://github.com/JavaZeroo/termforge/pull/50),联合源码 `3e5b96d` 已重建并[冻结真实基线](research/joint-conpty-baseline.md),尚未合并或通过产品整体验收 | [#47](https://github.com/JavaZeroo/termforge/issues/47) 跟踪后端整合;终端 margin 与原生状态分列。[resize 残尾 #51](https://github.com/JavaZeroo/termforge/issues/51)、[Console-width Vim #52](https://github.com/JavaZeroo/termforge/issues/52)、[未完成粘贴的确定性取消夹具 #53](https://github.com/JavaZeroo/termforge/issues/53)仍开放,现有 completed 观察不能证明部分发送取消通过或产品 Cancel 故障;worker gate [#62](https://github.com/JavaZeroo/termforge/issues/62) 已有[独立夹具修正与双后端实际 worker 验证](research/sender-fence.md),默认产品路径不启用 fence,也不替代 #53 的 UI 取消/关闭;工作区 [#63](https://github.com/JavaZeroo/termforge/issues/63) 回归仍开放 | 以下能力默认指已合并实现;某个配置的通过结果不能转用于另一个配置。R1 的真实系统 CF/拼音验收属于固定自研核心配置,不外推到候选 `.4` 或实验后端联合配置。 @@ -68,9 +70,9 @@ | 活体资源与滚动端点 | **限定测量**:普通启动默认关闭;[R1 组合审计](../experiments/shell/results/2026-10-24-r1-system-workflow/validation.json)绑定实际接收、state 与同 revision 的 WM_PAINT/BitBlt/GdiFlush 提交,保留跨时钟校准与阶段资源,可离线重算 | launcher-tree 不等于 UI 归因;观察进程成本不等于增量采样成本,短命进程及退出 CPU 可能漏采。短驻留不证明长期无泄漏,`presented_done=null`,不构成性能通过 | R1;扩展 R4 / R5 | | 自动正确性与构建 | **限定验收**:Windows shell/ConPTY/呈现及 Windows/Linux 核心 CI、差分/恢复/队列/生命周期场景 | 产品打包、干净机器使用、依赖升级、长期回归和更广平台矩阵;#40 的 CI 纯夹具超时,以及后续保存 stage2 #72 / 窄窗口选择 #73 的独立失败仍未闭合 | R2 / R4 | | Windows 产品交付 | **实现中,未验收**:首个 [v0.1.0-alpha.1 预发布](releases/v0.1.0-alpha.1.md)提供 Windows x64、静态 MSVC 运行库、附资源许可和构建身份的免安装 ZIP;未签名,已验环境限 Windows 11 本机与 Server 2025 CI,布局仍写入 LOCALAPPDATA | 这是 R1 体验包,尚非 R2 日常开发版;干净机器与更广平台矩阵、签名/安装、配置升级及持续运行仍待完成。Windows 10 未验收,Server 2022 已知资源门槛未过 | R2 / R3 | -| Linux/macOS 与其他架构 | **未实现**客户端;Linux 核心 CI 已有。[官方平台范围台账](../research/windterm-2.7.0-platform-scope.md)已固定 2.7.0 的 Windows x86/x64、macOS x64、Linux x64 资产及声明下限;这不是 TermForge 支持或实测结论 | 各平台 PTY/输入/字体/UI/安装与架构覆盖。Windows 7/8/10、macOS 10.13–12、Linux glibc 2.17+ 和未列出的 ARM/旧新系统等按台账分别验收或保留未知,不能由核心 CI 推断产品支持 | R4 / R5 | -| 吞吐、响应、内存与稳定性 | **实现中,未验收**:已有机制实验、连续 CPU 区间校准与合成回归;候选字素改动的受限诊断中 project/interactive 吞吐中位数约下降 16%/9%,由 [#54](https://github.com/JavaZeroo/termforge/issues/54) 跟踪 | 共享宿主、allocator 包装与缺少真实呈现/输入时延端点使该诊断不构成正式预算。仍需同负载/同正确性、无插桩对照、观测开销、长期/多会话公平性和可复核预算;与 WindTerm 的实际差距**待取证** | 持续工作;R4 / R5 收敛 | +| Linux/macOS 与其他架构 | **未实现**客户端;Linux 核心 CI 已有。[官方平台范围台账](../research/windterm-2.7.0-platform-scope.md)已固定 2.7.0 的 Windows x86/x64、macOS x64、Linux x64 资产及声明下限;这不是 TermForge 支持或实测结论 | 最终需真实 Linux/macOS 客户端;平台调查可提前进行,整合及完整验收排在 Windows 11 x64 完整版本之后。其他系统版本、最低版本和架构由用户后续明确;旧系统及 ARM 等保持调查记录,不自动承诺或排除,也不能由核心 CI 推断产品支持 | 持续调查;R5 全平台出口 | +| 吞吐、响应、内存与稳定性 | **实现中,未验收**:已有机制实验、连续 CPU 区间校准与合成回归;候选字素改动的受限诊断中 project/interactive 吞吐中位数约下降 16%/9%,由 [#54](https://github.com/JavaZeroo/termforge/issues/54) 跟踪 | 共享宿主、allocator 包装与缺少真实呈现/输入时延端点使该诊断不构成正式预算。仍需同负载/同正确性、无插桩对照、观测开销和长期/多会话公平性;可靠原版基线后提出逐项预算及允许波动范围,**由用户明确确认**。与 WindTerm 的实际差距**待取证** | 当前优先;贯穿 R1–R5 | | 大历史与动态内存压缩 | **未实现**产品能力;WindTerm 压缩属于官方性能声明,内部机制尚未证实 | 1/10/100 万行等明确规模下的内存/滚动/搜索/淘汰实验;根据瓶颈决定独立存储/压缩实现 | R4 | -| 完整目标验收 | **待取证**:已有固定版本和局部观察,没有完整行为/性能对照矩阵 | 全部目标行均有实现、验收与来源;剩余差异有明确裁决,支持平台可从源码复建;不依赖 WindTerm 二进制或专有资源 | R5 | +| 完整目标验收 | **待取证**:已有固定版本和局部观察,没有完整行为/性能对照矩阵 | 先在 Windows 11 x64 完整验收功能/行为/UI/性能及独立构建,再完成 Linux/macOS 全平台出口;重要差异和性能容差须有用户确认,Windows 通过不代表全平台完成;不依赖 WindTerm 二进制或专有资源 | R5 分平台出口 | -官方已知限制属于对照边界,不自动变成必须新增的功能或必须重现的缺陷。例如 tmux 嵌套及其与 Sender/SyncInput 的限制、Windows ZMODEM 非 ASCII 文件名问题,应记录实际差异。项目完整开源不要求复制 WindTerm 的私有实现、资源或错误;行为兼容与独立改进须明确标注。 +官方已知限制属于对照边界,默认以固定原版实际行为为准。例如 tmux 嵌套及其与 Sender/SyncInput 的限制、Windows ZMODEM 非 ASCII 文件名问题,应记录原版证据和差异;明确缺陷的修正或重要独立改进先提交用户确认。项目完整开源不要求内部实现一致,但不能以规范、第三方核心或现有项目策略自动豁免行为差距。 diff --git a/docs/PLAN.md b/docs/PLAN.md index 540721ef..bc582c29 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -4,6 +4,10 @@ 目标是以完整开源、可维护、可独立构建的实现,复刻官方 WindTerm 2.7.0 的可观察功能、操作行为、界面和性能。用户应能完成相同的工作,而不仅是看到相似布局。完整复刻不要求恢复私有源码;它要求固定目标矩阵中的每一项都具有独立实现和验收证据。 +用户已确认上述第一目标及 [ADR-0006](adr/0006-confirmed-project-direction.md) 的决策边界。首个完整版本以 **Windows 11 x64** 为验收环境,最终覆盖 Windows、Linux、macOS。其他系统版本、最低版本和架构列为待明确范围;官方历史支持声明是调查输入,不自动成为首个 Windows 版本的验收承诺。 + +默认以 WindTerm 2.7.0 的实际行为为准。与通用规范、第三方核心或现有项目策略冲突时,记录原版证据并按原版对齐;明确缺陷的修正方案及重要差异由用户确认。认真研究、借鉴原版公开代码与关键机制,内部结构不要求一致。 + 主要对照固定为官方 **2.7.0 Windows x64** 发行包,EXE SHA-256 为 `7b10531dccc7cd614ae559f36f1ef518e0c96335637431b4646354823b2804d0`。原安装目录中的不同 EXE 不混入该基准。其他平台、架构及版本的支持范围也必须列入目标矩阵并逐项处理,不能把 Windows 原型或 Linux 核心 CI 当成完整跨平台产品。 官方 `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)。官方声明、发行物静态事实、实际运行观察和本项目实现结果分别记录,前一类不能替代后一类。 @@ -14,23 +18,23 @@ **R1 基础文字交互已按限定合同验收,当前推进 R2,尚未达到开发版出口。** 下一次产品交付是在明确支持的 Windows 环境中可靠运行本地 shell 和固定 TUI、恢复工作配置,并提供可复建的开发包。当前各构建配置已做什么见 [FEATURES](FEATURES.md);R2 的接续顺序、并行工作和出口检查只在 [R2 交付路线与验收](milestones/R2-local-terminal.md)维护,实时进度由 [GitHub 执行项](TRACKING.md)承接。 -[平台范围](../research/windterm-2.7.0-platform-scope.md)与 [ADR-0003](adr/0003-core-reference-and-reuse.md)已为 R2 确定候选核心的实施路线。最终产品核心/GUI/平台边界仍由 #34 使用实际工作流与性能证据定案;局部路线决定、原型或 Alpha 均不代表可日常替代 WindTerm。 +[平台范围](../research/windterm-2.7.0-platform-scope.md)与 [ADR-0003](adr/0003-core-reference-and-reuse.md)保存已有调查和候选实验。Alacritty 代码保留为候选,与自主实现路线继续比较;#20/#26 的历史完成不代表用户确认采用。最终核心/GUI/平台边界由 #34 提交实际工作流、WindTerm 对标、成本及维护取舍,用户确认后定案;原型或 Alpha 均不代表可日常替代 WindTerm。 “完整复刻”同时包含功能、行为、UI、性能和交付,不能用单一完成比例概括。全量目标台账必须提前建立;性能测量和定向逆向从现在持续进行,远期路标表示验收位置,而不是推迟开始的日期。 ## 五个路标 -按用户价值划分五个路标,下面从远到近展开;实际主线按 R1 → R2 → R3 → R4 → R5 推进。远期只拆功能域,进入执行前再形成可验收的小任务。 +保留五个路标编号,下面从远到近展开;主线优先对齐终端基础能力和性能,再推进 SSH/SFTP 及其余功能。R1 → R2 → R3 → R4 → R5 首先完成 Windows 11 x64;R5 内先验收 Windows 完整版本,再完成 Linux/macOS 扩展和全平台出口。远期只拆功能域,进入执行前再形成可验收的小任务。 | 路标 | 达成后的能力 | 主要验收边界 | |---|---|---| -| R5 完整 2.7.0 复刻验收 | 在固定目标范围内用 TermForge 完成 WindTerm 2.7.0 的工作 | 全功能、行为、UI、平台、性能和交付矩阵逐项闭合 | -| R4 高级工作流、多协议与跨平台 | 使用专业终端的高级文本、自动化、多协议和跨平台工作流 | 高级功能域完成整合;实际客户端跨平台验证;性能差距收敛 | +| R5 完整 2.7.0 复刻验收 | 先在 Windows 11 x64 完整替代,再扩展 Linux/macOS | Windows 和全平台分别验收全功能、行为、UI、性能及交付;Windows 通过不关闭全平台总项 | +| R4 高级工作流、多协议与性能收敛 | 在 Windows 完成高级文本、自动化、多协议和完整工作区 | Windows 高级功能整合及性能收敛;跨平台可行性调查可提前推进 | | R3 Windows 远程日常版 | 可靠使用 SSH、文件传输和多会话完成远程工作 | 认证与身份、传输完整性、异常恢复、会话管理及持续运行 | | R2 可靠本地终端与开发版 | 日常使用本地 shell 和常见 TUI,重启后恢复工作配置 | 终端兼容、复杂文字、实际 DPI、持久化、真实应用与可分发构建 | | R1 基础文字交互 | 浏览历史、选择复制、粘贴、搜索,并完成基础中文输入 | 文字与输入正确,多个会话隔离,持续输出时仍可操作 | -性能与自动调查贯穿所有路标。R3 的协议库与测试环境调查、R4 的平台可行性调查可以提前并行;这不改变各路标的验收条件,也不要求先完成整个远期功能域才交付近期能力。 +性能与原版研究贯穿所有路标,终端基础能力及性能是当前优先工作。R3 协议库、受控环境及 Linux/macOS 可行性调查可以提前并行;完整 Linux/macOS 客户端不作为 Windows 完整版本的前置,仍是最终必需交付。 ## 逆向工作的安排 @@ -41,7 +45,7 @@ | R5 | 全量目标是否遗漏;各平台和异常状态是否仍有未知差异 | 每个目标 ID 对应来源、实现、复验与差异裁决;完整矩阵审计 | | R4 | 高级文本/自动化、其他协议、tmux 整合如何交互;已测瓶颈对应什么机制 | 按功能域的状态与动作合同;有测量支持的历史存储/调度等机制实验 | | R3 | 连接/断线/重连、身份提示、文件操作与冲突反馈如何变化 | 受控本地服务下的会话状态转换、文件操作和故障场景 | -| R2 | TUI 切换、屏幕恢复、resize、设置保存及实际 DPI/字体如何表现 | 固定应用轨迹、前后状态与配置恢复合同;规范和独立参考裁决 | +| R2 | TUI 切换、屏幕恢复、resize、设置保存及实际 DPI/字体如何表现 | 固定应用轨迹、前后状态与配置恢复合同;原版行为优先,规范与独立参考用于解释差异 | | R1 | 历史跟随、选择单位、复制文本、粘贴确认、查找与焦点如何工作 | 两次无人值守运行的输入/动作/结果记录,形成 R1-01 合同 | 优先比较可观察行为;需要解释默认值、调用分支或性能瓶颈时再定位二进制路径。每个调查都有待回答问题和停止条件;产物进入对应任务和证据索引,不另建一条无法验收的“恢复全部私有源码”主线。 @@ -50,19 +54,21 @@ **用户结果:** 不再需要因目标矩阵中的功能、交互或性能缺口回到 WindTerm 2.7.0;源码、依赖、资源、测试和构建流程均可获得。 +分两个出口管理:**先完成 Windows 11 x64 的完整复刻验收**,允许独立交付该平台的完整版本;随后实现和验收 Linux/macOS 客户端及已确认的扩展平台矩阵。Windows 出口通过时,全平台总项仍保持未完成。后续系统版本/架构的范围须由用户明确,不从官方资产清单或当前 CI 环境自动推导。 + 工作块: - **功能与行为闭合。** 对固定目标清单逐项验收,包括不在首批日常路径中的设置、菜单、会话状态、错误恢复和边界行为。清理仍为“未知”“仅静态线索”“只有布局”的项目。 - **UI 与操作闭合。** 在固定状态、字体、DPI、窗口尺寸和输入上下文下比较布局与操作结果;覆盖弹窗、面板、工作区、快捷键和持久化后的状态。视觉误差与功能差异分别验收。 -- **性能与稳定性闭合。** 在共同功能配置下验证吞吐、交互响应、CPU、内存、历史规模、传输、多会话公平性和长时间运行;给出原始样本身份、正确性、误差与适用范围。 -- **平台与交付闭合。** 固定平台、系统版本、架构及安装/便携方式的支持矩阵;完成真实客户端验证、可复建发布、依赖来源和许可、升级/迁移与故障恢复。 +- **性能与稳定性闭合。** 在共同功能配置下逐项验证吞吐、交互/滚动/搜索响应、CPU、内存/长期增长、历史规模、传输和多会话公平性;给出原始样本身份、正确性、误差与适用范围。各指标门槛及允许波动范围由用户在可靠基线后确认;未确认或未测项不能计为完整复刻通过。 +- **平台与交付闭合。** 首先在 Windows 11 x64 核对完整矩阵、可复建发布、依赖来源和许可、升级/迁移与故障恢复。随后完成 Linux/macOS 的 PTY、输入法、字体、窗口、剪贴板、会话和打包整合及真实客户端验证;按用户确认的系统/架构范围逐平台复验,核心 CI 不代替客户端验收。 - **维护闭合。** 将已确认的参考行为、协议兼容性和性能预算变成持续回归,使后续开发不依赖重新阅读过程记录或个人环境。 **出口条件:** 每个必需矩阵项都有目标依据、实现入口、验证方法和结果,全部达到既定合同。记录了差异不等于消除了差异;缺少环境、未知端点或尚未验证的功能仍是未完成。不得通过减少测试、改变负载、移除功能或静默缩小平台范围宣布完整复刻。确需改变目标时,应明确形成新范围版本,不能用新范围证明原目标已经完成。 -## R4:高级工作流、多协议、跨平台与性能收敛 +## R4:Windows 高级工作流、多协议与性能收敛 -**用户结果:** 从日常远程终端扩展到 WindTerm 的完整专业工作流,各面板和动作背后都有真实功能。 +**用户结果:** 在 Windows 从日常远程终端扩展到 WindTerm 的完整专业工作流,各面板和动作背后都有真实功能。 工作块: @@ -71,10 +77,10 @@ - **高级文本与自动化。** 补齐高亮、折叠、标记/大纲、补全、命令历史、命令面板、Sender、QuickBar、Free Type Mode(用户可见的自由输入模式,具体行为待取证)、同步输入、自动执行及其他已确认的工作流;后台分析必须有预算并可取消。 - **完整工作区。** 完成剩余面板、对话框、模式、主题/颜色、快捷键上下文、多语言、日志及会话操作;分清参考版本支持、参考版本已知限制和本项目额外能力。 - **tmux 深度整合。** 按 2.7.0 的会话、窗口、面板与操作合同实现整合,而不是把“能在终端里运行 tmux”作为完成。参考版本已知不支持的组合不自动升级为本路标必须实现的增强。 -- **跨平台客户端。** 在已记录的产品架构决策上完成 Linux/macOS 等目标平台的真实应用;分别验证 PTY、输入法、字体、窗口、剪贴板、会话和打包。复用核心测试之外仍需平台集成测试。 +- **跨平台准备。** 提前调查 Linux/macOS 的 PTY、输入法、字体、窗口、剪贴板和打包适配,识别影响长期选型的障碍。完整客户端整合与验收在 R5 的 Windows 出口之后完成,不以放弃跨平台换取当前选型便利。 - **性能收敛。** 对大历史、后台搜索、多会话、慢连接、大量小文件及持续输出识别瓶颈,再比较数据布局、缓存、压缩、批处理和调度方案。采用能保持正确性与维护成本的方案,不以恢复 WindTerm 的私有内部结构为前提。 -**出口条件:** 每个声明支持的功能域和平台都有可重复集成环境、失败路径、资源回收及真实工作流验证;功能与性能差距集中到明确的最终验收清单。R5 做的是全矩阵验收和剩余缺口关闭,不重新开始发现基础范围。 +**出口条件:** Windows 的每个声明支持功能域都有可重复集成环境、失败路径、资源回收及真实工作流验证;功能与性能差距集中到明确的最终验收清单。R5 的 Windows 出口核对全矩阵并关闭剩余缺口;Linux/macOS 的整合和验收继续单列,不把其尚未完成视作 Windows 出口失败。 ## R3:Windows 远程日常版 @@ -100,7 +106,7 @@ | 工作包 | 具体事项 | 完成条件 | |---|---|---| -| 核心路线重审 | 依据 ADR-0003 实际构建许可明确的候选核心;用同一输入、状态检查点和真实应用比较继续自研/复用;对六类 pyte 已知差异结合规范与第二参考逐项裁决,保留持续 fuzz 和最小失败回归;记录维护成本与可测量性 | 在 R2 扩大终端模式与常用 TUI 实现投入前形成可重审结论,不能只比较文档、接口名或语言 | +| 核心路线重审 | 保留 ADR-0003 的实际候选及历史比较;继续对照原版行为、关键性能与维护成本,并研究原版公开代码和机制;规范与其他参考协助解释差异,原版未知项待取证 | 实验可继续;正式选型由 #34 提供具体方案并经用户确认,不能由历史 issue 关闭或候选存在自动确定 | | 备用屏与滚动区域 | 主/备用屏切换、光标/样式恢复、历史隔离;局部滚动、边界、原点/换行模式及保存恢复 | 分块输入、重复切换、区域外保持、resize 交叉用例及参考差分通过 | | TUI 与终端回复 | 按固定真实应用补查询回复、插删、输入/输出模式和必要样式;定义模式与 UI 选择/粘贴的关系 | 应用可进入、操作、退出并恢复主屏;维护明确应用/协议支持矩阵 | | resize 与历史语义 | 核对逻辑行、软硬换行、裁剪/重排、宽字符边界及历史关系;处理与备用屏/滚动区交叉 | 当前物理行 resize 的限制被明确保留或由经验证的新合同取代;状态与真实子进程尺寸一致 | @@ -108,10 +114,10 @@ | 字体与真实 DPI | 明确终端字体来源、网格度量、缺字处理;完成真实显示设置和跨显示器切换 | 实际环境中布局、焦点、编辑框、输入命中和隐藏标签正确;受控消息测试不冒充跨屏验收 | | 本地会话与工作区 | shell 类型、目录/参数、启动失败、退出;真正分屏、标签操作和焦点;核对参考动作上下文 | 固定本地 shell 与多会话真实任务通过;布局存在不等于面板业务完成 | | 持久化 | 会话配置、工作区布局、标题/比例等状态的明确保存范围;原子替换、版本迁移、损坏回退 | 新进程恢复与异常配置场景通过;不会把当前仅保存布局说成完整会话恢复 | -| 产品架构决策 | 根据已实现工作流与测量结果,确定产品 GUI/平台边界、核心与历史接口、传输/呈现隔离、依赖和维护策略 | 在扩大跨平台/远程产品整合前形成 ADR;现有 Win32/DirectWrite 实验不自动锁定最终架构,也不因规划而盲目重写 | +| 产品架构决策 | 根据已实现工作流、原版对标和测量结果,提出核心、GUI/平台、历史接口、传输/呈现隔离、依赖和维护方案 | 在扩大跨平台/远程产品整合前提交具体 ADR,经用户确认后定案;原型投入不锁定架构,性能容差另经用户明确 | | 开发版构建与交付 | 清理实验与产品入口、可分发构建、字体/依赖来源、使用说明、诊断与长时回归 | 干净机器可以构建和使用;功能声明对应可下载产物与真实测试;重复开关会话资源稳定 | -**前置与架构门槛:** [平台切片 #23](https://github.com/JavaZeroo/termforge/issues/23)和[核心关卡 #20](https://github.com/JavaZeroo/termforge/issues/20)已有明确结论,新终端能力按 [ADR-0003](adr/0003-core-reference-and-reuse.md)实施。[全量目标台账 #19](https://github.com/JavaZeroo/termforge/issues/19)的其余调查继续并行。#34 必须使用平台边界、真实工作流、依赖维护成本及性能证据重审产品架构;现有 Win32/DirectWrite 或实验后端不自动成为最终选择。 +**前置与架构门槛:** [平台切片 #23](https://github.com/JavaZeroo/termforge/issues/23)和[核心比较 #20](https://github.com/JavaZeroo/termforge/issues/20)的限定证据保留,候选实验可按 [ADR-0003](adr/0003-core-reference-and-reuse.md)继续。[全量目标台账 #19](https://github.com/JavaZeroo/termforge/issues/19)的调查并行推进。#34 按 [ADR-0006](adr/0006-confirmed-project-direction.md)重审核心与 GUI/后端,提交证据和取舍供用户确认;#20/#26 已关闭不替代该确认,也不要求重做已有实验。 **出口条件:** 固定本地真实任务、TUI、文字输入、配置恢复、真实 DPI 和干净环境发布全部通过;实际支持与已知差异进入功能矩阵。详细验收、证据边界与近期执行顺序见 [R2 出口检查表](milestones/R2-local-terminal.md)。仅普通命令可运行不等同于可靠本地终端。 @@ -138,7 +144,7 @@ 1. 先提出具体问题和合成场景。优先公开文档、许可明确的源码、发行物声明与运行时行为;需要时再做定向二进制调查。 2. 将观察转成输入、状态、动作、结果和边界的合同,分别标记事实、推断、未知与本项目设计选择。静态符号不能代替运行结果。 -3. 使用公开规范和许可明确的组件独立实现。协议、核心状态、历史、会话与呈现应可分别测试;不复制私有源码、资源或未授权资产。 +3. 研究、借鉴许可明确的原版源码和关键机制,选择独立实现或开源组件。协议、核心状态、历史、会话与呈现应可分别测试;不复制私有源码、资源或未授权资产。参考规范用于理解行为,冲突时仍以固定原版为默认依据,明确缺陷的修正另由用户确认。 4. 对相同场景比较状态、文字、几何、动作结果或协议数据,再进行视觉检查。没有参考运行证据的项仍标未知,不用本项目自身测试补成“参考匹配”。 5. 发布精简事实、原创探针与可公开结果;原始二进制、私有提取物及敏感数据留在受控本地。具体规则见 [PROVENANCE](PROVENANCE.md)。 @@ -159,7 +165,8 @@ - 分开接收、解析/状态、历史、布局/绘制、提交与实际呈现;未知端点保留未知。 - 同时覆盖吞吐、交互延迟、CPU、内存、长期增长和多会话公平性。一个数字不能代表整体达标。 - 自动 WindTerm 对照尚不能成立时,继续自有成本分层和回归,但不能据此宣布已经追平。 -- 在可靠基线和共同功能范围明确后确定逐场景预算,按测量瓶颈选择优化;不预设 C++、某个 GUI 框架或恢复同样内部结构就必然达到同样性能。 +- 在可靠原版基线和共同功能范围明确后提出逐场景预算及允许波动范围,与用户明确并记录确认后用于验收;当前没有批准任何数值容差。采样波动、既有诊断护栏和候选间回归数字不自动成为等价标准,不能根据待验结果反填门槛。 +- 按测量瓶颈选择优化;不预设 C++、某个 GUI 框架或恢复同样内部结构就必然达到同样性能。阶段版本如实报告差距,完整复刻必须满足用户确认的各项门槛。 ## 文档与任务保持一致 @@ -168,3 +175,4 @@ - [任务跟踪](TRACKING.md)连接当前 GitHub 任务与依赖;近期任务写清可验收结果,远期保持功能域级别。 - 当前里程碑文档保存详细执行合同;历史研究、评审和样本保留可追溯证据,不再重复充当当前待办清单。 - 路标完成时更新矩阵并核对出口条件;不得只按 issue 关闭数量或代码量报告完成比例。 +- ADR 与 issue 中区分提议、实验实现及用户已确认决定;记录确认日期和依据。目标范围、主要技术路线、验收门槛、重要差异的变更先按 ADR-0006 确认;本轮方向确认不追认全部旧设计或未定细节。 diff --git a/docs/PROVENANCE.md b/docs/PROVENANCE.md index 150127a5..c99fff4f 100644 --- a/docs/PROVENANCE.md +++ b/docs/PROVENANCE.md @@ -10,6 +10,12 @@ 研究报告分别标记观察、推断和未知;公开结果应删除个人路径、账户、主机信息。测试优先采用隔离配置及合成数据。 +## 核心代码来源的记录口径 + +按 [ADR-0006](adr/0006-confirmed-project-direction.md) 认真研究、借鉴原版公开代码及关键机制。模块的实现来源与行为依据分开记录:直接复用 WindTerm 公开源码须注明固定版本、许可和修改;根据原版运行观察或逆向研究形成的实现须链接具体行为/机制证据;按功能合同独立开发须注明合同;Alacritty 等其他开源实现及其修改单独记录上游来源,不能归为 WindTerm 代码。 + +“逆向研究指导的原创实现”和“直接复制反编译输出”是不同来源,不用同一个代码占比混算。无法确定来源时标为待核实,不能自动归入自研。后续核心代码统计须固定提交、构建配置、代码范围及计数方法,并将第三方代码、生成数据与测试/研究工具分列;模块受到原版行为启发不等于其中每行都是原版源码。 + ## 已使用的第三方数据 - `assets/fonts/RobotoMono-Regular.ttf`:从 Google Fonts 的 RobotoMono 官方仓库固定提交独立取得,未修改;适用 SIL Open Font License 1.1,完整版权与许可证随字体分发。字体源码、固定版本、原始链接、字节数和 SHA-256 见[字体来源](../assets/fonts/README.md)。只在 TermForge 进程内作为工作区 UI 字体加载;不是从 WindTerm 提取的资源,不受项目 MIT 许可证覆盖。 diff --git a/docs/README.md b/docs/README.md index ca254be8..96a4f996 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,6 +6,7 @@ |---|---| | 已经能做什么,离目标差在哪里? | [功能与差异矩阵](FEATURES.md) | | 最终目标是什么,如何分阶段完成? | [五个路标,远到近](PLAN.md) | +| 用户确认了什么,哪些决策仍待确认? | [ADR-0006:方向与决策权限](adr/0006-confirmed-project-direction.md) | | R2 分几步交付,当前先做什么、怎样验收? | [R2 交付路线与验收](milestones/R2-local-terminal.md) | | 已验收的基础文字交互合同是什么? | [R1 基础文字交互](milestones/R1-local-text.md) | | 字体、网格和真实显示如何验收? | [R2 字体与显示合同](milestones/R2-font-display.md) | diff --git a/docs/STATUS-AND-BACKLOG.md b/docs/STATUS-AND-BACKLOG.md index c9572a6b..3ab47671 100644 --- a/docs/STATUS-AND-BACKLOG.md +++ b/docs/STATUS-AND-BACKLOG.md @@ -4,6 +4,7 @@ - 已实现能力、未实现功能及证据边界:[FEATURES](FEATURES.md)。 - 从完整 WindTerm 2.7.0 复刻倒推的五个路标:[PLAN](PLAN.md)。 +- Windows 11 x64 优先、原版行为优先、候选保留及确认权限:[ADR-0006](adr/0006-confirmed-project-direction.md)。 - 当前路标的交付顺序、剩余事项和验收:[R2 本地终端与开发版](milestones/R2-local-terminal.md)。 - 已验收的基础文字交互合同:[R1 基础文字交互](milestones/R1-local-text.md)。 - 正在等待实施的任务及真实状态:[TRACKING](TRACKING.md)。 diff --git a/docs/TRACKING.md b/docs/TRACKING.md index 6a03f833..10e239ea 100644 --- a/docs/TRACKING.md +++ b/docs/TRACKING.md @@ -2,12 +2,14 @@ 本页只导航到 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 提供基线和预算提案,性能容差经用户明确后生效。候选实验和既有关闭任务均不自动构成用户确认。 + ## 产品路标 | 路标(远到近) | GitHub milestone | 总项 | |---|---|---| -| R5 · WindTerm 2.7.0 完整复刻验收 | [milestone 6](https://github.com/JavaZeroo/termforge/milestone/6) | [完整目标验收](https://github.com/JavaZeroo/termforge/issues/10) | -| R4 · 高级功能、跨平台与性能收敛 | [milestone 5](https://github.com/JavaZeroo/termforge/milestone/5) | [高级工作流](https://github.com/JavaZeroo/termforge/issues/9) | +| R5 · 完整复刻验收:先 Windows,后全平台 | [milestone 6](https://github.com/JavaZeroo/termforge/milestone/6) | [Windows / 全平台两个出口](https://github.com/JavaZeroo/termforge/issues/10) | +| R4 · Windows 高级功能与性能收敛 | [milestone 5](https://github.com/JavaZeroo/termforge/milestone/5) | [高级工作流与跨平台准备](https://github.com/JavaZeroo/termforge/issues/9) | | R3 · SSH/SFTP 远程日常版 | [milestone 4](https://github.com/JavaZeroo/termforge/milestone/4) | [远程日常版](https://github.com/JavaZeroo/termforge/issues/8) | | R2 · 可靠本地终端与开发版 | [milestone 3](https://github.com/JavaZeroo/termforge/milestone/3) | [当前路标](https://github.com/JavaZeroo/termforge/issues/7) | | R1 · 基础文字交互 | [milestone 2](https://github.com/JavaZeroo/termforge/milestone/2) | [限定验收](https://github.com/JavaZeroo/termforge/issues/6) | @@ -28,7 +30,7 @@ | 查询回复、应用模式与真实 TUI | [固定应用矩阵 #28](https://github.com/JavaZeroo/termforge/issues/28) | #27;完成时核对 #29 的 resize 合同及目标配置 | | 完整 Unicode、IME 与选择/键盘 | [输入工作流 #30](https://github.com/JavaZeroo/termforge/issues/30) | #26/#39 已验;首批字素基础不替代最终配置的真实输入与同次八会话 | | 字体、真实不同 DPI 与跨屏 | [真实显示 #31](https://github.com/JavaZeroo/termforge/issues/31) | 当前为实际环境缺口;自动环境准备可并行,不反复运行相同 96-DPI 场景 | -| 字素吞吐成本定位与预算 | [受控性能 #54](https://github.com/JavaZeroo/termforge/issues/54) | 独立并行;固定负载/端点/重复方法与预算依据,再优化,不等 #34 最后才研究 | +| 字素吞吐成本定位与预算提案 | [受控性能 #54](https://github.com/JavaZeroo/termforge/issues/54) | 独立并行;固定负载/端点/重复方法并归因,预算提案需用户确认,不等 #34 最后才研究 | ## R2 可靠性与聚合关卡 @@ -43,7 +45,7 @@ | Windows 工作流可靠性 | [回归汇总 #38](https://github.com/JavaZeroo/termforge/issues/38) | #40/#44/#57/#72/#73;已闭合切片和旧失败保留在该总项,不再排入当前队列 | | 显式官方 ConPTY 整合 | [后端汇总 #47](https://github.com/JavaZeroo/termforge/issues/47) | #51/#52(GUI)/#53/#63;#62 worker 夹具与 #52 native 捕获已独立修正,#55 已固定实验联合基线,实验可选不等于产品默认或日常验收 | | 每缓冲区 margin 端到端合同 | [margin 汇总 #41](https://github.com/JavaZeroo/termforge/issues/41) | #47/#56;原生 API、transport 和末端分别验证 | -| 产品 GUI/平台与核心边界 | [架构定案 #34](https://github.com/JavaZeroo/termforge/issues/34) | #28–#31/#54,结合已验 #23/#26/#32/#33;维护正式 ADR | +| 产品核心、GUI/平台与呈现边界 | [选型提案与用户确认 #34](https://github.com/JavaZeroo/termforge/issues/34) | #28–#31/#54,结合 #23/#26/#32/#33 和原版对标证据;重审 ADR-0003/0004,记录用户确认 | | 最终 Windows 开发版 | [产物与持续运行 #35](https://github.com/JavaZeroo/termforge/issues/35) | #27–#34/#36/#38;在最终产物上执行完整合同后核对 #7 出口 | ## 已交付基础与历史入口 @@ -52,19 +54,19 @@ |---|---| | R1 基础文字与同次八会话限定验收 | [R1 总项 #6](https://github.com/JavaZeroo/termforge/issues/6)、[组合验收 #18](https://github.com/JavaZeroo/termforge/issues/18)、[合同](milestones/R1-local-text.md) | | Alpha 1 Windows x64 体验包 | [发布切片 #22](https://github.com/JavaZeroo/termforge/issues/22)、[发布说明](releases/v0.1.0-alpha.1.md)、[下载与验证](releases/v0.1.0-alpha.1-validation.json) | -| R2 平台与核心前置 | [平台 #23](https://github.com/JavaZeroo/termforge/issues/23)归属 [全量台账 #19](https://github.com/JavaZeroo/termforge/issues/19);[候选 #24](https://github.com/JavaZeroo/termforge/issues/24)、[差分 #25](https://github.com/JavaZeroo/termforge/issues/25)、[成本/路线 #26](https://github.com/JavaZeroo/termforge/issues/26)归属 [核心关卡 #20](https://github.com/JavaZeroo/termforge/issues/20) | +| R2 平台调查与候选比较证据 | [平台 #23](https://github.com/JavaZeroo/termforge/issues/23)归属 [全量台账 #19](https://github.com/JavaZeroo/termforge/issues/19);[候选 #24](https://github.com/JavaZeroo/termforge/issues/24)、[差分 #25](https://github.com/JavaZeroo/termforge/issues/25)、[成本/历史路线 #26](https://github.com/JavaZeroo/termforge/issues/26)归属 [历史比较 #20](https://github.com/JavaZeroo/termforge/issues/20);限定结项保留,正式选型待 #34 用户确认 | | 有限本地会话与配置恢复 | [本地会话 #32](https://github.com/JavaZeroo/termforge/issues/32)、[持久化 #33](https://github.com/JavaZeroo/termforge/issues/33),能力边界见 [FEATURES](FEATURES.md) | | 首批流式字素、宽度与 glyph | [字素合同 #39](https://github.com/JavaZeroo/termforge/issues/39)、[来源与合同](research/streaming-graphemes.md),完整输入由 #30 继续验收 | | 已闭合的回归/夹具与参考捕获 | #38 的原生子项及 [EVIDENCE](EVIDENCE.md)保留 #37/#42/#45/#46 等固定原因和证据,不再次当作待做功能 | | 旧 M0/G1、批次规格与审查 | [归档说明与迁移表](archive/README.md);历史记录不作为当前 TODO | -## 可提前推进的远期调查 +## 当前优先及可并行的调查 | 工作 | 责任任务与边界 | |---|---| | WindTerm 2.7.0 全量目标与平台台账 | [全量目标 #19](https://github.com/JavaZeroo/termforge/issues/19),R5 验收基础;#23 平台切片完成不代表其余行为已取证 | -| 自动观测、扰动校准与完整 Schema | [观测工具 #3](https://github.com/JavaZeroo/termforge/issues/3),R4 收敛;停止的手工批次不默认重启 | -| 正式 WindTerm 性能基线 | [受控对照 #4](https://github.com/JavaZeroo/termforge/issues/4),依赖 #3;不能用自有微基准替代 | +| 自动观测、扰动校准与完整 Schema | [观测工具 #3](https://github.com/JavaZeroo/termforge/issues/3),当前优先支持 Windows 本地终端对照,扩展覆盖持续至 R4;停止的手工批次不默认重启 | +| 正式 WindTerm 性能基线 | [受控对照 #4](https://github.com/JavaZeroo/termforge/issues/4),依赖 #3;优先 Windows 11 x64 本地终端,给用户提供容差提案,不能用自有微基准替代 | | Server 2022 ConPTY 稳态句柄 | [兼容性 #21](https://github.com/JavaZeroo/termforge/issues/21),R4;严格门槛与已知失败保留,不扩大支持声明 | 任务完成时更新责任 issue、能力行与证据索引。修改合同时同步规格和原生关系;记录未知或整理文档本身不解除产品出口。维护规则见 [issue tracker 约定](agents/issue-tracker.md)。 diff --git a/docs/adr/0001-evidence-before-stack.md b/docs/adr/0001-evidence-before-stack.md index d7456d4d..1f111a5f 100644 --- a/docs/adr/0001-evidence-before-stack.md +++ b/docs/adr/0001-evidence-before-stack.md @@ -1,11 +1,11 @@ # ADR-0001:性能证据先于技术栈 -- 状态:性能证据原则保持接受;先完成完整基线再开始原型的顺序由 [ADR-0002](0002-automation-first-investigation.md) 修订 +- 状态:证据原则由 [ADR-0006](0006-confirmed-project-direction.md) 确认;原型执行顺序由 [ADR-0002](0002-automation-first-investigation.md) 修订,具体栈与性能容差仍待用户确认 - 日期:2026-10-19 ## 背景 -项目需要接近 WindTerm 的速度和资源效率,同时易于维护。仅凭语言、GUI 框架或渲染 API 无法预测完整应用表现。早期考虑的现成客户端/Electron 路线尚未进行性能验证,不能作为已定方案。 +项目以 WindTerm 2.7.0 关键指标达到同等性能水平为目标,同时易于维护;允许波动范围在可靠基线后与用户明确。仅凭语言、GUI 框架或渲染 API 无法预测完整应用表现。早期考虑的现成客户端/Electron 路线尚未进行性能验证,不能作为已定方案。 ## 决策 @@ -15,4 +15,4 @@ ## 后果与重审 -短期交付以测量工具和规格为主,应用功能启动较晚,但避免围绕错误假设积累大量代码。M0/M1 结束后用新的 ADR 固定首个实现方案;重大负载变化或回归可以触发重审。 +本 ADR 最初要求先完整测量再启动应用;该顺序已由 ADR-0002 修订为自动调查与独立原型并行。当前按 R1–R5 推进,先对齐终端基础能力与性能;主要技术路线和性能门槛按 ADR-0006 提交证据供用户确认。历史 M0/M1 名称及早期候选保留原义,不构成现行选型。 diff --git a/docs/adr/0002-automation-first-investigation.md b/docs/adr/0002-automation-first-investigation.md index 1a6390ee..7f9bbfb3 100644 --- a/docs/adr/0002-automation-first-investigation.md +++ b/docs/adr/0002-automation-first-investigation.md @@ -2,7 +2,7 @@ > 本决策继续有效。当前能力见 [FEATURES](../FEATURES.md),任务见 [TRACKING](../TRACKING.md);旧工作包与工具安装过程见[历史版本](https://github.com/JavaZeroo/termforge/blob/c386494587656faa3d8621f7ddbf43a6aa678255/docs/adr/0002-automation-first-investigation.md)。本页只维护决策和执行约束。 -- 状态:接受 +- 状态:自动执行原则保持接受;重大决定的确认权限由 [ADR-0006](0006-confirmed-project-direction.md) 明确 - 日期:2026-10-22 - 修订 ADR-0001 的执行顺序,保留其性能证据与正确性要求。 @@ -16,7 +16,7 @@ 1. 默认交付可由代理执行的 CLI、脚本或测试。测试循环不要求用户新建会话、输入 y、复制结果或确认每一轮。仅确实需要用户作出的产品选择或外部权限决定才请求介入。 2. 不再扩展现有手工校准流程,也不把补齐该批次作为项目推进前提。旧记录保留,旧工具供可选人工诊断使用,不是默认入口。 -3. 调查与小型原型可以交替推进;正式性能选型和等价结论仍依赖充分证据。缺少完整 WindTerm 基线时,可以验证自己的正确性、各层成本与候选设计,预算明确暂定。原 M0/M1 名称已由当前 R1–R5 路线接续。 +3. 调查与小型原型可以交替推进;正式性能选型和等价结论仍依赖充分证据。缺少完整 WindTerm 基线时,可以验证自己的正确性、各层成本与候选设计;测试护栏或预算提案不等于验收标准。具体性能波动范围必须在可靠基线后与用户明确,主要技术路线也由用户确认。原 M0/M1 名称已由当前 R1–R5 路线接续。 4. 定向逆向优先使用无界面的分析与导出。初期研究范围为接收/线程协作、屏幕/历史存储、绘制调度;2026-10-23 路线整理后,范围由 [PLAN 的逆向安排](../PLAN.md#逆向工作的安排)和当前路标合同接续,包含文字操作、UI、会话及其他需要复刻的行为。每个问题输出事实、推断、未知、下一项独立实验,不以恢复整个私有源码为目标。 5. WindTerm 动态自动化先验证单次闭环,再建设批量运行。使用测试专用 profile 和受控 producer/服务端,每种场景单独验证建连、结果和回收。不得把“可以启动 EXE”当成“可以自动建立会话、验证画面并完成测试”;已验证范围从证据索引查阅。 6. 自动化入口不可用时,记录具体缺口并转向静态分析或自有原型;不回退为反复要求用户操作。遵守工具实际支持范围和操作规则,不通过换一套按键注入规避限制。 @@ -28,7 +28,7 @@ - 输出:机器可读原始数据、自动一致性检查、简短报告、明确测量端点。 - 自有原型可暴露解析完成、状态摘要、帧提交等测试接口,但这些端点不等价于 WindTerm 的黑盒端点;帧提交也不等价于显示完成。 - 需要可见桌面的渲染实验另列环境要求;没有画面证据时只完成可验证部分,不降低标准或把 producer_done 改名为 presented_done。 -- 在已授权的仓库工作中,代理完成代码、验证、脱敏报告、提交和推送;用户无需审批每个小步骤。外部必要权限仍按实际环境处理,不承诺自动绕过权限。 +- 在已授权的仓库工作中,代理完成代码、验证、脱敏报告、提交和推送;用户无需审批每个小步骤。目标范围、主要技术路线、验收门槛和重要行为差异依 ADR-0006 单独确认;自动执行授权不等于最终选型授权。外部必要权限仍按实际环境处理,不承诺自动绕过权限。 ## 结果与执行入口 diff --git a/docs/adr/0003-core-reference-and-reuse.md b/docs/adr/0003-core-reference-and-reuse.md index ded88186..e7e8afdc 100644 --- a/docs/adr/0003-core-reference-and-reuse.md +++ b/docs/adr/0003-core-reference-and-reuse.md @@ -1,11 +1,19 @@ # ADR-0003:差分参考与可重审的核心路线 -> 本文保留 C1/G1 等旧代号和当时的比较结果。2026-10-25 已由 [#20](https://github.com/JavaZeroo/termforge/issues/20)/[#26](https://github.com/JavaZeroo/termforge/issues/26) 完成 R2 重审;现状见 [FEATURES](../FEATURES.md)。 +> 本文保留 C1/G1 等旧代号和当时的比较结果。2026-10-25 由 [#20](https://github.com/JavaZeroo/termforge/issues/20)/[#26](https://github.com/JavaZeroo/termforge/issues/26) 完成的候选比较继续作为证据,正式选型按下方当前决定重新评估;能力现状见 [FEATURES](../FEATURES.md)。 -- 日期:2026-10-22;重审:2026-10-25 -- 状态:已接受 R2 复用候选核心的路线;产品整合尚未验收 +- 日期:2026-10-22;历史重审:2026-10-25;用户方向确认:2026-10-26 +- 状态:保留 Alacritty 作为候选;正式核心选型待用户确认。2026-10-25 的路线决定已被 [ADR-0006](0006-confirmed-project-direction.md) 的候选定位替代 - 对应任务:C1;R2-00 至 R2-03 +## 当前决定与确认边界 + +用户已确认保留 Alacritty 的代码和实验材料,重新按 WindTerm 2.7.0 的行为、关键性能及长期维护成本评估;不强求原版内部结构一致,但应认真研究、借鉴原版公开代码和机制。现有自研 C++ 核心与外部候选的证据均保留,允许继续可替换的实验和兼容修复。 + +正式核心选择由 [#34](https://github.com/JavaZeroo/termforge/issues/34) 提供具体方案、原版对标、性能及维护取舍,用户确认后生效。#20/#24–#26 已完成的是其限定研究和实验;关闭状态、过去的“Accepted”或已有适配器不能替代用户确认。性能允许波动范围同样待与用户明确,旧候选成本不等于 WindTerm 等价预算。 + +行为冲突默认以 WindTerm 2.7.0 实际行为为准;pyte、Alacritty、规范及现有项目合同是比较材料,未知原版行为继续取证。下面保留历史比较和当时的工程选择,供复验与重审,不作为强制采用某核心的当前指令。 + ## 问题 现有自研核心已经能回放有限文本、样式和历史,但单靠自己写预期容易把实现行为误当协议。若继续逐项扩展到完整终端,错误恢复、模式交互、Unicode、resize 和应用兼容性的维护成本会增长。完整开源允许复用开源核心;语言本身不构成性能证据。 @@ -24,14 +32,14 @@ 维护负担列为具体缺口,未虚构工时或使用代码行数衡量质量。 -## 决定 +## 初始实验决定(历史) 1. **保留现有核心用于受限实验和 G1 的有限集成,pyte 只作为测试依赖。** 不将这一临时安排升级为长期自研承诺,不发布性能等价声明。 2. 将可替换边界固定在“字节 feed → 可检查状态/变更 → 独立呈现”之间。参考适配不得依赖 GUI;自研核心、传输、呈现分别可测。当前 trace 是测试协议,未来产品状态接口仍需针对一致性/增量更新设计。 3. 共同子集每次变更执行差分;已知差异单独精确检查。错误恢复等不在共同子集的功能先定义行为,再增加负面与差分测试。参考结果与规范或产品策略冲突时保留复现并裁决,不机械追随任何一个实现。 4. C2 可在现有核心上补有界恢复,T1/V1 可继续独立推进。进入完整 TUI 功能扩张前,启动一个可构建的外部核心适配切片,再作产品路线决定。 -## 必须重审的关卡 +## 外部候选比较关卡(历史要求,结果继续复用) 当前关卡对应 R2:扩大终端模式与常用 TUI 的实现投入前,使用同一批字节轨迹至少比较自研和一个实际构建的外部候选;仅有库名或 README 不满足此条件。候选构建与共同子集/历史投影适配可以在 R1 期间并行进行,不要求先把自研核心补成完整终端,也不等待正式 WindTerm 基线。具体补齐: @@ -46,10 +54,12 @@ 当时完成固定参考、共同子集逐检查点/随机拆包差分、失败复现、策略差异记录与临时路线 ADR;产品级选择、外部原生候选与性能评估保留到下列 R2 重审。 -## R2 重审决定(2026-10-25) +## R2 重审决定(2026-10-25,正式选型效力已被替代) 完整的平台、维护、兼容修复与接口证据见 [R2 原生核心路线重审](../research/2026-10-25-core-route-review.md)。 +以下七项记录当时为何推进该实验,并保留其版本、接口和限制。当前继续哪些实验、最终保留/改造/替换哪条路线,遵循上方“当前决定与确认边界”,不再沿用下文的排他选型要求。 + 1. **R2 新终端能力复用 `alacritty_terminal` 的 `Term` / `Processor`,不再沿自研核心扩展完整 VT/TUI。** 原始比较版本为 0.26.0,后续整合的精确版本与兼容补丁以[来源台账](../../experiments/candidates/alacritty/PROVENANCE.md)为准。该次重审的备用屏、滚动区、回复、resize、真实应用与共同 feed 计量支持复用路线;这不是后续版本的性能预算通过证明,新增字素成本另由 [#54](https://github.com/JavaZeroo/termforge/issues/54)处理。 2. **只复用核心,不锁定候选 PTY/event loop。** 保留现有 ConPTY/传输、OutputQueue/InputQueue 背压、会话生命周期和 UI 所有权。终端 `PtyWrite` 经有界输入队列发送;其他事件按产品合同处理。 3. **保留自研 C++ 核心作为 R1 回退和独立差分参考。** 候选的显式原型接入不自动替换默认会话;替换须通过相同文字、选择、搜索、IME、多会话和资源回归。#27–#30 按选定路线实施,#34/#35 的产品与路标验收不变。 diff --git a/docs/adr/0004-presentation-backend.md b/docs/adr/0004-presentation-backend.md index 5505a4cd..082d874c 100644 --- a/docs/adr/0004-presentation-backend.md +++ b/docs/adr/0004-presentation-backend.md @@ -3,9 +3,11 @@ > A1/G1/G2 为历史代号;首个本地窗口已进入当前原型。后端与平台边界的重审归入 [R2 产品架构决策](../PLAN.md),须在扩大远程和跨平台产品整合前完成,不能以本 ADR 将实验后端永久定案。 - 日期:2026-10-23 -- 状态:临时接受;仅覆盖 Windows 的 A1/G1 实验,不锁定产品后端或跨平台栈。 +- 状态:历史实验选择保留;仅覆盖 Windows 的 A1/G1 实验,产品 GUI/呈现/后端选型待用户确认。 - 前置:[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。具体性能容差尚待用户明确。 + ## 问题与候选 需要把现有终端状态可靠地画进窗口,并让接收、解析和画面可以独立验证。先在 GDI `DrawText` 与 DirectWrite layout + Direct2D 软件 DC target 两个小候选中比较正确性可观测性、资源复用和接入成本。不据语言标签、主观速度或一次 draw 时长决定产品栈。 diff --git a/docs/adr/0005-physical-row-resize.md b/docs/adr/0005-physical-row-resize.md index 31716f39..bdc2b748 100644 --- a/docs/adr/0005-physical-row-resize.md +++ b/docs/adr/0005-physical-row-resize.md @@ -2,11 +2,13 @@ > 本文保留 C5 当时的物理行合同与实现记录。窗口章节中的固定度量和尺寸约束已由后续 DPI/zoom 实现扩展;现行窗口行为见 [shell 说明](../../experiments/shell/README.md),完整现状见 [FEATURES](../FEATURES.md)。 -日期:2026-10-23。状态:C5 / G1 实验采用,产品布局定案前重审。 +日期:2026-10-23。状态:默认/候选实验行为记录保留;原版一致性与最终产品策略由 #29 / #34 重审,重要差异待用户确认。 + +按 [ADR-0006](0006-confirmed-project-direction.md),WindTerm 2.7.0 实际行为优先。本页的裁剪、历史回填、8192 字节重放边界等是现有实现合同;其自身回归通过不构成原版匹配,也不代表用户批准内容丢失等差异。#29 补原版对照并区分匹配、未知和差异;明确原版缺陷的修正或其他重要差异提交用户确认。历史样本和当前回归护栏保留。 ## 决策与范围 -`Screen::resize(rows, columns)` 接受 1–200 行、1–500 列。该阶段的自研解析器采用物理行裁剪,不推断逻辑段落,不重排软换行或硬换行;此默认策略继续保留。缩窄造成的信息丢失是公开的功能限制,不用作吞吐优化依据。候选的软换行元数据与独立补充合同见下文;完整 reflow、备用屏、滚动区交叉语义由 #29 验收。 +`Screen::resize(rows, columns)` 接受 1–200 行、1–500 列。该阶段的自研解析器采用物理行裁剪,不推断逻辑段落,不重排软换行或硬换行;这是默认构建的当前行为。缩窄造成的信息丢失是公开的功能限制,不用作吞吐优化依据,也不因此成为最终目标策略。候选的软换行元数据与独立补充合同见下文;原版对照、完整 reflow、备用屏、滚动区交叉语义由 #29 验收。 - 尺寸未变是严格 no-op,保留待换行和组合字符附着。 - 实际尺寸变化时,保留左侧单元格;右侧被截去的内容不会在增宽后恢复。宽字符若在右边界被截断,整个字符及组合标记清空为默认样式空格。可见行和历史行遵循同一列宽规则,完整保留的字符保持文字、组合标记和样式。 diff --git a/docs/adr/0006-confirmed-project-direction.md b/docs/adr/0006-confirmed-project-direction.md new file mode 100644 index 00000000..b1bb98e7 --- /dev/null +++ b/docs/adr/0006-confirmed-project-direction.md @@ -0,0 +1,36 @@ +# ADR-0006:完整复刻目标、Windows 优先与决策确认 + +- 状态:已确认 +- 日期:2026-10-26 +- 决策者:项目负责人(用户) +- 确认依据:本次 `$grill-me` 逐项讨论及最终确认“可以的 包括issues等等”。下表记录确认的含义;不将此前 ADR 的状态、提交作者或 issue 关闭解释为用户确认。 +- 范围与执行入口:[PLAN](../PLAN.md)、[FEATURES](../FEATURES.md)、[TRACKING](../TRACKING.md)。本文保存决策依据和权限边界,不维护第二份路线或进度表。 + +## 已确认的方向 + +| 决策 | 确认内容与依据 | +|---|---| +| 第一目标 | 用户明确“将windterm开源出来”是第一目标。交付完整开源、可独立构建的实现,完整复刻功能、操作行为、界面和性能。 | +| 内部实现 | 用户选择外部行为等价,不强求内部结构一比一,同时要求尽可能研究、借鉴原版代码与关键机制。公开源码复用、逆向研究指导的实现、自主开发及其他开源组件均可作为手段;具体来源仍遵守 [PROVENANCE](../PROVENANCE.md)。 | +| 固定版本 | 用户明确“固定windterm2.7.0”;版本升级另行确认,当前任务不追随最新发行版扩大目标。 | +| 平台与首个完整版本 | 用户明确“最终目标是全平台,但是首要目标是我们的windows”,并确认以 Windows 11 x64 为首个完整版本验收环境。最终覆盖 Windows、Linux、macOS;其他系统版本、最低版本和架构仍需单独明确。 | +| 推进顺序 | 先对齐终端基础能力与性能,再逐步接入 SSH、SFTP 和其余功能。平台可行性及独立调查可并行;Linux/macOS 的完整客户端验收不阻塞首个 Windows 完整版本。 | +| Alacritty | 用户确认“可以保留”。保留已有代码与证据,重新作为待评估候选;比较目标行为、性能及维护成本后,再确认正式核心选型。 | +| 性能标准 | 吞吐、交互/滚动/搜索延迟、CPU、内存/长期增长及多会话关键指标分别达到原版同等水平。用户明确“具体的波动范围需要后续与我明确”;当前没有获得任何数值容差的批准。 | +| 行为裁决 | 用户明确“原版优先”。与通用规范、第三方核心或既有项目策略冲突时,默认以固定原版的实际行为为准;明确缺陷的修正方案另由用户确认。未知目标行为继续调查,不计为匹配。 | +| 决策权限 | 目标范围、主要技术路线、验收门槛和重要差异由用户确认;已确认方向内的研究、逆向调查、候选实验、具体实现、测试和修复由代理自主推进。 | + +## 对现有路线的处理 + +- [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-0005](0005-physical-row-resize.md)、字体/网格、字素、选择等现有合同仍用于准确描述实现和防止回归。它们与原版的匹配情况须另验;重要差异不因测试通过或写成合同而自动获准。 +- 已完成的构建、实验和限定验收保留原来源、结果和历史状态。当前问题由现有责任 issue 接续;不因方向重审重开全部已关闭任务,也不关闭真实缺口。 + +## 后续决定如何生效 + +重大决定先以“提议 / 待用户确认”记录,包含问题、候选及取舍、证据、未测项、影响的目标和后续工作。用户确认后才标为“已确认”,注明日期及确认依据;被替代的结论保留历史标记。实验实现状态与产品决策状态分开记录。 + +性能工作先建立可靠的原版基线,给出逐场景指标、重复样本、噪声和容差提案,再与用户明确并记录确认。确认后的门槛用于后续验收;不得根据待验结果反填一个刚好能通过的数值。既有诊断、测试超时和资源护栏保留原含义,不自动成为用户认可的 WindTerm 等价标准。 + +候选比较、证据准备和无依赖的实现工作可以自主继续;将候选正式采用、改变目标范围或接受重要行为差异前,提交具体可审查方案。源码可用、CI 通过、issue 关闭及 ADR 的旧“Accepted”文字均不替代这一步确认。 diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index da10bdd8..f47e9c56 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -9,4 +9,8 @@ - 使用原生 sub-issue 和 blocked-by 关系;任务正文也列出依赖,便于源码环境阅读。修改依赖时同步正文和关系,不以大路标的顺序制造不必要串行。 - 开工先核对 issue、当前 milestone 和工作树,固定本次审查基点;提交验收结果后更新对应能力行并关闭任务。不要把完整产品工作长期塞进旧研究 issue。 - 改范围先改规格,再同步 issue;移动到归档的记录是当时的证据,不能作为当前待办。原始结果/已知失败不因文档整理而改写。 +- 按 [ADR-0006](../adr/0006-confirmed-project-direction.md) 区分调查/实验实现与正式产品决定。范围、主要技术路线、验收门槛和重要差异先写提案、证据及影响,由用户确认后生效;记录确认日期和依据。历史 ADR、代码合并及 issue 关闭不代替用户确认。 +- 方向变化时更新受影响总项和执行项的当前合同;已完成的限定实验可保留关闭状态,在正文标明当前决定由谁接续。新发现的原版差异保持未完成,不改写历史结果或批量重开已验证工作。 +- #10 分别跟踪 Windows 11 x64 完整出口和后续 Linux/macOS 全平台出口;后者未完成时总项保持开放。其他系统版本/架构范围待用户明确,不从官方资产清单自动推导。 +- #3/#4 的原版基线和 #54 的候选成本研究可以自主执行;数值预算及允许波动范围作为提案,与用户明确后才用于性能验收。提案/待确认不写作性能通过。 - 规划整理不自动算功能交付;功能开始实施时另行记录源码基点与验收。旧任务和新路标的映射见 [归档说明](../archive/README.md)。 diff --git a/docs/milestones/R1-local-text.md b/docs/milestones/R1-local-text.md index 207c0169..c73769c8 100644 --- a/docs/milestones/R1-local-text.md +++ b/docs/milestones/R1-local-text.md @@ -1,5 +1,7 @@ # R1:基础文字交互复刻 +> 下文保留已完成的限定实现合同。按 [ADR-0006](../adr/0006-confirmed-project-direction.md),当前完整复刻以原版行为为默认依据;未对照策略与重要差异继续在目标矩阵/责任任务中调查并提交用户确认,R1 关闭不表示全部行为或容量限制已获最终批准。 + **状态:已按本合同限定范围验收。** 固定源码`ce9b24d`的[整体验收](../../experiments/shell/results/2026-10-24-r1-system-workflow/validation.json)结合R1-01–07及同源码回归,验证了真实八会话完整文字工作流。当前不含常用TUI、全部输入法、真实跨屏、长期无泄漏或WindTerm性能等价;下一路标见[总体计划](../PLAN.md)。下文保留交付合同与验收边界。 目标:用户在两个区域的真实本地会话中完成“输出日志 → 回看历史 → 查找 → 选择复制 → 粘贴 → 中文输入 → 切换/缩放 → 退出”。这是一条能完整操作的工作流,不以增加菜单或空面板计完成。 diff --git a/docs/milestones/R2-font-display.md b/docs/milestones/R2-font-display.md index fffcaab9..e2968b2b 100644 --- a/docs/milestones/R2-font-display.md +++ b/docs/milestones/R2-font-display.md @@ -2,6 +2,8 @@ 对应 [#31](https://github.com/JavaZeroo/termforge/issues/31)。本合同区分工作区字体、终端绘制字体、固定网格和真实显示环境;受控消息、真实窗口跨屏、实际呈现是不同证据层级。复杂 Unicode/IME 由 #30 验收,产品后端决定由 #34 负责。 +本文记录当前实现与验证合同,不表示用户已确认最终字体/网格或与原版的差异。按 [ADR-0006](../adr/0006-confirmed-project-direction.md),#31 补固定原版的实际对照;12×26 网格、18 DIP、缩字适配及缺字体失败等策略保留明确来源与限制,重要差异提交用户确认。已有度量和回归结果继续有效于原限定范围。 + ## 字体来源与失败策略 - 工作区 UI 使用独立获取的 Roboto Mono Regular,9pt,SIL OFL 1.1;固定上游提交、原始字节和 SHA-256 见[字体来源](../../assets/fonts/README.md)。通过 `AddFontResourceExW(..., FR_PRIVATE, ...)` 仅对进程加载,缺失、注册失败或实际 `GetTextFaceW` 不是 Roboto Mono 时明确失败,不静默替换。`renderer_metrics` 独立复核实际 GDI face、em 高度与 `TEXTMETRIC.tmHeight`;96/120/144/192 DPI 的 em 为 12/15/18/24,行高为 16/20/24/32,不能把二者混为“字符高度”。 diff --git a/docs/milestones/R2-local-terminal.md b/docs/milestones/R2-local-terminal.md index 94e7e187..4e9dc8bc 100644 --- a/docs/milestones/R2-local-terminal.md +++ b/docs/milestones/R2-local-terminal.md @@ -4,9 +4,11 @@ 用户结果:在明确支持的 Windows 环境中,用固定本地 shell、分页器和编辑器完成连续工作;复杂文字、输入和会话互相一致;重启后恢复已声明的配置;最终下载包能从公开源码复建。 +方向约束见 [ADR-0006](../adr/0006-confirmed-project-direction.md):优先对齐终端基础能力与性能,首个完整版本环境为 Windows 11 x64,R2 是其中的阶段性交付。原版行为优先;Alacritty 保留为候选,核心/GUI/后端正式方案及性能容差需用户确认。历史已验合同继续作为回归依据,原版未知和重要差异由相应任务取证及提交确认。 + ## 当前站位 -R2 的前期平台/核心路线、有限会话与恢复、首批流式字素已有各自限定交付。剩余工作集中在**联合配置、兼容与输入、环境、性能及最终产物**,不是重做这些前置,也不是只差修几个崩溃后打包。已发布 Alpha、主线显式候选、Draft 官方后端是不同配置,证据不得互借。 +R2 的前期平台调查/候选比较、有限会话与恢复、首批流式字素已有各自限定交付;这些研究不代表用户确认正式核心路线。剩余工作集中在**联合配置、原版对照、兼容与输入、环境、性能、用户选型确认及最终产物**。已有证据继续复用;已发布 Alpha、主线显式候选、Draft 官方后端是不同配置,证据不得互借。 联合源码 `3e5b96d` 的三配置[真实基线](../research/joint-conpty-baseline.md)已在实验分支冻结,包含原场景及完整回归的明确失败;近期转向这些失败的因果修复与复验。基线交付不选择默认后端或宣布兼容性通过,Draft #50 仍需通过原有回归。 @@ -18,7 +20,7 @@ R2 的前期平台/核心路线、有限会话与恢复、首批流式字素已 |---|---|---| | 1. 冻结联合基线 | 主线候选和显式官方后端来自同一份可重建源码;系统对照与联合配置各有实际结果 | [联合基线 #55](https://github.com/JavaZeroo/termforge/issues/55):固定 source/依赖/二进制/包/flags,验证 API 生命期、原 175B margin、Unicode/glyph、真实尺寸 ack、退出与回收;重放 #51–#53 原场景,分列 red、green 和未复现。默认路线与 #34 产品决定保持不变 | | 2. 闭合兼容性与输入 | 明确支持的 shell、分页器、编辑器、复杂文字与会话交互在联合配置中连续工作 | #47/#51–#53 处理后端;#41 处理原生 API/末端语义;#27/#29 核对模式与 resize,#28 验收固定 TUI/回复/输入字节,#30 验收完整 IME/选择/粘贴。实际不同 DPI 由 #31 并行提供 | -| 3. 定案产品架构与支持配置 | 能明确说明产品采用哪条核心/后端/呈现边界、为什么以及如何维护 | #34 使用 #23/#26、#28–#33 的真实结果与 #54 的受控成本,重审 ADR-0004;明确配置、平台下限、接口、并发/取消、依赖升级和暂不支持的范围,不静默缩小 R2 合同 | +| 3. 提交并确认产品架构与支持配置 | 提供可比较的核心/后端/GUI 方案、证据和取舍,经用户确认后定案 | #34 使用 #23/#26、#28–#33 的真实结果与 #54 的受控成本,重审 ADR-0003/0004;明确 Windows 11 x64 优先、未来平台障碍、接口、并发/取消和维护成本;范围及重要差异依 ADR-0006 确认 | | 4. 验收最终开发包 | 用户从公开源码复建或解压下载包,在声明环境中完成固定工作流 | #35 在最终产物上复验本页全部门槛、配置升级/恢复、错误/回收及预先冻结的持续运行与资源合同;#36/#38 的可靠性出口必须闭合。来源、许可、说明与产物身份一致后,才结项 #7 | 关键依赖如下;实线为硬前置,虚线为联合复验条件,省略已关闭前置和冗余边。完整原生关系在 GitHub。 @@ -43,7 +45,7 @@ flowchart LR ## 下一批的任务边界 1. **在已冻结基线上逐项闭合后端回归。** #55 已交付含红的真实基线;接续 #51–#53 与 #63 的独立失败。#62 的[真实 writer 持块、取消与停止夹具](../research/sender-fence.md)不降低原 4MiB/16KiB/期限,下一步把默认关闭的 fence 接到 #53 原 UI/3MB/八会话入口;这不代表这些 UI 路径已通过。#51–#53 可以用原冻结输入独立定位,最终修复验收须在联合配置重建;一次未复现不自动构成因果修复。 -2. **并行处理平台语义与性能。** [原生语义处理路径 #56](https://github.com/JavaZeroo/termforge/issues/56)先明确 #41 原合同需要什么、哪些路径可支持;保留必要的上游或独立实现工作,不用“平台不同”豁免缺口。#54 现在就冻结重复方法、完成端点和预算决定程序,再定位吞吐成本;不等到 #34 才补性能。 +2. **并行处理原版对照、平台语义与性能。** [原生语义处理路径 #56](https://github.com/JavaZeroo/termforge/issues/56)先明确 #41 原合同需要什么、哪些路径可支持;保留必要的上游或独立实现工作,不用“平台不同”豁免缺口。#3/#4 优先建立原版 Windows 本地终端基线;#54 现在冻结重复方法与完成端点并定位吞吐成本,数值预算作为提案交用户确认,不等到 #34 才补性能。 3. **在主线推进独立行为合同。** #29 核对极窄/极短、软硬行、历史/淘汰、选择/Find、连续 resize 和 child ack;#30 核对 IME 组合/提交/取消与输出/resize/切换、应用键盘/粘贴接收、实际复制及同次八会话。已验收的 #39 只提供首批字素基础,最终配置的交叉验收仍需执行。 4. **补终端模式和应用矩阵。** #27 明确 DECOM/DECAWM、pending-wrap、保存恢复、异常序列与 margin×resize;#28 先固定应用版本/入口/动作及协议字节预期,再逐应用完成进入、操作、resize、退出、主屏恢复。Vim 的一个修复不替代完整 TUI 验收。 5. **独立推进真实显示与可靠性。** #31 当前缺实际不同 DPI 环境;优先自动探测或准备隔离测试宿主,不改个人显示设置、不反复测试同两台 96-DPI 屏幕。#36/#40/#44 及[旧 normal-1 事件 #57](https://github.com/JavaZeroo/termforge/issues/57)按有停止条件的诊断批次推进,原失败和未知保留,不阻塞其他独立工作。 @@ -53,7 +55,7 @@ flowchart LR | 工作 | 每次执行必须产出 | 遇到缺口如何处理 | |---|---|---| | 联合基线后的后端修复 | 对同一 source/负载/期限的反例、最小原因与完整动作结果;native、transport、核心、glyph 和回收分列 | 有因果 red→green 才写修复;暂未复现保留旧输入和未知,不改 oracle 或等待预算 | -| #54 受控性能 | 正确性、固定负载/环境/配置、无观察或观察成本边界、重复样本、分层归因与预算依据 | 当前约 16%/9% 的吞吐成本只是共享宿主诊断;没有正式 WindTerm 基线或实际端点就保持未知 | +| #3/#4 原版基线及 #54 受控性能 | 正确性、固定负载/环境/配置、无观察或观察成本边界、重复样本、分层归因与预算提案 | 当前约 16%/9% 的吞吐成本只是共享宿主诊断;没有正式 WindTerm 基线或实际端点就保持未知;具体容差由用户明确后生效 | | #31 真实不同 DPI | 可识别的实际环境、跨屏输入/焦点/网格/隐藏会话和真实 child 尺寸记录 | 无环境则保留环境阻塞,继续隔离宿主自动化准备;消息模拟或受控 DIB 不计真实跨屏 | | 历史可靠性 #36/#40/#44 与 #38 未知事件 | 一次预先限定的假设/样本批次,包含事件阶段、原期限、源码/宿主身份和清理 | 未复现就报告该批未复现,更新下一可证伪假设;不无限重跑取绿,也不由规划整理解除 #35 的出口 | @@ -66,7 +68,7 @@ flowchart LR | resize 与真实 TUI:#29、#28 | 逻辑/物理行、宽字符、历史与淘汰有明确策略;窗口、核心和真实子进程尺寸一致;固定应用逐一完成进入、操作、resize、退出、主屏恢复;回复、输入模式和 bracketed paste 字节经独立预期验证 | 离线回放、单独 Vim 成功或默认核心通过,不能代表整个候选产品矩阵;未声明应用不计完成 | | 复杂文字与输入:#30(复用已验 #39) | 保留首批字素合同,在最终配置核对原始标量、宽度/光标、实际 glyph、复制与子进程接收;完成固定 IME 与同次八会话交叉回归 | #39 的字素与单列 resize 成功不代表完整 IME、应用模式或 R1 系统输入组合在另一配置已通过;未知 WindTerm 行为仍保留 | | 真实显示:#31 | 按[字体/显示合同](R2-font-display.md)记录实际不同 DPI、真实跨屏、焦点、IME/Find/rename、命中、隐藏会话及子进程尺寸;环境身份和重复结果可核对 | 相同 96 DPI 的两台显示器、受控消息、DIB 或实际提交时刻不能代替不同 DPI 或实际上屏证据;不得修改个人显示设置制造验收 | -| 产品架构:#34 | 基于上述实际工作流与 #23/#26、已验收的 #32/#33,重审 ADR-0004;明确产品核心选择、GUI/平台边界、历史/快照、传输/呈现、背压/取消、依赖升级与维护策略 | 原型已采用某技术或候选已有接口,不构成最终产品选择;未测性能仍保持未知 | +| 产品架构:#34 | 基于实际工作流、原版对标及 #23/#26/#32/#33/#54 的证据,重审 ADR-0003/0004;提出核心、GUI/平台、历史/快照、传输/呈现、背压/取消和维护方案,记录用户确认依据 | 原型已采用某技术、历史 issue 关闭或候选已有接口,不构成最终产品选择;未测性能和未确认容差保持未完成 | | 开发版交付:#35 | 最终下载产物通过干净构建、依赖/字体许可和清单审计、解压运行、shell/TUI/文字/配置升级/真实显示工作流;按预先冻结的负载和资源合同完成重复会话与持续运行,逐项核对本表 | Alpha 1、源码构建成功、短驻留或某一 CI 通过,不代表 R2 日常开发包、长期稳定或 WindTerm 性能等价 | #32 本地 shell/分屏标签、#33 会话与配置恢复已有各自限定合同;最终集成仍须复验这些合同。R2 不扩大为 SSH/SFTP、任意嵌套分屏、完整 WindTerm UI 或跨平台客户端;这些任务继续按 PLAN 的对应路标推进。 @@ -76,5 +78,5 @@ flowchart LR - 每个结果保留源码/二进制、系统/后端、输入/负载身份,以及实际通过、失败和跳过;不同源码或补充运行不拼成一次“全绿”。 - 控制台、模型、DWrite 布局、DIB、窗口提交和实际呈现各自留证;未观测端点保持 unknown/null。 - 只公开经审核的合成输入和脱敏摘要;运输原件、用户路径、桌面身份等按现有来源规则处理。真实原生会话的宿主和子进程须在自有 Job 中启动、超时和回收;离线模型回放另列实际期限与监督范围,不能由进程 timeout 推断 Job 回收。 -- 单项完成更新其 issue、FEATURES 与 EVIDENCE;原失败仍保留。若真实平台能力迫使改变合同,先明确提出范围/架构决定,不能用新合同证明旧合同已完成。 +- 单项完成更新其 issue、FEATURES 与 EVIDENCE;原失败仍保留。若需改变范围、主要路线、验收门槛或接受重要差异,先提交证据和具体方案供用户确认,不能用新合同证明旧合同已完成。 - #7 由 #35 对所有出口逐项核对后结项;正式 WindTerm 性能基线继续独立推进,不由本表推断已经等价。 diff --git a/docs/research/2026-10-25-core-route-review.md b/docs/research/2026-10-25-core-route-review.md index acd4b352..3cd71b20 100644 --- a/docs/research/2026-10-25-core-route-review.md +++ b/docs/research/2026-10-25-core-route-review.md @@ -1,5 +1,7 @@ # R2 原生核心路线重审(#26) +> 历史研究记录:2026-10-26 用户已确认保留 Alacritty 为候选并重新评估,见 [ADR-0006](../adr/0006-confirmed-project-direction.md)。本文的样本、接口及当时结论保留原义;下文的“决定”不再作为当前正式选型或用户批准依据。最终核心方案由 #34 提交用户确认。 + 调查与决定日期:2026-10-25。固定候选为 `alacritty_terminal 0.26.0`,对照为当前自研 C++ 核心。本文记录 [#26](https://github.com/JavaZeroo/termforge/issues/26) 的平台、维护、接口和路线证据;[ADR-0003](../adr/0003-core-reference-and-reuse.md) 保存决定,[FEATURES](../FEATURES.md) 保存实际能力。没有启动 WindTerm、GUI 或截图探针,也没有把 headless 轨迹写成产品呈现。 ## 决定 diff --git a/docs/research/r1-action-comparison.md b/docs/research/r1-action-comparison.md index 0843aa8a..114ce1cc 100644 --- a/docs/research/r1-action-comparison.md +++ b/docs/research/r1-action-comparison.md @@ -1,5 +1,7 @@ # R1 文字动作对照 +> 本页保留 R1 限定观察、实现策略与验证。当前方向按 [ADR-0006](../adr/0006-confirmed-project-direction.md) 原版优先;未经原版对照的项目策略继续列为差异或未知,重要差异及原版缺陷修正需用户确认。历史验收不自动成为最终差异获准记录。 + 本表用于 [R1-07 / #17](https://github.com/JavaZeroo/termforge/issues/17) 的逐项验收。参考观察、产品策略和实际验证分别记录;有实现或纯模型测试不等于真实入口通过。本表已按 R1 合同完成限定验收,执行状态只在 issue 维护。 ## 固定依据 diff --git a/docs/research/streaming-graphemes.md b/docs/research/streaming-graphemes.md index 67541cd8..ce36ce9f 100644 --- a/docs/research/streaming-graphemes.md +++ b/docs/research/streaming-graphemes.md @@ -1,5 +1,7 @@ # R2 流式字素、宽度与固定 emoji 合同(#39) +> 当前合同与规范回归描述候选实现,未完成的原版匹配由 #30 继续取证。按 [ADR-0006](../adr/0006-confirmed-project-direction.md),WindTerm 2.7.0 实际行为优先;Unicode 版本、宽度或事件边界策略与原版有重要差异时提交用户确认。#39 的关闭和正确性结果不构成该确认,也不确定最终核心选型。 + 本合同属于显式候选 `Term/Processor` 路线,不扩展默认自研解析器。固定首批样本为 `e\u0301`、`🙂`、`👩‍💻`、`1️⃣`;要求原始标量、不经 NFC 的原文、单元格、光标、选择复制和实际绘制一致。WindTerm 2.7.0 的对应运行时行为仍未知,不能由静态 QString 测量路径推断。 ## 依据与路线 diff --git a/experiments/candidates/alacritty/README.md b/experiments/candidates/alacritty/README.md index 1d452710..c6c711a9 100644 --- a/experiments/candidates/alacritty/README.md +++ b/experiments/candidates/alacritty/README.md @@ -1,6 +1,6 @@ # Alacritty 固定核心与候选适配工具 -本目录包含候选构建、状态适配、固定兼容补丁、C ABI 与核心成本实验。[ADR-0003](../../../docs/adr/0003-core-reference-and-reuse.md)决定 R2 新能力复用候选 Term/Processor;C++ 拥有值适配接入显式候选 `ShellWindow`,默认 CMake 保留自研回退。能力统一见[功能矩阵](../../../docs/FEATURES.md),联合验收和依赖见 [R2 合同](../../../docs/milestones/R2-local-terminal.md),本说明不维护逐批进度。 +本目录包含候选构建、状态适配、固定兼容补丁、C ABI 与核心成本实验。[ADR-0003](../../../docs/adr/0003-core-reference-and-reuse.md)及 [ADR-0006](../../../docs/adr/0006-confirmed-project-direction.md)保留 Alacritty 为待评估候选,正式核心选型待原版对标和用户确认;C++ 拥有值适配接入显式候选 `ShellWindow`,默认 CMake 保留自研回退。能力统一见[功能矩阵](../../../docs/FEATURES.md),联合验收和依赖见 [R2 合同](../../../docs/milestones/R2-local-terminal.md),本说明不维护逐批进度。 ## 固定来源与许可 diff --git a/experiments/core/CANDIDATE.md b/experiments/core/CANDIDATE.md index 3863ddaa..a7f81954 100644 --- a/experiments/core/CANDIDATE.md +++ b/experiments/core/CANDIDATE.md @@ -1,5 +1,7 @@ # 候选 C++ 终端适配器 +按 [ADR-0006](../../docs/adr/0006-confirmed-project-direction.md),用户确认保留本候选代码继续评估,尚未确认最终采用。下述实现、来源与回归结果继续保留;与 WindTerm 2.7.0 的重要差异、性能容差及正式选型分别提交用户确认。 + `CandidateTerminal` 是 #27 的拥有值适配层,不是自研核心的替代品声明。它把固定 `0.26.1-dev+termforge.4` 的 `Term/Processor` 接到现有 `Screen`/`Line`;默认 CMake 保留自研核心且不需要 Rust,候选产品由 `TERMFORGE_BUILD_CANDIDATE_ADAPTER=ON` 显式启用。 ## 构建与验证 diff --git a/research/windterm-2.7.0-platform-scope.md b/research/windterm-2.7.0-platform-scope.md index f48cdedd..c406af56 100644 --- a/research/windterm-2.7.0-platform-scope.md +++ b/research/windterm-2.7.0-platform-scope.md @@ -1,5 +1,7 @@ # WindTerm 2.7.0 平台、架构与发行边界 +> 当前产品优先级由 [ADR-0006](../docs/adr/0006-confirmed-project-direction.md)确认:首个完整版本验收 Windows 11 x64,最终覆盖 Windows/Linux/macOS;其他系统版本、最低版本和架构后续单独明确。下表的官方声明及历史调查不改写,也不自动成为 TermForge 首个版本的支持承诺。平台可行性可提前调查,Linux/macOS 完整客户端验收在 R5 的 Windows 出口之后完成。 + 调查日期:2026-10-24。本文是 [#23](https://github.com/JavaZeroo/termforge/issues/23) 的单一范围台账,供 R2 核心路线(#26)和产品架构(#34)判断候选支持缺口;不进行核心构建、功能实现或平台验收。全量目标仍归 [#19](https://github.com/JavaZeroo/termforge/issues/19),TermForge 当前能力与限制以 [FEATURES](../docs/FEATURES.md) 为准。 ## 固定对象与证据口径 @@ -17,7 +19,7 @@ 3. 实际发行形式为 Windows/Linux **portable ZIP**、macOS **portable DMG**;macOS 安装说明是打开 DMG 并把 `WindTerm.app` 拖入 `Applications`。release 另给 Scoop/Chocolatey 命令,但它们不是本次四个官方上传资产,具体包身份和系统边界未知。 4. release 的 Linux 命令提到 `.tar.gz`,实际资产却是 `.zip`;Checksums 提到 macOS ZIP,实际资产却是 DMG。两处均保留为官方材料内部差异,不虚构缺失资产,也不把 macOS ZIP 校验值用于 DMG。 5. 固定 commit 没有完整 WindTerm 应用的顶层构建/打包工程;公开 `src/libssh` 的 CMake/CPack 配置属于第三方库,不能据此重建四个应用资产或推导其平台支持。 -6. TermForge 当前只有有限 Windows x64 客户端原型;Linux 核心 CI 不是 Linux GUI 客户端,Windows 11/Server 2025 验证也没有覆盖官方 Windows 7/8/10 或 x86 范围。R2 只使用本台账做选型输入,真实跨平台客户端和完整矩阵主要归 R4/R5。 +6. TermForge 当前只有有限 Windows x64 客户端原型;Linux 核心 CI 不是 Linux GUI 客户端,Windows 11/Server 2025 验证也没有覆盖官方 Windows 7/8/10 或 x86 范围。R2 使用本台账做候选差距输入;平台调查可并行,真实跨平台整合及完整验收归 R5 的后续全平台出口。 ## 目标台账 @@ -25,10 +27,10 @@ | ID | 官方声明与发行物事实 | 最低系统边界及未知 | 来源类型与精确来源 | TermForge 当前实现/验证 | 负责路标与后续验收 | |---|---|---|---|---|---| -| PLAT-001 | Windows **x86_32**,portable ZIP;资产 `WindTerm_2.7.0_Windows_Portable_x86_32.zip` | 官方列出 Windows 7/8/10/11,故声明最低为 **Windows 7**;Service Pack、edition、Windows 8.1、Server 及各版本实测均未知 | 官方声明:[release Usage](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0);发行物:[资产元数据](https://api.github.com/repos/kingToolbox/WindTerm/releases/assets/236583144) | **未实现、未验证**;现有 Windows 客户端仅 x64 | R2 仅供 #26/#34 判断 32 位支持缺口;真实客户端/打包归 R4/R5;R5 在 #19 全矩阵验收 | -| PLAT-002 | Windows **x86_64**,portable ZIP;资产 `WindTerm_2.7.0_Windows_Portable_x86_64.zip` | 官方列出 Windows 7/8/10/11,故声明最低为 **Windows 7**;Service Pack、edition、Windows 8.1、Server 及各版本实测均未知 | 官方声明:[release Usage](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0);发行物:[资产元数据](https://api.github.com/repos/kingToolbox/WindTerm/releases/assets/236582459) | **部分**:有限 x64 原型与免安装 ZIP;只已验 Windows 11 本机和 Server 2025 CI。Windows 7/8/10 未验收,Server 2022 已知资源门槛未过 | R2 #26/#34 选型输入及 Windows 开发版;旧系统/更广矩阵归 R4/R5;R5 在 #19 验收,不把当前验证范围写成官方范围 | -| PLAT-003 | macOS **x86_64**,portable DMG;资产 `WindTerm_2.7.0_Mac_Portable_x86_64.dmg`;说明为拖入 `Applications` | 官方列出 macOS 10.13/10.14/10.15/11/12,故声明最低为 **10.13**;具体 build、10.12 及更早、13 及更新版本和实机验证未知 | 官方声明/安装说明:[release Usage](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0);发行物:[资产元数据](https://api.github.com/repos/kingToolbox/WindTerm/releases/assets/236583377) | **未实现、未验证** macOS 客户端 | R2 仅供 #26/#34 判断旧 macOS、窗口/输入/字体和打包缺口;真实客户端归 R4/R5;R5 在 #19 验收 | -| PLAT-004 | Linux **x86_64**,portable ZIP;资产 `WindTerm_2.7.0_Linux_Portable_x86_64.zip` | 官方声明 **Generic Linux(glibc 2.17+)**;具体发行版、内核、glibc 之外运行库、X11/Wayland/桌面环境和实机验证未知 | 官方声明:[release Usage](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0);发行物:[资产元数据](https://api.github.com/repos/kingToolbox/WindTerm/releases/assets/236583277) | **未实现、未验证** Linux 客户端;只有 Linux 核心 CI,不证明 GUI/PTY 整合或可分发产品 | R2 仅供 #26/#34 判断 libc/显示/输入/打包缺口;真实客户端归 R4/R5;R5 在 #19 验收 | +| PLAT-001 | Windows **x86_32**,portable ZIP;资产 `WindTerm_2.7.0_Windows_Portable_x86_32.zip` | 官方列出 Windows 7/8/10/11,故声明最低为 **Windows 7**;Service Pack、edition、Windows 8.1、Server 及各版本实测均未知 | 官方声明:[release Usage](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0);发行物:[资产元数据](https://api.github.com/repos/kingToolbox/WindTerm/releases/assets/236583144) | **未实现、未验证**;现有 Windows 客户端仅 x64 | #23/#26 的历史调查供 #34 判断 32 位支持缺口;x86 产品范围待用户明确,不阻塞 Windows 11 x64 首个完整出口 | +| PLAT-002 | Windows **x86_64**,portable ZIP;资产 `WindTerm_2.7.0_Windows_Portable_x86_64.zip` | 官方列出 Windows 7/8/10/11,故声明最低为 **Windows 7**;Service Pack、edition、Windows 8.1、Server 及各版本实测均未知 | 官方声明:[release Usage](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0);发行物:[资产元数据](https://api.github.com/repos/kingToolbox/WindTerm/releases/assets/236582459) | **部分**:有限 x64 原型与免安装 ZIP;只已验 Windows 11 本机和 Server 2025 CI。Windows 7/8/10 未验收,Server 2022 已知资源门槛未过 | R2 #34 选型输入及 Windows 开发版;R5 先验 Windows 11 x64,旧系统/更广矩阵由用户后续明确,不把当前验证范围写成官方范围 | +| PLAT-003 | macOS **x86_64**,portable DMG;资产 `WindTerm_2.7.0_Mac_Portable_x86_64.dmg`;说明为拖入 `Applications` | 官方列出 macOS 10.13/10.14/10.15/11/12,故声明最低为 **10.13**;具体 build、10.12 及更早、13 及更新版本和实机验证未知 | 官方声明/安装说明:[release Usage](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0);发行物:[资产元数据](https://api.github.com/repos/kingToolbox/WindTerm/releases/assets/236583377) | **未实现、未验证** macOS 客户端 | R2 仅供 #26/#34 判断旧 macOS、窗口/输入/字体和打包缺口;可行性调查可并行;真实客户端整合及验收归 R5 Windows 出口之后,系统/架构由用户明确 | +| PLAT-004 | Linux **x86_64**,portable ZIP;资产 `WindTerm_2.7.0_Linux_Portable_x86_64.zip` | 官方声明 **Generic Linux(glibc 2.17+)**;具体发行版、内核、glibc 之外运行库、X11/Wayland/桌面环境和实机验证未知 | 官方声明:[release Usage](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0);发行物:[资产元数据](https://api.github.com/repos/kingToolbox/WindTerm/releases/assets/236583277) | **未实现、未验证** Linux 客户端;只有 Linux 核心 CI,不证明 GUI/PTY 整合或可分发产品 | R2 仅供 #26/#34 判断 libc/显示/输入/打包缺口;可行性调查可并行;真实客户端整合及验收归 R5 Windows 出口之后,系统/架构由用户明确 | 固定 README 的 [Download](https://github.com/kingToolbox/WindTerm/blob/a8336c1d1e3dd1a981500dae8ef9eb42066de95f/README.md#download) 与 [GUI](https://github.com/kingToolbox/WindTerm/blob/a8336c1d1e3dd1a981500dae8ef9eb42066de95f/README.md#gui) 还明确声明 Linux/macOS/Windows binary 和三平台 GUI。这一声明由上面四行落实为 2.7.0 的具体资产;README 本身没有给出额外架构或更低系统版本。 @@ -37,7 +39,7 @@ | ID | 目标事实或组件边界 | 来源类型与精确来源 | 当前实现/验证状态 | 负责路标与后续验收 | |---|---|---|---|---| | PLAT-005 | release 提供 `scoop bucket add extras` + `scoop install windterm` 和 `choco install windterm`。这是官方说明中的安装入口,不是额外的官方 release 资产;包版本、架构、维护者、依赖和最低系统均未知 | 官方声明:[release Installation](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0);四个实际上传资产:[release API](https://api.github.com/repos/kingToolbox/WindTerm/releases/tags/2.7.0) | TermForge 未提供或验证这两个入口;未把第三方包管理器元数据当作官方目标事实 | R2/R3 决定 Windows 分发时另行核验;R5 验收所声明的安装/升级路径,不能以命令存在代替测试 | -| PLAT-006 | 固定公开 `ConPty.cpp` 定义 `CONPTY_MINIMAL_WINDOWS_VERSION 18309`,`isAvailable()` 检查该 build,失败文字为 Windows 10 below 1809;因此 **ConPTY 路径静态下限为 Windows 10 1809 / build 18309**。这不是整个 WindTerm 的最低系统,也不是 2.7.0 二进制运行观察;release 另称该版本暂以 WinPTY 替代 ConPTY | 源码静态事实:[`src/Pty/ConPty.cpp`](https://github.com/kingToolbox/WindTerm/blob/a8336c1d1e3dd1a981500dae8ef9eb42066de95f/src/Pty/ConPty.cpp);官方 release 的 `[SHELL]` 说明:[2.7.0 release](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0) | 当前原型使用 ConPTY,已验 Windows 11/Server 2025;Windows 10 未验收,Server 2022 资源门槛未过。没有验证官方 2.7.0 的 WinPTY/ConPTY 选择行为 | R2 #26 必须比较 ConPTY/WinPTY 或其他后端的支持和行为缺口,#34 明确 PTY 抽象;R4/R5 验证系统矩阵,不能把 1809 错写成全应用下限 | +| PLAT-006 | 固定公开 `ConPty.cpp` 定义 `CONPTY_MINIMAL_WINDOWS_VERSION 18309`,`isAvailable()` 检查该 build,失败文字为 Windows 10 below 1809;因此 **ConPTY 路径静态下限为 Windows 10 1809 / build 18309**。这不是整个 WindTerm 的最低系统,也不是 2.7.0 二进制运行观察;release 另称该版本暂以 WinPTY 替代 ConPTY | 源码静态事实:[`src/Pty/ConPty.cpp`](https://github.com/kingToolbox/WindTerm/blob/a8336c1d1e3dd1a981500dae8ef9eb42066de95f/src/Pty/ConPty.cpp);官方 release 的 `[SHELL]` 说明:[2.7.0 release](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0) | 当前原型使用 ConPTY,已验 Windows 11/Server 2025;Windows 10 未验收,Server 2022 资源门槛未过。没有验证官方 2.7.0 的 WinPTY/ConPTY 选择行为 | 保留 #26 的历史比较,#34 根据原版观察提交后端与 PTY 边界方案供用户确认;R5 按确认的系统矩阵验收,不能把 1809 错写成全应用下限 | | PLAT-007 | 固定公开树只有 `README.md`、`benchmark/`、`images/`、`src/`,没有完整应用入口或顶层构建/安装/打包工程。`src/libssh/CMakeLists.txt` 是 `project(libssh VERSION 0.9.5 LANGUAGES C)`,其 CPack 可生成 libssh ZIP/NSIS;这些不是 WindTerm 应用发行配置 | 源码树事实:[固定 commit 根目录](https://github.com/kingToolbox/WindTerm/tree/a8336c1d1e3dd1a981500dae8ef9eb42066de95f)、[递归 tree API](https://api.github.com/repos/kingToolbox/WindTerm/git/trees/a8336c1d1e3dd1a981500dae8ef9eb42066de95f?recursive=1)(本次返回 `truncated=false`);构建配置:[`src/libssh/CMakeLists.txt`](https://github.com/kingToolbox/WindTerm/blob/a8336c1d1e3dd1a981500dae8ef9eb42066de95f/src/libssh/CMakeLists.txt)、[`src/libssh/CPackConfig.cmake`](https://github.com/kingToolbox/WindTerm/blob/a8336c1d1e3dd1a981500dae8ef9eb42066de95f/src/libssh/CPackConfig.cmake)、[`src/libssh/INSTALL`](https://github.com/kingToolbox/WindTerm/blob/a8336c1d1e3dd1a981500dae8ef9eb42066de95f/src/libssh/INSTALL) | 未从官方公开源码构建官方应用;TermForge 的独立可复建目标不受此阻塞,但不能宣称恢复官方构建或复用其完整源码 | R2 #26/#34 把依赖许可、平台构建和维护成本分开;R5 对 TermForge 自己声明的平台完成可复建发布和矩阵验收 | ### 未确认架构与版本范围 @@ -46,10 +48,10 @@ | ID | 未知范围 | 来源类型与精确来源 | 当前实现/验证状态 | 负责路标与后续验收 | |---|---|---|---|---| -| PLAT-008 | Windows ARM/ARM64,以及 x86/x64 之外架构;原生运行、仿真运行和最低系统均未知 | 官方声明与发行物事实:[固定 README](https://github.com/kingToolbox/WindTerm/blob/a8336c1d1e3dd1a981500dae8ef9eb42066de95f/README.md) 只声明 Windows;[release API](https://api.github.com/repos/kingToolbox/WindTerm/releases/tags/2.7.0) 四资产无 Windows ARM | 未实现、未验证 | R2 #26/#34 记录候选硬限制,不作支持承诺;是否扩展须单独裁决,若纳入则 R4/R5 真实客户端验收 | +| PLAT-008 | Windows ARM/ARM64,以及 x86/x64 之外架构;原生运行、仿真运行和最低系统均未知 | 官方声明与发行物事实:[固定 README](https://github.com/kingToolbox/WindTerm/blob/a8336c1d1e3dd1a981500dae8ef9eb42066de95f/README.md) 只声明 Windows;[release API](https://api.github.com/repos/kingToolbox/WindTerm/releases/tags/2.7.0) 四资产无 Windows ARM | 未实现、未验证 | R2 #26/#34 记录候选硬限制,不作支持承诺;是否纳入由用户明确,若纳入则在 R5 后续平台出口完成真实客户端验收 | | PLAT-009 | macOS ARM64/Apple Silicon,包括原生与 Rosetta 路径;macOS x86 之外架构 | 官方声明与发行物事实:[release](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0) 只有 x86_64 和 10.13–12 声明;[macOS 资产元数据](https://api.github.com/repos/kingToolbox/WindTerm/releases/assets/236583377) 只有 x86_64 DMG,没有 ARM 资产或兼容声明 | 未实现、未验证 | 同 PLAT-008;不能从 x86_64 DMG 推断 ARM 原生或仿真通过 | | PLAT-010 | Linux ARM64/AArch32、x86_32 及其他架构 | 官方声明与发行物事实:[release](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0) 只有 x86_64 和 glibc 2.17+ 声明;[Linux 资产元数据](https://api.github.com/repos/kingToolbox/WindTerm/releases/assets/236583277) 没有其他架构或系统边界 | 未实现、未验证;核心 CI 不覆盖这些客户端 | 同 PLAT-008;核心可编译不等于产品平台支持 | -| PLAT-011 | 未列出的旧/新系统、Windows Server/edition/Service Pack、Linux 发行版与显示栈 | 官方声明:[release](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0) 只给 PLAT-001–004 的枚举或 glibc 条件;未提及项均保持未知,不自行填具体版本 | 仅 FEATURES 所列有限 Windows 环境和 Linux 核心 CI 有验证 | R2 选型必须列环境缺口;R4/R5 只对实际声明支持的环境做真实验收,范围变化另留证据 | +| PLAT-011 | 未列出的旧/新系统、Windows Server/edition/Service Pack、Linux 发行版与显示栈 | 官方声明:[release](https://github.com/kingToolbox/WindTerm/releases/tag/2.7.0) 只给 PLAT-001–004 的枚举或 glibc 条件;未提及项均保持未知,不自行填具体版本 | 仅 FEATURES 所列有限 Windows 环境和 Linux 核心 CI 有验证 | R2 选型必须列环境缺口;R5 对用户确认范围做真实验收,其他系统/架构保持待明确,范围变化另留确认依据 | ## 2.7.0 官方资产快照