@lqc123qwe/car-runtime 1.9.0 → 1.11.0

package/dist/ptc/schemaRender.js

@@ -0,0 +1,90 @@
+/**
+ * T-2+ · JSON Schema → TS 深度参数渲染（M5 · DEC-4 预埋项转正，原 M3-S16 评估项）
+ *
+ * 口径（M3系统设计增补 T-2 预埋 / M4演进规划 RC-3 / M5 DEC-4 用户裁决①）：
+ *  - 渲染源仍为注册表快照同一条目（声明面 = 授权面红线不变）——inputSchema 只是
+ *    ToolBridge/McpToolDefinition 上的附加字段，不引入独立声明通道；
+ *  - 深度转换 **fail-visible**：超深 / 不支持节点（$ref、not）/ 畸形输入落 `unknown`
+ *    并以内联注释标记原因（禁止静默截断——N1「零静默」纪律在类型面上的延伸）；
+ *  - 输入 = MCP tools/list 的 inputSchema（JSON Schema 2020-12 常用子集）。
+ */
+/** 递归深度上限：超过即 fail-visible 落 unknown（防 schema 爆栈与 prompt 膨胀） */
+const MAX_DEPTH = 6;
+function literal(v) {
+    return typeof v === 'string' ? JSON.stringify(v) : String(v);
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** 属性名合法标识符则裸写，否则 JSON 字符串引号（保留字在 TS 属性位合法，无需处理） */
+function propKey(name) {
+    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+/**
+ * JSON Schema 节点 → TS 类型表达式（深度递归）。
+ * 任何不可判定路径返回带内联原因标记的 unknown 字符串（形如 unknown + 注释）——可读、可测、不静默。
+ */
+export function jsonSchemaToTs(schema, depth = 0) {
+    if (depth > MAX_DEPTH)
+        return 'unknown /* depth>' + MAX_DEPTH + ' */';
+    if (!isObject(schema))
+        return 'unknown /* malformed */';
+    // $ref 无法在无注册表上下文解析 → fail-visible（不做猜测性内联）
+    if (typeof schema.$ref === 'string')
+        return 'unknown /* unsupported:$ref */';
+    // const / enum → 字面量联合（优先于 type）
+    if ('const' in schema)
+        return literal(schema.const);
+    if (Array.isArray(schema.enum) && schema.enum.length > 0)
+        return schema.enum.map(literal).join(' | ');
+    // 组合器：anyOf/oneOf → 联合；allOf → 交叉
+    for (const key of ['anyOf', 'oneOf']) {
+        if (Array.isArray(schema[key]) && schema[key].length > 0) {
+            return schema[key].map((s) => jsonSchemaToTs(s, depth + 1)).join(' | ');
+        }
+    }
+    if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
+        return schema.allOf.map((s) => jsonSchemaToTs(s, depth + 1)).join(' & ');
+    }
+    if ('not' in schema)
+        return 'unknown /* unsupported:not */';
+    // type 可能是单值或数组（['string','null'] → 联合）
+    const types = Array.isArray(schema.type) ? schema.type : typeof schema.type === 'string' ? [schema.type] : [];
+    if (types.includes('object') || 'properties' in schema || 'additionalProperties' in schema) {
+        const props = isObject(schema.properties) ? schema.properties : {};
+        const required = Array.isArray(schema.required) ? schema.required.filter((r) => typeof r === 'string') : [];
+        const parts = [];
+        for (const [name, sub] of Object.entries(props)) {
+            const opt = required.includes(name) ? '' : '?';
+            parts.push(`${propKey(name)}${opt}: ${jsonSchemaToTs(sub, depth + 1)}`);
+        }
+        const addl = schema.additionalProperties;
+        if (isObject(addl)) {
+            parts.push(`[k: string]: ${jsonSchemaToTs(addl, depth + 1)}`);
+        }
+        else if (parts.length === 0) {
+            // {} / { additionalProperties: true } / 空 object → 任意键值（TS 语法要求 index signature 兜底）
+            return 'Record<string, unknown>';
+        }
+        return `{ ${parts.join('; ')} }`;
+    }
+    if (types.includes('array') || 'items' in schema || 'prefixItems' in schema) {
+        if (Array.isArray(schema.prefixItems) && schema.prefixItems.length > 0) {
+            return `[${schema.prefixItems.map((s) => jsonSchemaToTs(s, depth + 1)).join(', ')}]`;
+        }
+        if ('items' in schema) {
+            // 2020-12：items 为单 schema（draft-07 数组形态按 tuple 兼容处理）
+            if (Array.isArray(schema.items)) {
+                return `[${schema.items.map((s) => jsonSchemaToTs(s, depth + 1)).join(', ')}]`;
+            }
+            return `${jsonSchemaToTs(schema.items, depth + 1)}[]`;
+        }
+        return 'unknown[]';
+    }
+    if (types.length > 0) {
+        const mapped = types.map((t) => (t === 'integer' ? 'number' : t === 'string' ? 'string' : t === 'number' ? 'number' : t === 'boolean' ? 'boolean' : t === 'null' ? 'null' : 'unknown /* unsupported:type:' + String(t) + ' */'));
+        return [...new Set(mapped)].join(' | ');
+    }
+    // 无 type / 组合器的开放 schema（true、{}）→ unknown
+    return 'unknown /* open */';
+}

package/dist/ptc/sdk.d.ts

@@ -0,0 +1,27 @@
+/**
+ * T-2 · PTC TS SDK 渲染（M3-S15）+ 深度参数渲染转正（M5 · DEC-4）
+ *
+ * 口径（M3系统设计增补 T-2 / dsh 一手口径 tools/src/index.ts:26,97）：
+ *  - SDK = 从工具注册表快照渲染进 system prompt 的 TS 声明（**非 .d.ts 文件生成**）；
+ *  - **声明面/授权面一致性红线**：渲染源与授权消费源必须同一 Map 快照——模型看到的工具集合
+ *    即授权门放行的集合（多渲一个 = 无授权执行面，少渲一个 = 授权白给）；
+ *  - 参数形状优先级：paramHint（手写 TS 字面量）> inputSchema（JSON Schema 深度转换，
+ *    M5 DEC-4 转正，见 ./schemaRender.ts）> `args: unknown`（无形状声明时的 fail-visible 默认）。
+ */
+import type { ToolBridge } from './runCode.ts';
+export interface SdkToolDef {
+    name: string;
+    description?: string;
+    /** 参数形状提示（TS 字面量），如 '{ x: number; y: number }'——手写声明，优先级最高 */
+    paramHint?: string;
+    /** JSON Schema（MCP tools/list inputSchema）——深度转换渲染，paramHint 缺省时生效 */
+    inputSchema?: unknown;
+}
+/** 渲染 SDK 声明：注入 PTC 程序体上文的 TS 类型面（模型据此写代码） */
+export declare function renderSdk(defs: Iterable<SdkToolDef>): string;
+/** 从 ToolBridge 注册表快照渲染（包装：接受可选 description/paramHint/inputSchema 的注册表条目） */
+export declare function renderSdkFromRegistry(registry: Map<string, ToolBridge & {
+    description?: string;
+    paramHint?: string;
+    inputSchema?: unknown;
+}>): string;

package/dist/ptc/sdk.js

@@ -0,0 +1,23 @@
+import { jsonSchemaToTs } from './schemaRender.js';
+/** 渲染单工具参数形状（优先级：paramHint > inputSchema 深渲 > unknown） */
+function renderArgsHint(d) {
+    if (d.paramHint)
+        return d.paramHint;
+    if (d.inputSchema !== undefined)
+        return jsonSchemaToTs(d.inputSchema);
+    return 'args: unknown';
+}
+/** 渲染 SDK 声明：注入 PTC 程序体上文的 TS 类型面（模型据此写代码） */
+export function renderSdk(defs) {
+    const lines = ['// CAR PTC SDK —— 以下声明与授权门消费同一注册表快照（声明面=授权面）', 'declare const tools: {'];
+    for (const d of defs) {
+        const hint = renderArgsHint(d);
+        lines.push(`  ${JSON.stringify(d.name)}: (${hint}) => Promise<unknown>${d.description ? ` // ${d.description}` : ''}`);
+    }
+    lines.push('};');
+    return lines.join('\n');
+}
+/** 从 ToolBridge 注册表快照渲染（包装：接受可选 description/paramHint/inputSchema 的注册表条目） */
+export function renderSdkFromRegistry(registry) {
+    return renderSdk([...registry.entries()].map(([name, d]) => ({ name, description: d.description, paramHint: d.paramHint, inputSchema: d.inputSchema })));
+}

package/dist/ptc/worker-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ptc/worker-entry.js

@@ -0,0 +1,71 @@
+/**
+ * PTC worker 入口（M3-S14）：隔离执行 PTC 程序体
+ *
+ * 协议：
+ *  - workerData: { code, budget }；
+ *  - 程序体 = async 函数体（顶层 await/return 支持，dsh 一手口径）；
+ *  - tools proxy：await tools.<name>(args) → postMessage {type:'tool'} → 主线程执行 → {type:'tool-result'} 回传；
+ *  - 预算：maxWallMs 计时超限 → done(error='budget-exceeded (maxWallMs)')；maxOutputBytes 序列化后检查；
+ *  - done 消息单发即退——程序体 = 一次原子 toolCall（收口点唯一在 executor 返回）；
+ *  - 1.8-D31：done 加法 span 字段（程序窗口 startMs/endMs——worker 侧 Date.now 计时，
+ *    worker_threads 同进程同时钟域；主线程 relay 收口 car.ptc span——单 exporter 纪律，
+ *    本隔离体零独立出站通道；程序未启动〔wallTimer 抢先〕不产 span 字段）。
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+const port = parentPort;
+const pending = new Map();
+port.on('message', (m) => {
+    if (m.type === 'tool-result' && m.callId) {
+        const p = pending.get(m.callId);
+        if (!p)
+            return;
+        pending.delete(m.callId);
+        if (m.error)
+            p.reject(new Error(m.error));
+        else
+            p.resolve(m.result);
+    }
+});
+const tools = new Proxy({}, {
+    get: (_, name) => (args) => new Promise((resolve, reject) => {
+        const callId = Math.random().toString(36).slice(2);
+        pending.set(callId, { resolve, reject });
+        port.postMessage({ type: 'tool', callId, name, args });
+    }),
+});
+const budget = workerData.budget;
+// 1.8-D31：程序窗口计时（null = 程序未启动——wallTimer 抢先不产 span 字段）
+let spanStart = null;
+const finish = (msg) => {
+    port.postMessage({ ...msg, ...(spanStart !== null ? { span: { startMs: spanStart, endMs: Date.now() } } : {}) });
+    setTimeout(() => process.exit(0), 50); // 让消息冲刷
+};
+const wallTimer = setTimeout(() => finish({ type: 'done', error: `budget-exceeded (maxWallMs=${budget.maxWallMs})——预算到期为资源护栏，不掐 turn（工具错误结果交回模型）` }), budget.maxWallMs);
+void (async () => {
+    try {
+        const code = workerData.code;
+        // erasable-only 的执行端：eval 前剥离类型（Node 22.13+ 内置 stripTypeScriptTypes）——
+        // 程序体是 erasable TS（含类型注解），new Function 是纯 JS 求值器，不剥离则注解即 SyntaxError
+        const { stripTypeScriptTypes } = await import('node:module');
+        // stripTypeScriptTypes 以「模块」语义解析——片段含顶层 return 会报 ERR_INVALID_TYPESCRIPT_SYNTAX；
+        // 故先包成 export default 箭头函数再剥离，剥离后还原为 return 表达式（程序体含字面 export default 不受支持，见 erasable 禁项）
+        const wrapped = 'export default async () => {\n' + code + '\n}';
+        const js = stripTypeScriptTypes(wrapped, { mode: 'strip' });
+        const body = js.replace(/^export default /, 'return ');
+        // 程序体 = async 函数体（顶层 await/return）；tools 为受控 proxy（仅显式调用，无宿主 import 面）
+        const fn = new Function('tools', '"use strict";\n' + body + '\n');
+        spanStart = Date.now();
+        const result = await fn(tools)();
+        clearTimeout(wallTimer);
+        const out = JSON.stringify(result ?? null);
+        if (Buffer.byteLength(out) > budget.maxOutputBytes) {
+            finish({ type: 'done', error: `budget-exceeded (maxOutputBytes=${budget.maxOutputBytes})` });
+            return;
+        }
+        finish({ type: 'done', result: JSON.parse(out) });
+    }
+    catch (e) {
+        clearTimeout(wallTimer);
+        finish({ type: 'done', error: String(e) });
+    }
+})();

package/dist/release-audit.jsonl

@@ -0,0 +1,4 @@
+{"stage":"archive","detail":"git archive HEAD → car-runtime-1.11.0.tgz（328238 bytes，树哈希锚定）","ts":1791363366364}
+{"stage":"sha256sums","detail":"SHA256SUMS e33ef93a776d2910…（裸字节复核通过）","ts":1791363366365}
+{"stage":"sbom","detail":"51 个组件（运行时依赖 0 项）","ts":1791363366373}
+{"stage":"cosign-keyless","detail":"signed car-runtime-1.11.0.tgz (keyless OIDC + Rekor)","ts":1791363368159}

package/dist/runtime-core/chatStep.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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 落（本层不重复）；
+ *  7. 1.11-S2（D-33 / 计量设计 §3.3）：流尾 usage chunk → 'runtime'/'usage' 请求级事实落链
+ *     （缺失 = provider 未回/流中断/畸形，禁补造；actor='runtime'、model_visible=0 不进模型
+ *     消息流）——turn 级聚合在 stop.ts 收口单点，本层不做跨请求状态。
+ */
+import type { SessionLog } from '../session/log.ts';
+import { type ModelStep } from '../loop/stop.ts';
+import type { RuntimeCore } from './llm.ts';
+import type { ToolDefinition } from './types.ts';
+export interface ChatStepOptions {
+    core: RuntimeCore;
+    log: SessionLog;
+    turnId: string;
+    /** 模型名（provider 侧路由） */
+    model: string;
+    /** 工具声明面（ToolDefinition 含 declaredSideEffect；不出站权限面仅 schema） */
+    tools: ToolDefinition[];
+    maxTokens?: number;
+    adapterId?: string;
+    /** 1.4-S4（D-19）：turn 取消信号——chunk 间隙与流结束后（finish 检查前）检查，命中抛 TurnAborted */
+    signal?: {
+        aborted: boolean;
+    };
+}
+/** ModelStep 加法扩展：脱敏计数留痕（S15 secretsRedacted 同名口径） */
+export type ChatStepResult = ModelStep & {
+    secretsRedacted: number;
+};
+export declare function chatStep(opts: ChatStepOptions): Promise<ChatStepResult>;

package/dist/runtime-core/chatStep.js

@@ -0,0 +1,121 @@
+import { TurnAborted } from '../loop/stop.js';
+import { StreamRedactor } from './redaction.js';
+import { scanSecrets } from '../security/secrets.js';
+import { providerUnreachable } from './errors.js';
+export async function chatStep(opts) {
+    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 对齐）；
+    //    toolCall 事件投影形态为 { role:'assistant', toolCall }（log.ts 口径）——此处归一化为
+    //    content {toolCall} 载荷（适配器历史回路映射的唯一消费源）。
+    //    1.5-BUG-1：此前仅透传 m.content，toolCall 属性被丢弃——工具调用历史在后续请求
+    //    静默消失（真实 provider 对无 tool_calls 前驱的 tool 消息直接 400）；anthropic E2E
+    //    生产调用点核查（1.5-GO-5）暴露，openai-compat 同样受益。
+    const messages = log.deriveMessages().map(m => ({
+        role: m.role,
+        content: m.toolCall !== undefined
+            ? { toolCall: m.toolCall }
+            : m.content,
+    }));
+    // 4. 流式消费（3. 凭据解析在适配器首块前，A080001 由此传播）
+    const redactor = new StreamRedactor();
+    let text = '';
+    const calls = new Map();
+    let stopReason;
+    let errorDetail;
+    let usage;
+    const stream = core.chat({
+        model,
+        messages,
+        tools,
+        ...(maxTokens != null ? { maxTokens } : {}),
+        ...(adapterId ? { adapterId } : {}),
+        ...(opts.signal ? { signal: opts.signal } : {}),
+        ...(opts.log.sessionId ? { metadata: { sessionId: opts.log.sessionId, turnId, traceId: `${opts.log.sessionId}:${turnId}` } } : {}),
+    });
+    for await (const chunk of stream) {
+        // 1.4-S4（D-19）：chunk 间隙取消——此刻 assistant 尚未落链（流完才 append），无半截消息
+        if (opts.signal?.aborted)
+            throw new TurnAborted();
+        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.usage)
+            usage = chunk.usage; // D-33：附着于最后一个 chunk——后到覆盖
+        if (chunk.finishReason !== undefined)
+            stopReason = chunk.finishReason === 'aborted' ? 'error' : chunk.finishReason;
+    }
+    // 1.4-S4（D-19）：finish 检查前先查取消（适配器取消路径静默收口无 finishReason——
+    // 必须先于此处的契约兜底，否则取消被误判为适配器违规）
+    if (opts.signal?.aborted)
+        throw new TurnAborted();
+    if (stopReason === undefined) {
+        // 适配器层已保证首 finishReason（AL-05）；防御性兜底显式化
+        throw new Error('CAR-E-LLM-FINISH: 流结束无 finishReason（适配器契约违规）');
+    }
+    text += redactor.flush();
+    // 1.11-S2（D-33 / 计量设计 §3.3）：请求级 usage 事实落链（拿到 usage 的最后一个 chunk 即请求
+    // 收尾；撞限/异常 turn 照常落——截断前已完成请求的 usage 事实不吞）。缺失 = provider 未回，
+    // 禁补造；actor='runtime'、不进模型消息流（deriveMessages 不投影 usage，§2.5 红线）
+    if (usage) {
+        log.append('runtime', 'usage', turnId, {
+            model: usage.model,
+            adapterId: usage.adapterId,
+            input: usage.inputTokens,
+            output: usage.outputTokens,
+            cacheRead: usage.cacheReadTokens,
+            cacheCreation: usage.cacheCreationTokens,
+            providerRaw: usage.providerRaw,
+        });
+    }
+    // 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 = [];
+        for (const [idx, c] of [...calls.entries()].sort((a, b) => a[0] - b[0])) {
+            if (!c.name)
+                continue;
+            let args;
+            try {
+                args = c.argsBuf ? JSON.parse(c.argsBuf) : {};
+            }
+            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/dist/runtime-core/credentials.d.ts

@@ -0,0 +1,49 @@
+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 变量（doctor 存在性探测等诊断面复用；值永不打印） */
+export declare function providerEnvVars(provider: string): string[];
+/** keychain 服务名（命名空间隔离：car-runtime/<provider>） */
+export declare function keychainService(provider: string): string;
+interface KeychainChannel {
+    reader: ((service: string) => string | null) | null;
+    note: string;
+}
+/** 平台 keychain 通道探测：命令在场（darwin/linux）→ 真实读取器；无读通道（win32）→ 显式 null */
+export declare function probeKeychainChannel(platform?: NodeJS.Platform): KeychainChannel;
+export declare class CredentialService {
+    #private;
+    constructor(opts?: {
+        keychainReader?: (service: string) => string | null;
+        platform?: NodeJS.Platform;
+    });
+    /** keychain 通道状态（doctor 展示/测试断言；缺席显式登记不静默） */
+    get channelStatus(): {
+        available: boolean;
+        note: string;
+    };
+    /**
+     * 解析凭据引用（天然幂等；返回值不含明文）。
+     * 检索顺序：keychain →（显式开启时）env；全落空 = A080001。
+     */
+    resolve(provider: string, opts?: CredentialResolveOptions): CredentialRef;
+    /** 按引用取明文（仅 provider 适配器请求时点调用；每次经审计留痕，值不入日志不入错误） */
+    reveal(ref: CredentialRef, opts?: CredentialResolveOptions): string;
+}
+export {};

package/dist/runtime-core/credentials.js

@@ -0,0 +1,118 @@
+/**
+ * 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.js';
+/** provider → 候选 env 变量（按序检索；CAR_LLM_API_KEY 为通用兜底） */
+const PROVIDER_ENV_VARS = {
+    'openai-compat': ['OPENAI_API_KEY'],
+    anthropic: ['ANTHROPIC_API_KEY'],
+};
+const GENERIC_ENV_VARS = ['CAR_LLM_API_KEY'];
+/** provider 候选 env 变量（doctor 存在性探测等诊断面复用；值永不打印） */
+export function providerEnvVars(provider) {
+    return [...(PROVIDER_ENV_VARS[provider] ?? []), ...GENERIC_ENV_VARS];
+}
+/** keychain 服务名（命名空间隔离：car-runtime/<provider>） */
+export function keychainService(provider) {
+    return `car-runtime/${provider}`;
+}
+/** 平台 keychain 通道探测：命令在场（darwin/linux）→ 真实读取器；无读通道（win32）→ 显式 null */
+export function probeKeychainChannel(platform = process.platform) {
+    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 {
+    #channel;
+    #platform;
+    constructor(opts = {}) {
+        this.#platform = opts.platform ?? process.platform;
+        this.#channel = opts.keychainReader
+            ? { reader: opts.keychainReader, note: 'injected reader' }
+            : probeKeychainChannel(this.#platform);
+    }
+    /** keychain 通道状态（doctor 展示/测试断言；缺席显式登记不静默） */
+    get channelStatus() {
+        return { available: this.#channel.reader !== null, note: this.#channel.note };
+    }
+    /**
+     * 解析凭据引用（天然幂等；返回值不含明文）。
+     * 检索顺序：keychain →（显式开启时）env；全落空 = A080001。
+     */
+    resolve(provider, opts = {}) {
+        const env = opts.env ?? process.env;
+        const searched = [];
+        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 = providerEnvVars(provider);
+            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, opts = {}) {
+        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/dist/runtime-core/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare class CarM8Error extends Error {
+    /** 六位错误码（§3.5.1 注册表） */
+    readonly code: M8ErrorCode;
+    /** CAR-E-* 代码库前缀（与 CAR-E-DEPCYCLE 等同风格） */
+    readonly slug: string;
+    /** 用户文案（§3.5.1 注册表原文） */
+    readonly userHint?: string | undefined;
+    /** 重试建议（A080001 不重试 / B080001 退避后重试） */
+    readonly retryable: boolean;
+    constructor(
+    /** 六位错误码（§3.5.1 注册表） */
+    code: M8ErrorCode, 
+    /** CAR-E-* 代码库前缀（与 CAR-E-DEPCYCLE 等同风格） */
+    slug: string, message: string, 
+    /** 用户文案（§3.5.1 注册表原文） */
+    userHint?: string | undefined, 
+    /** 重试建议（A080001 不重试 / B080001 退避后重试） */
+    retryable?: boolean);
+}
+export declare function credentialMissing(provider: string, searched: string[]): CarM8Error;
+export declare function providerUnreachable(detail: string): CarM8Error;

package/dist/runtime-core/errors.js

@@ -0,0 +1,36 @@
+/**
+ * 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 class CarM8Error extends Error {
+    code;
+    slug;
+    userHint;
+    retryable;
+    constructor(
+    /** 六位错误码（§3.5.1 注册表） */
+    code, 
+    /** CAR-E-* 代码库前缀（与 CAR-E-DEPCYCLE 等同风格） */
+    slug, message, 
+    /** 用户文案（§3.5.1 注册表原文） */
+    userHint, 
+    /** 重试建议（A080001 不重试 / B080001 退避后重试） */
+    retryable = false) {
+        super(`${slug}: ${message}（${code}）`);
+        this.code = code;
+        this.slug = slug;
+        this.userHint = userHint;
+        this.retryable = retryable;
+        this.name = 'CarM8Error';
+    }
+}
+export function credentialMissing(provider, searched) {
+    return new CarM8Error('A080001', 'CAR-E-CRED-MISSING', `未找到模型服务凭据（provider=${provider}，已检索：${searched.join('、') || '无可用通道'}）`, '未找到模型服务凭据，请运行 car doctor', false);
+}
+export function providerUnreachable(detail) {
+    return new CarM8Error('B080001', 'CAR-E-LLM-UNREACHABLE', `LLM Provider 不可达/重试耗尽：${detail}`, '模型服务暂时不可用，本轮已停止', true);
+}