serialforge 0.0.1__tar.gz

serialforge-0.0.1/.agents/ARCHITECTURE.md

@@ -0,0 +1,79 @@
+# serialforge · 架构总览
+
+> 类型: 活文档（原地更新，不编号、不归档）  |  最后更新: 2026-10-08
+> 基线 commit: 526ac6f（M4 已完成；无结束符回复已纳入传输层契约，M5 待实现）  |  适用版本: 0.0.1
+> 形态: 完整  |  维护: AI 更新（见 `.agents/rules/15_architecture_doc.md`）
+> 读法: 第 1、2、3、6 节为必读区（每次会话读，合计 ≤150 行）；其余按需读
+
+## 1. 这个项目是干什么的（必读）
+
+- **一句话**：serialforge 为 Windows x64 应用提供基于 QtCore 信号槽和线程的串口通讯、设备发现与命令调度能力。
+- **背景与动因**：把串口字节流、帧定界、设备探测、命令响应和日志封装为可发布到 PyPI 的库，让 PySide6 应用只接触稳定的门面 API。
+- **明确不做**：不包含任何具体设备业务命令；不使用 asyncio 或多进程；不导入 QtWidgets/QtGui；不承诺 Linux、32 位 Windows 或硬件无关的真机行为。
+
+## 2. 外部形态（必读）
+
+- 交付物：可安装的 Python 库 `serialforge`，另有无硬件示例和本地 CI 脚本。
+- 运行方式：使用方 `from serialforge import ...`；业务命令运行时声明并注册；Qt 应用提供 `QCoreApplication` 事件循环。
+- 关键依赖：Python >=3.11；`PySide6-Essentials`（只用 QtCore）、`pyserial`、`loguru`；uv + hatchling 构建。
+
+## 3. 模块地图（必读）
+
+| 模块 / 目录 | 职责（一句话） | 入口（文件:类） | 对外提供 | 依赖谁 | 被谁依赖 |
+| --- | --- | --- | --- | --- | --- |
+| `src/serialforge/enums.py` | 稳定枚举 | 定义层 | 顶层与 advanced 枚举 | 标准库 | 所有层 |
+| `src/serialforge/models.py` | 不可变声明、结果与配置数据类 | 定义层 | 顶层日常数据类 | enums/errors/advanced 类型约束 | 所有层 |
+| `src/serialforge/errors.py` | 异常层次 | 定义层 | `errors` 命名空间 | 标准库 | 所有层 |
+| `src/serialforge/settings.py` | 默认配置常量 | 定义层 | 内部默认值 | 标准库 | 定义层与实现层 |
+| `src/serialforge/protocols.py` | 后端与传输协议 | 定义层 | 内部协议 | models | transport/discovery/connection |
+| `src/serialforge/advanced.py` | 进阶配置和统计再导出 | 再出口 | `advanced.__all__` | 定义层 | 使用方与实现层 |
+| `src/serialforge/transport/` | 字节流、定界、校验、延迟与端口后端 | `__init__.py`：M2 传输组件 | 内部模块 | L0 | discovery/connection/testing |
+| `src/serialforge/connection/` | 命令注册、响应解析与调度；连接生命周期待 M5 | `command_registry.py:CommandRegistry`、`command_dispatcher.py:CommandDispatcher`、`serial_handler.py:SerialHandler` | 顶层门面与内部调度组件 | L0-L2 | `__init__.py` |
+| `src/serialforge/discovery/` | 扫描、探测、缓存 | M6 实现 | `DeviceFinder` | L0-L1 | connection/顶层 |
+| `src/serialforge/diagnostics/` | 流量与文件日志 | `traffic_logger.py:TrafficLogger`、`log_file_manager.py:LogFileManager` | 内部诊断组件 | L0-L1 | connection |
+| `src/serialforge/testing/` | 可脚本化假后端与模拟设备 | `__init__.py`：M2 假后端组件 | testing 命名空间 | L0-L1 | tests/使用方 |
+| `tests/` | 契约、守卫、单元和 API 快照 | `test_*.py` | 本地验证 | src | CI |
+
+## 4. 交互关系（按需）
+
+- 依赖单向：定义层 L0 → transport/diagnostics L1 → discovery/testing L2 → connection L3 → 顶层再导出 L4。
+- 典型路径：`SerialHandler.connect()` 通过 discovery 获取端口，再由 transport 读写；命令经 registry/dispatcher 匹配并以 Qt 信号发送结果。
+- M1 建立定义层、命名空间与契约测试；M2 只实现可替换传输层、帧/校验/延迟基础设施和无硬件测试后端，不提前实现 connection/discovery 门面。
+
+## 5. 状态与外部边界（按需）
+
+- 外部 I/O：M2 起由 pyserial 访问串口；QtCore 负责线程与信号；loguru 在 M3 接入。
+- 配置：人写的工具配置保留根目录 `pyproject.toml`；运行时日志、缓存和状态按项目规则进入 `data/` 或用户目录。
+- 发布：`uv build` 产出构建物；严禁在本项目中执行 PyPI 上传。
+
+## 6. 关键不变量（必读，最容易改错的地方）
+
+- 顶层 `__all__` 恰为设计文档的 15 个名字 —— **违反**：破坏公共 API 预算和快照 —— **生效范围**：`src/serialforge/__init__.py`。
+- `CommandSpec` / `EventSpec` 是 `frozen=True, eq=False` 且全链路保留同一对象 —— **违反**：`result.spec is X` 失效 —— **生效范围**：models、registry、dispatcher、Qt 信号。
+- 发送终止符与接收定界相互独立；无结束符回复使用显式正数 `silence_gap_s` 的 `SILENCE_GAP`，接收循环须在无新字节时周期性 `flush()` —— **违反**：半包误判或命令永不完成 —— **生效范围**：advanced、transport、M5 connection、M6 discovery。
+- 定义层不导入实现子包，跨子包只经 `__init__.py` —— **违反**：循环依赖和架构守卫失败 —— **生效范围**：`src/serialforge/`。
+- 库内只使用 loguru DEBUG 且默认静默 —— **违反**：宿主应用收到意外输出或等级 —— **生效范围**：diagnostics 与 connection。
+- 不在源码定义业务 `CommandSpec` / `EventSpec` —— **违反**：库无法复用于不同设备 —— **生效范围**：`src/serialforge/`。
+- Qt 依赖限于 QtCore，导入无线程、文件、串口和应用初始化副作用 —— **违反**：无界面导入环境被污染 —— **生效范围**：顶层导入与所有定义层模块。
+- 已知坑：当前用户级 `scaffold.py` 有冲突标记；M1 规范目录由模板手动落地，需在交付记录中保留该事实。
+
+## 7. 深潜入口（按需）
+
+| 想深入 | 读什么 |
+| --- | --- |
+| 设计契约 | `串口通讯模块_方案_v10定稿.md` |
+| M1 进度 | `.agents/docs/checkpoint/_archive/0001_m1-foundation.md` |
+| M2 交接 | `.agents/docs/checkpoint/_archive/0002_m2-transport.md` |
+| 任务队列 | `.agents/docs/todo/README.md` |
+| 定义层实现 | `src/serialforge/enums.py`、`models.py`、`errors.py`、`advanced.py` |
+
+## 8. 变更日志（按需，倒序）
+
+| 日期 | commit | 改了什么 |
+| --- | --- | --- |
+| 2026-10-08 | 526ac6f | 明确支持无结束符回复的静默定界，校验间隔并覆盖分片和动态版本号 |
+| 2026-10-08 | 393c7b9 | M4 调度边界、并发写锁与流量信号背压完成；真机版本查询通过 |
+| 2026-10-08 | 222044c | M4 增加注册表、响应解析、调度器及 handler 的注册发送入口 |
+| 2026-10-08 | 1716749 | 同步 M3 已完成的诊断模块与阶段状态；等待确认进入 M4 |
+| 2026-10-01 | 40ab7e7 | M2 传输基础设施、假后端和规范化迁移已提交 |
+| 2026-09-30 | 98ba269 | 完成 M1 定义层与规范目录；进入 M2 传输层开发 |

