[xiaoyumuxi]

这个 PR 做什么

#1210 的远程 attach 契约：让调试适配器附加到另一台机器上的被调试程序（JVM 开了 -agentlib:jdwp、Node --inspect、gdbserver 等需要主机和端口的场景）。本 PR 只做共享契约和 Rust Core 校验，不改变任何用户可见的调试行为：macOS 宿主还没有接入 attach，“附加到远程”对话框在后续 PR。

基线已更新：#1520 已合并到 preview。本 PR 已将 preview（cdeec194935a3450ebb17c1ef1204cf1aa7fac6f）合入并将 base 改为 preview；使用普通 merge commit cf4ffab70648e8260c116b0866279e8b6172da1c 解决冲突，没有改写历史或 force push。diff 只保留本 PR 的远程 attach 契约和设计说明。

先说范围：普通 TCP 与生命周期，网络通路另案

按本次讨论收敛：当前传输这轮只完成普通 TCP 正常连接与生命周期，复用 #1520，不再另写一套 TCP；保留 stdio。代理、隧道、端口转发、跳板和 SSH 远端执行不在本轮实现，也不作为 TCP 交付的前置。 本次追加提交只更新设计和说明，没有新增这些能力的实现。

独立的范围与验收 Note：2026-10-27-debug-network-paths-and-tcp-lifecycle.md。本轮连接实现应覆盖：

• 正常建连和有序双向收发；端点解析、建连、请求和停止有界，待发数据有资源上限，不给调试会话设置总时长。
• 取消、超时、拒绝连接、读写失败、EOF 和停止进入幂等清理链；回调绑定会话及连接代次，过期结果不污染新连接，终止通知只发一次。
• 仅释放本会话拥有的 socket / 进程，不结束共享语言服务器、外部 DAP 服务、attach 目标或用户建立的 VPN / 隧道；不自动重连或重放 DAP 请求。
• feat(debug): #1210 tcpLanguageServer 调试传输：调试适配器随插件语言服务器运行（Java 迁入插件的第一步） #1520 的 tcpLanguageServer 仍只接收同插件 LSP 提供的回环端口，不直接放宽为任意远端地址。用户提供的外部 DAP 端点（G2）需要独立入口、校验和确认，并复用已有 socket 生命周期。

要区分两条连接：

IDE -- DAP（stdio 或 TCP）--> 调试适配器 -- JDWP / GDB Remote 等 --> 被调试程序

targetBindings.connection 描述的是后者的适配器参数，不能拿来直接作为 IDE 的 DAP socket 地址。Java、GDB 的远端程序可以由本机适配器连接；默认 debugpy --listen 则会在目标机器上启动 DAP 适配器，需要 IDE 直连那个 DAP 端点，不能只在本机另起适配器并填 connect.host/port 就声称支持。

远程调试不以 SSH 可用为统一前提。端点可直接可达，也可由用户自行提供 VPN / 隧道后的端点；Lithe 本轮不管理这些网络设施。裸 TCP 不带认证和加密，不推荐把调试端口直接暴露到公网。

原 2026-10-27-remote-debug-adapter-over-ssh.md 保留为暂缓的 SSH 子方案草案，不再作为本轮下一步。路径映射优先复用适配器能力，同一对路径空间只转换一次，不预设远端适配器必须由 Core 翻译。

实现现状不变：#1525 仍只有契约和 Rust 校验，macOS 宿主尚未接入 attach / 外部 DAP 直连；上面的范围与验收要求不是已完成声明。

声明形态

attach 配置的 targetBindings 新增 connection，目标种类 connection（TARGET_KINDS 里原本就有，之前没有事实和绑定）。下面展示嵌套参数绑定与映射形状，不是完整的 debugpy --listen 连接配置：

"configurations": {
  "attach": {
    "arguments": { "timeout": 5000 },
    "targetBindings": {
      "connection": {
        "host": "connect.host",
        "port": "connect.port",
        "pathMappings": { "shape": "objects", "argument": "pathMappings",
                          "localKey": "localRoot", "remoteKey": "remoteRoot" }
      }
    }
  }
}

