autosnippet 3.3.5 → 3.3.7

package/dist/lib/http/routes/ai.js

@@ -25,6 +25,15 @@ const logger = Logger.getInstance();
 function getContainer() {
     return getServiceContainer();
 }
+/** 检查 AI Provider 是否可用（非 mock），不可用则抛 ValidationError */
+function requireAiReady() {
+    const container = getContainer();
+    const manager = container.singletons?._aiProviderManager;
+    if (manager?.isMock) {
+        throw new ValidationError('AI Provider 未配置，当前为 Mock 模式。请先在 .env 中配置 API Key。');
+    }
+    return container;
+}
 // ═══════════════════════════════════════════════════════
 //  UI 语言偏好 — 前端 ↔ 服务端同步
 // ═══════════════════════════════════════════════════════
@@ -76,22 +85,19 @@ router.get('/providers', async (req, res) => {
 });
 /**
  * GET /api/v1/ai/config
- * 获取当前 AI 配置
+ * 获取当前 AI 配置（优先从 AiProviderManager 读取）
  */
 router.get('/config', async (req, res) => {
     const container = getServiceContainer();
-    const p = container.singletons?.aiProvider;
+    const manager = container.singletons?._aiProviderManager;
     res.json({
         success: true,
-        data: {
-            provider: p?.name || '',
-            model: p?.model || '',
-        },
+        data: { provider: manager.name, model: manager.model, isMock: manager.isMock },
     });
 });
 /**
  * POST /api/v1/ai/config
- * 更新 AI 配置（切换提供商/模型）
+ * 更新 AI 配置（切换提供商/模型）— 通过 AiProviderManager 统一热切换
  */
 router.post('/config', validate(AiConfigBody), async (req, res) => {
     const { provider, model } = req.body;
@@ -106,18 +112,13 @@ router.post('/config', validate(AiConfigBody), async (req, res) => {
     catch (error) {
         throw new ValidationError(`Invalid provider: ${error.message}`);
     }
-    // 同步到 DI 容器，使 SearchEngine / Agent / IndexingPipeline 等也使用新 provider
-    try {
-        const container = getServiceContainer();
-        container.reloadAiProvider(newProvider);
-        logger.info('AI provider synced to DI container', {
-            provider: provider.toLowerCase(),
-            model: newProvider.model,
-        });
-    }
-    catch (err) {
-        logger.debug('DI container 同步 AI provider 失败', { error: err.message });
-    }
+    // 通过 reloadAiProvider → AiProviderManager.switchProvider() 统一热切换
+    const container = getServiceContainer();
+    container.reloadAiProvider(newProvider);
+    logger.info('AI provider switched via AiProviderManager', {
+        provider: provider.toLowerCase(),
+        model: newProvider.model,
+    });
     res.json({
         success: true,
         data: {
@@ -127,13 +128,58 @@ router.post('/config', validate(AiConfigBody), async (req, res) => {
         },
     });
 });
+/**
+ * POST /api/v1/ai/mock/cleanup
+ * 清理 Mock 模式产生的候选数据
+ */
+router.post('/mock/cleanup', async (_req, res) => {
+    const container = getContainer();
+    const knowledgeService = container.get('knowledgeService');
+    const dbConn = container.get('database');
+    const rawDb = dbConn.getDb();
+    // 查找所有 mock 来源的候选
+    const mockSources = ['mock-bootstrap', 'mock-pipeline'];
+    let totalDeleted = 0;
+    for (const source of mockSources) {
+        const rows = rawDb
+            .prepare('SELECT id FROM knowledge_entries WHERE source = ?')
+            .all(source);
+        for (const row of rows) {
+            try {
+                await knowledgeService.delete(row.id, { userId: 'system:mock-cleanup' });
+                totalDeleted++;
+            }
+            catch {
+                logger.debug(`Mock cleanup: failed to delete ${row.id}`);
+            }
+        }
+    }
+    // 清理 mock 相关的 semantic_memories
+    try {
+        rawDb
+            .prepare("DELETE FROM semantic_memories WHERE source = 'bootstrap' AND metadata LIKE '%mock%'")
+            .run();
+    }
+    catch {
+        // 表可能不存在
+    }
+    logger.info(`Mock cleanup completed: ${totalDeleted} entries deleted`);
+    const rt = getRealtimeService();
+    if (rt) {
+        rt.broadcastEvent('mock-cleanup-completed', { deleted: totalDeleted });
+    }
+    res.json({
+        success: true,
+        data: { deleted: totalDeleted },
+    });
+});
 /**
  * POST /api/v1/ai/summarize
  * AI 摘要生成
  */
 router.post('/summarize', validate(AiSummarizeBody), async (req, res) => {
     const { code, language } = req.body;
-    const container = getContainer();
+    const container = requireAiReady();
     const factory = container.get('agentFactory');
     const result = await factory.scanKnowledge({
         label: 'code',
@@ -158,7 +204,7 @@ router.post('/translate', validate(AiTranslateBody), async (req, res) => {
         });
     }
     try {
-        const container = getContainer();
+        const container = requireAiReady();
         const factory = container.get('agentFactory');
         const result = await factory.translateToEnglish(summary, usageGuide);
         if (result?.error) {
@@ -197,7 +243,7 @@ router.post('/translate', validate(AiTranslateBody), async (req, res) => {
  */
 router.post('/chat', validate(AiChatBody), async (req, res) => {
     const { prompt, history, lang, conversationId } = req.body;
-    const container = getContainer();
+    const container = requireAiReady();
     const factory = container.get('agentFactory');
     // ── 对话持久化: 从 ConversationStore 加载历史 ──
     let convStore = null;
@@ -309,7 +355,7 @@ router.post('/chat', validate(AiChatBody), async (req, res) => {
  */
 router.post('/agent/tool', validate(AiToolBody), async (req, res) => {
     const { tool, params } = req.body;
-    const container = getContainer();
+    const container = requireAiReady();
     const factory = container.get('agentFactory');
     const result = await factory.invokeAgent(tool, params);
     res.json({ success: true, data: result });
@@ -332,7 +378,7 @@ const DAG_TASK_HANDLERS = {
 };
 router.post('/agent/task', validate(AiTaskBody), async (req, res) => {
     const { task, params } = req.body;
-    const container = getContainer();
+    const container = requireAiReady();
     const factory = container.get('agentFactory');
     // 优先尝试 DAG 任务
     const dagHandler = DAG_TASK_HANDLERS[task];
@@ -530,7 +576,7 @@ router.post('/env-config', validate(AiEnvConfigBody), async (req, res) => {
     for (const [k, v] of Object.entries(updates)) {
         process.env[k] = String(v);
     }
-    // 尝试热切换 AI Provider（包括依赖 AI 的所有服务）
+    // 尝试热切换 AI Provider（通过 AiProviderManager 统一处理）
     try {
         const newProvider = createProvider({
             provider: provider.toLowerCase(),
@@ -538,7 +584,7 @@ router.post('/env-config', validate(AiEnvConfigBody), async (req, res) => {
         });
         const container = getServiceContainer();
         container.reloadAiProvider(newProvider);
-        logger.info('AI provider hot-swapped after env update', {
+        logger.info('AI provider hot-swapped via AiProviderManager after env update', {
             provider,
             model: newProvider.model,
         });
@@ -576,7 +622,7 @@ router.post('/env-config', validate(AiEnvConfigBody), async (req, res) => {
  */
 router.post('/chat/stream', validate(AiStreamBody), async (req, res) => {
     const { prompt, history, lang } = req.body;
-    const container = getContainer();
+    const container = requireAiReady();
     const factory = container.get('agentFactory');
     const session = createStreamSession('chat');
     logger.debug('SSE session created', { sessionId: session.sessionId });
@@ -626,18 +672,53 @@ router.post('/chat/stream', validate(AiStreamBody), async (req, res) => {
     runtime
         .execute(message)
         .then((result) => {
+        const replyText = result.reply || '';
         // 发送最终文本
-        if (result.reply) {
+        if (replyText) {
             const textId = `text_${Date.now()}`;
             session.send({ type: 'text:start', id: textId, role: 'assistant' });
-            session.send({ type: 'text:delta', id: textId, delta: result.reply });
+            session.send({ type: 'text:delta', id: textId, delta: replyText });
             session.send({ type: 'text:end', id: textId });
         }
+        else {
+            logger.warn('SSE session: empty reply from AgentRuntime', {
+                sessionId: session.sessionId,
+                iterations: result.iterations,
+                toolCalls: result.toolCalls?.length || 0,
+            });
+        }
         session.end({
-            text: result.reply,
+            text: replyText || '抱歉，AI 未能生成有效回复。请重试或换个问题。',
             toolCalls: result.toolCalls || [],
             iterations: result.iterations || 0,
         });
+        // ── Token 用量持久化（streaming） ──
+        try {
+            const tokenUsage = result.tokenUsage;
+            if (tokenUsage) {
+                const tokenStore = container.get('tokenUsageStore');
+                const aiProvider = container.singletons?.aiProvider;
+                tokenStore.record({
+                    source: 'user',
+                    provider: aiProvider?.name ?? undefined,
+                    model: aiProvider?.model ?? undefined,
+                    inputTokens: tokenUsage.input || 0,
+                    outputTokens: tokenUsage.output || 0,
+                    durationMs: result.durationMs || 0,
+                    toolCalls: result.toolCalls?.length || 0,
+                });
+                try {
+                    const realtime = getRealtimeService();
+                    realtime?.broadcastTokenUsageUpdated?.();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        catch {
+            /* token tracking should never break streaming */
+        }
         logger.debug('SSE session completed', {
             sessionId: session.sessionId,
             events: session.buffer.length,

package/dist/lib/http/routes/candidates.js

@@ -55,6 +55,13 @@ router.post('/enrich', validate(EnrichBody), async (req, res) => {
     let enrichedCount = 0;
     const results = [];
     if (aiProvider) {
+        // Mock 模式下跳过 AI enrichment
+        if (aiProvider.name === 'mock') {
+            return void res.json({
+                success: true,
+                data: { enriched: 0, total: candidates.length, results: [], mock: true },
+            });
+        }
         let enriched = [];
         try {
             // 获取用户语言偏好
@@ -418,8 +425,8 @@ router.post('/refine-preview', validate(RefinePreviewBody), async (req, res) =>
     const container = getServiceContainer();
     const knowledgeService = container.get('knowledgeService');
     const aiProvider = container.get('aiProvider');
-    if (!aiProvider) {
-        throw new ValidationError('AI provider not configured');
+    if (!aiProvider || aiProvider.name === 'mock') {
+        throw new ValidationError('AI Provider 未配置，当前为 Mock 模式。请先配置 API Key。');
     }
     const entry = await knowledgeService.get(candidateId);
     if (!entry) {
@@ -459,8 +466,8 @@ router.post('/refine-preview-stream', validate(RefinePreviewBody), async (req, r
     const container = getServiceContainer();
     const knowledgeService = container.get('knowledgeService');
     const aiProvider = container.get('aiProvider');
-    if (!aiProvider) {
-        throw new ValidationError('AI provider not configured');
+    if (!aiProvider || aiProvider.name === 'mock') {
+        throw new ValidationError('AI Provider 未配置，当前为 Mock 模式。请先配置 API Key。');
     }
     const entry = await knowledgeService.get(candidateId);
     if (!entry) {

package/dist/lib/http/routes/commands.js

@@ -29,6 +29,15 @@ router.post('/spm-map', async (req, res) => {
  */
 router.post('/embed', async (req, res) => {
     const container = getServiceContainer();
+    // Mock 模式下向量构建需要 embedding — 拒绝执行
+    const manager = container.singletons?._aiProviderManager;
+    if (manager?.isMock) {
+        res.status(400).json({
+            success: false,
+            message: 'AI Provider 未配置，当前为 Mock 模式。Embedding 不可用。',
+        });
+        return;
+    }
     // 优先使用 VectorService (新架构), 降级到 indexingPipeline (旧架构)
     const vectorService = container.services.vectorService ? container.get('vectorService') : null;
     let result;
@@ -80,7 +89,7 @@ router.get('/status', async (req, res) => {
         spmMap: { available: false },
     };
     try {
-        const indexingPipeline = container.get('indexingPipeline');
+        const _indexingPipeline = container.get('indexingPipeline');
         status.index.ready = true; // IndexingPipeline is available
     }
     catch {

package/dist/lib/http/routes/health.js

@@ -1,5 +1,6 @@
 /** 健康检查端点 */
 import express from 'express';
+import { getDeveloperIdentity } from '../../shared/developer-identity.js';
 const router = express.Router();
 /**
  * GET /api/v1/health
@@ -25,4 +26,14 @@ router.get('/ready', (req, res) => {
         timestamp: Math.floor(Date.now() / 1000),
     });
 });
+/**
+ * GET /api/v1/health/identity
+ * 当前开发者身份（从 git config / 环境变量解析）
+ */
+router.get('/identity', (_req, res) => {
+    res.json({
+        success: true,
+        developer: getDeveloperIdentity(),
+    });
+});
 export default router;

package/dist/lib/http/routes/knowledge.js

@@ -5,7 +5,7 @@
  */
 import express from 'express';
 import { ioLimit } from '#shared/concurrency.js';
-import { BatchPublishBody, CreateKnowledgeBody, DeprecateKnowledgeBody, KnowledgeUsageBody, UpdateKnowledgeBody, } from '#shared/schemas/http-requests.js';
+import { BatchDeleteBody, BatchDeprecateBody, BatchPublishBody, CreateKnowledgeBody, DeprecateKnowledgeBody, KnowledgeUsageBody, UpdateKnowledgeBody, } from '#shared/schemas/http-requests.js';
 import Logger from '../../infrastructure/logging/Logger.js';
 import { getServiceContainer } from '../../injection/ServiceContainer.js';
 import { validate } from '../middleware/validate.js';
@@ -140,6 +140,28 @@ router.get('/lifecycle', async (req, res) => {
     }
     res.json({ success: true, data: lifecycle });
 });
+/**
+ * POST /api/v1/knowledge/quality/refresh-all
+ * 批量重新计算所有条目的质量评分
+ */
+router.post('/quality/refresh-all', async (_req, res) => {
+    const container = getServiceContainer();
+    const knowledgeService = container.get('knowledgeService');
+    const result = await knowledgeService.list({}, { page: 1, pageSize: 10000 });
+    const all = result.data;
+    let updated = 0;
+    let failed = 0;
+    for (const entry of all) {
+        try {
+            await knowledgeService.updateQuality(entry.id);
+            updated++;
+        }
+        catch {
+            failed++;
+        }
+    }
+    res.json({ success: true, data: { updated, failed, total: all.length } });
+});
 /**
  * GET /api/v1/knowledge/:id
  * 获取知识条目详情
@@ -229,6 +251,54 @@ router.patch('/:id/reactivate', requirePermission('knowledge', 'update'), async
     const entry = await knowledgeService.reactivate(id, context);
     res.json({ success: true, data: sanitizeForAPI(entry) });
 });
+/**
+ * PATCH /api/v1/knowledge/:id/stage
+ * 暂存 (pending → staging)
+ */
+router.patch('/:id/stage', requirePermission('knowledge', 'update'), async (req, res) => {
+    const id = String(req.params.id);
+    const container = getServiceContainer();
+    const knowledgeService = container.get('knowledgeService');
+    const context = getContext(req);
+    const entry = await knowledgeService.stage(id, context);
+    res.json({ success: true, data: sanitizeForAPI(entry) });
+});
+/**
+ * PATCH /api/v1/knowledge/:id/evolve
+ * 进化 (active → evolving)
+ */
+router.patch('/:id/evolve', requirePermission('knowledge', 'update'), async (req, res) => {
+    const id = String(req.params.id);
+    const container = getServiceContainer();
+    const knowledgeService = container.get('knowledgeService');
+    const context = getContext(req);
+    const entry = await knowledgeService.evolve(id, context);
+    res.json({ success: true, data: sanitizeForAPI(entry) });
+});
+/**
+ * PATCH /api/v1/knowledge/:id/decay
+ * 衰退 (active|evolving → decaying)
+ */
+router.patch('/:id/decay', requirePermission('knowledge', 'update'), async (req, res) => {
+    const id = String(req.params.id);
+    const container = getServiceContainer();
+    const knowledgeService = container.get('knowledgeService');
+    const context = getContext(req);
+    const entry = await knowledgeService.decay(id, context);
+    res.json({ success: true, data: sanitizeForAPI(entry) });
+});
+/**
+ * PATCH /api/v1/knowledge/:id/restore
+ * 恢复为已发布 (decaying|evolving → active)
+ */
+router.patch('/:id/restore', requirePermission('knowledge', 'update'), async (req, res) => {
+    const id = String(req.params.id);
+    const container = getServiceContainer();
+    const knowledgeService = container.get('knowledgeService');
+    const context = getContext(req);
+    const entry = await knowledgeService.restore(id, context);
+    res.json({ success: true, data: sanitizeForAPI(entry) });
+});
 /* ═══ 批量操作 ═══════════════════════════════════════════ */
 /**
  * POST /api/v1/knowledge/batch-publish
@@ -258,6 +328,57 @@ router.post('/batch-publish', requirePermission('knowledge', 'publish'), validat
         },
     });
 });
+/**
+ * POST /api/v1/knowledge/batch-delete
+ * 批量删除知识条目
+ */
+router.post('/batch-delete', requirePermission('knowledge', 'delete'), validate(BatchDeleteBody), async (req, res) => {
+    const { ids } = req.body;
+    const container = getServiceContainer();
+    const knowledgeService = container.get('knowledgeService');
+    const context = getContext(req);
+    const results = await Promise.allSettled(ids.map((id) => ioLimit(() => knowledgeService.delete(id, context))));
+    const deleted = results.filter((r) => r.status === 'fulfilled').length;
+    const failed = results
+        .map((r, i) => (r.status === 'rejected' ? { id: ids[i], error: r.reason?.message } : null))
+        .filter(Boolean);
+    res.json({
+        success: true,
+        data: {
+            total: ids.length,
+            deletedCount: deleted,
+            failureCount: failed.length,
+            failed,
+        },
+    });
+});
+/**
+ * POST /api/v1/knowledge/batch-deprecate
+ * 批量废弃知识条目 (active → deprecated)
+ */
+router.post('/batch-deprecate', requirePermission('knowledge', 'publish'), validate(BatchDeprecateBody), async (req, res) => {
+    const { ids, reason } = req.body;
+    const container = getServiceContainer();
+    const knowledgeService = container.get('knowledgeService');
+    const context = getContext(req);
+    const results = await Promise.allSettled(ids.map((id) => ioLimit(() => knowledgeService.deprecate(id, reason || 'batch deprecate', context))));
+    const deprecated = results
+        .filter((r) => r.status === 'fulfilled')
+        .map((r) => sanitizeForAPI(r.value));
+    const failed = results
+        .map((r, i) => (r.status === 'rejected' ? { id: ids[i], error: r.reason?.message } : null))
+        .filter(Boolean);
+    res.json({
+        success: true,
+        data: {
+            deprecated,
+            failed,
+            total: ids.length,
+            successCount: deprecated.length,
+            failureCount: failed.length,
+        },
+    });
+});
 /* ═══ 使用 / 质量 ═══════════════════════════════════════ */
 /**
  * POST /api/v1/knowledge/:id/usage

package/dist/lib/http/routes/modules.js

@@ -5,7 +5,7 @@
  * 所有端点通过 container.get('moduleService') 获取 ModuleService 实例
  */
 import express from 'express';
-import { ModuleBootstrapBody, ScanFolderBody, ScanProjectBody, ScanTargetBody, } from '#shared/schemas/http-requests.js';
+import { ModuleBootstrapBody, ModuleRescanBody, ScanFolderBody, ScanProjectBody, ScanTargetBody, } from '#shared/schemas/http-requests.js';
 import Logger from '../../infrastructure/logging/Logger.js';
 import { getServiceContainer } from '../../injection/ServiceContainer.js';
 import { validate } from '../middleware/validate.js';
@@ -416,14 +416,17 @@ router.get('/project-info', async (req, res) => {
 router.post('/bootstrap', validate(ModuleBootstrapBody), async (req, res) => {
     const { maxFiles, skipGuard, contentMaxLines } = req.body || {};
     const container = getServiceContainer();
-    const agentFactory = container.get('agentFactory');
     logger.info('Bootstrap cold start initiated (ModuleService path)');
-    const bootstrapResult = await agentFactory.bootstrapKnowledge({
+    // 直接调用 bootstrap-internal handler（统一编排管线）
+    const { bootstrapKnowledge } = await import('#external/mcp/handlers/bootstrap-internal.js');
+    const raw = await bootstrapKnowledge({ container, logger }, {
         maxFiles: maxFiles || 500,
         skipGuard: skipGuard || false,
         contentMaxLines: contentMaxLines || 120,
         loadSkills: true,
     });
+    const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    const bootstrapResult = parsed?.data || parsed;
     res.json({
         success: true,
         data: {
@@ -456,4 +459,50 @@ router.get('/bootstrap/status', async (req, res) => {
         data: taskManager.getSessionStatus(),
     });
 });
+/**
+ * POST /api/v1/modules/bootstrap/cancel
+ * 取消正在运行的 bootstrap / rescan 异步填充会话
+ */
+router.post('/bootstrap/cancel', async (req, res) => {
+    const container = getServiceContainer();
+    let taskManager = null;
+    try {
+        taskManager = container.get('bootstrapTaskManager');
+    }
+    catch {
+        /* not registered */
+    }
+    if (!taskManager) {
+        return void res.json({ success: true, message: 'No bootstrap task manager initialized' });
+    }
+    if (!taskManager.isRunning) {
+        return void res.json({ success: true, message: 'No active bootstrap session' });
+    }
+    const reason = req.body?.reason || 'Cancelled by user via Dashboard';
+    taskManager.abortSession(reason);
+    logger.info('Bootstrap session cancelled via HTTP', { reason });
+    res.json({
+        success: true,
+        data: taskManager.getSessionStatus(),
+    });
+});
+/**
+ * POST /api/v1/modules/rescan
+ * 增量扫描：保留已有 Recipe，重新分析项目，补齐缺失知识
+ * 使用内部 Agent pipeline 自动完成知识补齐
+ */
+router.post('/rescan', validate(ModuleRescanBody), async (req, res) => {
+    const { reason, dimensions } = req.body || {};
+    const container = getServiceContainer();
+    logger.info('Rescan (internal) initiated from Dashboard', { reason, dimensions });
+    // 直接调用 rescan-internal handler（统一编排管线）
+    const { rescanInternal } = await import('#external/mcp/handlers/rescan-internal.js');
+    const raw = await rescanInternal({ container, logger }, { reason: reason || 'dashboard-rescan', dimensions });
+    const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    const result = parsed?.data || parsed;
+    res.json({
+        success: true,
+        data: result,
+    });
+});
 export default router;

package/dist/lib/http/routes/panorama.js

@@ -14,7 +14,7 @@ const router = express.Router();
  * GET /api/v1/panorama
  * 返回项目全景概览（层级、模块、覆盖率）
  */
-router.get('/', async (_req, res) => {
+router.get('/', async (req, res) => {
     try {
         const container = getServiceContainer();
         const panoramaService = container.get('panoramaService');
@@ -25,6 +25,9 @@ router.get('/', async (_req, res) => {
             });
             return;
         }
+        if (req.query.refresh === 'true' && typeof panoramaService.invalidate === 'function') {
+            panoramaService.invalidate();
+        }
         if (typeof panoramaService.ensureData === 'function') {
             await panoramaService.ensureData();
         }
@@ -42,7 +45,7 @@ router.get('/', async (_req, res) => {
  * GET /api/v1/panorama/health
  * 返回全景健康度评分
  */
-router.get('/health', async (_req, res) => {
+router.get('/health', async (req, res) => {
     try {
         const container = getServiceContainer();
         const panoramaService = container.get('panoramaService');
@@ -53,6 +56,9 @@ router.get('/health', async (_req, res) => {
             });
             return;
         }
+        if (req.query.refresh === 'true' && typeof panoramaService.invalidate === 'function') {
+            panoramaService.invalidate();
+        }
         if (typeof panoramaService.ensureData === 'function') {
             await panoramaService.ensureData();
         }
@@ -70,7 +76,7 @@ router.get('/health', async (_req, res) => {
  * GET /api/v1/panorama/gaps
  * 返回知识空白区列表
  */
-router.get('/gaps', async (_req, res) => {
+router.get('/gaps', async (req, res) => {
     try {
         const container = getServiceContainer();
         const panoramaService = container.get('panoramaService');
@@ -81,6 +87,9 @@ router.get('/gaps', async (_req, res) => {
             });
             return;
         }
+        if (req.query.refresh === 'true' && typeof panoramaService.invalidate === 'function') {
+            panoramaService.invalidate();
+        }
         if (typeof panoramaService.ensureData === 'function') {
             await panoramaService.ensureData();
         }
@@ -98,7 +107,7 @@ router.get('/gaps', async (_req, res) => {
  * GET /api/v1/panorama/coverage
  * 返回各模块知识覆盖率热力图数据
  */
-router.get('/coverage', async (_req, res) => {
+router.get('/coverage', async (req, res) => {
     try {
         const container = getServiceContainer();
         const panoramaService = container.get('panoramaService');
@@ -109,6 +118,9 @@ router.get('/coverage', async (_req, res) => {
             });
             return;
         }
+        if (req.query.refresh === 'true' && typeof panoramaService.invalidate === 'function') {
+            panoramaService.invalidate();
+        }
         if (typeof panoramaService.ensureData === 'function') {
             await panoramaService.ensureData();
         }

package/dist/lib/http/routes/recipes.js

@@ -70,6 +70,13 @@ router.post('/discover-relations', async (req, res) => {
             data: { status: 'error', error: 'AgentFactory 不可用，请检查 AI Provider 配置' },
         });
     }
+    // Mock 模式下跳过 AI 关系发现
+    if (agentFactory.getAiProviderInfo?.()?.name === 'mock') {
+        return void res.json({
+            success: true,
+            data: { status: 'error', error: 'AI Provider 未配置，当前为 Mock 模式。请先配置 API Key。' },
+        });
+    }
     // 快速检查：至少需要 2 条活跃 Recipe
     try {
         const knowledgeService = container.get('knowledgeService');

package/dist/lib/http/utils/routeHelpers.js

@@ -3,13 +3,14 @@
  * 提取自各路由文件中的重复实现
  */
 import { KnowledgeEntry } from '../../domain/knowledge/KnowledgeEntry.js';
+import { getDeveloperIdentity } from '../../shared/developer-identity.js';
 /**
  * 从请求中提取操作上下文（用户身份、IP、UA）
  * @returns }
  */
 export function getContext(req) {
     return {
-        userId: String(req.headers['x-user-id'] || 'anonymous'),
+        userId: String(req.headers['x-user-id'] || getDeveloperIdentity()),
         ip: req.ip || '',
         userAgent: req.headers['user-agent'] || '',
     };