From 0bb07c7754c0ba78390c32c2eabbe71760738523 Mon Sep 17 00:00:00 2001 From: zhaoyilun Date: Sun, 12 Jul 2026 01:29:07 +0800 Subject: [PATCH] docs: clarify rpa fallback priority --- docs/current-status-card.md | 9 ++++++++- docs/go-mcp-runbook.md | 3 ++- .../2026-07-12-main-business-status-correction.md | 10 ++++++---- docs/source-discovery/capability-source-matrix.md | 4 +++- docs/superpowers/plans/2026-07-11-a-route-rpa-send.md | 8 +++++--- 5 files changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/current-status-card.md b/docs/current-status-card.md index 2b21b03..87aa9dd 100644 --- a/docs/current-status-card.md +++ b/docs/current-status-card.md @@ -11,6 +11,12 @@ Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-repor 后续研发主线切换为 MCP 核心通信能力：搜索联系人、搜索群组、收发消息、收发文件。现有 UIA/selector/report 只作为底层辅助和证据，不再作为主线继续扩展。 +Route priority is explicit: + +1. Primary route: B-route running-client sidecar / in-process connector / existing API that reuses the logged-in `IMPlatformClient.exe` runtime. +2. Secondary route: existing bridge, local service, local data, log, cache, or database source where it can satisfy the MCP contract. +3. Backup route only: A-route/RPA/UIA. Use it to keep the product moving when the B-route is blocked or temporarily untestable, but do not promote it above B-route as the default product architecture. + ## Current completed state - Go MCP foundation exists: `cmd/isphere-mcp`, `internal/mcpserver`, `internal/helperclient`, and `internal/tools` build a stdio MCP server. @@ -61,7 +67,7 @@ N13/N14/N15 are pre-business validation results. They can help identify UI eleme ## Current loop -Current loop: `A-route real chat window merged to main`; next step is evidence-driven send/file production verification. +Current loop: `A-route real chat window merged to main`; next step is evidence-driven B-route send/file production verification, with A-route/RPA kept as backup readiness. Active continuous execution plan: `docs/superpowers/plans/2026-07-11-a-route-rpa-send.md`. @@ -393,6 +399,7 @@ R14 release-candidate report is complete: A-route UIA send work has been merged into `main`: +- Route positioning: A-route/RPA is a fallback, not the primary product route. B-route sidecar/API connector evidence remains the preferred path for real send/file capability. - User direction: do not add a product approval gate; implement function first and let the digital employee layer decide when to call it. - Added plan `docs\superpowers\plans\2026-07-11-a-route-rpa-send.md`. - Go connector request now carries raw `ContentText` only to the action connector; response and audit remain redacted. diff --git a/docs/go-mcp-runbook.md b/docs/go-mcp-runbook.md index 2e469e1..daade94 100644 --- a/docs/go-mcp-runbook.md +++ b/docs/go-mcp-runbook.md @@ -563,6 +563,7 @@ Current short answer: - 已完成：搜索联系人、搜索群组、收消息基础读取、收文件列表。 - 可预览：发消息 preview、发文件 preview。 +- A-route/RPA 是备选兜底，不是主线；主线仍是 B-route running-client sidecar / in-process connector / existing API。 - A-route 已具备 UI 动作能力：显式配置后可以对聊天窗口写入文本并点击发送按钮；本地还可打开真实离线 `frmP2PChat` 验证窗口/输入框/按钮定位。 - 阻断：在线业务送达、真实文件下载、生产发文件。离线点击不等于服务端发送成功。 @@ -577,7 +578,7 @@ They are generated under ignored `runs\` and are not committed. ## 18. A-route UIA send connector -A-route is the UI Automation fallback for text sending when the B-route sidecar cannot be tested. It is function-first: there is no human approval ID gate inside the connector. The digital employee layer is responsible for deciding when to call production mode. +A-route is the UI Automation fallback for text sending when the B-route sidecar cannot be tested. It is function-first, but it is not the primary architecture. Prefer B-route running-client sidecar / in-process connector / existing API evidence whenever that route is available. There is no human approval ID gate inside the connector; the digital employee layer is responsible for deciding when to call production mode. Local verification uses a synthetic WinForms window: diff --git a/docs/reports/2026-07-12-main-business-status-correction.md b/docs/reports/2026-07-12-main-business-status-correction.md index c51cb77..20edcbb 100644 --- a/docs/reports/2026-07-12-main-business-status-correction.md +++ b/docs/reports/2026-07-12-main-business-status-correction.md @@ -13,6 +13,7 @@ ## A-route 合并后的精确定义 +- 路线定位：B-route/运行客户端 sidecar/API connector 仍是主线；A-route/RPA 只是备选兜底，不作为默认产品架构。 - 已实现：打开真实离线 `frmP2PChat`，识别 `rtbSendMessage`、`btnSend`、`rtbRecvMessage`。 - 已实现：`uia_send_message` 可以写入发送框并触发发送按钮。 - 未证明：在线登录态下消息被服务端接受、对方收到、或本地 sent-record 产生。 @@ -20,10 +21,11 @@ ## 后续计划 -1. 本地 smoke：把真实 `frmP2PChat` HWND 接入 `isphere_send_message` 的 `uia_rpa` connector，形成可重复 UI action 验证。 -2. 在线消息验证：在可登录环境采集 before/after sent-record、content hash、ack/成功提示、idempotency 不重复发送证据。 -3. 文件发送节点：单独定位真实工具栏/菜单里的文件按钮，再做上传动作和在线 evidence package。 -4. 更新业务 smoke：把 `send_message_ui_action_ready` 与 `send_message_business_delivery_ready` 拆成两个字段。 +1. 主线优先：继续验证 B-route running-client sidecar / in-process connector / existing API 的真实发送和文件能力。 +2. 备选保持：把真实 `frmP2PChat` HWND 接入 `isphere_send_message` 的 `uia_rpa` connector，形成可重复 UI action smoke，但只作为 B-route 卡住时的兜底。 +3. 在线消息验证：在可登录环境采集 before/after sent-record、content hash、ack/成功提示、idempotency 不重复发送证据。 +4. 文件发送节点：优先找 B-route 上传/发送 connector；如果继续卡住，再单独定位真实工具栏/菜单里的文件按钮，做 RPA 上传动作和在线 evidence package。 +5. 更新业务 smoke：把 `send_message_ui_action_ready` 与 `send_message_business_delivery_ready` 拆成两个字段。 ## 对外口径 diff --git a/docs/source-discovery/capability-source-matrix.md b/docs/source-discovery/capability-source-matrix.md index 2b6b7a3..e328e96 100644 --- a/docs/source-discovery/capability-source-matrix.md +++ b/docs/source-discovery/capability-source-matrix.md @@ -27,6 +27,8 @@ A-route real offline chat window: `docs/source-discovery/2026-07-11-a-route-open 5. Network/protocol source. 6. Mock source for tests only. +Route rule: UIA helper / A-route / RPA is a backup route only. It can preserve delivery momentum while B-route is blocked or untestable, but B-route sidecar/API evidence remains the preferred path for production send and file capability. + ## Matrix | MCP tool | Primary source | Fallback source | Evidence file | Decision status | Next implementation slice | @@ -35,7 +37,7 @@ A-route real offline chat window: `docs/source-discovery/2026-07-11-a-route-open | `isphere_search_contacts` | bare sender/receiver JIDs extracted from normalized log-backed messages loaded from configured PacketReader file or directory source | validated copied `MsgLib.db` tables: `TD_Roster`, `TD_CustomEffigy`, `tblRecent`, `tblChatLevel`, `tblPersonMsg`; decrypted roster/contact stanzas from `Smark.SendReceive`; UIA helper source if display names are still missing | `docs/source-discovery/2026-07-10-msglib-readonly-schema-extraction.md`; `internal/isphere/contacts_test.go`; `internal/tools/isphere_contacts_test.go` | C34 documents optional MsgLib contact display enrichment; R2 adds deterministic exact-match-first ranking, case-insensitive de-duplication across log/MsgLib candidates, and preserves `source`/`raw_ref` | core contact search complete; optional richer fields later | | `isphere_search_groups` | decrypted `PacketReader.ProcessPacket` `type="groupchat"` stanzas and conference/MUC JIDs loaded from configured PacketReader file or directory source | validated copied `MsgLib.db` tables: `tblMsgGroupPersonMsg`, `TD_WorkGroupAuth`, `tblRecent`; UIA helper source if group display names are still missing | `docs/source-discovery/2026-07-10-msglib-readonly-schema-extraction.md`; `internal/isphere/groups_test.go`; `internal/tools/isphere_groups_test.go`; C9 ignored-log scan: PacketReader 86 groupchat/86 conference hits; Smark 24 groupchat/658 conference/631 muc hits | C34 documents optional MsgLib group display enrichment; R2 adds deterministic exact-match-first ranking, case-insensitive de-duplication across log/MsgLib candidates, and preserves `source`/`raw_ref` | core group search complete; optional member/owner hierarchy later | | `isphere_receive_files` | decrypted `PacketReader.ProcessPacket` file-transfer message stanzas via `internal/isphere.ListFilesFromMessages` and `isphere_receive_files` list mode; configured PacketReader file or directory source; `zyl\importal\` cache entries remain unlinked | MsgLib `TD_ReceiveFileRecord` safe metadata through explicit copied-DB path; decrypted `Smark.SendReceive` and `SaveToDB` traces for file-reference reconciliation; future UIA/client connector for download | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#c12-file-transfer-evidence-precheck`; `docs/source-discovery/2026-07-10-file-download-mapping-precheck.md`; `docs/source-discovery/2026-07-10-file-cache-mapping-diagnostic.md`; `docs/source-discovery/2026-07-10-file-download-mapping-v2.md`; `docs/reports/2026-07-10-business-goals-smoke.md` | C22 verifies safe file-list contract args; R10 proves resolver scoring with fixture accepted matches; R11 adds structured download preview with `blocked`/`planned` status and side-effect flags false; R13/R14 confirms list is ready but real download is still blocked. | blocked for real download pending accepted real cache mapping and copy gate; list mode is complete | -| `isphere_send_message` | B-route selected: running-client sidecar / in-process connector, preferring `AppContextManager.SendTxtMessageByJid(...)` or `MessageScheduling.SendChatMessage(...)` over the unimplemented `SendP2PMessage(...)` interface path; default MCP tool still exposes preview/dry-run unless an explicit connector mode is configured | A-route fallback is now implemented for UI action: `ISPHERE_SEND_CONNECTOR_MODE=uia_rpa` calls WinHelper `uia_send_message` against a configured HWND, writes `rtbSendMessage`, and clicks `btnSend`; network/protocol replay remains deferred | `docs/source-discovery/2026-07-10-send-message-source-precheck.md`; `docs/source-discovery/2026-07-10-send-message-connector-selection.md`; `docs/source-discovery/2026-07-10-send-sidecar-b-first-plan.md`; `docs/source-discovery/2026-07-10-returned-live-probe-analysis.md`; `docs/source-discovery/2026-07-10-send-connector-preflight.md`; `docs/source-discovery/2026-07-10-send-sandbox-gate.md`; `docs/source-discovery/2026-07-10-returned-send-sandbox-analysis.md`; `docs/source-discovery/2026-07-10-returned-send-sandbox-analysis-v2.md`; `docs/source-discovery/2026-07-10-returned-send-sent-record-diagnostic.md`; `docs/source-discovery/2026-07-11-a-route-uia-send.md`; `docs/source-discovery/2026-07-11-a-route-open-real-chat-window.md`; `internal/tools/isphere_send_message_test.go`; `cmd/isphere-capability-smoke/main.go`; `docs/reports/2026-07-10-business-goals-smoke.md` | R6f-R6l define connector contract, audit/idempotency replay, production gate, B-route shell, strict-v2 package, and explicit production closure. R10a validates two returned sent-record packages as manual-only evidence. A-route adds local UI action readiness: synthetic window proof plus real offline `frmP2PChat` open/write/click target proof. Business delivery is still not verified because local runtime is offline and no success/ack or sent-record hash evidence has passed. | UI action ready when explicitly configured; business send remains blocked until online sent-record/content-hash/ack evidence passes | +| `isphere_send_message` | B-route selected: running-client sidecar / in-process connector, preferring `AppContextManager.SendTxtMessageByJid(...)` or `MessageScheduling.SendChatMessage(...)` over the unimplemented `SendP2PMessage(...)` interface path; default MCP tool still exposes preview/dry-run unless an explicit connector mode is configured | A-route fallback is now implemented for UI action: `ISPHERE_SEND_CONNECTOR_MODE=uia_rpa` calls WinHelper `uia_send_message` against a configured HWND, writes `rtbSendMessage`, and clicks `btnSend`; this stays backup-only and network/protocol replay remains deferred | `docs/source-discovery/2026-07-10-send-message-source-precheck.md`; `docs/source-discovery/2026-07-10-send-message-connector-selection.md`; `docs/source-discovery/2026-07-10-send-sidecar-b-first-plan.md`; `docs/source-discovery/2026-07-10-returned-live-probe-analysis.md`; `docs/source-discovery/2026-07-10-send-connector-preflight.md`; `docs/source-discovery/2026-07-10-send-sandbox-gate.md`; `docs/source-discovery/2026-07-10-returned-send-sandbox-analysis.md`; `docs/source-discovery/2026-07-10-returned-send-sandbox-analysis-v2.md`; `docs/source-discovery/2026-07-10-returned-send-sent-record-diagnostic.md`; `docs/source-discovery/2026-07-11-a-route-uia-send.md`; `docs/source-discovery/2026-07-11-a-route-open-real-chat-window.md`; `internal/tools/isphere_send_message_test.go`; `cmd/isphere-capability-smoke/main.go`; `docs/reports/2026-07-10-business-goals-smoke.md` | R6f-R6l define connector contract, audit/idempotency replay, production gate, B-route shell, strict-v2 package, and explicit production closure. R10a validates two returned sent-record packages as manual-only evidence. A-route adds local UI action readiness: synthetic window proof plus real offline `frmP2PChat` open/write/click target proof. Business delivery is still not verified because local runtime is offline and no success/ack or sent-record hash evidence has passed. | B-route evidence remains next priority; A-route UI action is backup-ready only; business send remains blocked until online sent-record/content-hash/ack evidence passes | | `isphere_send_file` | B-route selected after send-message probe: managed offline-file path through `OffLineFileSend.sendFile()`, `IMPP.Service*.dll` `IFileTransfer.FileUpload(...)`, and `Chat.sendFileMessage(...)`; current MCP tool exposes preview/dry-run only | A-route file fallback is not implemented yet; real offline UIA dump did not expose stable `btnSendFile`, so the next fallback slice is toolbar/menu locator discovery; native `TcpFileTransfer.dll` is a later candidate only after managed path is rejected | `docs/source-discovery/2026-07-10-send-message-source-precheck.md`; `docs/source-discovery/2026-07-10-send-message-connector-selection.md`; `docs/source-discovery/2026-07-10-send-sidecar-b-first-plan.md`; `docs/source-discovery/2026-07-10-returned-live-probe-analysis.md`; `docs/source-discovery/2026-07-10-send-connector-preflight.md`; `docs/source-discovery/2026-07-10-send-file-sandbox-gate.md`; `docs/source-discovery/2026-07-11-a-route-open-real-chat-window.md`; `internal/tools/isphere_files_test.go`; `docs/reports/2026-07-10-business-goals-smoke.md` | R7 registers send-file preview as the tenth MCP tool; R8 adds audit/idempotency duplicate/conflict hardening without raw file paths/content; R9 builds and verifies the online send-file evidence package; R13/R14 confirms preview is ready and production upload remains blocked. A-route real-window work confirms file-button automation still needs a separate locator node. | blocked until file toolbar/menu locator is found and returned file-send package proves upload/sent evidence | ## Stage C entry rule diff --git a/docs/superpowers/plans/2026-07-11-a-route-rpa-send.md b/docs/superpowers/plans/2026-07-11-a-route-rpa-send.md index 8bee816..b1929eb 100644 --- a/docs/superpowers/plans/2026-07-11-a-route-rpa-send.md +++ b/docs/superpowers/plans/2026-07-11-a-route-rpa-send.md @@ -2,7 +2,7 @@ > **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 动作，不等于业务送达。 +**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 功能兜底。 @@ -17,6 +17,7 @@ - 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. --- @@ -146,8 +147,9 @@ against a real client chat form instead of only a synthetic WinForms probe. **Next implementation slices:** -- [ ] 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. -- [ ] Add an online/logged-in verification package for A-route message send: before/after sent-record capture, content-hash match, success/ack or sent-record proof, and duplicate-idempotency no-second-send check. +- [ ] 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.