370 lines
7.2 KiB
Markdown
370 lines
7.2 KiB
Markdown
# 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。
|