admin/isphere-ai-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b2ce7b0e36f6b90f10823478a9df652ecb9e712a
isphere-ai-bridge/docs/superpowers/plans/2026-07-09-mcp-core-source-discovery-loop.md
zhaoyilun 0a7b9d8596 docs: prepare mcp source discovery loop
2026-07-09 22:16:29 +08:00

18 KiB
Raw Blame History

MCP Core Source Discovery Loop 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: Prepare and execute the next development loop: turn the downloaded N12-pre evidence package into source decisions for the MCP core contact/group/message/file tools.

Architecture: The next loop is Stage B source discovery before Stage C implementation. It inventories copied iSphere / IMPlatformClient evidence, records capability-source decisions, then opens the first implementation slice only after the selected source is clear.

Tech Stack: Go 1.23.4, PowerShell, 7-Zip, Markdown decision records, existing Go MCP server, existing C# WinHelper.

Global Constraints

  • Repository root: E:\coding\codex\isphere-ai-bridge.
  • Remote name: gitea; active branch: main; local starting commit for this plan: e993ce1.
  • Code search rule from AGENTS.md: use git ls-files, ag, or grep -R; do not use rg.
  • Evidence archive path: E:\coding\codex\isphere-ai-bridge\runs\offline-evidence-intake\zyl-qqfile-20260709\archives\zyl.rar.
  • Evidence SHA256: 126CC72F21293829FED374321A2AFE6E067959B63A76981BCB6678C64E887173.
  • Raw evidence stays under runs/; normal commits contain docs/source/code, not the raw archive.
  • Product route: the six MCP core tools in docs/mcp-core-tools-contract.md.
  • Stage order for this loop: source discovery first, then read-loop implementation, then write capability.
  • Commit cadence: one small commit per accepted loop node.

File Structure

  • Modify: E:\coding\codex\isphere-ai-bridge\docs\current-status-card.md — keep current loop pointer accurate.
  • Create/modify: E:\coding\codex\isphere-ai-bridge\docs\source-discovery\README.md — live loop ledger and working rules for source discovery.
  • Create: E:\coding\codex\isphere-ai-bridge\docs\source-discovery\2026-07-09-n12-pre-zyl-index.md — evidence index extracted from archive metadata and later extraction summaries.
  • Create: E:\coding\codex\isphere-ai-bridge\docs\source-discovery\capability-source-matrix.md — decision table mapping each MCP core tool to primary/fallback source.
  • Later implementation files after decisions are accepted:
    • E:\coding\codex\isphere-ai-bridge\internal\isphere\source.go
    • E:\coding\codex\isphere-ai-bridge\internal\isphere\source_test.go
    • E:\coding\codex\isphere-ai-bridge\internal\tools\isphere_read_tools.go
    • E:\coding\codex\isphere-ai-bridge\internal\tools\isphere_read_tools_test.go

Task 1: Start the source-discovery loop ledger

Files:

  • Modify: E:\coding\codex\isphere-ai-bridge\docs\current-status-card.md
  • Create/modify: E:\coding\codex\isphere-ai-bridge\docs\source-discovery\README.md

Interfaces:

  • Consumes: current Git state, docs/mcp-core-tools-contract.md, docs/mcp-core-business-plan.md.

  • Produces: a single visible loop entry point for the next worker.

  • Step 1: Refresh repo state

Run:

git fetch gitea
git status --short --branch
git log --oneline -3

Expected:

## main...gitea/main [ahead 2]
e993ce1 docs: trim safety constraints from mcp roadmap
cfc7787 docs: realign iSphere bridge around core MCP capabilities
  • Step 2: Update docs/current-status-card.md

Set the loop base line:

Loop base: `e993ce1 docs: trim safety constraints from mcp roadmap`
Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-report-hardening'`

Add this current-loop block:

## Current loop

Current loop: `Stage B1 - source discovery from N12-pre zyl package`.

Plan file: `docs/superpowers/plans/2026-07-09-mcp-core-source-discovery-loop.md`.

Loop output:

1. Evidence index for downloaded `zyl.rar` package.
2. Capability-source matrix for the four read tools:
   - `isphere_search_contacts`
   - `isphere_search_groups`
   - `isphere_receive_messages`
   - `isphere_receive_files`
3. Selected first Stage C implementation slice.
  • Step 3: Create the loop ledger

Create docs/source-discovery/README.md with this content:

# Source Discovery Ledger

Date: 2026-07-09
Current loop: Stage B1 - N12-pre zyl evidence source discovery

## Objective

Find the best real capability source for the MCP core read tools before implementing Stage C.

## Inputs

