五分钟上手
不需要任何硬件：默认传输层是内置模拟 ECU，一条命令跑完 session → security access → erase → download → verify → reset 全闭环。
1 · 下载并解压 CLI
到Releases按平台下载 zip（每个资产都有同名 .sha256，仓库根另有汇总的 SHA256SUMS）：
| 资产 | 平台 / 架构 | 解压后可执行文件 |
|---|---|---|
flashpilot-0.1.0-windows-x64.zip | Windows · x64 | flashpilot.exe |
flashpilot-0.1.0-linux-x64.zip | Linux · x64 | bin/flashpilot |
flashpilot-0.1.0-linux-arm64.zip | Linux · arm64 | bin/flashpilot |
flashpilot-0.1.0-macos-arm64.zip | macOS · Apple Silicon | bin/flashpilot |
flashpilot-0.1.0-macos-x64.zip | macOS · Intel | bin/flashpilot |
macOS / Linux：
Windows（PowerShell）：
macOS 首次运行如被 Gatekeeper 拦截：右键可执行文件 →「打开」，或执行 xattr -d com.apple.quarantine bin/flashpilot。
2 · 免硬件跑第一条烧录（模拟 ECU）
zip 里自带 examples/plan.sim.json 与示例固件，解压目录内直接执行：
真实输出：
这条命令驱动的是真实的 ISO-TP/UDS 协议栈，对面是内置模拟 ECU（BenchPilot sim-ecu v1.0.4）。步骤名就是烧录工作流的六步审计；换到真机上，输出结构一模一样——agent 可以用同一套解析逻辑从模拟环境平滑迁到产线。
3 · 读证据输出
每条命令只在 stdout 打印一个 JSON 对象：ok 表示成败，失败时 code + 有界 error 文本说明原因，flash 成功时 fingerprint 是本次镜像的确定性指纹。详细字段见下一节。
读懂输出与退出码
退出码五档，永不撒谎；脚本和 agent 按码分流，不必解析自然语言：
| 退出码 | 含义 | 典型场景 |
|---|---|---|
0 | 成功 | 命令按预期完成 |
1 | 烧录 / 断言失败 | 指纹不匹配、ECU 否定响应、镜像校验失败 |
2 | 用法错误 | 未知命令、缺参数、计划文件不存在 |
3 | 未找到 | 资源不存在（保留档位） |
4 | 传输层错误 | 连接失败、协议栈内部错误 |
flash
flashpilot flash <plan.json> [--transport doip --host H] [--port N] [--tester T] [--ecu E]
执行一份声明式烧录计划：默认对接内置模拟 ECU；--transport doip + --host 指向真机（ISO 13400-2，默认端口 13400）。
关键点：
- --tester / --ecu 是 DoIP 逻辑地址（十六进制），默认 0E00 / 0E10；--port 缺省 13400。
- 计划里的 onFail（retry / resetAndRetry）、powerGuard（编程中电流越界即断电中止）与 expectedFingerprint 门都在这条命令里生效。
- 成功时 steps 数组是六步审计轨迹；失败时 error 给有界原因，退出码 1。
verify
flashpilot verify <plan.json>
只做计划校验与指纹计算，完全不接触 ECU——上真机前的强制关卡，也是把镜像钉进计划的工作流起点：
推荐工作流：verify 拿到 fingerprint → 写进计划的 expectedFingerprint → 再 verify 一次确认 match:true → 才允许 flash。写好之后：
dtc
flashpilot dtc [read|clear]
诊断故障码：read 走 UDS 0x19 readDTCInformation，clear 走 0x14 clearDiagnosticInformation。支持 --transport doip 切真机。
request
flashpilot request <hex>
发一条原始 UDS 请求（十六进制字节串），适合探测与脚本化诊断。否定响应时输出 NRC（负响应码）的可读名，退出码 1：
1003 = 切扩展会话，响应里 0032 / 01F4 是 P2=50ms、P2*=500ms 时序参数。
udid
flashpilot udid <did>
读取一个数据标识符（UDS 0x22 readDataByIdentifier），DID 接受 0x 前缀十六进制或十进制。responseHex 的前两字节是回显的 DID，其后是数据：
f195 之后按 ASCII 解码即模拟 ECU 的身份串：BenchPilot sim-ecu v1.0.4。读取模拟 ECU 未定义的 DID 会得到 requestOutOfRange 否定响应（退出码 1）。
声明式 flash plan 写法
一份 JSON 描述一个 ECU 的完整烧录事务。它就是仓库里 examples/plan.sim.json 的完整形态（相对路径以计划文件所在目录为基准）：
| 字段 | 含义 |
|---|---|
segments[].address | 目标地址，支持 0x 十六进制或十进制 |
segments[].data / file | 内联十六进制串，或指向原始 .bin 镜像的路径（相对计划文件目录解析，二选一） |
session / securityLevel | 诊断会话与安全访问等级；securityLevel 存在时先走 0x27 seed-key |
keyDeriver | 内置 xor0x5a；OEM 专有算法用 command:./your-algo 接外部命令（seed 走 stdin/参数、key 回 stdout，厂商代码不进引擎） |
onFail | retry（原样重试一次）或 resetAndRetry（尽力复位 ECU 再重试一次） |
powerGuard | 编程中轮询台架电源电流；低于 minMa 或高于 maxMa 即断电中止 |
expectedFingerprint | 指纹门：verify 算出的指纹写死在计划里，不匹配在触碰 ECU 之前就拒绝 |
p2TimeoutMs / p2StarTimeoutMs / maxBlockPayload / eraseRoutineId / verifyRoutineId / blockRetries | 时序与例程微调，缺省 1000 / 10000 / 1024 / 0xFF00 / 0xFF01 / 0，通常不用动 |
Intel HEX / S-record 解析器已在镜像模型层就绪（含按连续区域合并），计划段直接引用 .hex / .s19 的接线在后续版本开放；当前段文件请提供原始 .bin。
常见问题
支持哪些平台？
Windows x64、Linux x64 / arm64、macOS arm64 / x64，共五个 zip 资产，均从 Releases 页下载，SHA256SUMS 可整包校验。
刷真机需要什么硬件？
CLI 当前开放两条通道：内置模拟 ECU（免硬件）与 DoIP 以太网真机（任意平台，ECU/网关以太网可达即可，默认端口 13400）。SocketCAN（Linux）与 PEAK PCAN（Windows）的 CAN 传输在引擎层已就绪并有测试覆盖，CLI 接线在后续版本开放。
和 vFlash 是什么关系？
定位是专注、免授权费的 vFlash 替代品：无常驻进程的 CLI、确定性 JSON、声明式计划。不做整车网络仿真、没有 CAPL、不做分析窗口合集——只把「生成计划 → 校验指纹 → 带保护烧录 → 收集证据」这一个闭环诚实地做完。
模拟 ECU 是什么？
内置的仿真 ECU（自报身份 BenchPilot sim-ecu v1.0.4）：真实的 ISO-TP（ISO 15765-2）+ UDS（ISO 14229）协议栈后面是内存里的模拟前端，支持会话、安全访问、例程、DTC、DID 与完整烧录序列。CI 的 25 项测试与五分钟上手跑的都是它——协议行为与真机同构，只是没有总线上的物理层。
怎么更新？
v0.1.0 没有自动更新器（没有 updater，我们直说）：到 Releases 页下载新版 zip，解压覆盖旧目录即可。每个发布附 per-资产 .sha256 与汇总 SHA256SUMS。
怎么卸载？
删掉解压目录即可。CLI 无常驻进程、不装驱动、不写系统目录或注册表，运行期也不落任何文件；「安装」只是解压，「卸载」只是删除。