WinKit

面向 AI 代理的本地 Windows 可观测性与诊断能力，通过 Model Context 协议 (MCP) 暴露。

WinKit 是一个默认只读、本地优先的 MCP 服务器，为编码代理提供对其运行的 Windows 机器的结构化、权限化的视图：进程、网络、存储、服务、事件日志、窗口，以及——通过第一个深度应用适配器——实时的 Chrome 标签页检查以及一个 WinKit 自有的、用于诊断本地 Web 应用的隔离托管浏览器。在工具背后是一个确定性的诊断引擎，它区分了什么是测量得到的，什么是解释得到的，因此代理可以在不猜测的情况下回答真实问题。无遥测、无云端；唯一的外部出口是一个受门控、权限检查的托管浏览器启动。

v1 版本默认只读。 每个检查工具都会返回证据，且无法修改你的系统。WinKit 唯一能执行的操作——启动或关闭其自身隔离的托管 Chrome 会话——除非设置了 [chrome.managed] enabled = true，否则是禁用的；这些操作受单独的 application.browser.* 权限门控，safe/read_only 模式永远不会授予该权限，并且它们只会触碰 WinKit 自身创建的资源。

WinKit 能回答什么

WinKit 围绕三个问题构建，每个问题由一个工具回答：

它们共同在一分钟内讲述完整的故事：首先是机器，然后是单个最重的标签页，最后是它是否正在恶化。

Related MCP server: DivLens MCP

亮点

• 69 个 MCP 工具，涵盖系统、进程、网络、存储、硬件、电源、服务、事件、窗口、开发环境、应用、Chrome、托管浏览器和机器健康领域，组织成工具配置文件（core、developer [默认]、browser、full），这样代理只看到它需要的东西。

• 开发者工作流工具 — diagnose_workspace、diagnose_local_webapp、list_dev_servers、有边界的 wait_for_* 工具、correlate_recent_failures 和 system_health_trend 解决完整的问题（端口已占用、端口错误、HTTP 500、空白页面），而不是暴露原始测量值。

• 证据优先的诊断 — 每个高级报告都是一个稳定的信封，包含排序的发现、稳定的发现/证据 ID，以及 confirmed/observed/likely/possible/unknown 的置信度语言，从不基于时间临近性声称因果关系。纯阈值逻辑：无 LLM、无随机性、无捏造声明。

• 诚实的完整性 — system_diagnose 在某个维度无法测量时报告 evidence_completeness: "full" | "limited"，并且失败的维度会从健康集中排除。WinKit 会告诉你它没能看到什么。

• 通过 CDP 进行 Chrome 深度检查 — 标签页、性能、内存、网络、运行时控制台、组合诊断报告以及取样趋势。不会捕获标头、Cookie 和请求体。

• 隔离的托管浏览器 — chrome_start_managed_session 启动一个 WinKit 自有的 Chrome，带有一次性配置文件和仅回环的 DevTools 端点，检查页面（chrome_get_page_summary、chrome_capture_screenshot），而 chrome_stop_managed_session 关闭它并移除配置文件。仅限 Windows x64；不会下载 Chrome。默认有头：桌面上会打开一个真实的可见 Chrome 窗口（无 --headless 标志，无仅无头的 GPU 变通方案，窗口大小 1280x900）。如果默认的有头启动在启动时崩溃（GPU 进程故障），则会使用一个经过验证的有头软件渲染回退（headed-software）打开相同的可见窗口——它永远不会变为隐藏或无头。无头模式是可选加入的（headless: true），设计上不会打开任何窗口；它在软件路径上使用安全固定参数进行渲染（headless-software：--disable-gpu --disable-gpu-compositing --use-angle=swiftshader --disable-gpu-program-cache --disable-gpu-shader-disk-cache；如果软件模式在启动时崩溃，还会运行一个进程内 GPU 回退）。选择的模式总是会被报告（headless、window_mode、launch_mode），并且不会静默更改。会话仅在浏览器通过短暂的静止检查后被声明为 ready——DevTools 可能在 Chrome 死亡前片刻变得可访问（例如 GPU 进程崩溃），因此 ready 不会仅仅因为 /json/version 回应了一次就返回。浏览器的 stdout 会被重定向，因此它永远不会污染 MCP 流；其 stderr 会被捕获到有边界的、经过编辑的尾部以便诊断（包括 Chrome 报告时的 GPU 进程退出码），意外的退出会回收拥有的进程树（crashpad/GPU/工具/渲染器，通过确切拥有的配置文件路径识别）并移除拥有的配置文件——永远不会触及用户的 Chrome。功能门控、权限门控、无 Playwright、无手动调试标志。

• 分层权限模型 — 四种模式（safe、read_only、approval、unrestricted）覆盖 14 个 v1 读取能力以及单独门控的 application.browser.launch/navigate/close 操作能力。拒绝时会精确解释需要什么。

