feat: 按需启动并复用 Skill MCP 会话

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 0.15.0 (unreleased)
 
+- Add an optional Skill-managed session using the existing MCP client SDK and a persistent interactive terminal. Start the Gateway on the first tool call, validate workspace/build/provider, reuse the connection and Roslyn snapshot, preserve complete MCP results as local JSON/image attachments, and close owned resources explicitly or on owner exit. Disable the client's native WinCode MCP entry to prevent its automatic startup; no automatic retry/reconnection, new service or dependency is introduced.
 - Preserve completed/partial trash outcomes and actual file locations when the request deadline expires during metadata finalization. Propagate cancellation before the move and keep interruption accounting; client cancellation or disconnection still does not guarantee delivery of a final response.
 - Add optional Roslyn reference `limit` (1–1000, default 100, requires `symbolLocation`). Impact reports retain `totalReferences` and `referencesTruncated` alongside the existing returned `referencesCount`; unknown totals remain null and semantic risk/coverage rules stay unchanged.
 - Bound reference-tool replies by final formatted JSON size with `maxOutputChars` (2048–32768, default 8000). Preserve known totals and exact identities, report returned counts and omitted lists, and reject budgets that cannot hold required metadata. The output limit covers both providers and does not bound Roslyn search work or change internal impact aggregation.

CONTRIBUTING.md

@@ -17,6 +17,8 @@ Reports and bounded stage logs are under `test-tmp/check/<run>/`. CI retains the
 
 `npm run test:roslyn-host` and `npm run test:roslyn-gateway` use generated C# projects and an already installed SDK selected by `scripts/lib/dotnet.mjs`. The gateway check copies the entire published Code Host into a Chinese path with spaces and checks real overloads, stale identities and owned MSBuild descendants. This is not a clean-machine test or verification of the current Codex connection.
 
+`tests/skill-session.test.ts` covers the optional persistent Skill client in three scenarios: no Gateway before a call, connection/result preservation, real Roslyn snapshot reuse and invalidation, and cancellation followed by owner death during actual MSBuild work. It uses generated projects with offline restore against the installed SDK and observes process IDs plus creation times. Codex terminal integration must also use `tty:true` and read the result-file receipts; a pipes-only test does not prove that workflow or a refreshed desktop configuration.
+
 Windows CI jobs have a 20-minute overall budget for cold setup and native acceptance. Node 22 runs shared-cache checks early, then gives SDK concurrency and design-time output ownership separate steps. Design-time readiness uses the production Roslyn load budget of 120 seconds; it does not impose an additional cold-start performance target. Production request deadlines remain unchanged.
 
 `npm run test:owner-death` kills only a generated Gateway during confirmed initial MSBuild work and checks all previously observed process identities for survivors. `node scripts/verify-owner-death.mjs --repomix` audits the actual adapter with a controlled Node CLI, without installing Repomix. `check:desktop` also runs the `--desktop` owner-death scenario against the isolated WPF fixture: the UIA Helper must exit while the target remains alive; the fixture is closed separately after recording that result. Reports are kept under `test-tmp/owner-death/`. These checks never identify client applications by process name.

README.md

@@ -76,6 +76,8 @@ Running `npm run check` builds the Gateway and native components, runs core regr
 
 **2. Configure the MCP connection**
 