• 值是适配器参数里的目的地路径，不是固定的目标参数名。各适配器给主机和端口起的名字、嵌套都不一样（hostName/port、connect.host/connect.port、一个 host:port 字符串），按固定名字就得让宿主为每个适配器记名字，等于重新按名字分支。路径最多 4 段，中间对象由 Core 创建。
• host + port 成对，或 address（一个 host:port 字符串，IPv6 带方括号）；至少要有其中一种。
• pathMappings 可选，四种形状，覆盖按上游文档核对过的主流适配器：objects（对象列表：debugpy pathMappings、delve substitutePath）、first（唯一一条映射写成 local/remote 两个字符串：js-debug）、dictionary（以 keyedBy 一侧为键的对象：CodeLLDB sourceMap、PHP pathMappings）、pairs（二元数组列表，order 为 remoteLocal/localRemote：lldb-dap sourceMap）。
• 目的地冲突在声明期拒绝：与其他目的地、processId/cwd 参数，或同一配置默认 arguments 里已有的名字相同、包含或被包含，清单就是 plugin.manifest.invalid。否则“默认值优先”会让适配器连到用户没有确认的主机。
• connection 只允许在 attach 下；selectors[].targetKinds 列 connection 时适配器必须声明该绑定。

运行时行为（debug.adapters.startArguments）

• 目标 {kind: "connection", host, port, pathMappings?}。主机是 DNS 名或 IP 字面量（1–253 字符，标签 ≤63、不以 - 开头或结尾；不接受 scheme、端口、方括号、空白、用户名；全数字点分必须是合法 IPv4）；端口 1–65535；映射最多 16 条（first 形状只接受 1 条），每个根 1–1024 字符且无控制字符，本地根必须是绝对路径。错误码 debug.target.invalid，字段 target.host / target.port / target.pathMappings / target.kind。
• 映射装不下就拒绝，不截断、不丢弃：适配器没有路径映射绑定、first 收到多于 1 条、dictionary 在键的一侧出现同一个根两次，都返回 debug.target.invalid（target.pathMappings）。丢掉的话会话能启动但断点对不上源码，比启动失败更难排查。
  • 行为修正，请注意：本 PR 第一版的 first 只取第一条映射、静默丢掉其余的，与上面的原则矛盾，审计时发现后改成拒绝。debugAdapters 属于尚未发布的 API 4，没有已发布的契约被改动。
• 响应新增 connection: {host, port, remote}。remote 只在字面量是 localhost（不分大小写）、127.0.0.0/8、::1 时为 false，其余一律 true，包括 0.0.0.0、::ffff:127.0.0.1、localhost.example.org。Core 不解析域名、不开 socket；判断不了就当远端，最多多问一次。
• 启动计划的 debugAdapter.remoteAttach 是 {pathMappings: bool, maxPathMappings: n} 或 null（first 为 1，其余映射形状为 16，无映射为 0），宿主据此决定是否显示“连接到远程主机”、映射列表以及最多几行，不按适配器名字判断。
• 不新增权限：debug.attach 已覆盖，权限表里补了说明。宿主以后对每个新的非回环端点单独确认、默认不记住（和摄像头/麦克风“每次请求都不默认有权限”同一原则）。

改动清单

Rust Core

• debug/adapters.rs：新增 DebugConnectionBinding、DebugPathMappingBinding（objects/first/dictionary/pairs）；DebugConfiguration::validate 增加 attach-only、成对、目的地冲突校验；TargetFacts 增加 host/port/pathMappings；新增 bind_connection、set_argument（只写空位、自动建中间对象）、主机/端口/映射/回环判断；start_arguments 返回 StartArguments { arguments, connection }；plan_descriptor 增加 remoteAttach；plan() 对不支持 connection 的请求或适配器拒绝 connection 目标。
• plugins/declarative.rs：debug.adapters.startArguments 返回 connection。
• tests/declarative_plugins.rs：新增 9 个 Core 测试（四种参数形状写入、IPv6、四种路径映射形状、回环分类、非法主机/端口、不可用映射及 first/dictionary 装不下时的拒绝、launch/无绑定适配器拒绝、逐适配器的 remoteAttach 描述符）；拒绝 fixture 驱动器支持可选的 context.request。

契约与文档

