# 续接入口：DSH Windows Computer Use

## 当前阶段

`0.1.0-preview.1`：由上游 0.4.3 派生，迁移到 C# + TypeScript。原代码归档到 `upstream/`，新版运行时不调用 PowerShell。

## 目录

| 目录 | 用途 |
|---|---|
| `src/Engine/` | C#：Win32、UIA、内存截图、Windows OCR、输入、独立 Esc 线程 |
| `src/adapter/` | TypeScript：官方 MCP SDK、DSH 桥接、用户轮次、客户端说明卡片 |
| `tests/` | 新版协议、专用真实窗口与取消测试 |
| `scripts/` | 构建、打包、来源 schema 导入工具 |
| `native/`、`dist/` | 构建产物，不提交 |
| `artifacts/` | 测试与插件包产物，不提交 |
| `upstream/` | 原始来源归档，不参与运行 |

## 常用命令

```powershell
npm ci
npm run build
npm test
npm run package:local
```

构建要求 .NET 10 SDK、Node ≥22。SDK 不在 PATH 时用 `DOTNET_EXE`；构建脚本也识别当前机器的独立 SDK 安装目录。

## 核心约束

- stdout 只用于 JSON 协议；诊断输出到 stderr。
- 先观察再输入；以 HWND+PID 核对目标，元素引用限当前引擎实例、有效期两分钟。
- 坐标操作检查窗口边界、位置和遮挡。窗口移动后需重新观察，不猜测坐标补偿。
- 单工作进程串行操作；命名互斥防止本项目多个进程同时操作桌面，不约束其他控制软件。
- Esc/取消阻止当前轮继续；DSH 轮次由宿主注入，模型不能通过工具参数伪造新轮次。
- 按键和鼠标释放放在 finally；超时不自动重放输入。
- 截图不默认写盘。测试只操作本次创建的专用窗口，产物不得包含用户桌面或凭证。

## 验证

新测试的权威入口是 `npm test`，归档测试仅作参考。真实窗口测试核对中文输入回读、按钮点击后的标签变化、截图坐标、OCR、密码隐藏、陈旧目标拒绝、互斥、取消、Esc 和关闭。DSH 的协议/宿主接入需要单独验证，不以编译成功替代宿主运行。

本机第一版已通过 19 项测试。额外安装验证：设置进程级 `DSH_DESKTOP_EXE` 为已安装的 Desktop EXE，执行 `node scripts/verify-dsh-package.mjs`。它只创建 `work/isolated-dsh`，验证包安装、bundle 启用、配置合成和 24 个工具的官方桥接；不修改实际 profile。不要使用 PowerShell 对 GUI EXE 的即时返回作为测试通过证据，脚本已用 spawnSync 等待真实结果。

对外项目名统一为 `dsh-windows-computer-use`，中文名为“DSH Windows 电脑控制插件”；GitHub topic 与 package keywords 包含 dsh-plugin、computer-use、Windows。公开仓库不是插件市场自动收录，npm 未发布时不得宣称能按 npm 包名直接安装。

## 维护注意

- `origin` 应指向 shinji00222 的独立仓库；`upstream` 保留原作者地址，禁止向其直接推送。
- 原始 MIT 声明、NOTICE 和来源历史必须保留。
- 不覆盖正在运行的 DSH 配置；新版先在独立宿主验证，实际安装另作明确操作。
- 预览版尚无后台输入/WGC；已知边界写在 README，禁止在描述中声称上游全量兼容。

## 下一步

续验已补齐隔离 DSH 官方桥接的真实中文输入与回读，入口仍为 `scripts/verify-dsh-package.mjs`。曾出现一轮前台激活和 Esc 失败，随后原样连续四轮通过；原因未定，详见 `docs/verification.md`，后续复发时保留现场并检查交互桌面与焦点，不通过放宽断言掩盖失败。

按真实应用回归结果补充兼容性；优先完善跨轮操作追踪与证据展示，再考虑后台输入、WGC 和更丰富的设置界面。