serialforge-0.0.1/.agents/docs/checkpoint/0006_M5_/350/277/236/346/216/245/351/227/250/351/235/242/345/256/236/347/216/260.md

@@ -0,0 +1,28 @@
+# 0006_M5_连接门面实现
+
+> 任务: todo/0005_M5_连接门面与自动重连.md  |  更新: 2026-10-08  |  进度: 0/5
+> 最近 commit: 9b80efb
+
+## 已完成
+
+- 核对 M4 调度器、M2 可替换后端、M3 诊断模块和设计契约；已建 `feat/m5-m6-lifecycle-discovery` 分支。
+
+## 进行中（下一步从这里继续）
+
+- 实现连接工作线程与读循环，接入 `SerialHandler` 的状态、信号、日志和调度。
+
+## 待办
+
+- 覆盖主动断开、异常断线、自动重连、初始化序列、心跳、无结束符分片回复与线程退出。
+- 实现并测试 M6 设备发现后，完成无参/端口入口的联调。
+- M5 阶段 CI、任务归档、架构更新；M6 有用户本次明确授权，随后继续。
+
+## 关键决策与上下文（恢复任务必读）
+
+- 仅已有依赖 PySide6 QtCore、pyserial、loguru；不引入新依赖。
+- `main.py` 的删除是已有工作区状态，本任务不触碰。
+- 命令发送的 `\r\n` 与无结束符接收定界独立；接收线程必须在无新字节时 `flush()`。
+
+## 验证方式
+
+- 假后端定向测试，最终 `uv run python scripts/ci.py`；M6 再用 COM11 115200 真机扫描。

serialforge-0.0.1/.agents/docs/checkpoint/_archive/0001_m1-foundation.md

