82 lines
6.1 KiB
Markdown
82 lines
6.1 KiB
Markdown
# 架构决策记录（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 的部分，先留接口占位（不依赖后端即可运行的本地能力可先行）
|
||
|
||
## 5. D7 动态插件系统（两层能力模型）
|
||
|
||
harness 收敛为「壳 + 聊天 + 插件系统」，业务功能以插件交付（详见 docs/plugins.md）：
|
||
|
||
- **两层能力**：内置插件（代码注册，宿主树组件 + 第一方工厂 + 全量宿主能力，浏览器面板即首个实例）/ 外置插件（`userData/plugins/`，iframe 隔离页 + 动态 import 的 main.mjs + 仅 SDK 桥接 API）。同 id 高 semver 胜、外置可遮蔽内置（组件级需 `replacesNative` 声明）→ **内置插件也能在线热更而不发安装包**。
|
||
- **pi 原生契约**：插件工厂收到 `{ pi, ui, storage }`——`pi` 为真实 `ExtensionAPI`，工具/事件/命令/消息走 `pi.registerTool` 等原生路径（harness 挂一个聚合 extension 扇出）；`ui` 为 Electron 版槽位（对位 pi TUI 的 `ctx.ui.*`）：侧栏入口/整页视图/面板 tab/状态胶囊/深链，内联 UI 一律数据驱动。
|
||
- **iframe 隔离的动机**：外置 UI 与宿主无 React 实例共享问题、插件崩溃不拖垮宿主、热重载 = 换 src；代价（跨桥交互、主题靠 tokens.css 连续）已接受。`plugin://`/`peer://` 特权协议 + CSP `frame-src plugin:` + 路径穿越防护 + origin/source 双重校验。
|
||
- **SDK 即 npm 包**（`packages/plugin-sdk`，Obsidian 模式）：类型 + `definePlugin` + 页面桥 client（postMessage 白名单 invoke）+ hooks；仓库根 pnpm workspace（apps/* + packages/*）。
|
||
- **在线更新（M5）**：索引检查 → 下载 → ed25519 验签（公钥钉 harness）→ minContract 兼容检查 → 原子替换 → 热重载；自动/手动并存。
|
||
- **pi 原生目录（M7）**：pi resource-loader 默认已加载 `~/.pi/agent/extensions`（事实），M7 补开关与可见性管控。
|
||
|