[xiaoyumuxi]

关联 #1210。本 PR 只提交设计和实施计划，不关闭功能 Issue，不修改产品代码或正式契约。

方向调整：重写统一调试内核，而不是在两套内核上补丁

上一版方案是“Registry 先接入，Swift/Rust 两套内核以后在 Provider 背后慢慢整合”。评审后改为：在 Rust Core 里重新设计一个统一的 DAP 客户端内核，macOS 和 Windows 都通过 debug.* 使用它；平台只负责进程、socket、终端和界面。内置适配器和第三方插件共用同一个类型化 Registry，插件只声明“怎么启动调试器”。

本轮改动

• 主 Note 重写并改名：2026-10-25-debug-adapter-provider-and-declarative-registration.md 改为 2026-10-25-unified-debug-engine-and-adapter-registry.md。
  • 内容包括现状盘点（两套内核、按语言的工厂、以源码为中心的 v1 投影）和内核 / 平台 / 插件 / 调试器四方职责表。
  • 会话模型 v2 第一版就预留扩展位置：可选的 source/line/column、字符串地址、presentationHint 透传、引用绑定暂停代次、能力快照、保留未知值。
  • 扩展机制：宿主内核模块注册处理器，客户端能力由已注册的扩展决定，插件 JSON 里不出现。
  • 迁移分为 P0 行为基线 → P1 新内核与 v2 → P2 内置迁移与 Registry → P3 第三方声明契约 → P4 双端第三方验收 → P5 删除 Swift 会话、按语言工厂和 v1。
• 能力分三层：
  • 必选层（[Feature] 类型化 DebugAdapter Registry 与第三方 DAP 接入现有 Debug UI #1210 的关闭条件）：生命周期、行断点与位置修正、continue/pause/step、threads/stackTrace、scopes/variables 分页、核心事件；
  • 推荐层：evaluate 的 watch/hover/repl；
  • 可选扩展：其余全部。
• 原生投影 Note 改为可选扩展 Note：2026-10-25-native-debug-projections.md 改为 2026-10-25-optional-debug-extensions.md。
  • 覆盖全部可选分组：断点增强、表达式与变量、执行控制增强、无源码与生成代码、原生调试、进程与模块、语言专属。每组列出 DAP 请求、客户端能力和界面入口。
  • 明确区分反编译（适配器通过 sourceReference 返回源码）和反汇编（disassemble）。
  • 写操作单独授权；给出实现顺序，其中 startDebugging 是删除 Swift 会话的前置条件。
• 新增会话投影 v2 草案：debug-session-projection.draft.schema.json 和 projection-v2-examples.draft.json。
  • 4 条接受样例：有源码帧 + 无源码汇编帧、会话内反编译源码、registers scope 与未知提示、未注册内存扩展时的能力快照。
  • 5 条拒绝样例：数字地址、无 source 却有 line、两种源码身份同时出现、路径逃逸、缺少暂停代次。
• README 与链接：README 开头改为说明本目录评审“插件声明 + 投影 v2”两份跨端草案，插件声明部分（API 4、debugAdapters 1、serverProcess 2、传输、S01–S02 / C01–C09 拒绝表）保持不变；公共扩展契约 Note 的链接指向新文件名；旧阶段编号 P1–P3 改为 P3–P4。

保持不变的部分

插件声明沿用上一版：复用 serverProcess、stdio/tcpAnnounced/tcpPort 传输、标准能力跟随 DAP 协商且只能 capabilities.disabled、Java 作为内置 Provider、没有依赖/导出/工作流/resolver/hostIntegration 字段。插件依赖与导出仍是独立平台提案。

评审入口

• 统一调试内核与调试适配器 Registry
• 可选调试扩展
• 会话投影 v2 schema / 样例
• 插件声明草案 README / 能力块 schema
• 独立的插件依赖与导出提案

验证

• 投影 v2：Python jsonschema 离线按 Draft 2020-12 检查 schema 本身，4 条接受样例通过、5 条拒绝样例都被拒绝。
• ./scripts/verify-agent-notes.sh：157 篇 active Note 通过。
• ./scripts/verify-shared-contracts.sh、./scripts/verify-runtime-bundle-immutability.sh 通过。
• node scripts/verify-app-language-localization.mjs、node scripts/generate-i18n.mjs --check 通过；git diff --cached --check 通过。

