7 changed files with 49 additions and 162 deletions
+4
View File
@@ -0,0 +1,4 @@
# 行尾规范:文本文件统一 LF,Windows 批处理保留 CRLF
* text=auto eol=lf
*.bat text eol=crlf
*.cmd text eol=crlf
+26 -13
View File
@@ -4,7 +4,7 @@ on:
workflow_dispatch: workflow_dispatch:
inputs: inputs:
environment: environment:
description: '部署环境(本仓库仅 main 分支;dev/prod 均从 main 部署)' description: '部署环境(dev 仅允许 dev 分支;prod 仅允许 master 分支)'
required: true required: true
type: choice type: choice
options: options:
@@ -14,7 +14,7 @@ on:
env: env:
REGISTRY: 192.168.123.199:5000 REGISTRY: 192.168.123.199:5000
APP: lpt-ai APP: lpt-ai
REPO_URL: http://git.cat-shark.xyz/cat-shark/lpt-ai.git REPO_URL: https://git.cat-shark.xyz/cat-shark/lpt-ai.git
jobs: jobs:
build-and-deploy: build-and-deploy:
@@ -33,18 +33,31 @@ jobs:
fi fi
ENV="${{ inputs.environment }}" ENV="${{ inputs.environment }}"
echo "branch=$BRANCH environment=$ENV sha=${{ gitea.sha }}" echo "branch=$BRANCH environment=$ENV sha=${{ gitea.sha }}"
# lpt-ai 仅维护 main:dev/prod 都从 main 出包,靠 environment 区分 namespace/镜像 tag # lpt-ai 与 lpt-be/lpt-fe 同规则:master 发 prod,dev 发 dev。
case "$BRANCH" in # 不允许跨环境出包:本服务的入参/出参结构与 lpt-be 的版本强耦合,
main|master) # 把 dev 的代码推到 prod 会让旧版 lpt-be 读到不认识的字段(静默降级)。
echo "OK: lpt-ai 从 $BRANCH 部署到 $ENV"
;;
*)
echo "ERROR: lpt-ai 只能从 main/master 部署,当前分支是 '$BRANCH'"
exit 1
;;
esac
case "$ENV" in case "$ENV" in
dev|prod) ;; prod)
case "$BRANCH" in
master) echo "OK: prod 允许从 $BRANCH 部署" ;;
*)
echo "ERROR: prod 只能从 master 部署,当前分支是 '$BRANCH'"
echo "请切换到 master 后再 Run workflow,并选择 environment=prod"
exit 1
;;
esac
;;
dev)
case "$BRANCH" in
dev) echo "OK: dev 允许从 $BRANCH 部署" ;;
*)
echo "ERROR: dev 只能从 dev 分支部署,当前分支是 '$BRANCH'"
echo "请切换到 dev 后再 Run workflow,并选择 environment=dev"
echo "(禁止用 master 代码部署到 lpt-dev,避免环境错配)"
exit 1
;;
esac
;;
*) *)
echo "ERROR: 未知 environment=$ENV" echo "ERROR: 未知 environment=$ENV"
exit 1 exit 1
+3 -3
View File
@@ -11,7 +11,7 @@
- 运行时:Node.js 20+ - 运行时:Node.js 20+
- 框架:Fastify 5 - 框架:Fastify 5
- LLM:SiliconFlow OpenAI 兼容接口(Qwen/Qwen2.5-32B-Instruct) - LLM:DeepSeek OpenAI 兼容接口(deepseek-flash / DeepSeek-V4.1-Flash)
- 运行时依赖:除 fastify 外无其他外部依赖 - 运行时依赖:除 fastify 外无其他外部依赖
## 项目结构 ## 项目结构
@@ -60,9 +60,9 @@ lpt-ai/src/
## LLM 配置 ## LLM 配置
```env ```env
LLM_API_URL=https://api.siliconflow.cn/v1/chat/completions LLM_API_URL=https://api.deepseek.com/v1/chat/completions
LLM_API_KEY= # 必填,未配置时 /health 返回 llmAvailable: false LLM_API_KEY= # 必填,未配置时 /health 返回 llmAvailable: false
LLM_MODEL=Qwen/Qwen2.5-32B-Instruct LLM_MODEL=deepseek-flash
LLM_TIMEOUT_MS=60000 # 单次 LLM 调用超时 LLM_TIMEOUT_MS=60000 # 单次 LLM 调用超时
PORT=5199 PORT=5199
``` ```
+3 -1
View File
@@ -8,7 +8,9 @@ RUN npx tsc
FROM node:20-alpine AS runner FROM node:20-alpine AS runner
WORKDIR /app WORKDIR /app
RUN apk add --no-cache curl # 固定容器时区:alpine 默认无 tzdata,必须先安装,TZ 才会生效
ENV TZ=Asia/Shanghai
RUN apk add --no-cache curl tzdata
COPY --from=builder /app/dist ./dist COPY --from=builder /app/dist ./dist
COPY package*.json ./ COPY package*.json ./
RUN npm ci --omit=dev --ignore-scripts RUN npm ci --omit=dev --ignore-scripts
-136
View File
@@ -1,136 +0,0 @@
# lpt-ai
LPT 学习进度跟踪系统的独立 AI 服务。将 LLM 相关能力从 Java 主服务中剥离,便于独立迭代、增加安全层与沙箱。
## 能力
| 端点 | 方法 | 说明 |
|------|------|------|
| `/health` | GET | 健康检查,返回 LLM 可用状态 |
| `/ai/tasks` | POST | 提交异步 AI 任务(聚合报告/生成导图/回忆对比) |
| `/ai/tasks/:taskId` | GET | 轮询任务状态和结果 |
| `/fetch-title` | GET | 抓取 URL 页面标题 |
| `/admin` | GET | 管理面板(任务日志、Prompt 调试) |
## 快速开始
```bash
cp .env.example .env
# 编辑 .env,填入 LLM_API_KEY
npm install
npm run dev
```
未配置 `LLM_API_KEY` 时服务可启动,但 AI 端点返回 503,由调用方(Java 后端)降级到内置规则。
## 异步任务架构
由于 LLM 调用耗时长(可达数十秒),所有 AI 任务采用异步模式:
### 1. 提交任务
```bash
curl -X POST http://localhost:5199/ai/tasks \
-H "Content-Type: application/json" \
-d '{
"type": "aggregate-report",
"params": {
"taskName": "Java 并发编程",
"expectation": "理解线程池核心参数",
"fragments": [
{"content": "corePoolSize 是核心线程数,即使空闲也不回收"},
{"content": "workQueue 满了之后才会创建超过 core 的线程"}
]
}
}'
```
响应:
```json
{
"taskId": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending"
}
```
### 2. 轮询结果
```bash
curl http://localhost:5199/ai/tasks/550e8400-e29b-41d4-a716-446655440000
```
响应(进行中):
```json
{
"taskId": "550e8400-e29b-41d4-a716-446655440000",
"status": "running",
"progress": 50
}
```
响应(完成):
```json
{
"taskId": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"result": {
"summary": "本次学习主要掌握了线程池的核心参数配置...",
"keyPoints": ["corePoolSize 核心线程数", "workQueue 工作队列"]
}
}
```
### 3. 支持的任务类型
| type | 说明 | params 字段 |
|------|------|------------|
| `aggregate-report` | 聚合学习残片为报告 | `taskName`, `expectation`, `fragments[]` |
| `generate-mind-map` | 生成思维导图大纲 | `taskName`, `reports[]`, `applications[]` |
| `compare-recall` | 对比用户回忆与标准导图 | `taskName`, `standardOutline`, `recallOutline` |
## 架构位置
```
LPT 前端 (Vue) ──► LPT 后端 (Java/Spring Boot) ──► lpt-ai (TS/Fastify) ──► SiliconFlow API
```
Java 后端是唯一调用方;本服务不直接暴露给前端,不做鉴权(部署在内网)。
## 任务队列机制
- 任务提交后进入内存队列,返回 taskId
- 后台异步执行,Java 端通过轮询获取结果
- 任务超时时间:5 分钟
- 任务结果保留时间:30 分钟(自动清理)
- 失败重试:无(由 Java 端决定是否重试或降级)
## 降级策略
```
AI 服务不可用
↓
Java 后端捕获 503/超时
↓
自动切换到内置生成器
↓
- 聚合报告:简单拼接残片
- 生成导图:按 session 分组 + 规则去重
- 回忆对比:字符串相似度匹配
```
确保系统在 AI 服务异常时仍可正常工作。
## 管理面板
访问 `http://localhost:5199/admin` 查看:
- 任务执行日志(状态、耗时、token 消耗)
- Prompt 模板预览与调试
- 队列状态监控
## 后续规划
- 输入内容安全过滤(Prompt 注入防护)
- 输出审核
- 多模型路由(按任务复杂度选择模型)
- 用量与成本监控
- SSE 流式输出
+3 -3
View File
@@ -1,5 +1,5 @@
/** /**
* LLM 客户端 — SiliconFlow OpenAI 兼容接口 * LLM 客户端 — DeepSeek OpenAI 兼容接口
* *
* 设计要点: * 设计要点:
* - Key 从环境变量读取,永不写入代码或日志 * - Key 从环境变量读取,永不写入代码或日志
@@ -21,9 +21,9 @@ export interface LlmConfig {
export function loadConfig(): LlmConfig { export function loadConfig(): LlmConfig {
return { return {
apiUrl: process.env.LLM_API_URL ?? "https://api.siliconflow.cn/v1/chat/completions", apiUrl: process.env.LLM_API_URL ?? "https://api.deepseek.com/v1/chat/completions",
apiKey: process.env.LLM_API_KEY ?? "", apiKey: process.env.LLM_API_KEY ?? "",
model: process.env.LLM_MODEL ?? "Qwen/Qwen2.5-32B-Instruct", model: process.env.LLM_MODEL ?? "deepseek-flash",
timeoutMs: Number(process.env.LLM_TIMEOUT_MS ?? 120000), timeoutMs: Number(process.env.LLM_TIMEOUT_MS ?? 120000),
}; };
} }
+10 -6
View File
@@ -13,7 +13,7 @@ export interface FragmentInput {
/** /**
* 残片聚合为学习报告。 * 残片聚合为学习报告。
* 原则:报告是写给"未来复习的自己"的,保留具体知识点,剔除口语碎屑; * 原则:报告是写给"未来复习的自己"的,保留具体知识点,剔除口语碎屑;
* 不虚构残片中不存在的内容。 * 不虚构残片中不存在的内容;对抽象概念补充正反例子以明确边界。
*/ */
export function aggregateReportPrompt( export function aggregateReportPrompt(
taskName: string, taskName: string,
@@ -34,12 +34,16 @@ export function aggregateReportPrompt(
content: [ content: [
"你是一名学习记录整理助手。用户在一次学习会话中随手记录了若干学习残片,", "你是一名学习记录整理助手。用户在一次学习会话中随手记录了若干学习残片,",
"请将它们整理为一份简洁的学习报告。要求:", "请将它们整理为一份简洁的学习报告。要求:",
"1. 只基于残片内容,不虚构、不扩写残片中没有的知识;", "1. 只基于残片内容,不虚构残片中不存在的知识;",
"2. 保留具体的知识点、概念、结论,去掉口语化的碎屑;", "2. 保留具体的知识点、概念、结论,去掉口语化的碎屑;",
"3. 按逻辑而非时间组织内容,相关的点合并;", "3. 对残片中的抽象概念或知识,除定义/要点外,再补充一组正反例子,",
"4. 报告以要点形式呈现,控制在 300 字以内;", " 用「是X:…;不是X:…」的形式列出具体具象,帮助明确概念边界;",
"5. 如果提供了学习预期,在报告末尾用一句话说明本次学习与预期的差距(完成/部分完成/未涉及);", " 例如:奇数(也叫单数)是不能被 2 整除的整数;是奇数:1、3、5、7;不是奇数:2、4、6、8;",
"6. 直接输出报告正文,不要输出「报告如下」之类的引导语。", " 例子只用于解释残片已有的抽象内容,不引入新的知识点;",
"4. 按逻辑而非时间组织内容,相关的点合并;",
"5. 报告以要点形式呈现,因包含示例,目标 600 字左右,不超过 1000 字;",
"6. 如果提供了学习预期,在报告末尾用一句话说明本次学习与预期的差距(完成/部分完成/未涉及);",
"7. 直接输出报告正文,不要输出「报告如下」之类的引导语。",
].join(""), ].join(""),
}, },
{ {