@@ -0,0 +1,33 @@
+# 0001 M1 包骨架与定义层
+
+> 任务: todo/0001_M1-foundation.md | 更新: 2026-09-30 | 进度: 1/1
+> 最近 commit: 98ba269（feat/m1-foundation）
+
+## 已完成
+
+- 手动建立 AGENTS、架构总览、规则、工具、todo、checkpoint 和 git hook 结构。
+- 建立 `src/serialforge` 定义层、advanced/errors/testing 命名空间和 QtCore 门面空壳。
+- 写入公共数据类、枚举、构造期校验、对象身份契约、API 快照与架构守卫测试。
+- 配置 uv/hatchling/ty/ruff，生成 `uv.lock`，本地 CI 全量通过。
+- 原 `.agents/docs/checkpoint/0001_m1-foundation.md` 的验证记录已合并到本 checkpoint；阶段进度不再在公开 docs 下重复维护。
+
+## 历史验证记录
+
+- T-09、T-13、T-19、T-23、T-24、T-33、T-36、T-37、T-40、T-45、T-50、T-52、T-53、T-54、T-55 已完成。
+- `uv sync`、`uv run ty check`、`uv run ruff check src tests scripts`、`uv run ruff format --check src tests scripts`、`uv run pytest`（16 passed）、`uv run pylint src`（10.00/10）、`uv build`、`uv run twine check dist/*` 和 `uv run python scripts/ci.py` 均通过。
+- ty 参数、QtCore `Signal`/`Slot`/`QThread.run` smoke 与 `all = "error"` 均无诊断。
+- 未在真实串口硬件、Windows 10、多种 USB 芯片验证；未运行 Python 3.12–3.14 矩阵或最低依赖解析。
+- 用户级 `project-ai-normalize` 的脚手架存在冲突标记，因此项目规范目录按模板手动落地。
+
+## 关键决策与上下文
+
+- 顶层 `__all__` 固定 15 个名字；进阶类型只从 `serialforge.advanced` 导出。
+- `CommandSpec`/`EventSpec` 使用 `frozen=True, eq=False`，不复制对象。
+- 定义层通过延迟导入 advanced 默认配置，保持依赖单向且顶层导入无副作用。
+- 真实业务命令只允许出现在 tests/examples，源码没有任何具体命令实例。
+
+## 验证方式
+
+`uv run python scripts/ci.py` 全量通过：16 个 pytest、ty、ruff、pylint 10.00/10、uv build、twine check。
+
+旧的 `docs/progress/M1.md` 已迁移到本归档 checkpoint；后续阶段以 `.agents/docs/checkpoint/` 为唯一进度位置。

serialforge-0.0.1/.agents/docs/checkpoint/_archive/0002_m2-transport.md

@@ -0,0 +1,36 @@
+> 归档时间: 2026-09-30  |  归档原因: 任务已完成  |  原路径: .agents/docs/checkpoint/0002_m2-transport.md
+
+# 0002 M2 传输层与无硬件测试后端
+
+> 关联任务: todo/0002_M2 transport and no-hardware backend.md  |  更新: 2026-09-30  |  进度: 5/5
+> 最近 commit: 待提交（feat/m2-transport）
+
+## 已完成
+
+- 完成 `BackendSwitch`、`SerialTransport`、`FrameSplitter`、`ChecksumCalculator`、`LatencyTracker`、`PortRegistry`。
+- 完成 `FakeBackend`、`FakeTransport`、`SimulatedDevice`、`use_fake_backend`，支持脚本响应、延迟、回显、分块、主动注入和断线故障。
+- 新增 24 项定向测试，覆盖半包/粘包、四种定界、缓冲上限、六种校验、EWMA、租约和假后端读写。
+- 新增 `scripts/measure_windows_timer.py`；本机 20 次 1 ms 请求观测为 min 1.348 ms / median 1.539 ms / max 1.618 ms。
+- 规范化旧 M1 进度页：`docs/progress/M1.md` 已移入 `.agents/docs/checkpoint/_archive/`，M1 与 M2 todo/checkpoint 均已归档。
+
+## 进行中（下一步从这里继续）
+
+M2 实现与本地验证完成，等待用户确认后进入 M3。后续不得在本阶段继续扩展 connection/discovery。
+
+## 待办
+
+- Windows 10/11 多机器、USB 转串口芯片、拔插/DTR/RTS/真实计时粒度仍未在硬件真机验证。
+- M3：实现 TrafficLogger、LogFileManager 与 loguru 接入。
+
+## 关键决策与上下文（恢复任务必读）
+
+- `FrameSplitter` 内部始终处理 bytes；LINE/DELIMITED 返回去定界符或含边界的原始 bytes，LENGTH_PREFIX 的长度字段表示 payload 长度，SILENCE_GAP 由 `flush()` 发帧。
+- `ChecksumCalculator` 的 CRC16-MODBUS 返回 little-endian，CRC16-CCITT 返回 big-endian，CRC32 返回 little-endian；自定义函数优先。
+- `FakeBackend` 通过 `BackendSwitch` 注入，未改变 `SerialHandler`/`DeviceFinder` 构造签名；`PortRegistry` 是进程内租约表。
+
+## 验证方式
+
+- `uv run python scripts/ci.py --fast`：sync、ruff format、ty、pytest 全部通过，24 passed。
+- `python .agents/tools/newdoc.py --root . check`：编号、引用、任务索引通过。
+- `uv run pylint src/serialforge/transport src/serialforge/testing`：10.00/10。
+- 未执行 PyPI 上传；未在 Windows 10 或真实串口硬件验证。

serialforge-0.0.1/.agents/docs/checkpoint/_archive/0003_m2-handoff.md

