# 项目重构任务书

## 项目名称
小灵宝（xiaolingbao）项目重构

## 仓库地址
https://gitee.com/AY77-OP/xiaolingbao.git

## 红线要求
1. 严禁向仓库提交任何代码，一切操作在本地完成。
2. 源码中严禁保留任何 API Key，需全部清除并做环境变量或配置文件脱敏处理。
3. 最终交付物为本地压缩包，不推送到远程仓库。

## 一、任务目标
将现有项目进行全面重构，使其满足以下核心要求：
1. 零依赖运行：新电脑无需预装 Python、FFmpeg、浏览器内核或其他任何运行时或第三方语言环境，双击即可直接使用。
2. 去除浏览器内核及 HTML 依赖：项目不得依赖 Electron、CEF、WebView 等浏览器内核，不使用 HTML 作为界面渲染方案。
3. 内置运行时：将 Python 解释器和 FFmpeg 静态库完整内置于项目中。
4. 所有功能恢复正常：逐一排查并修复现有全部功能，确保正常可用。

## 二、技术路线说明
本项目的功能底层基于 ComfyUI 工作流模式。重构时需：
1. 深入研究 ComfyUI 工作流的运行机制和输出方式。
2. 将 ComfyUI 工作流的核心逻辑提取并封装为独立应用。
3. 最终目标是将 ComfyUI 工作流转化为一个界面简洁、可独立运行的桌面软件（本次先完成源码重构，暂不打包为 exe）。

## 三、具体工作内容

### 3.1 源码分析（第一步）
- 完整阅读项目源码，梳理架构、模块依赖关系和调用链。
- 识别并记录所有外部依赖（Python 包、系统工具、浏览器组件等）。
- 排查并清除所有硬编码的 API Key 和敏感信息。

### 3.2 项目重构（核心）
- 去除对浏览器内核和 HTML 的依赖，替换为原生桌面 UI 方案（如 PyQt / PySide / Tkinter 等，由技术负责人评估选定）。
- 内置 Python 嵌入式运行环境（embeddable Python）。
- 内置 FFmpeg 静态编译版本。
- 封装 ComfyUI 工作流的核心调用逻辑，使其脱离 ComfyUI 框架独立运行。
- 实现新电脑双击即可运行的目标。

### 3.3 功能修复
- 逐项测试现有所有功能。
- 修复所有异常或不可用的功能，确保全部正常运行。

### 3.4 文档编写
输出以下文档（随项目一起交付）：
- 重构报告：重构前后架构对比、变更清单、重构决策依据。
- 开发规范：代码风格、目录结构规范、命名规则、注释要求。
- 重构指南：详细的重构步骤记录，便于后续参考。
- 继续开发指南：新人上手文档，包含环境搭建、模块说明、扩展开发流程。
- 功能清单与使用说明：所有功能列表及使用方式。

## 四、交付物
将以下内容打包为一个压缩包（zip / 7z / tar.gz 均可）：
交付物/
├── xiaolingbao/          # 重构后的完整项目源码
├── docs/
│   ├── 重构报告.md
│   ├── 开发规范.md
│   ├── 重构指南.md
│   ├── 继续开发指南.md
│   └── 功能清单与使用说明.md
└── README.md             # 项目总览说明

## 五、协作要求
- 可使用 25 至 50 个并行子任务同步推进，子任务数不低于 25 个。
- 各子任务完成后统一汇总集成。
- 全程本地操作，禁止 git push 到远程仓库。

## 六、补充要求

### 6.1 平台兼容性
- 优先支持 Windows 10 / Windows 11 64位系统。
- 如有条件，兼顾 macOS 和 Linux 支持。
- 路径处理必须兼容中文路径和空格路径。

### 6.2 测试要求
- 每个功能模块重构完成后需进行本地功能验证。
- 交付前需在一台全新、无任何开发环境的电脑上完成全流程验证。
- 记录测试结果，附在 docs/测试报告.md 中。

### 6.3 日志与异常处理
- 所有关键操作需有日志记录，日志文件存放在项目 logs/ 目录下。
- 程序崩溃时需捕获异常并输出友好的错误提示，不得直接闪退无提示。

### 6.4 配置管理
- 所有用户可调配置项集中存放在一个配置文件中（如 config.yaml 或 config.json）。
- 配置文件需提供默认值，首次运行无需手动修改即可使用。
- API 地址等敏感配置不得硬编码，必须从配置文件或环境变量读取。

### 6.5 性能要求
- 应用启动时间不超过 10 秒（常规硬件条件下）。
- 运行时内存占用需合理控制，避免内存泄漏。
- 内置 Python 和 FFmpeg 后整体包体积需做优化，去除不必要的文件。

### 6.6 网络与离线
- 明确标注哪些功能需要联网，哪些可离线使用。
- 无网络情况下程序不得崩溃，需给出明确提示。

### 6.7 ComfyUI 工作流管理
- 工作流文件（JSON）需集中存放在项目 workflows/ 目录下。
- 支持工作流的导入、导出和切换。
- 工作流执行过程需有进度反馈。

### 6.8 更新机制
- 预留版本号管理（如 version.txt 或在配置文件中维护）。
- 后续需支持增量更新或版本检测能力。

### 6.9 沟通与进度管理
- 每完成一个阶段需输出进度报告。
- 遇到阻塞性问题需及时上报，不得自行跳过。
- 最终交付前需提交完整的变更清单（changelog）。

### 6.10 登录功能
- 登录界面需设计并实现，支持账号密码登录。
- 登录接口暂时未对接云端服务器，需做以下处理：
  - 将登录 API 地址设为可配置项，存放在配置文件中。
  - 定义好接口协议（请求参数、返回格式），前端页面先行开发完成。
  - 云端服务器就绪前，提供本地模拟登录模式（如本地配置文件中预设一个测试账号密码），用于开发和测试阶段正常使用。
- 登录状态需做本地持久化（如 token 缓存），避免每次启动重复登录。
- 需包含退出登录和账号切换功能。
- 后续云端登录系统就绪后，只需修改 API 地址即可无缝对接，无需改动前端逻辑。