CANConfigPython 0.1.0a1__py3-none-win_amd64.whl

canconfigpython/resources/docs/user-guide.en.md

@@ -0,0 +1,274 @@
+# CANConfigPython user guide
+
+Applies to Python CLI 0.1.0a1 / Console 2.3 / bridge API 1.
+Supports configuration of CANHub, CANFB, CANBridge, CANRPT and CANCOM.
+Consult the release validation record for tested platforms and hardware evidence.
+
+## Install and check without hardware
+
+Use Python 3.8+ in a virtual environment. Install the supplied wheel matching your
+platform; until publication there is no public package to install.
+The wheel includes Console, WIICAN and required Qt libraries. No GUI installation
+or graphical desktop is needed.
+
+Windows PowerShell:
+~~~powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install .\canconfigpython-0.1.0a1-py3-none-win_amd64.whl
+.\.venv\Scripts\canconfig.exe doctor --json
+~~~
+
+Linux: create an environment with `python3 -m venv .venv`, activate with
+`. .venv/bin/activate`, then install the actual supplied Linux wheel using
+`python -m pip install ./WHEEL_FILENAME.whl`. Its manylinux tag states the minimum
+glibc version established by the build. This release requires x86_64 and glibc 2.38+;
+it was built/tested on Ubuntu 24.04 / Python 3.12 with Qt 5.15.13.
+Use `ldd --version` to check glibc. ARM64, musl and macOS are not supported.
+
+After publication: `python -m pip install --pre CANConfigPython`.
+Upgrade: `python -m pip install --upgrade --pre CANConfigPython`.
+Uninstall: `python -m pip uninstall CANConfigPython`. Your backups and exported
+documentation/Skill remain your files.
+
+~~~console
+canconfig --version --json
+canconfig doctor --json
+canconfig schema --json
+canconfig apply --help
+canconfig docs export --output ./canconfig-docs
+canconfig skill export --output ./canconfig-skill
+~~~
+
+Doctor checks hashes, backend contract, library loading and exports without opening
+devices. Success: ok=true, exit_code=0, data.device_opened=false.
+Schema is a descriptive contract envelope, not a JSON Schema or patch file.
+Resource export requires a new directory. Copy the complete exported Skill folder,
+including references/assets, into your Agent's skill directory if desired.
+Package installation never changes Agent settings.
+
+If runtime_invalid/runtime_load_failed occurs, reinstall the complete matching
+wheel. Do not mix libraries from unrelated GUI installations. Developers replacing
+libraries should use the project's build/staging instructions.
+
+## Select the device and interpret results
+
+Choose an explicit COM port on Windows, for example COM3. On Linux use a confirmed
+/dev/ttyACM0 or /dev/serial/by-id/... path; names are case-sensitive.
+Inspect `ls -l /dev/serial/by-id/`, the selected node and `id` to diagnose access.
+An administrator can add your account to the actual device group (often dialout);
+log in again afterwards. Do not default to sudo or make the device world-writable.
+
+~~~console
+canconfig info --port COM3 --json
+~~~
+
+Replace COM3 with the actual selected port. Match data.device.uid/type/hardware/
+firmware and capabilities against the intended device. Info does not return a full
+configuration. Writable field names do not guarantee current-state writability.
+Info and configuration dry-run are live connections and can change device run mode.
+Only operate when maintenance access is authorized. Keep other applications off
+the port; Python locks only coordinate this user's CANConfigPython processes.
+
+Operations emit UTF-8 JSON; --json selects one compact line. Check the process exit
+code, ok, effects and verification together. PowerShell 5.1 capture requires temporary
+UTF-8 Console.OutputEncoding; restore it afterwards.
+
+- attempted/submitted/acknowledged/save_acknowledged count writes and acknowledgements.
+- none means no reported configuration writes; a connection can still change run mode.
+- applied/transferred must be read alongside verification.
+- partial/unknown means stop automatic retry or rollback.
+- Missing valid final backend output gives unknown counts as null, never invented zeros.
+- readback=matched is current readback; power_cycle=not_verified is not persistence proof.
+
+## Credentials and cleanup
+
+Passwords are 1–10 UTF-8 bytes without NUL. Characters may take multiple bytes.
+The CLI accepts environment variable names only. Do not put secrets in arguments,
+source, persistent files, reports or chat. Administrators may inspect process
+environments; environment variables are not a secret vault.
+
+PowerShell template; replace the port, filename and UID before use:
+~~~powershell
+$originalEncoding = [Console]::OutputEncoding
+$secure = Read-Host 'Device password' -AsSecureString
+try {
+    [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+    $env:CAN_PASSWORD = [System.Net.NetworkCredential]::new('', $secure).Password
+    $raw = canconfig export --port COM3 --file .\backup-new.ini --password-env CAN_PASSWORD --expect-uid 'CONFIRMED-DEVICE-UID' --json
+    $exitCode = $LASTEXITCODE
+    $result = $raw | ConvertFrom-Json
+    $result | ConvertTo-Json -Depth 20
+    if ($exitCode -ne 0 -or -not $result.ok) { throw 'Stop and inspect effects/verification.' }
+}
+finally {
+    Remove-Item Env:CAN_PASSWORD -ErrorAction SilentlyContinue
+    $secure.Dispose()
+    [Console]::OutputEncoding = $originalEncoding
+}
+~~~
+
+Linux Bash:
+~~~bash
+(
+  trap 'unset CAN_PASSWORD' EXIT
+  read -r -s -p 'Device password: ' CAN_PASSWORD
+  printf '\n'
+  export CAN_PASSWORD
+  canconfig export --port /dev/ttyACM0 --file ./backup-new.ini \
+    --password-env CAN_PASSWORD --expect-uid 'CONFIRMED-DEVICE-UID' --json
+  rc=$?
+  if [ "$rc" -ne 0 ]; then
+    printf 'Stop and inspect effects/verification.\n' >&2
+    exit "$rc"
+  fi
+)
+~~~
+
+Place authenticated commands below inside the same try/subshell template. Cleanup
+must also run when file preparation or JSON parsing fails. Save operation results
+as needed; they may contain device identity/configuration and deserve appropriate handling.
+
+## Back up, validate and restore
+
+Backups are INI. A successful export replaces an existing destination, so choose a
+fresh filename associated with the device/time.
+
+~~~console
+canconfig export --port COM3 --file backup-new.ini --password-env CAN_PASSWORD --expect-uid UID --json
+canconfig validate --file backup-new.ini --json
+canconfig restore --port COM3 --file backup-new.ini --password-env CAN_PASSWORD --expect-uid UID --check-device --dry-run --json
+~~~
+
+UID means the confirmed full device UID, not the literal word UID. Inspect data.file
+and data.complete after export. Validate is offline and accepts INI only.
+Restore dry-run connects and checks identity/state but performs no SET/WRITE/SAVE.
+Review fields, write_count and save_domains. Within existing authorization, remove
+only --dry-run to execute the unchanged request. Require ok=true and matched readback.
+
+For partial backups use matching explicit --sections on export, validate and restore.
+Choices: all, parameters, filters, filter_mode, mapping, options, routing, cancom,
+user_data; join sections with commas. Default all means all supported sections.
+Explicitly requesting an unsupported section fails.
+
+--expect-uid fixes the current target; --check-device also matches the backup UID.
+Only omit --check-device for an explicitly authorized compatible migration; retain
+the target UID guard. Never silently rewrite a mismatched backup UID. Do not disable
+adaptive mode simply to obtain a backup that export refuses.
+
+## Apply JSON edits
+
+Export the Skill, read assets/examples/index.en.md and copy a suitable model-specific
+example into your working directory. Replace only the template's all-zero UID with
+the confirmed target, then edit authorized fields. A nonzero UID mismatch in an
+existing request is a stop condition.
+
+Structural illustration for CANBridge, not universal timing values:
+~~~json
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "CAN1_PARAMETER/BRT": [500000, 1, 13, 2]
+  }
+}
+~~~
+
+Use UTF-8 without BOM, exact case and only the three top-level keys. No $schema,
+comments, duplicate keys or nonfinite values. In PowerShell 5.1 do not use > to
+create JSON; explicitly use File.WriteAllText with UTF8Encoding(false).
+If preparation fails, stop instead of executing an old file.
+Python parses a stable snapshot strictly; Console validates device-specific rules.
+
+~~~console
+canconfig apply --port COM3 --file changes.json --password-env CAN_PASSWORD --expect-uid UID --dry-run --json
+canconfig apply --port COM3 --file changes.json --password-env CAN_PASSWORD --expect-uid UID --json
+~~~
+
+Execute the second line only after successful preflight, scope review and authorization.
+A partial patch can write a whole section and SAVE domains; write_count is not the
+number of edited fields. Ordinary configuration checks RAM before SAVE and reads
+back after SAVE. Neither proves power-cycle persistence. Never automatically restore
+a previous backup after an uncertain write.
+
+Adaptive enable must be a separate patch containing only selected
+CANn_PARAMETER/BRT_AUTO:1 fields, with all channels initially unrestricted/manual.
+It verifies flags only; adaptive_result remains not_verified. Do not export or write
+back detected adaptive timings/placeholders for any role. Returning to manual needs
+explicit new manual values for every channel.
+
+## Change password
+
+Extend the credential template to prompt separately for old/new values and set
+CAN_PASSWORD/CAN_NEW_PASSWORD. Use different names. Clear both in finally/trap;
+dispose both SecureString objects in PowerShell.
+
+~~~console
+canconfig change-password --port COM3 --expect-uid UID --password-env CAN_PASSWORD --new-password-env CAN_NEW_PASSWORD --dry-run --json
+canconfig change-password --port COM3 --expect-uid UID --password-env CAN_PASSWORD --new-password-env CAN_NEW_PASSWORD --json
+~~~
+
+Dry-run checks identity and old authentication only; it does not change or SAVE.
+Execute the second line only after reviewing preflight within authorization.
+Success: verification.new_password=authenticated, readback=not_applicable.
+A submitted timeout or failure authenticating the new password is not evidence that
+the old password remains valid. Preserve results and stop automatic retries.
+
+## Update firmware
+
+Use the vendor's final .sfb package, not an encrypted .sfu intermediate:
+SFU1/SFU2/SFU3 header, nonempty payload, at most 64 MiB.
+Confirm model/image compatibility externally; file checks do not verify signatures.
+Manually put the selected device into update mode; the CLI does not do this.
+
+~~~console
+canconfig firmware-update --port COM3 --file image.sfb --dry-run --json
+canconfig firmware-update --port COM3 --file image.sfb --expect-sha256 HASH --expect-usb-serial SERIAL --timeout-ms 120000 --json
+~~~
+
+The first command is fully offline: no enumeration or serial I/O. Replace HASH with
+its data.sha256. SERIAL means a confirmed USB serial; omit that option only if unavailable
+and the explicit target port is confirmed. Execute only with target/image authorization.
+Firmware accepts no configuration password/UID flags. It uses 115200 8N1, DTR on by
+default; --no-dtr disables assertion.
+
+Success requires verification.transfer=completed and device_return=observed.
+Installed image/version/signature, compatibility and persistence remain unverified;
+check the device afterwards using its documented procedure. Ymodem may retry numbered
+packets; the CLI never restarts a whole session. On failure preserve phase/transfer/
+device_return and inspect device state instead of automatically flashing again.
+
+## Failure, interruption and cleanup
+
+Default backend timeout is 120000 ms; --timeout-ms accepts 1–3600000 ms.
+Python allows extra shutdown time. Ctrl+C requests cancellation. Without valid final
+output, hardware effects are unknown; cancellation does not mean nothing happened.
+After each task clear credentials. Restore operational mode or power-cycle only
+within the device procedure and task authorization.
+
+| Exit | Meaning | First action |
+|---|---|---|
+| 0 | Completed | Inspect remaining verification gaps |
+| 1 | Connection/runtime/lock | Doctor, explicit port, permissions, other applications |
+| 2 | Authentication/format | Check variable availability/byte length without printing secrets |
+| 3 | File I/O | Check path/access, stop dependent operations |
+| 4 | Communication/protocol | Preserve result, check connection/runtime |
+| 5 | Unsupported | Check platform/model/capabilities |
+| 6 | Identity | Stop and compare target/file UID |
+| 7 | Configuration/JSON | Correct the indicated field and preflight again |
+| 8 | Unknown hardware result | Stop automatic retry/rollback; inspect actual state |
+| 9 | Usage | COMMAND --help; errors do not echo possibly secret arguments |
+| 10 | Readback mismatch | Stop and preserve effects/verification |
+| 11 | Timeout | Inspect effects before any decision |
+| 12 | Cancelled | Inspect effects; do not assume no execution |
+
+Offline validation, fake-driver tests, installed-package checks and physical-device
+acceptance are distinct evidence. This release does not automatically retry
+configuration, roll back, or prove persistence after power loss.
+
+## Licenses and native source
+
+The Python wrapper is MIT. The bundled Console includes XinLi's GPL-3.0-or-later
+Ymodem implementation; Qt and compiler libraries retain their own licenses.
+`canconfig docs export --output ./canconfig-docs` also exports `native-source.tar.gz`.
+Extract it and follow DEVELOPING.md to rebuild the native programs. See its
+THIRD_PARTY_NOTICES.md for license materials and dependency source locations.

