autosnippet 3.2.10 → 3.2.12

package/lib/external/mcp/handlers/wiki-external.js

@@ -1,593 +0,0 @@
-/**
- * MCP Handlers — Cursor-Native Wiki 生成
- *
- *   - wikiPlan:     数据收集 + 主题发现 → 返回写作规划
- *   - wikiFinalize: Agent 写完所有文章后调用 → meta.json + 去重 + 验证
- *
- * 设计理念:
- *   现有 WikiGenerator 的核心价值在于 **数据收集 + 主题发现**（AST、模块图、知识库）。
- *   文章撰写由外部 Agent 完成（200K+ context），AutoSnippet 只做规划和元数据。
- *   bootstrap Phase 1-4 的分析缓存可被 wikiPlan 复用，避免重复计算。
- *
- * @module handlers/wiki-external
- */
-
-import { createHash } from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-import Logger from '../../../infrastructure/logging/Logger.js';
-import { WikiGenerator } from '../../../service/wiki/WikiGenerator.js';
-import { dedup, slug } from '../../../service/wiki/WikiUtils.js';
-import { envelope } from '../envelope.js';
-import { getActiveSession } from './bootstrap-external.js';
-
-const logger = Logger.getInstance();
-
-// ── 辅助：安全获取容器服务 ──────────────────────────────────
-
-function tryGet(container, name) {
-  try {
-    return container.get(name);
-  } catch {
-    return null;
-  }
-}
-
-// ════════════════════════════════════════════════════════════
-//  wikiPlan — 规划 Wiki 主题 + 数据包
-// ════════════════════════════════════════════════════════════
-
-/**
- * 规划 Wiki 文档生成 (autosnippet_wiki_plan)
- *
- * 复用 WikiGenerator 的数据收集和主题发现逻辑（Phase 1-5），
- * 但不撰写文章，只返回规划清单和每个主题的数据包。
- *
- * @param {object} ctx  — { container, logger, startedAt }
- * @param {object} args — { language?: 'zh'|'en', sessionId?: string }
- */
-export async function wikiPlan(ctx, args) {
-  const t0 = Date.now();
-  const language = args.language || 'zh';
-  const container = ctx.container;
-  const projectRoot =
-    container.singletons?._projectRoot || process.env.ASD_PROJECT_DIR || process.cwd();
-
-  // ── 优先复用 bootstrap 已有的分析缓存 ──
-  let projectInfo, astInfo, moduleInfo, knowledgeInfo;
-  let cacheHit = false;
-
-  const session = getActiveSession(container, args.sessionId);
-  const cachedData = session?.phaseCache;
-
-  if (cachedData?.astProjectSummary) {
-    // Bootstrap phase cache → WikiGenerator-compatible format 转换
-    const allFiles = cachedData.allFiles || [];
-    const ast = cachedData.astProjectSummary;
-
-    // projectInfo: 从 bootstrap 文件列表和语言统计构建
-    const filesByModule = {};
-    for (const f of allFiles) {
-      const mod = f.targetName || '_default';
-      if (!filesByModule[mod]) filesByModule[mod] = [];
-      filesByModule[mod].push(f.relativePath);
-    }
-    projectInfo = {
-      name: path.basename(projectRoot),
-      root: projectRoot,
-      sourceFiles: allFiles.map(f => f.relativePath),
-      languages: cachedData.langStats || {},
-      primaryLanguage: cachedData.primaryLang || 'unknown',
-      sourceFilesByModule: filesByModule,
-      buildSystems: [],
-    };
-
-    // astInfo: 从 AstAnalyzer 结果构建
-    const classesByModule = {};
-    const protocolsByModule = {};
-    for (const cls of ast.classes || []) {
-      const mod = cls.targetName || '_default';
-      if (!classesByModule[mod]) classesByModule[mod] = [];
-      classesByModule[mod].push(cls.name);
-    }
-    for (const p of ast.protocols || []) {
-      const mod = p.targetName || '_default';
-      if (!protocolsByModule[mod]) protocolsByModule[mod] = [];
-      protocolsByModule[mod].push(p.name);
-    }
-    astInfo = {
-      classes: (ast.classes || []).map(c => c.name),
-      protocols: (ast.protocols || []).map(p => p.name),
-      overview: ast.projectMetrics || null,
-      classNamesByModule: classesByModule,
-      protocolNamesByModule: protocolsByModule,
-    };
-
-    // moduleInfo: 从依赖图和 targets 构建
-    moduleInfo = {
-      targets: (cachedData.targetsSummary || []).map(t => ({
-        name: t.name, type: t.type, fileCount: t.fileCount,
-      })),
-      depGraph: cachedData.depGraphData || null,
-    };
-
-    // knowledgeInfo: 始终从 DB 获取最新（bootstrap 期间可能已写入知识）
-    try {
-      const ks = tryGet(container, 'knowledgeService');
-      if (ks) {
-        const items = await ks.list({ limit: 200 });
-        const stats = typeof ks.getStats === 'function' ? await ks.getStats() : null;
-        knowledgeInfo = { recipes: items?.items || items || [], stats };
-      } else {
-        knowledgeInfo = { recipes: [], stats: null };
-      }
-    } catch {
-      knowledgeInfo = { recipes: [], stats: null };
-    }
-
-    cacheHit = true;
-    logger.info('[wiki-plan] Reusing bootstrap phase cache (converted to WikiGenerator format)');
-  } else {
-    // 无缓存（独立调用 wiki_plan 或进程已重启）→ 重新扫描
-    logger.info('[wiki-plan] No bootstrap cache, running fresh scan...');
-    const generator = new WikiGenerator({
-      projectRoot,
-      moduleService: tryGet(container, 'moduleService'),
-      knowledgeService: tryGet(container, 'knowledgeService'),
-      projectGraph: tryGet(container, 'projectGraph'),
-      codeEntityGraph: tryGet(container, 'codeEntityGraph'),
-      aiProvider: null, // 不需要 AI — 只做规划
-      options: { language },
-    });
-
-    projectInfo = await generator._scanProject();
-    astInfo = await generator._analyzeAST();
-    moduleInfo = await generator._parseModules();
-    knowledgeInfo = await generator._integrateKnowledge();
-  }
-
-  // ── 主题发现（复用 WikiGenerator._discoverTopics） ──
-  const generator = new WikiGenerator({
-    projectRoot,
-    moduleService: tryGet(container, 'moduleService'),
-    knowledgeService: tryGet(container, 'knowledgeService'),
-    projectGraph: tryGet(container, 'projectGraph'),
-    codeEntityGraph: tryGet(container, 'codeEntityGraph'),
-    aiProvider: null,
-    options: { language },
-  });
-
-  const rawTopics = generator._discoverTopics(projectInfo, astInfo, moduleInfo, knowledgeInfo);
-
-  // ── 为每个主题构建 dataBundle ──
-  const structuredData = { projectInfo, astInfo, moduleInfo, knowledgeInfo };
-  const isZh = language === 'zh';
-
-  const topics = rawTopics.map((topic) => {
-    const mapped = {
-      id: topic.id,
-      path: topic.path,
-      title: topic.title,
-      type: topic.type,
-      priority: topic.priority,
-      writingGuide: _buildWritingGuide(topic, isZh),
-      dataBundle: _buildTopicDataBundle(topic, structuredData),
-    };
-
-    // 添加其他主题引用（供导航链接）
-    mapped.dataBundle.otherTopicPaths = rawTopics
-      .filter((t) => t.id !== topic.id)
-      .map((t) => ({ path: t.path, title: t.title }));
-
-    return mapped;
-  });
-
-  // ── 确保 Wiki 目录存在 ──
-  const wikiDir = path.join(projectRoot, 'AutoSnippet', 'wiki');
-  _ensureDir(wikiDir);
-  if (topics.some((t) => t.path.startsWith('modules/'))) {
-    _ensureDir(path.join(wikiDir, 'modules'));
-  }
-  if (topics.some((t) => t.path.startsWith('patterns/'))) {
-    _ensureDir(path.join(wikiDir, 'patterns'));
-  }
-  if (topics.some((t) => t.path.startsWith('folders/'))) {
-    _ensureDir(path.join(wikiDir, 'folders'));
-  }
-
-  return envelope({
-    success: true,
-    data: {
-      wikiDir: path.join('AutoSnippet', 'wiki'),
-      absoluteWikiDir: wikiDir,
-      topicCount: topics.length,
-      topics,
-      writingGuidelines: _buildWritingGuidelines(isZh),
-      cacheHit,
-    },
-    meta: {
-      tool: 'autosnippet_wiki_plan',
-      responseTimeMs: Date.now() - t0,
-    },
-  });
-}
-
-// ════════════════════════════════════════════════════════════
-//  wikiFinalize — 写入 meta.json + 去重 + 验证
-// ════════════════════════════════════════════════════════════
-
-/**
- * 完成 Wiki 生成 (autosnippet_wiki_finalize)
- *
- * Agent 写完所有文章后调用。负责：
- *   1. 验证文件存在性
- *   2. 去重检查（内容相似度）
- *   3. 写入 meta.json
- *   4. 同步 Cursor 端文档（可选）
- *
- * @param {object} ctx  — { container, logger, startedAt }
- * @param {object} args — { articlesWritten: string[] }
- */
-export async function wikiFinalize(ctx, args) {
-  const t0 = Date.now();
-  const { articlesWritten } = args;
-
-  if (!Array.isArray(articlesWritten) || articlesWritten.length === 0) {
-    return envelope({
-      success: false,
-      message: 'articlesWritten is required and must be a non-empty array of file paths',
-      errorCode: 'VALIDATION_ERROR',
-      meta: { tool: 'autosnippet_wiki_finalize' },
-    });
-  }
-
-  const container = ctx.container;
-  const projectRoot =
-    container.singletons?._projectRoot || process.env.ASD_PROJECT_DIR || process.cwd();
-  const wikiDir = path.join(projectRoot, 'AutoSnippet', 'wiki');
-
-  // ── 1. 验证文件存在性 ──
-  const missingFiles = [];
-  const thinFiles = [];
-  const fileDetails = [];
-  let totalSize = 0;
-
-  for (const relPath of articlesWritten) {
-    const fullPath = path.join(wikiDir, relPath);
-
-    // 安全检查 — 防路径遍历
-    const resolved = path.resolve(fullPath);
-    if (!resolved.startsWith(path.resolve(wikiDir))) {
-      missingFiles.push(relPath);
-      continue;
-    }
-
-    if (!fs.existsSync(fullPath)) {
-      missingFiles.push(relPath);
-      continue;
-    }
-
-    const stat = fs.statSync(fullPath);
-    const content = fs.readFileSync(fullPath, 'utf-8');
-    totalSize += stat.size;
-
-    if (content.length < 200) {
-      thinFiles.push(relPath);
-    }
-
-    fileDetails.push({
-      path: relPath,
-      size: stat.size,
-      hash: createHash('md5').update(content).digest('hex'),
-    });
-  }
-
-  // ── 2. 去重检查 ──
-  let dedupResult = { duplicatesFound: 0, removed: [] };
-  try {
-    const files = fileDetails.map((f) => ({
-      path: f.path,
-      hash: f.hash,
-      size: f.size,
-    }));
-    dedupResult = dedup(files, wikiDir, () => {});
-  } catch (e) {
-    logger.warn(`[wiki-finalize] Dedup check failed: ${e.message}`);
-  }
-
-  // ── 3. 写入 meta.json ──
-  // 计算 sourceHash — 与 WikiGenerator._computeSourceHash() 保持一致
-  // 使得 getStatus()._detectChanges() 对比时能正确判定"无变更"
-  let sourceHash;
-  try {
-    const generator = new WikiGenerator({
-      projectRoot,
-      options: { language: 'zh' },
-    });
-    sourceHash = generator._computeSourceHash();
-  } catch (e) {
-    logger.warn(`[wiki-finalize] Failed to compute sourceHash: ${e.message}`);
-  }
-
-  const meta = {
-    generatedAt: new Date().toISOString(),
-    version: '3.0-cursor-native',
-    source: 'external-agent',
-    filesCount: fileDetails.length,
-    totalSize,
-    files: fileDetails,
-    ...(sourceHash ? { sourceHash } : {}),
-  };
-
-  try {
-    _ensureDir(wikiDir);
-    fs.writeFileSync(path.join(wikiDir, 'meta.json'), JSON.stringify(meta, null, 2));
-  } catch (e) {
-    return envelope({
-      success: false,
-      message: `Failed to write meta.json: ${e.message}`,
-      errorCode: 'IO_ERROR',
-      meta: { tool: 'autosnippet_wiki_finalize' },
-    });
-  }
-
-  // ── 4. 同步 Cursor 端文档（仅检测，不修改 Agent 写的内容）──
-  let syncedDocs = 0;
-  try {
-    const devdocsDir = path.join(
-      projectRoot,
-      '.cursor',
-      'skills',
-      'autosnippet-devdocs',
-      'references'
-    );
-    if (fs.existsSync(devdocsDir)) {
-      const docsDir = path.join(wikiDir, 'documents');
-      _ensureDir(docsDir);
-      const mdFiles = fs.readdirSync(devdocsDir).filter((f) => f.endsWith('.md'));
-      for (const file of mdFiles) {
-        const src = path.join(devdocsDir, file);
-        const dest = path.join(docsDir, file);
-        if (!fs.existsSync(dest)) {
-          // 只同步 Agent 没写的文档
-          const content = fs.readFileSync(src, 'utf-8');
-          const header = `<!-- synced from .cursor/skills/autosnippet-devdocs/references/${file} -->\n\n`;
-          fs.writeFileSync(dest, header + content);
-          syncedDocs++;
-        }
-      }
-    }
-  } catch (e) {
-    logger.debug(`[wiki-finalize] Cursor docs sync skipped: ${e.message}`);
-  }
-
-  return envelope({
-    success: true,
-    data: {
-      fileCount: fileDetails.length,
-      totalSize: `${(totalSize / 1024).toFixed(1)} KB`,
-      dedup: dedupResult,
-      validation: {
-        missingFiles,
-        thinFiles,
-        passed: missingFiles.length === 0,
-      },
-      syncedDocs,
-      meta,
-    },
-    meta: {
-      tool: 'autosnippet_wiki_finalize',
-      responseTimeMs: Date.now() - t0,
-    },
-  });
-}
-
-// ════════════════════════════════════════════════════════════
-//  内部辅助函数
-// ════════════════════════════════════════════════════════════
-
-function _ensureDir(dir) {
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-}
-
-/**
- * 为主题生成写作指南
- */
-function _buildWritingGuide(topic, isZh) {
-  const guides = {
-    overview: isZh
-      ? '撰写完整的项目概述文档。包含: 项目简介(解释项目做什么)、模块总览(表格形式)、技术栈分析、核心数据指标。底部包含导航索引，链接到其他 wiki 文档。'
-      : 'Write a comprehensive project overview. Include: project introduction (what it does), module overview (table format), tech stack analysis, key metrics. Add navigation index at bottom linking to other wiki docs.',
-    architecture: isZh
-      ? '撰写项目架构文档。包含: 整体架构图(描述层次关系)、模块职责划分、模块间依赖关系(文字描述或 Mermaid 图)、核心设计决策、扩展点说明。'
-      : 'Write architecture documentation. Include: overall architecture diagram (layer relationships), module responsibilities, inter-module dependencies (Mermaid diagrams), core design decisions, extension points.',
-    'getting-started': isZh
-      ? '撰写快速上手文档。包含: 环境要求、安装步骤、构建命令、运行方式、项目结构简介。面向项目新成员。'
-      : 'Write getting started guide. Include: prerequisites, installation steps, build commands, how to run, project structure intro. Target new team members.',
-    module: isZh
-      ? '撰写模块深度文档。包含: 模块定位与职责、核心类及其关系、公共 API 概览(主要方法列表)、依赖关系、设计模式、使用示例。'
-      : 'Write module deep-dive documentation. Include: module purpose, core classes and relationships, public API overview, dependencies, design patterns, usage examples.',
-    patterns: isZh
-      ? '基于知识库中的 Recipe 整理代码模式文档。按分类组织，每个模式包含: 名称、触发场景、规则内容、代码示例。'
-      : 'Organize code patterns from knowledge base recipes. Group by category, each pattern includes: name, trigger scenario, rule content, code examples.',
-    'pattern-category': isZh
-      ? '撰写该分类下的代码模式文档。每个模式包含: 模式名称、应用场景、具体规则、代码示例。'
-      : 'Write code patterns for this category. Each pattern: name, applicable scenario, specific rules, code examples.',
-    reference: isZh
-      ? '撰写协议/接口参考文档。按功能分组，每个协议包含: 名称、职责描述、方法签名列表、实现类。'
-      : 'Write protocol/interface reference. Group by function, each includes: name, responsibility, method signatures, implementations.',
-    'folder-overview': isZh
-      ? '撰写项目结构分析文档。概述各个重要目录的功能定位、文件组织方式、命名规范。'
-      : 'Write project structure analysis. Overview important directory purposes, file organization, naming conventions.',
-    'folder-profile': isZh
-      ? '撰写该目录的详细分析文档。包含: 目录职责、文件列表与说明、入口点、命名模式、与其他目录的关系。'
-      : 'Write detailed directory analysis. Include: purpose, file list with descriptions, entry points, naming patterns, relationships with other directories.',
-  };
-
-  return guides[topic.type] || (isZh
-    ? '撰写详细的技术文档，结构清晰，内容准确。'
-    : 'Write detailed technical documentation with clear structure and accurate content.');
-}
-
-/**
- * 为主题构建数据包
- */
-function _buildTopicDataBundle(topic, structuredData) {
-  const { projectInfo, astInfo, moduleInfo, knowledgeInfo } = structuredData;
-  const bundle = {};
-
-  switch (topic.type) {
-    case 'overview':
-      bundle.projectName = projectInfo.name;
-      bundle.sourceFileCount = projectInfo.sourceFiles.length;
-      bundle.primaryLanguage = projectInfo.primaryLanguage;
-      bundle.langProfile = projectInfo.langProfile;
-      bundle.buildSystems = projectInfo.buildSystems;
-      bundle.languages = projectInfo.languages;
-      bundle.moduleCount = moduleInfo.targets?.length || 0;
-      bundle.moduleList = (moduleInfo.targets || []).map((t) => ({
-        name: t.name,
-        type: t.type || t.info?.type || 'unknown',
-        fileCount: t.sourceFileCount || t.info?.sourceFileCount || 0,
-        dependencies: (t.dependencies || t.info?.dependencies || []).slice(0, 10),
-      }));
-      bundle.astOverview = astInfo.overview || {};
-      bundle.recipeCount = knowledgeInfo.recipes?.length || 0;
-      break;
-
-    case 'architecture':
-      bundle.modules = (moduleInfo.targets || []).map((t) => ({
-        name: t.name,
-        type: t.type || t.info?.type || 'unknown',
-        path: t.path || t.info?.path || '',
-        dependencies: t.dependencies || t.info?.dependencies || [],
-      }));
-      bundle.depGraph = moduleInfo.depGraph
-        ? { nodes: moduleInfo.depGraph.nodes?.length || 0, edges: moduleInfo.depGraph.edges?.length || 0 }
-        : null;
-      // 热实体信息（高入度类/协议）
-      bundle.classCount = astInfo.classes?.length || 0;
-      bundle.protocolCount = astInfo.protocols?.length || 0;
-      bundle.hotClasses = (astInfo.classes || []).slice(0, 15);
-      bundle.hotProtocols = (astInfo.protocols || []).slice(0, 10);
-      break;
-
-    case 'getting-started':
-      bundle.projectName = projectInfo.name;
-      bundle.buildSystems = projectInfo.buildSystems;
-      bundle.primaryLanguage = projectInfo.primaryLanguage;
-      bundle.hasPackageSwift = projectInfo.hasPackageSwift;
-      bundle.hasPodfile = projectInfo.hasPodfile;
-      bundle.hasXcodeproj = projectInfo.hasXcodeproj;
-      bundle.entryPoints = astInfo.overview?.entryPoints || [];
-      break;
-
-    case 'module': {
-      const md = topic._moduleData || {};
-      bundle.targetInfo = md.target
-        ? { name: md.target.name, type: md.target.type || 'unknown', path: md.target.path || '' }
-        : { name: topic.title };
-      bundle.classNames = (astInfo.classNamesByModule?.[topic.title] || []).slice(0, 30);
-      bundle.protocolNames = (astInfo.protocolNamesByModule?.[topic.title] || []).slice(0, 15);
-      bundle.sourceFiles = (md.moduleFiles || []).slice(0, 30);
-      bundle.classCount = md.classCount || 0;
-      bundle.protoCount = md.protoCount || 0;
-      bundle.dependencies = md.target?.dependencies || md.target?.info?.dependencies || [];
-      break;
-    }
-
-    case 'patterns': {
-      const groups = {};
-      for (const r of knowledgeInfo.recipes || []) {
-        const json = r.toJSON ? r.toJSON() : r;
-        const cat = json.category || 'Other';
-        if (!groups[cat]) groups[cat] = [];
-        groups[cat].push({
-          title: json.title || json.name,
-          trigger: json.trigger || json.name,
-          kind: json.kind || 'pattern',
-          summary: json.summary || json.description || '',
-        });
-      }
-      bundle.recipesByCategory = groups;
-      bundle.totalRecipes = knowledgeInfo.recipes?.length || 0;
-      break;
-    }
-
-    case 'pattern-category': {
-      const pd = topic._patternData || {};
-      bundle.category = pd.category;
-      bundle.recipes = (pd.recipes || []).map((r) => ({
-        title: r.title || r.name,
-        trigger: r.trigger || r.name,
-        kind: r.kind || 'pattern',
-        summary: r.summary || r.description || '',
-        content: r.content?.substring(0, 500) || '', // 截断长内容
-      }));
-      break;
-    }
-
-    case 'reference':
-      bundle.protocols = (astInfo.protocols || []).slice(0, 40);
-      bundle.protocolsByModule = astInfo.protocolNamesByModule || {};
-      break;
-
-    case 'folder-overview':
-      bundle.folderProfiles = (topic._folderProfiles || []).map((fp) => ({
-        relPath: fp.relPath,
-        fileCount: fp.fileCount,
-        languages: fp.languages,
-        entryPoints: fp.entryPoints?.slice(0, 5) || [],
-        namingPatterns: fp.namingPatterns?.slice(0, 5) || [],
-        hasReadme: !!fp.readme,
-      }));
-      break;
-
-    case 'folder-profile': {
-      const fp = topic._folderProfile || {};
-      bundle.relPath = fp.relPath;
-      bundle.fileCount = fp.fileCount;
-      bundle.languages = fp.languages;
-      bundle.files = (fp.files || []).slice(0, 30);
-      bundle.entryPoints = fp.entryPoints || [];
-      bundle.namingPatterns = fp.namingPatterns || [];
-      bundle.imports = (fp.imports || []).slice(0, 20);
-      bundle.headerComments = (fp.headerComments || []).slice(0, 10);
-      bundle.readme = fp.readme?.substring(0, 500) || null;
-      break;
-    }
-  }
-
-  return bundle;
-}
-
-/**
- * 构建写作指导手册
- */
-function _buildWritingGuidelines(isZh) {
-  return {
-    language: isZh ? 'zh' : 'en',
-    style: isZh
-      ? '技术文档风格，面向项目新成员。清晰、结构化、有深度。'
-      : 'Technical documentation style targeting new team members. Clear, structured, in-depth.',
-    minChars: 500,
-    format: isZh
-      ? [
-          'Markdown 格式，使用 # 标题、## 分节',
-          '适当使用代码块、表格、Mermaid 图',
-          '引用具体文件路径（相对于项目根目录）',
-          '每篇文章底部包含相关文档链接',
-        ]
-      : [
-          'Markdown format with # titles and ## sections',
-          'Use code blocks, tables, and Mermaid diagrams where appropriate',
-          'Reference specific file paths (relative to project root)',
-          'Include related document links at the bottom of each article',
-        ],
-    navigation: isZh
-      ? '每篇文章末尾添加 "## 相关文档" 节，链接到其他 wiki 页面'
-      : 'Add a "## Related Documents" section at the end, linking to other wiki pages',
-  };
-}