inkreach-agent/docs/architecture.md

架构决策记录（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 补开关与可见性管控。