# Sensa 基础版架构说明

## 一句话理解

`sidepanel.js` 像餐馆店长，负责编排流程，不亲自做每件事。

## 餐馆比喻

- 顾客：你输入的提问
- 店长/前台：`sidepanel.js`
- 后厨：`background.js` 和 `ai-client.js`
- 跑堂/观察员：`content.js` 和 `page-context.js`
- 仓库管理员：`settings-store.js` 和 `session-storage.js`
- 摆盘上菜：`render/messages.js`

## 当前技术架构图

```mermaid
flowchart TD
    U[用户 User<br/>顾客点单] --> SP[sidepanel.js<br/>前台/店长<br/>编排层]

    SP --> RA[request-builder.js<br/>点单整理员<br/>把顾客需求整理成标准工单]
    SP --> PC[page-context.js<br/>跑堂观察员<br/>去看桌面和现场情况]
    SP --> SS[session-storage.js<br/>会员/订单档案员<br/>保存历史会话]
    SP --> RS[render/messages.js<br/>服务员摆盘上菜<br/>把结果展示给顾客]
    SP --> API[runtime-api.js<br/>店长对后厨传话通道]

    PC --> CT[content.js<br/>后厨侦察员<br/>读取网页标题、正文、表格、按钮等]
    CT --> PAGE[当前网页<br/>餐桌现场]

    API --> BG[background.js<br/>后厨总调度]
    BG --> SET[settings-store.js<br/>仓库管理员<br/>读取 API Key 和默认配置]
    BG --> PB[prompt-builder.js<br/>菜单翻译员<br/>把材料整理成 AI 看得懂的话]
    BG --> AI[ai-client.js<br/>外卖平台/中央厨房接口<br/>真正调用大模型]

    AI --> OPENAI[OpenAI / 大模型<br/>真正做菜的人]
    OPENAI --> AI
    AI --> BG
    BG --> SP
    SP --> RS
    RS --> U
```

## 模块职责

- `sidepanel.js`：负责流程编排、界面事件、状态推进
- `request-builder.js`：把用户输入、页面快照、截图、历史会话整理成请求
- `page-context.js`：负责抓取当前网页内容和截图
- `session-storage.js`：负责页面级聊天记录和快照存储
- `storage-stats.js`：负责本地存储统计
- `render/messages.js`：负责消息区和空状态渲染
- `runtime-api.js`：负责和后台消息通信
- `background.js`：负责后台消息路由
- `settings-store.js`：负责读取和保存设置
- `ai-client.js`：负责调用大模型
- `prompt-builder.js`：负责把材料拼成模型提示词

## 为什么要这样拆

如果不拆，`sidepanel.js` 会同时做：

- 接单
- 采集页面
- 拼请求
- 发模型
- 存历史
- 画界面

这样会越来越乱。

拆开以后，每一层只做一类事，后面再加功能会更稳。

