@lqc123qwe/car-runtime 1.3.0 → 1.4.0

package/README.md

@@ -181,11 +181,12 @@ node --experimental-transform-types --test test/*.spec.ts
 - **遗留登记**：W1 = 1.3 头号候选（含 D-12a TLS loopback 豁免实装、car run 装配面重做〔demo_tool 撞名观察项出清〕）；car run demo_tool 撞名 DEPCYCLE 为预存在边缘（登记不修，W1 出清）。规划：`car-docs/10-内核v1/1.2-迭代规划.md`；收口报告：`car-docs/10-内核v1/1.2-收口终验报告.md`。
 - **1.2.0 正式发布（2026-09-27，S5 收官）**：npm `@lqc123qwe/car-runtime@1.2.0` 在架——**dist-tag latest → 1.2.0，rc 保留指向 1.0.0-rc.1**；SLSA provenance（slsa.dev/provenance/v1）。Release `1.2.0`（用户创建，六资产）→ **j16 run 36312617477 success** → **post-publish REMOTE_CHECK=1 复跑 12 PASS / 1 DRY-RUN / 0 FAIL（G-09 实查 PASS）** + 外部验证者等价检查（Release 实下载件 SHA256 MATCH `6d6d4da1…` + cosign Verified OK）。发布工程事件：registry CDN 缓存滞后登记（cache-buster 口径）；制品自 tag 树重建后再挂（消除 1.1 的树漂移）。
 
-- **1.3 发布资产自动化（W4，2026-09-27 收口）**：`scripts/release-artifacts.ts` 制品构建单一事实源（本地流水线/CI j16 双端复用；SHA256SUMS 裸字节自检 G-11 口径 + SBOM G-05 同构 + releaseAssetNames 五件套清单——G-10/CI/测试三方同源）+ release.yml 重构（构建 → cosign keyless 签名〔D-15 正式轨：OIDC+Rekor，CI 零 keypair 材料〕→ `gh release upload --clobber` 五件套 → npm publish 原步不动；**upload 先于 publish**）+ D-14 资产集迁移（car-release.pub 移出——keyless 验证锚 = bundle 证书 + Rekor）+ D-14 tag 形态统一（裸版本号）。s30 六测（构建/清单/同源/yml 结构与步骤序红线）。全量 **269（266 PASS + 3 skip / 0 fail）**。1.3.0 发布 = W4 验收载体（**全链零人工拖拽资产**）。W1 三度延后登记 **1.4 头号候选**（设计账本 D-12a loopback 豁免 + D-13 --demo 保留）。规划：`car-docs/10-内核v1/1.3-迭代规划.md`；收口报告：`car-docs/10-内核v1/1.3-收口终验报告.md`。
+- **1.3 发布资产自动化（W4，2026-09-27 收口）**：`scripts/release-artifacts.ts` 制品构建单一事实源（本地流水线/CI j16 双端复用；SHA256SUMS 裸字节自检 G-11 口径 + SBOM G-05 同构 + releaseAssetNames 五件套清单——G-10/CI/测试三方同源）+ release.yml 重构（构建 → cosign keyless 签名〔D-15 正式轨：OIDC+Rekor，CI 零 keypair 材料〕→ `gh release upload --clobber` 五件套 → npm publish 原步不动；**upload 先于 publish**）+ D-14 资产集迁移（car-release.pub 移出——keyless 验证锚 = bundle 证书 + Rekor）+ D-14 tag 形态统一（裸版本号）。s30 七测（构建/清单/同源/yml 结构与步骤序红线/**name 行冒号守卫**〔1.3-BUG-2 回归钉〕）。全量 **270（267 PASS + 3 skip / 0 fail）**。W1 三度延后登记 **1.4 头号候选**（设计账本 D-12a loopback 豁免 + D-13 --demo 保留）。规划：`car-docs/10-内核v1/1.3-迭代规划.md`；收口报告：`car-docs/10-内核v1/1.3-收口终验报告.md`。
+- **1.3.0 正式发布（2026-09-27，S5 收官，W4 全自动首战兑现）**：Release `1.3.0`（tag 32dad29）→ **j16 run 36320604746 全步 success**（构建 → keyless 签名 → 自动上传五件套〔零人工拖拽〕→ npm publish）→ npm `@lqc123qwe/car-runtime@1.3.0` 在架，**dist-tags latest → 1.3.0、rc 保留 1.0.0-rc.1** + provenance。**post-publish 12 PASS / 1 DRY-RUN / 0 FAIL（G-09 实查）**；外部等价检查 **SHA256 MATCH（`70767c8d…`）+ cosign keyless Verified OK**（证书身份 + Rekor——D-15 正式轨兑现，pub 退役）。发布工程事件：首发受挫 1.3-BUG-2（workflow 步骤名未引号冒号 → YAML 解析失败 → startup failure 且 release 事件静默失效；**改 workflow 必须本地 PyYAML 复验**，post-publish 必须核对 release 事件 run 真实触发）。
 
 ## 状态
 
-- **版本主线**：S1-S4 48/48 ｜ M2 89/89（v0.2.0）｜ M3 127/127（v0.3.0）｜ M4 139/139（**1.0.0-rc.1 已发布**）｜ M5 156/156（DEC-4 预埋项转正）｜ M6 179/179（2026-09-15 收口）｜ M7 全量 195（192 PASS + 3 能力门控 skip，2026-09-19 收口）｜ **M5-S28 装载签名门 全量 204（201 PASS + 3 skip，2026-09-26）** ｜ **M8 运行时底座 全量 231（228 PASS + 3 skip，2026-09-26 收口，§3.2 八模块全部收口）** ｜ **1.1 签名收尾最小集 全量 249（246 PASS + 3 skip，2026-09-27 收口，1.1.0 已发布，enforce 翻转准备就绪）** ｜ **1.2 会话/遥测小项 全量 263（260 PASS + 3 skip，2026-09-27 收口，1.2.0 已发布）** ｜ **1.3 发布资产自动化 全量 269（266 PASS + 3 skip，2026-09-27 收口，发布全链去人工拖拽）**
+- **版本主线**：S1-S4 48/48 ｜ M2 89/89（v0.2.0）｜ M3 127/127（v0.3.0）｜ M4 139/139（**1.0.0-rc.1 已发布**）｜ M5 156/156（DEC-4 预埋项转正）｜ M6 179/179（2026-09-15 收口）｜ M7 全量 195（192 PASS + 3 能力门控 skip，2026-09-19 收口）｜ **M5-S28 装载签名门 全量 204（201 PASS + 3 skip，2026-09-26）** ｜ **M8 运行时底座 全量 231（228 PASS + 3 skip，2026-09-26 收口，§3.2 八模块全部收口）** ｜ **1.1 签名收尾最小集 全量 249（246 PASS + 3 skip，2026-09-27 收口，1.1.0 已发布，enforce 翻转准备就绪）** ｜ **1.2 会话/遥测小项 全量 263（260 PASS + 3 skip，2026-09-27 收口，1.2.0 已发布）** ｜ **1.3 发布资产自动化 全量 270（267 PASS + 3 skip，2026-09-27 收口，1.3.0 已发布，全链零人工拖拽兑现）**
 - **1.0.0 正式发布（2026-09-26，S29/S30）**：npm `@lqc123qwe/car-runtime@1.0.0` 在架——**dist-tag latest → 1.0.0，rc 保留指向 1.0.0-rc.1**（§1.1 口径）；SLSA provenance（Actions OIDC，透明日志在案）；GitHub Release v1.0.0 六资产（tgz/bundle/SHA256SUMS/SBOM/审计/公钥）；**post-publish 全链 13 PASS / 0 DRY-RUN / 0 FAIL** + 外部验证者等价检查（Release 实下载件 SHA256 MATCH + cosign Verified OK）。**宽限期时钟：2026-09-26 起算，2026-12-25 到期 verifier 默认值 warn→enforce 翻转（计划内变更）**。终验报告：`car-docs/10-内核v1/M5-S30-1.0收口终验报告.md`。发布工程事件：j16 首跑 E403（npm 2FA 策略 vs granular token 无 bypass——清单预设回退路径兑现）→ bypass token re-run 绿；G-09 期望 tag 动态化（`4c84b17`）在真实发布兑现价值。
 - **1.0.0-rc.1 已发布（2026-09-09）**：npm `@lqc123qwe/car-runtime@1.0.0-rc.1`（rc + latest 双 tag，SLSA provenance 在案）+ GitHub Release 6 制品；发布预演 **13 PASS / 0 DRY-RUN / 0 FAIL**（c762b72）。S22 GO 清单已全绿收口。
 - **轨道 A 三项全部完成**：E-1 WSL2 逃逸矩阵 **20/20 PASS 零逃逸**（2026-09-07，G-07 转 PASS）｜ E-3 远端发布通道 **13/13 全门禁 PASS**（2026-09-09，G-08/09/10 转 PASS）｜ E-2 Windows koffi FFI **四判据双环境全 PASS**（S24/S25/S26，2026-09-09~10；本机非提权 + windows-latest 提权 runner 双绿，CI 门禁已接入）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lqc123qwe/car-runtime",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Composable Agent Runtime (CAR) - microkernel plugin system with sandboxed PTC, append-only hashed session log, and MCP host bridge",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -24,10 +24,15 @@ import { runTurn } from './loop/stop.ts'
 import { Context } from './kernel/context.ts'
 import { mountPlugin } from './load/loader.ts'
 import { verifyPluginFile } from './load/sigGate.ts'
-import { loadCarConfig, mergeSignatureGate } from './load/config.ts'
+import { loadCarConfig, mergeSignatureGate, mergeLlmConfig } from './load/config.ts'
 import { generateSigningKeypair, signPluginFile, resolveTrustRoot } from './load/sign.ts'
-import { doctorCredentials, doctorConnectivity, doctorKeychain, doctorSignature } from './dx/doctor.ts'
+import { doctorCredentials, doctorConnectivity, doctorKeychain, doctorSignature, doctorModelReadiness } from './dx/doctor.ts'
+import { RuntimeCore, createOpenAICompatAdapter } from './runtime-core/llm.ts'
+import { CredentialService } from './runtime-core/credentials.ts'
+import { chatStep } from './runtime-core/chatStep.ts'
+import { toToolDefinitions } from './runtime-core/tools.ts'
 import { createTelemetryFacade, telemetryConfigFromEnv } from './runtime-core/telemetry.ts'
+import { TurnTracer } from './runtime-core/trace.ts'
 import type { CounterName, AllowedLabels } from './telemetry/metrics.ts'
 
 const HELP = `用法: car <command> [args]
@@ -98,8 +103,11 @@ async function main(): Promise<number> {
   const [, , cmd, ...rest] = process.argv
   switch (cmd) {
     case 'run': {
+      // 1.4-S5（D-13）：缺省 = 真实模型路径（chatStep 经 openai-compat 适配器）；--demo 保留 stub 演示流。
+      // 无模型配置 exit 2 显式报错引导（禁静默降级）。会话/索引/签名门两路径共用。
       const file = rest[0]
       if (!file) { console.error('缺少插件文件参数'); return 2 }
+      const isDemo = rest.includes('--demo')
       const t0 = Date.now()
       // 环节 0：装载前签名门（M5-S28 装载接线 + 1.1-S3 配置通道：flag > env > car.config.json > 缺省 warn）
       const sig = resolveSigGate(rest)
@@ -118,29 +126,164 @@ async function main(): Promise<number> {
       // 失败非致命——索引为派生缓存，rebuild-index 兜底语义不变；SQLite 能力缺席 = 显式登记一次后停用）
       const indexUpdater = new IndexUpdater({ dbPath: join(process.cwd(), 'sessions-index.db'), onError: e => console.error(`[index-updater] ${e.message}`) })
       log.attachSink(line => { store.append(line); indexUpdater.record(log.sessionId, line, store.path) })
+      // 1.4-S5：插件工具收集（ToolReg 全量进 Map——执行面与声明面同一对象，声明面=授权面红线）；
+      // setSystemPrompt 收集（last-wins，D-17）
       const hostTools: any[] = []
+      let pluginSystemPrompt: string | null = null
       ctx.plugin({ name: plugin.manifest.name, apply: (c) => {
         plugin.bindCore({
           registerTool: (t) => { hostTools.push(t); c.provide('tool:' + t.name, t) },
           getRegisteredTools: () => hostTools,
+          setSystemPrompt: (text) => { pluginSystemPrompt = text },
         })
-        plugin.api.registerTool({
-          name: 'demo_tool', run: async () => 'demo-ok',
-        })
+        if (isDemo) {
+          // --demo 演示流专属脚手架（真路径不注入——1.1 规划登记的 demo_tool 撞名边缘就此出清）
+          plugin.api.registerTool({
+            name: 'demo_tool', run: async () => 'demo-ok',
+          })
+        }
       } })
       console.log(`[1/5 装配] OK（${Date.now() - t0}ms，工具: ${hostTools.map(t => t.name).join(', ') || '无'}）`)
       // 环节 2-3：沙箱探测 + 事件运行 + 停止收口
       const probe = await probeCapabilities()
       const sandbox = new SandboxExecutor({ probe, audit: () => {}, workspace: process.cwd() })
       console.log(`[2/5 沙箱] ${probe.degraded ? `降级（${probe.reason}）——Q-04 约束生效` : 'Landlock 就绪'}`)
-      log.append('user', 'user', 'T0', '请调用 demo_tool 并汇报')
-      const r = await runTurn({
-        log, turnId: 'T0',
-        preset: { mode: 'confirm', authorize: async () => { console.log('[授权] 确认模式：放行 demo_tool'); return true } },
-        tools: new Map([['demo_tool', { declaredSideEffect: 'write', run: async () => 'demo-ok' } as any]]),
-        model: async () => ({ stopReason: 'toolUse' as const, toolCalls: [{ id: 'c1', tool: 'demo_tool', args: {} }] }),
-      })
+      // 工具执行面 Map（T-22 收口：declaredSideEffect 缺省 write）
+      const toolsMap = new Map<string, any>(hostTools.map(t => [t.name, {
+        declaredSideEffect: t.declaredSideEffect ?? 'write',
+        run: t.run,
+        ...(t.description !== undefined ? { description: t.description } : {}),
+        ...(t.parameters !== undefined ? { parameters: t.parameters } : {}),
+      }]))
+      // 取消信号（SIGINT → 中断在途流；runTurn 既有收口落 turnEnd aborted）
+      const signal = { aborted: false }
+      const onSigint = () => { signal.aborted = true; console.error('\n[取消] SIGINT——正在中断当前 turn…') }
+      process.once('SIGINT', onSigint)
+      // 1.4-S6：遥测门面（CAR_OTEL_ENDPOINT env 通道；缺省关 = noop 零出站）——turn/step span 挂装配层
+      const otel = createTelemetryFacade(telemetryConfigFromEnv())
+      const tracer = new TurnTracer(otel)
+      let r: Awaited<ReturnType<typeof runTurn>>
+      if (isDemo) {
+        // --demo：stub 演示流（无模型可跑——五环节叙事与既有测试/CI 承载）
+        log.append('user', 'user', 'T0', '请调用 demo_tool 并汇报')
+        r = await runTurn({
+          log, turnId: 'T0',
+          preset: { mode: 'confirm', authorize: async () => { console.log('[授权] 确认模式：放行 demo_tool'); return true } },
+          tools: new Map([['demo_tool', { declaredSideEffect: 'write', run: async () => 'demo-ok' } as any]]),
+          model: async () => ({ stopReason: 'toolUse' as const, toolCalls: [{ id: 'c1', tool: 'demo_tool', args: {} }] }),
+        })
+      } else {
+        // 真路径：模型配置解析（D-16 优先级 flag > env > config）+ 装配 RuntimeCore
+        const cfgLlm = loadCarConfig({ explicitPath: flagValue(rest, '--config') })
+        if (cfgLlm.error) { console.error(cfgLlm.error); return 2 }
+        const mtFlag = flagValue(rest, '--max-tokens')
+        const llm = mergeLlmConfig(process.env, cfgLlm.config, {
+          baseUrl: flagValue(rest, '--base-url'),
+          model: flagValue(rest, '--model'),
+          adapterId: flagValue(rest, '--adapter-id'),
+          ...(mtFlag !== undefined ? { maxTokens: Number(mtFlag) } : {}),
+        })
+        const prompt = flagValue(rest, '--prompt')
+        if (!llm.baseUrl || !llm.model || prompt === undefined) {
+          console.error('CAR-E-LLM-CONFIG: 真实模型路径需要 baseUrl + model + --prompt——')
+          console.error('  配置：car.config.json {"llm":{"baseUrl":"https://…","model":"…"}} / env CAR_LLM_BASE_URL+CAR_LLM_MODEL / flag --base-url --model --prompt')
+          console.error('  凭据：OPENAI_API_KEY（env fallback 需 CAR_ALLOW_ENV_CREDENTIALS=1 或 llm.allowEnvFallback）或 keychain；诊断：car doctor')
+          console.error('  （无模型演示流：--demo）')
+          return 2
+        }
+        const modelName = llm.model
+        const credService = new CredentialService()
+        const core = new RuntimeCore(credService)
+        core.bindContext(ctx)
+        // 适配器经根作用域 effect 可逆注册（bindContext 必须先于 register——否则走非可逆直注册分支）
+        core.registerLlmAdapter(createOpenAICompatAdapter({
+          baseUrl: llm.baseUrl,
+          credentials: credService,
+          provider: 'openai-compat',
+        }), { default: true })
+        // MCP 工具进 turn（D-18）：--mcp <serverId>（可重复；server 启动规格在 car.config.json mcp.servers 登记）
+        const mcpIds: string[] = []
+        for (let i = 0; i < rest.length; i++) {
+          if (rest[i] === '--mcp') {
+            const id = rest[++i]
+            if (!id) { console.error('缺少 --mcp serverId'); return 2 }
+            mcpIds.push(id)
+          }
+        }
+        const mcpTransports: import('./mcp/gateway.ts').ClientTransport[] = []
+        if (mcpIds.length) {
+          const { McpGateway } = await import('./mcp/gateway.ts')
+          const { createStdioClientTransport } = await import('./mcp/stdioClient.ts')
+          const gw = new McpGateway()
+          for (const id of mcpIds) {
+            const spec = cfgLlm.config.mcp?.servers?.[id]
+            if (!spec) { console.error(`CAR-E-MCP: server "${id}" 未在 car.config.json mcp.servers 登记`); return 2 }
+            const transport = createStdioClientTransport({ command: spec.command, args: spec.args })
+            mcpTransports.push(transport)
+            const mcpTools = await gw.register({ serverId: id, transport, env: spec.env })
+            for (const t of mcpTools) {
+              const modelName = `mcp_${id}_${t.name}`
+              if (toolsMap.has(modelName)) { console.error(`CAR-E-MCP: 工具名冲突 ${modelName}（跨源同名禁静默覆盖）`); return 1 }
+              toolsMap.set(modelName, {
+                declaredSideEffect: t.declaredSideEffect ?? 'write',
+                run: async (args: any) => { const r = await gw.callTool(id, t.name, args); if (!r.ok) throw new Error(r.error ?? 'mcp call failed'); return r.result },
+                ...(t.description !== undefined ? { description: t.description } : {}),
+                ...(t.inputSchema !== undefined ? { parameters: t.inputSchema } : {}),
+              })
+            }
+            console.log(`[MCP] ${id}: ${mcpTools.length} 工具入声明面`)
+          }
+        }
+        // PTC 进真实 turn（--ptc）：插件工具 Map 即 ToolBridge（声明面=授权面同源快照）；
+        // run_code 进工具 Map（强制 write）；SDK 声明块独立 system 事件（D-17）
+        let sdkBlock: string | null = null
+        if (rest.includes('--ptc')) {
+          const { makePtcToolDefinition, runCode } = await import('./ptc/runCode.ts')
+          void runCode
+          const { renderSdkFromRegistry } = await import('./ptc/sdk.ts')
+          const registry = new Map([...toolsMap].map(([name, t]) => [name, { run: t.run, description: t.description, inputSchema: t.parameters }]))
+          sdkBlock = renderSdkFromRegistry(registry)
+          const ptc = makePtcToolDefinition({ tools: registry, audit: () => {} })
+          toolsMap.set(ptc.name, ptc)
+          console.log(`[PTC] run_code 入工具面（桥接 ${registry.size} 工具；SDK 声明块进 system）`)
+        }
+        // system prompt 落链（D-17）：--system flag > 插件 setSystemPrompt（last-wins）；SDK 块独立追加
+        const systemText = flagValue(rest, '--system') ?? pluginSystemPrompt
+        if (systemText) log.append('runtime', 'system', 'system', systemText)
+        if (sdkBlock) log.append('runtime', 'system', 'system', sdkBlock)
+        log.append('user', 'user', 'T0', prompt)
+        const turn = tracer.startTurn('T0')
+        let stepNo = 0
+        r = await runTurn({
+          log, turnId: 'T0',
+          preset: { mode: 'confirm', authorize: async (call) => { console.log(`[授权] 确认模式：放行 ${call.tool}`); return true } },
+          tools: toolsMap,
+          signal,
+          model: () => {
+            // 1.4-S6：step span 挂每次 model() 调用（parent = turn span；同 turn 共享 traceId）
+            const step = turn.stepSpan(++stepNo)
+            return chatStep({
+              core, log, turnId: 'T0',
+              model: modelName,
+              tools: toToolDefinitions(toolsMap),
+              ...(llm.maxTokens !== undefined ? { maxTokens: llm.maxTokens } : {}),
+              ...(llm.adapterId ? { adapterId: llm.adapterId } : {}),
+              signal,
+            }).then(
+              res => { step.end(res.stopReason); return res },
+              e => { step.recordException(e); step.end('error'); throw e },
+            )
+          },
+        })
+        turn.end(r.reason)
+      }
+      process.removeListener('SIGINT', onSigint)
       console.log(`[3/5 收口] turnEnd=${r.reason}（steps=${r.steps}）`)
+      // 1.4-S6：遥测收口 flush（显式开路径；缺省关 = 空转）
+      if (otel.enabled) {
+        await otel.shutdown()
+        console.error(`[otel] stats=${JSON.stringify(otel.stats())}`)
+      }
       // 环节 4：落盘收口（全程逐事件 fsync 已发生，此处仅关句柄核对 + 索引 pending 落盘）
       store.close()
       await indexUpdater.close()
@@ -179,6 +322,9 @@ async function main(): Promise<number> {
       // 1.1-S2 增强：签名就绪行（mode 生效值 / 信任根可解析性 / 配置文件通道发现态；诊断只读）
       const sig = doctorSignature({ cwd: process.cwd(), configPath: flagValue(rest, '--config') })
       console.log(`signature: ${sig.detail}`)
+      // 1.4-S3 增强：模型就绪行（baseUrl/model / 凭据通道 / envFallback；值不打印）
+      const mr = doctorModelReadiness({ cwd: process.cwd(), configPath: flagValue(rest, '--config') })
+      console.log(`model: ${mr.detail}`)
       // M6 增强：registry 连通性（不可达 = SKIPPED 显式跳过，离线不失败）
       const conn = await doctorConnectivity()
       console.log(`connectivity: ${conn.status} — ${conn.detail}${conn.status === 'PASS' ? `（${conn.latencyMs}ms）` : ''}`)

package/src/dx/doctor.ts

@@ -9,7 +9,7 @@
  */
 import { createPublicKey } from 'node:crypto'
 import { CredentialService } from '../runtime-core/credentials.ts'
