Files
lpt-ai/AGENTS.md
T

200 lines
9.8 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 任务。
> **版本耦合警告**:本服务的 `/ai/tasks` 入参与任务结果字段**直接对接着 lpt-be**。
> 改 `aggregate-report` 的结果字段(曾经把 `report` 字符串改成 `{sessionSummary,expectationVerdict,freeSummary}`)
> 或 `generate-mind-map` 的 `reports` 入参形状(曾经从 `string[]` 改成对象数组)时,
> 必须同时确认 lpt-be 侧已经能读新形状;否则旧版 lpt-be 读不到字段会**静默降级**,界面无报错。
> 具体做法:两边同分支同环境一起发(`dev` 配 `dev`、`master` 配 `master`),不要跨环境出包。
## 规则与技能位置
- 通用规则(跨仓库):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 接口,返回正文 + token 用量)
│ ├── usage.ts → 用量归一化(null 与 0 区分、跨尝试累加)
│ ├── thinking.ts → 按 prompt 长度选思考强度(reasoning_effort)
│ ├── retry.ts → 退避重试(哪些错误可重试、等多久)
│ ├── prompts.ts → Prompt 模板(4 种任务类型)
│ └── prompts.test.ts
├── task-queue.ts → 异步任务队列(Worker 池 + 幂等复用 + 用量归集)
├── task-queue.test.ts
└── admin/
├── index.ts → 管理面板路由
├── routes.ts
├── store.ts → 日志存储(环形缓冲 + 原子落盘)
├── pricing.ts → 计价(DeepSeek 三档单价 + 峰谷时段)
├── reporter.ts → 用量上报(lpt-ai → lpt-be,本地 outbox 重试)
└── balance.ts → 上游余额查询(对账用)
```
## API 端点(6 个)
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查(返回 LLM 可用状态和模型名) |
| POST | `/ai/tasks` | 提交异步任务(返回 taskId) |
| GET | `/ai/tasks/:taskId` | 轮询任务结果 |
| POST | `/fetch-title` | 抓取网页标题 |
| GET | `/admin` | 管理面板(最近 500 条日志、用量与计价快照) |
| GET | `/admin/usage/balance` | 上游账户余额(对账用;未配置时 `configured:false`) |
## 用量统计
用量是「任务级」口径,不是「请求级」:一个任务重试 N 次就是 N 次计费。
- `llm/usage.ts`:把上游 `usage` 归一成 6 个维度(输入/输出/总计/缓存命中/缓存未命中/推理)。
**`null` 表示上游未上报,与「明确上报为 0」不同**,面板上必须区分显示。
- `task-queue.ts`:跨所有尝试累加用量(含失败尝试,如上游 200 但内容为空);`attempts` 是实际发起的调用次数。
- `admin/pricing.ts`:DeepSeek 三档单价(缓存命中/未命中/输出,USD per 1M)+ 峰谷时段。
峰时窗口按 UTC 判定(`01:00-04:00`、`06:00-10:00`,周一至周五),谷时 = 峰时 × 0.5。
计价结果在结算时**冻结进日志快照**,改价不会重算历史账。
- `admin/reporter.ts`:把用量推给 lpt-be(长期账本)。上报失败先落本地 outbox 再重试,
幂等靠 `record_id` 唯一索引;4xx 属于确定性拒绝,丢弃这批并计数,不无限重试。
未配置 `LPT_AI_REPORT_URL` 时为空操作。
- **权威口径在 lpt-be 的 MySQL**;本地面板只是最近 500 条的调试视图。
### 用量归属(callerRef)
lpt-ai 不知道调用方是谁,所以归属标记由调用方带过来:`POST /ai/tasks` 接受顶层可选字段
`callerRef`(lpt-be 传的是用户 id),结算时原样写进用量记录,lpt-be 据此做用户维度报表。
三条硬约束,改动时必须守住:
1. **不放进 `params`** —— 会污染 prompt 模板的输入;
2. **不参与幂等键** —— 否则同一份输入会因为调用方不同而重复调 LLM;
3. **不进入 prompt** —— 它只是记账标记。
复用已有任务时**沿用原任务的 `callerRef`**:那次 LLM 调用只发生了一次,账算在原调用方头上;
复用方没有产生新的 token 消耗,也不会有新的用量记录。
> `/admin` 用 `?token=…` 首次打开时会换发 `HttpOnly` cookie,否则面板 HTML 与它内部的
> `fetch` 是两个独立请求,内部请求会全部 401。详见 `roles/security-and-degradation.md`。
## 支持的任务类型
| 类型 | 说明 | 温度 | Max Tokens |
|------|------|------|------------|
| `aggregate-report` | 残片聚合为学习报告 | 0.3 | 2048 |
| `generate-mind-map` | 从报告/残片生成思维导图大纲 | 0.3 | 4096 |
| `compare-recall` | 用户回忆 vs 标准导图语义对比 | 0.2 | 4096 |
| `guidance` | 学习引导多轮对话 | 0.7 | 1024 |
| `guidance` | 学习引导单轮追问 | 0.7 | 1024 |
> 思考强度(`reasoning_effort`)不按任务类型固定,而是按 **prompt 总字符数**(所有 message 正文之和)自适应:
> 低于 `LPT_AI_REASONING_LOW_AT` → `none`(直接关掉思考),之后依次 `low` / `high`,超过 `LPT_AI_REASONING_MAX_AT` → `max`。
> 原因是 DeepSeek 缺省 `high`,不显式指定则短输入也会满档思考。映射实现在 `src/llm/thinking.ts`,阈值见 `.env.example`。
## 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_REASONING_ENABLED=true # 显式 false 才关闭自适应,回到供应商默认
LPT_AI_REASONING_LOW_AT=500 # 达到该长度起用 low,低于则为 none
LPT_AI_REASONING_HIGH_AT=2000 # 达到该长度起用 high
LPT_AI_REASONING_MAX_AT=8000 # 达到该长度起用 max
# 任务队列(完整注释见 .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)
# 用量统计(完整注释见 .env.example)
LLM_BALANCE_URL= # 留空按 LLM_API_URL 的 origin 推导
LLM_PRICE_CACHE_HIT_PER_M=0.006
LLM_PRICE_CACHE_MISS_PER_M=0.3
LLM_PRICE_OUTPUT_PER_M=1.2
LLM_PRICE_OFFPEAK_FACTOR=0.5
LLM_PRICE_PEAK_WINDOWS=01:00-04:00,06:00-10:00
LLM_PRICE_PEAK_HOLIDAYS= # 中国法定节假日,每年需要更新
# 用量上报(lpt-ai → lpt-be);留空表示不上报,只保留本地面板
LPT_AI_REPORT_URL=
LPT_AI_REPORT_TOKEN=
```
> 部署侧的变量在 `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-fe` 同规则,**一个分支对一个环境**,靠分支而不是靠参数区分:
| 分支 | 环境 | namespace | 镜像 tag |
|------|------|-----------|----------|
| `dev` | 开发 | `lpt-dev` | `lpt-ai:dev` |
| `master` | 生产 | `lpt-prod` | `lpt-ai:prod` |
- 发版在 Gitea 上手动触发 `lpt-ai Build & Deploy`(`workflow_dispatch`),选择 `environment`。
- 流水线第一步会校验**分支 ↔ 环境**:从 `dev` 发 `prod`、或从 `master` 发 `dev` 都会被直接拒绝。
- 例外:`main` 仅作为历史分支保留在 `7c751bf`(prod 冻结点),不再用于发版。
- 日常开发在 `dev`;需要上生产时,把 `dev` 合并进 `master`,并**同步升级 lpt-be**(见顶部版本耦合警告)。
## 关联项目
| 项目 | 路径 | 端口 | 说明 |
|------|------|------|------|
| 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)
```