speccore 8.3.246 → 8.3.248

package/dist/commands/analyze.js

@@ -67,6 +67,7 @@ const feature_source_1 = require("../core/feature-source");
 const analyze_engine_1 = require("../core/analyze-engine");
 const fs_extra_2 = require("fs-extra");
 const prompt_builder_1 = require("../core/prompt-builder");
+const spec_paths_1 = require("../core/spec-paths");
 // v8.3.160+: 子 Agent 适配层（analyze 自定义 Prompt 中手动注入）
 // v8.3.169+: 新增 dispatchSubagent 支持 Qoder SDK 直接调度
 const agent_adapter_1 = require("../core/agent-adapter");
@@ -74,7 +75,7 @@ const questions_1 = require("../core/questions");
 const platform_registry_1 = require("../core/platform-registry");
 const index_guard_1 = require("../core/index-guard");
 const unified_config_1 = require("../core/unified-config");
-const spec_paths_1 = require("../core/spec-paths");
+const spec_paths_2 = require("../core/spec-paths");
 const spec_skeleton_1 = require("../core/spec-skeleton");
 const unified_retrieval_1 = require("../core/unified-retrieval");
 const unit_context_assembler_1 = require("../core/unit-context-assembler");
@@ -260,7 +261,7 @@ async function applyDocContent(content, iter) {
     let applied = 0;
     // v8.3.237+: 与 --apply 主通道一致——有功能模块的项目才拦截（内容类归 {feature}/overview/，
     // 全局 overview/REQUIREMENT.md 由 split 聚合），无功能模块的老项目放行
-    const featureCount = (await (0, spec_paths_1.parseFeatureList)(iterDir)).length;
+    const featureCount = (await (0, spec_paths_2.parseFeatureList)(iterDir)).length;
     for (const [filename, docContent] of Object.entries(docs)) {
         if (typeof docContent !== 'string' || !docContent.trim())
             continue;
@@ -814,7 +815,7 @@ async function analyzeCommand(options) {
     }
     // v8.3.16+: 模糊匹配端名，支持多段指定（逗号分隔）
     if (options.platform) {
-        const allPlatforms = await (0, spec_paths_1.parsePlatformList)();
+        const allPlatforms = await (0, spec_paths_2.parsePlatformList)();
         const inputPlatforms = options.platform.split(',').map(p => p.trim()).filter(Boolean);
         const resolvedPlatforms = [];
         for (const input of inputPlatforms) {
@@ -923,7 +924,7 @@ async function analyzeCommand(options) {
                 }
                 // 新路径两级澄清产物（{feature}/overview/CLARIFY.md）与切分目录一一对应，优先级最高
                 const clarifyUnitDocs = await collectUnitClarifyDocs(specDir);
-                const featureUnits = await (0, spec_paths_1.parseFeatureList)(iterDir);
+                const featureUnits = await (0, spec_paths_2.parseFeatureList)(iterDir);
                 if (featureUnits.length > 0 && (clarifyUnitDocs.length > 0 || unitLevel.length > 0)) {
                     // 有切分锚点：按单元优先读入一一对应的澄清文档，跳过冗余的文档级
                     const legacyUnitName = (f) => (0, path_1.basename)(f).replace(/^unit-/, '').replace(/\.md$/, '');
@@ -953,7 +954,7 @@ async function analyzeCommand(options) {
             // features/ 单元名决定 020-specs 骨架，黄金需求文件名决定内容来源，
             // 两者不对齐时 taskify 无法把澄清内容挂接到对应单元
             try {
-                const featureUnits = await (0, spec_paths_1.parseFeatureList)(iterDir);
+                const featureUnits = await (0, spec_paths_2.parseFeatureList)(iterDir);
                 if (featureUnits.length > 0) {
                     const goldenBases = (await (0, fs_extra_2.readdir)(goldenReqDir))
                         .filter((f) => f.endsWith('.md') && !(0, task_utils_1.isTimestampBackup)(f))
@@ -1116,7 +1117,7 @@ async function analyzeCommand(options) {
                 // v8.0.0+: 骨架优先架构 — CLI 预创建所有文件，AI 只覆盖内容
                 const iterDirForSkeleton = await (0, context_1.getIterationDir)(iterForDirs);
                 const specDir = (0, path_1.join)(iterDirForSkeleton, '020-specs');
-                let platforms = await (0, spec_paths_1.parsePlatformList)();
+                let platforms = await (0, spec_paths_2.parsePlatformList)();
                 const iterName = iterForDirs;
                 // v8.3.16+: 如果指定了 --platform，只创建指定端的骨架
                 if (options.platform) {
@@ -1133,7 +1134,7 @@ async function analyzeCommand(options) {
                 // v8.3.171+: 删除 sanitize 自动调用（保留为 speccore migrate 工具）
                 // v8.3.21+: 按需求文档名组织（020-specs/{需求名}/）
                 const phase = options.phase;
-                const features = await (0, spec_paths_1.parseFeatureList)(iterDirForSkeleton);
+                const features = await (0, spec_paths_2.parseFeatureList)(iterDirForSkeleton);
                 let manifest;
                 if (features.length > 0) {
                     manifest = (0, spec_skeleton_1.computeFeatureBasedAnalyzeManifest)(features, platforms, phase, iterName);
@@ -1526,10 +1527,10 @@ ${singlePrompt}`);
                 if (stepId === 'phase1-prompt') {
                     // 有功能模块的项目只生成全局索引；老项目生成全部全局文档。
                     // CLARIFY.md 由 clarify 阶段产出，不在本步骤检查范围（skip clarify 时不会卡住）。
-                    const featureCount = (await (0, spec_paths_1.parseFeatureList)(iterDirForCheck)).length;
+                    const featureCount = (await (0, spec_paths_2.parseFeatureList)(iterDirForCheck)).length;
                     checkDocs = (featureCount > 0 ? spec_skeleton_1.PHASE1_INDEX_DOC_NAMES : spec_skeleton_1.PHASE1_DOC_NAMES)
                         .filter((n) => n !== 'CLARIFY.md');
-                    baseRel = spec_paths_1.GLOBAL_SPECS_DIR;
+                    baseRel = spec_paths_2.GLOBAL_SPECS_DIR;
                 }
                 else {
                     const m = stepId.match(/^feature-(.+)-prompt$/);
@@ -1803,7 +1804,7 @@ ${singlePrompt}`);
                     // v8.3.237+: 拦截条件化为「有功能模块的项目」——内容类归 {feature}/overview/，
                     // 全局 overview/REQUIREMENT.md 由 split 阶段从功能模块聚合生成，AI 不应直接写。
                     // 无功能模块的老项目放行（内容类唯一容器就是 overview/）。
-                    const featureCount = iterDir ? (await (0, spec_paths_1.parseFeatureList)(iterDir)).length : 0;
+                    const featureCount = iterDir ? (await (0, spec_paths_2.parseFeatureList)(iterDir)).length : 0;
                     if (featureCount > 0) {
                         for (const filename of Object.keys(docs)) {
                             if (filename === 'overview/REQUIREMENT.md' || filename === 'REQUIREMENT.md') {
@@ -1843,7 +1844,7 @@ ${singlePrompt}`);
                     // 全局级：写入 .speccore/GLOBAL/（与 platforms/ 同级，非迭代目录）
                     const globalBaseDir = (0, path_1.join)(_projectRoot, '.speccore', 'GLOBAL');
                     await (0, fs_extra_1.ensureDir)(globalBaseDir);
-                    const globalSet = new Set(spec_paths_1.GLOBAL_SPEC_FILES);
+                    const globalSet = new Set(spec_paths_2.GLOBAL_SPEC_FILES);
                     for (const [filename, content] of Object.entries(docs)) {
                         // PATTERNS/ 文件特殊处理 → 写入 .speccore/PATTERNS/
                         if (filename.startsWith('PATTERNS/')) {
@@ -1943,10 +1944,10 @@ ${singlePrompt}`);
                     // v6.69.2+: 增加端名白名单校验，防止 AI 创建非法目录
                     const specDir = (0, path_1.join)(iterDir, '020-specs');
                     await (0, fs_extra_1.ensureDir)(specDir);
-                    const globalSet = new Set(spec_paths_1.GLOBAL_SPEC_FILES);
-                    const validPlatforms = new Set([spec_paths_1.GLOBAL_SPECS_DIR, ...(await (0, spec_paths_1.parsePlatformList)())]);
+                    const globalSet = new Set(spec_paths_2.GLOBAL_SPEC_FILES);
+                    const validPlatforms = new Set([spec_paths_2.GLOBAL_SPECS_DIR, ...(await (0, spec_paths_2.parsePlatformList)())]);
                     // v8.3.21+: 按需求文档名组织
-                    const features = await (0, spec_paths_1.parseFeatureList)(iterDir);
+                    const features = await (0, spec_paths_2.parseFeatureList)(iterDir);
                     if (features.length > 0) {
                         logger_1.logger.info(`   📂 检测到 ${features.length} 个功能模块，按需求文档名路由文档`);
                     }
@@ -2002,16 +2003,16 @@ ${singlePrompt}`);
                         }
                         // v7.4.0+: 文件名归一化——剥离 AI 可能携带的 overview/ 前缀，防止嵌套目录
                         let cleanFilename = filename;
-                        if (cleanFilename.startsWith(`${spec_paths_1.GLOBAL_SPECS_DIR}/`)) {
-                            cleanFilename = cleanFilename.slice(`${spec_paths_1.GLOBAL_SPECS_DIR}/`.length);
+                        if (cleanFilename.startsWith(`${spec_paths_2.GLOBAL_SPECS_DIR}/`)) {
+                            cleanFilename = cleanFilename.slice(`${spec_paths_2.GLOBAL_SPECS_DIR}/`.length);
                         }
                         // v8.3.21+: 按需求文档名组织的目录结构路由
                         if (cleanFilename.includes('/')) {
                             const parts = cleanFilename.split('/');
                             const firstPart = parts[0];
                             // 全局文档：overview/xxx → 写入 020-specs/overview/
-                            if (firstPart === spec_paths_1.GLOBAL_SPECS_DIR) {
-                                const targetDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
+                            if (firstPart === spec_paths_2.GLOBAL_SPECS_DIR) {
+                                const targetDir = (0, path_1.join)(specDir, spec_paths_2.GLOBAL_SPECS_DIR);
                                 await (0, fs_extra_1.ensureDir)(targetDir);
                                 const fp = (0, path_1.join)(targetDir, parts.slice(1).join('/'));
                                 if (!options.merge && !(await (0, task_utils_1.shouldOverwrite)(fp, !!options.interactive))) {
@@ -2075,7 +2076,7 @@ ${singlePrompt}`);
                         // 如果 AI 输出 {端}/{文件}，尝试回退到功能模块路由
                         let targetDir;
                         if (globalSet.has(cleanFilename)) {
-                            targetDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
+                            targetDir = (0, path_1.join)(specDir, spec_paths_2.GLOBAL_SPECS_DIR);
                         }
                         else if (platformDir && validPlatforms.has(platformDir)) {
                             // 检查是否应归入功能模块（骨架文件已按功能模块创建）
@@ -2083,7 +2084,7 @@ ${singlePrompt}`);
                             try {
                                 const specEntries = await (0, fs_extra_2.readdir)(specDir, { withFileTypes: true });
                                 for (const entry of specEntries) {
-                                    if (!entry.isDirectory() || entry.name === spec_paths_1.GLOBAL_SPECS_DIR || validPlatforms.has(entry.name))
+                                    if (!entry.isDirectory() || entry.name === spec_paths_2.GLOBAL_SPECS_DIR || validPlatforms.has(entry.name))
                                         continue;
                                     const platformInFeature = (0, path_1.join)(specDir, entry.name, platformDir);
                                     if (await (0, fs_extra_1.pathExists)(platformInFeature)) {
@@ -2291,7 +2292,7 @@ ${singlePrompt}`);
         }
         if (!isGlobalScope) {
             // v8.3.237+: 与 JSON 通道一致——有功能模块的项目拦截，无功能模块的老项目放行
-            const featureCount = iterDir ? (await (0, spec_paths_1.parseFeatureList)(iterDir)).length : 0;
+            const featureCount = iterDir ? (await (0, spec_paths_2.parseFeatureList)(iterDir)).length : 0;
             if (featureCount > 0) {
                 for (const docName of docBlocks.keys()) {
                     if (docName === 'overview/REQUIREMENT.md' || docName === 'REQUIREMENT.md') {
@@ -2342,7 +2343,7 @@ ${singlePrompt}`);
                 else if (isGlobalScope) {
                     const globalBaseDir = (0, path_1.join)(_projectRoot, '.speccore', 'GLOBAL');
                     await (0, fs_extra_1.ensureDir)(globalBaseDir);
-                    const globalSet = new Set(spec_paths_1.GLOBAL_SPEC_FILES);
+                    const globalSet = new Set(spec_paths_2.GLOBAL_SPEC_FILES);
                     for (const [filename, content] of Object.entries(docs)) {
                         if (filename.startsWith('PATTERNS/')) {
                             const patternsDir = (0, path_1.join)(_projectRoot, '.speccore', 'PATTERNS');
@@ -2403,8 +2404,8 @@ ${singlePrompt}`);
                 else {
                     const specDir = (0, path_1.join)(iterDir, '020-specs');
                     await (0, fs_extra_1.ensureDir)(specDir);
-                    const globalSet = new Set(spec_paths_1.GLOBAL_SPEC_FILES);
-                    const validPlatforms = new Set([spec_paths_1.GLOBAL_SPECS_DIR, ...(await (0, spec_paths_1.parsePlatformList)())]);
+                    const globalSet = new Set(spec_paths_2.GLOBAL_SPEC_FILES);
+                    const validPlatforms = new Set([spec_paths_2.GLOBAL_SPECS_DIR, ...(await (0, spec_paths_2.parsePlatformList)())]);
                     let skippedCount = 0;
                     for (const [filename, content] of Object.entries(docs)) {
                         if (filename.startsWith('020-specs/requirements/')) {
@@ -2453,8 +2454,8 @@ ${singlePrompt}`);
                             continue;
                         }
                         let cleanFilename = filename;
-                        if (cleanFilename.startsWith(`${spec_paths_1.GLOBAL_SPECS_DIR}/`)) {
-                            cleanFilename = cleanFilename.slice(`${spec_paths_1.GLOBAL_SPECS_DIR}/`.length);
+                        if (cleanFilename.startsWith(`${spec_paths_2.GLOBAL_SPECS_DIR}/`)) {
+                            cleanFilename = cleanFilename.slice(`${spec_paths_2.GLOBAL_SPECS_DIR}/`.length);
                         }
                         if (cleanFilename.includes('/')) {
                             const prefix = cleanFilename.split('/')[0];
@@ -2473,7 +2474,7 @@ ${singlePrompt}`);
                         // 若 cleanFilename 含合法端名前缀（如 api/TECH.md），写入对应端目录
                         let targetDir;
                         if (globalSet.has(cleanFilename)) {
-                            targetDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
+                            targetDir = (0, path_1.join)(specDir, spec_paths_2.GLOBAL_SPECS_DIR);
                         }
                         else if (platformDir && validPlatforms.has(platformDir)) {
                             targetDir = (0, path_1.join)(specDir, platformDir);
@@ -2588,7 +2589,7 @@ ${singlePrompt}`);
         else if (!hasClarifyMarkers) {
             // 迭代级：写 020-specs/overview/（迭代综合文档，v6.78.0+）
             const specDir = (0, path_1.join)(iterDir, '020-specs');
-            const globalDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
+            const globalDir = (0, path_1.join)(specDir, spec_paths_2.GLOBAL_SPECS_DIR);
             await (0, fs_extra_1.ensureDir)(globalDir);
             const iterAnalysisPath = (0, path_1.join)(globalDir, 'ANALYSIS.md');
             if (await (0, task_utils_1.shouldOverwrite)(iterAnalysisPath, !!options.interactive)) {
@@ -2633,7 +2634,7 @@ ${singlePrompt}`);
         // ── v6.64.0+: Phase 1 完成后自动触发 Phase 2（仅多端项目，非 Pipeline 模式）──
         if (!options.phase && !isTaskLevel && options.iteration) {
             // 检查是否有多个端
-            const platforms = await (0, spec_paths_1.parsePlatformList)();
+            const platforms = await (0, spec_paths_2.parsePlatformList)();
             // 只有多端项目(≥2 个端)才需要分两阶段:
             // - Phase 1: 生成综合文档(overview/REQUIREMENT.md、ANALYSIS.md、DEPS.md)
             // - Phase 2: 生成各端专属文档({端}/TECH.md、TEST.md、UI_SPEC.md)
@@ -2726,9 +2727,9 @@ async function sanitizeSpecDirectories(iterDir) {
     const specDir = (0, path_1.join)(iterDir, '020-specs');
     if (!await (0, fs_extra_1.pathExists)(specDir))
         return;
-    const platforms = await (0, spec_paths_1.parsePlatformList)();
-    const validDirs = new Set([spec_paths_1.GLOBAL_SPECS_DIR, ...platforms]);
-    const globalSet = new Set(spec_paths_1.GLOBAL_SPEC_FILES);
+    const platforms = await (0, spec_paths_2.parsePlatformList)();
+    const validDirs = new Set([spec_paths_2.GLOBAL_SPECS_DIR, ...platforms]);
+    const globalSet = new Set(spec_paths_2.GLOBAL_SPEC_FILES);
     const entries = await (0, fs_extra_2.readdir)(specDir);
     let illegalDirCount = 0;
     let orphanFileCount = 0;
@@ -2739,17 +2740,17 @@ async function sanitizeSpecDirectories(iterDir) {
         if (entryStat.isDirectory()) {
             // 检测遗留的 global/ 目录（v6.78.0+ 已改名为 overview/）
             if (entry === 'global') {
-                logger_1.logger.warn(`⚠️ 检测到遗留 global/ 目录（v6.78.0+ 已改名为 ${spec_paths_1.GLOBAL_SPECS_DIR}/）`);
+                logger_1.logger.warn(`⚠️ 检测到遗留 global/ 目录（v6.78.0+ 已改名为 ${spec_paths_2.GLOBAL_SPECS_DIR}/）`);
                 // 将 global/ 中的文件迁移到 overview/
                 const globalFiles = await (0, fs_extra_2.readdir)(entryPath);
-                const overviewDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
+                const overviewDir = (0, path_1.join)(specDir, spec_paths_2.GLOBAL_SPECS_DIR);
                 await (0, fs_extra_1.ensureDir)(overviewDir);
                 for (const f of globalFiles) {
                     const src = (0, path_1.join)(entryPath, f);
                     const dest = (0, path_1.join)(overviewDir, f);
                     if (!await (0, fs_extra_1.pathExists)(dest)) {
                         await (0, fs_extra_1.rename)(src, dest);
-                        logger_1.logger.info(`   📦 迁移: global/${f} → ${spec_paths_1.GLOBAL_SPECS_DIR}/${f}`);
+                        logger_1.logger.info(`   📦 迁移: global/${f} → ${spec_paths_2.GLOBAL_SPECS_DIR}/${f}`);
                     }
                 }
                 // 删除空的 global/ 目录
@@ -2781,12 +2782,12 @@ async function sanitizeSpecDirectories(iterDir) {
         else if (entryStat.isFile()) {
             // v8.3.11+: 根目录散落的文件 → 检查是否应归入 overview/（不限于 .md）
             if (globalSet.has(entry)) {
-                const overviewDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
+                const overviewDir = (0, path_1.join)(specDir, spec_paths_2.GLOBAL_SPECS_DIR);
                 await (0, fs_extra_1.ensureDir)(overviewDir);
                 const dest = (0, path_1.join)(overviewDir, entry);
                 if (!await (0, fs_extra_1.pathExists)(dest)) {
                     await (0, fs_extra_1.rename)(entryPath, dest);
-                    logger_1.logger.warn(`⚠️ 散落文件已归位: 020-specs/${entry} → ${spec_paths_1.GLOBAL_SPECS_DIR}/${entry}`);
+                    logger_1.logger.warn(`⚠️ 散落文件已归位: 020-specs/${entry} → ${spec_paths_2.GLOBAL_SPECS_DIR}/${entry}`);
                     orphanFileCount++;
                 }
                 else {
@@ -2806,9 +2807,9 @@ async function sanitizeSpecDirectories(iterDir) {
         if (illegalDirCount > 0)
             logger_1.logger.warn(`   ⚠️ ${illegalDirCount} 个非法目录已归档（AI 绕过 --apply 创建）`);
         if (orphanFileCount > 0)
-            logger_1.logger.warn(`   ⚠️ ${orphanFileCount} 个散落文件已归位到 ${spec_paths_1.GLOBAL_SPECS_DIR}/`);
+            logger_1.logger.warn(`   ⚠️ ${orphanFileCount} 个散落文件已归位到 ${spec_paths_2.GLOBAL_SPECS_DIR}/`);
         if (legacyGlobalMigrated)
-            logger_1.logger.info(`   📦 遗留 global/ 已迁移到 ${spec_paths_1.GLOBAL_SPECS_DIR}/`);
+            logger_1.logger.info(`   📦 遗留 global/ 已迁移到 ${spec_paths_2.GLOBAL_SPECS_DIR}/`);
         logger_1.logger.info(`   ✅ 当前合法目录: ${Array.from(validDirs).join(', ')}`);
     }
 }
@@ -2818,7 +2819,7 @@ async function sanitizeSpecDirectories(iterDir) {
 async function generateIterationSpecDocs(iteration) {
     const iterDir = await (0, context_1.getIterationDir)(iteration);
     const specDir = (0, path_1.join)(iterDir, '020-specs');
-    const globalDir = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR);
+    const globalDir = (0, path_1.join)(specDir, spec_paths_2.GLOBAL_SPECS_DIR);
     await (0, fs_extra_1.ensureDir)(globalDir);
     const now = new Date().toISOString().split('T')[0];
     // 综合文档模板 → 写入 global/ 子目录（v6.41.0+）
@@ -3049,6 +3050,9 @@ function parseArgv(options) {
         [['--output', '-o'], (v) => { options.output = v; }],
         [['--depth'], (v) => { options.depth = v; }],
         [['--feature'], (v) => { options.feature = v; }],
+        // v8.3.248+: --unit 指定功能单元（支持逗号分隔多个），此前多单元 prompt 指示的
+        // 「analyze --unit {id} --apply」提交命令因未注册该选项而静默失效
+        [['--unit'], (v) => { options.unit = v; }],
         [['--phase'], (v) => { options.phase = v; }],
         [['--out-dir'], (v) => { options.outDir = v; }],
     ];
@@ -4410,10 +4414,10 @@ async function buildMultiDocPrompt(command, ctx, options, clarifyCtx) {
                 };
                 // 4a: 追加各前端端的需求文档
                 if (subLayerTarget === '4a') {
-                    const allPlatforms = await (0, spec_paths_1.parsePlatformList)();
+                    const allPlatforms = await (0, spec_paths_2.parsePlatformList)();
                     const frontendPlatforms = allPlatforms.filter(p => {
                         const pt = (async () => { try {
-                            const m = await (0, spec_paths_1.parsePlatformTypes)();
+                            const m = await (0, spec_paths_2.parsePlatformTypes)();
                             return m.get(p);
                         }
                         catch {
@@ -5029,11 +5033,11 @@ sequenceDiagram
             const iterDir = await (0, context_1.getIterationDir)(ctx.iteration);
             if (iterDir) {
                 const specDir = (0, path_1.join)(iterDir, '020-specs');
-                const platforms = await (0, spec_paths_1.parsePlatformList)();
+                const platforms = await (0, spec_paths_2.parsePlatformList)();
                 // v8.3.237+: 有功能模块的项目用功能模块 manifest（内容类骨架在 {feature}/overview/，
                 // 全局 overview/ 只含索引类），避免旧 manifest 把 overview/REQUIREMENT.md 当
                 // 「下一个待填充」但 --apply 又按路由表拦截 → 单文档模式死锁。
-                const features = await (0, spec_paths_1.parseFeatureList)(iterDir);
+                const features = await (0, spec_paths_2.parseFeatureList)(iterDir);
                 const manifest = features.length > 0
                     ? (0, spec_skeleton_1.computeFeatureBasedAnalyzeManifest)(features, platforms, undefined, ctx.iteration)
                     : (0, spec_skeleton_1.computeAnalyzeManifest)(platforms, undefined, ctx.iteration);
@@ -5082,14 +5086,14 @@ sequenceDiagram
                     // v8.1.1+: DOC_MATRIX 交叉校验 — 检查骨架清单之外是否有遗漏的文档
                     // v8.3.237+: 有功能模块的项目全局 overview/ 只应有索引类文档，
                     // 内容类（REQUIREMENT.md 等）归 {feature}/overview/，不得在此补建骨架
-                    const hasFeatures = (await (0, spec_paths_1.parseFeatureList)(iterDir)).length > 0;
+                    const hasFeatures = (await (0, spec_paths_2.parseFeatureList)(iterDir)).length > 0;
                     const expectedGlobalDocs = (hasFeatures
                         ? spec_skeleton_1.PHASE1_INDEX_DOC_NAMES
                         : GLOBAL_DOCS)
                         .filter(d => includeDocs.includes(d));
                     const missingDocs = [];
                     for (const doc of expectedGlobalDocs) {
-                        const docPath = (0, path_1.join)(specDir, spec_paths_1.GLOBAL_SPECS_DIR, doc);
+                        const docPath = (0, path_1.join)(specDir, spec_paths_2.GLOBAL_SPECS_DIR, doc);
                         if (!await (0, fs_extra_1.pathExists)(docPath)) {
                             missingDocs.push(doc);
                         }
@@ -5340,7 +5344,7 @@ status: "clarified"
     }
     // ── v6.67.0+: 在 prompt 开头就明确完整工作流程 ──
     if (!ctx.phase && !isTask) {
-        const platforms = await (0, spec_paths_1.parsePlatformList)();
+        const platforms = await (0, spec_paths_2.parsePlatformList)();
         if (platforms.length >= 2) {
             prompt += `## 📋 完整工作流程（两阶段分析）\n\n`;
             prompt += `本项目检测到有 ${platforms.length} 个端(${platforms.join('、')})，需要分两阶段执行：\n\n`;
@@ -5362,10 +5366,10 @@ status: "clarified"
     try {
         const iterDir = await (0, context_1.getIterationDir)(iter);
         if (iterDir) {
-            const platforms = await (0, spec_paths_1.parsePlatformList)();
+            const platforms = await (0, spec_paths_2.parsePlatformList)();
             const phase = options?.phase;
             // v8.3.34: 按需求文档名组织，prompt 中的文件清单也要用功能模块结构
-            const features = await (0, spec_paths_1.parseFeatureList)(iterDir);
+            const features = await (0, spec_paths_2.parseFeatureList)(iterDir);
             const manifest = (0, spec_skeleton_1.computeFeatureBasedAnalyzeManifest)(features, platforms, phase, iter);
             const specDir = (0, path_1.join)(iterDir, '020-specs');
             prompt += (0, spec_skeleton_1.buildSkeletonFileList)(manifest, specDir);
@@ -5636,8 +5640,19 @@ status: "clarified"
                 // v8.3.160+: 大项目按端分段读取，避免一次性加载全量结构化数据
                 prompt += `   - 先 Read \`.speccore/cache/structured-data.json\` 的 stats 部分（了解各端规模）\n`;
                 prompt += `   - **按需读取各端分段文件**：\`.speccore/cache/structured-data.{端名}.json\`（只读取本功能模块涉及的端）\n`;
-                prompt += `   - 再按需 Read 各端源码中与本功能模块相关的关键文件（从 CONSTITUTION.md 获取源码路径）\n`;
-                prompt += `   - 重点关注：接口定义、数据模型、业务逻辑实现、状态管理\n\n`;
+                // v8.3.248+: 直接注入各端工程路径表（此前仅提示 AI「从 CONSTITUTION.md 获取源码路径」，
+                // AI 需自行翻表定位；现在直接给出，减少一步间接查找、杜绝瞎猜）
+                try {
+                    const projectInfoMap = await (0, spec_paths_1.parseProjectInfo)();
+                    if (projectInfoMap.size > 0) {
+                        prompt += `   - **各端工程路径**（结合源码分析时按此定位，CONSTITUTION.md 工程表权威）：\n`;
+                        for (const [identifier, info] of projectInfoMap) {
+                            prompt += `     - \`${identifier}\`（${info.projectType || '-'}）→ \`${info.srcPath}\`\n`;
+                        }
+                    }
+                }
+                catch { /* 路径解析失败不阻断分析 */ }
+                prompt += `   - 再按需 Read 各端源码中与本功能模块相关的关键文件，重点关注：接口定义、数据模型、业务逻辑实现、状态管理\n\n`;
             }
             prompt += `3. 读取迭代需求文档（按功能模块组织）：\n`;
             prompt += `   a. 先读 010-requirements/INDEX.md — 获取功能模块清单\n`;
@@ -5729,7 +5744,7 @@ status: "clarified"
             prompt += `   - INTERACTION_MAP.md 是前后端开发者的共同参考，补全产品文档中隐含的技术交互\n`;
             // 注入工程类型信息（v6.49.0+）
             // v8.3.160+: 精简为路径引用，具体维度让 AI 从 CONSTITUTION.md 读取
-            const platformTypes = await (0, spec_paths_1.parsePlatformTypes)();
+            const platformTypes = await (0, spec_paths_2.parsePlatformTypes)();
             if (platformTypes.size > 0) {
                 prompt += `8. **工程类型识别**：CONSTITUTION.md 已配置各端的工程类型，请 Read 后据此生成针对性内容\n`;
                 prompt += `   | 工程标识 | 工程类型 |\n`;
@@ -5915,7 +5930,7 @@ status: "clarified"
         }
         else {
             prompt += `> 🎉 这是最后一个骨架文件！填充后所有迭代级分析文档将完整。\n`;
-            const platforms = await (0, spec_paths_1.parsePlatformList)();
+            const platforms = await (0, spec_paths_2.parsePlatformList)();
             const hasPlatformUnfilled = perDocStatus.unfilled.some(p => p.includes('/') && !p.startsWith('overview/'));
             if (platforms.length >= 2 && hasPlatformUnfilled) {
                 prompt += `> 下一步: 生成各端专属文档 → \`speccore analyze --prompt -I ${iter} --phase 2\`\n`;
@@ -5990,8 +6005,8 @@ status: "clarified"
 // ── v6.74.0+: 流式全局分析 Prompt 生成 ──
 async function buildStreamingGlobalPrompt(command, ctx, options) {
     const iter = ctx.iteration || '当前迭代';
-    const platforms = await (0, spec_paths_1.parsePlatformList)();
-    const platformTypes = await (0, spec_paths_1.parsePlatformTypes)();
+    const platforms = await (0, spec_paths_2.parsePlatformList)();
+    const platformTypes = await (0, spec_paths_2.parsePlatformTypes)();
     // 确定当前 Phase
     let currentPhase = 'phase0-scan';
     if (options?.streamingPhase) {
@@ -6094,7 +6109,7 @@ async function buildStreamingGlobalPrompt(command, ctx, options) {
 // ── v6.69.0+: 契约先行 Prompt 生成（增强策略一）──
 async function buildContractFirstPrompt(iteration) {
     const iterDir = await (0, context_1.getIterationDir)(iteration);
-    const globalDir = (0, path_1.join)(iterDir, '020-specs', spec_paths_1.GLOBAL_SPECS_DIR);
+    const globalDir = (0, path_1.join)(iterDir, '020-specs', spec_paths_2.GLOBAL_SPECS_DIR);
     let prompt = `\n# 任务: 跨端 API 契约定义（契约先行阶段）\n\n`;
     prompt += `## 背景\n\n`;
     prompt += `Phase 1 迭代分析已完成。现在需要在各端开始专属技术方案分析之前，**先定义跨端 API 契约**。\n\n`;
@@ -6174,7 +6189,7 @@ async function buildContractFirstPrompt(iteration) {
 // ── v6.49.9+: 扫描平铺的端目录，返回所有子任务目录路径 ──
 async function getSubtaskDirs(taskDir) {
     const result = [];
-    const platformList = await (0, spec_paths_1.parsePlatformList)();
+    const platformList = await (0, spec_paths_2.parsePlatformList)();
     for (const platform of platformList) {
         const platDir = (0, path_1.join)(taskDir, platform);
         if (!(await (0, fs_extra_1.pathExists)(platDir)))