# WikiBox 调试 MCP 新手使用指南

**从收到兑换码，到完成第一次有依据的故障排查。**

适用于 WikiBox 中心版调试套餐；编写与接口核对日期：2026-09-28。主流程面向新的 `WBA-` 激活码，以 Windows 上的 Codex / Claude Code 为例。你可以把这份文档交给自己的 Agent，让它协助准备环境。

- 接入页：<https://wikibox.eternalchip.com/connect.html>
- Agent 技术说明：<https://wikibox.eternalchip.com/agent-quickstart.html>
- 官方连接器下载：<https://wikibox.eternalchip.com/api/customer/connector>

## 一、先弄清楚：你买到的是什么

你获得的是调试知识服务的访问授权。它能帮助 Agent 查找已有方法、选择排查步骤，并在有设备时协助开展验证。**查到方法不等于已经找到你这块板子的故障原因。**

| 名称 | 人话解释 | 什么时候需要 |
|---|---|---|
| 兑换码 / WBA 激活码 | 发放方交给你的开通凭证，也可用于同套餐续期 | 首次开通或续期时私密输入 |
| 官方连接器 | 代你向中心库出示设备签名的本机程序 | 使用付费授权必须准备 |
| MCP | Agent 调用中心库工具的连接方式 | 按连接器输出配置，不必自己编程 |
| `wikibox` 用户 Skill | 教 Agent 如何查知识、读来源、检查授权与更新 | 日常使用的基本组件 |
| `hil-orchestrator` | 把排查计划、设备操作和验证证据组织起来的 HIL 编排器 | 要连接实物设备开展调试时推荐安装 |
| 设备插件 Skill | 操作对应探针、示波器或 CAN 设备的适配组件 | 按你的实际设备选择安装 |

当前调试套餐的配套组件包括 WikiBox 用户 Skill、HIL 编排器、MKLink、DSCope 示波器和 Toomoss CAN 插件。实际版本与可下载范围以你的授权市场为准；插件不包含实物设备，也不意味着任意型号都受支持。

只查方法、分析日志时，不需要购买或连接硬件，也不必安装全部设备插件。不需要安装管理员 Skill，不需要管理员 Token，日常召回知识也不要求绑定工程。

## 二、收到兑换码后，先做这三件事

1. 确认发放方提供的套餐、授权天数和码的使用截止日期。
2. 确认码的类型：新的购买流程使用 `WBA-` 开头的码；它不是可以填进 MCP 请求头的 Token。
3. 把码留在自己的私密位置，准备在本机终端输入。**不要把码、Token、密码或设备私钥贴进 Agent 聊天，也不要放入项目仓库。**

三个时间容易混淆：

- **码的使用截止日期**：必须在这个日期前激活或用于续期。
- **授权到期日期**：新开授权从激活成功开始，按购买的天数计算。
- **后台发货文件的 15 分钟下载窗口**：这是发放方下载整批码的限制，不是购买者收到码后只有 15 分钟可激活。

如果拿到的是旧版 `WB-` 兑换码或已有普通 Token，不要强套本指南的 WBA 激活步骤。请发放方确认交付类型，并按接入页的兼容入口处理。`WBE-` 是短期设备登记/换机码，也不等于新购套餐码。

## 三、最省心的方式：先把这段话交给 Agent

先打开已经能够正常对话的 Codex 或 Claude Code，把下面这段话复制进去。这里不需要填写你的兑换码。

> 请按《WikiBox 调试 MCP 新手使用指南》帮我接入中心版 https://wikibox.eternalchip.com。我持有 WBA- 调试套餐激活码，请先检查我的客户端、Python 和现有 WikiBox 配置，再从本站下载官方连接器、准备隔离环境。到输入激活码时，让我在本机可交互终端私密输入，不要让我贴进聊天。激活后保留配置编号和授权编号，使用连接器输出的 command/args 配置 MCP，安装 wikibox 用户 Skill，并验证身份、有效期和一次带来源的知识召回。已有连接请复用，不要重复激活；暂时不要操作硬件。

Agent 负责准备环境、下载、配置和检查。你主要做三件事：私密输入码、完成客户端正常的信任/重载操作、描述自己的实际问题。

**如果 Agent 没有能让你私密输入的交互终端**，由你打开本机 PowerShell 执行下一节的激活命令。不要为了省一步，把码粘进聊天或普通工具调用参数。

