openmatrix 0.2.5 → 0.2.6

package/dist/cli/commands/debug.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const debugCommand: Command;

package/dist/cli/commands/debug.js

@@ -0,0 +1,116 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debugCommand = void 0;
+// src/cli/commands/debug.ts
+const commander_1 = require("commander");
+const fs = __importStar(require("fs"));
+const debug_manager_js_1 = require("../../orchestrator/debug-manager.js");
+exports.debugCommand = new commander_1.Command('debug')
+    .description('系统化调试 - 诊断并修复问题')
+    .argument('[description]', '问题描述')
+    .option('--task <taskId>', '调试指定的失败任务')
+    .option('--diagnose-only', '仅诊断，不执行修复')
+    .option('--json', '输出 JSON 格式')
+    .option('--list', '列出最近的调试会话')
+    .action(async (description, options) => {
+    const basePath = process.cwd();
+    const omPath = `${basePath}/.openmatrix`;
+    // 初始化 .openmatrix 目录（如果不存在）
+    if (!fs.existsSync(omPath)) {
+        console.log('❌ .openmatrix 目录不存在，请先运行: openmatrix start --init-only');
+        return;
+    }
+    const debugManager = new debug_manager_js_1.DebugManager(omPath);
+    // 列出最近的调试会话
+    if (options.list) {
+        const sessions = debugManager.listRecent();
+        if (sessions.length === 0) {
+            console.log('📋 没有调试记录');
+            return;
+        }
+        console.log('📋 最近的调试会话:\n');
+        sessions.forEach(s => {
+            console.log(`  ${s.id}  ${s.status}  ${s.description}`);
+            console.log(`       ${s.createdAt}`);
+        });
+        return;
+    }
+    // 如果没有描述也没有任务 ID，提示用户
+    if (!description && !options.task) {
+        console.log('🔍 系统化调试 - 诊断并修复问题\n');
+        console.log('用法:');
+        console.log('  openmatrix debug <问题描述>           描述问题开始调试');
+        console.log('  openmatrix debug --task TASK-XXX       调试指定失败任务');
+        console.log('  openmatrix debug --diagnose-only       仅诊断不修复');
+        console.log('  openmatrix debug --list                列出最近调试记录');
+        console.log('  openmatrix debug --json                输出 JSON 格式\n');
+        console.log('示例:');
+        console.log('  openmatrix debug "API 返回 500 错误"');
+        console.log('  openmatrix debug --task TASK-003');
+        console.log('  openmatrix debug "测试失败" --diagnose-only');
+        return;
+    }
+    // 初始化调试会话
+    const result = await debugManager.initialize({
+        description,
+        taskId: options.task,
+        diagnoseOnly: options.diagnoseOnly
+    });
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    // 展示诊断信息
+    console.log('\n🔍 调试会话已初始化');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log(`会话 ID:    ${result.sessionId}`);
+    console.log(`状态:       ${result.status}`);
+    console.log(`问题类型:   ${result.problemType}`);
+    console.log(`问题描述:   ${result.report.description}`);
+    if (result.report.relatedTaskId) {
+        console.log(`关联任务:   ${result.report.relatedTaskId}`);
+    }
+    if (result.report.errorInfo?.message) {
+        console.log(`错误信息:   ${result.report.errorInfo.message}`);
+    }
+    if (result.report.relatedFiles && result.report.relatedFiles.length > 0) {
+        console.log(`相关文件:   ${result.report.relatedFiles.join(', ')}`);
+    }
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('\n💡 下一步:');
+    console.log('   使用 /om:debug 进入系统化调试流程');
+    console.log('   或使用 openmatrix debug --list 查看所有调试记录');
+});

package/dist/cli/index.js

@@ -51,6 +51,7 @@ const check_gitignore_js_1 = require("./commands/check-gitignore.js");
 const analyze_js_1 = require("./commands/analyze.js");
 const brainstorm_js_1 = require("./commands/brainstorm.js");
 const research_js_1 = require("./commands/research.js");
+const debug_js_1 = require("./commands/debug.js");
 const complete_js_1 = require("./commands/complete.js");
 const step_js_1 = require("./commands/step.js");
 // 读取 package.json 版本
@@ -85,5 +86,6 @@ program.addCommand(check_gitignore_js_1.checkGitignoreCommand);
 program.addCommand(analyze_js_1.analyzeCommand);
 program.addCommand(brainstorm_js_1.brainstormCommand);
 program.addCommand(research_js_1.researchCommand);
+program.addCommand(debug_js_1.debugCommand);
 // 默认帮助
 program.parse();

package/dist/orchestrator/context-collector.d.ts