上一轮的 semantic-rejections.draft.json 未改动：其中 15 条 Core 语义拒绝仍是 pendingCoreImplementation。本次没有运行产品构建或真实调试，没有启动 Lithe 或调试进程，schema 校验不构成运行时证据。只改设计文档，不涉及平台行为，因此不更新功能矩阵。

[lithe-code-review]

Lithe Review

结论： ⚠️ 有建议
范围： preview ← feat/1210-debug-adapter-provider · head: 22ac9a4

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

Findings

1. [P2] 能力快照应能表示直接绑定本包函数的能力
   shared/proposals/debug-adapters-1210/debug-capability-state.draft.schema.json:33

   • 实际影响：注册草案允许直接调用本包后端函数，但能力快照要求所有 source: "backend" 状态都提供 {pluginID, export}。对于没有导出的本包函数，宿主无法生成既符合 schema、又准确描述来源的快照。
   • 触发条件：能力通过 invoke.use: {backendRef: "resolver", functionID: "debug.hotCodeReplace"} 实现，没有对应导出。这种绑定由注册 schema 的 functionCapability 和组合 schema 的 use 明确允许。
   • 复现步骤：为上述能力构造 {state: "supported", source: "backend"}；它因缺少 provider 被拒绝。改用 {pluginID, backendRef, functionID} 描述来源，又会因缺少 export 和存在额外字段被拒绝，只能虚构一个未声明的导出。
   • 来源：本次引入；属于新增草案之间的一致性问题，尚未影响产品运行。

Scope Check

• 关联 [Feature] 类型化 DebugAdapter Registry 与第三方 DAP 接入现有 Debug UI #1210：本次交付设计与实施计划，不关闭功能 Issue；Registry、第三方 DAP 完整流程及 Windows 实机验收仍待实现。
• 已检查全部 29 个变更文件；没有产品实现、正式插件契约、测试代码或生成文件变更。
• 提案明确复用现有 DAP、插件函数通道、JDT 工程事实和平台资源清理链路，并保留旧 API 与分阶段迁移边界。
• Finding 属于本次新增 schema 的职责范围，没有要求修复历史问题。

Suggestions

1. 将能力来源建模为可区分的引用：依赖导出使用 {pluginID, export}，本包函数使用 {pluginID, backendRef, functionID}；明确组合流程的来源表示，并补充无导出本包函数的能力快照正例。

Summary

提案清楚区分设计与已实现能力，兼容性、上游复用及资源所有权方向与现有边界一致。建议先补齐能力声明与状态投影之间的表达缺口，避免后续双端实现自行补充不同规则。

Verification

• 静态阅读全部变更文件，并追踪现有调试工厂、配置解析、Node TCP transport、共享 Debug/函数契约及相关架构 Note。
• 作者报告离线 schema/示例校验、Agent Notes、共享契约、安装包只读与 i18n 检查通过；本次未独立执行这些检查。
• 提供的 head Checks 中，Agent Notes 和平台 gate 有成功记录；Rust、Swift、Windows 等产品测试为 skipped，不能作为运行时兼容性证据。
• 本次未运行代码、脚本、测试或应用，未访问网络。双端真实调试、取消竞态和清理验证仍属于后续实施验收；本次无 UI 改动，不要求界面截图。

[xiaoyumuxi]

评审意见：方向调整为「重写调试内核 + 沿用现有插件声明」

结论：目标是兼容 GDB / LLDB 等多种调试器，并支持线程、寄存器、内存、汇编等能力。这个目标靠**重新设计统一的调试内核（DAP 客户端）**来实现，插件只负责声明“怎么启动调试器”。当前草案在插件协议层新造了依赖、导出和 JSON 工作流，这些现有契约大多已经覆盖，有两处还和现有规则冲突。建议按下面的方式收窄范围后再推进。

1. 现有协议已覆盖的部分，不要再造

