# Go MCP 与 C# Windows Helper 边界设计

## 1. 目标

最终程序分成两层：

```text
MCP Client
  -> Go MCP Server
  -> C# Windows Helper
  -> 已登录的 iSphere / IMPlatformClient 窗口
```

当前阶段提前固定 Go 与 C# 之间的边界；Go MCP 主程序和真实搜索、发送、文件操作进入后续节点。

第一阶段的实际目标是：用 C# helper 探测已登录客户端窗口结构，并把窗口和 UI Automation 控件树以稳定 JSON 返回给未来 Go MCP 服务。

## 2. 当前阶段范围

当前阶段只定义 Go 与 C# helper 的分工：Go 负责 MCP 服务层，C# helper 负责 Windows 桌面/UIA 执行层。真实联系人、群组、消息、文件能力进入 `docs/mcp-core-tools-contract.md` 的核心工具路线。


## 3. 分工原则

### 3.1 Go MCP Server

Go 是对外服务层，负责：

- MCP 工具注册。
- 参数校验。
- 调用 C# helper。
- 控制超时。
- 解析 helper JSON 输出。
- 工具执行策略。
- 执行审计记录。
- 把 helper 结果整理成 MCP 返回值。

Go 通过 helper 获取窗口结构和执行结果，iSphere 控件细节由 C# helper 封装。

### 3.2 C# Windows Helper

C# 是 Windows 执行层，负责：

- 枚举桌面窗口。
- 找疑似 iSphere / IMPlatformClient 窗口。
- 读取指定窗口的 UI Automation 控件树。
- 后续在 selector 稳定后执行少量受控窗口动作。

C# 保持 Windows helper 定位，只返回 Go 请求的 helper 结果。

## 4. 进程模型

第一阶段采用一次性 CLI 模型：

```text
Go 启动 C# helper
Go 通过 stdin 写入一个 JSON 请求
C# 执行一个 op
C# 通过 stdout 返回一个 JSON 响应
C# 退出
```

原因：

- 简单。
- 易测试。
- 默认一次一进程，便于调试和替换。
- 联系人、消息、文件路径通过 stdin JSON 传入，命令行参数保持简单。
- 后续需要提速时，再评估长连接。

标准约束：

- stdout 只能输出 JSON 响应。
- stderr 可输出诊断信息。
- exit code 非 0 表示 helper 进程级失败。
- 业务失败用 JSON 中的 `ok:false` 表达。

## 5. Helper JSON Contract v1

协议名固定为：

```text
isphere.helper.v1
```

### 5.1 请求格式

```json
{
  "protocol": "isphere.helper.v1",
  "request_id": "uuid-string",
  "op": "scan_windows",
  "timeout_ms": 5000,
  "args": {}
}
```

字段说明：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `protocol` | 是 | 固定 `isphere.helper.v1` |
| `request_id` | 是 | Go 生成，用于关联请求和响应 |
| `op` | 是 | 操作名 |
| `timeout_ms` | 否 | Go 和 C# 都应尊重的超时 |
| `args` | 是 | op 参数 |

### 5.2 成功响应

```json
{
  "protocol": "isphere.helper.v1",
  "request_id": "uuid-string",
  "op": "scan_windows",
  "ok": true,
  "data": {},
  "error": null,
  "warnings": []
}
```

### 5.3 失败响应

```json
{
  "protocol": "isphere.helper.v1",
  "request_id": "uuid-string",
  "op": "scan_windows",
  "ok": false,
  "data": null,
  "error": {
    "code": "WINDOW_NOT_FOUND",
    "message": "no matching iSphere window found"
  },
  "warnings": []
}
```

第一版错误码只保留：

```text
INVALID_REQUEST
UNSUPPORTED_OP
HELPER_FAILED
TIMEOUT
WINDOW_NOT_FOUND
AMBIGUOUS_WINDOW
UIA_DUMP_FAILED
```

后续真实动作阶段再增加：

```text
SELECTOR_NOT_FOUND
APP_NOT_LOGGED_IN
APP_BUSY
WRITE_NOT_READY
VERIFY_FAILED
```

## 6. 第一阶段 op

第一阶段只支持四个 op。

### 6.1 `version`

用途：确认 helper 可运行，返回协议版本、程序版本、运行时信息。

请求：

