4.4 KiB
4.4 KiB
架构决策记录（ADR）
本文档沉淀截至 2026-09-05 的架构讨论结论，作为实现的唯一依据。后端/后台/数据库尚未设计，本期不动。
1. 系统形态
店铺运营桌面工具：固定业务流程 + Agent 灵活编排 + 可切换纯手动。
本地机器（每用户） 服务器（未设计，本期不动）
┌─ Electron App ────────────────┐ ┌─ NestJS ─────────────┐
│ 渲染进程：React UI │ │ 账号/鉴权 │
│ （聊天流、工具卡片、审批卡、 │ │ LLM 代理（key/用量） │
│ 业务面板、GSAP 动效） │ │ 共享资产（可选） │
│ ▲ IPC（contextBridge） │ └──────────┬───────────┘
│ 主进程： │ │
│ ├─ pi SDK（createAgentSession）│──── HTTPS ───────┘
│ ├─ pi 插件（extensions/tools） │ 业务工具=服务器API薄封装
│ └─ sqlite（会话/任务/业务数据） │
│ 共享 ~/.pi（auth/models/sessions）│
└────────────────────────────────┘
2. 关键决策
D1 pi 跑本地，嵌 Electron 主进程
- pi SDK 同进程嵌入（类型安全、
extensionFactories官方文档路径）。 - Electron 37.6+ 内置 Node ≥22.19，满足 pi 运行时要求（本机系统 Node 22.15 仅用于构建）。
- 备选降级路径：主进程 spawn
pi --mode rpc子进程（JSONL stdio），用于将来崩溃隔离；工具定义代码可复用。 - 共享
~/.pi/agent（auth.json、models-store.json、sessions/），与用户已有的 pi CLI 配置互通（本机已确认存在）。
D2 能力层唯一：Agent 与手动模式共用同一份实现
- 每个业务功能（热点词采集、素材生成、模板生成、CDP 操作、数据分析）=
packages/agent中的独立模块。 - 同时向两个方向暴露：① pi 的
defineTool()/extension 注册（Agent 模式，LLM 编排）；② Electron IPC 直接调用（纯手动模式，UI 按钮触发）。 - 两条路径行为一致、审计一致。这是"可切换纯手动"低成本实现的前提。
D3 固定流程用 pi skills 承载 SOP，审批卡做闸门
- SOP（完整上架流程、报活动流程等）写成 pi skill / 提示模板，agent 按剧本执行、剧本内灵活处理异常。
- 涉及花钱/不可逆的操作（核价、报活动）：extension 拦截
tool_call→ 渲染进程弹审批卡 → 人工确认后才放行。 - 任务状态落本地 sqlite，支持断点续跑。
D4 CDP 操作本地执行
- 店铺后台登录态在本地浏览器 cookie，CDP 控制必须发生在用户机器（这也是 D1 的根本原因之一）。
- 浏览器操作工具按"幂等、可重试、每步截图回传确认"设计；既保流程可靠，也缓冲平台风控。
D5 数据主权：本地优先，服务器极薄
| 存哪 | 存什么 |
|---|---|
| 本地 sqlite | 商品数据、分析结果、热点词采集结果、生成记录、任务/断点状态、pi 会话（大文件落磁盘，库存元数据与路径） |
| 服务器 PG | 仅账号/鉴权、LLM 代理配置与用量、（可选）团队共享词库/模板。明确不存商品数据、分析结果等用户业务数据 |
后果与对策：
- 单机即真相：无跨设备同步、无全团队聚合报表（用户已确认接受）。
- 本地备份：sqlite 单文件 + 资产目录做"一键打包备份/恢复"，排早期功能。
- 本地 sqlite schema 必须自带版本号与迁移机制（migrations 表 + 启动时自动升级）。
3. 业务流程链（目标态，全部以 pi 插件形式内置）
- 热点词采集（AI/工具采集）或手动定义
- 依据热点词 + 参考素材生成商品图、标题等信息
- 生成商家模板
- CDP 驱动浏览器操作店铺后台：上架、核价、流量加速、下架、报活动
- 数据分析
4. 范围裁剪（本期）
- ✅ Electron 桌面端（本仓库
apps/desktop） - ⛔ NestJS 后端、Ant Design Pro 后台、PostgreSQL —— 未设计，不创建、不实现
- 业务插件中依赖服务器 API 的部分，先留接口占位（不依赖后端即可运行的本地能力可先行）