@@ -0,0 +1,33 @@
+> 归档时间: 2026-10-01  |  归档原因: M2 已完成，已确认进入 M3  |  原路径: .agents/docs/checkpoint/0003_m2-handoff.md
+
+# 0003 M2 完成与下一阶段交接
+
+> 关联任务: 无（M2 已完成，等待确认进入 M3）  |  更新: 2026-10-01  |  进度: 1/1
+> 最近 commit: 40ab7e7
+
+## 已完成
+
+- M2 已提交：传输层、无硬件后端、帧/校验/延迟/端口基础设施及计时脚本。
+- 项目规范化完成；M1 与 M2 的历史任务/checkpoint 已归档，`docs/progress/M1.md` 已迁出公开 docs。
+- `main.py` 当前处于用户删除状态（`git status` 显示 `D main.py`），交接期间保留，不恢复、不提交。
+
+## 进行中（下一步从这里继续）
+
+M2 已完成；等待用户确认后创建并激活 M3（TrafficLogger、LogFileManager、loguru 接入）。恢复前读 `AGENTS.md`、架构必读区和 todo 索引。用户确认继续后再新建 M3 todo/checkpoint，不要把 M2 误当成未完成任务。
+
+## 待办
+
+- 当前 todo 队列为空；下一里程碑须等用户确认后登记。
+- Windows 10/11 多机器、USB 转串口硬件、拔插、DTR/RTS 及真机计时粒度尚未验证，按设计留待 M7 验证。
+
+## 关键决策与上下文（恢复任务必读）
+
+- 当前分支 `feat/m1-foundation`；最近提交 `40ab7e7 feat(m2): 实现传输层与无硬件测试后端`，其父提交为 M1 `98ba269`。
+- M2 全量本地 CI 通过：`uv run python scripts/ci.py`，24 passed、ty/ruff format/pylint/uv build/twine check 通过。
+- 全仓 `ruff check` 存在两个 M1 基线 import-order 告警，位于 `connection/serial_handler.py` 与 `discovery/device_finder.py`；M2 修改文件的 ruff 检查通过。
+- 本机 20 次 1 ms `sleep` 观测：min 1.348 ms / median 1.539 ms / max 1.618 ms；这不是 USB 串口或 Windows 10 硬件验收。
+
+## 验证方式
+
+- 交接仅变更架构与 checkpoint；运行 `python .agents/tools/newdoc.py --root . check` 校验引用、编号、索引和固定成本。
+- 不运行代码测试：M2 代码没有变化，完整 CI 已在提交 `40ab7e7` 上通过。

serialforge-0.0.1/.agents/docs/checkpoint/_archive/0004_M3_/346/227/245/345/277/227/344/270/216/346/265/201/351/207/217/350/257/212/346/226/255.md

@@ -0,0 +1,36 @@
+> 归档时间: 2026-10-01  |  归档原因: M3 已完成，等待进入 M4  |  原路径: .agents/docs/checkpoint/0004_M3_日志与流量诊断.md
+
+# 0004 M3 日志与流量诊断
+
+> 关联任务: todo/0003_M3_日志与流量诊断.md  |  更新: 2026-10-01  |  进度: 4/4
+> 最近 commit: 待提交（feat/m3-diagnostics）
+
+## 已完成
+- 已确认从 M2 进入 M3；分支 `feat/m3-diagnostics` 从 M2 交接提交 `a24e8ab` 创建。
+- 已登记 todo `0003_M3 日志与流量诊断.md`。
+- 实现 `TrafficLogger` / `LogFileManager`、诊断包导出和 10 项无硬件测试。
+- 定向测试 10 passed；本次 diagnostics Ruff 与 `ty check` 通过。
+- 阶段 CI 通过：34 passed、ty、Ruff、pylint 10.00、`uv build`、`twine check`。
+- 记录实例级日志开关的设计取舍：`.agents/docs/knowledge/software/0001_loguru 默认静默与导入边界.md`。
+
+## 进行中（下一步从这里继续）
+- M3 实现与验证已完成，提交后归档本 checkpoint；等待用户确认进入 M4。
+
+## 待办
+- [x] 实现 TrafficLogger / LogFileManager 与 diagnostics 导出。
+- [x] 添加 T-06/T-20/T-21/T-32/T-51 无硬件测试。
+- [x] 记录日志全局开关与导入边界的实现决策；模块职责符合现有架构地图，不需更新架构总览。
+- [x] 阶段级 CI 与文档检查；记录未验证的 Windows 真机/硬件范围。
+- [x] 更新任务记录并完成本阶段交付。
+
+## 关键决策与上下文（恢复任务必读）
+- 设计基准：`串口通讯模块_方案_v10定稿.md` 第 9.1–9.4 节，T-06、T-20、T-21、T-32、T-51。
+- `LogConfig` 在 `models.py`，`TrafficRecord` 在 `advanced.py`；顶层 `serialforge.__all__` 固定，不得改动。
+- M3 不实现 M4 dispatcher 或 M5 handler 生命周期；以显式 API 驱动开始连接、结束连接、流量与 EVT 记录。
+- loguru 全局 namespace 不在导入时修改；详细理由见 knowledge `0001_loguru 默认静默与导入边界.md`。
+- 工作区有用户删除 `main.py`，禁止恢复、暂存或提交该删除。
+
+## 验证方式
+- 定向运行新增 diagnostics 测试。
+- 阶段收尾运行 `uv run python scripts/ci.py`、`uv run ruff check`/`ruff format --check`（限制本次文件）与 `uv run ty check`。
+- `uv run python .agents/tools/newdoc.py --root . check` 校验文档和索引。

serialforge-0.0.1/.agents/docs/checkpoint/_archive/0005_M4 /345/221/275/344/273/244/346/263/250/345/206/214/344/270/216/350/260/203/345/272/246.md"

