首页
看点啥
插画图片
首页 科技看点 WinCode：AI Agent 工具实践指南

WinCode：AI Agent 工具实践指南

2026-10-04 0

在项目中评估WinCode，可以先看清用途边界：面向 Unity 开发的 AI 工具，把本地工作流、CLI、代码索引、视觉验证、输入模拟和播放器调试整合在一起。团队若要把它用于界面与前端开发，应先处理视觉还原、交互状态和响应式细节容易遗漏，否则试用结果很容易失真。先选一个包含多状态的真实组件完成实现更稳妥；过程中要观察尺寸、状态、可访问性、资源和不同视口表现，失败也应能解释原因。整体来看，它适合愿意逐状态验收界面质量的前端团队拿来做对照测试，最终决定仍应回到真实结果和维护状态。

linnnn89/WinCode 项目截图 1

WinCode

Background UI 适用于 Windows 和 .NET 的检查和代码智能 — 支持纯文本 LLMs.

面向 Windows 与 .NET 的后台 UI 检查和代码分析工具，支持纯文本大语言模型。

Setup / 配置指南 · Code / 代码分析 · UI inspection / UI 检查 · Changelog / 版本记录

英语

WinCode 是为 AI 编码代理实现模型上下文协议 (MCP) 的本地服务器。它结合了 Windows UI 自动化 (UIA)、代码导航和 .NET 项目分析，因此代理可以通过同一连接检查正在运行的应用程序并调查其源代码。

特点

通过查询特定控件而不是返回完整的树，使用 222 节点窗口记录的测试将响应文本从大约 62 KB 减少到 1.6 KB。请参阅 测试记录。

Example: Investigate a disabled Save button

Find the application's window, check whether the Save button is enabled without bringing the window to the foreground, and locate the relevant XAML and C# code.

The agent can complete this investigation using text output:

  1. 使用processName或titleContains调用wincode_ui_list_windows，获取目标进程ID（pid）和窗口句柄（hwnd）。
  2. 使用目标控件和相关源文件调用wincode_ui_review。如果这些文件尚不清楚，请先使用代码导航工具找到它们。
{
  "pid": 12345,
  "hwnd": "0x123456",
  "backgroundOnly": true,
  "capture": "none",
  "responseFormat": "compact",
  "query": { "automationId": "SaveButton", "controlType": "Button" },
  "maxDepth": 3,
  "maxNodes": 30,
  "candidateFiles": ["Views/MainWindow.xaml"],
  "candidateCodeFiles": ["ViewModels/MainWindowViewModel.cs"]
}
  1. 读取返回的控件属性和候选源。例如，isEnabled: false 报告该控件已禁用。按照返回的 nextRequest 参数和 wincode_prepare_context 来检查候选声明或分配。
  2. 在解释行为之前检查来源。匹配的绑定或命令名称标识要调查的代码；它本身并不能确定活动的 DataContext 或按钮被禁用的原因。

上面的 IDs 和路径是占位符。使用实际窗口和工作区中的值。当仅需要控制树时，请使用 wincode_ui_inspect 而不带源文件参数。添加 readStates: true 用于切换、选择或 expand/collapse 状态；当编号屏幕截图有助于目视查看时，请使用 capture: "annotated"。

快速启动

要求： Windows x64、Git 2.36 或更高版本、Node.js >=22（24 个主要、22 个兼容）和 .NET SDK 10.0.303。 SDK 版本固定在 global.json 中，并禁用前滚。已发布的 UI 帮助程序和可选托盘需要 .NET 10 Windows 桌面运行时。 Windows 11 x64 是开发和测试基准。

1.构建并验证 WinCode

git clone https://github.com/linnnn89/WinCode.git
cd WinCode
npm ci
npm run check
npm run delivery:verify

运行 npm run check 构建网关和本机组件，运行核心回归和 stdio 集成测试，并验证交付清单。桌面测试可单独进行。

2.配置 MCP 连接

