@gong-ym/ai-spec-auto 0.2.3

package/src/agent/collaboration-protocol.js

@@ -0,0 +1,333 @@
+/**
+ * Collaboration Protocol — Agent 协作协议
+ *
+ * 定义 Agent 间消息传递、任务分配和状态机管理。
+ * Agent 状态机独立于 Run 状态机。
+ */
+
+const { AGENT_STATES, VALID_AGENT_STATES, ESCALATION_POLICIES } = require('./agent-types');
+
+// ============================================================
+// 状态转换规则
+// ============================================================
+
+/** 合法的状态转换表 */
+const STATE_TRANSITIONS = Object.freeze({
+  [AGENT_STATES.IDLE]: [AGENT_STATES.ASSIGNED],
+  [AGENT_STATES.ASSIGNED]: [AGENT_STATES.EXECUTING, AGENT_STATES.IDLE],
+  [AGENT_STATES.EXECUTING]: [AGENT_STATES.REVIEWING, AGENT_STATES.COMPLETED, AGENT_STATES.FAILED, AGENT_STATES.BLOCKED],
+  [AGENT_STATES.REVIEWING]: [AGENT_STATES.REPAIRING, AGENT_STATES.COMPLETED, AGENT_STATES.FAILED],
+  [AGENT_STATES.REPAIRING]: [AGENT_STATES.EXECUTING, AGENT_STATES.REVIEWING, AGENT_STATES.FAILED, AGENT_STATES.BLOCKED],
+  [AGENT_STATES.BLOCKED]: [AGENT_STATES.ASSIGNED, AGENT_STATES.EXECUTING, AGENT_STATES.FAILED],
+  [AGENT_STATES.COMPLETED]: [],
+  [AGENT_STATES.FAILED]: [AGENT_STATES.ASSIGNED],
+});
+
+// ============================================================
+// AgentState — 单个 Agent 的运行时状态
+// ============================================================
+
+class AgentState {
+  /**
+   * @param {string} agentId
+   * @param {Object} [profile]
+   */
+  constructor(agentId, profile = {}) {
+    this.agentId = agentId;
+    this.profile = profile;
+    this.state = AGENT_STATES.IDLE;
+    this.taskId = null;
+    this.history = [];
+    this.startedAt = null;
+    this.updatedAt = new Date().toISOString();
+    this.metadata = {};
+  }
+
+  /**
+   * 尝试转换状态
+   * @param {string} newState - 目标状态
+   * @param {string} [reason] - 转换原因
+   * @returns {{ ok: boolean, error?: string }}
+   */
+  transition(newState, reason = '') {
+    if (!VALID_AGENT_STATES.has(newState)) {
+      return { ok: false, error: `非法状态: ${newState}` };
+    }
+
+    const allowed = STATE_TRANSITIONS[this.state] || [];
+    if (!allowed.includes(newState)) {
+      return { ok: false, error: `不允许从 ${this.state} 转换到 ${newState}` };
+    }
+
+    this.history.push({
+      from: this.state,
+      to: newState,
+      reason,
+      timestamp: new Date().toISOString(),
+    });
+
+    this.state = newState;
+    this.updatedAt = new Date().toISOString();
+
+    if (newState === AGENT_STATES.EXECUTING && !this.startedAt) {
+      this.startedAt = new Date().toISOString();
+    }
+
+    return { ok: true };
+  }
+
+  /**
+   * 检查是否处于终态
+   * @returns {boolean}
+   */
+  isTerminal() {
+    return this.state === AGENT_STATES.COMPLETED || this.state === AGENT_STATES.FAILED;
+  }
+
+  /**
+   * 重置为空闲状态
+   */
+  reset() {
+    this.state = AGENT_STATES.IDLE;
+    this.taskId = null;
+    this.startedAt = null;
+    this.updatedAt = new Date().toISOString();
+    this.metadata = {};
+  }
+}
+
+// ============================================================
+// AgentCollaborationProtocol — 协作协议管理器
+// ============================================================
+
+class AgentCollaborationProtocol {
+  constructor() {
+    /** @type {Map<string, AgentState>} */
+    this.agents = new Map();
+    /** @type {Array<CollaborationMessage>} */
+    this.messageQueue = [];
+    /** @type {Map<string, string>} taskId → agentId */
+    this.taskAssignments = new Map();
+  }
+
+  // ============================================================
+  // Agent 注册与管理
+  // ============================================================
+
+  /**
+   * 注册 Agent
+   * @param {Object} profile - AgentProfile
+   * @returns {AgentState}
+   */
+  registerAgent(profile) {
+    const state = new AgentState(profile.agentId, profile);
+    this.agents.set(profile.agentId, state);
+    return state;
+  }
+
+  /**
+   * 注销 Agent
+   * @param {string} agentId
+   * @returns {boolean}
+   */
+  unregisterAgent(agentId) {
+    return this.agents.delete(agentId);
+  }
+
+  /**
+   * 获取 Agent 状态
+   * @param {string} agentId
+   * @returns {AgentState|null}
+   */
+  getAgentState(agentId) {
+    return this.agents.get(agentId) || null;
+  }
+
+  /**
+   * 列出所有已注册 Agent
+   * @returns {Array<{ agentId: string, state: string, taskId: string|null }>}
+   */
+  listAgents() {
+    const list = [];
+    for (const [agentId, agentState] of this.agents) {
+      list.push({
+        agentId,
+        state: agentState.state,
+        taskId: agentState.taskId,
+      });
+    }
+    return list;
+  }
+
+  /**
+   * 获取空闲 Agent 列表
+   * @returns {AgentState[]}
+   */
+  getIdleAgents() {
+    const idle = [];
+    for (const agentState of this.agents.values()) {
+      if (agentState.state === AGENT_STATES.IDLE) {
+        idle.push(agentState);
+      }
+    }
+    return idle;
+  }
+
+  // ============================================================
+  // 任务分配
+  // ============================================================
+
+  /**
+   * 分配任务给 Agent
+   * @param {string} agentId
+   * @param {string} taskId
+   * @param {Object} [taskMeta] - 任务元数据
+   * @returns {{ ok: boolean, error?: string }}
+   */
+  assignTask(agentId, taskId, taskMeta = {}) {
+    const agentState = this.agents.get(agentId);
+    if (!agentState) {
+      return { ok: false, error: `Agent 不存在: ${agentId}` };
+    }
+
+    if (agentState.state !== AGENT_STATES.IDLE) {
+      return { ok: false, error: `Agent ${agentId} 当前状态 ${agentState.state}，无法分配任务` };
+    }
+
+    if (this.taskAssignments.has(taskId)) {
+      const existingAgent = this.taskAssignments.get(taskId);
+      return { ok: false, error: `任务 ${taskId} 已分配给 ${existingAgent}` };
+    }
+
+    agentState.taskId = taskId;
+    agentState.metadata = { ...taskMeta };
+
+    const transitionResult = agentState.transition(AGENT_STATES.ASSIGNED, `分配任务 ${taskId}`);
+    if (!transitionResult.ok) {
+      agentState.taskId = null;
+      return transitionResult;
+    }
+
+    this.taskAssignments.set(taskId, agentId);
+    return { ok: true };
+  }
+
+  /**
+   * 释放任务
+   * @param {string} taskId
+   * @returns {{ ok: boolean, error?: string }}
+   */
+  releaseTask(taskId) {
+    const agentId = this.taskAssignments.get(taskId);
+    if (!agentId) {
+      return { ok: false, error: `任务 ${taskId} 未分配` };
+    }
+
+    const agentState = this.agents.get(agentId);
+    if (agentState) {
+      agentState.taskId = null;
+      agentState.reset();
+    }
+
+    this.taskAssignments.delete(taskId);
+    return { ok: true };
+  }
+
+  // ============================================================
+  // 消息传递
+  // ============================================================
+
+  /**
+   * 发送消息
+   * @param {Object} params
+   * @param {string} params.fromAgentId - 发送者
+   * @param {string} params.toAgentId - 接收者
+   * @param {string} params.type - 消息类型 (task/result/review/repair/escalation)
+   * @param {Object} params.payload - 消息内容
+   * @returns {CollaborationMessage}
+   */
+  sendMessage({ fromAgentId, toAgentId, type, payload }) {
+    const message = {
+      id: `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      fromAgentId,
+      toAgentId,
+      type,
+      payload,
+      timestamp: new Date().toISOString(),
+      read: false,
+    };
+    this.messageQueue.push(message);
+    return message;
+  }
+
+  /**
+   * 获取指定 Agent 的未读消息
+   * @param {string} agentId
+   * @returns {Array<CollaborationMessage>}
+   */
+  getUnreadMessages(agentId) {
+    return this.messageQueue.filter((m) => m.toAgentId === agentId && !m.read);
+  }
+
+  /**
+   * 标记消息为已读
+   * @param {string} messageId
+   * @returns {boolean}
+   */
+  markMessageRead(messageId) {
+    const msg = this.messageQueue.find((m) => m.id === messageId);
+    if (!msg) return false;
+    msg.read = true;
+    return true;
+  }
+
+  // ============================================================
+  // 查询与统计
+  // ============================================================
+
+  /**
+   * 获取协议统计
+   * @returns {{ totalAgents: number, byState: Record<string, number>, totalTasks: number, totalMessages: number }}
+   */
+  getStats() {
+    const byState = {};
+    for (const agentState of this.agents.values()) {
+      byState[agentState.state] = (byState[agentState.state] || 0) + 1;
+    }
+
+    return {
+      totalAgents: this.agents.size,
+      byState,
+      totalTasks: this.taskAssignments.size,
+      totalMessages: this.messageQueue.length,
+    };
+  }
+
+  /**
+   * 重置协议状态
+   */
+  reset() {
+    for (const agentState of this.agents.values()) {
+      agentState.reset();
+    }
+    this.messageQueue = [];
+    this.taskAssignments = new Map();
+  }
+}
+
+/**
+ * @typedef {Object} CollaborationMessage
+ * @property {string} id
+ * @property {string} fromAgentId
+ * @property {string} toAgentId
+ * @property {string} type
+ * @property {Object} payload
+ * @property {string} timestamp
+ * @property {boolean} read
+ */
+
+module.exports = {
+  AgentState,
+  AgentCollaborationProtocol,
+  STATE_TRANSITIONS,
+};

package/src/agent/conflict-handler.js

@@ -0,0 +1,364 @@
+/**
+ * Conflict Handler — 多 Agent 冲突处理与人工门禁
+ *
+ * 处理多 Agent 同时修改同一文件的冲突，提供文件锁和人工审批队列。
+ */
+
+// ============================================================
+// 文件锁
+// ============================================================
+
+class FileLockManager {
+  constructor() {
+    /** @type {Map<string, FileLock>} filePath → lock */
+    this.locks = new Map();
+  }
+
+  /**
+   * 尝试获取文件锁
+   * @param {string} filePath
+   * @param {string} agentId
+   * @returns {{ ok: boolean, error?: string }}
+   */
+  acquire(filePath, agentId) {
+    const existing = this.locks.get(filePath);
+
+    if (existing && existing.agentId !== agentId) {
+      return { ok: false, error: `文件 ${filePath} 已被 Agent ${existing.agentId} 锁定` };
+    }
+
+    if (existing && existing.agentId === agentId) {
+      // 同一 Agent 重复获取，刷新时间
+      existing.acquiredAt = new Date().toISOString();
+      return { ok: true };
+    }
+
+    this.locks.set(filePath, {
+      filePath,
+      agentId,
+      acquiredAt: new Date().toISOString(),
+    });
+
+    return { ok: true };
+  }
+
+  /**
+   * 释放文件锁
+   * @param {string} filePath
+   * @param {string} agentId
+   * @returns {{ ok: boolean, error?: string }}
+   */
+  release(filePath, agentId) {
+    const existing = this.locks.get(filePath);
+
+    if (!existing) {
+      return { ok: true }; // 已释放
+    }
+
+    if (existing.agentId !== agentId) {
+      return { ok: false, error: `文件 ${filePath} 由 Agent ${existing.agentId} 锁定，不能由 ${agentId} 释放` };
+    }
+
+    this.locks.delete(filePath);
+    return { ok: true };
+  }
+
+  /**
+   * 强制释放文件锁
+   * @param {string} filePath
+   */
+  forceRelease(filePath) {
+    this.locks.delete(filePath);
+  }
+
+  /**
+   * 释放指定 Agent 的所有锁
+   * @param {string} agentId
+   * @returns {string[]} 被释放的文件列表
+   */
+  releaseAll(agentId) {
+    const released = [];
+    for (const [filePath, lock] of this.locks) {
+      if (lock.agentId === agentId) {
+        this.locks.delete(filePath);
+        released.push(filePath);
+      }
+    }
+    return released;
+  }
+
+  /**
+   * 检查文件是否被锁定
+   * @param {string} filePath
+   * @returns {FileLock|null}
+   */
+  getLock(filePath) {
+    return this.locks.get(filePath) || null;
+  }
+
+  /**
+   * 获取指定 Agent 锁定的所有文件
+   * @param {string} agentId
+   * @returns {string[]}
+   */
+  getAgentLocks(agentId) {
+    const files = [];
+    for (const [filePath, lock] of this.locks) {
+      if (lock.agentId === agentId) {
+        files.push(filePath);
+      }
+    }
+    return files;
+  }
+
+  /**
+   * 获取所有锁
+   * @returns {Array<FileLock>}
+   */
+  getAllLocks() {
+    return [...this.locks.values()];
+  }
+}
+
+// ============================================================
+// 冲突检测
+// ============================================================
+
+/**
+ * 检测文件修改冲突
+ * @param {Array<{ agentId: string, files: string[] }>} agentFileLists - 各 Agent 计划修改的文件列表
+ * @returns {Array<ConflictEntry>}
+ */
+function detectConflicts(agentFileLists) {
+  const conflicts = [];
+  const fileAgents = new Map();
+
+  for (const { agentId, files } of agentFileLists) {
+    for (const filePath of files) {
+      if (!fileAgents.has(filePath)) {
+        fileAgents.set(filePath, []);
+      }
+      fileAgents.get(filePath).push(agentId);
+    }
+  }
+
+  for (const [filePath, agents] of fileAgents) {
+    if (agents.length > 1) {
+      conflicts.push({
+        filePath,
+        agents: [...new Set(agents)],
+        detectedAt: new Date().toISOString(),
+      });
+    }
+  }
+
+  return conflicts;
+}
+
+// ============================================================
+// 人工审批队列
+// ============================================================
+
+class ApprovalQueue {
+  constructor() {
+    /** @type {Array<ApprovalRequest>} */
+    this.pending = [];
+    /** @type {Array<ApprovalRequest>} */
+    this.processed = [];
+  }
+
+  /**
+   * 提交审批请求
+   * @param {Object} params
+   * @param {string} params.agentId - 请求 Agent
+   * @param {string} params.type - 请求类型 (file-conflict/manual-review/tool-override)
+   * @param {Object} params.details - 请求详情
+   * @returns {ApprovalRequest}
+   */
+  submit({ agentId, type, details = {} }) {
+    const request = {
+      id: `approval-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      agentId,
+      type,
+      details,
+      status: 'pending',
+      submittedAt: new Date().toISOString(),
+      resolvedAt: null,
+      resolvedBy: null,
+      resolution: null,
+    };
+    this.pending.push(request);
+    return request;
+  }
+
+  /**
+   * 批准请求
+   * @param {string} requestId
+   * @param {string} [resolvedBy] - 审批人
+   * @param {string} [comment] - 审批意见
+   * @returns {{ ok: boolean, error?: string }}
+   */
+  approve(requestId, resolvedBy = 'human', comment = '') {
+    const request = this.pending.find((r) => r.id === requestId);
+    if (!request) {
+      return { ok: false, error: `审批请求不存在: ${requestId}` };
+    }
+
+    request.status = 'approved';
+    request.resolvedAt = new Date().toISOString();
+    request.resolvedBy = resolvedBy;
+    request.resolution = comment || '已批准';
+
+    this.pending = this.pending.filter((r) => r.id !== requestId);
+    this.processed.push(request);
+    return { ok: true };
+  }
+
+  /**
+   * 拒绝请求
+   * @param {string} requestId
+   * @param {string} [resolvedBy] - 审批人
+   * @param {string} [comment] - 拒绝原因
+   * @returns {{ ok: boolean, error?: string }}
+   */
+  reject(requestId, resolvedBy = 'human', comment = '') {
+    const request = this.pending.find((r) => r.id === requestId);
+    if (!request) {
+      return { ok: false, error: `审批请求不存在: ${requestId}` };
+    }
+
+    request.status = 'rejected';
+    request.resolvedAt = new Date().toISOString();
+    request.resolvedBy = resolvedBy;
+    request.resolution = comment || '已拒绝';
+
+    this.pending = this.pending.filter((r) => r.id !== requestId);
+    this.processed.push(request);
+    return { ok: true };
+  }
+
+  /**
+   * 获取待审批列表
+   * @param {string} [agentId] - 可选，按 Agent 过滤
+   * @returns {Array<ApprovalRequest>}
+   */
+  getPending(agentId) {
+    if (agentId) {
+      return this.pending.filter((r) => r.agentId === agentId);
+    }
+    return [...this.pending];
+  }
+
+  /**
+   * 获取已处理列表
+   * @returns {Array<ApprovalRequest>}
+   */
+  getProcessed() {
+    return [...this.processed];
+  }
+
+  /**
+   * 获取统计
+   * @returns {{ pending: number, approved: number, rejected: number }}
+   */
+  getStats() {
+    return {
+      pending: this.pending.length,
+      approved: this.processed.filter((r) => r.status === 'approved').length,
+      rejected: this.processed.filter((r) => r.status === 'rejected').length,
+    };
+  }
+}
+
+// ============================================================
+// ConflictHandler — 整合管理器
+// ============================================================
+
+class ConflictHandler {
+  constructor() {
+    this.fileLockManager = new FileLockManager();
+    this.approvalQueue = new ApprovalQueue();
+  }
+
+  /**
+   * 尝试锁定文件（冲突时自动提交审批）
+   * @param {string} filePath
+   * @param {string} agentId
+   * @param {Object} [conflictDetails] - 冲突详情
+   * @returns {{ ok: boolean, locked: boolean, approvalId?: string, error?: string }}
+   */
+  lockOrQueue(filePath, agentId, conflictDetails = {}) {
+    const lockResult = this.fileLockManager.acquire(filePath, agentId);
+
+    if (lockResult.ok) {
+      return { ok: true, locked: true };
+    }
+
+    // 锁冲突 — 提交审批
+    const approval = this.approvalQueue.submit({
+      agentId,
+      type: 'file-conflict',
+      details: {
+        filePath,
+        currentLock: this.fileLockManager.getLock(filePath),
+        ...conflictDetails,
+      },
+    });
+
+    return { ok: true, locked: false, approvalId: approval.id };
+  }
+
+  /**
+   * 释放 Agent 的所有锁和资源
+   * @param {string} agentId
+   */
+  releaseAgent(agentId) {
+    this.fileLockManager.releaseAll(agentId);
+  }
+
+  /**
+   * 获取总体状态
+   * @returns {Object}
+   */
+  getStatus() {
+    return {
+      activeLocks: this.fileLockManager.getAllLocks().length,
+      pendingApprovals: this.approvalQueue.getPending().length,
+      processedApprovals: this.approvalQueue.getProcessed().length,
+    };
+  }
+}
+
+/**
+ * @typedef {Object} FileLock
+ * @property {string} filePath
+ * @property {string} agentId
+ * @property {string} acquiredAt
+ */
+
+/**
+ * @typedef {Object} ApprovalRequest
+ * @property {string} id
+ * @property {string} agentId
+ * @property {string} type
+ * @property {Object} details
+ * @property {string} status - pending/approved/rejected
+ * @property {string} submittedAt
+ * @property {string|null} resolvedAt
+ * @property {string|null} resolvedBy
+ * @property {string|null} resolution
+ */
+
+/**
+ * @typedef {Object} ConflictEntry
+ * @property {string} filePath
+ * @property {string[]} agents
+ * @property {string} detectedAt
+ */
+
+module.exports = {
+  FileLockManager,
+  ApprovalQueue,
+  ConflictHandler,
+  detectConflicts,
+};