@lqc123qwe/car-runtime 1.0.0 → 1.2.0

package/src/load/config.ts

@@ -0,0 +1,129 @@
+/**
+ * 1.1-S3 · 签名配置文件通道（sandbox.* 键位空间；部署设计 §4.5.5 载体落地）
+ *
+ * 口径：
+ *  - 载体 = car.config.json（D-11a ①，2026-09-27 裁决：零依赖 / 免代码求值 / fail-visible 简单；
+ *    系统设计 §3.2 的 car.config.ts + zod configLoader 完整形态登记后续，届时迁移并保持键位兼容）
+ *  - 键位空间（嵌套 JSON 渲染点分键名）：
+ *      sandbox.unsigned.allow  （部署设计 §4.5.5 冻结键；= CAR_UNSIGNED_ALLOW 等价通道）
+ *      sandbox.sig.enforce     （= CAR_SIG_ENFORCE）
+ *      sandbox.sig.trustRoot   （= CAR_TRUST_ROOT；ed25519 公钥非凭据——CR-05「凭据禁入配置明文」不破）
+ *    未登记键 / 类型错 / 坏 JSON 一律 CAR-E-CONFIG 显式拒绝（fail-visible，禁静默忽略——
+ *    防拼写漂移导致的「配置写了但不生效」）
+ *  - 优先级（1.1 规划 §3 S3）：flag > env > 配置文件 > 缺省。env 已定义即为显式意见
+ *    （CAR_SIG_ENFORCE 非 '1' = 显式 warn，可压过配置 enforce；未定义才落到配置层）。
+ *    无配置文件 + 无 env 时行为与 1.0 完全一致（warn / 无信任根 / 不豁免）。
+ *  - 本模块只读配置与合并优先级；门禁判定在 sigGate/verifier。发现序：显式路径 > cwd car.config.json。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { isAbsolute, join } from 'node:path'
+import type { SignatureGateOptions } from './sigGate.ts'
+
+export const CONFIG_FILENAME = 'car.config.json'
+
+export interface SandboxSigConfig {
+  unsignedAllow?: boolean
+  sigEnforce?: boolean
+  sigTrustRoot?: string
+}
+
+export interface CarConfig {
+  sandbox?: SandboxSigConfig
+}
+
+export interface ConfigLoadResult {
+  /** 实际读取的配置文件路径（cwd 未发现时缺省——未发现是正常态非错误） */
+  path?: string
+  config: CarConfig
+  /** fail-visible：显式路径不存在 / 坏 JSON / 未登记键 / 类型错的原因（非空 = 调用方必须中止） */
+  error?: string
+}
+
+/** 加载配置：显式路径（必须存在，否则报错）或 cwd 发现（未发现 = 正常态返回空配置） */
+export function loadCarConfig(opts: { explicitPath?: string; cwd?: string } = {}): ConfigLoadResult {
+  let path: string | undefined
+  if (opts.explicitPath) {
+    path = isAbsolute(opts.explicitPath) ? opts.explicitPath : join(opts.cwd ?? process.cwd(), opts.explicitPath)
+    if (!existsSync(path)) {
+      return { path, config: {}, error: `CAR-E-CONFIG: 配置文件不存在：${path}（--config 显式指定的路径必须存在）` }
+    }
+  } else {
+    path = join(opts.cwd ?? process.cwd(), CONFIG_FILENAME)
+    if (!existsSync(path)) return { config: {} }
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf-8'))
+  } catch (e) {
+    return { path, config: {}, error: `CAR-E-CONFIG: 配置文件解析失败（${(e as Error).message}）——坏 JSON 显式拒绝，不静默忽略` }
+  }
+  const v = validate(raw)
+  return v.error ? { path, config: {}, error: v.error } : { path, config: v.config }
+}
+
+/** 手写校验（fail-visible；零依赖红线——不引 zod，D-11a ①） */
+function validate(raw: unknown): { config: CarConfig; error?: string } {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+    return { config: {}, error: 'CAR-E-CONFIG: 配置顶层必须为 JSON 对象' }
+  }
+  const out: CarConfig = {}
+  for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+    if (k !== 'sandbox') {
+      return { config: {}, error: `CAR-E-CONFIG: 未知顶层键 "${k}"（1.1 登记键位空间仅 sandbox.*）` }
+    }
+    if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+      return { config: {}, error: 'CAR-E-CONFIG: sandbox 必须为对象' }
+    }
+    const sb: SandboxSigConfig = {}
+    for (const [sk, sv] of Object.entries(v as Record<string, unknown>)) {
+      if (sk === 'unsigned') {
+        if (typeof sv !== 'object' || sv === null || Array.isArray(sv)) return { config: {}, error: 'CAR-E-CONFIG: sandbox.unsigned 必须为对象' }
+        for (const [uk, uv] of Object.entries(sv as Record<string, unknown>)) {
+          if (uk !== 'allow') return { config: {}, error: `CAR-E-CONFIG: 未知键 sandbox.unsigned.${uk}（登记键位：sandbox.unsigned.allow）` }
+          if (typeof uv !== 'boolean') return { config: {}, error: 'CAR-E-CONFIG: sandbox.unsigned.allow 必须为布尔' }
+          sb.unsignedAllow = uv
+        }
+      } else if (sk === 'sig') {
+        if (typeof sv !== 'object' || sv === null || Array.isArray(sv)) return { config: {}, error: 'CAR-E-CONFIG: sandbox.sig 必须为对象' }
+        for (const [gk, gv] of Object.entries(sv as Record<string, unknown>)) {
+          if (gk === 'enforce') {
+            if (typeof gv !== 'boolean') return { config: {}, error: 'CAR-E-CONFIG: sandbox.sig.enforce 必须为布尔' }
+            sb.sigEnforce = gv
+          } else if (gk === 'trustRoot') {
+            if (typeof gv !== 'string' || !gv.trim()) return { config: {}, error: 'CAR-E-CONFIG: sandbox.sig.trustRoot 必须为非空字符串（ed25519 spki base64）' }
+            sb.sigTrustRoot = gv.trim()
+          } else {
+            return { config: {}, error: `CAR-E-CONFIG: 未知键 sandbox.sig.${gk}（登记键位：sandbox.sig.enforce / sandbox.sig.trustRoot）` }
+          }
+        }
+      } else {
+        return { config: {}, error: `CAR-E-CONFIG: 未知 sandbox 键 "${sk}"（1.1 登记键位：sandbox.unsigned.* / sandbox.sig.*）` }
+      }
+    }
+    out.sandbox = sb
+  }
+  return { config: out }
+}
+
+/** 合并产出（mode/unsignedAllow 恒有值——比 SignatureGateOptions 的可选字段更窄，doctor 等消费方免缺省分支） */
+export interface ResolvedSignatureGate {
+  mode: 'warn' | 'enforce'
+  trustRootPublicKey?: string
+  unsignedAllow: boolean
+}
+
+/**
+ * 优先级合并（flag > env > 配置 > 缺省）：产出装载签名门选项。
+ * flagEnforce = CLI --sig-enforce；env 已定义即为显式意见（压过配置），未定义落配置层。
+ */
+export function mergeSignatureGate(env: NodeJS.ProcessEnv, cfg: CarConfig, flagEnforce?: boolean): ResolvedSignatureGate {
+  // cfg 为校验器产出的扁平形状（sandbox.{unsignedAllow,sigEnforce,sigTrustRoot}，JSON 嵌套键已拍平）
+  let mode: 'warn' | 'enforce' = cfg.sandbox?.sigEnforce === true ? 'enforce' : 'warn'
+  if (env.CAR_SIG_ENFORCE !== undefined) mode = env.CAR_SIG_ENFORCE === '1' ? 'enforce' : 'warn'
+  if (flagEnforce) mode = 'enforce'
+  let trustRootPublicKey = cfg.sandbox?.sigTrustRoot
+  if (env.CAR_TRUST_ROOT) trustRootPublicKey = env.CAR_TRUST_ROOT
+  let unsignedAllow = cfg.sandbox?.unsignedAllow === true
+  if (env.CAR_UNSIGNED_ALLOW !== undefined) unsignedAllow = env.CAR_UNSIGNED_ALLOW === '1'
+  return { mode, trustRootPublicKey: trustRootPublicKey || undefined, unsignedAllow }
+}