对于具有持久终端支持的 Codex，技能按需模式 仅在需要时启动 WinCode，并在整个任务中重复使用一个连接。安装技能，禁用本机 WinCode MCP 条目，并在使用此模式之前刷新客户端连接。该技能在交互式执行会话中启动 dist/Client/SkillSessionCli.js；结果仍以完整的 JSON 和图像文件形式提供。每个结果都需要读取额外的文件。其他客户端可以使用下面的本机 stdio 配置。

对于支持 mcpServers 的客户端，添加以下 stdio 配置。建议显式设置 --workspace：

{
  "mcpServers": {
    "wincode": {
      "command": "node",
      "args": ["C:/path/to/WinCode/dist/index.js", "--workspace", "C:/path/to/project"]
    }
  }
}

将这两个路径替换为现有的绝对路径。 WinCode安装目录和您的项目目录可能不同。确保 node 在 PATH 中可用，或使用其绝对可执行路径。

对于图形配置界面，请使用类型 stdio、命令 node 和三个单独的参数条目：dist/index.js 路径、--workspace 和项目路径。即使路径包含空格，也不要将引号添加到各个参数条目中。默认配置不需要额外的环境变量。

3.验证连接并尝试查询

连接后，请代理拨打wincode_hello_world，确认health.workspaceBinding.root与您的项目匹配。然后尝试：

总结一下这个项目的结构，列出src的内容，并找到负责保存数据的代码。

代理可以使用 workspace_open 获取项目摘要，使用 wincode_list_directory 浏览目录，使用 wincode_search_text 定位代码。对于 UI 检查，请在交互式 Windows 桌面会话中启动目标应用程序并使用上面的示例。

每个连接在其生命周期内都绑定到一个工作区。 workspace_open 确认或恢复该工作空间；它不会切换项目。不同的根返回 WORKSPACE_MISMATCH。对另一个项目使用单独配置的连接。如果省略 --workspace，则连接绑定到服务器的启动目录。

有关客户端配置和可选代理技能，请参阅 技能和 MCP 设置指南。重建后，重新连接客户端的 MCP 服务器以加载更新的流程和工具架构。

通用工作流程和工具

代码导航： 从已知的目录、文件或符号开始。 wincode_search_text 使用纯字符串而不是正则表达式在 scopePaths 中进行搜索； wincode_file_outline 返回文件的声明和行数。两者都提供了使用 wincode_prepare_context 读取源代码的后续参数。

{
  "task": "Review the save logic",
  "lineRanges": [{ "file": "src/Service.cs", "startLine": 50, "endLine": 80 }],
  "maxTokens": 2000
}

使用搜索结果中的实际路径和行号。 lineRanges 选择已知线路； scopeFiles 限制读取已知文件。 candidateFiles 在发现期间优先考虑文件，并且不是排他范围。在决定是否需要更多代码之前，检查返回的范围、coverage 和截断。 maxTokens 是基于 UTF-16 字符计数的估计值，而不是特定于模型的标记计数。

UI 检查： 选择一个窗口，查询相关控件或子树，并在需要时请求源候选。 responseFormat: "compact" 保留控制 IDs、名称、层次结构和状态，同时省略每个节点的几何形状和类名称。当需要坐标或其他详细信息时，请使用 full。不支持或未知的控制状态与 false 不同。

C# 语义分析： 显式启用 Roslyn，搜索符号，并将其返回的 location 不变地作为 symbolLocation 传递给引用、影响或重构工具。当工具报告过时的位置时再次搜索。默认的 local-text 提供程序提供基于文本的导航并报告其语义限制。