• plugin-manifest.schema.json：connection 及 debugArgumentName/debugArgumentPath/debugConnectionBinding 定义（host↔port dependentRequired，host 或 address 至少一个）。
• 新增 fixture debug-adapter-remote-attach.plugin.json（六个适配器，覆盖 flat、nested+objects、scalar+first、joined address、keyed+dictionary、paired+pairs）；debug-adapter-rejections.json 新增 28 条用例。
• 契约 README.md：新增“Remote attach”一节、configurations 行和 debug.attach 权限行；rust-core-api.md：startArguments 的目标字段、响应和错误；shared/proposals/debug-adapters-1210/README.md：targetBindings 段落。
• [Feature] 类型化 DebugAdapter Registry 与第三方 DAP 接入现有 Debug UI #1210 Agent Note 新增“远程 attach”一节：决策表、被否方案、没做的内容与原因；新增“兼容性审计”：逐个适配器标注每条结论是“已核对”（读过上游文档）还是“待核验”（来自记忆），列出 11 个缺口（G1–G11）的现状、决定和触发条件，以及后续路线；原“下一步：适配器在远端”改为暂缓子方案，并同步调整后续路线。
• 新增 Agent Note 2026-10-27-debug-network-paths-and-tcp-lifecycle.md（提议中）：普通 TCP 与独立网络通路的范围、两条连接的区别、复用 feat(debug): #1210 tcpLanguageServer 调试传输：调试适配器随插件语言服务器运行（Java 迁入插件的第一步） #1520、取消 / 超时 / 过期回调 / 幂等清理 / 资源所有权的验收，以及后续网络方案待评审事项。没有预增代理或隧道清单字段。
• Agent Note 2026-10-27-remote-debug-adapter-over-ssh.md 保留原有设计探索，但明确暂缓。修正“远端适配器必须由 Core 翻译路径”的过度断言：debugpy 的原生 pathMappings.localRoot 是客户端路径前缀，不要求该目录存在于适配器机器；优先上游映射，不重复转换。主 Note、契约 README 和声明草案同步区分 debuggee 参数与 DAP 端点。
• 功能矩阵 plugin-debug-adapters.json：补证据和验证说明（macOS 宿主尚未接入，Windows 仍为 missing）。

没做的（有意）

• 网络代理、隧道、端口转发、跳板、SSH 远端执行：独立方案评审，本轮不新增相关清单字段、认证界面或辅助进程。现有远程工作区的 TransportChain / PortForward 是后续复用候选，不代表调试宿主已经接入或具备完整的托管清理能力。
• 兼容性审计里编号的缺口（G1–G11）：保留记录，不在本次设计更新中预先实现。G2 包括 debugpy --listen、Godot 和 dlv dap --listen 的 DAP 直连入口；它应与适配器连接 debuggee 的 connection 分开，也不强制绑定 attach 请求。G4 的监听 attach、空闲端口、URI、命令模板、带参数 LSP 命令等按真实插件需求单独推进。导入 launch.json 不支持的远程字段时拒绝并说明，不悄悄忽略。
• IPv6 zone ID、国际化域名：前者依赖本机网卡、写进可分享配置不可移植；后者请用 punycode。
• 绑定键等于参数名的写法：见上，已否决。

注意：fixture 和参数形状不是适配器运行验收结论，Core 不内置任何一个参数名。此次额外核对了 debugpy 1.8.22 的 listen 启动 DAP 适配器、客户端路径映射 和 GDB 16.3 的 attach target：GDB 接受裸 host:port，自己拼 target remote，无需额外前缀。其余未核验组合仍保持待核验，不能宣称“兼容所有调试器”。

本地验证

2026-10-27 合入 preview 与冲突处理