- `runs/offline-evidence-intake/zyl-qqfile-20260709/archives/zyl.rar`
- `runs/offline-evidence-intake/zyl-qqfile-20260709/metadata/archive-list.txt`
- `runs/offline-evidence-intake/zyl-qqfile-20260709/metadata/sha256.txt`
- `docs/mcp-core-tools-contract.md`
- `docs/mcp-core-business-plan.md`

## Loop cadence

1. Inventory evidence.
2. Identify source candidates.
3. Map candidates to MCP tools.
4. Select primary/fallback source per tool.
5. Open one Stage C implementation slice.
6. Verify with `go test ./...`, `go build ./cmd/isphere-mcp`, and MCP verification script.
7. Commit exact paths.

## Current target order

1. `isphere_receive_messages`
2. `isphere_search_contacts`
3. `isphere_search_groups`
4. `isphere_receive_files`

Reason: message source discovery is the current blocker; contacts/groups can be derived or selected after the message source shape is known.

## Current plan

See `docs/superpowers/plans/2026-07-09-mcp-core-source-discovery-loop.md`.
  • Step 4: Verify docs diff

Run:

git diff --check
git diff -- docs/current-status-card.md docs/source-discovery/README.md

Expected: git diff --check exits 0 and the diff only touches the two listed docs.

  • Step 5: Commit Task 1

Run:

git add -- docs/current-status-card.md docs/source-discovery/README.md
git diff --cached --check
git commit -m "docs: start mcp source discovery loop"

Expected: commit succeeds.

Task 2: Build the N12-pre zyl evidence index

Files:

  • Create: E:\coding\codex\isphere-ai-bridge\docs\source-discovery\2026-07-09-n12-pre-zyl-index.md
  • Read local input: E:\coding\codex\isphere-ai-bridge\runs\offline-evidence-intake\zyl-qqfile-20260709\metadata\archive-list.txt

Interfaces:

  • Consumes: archive metadata, archive-list.txt, sha256.txt.

  • Produces: a reviewable evidence index without committing raw evidence files.

  • Step 1: Confirm archive metadata and candidate paths

Run:

Get-Content -LiteralPath runs\offline-evidence-intake\zyl-qqfile-20260709\metadata\sha256.txt
Select-String -LiteralPath runs\offline-evidence-intake\zyl-qqfile-20260709\metadata\archive-list.txt -Pattern 'MsgLib\.db|Smark\.SendReceive|SaveToDB|PacketReader\.ProcessPacket|LoginInfo|System\.Data\.SQLite|importal\\[0-9a-f]{32}' -CaseSensitive:$false | Select-Object -First 200

Expected: sha256 matches 126CC72F21293829FED374321A2AFE6E067959B63A76981BCB6678C64E887173; candidate file paths are visible.

  • Step 2: Create the evidence index file

Create docs/source-discovery/2026-07-09-n12-pre-zyl-index.md with this concrete starting content, then extend it only with exact paths from archive-list.txt:

# N12-pre zyl Evidence Index

Date: 2026-07-09
Evidence id: `zyl-qqfile-20260709`
Archive: `runs/offline-evidence-intake/zyl-qqfile-20260709/archives/zyl.rar`
SHA256: `126CC72F21293829FED374321A2AFE6E067959B63A76981BCB6678C64E887173`
Archive type: RAR5
Archive listing summary: 3931 files, 439 folders

## Candidate source families

| Family | Evidence path examples | Why it matters | Initial action |
| --- | --- | --- | --- |
| SQLite runtime | `zyl\iSphere\System.Data.SQLite.dll`; `zyl\Impp\System.Data.SQLite.dll` | Confirms bundled SQLite usage around message libraries | record versions and inspect dependent DB files |
| iSphere message DB | `zyl\iSphere\8c5e81a7f6dd1169.10083\27000000\Account\90005981\MsgLib.db`; `zyl\iSphere\8c5e81a7f6dd1169.10083\27000000\Account\duyanming0731\MsgLib.db` | Strong candidate for `isphere_receive_messages`, contacts, groups, and attachment references | extract selected DB copies and inspect schema |
| IMPP message DB | `zyl\Impp\Account\90005981\MsgLib.db`; `zyl\Impp\Account\27091282\MsgLib.db` | Older or parallel candidate source for message history | compare schema with iSphere DB |
| Local communication logs | `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\Smark.SendReceive\2026-07-07_1.log`; `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\SaveToDB\2026-07-07_1.log`; `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\PacketReader.ProcessPacket\2026-07-07_1.log` | Candidate execution trace for message receive/save behavior | inspect log structure and timestamp alignment |
| Login/info logs | `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\LoginInfo\2026-07-07_1.log` | Candidate account/session context for source mapping | inspect field names and account identifiers |
| Received/document cache | `zyl\importal\256914c029af44bd96665abd69ddd500\*.xlsx`; `zyl\importal\4a33b65a33c14149b440724bfc3d912e\g.docx`; `zyl\importal\4fa0846abdbb4331a956cb056be9566a\*.pdf` | Candidate file receive/download cache for `isphere_receive_files` | map hashed directories to DB/log references |