工具 目的
workspace_open 确认或恢复固定工作空间并返回紧凑的项目摘要。
wincode_list_directory 浏览具有深度、条目计数和输出限制的目录。
wincode_analyze_workspace 阅读解决方案结构和声明的项目参考。
wincode_search_text 在选定的文件或目录中查找文字。
wincode_file_outline 读取文件的本地声明并观察行数。
wincode_prepare_context 阅读选定的源代码摘录，其中包含路径、行范围和覆盖范围信息。
wincode_find_code_symbol 使用配置的提供程序搜索符号。
wincode_find_references 查找参考文献并报告已知总数、返回计数和截断。
analyze_change_impact 评估潜在的变更影响并在证据不完整时报告不确定性。
wincode_plan_refactoring 为拟议的重构提出检查和验证步骤建议。
wincode_safe_move_to_trash 将经过验证的工作区文件移至 trash/ 并记录实际已完成或部分结果。
wincode_ui_list_windows 列出带有进程和标题过滤器的可见顶级窗口。
wincode_ui_inspect 阅读控件和可选状态或屏幕截图。
wincode_ui_click 通过 UI 自动化模式单击一个唯一匹配的控件。
wincode_ui_type 在一个唯一匹配的控件中键入文本或设置其值。
wincode_ui_review 检查 UI 并返回候选 XAML/C# 源位置。
wincode_hello_world 读取实例标识、工作区绑定、功能和已知状态。
wincode_diagnose_project 主动检查SDKs、Git和本地环境。

wincode_analyze_change_impact 是 analyze_change_impact 的别名。详细参数及工作流程：代码分析、UI检查、诊断。要检查正在运行的连接中的工具架构，请将其名称 toolName 传递到 wincode_hello_world。

可选配置

范围和限制

开发和文档

当前源版本：0.16.0。有关版本历史记录和迁移说明，请参阅 CHANGELOG。 Windows 11 x64 是参考平台；到其他操作系统的端口需要调整和单独验证。

npm run check            # Builds, core regression, stdio integration and delivery verification
npm run check:desktop    # WPF and UI-to-source tests; requires an interactive Windows desktop
npm run delivery:verify  # Verify Gateway, native components and managed Skill artifacts
npm run test:inventory   # Verify automated-test suite registration
npm run benchmark:agent -- 1  # Run one iteration of the optional scripted benchmark

CI 在 Windows 上运行，带有 Node.js 22 和 24 以及固定的 .NET SDK。 Node.js 22 作业包括额外的本机和集成检查；桌面测试单独运行。基准报告衡量脚本化场景，包括调用、响应大小和执行时间。请参阅链接记录了解测试条件和结果。

简体中文

WinCode 是面向AI 编程智能体的本地模型上下文协议（Model Context Protocol，MCP）服务器，集成Windows UI Automation（UIA）、代码导航和.NET项目分析功能。智能体源码可以通过相同的连接检查正在运行的应用，并查找相关。

核心功能

在包含 222 个节点的窗口测试中，仅查询指定控件即可将返回文本量从约 62 KB 减少至 1.6 KB。详见 测试记录。

使用示例：排查“保存”按钮被禁用的问题

查找应用窗口，在不切换前台窗口的情况下检查“保存”按钮是否启用，并定位相关XAML和C#代码。

智能体可以通过纯文本输出完成以下排查流程：

  1. 调用 wincode_ui_list_windows，通过 processName 或 titleContains 获取目标进程 ID（pid）和窗口句柄（hwnd）。
  2. 调用 wincode_ui_review，指定目标控件和相关源码文件。如果尚不知道文件位置，先使用代码导航工具定位。
{
  "pid": 12345,
  "hwnd": "0x123456",
  "backgroundOnly": true,
  "capture": "none",
  "responseFormat": "compact",
  "query": { "automationId": "SaveButton", "controlType": "Button" },
  "maxDepth": 3,
  "maxNodes": 30,
  "candidateFiles": ["Views/MainWindow.xaml"],
  "candidateCodeFiles": ["ViewModels/MainWindowViewModel.cs"]
}
  1. 查看返回的控件属性和源码候选位置。例如，isEnabled: false 表示控件处于禁用状态。根据返回的 nextRequest 参数调用 wincode_prepare_context，读取候选声明或赋值语句。
  2. 核查源码后再解释界面行为。匹配到绑定或命令名称，可以确定下一步需要检查的代码，但仅凭名称匹配无法确定当前 DataContext 或按钮被禁用的原因。