@@ -0,0 +1,35 @@
+> 归档时间: 2026-10-08  |  归档原因: M4 任务已完成  |  原路径: .agents/docs/checkpoint/0005_M4 命令注册与调度.md
+
+# 0005_M4 命令注册与调度
+
+> 关联任务: todo/0004_M4_命令注册与调度.md  |  更新: 2026-10-08  |  进度: 6/6
+> 最近 commit: 393c7b9
+
+## 已完成
+
+- 用户确认进入 M4；从 M3 提交建立 `feat/m4-dispatcher`。`uv sync --locked` 已恢复可用环境。
+- 真机 COM11（115200）两次发送 `Version\r\n`，都收到原始字节 `Software version 1.02`，无回复结束符；用户确认这是预期格式。
+- `222044c`：注册表、解析器、调度器与 handler M4 入口的首个可回退单元已提交；定向、架构与 API 测试共 26 项通过，后续新增队列/背压测试 4 项通过。
+- M4 真机链路已通过：`SerialTransport` + `FrameSplitter(SILENCE_GAP, 0.08 s)` + `CommandDispatcher` 在 COM11 返回 `VersionInfo(version='1.02')`，`raw_frames=(b'Software version 1.02',)`，`result.spec is` 原声明。
+- `393c7b9` 完成并发写锁、随机终止路径、多流背压与诊断信号节流；阶段 CI 为 70 passed、Ruff/ty/Pylint 10.00、构建及 twine 通过。
+
+## 进行中（下一步从这里继续）
+
+- M4 已完成；归档本快照，汇报后等待用户确认进入 M5。
+
+## 待办
+
+- M5 接入 handler 生命周期、日志与 transport；M6 再用 COM11 做串口发现真机验收。
+- M6 扫描测试使用无结束符回复的真机，不提前实现 discovery。
+- 已把后续 M5 与 M6 登记为排队任务 0005、0006；M6 含 COM11 真机扫描验收。
+
+## 关键决策与上下文（恢复任务必读）
+
+- `CommandSpec` / `EventSpec` 均为 `frozen=True, eq=False`；注册、结果、事件和 ticket 必须保留同一对象。
+- 真机业务命令只能在 `tests/` 或 `examples/` 声明，不能写入 `src/serialforge/`。
+- 现有 `main.py` 删除是用户在途修改，绝不暂存或恢复。
+
+## 验证方式
+
+- 定向 pytest 逐步验证；M4 完成时运行 `uv run python scripts/ci.py` 及文档检查。
+- 真实 COM11 只执行用户授权的 `Version` 查询；默认自动测试不可访问硬件。

serialforge-0.0.1/.agents/docs/checkpoint/_archive/README.md

@@ -0,0 +1,3 @@
+# 归档目录
+
+本目录存放已过时、**不再被任何文件引用**的历史文档。

serialforge-0.0.1/.agents/docs/explore/_archive/README.md

@@ -0,0 +1,3 @@
+# 归档目录
+
+本目录存放已过时、**不再被任何文件引用**的历史文档。

serialforge-0.0.1/.agents/docs/knowledge/_archive/README.md

@@ -0,0 +1,3 @@
+# 归档目录
+
+本目录存放已过时、**不再被任何文件引用**的历史文档。

serialforge-0.0.1/.agents/docs/knowledge/software/0001_loguru /351/273/230/350/256/244/351/235/231/351/273/230/344/270/216/345/257/274/345/205/245/350/276/271/347/225/214.md"

@@ -0,0 +1,23 @@
+# 0001_loguru 默认静默与导入边界
+
+> 分类: knowledge/software  |  创建: 2026-10-01  |  适用范围: diagnostics 日志实现
+> 关键词: loguru、默认静默、导入副作用、enqueue
+
+## 结论（先给做法，再讲原理）
+不要在包导入时调用 `logger.disable("serialforge")` 或 `logger.enable(...)`。`TrafficLogger` 根据实例的 `LogConfig.enabled` 决定是否发出 DEBUG 记录；启用文件记录时，`LogFileManager` 只接收绑定了本连接 `conn_id` 的记录。
+
+## 背景
+设计文档提议在导入时禁用 `serialforge` namespace，再由日志开关启用它。loguru 的这些 API 修改进程级 logger 状态；导入 `serialforge` 则必须无副作用，也不能覆盖宿主程序自己的 loguru 配置。
+
+## 细节
+日志调用只从 `TrafficLogger` 的显式记录方法发出。默认 `enabled=False` 时不会发出记录，因此不需要改动 loguru 的全局 namespace 开关。启用后，记录通过宿主已配置的 loguru sink 输出；`save_to_file=True` 时另挂 `enqueue=True` 的连接专属 sink，filter 按 `conn_id` 隔离多个连接。
+
+关闭连接或文件开关时先移除该连接的 sink，再调用 `logger.complete()` 排空队列。该 `complete()` 会同步等待队列 sink；它返回的 awaitable 用于宿主配置的异步 sink，本项目不创建或运行异步 sink。
+
+## 常见改动点
+- 想调整默认静默策略 → 改 `src/serialforge/diagnostics/traffic_logger.py` 的 `_record()` / `record_event()`，不要在 `__init__.py` 增加 logger 全局设置。
+- 想调整连接文件隔离 → 改 `src/serialforge/diagnostics/log_file_manager.py` 的 `connection_filter`，确保它仍只匹配 `conn_id`。
+
+## 参考
+- 关联代码：`src/serialforge/diagnostics/traffic_logger.py`、`src/serialforge/diagnostics/log_file_manager.py`
+- 设计依据：`串口通讯模块_方案_v10定稿.md` 第 9.2、9.3 节；项目约束要求导入 `serialforge` 无副作用。