```json
{
  "protocol": "isphere.helper.v1",
  "request_id": "...",
  "op": "version",
  "args": {}
}
```

响应 data 示例：

```json
{
  "helper_name": "ISphereWinHelper",
  "helper_version": "0.1.0",
  "protocol": "isphere.helper.v1",
  "runtime": ".NET Framework"
}
```

### 6.2 `self_check`

用途：检查 helper 是否能访问当前桌面、UI Automation 是否可用。

响应 data 示例：

```json
{
  "desktop_access": true,
  "uia_available": true
}
```

### 6.3 `scan_windows`

用途：枚举当前桌面窗口，返回疑似 iSphere / IMPlatformClient 候选。

args 示例：

```json
{
  "include_all_visible": false
}
```

响应 data 示例：

```json
{
  "windows": [
    {
      "hwnd": "0x001A0B2C",
      "pid": 1234,
      "process_name": "IMPlatformClient",
      "title": "iSphere",
      "class_name": "WindowsForms10.Window.8.app.0.xxxxx",
      "visible": true,
      "bounds": {
        "x": 100,
        "y": 80,
        "width": 1200,
        "height": 800
      },
      "score": 90
    }
  ]
}
```

### 6.4 `dump_uia`

用途：对指定窗口导出 UI Automation 控件树。

args 示例：

```json
{
  "hwnd": "0x001A0B2C",
  "max_depth": 8,
  "include_text": true
}
```

响应 data 示例：

```json
{
  "hwnd": "0x001A0B2C",
  "root": {
    "name": "iSphere",
    "control_type": "Window",
    "automation_id": "",
    "class_name": "WindowsForms10.Window.8.app.0.xxxxx",
    "children": []
  }
}
```

第一阶段 Go 可以把该响应保存到：

```text
runs/real-loggedin-lab/uia-dumps/
```

C# helper 文件输出通过未来 `out_path` 参数控制。

## 7. 后续 op 扩展顺序

必须等真实登录窗口的 UIA dump 被确认后，再扩展真实动作。

建议顺序：

```text
search_contacts
open_conversation
read_latest_messages
write_draft
send_message
send_file
receive_file
```

其中：

- `search_contacts`、`open_conversation`、`read_latest_messages` 是后续核心工具候选 op。
- `write_draft` 用于构造待发送内容。
- `send_message`、`send_file`、`receive_file` 归入核心 MCP 工具路线。

## 8. 写入与审计接口

Go 负责把业务工具请求转换成 helper op，并记录目标、内容摘要、文件摘要、时间、连接器和执行结果。C# helper 只执行 Go 发来的单次 op，并返回可核验结果。

## 9. 部署形态

helper 保持普通企业辅助工具形态：普通命令行程序、普通安装路径、固定名称、可构建、可签名、可替换。正式部署关注安装路径、版本、日志和运维可见性。

## 10. 建议目录结构

当前以规划为主，目录按节点逐步创建。

Go 侧未来结构：

```text
go/
  cmd/
    isphere-mcp/
      main.go
  internal/
    mcpserver/
      server.go
    tools/
      real_lab.go
    helperclient/
      client.go
      contract.go
    audit/
      audit.go
    execution/
      execution.go
```

C# 侧第一阶段结构：

```text
native/
  ISphereWinHelper/
    Program.cs
    HelperProtocol.cs
    WindowScanner.cs
    UiaDumper.cs
```

第一阶段目录保持最小。

## 11. 验收标准

第一阶段完成后，只验收：

1. C# helper 能编译。
2. `version` 返回合法 JSON。
3. `self_check` 返回 UIA 可用状态。
4. `scan_windows` 能列出当前可见窗口。
5. 打开记事本后，`dump_uia` 能导出记事本控件树。
6. 用户手动登录 iSphere 后，`scan_windows` 能找到候选窗口。
7. 对 iSphere 候选窗口执行 `dump_uia` 能返回控件树。
8. 第一阶段验收聚焦窗口扫描和 UIA dump 结果。

## 12. 下一步

建议下一步只做 C# helper 第一阶段：

```text
version
self_check
scan_windows
dump_uia
```

Go MCP 代码在后续节点实现；C# helper 稳定拿到真实 iSphere 窗口结构后，再实现 Go 的 `helperclient` 和 MCP tools。