从一枚激活码，
到一次有依据的调试。

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

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

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

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

三个时间容易混淆：

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

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

先打开已经能够正常对话的 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 代为准备：

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 中运行：

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

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

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

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

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

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

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

检查现有连接：

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

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

.\.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。命令示例如下：

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

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

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

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

Codex：

[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：

{
  "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 只是连接检查通过；只有实际检索并读取来源，才能说知识召回通过。此时还没有连接硬件，就不能说设备调试已验证。

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

1. 先把现象说具体

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

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

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

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

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

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

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

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

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

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

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

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

对 Agent 说：

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

按设备选择插件：

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

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

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

5. 把方法变成实测证据

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

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

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

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

可以直接复制：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

---

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