autosnippet 2.6.0 → 2.7.1

package/lib/external/mcp/handlers/browse.js

@@ -15,7 +15,7 @@ export async function listByKind(ctx, kind, args) {
   const items = (result?.data || result?.items || []).map(r => ({
     id: r.id, title: r.title || r.name, description: r.description,
     trigger: r.trigger || '', status: r.status, language: r.language, category: r.category,
-    knowledgeType: r.knowledgeType || r.knowledge_type, kind: r.kind,
+    knowledgeType: r.knowledgeType, kind: r.kind,
     complexity: r.complexity, scope: r.scope, tags: r.tags || [],
     quality: r.quality || null, statistics: r.statistics || null,
   }));

package/lib/external/mcp/handlers/candidate.js

@@ -1,7 +1,7 @@
 /**
  * MCP Handlers — 候选提交 & 校验 & AI 补全
  * validateCandidate, checkDuplicate, submitSingle, submitBatch, submitDrafts, enrichCandidates
- * + 辅助: buildReasoning, buildCandidateMetadata, _createCandidateItem
+ * + 辅助: buildReasoning, _createCandidateItem
  */
 
 import fs from 'node:fs';
@@ -28,38 +28,6 @@ export function buildReasoning(obj) {
   };
 }
 
-export function buildCandidateMetadata(obj) {
-  const m = {};
-  // 标识 & 描述
-  if (obj.title)        m.title = obj.title;
-  if (obj.description)  m.description = obj.description;
-  // 中英文摘要（summary / summary_cn / summary_en）
-  if (obj.summary_cn || obj.summary)  m.summary = obj.summary_cn || obj.summary;
-  if (obj.summary_en)                 m.summary_en = obj.summary_en;
-  if (obj.trigger)      m.trigger = obj.trigger;
-  // 中英文使用指南（usageGuide / usageGuide_cn / usageGuide_en）
-  if (obj.usageGuide_cn || obj.usageGuide)  m.usageGuide = obj.usageGuide_cn || obj.usageGuide;
-  if (obj.usageGuide_en)                    m.usageGuide_en = obj.usageGuide_en;
-  // 分类
-  if (obj.knowledgeType) m.knowledgeType = obj.knowledgeType;
-  if (obj.complexity)    m.complexity = obj.complexity;
-  if (obj.scope)         m.scope = obj.scope;
-  if (obj.tags)          m.tags = obj.tags;
-  // 结构化内容
-  if (obj.rationale)     m.rationale = obj.rationale;
-  if (obj.steps)         m.steps = obj.steps;
-  if (obj.codeChanges)   m.codeChanges = obj.codeChanges;
-  if (obj.verification)  m.verification = obj.verification;
-  if (obj.headers)       m.headers = obj.headers;
-  // 约束 & 关系
-  if (obj.constraints)   m.constraints = obj.constraints;
-  if (obj.relations)     m.relations = obj.relations;
-  // 质量 & 来源
-  if (obj.quality)       m.quality = obj.quality;
-  if (obj.sourceFile)    m.sourceFile = obj.sourceFile;
-  return m;
-}
-
 /**
  * 统一创建候选的内部方法 — 委托到 CandidateService.createFromToolParams()
  * 保留此函数作为 MCP handler 层的快捷入口，保持向后兼容。

package/lib/external/mcp/handlers/skill.js

@@ -13,11 +13,26 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getProjectSkillsPath } from '../../../infrastructure/config/Paths.js';
+import pathGuard from '../../../shared/PathGuard.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PROJECT_ROOT = path.resolve(__dirname, '../../../..');
-const SKILLS_DIR = path.resolve(PROJECT_ROOT, 'skills');
-const PROJECT_SKILLS_DIR = path.resolve(PROJECT_ROOT, '.autosnippet', 'skills');
+const SKILLS_DIR = path.resolve(__dirname, '../../../../skills');
+
+/**
+ * 获取用户项目根目录（运行时动态解析）
+ */
+function _getProjectRoot() {
+  return process.env.ASD_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * 获取项目级 Skills 目录（运行时动态解析）
+ * 路径: {projectRoot}/AutoSnippet/skills/ — 跟随项目走
+ */
+function _getProjectSkillsDir() {
+  return getProjectSkillsPath(_getProjectRoot());
+}
 
 /**
  * 解析 SKILL.md frontmatter 全部元数据
@@ -93,10 +108,11 @@ export function listSkills() {
 
     // 项目级 Skills（覆盖同名内置）
     try {
-      const projectDirs = fs.readdirSync(PROJECT_SKILLS_DIR, { withFileTypes: true })
+      const projectSkillsDir = _getProjectSkillsDir();
+      const projectDirs = fs.readdirSync(projectSkillsDir, { withFileTypes: true })
         .filter(d => d.isDirectory()).map(d => d.name);
       for (const name of projectDirs) {
-        const meta = _parseSkillMeta(name, PROJECT_SKILLS_DIR);
+        const meta = _parseSkillMeta(name, projectSkillsDir);
         skillMap.set(name, { name, source: 'project', summary: meta.description, createdBy: meta.createdBy, createdAt: meta.createdAt, useCase: SKILL_USE_CASES[name] || null });
       }
     } catch { /* no project skills */ }
