From 917b77f6a6812f615961358b207adf8a7c110dc8 Mon Sep 17 00:00:00 2001 From: linnnn89 <216342082+linnnn89@users.noreply.github.com> Date: Fri, 11 Sep 2026 23:05:12 +0800 Subject: [PATCH] docs: clarify features and polish bilingual README --- README.md | 603 +++++++++++++++--------------------------- docs/codex_worklog.md | 8 + 2 files changed, 219 insertions(+), 392 deletions(-) diff --git a/README.md b/README.md index 5573293..7b16a98 100644 --- a/README.md +++ b/README.md @@ -1,137 +1,208 @@ # WinCode

- Read .NET projects, inspect desktop windows, and find related source code.
- 让 Coding Agent 读取 .NET 项目、检查桌面窗口，并查找相关源码。 + Background UI inspection and code intelligence for Windows and .NET—with support for text-only LLMs.
+ 面向 Windows 与 .NET 的后台 UI 检查和代码分析工具，支持纯文本大语言模型。

English · 简体中文
Windows 11 x64 MCP stdio + CI MIT license

-文档导航 / Documentation: [架构与数据流](WinCode-架构与数据流说明.md) · [后续测试计划](WinCode-下一轮工程化迭代计划书.md) · [Skill 与 MCP 配置](WinCode-Skill制作与MCP配置指南.md) · [版本记录](CHANGELOG.md) · [工作记录](docs/codex_worklog.md) +[Setup / 配置指南](WinCode-Skill制作与MCP配置指南.md) · [Code / 代码分析](skills/wincode/references/code.md) · [UI inspection / UI 检查](skills/wincode/references/ui.md) · [Changelog / 版本记录](CHANGELOG.md) ## English -WinCode is a local MCP server for Windows and .NET projects. It lets coding agents read project references, search source code, inspect controls in running applications, and capture annotated screenshots. It can also find possible XAML declarations for a control. +WinCode is a local server implementing the Model Context Protocol (MCP) for AI coding agents. It combines Windows UI Automation (UIA), code navigation and .NET project analysis, so an agent can inspect a running application and investigate its source code through the same connection. -- **Read project code:** Parse declared `.sln`/`.csproj` references, search symbols, and return code excerpts within a character-based output limit. Token counts are estimates. -- **Inspect the running app:** List visible windows, read controls or subtrees, and capture numbered screenshots without activating the target window. -- **Find related XAML:** Return matching declarations, line numbers and file hashes. Report ambiguous matches, truncated output and unavailable providers. +### Features -Current source version: **0.15.0**, merged into `main`; no GitHub Release has been published. All UI tools are read-only. See [CHANGELOG](CHANGELOG.md) for the fixed-workspace migration and version history. +- **Background UI inspection:** Read controls in a running application without activating its window or changing keyboard focus. Continue working in other applications while the agent inspects the target window. +- **Support for text-only LLMs:** Control names, hierarchy, properties and states are returned as structured JSON. Through an MCP-capable agent client, models such as DeepSeek used without image input can inspect desktop interfaces. Screenshots are optional. +- **UI inspection with source navigation:** Inspect a control, find candidate XAML declarations and related C# code, then read the relevant source lines. File paths, line numbers and content hashes make the findings traceable. +- **Faster, more accurate inspection in everyday use:** In our day-to-day Windows/.NET development, WinCode makes UI inspection and source navigation faster and more accurate than screenshot-based Computer Use workflows. Direct access to structured control properties and source locations reduces reliance on image interpretation and repeated interaction. Targeted queries and compact responses also reduce the amount of data the model needs to process. +- **Project and code analysis:** Explore declared solution and project references, search text and symbols, read selected code, and assess change impact. Built-in text analysis works by default; optional Roslyn integration provides compiler-backed C# symbol and reference analysis. -**Platform and compatibility:** Windows 11 x64 is the baseline for this project's local development and testing. Identical functionality, behavior, and performance are not guaranteed on other operating systems, other Windows versions, or different dependency versions. macOS and Linux users are encouraged to **fork this repository and adapt and validate it locally** for their platform. Use the dependency versions documented and pinned in this repository as the reference environment. +A recorded test with a 222-node window reduced response text from approximately **62 KB to 1.6 KB** by querying a specific control instead of returning the full tree. See the [test record](docs/codex_worklog.md). + +### 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. Call `wincode_ui_list_windows` with `processName` or `titleContains` to obtain the target process ID (`pid`) and window handle (`hwnd`). +2. Call `wincode_ui_review` with the target control and relevant source files. If those files are not yet known, locate them with the code navigation tools first. + +```json +{ + "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"] +} +``` + +3. Read the returned control properties and source candidates. For example, `isEnabled: false` reports that the control is disabled. Follow the returned `nextRequest` arguments with `wincode_prepare_context` to inspect the candidate declaration or assignment. +4. Check the source before explaining the behavior. A matching binding or command name identifies code to investigate; it does not by itself establish the active `DataContext` or the reason the button is disabled. + +The IDs and paths above are placeholders. Use values from the actual window and workspace. When only the control tree is needed, use `wincode_ui_inspect` without the source-file arguments. Add `readStates: true` for toggle, selection or expand/collapse states; use `capture: "annotated"` when a numbered screenshot is useful for visual review. ### Quick start -**Requirements:** Git, Windows x64 and Node.js `>=22` (24 primary, 22 compatible). Building requires .NET SDK 10.0.303, pinned without roll-forward in `global.json`; the published UI helper needs the .NET 10 Windows Desktop runtime. See [CONTRIBUTING](CONTRIBUTING.md) for locked builds and delivery verification. +**Requirements:** Windows x64, Git 2.36 or later, Node.js `>=22` (24 primary, 22 compatible), and .NET SDK **10.0.303**. The SDK version is pinned in `global.json` with roll-forward disabled. The published UI helper and optional Tray require the .NET 10 Windows Desktop runtime. Windows 11 x64 is the development and test baseline. + +**1. Build and verify WinCode** ```powershell git clone https://github.com/linnnn89/WinCode.git cd WinCode npm ci npm run check - -# Verify the complete Gateway / Release Host / Skill delivery npm run delivery:verify ``` -Add WinCode as a stdio MCP server in your agent client configuration (for clients that support `mcpServers`). Each connection binds one project at startup; an explicit absolute `--workspace` is recommended. +Running `npm run check` builds the Gateway and native components, runs core regression and stdio integration tests, and verifies the delivery manifest. Desktop tests are available separately. -**Bind the launch directory:** Use this only when the client reliably starts the server in the intended project: +**2. Configure the MCP connection** + +For clients that support `mcpServers`, add the following stdio configuration. Explicitly setting `--workspace` is recommended: ```json { "mcpServers": { "wincode": { "command": "node", - "args": ["C:/path/to/WinCode/dist/index.js"] + "args": ["C:/path/to/WinCode/dist/index.js", "--workspace", "C:/path/to/project"] } } } ``` -Without `--workspace`, WinCode binds the launch directory for the lifetime of that connection. `health.workspaceBinding` reports the fixed root and its source. `workspace_open` confirms or recovers that root; a different root returns `WORKSPACE_MISMATCH` before draining requests or changing resources. Select a connection configured for the other project. Project-scoped configurations may reuse a server name; multiple instances in one shared configuration need distinct names. Healthy same-root confirmation preserves the Host/snapshot and does not drain active queries; known recovery failures still follow the explicit recovery path. +Replace both paths with existing absolute paths. The WinCode installation directory and your project directory may be different. Ensure `node` is available in `PATH`, or use its absolute executable path. + +For a graphical configuration interface, use type `stdio`, command `node`, and three separate argument entries: the `dist/index.js` path, `--workspace`, and the project path. Do not add surrounding quotes to individual argument entries, even when a path contains spaces. No additional environment variables are required for the default configuration. + +**3. Verify the connection and try a query** + +After connecting, ask the agent to call `wincode_hello_world` and confirm that `health.workspaceBinding.root` matches your project. Then try: -Each Roslyn Host writes design-time intermediate files to its own directory while preserving the project's restore location, Compile exclusions and original import hook. Node 22 CI covers concurrent cold startup of three independent MCP processes (projects A/B/A), reference lookup and cleanup of each Host's output. This includes a regression test for the reproduced concurrent writes to shared `obj` files. +> Summarize this project's structure, list the contents of `src`, and locate the code responsible for saving data. -Each instance accepts up to **32 unfinished tool requests**, including queued requests. Passive hello and `tools/list` share a separate limit of **4 requests**. Raw arguments are limited to **64 KiB of UTF-8 JSON**. Queueing counts toward the request timeout; overload returns `SERVER_BUSY`. A cancelled request still counts toward the limit until its operation finishes cleanup. Shared-cache reads check the selected source content and cached attachments, and rebuild missing or corrupted entries. +The agent can use `workspace_open` to obtain the project summary, `wincode_list_directory` to browse a directory, and `wincode_search_text` to locate code. For UI inspection, start the target application in your interactive Windows desktop session and use the example above. -**Verified baseline on 2026-09-11:** Navigation and compact UI results ([PR #40](https://github.com/linnnn89/WinCode/pull/40)), followed by the worktree `.git` filter and Tray test scheduling correction ([PR #41](https://github.com/linnnn89/WinCode/pull/41)), are merged. The resulting `main` commit `631f8ba` passed [Node 22/24 CI](https://github.com/linnnn89/WinCode/actions/runs/34586761303) and all three [CodeQL checks](https://github.com/linnnn89/WinCode/actions/runs/34586761201). Node 22 recorded 453 core tests passed, zero failed and one optional TavernDesk test skipped; Roslyn Host 59/59, Gateway 22/22, shared-cache 8/8, SDK concurrency 10/10 and design-time isolation 21/21 passed. Node 22 runs additional acceptance stages, so its total job duration is not a Node 22/24 performance comparison. +Each connection is bound to one workspace for its lifetime. `workspace_open` confirms or recovers that workspace; it does not switch projects. A different root returns `WORKSPACE_MISMATCH`. Use a separately configured connection for another project. If `--workspace` is omitted, the connection binds to the server's launch directory. -The opt-in TavernDesk scripts bind the requested repository at startup and keep cache/trash in a separate temporary directory. The eight real-project context scenarios and six UI product tasks passed locally. The dedicated application initially failed with `UnauthorizedAccessException`; a build from current, unchanged source started successfully. The original startup failure remains unexplained. +See the [Skill and MCP setup guide](WinCode-Skill制作与MCP配置指南.md) for client configuration and the optional agent Skill. After rebuilding, reconnect the client's MCP server to load the updated process and tool schemas. -Local acceptance also covered two independent Gateway processes inspecting the same and different windows: overlapping access returned `AUDIT_BUSY`, subsequent access recovered, and window identity, screenshots and helper cleanup were checked. The actual Codex connection completed Roslyn search, references, impact and refactoring guidance on an isolated TavernDesk.Core copy; after a source edit, old locations were rejected and a new search restored reference queries. This covers one project/configuration and excludes eight analyzer/generator references; it does not establish complete application coverage. Extended resource use and unresolved UI issues remain in the [test plan](WinCode-下一轮工程化迭代计划书.md); results and failures are in the [work log](docs/codex_worklog.md). +### Common workflows and tools -**Specify a project at startup (recommended):** Add `--workspace` followed by the existing project directory's absolute path: +**Code navigation:** Start with a known directory, file or symbol. `wincode_search_text` searches within `scopePaths` using plain strings rather than regular expressions; `wincode_file_outline` returns a file's declarations and line count. Both provide follow-up arguments for reading source with `wincode_prepare_context`. ```json { - "mcpServers": { - "wincode": { - "command": "node", - "args": ["C:/path/to/WinCode/dist/index.js", "--workspace", "C:/path/to/project"] - } - } + "task": "Review the save logic", + "lineRanges": [{ "file": "src/Service.cs", "startLine": 50, "endLine": 80 }], + "maxTokens": 2000 } ``` -> **Path note:** All paths above are illustrative placeholders. Replace them with your actual absolute installation and project paths. The server entry point and the project directory serve different purposes and need not be in the same directory. - -For graphical configuration interfaces: - -| Field | Bind the launch directory | Specify a project at startup | -| --- | --- | --- | -| Name / Type | `wincode` / `stdio` | `wincode` / `stdio` | -| Command | `node` | `node` | -| Argument 1 | `C:/path/to/WinCode/dist/index.js` | `C:/path/to/WinCode/dist/index.js` | -| Argument 2 | Omit | `--workspace` | -| Argument 3 | Omit | `C:/path/to/project` | - -Add each argument as a separate entry, without extra surrounding quotes even when a path contains spaces. Explicit `--workspace` (or `-w`) requires a nonempty absolute path; omission binds the launch directory. Ensure `node` is available in PATH, or specify its absolute executable path. No extra environment variables are required. +Use actual paths and line numbers from the search result. `lineRanges` selects known lines; `scopeFiles` limits reading to known files. `candidateFiles` prioritizes files during discovery and is not an exclusive scope. Check returned ranges, `coverage` and truncation before deciding whether more code is needed. `maxTokens` is an estimate based on UTF-16 character count, not a model-specific token count. -For Skill installation and client configuration, see the [Skill and MCP setup guide](WinCode-Skill制作与MCP配置指南.md). +**UI inspection:** Select a window, query the relevant control or subtree, and request source candidates when needed. `responseFormat: "compact"` retains control IDs, names, hierarchy and states while omitting per-node geometry and class names. Use `full` when coordinates or additional detail are needed. Unsupported or unknown control states are distinct from `false`. -### Navigation and connection guidance +**C# semantic analysis:** Enable Roslyn explicitly, search for a symbol, and pass its returned `location` unchanged as `symbolLocation` to reference, impact or refactoring tools. Search again when the tool reports a stale location. The default `local-text` provider offers text-based navigation and reports its semantic limitations. -To obtain a separate project's STDIO configuration without starting its Gateway or changing client settings: +| Tool | Purpose | +| --- | --- | +| `workspace_open` | Confirm or recover the fixed workspace and return a compact project summary. | +| `wincode_list_directory` | Browse a directory with depth, entry-count and output limits. | +| `wincode_analyze_workspace` | Read solution structure and declared project references. | +| `wincode_search_text` | Find literal text within selected files or directories. | +| `wincode_file_outline` | Read a file's local declarations and observed line count. | +| `wincode_prepare_context` | Read selected source excerpts with paths, line ranges and coverage information. | +| `wincode_find_code_symbol` | Search symbols using the configured provider. | +| `wincode_find_references` | Find references and report known totals, returned counts and truncation. | +| `analyze_change_impact` | Assess potential change impact and report uncertainty when evidence is incomplete. | +| `wincode_plan_refactoring` | Suggest checks and verification steps for a proposed refactoring. | +| `wincode_safe_move_to_trash` | Move validated workspace files to `trash/` and record the actual completed or partial outcome. | +| `wincode_ui_list_windows` | List visible top-level windows with process and title filters. | +| `wincode_ui_inspect` | Read controls and optional states or screenshots. | +| `wincode_ui_review` | Inspect UI and return candidate XAML/C# source locations. | +| `wincode_hello_world` | Read instance identity, workspace binding, capabilities and known status. | +| `wincode_diagnose_project` | Actively check SDKs, Git and the local environment. | + +`wincode_analyze_change_impact` is an alias of `analyze_change_impact`. Detailed parameters and workflows: [code analysis](skills/wincode/references/code.md), [UI inspection](skills/wincode/references/ui.md), [diagnostics](skills/wincode/references/diagnostics.md). To inspect a tool's schema in the running connection, pass its name as `toolName` to `wincode_hello_world`. + +### Optional configuration + +- **Roslyn:** Add `--roslyn-config` followed by an absolute configuration-file path. This enables the C# Code Host and requires explicit authorization for MSBuild project evaluation. Configuration, input tracking and recovery are described in the [code guide](skills/wincode/references/code.md). +- **Connection configuration:** Run `node C:/path/to/WinCode/dist/index.js --print-connection --workspace C:/path/to/project` to generate a project's stdio configuration without starting its Gateway or changing client settings. This generates the default local-text configuration; add any Roslyn or Tray options separately. +- **Tray and memory management:** Add `--tray` to the Gateway arguments, reconnect, and manually start `tools/WinCode.Tray/bin/Release/net10.0-windows/win-x64/publish/WinCode.Tray.exe --show`. In **设置 / 内存管理**, select an idle instance and choose **释放 Roslyn 内存**. The next explicit symbol search reloads the project; previous symbol locations become invalid. Automatic idle release is disabled. Exiting Tray leaves MCP running. See the [diagnostics guide](skills/wincode/references/diagnostics.md). +- **Agent Skill:** After updating WinCode, use `npm run skill:check -- ` to check the installed Skill. `npm run skill:sync -- ` backs up and synchronizes the Skill documents managed by the sync script. It does not change MCP configuration or restart a connection. + +### Scope and limitations + +- **Desktop access:** UI inspection is read-only. It does not click controls, type text or read input-field values. Background mode requires both PID and HWND, supports non-minimized windows, and does not activate or restore the target. UI inspection requires an interactive Windows desktop session and does not support headless operation. +- **UIA and visual rendering:** Available properties depend on the application's UIA provider. WPF is covered by the project's desktop tests; other frameworks and custom-rendered controls may expose less information. Colors, icons and rendering quality require visual review. Background screenshots use `PrintWindow` without screen-capture fallback; check the returned capture-quality indicators. +- **Source mapping:** XAML and C# matches identify candidate source locations, with `runtimeSourceVerified: false`. The tool does not verify that the running build matches the source, resolve dynamic bindings or runtime templates, or determine the active `DataContext`. +- **Analysis coverage:** Project structure analysis reads `.sln` and `.csproj` declarations without MSBuild evaluation. Text-based references are heuristic. Review completeness, omissions and diagnostics before drawing conclusions; no matches in a limited scan do not establish absence across the project. +- **Resource limits:** Requests, traversal and response size have explicit limits. Overload returns `SERVER_BUSY`; queue time counts toward the timeout. Output limits do not represent process memory limits. Full concurrency, cache and process-lifecycle details are in the [architecture guide](WinCode-架构与数据流说明.md). +- **Inspection notice:** During inspection, a semi-transparent `REC / WinCoding` status overlay is displayed without taking focus, and minimal local audit metadata is recorded under `%LOCALAPPDATA%/WinCode/logs/ui-audit`. See the [diagnostics guide](skills/wincode/references/diagnostics.md) for audit-log maintenance. + +### Development and documentation + +Current source version: **0.15.0**. See [CHANGELOG](CHANGELOG.md) for version history and migration notes. Windows 11 x64 is the reference platform; ports to other operating systems require adaptation and separate validation. ```powershell -node C:/path/to/WinCode/dist/index.js --print-connection --workspace C:/path/to/project +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 ``` -`WORKSPACE_MISMATCH` returns the same `connectionGuide`: absolute command/argument entries and a workspace verification call. It describes a default local-text connection; existing Roslyn, development and Tray options are not copied. Directory existence is checked on actual startup. Refresh the corresponding client connection after rebuilding to load the new tools/schema. +[CI](https://github.com/linnnn89/WinCode/actions/workflows/ci.yml) runs on Windows with Node.js 22 and 24 and the pinned .NET SDK. The Node.js 22 job includes additional native and integration checks; desktop tests run separately. Benchmark reports measure scripted scenarios, including calls, response size and execution time. See the linked records for test conditions and results. -For ordinary code navigation, call `wincode_search_text` with a literal `query` and exclusive `scopePaths`, or `wincode_file_outline` with a literal `file`. Search returns one match per line; outlines return observed line/byte counts and text declarations. Both include `nextRequest` arguments for `wincode_prepare_context` and bounded file-level diagnostics. They use local text regardless of the semantic provider. Paths, scan/output budgets and cancellation remain enforced; zero matches do not prove absence outside the scanned scope. +- [Contributing](CONTRIBUTING.md): builds, test suites and delivery requirements. +- [Architecture and data flow](WinCode-架构与数据流说明.md): components, interfaces, resource limits and lifecycle management. +- [Skill and MCP setup](WinCode-Skill制作与MCP配置指南.md): installation and client configuration. +- [Work log](docs/codex_worklog.md) and [remaining test plan](WinCode-下一轮工程化迭代计划书.md): historical verification, known issues and pending validation. -Context `summary` gives the displayed scope, complete/partial/missing counts and next action. An EOF error now reports actual line count and, where an intersection exists, a corrected read request while preserving the original coverage gap. UI inspect/review optionally accept `responseFormat: "compact"`: retain node IDs/hierarchy/states and the image, omit per-node geometry/class names, share repeated C# candidates through `candidateIds`, and provide live-UI `expansionRequests` for full detail. Default UI output remains `full`; compact counts do not establish defects or binding causality. - -### Optional tray and manual memory release +--- -Automatic Roslyn release is **off**. This version provides no idle timer or automatic-release switch. A loaded semantic workspace stays warm for successive Agent calls. To release it when you decide it is no longer needed: +## 简体中文 -1. Build with `npm run check`, then run `tools/WinCode.Tray/bin/Release/net10.0-windows/win-x64/publish/WinCode.Tray.exe --show` from the repository. It requires the .NET 10 Windows Desktop runtime and does not install itself or enable Windows startup. -2. Add `--tray` as a separate argument to each Gateway you want to see, then refresh that MCP connection. For example: `"args": ["C:/path/to/WinCode/dist/index.js", "--workspace", "C:/path/to/project", "--tray"]`. Keep your existing explicit `--roslyn-config` arguments if using Roslyn. -3. Open **设置 / 内存管理**, refresh the observed state, select an idle instance and click **释放 Roslyn 内存**. A busy instance refuses the action; it does not queue a release for later. Requests arriving after a release has started wait for it to finish. +WinCode 是面向 AI 编程智能体的本地模型上下文协议（Model Context Protocol，MCP）服务器，集成 Windows UI Automation（UIA）、代码导航和 .NET 项目分析功能。智能体可以通过同一连接检查正在运行的应用，并查阅相关源码。 -“暂无在途请求” means no request is currently in flight, not that the Agent has finished its task. Failed refreshes or observations older than 30 seconds are shown as unknown; manual release first obtains a new passive status. Opening, refreshing, hiding, or reconnecting Tray never releases or reloads Roslyn. Registration errors are reported in settings and Gateway diagnostics. +### 核心功能 -Release closes only that instance's owned Roslyn Host and invalidates its symbol locations. The next explicit symbol search reloads the project; old `symbolLocation` values require a new search. Gateway, workspace watcher, bounded cache, and last diagnostics remain. Local-text instances have no Roslyn memory to release. +- **后台 UI 检查：**无需激活目标窗口或切换键盘焦点，即可读取运行中应用的控件信息。智能体检查目标窗口时，用户可以继续使用其他应用。 +- **支持纯文本大语言模型：**以结构化 JSON 返回控件名称、层级、属性和状态。通过支持 MCP 的智能体客户端，DeepSeek 等以纯文本方式使用的模型也能检查桌面界面，无需输入图像；截图为可选功能。 +- **结合源码分析 UI：**检查运行时控件，查找可能对应的 XAML 声明和相关 C# 代码，再读取具体源码。结果包含文件路径、行号和内容哈希，便于核查。 +- **实际使用中更快、更准确：**在日常 Windows/.NET 开发中，使用 WinCode 检查 UI 和定位源码，比基于截图的 Computer Use 工作流更快、更准确。通过直接获取结构化的控件属性和源码位置，可以减少对图像识别的依赖和反复交互；配合定向查询与精简响应，还能减少模型需要处理的数据量。 +- **项目与代码分析：**查看解决方案和项目中声明的引用关系，搜索文本与符号，按需读取代码，并评估变更影响。默认提供内置文本分析，可选的 Roslyn 集成支持基于编译器语义的 C# 符号与引用分析。 -Tray and Gateway are independent. Hiding settings or exiting Tray leaves MCP running; **停止此实例** requests that selected Gateway's normal shutdown after confirmation. Start Tray manually when needed; it can connect before or after an opted-in Gateway. The current limit is eight connected Gateways per Windows user/session. Use the same Windows user and privilege level. State is observed on registration/open/refresh, not continuously polled; disconnected means unknown, and the connection count does not include old or unregistered instances. Remove `--tray` and reconnect to disable integration. Windows 11 is the tested platform; alternate permissions, Explorer recovery and other DPI configurations need separate validation. +在包含 222 个节点的窗口测试中，仅查询指定控件即可将返回文本量从约 **62 KB 减少至 1.6 KB**。详见 [测试记录](docs/codex_worklog.md)。 -### Example: Inspect a control +### 使用示例：排查“保存”按钮被禁用的问题 -Filter by a control's name, type or automation ID to read the relevant part of a large window tree: +> 查找应用窗口，在不切换前台窗口的情况下检查“保存”按钮是否启用，并定位相关 XAML 和 C# 代码。 -> **Prompt:** *"Find my application's window, inspect its Save button in the background, and verify its declaration in `Views/MainWindow.xaml`."* +智能体可以通过纯文本输出完成以下排查流程： -1. Call `wincode_ui_list_windows` with a process name or title substring filter to obtain the target `pid` and `hwnd`. -2. Inspect the targeted control using `wincode_ui_inspect`: +1. 调用 `wincode_ui_list_windows`，通过 `processName` 或 `titleContains` 获取目标进程 ID（`pid`）和窗口句柄（`hwnd`）。 +2. 调用 `wincode_ui_review`，指定目标控件和相关源码文件。如果尚不知道文件位置，先使用代码导航工具定位。 ```json { @@ -139,196 +210,39 @@ Filter by a control's name, type or automation ID to read the relevant part of a "hwnd": "0x123456", "backgroundOnly": true, "capture": "none", - "query": {"automationId": "SaveButton", "controlType": "Button"}, + "responseFormat": "compact", + "query": { "automationId": "SaveButton", "controlType": "Button" }, "maxDepth": 3, "maxNodes": 30, - "readStates": true + "candidateFiles": ["Views/MainWindow.xaml"], + "candidateCodeFiles": ["ViewModels/MainWindowViewModel.cs"] } ``` -3. Enable `capture: "annotated"` when visual layout verification is needed. To correlate the widget with source code, switch to `wincode_ui_review` and supply `candidateFiles: ["Views/MainWindow.xaml"]`. - -Optionally add `candidateCodeFiles: ["ViewModels/MainWindowViewModel.cs"]` (1–8 explicit relative C# files). `codeEvidence` follows literal Click/simple Binding identifiers to declaration/assignment candidates and provides scoped `nextRequest` arguments for `wincode_prepare_context`. Reads are bounded to 256 KiB per file/1 MiB total, with at most 40 clues, 200 matches and 16000 JSON characters before the shared response budget. Missing or ambiguous matches remain explicit; runtime build identity, DataContext, templates and a disabled control's cause are not established. Omit this option for the existing XAML-only path. - -**Capture and state options:** - -- **Optional screenshots:** `capture: "none"` returns structural JSON without an image. Screenshots use separate MCP `image` blocks; their Base64 content is not included in the text response. -- **Control states:** `readStates: true` reads toggle, selection and expand/collapse states without changing them. An unsupported UIA pattern is reported as unsupported, so it can be distinguished from a supported state whose value is `false`. -- **Background capture:** `backgroundOnly: true` uses `PrintWindow` to capture the specified window. It does not activate or restore that window, change focus, or fall back to a screen capture. Minimized windows are not supported. - -### Tool reference - -Local declaration search supports C#/TS/TSX/JS/JSX/Python with bounded comment/literal/JSX masking; uncertain lexical boundaries are reported as incomplete. Text references remain heuristic. Impact analysis returns one JSON text block, including formattedReport once. Known tool errors expose matching JSON text and structuredContent; unknown tools use JSON-RPC -32602 during normal admission. - -The default provider is `local-text`, with an explicit semantic-unconfigured status. Configure direct Roslyn to obtain compiler-backed identities. Pass a returned `location` unchanged as `symbolLocation` to references, impact, or refactoring, and use the returned plain symbol name. Old Serena namePath identities and external startup settings are retired; stale snapshots require a new explicit search. - -`wincode_hello_world` reports a frozen running instance ID and build fingerprint, plus a hash of the tool definitions actually registered by that instance. Pass `toolName: "wincode_prepare_context"` to inspect just that tool's input schema. Compare it with `tools/list` on the same connection. `npm run build` emits a manifest; direct `tsc`, missing/mismatched artifacts or source development mode can report `unknown`. The build fingerprint checks local output consistency, not release authenticity. Workspace changes do not change the running build. - -Explicit `lineRanges` return `coverage` computed from the final serialized evidence: requested/complete line counts, actual returned intervals, missing intervals and reasons. A partial last line (`endLineComplete: false`) is not a covered line. Recoverable gaps can include a bounded `nextRequest`; EOF/missing files do not suggest blind retries. Detail pruning reports `omittedItemCount` while retaining totals. `bodyStatusScope` identifies `displayed-snippet` or `packed-file`; a complete snippet does not mean a complete method. Symbol windows report `symbolCoverage: "unknown"` and, when more file lines exist, a `nextRequest` for up to 80 following lines. A partial tail is reread; observed EOF stops continuation. This is optional follow-up evidence, not a parsed method boundary. Other requests return `coverage: null`; `taskCoverage` is always null because source excerpts do not prove whole-method or task sufficiency. `npm run test:tavern-context -- ` runs an opt-in read-only source acceptance in a new stdio process. - -After rebuilding, reconnect the client's MCP server and check hello again; rebuilding files alone cannot update an existing process or the client's cached schema. `npm run test:e2e` verifies one new stdio process with compiled handlers and an isolated source fixture, including actual symbol/range bodies. It does not verify a separate Codex connection or GUI/upstream adapters. - -After updating the repository, check the installed skill with `npm run skill:check -- `; a mismatch exits with code 2. Use `npm run skill:sync -- ` to back up and synchronize the four managed documents, preserving additional files. This does not change MCP configuration or restart a connection. - -The 2026-09-08 check of the current Codex connection against TavernDesk source passed: workspace opening returned 3,705 UTF-16 characters, the requested method was located, and a 223-line request matched the source completely. A 512-token estimate budget reported only 9 complete lines and an incomplete tenth line. This is a dated acceptance result for that instance; verify other connections separately. Details are in the [work log](docs/codex_worklog.md). - -| Tool | Purpose | -| --- | --- | -| `wincode_search_text` | Search literal text within exclusive files/directories; return locations, bounded previews and follow-up reads. | -| `wincode_file_outline` | Read one file's observed line/byte counts and bounded local declarations with follow-up reads. | -| `workspace_open` | Confirm or recover the fixed workspace and return a bounded summary; reject other roots. | -| `wincode_list_directory` | Browse a specific workspace directory with entry, depth and output limits. | -| `wincode_analyze_workspace` | Parse solution structure and declared `.sln`/`.csproj` project references. | -| `wincode_prepare_context` | Return code excerpts with file paths and line ranges within a character-based output limit. | -| `wincode_find_code_symbol` | Search symbols and report the provider and completeness of the results. | -| `wincode_find_references` | Find references using a returned symbol location; optional Roslyn `limit` is 1–1000 (default 100, requires `symbolLocation`). Both providers accept `maxOutputChars` (2048–32768, default 8000) for the final JSON text. Preserve known totals and report returned counts, truncation and output omissions. | -| `analyze_change_impact` | Estimate which code a change may affect. Return `riskLevel: "UNKNOWN"` and `confidence: "UNCERTAIN"` for ambiguous symbols, incomplete results or no references. | -| `wincode_plan_refactoring` | Suggest pre-edit checks and verification steps based on change impact. | -| `wincode_safe_move_to_trash` | Validate paths, move files to `trash/` and record metadata. Cancellation before the move stops it; finalization preserves the actual completed/partial outcome even after a deadline. | -| `wincode_ui_list_windows` | Enumerate visible top-level windows with title/process filters and count limits. | -| `wincode_ui_inspect` | Inspect UI control subtrees, interactive states, and optional numbered screenshots. | -| `wincode_ui_review` | Return explicit XAML/C# source candidates, lines, hashes and scoped next requests from one UI snapshot. | -| `wincode_hello_world` | Read instance identity and known adapter state without spawning probes; use diagnose_project for active checks. | -| `wincode_diagnose_project` | Check installed SDKs, Git and the local Windows environment. | - -`wincode_analyze_change_impact` is an alias of `analyze_change_impact`. Detailed workflows: [code intelligence](skills/wincode/references/code.md), [UI inspection](skills/wincode/references/ui.md), [diagnostics](skills/wincode/references/diagnostics.md). - -Architecture analysis accepts integer depths 1–5 and returns `scanComplete`, `omissions` and output truncation evidence. Discovery examines at most 2000 entries; the tree preview examines 500. The graph reads at most 16 project descriptors, 64 KiB per file and 256 KiB total, and examines at most 2000 entry-point directory entries. The complete report is capped at 32768 UTF-16 characters. Outside-workspace projects are omitted; this tool does not evaluate MSBuild. - -Git probes use a detected absolute installation path outside the workspace, require Git 2.36 or later and disable executable fsmonitor configuration. Missing or failed Git status is `unknown`, with no assertion that the tree is clean. Cache/trash writes reject existing symlinks and junctions in their paths. Cache cleanup manages versioned WinCode JSON and reserved overflow names; legacy/unrecognized files remain untouched and are outside the managed quota. These checks do not provide an atomic sandbox against concurrent filesystem replacement. - -Raw arguments, including unknown fields, are limited to 64 KiB of UTF-8 JSON before normalization. SERVER_BUSY includes workStarted:false, retryable:true and a capacity snapshot; retry only when needed, without automatic replay or Host restart. REQUEST_TIMEOUT includes queue time and does not prove work never started. health.admission exposes counters and timing. Passive hello uses known disk observations, with null values before an explicit diagnostic scan. These limits do not remove SDK parsed-frame allocation or bound process RSS. - -### Architecture and resource control - -The [architecture and data-flow guide](WinCode-架构与数据流说明.md) describes components, request handling, storage and delivery checks (Chinese). - -```text -Coding agent ── stdio MCP ── WinCode - ├─ Code adapters: Direct Roslyn / Repomix / Local text - ├─ Workspace analysis, context, and impact tools - └─ FlaUiAdapter ── stdin/stdout JSON ── .NET UIA helper - └─ Window tree + screenshot -``` - -- **Helper process cleanup:** UI inspection runs in a separate C# helper (`tools/WinCode.UIA.Host`). Cleanup uses Windows `taskkill /T` on helper processes started by WinCode and their children; the inspected application is outside that cleanup scope. -- **Request concurrency:** UI inspection and health checks share a mutex. Each connection keeps its startup workspace; requests for another workspace are rejected before resource changes. Recovery waits for existing calls within its timeout. Each instance accepts up to 32 unfinished tool requests; passive hello and `tools/list` share four separate request slots. Existing adapter mutexes retain FIFO order. Queueing counts toward the timeout, and a cancelled request keeps its slot until cleanup finishes. -- **Cache limits and invalidation:** Cache entries are separated by workspace namespace, though instances may share a disk directory. Defaults are 32 MiB for serialized data in memory and a 128 MiB disk cleanup target including overflow files. These are not process RSS limits or an immediate cross-process disk quota. Local-text queries rescan inputs within scan limits and reuse declarations by content hash. Built-in packing checks selected file contents before reuse; CLI output without a verified input manifest is not cached. Reads check the payload against its key and validate attachment size and SHA-256. Missing, corrupted or older entries without integrity metadata are rebuilt. Returned attachments can be removed by later cleanup. The watcher's 150 ms debounce and index probes invalidate a change-hint cache lasting about 2.5 seconds; the hint does not verify source contents or prove that every file change was observed. - -| UI inspection limit | Behavior | -| --- | --- | -| Targeted query | Scans up to 1,000 nodes by default (max 5,000); returns up to 10 candidates (max 20). | -| Traversal bounds | Soft limits of 2 seconds and 50 levels; blocking native Win32 calls are terminated by the helper process timeout. | -| Tree text | Capped at 128 KiB with explicit truncation reasons. | -| PNG image | 2 MiB ceiling; dynamically downscaled or safely omitted if still oversized. | -| Transport pipe | Capped at 6 MiB raw stream bytes. | -| Screenshot allocation | Hard check: at most 16,777,216 total pixels and 16,384 pixels per dimension before bitmap allocation. | - -`helperPeakWorkingSetBytes` reports peak operating system working set through response preparation. `treeComplete` reflects structural coverage, while `propertyIssues` tracks clipped or unavailable properties. - -### Limitations and on-screen notice - -- **Background capture:** `backgroundOnly: true` requires both PID and HWND. It uses `PrintWindow` without focus shifts or screen fallbacks. Minimized windows are rejected. `captureQuality` samples up to 1024 raw pixels before annotation: `suspect-low-variation` means the sampled RGB channel ranges are at most 3 and may reflect either blank output or a legitimate uniform/low-contrast view. `unknown` never certifies visual usability. Hints retain both image and UIA evidence and do not change the capture policy. Older helpers without this field leave quality unverified. -- **UI coverage:** Inspection depends on the application's underlying UIA provider. Verified against WPF; WinUI, WinForms, and custom-rendered controls may expose differing levels of UIA detail. -- **Source evidence:** Matches literal attribute declarations in supplied `.xaml` files (`runtimeSourceVerified: false`). Dynamic bindings, runtime templates, and resource dictionaries are not evaluated. -- **Project analysis:** Extracted directly from project file XML without invoking MSBuild evaluations. Direct Roslyn requires explicit project-evaluation authorization; Repomix is optional. Local text results explicitly label reduced semantic coverage. -- **On-screen notice:** During UI inspection, a semi-transparent `REC / WinCoding` overlay appears in the top-right corner of the primary display without taking focus. -- **Local audit:** Lightweight start/end records are flushed to `%LOCALAPPDATA%/WinCode/logs/ui-audit` (1 MiB triggers cleanup reminders; 2 MiB blocks new access with reserved end-record space). The [audit checker script](scripts/check-ui-audit.ps1) enables manual inspections. - -### Opening and browsing a workspace - -`workspace_open({"path":"~/target-project"})` returns a compact summary with at most 8 entry paths and no directory tree by default. `maxOutputChars` defaults to 8000 (2048–32768) and budgets the entire JSON text, including metadata and escaping; it is not a model-token count. Replace the placeholder with an absolute path. Discovery is bounded: check `projectScanComplete` and the reported gaps; unmeasured file/size totals are `null`. - -Use `wincode_list_directory({"path":"src","maxDepth":1,"maxEntries":100})` to browse only the next useful directory. It reports actual visited/returned counts, omissions and truncation. `includeIgnored:true` explicitly exposes generated directories within the workspace; outside-workspace links remain rejected. Narrow the path after truncation. Existing callers needing a tree can request `workspace_open({"path":"~/target-project","includeTree":true})`, which returns a bounded compatibility tree, not the former unrestricted inventory. - -### Choosing how to read code - -Use `wincode_prepare_context` with the location information already available: - -```json -{"task":"Review the save logic","lineRanges":[{"file":"src/Service.cs","startLine":50,"endLine":80}],"maxTokens":2000} -``` - -Known lines: use `lineRanges`. For a declaration and nearby context, use `scopeFiles` plus `symbol`; this returns a 24-line window before budget clipping. When reviewing a known method's error handling, cancellation or cleanup, prefer an existing file reader with bounded `rg` context when available, so the required branches can be read together. A small known file can also be requested with `scopeFiles` and `includeFullText:true`, subject to the output budget. Known files only: use `scopeFiles` for a preview. Use `candidateFiles` when discovery beyond those candidates is intended; it remains a priority list, not an exclusive scope. Scoped symbol matching currently uses local C#/TS/JS/Python declaration patterns and reports incomplete semantic coverage; ambiguous or missing targets remain explicit issues. - -The default `compact` response contains one JSON text block; `responseFormat: "legacy"` returns JSON plus Markdown. `maxTokens` accepts 512–65536 and estimates tokens by dividing the UTF-16 character count of all returned text, including metadata, by four. Check the returned ranges, `queryComplete`, truncation and `bodyStatus` to decide whether more code is needed. Read again after edits or reconnecting: source files can change between calls. The reuse strategy in the benchmark is not a production cache feature. Parameter combinations and limits are in the [code manual](skills/wincode/references/code.md). - -### Development and validation - -The [CI workflow](.github/workflows/ci.yml) runs `npm run check` on pull requests and main pushes using `windows-2025` runners, Node.js 22/24 and .NET SDK 10.0.303. Both jobs build with locked dependencies and run core regression tests, stdio integration tests and delivery verification. Reports have output limits and are also saved on failure. Only Node 22 runs the additional shared-cache, error/recovery, real Roslyn, process cleanup, manual release, SDK concurrency and design-time isolation tests. The jobs run different workloads, so their total durations cannot be used to compare Node runtime performance. Each job has a 20-minute timeout. Interactive desktop/UI tests run separately. Main branch protection requires Node 22/24 and three CodeQL checks; the single-maintainer policy requires no review approvals. See [CONTRIBUTING](CONTRIBUTING.md). - -```powershell -npm ci -npm run check # Locked builds, core regression, stdio and delivery manifest -npm run check:desktop # Isolated WPF, UI and UI-to-source; interactive Windows required -npm run delivery:verify # Detect changed/missing Gateway, Host sidecars or managed Skill -npm run test:inventory # Ensure every *.test.ts belongs to a declared suite -npm run test:all # Both check and check:desktop -npm run benchmark:agent -- 1 # Opt-in pilot; -- 3 for three repetitions -``` - -Live UI suites require an interactive Windows desktop session. In a 222-node test fixture, targeted queries reduced response text from 62 KB to ~1.6 KB while completing in ~0.78 seconds. Detailed test records are maintained in the [work log](docs/codex_worklog.md). - -`npm run test:product -- ` explicitly runs six navigation-to-source tasks against an already running fixed test profile. It discovers source files, checks the live control and verifies literal command/method candidates, recording native and MCP calls, response characters and repeated source lines under `test-tmp/product-tasks`. It neither launches the application nor changes its data or source. This scripted acceptance does not establish runtime bindings, full-method coverage, native-only speedup or semantic completeness; see the acceptance matrix in the work log. - -The agent benchmark covers ten scripted scenarios, including existing `dotnet-mini` C# fixtures and four levels of initial location knowledge. It validates returned files, ranges, bodies and status against current fixture contents. Tool/transport/response/cleanup failures remain in the JSON report under `test-tmp/agent-efficiency`; failed cases produce a nonzero exit code. Unchanged-evidence reuse is tested only under trusted, controlled fixture writes; edits require a new request. Reports measure MCP calls, output characters, repeated displayed lines and call time using local fallback with upstreams and GUI disabled. They do not establish real-agent completion rates, model-token savings or production cache benefits. Schema v2 results should not be compared directly with the earlier six-scenario report. - ---- - -## 简体中文 - -WinCode 是用于 Windows 和 .NET 项目的本地 MCP 服务。Coding Agent 可以通过它读取项目引用、搜索源码、查看运行中的控件和标注截图，也可以查找控件可能对应的 XAML 声明。 +3. 查看返回的控件属性和源码候选位置。例如，`isEnabled: false` 表示控件处于禁用状态。根据返回的 `nextRequest` 参数调用 `wincode_prepare_context`，读取候选声明或赋值语句。 +4. 核查源码后再解释界面行为。匹配到绑定或命令名称，可以确定下一步需要检查的代码，但仅凭名称匹配无法确定当前 `DataContext` 或按钮被禁用的原因。 -- **读取项目代码：**解析 `.sln`/`.csproj` 声明的项目引用，检索符号，并在字符数限制内返回代码片段。Token 数量为估算值。 -- **查看应用界面：**列出可见窗口，读取指定控件或子树，在不激活目标窗口的情况下获取带编号的截图。 -- **查找相关 XAML：**返回匹配的源码声明、行号和文件哈希，并说明匹配不唯一、输出被截断或代码分析服务不可用的情况。 +上述 ID 和路径均为示例，使用时应替换为实际窗口和工作区中的值。如果只需读取控件树，可使用 `wincode_ui_inspect`，无需传入源码文件参数。需要勾选、选中或展开/折叠状态时，添加 `readStates: true`；需要结合编号截图检查视觉效果时，使用 `capture: "annotated"`。 -当前源码版本为 **0.15.0**，已合并至 `main`，尚未发布 GitHub Release。UI 工具只读取信息，不操作控件；固定工作区迁移和版本历史见 [CHANGELOG](CHANGELOG.md)。 +### 快速开始 -**平台与兼容性说明：**本项目以 **Windows 11 x64** 为本地开发与测试基准。其他操作系统、其他 Windows 版本或不同依赖版本下，功能表现、运行行为与性能不保证完全一致。建议 **macOS、Linux 用户通过 fork 本仓库进行本地适配与验证**；请以本项目文档和锁定文件中列出的依赖版本作为参考环境。 +**环境要求：**Windows x64、Git 2.36 及以上、Node.js `>=22`（推荐 24，兼容 22），以及 .NET SDK **10.0.303**。SDK 版本已在 `global.json` 中锁定，并通过 `rollForward: "disable"` 要求使用完全匹配的版本。发布的 UI 辅助程序和可选托盘程序均依赖 .NET 10 Windows Desktop 运行时。开发和测试的基准平台为 Windows 11 x64。 -### 快速上手 - -**环境要求：**Git、Windows x64、Node.js `>=22`（主要使用 24，同时测试 22 的兼容性）。构建使用 `global.json` 锁定的 .NET SDK 10.0.303，不自动选择其他 SDK 版本；`dotnet publish` 生成的 UI Helper 需要 .NET 10 Windows Desktop 运行时。构建和交付校验见 [CONTRIBUTING](CONTRIBUTING.md)。 +**1. 构建并验证 WinCode** ```powershell git clone https://github.com/linnnn89/WinCode.git cd WinCode npm ci npm run check - -# 核对 Gateway / Release Host / Skill 完整交付物 npm run delivery:verify ``` -在 Agent 客户端配置文件中添加 stdio MCP 服务（以支持 `mcpServers` 的客户端为例）。每条连接在启动时固定一个项目，推荐显式指定绝对路径 `--workspace`。 +运行 `npm run check` 会构建 Gateway 和原生组件，执行核心回归测试与 stdio 集成测试，并验证交付清单。桌面测试单独执行。 -**绑定启动目录：**仅在客户端能够保证服务启动目录就是目标项目时使用： +**2. 配置 MCP 连接** -```json -{ - "mcpServers": { - "wincode": { - "command": "node", - "args": ["C:/path/to/WinCode/dist/index.js"] - } - } -} -``` - -省略 `--workspace` 时，启动目录就是该连接的固定工作区。`health.workspaceBinding` 返回工作区根目录及其配置来源。`workspace_open` 用于确认或恢复这个工作区；传入其他根目录会返回 `WORKSPACE_MISMATCH`，且不会等待现有请求结束或修改资源。要分析其他项目，请使用绑定该项目的连接。不同项目的局部配置可以使用同一服务名，同一份共享配置中的多个实例需要不同名称。工作区正常时，重复打开会保留 Host、快照和文件监听，无需等待现有查询结束；发生故障时按诊断手册恢复。 - -每个 Roslyn Host 都有独立的设计时中间文件目录，同时保留项目的 NuGet restore 位置、Compile 排除规则和原有 MSBuild 导入设置。Node 22 CI 已覆盖三个独立 MCP 进程同时冷启动（项目 A/B/A）、引用查询和各 Host 输出文件的清理，也包含此前共享 `obj` 文件并发写入冲突的回归测试。 - -每个实例最多接受 **32 个尚未完成的工具请求**，包含排队中的请求。被动 hello 和 `tools/list` 另行共享 **4 个请求名额**。原始参数上限为 **64 KiB UTF-8 JSON**。排队时间计入请求超时；超过容量时返回 `SERVER_BUSY`。取消的请求需完成清理后才不再占用名额。共享缓存会核对所选源码的内容和缓存附件，缺失或损坏时重建。 - -**2026-09-11 已验证基线：**代码导航和 UI 精简输出（[PR #40](https://github.com/linnnn89/WinCode/pull/40)），以及 worktree 的 `.git` 文件过滤与托盘测试调度修正（[PR #41](https://github.com/linnnn89/WinCode/pull/41)）均已合并。合并后的 `main` 提交 `631f8ba` 通过 [Node 22/24 CI](https://github.com/linnnn89/WinCode/actions/runs/34586761303) 和三项 [CodeQL 检查](https://github.com/linnnn89/WinCode/actions/runs/34586761201)。Node 22 记录核心测试 453 项通过、0 项失败、1 项可选 TavernDesk 测试跳过；Roslyn Host 59/59、Gateway 22/22、共享缓存 8/8、SDK 并发 10/10、设计时隔离 21/21 均通过。Node 22 还执行额外验收，不能用两个任务的总耗时比较 Node 22/24 的性能。 - -可选 TavernDesk 验收脚本在启动时绑定目标仓库，缓存和回收站使用独立临时目录。真实项目的 8 个上下文场景和 6 个 UI 产品任务均已在本机通过。专用应用最初报 `UnauthorizedAccessException`；用当前未修改的源码构建后启动成功，但原始启动失败的原因尚未确定。 - -本机还验证了两个独立 Gateway 检查同一窗口及不同窗口：重叠访问返回 `AUDIT_BUSY`，随后恢复成功，窗口身份、截图及辅助进程清理均通过检查。实际 Codex 连接使用 TavernDesk.Core 的隔离副本完成 Roslyn 搜索、引用、影响分析和重构建议；修改源码后，旧位置被拒绝，重新搜索后引用查询恢复。此次只覆盖一个项目和配置，排除了 8 个分析器/生成器引用，不代表完整应用覆盖。长期资源占用和未定位的 UI 问题见[后续测试计划](WinCode-下一轮工程化迭代计划书.md)，测试结果和失败记录见[工作日志](docs/codex_worklog.md)。 - -**启动时指定项目（推荐）：**添加 `--workspace` 和已存在的项目目录绝对路径： +对于支持 `mcpServers` 的客户端，添加以下 stdio 配置。建议显式设置 `--workspace`： ```json { @@ -341,190 +255,95 @@ npm run delivery:verify } ``` -> **路径说明：**以上路径均为通用占位示例，请替换为实际的安装目录和项目目录绝对路径。服务入口与待分析项目目录用途不同，不必位于同一个目录。 - -若通过图形界面添加： - -| 配置字段 | 绑定启动目录 | 启动时指定项目 | -| --- | --- | --- | -| 服务名称 / 类型 | `wincode` / `stdio` | `wincode` / `stdio` | -| 启动命令 | `node` | `node` | -| 参数 1 | `C:/path/to/WinCode/dist/index.js` | `C:/path/to/WinCode/dist/index.js` | -| 参数 2 | 不添加 | `--workspace` | -| 参数 3 | 不添加 | `C:/path/to/project` | - -每个参数独立添加为一行，路径包含空格时也无需额外加引号。显式 `--workspace`（或 `-w`）必须附带非空绝对路径；省略参数表示绑定启动目录。确保 PATH 中包含 `node`，或填写 node.exe 的绝对路径。无需额外设置环境变量。 - -Skill 安装和客户端配置方法见 [Skill 与 MCP 配置指南](WinCode-Skill制作与MCP配置指南.md)。 - -### 代码导航与连接引导 - -使用 `node C:/path/to/WinCode/dist/index.js --print-connection --workspace C:/path/to/project` 可以输出目标项目的独立 STDIO 配置，不启动其 Gateway、不修改客户端设置。`WORKSPACE_MISMATCH` 也返回同一 `connectionGuide`，包含绝对命令、独立参数和工作区核对调用。配置默认 local-text，不复制已有 Roslyn、开发或托盘选项，目录存在性在实际启动时检查。构建后刷新对应客户端连接，才能使用新工具及 Schema。 - -日常定位用 `wincode_search_text` 的字面量 `query` 和排他的 `scopePaths`；查看文件行数、字节数和声明，用 `wincode_file_outline({file: ...})`。两者都返回可交给 `wincode_prepare_context` 的 `nextRequest`，并指出具体失败文件。它们始终提供本地文本线索；路径、扫描和最终输出预算、取消机制继续生效，零匹配不证明范围外没有相关代码。 - -上下文 `summary` 汇总展示范围、完整/部分/缺失文件数和下一步。EOF 越界报告实际行数，有有效交集时给出修正读取请求，原始覆盖缺口仍保留。UI inspect/review 可显式传 `responseFormat: "compact"`：保留控件 ID、层级、状态及图片，省略节点几何和类名，以 `candidateIds` 共享重复 C# 候选，并通过 `expansionRequests` 重新查询完整控件信息。UI 默认格式仍为 full，统计不自动判定缺陷或绑定原因。 - -### 可选托盘与手动释放内存 +将两个路径替换为实际存在的绝对路径。WinCode 安装目录与目标项目目录可以不同。确保 `node` 位于 `PATH` 中，或将命令改为其可执行文件的绝对路径。 -**自动释放保持关闭**，本版没有 idle 定时器或自动释放开关。Roslyn 加载后会保留，优先保障 Agent 连续工作；确实不再需要时，由你在设置里主动释放。 +使用图形化配置界面时，类型选择 `stdio`，命令填写 `node`，依次添加三个独立参数：`dist/index.js` 的路径、`--workspace`、目标项目路径。即使路径包含空格，也不要为独立参数额外添加引号。默认配置不需要额外环境变量。 -1. 完成 `npm run check` 后，运行仓库内 `tools/WinCode.Tray/bin/Release/net10.0-windows/win-x64/publish/WinCode.Tray.exe --show`。使用已有 .NET 10 Windows Desktop 运行时，不安装服务，不设置 Windows 自启动。 -2. 给需要管理的 MCP 启动参数单独加上 `--tray`，再刷新该 MCP 连接。例如 `"args": ["C:/path/to/WinCode/dist/index.js", "--workspace", "C:/path/to/project", "--tray"]`。已配置 Roslyn 时保留原有 `--roslyn-config` 参数。 -3. 打开“设置 / 内存管理”，刷新状态、选择空闲实例，点击“释放 Roslyn 内存”。实例忙碌或仍在收尾时拒绝本次释放，不排队延后释放；释放开始后到来的请求等待其完成。 +**3. 验证连接并执行首次查询** -只关闭所选实例拥有的 Roslyn Host 并失效旧符号定位；下一次显式搜索才重新加载，旧 `symbolLocation` 必须重新搜索。Gateway、工作区 watcher、现有受限缓存和最后诊断保留。local-text 实例没有 Roslyn 内存可释放。 +连接后，让智能体调用 `wincode_hello_world`，确认 `health.workspaceBinding.root` 与目标项目一致，然后尝试： -“暂无在途请求”不代表 Agent 已结束任务。刷新失败或观察超过 30 秒时显示状态未知；手动释放前先获取新状态，超时不会接着释放。打开、刷新、隐藏设置及托盘重连均不触发 Roslyn 启停。注册失败原因会显示在设置和 Gateway 诊断输出中。 +> 概述项目结构，列出 `src` 目录中的内容，并查找负责保存数据的代码。 -关闭设置窗口会收回托盘；“退出托盘”不影响 MCP。“停止此实例”经确认后请求该 Gateway 正常退出，客户端可能重新建立一个新实例。托盘和 Gateway 可按任意顺序手动启动；每个 Windows 用户/登录会话目前最多连接八个 Gateway，应使用同一用户和权限级别。状态仅在注册、打开或手动刷新时更新，不持续轮询；失联表示未知，连接数不含旧版或未注册实例。移除 `--tray` 并刷新 MCP 连接即可禁用集成。其他权限、Explorer 重启和不同 DPI 仍需单独验证。 +智能体可以使用 `workspace_open` 获取项目摘要，使用 `wincode_list_directory` 浏览目录，再通过 `wincode_search_text` 定位代码。检查 UI 时，先在交互式 Windows 桌面会话中启动目标应用，再参考前面的使用示例。 -### 示例：查看指定控件 +每条连接在其生命周期内固定对应一个工作区。`workspace_open` 用于确认或恢复该工作区，不能切换项目；请求其他根目录会返回 `WORKSPACE_MISMATCH`。访问其他项目时，应使用单独配置的连接。如果省略 `--workspace`，连接将固定到服务器的启动目录。 -大型窗口的控件树可能很长。可以按名称、类型或 automation ID 筛选，只读取需要检查的控件： +客户端配置和可选的智能体 Skill 安装方式见 [Skill 与 MCP 配置指南](WinCode-Skill制作与MCP配置指南.md)。重新构建后，需要重新连接客户端中的 MCP 服务器，才能加载更新后的进程和工具参数定义。 -> **提示词示例：** *“找到我的应用窗口，在后台查看保存按钮的状态，并核对 `Views/MainWindow.xaml` 中的源码声明。”* +### 常用工作流与工具 -1. 调用 `wincode_ui_list_windows`，通过进程名或标题关键字筛选获得目标 `pid` 与 `hwnd`。 -2. 使用 `wincode_ui_inspect` 进行定向检索： +**代码导航：**从已知目录、文件或符号开始。通过 `wincode_search_text` 在 `scopePaths` 指定的范围内按普通字符串搜索，不使用正则表达式；通过 `wincode_file_outline` 查看文件中的声明和行数。两者均提供后续调用 `wincode_prepare_context` 读取源码所需的参数。 ```json { - "pid": 12345, - "hwnd": "0x123456", - "backgroundOnly": true, - "capture": "none", - "query": {"automationId": "SaveButton", "controlType": "Button"}, - "maxDepth": 3, - "maxNodes": 30, - "readStates": true + "task": "核查保存逻辑", + "lineRanges": [{ "file": "src/Service.cs", "startLine": 50, "endLine": 80 }], + "maxTokens": 2000 } ``` -3. 若需要视觉排查，启用 `capture: "annotated"` 获取带编号的高对比度标注截图；若需关联源码，改用 `wincode_ui_review` 并传入 `candidateFiles: ["Views/MainWindow.xaml"]`。 - -可增加 `candidateCodeFiles: ["ViewModels/MainWindowViewModel.cs"]`（1–8 个显式相对 C# 路径）。`codeEvidence` 从 Click/简单 Binding 的字面标识符提供声明、赋值候选及可用于 `wincode_prepare_context` 的限定 `nextRequest`。读取限单文件 256 KiB、总计 1 MiB，最多 40 条线索、200 个匹配，代码元数据最多 16000 JSON 字符并受整体响应预算限制。歧义、未找到和未完成扫描保留；运行时构建身份、DataContext、模板和禁用原因仍未证明。不传此参数时保持原有 XAML 路径。 - -**截图和状态选项：** - -- **按需截图：**`capture: "none"` 只返回结构化 JSON。需要截图时，图片通过独立的 MCP `image` 内容块传输，Base64 内容不放入文本响应。 -- **控件状态：**`readStates: true` 读取勾选、选中和展开/折叠状态，不改变控件。控件未实现相应 UIA 模式时会标记为“不支持”，以便与状态值为 `false` 的情况区分。 -- **后台截图：**`backgroundOnly: true` 使用 `PrintWindow` 截取指定窗口，不激活或还原窗口、不切换焦点，也不会改用屏幕截图。不支持最小化窗口。 +使用搜索结果中的实际路径和行号。通过 `lineRanges` 指定要读取的行号范围，通过 `scopeFiles` 将读取范围限制在指定文件内。`candidateFiles` 仅用于优先搜索候选文件，不排除其他文件。根据返回的行号、`coverage` 和截断信息判断是否需要继续读取。`maxTokens` 设置的是按 UTF-16 字符数估算的 Token 预算，并非具体模型的精确 Token 数。 -### 工具一览 - -本地声明扫描支持 C#/TS/TSX/JS/JSX/Python，有界屏蔽注释、字符串及 JSX；词法边界不确定时报告不完整。引用仍为文本线索。影响分析仅返回一个 JSON 文本块（含一份 formattedReport）；已知工具失败的 JSON 文本与 structuredContent 一致，正常受理的未知工具走 JSON-RPC -32602。 - -默认以 `local-text` 启动，并明确报告语义能力未配置。显式配置直接 Roslyn 后，将搜索返回的完整 `location` 作为 `symbolLocation` 传给引用、影响分析或重构工具，名称使用原结果的简单名称。外部 Serena 启动配置及 namePath 身份已退役；过期快照须重新显式搜索。 - -`wincode_hello_world` 返回启动时固定的实例 ID、构建指纹及当前注册工具定义的 hash。传 `toolName: "wincode_prepare_context"` 可按需查看单个工具参数，与同一连接的 `tools/list` 对照。`npm run build` 生成 manifest；直接运行 `tsc`、产物缺失/失配或源码开发模式会明确报告 `unknown`。构建指纹校验本地产物一致性，不证明发布来源可信；本连接的分析工作区在启动时固定，health.workspaceBinding 返回根及来源。 - -显式 `lineRanges` 的 `coverage` 按最终返回正文计算：请求/完整行数、实际返回区间、未返回区间及原因。尾行只有一部分字符（`endLineComplete:false`）不计完整覆盖；可补取缺口可带有界 `nextRequest`，EOF/缺文件不建议盲重试。明细超预算会记录 `omittedItemCount` 并保留总计。其他请求 `coverage:null`，`taskCoverage` 始终为 null，片段非空不证明整个方法或任务证据充足。`npm run test:tavern-context -- ` 在新 stdio 进程执行显式启动的只读源码验收。 - -重新构建后需在客户端重连 MCP，再核对 hello；仅替换磁盘文件不能更新旧进程或客户端缓存的参数定义。`npm run test:e2e` 用新 stdio 进程、生产编译产物和隔离源码夹具验证同会话契约及目标符号/行范围正文，不代表另一个 Codex 连接、GUI 或真实上游已经验收。 - -更新仓库后，用 `npm run skill:check -- <已安装wincode目录绝对路径>` 核对手册；不一致退出码为 2。明确更新时运行 `npm run skill:sync -- <同一路径>`，先备份再同步四份受管文档，保留其他文件。它不修改 MCP 配置，也不重启连接。 - -2026-09-08 已在当前 Codex 连接上完成 TavernDesk 源码验收：打开工作区返回 3,705 个 UTF-16 字符，目标方法成功定位，223 行请求与真实源码完整一致；512 token 估计预算明确报告仅 9 行完整、第 10 行不完整。这是该实例在当日的验收结果，其他连接仍需单独核对，详见[工作日志](docs/codex_worklog.md)。 - -| 工具名称 | 功能描述 | -| --- | --- | -| `wincode_search_text` | 在排他文件/目录范围内查字面量，返回位置、有界预览和续读请求。 | -| `wincode_file_outline` | 返回单文件实际行数/字节数、有界声明概览和续读请求。 | -| `workspace_open` | 确认或恢复本连接的固定工作区，返回有长度限制的摘要；拒绝其他根目录。 | -| `wincode_list_directory` | 按指定目录浏览，限制条目、深度与整份输出。 | -| `wincode_analyze_workspace` | 解析解决方案结构及 `.sln`/`.csproj` 中声明的项目引用。 | -| `wincode_prepare_context` | 按文件、符号或行号读取代码片段，返回文件路径和行号，并限制输出字符数。 | -| `wincode_find_code_symbol` | 检索代码符号，说明结果来自哪个分析服务，以及查询是否完整。 | -| `wincode_find_references` | 使用返回的符号位置查找引用；Roslyn 可选 `limit` 为 1–1000，默认 100，必须同时提供 `symbolLocation`。两种提供方均支持最终 JSON 字符预算 `maxOutputChars`（2048–32768，默认 8000），保留已知总数，报告实际返回数、截断状态和输出省略项。 | -| `analyze_change_impact` | 评估代码改动可能影响的范围。符号不唯一、查询不完整或未找到引用时，返回 `riskLevel: "UNKNOWN"` 和 `confidence: "UNCERTAIN"`。 | -| `wincode_plan_refactoring` | 根据改动影响，建议修改前需要检查的内容和修改后的验证步骤。 | -| `wincode_safe_move_to_trash` | 校验路径后移入 `trash/` 并记录元数据；移动前取消会停止操作，移动后的收尾即使超时也保留实际 completed/partial 结果。 | -| `wincode_ui_list_windows` | 列出可见顶层窗口，支持按标题或进程名筛选，并限制返回数量。 | -| `wincode_ui_inspect` | 读取控件子树、状态和可选的编号截图。 | -| `wincode_ui_review` | 根据一次 UI 检查结果，返回可能相关的 XAML/C# 代码、行号、哈希及后续读取参数。 | -| `wincode_hello_world` | 被动读取版本、能力及已知状态，不启动探测；主动检查使用 diagnose_project。 | -| `wincode_diagnose_project` | 检查已安装的 .NET SDK、Git 和本地 Windows 环境。 | - -`wincode_analyze_change_impact` 是 `analyze_change_impact` 的别名。详细参数与工作流请参考对应手册：[代码分析](skills/wincode/references/code.md)、[UI 检查](skills/wincode/references/ui.md)、[系统诊断](skills/wincode/references/diagnostics.md)。 - -架构分析只接受整数深度 1–5，返回 `scanComplete`、`omissions` 和输出截断证据。项目发现最多检查 2000 个目录项，树预览最多 500 项；依赖图最多读取 16 个项目描述文件、每文件 64 KiB、合计 256 KiB，入口文件搜索合计最多检查 2000 项。整份报告最多 32768 个 UTF-16 字符。工作区外项目会省略，本工具不求值 MSBuild。 - -Git 探测从工作区外的安装位置取得绝对可执行路径，要求 Git 2.36 及以上，并禁用可执行的 fsmonitor 配置；缺失或查询失败明确为 `unknown`，不报告干净。缓存和回收写入拒绝路径中已有的符号链接/junction。缓存仅管理带版本标记的 WinCode JSON 与保留命名的 overflow；旧版及无法识别的文件保留，不计入受管配额。这些校验不提供对抗并发路径替换的原子沙盒保证。 - -原始参数（含未知字段）按 UTF-8 JSON 限制为 64 KiB。SERVER_BUSY 附 workStarted=false、retryable=true 和容量快照；按需稍后重试，不自动重放或重启 Host。REQUEST_TIMEOUT 包括排队时间，不证明业务尚未执行。health.admission 提供计数与耗时；被动 hello 仅读取最近磁盘观察，显式诊断前磁盘数值为 null。这些限制不能消除 SDK 解析帧的瞬时分配，也不是 RSS 硬上限。 - -### 架构设计与资源管控 - -```text -Coding Agent ── stdio MCP ── WinCode - ├─ 代码适配器：直接 Roslyn / Repomix / 本地文本 - ├─ 工作区分析、上下文提取与影响面分析工具 - └─ FlaUiAdapter ── stdin/stdout JSON ── .NET UIA Helper - └─ 控件树遍历 + 截图渲染 -``` +**UI 检查：**选择窗口，查询相关控件或子树，必要时查找源码候选位置。设置 `responseFormat: "compact"` 后，响应中会保留控件 ID、名称、层级和状态，省略各节点的几何信息和类名；需要坐标或更多细节时使用 `full`。结果中会明确区分不支持读取、未知和 `false` 等状态。 -- **辅助进程清理：**UI 检查在独立的 C# 辅助进程（`tools/WinCode.UIA.Host`）中执行。清理时通过 Windows `taskkill /T` 结束 WinCode 启动的辅助进程及其子进程，被检查的目标应用不在清理范围内。 -- **请求并发：**UI 检查与健康检查共用互斥锁。每条连接固定一个工作区，其他工作区的请求会在修改资源前被拒绝。恢复工作区时，会在超时限制内等待现有请求结束。每个实例最多接受 32 个尚未完成的工具请求，被动 hello 和 `tools/list` 另行共享 4 个名额。适配器互斥锁保持 FIFO 顺序，排队时间计入超时；取消的请求完成清理后才释放名额。 -- **缓存容量与失效：**缓存按工作区命名空间区分，多个实例仍可能共用磁盘目录。序列化数据的默认内存预算为 32 MiB，磁盘清理目标为 128 MiB（含 overflow 文件）；这不是进程 RSS 上限，也不是即时生效的跨进程磁盘配额。local-text 每次在扫描限制内重新读取输入，按内容哈希复用声明解析结果。内置代码打包会检查所选文件的内容后再复用缓存；没有可验证输入清单的 CLI 结果不缓存。读取缓存时核对键与正文摘要、附件大小及 SHA-256；缺失、损坏或缺少校验元数据的旧条目会重建。已返回的附件可能被后续清理删除。文件监听的去抖时间为 150 ms；监听和索引检查会使约 2.5 秒的变更提示缓存失效，但这个提示不能证明源码内容未变，也不能保证监听到了每一次修改。 +**C# 语义分析：**显式启用 Roslyn 后，先搜索符号，再将返回的完整 `location` 作为 `symbolLocation` 传给引用、变更影响或重构工具。工具提示位置已过期时，应重新搜索。默认的 `local-text` 提供基于文本的代码导航，并说明其语义分析限制。 -| UI 检查限制 | 限制与处理方式 | +| 工具 | 用途 | | --- | --- | -| 定向搜索范围 | 默认最多扫描 1,000 个节点（上限 5,000）；候选匹配默认最多 10 个（上限 20）。 | -| 遍历层级约束 | 软限制 2 秒、50 层深度；若底层 Win32 调用发生阻塞，由 Helper 进程全局硬超时机制强制中断。 | -| 控件树文本 | 上限 128 KiB，超出时返回截断原因。 | -| PNG 图像 | 上限 2 MiB；先缩小尺寸，仍超限则省略图片并保留控件树。 | -| 进程管道传输 | 原始字节流上限为 6 MiB。 | -| 截图尺寸 | 总像素不超过 16,777,216，单边不超过 16,384 像素；在分配位图前检查。 | - -`helperPeakWorkingSetBytes` 记录截至响应准备阶段的进程峰值工作集。`treeComplete` 表示控件树是否完整，`propertyIssues` 单独记录不可用或被裁剪的属性。 - -### 使用限制与屏幕提示 - -- **后台截图适用性：**`backgroundOnly: true` 仅支持非最小化窗口且需同时指定 PID 与 HWND。`captureQuality` 在标注前最多采样 1024 个原始像素；suspect-low-variation 表示采样 RGB 各通道范围不超过 3，可能为空图或正常纯色/低对比界面。unknown 也不能证明图片可用。提示保留图像和 UIA，不自动改变截图策略；旧 Host 缺少该字段时按未验证处理。 -- **UIA 支持：**可读取的信息取决于目标应用的 UIA Provider。项目提供 WPF 测试程序；WinUI、WinForms 或自绘控件能返回多少信息，取决于它们的 UIA 实现。 -- **XAML 匹配范围：**仅匹配指定 `.xaml` 文件中的字面量属性声明（`runtimeSourceVerified: false`），不求值动态 Binding、模板或全局资源字典。 -- **项目分析范围：**直接解析 `.sln` 和 `.csproj` 文件，不执行 MSBuild 动态属性计算。使用 Roslyn 需要明确允许项目求值；Repomix 为可选工具。本地文本模式会说明其语义分析限制。 -- **屏幕提示：**UI 检查期间，主屏幕右上角会显示半透明的 `REC / WinCoding` 提示，不抢占焦点。 -- **本地审计记录：**仅记录时间、PID、耗时等结构化元数据至 `%LOCALAPPDATA%/WinCode/logs/ui-audit`。达到 1 MiB 提示清理，达到 2 MiB 拦截新访问以预留结束记录空间。日志不自动删除，支持通过 [检测脚本](scripts/check-ui-audit.ps1) 手动审查。 - -### 打开与浏览工作区 - -`workspace_open({"path":"~/target-project"})` 默认返回紧凑摘要及最多 8 个入口路径，不附带目录树。`maxOutputChars` 默认 8000（范围 2048–32768），约束包含元数据及转义的整份 JSON 文本，不是模型 token 数；示例占位路径须替换为实际绝对路径。项目发现有界，需检查 `projectScanComplete` 和缺口；未统计的文件数量及总大小为 `null`。 - -接下来用 `wincode_list_directory({"path":"src","maxDepth":1,"maxEntries":100})` 只读取需要的目录，核对实际检查/返回条目数、省略和截断。`includeIgnored:true` 可显式访问工作区内通常隐藏的生成目录，工作区外链接仍被拒绝；截断后应缩小目录路径。旧调用方需要树时可传 `workspace_open({"path":"~/target-project","includeTree":true})`，得到有界兼容树，不能恢复原先无总量限制的清单。 - -### 选择代码读取方式 - -调用 `wincode_prepare_context` 时，直接使用已经掌握的位置： - -```json -{"task":"核对保存逻辑","lineRanges":[{"file":"src/Service.cs","startLine":50,"endLine":80}],"maxTokens":2000} -``` - -已知行号用 `lineRanges`；只需声明及附近上下文时用 `scopeFiles` 加 `symbol`，预算裁剪前为 24 行窗口。审核已知方法的异常处理、取消或资源释放时，若已有文件读取工具，优先结合有界 `rg` 上下文一次读到所需分支。小文件也可用 `scopeFiles` 加 `includeFullText:true` 在预算内读取正文。仅知道文件时用 `scopeFiles` 预览。需要发现候选之外的文件时再用 `candidateFiles`，它仍然是优先列表，不是排他范围。限定范围的符号定位目前使用 C#/TS/JS/Python 本地声明模式，会明确保留语义不完整、重名和缺失提示。 - -默认 `compact` 返回一个 JSON 文本块；`responseFormat: "legacy"` 返回 JSON 加 Markdown。`maxTokens` 接受 512–65536，通过全部返回文本（含元数据）的 UTF-16 字符数除以四估算 Token 数。结合实际行号、`queryComplete`、截断信息和 `bodyStatus` 判断是否还需要读取更多代码。文件修改或更换连接后应重新读取，因为源码可能在两次调用之间发生变化。基准测试中的复用策略不属于生产缓存功能。参数组合与限制见[代码手册](skills/wincode/references/code.md)。 - -### 本地开发与测试验证 - -[CI 工作流](.github/workflows/ci.yml) 在 PR 和 main 推送时使用 `windows-2025` runner、Node.js 22/24 和 .NET SDK 10.0.303。两项任务都执行 `npm run check`，包括使用锁定依赖构建、核心回归测试、stdio 集成测试和交付校验；报告有输出限制，失败时也会保存。只有 Node 22 追加共享缓存、错误与恢复、实际 Roslyn、进程清理、手动释放、SDK 并发和设计时隔离测试。因此两项任务的总耗时不能用于比较 Node 运行时性能。每项任务的超时时间为 20 分钟，交互式桌面/UI 测试另行执行。main 分支保护要求 Node 22/24 和三项 CodeQL 检查通过；单维护者策略不要求审核批准。详见[贡献指南](CONTRIBUTING.md)。 +| `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_review` | 检查 UI 并返回 XAML/C# 源码候选位置。 | +| `wincode_hello_world` | 读取实例身份、工作区绑定、能力及已知状态。 | +| `wincode_diagnose_project` | 主动检查 SDK、Git 和本地环境。 | + +`wincode_analyze_change_impact` 是 `analyze_change_impact` 的别名。详细参数与工作流见 [代码分析手册](skills/wincode/references/code.md)、[UI 检查手册](skills/wincode/references/ui.md) 和 [诊断手册](skills/wincode/references/diagnostics.md)。如需查看当前连接中某个工具的参数定义，可将工具名作为 `toolName` 传给 `wincode_hello_world`。 + +### 可选配置 + +- **Roslyn：**在启动参数中添加 `--roslyn-config` 及配置文件的绝对路径，以启用 C# Code Host。启用前需要明确授权进行 MSBuild 项目评估。配置方式、输入跟踪与恢复流程见 [代码分析手册](skills/wincode/references/code.md)。 +- **连接配置生成：**运行 `node C:/path/to/WinCode/dist/index.js --print-connection --workspace C:/path/to/project`，可生成对应项目的 stdio 配置，不启动 Gateway，也不修改客户端设置。生成结果采用默认的 local-text 配置；Roslyn 或托盘选项需要单独添加。 +- **托盘与内存管理：**为 Gateway 添加 `--tray` 参数并重新连接，然后手动运行 `tools/WinCode.Tray/bin/Release/net10.0-windows/win-x64/publish/WinCode.Tray.exe --show`。在“设置 / 内存管理”中选择空闲实例，点击“释放 Roslyn 内存”。下一次显式符号搜索会重新加载项目，旧的符号位置随之失效。自动空闲释放处于禁用状态；退出托盘不会停止 MCP。详见 [诊断手册](skills/wincode/references/diagnostics.md)。 +- **智能体 Skill：**更新 WinCode 后，可运行 `npm run skill:check -- ` 检查已安装的 Skill。运行 `npm run skill:sync -- ` 会备份并更新由同步脚本管理的 Skill 文档，不会修改 MCP 配置或重启连接。 + +### 适用范围与限制 + +- **桌面访问：**UI 检查为只读操作，不点击控件、不输入文本，也不读取输入框的值。后台模式需同时指定 PID 和 HWND，仅支持未最小化的窗口，检查过程中不激活或还原目标窗口。该功能需要交互式 Windows 桌面会话，不支持在无头环境（Headless）中运行。 +- **UIA 与视觉效果：**可读取的属性取决于目标应用的 UIA 提供程序。项目的桌面测试覆盖 WPF，其他框架和自绘控件可能提供较少的信息。颜色、图标和渲染质量需要结合图像检查。后台截图使用 `PrintWindow`，不回退到屏幕截图；应检查返回的截图质量提示。 +- **源码映射：**XAML 和 C# 的匹配结果提供了可能相关的源码位置，`runtimeSourceVerified` 为 `false`。工具不验证运行版本与源码是否一致，不解析动态绑定或运行时模板，也不确定当前的 `DataContext`。 +- **分析范围：**项目结构分析仅静态读取 `.sln` 和 `.csproj` 中的声明，不进行 MSBuild 项目评估。文本引用搜索采用启发式方法。应结合完整性、省略项和诊断信息判断结果；在有限范围内未找到匹配，并不代表整个项目中不存在匹配内容。 +- **资源限制：**请求数量、遍历范围和响应大小均有限制。超过处理容量时返回 `SERVER_BUSY`，排队时间计入超时。输出限制不等于进程内存上限。并发、缓存与进程生命周期的详细说明见 [架构文档](WinCode-架构与数据流说明.md)。 +- **检查提示：**检查期间会显示半透明的 `REC / WinCoding` 状态浮层（Overlay），不会获取键盘焦点。同时，将最小必要的审计元数据记录到本地目录 `%LOCALAPPDATA%/WinCode/logs/ui-audit`。审计日志维护方式见 [诊断手册](skills/wincode/references/diagnostics.md)。 + +### 开发与文档 + +当前源码版本为 **0.15.0**。版本历史和迁移说明见 [CHANGELOG](CHANGELOG.md)。项目以 Windows 11 x64 为基准平台，移植至其他操作系统需要适配并单独验证。 ```powershell -npm ci -npm run check # 锁定构建、核心回归、stdio 和交付清单 -npm run check:desktop # 隔离 WPF、UI 与 UI→源码；需要交互式 Windows -npm run delivery:verify # 检测 Gateway、Host/依赖文件、受管 Skill 缺失或变化 -npm run test:inventory # 核对每个 *.test.ts 均被明确归入套件 -npm run test:all # 同时执行 check 与 check:desktop -npm run benchmark:agent -- 1 # 显式小样本；三轮对照使用 -- 3 +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 # 执行一轮可选的脚本化基准测试 ``` -实机 UI 测试需要交互式 Windows 桌面会话。此前在包含 222 个节点的测试程序中，按条件查询使返回文本从 62 KB 减少到约 1.6 KB，单次耗时约 0.78 秒。测试记录见[工作日志](docs/codex_worklog.md)。 - -`npm run test:product -- <专用测试PID> ` 显式运行六项导航到源码任务，要求固定测试 profile 已启动。它发现候选文件、核对实际控件及命令/方法文字候选，将原生和 MCP 调用、返回字符、重复源码行写入 `test-tmp/product-tasks`；不启动应用、不修改数据或源码。此脚本验收不证明运行时绑定、完整方法覆盖、相对纯原生工具提速或语义完整性；详见工作日志验收矩阵。 +[CI](https://github.com/linnnn89/WinCode/actions/workflows/ci.yml) 在 Windows 环境中使用 Node.js 22、24 和固定版本的 .NET SDK 运行。在 Node.js 22 的任务中，还会额外执行原生组件与集成检查；桌面测试单独运行。基准报告记录脚本化场景中的调用次数、响应大小和执行时间，具体测试条件及结果见以下文档。 -Agent 基准包含 10 类脚本场景，复用现有 `dotnet-mini` C# 夹具，并按四种初始位置信息分层。返回的文件、行号、正文及状态均与当前夹具核对；工具错误、传输异常、响应损坏和清理失败会保留在 `test-tmp/agent-efficiency` 下的 JSON 报告中，失败返回非零退出码。无变化复用只在夹具写入受控、变化事件可信的条件下测试，修改后必须重新请求。测量使用本地回退，关闭上游与 GUI，记录 MCP 调用、返回字符、重复显示行和调用耗时，不代表真实 Agent 完成率、模型 Token 节省或生产缓存收益。Schema v2 场景与旧版六场景报告不同，不能直接比较两版总量。 +- [贡献指南](CONTRIBUTING.md)：构建、测试套件和交付要求。 +- [架构与数据流](WinCode-架构与数据流说明.md)：组件、接口、资源限制和生命周期管理。 +- [Skill 与 MCP 配置指南](WinCode-Skill制作与MCP配置指南.md)：安装与客户端配置。 +- [工作记录](docs/codex_worklog.md) 与 [后续测试计划](WinCode-下一轮工程化迭代计划书.md)：历史验证结果、已知问题和待验证事项。 --- diff --git a/docs/codex_worklog.md b/docs/codex_worklog.md index 4d9a953..e2f6c21 100644 --- a/docs/codex_worklog.md +++ b/docs/codex_worklog.md @@ -1383,3 +1383,11 @@ - 回归先确认旧实现会丢失移动结果/取消信号/引用总数，以及最终 JSON 超预算。实现后定向验证通过：真实临时文件移动与取消、真实 Roslyn Host 的 120 处引用、长路径和转义预览、候选身份及必要元数据边界。本轮累计新增 5 个测试，分属两次授权的局部任务（3 个及 2 个）；没有放宽原有超时或断言。 - 最终完整 `npm run check` 460/460、0 失败、0 跳过，类型检查、Gateway/原生构建、生产 stdio 和交付核验通过。报告：`test-tmp/check/2026-09-11T13-13-40-686Z-core/report.json`；交付 contentId=`7d04eb319ef210868f25ece81496aaaad184e456a2ec3d302a8593e8923537f3`。错误契约 17/17：`test-tmp/error-contracts/run-bAbdGe/report.json`。 - 自查及本地验证不等同于独立审查；最新 PR 提交仍须通过 Node 22/24 和三项 CodeQL 后再合并。未重新执行无关桌面验收，也未同步已安装 Skill 或重连当前 Codex MCP；本地构建完成不证明活动客户端已更新。 + +## 2026-09-11 — 重组并润色中英文 README + +- 用户要求突出后台 UI 检查、纯文本大语言模型支持，以及实际使用中相比基于截图的 Computer Use 更快、更准确的体验；随后要求规范中英文术语、结合 Gemini 建议润色，并提交 PR 合并。 +- README 按核心功能、使用示例、快速开始、常用工作流、可选配置、适用范围和开发文档重新组织。增加禁用按钮的 UI 与源码联合分析示例，前置推荐的固定工作区配置，将详细历史与内部机制改为现有文档链接。保留后台操作、UIA、源码候选和视觉检查的实际适用范围。 +- 调整中文语序、动宾搭配和链接间距，同步英文。依据微软文档使用“MSBuild 项目评估”，将 rollForward=disable 解释为 SDK 版本须完全匹配；字符串搜索和 Skill 同步说明保持现有接口含义。Computer Use 比较保留为日常开发体验，222 节点窗口的 62 KB/1.6 KB 数据来自既有测试记录。 +- 文档验证通过：10 个本地链接、6 个 JSON 示例、4 个工具调用示例的当前源码 Schema 校验、7 个 npm 命令和 16 个工具名称；中英文工具列表与对应配置一致，git diff --check 通过。未发现文档验证失败；没有修改生产代码、依赖或受管 Skill，也没有新增测试或重新运行运行时测试。 +- 本条按 CONTRIBUTING 的合并要求追加。最新提交的 Node 22/24 与三项 CodeQL 仍待远端检查；本地自查不等于独立审查或活动客户端验收。