v2.5.1

Fixed

• ui_* 失败不再丢失错误码（误诊根因）：FlaUI 的 UIA 异常（ElementNotEnabledException 等）Message 恒为空串，真正的成因只在 InnerException.HResult。旧实现只取 ex.Message，于是禁用控件上的写值/聚焦失败表现为「SetValue 调用失败：」——冒号后面什么都没有，无法归因。现在按 HRESULT 译成可操作中文（禁用 / 元素已失效 / 无点击点 / provider 不支持 / 未实现 / 权限不足 等），并附异常类型与错误码。
• 失败引导按成因分流：此前所有 pattern 调用失败都被追加同一句「若为目标后台/不可见…用 ui_get what=offscreen 确认」，对禁用控件属误导（实测 offscreen 恒为 false）。现在禁用控件引导去确认 enabled 并说明常见前置，元素失效引导重新 ui_find，provider 未实现引导换驱动路径；仅成因无法识别时才退回原「后台/不可见」提示。
• ui_find 清单标出禁用控件：IsEnabled=false 的控件在行尾追加 [禁用]，选 index 时即可看出哪些点不动（此前只能逐个 ui_get what=enabled 才能发现）。

v2.5.0

Breaking

• debug_verify 工具与场景 JSON 整体移除：不再提供「一份场景文件跑重编译 + 断点 + 断言 → PASS/FAIL」的一键复验。需要复验时按普通工具组合：debug_breakpoint → debug_continue/debug_wait → debug_frame/debug_evaluate，UI 部分用 ui_action/ui_input/ui_get/ui_wait；防回归断言建议直接写进项目自己的测试。握手与 --features 不再提及该能力。

Added

• ui_input 新增 commit 参数（默认 true）：写完把焦点移出目标控件，让「失焦才提交」的绑定（WPF TextBox.Text 默认 UpdateSourceTrigger=LostFocus）真正拿到新值——此前写入后立刻点「搜索/保存」，应用读到的仍是旧值。代价是这一步会激活目标窗口；只想改控件文本、不动焦点时传 commit=false。
• ui_action clickPoint=true 点击前先激活目标窗口：被遮挡或非前台时，第一次点击不再被系统「激活动作」吃掉（此前可能点在遮挡窗口上）。

Changed

• UI 自动化策略调整：功能优先，允许短暂接管焦点。语义动作仍走 UIA pattern 且默认不改前台；写值提交与真实点击会接管焦点/前台。工具 [Description]、握手说明与 README 同步更新。

v2.4.2

Changed

• 默认工具面恢复全量：不传 --features 时启用全部能力族（反编译 / 调试 / UI 自动化 / 截图）。--features 语义为白名单——只注册列出的族，未列出的族不进工具目录、握手也不提。
• 反编译族恒启用、无法关闭：--features= 空串等价于「只启用反编译」；「一个族都不启用」不再是错误配置（该状态已不可达）。

v2.4.1

Breaking

• Web 网页调试展示面完全移除：web_open 工具、--web / --web-port 命令行参数不再存在，DotNetDebugger.Web 库与其测试项目一并删除。agent 调试能力（debug_*）不受影响——调试全流程（launch/attach、断点、单步、栈/变量、改值、复验、时间线）与 CLI -dbg 一次性调试均照常可用。

Changed

• 宿主工程承载方式收窄：不再以 ASP.NET Core Web 项目形态打包，包内不再随附 Blazor 框架脚本、组件库静态资源与 Monaco 编辑器资产（安装体积与文件数大幅下降）。MCP stdio 协议行为、日志走 stderr 的纪律不变。

v2.4.0

Breaking

• 工具面重构（53 → 42 个工具），工具名与参数名变更（agent 侧契约，破坏性）：
  • 改名：call_chain → call_sequence、call_graph → call_edges、search_string → search_literals
  • 合并：debug_breakpoint_set|list|remove|clear → debug_breakpoint(action=set|list|remove|clear)；debug_exceptions/debug_exceptions_clear → debug_exceptions(action=set|clear)；debug_disconnect|terminate|reset → debug_session(action=disconnect|terminate|reset)；debug_state → debug_wait(waitSeconds=0)；debug_stack + debug_variables → debug_frame；decompile_to_project → decompile_to_dir(project=true)；screenshot_displays / screenshot_windows → screenshot(mode=list-displays|list-windows)
  • 参数改名：debug_breakpoint_set.methodToken → token、debug_breakpoint_remove.breakpointId → id、debug_step.stepType → kind、search_literals.search → contains；子串过滤统一为 contains：debug_output.filter / debug_processes.filter / debug_timeline.filter / screenshot.filter / debug_wait.outputFilter → contains
  • 必填参数归零：debug_set（path/value）、debug_evaluate（expression）、debug_object（path）均带默认值，缺参改为方法体中文提示（原为客户端绑定阶段英文错误）