@@ -151,7 +167,8 @@ export function loadSkill(_ctx, args) {
   }
 
   // 项目级 Skills 优先
-  const projectSkillPath = path.join(PROJECT_SKILLS_DIR, skillName, 'SKILL.md');
+  const projectSkillsDir = _getProjectSkillsDir();
+  const projectSkillPath = path.join(projectSkillsDir, skillName, 'SKILL.md');
   const builtinSkillPath = path.join(SKILLS_DIR, skillName, 'SKILL.md');
   const skillPath = fs.existsSync(projectSkillPath) ? projectSkillPath : builtinSkillPath;
   const source = skillPath === projectSkillPath ? 'project' : 'builtin';
@@ -172,7 +189,7 @@ export function loadSkill(_ctx, args) {
     }
 
     // 提取 createdBy/createdAt
-    const meta = _parseSkillMeta(skillName, source === 'project' ? PROJECT_SKILLS_DIR : SKILLS_DIR);
+    const meta = _parseSkillMeta(skillName, source === 'project' ? projectSkillsDir : SKILLS_DIR);
 
     return JSON.stringify({
       success: true,
@@ -191,7 +208,7 @@ export function loadSkill(_ctx, args) {
     // 列出所有可用 Skills
     const available = new Set();
     try { fs.readdirSync(SKILLS_DIR, { withFileTypes: true }).filter(d => d.isDirectory()).forEach(d => available.add(d.name)); } catch {}
-    try { fs.readdirSync(PROJECT_SKILLS_DIR, { withFileTypes: true }).filter(d => d.isDirectory()).forEach(d => available.add(d.name)); } catch {}
+    try { fs.readdirSync(_getProjectSkillsDir(), { withFileTypes: true }).filter(d => d.isDirectory()).forEach(d => available.add(d.name)); } catch {}
 
     return JSON.stringify({
       success: false,
@@ -209,7 +226,7 @@ export function loadSkill(_ctx, args) {
 // ═══════════════════════════════════════════════════════════
 
 /**
- * 创建项目级 Skill — 写入 .autosnippet/skills/<name>/SKILL.md
+ * 创建项目级 Skill — 写入 {projectRoot}/AutoSnippet/skills/<name>/SKILL.md
  * 创建后自动 regenerate 编辑器索引（.cursor/rules/autosnippet-skills.mdc）
  *
  * @param {object} _ctx  MCP context
@@ -217,7 +234,7 @@ export function loadSkill(_ctx, args) {
  * @returns {string} JSON envelope
  */
 export function createSkill(_ctx, args) {
-  const { name, description, content, overwrite = false, createdBy = 'external-ai' } = args || {};
+  const { name, description, content, overwrite = false, createdBy = 'external-ai', title } = args || {};
 
   // ── 参数校验 ──
   if (!name || !description || !content) {
@@ -251,7 +268,8 @@ export function createSkill(_ctx, args) {
   }
 
   // 检查同名项目级 Skill
-  const skillDir = path.join(PROJECT_SKILLS_DIR, name);
+  const projectSkillsDir = _getProjectSkillsDir();
+  const skillDir = path.join(projectSkillsDir, name);
   const skillPath = path.join(skillDir, 'SKILL.md');
   if (fs.existsSync(skillPath) && !overwrite) {
     return JSON.stringify({
@@ -265,17 +283,29 @@ export function createSkill(_ctx, args) {
 
   // ── 写入 SKILL.md ──
   try {
+    // 路径安全检查 — name 来自用户输入，可能含路径字符
+    pathGuard.assertProjectWriteSafe(skillDir);
     fs.mkdirSync(skillDir, { recursive: true });
 
-    const frontmatter = [
+    // 自动推断 title: 优先使用传入参数，否则从 content 的第一个 # heading 提取
+    const resolvedTitle = title || (() => {
+      const m = (content || '').match(/^#\s+(.+)/m);
+      return m ? m[1].trim() : '';
+    })();
+
+    const fmLines = [
       '---',
       `name: ${name}`,
+    ];
+    if (resolvedTitle) fmLines.push(`title: "${resolvedTitle.replace(/"/g, '\\"')}"`);
+    fmLines.push(
       `description: ${description}`,
       `createdBy: ${createdBy}`,
       `createdAt: ${new Date().toISOString()}`,
       '---',
       '',
-    ].join('\n');
+    );
+    const frontmatter = fmLines.join('\n');
 
     fs.writeFileSync(skillPath, frontmatter + content, 'utf8');
   } catch (err) {
@@ -288,6 +318,13 @@ export function createSkill(_ctx, args) {
   // ── regenerate 编辑器索引 ──
   const indexResult = _regenerateEditorIndex();
 
+  // ── 清理 SignalCollector 已创建的 pendingSuggestions ──
+  try {
+    if (global._signalCollector) {
+      global._signalCollector.removePendingSuggestion(name);
+    }
+  } catch { /* silent */ }
+
   return JSON.stringify({
     success: true,
     data: {
@@ -310,19 +347,23 @@ function _regenerateEditorIndex() {
   try {
     // 扫描项目级 Skills
     let projectSkills = [];
+    const projectSkillsDir = _getProjectSkillsDir();
     try {
-      const dirs = fs.readdirSync(PROJECT_SKILLS_DIR, { withFileTypes: true })
+      const dirs = fs.readdirSync(projectSkillsDir, { withFileTypes: true })
         .filter(d => d.isDirectory())
         .map(d => d.name);
       for (const name of dirs) {
-        const meta = _parseSkillMeta(name, PROJECT_SKILLS_DIR);
+        const meta = _parseSkillMeta(name, projectSkillsDir);
         projectSkills.push({ name, summary: meta.description });
       }
     } catch { /* no project skills dir */ }
 
+    const projectRoot = _getProjectRoot();
+    const rulesDir = path.join(projectRoot, '.cursor', 'rules');
+
     if (projectSkills.length === 0) {
       // 没有项目级 Skills 时，删除索引文件（如果存在）
-      const indexPath = path.join(PROJECT_ROOT, '.cursor', 'rules', 'autosnippet-skills.mdc');
+      const indexPath = path.join(rulesDir, 'autosnippet-skills.mdc');
       try { fs.unlinkSync(indexPath); } catch { /* not exists */ }
       return { success: true, skillCount: 0 };
     }
@@ -347,7 +388,7 @@ function _regenerateEditorIndex() {
     ].join('\n');
 
     // 写入 .cursor/rules/
-    const rulesDir = path.join(PROJECT_ROOT, '.cursor', 'rules');
+    pathGuard.assertProjectWriteSafe(rulesDir);
     fs.mkdirSync(rulesDir, { recursive: true });
     const indexPath = path.join(rulesDir, 'autosnippet-skills.mdc');
     fs.writeFileSync(indexPath, mdcContent, 'utf8');

package/lib/external/mcp/tools.js

@@ -558,13 +558,14 @@ export const TOOLS = [
       required: ['candidateIds'],
     },
   },
-  // 31. 冷启动知识库初始化（自动创建 9 维度 Candidate）
+  // 31. 冷启动知识库初始化（自动创建 9 维度 Candidate + 4 个 Project Skills）
   {
     name: 'autosnippet_bootstrap_knowledge',
     description:
       '项目冷启动：一键初始化知识库（纯启发式，不使用 AI）。覆盖 9 大知识维度。\n' +
       '自动为每个维度创建 N 条 Candidate（PENDING 状态），基于启发式规则从扫描文件中提取代表性代码。\n' +
-      '返回 filesByTarget、dependencyGraph、bootstrapCandidates、analysisFramework。\n' +
+      'Phase 5.5 自动为 4 个宏观维度（code-standard, architecture, project-profile, agent-guidelines）生成 Project Skills，写入 AutoSnippet/skills/。\n' +
+      '返回 filesByTarget、dependencyGraph、bootstrapCandidates、projectSkills、analysisFramework。\n' +
       '\n' +
       '💡 建议：调用前先加载 autosnippet-coldstart Skill（autosnippet_load_skill），获取完整的 9 维度分析指南和最佳实践。\n' +
       '\n' +
@@ -628,7 +629,7 @@ export const TOOLS = [
   {
     name: 'autosnippet_create_skill',
     description:
-      '创建一个项目级 Skill 文档，写入 .autosnippet/skills/<name>/SKILL.md。\n' +
+      '创建一个项目级 Skill 文档，写入 AutoSnippet/skills/<name>/SKILL.md。\n' +
       'Skill 是 Agent 的领域知识增强文档，帮助 Agent 正确执行特定任务。\n' +
       '创建后自动更新编辑器索引（.cursor/rules/autosnippet-skills.mdc），使 Skill 被 AI Agent 被动发现。\n' +
       '\n' +

package/lib/http/middleware/requestLogger.js

@@ -1,8 +1,15 @@
 /**
  * 请求日志中间件
  * 使用 res.on('finish') 替代猴子补丁 res.send
+ *
+ * 精简策略:
+ *   - GET 请求 + 2xx 状态码: 降为 debug（Dashboard 轮询高频噪音）
+ *   - 非 GET / 非 2xx / 慢请求(>2s): 保留 info 级别
  */
 
+// 轮询/心跳路径 — 完全静默
+const SILENT_PATHS = ['/api/health', '/api/realtime/events', '/api/sse'];
+
 export function requestLogger(logger) {
   return (req, res, next) => {
     const startTime = Date.now();
@@ -10,14 +17,26 @@ export function requestLogger(logger) {
     res.on('finish', () => {
       const duration = Date.now() - startTime;
 
-      logger.info('HTTP Request', {
+      // 完全静默的路径
+      if (SILENT_PATHS.some(p => req.path.startsWith(p))) return;
+
+      const logData = {
         method: req.method,
         path: req.path,
-        query: Object.keys(req.query).length > 0 ? req.query : undefined,
         statusCode: res.statusCode,
         duration: `${duration}ms`,
-        timestamp: new Date().toISOString(),
-      });
+      };
+
+      // 非 GET / 非 2xx / 慢请求 → info; 其余 → debug
+      const isNoisy = req.method === 'GET' && res.statusCode >= 200 && res.statusCode < 300 && duration < 2000;
+      const isSlow = duration >= 1000;
+      if (isSlow) {
+        logger.warn(`🐌慢请求： ${req.method} ${req.path} - ${duration}ms`, logData);
+      } else if (isNoisy) {
+        logger.debug('HTTP', logData);
+      } else {
+        logger.info('HTTP', logData);
+      }
     });
 
     next();

package/lib/http/routes/ai.js

@@ -1,9 +1,11 @@
 /**
  * AI API 路由
- * AI 提供商管理、摘要、翻译、对话
+ * AI 提供商管理、摘要、翻译、对话、.env LLM 配置
  */
 
 import express from 'express';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { asyncHandler } from '../middleware/errorHandler.js';
 import { getServiceContainer } from '../../injection/ServiceContainer.js';
 import { createProvider } from '../../external/ai/AiFactory.js';
@@ -79,7 +81,9 @@ router.post('/config', asyncHandler(async (req, res) => {
     const container = getServiceContainer();
     container.singletons.aiProvider = newProvider;
     logger.info('AI provider synced to DI container', { provider: provider.toLowerCase(), model: newProvider.model });
-  } catch { /* container 未初始化时不阻塞 */ }
+  } catch (err) {
+    logger.debug('DI container 同步 AI provider 失败', { error: err.message });
+  }
 
   res.json({
     success: true,
@@ -242,4 +246,156 @@ router.post('/format-usage-guide', asyncHandler(async (req, res) => {
   res.json({ success: true, data: { formatted } });
 }));
 
+// ═══════════════════════════════════════════════════════
+//  .env LLM 配置读写
+// ═══════════════════════════════════════════════════════
+
+/** 获取用户项目目录下 .env 的路径 */
+function _getProjectEnvPath() {
+  const container = getServiceContainer();
+  const projectRoot = container.singletons?._projectRoot || process.env.ASD_PROJECT_DIR || process.cwd();
+  return join(projectRoot, '.env');
+}
+
+/** LLM 相关的 env 变量名 → 标签映射 */
+const LLM_ENV_KEYS = [
+  'ASD_AI_PROVIDER',
+  'ASD_AI_MODEL',
+  'ASD_GOOGLE_API_KEY',
+  'ASD_OPENAI_API_KEY',
+  'ASD_CLAUDE_API_KEY',
+  'ASD_DEEPSEEK_API_KEY',
+  'ASD_AI_PROXY',
+];
+
+/**
+ * 解析 .env 内容为 key-value（仅提取 LLM 相关变量）
+ * 返回 { vars, hasEnvFile, llmReady }
+ *   llmReady: provider + 至少一个对应 API Key 已配置
+ */
+function parseLlmEnv(envPath) {
+  if (!existsSync(envPath)) {
+    return { vars: {}, hasEnvFile: false, llmReady: false };
+  }
+
+  const raw = readFileSync(envPath, 'utf8');
+  const vars = {};
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    // 跳过注释和空行
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    const val = trimmed.slice(eqIdx + 1).trim().replace(/^["']|["']$/g, '');
+    if (LLM_ENV_KEYS.includes(key)) {
+      vars[key] = val;
+    }
+  }
+
+  // 判断 LLM 是否可用：有 provider + 对应的 API Key
+  const provider = vars.ASD_AI_PROVIDER || '';
+  const keyMap = {
+    google: 'ASD_GOOGLE_API_KEY',
+    openai: 'ASD_OPENAI_API_KEY',
+    claude: 'ASD_CLAUDE_API_KEY',
+    deepseek: 'ASD_DEEPSEEK_API_KEY',
+    ollama: '', // ollama 不需要 key
+    mock: '',   // mock 不需要 key
+  };
+  const neededKey = keyMap[provider] || '';
+  const llmReady = !!provider && (!neededKey || !!vars[neededKey]);
+
+  return { vars, hasEnvFile: true, llmReady };
+}
+
+/**
+ * GET /api/v1/ai/env-config
+ * 读取用户项目 .env 中的 LLM 配置
+ */
+router.get('/env-config', asyncHandler(async (req, res) => {
+  const envPath = _getProjectEnvPath();
+  const result = parseLlmEnv(envPath);
+  res.json({ success: true, data: result });
+}));
+
+/**
+ * POST /api/v1/ai/env-config
+ * 写入 / 更新用户项目 .env 中的 LLM 配置
+ *
+ * Body: { provider, model, apiKey, proxy? }
+ */
+router.post('/env-config', asyncHandler(async (req, res) => {
+  const { provider, model, apiKey, proxy } = req.body;
+  if (!provider || typeof provider !== 'string') {
+    throw new ValidationError('provider is required');
+  }
+
+  const envPath = _getProjectEnvPath();
+  let content = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+
+  // 构建 key-value 更新列表
+  const updates = {
+    ASD_AI_PROVIDER: provider,
+  };
+  if (model) updates.ASD_AI_MODEL = model;
+  if (proxy) updates.ASD_AI_PROXY = proxy;
+
+  // 根据 provider 决定写入哪个 API Key 变量
+  const providerKeyMap = {
+    google: 'ASD_GOOGLE_API_KEY',
+    openai: 'ASD_OPENAI_API_KEY',
+    claude: 'ASD_CLAUDE_API_KEY',
+    deepseek: 'ASD_DEEPSEEK_API_KEY',
+  };
+  const keyName = providerKeyMap[provider];
+  if (keyName && apiKey) {
+    updates[keyName] = apiKey;
+  }
+
+  // 逐条合并到 .env 内容
+  for (const [k, v] of Object.entries(updates)) {
+    // 匹配已有行（包括被注释的行）
+    const activeRe = new RegExp(`^${k}\\s*=.*$`, 'm');
+    const commentedRe = new RegExp(`^#\\s*${k}\\s*=.*$`, 'm');
+
+    if (activeRe.test(content)) {
+      // 替换已有活动行
+      content = content.replace(activeRe, `${k}=${v}`);
+    } else if (commentedRe.test(content)) {
+      // 取消注释并赋值
+      content = content.replace(commentedRe, `${k}=${v}`);
+    } else {
+      // 追加到末尾
+      if (!content.endsWith('\n')) content += '\n';
+      content += `${k}=${v}\n`;
+    }
+  }
+
+  writeFileSync(envPath, content);
+  logger.info('LLM env config updated', { provider, model });
+
+  // 同步到当前进程环境变量（热生效）
+  for (const [k, v] of Object.entries(updates)) {
+    process.env[k] = v;
+  }
+
+  // 尝试热切换 AI Provider
+  try {
+    const newProvider = createProvider({
+      provider: provider.toLowerCase(),
+      model: model || undefined,
+    });
+    const container = getServiceContainer();
+    container.singletons.aiProvider = newProvider;
+    logger.info('AI provider hot-swapped after env update', { provider, model: newProvider.model });
+  } catch (err) {
+    logger.debug('Hot-swap AI provider failed (will take effect on restart)', { error: err.message });
+  }
+
+  const result = parseLlmEnv(envPath);
+  res.json({ success: true, data: result });
+}));
+
 export default router;

package/lib/http/routes/auth.js

@@ -23,8 +23,9 @@ const AUTH_USERNAME = process.env.ASD_AUTH_USERNAME || 'admin';
 const AUTH_PASSWORD = process.env.ASD_AUTH_PASSWORD || 'autosnippet';
 const TOKEN_SECRET  = process.env.ASD_AUTH_SECRET  || crypto.randomBytes(32).toString('hex');
 
-// 安全警告：使用默认凭据时提示
-if (!process.env.ASD_AUTH_USERNAME || !process.env.ASD_AUTH_PASSWORD) {
+// 安全警告：仅在认证启用且使用默认凭据时提示
+const authEnabled = process.env.VITE_AUTH_ENABLED === 'true' || process.env.ASD_AUTH_ENABLED === 'true';
+if (authEnabled && (!process.env.ASD_AUTH_USERNAME || !process.env.ASD_AUTH_PASSWORD)) {
   console.warn(
     '[auth] WARNING: Using default credentials (admin/autosnippet). '
     + 'Set ASD_AUTH_USERNAME and ASD_AUTH_PASSWORD environment variables for production.',

package/lib/http/routes/candidates.js

@@ -7,27 +7,14 @@ import express from 'express';
 import { asyncHandler } from '../middleware/errorHandler.js';
 import { getServiceContainer } from '../../injection/ServiceContainer.js';
 import { NotFoundError, ValidationError } from '../../shared/errors/index.js';
+import Logger from '../../infrastructure/logging/Logger.js';
+import { getContext, safeInt } from '../utils/routeHelpers.js';
 
 const router = express.Router();
+const logger = Logger.getInstance();
 
 const MAX_BATCH_SIZE = 100;
 
-/** 从请求中提取操作上下文 */
-function getContext(req) {
-  return {
-    userId: req.headers['x-user-id'] || 'anonymous',
-    ip: req.ip,
-    userAgent: req.headers['user-agent'] || '',
-  };
-}
-
-/** 安全的整数解析 */
-function safeInt(value, defaultValue, min = 1, max = 1000) {
-  const parsed = parseInt(value, 10);
-  if (Number.isNaN(parsed)) return defaultValue;
-  return Math.max(min, Math.min(max, parsed));
-}
-
 /**
  * GET /api/v1/candidates
  * 获取候选项列表（支持筛选和分页）
@@ -112,7 +99,9 @@ router.post('/', asyncHandler(async (req, res) => {
     duplicateCheck = await chatAgent.executeTool('check_duplicate', {
       candidate: candidateForCheck,
     });
-  } catch { /* 查重失败不阻塞创建 */ }
+  } catch (err) {
+    logger.warn('自动查重失败，不阻塞创建', { error: err.message });
+  }
 
   res.status(201).json({
     success: true,
@@ -249,12 +238,35 @@ router.post('/batch-delete', asyncHandler(async (req, res) => {
   }
   const container = getServiceContainer();
   const candidateService = container.get('candidateService');
-  const candidateRepo = container.get('candidateRepository');
-  const list = await candidateService.listCandidates({ category: targetName }, { page: 1, pageSize: 2000 });
-  const items = list.data || list.items || [];
+
+  // 查两次：按 category 字段 + 全量扫描 metadata.targetName
+  // （前端分组 key = metadata.targetName || category，两者可能不同）
+  const byCategory = await candidateService.listCandidates({ category: targetName }, { page: 1, pageSize: 2000 });
+  const byCategoryItems = byCategory.data || byCategory.items || [];
+
+  // 全量扫描 metadata.targetName 匹配（避免 category 不一致导致漏删）
+  const allList = await candidateService.listCandidates({}, { page: 1, pageSize: 5000 });
+  const allItems = allList.data || allList.items || [];
+  const byTargetName = allItems.filter(c => {
+    const meta = c.metadata || {};
+    return meta.targetName === targetName;
+  });
+
+  // 合并去重
+  const seen = new Set();
+  const merged = [];
+  for (const item of [...byCategoryItems, ...byTargetName]) {
+    if (!seen.has(item.id)) {
+      seen.add(item.id);
+      merged.push(item);
+    }
+  }
+
   let deleted = 0;
-  for (const item of items) {
-    try { await candidateRepo.delete(item.id); deleted++; } catch { /* skip */ }
+  for (const item of merged) {
+    try { await candidateService.deleteCandidate(item.id, { userId: 'batch-delete' }); deleted++; } catch (err) {
+      logger.debug('批量删除: 单条失败', { id: item.id, error: err.message });
+    }
   }
   res.json({ success: true, data: { deleted } });
 }));
@@ -298,7 +310,9 @@ router.post('/similarity', asyncHandler(async (req, res) => {
     if (result && result.length > 0) {
       return res.json({ success: true, data: { similar: result } });
     }
-  } catch { /* fallback to text similarity */ }
+  } catch (err) {
+    logger.debug('SimilarityService 不可用，降级到文本相似度', { error: err.message });
+  }
 
   // Fallback: text-based similarity
   const allRecipes = await recipeService.listRecipes({}, { page: 1, pageSize: 500 });
@@ -490,11 +504,21 @@ router.post('/refine-preview', asyncHandler(async (req, res) => {
 
   const preview = result.results?.[0]?.preview || {};
 
-  // 构建 after 对象
+  // 构建 after 对象（增强 code 字段校验：防止 AI 返回截断/片段代码或类型变更）
+  const origCode = before.code || '';
+  const isOrigMarkdown = /^---\s*\n/.test(origCode) || /^#\s+/.test(origCode) || (origCode.match(/^#{1,3}\s+/gm) || []).length >= 2;
+  const isPreviewMarkdown = preview.code && (/^---\s*\n/.test(preview.code) || /^#\s+/.test(preview.code) || (preview.code.match(/^#{1,3}\s+/gm) || []).length >= 2);
+  // 防止源代码被转成 Markdown 文档
+  const codeTypeChanged = !isOrigMarkdown && isPreviewMarkdown;
+  const isCodeValid = preview.code
+    && preview.code.length > 50
+    && preview.code !== before.code
+    && preview.code.length >= before.code.length * 0.4 // 不能太短（防止截断）
+    && !codeTypeChanged; // 不允许类型变更
   const after = {
     title: preview.title || before.title,
     summary: preview.summary || before.summary,
-    code: (preview.code && preview.code.length > 50 && preview.code !== before.code) ? preview.code : before.code,
+    code: isCodeValid ? preview.code : before.code,
     tags: preview.tags ? [...new Set([...(before.tags || []), ...preview.tags])] : before.tags,
     confidence: (typeof preview.confidence === 'number' && preview.confidence !== 0.6) ? preview.confidence : before.confidence,
     relations: (preview.relations && Array.isArray(preview.relations) && preview.relations.length > 0) ? preview.relations : before.relations,

package/lib/http/routes/commands.js

@@ -238,12 +238,4 @@ router.post('/files/save', asyncHandler(async (req, res) => {
   }
 }));
 
-/**
- * POST /api/v1/commands/execute
- * Execute command (stub - not supported for security)
- */
-router.post('/execute', asyncHandler(async (req, res) => {
-  res.json({ success: false, error: 'Execute not supported' });
-}));
-
 export default router;

package/lib/http/routes/guardRules.js

@@ -7,27 +7,12 @@ import express from 'express';
 import { asyncHandler } from '../middleware/errorHandler.js';
 import { getServiceContainer } from '../../injection/ServiceContainer.js';
 import { NotFoundError, ValidationError } from '../../shared/errors/index.js';
+import { getContext, safeInt } from '../utils/routeHelpers.js';
 
 const router = express.Router();
 
 const MAX_BATCH_SIZE = 100;
 
-/** 从请求中提取操作上下文 */
-function getContext(req) {
-  return {
-    userId: req.headers['x-user-id'] || 'anonymous',
-    ip: req.ip,
-    userAgent: req.headers['user-agent'] || '',
-  };
-}
-
-/** 安全的整数解析 */
-function safeInt(value, defaultValue, min = 1, max = 1000) {
-  const parsed = parseInt(value, 10);
-  if (Number.isNaN(parsed)) return defaultValue;
-  return Math.max(min, Math.min(max, parsed));
-}
-
 /**
  * 将 Recipe 实体 → Guard 规则扁平格式（Dashboard GuardView 期望）
  */