Skill：TSMaster 二次开发通用机制（小程序 + 面板）

> 读完本 Skill，AI 能在一个陌生的 TSMaster 工程里从零建起「可控、可编译、可观测、可复用」的小程序与面板。
> 本文只写跨工程成立的机制；与具体被测对象/硬件/工程约定有关的内容一律用 <占位符>，用时按工程自身文档填。

0. 何时用

主要功能是写小程序（MiniProgram，C/.mp）和做测试面板（Panel）。

> 涉及具体硬件 SDK（干扰仪、程控电源等）或被测评据时，机制照本 Skill，参数按工程自身文档补。

1. 铁律速查表

2. 环境与前置事实

占位符约定：

前置条件（缺一项先停下）：

• [ ] 已知 <工程根> 与 <程序名>，且 <工程根>/MiniProgram/Build/<程序名>/ 存在
• [ ] 改面板前 TSMaster 已完全退出（任务管理器确认无 TSMaster* 进程）
• [ ] 编译前已确认 .mp 未被运行中的小程序占用

> Custom_Function 的返回值与参数规则（含迁移决策表）见 REFERENCE.md §3.1。
> 一句话：返回值必须 s32，参数可以带（写进区块名后的 base64 签名），
> 但自定义 struct 指针 / 函数指针 / 非 s32 返回值的函数只能留在 Global_Definitions。

3. 标准流程

<a id="step-1-source"></a>

步骤 1 — 定权威源与产物边界

• 动作：确认三件事——<程序名>、CSrc/<程序名>.cpp 是否存在、bin/<程序名>.mp 是否已存在
• 产物：一张「唯一手改文件 / 派生物」清单
• 判据：能明确回答「我改哪个文件、产物落在哪」
• 失败：目录结构与 REFERENCE.md §1 不符 → 先摸清实际结构，不要按文档硬套

<a id="step-2-contract"></a>

步骤 2 — 先定变量契约（L0/L1/L2）

• 动作：把要「用户可配 / 面板可见」的项写进系统变量（L0），把跨 step 的运行态放 s_ 静态全局（L1），case 内部状态留局部（L2）
• 产物：变量表（全名、类型、默认值、界面控件）
• 判据：每条 L0 都能回答「谁在面板上改它」；每条 L1 都能回答「哪些 step 之间共享」
• 失败：变量命名/类型/Count 规则见 REFERENCE.md §4

> 先定契约再写代码。变量名后续改动会同时打断面板绑定与代码引用。

<a id="step-3-skeleton"></a>

步骤 3 — 先写「能启动、能停止、能观测」的骨架

• 动作：贴 TEMPLATES.md §1 骨架：On_Start 复位状态、step 心跳 + tick 安全阀 + 空状态机、On_Stop 释放
• 产物：可编译、可运行、能自动退出、日志有心跳的空程序
• 判据：跑起来能看到 alive tick=…，且到 TICK_LIMIT 自动 terminate
• 失败：起不来先查 On_Start 是否含等待/循环；停不下来查 step 是否阻塞（TROUBLESHOOTING.md §3）

> 不要跳这一步。 业务未完成时也要能安全退出，否则后续调试全部失去现场。

<a id="step-4-business"></a>

步骤 4 — 填业务：一次只加一个环节

• 动作：每个需要「等待外部响应」的用例都写成相位状态机（TEMPLATES.md §2），
  每个对外能力收敛到一个实现函数，未就绪时返回 E_NOT_READY 由用例判 NA
• 产物：每个 case 一个 Custom_Function 区块 + 判定写回报告
• 判据：单次 step 内不出现 Sleep/死等；每个 case 都有显式超时兜底
• 失败：卡死查相位是否漏 tc_arm_wait/漏超时定时器

<a id="step-5-build"></a>

步骤 5 — 同步 + 编译 + 查产物

• 动作三选一（判据见 REFERENCE.md §2）：
  1. TSMaster UI 内 Ctrl+F9（自己处理占用，最省事）
  2. ASSETS/compile_mp.ps1（参数化，能拿到完整 stderr）
  3. build_mp_x86.bat（成功无 pause，失败会 pause，非交互调用会挂住）
• 产物：bin/<程序名>.mp 时间戳更新
• 判据：退出码 0 且 产物时间戳晚于源文件
• 失败：先查占用，再读 stderr（TROUBLESHOOTING.md §1）

<a id="step-6-evidence"></a>

步骤 6 — 跑 + 取证据

• 动作：运行 → 读 Logging/<程序名>/system_messages/*.log（过程）→ 解析 AutoReport/<时间戳>/testjsonreport.csv（结论）
• 产物：日志正文 + TSPass/TSFail/TSNA 计数
• 判据：报告条目数 = 预期用例数；日志无 log_nok 级别的异常
• 失败：见 TROUBLESHOOTING.md §5、§6

> 程序必须自己在 step 首次进入时开 start_system_message_log（TEMPLATES.md §5），
> 否则证据目录永不产生，工具链门禁会被永久卡住。

<a id="step-7-panel"></a>

步骤 7 — 接面板（变量 → 控件 → 边沿）

• 动作：控件绑变量全名；瞬时按钮走边沿检测 + 读后清零；持续状态（勾选/进度）只写不清零
• 产物：可操作面板
• 判据：点一次按钮只触发一次；改代码里的变量名后，面板同步改绑定
• 失败：见 TROUBLESHOOTING.md §4

<a id="step-8-close"></a>

步骤 8 — 收尾核对

• 动作：停程序 → 确认 .mp 可写（没被锁）→ 删探针残留 → 过 §4 清单
• 判据：§4 全部通过
• 失败：未通过项回对应步骤，不要带着问题进下一轮

4. 验证清单

• [ ] 改动全部落在 CODE BLOCK 内（判据：diff 里无 GEN BLOCK 段被改）
• [ ] CSrc/<程序名>.cpp 与 Build/<程序名>/<程序名>.cpp 差异只有构建时间戳（判据：Compare-Object 后仅剩该行）
• [ ] 编译退出码 = 0 且 bin/<程序名>.mp 时间戳晚于源文件（判据：Get-Item 比较）
• [ ] 无重复函数定义（判据：TEMPLATES.md §7 查重命令输出为空）
• [ ] step 单次耗时 < 看门狗阈值 1/10（判据：心跳日志间隔稳定，无「像重启」现象）
• [ ] 每个函数都有 try/catch 且 catch 有日志（判据：grep catch (...) 数量 = 函数数）
• [ ] Logging/<程序名>/system_messages/ 下有本轮新 .log，且已读取内容
• [ ] 报告 TSPass + TSFail + TSNA = 预期用例数（判据：ASSETS/parse_report.py 输出）
• [ ] 报告中文正常、无未替换的 {{ }} 占位符（判据：打开 html 抽查）
• [ ] 面板按钮点一次只触发一次（判据：日志里同一动作只出现一条）
• [ ] 写面板前 TSMaster 已完全退出（判据：Get-Process TSMaster* 为空）
• [ ] 探针残留 6 处已删（CSrc / CSrcExtern / Build / libs / Logging / bin 无同名项）

5. 排错表

> 未命中查 TROUBLESHOOTING.md（六类分组，含诊断命令）。

⛔ 不要做

参考文件