v0.1.0: Electron 桌面端骨架 + pi SDK 聊天链路

2026-09-05 09:28:33 +08:00
commit 17110ee5ab
35 changed files with 5350 additions and 0 deletions
@@ -0,0 +1,69 @@
+# 架构决策记录（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 插件形式内置）
+
+1. 热点词采集（AI/工具采集）或手动定义
+2. 依据热点词 + 参考素材生成商品图、标题等信息
+3. 生成商家模板
+4. CDP 驱动浏览器操作店铺后台：上架、核价、流量加速、下架、报活动
+5. 数据分析
+
+## 4. 范围裁剪（本期）
+
+- ✅ Electron 桌面端（本仓库 `apps/desktop`）
+- ⛔ NestJS 后端、Ant Design Pro 后台、PostgreSQL —— 未设计，不创建、不实现
+- 业务插件中依赖服务器 API 的部分，先留接口占位（不依赖后端即可运行的本地能力可先行）