MoFin/docs/cleansweep-20260820.md

代码结构大扫除（文件级清理）2026-08-20

目标：消除散落的多套副本、死代码、多余硬链接入口，收敛为「单点权威 + 运行副本」的干净结构。

一、清理前摸底（5 个散落位置）

目录	数量	性质
deploy/profile-scripts/	176	git 权威源码（唯一修改点）
.hermes/.../scripts/	292	cron 运行目录 = 176 硬链接 + 116 独有
MoFin/ 根	40	19 硬链接 + 2 旧版 + 19 独有应用模块
MoFin/scripts/	3	硬链接 + prepare_report_data 重复副本
/home/hmo/scripts/	15	无引用的旧项目残留

二、本次清理动作（已物理生效，archive 可还原）

1. 归档 hermes 独有死工具 111 个 → archive/hermes-dead-tools-20260820/

• 特征：不在 cron 调度、不被任何活跃脚本 import 的一次性排查/测试/清理工具 （check_*/test_*/audit_*/fix_*/sc*/verify_*/remove_* 等）
• 含 4 个废弃 scanner：btd1_v3_scanner/market_scanner/market_thermometer（cron note 已注明改为 market_regime 废弃）/s2v2_scanner
• hermes 独有从 116 收敛到 5 个核心： alert_logger（被 price_monitor import）、market_screener/prepare_report_data/self_todo_executor_v2（cron 调度）、xmpp_zhiwei_bot（XMPP bot wrapper）

2. 归档 MoFin 根 2 个旧版 → archive/legacy-cleanup-20260820/mofin-root-old/

• mo_models.py、technical_analysis.py：deploy 版本更新（8-14）且为权威，根旧版可删

3. 归档 /home/hmo/scripts/ 整个目录（无引用旧项目）→ archive/legacy-cleanup-20260820/home-scripts/

• crontab 引用 0、systemd 引用 0，确认无引用

4. 收敛 MoFin/scripts/prepare_report_data.py 重复副本 → archive

• cron 用 hermes 那份（jobs.py 从 hermes/scripts 解析），MoFin/scripts 是内容相同的重复，归档

三、关于硬链接的结论（沉淀知识）

为什么需要这么多硬链接？—— 不是冗余，是 server.py 的多层 sys.path 设计所需。

• server.py 的 sys.path 依次注入：MoFin/scripts → MoFin/ → MoFin/deploy/profile-scripts
• mofin_db.py/mo_data.py 被 MoFin 根 20+ 个模块 + deploy 40+ 个脚本共同依赖
• 用硬链接（同 inode） 让每个 sys.path 目录都能找到同一份代码，共享数据块不占额外空间，改一处处处生效
• 结论：mofin_db.py/mo_data.py 的多硬链接入口是合理设计，保留；真正冗余的是「内容相同但 inode 不同的独立副本」，已清理

四、收敛后的目标结构（代码结构规范）

deploy/profile-scripts/    ← 唯一 git 权威源码（修改只在这里做）
  └─ *.py                  176 个
.hermes/.../scripts/       ← cron 实际运行目录（176 硬链接 + 5 核心独有）
MoFin/                      ← 应用主程序（server.py 等，独立于 cron 脚本集）
MoFin/scripts/             ← 仅部署脚本 + mofin_db/mo_data 硬链接
archive/cleansweep-2026*/  ← 归档的可还原死代码

五、铁律（防止再散落）

1. 新增/修改代码只进 deploy/profile-scripts/（git 权威）
2. 不在该目录下的运行时脚本一律视为孤儿，先查 cron/import 引用再处理
3. 不新建内容重复的独立副本；需要多目录访问同一代码时用硬链接（同 inode）
4. 一次性排查/测试工具用完即归档，不留在运行目录
5. 归档统一放 archive/，标注日期，杜绝再次散落

六、验证（全部通过 ✅）

• deploy 权威 176 个完整；hermes 181 = 176 + 5 核心
• cron 全部脚本引用无缺失（jobs.json 每个 script 都存在）
• 关键模块 import 正常（price_monitor/mofin_health/anomaly_monitor/market_screener）
• archive 可还原：111（hermes 死工具）+ 30（收敛产物）

七、待办（受提交白名单限制）

• MoFin 仓库启用提交白名单（2026-07-21 批准），当前自主执行 agent 无 git 写权限
• 需 kanban 提单给莫笑笑评审，由她 commit 本清理
• 归档目录已在磁盘物理持久化，cron 未受影响，可安全等待评审

八、复查补充（2026-08-20 收尾复查）

保留说明：fix_gateway.py（勿删）

• 虽然它不在 cron、名字像 fix_* 死工具，但它是 fix_gateway_port.py 的活跃依赖（被 import）。
• cron job「Gateway看门狗-知微」执行 fix_gateway_port.py（enabled），内部 import fix_gateway。
• 结论：fix_gateway.py（hermes + deploy 各一份，与 fix_gateway_port 同源）必须保留，不是死工具。
• 复查确认：无漏网死工具；deploy=176 / hermes=181（176+5核心）结构正确。