canconfigpython/resources/docs/user-guide.zh-CN.md

@@ -0,0 +1,265 @@
+# CANConfigPython 用户操作说明
+
+适用版本：Python CLI 0.1.0a1 / Console 2.3 / bridge API 1。
+Windows 和 Linux 使用相同命令。Linux 包的实测状态以发布包附带的验证记录为准。
+本工具面向 CANHub、CANFB、CANBridge、CANRPT、CANCOM 配置，不提供 CAN 报文发送功能。
+
+## 1. 安装与第一次成功运行
+
+在保存发布文件的目录打开 PowerShell 或 Linux 终端。需要 Python 3.8 或以上。
+建议创建虚拟环境；运行时无需单独安装 Qt、WIICAN 或 GUI。
+
+Windows PowerShell（按实际 wheel 文件名替换）：
+~~~powershell
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install .\canconfigpython-0.1.0a1-py3-none-win_amd64.whl
+.\.venv\Scripts\canconfig.exe doctor --json
+~~~
+
+Linux x86_64（需要 glibc 2.38 或以上，已在 Ubuntu 24.04 / Python 3.12 上验证）：
+~~~bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install ./canconfigpython-0.1.0a1-py3-none-manylinux_2_38_x86_64.manylinux_2_39_x86_64.whl
+canconfig doctor --json
+~~~
+
+可用 `ldd --version` 查看 glibc 版本。当前 Linux 包不适用于低于 2.38 的 glibc、ARM64 或 musl 系统。
+安装成功后可激活环境，或使用其完整可执行文件路径。后续以 canconfig 简写。
+已上传 PyPI 后才可以使用 `python -m pip install --pre CANConfigPython`。
+升级用 `python -m pip install --upgrade --pre CANConfigPython`；
+卸载用 `python -m pip uninstall CANConfigPython`。备份和已导出的说明/Skill 不会被卸载删除。
+
+~~~console
+canconfig --version --json
+canconfig doctor --json
+canconfig schema --json
+canconfig apply --help
+canconfig docs export --output ./canconfig-docs
+canconfig skill export --output ./canconfig-skill
+~~~
+
+doctor 成功应有 exit_code=0、ok=true、data.device_opened=false；
+它检查运行包哈希、后端版本、动态库和必要函数，不发现或打开设备。
+schema 返回说明性契约，不是可直接套用的 JSON Schema 或配置文件。
+docs/skill export 只接受不存在的目录，避免覆盖已有文件。
+Skill 的入口是导出目录中的 SKILL.md，可将整个目录复制到所用 Agent 的技能目录；
+不要只复制 SKILL.md 而丢弃 references/assets。安装 Python 包不会自动修改 Agent 设置。
+
+若提示 runtime_invalid/runtime_load_failed，重新安装匹配平台的完整 wheel。
+不要从其他 GUI 目录随意复制 DLL/SO 混用。修改运行库的开发者参见项目构建说明。
+
+## 2. 选择目标和理解输出
+
+每个命令都显式指定端口。Windows 用 COM3；Linux 用 /dev/ttyACM0，
+优先使用已确认设备的 /dev/serial/by-id/... 稳定别名。Linux 区分大小写。
+
+Linux 可用 `ls -l /dev/serial/by-id/`、`ls -l /dev/ttyACM0` 和 `id`
+核对设备及权限。若设备组为 dialout，可由系统管理员把当前用户加入该组，
+重新登录后重试；不同发行版组名可能不同。不要将设备改为全员可写，也不默认用 sudo。
+同一端口应只由一个配置程序使用；本工具的锁只约束同用户的 CANConfigPython 进程。
+
+~~~console
+canconfig info --port COM3 --json
+~~~
+
+Linux 将 COM3 换成确认的 /dev 路径。核对 data.device.uid、type、hardware、firmware
+和 capabilities。info 不提供完整当前配置，writable_fields 仅列字段名，不保证当前状态可写。
+即使是 info 或配置 dry-run，连接也可能改变设备运行模式，应在允许维护的条件下使用。
+
+所有操作输出 UTF-8 JSON；--json 压缩为一行，便于程序读取。
+同时检查进程退出码、ok、effects、verification，不能只检查“程序有输出”。
+
+- effects.attempted/submitted/acknowledged/save_acknowledged：尝试、已提交、已确认及 SAVE 确认数。
+- effects.status=none：该结果没有配置写入；并不承诺连接没有改变运行模式。
+- applied/transferred：所述配置操作或固件传输完成，仍应检查 verification。
+- partial/unknown：部分发生或无法确定。立即停止自动重试/回滚。
+- Python 无法取得有效最终结果时，计数可能为 null，表示未知，不是 0。
+- readback=matched 证明此次回读匹配；power_cycle=not_verified 表示未验证断电保持。
+
+PowerShell 5.1 捕获并解析 JSON 时，在 try 中设置
+`[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)`，
+finally 恢复原值。原生退出码用 $LASTEXITCODE；Linux 用 $?，必须在运行命令后立即读取。
+
+## 3. 准备密码，保留失败信息
+
+密码为 1–10 个 UTF-8 字节，不能含 NUL。中文字符通常占多个字节。
+CLI 只接受环境变量名，不接受明文 --password。不要把密码写进命令、脚本或聊天。
+临时环境变量仍可能被本机管理员读取；它不是密码保险箱。
+
+PowerShell 完整模板（按本次任务替换 try 中的那一条命令）：
+~~~powershell
+$originalEncoding = [Console]::OutputEncoding
+$secure = Read-Host '设备密码' -AsSecureString
+try {
+    [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+    $env:CAN_PASSWORD = [System.Net.NetworkCredential]::new('', $secure).Password
+    $raw = canconfig export --port COM3 --file .\backup-new.ini --password-env CAN_PASSWORD --expect-uid '从已核对设备复制完整UID' --json
+    $exitCode = $LASTEXITCODE
+    $result = $raw | ConvertFrom-Json
+    $result | ConvertTo-Json -Depth 20
+    if ($exitCode -ne 0 -or -not $result.ok) { throw '操作失败；检查 effects 和 verification，停止自动重试。' }
+}
+finally {
+    Remove-Item Env:CAN_PASSWORD -ErrorAction SilentlyContinue
+    $secure.Dispose()
+    [Console]::OutputEncoding = $originalEncoding
+}
+~~~
+
+示例中的端口、文件和 UID 必须替换成已确认值。将成功和失败的 JSON 保存为任务记录，
+其中可能包含设备 UID/配置；分享前按需要处理这些业务信息。
+
+Linux Bash 模板：
+~~~bash
+(
+  trap 'unset CAN_PASSWORD' EXIT
+  read -r -s -p '设备密码: ' CAN_PASSWORD
+  printf '\n'
+  export CAN_PASSWORD
+  canconfig export --port /dev/ttyACM0 --file ./backup-new.ini \
+    --password-env CAN_PASSWORD --expect-uid '从已核对设备复制完整UID' --json
+  rc=$?
+  if [ "$rc" -ne 0 ]; then
+    printf '操作失败，检查结果后停止自动重试。\n' >&2
+    exit "$rc"
+  fi
+)
+~~~
+
+后续所有需要密码的命令，都放在上述模板 try/子 Shell 内执行，确保任何失败路径都清理密码。
+
+## 4. 导出、验证和恢复备份
+
+备份为 INI 文件；JSON 补丁不能用 validate 验证。
+导出会替换已有目标文件，使用新的、可识别设备和时间的文件名。
+
+~~~console
+canconfig export --port COM3 --file backup-new.ini --password-env CAN_PASSWORD --expect-uid UID --json
+canconfig validate --file backup-new.ini --json
+canconfig restore --port COM3 --file backup-new.ini --password-env CAN_PASSWORD --expect-uid UID --check-device --dry-run --json
+~~~
+
+UID 是本次已确认目标 UID，不要直接输入“UID”。
+export 成功后核对 data.file 与 data.complete；validate 离线检查文件规则，不连接设备。
+restore --dry-run 会连接、检查身份和现有状态，但不发 SET/WRITE/SAVE。
+检查 fields、write_count、save_domains 与预期一致后，在已有操作授权范围内去掉
+--dry-run 执行相同命令。恢复成功要求 ok=true 且 verification.readback=matched。
+
+只处理部分配置时，在 export、validate、restore 上使用相同的 --sections 列表。
+可选：parameters、filters、filter_mode、mapping、options、routing、cancom、user_data，
+用逗号连接；默认 all 表示所有支持段。明确选择不支持的段会报错。
+
+--expect-uid 固定当前目标；--check-device 同时要求备份属于该设备。
+跨设备迁移须明确确认兼容性和迁移范围，才省略 --check-device；仍固定目标 UID。
+身份不匹配时不要自动改备份 UID。导出受自适应/只读限制失败时，不要擅自切换模式取备份。
+
+## 5. 用 JSON 修改参数
+
+先导出 Skill，按 assets/examples/index.zh-CN.md 选择匹配型号/版本的例子。
+复制到工作目录，依据已确认目标填入例子的全零 UID，再编辑授权字段。
+既有请求的非零 UID 不匹配时停止，不自动替换。
+
+下例仅用于说明 CANBridge 的结构；时序值取决于型号/通道，不能通用套用：
+~~~json
+{
+  "schema_version": 1,
+  "device_uid": "0000-0000-0000-0000-0000-0000",
+  "changes": {
+    "CAN1_PARAMETER/BRT": [500000, 1, 13, 2]
+  }
+}
+~~~
+
+文件必须是无 BOM 的 UTF-8，字段区分大小写；不能加 $schema、重复键、注释或 NaN。
+Windows PowerShell 5.1 不用 > 创建 JSON，使用明确的 UTF-8 无 BOM 写入方法：
+~~~powershell
+[IO.File]::WriteAllText((Join-Path $PWD 'changes.json'), $jsonText, (New-Object Text.UTF8Encoding($false)))
+~~~
+
+$jsonText 必须是本次成功构造/编辑的 JSON 文本；文件生成或转换失败即停止。
+包装层严格解析并生成临时快照，防止校验与执行读取到不同 JSON。设备规则由 Console 检查。
+
+~~~console
+canconfig apply --port COM3 --file changes.json --password-env CAN_PASSWORD --expect-uid UID --dry-run --json
+canconfig apply --port COM3 --file changes.json --password-env CAN_PASSWORD --expect-uid UID --json
+~~~
+
+第二条只在第一条成功、预检范围已核对且操作已获授权时执行。
+局部字段修改可能写整个配置段，并保存相应域；write_count 不是字段数。
+普通配置会在 SAVE 前回读 RAM、SAVE 后再次回读；这仍不能证明断电保持。
+不要把恢复旧备份当作失败后的自动回滚。
+
+自适应模式：开启须单独提交只有 CANn_PARAMETER/BRT_AUTO:1 的补丁，
+所有通道起始为可完整读取的手动参数。验证只确认模式标志，
+adaptive_result 仍为 not_verified。检测得到的时序/占位值不能导出或写回；
+切回手动须明确提供全部通道的新手动参数，不与开启操作混在一起。
+
+## 6. 修改密码
+
+使用不同变量名保存旧/新密码；两者均遵守 1–10 UTF-8 字节限制。
+扩展第 3 节模板：分别隐藏输入两次，设置 CAN_PASSWORD 与 CAN_NEW_PASSWORD；
+finally/trap 清理两个变量，PowerShell 同时 Dispose 两个 SecureString。
+
+~~~console
+canconfig change-password --port COM3 --expect-uid UID --password-env CAN_PASSWORD --new-password-env CAN_NEW_PASSWORD --dry-run --json
+canconfig change-password --port COM3 --expect-uid UID --password-env CAN_PASSWORD --new-password-env CAN_NEW_PASSWORD --json
+~~~
+
+dry-run 只核对身份和旧密码，不修改、不 SAVE。核对成功后才按授权执行第二条。
+成功看 verification.new_password=authenticated；readback=not_applicable。
+若提交后超时、ACK 后新密码认证失败，保留结果并停止重试，不能断言旧密码仍有效。
+
+## 7. 固件更新
+
+使用厂家最终 .sfb 包，不使用加密中间文件 .sfu。支持 SFU1/SFU2/SFU3 头、
+有负载且不超过 64 MiB。文件格式匹配不证明型号兼容或签名可信。
+外部确认设备型号与固件匹配，并手动让目标设备进入升级模式；CLI 不自动进入。
+
+~~~console
+canconfig firmware-update --port COM3 --file image.sfb --dry-run --json
+canconfig firmware-update --port COM3 --file image.sfb --expect-sha256 HASH --expect-usb-serial SERIAL --timeout-ms 120000 --json
+~~~
+
+第一条完全离线：不枚举、不打开串口。核对 data.sha256 后，将 HASH 替换为该值。
+SERIAL 是已确认的 USB 序列号；设备不提供且用户确认显式端口时省略该选项。
+第二条会下载固件，只在目标和固件已获授权后执行。
+固件模式不接受配置密码/UID；传输为 115200 8N1，默认置 DTR，可用 --no-dtr 关闭。
+
+成功需 verification.transfer=completed、device_return=observed；
+installed_firmware、compatibility 等仍为 not_verified。还需按设备流程检查实际版本。
+Ymodem 可以重发编号数据包，但 CLI 不重新开始整个会话。
+失败或中断时保留 phase/transfer/device_return、检查设备当前升级状态，禁止自动重刷。
+
+## 8. 故障处理和退出码
+
+默认后端期限 120000 ms；--timeout-ms 为 1–3600000 ms。Python 留出额外关闭时间。
+Ctrl+C 请求中断；如果后端不能返回最终结果，显示 unknown，不能视为未写入。
+执行完成后关闭连接，清理密码变量。恢复业务运行模式/断电重启应依设备流程和任务授权进行。
+
+| 退出码 | 意义 | 首先处理 |
+|---|---|---|
+| 0 | 操作完成 | 继续检查 verification 未验证项 |
+| 1 | 连接、运行库、端口锁 | 检查 doctor、明确端口、权限、其他占用程序 |
+| 2 | 认证/密码格式 | 检查变量是否存在及字节长度，不打印密码 |
+| 3 | 文件 I/O | 检查路径/权限，导出选新目录，停止后续写操作 |
+| 4 | 通信或输出协议 | 保留结果，检查连接和运行包版本 |
+| 5 | 不支持 | 核对平台、型号和能力 |
+| 6 | 身份不符 | 停止，核对目标与文件 UID |
+| 7 | 配置/JSON 不合法 | 根据 error.field 修改本次请求后重新预检 |
+| 8 | 硬件结果未知 | 停止自动重试/回滚，人工确认现状 |
+| 9 | 用法错误 | 查看 COMMAND --help；错误不回显可能含密码的参数 |
+| 10 | 回读不匹配 | 停止，保留 effects 和 verification |
+| 11 | 超时 | 先判断 effects，不按超时自动重试 |
+| 12 | 取消 | 先判断 effects，不假设未执行 |
+
+本版不自动重试配置操作、不自动回滚、不证明断电保存。离线检查、假驱动测试、
+安装验证与真实设备验收属于不同证据，不能互相替代。
+
+## 许可证与原生源码
+
+Python 包装层采用 MIT。随包 Console 包含 XinLi 的 GPLv3-or-later Ymodem
+实现，保留其许可证；Qt 和编译器运行库也保留各自许可证。
+`canconfig docs export --output ./canconfig-docs` 会一起导出
+`native-source.tar.gz`。解压后按其中的 DEVELOPING.md 重建原生程序，
+THIRD_PARTY_NOTICES.md 列出了许可和外部依赖的源码位置。

canconfigpython/resources/skill/canconfig-python/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: canconfig-python
+description: Use CANConfigPython on Windows or Linux to inspect CAN device identity, export or restore INI backups, apply JSON configuration, change passwords, or update firmware on an explicit serial port. Use for CLI operations and troubleshooting, not CAN traffic generation or firmware development.
+---
+
+# CANConfigPython device operations
+
+Read [the operation reference](references/operations.md) for the selected task.
+For parameter edits, select a device-specific request from
+[the example catalog](assets/examples/index.en.md) or
+[中文用例目录](assets/examples/index.zh-CN.md), using
+[changes.schema.json](assets/changes.schema.json) for offline structure checks.
+
+## Identify and prepare
+
+1. Run `canconfig --version --json` and `canconfig doctor --json`. This Skill targets
+   Python 0.1.0a1, Console 2.3, bridge API 1. Doctor opens no device.
+2. Use the user-selected explicit COM port on Windows or /dev path on Linux.
+   Query info when authorized to connect. It returns identity, capabilities and field
+   names, not a complete current configuration. Info/configuration dry-run can
+   change device run mode.
+3. Match UID, model and capabilities to the task. Ask only for missing target/scope;
+   existing authorization remains valid. Prepare a concrete reviewable request
+   before any additional approval that is actually required.
+4. Copy a suitable example. Only replace its all-zero placeholder UID using the
+   confirmed target. A mismatch in an existing request/backup is a stop condition,
+   not permission to rewrite it. Change only authorized fields. A partial patch may
+   write an entire section and associated SAVE domains.
+
+## Execute and interpret
+
+- Use UTF-8 JSON without BOM containing exactly schema_version, device_uid and
+  changes. Python rejects duplicate keys and nonfinite numbers. Stop on preparation
+  errors; do not accidentally apply a previous file. Schema/results are envelopes,
+  not patch files. Validate accepts INI backups only.
+- Pass credentials through short-lived environment variables (--password-env);
+  the API accepts in-memory passwords. Never pass secrets in argv, logs, committed
+  files, reports or chat. Clear caller variables in finally/trap paths covering
+  preparation, invocation and result parsing.
+- For configuration writes, run the matching live dry-run, inspect its scope, then
+  execute the unchanged request within existing authorization. A dry-run is not a
+  reservation; execution repeats preflight.
+- Check process exit, ok, effects and verification. On partial/unknown effects,
+  timeout, cancellation, mismatch or missing final JSON, stop automatic retry and
+  rollback; report known effects and uncertainty. Missing output means counts can
+  be null, not zero. Do not infer power-cycle persistence.
+
+## Device-specific boundaries
+
+- Adaptive enable must be a separate patch containing only selected
+  CANn_PARAMETER/BRT_AUTO: 1 fields. All channels must initially have unrestricted
+  manual parameters. It verifies flags only, not detected baud rate.
+- Never export/write back adaptive detected timings/placeholders for any role.
+  Do not disable adaptive merely to get a backup. Returning to manual requires
+  explicitly authorized new manual parameters for every channel.
+- Same-device restore uses --expect-uid and --check-device. Cross-device migration
+  requires explicit scope; retain target --expect-uid, omit --check-device only for
+  that authorized migration.
+- Password change requires explicit UID and distinct old/new environment names.
+  Dry-run authenticates the old password without changing it. Success confirms one
+  new-password authentication, not persistence after power cycle.
+- Firmware .sfb dry-run is offline. Pin SHA-256, confirm external model/image
+  compatibility and that the selected device is already in update mode. Do not add
+  configuration UID/password flags. Transmission plus port return does not prove
+  installed version, signature, compatibility or power-cycle behavior.
+
+## Report
+
+State target, scope, actual effects/verification and needed next action.
+Distinguish simulated/offline checks from physical-device validation.
+Do not disclose passwords or adaptive detected timings.

canconfigpython/resources/skill/canconfig-python/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "CANConfigPython"
+  short_description: "Configure CAN devices with the bundled Python CLI"
+  default_prompt: "Use $canconfig-python to inspect the selected CAN device and prepare the requested configuration change."