@lqc123qwe/car-runtime 1.13.0 → 1.14.1

package/src/load/config.ts

@@ -35,12 +35,59 @@ export interface SandboxSigConfig {
   sigTrustRoot?: string
 }
 
+export interface CompactionConfig {
+  /** 缺省 false = 行为零变化（1.13 兼容线） */
+  enabled?: boolean
+  /** 距上次压缩的新增事件数阈值（事实计数非估算）；缺省 200 */
+  thresholdEvents?: number
+  /** 保护最近 N 个 turn 不折叠；缺省 4 */
+  protectLastTurns?: number
+}
+
 export interface LlmConfig {
   baseUrl?: string
   model?: string
   adapterId?: string
   maxTokens?: number
   allowEnvFallback?: boolean
+  /** 1.14-S2（K-MP-2 / D-40）：历史压缩策略（阈值自动触发判定入参；立即压缩 API 独立可用） */
+  compaction?: CompactionConfig
+}
+
+/** 1.14-S4（K-POOL-1 / D-42）：模型池端点登记（多端点 fallback 候选；凭据仅收 keyEnv 引用） */
+export interface ModelPoolEndpointSpec {
+  /** 端点标识（routing/decide 落链定位；缺省 ep-1..N 派生；重复显式拒绝） */
+  id?: string
+  baseUrl: string
+  model: string
+  /** 适配器家族（config 可装配集 = 内置两族；缺省 openai-compat） */
+  adapterId?: 'openai-compat' | 'anthropic'
+  /** 凭据 env 变量名引用（明文 key 显式拒绝——CR-05；缺省按 adapterId 缺省表 + CAR_LLM_API_KEY） */
+  keyEnv?: string
+  /** 优先级：数值越小越优先（缺省 0） */
+  priority?: number
+  /** 同优先级内次序：越大越先（缺省 0——D-42：登记生效为排序 tie-break，不做负载均衡调度） */
+  weight?: number
+  /** 成员级 maxTokens（缺省回落 llm.maxTokens） */
+  maxTokens?: number
+}
+
+/** 1.14-S4（K-POOL-1 / D-42）：health 预检策略（doctor 面同款口径——值不打印） */
+export interface ModelPoolProbeConfig {
+  /** 缺省开；不可达端点按序跳过（fail-visible 落 routing/decide attempts） */
+  enabled?: boolean
+  /** 单端点探测超时（缺省 4000ms） */
+  timeoutMs?: number
+  /** 探测结果缓存 TTL（缺省 30000ms；0 = 每请求重探） */
+  ttlMs?: number
+}
+
+/** 1.14-S4（K-POOL-1 / D-42）：模型池登记。与 llm.baseUrl/model/adapterId 并存时池装配压过（每次路由决策落链可解释）；llm.maxTokens/allowEnvFallback/compaction 仍生效。无 modelPool 配置 = 行为与 1.13 逐字节一致（兼容验收线） */
+export interface ModelPoolConfig {
+  endpoints: ModelPoolEndpointSpec[]
+  probe?: ModelPoolProbeConfig
+  /** 候选请求尝试上限（含首选；缺省 = 端点数） */
+  maxAttempts?: number
 }
 
 export interface McpServerSpec {
@@ -59,6 +106,8 @@ export interface CarConfig {
   sandbox?: SandboxSigConfig
   /** 1.4-S3（D-16）：模型接入配置键位空间；凭据禁入（CR-05）——只放端点/模型名/开关 */
   llm?: LlmConfig
+  /** 1.14-S4（K-POOL-1 / D-42）：模型池登记（多端点 fallback；与 llm.* 并存时池压过，路由决策落链） */
+  modelPool?: ModelPoolConfig
   /** 1.4-S7（D-18）：MCP server 登记面（--mcp <id> 显式启用） */
   mcp?: { servers: Record<string, McpServerSpec> }
 }
@@ -82,6 +131,66 @@ const nonEmptyTrimmed = () =>
 const stringMap = () =>
   z.record(z.string(), z.string({ invalid_type_error: '必须为字符串' }), { invalid_type_error: '必须为字符串映射', required_error: '必须为字符串映射' })
 
+// 1.14-S4（K-POOL-1）辅助：正整数 / 非负整数
+const positiveInt = () =>
+  z.number({ invalid_type_error: '必须为正整数', required_error: '必须为正整数' })
+    .refine(v => Number.isFinite(v) && Number.isInteger(v) && v > 0, { message: '必须为正整数' })
+const nonNegativeInt = () =>
+  z.number({ invalid_type_error: '必须为非负整数', required_error: '必须为非负整数' })
+    .refine(v => Number.isFinite(v) && Number.isInteger(v) && v >= 0, { message: '必须为非负整数' })
+
+// 明文凭据键黑名单（1.14-S4 / CR-05）：专用文案先于未知键检查（首个 issue 渲染）
+const PLAINTEXT_CRED_KEYS = ['key', 'apiKey', 'api_key', 'apikey', 'token', 'password']
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/
+const POOL_ENDPOINT_KEYS = new Set(['id', 'baseUrl', 'model', 'adapterId', 'keyEnv', 'priority', 'weight', 'maxTokens'])
+
+/**
+ * 池端点 schema（1.14-S4）：passthrough + superRefine 显式拒绝（等价 strict，但明文凭据键
+ * 给专用文案——CR-05 红线「明文 key 显式拒绝」必须可读可引导，不能只报「未知键」）。
+ */
+const poolEndpointSchema = z.object({
+  id: nonEmptyTrimmed().optional(),
+  baseUrl: nonEmptyTrimmed().refine(v => /^https?:\/\//.test(v), { message: '必须为 http(s) URL' }),
+  model: nonEmptyTrimmed(),
+  adapterId: z.enum(['openai-compat', 'anthropic'], { errorMap: () => ({ message: '必须为 openai-compat 或 anthropic（config 可装配集 = 内置两族）' }) }).optional(),
+  keyEnv: nonEmptyTrimmed().refine(v => ENV_NAME_RE.test(v), { message: '必须为环境变量名（明文凭据禁入——凭据仅收 keyEnv 引用，CR-05）' }).optional(),
+  priority: positiveInt().optional(),
+  weight: nonNegativeInt().optional(),
+  maxTokens: positiveInt().optional(),
+}).passthrough().superRefine((obj, ctx) => {
+  for (const k of PLAINTEXT_CRED_KEYS) {
+    if (k in obj) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: [k], message: `明文凭据禁入——凭据仅收 keyEnv（环境变量名引用），明文键 "${k}" 一律拒绝` })
+      return
+    }
+  }
+  for (const k of Object.keys(obj)) {
+    if (!POOL_ENDPOINT_KEYS.has(k)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: [k], message: '未登记键（登记键位：id/baseUrl/model/adapterId/keyEnv/priority/weight/maxTokens）' })
+      return
+    }
+  }
+})
+
+const modelPoolSchema = z.object({
+  endpoints: z.array(poolEndpointSchema, { invalid_type_error: '必须为端点数组', required_error: '必须为端点数组' })
+    .min(1, { message: '至少登记一个端点（池空 = CAR-E-CONFIG；无池需求请移除 modelPool 键，行为与 1.13 一致）' }),
+  probe: z.object({
+    enabled: z.boolean({ invalid_type_error: '必须为布尔', required_error: '必须为布尔' }).optional(),
+    timeoutMs: positiveInt().optional(),
+    ttlMs: nonNegativeInt().optional(),
+  }).strict().optional(),
+  maxAttempts: positiveInt().optional(),
+}).strict().superRefine((obj, ctx) => {
+  // 端点 id 唯一（缺省派生同口径）——routing/decide 落链定位歧义禁入
+  const ids = new Set<string>()
+  for (const [i, ep] of (obj.endpoints ?? []).entries()) {
+    const id = ep.id ?? `ep-${i + 1}`
+    if (ids.has(id)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['endpoints', i], message: `端点 id "${id}" 重复（落链定位歧义，禁静默）` })
+    ids.add(id)
+  }
+})
+
 const mcpServerSchema = z.object({
   command: nonEmptyTrimmed().optional(),
   url: nonEmptyTrimmed().refine(v => /^https?:\/\//.test(v), { message: '必须为 http(s) URL' }).optional(),
@@ -118,14 +227,24 @@ const rawSchema = z.object({
       .refine(v => Number.isFinite(v) && Number.isInteger(v) && v > 0, { message: '必须为正整数' })
       .optional(),
     allowEnvFallback: z.boolean({ invalid_type_error: '必须为布尔', required_error: '必须为布尔' }).optional(),
+    // 1.14-S2（K-MP-2 / D-40）：历史压缩策略（阈值事实计数，非 token 估算）
+    compaction: z.object({
+      enabled: z.boolean({ invalid_type_error: '必须为布尔', required_error: '必须为布尔' }).optional(),
+      thresholdEvents: z.number({ invalid_type_error: '必须为正整数', required_error: '必须为正整数' })
+        .refine(v => Number.isInteger(v) && v > 0, { message: '必须为正整数' }).optional(),
+      protectLastTurns: z.number({ invalid_type_error: '必须为正整数', required_error: '必须为正整数' })
+        .refine(v => Number.isInteger(v) && v > 0, { message: '必须为正整数' }).optional(),
+    }).strict().optional(),
   }).strict().optional(),
+  // 1.14-S4（K-POOL-1 / D-42）：模型池登记（多端点 fallback + health + routing/decide 落链）
+  modelPool: modelPoolSchema.optional(),
   mcp: z.object({
     servers: z.record(z.string(), mcpServerSchema, { invalid_type_error: '必须为对象（serverId → 启动规格）' }),
   }).strict().optional(),
 }, { invalid_type_error: '配置顶层必须为 JSON 对象' }).strict()
 
 /** 未登记键提示（渲染层拼 path）——与系统设计键位空间同步 */
-const KEY_SPACES = '登记键位：sandbox.* / llm.* / mcp.servers.*'
+const KEY_SPACES = '登记键位：sandbox.* / llm.* / llm.modelPool.* / mcp.servers.*'
 
 /** zod issue → CAR-E-CONFIG 渲染（首个 issue；unrecognized_keys 按键路径展开） */
 function renderIssue(error: z.ZodError): string {
@@ -161,6 +280,13 @@ function parseCarConfig(raw: unknown): { config: CarConfig; error?: string } {
     if (d.llm.adapterId !== undefined) llm.adapterId = d.llm.adapterId
     if (d.llm.maxTokens !== undefined) llm.maxTokens = d.llm.maxTokens
     if (d.llm.allowEnvFallback !== undefined) llm.allowEnvFallback = d.llm.allowEnvFallback
+    if (d.llm.compaction) {
+      const cp: CompactionConfig = {}
+      if (d.llm.compaction.enabled !== undefined) cp.enabled = d.llm.compaction.enabled
+      if (d.llm.compaction.thresholdEvents !== undefined) cp.thresholdEvents = d.llm.compaction.thresholdEvents
+      if (d.llm.compaction.protectLastTurns !== undefined) cp.protectLastTurns = d.llm.compaction.protectLastTurns
+      llm.compaction = cp
+    }
     out.llm = llm
   }
   if (d.mcp) {
@@ -176,6 +302,14 @@ function parseCarConfig(raw: unknown): { config: CarConfig; error?: string } {
     }
     out.mcp = { servers }
   }
+  if (d.modelPool) {
+    const mp = d.modelPool as { endpoints: ModelPoolEndpointSpec[]; probe?: ModelPoolProbeConfig; maxAttempts?: number }
+    out.modelPool = {
+      endpoints: mp.endpoints.map(ep => ({ ...ep })),
+      ...(mp.probe ? { probe: { ...mp.probe } } : {}),
+      ...(mp.maxAttempts !== undefined ? { maxAttempts: mp.maxAttempts } : {}),
+    }
+  }
   return { config: out }
 }
 

package/src/load/pool.ts

@@ -0,0 +1,339 @@
+/**
+ * 1.14-S4 · K-POOL-1 模型池网关（D-42：登记 + health 探测 + fallback 链 + retry 策略 + routing/decide 落链）
+ *
+ * 口径：
+ *  - 候选序 = priority 升序（缺省 0）→ weight 降序（缺省 0；D-42：weight 仅作排序 tie-break，
+ *    不做负载均衡调度）→ 登记序（稳定排序）；
+ *  - health 预检（doctor 面同款口径——值不打印）：GET {baseUrl}/models（openai）/
+ *    {baseUrl}/v1/models（anthropic）；**任意 HTTP 状态码 = 传输可达（健康）**——404/401 ≠ 不健康
+ *    （真实连通性以发消息为准，doctor 先例）；网络层失败/超时 = 不健康（按序跳过，fail-visible
+ *    落 routing/decide attempts）；结果 TTL 缓存（防死主端点每请求烧重试预算）；probeImpl 测试注入缝；
+ *  - fallback 链 = **首块前失败才可降级**（已消费 chunk 不可重放——llm.ts §3.5.4 同红线）：
+ *    成员请求抛错（网络/429/5xx 重试耗尽/凭据缺失）或首 chunk 即 error chunk（4xx 业务错，零内容
+ *    消费）→ 按序降级下一候选；流中途失败 = error chunk 原样收口不降级；
+ *  - retry 策略 = 成员级重试（§3.5.4 基线，装配层透传）+ 池级 maxAttempts 候选请求尝试上限
+ *    （缺省 = 端点数；耗尽 = providerUnreachable B080001——runTurn 以 error 收口）；
+ *  - **routing/decide 审计事件**：每次决策一条（payload.type='decide'：selected/reason/retries/
+ *    attempts）——onDecide 回调由宿主接线 SessionLog.append（事件链只追加红线；禁静默换模型）；
+ *    retries = 发起请求且失败的候选数（健康跳过不计，attempts 全量在册）；
+ *  - 成员请求 req.model/maxTokens 按成员改写（成员适配器消费自身 model——usage 按成员模型落账）；
+ *  - 无池配置 = 行为与 1.13 逐字节一致（兼容验收线——池路由零介入）；
+ *  - 明文凭据红线：成员凭据仅收 keyEnv env 变量名引用（config schema 明文键显式拒绝，CR-05）。
+ */
+import { request as httpRequest } from 'node:http'
+import { request as httpsRequest } from 'node:https'
+import type { ModelPoolConfig } from './config.ts'
+import { createAnthropicAdapter, createOpenAICompatAdapter } from '../runtime-core/llm.ts'
+import { CredentialService } from '../runtime-core/credentials.ts'
+import { providerUnreachable } from '../runtime-core/errors.ts'
+import type { LlmAdapter, LlmChunk, LlmRequest } from '../runtime-core/types.ts'
+
+/** 池成员（解析后形态——id 缺省已派生；候选序已定） */
+export interface PoolMember {
+  id: string
+  baseUrl: string
+  model: string
+  adapterId: 'openai-compat' | 'anthropic'
+  keyEnv?: string
+  maxTokens?: number
+  priority?: number
+  weight?: number
+}
+
+/** 候选序：priority 升序（缺省 0）→ weight 降序（缺省 0，D-42 tie-break）→ 登记序（稳定） */
+export function orderPoolMembers(members: PoolMember[]): PoolMember[] {
+  return members
+    .map((m, i) => ({ m, i }))
+    .sort((a, b) => (a.m.priority ?? 0) - (b.m.priority ?? 0) || (b.m.weight ?? 0) - (a.m.weight ?? 0) || a.i - b.i)
+    .map(x => x.m)
+}
+
+/** config modelPool → 池成员（id 缺省 ep-1..N 派生；重复 id 显式拒绝；候选序就位） */
+export function resolveModelPoolMembers(pool: ModelPoolConfig): { members: PoolMember[]; error?: string } {
+  const seen = new Set<string>()
+  const members: PoolMember[] = []
+  for (const [i, ep] of pool.endpoints.entries()) {
+    const id = ep.id ?? `ep-${i + 1}`
+    if (seen.has(id)) {
+      return { members: [], error: `CAR-E-CONFIG: 模型池端点 id "${id}" 重复（routing/decide 落链定位歧义禁入）` }
+    }
+    seen.add(id)
+    members.push({
+      id,
+      baseUrl: ep.baseUrl,
+      model: ep.model,
+      adapterId: ep.adapterId ?? 'openai-compat',
+      ...(ep.keyEnv !== undefined ? { keyEnv: ep.keyEnv } : {}),
+      ...(ep.maxTokens !== undefined ? { maxTokens: ep.maxTokens } : {}),
+      ...(ep.priority !== undefined ? { priority: ep.priority } : {}),
+      ...(ep.weight !== undefined ? { weight: ep.weight } : {}),
+    })
+  }
+  return { members: orderPoolMembers(members) }
+}
+
+// ==================== health 预检（doctor 面同款口径） ====================
+
+export interface PoolMemberHealth {
+  /** 传输可达（任意 HTTP 状态码）= true；网络层失败/超时 = false */
+  ok: boolean
+  status?: number
+  latencyMs: number
+  /** 不健康原因类别（值不打印纪律——只出类别） */
+  errorCategory?: string
+}
+
+/** node:http(s) GET 状态码（1.8-BUG-1 出站通道口径——全局 fetch/undici win32 退出断言预防） */
+function httpGetStatus(url: string, signal: AbortSignal): Promise<number> {
+  return new Promise((resolve, reject) => {
+    try {
+      const u = new URL(url)
+      const mod = u.protocol === 'https:' ? httpsRequest : httpRequest
+      const req = mod(u, { method: 'GET', headers: { accept: 'application/json' } }, res => {
+        res.resume() // 排干 body——连接收口
+        resolve(res.statusCode ?? 0)
+      })
+      const onAbort = () => { try { req.destroy(new Error('aborted')) } catch { /* 已完成 */ } }
+      if (signal.aborted) onAbort()
+      else signal.addEventListener('abort', onAbort, { once: true })
+      req.on('error', reject)
+      req.end()
+    } catch (e) { reject(e) }
+  })
+}
+
+/** 单端点 health 探测（doctor/池预检复用；值不打印——只出状态/延迟/类别） */
+export async function probePoolMember(
+  member: Pick<PoolMember, 'baseUrl' | 'adapterId'>,
+  opts: { timeoutMs?: number } = {},
+): Promise<PoolMemberHealth> {
+  const base = member.baseUrl.replace(/\/+$/, '')
+  const url = member.adapterId === 'anthropic' ? `${base}/v1/models` : `${base}/models`
+  const t0 = Date.now()
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 4000)
+  try {
+    const status = await httpGetStatus(url, controller.signal)
+    return { ok: true, status, latencyMs: Date.now() - t0 }
+  } catch (e) {
+    const aborted = (e as Error).name === 'AbortError' || String((e as Error).message).includes('aborted')
+    return { ok: false, latencyMs: Date.now() - t0, errorCategory: aborted ? 'timeout' : 'network-error' }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// ==================== 路由引擎（fallback 链 + retry 上限 + routing/decide） ====================
+
+/** 逐候选结果（attempts 全量在册——健康跳过与请求失败都显性化） */
+export interface RoutingAttempt {
+  id: string
+  outcome: 'selected' | 'failed' | 'skipped-unhealthy'
+  /** 失败/跳过类别（错误码/名称，值不打印） */
+  detail?: string
+}
+
+/** 路由决策（routing/decide 事件 payload 源——每次请求一条） */
+export interface RoutingDecision {
+  /** 选中端点 id（耗尽 = null） */
+  selected: string | null
+  /** 首位候选选中 = primary；降级选中 = fallback；全部不可用 = exhausted */
+  reason: 'primary' | 'fallback' | 'exhausted'
+  /** 降级重试次数 = 发起请求且失败的候选数（健康跳过不计——attempts 全量在册） */
+  retries: number
+  attempts: RoutingAttempt[]
+  turnId?: string
+  sessionId?: string
+}
+
+export interface PoolAdapterOptions {
+  id?: string
+  /** 成员与适配器（装配层产出的候选序） */
+  members: Array<{ member: PoolMember; adapter: LlmAdapter }>
+  /** health 预检（enabled 缺省 true；probeImpl 测试注入缝——缺省真实 GET 探测） */
+  probe?: { enabled?: boolean; timeoutMs?: number; ttlMs?: number; probeImpl?: typeof probePoolMember }
+  /** 候选请求尝试上限（缺省 = 成员数） */
+  maxAttempts?: number
+  /** routing/decide 审计回调（宿主接线 SessionLog.append——禁静默换模型红线） */
+  onDecide?: (d: RoutingDecision) => void
+}
+
+const errorCategory = (e: unknown): string => {
+  const err = e as { slug?: string; name?: string }
+  return err.slug ?? err.name ?? 'unknown'
+}
+
+export function createModelPoolAdapter(opts: PoolAdapterOptions): LlmAdapter & { id: string; members: PoolMember[] } {
+  const ordered = opts.members
+  const maxAttempts = opts.maxAttempts ?? ordered.length
+  const probeEnabled = opts.probe?.enabled !== false
+  const probeFn = opts.probe?.probeImpl ?? probePoolMember
+  const probeTimeoutMs = opts.probe?.timeoutMs ?? 4000
+  const ttlMs = opts.probe?.ttlMs ?? 30_000
+  const healthCache = new Map<string, { ok: boolean; at: number; category?: string }>()
+  const id = opts.id ?? 'model-pool'
+
+  const healthOf = async (m: PoolMember): Promise<{ ok: boolean; category?: string }> => {
+    const hit = healthCache.get(m.id)
+    if (hit && Date.now() - hit.at < ttlMs) {
+      return { ok: hit.ok, ...(hit.category !== undefined ? { category: hit.category } : {}) }
+    }
+    const h = await probeFn(m, { timeoutMs: probeTimeoutMs })
+    const entry = { ok: h.ok, at: Date.now(), ...(h.errorCategory !== undefined ? { category: h.errorCategory } : {}) }
+    healthCache.set(m.id, entry)
+    return { ok: entry.ok, ...(entry.category !== undefined ? { category: entry.category } : {}) }
+  }
+
+  const withMeta = (d: Omit<RoutingDecision, 'turnId' | 'sessionId'>, req: LlmRequest): RoutingDecision => ({
+    ...d,
+    ...(req.metadata?.turnId !== undefined ? { turnId: req.metadata.turnId } : {}),
+    ...(req.metadata?.sessionId !== undefined ? { sessionId: req.metadata.sessionId } : {}),
+  })
+
+  return {
+    id,
+    members: ordered.map(x => x.member),
+    chat(req: LlmRequest): AsyncIterable<LlmChunk> {
+      return (async function* () {
+        const attempts: RoutingAttempt[] = []
+        let failedCount = 0
+        let requestAttempts = 0
+        for (const [pos, entry] of ordered.entries()) {
+          if (requestAttempts >= maxAttempts) break
+          if (probeEnabled) {
+            const h = await healthOf(entry.member)
+            if (!h.ok) {
+              attempts.push({ id: entry.member.id, outcome: 'skipped-unhealthy', ...(h.category !== undefined ? { detail: h.category } : {}) })
+              continue
+            }
+          }
+          requestAttempts++
+          // 成员请求：req.model/maxTokens 按成员改写（usage 按成员模型落账）
+          let it: AsyncIterator<LlmChunk>
+          try {
+            it = entry.adapter.chat({
+              ...req,
+              model: entry.member.model,
+              ...(entry.member.maxTokens != null ? { maxTokens: entry.member.maxTokens } : {}),
+            })[Symbol.asyncIterator]()
+          } catch (e) {
+            // 适配器同步抛错（契约违规/装配错误）= 候选不可用，降级下一候选
+            attempts.push({ id: entry.member.id, outcome: 'failed', detail: errorCategory(e) })
+            failedCount++
+            continue
+          }
+          try {
+            let first: IteratorResult<LlmChunk>
+            try {
+              first = await it.next()
+            } catch (e) {
+              // 首块前失败（网络/429/5xx 重试耗尽/凭据缺失）→ 降级下一候选
+              attempts.push({ id: entry.member.id, outcome: 'failed', detail: errorCategory(e) })
+              failedCount++
+              continue
+            }
+            if (first.done || !first.value) {
+              attempts.push({ id: entry.member.id, outcome: 'failed', detail: 'empty-stream' })
+              failedCount++
+              continue
+            }
+            const fc = first.value
+            // 首 chunk 即 error chunk 且零内容消费（4xx 业务错）→ 候选不可用，降级（零 chunk 已出——可重放安全）
+            const errorOnly = fc.finishReason === 'error' && fc.delta === undefined && fc.toolCallDelta === undefined
+            if (errorOnly) {
+              attempts.push({ id: entry.member.id, outcome: 'failed', detail: fc.error ? 'http-4xx' : 'error-chunk' })
+              failedCount++
+              continue
+            }
+            // 选中：routing/decide 落链（禁静默换模型——选中端点/原因/重试次数显性化）
+            attempts.push({ id: entry.member.id, outcome: 'selected' })
+            opts.onDecide?.(withMeta({
+              selected: entry.member.id,
+              reason: pos === 0 ? 'primary' : 'fallback',
+              retries: failedCount,
+              attempts,
+            }, req))
+            yield fc
+            while (true) {
+              const r = await it.next()
+              if (r.done) break
+              yield r.value // 流中途失败 = error chunk 原样收口（已消费 chunk 不可重放——不降级）
+            }
+            return
+          } finally {
+            // 成员迭代器收口（首 chunk 后未耗尽路径——4xx 降级/取消/异常；自然结束路径 no-op）
+            await it.return?.(undefined)
+          }
+        }
+        // 耗尽：决策落链 + B080001（runTurn error 收口——BD-04）
+        opts.onDecide?.(withMeta({ selected: null, reason: 'exhausted', retries: failedCount, attempts }, req))
+        const summary = attempts.map(a => `${a.id}:${a.outcome}${a.detail ? `(${a.detail})` : ''}`).join(', ') || '无候选'
+        throw providerUnreachable(`模型池全部候选不可用（${summary}）`)
+      })()
+    },
+  }
+}
+
+// ==================== 池装配层（config → 成员适配器 → 路由适配器） ====================
+
+export interface ModelPoolAssemblyOptions {
+  pool: ModelPoolConfig
+  /** 共享凭据服务（成员级 keyEnv 经 credentialEnvVars 精确候选） */
+  credentials?: CredentialService
+  /** 测试注入（成员适配器 fetch/退避——缺省真实通道） */
+  fetchImpl?: typeof fetch
+  timeoutMs?: number
+  firstByteMs?: number
+  retries?: number
+  backoffMs?: number[]
+  sleep?: (ms: number) => Promise<void>
+  /** routing/decide 审计回调（透传路由引擎） */
+  onDecide?: (d: RoutingDecision) => void
+}
+
+/** 池装配：config 解析（候选序/重复拒绝）→ 成员适配器（内置两族 + keyEnv）→ 路由适配器 */
+export function assembleModelPool(opts: ModelPoolAssemblyOptions): {
+  adapter: LlmAdapter & { id: string; members: PoolMember[] }
+  members: PoolMember[]
+} {
+  const { members, error } = resolveModelPoolMembers(opts.pool)
+  if (error) throw new Error(error)
+  const entries = members.map(m => ({
+    member: m,
+    adapter: (m.adapterId === 'anthropic'
+      ? createAnthropicAdapter({
+          baseUrl: m.baseUrl,
+          credentials: opts.credentials,
+          ...(m.keyEnv !== undefined ? { credentialEnvVars: [m.keyEnv] } : {}),
+          ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+          ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+          ...(opts.firstByteMs !== undefined ? { firstByteMs: opts.firstByteMs } : {}),
+          ...(opts.retries !== undefined ? { retries: opts.retries } : {}),
+          ...(opts.backoffMs !== undefined ? { backoffMs: opts.backoffMs } : {}),
+          ...(opts.sleep ? { sleep: opts.sleep } : {}),
+        })
+      : createOpenAICompatAdapter({
+          baseUrl: m.baseUrl,
+          credentials: opts.credentials,
+          provider: 'openai-compat',
+          ...(m.keyEnv !== undefined ? { credentialEnvVars: [m.keyEnv] } : {}),
+          ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+          ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+          ...(opts.firstByteMs !== undefined ? { firstByteMs: opts.firstByteMs } : {}),
+          ...(opts.retries !== undefined ? { retries: opts.retries } : {}),
+          ...(opts.backoffMs !== undefined ? { backoffMs: opts.backoffMs } : {}),
+          ...(opts.sleep ? { sleep: opts.sleep } : {}),
+        })),
+  }))
+  const adapter = createModelPoolAdapter({
+    members: entries,
+    probe: {
+      ...(opts.pool.probe?.enabled !== undefined ? { enabled: opts.pool.probe.enabled } : {}),
+      ...(opts.pool.probe?.timeoutMs !== undefined ? { timeoutMs: opts.pool.probe.timeoutMs } : {}),
+      ...(opts.pool.probe?.ttlMs !== undefined ? { ttlMs: opts.pool.probe.ttlMs } : {}),
+    },
+    ...(opts.pool.maxAttempts !== undefined ? { maxAttempts: opts.pool.maxAttempts } : {}),
+    ...(opts.onDecide ? { onDecide: opts.onDecide } : {}),
+  })
+  return { adapter, members }
+}

package/src/loop/stop.ts

@@ -72,12 +72,13 @@ export class TurnAborted extends Error {
  * 在 JSONL，聚合由事实行求和而非运行时状态；字段非数值容错跳过不吞计数）。无 usage 事件
  * 返回 undefined → turnEnd meta 不带 usage 键（缺省=未采集，旧格式向后兼容）。
  */
-function turnUsageFrom(log: SessionLog, turnId: string): { input: number; output: number; cacheRead: number; cacheCreation: number; requests: number } | undefined {
+function turnUsageFrom(log: SessionLog, turnId: string): { input: number; output: number; cacheRead: number; cacheCreation: number; requests: number; segments?: { reasoningTokens: number } } | undefined {
   let input = 0
   let output = 0
   let cacheRead = 0
   let cacheCreation = 0
   let requests = 0
+  let reasoning: number | undefined
   for (const e of log.events) {
     if (e.kind !== 'usage' || e.turnId !== turnId) continue
     const p = (e.payload ?? {}) as Record<string, unknown>
@@ -85,9 +86,14 @@ function turnUsageFrom(log: SessionLog, turnId: string): { input: number; output
     if (typeof p.output === 'number') output += p.output
     if (typeof p.cacheRead === 'number') cacheRead += p.cacheRead
     if (typeof p.cacheCreation === 'number') cacheCreation += p.cacheCreation
+    // 1.14-S3（K-MP-2b / D-41）：分段聚合——任一请求携带 segments.reasoningTokens 即求和；
+    // 全 turn 无分段事实 = meta.usage 不带 segments 键（禁估算补造）
+    const seg = (p.segments ?? null) as { reasoningTokens?: unknown } | null
+    if (seg && typeof seg.reasoningTokens === 'number') reasoning = (reasoning ?? 0) + seg.reasoningTokens
     requests++
   }
-  return requests ? { input, output, cacheRead, cacheCreation, requests } : undefined
+  if (!requests) return undefined
+  return { input, output, cacheRead, cacheCreation, requests, ...(reasoning !== undefined ? { segments: { reasoningTokens: reasoning } } : {}) }
 }
 
 export async function runTurn(opts: {

package/src/runtime-core/chatStep.ts

@@ -37,6 +37,12 @@ export interface ChatStepOptions {
   adapterId?: string
   /** 1.4-S4（D-19）：turn 取消信号——chunk 间隙与流结束后（finish 检查前）检查，命中抛 TurnAborted */
   signal?: { aborted: boolean }
+  /**
+   * 1.14.1（K-MP-1 消费面 / D-39）：思考参数透传——chatStep 是宿主 model 回调的唯一路径，
+   * 本形参补齐后 reasoning 才经 chatStep 可达（off / 缺席 = 不下发该字段，字节面零痕迹）；
+   * 模型元数据思考档位判断在宿主侧（models:meta），内核防线 = 未知档位 fail-visible。
+   */
+  reasoning?: { effort: 'off' | 'low' | 'medium' | 'high' }
 }
 
 /** ModelStep 加法扩展：脱敏计数留痕（S15 secretsRedacted 同名口径） */
@@ -78,6 +84,8 @@ export async function chatStep(opts: ChatStepOptions): Promise<ChatStepResult> {
     tools,
     ...(maxTokens != null ? { maxTokens } : {}),
     ...(adapterId ? { adapterId } : {}),
+    // 1.14.1（K-MP-1 消费面）：reasoning 透传（off/缺席 = 不下发）
+    ...(opts.reasoning ? { reasoning: opts.reasoning } : {}),
     ...(opts.signal ? { signal: opts.signal } : {}),
     ...(opts.log.sessionId ? { metadata: { sessionId: opts.log.sessionId, turnId, traceId: `${opts.log.sessionId}:${turnId}` } } : {}),
   })
@@ -117,6 +125,8 @@ export async function chatStep(opts: ChatStepOptions): Promise<ChatStepResult> {
       output: usage.outputTokens,
       cacheRead: usage.cacheReadTokens,
       cacheCreation: usage.cacheCreationTokens,
+      // 1.14-S3（K-MP-2b / D-41）：分段事实随事件落链——无分段 = 不带键（禁估算）
+      ...(usage.segments ? { segments: usage.segments } : {}),
       providerRaw: usage.providerRaw,
     })
   }

package/src/runtime-core/credentials.ts

@@ -28,6 +28,8 @@ export interface CredentialResolveOptions {
   keychainReader?: (service: string) => string | null
   /** reveal 审计回调（值不入参——审计全量留痕但零明文） */
   audit?: (event: { action: 'resolve' | 'reveal'; provider: string; source: CredentialSource; origin: string }) => void
+  /** 1.14-S4（K-POOL-1）：显式 env 变量候选（modelPool keyEnv 精确引用——替代 provider 缺省表；keychain 链保持在前） */
+  envVarCandidates?: string[]
 }
 
 /** provider → 候选 env 变量（按序检索；CAR_LLM_API_KEY 为通用兜底） */
@@ -107,7 +109,8 @@ export class CredentialService {
 
     const allowEnv = opts.allowEnvFallback === true || env.CAR_ALLOW_ENV_CREDENTIALS === '1'
     if (allowEnv) {
-      const candidates = providerEnvVars(provider)
+      // 1.14-S4（K-POOL-1）：显式候选（keyEnv 精确引用）压过 provider 缺省表——用户点名变量即显式意见
+      const candidates = opts.envVarCandidates?.length ? opts.envVarCandidates : providerEnvVars(provider)
       for (const name of candidates) {
         searched.push(`env:${name}`)
         if (env[name]) {