docs: prepare mcp source discovery loop
This commit is contained in:
zhaoyilun
@@ -2,7 +2,8 @@
|
|||||||
|
|
||||||
Date: 2026-07-09
|
Date: 2026-07-09
|
||||||
Branch: `main`
|
Branch: `main`
|
||||||
HEAD: `b2d839e (HEAD -> main, gitea/main, gitea/HEAD) Merge branch 'codex/n15-report-hardening'`
|
Loop base: `e993ce1 docs: trim safety constraints from mcp roadmap`
|
||||||
|
Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-report-hardening'`
|
||||||
|
|
||||||
## Business direction
|
## Business direction
|
||||||
|
|
||||||
@@ -44,14 +45,26 @@ HEAD: `b2d839e (HEAD -> main, gitea/main, gitea/HEAD) Merge branch 'codex/n15-re
|
|||||||
|
|
||||||
N13/N14/N15 are pre-business validation results. They can help identify UI elements and validate reports if UI automation becomes necessary, but they are not the product route. New work should first validate real business capability sources and core MCP tool contracts.
|
N13/N14/N15 are pre-business validation results. They can help identify UI elements and validate reports if UI automation becomes necessary, but they are not the product route. New work should first validate real business capability sources and core MCP tool contracts.
|
||||||
|
|
||||||
## Next business mainline
|
## Current loop
|
||||||
|
|
||||||
1. Freeze the MCP core tools contract in `docs/mcp-core-tools-contract.md`.
|
Current loop: `Stage B1 - source discovery from N12-pre zyl package`.
|
||||||
2. Discover the best real capability source for:
|
|
||||||
|
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_contacts`
|
||||||
- `isphere_search_groups`
|
- `isphere_search_groups`
|
||||||
- `isphere_receive_messages`
|
- `isphere_receive_messages`
|
||||||
- `isphere_receive_files`
|
- `isphere_receive_files`
|
||||||
3. Build the read-only loop first.
|
3. Selected first Stage C implementation slice.
|
||||||
|
|
||||||
|
## Next business mainline
|
||||||
|
|
||||||
|
1. Complete Stage B1 evidence index and capability-source matrix.
|
||||||
|
2. Open Stage C with `isphere_receive_messages` as the first likely slice if evidence supports it.
|
||||||
|
3. Add contact/group/file read tools after their source decisions are recorded.
|
||||||
4. Add `isphere_send_message` and `isphere_send_file` after source discovery and connector selection.
|
4. Add `isphere_send_message` and `isphere_send_file` after source discovery and connector selection.
|
||||||
5. Keep UIA selector/report work as fallback support, not as the primary roadmap.
|
5. Keep UIA selector/report work as fallback support, not as the primary roadmap.
|
||||||
|
|||||||
39
docs/source-discovery/README.md
Normal file
39
docs/source-discovery/README.md
Normal file
@@ -0,0 +1,39 @@
|
|||||||
|
# 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`.
|
||||||
@@ -0,0 +1,474 @@
|
|||||||
|
# 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:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
git fetch gitea
|
||||||
|
git status --short --branch
|
||||||
|
git log --oneline -3
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected:
|
||||||
|
|
||||||
|
```text
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
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:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
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:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
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:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
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`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
Select-String -LiteralPath docs\source-discovery\2026-07-09-n12-pre-zyl-index.md -Pattern '待补|占位'
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: no output.
|
||||||
|
|
||||||
|
- [ ] **Step 4: Commit Task 2**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
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:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
Select-String -LiteralPath docs\source-discovery\capability-source-matrix.md -Pattern '待补|占位'
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: no output.
|
||||||
|
|
||||||
|
- [ ] **Step 3: Commit Task 3**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
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:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
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:
|
||||||
|
|
||||||
|
```go
|
||||||
|
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:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
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`:
|
||||||
|
|
||||||
|
```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:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
go test ./internal/isphere -run TestMockMessageSourceReturnsNormalizedMessages -v
|
||||||
|
```
|
||||||
|
|
||||||
|
Expected: PASS.
|
||||||
|
|
||||||
|
- [ ] **Step 5: Commit Task 4 source abstraction**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
|
||||||
|
```powershell
|
||||||
|
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
Block a user