package/src/load/sign.ts

@@ -0,0 +1,60 @@
+/**
+ * 1.1-S1 · plugin-sign 签名原语（keygen / sign 纯函数；verify 复用 sigGate.verifyPluginFile）
+ *
+ * 口径（与 M2-S6 verifier / M5-S28 sigGate 签验同源，逐字对齐签名强制启用指南 §2）：
+ *  - 被签物 = 插件入口 .ts 文件裸字节 sha256 的 hex 串；被签消息 = hex 字符串的 UTF-8 字节
+ *    （sigGate.ts 头注释同源；哈希对裸字节求——G-11 教训：禁止对编码文本求哈希）
+ *  - 私钥 = ed25519 PKCS8 DER 文件（<前缀>.priv）；公钥 = SPKI DER base64（<前缀>.pub，
+ *    即 CAR_TRUST_ROOT 信任根值）；sidecar = `<file>.minisig` 单段 base64（sigGate 读取口径）
+ *  - 本模块只产出密钥与签名；门禁判定（warn/enforce 分级、fail-closed 分级）在 verifier/sigGate——
+ *    sign 不判门。边界登记（1.1 规划 W2-1）：minisign 离线单轨；sigstore keyless 主轨延后（1.2 候选）
+ */
+import { createHash, generateKeyPairSync, sign as cryptoSign } from 'node:crypto'
+import { readFileSync, writeFileSync } from 'node:fs'
+
+export interface SigningKeypair {
+  /** PKCS8 DER 私钥字节（写 <前缀>.priv；离线保管不入仓库——secrets 红线） */
+  privateKeyDer: Buffer
+  /** SPKI DER base64 公钥（写 <前缀>.pub；即 CAR_TRUST_ROOT 信任根值） */
+  publicKeyBase64: string
+}
+
+/** ed25519 签名密钥对生成（指南 §2 第 1 步 node -e 流程固化） */
+export function generateSigningKeypair(): SigningKeypair {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519')
+  return {
+    privateKeyDer: privateKey.export({ type: 'pkcs8', format: 'der' }) as Buffer,
+    publicKeyBase64: publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+  }
+}
+
+export interface SignResult {
+  file: string
+  sidecar: string
+  /** 文件裸字节 sha256 hex（横幅指纹与审计留痕口径同 sigGate.manifestHash） */
+  manifestHash: string
+}
+
+/** 对单文件签名并写 sidecar `<file>.minisig`（指南 §2 第 2 步 node -e 流程固化） */
+export function signPluginFile(file: string, privateKeyDer: Buffer): SignResult {
+  const manifestHash = createHash('sha256').update(readFileSync(file)).digest('hex')
+  const minisig = cryptoSign(null, Buffer.from(manifestHash), { key: privateKeyDer, format: 'der', type: 'pkcs8' }).toString('base64')
+  const sidecar = `${file}.minisig`
+  writeFileSync(sidecar, minisig)
+  return { file, sidecar, manifestHash }
+}
+
+/** 信任根解析（plugin-sign verify 用）：显式 flag > CAR_TRUST_ROOT env > <前缀>.pub 文件 */
+export function resolveTrustRoot(opts: { flag?: string; env?: NodeJS.ProcessEnv; pubFilePath?: string }): { value?: string; source: 'flag' | 'env' | 'pubfile' | 'none' } {
+  if (opts.flag) return { value: opts.flag, source: 'flag' }
+  const envVal = opts.env?.CAR_TRUST_ROOT
+  if (envVal) return { value: envVal, source: 'env' }
+  const pub = opts.pubFilePath
+  if (pub) {
+    try {
+      const v = readFileSync(pub, 'utf-8').trim()
+      if (v) return { value: v, source: 'pubfile' }
+    } catch { /* pub 文件不可读 → 视同未提供，由调用方显式报错 */ }
+  }
+  return { value: undefined, source: 'none' }
+}

