VPSMaster/DEVELOPMENT_BRIEF.zh.md

历史记录 / Historical record：ProxyDoctor 是项目旧名。以下旧版本、SHA256、测试数量与路径保留原样，不代表 VPSMaster 新构建已通过；当前范围见 README.md、CURRENT_STATUS.md 和新包同 SHA256 验收报告。

VPS 综合检测工具——完整开发与工程优化任务书

0. 项目背景与最终目标

我正在独立开发一个基于 Python 的开源 VPS 综合检测工具，主要面向中文 VPS 社区及 Linux 初学者。

当前已有初步完成的功能：

• Linux 发行版、内核、CPU、内存、磁盘等基础信息检测。
• Traceroute 路由跟踪及终端显示。
• 现有代码已在 Ubuntu 22.04 Server 和 Ubuntu 24.04 Desktop 虚拟机环境中进行过测试。

以上完成情况是我的阶段性描述，请通过实际代码和测试重新核实，不能仅凭我的描述认定全部测试通过。

本项目的目标不是简单复制其他 VPS 检测脚本，而是开发一个：

自主实现为主、安全透明、功能完整、结果准确、适合小白、可长期维护，并能被未来 FlexMaster 项目调用的 VPS 综合诊断工具。

项目现阶段只开发 Python CLI 检测工具，不开发代理部署功能和 Web UI。

未来 FlexMaster 将复用本项目的检测核心，但二者作为独立项目维护。

---

1. 开发原则（最高优先级）

1. 自主实现优先。 能够通过 Python 标准库或成熟 Python 依赖完成的功能，优先自主编写。
2. 保留已有成果。 不推倒重来，不重复开发已经稳定实现的本机检测与 Traceroute。
3. 避免重复造轮子。 对磁盘基准、专业网络吞吐和高级路由诊断，可调用 fio、iperf3、mtr 等成熟工具。
4. 合法利用外部资源。 对地理位置、ASN、IP 风险、信誉信息等本机无法独立获取的数据，可使用合法的第三方 API 或数据库。
5. 源码借鉴必须合法。 先检查 LICENSE、版权声明及第三方依赖许可，不未经确认直接复制 GPL/AGPL 项目的实现代码。
6. 检测结果必须真实。 不伪造延迟、丢包、IP 纯净度、流媒体解锁状态或测速结果。
7. 默认安全。 普通检测只读；性能、磁盘写入、持续测速及较大流量测试必须明确提示并取得用户确认。
8. 单模块故障隔离。 外部 API、网络、权限或依赖出错时，不能导致整个程序崩溃。
9. 结构化优先。 检测逻辑、数据模型、CLI 输出、报告导出相互解耦。
10. 面向小白。 最终实现一条命令启动，中文输出清楚，提供英文选项，并解释结果含义。
11. 以证据判定完成。 每个任务必须有对应实现、测试记录及验收说明。
12. 不得擅自执行高风险动作。 不自动修改 SSH、防火墙、路由、DNS、系统网络配置，不部署代理，不向外上传完整报告。

---

2. 需要解决的全部功能问题

请对以下十一类功能进行逐项审查、设计、实现及测试。

要求建立完整的问题追踪表，记录每项的状态：

• 已实现且通过测试
• 已实现但有缺陷
• 部分实现
• 尚未实现
• 外部条件不足，待实机验证
• 不适用，并说明原因

第一类：VPS 本机与硬件检测

• 准确识别 Linux 发行版、内核、CPU 架构及虚拟化类型。
• 识别 CPU 型号、核心数、频率及实际资源配额。
• 检测内存、Swap、磁盘容量与资源限制。
• 检测 CPU steal、内存压力、资源争用。
• 实现可重复、可比较的 CPU 性能基准。
• 检测磁盘吞吐、IOPS、读写延迟，严格限制磁盘写入和占用。
• 支持用户输入购买规格，并对比实际可见配置；无法核实时明确说明。

第二类：基础网络与 DNS

• 检测公网 IPv4、IPv6、默认路由和网络接口。
• 分别验证 IPv4/IPv6 外网连通性。
• 测量 DNS 解析时间、成功率和错误类型。
• 区分 DNS、网络路径及目标服务故障。
• 测试 TCP 连接、TLS 握手与 UDP 连通性。
• 检查 MTU/PMTU、双栈异常与 IPv6 连接问题。
• 正确处理 NAT、容器、多网卡环境，避免误判公网出口。

第三类：Traceroute、BGP 与线路分析

• 保留现有 Traceroute 核心代码并完善。
• 支持可行的 ICMP、UDP、TCP 探测方式。
• 显示逐跳 IP、RTT、超时及具有明确统计依据的丢包数据。
• 查询逐跳 ASN、运营商、推测地区。
• 避免将不响应的路由器错误判断为线路故障。
• 避免将单个中间节点的高延迟直接认定为拥堵。
• 检测中国电信、联通、移动相关线路特征。
• 支持 BGP、上游网络与 ASN 信息分析。
• 明确区分 VPS → 中国与中国 → VPS 的测试方向。
• 地理位置只显示推测结果，不声称是真实物理线路。
• 无中国侧测试节点时，不伪造中国到 VPS 的去程检测。

第四类：IP 地理位置、纯净度与信誉

• 查询国家、地区、城市、ASN、运营商。
• 识别住宅、机房、移动网络等 IP 分类。
• 查询代理、VPN、Tor 及相关风险标签。
• 支持多个数据源交叉验证与冲突提示。
• 查询公开黑名单、DNSBL、邮件信誉。
• 检测 PTR 等 DNS 邮件相关信息。
• 不使用缺乏依据的绝对“纯净度分数”。
• 处理 API 限速、失效、付费要求和服务条款。
• 每条结果记录来源、查询时间、可信度及限制。

第五类：流媒体与在线服务可用性

• 检测 Netflix、Disney+、YouTube 等服务。
• 检测 ChatGPT 等在线服务的网络与地区可用性。
• 区分网络可达、地区识别、受限、需要登录、无法确认及实际播放成功。
• 检测 DNS、TLS、HTTP 错误及服务端限制。
• 禁止将 HTTP 200 直接判定为成功解锁。
• 处理网站检测规则变化、反爬限制和误报。
• 明确声明账号权限、订阅资格和实际播放能力可能无法自动验证。
• 支持用户自定义合法检测目标。
• 不尝试绕过账号验证、反爬或访问限制。

第六类：多地区测速与长期稳定性

• 研究可信的全球及中国不同运营商测试节点。
• 测量延迟、抖动、丢包、下载和上传速率。
• 严格区分测试方向、节点地理位置与节点运营商。
• 限制带宽、并发、执行时间及流量消耗。
• 识别测试节点瓶颈，避免假性低速。
• 支持可中断的 24/48 小时低负载监测。
• 分析晚高峰性能劣化、间歇性断线、突发丢包。
• 关联 CPU steal、内存压力及网络质量的时间变化。
• 中断监测时安全退出并保留已有数据。

第七类：基础安全体检

• 只读检查 SSH 配置和潜在高风险认证方式。
• 检查监听端口及可能暴露的服务。
• 识别系统防火墙状态，说明云安全组无法从本机完整确认。
• 检查系统更新状态及基础安全设置。
• 检测重要文件权限风险。
• 避免把正常业务配置直接定义为漏洞。
• 提供有依据的修复建议，但不自动执行。
• 避免泄露密码、Token、私钥及其他敏感信息。

第八类：报告、诊断与历史记录

• 设计统一的结构化检测结果 Schema。
• 区分成功、失败、跳过、不支持和无法判断。
• 保存检测时间、方法、来源、错误与置信度说明。
• 将技术指标转换成普通用户能理解的中文解释。
• 提供基于规则和真实测量结果的诊断建议。
• 支持本地 JSON、Markdown 报告，必要时提供 HTML。
• 对分享用报告进行脱敏。
• 上传失败、断网或意外退出时不丢失已有报告。
• 支持历史记录及不同时间、不同服务器的对比。
• 生成 VPS 购买验收报告，区分实际测量与用户提供的购买规格。
• 不生成未经校准的绝对性能评分。

第九类：安装、兼容性与用户体验

• 实现面向小白的一键安装与运行。
• 检查 Python 版本、依赖及权限。
• 使用虚拟环境隔离依赖，不污染系统 Python。
• 优先兼容 Ubuntu 22.04 Server、24.04 Desktop。
• 评估其他发行版、容器、ARM/x86 架构兼容性。
• 提供中文和英文输出，处理终端编码问题。
• 尽可能支持非 root 检测。
• 缺少依赖时友好提示、降级或跳过。
• 提供帮助、参数说明、更新、卸载和离线说明。
• 安装脚本可审查，采用可信来源及版本固定/完整性验证。
• 不要求用户盲目执行来源不明的 curl | bash。

第十类：可靠性、隐私与自动化测试

• 验证默认检测确实不修改系统配置。
• 区分普通检测与高负载、有写入的基准测试。
• 对运行时间、CPU、磁盘、流量设置安全上限。
• 处理超时、网络失败、权限错误和依赖缺失。
• 保证模块故障隔离。
• 处理 Ctrl+C、安全取消与临时文件清理。
• 防止命令注入、路径问题、终端控制字符污染和敏感日志泄露。
• 使用 Mock、单元测试、集成测试和异常场景测试。
• 在两种 Ubuntu 虚拟机及真实 VPS 上验证。
• 建立安全的社区错误反馈方式。
• 检查第三方许可证、依赖安全和 API 使用条款。

第十一类：开源维护与未来 FlexMaster 集成

• 每个检测模块既能由 CLI 使用，也能通过 Python API 调用。
• 检测核心与终端 UI 解耦。
• 为未来 FlexMaster 设计稳定、可复用的接口。
• 完善 README、安装说明、贡献指南及测试文档。
• 提供标准 GitHub Issue 模板和脱敏日志机制。
• 明确支持系统、已知问题和未验证环境。
• 建立外部贡献代码审查与自动化测试规范。
• 为开源发布准备合适的 LICENSE、依赖声明及第三方版权通知。

---

3. 参考成熟项目，但不能直接拼接它们

请实际阅读以下 GitHub 仓库的相关源码、目录结构、检测逻辑和许可证文件：

1. YABS
   https://github.com/masonr/yet-another-bench-script

2. Backtrace
   https://github.com/oneclickvirt/backtrace

3. 融合怪 ECS
   https://github.com/oneclickvirt/ecs

4. NodeQuality
   https://github.com/LloydAsp/NodeQuality

5. OneClickVirt
   https://github.com/oneclickvirt/oneclickvirt

重点研究：

• YABS：fio、iperf3、基准流程及结构化结果。
• Backtrace：三网回程、ASN、线路识别。
• 融合怪：多模块综合检测与功能覆盖。
• NodeQuality：环境隔离、报告组织、异常恢复。
• OneClickVirt：自动化工程组织及兼容性测试。

必须实际检查相关源码，不仅阅读 README。

每项借鉴方案要说明：

• 项目与源码链接
• 具体文件、函数或调用入口
• 采用何种实现方式
• 采用原因
• 许可证及版权义务
• 可能涉及的 API 条款或费用
• 安全风险及兼容性问题

如果可以自主开发，请优先自主实现。确需借助已有项目时，优先选择通过公开接口、系统命令或兼容许可证的独立依赖实现。

不要未经授权复制 GPL/AGPL 代码；不要认为调用外部程序就自动豁免全部许可证义务。必要时明确标记为待确认。

---

4. 与现有竞品的竞争策略

请参考融合怪和 NodeQuality 的功能覆盖，但不要只追求更多测试项目。

我们的重点竞争优势为：

A. Safe by Default

• 只读优先
• 低负载模式
• 资源限制
• 错误隔离
• 数据本地优先
• 不修改 SSH、防火墙及网络配置

B. Explain, Not Just Measure

• 用中文说明检测结果
• 提供数据来源和可信度
• 解释风险与异常
• 给出明确的下一步排查建议
• 不编造检测结论

C. Compare Over Time

• 本地检测历史
• 24/48 小时稳定性监测
• 晚高峰异常分析
• 多 VPS 比较
• 购买验收报告

请在竞品研究中区分：

1. 竞争项目已经实现的能力。
2. 竞争项目部分实现或存在局限的能力。
3. 我们能够通过实际工程实现证明的优势。

不允许仅凭宣传描述声称优于竞争项目。

---

5. 技术架构与实现要求

保持 Python 为核心技术栈。

推荐采用以下逻辑分层，可以根据现有代码合理调整：

• Core：模块调度、配置、数据模型、异常处理。
• Checks：系统、网络、路由、IP、流媒体、安全等检测。
• Benchmarks：CPU、磁盘和吞吐性能基准。
• Providers：外部 API、数据库、测速节点接口。
• Diagnostics：解释规则和异常诊断。
• Reports：JSON、Markdown、HTML、脱敏和历史比较。
• CLI：终端交互、语言切换和进度展示。
• Tests：Mock、单元、集成与回归测试。

要求：

• 模块可以独立运行。
• 外部依赖允许替换。
• 接口返回结构化对象，不依赖解析 CLI 文字。
• 所有网络请求具有明确超时。
• 默认测试不要求 root。
• 高风险或高负载操作使用显式确认机制。
• 使用固定版本或受控版本范围管理依赖。
• 提供稳定的数据格式与错误编码。
• 保持未来与 FlexMaster 的接口兼容性。

---

6. Work 的执行流程

第一步：代码审查与现状确认

先查看我现有项目代码、Git 状态、测试、依赖和目录。

识别哪些功能已经存在、哪些功能不稳定、哪些功能尚未开发。

不得覆盖已有成果。

第二步：建立问题追踪表

把上面十一类需求全部登记。

为每一项标注：

• 编号及问题描述
• 当前代码位置
• 实际完成状态
• 建议实现方法
• 所需依赖/API
• 测试方法
• 风险及限制
• 完成证据

不要单纯因为某个功能名称出现在代码里就标记完成。

第三步：技术方案与开源研究

针对未实现或不可靠的功能，先比较自主实现、Python 依赖、系统工具及第三方 API 方案。

涉及 GPL/AGPL 代码复制、付费 API、上传用户数据或改变原有架构的重大决定时，先征求我确认。

第四步：逐模块开发

完成代码实现、测试、必要文档和错误处理。

优先复用现有组件，避免一次性进行无关的大规模重构。

第五步：测试与验证

在有权限的隔离测试环境中执行安全测试。

对于 Ubuntu 22.04 Server、24.04 Desktop，以及真实 VPS 的测试，分别记录结果。

没有真实 VPS 环境时，通过 Mock 和有限的本地测试推进，但必须注明尚未实机验证。

禁止擅自在生产 VPS 上运行高负载测试。

第六步：汇总与交付

输出真实完成情况和未解决问题。

不要为了交付而将模拟、跳过或不确定的检测伪装为通过。

---

7. 需要创建和维护的项目文件

建议在仓库中维护：

• PROBLEM_BACKLOG.md：全部问题及实际状态
• ARCHITECTURE.md：模块架构与数据接口
• OPEN_SOURCE_RESEARCH.md：开源项目源码研究与许可证分析
• TEST_PLAN.md：测试场景及验收标准
• SECURITY.md：安全边界、隐私和漏洞报告
• CHANGELOG.md：已经完成的实际更新
• README.md：面向用户的使用说明

如果文件已存在，应审查并更新，不要无故覆盖。

---

8. 最终验收标准

我希望最终获得的不是只有功能菜单的半成品，而是实际可运行、可信的工具。

验收时需要证明：

1. 十一类问题都有明确状态及依据。
2. 声称完成的功能具有相应测试证据。
3. 常规扫描不会擅自更改服务器网络和安全配置。
4. 基准和大流量测试有明确授权及资源限制。
5. 一个模块失败不影响其他模块运行。
6. 结果可在终端查看、导出并安全保存。
7. 第三方数据具有来源和不确定性说明。
8. 用户能够理解检测结果及异常原因。
9. 项目能够通过合理的安装流程运行。
10. 代码模块可被未来 FlexMaster 独立调用。
11. 开源借鉴内容具备合法的版权和许可证处理方案。
12. 未验证的功能不得宣传为已经完成。

9. 本次工作授权边界

请先完成现有代码审查、问题登记、开源源码研究及架构分析。

完成这些后，在隔离分支中逐模块推进低风险开发和自动化测试，保留原有代码及 Git 历史。

未经我进一步确认，不要执行生产 VPS 测试、安装系统级依赖、修改防火墙/SSH、使用付费 API、上传检测数据、合并主分支或公开发布。

每完成一组实质性工作，请向我汇报：

• 实际完成了什么
• 修改了哪些文件
• 测试通过了哪些项目
• 哪些仍然存在问题
• 下一步建议

最终目标：建立一个具有独立代码价值、可信检测结果、安全工程设计，并能持续维护的 Python VPS 综合诊断工具。