pydiag 1.0.0__tar.gz

pydiag-1.0.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+本文件记录 pydiag 的所有重要变更。
+格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-22
+
+首个公开发布版本（公开版本号自 1.0.0 起算）。
+
+### Added
+
+- **多设备自动探测**：遍历所有厂商 → 设备 → 通道，以「收到 ECU 应答」为判据定位诊断通道；
+  探测结果写回配置，下次启动走缓存快速校验（约 0.6 秒）。
+- **多厂商设备驱动**：ZLG（Windows DLL / Linux libusb 两套）、PEAK PCAN、Vector XL、Linux SocketCAN、虚拟回环。
+  多盒同时在线按序列号 / UID 稳定区分。
+- **四种协议**：DoCAN（ISO 15765-2）、DoLIN（ISO 17987-2）、DoIP（ISO 13400）、OBD-II（SAE J1979），
+  统一 `--protocol` 入口。
+- **四种安全访问算法形态**：固定 key、内置算法（`xor` / `const_add` / `invert` / `swap` / `mask_shift` / `aes_ecb`）、
+  Python 脚本、OEM DLL（A/B/C 三种调用约定）。
+- **交互模式 S3 心跳保活**：进入扩展会话后后台每 2 秒发 `3E 00`（抑制响应），手动输入慢不掉会话。
+- **NRC 负响应码中文描述**：所有 `[NEG]` 输出自动附带含义与处置建议。
+- **可插拔驱动的四层配置**：命令行显式参数 > profile 配置 > 自动探测 > 内置默认。
+- **多 profile 持久化**：每个 ECU 独立记住设备 / 通道 / ID / 波特率 / 算法。
+- **轮转日志**（5 MB × 5 份）+ `pydiag logs` 子命令 + `PYDIAG_LOG_LEVEL=DEBUG` 帧级日志。
+- **内置自检** `pydiag selftest`：6 项检查全部跑在虚拟设备上，无需硬件。
+- 10 个子命令：`devices` / `probe` / `smoke` / `request` / `security` / `diag-round` /
+  `interactive` / `selftest` / `config` / `logs`。
+
+### Notes
+
+- 基础安装零第三方 Python 依赖；`aes_ecb` 算法需 `pip install "pydiag[crypto]"`。
+- 随包分发 ZLG / PEAK 的厂商驱动二进制，版权与来源见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。
+- Vector `vxlapi64.dll` 因 EULA 限制不随包分发。

pydiag-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# 贡献指南
+
+感谢你愿意改进 pydiag。这个项目的目标很具体：**把 UDS 诊断这件事在命令行里做到可靠、可复现**。
+所以贡献门槛不在代码量，而在「能不能被验证」。
+
+## 开发环境
+
+```bash
+git clone https://github.com/zhifou5065/pydiag.git
+cd pydiag
+python -m venv .venv
+. .venv/Scripts/activate          # Windows
+# . .venv/bin/activate            # Linux / macOS
+pip install -e ".[dev]"
+pydiag selftest                   # 应输出 6/6 通过
+```
+
+要求 Python 3.10+。没有硬件也可以开发 —— 所有自检跑在 `virtual:0` 虚拟设备上。
+
+## 改动前先跑这两条
+
+```bash
+pydiag selftest                   # 六项基本链路
+python tools/build_dist.py        # 确认还能正常打包
+```
+
+自检里有任何一项 `NG`，先在干净环境下复现再改代码。
+
+## 代码结构约定
+
+| 目录 | 职责 | 改动影响面 |
+|---|---|---|
+| `zuds.py` | UDS 核心：ISO-TP、会话、27 服务、DoLIN / DoIP 传输 | 全局，改前务必跑全量自检 |
+| `zuds_security.py` | 安全访问编排、DLL 调用约定、内置算法注册表 | 安全相关 |
+| `sec_algo.py` | 命令行 / profile → 算法函数的解析层 | 只影响 27 服务入口 |
+| `devices/` | 各厂商驱动实现 | 只影响对应厂商 |
+| `autodetect.py` | 多设备多通道探测 | 影响所有裸跑命令 |
+| `cli.py` | 参数定义与输出渲染 | 影响用户可见行为 |
+
+**分层原则**：协议层不认识设备，设备层不认识 UDS。新增能力尽量落在对应层，不要跨层写死。
+
+### 新增设备驱动
+
+实现 `BaseDriver`（`is_available` / `list_devices` / `open`）与 `BaseCANDevice.open_channel`，
+在 `devices/__init__.py` 注册。CLI、自动探测、配置层不需要任何改动 —— 如果你的改动需要改这三个地方，
+说明抽象漏了，先补抽象。
+
+### 新增内置安全算法
+
+```python
+from pydiag.zuds_security import register_builtin
+
+@register_builtin("my_algo")
+def factory(key: str = "00000000"):
+    kb = bytes.fromhex(key)
+    def fn(seed: bytes, level: int) -> bytes:
+        return bytes((s ^ kb[i % len(kb)]) + level for i, s in enumerate(seed))
+    return fn
+```
+
+并在 `zuds_security.py` 的算法表与 README 的「内置算法」表格里同步登记。
+
+## 绝对不要提交的东西
+
+- `.pydiag_config/` 或任何含**真实 ECU 解锁密钥、设备序列号、VIN** 的配置与日志
+- 抓包文件、`*.log`、`*.jsonl`
+- 你所在公司的 DBC / ODX / CDD 文件与诊断规范原文
+- 任何厂商 NDA 覆盖的算法 DLL
+
+提 issue 贴输出时同样注意：把序列号和 key 抹掉。需要展示密钥形态时用 `1A2B3C4D` 这类中性值。
+
+## 提交与 PR
+
+- 一个 PR 解决一个问题。重构与功能改动尽量分开。
+- commit message 说明**改了什么 + 为什么**，不要求特定格式，但要能读懂。
+- PR 描述里请写清：**怎么验证的**（跑了哪些命令、接的什么硬件、输出是什么）。
+  只说「已测试」不写过程的 PR 会被要求补充。
+- 新增用户可见行为 → 同步更新 `README.md`；新增版本 → 更新 `CHANGELOG.md` 的 `[Unreleased]`。
+
+## 报告问题
+
+- 功能异常 / 用法疑问 → [Issues](https://github.com/zhifou5065/pydiag/issues)
+- 安全漏洞 → 不要开 issue，按 [SECURITY.md](SECURITY.md) 私下报告

pydiag-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Diag Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydiag-1.0.0/MANIFEST.in

@@ -0,0 +1,19 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+include THIRD_PARTY_NOTICES.md
+include pyproject.toml
+include setup.py
+
+# 第三方驱动二进制（随包分发，见 THIRD_PARTY_NOTICES.md）
+recursive-include src/pydiag/vendor *.dll *.so *.dylib *.rules *.md
+recursive-include src/pydiag/zlg_runtime *.dll *.xml *.ini *.md
+
+# 排除运行时产物与缓存
+prune .pydiag_config
+prune .venv
+prune dist
+prune build
+global-exclude *.py[cod] *.log *.jsonl