package/src/runtime-core/chatStep.ts

@@ -0,0 +1,121 @@
+/**
+ * M8 · SQ-07 模型接入集成（chat → 流式消费 → assistant 落 M7 → ModelStep 交 M4 状态机）
+ *
+ * 时序对齐（§3.2.M8.4 SQ-07 逐行）：
+ *  1. 请求前断言：assertModelVisibleLogged（配合 M7，N1 不变量前置）；
+ *  2. 请求消息 = log.deriveMessages() 投影——Model-visible means logged 由构造保证
+ *     （本层不引入任何未落链的模型可见输入：新增可见输入必须新增事件类型，§3.5.5 红线；
+ *     system prompt 组装属 M4/M2 职责，v1 不在本层旁路）；
+ *  3. 凭据解析在适配器内（resolve→reveal，A080001 在首块前抛出 → runTurn catch → turn error，
+ *     用户文案引导 car doctor）；
+ *  4. 流式消费：delta 过 StreamRedactor（跨 chunk 命中不泄漏）+ toolCallDelta 聚合
+ *     （半截 JSON 不解析——ADR-001 同纪律，length 时只交 truncatedTools）；
+ *  5. assistant 文本事件落 M7（脱敏后 + secretsRedacted 计数留痕 meta）；
+ *  6. finishReason 不可变透传为 ModelStep.stopReason（error/aborted → 'error'，BD-04 收口
+ *     由 runTurn 落 turnEnd）；工具调用事件由 runTurn executeBatch 落（本层不重复）。
+ */
+import type { SessionLog } from '../session/log.ts'
+import type { ModelStep, ToolCall } from '../loop/stop.ts'
+import type { RuntimeCore } from './llm.ts'
+import type { ToolDefinition } from './types.ts'
+import { StreamRedactor } from './redaction.ts'
+import { scanSecrets } from '../security/secrets.ts'
+import { providerUnreachable } from './errors.ts'
+
+export interface ChatStepOptions {
+  core: RuntimeCore
+  log: SessionLog
+  turnId: string
+  /** 模型名（provider 侧路由） */
+  model: string
+  /** 工具声明面（ToolDefinition 含 declaredSideEffect；不出站权限面仅 schema） */
+  tools: ToolDefinition[]
+  maxTokens?: number
+  adapterId?: string
+}
+
+/** ModelStep 加法扩展：脱敏计数留痕（S15 secretsRedacted 同名口径） */
+export type ChatStepResult = ModelStep & { secretsRedacted: number }
+
+export async function chatStep(opts: ChatStepOptions): Promise<ChatStepResult> {
+  const { core, log, turnId, model, tools, maxTokens, adapterId } = opts
+
+  // 1. 请求前断言（SQ-07 #2）：N1 失守 = 带病请求，显式拒绝
+  const asserted = log.assertModelVisibleLogged()
+  if (!asserted.ok) {
+    throw new Error(`CAR-E-N1: 模型请求前快照与日志投影失配 @ atSeq=${asserted.failedAt}（Model-visible means logged 违规）`)
+  }
+
+  // 2. 请求消息 = 投影（角色系统：user/assistant/toolResult 与 LlmRequest 对齐；
+  //    assistant 工具调用以 { toolCall } content 形态原样透传——deriveMessages 投影即模型可见流）
+  const messages = log.deriveMessages().map(m => ({
+    role: m.role as 'user' | 'assistant' | 'toolResult',
+    content: m.content,
+  }))
+
+  // 4. 流式消费（3. 凭据解析在适配器首块前，A080001 由此传播）
+  const redactor = new StreamRedactor()
+  let text = ''
+  const calls = new Map<number, { id?: string; name?: string; argsBuf: string }>()
+  let stopReason: ModelStep['stopReason'] | undefined
+  let errorDetail: string | undefined
+
+  const stream = core.chat({
+    model,
+    messages,
+    tools,
+    ...(maxTokens != null ? { maxTokens } : {}),
+    ...(adapterId ? { adapterId } : {}),
+    ...(opts.log.sessionId ? { metadata: { sessionId: opts.log.sessionId, turnId, traceId: `${opts.log.sessionId}:${turnId}` } } : {}),
+  })
+  for await (const chunk of stream) {
+    if (chunk.delta !== undefined) text += redactor.push(chunk.delta)
+    if (chunk.toolCallDelta) {
+      const idx = chunk.toolCallDelta.index ?? 0
+      const cur = calls.get(idx) ?? { argsBuf: '' }
+      if (chunk.toolCallDelta.id) cur.id = chunk.toolCallDelta.id
+      if (chunk.toolCallDelta.name) cur.name = chunk.toolCallDelta.name
+      if (chunk.toolCallDelta.argumentsDelta) cur.argsBuf += chunk.toolCallDelta.argumentsDelta
+      calls.set(idx, cur)
+    }
+    if (chunk.error) errorDetail = chunk.error.message
+    if (chunk.finishReason !== undefined) stopReason = chunk.finishReason === 'aborted' ? 'error' : chunk.finishReason
+  }
+  if (stopReason === undefined) {
+    // 适配器层已保证首 finishReason（AL-05）；防御性兜底显式化
+    throw new Error('CAR-E-LLM-FINISH: 流结束无 finishReason（适配器契约违规）')
+  }
+  text += redactor.flush()
+
+  // 5. assistant 文本落 M7（脱敏后 + 计数留痕；空文本不产事件）
+  //    flush 后兜底复扫只计数不复写：流式遮蔽已生效，>0 即流式边界逃逸的审计信号
+  let secretsRedacted = 0
+  if (text.length) {
+    secretsRedacted = scanSecrets(text).hits.length
+    log.append('model', 'assistant', turnId, text, { secretsRedacted })
+  }
+
+  // 6. finishReason → ModelStep（不可变透传；length 不解析 args——ADR-001 解析前收口）
+  if (stopReason === 'length') {
+    const truncated = [...calls.values()].filter(c => c.id || c.name).map(c => ({ id: c.id ?? `tc-${c.name ?? 'unknown'}`, tool: c.name ?? 'unknown' }))
+    return { stopReason: 'length', ...(text ? { text } : {}), truncatedTools: truncated, secretsRedacted }
+  }
+  if (stopReason === 'toolUse') {
+    const toolCalls: ToolCall[] = []
+    for (const [idx, c] of [...calls.entries()].sort((a, b) => a[0] - b[0])) {
+      if (!c.name) continue
+      let args: Record<string, unknown>
+      try { args = c.argsBuf ? JSON.parse(c.argsBuf) as Record<string, unknown> : {} } catch {
+        // toolUse 声明下 args 非法 JSON = 协议违规显式化（非 length 场景无 truncatedTools 口径）
+        throw new Error(`CAR-E-LLM-PROTO: 工具调用 ${c.name} 参数非法 JSON（finishReason=${stopReason}，${errorDetail ?? '无附加错误'}）`)
+      }
+      toolCalls.push({ id: c.id ?? `tc-${idx}-${c.name}`, tool: c.name, args })
+    }
+    return { stopReason: 'toolUse', ...(text ? { text } : {}), ...(toolCalls.length ? { toolCalls } : {}), secretsRedacted }
+  }
+  // error（含 aborted 映射）：以 B080001 抛出 → runTurn catch → turnEnd error 携带 detail（BD-04 收口）
+  if (stopReason === 'error') {
+    throw providerUnreachable(errorDetail ?? 'provider 返回 error 终止（无附加说明）')
+  }
+  return { stopReason: 'stop', ...(text ? { text } : {}), secretsRedacted }
+}