@@ -0,0 +1,23 @@
+export interface DebugContext {
+    state?: Record<string, unknown>;
+    task?: Record<string, unknown>;
+    logs?: string;
+    errorStack?: string;
+    projectFiles?: string[];
+    envInfo?: Record<string, unknown>;
+    configFiles?: string[];
+    cliLogs?: string;
+    systemState?: Record<string, unknown>;
+}
+/**
+ * 根据问题类型收集上下文信息
+ */
+export declare class ContextCollector {
+    private basePath;
+    constructor(basePath: string);
+    collectForTaskFailure(taskId: string): Promise<DebugContext>;
+    collectForProjectBug(): Promise<DebugContext>;
+    collectForEnvironment(): Promise<DebugContext>;
+    collectForSystemBug(): Promise<DebugContext>;
+    private scanFiles;
+}

package/dist/orchestrator/context-collector.js

@@ -0,0 +1,168 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextCollector = void 0;
+// src/orchestrator/context-collector.ts
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * 根据问题类型收集上下文信息
+ */
+class ContextCollector {
+    basePath;
+    constructor(basePath) {
+        this.basePath = basePath;
+    }
+    async collectForTaskFailure(taskId) {
+        const context = {};
+        // 读取全局状态
+        const statePath = path.join(this.basePath, 'state.json');
+        if (fs.existsSync(statePath)) {
+            try {
+                context.state = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+            }
+            catch { /* ignore */ }
+        }
+        // 读取任务文件
+        const taskPath = path.join(this.basePath, 'tasks', `${taskId}.json`);
+        if (fs.existsSync(taskPath)) {
+            try {
+                context.task = JSON.parse(fs.readFileSync(taskPath, 'utf-8'));
+            }
+            catch { /* ignore */ }
+        }
+        // 读取日志
+        const logPath = path.join(this.basePath, 'logs');
+        if (fs.existsSync(logPath)) {
+            try {
+                const files = fs.readdirSync(logPath);
+                const logs = files
+                    .filter(f => f.endsWith('.log') || f.includes(taskId))
+                    .map(f => fs.readFileSync(path.join(logPath, f), 'utf-8'))
+                    .join('\n---\n');
+                if (logs)
+                    context.logs = logs;
+            }
+            catch { /* ignore */ }
+        }
+        return context;
+    }
+    async collectForProjectBug() {
+        const context = {};
+        // 扫描项目关键文件
+        const projectRoot = path.resolve(this.basePath, '..');
+        const scanDirs = ['src', 'lib', 'app', 'server', 'api', 'controllers', 'routes'];
+        const projectFiles = [];
+        for (const dir of scanDirs) {
+            const fullPath = path.join(projectRoot, dir);
+            if (fs.existsSync(fullPath)) {
+                const files = this.scanFiles(fullPath, ['.ts', '.js', '.tsx', '.jsx'], 2);
+                projectFiles.push(...files);
+            }
+        }
+        if (projectFiles.length > 0) {
+            context.projectFiles = projectFiles.slice(0, 50);
+        }
+        return context;
+    }
+    async collectForEnvironment() {
+        const context = {};
+        // 收集环境信息
+        const envInfo = {
+            nodeVersion: process.version,
+            platform: process.platform,
+            cwd: process.cwd(),
+            envVars: Object.keys(process.env).slice(0, 20)
+        };
+        context.envInfo = envInfo;
+        // 扫描配置文件
+        const projectRoot = path.resolve(this.basePath, '..');
+        const configFiles = [
+            'package.json',
+            'tsconfig.json',
+            '.env',
+            '.env.local',
+            'config.json',
+            'webpack.config.js',
+            'vite.config.ts',
+            '.openmatrix/state.json'
+        ];
+        const found = [];
+        for (const file of configFiles) {
+            const fullPath = path.join(projectRoot, file);
+            if (fs.existsSync(fullPath)) {
+                found.push(file);
+            }
+        }
+        if (found.length > 0) {
+            context.configFiles = found;
+        }
+        return context;
+    }
+    async collectForSystemBug() {
+        const context = {};
+        // 读取系统状态
+        const statePath = path.join(this.basePath, 'state.json');
+        if (fs.existsSync(statePath)) {
+            try {
+                context.systemState = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+            }
+            catch { /* ignore */ }
+        }
+        return context;
+    }
+    scanFiles(dir, extensions, maxDepth, currentDepth = 0) {
+        if (currentDepth > maxDepth)
+            return [];
+        const results = [];
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+                        results.push(...this.scanFiles(fullPath, extensions, maxDepth, currentDepth + 1));
+                    }
+                }
+                else if (extensions.some(ext => entry.name.endsWith(ext))) {
+                    results.push(fullPath.replace(process.cwd() + path.sep, ''));
+                }
+            }
+        }
+        catch { /* ignore */ }
+        return results;
+    }
+}
+exports.ContextCollector = ContextCollector;

package/dist/orchestrator/debug-manager.d.ts

