speccore 8.3.181 → 8.3.188

package/dist/core/prompt-builder.js

@@ -58,7 +58,12 @@ const knowledge_graph_1 = require("./knowledge-graph");
 const context_builder_1 = require("./context-builder");
 const spec_paths_1 = require("./spec-paths");
 const context_1 = require("./context");
+const rag_engine_1 = require("./rag-engine");
 const unified_retrieval_1 = require("./unified-retrieval");
+// v8.3.183+: 统一内容供给管线（md 大纲摘要，替代链接全文内联）
+const content_delivery_1 = require("./content-delivery");
+// v8.3.183+: HTML 原型渲染（Playwright 截图 + accessibility tree，替代纯文本）
+const html_prototype_1 = require("./html-prototype");
 // v8.3.122+: execute 时深入读取关联源码
 const code_scanner_1 = require("./code-scanner");
 // v8.3.125+: 同义词扩展，解决中英文/缩写关键词匹配失败
@@ -415,7 +420,12 @@ async function loadExtraSpecs(cwd, taskDir, platform, iteration, options) {
             const budget = getFileBudget(fileName);
             if (content.length > budget.limit) {
                 if (budget.mode === 'error') {
-                    logger_1.logger.error(`[prompt-builder] ${fileName} 超过预算上限 (${content.length} > ${budget.limit})。该文件必须完整，请精简源文件内容。`);
+                    logger_1.logger.error(`[prompt-builder] ${fileName} 超过预算上限 (${content.length} > ${budget.limit})。`);
+                    logger_1.logger.error(`  该文件属于"必须完整"类型，不会被截断。建议精简方式：`);
+                    logger_1.logger.error(`  - 删除过时的注释和示例代码`);
+                    logger_1.logger.error(`  - 将详细说明链接到外部文档`);
+                    logger_1.logger.error(`  - 使用表格代替冗长的列表`);
+                    logger_1.logger.error(`  - 精简后重新执行: speccore execute --resume`);
                     // 不截断，保留完整内容
                 }
                 else {
@@ -537,14 +547,28 @@ async function loadExtraSpecs(cwd, taskDir, platform, iteration, options) {
  * 只加载 ALLOWED_EXTRA_FILES 白名单内的文件，防止上下文污染
  * 白名单外文件将被忽略并输出提示
  */
-const ALLOWED_EXTRA_FILES = new Set([
-    'SCHEMA.md', 'TEST.md', 'REVIEW.md', 'DEPLOY.md', 'MONITOR.md',
-    'RISK.md', 'DEPS.md', 'ERROR_CODES.md', 'COMPONENT_TREE.md',
-    'ROUTES.md', 'STATE.md',
+// v8.3.182+: 白名单分两级（核心 + 条件）
+// 核心白名单：所有任务都需要
+const CORE_EXTRA_FILES = new Set([
+    'CONTEXT.md', // 任务上下文（来源追溯 + 关联任务）
+    'ERROR_CODES.md', // 错误码定义
 ]);
+// 条件白名单：按平台类型加载
+function getPlatformExtraFiles(platform) {
+    if (!platform)
+        return new Set();
+    const p = platform.toLowerCase();
+    if (p.includes('backend') || p.includes('service') || p.includes('api') || p.includes('server')) {
+        return new Set(['SCHEMA.md']);
+    }
+    if (p.includes('web') || p.includes('mobile') || p.includes('h5') || p.includes('frontend') || p.includes('admin')) {
+        return new Set(['COMPONENT_TREE.md', 'ROUTES.md', 'STATE.md']);
+    }
+    return new Set();
+}
 // v8.3.181+: 按文件类型细分预算（必须完整 vs 可以截断）
 const FILE_BUDGETS = {
-    'CONSTITUTION.md': { limit: 4000, mode: 'error' },
+    'CONSTITUTION.md': { limit: 6000, mode: 'error' },
     'REQ.md': { limit: 2000, mode: 'error' },
     'API_CONTRACT.yaml': { limit: 2000, mode: 'error' },
     'TASK.md': { limit: 1500, mode: 'truncate' },
@@ -560,6 +584,9 @@ async function scanUserCustomFiles(cwd, taskDir, platform, seenPaths) {
     const validExts = ['.md', '.yaml', '.yml', '.json', '.html', '.htm'];
     const skipDirs = new Set(['.meta', '.git', 'node_modules', 'tests', 'src', 'dist', 'build']);
     const ignoredFiles = [];
+    // v8.3.182+: 合并核心白名单 + 条件白名单
+    const platformExtras = getPlatformExtraFiles(platform);
+    const allowedFiles = new Set([...CORE_EXTRA_FILES, ...platformExtras]);
     // 1. 扫描 00-specs/ 下白名单内的文件
     const specsDir = (0, path_1.join)(cwd, taskDir, '00-specs');
     try {
@@ -571,7 +598,7 @@ async function scanUserCustomFiles(cwd, taskDir, platform, seenPaths) {
                 const ext = e.name.slice(e.name.lastIndexOf('.'));
                 if (!validExts.includes(ext))
                     continue;
-                if (!ALLOWED_EXTRA_FILES.has(e.name)) {
+                if (!allowedFiles.has(e.name)) {
                     ignoredFiles.push(`00-specs/${e.name}`);
                     continue;
                 }
@@ -594,7 +621,7 @@ async function scanUserCustomFiles(cwd, taskDir, platform, seenPaths) {
                     if (!subE.isDirectory() || subE.name.startsWith('.'))
                         continue;
                     const subtaskDir = (0, path_1.join)(platformBase, subE.name);
-                    await scanDirRecursive(subtaskDir, (0, path_1.join)(platform, subE.name), results, seenPaths, skipDirs, validExts, cwd, taskDir, ignoredFiles);
+                    await scanDirRecursive(subtaskDir, (0, path_1.join)(platform, subE.name), results, seenPaths, skipDirs, validExts, cwd, taskDir, ignoredFiles, allowedFiles);
                 }
             }
         }
@@ -613,7 +640,7 @@ async function scanUserCustomFiles(cwd, taskDir, platform, seenPaths) {
     return results;
 }
 /** 递归扫描目录，收集用户自定义文档（白名单模式） */
-async function scanDirRecursive(dir, relPrefix, results, seenPaths, skipDirs, validExts, cwd, taskDir, ignoredFiles) {
+async function scanDirRecursive(dir, relPrefix, results, seenPaths, skipDirs, validExts, cwd, taskDir, ignoredFiles, allowedFiles) {
     try {
         const entries = await (0, fs_extra_1.readdir)(dir, { withFileTypes: true });
         for (const e of entries) {
@@ -622,13 +649,13 @@ async function scanDirRecursive(dir, relPrefix, results, seenPaths, skipDirs, va
             if (e.isDirectory()) {
                 if (skipDirs.has(e.name) || e.name.startsWith('.'))
                     continue;
-                await scanDirRecursive((0, path_1.join)(dir, e.name), relPath, results, seenPaths, skipDirs, validExts, cwd, taskDir, ignoredFiles);
+                await scanDirRecursive((0, path_1.join)(dir, e.name), relPath, results, seenPaths, skipDirs, validExts, cwd, taskDir, ignoredFiles, allowedFiles);
             }
             else if (e.isFile()) {
                 const ext = e.name.slice(e.name.lastIndexOf('.'));
                 if (!validExts.includes(ext))
                     continue;
-                if (!ALLOWED_EXTRA_FILES.has(e.name)) {
+                if (!allowedFiles.has(e.name)) {
                     ignoredFiles.push(relPath);
                     continue;
                 }
@@ -676,7 +703,12 @@ async function loadAllTaskContext(cwd, taskDir, platform, iteration, graph) {
         const fallbackLimit = budget.limit * 2;
         if (content.length > fallbackLimit) {
             if (budget.mode === 'error') {
-                logger_1.logger.error(`[prompt-builder] ${fileName} 超过兜底预算上限 (${content.length} > ${fallbackLimit})。该文件必须完整，请精简源文件内容。`);
+                logger_1.logger.error(`[prompt-builder] ${fileName} 超过兜底预算上限 (${content.length} > ${fallbackLimit})。`);
+                logger_1.logger.error(`  该文件属于"必须完整"类型，不会被截断。建议精简方式：`);
+                logger_1.logger.error(`  - 删除过时的注释和示例代码`);
+                logger_1.logger.error(`  - 将详细说明链接到外部文档`);
+                logger_1.logger.error(`  - 使用表格代替冗长的列表`);
+                logger_1.logger.error(`  - 精简后重新执行: speccore execute --resume`);
                 // 不截断
             }
             else {
@@ -1059,7 +1091,7 @@ async function buildGlobalTOC(globalDir) {
  * 加载全局上下文（带 TOC 缓存）
  * 策略：必读的 INDEX.md 直接注入 + 其余文件只给目录，AI 自己 Read
  */
-async function loadGlobalContext(cwd, _command, platform) {
+async function loadGlobalContext(cwd, _command, platform, feature) {
     const globalDir = (0, path_1.join)(cwd, '.speccore', 'GLOBAL');
     const ctx = { toc: [] };
     if (!await (0, fs_extra_1.pathExists)(globalDir))
@@ -1074,37 +1106,15 @@ async function loadGlobalContext(cwd, _command, platform) {
     // 支持单文件（单文件模式）+ BUSINESS_RULES/ 目录（推荐，支持按 platform 过滤）
     if (!ctx.keyFileSummaries)
         ctx.keyFileSummaries = [];
-    // 1. 单文件模式：GLOBAL/BUSINESS_RULES.md
-    const legacyPath = (0, path_1.join)(globalDir, 'BUSINESS_RULES.md');
-    if (await (0, fs_extra_1.pathExists)(legacyPath)) {
-        try {
-            const content = await (0, fs_extra_1.readFile)(legacyPath, 'utf-8');
-            ctx.keyFileSummaries.push({ path: 'BUSINESS_RULES.md', content: content.slice(0, 4000) });
-        }
-        catch { /* 忽略 */ }
-    }
-    // 2. 新路径：GLOBAL/BUSINESS_RULES/ 目录，按 platform 过滤加载
-    const businessRulesDir = (0, path_1.join)(globalDir, 'BUSINESS_RULES');
-    if (await (0, fs_extra_1.pathExists)(businessRulesDir)) {
-        try {
-            const files = (await (0, fs_extra_1.readdir)(businessRulesDir))
-                .filter(f => f.endsWith('.md'))
-                .sort();
-            for (const file of files) {
-                // platform 过滤：无 platform 时加载全部；有 platform 时加载 common + 匹配端
-                if (platform) {
-                    const base = file.replace(/\.md$/, '');
-                    const isCommon = base.includes('-common');
-                    const isPlatformMatch = base === platform || base.endsWith(`-${platform}`) || base.includes(`-${platform}-`);
-                    if (!isCommon && !isPlatformMatch)
-                        continue;
-                }
-                const content = await (0, fs_extra_1.readFile)((0, path_1.join)(businessRulesDir, file), 'utf-8');
-                ctx.keyFileSummaries.push({ path: `BUSINESS_RULES/${file}`, content: content.slice(0, 4000) });
-            }
+    // v8.3.184+: 业务规则三层统一加载（全局 BUSINESS_RULES/ + 端级 + 功能级）
+    try {
+        const { loadBusinessRules } = await Promise.resolve().then(() => __importStar(require('./business-rules')));
+        const rules = await loadBusinessRules({ cwd, platform, feature });
+        for (const item of rules) {
+            ctx.keyFileSummaries.push({ path: item.path, content: item.content });
         }
-        catch { /* 忽略 */ }
     }
+    catch { /* 忽略 */ }
     // 3. v8.3.134+: RULES/ 规则文件自动注入（四层架构第二层）
     // 按 frontmatter priority 降序排序，优先加载高优先级规则；总量上限 8000 字符
     const rulesDir = (0, path_1.join)(cwd, '.speccore', 'RULES');
@@ -1604,8 +1614,8 @@ function getInstruction(command, context) {
  */
 // v8.3.160+: 命令 → 默认子 Agent 角色映射
 const DEFAULT_SUBAGENT_MAP = {
-    analyze: 'spec-analyzer',
-    execute: 'spec-executor',
+    analyze: 'requirement-analyzer',
+    execute: 'code-generator',
     split: 'task-decomposer',
     plan: 'schedule-planner',
     change: 'impact-analyst',
@@ -2404,6 +2414,23 @@ function formatPrompt(prompt, maxTokens) {
     logger_1.logger?.info?.(`   🪶 Prompt 已极简模式：仅保留技术栈/API/核心指令`);
     return result;
 }
+// ═══════════════════════════════════════════════════════════
+// v8.3.187+ 通用行为准则（degrade to honesty 体系）
+// 融合业界最佳实践：
+//   - Claude Code 官方系统提示词：Read before write / Minimal change / 不臆造 API
+//   - Anthropic Prompt Library：avoid over-engineering / hallucination-free / 诚实标注
+//   - Karpathy 12 规则：Think before coding / Precise edits / 主动澄清 / 明确失败报告
+// 原则：少而精（5–8 条为宜，过多会导致合规率骤降），每条可操作、正面指令 + 明确禁止结合。
+// ═══════════════════════════════════════════════════════════
+const UNIVERSAL_BEHAVIOR_RULES = [
+    '- **Spec 优先（最高优先级）**：代码、口头要求与 Spec（REQ/TECH/API_CONTRACT）冲突时，一律以 Spec 为准，并明确指出冲突点与差异。',
+    '- **先读后写**：动手改代码前，先读相关 Spec 与现有实现；禁止凭空臆造不存在的 API、字段、路径或库方法，不确定就查，查不到就如实说明。',
+    '- **不迎合用户**：优先保证技术正确与真实，而非附和用户；需求有缺陷、自相矛盾或不合理处，直接指出并给建议，不为顺从而照做。',
+    '- **最小改动**：只做当前任务要求或明确必要的改动；不顺手重构无关代码、不添加超出需求的「改进」、不过度设计；无用代码直接删除，不留兼容性 hack。',
+    '- **主动澄清**：需求或 Spec 有歧义、缺关键信息时，先提出澄清问题或明确列出假设，不擅自猜测后闷头实现。',
+    '- **降级到诚实**：区分「事实 / 推断 / 猜测」；不确定的信息标注置信度，不编造；做不到或没把握的方案，说明局限，不给自信的错误答案。',
+    '- **破坏性操作先确认**：删除、覆盖、迁移文件或改动公共 API 等影响面大/不可逆的操作，先说明影响并确认后再执行。',
+];
 /** 实际构建 prompt 文本（无裁剪逻辑） */
 function buildPromptText(prompt) {
     // v8.3.160+: analyze 命令使用 buildMultiDocPrompt 生成的原始 Prompt，直接返回
@@ -2413,6 +2440,11 @@ function buildPromptText(prompt) {
     const lines = [];
     lines.push('[SPECCORE_PROMPT]');
     lines.push('');
+    // v8.3.184+ 通用行为准则（v8.3.187+ 扩展并抽取为 UNIVERSAL_BEHAVIOR_RULES 常量）
+    lines.push('## 通用行为准则');
+    for (const rule of UNIVERSAL_BEHAVIOR_RULES)
+        lines.push(rule);
+    lines.push('');
     // v8.3.160+: 注入子 Agent 角色定义和上下文裁剪策略
     if (prompt.agentContext) {
         lines.push(prompt.agentContext);
@@ -2774,32 +2806,22 @@ async function expandMarkdownLinks(content, baseDir, seenPaths, maxDepth = 3, cu
             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 原型文件保留完整内容，不再提取纯文本
+            // v8.3.183+: 统一用结构化摘要替代全文内联
+            //   - html → Playwright accessibility tree（页面结构），失败降级 extractHtmlText
+            //   - md → 标题大纲
+            let rawSummary;
             if (isHtml) {
-                // 保留原始 HTML（包含 CSS/JS/结构），让 AI 完整解析原型
+                const proto = await (0, html_prototype_1.renderHtmlPrototype)(resolved);
+                rawSummary = proto?.accessibilityTree || (0, rag_engine_1.extractHtmlText)(linkContent);
             }
-            const isTruncated = isHtml ? linkContent.length > htmlMaxChars : linkContent.length > maxChars;
-            if (isTruncated) {
-                linkContent = linkContent.slice(0, maxChars) +
-                    `\n\n---\n📄 **文件内容已截断**（宿主 AI 请务必打开查看完整内容）：\n` +
-                    `- 文件: ${resolved}\n` +
-                    `- 大小: ${(await (0, fs_extra_1.stat)(resolved)).size} 字节\n` +
-                    `> ⚠️ **请打开此文件查看完整内容**。此文件与需求理解高度相关，CLI 因长度限制已截断，需要你直接打开文件查看。`;
+            else {
+                rawSummary = (0, content_delivery_1.extractMdOutline)(linkContent);
             }
-            expansions.push(`\n\n<!-- 展开链接: ${link.path} -->\n**[链接展开] ${link.text}** (${link.path}):\n\n${linkContent}`);
+            const summary = rawSummary.length > maxChars
+                ? rawSummary.slice(0, maxChars) + '\n…(摘要截断)'
+                : rawSummary;
+            expansions.push(`\n\n**[链接] ${link.text}** (${link.path}):\n${summary}\n> 全文见 \`${resolved}\``);
         }
         catch { /* 忽略读取失败的链接文件 */ }
     }
@@ -2873,17 +2895,21 @@ async function inlineMarkdownImages(content, baseDir, seenPaths, visionConfig, m
             }
         }
         else {
-            // 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`);
+            // v8.3.183+: 无视觉模型时，用 alt 语义兜底（硬保证有描述），"请打开"降为补充
+            const altDesc = img.alt && img.alt.trim() ? img.alt.trim() : '';
+            if (altDesc) {
+                inlines.push(`\n\n---\n🖼️ **图片** ${altDesc}：\`${resolved}\`\n> 图片细节需宿主 AI 打开查看（CLI 无视觉模型，仅能提供 alt 语义）`);
+            }
+            else {
+                inlines.push(`\n\n---\n🖼️ **图片文件**（无 alt 描述，宿主 AI 请打开查看）：\n- ${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`);
+                    }
                 }
+                catch { /* ignore */ }
             }
-            catch { /* ignore */ }
-            inlines.push(`> ⚠️ **请打开此图片文件查看内容**。此图片与需求理解高度相关，CLI 无法自动解析图片内容，需要你直接打开文件查看。`);
         }
     }
     // v8.3.125+: 在内容末尾附加外链图片清单，提示宿主 AI 按需查看