openmatrix 0.2.14 → 0.2.16

package/dist/agents/agent-runner.d.ts

@@ -67,6 +67,10 @@ export declare class AgentRunner {
      * 构建完整的执行提示词
      */
     buildExecutionPrompt(task: Task): Promise<string>;
+    /**
+     * 构建歧义检测指令
+     */
+    private buildAmbiguityDetectionInstruction;
     /**
      * 构建累积上下文 - 从全局 context.md 读取前序 Agent 的决策和知识
      */

package/dist/agents/agent-runner.js

@@ -136,8 +136,11 @@ class AgentRunner {
         const agentPrompt = this.buildAgentPrompt(task);
         const phaseContext = this.buildPhaseContext(task);
         const accumulatedContext = await this.buildAccumulatedContext(task);
+        const ambiguityInstruction = this.buildAmbiguityDetectionInstruction(task);
         return `# 任务执行
 
+${ambiguityInstruction}
+
 ## 任务信息
 - ID: ${task.id}
 - 标题: ${task.title}
@@ -172,6 +175,89 @@ ${agentPrompt.instructions}
 注意: 任务完成后，由 Skill 调用 \`openmatrix complete\` 并传入 --summary 参数，
 该摘要会自动追加到全局 \`.openmatrix/context.md\` 供后续 Agent 参考。
 `;
+    }
+    /**
+     * 构建歧义检测指令
+     */
+    buildAmbiguityDetectionInstruction(task) {
+        return `## 🚨 歧义检测指令（必须在执行前完成）
+
+在开始执行任务之前，你必须完成歧义检测。检测以下 5 种歧义类型：
+
+### 检测清单
+
+1. **需求歧义** (requirement)
+   - 任务描述是否清晰可理解？
+   - 是否有缺少的关键信息？
+   - 验收标准是否明确？
+
+2. **技术歧义** (technical)
+   - 技术选型是否明确？
+   - 实现方案是否有多种选择？
+   - 是否需要特定的技术决策？
+
+3. **依赖歧义** (dependency)
+   - 依赖任务是否已完成？
+   - 依赖代码是否可找到？
+   - 是否有缺失的依赖项？
+
+4. **验收歧义** (acceptance)
+   - 验收标准是否明确？
+   - 成功定义是否清晰？
+   - 是否有模糊的边界条件？
+
+5. **测试结果歧义** (test_result)
+   - 测试失败原因是否明确？
+   - 测试通过是否可信？
+   - 是否需要额外的验证？
+
+### 严重程度定义
+
+| 级别 | 说明 | 处理方式 |
+|-----|------|---------|
+| **Critical** | 无法继续执行，必须澄清 | 立即报告，等待澄清 |
+| **High** | 可能导致错误结果 | 报告并建议处理方案 |
+| **Medium** | 影响执行效率 | 记录并尝试解决 |
+| **Low** | 轻微不确定性 | 继续执行，备注说明 |
+
+### 输出格式
+
+如果检测到歧义，在任务执行前输出：
+\`\`\`xml
+<ambiguity_report>
+{
+  "hasAmbiguity": true,
+  "taskId": "${task.id}",
+  "detectionPhase": "pre_execution",
+  "ambiguities": [
+    {
+      "type": "requirement|technical|dependency|acceptance|test_result",
+      "severity": "Critical|High|Medium|Low",
+      "description": "歧义描述",
+      "suggestedResolution": "建议的处理方案"
+    }
+  ],
+  "maxSeverity": "Critical|High|Medium|Low",
+  "suggestedStrategy": "ask_immediate|write_meeting|continue",
+  "detectedAt": "<ISO timestamp>"
+}
+</ambiguity_report>
+\`\`\`
+
+如果没有歧义，输出：
+\`\`\`xml
+<ambiguity_report>
+{ "hasAmbiguity": false }
+</ambiguity_report>
+\`\`\`
+
+### 处理策略
+
+- **Critical/High**: 输出报告后暂停，等待用户决策
+- **Medium**: 输出报告后继续执行，采用合理假设
+- **Low**: 记录并继续执行
+
+**重要**: 如果无法解析歧义检测结果，视为无歧义继续执行。`;
     }
     /**
      * 构建累积上下文 - 从全局 context.md 读取前序 Agent 的决策和知识

package/dist/orchestrator/executor.d.ts

@@ -4,6 +4,7 @@ import type { SubagentTask } from '../types/index.js';
 import { StateManager } from '../storage/state-manager.js';
 import { ApprovalManager } from './approval-manager.js';
 import { PhaseExecutor } from './phase-executor.js';
+import type { AmbiguityReport } from '../types/index.js';
 export interface ExecutorConfig {
     maxConcurrent: number;
     taskTimeout: number;
@@ -16,7 +17,7 @@ export interface ExecutorStatus {
     waitingApprovals: number;
 }
 export interface ExecutionResult {
-    status: 'continue' | 'waiting_approval' | 'completed' | 'failed';
+    status: 'continue' | 'waiting_approval' | 'completed' | 'failed' | 'ambiguity_ask_user';
     subagentTasks: SubagentTask[];
     message: string;
     statistics: {
@@ -26,6 +27,8 @@ export interface ExecutionResult {
         pending: number;
         failed: number;
     };
+    /** 歧义报告 (仅 status 为 'ambiguity_ask_user' 时存在) */
+    ambiguityReport?: AmbiguityReport;
 }
 /**
  * OrchestratorExecutor - 执行循环核心
@@ -41,6 +44,7 @@ export declare class OrchestratorExecutor {
     private phaseExecutor;
     private retryManager;
     private aiReviewer;
+    private meetingManager;
     private config;
     private taskTimers;
     constructor(stateManager: StateManager, approvalManager: ApprovalManager, config?: Partial<ExecutorConfig>);
@@ -94,7 +98,9 @@ export declare class OrchestratorExecutor {
     /**
      * 标记任务完成
      *
-     * 增强：对于 reviewer 任务，自动解析 Review 报告并生成修复任务
+     * 增强：
+     * 1. 对于 reviewer 任务，自动解析 Review 报告并生成修复任务
+     * 2. 解析歧义报告并根据执行模式处理
      */
     completeTask(taskId: string, result: {
         success: boolean;
@@ -102,6 +108,10 @@ export declare class OrchestratorExecutor {
         error?: string;
     }): Promise<{
         createdFixTasks?: string[];
+        ambiguityResult?: {
+            status: 'ambiguity_ask_user' | 'ambiguity_handled';
+            report: AmbiguityReport;
+        };
     }>;
     /**
      * 处理 Review 结果：解析报告，如有 critical/major 问题则自动创建修复任务
@@ -111,6 +121,26 @@ export declare class OrchestratorExecutor {
      * 获取当前阶段
      */
     private getCurrentPhase;
+    /**
+     * 解析歧义报告
+     *
+     * 从 Agent 输出中提取歧义报告 JSON
+     * 支持多种标记格式：
+     * - <ambiguity_report>...</ambiguity_report>
+     * - AMBIGUITY_REPORT: {...}
+     * - 直接 JSON 块
+     */
+    private parseAmbiguityReport;
+    /**
+     * 处理歧义
+     *
+     * 根据执行模式和严重程度选择处理策略：
+     * - auto 模式：所有歧义写入 Meeting，继续执行
+     * - 其他模式：
+     *   - Critical/High：返回 ambiguity_ask_user 状态，让 Skill 层用 AskUserQuestion 处理
+     *   - Medium/Low：写入 Meeting，继续执行
+     */
+    private handleAmbiguity;
     /**
      * 获取执行器状态
      */

package/dist/orchestrator/executor.js

@@ -8,6 +8,7 @@ const state_machine_js_1 = require("./state-machine.js");
 const phase_executor_js_1 = require("./phase-executor.js");
 const retry_manager_js_1 = require("./retry-manager.js");
 const ai_reviewer_js_1 = require("./ai-reviewer.js");
+const meeting_manager_js_1 = require("./meeting-manager.js");
 const logger_js_1 = require("../utils/logger.js");
 /**
  * OrchestratorExecutor - 执行循环核心
@@ -23,11 +24,13 @@ class OrchestratorExecutor {
     phaseExecutor;
     retryManager;
     aiReviewer;
+    meetingManager;
     config;
     taskTimers = new Map();
     constructor(stateManager, approvalManager, config) {
         this.stateManager = stateManager;
         this.approvalManager = approvalManager;
+        this.meetingManager = new meeting_manager_js_1.MeetingManager(stateManager, approvalManager);
         // 从 state.config 读取 taskTimeout，如果未定义则使用默认值
         const stateConfig = stateManager.getState().then(s => s.config).catch(() => null);
         const defaultTaskTimeout = 600000; // 10 分钟（毫秒）
@@ -265,13 +268,25 @@ class OrchestratorExecutor {
     /**
      * 标记任务完成
      *
-     * 增强：对于 reviewer 任务，自动解析 Review 报告并生成修复任务
+     * 增强：
+     * 1. 对于 reviewer 任务，自动解析 Review 报告并生成修复任务
+     * 2. 解析歧义报告并根据执行模式处理
      */
     async completeTask(taskId, result) {
         const task = await this.stateManager.getTask(taskId);
         if (!task) {
             throw new Error(`Task ${taskId} not found`);
         }
+        // 检查输出中是否包含歧义报告（仅匹配 XML 标签作为唯一触发标记）
+        if (result.output?.includes('<ambiguity_report>')) {
+            const ambiguityReport = this.parseAmbiguityReport(taskId, result.output);
+            if (ambiguityReport?.hasAmbiguity) {
+                const ambiguityResult = await this.handleAmbiguity(task, ambiguityReport);
+                if (ambiguityResult) {
+                    return { ambiguityResult };
+                }
+            }
+        }
         if (result.success) {
             // 清除超时计时器
             this.clearTaskTimeout(taskId);
@@ -370,6 +385,109 @@ class OrchestratorExecutor {
             return 'verify';
         return 'accept';
     }
+    // ============ Ambiguity Management ============
+    /**
+     * 解析歧义报告
+     *
+     * 从 Agent 输出中提取歧义报告 JSON
+     * 支持多种标记格式：
+     * - <ambiguity_report>...</ambiguity_report>
+     * - AMBIGUITY_REPORT: {...}
+     * - 直接 JSON 块
+     */
+    parseAmbiguityReport(taskId, output) {
+        try {
+            // 尝试提取 XML 标记格式
+            const xmlMatch = output.match(/<ambiguity_report>([\s\S]*?)<\/ambiguity_report>/);
+            if (xmlMatch) {
+                const jsonStr = xmlMatch[1].trim();
+                const report = JSON.parse(jsonStr);
+                return { ...report, taskId };
+            }
+            // 尝试提取 AMBIGUITY_REPORT: 格式
+            const prefixMatch = output.match(/AMBIGUITY_REPORT:\s*([\s\S]*?)(?:\n\n|\n---|$)/);
+            if (prefixMatch) {
+                const jsonStr = prefixMatch[1].trim();
+                const report = JSON.parse(jsonStr);
+                return { ...report, taskId };
+            }
+            // 尝试查找包含 hasAmbiguity 的 JSON 块（平衡括号匹配，作为最后兜底）
+            const hasAmbiguityIdx = output.indexOf('"hasAmbiguity"');
+            if (hasAmbiguityIdx !== -1) {
+                // 向前扫描找到深度为 1 的最外层 {
+                let start = -1;
+                let depth = 0;
+                for (let i = hasAmbiguityIdx; i >= 0; i--) {
+                    if (output[i] === '}')
+                        depth++;
+                    else if (output[i] === '{') {
+                        depth--;
+                        if (depth < 0) {
+                            start = i;
+                            break;
+                        }
+                    }
+                }
+                if (start !== -1) {
+                    let d = 0;
+                    let end = -1;
+                    for (let i = start; i < output.length; i++) {
+                        if (output[i] === '{')
+                            d++;
+                        else if (output[i] === '}') {
+                            d--;
+                            if (d === 0) {
+                                end = i;
+                                break;
+                            }
+                        }
+                    }
+                    if (end !== -1) {
+                        const report = JSON.parse(output.slice(start, end + 1));
+                        return { ...report, taskId };
+                    }
+                }
+            }
+            return null;
+        }
+        catch (error) {
+            console.warn(`⚠️ 解析歧义报告失败: ${taskId}`, error);
+            return null;
+        }
+    }
+    /**
+     * 处理歧义
+     *
+     * 根据执行模式和严重程度选择处理策略：
+     * - auto 模式：所有歧义写入 Meeting，继续执行
+     * - 其他模式：
+     *   - Critical/High：返回 ambiguity_ask_user 状态，让 Skill 层用 AskUserQuestion 处理
+     *   - Medium/Low：写入 Meeting，继续执行
+     */
+    async handleAmbiguity(task, report) {
+        const state = await this.stateManager.getState();
+        const mode = state.config.approvalPoints.length === 0 ? 'auto' : 'interactive';
+        console.log(`🔍 检测到歧义: ${task.id} - 最高严重程度: ${report.maxSeverity || 'unknown'}`);
+        // auto 模式：所有歧义写入 Meeting，继续执行
+        if (mode === 'auto') {
+            await this.meetingManager.createAmbiguityMeeting(task.id, report);
+            console.log(`📝 [auto模式] 歧义已写入 Meeting，继续执行`);
+            return { status: 'ambiguity_handled', report };
+        }
+        // 其他模式：根据严重程度处理
+        const severity = report.maxSeverity;
+        if (severity === 'critical' || severity === 'high') {
+            // Critical/High: 返回特殊状态让 Skill 层用 AskUserQuestion 处理
+            console.log(`⚠️ [interactive模式] Critical/High 歧义，需用户确认`);
+            return { status: 'ambiguity_ask_user', report };
+        }
+        else {
+            // Medium/Low: 写入 Meeting，继续执行
+            await this.meetingManager.createAmbiguityMeeting(task.id, report);
+            console.log(`📝 [interactive模式] Medium/Low 歧义已写入 Meeting，继续执行`);
+            return { status: 'ambiguity_handled', report };
+        }
+    }
     /**
      * 获取执行器状态
      */

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

@@ -1,6 +1,6 @@
 import { StateManager } from '../storage/state-manager.js';
 import { ApprovalManager } from './approval-manager.js';
-import type { Approval, Meeting } from '../types/index.js';
+import type { Approval, Meeting, AmbiguityReport } from '../types/index.js';
 /**
  * MeetingManager - Meeting 管理器
  *
@@ -28,6 +28,21 @@ export declare class MeetingManager {
         meeting: Meeting;
         approval: Approval;
     }>;
+    /**
+     * 获取严重程度对应的图标和标题前缀
+     */
+    private getSeverityPrefix;
+    /**
+     * 格式化歧义报告为 Markdown 描述
+     */
+    private formatAmbiguityReport;
+    /**
+     * 创建歧义 Meeting
+     */
+    createAmbiguityMeeting(taskId: string, ambiguityReport: AmbiguityReport): Promise<{
+        meeting: Meeting;
+        approval: Approval;
+    }>;
     /**
      * 开始 Meeting
      */

package/dist/orchestrator/meeting-manager.js

@@ -104,6 +104,119 @@ ${options.map((opt, i) => `${i + 1}. ${opt}`).join('\n')}
         });
         return { meeting, approval };
     }
