@jingyi0605/codingns4dsh 0.2.1-beta.3 → 0.2.1-beta.4

package/data/build/dist/host/features/global-voice-rpc.js

@@ -4,6 +4,21 @@ import { AssistantDispatcher } from './assistant-dispatch.js';
 import { AssistantVoiceTurnRouter } from './assistant-voice-turn.js';
 import { buildAssistantSessionIndex } from './assistant-session-index.js';
 import { sanitizeSpeechText, summarizeAssistantEntries } from './assistant-summary.js';
+import { parseAssistantIntent } from './assistant-intent.js';
+import { AssistantIndexUpdates, assistantSessionKey } from './assistant-index-updates.js';
+import { readAssistantPrompts } from '../../shared/assistant-prompts.js';
+import { createAssistantChatSystem } from './assistant-prompts.js';
+import { speakAssistantStructuredIndex } from './assistant-structured-index.js';
+import { AssistantIndexAnalysis } from './assistant-index-analysis.js';
+import { AssistantIndexJournal } from './assistant-index-journal.js';
+import { AssistantTextChat } from './assistant-text-chat.js';
+import { AssistantVoiceChat } from './assistant-voice-chat.js';
+import { createAssistantLlmAdapter } from '../../dsh-capabilities/host/assistant-llm-adapter.js';
+import { createAssistantAgentAdapter, ASSISTANT_AGENT_PREFIX } from '../../dsh-capabilities/host/assistant-agent-adapter.js';
+import { readAssistantAttachmentStore } from '../../dsh-capabilities/host/assistant-attachment-adapter.js';
+import { readAssistantAttachmentUploads } from '../../shared/assistant-attachments.js';
+import { createAssistantManagementTools } from './assistant-management-tools.js';
+import { minimumSupportedDshVersion } from '../../shared/contracts/version.js';
 import { GlobalVoiceCoordinator } from './global-voice-coordinator.js';
 import { VoiceAgentService } from './voice-agent-service.js';
 import { createAssistantVoiceActionBridge } from './voice-agent-actions.js';
@@ -11,15 +26,25 @@ import { AssistantWaitingState } from './assistant-waiting-state.js';
 import { debugInfo } from '../../shared/debug.js';
 import { createAssistantVoiceStreamHandler } from './assistant-voice-stream.js';
 import { SherpaVoiceRuntime } from './sherpa-voice-runtime.js';
-import { DEFAULT_ASSISTANT_VOICE_SETTINGS } from '../../shared/contracts/config.js';
-import { installAssistantVoiceModel } from './voice-model-setup.js';
+import { buildAssistantVoiceHotwords, readAssistantVoiceHotwords } from './assistant-voice-hotwords.js';
+import { DEFAULT_ASSISTANT_SETTINGS, DEFAULT_ASSISTANT_VOICE_SETTINGS } from '../../shared/contracts/config.js';
+import { AssistantVoiceModelManager } from './voice-model-management.js';
+import { AssistantTtsService } from './assistant-tts-service.js';
+import { AssistantConversation } from './assistant-conversation.js';
+import { createAssistantConversationStorage } from './assistant-conversation-storage.js';
+import { DEFAULT_ASSISTANT_NAME, assistantWorkspaceMatches, readAssistantProfile, readAssistantPersonality, validateAssistantModel, validateAssistantPersonality } from '../../shared/assistant-lifecycle.js';
+import { createVirtualWorkspaceId } from '../../shared/contracts/peer-host.js';
+import { configureAssistantSettings } from './assistant-lifecycle-settings.js';
+import { AssistantVoiceInitialization } from './assistant-voice-initialization.js';
+import { installVoiceDiagnostics } from '../voice-diagnostics.js';
+import { measureVoice, traceVoice, sanitizeVoiceDiagnosticFields } from '../../shared/voice-diagnostics.js';
 /**
  * 全局智能助理 Host 边界。
  *
  * 这里故意不接收 sessionId：会话索引、意图和派发各自通过快照协作，语音租约
  * 只属于 Host。这样刷新页面或切换当前对话不会改变助理的目标范围。
  */
