# 技术栈

## 桌面端（本期实现范围）

| 层 | 选型 | 说明 |
|---|---|---|
| 框架 | Electron + electron-vite | 三进程构建（main/preload/renderer），HMR；Electron ≥37.6（内置 Node ≥22.19，满足 pi 运行时） |
| 渲染进程 UI | React + TypeScript | |
| 样式 | Tailwind CSS v4 | |
| 组件 | beautifului.dev registry 原语（MIT，shadcn CLI 分发）+ shadcn/ui 风格自实现 | `components.json` 已配置，`npx shadcn add https://www.beautifului.dev/r/<slug>.json` 直装；已装 LoadingState / ThinkingState / ToolChips / ApprovalCard / Button / GlideMenu + foundation tokens（暗色适配见 `src/renderer/src/styles/beautifului.css`） |
| 动效 | GSAP | 消息入场、卡片展开、状态过渡 |
| 图标 | lucide-react | |
| Agent 运行时 | pi SDK（`@earendil-works/pi-coding-agent`，版本精确锁定） | 嵌主进程；`save-exact` 纪律 |
| 本地库 | sqlite3（better-sqlite3 候选，带 migrations 表 + 启动自动迁移） | v0.x 后期引入，先跑通链路 |

## Monorepo 布局（目标态，按版本逐步填充）

```
agent-store-operations/
├─ pnpm-workspace.yaml          # apps/*, packages/*
├─ apps/
│  ├─ desktop/                  # ✅ 本期：Electron 客户端
│  ├─ server/                   # ⛔ 未设计，不创建（NestJS）
│  └─ admin/                    # ⛔ 未设计，不创建（Ant Design Pro）
├─ packages/
│  ├─ shared/                   # ⏳ 后端设计定稿后再建（DTO 契约）
│  └─ agent/                    # ⏳ pi 插件：业务工具 + skills + 提示词
└─ docs/                        # ✅
```

> 约束：`apps/server`、`apps/admin`、数据库相关一律不创建不设计（用户明确要求）。业务插件包 `packages/agent` 中依赖服务器 API 的工具只留占位接口。

## 工程纪律

- 依赖 `save-exact=true`（.npmrc），pi 包版本浮动 = 行为漂移
- 主进程依赖 externalize（electron-vite 默认），pi 保持 `dependencies`，打包时随 app 分发
- 每个版本 git tag（v0.1.0 起），自省记录追加到 `docs/roadmap.md`
- 渲染进程零敏感信息：API key、pi 凭据只存在主进程可达的 `~/.pi`，渲染进程经 IPC 交互