上述 ID 和路径均为示例，使用时应替换为实际窗口和工作区中的值。如果只需读取控件树，可使用 wincode_ui_inspect，无需传入源码文件参数。需要勾选、选中或展开/折叠状态时，添加 readStates: true；需要结合编号截图检查视觉效果时，使用 capture: "annotated"。

快速开始

环境要求：Windows x64、Git 2.36及以上、Node.js >=22（推荐24，兼容22），以及.NET SDK 10.0.303。SDK 版本已在global.json中锁定，并通过rollForward: "disable"要求使用完全匹配的版本。发布UI辅助程序和任选托盘程序均依赖。NET 10 Windows桌面运行时。开发和测试的基准平台为Windows 11 x64。

1. 构建并验证 WinCode

git clone https://github.com/linnnn89/WinCode.git
cd WinCode
npm ci
npm run check
npm run delivery:verify

运行 npm run check 会构建网关和组件分离，执行核心回归测试与 stdio 集成测试，并验证交付清单。桌面测试单独执行。

2. 配置 MCP 连接

持久终端的 Codex 可使用 Skill 后续模式：第一次需要时才启动 WinCode 任务，内复用同义。先安装 Skill、禁用连接 WinCode MCP 支持连接，并刷新客户端连接。Skill 执行会话启动dist/Client/SkillSessionCli.js，完整结果保存为 JSON 和图片文件，每次结果需要额外读取文件。其他客户端可使用以下括号 stdio 配置。

对于支持 mcpServers 的客户端，添加以下 stdio 配置。建议显式设置 --workspace：

{
  "mcpServers": {
    "wincode": {
      "command": "node",
      "args": ["C:/path/to/WinCode/dist/index.js", "--workspace", "C:/path/to/project"]
    }
  }
}

将两个路径替换为实际存在的绝对路径。WinCode 安装目录与目标项目目录可以不同。确保 node 位于 PATH 中，或将命令改为其可执行文件的绝对路径。

使用图形化配置界面时，类型选择 stdio，命令填写 node，依次添加三个独立参数：dist/index.js 的路径、--workspace、目标项目路径。即使路径包含空格，也不要为独立参数额外添加引号。默认配置不需要额外环境变量。

3. 验证连接并执行首次查询

连接后，让智能体调用 wincode_hello_world，确认 health.workspaceBinding.root 与目标项目一致，然后尝试：

概述项目结构，列出 src 目录中的内容，并查找负责保存数据的代码。

智能体可以使用 workspace_open 获取项目摘要，使用 wincode_list_directory 浏览目录，再通过 wincode_search_text 定位代码。检查 UI 时，先在占用 Windows 桌面会话中启动目标应用，再参考前面的使用示例。

每条连接在其生命周期内固定对应一个工作区。workspace_open 用于确认或恢复该工作区，不能切换项目；请求其他根目录会返回 WORKSPACE_MISMATCH。访问其他项目时，应使用单独配置的连接。如果省略 --workspace，连接将固定到服务器的启动目录。

客户端配置和可选的智能体技能安装方式参见技能与MCP配置指南定义。重新构建后，需要重新连接客户端中的MCP服务器，才能加载更新后的进程和工具参数。

常用工作流与工具

代码导航：从已知目录、文件或符号开始。通过 wincode_search_text 在 scopePaths 指定的范围内按普通字符串搜索，不使用正则表达式；通过 wincode_file_outline 查看文件中的声明和行数。两者均提供后续调用 wincode_prepare_context 读取源码所需的参数。

{
  "task": "核查保存逻辑",
  "lineRanges": [{ "file": "src/Service.cs", "startLine": 50, "endLine": 80 }],
  "maxTokens": 2000
}