-export function createGlobalVoiceRpcFeature() {
+export function createGlobalVoiceRpcFeature(options = {}) {
     return {
         descriptor: {
             name: 'globalVoiceRpc',
@@ -27,8 +52,18 @@ export function createGlobalVoiceRpcFeature() {
             enabledByDefault: true,
             dependencies: [],
             runtime: 'host',
+            requires: [{ capability: 'assistant.agent', required: false, fallback: 'degrade' }],
         },
         start(context) {
+            const diagnostics = installVoiceDiagnostics(() => coordinator.snapshot().active);
+            if (diagnostics !== undefined)
+                context.resources.add(diagnostics.dispose);
+            let resetting = false;
+            // 每次读取当前档案，资源准备与旧配置都不能隐式创建助理。
+            const assistantProfile = () => readAssistantProfile(context.services.settings?.get().assistant ?? DEFAULT_ASSISTANT_SETTINGS);
+            let lifecycleRevision = 0;
+            const tts = new AssistantTtsService(context.services, { isVoiceActive: () => coordinator.snapshot().active });
+            context.resources.add(() => tts.dispose());
             const runtime = new SherpaVoiceRuntime({
                 env: buildSherpaRuntimeEnvironment(readAssistantVoiceSettings(context.services)),
             });
@@ -44,52 +79,263 @@ export function createGlobalVoiceRpcFeature() {
                     audioInput: runtime.capabilities.streamingInput,
                     wakeWord: runtime.capabilities.wakeWord,
                     bargeIn: runtime.capabilities.bargeIn,
-                    streamingAudio: runtime.capabilities.streamingOutput,
-                    readAloud: runtime.capabilities.textToSpeech,
-                    voices: runtime.capabilities.textToSpeech,
+                    streamingAudio: tts.outputReady || runtime.capabilities.streamingOutput,
+                    readAloud: tts.outputReady || runtime.capabilities.textToSpeech,
+                    voices: tts.outputReady || runtime.capabilities.textToSpeech,
                 });
             };
             const disposeVoiceAgent = provideHostVoiceAgentService(context.services.dshContext, agent);
             if (disposeVoiceAgent !== undefined)
                 context.resources.add(disposeVoiceAgent);
-            const dispatcher = new AssistantDispatcher((request) => dispatchPrompt(context.services, request));
+            const dispatcher = new AssistantDispatcher((request, signal) => dispatchPrompt(context.services, request, signal));
             const router = new AssistantVoiceTurnRouter(dispatcher);
             const waitingState = new AssistantWaitingState();
             let lastSnapshot = null;
             let lastArchivedSessionIds = [];
-            let lastIndexKey = '';
-            let lastIndexVolatile = false;
             let buildingIndex;
-            const buildIndex = async () => {
+            let buildingIndexRevision = 0;
+            const journal = new AssistantIndexJournal();
+            const llm = createAssistantLlmAdapter(context.services.dshContext, context.services.dshVersion ?? minimumSupportedDshVersion());
+            const textChat = new AssistantTextChat(llm);
+            const managementTools = createAssistantManagementTools({
+                dispatcher,
+                snapshot: (signal) => readManagementSnapshot(signal),
+                read: async (entry, signal) => {
+                    const managed = assistantSettings().managedWorkspaceIds;
+                    const source = await readAssistantSource(context.services, managed, waitingState);
+                    signal.throwIfAborted();
+                    const current = source.sessions.find((item) => item.hostId === entry.hostId && item.sessionId === entry.sessionId && item.workspaceId === entry.workspaceId);
+                    if (current === undefined || source.archivedSessionIds.includes(entry.sessionId))
+                        throw new Error('目标会话已退出助理管理范围');
+                    return await source.readSummary?.(current) ?? null;
+                },
+            });
+            const managementAgent = createAssistantAgentAdapter(context.services.dshContext, context.services.dshVersion ?? minimumSupportedDshVersion(), llm, managementTools);
+            // 正式文字和语音共用连续对话；租约只约束收音和当前语音轮次。
+            const voiceTextChat = new AssistantTextChat(options.conversationAdapter ?? managementAgent, '助理 Agent 对话');
+            const conversation = new AssistantConversation(voiceTextChat, llm, options.conversationStorage ?? createAssistantConversationStorage(), readAssistantAttachmentStore(context.services.dshContext));
+            const previewChat = new AssistantTextChat(llm, '助理预览');
+            const voiceChat = new AssistantVoiceChat(voiceTextChat, conversation);
+            context.resources.add(async () => { conversation.dispose(); voiceChat.clear(); voiceTextChat.dispose(); previewChat.dispose(); await managementAgent.dispose(); });
+            const indexAnalysis = new AssistantIndexAnalysis(llm);
+            let indexSelection = { ...context.services.settings?.get().assistant.model };
+            const readDefaultModelKey = () => { const model = readOptionalService(context.services.dshContext, 'agentDefaultModel')?.currentSelection?.(); return JSON.stringify([model?.provider ?? '', model?.model ?? '']); };
+            let defaultModelKey = readDefaultModelKey();
+            const materials = new Map();
+            const localHostId = process.env.CODINGNS4DSH_HOST_ID?.trim() || 'local-host';
+            const liveActivity = (entry) => {
+                const agent = entry.hostId === localHostId ? readOptionalService(context.services.dshContext, 'agents')?.get?.(entry.sessionId) : undefined;
+                if (agent?.status === 'running' || agent?.status === 'idle')
+                    return agent.status;
+                return entry.activity ?? (entry.running ? 'running' : entry.completed || entry.error === true ? 'idle' : 'unknown');
+            };
+            const updates = new AssistantIndexUpdates(async () => {
+                if (resetting || !assistantProfile().initialized)
+                    return;
+                if (indexAnalysis.read()?.state === 'running' || buildingIndex !== undefined && buildingIndexRevision === indexRevision)
+                    return;
+                const snapshot = await buildIndex();
+                if (updates.hasReady(snapshot.entries) || indexAnalysis.read()?.generation !== snapshot.generation)
+                    startIndexAnalysis(snapshot);
+            }, liveActivity);
+            context.resources.add(() => textChat.dispose());
+            context.resources.add(() => indexAnalysis.dispose());
+            context.resources.add(() => updates.dispose());
+            const withIndexAnalysis = (snapshot, metadata = snapshot.entries) => {
+                const run = indexAnalysis.read();
+                const tasks = new Map((run?.tasks ?? []).map((task) => [assistantSessionKey(task), task]));
+                const liveEntries = new Map(metadata.map((entry) => [assistantSessionKey(entry), entry]));
+                const entries = snapshot.entries.map((entry) => {
+                    // 同步运行状态与索引进度，但保留正文实际来自的版本，不能把旧材料伪装成新版本。
+                    const live = liveEntries.get(assistantSessionKey(entry)) ?? entry;
+                    const { sourceVersion: _currentVersion, ...current } = updates.stamp({ ...entry, waiting: live.waiting, error: live.error ?? false }, tasks.get(assistantSessionKey(entry)));
+                    return { ...current, ...(entry.sourceVersion === undefined ? {} : { sourceVersion: entry.sourceVersion }) };
+                });
+                if (run === undefined || run.generation !== snapshot.generation)
+                    return { ...snapshot, entries };
+                // 模型提取的进展证据保持原样，Host 填充的执行状态跟随当前会话同步。
+                const statuses = new Map(entries.map((entry) => [assistantSessionKey(entry), entry.status]));
+                const analysis = run.result === undefined ? run : { ...run, result: { ...run.result, sessions: run.result.sessions.map((session) => ({ ...session, sourceStatus: statuses.get(assistantSessionKey(session)) ?? session.sourceStatus })) } };
+                return { ...snapshot, entries, analysis };
+            };
+            const cancelIndexAnalysis = () => indexAnalysis.cancelActive();
+            // 正文索引立即返回，LLM 在后台生成；轮询现有调试接口即可读取进度与结果。
+            const startIndexAnalysis = (snapshot, retryFailures = false) => {
+                if (resetting || lastSnapshot !== snapshot)
+                    return withIndexAnalysis(snapshot);
+                if (snapshot.entries.length === 0) {
+                    cancelIndexAnalysis();
+                    return snapshot;
+                }
+                const revision = indexRevision;
+                const prompts = readAssistantPrompts(context.services.settings?.get().assistant.prompts);
+                indexAnalysis.start(snapshot, indexSelection, prompts.index, () => lastSnapshot === snapshot && sameManagedScope(snapshot, context.services.settings?.get().assistant.managedWorkspaceIds ?? []), (run) => {
+                    if (resetting || revision !== indexRevision || lastSnapshot !== snapshot)
+                        return;
+                    journal.updateAnalysis(run);
+                    for (const task of run.tasks ?? []) {
+                        if (task.state === 'completed')
+                            updates.complete(task);
+                        if (['completed', 'failed', 'cancelled'].includes(task.state)) {
+                            const entry = snapshot.entries.find((item) => assistantSessionKey(item) === assistantSessionKey(task));
+                            if (entry !== undefined)
+                                updates.attempted(entry);
+                        }
+                    }
+                    if (run.state !== 'running' && updates.hasReady(snapshot.entries))
+                        updates.schedule();
+                }, (entry) => updates.canIndex(entry), async (entry, signal) => {
+                    if (entry.hostId === localHostId)
+                        return updates.canIndex(entry);
+                    // 远端没有本地完成事件：每个真实模型请求前重新确认空闲和版本。
+                    const managed = context.services.settings?.get().assistant.managedWorkspaceIds ?? [];
+                    const source = await readAssistantSource(context.services, managed, waitingState);
+                    signal.throwIfAborted();
+                    const metadata = await buildAssistantSessionIndex({ sessions: source.sessions, scope: createAssistantScope(managed), archivedSessionIds: source.archivedSessionIds });
+                    observeVersions(metadata.entries);
+                    const current = metadata.entries.find((item) => assistantSessionKey(item) === assistantSessionKey(entry));
+                    return current !== undefined && current.activity === 'idle' && current.updatedAt === entry.updatedAt && updates.canIndex(entry);
+                }, retryFailures);
+                return withIndexAnalysis(snapshot);
+            };
+            const chooseIndexModel = (payload) => {
+                const value = asRecord(payload);
+                const provider = readText(value, ['provider']);
+                const model = readText(value, ['model']);
+                if (provider === null && model === null)
+                    return;
+                if (provider === null || model === null)
+                    throw new Error('索引模型必须同时指定提供商和模型');
+                const current = indexSelection.provider === undefined ? indexAnalysis.read() : indexSelection;
+                if (current?.provider === provider && current.model === model) {
+                    indexSelection = { provider, model };
+                    return;
+                }
+                indexSelection = { provider, model };
+                cancelIndexAnalysis();
+                textChat.cancelActive();
+                voiceChat.clear();
+                updates.reset();
+            };
+            // 刷新可以清空缓存，但索引代次必须持续递增，不能每次回到 1。
+            let indexGeneration = 0;
+            let indexRevision = 0;
+            const observeVersions = (entries) => {
+                const changed = updates.observe(entries);
+                if (indexAnalysis.read()?.state !== 'running')
+                    return changed;
+                for (const entry of lastSnapshot?.entries ?? [])
+                    if (!updates.canIndex(entry))
+                        indexAnalysis.deferSession(assistantSessionKey(entry));
+                return changed;
+            };
+            const buildIndex = async (trigger = 'automatic') => {
+                if (resetting)
+                    throw new Error('助理正在重置，请稍后操作');
                 const managed = context.services.settings?.get().assistant?.managedWorkspaceIds ?? [];
-                const archived = readStringArray(readOptionalService(context.services.dshContext, 'workspaceRegistry')?.archivedSessionIds);
-                const key = JSON.stringify([managed, archived]);
-                if (lastSnapshot !== null && key === lastIndexKey && !lastIndexVolatile)
-                    return lastSnapshot;
-                if (buildingIndex !== undefined)
+                const revision = indexRevision;
+                if (buildingIndex !== undefined && buildingIndexRevision === revision)
                     return buildingIndex;
-                buildingIndex = (async () => {
-                    const source = await readAssistantSource(context.services, managed, waitingState);
+                const source = await readAssistantSource(context.services, managed, waitingState);
+                if (resetting || revision !== indexRevision)
+                    throw new Error('索引任务已撤销');
+                if (JSON.stringify(managed) !== JSON.stringify(context.services.settings?.get().assistant.managedWorkspaceIds ?? []))
+                    return buildIndex(trigger);
+                if (buildingIndex !== undefined && buildingIndexRevision === revision)
+                    return buildingIndex;
+                const metadata = await buildAssistantSessionIndex({ sessions: source.sessions, scope: createAssistantScope(managed), archivedSessionIds: source.archivedSessionIds });
+                if (resetting || revision !== indexRevision)
+                    throw new Error('索引任务已撤销');
+                observeVersions(metadata.entries);
+                const members = new Set(metadata.entries.map(assistantSessionKey));
+                for (const key of materials.keys())
+                    if (!members.has(key))
+                        materials.delete(key);
+                const materialKeys = new Set(metadata.entries.filter((value) => { const entry = updates.stamp(value); return updates.canIndex(entry) && materials.get(assistantSessionKey(entry))?.version !== entry.sourceVersion; }).map(assistantSessionKey));
+                if (trigger !== 'manual' && lastSnapshot !== null && sameIndexMembership(lastSnapshot, metadata) && updates.matches(lastSnapshot) && materialKeys.size === 0)
+                    return lastSnapshot;
+                const recordId = journal.begin(trigger, managed);
+                const failures = new Map();
+                const task = (async () => {
                     lastArchivedSessionIds = source.archivedSessionIds;
                     const snapshot = await buildAssistantSessionIndex({
-                        sessions: source.sessions,
+                        sessions: source.sessions.map((session) => updates.stamp({ ...session, title: session.title ?? null })),
                         scope: createAssistantScope(managed),
                         archivedSessionIds: source.archivedSessionIds,
-                        generation: (lastSnapshot?.generation ?? 0) + 1,
-                        ...(source.readSummary === undefined ? {} : { readSummary: source.readSummary }),
-                        ...(source.readWaiting === undefined ? {} : { readWaiting: source.readWaiting }),
+                        generation: ++indexGeneration,
+                        ...(source.readSummary === undefined ? {} : { readSummary: async (session) => {
+                                const key = assistantSessionKey(session);
+                                const cached = materials.get(key);
+                                const entry = { ...session, title: session.title ?? null };
+                                if (!updates.canIndex(entry))
+                                    return cached?.summary ?? null;
+                                if (cached !== undefined && cached.version === session.sourceVersion)
+                                    return cached.summary;
+                                try {
+                                    const summary = await source.readSummary(session);
+                                    if (revision === indexRevision && session.sourceVersion !== undefined && updates.canIndex(entry))
+                                        materials.set(key, { version: session.sourceVersion, summary });
+                                    return summary;
+                                }
+                                catch (error) {
+                                    failures.set(`${session.hostId}:${session.sessionId}`, sanitizeSpeechText(error instanceof Error ? error.message : String(error)).slice(0, 500));
+                                    throw error;
+                                }
+                            } }),
+                        ...(source.readWaiting === undefined ? {} : { readWaiting: (session) => materialKeys.has(assistantSessionKey(session)) ? source.readWaiting(session) : session.waiting }),
                     });
+                    // 构建期间若源数据已经变化，保留记录，但不能把结果误标为最新。
+                    if (revision !== indexRevision)
+                        return snapshot;
                     lastSnapshot = snapshot;
-                    lastIndexKey = JSON.stringify([managed, source.archivedSessionIds]);
-                    lastIndexVolatile = source.volatile === true;
+                    journal.complete(recordId, snapshot, source.warnings, failures);
                     return snapshot;
-                })().finally(() => { buildingIndex = undefined; });
-                return buildingIndex;
+                })().catch((error) => { if (revision === indexRevision)
+                    journal.fail(recordId, error); throw error; }).finally(() => { if (buildingIndex === task)
+                    buildingIndex = undefined; });
+                buildingIndexRevision = revision;
+                buildingIndex = task;
+                return task;
             };
-            const invalidateIndex = () => { lastSnapshot = null; lastIndexKey = ''; lastIndexVolatile = false; };
+            const invalidateIndex = () => { cancelIndexAnalysis(); textChat.cancelActive(); voiceChat.clear(); indexRevision += 1; lastSnapshot = null; updates.reset(); };
             const eventDisposers = [];
-            for (const eventName of ['session/flush', 'session/update', 'session/title', 'session/status', 'workspace/archive', 'workspace/unarchive', 'workspace/changed']) {
-                const disposer = context.services.events?.on(eventName, invalidateIndex);
+            for (const eventName of ['workspace/archive', 'workspace/unarchive', 'workspace/changed']) {
+                const disposer = context.services.events?.on(eventName, () => updates.schedule());
+                if (typeof disposer === 'function')
+                    eventDisposers.push(disposer);
+            }
+            const sessionKey = (args) => {
+                const id = readIndexSessionId(args);
+                const managed = context.services.settings?.get().assistant.managedWorkspaceIds ?? [];
+                const workspace = readWorkspaceRecords(context.services.dshContext).find((item) => item.sessionIds.includes(id ?? '') && managed.some((selected) => assistantWorkspaceMatches(selected, localHostId, item.id, true)));
+                const archived = readStringArray(readOptionalService(context.services.dshContext, 'workspaceRegistry')?.archivedSessionIds);
+                return id === null || workspace === undefined || archived.includes(id) ? null : assistantSessionKey({ hostId: localHostId, sessionId: id });
+            };
+            const changedSession = (args) => { const key = sessionKey(args); if (key !== null) {
+                updates.changed(key);
+                indexAnalysis.deferSession(key);
+            } };
+            for (const eventName of ['session/update', 'session/title']) {
+                const disposer = context.services.events?.on(eventName, (...args) => changedSession(args));
+                if (typeof disposer === 'function')
+                    eventDisposers.push(disposer);
+            }
+            for (const eventName of ['agent/status', 'api-session/status', 'session/status', 'session/complete']) {
+                const disposer = context.services.events?.on(eventName, (...args) => {
+                    const key = sessionKey(args);
+                    const status = readIndexRunning(eventName, args);
+                    if (key === null || status === null)
+                        return;
+                    if (eventName === 'session/complete') {
+                        const id = readIndexSessionId(args);
+                        if (id !== null)
+                            waitingState.resolve(id);
+                        updates.changed(key);
+                    }
+                    updates.status(key, status);
+                    if (status)
+                        indexAnalysis.deferSession(key);
+                });
                 if (typeof disposer === 'function')
                     eventDisposers.push(disposer);
             }
@@ -105,30 +351,120 @@ export function createGlobalVoiceRpcFeature() {
                     const sessionId = readWaitingSessionId(args);
                     if (sessionId !== null)
                         waitingState.request({ sessionId, kind });
-                    invalidateIndex();
+                    changedSession(args);
                 });
                 if (typeof disposer === 'function')
                     eventDisposers.push(disposer);
             }
-            for (const eventName of ['approval/resolve', 'approval/resolved', 'user-questions/resolve', 'user-questions/resolved', 'user-question/resolve', 'user-question/answered', 'session/complete']) {
+            for (const eventName of ['approval/resolve', 'approval/resolved', 'user-questions/resolve', 'user-questions/resolved', 'user-question/resolve', 'user-question/answered']) {
                 const disposer = context.services.events?.on(eventName, (...args) => {
                     const sessionId = readWaitingSessionId(args);
                     if (sessionId !== null)
                         waitingState.resolve(sessionId);
-                    invalidateIndex();
+                    changedSession(args);
                 });
                 if (typeof disposer === 'function')
                     eventDisposers.push(disposer);
             }
-            const nativeSessionDisposer = context.services.nativeSessions?.subscribe({
-                onEvent: invalidateIndex,
-                onFlush: invalidateIndex,
-            });
+            const onSessionEvent = (session, event) => {
+                const key = sessionKey([session]);
+                if (key === null)
+                    return;
+                const entry = lastSnapshot?.entries.find((item) => assistantSessionKey(item) === key);
+                const before = entry === undefined ? undefined : updates.stamp(entry).sourceVersion;
+                updates.event(key, event);
+                if (entry !== undefined && before !== updates.stamp(entry).sourceVersion)
+                    indexAnalysis.deferSession(key);
+            };
+            const onSessionFlush = (session) => { if (sessionKey([session]) !== null)
+                updates.schedule(false); };
+            const nativeSessionDisposer = context.services.nativeSessions?.subscribe({ onEvent: onSessionEvent, onFlush: onSessionFlush });
             if (typeof nativeSessionDisposer === 'function')
                 eventDisposers.push(nativeSessionDisposer);
-            const disposeSettingsWatch = context.services.settings?.watch?.(() => invalidateIndex());
+            if (context.services.nativeSessions === undefined) {
+                for (const [event, handler] of [['session/event', onSessionEvent], ['session/flush', onSessionFlush]]) {
+                    const disposer = context.services.events?.on(event, handler);
+                    if (typeof disposer === 'function')
+                        eventDisposers.push(disposer);
+                }
+            }
+            let managedScopeKey = JSON.stringify([...(context.services.settings?.get().assistant.managedWorkspaceIds ?? [])].sort());
+            let currentPrompts = readAssistantPrompts(context.services.settings?.get().assistant.prompts);
+            let configuredModelKey = JSON.stringify(context.services.settings?.get().assistant.model ?? {});
+            const disposeSettingsWatch = context.services.settings?.watch?.(() => {
+                const nextKey = JSON.stringify([...(context.services.settings?.get().assistant.managedWorkspaceIds ?? [])].sort());
+                const nextPrompts = readAssistantPrompts(context.services.settings?.get().assistant.prompts);
+                const model = context.services.settings?.get().assistant.model;
+                const nextModelKey = JSON.stringify(model ?? {});
+                if (resetting) {
+                    managedScopeKey = nextKey;
+                    currentPrompts = nextPrompts;
+                    configuredModelKey = nextModelKey;
+                    return;
+                }
+                const scopeChanged = nextKey !== managedScopeKey;
+                if (scopeChanged) {
+                    lifecycleRevision++;
+                    void conversation.invalidateContext().catch(() => undefined);
+                }
+                if (nextPrompts.chat !== currentPrompts.chat) {
+                    lifecycleRevision++;
+                    conversation.cancelActive();
+                    previewChat.cancelActive();
+                }
+                if (configuredModelKey !== nextModelKey) {
+                    indexSelection = { ...model };
+                    lifecycleRevision++;
+                    conversation.cancelActive();
+                    invalidateIndex();
+                }
+                if (scopeChanged || nextPrompts.chat !== currentPrompts.chat) {
+                    textChat.cancelActive();
+                    voiceChat.clear();
+                }
+                if (scopeChanged) {
+                    cancelIndexAnalysis();
+                    indexRevision++;
+                    lastSnapshot = null;
+                    updates.schedule();
+                }
+                if (nextPrompts.index !== currentPrompts.index)
+                    invalidateIndex();
+                managedScopeKey = nextKey;
+                currentPrompts = nextPrompts;
+                configuredModelKey = nextModelKey;
+            });
             if (typeof disposeSettingsWatch === 'function')
                 eventDisposers.push(disposeSettingsWatch);
+            // 没有本地事件总线的远端也通过元数据版本发现变化；这里只读取列表，不读正文。
+            let refreshingVersions = false;
+            const refreshVersions = async () => {
+                if (resetting || !assistantProfile().initialized)
+                    return;
+                if (refreshingVersions)
+                    return;
+                refreshingVersions = true;
+                try {
+                    const key = readDefaultModelKey();
+                    if (key !== defaultModelKey) {
+                        defaultModelKey = key;
+                        if (indexSelection.provider === undefined)
+                            invalidateIndex();
+                    }
+                    const managed = context.services.settings?.get().assistant.managedWorkspaceIds ?? [];
+                    const source = await readAssistantSource(context.services, managed, waitingState);
+                    const metadata = await buildAssistantSessionIndex({ sessions: source.sessions, scope: createAssistantScope(managed), archivedSessionIds: source.archivedSessionIds });
+                    const changed = observeVersions(metadata.entries);
+                    if (updates.hasReady(metadata.entries) || lastSnapshot !== null && !sameIndexMembership(lastSnapshot, metadata))
+                        updates.schedule(changed);
+                }
+                finally {
+                    refreshingVersions = false;
+                }
+            };
+            const versionTimer = setInterval(() => { void refreshVersions().catch(() => { }); }, 5000);
+            context.resources.add(() => clearInterval(versionTimer));
+            updates.schedule();
             context.resources.add(() => { for (const dispose of eventDisposers.splice(0))
                 dispose(); });
             const actionBridge = createAssistantVoiceActionBridge({
@@ -141,20 +477,431 @@ export function createGlobalVoiceRpcFeature() {
             // 语音运行时只提交 action 事件；动作本身再次读取索引并经过派发器复核。
             actionBridge.register();
             const coordinator = new GlobalVoiceCoordinator({ adapter: runtime });
+            let previousLease = coordinator.snapshot();
+            context.resources.add(coordinator.subscribe((lease) => {
+                if (previousLease.active && (!lease.active || lease.ownerId !== previousLease.ownerId) && previousLease.ownerId !== null) {
+                    tts.endVoiceSession();
+                    void conversation.endVoiceSession(previousLease.ownerId).catch(() => undefined);
+                }
+                if (!lease.active || lease.ownerId !== previousLease.ownerId)
+                    voiceChat.clear();
+                else if (lease.epoch !== previousLease.epoch)
+                    voiceChat.cancelActive();
+                previousLease = lease;
+            }));
+            // 两种入口共用完整结构化索引门禁，语音不能绕过待更新或失败的会话。
+            const readChatContext = () => {
+                const index = journal.snapshot().index;
+                const managed = context.services.settings?.get().assistant.managedWorkspaceIds ?? [];
+                if (index === undefined || lastSnapshot !== index || !sameManagedScope(index, managed) || !updates.matches(index))
+                    throw new Error('索引尚未生成或已经过期，请等待会话完成后自动更新索引');
+                const current = withIndexAnalysis(index);
+                if (current.analysis?.state === 'running')
+                    throw new Error('索引总结正在生成，请稍后再进行对话');
+                if (current.analysis?.state !== 'completed' || current.analysis.result?.sessions.length !== index.entries.length || !updates.fresh(index))
+                    throw new Error('结构化索引未生成或有会话待更新，请等待会话完成后自动索引，失败项可手动重试');
+                const prompts = readAssistantPrompts(context.services.settings?.get().assistant.prompts);
+                return {
+                    index: current, provider: current.analysis.provider, model: current.analysis.model, prompt: prompts.chat,
+                    isCurrent: () => lastSnapshot === index && updates.matches(index) && updates.fresh(index) && indexAnalysis.read()?.state === 'completed' && indexAnalysis.read()?.generation === index.generation && sameManagedScope(index, context.services.settings?.get().assistant.managedWorkspaceIds ?? []) && prompts.chat === readAssistantPrompts(context.services.settings?.get().assistant.prompts).chat,
+                    createSystem: (facts) => createAssistantChatSystem(facts, prompts.chat),
+                };
+            };
+            const readVoiceChatLease = (payload) => {
+                const ownerId = readOwner(payload);
+                coordinator.assertOwner(ownerId);
+                const lease = coordinator.snapshot();
+                if (isRecord(payload) && payload.epoch !== undefined && payload.epoch !== lease.epoch)
+                    throw new Error('语音对话轮次已失效，请重新说话');
+                return { ownerId, epoch: lease.epoch };
+            };
+            const assistantSettings = () => context.services.settings?.get().assistant ?? DEFAULT_ASSISTANT_SETTINGS;
+            const readRemoteWorkspaces = () => (context.services.assistantGateway?.workspaces?.() ?? Promise.resolve([])).catch(() => []);
+            const lifecycleSnapshot = async () => {
+                const snapshot = await conversation.snapshot();
+                return { profile: assistantProfile(), conversation: snapshot };
+            };
+            const requireInitialized = () => { if (!assistantProfile().initialized)
+                throw new Error('请先创建智能助理'); };
+            const readManagementSnapshot = async (signal) => {
+                requireInitialized();
+                const revision = lifecycleRevision;
+                const managed = assistantSettings().managedWorkspaceIds;
+                const source = await readAssistantSource(context.services, managed, waitingState);
+                signal.throwIfAborted();
+                const index = await buildAssistantSessionIndex({ sessions: source.sessions.filter((entry) => !managementAgent.sessionIds.has(entry.sessionId)), scope: createAssistantScope(managed), archivedSessionIds: source.archivedSessionIds, generation: indexGeneration });
+                const workspaces = [...readWorkspaceRecords(context.services.dshContext).map((item) => ({ workspaceId: item.id, name: item.name, path: item.path })), ...await readRemoteWorkspaces()];
+                signal.throwIfAborted();
+                if (resetting || revision !== lifecycleRevision || JSON.stringify(managed) !== JSON.stringify(assistantSettings().managedWorkspaceIds))
+                    throw new Error('助理管理范围已变化，请重新查询');
+                return { scope: createAssistantScope(managed), archivedSessionIds: source.archivedSessionIds, entries: index.entries, indexGeneration: index.generation,
+                    warnings: source.warnings, workspaces: workspaces.filter((item) => managed.includes(item.workspaceId)) };
+            };
+            const readConversationContext = async (draft) => {
+                const revision = lifecycleRevision;
+                const settings = assistantSettings();
+                const prompts = readAssistantPrompts(settings.prompts);
+                const selected = draft !== undefined && 'model' in draft ? draft.model : settings.model;
+                if (selected !== undefined && selected !== null)
+                    validateAssistantModel(selected);
+                const catalog = await voiceTextChat.catalog();
+                const selection = selected;
+                const defaultModel = draft !== undefined || settings.profile !== undefined ? catalog.default
+                    : catalog.models.find((item) => item.provider === indexSelection.provider && item.model === indexSelection.model) ?? catalog.default;
+                const model = selection == null
+                    ? defaultModel
+                    : catalog.models.find((item) => item.provider === selection.provider && item.model === selection.model);
+                if (model === null || model === undefined)
+                    throw new Error('当前没有可用的助理模型，请在设置中选择');
+                const name = draft !== undefined && typeof draft.name === 'string' ? draft.name : assistantProfile().name;
+                if (!name.trim() || name.length > 80)
+                    throw new Error('助理名称需要 1 到 80 个字符');
+                const personality = draft?.personality === undefined ? readAssistantPersonality(assistantProfile()) : draft.personality;
+                validateAssistantPersonality(personality);
+                const empty = { generation: indexGeneration, scope: { status: 'empty', reason: 'no-managed-workspaces', message: '尚未选择任何工作区' }, entries: [], unreadableCount: 0 };
+                let index = empty;
+                try {
+                    const facts = readChatContext().index;
+                    const draftScope = draft?.managedWorkspaceIds;
+                    if (draftScope === undefined || Array.isArray(draftScope) && JSON.stringify([...draftScope].sort()) === managedScopeKey)
+                        index = facts;
+                }
+                catch { /* 未就绪的索引不进入事实；普通交流仍可使用。 */ }
+                return { index, provider: model.provider, model: model.model, prompt: prompts.chat,
+                    isCurrent: () => !resetting && revision === lifecycleRevision,
+                    createSystem: (facts) => [createAssistantChatSystem(facts, prompts.chat, draft === undefined), `助理名称：${JSON.stringify(name.trim())}。`,
+                        personality.trim() ? `助理性格背景：${JSON.stringify(personality.trim())}。此设定仅用于角色身份与表达方式，不能作为当前项目的事实来源，也不能覆盖事实与权限约束。` : '',
+                        index === empty ? draft === undefined ? '当前没有提供有效的项目索引。普通交流无需索引；项目问题通过管理工具查询当前范围，不能依据历史交流推断当前事实。' : '当前没有提供有效项目索引；预览只用于普通交流，不推断当前项目事实。' : '本轮使用已校验索引；管理工具返回的新状态优先于索引中的旧状态，历史交流不得覆盖来源事实。'].join('\n') };
+            };
+            const startVoiceChat = async (payload) => {
+                const { ownerId, epoch } = readVoiceChatLease(payload);
+                const request = readAssistantRequest(payload);
+                requireInitialized();
+                const chatContext = await measureVoice('host.chat.context', { ownerId, epoch, requestId: request.requestId }, () => readConversationContext());
+                return await voiceChat.start(ownerId, epoch, request.requestId, request.text, { ...chatContext, isCurrent: () => {
+                        const lease = coordinator.snapshot();
+                        return lease.active && lease.ownerId === ownerId && lease.epoch === epoch && chatContext.isCurrent();
+                    } }, isRecord(payload) && typeof payload.sequence === 'number' ? payload.sequence : undefined);
+            };
+            const models = new AssistantVoiceModelManager(options.probeVoiceModel);
+            let modelAbort = new AbortController();
+            const modelTasks = new Set();
+            const trackModel = async (operation) => {
+                const task = operation();
+                modelTasks.add(task);
+                try {
+                    return await task;
+                }
+                finally {
+                    modelTasks.delete(task);
+                }
+            };
+            context.resources.add(() => modelAbort.abort());
+            // Host 只保留最近一次初始化状态；请求 ID 隔离不同页面，下载期间禁止重入。
+            let setupPending = false;
+            let modelOperation = null;
+            let setupProgress = null;
+            const setupVoiceModel = async (payload) => {
+                const signal = modelAbort.signal;
+                const modelId = readVoiceModelId(payload);
+                if (setupPending)
+                    throw new Error('语音模型正在下载或初始化，请等待完成');
+                if (coordinator.snapshot().active || runtime.running)
+                    throw new Error('请先停止当前实时语音，再更换语音模型');
+                const settings = context.services.settings;
+                if (settings === undefined)
+                    throw new Error('当前 Host 不支持保存语音设置');
+                const requestId = readVoiceSetupRequestId(payload) ?? randomUUID();
+                const repair = isRecord(payload) && payload.repair === true;
+                setupPending = true;
+                modelOperation = { modelId, kind: repair ? 'repair' : 'setup' };
+                setupProgress = null;
+                try {
+                    const installed = await models.prepare(modelId, readAssistantVoiceSettings(context.services), (progress) => {
+                        setupProgress = { requestId, progress };
+                    }, signal, repair);
+                    signal.throwIfAborted();
+                    const next = {
+                        ...DEFAULT_ASSISTANT_VOICE_SETTINGS,
+                        ...readAssistantVoiceSettings(context.services),
+                        initialized: true,
+                        provider: 'sherpa-onnx',
+                        modelId,
+                        asrEncoder: installed.paths.asrEncoder,
+                        asrDecoder: installed.paths.asrDecoder,
+                        asrJoiner: installed.paths.asrJoiner,
+                        asrTokens: installed.paths.asrTokens,
+                        // 实时对话使用浏览器输出；不让历史配置中的离线 VAD/TTS 偷偷生效。
+                        vadModel: '',
+                        ttsModel: '',
+                        ttsTokens: '',
+                        ttsLexicon: '',
+                    };
+                    const prepareOnly = isRecord(payload) && payload.prepareOnly === true;
+                    if (!prepareOnly) {
+                        await settings.update({ assistant: { ...settings.get().assistant, voice: next } });
+                        runtime.configureEnvironment(buildSherpaRuntimeEnvironment(next));
+                        updateVoiceAgentCapabilities();
+                    }
+                    setupProgress = {
+                        requestId,
+                        progress: { modelId, phase: 'completed', fileName: null, fileIndex: installed.model.files.length,
+                            fileCount: installed.model.files.length, downloadedBytes: 0, totalBytes: null },
+                    };
+                    return { modelId, downloaded: installed.downloaded, ...(prepareOnly ? { voice: next } : {}) };
+                }
+                catch (error) {
+                    setupProgress = null;
+                    throw error;
+                }
+                finally {
+                    setupPending = false;
+                    modelOperation = null;
+                }
+            };
+            const verifyVoiceModel = async (payload) => {
+                const signal = modelAbort.signal;
+                const modelId = readVoiceModelId(payload);
+                if (setupPending)
+                    throw new Error('已有模型操作正在进行，请等待完成');
+                setupPending = true;
+                modelOperation = { modelId, kind: 'verify' };
+                try {
+                    return await models.verify(modelId, readAssistantVoiceSettings(context.services), signal);
+                }
+                finally {
+                    setupPending = false;
+                    modelOperation = null;
+                }
+            };
+            const initialization = new AssistantVoiceInitialization({
+                readModels: async () => {
+                    const voice = readAssistantVoiceSettings(context.services);
+                    const snapshot = await models.snapshot(voice, {
+                        running: runtime.running, ready: runtime.capabilities.realtime, operation: modelOperation,
+                    });
+                    // 旧手工路径配置没有目录 ID，不能把它当作新用户并静默替换。
+                    return snapshot.currentModelId === null && validateAssistantVoiceSettings(voice) === undefined
+                        ? { ...snapshot, currentModelId: 'custom' } : snapshot;
+                },
+                readTts: () => tts.snapshot(),
+                prepareModel: (modelId) => setupVoiceModel({ modelId }),
+                prepareTts: () => tts.handle('tts/setup', {}),
+                selectTts: (id) => tts.handle('tts/select', { id, backend: 'moss-onnx' }),
+                modelProgress: () => setupProgress?.progress ?? null,
+                active: () => coordinator.snapshot().active || runtime.running,
+            });
             if (context.services.registerAssistantVoiceStreamRoute !== undefined) {
-                context.resources.add(context.services.registerAssistantVoiceStreamRoute(createAssistantVoiceStreamHandler({ coordinator })));
+                context.resources.add(context.services.registerAssistantVoiceStreamRoute(createAssistantVoiceStreamHandler({ coordinator, chat: voiceChat, tts: (request) => tts.http(request) })));
             }
             context.resources.add(async () => {
                 await actionBridge.dispose();
                 coordinator.dispose();
             });
+            let configuring = false;
+            const stopAssistant = async () => {
+                conversation.cancelActive();
+                previewChat.cancelActive();
+                textChat.cancelActive();
+                voiceChat.clear();
+                const lease = coordinator.snapshot();
+                if (lease.active && lease.ownerId !== null)
+                    await coordinator.stop(lease.ownerId);
+            };
+            const configureAssistant = async (payload) => {
+                if (configuring)
+                    throw new Error('助理配置正在保存，请稍后操作');
+                const settings = context.services.settings;
+                if (settings === undefined || context.services.settingsProvider?.writable === false)
+                    throw new Error('当前助理设置不可写');
+                const revision = lifecycleRevision;
+                configuring = true;
+                try {
+                    const [catalog, remoteWorkspaces] = await Promise.all([textChat.catalog(), isRecord(payload) && payload.managedWorkspaceIds !== undefined ? readRemoteWorkspaces() : Promise.resolve([])]);
+                    if (revision !== lifecycleRevision || resetting)
+                        throw new Error('助理配置已变化，请重新保存');
+                    const workspaceIds = () => [...readWorkspaceRecords(context.services.dshContext).flatMap((workspace) => [workspace.id, createVirtualWorkspaceId(localHostId, workspace.id), createVirtualWorkspaceId('local', workspace.id)]), ...remoteWorkspaces.map((workspace) => workspace.workspaceId)];
+                    let next = configureAssistantSettings(settings.get().assistant, payload, catalog, workspaceIds());
+                    if (next.tts?.backend === 'moss-onnx' && !(await tts.handle('tts/catalog', {})).status.ready)
+                        throw new Error('请先在更多设置中初始化 MOSS，再选择音色');
+                    await stopAssistant();
+                    if (revision !== lifecycleRevision || resetting)
+                        throw new Error('助理配置已变化，请重新保存');
+                    // 收音停止可能等待异步资源释放，重新合并期间保存的音色、形象和模型文件设置。
+                    next = configureAssistantSettings(settings.get().assistant, payload, catalog, workspaceIds());
+                    const scopeChanged = JSON.stringify([...settings.get().assistant.managedWorkspaceIds].sort()) !== JSON.stringify([...next.managedWorkspaceIds].sort());
+                    lifecycleRevision++;
+                    await settings.update({ assistant: next });
+                    if (isRecord(payload) && payload.configurationPatch !== undefined) {
+                        runtime.configureEnvironment(buildSherpaRuntimeEnvironment(next.voice));
+                        updateVoiceAgentCapabilities();
+                    }
+                    if (scopeChanged && typeof settings.watch !== 'function') {
+                        await conversation.invalidateContext();
+                        invalidateIndex();
+                    }
+                    const selectionChanged = JSON.stringify(indexSelection) !== JSON.stringify(next.model ?? {});
+                    indexSelection = { ...next.model };
+                    if (selectionChanged)
+                        invalidateIndex();
+                    if (next.managedWorkspaceIds.length > 0)
+                        updates.schedule();
+                    return await lifecycleSnapshot();
+                }
+                finally {
+                    configuring = false;
+                }
+            };
+            const resetAssistant = async () => {
+                const settings = context.services.settings;
+                if (settings === undefined || context.services.settingsProvider?.writable === false)
+                    throw new Error('当前助理设置不可写');
+                if (configuring)
+                    throw new Error('请等待助理配置保存完成，再重置');
+                resetting = true;
+                lifecycleRevision++;
+                indexRevision++;
+                updates.pause();
+                cancelIndexAnalysis();
+                modelAbort.abort(new Error('助理已重置'));
+                try {
+                    await stopAssistant();
+                    await Promise.all([tts.cancelPending(), ...[...modelTasks].map((task) => task.catch(() => undefined))]);
+                    await conversation.clear(true);
+                    await settings.update({ assistant: { ...structuredClone(DEFAULT_ASSISTANT_SETTINGS), profile: { name: DEFAULT_ASSISTANT_NAME, initialized: false, createdAt: null } } });
+                    journal.clear();
+                    indexAnalysis.clear();
+                    updates.clear();
+                    materials.clear();
+                    lastSnapshot = null;
+                    lastArchivedSessionIds = [];
+                    indexSelection = {};
+                    setupProgress = null;
+                    initialization.reset();
+                    return await lifecycleSnapshot();
+                }
+                finally {
+                    modelAbort = new AbortController();
+                    resetting = false;
+                }
+            };
             context.resources.add(context.services.rpc.register('assistant', async (action, payload) => {
+                if (resetting && action !== 'lifecycle/read' && action !== 'voice/capabilities' && action !== 'tts/catalog')
+                    throw new Error('助理正在重置，请稍后操作');
+                if (action.startsWith('tts/')) {
+                    if (initialization.busy && action !== 'tts/catalog')
+                        throw new Error('请等待语音初次配置完成');
+                    const result = await tts.handle(action, payload);
+                    updateVoiceAgentCapabilities();
+                    return result;
+                }
                 switch (action) {
+                    case 'lifecycle/read': return await lifecycleSnapshot();
+                    case 'lifecycle/configure': return await configureAssistant(payload);
+                    case 'lifecycle/reset': return await resetAssistant();
+                    case 'conversation/start': {
+                        requireInitialized();
+                        const request = readAssistantRequest(payload);
+                        const attachments = readAssistantAttachmentUploads(asRecord(payload)?.attachments);
+                        return await conversation.start(request.requestId, request.text, await readConversationContext(), 'text', attachments);
+                    }
+                    case 'conversation/preview': {
+                        const request = readAssistantRequest(payload);
+                        const draft = asRecord(asRecord(payload)?.draft) ?? {};
+                        const facts = await readConversationContext(draft);
+                        await previewChat.catalog();
+                        return await previewChat.start({ requestId: request.requestId, provider: facts.provider, model: facts.model, generation: facts.index.generation, messages: [{ role: 'user', text: request.text }] }, facts.index, facts.isCurrent, facts.createSystem, true);
+                    }
+                    case 'conversation/read': return asRecord(payload)?.preview === true ? previewChat.read(readChatRequestId(payload)) : conversation.read(readChatRequestId(payload));
+                    case 'conversation/cancel': return asRecord(payload)?.preview === true ? previewChat.revoke(readChatRequestId(payload)) : conversation.cancel(readChatRequestId(payload));
+                    case 'conversation/clear':
+                        await stopAssistant();
+                        await conversation.clear();
+                        return await lifecycleSnapshot();
+                    case 'conversation/compress': {
+                        requireInitialized();
+                        await stopAssistant();
+                        await conversation.compress(await readConversationContext());
+                        return await lifecycleSnapshot();
+                    }
                     case 'index':
-                        return await buildIndex();
+                        return withIndexAnalysis(await buildIndex());
+                    case 'index/rebuild':
+                        chooseIndexModel(payload);
+                        return startIndexAnalysis(await buildIndex('manual'), true);
+                    case 'index/configure':
+                        chooseIndexModel(payload);
+                        return { configured: true };
+                    case 'index/cancel': {
+                        updates.pause();
+                        const id = readChatRequestId(payload);
+                        return indexAnalysis.cancel(id);
+                    }
+                    case 'chat/models':
+                        return await textChat.catalog();
+                    case 'chat/start': {
+                        const chatContext = readChatContext();
+                        return await textChat.start(payload, chatContext.index, chatContext.isCurrent, chatContext.createSystem);
+                    }
+                    case 'chat/read': {
+                        const index = journal.snapshot().index;
+                        if (index === undefined || !sameManagedScope(index, context.services.settings?.get().assistant.managedWorkspaceIds ?? []))
+                            textChat.cancelActive();
+                        return textChat.read(readChatRequestId(payload));
+                    }
+                    case 'chat/cancel':
+                        return textChat.cancel(readChatRequestId(payload));
                     case 'summary': {
+                        const snapshot = withIndexAnalysis(await buildIndex());
+                        const summary = summarizeAssistantEntries(snapshot.entries, snapshot.scope, snapshot.generation, snapshot.unreadableCount);
+                        return snapshot.analysis?.state === 'completed' && snapshot.analysis.result !== undefined ? { ...summary, speechText: sanitizeSpeechText(speakAssistantStructuredIndex(snapshot.analysis.result)) } : summary;
+                    }
+                    case 'debug': {
+                        // 查看面板只列元数据，不把“刷新视图”混同为“执行索引”。
+                        const managed = context.services.settings?.get().assistant.managedWorkspaceIds ?? [];
+                        const source = await readAssistantSource(context.services, managed, waitingState);
+                        const metadata = await buildAssistantSessionIndex({ sessions: source.sessions, scope: createAssistantScope(managed), archivedSessionIds: source.archivedSessionIds });
+                        observeVersions(metadata.entries);
+                        const history = journal.snapshot();
+                        // 归档、空白状态或工作区成员关系变化后，旧正文不能继续冒充当前结果。
+                        const matching = history.index !== undefined && sameManagedScope(history.index, managed) && sameIndexMembership(history.index, metadata);
+                        if (history.index !== undefined && !matching) {
+                            textChat.cancelActive();
+                            updates.schedule(false);
+                        }
+                        const index = matching ? withIndexAnalysis(history.index, metadata.entries) : metadata;
+                        const tasks = new Map((indexAnalysis.read()?.tasks ?? []).map((task) => [assistantSessionKey(task), task]));
+                        const summary = summarizeAssistantEntries(index.entries, index.scope, index.generation, index.unreadableCount, 0);
+                        const query = readOptionalService(context.services.dshContext, 'sessionQuery');
+                        const snapshot = {
+                            capturedAt: Date.now(),
+                            index,
+                            // 调试页不限制播报长度，复用摘要接口的范围状态和分组语义。
+                            summary: index.analysis?.state === 'completed' && index.analysis.result !== undefined ? { ...summary, speechText: sanitizeSpeechText(speakAssistantStructuredIndex(index.analysis.result)) } : summary,
+                            workspaces: [...readWorkspaceRecords(context.services.dshContext).map((workspace) => ({ workspaceId: workspace.id, name: workspace.name, path: workspace.path })), ...await readRemoteWorkspaces()],
+                            modelId: readAssistantVoiceSettings(context.services).modelId ?? '',
+                            warnings: source.warnings,
+                            scopeSessions: metadata.entries.map((entry) => updates.stamp(entry, tasks.get(assistantSessionKey(entry)))),
+                            indexState: readDebugIndexState(index, { building: buildingIndex !== undefined && buildingIndexRevision === indexRevision, exists: history.index !== undefined, current: lastSnapshot === history.index && matching && updates.matches(index) }),
+                            indexedAt: matching ? history.indexedAt : null,
+                            records: journal.snapshot().records,
+                            services: {
+                                workspaceList: typeof readOptionalService(context.services.dshContext, 'workspaceRegistry')?.list === 'function',
+                                sessionList: typeof readOptionalService(context.services.dshContext, 'sessionController')?.list === 'function' || typeof query?.listSessions === 'function' || context.services.nativeSessions !== undefined,
+                                summaryRead: typeof query?.readSurface === 'function',
+                                taskDispatch: typeof readOptionalService(context.services.dshContext, 'sessionController')?.prompt === 'function',
+                                remoteGateway: context.services.assistantGateway !== undefined,
+                            },
+                        };
+                        return snapshot;
+                    }
+                    case 'preview': {
+                        const request = readAssistantRequest(payload);
                         const snapshot = await buildIndex();
-                        return summarizeAssistantEntries(snapshot.entries, snapshot.scope, snapshot.generation, snapshot.unreadableCount);
+                        return {
+                            generation: snapshot.generation,
+                            intent: parseAssistantIntent(request.text, snapshot.entries, { indexGeneration: snapshot.generation, excludedTargets: snapshot.excludedTargets ?? [] }),
+                        };
                     }
                     case 'turn': {
                         const request = readAssistantRequest(payload);
@@ -174,48 +921,60 @@ export function createGlobalVoiceRpcFeature() {
                         });
                         return result;
                     }
-                    case 'voice/capabilities':
+                    case 'voice/capabilities': {
+                        await tts.snapshot();
+                        updateVoiceAgentCapabilities();
                         return {
                             ...coordinator.snapshot(),
+                            capabilities: { ...runtime.capabilities, textToSpeech: tts.outputReady || runtime.capabilities.textToSpeech, streamingOutput: tts.outputReady || runtime.capabilities.streamingOutput },
                             voiceAgent: agent.capabilities(),
                         };
-                    case 'voice/setup': {
-                        const modelId = readVoiceModelId(payload);
-                        if (coordinator.snapshot().active || runtime.running) {
-                            throw new Error('请先停止当前实时语音，再更换语音模型');
-                        }
-                        const installed = await installAssistantVoiceModel(modelId);
-                        const current = readAssistantVoiceSettings(context.services);
-                        const next = {
-                            ...DEFAULT_ASSISTANT_VOICE_SETTINGS,
-                            ...current,
-                            initialized: true,
-                            provider: 'sherpa-onnx',
-                            modelId,
-                            asrEncoder: installed.paths.asrEncoder,
-                            asrDecoder: installed.paths.asrDecoder,
-                            asrJoiner: installed.paths.asrJoiner,
-                            asrTokens: installed.paths.asrTokens,
-                            // 实时对话使用浏览器输出；不让历史配置中的离线 VAD/TTS 偷偷生效。
-                            vadModel: '',
-                            ttsModel: '',
-                            ttsTokens: '',
-                            ttsLexicon: '',
-                        };
-                        if (context.services.settings === undefined)
-                            throw new Error('当前 Host 不支持保存语音设置');
-                        await context.services.settings.update({
-                            assistant: {
-                                ...context.services.settings.get().assistant,
-                                voice: next,
-                            },
+                    }
+                    case 'configuration/capabilities':
+                        return { prepareOnly: true };
+                    case 'voice/models':
+                        return await models.snapshot(readAssistantVoiceSettings(context.services), {
+                            running: runtime.running, ready: runtime.capabilities.realtime, operation: modelOperation,
                         });
-                        runtime.configureEnvironment(buildSherpaRuntimeEnvironment(next));
+                    case 'voice/initialization':
+                        return await initialization.snapshot();
+                    case 'voice/initialize': {
+                        if (context.services.settings === undefined || context.services.settingsProvider?.writable === false)
+                            throw new Error('当前语音设置不可写');
+                        if (setupPending)
+                            throw new Error('请等待当前识别模型操作完成');
+                        if (isRecord(payload) && payload.prepareOnly === true) {
+                            // 配置窗口只准备资源；识别路径和播报后端由统一保存提交。
+                            const current = await initialization.snapshot();
+                            const modelId = typeof payload.modelId === 'string' ? payload.modelId : current.modelId;
+                            const prepared = current.recognitionReady && modelId === current.modelId ? { voice: readAssistantVoiceSettings(context.services) }
+                                : await setupVoiceModel({ modelId, prepareOnly: true });
+                            if (!current.tts.status.ready)
+                                await tts.handle('tts/setup', { prepareOnly: true });
+                            const ready = await initialization.snapshot();
+                            return { ...ready, ready: true, recognitionReady: true, voice: prepared.voice,
+                                tts: { ...ready.tts, settings: { ...ready.tts.settings, backend: 'moss-onnx' } } };
+                        }
+                        const result = await trackModel(() => initialization.initialize(modelAbort.signal));
                         updateVoiceAgentCapabilities();
-                        return { modelId, downloaded: installed.downloaded };
+                        return result;
+                    }
+                    case 'voice/model/verify':
+                        if (initialization.busy)
+                            throw new Error('请等待语音初次配置完成');
+                        return await trackModel(() => verifyVoiceModel(payload));
+                    case 'voice/setup':
+                        if (initialization.busy)
+                            throw new Error('请等待语音初次配置完成');
+                        return await trackModel(() => setupVoiceModel(payload));
+                    case 'voice/setup-progress': {
+                        const requestId = readVoiceSetupRequestId(payload);
+                        return requestId !== undefined && setupProgress?.requestId === requestId ? setupProgress.progress : null;
                     }
                     case 'voice/start':
                         {
+                            if (setupPending || initialization.busy)
+                                throw new Error('请等待语音模型初始化完成，再启动实时语音');
                             const ownerId = readOwner(payload);
                             if (isRecord(payload) && payload.mode === 'fallback') {
                                 return {
@@ -242,10 +1001,30 @@ export function createGlobalVoiceRpcFeature() {
                                 }
                                 if (!coordinator.snapshot().active) {
                                     runtime.configureEnvironment(buildSherpaRuntimeEnvironment(voiceSettings));
+                                    // 只读最新元数据，不等 LLM 索引总结，也不读取会话正文；失败仍保留领域词。
+                                    let hotwords = buildAssistantVoiceHotwords([], []);
+                                    try {
+                                        hotwords = await readAssistantVoiceHotwords(readManagementSnapshot);
+                                    }
+                                    catch (error) {
+                                        traceVoice('host.asr.hotwords_source_error', { errorName: error instanceof Error ? error.name : 'UnknownError' });
+                                    }
+                                    runtime.configureHotwords(hotwords);
                                 }
                                 const snapshot = await coordinator.start(ownerId);
+                                tts.beginVoiceSession(ownerId);
+                                if (isRecord(payload) && typeof payload.voiceSessionId === 'string') {
+                                    try {
+                                        await conversation.beginVoiceSession(ownerId, payload.voiceSessionId);
+                                    }
+                                    catch (error) {
+                                        await coordinator.stop(ownerId);
+                                        throw error;
+                                    }
+                                }
                                 updateVoiceAgentCapabilities();
-                                return snapshot;
+                                traceVoice('host.call.started', { ownerId, epoch: snapshot.epoch, callId: isRecord(payload) && typeof payload.voiceSessionId === 'string' ? payload.voiceSessionId : undefined });
+                                return { ...snapshot, diagnosticsEnabled: diagnostics !== undefined };
                             }
                             catch (error) {
                                 if (isVoiceRuntimeUnavailableError(error)) {
@@ -258,12 +1037,20 @@ export function createGlobalVoiceRpcFeature() {
                                 throw error;
                             }
                         }
-                    case 'voice/stop':
+                    case 'voice/stop': {
+                        traceVoice('host.call.stopping', { ownerId: readOwner(payload), epoch: coordinator.snapshot().epoch });
+                        coordinator.assertOwner(readOwner(payload));
+                        await conversation.endVoiceSession(readOwner(payload));
+                        voiceChat.clear();
                         return await coordinator.stop(readOwner(payload));
+                    }
                     case 'voice/heartbeat':
                         return coordinator.heartbeat(readOwner(payload));
-                    case 'voice/interrupt':
+                    case 'voice/interrupt': {
+                        coordinator.assertOwner(readOwner(payload));
+                        voiceChat.cancelActive();
                         return await coordinator.interrupt(readOwner(payload));
+                    }
                     case 'voice/register-client': {
                         const ownerId = readOwner(payload);
                         const capabilities = readVoiceRuntimeCapabilities(payload);
@@ -281,21 +1068,49 @@ export function createGlobalVoiceRpcFeature() {
                         const sequence = isRecord(payload) && typeof payload.sequence === 'number' && Number.isFinite(payload.sequence) ? payload.sequence : undefined;
                         return coordinator.acceptClientEvent(ownerId, event, sequence);
                     }
-                    case 'voice/text': {
+                    case 'voice/chat/start':
+                        return await measureVoice('host.chat.start', { requestId: readChatRequestId(payload), ownerId: readOwner(payload) }, () => startVoiceChat(payload));
+                    case 'voice/diagnostics': {
+                        if (diagnostics === undefined)
+                            return { recorded: 0 };
                         const ownerId = readOwner(payload);
-                        coordinator.assertOwner(ownerId);
-                        const request = readAssistantRequest(payload);
-                        const result = await actionBridge.handleFinalText(request.text, request.requestId);
-                        debugInfo('codingns4dsh: assistant voice text resolved', {
-                            requestId: request.requestId,
-                            text: sanitizeSpeechText(request.text).slice(0, 1000),
-                            kind: result.kind,
-                            targetSessionId: result.target?.sessionId ?? null,
-                            targetHostId: result.target?.hostId ?? null,
-                            mode: result.mode ?? null,
-                            ok: result.kind !== 'clarify',
-                        });
-                        return result;
+                        const value = asRecord(payload);
+                        const records = value?.records;
+                        if (!Array.isArray(records) || records.length > 64)
+                            throw new Error('语音诊断每批最多 64 条记录');
+                        let recorded = 0;
+                        for (const item of records) {
+                            if (!isRecord(item) || typeof item.event !== 'string' || !item.event.startsWith('client.') || typeof item.timestamp !== 'number' || !Number.isFinite(item.timestamp) || Math.abs(item.timestamp - Date.now()) > 86400_000)
+                                continue;
+                            diagnostics.writer.record({ timestamp: item.timestamp, event: item.event, fields: { ...sanitizeVoiceDiagnosticFields(item.fields), ownerId } }, 'client');
+                            recorded++;
+                        }
+                        if (typeof value?.dropped === 'number' && value.dropped > 0)
+                            traceVoice('diagnostics.client_dropped', { ownerId, dropped: value.dropped });
+                        return { recorded };
+                    }
+                    case 'voice/chat/read': {
+                        const { ownerId, epoch } = readVoiceChatLease(payload);
+                        return voiceChat.read(ownerId, epoch, readChatRequestId(payload));
+                    }
+                    case 'voice/chat/cancel': {
+                        const { ownerId, epoch } = readVoiceChatLease(payload);
+                        voiceChat.cancel(ownerId, epoch, readChatRequestId(payload));
+                        return { cancelled: true };
+                    }
+                    case 'voice/chat/clear':
+                        readVoiceChatLease(payload);
+                        voiceChat.clear();
+                        await conversation.clear();
+                        return { cleared: true };
+                    case 'voice/text': {
+                        // 兼容旧客户端，但识别话语统一走 LLM，不再隐式触发关键词派发。
+                        const { ownerId, epoch } = readVoiceChatLease(payload);
+                        const run = await startVoiceChat(payload);
+                        const result = await voiceChat.wait(ownerId, epoch, run.requestId);
+                        if (result.state !== 'completed')
+                            throw new Error(result.error ?? '语音 LLM 对话已停止');
+                        return { kind: 'chat', speechText: result.text, requestId: result.requestId };
                     }
                     default:
                         throw new Error(`未知全局语音 RPC: assistant/${action}`);
@@ -304,6 +1119,20 @@ export function createGlobalVoiceRpcFeature() {
         },
     };
 }
+/** 原始材料就绪和完整结构化索引就绪分别表示，失败时不启用问答。 */
+function readDebugIndexState(index, state) {
+    if (state.building || index.analysis?.state === 'running')
+        return 'building';
+    if (!state.exists)
+        return 'not-built';
+    if (!state.current)
+        return 'stale';
+    if (index.entries.some((entry) => entry.indexState !== undefined && entry.indexState !== 'completed'))
+        return 'incomplete';
+    if (index.entries.length > 0 && (index.analysis?.state !== 'completed' || index.analysis.result?.sessions.length !== index.entries.length || index.analysis.tasks?.some((task) => task.state === 'deferred')))
+        return 'incomplete';
+    return 'ready';
+}
 /**
  * 在 Host Context 注册 CodingNS 自己的 voiceAgent 服务。
  *
@@ -358,35 +1187,36 @@ function readAssistantRequest(payload) {
     const requestId = typeof payload.requestId === 'string' && payload.requestId.trim() !== '' ? payload.requestId.trim() : `assistant-${randomUUID()}`;
     return { text: payload.text.trim(), requestId };
 }
-async function dispatchPrompt(services, request) {
+async function dispatchPrompt(services, request, signal = new AbortController().signal) {
     const localHostId = process.env.CODINGNS4DSH_HOST_ID?.trim() || 'local-host';
-    if (request.hostId !== undefined && request.hostId !== localHostId && services.assistantGateway !== undefined) {
-        await services.assistantGateway.dispatch({ ...request, hostId: request.hostId });
+    signal.throwIfAborted();
+    if (request.hostId !== undefined && request.hostId !== localHostId) {
+        if (services.assistantGateway === undefined)
+            throw new Error('远端会话管理网关不可用');
+        await services.assistantGateway.dispatch({ ...request, hostId: request.hostId }, signal);
         return;
     }
     const controller = readOptionalService(services.dshContext, 'sessionController');
     if (controller !== undefined && typeof controller.prompt === 'function') {
-        await controller.prompt(request);
+        const { hostId: _hostId, ...prompt } = request;
+        await controller.prompt(prompt, signal);
         return;
     }
     throw new Error('DSH sessionController.prompt 不可用，无法派发任务');
 }
 async function readAssistantSource(services, managedWorkspaceIds = [], waitingState) {
     const ctx = services.dshContext;
+    const warnings = [];
     const query = readOptionalService(ctx, 'sessionQuery');
-    const primaryValue = query !== undefined && typeof query.listSessions === 'function'
-        ? await query.listSessions()
-        : [];
-    const primaryRecords = flattenSessionList(primaryValue);
-    const bridgeSessions = managedWorkspaceIds.length > 0 && services.nativeSessions !== undefined
-        ? await services.nativeSessions.listRemote()
-        : [];
+    const localSessions = await readLocalAssistantSessions(services, warnings);
     const gatewayResult = services.assistantGateway === undefined || managedWorkspaceIds.length === 0
         ? undefined
-        : await services.assistantGateway.list(managedWorkspaceIds).catch(() => undefined);
+        : await services.assistantGateway.list(managedWorkspaceIds).catch((error) => {
+            warnings.push(`远端 Host 状态读取失败：${sanitizeSpeechText(error instanceof Error ? error.message : String(error)).slice(0, 500)}`);
+            return undefined;
+        });
     const sessions = dedupeSessionRecords([
-        ...primaryRecords,
-        ...(primaryRecords.length === 0 ? flattenSessionList(bridgeSessions) : []),
+        ...localSessions,
         ...(gatewayResult?.sessions ?? []),
     ]);
     const workspaces = readWorkspaceRecords(ctx);
@@ -401,35 +1231,48 @@ async function readAssistantSource(services, managedWorkspaceIds = [], waitingSt
     for (const [sessionId, kind] of waitingState?.snapshot() ?? [])
         waitingBySession.set(sessionId, kind);
     const hostId = process.env.CODINGNS4DSH_HOST_ID?.trim() || 'local-host';
+    let unmappedSessionCount = 0;
     const records = sessions.flatMap((raw) => {
         const value = asRecord(raw);
         const header = asRecord(value?.header) ?? value;
         const sessionId = readText(header, ['sessionId', 'id', 'key']);
         if (sessionId === null)
             return [];
-        // PeerHost Gateway 返回的摘要记录已经携带 workspaceId/hostId；本地
-        // sessionQuery 记录才需要通过 workspaceRegistry 的成员关系或 cwd 反查。
-        const workspaceId = readText(value, ['workspaceId']) ?? findWorkspaceId(sessionId, header, workspaces);
-        if (workspaceId === null || !managed.has(workspaceId) || archivedSet.has(sessionId))
+        // 子代理属于父会话，空白会话只是新会话占位；两者都不是可索引的独立对话。
+        if (header?.origin === 'subagent' || value?.origin === 'subagent' || value?.blank === true || sessionId.startsWith(ASSISTANT_AGENT_PREFIX))
             return [];
-        const workspace = workspaceById.get(workspaceId);
-        const sourceWorkspaceName = readText(value, ['workspaceName', 'workspaceDisplayName']);
         const sourceHostId = readText(value, ['hostId', 'sourceHostId']) ?? hostId;
+        // 本地工作区成员关系由 Registry 决定，cwd 相同不意味着它是工作区成员。
+        // Gateway 已在远端按同一成员关系投影，保留其 workspaceId/hostId。
+        const originalWorkspaceId = sourceHostId === hostId ? findWorkspaceId(sessionId, workspaces) : readText(value, ['workspaceId']);
+        // 保留范围外和归档会话的元数据，索引构建器统一决定纳入/排除。
+        // 不能提前丢掉这些记录，否则调试页和目标澄清都无法解释排除原因。
+        if (originalWorkspaceId === null) {
+            unmappedSessionCount += 1;
+            return [];
+        }
+        const workspaceId = sourceHostId === hostId ? managedWorkspaceIds.find((selected) => assistantWorkspaceMatches(selected, hostId, originalWorkspaceId, true)) ?? originalWorkspaceId : originalWorkspaceId;
+        const workspace = workspaceById.get(originalWorkspaceId);
+        const sourceWorkspaceName = readText(value, ['workspaceName', 'workspaceDisplayName']);
+        const agent = sourceHostId === hostId ? readOptionalService(ctx, 'agents')?.get?.(sessionId) : undefined;
         const state = readText(value, ['state', 'status']) ?? '';
-        const live = value?.live === true;
-        const running = live || value?.running === true || /running|active|working/iu.test(state);
-        // listSessions 的 persisted/live 只是可用性包装，不足以证明会话已完成；
-        // 没有显式状态时保留 completed=false，由索引 status=unknown 表示未知。
-        const completed = value?.completed === true || /completed|complete|done/iu.test(state);
+        // live 只说明存在内存实例；真实运行状态从原生列表或 Agent 状态读取。
+        const running = value?.running === true || /^(running|active|working|queued)$/iu.test(state);
+        // persisted/live 只表示可用性；本轮完成由明确的空闲状态证明。
+        const completed = value?.completed === true || /^(completed|complete|done|success)$/iu.test(state);
+        // 实时 Agent 和 Gateway 的明确 activity 优先于可能滞后的列表布尔值。
+        const activity = agent?.status === 'running' || agent?.status === 'idle' ? agent.status
+            : ['running', 'idle', 'unknown'].includes(value?.activity) ? value.activity : running ? 'running' : value?.running === false || completed || /^(idle|error|failed|cancelled|canceled|stopped)$/iu.test(state) ? 'idle' : 'unknown';
         return [{
                 sessionId,
                 workspaceId,
                 workspaceName: sourceWorkspaceName ?? workspace?.name ?? workspaceId,
                 hostId: sourceHostId,
-                running: running && !completed,
-                completed,
-                error: value?.error === true || /error|failed/iu.test(state),
-                updatedAt: readTimestamp(header, ['updatedAt', 'updated', 'lastUpdatedAt']),
+                running: activity === 'running',
+                activity,
+                completed: activity === 'idle',
+                error: value?.error === true || /^(error|failed)$/iu.test(state),
+                updatedAt: readTimestamp(value, ['updatedAt', 'updated', 'lastUpdatedAt']) ?? readTimestamp(header, ['updatedAt', 'updated', 'lastUpdatedAt']),
                 waiting: readWaiting(value) ?? waitingBySession.get(sessionId) ?? null,
                 title: readText(value, ['title', 'name', 'displayName']),
                 titleEvents: readStringArray(value?.titleEvents),
@@ -437,6 +1280,8 @@ async function readAssistantSource(services, managedWorkspaceIds = [], waitingSt
             }];
     });
     const readSurface = query !== undefined && typeof query.readSurface === 'function' ? query.readSurface.bind(query) : undefined;
+    if (unmappedSessionCount > 0)
+        warnings.push(`有${unmappedSessionCount}个会话无法确定所属工作区，未纳入索引，请检查工作区成员关系。`);
     const readTitle = query !== undefined && typeof query.readTitle === 'function'
         ? query.readTitle.bind(query)
         : query !== undefined && typeof query.readTitleSnapshot === 'function'
@@ -447,7 +1292,7 @@ async function readAssistantSource(services, managedWorkspaceIds = [], waitingSt
         : await Promise.all(records.map(async (record) => {
             // Gateway 已经携带远端标题；本地 query 不能读取远端 Host 的 sessionId，
             // 也不能把远端会话误当成本地会话产生一次额外 I/O。
-            if (record.hostId !== hostId)
+            if (record.hostId !== hostId || !managed.has(record.workspaceId) || archivedSet.has(record.sessionId))
                 return record;
             const title = await readSessionTitle(readTitle, record.sessionId);
             return title === null ? record : { ...record, title };
@@ -455,7 +1300,10 @@ async function readAssistantSource(services, managedWorkspaceIds = [], waitingSt
     // workspaceRegistry 可能只暴露归档 ID，而 sessionQuery 不再返回归档记录。
     // 为了给用户明确的“已归档”诊断，这里只建立没有正文的元数据占位，不读取归档日志。
     const knownSessionIds = new Set(records.map((record) => `${record.hostId}:${record.sessionId}`));
-    const archivedStubs = workspaces.flatMap((workspace) => workspace.archivedSessionIds.flatMap((sessionId) => {
+    const archivedStubs = workspaces.flatMap((workspace) => [...new Set([
+            ...workspace.archivedSessionIds,
+            ...workspace.sessionIds.filter((sessionId) => archivedSet.has(sessionId)),
+        ])].flatMap((sessionId) => {
         const key = `${hostId}:${sessionId}`;
         if (knownSessionIds.has(key))
             return [];
@@ -471,31 +1319,11 @@ async function readAssistantSource(services, managedWorkspaceIds = [], waitingSt
                 title: null,
                 summary: null,
             }];
-    })).concat(sessions.flatMap((raw) => {
-        const value = asRecord(raw);
-        const header = asRecord(value?.header) ?? value;
-        const sessionId = readText(header, ['sessionId', 'id', 'key']);
-        const workspaceId = readText(value, ['workspaceId']);
-        const sourceHostId = readText(value, ['hostId', 'sourceHostId']) ?? hostId;
-        if (sessionId === null || workspaceId === null || sourceHostId === hostId || !managed.has(workspaceId) || !archivedSet.has(sessionId))
-            return [];
-        const workspace = workspaceById.get(workspaceId);
-        return [{
-                sessionId,
-                workspaceId,
-                workspaceName: readText(value, ['workspaceName', 'workspaceDisplayName']) ?? workspace?.name ?? workspaceId,
-                hostId: sourceHostId,
-                running: false,
-                completed: false,
-                updatedAt: null,
-                waiting: null,
-                title: readText(value, ['title', 'name', 'displayName']),
-                summary: null,
-            }];
     }));
     return {
         sessions: [...hydratedRecords, ...archivedStubs],
         archivedSessionIds: archived,
+        warnings,
         ...(gatewayResult?.volatile === true ? { volatile: true } : {}),
         ...((readSurface === undefined && gatewayResult?.readSummary === undefined) ? {} : {
             readSummary: async (session) => {
@@ -515,6 +1343,24 @@ async function readAssistantSource(services, managedWorkspaceIds = [], waitingSt
         }),
     };
 }
+/** 原生列表提供 blank/origin 投影；原始日志目录只能作为旧版本的能力回退。 */
+async function readLocalAssistantSessions(services, warnings) {
+    const controller = readOptionalService(services.dshContext, 'sessionController') ?? services.nativeSessions?.controller;
+    if (typeof controller?.list === 'function') {
+        try {
+            return flattenSessionList(await controller.list({}));
+        }
+        catch {
+            // 列表失败或列表为空都不能改用全量历史，否则会重新纳入被侧栏隐藏的会话。
+            warnings.push('原生会话列表读取失败，暂不纳入本地会话；请刷新后重试。');
+            return [];
+        }
+    }
+    const query = readOptionalService(services.dshContext, 'sessionQuery');
+    if (typeof query?.listSessions === 'function')
+        return flattenSessionList(await query.listSessions());
+    return services.nativeSessions === undefined ? [] : flattenSessionList(await services.nativeSessions.listRemote());
+}
 async function readSessionTitle(readTitle, sessionId) {
     try {
         const value = await readTitle(sessionId);
@@ -567,9 +1413,12 @@ export function summarizeSurfaceEvents(events) {
             continue;
         const type = readText(event, ['type', 'kind', 'event']) ?? '';
         const data = asRecord(event.data);
-        const text = readEventText(event) ?? (data === null ? null : readEventText(data));
+        const message = asRecord(data?.message) ?? asRecord(event.message) ?? data ?? event;
+        const text = readEventText(message);
         if (type === 'user/message' || type === 'user.message' || type === 'message/user') {
-            if (text !== null)
+            // v4 把运行时上下文也放在 user/message；只提取真实用户的消息。
+            const source = asRecord(message.source);
+            if ((source === null || source.kind === 'user') && text !== null)
                 latestUser = text;
         }
         else if (type === 'assistant/message' || type === 'assistant.message' || type === 'message/assistant') {
@@ -600,7 +1449,7 @@ function readEventText(value) {
                 if (typeof item === 'string')
                     return item;
                 const record = asRecord(item);
-                return record === null ? '' : readText(record, ['text', 'content', 'value']) ?? '';
+                return record === null || (record.type !== undefined && record.type !== 'text') ? '' : readText(record, ['text', 'content', 'value']) ?? '';
             })
                 .join(' ')
                 .trim();
@@ -653,6 +1502,43 @@ function readWaitingSessionId(args) {
     }
     return null;
 }
+/** 原生状态事件携带 Agent.session，旧 API 使用第一个 sessionId 字符串。 */
+function readIndexSessionId(args) {
+    for (const item of args) {
+        if (typeof item === 'string' && item !== '')
+            return item;
+        const value = asRecord(item);
+        if (value === null)
+            continue;
+        const session = asRecord(value.session) ?? asRecord(asRecord(value.agent)?.session);
+        const id = readText(value, ['sessionId', 'session_id']) ?? readText(session, ['id', 'sessionId']) ?? readText(asRecord(session?.header), ['id']) ?? readText(asRecord(value.header), ['id']);
+        if (id !== null)
+            return id;
+        if (value.agent === undefined && value.request === undefined) {
+            const direct = readText(value, ['id']);
+            if (direct !== null)
+                return direct;
+        }
+    }
+    return null;
+}
+function readIndexRunning(event, args) {
+    if (event === 'session/complete')
+        return false;
+    for (const item of args) {
+        if (typeof item === 'boolean')
+            return item;
+        const value = asRecord(item);
+        if (typeof value?.running === 'boolean')
+            return value.running;
+        const status = readText(value, ['status', 'state']) ?? (typeof item === 'string' && item !== args[0] ? item : '');
+        if (/^(running|active|working|queued)$/iu.test(status))
+            return true;
+        if (/^(idle|completed|complete|done|success|error|failed|cancelled|canceled|stopped)$/iu.test(status))
+            return false;
+    }
+    return null;
+}
 function readWorkspaceRecords(ctx) {
     const registry = readOptionalService(ctx, 'workspaceRegistry');
     const list = registry !== undefined && typeof registry.list === 'function' ? registry.list() : [];
@@ -707,15 +1593,25 @@ function dedupeSessionRecords(values) {
     }
     return result;
 }
-function findWorkspaceId(sessionId, header, workspaces) {
+function findWorkspaceId(sessionId, workspaces) {
     for (const workspace of workspaces)
         if (workspace.sessionIds.includes(sessionId))
             return workspace.id;
-    const cwd = readText(header, ['cwd']);
-    if (cwd === null)
-        return null;
-    const candidate = workspaces.find((workspace) => workspace.path !== null && (cwd === workspace.path || cwd.startsWith(`${workspace.path}/`)));
-    return candidate?.id ?? null;
+    return null;
+}
+function sameManagedScope(index, managed) {
+    const indexed = index.scope.status === 'empty' ? [] : index.scope.managedWorkspaceIds;
+    return JSON.stringify([...new Set(indexed)].sort()) === JSON.stringify([...new Set(managed)].sort());
+}
+function sameIndexMembership(left, right) {
+    const keys = (index) => index.entries.map((entry) => JSON.stringify([entry.hostId, entry.workspaceId, entry.sessionId])).sort();
+    return JSON.stringify(keys(left)) === JSON.stringify(keys(right));
+}
+function readChatRequestId(payload) {
+    const id = asRecord(payload)?.requestId;
+    if (typeof id !== 'string' || id.length === 0 || id.length > 200)
+        throw new Error('文本调试请求标识无效');
+    return id;
 }
 function readAssistantVoiceSettings(services) {
     const configured = services.settings?.get().assistant?.voice;
@@ -730,6 +1626,11 @@ function readVoiceModelId(payload) {
     }
     return payload.modelId.trim();
 }
+/** 老客户端没有请求 ID 时仍可初始化；进度查询只接受具体请求的 ID。 */
+function readVoiceSetupRequestId(payload) {
+    return isRecord(payload) && typeof payload.requestId === 'string' && payload.requestId.trim() !== ''
+        ? payload.requestId.trim() : undefined;
+}
 function validateAssistantVoiceSettings(settings) {
     if (!settings.initialized)
         return '请先完成全局语音助理初始化配置';
@@ -778,8 +1679,9 @@ function readOptionalService(ctx, name) {
 function asRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null;
 }
+/** 原生列表缺失元数据时，null 和 Map.get() 返回的 undefined 都表示没有字段。 */
 function readText(value, keys) {
-    if (value === null)
+    if (value === null || value === undefined)
         return null;
     for (const key of keys)
         if (typeof value[key] === 'string' && value[key].trim() !== '')
@@ -817,7 +1719,7 @@ function readVoiceRuntimeEvent(payload) {
     const epoch = value !== null && typeof value.epoch === 'number' && Number.isFinite(value.epoch) ? value.epoch : null;
     if (value === null || epoch === null || typeof value.type !== 'string')
         throw new TypeError('全局语音 RPC 的 event 无效');
-    const states = ['disabled', 'loading', 'standby', 'listening', 'speaking', 'interrupted', 'error'];
+    const states = ['disabled', 'loading', 'standby', 'listening', 'thinking', 'speaking', 'interrupted', 'error'];
     if (value.type === 'state' && states.includes(value.state))
         return { type: 'state', state: value.state, epoch };
     if (value.type === 'wake')
@@ -843,7 +1745,7 @@ function readWaiting(value) {
     return null;
 }
 function readTimestamp(value, keys) {
-    if (value === null)
+    if (value === null || value === undefined)
         return null;
     for (const key of keys) {
         if (typeof value[key] === 'number' && Number.isFinite(value[key]))