对Harness工程的一些理解

AI-PPT/
├── backend/                    # Web 服务模式
│   ├── app.py                  # FastAPI 入口
│   ├── taskRunner.py           # 后台任务编排
│   ├── middleware.py           # 认证中间件
│   ├── authClient.py           # 企业微信 OAuth 封装
│   ├── database.py             # SQLite 操作
│   ├── config.py               # 全局配置
│   ├── routes/                 # API 路由
│   │   ├── authRoutes.py       # 登录相关接口
│   │   ├── taskRoutes.py       # 上传/状态/下载接口
│   │   └── historyRoutes.py    # 历史记录接口
│   └── operators/              # 算子层（Web 端副本）
│       ├── llmClient.py        # OpenAI 兼容 API 封装
│       ├── mineruClient.py     # MineRU API 封装
│       └── pptBuilder.py       # python-pptx 生成幻灯片
├── frontend/                   # 前端纯 HTML/CSS/JS
│   ├── index.html              # 主页面
│   ├── login.html              # 登录页面
│   ├── app.js                  # 前端逻辑
│   └── style.css               # 样式表
├── templates/                  # PPT 母版与附件
│   ├── 母版_带缩写.pptx        # PPT 母版文件
│   └── IF表.xlsx               # IF 数据表
├── storage/                    # 运行时数据（运行时生成）
│   ├── app.db                  # SQLite 数据库
│   ├── uploads/{taskId}/       # 上传的 PDF 文件
│   └── output/{taskId}/        # MineRU 解析结果 + 生成的 PPT
├── CLAUDE.md                   # 项目说明（面向 Claude Code）
├── code.md                     # UOP 代码规范
├── requirements.txt            # Python 依赖
├── .env                        # 环境变量
└── .gitignore                  # Git 忽略规则

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 语言要求

优先用中文回复问题。

## 代码规范

写代码前必须遵循 `code.md` 中的"面向理解编程 (UOP)"规范。

## 项目概述

批量学术论文 PDF → 单页 PPT 摘要工具，支持两种运行模式：CLI 直接处理 和 Web 在线服务。

核心流程：PDF → MineRU API 解析 → LLM 两轮提取（文本提取 + 多模态选图）→ python-pptx 生成 PPT。

## 运行命令

pip install -r requirements.txt

# --- CLI模式（根目录脚本） ---
python main.py                          # 处理当前目录所有PDF
python main.py paper1.pdf paper2.pdf    # 处理指定文件
python main.py --output result.pptx     # 指定输出文件名

# --- Web服务模式 ---
uvicorn backend.app:app --reload        # 启动FastAPI开发服务器（默认8000端口）


## 架构

项目有两套独立入口，共享同一套算子层逻辑：

### CLI模式（根目录）
- `main.py` — 编排层，直接调用根目录下的算子模块

### Web服务模式（backend/）
- `backend/app.py` — FastAPI入口，注册路由、中间件、静态文件
- `backend/taskRunner.py` — 后台任务编排，在 BackgroundTasks 线程中执行转换流程
- `backend/middleware.py` — 认证中间件，校验session cookie（itsdangerous签名）
- `backend/authClient.py` — 企业微信OAuth封装（access_token缓存 + code换userId）
- `backend/database.py` — SQLite操作（WAL模式），users + tasks 两张表
- `backend/config.py` — 全局配置，集中管理路径常量和环境变量
- `backend/routes/` — 三组API路由：authRoutes（登录）、taskRoutes（上传/状态/下载）、historyRoutes（历史）

### 算子层（两套副本，根目录 + backend/operators/）
- `mineruClient.py` — MineRU API封装（uploadFiles / waitForResults / downloadAndExtract）
- `llmClient.py` — OpenAI兼容API封装，两轮调用：extractPaperInfo（文本模型）+ selectKeyImage（视觉模型）
- `pptBuilder.py` — python-pptx生成幻灯片，基于母版占位符索引填充内容

### 前端
- `frontend/` — 纯HTML/CSS/JS，login.html + index.html + app.js + style.css

### 存储
- `storage/uploads/{taskId}/` — 上传的PDF文件
- `storage/output/{taskId}/` — MineRU解析结果 + 生成的PPT
- `storage/app.db` — SQLite数据库
- `templates/母版.pptx` — PPT母版文件

## 环境变量（.env）

- `MINERU_API_TOKEN` — MineRU 的 Bearer Token
- `OPENAI_API_KEY` — LLM API 密钥
- `OPENAI_BASE_URL` — 可选，自定义 API 地址（兼容中转站/国产模型）
- `WECOM_CORP_ID` / `WECOM_AGENT_ID` / `WECOM_APP_SECRET` — 企业微信OAuth配置（Web模式必需）
- `SESSION_SECRET` — cookie签名密钥
- `SERVICE_BASE_URL` — 服务外部访问地址，用于OAuth回调URL拼接

## 关键设计细节

- LLM两轮调用：第一轮用文本模型（textModel）提取结构化JSON，第二轮用视觉模型（visionModel）从候选图片中选GA图
- PPT通过占位符索引（phTitle=11, phImage=16等）定位母版中的文本框和图片框，修改母版后需同步更新索引
- Web模式认证链：企微OAuth → code换userId → itsdangerous签名cookie → 中间件校验注入request.state.userId
- 任务进度分5步：1-上传PDF → 2-解析PDF → 3-提取文字 → 4-选择图片 → 5-生成PPT，前端轮询 progressStep 展示进度