package/src/runtime-core/credentials.ts

@@ -0,0 +1,135 @@
+/**
+ * M8 · 凭据门（resolveCredential ——《系统设计》§3.2.M8.2 凭据行 / SQ-07 凭据解析 / O-13）
+ *
+ * 口径：
+ *  - 解析链：OS Keychain（C-03）→ env fallback（**需用户显式开启**——§3.2.M8.3 字段表
+ *    「env 需用户显式开启 fallback」）；全落空 = CarM8Error A080001（不重试，引导 car doctor）；
+ *  - Keychain 通道按平台探测（能力探测三件套：命令在场的显式探测，缺席显式降级不静默）：
+ *    darwin = `security find-generic-password`、linux = `secret-tool`、
+ *    win32 = 零依赖读通道缺席（cmdkey 仅列举不可读值）→ 显式降级登记；
+ *  - CredentialRef 不落明文（O-13）：ref 只含 provider/source/origin；明文经 reveal() 按需取用，
+ *    reveal 必须经审计回调（provider+source 留痕，值不入审计——值入日志即泄露面，secrets 红线）；
+ *  - 环境变量约定：OPENAI_API_KEY（openai-compat）/ ANTHROPIC_API_KEY（anthropic）/
+ *    CAR_LLM_API_KEY（通用兜底）；显式开启 = opts.allowEnvFallback 或 CAR_ALLOW_ENV_CREDENTIALS=1。
+ */
+import { spawnSync } from 'node:child_process'
+import { CarM8Error, credentialMissing } from './errors.ts'
+import type { CredentialRef, CredentialSource } from './types.ts'
+
+export interface CredentialResolveOptions {
+  /** 测试注入；缺省取 process.env */
+  env?: NodeJS.ProcessEnv
+  /** env fallback 显式开启（规格要求默认关；CAR_ALLOW_ENV_CREDENTIALS=1 等效） */
+  allowEnvFallback?: boolean
+  /**
+   * keychain 读取器注入（测试替身）：入参 keychain 服务名，返回明文或 null（不存在）。
+   * 缺省用平台命令真实读取；平台无读通道（win32）= 通道不可用（显式降级）。
+   */
+  keychainReader?: (service: string) => string | null
+  /** reveal 审计回调（值不入参——审计全量留痕但零明文） */
+  audit?: (event: { action: 'resolve' | 'reveal'; provider: string; source: CredentialSource; origin: string }) => void
+}
+
+/** provider → 候选 env 变量（按序检索；CAR_LLM_API_KEY 为通用兜底） */
+const PROVIDER_ENV_VARS: Record<string, string[]> = {
+  'openai-compat': ['OPENAI_API_KEY'],
+  anthropic: ['ANTHROPIC_API_KEY'],
+}
+const GENERIC_ENV_VARS = ['CAR_LLM_API_KEY']
+
+/** keychain 服务名（命名空间隔离：car-runtime/<provider>） */
+export function keychainService(provider: string): string {
+  return `car-runtime/${provider}`
+}
+
+interface KeychainChannel { reader: ((service: string) => string | null) | null; note: string }
+
+/** 平台 keychain 通道探测：命令在场（darwin/linux）→ 真实读取器；无读通道（win32）→ 显式 null */
+export function probeKeychainChannel(platform: NodeJS.Platform = process.platform): KeychainChannel {
+  if (platform === 'darwin') {
+    return { reader: service => {
+      const r = spawnSync('security', ['find-generic-password', '-s', service, '-w'], { encoding: 'utf-8', timeout: 5000 })
+      if (r.status !== 0 || r.stdout == null) return null
+      return r.stdout.replace(/\r?\n$/, '') || null
+    }, note: 'darwin security' }
+  }
+  if (platform === 'linux') {
+    return { reader: service => {
+      const r = spawnSync('secret-tool', ['lookup', 'service', service], { encoding: 'utf-8', timeout: 5000 })
+      if (r.status !== 0 || r.stdout == null) return null
+      return r.stdout.replace(/\r?\n$/, '') || null
+    }, note: 'linux secret-tool' }
+  }
+  // win32 及其他：无零依赖读通道——显式不可用（禁静默假装有 keychain）
+  return { reader: null, note: `keychain 读通道在 ${platform} 缺席（零依赖实现无 OS 凭据库读取面）——显式降级` }
+}
+
+export class CredentialService {
+  readonly #channel: KeychainChannel
+  readonly #platform: NodeJS.Platform
+
+  constructor(opts: { keychainReader?: (service: string) => string | null; platform?: NodeJS.Platform } = {}) {
+    this.#platform = opts.platform ?? process.platform
+    this.#channel = opts.keychainReader
+      ? { reader: opts.keychainReader, note: 'injected reader' }
+      : probeKeychainChannel(this.#platform)
+  }
+
+  /** keychain 通道状态（doctor 展示/测试断言；缺席显式登记不静默） */
+  get channelStatus(): { available: boolean; note: string } {
+    return { available: this.#channel.reader !== null, note: this.#channel.note }
+  }
+
+  /**
+   * 解析凭据引用（天然幂等；返回值不含明文）。
+   * 检索顺序：keychain →（显式开启时）env；全落空 = A080001。
+   */
+  resolve(provider: string, opts: CredentialResolveOptions = {}): CredentialRef {
+    const env = opts.env ?? process.env
+    const searched: string[] = []
+    const service = keychainService(provider)
+
+    if (this.#channel.reader) {
+      searched.push(`keychain:${service}`)
+      const value = this.#channel.reader(service)
+      if (value) {
+        opts.audit?.({ action: 'resolve', provider, source: 'keychain', origin: service })
+        return { provider, source: 'keychain', origin: service }
+      }
+    } else {
+      searched.push(`keychain:${service}(通道缺席)`)
+    }
+
+    const allowEnv = opts.allowEnvFallback === true || env.CAR_ALLOW_ENV_CREDENTIALS === '1'
+    if (allowEnv) {
+      const candidates = [...(PROVIDER_ENV_VARS[provider] ?? []), ...GENERIC_ENV_VARS]
+      for (const name of candidates) {
+        searched.push(`env:${name}`)
+        if (env[name]) {
+          opts.audit?.({ action: 'resolve', provider, source: 'env', origin: name })
+          return { provider, source: 'env', origin: name, degraded: this.#channel.reader ? undefined : this.#channel.note }
+        }
+      }
+    } else {
+      searched.push('env(未显式开启 fallback)')
+    }
+
+    throw credentialMissing(provider, searched)
+  }
+
+  /** 按引用取明文（仅 provider 适配器请求时点调用；每次经审计留痕，值不入日志不入错误） */
+  reveal(ref: CredentialRef, opts: CredentialResolveOptions = {}): string {
+    const env = opts.env ?? process.env
+    if (ref.source === 'keychain') {
+      if (!this.#channel.reader) throw new CarM8Error('A080001', 'CAR-E-CRED-MISSING', `keychain 通道缺席，无法取值（${ref.origin}）`, '未找到模型服务凭据，请运行 car doctor', false)
+      const value = this.#channel.reader(ref.origin)
+      if (!value) throw credentialMissing(ref.provider, [`keychain:${ref.origin}(resolve 后消失)`])
+      opts.audit?.({ action: 'reveal', provider: ref.provider, source: ref.source, origin: ref.origin })
+      return value
+    }
+    const value = env[ref.origin]
+    if (!value) throw credentialMissing(ref.provider, [`env:${ref.origin}(resolve 后消失)`])
+    opts.audit?.({ action: 'reveal', provider: ref.provider, source: ref.source, origin: ref.origin })
+    return value
+  }
+}

package/src/runtime-core/errors.ts

@@ -0,0 +1,47 @@
+/**
+ * M8 · 错误面（《系统设计》§3.5.1 六位错误码 + 代码库 CAR-E-* 前缀双轨）
+ *
+ *  - A080001 凭据缺失：不重试，用户文案引导 car doctor（SQ-07 凭据缺失分支）；
+ *  - B080001 LLM Provider 不可达/重试耗尽：退避后重试（§3.5.4 基线——2 次指数退避 1s/2s）；
+ *  - 两条均为「错误路径不改写 finishReason 语义」的守门错误：流中途失败以
+ *    finishReason='error' chunk 收口（BD-04），首块前失败以 CarError 抛出（runTurn catch → turn error）。
+ */
+
+export type M8ErrorCode = 'A080001' | 'B080001'
+
+export class CarM8Error extends Error {
+  constructor(
+    /** 六位错误码（§3.5.1 注册表） */
+    readonly code: M8ErrorCode,
+    /** CAR-E-* 代码库前缀（与 CAR-E-DEPCYCLE 等同风格） */
+    readonly slug: string,
+    message: string,
+    /** 用户文案（§3.5.1 注册表原文） */
+    readonly userHint?: string,
+    /** 重试建议（A080001 不重试 / B080001 退避后重试） */
+    readonly retryable = false,
+  ) {
+    super(`${slug}: ${message}（${code}）`)
+    this.name = 'CarM8Error'
+  }
+}
+
+export function credentialMissing(provider: string, searched: string[]): CarM8Error {
+  return new CarM8Error(
+    'A080001',
+    'CAR-E-CRED-MISSING',
+    `未找到模型服务凭据（provider=${provider}，已检索：${searched.join('、') || '无可用通道'}）`,
+    '未找到模型服务凭据，请运行 car doctor',
+    false,
+  )
+}
+
+export function providerUnreachable(detail: string): CarM8Error {
+  return new CarM8Error(
+    'B080001',
+    'CAR-E-LLM-UNREACHABLE',
+    `LLM Provider 不可达/重试耗尽：${detail}`,
+    '模型服务暂时不可用，本轮已停止',
+    true,
+  )
+}