草案新增	现有契约中已有	建议
backends.process、debugProcess.dependencyRuntime	serverProcess 的 packaged / systemCommand / runtime 启动方式、启动模板（${pluginDir}、${stateDir}、${setting:…}、${arch}）、languageServerLaunchPlan 按 languageID / buildSystemID / vcsProviderID / backend 选择进程	新增 debugAdapterID 选择项，安装审查、路径校验、requiredPackagePaths 全部沿用
依赖 python-runtime 插件导出 selectedInterpreter	runtime 的 tool + runtimeDependencies、executableResolution: 1 候选链（setting / projectFile / environment / command）	用现有解释器/工具选择机制，不引入插件依赖
backend.kind: "hostIntegration", integrationID: "jdt"	languageServers[].hostIntegration: { id: "jdt", capabilities: ["debug", "run", "testing"] }，仅 dev.lithe 可声明	Java 调试已有声明方式；草案写法还绕开了“仅官方插件”限制
steps / use / with / $value 工作流与 debug.process.acquire、debug.session.plan	Build 的 Core plan → 宿主执行 → Core decode 模式（build.modelPlan / build.decodeModel）	改为 Core 命令（如 debug.launchPlan），编排留在 Core
动态解析走 lithe/function/invoke + 领域绑定	Build Provider：initialize 协商 litheBuild，类型化方法 lithe/build/model	照搬：协商 litheDebug，类型化 lithe/debug/* 方法
能力 source: dap | function | disabled，省略即不展示	领域操作由 manifest source 选唯一实现；其余靠 initialize 协商	标准能力跟随 DAP initialize / capabilities 事件，manifest 不再逐项声明
targetBindings	executionProviders 参数模板 ${file}、${fileDirectory}、${userArguments}	沿用同一套模板变量
start-plan 自定义错误码	「Outcomes and error codes」的 plugin.* 稳定码	沿用，按需新增 plugin.debug.*

2. 与现有契约冲突的两处

• shared/contracts/plugins/v1/README.md「Declarative or backend implementation」规定：领域操作必须通过类型化方法和 Core 的 plan/decode 命令实现，never through a plugin function。草案把 debug.resolve 放进插件函数，并写明“不另建 lithe/debug/*”，方向正好相反。
• 同文件 Build providers 规定：“Two plugins never share a process, and the host never relays messages between processes”。跨插件 exports 调用本质上就是宿主在插件进程之间转发消息。插件依赖如确有需要，应作为插件平台级提案单独评审（包括市场依赖解析、菱形依赖版本冲突、禁用/卸载级联、信任传递），不放在 [Feature] 类型化 DebugAdapter Registry 与第三方 DAP 接入现有 Debug UI #1210 里。

3. Schema 校验覆盖不到语义规则

离线校验时，14 个示例通过；下面 7 个本应拒绝的输入也全部通过：

• 引用未声明的 dependency
• 引用未声明的 backendRef
• 插件依赖自身
• 重复的 adapter id
• 重复的 step id，或引用不存在的 step
• launch 把 program 绑定到 target.processID
• stepBack 走没有契约的 function

JSON Schema 本身做不到这类交叉引用检查。正式设计需要列出 Core 语义校验规则清单，每条配一个拒绝 fixture。

其他细节：

• node.registration.json 支持 file 目标，但没有 program 绑定。
• ${pluginDir} 出现在 dependencyRuntime 参数里，没写明属于哪个包。
• preparation 是任意字符串，应改为类型化的 Build/Run 动作引用，并限制最多重入一次。
• 两份 schema 的 id pattern 大小写规则不一致。
• registration 没有 pluginAPIVersion / requires / permissions，看不出挂在 manifest 的哪里。

4. 建议的新范围

主提案：重写调试内核 + Registry

1. 用一个统一的 DAP 客户端内核取代现在 Swift DebugAdapterProtocolSession 与 Rust CoreDebugAdapterProtocolSession 两套会话，去掉按语言（Java / Go / Node）的专用分支。
2. 插件声明沿用现有协议：requires.debugAdapters: 1；debugAdapters[] 声明 id、adapterID、languageIDs、configurationTypes、launch/attach 参数模板；进程用 serverProcess；transport 只有 stdio 和固定几种 TCP 端口发现方式。按能力版本规则，新增调试权限（如 process.debug）需要新的 API 级别。
3. 可选 Debug Provider：只在需要动态解析配置时使用，按 Build Provider 模式协商 litheDebug，配合 Core 的 plan/decode 命令。
4. Java 继续走 hostIntegration.capabilities: ["debug"]，热替换作为内核的扩展请求。
5. 第一个第三方接入用 GDB DAP（gdb -i=dap）或 lldb-dap，跑通源码级调试，证明内核与语言无关。

迁移

• 先把旧行为录成基线 fixtures：Java 热替换与 JUnit/TestNG、调试用 Run 的 JDK、Node 子会话与 source map、断点先于 launch 入队、停止与清理顺序。
• 按适配器逐个切换到新内核，同一目标只启用一个实现；功能等价后再删除旧路径。macOS / Windows 分别提供真机证据。

扩展（汇编、内存等）单独成 Note，但新内核第一版就要预留模型

第一版就定下来	原因
栈帧 source / line / column 可选，带不透明的 instructionPointerReference	目前 DebugStackFrame.line 是必填 i64；以后再改就是破坏性变更
地址、内存引用、指令引用一律用字符串	避免 JS 数值精度问题，以后不改类型
scope 透传 presentationHint（如 registers）	寄存器视图直接按提示筛选
功能是否显示由 DAP initialize 能力与 capabilities 事件决定	扩展上线只是多一个按能力显示的入口
请求分发按请求名注册处理器	加 readMemory / writeMemory / disassemble / setInstructionBreakpoints 只是新增条目
客户端能力（如 supportsMemoryReferences，目前写死 false）由已注册的扩展决定	没装扩展就不声明
Rust / Swift / TypeScript 共用 fixtures，包含无源码栈帧样例	三端从第一天就能解码

扩展是宿主侧的内核模块加界面，不放进插件 JSON 的 source: function。插件只负责启动调试器，能力由 DAP 协商。

参考：Rust Core 当前已实现 threads / stackTrace / scopes / variables / setVariable、各类断点（含 data breakpoints）、step / stepBack / pause、runInTerminal；尚未实现 readMemory、writeMemory、disassemble、setInstructionBreakpoints、指令粒度单步、modules / loadedSources、startDebugging。

注：微软 cpptools 的 OpenDebugAD7 / vsdbg 许可证只允许在微软 VS 系列产品中使用，不能打包。GDB 14+ 原生 DAP、lldb-dap、CodeLLDB（MIT）可以使用。

[xiaoyumuxi]

补充：调试能力分层（必选 / 推荐 / 可选）

基本的断点调试、调用栈和变量查看属于必选，其余能力都按适配器在 DAP initialize 中声明的 capabilities（以及之后的 capabilities 事件）开关：支持就显示，不支持就隐藏。插件 manifest 不逐项声明。

必选：接入的适配器都必须支持，宿主必须实现

类别	内容
会话生命周期	initialize；launch 或 attach 至少一种；configurationDone；disconnect / terminate；停止与资源清理
断点	行断点（setBreakpoints）；断点确认与位置修正（verified、移到有效行）
执行控制	continue、pause、next、stepIn、stepOut
调用栈	threads（调用栈按线程获取，不能省）、stackTrace
变量	scopes、variables（含嵌套展开与分页）
事件	stopped（带停止原因）、continued、exited / terminated、output

Rust Core 目前已实现以上全部内容。新内核主要是重新整理和统一实现，不是新增功能。

推荐：协议上是可选，但优先做

• 监视表达式、悬停求值、调试控制台（evaluate 的 watch / hover / repl 上下文）。用户通常把它们视为“变量追踪”的一部分。GDB / LLDB 的大量功能也要靠控制台命令，没有控制台，原生调试的体验会明显变差。

可选：按适配器能力启用

分组	内容
断点增强	条件断点、命中次数、日志点、函数断点、异常断点过滤、数据断点（监视点）
表达式与变量	setVariable、setExpression、completions
执行控制增强	stepBack / reverseContinue、restart、restartFrame、gotoTargets、stepInTargets
无源码 / 生成代码	source 请求（sourceReference）：反编译源码（如 Java jar 中的 class）、JS 中 eval 生成的代码。反编译和反汇编不同：反编译由适配器直接返回源码内容
原生调试	寄存器（scope 的 presentationHint: "registers"）、readMemory / writeMemory、disassemble、setInstructionBreakpoints、granularity: "instruction" 单步
进程与模块	modules、loadedSources、startDebugging 子会话、runInTerminal
语言专属扩展	Java 热替换等，以内核扩展请求的形式接入

注意

“可选”指功能可以晚做、适配器可以不支持，数据模型本身不能可选。上一条评论“扩展预留”表里的内容需要在新内核第一版里定下来：可选的 source / line / column、字符串形式的地址与引用、透传 presentationHint、能力驱动界面、按请求名分发、三端共用 fixtures。之后加上可选功能时只做增量，不改已有结构。

验收建议：

• [Feature] 类型化 DebugAdapter Registry 与第三方 DAP 接入现有 Debug UI #1210 只要求必选层，加上一个真实第三方适配器（GDB DAP 或 lldb-dap）跑通。
• 推荐层和各可选分组各自独立验收，适配器不支持的功能要明确显示为不可用。