@njuptlzf/agent-chat-server 0.4.1 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,260 @@
1
+ /**
2
+ * 统一成本模型(M-14 / 成本模型:平台级成本口径,不绑定供应商)。
3
+ *
4
+ * 为什么要有它:平台曾有三条各说各话的成本线(pi 的 costUsd / 向用户收费的 spendCents /
5
+ * 只数 token 的额度闸),benchmark 被迫去适配"某家按次、某家按 token"——本末倒置。
6
+ * 本模块定义平台唯一的成本口径:任何供应商的计费模型都声明成 CostModel,
7
+ * 统一折算成整数 CU(内部记账单位),与供应商、币种、显示单位解耦。
8
+ *
9
+ * 核心折算纯函数零副作用;loadCostTable 读 models.json 是启动期一次性的 IO。
10
+ * 类型不进 protocol(公开 54 符号不变)。
11
+ *
12
+ * 设计稿:docs/design/统一成本模型设计稿.md(五口径已由用户 2026-11-17 拍板)。
13
+ */
14
+ import { readFileSync } from "node:fs";
15
+
16
+ /** 平台内部记账单位:非负整数 CU。金额由展示层倍率决定,不进核心计算。 */
17
+ export type CU = number;
18
+
19
+ /** 每百万 token 的 CU 单价。 */
20
+ export interface CUTokenRates {
21
+ readonly input: CU;
22
+ readonly output: CU;
23
+ readonly cacheRead: CU;
24
+ readonly cacheWrite: CU;
25
+ }
26
+
27
+ /**
28
+ * 供应商计费模型——models.json 声明,启动期强制校验(口径 4:缺声明拒绝启动)。
29
+ *
30
+ * - per-token:四维单价,按 usage 各维度计费;
31
+ * - per-call:每次固定 cuPerCall,含 includedTokens 免费额度,超出部分按 overflow 补价(口径 2);
32
+ * - flat:整 run 一口价(订阅/包月内部结算);
33
+ * - hybrid:base(per-call 或 flat)+ tokenRates 两部分相加。
34
+ */
35
+ export type CostModel =
36
+ | { readonly kind: "per-token"; readonly rates: CUTokenRates }
37
+ | { readonly kind: "per-call"; readonly cuPerCall: CU; readonly includedTokens?: number; readonly overflow: CUTokenRates }
38
+ | { readonly kind: "flat"; readonly cuPerRun: CU }
39
+ | {
40
+ readonly kind: "hybrid";
41
+ readonly base: "per-call" | "flat";
42
+ readonly cuBase: CU;
43
+ readonly tokenRates: CUTokenRates;
44
+ };
45
+
46
+ /** 成本拆分:各维度 CU + 总计。 */
47
+ export interface CostBreakdown {
48
+ readonly cu: CU;
49
+ readonly byDimension: {
50
+ readonly base: CU;
51
+ readonly input: CU;
52
+ readonly output: CU;
53
+ readonly cacheRead: CU;
54
+ readonly cacheWrite: CU;
55
+ };
56
+ readonly kind: CostModel["kind"];
57
+ }
58
+
59
+ /** costOfUsage 的最小输入(与 protocol 的 TokenUsage 结构兼容,但不依赖它——保持 server 内部类型独立)。 */
60
+ export interface UsageLike {
61
+ readonly input: number;
62
+ readonly output: number;
63
+ readonly cacheRead: number;
64
+ readonly cacheWrite: number;
65
+ readonly total: number;
66
+ }
67
+
68
+ /** 向上取整到整数 CU——宁可多算一 CU,不白送成本。 */
69
+ const ceilCu = (cu: number): CU => Math.max(0, Math.ceil(cu - 1e-9));
70
+
71
+ /** 按四维单价计算 token 部分;included 额度从 input 开始依次扣减(输入优先,其次输出)。 */
72
+ function tokenCu(usage: UsageLike, rates: CUTokenRates, included = 0): CostBreakdown["byDimension"] {
73
+ let remaining = Math.max(0, included);
74
+ const afterIncluded = (v: number): number => {
75
+ const consumed = Math.min(remaining, v);
76
+ remaining -= consumed;
77
+ return v - consumed;
78
+ };
79
+ const input = afterIncluded(usage.input);
80
+ const output = afterIncluded(usage.output);
81
+ const cacheRead = afterIncluded(usage.cacheRead);
82
+ const cacheWrite = afterIncluded(usage.cacheWrite);
83
+ return {
84
+ base: 0,
85
+ input: ceilCu((input * rates.input) / 1_000_000),
86
+ output: ceilCu((output * rates.output) / 1_000_000),
87
+ cacheRead: ceilCu((cacheRead * rates.cacheRead) / 1_000_000),
88
+ cacheWrite: ceilCu((cacheWrite * rates.cacheWrite) / 1_000_000),
89
+ };
90
+ }
91
+
92
+ const sum = (d: CostBreakdown["byDimension"]): CU =>
93
+ d.base + d.input + d.output + d.cacheRead + d.cacheWrite;
94
+
95
+ /** 平台唯一的成本口径:把任意 CostModel 的一次用量折算成 CU 拆分。 */
96
+ export function costOfUsage(usage: UsageLike, model: CostModel): CostBreakdown {
97
+ let by: CostBreakdown["byDimension"] = { base: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
98
+ switch (model.kind) {
99
+ case "per-token":
100
+ by = tokenCu(usage, model.rates);
101
+ break;
102
+ case "per-call":
103
+ by = tokenCu(usage, model.overflow, model.includedTokens ?? 0);
104
+ by = { ...by, base: ceilCu(model.cuPerCall) };
105
+ break;
106
+ case "flat":
107
+ by = { ...by, base: ceilCu(model.cuPerRun) };
108
+ break;
109
+ case "hybrid":
110
+ by = tokenCu(usage, model.tokenRates);
111
+ by = { ...by, base: ceilCu(model.cuBase) };
112
+ break;
113
+ }
114
+ return { cu: sum(by), byDimension: by, kind: model.kind };
115
+ }
116
+
117
+ /** 显示单位:CU 是内部不可变整数,展示层按需换算(口径 1 的前半:显示单位可切换)。 */
118
+ export type DisplayUnit = "CU" | "US_CENTS" | "CNY_CENTS";
119
+
120
+ /** displayRate:1 CU 等于多少个目标单位(倍率可由产品配置调整——口径 1 的后半:计价基准靠改倍率)。 */
121
+ export function displayCu(cu: CU, unit: DisplayUnit, rate: { US_CENTS: number; CNY_CENTS: number }): number {
122
+ if (unit === "CU") return cu;
123
+ const factor = unit === "US_CENTS" ? rate.US_CENTS : rate.CNY_CENTS;
124
+ return Math.round(cu * factor * 100) / 100;
125
+ }
126
+
127
+ /**
128
+ * 从 models.json 的模型条目解析 CostModel(启动期校验用)。
129
+ * 缺 costModel 返回 null——调用方据此拒绝启动并报清晰错误(口径 4)。
130
+ */
131
+ export function parseCostModel(raw: unknown): CostModel | null {
132
+ if (!raw || typeof raw !== "object") return null;
133
+ const o = raw as Record<string, unknown>;
134
+ if (typeof o.kind !== "string") return null;
135
+ switch (o.kind) {
136
+ case "per-token": {
137
+ const r = o.rates;
138
+ return isRates(r) ? { kind: "per-token", rates: r } : null;
139
+ }
140
+ case "per-call": {
141
+ if (!isCu(o.cuPerCall) || !isRates(o.overflow)) return null;
142
+ const included = o.includedTokens;
143
+ if (included !== undefined && (typeof included !== "number" || !Number.isFinite(included) || included < 0)) return null;
144
+ return { kind: "per-call", cuPerCall: o.cuPerCall, includedTokens: included as number | undefined, overflow: o.overflow };
145
+ }
146
+ case "flat":
147
+ return isCu(o.cuPerRun) ? { kind: "flat", cuPerRun: o.cuPerRun } : null;
148
+ case "hybrid":
149
+ if ((o.base !== "per-call" && o.base !== "flat") || !isCu(o.cuBase) || !isRates(o.tokenRates)) return null;
150
+ return { kind: "hybrid", base: o.base, cuBase: o.cuBase, tokenRates: o.tokenRates };
151
+ default:
152
+ return null;
153
+ }
154
+ }
155
+
156
+ /**
157
+ * 启动期校验(口径 4 · 2026-11-18 修订):逐 provider/model 检查 models.json 的 costModel 声明。
158
+ *
159
+ * - **缺声明 → 放行**(不报错):这类模型走 CostTable 的全局倍率兜底(token × rate);
160
+ * ModelScope 这类按次计费、不在权威定价表的模型因此零配置也能算成本。
161
+ * - **声明了但非法 → fail fast**:有 typo 的配置必须当场暴露(错误矩阵:输入校验失败=fatal)。
162
+ * - providers 形状不对 → fail fast(无法建立成本表)。
163
+ *
164
+ * 返回解析好的逐模型 CostModel 表(只含合法声明),供 costOfUsage 精细折算优先使用。
165
+ */
166
+ export function validateModelsCost(modelsJson: unknown): Map<string, CostModel> {
167
+ const root = modelsJson as { providers?: Record<string, { models?: Array<Record<string, unknown>> }> } | null;
168
+ if (!root || typeof root !== "object" || !root.providers || typeof root.providers !== "object") {
169
+ throw new Error("[cost-model] models.json 缺少 providers 对象,无法校验成本模型声明");
170
+ }
171
+ const table = new Map<string, CostModel>();
172
+ const problems: string[] = [];
173
+ for (const [provider, cfg] of Object.entries(root.providers)) {
174
+ const models = cfg?.models;
175
+ if (!Array.isArray(models)) {
176
+ problems.push(`provider "${provider}" 没有 models 数组`);
177
+ continue;
178
+ }
179
+ for (const m of models) {
180
+ const id = String(m.id ?? "<无 id>");
181
+ if (m.costModel === undefined) continue; // 缺声明放行 → 全局倍率兜底
182
+ const parsed = parseCostModel(m.costModel);
183
+ if (!parsed) {
184
+ problems.push(
185
+ `provider "${provider}" 的 model "${id}" 的 costModel 声明非法` +
186
+ `(需形如 {kind:"per-token",rates:{input,output,cacheRead,cacheWrite}},` +
187
+ `或 {kind:"per-call",cuPerCall,includedTokens?,overflow} / {kind:"flat",cuPerRun} / {kind:"hybrid",...};CU 为非负整数)。` +
188
+ `若不声明则走全局倍率兜底,但仍建议修正 typo`,
189
+ );
190
+ continue;
191
+ }
192
+ table.set(`${provider}/${id}`, parsed);
193
+ }
194
+ }
195
+ if (problems.length) {
196
+ throw new Error(`[cost-model] models.json 成本模型声明校验失败(声明了但非法;未声明的模型走全局倍率兜底):\n- ${problems.join("\n- ")}`);
197
+ }
198
+ return table;
199
+ }
200
+
201
+ function isCu(v: unknown): v is CU {
202
+ return typeof v === "number" && Number.isFinite(v) && v >= 0 && Number.isInteger(v);
203
+ }
204
+ function isRates(v: unknown): v is CUTokenRates {
205
+ if (!v || typeof v !== "object") return false;
206
+ const r = v as Record<string, unknown>;
207
+ return isCu(r.input) && isCu(r.output) && isCu(r.cacheRead) && isCu(r.cacheWrite);
208
+ }
209
+
210
+ /**
211
+ * 成本表:按 provider/model 索引 CostModel,供 settle 把 run 的 usage 折算成 CU。
212
+ *
213
+ * 口径边界(诚实):一次 run 可能 failover 换候选、多 phase 用不同 persona/model,
214
+ * 但 usage 是 run 级聚合、拿不到每次调用的归属。这里按 run 的**起始 tier 模型**折算整笔,
215
+ * 与 T3 的 perRunTokenCap 同抽象层(run 维度)。精确分模型计费要改 pi session 每次
216
+ * 调用点记录,属另一个接缝改造——见设计稿 §6.1。
217
+ */
218
+ /** 全局倍率默认值:1 CU / 千 token,开箱即用(口径 4 修订)。 */
219
+ export const DEFAULT_COST_RATE = 1;
220
+
221
+ /** 全局倍率兜底:token 数 × 倍率 / 1000,向上取整到整数 CU(不白送成本)。 */
222
+ export function flatRateCu(usage: UsageLike, ratePerThousand: number): CU {
223
+ return ceilCu((usage.total / 1000) * ratePerThousand);
224
+ }
225
+
226
+ export class CostTable {
227
+ /**
228
+ * @param models 逐模型精细声明(优先)
229
+ * @param ratePerThousandTokens 全局倍率兜底(无精细声明时用),默认 DEFAULT_COST_RATE
230
+ */
231
+ constructor(
232
+ private readonly models: ReadonlyMap<string, CostModel>,
233
+ private readonly ratePerThousandTokens: number = DEFAULT_COST_RATE,
234
+ ) {}
235
+
236
+ /**
237
+ * 按 provider/model 折算 CU:
238
+ * - 有合法逐模型声明 → costOfUsage 精细折算(优先);
239
+ * - 无声明 → 全局倍率兜底 token × rate(口径 4 修订,ModelScope 这类模型零配置也能算)。
240
+ */
241
+ cuFor(provider: string, model: string, usage: UsageLike): CU {
242
+ const declared = this.models.get(`${provider}/${model}`);
243
+ return declared ? costOfUsage(usage, declared).cu : flatRateCu(usage, this.ratePerThousandTokens);
244
+ }
245
+
246
+ /** 该 provider/model 是否有精细声明(供测试与诊断;无声明走兜底不等于无成本)。 */
247
+ has(provider: string, model: string): boolean {
248
+ return this.models.has(`${provider}/${model}`);
249
+ }
250
+ }
251
+
252
+ /**
253
+ * 启动期从 dataDir/models.json 加载并校验成本表。
254
+ * @param ratePerThousandTokens 全局倍率兜底,默认 DEFAULT_COST_RATE;由 main.ts 从 manifest 传入。
255
+ * 校验失败(providers 形状不对 / 声明了但非法)直接抛,与 createModelRuntime 同源。
256
+ */
257
+ export function loadCostTable(dataDir: string, ratePerThousandTokens: number = DEFAULT_COST_RATE): CostTable {
258
+ const raw = JSON.parse(readFileSync(`${dataDir}/models.json`, "utf8")) as unknown;
259
+ return new CostTable(validateModelsCost(raw), ratePerThousandTokens);
260
+ }
package/src/events.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
2
2
  import type { ChatEvent, TokenUsage, ToolResultView } from "@njuptlzf/agent-chat-protocol";
3
+ import type { UsageLike } from "./cost-model.ts";
3
4
 
4
5
  type PiUsage = {
5
6
  input: number;
@@ -14,14 +15,28 @@ export function emptyUsage(): TokenUsage {
14
15
  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0, costUsd: 0 };
15
16
  }
16
17
 
17
- function toTokenUsage(u: PiUsage): TokenUsage {
18
+ /**
19
+ * costOf:把 usage 折算成平台统一成本 CU 的回调(由调用方绑定 provider/model 的 CostModel)。
20
+ * 不传 ⇒ 回退 pi 的 u.cost.total(零行为变化,兼容老部署与 trial 旁路)。
21
+ *
22
+ * 注意 TokenUsage.costUsd 这个字段名是历史遗留:传了 costOf 时装的是 CU 整数、不是美元。
23
+ * 协议注释已同步说明(见 protocol/src/index.ts)。
24
+ */
25
+ function toTokenUsage(u: PiUsage, costOf?: (usage: UsageLike) => number): TokenUsage {
26
+ const asUsage: UsageLike = {
27
+ input: u.input,
28
+ output: u.output,
29
+ cacheRead: u.cacheRead,
30
+ cacheWrite: u.cacheWrite,
31
+ total: u.totalTokens,
32
+ };
18
33
  return {
19
34
  input: u.input,
20
35
  output: u.output,
21
36
  cacheRead: u.cacheRead,
22
37
  cacheWrite: u.cacheWrite,
23
38
  total: u.totalTokens,
24
- costUsd: u.cost.total,
39
+ costUsd: costOf ? costOf(asUsage) : u.cost.total,
25
40
  };
26
41
  }
27
42
 
@@ -101,7 +116,7 @@ export interface EventMapper {
101
116
  * Translate pi session events into the stable wire protocol.
102
117
  * Stateful (message ids, usage totals), so create one mapper per run.
103
118
  */
104
- export function createEventMapper(): EventMapper {
119
+ export function createEventMapper(costOf?: (usage: UsageLike) => number): EventMapper {
105
120
  let counter = 0;
106
121
  let currentMessageId = "";
107
122
  let total = emptyUsage();
@@ -136,7 +151,7 @@ export function createEventMapper(): EventMapper {
136
151
  };
137
152
  if (msg.role !== "assistant") return [];
138
153
  const out: ChatEvent[] = [];
139
- const usage = msg.usage ? toTokenUsage(msg.usage) : undefined;
154
+ const usage = msg.usage ? toTokenUsage(msg.usage, costOf) : undefined;
140
155
  if (usage) total = addUsage(total, usage);
141
156
  out.push({
142
157
  type: "message_end",
package/src/ledger.ts CHANGED
@@ -22,7 +22,7 @@
22
22
  * `used + Σ在飞上界 <= tokenCap` 恒成立(正常范围内);没配 ⇒ 预留 token 恒 0,
23
23
  * 退化为 W3 现状(只数已结算,在飞 run 可能把当日总量顶过去)。配置缺省零行为变化。
24
24
  */
25
- import { quotaBlockedReason, type QuotaCaps } from "./stores.ts";
25
+ import { quotaBlockedCostReason, quotaBlockedReason, type QuotaCaps } from "./stores.ts";
26
26
 
27
27
  /** 一次预留的句柄。`operationId` 由调用方生成(一请求一个),是幂等键。 */
28
28
  export interface LedgerReservation {
@@ -52,6 +52,8 @@ export interface SettleInput {
52
52
  readonly persona: string;
53
53
  /** 实际消耗的 token;`0` 也照常收口(只释放占位)。 */
54
54
  readonly tokens: number;
55
+ /** 实际消耗的 CU(成本模型独立闸);缺省 0 = 不启用 CU 计量。 */
56
+ readonly cu?: number;
55
57
  }
56
58
 
57
59
  export type SettleOutcome = "settled" | "already";
@@ -82,9 +84,12 @@ export class MemoryLedger implements Ledger {
82
84
  expiresAt: number;
83
85
  /** 预留的 token 上界(T3);settle 时回填实际值。W3 恒 0。 */
84
86
  tokens: number;
87
+ /** 预留的 CU 上界(成本模型独立闸);settle 时回填实际值。 */
88
+ costUnits: number;
85
89
  }
86
90
  >();
87
91
  private readonly used = new Map<string, number>();
92
+ private readonly usedCu = new Map<string, number>();
88
93
  private readonly runs = new Map<string, number>();
89
94
 
90
95
  constructor(
@@ -143,6 +148,21 @@ export class MemoryLedger implements Ledger {
143
148
  if (cap !== undefined && cap > 0) reserveTokens = Math.min(cap, tokenCap - used - reserved);
144
149
  }
145
150
 
151
+ // 成本模型 CU 闸(独立于 token):同样"已结算 + 在飞上界"判定,任一维触顶即拒。
152
+ let reserveCu = 0;
153
+ const dailyCostCap = input.caps?.dailyCostCap;
154
+ if (dailyCostCap !== undefined && dailyCostCap > 0) {
155
+ const usedCu = this.usedCu.get(key) ?? 0;
156
+ const reservedCu = [...this.rows.values()]
157
+ .filter((r) => r.day === day && r.state === "reserved" && r.expiresAt > now)
158
+ .reduce((a, r) => a + r.costUnits, 0);
159
+ if (usedCu + reservedCu >= dailyCostCap) {
160
+ return { ok: false, reason: quotaBlockedCostReason(input.caps ?? {}) };
161
+ }
162
+ const cap = input.caps?.perRunCostCap;
163
+ if (cap !== undefined && cap > 0) reserveCu = Math.min(cap, dailyCostCap - usedCu - reservedCu);
164
+ }
165
+
146
166
  const expiresAt = now + (input.ttlMs ?? RESERVATION_TTL_MS);
147
167
  this.rows.set(input.operationId, {
148
168
  userId: input.userId,
@@ -151,6 +171,7 @@ export class MemoryLedger implements Ledger {
151
171
  state: "reserved",
152
172
  expiresAt,
153
173
  tokens: reserveTokens,
174
+ costUnits: reserveCu,
154
175
  });
155
176
  return { ok: true, reservation: { operationId: input.operationId, expiresAt } };
156
177
  }
@@ -163,8 +184,10 @@ export class MemoryLedger implements Ledger {
163
184
  row.state = "settled";
164
185
  // 多退少补:把占位的上界改写为实际消耗(未用部分释放给后续 run)。
165
186
  row.tokens = input.tokens;
187
+ row.costUnits = input.cu ?? 0;
166
188
  const key = MemoryLedger.key(input.userId, input.persona, MemoryLedger.day(this.now()));
167
189
  if (input.tokens > 0) this.used.set(key, (this.used.get(key) ?? 0) + input.tokens);
190
+ if (input.cu && input.cu > 0) this.usedCu.set(key, (this.usedCu.get(key) ?? 0) + input.cu);
168
191
  this.runs.set(key, (this.runs.get(key) ?? 0) + 1);
169
192
  return "settled";
170
193
  }
package/src/main.ts CHANGED
@@ -7,6 +7,7 @@ import { createMcpConfigStore } from "./mcp-config.ts";
7
7
  import { createPersonaConfigStore } from "./persona-config.ts";
8
8
  import { initProductRoutes, loadProductAssembly, loadProductRoutes } from "./product-routes.ts";
9
9
  import { createChatServer } from "./server.ts";
10
+ import { loadCostTable } from "./cost-model.ts";
10
11
  import { describeComponents } from "./components.ts";
11
12
  import { createModelRuntime } from "./session.ts";
12
13
  import { createAdminAuth, createJwtAuth, insecureHeaderAuth } from "./stores.ts";
@@ -115,6 +116,9 @@ const deps = {
115
116
  toolFactory,
116
117
  history: new SqliteHistoryStore(db),
117
118
  ledger: new SqliteLedger(db, product.manifest.agent.limits?.dailyTokenQuota),
119
+ // 统一成本模型:启动期已校验 models.json 声明,这里装配成本表供 settle 折算 CU。
120
+ // 全局倍率兜底(无逐模型声明时用)来自 manifest,默认 1 CU/千 token。
121
+ costTable: loadCostTable(dataDir, product.manifest.agent.limits?.costRatePerThousandTokens),
118
122
  authenticate: jwtSecret ? createJwtAuth(jwtSecret) : insecureHeaderAuth,
119
123
  dataDir,
120
124
  runLog: new SqliteRunLog(db),
package/src/manifest.ts CHANGED
@@ -7,6 +7,7 @@ import { DEFAULT_PERSONA_ID, PERSONA_UI_FIELDS } from "@njuptlzf/agent-chat-prot
7
7
  import { FOLLOW_UP_MODES, parseBrandingUi, type FollowUpMode } from "./branding-ui.ts";
8
8
  import { auditExtensionSource } from "./extension-admission.ts";
9
9
  import { validateFlows } from "./flows.ts";
10
+ import { DEFAULT_MEMORY_PROVIDER_ID } from "./memory-providers.ts";
10
11
 
11
12
  /** A manifest whose relative paths have been resolved to absolute ones. */
12
13
  export interface LoadedProduct {
@@ -16,8 +17,18 @@ export interface LoadedProduct {
16
17
  systemPromptText: string;
17
18
  skillDirs: string[];
18
19
  extensionPaths: string[];
19
- /** `agent.memory` (default true): scope the scopedMemory plugin per session (). */
20
+ /**
21
+ * `agent.memory` (default true): which memory provider this product mounts.
22
+ * Resolved here so the server only ever passes an id to the registry.
23
+ */
20
24
  memoryEnabled: boolean;
25
+ /** Provider id from `agent.memory.provider`; falls back to the platform default. */
26
+ memoryProviderId: string;
27
+ /**
28
+ * 外部提供方模块(`agent.memoryProviders`),原样保留声明顺序。
29
+ * 加载在会话创建前完成——解析与准入扫描要读文件,manifest 解析是同步的。
30
+ */
31
+ memoryProviderModules: string[];
21
32
  /**
22
33
  * Question-bank directories keyed by qualification id (V0). A product with no
23
34
  * `quals` gets the single conventional `<product>/questions` under the empty
@@ -360,6 +371,10 @@ export function loadProduct(dir: string): LoadedProduct {
360
371
  if (maxRounds !== undefined && (!Number.isInteger(maxRounds) || maxRounds < 1)) {
361
372
  fail(file, "`agent.limits.maxToolRounds` must be a positive integer");
362
373
  }
374
+ const costRate = manifest.agent.limits?.costRatePerThousandTokens;
375
+ if (costRate !== undefined && (typeof costRate !== "number" || !Number.isFinite(costRate) || costRate <= 0)) {
376
+ fail(file, "`agent.limits.costRatePerThousandTokens` must be a positive number (CU per 1k tokens)");
377
+ }
363
378
  // Extensions execute in-process with full privileges, so a malformed entry is a
364
379
  // startup error: the operator must see a typo, not a silently skipped module.
365
380
  // Entries must be files: pi resolves an additional path that is a directory by
@@ -383,8 +398,22 @@ export function loadProduct(dir: string): LoadedProduct {
383
398
  }
384
399
  }
385
400
  }
386
- if (manifest.agent.memory !== undefined && typeof manifest.agent.memory !== "boolean") {
387
- fail(file, "`agent.memory` must be a boolean");
401
+ if (typeof manifest.agent.memory !== "boolean" && manifest.agent.memory !== undefined) {
402
+ const memory = manifest.agent.memory as { provider?: unknown };
403
+ if (typeof memory !== "object" || memory === null || Array.isArray(memory)) {
404
+ fail(file, "`agent.memory` must be a boolean or `{ provider }`");
405
+ }
406
+ if (memory.provider !== undefined && (typeof memory.provider !== "string" || memory.provider.trim() === "")) {
407
+ fail(file, "`agent.memory.provider` must be a non-empty string");
408
+ }
409
+ }
410
+ if (manifest.agent.memoryProviders !== undefined) {
411
+ const modules = manifest.agent.memoryProviders;
412
+ if (!Array.isArray(modules) || modules.length === 0 || !modules.every((p) => typeof p === "string" && p.trim() !== "")) {
413
+ fail(file, "`agent.memoryProviders` must be a non-empty list of non-empty strings");
414
+ }
415
+ // 只校验形状:条目可能是包名(靠依赖树解析),存在性与准入扫描留给真正加载它的
416
+ // 那一刻——报错信息里会带上解析后的绝对路径,比在这里猜准得多。
388
417
  }
389
418
  loadTiers(file, manifest);
390
419
  loadQuals(file, manifest);
@@ -527,6 +556,10 @@ export function loadProduct(dir: string): LoadedProduct {
527
556
  skillDirs,
528
557
  extensionPaths: (manifest.agent.extensions ?? []).map(resolve),
529
558
  memoryEnabled: manifest.agent.memory !== false,
559
+ memoryProviderId: typeof manifest.agent.memory === "object" && manifest.agent.memory !== null
560
+ ? manifest.agent.memory.provider ?? DEFAULT_MEMORY_PROVIDER_ID
561
+ : DEFAULT_MEMORY_PROVIDER_ID,
562
+ memoryProviderModules: [...(manifest.agent.memoryProviders ?? [])],
530
563
  questionDirs,
531
564
  caseDirs,
532
565
  essayDirs,
@@ -0,0 +1,187 @@
1
+ /**
2
+ * 记忆提供方注册表。
3
+ *
4
+ * 服务器只认 id,不认实现:换记忆引擎 = 换 manifest 里的 `agent.memory.provider`,
5
+ * 本文件之外的服务器代码一行不动。
6
+ *
7
+ * 注册有两条路:
8
+ * 1. **内置**:`scoped-memory` 是平台自带的最小实现,作为默认值存在——没有它,
9
+ * 一个没声明 provider 的产品就会没有记忆,那是最糟的默认。
10
+ * 2. **外部**:产品在 manifest 里声明 `agent.memoryProviders: [...]`,条目可以是
11
+ * 产品目录内的相对路径,也可以是包名(走 Node 解析)。外部模块与 `agent.extensions`
12
+ * 同一信任模型:仓库内代码、过准入扫描、进程内运行。
13
+ *
14
+ * 两条刻意选择:
15
+ * - **不可用即报错,不静默降级**。选了没装的 provider 就抛,并列出已注册 id。
16
+ * 静默回落默认实现,会让"我换了引擎"和"我忘了装"看起来一模一样。
17
+ * - **模块用动态 import**。静态导入会把提供方(可能是第三方包)的整棵源码拉进
18
+ * 本仓的 tsc program,跨仓源码进他人编译单元是最难收拾的一类耦合。
19
+ */
20
+
21
+ import { existsSync, readFileSync } from "node:fs";
22
+ import { createRequire } from "node:module";
23
+ import * as path from "node:path";
24
+ import { pathToFileURL } from "node:url";
25
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
26
+ import { scopedMemory } from "pi-scoped-memory";
27
+ import type { MemoryProvider, MemoryProviderModule } from "@njuptlzf/agent-chat-protocol";
28
+ import { auditExtensionSource } from "./extension-admission.ts";
29
+
30
+ /** 不指定时的实现。与 protocol 的 `agent.memory === true` 对齐。 */
31
+ export const DEFAULT_MEMORY_PROVIDER_ID = "scoped-memory";
32
+
33
+ const requireFromRoot = createRequire(import.meta.url);
34
+
35
+ function installedVersion(pkg: string): string {
36
+ try {
37
+ const parsed = requireFromRoot(`${pkg}/package.json`) as { version?: unknown };
38
+ return typeof parsed.version === "string" ? parsed.version : "unknown";
39
+ } catch {
40
+ // Version is for logs, not behaviour: a missing package.json must not break open().
41
+ return "unknown";
42
+ }
43
+ }
44
+
45
+ const scopedMemoryProvider: MemoryProvider<ExtensionAPI> = {
46
+ id: DEFAULT_MEMORY_PROVIDER_ID,
47
+ version: installedVersion("pi-scoped-memory"),
48
+ async open(ctx) {
49
+ const dir = ctx.storageRoot;
50
+ const { rm } = await import("node:fs/promises");
51
+ return {
52
+ providerId: DEFAULT_MEMORY_PROVIDER_ID,
53
+ // scopedMemory appends its own snapshot in before_agent_start.
54
+ selfInjects: true,
55
+ factory: scopedMemory({ dir, autoCapture: true }),
56
+ async promptSection() {
57
+ return "";
58
+ },
59
+ async erase() {
60
+ // Its own file is <dir>/entries.jsonl; the directory is host-allocated,
61
+ // so removing it is exactly one tenant's worth of data.
62
+ await rm(dir, { recursive: true, force: true });
63
+ },
64
+ async dispose() {},
65
+ };
66
+ },
67
+ };
68
+
69
+ const registry = new Map<string, MemoryProvider<ExtensionAPI>>([
70
+ [scopedMemoryProvider.id, scopedMemoryProvider],
71
+ ]);
72
+
73
+ /** 已加载的外部模块,按解析后的绝对路径去重:同一文件 import 两次不该注册两次。 */
74
+ const loadedModules = new Map<string, Promise<MemoryProvider<ExtensionAPI>>>();
75
+
76
+ function assertProviderShape(candidate: unknown, source: string): MemoryProvider<ExtensionAPI> {
77
+ const provider = candidate as Partial<MemoryProvider<ExtensionAPI>> | null | undefined;
78
+ if (!provider || typeof provider !== "object") {
79
+ throw new Error(`${source}: default export must be a memory provider object`);
80
+ }
81
+ if (typeof provider.id !== "string" || provider.id.trim() === "") {
82
+ throw new Error(`${source}: provider.id must be a non-empty string`);
83
+ }
84
+ if (typeof provider.version !== "string") {
85
+ throw new Error(`${source}: provider.version must be a string`);
86
+ }
87
+ if (typeof provider.open !== "function") {
88
+ throw new Error(`${source}: provider.open must be a function`);
89
+ }
90
+ return provider as MemoryProvider<ExtensionAPI>;
91
+ }
92
+
93
+ /**
94
+ * 注册一个提供方。
95
+ *
96
+ * 同 id 重复注册直接抛:静默覆盖会让"哪个实现真的生效"变成必须读启动日志才能回答的
97
+ * 问题,而启动日志往往在出事后已经滚没了。
98
+ */
99
+ export function registerMemoryProvider(provider: MemoryProvider<ExtensionAPI>): void {
100
+ const existing = registry.get(provider.id);
101
+ if (existing && existing !== provider) {
102
+ throw new Error(`memory provider "${provider.id}" is already registered (${existing.version})`);
103
+ }
104
+ registry.set(provider.id, provider);
105
+ }
106
+
107
+ /**
108
+ * 解析 manifest 里的一条外部模块声明。
109
+ *
110
+ * 相对路径(`./x.ts`)必须落在产品目录内——与 `server.routes` 同一条纪律:写 `../`
111
+ * 等于让 manifest 加载任意文件。裸说明符(包名)交给 Node 解析,装在哪由依赖树决定。
112
+ */
113
+ export function resolveProviderModuleEntry(entry: string, productDir: string): string {
114
+ const trimmed = entry.trim();
115
+ if (trimmed === "") throw new Error("memory provider module path must not be empty");
116
+ if (trimmed.startsWith(".")) {
117
+ const resolved = path.resolve(productDir, trimmed);
118
+ const inside = path.resolve(productDir) + path.sep;
119
+ if (!resolved.startsWith(inside)) {
120
+ throw new Error(`memory provider module "${trimmed}" must stay inside the product directory`);
121
+ }
122
+ return resolved;
123
+ }
124
+ try {
125
+ return requireFromRoot.resolve(trimmed, { paths: [productDir] });
126
+ } catch (error) {
127
+ throw new Error(
128
+ `memory provider module "${trimmed}" is not resolvable from ${productDir}: ${(error as Error).message}`,
129
+ );
130
+ }
131
+ }
132
+
133
+ /**
134
+ * 从文件加载外部提供方。准入扫描与扩展同一套判据:提供方也在服务进程内运行,
135
+ * 读 env / 拉子进程在这里同样是跨层能力。
136
+ */
137
+ export async function loadMemoryProviderModule(
138
+ entry: string,
139
+ productDir: string,
140
+ ): Promise<MemoryProvider<ExtensionAPI>> {
141
+ const resolved = resolveProviderModuleEntry(entry, productDir);
142
+ const cached = loadedModules.get(resolved);
143
+ if (cached) return cached;
144
+
145
+ const loading = (async () => {
146
+ if (!existsSync(resolved)) {
147
+ throw new Error(`memory provider module "${entry}" does not exist (resolved: ${resolved})`);
148
+ }
149
+ const violations = auditExtensionSource(readFileSync(resolved, "utf8"), `memory provider "${entry}"`);
150
+ if (violations.length > 0) {
151
+ throw new Error(violations.map((v) => `criterion ${v.criterion}: ${v.reason}`).join("; "));
152
+ }
153
+ const mod = (await import(pathToFileURL(resolved).href)) as MemoryProviderModule<ExtensionAPI>;
154
+ const provider = assertProviderShape(mod.default, `memory provider "${entry}"`);
155
+ registerMemoryProvider(provider);
156
+ return provider;
157
+ })();
158
+
159
+ loadedModules.set(resolved, loading);
160
+ try {
161
+ return await loading;
162
+ } catch (error) {
163
+ // A failed load must not poison the cache: fixing the file and retrying is
164
+ // the normal path during development.
165
+ loadedModules.delete(resolved);
166
+ throw error;
167
+ }
168
+ }
169
+
170
+ export function listMemoryProviders(): Array<{ id: string; version: string; default: boolean }> {
171
+ return [...registry.values()].map((provider) => ({
172
+ id: provider.id,
173
+ version: provider.version,
174
+ default: provider.id === DEFAULT_MEMORY_PROVIDER_ID,
175
+ }));
176
+ }
177
+
178
+ export function resolveMemoryProvider(id: string | undefined): MemoryProvider<ExtensionAPI> {
179
+ const wanted = id ?? DEFAULT_MEMORY_PROVIDER_ID;
180
+ const provider = registry.get(wanted);
181
+ if (!provider) {
182
+ throw new Error(
183
+ `unknown memory provider "${wanted}" — available: ${[...registry.keys()].join(", ")}`,
184
+ );
185
+ }
186
+ return provider;
187
+ }