使用搜索结果中的实际路径和行号。通过 lineRanges 指定要读取的行号范围，通过 scopeFiles 将读取范围限制在指定文件内。candidateFiles 仅用于优先搜索候选文件，不排除其他文件。根据返回的行号、coverage和截断信息判断是否需要继续读取。maxTokens 设置的是按 UTF-16 字符数指示的令牌准备，并不是具体模型的精确令牌数。

UI 检查：选择窗口，查询相关控件或子树，必要时查找源码候选位置。设置 responseFormat: "compact" 后，响应中会保留控件 ID、名称、层级和状态，省略各节点的几何信息和类名；需要坐标或更多细节时使用 full。结果中会明确区分不支持读取、未知和 false 等状态。

C#语义分析：显式启用Roslyn后，先搜索符号，再将返回的完整location作为symbolLocation传给引用、变更影响或已更新工具。工具位置过渡时，应重新搜索。默认的local-text提供基于文本的代码导航，并说明其语义分析限制。

工具 用途
workspace_open 确认或恢复固定工作区，返回精简的项目摘要。
wincode_list_directory 浏览指定目录，支持深度、条目数和输出限制。
wincode_analyze_workspace 读取解决方案结构及声明的项目引用。
wincode_search_text 在指定文件或目录中按普通字符串搜索。
wincode_file_outline 通过本地文本分析提取文件中的声明，并返回实际行数。
wincode_prepare_context 读取指定源码片段，提供路径、行号范围和覆盖情况。
wincode_find_code_symbol 使用已配置的分析后端搜索符号。
wincode_find_references 查找引用，报告已知总数、返回数量和截断情况。
analyze_change_impact 评估潜在变更影响，并在信息不完整时报告不确定性。
wincode_plan_refactoring 为拟议的重构提供检查和验证建议。
wincode_safe_move_to_trash 将通过路径校验的工作区文件移至 trash/，记录实际完成或部分完成的结果。
wincode_ui_list_windows 列出可见顶层窗口，支持按进程和标题筛选。
wincode_ui_inspect 读取控件信息，以及可选的状态或截图。
wincode_ui_click 通过UI Automation模式唯一点击命中的控件。
wincode_ui_type 向唯一命中的控件输入文本，或直接写入其值。
wincode_ui_review 检查 UI 并返回 XAML/C# 源码候选位置。
wincode_hello_world 读取实例身份、工作区绑定、能力及已知状态。
wincode_diagnose_project 检查活动 SDK、Git 和本地环境。

wincode_analyze_change_impact 是 analyze_change_impact 的别名。详细参数与工作流见 代码分析手册、UI 检查手册 和 诊断手册。如需查看当前连接中某个工具的参数定义，可将工具名作为 toolName 传给 wincode_hello_world。

可选配置

适用范围与限制

开发与文档

当前源码版本为 0.16.0。版本历史和迁移说明见 CHANGELOG。项目以 Windows 11 x64 为基准平台，移植至其他操作系统需要适配并单独验证。

npm run check            # 构建、核心回归、stdio 集成和交付校验
npm run check:desktop    # WPF 与 UI 源码关联测试，需要交互式 Windows 桌面
npm run delivery:verify  # 校验 Gateway、原生组件和交付清单中的 Skill 文件
npm run test:inventory   # 核对自动化测试的套件注册情况
npm run benchmark:agent -- 1  # 执行一轮可选的脚本化基准测试

CI 在 Windows 环境中使用 Node.js 22、24 和固定版本的 .NET SDK 运行。在 Node.js 22 的任务中，还会额外执行原生组件与集成检查；桌面测试单独运行。基准报告记录脚本化场景中的调用次数、响应大小和执行时间，具体测试条件及结果见以下文档。

喜欢(0)

上一篇

oh-my-fable：AI Agent 工具实践指南

oh-my-fable：AI Agent 工具实践指南

下一篇

SpecVibe：AI Agent 工具实践指南

SpecVibe：AI Agent 工具实践指南
猜你喜欢

Copyright © 2022 漫资讯 · Powered By WordPress