Skill：TSMaster 干扰仪上位机小程序开发

> 目标：在一个 TSMaster MiniProgram 里，把总线干扰仪做成「能连、能配、能干扰、能判定、能收尾」的上位机。
> 所有参数都是真机跑出来的值，不是照抄 demo；demo 与我们环境的差异见 VALIDATION.md。

0. 何时用

1. 铁律速查表

2. 程序架构（四层 + 区块落位）

┌─ L4 编排层：自定义函数 + 用例 tc_*          ← 对 UI 暴露的入口
├─ L3 能力层：init / disturb_config / sp_test / stop / query
├─ L2 连接层：create → scan → get_info → open；ETH/USB 回退；句柄管理
└─ L1 加载层：dll 定位 + 函数指针表

区块落位（放错区块是最常见的「编译过了但 UI 里没有」）：

自定义函数四条硬性要求（缺一条 UI 里就不显示）：

// CODE BLOCK BEGIN Custom_Function <函数名> <base64标识>
// 自定义函数 "<函数名>"
s32 <函数名>(void) { try { // 自定义函数:
    return 0;
} catch (...) { log_nok("CRASH detected"); app.terminate_application(); return(IDX_ERR_MP_CODE_CRASH); }}
// CODE BLOCK END Custom_Function <函数名>

一个区块只能一个函数；签名必须 s32 名(void)；首行标记 // 自定义函数: 要在 { try { 同一行；catch 必须返回 IDX_ERR_MP_CODE_CRASH。

参数怎么传（自定义函数不支持参数）：少量标量走全局变量；指针/句柄用 s32 承载（32 位同宽，安全）；字符串返回静态常量地址；线程入口不能迁。

3. 两种耗时模型（选型先看这张表）

模型 A：线程 + 轮询（起始 → 轮询 → 工作线程三段式）

s32 th_sp_start(void) { try {            // ① 启动后立即返回
    if (InterlockedCompareExchange(&g_th_busy, 1, 0) != 0) return 0;
    InterlockedExchange(&g_th_job_done, 0);
    HANDLE th = CreateThread(NULL, 0, th_sp_worker, NULL, 0, NULL);
    if (!th) { InterlockedExchange(&g_th_busy, 0); return -1; }
    CloseHandle(th);
    return 1;
} catch (...) { ... } }

s32 th_sp_poll(void) { try {             // ② 主线程每 5ms 查一次
    return (s32)InterlockedCompareExchange(&g_th_job_done, 1, 1);
} catch (...) { ... } }

模型 B：tick 状态机（步进式，每 tick 推进一步）

if (g_step == STEP_IDLE)    { ...初始化...; g_step = STEP_START;  return 0; }
if (g_step == STEP_START)   { ...连接+配干扰...; g_step = STEP_RUN; return 0; }
if (g_step == STEP_RUN)     { g_tick++; if (g_tick >= 2000) { g_step = STEP_OBSERVE; } return 0; }  // 200 tick = 1 秒
if (g_step == STEP_OBSERVE) { ...判定...; g_step = STEP_DONE; return 1; }
return 1;   // DONE

> 5ms 一个 tick，200 tick = 1 秒。不要用 Sleep() 等，那会顶死调度器。

4. 标准流程（8 步）

1. 环境自检
   - dll 是 32 位？依赖 libusb-1.0_tosun.dll 在不在？
   - 控制端口 21840 有没有残留连接？（Get-NetTCPConnection -RemotePort 21840）
2. 加载 dll
   - 五级查找 → SetDllDirectory → LoadLibraryEx → GetProcAddress
   - 必查 4 个：create / scan / open / sp_test（缺一就报 -2 并打印缺失项）
3. 连接设备
   - create(dev_type=0, com=1 eth / 4 usb) → scan → get_info → open(uid)
   - 自动模式：ETH 失败回退 USB，保留首个错误码
4. 初始化 CAN 控制器
   - th_can_ctrl_t：仲裁/数据波特率 + 两个采样点（默认 500k/2M/80/80）
5. 选择测量方式
   - 采样点 → 线程模型；干扰 → 先清计数再配干扰
6. 编排与推进
   - 线程模型：用例里 tc_begin → start → 轮询 → 判定
   - tick 模型：用例每 step 调引擎一次，引擎自己推进内部相位
7. 判定与回写
   - 测量类：数值优先，错误码只进「诊断」栏
   - 干扰类：先查干扰次数 > 0（否则总线无报文），再查通信是否恢复
8. 收尾（顺序不能错）
   - stop(停止干扰) → close → destory → 句柄置空 → 再查 21840 应为空

5. 验证清单（每次改完必跑）

[ ] 1. 编译：clang 直接编，exit 0，bin/<程序名>.mp 时间戳更新
[ ] 2. 定义唯一性：无重复 s32 xxx(void) { try 定义（混用脚本改与区块写的高发区）
[ ] 3. 括号平衡：{ 数量 == } 数量
[ ] 4. 跑前清场：21840 无 Established 连接
[ ] 5. 只读先验：先跑只读探针确认连接与 dll 版本，不做任何干扰
[ ] 6. 跑测试：干扰类会真的产生错误帧，确认目标是台架不是实车
[ ] 7. 看报告：PASS/FAIL/NA 计数符合预期，诊断栏有中文原因
[ ] 8. 跑后查泄漏：21840 仍应为空

第 4 步和第 8 步必须前后各查一次，才能证明「修好了」而不是「这次没报错」。

6. 排错速查

详见 TROUBLESHOOTING.md。

7. 参考文件