• 提供者架构 — 所有内容都位于 WindowsBackend / ApplicationProvider 特性之后；真实的 Win32 层是完全可分离的，并且模拟后端加上确定性夹具支持一个 381 测试的测试套件（cargo test --features mocks），无需机器依赖。

• 构建时加固 — 有边界的结果、每个工具的超时、有效载荷上限、8 MiB 传输帧上限、严格的 JSON 模式验证，以及保持 stdout 协议清洁（所有诊断信息都发往 stderr）。

• npm 分发 — 两个包：@winkit/mcp（启动器）和 @winkit/win32-x64-msvc（Windows x64 原生运行时），使用 npx --yes @winkit/mcp@latest 安装。无安装脚本、无浏览器自动化依赖；原生可执行文件是一个实现细节。

• 代理技能 — skills/winkit-developer-debugging/SKILL.md 教导编码代理从问题到工具的路由、权限和配置文件选择，以及安全/只读边界。

• 评估套件 — tests/eval/ 是一个基于夹具的、确定性的 18 场景套件，它断言状态、证据、发现 ID、支持/反驳证据、编辑、有边界输出、权限行为，以及对于 WinKit 旨在诊断的故障模式没有错误的根本原因声明。

快速开始

要求：Windows 10/11 x64 和 Node.js >= 18（npm 路径）或 Rust 1.75+（从源码构建）。

npx --yes @winkit/mcp@latest doctor   # verify the install

或者从源码构建：

cargo build --release
.\target\release\winkit --help

WinKit 由 MCP 客户端作为 stdio 子进程启动，可以通过 npx 启动器，或者直接从构建的二进制文件启动（参见 docs/mcp-integration.md）：

• OpenCode — examples/mcp/opencode.json

• Claude Code — examples/mcp/claude-code.json

• 任意 MCP 客户端 — examples/mcp/generic.json

没有配置文件时，WinKit 以安全默认值运行：read_only 权限模式、两个内置提供者启用、以及文档化的限制。请参阅 config/example.toml 了解完整表面，以及 docs/installation.md 了解完整的设置故事。

Chrome 检查与托管浏览器

Chrome 深度检查需要 Chrome 暴露其 DevTools 端点。WinKit 可以为你做到这一点：使用 [chrome.managed] enabled = true 和 application.browser.launch 权限，chrome_start_managed_session 会生成其自身的隔离 Chrome 实例（一次性配置文件、仅回环的 DevTools 端点），因此无需手动调试标志或单独的浏览器进程。默认情况下，桌面上会打开一个真实的可见 Chrome 窗口；仅在需要非可见的自动化/CI 会话时传递 headless: true（该模式设计上不打开任何窗口）：

chrome_start_managed_session(url="http://localhost:3000")  # opens a visible Chrome window
  -> chrome_get_page_summary(session_id)     # runtime errors, failed requests, headings
  -> chrome_capture_screenshot(session_id)   # optional visual check
  -> chrome_stop_managed_session(session_id) # closes Chrome, removes the profile

要检查一个已经在运行的 Chrome（例如开发者使用 --remote-debugging-port 启动的那个），WinKit 通过探测 fallback_port（默认 9222）并建立 CDP 连接来发现端点。请参阅 docs/chrome.md 了解完整的生命周期、状态和安全规则。

性能

端到端中位延迟，在 Windows 10 桌面（8 核、16 GB RAM）上使用发布构建和每次调用一个全新服务器进程进行测量——因此数字包括进程启动和 MCP 初始化握手：

观察窗口工具会随其配置的窗口缩放，而不是系统大小；每个其他工具无论存在多少进程、端口或标签页，都保持 100 毫秒以下。完整表格和方法：docs/performance.md。

工具表面

包含参数模式的完整参考：docs/tools.md。

架构

WinKit 的管道采用三层分离职责——WinKit 测量，WinKit 解释信号，WinKit 对基于证据的发现进行排序；LLM 负责解释它们：

                 WinKit
                   │
      ┌────────────┼────────────┐
      │            │            │
  Observation  Correlation  Diagnosis
      │            │            │
      ↓            ↓            ↓
  Windows/App   Evidence    Findings
    metrics      linking     ranking

server (MCP over stdio, JSON-RPC 2.0, session lifecycle)
  ├── tools        (59 tool definitions + argument handling + registry)
  │     ├── providers (WindowsBackend / ApplicationProvider traits)
  │     │     └── chrome::managed (isolated WinKit-owned sessions)
  │     └── platform::windows (real Win32 implementations, windows-sys 0.59)
  ├── permissions  (modes, capabilities, policy, approval surface)
  ├── config       (winkit.toml, strict, deny-unknown-keys)
  ├── models       (unified data models shared by providers/tools/diagnostics)
  └── diagnostics  (measurements → signals → ranked findings)

分层规则严格：MCP 表面层从不直接接触 Win32，Windows 层可通过模拟后端进行测试（cargo test --features mocks）。深入了解：docs/architecture.md。

安全模型