@@ -0,0 +1,52 @@
+import type { DebugSession, DiagnosisReport, ProblemType } from '../types/index.js';
+export interface DebugConfig {
+    description?: string;
+    taskId?: string;
+    diagnoseOnly?: boolean;
+}
+export interface DebugInitResult {
+    sessionId: string;
+    status: string;
+    problemType: ProblemType;
+    report: Partial<DiagnosisReport>;
+}
+/**
+ * 调试管理器 - 协调整个调试流程
+ */
+export declare class DebugManager {
+    private omPath;
+    private detector;
+    private collector;
+    private reporter;
+    constructor(omPath: string);
+    /**
+     * 初始化调试会话
+     */
+    initialize(config: DebugConfig): Promise<DebugInitResult>;
+    /**
+     * 获取会话
+     */
+    getSession(sessionId: string): DebugSession | null;
+    /**
+     * 更新会话
+     */
+    updateSession(sessionId: string, updates: Partial<DebugSession>): void;
+    /**
+     * 完成会话
+     */
+    completeSession(sessionId: string): Promise<string | null>;
+    /**
+     * 列出最近的调试会话
+     */
+    listRecent(): {
+        id: string;
+        status: string;
+        description: string;
+        createdAt: string;
+    }[];
+    private collectContext;
+    private getTaskError;
+    private saveSession;
+    private getSessionPath;
+    private generateSessionId;
+}

package/dist/orchestrator/debug-manager.js

