autosnippet 2.8.3 → 2.10.0

package/lib/domain/knowledge/values/Relations.js

@@ -0,0 +1,168 @@
+/**
+ * Relations — 关系图值对象
+ *
+ * 统一为分桶结构（非扁平数组）。
+ * 每个桶存储 [{ target, description }] 格式的关系列表。
+ */
+
+/** 所有合法的关系桶名 (snake_case) */
+export const RELATION_BUCKETS = [
+  'inherits',       // 继承
+  'implements',     // 实现接口/协议
+  'calls',          // 调用
+  'depends_on',     // 依赖
+  'data_flow',      // 数据流向
+  'conflicts',      // 冲突
+  'extends',        // 扩展
+  'related',        // 弱关联
+  'alternative',    // 替代方案
+  'prerequisite',   // 前置条件
+  'deprecated_by',  // 被取代
+  'solves',         // 解决问题
+  'enforces',       // 强制约束
+  'references',     // 引用
+];
+
+/** camelCase → snake_case 桶名映射（兼容旧数据） */
+const LEGACY_BUCKET_MAP = {
+  dependsOn:    'depends_on',
+  dataFlow:     'data_flow',
+  deprecatedBy: 'deprecated_by',
+  dataFlowTo:   'data_flow',
+};
+
+export class Relations {
+  constructor(buckets = {}) {
+    /** @type {Object.<string, Array<{target:string, description:string}>>} */
+    this._b = {};
+    for (const k of RELATION_BUCKETS) {
+      // 同时尝试 snake_case 和 camelCase 的 key
+      const vals = buckets[k] || [];
+      this._b[k] = vals.map(r => ({
+        target:      r.target || '',
+        description: r.description || '',
+      }));
+    }
+    // 处理旧 camelCase key
+    for (const [legacy, canonical] of Object.entries(LEGACY_BUCKET_MAP)) {
+      if (buckets[legacy]?.length > 0) {
+        for (const r of buckets[legacy]) {
+          if (!this._b[canonical].some(x => x.target === r.target)) {
+            this._b[canonical].push({
+              target:      r.target || '',
+              description: r.description || '',
+            });
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * 从任意输入构造 Relations
+   * @param {Relations|Array|Object|null} input
+   * @returns {Relations}
+   */
+  static from(input) {
+    if (input instanceof Relations) return input;
+    if (!input) return new Relations();
+    // 扁平数组 → 自动分桶（兼容旧 Candidate relations）
+    if (Array.isArray(input)) return Relations.fromFlat(input);
+    return new Relations(input);
+  }
+
+  /**
+   * 从扁平数组 [{type, target, description}] 构建分桶
+   * @param {Array<{type:string, target:string, description?:string}>} arr
+   * @returns {Relations}
+   */
+  static fromFlat(arr) {
+    const buckets = {};
+    for (const rel of arr) {
+      const bucket = LEGACY_BUCKET_MAP[rel.type] || rel.type || 'related';
+      if (!buckets[bucket]) buckets[bucket] = [];
+      buckets[bucket].push({
+        target:      rel.target || '',
+        description: rel.description || '',
+      });
+    }
+    return new Relations(buckets);
+  }
+
+  /**
+   * 扁平视图（仅 Dashboard 渲染用）
+   * @returns {Array<{type:string, target:string, description:string}>}
+   */
+  toFlatArray() {
+    const result = [];
+    for (const [type, list] of Object.entries(this._b)) {
+      for (const r of list) {
+        result.push({ type, ...r });
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 获取指定桶
+   * @param {string} type
+   * @returns {Array<{target:string, description:string}>}
+   */
+  getByType(type) {
+    return this._b[type] || [];
+  }
+
+  /**
+   * 是否为空
+   * @returns {boolean}
+   */
+  isEmpty() {
+    return Object.values(this._b).every(l => l.length === 0);
+  }
+
+  /**
+   * 添加关系
+   * @param {string} type 桶名
+   * @param {string} target 目标
+   * @param {string} description
+   * @returns {Relations}
+   */
+  add(type, target, description = '') {
+    if (!this._b[type]) this._b[type] = [];
+    if (!this._b[type].some(r => r.target === target)) {
+      this._b[type].push({ target, description });
+    }
+    return this;
+  }
+
+  /**
+   * 移除关系
+   * @param {string} type 桶名
+   * @param {string} target 目标
+   * @returns {Relations}
+   */
+  remove(type, target) {
+    if (this._b[type]) {
+      this._b[type] = this._b[type].filter(r => r.target !== target);
+    }
+    return this;
+  }
+
+  /**
+   * 转换为 wire format JSON (分桶)
+   */
+  toJSON() {
+    return { ...this._b };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object|Array} data
+   * @returns {Relations}
+   */
+  static fromJSON(data) {
+    return Relations.from(data);
+  }
+}
+
+export default Relations;

package/lib/domain/knowledge/values/Stats.js

@@ -0,0 +1,87 @@
+/**
+ * Stats — 统计值对象
+ *
+ * 记录知识条目的使用统计：浏览、采用、应用、Guard 命中、搜索命中、权威分。
+ */
+export class Stats {
+  constructor(props = {}) {
+    /** @type {number} 浏览次数 */
+    this.views        = props.views        ?? 0;
+    /** @type {number} 采用次数 */
+    this.adoptions    = props.adoptions    ?? 0;
+    /** @type {number} 应用次数 */
+    this.applications = props.applications ?? 0;
+    /** @type {number} Guard 命中次数 */
+    this.guardHits    = props.guard_hits   ?? props.guardHits ?? 0;
+    /** @type {number} 搜索命中次数 */
+    this.searchHits   = props.search_hits  ?? props.searchHits ?? 0;
+    /** @type {number} 权威分 0-5 */
+    this.authority    = props.authority    ?? 0;
+  }
+
+  /**
+   * 从任意输入构造 Stats
+   * @param {Stats|Object|null} input
+   * @returns {Stats}
+   */
+  static from(input) {
+    if (input instanceof Stats) return input;
+    return new Stats(input || {});
+  }
+
+  /**
+   * 从旧 Recipe statistics 字段映射
+   * @param {Object} old
+   * @param {number} qualityOverall 用于初始化 authority
+   * @returns {Stats}
+   */
+  static fromLegacyRecipe(old, qualityOverall = 0) {
+    if (!old) return new Stats();
+    return new Stats({
+      views:        old.viewCount        ?? old.views        ?? 0,
+      adoptions:    old.adoptionCount    ?? old.adoptions    ?? 0,
+      applications: old.applicationCount ?? old.applications ?? 0,
+      guard_hits:   old.guardHitCount    ?? old.guardHits    ?? 0,
+      search_hits:  old.searchHits       ?? 0,
+      authority:    qualityOverall * 5,
+    });
+  }
+
+  /**
+   * 增加计数
+   * @param {'views'|'adoptions'|'applications'|'guardHits'|'searchHits'} counter
+   * @param {number} delta
+   * @returns {Stats}
+   */
+  increment(counter, delta = 1) {
+    if (counter in this && typeof this[counter] === 'number') {
+      this[counter] += delta;
+    }
+    return this;
+  }
+
+  /**
+   * 转换为 wire format JSON (snake_case)
+   */
+  toJSON() {
+    return {
+      views:        this.views,
+      adoptions:    this.adoptions,
+      applications: this.applications,
+      guard_hits:   this.guardHits,
+      search_hits:  this.searchHits,
+      authority:    this.authority,
+    };
+  }
+
+  /**
+   * 从 wire format 创建
+   * @param {Object} data
+   * @returns {Stats}
+   */
+  static fromJSON(data) {
+    return Stats.from(data);
+  }
+}
+
+export default Stats;

package/lib/domain/knowledge/values/index.js

@@ -0,0 +1,9 @@
+/**
+ * 值对象统一导出
+ */
+export { Content } from './Content.js';
+export { Relations, RELATION_BUCKETS } from './Relations.js';
+export { Constraints } from './Constraints.js';
+export { Reasoning } from './Reasoning.js';
+export { Quality } from './Quality.js';
+export { Stats } from './Stats.js';

package/lib/external/ai/AiProvider.js

@@ -174,6 +174,54 @@ export class AiProvider {
       ? `\n# Code Structure Analysis (AST)\nThe following is a Tree-sitter AST analysis of the project. Use this structural context to better understand class hierarchies, design patterns, and code quality when extracting recipes:\n\n${options.astContext.substring(0, 3000)}\n`
       : '';
 
+    // comprehensive 模式：全量分析整个文件，不跳过任何有意义的方法
+    if (options.comprehensive) {
+      return `# Role
+You are a ${langProfile.role} performing a **comprehensive full-file analysis**.
+
+# Goal
+Thoroughly analyze ALL code in "${targetName}" and create Recipe entries for **every significant method, function, or code block**.
+This is a full-file analysis — do NOT skip methods just because they seem "simple" or "standard".
+${skillSection}${astSection}
+
+# What to extract
+- **Every** complete method/function with 5+ lines of implementation
+- Initialization and configuration methods (init, viewDidLoad, setup, configure)
+- Event handlers and action methods
+- Data processing and business logic
+- Protocol/delegate implementations
+- ANY code block that a developer might reference, learn from, or reuse
+
+# Extraction Rules
+- Extract **BROADLY** — include all meaningful code units, not just "clever" or "novel" patterns
+- Each recipe must be a **complete, standalone** code unit with full signature and body
+- Preserve the file's actual code. Use \`<#placeholder#>\` ONLY for literal strings/values a developer would customize
+- Every recipe must be traceable to real code in the file. Do NOT invent code
+- Include relevant \`headers\` (import/require lines) that the code depends on
+- You **MUST** extract at least ONE recipe — every source file has something worth capturing
+
+${langProfile.extractionExamples}
+
+# Output (JSON Array)
+Each item:
+- title (string): Descriptive English name
+- summary_cn (string): Chinese description (2-3 sentences explaining what this code does)
+- summary_en (string): English description (2-3 sentences)
+- trigger (string): @shortcut
+- category: ${langProfile.categories}
+- language: "${langProfile.primaryLanguage}"
+- code (string): Complete function/method/class from the file
+- headers (string[]): Required import/require lines
+- tags (string[]): Search keywords
+- usageGuide_cn (string): "何时使用" + "关键要点" (2-3 lines)
+- usageGuide_en (string): "When to use" + "Key points" (2-3 lines)
+
+Return ONLY a JSON array. Do NOT return an empty array.
+
+Files Content:
+${files}`;
+    }
+
     return `# Role
 You are a ${langProfile.role} extracting production-quality reusable code patterns.
 

package/lib/external/ai/providers/GoogleGeminiProvider.js

@@ -17,7 +17,7 @@ export class GoogleGeminiProvider extends AiProvider {
   constructor(config = {}) {
     super(config);
     this.name = 'google-gemini';
-    this.model = config.model || 'gemini-2.0-flash';
+    this.model = config.model || 'gemini-3-flash-preview';
     this.apiKey = config.apiKey || process.env.ASD_GOOGLE_API_KEY || '';
     this.logger = Logger.getInstance();
   }
@@ -173,7 +173,12 @@ export class GoogleGeminiProvider extends AiProvider {
         if (msg.content) parts.push({ text: msg.content });
         if (msg.toolCalls?.length > 0) {
           for (const tc of msg.toolCalls) {
-            parts.push({ functionCall: { name: tc.name, args: tc.args || {} } });
+            const fcPart = { functionCall: { name: tc.name, args: tc.args || {} } };
+            // Gemini 3+: 回填 thoughtSignature（首个 functionCall 必须携带）
+            if (tc.thoughtSignature) {
+              fcPart.thoughtSignature = tc.thoughtSignature;
+            }
+            parts.push(fcPart);
           }
         }
         if (parts.length > 0) pushOrMerge({ role: 'model', parts });
@@ -266,6 +271,8 @@ export class GoogleGeminiProvider extends AiProvider {
           id: `gemini_fc_${Date.now()}_${fcIndex++}`,
           name: part.functionCall.name,
           args: part.functionCall.args || {},
+          // Gemini 3+: thoughtSignature 必须原样回传，否则后续请求 400
+          thoughtSignature: part.thoughtSignature || undefined,
         });
       } else if (part.text) {
         textParts.push(part.text);
@@ -327,7 +334,9 @@ export class GoogleGeminiProvider extends AiProvider {
         signal: controller.signal,
       });
       if (!res.ok) {
-        const err = new Error(`Gemini API error: ${res.status}`);
+        let detail = '';
+        try { const j = await res.json(); detail = j?.error?.message || JSON.stringify(j).slice(0, 300); } catch { /* ignore */ }
+        const err = new Error(`Gemini API error: ${res.status}${detail ? ' — ' + detail : ''}`);
         err.status = res.status;
         throw err;
       }

package/lib/external/mcp/McpServer.js

@@ -3,7 +3,7 @@
  *
  * Model Context Protocol (stdio transport)
  * 提供给 IDE AI Agent (Cursor/VSCode Copilot) 的工具集
- * 34 工具，全部基于 V2 服务层，不依赖 V1
+ * 38 工具，全部基于 V2 服务层，不依赖 V1
  * Gateway 权限 gating: 写操作经过 Gateway 权限/宪法/审计检查
  *
  * 本文件仅包含服务编排层（初始化、路由、Gateway gating、生命周期）。
@@ -31,6 +31,7 @@ import * as candidateHandlers from './handlers/candidate.js';
 import * as guardHandlers from './handlers/guard.js';
 import * as bootstrapHandlers from './handlers/bootstrap.js';
 import * as skillHandlers from './handlers/skill.js';
+import * as knowledgeHandlers from './handlers/knowledge.js';
 
 // ─── McpServer 类 ─────────────────────────────────────────────
 
@@ -140,12 +141,9 @@ export class McpServer {
       case 'autosnippet_graph_impact':      return structureHandlers.graphImpact(ctx, args);
       case 'autosnippet_graph_path':        return structureHandlers.graphPath(ctx, args);
       case 'autosnippet_graph_stats':       return structureHandlers.graphStats(ctx);
-      // 候选校验 & 提交 & AI 补全
+      // 候选校验 & AI 补全（提交已移至 V3 knowledge handlers）
       case 'autosnippet_validate_candidate':  return candidateHandlers.validateCandidate(ctx, args);
       case 'autosnippet_check_duplicate':   return candidateHandlers.checkDuplicate(ctx, args);
-      case 'autosnippet_submit_candidate':  return candidateHandlers.submitSingle(ctx, args);
-      case 'autosnippet_submit_candidates': return candidateHandlers.submitBatch(ctx, args);
-      case 'autosnippet_submit_draft_recipes': return candidateHandlers.submitDrafts(ctx, args);
       case 'autosnippet_enrich_candidates': return candidateHandlers.enrichCandidates(ctx, args);
       // Guard & 扫描
       case 'autosnippet_guard_check':       return guardHandlers.guardCheck(ctx, args);
@@ -161,6 +159,10 @@ export class McpServer {
       case 'autosnippet_delete_skill':        return skillHandlers.deleteSkill(ctx, args);
       case 'autosnippet_update_skill':        return skillHandlers.updateSkill(ctx, args);
       case 'autosnippet_suggest_skills':      return skillHandlers.suggestSkills(ctx);
+      // V3 知识条目
+      case 'autosnippet_submit_knowledge':        return knowledgeHandlers.submitKnowledge(ctx, args);
+      case 'autosnippet_submit_knowledge_batch':  return knowledgeHandlers.submitKnowledgeBatch(ctx, args);
+      case 'autosnippet_knowledge_lifecycle':      return knowledgeHandlers.knowledgeLifecycle(ctx, args);
       default: throw new Error(`Unknown tool: ${name}`);
     }
   }

package/lib/external/mcp/handlers/bootstrap/pipeline/orchestrator.js

@@ -5,7 +5,7 @@
  *
  * 1. Analyst Agent 自由探索代码 (AST 工具 + 文件搜索)
  * 2. HandoffProtocol 质量门控
- * 3. Producer Agent 格式化输出 (submit_candidate)
+ * 3. Producer Agent 格式化输出 (submit_knowledge)
  * 4. TierScheduler 分层并行执行
  *
  * @module pipeline/orchestrator
@@ -412,7 +412,7 @@ export async function fillDimensionsV3(fillContext) {
       // 记录到 DimensionContext
       for (const tc of (producerResult.toolCalls || [])) {
         const tool = tc.tool || tc.name;
-        if (tool === 'submit_candidate' || tool === 'submit_with_check') {
+        if (tool === 'submit_knowledge' || tool === 'submit_with_check') {
           dimContext.addSubmittedCandidate(dimId, {
             title: tc.params?.title || '',
             subTopic: tc.params?.category || '',
@@ -654,4 +654,5 @@ export async function fillDimensionsV3(fillContext) {
   chatAgent.setFileCache(null);
 }
 
+export { clearCheckpoints };
 export default fillDimensionsV3;

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

@@ -45,7 +45,7 @@ import pathGuard from '../../../shared/PathGuard.js';
 
 // ── Sub-modules ──
 import { loadBootstrapSkills, extractSkillDimensionGuides, enhanceDimensions } from './bootstrap/skills.js';
-import { fillDimensionsV3 } from './bootstrap/pipeline/orchestrator.js';
+import { fillDimensionsV3, clearCheckpoints } from './bootstrap/pipeline/orchestrator.js';
 
 // Re-export for external consumers
 export { loadBootstrapSkills };
@@ -69,6 +69,10 @@ export async function bootstrapKnowledge(ctx, args) {
   const t0 = Date.now();
   const projectRoot = process.env.ASD_PROJECT_DIR || process.cwd();
 
+  // ── 清除旧 checkpoint: 每次手动触发冷启动时重新开始 ──
+  await clearCheckpoints(projectRoot);
+  ctx.logger.info('[Bootstrap] Cleared old checkpoints — starting fresh');
+
   // 路径安全守卫 — 确保所有写操作限制在项目目录内
   if (!pathGuard.configured) {
     const { default: Bootstrap } = await import('../../../bootstrap.js');
@@ -388,7 +392,7 @@ export async function bootstrapKnowledge(ctx, args) {
       skillWorthyDimensions: dimensions.filter(d => d.skillWorthy).map(d => d.id),
       candidateOnlyDimensions: dimensions.filter(d => !d.skillWorthy).map(d => d.id),
       candidateRequiredFields: ['title', 'code', 'language', 'category', 'knowledgeType', 'reasoning'],
-      submissionTool: 'autosnippet_submit_candidates',
+      submissionTool: 'autosnippet_submit_knowledge_batch',
       expectedOutput: '候选知识（微观代码维度：code-pattern/best-practice/event-and-data-flow + 深度扫描：objc-deep-scan/category-scan）+ 6 个 Project Skills（宏观叙事维度：code-standard/architecture/project-profile/agent-guidelines + 深度扫描：objc-deep-scan/category-scan）',
     },
 
@@ -419,7 +423,7 @@ export async function bootstrapKnowledge(ctx, args) {
       '== 完成后可执行的后续操作 ==',
       '1. 调用 autosnippet_enrich_candidates(candidateIds) 补全候选缺失字段',
       '2. 调用 autosnippet_bootstrap_refine() 对候选进行 AI 精炼',
-      '3. 使用 autosnippet_submit_candidates 手动提交更多候选',
+      '3. 使用 autosnippet_submit_knowledge_batch 手动提交更多知识条目',
       '4. 使用 autosnippet_load_skill 加载自动生成的 Project Skills',
       '',
       '== 宏观维度 → Project Skills ==',
@@ -516,7 +520,7 @@ export async function bootstrapKnowledge(ctx, args) {
 /**
  * bootstrapRefine — Phase 6 AI 润色
  *
- * 对 Bootstrap Phase 5 产出的候选进行 AI 二次精炼：
+ * 对 Bootstrap Phase 5 产出的知识条目进行 AI 二次精炼：
  * - 改善模板化描述 → 更自然精准
  * - 补充高阶架构洞察
  * - 推断并填充 relations 关联
@@ -527,7 +531,7 @@ export async function bootstrapKnowledge(ctx, args) {
  */
 export async function bootstrapRefine(ctx, args) {
   const t0 = Date.now();
-  const candidateService = ctx.container.get('candidateService');
+  const knowledgeService = ctx.container.get('knowledgeService');
   const aiProvider = ctx.container.get('aiProvider');
 
   if (!aiProvider) {
@@ -541,17 +545,122 @@ export async function bootstrapRefine(ctx, args) {
     onProgress = (eventName, data) => taskManager.emitProgress(eventName, data);
   } catch { /* optional */ }
 
-  const result = await candidateService.refineBootstrapCandidates(
-    aiProvider,
-    { candidateIds: args.candidateIds, userPrompt: args.userPrompt, dryRun: args.dryRun, onProgress },
-    { userId: 'external_agent' },
-  );
+  // 1. 收集待润色条目
+  let entries;
+  if (args.candidateIds?.length) {
+    entries = [];
+    for (const id of args.candidateIds) {
+      const e = await knowledgeService.get(id);
+      if (e) entries.push(typeof e.toJSON === 'function' ? e.toJSON() : e);
+    }
+  } else {
+    const result = await knowledgeService.list({ lifecycle: 'pending', source: 'bootstrap' }, { page: 1, pageSize: 200 });
+    entries = (result.items || []).map(e => typeof e.toJSON === 'function' ? e.toJSON() : e);
+  }
+
+  if (entries.length === 0) {
+    return envelope({ success: true, data: { refined: 0, total: 0, errors: [], results: [] }, meta: { tool: 'autosnippet_bootstrap_refine', responseTimeMs: Date.now() - t0 } });
+  }
+
+  onProgress?.('refine:started', { total: entries.length, candidateIds: entries.map(e => e.id) });
+
+  // 2. 逐条 AI 润色
+  const allTitles = entries.map(e => e.title).filter(Boolean);
+  const results = [];
+  const errors = [];
+  let refined = 0;
+  let processed = 0;
+
+  for (const entry of entries) {
+    processed++;
+    onProgress?.('refine:item-started', { candidateId: entry.id, title: entry.title, current: processed, total: entries.length, progress: Math.round(((processed - 1) / entries.length) * 100) });
+
+    try {
+      const prompt = `你是一位高级代码知识管理专家。请改进以下知识条目：
+
+标题: ${entry.title}
+类型: ${entry.knowledge_type}
+语言: ${entry.language}
+描述: ${entry.description || ''}
+代码:
+\`\`\`
+${(entry.content?.pattern || '').substring(0, 2000)}
+\`\`\`
+
+同批次知识: ${allTitles.slice(0, 20).join(', ')}
+${args.userPrompt ? `用户补充: ${args.userPrompt}` : ''}
+
+请返回 JSON:
+{
+  "summary": "改进后的中文摘要",
+  "tags": ["建议标签"],
+  "relations": [{"target":"相关条目标题","relation":"depends_on|extends|related_to"}],
+  "confidence": 0.0-1.0,
+  "insight": "架构洞察（一句话）"
+}`;
+
+      const response = await aiProvider.chat(prompt, { temperature: 0.3 });
+      const parsed = aiProvider.extractJSON(response, '{', '}');
+
+      if (!parsed) {
+        errors.push({ id: entry.id, title: entry.title, error: 'AI returned no valid JSON' });
+        onProgress?.('refine:item-failed', { candidateId: entry.id, title: entry.title, error: 'No valid JSON', current: processed, total: entries.length, progress: Math.round((processed / entries.length) * 100) });
+        continue;
+      }
+
+      if (args.dryRun) {
+        results.push({ id: entry.id, title: entry.title, preview: parsed });
+        onProgress?.('refine:item-completed', { candidateId: entry.id, title: entry.title, refined: false, current: processed, total: entries.length, progress: Math.round((processed / entries.length) * 100) });
+        continue;
+      }
+
+      // 构建更新数据
+      const updateData = {};
+      let changed = false;
+
+      if (parsed.summary && parsed.summary !== entry.summary_cn) {
+        updateData.summary_cn = parsed.summary;
+        changed = true;
+      }
+      if (parsed.tags && Array.isArray(parsed.tags)) {
+        const merged = [...new Set([...(entry.tags || []), ...parsed.tags])];
+        if (merged.length > (entry.tags || []).length) {
+          updateData.tags = merged;
+          changed = true;
+        }
+      }
+      if (typeof parsed.confidence === 'number' && parsed.confidence !== 0.6) {
+        updateData.reasoning = { ...(entry.reasoning || {}), confidence: parsed.confidence };
+        changed = true;
+      }
+      if (parsed.insight) {
+        updateData.description = `${entry.description || ''}\n\n**AI Insight**: ${parsed.insight}`.trim();
+        changed = true;
+      }
+
+      if (changed) {
+        await knowledgeService.update(entry.id, updateData);
+        refined++;
+      }
+
+      results.push({ id: entry.id, title: entry.title, refined: changed, fields: Object.keys(parsed) });
+      onProgress?.('refine:item-completed', { candidateId: entry.id, title: entry.title, refined: changed, current: processed, total: entries.length, progress: Math.round((processed / entries.length) * 100), refinedSoFar: refined });
+    } catch (err) {
+      errors.push({ id: entry.id, title: entry.title, error: err.message });
+      onProgress?.('refine:item-failed', { candidateId: entry.id, title: entry.title, error: err.message, current: processed, total: entries.length, progress: Math.round((processed / entries.length) * 100) });
+    }
+  }
+
+  onProgress?.('refine:completed', { total: entries.length, refined, failed: errors.length });
 
   return envelope({
     success: true,
     data: {
-      ...result,
-      message: `Phase 6 AI 润色完成: ${result.refined}/${result.total} 条候选已更新${args.dryRun ? '（预览模式）' : ''}`,
+      refined,
+      total: entries.length,
+      errors,
+      results,
+      message: `Phase 6 AI 润色完成: ${refined}/${entries.length} 条知识条目已更新${args.dryRun ? '（预览模式）' : ''}`,
     },
     meta: { tool: 'autosnippet_bootstrap_refine', responseTimeMs: Date.now() - t0 },
   });