+For Codex with persistent terminal support, the [Skill on-demand mode](skills/wincode/references/diagnostics.md#skill-按需会话) starts WinCode only when needed and reuses one connection throughout the task. Install the Skill, disable the native WinCode MCP entry, and refresh the client connection before using this mode. The Skill starts `dist/Client/SkillSessionCli.js` in an interactive execution session; results remain available as full JSON and image files. It requires an extra file read per result. Other clients can use the native stdio configuration below.
+
 For clients that support `mcpServers`, add the following stdio configuration. Explicitly setting `--workspace` is recommended:
 
 ```json
@@ -242,6 +244,8 @@ npm run delivery:verify
 
 **2. 配置 MCP 连接**
 
+支持持久终端的 Codex 可使用 [Skill 按需模式](skills/wincode/references/diagnostics.md#skill-按需会话)：首次需要时才启动 WinCode，任务内复用同一连接。先安装 Skill、禁用原生 WinCode MCP 条目，并刷新客户端连接。Skill 通过交互执行会话启动 `dist/Client/SkillSessionCli.js`，完整结果保存为 JSON 和图片文件，每次结果需要额外读取文件。其他客户端可使用下列原生 stdio 配置。
+
 对于支持 `mcpServers` 的客户端，添加以下 stdio 配置。建议显式设置 `--workspace`：
 
 ```json

WinCode-Skill制作与MCP配置指南.md

@@ -1,10 +1,10 @@
 # WinCode Skill 安装、维护与 MCP 配置指南
 
-适用于 **0.15.0**，核对日期 2026-09-10（北京时间）。以下使用本机 `I:/WinCode` 路径举例；其他机器必须替换路径。客户端界面名称随版本变化，以实际界面为准。
+适用于 **0.15.0**，核对日期 2026-09-12（北京时间）。以下使用本机 `I:/WinCode` 路径举例；其他机器必须替换路径。客户端界面名称随版本变化，以实际界面为准。
 
 ## 1. 三个独立对象
 
-- **Skill 手册**指导 Agent 选择工具和使用规范字段，不启动服务器。
+- **Skill 手册**指导 Agent 选择工具和使用规范字段；被发现或读取不启动服务器。按需模式由 Agent 首次需要时执行随产品交付的会话入口。
 - **磁盘交付物**包含 Gateway、原生 UIA/Code Host 及可选 Tray 的完整发布目录、构建身份和交付清单。
 - **MCP 连接实例**是客户端已经启动的进程；更新源码、构建或复制 Skill 都不会自动更新这个进程。
 
@@ -42,7 +42,17 @@ npm run skill:check -- C:/Users/40218/.agents/skills/wincode
 
 **未知字段保持容忍，但不会生效。** 参数名称、大小写、类型和范围以手册字段表为准。例如 `automationId` 是规范字段，`automationID` 不会成为筛选条件；仅含未知字段的 query 仍缺少必需条件。适配器配置字段不能伪装成 MCP 请求参数。
 
-## 4. 注册 stdio MCP
+## 4. 选择启动方式
+
+### Codex 按需模式
+
+先构建并同步 Skill，再按[会话手册](skills/wincode/references/diagnostics.md#skill-按需会话)用持久交互终端验收连续查询和关闭。通过后，在 Codex `config.toml` 原有 `[mcp_servers.wincode]` 段内设 `enabled = false`，保留 `command/args` 等配置，刷新客户端连接；已运行进程不会因保存配置自行消失。禁用原生条目后，Codex 启动不再因该条目创建 WinCode。
+
+Skill 首次使用启动 `dist/Client/SkillSessionCli.js --workspace <当前项目绝对路径>`；终端须保留 stdin（Codex `exec_command` 使用 `tty:true`）。任务内复用返回的执行会话 ID，工具参数不变，完整结果通过回执中的文件读取。任务收尾显式关闭；不会每次查询重启 Host，也没有额外常驻服务或自动重连。Roslyn 配置须明确匹配目标项目。恢复原生模式时关闭按需会话，把原配置的 `enabled` 恢复为 `true` 后刷新客户端。
+
+此模式依赖客户端执行工具能保留交互会话；不支持时使用下方原生配置。结果文件包含实际源码/截图，保存在安装目录 `test-tmp/skill-sessions/`，不会随连接关闭自动删除。Skill 同步脚本不会替用户切换模式。
+
+### 原生 stdio MCP
 
 在客户端添加 stdio 服务器，分别填写：
 

WinCode-下一轮工程化迭代计划书.md

@@ -1,13 +1,15 @@
 # WinCode 后续测试计划
 
-更新：2026-09-11（北京时间）。当前版本为 **0.15.0**，已验证的 main 基线为 `631f8ba`。版本和 CI 状态见 [README](README.md)，实现方式见[架构说明](WinCode-架构与数据流说明.md)，历史结果见[工作日志](docs/codex_worklog.md)。
+更新：2026-09-12（北京时间）。当前版本为 **0.15.0**；按需会话改动基于 `af9c1b6`。版本和 CI 状态见 [README](README.md)，实现方式见[架构说明](WinCode-架构与数据流说明.md)，历史结果见[工作日志](docs/codex_worklog.md)。
 
 固定工作区、保持已加载的 Host、请求数量限制、独立的设计时输出目录、共享缓存回归，以及 PR #40/#41 的代码导航、UI 精简输出和测试修正已合并，Node 22/24 和 CodeQL 检查通过。后续本地验收已完成 TavernDesk 的 8 个上下文场景、6 个 UI 产品任务、两个独立 Gateway 的审计争用及恢复，以及实际 Codex 连接中的单项目 Roslyn 流程。对应 PR 的交付状态见工作日志；这些测试完成项从待办移除，不扩大为所有项目或所有 UI 环境均已验证。
 
 ## 待完成的测试与问题排查
 
 | 事项 | 已知情况 | 下一步 |
 | --- | --- | --- |
+| 已安装 Codex 的冷启动确认 | Skill 按需入口已通过真实终端连续 Roslyn 查询、关闭和所属进程退出；Node 22.23.2 与 24.19.0 本地核心回归均为 462 通过、1 项可选夹具跳过。Node 24 已在 I:/New-tarven 完成后台 UI 和真实图片附件验证，Node 22 补验了该项目的实际终端声明/引用流程。原生 wincode 已设 enabled=false，已安装 Skill 四文件一致 | 正常刷新/重新启动 Codex，确认未调用时没有新建 WinCode 进程。当前任务未重启宿主；保存配置不会清除旧连接。Node 22 证据见 test-tmp/node22-validation/report.json |
+| Tavern 的 Roslyn 语义覆盖 | 本地 App 项目 Release/net10.0-windows 快照正确返回导航声明及两处引用，并跨 UI 调用保持身份；同时排除 24 个分析器/生成器，报告 CS8795 和部分 Microsoft.Data/Microsoft.ML 的 CS0234。源码正常构建/隔离启动不能消除这些设计时诊断 | 如需扩大到完整项目语义，先核对设计时项目引用、TFM 和依赖解析，再区分生成器策略造成的缺口；当前维持 incomplete，不根据局部零引用判断删除安全。证据：test-tmp/tavern-skill-JNZ7Wu/report.json |
 | UI 和托盘的间歇性失败 | PR #41 将真实端点启动检查移到顺序阶段，main 两个 Node 版本均通过，3000 ms 生产超时未变；隐藏/唤出、截图/提示窗及原生启动延迟的根因仍未全部定位 | 再现时保存错误码、原生日志和步骤耗时，再针对原因修复；不把调度修正及重跑通过称为已解决所有 UI/托盘问题 |
 | SDK 突发请求警告 | main 的 128 请求阶段仍记录 11 个 drain 监听器警告，阶段结束后为 0；此次实际客户端连续查询未出现调用失败，但未采集该客户端的监听器统计 | 若普通负载也出现问题，再检查发送背压及监听器释放。不提高监听器上限来隐藏警告，也不据此认定内存泄漏 |
 

WinCode-架构与数据流说明.md

@@ -41,9 +41,12 @@ flowchart TB
 
 图中箭头表示主要调用或数据联系，不表示每条请求都经过全部组件。原生 Host 的进程隔离用于故障与生命周期控制，**不等于操作系统安全沙盒**。
 
+Codex 可选择 Skill 按需入口：首次使用才创建交互执行会话，`SkillSessionCli` 使用现有 MCP SDK 连接上图中的 Gateway，后续查询复用同一连接。入口启动或读取本地状态不会创建 Gateway；首次工具请求完成工作区、构建和提供方核验后才派发业务。完整 MCP 结果和原始图片作为本地附件交付，入口不重写工具契约或自动重放请求。关闭/所属入口死亡沿用 Gateway 与原生 Host 的清理链路。该模式需禁用客户端自动启动的 WinCode 条目，不能通过 Gateway 内部延迟初始化实现客户端侧零进程；使用方法见 [Skill 会话手册](skills/wincode/references/diagnostics.md#skill-按需会话)。
+
 | 层 / 模块 | 负责什么 | 设计边界与源码入口 |
 |---|---|---|
 | 启动层 | 解析 workspace/development 参数，创建 Router 和 MCP Server，处理退出 | [index.ts](src/index.ts)；当前入口以默认配置和 CLI 参数启动，不是通用配置中心 |
+| 可选 Skill 客户端 | 按需连接、任务内复用、附件交付与显式关闭 | [SkillSession](src/Client/SkillSession.ts)、[SkillSessionCli](src/Client/SkillSessionCli.ts)；运行于持久执行会话，不注册第二个 MCP 服务器或常驻服务 |
 | Gateway | 列举工具、校验输入、执行工具、封装结果 | [McpServer](src/Gateway/McpServer.ts)、[ToolRegistry](src/Gateway/ToolRegistry.ts)；不直接调用适配器字段 |
 | ToolRouter | 创建并组合组件，提供用例入口，协调请求与工作区生命周期 | [ToolRouter](src/Core/ToolRouter.ts)；这是装配与协调中心，不只是名称路由表 |
 | 核心能力契约 | 定义符号、引用、打包、UI、操作取消等数据类型 | [CodeQueries](src/Core/CodeQueries.ts)、[ContextPacking](src/Core/ContextPacking.ts)、[UiContracts](src/Core/UiContracts.ts)、[OperationContext](src/Core/OperationContext.ts) |