serialforge-0.0.1/.agents/docs/questions/_archive/README.md

@@ -0,0 +1,3 @@
+# 归档目录
+
+本目录存放已过时、**不再被任何文件引用**的历史文档。

serialforge-0.0.1/.agents/docs/todo/0005_M5_/350/277/236/346/216/245/351/227/250/351/235/242/344/270/216/350/207/252/345/212/250/351/207/215/350/277/236.md

@@ -0,0 +1,21 @@
+# 0005_M5 连接门面与自动重连
+
+> 状态: 进行中  |  创建: 2026-10-08  |  完成: -
+> 优先级: 高  |  关联 checkpoint: checkpoint/0006_M5_连接门面实现.md
+
+## 背景
+
+设计文档第 14 节要求在 M4 命令调度验收后，才把传输、诊断与调度接入 `SerialHandler` 生命周期。本任务在 M4 完成并得到用户阶段确认后启动。
+
+## 目标（验收标准）
+- [ ] `SerialHandler.connect()` 支持无参、端口名及 `DeviceInfo` 三种入口；连接、断线和断开状态及信号符合设计。
+- [ ] 自动重连、初始化序列、心跳、日志会话与端口所有权在假后端中通过；主动断开不重连。
+- [ ] 命令、事件、流量与错误信号跨线程正确送达；并发发送和退出后线程/句柄无泄漏。
+- [ ] 接收循环按 `profile.framing` 定界；`SILENCE_GAP` 在无新字节时仍定期 `flush()`，支持发送 `Version\r\n`、接收无结束符版本回复，并保持版本号动态匹配。假后端覆盖分片回复及超时前完成。
+- [ ] 完成 M5 阶段 CI，汇报未验证范围并等待确认进入 M6。
+
+## 阻塞 / 依赖
+
+- 依赖 M4 完成与用户阶段确认；不得提前进入 M5 实现。
+
+## 完成记录

serialforge-0.0.1/.agents/docs/todo/0006_M6_/350/256/276/345/244/207/345/217/221/347/216/260/344/270/216_COM11_/347/234/237/346/234/272/346/211/253/346/217/217.md

@@ -0,0 +1,21 @@
+# 0006_M6 设备发现与 COM11 真机扫描
+
+> 状态: 排队  |  创建: 2026-10-08  |  完成: -
+> 优先级: 高  |  关联 checkpoint: -
+
+## 背景
+
+用户提供 Windows 真机 COM11，115200 波特率，发送 `Version\r\n`，回复为无结束符的 `Software version <版本号>`。2026-10-08 实测当前版本 `1.02`，COM11 的 VID/PID 为 `067B:23A3`。M6 按设计文档第 14 节完成扫描、波特率探测、缓存与 `DeviceFinder` 后，用这台设备做显式真机验收。
+
+## 目标（验收标准）
+- [ ] 实现 `PortScanner`、`BaudProber`、`BaudCache` 与 `DeviceFinder`，覆盖 `ALL`/`FIRST_MATCH`、取消、缓存回退、占用端口跳过和句柄释放。
+- [ ] 无硬件测试默认不打开真实串口；发现流程的关键分支由假后端验证。
+- [ ] 发现探测按 `profile.framing` 定界；无结束符的回复在静默间隔后也能完成探测，假后端覆盖分片回复和取消。
+- [ ] 用户显式运行真机测试时，用 `CommandSpec("Version", r"Software version (?P<version>\d+\.\d+)")`、发送 `Version\r\n`、115200 和可配置静默间隔帧定界扫描 COM11；得到端口、波特率及版本回复，版本号不得写死。
+- [ ] 完成 M6 阶段 CI 和真机验证记录，汇报后等待确认进入 M7。
+
+## 阻塞 / 依赖
+
+- 依赖 M5 完成与用户阶段确认；M4 不提前实现 discovery。
+
+## 完成记录

serialforge-0.0.1/.agents/docs/todo/README.md

@@ -0,0 +1,27 @@
+# 任务索引与调度表（todo/README.md）
+
+> 本文件是 `.agents/docs/todo/` 的**唯一调度真源**。
+> 被要求「继续任务」时**只读这一个文件**——不要 ls 目录、不要逐个读 todo 文档（省 token）。
+> 维护一律用 `python .agents/tools/taskmgr.py`，不要手改表格。
+> 规则见 `.agents/rules/07_task_tracking.md` §2。
+> 最后更新: 2026-10-08  |  激活任务: 0005_M5_连接门面与自动重连
+
+## 激活中（同时最多一个）
+
+| 编号 | 任务 | 优先级 | 关联 checkpoint |
+| --- | --- | --- | --- |
+| 0005 | [0005_M5_连接门面与自动重连](./0005_M5_连接门面与自动重连.md) | 高 | checkpoint/0006_M5_连接门面实现.md |
+
+## 排队中（按 优先级 → 编号 排序）
+
+| 编号 | 任务 | 优先级 | 关联 checkpoint |
+| --- | --- | --- | --- |
+| 0006 | [0006_M6_设备发现与_COM11_真机扫描](./0006_M6_设备发现与_COM11_真机扫描.md) | 高 | - |
+
+## 说明
+
+- **单一激活**：「激活中」永远最多一行；激活新任务时旧的自动退回「排队中」。
+- **完成即出表**：任务归档（完成 / 废弃）后**必须**从本表删除该行，历史由 `todo/_archive/` 留存。
+- **排序**：优先级 `高 > 中 > 低`，同优先级按编号升序（先建的先做）。
+- **改优先级**：`taskmgr.py priority <编号> 高|中|低`（同步改任务文档文首的 `优先级`）。
+- **队列为空**：两个表都空 = 真的没有排队任务，去问用户，不要自己从代码里猜一个出来。