-import { loadCarConfig, mergeSignatureGate } from '../load/config.ts'
+import { loadCarConfig, mergeSignatureGate, mergeLlmConfig } from '../load/config.ts'
 
 export interface CredentialCheck {
   name: string
@@ -90,6 +90,47 @@ export function doctorSignature(opts: { env?: NodeJS.ProcessEnv; cwd?: string; c
   return { mode, trustRoot, configFile, detail: parts.join('；') }
 }
 
+export interface ModelReadinessCheck {
+  /** baseUrl + model 均在场 = true（可发起真实模型请求的最低配置面） */
+  configured: boolean
+  baseUrl: string
+  model: string
+  /** 凭据通道探测（存在性，值不打印）：keychain 命中 / env 命中（显式开启时）/ 全落空 */
+  credential: 'keychain' | 'env' | 'not-found'
+  /** env fallback 开关态（CAR_ALLOW_ENV_CREDENTIALS=1 或 llm.allowEnvFallback） */
+  envFallback: 'on' | 'off'
+  detail: string
+}
+
+/** 1.4-S3 模型就绪检查（D-16）：baseUrl/model 在场性 + 凭据通道存在性探测（离线可过；值不打印） */
+export function doctorModelReadiness(opts: { env?: NodeJS.ProcessEnv; cwd?: string; configPath?: string } = {}): ModelReadinessCheck {
+  const env = opts.env ?? process.env
+  const cfg = loadCarConfig({ explicitPath: opts.configPath, cwd: opts.cwd })
+  const { baseUrl, model, allowEnvFallback } = mergeLlmConfig(env, cfg.error ? {} : cfg.config)
+  const envFallback: ModelReadinessCheck['envFallback'] = allowEnvFallback ? 'on' : 'off'
+  let credential: ModelReadinessCheck['credential'] = 'not-found'
+  if (allowEnvFallback) {
+    // env fallback 显式开启：env 变量存在性（OPENAI_API_KEY / CAR_LLM_API_KEY）——只探存在不取值
+    if (env.OPENAI_API_KEY || env.CAR_LLM_API_KEY) credential = 'env'
+  }
+  if (credential === 'not-found') {
+    // keychain 通道存在性（resolve 探测，A080001 全落空即 not-found；值不打印）
+    try {
+      const ref = new CredentialService().resolve('openai-compat', { env, allowEnvFallback })
+      credential = ref.source
+    } catch { /* 全落空 = not-found（登记口径，非错误） */ }
+  }
+  const configured = !!baseUrl && !!model
+  const parts = [
+    configured ? `baseUrl=${baseUrl} model=${model}` : 'baseUrl/model 未配置（car run 真路径需 llm.* 配置或 CAR_LLM_BASE_URL/CAR_LLM_MODEL——见 car doctor / 配置指南）',
+    credential === 'keychain' ? '凭据=keychain 命中（car-runtime/openai-compat，值不打印）'
+      : credential === 'env' ? '凭据=env 命中（显式开启 fallback，值不打印）'
+      : '凭据未就绪（keychain 未命中且 env fallback 未开或变量缺席——A080001 会引导至此）',
+    `envFallback=${envFallback}`,
+  ]
+  return { configured, baseUrl: baseUrl ?? '', model: model ?? '', credential, envFallback, detail: parts.join('；') }
+}
+
 /**
  * registry 连通性检查：可达 = PASS（含延迟）；不可达/显式跳过 = SKIPPED（不失败）。
  * 默认 registry 取 CAR_REGISTRY_URL，缺省 npmjs。
@@ -105,14 +146,20 @@ export async function doctorConnectivity(opts: {
     return { status: 'SKIPPED', detail: `显式离线（CAR_OFFLINE=1 或测试注入）——跳过 ${url}`, latencyMs: 0 }
   }
   const t0 = Date.now()
+  // 同 1.4-BUG-2：AbortSignal.timeout → 手动 controller（进程退出 libuv win32 断言预防）
+  const controller = new AbortController()
+  const abortTimer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 2000)
   try {
-    await fetch(url, { signal: AbortSignal.timeout(opts.timeoutMs ?? 2000) })
+    await fetch(url, { signal: controller.signal })
     return { status: 'PASS', detail: url, latencyMs: Date.now() - t0 }
   } catch (e) {
+    clearTimeout(abortTimer)
     return {
       status: 'SKIPPED',
       detail: `registry 不可达（${(e as Error).name}: ${(e as Error).message}）——离线环境显式跳过，不判失败`,
       latencyMs: Date.now() - t0,
     }
+  } finally {
+    clearTimeout(abortTimer)
   }
 }

package/src/load/config.ts

@@ -27,8 +27,27 @@ export interface SandboxSigConfig {
   sigTrustRoot?: string
 }
 
+export interface LlmConfig {
+  baseUrl?: string
+  model?: string
+  adapterId?: string
+  maxTokens?: number
+  allowEnvFallback?: boolean
+}
+
+export interface McpServerSpec {
+  command: string
+  args?: string[]
+  /** 启动环境变量（禁明文凭据——gateway.containsPlaintextCredential 注册时强制检查） */
+  env?: Record<string, string>
+}
+
 export interface CarConfig {
   sandbox?: SandboxSigConfig
+  /** 1.4-S3（D-16）：模型接入配置键位空间；凭据禁入（CR-05）——只放端点/模型名/开关 */
+  llm?: LlmConfig
+  /** 1.4-S7（D-18）：MCP server 登记面（--mcp <id> 显式启用；serverId → stdio 启动规格） */
+  mcp?: { servers: Record<string, McpServerSpec> }
 }
 
 export interface ConfigLoadResult {
@@ -68,8 +87,77 @@ function validate(raw: unknown): { config: CarConfig; error?: string } {
   }
   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 (k !== 'sandbox' && k !== 'llm' && k !== 'mcp') {
+      return { config: {}, error: `CAR-E-CONFIG: 未知顶层键 "${k}"（登记键位空间：sandbox.* / llm.* / mcp.*）` }
+    }
+    if (k === 'mcp') {
+      if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+        return { config: {}, error: 'CAR-E-CONFIG: mcp 必须为对象' }
+      }
+      const top = v as Record<string, unknown>
+      if (Object.keys(top).some(x => x !== 'servers')) {
+        return { config: {}, error: `CAR-E-CONFIG: 未知键 mcp.${Object.keys(top).find(x => x !== 'servers')}（登记键位：mcp.servers）` }
+      }
+      const serversRaw = top.servers
+      if (typeof serversRaw !== 'object' || serversRaw === null || Array.isArray(serversRaw)) {
+        return { config: {}, error: 'CAR-E-CONFIG: mcp.servers 必须为对象（serverId → 启动规格）' }
+      }
+      const servers: Record<string, McpServerSpec> = {}
+      for (const [sid, sv] of Object.entries(serversRaw as Record<string, unknown>)) {
+        if (typeof sv !== 'object' || sv === null || Array.isArray(sv)) {
+          return { config: {}, error: `CAR-E-CONFIG: mcp.servers.${sid} 必须为对象` }
+        }
+        const spec = sv as Record<string, unknown>
+        if (typeof spec.command !== 'string' || !spec.command.trim()) {
+          return { config: {}, error: `CAR-E-CONFIG: mcp.servers.${sid}.command 必须为非空字符串` }
+        }
+        const parsed: McpServerSpec = { command: spec.command.trim() }
+        if (spec.args !== undefined) {
+          if (!Array.isArray(spec.args) || spec.args.some(a => typeof a !== 'string')) {
+            return { config: {}, error: `CAR-E-CONFIG: mcp.servers.${sid}.args 必须为字符串数组` }
+          }
+          parsed.args = spec.args as string[]
+        }
+        if (spec.env !== undefined) {
+          if (typeof spec.env !== 'object' || spec.env === null || Array.isArray(spec.env) || Object.values(spec.env).some(x => typeof x !== 'string')) {
+            return { config: {}, error: `CAR-E-CONFIG: mcp.servers.${sid}.env 必须为字符串映射` }
+          }
+          parsed.env = spec.env as Record<string, string>
+        }
+        const unknownKey = Object.keys(spec).find(x => x !== 'command' && x !== 'args' && x !== 'env')
+        if (unknownKey) {
+          return { config: {}, error: `CAR-E-CONFIG: 未知键 mcp.servers.${sid}.${unknownKey}（登记键位：command / args / env）` }
+        }
+        servers[sid] = parsed
+      }
+      out.mcp = { servers }
+      continue
+    }
+    if (k === 'llm') {
+      if (typeof v !== 'object' || v === null || Array.isArray(v)) {
+        return { config: {}, error: 'CAR-E-CONFIG: llm 必须为对象' }
+      }
+      const llm: LlmConfig = {}
+      for (const [lk, lv] of Object.entries(v as Record<string, unknown>)) {
+        if (lk === 'baseUrl' || lk === 'model' || lk === 'adapterId') {
+          if (typeof lv !== 'string' || !lv.trim()) return { config: {}, error: `CAR-E-CONFIG: llm.${lk} 必须为非空字符串` }
+          if (lk === 'baseUrl') llm.baseUrl = lv.trim()
+          else if (lk === 'model') llm.model = lv.trim()
+          else llm.adapterId = lv.trim()
+        } else if (lk === 'maxTokens') {
+          if (typeof lv !== 'number' || !Number.isFinite(lv) || lv <= 0 || !Number.isInteger(lv)) {
+            return { config: {}, error: 'CAR-E-CONFIG: llm.maxTokens 必须为正整数' }
+          }
+          llm.maxTokens = lv
+        } else if (lk === 'allowEnvFallback') {
+          if (typeof lv !== 'boolean') return { config: {}, error: 'CAR-E-CONFIG: llm.allowEnvFallback 必须为布尔' }
+          llm.allowEnvFallback = lv
+        } else {
+          return { config: {}, error: `CAR-E-CONFIG: 未知键 llm.${lk}（登记键位：llm.baseUrl / llm.model / llm.adapterId / llm.maxTokens / llm.allowEnvFallback）` }
+        }
+      }
+      out.llm = llm
+      continue
     }
     if (typeof v !== 'object' || v === null || Array.isArray(v)) {
       return { config: {}, error: 'CAR-E-CONFIG: sandbox 必须为对象' }
@@ -112,6 +200,34 @@ export interface ResolvedSignatureGate {
   unsignedAllow: boolean
 }
 
+/**
+ * 1.4-S3（D-16）：模型接入配置合并（flag > env > 配置 > 缺省）。
+ * env 已定义为显式意见（压过配置），未定义落配置层——与 mergeSignatureGate 同纪律。
+ * 凭据不在此层（CR-05）：走 CredentialService（keychain → env OPENAI_API_KEY/CAR_LLM_API_KEY，
+ * env fallback 需显式开启 = CAR_ALLOW_ENV_CREDENTIALS=1 或 llm.allowEnvFallback）。
+ */
+export function mergeLlmConfig(env: NodeJS.ProcessEnv, cfg: CarConfig, flags: { baseUrl?: string; model?: string; adapterId?: string; maxTokens?: number } = {}): LlmConfig {
+  let baseUrl = cfg.llm?.baseUrl
+  if (env.CAR_LLM_BASE_URL) baseUrl = env.CAR_LLM_BASE_URL
+  if (flags.baseUrl) baseUrl = flags.baseUrl
+  let model = cfg.llm?.model
+  if (env.CAR_LLM_MODEL) model = env.CAR_LLM_MODEL
+  if (flags.model) model = flags.model
+  let adapterId = cfg.llm?.adapterId
+  if (flags.adapterId) adapterId = flags.adapterId
+  let maxTokens = cfg.llm?.maxTokens
+  if (flags.maxTokens !== undefined) maxTokens = flags.maxTokens
+  let allowEnvFallback = cfg.llm?.allowEnvFallback === true
+  if (env.CAR_ALLOW_ENV_CREDENTIALS !== undefined) allowEnvFallback = env.CAR_ALLOW_ENV_CREDENTIALS === '1'
+  return {
+    ...(baseUrl ? { baseUrl } : {}),
+    ...(model ? { model } : {}),
+    ...(adapterId ? { adapterId } : {}),
+    ...(maxTokens !== undefined ? { maxTokens } : {}),
+    allowEnvFallback,
+  }
+}
+
 /**
  * 优先级合并（flag > env > 配置 > 缺省）：产出装载签名门选项。
  * flagEnforce = CLI --sig-enforce；env 已定义即为显式意见（压过配置），未定义落配置层。

package/src/load/loader.ts

@@ -85,24 +85,38 @@ export function parseManifest(raw: unknown, file = '<manifest>'): Manifest {
   return m
 }
 
-export interface ToolReg { name: string; run: (args: any) => Promise<unknown> }
+export interface ToolReg {
+  name: string
+  run: (args: any) => Promise<unknown>
+  // —— 1.4-S1 声明面加法（进模型 ToolDefinition；缺省收口见 runtime-core/tools.ts T-22）——
+  /** 工具描述（进模型 function.description） */
+  description?: string
+  /** 入参 JSON Schema（进模型 function.parameters） */
+  parameters?: unknown
+  /** 副作用声明（缺省 write 收口——T-22 同款：未声明按最高约束） */
+  declaredSideEffect?: 'readonly' | 'write'
+}
 export interface CommandReg { name: string; run: (args: string[]) => Promise<void> }
 export interface PluginApi {
   registerTool(tool: ToolReg): void
   registerCommand(cmd: CommandReg): void
   getRegisteredTools(): ToolReg[]
+  /** 1.4-S2：插件设定 system prompt（session 级；last-wins；bindCore 时冲刷进宿主收集器，落 'system' 事件） */
+  setSystemPrompt(text: string): void
 }
 
 interface HostBinding {
   registerTool?(tool: ToolReg): void
   registerCommand?(cmd: CommandReg): void
   getRegisteredTools(): ToolReg[]
+  setSystemPrompt?(text: string): void
 }
 
 class ApiImpl {
   #host: HostBinding | undefined
   #pendingTools: ToolReg[] = []
   #pendingCommands: CommandReg[] = []
+  #pendingSystemPrompt: string | null = null
   registerTool(tool: ToolReg): void {
     if (this.#host?.registerTool) { this.#host.registerTool(tool); return }
     this.#pendingTools.push(tool) // 注册类动作始终可用：Stub 期收集，bind 后冲刷
@@ -111,6 +125,10 @@ class ApiImpl {
     if (this.#host?.registerCommand) { this.#host.registerCommand(cmd); return }
     this.#pendingCommands.push(cmd)
   }
+  setSystemPrompt(text: string): void {
+    if (this.#host?.setSystemPrompt) { this.#host.setSystemPrompt(text); return }
+    this.#pendingSystemPrompt = text // last-wins：多次设定取最后一次
+  }
   getRegisteredTools(): ToolReg[] {
     // 依赖宿主绑定的能力查询：bindCore 前一调用即抛错（Stub 显式失败）
     if (!this.#host) throw new Error('CAR-STUB: "getRegisteredTools" called before bindCore（启动期显式失败换运行期时序正确）')
@@ -120,8 +138,10 @@ class ApiImpl {
     this.#host = host
     for (const t of this.#pendingTools) host.registerTool?.(t)
     for (const c of this.#pendingCommands) host.registerCommand?.(c)
+    if (this.#pendingSystemPrompt !== null) host.setSystemPrompt?.(this.#pendingSystemPrompt)
     this.#pendingTools = []
     this.#pendingCommands = []
+    this.#pendingSystemPrompt = null
   }
 }
 

package/src/loop/stop.ts

@@ -12,6 +12,7 @@
  *  - 取消：未派发调用补记成对事件（toolCall + 合成错误 toolResult），日志无缺口
  */
 import type { SessionLog } from '../session/log.ts'
+import { CarM8Error } from '../runtime-core/errors.ts'
 
 export type StepOutcome = 'completed' | 'max-tokens' | 'null'
 export type TurnEndReason = 'completed' | 'max-tokens' | 'aborted' | 'error' | 'blocked' | 'interrupted'
@@ -23,6 +24,9 @@ export interface ToolDef {
   concludesTurn?: boolean
   terminate?: boolean
   run(args: Record<string, unknown>): Promise<unknown>
+  // —— 1.4-S1 声明面加法（进模型 ToolDefinition；执行面与声明面同一对象——声明面=授权面红线）——
+  description?: string
+  parameters?: unknown
 }
 /** 模型单步响应（provider 形态；stopReason 为不可变透传——ADR-001） */
 export interface ModelStep {
@@ -193,7 +197,14 @@ export async function runTurn(opts: {
       trail.push({ seq, reason: 'aborted' })
       return { reason: 'aborted', steps, endReasonTrail: trail }
     }
-    const seq = log.append('runtime', 'turnEnd', turnId, null, { reason: 'error', detail: String(e) }).seq
+    // 1.4-S4：CarM8Error 保形——code/userHint/retryable 进 turnEnd（A080001 引导文案「请运行
+    // car doctor」可达用户；非 CarM8Error 维持 String(e) 口径不变）
+    const m8 = e instanceof CarM8Error
+    const detail = m8 ? `${e.slug}: ${e.message}` : String(e)
+    const seq = log.append('runtime', 'turnEnd', turnId, null, {
+      reason: 'error', detail,
+      ...(m8 ? { code: e.code, userHint: e.userHint, retryable: e.retryable } : {}),
+    }).seq
     trail.push({ seq, reason: 'error' })
     return { reason: 'error', steps, endReasonTrail: trail }
   }

package/src/mcp/stdioClient.ts

@@ -0,0 +1,75 @@
+/**
+ * 1.4-S7 · MCP stdio 客户端传输（W1 MCP 工具进 turn）：spawn 子进程 + JSON-RPC 换行分隔 JSON
+ *
+ * 口径（1.4 规划 W1 MCP 块 / D-18）：
+ *  - CAR → 外部 MCP Server 方向（gateway.ts ClientTransport 的真实通道实装——此前仅测试替身）；
+ *    server 侧对偶（宿主 → CAR）见 src/host/stdio.ts；
+ *  - 行协议：请求一行 JSON 写入 server stdin；响应按 id 匹配 pending 表（行解析容错跳过非 JSON 行）；
+ *  - send 内建 30s 超时（fail-visible——gateway.register 的 tools/list 无外层 race，防挂死）；
+ *  - stderr 不透传（server 诊断输出与协议通道隔离）；close = kill（car run 收口调用）。
+ */
+import { spawn, type ChildProcess } from 'node:child_process'
+import type { ClientTransport, JsonRpcResponse } from './gateway.ts'
+
+export interface StdioServerSpec {
+  command: string
+  args?: string[]
+}
+
+export function createStdioClientTransport(spec: StdioServerSpec): ClientTransport & { readonly alive: () => boolean } {
+  const child: ChildProcess = spawn(spec.command, spec.args ?? [], { stdio: ['pipe', 'pipe', 'pipe'] })
+  const pending = new Map<number, (res: JsonRpcResponse) => void>()
+  let buffer = ''
+  let exited = false
+  child.on('exit', () => { exited = true })
+  child.stdout!.on('data', chunk => {
+    buffer += chunk.toString('utf-8')
+    let nl: number
+    while ((nl = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, nl).trim()
+      buffer = buffer.slice(nl + 1)
+      if (!line) continue
+      try {
+        const res = JSON.parse(line) as JsonRpcResponse
+        const settle = pending.get(res.id as number)
+        if (settle) {
+          pending.delete(res.id as number)
+          settle(res)
+        }
+      } catch { /* 非 JSON 行容错跳过（server 诊断污染 stdin 协议通道时不断链） */ }
+    }
+  })
+  child.stderr!.on('data', () => { /* 隔离（见头注释） */ })
+  child.on('error', () => { exited = true })
+
+  const transport: ClientTransport & { readonly alive: () => boolean } = {
+    send(req) {
+      return new Promise((resolve, reject) => {
+        if (!transport.alive()) {
+          reject(new Error('CAR-E-MCP: stdio transport not alive（server 进程已退出）'))
+          return
+        }
+        const timer = setTimeout(() => {
+          pending.delete(req.id as number)
+          reject(new Error('CAR-E-MCP: stdio send timeout (30s)'))
+        }, 30_000)
+        pending.set(req.id as number, res => {
+          clearTimeout(timer)
+          resolve(res)
+        })
+        try {
+          child.stdin!.write(JSON.stringify(req) + '\n')
+        } catch (e) {
+          clearTimeout(timer)
+          pending.delete(req.id as number)
+          reject(e)
+        }
+      })
+    },
+    alive: () => !exited && child.exitCode === null && !child.killed,
+    close: () => {
+      try { child.kill() } catch { /* 已退出 */ }
+    },
+  }
+  return transport
+}