@jingyi0605/codingns4dsh 0.1.1 → 0.1.7-rc.2

package/data/build/dist/host/cli-adapters/dsh-message-projector.js

@@ -1,5 +1,25 @@
 import { CodingNsDshToolHistoryProjector } from './dsh-tool-history.js';
 import { CodingNsAgentEventNormalizer, } from './stream-normalizer.js';
+/**
+ * 把驱动的 Provider 口径 usage 映射成 DSH `TokenUsage` 的互斥桶口径。
+ *
+ * DSH 约定 `inputTokens` 只含未缓存输入，计费输入 = inputTokens + 缓存读写，而
+ * 驱动层已经用 `usageChunk` 按各 Provider 的字段语义折算出 `uncachedInputTokens`
+ * （Codex、Command Code 的 inputTokens 含缓存命中，Anthropic 风格的 input 不含）。
+ * 这里必须以该字段为准；直接把驱动事件里的 `inputTokens` 当成未缓存输入写进 DSH，
+ * 会让 token-meter 把缓存读取重复计入分母：缓存命中率被腰斩，上下文占用翻倍。
+ */
+function toDshTokenUsage(event) {
+    // 没有缓存分桶时 `inputTokens` 本身就是全部输入，也就是未缓存输入。
+    const inputTokens = event.uncachedInputTokens ?? event.inputTokens;
+    return {
+        inputTokens: Math.max(0, inputTokens),
+        outputTokens: event.outputTokens,
+        ...(event.cacheReadTokens === undefined ? {} : { cacheReadTokens: event.cacheReadTokens }),
+        ...(event.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: event.cacheWriteTokens }),
+        ...(event.totalTokens === undefined ? {} : { totalTokens: event.totalTokens }),
+    };
+}
 /**
  * 所有外部 Agent 共用的 DSH 消息投影器。
  *
@@ -16,6 +36,8 @@ export class CodingNsDshMessageProjector {
     reasoningText = '';
     textText = '';
     finished = false;
+    /** 只要收到正文、工具、usage 或交互事件，就说明 Provider 确实产出了结果。 */
+    receivedProviderEvent = false;
     constructor(options) {
         this.options = options;
         this.toolHistory = new CodingNsDshToolHistoryProjector(options.nativeSessions, options.sessionId, options.adapterId);
@@ -26,6 +48,9 @@ export class CodingNsDshMessageProjector {
     async push(event) {
         if (this.finished)
             return [];
+        if (event.type !== 'session-binding' && event.type !== 'finish') {
+            this.receivedProviderEvent = true;
+        }
         if (event.type === 'usage')
             this.recordUsageSample(event);
         const projected = [];
@@ -40,6 +65,9 @@ export class CodingNsDshMessageProjector {
     async complete(reason = 'stop') {
         if (this.finished)
             return [];
+        if (reason === 'stop' && !this.receivedProviderEvent) {
+            return this.fail('CODINGNS_PROVIDER_EMPTY_RESPONSE: Provider 未返回任何有效事件。');
+        }
         const projected = await this.flushUsage();
         projected.push(...await this.project({ type: 'finish', reason }));
         return projected;
@@ -68,13 +96,9 @@ export class CodingNsDshMessageProjector {
      * 提前向 LLM 流发送第二个 usage，只写入 assistant/attempt 供上下文计量投影使用。
      */
     recordUsageSample(event) {
+        // assistant/attempt 同样是 DSH 会话记录，usage 必须按 DSH 的互斥桶口径落盘。
         const usage = {
-            inputTokens: event.inputTokens,
-            outputTokens: event.outputTokens,
-            ...(event.cacheReadTokens === undefined ? {} : { cacheReadTokens: event.cacheReadTokens }),
-            ...(event.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: event.cacheWriteTokens }),
-            ...(event.uncachedInputTokens === undefined ? {} : { uncachedInputTokens: event.uncachedInputTokens }),
-            ...(event.totalTokens === undefined ? {} : { totalTokens: event.totalTokens }),
+            ...toDshTokenUsage(event),
             ...(event.cacheHitRate === undefined ? {} : { cacheHitRate: event.cacheHitRate }),
             ...(event.contextWindow === undefined ? {} : { contextWindow: event.contextWindow }),
             ...(event.contextTokens === undefined ? {} : { contextTokens: event.contextTokens }),
@@ -85,6 +109,7 @@ export class CodingNsDshMessageProjector {
                 provider: this.options.adapterId,
                 model: this.options.modelId ?? this.options.adapterId,
                 contextWindow: event.contextWindow,
+                confirmed: true,
             });
         }
         this.options.nativeSessions?.appendUsageSample?.(this.options.sessionId, usage);
@@ -102,13 +127,9 @@ export class CodingNsDshMessageProjector {
             case 'message-boundary':
                 return this.closeMessageBlock(event.channel);
             case 'step-boundary':
-                // DSH 0.1.7 的 Chat 分组器会把同一 Turn 中没有可见 assistant
-                // 回复的连续工具节点合并到一个 process group。Codex 的工具已经
-                // 在外部进程完成，分段之间没有 DSH 原生 assistant 文本可供分组器
-                // 识别，因此写入一个 Markdown 引用定义作为不可见的回复边界。
-                // 必须从新行开始；DSH UI 会忽略 definition 节点，而不是把 HTML 当注释解析。
-                // 该内容不会显示给用户，也不会改变工具的原生 step 坐标。
-                return this.appendDelta('text', '\n\n[//]: # (codingns-step-boundary)');
+                // step 边界由 DSH 原生 turn/step 事件表达，不再伪造 Markdown 文本。
+                // 伪造的空文本会被 Chat 渲染成额外的空白块，导致相邻 step 间距异常。
+                return [];
             case 'tool-event':
                 return this.externalToolChunk(this.toolHistory.observe(event));
             case 'permission-request':
@@ -118,23 +139,16 @@ export class CodingNsDshMessageProjector {
                 await this.requestQuestions(event);
                 return [];
             case 'usage':
-                return [{
-                        type: 'usage',
-                        usage: {
-                            inputTokens: event.inputTokens,
-                            outputTokens: event.outputTokens,
-                            ...(event.cacheReadTokens === undefined ? {} : { cacheReadTokens: event.cacheReadTokens }),
-                            ...(event.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: event.cacheWriteTokens }),
-                            ...(event.uncachedInputTokens === undefined ? {} : { uncachedInputTokens: event.uncachedInputTokens }),
-                            ...(event.totalTokens === undefined ? {} : { totalTokens: event.totalTokens }),
-                            ...(event.cacheHitRate === undefined ? {} : { cacheHitRate: event.cacheHitRate }),
-                            ...(event.contextWindow === undefined ? {} : { contextWindow: event.contextWindow }),
-                            ...(event.contextTokens === undefined ? {} : { contextTokens: event.contextTokens }),
-                            ...(event.contextUsageRatio === undefined ? {} : { contextUsageRatio: event.contextUsageRatio }),
-                        },
-                    }];
+                return [{ type: 'usage', usage: toDshTokenUsage(event) }];
             case 'session-binding':
                 return [];
+            case 'context-compaction':
+                this.options.nativeSessions?.appendCompactionEvent?.(this.options.sessionId, {
+                    ...event,
+                    provider: event.provider ?? this.options.adapterId,
+                    model: event.model ?? this.options.modelId ?? this.options.adapterId,
+                });
+                return [];
             case 'finish':
                 const closed = [
                     ...this.closeMessageBlock('reasoning'),
@@ -144,6 +158,8 @@ export class CodingNsDshMessageProjector {
                 this.toolHistory.finalize(event.reason, failureMessage);
                 closed.push({ type: 'finish', reason: toDshFinishReason(event.reason, failureMessage) });
                 return closed;
+            default:
+                return assertNeverNormalizedEvent(event);
         }
     }
     appendDelta(channel, text) {
@@ -236,6 +252,9 @@ export class CodingNsDshMessageProjector {
         await responder(response);
     }
 }
+function assertNeverNormalizedEvent(value) {
+    throw new Error(`未支持的 DSH 事件类型: ${String(value.type ?? 'unknown')}`);
+}
 function toDshFinishReason(reason, failureMessage) {
     if (reason === 'cancel') {
         return { kind: 'aborted', failure: { message: failureMessage ?? '外部 Agent 执行已取消', code: 'ABORTED' } };

package/data/build/dist/host/cli-adapters/dsh-tool-history.js

@@ -316,8 +316,25 @@ function toolResultMeta(name, argumentsJson) {
     if (name !== 'edit' && name !== 'write')
         return {};
     const args = parseRecord(argumentsJson);
+    if (name === 'edit' && Array.isArray(args?.changes)) {
+        const diffs = args.changes.flatMap((value) => {
+            if (!isRecord(value))
+                return [];
+            const path = stringValue(value.file_path ?? value.path);
+            const diff = stringValue(value.diff ?? value.patch);
+            if (path === null || diff === null)
+                return [];
+            return [unifiedDiffMeta(path, diff, stringValue(value.kind))];
+        });
+        return diffs.length > 0 ? { meta: { diffs } } : {};
+    }
     const path = stringValue(args?.file_path);
     const newText = stringValue(name === 'edit' ? args?.new_string : args?.content);
+    if (name === 'edit' && path !== null) {
+        const diff = stringValue(args?.diff ?? args?.patch);
+        if (diff !== null)
+            return { meta: { diffs: [unifiedDiffMeta(path, diff, stringValue(args?.kind))] } };
+    }
     if (path === null || newText === null)
         return {};
     const oldText = name === 'edit' ? stringValue(args?.old_string) : null;
@@ -327,6 +344,26 @@ function toolResultMeta(name, argumentsJson) {
         },
     };
 }
+function unifiedDiffMeta(path, diff, kind) {
+    const oldLines = [];
+    const newLines = [];
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('--- ') || line.startsWith('+++ ') || line.startsWith('@@'))
+            continue;
+        if (line.startsWith('-'))
+            oldLines.push(line.slice(1));
+        else if (line.startsWith('+'))
+            newLines.push(line.slice(1));
+        else if (line.startsWith(' ')) {
+            const context = line.slice(1);
+            oldLines.push(context);
+            newLines.push(context);
+        }
+    }
+    const oldText = kind === 'add' || kind === 'create' ? null : oldLines.join('\n');
+    const newText = kind === 'delete' || kind === 'remove' ? '' : newLines.join('\n');
+    return { path, oldText, newText };
+}
 /** Command Code 等 Provider 会把文本块包成 JSON；原生结果只展示真正文本。 */
 function normalizeToolOutput(value) {
     if (value === '')

package/data/build/dist/host/cli-adapters/feature.js

@@ -109,24 +109,42 @@ export function createCliAdaptersFeature(options = {}) {
                 const dispose = events.on('llm/stream', async function* (options, next) {
                     const value = asRecord(options);
                     const sessionId = typeof value?.sessionId === 'string' ? value.sessionId : '';
-                    const config = sessionId ? registry.getSession(sessionId) : { adapterId: 'dsh' };
+                    if (value?.purpose === 'session-title' || value?.purpose === 'compaction') {
+                        yield* next();
+                        return;
+                    }
+                    const storedConfig = sessionId ? registry.getSession(sessionId) : { adapterId: 'dsh' };
+                    // DSH 原生请求仍会携带当前模型提供方。旧会话在重载后可能暂时
+                    // 被恢复成 dsh，但 provider 已明确指向外部 Agent；继续旁路会让
+                    // 第二轮直接落入 DSH 空流，并丢失外部驱动的 usage/context 修正。
+                    const dshSelection = readDshSelection(value);
+                    const messages = Array.isArray(value?.messages) ? value.messages.filter(isMessage) : [];
+                    const selectedExternalAdapter = selectExternalAdapter(dshSelection.providerId, inferMessageAdapter(messages), registry);
+                    const config = storedConfig.adapterId === 'dsh' && selectedExternalAdapter !== undefined
+                        ? {
+                            adapterId: selectedExternalAdapter,
+                            ...(dshSelection.modelId === undefined ? {} : { modelId: dshSelection.modelId }),
+                            ...(dshSelection.effortId === undefined ? {} : { effortId: dshSelection.effortId }),
+                        }
+                        : storedConfig;
+                    // DSH 首轮请求可能只通过 provider 临时选择外部 Agent，第二轮请求通常不再携带
+                    // provider。必须在路由决定后立即持久化绑定，否则下一轮会在进入 Registry 前退回 dsh。
+                    if (sessionId !== '' && storedConfig.adapterId === 'dsh' && selectedExternalAdapter !== undefined) {
+                        registry.setSession(sessionId, config);
+                    }
                     if (config.adapterId === 'dsh') {
-                        const selection = readDshSelection(value);
+                        const selection = dshSelection;
                         if (sessionId !== '' && (selection.modelId !== undefined || selection.effortId !== undefined)) {
                             registry.setSession(sessionId, { adapterId: 'dsh', ...selection });
                         }
-                        yield* next();
+                        yield* guardDshNativeStream(next);
                         return;
                     }
-                    if (value?.purpose === 'session-title' || value?.purpose === 'compaction') {
-                        yield* next();
-                        return;
-                    }
-                    const messages = Array.isArray(value?.messages) ? value.messages.filter(isMessage) : [];
                     const cwd = resolveSessionCwd(context.services.nativeSessions, sessionId, value);
                     // 只有 Provider 驱动明确维护了稳定的 turn 分段，才把工具边界映射为 DSH step。
-                    // OpenCode、Command Code 会在同一轮连续产出工具和 usage，强行切 step 会让
-                    // token-meter 在下一条 usage 到达前失去投影，表现为上下文组件反复卸载。
+                    // Command Code、Codex 会在下一个 assistant 消息处结束当前 step；未声明分段
+                    // 支持的驱动（如 OpenCode）仍把整轮保持在一个 step，避免 token-meter 在下一
+                    // 条 usage 到达前失去投影。
                     const input = {
                         sessionId,
                         messages,
@@ -199,6 +217,48 @@ export function createCliAdaptersFeature(options = {}) {
         },
     };
 }
+/**
+ * DSH 原生 Provider 可能只返回一个 finish(stop)。不能把这个空回合当作成功，
+ * 否则 Session 会落下一条空 assistant/message，用户只能看到“一秒结束”。
+ */
+async function* guardDshNativeStream(next) {
+    let meaningful = false;
+    const terminal = [];
+    for await (const chunk of next()) {
+        if (isDshFinishChunk(chunk)) {
+            terminal.push(chunk);
+            continue;
+        }
+        meaningful ||= isMeaningfulDshChunk(chunk);
+        yield chunk;
+    }
+    if (meaningful) {
+        for (const chunk of terminal)
+            yield chunk;
+        return;
+    }
+    const message = 'CODINGNS_PROVIDER_EMPTY_RESPONSE: DSH Provider 未返回任何有效事件。';
+    yield { type: 'block-start', index: 1, blockType: 'text' };
+    yield { type: 'text-delta', index: 1, text: message };
+    yield { type: 'block-end', index: 1, block: { type: 'text', text: message } };
+    yield { type: 'finish', reason: { kind: 'error', failure: { message, code: 'PROVIDER_ERROR' } } };
+}
+function isDshFinishChunk(value) {
+    const record = asRecord(value);
+    return record?.type === 'finish';
+}
+function isMeaningfulDshChunk(value) {
+    const record = asRecord(value);
+    if (record === null)
+        return false;
+    if (record.type === 'text-delta' || record.type === 'reasoning-delta' || record.type === 'usage' || record.type === 'tool-call' || record.type === 'tool-result')
+        return true;
+    if (record.type === 'block-end') {
+        const block = asRecord(record.block);
+        return typeof block?.text === 'string' && block.text !== '';
+    }
+    return false;
+}
 function readAdapterId(value) {
     const record = asRecord(value);
     if (typeof record?.adapterId !== 'string' || record.adapterId.trim() === '')
@@ -280,15 +340,39 @@ function readModelSelectionCandidates(value) {
     const result = [];
     for (const candidate of [value, asRecord(value?.request), asRecord(value?.config), asRecord(value?.header), asRecord(asRecord(value?.record)?.rows)]) {
         const selection = asRecord(candidate?.modelSelection);
+        if (selection !== null)
+            result.push(selection);
         const lastUsed = asRecord(selection?.lastUsed);
         const next = asRecord(selection?.next);
+        const pending = asRecord(selection?.pending);
         if (lastUsed !== null)
             result.push(lastUsed);
         if (next !== null)
             result.push(next);
+        if (pending !== null)
+            result.push(pending);
     }
     return result;
 }
+function selectExternalAdapter(selectedProvider, messageAdapter, registry) {
+    for (const candidate of [selectedProvider, messageAdapter]) {
+        if (candidate !== undefined && candidate !== 'dsh' && registry.isEnabled(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** 从当前会话历史恢复外部路由，覆盖 DSH 第二轮省略 provider 的请求形态。 */
+function inferMessageAdapter(messages) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const source = asRecord(messages[index].source);
+        if (source?.kind !== 'model' || source.plugin !== 'codingns4dsh')
+            continue;
+        const provider = source.provider;
+        if (typeof provider === 'string' && provider.trim() !== '')
+            return provider.trim();
+    }
+    return undefined;
+}
 async function setAdapterEnabled(settings, registry, value) {
     const record = asRecord(value);
     const adapterId = readAdapterId(record);

package/data/build/dist/host/cli-adapters/json-rpc-process.d.ts

@@ -13,6 +13,12 @@ export interface JsonRpcMessage {
     };
     readonly [key: string]: unknown;
 }
+/** 保留 JSON-RPC 错误的稳定字段，供适配器识别可恢复错误。 */
+export declare class JsonRpcRequestError extends Error {
+    readonly code: number | undefined;
+    readonly data: unknown;
+    constructor(code: number | undefined, data: unknown);
+}
 export interface JsonRpcProcessOptions {
     readonly command: string;
     readonly args?: readonly string[];

package/data/build/dist/host/cli-adapters/json-rpc-process.js

@@ -1,6 +1,17 @@
 import { spawn } from 'node:child_process';
 import readline from 'node:readline';
-import { terminateChildProcess, WINDOWS } from './process-utils.js';
+import { commandEnvironment, terminateChildProcess, WINDOWS } from './process-utils.js';
+/** 保留 JSON-RPC 错误的稳定字段，供适配器识别可恢复错误。 */
+export class JsonRpcRequestError extends Error {
+    code;
+    data;
+    constructor(code, data) {
+        super('JSON-RPC 请求失败');
+        this.name = 'JsonRpcRequestError';
+        this.code = code;
+        this.data = data;
+    }
+}
 /**
  * 统一管理 stdio JSON-RPC 子进程：请求编号、逐行解码、取消和退出清理都在这里完成。
  * 凭据不会被记录，也不会进入错误文本。
@@ -132,7 +143,7 @@ export class JsonRpcProcess {
             return;
         const child = this.runSpawn(this.options.command, this.options.args ?? [], {
             cwd: this.options.cwd,
-            env: { ...process.env, ...(this.options.env ?? {}) },
+            env: { ...commandEnvironment(this.options.command), ...(this.options.env ?? {}) },
             stdio: ['pipe', 'pipe', 'pipe'],
             windowsHide: true,
             shell: WINDOWS,
@@ -193,7 +204,7 @@ export class JsonRpcProcess {
                         continue;
                     // Provider 错误可能带命令行、路径或凭据片段，只向上层暴露稳定错误，不回传原文。
                     if (isRecord(value.error))
-                        pending.reject(new Error('JSON-RPC 请求失败'));
+                        pending.reject(new JsonRpcRequestError(typeof value.error.code === 'number' ? value.error.code : undefined, value.error.data));
                     else
                         pending.resolve(value.result);
                     continue;

package/data/build/dist/host/cli-adapters/kimi-driver.js

@@ -7,7 +7,7 @@ import { probeStoredSession, readFirstJsonRecord, resolveSessionDirectory } from
 import { firstToolText, isToolRecord, normalizeToolStatus, serializeToolValue } from './tool-observation.js';
 import { isQuestionEvent, readAgentQuestions } from './interaction-events.js';
 import { usageChunk } from './rpc-driver-utils.js';
-import { terminateChildProcess } from './process-utils.js';
+import { commandEnvironment, terminateChildProcess } from './process-utils.js';
 /** Kimi 的 wire 协议优先，旧版 CLI 不支持时自动回退 stream-json。 */
 export class KimiCliDriver extends StandardStreamDriver {
     legacySyntax = false;
@@ -113,7 +113,7 @@ export class KimiCliDriver extends StandardStreamDriver {
         if (input.modelId && !isProviderDefaultModel(input.modelId))
             args.push('--model', input.modelId);
         const child = this.runSpawn(command, args, {
-            cwd: input.cwd ?? process.cwd(), env: { ...process.env }, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, shell: process.platform === 'win32',
+            cwd: input.cwd ?? process.cwd(), env: commandEnvironment(command), stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, shell: process.platform === 'win32',
         });
         const stdin = child.stdin;
         const interaction = {
@@ -223,7 +223,7 @@ export class KimiCliDriver extends StandardStreamDriver {
     }
     detectSyntax(command) {
         try {
-            const result = this.runSpawnSync(command, ['--help'], { encoding: 'utf8', timeout: 5_000, windowsHide: true, shell: process.platform === 'win32' });
+            const result = this.runSpawnSync(command, ['--help'], { encoding: 'utf8', timeout: 5_000, windowsHide: true, shell: process.platform === 'win32', env: commandEnvironment(command) });
             const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.toLowerCase();
             this.legacySyntax = /(?:^|\s)wire(?:\s|$)/u.test(output) && !output.includes('--wire');
         }

package/data/build/dist/host/cli-adapters/model-catalog.d.ts

@@ -14,6 +14,12 @@ export declare const CLAUDE_CATALOG: CodingNsCliModelCatalog;
 export declare const KIMI_CATALOG: CodingNsCliModelCatalog;
 export declare const GEMINI_CATALOG: CodingNsCliModelCatalog;
 export declare const CODEX_CATALOG: CodingNsCliModelCatalog;
+/**
+ * Codex app-server 在 request/context 中会先沿用 1M 的通用默认值，
+ * 但 gpt-5.6-sol 的真实 tokenUsage.contextWindow 是 258400。
+ * 这个提示只用于首个 usage 到达前稳定 DSH 的分母；真实 usage 仍然优先。
+ */
+export declare function knownCodexContextWindow(modelId: string | undefined): number | undefined;
 export declare const GROK_CATALOG: CodingNsCliModelCatalog;
 export declare const PI_CATALOG: CodingNsCliModelCatalog;
 /** 把 CLI 帮助解析到的模型补上已知档位，未知模型保持空数组。 */

package/data/build/dist/host/cli-adapters/model-catalog.js

@@ -64,6 +64,14 @@ export const CODEX_CATALOG = staticCatalog('codex', 'Codex', [
     { id: 'gpt-5.4', efforts: ['low', 'medium', 'high', 'xhigh'] },
     { id: 'gpt-5.3-codex', efforts: ['low', 'medium', 'high', 'xhigh'] },
 ]);
+/**
+ * Codex app-server 在 request/context 中会先沿用 1M 的通用默认值，
+ * 但 gpt-5.6-sol 的真实 tokenUsage.contextWindow 是 258400。
+ * 这个提示只用于首个 usage 到达前稳定 DSH 的分母；真实 usage 仍然优先。
+ */
+export function knownCodexContextWindow(modelId) {
+    return modelId?.trim().toLowerCase() === 'gpt-5.6-sol' ? 258400 : undefined;
+}
 export const GROK_CATALOG = staticCatalog('grok', 'Grok', [
     { id: 'provider-default', name: '跟随 Grok 默认模型', efforts: ['low', 'medium', 'high', 'xhigh'] },
     { id: 'grok-4.6', efforts: ['low', 'medium', 'high', 'xhigh'] },

package/data/build/dist/host/cli-adapters/opencode-driver.js

@@ -4,7 +4,7 @@ import { isProviderDefaultModel } from './model-catalog.js';
 import { firstToolText, normalizeToolStatus, serializeToolValue } from './tool-observation.js';
 import { isQuestionEvent, questionAnswersList, readAgentQuestions } from './interaction-events.js';
 import { usageChunk } from './rpc-driver-utils.js';
-import { terminateChildProcess } from './process-utils.js';
+import { commandEnvironment, resolveCommandPath, terminateChildProcess } from './process-utils.js';
 const WINDOWS = process.platform === 'win32';
 const DEFAULT_BINARIES = WINDOWS ? ['opencode.exe', 'opencode'] : ['opencode'];
 const DEFAULT_URLS = ['http://127.0.0.1:4096'];
@@ -380,7 +380,7 @@ export class OpenCodeDriver {
         try {
             child = this.runSpawn(command, [...this.serverArgs, '--port', String(port)], {
                 cwd,
-                env: { ...process.env },
+                env: commandEnvironment(command),
                 stdio: ['ignore', 'pipe', 'pipe'],
                 windowsHide: true,
                 shell: WINDOWS,
@@ -441,6 +441,18 @@ export class OpenCodeDriver {
                 }
             }
             catch { /* PATH 中没有命令 */ }
+            const resolved = resolveCommandPath(command, this.runSpawnSync);
+            if (resolved === null)
+                continue;
+            try {
+                const result = this.runSpawnSync(resolved, ['--version'], { encoding: 'utf8', timeout: 3_000, windowsHide: true, shell: WINDOWS, env: commandEnvironment(resolved) });
+                const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
+                if (result.status === 0) {
+                    this.cachedBinary = resolved;
+                    return { command: resolved, version: output.match(/\d+\.\d+\.\d+/u)?.[0] ?? null };
+                }
+            }
+            catch { /* 登录 Shell 找到的命令也可能已失效 */ }
         }
         return null;
     }

package/data/build/dist/host/cli-adapters/pi-driver.js

@@ -6,7 +6,7 @@ import { detectBinary, emptyCatalog, isRecord, textValue, usageChunk } from './r
 import { PI_CATALOG, isProviderDefaultModel } from './model-catalog.js';
 import { probeStoredSession, readFirstJsonRecord } from './session-probe.js';
 import { firstToolText, isToolRecord, normalizeToolStatus, serializeToolValue } from './tool-observation.js';
-import { WINDOWS } from './process-utils.js';
+import { commandEnvironment, WINDOWS } from './process-utils.js';
 /** Pi Agent 的 --mode rpc 适配器。Pi 的长期 RPC 细节被限制在本文件和标准进程层内。 */
 export class PiAgentDriver {
     descriptor = { id: 'pi', name: 'Pi Agent', protocol: 'json-rpc', capabilities: ['models', 'stream', 'resume', 'interrupt', 'tool-events', 'reasoning', 'usage', 'steer'] };
@@ -51,7 +51,7 @@ export class PiAgentDriver {
             rpc.dispose();
         }
         try {
-            const result = this.runSpawnSync(detection.command, ['--list-models'], { encoding: 'utf8', timeout: 12_000, windowsHide: true, shell: WINDOWS });
+            const result = this.runSpawnSync(detection.command, ['--list-models'], { encoding: 'utf8', timeout: 12_000, windowsHide: true, shell: WINDOWS, env: commandEnvironment(detection.command) });
             const catalog = parsePiCliCatalog(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);
             if (catalog.groups.length > 0)
                 return catalog;

package/data/build/dist/host/cli-adapters/process-utils.d.ts

@@ -1,9 +1,17 @@
+import { spawnSync } from 'node:child_process';
 interface KillableChild {
     readonly pid?: number | null;
     kill(signal?: string): boolean;
 }
 /** Windows 的 npm CLI 通常是 .cmd 包装器，必须经由 shell 才能启动。 */
 export declare const WINDOWS: boolean;
+/**
+ * 桌面应用通常不是从登录终端启动，继承到的 PATH 只有系统目录。
+ * 先尝试当前进程的 PATH，失败后再从用户登录 Shell 解析命令位置。
+ */
+export declare function resolveCommandPath(command: string, run?: typeof spawnSync): string | null;
+/** 把解析出的 CLI 所在目录补到子进程 PATH，确保 npm shim 的 node shebang 可用。 */
+export declare function commandEnvironment(command: string): Record<string, string | undefined>;
 /**
  * 结束 CLI 进程及其子进程树。
  *

package/data/build/dist/host/cli-adapters/process-utils.js

@@ -1,6 +1,54 @@
 import { spawnSync } from 'node:child_process';
+import { dirname } from 'node:path';
 /** Windows 的 npm CLI 通常是 .cmd 包装器，必须经由 shell 才能启动。 */
 export const WINDOWS = process.platform === 'win32';
+let loginShellPath;
+/**
+ * 桌面应用通常不是从登录终端启动，继承到的 PATH 只有系统目录。
+ * 先尝试当前进程的 PATH，失败后再从用户登录 Shell 解析命令位置。
+ */
+export function resolveCommandPath(command, run = spawnSync) {
+    if (isAbsoluteCommand(command))
+        return command;
+    try {
+        const result = WINDOWS
+            ? run('where.exe', [command], { encoding: 'utf8', timeout: 3_000, windowsHide: true })
+            : run(process.env.SHELL || '/bin/sh', ['-ilc', 'command -v "$1"; printf "\\n__CODINGNS_PATH__%s\\n" "$PATH"', 'codingns4dsh-command-lookup', command], { encoding: 'utf8', timeout: 3_000, windowsHide: true });
+        if (result.status !== 0)
+            return null;
+        const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+        const pathMarker = output.match(/(?:^|\n)__CODINGNS_PATH__(.*?)(?:\n|$)/u)?.[1]?.trim();
+        if (pathMarker)
+            loginShellPath = pathMarker;
+        const lines = output
+            .split(/\r?\n/u)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        for (const line of lines.reverse()) {
+            if (isAbsoluteCommand(line))
+                return line;
+        }
+    }
+    catch {
+        // 登录 Shell 不可用时仍按未安装处理。
+    }
+    return null;
+}
+/** 把解析出的 CLI 所在目录补到子进程 PATH，确保 npm shim 的 node shebang 可用。 */
+export function commandEnvironment(command) {
+    const currentPath = loginShellPath ?? process.env.PATH ?? '';
+    if (!isAbsoluteCommand(command))
+        return { ...process.env };
+    const directory = dirname(command);
+    const separator = WINDOWS ? ';' : ':';
+    const pathEntries = currentPath.split(separator).filter((entry) => entry.length > 0);
+    if (!pathEntries.includes(directory))
+        pathEntries.unshift(directory);
+    return { ...process.env, PATH: pathEntries.join(separator) };
+}
+function isAbsoluteCommand(value) {
+    return WINDOWS ? /^[A-Za-z]:[\\/]/u.test(value) || value.startsWith('\\\\') : value.startsWith('/');
+}
 /**
  * 结束 CLI 进程及其子进程树。
  *

package/data/build/dist/host/cli-adapters/registry.d.ts

@@ -28,7 +28,12 @@ export declare class CodingNsCliAdapterRegistry {
     private readonly modelTimers;
     private readonly modelGenerations;
     private readonly requestedModelCatalogs;
-    /** 已切到下一个 DSH step、但仍在继续产出 Provider 流的驱动迭代器。 */
+    /**
+     * 已切到下一个 DSH step、但仍在继续产出 Provider 流的运行。
+     *
+     * 通用切分由 Registry 持有活迭代器；驱动自行分段的适配器（Codex、Command Code）
+     * 把进程和段状态留在驱动内，这里只登记续段意图，用 null 迭代器区分两者。
+     */
     private readonly segmentedTurns;
     private cacheGeneration;
     private disposed;