serialforge-0.0.1/.agents/docs/todo/_archive/0001_M1-foundation.md

@@ -0,0 +1,26 @@
+> 归档时间: 2026-09-30  |  归档原因: 任务已完成  |  原路径: .agents/docs/todo/0001_M1-foundation.md
+
+# 0001 M1 foundation
+
+> 状态: 已完成  |  创建: 2026-09-30  |  完成: 2026-09-30
+> 优先级: 高  |  关联 checkpoint: checkpoint/0001_m1-foundation.md
+
+## 背景
+
+设计文档要求先交付 M1：建立 `src` 布局、定义层数据类与枚举、分层命名空间、架构守卫/API 快照骨架、ty 验证夹具和本地 CI。项目当前只有占位 `main.py`，没有可复用的库实现。
+
+## 目标（验收标准）
+- [x] `uv sync` 成功，`uv.lock` 入库，包可从 `src/serialforge` 导入。
+- [x] 顶层 `__all__` 恰为 15 个名字；`advanced`、`errors`、`testing` 命名空间边界稳定。
+- [x] `CommandSpec`、`EventSpec`、`DeviceProfile`、`LogConfig`、结果类和 M1 进阶配置具备构造期校验及不可变契约。
+- [x] `CommandSpec`/`EventSpec` 模式推断、默认值、对象身份语义和 `DeviceProfile` 默认 8N1 有测试。
+- [x] `test_architecture.py`、API 快照骨架、`tests/typing/qt_smoke.py`、`scripts/ci.py` 可运行。
+- [x] `.agents/docs/checkpoint/0001_m1-foundation.md` 记录三项 ty 未验证点、命令结果、假设与未在真机验证项。
+
+## 阻塞 / 依赖
+
+设计文档指定的第三方依赖已由用户需求明确授权：`PySide6-Essentials`、`pyserial`、`loguru`；工具链使用 uv。
+
+## 完成记录
+
+M1 验收已在 2026-09-30 完成；全量本地 CI 通过，未进行真实串口或 Windows 10 验证。进度记录已迁入 `.agents/docs/checkpoint/`，旧的 `docs/progress/M1.md` 已归档。

serialforge-0.0.1/.agents/docs/todo/_archive/0002_M2 transport and no-hardware backend.md

@@ -0,0 +1,24 @@
+> 归档时间: 2026-09-30  |  归档原因: 任务已完成  |  原路径: .agents/docs/todo/0002_M2 transport and no-hardware backend.md
+
+# 0002_M2 transport and no-hardware backend
+
+> 状态: 已完成  |  创建: 2026-09-30  |  完成: 2026-09-30
+> 优先级: 高  |  关联 checkpoint: checkpoint/0002_m2-transport.md
+
+## 背景
+
+设计文档的 M2 负责建立可替换的串口传输基础设施，使后续 connection/discovery 能在真实后端与无硬件假后端之间复用同一协议。当前 `transport` 只有空壳，`testing` 只有数据占位，M1 的定义层已冻结。
+
+## 目标（验收标准）
+- [ ] `BackendSwitch`、`SerialTransport`、`FrameSplitter`、`ChecksumCalculator`、`LatencyTracker`、`PortRegistry` 按 L1 单向依赖实现并有完整类型注解。
+- [ ] `FakeBackend`、`FakeTransport`、`SimulatedDevice`、`use_fake_backend` 可注入后端，支持延迟、粘包/半包、乱码和断线故障脚本。
+- [ ] 帧定界覆盖 LINE、DELIMITED、LENGTH_PREFIX、SILENCE_GAP，处理超长缓冲并保留原始 bytes；校验覆盖 NONE、SUM8、XOR、CRC16-MODBUS、CRC16-CCITT、CRC32 及自定义函数。
+- [ ] 延迟跟踪实现 RFC 6298 风格 EWMA、冷启动和轮询间隔上下限；端口注册表实现进程内独占租约。
+- [ ] 加入 Windows 计时粒度实测脚本；真实 Windows/硬件结果如实标为未验证。
+- [ ] 新增 M2 单元测试，更新架构总览、checkpoint 和任务完成记录；`uv run pytest`、ruff、ty 通过。
+
+## 阻塞 / 依赖
+
+## 完成记录
+
+M2 传输层、可替换假后端、计时脚本和定向测试已完成；`uv run python scripts/ci.py --fast`、ty、ruff、pylint 和规范校验通过。真实 Windows 10/11、多种 USB 芯片及串口硬件仍待 M7 验证。

serialforge-0.0.1/.agents/docs/todo/_archive/0003_M3_/346/227/245/345/277/227/344/270/216/346/265/201/351/207/217/350/257/212/346/226/255.md

