autosnippet 2.5.0 → 2.7.0

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,34 +13,55 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getProjectSkillsPath } from '../../../infrastructure/config/Paths.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');
 
 /**
- * Skill 名称 → 摘要描述映射（用于 list_skills 返回）
+ * 获取用户项目根目录（运行时动态解析）
+ */
+function _getProjectRoot() {
+  return process.env.ASD_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * 获取项目级 Skills 目录（运行时动态解析）
+ * 路径: {projectRoot}/AutoSnippet/skills/ — 跟随项目走
+ */
+function _getProjectSkillsDir() {
+  return getProjectSkillsPath(_getProjectRoot());
+}
+
+/**
+ * 解析 SKILL.md frontmatter 全部元数据
  *
- * 从 SKILL.md 的 frontmatter description 提取。
- * 如果解析失败，返回 Skill 名称本身。
+ * 返回 { description, createdBy, createdAt }，缺失字段为 null。
+ * 同时兼容旧格式（无 createdBy 的 SKILL.md）。
  */
-function _parseSkillSummary(skillName, baseDir = SKILLS_DIR) {
+function _parseSkillMeta(skillName, baseDir = SKILLS_DIR) {
   try {
     const content = fs.readFileSync(
       path.join(baseDir, skillName, 'SKILL.md'), 'utf8',
     );
-    // 提取 frontmatter 的 description 字段
-    const descMatch = content.match(/^description:\s*(.+?)(?:\n|$)/m);
-    if (descMatch) {
-      // 截断到第一句或 120 字符
-      const desc = descMatch[1].trim();
-      const firstSentence = desc.split(/\.\s/)[0];
-      return firstSentence.length < desc.length ? `${firstSentence}.` : desc.substring(0, 120);
+    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+    const meta = { description: skillName, createdBy: null, createdAt: null };
+    if (fmMatch) {
+      const fm = fmMatch[1];
+      const descMatch = fm.match(/^description:\s*(.+?)$/m);
+      if (descMatch) {
+        const desc = descMatch[1].trim();
+        const firstSentence = desc.split(/\.\s/)[0];
+        meta.description = firstSentence.length < desc.length ? `${firstSentence}.` : desc.substring(0, 120);
+      }
+      const cbMatch = fm.match(/^createdBy:\s*(.+?)$/m);
+      if (cbMatch) meta.createdBy = cbMatch[1].trim();
+      const caMatch = fm.match(/^createdAt:\s*(.+?)$/m);
+      if (caMatch) meta.createdAt = caMatch[1].trim();
     }
-    return skillName;
+    return meta;
   } catch {
-    return skillName;
+    return { description: skillName, createdBy: null, createdAt: null };
   }
 }
 
@@ -80,26 +101,39 @@ export function listSkills() {
     const builtinDirs = fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
       .filter(d => d.isDirectory()).map(d => d.name);
     for (const name of builtinDirs) {
-      skillMap.set(name, { name, source: 'builtin', summary: _parseSkillSummary(name, SKILLS_DIR), useCase: SKILL_USE_CASES[name] || null });
+      const meta = _parseSkillMeta(name, SKILLS_DIR);
+      skillMap.set(name, { name, source: 'builtin', summary: meta.description, createdBy: null, createdAt: null, useCase: SKILL_USE_CASES[name] || null });
     }
 
     // 项目级 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) {
-        skillMap.set(name, { name, source: 'project', summary: _parseSkillSummary(name, PROJECT_SKILLS_DIR), useCase: SKILL_USE_CASES[name] || null });
+        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 */ }
 
     const skills = [...skillMap.values()].sort((a, b) => a.name.localeCompare(b.name));
 
+    // _meta：附带 SignalCollector 推荐计数（如果后台服务可用）
+    let suggestionCount = 0;
+    try {
+      if (global._signalCollector) {
+        const snapshot = global._signalCollector.getSnapshot();
+        suggestionCount = snapshot?.lastResult?.newSuggestions || 0;
+      }
+    } catch { /* silent */ }
+
     return JSON.stringify({
       success: true,
       data: {
         skills,
         total: skills.length,
         hint: '根据当前任务选择合适的 Skill 加载（load_skill）。不确定时先加载 autosnippet-intent 做意图路由。',
+        _meta: { signalSuggestions: suggestionCount },
       },
     });
   } catch (err) {
@@ -132,7 +166,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';
@@ -152,6 +187,9 @@ export function loadSkill(_ctx, args) {
       }
     }
 
+    // 提取 createdBy/createdAt
+    const meta = _parseSkillMeta(skillName, source === 'project' ? projectSkillsDir : SKILLS_DIR);
+
     return JSON.stringify({
       success: true,
       data: {
@@ -159,6 +197,8 @@ export function loadSkill(_ctx, args) {
         source,
         content,
         charCount: content.length,
+        createdBy: source === 'project' ? meta.createdBy : null,
+        createdAt: source === 'project' ? meta.createdAt : null,
         useCase: SKILL_USE_CASES[skillName] || null,
         relatedSkills: _getRelatedSkills(skillName),
       },
@@ -167,7 +207,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,
@@ -185,7 +225,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
@@ -193,7 +233,7 @@ export function loadSkill(_ctx, args) {
  * @returns {string} JSON envelope
  */
 export function createSkill(_ctx, args) {
-  const { name, description, content, overwrite = false } = args || {};
+  const { name, description, content, overwrite = false, createdBy = 'external-ai', title } = args || {};
 
   // ── 参数校验 ──
   if (!name || !description || !content) {
@@ -227,7 +267,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({
@@ -243,13 +284,25 @@ export function createSkill(_ctx, args) {
   try {
     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) {
@@ -262,6 +315,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: {
@@ -284,19 +344,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 summary = _parseSkillSummary(name, PROJECT_SKILLS_DIR);
-        projectSkills.push({ name, summary });
+        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 };
     }
@@ -321,7 +385,6 @@ function _regenerateEditorIndex() {
     ].join('\n');
 
     // 写入 .cursor/rules/
-    const rulesDir = path.join(PROJECT_ROOT, '.cursor', 'rules');
     fs.mkdirSync(rulesDir, { recursive: true });
     const indexPath = path.join(rulesDir, 'autosnippet-skills.mdc');
     fs.writeFileSync(indexPath, mdcContent, 'utf8');
@@ -332,6 +395,38 @@ function _regenerateEditorIndex() {
   }
 }
 
+// ═══════════════════════════════════════════════════════════
+// Handler: suggestSkills
+// ═══════════════════════════════════════════════════════════
+
+/**
+ * 基于项目使用模式分析，推荐创建 Skill
+ *
+ * 分析维度：Guard 违规模式、Memory 偏好积累、Recipe 分布缺口、候选积压
+ * Agent 可根据推荐结果自行决定是否调用 createSkill 创建
+ *
+ * @param {object} ctx  MCP context（含 container）
+ * @returns {string} JSON envelope
+ */
+export async function suggestSkills(ctx) {
+  try {
+    const { SkillAdvisor } = await import('../../../service/skills/SkillAdvisor.js');
+    const database = ctx?.container?.get?.('database') || null;
+    const advisor = new SkillAdvisor(PROJECT_ROOT, { database });
+    const result = advisor.suggest();
+
+    return JSON.stringify({
+      success: true,
+      data: result,
+    });
+  } catch (err) {
+    return JSON.stringify({
+      success: false,
+      error: { code: 'SUGGEST_ERROR', message: err.message },
+    });
+  }
+}
+
 /**
  * 推荐相关 Skills（基于静态映射）
  */

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' +
@@ -658,10 +659,31 @@ export const TOOLS = [
           default: false,
           description: '如果同名 Skill 已存在，是否覆盖（默认 false）',
         },
+        createdBy: {
+          type: 'string',
+          enum: ['manual', 'user-ai', 'system-ai', 'external-ai'],
+          default: 'external-ai',
+          description: '创建者类型：manual=用户手动 | user-ai=用户调用AI | system-ai=系统自动 | external-ai=外部AI Agent',
+        },
       },
       required: ['name', 'description', 'content'],
     },
   },
+  // 36. Skill 推荐：基于使用模式分析，推荐创建 Skill
+  {
+    name: 'autosnippet_suggest_skills',
+    description:
+      '基于项目使用模式分析，推荐创建 Skill。\n' +
+      '分析 4 个维度：Guard 违规模式、Memory 偏好积累、Recipe 分布缺口、候选积压率。\n' +
+      '返回推荐列表（含 name / description / rationale / priority），Agent 可据此直接调用 autosnippet_create_skill 创建。\n' +
+      '\n' +
+      '使用时机：\n' +
+      '  • 项目使用一段时间后，定期调用检查是否有新的 Skill 需求\n' +
+      '  • 用户反复说"我们项目不用…"、"以后都…"等偏好表述时\n' +
+      '  • Guard 违规频繁出现同一规则时\n' +
+      '  • 候选被大量驳回时',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
   // 36. ② 内容润色：Bootstrap 候选 AI 精炼（Phase 6）
   {
     name: 'autosnippet_bootstrap_refine',

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

@@ -79,7 +79,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,

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 期望）
  */