From e6bcf0db158f79db487d8f06af4d6e8927bd5c9a Mon Sep 17 00:00:00 2001
From: cat-shark <1716967236@qq.com>
Date: Thu, 23 Jul 2026 23:01:47 +0800
Subject: [PATCH] docs: add .pi/SYSTEM.md with project overview

---
 .pi/SYSTEM.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 109 insertions(+)
 create mode 100644 .pi/SYSTEM.md

diff --git a/.pi/SYSTEM.md b/.pi/SYSTEM.md
new file mode 100644
index 0000000..e979a64
--- /dev/null
+++ b/.pi/SYSTEM.md
@@ -0,0 +1,109 @@
+# LPT AI 服务（lpt-ai）
+
+> TypeScript + Fastify 独立 AI 服务，集成 SiliconFlow LLM，为后端提供异步 AI 任务
+
+---
+
+## 技术栈
+- **运行时**: Node.js 20+
+- **框架**: Fastify 5
+- **LLM**: SiliconFlow OpenAI 兼容接口（Qwen/Qwen2.5-32B-Instruct）
+- **依赖**: 零外部依赖（除 fastify）
+
+---
+
+## 项目结构
+```
+lpt-ai/src/
+├── index.ts          → 服务入口（加载 .env，启动 Fastify）
+├── routes/ai.ts      → AI 路由（health, tasks, fetch-title）
+├── llm/
+│   ├── client.ts     → LLM 客户端（SiliconFlow 接口）
+│   ├── prompts.ts    → Prompt 模板（3种任务类型）
+│   └── prompts.test.ts
+├── task-queue.ts     → 异步任务队列
+└── admin/
+    ├── index.ts      → 管理面板路由
+    ├── routes.ts
+    └── store.ts      → 日志存储
+```
+
+---
+
+## API 端点（5 个）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/health` | 健康检查（返回 LLM 可用状态和模型名） |
+| POST | `/ai/tasks` | 提交异步任务（返回 taskId） |
+| GET | `/ai/tasks/:taskId` | 轮询任务结果 |
+| POST | `/fetch-title` | 抓取网页标题 |
+| GET | `/admin` | 管理面板（查看最近 200 条日志） |
+
+---
+
+## 支持的任务类型
+
+| 类型 | 说明 | 温度 | Max Tokens |
+|------|------|------|------------|
+| `aggregate-report` | 残片聚合为学习报告 | 0.3 | 2048 |
+| `generate-mind-map` | 从报告/残片生成思维导图大纲 | 0.3 | 4096 |
+| `compare-recall` | 用户回忆 vs 标准导图语义对比 | 0.2 | 4096 |
+
+---
+
+## 任务队列设计
+- **异步任务模式**: submit + poll，避免 LLM 长耗时（10-60s）超时
+- **单线程 Worker**: `setImmediate` 链，同一时刻只处理一个 LLM 调用，防止 API 限流
+- **TTL 清理**: 5 分钟一次，移除完成超过 1 小时的记录
+- **异常隔离**: 单个任务失败不影响后续任务
+- **管理面板日志**: 复用 `logStore`，记录最近 200 条请求/响应
+
+---
+
+## LLM 配置
+
+### 环境变量（`.env`）
+```env
+LLM_API_URL=https://api.siliconflow.cn/v1/chat/completions
+LLM_API_KEY=                    # 必填，未配置时 /health 返回 llmAvailable: false
+LLM_MODEL=Qwen/Qwen2.5-32B-Instruct
+LLM_TIMEOUT_MS=60000            # 单次 LLM 调用超时
+PORT=5199
+```
+
+### 降级策略
+- LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`
+- 后端（lpt-be）检测到 AI 不可用 → 自动切换到内置规则引擎（`BuiltinMindMapGenerator`）
+
+---
+
+## 启动命令
+```bash
+npm install        # 安装依赖
+npm run dev        # 开发模式（tsx watch，热重载）
+npm run build      # 编译 TypeScript
+npm run start      # 生产模式
+npm run test       # 测试
+```
+
+---
+
+## Docker
+- 多阶段构建：`node:20-alpine` 编译 → `node:20-alpine` 运行
+- 暴露端口：5199
+- 健康检查：`curl http://localhost:5199/health`
+
+---
+
+## 关联项目
+| 项目 | 路径 | 端口 | 说明 |
+|------|------|------|------|
+| lpt-be | `../lpt-be/` | 5157 | Spring Boot 后端，通过 `lpt.ai-service.url` 调用本服务 |
+| lpt-fe | `../lpt-fe/` | 5158 | Vue 3 前端，不直接调用本服务 |
+
+## 调用关系
+```
+lpt-be (5157) ──HTTP POST /ai/tasks──→ lpt-ai (5199)
+lpt-be (5157) ──HTTP GET  /ai/tasks/:id──→ lpt-ai (5199)
+```