feat: 采集 LLM token 用量并上报 lpt-be

- 客户端解析上游 usage(含 DeepSeek 缓存命中/未命中),跨重试累加
- 新增计价表(三档单价 + 峰谷时段),费用在结算时冻结
- 新增用量上报与本地 outbox 重试;4xx 判定为确定性拒绝,不无限重试
- 面板补充 Token/费用/调用次数与计价快照
- 顺带修复面板内联脚本转义错误(模板字面量吃掉 \n 与 \',面板一直空白)
This commit is contained in:
2026-10-10 18:46:01 +08:00
parent fd1193a66f
commit 935f4781a4
24 changed files with 2632 additions and 65 deletions
+117
View File
@@ -0,0 +1,117 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { deriveBalanceUrl, fetchUpstreamBalance, loadBalanceConfig } from "./balance.js";
const originalKey = process.env.LLM_API_KEY;
const originalUrl = process.env.LLM_API_URL;
const originalBalanceUrl = process.env.LLM_BALANCE_URL;
afterEach(() => {
for (const [key, value] of [
["LLM_API_KEY", originalKey],
["LLM_API_URL", originalUrl],
["LLM_BALANCE_URL", originalBalanceUrl],
] as const) {
if (value === undefined) {
delete process.env[key];
} else {
process.env[key] = value;
}
}
});
describe("deriveBalanceUrl", () => {
it("从 chat completions 地址推导出同源余额地址", () => {
expect(deriveBalanceUrl("https://api.deepseek.com/v1/chat/completions")).toBe(
"https://api.deepseek.com/user/balance",
);
});
it("地址非法时返回空串,由调用方判定为不可用", () => {
expect(deriveBalanceUrl("not-a-url")).toBe("");
});
});
describe("loadBalanceConfig", () => {
it("显式配置优先于推导值", () => {
const config = loadBalanceConfig({
LLM_API_URL: "https://api.deepseek.com/v1/chat/completions",
LLM_BALANCE_URL: "https://proxy.test/balance",
});
expect(config.url).toBe("https://proxy.test/balance");
});
it("非法超时回退到缺省", () => {
expect(loadBalanceConfig({ LLM_BALANCE_TIMEOUT_MS: "-1" }).timeoutMs).toBe(10_000);
});
});
describe("fetchUpstreamBalance", () => {
it("未配置 API Key 时不发请求,直接返回未配置", async () => {
delete process.env.LLM_API_KEY;
const fetchImpl = vi.fn();
await expect(
fetchUpstreamBalance({ fetchImpl: fetchImpl as unknown as typeof fetch }),
).resolves.toEqual({ configured: false });
expect(fetchImpl).not.toHaveBeenCalled();
});
it("优先取人民币账户", async () => {
process.env.LLM_API_KEY = "key";
const fetchImpl = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({
balance_infos: [
{ currency: "USD", total_balance: "1.00", granted_balance: "0", topped_up_balance: "1.00" },
{ currency: "CNY", total_balance: "12.34", granted_balance: "0.00", topped_up_balance: "12.34" },
],
}),
} as Response);
const result = await fetchUpstreamBalance({
fetchImpl: fetchImpl as unknown as typeof fetch,
now: () => Date.parse("2026-10-10T09:00:00Z"),
});
expect(result).toEqual({
configured: true,
currency: "CNY",
totalBalance: "12.34",
grantedBalance: "0.00",
toppedUpBalance: "12.34",
fetchedAt: "2026-10-10T09:00:00.000Z",
});
});
it("没有人民币账户时取第一条,不返回空余额", async () => {
process.env.LLM_API_KEY = "key";
const fetchImpl = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ balance_infos: [{ currency: "USD", total_balance: "1.00" }] }),
} as Response);
const result = await fetchUpstreamBalance({ fetchImpl: fetchImpl as unknown as typeof fetch });
expect(result.configured).toBe(true);
expect(result.currency).toBe("USD");
});
it("上游报错或响应缺字段时返回未配置,而不是抛错把面板打挂", async () => {
process.env.LLM_API_KEY = "key";
const failing = vi.fn().mockResolvedValue({ ok: false, status: 500 } as Response);
await expect(
fetchUpstreamBalance({ fetchImpl: failing as unknown as typeof fetch }),
).resolves.toEqual({ configured: false });
const empty = vi.fn().mockResolvedValue({ ok: true, json: async () => ({}) } as Response);
await expect(
fetchUpstreamBalance({ fetchImpl: empty as unknown as typeof fetch }),
).resolves.toEqual({ configured: false });
const throwing = vi.fn().mockRejectedValue(new Error("network down"));
await expect(
fetchUpstreamBalance({ fetchImpl: throwing as unknown as typeof fetch }),
).resolves.toEqual({ configured: false });
});
});
+109
View File
@@ -0,0 +1,109 @@
/**
* 上游账户余额查询(对账用)。
*
* 设计要点:
* - 本地算出来的费用只是**估算**:单价表可能过期、峰谷判定可能偏差。
* 拿上游余额的变化去比对,是唯一能发现「计价表已经不对了」的手段。
* - 余额接口是供应商特有的(DeepSeek 是 `GET /user/balance`),因此地址可配置,
* 默认按 `LLM_API_URL` 的 origin 推导,换供应商时不必改代码。
* - 查询失败一律返回 `configured:false` 而不是抛错:余额只是辅助信息,
* 不能因为它把用量面板整体打挂。
*/
export interface BalanceSnapshot {
/** false 表示未配置 API Key、供应商不支持或查询失败 */
configured: boolean;
currency?: string;
totalBalance?: string;
grantedBalance?: string;
toppedUpBalance?: string;
fetchedAt?: string;
}
export interface BalanceConfig {
url: string;
apiKey: string;
timeoutMs: number;
}
export interface BalanceDeps {
fetchImpl?: typeof fetch;
now?: () => number;
}
/** 从 chat completions 地址推导出同源的余额地址;推导不出来时返回空串 */
export function deriveBalanceUrl(apiUrl: string): string {
try {
return `${new URL(apiUrl).origin}/user/balance`;
} catch {
return "";
}
}
export function loadBalanceConfig(env: NodeJS.ProcessEnv = process.env): BalanceConfig {
const apiUrl = env.LLM_API_URL ?? "https://api.deepseek.com/v1/chat/completions";
const explicit = (env.LLM_BALANCE_URL ?? "").trim();
const timeoutRaw = Number(env.LLM_BALANCE_TIMEOUT_MS ?? 10_000);
return {
url: explicit.length > 0 ? explicit : deriveBalanceUrl(apiUrl),
apiKey: (env.LLM_API_KEY ?? "").trim(),
timeoutMs: Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 10_000,
};
}
interface DeepSeekBalanceResponse {
balance_infos?: Array<{
currency?: string;
total_balance?: string;
granted_balance?: string;
topped_up_balance?: string;
}>;
}
/** 优先取人民币账户;找不到就取第一条,避免多币种账户下返回空 */
function pickBalanceInfo(
infos: DeepSeekBalanceResponse["balance_infos"],
): NonNullable<DeepSeekBalanceResponse["balance_infos"]>[number] | undefined {
if (!infos || infos.length === 0) return undefined;
return infos.find((info) => info.currency === "CNY") ?? infos[0];
}
export async function fetchUpstreamBalance(
deps: BalanceDeps = {},
): Promise<BalanceSnapshot> {
const config = loadBalanceConfig();
if (config.apiKey.length === 0 || config.url.length === 0) {
return { configured: false };
}
const fetchImpl = deps.fetchImpl ?? fetch;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), config.timeoutMs);
try {
const response = await fetchImpl(config.url, {
method: "GET",
headers: { Authorization: `Bearer ${config.apiKey}` },
signal: controller.signal,
});
if (!response.ok) {
return { configured: false };
}
const data = (await response.json()) as DeepSeekBalanceResponse;
const info = pickBalanceInfo(data.balance_infos);
if (!info) {
return { configured: false };
}
return {
configured: true,
currency: info.currency ?? "",
totalBalance: info.total_balance ?? "",
grantedBalance: info.granted_balance ?? "",
toppedUpBalance: info.topped_up_balance ?? "",
fetchedAt: new Date(deps.now ? deps.now() : Date.now()).toISOString(),
};
} catch {
return { configured: false };
} finally {
clearTimeout(timer);
}
}
+19 -1
View File
@@ -1,2 +1,20 @@
export { logStore, type LogEntry, type LogSummary } from "./store.js";
export { logStore, resetLogStoreForTest, type LogEntry, type LogSummary } from "./store.js";
export { adminRoutes } from "./routes.js";
export {
UsageReporter,
usageReporter,
loadReporterConfig,
toUsageRecord,
type UsageRecord,
type ReporterConfig,
} from "./reporter.js";
export { fetchUpstreamBalance, type BalanceSnapshot } from "./balance.js";
export {
loadPricingConfig,
priceUsage,
isPeak,
parsePeakWindows,
type PricingConfig,
type PricingSnapshot,
type PricedUsage,
} from "./pricing.js";
+166
View File
@@ -0,0 +1,166 @@
import { describe, expect, it } from "vitest";
import { emptyUsage, type TokenUsage } from "../llm/usage.js";
import { isPeak, loadPricingConfig, parsePeakWindows, priceUsage } from "./pricing.js";
function usage(partial: Partial<TokenUsage>): TokenUsage {
return { ...emptyUsage(), ...partial };
}
/** 2026-10-09 是周五;10-10/10-11 是周末;10-12 是周一 */
function utc(iso: string): Date {
return new Date(iso);
}
describe("parsePeakWindows", () => {
it("解析 HH:mm-HH:mm 列表", () => {
expect(parsePeakWindows("01:00-04:00,06:00-10:00")).toEqual([
{ startMinute: 60, endMinute: 240 },
{ startMinute: 360, endMinute: 600 },
]);
});
it("单条格式写错只跳过这一条,其余窗口仍生效", () => {
expect(parsePeakWindows("01:00-04:00,bad,06:00-10:00")).toEqual([
{ startMinute: 60, endMinute: 240 },
{ startMinute: 360, endMinute: 600 },
]);
});
it("起止相同的窗口视为无效", () => {
expect(parsePeakWindows("01:00-01:00")).toEqual([]);
});
it("不传时回退到 DeepSeek 公布的默认窗口", () => {
expect(parsePeakWindows(undefined)).toHaveLength(2);
});
});
describe("isPeak", () => {
const config = loadPricingConfig({});
it("工作日落在峰时窗口内为峰时", () => {
expect(isPeak(utc("2026-10-09T02:00:00Z"), config)).toBe(true);
expect(isPeak(utc("2026-10-09T08:00:00Z"), config)).toBe(true);
});
it("工作日落在窗口外为谷时", () => {
expect(isPeak(utc("2026-10-09T00:30:00Z"), config)).toBe(false);
expect(isPeak(utc("2026-10-09T05:00:00Z"), config)).toBe(false);
expect(isPeak(utc("2026-10-09T12:00:00Z"), config)).toBe(false);
});
it("窗口右端开区间:04:00 整不算峰时", () => {
expect(isPeak(utc("2026-10-09T04:00:00Z"), config)).toBe(false);
});
it("周末一律谷时", () => {
expect(isPeak(utc("2026-10-10T02:00:00Z"), config)).toBe(false);
expect(isPeak(utc("2026-10-11T08:00:00Z"), config)).toBe(false);
});
it("配置为法定节假日的日期按谷时计价", () => {
const holiday = loadPricingConfig({ LLM_PRICE_PEAK_HOLIDAYS: "2026-10-12" });
expect(isPeak(utc("2026-10-12T02:00:00Z"), holiday)).toBe(false);
// 未列入的周一仍按峰时
expect(isPeak(utc("2026-10-12T02:00:00Z"), config)).toBe(true);
});
it("支持跨零点的窗口", () => {
const overnight = loadPricingConfig({ LLM_PRICE_PEAK_WINDOWS: "23:00-02:00" });
expect(isPeak(utc("2026-10-09T23:30:00Z"), overnight)).toBe(true);
expect(isPeak(utc("2026-10-09T01:00:00Z"), overnight)).toBe(true);
expect(isPeak(utc("2026-10-09T03:00:00Z"), overnight)).toBe(false);
});
});
describe("priceUsage", () => {
const config = loadPricingConfig({});
it("按峰时三档单价计价", () => {
const { costUsd, snapshot } = priceUsage(
usage({ cacheHitTokens: 1_000_000, cacheMissTokens: 1_000_000, completionTokens: 1_000_000 }),
utc("2026-10-09T02:00:00Z"),
config,
);
expect(snapshot.peak).toBe(true);
expect(costUsd).toBe(1.506);
});
it("谷时单价是峰时的一半", () => {
const { costUsd, snapshot } = priceUsage(
usage({ cacheHitTokens: 1_000_000, cacheMissTokens: 1_000_000, completionTokens: 1_000_000 }),
utc("2026-10-09T12:00:00Z"),
config,
);
expect(snapshot.peak).toBe(false);
expect(costUsd).toBe(0.753);
expect(snapshot.effectivePrices.cacheMissPerM).toBe(0.15);
expect(snapshot.listPrices.cacheMissPerM).toBe(0.3);
});
it("未上报用量时费用为 null,而不是 0", () => {
const { costUsd } = priceUsage(emptyUsage(), utc("2026-10-09T12:00:00Z"), config);
expect(costUsd).toBeNull();
});
it("没有缓存明细时把整个 prompt 按未命中价计,宁可高估也不低估", () => {
const { costUsd } = priceUsage(
usage({ promptTokens: 1_000_000, completionTokens: 0 }),
utc("2026-10-09T02:00:00Z"),
config,
);
expect(costUsd).toBe(0.3);
});
it("只有命中数没有未命中数时用 prompt - hit 兜底", () => {
const { costUsd } = priceUsage(
usage({ promptTokens: 1_000_000, cacheHitTokens: 400_000, completionTokens: 0 }),
utc("2026-10-09T02:00:00Z"),
config,
);
// 40 万命中 × 0.006 + 60 万未命中 × 0.3 = 0.0024 + 0.18
expect(costUsd).toBe(0.1824);
});
it("费用按 8 位小数收敛,避免浮点噪声写进 DECIMAL(18,8)", () => {
const { costUsd } = priceUsage(
usage({ promptTokens: 3, completionTokens: 7 }),
utc("2026-10-09T02:00:00Z"),
config,
);
expect(String(costUsd)).toMatch(/^\d+(\.\d{1,8})?$/);
});
});
describe("loadPricingConfig", () => {
it("缺省单价与官方 PEAK 一列一致", () => {
const config = loadPricingConfig({});
expect(config.cacheHitPerM).toBe(0.006);
expect(config.cacheMissPerM).toBe(0.3);
expect(config.outputPerM).toBe(1.2);
expect(config.offpeakFactor).toBe(0.5);
});
it("环境变量可覆盖单价,并让版本号随之变化", () => {
const base = loadPricingConfig({});
const changed = loadPricingConfig({ LLM_PRICE_OUTPUT_PER_M: "2.4" });
expect(changed.outputPerM).toBe(2.4);
// 版本号由单价派生,改价即变版本,避免历史账被新价格重算
expect(changed.version).not.toBe(base.version);
});
it("显式版本号优先于派生值", () => {
const config = loadPricingConfig({ LLM_PRICE_VERSION: "2026-11 调价" });
expect(config.version).toBe("2026-11 调价");
});
it("非法单价回退到缺省值", () => {
const config = loadPricingConfig({ LLM_PRICE_OUTPUT_PER_M: "abc", LLM_PRICE_CACHE_HIT_PER_M: "-1" });
expect(config.outputPerM).toBe(1.2);
expect(config.cacheHitPerM).toBe(0.006);
});
});
+231
View File
@@ -0,0 +1,231 @@
/**
* LLM 计价 —— DeepSeek 三档单价 + 峰谷时段。
*
* 设计要点:
* - **单价按「每百万 token 的美元价」配置**,不引入中转站那套倍率/钱包抽象:
* 本项目是单租户内部服务,没有余额可扣,倍率只会多一层浮点误差面。
* - **峰谷价差必须算进去**:DeepSeek 谷时价是峰时价的一半,而峰时只占工作日的 7 小时。
* 忽略它会将近一倍地高估费用(夜间与周末的调用全被按峰时价算)。
* - **计价结果要冻结**:价格表会变,历史账不能被新价格改写,所以结算时把生效单价与
* 是否峰时一并写进日志快照,而不是展示时现算。
* - **中国法定节假日按谷时计价**,但节假日表每年都变,因此做成配置项而不是硬编码日历。
*/
import { hasUsage, type TokenUsage } from "../llm/usage.js";
/** UTC 分钟数区间;`startMinute > endMinute` 表示跨零点 */
export interface PeakWindow {
startMinute: number;
endMinute: number;
}
export interface PricingConfig {
/** 峰时:缓存命中输入 token 单价(USD / 1M tokens) */
cacheHitPerM: number;
/** 峰时:缓存未命中输入 token 单价 */
cacheMissPerM: number;
/** 峰时:输出 token 单价 */
outputPerM: number;
/** 谷时价 = 峰时价 × 该系数;设为 1 即取消峰谷差异 */
offpeakFactor: number;
peakWindows: PeakWindow[];
/** 按谷时计价的日期(UTC 的 `yyyy-MM-dd`),用于中国法定节假日 */
offpeakDates: string[];
/** 计价表版本;不显式配置时由单价派生,改价即自动变版本 */
version: string;
}
export interface PricingSnapshot {
version: string;
peak: boolean;
/** 本次实际生效的单价(已含峰谷系数) */
effectivePrices: {
cacheHitPerM: number;
cacheMissPerM: number;
outputPerM: number;
};
/** 峰时标价,便于与账单核对 */
listPrices: {
cacheHitPerM: number;
cacheMissPerM: number;
outputPerM: number;
};
}
export interface PricedUsage {
/** 无法计价(上游完全没上报用量)时为 null,不要用 0 冒充 */
costUsd: number | null;
snapshot: PricingSnapshot;
}
/**
* DeepSeek 公布的峰时窗口(UTC,周一至周五):
* 01:00–04:00 与 06:00–10:00,其余时段(含周末与中国法定节假日)为谷时。
*/
const DEFAULT_PEAK_WINDOWS = "01:00-04:00,06:00-10:00";
/** 峰时单价(USD / 1M tokens),取自 DeepSeek 官方 Models & Pricing 的 PEAK 一列 */
const DEFAULT_CACHE_HIT_PER_M = 0.006;
const DEFAULT_CACHE_MISS_PER_M = 0.3;
const DEFAULT_OUTPUT_PER_M = 1.2;
/** 谷时 = 峰时 × 0.5 */
const DEFAULT_OFFPEAK_FACTOR = 0.5;
/** 费用落到 DECIMAL(18,8) 之前先收敛浮点噪声 */
const COST_DECIMALS = 8;
function numberFrom(value: string | undefined, fallback: number): number {
if (value === undefined || value.trim() === "") return fallback;
const parsed = Number(value);
return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
}
/**
* 解析 `HH:mm-HH:mm` 列表。
*
* 单条格式不对就跳过它而不是整段回退到默认值:运维改了一个窗口写错格式时,
* 其余窗口仍然生效,故障面更小。
*/
export function parsePeakWindows(raw: string | undefined): PeakWindow[] {
if (raw === undefined) return parsePeakWindows(DEFAULT_PEAK_WINDOWS);
return raw
.split(",")
.map((item) => item.trim())
.filter((item) => item.length > 0)
.map((item) => {
const match = /^(\d{1,2}):(\d{2})\s*-\s*(\d{1,2}):(\d{2})$/.exec(item);
if (!match) return null;
const [, startHour, startMinute, endHour, endMinute] = match;
const start = Number(startHour) * 60 + Number(startMinute);
const end = Number(endHour) * 60 + Number(endMinute);
if (start > 24 * 60 || end > 24 * 60 || start === end) return null;
return { startMinute: start, endMinute: end };
})
.filter((window): window is PeakWindow => window !== null);
}
function parseOffpeakDates(raw: string | undefined): string[] {
if (raw === undefined || raw.trim() === "") return [];
return raw
.split(",")
.map((item) => item.trim())
.filter((item) => /^\d{4}-\d{2}-\d{2}$/.test(item));
}
/** 单价指纹:改价即变版本,无需人工维护版本号 */
function deriveVersion(
cacheHitPerM: number,
cacheMissPerM: number,
outputPerM: number,
offpeakFactor: number,
): string {
return `hit${cacheHitPerM}|miss${cacheMissPerM}|out${outputPerM}|off${offpeakFactor}`;
}
export function loadPricingConfig(env: NodeJS.ProcessEnv = process.env): PricingConfig {
const cacheHitPerM = numberFrom(env.LLM_PRICE_CACHE_HIT_PER_M, DEFAULT_CACHE_HIT_PER_M);
const cacheMissPerM = numberFrom(env.LLM_PRICE_CACHE_MISS_PER_M, DEFAULT_CACHE_MISS_PER_M);
const outputPerM = numberFrom(env.LLM_PRICE_OUTPUT_PER_M, DEFAULT_OUTPUT_PER_M);
const offpeakFactor = numberFrom(env.LLM_PRICE_OFFPEAK_FACTOR, DEFAULT_OFFPEAK_FACTOR);
const explicitVersion = (env.LLM_PRICE_VERSION ?? "").trim();
return {
cacheHitPerM,
cacheMissPerM,
outputPerM,
offpeakFactor,
peakWindows: parsePeakWindows(env.LLM_PRICE_PEAK_WINDOWS),
offpeakDates: parseOffpeakDates(env.LLM_PRICE_PEAK_HOLIDAYS),
version:
explicitVersion.length > 0
? explicitVersion
: deriveVersion(cacheHitPerM, cacheMissPerM, outputPerM, offpeakFactor),
};
}
function utcDateKey(at: Date): string {
const year = at.getUTCFullYear();
const month = String(at.getUTCMonth() + 1).padStart(2, "0");
const day = String(at.getUTCDate()).padStart(2, "0");
return `${year}-${month}-${day}`;
}
function inWindow(minute: number, window: PeakWindow): boolean {
if (window.startMinute < window.endMinute) {
return minute >= window.startMinute && minute < window.endMinute;
}
// 跨零点(如 23:00-02:00)
return minute >= window.startMinute || minute < window.endMinute;
}
/**
* 判断某一时刻是否按峰时计价。
*
* 一律按 UTC 判定:DeepSeek 的峰时窗口就是按 UTC 公布的,
* 用服务器本地时区(部署在哪个区不确定)会算错整段。
*/
export function isPeak(at: Date, config: PricingConfig): boolean {
const weekday = at.getUTCDay();
if (weekday === 0 || weekday === 6) return false;
if (config.offpeakDates.includes(utcDateKey(at))) return false;
const minute = at.getUTCHours() * 60 + at.getUTCMinutes();
return config.peakWindows.some((window) => inWindow(minute, window));
}
function roundCost(value: number): number {
const factor = 10 ** COST_DECIMALS;
return Math.round(value * factor) / factor;
}
/**
* 把一次(或累计多次尝试的)用量换算成美元费用。
*
* 缓存未命中数的兜底顺序:优先用上游给的 `cacheMissTokens`;没给就用
* `promptTokens - cacheHitTokens`;连命中数都没有则把整个 `promptTokens`
* 按未命中价计——未命中价更高,宁可略微高估也不低估账单。
*/
export function priceUsage(
usage: TokenUsage,
at: Date,
config: PricingConfig,
): PricedUsage {
const peak = isPeak(at, config);
const multiplier = peak ? 1 : config.offpeakFactor;
const effectivePrices = {
cacheHitPerM: config.cacheHitPerM * multiplier,
cacheMissPerM: config.cacheMissPerM * multiplier,
outputPerM: config.outputPerM * multiplier,
};
const snapshot: PricingSnapshot = {
version: config.version,
peak,
effectivePrices,
listPrices: {
cacheHitPerM: config.cacheHitPerM,
cacheMissPerM: config.cacheMissPerM,
outputPerM: config.outputPerM,
},
};
if (!hasUsage(usage)) {
return { costUsd: null, snapshot };
}
const cacheHitTokens = usage.cacheHitTokens ?? 0;
let cacheMissTokens = usage.cacheMissTokens;
if (cacheMissTokens === null) {
cacheMissTokens =
usage.promptTokens !== null
? Math.max(0, usage.promptTokens - cacheHitTokens)
: 0;
}
const completionTokens = usage.completionTokens ?? 0;
const cost =
(cacheHitTokens / 1_000_000) * effectivePrices.cacheHitPerM +
(cacheMissTokens / 1_000_000) * effectivePrices.cacheMissPerM +
(completionTokens / 1_000_000) * effectivePrices.outputPerM;
return { costUsd: roundCost(cost), snapshot };
}
+290
View File
@@ -0,0 +1,290 @@
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("必填字段永远非空,否则 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);
});
});
+299
View File
@@ -0,0 +1,299 @@
/**
* 用量上报(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;
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,
model: entry.model,
attempts: entry.attempts ?? 1,
isLlmCall: entry.isLlmCall,
usageSource: entry.usageSource ?? "missing",
promptTokens: usage?.promptTokens ?? null,
completionTokens: usage?.completionTokens ?? null,
totalTokens: usage?.totalTokens ?? null,
cacheHitTokens: usage?.cacheHitTokens ?? null,
cacheMissTokens: usage?.cacheMissTokens ?? null,
reasoningTokens: usage?.reasoningTokens ?? null,
costUsd: entry.costUsd ?? null,
pricingVersion: entry.pricing?.version ?? null,
peak: entry.pricing?.peak ?? null,
durationMs: entry.durationMs,
status: entry.status,
errorCode: entry.errorCode ?? null,
};
}
const DEFAULT_OUTBOX_NAME = "usage-outbox.json";
/** 与 store.ts 同一口径:可配置且惰性解析,避免测试写进开发者的真实数据目录 */
/** 取一批记录的幂等键,用于从 outbox 里精确移除已处理的那批 */
function sentIdsOf(batch: UsageRecord[]): Set<string> {
return new Set(batch.map((record) => record.recordId));
}
function defaultOutboxFile(): string {
const configured = (process.env.LPT_AI_DATA_DIR ?? "").trim();
const dir = configured.length > 0 ? configured : resolve(process.cwd(), "data");
return resolve(dir, DEFAULT_OUTBOX_NAME);
}
export class UsageReporter {
private readonly deps: ReporterDeps;
private pending: UsageRecord[] = [];
private loaded = false;
private cachedConfig: ReporterConfig | null = null;
private timer: NodeJS.Timeout | null = null;
private flushing = false;
/** 因超出上限被丢弃的条数,便于发现「长期上报失败」 */
private droppedCount = 0;
constructor(deps: ReporterDeps = {}) {
this.deps = deps;
}
private config(): ReporterConfig {
if (!this.cachedConfig) {
this.cachedConfig = (this.deps.loadConfig ?? loadReporterConfig)();
}
return this.cachedConfig;
}
private outboxFile(): string {
return this.deps.outboxFile ?? defaultOutboxFile();
}
isConfigured(): boolean {
return this.config().url.length > 0;
}
pendingCount(): number {
this.ensureLoaded();
return this.pending.length;
}
get dropped(): number {
return this.droppedCount;
}
/** 入队一条日志;未配置上报地址时直接忽略 */
enqueue(entry: LogEntry): void {
if (!this.isConfigured()) return;
this.ensureLoaded();
this.pending.push(toUsageRecord(entry));
const { maxPending } = this.config();
if (this.pending.length > maxPending) {
const overflow = this.pending.length - maxPending;
this.pending.splice(0, overflow);
this.droppedCount += overflow;
}
this.persist();
}
/** 推送一批;成功才从 outbox 删除,失败原样保留等下次 */
async flush(): Promise<FlushResult> {
this.ensureLoaded();
const config = this.config();
if (!this.isConfigured() || this.pending.length === 0) {
return { sent: 0, remaining: this.pending.length };
}
if (this.flushing) {
return { sent: 0, remaining: this.pending.length };
}
this.flushing = true;
const batch = this.pending.slice(0, config.batchSize);
try {
const fetchImpl = this.deps.fetchImpl ?? fetch;
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), config.timeoutMs);
let response: Response;
try {
response = await fetchImpl(`${config.url}/internal/ai-usage/records`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-token": config.token,
},
body: JSON.stringify({ records: batch }),
signal: controller.signal,
});
} finally {
clearTimeout(timer);
}
if (!response.ok) {
const body = await response.text().catch(() => "");
// 4xx 是确定性拒绝(报文格式不对、令牌不对):重试多少次都一样,
// 继续留在 outbox 只会把队列堵死,把后续正常记录一起饿死。丢弃并计数。
if (response.status >= 400 && response.status < 500) {
this.pending = this.pending.filter((record) => !sentIdsOf(batch).has(record.recordId));
this.droppedCount += batch.length;
this.persist();
return {
sent: 0,
remaining: this.pending.length,
error: `上报被拒绝 (${response.status}),已丢弃这批记录: ${body.slice(0, 200)}`,
};
}
return {
sent: 0,
remaining: this.pending.length,
error: `上报失败 (${response.status}): ${body.slice(0, 200)}`,
};
}
// 只移除本次实际推送的那批;期间新入队的记录不受影响
const sentIds = sentIdsOf(batch);
this.pending = this.pending.filter((record) => !sentIds.has(record.recordId));
this.persist();
return { sent: batch.length, remaining: this.pending.length };
} catch (err) {
return {
sent: 0,
remaining: this.pending.length,
error: err instanceof Error ? err.message : String(err),
};
} finally {
this.flushing = false;
}
}
/** 启动定时推送;未配置上报地址时不做任何事 */
start(): void {
if (!this.isConfigured() || this.timer) return;
const { intervalMs } = this.config();
this.timer = setInterval(() => {
void this.flush();
}, intervalMs);
// 不要因为上报定时器让进程无法退出
this.timer.unref?.();
void this.flush();
}
stop(): void {
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
}
// ---- outbox 持久化 ----
private ensureLoaded(): void {
if (this.loaded) return;
this.loaded = true;
try {
const file = this.outboxFile();
if (!existsSync(file)) return;
const raw = readFileSync(file, "utf-8");
const data = JSON.parse(raw) as UsageRecord[];
this.pending = Array.isArray(data) ? data : [];
} catch {
// 文件损坏时从空队列开始,避免坏数据让上报永久卡死
this.pending = [];
}
}
private persist(): void {
try {
const file = this.outboxFile();
const dir = dirname(file);
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
// 原子替换:被中断的直写会留下截断 JSON,重启后整队列丢失
const tmpFile = `${file}.tmp`;
writeFileSync(tmpFile, JSON.stringify(this.pending), "utf-8");
renameSync(tmpFile, file);
} catch {
// 写盘失败不阻塞请求,队列仍在内存里
}
}
}
export const usageReporter = new UsageReporter();
+129
View File
@@ -0,0 +1,129 @@
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import Fastify from "fastify";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { adminRoutes } from "./routes.js";
import { logStore, resetLogStoreForTest } from "./store.js";
const originalToken = process.env.LPT_AI_TOKEN;
const originalDataDir = process.env.LPT_AI_DATA_DIR;
let workDir: string;
// 必须指向临时目录:单例默认写 process.cwd()/data,不隔离会把开发者真实的面板数据清掉
beforeEach(() => {
workDir = mkdtempSync(join(tmpdir(), "lpt-ai-admin-"));
process.env.LPT_AI_DATA_DIR = workDir;
});
afterEach(() => {
if (originalToken === undefined) {
delete process.env.LPT_AI_TOKEN;
} else {
process.env.LPT_AI_TOKEN = originalToken;
}
if (originalDataDir === undefined) {
delete process.env.LPT_AI_DATA_DIR;
} else {
process.env.LPT_AI_DATA_DIR = originalDataDir;
}
rmSync(workDir, { recursive: true, force: true });
});
async function buildApp() {
const app = Fastify();
await app.register(adminRoutes);
await app.ready();
return app;
}
function scriptOf(html: string): string {
const match = /<script>([\s\S]*)<\/script>/.exec(html);
if (!match) throw new Error("面板 HTML 里找不到内联脚本");
return match[1];
}
describe("管理面板", () => {
it("内联脚本必须能被解析", async () => {
const app = await buildApp();
const response = await app.inject({ method: "GET", url: "/admin" });
expect(response.statusCode).toBe(200);
const script = scriptOf(response.body);
// 面板 HTML 是模板字面量拼出来的:`\n` / `\'` 会被模板先吃掉,
// 落到产物里就是字符串里的裸换行或提前截断的引号——整套面板会静默变成空白页。
// 这里直接解析产物脚本,把这类转义错误挡在提交之前。
expect(() => new Function(script)).not.toThrow();
await app.close();
});
it("未配置令牌时面板与日志接口都放行", async () => {
delete process.env.LPT_AI_TOKEN;
const app = await buildApp();
expect((await app.inject({ method: "GET", url: "/admin" })).statusCode).toBe(200);
expect((await app.inject({ method: "GET", url: "/admin/logs" })).statusCode).toBe(200);
await app.close();
});
it("配置令牌后无令牌请求被拒", async () => {
process.env.LPT_AI_TOKEN = "secret-token";
const app = await buildApp();
expect((await app.inject({ method: "GET", url: "/admin" })).statusCode).toBe(401);
expect((await app.inject({ method: "GET", url: "/admin/logs" })).statusCode).toBe(401);
await app.close();
});
it("用 ?token= 打开面板时换发 HttpOnly cookie,后续 fetch 才能通过", async () => {
process.env.LPT_AI_TOKEN = "secret-token";
const app = await buildApp();
const page = await app.inject({ method: "GET", url: "/admin?token=secret-token" });
expect(page.statusCode).toBe(200);
const setCookie = String(page.headers["set-cookie"]);
expect(setCookie).toContain("lpt_ai_token=secret-token");
expect(setCookie).toContain("HttpOnly");
expect(setCookie).toContain("Path=/admin");
// 面板内部的 fetch 不带 query,只靠 cookie
const logs = await app.inject({
method: "GET",
url: "/admin/logs",
headers: { cookie: "lpt_ai_token=secret-token" },
});
expect(logs.statusCode).toBe(200);
await app.close();
});
it("日志摘要按 isLlmCall 区分,非 LLM 请求不计入用量分母", async () => {
delete process.env.LPT_AI_TOKEN;
resetLogStoreForTest();
const app = await buildApp();
logStore.add({
timestamp: "2026-10-10T09:00:00.000Z",
endpoint: "/fetch-title",
taskType: "fetch-title",
model: "",
isLlmCall: false,
durationMs: 10,
status: 200,
requestBody: {},
responseBody: {},
});
const response = await app.inject({ method: "GET", url: "/admin/logs" });
const body = JSON.parse(response.body) as {
stats: { total: number; llmCalls: number; cacheHitRate: number | null };
};
expect(body.stats.total).toBe(1);
expect(body.stats.llmCalls).toBe(0);
// 分母为 0 时返回 null,面板显示「—」而不是 0%
expect(body.stats.cacheHitRate).toBeNull();
resetLogStoreForTest();
await app.close();
});
});
+113 -20
View File
@@ -4,7 +4,8 @@
import type { FastifyInstance } from "fastify";
import { logStore } from "./store.js";
import { checkToken, configuredToken } from "../utils/auth.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">
@@ -36,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}
@@ -60,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>
@@ -82,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('');
@@ -104,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('');
}
}
@@ -153,22 +182,26 @@ 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.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;
};
@@ -176,7 +209,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
@@ -188,8 +221,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>';
@@ -209,6 +260,12 @@ function escapeHtml(s) {
return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;');
}
/** 千位分隔;null/undefined 统一显示为 0,调用方负责区分「未上报」 */
function formatNumber(value) {
if (value == null) return '0';
return Number(value).toLocaleString('en-US');
}
function copyLog(id, btn) {
const ta = document.getElementById(id);
if (!ta) return;
@@ -230,6 +287,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();
@@ -253,7 +318,15 @@ export async function adminRoutes(app: FastifyInstance): Promise<void> {
});
// —— 面板页面 ——
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);
});
@@ -261,6 +334,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,
@@ -269,10 +349,23 @@ export async function adminRoutes(app: FastifyInstance): Promise<void> {
? Math.round(summaries.reduce((a, s) => a + s.durationMs, 0) / summaries.length)
: 0,
endpoints: logStore.endpoints(),
llmCalls: llm.length,
promptTokens: sum((s) => s.usage?.promptTokens),
completionTokens: sum((s) => s.usage?.completionTokens),
totalTokens: sum((s) => s.usage?.totalTokens),
cacheHitTokens,
cacheMissTokens,
// 分母为 0 时返回 null,面板显示「—」而不是 0%
cacheHitRate: cacheTotal > 0 ? cacheHitTokens / cacheTotal : null,
costUsd: llm.reduce((total, item) => total + (item.costUsd ?? 0), 0),
unreportedUsageCalls: llm.filter((s) => s.usage?.promptTokens == null).length,
};
return { logs: summaries, stats };
});
// —— 上游余额(对账)——
app.get("/admin/usage/balance", async () => fetchUpstreamBalance());
// —— 日志详情 ——
app.get<{ Params: { id: string } }>("/admin/logs/:id", async (request, reply) => {
const id = parseInt(request.params.id, 10);
+162
View File
@@ -0,0 +1,162 @@
import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { logStore, LogStore, resetLogStoreForTest, type LogEntry } from "./store.js";
const originalDataDir = process.env.LPT_AI_DATA_DIR;
let workDir: string;
// 必须指向临时目录:单例默认写 process.cwd()/data,
// 不隔离就会在跑测试时把开发者真实的面板数据清掉。
beforeEach(() => {
workDir = mkdtempSync(join(tmpdir(), "lpt-ai-store-"));
process.env.LPT_AI_DATA_DIR = workDir;
});
afterEach(() => {
if (originalDataDir === undefined) {
delete process.env.LPT_AI_DATA_DIR;
} else {
process.env.LPT_AI_DATA_DIR = originalDataDir;
}
rmSync(workDir, { recursive: true, force: true });
});
function logFile(): string {
return join(workDir, "logs.json");
}
function entry(overrides: Partial<LogEntry> = {}): Omit<LogEntry, "id" | "recordId"> {
return {
timestamp: "2026-10-10T09:00:00.000Z",
endpoint: "/ai/tasks#guidance",
taskType: "guidance",
model: "deepseek-flash",
attempts: 1,
isLlmCall: true,
durationMs: 100,
status: 200,
requestBody: {},
responseBody: {},
...overrides,
};
}
describe("LogStore 落盘", () => {
it("写入临时文件后原子替换,不留下 .tmp 残渣", () => {
const store = new LogStore();
store.add(entry());
expect(existsSync(logFile())).toBe(true);
expect(existsSync(`${logFile()}.tmp`)).toBe(false);
const persisted = JSON.parse(readFileSync(logFile(), "utf-8")) as { entries: LogEntry[] };
expect(persisted.entries).toHaveLength(1);
expect(persisted.entries[0].recordId).toBeTruthy();
});
it("落盘到 LPT_AI_DATA_DIR,而不是 process.cwd()/data", () => {
const store = new LogStore();
store.add(entry());
expect(existsSync(logFile())).toBe(true);
});
it("重新打开时能读回自己写的数据", () => {
new LogStore().add(entry({ endpoint: "/ai/tasks#compare-recall" }));
const reopened = new LogStore();
expect(reopened.list()).toHaveLength(1);
expect(reopened.list()[0].endpoint).toBe("/ai/tasks#compare-recall");
});
it("超过上限时丢弃最旧的记录", () => {
const store = new LogStore();
for (let i = 0; i < 501; i += 1) {
store.add(entry({ status: i }));
}
expect(store.list()).toHaveLength(500);
});
});
describe("LogStore 历史数据迁移", () => {
it("旧条目缺 isLlmCall 时按端点补齐,避免历史 LLM 调用被当成非 LLM 而静默消失", () => {
// 旧格式:没有 isLlmCall / recordId / usage
writeFileSync(
logFile(),
JSON.stringify({
nextId: 3,
entries: [
{
id: 1,
timestamp: "2026-10-09T09:00:00.000Z",
endpoint: "/ai/tasks#guidance",
model: "deepseek-flash",
durationMs: 100,
status: 200,
requestBody: {},
responseBody: {},
},
{
id: 2,
timestamp: "2026-10-09T09:01:00.000Z",
endpoint: "/fetch-title",
model: "",
durationMs: 5,
status: 200,
requestBody: {},
responseBody: {},
},
],
}),
"utf-8",
);
const summaries = new LogStore().list();
expect(summaries).toHaveLength(2);
expect(summaries.find((s) => s.endpoint === "/ai/tasks#guidance")?.isLlmCall).toBe(true);
// 抓标题不过 LLM,不该被计入用量分母
expect(summaries.find((s) => s.endpoint === "/fetch-title")?.isLlmCall).toBe(false);
});
it("旧条目没有用量时保持未上报,不用 0 冒充", () => {
writeFileSync(
logFile(),
JSON.stringify({
nextId: 2,
entries: [
{
id: 1,
timestamp: "2026-10-09T09:00:00.000Z",
endpoint: "/ai/tasks#guidance",
model: "deepseek-flash",
durationMs: 100,
status: 200,
requestBody: {},
responseBody: {},
},
],
}),
"utf-8",
);
const summary = new LogStore().list()[0];
expect(summary.usage).toBeUndefined();
expect(summary.costUsd).toBeUndefined();
});
it("文件损坏时从空存储开始,不让面板整体起不来", () => {
writeFileSync(logFile(), "{ not json", "utf-8");
expect(new LogStore().list()).toEqual([]);
});
});
describe("resetLogStoreForTest", () => {
it("清空单例,避免用例之间互相污染", () => {
logStore.add(entry());
resetLogStoreForTest();
expect(logStore.list()).toEqual([]);
});
});
+123 -22
View File
@@ -1,19 +1,46 @@
/**
* 请求日志存储 —— 环形缓冲区 + 可选文件持久化。
*
* 每条日志记录 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;
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 +48,120 @@ 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;
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 } : {}),
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 +169,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 +203,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 +220,8 @@ class LogStore {
}
export const logStore = new LogStore();
/** 仅用于测试:重置内部状态,避免用例之间互相污染 */
export function resetLogStoreForTest(): void {
logStore.clear();
}
+11
View File
@@ -4,6 +4,7 @@ import { dirname, resolve } from "node:path";
import Fastify from "fastify";
import { aiRoutes } from "./routes/ai.js";
import { adminRoutes } from "./admin/index.js";
import { usageReporter } from "./admin/reporter.js";
// ===== 加载 .env(零依赖,兼容 dev/start 两种启动方式)=====
const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -36,6 +37,16 @@ const app = Fastify({
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 {
+74
View File
@@ -23,6 +23,18 @@ function mockFetchOnce() {
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>;
@@ -64,3 +76,65 @@ describe("chat 请求体", () => {
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,
);
});
});
+38 -5
View File
@@ -8,12 +8,28 @@
*/
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;
@@ -53,6 +69,13 @@ export class LlmError extends Error {
* 而不是用自己的指数退避——服务商限流时自己的退避往往偏短。
*/
public readonly retryAfterMs?: number,
/**
* 这次失败的调用是否已经产生了 token 消耗。
*
* 典型场景是上游返回 200 但内容为空:请求已经计费,只是没法用。
* 有值时调用方必须把它计入用量,否则这部分消耗会凭空消失。
*/
public readonly usage?: TokenUsage,
) {
super(message);
this.name = "LlmError";
@@ -81,13 +104,13 @@ export function parseRetryAfter(value: string | null, now: number = Date.now()):
}
/**
* 非流式调用,返回完整文本
* 非流式调用,返回正文与上游上报的 token 用量。
*/
export async function chat(
config: LlmConfig,
messages: ChatMessage[],
options?: ChatOptions,
): Promise<string> {
): Promise<ChatResult> {
if (!isAvailable(config)) {
throw new LlmError("LLM API Key 未配置", 503);
}
@@ -126,13 +149,23 @@ export async function chat(
}
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") {
+134
View File
@@ -0,0 +1,134 @@
import { describe, expect, it } from "vitest";
import {
accumulateUsage,
combineSource,
emptyUsage,
hasUsage,
normalizeUsage,
type TokenUsage,
} from "./usage.js";
function usage(partial: Partial<TokenUsage>): TokenUsage {
return { ...emptyUsage(), ...partial };
}
describe("normalizeUsage", () => {
it("取 DeepSeek 顶层字段,包括缓存命中与未命中", () => {
const { usage: result, source } = normalizeUsage({
prompt_tokens: 1000,
completion_tokens: 200,
total_tokens: 1200,
prompt_cache_hit_tokens: 800,
prompt_cache_miss_tokens: 200,
completion_tokens_details: { reasoning_tokens: 50 },
});
expect(source).toBe("upstream");
expect(result).toEqual({
promptTokens: 1000,
completionTokens: 200,
totalTokens: 1200,
cacheHitTokens: 800,
cacheMissTokens: 200,
reasoningTokens: 50,
});
});
it("OpenAI 风格的 prompt_tokens_details.cached_tokens 也能识别", () => {
const { usage: result } = normalizeUsage({
prompt_tokens: 500,
completion_tokens: 100,
prompt_tokens_details: { cached_tokens: 300 },
});
expect(result.cacheHitTokens).toBe(300);
// 未命中数缺失时用 prompt - hit 兜底推出
expect(result.cacheMissTokens).toBe(200);
});
it("total_tokens 缺失时用 prompt + completion 兜底", () => {
const { usage: result } = normalizeUsage({ prompt_tokens: 10, completion_tokens: 5 });
expect(result.totalTokens).toBe(15);
});
it("缓存命中数大于 prompt 时不会算出负的未命中数", () => {
const { usage: result } = normalizeUsage({
prompt_tokens: 100,
prompt_tokens_details: { cached_tokens: 150 },
});
expect(result.cacheMissTokens).toBe(0);
});
it("非对象一律当成未上报,不抛错", () => {
for (const raw of [undefined, null, "usage", 42, []]) {
const { usage: result, source } = normalizeUsage(raw);
expect(source).toBe("missing");
expect(hasUsage(result)).toBe(false);
}
});
it("负值与非数字字段按未上报处理,不猜值", () => {
const { usage: result, source } = normalizeUsage({
prompt_tokens: -5,
completion_tokens: "abc",
});
expect(source).toBe("missing");
expect(result.promptTokens).toBeNull();
expect(result.completionTokens).toBeNull();
});
it("明确上报 0 与未上报是两种结果", () => {
const reportedZero = normalizeUsage({ prompt_tokens: 0, completion_tokens: 0 });
expect(reportedZero.source).toBe("upstream");
expect(reportedZero.usage.promptTokens).toBe(0);
const missing = normalizeUsage({});
expect(missing.source).toBe("missing");
expect(missing.usage.promptTokens).toBeNull();
});
});
describe("accumulateUsage", () => {
it("累加各次尝试的用量", () => {
const result = accumulateUsage([
usage({ promptTokens: 100, completionTokens: 20, totalTokens: 120 }),
usage({ promptTokens: 150, completionTokens: 30, totalTokens: 180 }),
]);
expect(result.promptTokens).toBe(250);
expect(result.completionTokens).toBe(50);
expect(result.totalTokens).toBe(300);
});
it("某次尝试没上报的字段按 0 计,但全都没上报时保持 null", () => {
const result = accumulateUsage([
usage({ promptTokens: 100 }),
usage({}),
]);
expect(result.promptTokens).toBe(100);
// 两次都没上报的字段不能被算成 0
expect(result.completionTokens).toBeNull();
expect(result.reasoningTokens).toBeNull();
});
it("空数组返回全 null", () => {
expect(hasUsage(accumulateUsage([]))).toBe(false);
});
});
describe("combineSource", () => {
it("只要有真实上游数据就标 upstream", () => {
expect(combineSource(["missing", "upstream", "missing"])).toBe("upstream");
});
it("没有 upstream 但有估算时标 estimated", () => {
expect(combineSource(["missing", "estimated"])).toBe("estimated");
});
it("全为 missing 时标 missing", () => {
expect(combineSource(["missing", "missing"])).toBe("missing");
expect(combineSource([])).toBe("missing");
});
});
+161
View File
@@ -0,0 +1,161 @@
/**
* Token 用量归一化与跨尝试累加。
*
* 设计要点:
* - **null 与 0 是两回事**:null 表示上游根本没上报 usage,0 表示上游明确说这次用了 0。
* 面板上「未上报」与「0 token」必须能分辨,否则上游一改返回结构,用量会静默变成 0 而不是暴露出来。
* - **按厂商字段归一**:DeepSeek 把缓存命中放在顶层 `prompt_cache_hit_tokens`,
* OpenAI 兼容实现放在 `prompt_tokens_details.cached_tokens`,两者都取;
* 未命中数缺失时用 `prompt_tokens - cacheHit` 兜底推出。
* - **跨尝试累加**:一个任务重试 N 次就是 N 次计费,失败尝试若已产生 token 同样要算
* (例如上游返回 200 但内容为空)。累加时 null 视为 0,但「所有尝试都没上报」必须保持 null。
*/
/** 一次 LLM 调用的 token 明细;字段为 null 表示上游未上报该维度 */
export interface TokenUsage {
promptTokens: number | null;
completionTokens: number | null;
totalTokens: number | null;
/** 命中上下文缓存的输入 token(计价明显低于未命中) */
cacheHitTokens: number | null;
/** 未命中缓存的输入 token */
cacheMissTokens: number | null;
/** 思考模式产生的推理 token,已含在 completionTokens 内 */
reasoningTokens: number | null;
}
/**
* 用量的来源,用于区分「上游真实上报」与「本地兜底」。
* `missing` 占比升高说明上游改了返回结构,是需要告警的信号。
*/
export type UsageSource = "upstream" | "estimated" | "missing";
export interface UsageSnapshot {
usage: TokenUsage;
source: UsageSource;
}
const TOKEN_FIELDS = [
"promptTokens",
"completionTokens",
"totalTokens",
"cacheHitTokens",
"cacheMissTokens",
"reasoningTokens",
] as const satisfies readonly (keyof TokenUsage)[];
export function emptyUsage(): TokenUsage {
return {
promptTokens: null,
completionTokens: null,
totalTokens: null,
cacheHitTokens: null,
cacheMissTokens: null,
reasoningTokens: null,
};
}
export function hasUsage(usage: TokenUsage): boolean {
return TOKEN_FIELDS.some((field) => usage[field] !== null);
}
/** 只接受非负整数;负值、NaN、非数字一律当「未上报」,不要猜 */
function nonNegativeInt(value: unknown): number | null {
if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return null;
return Math.floor(value);
}
function firstPresent(...values: Array<number | null>): number | null {
for (const value of values) {
if (value !== null) return value;
}
return null;
}
function readPath(source: Record<string, unknown>, path: string): number | null {
let current: unknown = source;
for (const key of path.split(".")) {
if (current === null || typeof current !== "object") return null;
current = (current as Record<string, unknown>)[key];
}
return nonNegativeInt(current);
}
/**
* 把上游响应里的 `usage` 对象归一化成 {@link TokenUsage}。
*
* 传入任何非对象(undefined、null、字符串)都返回全 null 且来源为 `missing`,
* 让调用方无需自己判空。
*/
export function normalizeUsage(raw: unknown): UsageSnapshot {
if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
return { usage: emptyUsage(), source: "missing" };
}
const source = raw as Record<string, unknown>;
// Anthropic 风格的 input/output_tokens 一并兼容,换供应商时不用改这里
const promptTokens = firstPresent(
readPath(source, "prompt_tokens"),
readPath(source, "input_tokens"),
);
const completionTokens = firstPresent(
readPath(source, "completion_tokens"),
readPath(source, "output_tokens"),
);
const totalTokens = firstPresent(
readPath(source, "total_tokens"),
promptTokens !== null && completionTokens !== null ? promptTokens + completionTokens : null,
);
const cacheHitTokens = firstPresent(
readPath(source, "prompt_cache_hit_tokens"),
readPath(source, "prompt_tokens_details.cached_tokens"),
readPath(source, "input_tokens_details.cached_tokens"),
);
const cacheMissTokens = firstPresent(
readPath(source, "prompt_cache_miss_tokens"),
// 上游只给总数与命中数时,相减即未命中数;钳到 0 避免上游字段不一致时算出负数
promptTokens !== null && cacheHitTokens !== null
? Math.max(0, promptTokens - cacheHitTokens)
: null,
);
const reasoningTokens = readPath(source, "completion_tokens_details.reasoning_tokens");
const usage: TokenUsage = {
promptTokens,
completionTokens,
totalTokens,
cacheHitTokens,
cacheMissTokens,
reasoningTokens,
};
return { usage, source: hasUsage(usage) ? "upstream" : "missing" };
}
/**
* 累加多次尝试的用量。
*
* 每个字段独立判断:只要有任意一次上报了该字段就求和(未上报的那几次按 0 计),
* 全部都没上报才返回 null。这样「重试 3 次只有第 2 次拿到 usage」不会被算成 0。
*/
export function accumulateUsage(snapshots: TokenUsage[]): TokenUsage {
const result = emptyUsage();
for (const field of TOKEN_FIELDS) {
const present = snapshots
.map((snapshot) => snapshot[field])
.filter((value): value is number => value !== null);
result[field] = present.length > 0 ? present.reduce((sum, value) => sum + value, 0) : null;
}
return result;
}
/**
* 合并多次尝试的来源标记。
*
* 只要有一次拿到真实上游数据就标 `upstream`——部分上报仍比完全没有数据可信,
* 把它降级成 `estimated` 会让「上游改结构」这个信号被淹没。
*/
export function combineSource(sources: UsageSource[]): UsageSource {
if (sources.includes("upstream")) return "upstream";
if (sources.includes("estimated")) return "estimated";
return "missing";
}
+9
View File
@@ -116,7 +116,11 @@ export async function aiRoutes(app: FastifyInstance): Promise<void> {
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 },
@@ -130,12 +134,17 @@ export async function aiRoutes(app: FastifyInstance): Promise<void> {
logStore.add({
timestamp: new Date().toISOString(),
endpoint: "/fetch-title",
taskType: "fetch-title",
model: "",
attempts: 1,
// 抓标题不过 LLM,不计入用量统计
isLlmCall: false,
durationMs: Date.now() - t0,
status: blocked ? 400 : 502,
requestBody: { url },
responseBody: { url, title: null },
error: message,
errorCode: blocked ? "unsafe_url" : "fetch_failed",
});
if (blocked) {
return reply.status(400).send({ error: message });
+149 -2
View File
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
import { afterEach, describe, expect, it, vi } from "vitest";
import { LlmError } from "./llm/client.js";
import { parseReportDraft, TaskQueue, computeTaskKey, callOptionsFor, loadQueueConfig, type QueueConfig, type TaskRecord } from "./task-queue.js";
import { classifyLlmError, parseReportDraft, TaskQueue, computeTaskKey, callOptionsFor, loadQueueConfig, type QueueConfig, type TaskRecord } from "./task-queue.js";
/** 测试用队列:不碰真实 LLM、不写管理面板日志、不启定时器 */
function makeQueue(
@@ -527,6 +527,153 @@ describe("TaskQueue 基本行为", () => {
});
});
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("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(
+84 -1
View File
@@ -13,10 +13,12 @@
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 } 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";
// ---- 类型 ----
@@ -35,6 +37,16 @@ export interface TaskRecord {
error?: string;
/** 已尝试次数(含首次),便于排查重试情况 */
attempts: number;
/**
* 跨所有尝试累加的 token 用量。
*
* 重试会重复计费,所以这里是「这个任务一共花了多少」,不是「最后一次花了多少」;
* 某个字段为 null 表示所有尝试都没拿到该维度(不要当成 0)。
*/
usage?: TokenUsage;
usageSource?: UsageSource;
/** 失败分类(timeout / rate_limited / ...),便于按错误类型聚合用量 */
errorCode?: string;
createdAt: string; // ISO 8601
startedAt?: string;
completedAt?: string;
@@ -289,6 +301,8 @@ export class TaskQueue {
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;
}
@@ -308,9 +322,31 @@ export class TaskQueue {
},
};
// 每次尝试的用量都要留下:重试 N 次就是 N 次计费,失败尝试也可能已经产生了 token
const attemptUsages: TokenUsage[] = [];
const attemptSources: UsageSource[] = [];
try {
const runOnce =
this.deps.runOnce ?? (async (t, ctx) => parseResult(t.type, await chat(ctx.config, ctx.messages, callOptions)));
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,
@@ -323,8 +359,11 @@ export class TaskQueue {
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);
}
}
@@ -338,15 +377,28 @@ export class TaskQueue {
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(this.now()).toISOString(),
endpoint: `/ai/tasks#${task.type}`,
taskType: task.type,
taskId: task.id,
model: config.model,
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: task.status === "done" ? (task.result ?? {}) : {},
...(task.error ? { error: task.error } : {}),
...(task.errorCode ? { errorCode: task.errorCode } : {}),
});
}
@@ -377,6 +429,37 @@ export class TaskQueue {
}
}
// ---- 失败分类 ----
/**
* 把失败原因归成可聚合的短分类。
*
* 面板要能回答「这个月有多少次是被限流打掉的」;把整句错误文案当分类是聚合不起来的。
* 上游原文仍然留在 `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 {
+84 -1
View File
@@ -1,6 +1,6 @@
import { afterEach, describe, expect, it } from "vitest";
import { checkToken, configuredToken, TOKEN_HEADER } from "./auth.js";
import { checkToken, configuredToken, providedToken, queryTokenMatches, readCookie, TOKEN_COOKIE, TOKEN_HEADER } from "./auth.js";
/** 极简 reply 替身:记录是否写出 401 */
const makeReply = () => {
@@ -70,4 +70,87 @@ describe("AI 入站令牌", () => {
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);
});
});
+48 -5
View File
@@ -2,14 +2,20 @@
* 入站访问令牌(安全-03)。
*
* 设计取舍:令牌是**可选**的。
* - 设置 `LPT_AI_TOKEN` 后,`/ai/*` 与 `/admin` 都要求携带令牌(header `x-api-token` 或 query `token`);
* - 设置 `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 {
@@ -21,6 +27,33 @@ interface TokenRequest {
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) ?? "";
}
/**
* 校验请求是否携带了正确的令牌。
*
@@ -33,11 +66,21 @@ export function checkToken(
const token = configuredToken();
if (!token) return true;
const header = request.headers[TOKEN_HEADER];
const query = request.query as { token?: string } | undefined;
const provided = typeof header === "string" ? header : query?.token;
if (provided === 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;
}