• feat(debug): #1210 tcpLanguageServer 调试传输：调试适配器随插件语言服务器运行（Java 迁入插件的第一步） #1520 合并后撤掉堆叠基线，保留其后补的完整实现：从保存配置启动时主动激活语言服务器、端口命令的取消与期限、工作区 / 会话替换后的旧结果保护；相关 macOS 源码和测试与本次 preview 基线逐字节一致。
• 共享测试保留本 PR 的远程 attach fixture 和绑定校验；Agent Note 与功能矩阵同时保留 feat(debug): #1210 tcpLanguageServer 调试传输：调试适配器随插件语言服务器运行（Java 迁入插件的第一步） #1520 新增的生命周期说明、证据和本 PR 的契约说明。相对 preview 仍是原有 13 个文件，没有新增网络代理、转发或宿主 attach 实现。
• Rust 逐例计时通过：1296/1296，无超时、无超预算。命令：GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=init.defaultBranch GIT_CONFIG_VALUE_0=master node .agents/skills/write-stable-tests/scripts/run-rust-tests-with-timing.mjs --manifest rust/Cargo.toml --package lithe-core --suite-timeout-ms 1200000 --report .artifacts/test-stability/pr1525-merge-rust-master.json。HTML / JUnit / JSON 均已核对，本 PR 9 个远程契约测试为 8–19 ms，最慢为 debug_start_arguments_refuse_a_remote_target_without_a_usable_endpoint（19 ms）。
• 首次 Rust 运行的环境限制（保留记录）：933 例通过后，既有 git_line_history_keeps_first_parent_chain 在 checkout master 失败；该测试在 git init 后硬编码 master，本机 init.defaultBranch=main。上面的完整通过记录仅在测试进程设置 init.defaultBranch=master 后获得，未改全局 Git 配置，也未修改该基线测试。
• verify-agent-notes（162 篇）、verify-shared-contracts、verify-runtime-bundle-immutability、verify-service-boundaries、verify-windows-boundaries、verify-rust-core-comments、verify-rust-core-layout、Rust 格式检查、i18n 校验、generate-i18n --check、测试稳定性静态门禁和 diff 空白检查均通过。
• 精确提交矩阵门禁通过：./scripts/verify-platform-feature-matrix-change.sh cdeec194935a3450ebb17c1ef1204cf1aa7fac6f cf4ffab70648e8260c116b0866279e8b6172da1c；./scripts/verify-platform-feature-matrix.sh 通过（209 项能力）。
• Swift 本地未验证成功：使用仓库指定 Swift 6.3.3 运行 test-stability-macos.sh --report .artifacts/test-stability/pr1525-merge-swift.json -- --filter 'PluginDebugAdapterTests|LanguageIntelligenceModuleTests|MacBuildProviderSessionsTests'，在依赖 manifest 编译阶段因本机 Xcode 27 SDK / 编译器组合报 unknown argument: '-target-arch-variant'，0 个测试执行；未改工具链固定版本或测试来绕过。Swift 与 Windows 运行验证仍需对应 CI，不能把本地边界检查当成平台测试通过。
• 本次没有启动 Lithe 应用或 SSH 隧道；测试进程已退出。本地计时报告在 .artifacts/test-stability/index.html 与 pr1525-merge-rust-master.html，不提交生成物。

上一次范围与文档更新的验证记录（保留）

• ./scripts/verify-agent-notes.sh：162 篇 active Note 通过。
• ./scripts/verify-shared-contracts.sh：通过（共享 i18n 与 debug v1 基线检查包含在内）。
• ./scripts/verify-platform-feature-matrix-change.sh 979ba5ae58b45ccddbeb81f9c26622c4d611b12a b1452a6b08cec2a68fe807215b56915532c08fba、./scripts/verify-platform-feature-matrix.sh：通过（209 项能力）。
• ./scripts/verify-runtime-bundle-immutability.sh、git diff --check：通过。
• 仅更新设计 / 契约说明，没有修改 Rust / Swift / TypeScript 实现或测试；没有启动 Lithe、适配器或 SSH 进程，也没有重跑下面的原契约实现全量测试。

原契约实现提交的验证记录（保留）

以下是原 PR 已有记录，不冒称在本次文档更新中重新运行；全部通过，除其中两条说明：

• cargo test -p lithe-core：1264 + 2 + 25 + 5 个测试通过，0 失败（其中包含本 PR 新增的 9 个 Core 测试和拒绝 fixture 驱动的 28 条新用例）。
• cargo fmt -p lithe-core -- --check、bash scripts/verify-rust-core-comments.sh：通过。
• zsh scripts/verify-shared-contracts.sh（契约 fixture、i18n 9372/9372 完整、debug v1 基线 15 项：covered 14、partial 1）、zsh scripts/verify-agent-notes.sh（161 篇）、zsh scripts/verify-platform-feature-matrix.sh（209 项能力）、git diff --check：通过。
• 平台功能矩阵变更门禁（verify-platform-feature-matrix-change）：通过。
• clippy 说明：cargo clippy -p lithe-core --all-targets --no-deps -- -D warnings 在较新的工具链（1.96）上报 62 条，全部在本 PR 没有改动的行上（例如 debug/adapters.rs 里 3 处 map_or(true, …) 在基线 HEAD 就存在；plugins/declarative.rs 和 tests/declarative_plugins.rs 没有任何条目）。仓库脚本只门禁 rustfmt，不门禁 lithe-core 的 clippy，所以我没有顺手改这些旧代码，避免扩大 diff。
• verify-rust-core-crates.sh 说明：整套脚本曾因 node --test scripts/test-ide-mcp.mjs 首次运行时 initialize 超时而退出 1（冷启动，与本 PR 无关）；单独再跑通过。
• 没有启动 Lithe 应用，核对后无 Lithe/ssh 残留进程。macOS 宿主未接入 attach，所以应用内的行为验证留给宿主接入的 PR。

