diff --git a/skills/wincode/SKILL.md b/skills/wincode/SKILL.md index a7cd80d..9101622 100644 --- a/skills/wincode/SKILL.md +++ b/skills/wincode/SKILL.md @@ -10,7 +10,7 @@ description: 使用 WinCode MCP 分析 Windows/.NET 项目源码、引用与变 只读取与当前任务有关的手册： - [代码与工作区](references/code.md)：源码搜索、上下文、引用、影响分析和 Roslyn 配置。 -- [窗口与 UI](references/ui.md)：窗口与控件定位、后台语义操作、前台键盘输入（需授权）、结果验证和源码候选。 +- [窗口与 UI](references/ui.md)：窗口与控件定位、语义操作与激活边界、前台键盘输入（需授权）、结果验证和源码候选。 - [诊断与恢复](references/diagnostics.md)：按需会话的启动、复用、结果读取和关闭，以及版本和故障恢复。按需模式先只读该手册首节。 连接固定到启动工作区；已知根一致时直接查询，不例行重复打开。`WORKSPACE_MISMATCH` 时选择目标项目的连接，可参考 `connectionGuide`；`workspace_open` 只能确认或恢复原工作区。 @@ -23,4 +23,15 @@ description: 使用 WinCode MCP 分析 Windows/.NET 项目源码、引用与变 优先按文件、符号和行范围获取小结果。参数遵循手册与实际 Schema；保留截断、降级和歧义，UI 源码候选不等于已验证的运行时映射。`SERVER_BUSY` 或超时后先按诊断手册处理，不自动重放请求或重启连接。 -用户要求执行或测试界面流程时，可自主完成定位、点击与输入；只要求评估或查看时保持只读。后台路径（inspect、click、`mode:"setValue"`）不需要前台；`mode:"type"` 会索取键盘焦点，只在用户授权前台交互后使用，用户正在游戏、聊天或会议中时先询问并由用户自己切换窗口。细节见 [窗口与 UI](references/ui.md)。 +用户要求执行或测试界面流程时，可在授权范围内完成定位、点击、输入与结果验证；只要求评估或查看时保持只读。操作前遵循下面的前台边界，字段与流程细节见 [窗口与 UI](references/ui.md)。 + +## 注意事项：后台取证不等于所有操作都不会抢前台 + +“工具不主动激活窗口”与“目标应用不会跳到前台”是两件事。不要因使用 WinCode、UIA 或某个 AI 客户端，就承诺所有步骤都不会打扰用户。 + +- **只看界面或截图时，保持只读。**复用已有实例；对确定的 PID/HWND 使用 `wincode_ui_inspect` 或 `wincode_ui_review`，设置 `backgroundOnly:true`；仅需控件信息时用 `capture:"none"`，需要图像时用 `capture:"original"`。不要为查看而额外点击、换页或填写。 +- **后台截图直接用 PrintWindow，不先把窗口提到前台。**`backgroundOnly:true` 禁止屏幕截图回退；它只约束 inspect/review 的取证方式，不是 click/type 的“禁止激活”开关。截图失败、黑图或窗口最小化时报告实际限制，不为了截图调用 `SetForegroundWindow`、恢复窗口或重新启动实例。 +- **填写必须明确选择模式。**后台写值使用 `wincode_ui_type` 且显式传 `mode:"setValue"`；省略 mode 会走默认的 `"type"`，请求焦点并发送键盘输入。控件不支持 ValuePattern 时，不自动改成 type、SendKeys 或自写聚焦脚本。setValue 不请求键盘焦点，但写值触发的应用事件仍需验证。 +- **语义点击不等于保证不激活。**`wincode_ui_click` 只调用 Invoke/Toggle/SelectionItem，不先聚焦、不模拟鼠标；目标控件的事件、导航、视图装载或弹窗仍可能带来前台变化。已有 WPF 导航按钮的反馈中，自写脚本与 WinCode 对同一按钮使用 InvokePattern 都出现了前台切换，而只读取证未观察到切换。该证据只限具体路径，不能推成“所有 Invoke/Select 都抢前台”，也不能归因于 AI 客户端身份。 +- **只授权后台操作时，不擅自进入前台路径。**启动应用、恢复最小化窗口、Focus/SetFocus、键盘或鼠标模拟都可能改变前台状态，不能当成后台步骤的自动补救。某个动作已知会抢前台，就说明该步骤的限制；没有前台授权不再执行它。若执行中观察到抢前台，停止后续动作，先只读检查状态，不反复重放来“确认”。 +- **区分复现与根因。**动作返回成功只说明调用被接受；先读回业务状态。没有发现显式 Activate 调用不等于已排除应用或框架；有限采样未见前台变化只能报告“本轮未观察到”，不能保证绝不激活。用户未要求追查时，不自行追加对照实验。 diff --git a/skills/wincode/references/ui.md b/skills/wincode/references/ui.md index b86c4d4..57fc8ec 100644 --- a/skills/wincode/references/ui.md +++ b/skills/wincode/references/ui.md @@ -67,13 +67,15 @@ captureQuality 在标注前检查原始像素，最多采样 1024 点；suspect- | 任务 | 用法 | | --- | --- | | 查看界面、定位控件 | `wincode_ui_inspect` | -| 后台点击、勾选、选择条目 | `wincode_ui_click`：Invoke/Toggle/SelectionItem，不需要前台 | -| 后台写入或清空输入框 | `wincode_ui_type` 且**显式**传 `mode:"setValue"`：ValuePattern，不需要前台 | +| 语义点击、勾选、选择条目 | `wincode_ui_click`：Invoke/Toggle/SelectionItem，不先请求焦点；应用响应仍可能激活窗口 | +| 后台写入或清空输入框 | `wincode_ui_type` 且**显式**传 `mode:"setValue"`：ValuePattern，不请求键盘焦点；应用事件仍需验证 | | 验证逐键输入、快捷键、IME 行为 | `wincode_ui_type` 的 `mode:"type"`：需要前台授权 | | 控件不支持 ValuePattern 的后台写入 | 报告该步骤无法后台完成，不自动改走键盘输入 | 用户要求执行或测试明确的界面流程时，自主完成定位、点击、输入与结果检查，不为每个常规步骤重复确认；用户只要求评估、查看或审查时保持只读。动作会改变目标应用状态，按影响判断是否需要额外确认：超出任务范围的发布、发送、删除或真实业务提交，先说明再执行。 +后台与前台的判断先遵循 [SKILL.md](../SKILL.md) 的独立注意事项：`backgroundOnly` 仅约束 inspect/review 的取证方式，不是动作的禁止激活开关；工具不先请求焦点，不代表目标应用的导航、事件或弹窗不会激活窗口。只授权后台时，不以启动、恢复窗口或聚焦补救失败；已知会激活的动作没有前台授权就停止该步骤。 + `mode:"type"` 会向目标控件索取键盘焦点（UIA SetFocus），可能把该窗口带到前台并中断用户当前输入，因此只在用户授权前台交互时使用： - 用户只授权后台测试时固定用 `setValue`，不因为 `type` 更接近真实输入而擅自切换。