@@ -0,0 +1,214 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DebugManager = void 0;
+// src/orchestrator/debug-manager.ts
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const problem_detector_js_1 = require("./problem-detector.js");
+const context_collector_js_1 = require("./context-collector.js");
+const debug_reporter_js_1 = require("./debug-reporter.js");
+/**
+ * 调试管理器 - 协调整个调试流程
+ */
+class DebugManager {
+    omPath;
+    detector;
+    collector;
+    reporter;
+    constructor(omPath) {
+        this.omPath = omPath;
+        this.detector = new problem_detector_js_1.ProblemDetector();
+        this.collector = new context_collector_js_1.ContextCollector(omPath);
+        this.reporter = new debug_reporter_js_1.DebugReporter(omPath);
+    }
+    /**
+     * 初始化调试会话
+     */
+    async initialize(config) {
+        // 如果有任务 ID，尝试读取任务信息
+        let taskError = null;
+        if (config.taskId) {
+            taskError = await this.getTaskError(config.taskId);
+        }
+        // 判断问题类型
+        const problemType = await this.detector.detect({
+            description: config.description,
+            taskId: config.taskId,
+            taskError
+        });
+        // 收集上下文
+        const context = await this.collectContext(problemType, config);
+        // 创建会话
+        const sessionId = this.generateSessionId();
+        const session = {
+            id: sessionId,
+            status: config.diagnoseOnly ? 'initialized' : 'diagnosing',
+            report: {
+                id: sessionId,
+                problemType,
+                trigger: config.taskId ? 'auto' : 'explicit',
+                description: config.description || `调试任务 ${config.taskId}`,
+                relatedTaskId: config.taskId,
+                errorInfo: taskError ? {
+                    message: taskError,
+                    timestamp: new Date().toISOString()
+                } : undefined,
+                relatedFiles: context.projectFiles || [],
+                rootCause: '', // 由 Skill 阶段 Agent 填充
+                impactScope: [],
+                suggestedFix: '', // 由 Skill 阶段 Agent 填充
+                diagnosedAt: new Date().toISOString()
+            },
+            retryCount: 0,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString()
+        };
+        // 持久化会话
+        this.saveSession(session);
+        return {
+            sessionId,
+            status: session.status,
+            problemType,
+            report: {
+                description: session.report.description,
+                relatedTaskId: session.report.relatedTaskId,
+                relatedFiles: session.report.relatedFiles,
+                errorInfo: session.report.errorInfo
+            }
+        };
+    }
+    /**
+     * 获取会话
+     */
+    getSession(sessionId) {
+        const sessionPath = this.getSessionPath(sessionId);
+        if (!fs.existsSync(sessionPath))
+            return null;
+        try {
+            return JSON.parse(fs.readFileSync(sessionPath, 'utf-8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 更新会话
+     */
+    updateSession(sessionId, updates) {
+        const session = this.getSession(sessionId);
+        if (!session)
+            return;
+        Object.assign(session, updates, { updatedAt: new Date().toISOString() });
+        this.saveSession(session);
+    }
+    /**
+     * 完成会话
+     */
+    async completeSession(sessionId) {
+        const session = this.getSession(sessionId);
+        if (!session)
+            return null;
+        session.status = 'completed';
+        session.completedAt = new Date().toISOString();
+        this.saveSession(session);
+        return await this.reporter.generateReport(session);
+    }
+    /**
+     * 列出最近的调试会话
+     */
+    listRecent() {
+        const debugDir = path.join(this.omPath, 'debug');
+        if (!fs.existsSync(debugDir))
+            return [];
+        const files = fs.readdirSync(debugDir)
+            .filter(f => f.endsWith('.json') && f.startsWith('DEBUG-'))
+            .sort()
+            .reverse()
+            .slice(0, 10);
+        return files.map(f => {
+            const session = JSON.parse(fs.readFileSync(path.join(debugDir, f), 'utf-8'));
+            return {
+                id: session.id,
+                status: session.status,
+                description: session.report.description,
+                createdAt: session.createdAt
+            };
+        });
+    }
+    async collectContext(problemType, config) {
+        switch (problemType) {
+            case 'task_failure':
+                return config.taskId ? await this.collector.collectForTaskFailure(config.taskId) : {};
+            case 'project_bug':
+                return await this.collector.collectForProjectBug();
+            case 'environment':
+                return await this.collector.collectForEnvironment();
+            case 'system_bug':
+                return await this.collector.collectForSystemBug();
+            default:
+                return {};
+        }
+    }
+    async getTaskError(taskId) {
+        const taskPath = path.join(this.omPath, 'tasks', `${taskId}.json`);
+        if (!fs.existsSync(taskPath))
+            return null;
+        try {
+            const task = JSON.parse(fs.readFileSync(taskPath, 'utf-8'));
+            return task.error || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    saveSession(session) {
+        const debugDir = path.join(this.omPath, 'debug');
+        if (!fs.existsSync(debugDir)) {
+            fs.mkdirSync(debugDir, { recursive: true });
+        }
+        const sessionPath = this.getSessionPath(session.id);
+        fs.writeFileSync(sessionPath, JSON.stringify(session, null, 2), 'utf-8');
+    }
+    getSessionPath(sessionId) {
+        return path.join(this.omPath, 'debug', `${sessionId}.json`);
+    }
+    generateSessionId() {
+        const timestamp = Date.now().toString(36).toUpperCase();
+        const random = Math.random().toString(36).substring(2, 5).toUpperCase();
+        return `DEBUG-${timestamp}${random}`;
+    }
+}
+exports.DebugManager = DebugManager;

package/dist/orchestrator/debug-reporter.d.ts

@@ -0,0 +1,25 @@
+import type { DebugSession } from '../types/index.js';
+/**
+ * 生成和保存诊断报告
+ */
+export declare class DebugReporter {
+    private debugDir;
+    constructor(basePath: string);
+    /**
+     * 生成诊断报告文件
+     */
+    generateReport(session: DebugSession): Promise<string>;
+    /**
+     * 格式化报告内容为 Markdown
+     */
+    private formatReport;
+    /**
+     * 列出所有诊断报告
+     */
+    listReports(): {
+        id: string;
+        path: string;
+        createdAt: string;
+    }[];
+    private ensureDir;
+}

package/dist/orchestrator/debug-reporter.js

@@ -0,0 +1,167 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DebugReporter = void 0;
+// src/orchestrator/debug-reporter.ts
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * 生成和保存诊断报告
+ */
+class DebugReporter {
+    debugDir;
+    constructor(basePath) {
+        this.debugDir = path.join(basePath, 'debug');
+        this.ensureDir();
+    }
+    /**
+     * 生成诊断报告文件
+     */
+    async generateReport(session) {
+        const report = session.report;
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const fileName = `${report.id}-report-${timestamp}.md`;
+        const filePath = path.join(this.debugDir, fileName);
+        const content = this.formatReport(session);
+        fs.writeFileSync(filePath, content, 'utf-8');
+        return filePath;
+    }
+    /**
+     * 格式化报告内容为 Markdown
+     */
+    formatReport(session) {
+        const { report, fixResult, verifyResult } = session;
+        let md = `# Debug Report\n\n`;
+        md += `**会话 ID**: ${session.id}\n`;
+        md += `**日期**: ${session.createdAt}\n`;
+        md += `**状态**: ${session.status}\n`;
+        if (session.completedAt) {
+            md += `**完成时间**: ${session.completedAt}\n`;
+        }
+        md += `\n---\n\n`;
+        // 问题描述
+        md += `## 问题描述\n\n${report.description}\n\n`;
+        // 问题类型
+        md += `## 问题类型\n\n\`${report.problemType}\`\n\n`;
+        if (report.relatedTaskId) {
+            md += `**关联任务**: ${report.relatedTaskId}\n\n`;
+        }
+        // 诊断结果
+        md += `## 诊断结果\n\n`;
+        md += `### 根因\n\n${report.rootCause}\n\n`;
+        if (report.errorInfo) {
+            md += `### 错误信息\n\n`;
+            md += `\`\`\`\n${report.errorInfo.message}\n\`\`\`\n\n`;
+            if (report.errorInfo.stack) {
+                md += `### 错误栈\n\n\`\`\`\n${report.errorInfo.stack}\n\`\`\`\n\n`;
+            }
+        }
+        // 影响范围
+        if (report.impactScope.length > 0) {
+            md += `### 影响范围\n\n`;
+            report.impactScope.forEach((item) => { md += `- ${item}\n`; });
+            md += `\n`;
+        }
+        // 相关文件
+        if (report.relatedFiles && report.relatedFiles.length > 0) {
+            md += `### 相关文件\n\n`;
+            report.relatedFiles.forEach((file) => { md += `- \`${file}\`\n`; });
+            md += `\n`;
+        }
+        // 修复建议
+        md += `## 修复建议\n\n${report.suggestedFix}\n\n`;
+        // 修复操作
+        if (fixResult) {
+            md += `## 修复操作\n\n`;
+            if (fixResult.success) {
+                md += `✅ 修复成功\n\n`;
+            }
+            else {
+                md += `❌ 修复未完全生效\n\n`;
+            }
+            if (fixResult.modifiedFiles.length > 0) {
+                md += `### 修改文件\n\n`;
+                fixResult.modifiedFiles.forEach((file) => { md += `- \`${file}\`\n`; });
+                md += `\n`;
+            }
+            if (fixResult.operations.length > 0) {
+                md += `### 执行操作\n\n`;
+                fixResult.operations.forEach((op) => { md += `- ${op}\n`; });
+                md += `\n`;
+            }
+        }
+        // 验证结果
+        if (verifyResult) {
+            md += `## 验证结果\n\n`;
+            if (verifyResult.passed) {
+                md += `✅ 验证通过\n\n`;
+            }
+            else {
+                md += `❌ 验证未通过\n\n`;
+            }
+            md += `${verifyResult.details}\n\n`;
+        }
+        // 重试信息
+        if (session.retryCount > 0) {
+            md += `## 重试信息\n\n已尝试 ${session.retryCount} 次修复\n\n`;
+            if (session.retryCount >= 3) {
+                md += `⚠️ **已尝试 3 次以上修复，建议暂停并质疑架构**\n\n`;
+            }
+        }
+        return md;
+    }
+    /**
+     * 列出所有诊断报告
+     */
+    listReports() {
+        if (!fs.existsSync(this.debugDir))
+            return [];
+        const files = fs.readdirSync(this.debugDir)
+            .filter(f => f.endsWith('-report.md') || f.includes('-report-'))
+            .sort()
+            .reverse();
+        return files.map(f => ({
+            id: f.split('-')[0],
+            path: path.join(this.debugDir, f),
+            createdAt: f
+        }));
+    }
+    ensureDir() {
+        if (!fs.existsSync(this.debugDir)) {
+            fs.mkdirSync(this.debugDir, { recursive: true });
+        }
+    }
+}
+exports.DebugReporter = DebugReporter;

package/dist/orchestrator/problem-detector.d.ts

@@ -0,0 +1,15 @@
+import type { ProblemType } from '../types/index.js';
+export interface ProblemDetectionConfig {
+    description?: string;
+    taskId?: string;
+    taskError?: string | null;
+}
+/**
+ * 判断问题类型的检测器
+ */
+export declare class ProblemDetector {
+    /**
+     * 根据配置判断问题类型
+     */
+    detect(config: ProblemDetectionConfig): Promise<ProblemType>;
+}

package/dist/orchestrator/problem-detector.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProblemDetector = void 0;
+/**
+ * 判断问题类型的检测器
+ */
+class ProblemDetector {
+    /**
+     * 根据配置判断问题类型
+     */
+    async detect(config) {
+        // 有任务 ID 且任务失败
+        if (config.taskId && config.taskError) {
+            return 'task_failure';
+        }
+        // 根据描述判断
+        if (config.description) {
+            const desc = config.description.toLowerCase();
+            // 环境相关关键词
+            const envKeywords = [
+                '依赖', '安装', '环境', '配置', 'npm install', 'node_modules',
+                'env', 'environment', 'dependency', 'install', 'config',
+                'path', '版本', 'version', '权限', 'permission'
+            ];
+            // 项目代码相关关键词
+            const projectKeywords = [
+                '接口', 'api', '函数', 'function', '返回', 'response',
+                '数据', 'data', '逻辑', 'logic', '页面', 'page',
+                '组件', 'component', '样式', 'style', '渲染', 'render'
+            ];
+            // 系统/OpenMatrix 相关关键词
+            const systemKeywords = [
+                'openmatrix', 'cli', '命令', 'command', '状态', 'state',
+                '任务', 'task', '编排', 'orchestrat', 'agent', '技能', 'skill'
+            ];
+            const hasEnvKeyword = envKeywords.some(kw => desc.includes(kw));
+            const hasProjectKeyword = projectKeywords.some(kw => desc.includes(kw));
+            const hasSystemKeyword = systemKeywords.some(kw => desc.includes(kw));
+            // 优先级：环境 > 项目 > 系统
+            if (hasEnvKeyword)
+                return 'environment';
+            if (hasProjectKeyword)
+                return 'project_bug';
+            if (hasSystemKeyword)
+                return 'system_bug';
+        }
+        // 默认：系统 bug
+        return 'system_bug';
+    }
+}
+exports.ProblemDetector = ProblemDetector;

package/dist/types/index.d.ts

@@ -267,3 +267,47 @@ export interface ResearchSession {
     createdAt: string;
     completedAt?: string;
 }
+/** 问题类型 */
+export type ProblemType = 'task_failure' | 'project_bug' | 'system_bug' | 'environment';
+/** 诊断报告 */
+export interface DiagnosisReport {
+    id: string;
+    problemType: ProblemType;
+    trigger: 'explicit' | 'auto';
+    description: string;
+    errorInfo?: {
+        message: string;
+        stack?: string;
+        timestamp: string;
+    };
+    relatedTaskId?: string;
+    relatedFiles?: string[];
+    rootCause: string;
+    impactScope: string[];
+    suggestedFix: string;
+    diagnosedAt: string;
+    diagnosisDuration?: number;
+}
+/** 调试会话状态 */
+export type DebugStatus = 'initialized' | 'diagnosing' | 'awaiting_fix' | 'fixing' | 'verifying' | 'completed' | 'cancelled';
+/** 调试会话 */
+export interface DebugSession {
+    id: string;
+    status: DebugStatus;
+    report: DiagnosisReport;
+    fixDecision?: 'approve' | 'skip' | 'manual';
+    fixResult?: {
+        success: boolean;
+        operations: string[];
+        modifiedFiles: string[];
+        output: string;
+    };
+    verifyResult?: {
+        passed: boolean;
+        details: string;
+    };
+    retryCount: number;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmatrix",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "AI Agent task orchestration system with Claude Code Skills integration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/debug.md

@@ -0,0 +1,425 @@
+---
+name: om:debug
+description: 系统化调试 - 遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行
+priority: high
+---
+
+<NO-OTHER-SKILLS>
+**绝对禁止**调用以下技能：
+- ❌ superpowers:systematic-debugging → 你已经在 om:debug 中了
+- ❌ superpowers:* → 全部被 OpenMatrix 替代
+- ❌ gsd:* → 全部被 OpenMatrix 替代
+- ❌ 任何其他任务编排相关的技能
+
+**诊断和修复阶段只能使用 Agent 工具** — 直接调用 Agent，不通过任何中间层。
+</NO-OTHER-SKILLS>
+
+<MANDATORY-EXECUTION-ORDER>
+## 执行顺序 - 必须严格按此顺序，不得跳过
+
+```
+Step 1:  接收问题描述（参数、指定任务、或询问用户）
+Step 2:  调用 CLI: openmatrix debug 初始化会话
+Step 3:  第一阶段：根因调查（Explore Agent）
+Step 4:  第二阶段：模式分析（Explore Agent）
+Step 5:  展示诊断报告 + 修复建议
+Step 6:  AskUserQuestion 确认修复策略
+Step 7:  第四阶段：实施修复（Agent）
+Step 8:  验证修复结果
+Step 9:  写入 Debug Report 并展示
+```
+
+**铁律：不做根因调查，不许提修复方案**
+</MANDATORY-EXECUTION-ORDER>
+
+<objective>
+系统化调试 - 通过四阶段流程诊断和修复问题。不依赖任务流程，可独立使用。
+</objective>
+
+<process>
+
+## Step 1: 接收问题
+
+**检查 `$ARGUMENTS`:**
+
+| 参数 | 处理方式 |
+|------|---------|
+| `--task TASK-XXX` | 读取指定失败任务 |
+| `<问题描述>` | 直接使用描述 |
+| 空 | 询问用户问题描述 |
+
+**如果是空参数，询问：**
+
+AskUserQuestion: `header: "问题描述"`, `multiSelect: false`
+**question:** 请描述你遇到的问题
+
+| label | description |
+|-------|-------------|
+| 描述问题 | 输入自由文本描述 |
+| 选择失败任务 | 从当前失败任务中选择 |
+| 取消 | 退出调试模式 |
+
+**如果有失败任务（检查 .openmatrix/state.json）：**
+```bash
+cat .openmatrix/state.json 2>/dev/null | grep -o '"failed":[0-9]*'
+```
+如果 `statistics.failed > 0`，读取 `.openmatrix/tasks/` 目录找到 failed 任务并展示。
+
+## Step 2: 调用 CLI 初始化
+
+**带任务 ID：**
+```bash
+openmatrix debug --task TASK-XXX --json
+```
+
+**带描述：**
+```bash
+openmatrix debug "问题描述" --json
+```
+
+CLI 返回：
+```json
+{
+  "sessionId": "DEBUG-xxx",
+  "status": "diagnosing",
+  "problemType": "task_failure",
+  "report": {
+    "description": "...",
+    "relatedTaskId": "TASK-003",
+    "relatedFiles": ["src/xxx.ts"]
+  }
+}
+```
+
+从返回结果中读取 `sessionId`，后续步骤使用此 ID。
+
+## Step 3: 第一阶段 - 根因调查
+
+**调用 Explore Agent：**
+
+```typescript
+Agent({
+  subagent_type: "Explore",
+  description: "根因调查 - 第一阶段",
+  prompt: `你是调试专家。正在进行系统化调试的第一阶段：根因调查。
+
+**铁律：在找到根因之前，不要提出任何修复方案。**
+
+## 问题信息
+- 问题类型: ${problemType}
+- 问题描述: ${description}
+${relatedTaskId ? `- 关联任务: ${relatedTaskId}` : ''}
+
+## 任务
+1. 仔细阅读所有错误信息（不要跳过任何警告或错误）
+2. 收集相关文件和日志
+3. 检查近期代码变更（git diff、最近提交）
+4. 如果有多个组件，追踪数据流，找到断裂点
+5. 定位问题根源
+
+## 输出格式
+请按以下格式输出：
+
+### 错误信息
+- 错误类型: ...
+- 错误位置: 文件:行号
+- 错误详情: ...
+
+### 复现步骤
+1. ...
+
+### 近期变更
+- 提交1: 描述
+- 提交2: 描述
+
+### 根因分析
+[详细描述问题根源]
+
+### 影响范围
+- 文件1
+- 文件2
+
+## 禁止行为
+❌ 提出修复方案
+❌ 修改任何文件
+❌ 做出未经证实的假设`,
+  run_in_background: false
+})
+```
+
+## Step 4: 第二阶段 - 模式分析
+
+**调用 Explore Agent：**
+
+```typescript
+Agent({
+  subagent_type: "Explore",
+  description: "模式分析 - 第二阶段",
+  prompt: `继续进行系统化调试的第二阶段：模式分析。
+
+## 第一阶段发现
+
+${第一阶段根因调查的完整输出}
+
+## 任务
+1. 在代码库中找到类似的、正常工作的代码
+2. 对比正常代码和异常代码的差异
+3. 列出所有差异点（无论多小）
+4. 理解功能依赖关系和隐含假设
+
+## 输出格式
+
+### 正常示例
+- 文件: path:line
+- 说明: 为什么这段代码能正常工作
+
+### 差异点
+1. 差异1: 正常代码 vs 异常代码
+2. 差异2: ...
+
+### 依赖关系
+- 需要哪些前置条件
+- 有哪些隐含假设`,
+  run_in_background: false
+})
+```
+
+## Step 5: 展示诊断报告
+
+**第一阶段和第二阶段完成后，展示诊断报告：**
+
+```
+🔍 诊断报告
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+问题类型: xxx
+
+根因分析
+  [来自第一阶段调查的根因描述]
+
+正常示例
+  文件: path:line
+  说明: ...
+
+差异点
+  1. ...
+  2. ...
+
+影响范围
+  - 文件1
+  - 文件2
+
+修复建议
+  [基于差异分析的具体修复建议]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Step 6: 确认修复策略
+
+AskUserQuestion: `header: "修复策略"`, `multiSelect: false`
+**question:** 诊断完成，选择修复策略？
+
+| label | description |
+|-------|-------------|
+| 自动修复 (推荐) | 调用 Agent 执行修复 |
+| 手动修复 | 仅展示建议，用户自行修复 |
+| 跳过 | 不修复，仅记录诊断报告 |
+| 继续深入 | 根因不够清晰，继续调查 |
+
+**用户选择 "继续深入"** → 回到 Step 3，带着新信息重新调查。
+
+## Step 7: 实施修复
+
+**如果用户选择自动修复：**
+
+**修复前安全检查（必须执行）：**
+```bash
+git status --porcelain
+git log --oneline -5
+```
+
+```typescript
+Agent({
+  subagent_type: "general-purpose",
+  description: "实施 bug 修复",
+  prompt: `根据诊断报告执行修复。
+
+## 铁律
+1. 只实施单一修复（不要做额外改动）
+2. 每次只改一个变量
+3. 不在诊断不清的情况下盲目尝试
+4. 不做"顺便"的重构
+
+## 诊断报告
+${诊断报告全文}
+
+## 修复建议
+${suggestedFix}
+
+## 任务
+1. 根据修复建议实施修改
+2. 确保修改范围最小化
+3. 完成后输出修改了哪些文件和具体改动
+
+## 禁止行为
+❌ 修改与修复无关的文件
+❌ 进行额外的重构
+❌ 同时修复多个问题`,
+  run_in_background: false
+})
+```
+
+**Agent 完成后：**
+1. 检查 Git 状态
+2. 提交修复（如果文件有变更）
+3. 进入 Step 8 验证
+
+## Step 8: 验证修复
+
+**根据问题类型选择验证方式：**
+
+| 问题类型 | 验证方式 |
+|---------|---------|
+| task_failure | 重新运行失败任务或相关测试 |
+| project_bug | 运行相关测试或构建 |
+| system_bug | 验证 CLI 功能 |
+| environment | 检查依赖安装状态 |
+
+**任务失败：**
+```bash
+# 运行相关测试
+npm test -- --run 2>&1 | tail -20
+```
+
+**项目 bug：**
+```bash
+npm run build 2>&1 | tail -10
+```
+
+**环境：**
+```bash
+npm ls --depth=0 2>&1 | tail -20
+```
+
+**验证结果判断：**
+- 测试全通过 / 构建成功 → 验证通过
+- 仍有失败 / 构建失败 → 验证未通过
+
+AskUserQuestion: `header: "验证结果"`, `multiSelect: false`
+**question:** 修复验证通过了吗？
+
+| label | description |
+|-------|-------------|
+| 通过 | 修复成功，记录报告 |
+| 未通过 | 修复未生效，重新分析 |
+| 部分通过 | 部分修复，继续诊断 |
+
+**如果验证未通过：**
+- 重试计数 +1
+- **< 3 次** → 回到 Step 3（带着新信息重新分析）
+- **>= 3 次** → 输出"已尝试 3 次以上修复，建议暂停并质疑架构"，进入 Step 9
+
+## Step 9: 写入 Debug Report
+
+完成调试会话：
+```bash
+openmatrix debug --list
+```
+
+**生成诊断报告文件（在界面输出）：**
+
+```markdown
+# Debug Report
+
+**会话 ID**: ${sessionId}
+**日期**: ${timestamp}
+**状态**: ${status}
+
+## 问题描述
+${description}
+
+## 问题类型
+${problemType}
+
+## 诊断结果
+### 根因
+${rootCause}
+
+### 影响范围
+${impactScope}
+
+## 修复操作
+${operations}
+
+## 验证结果
+${verifyResult}
+
+## 经验教训
+${lessons}
+```
+
+**Git 提交修复（如果有文件变更）：**
+```bash
+git status --porcelain
+# 如果有未提交文件：
+git add -A && git commit -m "$(cat <<'EOF'
+fix: 修复 bug - 问题描述
+
+根因: ...
+修复: ...
+
+影响范围: ...
+文件改动: ...
+
+Co-Authored-By: OpenMatrix https://github.com/bigfish1913/openmatrix
+EOF
+)"
+```
+
+</process>
+
+<arguments>
+$ARGUMENTS
+</arguments>
+
+<examples>
+/om:debug                          # 交互式调试
+/om:debug --task TASK-003          # 调试指定失败任务
+/om:debug "API 返回 500 错误"      # 带问题描述调试
+</examples>
+
+<notes>
+## 四阶段流程
+
+```
+Step 1: 接收问题
+    ↓
+Step 2: CLI 初始化会话
+    ↓
+Step 3: 第一阶段 - 根因调查（只读）
+    ↓
+Step 4: 第二阶段 - 模式分析（只读）
+    ↓
+Step 5: 展示诊断报告 + 修复建议
+    ↓
+Step 6: AskUserQuestion 确认修复策略
+    ↓
+Step 7: 第三/四阶段 - 实施修复
+    ↓
+Step 8: 验证修复结果
+    ↓
+Step 9: 写入 Debug Report
+```
+
+## 铁律
+
+**不做根因调查，不许提修复方案**
+
+## 红线
+
+- 3 次修复失败 → 暂停，质疑架构
+- 不修改未关联的文件
+- 单一修复原则
+- 修复前必须有验证方法
+</notes>

package/skills/om.md

@@ -82,6 +82,7 @@ OpenMatrix 默认入口 — 用户无需记忆命令，直接描述任务即可
      /om:status      - View status
      /om:meeting     - Handle blockers
      /om:report      - Generate report
+     /om:debug       - Systematic debugging (bug/error investigation)
    ```
 </process>
 
@@ -99,5 +100,5 @@ $ARGUMENTS
 
 <notes>
 `/om` is shorthand for the OpenMatrix workflow. Same skill set as `openmatrix`, shorter invocation.
-Available commands: `/om:brainstorm`, `/om:start`, `/om:auto`, `/om:status`, `/om:meeting`, `/om:report`, `/om:resume`, `/om:retry`, `/om:research`, `/om:approve`, `/om:check`
+Available commands: `/om:brainstorm`, `/om:start`, `/om:auto`, `/om:status`, `/om:meeting`, `/om:report`, `/om:resume`, `/om:retry`, `/om:research`, `/om:approve`, `/om:check`, `/om:debug`
 </notes>