## First extraction target list

| Priority | Archive path | Destination under runs | Reason |
| --- | --- | --- | --- |
| 1 | `zyl\iSphere\8c5e81a7f6dd1169.10083\27000000\Account\90005981\MsgLib.db` | `runs/offline-evidence-intake/zyl-qqfile-20260709/extracted/msgdb-isphere-90005981/` | latest visible iSphere message DB candidate |
| 2 | `zyl\Impp\Account\90005981\MsgLib.db` | `runs/offline-evidence-intake/zyl-qqfile-20260709/extracted/msgdb-impp-90005981/` | compare older or parallel IMPP DB candidate |
| 3 | `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\Smark.SendReceive\2026-07-07_1.log` | `runs/offline-evidence-intake/zyl-qqfile-20260709/extracted/log-smark-90005981-20260707/` | message send/receive trace candidate |
| 4 | `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\SaveToDB\2026-07-07_1.log` | `runs/offline-evidence-intake/zyl-qqfile-20260709/extracted/log-savetodb-90005981-20260707/` | DB write trace candidate |
| 5 | `zyl\importal\localcache\8c5e81a7f6dd1169.10083\27000000\Log\90005981\LoginInfo\2026-07-07_1.log` | `runs/offline-evidence-intake/zyl-qqfile-20260709/extracted/log-logininfo-90005981-20260707/` | account/session context candidate |

## Decision after index

Proceed to `docs/source-discovery/capability-source-matrix.md` after the first extraction target list has confirmed message DB and log candidates.
  • Step 3: Verify index contains concrete candidates

Run:

Select-String -LiteralPath docs\source-discovery\2026-07-09-n12-pre-zyl-index.md -Pattern '待补|占位'

Expected: no output.

  • Step 4: Commit Task 2

Run:

git add -- docs/source-discovery/2026-07-09-n12-pre-zyl-index.md
git diff --cached --check
git commit -m "docs: index n12-pre zyl evidence sources"

Expected: commit succeeds.

Task 3: Create the capability-source matrix

Files:

  • Create: E:\coding\codex\isphere-ai-bridge\docs\source-discovery\capability-source-matrix.md

Interfaces:

  • Consumes: docs/mcp-core-tools-contract.md, docs/source-discovery/2026-07-09-n12-pre-zyl-index.md.

  • Produces: source decisions that Stage C implementation can consume.

  • Step 1: Create the matrix

Create docs/source-discovery/capability-source-matrix.md with this content:

# Capability Source Matrix

Date: 2026-07-09
Stage: B source discovery

## Source priority

1. Existing bridge / API / local service.
2. Local data, log, cache, or database source.
3. UIA helper source through C# WinHelper.
4. Network/protocol source.
5. Mock source for tests only.

## Matrix

| MCP tool | Primary source | Fallback source | Evidence file | Decision status | Next implementation slice |
| --- | --- | --- | --- | --- | --- |
| `isphere_receive_messages` | `zyl\iSphere\8c5e81a7f6dd1169.10083\27000000\Account\90005981\MsgLib.db` | `zyl\Impp\Account\90005981\MsgLib.db` plus `Smark.SendReceive` logs | `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md#first-extraction-target-list` | selected after schema confirms message table | first |
| `isphere_search_contacts` | message DB contact/conversation tables after schema inspection | UIA helper source through current WinHelper if DB lacks display names | `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md#candidate-source-families` | candidate | second |
| `isphere_search_groups` | message DB group/conversation tables after schema inspection | UIA helper source through current WinHelper if DB lacks group display names | `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md#candidate-source-families` | candidate | third |
| `isphere_receive_files` | importal hashed document cache mapped through message DB attachment references | `Smark.SendReceive` and `SaveToDB` logs for file-reference traces | `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md#candidate-source-families` | candidate | fourth |

## Stage C entry rule

Open implementation only after the selected row links to a concrete file or directory in the evidence index and the schema/log inspection notes state which fields map to the MCP output contract.
  • Step 2: Verify the matrix contains concrete candidates

Run:

Select-String -LiteralPath docs\source-discovery\capability-source-matrix.md -Pattern '待补|占位'

Expected: no output.

  • Step 3: Commit Task 3

Run:

