Files
lpt-ai/AGENTS.md
T

117 lines
4.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# LPT AI 服务(lpt-ai)
> TypeScript + Fastify 独立 AI 服务,集成 DeepSeek LLM,为后端提供异步 AI 任务。
## 规则与技能位置
- 通用规则(跨仓库):meta 仓库 `.agents/roles/`
- 本仓库专属规则:`roles/`
- `roles/task-queue.md`:任务队列设计(含「不要改动的契约」)
- `roles/security-and-degradation.md`:安全边界与降级策略
- 本仓库专属技能:本仓库暂无专属技能目录
- Git 提交规范属通用规则,见 meta 仓库 `.agents/roles/commit-convention.md`,本文件不再重复。
## 技术栈
- 运行时:Node.js 20+
- 框架:Fastify 5
- LLM:DeepSeek OpenAI 兼容接口(`deepseek-flash`)
- 运行时依赖:除 fastify 外无其他外部依赖
## 项目结构
```text
lpt-ai/src/
├── index.ts → 服务入口(加载 .env,启动 Fastify)
├── routes/ai.ts → AI 路由(health, tasks, fetch-title)
├── llm/
│ ├── client.ts → LLM 客户端(DeepSeek 接口)
│ ├── retry.ts → 退避重试(哪些错误可重试、等多久)
│ ├── prompts.ts → Prompt 模板(3 种任务类型)
│ └── prompts.test.ts
├── task-queue.ts → 异步任务队列(Worker 池 + 幂等复用)
├── task-queue.test.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 |
## LLM 配置
```env
LLM_API_URL=https://api.deepseek.com/v1/chat/completions
LLM_API_KEY= # 必填,未配置时 /health 返回 llmAvailable: false
LLM_MODEL=deepseek-flash
LLM_TIMEOUT_MS=60000 # 单次 LLM 调用超时
PORT=5199
# 任务队列(完整注释见 .env.example)
LPT_AI_CONCURRENCY=2 # Worker 池并发度
LPT_AI_MAX_ATTEMPTS=3 # 单任务总尝试次数(含首次)
LPT_AI_RETRY_BASE_MS=1000 # 退避首次等待,之后 ×2
LPT_AI_RETRY_MAX_MS=20000 # 单次退避上限
LPT_AI_RESULT_CACHE_MS=600000 # 已完成结果可被相同请求复用的窗口
# 安全(完整注释见 .env.example)
LPT_AI_TOKEN= # 入站令牌:设置后 /ai/* 与 /admin 都要求携带(留空=不校验)
LPT_AI_RATE_LIMIT=30 # 每来源每窗口允许提交的 AI 任务数
LPT_AI_RATE_WINDOW_MS=60000 # 限流窗口
LPT_AI_BODY_LIMIT_BYTES=262144 # 请求体上限
LPT_AI_FETCH_ALLOWED_PORTS= # 抓取允许的额外端口(默认只有 80/443)
```
> 部署侧的变量在 `lpt-infra` 的 `dev/`、`prod/` configmap 里;本服务只读环境变量,默认值写在 `src/llm/client.ts` 与 `loadQueueConfig()` 里。
## 启动命令
```bash
npm install
npm run dev # 开发模式(tsx watch,热重载)
npm run build # 编译 TypeScript
npm run start # 生产模式
npm run test # 测试
npm run typecheck # 同时校验 src 与测试文件
```
> `tsconfig.json` 排除 `*.test.ts`(不入打包产物),因此测试的类型检查走单独的 `tsconfig.test.json`;
> 新增测试后靠 `npm run typecheck` 把关,不要只跑 `tsc --noEmit`。
## 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 前端,不直接调用本服务 |
## 调用关系
```text
lpt-be (5157) ──HTTP POST /ai/tasks──→ lpt-ai (5199)
lpt-be (5157) ──HTTP GET /ai/tasks/:id──→ lpt-ai (5199)
```