后续（不在本次文档更新）

• 当前传输优先完成 feat(debug): #1210 tcpLanguageServer 调试传输：调试适配器随插件语言服务器运行（Java 迁入插件的第一步） #1520 普通 TCP 的连接与生命周期验收；代理 / 隧道 / 转发 / SSH 远端执行另案，不影响普通 TCP 交付。
• macOS 宿主：接入 attach，通用“附加到远程”对话框取代仅限 Java 的 JavaAttachView，非回环端点确认，文案走 shared/i18n。附加结束沿用 terminateDebuggee: false，只断开不结束远端程序。
• 合并后在 lithe-plugin-docs 运行 node scripts/contract.mjs sync --revision <合并后的 preview commit> 同步契约副本。插件后端协议没有变化，不需要跑 SDK 端到端。
• feat(debug): #1210 tcpLanguageServer 调试传输：调试适配器随插件语言服务器运行（Java 迁入插件的第一步） #1520 之后的 PR-B / PR-C（Java 迁入 Java Support 插件）与本 PR 互不依赖。

[lithe-code-review]

Lithe Review

结论： ✅ 通过
范围： feat/1210-java-debug-plugin ← feat/1210-remote-attach-contract · head: c9df5b7

未发现需要阻塞合并的问题。

Scope Check

• 关联 Issue 或需求是否完成：[Feature] 类型化 DebugAdapter Registry 与第三方 DAP 接入现有 Debug UI #1210 的整体验收仍未完成。本 PR 完成远程 attach 的共享契约与 Rust Core 校验这一部分。
• 已完成范围：声明 schema、主机/端口和路径映射验证、参数绑定、remoteAttach 描述符、拒绝与成功 fixture，以及相关文档和测试。
• 未完成范围：macOS 宿主的 attach 输入与非回环确认、Windows 宿主接入，以及合并后的 lithe-plugin-docs 契约同步；这些在 PR 范围说明和功能矩阵中均标为后续工作。
• 是否复用了已有上游能力，或对自研边界给出充分证据：Core 负责把通用目标事实写入适配器声明的参数路径，没有重建 DAP 调试器行为。架构笔记列出了参数形状和未覆盖的连接方式；本次未独立核验外部适配器文档。
• 每个 Finding 是否由本次变更引入或加剧：未列出 Finding。
• 是否属于本次变更职责范围：检查范围内的代码、契约与文档职责一致；宿主端到端接入明确不属于本 PR。

Summary

远程目标校验、目的地冲突拒绝、路径映射形状转换及映射容量不足时拒绝的逻辑与新增契约相符。Core 测试覆盖了参数写入、回环分类、无效输入、映射拒绝和计划描述符。此 PR 尚未让产品宿主执行远程 attach；当前 macOS Swift 包装器仍未传递新目标字段或向调用方提供 connection 元数据，需由后续宿主接入完成。

Verification

• 实际检查：给定 base...head 的 12 个文件差异；Rust Core 实现、声明式命令、测试与拒绝 fixture、manifest schema、API/插件契约文档、功能矩阵和相关 Agent Notes；并查看了 base 中对应的 Core 与 macOS API 形状。
• 已提供的测试或 CI 结果：PR 描述报告 cargo test -p lithe-core、格式和若干契约/笔记/矩阵验证通过；提供的 head Check Run 列表中 Rust Core tests 标为 skipped。这些结果未在本次独立复跑。
• 本次未运行的测试：所有测试、验证脚本和应用；未访问网络。
• 仍存在的非阻塞风险或平台验证缺口：macOS 尚未接入远程 attach，Windows 插件调试宿主仍标为 missing；因此远程连接确认和实际会话行为尚无本 PR 内的宿主验证。