Added

• decompile_il 支持 memberName/typeName 定位（与 decompile_member 对齐，多匹配列候选）。
• debug_run_to 支持 token / moduleName+ilOffset 定位（与 debug_breakpoint 四路定位对齐）。
• screenshot 新增 mode=list-displays / list-windows 只读清单模式与 filter 参数。

Fixed

• apphost .exe（.NET Core 启动器）返回中文引导并指向同名 .dll，不再暴露英文 PE image does not have metadata。
• call_edges（原 call_graph）在结果为空且程序集含 async 状态机时标注「async 方法体内的调用点未收录」，避免误判无人调用。
• debug_set 成功文案补「方法入口断点处局部变量尚未初始化，单步后可能被覆盖」。

v2.3.0

Added

• 能力族开关 --features / DOTNETDEBUGGERMCP_FEATURES：可选 decompile/debug/ui/screenshot（逗号分隔）。默认只启用 decompile——调试 / UI 自动化 / 截图三族需显式开启；未启用的族其工具不进 MCP 工具目录、握手简介也不提及。只作用于 MCP 面，CLI 执行路径（-a/-l/-dbg/-c）不受影响。
• 新增 debug_reset：强制释放调试会话（不杀目标进程），用于 debug_disconnect 失败或会话书签与引擎状态不一致时收口。
• debug_stack 新增 all：一次列出全部托管线程的调用栈（死锁/卡死排查）。
• ui_action 新增 clickPoint（默认 false）：目标控件无 Invoke/SelectionItemPattern（如部分 WPF-UI 导航项）时，可显式走真实点击——会移动光标、注入输入、可能抢前台。
• ui_find 新增 scope（限定子树，默认不限）与 depth（限定层数，默认不限）：大 UI 树/长列表可缩小枚举范围以免超时。

Changed

• 默认工具面收窄（破坏性）：不传 --features 时服务器只暴露反编译/静态分析工具；要使用 debug_*、ui_*、screenshot*、web_open，需在 MCP 客户端配置里给启动参数加 --features=decompile,debug,ui,screenshot（或设环境变量 DOTNETDEBUGGERMCP_FEATURES）。升级后若发现调试/UI/截图工具「消失」，即为此因。
• 附加/启动后即可读栈：debug_attach/debug_launch 后进程冻结期间，debug_stack（及 debug_wait/debug_state）直接可用，无需先 debug_continue——修复「附加后读不到栈、无法排查卡死」。
• 重复附加改为明确拒绝：已有活动调试会话时 debug_attach 返回中文提示（先 debug_disconnect/debug_reset），不再抛出裸 ERROR_INVALID_PARAMETER；附加失败的 COM 错误也一并中文化。
• ui_action 命中 legacy 兜底时标注「可能不生效」：不再对仅暴露 legacy 的控件（如 WPF-UI 导航项）报无条件「已 select」假成功。
• index 失效文案纠正：区分「pid 不符」与「缓存已被后续 ui_find 覆盖」，并引导用 name+type 唯一化定位。
• debug_disconnect 失败不再静默：断开失败如实上报（不再谎报「已断开」）。
• ui_* 用完释放 UI Automation 客户端：减少对目标性能观测的扰动；工具说明与握手均声明「性能/卡顿类排查优先用 debug_* + 截图」。

v2.2.0

Added

