157 lines
9.1 KiB
Markdown
157 lines
9.1 KiB
Markdown
# A-Route RPA Send Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 在 `codex/a-route-rpa-send` 分支实现 A 方案，并在合并到 `main` 后继续校准计划：通过受控 UI Automation 路线让 `isphere_send_message` 能配置为真实 UI 写入并点击发送；同时明确这只证明 UI 动作，不等于业务送达，而且 A-route/RPA 是备选兜底，不是主线。
|
||
|
||
**Architecture:** Go MCP 继续保留稳定 `isphere_send_message` 接口、hash、idempotency、audit。新增 A-route connector 调用 C# `ISphereWinHelper` 的 UIA action op；C# helper 根据窗口句柄、发送框 AutomationId、发送按钮 AutomationId 写入文本并点击。B-route sidecar 仍是主路线，但当前不可测时先实现 A-route 功能兜底。
|
||
|
||
**Tech Stack:** Go 1.23.4, github.com/modelcontextprotocol/go-sdk, Windows PowerShell, .NET Framework C# helper, Windows UI Automation.
|
||
|
||
## Global Constraints
|
||
|
||
- Repository root: `E:\coding\codex\isphere-ai-bridge`.
|
||
- Original implementation branch: `codex/a-route-rpa-send`; merged branch for follow-up documentation and plan correction: `main`.
|
||
- Do not use `rg`; use `git ls-files`, `ag`, `grep -R`, or PowerShell commands.
|
||
- Local machine cannot log in; use synthetic WinForms/UIA verification for local tests.
|
||
- User explicitly removed human approval as a product gate for A-route; do not add approval IDs or approval queues in this plan.
|
||
- Keep audit redaction: do not store raw message body or raw idempotency key in committed docs/audit tests.
|
||
- Real UI action requires explicit env configuration; default MCP behavior remains preview/blocked.
|
||
- Route priority must stay B-route first: running-client sidecar / in-process connector / existing API is the primary product route; A-route/RPA only keeps a fallback path alive while B-route is blocked or untestable.
|
||
- Helper fields `clicked_ui=true` and `sent_message=true` mean the helper wrote the editor and invoked/clicked the send button. They must not be interpreted as server acceptance, receiver delivery, or sent-record proof.
|
||
|
||
---
|
||
|
||
## Task 1: Go connector must carry raw content to action connector
|
||
|
||
**Files:**
|
||
- Modify: `internal/tools/send_message_connector.go`
|
||
- Modify: `internal/tools/isphere_send_message.go`
|
||
- Modify: `internal/tools/isphere_send_message_test.go`
|
||
|
||
**Interfaces:**
|
||
- Produces: `SendMessageConnectorRequest.ContentText string` for connector execution only.
|
||
- Audit and response still omit raw content.
|
||
|
||
- [x] Write failing test proving injected connector receives raw `ContentText` while response/audit do not leak it.
|
||
- [x] Run focused test and confirm failure.
|
||
- [x] Add `ContentText` to normalized args and connector request.
|
||
- [x] Run focused send-message tests.
|
||
|
||
## Task 2: Go A-route UIA connector adapter
|
||
|
||
**Files:**
|
||
- Create: `internal/tools/send_message_uia_adapter.go`
|
||
- Create: `internal/tools/send_message_uia_adapter_test.go`
|
||
|
||
**Interfaces:**
|
||
- Produces: `type UiaSendMessageAdapterConfig struct { HelperPath string; TimeoutSeconds int; Hwnd string; SendEditorAutomationID string; SendButtonAutomationID string; Mode string }`.
|
||
- Produces: `NewUiaSendMessageConnector(config UiaSendMessageAdapterConfig, caller UiaHelperCaller) SendMessageConnector`.
|
||
- Helper op: `uia_send_message`.
|
||
|
||
- [x] Write failing tests for missing config and successful helper call using a fake helper caller.
|
||
- [x] Implement adapter request mapping.
|
||
- [x] Run focused adapter tests.
|
||
|
||
## Task 3: C# WinHelper UIA send action
|
||
|
||
**Files:**
|
||
- Create: `native/ISphereWinHelper/UiaSendAction.cs`
|
||
- Modify: `native/ISphereWinHelper/Program.cs`
|
||
- Modify: `scripts/verify-win-helper.ps1`
|
||
|
||
**Interfaces:**
|
||
- Helper op `uia_send_message` args: `hwnd`, `send_editor_automation_id`, `send_button_automation_id`, `content_text`, `content_sha256`, `target_ref`.
|
||
- Helper data: `action_mode="uia_send_message"`, `typed_text=true`, `clicked_ui=true`, `sent_message=true`, `content_sha256`, `target_ref`, `editor_found`, `button_found`.
|
||
|
||
- [x] Add synthetic WinForms verification that starts a form with `rtbSendMessage`, `btnSend`, invokes `uia_send_message`, and verifies button-click side effect in a label.
|
||
- [x] Implement `UiaSendAction` with ValuePattern/Win32 fallback and InvokePattern/click fallback.
|
||
- [x] Run `scripts\verify-win-helper.ps1`.
|
||
|
||
## Task 4: Wire A-route connector into MCP env config
|
||
|
||
**Files:**
|
||
- Modify: `internal/tools/isphere_send_message.go`
|
||
- Modify: `internal/mcpserver/server.go`
|
||
- Modify: `scripts/verify-go-mcp.ps1`
|
||
- Modify: `docs/go-mcp-runbook.md`
|
||
- Modify: `docs/current-status-card.md`
|
||
|
||
**Interfaces:**
|
||
- Env `ISPHERE_SEND_CONNECTOR_MODE=uia_rpa` enables A-route connector.
|
||
- Env `ISPHERE_SEND_UIA_HWND`, `ISPHERE_SEND_UIA_EDITOR_AUTOMATION_ID`, `ISPHERE_SEND_UIA_BUTTON_AUTOMATION_ID`, optional `ISPHERE_SEND_UIA_HELPER_PATH` configure the action.
|
||
- Default env remains no real send.
|
||
|
||
- [x] Add config loader and tests around production connector availability.
|
||
- [x] Keep standard smoke deterministic with env cleared.
|
||
- [x] Add server env routing test; helper synthetic UIA smoke covers the local write/click action.
|
||
- [x] Update docs with minimal usage.
|
||
|
||
## Task 5: Verification, commit, push
|
||
|
||
- [x] Run `git diff --check`.
|
||
- [x] Run `go test ./...`.
|
||
- [x] Run `go build ./cmd/isphere-mcp` then remove root binary.
|
||
- [x] Run `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-win-helper.ps1`.
|
||
- [x] Run `powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1`.
|
||
- [x] Commit and push branch `codex/a-route-rpa-send`.
|
||
|
||
## Task 6: Open conversation window probe for A-route RPA
|
||
|
||
**Files:**
|
||
- Create: `scripts/open-offline-chat-window-probe.ps1`
|
||
- Create: `scripts/test-open-offline-chat-window-probe.ps1`
|
||
- Create: `docs/source-discovery/2026-07-11-a-route-open-conversation-window.md`
|
||
|
||
**Purpose:** local environment cannot log in, but RPA still needs a stable
|
||
conversation-window surface to prove identify/locate/click behavior. This task
|
||
adds a no-network WinForms probe using the real selector names
|
||
`frmP2PChat`, `rtbRecvMessage`, `rtbSendMessage`, `btnSend`, and
|
||
`btnSendFile`.
|
||
|
||
- [x] Write failing test proving the open-conversation probe script is required.
|
||
- [x] Implement the offline chat-window probe.
|
||
- [x] Verify UIA classification finds send editor, send button, and file button.
|
||
- [x] Verify `-ProbeClick` writes text and clicks `btnSend`.
|
||
- [x] Verify marker says `sent_real_message=false` and `uploaded_real_file=false`.
|
||
- [x] Document the then-current direct-construction blocker; Task 7 supersedes this by opening the real `frmP2PChat` with a fuller offline dependency harness.
|
||
|
||
## Task 7: Replace synthetic-only proof with real offline `frmP2PChat`
|
||
|
||
**Files:**
|
||
- Create: `scripts/open-offline-real-frmP2PChat.ps1`
|
||
- Create: `scripts/extract-frmP2PChat-il-risk.ps1`
|
||
- Create: `scripts/test-extract-frmP2PChat-il-risk.ps1`
|
||
- Create: `scripts/test-open-offline-real-frmP2PChat-contract.ps1`
|
||
- Create: `docs/source-discovery/2026-07-11-a-route-open-real-chat-window.md`
|
||
|
||
**Purpose:** local machine still cannot log in, but RPA validation should run
|
||
against a real client chat form instead of only a synthetic WinForms probe.
|
||
|
||
- [x] Extract constructor/load IL risks for `frmP2PChat`.
|
||
- [x] Build an offline dependency harness that can construct and show the real `frmP2PChat`.
|
||
- [x] Confirm UIA root `automation_id=frmP2PChat`.
|
||
- [x] Confirm send editor `automation_id=rtbSendMessage`.
|
||
- [x] Confirm send button `automation_id=btnSend`.
|
||
- [x] Confirm receive area `automation_id=rtbRecvMessage`.
|
||
- [x] Record that the real offline window shows the expected offline-send blocker.
|
||
- [x] Merge and push the real-window branch to `main`.
|
||
|
||
## Task 8: Corrected next loop after main merge
|
||
|
||
**Business status after Task 7:**
|
||
|
||
- Message send: UI write/click path exists; online delivery is not verified.
|
||
- File send: preview-only; no real upload path is implemented.
|
||
- Receive/search: unchanged from R14; basic digital-employee read/search remains usable through local-readonly evidence paths.
|
||
|
||
**Next implementation slices:**
|
||
|
||
- [ ] Re-check B-route sidecar / in-process connector / existing API feasibility before promoting any RPA path.
|
||
- [ ] Add a real-window A-route smoke that opens `frmP2PChat`, passes its HWND into the MCP `uia_rpa` connector, writes a unique text, clicks `btnSend`, and records sanitized UI evidence; treat this as backup readiness only.
|
||
- [ ] Add an online/logged-in verification package for message send: first target B-route evidence; include A-route evidence only as a fallback comparison path.
|
||
- [ ] Keep default `verify-go-mcp.ps1` preview/blocked unless explicit A-route env is set, so CI does not depend on a desktop login.
|
||
- [ ] Start a separate file-send RPA locator node: identify the real toolbar/menu path for file attach because `btnSendFile` was not exposed in the real offline UIA dump.
|
||
- [ ] Only after file locator proof, add file upload action and online file-send evidence package.
|
||
- [x] Create `docs/reports/2026-07-12-main-business-status-correction.md` separating “UI action ready” from “business delivery ready”.
|