cmshoppe/docs/03-tech-stack.md

技术栈（Tech Stack）

“用什么”的统一速查表。选型与理由在此集中维护；“怎么把它们搭起来”见 架构设计。 未定项必须标为待定，不要让 agent 在代码里自行决定。

一、技术栈一览

维度	选型	状态	理由 / 说明
语言	Python 3.10+	已定	已有脚本均为 Python；标准库够用
运行平台	Windows（生产）；WSL 可用于开发	已定	Chrome 与各 user-data-dir 在 Windows；GUI 与 Chrome 同机，CDP 走 localhost
浏览器自动化	自研 CDP 客户端 app/cdp.py	已定	基于 websocket-client + requests 手写；不引入 playwright/selenium，规避代理与 Origin 坑
WebSocket	websocket-client（import websocket）	已定	讲 CDP 协议；用 suppress_origin=True 绕过 403
HTTP	requests	已定	读 /json 拿 tab 列表；trust_env=False 忽略代理
浏览器	Google Chrome（已安装）	已定	带 --remote-debugging-port 启动
GUI 框架	PySide6（Qt for Python，QTabWidget 5 Tab）	已定	当前环境已安装 PySide6；V1 需要表格、图片预览、后台任务进度、确认弹窗，Qt 的 signal/slot + QThread 更适合
应用配置	config.json（JSON，stdlib）	已定	少量应用级设置：Chrome 路径、目录根、端口、DB 路径等
业务数据	SQLite（stdlib sqlite3，cmshopee.db）	已定	账号、任务、结果：成行增长、要查询/统计/导出
Excel 读写	openpyxl	已定	导入任务、回写结果；stdlib 读不了 .xlsx
AI 模型注册	config/ai_models.json 多模型清单（HTTP 调用）	已定（结构）	每模型 name/category(text/image)/url/model/key/api_type/连接超时；⑤ 设置可增删改+测试连接；Key 本地明文保存，保存/变更时提示
AI 文本生成	app/ai.py 读取 default_text_model（category=text），通用 chat JSON HTTP	已接入	提示词+旧标题→新标题；失败重试，错误脱敏
AI 图像生成	app/ai.py 读取 default_image_model（category=image），支持 chat 多模态 JSON / images_edits multipart	已接入	提示词+旧封面→新封面；分辨率 512/1k/2k/4k，jpg_quality 存盘，返回超时随分辨率
并发	标准库 concurrent.futures.ThreadPoolExecutor	已定	标题/图片分别按并发数并行；③ 可按账号并行更新；可停止、可重试
运行日志	SQLite run_logs / run_log_events	已定	③ dry-run 与真实更新都留痕；结构化内容走脱敏
图片处理	requests（下载）+ Pillow（按分辨率/jpg质量存盘）	部分待定	下载旧封面；新封面按 resolution 生成、jpg_quality 存盘
测试	python -m compileall app main.py + unittest + 手动 CDP/AI 验证	已定（分层）	配置/DB/Excel/prompts 用单测；CDP/Shopee 与真实 AI 属集成验证或 mock

二、决策记录与演进

• CDP 自研而非 playwright：当前已验证根目录 cdp.py，正式代码迁入 app/cdp.py；它零重依赖、完全可控，并已在开发环境绕开了代理（*_proxy 指向本地 :1080）和 Chrome 的 Origin 403 两个坑。未来若交互复杂度大幅上升，再评估 playwright。
• GUI 选 PySide6：V1 是 5 Tab 运营工作台，包含任务表格、筛选、图片预览、后台采集/生成/更新、进度与停止。当前环境已安装 PySide6，且 Tkinter 不可用；Qt 的 QThread/signal-slot 比 Tkinter 手动 queue/after 更适合长任务回传 UI。
• 存储拆两层：应用设置进 config.json，账号/任务/结果进 SQLite。判据：少量人改无需查询 → 配置文件；成行增长要查询/导出 → DB。同一事实只存一处，不重复。取代早期的 accounts.json 方案。
• Excel 用 openpyxl：运营用真实 .xlsx；stdlib 无法读写 xlsx，引入一个轻依赖比改用 CSV 更贴合用户习惯。
• 多账号隔离用独立 user-data-dir，不用 Chrome profile：profile 共享同一 user-data-dir/进程/调试端口，无法每账号独立 CDP 与并行；独立 user-data-dir 才契合自动化。详见 架构 3.0。
• 快捷方式生成用 PowerShell（无额外依赖）：用 WScript.Shell.CreateShortcut 生成 .lnk，不引入 pywin32 等依赖。
• AI 服务商不写死在代码里：T-301 已采用 config/ai_models.json 的通用 HTTP 接入，当前支持 OpenAI-compatible chat JSON 与 images_edits multipart；具体服务商/模型/Key 由⑤设置维护。
• 敏感信息不加密但强提示与脱敏：密码与 AI Key 只在本机 SQLite / config/ai_models.json 明文保存；保存/变更时弹窗提示，UI 打码，日志/导出必须脱敏，相关本地文件必须 gitignore。
• AI 产出无逐条审核：生成的新标题/新封面经 ③ 批量确认后提交线上；无常驻提交开关，本地留档 + 回写 Excel 供追溯。
• T-504 更新执行增强：③ 支持 dry-run 预览、运行日志和按账号并行；默认 dry-run 关闭、并行关闭，不引入新依赖。
• 不引入数据库（指外部 DB）：用 stdlib SQLite 足够；不引入 Postgres/MySQL 等。
• 生产在 Windows 直跑：开发期我们用过 WSL→Windows 的 netsh portproxy（9333→9222）连 CDP；但 GUI 与 Chrome 都在 Windows 时，直接连 127.0.0.1:9222，无需 portproxy。

三、构建与运行命令

用途	命令
安装依赖	pip install websocket-client requests openpyxl pillow PySide6
检查 PySide6	python -c "import PySide6; print(PySide6.__version__)"
语法检查	python -m compileall app main.py
启动 GUI	python main.py / python -m app
单元测试（T-006 后）	python -m unittest discover -s tests
跑单账号演示	python prototypes/demo.py（分步）/ set AUTO=1 && python prototypes/demo.py（自动）
提交更新（真改线上）	set UPDATE=1 && python prototypes/demo.py
读取某账号 Cookie（调试）	python prototypes/cookies.py

Windows PowerShell 下设置环境变量与 cmd 不同：

# PowerShell
$env:AUTO=1; python prototypes/demo.py
$env:UPDATE=1; python prototypes/demo.py

:: cmd
set AUTO=1 && python prototypes/demo.py

四、依赖纪律

• 新增第三方依赖前，先在本文说明用途、替代方案和维护成本。
• GUI 框架固定为 PySide6，不允许混入 Tkinter/PyQt/Web 形成两套 UI。
• 不引入第二套浏览器自动化方案（不要 app/cdp.py 之外再混入 selenium/playwright）。
• 不确定的技术选型先更新本文，再进入代码。

五、测试分层

层级	覆盖对象	验证方式
语法	正式代码包与入口	python -m compileall app main.py
单元	appconfig/db/excel/prompts/config/chrome 的纯逻辑	T-006 建立 tests/ 后运行 python -m unittest discover -s tests，使用临时目录/临时 SQLite/样例 Excel
GUI 轻测	PySide6 主窗口可创建、Tab 数量、worker signal 基本行为	可用 unittest 构造 QApplication，不连真实 Shopee
集成	CDP/editor 操作 Shopee 测试商品	手动跑 prototypes/demo.py 或后续专用集成脚本
外部 AI	模型连接、文本/图像生成	默认 mock；真实调用只在手动验证时跑，避免成本和限流