project-structure-optimization-tasks.md 151 KB

Raw Blame History Permalink



BettaFish 项目结构优化任务文档

版本：v4.19

状态：Active

更新时间：2026-04-09

关联文档：


项目结构分析与优化方案
项目结构优化记忆文件
根目录兼容壳清单


1. 目标

本任务文档用于把《BettaFish 项目结构分析与优化方案》转成可执行、可追踪、可持续更新的任务清单。

本轮优化的核心目标是：


重新建立一级目录边界，区分前端、后端、引擎、爬虫、工具、基础设施和运行时数据。
降低根目录噪音，剥离构建产物、本地依赖和运行期数据。
收敛平台装配层，逐步将 app.py 的超级入口职责迁移到清晰的应用层结构。
为后续持续重构建立统一任务基线和进度记录方式。


2. 更新规则

从本文件建立开始，后续每次执行结构优化相关任务后，都必须同步更新以下两份文档：


docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


每次更新至少要补充：


本次完成了什么任务。
任务状态从什么变成了什么。
影响了哪些目录或文件。
做了哪些关键决策。
做了哪些验证。
下一步建议执行哪个任务。


3. 状态定义


todo：尚未开始

in_progress：正在进行

blocked：被依赖或风险阻塞

done：已完成并已记录验证结果

deferred：暂缓处理，后续再排期


4. 执行约束


保持单仓库、单部署单元，不在本轮结构优化中拆微服务。
继续保留三引擎工作台和最终报告主链路。
继续以纯本地为默认运行和验证入口，Docker 仅保留兼容入口。
优先做“目录和装配层收口”，不在同一批任务里大规模重写业务逻辑。
涉及外部子模块 MediaCrawler 时，优先做隔离和适配，不直接深改上游结构。


5. 当前基线

当前已知基线如下：


已完成结构诊断，并生成 项目结构分析与优化方案。
当前仓库存在新旧架构并存、根目录职责过重、配置分裂、脚本散落、运行目录混入源码区等问题。
已完成 T-101 ~ T-103，运行时目录已开始从根目录收口到 var/。
已完成 T-201 ~ T-205，应用层目录迁移与旧入口兼容层已经形成闭环。
已完成 T-105，根目录 .codex-tmp-* 临时目录与压缩包已被实际删除，最低风险临时残留已完成首次物理清场。
已完成 T-301，服务层引擎骨架已建立。
已完成 T-303，共享服务层骨架已建立。
已完成 T-304，共享配置入口与环境模型已统一到服务层公共配置基础设施。
已完成 T-401，爬虫服务层骨架已建立。
已完成 T-501，首批报告类脚本已收口到 tools/reports/，根目录旧脚本降级为 wrapper。
已完成 T-502，infra/docker/ 已成为 Docker / compose canonical 入口。
已完成 T-402，MindSpider 主爬虫真实代码已迁入 services/crawler/mindspider/，根目录 MindSpider/ 降级为兼容壳。
已完成 T-403，MediaCrawler 已迁入 vendor/mediacrawler/，.gitmodules、Docker / compose 与运行时路径解析已切到 vendor canonical 路径。
已完成 T-404，services/crawler/adapters/mediacrawler_adapter.py 已成为外部爬虫访问的统一适配入口，backend/crawler/ 与 MindSpider 主流程已切到适配层。
已完成 T-405，backend/crawler/ 已成为爬虫 Web 控制的 canonical 导出面，根目录 crawler_web.py 已收口为最薄兼容 shim。
已完成 T-406，根目录 MindSpider/ 的 CLI/README/目录树说明已继续收口到 canonical 路径，主 README 与爬虫 README 已明确新旧入口边界。
已完成 T-407，MindSpider/config.py.example 与 MindSpider/requirements.txt 已补齐为可用的兼容入口说明，根目录 MindSpider/ 兼容文件边界更清晰。
已完成 T-601，SentimentAnalysisModel/ 已确认更适合作为研究/训练资产集合保留，后续应通过 T-602 迁入 research/，而不是继续留在根目录主应用结构中。
已完成 T-602，情感分析研究资产已迁入 research/sentiment_models/，根目录 SentimentAnalysisModel/ 已收口为仅保留 WeiboMultilingualSentiment/ 的兼容/运行时缓存目录。
已完成 T-603，Insight 多语言情感模型运行时路径已改为通过 INSIGHT_SENTIMENT_MODEL_DIR 配置解析，默认仍指向根目录 SentimentAnalysisModel/WeiboMultilingualSentiment 兼容路径。
已完成 T-604，Insight 多语言情感模型默认缓存目录已迁入 var/models/insight_weibo_multilingual，根目录旧路径降级为示例/兼容用途。
已完成 T-605，多语言情感分析研究示例已迁入 research/sentiment_models/WeiboMultilingualSentiment/，根目录旧位置已降级为转发到 canonical 示例的兼容 wrapper。
已完成 T-503，主仓库测试已收口为 tests/unit、tests/integration、tests/e2e 三层结构，原先散落在业务目录中的测试文件已迁回统一测试目录。
已完成 T-504，基础质量守门已接入 .github/workflows/quality_ci.yml，主仓库已具备 Python lint / test 与前端 type-check 的最小自动化链路。
已完成 T-505，vendor/mediacrawler 已补齐独立 workflow 与执行脚本，第三方 smoke tests 不再需要混入主仓库默认守门入口。


6. 任务总览


Phase 0：文档与基线


ID
任务
状态
依赖
交付物
验证标准


T-000
完成结构诊断与目标方案文档
done
无
docs/project-structure-optimization-plan.md
输出问题分析、目标结构和阶段路线


T-001
建立结构优化任务文档与记忆文件
done
T-000
本任务文档 + memory 文档
后续可按任务推进并持续更新


Phase 1：运行时目录隔离与仓库清场


ID
任务
状态
依赖
交付物
验证标准


T-101
建立统一运行目录方案 var/

done
T-001

var/ 目录骨架
日志、报告、浏览器数据、数据库卷、输出目录有统一归属


T-102
收口 .gitignore 与 .dockerignore

done
T-101
ignore 规则更新

node_modules、构建产物、临时目录、运行目录不再污染源码树


T-103
调整 Docker volume 与运行路径
done
T-101
compose / Dockerfile 路径更新
容器仍能正常读写日志、报告和浏览器数据


T-104
清理根目录临时与兼容残留清单
done
T-102
docs/project-structure-root-cleanup-inventory.md
根目录残留已完成分类，后续删除/迁移顺序明确


T-105
删除根目录 .codex-tmp-* 临时残留
done
T-104
已清理的临时目录与压缩包
可立即删除的 codex 临时残留不再停留在根目录


T-106
迁移轻量旧运行目录到 var/ 并删除根目录目录
done
T-104,T-105
已迁移的运行数据、路径默认值收口与文档同步

logs/、final_reports/、*_streamlit_reports/、output/ 的内容迁入 var/，根目录旧目录被删除且默认运行路径不再依赖旧位置


T-107
评估 crawler_browser_data/ 与 db_data/ 冷迁移方案
done
T-106
高风险目录盘点结果、迁移约束与执行步骤
已确认目录现状、compose 挂载边界、体量与停机前置条件，形成 T-108 执行基线


T-108
执行高风险旧运行目录冷迁移或归档
done
T-107

crawler_browser_data/ / db_data/ 迁移或备份结果
在停进程/停容器窗口下完成迁移、容器重建验证与根目录旧目录删除


T-109
清理仓库无用缓存与编译残留
done
T-108
缓存清理结果与更新后的清单文档

__pycache__/、.pytest_cache/ 等明确无用缓存不再留在仓库


T-110
评估并收缩剩余根目录兼容壳
done
T-108,T-109
兼容壳清单、共享 shim helper 与补充测试
已明确 thin shim / 目录级兼容壳边界，根目录兼容包已统一为更轻的惰性实现


T-111
评估目录级兼容壳的最终冻结与删除边界
done
T-110
最终冻结/删除候选清单
已明确 MindSpider/、根目录 Docker / compose 副本、研究示例 wrapper 中的冻结保留项与删除候选


T-112
执行已确认低风险兼容文件的删除试点
done
T-111
删除结果与回归验证
在确认无外部依赖后，移除 Dockerfile.runtime-hotfix、MindSpider/config.py.example、MindSpider/requirements.txt 等低风险候选


T-113
评估运行时冷备份与空目录的保留窗口
done
T-108,T-112
冷备份保留策略与空目录分类结果
明确 var/backups/runtime-migration/20260407/t108/ 与运行时空目录哪些必须保留、哪些可后续清理


T-114
制定并执行受控运行时空间回收方案
done
T-113
回收清单、执行前置条件与验证步骤
已在确认活跃主站与浏览器进程不使用仓内 scratch profile 后，完成 var/output/chrome-headless/ 受控清理与回收后体积复核


Phase 2：应用层重组


ID
任务
状态
依赖
交付物
验证标准


T-201
建立 apps/ 一级目录骨架
done
T-104

apps/ 目录骨架与说明文档
Web API、Web UI、引擎控制台有清晰位置


T-202
迁移前端到 apps/web_ui/

done
T-201
前端工程迁移

apps/web_ui 构建通过，静态产物仍输出到 static/frontend/


T-203
迁移 Web API 装配层到 apps/web_api/

done
T-201
Flask 装配层迁移

apps/web_api 成为真实装配入口，主站仍可通过兼容入口启动


T-204
迁移 SingleEngineApp/ 到 apps/engine_console/

done
T-201
单引擎入口迁移
三个引擎控制台入口已迁到 apps/engine_console/


T-205
为旧入口保留兼容 shim
done
T-202,T-203,T-204
兼容入口文件
根目录旧入口仍可工作，迁移阶段外部使用方式不中断


Phase 3：服务层重组


ID
任务
状态
依赖
交付物
验证标准


T-301
建立 services/engines/ 骨架
done
T-205
新服务目录骨架
五大引擎有统一层级


T-302
迁移五大引擎到 services/engines/*

done
T-301
引擎目录迁移
导入链路稳定，主要运行入口可用


T-303
建立 services/shared/ 公共层
done
T-301
共享层目录
config、llm、utils、logging 有统一落点


T-304
统一配置入口与环境模型
done
T-303
共享配置模块

.env 读写与运行时配置来源收口


T-305
为旧导入路径增加过渡兼容层
done
T-302,T-304
shim 文件或转发导入
迁移期减少大面积导入报错


Phase 4：爬虫与外部子项目隔离


ID
任务
状态
依赖
交付物
验证标准


T-401
建立 services/crawler/ 骨架
done
T-305
crawler 服务目录
主仓库爬虫侧目录有统一归属


T-402
迁移 MindSpider/ 到 services/crawler/mindspider/

done
T-401
主爬虫目录迁移
调用路径与运行入口仍可工作


T-403
隔离 MediaCrawler 为 vendor/mediacrawler/

done
T-401
vendor 目录结构
明确它是外部依赖而不是内部主模块


T-404
增加 mediacrawler_adapter 适配层
done
T-403
适配层模块
平台仅通过适配层调用外部爬虫能力


T-405
收口 crawler_web.py 兼容入口
done
T-404
API 装配整理
兼容层最小化或删除


T-406
收口 MindSpider/ 兼容壳说明与 CLI 指引
done
T-405
更新后的 MindSpider 兼容说明、canonical README 与主 README 树
根目录 MindSpider/ 明确为 wrapper，推荐入口统一切到 canonical 路径


T-407
收口 MindSpider/ 兼容文件入口
done
T-406
更新后的 config.py.example、requirements.txt 与兼容说明
旧安装/复制路径仍可用，但不会再误导为正式 canonical 文件


Phase 5：工具、基础设施与自动化


ID
任务
状态
依赖
交付物
验证标准


T-501
建立 tools/ 一级目录并迁移根脚本
done
T-305
工具目录
根目录报告脚本职责明显减少，旧入口降级为 wrapper


T-502
将 Docker 与 compose 文件迁移到 infra/docker/

done
T-103,T-501
基础设施目录
Docker 启动链路可用


T-503
建立统一测试目录分层
done
T-302,T-501

tests/unit、tests/integration、tests/e2e

测试组织结构清晰


T-504
增加基础自动化守门
done
T-503
CI 更新
至少具备 lint / type-check / test 基础链路


T-505
为 vendor/mediacrawler 增加隔离自动化守门
done
T-403,T-504
独立 workflow 与执行脚本
第三方 smoke tests 与主仓库默认守门解耦


T-506
建立纯本地优先启动链路
done
T-203,T-304,T-502
本地启动脚本、环境模板与 README 更新
纯本地启动默认切到 .env.local + python -m scripts.dev.start_local，Docker 降级为可选兼容方式


T-521
删除根目录 Docker / compose 兼容副本
done
T-506,T-520
根目录 Docker 兼容副本删除结果与 README / 清单同步更新
仓库根目录不再保留 Dockerfile 与 docker-compose*.yml，CI 与文档统一只指向 infra/docker/*


T-522
建立前后端分离的本地热更新链路
done
T-506,T-509,T-521

Vite HMR + Flask API 双进程启动链路、README 更新与本地验证记录
默认本地启动切换为 5173 前端热更新 + 5000 后端 API，--frontend-mode build 保留 Flask 静态托管兼容模式


T-523
调整默认前端开发端口到 9527
done
T-522
新的前端默认端口配置、启动脚本与文档同步更新
默认本地前端入口切换为 9527，Python / PowerShell / Vite 配置与 README、任务记忆文档一致


T-524
评估根目录 app.py 的长期保留必要性
done
T-205,T-521,T-523

app.py 兼容窗口评估结论、任务/记忆文档更新与根级兼容清单同步
确认仓内代码已不再依赖根目录 app.py，兼容价值仅剩旧命令与外部自动化缓冲，形成“可进入删除窗口”的明确结论


T-525
删除根目录 app.py 并收口旧命令说明
done
T-524

app.py 删除结果、中英文 README 与兼容清单同步更新、根级入口收尾记录
仓库根目录不再保留 Web API Python 入口，当前对外说明统一收口到 python -m apps.web_api 与 python -m scripts.dev.start_local


T-526
评估 apps/web_api/app.py 前端 build 托管的保留边界
done
T-522,T-525
评估结论、任务/记忆文档更新与后续收口建议
明确本地 Vite HMR + Flask API 与 Docker / 单服务部署下 static/frontend/ 托管链路的职责边界，并给出删除该逻辑前的前置条件


T-527
收口前端 build 托管的文档口径与冗余环境变量
done
T-526
README / 启动说明 / fallback 提示 / Web API 装配层收口更新
不再把 build 模式描述为本地开发主路径，并清理未被消费的 BETTAFISH_FRONTEND_MODE 等冗余信号


T-528
设计独立前端交付方案并为 API-only 后端收口做准备
done
T-526,T-527
交付方案评估、部署边界说明、前置条件与实施顺序文档
明确替代 static/frontend/ 托管的推荐路径，并列出后端 API-only 收口前置条件


T-529
收口前端运行时 URL 配置并去除端口硬编码
todo
T-528
URL 配置层、前端统一链接生成与最小兼容迁移
前端不再在页面代码中散落硬编码 /api 和 :8501/:8502/:8503 端口拼接


T-530
为独立前端交付建立代理层与容器拓扑
todo
T-528,T-529
前端静态服务镜像、代理配置与新的 compose 拓扑
前端可通过同源代理访问 API、Socket.IO 与引擎工作台，且后端无需再托管首页 HTML


Phase 6：研究资产与模型目录隔离


ID
任务
状态
依赖
交付物
验证标准


T-601
评估 SentimentAnalysisModel/ 的保留策略
done
T-302
评估结论
明确它是运行资产、研究资产还是候选外部仓库


T-602
将研究资产迁移到 research/

done
T-601

research/ 目录
主应用目录与研究资产解耦


T-603
收口 Insight 情感模型运行时路径配置
done
T-602
配置项、路径解析与单元测试
运行时路径不再硬编码，且默认行为保持兼容


T-604
将 Insight 默认模型缓存迁入 var/

done
T-603,T-101
新默认路径、var/ 骨架与兼容测试
默认运行时缓存不再占用根目录，旧路径仍可通过配置覆盖


T-605
收口 WeiboMultilingualSentiment 研究示例与根目录兼容壳
done
T-604

research/ 正式示例目录、根目录 wrapper 与说明文档
研究示例进入 canonical 目录，旧路径继续可用但不再承载正式内容


| T-507 | 修复纯本地启动的 Python 3.13 兼容问题并完成启动验证 | done | T-506 | 本地依赖补齐、导入冲突修复、PostgreSQL 驱动兼容调整与启动验证记录 | 在本机 Python 3.13 环境下完成纯本地依赖安装，修复 MindSpider 裸 config 导入污染，并确认 http://127.0.0.1:5000 返回 200 |
| T-508 | 固化纯本地启动 bootstrap 依赖基线 | done | T-507 | infra/python/requirements-local.txt、scripts/dev/bootstrap_local.py、README 启动说明更新与根依赖兼容性收口 | python -m pip install --dry-run -r infra/python/requirements-local.txt 通过，python -m scripts.dev.bootstrap_local --dry-run 通过，且 http://127.0.0.1:5000 与 /api/research/options 持续可用 |
| T-509 | 建立 Windows 一键启动脚本与本地 PostgreSQL 预检 | done | T-508 | scripts/dev/start_local_stack.ps1、start_local.bat、README 启动说明更新与本地端口预检收口 | start_local.bat 与 PowerShell 入口可用，主站可再次通过一键入口拉起并返回 200，且脚本会对 127.0.0.1:5432 未监听给出明确预警 |
| T-510 | 建立本地 PostgreSQL 准备脚本并接入纯本地工作流 | done | T-509 | scripts/dev/prepare_local_postgres.py、README/PowerShell 提示更新与数据库默认端口一致性修正 | python -m scripts.dev.prepare_local_postgres --help 通过，--check-only 在数据库未监听时给出明确失败原因，且 README/Windows 启动入口都能指向同一条 PostgreSQL 收口路径 |
| T-514 | 评估并隔离系统级 PostgreSQL 认证阻塞 | done | T-510,T-513 | 阻塞定位记录、pg_hba.conf 备份与恢复确认、认证修复边界结论 | 确认系统 PostgreSQL 安装正常但当前用户无法直接接管服务控制，且临时 pg_hba.conf 放宽方案已恢复原状 |
| T-515 | 建立项目自管 PostgreSQL 修复链路 | done | T-514 | scripts/dev/repair_local_postgres.py、var/db/postgres-local/、启动链路与 README 更新 | python -m scripts.dev.repair_local_postgres、python -m scripts.dev.prepare_local_postgres --check-only 通过，且 start_local_stack.ps1 可在修复后重新拉起主站并返回 200 |
| T-520 | 删除低价值根级兼容 shim | done | T-519 | config.py、crawler_web.py、openai_compat.py 删除，README / 兼容清单 / 配置文档同步更新 | 仓库内导入全面切回 services.shared.config、backend.crawler、utils.openai_compat，根目录仅保留少量高价值入口 |


7. 近期执行顺序

更新：


纯本地主站入口已于 2026-04-08 在本机完成启动验证，http://127.0.0.1:5000 当前可返回 200。
纯本地 bootstrap 入口已补齐：首次拉起项目时可先执行 python -m scripts.dev.bootstrap_local，默认开发模式直接执行 python -m scripts.dev.start_local；仅在需要生成 Flask / Docker 单服务部署兼容产物时再执行 --frontend-mode build。
2026-04-09 已补齐 Windows 一键启动入口：可直接运行根目录 start_local.bat，真实逻辑统一收口到 scripts/dev/start_local_stack.ps1。
2026-04-09 已补齐项目自管 PostgreSQL 修复入口：python -m scripts.dev.repair_local_postgres 会在系统 5432 实例不可用或凭据不匹配时，自动在 var/db/postgres-local/ 下拉起本地实例，并把 .env.local 切到 127.0.0.1:55432。
当前机器上的纯本地数据库链路已不再依赖系统 5432 实例的管理员密码；python -m scripts.dev.prepare_local_postgres --check-only 当前已在 55432 上验证通过。
2026-04-09 已完成根目录低价值 shim 回收：config.py、crawler_web.py、openai_compat.py 已删除，canonical 导入面分别固定为 services.shared.config、backend.crawler 与 utils.openai_compat。
2026-04-09 已完成 T-114：var/output/chrome-headless/ 已在运行态复核后受控删除，var/output/ 当前仅剩 screens/ 截图与 .gitkeep。
2026-04-09 已完成 T-521：根目录 Dockerfile、docker-compose.yml 与 docker-compose.override.yml 已删除，Docker 入口统一固定为 infra/docker/。
2026-04-09 已完成 T-522：本地默认启动已切换为 5173 前端热更新 + 5000 后端 API 的前后端分离模式，--frontend-mode build / --build-frontend 继续保留 Flask 静态托管兼容链路。
2026-04-09 已完成 T-523：本地前端默认端口已从 5173 收口到 9527，并同步更新 Python / PowerShell 启动脚本、Vite 配置与中英文 README。
2026-04-09 已完成 T-524：根目录 app.py 已完成保留评估，确认仓内代码已无真实依赖，建议在同步清理旧文档与外部命令后进入删除窗口。
2026-04-10 已完成 T-525：根目录 app.py 已删除，当前仓库根目录只保留 start_local.bat 作为用户向一键启动薄入口。
2026-04-10 已完成 T-526：确认 apps/web_api/app.py 中的前端 build 托管已不再承担本地开发主链路，但 Docker / 单服务部署仍依赖它返回 static/frontend/index.html，当前不应直接删除。
2026-04-10 已完成 T-527：已移除 BETTAFISH_FRONTEND_MODE 冗余环境变量写入，并把 build 模式在 README、模块 README、fallback 页与启动脚本提示中统一收口为 Flask / Docker 单服务部署兼容用途。
2026-04-10 已完成 T-528：已新增独立前端交付方案文档，确认当前推荐路径应先落地“同源反向代理的独立前端服务”，再逐步推进 API-only 后端收口。


当前阶段的主干结构优化任务与主要收尾项已全部完成，后续更推荐转入以下进一步收口动作：


如需继续推进纯本地体验，可进一步清理 Conda PowerShell 编码噪声，并按需补齐 WeasyPrint / Scipy 这类非阻塞依赖。
如需继续做前后端工程化收尾，可优先执行前端 URL 配置收口与引擎 iframe 去端口耦合，再进入独立前端交付落地。
如需继续做根级收口，可继续围绕仅剩的 start_local.bat 整理用户入口说明，并清理历史文档中已过时的兼容表述；start_local.bat 建议继续作为 Windows 一键入口保留。


8. 当前工作日志


2026-04-02


完成结构优化任务文档初版创建。
明确后续每次执行结构优化任务后，需要同步更新任务文档和记忆文件。
将当前可执行任务拆分为 6 个阶段、22 个任务项。
当前推荐从运行时目录隔离和 ignore 规则收口开始，而不是直接做大规模目录迁移。


2026-04-02 / T-101


任务：T-101

状态：todo -> done

变更：


新增统一运行时目录骨架 var/

新增 utils/runtime_paths.py 作为运行时路径单一入口
将日志、最终报告、三引擎报告、浏览器数据、数据库卷、临时输出统一映射到 var/


涉及文件：


utils/runtime_paths.py
var/README.md
var/logs/.gitkeep
var/reports/final/.gitkeep
var/reports/engines/insight/.gitkeep
var/reports/engines/media/.gitkeep
var/reports/engines/query/.gitkeep
var/crawler/browser_data/.gitkeep
var/db/postgres/.gitkeep
var/output/.gitkeep
app.py
backend/research_tasks.py
backend/crawler/state_store.py
scripts/reports/export_pdf.py
SingleEngineApp/insight_engine_streamlit_app.py
SingleEngineApp/media_engine_streamlit_app.py
SingleEngineApp/query_engine_streamlit_app.py
ReportEngine/agent.py
ReportEngine/flask_interface.py
ReportEngine/renderers/pdf_renderer.py
ReportEngine/nodes/chapter_generation_node.py


验证：


python -m py_compile ... 通过

python 脚本调用 ensure_runtime_dirs() 后成功创建全部 var/ 子目录


风险 / 遗留：


根目录旧运行目录尚未清理，当前仍处于“新目录生效 + 旧目录残留”的过渡态


下一步建议：


执行 T-104，输出根目录历史运行目录与兼容残留的处理清单


2026-04-02 / T-102


任务：T-102

状态：todo -> done

变更：


收紧 .gitignore，允许跟踪 var/ 骨架但忽略其运行时内容
新增 frontend/node_modules/、static/frontend/、.codex-tmp-* 等规则
收紧 .dockerignore，排除运行目录、本地依赖、构建产物和临时目录


涉及文件：


.gitignore
.dockerignore


验证：


git status --short 中 var/ 目录骨架可被跟踪
Docker build context 相关目录已被忽略配置覆盖


风险 / 遗留：


旧运行目录仍保留在忽略规则中，待 T-104 统一清理策略


下一步建议：


执行 T-104


2026-04-02 / T-103


任务：T-103

状态：todo -> done

变更：


将 docker-compose.yml 的主机侧 volume 全部切换到 ./var/...

保留容器内旧路径兼容挂载，避免未迁移模块立即失效
更新 Dockerfile，为新旧运行路径同时预创建目录


涉及文件：


docker-compose.yml
Dockerfile


验证：


docker compose -f docker-compose.yml -f docker-compose.override.yml config 通过


风险 / 遗留：


当前仍存在容器内旧路径兼容挂载，后续应用层/服务层迁移完成后可继续收口


下一步建议：


先执行 T-104 清理清单，再进入 T-201


2026-04-02 / T-104


任务：T-104

状态：todo -> done

变更：


新增根目录清理清单文档 docs/project-structure-root-cleanup-inventory.md

将根目录残留分为“可立即删除的临时残留”“需迁移或归档后删除的旧运行目录”“暂时保留的兼容入口”“当前目标态保留目录”四类
明确 logs/、final_reports/、三个 *_streamlit_reports/、crawler_browser_data/、db_data/、output/ 的后续处理顺序
记录 crawler_web.py、export_pdf.py、report_engine_only.py、regenerate_latest_*.py 与 Dockerfile.runtime-hotfix 的过渡身份


涉及文件：


docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


核对根目录当前残留目录与文件现状
核对旧运行目录的文件数与体积，形成迁移优先级依据
核对 crawler_web.py、export_pdf.py、Dockerfile.runtime-hotfix 与 ReportEngine/utils/config.py 的兼容残留状态


风险 / 遗留：


本任务只完成清单与策略，不等于已经删除全部根目录残留

crawler_browser_data/ 与 db_data/ 仍需在停进程/停容器条件下谨慎处理
多个历史脚本仍直接引用 final_reports/ 和 logs/，需在后续任务中继续收口


下一步建议：


执行 T-201，开始建立 apps/ 一级目录骨架


2026-04-07 / T-105


任务：T-105

状态：todo -> done

变更：


删除根目录 .codex-tmp-mediacrawler/

删除根目录 .codex-tmp-mediacrawler2/

删除根目录 .codex-tmp-mediacrawler.zip

将根目录清理从“仅有清单”推进到“实际物理删除已执行”的状态


涉及文件：


docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


通过 Resolve-Path 先确认三个删除目标都位于工作区 d:\\工作\\APP\\AI-Agent-Platform\\BettaFish

删除后再次检查，三个 .codex-tmp-* 路径均已不存在
根目录 Get-ChildItem -Force 复核后，不再出现 .codex-tmp-mediacrawler* 目录和压缩包


风险 / 遗留：


本轮仅清理了最低风险临时残留，logs/、final_reports/、*_streamlit_reports/、output/ 等旧运行目录仍待进一步归档或删除
根目录 .pytest_cache/ 与各处 __pycache__/ 仍属于可再生运行产物，但尚未纳入本轮结构化清理任务


下一步建议：


继续评估并收口轻量旧运行目录，优先处理 logs/、final_reports/、*_streamlit_reports/ 与 output/


2026-04-02 / T-201


任务：T-201

状态：todo -> done

变更：


新增 apps/ 一级目录骨架
新增 apps/web_api/、apps/web_ui/、apps/engine_console/ 三个应用层承接目录
为每个子目录补充职责说明与当前迁移边界，明确现阶段仍由原目录承载真实代码


涉及文件：


apps/README.md
apps/web_api/README.md
apps/web_ui/README.md
apps/engine_console/README.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


核对 apps/ 目录及三个子目录已创建
核对 apps/README.md 中的迁移映射与任务拆分一致


风险 / 遗留：


当前仅建立目录骨架，真实前后端与控制台代码尚未迁移
根目录旧入口仍然是运行时事实来源，需后续任务继续收口


下一步建议：


执行 T-202，迁移前端到 apps/web_ui/


2026-04-02 / T-202


任务：T-202

状态：todo -> done

变更：


将真实 Vue 3 + Vite + TypeScript 前端工程从根目录 frontend/ 迁移到 apps/web_ui/

更新 Vite 构建输出路径，继续输出到 static/frontend/，避免当前 Flask 静态资源链路回归
更新 Dockerfile 前端构建阶段到 apps/web_ui/

为根目录 frontend/ 新增兼容壳，用于转发旧的 npm run dev/build/preview/typecheck

更新根目录清理清单，明确 frontend/ 已降级为过渡兼容目录


涉及文件：


apps/web_ui/index.html
apps/web_ui/package.json
apps/web_ui/package-lock.json
apps/web_ui/tsconfig.json
apps/web_ui/tsconfig.node.json
apps/web_ui/vite.config.ts
apps/web_ui/src/**
apps/web_ui/README.md
apps/README.md
frontend/package.json
frontend/README.md
.gitignore
.dockerignore
Dockerfile
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


在 apps/web_ui/ 下执行 npm ci 与 npm run build 通过
在根目录 frontend/ 兼容壳下执行 npm run build，确认旧命令可正常转发

docker compose -f docker-compose.yml -f docker-compose.override.yml config 通过


风险 / 遗留：


根目录 frontend/ 仍作为兼容壳存在，后续可在 T-205 统一评估是否继续保留
当前后端静态资源链路仍依赖 static/frontend/，后续若要继续收口需配合 app.py 和部署链路一起调整
尝试执行 docker build -f Dockerfile --target frontend-builder -q . 时，因本机缺少 node:20-alpine 且 Docker Hub 鉴权连接中断而未完成；这是外部网络阻塞，不是前端路径配置错误


下一步建议：


执行 T-203，迁移 Web API 装配层到 apps/web_api/


2026-04-02 / T-203


任务：T-203

状态：todo -> done

变更：


将真实 Flask 装配入口从根目录 app.py 迁移到 apps/web_api/app.py

为 apps/、apps/web_api/ 新增 Python 包入口，支持 python -m apps.web_api

在 apps/web_api/app.py 中显式指定根目录 static/ 与 templates/，避免迁移后静态资源链路失效
将根目录 app.py 降级为兼容 shim，继续保留旧启动方式
更新 Dockerfile 默认启动命令为 python -m apps.web_api

更新根目录清理清单，明确 app.py 已变为兼容入口


涉及文件：


apps/__init__.py
apps/web_api/__init__.py
apps/web_api/__main__.py
apps/web_api/app.py
apps/web_api/README.md
apps/README.md
app.py
Dockerfile
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile app.py apps/__init__.py apps/web_api/__init__.py apps/web_api/__main__.py apps/web_api/app.py 通过
静态检索确认仓库内无其他模块依赖旧版根目录 app.py 的内部符号

docker compose -f docker-compose.yml -f docker-compose.override.yml config 通过


风险 / 遗留：


当前本地 Python 环境缺少 flask 依赖，无法直接 import 新入口并执行 Flask 测试客户端验证
运行时级别验证仍需在具备完整 Python 依赖或可正常拉取基础镜像的环境中补做

backend/ 仍承接部分蓝图与支撑模块，后续还需继续向更清晰的应用层/服务层边界演进


下一步建议：


执行 T-204，迁移 SingleEngineApp/ 到 apps/engine_console/


2026-04-02 / T-204


任务：T-204

状态：todo -> done

变更：


将三个真实 Streamlit 引擎入口从根目录 SingleEngineApp/ 迁移到 apps/engine_console/

更新三个脚本的项目根路径解析逻辑，避免迁移后 sys.path 指向错误
更新 apps/web_api/app.py 中的引擎控制台脚本路径到 apps/engine_console/

更新 apps/engine_console/README.md 与仓库 README 中的推荐启动路径


涉及文件：


apps/engine_console/__init__.py
apps/engine_console/insight_engine_streamlit_app.py
apps/engine_console/media_engine_streamlit_app.py
apps/engine_console/query_engine_streamlit_app.py
apps/engine_console/README.md
apps/README.md
apps/web_api/app.py
README.md
README-EN.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile 对迁移后的控制台脚本和兼容 wrapper 通过
静态检索确认 apps/web_api 已切换为优先使用 apps/engine_console/ 路径
仓库内剩余 SingleEngineApp/ 引用仅保留在兼容 wrapper 与少量文档说明范围内


风险 / 遗留：


当前本地 Python 环境未验证 streamlit 运行时级别行为，运行验证仍需完整依赖环境
根目录 SingleEngineApp/ 仍作为兼容壳存在，后续可在 T-205 统一收口策略下继续评估


下一步建议：


同步确认 T-205 的兼容 shim 覆盖范围并标记完成


2026-04-02 / T-205


任务：T-205

状态：todo -> done

变更：


为根目录 frontend/ 保留命令转发兼容壳
为根目录 app.py 保留 Web API 启动兼容 shim
为根目录 SingleEngineApp/*.py 保留三个 Streamlit 入口兼容 wrapper
在根目录清理清单中明确以上目录/文件均已降级为过渡兼容入口


涉及文件：


frontend/package.json
frontend/README.md
app.py
SingleEngineApp/insight_engine_streamlit_app.py
SingleEngineApp/media_engine_streamlit_app.py
SingleEngineApp/query_engine_streamlit_app.py
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


根目录 frontend/ 兼容壳已验证可以转发旧构建命令
静态检索确认仓库内无其他模块依赖旧版根目录 app.py 的内部符号
兼容 wrapper 的 Python 语法检查已通过


风险 / 遗留：


兼容层虽然保留了旧使用方式，但也意味着根目录短期内仍会保留少量历史入口
后续若继续清理这些兼容入口，需要结合对外使用情况和部署链路一起评估


下一步建议：


执行 T-301，建立 services/engines/ 骨架


2026-04-02 / T-301


任务：T-301

状态：todo -> done

变更：


新建 services/ 与 services/engines/ 服务层骨架
新建五大引擎目标子目录：insight/、media/、query/、report/、forum/

通过 README 说明当前根目录引擎目录与未来迁移目标之间的映射关系


涉及文件：


services/__init__.py
services/README.md
services/engines/__init__.py
services/engines/README.md
services/engines/insight/README.md
services/engines/media/README.md
services/engines/query/README.md
services/engines/report/README.md
services/engines/forum/README.md
apps/README.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile services/__init__.py services/engines/__init__.py 通过
核对 services/engines/ 与五个子目录已实际创建
核对 services/engines/README.md 中的迁移映射与当前任务拆分一致


风险 / 遗留：


当前只建立了服务层骨架，五大引擎真实实现仍在根目录目录中

services/shared/ 尚未建立，真正搬迁引擎前还缺少公共层承接点


下一步建议：


执行 T-303，建立 services/shared/ 公共层


2026-04-02 / T-303


任务：T-303

状态：todo -> done

变更：


新建 services/shared/ 公共层骨架
新建 config/、llm/、utils/、logging/ 四个共享子目录
通过 README 明确当前分散来源与后续收口目标映射


涉及文件：


services/shared/__init__.py
services/shared/README.md
services/shared/config/README.md
services/shared/llm/README.md
services/shared/utils/README.md
services/shared/logging/README.md
services/README.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile services/shared/__init__.py 通过
核对 services/shared/ 与四个子目录已实际创建
核对 services/shared/README.md 中的来源映射与当前项目现状一致


风险 / 遗留：


当前仍只是公共层骨架，真实配置、LLM、工具和日志代码尚未迁入
若直接开始 T-302 大规模迁移引擎目录，仍会受到配置入口分裂的影响


下一步建议：


执行 T-304，统一配置入口与环境模型


2026-04-03 / T-304


任务：T-304

状态：todo -> done

变更：


新建共享配置基础设施：services/shared/config/base.py、services/shared/config/app_settings.py、services/shared/config/__init__.py

将根目录 config.py 改为兼容 shim，统一转发到 services.shared.config

将 InsightEngine、MediaEngine、QueryEngine、ReportEngine 与 MindSpider 的配置模块统一切换为继承 SharedSettings

统一 .env 解析优先级与“空环境变量不覆盖 .env 值”的加载策略
在根目录清理清单中记录 config.py 已降级为兼容导入入口


涉及文件：


services/shared/config/base.py
services/shared/config/app_settings.py
services/shared/config/__init__.py
services/shared/config/README.md
config.py
InsightEngine/utils/config.py
MediaEngine/utils/config.py
QueryEngine/utils/config.py
ReportEngine/utils/config.py
MindSpider/config.py
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile config.py services/shared/config/__init__.py services/shared/config/base.py services/shared/config/app_settings.py InsightEngine/utils/config.py MediaEngine/utils/config.py QueryEngine/utils/config.py ReportEngine/utils/config.py MindSpider/config.py 通过
已验证根目录 config.py shim 与 services.shared.config 可正常导入
已用按文件直载方式验证各引擎配置模块可基于共享配置基类完成初始化


风险 / 遗留：


当前只是统一了配置加载基础设施，各引擎的字段定义仍有重复，后续可继续按共享/专属边界逐步收口
受当前环境缺少 numpy、loguru 等运行依赖影响，未对完整引擎包做运行时导入验证；本次验证聚焦于配置模块本身


下一步建议：


执行 T-302，开始将五大引擎真实代码迁移到 services/engines/*


2026-04-03 / T-401


任务：T-401

状态：todo -> done

变更：


新建 services/crawler/ 爬虫服务层骨架
新建 mindspider/、adapters/、web/ 三个目标子目录
通过 README 明确 MindSpider/、backend/crawler/ 与后续 MediaCrawler 适配层的迁移边界


涉及文件：


services/crawler/__init__.py
services/crawler/README.md
services/crawler/mindspider/README.md
services/crawler/adapters/README.md
services/crawler/web/README.md
services/README.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile services/crawler/__init__.py 通过
核对 services/crawler/ 与三个子目录已实际创建
核对 services/crawler/README.md 中的来源映射与当前项目现状一致


风险 / 遗留：


当前只建立了爬虫服务层骨架，真实实现仍在 MindSpider/ 与 backend/crawler/


MediaCrawler 仍嵌套在 MindSpider/DeepSentimentCrawling/MediaCrawler/，尚未完成 vendor 隔离


下一步建议：


保持主线执行 T-302，开始迁移五大引擎到 services/engines/*


2026-04-03 / T-302


任务：T-302

状态：todo -> done

变更：


将 InsightEngine/、MediaEngine/、QueryEngine/、ReportEngine/、ForumEngine/ 的真实代码迁移到 services/engines/insight/、media/、query/、report/、forum/

保留根目录同名目录作为兼容包承载点，为后续旧导入路径过渡留出空间
将 apps/engine_console/ 与 apps/web_api/ 的核心导入切换到 services.engines.* canonical 路径
更新 services/README.md 与 services/engines/*/README.md，将服务层状态从“骨架预留”升级为“真实代码已迁入”


涉及文件：


services/engines/insight/**
services/engines/media/**
services/engines/query/**
services/engines/report/**
services/engines/forum/**
apps/engine_console/insight_engine_streamlit_app.py
apps/engine_console/media_engine_streamlit_app.py
apps/engine_console/query_engine_streamlit_app.py
apps/web_api/app.py
services/README.md
services/engines/README.md
services/engines/insight/README.md
services/engines/media/README.md
services/engines/query/README.md
services/engines/report/README.md
services/engines/forum/README.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


核对五大引擎真实代码目录已实际落到 services/engines/*


python -m compileall services/engines InsightEngine MediaEngine QueryEngine ReportEngine ForumEngine apps/engine_console apps/web_api 通过
核对 apps/engine_console/*.py 与 apps/web_api/app.py 已不再直接导入根目录旧引擎包


风险 / 遗留：


仍有测试、脚本和历史入口继续使用根目录旧包名，当前依赖兼容层保持稳定
这一步只完成了引擎服务层迁移，根目录脚本与爬虫主实现尚未收口


下一步建议：


执行 T-501，开始建立 tools/ 一级目录并迁移根脚本


2026-04-03 / T-305


任务：T-305

状态：todo -> done

变更：


为 InsightEngine/、MediaEngine/、QueryEngine/、ReportEngine/、ForumEngine/ 新增根目录兼容包 __init__.py

兼容包通过扩展 __path__ 指向 services/engines/* 中的真实代码，保留旧模块路径可用
保持旧包名对外可导入，同时推动应用层优先使用 services.engines.*


涉及文件：


InsightEngine/__init__.py
MediaEngine/__init__.py
QueryEngine/__init__.py
ReportEngine/__init__.py
ForumEngine/__init__.py
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m compileall InsightEngine MediaEngine QueryEngine ReportEngine ForumEngine 通过
核对根目录兼容包已生成且语法检查通过


风险 / 遗留：


兼容包会让根目录仍保留少量历史目录壳，需等后续脚本与调用方完成切换后再评估是否收口
当前验证聚焦静态编译与导入链路改造，完整运行时验证仍依赖缺失的本地 Python 依赖恢复后补做


下一步建议：


执行 T-501


2026-04-07 / T-501


任务：T-501

状态：todo -> done

变更：


新建 tools/ 与 tools/reports/，作为报告导出、报告重建与命令行报告工具的真实目录
将 export_pdf.py、regenerate_latest_html.py、regenerate_latest_md.py、regenerate_latest_pdf.py、report_engine_only.py 的真实实现迁入 tools/reports/

将根目录同名脚本全部降级为 wrapper，并将 scripts/reports/export_pdf.py 同步降级为兼容转发入口
将报告类工具脚本的核心导入切换到 services.engines.report，并显式接入 utils/runtime_paths.py

将报告类工具脚本的默认输出与查找路径切到 var/reports/final/ 与 var/reports/engines/*


涉及文件：


tools/__init__.py
tools/README.md
tools/reports/__init__.py
tools/reports/README.md
tools/reports/export_pdf.py
tools/reports/regenerate_latest_html.py
tools/reports/regenerate_latest_md.py
tools/reports/regenerate_latest_pdf.py
tools/reports/report_engine_only.py
export_pdf.py
regenerate_latest_html.py
regenerate_latest_md.py
regenerate_latest_pdf.py
report_engine_only.py
scripts/reports/export_pdf.py
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m compileall tools export_pdf.py regenerate_latest_html.py regenerate_latest_md.py regenerate_latest_pdf.py report_engine_only.py scripts/reports/export_pdf.py 通过
核对 tools/reports/ 已实际承接五个报告类脚本
核对根目录与 scripts/reports/export_pdf.py 已降级为轻量 wrapper


风险 / 遗留：


根目录历史脚本文件名仍被保留用于兼容旧命令，短期内文件数量不会立刻大幅下降

crawler_web.py 仍属于后续 T-405 范围，本次未纳入 tools/ 收口
Report Engine 核心配置模块默认路径仍有历史值，当前由工具脚本侧显式覆盖，后续可视情况再统一收口


下一步建议：


执行 T-502，将 Docker 与 compose 文件迁移到 infra/docker/


2026-04-07 / T-502


任务：T-502

状态：todo -> done

变更：


新建 infra/README.md 与 infra/docker/README.md，明确基础设施层职责和 infra/docker/ 的 canonical 入口定位
将 Dockerfile、Dockerfile.runtime-hotfix、docker-compose.yml、docker-compose.override.yml 的真实版本迁入 infra/docker/

调整 infra/docker/ 下 compose 相对路径，使其在子目录中仍能正确解析仓库根目录 .env、build context 与 var/ 目录
将根目录同名 Docker / compose 文件降级为兼容副本，并显式标注 canonical 文件位于 infra/docker/

更新 .github/workflows/docker_ci.yml、README.md、README-EN.md 与结构优化文档，切换到新的基础设施 canonical 路径


涉及文件：


infra/README.md
infra/docker/README.md
infra/docker/Dockerfile
infra/docker/Dockerfile.runtime-hotfix
infra/docker/docker-compose.yml
infra/docker/docker-compose.override.yml
Dockerfile
Dockerfile.runtime-hotfix
docker-compose.yml
docker-compose.override.yml
.github/workflows/docker_ci.yml
README.md
README-EN.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


docker compose -f infra/docker/docker-compose.yml -f infra/docker/docker-compose.override.yml config 通过

docker compose -f docker-compose.yml -f docker-compose.override.yml config 通过
核对 infra/docker/docker-compose.override.yml 中 build.context、build.dockerfile、env_file 已正确切到仓库根目录相对路径
核对根目录 Docker / compose 文件已带有兼容说明头注释，且仍能作为旧命令入口工作


风险 / 遗留：


根目录 Dockerfile、Dockerfile.runtime-hotfix、docker-compose*.yml 仍需保留一段时间，避免旧文档命令或本地自动化立即失效

MindSpider/ 与 MediaCrawler 仍位于根目录系路径，Dockerfile 中相关复制路径尚未进入爬虫层收口阶段

Dockerfile.runtime-hotfix 仍属于兼容热修链路，后续是否继续保留需结合 T-402 ~ T-405 再评估


下一步建议：


执行 T-402，开始将 MindSpider/ 迁移到 services/crawler/mindspider/


2026-04-07 / T-402


任务：T-402

状态：todo -> done

变更：


将 MindSpider 主爬虫真实代码从根目录 MindSpider/ 迁入 services/crawler/mindspider/

为 services/crawler/mindspider/、BroadTopicExtraction/、DeepSentimentCrawling/ 补齐包入口与 runtime_paths.py，明确 canonical 目录与 MediaCrawler 过渡路径解析
将 apps/web_api/app.py 的 MindSpider 导入切到 services.crawler.mindspider.main

将 backend/crawler/runtime.py 的 MediaCrawler Web runtime 定位切到 canonical helper，当前仍解析到根目录旧 MediaCrawler 路径
将根目录 MindSpider/ 降级为兼容壳：保留 main.py、config.py、BroadTopicExtraction/main.py、DeepSentimentCrawling/main.py、schema/*.py wrapper，并继续承载 DeepSentimentCrawling/MediaCrawler/

更新 services/crawler/README.md、services/crawler/mindspider/README.md、README.md、README-EN.md，把 MindSpider canonical 路径切到 services/crawler/mindspider/


涉及文件：


services/crawler/mindspider/**
MindSpider/__init__.py
MindSpider/main.py
MindSpider/config.py
MindSpider/README.md
MindSpider/requirements.txt
MindSpider/config.py.example
MindSpider/BroadTopicExtraction/__init__.py
MindSpider/BroadTopicExtraction/main.py
MindSpider/DeepSentimentCrawling/__init__.py
MindSpider/DeepSentimentCrawling/main.py
MindSpider/schema/__init__.py
MindSpider/schema/db_manager.py
MindSpider/schema/init_database.py
apps/web_api/app.py
backend/crawler/runtime.py
services/crawler/README.md
README.md
README-EN.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m compileall services/crawler/mindspider MindSpider backend/crawler/runtime.py apps/web_api/app.py 通过
兼容命名空间检查通过：MindSpider、MindSpider.BroadTopicExtraction、MindSpider.DeepSentimentCrawling、MindSpider.schema 均已同时挂载 root 兼容目录与 canonical 目录

services.crawler.mindspider.runtime_paths.resolve_media_crawler_root() 与 resolve_media_crawler_runtime_path() 可正确解析到当前根目录旧 MediaCrawler 路径
全仓静态搜索确认：apps/web_api/app.py 已不再直接导入 MindSpider.main，backend/crawler/runtime.py 已不再硬编码旧 MindSpider/.../web_runtime.py 路径


风险 / 遗留：


当前本地环境缺少 pymysql，无法完成 import services.crawler.mindspider.main 级别的完整运行时导入验证
根目录 MindSpider/DeepSentimentCrawling/MediaCrawler/ 仍是实际生效路径，待 T-403 继续隔离为 vendor 目录
根目录 MindSpider/ 兼容壳仍需保留一段时间，避免旧 CLI 命令、README 缓存路径与本地自动化立即失效


下一步建议：


执行 T-403，开始将 MediaCrawler 隔离到 vendor/mediacrawler/


2026-04-07 / T-403


任务：T-403

状态：todo -> done

变更：


将 MediaCrawler 子模块工作树从 MindSpider/DeepSentimentCrawling/MediaCrawler/ 迁移到 vendor/mediacrawler/

更新 .gitmodules 与本地 submodule 配置，使 vendor/mediacrawler/ 成为新的 canonical 子模块路径
更新 services/crawler/mindspider/runtime_paths.py，优先解析 vendor/mediacrawler/，并保留共置路径与旧路径 fallback
将 infra/docker/ 与根目录兼容副本中的 Docker / compose 路径全部切到 vendor/mediacrawler/

更新 README.md、README-EN.md、services/crawler/README.md、services/crawler/mindspider/README.md、MindSpider/README.md 与 vendor/README.md，明确外部爬虫依赖的新目录边界


涉及文件：


vendor/mediacrawler/**
vendor/README.md
.gitmodules
services/crawler/mindspider/runtime_paths.py
services/crawler/mindspider/schema/models_bigdata.py
infra/docker/Dockerfile
infra/docker/Dockerfile.runtime-hotfix
infra/docker/docker-compose.yml
Dockerfile
Dockerfile.runtime-hotfix
docker-compose.yml
README.md
README-EN.md
services/crawler/README.md
services/crawler/mindspider/README.md
MindSpider/README.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m compileall services/crawler/mindspider backend/crawler/runtime.py apps/web_api/app.py MindSpider 通过
运行时路径检查通过：resolve_media_crawler_root() 已解析到 vendor/mediacrawler

运行时路径检查通过：backend.crawler.runtime.RUNTIME_PATH 已解析到 vendor/mediacrawler/web_runtime.py


docker compose -f infra/docker/docker-compose.yml -f infra/docker/docker-compose.override.yml config 通过

docker compose -f docker-compose.yml -f docker-compose.override.yml config 通过

git submodule status 已显示新路径 vendor/mediacrawler


风险 / 遗留：


当前本地环境仍缺少 pymysql，无法完成 import services.crawler.mindspider.main 级别的完整运行时导入验证

docs/project-structure-optimization-plan.md 仍保留若干基于迁移前状态的分析描述，后续若需要可再统一刷新

T-404 之前，主仓库对 MediaCrawler 的访问仍主要依赖运行时路径 helper，而不是独立适配层


下一步建议：


执行 T-404，开始补齐 mediacrawler_adapter 适配层


2026-04-07 / T-404


任务：T-404

状态：todo -> done

变更：


新增 services/crawler/adapters/mediacrawler_adapter.py 与 services/crawler/adapters/__init__.py，统一承接 MediaCrawler 根目录、运行脚本、依赖文件、配置文件等路径解析
将 services/crawler/mindspider/runtime_paths.py 降级为兼容 wrapper，转发到新的适配层实现
将 backend/crawler/runtime.py、services/crawler/mindspider/main.py、services/crawler/mindspider/DeepSentimentCrawling/platform_crawler.py 切到适配层 API
更新 services/crawler/adapters/README.md 与 services/crawler/README.md，明确外部爬虫调用边界已进入 adapter 收口阶段


涉及文件：


services/crawler/adapters/__init__.py
services/crawler/adapters/mediacrawler_adapter.py
services/crawler/adapters/README.md
services/crawler/mindspider/runtime_paths.py
services/crawler/mindspider/main.py
services/crawler/mindspider/DeepSentimentCrawling/platform_crawler.py
backend/crawler/runtime.py
services/crawler/README.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m compileall services/crawler/adapters services/crawler/mindspider backend/crawler/runtime.py apps/web_api/app.py MindSpider 通过
适配层路径检查通过：get_mediacrawler_paths() 已返回 root、runtime、db_config 等 vendor 路径
兼容转发检查通过：services.crawler.mindspider.runtime_paths 仍可返回 vendor/mediacrawler/web_runtime.py

运行时接入检查通过：backend.crawler.runtime.RUNTIME_PATH 与 RUNTIME_CWD 已来自适配层


风险 / 遗留：


当前本地环境仍缺少 pymysql，无法完成 import services.crawler.mindspider.main 级别的完整运行时导入验证
当前本地环境仍缺少 loguru，无法完成 platform_crawler 级别的完整模块导入验证

crawler_web.py 兼容入口尚未收口，主仓库爬虫侧的最终适配边界仍待 T-405 继续压实


下一步建议：


执行 T-405，开始收口 crawler_web.py 兼容入口


2026-04-07 / T-405


任务：T-405

状态：todo -> done

变更：


将 backend/crawler/__init__.py 收口为爬虫 Web 控制的 canonical 导出面，统一导出 crawler_bp、crawl_manager、login_manager、CrawlTaskManager、LoginTaskManager

将根目录 crawler_web.py 降级为最薄兼容 shim，仅转发 backend.crawler 对外导出，不再直接承载更深层装配逻辑
将 apps/web_api/app.py 中的蓝图导入切换为 from backend.crawler import crawler_bp

同步更新爬虫侧 README 与结构优化相关文档，明确 backend/crawler/ 是 canonical Web 控制入口，crawler_web.py 只是兼容层


涉及文件：


backend/crawler/__init__.py
crawler_web.py
apps/web_api/app.py
services/crawler/web/README.md
services/crawler/README.md
docs/venue-operations-research-backlog.md
docs/venue-operations-research-platform-plan.md
docs/venue-operations-research-project-memory.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m compileall backend/crawler apps/web_api crawler_web.py 通过
AST 静态检查通过：backend/crawler/__init__.py 仅负责统一重导出，crawler_web.py 仅从 backend.crawler 转发符号
仓内静态搜索未发现新的 backend.crawler.routes 直连导入或 crawler_web 反向依赖

git submodule status 仍显示 vendor/mediacrawler，说明前序 vendor 隔离状态未被本次收口破坏


风险 / 遗留：


当前本地环境仍缺少 loguru，无法完成 from backend.crawler import ... 与 from crawler_web import ... 级别的运行时导入验证
根目录 crawler_web.py 仍被保留为兼容入口，当前完成的是“最小化兼容壳”，不是彻底删除
根目录 MindSpider/ 兼容壳与历史 CLI/README 路径仍存在，需在后续任务中继续评估是否回收


下一步建议：


执行 T-601，评估 SentimentAnalysisModel/ 的保留策略


2026-04-07 / T-601


任务：T-601

状态：todo -> done

变更：


盘点 SentimentAnalysisModel/ 下 5 组子目录的内容类型、体积构成与仓库内引用关系
确认该目录整体属于“研究/训练资产集合”，而不是主运行链路一级目录，也不是适合直接 vendoring 的单一外部仓库
明确后续 T-602 的迁移策略应为“研究资产迁入 research/ + 单独处理运行时缓存路径”，而不是对现有目录做无差别整体平移


涉及文件：


docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


目录盘点结果：SentimentAnalysisModel/ 当前包含 61 个文件、17 个子目录，体积主要来自 .csv、.pth、.pkl 等数据集与模型权重
体积核对结果：最大文件分别是 BertTopicDetection_Finetuned/dataset/web_text_zh_train.csv、WeiboSentiment_MachineLearning/model/lstm_model.pth 等训练/数据产物，而不是主应用装配代码
仓内 Python 引用核对结果：仅 services/engines/insight/tools/sentiment_analyzer.py 一处直接引用 SentimentAnalysisModel/WeiboMultilingualSentiment

运行角色核对结果：WeiboMultilingualSentiment 仅被 InsightEngine 用作可选本地模型缓存落点，其余子目录均未进入当前主运行链路


风险 / 遗留：


services/engines/insight/tools/sentiment_analyzer.py 仍硬编码 SentimentAnalysisModel/WeiboMultilingualSentiment 路径，T-602 前不能直接搬迁目录

README.md 与 README-EN.md 仍暴露多条 cd SentimentAnalysisModel/... 命令，后续迁移时需要同步收口文档
若后续保留 WeiboMultilingualSentiment 的本地缓存能力，建议把运行时缓存位置和研究样例脚本拆开管理


下一步建议：


执行 T-602，将研究资产迁入 research/，并为情感分析运行时缓存单独设计路径


2026-04-07 / T-602


任务：T-602

状态：todo -> done

变更：


新建 research/ 与 research/sentiment_models/ 目录说明文档，作为研究资产承接点
将 BertTopicDetection_Finetuned/、WeiboSentiment_Finetuned/、WeiboSentiment_MachineLearning/、WeiboSentiment_SmallQwen/ 从根目录 SentimentAnalysisModel/ 迁入 research/sentiment_models/

将根目录 SentimentAnalysisModel/ 收口为兼容目录，仅保留 WeiboMultilingualSentiment/ 运行时缓存/示例入口，并新增迁移说明文档
更新中英文 README 中的目录树与命令示例路径，使研究模型命令切到 research/sentiment_models/


涉及文件：


research/README.md
research/sentiment_models/README.md
research/sentiment_models/BertTopicDetection_Finetuned/**
research/sentiment_models/WeiboSentiment_Finetuned/**
research/sentiment_models/WeiboSentiment_MachineLearning/**
research/sentiment_models/WeiboSentiment_SmallQwen/**
SentimentAnalysisModel/README.md
README.md
README-EN.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


迁移后根目录 SentimentAnalysisModel/ 仅剩 WeiboMultilingualSentiment/ 与 README.md


research/sentiment_models/ 已承接 4 组研究模型目录与新的目录说明文档
已确认 README.md 与 README-EN.md 中不再保留已迁移模型的旧根目录命令路径
迁移过程中未改动 services/engines/insight/tools/sentiment_analyzer.py 当前依赖的 SentimentAnalysisModel/WeiboMultilingualSentiment 路径


风险 / 遗留：


根目录 SentimentAnalysisModel/ 仍作为兼容/运行时缓存目录存在，后续若要彻底移出根目录，需要先把 WeiboMultilingualSentiment 路径配置化

README 之外的历史分析文档仍可能保留迁移前的描述；若这些文档需要面向开发执行，应后续逐步刷新
当前尚未建立 research/ 目录下统一的测试、元数据或索引规范，后续研究资产继续增多时可能再次出现内部杂糅


下一步建议：


执行 T-503，建立统一测试目录分层


2026-04-07 / T-503


任务：T-503

状态：todo -> done

变更：


建立 tests/unit、tests/integration、tests/e2e 与 tests/fixtures 分层骨架，并补充 pytest.ini、tests/conftest.py 与新的测试目录说明文档
将报告引擎相关测试从 services/engines/report/utils/ 与扁平 tests/ 迁入 tests/unit/report/

将论坛日志解析测试迁入 tests/integration/forum/，并把 forum_log_test_data.py 收口到 tests/fixtures/

保留 tests/run_tests.py 旧入口，但真实实现改由 tests/integration/forum/run_tests.py 承接
将测试导入优先切到 services.engines.* canonical 路径，减少对根目录兼容包的依赖


涉及文件：


pytest.ini
tests/README.md
tests/conftest.py
tests/fixtures/__init__.py
tests/fixtures/forum_log_test_data.py
tests/unit/__init__.py
tests/unit/report/__init__.py
tests/unit/report/test_chart_validator.py
tests/unit/report/test_json_parser.py
tests/unit/report/test_report_engine_sanitization.py
tests/integration/__init__.py
tests/integration/forum/__init__.py
tests/integration/forum/test_monitor.py
tests/integration/forum/run_tests.py
tests/e2e/README.md
tests/run_tests.py
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m compileall tests 通过
仓内静态搜索确认：除当前迁移任务记录外，主仓库文档与代码已不再引用旧测试路径 tests/test_monitor.py、tests/test_report_engine_sanitization.py、services/engines/report/utils/test_*.py

已确认 services/engines/report/utils/ 不再混放测试文件，主仓库测试已回收到 tests/

已确认 pytest.ini 默认只收集主仓库 tests/unit、tests/integration、tests/e2e，不把 vendor/mediacrawler 自带测试混入主测试入口


风险 / 遗留：


python tests/run_tests.py 运行时仍会因当前环境缺少 loguru 而失败，说明测试入口链路本身可解析，但环境尚不完整
当前只完成了测试目录分层，还没有建立 CI 守门、分层测试命令矩阵与依赖安装策略

vendor/mediacrawler 自带测试目前仍保持原状，后续若要纳入统一自动化，需要单独设计第三方依赖与隔离策略


下一步建议：


执行 T-504，增加基础自动化守门


2026-04-07 / T-504


任务：T-504

状态：todo -> done

变更：


新增 .github/workflows/quality_ci.yml，建立主仓库最小质量守门工作流，拆分为 Python 质量检查与前端类型检查两个作业
将 Python 守门链路收敛为“compileall + flake8 tests --extend-ignore=E501,W293,W391,E402,E712,F401 + pytest tests/unit tests/integration”
将前端守门链路收敛为 npm ci + npm run typecheck --prefix apps/web_ui

修复 apps/web_ui/src/components/crawler/CrawlerControlForm.vue 的隐式 any 事件参数问题，并修复 apps/web_ui/src/composables/useCrawlerController.ts 的泛型字段恢复赋值类型错误
新增根目录 openai_compat.py 兼容 shim，并将 services/engines/report/、services/engines/report/utils/、services/engines/report/nodes/ 与 ReportEngine/ 的包级导出改为惰性导入，避免测试收集时被报告引擎重型依赖链路误伤


涉及文件：


.github/workflows/quality_ci.yml
apps/web_ui/src/components/crawler/CrawlerControlForm.vue
apps/web_ui/src/composables/useCrawlerController.ts
openai_compat.py
services/engines/report/__init__.py
services/engines/report/utils/__init__.py
services/engines/report/nodes/__init__.py
ReportEngine/__init__.py
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md
docs/project-structure-root-cleanup-inventory.md


验证：


python -m compileall tests services/engines/forum/monitor.py services/engines/report/utils/chart_validator.py services/engines/report/utils/json_parser.py services/engines/report/nodes/chapter_generation_node.py openai_compat.py 通过

python -m flake8 tests --extend-ignore=E501,W293,W391,E402,E712,F401 通过

python -m pytest tests/unit tests/integration 通过，结果为 75 passed


npm --prefix apps/web_ui run typecheck 通过


风险 / 遗留：


当前 CI 采用的是“最小可执行依赖集”，尚未覆盖完整业务运行依赖、PDF 渲染链路与模型训练/推理依赖

vendor/mediacrawler 自带测试仍未并入主仓库默认守门，后续若要纳入应单独设计隔离策略

SentimentAnalysisModel/WeiboMultilingualSentiment 的根目录兼容/运行时缓存路径仍待后续配置化收口


下一步建议：


当前主干任务已完成；其中 WeiboMultilingualSentiment 路径配置化已在后续 T-603 中落地，继续评估 vendor/mediacrawler 的独立自动化任务


2026-04-07 / T-603


任务：T-603

状态：todo -> done

变更：


在 services/shared/config/app_settings.py 中新增 INSIGHT_SENTIMENT_MODEL_DIR 共享配置项，默认值保持为 SentimentAnalysisModel/WeiboMultilingualSentiment

将 services/engines/insight/tools/sentiment_analyzer.py 中的情感模型工作目录解析收口为可配置函数，支持项目相对路径与绝对路径
将 services/engines/insight/、services/engines/insight/tools/ 与根目录 InsightEngine/ 的包级导出改为惰性导出，避免路径测试被额外依赖链路阻断
新增 tests/unit/insight/test_sentiment_analyzer_paths.py，覆盖默认路径、项目相对覆盖和绝对路径覆盖
更新 .env.example 与相关 README，明确多语言情感模型运行目录现由 INSIGHT_SENTIMENT_MODEL_DIR 控制


涉及文件：


.env.example
services/shared/config/app_settings.py
services/engines/insight/__init__.py
services/engines/insight/tools/__init__.py
services/engines/insight/tools/sentiment_analyzer.py
InsightEngine/__init__.py
tests/unit/insight/__init__.py
tests/unit/insight/test_sentiment_analyzer_paths.py
README.md
README-EN.md
SentimentAnalysisModel/README.md
research/sentiment_models/README.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile services/shared/config/app_settings.py services/engines/insight/tools/sentiment_analyzer.py services/engines/insight/__init__.py services/engines/insight/tools/__init__.py InsightEngine/__init__.py tests/unit/insight/test_sentiment_analyzer_paths.py 通过

python -m pytest tests/unit/insight/test_sentiment_analyzer_paths.py 通过，结果为 3 passed


python -m flake8 tests --extend-ignore=E501,W293,W391,E402,E712,F401 通过

python -m pytest tests/unit tests/integration 通过，结果为 78 passed


风险 / 遗留：


INSIGHT_SENTIMENT_MODEL_DIR 当前默认仍指向根目录兼容目录，只是已解除代码硬编码；若要彻底移出根目录，后续仍需决定迁往 var/ 还是独立模型缓存目录
当时 vendor/mediacrawler 的独立自动化/隔离守门策略尚未落地；该项已在后续 T-505 中补齐


下一步建议：


vendor/mediacrawler 独立自动化已在后续 T-505 中落地，后续可继续评估默认情感模型缓存目录是否迁出根目录


2026-04-07 / T-505


任务：T-505

状态：todo -> done

变更：


新增 .github/workflows/mediacrawler_ci.yml，为 vendor/mediacrawler 建立独立 GitHub Actions 工作流，并限制为路径命中或手动触发时运行
新增 tools/ci/run_mediacrawler_quality.py，固定 vendor/mediacrawler 的隔离 smoke tests 入口，避免把第三方测试重新混入主仓库默认 pytest

新增 tools/ci/README.md，并更新 tools/README.md 与 vendor/README.md，明确独立守门入口、Python 版本约束与使用方式
将 vendor/mediacrawler 隔离守门固定为 Python 3.11 + vendor 自身依赖安装，避免主仓库 Python 3.13 本地环境与第三方依赖矩阵互相污染


涉及文件：


.github/workflows/mediacrawler_ci.yml
tools/ci/README.md
tools/ci/run_mediacrawler_quality.py
tools/README.md
vendor/README.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile tools/ci/run_mediacrawler_quality.py 通过

python tools/ci/run_mediacrawler_quality.py --print-only 通过，已输出固定 smoke-test 命令
本地临时虚拟环境尝试在 Python 3.13 下安装 vendor/mediacrawler/requirements.txt 时，卡在 Pillow==9.5.0 构建阶段，验证了独立 workflow 锁定 Python 3.11 的必要性


风险 / 遗留：


当前工作流只覆盖 vendor/mediacrawler 的轻量 smoke tests，数据库、Redis、MongoDB、代理池等外部依赖测试仍未纳入
受限于本地缺少 Python 3.11 运行时，本轮未在本机完整跑通 vendor smoke tests，完整验证需依赖 GitHub Actions 或后续补齐本地 3.11 环境


下一步建议：


INSIGHT_SENTIMENT_MODEL_DIR 默认缓存迁移已在后续 T-604 中完成，后续可继续评估根目录 SentimentAnalysisModel/ 是否还有进一步缩减空间


2026-04-07 / T-604


任务：T-604

状态：todo -> done

变更：


将 INSIGHT_SENTIMENT_MODEL_DIR 的共享默认值从根目录 SentimentAnalysisModel/WeiboMultilingualSentiment 切换到 var/models/insight_weibo_multilingual

更新 services/engines/insight/tools/sentiment_analyzer.py 的默认路径常量，并移除对运行时模型目录的 sys.path 追加逻辑
为 var/models/ 补齐目录骨架与 .gitignore 跟踪规则，并在 var/README.md 中登记模型缓存职责
扩展 tests/unit/insight/test_sentiment_analyzer_paths.py，在新默认路径下继续覆盖旧根目录兼容路径 override
更新中英文 README、研究目录说明、根目录清理清单与结构优化文档，明确默认缓存已经迁到 var/


涉及文件：


.env.example
.gitignore
services/shared/config/app_settings.py
services/engines/insight/tools/sentiment_analyzer.py
tests/unit/insight/test_sentiment_analyzer_paths.py
var/README.md
var/models/.gitkeep
README.md
README-EN.md
SentimentAnalysisModel/README.md
research/sentiment_models/README.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile services/shared/config/app_settings.py services/engines/insight/tools/sentiment_analyzer.py tests/unit/insight/test_sentiment_analyzer_paths.py 通过

python -m pytest tests/unit/insight/test_sentiment_analyzer_paths.py 通过，结果为 4 passed


python -m flake8 tests --extend-ignore=E501,W293,W391,E402,E712,F401 通过

python -m pytest tests/unit tests/integration 通过，结果为 79 passed


风险 / 遗留：


根目录 SentimentAnalysisModel/WeiboMultilingualSentiment 仍保留示例脚本与 README，尚未完全从根目录回收
运行时首次下载模型时会写入 var/models/insight_weibo_multilingual/model/，部署环境仍需确保该目录可写


下一步建议：


评估是否继续回收根目录 SentimentAnalysisModel/，将 WeiboMultilingualSentiment 示例入口进一步迁入 research/ 或仅保留文档说明


2026-04-07 / T-605


任务：T-605

状态：todo -> done

变更：


在 research/sentiment_models/WeiboMultilingualSentiment/ 下建立多语言情感分析研究示例的正式落点，并重写 predict.py 为可执行的 CLI / demo / 交互三用脚本
将根目录 SentimentAnalysisModel/WeiboMultilingualSentiment/predict.py 改为最薄兼容 wrapper，转发到 research/ 下的正式脚本
将根目录 SentimentAnalysisModel/WeiboMultilingualSentiment/README.md 与 SentimentAnalysisModel/README.md 收口为兼容说明，不再把根目录位置描述为正式研究目录
更新中英文 README 与 research/sentiment_models/README.md，把示例命令和目录树切到 research/sentiment_models/WeiboMultilingualSentiment/

为研究示例的本地缓存补充 .gitignore 路径，避免 research/sentiment_models/WeiboMultilingualSentiment/model/ 回流仓库


涉及文件：


.gitignore
README.md
README-EN.md
SentimentAnalysisModel/README.md
SentimentAnalysisModel/WeiboMultilingualSentiment/README.md
SentimentAnalysisModel/WeiboMultilingualSentiment/predict.py
research/sentiment_models/README.md
research/sentiment_models/WeiboMultilingualSentiment/README.md
research/sentiment_models/WeiboMultilingualSentiment/predict.py
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile research/sentiment_models/WeiboMultilingualSentiment/predict.py SentimentAnalysisModel/WeiboMultilingualSentiment/predict.py 通过

python research/sentiment_models/WeiboMultilingualSentiment/predict.py --help 通过

python SentimentAnalysisModel/WeiboMultilingualSentiment/predict.py --help 通过

git grep -n "SentimentAnalysisModel/WeiboMultilingualSentiment" 复核后，仅剩兼容说明、README 解释与 .gitignore 历史兼容路径


风险 / 遗留：


research/sentiment_models/WeiboMultilingualSentiment/predict.py 仍依赖 transformers 与 torch，在未安装依赖的环境中只能完成 --help 级别验证
根目录 SentimentAnalysisModel/WeiboMultilingualSentiment/ 仍保留 wrapper；若后续确认旧路径无人使用，可继续收缩为纯文档说明


下一步建议：


继续回收根目录 MindSpider/ 兼容壳，优先整理旧 CLI、README 与路径说明对 canonical 目录的映射


2026-04-07 / T-406


任务：T-406

状态：todo -> done

变更：


更新根目录 MindSpider/README.md，明确根目录目录只保留兼容 wrapper、兼容 requirements.txt 与 config.py.example，并写清 canonical 与 legacy 两种入口命令
更新 services/crawler/mindspider/README.md，补充推荐的 repo-root canonical 启动命令，修正重新登录说明、数据库初始化命令与 Python API 导入示例
更新中英文主 README 的目录树，将根目录 MindSpider/ 改写为兼容壳，并新增 services/crawler/mindspider/ 的 canonical 目录说明
在主 README 的“爬虫系统单独使用”章节中补充 canonical 命令与旧兼容命令边界，减少用户继续沿根目录路径误操作


涉及文件：


MindSpider/README.md
services/crawler/mindspider/README.md
README.md
README-EN.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile MindSpider/main.py MindSpider/config.py MindSpider/BroadTopicExtraction/main.py MindSpider/DeepSentimentCrawling/main.py MindSpider/schema/db_manager.py MindSpider/schema/init_database.py services/crawler/mindspider/main.py 通过

git grep -n "from BroadTopicExtraction import BroadTopicExtraction" 复核后，不再由 README 保留旧式导入示例

git grep -n "MindSpider/                             # 社交媒体爬虫系统" 与 git grep -n "MindSpider/                             # Social media crawler system" 复核后，主 README 目录树已切换为兼容壳描述


风险 / 遗留：


根目录 MindSpider/ 仍保留 requirements.txt 与 config.py.example 等兼容文件，尚未彻底缩减为纯 Python wrapper 包

services/crawler/mindspider/main.py 仍有较重运行依赖，本轮只完成了说明与入口边界收口，没有触碰爬虫主逻辑


下一步建议：


评估根目录 MindSpider/requirements.txt 与 config.py.example 是否还有外部使用价值，再决定是否继续压缩为更轻的兼容壳


2026-04-07 / T-407


任务：T-407

状态：todo -> done

变更：


将 MindSpider/config.py.example 从仅含两行注释的占位文件，改为可用的兼容示例入口，明确 canonical 来源并导出 Settings / settings

为 MindSpider/requirements.txt 补充 canonical 路径与推荐安装命令说明，保留旧命令 pip install -r MindSpider/requirements.txt 的兼容行为
更新 MindSpider/README.md，明确 requirements.txt 与 config.py.example 属于“仍保留但推荐直接改用 canonical 路径”的兼容文件


涉及文件：


MindSpider/config.py.example
MindSpider/requirements.txt
MindSpider/README.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile MindSpider/main.py MindSpider/config.py MindSpider/BroadTopicExtraction/main.py MindSpider/DeepSentimentCrawling/main.py MindSpider/schema/db_manager.py MindSpider/schema/init_database.py services/crawler/mindspider/main.py 通过

git grep -n "MindSpider/config.py.example\\|MindSpider/requirements.txt" 复核后，仅剩新的兼容说明与文件自身内容
已人工复核 MindSpider/config.py.example 指向 services.crawler.mindspider.config，MindSpider/requirements.txt 指向 services/crawler/mindspider/requirements.txt


风险 / 遗留：


MindSpider/config.py.example 现在是兼容导出文件，但与 canonical 示例仍存在“双入口”事实，后续仍需决定是否继续保留

MindSpider/requirements.txt 继续保留意味着旧安装命令不会失效，但也意味着根目录兼容壳尚未完全收缩为纯 Python wrapper


下一步建议：


继续评估是否将 MindSpider/config.py.example 与 MindSpider/requirements.txt 冻结为最终兼容入口，或在后续版本中删除


2026-04-07 / T-106


任务：T-106

状态：todo -> done

变更：


将根目录 logs/、final_reports/、insight_engine_streamlit_reports/、media_engine_streamlit_reports/、query_engine_streamlit_reports/、output/ 的历史内容迁入 var/ 下对应 canonical 目录
将仍有参考价值的示例日志归档到 var/logs/archive/legacy-root/20260407/，保留活跃日志、状态文件与任务注册数据在 var/logs/

收口 utils/forum_reader.py 与 services/engines/report/utils/config.py 默认路径，使论坛日志、报告输出与 JSON 修复失败日志默认落到 var/

更新中英文 README、研究 backlog / plan / PRD / memory，以及结构优化任务、记忆、根目录清理清单文档，使根目录轻量旧运行目录状态与新 canonical 路径保持一致


涉及文件：


utils/forum_reader.py
services/engines/report/utils/config.py
README.md
README-EN.md
docs/venue-operations-research-backlog.md
docs/venue-operations-research-platform-plan.md
docs/venue-operations-research-prd.md
docs/venue-operations-research-project-memory.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile utils/forum_reader.py services/engines/report/utils/config.py 通过
已静态确认 DEFAULT_LOG_DIR、OUTPUT_DIR、CHAPTER_OUTPUT_DIR、DOCUMENT_IR_OUTPUT_DIR、LOG_FILE、JSON_ERROR_LOG_DIR 全部切到 var/...

已确认根目录 logs/、final_reports/、insight_engine_streamlit_reports/、media_engine_streamlit_reports/、query_engine_streamlit_reports/、output/ 均已不存在


风险 / 遗留：


轻量目录已迁走，但高风险根目录 crawler_browser_data/ 与 db_data/ 仍保留旧数据
这两类目录不能沿用轻量目录的“直接迁移并删除”策略，必须先确认停进程窗口与冷迁移方案


下一步建议：


执行 T-107，先复核高风险目录的体量、挂载边界和迁移约束，再决定 T-108 的实际迁移动作


2026-04-07 / T-107


任务：T-107

状态：todo -> done

变更：


复核根目录 crawler_browser_data/ 与 db_data/ 的当前体量、文件结构与最近修改时间，确认其分别仍保留 5013 个文件 / 337.49 MB 与 1462 个文件 / 47.78 MB

复核 docker-compose.yml、infra/docker/docker-compose.yml 与 Dockerfile 当前只引用 var/crawler/browser_data 与 var/db/postgres，确认根目录高风险目录已不再是 canonical 运行路径
确认 var/crawler/browser_data/ 与 var/db/postgres/ 当前仅有 .gitkeep，因此高风险问题已经收敛为“旧数据尚未冷迁移”，而不是“代码仍写回根目录”
将高风险目录结论与后续冷迁移步骤写入 docs/project-structure-root-cleanup-inventory.md，并在任务 / memory 文档中建立 T-108 基线


涉及文件：


docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


docker compose -f infra/docker/docker-compose.yml -f infra/docker/docker-compose.override.yml config 通过
已确认 crawler_browser_data/ 顶层包含 bili、dy、ks、tieba、wb、xhs、zhihu 七组浏览器用户目录，其中 dy_user_data_dir 约 194.53 MB

已确认 db_data/ 为完整 PostgreSQL 数据目录，包含 base/、global/、pg_wal/、PG_VERSION 与 postmaster.pid

已确认仓库内对浏览器数据与数据库卷的新路径引用都已指向 var/...


风险 / 遗留：


crawler_browser_data/ 中包含潜在有效登录态与大量浏览器缓存，迁移时需要区分“必须保留的会话数据”和“可丢弃缓存”

db_data/ 是状态性最强的卷目录，必须在停容器窗口下执行冷迁移或先做完整备份


下一步建议：


执行 T-108，在明确停进程窗口后按“备份 -> 冷迁移/归档 -> compose 最小验证 -> 删除根目录旧目录”的顺序推进


2026-04-07 / T-108


任务：T-108

状态：todo -> done

变更：


将根目录 crawler_browser_data/ 与 db_data/ 分别冷备份到 var/backups/runtime-migration/20260407/t108/

将两份高风险运行目录完整复制到 var/crawler/browser_data/ 与 var/db/postgres/，并移除目标目录中的 .gitkeep

在文件数、文件集合与总字节数全部对账通过后，删除根目录 crawler_browser_data/ 与 db_data/

删除仍绑定旧根目录路径的退出容器 bettafish、bettafish-db，再按当前 infra/docker/ compose 配置重建容器


涉及文件：


var/crawler/browser_data/
var/db/postgres/
var/backups/runtime-migration/20260407/t108/crawler_browser_data/
var/backups/runtime-migration/20260407/t108/db_data/
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


已确认源目录、目标目录与冷备份目录在 crawler_browser_data 上均为 5013 个文件，且总字节数完全一致
已确认源目录、目标目录与冷备份目录在 db_data 上均为 1462 个文件，且总字节数完全一致

docker compose -f infra/docker/docker-compose.yml -f infra/docker/docker-compose.override.yml up -d db 后，bettafish-db 健康检查通过
已确认重建后的 bettafish-db 挂载 var/db/postgres，重建后的 bettafish 挂载 var/logs、var/reports/*、var/output 与 var/crawler/browser_data

已确认根目录 crawler_browser_data/ 与 db_data/ 迁移完成后没有被重新创建


风险 / 遗留：


var/backups/runtime-migration/20260407/t108/ 当前保留了一份冷备份，占用额外磁盘空间，后续是否长期保留需要另行决策
浏览器用户目录中的缓存文件仍保留在 var/crawler/browser_data/，当前优先保障登录态不丢失，尚未做体积优化


下一步建议：


执行 T-109，清理仓库里的无用缓存与编译残留，进一步降低工作区噪音


2026-04-07 / T-109


任务：T-109

状态：todo -> done

变更：


全仓删除 __pycache__/ 与 .pytest_cache/，清理 Python 编译缓存与 pytest 运行缓存
共清理 106 个缓存目录，覆盖根目录、apps/、services/、tests/、tools/ 与 vendor/mediacrawler/ 等区域
将缓存清理结果同步写回根目录清理清单、任务文档与记忆文件


涉及文件：


全仓 __pycache__/

.pytest_cache/
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


已确认缓存清理后，不再存在 __pycache__/ 与 .pytest_cache/ 目录
已确认 bettafish 与 bettafish-db 在缓存清理后仍保持运行


风险 / 遗留：


这一步只清理了明确无用的缓存目录，没有触碰业务产物、模型文件、报告输出与运行态备份
后续重新运行测试或脚本时，__pycache__/ 与 .pytest_cache/ 仍会重新生成，需要按需再次清理


下一步建议：


执行 T-110，开始评估根目录剩余兼容壳的删除边界与保留策略


2026-04-08 / T-110


任务：T-110

状态：todo -> done

变更：


新增 utils/compat_shims.py，把根目录兼容包常用的 canonical 路径挂接与惰性导出逻辑收口到共享 helper
将 ForumEngine/、InsightEngine/、MediaEngine/、QueryEngine/、ReportEngine/ 的根目录兼容包统一成更轻的惰性实现，避免包级 eager import 把重型子模块提前拉起
新增 docs/root-compatibility-shim-inventory.md，把根目录兼容壳拆成“可长期冻结的最薄 shim”“目录级兼容壳”“下一轮候选”三类
为 SingleEngineApp/ 补齐 README，明确其仅保留旧 Streamlit 入口 wrapper，不再承载真实控制台实现
新增 tests/unit/test_root_compat_shims.py，验证根目录兼容包的 canonical 路径与惰性导出行为


涉及文件：


utils/compat_shims.py
ForumEngine/__init__.py
InsightEngine/__init__.py
MediaEngine/__init__.py
QueryEngine/__init__.py
ReportEngine/__init__.py
SingleEngineApp/README.md
docs/root-compatibility-shim-inventory.md
tests/unit/test_root_compat_shims.py
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile utils/compat_shims.py ForumEngine/__init__.py InsightEngine/__init__.py MediaEngine/__init__.py QueryEngine/__init__.py ReportEngine/__init__.py 通过

python -m pytest tests/unit/test_root_compat_shims.py -q 通过，结果为 4 passed

已确认 ForumEngine、InsightEngine、MediaEngine、QueryEngine、ReportEngine 的 __all__ 仍保持兼容导出边界


风险 / 遗留：


这一步只收口了“最薄 shim”级别的兼容包，没有删除目录级兼容壳

MindSpider/、根目录 Docker / compose 兼容副本、SentimentAnalysisModel/WeiboMultilingualSentiment/ 仍需继续评估长期留存策略


下一步建议：


执行 T-111，专门判断目录级兼容壳哪些应冻结保留，哪些已经可以进入删除候选


2026-04-08 / T-111


任务：T-111

状态：todo -> done

变更：


以仓内代码、README 与结构文档为依据，完成目录级兼容壳的冻结/删除边界评估
在 docs/root-compatibility-shim-inventory.md 中明确：docker-compose.yml / docker-compose.override.yml / Dockerfile、MindSpider/main.py 系列 wrapper、SentimentAnalysisModel/WeiboMultilingualSentiment/predict.py 进入“冻结保留”
同时明确 Dockerfile.runtime-hotfix、MindSpider/config.py.example、MindSpider/requirements.txt 进入“删除候选”
将结构优化任务文档、记忆文件与根目录清理清单统一切到 T-112 作为下一删除试点任务


涉及文件：


docs/root-compatibility-shim-inventory.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


git grep -n 复核后，MindSpider/config.py.example、MindSpider/requirements.txt 在仓内已无除文件自身与兼容说明外的有效引用

git grep -n 复核后，Dockerfile.runtime-hotfix 在仓内未发现除兼容清单外的有效引用
已确认主 README / 英文 README 仍显式保留 python MindSpider/main.py --status 与 SentimentAnalysisModel/WeiboMultilingualSentiment/predict.py 的兼容说明，因此这两类入口暂不进入删除试点


风险 / 遗留：


“仓内无引用”不等于“外部无人使用”；删除候选仍应在真正删除前再做一次人工确认
根目录 Docker / compose 兼容副本虽然当前主文档已切到 canonical 路径，但仍承接 repo-root 默认命令习惯，短期不宜删除


下一步建议：


执行 T-112，只对已进入删除候选且维护成本最低的兼容文件做最小删除试点


2026-04-08 / T-506


任务：T-506

状态：todo -> done

变更：


为共享配置层新增 .env.local 优先级与 BETTAFISH_ENV_FILE 显式覆盖支持，源码启动不再只能依赖根目录 .env

新增纯本地启动脚本 scripts/dev/start_local.py，负责本地环境文件选择、基础校验、可选前端构建与统一启动 apps.web_api

新增 .env.local.example 作为纯本地默认模板，并在 .env.example 中补充 .env / .env.local 双轨说明
将主 README / 英文 README 的默认推荐启动方式切到纯本地；Docker 保留为可选兼容模式
更新前端 fallback 页提示，默认指向 apps/web_ui 与本地启动脚本，而不是旧 frontend/ 路径
在本轮验证后再次清理仓库内新生成的 __pycache__/ 与 .pytest_cache/，避免缓存残留重新污染目录状态


涉及文件：


services/shared/config/base.py
services/shared/config/__init__.py
config.py
.gitignore
.dockerignore
.env.example
.env.local.example
scripts/dev/__init__.py
scripts/dev/start_local.py
tests/unit/shared/test_env_resolution.py
templates/index.html
README.md
README-EN.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md
docs/project-structure-root-cleanup-inventory.md


验证：


python -m scripts.dev.start_local --help 通过
已通过临时实验确认 pydantic-settings 对多 env 文件采用“后者覆盖前者”策略，因此当前 .env -> .env.local 的优先级设计成立
已补充 tests/unit/shared/test_env_resolution.py 覆盖 env 文件候选顺序、显式 env 路径解析与本地覆盖优先行为
已确认本轮验证后新生成的 __pycache__/ 与 .pytest_cache/ 已再次删除


风险 / 遗留：


纯本地模式仍依赖用户自行准备本机 PostgreSQL / MySQL 与可用的模型 API 配置，不属于脚本自动托管范围
Docker 兼容链路虽然仍保留，但当前这一步没有进一步清理根目录 Docker 兼容副本，后续仍应回到 T-112


下一步建议：


回到结构清理主线，执行 T-112


2026-04-08 / T-112


任务：T-112

状态：todo -> done

变更：


删除根目录低风险兼容文件 Dockerfile.runtime-hotfix

删除根目录 MindSpider/ 下已不再需要的兼容文件 config.py.example 与 requirements.txt

复核当前空目录后确认，本轮扫描出的空目录均位于 var/ 运行时数据与冷备份内部，不属于可直接删除的源码树垃圾
将任务文档、记忆文件、根目录清理清单与兼容壳清单同步切到删除后的最新状态


涉及文件：


Dockerfile.runtime-hotfix
MindSpider/config.py.example
MindSpider/requirements.txt
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md
docs/project-structure-root-cleanup-inventory.md
docs/root-compatibility-shim-inventory.md


验证：


git grep -n "Dockerfile.runtime-hotfix\\|MindSpider/config.py.example\\|MindSpider/requirements.txt" 已无匹配结果
已人工复核 MindSpider/ 目录当前仍保留 main.py、config.py、README 与子目录 wrapper，兼容 CLI 不受本轮删除影响
已人工复核空目录扫描结果，本轮未发现新的源码树空垃圾目录；扫描命中的均为 var/ 下运行时/冷备份内部目录


风险 / 遗留：


若外部私有脚本仍硬编码这三个已删除文件，需要改为 canonical 路径 infra/docker/Dockerfile.runtime-hotfix 与 services/crawler/mindspider/requirements.txt


var/backups/runtime-migration/20260407/t108/ 仍保留完整冷备份，占用磁盘空间，但当前不应未经评估直接删除


下一步建议：


执行 T-113，专门评估冷备份与运行时空目录的保留窗口


2026-04-08 / T-113


任务：T-113

状态：todo -> done

变更：


统计 var/backups/runtime-migration/20260407/t108/、var/crawler/browser_data/、var/db/postgres/、var/output/、var/reports/final/、var/logs/ 的文件数、体积与空目录分布
新增 docs/runtime-retention-assessment.md，将运行时目录划分为“必须保留的冷备份”“必须保留的结构性空目录”“可控回收候选”
明确 var/output/chrome-headless/ 是当前更适合后续空间回收的 scratch 候选，而 db/postgres/、crawler/browser_data/ 与 t108 冷备份不应直接删除


涉及文件：


docs/runtime-retention-assessment.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md
docs/project-structure-root-cleanup-inventory.md
docs/root-compatibility-shim-inventory.md


验证：


已统计 t108 冷备份为 6475 个文件、385.27 MB

已统计 var/output/ 为 358 个文件、18.50 MB，其中包含 57 个空目录
尝试执行 docker ps -a 时确认本机 Docker daemon 当前不可用，因此本轮结论不依赖容器在线状态


风险 / 遗留：


运行时空间回收仍是高风险动作，尤其是 var/backups/runtime-migration/20260407/t108/、var/db/postgres/ 与 var/crawler/browser_data/

若要进一步回收空间，必须先定义停进程条件、回滚窗口和验证步骤


下一步建议：


执行 T-114，制定并在明确前置条件后执行受控运行时空间回收


9. 下一次执行任务后的更新模板

后续每完成一个任务，请至少按以下格式更新：


2026-04-08 / T-507


任务：T-507

状态：todo -> done

变更：


在本机 Conda Python 3.13 环境下补齐纯本地启动最小依赖，绕过 Pillow==9.5.0 在 Python 3.13 上无法直接安装的问题。
修复 services/crawler/mindspider/main.py 的裸 import config 导入污染问题，避免 backend/crawler 误读到爬虫侧 config.py。
将 services/crawler/mindspider/main.py、services/crawler/mindspider/schema/init_database.py、services/engines/insight/utils/db.py 中的 PostgreSQL 异步驱动从 asyncpg 调整为 psycopg，提升 Python 3.13 兼容性。


影响文件：


services/crawler/mindspider/main.py
services/crawler/mindspider/schema/init_database.py
services/engines/insight/utils/db.py
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


关键决策：


纯本地启动兼容问题优先通过“修正驱动与导入边界”解决，而不是继续依赖 Docker 兜底。
当前目标先确保主站 Web 入口稳定可启动；本地 PostgreSQL 常驻服务的补齐属于后续端到端研究链路收口项。


验证：


运行 python -X utf8 -m scripts.dev.start_local --env-file .env.local 时，进程不再导入即崩溃，而是进入持续运行态。

Get-NetTCPConnection -LocalPort 5000 -State Listen 验证到 127.0.0.1:5000 正在监听。

Invoke-WebRequest http://127.0.0.1:5000 返回 200。

Invoke-WebRequest http://127.0.0.1:5000/api/research/options 返回 success: true 的 JSON 结果。


遗留问题：


本机当前仍未启动本地 PostgreSQL 服务，因此“主站可启动”并不等于全部研究/爬虫链路已端到端打通。
运行时空间回收任务 T-114 仍未执行。


下一步建议：


结构优化主线继续执行 T-114。
若以纯本地可用性为优先目标，则在下一轮补齐本地 PostgreSQL 服务与相关启动脚本。


2026-04-08 / T-508


任务：T-508

状态：todo -> done

变更：


新增 infra/python/requirements-local.txt，把纯本地主站启动所需的 runtime 依赖从根 requirements.txt 中收口出来，避免首次启动被训练/研究依赖和旧版编译链阻塞。
新增 scripts/dev/bootstrap_local.py，统一执行本地 Python 依赖、Playwright Chromium 与前端依赖准备。
调整 requirements.txt 中默认 PostgreSQL 驱动与 Pillow 约束，移除主仓库默认本地路径对 asyncpg 的继续依赖，并将 Pillow 放宽到 Python 3.13 可安装范围。
更新 README.md 与 README-EN.md 的纯本地启动说明，把 bootstrap 入口纳入默认步骤。


影响文件：


infra/python/requirements-local.txt
scripts/dev/bootstrap_local.py
requirements.txt
README.md
README-EN.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


关键决策：


纯本地启动依赖不再强行复用根 requirements.txt，而是通过独立 runtime 清单收口到“可本地启动主站”的最小可复现集合。
对 Python 3.13 的兼容收口优先围绕当前主站启动链路，而不是要求研究/训练全量依赖立刻全部跟上。


验证：


python -m py_compile scripts/dev/bootstrap_local.py scripts/dev/start_local.py 通过。

python -m scripts.dev.bootstrap_local --help 通过。

python -m scripts.dev.bootstrap_local --dry-run --skip-pip-tools-upgrade 通过。

python -m pip install --dry-run -r infra/python/requirements-local.txt 通过。

Get-NetTCPConnection -LocalPort 5000 -State Listen 确认 127.0.0.1:5000 仍在监听，当前监听进程命令行为 python.exe -m apps.web_api。

Invoke-WebRequest http://127.0.0.1:5000 返回 200。

Invoke-RestMethod http://127.0.0.1:5000/api/research/options 返回 success: true。


风险 / 遗留：


根 requirements.txt 仍代表“全仓库/全能力”依赖集合，并不等价于“Python 3.13 下完整无编译安装”；当前收口的是纯本地主站启动链路。
本地 PostgreSQL 常驻服务尚未补齐，因此 bootstrap 和主站可启动并不等于完整研究链路已经端到端可用。


下一步建议：


如果优先继续提升本地可用性，则补齐本地 PostgreSQL 服务并验证一条最小研究链路。
如果优先继续仓库清理主线，则执行 T-114 受控空间回收。


2026-04-09 / T-509


任务：T-509

状态：todo -> done

变更：


重写 scripts/dev/start_local_stack.ps1，建立纯 ASCII 的 Windows 一键启动脚本，统一处理 .env.local / .env 选择、缺依赖时的 bootstrap_local、前端依赖检查、5000 端口复用与 PostgreSQL 预检。
重写根目录 start_local.bat，作为 Windows 双击或命令行便捷入口；实际启动逻辑继续收口在 scripts/dev/。
更新 README.md 与 README-EN.md，补充 Windows 一键启动方式、脚本行为与 PostgreSQL 预警说明。


影响文件：


scripts/dev/start_local_stack.ps1
start_local.bat
README.md
README-EN.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


关键决策：


根目录允许保留极薄的用户向启动入口，但真实逻辑必须继续集中在 scripts/dev/，避免再次把装配逻辑散回根目录。
一键启动脚本在本地 PostgreSQL 未监听时只发出明确预警，不直接阻塞 Web 主站启动；数据库链路可用性作为后续独立收口项处理。


验证：


powershell -ExecutionPolicy Bypass -NoProfile -File scripts/dev/start_local_stack.ps1 -SkipPlaywright 通过。

cmd /c start_local.bat -SkipPlaywright 通过。

Invoke-WebRequest http://127.0.0.1:5000 返回 200。

Invoke-RestMethod http://127.0.0.1:5000/api/research/options 返回 success: true。

Get-NetTCPConnection -LocalPort 5432 -State Listen 确认当前机器没有本地 PostgreSQL 监听，预警分支已被实际覆盖。


风险 / 遗留：


当前一键启动链路仍依赖系统 PATH 中存在可用的 python。

127.0.0.1:5432 仍未监听，说明研究链路尚未进入“纯本地端到端就绪”状态。


下一步建议：


如果继续优先提升纯本地体验，则补齐本地 PostgreSQL 常驻服务或等价替代方案。
如果继续推进仓库收尾清理，则执行 T-114 受控空间回收。


2026-04-09 / T-510


任务：T-510

状态：todo -> done

变更：


新增 scripts/dev/prepare_local_postgres.py，统一处理 .env.local / .env 读取、PostgreSQL 本地配置校验、TCP 连通性检测、目标数据库探测、可选 CREATE DATABASE 与 schema 初始化。
更新 scripts/dev/start_local_stack.ps1，让 Windows 一键启动脚本在 PostgreSQL 未监听时直接提示 python -m scripts.dev.prepare_local_postgres --check-only。
更新 README.md 与 README-EN.md，把 PostgreSQL 的诊断、建库和 schema 初始化命令纳入纯本地默认工作流。
修正 services/shared/config/app_settings.py 中 DB_DIALECT=postgresql 但 DB_PORT 仍默认为 3306 的不一致问题，将默认端口统一为 5432。


影响文件：


scripts/dev/prepare_local_postgres.py
scripts/dev/start_local_stack.ps1
services/shared/config/app_settings.py
README.md
README-EN.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile scripts/dev/prepare_local_postgres.py services/shared/config/app_settings.py
python -m scripts.dev.prepare_local_postgres --help
python -m scripts.dev.prepare_local_postgres --check-only


风险 / 遗留：


当前仓库内脚本已经能明确指向“下一步怎么做”，但它不会替代系统层面的 PostgreSQL 安装与服务注册。
当前机器如果仍未监听 127.0.0.1:5432，--check-only 会按预期失败；这属于环境未就绪，而不是仓库脚本链路缺失。


下一步建议：


如果继续优先提升纯本地体验，则在本机安装并启动 PostgreSQL 后执行 python -m scripts.dev.prepare_local_postgres --ensure-db --apply-schema。
如果继续推进仓库收尾清理，则执行 T-114 受控空间回收。


2026-04-09 / T-511


任务：T-511

状态：todo -> done

变更：


将仓库内容从旧根目录 BettaFish/ 整体上移到上级目录，移除多余的单层包装目录。
将 Git 仓库根路径切换为 d:\工作\APP\AI-Agent-Platform，后续所有本地启动、脚本执行与文档引用均以该目录为 canonical workspace root。
在迁移过程中终止仍持有旧目录句柄的本地启动残留进程，并保留已有本地启动日志到 var/logs/ 便于继续排查。


涉及文件：


docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md
var/logs/t509-start-local-stdout.log
var/logs/t509-start-local-stderr.log


验证：


git rev-parse --show-toplevel 返回 D:/工作/APP/AI-Agent-Platform。

Test-Path .\BettaFish 返回 False，确认旧外层目录已移除。
迁移后旧启动日志仍保留在 var/logs/ 下，可继续用于本地启动诊断。


风险 / 遗留：


结构追踪文档中的历史绝对路径仍保留旧的 ...\BettaFish\... 记录，语义上属于历史快照，不代表当前 canonical 路径。
迁移时为释放旧目录句柄已停止本地启动进程，如需继续联调，需要从新根目录重新启动。


下一步建议：


从新根目录执行 powershell -ExecutionPolicy Bypass -NoProfile -File scripts/dev/start_local_stack.ps1 -SkipPlaywright，验证扁平化后的本地启动链路。
后续新增或修正文档时，统一把绝对路径写为 d:\工作\APP\AI-Agent-Platform\...，不再使用 ...\BettaFish\...。


2026-04-09 / T-512


任务：T-512

状态：todo -> done

变更：


从新的仓库根目录 d:\工作\APP\AI-Agent-Platform 重新执行 scripts/dev/start_local_stack.ps1 -SkipPlaywright，验证扁平化后的纯本地启动链路。
新增本轮启动日志 var/logs/t511-start-local-stdout.log 与 var/logs/t511-start-local-stderr.log，用于记录迁移后的首次重启结果。
确认启动脚本已正确读取新根目录下的 .env.local，并将 Web 主站拉起到 http://127.0.0.1:5000。


涉及文件：


docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md
var/logs/t511-start-local-stdout.log
var/logs/t511-start-local-stderr.log


验证：


Get-NetTCPConnection -LocalPort 5000 -State Listen 显示 127.0.0.1:5000 正在监听。

Invoke-WebRequest http://127.0.0.1:5000 返回 200。
启动日志显示 Repo root: D:\工作\APP\AI-Agent-Platform 与 Using env file: D:\工作\APP\AI-Agent-Platform\.env.local。


风险 / 遗留：


启动日志中仍有 WeasyPrint 未安装与 Scipy 未安装的警告，但不影响当前 Web 主站启动。
当前环境依旧存在 Conda PowerShell 激活输出的编码异常噪声，虽然不阻断主流程，但会污染终端输出。


下一步建议：


如果继续补齐纯本地能力，下一步执行 python -m scripts.dev.prepare_local_postgres --check-only 或在 PostgreSQL 就绪后执行 --ensure-db --apply-schema。
如果继续推进结构清理，可单独整理 README / 文档中仍以 BettaFish/ 作为目录树展示的说明文本。


2026-04-09 / T-513


任务：T-513

状态：todo -> done

变更：


对本机 PostgreSQL 安装完成后的纯本地数据库链路进行复验，确认 Windows 服务 postgresql-x64-15 正在运行，且 5432 端口处于监听状态。
运行 python -m scripts.dev.prepare_local_postgres --check-only，确认当前阻塞点不是安装缺失，而是 .env.local 中应用账号 bettafish 的认证失败。
加固 scripts/dev/prepare_local_postgres.py：补充 Windows 非 UTF-8 终端下的安全输出处理，并将认证失败与一般连接失败区分开，避免再次被 UnicodeEncodeError 截断或给出误导性的“缺库”提示。


涉及文件：


scripts/dev/prepare_local_postgres.py
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


Get-Service *postgres* 显示 postgresql-x64-15 为 Running。

Get-NetTCPConnection -LocalPort 5432 -State Listen 确认本机 5432 正在监听。

python -m py_compile scripts/dev/prepare_local_postgres.py 通过。

python -m scripts.dev.prepare_local_postgres --check-only 现在能稳定输出认证失败提示，不再因中文/GBK 输出崩溃。


风险 / 遗留：


当前 .env.local 中的 DB_USER / DB_PASSWORD 与本机 PostgreSQL 中的实际角色凭据未对齐，因此仓库脚本暂时无法继续建库或执行 schema 初始化。
在认证问题解决之前，python -m scripts.dev.prepare_local_postgres --ensure-db --apply-schema 不应继续执行，否则只会在同一凭据层面失败。


下一步建议：


将本机 PostgreSQL 中的 bettafish 用户密码调整为与 .env.local 一致，或反向把 .env.local 的 DB_PASSWORD 改为本机实际密码后，再重新执行 python -m scripts.dev.prepare_local_postgres --check-only。
认证通过后，再执行 python -m scripts.dev.prepare_local_postgres --ensure-db --apply-schema 完成建库与 schema 初始化。


2026-04-09 / T-514


任务：T-514

状态：todo -> done

变更：


对系统级 PostgreSQL 认证阻塞执行了一轮直接修复尝试：定位到实际 pg_hba.conf 位于 D:\Program Files\PostgreSQL\15\data\pg_hba.conf，并为该文件创建了备份 var/backups/postgres/t514/pg_hba.conf.bak。
尝试通过临时放宽本地回环认证策略来重置 bettafish 角色密码，但在当前用户权限下无法成功执行 pg_ctl reload 或 Restart-Service postgresql-x64-15。
已确认修复尝试结束后 pg_hba.conf 已恢复到 scram-sha-256 配置，系统 5432 实例未被留在不安全状态。


涉及文件：


docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md
var/backups/postgres/t514/pg_hba.conf.bak


验证：


Get-Service *postgres* 显示 postgresql-x64-15 仍为 Running。

Get-NetTCPConnection -LocalPort 5432 -State Listen 确认系统 PostgreSQL 仍在监听。
复核 D:\Program Files\PostgreSQL\15\data\pg_hba.conf，确认本地回环认证已恢复为 scram-sha-256。


风险 / 遗留：


当前用户仍无法直接接管系统 PostgreSQL 服务重载 / 重启，因此“修改系统实例认证策略再回改”的路径不适合作为默认自动修复方案。
系统 5432 实例的超级用户密码仍未知，不适合继续把“拿到管理员凭据”作为唯一收口前提。


下一步建议：


转向项目自管的本地 PostgreSQL 实例方案，在不碰系统服务密码的前提下打通纯本地数据库链路。


2026-04-09 / T-515


任务：T-515

状态：todo -> done

变更：


新增 scripts/dev/repair_local_postgres.py，用于在系统 5432 实例不可用或认证失败时，自动创建并拉起仓库内的项目自管 PostgreSQL 实例。
将项目自管实例数据目录固定到 var/db/postgres-local/，日志固定到 var/logs/postgres-local.log，并在首次修复时把 .env.local 自动切换到 DB_PORT=55432。
更新 scripts/dev/start_local.py，让纯本地 Python 启动入口具备 PostgreSQL 自修复能力；更新 scripts/dev/start_local_stack.ps1，移除旧的静态 5432 预警逻辑，转而复用 Python 入口里的修复链路。
加固 scripts/dev/prepare_local_postgres.py，补齐本地化“数据库不存在”场景下的维护库回退建库逻辑，并修正 schema 初始化时的 PYTHONPATH / 工作目录问题。
修复 services/crawler/mindspider/schema/init_database.py 在 Windows 下使用 psycopg 异步驱动时与 ProactorEventLoop 不兼容的问题，切换到 WindowsSelectorEventLoopPolicy。
更新 .env.local.example、README.md 与 README-EN.md，把“项目自管 PostgreSQL 修复入口”写入纯本地默认工作流说明。


涉及文件：


scripts/dev/repair_local_postgres.py
scripts/dev/start_local.py
scripts/dev/start_local_stack.ps1
scripts/dev/prepare_local_postgres.py
services/crawler/mindspider/schema/init_database.py
.env.local.example
README.md
README-EN.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md
var/db/postgres-local/
var/logs/postgres-local.log
var/logs/t515-start-local-stdout.log
var/logs/t515-start-local-stderr.log


验证：


python -m scripts.dev.prepare_local_postgres --env-file .env.local --ensure-db --apply-schema 通过。

python -m scripts.dev.prepare_local_postgres --check-only 通过。

python -m scripts.dev.repair_local_postgres 通过，并确认当前数据库目标为 127.0.0.1:55432。

psql -h 127.0.0.1 -p 55432 -U bettafish -d bettafish -c "\dt" 可列出初始化后的 26 张表。
通过 scripts/dev/start_local_stack.ps1 -SkipPlaywright 重新拉起主站，http://127.0.0.1:5000 返回 200，/api/research/options 返回 success: true。


风险 / 遗留：


当前项目已不再依赖系统 5432 实例的管理员密码，但系统 PostgreSQL 服务本身仍保留在机器上；后续若用户主动修复系统实例，可自行决定是否切回 5432。
启动日志中仍有 WeasyPrint 与 Scipy 缺失告警，以及 Conda PowerShell 编码噪声；这些不影响当前主站与数据库链路可用性。


下一步建议：


如需继续优化纯本地体验，可单独收口 Conda 编码噪声与非阻塞依赖告警。
如需继续推进结构清理，转入 T-114 受控空间回收。


2026-04-09 / T-516


任务：T-516

状态：todo -> done

变更：


重新审计当前仓库的一级目录与主功能边界，确认当前 canonical 结构已以 apps/、services/、backend/、scripts/、tools/、infra/、research/、vendor/、tests/、utils/、var/ 为主。
更新 README.md，新增“当前代码结构（截至 2026-04-09）”“当前功能分层说明”“推荐入口与职责边界”“兼容目录说明”四个主说明块。
将旧的“项目代码结构树”显式降级为“历史目录树（已过时，仅供兼容背景参考）”，避免继续把历史根目录布局误读为当前开发入口。
补充 .env.local.example 默认 5432 与 repair_local_postgres 自动切换到 55432 的关系说明，保证结构说明与当前本地启动链路一致。


涉及文件：


README.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


Select-String -Path README.md -Pattern "当前代码结构（截至 2026-04-09）|当前功能分层说明|推荐入口与职责边界|历史目录树（已过时，仅供兼容背景参考）"
手工复核 README.md 中的结构说明与当前仓库目录实际一致


风险 / 遗留：


README 中历史目录树正文仍然保留，当前只是降级为历史参考；若后续继续压缩文档体积，可单独裁剪整段旧树。

README-EN.md 尚未同步本轮中文结构重写；如需中英文一致，需要在后续单独补齐。


下一步建议：


继续清理 README 中仍然混合新旧路径的说明段落，逐步把兼容层信息压缩到更短的参考说明。


2026-04-09 / T-517


任务：T-517

状态：todo -> done

变更：


清理根目录历史兼容包目录与兼容 CLI 目录：QueryEngine/、MediaEngine/、InsightEngine/、ReportEngine/、ForumEngine/、MindSpider/、frontend/、SingleEngineApp/、SentimentAnalysisModel/。
删除与这些兼容包配套的共享 shim helper utils/compat_shims.py，以及专门验证兼容包存在性的测试 tests/unit/test_root_compat_shims.py。
更新 README.md、README-EN.md、apps/*.md、services/*/README.md、research/README.md、docs/root-compatibility-shim-inventory.md 等说明文档，将结构表述切换到当前 canonical 目录，不再继续宣称旧兼容目录可用。
清理 .gitignore、.dockerignore 和 PDF 导出说明中的旧目录路径，统一改为当前 research/、services/、apps/ 路径。


涉及文件：


README.md
README-EN.md
.gitignore
.dockerignore
apps/README.md
apps/web_api/README.md
apps/web_ui/README.md
apps/engine_console/README.md
services/engines/README.md
services/crawler/README.md
research/README.md
docs/root-compatibility-shim-inventory.md
docs/project-structure-root-cleanup-inventory.md
tests/unit/test_root_compat_shims.py
utils/compat_shims.py


验证：


git grep -n "compat_shims\\|QueryEngine\\|MediaEngine\\|InsightEngine\\|ReportEngine\\|ForumEngine\\|MindSpider\\|SingleEngineApp\\|SentimentAnalysisModel" -- '*.py' ':!README.md' ':!README-EN.md' ':!docs/**' ':!static/**' 无结果

python -m pytest tests/unit/shared/test_env_resolution.py tests/unit/report/test_json_parser.py tests/unit/insight/test_sentiment_analyzer_paths.py -q 通过（24 passed）
手工复核仓库顶层目录，确认上述历史兼容目录已不再存在


风险 / 遗留：


所有基于旧目录的外部脚本、旧 import 路径与旧 CLI 命令将不再可用；当前假设是仓库内部和后续维护都已接受切换到 canonical 目录。
README 中仍保留部分历史目录树作为迁移背景参考，后续若继续压缩文档体积，可单独删除这部分历史正文。


下一步建议：


继续清理根目录仍然保留的文件级兼容入口，优先评估 app.py、crawler_web.py、Dockerfile、docker-compose*.yml 是否还需要长期保留。


2026-04-09 / T-518


任务：T-518

状态：todo -> done

变更：


将 README.md 与 README-EN.md 中的大段历史目录树替换为精简迁移说明，避免继续在主文档中展示已删除的根目录兼容包目录。
更新 docs/project-structure-optimization-memory.md 顶部稳定事实与“当前推荐下一步”，补齐 T-517 记录并把当前仓库状态校准到目录级兼容壳已移除后的版本。
清理仓库源码树中的 .pytest_cache/ 与多处 __pycache__/，减少顶层和代码目录噪音。


涉及文件：


README.md
README-EN.md
docs/project-structure-optimization-memory.md
源码树中的 .pytest_cache/ 与 __pycache__/


验证：


手工复核 README.md 与 README-EN.md，确认主文档不再内嵌已删除兼容目录的大段历史树。

Get-ChildItem -Path . -Directory -Force | Where-Object { $_.Name -eq '.pytest_cache' } 无结果

Get-ChildItem apps,backend,scripts,services,tests,utils -Recurse -Directory -Force | Where-Object { $_.Name -eq '__pycache__' } 无结果


风险 / 遗留：


根目录仍保留少量文件级兼容入口，尚未进入本轮删除范围。

var/ 下的 scratch / 下载目录仍需按 T-114 做受控回收，不能简单按缓存统一删除。


下一步建议：


继续评估 app.py、config.py、crawler_web.py、openai_compat.py、Dockerfile、docker-compose*.yml 的长期保留必要性。


2026-04-09 / T-519


任务：T-519

状态：todo -> done

变更：


修正 services/engines/report/ 内部残留的 ReportEngine 旧导入、硬编码路径与命令示例，统一切到 services.engines.report canonical 路径。
修正 services/engines/report/scripts/ 的路径引导逻辑与文案示例，使其从 canonical 包入口运行时不再依赖根目录兼容包。
修正报告模板目录默认值，不再硬编码已删除的 ReportEngine/report_template 路径。
删除根目录 report_engine_only.py、regenerate_latest_html.py、regenerate_latest_md.py、regenerate_latest_pdf.py、export_pdf.py 五个报告类兼容 wrapper。
更新 README.md、README-EN.md、tools/reports/README.md、docs/root-compatibility-shim-inventory.md 与 docs/project-structure-root-cleanup-inventory.md，统一把用户指令改为 python -m tools.reports.*。
清理本轮验证产生的 services/engines/report/ 与 tools/reports/ 下 __pycache__/ 目录，避免缓存重新进入源码树。


涉及文件：


services/engines/report/renderers/html_renderer.py
services/engines/report/renderers/markdown_renderer.py
services/engines/report/renderers/pdf_renderer.py
services/engines/report/utils/chart_repair_api.py
services/engines/report/utils/chart_review_service.py
services/engines/report/scripts/export_to_pdf.py
services/engines/report/scripts/generate_all_blocks_demo.py
services/engines/report/scripts/validate_ir.py
services/engines/report/nodes/template_selection_node.py
services/engines/report/utils/config.py
services/engines/report/utils/dependency_check.py
services/engines/report/README.md
README.md
README-EN.md
tools/reports/README.md
tools/reports/report_engine_only.py
docs/root-compatibility-shim-inventory.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-memory.md
docs/project-structure-optimization-tasks.md


验证：


python -m py_compile services/engines/report/renderers/html_renderer.py services/engines/report/renderers/markdown_renderer.py services/engines/report/renderers/pdf_renderer.py services/engines/report/utils/chart_repair_api.py services/engines/report/utils/chart_review_service.py services/engines/report/scripts/export_to_pdf.py services/engines/report/scripts/generate_all_blocks_demo.py services/engines/report/scripts/validate_ir.py tools/reports/export_pdf.py tools/reports/report_engine_only.py 通过。

python -m tools.reports.export_pdf --help 通过。

python -m tools.reports.report_engine_only --help 通过。

Select-String -Path (Get-ChildItem services/engines/report,tools/reports -Recurse -File | Select-Object -ExpandProperty FullName) -Pattern 'ReportEngine/report_template|python -m ReportEngine|ReportEngine/scripts/' 无结果。
已确认根目录 report_engine_only.py、regenerate_latest_html.py、regenerate_latest_md.py、regenerate_latest_pdf.py、export_pdf.py 均已删除。


风险 / 遗留：


可选依赖 WeasyPrint、Scipy 仍可能在报告工具 help / import 验证时输出非阻塞告警。
根目录仍保留少量高兼容价值文件入口，后续若继续清理，应优先评估 app.py、crawler_web.py、Dockerfile 与 docker-compose*.yml。


下一步建议：


结构清理主线继续执行 T-114 受控空间回收。
继续评估剩余根级文件兼容入口的保留与删除边界。


2026-04-09 / T-520


任务：T-520

状态：todo -> done

变更：


删除根目录低价值兼容 shim：config.py、crawler_web.py、openai_compat.py。
更新 README.md、README-EN.md 中的当前结构说明、配置说明和示例代码，移除对根目录 config.py / crawler_web.py 的推荐描述。
更新 docs/root-compatibility-shim-inventory.md、docs/project-structure-root-cleanup-inventory.md、services/shared/config/README.md、docs/project-structure-optimization-memory.md，让“当前保留的根级兼容入口”与实际仓库状态对齐。
修复删除 shim 后暴露出的运行时导入残留，把 backend/、apps/、services/engines/ 与 services/crawler/mindspider/ 中仍依赖根级 config / openai_compat 的模块统一切到 canonical 导入路径。


涉及文件：


backend/config_admin.py
backend/crawler/routes.py
backend/crawler/runtime.py
backend/crawler/managers.py
services/engines/forum/llm_host.py
services/engines/report/llms/base.py
services/engines/query/llms/base.py
services/engines/media/llms/base.py
services/engines/media/tools/search.py
services/engines/insight/llms/base.py
services/engines/insight/tools/keyword_optimizer.py
services/engines/insight/tools/sentiment_analyzer.py
services/crawler/mindspider/main.py
services/crawler/mindspider/BroadTopicExtraction/database_manager.py
services/crawler/mindspider/BroadTopicExtraction/topic_extractor.py
services/crawler/mindspider/DeepSentimentCrawling/keyword_manager.py
services/crawler/mindspider/DeepSentimentCrawling/platform_crawler.py
services/crawler/mindspider/schema/db_manager.py
services/crawler/mindspider/schema/init_database.py
apps/engine_console/insight_engine_streamlit_app.py
apps/engine_console/media_engine_streamlit_app.py
apps/engine_console/query_engine_streamlit_app.py
apps/web_api/app.py
README.md
README-EN.md
docs/root-compatibility-shim-inventory.md
docs/project-structure-root-cleanup-inventory.md
services/shared/config/README.md
docs/project-structure-optimization-memory.md
docs/project-structure-optimization-tasks.md
已删除：config.py

已删除：crawler_web.py

已删除：openai_compat.py


验证：


基于 Python 脚本的全仓扫描已确认源码树内不存在真实的 from config import、import config、from openai_compat import、import openai_compat、from crawler_web import 或 import crawler_web 语句。

python -m py_compile services/shared/config/app_settings.py utils/openai_compat.py backend/config_admin.py backend/crawler/__init__.py backend/crawler/managers.py backend/crawler/routes.py backend/crawler/runtime.py services/crawler/mindspider/main.py services/crawler/mindspider/BroadTopicExtraction/database_manager.py services/crawler/mindspider/BroadTopicExtraction/topic_extractor.py services/crawler/mindspider/DeepSentimentCrawling/keyword_manager.py services/crawler/mindspider/DeepSentimentCrawling/platform_crawler.py services/crawler/mindspider/schema/db_manager.py services/crawler/mindspider/schema/init_database.py services/engines/forum/llm_host.py services/engines/report/llms/base.py services/engines/query/llms/base.py services/engines/media/llms/base.py services/engines/media/tools/search.py services/engines/insight/llms/base.py services/engines/insight/tools/keyword_optimizer.py services/engines/insight/tools/sentiment_analyzer.py apps/engine_console/insight_engine_streamlit_app.py apps/engine_console/media_engine_streamlit_app.py apps/engine_console/query_engine_streamlit_app.py apps/web_api/app.py 通过。
运行时导入验证通过：services.shared.config、utils.openai_compat、backend.crawler 与 apps.web_api.app 当前均可成功 import。
已确认根目录 config.py、crawler_web.py、openai_compat.py 不再存在。


风险 / 遗留：


历史仓外脚本如果仍直接依赖这三个根级 shim，将需要切换到 canonical 导入路径。
根目录仍保留 app.py、start_local.bat、Dockerfile 与 docker-compose*.yml 等少量高兼容价值入口，后续仍需继续评估。


下一步建议：


结构清理主线继续执行 T-114 受控运行时空间回收。
或继续评估剩余根级文件兼容入口的长期保留边界。


2026-04-09 / T-114


任务：T-114

状态：todo -> done

变更：


复核当前 5000 端口仍由 python -m apps.web_api 提供主站服务，scripts.dev.start_local 监控进程也仍在运行，因此本轮空间回收不采用停服策略。
复核活跃 Chrome / Playwright 进程的命令行后，确认它们使用的是用户目录下的 ms-playwright profile，而不是仓内 var/output/chrome-headless/。
删除 var/output/chrome-headless/ 整棵 scratch 子树，保留 var/output/screens/ 与 .gitkeep。
更新 docs/runtime-retention-assessment.md、docs/project-structure-root-cleanup-inventory.md、docs/project-structure-optimization-memory.md 与本任务文档，使回收前置条件、执行结果和当前体积数据一致。


涉及文件：


var/output/chrome-headless/（已删除）
docs/runtime-retention-assessment.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-memory.md
docs/project-structure-optimization-tasks.md


验证：


Get-CimInstance Win32_Process 已确认 20288 为 python -m apps.web_api、56300 为 python -m scripts.dev.start_local --env-file ...\\.env.local。

Get-CimInstance Win32_Process 已确认活跃 Chrome / Playwright 进程使用的 --user-data-dir 位于 C:\\Users\\wanzh\\AppData\\Local\\ms-playwright\\...，而非仓内 var/output/chrome-headless/。

Test-Path var/output/chrome-headless 返回 False。
目录统计已确认 var/output/ 当前为 4 个文件、1 个目录、0 个空目录，约 2.49 MB。


风险 / 遗留：


var/backups/runtime-migration/20260407/t108/、var/crawler/browser_data/ 与 var/db/postgres/ 仍属于高价值运行态/冷备份目录，不在本轮清理范围。
若后续再次生成 chrome-headless 类 scratch 目录，仍需先复核活跃进程实际使用的 profile 路径，再决定是否回收。


下一步建议：


继续评估根级文件入口的最终保留边界，优先判断 app.py 是否仍需长期保留。


2026-04-09 / T-521


任务：T-521

状态：todo -> done

变更：


删除根目录 Dockerfile、docker-compose.yml 与 docker-compose.override.yml 三个 Docker / compose 兼容副本。
更新 README.md 与 README-EN.md，把 Docker 启动说明统一收口为只使用 infra/docker/ 下的 canonical 文件。
更新 docs/root-compatibility-shim-inventory.md、docs/project-structure-root-cleanup-inventory.md、docs/project-structure-optimization-memory.md 与本任务文档，移除“根目录 Docker 兼容副本仍保留”的过时表述。


涉及文件：


Dockerfile（已删除）

docker-compose.yml（已删除）

docker-compose.override.yml（已删除）
README.md
README-EN.md
docs/root-compatibility-shim-inventory.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-memory.md
docs/project-structure-optimization-tasks.md


验证：


git grep 已确认仓内 CI 与 README 的 Docker 入口均指向 infra/docker/Dockerfile、infra/docker/docker-compose.yml 与 infra/docker/docker-compose.override.yml。
已确认根目录 Dockerfile、docker-compose.yml 与 docker-compose.override.yml 不再存在。


风险 / 遗留：


旧的 repo-root docker build . / docker compose up 使用习惯已不再兼容，需要改为显式使用 infra/docker/ 下的 canonical 文件。
根目录仍保留 app.py 与 start_local.bat 两个高价值入口，其中 app.py 仍需后续继续评估。


下一步建议：


若继续做根目录收尾，优先评估 app.py 的最终保留窗口；start_local.bat 建议继续保留。


2026-04-09 / T-522


任务：T-522

状态：todo -> done

变更：


重写 scripts/dev/start_local.py，为纯本地工作流增加 --frontend-mode dev|build|skip，默认切换到 dev 模式并同时拉起 Vite HMR + Flask API。
重写 scripts/dev/start_local_stack.ps1，让 Windows 一键入口默认对齐前后端分离模式，并对 5000/5173 端口做复用检测、分支启动处理，以及 -FrontendPort 端口覆盖支持。
更新 apps/web_ui/vite.config.ts，在开发模式下把 base 切回 /，并为 /api 与 /socket.io 增加到 http://127.0.0.1:5000 的代理。
调整 apps/web_api/app.py 根路由，在本地 dev 模式下通过 BETTAFISH_FRONTEND_DEV_URL 跳转到独立前端服务，避免继续由 Flask 直接输出前端页面。
更新 README.md 与 README-EN.md，将默认启动方式、访问地址和兼容模式说明统一切换到“前端 5173 + 后端 5000”的新链路。


涉及文件：


scripts/dev/start_local.py
scripts/dev/start_local_stack.ps1
apps/web_ui/vite.config.ts
apps/web_api/app.py
README.md
README-EN.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m compileall scripts/dev/start_local.py apps/web_api/app.py
npm --prefix apps/web_ui run typecheck
npm --prefix apps/web_ui run build
python -m scripts.dev.start_local --help
powershell -ExecutionPolicy Bypass -NoProfile -File .\scripts\dev\start_local_stack.ps1 -?
临时使用 cmd.exe /c npm --prefix apps/web_ui run dev -- --host 127.0.0.1 --port 5174 --strictPort 拉起前端后，http://127.0.0.1:5174 返回 200，且 http://127.0.0.1:5174/api/status 通过 Vite 代理返回 200


风险 / 遗留：


当前 apps/web_api/app.py 仍保留静态前端兼容托管逻辑，用于 --frontend-mode build 与已有发布链路；如果后续要彻底 API-only，还需要单独评估生产兼容面。
本机默认端口 5173 当前被另一个 Vite 项目占用，因此本轮真实连通性验证改用 5174；对应地，Windows 一键入口与 Python 启动入口都已补上前端端口覆盖能力。
当前前端仍使用 hash 路由，这能降低分离部署时的回退路由成本；若后续切到 history 路由，需要同步补齐前端静态服务器的 fallback 配置。


下一步建议：


如继续推进前后端彻底解耦，可把 Flask 根路由进一步降级为仅 API 状态页，并把静态前端托管完全收敛到独立前端部署链路。


2026-04-09 / T-523


任务：T-523

状态：todo -> done

变更：


将 scripts/dev/start_local.py 的默认前端端口从 5173 调整为 9527，让纯本地 Python 启动入口默认落到新的前端地址。
将 scripts/dev/start_local_stack.ps1 的默认 -FrontendPort 从 5173 调整为 9527，保证 Windows 一键启动默认对齐。
将 apps/web_ui/vite.config.ts 的 Vite dev server 默认端口从 5173 调整为 9527。
更新 README.md、README-EN.md 中所有默认前端访问地址、端口冲突提示和端口覆盖示例，使文档统一指向 9527。


涉及文件：


scripts/dev/start_local.py
scripts/dev/start_local_stack.ps1
apps/web_ui/vite.config.ts
README.md
README-EN.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m scripts.dev.start_local --help
powershell -ExecutionPolicy Bypass -NoProfile -Command "Get-Help '.\scripts\dev\start_local_stack.ps1'"
npm --prefix apps/web_ui run typecheck
临时使用 cmd.exe /c npm --prefix apps/web_ui run dev -- --host 127.0.0.1 --port 9527 --strictPort 拉起前端后，http://127.0.0.1:9527 返回 200，且 http://127.0.0.1:9527/api/status 通过 Vite 代理返回 200


风险 / 遗留：


这是默认端口切换，不会影响手动通过 --frontend-port / -FrontendPort 指定其他端口的能力。
若本机已有服务占用 9527，仍需显式改用其他端口，例如 9528。


下一步建议：


如需，我可以继续直接帮你按新的 9527 端口把本地前后端服务拉起来并检查页面热更新。


2026-04-09 / T-524


任务：T-524

状态：todo -> in_progress -> done

变更：


审查根目录 app.py，确认其内容仅是 from apps.web_api.app import app, main, socketio 的文件级兼容 shim，不再承载业务逻辑。
全仓静态检索确认：除文档说明外，仓内源码与启动脚本已不再依赖 python app.py 或根级 app.py 的内部符号。
复核当前 canonical 启动链路，确认后端真实入口已收口到 python -m apps.web_api / apps/web_api/app.py，Windows 一键入口已收口到 start_local.bat -> scripts/dev/start_local_stack.ps1。
更新任务文档、记忆文件与根级兼容清单，正式记录 app.py 已完成保留评估。


涉及文件：


docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md
docs/root-compatibility-shim-inventory.md
docs/project-structure-root-cleanup-inventory.md


验证：


python -m py_compile app.py apps/web_api/app.py apps/web_api/__main__.py
python -c "import importlib; root = importlib.import_module('app'); web_api = importlib.import_module('apps.web_api.app'); print(root.app is web_api.app); print(callable(root.main)); print(hasattr(root, 'socketio'))"
PowerShell 静态搜索确认：README.md、README-EN.md、apps/README.md、apps/web_api/README.md 仍存在兼容说明，但仓内代码未发现真实运行依赖。


风险 / 遗留：


app.py 仍被 README 与若干兼容说明文档显式引用，直接删除会让文档与历史命令示例失效。
仓外自动化、个人启动习惯或已缓存的旧命令仍可能直接执行 python app.py；这一部分无法仅靠仓内搜索完全证明为零。


下一步建议：


如继续做根级收口，优先删除 app.py，并同步清理 README / 兼容清单中的旧命令示例；start_local.bat 建议继续保留为 Windows 一键入口。


2026-04-10 / T-525


任务：T-525

状态：todo -> in_progress -> done

变更：


删除根目录 app.py，终止对 python app.py 旧启动方式的仓内兼容。
更新 README.md、README-EN.md、apps/README.md 与 apps/web_api/README.md，把所有当前有效启动说明统一切换到 python -m apps.web_api 与 python -m scripts.dev.start_local。
更新根级兼容清单与根目录清理清单，明确仓库当前仅剩 start_local.bat 一个高价值根级入口。
更新任务文档与记忆文件，正式记录 app.py 从“已完成删除评估”进入“已实际删除”的状态。


涉及文件：


app.py（已删除）
README.md
README-EN.md
apps/README.md
apps/web_api/README.md
docs/root-compatibility-shim-inventory.md
docs/project-structure-root-cleanup-inventory.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile apps/web_api/app.py apps/web_api/__main__.py
PowerShell 定向静态检索确认：README.md、README-EN.md、apps/README.md、apps/web_api/README.md、docs/root-compatibility-shim-inventory.md、docs/project-structure-root-cleanup-inventory.md 中已不再把 python app.py 或根目录 app.py 描述为当前可用入口。
PowerShell 区分大小写的定向静态检索覆盖 apps/、backend/、services/、scripts/、tests/、.github/、infra/ 与 start_local.bat，未发现 from app import、import app 或 python app.py 的真实运行依赖。

Test-Path app.py 返回 False


风险 / 遗留：


仓外自动化、个人脚本或缓存命令若仍执行 python app.py，将直接失效，需要改为 python -m apps.web_api 或 python -m scripts.dev.start_local。
任务记忆文档中仍会保留历史迁移记录里关于 app.py 的描述，这是历史事实，不代表当前入口仍然有效。


下一步建议：


如继续做工程化收尾，可进一步评估是否把 apps/web_api/app.py 中的静态前端 build 兼容托管继续收口为更纯粹的 API-only 形态。


2026-04-10 / T-526


任务：T-526

状态：todo -> in_progress -> done

变更：


审查 apps/web_api/app.py 的根路由逻辑，确认当前行为是：若存在 BETTAFISH_FRONTEND_DEV_URL 则重定向到 Vite dev server；否则优先返回 static/frontend/index.html；若构建产物缺失再降级到 templates/index.html 兜底页。
审查 scripts/dev/start_local.py、scripts/dev/start_local_stack.ps1 与 README，确认当前本地 canonical 启动链路已经是 9527 前端热更新 + 5000 后端 API，--frontend-mode build 只剩兼容 / 部署用途，不再是主开发路径。
审查 apps/web_ui/vite.config.ts、apps/web_ui/README.md 与 infra/docker/Dockerfile，确认前端构建产物仍输出到 static/frontend/，且 Docker 镜像构建阶段会显式复制该目录，因此 Flask 静态托管链路仍被当前单服务部署方式依赖。
识别到 BETTAFISH_FRONTEND_MODE 当前仅在 scripts/dev/start_local.py 中写入环境变量，apps/web_api/app.py 并未消费它，属于后续可以单独清理的冗余信号。


涉及文件：


apps/web_api/app.py
scripts/dev/start_local.py
scripts/dev/start_local_stack.ps1
apps/web_ui/vite.config.ts
apps/web_ui/README.md
infra/docker/Dockerfile
templates/index.html
README.md
README-EN.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


PowerShell 定位确认：apps/web_api/app.py 当前只有 / 入口承担前端相关行为，实际分支为“开发跳转 -> 静态构建产物 -> fallback 模板”三段式逻辑。
定向静态检索确认：BETTAFISH_FRONTEND_DEV_URL 被 apps/web_api/app.py 消费用于开发态跳转，而 BETTAFISH_FRONTEND_MODE 当前只在 scripts/dev/start_local.py 中写入，未形成后端行为分支。
定向静态检索确认：infra/docker/Dockerfile 与 apps/web_ui/vite.config.ts 仍共同依赖 static/frontend/ 作为当前单服务部署产物目录。


风险 / 遗留：


若现在直接删除 apps/web_api/app.py 中对 static/frontend/index.html 的托管分支，将立即打断当前 Docker 镜像与任何“单服务 Flask 承载前端构建产物”的部署方式。
当前 build 模式在文档口径上仍容易被理解为“本地开发的替代模式”，但从职责上看它更准确地属于“部署兼容模式”。

BETTAFISH_FRONTEND_MODE 这类未被消费的环境变量会制造“后端已显式识别模式”的错觉，建议后续收口。


下一步建议：


先执行 T-527，把文档与启动口径统一改成“dev = 本地前后端分离开发模式，build = Flask / Docker 单服务部署兼容模式”，并清理未被消费的模式环境变量。
只有在补齐独立前端交付方案后，才建议继续推进真正的 API-only 后端收口。


2026-04-10 / T-527


任务：T-527

状态：todo -> in_progress -> done

变更：


从 scripts/dev/start_local.py 中移除未被后端消费的 BETTAFISH_FRONTEND_MODE 环境变量写入，并同步调整 --frontend-mode、--skip-frontend-check 与缺失构建产物提示的描述。
更新 README.md、README-EN.md、apps/web_ui/README.md 与 apps/web_api/README.md，统一把 build 模式描述为“Flask / Docker 单服务部署兼容模式”，不再把它表述为本地开发主路径。
更新 templates/index.html fallback 页，引导用户区分“本地开发推荐直接跑 python -m scripts.dev.start_local”与“需要让 Flask / Docker 承载前端时再生成部署兼容构建产物”。
更新 scripts/dev/start_local_stack.ps1 的 build 分支提示文案，使 PowerShell 一键启动入口与当前口径一致。


涉及文件：


scripts/dev/start_local.py
scripts/dev/start_local_stack.ps1
README.md
README-EN.md
apps/web_ui/README.md
apps/web_api/README.md
templates/index.html
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


python -m py_compile scripts/dev/start_local.py apps/web_api/app.py apps/web_api/__main__.py
定向静态检索确认：运行时代码中已不再出现 BETTAFISH_FRONTEND_MODE。
定向静态检索确认：当前 README、模块 README、fallback 页与启动脚本文案均已将 build 模式描述为部署兼容用途，而不是本地开发主入口。


风险 / 遗留：


当前只是收口口径与冗余信号，static/frontend/ 交付链路本身仍保留，Docker / 单服务部署仍继续依赖它。

--build-frontend 兼容别名仍继续保留，避免打断已有命令习惯；后续若要彻底删除该别名，需要单独评估外部使用面。


下一步建议：


执行 T-528，开始设计替代 static/frontend/ 托管的独立前端交付方案，再决定 API-only 后端的最终收口路径。


2026-04-10 / T-528


任务：T-528

状态：todo -> in_progress -> done

变更：


审查 apps/web_ui/、apps/web_api/app.py、infra/docker/Dockerfile、infra/docker/docker-compose*.yml 与前端运行时代码，确认当前独立前端交付的真实阻塞点不只在首页托管，还包括相对 /api 请求、报告预览 / 下载 URL、引擎 iframe 裸端口访问以及 Streamlit 子路径能力。
新增 docs/frontend-independent-delivery-plan.md，系统化输出当前现状、方案选项、推荐架构、实施顺序、删除 Flask 静态托管前的前置条件与完成标准。
形成推荐结论：优先落地“同源反向代理的独立前端服务”，而不是直接切到跨域前端直连 API，也不是现在立刻删除 Flask 对 static/frontend/ 的托管。


涉及文件：


apps/web_ui/vite.config.ts
apps/web_ui/src/router/index.ts
apps/web_ui/src/utils/http.ts
apps/web_ui/src/utils/format.ts
apps/web_ui/src/composables/useReportStudio.ts
apps/web_ui/src/composables/useSystemController.ts
apps/web_api/app.py
infra/docker/Dockerfile
infra/docker/docker-compose.yml
infra/docker/docker-compose.override.yml
docs/frontend-independent-delivery-plan.md
docs/project-structure-optimization-tasks.md
docs/project-structure-optimization-memory.md


验证：


定向静态检索确认：前端当前使用 createWebHashHistory，具备独立静态托管的基础条件。
定向静态检索确认：前端大量依赖相对 /api/... 与报告 /api/report/... 路径，说明“同源代理”比“跨域直连”更适合作为第一阶段方案。
定向静态检索确认：buildEngineUrl() 当前按 window.location.hostname + :8501/:8502/:8503 生成引擎 iframe 地址，必须作为独立交付前的显式收口项。
定向静态检索确认：当前未发现通用 HTTP CORS 配置；后端仅对 Socket.IO 配置了 cors_allowed_origins="*"，因此当前不适合直接切跨域前端直连。


风险 / 遗留：


文档层面已经明确路径，但尚未实际实现代理层、URL 配置层和 Streamlit 子路径能力。

static/frontend/ 仍继续承担当前 Docker / 单服务部署的前端交付责任。


下一步建议：


先执行 T-529，把前端 URL 配置和引擎 iframe 端口拼接统一抽象出来。
然后执行 T-530，落地独立前端服务与同源代理拓扑。


YYYY-MM-DD / Task ID


任务：T-xxx

状态：todo -> in_progress -> done

变更：
涉及文件：
验证：
风险 / 遗留：
下一步建议：