git add -- docs/source-discovery/capability-source-matrix.md
git diff --cached --check
git commit -m "docs: select mcp capability sources"

Expected: commit succeeds.

Task 4: Open the first Stage C implementation slice

Files:

  • Create: E:\coding\codex\isphere-ai-bridge\internal\isphere\source.go
  • Create: E:\coding\codex\isphere-ai-bridge\internal\isphere\source_test.go
  • Modify: the current tool registration file found with git ls-files internal | Select-String -Pattern 'tool|mcp|registry|server'.
  • Create/modify: E:\coding\codex\isphere-ai-bridge\internal\tools\isphere_read_tools_test.go

Interfaces:

  • Consumes: selected source row for isphere_receive_messages.

  • Produces: first business MCP tool skeleton with normalized JSON and audit object.

  • Step 1: Locate current tool registration

Run:

git ls-files internal | Select-String -Pattern 'tool|mcp|registry|server'

Expected: the file that registers win_helper_version, win_helper_self_check, win_helper_scan_windows, and win_helper_dump_uia is visible.

  • Step 2: Write failing test for source abstraction

Create internal/isphere/source_test.go with this test:

package isphere

import (
    "context"
    "testing"
)

func TestMockMessageSourceReturnsNormalizedMessages(t *testing.T) {
    src := MockMessageSource{
        Messages: []Message{
            {
                ID:             "msg-1",
                ConversationID: "conv-1",
                SenderName:     "测试用户",
                Text:           "hello",
            },
        },
    }

    got, err := src.ReceiveMessages(context.Background(), ReceiveMessagesQuery{ConversationID: "conv-1", Limit: 10})
    if err != nil {
        t.Fatalf("ReceiveMessages returned error: %v", err)
    }
    if len(got.Messages) != 1 {
        t.Fatalf("message count = %d, want 1", len(got.Messages))
    }
    if got.Messages[0].ID != "msg-1" || got.Messages[0].ConversationID != "conv-1" {
        t.Fatalf("unexpected message: %+v", got.Messages[0])
    }
}

Run:

go test ./internal/isphere -run TestMockMessageSourceReturnsNormalizedMessages -v

Expected: FAIL because package/types do not exist yet.

  • Step 3: Implement minimal source abstraction

Create internal/isphere/source.go:

package isphere

import "context"

type Message struct {
    ID             string `json:"message_id"`
    ConversationID string `json:"conversation_id"`
    SenderName     string `json:"sender_name"`
    Text           string `json:"text"`
}

type ReceiveMessagesQuery struct {
    ConversationID string
    Limit          int
}

type ReceiveMessagesResult struct {
    Messages []Message `json:"messages"`
}

type MessageSource interface {
    ReceiveMessages(ctx context.Context, query ReceiveMessagesQuery) (ReceiveMessagesResult, error)
}

type MockMessageSource struct {
    Messages []Message
}

func (s MockMessageSource) ReceiveMessages(ctx context.Context, query ReceiveMessagesQuery) (ReceiveMessagesResult, error) {
    if query.Limit <= 0 || query.Limit > len(s.Messages) {
        query.Limit = len(s.Messages)
    }
    out := make([]Message, 0, query.Limit)
    for _, msg := range s.Messages {
        if query.ConversationID != "" && msg.ConversationID != query.ConversationID {
            continue
        }
        out = append(out, msg)
        if len(out) == query.Limit {
            break
        }
    }
    return ReceiveMessagesResult{Messages: out}, nil
}
  • Step 4: Verify source abstraction

Run:

go test ./internal/isphere -run TestMockMessageSourceReturnsNormalizedMessages -v

Expected: PASS.

  • Step 5: Commit Task 4 source abstraction

Run:

git add -- internal/isphere/source.go internal/isphere/source_test.go
git diff --cached --check
go test ./...
go build ./cmd/isphere-mcp
git commit -m "feat: add isphere message source abstraction"

Expected: all commands exit 0 and commit succeeds.

Self-Review

  • Spec coverage: this plan covers the next loop requested by the user: source discovery, evidence organization, capability-source selection, and first Stage C entry.
  • Placeholder scan: the plan contains concrete paths and explicit verification commands for future generated docs.
  • Type consistency: MessageSource, ReceiveMessagesQuery, ReceiveMessagesResult, and MockMessageSource are defined before use.

Execution Handoff

Plan saved for the next loop. Recommended execution mode: one node at a time.

  1. Start with Task 1 and Task 2 only.
  2. Stop after the evidence index is concrete.
  3. Ask the business manager to accept the selected first source.
  4. Open Task 3 and Task 4 only after acceptance.
Reference in New Issue View Git Blame Copy Permalink