bugfix

README.md

@@ -595,6 +595,160 @@ uv run --python 3.13 python scripts/smoke_test.py search-points --project-key de
 2. 再运行 `list-locations` 或 `list-system-tree`，确认配置接口可访问
 3. 最后运行 `search-devices`、`search-meters` 或 `search-points` 做正式搜索
 
+## 使用 OpenCode CLI 隔离测试本地 MCP
+
+如果需要另起一个命令行版 `opencode` 来测试本地 MCP，建议始终使用“隔离数据库 + 隔离用户目录”的方式启动，避免影响当前桌面版 OpenCode 正在使用的会话数据库。
+
+### 为什么要隔离
+
+如果直接在当前桌面版 OpenCode 环境里再启动 `opencode run`，可能会遇到以下问题：
+
+- 复用桌面版注入的环境变量
+- 命中桌面版当前 session 状态
+- 报 `Session not found`
+- 干扰当前 GUI 会话状态
+
+因此，命令行测试时不要直接复用桌面版进程环境。
+
+### 前提条件
+
+1. 本地 MCP 服务已经启动，例如：
+
+```powershell
+uv run --python 3.13 python -m instrument_config_mcp
+```
+
+默认地址：`http://127.0.0.1:8500/mcp`
+
+2. 当前机器上已经存在可用的 OpenCode 认证文件：
+
+```text
+C:\Users\Guangyu\.local\share\opencode\auth.json
+```
+
+如果 `openai-gw` 需要鉴权，命令行隔离环境里也要提供这份文件。
+
+### 推荐测试步骤
+
+下面的步骤会创建一套临时 OpenCode 用户目录，并把 `auth.json` 复制进去。这样可以保证：
+
+- 不会写入当前主会话数据库
+- 不会复用桌面版当前 session 状态
+- 仍然可以使用 `openai-gw` 鉴权
+
+#### 1. 准备隔离目录
+
+```powershell
+$root = 'C:\Users\Guangyu\AppData\Local\Temp\oc-userprofile-openai-gw'
+New-Item -ItemType Directory -Force -Path "$root\.local\share\opencode","$root\.cache","$root\AppData\Roaming","$root\AppData\Local" | Out-Null
+Copy-Item 'C:\Users\Guangyu\.local\share\opencode\auth.json' "$root\.local\share\opencode\auth.json" -Force
+```
+
+#### 2. 清掉桌面版注入的 OpenCode 环境变量
+
+这一组环境变量如果被继承，`opencode run` 可能会直接报 `Session not found`：
+
+```powershell
+Remove-Item Env:OPENCODE_SERVER_PASSWORD -ErrorAction SilentlyContinue
+Remove-Item Env:OPENCODE_SERVER_USERNAME -ErrorAction SilentlyContinue
+Remove-Item Env:OPENCODE_CLIENT -ErrorAction SilentlyContinue
+Remove-Item Env:OPENCODE_PID -ErrorAction SilentlyContinue
+Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue
+```
+
+#### 3. 设置隔离环境变量
+
+```powershell
+$env:USERPROFILE = $root
+$env:HOMEDRIVE = 'C:'
+$env:HOMEPATH = '\Users\Guangyu\AppData\Local\Temp\oc-userprofile-openai-gw'
+$env:HOME = $root
+$env:XDG_CONFIG_HOME = 'C:\Users\Guangyu\.config'
+$env:XDG_DATA_HOME = "$root\.local\share"
+$env:XDG_CACHE_HOME = "$root\.cache"
+$env:APPDATA = "$root\AppData\Roaming"
+$env:LOCALAPPDATA = "$root\AppData\Local"
+```
+
+#### 4. 确认当前命令会写到隔离数据库
+
+```powershell
+opencode db path
+```
+
+输出应类似：
+
+```text
+C:\Users\Guangyu\AppData\Local\Temp\oc-userprofile-openai-gw\.local\share\opencode\opencode.db
+```
+
+如果这里仍然指向默认的 `C:\Users\Guangyu\.local\share\opencode\opencode.db`，说明隔离没有生效，不要继续测试。
+
+#### 5. 用 `openai-gw` 跑最小化 MCP 测试
+
+例如先验证 `project.list`：
+
+```powershell
+opencode --pure run --format json --print-logs --log-level INFO --model openai-gw/gpt-5.4 --agent build --dir "C:\Guangyu\Projects\instrument-data-mcp" "调用 instrument-config-local MCP 的 project.list 工具列出项目，然后停止。不要修改任何文件。"
+```
+
+如果要测试拓扑工具，可以改成：
+
+```powershell
+opencode --pure run --format json --print-logs --log-level INFO --model openai-gw/gpt-5.4 --agent build --dir "C:\Guangyu\Projects\instrument-data-mcp" "调用 instrument-config-local MCP 的 topology.group_list 和 topology.list。参数 project_key=topo-test。只用一句话总结分组数量、拓扑数量，以及前 3 个 topology_id。不要修改文件，不要做额外操作。"
+```
+
+### 建议的测试顺序
+
+1. 先确认本地 MCP 服务已启动
+2. 再确认 `opencode db path` 指向临时目录
+3. 再测试 `project.list`
+4. 再测试 `topology.group_list` / `topology.list`
+5. 最后测试 `topology.find_context` / `topology.get_node`
+
+### 常见错误
+
+#### 1. `Session not found`
+
+通常不是 MCP 服务的问题，而是命令行继承了桌面版 OpenCode 注入的环境变量。
+
+优先检查：
+
+- 是否清除了 `OPENCODE_SERVER_PASSWORD`
+- 是否清除了 `OPENCODE_SERVER_USERNAME`
+- 是否清除了 `OPENCODE_CLIENT`
+- 是否清除了 `OPENCODE_PID`
+- `opencode db path` 是否真的指向临时目录
+
+#### 2. `401 Invalid secret key`
+
+说明隔离环境里没有可用的 `auth.json`，或者 `openai-gw` 凭证没有被复制到隔离数据目录。
+
+优先检查：
+
+- `C:\Users\Guangyu\.local\share\opencode\auth.json` 是否存在
+- 是否已复制到 `$root\.local\share\opencode\auth.json`
+
+#### 3. 命令行能启动，但 MCP 没连接
+
+优先检查本地 MCP 是否真的在监听：
+
+```powershell
+Invoke-WebRequest -UseBasicParsing 'http://127.0.0.1:8500/mcp' -Method Post -ContentType 'application/json' -Body '{}'
+```
+
+只要不是“无法连接到远程服务器”，通常说明服务已经起来了。
+
+### 不建议的做法
+
+不要直接在桌面版 OpenCode 已打开的同一个环境里运行：
+
+```powershell
+opencode run ...
+```
+
+尤其不要在未隔离 `USERPROFILE/HOME/XDG_DATA_HOME` 的情况下直接测试，否则有机会干扰当前 GUI 会话数据库或命中桌面版 session 状态。
+
 ## 常见问题
 
 ### 1. `project_key not found`

instrument_config_mcp/topology_cache.py

@@ -731,6 +731,16 @@ def _has_topology_cache(session: Session, project_key: str) -> bool:
     return bool(registry_rows)
 
 
+def _require_topology_cache(session: Session, project_key: str) -> None:
+    if _has_topology_cache(session, project_key):
+        return
+    raise ValueError(
+        f"Project '{project_key}' has no cached topologies. Refresh it via "
+        f"GET /topology/cache/refresh?project_key={project_key}. If the refresh "
+        "already succeeded, the upstream project likely has no topology data."
+    )
+
+
 def list_topology_groups(project_key: str) -> dict[str, Any]:
     project_key = _text(project_key)
     if not project_key: