Hermes/DbusSmsForward

Fork 0

Files

T

Hermes 9f1ee9ffe6 feat: publish dbussmsforward refactor

2026-05-08 23:54:03 +08:00

14 KiB

Raw Permalink Blame History

DbusSmsForward Debian 重构状态报告与下一步落地清单

For Hermes: Use subagent-driven-development skill to implement this plan task-by-task.

Goal: 基于当前仓库实际状态，给出一份 Debian-first 的真实重构进度报告，并列出后续最小可落地的执行清单，避免再把方向带回 OpenWRT。

Architecture: 当前仓库处于双轨状态：保留 C# Worker 主线，同时新增 Python 重构线。Python 线已经形成可测试的运行时核心，但 Web 管理层和 Debian 交付闭环尚未完成；C# 线则有 Debian 友好的部分配置改造，但还不是完整的 Web 化交付形态。

Tech Stack: Python 3.11、unittest、CLI runtime、ModemManager/DBus 抽象、C# .NET 8 Worker、Systemd-oriented configuration

一、结论摘要

1. 当前方向应明确为 Debian-first

本项目当前应围绕：

Debian 运行
ModemManager/DBus 短信接收
Web 管理
不要求在 Debian 目标机上编译源码

不应再把“下一步推进目标”描述为 OpenWRT 部署。

2. 当前重构不是没进展，但也还没到 Debian Web 成品

仓库里的 Python 重构线已经完成了“核心运行层”的大量工作：

配置模型
短信来源抽象
文件源/ModemManager 源
sender 分发
AutmanPush 错误结构化
轮询、去重、fetch issue 统计
CLI 基本闭环
自动化测试覆盖

但 Debian Web 管理版本身尚未完成，因为还缺：

HTTP 服务入口
Web API
前端页面
配置读写 API
状态 API
systemd/service 交付文件
Debian 部署说明与目录规范

3. C# 主线仍存在，但并非当前可直接交付的 Debian Web 版本

C# 线保留了较多历史功能与 Debian 友好的配置思路，但从当前文件状态看，它仍然是 Worker 应用，不是完整 Web 项目，且存在引用类与当前可见文件状态不完全一致的问题，因此不适合作为“已完成的 Debian Web 版”来对外描述。

二、实际检查到的仓库状态

仓库路径：/Users/chick/.Hermes/workspace/DbusSmsForward

目录结构观察

C# 主线目录：DbusTest/
Python 重构目录：src/dbussmsforward/
Python 测试目录：tests/
README：README.md

粗略文件数量

DbusTest/ 文件数：35
src/dbussmsforward/ 文件数：14
tests/ 文件数：9

这说明仓库现在不是“只剩一个新实现”，而是明确的双轨并存状态。

三、Python 重构线：已完成内容

1. 配置模型已成型

已检查文件：

src/dbussmsforward/config.py

已具备：

DaemonConfig
ForwardingConfig
AutmanPushConfig
SmsSourceConfig
NotificationChannels
AppConfig
legacy appSettings/appsettings 到新模型的兼容映射

说明：Python 线已经不是零散脚本，而是具备明确配置边界的可持续实现。

2. 短信源抽象已成型

已检查文件：

src/dbussmsforward/source.py

已具备：

FileSmsSource
ModemManagerSmsSource
PythonDbusModemManagerProxy
FetchIssue

说明：

modemmanager source 是 Debian-first 能力，不是 OpenWRT 专属。
当前 Python 线已经具备在 Debian + ModemManager 环境继续推进的正确技术基础。

3. 通知分发核心已成型

已检查文件：

src/dbussmsforward/notifications.py
src/dbussmsforward/app.py

已具备：

console sender
AutmanPush sender
DispatchOutcome
SenderDispatchResult
sender 级别失败记录
HTTP/timeout/network/unknown 分类
HTTP 响应片段摘录
partial success 保留
dedupe
轮询统计
fetch issue 聚合

4. CLI 基本闭环已经存在

已检查文件：

src/dbussmsforward/cli.py

当前命令：

run
send
validate-config
print-sample-config

说明：

这已经满足“核心运行原型”的最低闭环。
但还不是 Web 管理闭环。

四、Python 重构线：验证状态

1. CLI 测试

命令：

PYTHONPATH=src python3 -m unittest tests.test_cli -v

结果：10/10 通过

2. 运行时流程测试

命令：

PYTHONPATH=src python3 -m unittest tests.test_runtime_flow -v

结果：16/16 通过

3. 配置模型测试

命令：

PYTHONPATH=src python3 -m unittest tests.test_config_model -v

结果：4/4 通过

4. 关于“全量测试”口径的注意事项

如果直接运行：

python3 -m unittest discover -s tests -v

会失败，原因不是测试逻辑本身坏了，而是当前仓库还没有把 PYTHONPATH=src 或等价安装流程固化到默认测试入口里，导致：

test_config_model
test_runtime_flow 在 discover 模式下导入 dbussmsforward 失败

这说明：

测试内容本身大体可用
但仓库级测试入口还没标准化

这属于 Debian 交付前必须补齐的一环。

五、C# 主线：当前真实状态

1. 仍是 Worker，不是 Web 项目

已检查文件：

DbusTest/DbusSmsForward.csproj

当前项目 SDK：

<Project Sdk="Microsoft.NET.Sdk.Worker">

说明：

这不是 Microsoft.NET.Sdk.Web
当前 C# 主线不能被称为“已完成 Web 化”

2. 有 Debian 友好的配置痕迹

已检查文件：

DbusTest/Helper/ConfigHelper.cs

确认存在：

/etc/dbussmsforward/appsettings.json 的优先加载路径
DBUSSMSFORWARD_CONFIG_PATH 环境变量支持
SaveOptions / LoadOptions
旧配置与新配置转换

说明：

C# 线并非完全无效，已经有面向 Debian 服务运行的配置设计。
但这只是“服务化/配置化能力”，不是完整 Web 管理版。

3. Program.cs 依赖的若干类当前未直接看到实现文件

在 DbusTest/Program.cs 中可见引用：

SampleConfigFactory
LegacyConfigurationBridge
CommandLineConfigurationApplier
ConfigurationValidator

但本轮目录巡检中未直接发现对应文件，说明至少有以下一种情况：

文件缺失
尚未提交完整
放在当前未显式识别的位置
或重构过程中断过

因此，当前不应把 C# 主线描述为“已稳定可构建的 Debian Web 版”。

4. README 仍是旧交付叙事

已检查文件：

README.md

当前 README 仍主要描述：

直接运行旧二进制
-fE/-fP/-fW/... 旧参数模式
Native AOT 交叉编译

没有覆盖：

Python 重构线的运行方式
Debian-first Web 管理目标
统一部署方式
systemd 落地方式

这意味着：

仓库文档叙事仍停留在旧时代
这会持续误导后续判断与交付方向

六、当前最准确的项目分层判断

已完成层

Python 核心配置模型
Python 短信源抽象（含 ModemManager）
Python 通知分发运行时
Python CLI 基本闭环
单元/流程级测试覆盖的大部分核心行为

半完成层

C# Debian 服务化配置思路
legacy -> 新配置兼容桥接思路
多通知渠道的旧实现保留

明显未完成层

Debian Web API
Debian Web 前端
Web 管理配置读写
服务状态查看接口
消息查看/发送 API
systemd/service 交付物
Debian 安装/升级/目录规范
统一测试入口
README/部署文档重写

七、建议的方向收敛

建议主路线

以 Python 线作为 Debian-first 主实现继续推进。

原因：

Python 线目前已经具备可测试、可迭代的核心运行时
已有 ModemManager 抽象，技术方向与 Debian 目标一致
当前 Web 化缺口更适合作为 Python 层增量补齐
C# 线当前更适合做“参考/兼容来源”，不适合作为当前主交付叙事

C# 线建议定位

短期内将 C# 线定义为：

历史主线
兼容配置与行为参考来源
功能映射对照对象

而不是当前 Debian Web 交付主线。

八、下一步落地清单（按优先级排序）

下面这份清单按“最小可落地 Debian Web 版”来排，不再发散。

阶段 0：先把工程入口和叙事统一（高优先级，半天内可做）

Task 0.1：补统一测试入口

Objective: 让仓库级测试命令不依赖手工写 PYTHONPATH=src

Files:

Create: pyproject.toml 或 pytest.ini / tox.ini（择一）
Optionally modify: README.md

Expected outcome: 以下命令之一可直接工作：

python3 -m unittest discover -s tests -v

或

python3 -m pytest -q

Task 0.2：补 Python 运行入口说明

Objective: 把当前 Python 线的实际运行方式写清楚

Files:

Modify: README.md

Must include:

Python CLI 启动方式
PYTHONPATH/安装方式
validate-config / run / send
file source 与 modemmanager source 的示例配置

Task 0.3：明确仓库主线状态说明

Objective: 在 README 顶部写明当前仓库是 C# 历史主线 + Python Debian 重构线并存

Files:

Modify: README.md

Must include:

当前推荐继续投入的是 Python Debian-first 线
C# 线主要用于兼容参考，不宣称已完成 Web 化

阶段 1：补最小 Debian Web API（最高业务优先级）

Task 1.1：新增 Web 服务入口模块

Objective: 在 Python 线增加最小 HTTP 服务，而不破坏 CLI

Files:

Create: src/dbussmsforward/web.py
Modify: src/dbussmsforward/cli.py
Modify: src/dbussmsforward/config.py

API baseline:

GET /api/health
GET /api/system/status
GET /api/settings
POST /api/settings
POST /api/sms/send

Task 1.2：补 Web 层测试

Files:

Create: tests/test_web.py

Validation:

健康检查返回 200
设置读取/写入生效
send API 能触发 dispatcher
错误配置返回结构化 4xx

Task 1.3：定义配置文件持久化位置

Objective: 对齐 Debian 运行约定

Files:

Modify: src/dbussmsforward/cli.py
Modify: src/dbussmsforward/web.py
Create: appsettings.example.json

Recommended path order:

--config
DBUSSMSFORWARD_CONFIG_PATH
/etc/dbussmsforward/appsettings.json
项目内默认示例路径

阶段 2：补最小前端管理页（次高优先级）

Task 2.1：加纯静态前端

Files:

Create: wwwroot/index.html
Create: wwwroot/app.js
Create: wwwroot/app.css

UI minimum scope:

当前运行状态
当前配置查看
基础配置编辑保存
手工发送短信/测试通知

Task 2.2：把前端挂到 Web 服务

Files:

Modify: src/dbussmsforward/web.py

Validation:

浏览器可直接打开管理页
前端能调用 settings / status / send

阶段 3：补 Debian 部署闭环

Task 3.1：新增 systemd service 文件

Files:

Create: deploy/dbussmsforward.service

Must include:

Environment=DBUSSMSFORWARD_CONFIG_PATH=/etc/dbussmsforward/appsettings.json
WorkingDirectory=/opt/dbussmsforward
ExecStart= 指向 Python 启动方式或打包后的启动方式
Restart=always

Task 3.2：新增 Debian 部署说明

Files:

Modify: README.md
Optionally create: docs/debian-deploy.md

Must include:

依赖安装
目录布局
配置文件位置
systemd 安装与启动
日志查看方式
升级步骤

Task 3.3：明确“不在 Debian 目标机编译”的交付方式

推荐选项二选一：

Python wheel / source bundle + venv 安装
打包好的独立运行目录（含依赖）

建议优先： Python venv + requirements/pip install 方案，先求稳。

阶段 4：补运维与可观察性

Task 4.1：统一日志输出格式

Files:

Modify: src/dbussmsforward/cli.py
Modify: src/dbussmsforward/app.py
Modify: src/dbussmsforward/web.py

Need:

标准 INFO/WARN/ERROR
sender failure / fetch issue 结构化输出
Web API 错误统一 JSON

Task 4.2：补状态页指标

API suggested:

最近一次 poll 时间
最近 dispatch failures 数量
最近 fetch issues
启用的通知渠道
当前 source kind

Task 4.3：补消息历史持久化（可选）

这项不是第一阶段必须，但如果要做 Web 查看“最近短信”，就需要：

SQLite 或轻量 JSONL 存储
最近 N 条消息与失败记录查询

建议放到 Web API 稳定之后再做。

九、推荐执行顺序（最务实版本）

最小 4 步路线

统一测试入口 + README 重写
补 Python Web API 最小闭环
补静态前端最小页面
补 systemd + Debian 部署说明

这样完成后，项目才能第一次比较诚实地对外说：

已具备 Debian-first 的可运行 Web 管理版本雏形。

十、风险与注意事项

风险 1：双轨并存会继续制造误判

如果不尽快在 README 和目录说明里明确：

哪条线是当前主线
哪条线只是历史参考

后续任何人都可能再次把方向带偏。

风险 2：测试入口不统一会导致“看起来坏了”

目前 unittest discover 直接跑会误报导入失败，这会让人误以为 Python 重构质量不稳定。

风险 3：如果先补太多高级功能，会拖慢最小交付

比如：

历史消息数据库
权限系统
多用户管理
完整前端框架重构

这些都不该排在 Debian 最小可交付之前。

十一、最终建议

不建议的动作

继续把目标描述为 OpenWRT 部署
先做复杂前端重构
先追求完整数据库历史功能
继续把 C# Worker 当成当前 Web 主交付线

十二、执行准备说明

如果下一步进入实现，建议采用以下节奏：

先修测试入口与 README
再加 web.py 和 tests/test_web.py
API 稳定后再加 wwwroot/
最后补 deploy/dbussmsforward.service

这样每一步都可验证，也不会再跑偏。

14 KiB Raw Permalink Blame History Unescape Escape

DbusSmsForward Debian 重构状态报告与下一步落地清单

一、结论摘要

1. 当前方向应明确为 Debian-first

2. 当前重构不是没进展，但也还没到 Debian Web 成品

3. C# 主线仍存在，但并非当前可直接交付的 Debian Web 版本

二、实际检查到的仓库状态

目录结构观察

粗略文件数量

三、Python 重构线：已完成内容

1. 配置模型已成型

2. 短信源抽象已成型

3. 通知分发核心已成型

4. CLI 基本闭环已经存在

四、Python 重构线：验证状态

1. CLI 测试

2. 运行时流程测试

3. 配置模型测试

4. 关于“全量测试”口径的注意事项

五、C# 主线：当前真实状态

1. 仍是 Worker，不是 Web 项目

2. 有 Debian 友好的配置痕迹

3. Program.cs 依赖的若干类当前未直接看到实现文件

4. README 仍是旧交付叙事

六、当前最准确的项目分层判断

已完成层

半完成层

明显未完成层

七、建议的方向收敛

建议主路线

C# 线建议定位

八、下一步落地清单（按优先级排序）

阶段 0：先把工程入口和叙事统一（高优先级，半天内可做）

Task 0.1：补统一测试入口

Task 0.2：补 Python 运行入口说明

Task 0.3：明确仓库主线状态说明

阶段 1：补最小 Debian Web API（最高业务优先级）

Task 1.1：新增 Web 服务入口模块

Task 1.2：补 Web 层测试

Task 1.3：定义配置文件持久化位置

阶段 2：补最小前端管理页（次高优先级）

Task 2.1：加纯静态前端

Task 2.2：把前端挂到 Web 服务

阶段 3：补 Debian 部署闭环

Task 3.1：新增 systemd service 文件

Task 3.2：新增 Debian 部署说明

Task 3.3：明确“不在 Debian 目标机编译”的交付方式

阶段 4：补运维与可观察性

Task 4.1：统一日志输出格式

Task 4.2：补状态页指标

Task 4.3：补消息历史持久化（可选）

九、推荐执行顺序（最务实版本）

最小 4 步路线

十、风险与注意事项

风险 1：双轨并存会继续制造误判

风险 2：测试入口不统一会导致“看起来坏了”

风险 3：如果先补太多高级功能，会拖慢最小交付

十一、最终建议

推荐的下一动作

不建议的动作

十二、执行准备说明

14 KiB

Raw Permalink Blame History