speccore 6.6.0 → 6.11.0

package/dist/core/knowledge-graph.js

@@ -51,6 +51,8 @@ const crypto_1 = require("crypto");
 const context_1 = require("./context");
 const task_paths_1 = require("./task-paths");
 const task_utils_1 = require("../utils/task-utils");
+const logger_1 = require("../utils/logger");
+const kgCache = new Map();
 // ═══════════════════════════════════════════════
 // 文件扫描辅助
 // ═══════════════════════════════════════════════
@@ -102,6 +104,9 @@ async function scanRequirements(iterDir, iterName) {
             const fullPath = (0, path_1.join)(dir, item.name);
             const relPath = `${prefix}${item.name}`;
             if (item.isDirectory()) {
+                // sources/ 由 scanUserFiles() 单独处理，避免双重注册
+                if (item.name === 'sources')
+                    continue;
                 await scanDir(fullPath, `${relPath}/`);
             }
             else if (item.name.endsWith('.md') && item.name !== 'INDEX.md' && !(0, task_utils_1.isTimestampBackup)(item.name)) {
@@ -118,7 +123,13 @@ async function scanRequirements(iterDir, iterName) {
                     file: `010-requirements/${relPath}`,
                     hash,
                     mtime,
-                    tags: [prefix.includes('features/') ? 'feature' : 'requirement'],
+                    tags: [
+                        prefix.includes('features/') ? 'feature'
+                            : prefix.includes('bugs/') ? 'bug'
+                                : prefix.includes('refactors/') ? 'refactor'
+                                    : prefix.includes('research/') ? 'research'
+                                        : 'requirement'
+                    ],
                 });
             }
         }
@@ -179,6 +190,74 @@ async function scanSpecs(iterDir) {
             }
         }
     }
+    // 扫描 features/ 子目录（按功能模块的分析产出）
+    const featuresDir = (0, path_1.join)(specsDir, 'features');
+    if (await (0, fs_extra_1.pathExists)(featuresDir)) {
+        const featureEntries = await (0, fs_extra_1.readdir)(featuresDir, { withFileTypes: true });
+        for (const fe of featureEntries) {
+            if (fe.name.startsWith('.') || (0, task_utils_1.isTimestampBackup)(fe.name))
+                continue;
+            if (!fe.name.endsWith('.md'))
+                continue;
+            const fullPath = (0, path_1.join)(featuresDir, fe.name);
+            const { hash, mtime } = await fileHash(fullPath);
+            const title = await extractTitle(fullPath);
+            const featureName = fe.name.replace('.md', '');
+            entities.push({
+                id: `SPEC:features/${featureName}`,
+                type: 'spec',
+                title: title || featureName,
+                file: `020-specs/features/${fe.name}`,
+                hash,
+                mtime,
+                tags: ['feature-spec'],
+            });
+            // 关联到对应的需求 feature（同名匹配）
+            const reqFeaturePath = (0, path_1.join)('010-requirements', 'features', featureName);
+            const matchedReq = entities.find(e => e.file?.startsWith(reqFeaturePath));
+            if (matchedReq) {
+                relations.push({
+                    from: `SPEC:features/${featureName}`,
+                    to: matchedReq.id,
+                    type: 'references',
+                });
+            }
+        }
+    }
+    // 扫描类型目录（bugs/refactors/research — 扁平文件）
+    for (const typeDir of ['bugs', 'refactors', 'research']) {
+        const typeDirPath = (0, path_1.join)(specsDir, typeDir);
+        if (!(await (0, fs_extra_1.pathExists)(typeDirPath)))
+            continue;
+        const typeEntries = await (0, fs_extra_1.readdir)(typeDirPath, { withFileTypes: true });
+        for (const te of typeEntries) {
+            if (!te.isFile() || !te.name.endsWith('.md') || (0, task_utils_1.isTimestampBackup)(te.name))
+                continue;
+            const fullPath = (0, path_1.join)(typeDirPath, te.name);
+            const { hash, mtime } = await fileHash(fullPath);
+            const title = await extractTitle(fullPath);
+            const slug = te.name.replace('.md', '');
+            entities.push({
+                id: `SPEC:${typeDir}/${slug}`,
+                type: 'spec',
+                title: title || slug,
+                file: `020-specs/${typeDir}/${te.name}`,
+                hash,
+                mtime,
+                tags: [`${typeDir}-spec`],
+            });
+            // 关联到对应的需求文件（同名匹配）
+            const reqPath = (0, path_1.join)('010-requirements', typeDir, te.name);
+            const matchedReq = entities.find(e => e.file === reqPath);
+            if (matchedReq) {
+                relations.push({
+                    from: `SPEC:${typeDir}/${slug}`,
+                    to: matchedReq.id,
+                    type: 'references',
+                });
+            }
+        }
+    }
     return { entities, relations };
 }
 // ═══════════════════════════════════════════════
