speccore 8.3.137 → 8.3.147

package/dist/core/prompt-builder.js

@@ -321,7 +321,7 @@ async function loadExtraSpecs(cwd, taskDir, platform, iteration, options) {
             // v8.3.93+: Markdown 链接自动展开 + 图片提取
             if (fullPath.endsWith('.md')) {
                 content = await processMarkdownContent(content, fullPath, seenPaths, visionConfig, {
-                    maxLinkDepth: 2, maxLinkChars: 1200, maxSvgChars: 1500,
+                    maxLinkDepth: 3, maxLinkChars: 2000, maxSvgChars: 1500,
                 });
             }
             // 跳过空文件或纯占位符文件
@@ -361,7 +361,7 @@ async function loadExtraSpecs(cwd, taskDir, platform, iteration, options) {
             // v8.3.93+: Markdown 链接自动展开 + 图片提取
             if (fullPath.endsWith('.md')) {
                 content = await processMarkdownContent(content, fullPath, seenPaths, visionConfig, {
-                    maxLinkDepth: 2, maxLinkChars: 1200, maxSvgChars: 1500,
+                    maxLinkDepth: 3, maxLinkChars: 2000, maxSvgChars: 1500,
                 });
             }
             if (content.trim().length <= 50 || content.trim().match(/^#+\s*待填充|^<!--\s*AI-FILL\s*-->$/m)) {
@@ -536,7 +536,7 @@ async function loadAllTaskContext(cwd, taskDir, platform, iteration, graph) {
         // v8.3.93+: Markdown 链接自动展开 + 图片提取
         if (fullPath.endsWith('.md')) {
             content = await processMarkdownContent(content, fullPath, seen, visionConfig, {
-                maxLinkDepth: 2, maxLinkChars: 1500, maxSvgChars: 2000,
+                maxLinkDepth: 3, maxLinkChars: 2000, maxSvgChars: 2000,
             });
         }
         if (content.trim().length <= 50 || content.trim().match(/^#+\s*待填充|^<!--\s*AI-FILL\s*-->$/m))
@@ -741,13 +741,17 @@ function extractSummary(content) {
 }
 /**
  * 从路径和内容推断涉及的端
+ * v8.3.144+: 使用项目实际端名（工程标识），不再硬编码 backend/frontend 等
  */
-function extractPlatforms(path, content) {
+function extractPlatforms(path, content, projectPlatforms) {
     const platforms = new Set();
-    const knownPlatforms = ['backend', 'admin', 'h5', 'miniapp', 'app', 'web', 'ios', 'android'];
+    // 优先使用项目 CONSTITUTION.md 中定义的工程标识，fallback 到常见端名
+    const knownPlatforms = projectPlatforms?.length
+        ? projectPlatforms
+        : ['backend', 'admin', 'h5', 'miniapp', 'app', 'web', 'ios', 'android'];
     // 从路径推断
     for (const p of knownPlatforms) {
-        if (path.toLowerCase().includes(p)) {
+        if (path.toLowerCase().includes(p.toLowerCase())) {
             platforms.add(p);
         }
     }
@@ -759,7 +763,7 @@ function extractPlatforms(path, content) {
     // 从内容中扫描（前 2000 字）
     const head = content.slice(0, 2000).toLowerCase();
     for (const p of knownPlatforms) {
-        if (head.includes(p)) {
+        if (head.includes(p.toLowerCase())) {
             platforms.add(p);
         }
     }
@@ -796,15 +800,16 @@ function extractTags(headings) {
 }
 /**
  * 构建单个 TOC 条目（含摘要/端/行数/标签）
+ * v8.3.144+: 异步化，支持传入项目实际端名（工程标识）
  */
-function buildTOCEntry(path, description, content, maxSections) {
+async function buildTOCEntry(path, description, content, maxSections, projectPlatforms) {
     const sections = extractHeadings(content);
     return {
         path,
         description,
         sections: maxSections ? sections.slice(0, maxSections) : sections,
         summary: extractSummary(content) || undefined,
-        platforms: extractPlatforms(path, content) || undefined,
+        platforms: extractPlatforms(path, content, projectPlatforms) || undefined,
         lineCount: content.split(/\r?\n/).length,
         tags: extractTags(sections) || undefined,
     };
@@ -816,13 +821,15 @@ function buildTOCEntry(path, description, content, maxSections) {
 async function buildGlobalTOC(globalDir) {
     const toc = [];
     const speccoreDir = (0, path_1.join)(globalDir, '..'); // .speccore/
+    // v8.3.144+: 读取项目实际端名（工程标识），不再硬编码 backend/frontend
+    const projectPlatforms = await (0, spec_paths_1.parsePlatformList)();
     // 1. synthesis/ 下的综合文档
     const synthesisDir = (0, path_1.join)(globalDir, 'synthesis');
     if (await (0, fs_extra_1.pathExists)(synthesisDir)) {
         const files = await (0, fs_extra_1.readdir)(synthesisDir);
         for (const f of files.filter(f => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f))) {
             const content = await (0, fs_extra_1.readFile)((0, path_1.join)(synthesisDir, f), 'utf-8');
-            toc.push(buildTOCEntry(`synthesis/${f}`, FILE_DESC[f] || f.replace('.md', ''), content));
+            toc.push(await buildTOCEntry(`synthesis/${f}`, FILE_DESC[f] || f.replace('.md', ''), content, undefined, projectPlatforms));
         }
     }
     // 2. platforms/ 下各端文档
@@ -836,7 +843,7 @@ async function buildGlobalTOC(globalDir) {
             const subFiles = await (0, fs_extra_1.readdir)((0, path_1.join)(platformsDir, platformName));
             for (const f of subFiles.filter(f => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f))) {
                 const content = await (0, fs_extra_1.readFile)((0, path_1.join)(platformsDir, platformName, f), 'utf-8');
-                toc.push(buildTOCEntry(`platforms/${platformName}/${f}`, `${platformName} 端 — ${f.replace('.md', '')}`, content));
+                toc.push(await buildTOCEntry(`platforms/${platformName}/${f}`, `${platformName} 端 — ${f.replace('.md', '')}`, content, undefined, projectPlatforms));
             }
         }
     }
@@ -851,7 +858,7 @@ async function buildGlobalTOC(globalDir) {
             const subFiles = await (0, fs_extra_1.readdir)((0, path_1.join)(projectsDir, projectName));
             for (const f of subFiles.filter(f => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f))) {
                 const content = await (0, fs_extra_1.readFile)((0, path_1.join)(projectsDir, projectName, f), 'utf-8');
-                toc.push(buildTOCEntry(`PROJECTS/${projectName}/${f}`, `${projectName} — ${f.replace('.md', '')}`, content));
+                toc.push(await buildTOCEntry(`PROJECTS/${projectName}/${f}`, `${projectName} — ${f.replace('.md', '')}`, content, undefined, projectPlatforms));
             }
         }
     }
@@ -865,7 +872,7 @@ async function buildGlobalTOC(globalDir) {
         return true;
     })) {
         const content = await (0, fs_extra_1.readFile)((0, path_1.join)(globalDir, f), 'utf-8');
-        toc.push(buildTOCEntry(`GLOBAL:${f}`, FILE_DESC[f] || f.replace('.md', ''), content));
+        toc.push(await buildTOCEntry(`GLOBAL:${f}`, FILE_DESC[f] || f.replace('.md', ''), content, undefined, projectPlatforms));
     }
     // 5. PATTERNS/ 可复用模式（含 TEMPLATES/ 写作模板）
     const patternsDir = (0, path_1.join)(speccoreDir, 'PATTERNS');
@@ -882,7 +889,7 @@ async function buildGlobalTOC(globalDir) {
                     const label = isTemplate
                         ? entry.name.replace('-template.md', '').toUpperCase() + ' 写作模板'
                         : (prefix ? prefix.slice(0, -1).replace(/\//g, ' › ') + ' › ' : '') + entry.name.replace('.md', '');
-                    toc.push(buildTOCEntry(`PATTERNS:${prefix}${entry.name}`, label, content, isTemplate ? 6 : 4));
+                    toc.push(await buildTOCEntry(`PATTERNS:${prefix}${entry.name}`, label, content, isTemplate ? 6 : 4, projectPlatforms));
                 }
             }
         };
@@ -894,7 +901,7 @@ async function buildGlobalTOC(globalDir) {
         const files = await (0, fs_extra_1.readdir)(rulesDir);
         for (const f of files.filter(f => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f))) {
             const content = await (0, fs_extra_1.readFile)((0, path_1.join)(rulesDir, f), 'utf-8');
-            toc.push(buildTOCEntry(`RULES:${f}`, RULES_DESC[f] || f.replace('.md', ''), content));
+            toc.push(await buildTOCEntry(`RULES:${f}`, RULES_DESC[f] || f.replace('.md', ''), content, undefined, projectPlatforms));
         }
     }
     // 7. SKILLS/ 技术能力库（v8.3.134+ 四层架构：TOC 可见性）
@@ -903,7 +910,7 @@ async function buildGlobalTOC(globalDir) {
         const files = await (0, fs_extra_1.readdir)(skillsDir);
         for (const f of files.filter(f => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f))) {
             const content = await (0, fs_extra_1.readFile)((0, path_1.join)(skillsDir, f), 'utf-8');
-            toc.push(buildTOCEntry(`SKILLS:${f}`, SKILLS_DESC[f] || f.replace('.md', ''), content));
+            toc.push(await buildTOCEntry(`SKILLS:${f}`, SKILLS_DESC[f] || f.replace('.md', ''), content, undefined, projectPlatforms));
         }
     }
     return toc;
@@ -2403,7 +2410,9 @@ function outputNeedsInfo(req) {
 // ═══════════════════════════════════════════════════════════
 // Markdown 链接自动展开 + 图片提取（v8.3.93+）
 // ═══════════════════════════════════════════════════════════
-/** 提取 Markdown 文本链接 [text](path)，排除图片链接 */
+/** 提取 Markdown 文本链接 [text](path)，排除图片链接
+ * v8.3.125+: 不再跳过外部链接 — 由调用方决定如何处理（收集到外链清单）
+ */
 function extractMarkdownLinks(content) {
     const links = [];
     const regex = /\[([^\]]+)\]\(([^)]+)\)/g;
@@ -2414,8 +2423,10 @@ function extractMarkdownLinks(content) {
         // 跳过图片链接 ![alt](path) — 检查前一个字符
         if (match.index > 0 && content.charAt(match.index - 1) === '!')
             continue;
-        // 跳过外部链接、锚点、协议链接
-        if (/^(https?:|mailto:|ftp:|#|javascript:)/i.test(path))
+        // 跳过锚点和危险协议（保留 http/https/ftp 外链，由调用方处理）
+        if (/^(mailto:|javascript:)/i.test(path))
+            continue;
+        if (path.startsWith('#'))
             continue;
         links.push({ text, path });
     }
@@ -2441,19 +2452,22 @@ function resolveLinkPath(baseDir, linkPath) {
         return linkPath;
     return (0, path_1.join)(baseDir, linkPath);
 }
-/** 递归展开 Markdown 链接指向的文件内容（防循环，限深度） */
-async function expandMarkdownLinks(content, baseDir, seenPaths, maxDepth = 2, currentDepth = 0, maxChars = 1500) {
+/** 递归展开 Markdown 链接指向的文件内容（防循环，限深度）
+ * v8.3.138+: HTML 文件独立阈值（8KB），避免原型文件被过度截断
+ * maxDepth 默认 3：支持文档 A → B → C 三级展开
+ */
+async function expandMarkdownLinks(content, baseDir, seenPaths, maxDepth = 3, currentDepth = 0, maxChars = 1500) {
     if (currentDepth >= maxDepth)
         return content;
     const links = extractMarkdownLinks(content);
     if (links.length === 0)
         return content;
     const expansions = [];
-    // v8.3.125+: 收集外链资源，供宿主 AI 按需读取
-    const externalLinks = [];
+    // v8.3.125+: 收集外链资源，供宿主 AI 按需读取（用 Map 按 URL 去重）
+    const externalLinks = new Map(); // path -> text
     for (const link of links) {
         if (isExternalLink(link.path)) {
-            externalLinks.push(link);
+            externalLinks.set(link.path, link.text);
             continue;
         }
         const resolved = resolveLinkPath(baseDir, link.path);
@@ -2467,15 +2481,32 @@ async function expandMarkdownLinks(content, baseDir, seenPaths, maxDepth = 2, cu
             if (!st.isFile())
                 continue;
             let linkContent = await (0, fs_extra_1.readFile)(resolved, 'utf-8');
+            if (linkContent.trim().length <= 30)
+                continue;
+            // v8.3.138+: HTML/原型文件使用独立阈值（8KB），避免原型文件被过度截断。
+            // 超过阈值不截断 inline（避免结构残缺误导 AI），而是提示宿主 AI 直接打开查看。
+            const isHtml = resolved.endsWith('.html') || resolved.endsWith('.htm');
+            const htmlMaxChars = 8192; // 8KB，足够覆盖大多数 HTML 原型
+            const isLarge = isHtml ? linkContent.length > htmlMaxChars : linkContent.length > maxChars;
+            if (isHtml && isLarge) {
+                expansions.push(`\n\n---\n📄 **HTML 原型文件**（内容过大未展开，宿主 AI 请务必直接打开查看）：\n` +
+                    `- 文件: ${resolved}\n` +
+                    `- 大小: ${(linkContent.length / 1024).toFixed(1)} KB\n` +
+                    `- 描述: ${link.text || '无描述'}\n` +
+                    `> ⚠️ **请打开此 HTML 文件查看完整内容**。此为页面原型/设计稿，与需求理解高度相关，CLI 因文件过大未完整展开，需要你直接打开文件查看。`);
+                continue;
+            }
             // v8.3.122+: HTML 原型文件保留完整内容，不再提取纯文本
-            if (resolved.endsWith('.html') || resolved.endsWith('.htm')) {
+            if (isHtml) {
                 // 保留原始 HTML（包含 CSS/JS/结构），让 AI 完整解析原型
             }
-            if (linkContent.trim().length <= 30)
-                continue;
-            const isTruncated = linkContent.length > maxChars;
+            const isTruncated = isHtml ? linkContent.length > htmlMaxChars : linkContent.length > maxChars;
             if (isTruncated) {
-                linkContent = linkContent.slice(0, maxChars) + `\n\n> ... (已截断，完整内容请 Read: ${resolved})`;
+                linkContent = linkContent.slice(0, maxChars) +
+                    `\n\n---\n📄 **文件内容已截断**（宿主 AI 请务必打开查看完整内容）：\n` +
+                    `- 文件: ${resolved}\n` +
+                    `- 大小: ${(await (0, fs_extra_1.stat)(resolved)).size} 字节\n` +
+                    `> ⚠️ **请打开此文件查看完整内容**。此文件与需求理解高度相关，CLI 因长度限制已截断，需要你直接打开文件查看。`;
             }
             expansions.push(`\n\n<!-- 展开链接: ${link.path} -->\n**[链接展开] ${link.text}** (${link.path}):\n\n${linkContent}`);
         }
@@ -2483,11 +2514,11 @@ async function expandMarkdownLinks(content, baseDir, seenPaths, maxDepth = 2, cu
     }
     let expanded = content + expansions.join('');
     // v8.3.125+: 在内容末尾附加外链资源清单，提示宿主 AI 按需读取
-    if (externalLinks.length > 0) {
+    if (externalLinks.size > 0) {
         const externalSection = [
             '\n\n---',
-            '📎 **外链资源清单**（CLI 无法直接获取内容，宿主 AI 可按需访问）：',
-            ...externalLinks.map(l => `- [${l.text || '链接'}](${l.path})`),
+            '📎 **外链资源清单**（CLI 无法直接获取内容，宿主 AI 请务必按需访问）：',
+            ...Array.from(externalLinks.entries()).map(([path, text]) => `- [${text || '链接'}](${path})`),
         ].join('\n');
         expanded += externalSection;
     }
@@ -2505,11 +2536,11 @@ async function inlineMarkdownImages(content, baseDir, seenPaths, visionConfig, m
     const inlines = [];
     let visionCallCount = 0;
     const maxVisionCalls = visionConfig?.maxImagesPerPrompt ?? 10;
-    // v8.3.125+: 收集外链图片，供宿主 AI 按需查看
-    const externalImages = [];
+    // v8.3.125+: 收集外链图片，供宿主 AI 按需查看（用 Map 按 URL 去重）
+    const externalImages = new Map(); // path -> alt
     for (const img of images) {
         if (isExternalLink(img.path)) {
-            externalImages.push(img);
+            externalImages.set(img.path, img.alt);
             inlines.push(`\n<!-- 外链图片: ${img.alt || '无描述'} | URL: ${img.path} -->`);
             continue;
         }
@@ -2526,7 +2557,7 @@ async function inlineMarkdownImages(content, baseDir, seenPaths, visionConfig, m
                         inlines.push(`\n<!-- SVG 图片: ${img.path} -->\n${svgContent}`);
                     }
                     else {
-                        inlines.push(`\n<!-- SVG 图片: ${img.path} (内容过长已省略，大小: ${svgContent.length} 字符) -->`);
+                        inlines.push(`\n\n---\n🖼️ **SVG 图片文件**（内容过长已省略，宿主 AI 请务必直接打开查看）：\n- ${img.path}\n- 大小: ${svgContent.length} 字符（超出 ${maxSvgChars} 字符限制）\n> ⚠️ **请打开此 SVG 文件查看完整内容**。此 SVG 与需求理解高度相关，因内容过长被省略，需要你直接打开文件查看。`);
                     }
                 }
             }
@@ -2541,31 +2572,35 @@ async function inlineMarkdownImages(content, baseDir, seenPaths, visionConfig, m
                     inlines.push(`\n<!-- 图片描述 (视觉模型: ${visionConfig.provider}): ${img.path} -->\n**[图片内容]** ${img.alt || '无描述'}\n\n${result.description}`);
                 }
                 else {
-                    inlines.push(`\n<!-- 图片: ${img.alt || '无描述'} | 路径: ${img.path} | 描述失败: ${result.error} -->`);
+                    // v8.3.138+: Vision 描述失败时，明确提示宿主 AI 打开文件查看
+                    inlines.push(`\n\n---\n🖼️ **图片文件**（视觉模型描述失败，宿主 AI 请务必直接打开查看）：\n- ${img.alt || '无描述'}: ${resolved}\n> ⚠️ **请打开此图片文件查看内容**。此图片与需求理解高度相关，视觉模型未能成功描述，需要你直接打开文件查看。`);
                 }
             }
             catch (e) {
-                inlines.push(`\n<!-- 图片: ${img.alt || '无描述'} | 路径: ${img.path} | 描述失败: ${e.message || e} -->`);
+                // v8.3.138+: 描述异常时，同样提示宿主 AI 打开查看
+                inlines.push(`\n\n---\n🖼️ **图片文件**（视觉模型异常，宿主 AI 请务必直接打开查看）：\n- ${img.alt || '无描述'}: ${resolved}\n> ⚠️ **请打开此图片文件查看内容**。此图片与需求理解高度相关，视觉模型异常未能描述，需要你直接打开文件查看。`);
             }
         }
         else {
-            // 其他图片（PNG/JPG/GIF/WebP 等）：提取 alt + 路径 + 文件大小信息
-            inlines.push(`\n<!-- 图片: ${img.alt || '无描述'} | 路径: ${img.path} -->`);
+            // v8.3.138+: 无视觉模型时，明确提示宿主 AI 打开图片查看（不要用 HTML 注释，AI 会忽略）
+            inlines.push(`\n\n---\n🖼️ **图片文件**（CLI 无法解析图片内容，宿主 AI 请务必直接打开查看）：`);
+            inlines.push(`- ${img.alt || '无描述'}: ${resolved}`);
             try {
                 if (await (0, fs_extra_1.pathExists)(resolved)) {
                     const st = await (0, fs_extra_1.stat)(resolved);
-                    inlines.push(`<!-- 图片大小: ${(st.size / 1024).toFixed(1)} KB | 完整路径: ${resolved} -->`);
+                    inlines.push(`- 文件大小: ${(st.size / 1024).toFixed(1)} KB`);
                 }
             }
             catch { /* ignore */ }
+            inlines.push(`> ⚠️ **请打开此图片文件查看内容**。此图片与需求理解高度相关，CLI 无法自动解析图片内容，需要你直接打开文件查看。`);
         }
     }
     // v8.3.125+: 在内容末尾附加外链图片清单，提示宿主 AI 按需查看
-    if (externalImages.length > 0) {
+    if (externalImages.size > 0) {
         inlines.push([
             '\n\n---',
-            '🖼️ **外链图片清单**（CLI 无法直接获取内容，宿主 AI 可按需查看）：',
-            ...externalImages.map(img => `- ${img.alt || '无描述'}: ${img.path}`),
+            '🖼️ **外链图片清单**（CLI 无法直接获取内容，宿主 AI 请务必按需查看）：',
+            ...Array.from(externalImages.entries()).map(([path, alt]) => `- ${alt || '无描述'}: ${path}`),
         ].join('\n'));
     }
     return content + inlines.join('');