@@ -0,0 +1,23 @@
+> 归档时间: 2026-10-01  |  归档原因: M3 实现、测试与阶段 CI 已完成  |  原路径: .agents/docs/todo/0003_M3_日志与流量诊断.md
+
+# 0003_M3 日志与流量诊断
+
+> 状态: 已完成  |  创建: 2026-10-01  |  完成: 2026-10-01
+> 优先级: 高  |  关联 checkpoint: checkpoint/0004_M3_日志与流量诊断.md
+
+## 背景
+M2 已完成传输层和无硬件后端；M3 落地可复用的流量记录与按连接日志文件能力，供后续 M4/M5 收发调度和连接生命周期接入。实现遵循设计文档第 9 节与 T-06、T-20、T-21、T-32、T-51。
+
+## 目标（验收标准）
+- [x] `TrafficLogger` 接收 TX/RX 流量，生成毫秒时间戳、十六进制和可读文本；保留有界环形缓冲并发出 `traffic_logged(TrafficRecord)`。
+- [x] 所有日志仅使用 loguru DEBUG；默认禁用时无输出；启用后采用延迟格式化，导入 `serialforge` 不修改 loguru 全局状态。
+- [x] `LogFileManager` 支持显式连接会话开始/结束与落盘开关；每次连接一个 UTF-8 时间戳 `.txt` 文件；活动连接切换落盘开关继续写原文件，探测阶段不创建文件。
+- [x] 默认目录使用 `QStandardPaths` 的用户本地数据目录和应用名；文件名冲突追加后缀；保留清理只删除符合本库时间戳命名的文件，最多保留 `max_files`。
+- [x] 文件行符合设计格式并包含 `SPEC:<name>` / `MATCHED:<name>` / `RAW` TX 标注；`TrafficRecord` 与文件记录表达一致。
+- [x] 达到 `max_file_bytes` 后停止写 TX/RX 流量，继续写 EVT，写一次超限说明并在结束时汇总丢弃行数。
+- [x] 覆盖运行时切换、目录创建/不可写、冲突文件名、清理失败、文件上限和仅 DEBUG 等设计文档 T-21 测试清单；定向测试与阶段 CI 通过。
+
+## 阻塞 / 依赖
+
+## 完成记录
+M3 已完成。新增 `TrafficLogger`、`LogFileManager`、诊断包导出和 10 项无硬件测试；`uv run python scripts/ci.py` 通过（34 passed、ty、Ruff、pylint 10.00、uv build、twine check）。未执行 Windows 10/11 多机器、真实 USB 串口和硬件拔插验证，按设计留待 M7。

serialforge-0.0.1/.agents/docs/todo/_archive/0004_M4_/345/221/275/344/273/244/346/263/250/345/206/214/344/270/216/350/260/203/345/272/246.md

@@ -0,0 +1,27 @@
+> 归档时间: 2026-10-08  |  归档原因: M4 实现、真机 Version 验证和阶段 CI 已完成  |  原路径: .agents/docs/todo/0004_M4_命令注册与调度.md
+
+# 0004_M4 命令注册与调度
+
+> 状态: 已完成  |  创建: 2026-10-08  |  完成: 2026-10-08
+> 优先级: 高  |  关联 checkpoint: checkpoint/0005_M4 命令注册与调度.md
+
+## 背景
+
+M3 的传输、假后端与诊断组件已完成。M4 按设计文档第 5、8、13、14 节实现命令注册、文本匹配、响应解析和调度；真实设备 COM11 可发送 `Version\r\n`，115200 波特率下回复 `Software version <版本号>`，回复无结束符。设备发现仍属 M6。
+
+## 目标（验收标准）
+- [x] `CommandRegistry` 保留声明对象身份，支持运行时注册/注销、不可变快照、重复与模板骨架冲突检测、文本精确及模板匹配。
+- [x] `CommandDispatcher` 支持 `NO_REPLY`、`SINGLE`、`MULTI`、`STREAM` 和 `EXCLUSIVE`、`TAGGED`；结果及事件携带原始声明对象。
+- [x] 实现参数注入防护、数据类/数值/字典解析、设备错误、回显跳过、主动上报和原始文本发送。
+- [x] 实现优先级、队列上限、取消、超时、自适应 RTO、迟到帧隔离和恰好一次完成；STREAM 背压与日志 TX 标注符合设计。
+- [x] 无硬件测试覆盖设计文档 M4 所列任务和关键组合；以不同版本号的 `Software version <版本号>` 测试真实设备声明，且默认测试不打开 COM11。
+- [x] 阶段 CI、架构与文档检查通过；Windows 真机和未验证项据实记录，汇报后等待确认进入 M5。
+
+## 阻塞 / 依赖
+
+- M3 已完成。当前仓库无 `dev` 分支，M4 从 M3 提交 `a48a66e` 建立 `feat/m4-dispatcher`。
+- M6 才实现串口扫描；届时用 COM11/115200 和无结束符回复验证发现功能。
+
+## 完成记录
+
+M4 代码提交 `222044c`、`393c7b9`。`uv run python scripts/ci.py` 通过：70 项测试、Ruff、ty、Pylint 10.00、wheel/sdist 构建与 `twine check`；`newdoc.py check` 通过。COM11/115200 真机一次 `Version\r\n` 查询通过，按静默间隔定界得到无结束符回复 `Software version 1.02`，解析结果保留原命令对象。M5 才将调度器、日志和传输正式接入 handler 生命周期；M6 才执行真实串口扫描。Windows 10/11 多机器、不同芯片、拔插/重连仍未验证，依设计留待 M7。

serialforge-0.0.1/.agents/docs/todo/_archive/README.md

@@ -0,0 +1,3 @@
+# 归档目录
+
+本目录存放已过时、**不再被任何文件引用**的历史文档。