@@ -232,7 +311,34 @@ async function scanTasks(iterDir) {
                     status = 'in_progress';
             }
         }
-        const { hash, mtime } = taskMdPath ? await fileHash(taskMdPath) : { hash: '', mtime: '' };
+        // 回退：从 _shared/REQ.md 提取标题和状态
+        if (title === taskId) {
+            const reqMdPath = (0, path_1.join)(taskPath, '_shared', 'REQ.md');
+            if (await (0, fs_extra_1.pathExists)(reqMdPath)) {
+                const reqContent = await (0, fs_extra_1.readFile)(reqMdPath, 'utf-8');
+                const reqTitleMatch = reqContent.match(/^#\s+(.+)/m);
+                if (reqTitleMatch)
+                    title = reqTitleMatch[1].trim().slice(0, 80);
+            }
+        }
+        // hash/mtime 回退链：TASK.md → REQ.md → .meta/status
+        let hash = '', mtime = '';
+        if (taskMdPath) {
+            const h = await fileHash(taskMdPath);
+            hash = h.hash;
+            mtime = h.mtime;
+        }
+        else {
+            const fallbackPaths = [(0, path_1.join)(taskPath, '_shared', 'REQ.md'), (0, path_1.join)(taskPath, '.meta', 'status')];
+            for (const fp of fallbackPaths) {
+                if (await (0, fs_extra_1.pathExists)(fp)) {
+                    const h = await fileHash(fp);
+                    hash = h.hash;
+                    mtime = h.mtime;
+                    break;
+                }
+            }
+        }
         entities.push({
             id: taskId,
             type: 'task',
@@ -253,27 +359,43 @@ async function scanTasks(iterDir) {
             if ((0, task_utils_1.isTimestampBackup)(de.name))
                 continue;
             const platformTaskMd = (0, path_1.join)(taskPath, de.name, 'TASK.md');
-            if (!(await (0, fs_extra_1.pathExists)(platformTaskMd)))
-                continue;
-            const subContent = await (0, fs_extra_1.readFile)(platformTaskMd, 'utf-8');
-            let subTitle = `${title} - ${de.name}`;
+            let subTitle = `${title} — ${de.name}`;
             let subStatus = 'pending';
             let subTaskId = `${taskId}-${de.name}`;
-            const titleMatch = subContent.match(/^#\s+(.+)/m);
-            if (titleMatch)
-                subTitle = titleMatch[1].trim().slice(0, 80);
-            const statusMatch = subContent.match(/\*\*状态\*\*[:\s]*(.+)/);
-            if (statusMatch) {
-                const raw = statusMatch[1].trim();
-                if (raw.includes('已完成') || raw.includes('completed'))
-                    subStatus = 'completed';
-                else if (raw.includes('进行中') || raw.includes('in_progress'))
-                    subStatus = 'in_progress';
+            if (await (0, fs_extra_1.pathExists)(platformTaskMd)) {
+                const subContent = await (0, fs_extra_1.readFile)(platformTaskMd, 'utf-8');
+                const titleMatch = subContent.match(/^#\s+(.+)/m);
+                if (titleMatch)
+                    subTitle = titleMatch[1].trim().slice(0, 80);
+                const statusMatch = subContent.match(/\*\*状态\*\*[:\s]*(.+)/);
+                if (statusMatch) {
+                    const raw = statusMatch[1].trim();
+                    if (raw.includes('已完成') || raw.includes('completed'))
+                        subStatus = 'completed';
+                    else if (raw.includes('进行中') || raw.includes('in_progress'))
+                        subStatus = 'in_progress';
+                }
+                const subIdMatch = subContent.match(/子任务 ID\*\*[:\s]*`(Task-[^`]+)`/);
+                if (subIdMatch)
+                    subTaskId = subIdMatch[1];
+            }
+            // hash 回退：TASK.md → src/ 目录文件 → 空
+            let subHash = { hash: '', mtime: '' };
+            if (await (0, fs_extra_1.pathExists)(platformTaskMd)) {
+                subHash = await fileHash(platformTaskMd);
+            }
+            else {
+                const srcDir = (0, path_1.join)(taskPath, de.name, 'src');
+                if (await (0, fs_extra_1.pathExists)(srcDir)) {
+                    try {
+                        const srcFiles = await (0, fs_extra_1.readdir)(srcDir);
+                        if (srcFiles.length > 0) {
+                            subHash = await fileHash((0, path_1.join)(srcDir, srcFiles[0]));
+                        }
+                    }
+                    catch { /* 忽略 */ }
+                }
             }
-            const subIdMatch = subContent.match(/子任务 ID\*\*[:\s]*`(Task-[^`]+)`/);
-            if (subIdMatch)
-                subTaskId = subIdMatch[1];
-            const subHash = await fileHash(platformTaskMd);
             entities.push({
                 id: subTaskId,
                 type: 'subtask',
@@ -331,6 +453,240 @@ async function scanUserFiles(iterDir) {
     return entities;
 }
 // ═══════════════════════════════════════════════
+// 源码文件扫描（从 code-index 缓存读取）
+// ═══════════════════════════════════════════════
+async function scanSourceFiles(cwd) {
+    const entities = [];
+    const relations = [];
+    // 从 code-index 缓存读取
+    const indexPath = (0, path_1.join)(cwd, '.speccore', 'cache', 'code-structure.json');
+    if (!(await (0, fs_extra_1.pathExists)(indexPath)))
+        return { entities, relations };
+    try {
+        const index = JSON.parse(await (0, fs_extra_1.readFile)(indexPath, 'utf-8'));
+        const files = index.files || [];
+        // 只取核心文件（每个模块 top 3）
+        const moduleGroups = new Map();
+        for (const f of files) {
+            const key = `${f.endpoint || 'common'}:${f.module || 'root'}`;
+            if (!moduleGroups.has(key))
+                moduleGroups.set(key, []);
+            moduleGroups.get(key).push(f);
+        }
+        const coreFiles = [];
+        for (const group of moduleGroups.values()) {
+            group.sort((a, b) => (b.exports?.length || 0) - (a.exports?.length || 0));
+            coreFiles.push(...group.slice(0, 3));
+        }
+        // 限制总数，避免图谱过大
+        const maxFiles = Math.min(coreFiles.length, 50);
+        const selectedFiles = coreFiles.slice(0, maxFiles);
+        for (const f of selectedFiles) {
+            const id = `SRC:${f.path.replace(/\//g, '-').replace(/\.[^.]+$/, '')}`;
+            entities.push({
+                id,
+                type: 'source-file',
+                title: f.path.split('/').pop() || f.path,
+                file: f.path,
+                hash: '',
+                mtime: new Date(f.lastModified || 0).toISOString(),
+                endpoint: f.endpoint || 'common',
+                module: f.module || 'root',
+                language: f.language || 'unknown',
+                exports: (f.exports || []).slice(0, 10),
+                imports: (f.imports || []).slice(0, 15),
+                apis: f.apis || [],
+                tags: ['source', f.endpoint || 'common', f.module || 'root'],
+            });
+        }
+        // 构建 import 关系
+        const entityMap = new Map(entities.map(e => [e.id, e]));
+        for (const f of selectedFiles) {
+            const fromId = `SRC:${f.path.replace(/\//g, '-').replace(/\.[^.]+$/, '')}`;
+            for (const imp of (f.imports || [])) {
+                // 查找被 import 的文件
+                const impBasename = imp.replace(/\.[^.]+$/, '').replace(/.*[\/\\]/, '');
+                for (const other of selectedFiles) {
+                    if (other.path === f.path)
+                        continue;
+                    const otherBasename = other.path.replace(/\.[^.]+$/, '').replace(/.*[\/\\]/, '');
+                    if (imp.includes(otherBasename) || imp.includes(other.path)) {
+                        const toId = `SRC:${other.path.replace(/\//g, '-').replace(/\.[^.]+$/, '')}`;
+                        if (entityMap.has(toId) && !relations.some(r => r.from === fromId && r.to === toId && r.type === 'imports')) {
+                            relations.push({ from: fromId, to: toId, type: 'imports' });
+                        }
+                    }
+                }
+            }
+        }
+        // 构建模块依赖关系
+        const moduleDeps = new Map();
+        for (const f of selectedFiles) {
+            const fromMod = `${f.endpoint || 'common'}:${f.module || 'root'}`;
+            for (const imp of (f.imports || [])) {
+                for (const other of selectedFiles) {
+                    if (other.path === f.path)
+                        continue;
+                    const otherBasename = other.path.replace(/\.[^.]+$/, '').replace(/.*[\/\\]/, '');
+                    if (imp.includes(otherBasename)) {
+                        const toMod = `${other.endpoint || 'common'}:${other.module || 'root'}`;
+                        if (toMod !== fromMod) {
+                            if (!moduleDeps.has(fromMod))
+                                moduleDeps.set(fromMod, new Set());
+                            moduleDeps.get(fromMod).add(toMod);
+                        }
+                    }
+                }
+            }
+        }
+        // 添加模块依赖关系（用模块名作为虚拟节点）
+        for (const [fromMod, toMods] of moduleDeps) {
+            for (const toMod of toMods) {
+                if (!relations.some(r => r.from === fromMod && r.to === toMod && r.type === 'module_depends')) {
+                    relations.push({ from: fromMod, to: toMod, type: 'module_depends' });
+                }
+            }
+        }
+        // 构建 Git 共变关系
+        const correlations = index.correlations || [];
+        for (const corr of correlations) {
+            const filesInCorr = corr.files || [];
+            for (let i = 0; i < filesInCorr.length; i++) {
+                for (let j = i + 1; j < filesInCorr.length; j++) {
+                    const fromId = `SRC:${filesInCorr[i].replace(/\//g, '-').replace(/\.[^.]+$/, '')}`;
+                    const toId = `SRC:${filesInCorr[j].replace(/\//g, '-').replace(/\.[^.]+$/, '')}`;
+                    if (entityMap.has(fromId) && entityMap.has(toId)) {
+                        if (!relations.some(r => r.from === fromId && r.to === toId && r.type === 'co_changes')) {
+                            relations.push({ from: fromId, to: toId, type: 'co_changes' });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // 索引不存在或解析失败，跳过
+    }
+    return { entities, relations };
+}
+// ═══════════════════════════════════════════════
+// 全局层扫描（.speccore/GLOBAL/）
+// ═══════════════════════════════════════════════
+async function scanGlobalDocs(cwd) {
+    const entities = [];
+    const relations = [];
+    const globalDir = (0, path_1.join)(cwd, '.speccore', 'GLOBAL');
+    if (!(await (0, fs_extra_1.pathExists)(globalDir)))
+        return { entities, relations };
+    const scanDir = async (dir, prefix) => {
+        const items = await (0, fs_extra_1.readdir)(dir, { withFileTypes: true });
+        for (const item of items) {
+            if (item.name.startsWith('.') || (0, task_utils_1.isTimestampBackup)(item.name))
+                continue;
+            const fullPath = (0, path_1.join)(dir, item.name);
+            const relPath = `${prefix}${item.name}`;
+            if (item.isDirectory()) {
+                if (item.name === '_template' || item.name === 'RULES')
+                    continue;
+                await scanDir(fullPath, `${relPath}/`);
+            }
+            else if (item.name.endsWith('.md') && item.name !== 'INDEX.md') {
+                const { hash, mtime } = await fileHash(fullPath);
+                const title = await extractTitle(fullPath);
+                const tags = ['global'];
+                if (prefix.includes('synthesis/'))
+                    tags.push('synthesis');
+                else if (prefix.includes('platforms/')) {
+                    tags.push('platform');
+                    tags.push(prefix.split('platforms/')[1]?.split('/')[0] || '');
+                }
+                else if (prefix.includes('baselines/'))
+                    tags.push('baseline');
+                else if (prefix.includes('projects/'))
+                    tags.push('project');
+                entities.push({
+                    id: `GLOBAL:${relPath.replace(/\.md$/, '').replace(/\//g, '-')}`,
+                    type: 'global-doc',
+                    title: title || item.name.replace('.md', ''),
+                    file: `.speccore/GLOBAL/${relPath}`,
+                    hash,
+                    mtime,
+                    tags,
+                });
+            }
+        }
+    };
+    await scanDir(globalDir, '');
+    return { entities, relations };
+}
+// ═══════════════════════════════════════════════
+// 任务层详细规格扫描（Task-xxx/{platform}/REQ.md, TECH.md 等）
+// ═══════════════════════════════════════════════
+const TASK_SPEC_FILES = ['REQ.md', 'TECH.md', 'SCHEMA.md', 'CHANGELOG.md', 'TEST.md', 'TASK.md'];
+async function scanTaskSpecs(iterDir) {
+    const entities = [];
+    const relations = [];
+    const tasksDir = (0, path_1.join)(iterDir, '030-tasks');
+    if (!(await (0, fs_extra_1.pathExists)(tasksDir)))
+        return { entities, relations };
+    const findTaskDirs = async (dir) => {
+        const results = [];
+        try {
+            const entries = await (0, fs_extra_1.readdir)(dir, { withFileTypes: true });
+            for (const e of entries) {
+                const p = (0, path_1.join)(dir, e.name);
+                if (e.isDirectory()) {
+                    if (e.name.startsWith('Task-'))
+                        results.push(p);
+                    else if (!e.name.startsWith('.') && e.name !== 'node_modules') {
+                        results.push(...await findTaskDirs(p));
+                    }
+                }
+            }
+        }
+        catch { /* 跳过 */ }
+        return results;
+    };
+    const taskDirs = await findTaskDirs(tasksDir);
+    for (const taskDir of taskDirs) {
+        const taskId = taskDir.split('/').pop() || '';
+        const subDirs = ['_shared', '00-specs'];
+        try {
+            const entries = await (0, fs_extra_1.readdir)(taskDir, { withFileTypes: true });
+            for (const e of entries) {
+                if (e.isDirectory() && !e.name.startsWith('.') && !e.name.startsWith('0') && e.name !== '_shared' && e.name !== '99-artifacts' && !(0, task_utils_1.isTimestampBackup)(e.name)) {
+                    subDirs.push(e.name);
+                }
+            }
+        }
+        catch { /* 跳过 */ }
+        for (const subDir of subDirs) {
+            const specDir = (0, path_1.join)(taskDir, subDir);
+            if (!(await (0, fs_extra_1.pathExists)(specDir)))
+                continue;
+            for (const specFile of TASK_SPEC_FILES) {
+                const specPath = (0, path_1.join)(specDir, specFile);
+                if (!(await (0, fs_extra_1.pathExists)(specPath)))
+                    continue;
+                const { hash, mtime } = await fileHash(specPath);
+                const title = await extractTitle(specPath);
+                const specType = specFile.replace('.md', '').toLowerCase();
+                entities.push({
+                    id: `TSPEC:${taskId}-${subDir}-${specType}`,
+                    type: 'task-spec',
+                    title: title || `${taskId}/${subDir}/${specFile}`,
+                    file: `030-tasks/**/${taskId}/${subDir}/${specFile}`,
+                    hash,
+                    mtime,
+                    tags: ['task-spec', specType, subDir === '_shared' ? 'shared' : subDir],
+                });
+                relations.push({ from: `TSPEC:${taskId}-${subDir}-${specType}`, to: taskId, type: 'elaborates' });
+            }
+        }
+    }
+    return { entities, relations };
+}
+// ═══════════════════════════════════════════════
 // 关联推断
 // ═══════════════════════════════════════════════
 async function inferRelations(entities, iterDir) {
@@ -351,6 +707,26 @@ async function inferRelations(entities, iterDir) {
             }
         }
     }
+    // 需求 → 任务：内容关键词匹配（当编号匹配失败时回退）
+    // 从需求标题中提取 ≥3 字符的特征关键词，匹配任务标题
+    const matchedPairs = new Set(relations.map(r => `${r.from}:${r.to}`));
+    for (const req of reqs) {
+        const reqKeywords = req.title
+            .split(/[-_\s]+/)
+            .filter(w => w.length >= 3);
+        if (reqKeywords.length === 0)
+            continue;
+        for (const task of tasks) {
+            const pairKey = `${task.id}:${req.id}`;
+            if (matchedPairs.has(pairKey))
+                continue;
+            const hasMatch = reqKeywords.some(kw => task.title.includes(kw));
+            if (hasMatch) {
+                relations.push({ from: task.id, to: req.id, type: 'implements' });
+                matchedPairs.add(pairKey);
+            }
+        }
+    }
     // 规格 → 需求：读取 spec 文件内容，提取 REQ-xxx 引用
     for (const spec of specs) {
         const specPath = (0, path_1.join)(iterDir, spec.file);
@@ -367,6 +743,60 @@ async function inferRelations(entities, iterDir) {
         }
         catch { /* 文件不存在或无法读取，跳过 */ }
     }
+    // 任务 → 需求 / 任务 → 规格：读取任务目录下的 REQ.md 和 TECH.md
+    for (const task of tasks) {
+        const taskAbsDir = (0, path_1.join)(iterDir, task.file);
+        const reqPaths = [
+            (0, path_1.join)(taskAbsDir, '_shared', 'REQ.md'),
+            (0, path_1.join)(taskAbsDir, '00-specs', 'REQ.md'),
+            (0, path_1.join)(taskAbsDir, 'REQ.md'),
+        ];
+        for (const reqPath of reqPaths) {
+            if (!(await (0, fs_extra_1.pathExists)(reqPath)))
+                continue;
+            try {
+                const content = await (0, fs_extra_1.readFile)(reqPath, 'utf-8');
+                // 提取 REQ-xxx 引用 → task implements req
+                const reqRefs = content.match(/REQ-\d+/g);
+                if (reqRefs) {
+                    for (const ref of [...new Set(reqRefs)]) {
+                        if (entityMap.has(ref) && !relations.some(r => r.from === task.id && r.to === ref && r.type === 'implements')) {
+                            relations.push({ from: task.id, to: ref, type: 'implements' });
+                        }
+                    }
+                }
+                // 提取 SPEC:xxx 引用 → task references spec
+                const specRefs = content.match(/SPEC:[\w\/\-]+/g);
+                if (specRefs) {
+                    for (const ref of [...new Set(specRefs)]) {
+                        if (entityMap.has(ref) && !relations.some(r => r.from === task.id && r.to === ref && r.type === 'references')) {
+                            relations.push({ from: task.id, to: ref, type: 'references' });
+                        }
+                    }
+                }
+            }
+            catch { /* 跳过 */ }
+            break; // 只读第一个存在的
+        }
+        // 读取 API_CONTRACT.yaml 解析依赖
+        const contractPath = (0, path_1.join)(taskAbsDir, '_shared', 'API_CONTRACT.yaml');
+        if (await (0, fs_extra_1.pathExists)(contractPath)) {
+            try {
+                const content = await (0, fs_extra_1.readFile)(contractPath, 'utf-8');
+                // 提取依赖的任务引用: dependsOn: Task-xxx 或 # Depends on Task-xxx
+                const depRefs = content.match(/(?:dependsOn|depends on|依赖)\s*[:：]\s*(Task-\S+)/gi);
+                if (depRefs) {
+                    for (const raw of depRefs) {
+                        const m = raw.match(/(Task-\S+)/i);
+                        if (m && entityMap.has(m[1]) && !relations.some(r => r.from === task.id && r.to === m[1] && r.type === 'depends_on')) {
+                            relations.push({ from: task.id, to: m[1], type: 'depends_on' });
+                        }
+                    }
+                }
+            }
+            catch { /* 跳过 */ }
+        }
+    }
     return relations;
 }
 // ═══════════════════════════════════════════════
@@ -381,7 +811,7 @@ async function buildKnowledgeGraph(cwd, iteration) {
         iteration: iterName,
         entities: {},
         relations: [],
-        stats: { requirements: 0, specs: 0, tasks: 0, subtasks: 0, userFiles: 0, relations: 0 },
+        stats: { requirements: 0, specs: 0, tasks: 0, subtasks: 0, userFiles: 0, sourceFiles: 0, globalDocs: 0, taskSpecs: 0, relations: 0 },
     };
     if (!iterDir || !(await (0, fs_extra_1.pathExists)(iterDir)))
         return graph;
@@ -390,21 +820,42 @@ async function buildKnowledgeGraph(cwd, iteration) {
     const specResult = await scanSpecs(iterDir);
     const taskResult = await scanTasks(iterDir);
     const userFiles = await scanUserFiles(iterDir);
-    // 合并实体
+    const sourceResult = await scanSourceFiles(cwd);
+    const globalResult = await scanGlobalDocs(cwd);
+    const taskSpecResult = await scanTaskSpecs(iterDir);
+    // 合并实体（处理 ID 冲突：同名实体用路径前缀去重）
     const allEntities = [
         ...reqResult.entities,
         ...specResult.entities,
         ...taskResult.entities,
         ...userFiles,
+        ...sourceResult.entities,
+        ...globalResult.entities,
+        ...taskSpecResult.entities,
     ];
+    const idRemap = new Map();
     for (const e of allEntities) {
+        let finalId = e.id;
+        if (graph.entities[e.id]) {
+            finalId = `${e.id}@${e.file.replace(/\//g, '-')}`;
+            idRemap.set(e.id, finalId);
+        }
+        e.id = finalId;
         graph.entities[e.id] = e;
     }
+    // 同步更新已有关系中的旧 ID
+    const remapId = (id) => idRemap.get(id) || id;
+    for (const r of [...reqResult.relations, ...specResult.relations, ...taskResult.relations, ...taskSpecResult.relations]) {
+        r.from = remapId(r.from);
+        r.to = remapId(r.to);
+    }
     // 合并关系
     graph.relations = [
         ...reqResult.relations,
         ...specResult.relations,
         ...taskResult.relations,
+        ...sourceResult.relations,
+        ...taskSpecResult.relations,
         ...(await inferRelations(allEntities, iterDir)),
     ];
     // 统计
@@ -414,6 +865,9 @@ async function buildKnowledgeGraph(cwd, iteration) {
         tasks: taskResult.entities.filter(e => e.type === 'task').length,
         subtasks: taskResult.entities.filter(e => e.type === 'subtask').length,
         userFiles: userFiles.length,
+        sourceFiles: sourceResult.entities.length,
+        globalDocs: globalResult.entities.length,
+        taskSpecs: taskSpecResult.entities.length,
         relations: graph.relations.length,
     };
     return graph;
@@ -427,13 +881,24 @@ async function saveKnowledgeGraph(cwd, graph) {
     return filePath;
 }
 /** 加载已存在的知识图谱 */
+/**
+ * 加载知识图谱（带进程缓存）
+ * 文件 mtime 未变时直接返回缓存，避免重复 JSON 解析
+ */
 async function loadKnowledgeGraph(cwd) {
     const filePath = (0, path_1.join)(cwd, '.speccore', 'cache', 'knowledge-graph.json');
     if (!(await (0, fs_extra_1.pathExists)(filePath)))
         return null;
     try {
+        const st = await (0, fs_extra_1.stat)(filePath);
+        const cached = kgCache.get(filePath);
+        if (cached && cached.mtime >= st.mtimeMs) {
+            return cached.graph;
+        }
         const content = await (0, fs_extra_1.readFile)(filePath, 'utf-8');
-        return JSON.parse(content);
+        const graph = JSON.parse(content);
+        kgCache.set(filePath, { graph, mtime: st.mtimeMs });
+        return graph;
     }
     catch {
         return null;
@@ -443,18 +908,38 @@ async function loadKnowledgeGraph(cwd) {
 function getTaskContext(graph, taskId) {
     const entity = graph.entities[taskId];
     if (!entity) {
-        return { requirement: null, siblingSubtasks: [], parentTask: null };
+        return { requirement: null, siblingSubtasks: [], parentTask: null, relatedSpecs: [], dependsOn: [] };
     }
     let requirement = null;
     let parentTask = null;
-    const siblingSubtasks = [];
-    // 找上游需求（直接 implements 或通过父任务间接关联）
-    for (const rel of graph.relations) {
-        if (rel.from === taskId && rel.type === 'implements') {
-            requirement = graph.entities[rel.to] || null;
+    const relatedSpecs = [];
+    const dependsOn = [];
+    // 预建索引：避免多次遍历全量关系
+    const parentIndex = new Map();
+    for (const e of Object.values(graph.entities)) {
+        if (e.type === 'subtask' && e.parentTaskId) {
+            const list = parentIndex.get(e.parentTaskId) || [];
+            list.push(e);
+            parentIndex.set(e.parentTaskId, list);
         }
-        if (rel.from === taskId && rel.type === 'subtask_of') {
-            parentTask = graph.entities[rel.to] || null;
+    }
+    // 找上游需求、关联规格、依赖任务
+    for (const rel of graph.relations) {
+        if (rel.from === taskId) {
+            if (rel.type === 'implements')
+                requirement = graph.entities[rel.to] || null;
+            if (rel.type === 'references') {
+                const spec = graph.entities[rel.to];
+                if (spec)
+                    relatedSpecs.push(spec);
+            }
+            if (rel.type === 'depends_on') {
+                const dep = graph.entities[rel.to];
+                if (dep)
+                    dependsOn.push(dep);
+            }
+            if (rel.type === 'subtask_of')
+                parentTask = graph.entities[rel.to] || null;
         }
     }
     // 子任务没有直接 implements 关系 → 通过父任务找上游需求
@@ -466,22 +951,25 @@ function getTaskContext(graph, taskId) {
             }
         }
     }
-    // 如果是子任务，找兄弟子任务
+    // 如果是子任务，找兄弟子任务（用索引，O(1)）
+    const siblingSubtasks = [];
     const parentId = entity.parentTaskId || parentTask?.id;
     if (parentId) {
-        for (const e of Object.values(graph.entities)) {
-            if (e.type === 'subtask' && e.parentTaskId === parentId) {
-                siblingSubtasks.push(e);
-            }
-        }
+        const siblings = parentIndex.get(parentId);
+        if (siblings)
+            siblingSubtasks.push(...siblings);
     }
-    return { requirement, siblingSubtasks, parentTask };
+    return { requirement, siblingSubtasks, parentTask, relatedSpecs, dependsOn };
 }
 // ═══════════════════════════════════════════════
 // 自动更新机制
 // ═══════════════════════════════════════════════
-/** 递归获取目录下所有文件的最新 mtime */
-async function getLatestMtime(dir) {
+/**
+ * 递归获取目录下所有文件的最新 mtime
+ * 限制：每个目录最多检查 MAX_FILES_PER_DIR 个文件，避免大型项目阻塞
+ */
+const MAX_FILES_PER_DIR = 100;
+async function getLatestMtime(dir, fileCount = { value: 0 }) {
     if (!(await (0, fs_extra_1.pathExists)(dir)))
         return 0;
     let latest = 0;
@@ -489,23 +977,26 @@ async function getLatestMtime(dir) {
     for (const item of items) {
         if (item.name.startsWith('.') || (0, task_utils_1.isTimestampBackup)(item.name))
             continue;
+        if (fileCount.value >= MAX_FILES_PER_DIR)
+            break;
         const fullPath = (0, path_1.join)(dir, item.name);
         const st = await (0, fs_extra_1.stat)(fullPath);
         if (item.isDirectory()) {
             if (item.name === 'node_modules' || item.name === 'cache')
                 continue;
-            const subLatest = await getLatestMtime(fullPath);
+            const subLatest = await getLatestMtime(fullPath, fileCount);
             if (subLatest > latest)
                 latest = subLatest;
         }
         else {
+            fileCount.value++;
             if (st.mtimeMs > latest)
                 latest = st.mtimeMs;
         }
     }
     return latest;
 }
-/** 检查知识图谱是否已过期 */
+/** 检查知识图谱是否已过期（带 500ms 超时保护） */
 async function isGraphStale(cwd, iteration) {
     const graph = await loadKnowledgeGraph(cwd);
     if (!graph)
@@ -522,7 +1013,13 @@ async function isGraphStale(cwd, iteration) {
         (0, path_1.join)(iterDir, '030-tasks'),
     ];
     for (const dir of dirsToCheck) {
+        // 超时保护：单目录扫描超过 200ms 就放弃
+        const start = Date.now();
         const latestMtime = await getLatestMtime(dir);
+        if (Date.now() - start > 200) {
+            logger_1.logger.debug(`isGraphStale: ${dir} 扫描超时，假设未过期`);
+            continue;
+        }
         if (latestMtime > graphTime)
             return true;
     }