432 lines
39 KiB
Markdown
432 lines
39 KiB
Markdown
# opencode review log
|
||
|
||
## 2026-07-05 审查记录
|
||
|
||
### 审查文件
|
||
- docs/go-mcp-minimal-plan.md
|
||
- docs/go-csharp-helper-boundary.md
|
||
- docs/process/go-implementation-log.md
|
||
- docs/process/csharp-helper-log.md
|
||
- scripts/build-win-helper.ps1
|
||
- scripts/verify-win-helper.ps1
|
||
- native/ISphereWinHelper/HelperProtocol.cs
|
||
- native/ISphereWinHelper/Program.cs
|
||
- native/ISphereWinHelper/WindowScanner.cs
|
||
- native/ISphereWinHelper/UiaDumper.cs
|
||
- .gitignore
|
||
- git status / git ls-files 边界输出
|
||
|
||
### 结构问题
|
||
- 未发现 Go/C# 边界混乱：Go 层尚未创建，C# helper 只保留 Windows/UIA 执行层；当前 switch 仅暴露 version、self_check、scan_windows、dump_uia 四个只读 op。
|
||
- 未发现过度设计：没有常驻服务、HTTP、named pipe、gRPC、插件框架、selector 学习系统。
|
||
- 轻微结构风险：Program.cs 接收 timeout_ms 但未在 C# 侧执行超时；当前依赖 Go 未来进程级超时会更明确。建议后续在进入 Go client 前明确“Go 强制超时、C# best-effort”或补 C# 侧计时保护。
|
||
- 轻微接口风险：helper 启动时传入 --json，但 Program.cs 当前不解析 args；行为上仍输出 JSON，不影响 N1，不过 CLI 合约还没有显式校验。
|
||
|
||
### 代码问题
|
||
- 未发现真实动作越界：未实现搜索联系人、打开会话、发送消息、发送文件、接收文件、自动登录、注入、hook、读内存或规避安防能力。
|
||
- 未发现不必要外部依赖：无 go.mod/go.sum；C# 仅使用 .NET Framework / Win32 / UIAutomation / System.Web.Extensions。
|
||
- WindowScanner 的 iSphere/IMPlatformClient/impp/importal 评分字符串属于窗口候选识别硬编码，当前阶段可接受；不是假通过，但后续真实环境需要用真实 UIA evidence 校验。
|
||
- UiaDumper 的 max_children 是每层/每节点限制，不是全局节点上限；在高 max_depth/max_children 下可能输出过大或耗时过长。当前脚本使用低深度通过，建议后续增加全局节点/耗时限制。
|
||
- build-win-helper.ps1 使用 /warn:0，能减少环境噪音，但会隐藏 C# 编译警告；当前不阻塞，后续代码增长时建议打开警告。
|
||
|
||
### 测试问题
|
||
- verify-win-helper.ps1 确认覆盖 version、self_check、scan_windows、dump_uia，并额外验证 missing hwnd 和临时 WinForms 窗口 dump_uia。
|
||
- 验证脚本解析 helper stdout JSON，并在 helper 退出码非 0 时失败；未看到伪造 ok=true 的路径。
|
||
- 覆盖缺口：脚本未断言响应 envelope 的 protocol/request_id/op，也未测试 unsupported op / invalid request；建议作为后续 N1 质量补强，不阻塞当前基线。
|
||
- 本轮未重新运行 verify-win-helper.ps1，避免产生新的构建/运行副作用；结论基于脚本静态审查和已有 C# helper 日志。
|
||
|
||
### 是否建议返工
|
||
- 不建议返工。
|
||
- 建议继续保持 N0/N1 已通过的边界，不进入 N2 以外的后续能力；进入 N2 前可把 timeout_ms/--json/envelope 断言列为小补强项。
|
||
|
||
### 结论
|
||
- 当前实现与计划主线一致：C# helper 是一次性 CLI，只读 UIA/窗口探测；Go MCP 尚未开始；没有 go.mod、Python MCP、测试套件或越界动作。
|
||
- 当前没有发现不必要依赖、过度设计、伪造验证或假通过。
|
||
|
||
## 2026-07-05 第二轮 N2 Go module skeleton 审查记录
|
||
|
||
### 审查文件
|
||
- docs/go-mcp-minimal-plan.md（重点复核 N2 Go module skeleton）
|
||
- docs/go-csharp-helper-boundary.md（复核 Go/C# 分层和当前阶段边界）
|
||
- docs/process/go-implementation-log.md（复核 N2 执行记录）
|
||
- go.mod
|
||
- git status / git ls-files / Test-Path / go list 边界输出
|
||
|
||
### 结构问题
|
||
- 未发现进入 N3：未创建 `internal/helperclient`、`internal/tools`、`cmd/isphere-mcp`，也未发现任何 `.go` 源文件。
|
||
- `go.mod` 当前只是 N2 要求的最小 Go module skeleton，模块名为 `isphere-ai-bridge`，与计划一致。
|
||
- Go/C# 边界仍清晰：Go 侧只有 module 元数据，没有 helper protocol contract、process client、MCP server 或 tool handler；C# helper 仍是 Windows/UIA 执行层。
|
||
- 未发现过度设计：没有新增目录框架、server 空壳、抽象层、MCP 依赖或工具注册代码。
|
||
|
||
### 代码问题
|
||
- `go.mod` 内容只有 `module isphere-ai-bridge` 和 `go 1.23`，无 `require`，未引入不必要依赖。
|
||
- 未发现 `go.sum`，未发现 Go 源码文件，因此不存在提前实现搜索联系人、打开会话、发送消息、文件收发、自动登录、注入、hook、读内存、规避安防等能力。
|
||
- 未发现硬编码业务动作或假实现；当前唯一新增的 Go 相关内容是模块元数据。
|
||
- 注意：`go.mod` 目前在 `git status` 中是未跟踪文件；这符合 N2 “创建 go.mod”的事实，但后续提交时需按计划精确 stage，不要 broad `git add -A`。
|
||
|
||
### 测试问题
|
||
- 已复核 `go version`：`go version go1.23.4 windows/amd64`。
|
||
- 已复核 `go list ./...`：输出 `go: warning: "./..." matched no packages`，退出码 `0`，符合 N2 对无 package skeleton 的接受条件。
|
||
- 当前阶段无 Go package、无 Go test，这是 N2 范围内可接受状态；不应要求 N3 的 contract test。
|
||
- 路径复核结果：`go.sum=false`，`cmd/isphere-mcp=false`，`internal/helperclient=false`，`internal/tools=false`，`go_files=0`。
|
||
|
||
### 是否建议返工
|
||
- 不建议返工。
|
||
- 建议维持当前 N2 边界，等待业务经理批准后才进入 N3；N3 前不要补写 contract.go、client_test.go 或任何 server/tool 代码。
|
||
|
||
### 结论
|
||
- 第二轮 N2 结果与计划一致：只创建最小 `go.mod`，无依赖、无 Go 源码、无 N3 内容、无越界动作。
|
||
- 未发现过度设计、不必要依赖、Go/C# 边界混乱、伪造验证或假通过。
|
||
|
||
## 2026-07-05 第三轮 N3 Go helper protocol contract 审查记录
|
||
|
||
### 审查文件
|
||
- docs/go-mcp-minimal-plan.md（重点复核 N3 Go helper protocol contract）
|
||
- docs/go-csharp-helper-boundary.md（复核 `isphere.helper.v1` 请求/响应协议边界）
|
||
- docs/process/go-implementation-log.md（复核 N3 red/green/补充验证记录）
|
||
- go.mod
|
||
- internal/helperclient/contract.go
|
||
- internal/helperclient/client_test.go
|
||
- git status / git ls-files / Test-Path / go test / go list -m all 边界输出
|
||
|
||
### 结构问题
|
||
- 未发现进入 N4：`internal/helperclient/client.go=false`，未实现 helper 进程调用、路径解析、stdin/stdout、timeout、stderr 捕获等 N4 内容。
|
||
- 未发现 MCP server/tools 提前创建：`cmd/isphere-mcp=false`，`internal/tools=false`，`internal/mcpserver=false`。
|
||
- 当前 Go 侧只有 `internal/helperclient/contract.go` 和 `internal/helperclient/client_test.go` 两个 `.go` 文件，范围符合 N3 “纯 JSON contract”。
|
||
- Go/C# 边界仍清晰：Go N3 仅建模 `isphere.helper.v1` JSON 结构；未启动 C# helper，未复制 UIA/窗口扫描逻辑。
|
||
- 未发现过度设计：没有 client interface、mock helper、server skeleton、审计/审批目录、MCP 抽象或额外框架。
|
||
|
||
### 代码问题
|
||
- `HelperRequest` 字段覆盖 `protocol`、`request_id`、`op`、`timeout_ms`、`args`；`HelperResponse` 字段覆盖 `protocol`、`request_id`、`op`、`ok`、`data`、`error`、`warnings`；`HelperError` 覆盖 `code`、`message`，与 N3 要求一致。
|
||
- `HelperResponse.Data` 使用 `map[string]json.RawMessage`，能保留未知 data 字段，符合 N3 验收点。
|
||
- `go.mod` 仍只有 module/go 版本；`go list -m all` 仅输出 `isphere-ai-bridge`，未引入外部依赖，未生成 `go.sum`。
|
||
- 未发现提前实现搜索联系人、打开会话、发送消息、文件收发、自动登录、注入、hook、读内存、规避安防等能力；代码中未出现 `exec.Command`、`Start-Process`、`--json`、`net/http`、MCP/tool 调用。
|
||
- 非阻塞质量项：测试未显式断言 `timeout_ms` 已被 marshal，也未断言 response 的 `protocol/request_id/op` 回填；结构体已具备字段，建议 N3 后续如补强测试时只补 contract 测试，不进入 N4。
|
||
- 非阻塞质量项：`Warnings []string` 对当前空数组可用；若 C# 未来返回非字符串 warning 对象，需要再评估是否改为 `[]json.RawMessage` 或结构化 warning。
|
||
|
||
### 测试问题
|
||
- 已复核 `go test ./internal/helperclient -run Contract -v -count=1`：3 个 Contract 测试 PASS，退出码 `0`。
|
||
- 已复核 `go test ./... -count=1`：PASS，退出码 `0`。
|
||
- 测试是纯 JSON marshal/unmarshal；未启动真实 C# helper，符合 N3 “不依赖真实 helper 进程”的要求。
|
||
- 当前测试覆盖 N3 核心验收点：version request protocol、success response ok/helper_name/unknown field、error response ok=false/error.code=WINDOW_NOT_FOUND。
|
||
- 未复现 Red 阶段，因为本轮只读审查不回退代码；Red 证据来自 `docs/process/go-implementation-log.md` 的记录。
|
||
|
||
### 是否建议返工
|
||
- 不建议返工。
|
||
- 建议保持当前 N3 边界，等待业务经理批准后才进入 N4；不要在本轮补 `client.go`、helper 启动逻辑、MCP server 或 tools。
|
||
|
||
### 结论
|
||
- 第三轮 N3 结果与计划一致：实现了最小 Go JSON contract 和 contract 测试，无外部依赖、无 `go.sum`、无 N4 client、无 MCP server/tools、无真实 helper 调用。
|
||
- 未发现过度设计、不必要依赖、Go/C# 边界混乱、伪造验证或假通过。
|
||
|
||
## 2026-07-05 第四轮 N4 Go helper process client 审查记录
|
||
|
||
### 审查文件
|
||
- docs/go-mcp-minimal-plan.md（重点复核 N4 Go helper process client）
|
||
- docs/go-csharp-helper-boundary.md（复核一次性 CLI、stdin/stdout JSON、Go/C# 分层边界）
|
||
- docs/process/go-implementation-log.md（复核 N4 red/green/真实 helper version 记录）
|
||
- go.mod
|
||
- internal/helperclient/client.go
|
||
- internal/helperclient/contract.go
|
||
- internal/helperclient/client_test.go
|
||
- git status / Test-Path / go test / go list -m all / Select-String 边界输出
|
||
|
||
### 结构问题
|
||
- 未发现进入 N5：本轮只实现 `internal/helperclient.Client` 进程调用；未新增 `scripts/verify-go-mcp.ps1`、未执行 Go MCP 层验证，也未创建 N5 之外的流程脚本。
|
||
- 未发现提前创建 MCP server/tools/cmd：`cmd/isphere-mcp=false`，`internal/tools=false`，`internal/mcpserver=false`。
|
||
- Go/C# 边界仍清晰：Go 只负责 helper 路径解析、启动 C# helper、stdin 写 JSON、stdout/stderr 读取、context timeout 和结构化 Go error；未复制 C# UIA、窗口枚举或控件树逻辑。
|
||
- `Client.Call(ctx, op, args)` 保持 N4 通用 process client API，没有业务动作方法；未出现 search/send/file/login 等专用 API。
|
||
- 未发现过度设计：没有接口工厂、常驻 helper、HTTP/gRPC/named pipe、MCP 抽象、审批/审计目录或额外框架。
|
||
|
||
### 代码问题
|
||
- `client.go` 使用标准库 `os/exec` 调用 helper with `--json`，stdin 写入 `HelperRequest`，stdout 反序列化 `HelperResponse`，stderr/exit code 纳入 `ClientError`，符合 N4 职责。
|
||
- 缺失 helper、timeout、bad JSON、non-zero exit 均有结构化错误码，范围清晰。
|
||
- `go.mod` 仍只有 module/go 版本；`go list -m all` 仅输出 `isphere-ai-bridge`，无外部依赖，未生成 `go.sum`。
|
||
- `git status --short -- native/ISphereWinHelper scripts` 为空，未改 C# helper 或脚本。
|
||
- 未发现搜索联系人、打开会话、发送消息、发送/接收文件、自动登录、注入、hook、读内存、规避安防等越界能力；Go 文件中未命中这些动作关键字，也未出现 UIAutomation/AutomationElement/SendKeys 等 UI 操作逻辑。
|
||
- 非阻塞质量项：`newRequestID()` 当前生成 32 位 hex 字符串，不是带 hyphen 的 UUID 字符串；C# 当前只按 opaque string 回显，N4 不阻塞，但若严格遵守边界文档“uuid-string”可在后续小补强。
|
||
- 非阻塞质量项：`Client.Call` 未校验 helper 响应的 `protocol/request_id/op` 是否与请求一致；当前 N4 验收未强制，但后续可补，减少错线响应或伪响应风险。
|
||
- 非阻塞质量项：测试未直接断言 stub 收到 `--json` 和 stdin 请求内容；代码路径已可见，但后续可增加专门 stub 验证，提升防回归强度。
|
||
|
||
### 测试问题
|
||
- 已复核 `go test ./internal/helperclient -run Client -v -count=1`：5 个 Client 测试全部 PASS，退出码 `0`。
|
||
- 真实 helper version 测试本轮实际执行并通过，日志包含 `helper_name=ISphereWinHelper path=E:\coding\codex\isphere-ai-bridge\runs\win-helper\ISphereWinHelper.exe`。
|
||
- 已复核 `go test ./... -count=1`：PASS，退出码 `0`。
|
||
- `go list -m all` 退出码 `0`，仅有根模块，无不必要依赖。
|
||
- 测试覆盖 missing helper、bad JSON、timeout、non-zero exit/stderr、真实 version call；未执行搜索、发送、文件、登录或 UI 动作。
|
||
- 未复现 Red 阶段，因为本轮只读审查不回退代码；Red 证据来自 `docs/process/go-implementation-log.md` 的记录。
|
||
|
||
### 是否建议返工
|
||
- 不建议返工。
|
||
- 建议保持当前 N4 边界，等待业务经理批准后才进入 N5；不要在本轮补 MCP server/tools/cmd，也不要扩大到业务动作。
|
||
|
||
### 结论
|
||
- 第四轮 N4 结果与计划一致：实现了 Go helper process client，能调用现有 C# helper 的真实 `version`，无外部依赖、无 MCP server/tools、无 C# 修改、无 UIA 逻辑复制、无业务动作越界。
|
||
- 未发现过度设计、不必要依赖、Go/C# 边界混乱、伪造验证或假通过。
|
||
|
||
## 2026-07-05 第五轮 N5 Helper client live verification 审查记录
|
||
|
||
### 审查文件
|
||
- docs/go-mcp-minimal-plan.md（重点复核 N5 Helper client live verification）
|
||
- docs/go-csharp-helper-boundary.md（复核一次性 CLI、stdin/stdout JSON、只读 helper 边界）
|
||
- docs/process/go-implementation-log.md（复核 N5 helper live verification 记录）
|
||
- docs/process/csharp-helper-log.md（复核 N5 C# helper 单体验证记录）
|
||
- go.mod
|
||
- internal/helperclient/client.go
|
||
- internal/helperclient/contract.go
|
||
- internal/helperclient/client_test.go
|
||
- git status / Test-Path / go test / go list -m all / Select-String 边界输出
|
||
|
||
### 结构问题
|
||
- 未发现进入 N6：未新增 MCP library decision 记录，`go.mod` 无 MCP 依赖，`go list -m all` 仅输出根模块 `isphere-ai-bridge`。
|
||
- 未发现提前创建 MCP server/tools/cmd：`cmd/isphere-mcp=false`，`internal/tools=false`，`internal/mcpserver=false`，`scripts/verify-go-mcp.ps1=false`。
|
||
- N5 本身是 live verification 节点；过程日志显示本轮只追加 Go 日志，C# helper 日志也声明未改 C# 文件，结构没有因 N5 被扩大。
|
||
- Go/C# 边界仍清晰：Go helperclient 只负责启动 helper、stdin/stdout JSON、stderr/exit code、timeout 和结构化错误；C# helper 仍只负责 `version` / `self_check` / `scan_windows` / `dump_uia`。
|
||
- 未发现过度设计：没有新目录框架、MCP 框架、HTTP/gRPC/named pipe、常驻 helper、审批/审计抽象或业务工具层。
|
||
|
||
### 代码问题
|
||
- `git status --short -- native/ISphereWinHelper scripts` 为空，未发现 C# helper 或脚本修改。
|
||
- 当前 Go 文件仍只有 `internal/helperclient/client.go`、`contract.go`、`client_test.go` 三个文件；未新增业务动作代码。
|
||
- 关键词检查未命中搜索联系人、打开会话、发送消息、文件收发、自动登录、注入、hook、读内存、UIAutomation/AutomationElement/SendKeys 等越界实现。
|
||
- 未发现不必要依赖：`go.mod` 仍只有 module/go 版本，未生成 `go.sum`。
|
||
- 未发现硬编码假通过：真实 helper version 测试读取默认路径 `runs\win-helper\ISphereWinHelper.exe` 并断言响应 `helper_name=ISphereWinHelper`；C# helper 日志中的 `verify-win-helper.ps1` 覆盖四个只读 op 和临时 WinForms `dump_uia`。
|
||
- 非阻塞质量项沿用 N4：后续仍可补响应 `protocol/request_id/op` 校验，以及让 `newRequestID()` 严格符合 UUID 格式；这不是 N5 阻塞项。
|
||
|
||
### 测试问题
|
||
- 本轮未重新运行 `scripts\verify-win-helper.ps1`，原因是审查职责为只读，避免构建脚本再次写入 `runs/`；C# helper 验证结果依据 Go/C# 过程日志交叉复核。
|
||
- 已复核 `go test ./internal/helperclient -v -count=1`：Contract 与 Client 测试全部 PASS，退出码 `0`，输出包含真实 helper version 调用 `helper_name=ISphereWinHelper path=E:\coding\codex\isphere-ai-bridge\runs\win-helper\ISphereWinHelper.exe`。
|
||
- 已复核 `go test ./... -count=1`：PASS，退出码 `0`。
|
||
- 已复核 `go list -m all`：退出码 `0`，仅输出 `isphere-ai-bridge`。
|
||
- C# helper 日志显示 `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1` 退出码 `0`，输出 `ok=true`、`version=0.1.0`、`scan_window_count=30`、`uia_available=true`，且只涉及 `version/self_check/scan_windows/dump_uia`。
|
||
|
||
### 是否建议返工
|
||
- 不建议返工。
|
||
- 建议保持当前 N5 结论，等待业务经理批准后才进入 N6；不要在当前轮次选择 MCP library、添加依赖、创建 server/tools/cmd 或扩大业务能力。
|
||
|
||
### 结论
|
||
- 第五轮 N5 结果与计划一致：完成 helper live verification，Go helperclient 能调用真实 C# helper 的 `version`，C# helper 单体验证覆盖四个只读 op；未发现 N6、MCP server/tools、外部依赖、C# 修改或业务动作越界。
|
||
- 未发现过度设计、不必要依赖、Go/C# 边界混乱、伪造验证或假通过。
|
||
|
||
## 2026-07-05 第六轮 N6 MCP library decision 审查记录
|
||
|
||
### 审查文件
|
||
- docs/go-mcp-minimal-plan.md（重点复核 N6 MCP library decision）
|
||
- docs/go-mcp-library-decision.md
|
||
- docs/process/go-implementation-log.md（复核 N6 执行记录）
|
||
- go.mod
|
||
- go.sum
|
||
- internal/helperclient/client.go
|
||
- internal/helperclient/contract.go
|
||
- internal/helperclient/client_test.go
|
||
- git status / Test-Path / git ls-files / go list -m all / go test / go doc / Select-String 边界输出
|
||
|
||
### 结构问题
|
||
- 未发现进入 N7：`cmd/isphere-mcp=false`，`internal/mcpserver=false`，未写 server skeleton，未调用 `mcp.NewServer` 的 Go 代码。
|
||
- 未发现进入 N8：`internal/tools=false`，未注册 `win_helper_*` 工具，未创建 tool handler。
|
||
- N6 产物集中在库决策文档和 Go module 元数据：`docs/go-mcp-library-decision.md`、`go.mod`、`go.sum`；Go 源码仍只有 `internal/helperclient` 三个既有文件。
|
||
- Go/C# 边界未被破坏：本轮没有调用 C# helper、没有修改 C# helper/脚本，Go 侧也没有新增窗口/UIA/业务动作代码。
|
||
- 未发现过度设计：没有 HTTP server、gRPC、named pipe、后台 daemon、多 MCP 框架、server 目录或工具目录。
|
||
|
||
### 代码问题
|
||
- `go.mod` 当前为 `go 1.23.0`、`toolchain go1.23.4`，并仅新增 `require github.com/modelcontextprotocol/go-sdk v1.3.1 // indirect`；N6 未写 import，因此保持 indirect 属于 Go 工具当前状态，后续 N7/N8 首次 import 后可自然变 direct。
|
||
- `go.sum` 仅包含 `github.com/modelcontextprotocol/go-sdk v1.3.1` 两条校验和；未出现 `v1.6.1`、`v1.7.0` 或 `go 1.25` 版本线。
|
||
- `go list -m all` 显示 SDK 的 transitive module graph，但 MCP-related dependency 只有 `github.com/modelcontextprotocol/go-sdk v1.3.1` 一个；未发现第二个 MCP 框架。
|
||
- `go doc` 复核通过：`mcp.StdioTransport` 支持 stdin/stdout newline-delimited JSON；`mcp.AddTool` 支持 typed handler 和 JSON schema 推断；`mcp.NewServer` 存在但当前未在代码中使用。
|
||
- 关键词检查显示 MCP SDK 相关符号只出现在决策文档，不在 Go 源码中；未提前实现 server/tool。
|
||
- 未发现搜索联系人、打开会话、发送消息、发送/接收文件、自动登录、注入、hook、读内存、规避安防等越界能力。
|
||
- 非阻塞注意：`go list -m all` 包含 SDK 的若干传递依赖（如 jsonschema、oauth2、x/sys 等）；这来自官方 SDK module graph，当前没有项目代码 import 这些包，不构成额外框架选择，但后续 N7/N8 应避免再引入第二套 MCP 或 HTTP server 依赖。
|
||
|
||
### 测试问题
|
||
- 已复核 `go test ./... -count=1`：PASS，退出码 `0`。
|
||
- 已复核 `go list -m all`：退出码 `0`，输出包含 `github.com/modelcontextprotocol/go-sdk v1.3.1`，未出现其他 MCP-related module。
|
||
- 已复核 `go doc github.com/modelcontextprotocol/go-sdk/mcp.StdioTransport`、`AddTool`、`NewServer`：均退出码 `0`，与决策文档中的 stdio/tool/schema 说法一致。
|
||
- `git status --short -- native/ISphereWinHelper scripts` 为空，未发现 C# helper 或脚本修改。
|
||
- `git ls-files` 对 `cmd/isphere-mcp/*`、`internal/mcpserver/*`、`internal/tools/*`、`scripts/verify-go-mcp.ps1`、`src/isphere_ai_bridge/*`、`tests/test_*.py` 无输出，未发现提前进入 N7/N8 或恢复 Python 路径。
|
||
|
||
### 是否建议返工
|
||
- 不建议返工。
|
||
- 建议保持当前 N6 边界，等待业务经理批准后才进入 N7；N7 前不要创建 `cmd/isphere-mcp`、`internal/mcpserver`、`internal/tools`，也不要注册工具或扩大业务能力。
|
||
|
||
### 结论
|
||
- 第六轮 N6 结果与计划一致：只完成 MCP library decision，选择 `github.com/modelcontextprotocol/go-sdk v1.3.1` / `mcp` 包，记录了 stdio、AddTool、schema、维护风险和适配四个工具的理由；未写 server code、未注册工具、未调用 C# helper、未改 C#。
|
||
- 未发现过度设计、不必要依赖、Go/C# 边界混乱、伪造验证或假通过。
|
||
|
||
## 2026-07-05 第七轮 N7 Go MCP server skeleton 审查记录
|
||
|
||
### 审查文件
|
||
- docs/go-mcp-minimal-plan.md（重点复核 N7 Go MCP server skeleton）
|
||
- cmd/isphere-mcp/main.go
|
||
- internal/mcpserver/server.go
|
||
- internal/mcpserver/server_test.go
|
||
- go.mod
|
||
- go.sum
|
||
- docs/process/go-implementation-log.md（复核 N7 red/green/build 记录）
|
||
- internal/helperclient/client.go / contract.go / client_test.go（边界关键词复核）
|
||
- git status / Test-Path / git ls-files / go list -m all / go test / go build / Select-String 边界输出
|
||
|
||
### 结构问题
|
||
- 未发现进入 N8：`internal/tools=false`，`git ls-files -- internal/tools/*` 无输出，Go 源码中未出现 `AddTool`、`mcp.AddTool`、`win_helper_*` 工具注册。
|
||
- N7 server skeleton 范围清晰：`cmd/isphere-mcp/main.go` 仅创建 context、调用 `mcpserver.NewServer()` 并用 `mcp.StdioTransport` 运行；`internal/mcpserver/server.go` 仅封装 `mcp.NewServer` 和 server metadata。
|
||
- `internal/mcpserver/server_test.go` 只验证空 MCP server 可构造，不启动 stdio、不调用 C# helper、不导入 helperclient。
|
||
- Go/C# 边界仍清晰：`cmd/isphere-mcp` 和 `internal/mcpserver` 未导入 `internal/helperclient`，未解析 helper 路径，未调用 `ISphereWinHelper.exe`；C# helper/脚本状态为空修改。
|
||
- 未发现过度设计：没有业务 tool 层、HTTP listener、gRPC、named pipe、后台 daemon、审批/审计抽象、第二套 MCP 框架或复杂配置系统。
|
||
|
||
### 代码问题
|
||
- `server.go` 中 `ServerName`、`ServerTitle`、`ServerVersion` 是 server metadata 常量，属于 N7 skeleton 必需信息，不是业务假实现。
|
||
- `main.go` 使用 `mcp.StdioTransport`，符合 N7 stdio server skeleton 目标；没有 HTTP server 或 Python/Node runtime。
|
||
- `go.mod` 现在将 `github.com/modelcontextprotocol/go-sdk v1.3.1` 调整为 direct require，并列出 SDK 需要的 indirect dependencies；这是首次 import SDK 包后的正常 module 元数据变化。
|
||
- `go.sum` 包含 SDK 及其传递依赖校验和；未发现第二个 MCP SDK 或 `v1.6.1`/`v1.7.0`/`go 1.25` 版本线。
|
||
- `go list -m all` 中出现的 transitive modules 来自官方 SDK 依赖图；当前项目源码未引入第二个 MCP 框架，也未新增 HTTP server 代码。
|
||
- 关键词检查未发现搜索联系人、打开会话、发送消息、发送/接收文件、自动登录、注入、hook、读内存、规避安防等越界能力；`ISphereWinHelper` 仅存在于既有 helperclient 代码/测试，不在 N7 server skeleton 中。
|
||
- 非阻塞质量项：N7 当前只有“server 可构造”测试，未验证 `ServerName/Title/Version` 是否进入 SDK Implementation；如果 SDK 提供稳定 accessor，后续可补，不影响 N7 骨架验收。
|
||
|
||
### 测试问题
|
||
- 已复核 `go test ./... -count=1`：`cmd/isphere-mcp [no test files]`，`internal/helperclient` PASS，`internal/mcpserver` PASS，退出码 `0`。
|
||
- 已复核构建：使用 `go build -o NUL ./cmd/isphere-mcp` 退出码 `0`，并确认工作区没有留下 `isphere-mcp.exe`。
|
||
- 已复核 `go list -m all`：退出码 `0`，MCP-related dependency 仍为 `github.com/modelcontextprotocol/go-sdk v1.3.1`，未发现第二个 MCP 框架。
|
||
- `git status --short -- native/ISphereWinHelper scripts` 为空，未发现 C# helper 或脚本修改。
|
||
- 本轮未复现 Red 阶段，因为只读审查不回退代码；Red 证据来自 `docs/process/go-implementation-log.md`，记录最终因 `undefined: NewServer` 失败，随后 green/build 通过。
|
||
|
||
### 是否建议返工
|
||
- 不建议返工。
|
||
- 建议保持当前 N7 边界，等待业务经理批准后才进入 N8；N8 前不要创建 `internal/tools`，不要注册 `AddTool`，不要引入 helperclient 到 server skeleton，也不要扩大到业务动作。
|
||
|
||
### 结论
|
||
- 第七轮 N7 结果与计划一致：创建了最小 Go MCP stdio server skeleton，可测试、可构建；未注册工具、未创建 `internal/tools`、未导入 helperclient、未调用 C# helper、未改 C#。
|
||
- 未发现过度设计、不必要依赖、Go/C# 边界混乱、伪造验证或假通过。
|
||
|
||
## 2026-07-05 第八轮 N8 Four read-only MCP tool handlers 审查记录
|
||
|
||
### 审查文件
|
||
- docs/go-mcp-minimal-plan.md（重点复核 N8 Four read-only MCP tool handlers）
|
||
- internal/tools/winhelper.go
|
||
- internal/tools/winhelper_test.go
|
||
- internal/mcpserver/server.go
|
||
- internal/mcpserver/server_test.go
|
||
- cmd/isphere-mcp/main.go
|
||
- go.mod
|
||
- go.sum
|
||
- docs/process/go-implementation-log.md（复核 N8 red/green 记录）
|
||
- git status / Test-Path / git ls-files / go list -m all / go test / Select-String 边界输出
|
||
|
||
### 结构问题
|
||
- 未发现进入 N9：`scripts/verify-go-mcp.ps1=false`，`git ls-files -- scripts/verify-go-mcp.ps1` 无输出，未创建 MCP stdio smoke verification 脚本。
|
||
- N8 范围集中在 `internal/tools` 和 `internal/mcpserver` 接入；`cmd/isphere-mcp/main.go` 未扩展业务逻辑。
|
||
- `internal/tools/winhelper.go` 通过 `RegisterWinHelperTools(server, caller)` 注册工具；`internal/mcpserver.NewServer()` 仅接入该注册函数并传入 `helperclient.Client{}`，构造阶段未调用 C# helper。
|
||
- Go/C# 边界清晰：tool handler 只通过 `HelperCaller` / `internal/helperclient` 调 helper op；未复制 C# UIA、WindowScanner、UiaDumper、user32、FindWindow、SendKeys 等逻辑。
|
||
- 未发现过度设计：没有额外插件框架、审批/审计层、HTTP/gRPC/named pipe、后台 daemon 或第二套 MCP 框架。
|
||
|
||
### 代码问题
|
||
- `mcp.AddTool` 在 `internal/tools/winhelper.go` 中恰好 4 处。
|
||
- 只注册四个工具名：`win_helper_version`、`win_helper_self_check`、`win_helper_scan_windows`、`win_helper_dump_uia`；未发现第五个工具。
|
||
- 参数结构符合 N8：version/self_check 无业务参数；scan 只有 `include_all_visible`；dump 只有 `hwnd`、`max_depth`、`include_text`、`max_children`。
|
||
- handler op 映射符合边界：`version`、`self_check`、`scan_windows`、`dump_uia`；没有 search/open/send/file/login 等业务动作 op。
|
||
- 生产 Go 文件动作词检查无命中：未出现 send/search/file/conversation/receive/upload/download/login 等业务动作词。
|
||
- 测试中出现 `send/search/file/login/upload/download/receive` 仅用于 forbidden tool-name 检查，不是实现动作。
|
||
- `go.mod` / `go.sum` 未显示新增第二个 MCP 框架；`go list -m all` 仍只有一个 MCP-related dependency：`github.com/modelcontextprotocol/go-sdk v1.3.1`。SDK 传递依赖属于既有官方 SDK 依赖图。
|
||
- 非阻塞质量项：`DumpUIAArgs` 的 `MaxDepth`、`MaxChildren` 在 handler 中转为 `float64` 后传给 helper args；当前测试按 MCP JSON number 行为验证，C# `Convert.ToInt32` 可接受，暂不阻塞。
|
||
- 非阻塞质量项：helper 返回 `ok:false` 时当前仍作为 tool output map 返回而不是 Go error；这与协议“业务失败用 JSON ok:false 表达”一致，但后续 runbook 可明确客户端如何展示失败。
|
||
|
||
### 测试问题
|
||
- 已复核 `go test ./internal/tools -v -count=1`：3 个 internal/tools 测试全部 PASS，退出码 `0`。
|
||
- 已复核 `go test ./... -count=1`：`cmd/isphere-mcp [no test files]`，`internal/helperclient` PASS，`internal/mcpserver` PASS，`internal/tools` PASS，退出码 `0`。
|
||
- tests 覆盖 exactly four tool names、schema 参数、handler 通过 fake caller 调用 helper op；未调用真实 C# helper。
|
||
- `internal/mcpserver` 测试通过 in-memory transport 列出四个工具，不启动 stdio、不执行 helper。
|
||
- `git status --short -- native/ISphereWinHelper scripts` 为空，未发现 C# helper 或脚本修改。
|
||
- 未复现 Red 阶段，因为只读审查不回退代码；Red 证据来自 `docs/process/go-implementation-log.md`，记录 undefined 注册函数/参数结构和空工具列表失败，随后 green 通过。
|
||
|
||
### 是否建议返工
|
||
- 不建议返工。
|
||
- 建议保持当前 N8 边界，等待业务经理批准后才进入 N9；N9 前不要创建 `scripts/verify-go-mcp.ps1`，不要做 stdio smoke 脚本，也不要扩大到搜索/会话/发送/文件/登录能力。
|
||
|
||
### 结论
|
||
- 第八轮 N8 结果与计划一致：只注册四个只读 WinHelper MCP tools，handler 经 `internal/helperclient` 调用 C# helper 协议 op；无第五个工具、无直接 UI 操作、无 C# 修改、无 N9 脚本、无业务动作越界。
|
||
- 未发现过度设计、不必要依赖、Go/C# 边界混乱、伪造验证或假通过。
|
||
|
||
## 2026-07-05 第九轮 N9 MCP stdio smoke verification 审查记录
|
||
|
||
### 审查文件
|
||
- docs/go-mcp-minimal-plan.md（重点复核 N9 MCP stdio smoke verification）
|
||
- scripts/verify-go-mcp.ps1
|
||
- docs/process/go-implementation-log.md（复核 N9 red/green 记录）
|
||
- internal/tools/winhelper.go
|
||
- internal/mcpserver/server.go
|
||
- go.mod / go.sum / 当前 Go 测试与 git 状态输出
|
||
- PowerShell Parser / Select-String / Test-Path / git ls-files 边界输出
|
||
|
||
### 结构问题
|
||
- 未发现进入 N10：`docs/go-mcp-runbook.md=false`，`git ls-files -- docs/go-mcp-runbook.md` 无输出，`README.md` 未修改。
|
||
- N9 新增范围集中在 `scripts/verify-go-mcp.ps1`；未新增 runbook、配置文档或 operator 操作说明。
|
||
- 验证脚本结构符合 N9：先构建 C# helper，再构建 Go MCP binary，再通过官方 Go MCP SDK harness 自动 initialize/connect、tools/list、tools/call `win_helper_version`。
|
||
- 脚本使用 SDK in-memory harness 而不是直接运行已构建二进制 stdio；过程日志说明原因是 Windows PowerShell stdin BOM/encoding 问题，且 N9 计划允许“use the MCP library test harness”。脚本也明确输出 `transport=sdk_in_memory`，未伪装成真实 stdio binary run。
|
||
- 未发现过度设计：没有新增服务、daemon、HTTP/gRPC/named pipe、N10 runbook、部署配置或第二套验证框架。
|
||
|
||
### 代码问题
|
||
- 脚本会构建 Go MCP binary 到系统临时目录，并在 finally 清理；会把临时 SDK harness 写到 `runs\go-mcp-harness-*` 并在 finally 清理。该设计可重复运行，但如果进程被强杀，可能残留 ignored `runs` 临时目录；这是非阻塞运维风险。
|
||
- 脚本最终 JSON 明确包含 `ok=true`、`helper_name`、`tool_count`、`tools`、`python_runtime_required=false`、`real_isphere_login_required=false`、`action_tools_present=false`。
|
||
- `action_tools_present=false` 不是裸写假通过：harness 先遍历 tool name 并检查 forbiddenTerms（send/search/file/login/conversation/upload/download/receive/autologin），发现即 fail；随后才输出 false。
|
||
- `helper_name=ISphereWinHelper` 不是硬编码假通过：harness 调用 `win_helper_version` 后从 structured content 的 `data.helper_name` 读取并断言等于 `ISphereWinHelper`。
|
||
- `tool_count=4` 不是硬编码假通过：harness 通过 `ListTools` 获取 toolNames，排序后与四个期望工具名比较，并断言长度为 4。
|
||
- 未发现 N9 脚本实现搜索联系人、打开会话、发送消息、发送/接收文件、自动登录、注入、hook、读内存或规避安防；动作词只出现在 forbiddenTerms 或 false 输出字段中。
|
||
- `go list -m all` 仍只有一个 MCP-related dependency：`github.com/modelcontextprotocol/go-sdk v1.3.1`；未发现新增不必要 MCP 依赖。
|
||
- C# helper 源码和既有 `build-win-helper.ps1` / `verify-win-helper.ps1` 无修改；新增脚本 `scripts/verify-go-mcp.ps1` 属于 N9 范围。
|
||
|
||
### 测试问题
|
||
- 本轮未重新运行 `scripts\verify-go-mcp.ps1`，因为本轮硬性约束是不创建任何文件（除追加本审查文档）；该脚本会构建 helper/binary 并创建临时 harness 目录。审查改用静态脚本审查、过程日志复核和 Go 测试复核。
|
||
- 已复核 PowerShell 脚本语法：`Parser.ParseFile` 返回 `parse_ok=true`。
|
||
- 已复核 `go test ./... -count=1`：`cmd/isphere-mcp [no test files]`，`internal/helperclient` PASS，`internal/mcpserver` PASS，`internal/tools` PASS，退出码 `0`。
|
||
- 已复核 `go list -m all`：退出码 `0`，MCP-related dependency 仍为 `github.com/modelcontextprotocol/go-sdk v1.3.1`。
|
||
- 已复核工具数量：`internal/tools/winhelper.go` 中 `mcp.AddTool` 数量为 4；工具名仍是 `win_helper_version`、`win_helper_self_check`、`win_helper_scan_windows`、`win_helper_dump_uia`。
|
||
- `git status --short -- native/ISphereWinHelper` 为空，`scripts/build-win-helper.ps1` 与 `scripts/verify-win-helper.ps1` 为空修改；`scripts/verify-go-mcp.ps1` 是本 N9 新增脚本。
|
||
- 未复现 N9 red/green 脚本执行，因为只读审查不回退或重跑构建脚本；Red/Green 证据来自 `docs/process/go-implementation-log.md`，其中记录最终 `verify_go_mcp_exit=0` 和关键 JSON 输出。
|
||
|
||
### 是否建议返工
|
||
- 不建议返工。
|
||
- 建议保持当前 N9 边界，等待业务经理批准后才进入 N10；N10 前不要创建 runbook，不要新增业务工具，不要扩大到搜索/会话/发送/文件/登录能力。
|
||
|
||
### 结论
|
||
- 第九轮 N9 结果与计划一致：新增可重复 MCP smoke verification 脚本，验证 C# helper 构建、Go MCP binary 构建、MCP initialize/list/call `win_helper_version`，并确认四个工具、无 action tools、无需 Python、无需真实 iSphere 登录。
|
||
- 未发现过度设计、不必要依赖、Go/C# 边界混乱、伪造验证、硬编码假通过、N10 runbook 或业务动作越界。
|
||
|
||
## 2026-07-05 第十轮 N10 Operator runbook 审查记录
|
||
|
||
### 审查文件
|
||
- docs/go-mcp-minimal-plan.md（重点复核 N10 Operator runbook and process scripts）
|
||
- docs/go-mcp-runbook.md
|
||
- docs/process/go-implementation-log.md（复核 N10 执行记录）
|
||
- README.md / cmd / internal / go.mod / go.sum / native/ISphereWinHelper / scripts 的 git 状态输出
|
||
- internal/tools/winhelper.go / internal/mcpserver/server.go / cmd/isphere-mcp/main.go 的工具与边界抽查输出
|
||
|
||
### 结构问题
|
||
- Runbook 结构完整，包含 Prerequisites、Build C# helper、Verify C# helper、Build Go MCP、Verify Go MCP、Configure MCP client command、Allowed tools、Explicit non-goals and safety boundaries、Real-login UIA capture procedure、Troubleshooting。
|
||
- N10 计划要求的八类内容均已覆盖：构建/验证 C# helper、构建/验证 Go MCP、配置 MCP client command、允许工具、明确非目标、real-login UIA capture procedure。
|
||
- Real-login UIA capture procedure 明确标注为 later real-login capture gate，要求 explicit approval，不要求当前执行；这是 N10 runbook 范围内的操作说明，不是提前进入 N12。
|
||
- 未发现进入 N11：`git log -1 --oneline` 仍为 `87e0e47 chore: remove temporary python mcp layer`，未执行 N11 commit/review checkpoint。
|
||
- README 状态为空，未发现 README 修改；N10 实现日志说明检查过 README 后选择不改，符合“only if needed”。
|
||
- 工作区仍保留前序 N2-N10 的未跟踪实现/过程文件；未发现本轮回退他人改动或提交。
|
||
|
||
### 代码问题
|
||
- 本轮为文档轮，未发现 tracked code/script/native/README diff；`git diff --name-only -- README.md cmd internal go.mod go.sum native/ISphereWinHelper scripts` 为空。
|
||
- `docs/go-mcp-runbook.md` 原样包含四条 N10 必需命令：`powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1`、`go test ./...`、`go build ./cmd/isphere-mcp`、`powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1`。
|
||
- Runbook 只列出四个允许工具：`win_helper_version`、`win_helper_self_check`、`win_helper_scan_windows`、`win_helper_dump_uia`；`internal/tools/winhelper.go` 中 `mcp.AddTool` 数量仍为 4。
|
||
- Runbook 明确写出 N10 必需边界：`no login automation`、`no send message`、`no send file`、`no receive/download file`、`no process injection`、`no hook`、`no memory reading`，并额外列出 no search contacts、no open conversation、no automatic login、no Python MCP fallback。
|
||
- Go/C# 边界表达清晰：C# helper 是 Windows/UI Automation execution layer；Go MCP 是 stdio server 和四个只读 tool handler；Runbook 没有要求 Python MCP fallback 或 Go 侧复制 UIA/窗口逻辑。
|
||
- 未发现伪造或硬编码假通过说法：Runbook 使用“Expected output includes”描述操作者应看到的验证结果，并指向现有验证脚本；没有声称未运行的本轮验证已经通过。
|
||
- 未发现暗示业务能力已实现：Runbook 明确当前阶段不自动登录、不搜索联系人、不打开会话、不发送消息、不发送/接收文件；future send/file operations 被写为“if ever approved”且“not implemented in this phase”。
|
||
- 未发现新增不必要脚本或依赖：N10 新增范围是 `docs/go-mcp-runbook.md`；`go.mod` 仍只有官方 MCP SDK direct require，其他为 SDK indirect dependencies。
|
||
|
||
### 测试问题
|
||
- N10 是文档/运行手册节点，本身不要求新增 Go 测试或执行会生成产物的 smoke 脚本。
|
||
- 已复核 `go list -m all`：退出码 `0`，MCP-related dependency 仍为 `github.com/modelcontextprotocol/go-sdk v1.3.1`，未发现第二个 MCP SDK。
|
||
- 已复核 `go test ./... -count=1`：`cmd/isphere-mcp [no test files]`，`internal/helperclient` PASS，`internal/mcpserver` PASS，`internal/tools` PASS，退出码 `0`。
|
||
- 未重新执行 `scripts\verify-go-mcp.ps1`，因为本轮审查约束是不创建任何文件（除追加本审查文档），该脚本会构建 helper/binary 并创建临时 harness 目录；本轮改用 runbook 内容核验、Go 测试和 git 状态复核。
|
||
- 已用 `Select-String -SimpleMatch` 复核必需命令、四个工具名、边界短语和 `not implemented` 均在 runbook 中存在。
|
||
|
||
### 是否建议返工
|
||
- 不建议返工。
|
||
- 建议保持当前 N10 边界，等待业务经理批准后才进入 N11；N11 前不要提交、不要新增业务工具、不要扩大到搜索/会话/发送/文件/登录能力。
|
||
|
||
### 结论
|
||
- 第十轮 N10 结果与计划一致：新增 operator runbook，覆盖构建、验证、MCP client 配置、四个只读工具、非目标边界和未来 real-login UIA capture procedure；README 未改，功能代码未改，未新增依赖或脚本，未进入 N11。
|
||
- 未发现过度设计、不必要依赖、Go/C# 边界混乱、伪造验证、硬编码假通过或暗示未实现业务能力。
|