## 四、第一次安装与激活：一步一步来

### 第 1 步：准备电脑与连接器

当前完整接入路径主要验证过 Windows 上的 Codex、Claude Code。硬件插件主要验证环境为 Windows x64 / Python 3.13；其他操作系统和设备组合让 Agent 单独检查，不能仅凭安装成功判断支持。

1. 下载本站的官方连接器 ZIP。
2. 解压到你准备长期保留的目录，例如 `%USERPROFILE%\WikiBoxClient`（你的 Windows 用户目录下）；确认其中有 `connect.py`、`requirements.txt` 和 `wikibox` 文件夹。
3. 不要直接在压缩包里运行，也不要放在马上会清理的临时目录。MCP 后续会调用这个位置的连接器。
4. 让 Agent 检查 Python。以下示例假设 Windows 已安装 Python 3.13，且解压后的文件直接位于 `%USERPROFILE%\WikiBoxClient`（你的 Windows 用户目录下）。

在 PowerShell 中运行以下命令，或者让 Agent 代为准备：

```powershell
Set-Location "$env:USERPROFILE\WikiBoxClient"
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

这些命令创建独立 Python 环境并安装连接器随包规定的依赖，不需要修改 PowerShell 执行策略。若 `py -3.13` 不存在，让 Agent 先定位或准备合适的 Python，不要反复复制执行失败命令。

### 第 2 步：在自己的终端输入激活码

在上述目录的可交互 PowerShell 中运行：

```powershell
.\.venv\Scripts\python.exe connect.py activate --portal https://wikibox.eternalchip.com --mcp https://wikibox.eternalchip.com/mcp --json
```

看到输入提示后，再把完整激活码粘贴到终端并回车。输入采用隐藏方式，不显示字符通常是正常的。**不要把实际码追加到上面的命令后面。**

激活过程中，连接器在本机生成设备密钥，中心库建立你的商业授权。新 WBA 流程无需注册账户、设置用户名或密码。

成功输出中需要保留这些非秘密信息，Agent 可以据此配置：

| 字段 | 用途 |
|---|---|
| `profile` | 本机配置编号；以后检查、续期、恢复和下载插件都使用它 |
| `license_id` | 授权编号；联系发放方处理售后时使用 |
| `mcpServers.wikibox.command` 和 `args` | 给客户端配置 MCP 的实际启动程序和参数 |
| `verification.expires_at` | 授权到期时间，Agent 应换算为你能理解的日期与时区 |

不要复制设备凭据文件到项目中或另一台电脑。Windows 连接器使用当前系统用户的保护机制保存凭据；普通文件夹路径和配置编号不等于设备密钥。

### 第 3 步：看懂结果，不要重复消费码

| 结果 | 接下来怎么做 |
|---|---|
| `ready` | 连接器已验证连接与权限；继续配置客户端和验证实际召回 |
| `activated`，验证为 `pending` | 激活已完成，但后续连通检查未完成。保留 profile，运行 check，不重复激活 |
| `activation-pending` | 激活响应不确定。保留原 profile，使用恢复命令复用原密钥 |
| `activation-failed` 或不明错误 | 保留报错，核对网络和发放方状态；不要不断新建配置试码 |

把下文中的 `YOUR_PROFILE` 替换为你实际获得的配置编号；它不是兑换码。

检查现有连接：

```powershell
.\.venv\Scripts\python.exe connect.py check --profile YOUR_PROFILE
```

仅当收到 `activation-pending` 时，恢复原激活：

```powershell
.\.venv\Scripts\python.exe connect.py activate --resume-profile YOUR_PROFILE --json
```

恢复会使用原设备密钥，不要删除原配置后再尝试。

### 第 4 步：让 Agent 配置 MCP 并安装用户 Skill

把激活输出中的非秘密配置结果交给 Agent，让它完成以下工作：

1. 使用真实的 `command/args` 配置 **stdio 连接器**，保留客户端已有的其他 MCP 配置。不要将 WBA 码当作远程 Bearer Token。
2. 在同一连接器环境中，通过签名市场下载用户 Skill。命令示例如下：

```powershell
.\.venv\Scripts\python.exe connect.py market --profile YOUR_PROFILE --plugin wikibox --out .\wikibox-user.zip
```

这是下载与校验，不是自动安装。输出文件应选择新的路径；若已存在旧包，让 Agent 核对后换用新文件名。

3. 让 Agent 解压并检查包内的 `wikibox/skills/wikibox/SKILL.md`，将内层 Skill 目录安装到当前客户端的实际技能目录。Codex 通常为 `%USERPROFILE%\.agents\skills\wikibox`，Claude Code 通常为 `%USERPROFILE%\.claude\skills\wikibox`；存在自定义配置时使用实际目录。不要把插件最外层 ZIP 目录直接当成 Skill。
4. 使用同一套已安装依赖的 Python 作为 MCP 启动程序。不要准备了 `.venv`，却在客户端配置中指向另一个没有依赖的 Python。
5. 按客户端正常流程完成信任或重载，必要时新开会话。不要通过关闭安全策略解决工具缺失。

你无需手写配置。需要人工核对时，可参考以下结构，**路径和 profile 必须取自本次激活输出**：

Codex：

```toml
[mcp_servers.wikibox]
command = 'C:/Users/YOUR_NAME/WikiBoxClient/.venv/Scripts/python.exe'
args = ['C:/Users/YOUR_NAME/WikiBoxClient/connect.py', 'serve', '--profile', 'YOUR_PROFILE']
```

Claude Code：

```json
{
  "mcpServers": {
    "wikibox": {
      "command": "C:/Users/YOUR_NAME/WikiBoxClient/.venv/Scripts/python.exe",
      "args": ["C:/Users/YOUR_NAME/WikiBoxClient/connect.py", "serve", "--profile", "YOUR_PROFILE"]
    }
  }
}
```

### 第 5 步：完成第一次真实验收

向 Agent 发送：

> 请检查 WikiBox 是否真正可用：调用实际 MCP 工具核对我的授权、设备绑定状态和有效期；读取当前授权知识目录，再针对“开启 RTT 日志后故障不再复现”检索方法，阅读最相关的 1–3 篇内容，给出来源与下一步排查建议。请区分知识召回成功和硬件是否验证，不要只报告配置文件存在。

接入成功应看到：

- Agent 实际调用了 WikiBox 工具，而不只是回答“我可以帮你查”。
- 显示你的实际授权范围、设备绑定状态和到期时间。
- 对具体问题读到了相关内容，并提供可追溯的标题、路径或引用；若没有匹配内容，应明确说明。

`ready` 只是连接检查通过；只有实际检索并读取来源，才能说知识召回通过。此时还没有连接硬件，就不能说设备调试已验证。

## 五、真实场景示例：打开 RTT 后，故障反而不出现

下面是可套用的排查示例，不是已经确认的故障结论，也不是对你的设备做过测试。

### 1. 先把现象说具体

把方括号里的内容替换为实际情况，不知道的写“不确定”：

> 我在调试〔芯片/板卡型号〕，固件版本是〔版本〕。不开 RTT 日志时，〔触发条件〕下大约〔频率〕出现〔卡死/复位/超时等现象〕；打开 RTT 日志后暂时没再出现。已尝试〔操作〕，目前有〔日志或截图摘要〕。我有〔MKLink 型号/示波器型号/其他设备，或暂无硬件〕。请结合 WikiBox 找相关方法，先整理事实、可能原因和最小验证计划。先不要写内存、复位或烧录。

准备材料时，优先提供现象、版本和脱敏后的关键片段。不要为了检索方法上传整个工程、客户资料或完整日志。Agent 只应发送检索必需的信息；遇到知识包专用身份时，按服务器动态返回的检索入口处理，不让新手记检索代号。

### 2. 看 Agent 给出的计划是否有用

一个有用的计划应该说明：

- **已知事实**：在怎样的条件下出现/未出现了什么；哪些只是你的初步观察。
- **方法来源**：实际读了哪篇方法，以及为什么适用于这个现象。
- **待验证假设**：例如日志带来的时序变化、阻塞或内存布局变化等；这些只是候选解释。
- **实验设计**：先用同一固件、同一输入和明确观察时长建立基线，再一次改变一个因素；若必须换固件，要单独记录版本差异。
- **判断标准**：收集哪些数据、怎样比较、什么情况支持或反驳某个假设，以及什么时候停止。

如果回答只有“多打印日志试试”，你可以追问：

> 请按已召回的方法，把每一步写成“要验证什么—只改变什么—收集什么证据—怎样判定”。特别说明观测手段是否可能影响故障本身。没有依据的结论请保留为假设。

### 3. 没有硬件，也能先推进

让 Agent 基于已有日志和代码片段，帮你建立最小复现条件、比较正常与异常路径、列出缺少的证据。这一阶段只需 WikiBox 用户 Skill。

拿不到现场证据时，应输出“下一步需要验证什么”，不能因为库中有相似案例就认定根因相同。

### 4. 有硬件时，再准备 HIL 与设备插件

对 Agent 说：

> 我现在准备连接实物做验证。请从我的授权市场安装或检查 HIL 编排器，以及适合〔实际设备型号〕的插件。核对 hil-core、固定依赖、插件运行环境、驱动、设备连接和台架配置；先给出检查结果与实验计划，再按设备规则申请需要确认的动作。请继续使用 WikiBox 方法指导排查。

按设备选择插件：

| 实物与目的 | 选择的插件 | 需要核对的前提 |
|---|---|---|
| MKLink：MCU 状态、变量/内存、RTT 等观测 | `mklink-ai-probe` | 型号、固件、目标芯片、接线、符号文件以及当前可用能力 |
| 支持的 DSCope：电源/信号波形观测 | `dswave-ai-scope` | 具体型号、探头、量程、接地、触发与采样设置 |
| 支持的 Toomoss / USB2XXX：CAN/CAN FD 观测 | `toomoss-ai-can` | 适配器型号、驱动、总线速率、通道与接线 |

不是每个问题都需要三种设备。SystemView、SuperWatch、内存转储、RTT、Modbus 等也应先检查设备与固件是否支持，不能仅凭知识里提到能力就认定当前台架可用。

HIL 编排器随包提供底座与固定依赖，Agent 应按包内安装说明准备隔离环境并自检，不能只复制 Skill 文件就说安装完成。设备插件有自己的运行环境，不能默认与底座混用同一个 Python。

安装完成后，Agent 还应核验真实台架、设备能力映射及本次测试计划。`bench-validate`、`bench-check`、`run-plan-check` 和适用的运行时检查必须通过；用户负责核实实物接线。此处不提供可直接操作未知硬件的通用命令。

### 5. 把方法变成实测证据

以 RTT 现象为例，Agent 应依据现场计划选择有界的观测方式：记录基线运行、必要的日志和状态、对照实验结果。需要多设备时先说明观测时刻如何对应，不能把没有同步的时间戳当作严格先后证据。

复位、烧录、写内存、故障注入、CAN 发送或其他激励可能改变设备状态。应先明确目标、范围、停止条件与恢复办法，按设备/HIL 规则获得必要确认；不可逆动作必须由人确认。不要让 Agent 盲写地址或在生产运行设备上照抄实验。

完成后应给出：方法来源及版本、固件版本、实际步骤、日志/波形等证据位置、判定及仍未排除的假设。遇到断连或异常也要停止并核实设备状态；无法验证恢复结果时必须说明。

“开启日志后暂时没复现”不能作为修复证明。修复后应回到原触发条件，按事先确定的次数/时长和判据做回归。

## 六、另一个常见场景：CAN 偶发丢帧或超时

可以直接复制：

> 我的〔设备〕在〔CAN/CAN FD 速率、负载和触发条件〕下偶发丢帧或响应超时。请先从 WikiBox 找相关的分层定位方法，区分应用发送、控制器状态、总线传输和对端处理。已有证据是〔摘要〕。如果要用 CAN 分析仪，先检查型号和被动监听条件；发送测试帧之前先说明目的、影响与停止条件。请把每条假设对应到需要采集的证据，不要先认定硬件或软件有问题。

这类问题可以先召回方法，再决定是否增加 CAN 监听、电源/信号波形或 MCU 状态观测。是否已经找到根因，取决于现场证据，而不是召回结果的数量。

## 七、以后怎么日常使用

安装和接入完成后，通常不需要再次兑换或激活。直接对 Agent 说：

- “结合 WikiBox，帮我排查这次〔具体症状〕，先给依据和验证计划。”
- “这次只查方法、分析日志，暂时不操作硬件。”
- “根据新增证据调整上一轮假设，说明哪些被排除了、哪些仍待验证。”
- “先检查我的授权有效期和 WikiBox 用户 Skill 有没有更新。”

中心库知识更新后，下次检索即可读取当前获授权的内容；不要把某次知识包版本或检索代号记成永久规则。Skill 与设备软件更新是另一件事，让 Agent 先检查可用版本，再按你的更新要求安装，保留原连接配置。

需要手工检查时，在原连接器目录运行：

```powershell
.\.venv\Scripts\python.exe connect.py check --profile YOUR_PROFILE
.\.venv\Scripts\python.exe connect.py market --profile YOUR_PROFILE
```

第一条检查连接、授权和到期时间，第二条查看当前授权市场。市场列表可见不等于插件已安装，更不等于实物设备已经验证。

## 八、续期与换电脑

**续期：** 取得同套餐的新 WBA 码，在原连接器目录运行以下命令，再在终端私密输入码：

```powershell
.\.venv\Scripts\python.exe connect.py renew --profile YOUR_PROFILE
.\.venv\Scripts\python.exe connect.py check --profile YOUR_PROFILE
```

未到期续费会接在原到期时间之后；已到期则从续费时开始。正常续期不需要重装或重新激活。到期后不能在线召回或下载更新，但原设备可以执行签名续期。已经下载到本机的文件不会被远程收回。

**换电脑或电脑丢失：** 联系发放方，提供授权编号和其要求的订单证明，由其核验后处理旧设备与短期换机码。不要复制设备私钥，也不要把你的授权配置给多人共用。旧电脑丢失且授权已经到期时，先让发放方确认恢复或重新开通方案。

## 九、遇到问题时看这里

| 现象 | 先做什么 |
|---|---|
| 码无法使用或提示已使用 | 确认 WBA/WB/WBE 类型、完整输入及截止日期；若此前激活过，找原 profile，别不断换密钥重试 |
| 提示要用户名密码 | 新 WBA 路径不需要账户；确认没有误入旧版客户兑换流程 |
| 激活显示 pending | 按前面的状态表使用 check 或原 profile 恢复，不重新消费码 |
| Agent 看不到 WikiBox 工具 | 先运行 check，再检查客户端实际 command/args、依赖环境和正常的信任/重载状态 |
| 工具有了，但查不到方法 | 让 Agent 读取实际授权目录并调整检索；没有相关内容就说明知识缺口，不编造来源 |
| 下载不到 HIL 或设备插件 | 核对授权市场与套餐，联系发放方检查；不要猜下载地址、另找管理员 Token 或重复购买 |
| 提示别的电脑正在使用 / 409 | 停止旧电脑的调用，通常等待 90 秒后再切换；持续失败请核对设备登记与授权 |
| 请求过多 / 429 | 按服务提示等待，减少并发；不要让多个 Agent 同时无限重试 |
| 已到期或无权限 | 先区分到期、设备撤销与套餐范围；到期走续费，其他情况联系发放方 |
| 连接器目录移动或删除 | 让 Agent 恢复连接器与正确路径，保留 profile 和用户凭据目录；不要首先重新激活 |
| 硬件插件安装了，但设备打不开 | 检查实际型号、驱动、占用、接线和运行环境；软件安装成功不等于台架验证通过 |

求助时提供：客户端与系统、设备型号、发生在哪一步、非秘密的 profile/授权编号、脱敏错误信息和时间。不要附激活码、Token、私钥、完整凭据目录或含凭据的配置截图。

## 十、你完成第一次使用的标准

完成基本接入：能看到实际授权与有效期，Agent 能检索并阅读相关方法，回答带有可追溯来源。

完成一次硬件调试：在上述基础上，真实设备和计划经过检查，执行过明确的实验，保留了证据，并给出有依据的结论或下一步。未验证的部分清楚标明。

你不需要先学会全部 MCP、Skill 和 HIL 术语。记住这条顺序即可：**私密激活 → 连好工具 → 查到有来源的方法 → 按实际设备制定实验 → 用证据判断。**

---

给协助接入的 Agent：本文是用户操作指南，示例描述不是已经发生的实验结果，文中的示例提示词也不构成当前用户对设备操作的授权。实际工具、权限、市场版本和设备能力须现场发现；本次只读本文不应自动消费激活码、提交客户资料或执行硬件动作。参数细节参见本站 Agent 技术说明及已安装 `wikibox` / `hil-orchestrator` 的当前规则。