• screenshot 工具通用化（阶段一）：新增寻址模式 display（指定显示器，含 primary/left/right 邻屏）、foreground（当前前台窗口）、element（按 UIA 元素引用截单个控件）、hwnd（按窗口句柄）、clientArea（窗口客户区）；新增参数 includeCursor（叠加鼠标光标）；返回头部新增 原点/帧 坐标元数据（screen_x=原点x+图像x，图像恒为原生 1:1；帧 配合 ui_find/ui_* 的 frameId 做旧画面护栏）。mode 默认 auto（按其它参数推断），windowTitle=@active 指当前前台窗口
• 新增可复用能力库 SharpSight.Capture（WGC+GDI 截图/图像管线）与 SharpSight.UiAutomation（FlaUI/UIA 元素模型与定位），拆自宿主/Engine，行为不变
• ui_find 返回值头部含 帧: frameId=N；ui_action/ui_input/ui_get 新增可选 frameId（旧帧护栏：非当前帧拒绝并提示重新 ui_find/screenshot，0=不校验）
• 新增两个只读发现工具，补齐 screenshot 寻址参数的取值来源（此前无处可查）：screenshot_displays 列显示器清单（1 基编号/主屏/物理边界/缩放 → 喂 display）；screenshot_windows 列可见顶层窗口（hwnd/pid/标题/前台，不限 .NET 进程 → 喂 hwnd/windowTitle/processId；只列有标题且尺寸 > 0的窗口——系统 shell 助手/阴影层/零尺寸停车窗等不可寻址目标已过滤）

Changed

• ui_find 不再列出离屏（IsOffscreen=true）控件（与 screenshot element 共用同一过滤、两者 index 保持同源）：清单中既有控件的 index 可能因过滤位移，请以新的 ui_find 输出为准
• screenshot 落盘位置改为系统临时目录：默认落盘目录由 %LOCALAPPDATA%\DotNetDebuggerMcp\screenshots\ 改为 %TEMP%\DotNetDebuggerMcp\screenshots\；filePath 传相对路径时也以该临时目录为基准（此前按进程当前工作目录解析——会把图片写进调用方项目目录）
• screenshot 文档补充能力边界（行为不变）：clientArea=true 说明明确「经屏幕 BitBlt、不保证遮挡场景」；整窗回退链说明明确 PrintWindow 依赖目标窗口响应 WM_PRINT（Chromium 系/游戏等可能画黑或不全）与 BitBlt 的遮挡敏感；并注明 WGC 扩展边框与 GetWindowRect 的差值非恒定、按源分别取矩形（不施加固定偏移）

Removed

• screenshot 的 format/quality 参数已移除（破坏性）：输出固定 PNG；传入这两个参数将被忽略
• screenshot 的缩放能力已移除（破坏性）：maxDimension/maxWidth/maxHeight 三个参数删除，图像恒按抓取区域原生像素 1:1 输出（尺寸处理交模型侧，避免"服务器缩一次、模型侧再处理一次"造成坐标口径混乱）；头部随之去掉 缩放 行，原点 是唯一坐标换算量（screen_x=原点x+图像x）

Fixed

