Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
0d27ee84d9 | ||
|
|
1c8a846635 | ||
|
|
499e218072 | ||
|
|
4a667a5d91 | ||
|
|
0c0c5be299 | ||
|
|
4aff5c03fe | ||
|
|
935f4781a4 | ||
|
|
fd1193a66f | ||
|
|
09d16dfb98 | ||
|
|
a70625267d | ||
|
|
1e1b101a46 | ||
|
|
fb3c6f9933 | ||
|
|
e359e58ff2 | ||
|
|
1c3168277d | ||
|
|
f091fe691d | ||
|
|
bf56c2bd46 |
+76
-4
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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 未路由本服务)。
|
||||
@@ -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 的升级同步进行。
|
||||
@@ -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 });
|
||||
});
|
||||
});
|
||||
@@ -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
@@ -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";
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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 };
|
||||
}
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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();
|
||||
@@ -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
@@ -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,'&').replace(/</g,'<').replace(/>/g,'>').replace(/"/g,'"');
|
||||
}
|
||||
|
||||
/** 千位分隔;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);
|
||||
|
||||
@@ -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
@@ -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();
|
||||
}
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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,
|
||||
];
|
||||
}
|
||||
|
||||
@@ -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]);
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
@@ -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";
|
||||
}
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
@@ -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";
|
||||
}
|
||||
@@ -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
@@ -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 };
|
||||
}
|
||||
});
|
||||
|
||||
@@ -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
@@ -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 };
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
}
|
||||
@@ -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);
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"noEmit": true
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
Reference in New Issue
Block a user