+    /**
+     * 获取严重程度对应的图标和标题前缀
+     */
+    getSeverityPrefix(severity) {
+        const prefixes = {
+            critical: '🔴 Critical',
+            high: '🟠 High',
+            medium: '🟡 Medium',
+            low: '🟢 Low'
+        };
+        return prefixes[severity];
+    }
+    /**
+     * 格式化歧义报告为 Markdown 描述
+     */
+    formatAmbiguityReport(report) {
+        const lines = [];
+        lines.push('## 歧义检测结果');
+        lines.push('');
+        lines.push(`**检测阶段**: ${report.detectionPhase === 'pre_execution' ? '执行前' : '执行中'}`);
+        lines.push(`**检测时间**: ${report.detectedAt}`);
+        lines.push(`**歧义数量**: ${report.ambiguities.length}`);
+        if (report.maxSeverity) {
+            lines.push(`**最高严重程度**: ${this.getSeverityPrefix(report.maxSeverity)}`);
+        }
+        lines.push('');
+        lines.push('## 歧义详情');
+        lines.push('');
+        for (const ambiguity of report.ambiguities) {
+            const severityIcon = this.getSeverityPrefix(ambiguity.severity);
+            lines.push(`### ${severityIcon} ${ambiguity.type}`);
+            lines.push('');
+            lines.push(`**描述**: ${ambiguity.description}`);
+            lines.push('');
+            if (ambiguity.impactScope.length > 0) {
+                lines.push('**影响范围**:');
+                for (const scope of ambiguity.impactScope) {
+                    lines.push(`- ${scope}`);
+                }
+                lines.push('');
+            }
+            if (ambiguity.possibleSolutions && ambiguity.possibleSolutions.length > 0) {
+                lines.push('**可能的解决方案**:');
+                for (let i = 0; i < ambiguity.possibleSolutions.length; i++) {
+                    lines.push(`${i + 1}. ${ambiguity.possibleSolutions[i]}`);
+                }
+                lines.push('');
+            }
+            if (ambiguity.relatedFiles && ambiguity.relatedFiles.length > 0) {
+                lines.push(`**相关文件**: ${ambiguity.relatedFiles.join(', ')}`);
+                lines.push('');
+            }
+            if (ambiguity.relatedTaskIds && ambiguity.relatedTaskIds.length > 0) {
+                lines.push(`**相关任务**: ${ambiguity.relatedTaskIds.join(', ')}`);
+                lines.push('');
+            }
+        }
+        if (report.suggestedStrategy) {
+            lines.push('## 建议处理策略');
+            lines.push('');
+            const strategyMap = {
+                ask_immediate: '立即提问 (ask_immediate)',
+                write_meeting: '写入 Meeting (write_meeting)',
+                continue: '继续执行 (continue)'
+            };
+            lines.push(strategyMap[report.suggestedStrategy] || report.suggestedStrategy);
+            lines.push('');
+        }
+        if (report.suggestedQuestions && report.suggestedQuestions.length > 0) {
+            lines.push('## 建议的问题');
+            lines.push('');
+            for (let i = 0; i < report.suggestedQuestions.length; i++) {
+                lines.push(`${i + 1}. ${report.suggestedQuestions[i]}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * 创建歧义 Meeting
+     */
+    async createAmbiguityMeeting(taskId, ambiguityReport) {
+        const meetingId = `meeting-${Date.now().toString(36)}`;
+        const now = new Date().toISOString();
+        // 根据最高严重程度生成标题
+        const severity = ambiguityReport.maxSeverity || 'medium';
+        const severityPrefix = this.getSeverityPrefix(severity);
+        const titleSummary = ambiguityReport.ambiguities[0]?.description.slice(0, 50) || '歧义检测';
+        const meeting = {
+            id: meetingId,
+            type: 'ambiguity',
+            status: 'pending',
+            taskId,
+            title: `${severityPrefix}: ${titleSummary}...`,
+            description: `任务 ${taskId} 检测到歧义，需要用户确认处理方式`,
+            impactScope: ambiguityReport.ambiguities.flatMap(a => a.impactScope),
+            participants: ['user'],
+            createdAt: now,
+            ambiguityReport,
+            suggestedQuestions: ambiguityReport.suggestedQuestions
+        };
+        // 保存 Meeting
+        await this.stateManager.saveMeeting(meeting);
+        // 创建审批
+        const approval = await this.approvalManager.createApproval({
+            type: 'meeting',
+            taskId,
+            title: meeting.title,
+            description: this.formatAmbiguityReport(ambiguityReport),
+            content: JSON.stringify({ meetingId, ambiguityReport })
+        });
+        return { meeting, approval };
+    }
     /**
      * 开始 Meeting
      */

package/dist/types/index.d.ts

@@ -204,7 +204,7 @@ export interface ApprovalOption {
     label: string;
 }
 export type MeetingStatus = 'pending' | 'in_progress' | 'resolved' | 'cancelled';
-export type MeetingType = 'blocking' | 'decision' | 'review' | 'planning';
+export type MeetingType = 'blocking' | 'decision' | 'review' | 'planning' | 'ambiguity';
 export interface Meeting {
     id: string;
     type: MeetingType;
@@ -219,6 +219,10 @@ export interface Meeting {
     createdAt: string;
     startedAt?: string;
     resolvedAt?: string;
+    /** 歧义报告 (仅 type 为 'ambiguity' 时使用) */
+    ambiguityReport?: AmbiguityReport;
+    /** 建议的问题列表 (用于歧义处理) */
+    suggestedQuestions?: string[];
 }
 export interface ParsedTask {
     title: string;
@@ -311,3 +315,64 @@ export interface DebugSession {
     updatedAt: string;
     completedAt?: string;
 }
+/**
+ * 歧义类型
+ * - requirement: 需求歧义 (需求描述不清晰、存在多种解读)
+ * - technical: 技术歧义 (技术方案选择、实现方式不明确)
+ * - dependency: 依赖歧义 (依赖项版本、接口契约不明确)
+ * - acceptance: 验收歧义 (验收标准不清晰、无法验证)
+ * - test_result: 测试结果歧义 (测试结果不一致、无法判断)
+ */
+export type AmbiguityType = 'requirement' | 'technical' | 'dependency' | 'acceptance' | 'test_result';
+/**
+ * 歧义严重程度
+ * - critical: 严重歧义，必须立即解决，否则任务无法继续
+ * - high: 高优先级歧义，影响核心功能，应尽快解决
+ * - medium: 中等优先级歧义，影响非核心功能，可稍后解决
+ * - low: 低优先级歧义，影响较小，可在后续处理
+ */
+export type AmbiguitySeverity = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * 歧义项 - 描述单个歧义点
+ */
+export interface AmbiguityItem {
+    /** 歧义唯一标识 */
+    id: string;
+    /** 歧义类型 */
+    type: AmbiguityType;
+    /** 严重程度 */
+    severity: AmbiguitySeverity;
+    /** 歧义描述 */
+    description: string;
+    /** 影响范围 */
+    impactScope: string[];
+    /** 可能的解决方案 */
+    possibleSolutions?: string[];
+    /** 相关文件 */
+    relatedFiles?: string[];
+    /** 相关任务 ID */
+    relatedTaskIds?: string[];
+}
+/**
+ * 歧义报告 - Agent 输出的歧义检测结果
+ */
+export interface AmbiguityReport {
+    /** 报告唯一标识 */
+    id: string;
+    /** 关联的任务 ID */
+    taskId: string;
+    /** 检测阶段: 'pre_execution' 执行前 | 'during_execution' 执行中 */
+    detectionPhase: 'pre_execution' | 'during_execution';
+    /** 检测到的歧义列表 */
+    ambiguities: AmbiguityItem[];
+    /** 是否存在歧义 */
+    hasAmbiguity: boolean;
+    /** 最高严重程度 (用于快速判断) */
+    maxSeverity?: AmbiguitySeverity;
+    /** 检测时间 */
+    detectedAt: string;
+    /** 建议的处理策略 */
+    suggestedStrategy?: 'ask_immediate' | 'write_meeting' | 'continue';
+    /** 建议的问题列表 (用于 AskUserQuestion) */
+    suggestedQuestions?: string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmatrix",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "AI Agent task orchestration system with Claude Code Skills integration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -51,6 +51,7 @@
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^8.58.1",
     "@typescript-eslint/parser": "^8.58.1",
+    "@vitest/coverage-v8": "^1.6.1",
     "eslint": "^10.2.0",
     "vitest": "^1.6.0"
   },