Author SHA1 Message Date
cat-shark 0d27ee84d9 fix: 部署流水线改用 https 拉取代码(Gitea 已不再监听 80 端口) 2026-11-08 14:48:34 +08:00
cat-shark 1c8a846635 docs: 记录 dev/master 两侧的硬契约差异 2026-11-08 14:37:23 +08:00
cat-shark 499e218072 docs: 补充分支与发布口径与后端版本耦合警告 2026-11-08 14:36:34 +08:00
cat-shark 4a667a5d91 chore: 部署流水线按环境绑定分支(dev/master) 2026-11-08 14:36:29 +08:00
cat-shark 0c0c5be299 feat: 导图生成支持携带同源报告作为参考 2026-10-22 21:55:36 +08:00
cat-shark 4aff5c03fe feat: 用量归属支持 callerRef 透传
- POST /ai/tasks 接受顶层可选 callerRef(限 64 字符),不进入 params、不参与幂等键、不进 prompt
- 结算时写进用量记录,lpt-be 据此做用户维度报表
- 复用已有任务时沿用原归属:那次 LLM 调用只发生一次,账算在原调用方头上
2026-10-10 20:08:51 +08:00
cat-shark 935f4781a4 feat: 采集 LLM token 用量并上报 lpt-be
- 客户端解析上游 usage(含 DeepSeek 缓存命中/未命中),跨重试累加
- 新增计价表(三档单价 + 峰谷时段),费用在结算时冻结
- 新增用量上报与本地 outbox 重试;4xx 判定为确定性拒绝,不无限重试
- 面板补充 Token/费用/调用次数与计价快照
- 顺带修复面板内联脚本转义错误(模板字面量吃掉 \n 与 \',面板一直空白)
2026-10-10 18:46:01 +08:00
cat-shark fd1193a66f perf: LLM 按 prompt 长度自适应思考强度 2026-10-10 17:53:41 +08:00
cat-shark 09d16dfb98 docs: 规则分离到 roles 目录 2026-10-10 15:08:45 +08:00
cat-shark a70625267d docs: 通用规则收口径到 meta 的 .agents/roles 2026-10-10 14:38:43 +08:00
cat-shark 1e1b101a46 docs: 补充并行与委派规则 2026-10-10 14:27:43 +08:00
cat-shark fb3c6f9933 feat: 新增学习引导提示词与任务类型 2026-10-09 19:26:50 +08:00
cat-shark e359e58ff2 feat: 导图改用知识碎片素材并输出结构化报告草稿 2026-10-09 19:12:04 +08:00
cat-shark 1c3168277d docs: 补充安全边界与新增环境变量 2026-10-09 15:52:25 +08:00
cat-shark f091fe691d feat: 加固标题抓取并加上限流与可选入站令牌 2026-10-09 15:51:50 +08:00
cat bf56c2bd46 feat: 任务队列改为并发池并支持幂等复用与退避重试 2026-10-08 17:32:34 +08:00
39 changed files with 5583 additions and 267 deletions
+76 -4
View File
@@ -1,11 +1,83 @@
# LLM 提供商配置(SiliconFlow OpenAI 兼容接口)
LLM_API_URL=https://api.siliconflow.cn/v1/chat/completions
# LLM 提供商配置(DeepSeek OpenAI 兼容接口)
LLM_API_URL=https://api.deepseek.com/v1/chat/completions
# API Key(必填,未配置时服务返回 503)
LLM_API_KEY=
# 模型名(32B 级别即可满足残片聚合需求)
LLM_MODEL=Qwen/Qwen2.5-32B-Instruct
# 模型名(轻量快速即可满足残片聚合需求)
LLM_MODEL=deepseek-flash
# 请求超时(毫秒)
LLM_TIMEOUT_MS=60000
# ---- 思考强度自适应(reasoning_effort)----
# DeepSeek 的 reasoning_effort 缺省是 high,不显式指定就每次满档思考。
# 这里按 prompt 总字符数(所有 message 正文之和)选档,短输入直接 none 关掉思考。
# 显式写 false 才关闭自适应(回到供应商默认);换到不支持该字段的供应商时用得上。
LPT_AI_REASONING_ENABLED=true
# 长度达到该值起用 low;低于它一律 none(不思考)
LPT_AI_REASONING_LOW_AT=500
# 长度达到该值起用 high
LPT_AI_REASONING_HIGH_AT=2000
# 长度达到该值起用 max
LPT_AI_REASONING_MAX_AT=8000
# 服务端口
PORT=5199
# ---- 任务队列 ----
# 并发处理的任务数。设得越高吞吐越高,但要注意 LLM 服务商的限流配额
LPT_AI_CONCURRENCY=2
# 单个任务的总尝试次数(含首次);1 表示不重试
LPT_AI_MAX_ATTEMPTS=3
# 退避重试的首次等待(毫秒),之后按 2 倍增长
LPT_AI_RETRY_BASE_MS=1000
# 单次退避上限(毫秒)
LPT_AI_RETRY_MAX_MS=20000
# 完成记录的保留时长(毫秒)
LPT_AI_TTL_MS=3600000
# 已完成结果可被相同请求复用的时间窗口(毫秒)
LPT_AI_RESULT_CACHE_MS=600000
# 过期记录清理间隔(毫秒)
LPT_AI_CLEANUP_MS=300000
# ===== 安全(安全-03)=====
# 入站令牌:设置后 /ai/* 与 /admin 都要求携带(header x-api-token 或 query token)。
# 留空表示不校验,开发阶段可以不管;生产往 lpt-secrets 加 lpt-ai-token 即可生效。
LPT_AI_TOKEN=
# AI 任务限流:每来源在窗口内允许的提交次数(单进程内存计数,粗粒度保护)
LPT_AI_RATE_LIMIT=30
LPT_AI_RATE_WINDOW_MS=60000
# 请求体上限(字节)
LPT_AI_BODY_LIMIT_BYTES=262144
# 抓取标题允许的额外端口(逗号分隔);默认只允许 80/443
LPT_AI_FETCH_ALLOWED_PORTS=
# ===== 用量统计 =====
# 上游余额对账地址;留空时按 LLM_API_URL 的 origin 推导(DeepSeek 为 /user/balance)。
# 余额只是辅助信息,查询失败不会影响用量面板。
LLM_BALANCE_URL=
LLM_BALANCE_TIMEOUT_MS=10000
# 计价表(USD / 1M tokens,填 DeepSeek 官方 PEAK 一列)
LLM_PRICE_CACHE_HIT_PER_M=0.006
LLM_PRICE_CACHE_MISS_PER_M=0.3
LLM_PRICE_OUTPUT_PER_M=1.2
# 谷时价 = 峰时价 × 该系数;设为 1 即取消峰谷差异
LLM_PRICE_OFFPEAK_FACTOR=0.5
# 峰时窗口(UTC,HH:mm-HH:mm,逗号分隔);留空回退到 DeepSeek 公布的 01:00-04:00,06:00-10:00
LLM_PRICE_PEAK_WINDOWS=01:00-04:00,06:00-10:00
# 按谷时计价的日期(UTC 的 yyyy-MM-dd,逗号分隔),用于中国法定节假日;每年需要更新
LLM_PRICE_PEAK_HOLIDAYS=
# 计价表版本;留空时由单价自动派生(改价即变版本,历史账不会被新价格重算)
LLM_PRICE_VERSION=
# ---- 用量上报(lpt-ai → lpt-be)----
# lpt-be 基地址;留空表示不上报,用量只保留在本地面板(没有长期账本,Pod 重建即丢)
LPT_AI_REPORT_URL=
# 与 lpt-be 的 lpt.ai-usage.report-token 一致
LPT_AI_REPORT_TOKEN=
# 定时推送间隔(毫秒);上报失败会留在本地 outbox 里重试,不会丢数据
LPT_AI_REPORT_INTERVAL_MS=15000
# 单次推送条数上限
LPT_AI_REPORT_BATCH_SIZE=50
# outbox 上限;超过后丢弃最旧的,避免磁盘被写满
LPT_AI_REPORT_MAX_PENDING=5000
LPT_AI_REPORT_TIMEOUT_MS=10000
+26 -13
View File
@@ -4,7 +4,7 @@ on:
workflow_dispatch:
inputs:
environment:
description: '部署环境(本仓库仅 main 分支;dev/prod 均从 main 部署)'
description: '部署环境(dev 仅允许 dev 分支;prod 仅允许 master 分支)'
required: true
type: choice
options:
@@ -14,7 +14,7 @@ on:
env:
REGISTRY: 192.168.123.199:5000
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:
build-and-deploy:
@@ -33,18 +33,31 @@ jobs:
fi
ENV="${{ inputs.environment }}"
echo "branch=$BRANCH environment=$ENV sha=${{ gitea.sha }}"
# lpt-ai 仅维护 main:dev/prod 都从 main 出包,靠 environment 区分 namespace/镜像 tag
case "$BRANCH" in
main|master)
echo "OK: lpt-ai 从 $BRANCH 部署到 $ENV"
;;
*)
echo "ERROR: lpt-ai 只能从 main/master 部署,当前分支是 '$BRANCH'"
exit 1
;;
esac
# lpt-ai 与 lpt-be/lpt-fe 同规则:master 发 prod,dev 发 dev。
# 不允许跨环境出包:本服务的入参/出参结构与 lpt-be 的版本强耦合,
# 把 dev 的代码推到 prod 会让旧版 lpt-be 读到不认识的字段(静默降级)。
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"
exit 1
+119 -24
View File
@@ -1,37 +1,54 @@
# LPT AI 服务(lpt-ai)
> TypeScript + Fastify 独立 AI 服务,集成 SiliconFlow LLM,为后端提供异步 AI 任务。
> TypeScript + Fastify 独立 AI 服务,集成 DeepSeek LLM,为后端提供异步 AI 任务。
## Git 提交规范
> **版本耦合警告**:本服务的 `/ai/tasks` 入参与任务结果字段**直接对接着 lpt-be**。
> 改 `aggregate-report` 的结果字段(曾经把 `report` 字符串改成 `{sessionSummary,expectationVerdict,freeSummary}`)
> 或 `generate-mind-map` 的 `reports` 入参形状(曾经从 `string[]` 改成对象数组)时,
> 必须同时确认 lpt-be 侧已经能读新形状;否则旧版 lpt-be 读不到字段会**静默降级**,界面无报错。
> 具体做法:两边同分支同环境一起发(`dev` 配 `dev`、`master` 配 `master`),不要跨环境出包。
- 提交信息必须简短且使用中文,不要使用英文长句。
- 格式:`类型: 简述`,例如 `feat: 新增思维导图生成任务`、`fix: 修复任务队列TTL清理`、`docs: 补充环境变量说明`。
## 规则与技能位置
- 通用规则(跨仓库):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 / DeepSeek-V4.1-Flash)
- LLM:DeepSeek OpenAI 兼容接口(`deepseek-flash`)
- 运行时依赖:除 fastify 外无其他外部依赖
## 项目结构
```text
lpt-ai/src/
├── index.ts → 服务入口(加载 .env,启动 Fastify)
├── index.ts → 服务入口(加载 .env,启动 Fastify 与用量上报)
├── routes/ai.ts → AI 路由(health, tasks, fetch-title)
├── llm/
│ ├── client.ts → LLM 客户端(SiliconFlow 接口)
│ ├── prompts.ts → Prompt 模板(3 种任务类型)
│ ├── 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 → 异步任务队列
├── task-queue.ts → 异步任务队列(Worker 池 + 幂等复用 + 用量归集)
├── task-queue.test.ts
└── admin/
├── index.ts → 管理面板路由
├── routes.ts
└── store.ts → 日志存储
├── store.ts → 日志存储(环形缓冲 + 原子落盘)
├── pricing.ts → 计价(DeepSeek 三档单价 + 峰谷时段)
├── reporter.ts → 用量上报(lpt-ai → lpt-be,本地 outbox 重试)
└── balance.ts → 上游余额查询(对账用)
```
## API 端点(5 个)
## API 端点(6 个)
| 方法 | 路径 | 说明 |
|------|------|------|
@@ -39,7 +56,40 @@ lpt-ai/src/
| POST | `/ai/tasks` | 提交异步任务(返回 taskId) |
| GET | `/ai/tasks/:taskId` | 轮询任务结果 |
| POST | `/fetch-title` | 抓取网页标题 |
| GET | `/admin` | 管理面板(查看最近 200 条日志) |
| 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`。
## 支持的任务类型
@@ -48,14 +98,12 @@ lpt-ai/src/
| `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 |
## 任务队列设计
- 异步任务模式:submit + poll,避免 LLM 长耗时(10-60s)超时。
- 单线程 Worker:`setImmediate` 链,同一时刻只处理一个 LLM 调用,防止 API 限流。
- TTL 清理:5 分钟一次,移除完成超过 1 小时的记录。
- 异常隔离:单个任务失败不影响后续任务。
- 管理面板日志:复用 `logStore`,记录最近 200 条请求/响应。
> 思考强度(`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 配置
@@ -65,13 +113,42 @@ LLM_API_KEY= # 必填,未配置时 /health 返回 llmAvaila
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=
```
## 降级策略
- LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`。
- 后端(lpt-be)检测到 AI 不可用 → 自动切换到内置规则引擎(`BuiltinMindMapGenerator`)。
- Java 后端是唯一调用方;本服务不直接暴露给前端,不做鉴权(部署在内网)。
> 部署侧的变量在 `lpt-infra` 的 `dev/`、`prod/` configmap 里;本服务只读环境变量,默认值写在 `src/llm/client.ts` 与 `loadQueueConfig()` 里。
## 启动命令
@@ -81,14 +158,32 @@ 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**(见顶部版本耦合警告)。
## 关联项目
| 项目 | 路径 | 端口 | 说明 |
+2 -2
View File
@@ -9,7 +9,7 @@
"build": "tsc",
"start": "node --env-file=.env dist/index.js",
"test": "vitest run",
"typecheck": "tsc --noEmit"
"typecheck": "tsc --noEmit && tsc -p tsconfig.test.json"
},
"dependencies": {
"fastify": "^5.2.0"
@@ -23,4 +23,4 @@
"engines": {
"node": ">=20"
}
}
}
+31
View File
@@ -0,0 +1,31 @@
# 安全边界与降级策略
- **功能**:说明 lpt-ai 的入站令牌、限流、抓取加固、`/admin` 暴露边界,以及 LLM 不可用时的降级路径。
- **何时用**:改动鉴权、限流、`/fetch-title` 抓取逻辑、`/admin` 暴露范围,或处理 LLM 不可用 / 降级行为时。
## 安全边界
本服务是 `ClusterIP` 且未被 Traefik 路由,公网不可达;但集群内任何工作负载都能访问它,因此仍有防护:
- **入站令牌(可选)**:设置 `LPT_AI_TOKEN` 后,`/ai/*` 与 `/admin` 都要求携带,按 header `x-api-token` → query `token` → cookie `lpt_ai_token` 的优先级取值。
cookie 这一路是给面板用的:面板 HTML 与它后续的 `fetch` 是两个独立请求,只在 URL 上带令牌会让 HTML 打得开而内部请求全部 401。
用 `/admin?token=…` 首次访问时换发一个 `HttpOnly; SameSite=Strict; Path=/admin` 的 cookie(依赖零新增依赖的手写 `set-cookie`)。
部署清单用 `secretKeyRef.optional: true` 引用 `lpt-secrets/lpt-ai-token`,**没设这个 key 也能正常启动**(此时不校验)。
`lpt-be` 侧由 `lpt.ai-service.token` 提供,部署经 `LPT_AI-SERVICE_TOKEN` 注入。
开发阶段可以不设,保持零摩擦;生产只需往 secret 加一个 key。
- **限流**:`/ai/tasks` 按来源限流(默认 30 次/分钟),因为是单进程内存计数,属于粗粒度保护,不是精确配额。
- **抓取加固**:`/fetch-title` 的目标由调用方给出,抓取前做四层校验 —— 协议白名单、端口白名单、**DNS 解析后逐个校验**(防解析到内网与 DNS rebinding)、**重定向逐跳校验**(防「首跳合法、次跳内网」);响应体截断到 512 KiB,且只在网页类型上取标题。
- `/admin` 面板会展示完整 prompt 与学习内容,未设置令牌时会启动告警提示。
- **用量上报出口**:`POST {lpt-be}/internal/ai-usage/records`,用 `LPT_AI_REPORT_TOKEN` 与 lpt-be 的 `lpt.ai-usage.report-token` 对接。
上报载荷只含 token 计数、费用与任务元信息,**不含 prompt 与学习内容**。未配置 `LPT_AI_REPORT_URL` 时不上报。
- **面板的用量统计口径是「最近 500 条」**(`data/logs.json` 环形缓冲),长期账本在 lpt-be 的 MySQL。
面板与前端页面数字不一致时,以前端页面为准。
> `/fetch-title` 当前**全工作区零调用**(`lpt-fe` 走的是 `lpt-be` 的 `/utils/fetch-title`,用 Java 侧 `TitleFetcher`)。
> 保留它是为了满足安全条目的验收;如需精简可连同本文件的抓取工具一并删除。
## 降级策略
- LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`。
- 后端(lpt-be)检测到 AI 不可用 → 自动切换到内置规则引擎(`BuiltinMindMapGenerator`)。
- Java 后端是唯一调用方;本服务不直接暴露给前端(Service 是 `ClusterIP`,且 Traefik 未路由本服务)。
+43
View File
@@ -0,0 +1,43 @@
# 任务队列
- **功能**:定义 lpt-ai 异步任务队列(Worker 池、退避重试、相同输入幂等复用、TTL 清理)的行为与不可改契约。
- **何时用**:改动 `/ai/tasks` 的提交/轮询、并发度、重试、幂等复用、TTL 清理、管理面板日志,或调整任务响应契约与单次调用参数(温度 / 思考强度)时。
## 任务队列设计
- 异步任务模式:submit + poll,避免 LLM 长耗时(10-60s)超时。
- **Worker 池**:并发度由 `LPT_AI_CONCURRENCY` 控制(默认 2)。
不要改回单 worker 串行:N 个请求会等 N × LLM 耗时,客户端会先超时。
- **退避重试**:429 / 5xx / 超时等瞬时抖动会重试(`LPT_AI_MAX_ATTEMPTS`,默认 3),
4xx 客户端错误与「API Key 未配置」不重试。服务端返回的 `Retry-After` 优先于自算退避。
- **相同输入复用**:以 `type + params` 的稳定哈希为幂等键。
- 同键任务 pending/running → 合并为同一个任务,不重复调用 LLM(不重复计费)
- 同键任务已完成且在 `LPT_AI_RESULT_CACHE_MS` 窗口内 → 复用结果
- 同键任务已失败 → 新建(失败必须可重试)
- 请求体传 `force: true` 可跳过复用(用户主动「重新生成」)
- 也可传 `idempotencyKey` 显式指定幂等键
- TTL 清理:按 `LPT_AI_CLEANUP_MS` 周期移除过期记录,同时清理幂等索引。
- **单次调用参数**:温度与输出上限按任务类型固定;思考强度(`reasoning_effort`)按 prompt 总字符数自适应,
短输入直接 `none` 关掉思考(DeepSeek 缺省 `high`,不显式指定就会满档思考)。
调用参数不参与幂等键,改阈值不会让已有缓存失效。映射实现在 `src/llm/thinking.ts`。
- 异常隔离:单个任务失败不影响后续任务。
- 管理面板日志:复用 `logStore`,记录最近 200 条请求/响应。
### 不要改动的契约
- `/ai/tasks` **必须固定返回 201**。Java 端 `AiServiceClient.submitTask()` 把非 201 视为提交失败,
所以不能用 200 表达「复用了已有任务」;复用信息放在响应体的 `reused` / `status` 字段里。
- `TaskRecord` 的 `status` / `result` / `error` 字段名被 Java 端轮询逻辑依赖,新增字段可以,改名不行。
### 跨分支契约差异(`dev` 与 `master` 配对不同的 lpt-be)
**分支即契约版本**:`dev` 配 lpt-be `dev`,`master` 配 lpt-be `master`。
下面两处是本仓库历史上唯一让旧版 lpt-be 静默降级的地方,改动前必须确认对应分支的 lpt-be 能读新形状。
| 能力 | `dev`(新 lpt-be) | `master`(旧 lpt-be) | 旧端读不到时的表现 |
|---|---|---|---|
| `aggregate-report` 结果 | `{sessionSummary, expectationVerdict, freeSummary, model}` | `{report: "<纯文本>", model}` | 旧 be 读 `result.report` 得 null → 降级为内置按序拼接,界面无报错 |
| `generate-mind-map` 的 `reports` 入参 | 对象数组 `{ref, taskName, sessionSummary, expectationVerdict, freeSummary}` | `string[]`(纯报告正文) | 新提示词把字符串渲染成 `[报告 undefined]`,报告正文被丢弃 |
- `compare-recall` 的入参(`taskName` / `standardOutline` / `recallOutline`)与结果 JSON 字段两侧一致,可放心改提示词但不要改字段名。
- 从 `dev` 合并到 `master`(= 上生产)时必须与 lpt-be 的升级同步进行。
+117
View File
@@ -0,0 +1,117 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { deriveBalanceUrl, fetchUpstreamBalance, loadBalanceConfig } from "./balance.js";
const originalKey = process.env.LLM_API_KEY;
const originalUrl = process.env.LLM_API_URL;
const originalBalanceUrl = process.env.LLM_BALANCE_URL;
afterEach(() => {
for (const [key, value] of [
["LLM_API_KEY", originalKey],
["LLM_API_URL", originalUrl],
["LLM_BALANCE_URL", originalBalanceUrl],
] as const) {
if (value === undefined) {
delete process.env[key];
} else {
process.env[key] = value;
}
}
});
describe("deriveBalanceUrl", () => {
it("从 chat completions 地址推导出同源余额地址", () => {
expect(deriveBalanceUrl("https://api.deepseek.com/v1/chat/completions")).toBe(
"https://api.deepseek.com/user/balance",
);
});
it("地址非法时返回空串,由调用方判定为不可用", () => {
expect(deriveBalanceUrl("not-a-url")).toBe("");
});
});
describe("loadBalanceConfig", () => {
it("显式配置优先于推导值", () => {
const config = loadBalanceConfig({
LLM_API_URL: "https://api.deepseek.com/v1/chat/completions",
LLM_BALANCE_URL: "https://proxy.test/balance",
});
expect(config.url).toBe("https://proxy.test/balance");
});
it("非法超时回退到缺省", () => {
expect(loadBalanceConfig({ LLM_BALANCE_TIMEOUT_MS: "-1" }).timeoutMs).toBe(10_000);
});
});
describe("fetchUpstreamBalance", () => {
it("未配置 API Key 时不发请求,直接返回未配置", async () => {
delete process.env.LLM_API_KEY;
const fetchImpl = vi.fn();
await expect(
fetchUpstreamBalance({ fetchImpl: fetchImpl as unknown as typeof fetch }),
).resolves.toEqual({ configured: false });
expect(fetchImpl).not.toHaveBeenCalled();
});
it("优先取人民币账户", async () => {
process.env.LLM_API_KEY = "key";
const fetchImpl = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
balance_infos: [
{ currency: "USD", total_balance: "1.00", granted_balance: "0", topped_up_balance: "1.00" },
{ currency: "CNY", total_balance: "12.34", granted_balance: "0.00", topped_up_balance: "12.34" },
],
}),
} as Response);
const result = await fetchUpstreamBalance({
fetchImpl: fetchImpl as unknown as typeof fetch,
now: () => Date.parse("2026-10-10T09:00:00Z"),
});
expect(result).toEqual({
configured: true,
currency: "CNY",
totalBalance: "12.34",
grantedBalance: "0.00",
toppedUpBalance: "12.34",
fetchedAt: "2026-10-10T09:00:00.000Z",
});
});
it("没有人民币账户时取第一条,不返回空余额", async () => {
process.env.LLM_API_KEY = "key";
const fetchImpl = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ balance_infos: [{ currency: "USD", total_balance: "1.00" }] }),
} as Response);
const result = await fetchUpstreamBalance({ fetchImpl: fetchImpl as unknown as typeof fetch });
expect(result.configured).toBe(true);
expect(result.currency).toBe("USD");
});
it("上游报错或响应缺字段时返回未配置,而不是抛错把面板打挂", async () => {
process.env.LLM_API_KEY = "key";
const failing = vi.fn().mockResolvedValue({ ok: false, status: 500 } as Response);
await expect(
fetchUpstreamBalance({ fetchImpl: failing as unknown as typeof fetch }),
).resolves.toEqual({ configured: false });
const empty = vi.fn().mockResolvedValue({ ok: true, json: async () => ({}) } as Response);
await expect(
fetchUpstreamBalance({ fetchImpl: empty as unknown as typeof fetch }),
).resolves.toEqual({ configured: false });
const throwing = vi.fn().mockRejectedValue(new Error("network down"));
await expect(
fetchUpstreamBalance({ fetchImpl: throwing as unknown as typeof fetch }),
).resolves.toEqual({ configured: false });
});
});
+109
View File
@@ -0,0 +1,109 @@
/**
* 上游账户余额查询(对账用)。
*
* 设计要点:
* - 本地算出来的费用只是**估算**:单价表可能过期、峰谷判定可能偏差。
* 拿上游余额的变化去比对,是唯一能发现「计价表已经不对了」的手段。
* - 余额接口是供应商特有的(DeepSeek 是 `GET /user/balance`),因此地址可配置,
* 默认按 `LLM_API_URL` 的 origin 推导,换供应商时不必改代码。
* - 查询失败一律返回 `configured:false` 而不是抛错:余额只是辅助信息,
* 不能因为它把用量面板整体打挂。
*/
export interface BalanceSnapshot {
/** false 表示未配置 API Key、供应商不支持或查询失败 */
configured: boolean;
currency?: string;
totalBalance?: string;
grantedBalance?: string;
toppedUpBalance?: string;
fetchedAt?: string;
}
export interface BalanceConfig {
url: string;
apiKey: string;
timeoutMs: number;
}
export interface BalanceDeps {
fetchImpl?: typeof fetch;
now?: () => number;
}
/** 从 chat completions 地址推导出同源的余额地址;推导不出来时返回空串 */
export function deriveBalanceUrl(apiUrl: string): string {
try {
return `${new URL(apiUrl).origin}/user/balance`;
} catch {
return "";
}
}
export function loadBalanceConfig(env: NodeJS.ProcessEnv = process.env): BalanceConfig {
const apiUrl = env.LLM_API_URL ?? "https://api.deepseek.com/v1/chat/completions";
const explicit = (env.LLM_BALANCE_URL ?? "").trim();
const timeoutRaw = Number(env.LLM_BALANCE_TIMEOUT_MS ?? 10_000);
return {
url: explicit.length > 0 ? explicit : deriveBalanceUrl(apiUrl),
apiKey: (env.LLM_API_KEY ?? "").trim(),
timeoutMs: Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 10_000,
};
}
interface DeepSeekBalanceResponse {
balance_infos?: Array<{
currency?: string;
total_balance?: string;
granted_balance?: string;
topped_up_balance?: string;
}>;
}
/** 优先取人民币账户;找不到就取第一条,避免多币种账户下返回空 */
function pickBalanceInfo(
infos: DeepSeekBalanceResponse["balance_infos"],
): NonNullable<DeepSeekBalanceResponse["balance_infos"]>[number] | undefined {
if (!infos || infos.length === 0) return undefined;
return infos.find((info) => info.currency === "CNY") ?? infos[0];
}
export async function fetchUpstreamBalance(
deps: BalanceDeps = {},
): Promise<BalanceSnapshot> {
const config = loadBalanceConfig();
if (config.apiKey.length === 0 || config.url.length === 0) {
return { configured: false };
}
const fetchImpl = deps.fetchImpl ?? fetch;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), config.timeoutMs);
try {
const response = await fetchImpl(config.url, {
method: "GET",
headers: { Authorization: `Bearer ${config.apiKey}` },
signal: controller.signal,
});
if (!response.ok) {
return { configured: false };
}
const data = (await response.json()) as DeepSeekBalanceResponse;
const info = pickBalanceInfo(data.balance_infos);
if (!info) {
return { configured: false };
}
return {
configured: true,
currency: info.currency ?? "",
totalBalance: info.total_balance ?? "",
grantedBalance: info.granted_balance ?? "",
toppedUpBalance: info.topped_up_balance ?? "",
fetchedAt: new Date(deps.now ? deps.now() : Date.now()).toISOString(),
};
} catch {
return { configured: false };
} finally {
clearTimeout(timer);
}
}
+19 -1
View File
@@ -1,2 +1,20 @@
export { logStore, type LogEntry, type LogSummary } from "./store.js";
export { logStore, resetLogStoreForTest, type LogEntry, type LogSummary } from "./store.js";
export { adminRoutes } from "./routes.js";
export {
UsageReporter,
usageReporter,
loadReporterConfig,
toUsageRecord,
type UsageRecord,
type ReporterConfig,
} from "./reporter.js";
export { fetchUpstreamBalance, type BalanceSnapshot } from "./balance.js";
export {
loadPricingConfig,
priceUsage,
isPeak,
parsePeakWindows,
type PricingConfig,
type PricingSnapshot,
type PricedUsage,
} from "./pricing.js";
+166
View File
@@ -0,0 +1,166 @@
import { describe, expect, it } from "vitest";
import { emptyUsage, type TokenUsage } from "../llm/usage.js";
import { isPeak, loadPricingConfig, parsePeakWindows, priceUsage } from "./pricing.js";
function usage(partial: Partial<TokenUsage>): TokenUsage {
return { ...emptyUsage(), ...partial };
}
/** 2026-10-09 是周五;10-10/10-11 是周末;10-12 是周一 */
function utc(iso: string): Date {
return new Date(iso);
}
describe("parsePeakWindows", () => {
it("解析 HH:mm-HH:mm 列表", () => {
expect(parsePeakWindows("01:00-04:00,06:00-10:00")).toEqual([
{ startMinute: 60, endMinute: 240 },
{ startMinute: 360, endMinute: 600 },
]);
});
it("单条格式写错只跳过这一条,其余窗口仍生效", () => {
expect(parsePeakWindows("01:00-04:00,bad,06:00-10:00")).toEqual([
{ startMinute: 60, endMinute: 240 },
{ startMinute: 360, endMinute: 600 },
]);
});
it("起止相同的窗口视为无效", () => {
expect(parsePeakWindows("01:00-01:00")).toEqual([]);
});
it("不传时回退到 DeepSeek 公布的默认窗口", () => {
expect(parsePeakWindows(undefined)).toHaveLength(2);
});
});
describe("isPeak", () => {
const config = loadPricingConfig({});
it("工作日落在峰时窗口内为峰时", () => {
expect(isPeak(utc("2026-10-09T02:00:00Z"), config)).toBe(true);
expect(isPeak(utc("2026-10-09T08:00:00Z"), config)).toBe(true);
});
it("工作日落在窗口外为谷时", () => {
expect(isPeak(utc("2026-10-09T00:30:00Z"), config)).toBe(false);
expect(isPeak(utc("2026-10-09T05:00:00Z"), config)).toBe(false);
expect(isPeak(utc("2026-10-09T12:00:00Z"), config)).toBe(false);
});
it("窗口右端开区间:04:00 整不算峰时", () => {
expect(isPeak(utc("2026-10-09T04:00:00Z"), config)).toBe(false);
});
it("周末一律谷时", () => {
expect(isPeak(utc("2026-10-10T02:00:00Z"), config)).toBe(false);
expect(isPeak(utc("2026-10-11T08:00:00Z"), config)).toBe(false);
});
it("配置为法定节假日的日期按谷时计价", () => {
const holiday = loadPricingConfig({ LLM_PRICE_PEAK_HOLIDAYS: "2026-10-12" });
expect(isPeak(utc("2026-10-12T02:00:00Z"), holiday)).toBe(false);
// 未列入的周一仍按峰时
expect(isPeak(utc("2026-10-12T02:00:00Z"), config)).toBe(true);
});
it("支持跨零点的窗口", () => {
const overnight = loadPricingConfig({ LLM_PRICE_PEAK_WINDOWS: "23:00-02:00" });
expect(isPeak(utc("2026-10-09T23:30:00Z"), overnight)).toBe(true);
expect(isPeak(utc("2026-10-09T01:00:00Z"), overnight)).toBe(true);
expect(isPeak(utc("2026-10-09T03:00:00Z"), overnight)).toBe(false);
});
});
describe("priceUsage", () => {
const config = loadPricingConfig({});
it("按峰时三档单价计价", () => {
const { costUsd, snapshot } = priceUsage(
usage({ cacheHitTokens: 1_000_000, cacheMissTokens: 1_000_000, completionTokens: 1_000_000 }),
utc("2026-10-09T02:00:00Z"),
config,
);
expect(snapshot.peak).toBe(true);
expect(costUsd).toBe(1.506);
});
it("谷时单价是峰时的一半", () => {
const { costUsd, snapshot } = priceUsage(
usage({ cacheHitTokens: 1_000_000, cacheMissTokens: 1_000_000, completionTokens: 1_000_000 }),
utc("2026-10-09T12:00:00Z"),
config,
);
expect(snapshot.peak).toBe(false);
expect(costUsd).toBe(0.753);
expect(snapshot.effectivePrices.cacheMissPerM).toBe(0.15);
expect(snapshot.listPrices.cacheMissPerM).toBe(0.3);
});
it("未上报用量时费用为 null,而不是 0", () => {
const { costUsd } = priceUsage(emptyUsage(), utc("2026-10-09T12:00:00Z"), config);
expect(costUsd).toBeNull();
});
it("没有缓存明细时把整个 prompt 按未命中价计,宁可高估也不低估", () => {
const { costUsd } = priceUsage(
usage({ promptTokens: 1_000_000, completionTokens: 0 }),
utc("2026-10-09T02:00:00Z"),
config,
);
expect(costUsd).toBe(0.3);
});
it("只有命中数没有未命中数时用 prompt - hit 兜底", () => {
const { costUsd } = priceUsage(
usage({ promptTokens: 1_000_000, cacheHitTokens: 400_000, completionTokens: 0 }),
utc("2026-10-09T02:00:00Z"),
config,
);
// 40 万命中 × 0.006 + 60 万未命中 × 0.3 = 0.0024 + 0.18
expect(costUsd).toBe(0.1824);
});
it("费用按 8 位小数收敛,避免浮点噪声写进 DECIMAL(18,8)", () => {
const { costUsd } = priceUsage(
usage({ promptTokens: 3, completionTokens: 7 }),
utc("2026-10-09T02:00:00Z"),
config,
);
expect(String(costUsd)).toMatch(/^\d+(\.\d{1,8})?$/);
});
});
describe("loadPricingConfig", () => {
it("缺省单价与官方 PEAK 一列一致", () => {
const config = loadPricingConfig({});
expect(config.cacheHitPerM).toBe(0.006);
expect(config.cacheMissPerM).toBe(0.3);
expect(config.outputPerM).toBe(1.2);
expect(config.offpeakFactor).toBe(0.5);
});
it("环境变量可覆盖单价,并让版本号随之变化", () => {
const base = loadPricingConfig({});
const changed = loadPricingConfig({ LLM_PRICE_OUTPUT_PER_M: "2.4" });
expect(changed.outputPerM).toBe(2.4);
// 版本号由单价派生,改价即变版本,避免历史账被新价格重算
expect(changed.version).not.toBe(base.version);
});
it("显式版本号优先于派生值", () => {
const config = loadPricingConfig({ LLM_PRICE_VERSION: "2026-11 调价" });
expect(config.version).toBe("2026-11 调价");
});
it("非法单价回退到缺省值", () => {
const config = loadPricingConfig({ LLM_PRICE_OUTPUT_PER_M: "abc", LLM_PRICE_CACHE_HIT_PER_M: "-1" });
expect(config.outputPerM).toBe(1.2);
expect(config.cacheHitPerM).toBe(0.006);
});
});
+231
View File
@@ -0,0 +1,231 @@
/**
* LLM 计价 —— DeepSeek 三档单价 + 峰谷时段。
*
* 设计要点:
* - **单价按「每百万 token 的美元价」配置**,不引入中转站那套倍率/钱包抽象:
* 本项目是单租户内部服务,没有余额可扣,倍率只会多一层浮点误差面。
* - **峰谷价差必须算进去**:DeepSeek 谷时价是峰时价的一半,而峰时只占工作日的 7 小时。
* 忽略它会将近一倍地高估费用(夜间与周末的调用全被按峰时价算)。
* - **计价结果要冻结**:价格表会变,历史账不能被新价格改写,所以结算时把生效单价与
* 是否峰时一并写进日志快照,而不是展示时现算。
* - **中国法定节假日按谷时计价**,但节假日表每年都变,因此做成配置项而不是硬编码日历。
*/
import { hasUsage, type TokenUsage } from "../llm/usage.js";
/** UTC 分钟数区间;`startMinute > endMinute` 表示跨零点 */
export interface PeakWindow {
startMinute: number;
endMinute: number;
}
export interface PricingConfig {
/** 峰时:缓存命中输入 token 单价(USD / 1M tokens) */
cacheHitPerM: number;
/** 峰时:缓存未命中输入 token 单价 */
cacheMissPerM: number;
/** 峰时:输出 token 单价 */
outputPerM: number;
/** 谷时价 = 峰时价 × 该系数;设为 1 即取消峰谷差异 */
offpeakFactor: number;
peakWindows: PeakWindow[];
/** 按谷时计价的日期(UTC 的 `yyyy-MM-dd`),用于中国法定节假日 */
offpeakDates: string[];
/** 计价表版本;不显式配置时由单价派生,改价即自动变版本 */
version: string;
}
export interface PricingSnapshot {
version: string;
peak: boolean;
/** 本次实际生效的单价(已含峰谷系数) */
effectivePrices: {
cacheHitPerM: number;
cacheMissPerM: number;
outputPerM: number;
};
/** 峰时标价,便于与账单核对 */
listPrices: {
cacheHitPerM: number;
cacheMissPerM: number;
outputPerM: number;
};
}
export interface PricedUsage {
/** 无法计价(上游完全没上报用量)时为 null,不要用 0 冒充 */
costUsd: number | null;
snapshot: PricingSnapshot;
}
/**
* DeepSeek 公布的峰时窗口(UTC,周一至周五):
* 01:00–04:00 与 06:00–10:00,其余时段(含周末与中国法定节假日)为谷时。
*/
const DEFAULT_PEAK_WINDOWS = "01:00-04:00,06:00-10:00";
/** 峰时单价(USD / 1M tokens),取自 DeepSeek 官方 Models & Pricing 的 PEAK 一列 */
const DEFAULT_CACHE_HIT_PER_M = 0.006;
const DEFAULT_CACHE_MISS_PER_M = 0.3;
const DEFAULT_OUTPUT_PER_M = 1.2;
/** 谷时 = 峰时 × 0.5 */
const DEFAULT_OFFPEAK_FACTOR = 0.5;
/** 费用落到 DECIMAL(18,8) 之前先收敛浮点噪声 */
const COST_DECIMALS = 8;
function numberFrom(value: string | undefined, fallback: number): number {
if (value === undefined || value.trim() === "") return fallback;
const parsed = Number(value);
return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
}
/**
* 解析 `HH:mm-HH:mm` 列表。
*
* 单条格式不对就跳过它而不是整段回退到默认值:运维改了一个窗口写错格式时,
* 其余窗口仍然生效,故障面更小。
*/
export function parsePeakWindows(raw: string | undefined): PeakWindow[] {
if (raw === undefined) return parsePeakWindows(DEFAULT_PEAK_WINDOWS);
return raw
.split(",")
.map((item) => item.trim())
.filter((item) => item.length > 0)
.map((item) => {
const match = /^(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})$/.exec(item);
if (!match) return null;
const [, startHour, startMinute, endHour, endMinute] = match;
const start = Number(startHour) * 60 + Number(startMinute);
const end = Number(endHour) * 60 + Number(endMinute);
if (start > 24 * 60 || end > 24 * 60 || start === end) return null;
return { startMinute: start, endMinute: end };
})
.filter((window): window is PeakWindow => window !== null);
}
function parseOffpeakDates(raw: string | undefined): string[] {
if (raw === undefined || raw.trim() === "") return [];
return raw
.split(",")
.map((item) => item.trim())
.filter((item) => /^\d{4}-\d{2}-\d{2}$/.test(item));
}
/** 单价指纹:改价即变版本,无需人工维护版本号 */
function deriveVersion(
cacheHitPerM: number,
cacheMissPerM: number,
outputPerM: number,
offpeakFactor: number,
): string {
return `hit${cacheHitPerM}|miss${cacheMissPerM}|out${outputPerM}|off${offpeakFactor}`;
}
export function loadPricingConfig(env: NodeJS.ProcessEnv = process.env): PricingConfig {
const cacheHitPerM = numberFrom(env.LLM_PRICE_CACHE_HIT_PER_M, DEFAULT_CACHE_HIT_PER_M);
const cacheMissPerM = numberFrom(env.LLM_PRICE_CACHE_MISS_PER_M, DEFAULT_CACHE_MISS_PER_M);
const outputPerM = numberFrom(env.LLM_PRICE_OUTPUT_PER_M, DEFAULT_OUTPUT_PER_M);
const offpeakFactor = numberFrom(env.LLM_PRICE_OFFPEAK_FACTOR, DEFAULT_OFFPEAK_FACTOR);
const explicitVersion = (env.LLM_PRICE_VERSION ?? "").trim();
return {
cacheHitPerM,
cacheMissPerM,
outputPerM,
offpeakFactor,
peakWindows: parsePeakWindows(env.LLM_PRICE_PEAK_WINDOWS),
offpeakDates: parseOffpeakDates(env.LLM_PRICE_PEAK_HOLIDAYS),
version:
explicitVersion.length > 0
? explicitVersion
: deriveVersion(cacheHitPerM, cacheMissPerM, outputPerM, offpeakFactor),
};
}
function utcDateKey(at: Date): string {
const year = at.getUTCFullYear();
const month = String(at.getUTCMonth() + 1).padStart(2, "0");
const day = String(at.getUTCDate()).padStart(2, "0");
return `${year}-${month}-${day}`;
}
function inWindow(minute: number, window: PeakWindow): boolean {
if (window.startMinute < window.endMinute) {
return minute >= window.startMinute && minute < window.endMinute;
}
// 跨零点(如 23:00-02:00)
return minute >= window.startMinute || minute < window.endMinute;
}
/**
* 判断某一时刻是否按峰时计价。
*
* 一律按 UTC 判定:DeepSeek 的峰时窗口就是按 UTC 公布的,
* 用服务器本地时区(部署在哪个区不确定)会算错整段。
*/
export function isPeak(at: Date, config: PricingConfig): boolean {
const weekday = at.getUTCDay();
if (weekday === 0 || weekday === 6) return false;
if (config.offpeakDates.includes(utcDateKey(at))) return false;
const minute = at.getUTCHours() * 60 + at.getUTCMinutes();
return config.peakWindows.some((window) => inWindow(minute, window));
}
function roundCost(value: number): number {
const factor = 10 ** COST_DECIMALS;
return Math.round(value * factor) / factor;
}
/**
* 把一次(或累计多次尝试的)用量换算成美元费用。
*
* 缓存未命中数的兜底顺序:优先用上游给的 `cacheMissTokens`;没给就用
* `promptTokens - cacheHitTokens`;连命中数都没有则把整个 `promptTokens`
* 按未命中价计——未命中价更高,宁可略微高估也不低估账单。
*/
export function priceUsage(
usage: TokenUsage,
at: Date,
config: PricingConfig,
): PricedUsage {
const peak = isPeak(at, config);
const multiplier = peak ? 1 : config.offpeakFactor;
const effectivePrices = {
cacheHitPerM: config.cacheHitPerM * multiplier,
cacheMissPerM: config.cacheMissPerM * multiplier,
outputPerM: config.outputPerM * multiplier,
};
const snapshot: PricingSnapshot = {
version: config.version,
peak,
effectivePrices,
listPrices: {
cacheHitPerM: config.cacheHitPerM,
cacheMissPerM: config.cacheMissPerM,
outputPerM: config.outputPerM,
},
};
if (!hasUsage(usage)) {
return { costUsd: null, snapshot };
}
const cacheHitTokens = usage.cacheHitTokens ?? 0;
let cacheMissTokens = usage.cacheMissTokens;
if (cacheMissTokens === null) {
cacheMissTokens =
usage.promptTokens !== null
? Math.max(0, usage.promptTokens - cacheHitTokens)
: 0;
}
const completionTokens = usage.completionTokens ?? 0;
const cost =
(cacheHitTokens / 1_000_000) * effectivePrices.cacheHitPerM +
(cacheMissTokens / 1_000_000) * effectivePrices.cacheMissPerM +
(completionTokens / 1_000_000) * effectivePrices.outputPerM;
return { costUsd: roundCost(cost), snapshot };
}
+295
View File
@@ -0,0 +1,295 @@
import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { emptyUsage } from "../llm/usage.js";
import { UsageReporter, loadReporterConfig, toUsageRecord, type ReporterConfig } from "./reporter.js";
import type { LogEntry } from "./store.js";
let workDir: string;
beforeEach(() => {
workDir = mkdtempSync(join(tmpdir(), "lpt-ai-reporter-"));
});
afterEach(() => {
rmSync(workDir, { recursive: true, force: true });
});
function outboxFile(): string {
return join(workDir, "usage-outbox.json");
}
function reporterConfig(overrides: Partial<ReporterConfig> = {}): ReporterConfig {
return {
url: "http://lpt-be.test",
token: "report-token",
intervalMs: 15_000,
batchSize: 50,
maxPending: 5_000,
timeoutMs: 5_000,
...overrides,
};
}
function makeReporter(
config: Partial<ReporterConfig> = {},
fetchImpl?: typeof fetch,
): UsageReporter {
return new UsageReporter({
loadConfig: () => reporterConfig(config),
outboxFile: outboxFile(),
...(fetchImpl ? { fetchImpl } : {}),
});
}
function entry(overrides: Partial<LogEntry> = {}): LogEntry {
return {
id: 1,
recordId: "rec-1",
timestamp: "2026-10-10T09:38:23.543Z",
endpoint: "/ai/tasks#aggregate-report",
taskType: "aggregate-report",
taskId: "task-1",
model: "deepseek-flash",
attempts: 2,
isLlmCall: true,
usage: {
promptTokens: 1234,
completionTokens: 567,
totalTokens: 1801,
cacheHitTokens: 800,
cacheMissTokens: 434,
reasoningTokens: 0,
},
usageSource: "upstream",
costUsd: 0.001234,
pricing: {
version: "hit0.006|miss0.3|out1.2|off0.5",
peak: false,
effectivePrices: { cacheHitPerM: 0.003, cacheMissPerM: 0.15, outputPerM: 0.6 },
listPrices: { cacheHitPerM: 0.006, cacheMissPerM: 0.3, outputPerM: 1.2 },
},
durationMs: 7466,
status: 200,
requestBody: {},
responseBody: {},
...overrides,
};
}
describe("loadReporterConfig", () => {
it("未配置上报地址时视为关闭", () => {
expect(loadReporterConfig({}).url).toBe("");
});
it("去掉结尾斜杠,避免拼出双斜杠路径", () => {
expect(loadReporterConfig({ LPT_AI_REPORT_URL: "http://be.test/" }).url).toBe("http://be.test");
});
it("非法数值回退到缺省", () => {
const config = loadReporterConfig({ LPT_AI_REPORT_INTERVAL_MS: "-5", LPT_AI_REPORT_BATCH_SIZE: "x" });
expect(config.intervalMs).toBe(15_000);
expect(config.batchSize).toBe(50);
});
});
describe("toUsageRecord", () => {
it("把日志映射成上报载荷,null 字段显式保留", () => {
const record = toUsageRecord(entry({ usage: emptyUsage(), costUsd: null, usageSource: "missing" }));
expect(record).toMatchObject({
recordId: "rec-1",
taskType: "aggregate-report",
attempts: 2,
usageSource: "missing",
promptTokens: null,
completionTokens: null,
cacheHitTokens: null,
costUsd: null,
});
});
it("非 LLM 请求也上报,由 isLlmCall 区分", () => {
const record = toUsageRecord(
entry({ isLlmCall: false, taskType: "fetch-title", model: "", usage: undefined }),
);
expect(record.isLlmCall).toBe(false);
expect(record.taskType).toBe("fetch-title");
expect(record.model).toBe("");
});
it("归属标记原样带上;没传时显式写 null", () => {
expect(toUsageRecord(entry({ callerRef: "U-123" })).callerRef).toBe("U-123");
expect(toUsageRecord(entry()).callerRef).toBeNull();
});
it("必填字段永远非空,否则 lpt-be 会把整批上报判 400", () => {
// 契约 1 的必填项:lpt-be 侧 @NotBlank 的字段不能是空串,@NotNull 的字段不能缺。
// 尤其是 /fetch-title 的 model——它合法地是空串,所以 lpt-be 那边用的是 @NotNull。
const notBlank = ["recordId", "occurredAt", "taskType", "usageSource"] as const;
const notNull = ["model", "attempts", "isLlmCall", "durationMs", "status"] as const;
const cases = [
entry(),
entry({ isLlmCall: false, taskType: "fetch-title", model: "", usage: undefined, usageSource: undefined }),
entry({ usage: emptyUsage(), costUsd: null, usageSource: "missing", status: 500, errorCode: "rate_limited" }),
];
for (const logEntry of cases) {
const record = toUsageRecord(logEntry) as unknown as Record<string, unknown>;
for (const field of notBlank) {
expect(typeof record[field], field).toBe("string");
expect(String(record[field]).trim().length, field).toBeGreaterThan(0);
}
for (const field of notNull) {
expect(record[field], field).not.toBeNull();
expect(record[field], field).not.toBeUndefined();
}
// lpt-be 用 OffsetDateTime.parse 解析 occurredAt,必须是带时区的 ISO 8601
expect(record.occurredAt).toMatch(/Z$|[+-]\d{2}:\d{2}$/);
}
});
});
describe("UsageReporter", () => {
it("未配置上报地址时不入队、不落盘", async () => {
const reporter = makeReporter({ url: "" });
reporter.enqueue(entry());
expect(reporter.isConfigured()).toBe(false);
expect(reporter.pendingCount()).toBe(0);
expect(existsSync(outboxFile())).toBe(false);
await expect(reporter.flush()).resolves.toEqual({ sent: 0, remaining: 0 });
});
it("推送成功后清空队列并落盘", async () => {
const fetchImpl = vi.fn().mockResolvedValue({ ok: true, status: 200 } as Response);
const reporter = makeReporter({}, fetchImpl as unknown as typeof fetch);
reporter.enqueue(entry({ recordId: "rec-1" }));
reporter.enqueue(entry({ recordId: "rec-2" }));
await expect(reporter.flush()).resolves.toEqual({ sent: 2, remaining: 0 });
expect(reporter.pendingCount()).toBe(0);
expect(JSON.parse(readFileSync(outboxFile(), "utf-8"))).toEqual([]);
const [url, init] = fetchImpl.mock.calls[0] as [string, RequestInit];
expect(url).toBe("http://lpt-be.test/internal/ai-usage/records");
expect((init.headers as Record<string, string>)["x-api-token"]).toBe("report-token");
expect(JSON.parse(String(init.body)).records).toHaveLength(2);
});
it("上报失败时保留队列,等下次重试", async () => {
const fetchImpl = vi.fn().mockResolvedValue({
ok: false,
status: 500,
text: async () => "boom",
} as Response);
const reporter = makeReporter({}, fetchImpl as unknown as typeof fetch);
reporter.enqueue(entry());
const result = await reporter.flush();
expect(result.sent).toBe(0);
expect(result.remaining).toBe(1);
expect(result.error).toContain("500");
expect(reporter.pendingCount()).toBe(1);
expect(reporter.dropped).toBe(0);
});
it("4xx 是确定性拒绝:丢弃这批而不是无限重试把队列堵死", async () => {
const fetchImpl = vi.fn().mockResolvedValue({
ok: false,
status: 400,
text: async () => "model 不能为空",
} as Response);
const reporter = makeReporter({}, fetchImpl as unknown as typeof fetch);
reporter.enqueue(entry({ recordId: "bad" }));
reporter.enqueue(entry({ recordId: "good" }));
const result = await reporter.flush();
expect(result.error).toContain("400");
expect(reporter.pendingCount()).toBe(0);
expect(reporter.dropped).toBe(2);
// 后续正常记录不受影响,仍然能上报
fetchImpl.mockResolvedValue({ ok: true, status: 200 } as Response);
reporter.enqueue(entry({ recordId: "later" }));
await expect(reporter.flush()).resolves.toEqual({ sent: 1, remaining: 0 });
});
it("网络异常时不丢队列", async () => {
const fetchImpl = vi.fn().mockRejectedValue(new Error("ECONNREFUSED"));
const reporter = makeReporter({}, fetchImpl as unknown as typeof fetch);
reporter.enqueue(entry());
const result = await reporter.flush();
expect(result.error).toBe("ECONNREFUSED");
expect(reporter.pendingCount()).toBe(1);
});
it("按 batchSize 分批推送,剩余记录留待下一轮", async () => {
const fetchImpl = vi.fn().mockResolvedValue({ ok: true, status: 200 } as Response);
const reporter = makeReporter({ batchSize: 2 }, fetchImpl as unknown as typeof fetch);
for (const id of ["a", "b", "c"]) {
reporter.enqueue(entry({ recordId: id }));
}
await expect(reporter.flush()).resolves.toEqual({ sent: 2, remaining: 1 });
expect(JSON.parse(String((fetchImpl.mock.calls[0][1] as RequestInit).body)).records.map(
(r: { recordId: string }) => r.recordId,
)).toEqual(["a", "b"]);
});
it("超出上限时丢弃最旧的并计数,避免磁盘被写满", () => {
const reporter = makeReporter({ maxPending: 2 });
for (const id of ["a", "b", "c", "d"]) {
reporter.enqueue(entry({ recordId: id }));
}
expect(reporter.pendingCount()).toBe(2);
expect(reporter.dropped).toBe(2);
});
it("新实例从 outbox 文件恢复未上报的记录", () => {
const first = makeReporter();
first.enqueue(entry({ recordId: "rec-persisted" }));
expect(first.pendingCount()).toBe(1);
const second = makeReporter();
expect(second.pendingCount()).toBe(1);
});
it("outbox 文件损坏时从空队列开始,不阻塞后续上报", () => {
const first = makeReporter();
first.enqueue(entry());
const reporter = new UsageReporter({
loadConfig: () => reporterConfig(),
outboxFile: join(workDir, "corrupt.json"),
});
expect(reporter.pendingCount()).toBe(0);
});
it("并发调用 flush 时第二次直接返回,不重复推送", async () => {
let release!: (value: Response) => void;
const fetchImpl = vi.fn().mockImplementation(
() => new Promise<Response>((resolve) => { release = resolve; }),
);
const reporter = makeReporter({}, fetchImpl as unknown as typeof fetch);
reporter.enqueue(entry());
const first = reporter.flush();
const second = await reporter.flush();
expect(second).toEqual({ sent: 0, remaining: 1 });
release({ ok: true, status: 200 } as Response);
await expect(first).resolves.toEqual({ sent: 1, remaining: 0 });
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
});
+302
View File
@@ -0,0 +1,302 @@
/**
* 用量上报(lpt-ai → lpt-be)。
*
* 设计要点:
* - **lpt-be 的 MySQL 是长期账本**,lpt-ai 本地只有最近若干条的面板缓存,
* 所以上报失败不能丢数据:先落到本地 outbox 文件,再批量推送、成功后删除。
* - **幂等交给 lpt-be**(`record_id` 唯一索引),因此「推送成功但响应丢失」
* 导致的重复推送是安全的,不需要在这里做去重协商。
* - **未配置 `LPT_AI_REPORT_URL` 时整体退化为空操作**:本地开发不必起 lpt-be,
* 面板照常工作,只是没有长期账本。
* - **配置延迟读取**:ESM 的 import 先于 `index.ts` 里的 .env 加载执行,
* 在模块顶层读环境变量会永远读不到 .env 里的值。
*/
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import type { LogEntry } from "./store.js";
// ---- 上报载荷(与 lpt-be 的 /internal/ai-usage/records 契约一致)----
export interface UsageRecord {
recordId: string;
occurredAt: string;
taskType: string;
taskId: string | null;
/** 归属标记(lpt-be 传的用户 id);lpt-be 把它落到 ai_usage_records.user_id */
callerRef: string | null;
model: string;
attempts: number;
isLlmCall: boolean;
usageSource: string;
promptTokens: number | null;
completionTokens: number | null;
totalTokens: number | null;
cacheHitTokens: number | null;
cacheMissTokens: number | null;
reasoningTokens: number | null;
costUsd: number | null;
pricingVersion: string | null;
peak: boolean | null;
durationMs: number;
status: number;
errorCode: string | null;
}
export interface ReporterConfig {
/** lpt-be 基地址;为空表示不上报 */
url: string;
token: string;
intervalMs: number;
batchSize: number;
/** outbox 上限:超过后丢弃最旧的,避免磁盘被写满 */
maxPending: number;
timeoutMs: number;
}
export interface ReporterDeps {
loadConfig?: () => ReporterConfig;
fetchImpl?: typeof fetch;
now?: () => number;
/** outbox 文件路径;测试里指向临时目录 */
outboxFile?: string;
}
export interface FlushResult {
sent: number;
remaining: number;
error?: string;
}
function intFrom(value: string | undefined, fallback: number): number {
if (value === undefined || value.trim() === "") return fallback;
const parsed = Number(value);
return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
}
export function loadReporterConfig(env: NodeJS.ProcessEnv = process.env): ReporterConfig {
return {
url: (env.LPT_AI_REPORT_URL ?? "").trim().replace(/\/+$/, ""),
token: (env.LPT_AI_REPORT_TOKEN ?? "").trim(),
intervalMs: intFrom(env.LPT_AI_REPORT_INTERVAL_MS, 15_000),
batchSize: intFrom(env.LPT_AI_REPORT_BATCH_SIZE, 50),
maxPending: intFrom(env.LPT_AI_REPORT_MAX_PENDING, 5_000),
timeoutMs: intFrom(env.LPT_AI_REPORT_TIMEOUT_MS, 10_000),
};
}
/** 把面板日志转成上报载荷;缺失字段一律显式写成 null,不要省略键 */
export function toUsageRecord(entry: LogEntry): UsageRecord {
const usage = entry.usage;
return {
recordId: entry.recordId,
occurredAt: entry.timestamp,
taskType: entry.taskType ?? entry.endpoint,
taskId: entry.taskId ?? null,
callerRef: entry.callerRef ?? null,
model: entry.model,
attempts: entry.attempts ?? 1,
isLlmCall: entry.isLlmCall,
usageSource: entry.usageSource ?? "missing",
promptTokens: usage?.promptTokens ?? null,
completionTokens: usage?.completionTokens ?? null,
totalTokens: usage?.totalTokens ?? null,
cacheHitTokens: usage?.cacheHitTokens ?? null,
cacheMissTokens: usage?.cacheMissTokens ?? null,
reasoningTokens: usage?.reasoningTokens ?? null,
costUsd: entry.costUsd ?? null,
pricingVersion: entry.pricing?.version ?? null,
peak: entry.pricing?.peak ?? null,
durationMs: entry.durationMs,
status: entry.status,
errorCode: entry.errorCode ?? null,
};
}
const DEFAULT_OUTBOX_NAME = "usage-outbox.json";
/** 与 store.ts 同一口径:可配置且惰性解析,避免测试写进开发者的真实数据目录 */
/** 取一批记录的幂等键,用于从 outbox 里精确移除已处理的那批 */
function sentIdsOf(batch: UsageRecord[]): Set<string> {
return new Set(batch.map((record) => record.recordId));
}
function defaultOutboxFile(): string {
const configured = (process.env.LPT_AI_DATA_DIR ?? "").trim();
const dir = configured.length > 0 ? configured : resolve(process.cwd(), "data");
return resolve(dir, DEFAULT_OUTBOX_NAME);
}
export class UsageReporter {
private readonly deps: ReporterDeps;
private pending: UsageRecord[] = [];
private loaded = false;
private cachedConfig: ReporterConfig | null = null;
private timer: NodeJS.Timeout | null = null;
private flushing = false;
/** 因超出上限被丢弃的条数,便于发现「长期上报失败」 */
private droppedCount = 0;
constructor(deps: ReporterDeps = {}) {
this.deps = deps;
}
private config(): ReporterConfig {
if (!this.cachedConfig) {
this.cachedConfig = (this.deps.loadConfig ?? loadReporterConfig)();
}
return this.cachedConfig;
}
private outboxFile(): string {
return this.deps.outboxFile ?? defaultOutboxFile();
}
isConfigured(): boolean {
return this.config().url.length > 0;
}
pendingCount(): number {
this.ensureLoaded();
return this.pending.length;
}
get dropped(): number {
return this.droppedCount;
}
/** 入队一条日志;未配置上报地址时直接忽略 */
enqueue(entry: LogEntry): void {
if (!this.isConfigured()) return;
this.ensureLoaded();
this.pending.push(toUsageRecord(entry));
const { maxPending } = this.config();
if (this.pending.length > maxPending) {
const overflow = this.pending.length - maxPending;
this.pending.splice(0, overflow);
this.droppedCount += overflow;
}
this.persist();
}
/** 推送一批;成功才从 outbox 删除,失败原样保留等下次 */
async flush(): Promise<FlushResult> {
this.ensureLoaded();
const config = this.config();
if (!this.isConfigured() || this.pending.length === 0) {
return { sent: 0, remaining: this.pending.length };
}
if (this.flushing) {
return { sent: 0, remaining: this.pending.length };
}
this.flushing = true;
const batch = this.pending.slice(0, config.batchSize);
try {
const fetchImpl = this.deps.fetchImpl ?? fetch;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), config.timeoutMs);
let response: Response;
try {
response = await fetchImpl(`${config.url}/internal/ai-usage/records`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-token": config.token,
},
body: JSON.stringify({ records: batch }),
signal: controller.signal,
});
} finally {
clearTimeout(timer);
}
if (!response.ok) {
const body = await response.text().catch(() => "");
// 4xx 是确定性拒绝(报文格式不对、令牌不对):重试多少次都一样,
// 继续留在 outbox 只会把队列堵死,把后续正常记录一起饿死。丢弃并计数。
if (response.status >= 400 && response.status < 500) {
this.pending = this.pending.filter((record) => !sentIdsOf(batch).has(record.recordId));
this.droppedCount += batch.length;
this.persist();
return {
sent: 0,
remaining: this.pending.length,
error: `上报被拒绝 (${response.status}),已丢弃这批记录: ${body.slice(0, 200)}`,
};
}
return {
sent: 0,
remaining: this.pending.length,
error: `上报失败 (${response.status}): ${body.slice(0, 200)}`,
};
}
// 只移除本次实际推送的那批;期间新入队的记录不受影响
const sentIds = sentIdsOf(batch);
this.pending = this.pending.filter((record) => !sentIds.has(record.recordId));
this.persist();
return { sent: batch.length, remaining: this.pending.length };
} catch (err) {
return {
sent: 0,
remaining: this.pending.length,
error: err instanceof Error ? err.message : String(err),
};
} finally {
this.flushing = false;
}
}
/** 启动定时推送;未配置上报地址时不做任何事 */
start(): void {
if (!this.isConfigured() || this.timer) return;
const { intervalMs } = this.config();
this.timer = setInterval(() => {
void this.flush();
}, intervalMs);
// 不要因为上报定时器让进程无法退出
this.timer.unref?.();
void this.flush();
}
stop(): void {
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
}
// ---- outbox 持久化 ----
private ensureLoaded(): void {
if (this.loaded) return;
this.loaded = true;
try {
const file = this.outboxFile();
if (!existsSync(file)) return;
const raw = readFileSync(file, "utf-8");
const data = JSON.parse(raw) as UsageRecord[];
this.pending = Array.isArray(data) ? data : [];
} catch {
// 文件损坏时从空队列开始,避免坏数据让上报永久卡死
this.pending = [];
}
}
private persist(): void {
try {
const file = this.outboxFile();
const dir = dirname(file);
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
// 原子替换:被中断的直写会留下截断 JSON,重启后整队列丢失
const tmpFile = `${file}.tmp`;
writeFileSync(tmpFile, JSON.stringify(this.pending), "utf-8");
renameSync(tmpFile, file);
} catch {
// 写盘失败不阻塞请求,队列仍在内存里
}
}
}
export const usageReporter = new UsageReporter();
+129
View File
@@ -0,0 +1,129 @@
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import Fastify from "fastify";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { adminRoutes } from "./routes.js";
import { logStore, resetLogStoreForTest } from "./store.js";
const originalToken = process.env.LPT_AI_TOKEN;
const originalDataDir = process.env.LPT_AI_DATA_DIR;
let workDir: string;
// 必须指向临时目录:单例默认写 process.cwd()/data,不隔离会把开发者真实的面板数据清掉
beforeEach(() => {
workDir = mkdtempSync(join(tmpdir(), "lpt-ai-admin-"));
process.env.LPT_AI_DATA_DIR = workDir;
});
afterEach(() => {
if (originalToken === undefined) {
delete process.env.LPT_AI_TOKEN;
} else {
process.env.LPT_AI_TOKEN = originalToken;
}
if (originalDataDir === undefined) {
delete process.env.LPT_AI_DATA_DIR;
} else {
process.env.LPT_AI_DATA_DIR = originalDataDir;
}
rmSync(workDir, { recursive: true, force: true });
});
async function buildApp() {
const app = Fastify();
await app.register(adminRoutes);
await app.ready();
return app;
}
function scriptOf(html: string): string {
const match = /<script>([\s\S]*)<\/script>/.exec(html);
if (!match) throw new Error("面板 HTML 里找不到内联脚本");
return match[1];
}
describe("管理面板", () => {
it("内联脚本必须能被解析", async () => {
const app = await buildApp();
const response = await app.inject({ method: "GET", url: "/admin" });
expect(response.statusCode).toBe(200);
const script = scriptOf(response.body);
// 面板 HTML 是模板字面量拼出来的:`\n` / `\'` 会被模板先吃掉,
// 落到产物里就是字符串里的裸换行或提前截断的引号——整套面板会静默变成空白页。
// 这里直接解析产物脚本,把这类转义错误挡在提交之前。
expect(() => new Function(script)).not.toThrow();
await app.close();
});
it("未配置令牌时面板与日志接口都放行", async () => {
delete process.env.LPT_AI_TOKEN;
const app = await buildApp();
expect((await app.inject({ method: "GET", url: "/admin" })).statusCode).toBe(200);
expect((await app.inject({ method: "GET", url: "/admin/logs" })).statusCode).toBe(200);
await app.close();
});
it("配置令牌后无令牌请求被拒", async () => {
process.env.LPT_AI_TOKEN = "secret-token";
const app = await buildApp();
expect((await app.inject({ method: "GET", url: "/admin" })).statusCode).toBe(401);
expect((await app.inject({ method: "GET", url: "/admin/logs" })).statusCode).toBe(401);
await app.close();
});
it("用 ?token= 打开面板时换发 HttpOnly cookie,后续 fetch 才能通过", async () => {
process.env.LPT_AI_TOKEN = "secret-token";
const app = await buildApp();
const page = await app.inject({ method: "GET", url: "/admin?token=secret-token" });
expect(page.statusCode).toBe(200);
const setCookie = String(page.headers["set-cookie"]);
expect(setCookie).toContain("lpt_ai_token=secret-token");
expect(setCookie).toContain("HttpOnly");
expect(setCookie).toContain("Path=/admin");
// 面板内部的 fetch 不带 query,只靠 cookie
const logs = await app.inject({
method: "GET",
url: "/admin/logs",
headers: { cookie: "lpt_ai_token=secret-token" },
});
expect(logs.statusCode).toBe(200);
await app.close();
});
it("日志摘要按 isLlmCall 区分,非 LLM 请求不计入用量分母", async () => {
delete process.env.LPT_AI_TOKEN;
resetLogStoreForTest();
const app = await buildApp();
logStore.add({
timestamp: "2026-10-10T09:00:00.000Z",
endpoint: "/fetch-title",
taskType: "fetch-title",
model: "",
isLlmCall: false,
durationMs: 10,
status: 200,
requestBody: {},
responseBody: {},
});
const response = await app.inject({ method: "GET", url: "/admin/logs" });
const body = JSON.parse(response.body) as {
stats: { total: number; llmCalls: number; cacheHitRate: number | null };
};
expect(body.stats.total).toBe(1);
expect(body.stats.llmCalls).toBe(0);
// 分母为 0 时返回 null,面板显示「—」而不是 0%
expect(body.stats.cacheHitRate).toBeNull();
resetLogStoreForTest();
await app.close();
});
});
+127 -19
View File
@@ -4,6 +4,8 @@
import type { FastifyInstance } from "fastify";
import { logStore } from "./store.js";
import { checkToken, configuredToken, queryTokenMatches, TOKEN_COOKIE } from "../utils/auth.js";
import { fetchUpstreamBalance } from "./balance.js";
const PANEL_HTML = `<!DOCTYPE html>
<html lang="zh-CN">
@@ -35,6 +37,8 @@ main{padding:14px 24px 40px;max-width:1400px;margin:0 auto}
.log-table .row-expand{max-width:20px;text-align:center;cursor:pointer;user-select:none;color:#6b8a6b;font-weight:700}
.log-table .status-badge{padding:2px 8px;border-radius:12px;font-size:11px;font-weight:600}
.status-ok{background:#e8f5e9;color:#2e7d32}.status-err{background:#ffebee;color:#c62828}
.muted{color:#9aa89a;font-size:12px}
.unreported{color:#ef6c00;font-size:12px}
.detail-row td{padding:0;border-bottom:2px solid #c8e6c9}
.detail-card{margin:8px 14px 12px;padding:12px 16px;background:#fafdfa;border-radius:8px;border:1px solid #dce8dc;max-height:460px;overflow-y:auto}
.detail-card h4{font-size:13px;color:#4a6a4a;margin-bottom:6px}
@@ -59,9 +63,17 @@ main{padding:14px 24px 40px;max-width:1400px;margin:0 auto}
<select id="filterEndpoint"><option value="">全部端点</option></select>
<button id="btnRefresh" onclick="loadLogs()">刷新</button>
<button class="danger" id="btnClear" onclick="clearLogs()">清除全部</button>
<span id="balanceBar" class="muted" style="margin-left:auto"></span>
</div>
<table class="log-table" id="logTable"><tbody></tbody></table>
<table class="log-table" id="logTable">
<thead><tr>
<th></th><th>时间</th><th>端点</th><th>状态</th>
<th>Token 输入/输出</th><th>缓存命中</th><th>费用(USD)</th>
<th>耗时</th><th>调用次数</th><th>模型</th>
</tr></thead>
<tbody></tbody>
</table>
<div class="empty" id="empty">暂无请求记录</div>
</main>
@@ -81,10 +93,16 @@ async function loadLogs() {
const { logs, stats } = await fetchJSON(url);
// stats
const hitRate = stats.cacheHitRate == null ? '—' : (stats.cacheHitRate*100).toFixed(1)+'%';
$('#statsBar').innerHTML = [
{ label:'总请求', value:stats.total, cls:'neutral' },
{ label:'LLM 调用', value:stats.llmCalls, cls:'neutral' },
{ label:'成功', value:stats.ok, cls:'ok' },
{ label:'失败', value:stats.err, cls:'err' },
{ label:'总 Token', value:formatNumber(stats.totalTokens), cls:'neutral' },
{ label:'缓存命中率', value:hitRate, cls:'neutral' },
{ label:'估算费用', value:'$'+stats.costUsd.toFixed(6), cls:'neutral' },
{ label:'未上报用量', value:stats.unreportedUsageCalls, cls:(stats.unreportedUsageCalls>0?'err':'neutral') },
{ label:'平均耗时', value:stats.avgMs+'ms', cls:(stats.avgMs>60000?'err':'neutral') },
].map(s=>'<div class="stat-card"><div class="label">'+s.label+'</div><div class="value '+s.cls+'">'+s.value+'</div></div>').join('');
@@ -103,15 +121,27 @@ async function loadLogs() {
$('#empty').classList.add('hidden');
tbody.innerHTML = logs.map(l => {
const statusCls = l.status >= 200 && l.status < 300 ? 'status-ok' : 'status-err';
const u = l.usage;
const tokens = !l.isLlmCall ? '<span class="muted">不适用</span>'
: (u && u.promptTokens != null
? formatNumber(u.promptTokens)+' / '+formatNumber(u.completionTokens)
: '<span class="unreported">未上报</span>');
const cache = !l.isLlmCall ? '<span class="muted">—</span>'
: (u && u.cacheHitTokens != null ? formatNumber(u.cacheHitTokens) : '<span class="unreported">未上报</span>');
const cost = l.costUsd == null ? '<span class="unreported">无法计价</span>'
: '$'+l.costUsd.toFixed(6)+(l.pricing && l.pricing.peak ? '' : ' <span class="muted">谷</span>');
return '<tr class="log-row" data-id="'+l.id+'">'+
'<td class="row-expand" onclick="toggleDetail('+l.id+',this)">▸</td>'+
'<td>'+escapeHtml(l.timestamp.replace('T',' ').slice(0,19))+'</td>'+
'<td>'+escapeHtml(l.endpoint)+'</td>'+
'<td><span class="status-badge '+statusCls+'">'+l.status+'</span></td>'+
'<td>'+(l.error ? '<span style="color:#c62828;font-size:12px">'+escapeHtml(l.error.slice(0,40))+'</span>' : '—')+'</td>'+
'<td>'+l.durationMs+'ms</td>'+
'<td style="font-size:12px;color:#6b8a6b">'+escapeHtml(l.model)+'</td>'+
'</tr><tr class="detail-row hidden" id="detail-'+l.id+'"><td colspan="7"><div class="detail-card"><span style="color:#8a9a8a;font-size:13px">加载中…</span></div></td></tr>';
'<td><span class="status-badge '+statusCls+'"'+(l.error ? ' title="'+escapeHtml(l.error)+'"' : '')+'>'+l.status+'</span></td>'+
'<td>'+tokens+'</td>'+
'<td>'+cache+'</td>'+
'<td>'+cost+'</td>'+
'<td>'+(l.durationMs)+'ms</td>'+
'<td>'+(l.attempts == null ? '—' : l.attempts)+'</td>'+
'<td style="font-size:12px;color:#6b8a6b">'+escapeHtml(l.model || '—')+'</td>'+
'</tr><tr class="detail-row hidden" id="detail-'+l.id+'"><td colspan="10"><div class="detail-card"><span style="color:#8a9a8a;font-size:13px">加载中…</span></div></td></tr>';
}).join('');
}
}
@@ -152,22 +182,27 @@ async function toggleDetail(id, el) {
// 构建复制的纯文本
const buildCopyText = () => {
let txt = '=== lpt-ai 请求日志 ===\n';
txt += '端点: '+(log.endpoint||'')+'\n';
txt += '模型: '+(log.model||'')+'\n';
txt += '耗时: '+log.durationMs+'ms\n';
txt += '状态: '+log.status+'\n';
if (paramsStr) txt += '参数: '+paramsStr+'\n';
let txt = '=== lpt-ai 请求日志 ===\\n';
txt += '端点: '+(log.endpoint||'')+'\\n';
txt += '模型: '+(log.model||'')+'\\n';
txt += '归属: '+(log.callerRef||'未归属')+'\\n';
txt += '耗时: '+log.durationMs+'ms\\n';
txt += '状态: '+log.status+'\\n';
if (log.attempts != null) txt += '调用次数: '+log.attempts+'\\n';
if (log.usage) txt += '用量: '+JSON.stringify(log.usage)+'\\n';
if (log.usageSource) txt += '用量来源: '+log.usageSource+'\\n';
if (log.pricing) txt += '计价: '+(log.pricing.peak?'峰时':'谷时')+' 版本 '+log.pricing.version+' 费用 '+(log.costUsd==null?'无法计价':'$'+log.costUsd)+'\\n';
if (paramsStr) txt += '参数: '+paramsStr+'\\n';
if (log.messages) {
log.messages.forEach((m,i) => {
txt += '\n--- '+(m.role==='system'?'System Prompt':'User Message')+' ---\n';
txt += '\\n--- '+(m.role==='system'?'System Prompt':'User Message')+' ---\\n';
txt += m.content;
});
}
txt += '\n\n--- 原始请求体 ---\n';
txt += '\\n\\n--- 原始请求体 ---\\n';
txt += reqStr;
txt += '\n\n--- 响应体 ---\n';
if (log.error) txt += '错误: '+log.error+'\n';
txt += '\\n\\n--- 响应体 ---\\n';
if (log.error) txt += '错误: '+log.error+'\\n';
txt += respStr;
return txt;
};
@@ -175,7 +210,7 @@ async function toggleDetail(id, el) {
let html = '';
// 复制按钮
html += '<div style="display:flex;gap:6px;margin-bottom:10px">'+
'<button class="copy-btn" onclick="copyLog(\''+copyId+'\',this)">📋 复制到剪贴板</button>'+
'<button class="copy-btn" onclick="copyLog(\\''+copyId+'\\',this)">📋 复制到剪贴板</button>'+
'<textarea id="'+copyId+'" style="position:absolute;left:-9999px">'+escapeHtml(buildCopyText())+'</textarea>'+
'</div>';
// prompt
@@ -187,8 +222,26 @@ async function toggleDetail(id, el) {
if (paramsStr) {
html += '<div><h4>⚙️ 调用参数</h4><pre style="background:#fff3e0;border-color:#ffe0b2;font-size:12px">'+escapeHtml(paramsStr)+'</pre></div>';
}
html += '<div><h4>⏱️ 耗时</h4><pre style="font-size:12px">'+log.durationMs+'ms</pre></div>';
html += '<div><h4>⏱️ 耗时</h4><pre style="font-size:12px">'+log.durationMs+'ms'+(log.attempts != null ? '('+log.attempts+' 次调用)' : '')+'</pre></div>';
html += '</div>';
// 用量与计价:必须标清「未上报」与「无法计价」,不能用 0 冒充
html += '<div style="margin-bottom:12px"><h4>🔢 Token 用量</h4>';
if (log.isLlmCall === false) {
html += '<pre style="font-size:12px">本次请求不过 LLM,无用量</pre>';
} else if (!log.usage || log.usage.promptTokens == null) {
html += '<pre style="background:#fff3e0;border-color:#ffe0b2;font-size:12px">上游未上报用量(usageSource: '+escapeHtml(log.usageSource||'missing')+')</pre>';
} else {
html += '<pre style="font-size:12px">'+escapeHtml(JSON.stringify(log.usage, null, 2))+'</pre>';
}
html += '</div>';
if (log.pricing) {
html += '<div style="margin-bottom:12px"><h4>💰 计价快照</h4><pre style="background:#e8f5e9;border-color:#c8e6c9;font-size:12px">'+escapeHtml(
'版本: '+log.pricing.version+'\\n'+
'时段: '+(log.pricing.peak ? '峰时' : '谷时')+'\\n'+
'费用: '+(log.costUsd == null ? '无法计价(用量未上报)' : '$'+log.costUsd.toFixed(8))+'\\n'+
'生效单价/1M: 命中 '+log.pricing.effectivePrices.cacheHitPerM+' | 未命中 '+log.pricing.effectivePrices.cacheMissPerM+' | 输出 '+log.pricing.effectivePrices.outputPerM
)+'</pre></div>';
}
html += '<div class="side">';
html += '<div><h4>📤 原始请求体</h4><pre>'+escapeHtml(reqStr)+'</pre></div>';
html += '<div><h4>📥 响应体</h4><pre>'+errorHtml+escapeHtml(respStr)+'</pre></div>';
@@ -208,6 +261,12 @@ function escapeHtml(s) {
return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');
}
/** 千位分隔;null/undefined 统一显示为 0,调用方负责区分「未上报」 */
function formatNumber(value) {
if (value == null) return '0';
return Number(value).toLocaleString('en-US');
}
function copyLog(id, btn) {
const ta = document.getElementById(id);
if (!ta) return;
@@ -229,6 +288,14 @@ async function init() {
const h = await fetchJSON('/health');
$('#serverInfo').textContent = '模型: '+h.model+' | API: '+(h.llmAvailable?'已配置':'未配置');
} catch(e) {}
try {
const b = await fetchJSON('/admin/usage/balance');
$('#balanceBar').textContent = b.configured
? '上游余额: '+b.currency+' '+b.totalBalance+'(赠送 '+b.grantedBalance+' / 充值 '+b.toppedUpBalance+')'
: '上游余额: 未配置或查询失败';
} catch(e) {
$('#balanceBar').textContent = '上游余额: 查询失败';
}
await loadLogs();
}
init();
@@ -238,8 +305,29 @@ init();
export async function adminRoutes(app: FastifyInstance): Promise<void> {
// 管理面板会展示完整 prompt 与学习内容,与 /ai/* 共用同一个可选令牌(安全-03)
if (!configuredToken()) {
app.log.warn(
"未设置 LPT_AI_TOKEN,/admin 面板与 /ai/* 无访问保护(面板会展示 prompt 与学习内容)",
);
}
app.addHook("preHandler", async (request, reply) => {
if (!checkToken(request, reply)) {
return reply;
}
});
// —— 面板页面 ——
app.get("/admin", async (_request, reply) => {
app.get<{ Querystring: { token?: string } }>("/admin", async (request, reply) => {
// 用 `?token=` 打开面板时换发一个 HttpOnly cookie:
// 面板 HTML 与它后续的 fetch 是两个独立请求,只在 URL 上带令牌会让面板永远空白
if (queryTokenMatches(request)) {
reply.header(
"set-cookie",
`${TOKEN_COOKIE}=${encodeURIComponent(configuredToken())}; Path=/admin; HttpOnly; SameSite=Strict`,
);
}
return reply.type("text/html; charset=utf-8").send(PANEL_HTML);
});
@@ -247,6 +335,13 @@ export async function adminRoutes(app: FastifyInstance): Promise<void> {
app.get<{ Querystring: { endpoint?: string } }>("/admin/logs", async (request) => {
const endpoint = request.query.endpoint || undefined;
const summaries = logStore.list(endpoint);
// 用量统计只算真正消耗 LLM 的记录;/fetch-title 这类请求混进来会把分母撑大
const llm = summaries.filter((s) => s.isLlmCall);
const sum = (pick: (s: (typeof llm)[number]) => number | null | undefined): number =>
llm.reduce((total, item) => total + (pick(item) ?? 0), 0);
const cacheHitTokens = sum((s) => s.usage?.cacheHitTokens);
const cacheMissTokens = sum((s) => s.usage?.cacheMissTokens);
const cacheTotal = cacheHitTokens + cacheMissTokens;
const stats = {
total: summaries.length,
ok: summaries.filter((s) => s.status >= 200 && s.status < 300).length,
@@ -255,10 +350,23 @@ export async function adminRoutes(app: FastifyInstance): Promise<void> {
? Math.round(summaries.reduce((a, s) => a + s.durationMs, 0) / summaries.length)
: 0,
endpoints: logStore.endpoints(),
llmCalls: llm.length,
promptTokens: sum((s) => s.usage?.promptTokens),
completionTokens: sum((s) => s.usage?.completionTokens),
totalTokens: sum((s) => s.usage?.totalTokens),
cacheHitTokens,
cacheMissTokens,
// 分母为 0 时返回 null,面板显示「—」而不是 0%
cacheHitRate: cacheTotal > 0 ? cacheHitTokens / cacheTotal : null,
costUsd: llm.reduce((total, item) => total + (item.costUsd ?? 0), 0),
unreportedUsageCalls: llm.filter((s) => s.usage?.promptTokens == null).length,
};
return { logs: summaries, stats };
});
// —— 上游余额(对账)——
app.get("/admin/usage/balance", async () => fetchUpstreamBalance());
// —— 日志详情 ——
app.get<{ Params: { id: string } }>("/admin/logs/:id", async (request, reply) => {
const id = parseInt(request.params.id, 10);
+162
View File
@@ -0,0 +1,162 @@
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { logStore, LogStore, resetLogStoreForTest, type LogEntry } from "./store.js";
const originalDataDir = process.env.LPT_AI_DATA_DIR;
let workDir: string;
// 必须指向临时目录:单例默认写 process.cwd()/data,
// 不隔离就会在跑测试时把开发者真实的面板数据清掉。
beforeEach(() => {
workDir = mkdtempSync(join(tmpdir(), "lpt-ai-store-"));
process.env.LPT_AI_DATA_DIR = workDir;
});
afterEach(() => {
if (originalDataDir === undefined) {
delete process.env.LPT_AI_DATA_DIR;
} else {
process.env.LPT_AI_DATA_DIR = originalDataDir;
}
rmSync(workDir, { recursive: true, force: true });
});
function logFile(): string {
return join(workDir, "logs.json");
}
function entry(overrides: Partial<LogEntry> = {}): Omit<LogEntry, "id" | "recordId"> {
return {
timestamp: "2026-10-10T09:00:00.000Z",
endpoint: "/ai/tasks#guidance",
taskType: "guidance",
model: "deepseek-flash",
attempts: 1,
isLlmCall: true,
durationMs: 100,
status: 200,
requestBody: {},
responseBody: {},
...overrides,
};
}
describe("LogStore 落盘", () => {
it("写入临时文件后原子替换,不留下 .tmp 残渣", () => {
const store = new LogStore();
store.add(entry());
expect(existsSync(logFile())).toBe(true);
expect(existsSync(`${logFile()}.tmp`)).toBe(false);
const persisted = JSON.parse(readFileSync(logFile(), "utf-8")) as { entries: LogEntry[] };
expect(persisted.entries).toHaveLength(1);
expect(persisted.entries[0].recordId).toBeTruthy();
});
it("落盘到 LPT_AI_DATA_DIR,而不是 process.cwd()/data", () => {
const store = new LogStore();
store.add(entry());
expect(existsSync(logFile())).toBe(true);
});
it("重新打开时能读回自己写的数据", () => {
new LogStore().add(entry({ endpoint: "/ai/tasks#compare-recall" }));
const reopened = new LogStore();
expect(reopened.list()).toHaveLength(1);
expect(reopened.list()[0].endpoint).toBe("/ai/tasks#compare-recall");
});
it("超过上限时丢弃最旧的记录", () => {
const store = new LogStore();
for (let i = 0; i < 501; i += 1) {
store.add(entry({ status: i }));
}
expect(store.list()).toHaveLength(500);
});
});
describe("LogStore 历史数据迁移", () => {
it("旧条目缺 isLlmCall 时按端点补齐,避免历史 LLM 调用被当成非 LLM 而静默消失", () => {
// 旧格式:没有 isLlmCall / recordId / usage
writeFileSync(
logFile(),
JSON.stringify({
nextId: 3,
entries: [
{
id: 1,
timestamp: "2026-10-09T09:00:00.000Z",
endpoint: "/ai/tasks#guidance",
model: "deepseek-flash",
durationMs: 100,
status: 200,
requestBody: {},
responseBody: {},
},
{
id: 2,
timestamp: "2026-10-09T09:01:00.000Z",
endpoint: "/fetch-title",
model: "",
durationMs: 5,
status: 200,
requestBody: {},
responseBody: {},
},
],
}),
"utf-8",
);
const summaries = new LogStore().list();
expect(summaries).toHaveLength(2);
expect(summaries.find((s) => s.endpoint === "/ai/tasks#guidance")?.isLlmCall).toBe(true);
// 抓标题不过 LLM,不该被计入用量分母
expect(summaries.find((s) => s.endpoint === "/fetch-title")?.isLlmCall).toBe(false);
});
it("旧条目没有用量时保持未上报,不用 0 冒充", () => {
writeFileSync(
logFile(),
JSON.stringify({
nextId: 2,
entries: [
{
id: 1,
timestamp: "2026-10-09T09:00:00.000Z",
endpoint: "/ai/tasks#guidance",
model: "deepseek-flash",
durationMs: 100,
status: 200,
requestBody: {},
responseBody: {},
},
],
}),
"utf-8",
);
const summary = new LogStore().list()[0];
expect(summary.usage).toBeUndefined();
expect(summary.costUsd).toBeUndefined();
});
it("文件损坏时从空存储开始,不让面板整体起不来", () => {
writeFileSync(logFile(), "{ not json", "utf-8");
expect(new LogStore().list()).toEqual([]);
});
});
describe("resetLogStoreForTest", () => {
it("清空单例,避免用例之间互相污染", () => {
logStore.add(entry());
resetLogStoreForTest();
expect(logStore.list()).toEqual([]);
});
});
+127 -22
View File
@@ -1,19 +1,48 @@
/**
* 请求日志存储 —— 环形缓冲区 + 可选文件持久化。
*
* 每条日志记录 AI 路由的一次完整请求/响应,供 /admin 面板查看。
* 每条日志记录 AI 路由的一次完整请求/响应,供 /admin 面板查看,
* 并携带该次请求的 token 用量与计价快照。
*
* 设计要点:
* - 这里只是**最近的调试视图**:真正的长期账本在 lpt-be 的 MySQL(见 reporter.ts)。
* 因此保留条数有限,用量统计的权威口径不在这个文件里。
* - **原子落盘**:直写会在进程被杀时留下截断的 JSON,把连同历史用量在内的
* 整个文件一起毁掉,所以先写临时文件再 rename 替换。
* - `usage` 里的字段可以为 null(上游未上报),**不要用 0 代替**。
*/
import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import { resolve } from "node:path";
import { randomUUID } from "node:crypto";
import type { TokenUsage, UsageSource } from "../llm/usage.js";
import type { PricingSnapshot } from "./pricing.js";
import { usageReporter } from "./reporter.js";
// ---- 类型 ----
export interface LogEntry {
id: number;
/** 上报幂等键:lpt-be 按它去重,重复推送不会重复入账 */
recordId: string;
timestamp: string; // ISO 8601
endpoint: string; // 如 "/ai/aggregate-report"
endpoint: string; // 如 "/ai/tasks#aggregate-report"
/** 任务类型;`/fetch-title` 这类非任务端点为空 */
taskType?: string;
/** 任务标识,便于把面板上的一条日志对回具体任务 */
taskId?: string;
/** 归属标记(lpt-be 传的用户 id);为空表示调用方没传或为独立调用 */
callerRef?: string;
model: string;
/** 本次请求实际发起的 LLM 调用次数(含失败重试);重试会重复计费 */
attempts?: number;
/** false 表示这次请求没有消耗 LLM(如抓取网页标题) */
isLlmCall: boolean;
usage?: TokenUsage;
usageSource?: UsageSource;
/** 结算时算好并冻结的费用;null 表示用量未上报、无法计价 */
costUsd?: number | null;
pricing?: PricingSnapshot;
durationMs: number;
status: number; // HTTP status code
requestBody: unknown; // Java 端发来的原始请求体
@@ -21,65 +50,122 @@ export interface LogEntry {
params?: Record<string, unknown>; // 模型调用参数(temperature、max_tokens 等)
responseBody: unknown;
error?: string;
/** 失败分类,便于按错误类型聚合(timeout / rate_limited / ...) */
errorCode?: string;
}
export interface LogSummary {
id: number;
timestamp: string;
endpoint: string;
taskType?: string;
callerRef?: string;
model: string;
attempts?: number;
isLlmCall: boolean;
usage?: TokenUsage;
usageSource?: UsageSource;
costUsd?: number | null;
durationMs: number;
status: number;
error?: string;
errorCode?: string;
}
// ---- 存储实现 ----
const MAX_ENTRIES = 200;
const DATA_DIR = resolve(process.cwd(), "data");
const LOG_FILE = resolve(DATA_DIR, "logs.json");
/** 面板只展示最近若干条;长期账本在 lpt-be,这里不需要留太多 */
const MAX_ENTRIES = 500;
class LogStore {
/**
* 数据目录。
*
* 可配置是为了两件事:部署时能挂卷,以及**测试不污染开发者的真实面板数据**——
* 单例默认写在 `process.cwd()/data`,测试里一旦触发落盘就会把真实的 logs.json 清掉。
* 路径惰性解析:ESM 的 import 先于测试里设置环境变量执行,模块顶层解析会读不到。
*/
function dataDir(): string {
const configured = (process.env.LPT_AI_DATA_DIR ?? "").trim();
return configured.length > 0 ? configured : resolve(process.cwd(), "data");
}
function logFile(): string {
return resolve(dataDir(), "logs.json");
}
/**
* 把旧格式的历史日志补齐到当前结构。
*
* 用量字段是这次才加的,旧条目没有 `isLlmCall` 也没有 `recordId`;
* 不补的话它们会被当成「非 LLM 请求」而从用量统计里静默消失(比报错更难发现)。
* 旧条目无法回溯 token,所以用量保持未上报,但 `isLlmCall` 可以从端点推出。
*/
function migrateEntry(entry: LogEntry): LogEntry {
return {
...entry,
recordId: entry.recordId ?? randomUUID(),
isLlmCall: entry.isLlmCall ?? entry.endpoint.startsWith("/ai/tasks"),
};
}
export class LogStore {
private entries: LogEntry[] = [];
private nextId = 1;
private dirty = false;
private loaded = false;
constructor() {
this.load();
}
/** 追加一条日志,超出上限时移除最旧的 */
add(entry: Omit<LogEntry, "id">): LogEntry {
const full: LogEntry = { id: this.nextId++, ...entry };
/** 追加一条日志,超出上限时移除最旧的;同时投递到用量上报队列 */
add(entry: Omit<LogEntry, "id" | "recordId"> & { recordId?: string }): LogEntry {
this.ensureLoaded();
const full: LogEntry = { id: this.nextId++, recordId: entry.recordId ?? randomUUID(), ...entry };
this.entries.push(full);
while (this.entries.length > MAX_ENTRIES) {
this.entries.shift();
}
this.dirty = true;
this.flush(); // fire-and-forget
// 上报失败由 reporter 自己持久化重试,这里不阻塞请求
usageReporter.enqueue(full);
return full;
}
/** 列出摘要(不含请求/响应体,减少面板传输量) */
list(endpoint?: string): LogSummary[] {
this.ensureLoaded();
let result = [...this.entries];
if (endpoint) {
result = result.filter((e) => e.endpoint === endpoint);
}
// 倒序:最新在前
result.reverse();
return result.map(({ id, timestamp, endpoint, model, durationMs, status, error }) => ({
id, timestamp, endpoint, model, durationMs, status, error,
return result.map((entry) => ({
id: entry.id,
timestamp: entry.timestamp,
endpoint: entry.endpoint,
...(entry.taskType !== undefined ? { taskType: entry.taskType } : {}),
...(entry.callerRef !== undefined ? { callerRef: entry.callerRef } : {}),
model: entry.model,
...(entry.attempts !== undefined ? { attempts: entry.attempts } : {}),
isLlmCall: entry.isLlmCall,
...(entry.usage !== undefined ? { usage: entry.usage } : {}),
...(entry.usageSource !== undefined ? { usageSource: entry.usageSource } : {}),
...(entry.costUsd !== undefined ? { costUsd: entry.costUsd } : {}),
durationMs: entry.durationMs,
status: entry.status,
...(entry.error !== undefined ? { error: entry.error } : {}),
...(entry.errorCode !== undefined ? { errorCode: entry.errorCode } : {}),
}));
}
/** 获取单条完整日志 */
get(id: number): LogEntry | undefined {
this.ensureLoaded();
return this.entries.find((e) => e.id === id);
}
/** 清空 */
clear(): void {
this.ensureLoaded();
this.entries = [];
this.dirty = true;
this.flush();
@@ -87,18 +173,26 @@ class LogStore {
/** 端点列表(用于筛选下拉) */
endpoints(): string[] {
this.ensureLoaded();
return [...new Set(this.entries.map((e) => e.endpoint))].sort();
}
// ---- 持久化 ----
private ensureLoaded(): void {
if (this.loaded) return;
this.loaded = true;
this.load();
}
private load(): void {
try {
if (existsSync(LOG_FILE)) {
const raw = readFileSync(LOG_FILE, "utf-8");
const file = logFile();
if (existsSync(file)) {
const raw = readFileSync(file, "utf-8");
const data = JSON.parse(raw) as { nextId: number; entries: LogEntry[] };
this.nextId = data.nextId ?? 1;
this.entries = data.entries ?? [];
this.entries = (data.entries ?? []).map((entry) => migrateEntry(entry));
// 裁剪
while (this.entries.length > MAX_ENTRIES) {
this.entries.shift();
@@ -113,10 +207,16 @@ class LogStore {
if (!this.dirty) return;
this.dirty = false;
try {
if (!existsSync(DATA_DIR)) {
mkdirSync(DATA_DIR, { recursive: true });
const dir = dataDir();
const file = logFile();
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
writeFileSync(LOG_FILE, JSON.stringify({ nextId: this.nextId, entries: this.entries }), "utf-8");
// 先写临时文件再原子替换:直写被中断会留下截断的 JSON,
// 下次启动读不出来就把历史用量一起丢了
const tmpFile = `${file}.tmp`;
writeFileSync(tmpFile, JSON.stringify({ nextId: this.nextId, entries: this.entries }), "utf-8");
renameSync(tmpFile, file);
} catch {
// 写入失败不阻塞服务
}
@@ -124,3 +224,8 @@ class LogStore {
}
export const logStore = new LogStore();
/** 仅用于测试:重置内部状态,避免用例之间互相污染 */
export function resetLogStoreForTest(): void {
logStore.clear();
}
+14
View File
@@ -4,6 +4,7 @@ import { dirname, resolve } from "node:path";
import Fastify from "fastify";
import { aiRoutes } from "./routes/ai.js";
import { adminRoutes } from "./admin/index.js";
import { usageReporter } from "./admin/reporter.js";
// ===== 加载 .env(零依赖,兼容 dev/start 两种启动方式)=====
const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -28,11 +29,24 @@ const app = Fastify({
redact: ["req.headers.authorization"], // 永不记录密钥
},
connectionTimeout: 180_000, // 3 min
// 安全-03:请求体上限。抓取标题与 AI 任务参数都是小报文,
// 没有上限时超大 body 可以打爆内存。
bodyLimit: Number(process.env.LPT_AI_BODY_LIMIT_BYTES ?? 256 * 1024),
});
await app.register(aiRoutes);
await app.register(adminRoutes);
// 用量上报(lpt-ai → lpt-be):未配置 LPT_AI_REPORT_URL 时为空操作。
// 必须放在 .env 加载之后:ESM 的 import 先于本文件顶层代码执行,
// 在模块顶层读环境变量永远读不到 .env 里的值。
if (usageReporter.isConfigured()) {
usageReporter.start();
app.log.info("用量上报已启用,待上报条数 " + usageReporter.pendingCount());
} else {
app.log.info("未配置 LPT_AI_REPORT_URL,用量只保留在本地面板(无长期账本)");
}
const port = Number(process.env.PORT ?? 5199);
try {
+140
View File
@@ -0,0 +1,140 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { chat, type LlmConfig } from "./client.js";
/**
* 只验证「请求体契约」:思考强度要真的写进 `reasoning_effort`,
* 不传时不能凭空加上该字段(否则换供应商会被当成非法参数)。
*/
const llmConfig: LlmConfig = {
apiUrl: "https://example.invalid/v1/chat/completions",
apiKey: "test-key",
model: "deepseek-flash",
timeoutMs: 5_000,
};
function mockFetchOnce() {
const fetchMock = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ choices: [{ message: { content: "ok" } }] }),
headers: new Headers(),
} as unknown as Response);
vi.stubGlobal("fetch", fetchMock);
return fetchMock;
}
function mockFetchJson(payload: unknown, ok = true, status = 200) {
const fetchMock = vi.fn().mockResolvedValue({
ok,
status,
json: async () => payload,
text: async () => JSON.stringify(payload),
headers: new Headers(),
} as unknown as Response);
vi.stubGlobal("fetch", fetchMock);
return fetchMock;
}
function bodyOf(fetchMock: ReturnType<typeof mockFetchOnce>): Record<string, unknown> {
const init = fetchMock.mock.calls[0][1] as RequestInit;
return JSON.parse(String(init.body)) as Record<string, unknown>;
}
afterEach(() => {
vi.unstubAllGlobals();
});
describe("chat 请求体", () => {
it("传入 reasoningEffort 时写进 reasoning_effort", async () => {
const fetchMock = mockFetchOnce();
await chat(llmConfig, [{ role: "user", content: "hi" }], {
temperature: 0.2,
maxTokens: 1024,
reasoningEffort: "low",
});
expect(bodyOf(fetchMock)).toMatchObject({
model: "deepseek-flash",
temperature: 0.2,
max_tokens: 1024,
stream: false,
reasoning_effort: "low",
});
});
it("none 也要显式发送,用于关闭思考模式", async () => {
const fetchMock = mockFetchOnce();
await chat(llmConfig, [{ role: "user", content: "hi" }], { reasoningEffort: "none" });
expect(bodyOf(fetchMock).reasoning_effort).toBe("none");
});
it("不传 reasoningEffort 时不带该字段,交回供应商默认", async () => {
const fetchMock = mockFetchOnce();
await chat(llmConfig, [{ role: "user", content: "hi" }]);
expect(bodyOf(fetchMock)).not.toHaveProperty("reasoning_effort");
});
});
describe("chat 返回值", () => {
it("带回上游上报的 token 用量与模型名", async () => {
mockFetchJson({
model: "deepseek-flash-0715",
choices: [{ message: { content: "ok" }, finish_reason: "stop" }],
usage: {
prompt_tokens: 1000,
completion_tokens: 200,
total_tokens: 1200,
prompt_cache_hit_tokens: 800,
prompt_cache_miss_tokens: 200,
},
});
const result = await chat(llmConfig, [{ role: "user", content: "hi" }]);
expect(result.content).toBe("ok");
expect(result.model).toBe("deepseek-flash-0715");
expect(result.finishReason).toBe("stop");
expect(result.usageSource).toBe("upstream");
expect(result.usage).toMatchObject({
promptTokens: 1000,
completionTokens: 200,
cacheHitTokens: 800,
cacheMissTokens: 200,
});
});
it("上游没带 usage 时标为 missing,字段全为 null", async () => {
mockFetchJson({ choices: [{ message: { content: "ok" } }] });
const result = await chat(llmConfig, [{ role: "user", content: "hi" }]);
expect(result.usageSource).toBe("missing");
expect(result.usage.promptTokens).toBeNull();
});
it("返回 200 但内容为空时,把已产生的用量挂在错误上带回来", async () => {
mockFetchJson({
choices: [{ message: { content: "" } }],
usage: { prompt_tokens: 500, completion_tokens: 0, total_tokens: 500 },
});
await expect(chat(llmConfig, [{ role: "user", content: "hi" }])).rejects.toMatchObject({
statusCode: 502,
usage: { promptTokens: 500 },
});
});
it("上游报错时错误不带用量(上游没产生可计费的输出)", async () => {
mockFetchJson({ error: "rate limited" }, false, 429);
await expect(chat(llmConfig, [{ role: "user", content: "hi" }])).rejects.toMatchObject({
statusCode: 429,
});
await expect(chat(llmConfig, [{ role: "user", content: "hi" }])).rejects.toHaveProperty(
"usage",
undefined,
);
});
});
+87 -7
View File
@@ -7,11 +7,37 @@
* - 超时保护,避免长时间挂起
*/
import type { ReasoningEffort } from "./thinking.js";
import { normalizeUsage, type TokenUsage, type UsageSource } from "./usage.js";
export interface ChatMessage {
role: "system" | "user" | "assistant";
content: string;
}
/**
* 一次成功调用的返回值。
*
* 除了正文,还带回上游上报的 token 用量:调用方必须把它记下来,
* 否则重试与失败尝试产生的消耗就再也拿不到了(上游不会补发)。
*/
export interface ChatResult {
content: string;
usage: TokenUsage;
usageSource: UsageSource;
/** 上游回显的模型名,可能与本项目配置的模型名不同 */
model: string;
finishReason: string | null;
}
/** 单次调用的采样参数:温度与输出上限按任务类型定,思考强度按 prompt 长度定 */
export interface ChatOptions {
temperature?: number;
maxTokens?: number;
/** 思考强度;不传时不带 `reasoning_effort`,由供应商按自己的默认值处理 */
reasoningEffort?: ReasoningEffort;
}
export interface LlmConfig {
apiUrl: string;
apiKey: string;
@@ -36,19 +62,55 @@ export class LlmError extends Error {
constructor(
message: string,
public readonly statusCode: number,
/**
* 服务端给出的建议重试等待(毫秒)。
*
* 来自 429/503 的 `Retry-After` 头;有值时退避重试应优先采用它,
* 而不是用自己的指数退避——服务商限流时自己的退避往往偏短。
*/
public readonly retryAfterMs?: number,
/**
* 这次失败的调用是否已经产生了 token 消耗。
*
* 典型场景是上游返回 200 但内容为空:请求已经计费,只是没法用。
* 有值时调用方必须把它计入用量,否则这部分消耗会凭空消失。
*/
public readonly usage?: TokenUsage,
) {
super(message);
this.name = "LlmError";
}
}
/**
* 非流式调用,返回完整文本
* 解析 `Retry-After` 头。
*
* 规范允许秒数或 HTTP 日期两种形式,两种都支持;解析不出来时返回 undefined。
*/
export function parseRetryAfter(value: string | null, now: number = Date.now()): number | undefined {
if (!value) return undefined;
const trimmed = value.trim();
if (trimmed.length === 0) return undefined;
// 纯数字:秒
if (/^\d+$/.test(trimmed)) {
return Number(trimmed) * 1000;
}
// HTTP 日期
const at = Date.parse(trimmed);
if (Number.isNaN(at)) return undefined;
return Math.max(0, at - now);
}
/**
* 非流式调用,返回正文与上游上报的 token 用量。
*/
export async function chat(
config: LlmConfig,
messages: ChatMessage[],
options?: { temperature?: number; maxTokens?: number },
): Promise<string> {
options?: ChatOptions,
): Promise<ChatResult> {
if (!isAvailable(config)) {
throw new LlmError("LLM API Key 未配置", 503);
}
@@ -69,23 +131,41 @@ export async function chat(
temperature: options?.temperature ?? 0.3,
max_tokens: options?.maxTokens ?? 2048,
stream: false,
// 思考强度交给调用方按内容长度决定;不传表示由供应商默认(DeepSeek 为 high)
...(options?.reasoningEffort ? { reasoning_effort: options.reasoningEffort } : {}),
}),
signal: controller.signal,
});
if (!response.ok) {
const body = await response.text().catch(() => "");
throw new LlmError(`LLM 请求失败 (${response.status}): ${body.slice(0, 200)}`, 502);
const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
// 保留上游真实状态码:重试策略靠它区分 429/5xx(可重试)与 4xx(不可重试)
throw new LlmError(
`LLM 请求失败 (${response.status}): ${body.slice(0, 200)}`,
response.status,
retryAfterMs,
);
}
const data = (await response.json()) as {
choices?: { message?: { content?: string } }[];
model?: string;
choices?: { message?: { content?: string }; finish_reason?: string }[];
usage?: unknown;
};
// 先把用量取出来:即使下面因为内容为空而抛错,这次请求也已经计费了
const snapshot = normalizeUsage(data.usage);
const content = data.choices?.[0]?.message?.content;
if (!content) {
throw new LlmError("LLM 返回内容为空", 502);
throw new LlmError("LLM 返回内容为空", 502, undefined, snapshot.usage);
}
return content;
return {
content,
usage: snapshot.usage,
usageSource: snapshot.source,
model: data.model ?? config.model,
finishReason: data.choices?.[0]?.finish_reason ?? null,
};
} catch (err) {
if (err instanceof LlmError) throw err;
if (err instanceof Error && err.name === "AbortError") {
+58 -5
View File
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
import { aggregateReportPrompt, generateMindMapPrompt } from "./prompts.js";
import { aggregateReportPrompt, generateMindMapPrompt, guidancePrompt } from "./prompts.js";
describe("aggregateReportPrompt", () => {
it("包含全部残片和任务名", () => {
@@ -32,14 +32,67 @@ describe("aggregateReportPrompt", () => {
});
describe("generateMindMapPrompt", () => {
it("要求输出缩进大纲且只包含学习报告", () => {
it("要求输出缩进大纲,素材是该任务名下的知识碎片", () => {
const messages = generateMindMapPrompt(
"Java 并发",
"并发编程学习",
["报告一"],
["corePoolSize 是核心线程数"],
);
expect(messages[0].content).toContain("缩进");
expect(messages[1].content).toContain("报告一");
expect(messages[1].content).not.toContain("学习残片");
expect(messages[0].content).toContain("知识碎片");
expect(messages[1].content).toContain("corePoolSize");
expect(messages[1].content).not.toContain("学习报告");
});
it("没有报告时不带报告块与报告规则", () => {
const messages = generateMindMapPrompt("t", "", ["x"]);
expect(messages[0].content).not.toContain("参考报告规则");
expect(messages[1].content).not.toContain("参考报告");
});
it("携带报告时:碎片标注同源报告,报告三段进入上下文,并给出相关性约束", () => {
const messages = generateMindMapPrompt(
"Java 并发",
"",
[{ content: "corePoolSize 是核心线程数", reportRef: "S1" }],
[
{
ref: "S1",
taskName: "Java 并发",
sessionSummary: "线程池参数总结",
freeSummary: "还需补队列的取舍",
},
],
);
// 系统规则里说明「实质讨论/领域一致才用,否则完全不用」
expect(messages[0].content).toContain("域一致");
expect(messages[0].content).toContain("完全不要使用该报告");
// 用户上下文里碎片标注来源报告,并带上报告三段
expect(messages[1].content).toContain("来源报告:S1");
expect(messages[1].content).toContain("报告 S1");
expect(messages[1].content).toContain("会话摘要:线程池参数总结");
expect(messages[1].content).toContain("自由总结:还需补队列的取舍");
});
});
describe("guidancePrompt", () => {
it("把任务名与概念写进 system,并带上历史轮次", () => {
const messages = guidancePrompt("AI 基础", "参数量与显存", [
{ role: "user", content: "我觉得参数量决定显存占用" },
{ role: "assistant", content: "那 1B 模型一定占 1GB 吗?" },
]);
expect(messages).toHaveLength(3);
expect(messages[0].role).toBe("system");
expect(messages[0].content).toContain("AI 基础");
expect(messages[0].content).toContain("参数量与显存");
// 不判分、不设轮数上限
expect(messages[0].content).toContain("不给分数");
// 历史轮次原样带上,供多轮对话使用
expect(messages[1].content).toContain("参数量决定显存占用");
expect(messages[2].content).toContain("1B 模型");
});
it("没有历史时只有 system", () => {
expect(guidancePrompt("t", "c", [])).toHaveLength(1);
});
});
+131 -43
View File
@@ -10,10 +10,33 @@ export interface FragmentInput {
createdTime?: string;
}
/** 导图生成的一条碎片素材:正文 + 可空的同源报告标识(报告-02) */
export interface MindMapFragmentInput {
content: string;
/** 同源报告标识(会话编号):该碎片与这份报告来自同一次学习会话 */
reportRef?: string;
}
/** 导图生成的一份报告参考上下文(报告-02):同源会话的总结三段 */
export interface MindMapReportInput {
ref: string;
/** 产生该报告的会话所属任务名,用于判断领域是否一致 */
taskName?: string;
sessionSummary?: string;
expectationVerdict?: string;
freeSummary?: string;
}
/**
* 残片聚合为学习报告。
* 原则:报告是写给"未来复习的自己"的,保留具体知识点,剔除口语碎屑;
* 不虚构残片中不存在的内容;对抽象概念补充正反例子以明确边界。
* 残片聚合为结构化的学习报告草稿。
*
* 报告形态是结构化的,AI 负责能由碎片推出的三段:
* 会话摘要(这次实际学了什么)、预期达成判断、自由总结草稿。
* 第四段「按归属分组的碎片」由后端按内容归属实时聚合,不需要 AI 输出。
*
* 输出要求:严格 JSON,不要 markdown 代码块,格式如下:
* {"sessionSummary":"...","expectationVerdict":"...","freeSummary":"..."}
* 没有依据的字段输出空字符串,不要编造。
*/
export function aggregateReportPrompt(
taskName: string,
@@ -32,62 +55,95 @@ export function aggregateReportPrompt(
{
role: "system",
content: [
"你是一名学习记录整理助手。用户在一次学习会话中随手记录了若干学习残片,",
"请将它们整理为一份简洁的学习报告。要求:",
"1. 只基于残片内容,不虚构残片中不存在的知识;",
"2. 保留具体的知识点、概念、结论,去掉口语化的碎屑;",
"3. 对残片中的抽象概念或知识,除定义/要点外,再补充一组正反例子,",
" 用「是X:…;不是X:…」的形式列出具体具象,帮助明确概念边界;",
" 例如:奇数(也叫单数)是不能被 2 整除的整数;是奇数:1、3、5、7;不是奇数:2、4、6、8;",
" 例子只用于解释残片已有的抽象内容,不引入新的知识点;",
"4. 按逻辑而非时间组织内容,相关的点合并;",
"5. 报告以要点形式呈现,因包含示例,目标 600 字左右,不超过 1000 字;",
"6. 如果提供了学习预期,在报告末尾用一句话说明本次学习与预期的差距(完成/部分完成/未涉及);",
"7. 直接输出报告正文,不要输出「报告如下」之类的引导语。",
"你是一名学习记录整理助手。用户在一次学习会话中随手记录了若干知识碎片,",
"请据此生成一份结构化学习报告草稿,只输出严格 JSON,不要 markdown 代码块、不要解释。",
"JSON 字段:",
'1. "sessionSummary":会话摘要,说明这次实际学了什么。按逻辑组织、合并相关要点,保留具体知识点,',
" 去掉口语化碎屑;对抽象概念可用「是X:…;不是X:…」补一组具体例子帮自己以后看懂边界。",
'2. "expectationVerdict":预期达成判断,对照给定的学习预期用一两句话判断完成情况',
" (完全达成/部分达成/未涉及)。没有提供学习预期时输出空字符串。",
'3. "freeSummary":自由总结草稿。只写能从碎片推断出的疑问、卡点与可能的下一步;',
" 没有依据就输出空字符串,不要编造。用户会在此基础上修改。",
"硬性要求:只基于给定碎片,不虚构不存在的知识;所有字段都必须是字符串。",
].join(""),
},
{
role: "user",
content: `学习任务:${taskName}\n${expectationBlock}\n本次学习的残片记录:\n${fragmentLines}`,
content: `学习任务:${taskName}\n${expectationBlock}\n本次学习记录的知识碎片:\n${fragmentLines}`,
},
];
}
/**
* 从学习报告生成标准思维导图(预留,用于替代 Java 端 BuiltinMindMapGenerator)。
* 从知识碎片生成标准思维导图(报告-02 起可携带报告作为参考上下文;预留,用于替代 Java 端 BuiltinMindMapGenerator)。
*
* <p>素材按**内容归属**给(一个任务名下的碎片),而不是按产生它的会话给:
* 学 A 时顺手记下的旁支知识若归属到 B,就应该出现在 B 的导图里。</p>
*
* <p>报告是同源会话的总结:一次总结可能把若干碎片拼接出新的定义与观点,
* 这些内容只存在于报告里。因此把与碎片同源的报告作为参考带上,但**是否采用由模型按相关性判断**:
* 报告必须实质讨论相关碎片的同一主题、且与本批碎片领域一致,才可提取;只是顺带提及或没提及则完全不用。</p>
*
* 输出为缩进大纲文本,与后端 MindMapTreeTool.parseOutline 格式一致。
*/
export function generateMindMapPrompt(
taskName: string,
taskDescription: string,
reports: string[],
fragments: Array<string | MindMapFragmentInput>,
reports: MindMapReportInput[] = [],
): ChatMessage[] {
const fragmentItems: MindMapFragmentInput[] = fragments.map((f) =>
typeof f === "string" ? { content: f } : f,
);
const hasReports = reports.length > 0;
const systemRules = [
"你是一名知识结构整理助手。请阅读某个学习任务名下的全部知识碎片,",
"将这些碎片整理成一份思维导图大纲。要求:",
"1. 第一行是导图根标题(任务主题);",
"2. 之后每行一个节点,用两个空格的缩进表示层级;",
"3. 按知识的内在结构组织(概念→细分→要点),不按时间顺序;",
"4. 合并重复的知识点;",
"5. 只基于给定内容,不补充外部知识;",
"6. 直接输出大纲,不要任何解释。",
];
if (hasReports) {
systemRules.push(
"参考报告规则(这些报告是同源学习会话的总结,仅作参考):",
"7. 只有当某份报告实质地讨论了相关碎片的同一主题、且与本批碎片的领域一致时,",
" 才可提取报告中由碎片拼接出的新定义、新观点进入导图;",
"8. 报告只是顺带提及、或者根本没有提到该主题时,完全不要使用该报告的内容;",
"9. 报告与该批碎片的主干强相关时,可以参考它的组织结构,但不要照搬无关内容;",
"10. 不要引入碎片与报告都未涉及的知识。",
);
}
const fragmentLines = fragmentItems.map((fragment, i) => {
const source = fragment.reportRef ? `(来源报告:${fragment.reportRef})` : "";
return `${i + 1}. ${fragment.content}${source}`;
});
const userLines = [
`学习任务:${taskName}`,
taskDescription ? `任务描述:${taskDescription}` : "",
"",
"知识碎片:",
...fragmentLines,
];
if (hasReports) {
userLines.push("", "参考报告(是否采用见规则 7~10):");
for (const report of reports) {
userLines.push(`[报告 ${report.ref}]${report.taskName ? `(来自学习任务「${report.taskName}」)` : ""}`);
if (report.sessionSummary) userLines.push(`会话摘要:${report.sessionSummary}`);
if (report.expectationVerdict) userLines.push(`预期达成判断:${report.expectationVerdict}`);
if (report.freeSummary) userLines.push(`自由总结:${report.freeSummary}`);
}
}
return [
{
role: "system",
content: [
"你是一名知识结构整理助手。请阅读某个学习任务的全部学习报告,",
"将其中的知识点整理成一份思维导图大纲。要求:",
"1. 第一行是导图根标题(任务主题);",
"2. 之后每行一个节点,用两个空格的缩进表示层级;",
"3. 按知识的内在结构组织(概念→细分→要点),不按时间顺序;",
"4. 合并重复的知识点;",
"5. 只基于给定内容,不补充外部知识;",
"6. 直接输出大纲,不要任何解释。",
].join(""),
},
{
role: "user",
content: [
`学习任务:${taskName}`,
taskDescription ? `任务描述:${taskDescription}` : "",
"",
"学习报告:",
...reports.map((r, i) => `${i + 1}. ${r}`),
]
.filter(Boolean)
.join("\n"),
},
{ role: "system", content: systemRules.join("") },
{ role: "user", content: userLines.filter(Boolean).join("\n") },
];
}
@@ -156,3 +212,35 @@ export function compareRecallPrompt(
},
];
}
/**
* 学习引导:用一个开放式问题引出用户的回答,并针对回答里隐含的概念边界问题纠正。
*
* 与其它能力不同,学习引导**允许完全依赖 AI**:它不属于核心闭环,AI 不可用时整体不可用,
* 因此这里不做降级拼接。
*
* 要求:不判分、不评价对错、不设轮数上限;只在回答里确实存在边界问题时纠正,
* 没有问题时继续往下追问一层,不做无意义的夸奖。
*/
export function guidancePrompt(
taskName: string,
concept: string,
history: ChatMessage[],
): ChatMessage[] {
return [
{
role: "system",
content: [
"你是一名学习引导助手。用户在复习某个知识概念,你要用开放式问题引导他主动表达,",
"并从他的回答里发现隐含的概念边界问题并纠正。要求:",
"1. 不给分数、不评价好坏、不用「很好」「不错」这类空话;",
"2. 只有当回答里真的存在概念混淆、边界模糊或错误前提时才纠正,纠正要给出具体边界;",
"3. 纠正之后继续追问一层更深的问题,帮助用户把边界说清楚;",
"4. 如果回答没有问题,直接追问更深或相邻的问题;",
"5. 一次只问一个问题,语言简短、口语化,不超过 80 字;",
`6. 用户正在复习的学习任务是「${taskName}」,被引导的概念是「${concept}」。`,
].join(""),
},
...history,
];
}
+196
View File
@@ -0,0 +1,196 @@
import { describe, expect, it } from "vitest";
import { LlmError, parseRetryAfter } from "./client.js";
import { computeBackoffMs, isRetryableLlmError, withRetry } from "./retry.js";
describe("parseRetryAfter", () => {
it("解析秒数形式", () => {
expect(parseRetryAfter("5")).toBe(5000);
expect(parseRetryAfter("0")).toBe(0);
});
it("解析 HTTP 日期形式", () => {
const now = Date.parse("2026-10-08T10:00:00Z");
expect(parseRetryAfter("Thu, 08 Oct 2026 10:00:03 GMT", now)).toBe(3000);
});
it("空值与非法值返回 undefined", () => {
expect(parseRetryAfter(null)).toBeUndefined();
expect(parseRetryAfter("")).toBeUndefined();
expect(parseRetryAfter(" ")).toBeUndefined();
expect(parseRetryAfter("soon")).toBeUndefined();
});
it("已过期的日期不会返回负数", () => {
const now = Date.parse("2026-10-08T10:00:10Z");
expect(parseRetryAfter("Thu, 08 Oct 2026 10:00:00 GMT", now)).toBe(0);
});
});
describe("isRetryableLlmError", () => {
it("限流与服务端错误可重试", () => {
for (const status of [408, 429, 500, 502, 503, 504]) {
expect(isRetryableLlmError(new LlmError("x", status))).toBe(true);
}
});
it("客户端错误不重试", () => {
for (const status of [400, 401, 403, 404, 422]) {
expect(isRetryableLlmError(new LlmError("x", status))).toBe(false);
}
});
it("未配置 API Key 不重试(重试也不会成功)", () => {
expect(isRetryableLlmError(new LlmError("LLM API Key 未配置", 503))).toBe(false);
});
it("非 LlmError 不重试", () => {
expect(isRetryableLlmError(new Error("boom"))).toBe(false);
expect(isRetryableLlmError("boom")).toBe(false);
expect(isRetryableLlmError(undefined)).toBe(false);
});
});
describe("computeBackoffMs", () => {
const base = { baseDelayMs: 1000, maxDelayMs: 20000, factor: 2, jitterRatio: 0 };
it("按指数增长", () => {
expect(computeBackoffMs(1, base)).toBe(1000);
expect(computeBackoffMs(2, base)).toBe(2000);
expect(computeBackoffMs(3, base)).toBe(4000);
});
it("受上限约束", () => {
expect(computeBackoffMs(10, base)).toBe(20000);
});
it("服务端给的建议等待优先于指数退避", () => {
expect(computeBackoffMs(1, base, 7000)).toBe(7000);
});
it("服务端建议同样受上限约束", () => {
expect(computeBackoffMs(1, base, 999999)).toBe(20000);
});
it("抖动落在 ±比例范围内且不为负", () => {
const jittered = { ...base, jitterRatio: 0.2 };
// random()=0 → 减满抖动;random()=1 → 加满抖动
expect(computeBackoffMs(1, jittered, undefined, () => 0)).toBe(800);
expect(computeBackoffMs(1, jittered, undefined, () => 1)).toBe(1200);
expect(computeBackoffMs(1, jittered, undefined, () => 0.5)).toBe(1000);
});
});
describe("withRetry", () => {
const noSleep = async (): Promise<void> => {};
it("首次成功不重试", async () => {
let calls = 0;
const result = await withRetry(
async () => {
calls += 1;
return "ok";
},
{ maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep },
);
expect(result).toBe("ok");
expect(calls).toBe(1);
});
it("可重试错误会重试直到成功", async () => {
let calls = 0;
const result = await withRetry(
async () => {
calls += 1;
if (calls < 3) throw new LlmError("限流了", 429);
return "ok";
},
{ maxAttempts: 5, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep },
);
expect(result).toBe("ok");
expect(calls).toBe(3);
});
it("不可重试错误立即抛出,不浪费重试", async () => {
let calls = 0;
await expect(
withRetry(
async () => {
calls += 1;
throw new LlmError("参数错误", 400);
},
{ maxAttempts: 5, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep },
),
).rejects.toThrow("参数错误");
expect(calls).toBe(1);
});
it("重试次数用尽后抛出最后一次的错误", async () => {
let calls = 0;
await expect(
withRetry(
async () => {
calls += 1;
throw new LlmError(`第 ${calls} 次`, 503);
},
{ maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep },
),
).rejects.toThrow("第 3 次");
expect(calls).toBe(3);
});
it("maxAttempts 为 1 时等价于不重试", async () => {
let calls = 0;
await expect(
withRetry(
async () => {
calls += 1;
throw new LlmError("x", 503);
},
{ maxAttempts: 1, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep },
),
).rejects.toThrow();
expect(calls).toBe(1);
});
it("每次重试前回调,带上尝试序号与等待时长", async () => {
const seen: Array<{ attempt: number; delayMs: number }> = [];
await expect(
withRetry(
async () => {
throw new LlmError("x", 503);
},
{
maxAttempts: 3,
baseDelayMs: 100,
maxDelayMs: 10_000,
jitterRatio: 0,
sleep: noSleep,
onRetry: (info) => seen.push({ attempt: info.attempt, delayMs: info.delayMs }),
},
),
).rejects.toThrow();
expect(seen).toEqual([
{ attempt: 1, delayMs: 100 },
{ attempt: 2, delayMs: 200 },
]);
});
it("服务端 Retry-After 会覆盖指数退避的等待时长", async () => {
const delays: number[] = [];
await expect(
withRetry(
async () => {
throw new LlmError("限流", 429, 5000);
},
{
maxAttempts: 2,
baseDelayMs: 10,
maxDelayMs: 10_000,
sleep: noSleep,
onRetry: (info) => delays.push(info.delayMs),
},
),
).rejects.toThrow();
expect(delays).toEqual([5000]);
});
});
+124
View File
@@ -0,0 +1,124 @@
/**
* LLM 调用的退避重试。
*
* 背景:LLM 服务商的 429(限流)与 5xx(瞬时故障)是常态抖动,
* 把它们当成永久失败会让用户看到「AI 失败」而实际上只是被限流了一下。
* 本模块只负责「哪些错误值得重试」与「等多久再试」,不关心任务队列。
*/
import { LlmError } from "./client.js";
/** 默认值得重试的上游状态码 */
const RETRYABLE_STATUS = new Set([
408, // 请求超时
425, // Too Early
429, // 限流
500, // 上游内部错误
502, // 网关错误
503, // 服务不可用
504, // 网关超时
]);
/**
* 判断一个错误是否值得重试。
*
* 原则:只有「重试可能成功」的错误才重试。
* - 429 / 5xx / 网络异常 / 超时 → 可重试
* - 400 / 401 / 403 / 404 等客户端错误 → 不可重试(重试多少次都一样)
* - 未配置 API Key(503 但属配置问题)→ 不可重试
*/
export function isRetryableLlmError(error: unknown): boolean {
if (!(error instanceof LlmError)) {
// 非 LlmError 的异常(例如 JSON 解析失败)不重试,避免无限循环
return false;
}
if (error.message.includes("API Key 未配置")) {
return false;
}
// 超时统一为 504,属于可重试
return RETRYABLE_STATUS.has(error.statusCode);
}
export interface RetryOptions {
/** 总尝试次数(含首次)。<=1 表示不重试 */
maxAttempts: number;
/** 首次退避基准(毫秒),之后按倍数增长 */
baseDelayMs: number;
/** 单次退避上限(毫秒) */
maxDelayMs: number;
/** 指数倍数,默认 2 */
factor?: number;
/** 抖动比例 0~1,默认 0.2,避免多个任务同时重试造成共振 */
jitterRatio?: number;
/** 判断是否重试,默认 isRetryableLlmError */
isRetryable?: (error: unknown) => boolean;
/** 注入以便测试 */
sleep?: (ms: number) => Promise<void>;
/** 注入以便测试 */
random?: () => number;
/** 每次重试前的回调,用于日志 */
onRetry?: (info: { attempt: number; delayMs: number; error: unknown }) => void;
}
const defaultSleep = (ms: number): Promise<void> =>
new Promise((resolve) => {
setTimeout(resolve, ms);
});
/**
* 计算第 attempt 次重试(attempt 从 1 开始)应等待的毫秒数。
*
* 优先采用服务端给的 `Retry-After`,否则用指数退避 + 抖动,并受 maxDelayMs 限制。
*/
export function computeBackoffMs(
attempt: number,
options: Pick<RetryOptions, "baseDelayMs" | "maxDelayMs" | "factor" | "jitterRatio">,
serverHintMs?: number,
random: () => number = Math.random,
): number {
const factor = options.factor ?? 2;
const jitterRatio = options.jitterRatio ?? 0.2;
const base = Math.min(options.baseDelayMs * factor ** (attempt - 1), options.maxDelayMs);
// 服务端明确要求等待时以它为准(同样受上限约束),此时不再叠加抖动
if (serverHintMs !== undefined && serverHintMs >= 0) {
return Math.min(serverHintMs, options.maxDelayMs);
}
const jitter = base * jitterRatio * (random() * 2 - 1);
return Math.max(0, Math.round(Math.min(base + jitter, options.maxDelayMs)));
}
/**
* 执行 fn,失败且可重试时按退避策略重试。
*
* 最后一次失败会原样抛出,调用方据此判断任务最终状态。
*/
export async function withRetry<T>(
fn: () => Promise<T>,
options: RetryOptions,
): Promise<T> {
const isRetryable = options.isRetryable ?? isRetryableLlmError;
const sleep = options.sleep ?? defaultSleep;
const random = options.random ?? Math.random;
const attempts = Math.max(1, Math.floor(options.maxAttempts));
let lastError: unknown;
for (let attempt = 1; attempt <= attempts; attempt += 1) {
try {
return await fn();
} catch (error) {
lastError = error;
const isLast = attempt >= attempts;
if (isLast || !isRetryable(error)) {
throw error;
}
const serverHint = error instanceof LlmError ? error.retryAfterMs : undefined;
const delayMs = computeBackoffMs(attempt, options, serverHint, random);
options.onRetry?.({ attempt, delayMs, error });
await sleep(delayMs);
}
}
// 理论不可达:循环内要么返回要么抛出
throw lastError;
}
+87
View File
@@ -0,0 +1,87 @@
import { describe, expect, it } from "vitest";
import {
loadThinkingConfig,
promptLength,
reasoningEffortFor,
type ThinkingConfig,
} from "./thinking.js";
const config = (overrides: Partial<ThinkingConfig> = {}): ThinkingConfig => ({
enabled: true,
lowAt: 500,
highAt: 2_000,
maxAt: 8_000,
...overrides,
});
describe("loadThinkingConfig", () => {
it("缺省值可用:开启自适应,500 / 2000 / 8000 分档", () => {
expect(loadThinkingConfig({})).toEqual({
enabled: true,
lowAt: 500,
highAt: 2_000,
maxAt: 8_000,
});
});
it("环境变量可覆盖阈值", () => {
const loaded = loadThinkingConfig({
LPT_AI_REASONING_LOW_AT: "100",
LPT_AI_REASONING_HIGH_AT: "900",
LPT_AI_REASONING_MAX_AT: "5000",
});
expect(loaded).toMatchObject({ lowAt: 100, highAt: 900, maxAt: 5_000 });
});
it("非法阈值回退到缺省", () => {
const loaded = loadThinkingConfig({
LPT_AI_REASONING_LOW_AT: "-1",
LPT_AI_REASONING_HIGH_AT: "abc",
});
expect(loaded.lowAt).toBe(500);
expect(loaded.highAt).toBe(2_000);
});
it("只有显式 false 才关闭自适应,空值与其他取值都保持开启", () => {
expect(loadThinkingConfig({ LPT_AI_REASONING_ENABLED: "false" }).enabled).toBe(false);
expect(loadThinkingConfig({ LPT_AI_REASONING_ENABLED: "False" }).enabled).toBe(false);
expect(loadThinkingConfig({ LPT_AI_REASONING_ENABLED: "" }).enabled).toBe(true);
expect(loadThinkingConfig({ LPT_AI_REASONING_ENABLED: "0" }).enabled).toBe(true);
});
});
describe("promptLength", () => {
it("累加所有 message 的正文长度", () => {
expect(
promptLength([
{ role: "system", content: "abcd" },
{ role: "user", content: "efg" },
]),
).toBe(7);
});
it("空消息列表为 0", () => {
expect(promptLength([])).toBe(0);
});
});
describe("reasoningEffortFor", () => {
it("按长度落在对应档位", () => {
expect(reasoningEffortFor(0, config())).toBe("none");
expect(reasoningEffortFor(499, config())).toBe("none");
expect(reasoningEffortFor(500, config())).toBe("low");
expect(reasoningEffortFor(1_999, config())).toBe("low");
expect(reasoningEffortFor(2_000, config())).toBe("high");
expect(reasoningEffortFor(7_999, config())).toBe("high");
expect(reasoningEffortFor(8_000, config())).toBe("max");
expect(reasoningEffortFor(100_000, config())).toBe("max");
});
it("阈值写反时按升序兜底,仍保持单调不降", () => {
const reversed = config({ lowAt: 5_000, highAt: 100, maxAt: 200 });
expect(reasoningEffortFor(50, reversed)).toBe("none");
expect(reasoningEffortFor(100, reversed)).toBe("low");
expect(reasoningEffortFor(200, reversed)).toBe("high");
expect(reasoningEffortFor(5_000, reversed)).toBe("max");
});
});
+74
View File
@@ -0,0 +1,74 @@
/**
* 思考强度(reasoning_effort)自适应 —— 按 prompt 内容长度选档。
*
* 背景:DeepSeek 的 `reasoning_effort` 缺省是 `high`,即不显式指定时每次都按满档思考。
* 残片聚合、单轮引导这类短输入根本不需要那么多思考,白付额度和延迟;
* 所以这里用一个统一口径(所有 message 正文字符数)决定档位,短文本直接 `none` 关掉思考。
*
* 契约:`reasoning_effort` 只作为调用参数随请求发送,**不进任务 params**,
* 因此不影响 `type + params` 幂等键。
*/
import type { ChatMessage } from "./client.js";
/** DeepSeek `reasoning_effort` 取值;`none` 表示关闭思考模式 */
export type ReasoningEffort = "none" | "low" | "high" | "max";
export interface ThinkingConfig {
/** 是否在请求里携带 `reasoning_effort`;换到不支持该字段的供应商时可关闭(回到供应商默认) */
enabled: boolean;
/** 长度达到该值起用 low;低于它一律 none(不思考) */
lowAt: number;
/** 长度达到该值起用 high */
highAt: number;
/** 长度达到该值起用 max */
maxAt: number;
}
const DEFAULT_LOW_AT = 500;
const DEFAULT_HIGH_AT = 2_000;
const DEFAULT_MAX_AT = 8_000;
function intFrom(value: string | undefined, fallback: number): number {
if (value === undefined || value.trim() === "") return fallback;
const parsed = Number(value);
return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
}
/** 只有显式写 `false`(不区分大小写)才关闭,避免部署里写错的空值把功能悄悄关掉 */
function boolFrom(value: string | undefined, fallback: boolean): boolean {
if (value === undefined || value.trim() === "") return fallback;
return value.trim().toLowerCase() !== "false";
}
export function loadThinkingConfig(env: NodeJS.ProcessEnv = process.env): ThinkingConfig {
return {
enabled: boolFrom(env.LPT_AI_REASONING_ENABLED, true),
lowAt: intFrom(env.LPT_AI_REASONING_LOW_AT, DEFAULT_LOW_AT),
highAt: intFrom(env.LPT_AI_REASONING_HIGH_AT, DEFAULT_HIGH_AT),
maxAt: intFrom(env.LPT_AI_REASONING_MAX_AT, DEFAULT_MAX_AT),
};
}
/** prompt 总字符数:所有 message 正文长度之和(system 说明与 user 素材都算) */
export function promptLength(messages: ChatMessage[]): number {
return messages.reduce((sum, message) => sum + message.content.length, 0);
}
/**
* 阈值必须严格递增,否则分档会出现「永远命中低档」的坑;
* 这里把写反或写重的配置按升序排一遍并去重兜底,宁可升档也不静默错档。
*/
function normalizeThresholds(config: ThinkingConfig): [number, number, number] {
const sorted = [config.lowAt, config.highAt, config.maxAt].sort((a, b) => a - b);
return [sorted[0], Math.max(sorted[1], sorted[0] + 1), Math.max(sorted[2], sorted[1] + 1)];
}
/** 按 prompt 长度选思考档位:越短越省,越长越深 */
export function reasoningEffortFor(length: number, config: ThinkingConfig): ReasoningEffort {
const [lowAt, highAt, maxAt] = normalizeThresholds(config);
if (length >= maxAt) return "max";
if (length >= highAt) return "high";
if (length >= lowAt) return "low";
return "none";
}
+134
View File
@@ -0,0 +1,134 @@
import { describe, expect, it } from "vitest";
import {
accumulateUsage,
combineSource,
emptyUsage,
hasUsage,
normalizeUsage,
type TokenUsage,
} from "./usage.js";
function usage(partial: Partial<TokenUsage>): TokenUsage {
return { ...emptyUsage(), ...partial };
}
describe("normalizeUsage", () => {
it("取 DeepSeek 顶层字段,包括缓存命中与未命中", () => {
const { usage: result, source } = normalizeUsage({
prompt_tokens: 1000,
completion_tokens: 200,
total_tokens: 1200,
prompt_cache_hit_tokens: 800,
prompt_cache_miss_tokens: 200,
completion_tokens_details: { reasoning_tokens: 50 },
});
expect(source).toBe("upstream");
expect(result).toEqual({
promptTokens: 1000,
completionTokens: 200,
totalTokens: 1200,
cacheHitTokens: 800,
cacheMissTokens: 200,
reasoningTokens: 50,
});
});
it("OpenAI 风格的 prompt_tokens_details.cached_tokens 也能识别", () => {
const { usage: result } = normalizeUsage({
prompt_tokens: 500,
completion_tokens: 100,
prompt_tokens_details: { cached_tokens: 300 },
});
expect(result.cacheHitTokens).toBe(300);
// 未命中数缺失时用 prompt - hit 兜底推出
expect(result.cacheMissTokens).toBe(200);
});
it("total_tokens 缺失时用 prompt + completion 兜底", () => {
const { usage: result } = normalizeUsage({ prompt_tokens: 10, completion_tokens: 5 });
expect(result.totalTokens).toBe(15);
});
it("缓存命中数大于 prompt 时不会算出负的未命中数", () => {
const { usage: result } = normalizeUsage({
prompt_tokens: 100,
prompt_tokens_details: { cached_tokens: 150 },
});
expect(result.cacheMissTokens).toBe(0);
});
it("非对象一律当成未上报,不抛错", () => {
for (const raw of [undefined, null, "usage", 42, []]) {
const { usage: result, source } = normalizeUsage(raw);
expect(source).toBe("missing");
expect(hasUsage(result)).toBe(false);
}
});
it("负值与非数字字段按未上报处理,不猜值", () => {
const { usage: result, source } = normalizeUsage({
prompt_tokens: -5,
completion_tokens: "abc",
});
expect(source).toBe("missing");
expect(result.promptTokens).toBeNull();
expect(result.completionTokens).toBeNull();
});
it("明确上报 0 与未上报是两种结果", () => {
const reportedZero = normalizeUsage({ prompt_tokens: 0, completion_tokens: 0 });
expect(reportedZero.source).toBe("upstream");
expect(reportedZero.usage.promptTokens).toBe(0);
const missing = normalizeUsage({});
expect(missing.source).toBe("missing");
expect(missing.usage.promptTokens).toBeNull();
});
});
describe("accumulateUsage", () => {
it("累加各次尝试的用量", () => {
const result = accumulateUsage([
usage({ promptTokens: 100, completionTokens: 20, totalTokens: 120 }),
usage({ promptTokens: 150, completionTokens: 30, totalTokens: 180 }),
]);
expect(result.promptTokens).toBe(250);
expect(result.completionTokens).toBe(50);
expect(result.totalTokens).toBe(300);
});
it("某次尝试没上报的字段按 0 计,但全都没上报时保持 null", () => {
const result = accumulateUsage([
usage({ promptTokens: 100 }),
usage({}),
]);
expect(result.promptTokens).toBe(100);
// 两次都没上报的字段不能被算成 0
expect(result.completionTokens).toBeNull();
expect(result.reasoningTokens).toBeNull();
});
it("空数组返回全 null", () => {
expect(hasUsage(accumulateUsage([]))).toBe(false);
});
});
describe("combineSource", () => {
it("只要有真实上游数据就标 upstream", () => {
expect(combineSource(["missing", "upstream", "missing"])).toBe("upstream");
});
it("没有 upstream 但有估算时标 estimated", () => {
expect(combineSource(["missing", "estimated"])).toBe("estimated");
});
it("全为 missing 时标 missing", () => {
expect(combineSource(["missing", "missing"])).toBe("missing");
expect(combineSource([])).toBe("missing");
});
});
+161
View File
@@ -0,0 +1,161 @@
/**
* Token 用量归一化与跨尝试累加。
*
* 设计要点:
* - **null 与 0 是两回事**:null 表示上游根本没上报 usage,0 表示上游明确说这次用了 0。
* 面板上「未上报」与「0 token」必须能分辨,否则上游一改返回结构,用量会静默变成 0 而不是暴露出来。
* - **按厂商字段归一**:DeepSeek 把缓存命中放在顶层 `prompt_cache_hit_tokens`,
* OpenAI 兼容实现放在 `prompt_tokens_details.cached_tokens`,两者都取;
* 未命中数缺失时用 `prompt_tokens - cacheHit` 兜底推出。
* - **跨尝试累加**:一个任务重试 N 次就是 N 次计费,失败尝试若已产生 token 同样要算
* (例如上游返回 200 但内容为空)。累加时 null 视为 0,但「所有尝试都没上报」必须保持 null。
*/
/** 一次 LLM 调用的 token 明细;字段为 null 表示上游未上报该维度 */
export interface TokenUsage {
promptTokens: number | null;
completionTokens: number | null;
totalTokens: number | null;
/** 命中上下文缓存的输入 token(计价明显低于未命中) */
cacheHitTokens: number | null;
/** 未命中缓存的输入 token */
cacheMissTokens: number | null;
/** 思考模式产生的推理 token,已含在 completionTokens 内 */
reasoningTokens: number | null;
}
/**
* 用量的来源,用于区分「上游真实上报」与「本地兜底」。
* `missing` 占比升高说明上游改了返回结构,是需要告警的信号。
*/
export type UsageSource = "upstream" | "estimated" | "missing";
export interface UsageSnapshot {
usage: TokenUsage;
source: UsageSource;
}
const TOKEN_FIELDS = [
"promptTokens",
"completionTokens",
"totalTokens",
"cacheHitTokens",
"cacheMissTokens",
"reasoningTokens",
] as const satisfies readonly (keyof TokenUsage)[];
export function emptyUsage(): TokenUsage {
return {
promptTokens: null,
completionTokens: null,
totalTokens: null,
cacheHitTokens: null,
cacheMissTokens: null,
reasoningTokens: null,
};
}
export function hasUsage(usage: TokenUsage): boolean {
return TOKEN_FIELDS.some((field) => usage[field] !== null);
}
/** 只接受非负整数;负值、NaN、非数字一律当「未上报」,不要猜 */
function nonNegativeInt(value: unknown): number | null {
if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return null;
return Math.floor(value);
}
function firstPresent(...values: Array<number | null>): number | null {
for (const value of values) {
if (value !== null) return value;
}
return null;
}
function readPath(source: Record<string, unknown>, path: string): number | null {
let current: unknown = source;
for (const key of path.split(".")) {
if (current === null || typeof current !== "object") return null;
current = (current as Record<string, unknown>)[key];
}
return nonNegativeInt(current);
}
/**
* 把上游响应里的 `usage` 对象归一化成 {@link TokenUsage}。
*
* 传入任何非对象(undefined、null、字符串)都返回全 null 且来源为 `missing`,
* 让调用方无需自己判空。
*/
export function normalizeUsage(raw: unknown): UsageSnapshot {
if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
return { usage: emptyUsage(), source: "missing" };
}
const source = raw as Record<string, unknown>;
// Anthropic 风格的 input/output_tokens 一并兼容,换供应商时不用改这里
const promptTokens = firstPresent(
readPath(source, "prompt_tokens"),
readPath(source, "input_tokens"),
);
const completionTokens = firstPresent(
readPath(source, "completion_tokens"),
readPath(source, "output_tokens"),
);
const totalTokens = firstPresent(
readPath(source, "total_tokens"),
promptTokens !== null && completionTokens !== null ? promptTokens + completionTokens : null,
);
const cacheHitTokens = firstPresent(
readPath(source, "prompt_cache_hit_tokens"),
readPath(source, "prompt_tokens_details.cached_tokens"),
readPath(source, "input_tokens_details.cached_tokens"),
);
const cacheMissTokens = firstPresent(
readPath(source, "prompt_cache_miss_tokens"),
// 上游只给总数与命中数时,相减即未命中数;钳到 0 避免上游字段不一致时算出负数
promptTokens !== null && cacheHitTokens !== null
? Math.max(0, promptTokens - cacheHitTokens)
: null,
);
const reasoningTokens = readPath(source, "completion_tokens_details.reasoning_tokens");
const usage: TokenUsage = {
promptTokens,
completionTokens,
totalTokens,
cacheHitTokens,
cacheMissTokens,
reasoningTokens,
};
return { usage, source: hasUsage(usage) ? "upstream" : "missing" };
}
/**
* 累加多次尝试的用量。
*
* 每个字段独立判断:只要有任意一次上报了该字段就求和(未上报的那几次按 0 计),
* 全部都没上报才返回 null。这样「重试 3 次只有第 2 次拿到 usage」不会被算成 0。
*/
export function accumulateUsage(snapshots: TokenUsage[]): TokenUsage {
const result = emptyUsage();
for (const field of TOKEN_FIELDS) {
const present = snapshots
.map((snapshot) => snapshot[field])
.filter((value): value is number => value !== null);
result[field] = present.length > 0 ? present.reduce((sum, value) => sum + value, 0) : null;
}
return result;
}
/**
* 合并多次尝试的来源标记。
*
* 只要有一次拿到真实上游数据就标 `upstream`——部分上报仍比完全没有数据可信,
* 把它降级成 `estimated` 会让「上游改结构」这个信号被淹没。
*/
export function combineSource(sources: UsageSource[]): UsageSource {
if (sources.includes("upstream")) return "upstream";
if (sources.includes("estimated")) return "estimated";
return "missing";
}
+127
View File
@@ -0,0 +1,127 @@
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import Fastify from "fastify";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { aiRoutes } from "./ai.js";
import { getTask } from "../task-queue.js";
const originalDataDir = process.env.LPT_AI_DATA_DIR;
const originalKey = process.env.LLM_API_KEY;
const originalRateLimit = process.env.LPT_AI_RATE_LIMIT;
let workDir: string;
beforeEach(() => {
// 面板日志会落盘,必须指向临时目录,否则会清掉开发者真实的面板数据
workDir = mkdtempSync(join(tmpdir(), "lpt-ai-routes-"));
process.env.LPT_AI_DATA_DIR = workDir;
// 不配 Key:任务会以「LLM 不可用」快速失败,用例不需要真调 LLM
delete process.env.LLM_API_KEY;
process.env.LPT_AI_RATE_LIMIT = "10000";
});
afterEach(() => {
for (const [key, value] of [
["LPT_AI_DATA_DIR", originalDataDir],
["LLM_API_KEY", originalKey],
["LPT_AI_RATE_LIMIT", originalRateLimit],
] as const) {
if (value === undefined) {
delete process.env[key];
} else {
process.env[key] = value;
}
}
rmSync(workDir, { recursive: true, force: true });
});
async function buildApp() {
const app = Fastify();
await app.register(aiRoutes);
await app.ready();
return app;
}
function submit(app: Awaited<ReturnType<typeof buildApp>>, body: unknown) {
return app.inject({
method: "POST",
url: "/ai/tasks",
payload: body as Record<string, unknown>,
});
}
describe("POST /ai/tasks 的 callerRef(用量归属)", () => {
it("带归属提交时落到任务记录上,供结算写进用量记录", async () => {
const app = await buildApp();
const response = await submit(app, {
type: "guidance",
params: { taskName: "t", concept: "c", history: [] },
callerRef: "U-123",
});
expect(response.statusCode).toBe(201);
const { taskId } = JSON.parse(response.body) as { taskId: string };
expect(getTask(taskId)?.callerRef).toBe("U-123");
await app.close();
});
it("不传归属时任务记录上没有该字段", async () => {
const app = await buildApp();
const response = await submit(app, {
type: "guidance",
params: { taskName: "t", concept: "c", history: [] },
});
const { taskId } = JSON.parse(response.body) as { taskId: string };
expect(getTask(taskId)?.callerRef).toBeUndefined();
await app.close();
});
it("空白归属视为未传,不写空字符串", async () => {
const app = await buildApp();
const response = await submit(app, {
type: "guidance",
params: { taskName: "t", concept: "c", history: [] },
callerRef: " ",
});
const { taskId } = JSON.parse(response.body) as { taskId: string };
expect(getTask(taskId)?.callerRef).toBeUndefined();
await app.close();
});
it("超过 64 字符被拒:它会落进日志与数据库列,限长比让库截断安全", async () => {
const app = await buildApp();
const response = await submit(app, {
type: "guidance",
params: { taskName: "t", concept: "c", history: [] },
callerRef: "x".repeat(65),
});
expect(response.statusCode).toBe(400);
expect(JSON.parse(response.body).error).toContain("64");
await app.close();
});
it("非字符串被拒,避免把对象写进归属列", async () => {
const app = await buildApp();
const response = await submit(app, {
type: "guidance",
params: { taskName: "t", concept: "c", history: [] },
callerRef: { userId: "U-1" },
});
expect(response.statusCode).toBe(400);
await app.close();
});
it("归属不影响参数校验:type 非法仍然优先报错", async () => {
const app = await buildApp();
const response = await submit(app, { type: "nope", params: {}, callerRef: "U-1" });
expect(response.statusCode).toBe(400);
expect(JSON.parse(response.body).error).toContain("无效的 type");
await app.close();
});
});
+106 -17
View File
@@ -6,10 +6,45 @@ import type { FastifyInstance } from "fastify";
import { isAvailable, loadConfig } from "../llm/client.js";
import { createTask, getTask, type TaskType } from "../task-queue.js";
import { logStore } from "../admin/store.js";
import { safeFetchText, UnsafeUrlError } from "../utils/ssrf-guard.js";
import { RateLimiter, intFromEnv } from "../utils/rate-limit.js";
import { checkToken } from "../utils/auth.js";
/**
* 归属标记的最大长度。
*
* 它会落进日志与 lpt-be 的 `ai_usage_records.user_id`(VARCHAR(255)),
* 在入口限长比让数据库截断更安全。
*/
const MAX_CALLER_REF_LENGTH = 64;
export async function aiRoutes(app: FastifyInstance): Promise<void> {
const config = loadConfig();
// 安全-03:AI 任务会消耗 LLM 额度,按来源限流(单进程粗粒度保护)
const taskLimiter = new RateLimiter({
limit: intFromEnv("LPT_AI_RATE_LIMIT", 30),
windowMs: intFromEnv("LPT_AI_RATE_WINDOW_MS", 60_000),
});
// 安全-03:可选的入站令牌。设置了 LPT_AI_TOKEN 时,所有 /ai/* 请求都必须携带
app.addHook("preHandler", async (request, reply) => {
if (!request.url.startsWith("/ai/")) return;
if (!checkToken(request, reply)) {
return reply;
}
return undefined;
});
/** 取限流用的来源标识:优先真实客户端 IP(后面有反代时取 X-Forwarded-For 首段) */
const clientKey = (request: { ip?: string; headers: Record<string, unknown> }): string => {
const forwarded = request.headers["x-forwarded-for"];
if (typeof forwarded === "string" && forwarded.trim()) {
return forwarded.split(",")[0].trim();
}
return request.ip ?? "unknown";
};
app.get("/health", async () => ({
status: "ok",
llmAvailable: isAvailable(config),
@@ -17,18 +52,57 @@ export async function aiRoutes(app: FastifyInstance): Promise<void> {
}));
/** 提交 AI 任务,立即返回 taskId */
app.post<{ Body: { type: string; params: Record<string, unknown> } }>("/ai/tasks", async (request, reply) => {
const { type, params } = request.body ?? {};
app.post<{
Body: {
type: string;
params: Record<string, unknown>;
/** 可选:显式幂等键,用于跨请求去重 */
idempotencyKey?: string;
/** 可选:跳过结果复用,强制重新生成 */
force?: boolean;
/** 可选:归属标记(lpt-be 传用户 id),原样写进用量记录;不参与幂等键 */
callerRef?: string;
};
}>("/ai/tasks", async (request, reply) => {
const { type, params, idempotencyKey, force, callerRef } = request.body ?? {};
if (!type || !["aggregate-report", "generate-mind-map", "compare-recall"].includes(type)) {
return reply.status(400).send({ error: "无效的 type,允许: aggregate-report, generate-mind-map, compare-recall" });
const decision = taskLimiter.check(clientKey(request));
if (!decision.allowed) {
app.log.warn({ key: clientKey(request) }, "AI 任务提交被限流");
return reply
.status(429)
.header("retry-after", String(Math.ceil(decision.retryAfterMs / 1000)))
.send({ error: "提交太频繁了,请稍后再试" });
}
if (!type || !["aggregate-report", "generate-mind-map", "compare-recall", "guidance"].includes(type)) {
return reply.status(400).send({ error: "无效的 type,允许: aggregate-report, generate-mind-map, compare-recall, guidance" });
}
if (!params || typeof params !== "object") {
return reply.status(400).send({ error: "params 必须为非空对象" });
}
// 归属标记是 opaque 字符串,但必须限长:它会落进日志与数据库列(VARCHAR(64))
if (callerRef !== undefined && callerRef !== null) {
if (typeof callerRef !== "string" || callerRef.length > MAX_CALLER_REF_LENGTH) {
return reply
.status(400)
.send({ error: `callerRef 必须是不超过 ${MAX_CALLER_REF_LENGTH} 字符的字符串` });
}
}
const taskId = createTask(type as TaskType, params as Record<string, unknown>);
return reply.status(201).send({ taskId });
const created = createTask(type as TaskType, params as Record<string, unknown>, {
...(typeof idempotencyKey === "string" && idempotencyKey.trim().length > 0
? { idempotencyKey }
: {}),
...(force === true ? { force: true } : {}),
...(typeof callerRef === "string" && callerRef.trim().length > 0
? { callerRef: callerRef.trim() }
: {}),
});
// 固定返回 201:Java 端 AiServiceClient 把非 201 当作提交失败,
// 所以不能改用 200 表达「复用」。复用信息放在响应体里。
return reply.status(201).send(created);
});
/** 查询任务状态与结果 */
@@ -41,29 +115,33 @@ export async function aiRoutes(app: FastifyInstance): Promise<void> {
return task;
});
/** 抓取网页标题 */
/**
* 抓取网页标题。
*
* <p>安全-03:目标由调用方给出,因此在抓取前做协议、端口、DNS 解析与逐跳重定向校验,
* 避免被当成探测内网与云元数据的跳板,同时对响应体做截断。</p>
*/
app.post<{ Body: { url: string } }>("/fetch-title", async (request, reply) => {
const { url } = request.body ?? {};
const t0 = Date.now();
if (!url || typeof url !== "string" || (!url.startsWith("http://") && !url.startsWith("https://"))) {
if (!url || typeof url !== "string") {
return reply.status(400).send({ error: "无效的 URL" });
}
try {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 10_000);
const response = await fetch(url, { signal: controller.signal });
clearTimeout(timer);
const html = await response.text();
const match = html.match(/<title[^>]*>([^<]+)<\/title>/i);
const { body } = await safeFetchText(url);
const match = body.match(/<title[^>]*>([^<]+)<\/title>/i);
const title = match ? match[1].trim() : null;
logStore.add({
timestamp: new Date().toISOString(),
endpoint: "/fetch-title",
taskType: "fetch-title",
model: "",
attempts: 1,
// 抓标题不过 LLM,不计入用量统计
isLlmCall: false,
durationMs: Date.now() - t0,
status: 200,
requestBody: { url },
@@ -71,16 +149,27 @@ export async function aiRoutes(app: FastifyInstance): Promise<void> {
});
return { url, title };
} catch (err) {
// 被安全校验拦下时返回 400(调用方的问题),其余按抓取失败处理
const blocked = err instanceof UnsafeUrlError;
const message = err instanceof Error ? err.message : String(err);
logStore.add({
timestamp: new Date().toISOString(),
endpoint: "/fetch-title",
taskType: "fetch-title",
model: "",
attempts: 1,
// 抓标题不过 LLM,不计入用量统计
isLlmCall: false,
durationMs: Date.now() - t0,
status: 502,
status: blocked ? 400 : 502,
requestBody: { url },
responseBody: { url, title: null },
error: err instanceof Error ? err.message : String(err),
error: message,
errorCode: blocked ? "unsafe_url" : "fetch_failed",
});
if (blocked) {
return reply.status(400).send({ error: message });
}
return { url, title: null };
}
});
+758
View File
@@ -0,0 +1,758 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { LlmError } from "./llm/client.js";
import { classifyLlmError, parseReportDraft, TaskQueue, computeTaskKey, callOptionsFor, loadQueueConfig, type QueueConfig, type TaskRecord } from "./task-queue.js";
/** 测试用队列:不碰真实 LLM、不写管理面板日志、不启定时器 */
function makeQueue(
overrides: Partial<QueueConfig> = {},
runOnce?: (task: TaskRecord) => Promise<unknown>,
): TaskQueue {
return new TaskQueue({
config: {
concurrency: 2,
maxAttempts: 3,
retryBaseMs: 1,
retryMaxMs: 10,
ttlMs: 60_000,
cleanupIntervalMs: 60_000,
resultCacheMs: 10_000,
...overrides,
},
enableCleanup: false,
isLlmAvailable: () => true,
sleep: async () => {},
onSettled: () => {},
...(runOnce ? { runOnce: async (task) => runOnce(task) } : {}),
});
}
function ok(params: Record<string, unknown> = { taskName: "t", fragments: [] }) {
return params;
}
describe("loadQueueConfig", () => {
it("缺省值可用", () => {
const config = loadQueueConfig({});
expect(config.concurrency).toBe(2);
expect(config.maxAttempts).toBe(3);
expect(config.resultCacheMs).toBe(600_000);
});
it("环境变量可覆盖", () => {
const config = loadQueueConfig({
LPT_AI_CONCURRENCY: "5",
LPT_AI_MAX_ATTEMPTS: "7",
LPT_AI_RETRY_BASE_MS: "250",
});
expect(config.concurrency).toBe(5);
expect(config.maxAttempts).toBe(7);
expect(config.retryBaseMs).toBe(250);
});
it("非法值回退到缺省", () => {
const config = loadQueueConfig({ LPT_AI_CONCURRENCY: "-1", LPT_AI_MAX_ATTEMPTS: "abc" });
expect(config.concurrency).toBe(2);
expect(config.maxAttempts).toBe(3);
});
});
describe("callOptionsFor", () => {
const thinking = { enabled: true, lowAt: 500, highAt: 2_000, maxAt: 8_000 };
it("短 prompt 关闭思考,但温度与输出上限仍按任务类型", () => {
const options = callOptionsFor("aggregate-report", [{ role: "user", content: "短" }], thinking);
expect(options.reasoningEffort).toBe("none");
expect(options.temperature).toBe(0.3);
expect(options.maxTokens).toBe(2048);
});
it("长 prompt 升到 max,任务类型基准参数不变", () => {
const options = callOptionsFor(
"generate-mind-map",
[{ role: "user", content: "x".repeat(9_000) }],
thinking,
);
expect(options.reasoningEffort).toBe("max");
expect(options.temperature).toBe(0.3);
expect(options.maxTokens).toBe(4096);
});
it("关闭自适应时不带 reasoningEffort,回退供应商默认", () => {
const options = callOptionsFor(
"compare-recall",
[{ role: "user", content: "x".repeat(9_000) }],
{ ...thinking, enabled: false },
);
expect(options.reasoningEffort).toBeUndefined();
expect(options.temperature).toBe(0.2);
});
});
describe("computeTaskKey", () => {
it("同输入得到同键", () => {
const a = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "x" }] });
const b = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "x" }] });
expect(a).toBe(b);
});
it("对象键顺序不影响结果", () => {
const a = computeTaskKey("compare-recall", { taskName: "t", standardOutline: "s" });
const b = computeTaskKey("compare-recall", { standardOutline: "s", taskName: "t" });
expect(a).toBe(b);
});
it("参数不同则键不同", () => {
const a = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "x" }] });
const b = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "y" }] });
expect(a).not.toBe(b);
});
it("类型不同则键不同", () => {
const a = computeTaskKey("aggregate-report", { taskName: "t" });
const b = computeTaskKey("generate-mind-map", { taskName: "t" });
expect(a).not.toBe(b);
});
});
describe("TaskQueue 并发", () => {
it("并发度内的任务同时执行,不再串行", async () => {
let inFlight = 0;
let maxInFlight = 0;
const started: string[] = [];
const queue = makeQueue({ concurrency: 3 }, async (task) => {
inFlight += 1;
maxInFlight = Math.max(maxInFlight, inFlight);
started.push(task.id);
await new Promise((resolve) => setTimeout(resolve, 20));
inFlight -= 1;
return { ok: true };
});
for (let i = 0; i < 3; i += 1) {
queue.create("aggregate-report", { taskName: `t${i}`, fragments: [{ content: `c${i}` }] });
}
await queue.drain();
// 三个任务应同时在跑,而不是一个个来
expect(maxInFlight).toBe(3);
expect(started).toHaveLength(3);
queue.stop();
});
it("超出并发度的任务排队等待", async () => {
let inFlight = 0;
let maxInFlight = 0;
const queue = makeQueue({ concurrency: 2 }, async () => {
inFlight += 1;
maxInFlight = Math.max(maxInFlight, inFlight);
await new Promise((resolve) => setTimeout(resolve, 15));
inFlight -= 1;
return { ok: true };
});
for (let i = 0; i < 6; i += 1) {
queue.create("aggregate-report", { taskName: `t${i}`, fragments: [{ content: `c${i}` }] });
}
await queue.drain();
expect(maxInFlight).toBe(2);
queue.stop();
});
it("并发 N 个任务的总耗时明显小于串行累加", async () => {
const perTaskMs = 30;
const n = 6;
const queue = makeQueue({ concurrency: n }, async () => {
await new Promise((resolve) => setTimeout(resolve, perTaskMs));
return { ok: true };
});
const t0 = Date.now();
for (let i = 0; i < n; i += 1) {
queue.create("aggregate-report", { taskName: `t${i}`, fragments: [{ content: `c${i}` }] });
}
await queue.drain();
const elapsed = Date.now() - t0;
// 串行需要 n * perTaskMs;并发后应接近单次耗时
expect(elapsed).toBeLessThan(perTaskMs * n * 0.6);
queue.stop();
});
it("drain 在队列空闲时立即返回", async () => {
const queue = makeQueue();
await queue.drain();
expect(queue.pendingCount).toBe(0);
queue.stop();
});
});
describe("TaskQueue 相同输入复用", () => {
it("进行中的相同请求被合并,不重复执行", async () => {
let calls = 0;
const queue = makeQueue({ concurrency: 1 }, async () => {
calls += 1;
await new Promise((resolve) => setTimeout(resolve, 20));
return { ok: true };
});
const params = { taskName: "t", fragments: [{ content: "same" }] };
const first = queue.create("aggregate-report", params);
const second = queue.create("aggregate-report", params);
expect(second.taskId).toBe(first.taskId);
expect(second.reused).toBe(true);
expect(second.status).toBe("pending");
await queue.drain();
expect(calls).toBe(1);
queue.stop();
});
it("参数不同则各自新建", async () => {
const queue = makeQueue({}, async () => ({ ok: true }));
const a = queue.create("aggregate-report", { taskName: "t", fragments: [{ content: "a" }] });
const b = queue.create("aggregate-report", { taskName: "t", fragments: [{ content: "b" }] });
expect(a.taskId).not.toBe(b.taskId);
expect(b.reused).toBe(false);
await queue.drain();
queue.stop();
});
it("已完成且在窗口内的结果被复用", async () => {
let calls = 0;
const queue = makeQueue({}, async () => {
calls += 1;
return { value: calls };
});
const params = { taskName: "t", fragments: [{ content: "same" }] };
const first = queue.create("aggregate-report", params);
await queue.drain();
const second = queue.create("aggregate-report", params);
expect(second.taskId).toBe(first.taskId);
expect(second.reused).toBe(true);
expect(second.status).toBe("done");
expect(calls).toBe(1);
queue.stop();
});
it("超出结果复用窗口后重新执行", async () => {
let nowMs = 1_000_000;
let calls = 0;
const queue = new TaskQueue({
config: {
concurrency: 1,
maxAttempts: 1,
retryBaseMs: 1,
retryMaxMs: 10,
ttlMs: 10_000_000,
cleanupIntervalMs: 60_000,
resultCacheMs: 5_000,
},
enableCleanup: false,
isLlmAvailable: () => true,
sleep: async () => {},
onSettled: () => {},
now: () => nowMs,
runOnce: async () => {
calls += 1;
return { value: calls };
},
});
const params = { taskName: "t", fragments: [{ content: "same" }] };
queue.create("aggregate-report", params);
await queue.drain();
nowMs += 10_000; // 超过窗口
const again = queue.create("aggregate-report", params);
await queue.drain();
expect(again.reused).toBe(false);
expect(calls).toBe(2);
queue.stop();
});
it("失败的任务不进入复用,用户能重试", async () => {
let calls = 0;
const queue = makeQueue({ maxAttempts: 1 }, async () => {
calls += 1;
throw new LlmError("上游 400", 400);
});
const params = { taskName: "t", fragments: [{ content: "same" }] };
const first = queue.create("aggregate-report", params);
await queue.drain();
expect(queue.get(first.taskId)?.status).toBe("failed");
const second = queue.create("aggregate-report", params);
await queue.drain();
expect(second.reused).toBe(false);
expect(calls).toBe(2);
queue.stop();
});
it("force 强制新建,跳过复用", async () => {
let calls = 0;
const queue = makeQueue({}, async () => {
calls += 1;
return { value: calls };
});
const params = { taskName: "t", fragments: [{ content: "same" }] };
queue.create("aggregate-report", params);
await queue.drain();
const forced = queue.create("aggregate-report", params, { force: true });
await queue.drain();
expect(forced.reused).toBe(false);
expect(calls).toBe(2);
queue.stop();
});
it("显式幂等键可跨不同参数去重", async () => {
let calls = 0;
const queue = makeQueue({}, async () => {
calls += 1;
return { ok: true };
});
const first = queue.create("aggregate-report", { taskName: "a", fragments: [] }, { idempotencyKey: "k1" });
const second = queue.create("aggregate-report", { taskName: "b", fragments: [] }, { idempotencyKey: "k1" });
await queue.drain();
expect(second.taskId).toBe(first.taskId);
expect(calls).toBe(1);
queue.stop();
});
});
describe("TaskQueue 重试", () => {
it("429 抖动后成功,任务最终为 done 而不是 failed", async () => {
let calls = 0;
const queue = makeQueue({ maxAttempts: 3 }, async () => {
calls += 1;
if (calls < 3) throw new LlmError("限流", 429);
return { ok: true };
});
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
await queue.drain();
const task = queue.get(created.taskId);
expect(task?.status).toBe("done");
expect(calls).toBe(3);
expect(task?.attempts).toBe(3);
queue.stop();
});
it("不可重试错误只尝试一次", async () => {
let calls = 0;
const queue = makeQueue({ maxAttempts: 5 }, async () => {
calls += 1;
throw new LlmError("请求体非法", 400);
});
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
await queue.drain();
expect(queue.get(created.taskId)?.status).toBe("failed");
expect(calls).toBe(1);
queue.stop();
});
it("重试用尽后为 failed", async () => {
let calls = 0;
const queue = makeQueue({ maxAttempts: 2 }, async () => {
calls += 1;
throw new LlmError("上游挂了", 503);
});
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
await queue.drain();
const task = queue.get(created.taskId);
expect(task?.status).toBe("failed");
expect(task?.error).toContain("上游挂了");
expect(calls).toBe(2);
queue.stop();
});
it("LLM 不可用时直接失败,不空跑重试", async () => {
let calls = 0;
const queue = new TaskQueue({
config: {
concurrency: 1,
maxAttempts: 3,
retryBaseMs: 1,
retryMaxMs: 10,
ttlMs: 60_000,
cleanupIntervalMs: 60_000,
resultCacheMs: 10_000,
},
enableCleanup: false,
isLlmAvailable: () => false,
sleep: async () => {},
onSettled: () => {},
runOnce: async () => {
calls += 1;
return { ok: true };
},
});
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
await queue.drain();
const task = queue.get(created.taskId);
expect(task?.status).toBe("failed");
expect(task?.error).toContain("API Key");
expect(calls).toBe(0);
queue.stop();
});
});
describe("TaskQueue 清理", () => {
it("只清理过期的完成记录,进行中的不动", async () => {
let nowMs = 1_000_000;
const queue = new TaskQueue({
config: {
concurrency: 1,
maxAttempts: 1,
retryBaseMs: 1,
retryMaxMs: 10,
ttlMs: 1_000,
cleanupIntervalMs: 60_000,
resultCacheMs: 10,
},
enableCleanup: false,
isLlmAvailable: () => true,
sleep: async () => {},
onSettled: () => {},
now: () => nowMs,
runOnce: async () => ({ ok: true }),
});
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
await queue.drain();
expect(queue.size()).toBe(1);
nowMs += 5_000;
const removed = queue.cleanup();
expect(removed).toBe(1);
expect(queue.size()).toBe(0);
expect(queue.get(created.taskId)).toBeUndefined();
queue.stop();
});
it("清理后同输入可以重新提交,不会命中已删记录的索引", async () => {
let nowMs = 1_000_000;
let calls = 0;
const queue = new TaskQueue({
config: {
concurrency: 1,
maxAttempts: 1,
retryBaseMs: 1,
retryMaxMs: 10,
ttlMs: 1_000,
cleanupIntervalMs: 60_000,
resultCacheMs: 10,
},
enableCleanup: false,
isLlmAvailable: () => true,
sleep: async () => {},
onSettled: () => {},
now: () => nowMs,
runOnce: async () => {
calls += 1;
return { value: calls };
},
});
const params = { taskName: "t", fragments: [{ content: "x" }] };
queue.create("aggregate-report", params);
await queue.drain();
nowMs += 5_000;
queue.cleanup();
const again = queue.create("aggregate-report", params);
await queue.drain();
expect(again.reused).toBe(false);
expect(calls).toBe(2);
queue.stop();
});
});
describe("TaskQueue 基本行为", () => {
it("get 返回拷贝,外部修改不影响内部状态", async () => {
const queue = makeQueue({}, async () => ({ ok: true }));
const created = queue.create("aggregate-report", ok());
await queue.drain();
const task = queue.get(created.taskId);
expect(task).toBeDefined();
if (task) {
task.status = "failed";
}
expect(queue.get(created.taskId)?.status).toBe("done");
queue.stop();
});
it("不存在的任务返回 undefined", () => {
const queue = makeQueue();
expect(queue.get("nope")).toBeUndefined();
queue.stop();
});
it("任务记录带类型、参数、尝试次数与时间戳", async () => {
const queue = makeQueue({}, async () => ({ ok: true }));
const params = { taskName: "Java 并发", fragments: [{ content: "x" }] };
const created = queue.create("aggregate-report", params);
await queue.drain();
const task = queue.get(created.taskId);
expect(task?.type).toBe("aggregate-report");
expect(task?.params).toEqual(params);
expect(task?.attempts).toBe(1);
expect(Number.isNaN(Date.parse(task?.createdAt ?? ""))).toBe(false);
expect(Number.isNaN(Date.parse(task?.completedAt ?? ""))).toBe(false);
queue.stop();
});
});
describe("用量归集", () => {
const originalKey = process.env.LLM_API_KEY;
afterEach(() => {
vi.unstubAllGlobals();
if (originalKey === undefined) {
delete process.env.LLM_API_KEY;
} else {
process.env.LLM_API_KEY = originalKey;
}
});
/** 按顺序返回响应;用完之后重复最后一个,避免用例里数错调用次数 */
function mockChatResponses(responses: Array<{ ok: boolean; status?: number; body: unknown }>) {
let index = 0;
const fetchMock = vi.fn().mockImplementation(async () => {
const response = responses[Math.min(index, responses.length - 1)];
index += 1;
return {
ok: response.ok,
status: response.status ?? 200,
json: async () => response.body,
text: async () => JSON.stringify(response.body),
headers: new Headers(),
} as unknown as Response;
});
vi.stubGlobal("fetch", fetchMock);
return fetchMock;
}
/** 用真实 chat() 路径(而非注入 runOnce)才能验证默认执行器的用量归集 */
function queueWithRealRunner(settled: TaskRecord[]): TaskQueue {
return new TaskQueue({
config: {
concurrency: 1,
maxAttempts: 3,
retryBaseMs: 1,
retryMaxMs: 10,
ttlMs: 60_000,
cleanupIntervalMs: 60_000,
resultCacheMs: 10_000,
},
enableCleanup: false,
isLlmAvailable: () => true,
sleep: async () => {},
onSettled: (task) => settled.push(task),
});
}
function usageBody(prompt: number, completion: number) {
return {
model: "deepseek-flash",
choices: [{ message: { content: "ok" }, finish_reason: "stop" }],
usage: {
prompt_tokens: prompt,
completion_tokens: completion,
total_tokens: prompt + completion,
},
};
}
it("重试后成功:累加各次尝试的用量,而不是只留最后一次", async () => {
process.env.LLM_API_KEY = "test-key";
const settled: TaskRecord[] = [];
mockChatResponses([
{ ok: false, status: 429, body: { error: "rate limited" } },
{ ok: true, body: usageBody(100, 20) },
]);
const queue = queueWithRealRunner(settled);
queue.create("guidance", { taskName: "t", concept: "c", history: [] });
await queue.drain();
const task = settled[0];
expect(task.status).toBe("done");
expect(task.attempts).toBe(2);
expect(task.usage?.promptTokens).toBe(100);
expect(task.usageSource).toBe("upstream");
queue.stop();
});
it("失败尝试已产生的用量也计入(200 但内容为空同样是计费请求)", async () => {
process.env.LLM_API_KEY = "test-key";
const settled: TaskRecord[] = [];
mockChatResponses([
{
ok: true,
body: {
choices: [{ message: { content: "" } }],
usage: { prompt_tokens: 300, completion_tokens: 0, total_tokens: 300 },
},
},
{ ok: true, body: usageBody(100, 20) },
]);
const queue = queueWithRealRunner(settled);
queue.create("guidance", { taskName: "t", concept: "c", history: [] });
await queue.drain();
const task = settled[0];
expect(task.status).toBe("done");
expect(task.attempts).toBe(2);
// 两次尝试都计费:300 + 100 / 0 + 20
expect(task.usage?.promptTokens).toBe(400);
expect(task.usage?.completionTokens).toBe(20);
expect(task.usage?.totalTokens).toBe(420);
queue.stop();
});
it("全部尝试都没拿到用量时保持 null,不能变成 0", async () => {
process.env.LLM_API_KEY = "test-key";
const settled: TaskRecord[] = [];
mockChatResponses([{ ok: false, status: 429, body: { error: "rate limited" } }]);
const queue = queueWithRealRunner(settled);
queue.create("guidance", { taskName: "t", concept: "c", history: [] });
await queue.drain();
const task = settled[0];
expect(task.status).toBe("failed");
expect(task.usageSource).toBe("missing");
expect(task.usage?.promptTokens).toBeNull();
expect(task.errorCode).toBe("rate_limited");
queue.stop();
});
});
describe("callerRef(用量归属)", () => {
it("落到任务记录上,供结算时写进用量日志", async () => {
const queue = makeQueue({}, async () => ({ ok: true }));
const created = queue.create(
"aggregate-report",
{ taskName: "t", fragments: [] },
{ callerRef: "U-123" },
);
await queue.drain();
expect(queue.get(created.taskId)?.callerRef).toBe("U-123");
queue.stop();
});
it("不传时不写该字段,避免出现空字符串归属", async () => {
const queue = makeQueue({}, async () => ({ ok: true }));
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
await queue.drain();
expect(queue.get(created.taskId)?.callerRef).toBeUndefined();
queue.stop();
});
it("复用已有任务时沿用原归属,不被后来的调用方覆盖", async () => {
// 同类型同参数会被复用,而那次 LLM 调用只发生了一次,账算在原调用方头上;
// 复用方没有产生新的 token 消耗,也不会有新的用量记录。
const queue = makeQueue({}, async () => ({ ok: true }));
const params = { taskName: "t", fragments: [{ content: "same" }] };
const first = queue.create("aggregate-report", params, { callerRef: "U-1" });
await queue.drain();
const second = queue.create("aggregate-report", params, { callerRef: "U-2" });
expect(second.reused).toBe(true);
expect(second.taskId).toBe(first.taskId);
expect(queue.get(first.taskId)?.callerRef).toBe("U-1");
queue.stop();
});
it("不参与幂等键:同一输入带上不同归属仍然复用同一个任务", () => {
// 若 callerRef 进了键,同一份输入会因为调用方不同而重复调 LLM,白花钱
const withRef = computeTaskKey("aggregate-report", { taskName: "t" });
expect(computeTaskKey("aggregate-report", { taskName: "t" })).toBe(withRef);
});
});
describe("classifyLlmError", () => {
it("按状态码归成可聚合的分类", () => {
expect(classifyLlmError(new LlmError("超时", 504))).toBe("timeout");
expect(classifyLlmError(new LlmError("限流", 429))).toBe("rate_limited");
expect(classifyLlmError(new LlmError("余额不足", 402))).toBe("insufficient_balance");
expect(classifyLlmError(new LlmError("鉴权失败", 401))).toBe("auth_failed");
expect(classifyLlmError(new LlmError("参数非法", 400))).toBe("bad_request");
expect(classifyLlmError(new LlmError("上游挂了", 503))).toBe("upstream_error");
});
it("未配置 Key 单独归类,便于与上游故障区分", () => {
expect(classifyLlmError(new LlmError("LLM API Key 未配置", 503))).toBe("not_configured");
});
it("非 LlmError 归为 unknown,不把解析异常误当成上游故障", () => {
expect(classifyLlmError(new Error("JSON 解析失败"))).toBe("unknown");
expect(classifyLlmError("字符串异常")).toBe("unknown");
});
});
describe("parseReportDraft(结构化报告草稿)", () => {
it("解析严格 JSON 的三段", () => {
const draft = parseReportDraft(
'{"sessionSummary":"学了线程池","expectationVerdict":"部分达成","freeSummary":"想再看拒绝策略"}',
"deepseek-flash",
);
expect(draft.sessionSummary).toBe("学了线程池");
expect(draft.expectationVerdict).toBe("部分达成");
expect(draft.freeSummary).toBe("想再看拒绝策略");
expect(draft.model).toBe("deepseek-flash");
});
it("容忍 markdown 代码块围栏", () => {
const draft = parseReportDraft('```json\n{"sessionSummary":"a","expectationVerdict":"","freeSummary":"b"}\n```');
expect(draft.sessionSummary).toBe("a");
expect(draft.freeSummary).toBe("b");
});
it("不是 JSON 时降级:整段文本当作自由总结,不报错", () => {
const draft = parseReportDraft("这次学习了线程池的四种拒绝策略……");
expect(draft.sessionSummary).toBe("");
expect(draft.expectationVerdict).toBe("");
expect(draft.freeSummary).toContain("拒绝策略");
});
it("JSON 解析成功但三段全空时同样降级", () => {
const draft = parseReportDraft('{"sessionSummary":"","expectationVerdict":"","freeSummary":""}');
expect(draft.freeSummary).toContain("sessionSummary");
});
it("字段类型不对时按空字符串处理", () => {
const draft = parseReportDraft('{"sessionSummary":123,"freeSummary":"ok"}');
expect(draft.sessionSummary).toBe("");
expect(draft.freeSummary).toBe("ok");
});
});
+531 -110
View File
@@ -1,153 +1,566 @@
/**
* 异步任务队列 —— 接收任务,后台 Worker 顺序处理,提供查询。
* 异步任务队列 —— 接收任务,后台 Worker 池并发处理,提供查询与幂等复用。
*
* 设计要点:
* - 单线程 Worker(setImmediate 链),同一时刻只处理一个 LLM 调用
* - TTL 清理:5 分钟一次,移除完成超过 1 小时的记录
* - 异常隔离:单个任务失败不影响后续任务
* - 日志复用 logStore,与管理面板日志统一
* - **Worker 池**:并发度可配置。原实现用单个 processing 标志串行,
* N 个请求要等 N × LLM 耗时,客户端很容易先超时。
* - **退避重试**:429 / 5xx / 超时等瞬时抖动不再直接判失败,见 llm/retry.ts。
* - **相同输入复用**:同一 type + 同参数的请求会复用同一个任务,
* 避免重复计费;进行中的请求直接合并,已完成的结果在窗口内复用。
* - **TTL 清理**:定期移除过期的完成记录,同时清理幂等索引。
* - 依赖以构造参数注入,便于单测;生产使用文件末尾的单例。
*/
import { randomUUID } from "node:crypto";
import { chat, isAvailable, loadConfig, LlmError } from "./llm/client.js";
import { aggregateReportPrompt, compareRecallPrompt, generateMindMapPrompt } from "./llm/prompts.js";
import { randomUUID, createHash } from "node:crypto";
import { chat, isAvailable, loadConfig, LlmError, type ChatMessage, type ChatOptions } from "./llm/client.js";
import { accumulateUsage, combineSource, emptyUsage, type TokenUsage, type UsageSource } from "./llm/usage.js";
import { withRetry, isRetryableLlmError, type RetryOptions } from "./llm/retry.js";
import {
aggregateReportPrompt,
compareRecallPrompt,
generateMindMapPrompt,
guidancePrompt,
type MindMapFragmentInput,
type MindMapReportInput,
} from "./llm/prompts.js";
import { loadThinkingConfig, promptLength, reasoningEffortFor, type ThinkingConfig } from "./llm/thinking.js";
import { logStore } from "./admin/store.js";
import { loadPricingConfig, priceUsage, type PricingSnapshot } from "./admin/pricing.js";
// ---- 类型 ----
export type TaskType = "aggregate-report" | "generate-mind-map" | "compare-recall";
export type TaskType = "aggregate-report" | "generate-mind-map" | "compare-recall" | "guidance";
export type TaskStatus = "pending" | "running" | "done" | "failed";
export interface TaskRecord {
id: string;
/** 幂等键:同一 type + 同参数的记录共享同一个键 */
key: string;
type: TaskType;
params: Record<string, unknown>;
status: TaskStatus;
result?: unknown;
error?: string;
/** 已尝试次数(含首次),便于排查重试情况 */
attempts: number;
/**
* 调用方打的归属标记(lpt-be 传的是用户 id)。
*
* opaque 字符串,lpt-ai 不解释它的含义,只在结算时原样写进用量记录。
* 刻意不放进 `params`:那会污染 prompt 模板的输入,也会把幂等键算错。
*/
callerRef?: string;
/**
* 跨所有尝试累加的 token 用量。
*
* 重试会重复计费,所以这里是「这个任务一共花了多少」,不是「最后一次花了多少」;
* 某个字段为 null 表示所有尝试都没拿到该维度(不要当成 0)。
*/
usage?: TokenUsage;
usageSource?: UsageSource;
/** 失败分类(timeout / rate_limited / ...),便于按错误类型聚合用量 */
errorCode?: string;
createdAt: string; // ISO 8601
startedAt?: string;
completedAt?: string;
}
// ---- 存储 ----
export interface CreateTaskOptions {
/** 显式幂等键;不传则由 type + params 计算 */
idempotencyKey?: string;
/** 跳过复用,强制新建任务(用户主动「重新生成」时用) */
force?: boolean;
/**
* 归属标记(lpt-be 传用户 id),结算时原样写进用量记录。
*
* 复用已有任务时**不会**覆盖原任务的标记:那次 LLM 调用只发生了一次,
* 账算在原调用方头上;复用方没有产生新的 token 消耗。
*/
callerRef?: string;
}
const records = new Map<string, TaskRecord>();
const queue: TaskRecord[] = [];
let processing = false;
export interface CreateTaskResult {
taskId: string;
/** true 表示复用了已有任务,调用方不应按「新任务」处理 */
reused: boolean;
/** 复用的任务当前状态,便于调用方决定返回 200 还是 201 */
status: TaskStatus;
}
// ---- 公开 API ----
export interface QueueConfig {
/** 并发处理的任务数 */
concurrency: number;
/** 单任务总尝试次数(含首次) */
maxAttempts: number;
retryBaseMs: number;
retryMaxMs: number;
/** 完成记录的保留时长 */
ttlMs: number;
cleanupIntervalMs: number;
/** 已完成结果可被复用的时间窗口 */
resultCacheMs: number;
}
export function createTask(type: TaskType, params: Record<string, unknown>): string {
const id = randomUUID();
const task: TaskRecord = {
id,
type,
params,
status: "pending",
createdAt: new Date().toISOString(),
function intFrom(value: string | undefined, fallback: number): number {
if (value === undefined || value.trim() === "") return fallback;
const parsed = Number(value);
return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
}
export function loadQueueConfig(env: NodeJS.ProcessEnv = process.env): QueueConfig {
return {
concurrency: intFrom(env.LPT_AI_CONCURRENCY, 2),
maxAttempts: intFrom(env.LPT_AI_MAX_ATTEMPTS, 3),
retryBaseMs: intFrom(env.LPT_AI_RETRY_BASE_MS, 1_000),
retryMaxMs: intFrom(env.LPT_AI_RETRY_MAX_MS, 20_000),
ttlMs: intFrom(env.LPT_AI_TTL_MS, 60 * 60 * 1000),
cleanupIntervalMs: intFrom(env.LPT_AI_CLEANUP_MS, 5 * 60 * 1000),
resultCacheMs: intFrom(env.LPT_AI_RESULT_CACHE_MS, 10 * 60 * 1000),
};
records.set(id, task);
queue.push(task);
setImmediate(() => tryProcessNext());
return id;
}
export function getTask(id: string): TaskRecord | undefined {
const t = records.get(id);
if (!t) return undefined;
// 返回浅拷贝,防止外部修改
return { ...t };
/** 任务执行器:给定任务与参数返回结果,失败时抛出 */
export type TaskRunner = (
task: TaskRecord,
context: { attempt: number; messages: ChatMessage[]; config: ReturnType<typeof loadConfig> },
) => Promise<unknown>;
export interface TaskQueueDeps {
config?: QueueConfig;
/** 执行单次 LLM 调用;默认走 chat() */
runOnce?: TaskRunner;
/** 任务最终结束(成功或失败)时的回调,默认写管理面板日志 */
onSettled?: (task: TaskRecord) => void;
/** 是否可用 LLM;默认看 API Key 是否配置。注入以便测试 */
isLlmAvailable?: (config: ReturnType<typeof loadConfig>) => boolean;
sleep?: (ms: number) => Promise<void>;
random?: () => number;
now?: () => number;
/** 是否启用定时清理,测试里通常关掉 */
enableCleanup?: boolean;
}
// ---- 后台 Worker ----
// ---- 幂等键 ----
async function tryProcessNext(): Promise<void> {
if (processing || queue.length === 0) return;
processing = true;
/**
* 稳定序列化:键名排序后再序列化,避免对象键顺序不同导致同一输入算出不同键。
*/
function stableStringify(value: unknown): string {
if (value === null || typeof value !== "object") {
return JSON.stringify(value) ?? "null";
}
if (Array.isArray(value)) {
return `[${value.map(stableStringify).join(",")}]`;
}
const entries = Object.entries(value as Record<string, unknown>)
.filter(([, v]) => v !== undefined)
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
}
const task = queue.shift()!;
export function computeTaskKey(type: TaskType, params: Record<string, unknown>): string {
const payload = stableStringify({ type, params });
return createHash("sha256").update(payload).digest("hex").slice(0, 32);
}
try {
// ---- 队列 ----
export class TaskQueue {
private readonly config: QueueConfig;
private readonly deps: TaskQueueDeps;
private readonly records = new Map<string, TaskRecord>();
/** 幂等键 → 任务 id */
private readonly keyIndex = new Map<string, string>();
private readonly queue: string[] = [];
private running = 0;
private cleanupTimer: NodeJS.Timeout | null = null;
private readonly idleWaiters: Array<() => void> = [];
constructor(deps: TaskQueueDeps = {}) {
this.deps = deps;
this.config = deps.config ?? loadQueueConfig();
if (deps.enableCleanup ?? true) {
this.cleanupTimer = setInterval(() => this.cleanup(), this.config.cleanupIntervalMs);
// 不要因为清理定时器让进程无法退出
this.cleanupTimer.unref?.();
}
}
private now(): number {
return this.deps.now ? this.deps.now() : Date.now();
}
private sleep(ms: number): Promise<void> {
if (this.deps.sleep) return this.deps.sleep(ms);
return new Promise((resolve) => {
setTimeout(resolve, ms);
});
}
/**
* 提交任务。
*
* 复用规则:
* - 同键任务处于 pending/running → 直接复用(合并重复请求,不重复计费)
* - 同键任务已完成且在 resultCacheMs 窗口内 → 复用结果
* - 同键任务已失败 → 新建(失败不该被缓存)
* - force=true → 一律新建
*/
create(
type: TaskType,
params: Record<string, unknown>,
options: CreateTaskOptions = {},
): CreateTaskResult {
const key = options.idempotencyKey?.trim() || computeTaskKey(type, params);
if (!options.force) {
const existingId = this.keyIndex.get(key);
const existing = existingId ? this.records.get(existingId) : undefined;
if (existing && this.isReusable(existing)) {
return { taskId: existing.id, reused: true, status: existing.status };
}
}
const id = randomUUID();
const task: TaskRecord = {
id,
key,
type,
params,
status: "pending",
attempts: 0,
createdAt: new Date(this.now()).toISOString(),
...(options.callerRef ? { callerRef: options.callerRef } : {}),
};
this.records.set(id, task);
this.keyIndex.set(key, id);
this.queue.push(id);
setImmediate(() => this.pump());
return { taskId: id, reused: false, status: "pending" };
}
private isReusable(task: TaskRecord): boolean {
if (task.status === "pending" || task.status === "running") {
return true;
}
if (task.status !== "done") {
// 失败的任务不进入复用,否则用户拿不到重试机会
return false;
}
if (!task.completedAt) return false;
return this.now() - Date.parse(task.completedAt) <= this.config.resultCacheMs;
}
get(id: string): TaskRecord | undefined {
const task = this.records.get(id);
return task ? { ...task } : undefined;
}
/** 待处理 + 处理中的任务数,便于观测与测试 */
get pendingCount(): number {
return this.queue.length + this.running;
}
/** 当前并发度 */
get concurrency(): number {
return this.config.concurrency;
}
/**
* 等待队列跑空。仅用于测试与静态工具场景,生产不应阻塞请求。
*/
drain(): Promise<void> {
if (this.pendingCount === 0) {
return Promise.resolve();
}
return new Promise((resolve) => {
this.idleWaiters.push(resolve);
});
}
stop(): void {
if (this.cleanupTimer) {
clearInterval(this.cleanupTimer);
this.cleanupTimer = null;
}
}
// ---- Worker 池 ----
/** 在并发额度允许的范围内尽量多启动 Worker */
private pump(): void {
while (this.running < this.config.concurrency && this.queue.length > 0) {
const id = this.queue.shift();
if (!id) break;
const task = this.records.get(id);
if (!task) continue;
this.running += 1;
void this.runTask(task).finally(() => {
this.running -= 1;
this.pump();
this.notifyIfIdle();
});
}
this.notifyIfIdle();
}
private notifyIfIdle(): void {
if (this.pendingCount > 0) return;
const waiters = this.idleWaiters.splice(0, this.idleWaiters.length);
for (const resolve of waiters) resolve();
}
private async runTask(task: TaskRecord): Promise<void> {
task.status = "running";
task.startedAt = new Date().toISOString();
task.startedAt = new Date(this.now()).toISOString();
const config = loadConfig();
if (!isAvailable(config)) {
throw new LlmError("LLM API Key 未配置", 503);
const available = this.deps.isLlmAvailable
? this.deps.isLlmAvailable(config)
: isAvailable(config);
if (!available) {
task.status = "failed";
task.error = "LLM API Key 未配置";
task.completedAt = new Date(this.now()).toISOString();
task.usage = emptyUsage();
task.usageSource = "missing";
this.settle(task);
return;
}
const messages = buildMessages(task);
let callOptions: { temperature?: number; maxTokens?: number } | undefined;
if (task.type === "compare-recall") {
callOptions = { temperature: 0.2, maxTokens: 4096 };
} else if (task.type === "generate-mind-map") {
callOptions = { temperature: 0.3, maxTokens: 4096 };
} else {
callOptions = { temperature: 0.3, maxTokens: 2048 };
const callOptions = callOptionsFor(task.type, messages);
const retryOptions: RetryOptions = {
maxAttempts: this.config.maxAttempts,
baseDelayMs: this.config.retryBaseMs,
maxDelayMs: this.config.retryMaxMs,
isRetryable: isRetryableLlmError,
sleep: (ms) => this.sleep(ms),
...(this.deps.random ? { random: this.deps.random } : {}),
onRetry: () => {
task.attempts += 1;
},
};
// 每次尝试的用量都要留下:重试 N 次就是 N 次计费,失败尝试也可能已经产生了 token
const attemptUsages: TokenUsage[] = [];
const attemptSources: UsageSource[] = [];
try {
const runOnce =
this.deps.runOnce ??
(async (t, ctx) => {
try {
const result = await chat(ctx.config, ctx.messages, callOptions);
attemptUsages.push(result.usage);
attemptSources.push(result.usageSource);
return parseResult(t.type, result.content, result.model);
} catch (err) {
// 上游返回 200 但内容为空这类失败已经计费,用量挂在 LlmError 上带回来
if (err instanceof LlmError && err.usage) {
attemptUsages.push(err.usage);
attemptSources.push("upstream");
} else {
attemptUsages.push(emptyUsage());
attemptSources.push("missing");
}
throw err;
}
});
const result = await withRetry(
() => runOnce(task, { attempt: task.attempts + 1, messages, config }),
retryOptions,
);
task.attempts += 1;
task.status = "done";
task.result = result;
task.completedAt = new Date(this.now()).toISOString();
} catch (err: unknown) {
task.attempts += 1;
task.status = "failed";
task.error = err instanceof Error ? err.message : String(err);
task.errorCode = classifyLlmError(err);
task.completedAt = new Date(this.now()).toISOString();
} finally {
task.usage = accumulateUsage(attemptUsages);
task.usageSource = combineSource(attemptSources);
this.settle(task, config);
}
}
const raw = await chat(config, messages, callOptions);
let result: unknown;
if (task.type === "aggregate-report") {
result = { report: raw.trim(), model: config.model };
} else if (task.type === "generate-mind-map") {
result = { outline: raw.trim(), model: config.model };
} else {
// compare-recall: 清理可能的 ```json 包裹
const clean = raw.trim().replace(/^```(?:json)?\s*/, "").replace(/\s*```$/, "");
result = JSON.parse(clean);
private settle(task: TaskRecord, config = loadConfig()): void {
if (this.deps.onSettled) {
this.deps.onSettled(task);
return;
}
task.status = "done";
task.result = result;
task.completedAt = new Date().toISOString();
// 记录到管理面板日志
const durationMs =
task.startedAt && task.completedAt
? Date.parse(task.completedAt) - Date.parse(task.startedAt)
: 0;
const usage = task.usage ?? emptyUsage();
// 计价在结算时冻结:价格表会变,历史账不能被新价格改写。
// 重试跨越峰谷分界时整单按结算时刻计价,偏差上限是一个任务的执行时长。
const priced = priceUsage(usage, new Date(this.now()), loadPricingConfig());
logStore.add({
timestamp: new Date().toISOString(),
timestamp: new Date(this.now()).toISOString(),
endpoint: `/ai/tasks#${task.type}`,
taskType: task.type,
taskId: task.id,
...(task.callerRef ? { callerRef: task.callerRef } : {}),
model: config.model,
durationMs: task.startedAt ? Date.parse(task.completedAt) - Date.parse(task.startedAt) : 0,
status: 200,
attempts: task.attempts,
isLlmCall: true,
usage,
usageSource: task.usageSource ?? "missing",
costUsd: priced.costUsd,
pricing: priced.snapshot,
durationMs,
status: task.status === "done" ? 200 : 500,
requestBody: task.params,
responseBody: result,
messages,
params: callOptions,
responseBody: task.status === "done" ? (task.result ?? {}) : {},
...(task.error ? { error: task.error } : {}),
...(task.errorCode ? { errorCode: task.errorCode } : {}),
});
}
} catch (err: unknown) {
const errMsg = err instanceof Error ? err.message : String(err);
task.status = "failed";
task.error = errMsg;
task.completedAt = new Date().toISOString();
// ---- 清理 ----
const config = loadConfig();
logStore.add({
timestamp: new Date().toISOString(),
endpoint: `/ai/tasks#${task.type}`,
model: config.model,
durationMs: task.startedAt ? Date.parse(task.completedAt) - Date.parse(task.startedAt) : 0,
status: err instanceof LlmError ? err.statusCode : 500,
requestBody: task.params,
responseBody: {},
error: errMsg,
});
} finally {
processing = false;
// 处理下一个任务
if (queue.length > 0) {
setImmediate(() => tryProcessNext());
/** 移除过期的完成记录与对应幂等索引;返回移除条数便于测试 */
cleanup(): number {
const cutoff = this.now() - this.config.ttlMs;
let removed = 0;
for (const [id, task] of this.records) {
if (task.status !== "done" && task.status !== "failed") continue;
const completed = task.completedAt ? Date.parse(task.completedAt) : 0;
if (completed > 0 && completed < cutoff) {
this.records.delete(id);
// 索引只在该键仍指向这条记录时才删,避免误删后续新任务的索引
if (this.keyIndex.get(task.key) === id) {
this.keyIndex.delete(task.key);
}
removed += 1;
}
}
return removed;
}
/** 供测试断言内部状态 */
size(): number {
return this.records.size;
}
}
// ---- Prompt 构建 ----
// ---- 失败分类 ----
function buildMessages(task: TaskRecord) {
/**
* 把失败原因归成可聚合的短分类。
*
* 面板要能回答「这个月有多少次是被限流打掉的」;把整句错误文案当分类是聚合不起来的。
* 上游原文仍然留在 `error` 字段里,分类只用于分组统计。
*/
export function classifyLlmError(error: unknown): string {
if (!(error instanceof LlmError)) return "unknown";
if (error.message.includes("API Key 未配置")) return "not_configured";
switch (error.statusCode) {
case 408:
case 504:
return "timeout";
case 429:
return "rate_limited";
case 402:
return "insufficient_balance";
case 401:
case 403:
return "auth_failed";
case 400:
case 404:
case 422:
return "bad_request";
default:
return error.statusCode >= 500 ? "upstream_error" : "unknown";
}
}
// ---- 结果解析与 Prompt ----
function baseCallOptions(type: TaskType): ChatOptions {
if (type === "compare-recall") return { temperature: 0.2, maxTokens: 4096 };
if (type === "generate-mind-map") return { temperature: 0.3, maxTokens: 4096 };
if (type === "guidance") return { temperature: 0.7, maxTokens: 1024 };
return { temperature: 0.3, maxTokens: 2048 };
}
/**
* 单次调用参数:温度与输出上限按任务类型固定,思考强度按 prompt 总长度自适应。
*
* 短输入(几句碎片、单轮引导)直接 `none` 关掉思考,不再跟随供应商的默认 `high`,
* 避免为一点点内容付满档思考的额度与延迟;阈值全部走 `LPT_AI_REASONING_*`。
*/
export function callOptionsFor(
type: TaskType,
messages: ChatMessage[],
thinking: ThinkingConfig = loadThinkingConfig(),
): ChatOptions {
const base = baseCallOptions(type);
if (!thinking.enabled) return base;
return { ...base, reasoningEffort: reasoningEffortFor(promptLength(messages), thinking) };
}
/** 把模型原文转成结构化结果 */
/**
* 解析结构化的报告草稿。
*
* 报告是结构化的(会话摘要 / 预期达成判断 / 自由总结),但 LLM 不一定老实返回 JSON:
* 这里对「带代码块围栏」「返回了纯文本」两种情况都做降级,把整段文本当作自由总结,
* 保证用户至少拿到一份可编辑的草稿,而不是一个报错。
*/
export function parseReportDraft(raw: string, model = ""): {
sessionSummary: string;
expectationVerdict: string;
freeSummary: string;
model: string;
} {
const text = raw.trim();
const jsonText = text.replace(/^```(?:json)?\s*/, "").replace(/\s*```$/, "");
try {
const parsed = JSON.parse(jsonText) as Record<string, unknown>;
const pick = (key: string): string => {
const value = parsed[key];
return typeof value === "string" ? value : "";
};
const draft = {
sessionSummary: pick("sessionSummary"),
expectationVerdict: pick("expectationVerdict"),
freeSummary: pick("freeSummary"),
model,
};
if (draft.sessionSummary || draft.expectationVerdict || draft.freeSummary) {
return draft;
}
} catch {
// 不是 JSON:按纯文本降级处理
}
return { sessionSummary: "", expectationVerdict: "", freeSummary: text, model };
}
export function parseResult(type: TaskType, raw: string, model = ""): unknown {
const text = raw.trim();
if (type === "aggregate-report") {
return parseReportDraft(text, model);
}
if (type === "generate-mind-map") {
return { outline: text, model };
}
if (type === "guidance") {
return { reply: text, model };
}
const clean = text.replace(/^```(?:json)?\s*/, "").replace(/\s*```$/, "");
return JSON.parse(clean);
}
export function buildMessages(task: TaskRecord): ChatMessage[] {
const p = task.params;
switch (task.type) {
case "aggregate-report": {
@@ -159,13 +572,20 @@ function buildMessages(task: TaskRecord) {
);
}
case "generate-mind-map": {
const reports = p.reports as string[] | undefined;
// 素材为「该任务名下的知识碎片」(按内容归属取),并携带同源会话的报告作为参考(报告-02)
const fragments = (p.fragments as Array<string | MindMapFragmentInput> | undefined) ?? [];
const reports = (p.reports as MindMapReportInput[] | undefined) ?? [];
return generateMindMapPrompt(
p.taskName as string,
(p.taskDescription as string) ?? "",
reports ?? [],
fragments,
reports,
);
}
case "guidance": {
const history = (p.history as ChatMessage[] | undefined) ?? [];
return guidancePrompt(p.taskName as string, p.concept as string, history);
}
case "compare-recall": {
return compareRecallPrompt(
p.taskName as string,
@@ -176,19 +596,20 @@ function buildMessages(task: TaskRecord) {
}
}
// ---- TTL 清理 ----
// ---- 生产单例 ----
const TTL_MS = 60 * 60 * 1000; // 1 小时
const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 分钟
export const taskQueue = new TaskQueue();
setInterval(() => {
const cutoff = Date.now() - TTL_MS;
for (const [id, task] of records) {
if (task.status === "done" || task.status === "failed") {
const completed = task.completedAt ? Date.parse(task.completedAt) : 0;
if (completed > 0 && completed < cutoff) {
records.delete(id);
}
}
}
}, CLEANUP_INTERVAL_MS);
export function createTask(
type: TaskType,
params: Record<string, unknown>,
options: CreateTaskOptions = {},
): CreateTaskResult {
return taskQueue.create(type, params, options);
}
export function getTask(id: string): TaskRecord | undefined {
return taskQueue.get(id);
}
export { LlmError };
+156
View File
@@ -0,0 +1,156 @@
import { afterEach, describe, expect, it } from "vitest";
import { checkToken, configuredToken, providedToken, queryTokenMatches, readCookie, TOKEN_COOKIE, TOKEN_HEADER } from "./auth.js";
/** 极简 reply 替身:记录是否写出 401 */
const makeReply = () => {
const calls: number[] = [];
return {
calls,
status(code: number) {
calls.push(code);
return { send: (body: unknown) => body };
},
};
};
const original = process.env.LPT_AI_TOKEN;
afterEach(() => {
if (original === undefined) {
delete process.env.LPT_AI_TOKEN;
} else {
process.env.LPT_AI_TOKEN = original;
}
});
describe("AI 入站令牌", () => {
it("未配置令牌时放行,保持开发环境零摩擦", () => {
delete process.env.LPT_AI_TOKEN;
expect(configuredToken()).toBe("");
const reply = makeReply();
expect(checkToken({ headers: {} }, reply)).toBe(true);
expect(reply.calls).toEqual([]);
});
it("配置令牌后,缺令牌的请求被拒绝", () => {
process.env.LPT_AI_TOKEN = "secret-token";
const reply = makeReply();
expect(checkToken({ headers: {} }, reply)).toBe(false);
expect(reply.calls).toEqual([401]);
});
it("配置令牌后,header 提供正确令牌放行", () => {
process.env.LPT_AI_TOKEN = "secret-token";
const reply = makeReply();
expect(checkToken({ headers: { [TOKEN_HEADER]: "secret-token" } }, reply)).toBe(true);
expect(reply.calls).toEqual([]);
});
it("支持用 query 传令牌(便于在浏览器里打开 /admin)", () => {
process.env.LPT_AI_TOKEN = "secret-token";
const reply = makeReply();
expect(checkToken({ headers: {}, query: { token: "secret-token" } }, reply)).toBe(true);
});
it("令牌错误被拒绝", () => {
process.env.LPT_AI_TOKEN = "secret-token";
const reply = makeReply();
expect(checkToken({ headers: { [TOKEN_HEADER]: "wrong" } }, reply)).toBe(false);
expect(reply.calls).toEqual([401]);
});
it("空白令牌视为未配置", () => {
process.env.LPT_AI_TOKEN = " ";
expect(configuredToken()).toBe("");
expect(checkToken({ headers: {} }, makeReply())).toBe(true);
});
it("支持 cookie 传令牌:面板 HTML 与它后续的 fetch 是两个独立请求", () => {
process.env.LPT_AI_TOKEN = "secret-token";
const reply = makeReply();
expect(
checkToken({ headers: { cookie: `${TOKEN_COOKIE}=secret-token` } }, reply),
).toBe(true);
expect(reply.calls).toEqual([]);
});
it("cookie 与其它 cookie 混在一起时仍能取出令牌", () => {
process.env.LPT_AI_TOKEN = "secret-token";
const reply = makeReply();
expect(
checkToken(
{ headers: { cookie: `a=1; ${TOKEN_COOKIE}=secret-token; b=2` } },
reply,
),
).toBe(true);
});
it("header 优先于 cookie,避免旧 cookie 把新令牌挡在门外", () => {
process.env.LPT_AI_TOKEN = "new-token";
const reply = makeReply();
expect(
checkToken(
{ headers: { [TOKEN_HEADER]: "new-token", cookie: `${TOKEN_COOKIE}=old-token` } },
reply,
),
).toBe(true);
});
});
describe("readCookie", () => {
it("取出 URL 编码的值", () => {
expect(readCookie("t=a%20b", "t")).toBe("a b");
});
it("编码非法时退回原值,不抛异常", () => {
expect(readCookie("t=%E0%A4%A", "t")).toBe("%E0%A4%A");
});
it("缺失时返回 undefined", () => {
expect(readCookie(undefined, "t")).toBeUndefined();
expect(readCookie("a=1", "t")).toBeUndefined();
expect(readCookie("novalue", "t")).toBeUndefined();
});
});
describe("providedToken", () => {
it("按 header → query → cookie 的优先级取值", () => {
process.env.LPT_AI_TOKEN = "secret-token";
expect(
providedToken({
headers: { [TOKEN_HEADER]: "from-header", cookie: `${TOKEN_COOKIE}=from-cookie` },
query: { token: "from-query" },
}),
).toBe("from-header");
expect(
providedToken({ headers: {}, query: { token: "from-query" } }),
).toBe("from-query");
expect(
providedToken({ headers: { cookie: `${TOKEN_COOKIE}=from-cookie` } }),
).toBe("from-cookie");
expect(providedToken({ headers: {} })).toBe("");
});
});
describe("queryTokenMatches", () => {
it("仅在 query 令牌正确时返回 true,用于决定要不要下发 cookie", () => {
process.env.LPT_AI_TOKEN = "secret-token";
expect(queryTokenMatches({ query: { token: "secret-token" } })).toBe(true);
expect(queryTokenMatches({ query: { token: "wrong" } })).toBe(false);
expect(queryTokenMatches({})).toBe(false);
});
it("未配置令牌时不下发 cookie", () => {
delete process.env.LPT_AI_TOKEN;
expect(queryTokenMatches({ query: { token: "" } })).toBe(false);
});
});
+86
View File
@@ -0,0 +1,86 @@
/**
* 入站访问令牌(安全-03)。
*
* 设计取舍:令牌是**可选**的。
* - 设置 `LPT_AI_TOKEN` 后,`/ai/*` 与 `/admin` 都要求携带令牌;
* - 未设置时保持可访问,并在启动日志里明确告知,避免开发阶段被迫维护额外凭据。
*
* 令牌来源按优先级:header `x-api-token` → query `token` → cookie `lpt_ai_token`。
* cookie 这一路是给 `/admin` 面板用的:面板 HTML 与它后续的 `fetch` 是两个独立请求,
* 只在 URL 上带令牌的话,HTML 能打开、里面的 fetch 全是 401(面板永远空白);
* 用 `?token=` 首次访问时换发一个 HttpOnly cookie,后续请求浏览器会自动带上。
*
* 生产环境只需往 `lpt-secrets` 里加一个 key 即可收紧(部署清单已用 `optional: true` 引用,
* 不设置也不会导致 Pod 起不来)。
*/
export const TOKEN_HEADER = "x-api-token";
export const TOKEN_COOKIE = "lpt_ai_token";
/** 当前配置的令牌;空字符串表示未启用 */
export function configuredToken(): string {
return (process.env.LPT_AI_TOKEN ?? "").trim();
}
interface TokenRequest {
headers: Record<string, unknown>;
query?: unknown;
}
/** 极简 cookie 解析:只取需要的那个键,不引入额外依赖 */
export function readCookie(cookieHeader: unknown, name: string): string | undefined {
if (typeof cookieHeader !== "string" || cookieHeader.length === 0) return undefined;
for (const part of cookieHeader.split(";")) {
const separator = part.indexOf("=");
if (separator === -1) continue;
if (part.slice(0, separator).trim() !== name) continue;
const raw = part.slice(separator + 1).trim();
try {
return decodeURIComponent(raw);
} catch {
// 编码非法时退回原值,宁可让校验失败也不要抛异常
return raw;
}
}
return undefined;
}
/** 从请求里取出调用方提供的令牌;取不到时返回空串 */
export function providedToken(request: TokenRequest): string {
const header = request.headers[TOKEN_HEADER];
if (typeof header === "string" && header.length > 0) return header;
const query = request.query as { token?: string } | undefined;
if (typeof query?.token === "string" && query.token.length > 0) return query.token;
return readCookie(request.headers["cookie"], TOKEN_COOKIE) ?? "";
}
/**
* 校验请求是否携带了正确的令牌。
*
* @returns true 表示放行;false 表示已写出 401 响应,调用方应直接结束处理
*/
export function checkToken(
request: TokenRequest,
reply: { status: (code: number) => { send: (body: unknown) => unknown } },
): boolean {
const token = configuredToken();
if (!token) return true;
if (providedToken(request) === token) return true;
reply.status(401).send({ error: "未授权" });
return false;
}
/**
* 判断请求是否用 query 提供了正确的令牌。
*
* `/admin` 据此决定要不要下发 cookie:只在真正用 `?token=` 打开面板时才种,
* 避免把令牌写进每个响应头。
*/
export function queryTokenMatches(request: { query?: unknown }): boolean {
const token = configuredToken();
if (!token) return false;
const query = request.query as { token?: string } | undefined;
return query?.token === token;
}
+68
View File
@@ -0,0 +1,68 @@
import { describe, expect, it } from "vitest";
import { RateLimiter, intFromEnv } from "./rate-limit.js";
describe("RateLimiter", () => {
it("窗口内放行到上限,超出后拒绝并给出等待时间", () => {
const limiter = new RateLimiter({ limit: 3, windowMs: 1000 });
const t0 = 1_000_000;
expect(limiter.check("a", t0).allowed).toBe(true);
expect(limiter.check("a", t0 + 10).allowed).toBe(true);
expect(limiter.check("a", t0 + 20).allowed).toBe(true);
const blocked = limiter.check("a", t0 + 30);
expect(blocked.allowed).toBe(false);
expect(blocked.retryAfterMs).toBeGreaterThan(0);
expect(blocked.retryAfterMs).toBeLessThanOrEqual(1000);
});
it("窗口滑过之后重新放行", () => {
const limiter = new RateLimiter({ limit: 1, windowMs: 1000 });
const t0 = 1_000_000;
expect(limiter.check("a", t0).allowed).toBe(true);
expect(limiter.check("a", t0 + 500).allowed).toBe(false);
expect(limiter.check("a", t0 + 1001).allowed).toBe(true);
});
it("不同来源互不影响", () => {
const limiter = new RateLimiter({ limit: 1, windowMs: 1000 });
const t0 = 1_000_000;
expect(limiter.check("a", t0).allowed).toBe(true);
expect(limiter.check("b", t0).allowed).toBe(true);
expect(limiter.check("a", t0).allowed).toBe(false);
});
it("清理过期来源,避免 Map 无界增长", () => {
const limiter = new RateLimiter({ limit: 1, windowMs: 1000 });
const t0 = 1_000_000;
limiter.check("a", t0);
limiter.check("b", t0);
// 跨过多个窗口后再访问,触发清理
limiter.check("c", t0 + 5000);
const internal = limiter as unknown as { hits: Map<string, number[]> };
expect(internal.hits.has("a")).toBe(false);
expect(internal.hits.has("b")).toBe(false);
expect(internal.hits.has("c")).toBe(true);
});
});
describe("intFromEnv", () => {
it("读取正整数,非法值回退默认", () => {
process.env.TEST_INT_ENV = "42";
expect(intFromEnv("TEST_INT_ENV", 7)).toBe(42);
process.env.TEST_INT_ENV = "abc";
expect(intFromEnv("TEST_INT_ENV", 7)).toBe(7);
process.env.TEST_INT_ENV = "-1";
expect(intFromEnv("TEST_INT_ENV", 7)).toBe(7);
delete process.env.TEST_INT_ENV;
expect(intFromEnv("TEST_INT_ENV", 7)).toBe(7);
});
});
+68
View File
@@ -0,0 +1,68 @@
/**
* 进程内限流(安全-03)。
*
* 目的:`/ai/tasks` 每次调用都会消耗 LLM 额度,需要防止误用刷爆。
* 不引入额外依赖,按「每窗口每来源」计数即可。
*
* 注意:这是单进程内存计数。多副本部署时每个副本各算一份,属于粗粒度保护,
* 不是精确配额;真要做精确配额需要放到共享存储(当前不需要)。
*/
export interface RateLimitOptions {
/** 窗口内允许的请求数 */
limit: number;
/** 窗口长度(毫秒) */
windowMs: number;
}
export interface RateLimitDecision {
allowed: boolean;
/** 建议告诉调用方还要等多久(毫秒) */
retryAfterMs: number;
}
export class RateLimiter {
private readonly hits = new Map<string, number[]>();
private lastSweep = 0;
constructor(private readonly options: RateLimitOptions) {}
/** 记一次命中并返回是否放行 */
check(key: string, now = Date.now()): RateLimitDecision {
this.sweep(now);
const windowStart = now - this.options.windowMs;
const recent = (this.hits.get(key) ?? []).filter((at) => at > windowStart);
if (recent.length >= this.options.limit) {
this.hits.set(key, recent);
const oldest = recent[0];
return { allowed: false, retryAfterMs: Math.max(0, oldest + this.options.windowMs - now) };
}
recent.push(now);
this.hits.set(key, recent);
return { allowed: true, retryAfterMs: 0 };
}
/** 清理过期的 key,避免长期运行后 Map 无界增长 */
private sweep(now: number): void {
if (now - this.lastSweep < this.options.windowMs) return;
this.lastSweep = now;
const windowStart = now - this.options.windowMs;
for (const [key, times] of this.hits) {
const recent = times.filter((at) => at > windowStart);
if (recent.length === 0) {
this.hits.delete(key);
} else {
this.hits.set(key, recent);
}
}
}
}
/** 从环境变量读一个正整数,非法时返回默认值 */
export function intFromEnv(name: string, fallback: number): number {
const raw = process.env[name];
if (!raw) return fallback;
const value = Number(raw);
return Number.isInteger(value) && value > 0 ? value : fallback;
}
+103
View File
@@ -0,0 +1,103 @@
import { describe, expect, it } from "vitest";
import { isBlockedAddress, UnsafeUrlError, assertSafeUrl } from "./ssrf-guard.js";
describe("isBlockedAddress — IPv4", () => {
it("拦下私网、回环、链路本地(含云元数据)与保留段", () => {
const blocked = [
"127.0.0.1",
"127.255.255.254",
"10.0.0.1",
"10.255.255.255",
"172.16.0.1",
"172.31.255.255",
"192.168.1.1",
"169.254.169.254", // 云元数据
"0.0.0.0",
"100.64.0.1", // CGNAT
"224.0.0.1", // 组播
"255.255.255.255",
];
for (const ip of blocked) {
expect(isBlockedAddress(ip), ip).toBe(true);
}
});
it("放行公网地址", () => {
const allowed = ["8.8.8.8", "1.1.1.1", "100.63.255.255", "172.32.0.1", "192.169.0.1", "223.255.255.255"];
for (const ip of allowed) {
expect(isBlockedAddress(ip), ip).toBe(false);
}
});
it("非法 IPv4 字面量按不安全处理", () => {
expect(isBlockedAddress("999.1.1.1")).toBe(true);
expect(isBlockedAddress("1.2.3")).toBe(true);
expect(isBlockedAddress("")).toBe(true);
});
});
describe("isBlockedAddress — IPv6", () => {
it("拦下回环、未指定、ULA、链路本地与组播", () => {
const blocked = ["::1", "::", "fc00::1", "fd12:3456::1", "fe80::1", "ff02::1", "fe80::1%eth0"];
for (const ip of blocked) {
expect(isBlockedAddress(ip), ip).toBe(true);
}
});
it("识别 IPv4-mapped 内嵌的私网地址(绕过尝试)", () => {
expect(isBlockedAddress("::ffff:127.0.0.1")).toBe(true);
expect(isBlockedAddress("::ffff:169.254.169.254")).toBe(true);
expect(isBlockedAddress("::ffff:8.8.8.8")).toBe(false);
});
it("识别 NAT64 内嵌的私网地址", () => {
expect(isBlockedAddress("64:ff9b::7f00:1")).toBe(true); // 内嵌 127.0.0.1
expect(isBlockedAddress("64:ff9b::808:808")).toBe(false); // 内嵌 8.8.8.8
});
it("放行公网 IPv6", () => {
expect(isBlockedAddress("2001:4860:4860::8888")).toBe(false);
});
});
describe("assertSafeUrl", () => {
it("只允许 http/https", async () => {
await expect(assertSafeUrl("file:///etc/passwd")).rejects.toBeInstanceOf(UnsafeUrlError);
await expect(assertSafeUrl("ftp://example.com")).rejects.toBeInstanceOf(UnsafeUrlError);
await expect(assertSafeUrl("gopher://example.com")).rejects.toBeInstanceOf(UnsafeUrlError);
});
it("拒绝无效 URL", async () => {
await expect(assertSafeUrl("not a url")).rejects.toBeInstanceOf(UnsafeUrlError);
});
it("拒绝内网 IP 字面量,不经过 DNS", async () => {
await expect(assertSafeUrl("http://127.0.0.1:80/")).rejects.toBeInstanceOf(UnsafeUrlError);
await expect(assertSafeUrl("http://192.168.1.1/")).rejects.toBeInstanceOf(UnsafeUrlError);
await expect(assertSafeUrl("http://169.254.169.254/latest/meta-data/")).rejects.toBeInstanceOf(
UnsafeUrlError,
);
await expect(assertSafeUrl("http://[::1]/")).rejects.toBeInstanceOf(UnsafeUrlError);
});
it("拒绝非 http/https 默认端口的地址(避免探测内网服务)", async () => {
await expect(assertSafeUrl("http://8.8.8.8:6379/")).rejects.toBeInstanceOf(UnsafeUrlError);
await expect(assertSafeUrl("http://8.8.8.8:3306/")).rejects.toBeInstanceOf(UnsafeUrlError);
});
it("放行公网 http/https 字面量与默认端口", async () => {
await expect(assertSafeUrl("http://8.8.8.8/")).resolves.toBeInstanceOf(URL);
await expect(assertSafeUrl("https://8.8.8.8:443/")).resolves.toBeInstanceOf(URL);
});
it("域名解析失败时拒绝", async () => {
await expect(assertSafeUrl("https://this-domain-should-not-resolve.invalid/")).rejects.toBeInstanceOf(
UnsafeUrlError,
);
});
it("localhost 这类解析到回环的域名被拦下(防绕过字面量检查)", async () => {
await expect(assertSafeUrl("http://localhost:80/")).rejects.toBeInstanceOf(UnsafeUrlError);
});
});
+285
View File
@@ -0,0 +1,285 @@
/**
* SSRF 防护:校验「服务端主动抓取」的目标地址是否安全。
*
* 背景:`/fetch-title` 由服务端抓取调用方给的 URL。如果不做限制,调用方可以拿它探测
* 内网服务与云元数据地址(169.254.169.254),把本服务当成内网跳板。
*
* 防护分四层,缺一层都能绕过:
* 1. 协议只允许 http/https;
* 2. 端口只允许 http/https 默认端口(外加显式配置的额外端口),避免被用来探测 Redis/MySQL 等内网服务;
* 3. 解析域名后校验**每一个**解析结果,而不是只校验字面量(防 DNS 解析到内网、防 DNS rebinding);
* 4. 重定向逐跳校验,避免「首跳合法、次跳内网」。
*/
import { lookup } from "node:dns/promises";
/** 允许的协议 */
const ALLOWED_PROTOCOLS = new Set(["http:", "https:"]);
/** 默认允许的端口 */
const DEFAULT_ALLOWED_PORTS = new Set(["80", "443"]);
/** 响应体读取上限(字节):标题通常在头部,不必读完整个页面 */
export const MAX_RESPONSE_BYTES = 512 * 1024;
/** 最大重定向跳数 */
export const MAX_REDIRECTS = 3;
export class UnsafeUrlError extends Error {
constructor(message: string) {
super(message);
this.name = "UnsafeUrlError";
}
}
/** 解析额外允许的端口:环境变量 LPT_AI_FETCH_ALLOWED_PORTS,逗号分隔 */
function allowedPorts(): Set<string> {
const extra = (process.env.LPT_AI_FETCH_ALLOWED_PORTS ?? "")
.split(",")
.map((p) => p.trim())
.filter((p) => /^\d+$/.test(p));
return new Set([...DEFAULT_ALLOWED_PORTS, ...extra]);
}
/**
* 判断一个 IP 字面量是否属于「不可主动访问」的地址段。
*
* 覆盖 IPv4 私网/回环/链路本地(含云元数据 169.254.169.254)/CGNAT/组播/保留段,
* 以及 IPv6 回环、未指定、ULA、链路本地、组播,并识别 IPv4-mapped 与 NAT64 里内嵌的 IPv4。
*/
export function isBlockedAddress(address: string): boolean {
const ip = address.trim().toLowerCase();
if (!ip) return true;
// IPv6:去掉可能的 zone id(fe80::1%eth0)
const bare = ip.includes("%") ? ip.slice(0, ip.indexOf("%")) : ip;
if (bare.includes(":")) {
return isBlockedIpv6(bare);
}
return isBlockedIpv4(bare);
}
function isBlockedIpv4(ip: string): boolean {
const parts = ip.split(".");
if (parts.length !== 4) return true; // 不是合法 IPv4,按不安全处理
const octets = parts.map((p) => Number(p));
if (octets.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return true;
const [a, b] = octets;
if (a === 0) return true; // 0.0.0.0/8
if (a === 10) return true; // 10.0.0.0/8
if (a === 127) return true; // 回环
if (a === 169 && b === 254) return true; // 链路本地,含云元数据
if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12
if (a === 192 && b === 168) return true; // 192.168.0.0/16
if (a === 192 && b === 0) return true; // 192.0.0.0/24 与 192.0.2.0/24
if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT 100.64.0.0/10
if (a === 198 && (b === 18 || b === 19)) return true; // 基准测试 198.18.0.0/15
if (a === 198 && b === 51) return true; // TEST-NET-2
if (a === 203 && b === 0) return true; // TEST-NET-3
if (a >= 224) return true; // 组播与保留段
return false;
}
function isBlockedIpv6(ip: string): boolean {
// IPv4-mapped:::ffff:127.0.0.1 / ::ffff:7f00:1
const mapped = ip.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
if (mapped) return isBlockedIpv4(mapped[1]);
const groups = expandIpv6(ip);
if (!groups) return true; // 无法解析,按不安全处理
const first = groups[0];
if (groups.every((g) => g === 0)) return true; // :: 未指定
if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1) return true; // ::1 回环
if ((first & 0xfe00) === 0xfc00) return true; // fc00::/7 ULA
if ((first & 0xffc0) === 0xfe80) return true; // fe80::/10 链路本地
if ((first & 0xff00) === 0xff00) return true; // ff00::/8 组播
// NAT64 64:ff9b::/96:内嵌 IPv4,取最后两组
if (groups[0] === 0x0064 && groups[1] === 0xff9b) {
const embedded = [groups[6] >> 8, groups[6] & 0xff, groups[7] >> 8, groups[7] & 0xff].join(".");
return isBlockedIpv4(embedded);
}
return false;
}
/** 把 IPv6 文本展开成 8 组 16 位整数;无法解析返回 null */
function expandIpv6(ip: string): number[] | null {
let text = ip;
// 内嵌 IPv4(如 ::ffff:1.2.3.4)先转成两组十六进制
const embedded = text.match(/^(.*:)(\d+\.\d+\.\d+\.\d+)$/);
if (embedded) {
const octets = embedded[2].split(".").map((p) => Number(p));
if (octets.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return null;
const high = ((octets[0] << 8) | octets[1]).toString(16);
const low = ((octets[2] << 8) | octets[3]).toString(16);
text = `${embedded[1]}${high}:${low}`;
}
const halves = text.split("::");
if (halves.length > 2) return null;
const parseGroups = (part: string): number[] | null => {
if (!part) return [];
const items = part.split(":");
const result: number[] = [];
for (const item of items) {
if (!/^[0-9a-f]{1,4}$/.test(item)) return null;
result.push(parseInt(item, 16));
}
return result;
};
const head = parseGroups(halves[0]);
const tail = halves.length === 2 ? parseGroups(halves[1]) : [];
if (head === null || tail === null) return null;
if (halves.length === 1) {
return head.length === 8 ? head : null;
}
const fill = 8 - head.length - tail.length;
if (fill < 0) return null;
return [...head, ...new Array(fill).fill(0), ...tail];
}
/**
* 校验目标 URL 是否可以安全抓取。不通过时抛 {@link UnsafeUrlError}。
*
* @param rawUrl 调用方给的 URL
*/
export async function assertSafeUrl(rawUrl: string): Promise<URL> {
let url: URL;
try {
url = new URL(rawUrl);
} catch {
throw new UnsafeUrlError("无效的 URL");
}
if (!ALLOWED_PROTOCOLS.has(url.protocol)) {
throw new UnsafeUrlError("只支持抓取 http/https 链接");
}
const port = url.port || (url.protocol === "https:" ? "443" : "80");
if (!allowedPorts().has(port)) {
throw new UnsafeUrlError("这个链接的端口不在允许范围内");
}
// 字面量就是 IP 时直接判定,避免走了 DNS 分支
const host = url.hostname.replace(/^\[|\]$/g, "");
if (isIpLiteral(host)) {
if (isBlockedAddress(host)) {
throw new UnsafeUrlError("不能抓取内网或本机地址");
}
return url;
}
// 域名:解析后逐个校验,防止解析到内网或 DNS rebinding
let addresses: string[];
try {
const resolved = await lookup(host, { all: true });
addresses = resolved.map((item) => item.address);
} catch {
throw new UnsafeUrlError("无法解析这个链接的域名");
}
if (addresses.length === 0) {
throw new UnsafeUrlError("无法解析这个链接的域名");
}
if (addresses.some((address) => isBlockedAddress(address))) {
throw new UnsafeUrlError("不能抓取内网或本机地址");
}
return url;
}
function isIpLiteral(host: string): boolean {
if (/^\d+\.\d+\.\d+\.\d+$/.test(host)) return true;
return host.includes(":");
}
export interface SafeFetchResult {
/** 最终跳转到的地址 */
finalUrl: string;
/** 响应体(截断到上限) */
body: string;
}
/**
* 带上限与逐跳校验的抓取。
*
* @param rawUrl 目标地址
* @param timeoutMs 单次请求超时
*/
export async function safeFetchText(rawUrl: string, timeoutMs = 10_000): Promise<SafeFetchResult> {
let current = await assertSafeUrl(rawUrl);
for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
try {
const response = await fetch(current, {
signal: controller.signal,
// 自己处理重定向,才能逐跳校验
redirect: "manual",
headers: { accept: "text/html,application/xhtml+xml" },
});
if (isRedirect(response.status)) {
const location = response.headers.get("location");
if (!location) {
throw new UnsafeUrlError("重定向没有给出目标地址");
}
// 相对跳转按当前地址解析,然后重新走一遍完整校验
current = await assertSafeUrl(new URL(location, current).toString());
continue;
}
if (!response.ok) {
throw new UnsafeUrlError("目标地址没有正常返回内容");
}
const body = await readCapped(response);
return { finalUrl: current.toString(), body };
} finally {
clearTimeout(timer);
}
}
throw new UnsafeUrlError("跳转次数过多,已停止抓取");
}
function isRedirect(status: number): boolean {
return status === 301 || status === 302 || status === 303 || status === 307 || status === 308;
}
/**
* 读取响应体并截断:既防超大响应打爆内存,也避免为一个标题读完整个页面。
*/
async function readCapped(response: Response): Promise<string> {
const contentType = response.headers.get("content-type") ?? "";
if (contentType && !/text\/|xml|json/i.test(contentType)) {
throw new UnsafeUrlError("这个链接不是网页内容");
}
const body = response.body;
if (!body) return "";
const reader = body.getReader();
const chunks: Uint8Array[] = [];
let total = 0;
try {
for (;;) {
const { done, value } = await reader.read();
if (done) break;
if (!value) continue;
chunks.push(value);
total += value.byteLength;
if (total >= MAX_RESPONSE_BYTES) break;
}
} finally {
await reader.cancel().catch(() => undefined);
}
const buffer = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)));
const text = buffer.subarray(0, MAX_RESPONSE_BYTES).toString("utf-8");
return text;
}
+8
View File
@@ -0,0 +1,8 @@
{
"extends": "./tsconfig.json",
"compilerOptions": {
"noEmit": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}