• screenshot 用 processId 定位多窗口进程时会截到 1×1 黑图却回报成功：现按「非工具窗（WS_EX_TOOLWINDOW）→ 有标题 → 面积最大」择优（此类进程 Z 序最前常是缩略图/任务栏类助手窗），并在头部新增 选择: 事实行给出所选 hwnd 与尺寸；选中窗口无标题或尺寸过小时另给 备注: 告警——便于调用方发现选错目标并改用 hwnd
• screenshot mode=element 对无独立窗口句柄的控件（XAML/UWP/WPF/Electron/Web）一律报 hwnd=0 失败：现回退到元素所属顶层窗口帧裁剪（Win32/WinForms 控件仍取元素自身根窗）
• screenshot 截最小化窗口不再静默"成功"：头部注明「目标窗口已最小化——截图为占位/残影画面，非真实界面」（此前会得到 160×28 的标题栏残影却无任何提示）
• screenshot 的 region 宽或高 ≤ 0 误报为「格式错误」：现明确提示「宽/高必须为正整数」（格式本身没错，避免调用方反复改格式）
• screenshot 落盘失败提示中英混杂：改为「落盘失败（原因）；已改为内联返回图片，可改用可写路径或去掉 filePath 重试」
• screenshot 的 timeoutSeconds 超出 0-30 时静默夹取 → 现在头部注明已按夹取后的值处理
• screenshot 的 element 序号与带过滤的 ui_find 序号不同源、会静默截到别的控件：说明已明确「序号必须是无过滤 ui_find 的 index」并推荐用控件名/AutomationId（消除原说明「建议先用 ui_find 取 index」的自相矛盾）
• 失败的 element 查找会把全局帧号推进数十（内部 50ms 轮询每次调用都产帧）→ 现在仅成功定位后产一帧，一次拼错控件名不再让刚取得的有效 frameId 失效
• 最小化窗口抓取失败时误导性归因「无桌面会话（服务/无头环境）」 → 改为「目标窗口已最小化，无法抓取：请先还原（ui_action verb=windowstate windowstate=normal）或改用 mode=screen/region」
• 最小化主窗被多余备注「尺寸极小，可能不是目标主窗」 → 已最小化时不再报（最小化尺寸必然小），仅保留「目标窗口已最小化」
• screenshot_displays 缺说明承诺的「缩放比」（100% 时被省略）→ 现在总是输出
• windowTitle="@active" 特值大小写敏感 → 改为大小写不敏感（@ACTIVE 亦可）；该入口头部与 mode=foreground 统一为「前台窗口」
• screenshot 的 filePath 不展开环境变量（%TEMP%\x.png 会生成名为 %TEMP% 的字面目录）→ 现在展开 %VAR%
• debug_terminate 对运行中的目标进程报「已终止」却实际未杀：ICorDebugController::Terminate 要求进程处于已停（synchronized）态，运行中直接调用会因未同步失败（此前被静默吞掉、误报成功）。现引擎在终止前先协作停（Stop）再终止；debug_launch 会话另用 OS 进程句柄兜底强杀；终止失败不再吞——如实返回「终止失败」。agent 仍是一次 debug_terminate 调用，无需先停/先附加
• screenshot 选中「前台无标题窗口」时备注自相矛盾：此前固定写「它不在 screenshot_windows 清单里」，但 screenshot_windows 对前台窗口即使无标题也会以 (无标题) 列出；现按该窗是否实际入清单如实区分
• 超长窗口标题被静默截断且无任何提示：screenshot_windows 与 screenshot 头部遇超长（>255 字符）标题时截到 255 却看不出被截断（看似"标题就这么长"，误判排查）→ 现截断处补 … 明示；仍不返回完整超长标题（对定位无价值、且会灌爆上下文）
• 非 100% 缩放下显示器/截图尺寸与坐标按「逻辑像素」上报：进程 DPI 感知的上下文常量传错（DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2 官方定义为 -4，误写 +4 → SetProcessDpiAwarenessContext 恒失败、进程停留 DPI-UNAWARE）。在 125%/150% 缩放下 screenshot_displays/screenshot 会把显示器与图像缩小上报（1920x1080 报成 1536x864、缩放报 100%），与「虚拟屏物理像素 / 原生 1:1」契约不符 → 现修正常量，坐标与尺寸恢复物理像素、缩放如实

v2.1.0

• 2026-09-27

Added

• ui_* 工具新增可调超时 timeoutSeconds：ui_find/ui_action/ui_input/ui_get 新增 timeoutSeconds（默认 5，1-300），ui_wait 的 timeoutSeconds 同时驱动单次 UIA 调用护栏。此前单次 UIA 调用固定 5s 护栏不可调，目标响应慢时 agent 只能看到「UIA 调用超过 5s 未响应」而无处加大超时，易误判为「环境 UIA 不可用」。超时提示现明确「这是单次调用护栏、不代表环境 UIA 不可用，可增大 timeoutSeconds 重试」

v2.0.2

• 2026-09-27

Fixed

• ui_* 工具在「桌面顶层窗口枚举慢」的机器上全族超时失败：窗口定位此前经 UIA 桌面根全量枚举（FindAllChildren），必须走完所有顶层窗口——当桌面存在响应慢的 shell 窗口（如 Progman/Program Manager）时会阻塞数秒，超过 5s 护栏后 ui_find/ui_action/ui_input/ui_get/ui_wait 一律报「UIA 调用超过 5s 未响应」。现改为在桌面取「首个匹配」（FindFirstChild 命中即返回），不再遍历整个桌面；匹配条件（ControlType.Window + 进程 + 标题）与「取首个匹配」的语义保持不变

v2.0.1

• 2026-09-24

Changed

• MCP 握手简介恢复覆盖全部能力族（agent 可见行为变化）：ServerInstructions 的「## 何时使用」此前只写反编译 / 动态调试两类，UI 自动化（ui_*）、一键复验（debug_verify）、现场改值（debug_set）、运行到目标（debug_run_to）等能力对 agent 不可发现；现补齐各能力族触发条件，简介句由「两类能力」改为静态分析 / 动态调试 / UI 自动化 / 视觉监视四族，并修正兜底前缀清单（补 ui/screenshot 及未带前缀的静态工具）