• 默认只读——每个检查工具都是只读的；唯一操作（托管浏览器的启动/导航/关闭）通过 [chrome.managed] enabled 进行特性门控，并在 safe/read_only 模式下被拒绝。

• 权限模式在每个工具调用前进行门控，并为托管浏览器生命周期工具设置单独的操作门控。

• 托管浏览器隔离且自清洁——在托管根目录下使用一次性配置文件，仅回环 DevTools，清理时拒绝任何托管根目录外的路径，且从不附加到普通 Chrome 配置文件。

• 不捕获任何秘密——Chrome 网络/运行时检查会截断输出并明确排除标头、Cookie 和主体；URL 会进行脱敏处理（查询字符串被剥离）。

• 处处有界工作——结果上限、超时、负载上限、帧上限。

• 完整详情：SECURITY.md 和 docs/security.md。

已知限制

WinKit 将限制视为一等输出，而非缺陷：

• 每个进程的 CPU 百分比是实时采样值，而非累积度量。 在多核机器上，简单的系统比率计算会产生误导，因此 list_processes（一个廉价的完整快照）报告 cpu_percent: null。要发现失控进程，get_process 会在 300 毫秒窗口内对两个实时采样的 CPU 百分比进行采样，并带有显式基准（system_capacity_all_cores）；聚合视图（ApplicationGroupInfo）使用 1 秒采样执行相同操作。

• Chrome 并不总能将标签页映射到 PID——适配器报告 process_mapping: "none" 并仅凭纯 CDP 证据继续运行，而不是失败或猜测。

• 某些 Windows 进程拒绝读取访问——它们仍会被列出，对于无法读取的字段显示 null，而不会被静默丢弃。

• 诊断区分已测量和未测量——system_diagnose 带有 evidence_completeness，报告可以包含 limitations 条目，以便代理不会过度解读部分视图。

• 检查已经运行的 Chrome 需要远程调试端口。 托管浏览器工作流程消除了本地应用诊断的这个要求：当功能与权限启用时，WinKit 会启动其自己的隔离 Chrome；普通浏览配置文件始终不受影响。

开发

cargo check                 # compile checks
cargo build                 # debug build
cargo test --features mocks # full test suite (381 tests)
cargo clippy --all-targets  # lint

# evaluation suite (fixture-backed failure scenarios)
cargo test --features mocks --test eval

# npm launcher + package validation (after cargo build --release)
powershell -ExecutionPolicy Bypass -File npm/scripts/copy-native.ps1
node --test npm/test/launcher.test.js npm/test/package.test.js
powershell -ExecutionPolicy Bypass -File npm/scripts/test-packed.ps1

# opt-in live tests (need a real Windows machine / Chrome install)
$env:WINKIT_LIVE_WINDOWS = "1"; cargo test --features live-windows
# live managed-Chrome lifecycle, both modes (requires an installed Google
# Chrome on an interactive desktop; run ten consecutive isolated runs per
# mode before any release-ready claim)
$env:WINKIT_LIVE_CHROME = "1"; cargo test --features live-chrome --lib live_managed_chrome_headed_start_inspect_stop -- --nocapture
$env:WINKIT_LIVE_CHROME = "1"; cargo test --features live-chrome --lib live_managed_chrome_headless_start_inspect_stop -- --nocapture

当 WINKIT_LIVE_CHROME 不为 1 时，实时的托管 Chrome 测试会打印明确的跳过原因；当没有交互式桌面时，有头测试也会跳过（将有头行为标记为未验证）。跳过的实时测试绝非通过，如果两种模式没有在真实的 Chrome 安装上通过，该项目就不算“发布就绪”（参见 docs/release.md）。

集成测试在不接触真实机器的情况下，测试了 MCP 协议、工具调度、权限执行以及基于测试夹具的模拟提供程序；评估套件（tests/eval/）涵盖了 18 个确定性故障场景。请参阅 docs/development.md 和 CONTRIBUTING.md。

文档

• docs/installation.md — 构建、配置、连接到 MCP 客户端

• docs/architecture.md — 分层、数据流、提供程序模型

• docs/diagnostics.md — 证据优先的报告格式和评分公式

• docs/security.md — 威胁模型与缓解措施

• docs/permissions.md — 模式、能力、策略表

• docs/tools.md — 带有参数的工具参考

• docs/configuration.md — 每个配置键与默认值

• docs/application-adapters.md — 适配器如何接入

• docs/chrome.md — Chrome 发现、CDP、托管会话与注意事项

• docs/performance.md — 基准测试方法与完整表格

• docs/demos.md — 三个演示脚本与录制指南

• docs/mcp-integration.md — 客户端配置示例

• docs/development.md — 构建、测试、贡献

• docs/release.md — 发布流程与检查清单

• tests/eval/README.md — 如何运行评估套件

• skills/winkit-developer-debugging/SKILL.md — 代理技能

许可

MIT — 参见 LICENSE。WinKit 是本地优先且开源的项目；它不包含任何遥测机制，除了回环 Chrome DevTools 探测外，不发出任何网络调用。