@gong-ym/ai-spec-auto 0.2.3

package/src/agent/file-permission.js

@@ -0,0 +1,121 @@
+/**
+ * File Permission — 文件作用域权限校验
+ *
+ * 根据 AgentProfile 的 allowedFileScopes / deniedFileScopes 判断是否允许访问某文件。
+ * 规则：deniedFileScopes 优先于 allowedFileScopes；使用 glob 匹配。
+ */
+
+// ============================================================
+// globMatch — 简易 glob 匹配
+// ============================================================
+
+/**
+ * 简易 glob 模式匹配（支持 ** / * / ?）
+ * @param {string} pattern - glob 模式
+ * @param {string} filePath - 文件路径
+ * @returns {boolean}
+ */
+function globMatch(pattern, filePath) {
+  // 规范化路径分隔符
+  const normalizedPattern = pattern.replace(/\\/g, '/');
+  const normalizedPath = filePath.replace(/\\/g, '/');
+
+  // 转换 glob 为正则表达式
+  let regexStr = normalizedPattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&') // 转义特殊字符
+    .replace(/\*\*/g, '{{DOUBLE_STAR}}') // 临时替换 **
+    .replace(/\*/g, '[^/]*') // * 匹配非斜杠字符
+    .replace(/\?/g, '[^/]') // ? 匹配单个非斜杠字符
+    .replace(/\{\{DOUBLE_STAR\}\}/g, '.*'); // ** 匹配任意路径
+
+  // **/ 前缀应匹配零个或多个路径段（根文件也需要匹配）
+  regexStr = regexStr.replace(/^\.\*\//, '(.*\\/)?');
+
+  const regex = new RegExp(`^${regexStr}$`);
+  return regex.test(normalizedPath);
+}
+
+// ============================================================
+// matchesAnyGlob — 匹配任一 glob 模式
+// ============================================================
+
+/**
+ * 检查文件路径是否匹配 glob 模式列表中的任一模式
+ * @param {string[]} patterns - glob 模式列表
+ * @param {string} filePath - 文件路径
+ * @returns {boolean}
+ */
+function matchesAnyGlob(patterns, filePath) {
+  return patterns.some((pattern) => globMatch(pattern, filePath));
+}
+
+// ============================================================
+// checkFilePermission — 文件权限校验
+// ============================================================
+
+/**
+ * 检查 Agent 是否被允许访问指定文件
+ * @param {Object} profile - AgentProfile
+ * @param {string} filePath - 文件路径
+ * @returns {{ allowed: boolean, reason: string }}
+ */
+function checkFilePermission(profile, filePath) {
+  if (!profile || typeof profile !== 'object') {
+    return { allowed: false, reason: 'profile 无效' };
+  }
+
+  if (!filePath || typeof filePath !== 'string') {
+    return { allowed: false, reason: 'filePath 无效' };
+  }
+
+  const deniedFileScopes = profile.deniedFileScopes || [];
+  const allowedFileScopes = profile.allowedFileScopes || [];
+
+  // deniedFileScopes 优先级最高
+  if (deniedFileScopes.length > 0 && matchesAnyGlob(deniedFileScopes, filePath)) {
+    return { allowed: false, reason: `文件 ${filePath} 匹配 deniedFileScopes` };
+  }
+
+  // 空 allowedFileScopes 表示全部允许（除 denied 外）
+  if (allowedFileScopes.length === 0) {
+    return { allowed: true, reason: 'allowedFileScopes 为空，全部允许' };
+  }
+
+  // allowedFileScopes 非空时，必须匹配至少一个
+  if (matchesAnyGlob(allowedFileScopes, filePath)) {
+    return { allowed: true, reason: `文件 ${filePath} 匹配 allowedFileScopes` };
+  }
+
+  return { allowed: false, reason: `文件 ${filePath} 不匹配任何 allowedFileScopes` };
+}
+
+// ============================================================
+// checkBatchFilePermission — 批量文件权限校验
+// ============================================================
+
+/**
+ * 批量检查 Agent 是否被允许访问多个文件
+ * @param {Object} profile - AgentProfile
+ * @param {string[]} filePaths - 文件路径列表
+ * @returns {{ results: Record<string, { allowed: boolean, reason: string }>, allAllowed: boolean }}
+ */
+function checkBatchFilePermission(profile, filePaths) {
+  const results = {};
+  let allAllowed = true;
+
+  for (const filePath of filePaths) {
+    results[filePath] = checkFilePermission(profile, filePath);
+    if (!results[filePath].allowed) {
+      allAllowed = false;
+    }
+  }
+
+  return { results, allAllowed };
+}
+
+module.exports = {
+  globMatch,
+  matchesAnyGlob,
+  checkFilePermission,
+  checkBatchFilePermission,
+};

package/src/agent/index.js

@@ -0,0 +1,38 @@
+/**
+ * Agent 模块 — barrel 导出
+ */
+
+const agentTypes = require('./agent-types');
+const agentProfile = require('./agent-profile');
+const agentTemplates = require('./agent-templates');
+const toolPermission = require('./tool-permission');
+const filePermission = require('./file-permission');
+const { PermissionAuditLog } = require('./permission-audit');
+const { AgentContext } = require('./agent-context');
+const { AgentState, AgentCollaborationProtocol } = require('./collaboration-protocol');
+const { ReviewRepairLoop } = require('./review-repair-loop');
+const { FileLockManager, ApprovalQueue, ConflictHandler, detectConflicts } = require('./conflict-handler');
+
+module.exports = {
+  // 类型与常量
+  ...agentTypes,
+  // Profile
+  ...agentProfile,
+  ...agentTemplates,
+  // 权限
+  ...toolPermission,
+  ...filePermission,
+  PermissionAuditLog,
+  // 上下文
+  AgentContext,
+  // 协作
+  AgentState,
+  AgentCollaborationProtocol,
+  // Review/Repair
+  ReviewRepairLoop,
+  // 冲突处理
+  FileLockManager,
+  ApprovalQueue,
+  ConflictHandler,
+  detectConflicts,
+};

package/src/agent/permission-audit.js

@@ -0,0 +1,151 @@
+/**
+ * Permission Audit — 权限审计日志
+ *
+ * 记录每次权限检查的结果，支持查询和导出。
+ */
+
+// ============================================================
+// PermissionAuditLog
+// ============================================================
+
+class PermissionAuditLog {
+  constructor() {
+    /** @type {Array<PermissionAuditEntry>} */
+    this.entries = [];
+  }
+
+  /**
+   * 记录权限检查结果
+   * @param {Object} params
+   * @param {string} params.agentId - Agent ID
+   * @param {string} params.checkType - 检查类型 (tool/file)
+   * @param {string} params.target - 被检查的目标（工具名或文件路径）
+   * @param {boolean} params.allowed - 是否允许
+   * @param {string} params.reason - 原因
+   */
+  record({ agentId, checkType, target, allowed, reason }) {
+    this.entries.push({
+      agentId,
+      checkType,
+      target,
+      allowed,
+      reason,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  /**
+   * 记录工具权限检查
+   * @param {string} agentId
+   * @param {string} toolName
+   * @param {{ allowed: boolean, reason: string }} result
+   */
+  recordToolCheck(agentId, toolName, result) {
+    this.record({
+      agentId,
+      checkType: 'tool',
+      target: toolName,
+      allowed: result.allowed,
+      reason: result.reason,
+    });
+  }
+
+  /**
+   * 记录文件权限检查
+   * @param {string} agentId
+   * @param {string} filePath
+   * @param {{ allowed: boolean, reason: string }} result
+   */
+  recordFileCheck(agentId, filePath, result) {
+    this.record({
+      agentId,
+      checkType: 'file',
+      target: filePath,
+      allowed: result.allowed,
+      reason: result.reason,
+    });
+  }
+
+  /**
+   * 查询指定 Agent 的所有审计记录
+   * @param {string} agentId
+   * @returns {Array<PermissionAuditEntry>}
+   */
+  getByAgent(agentId) {
+    return this.entries.filter((e) => e.agentId === agentId);
+  }
+
+  /**
+   * 查询被拒绝的记录
+   * @param {string} [agentId] - 可选，按 Agent 过滤
+   * @returns {Array<PermissionAuditEntry>}
+   */
+  getDenied(agentId) {
+    return this.entries.filter((e) => !e.allowed && (!agentId || e.agentId === agentId));
+  }
+
+  /**
+   * 获取审计统计
+   * @param {string} [agentId] - 可选，按 Agent 过滤
+   * @returns {{ total: number, allowed: number, denied: number, byType: Record<string, number> }}
+   */
+  getStats(agentId) {
+    const filtered = agentId ? this.getByAgent(agentId) : this.entries;
+
+    const stats = {
+      total: filtered.length,
+      allowed: 0,
+      denied: 0,
+      byType: {},
+    };
+
+    for (const entry of filtered) {
+      if (entry.allowed) {
+        stats.allowed++;
+      } else {
+        stats.denied++;
+      }
+
+      stats.byType[entry.checkType] = (stats.byType[entry.checkType] || 0) + 1;
+    }
+
+    return stats;
+  }
+
+  /**
+   * 清空审计日志
+   */
+  clear() {
+    this.entries = [];
+  }
+
+  /**
+   * 获取日志条目数量
+   * @returns {number}
+   */
+  get size() {
+    return this.entries.length;
+  }
+
+  /**
+   * 导出为 JSON
+   * @returns {Array<PermissionAuditEntry>}
+   */
+  toJSON() {
+    return [...this.entries];
+  }
+}
+
+/**
+ * @typedef {Object} PermissionAuditEntry
+ * @property {string} agentId
+ * @property {string} checkType - 'tool' | 'file'
+ * @property {string} target
+ * @property {boolean} allowed
+ * @property {string} reason
+ * @property {string} timestamp
+ */
+
+module.exports = {
+  PermissionAuditLog,
+};

package/src/agent/review-repair-loop.js

@@ -0,0 +1,270 @@
+/**
+ * Review/Repair Loop — Review → Repair → Re-test 闭环
+ *
+ * 管理 Agent 的审查-修复循环，控制最大修复次数和升级策略。
+ */
+
+const { AGENT_STATES, ESCALATION_POLICIES } = require('./agent-types');
+
+// ============================================================
+// 默认配置
+// ============================================================
+
+const DEFAULT_LOOP_CONFIG = Object.freeze({
+  /** 最大修复次数 */
+  maxRepairAttempts: 2,
+  /** 最大审查次数 */
+  maxReviewAttempts: 3,
+  /** 超时时间（毫秒） */
+  timeout: 600000,
+  /** 超时后的升级策略 */
+  timeoutPolicy: ESCALATION_POLICIES.BLOCK,
+  /** 修复失败后的升级策略 */
+  repairFailurePolicy: ESCALATION_POLICIES.BLOCK,
+});
+
+// ============================================================
+// ReviewRepairLoop
+// ============================================================
+
+class ReviewRepairLoop {
+  /**
+   * @param {Object} [config] - 配置覆盖
+   */
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_LOOP_CONFIG, ...config };
+
+    /** 当前修复次数 */
+    this.repairCount = 0;
+    /** 当前审查次数 */
+    this.reviewCount = 0;
+    /** 循环是否已完成 */
+    this.completed = false;
+    /** 循环是否已失败 */
+    this.failed = false;
+    /** 最终状态 */
+    this.finalStatus = null;
+    /** 事件日志 */
+    this.events = [];
+    /** 开始时间 */
+    this.startedAt = new Date().toISOString();
+  }
+
+  // ============================================================
+  // 事件记录
+  // ============================================================
+
+  /**
+   * 记录事件
+   * @param {string} type - 事件类型
+   * @param {Object} data - 事件数据
+   */
+  recordEvent(type, data = {}) {
+    this.events.push({
+      type,
+      data,
+      timestamp: new Date().toISOString(),
+      repairCount: this.repairCount,
+      reviewCount: this.reviewCount,
+    });
+  }
+
+  // ============================================================
+  // Review 阶段
+  // ============================================================
+
+  /**
+   * 开始审查
+   * @returns {{ ok: boolean, state: string, error?: string }}
+   */
+  startReview() {
+    if (this.completed || this.failed) {
+      return { ok: false, state: this.completed ? 'completed' : 'failed', error: '循环已结束' };
+    }
+
+    if (this.reviewCount >= this.config.maxReviewAttempts) {
+      this.fail('超过最大审查次数');
+      return { ok: false, state: 'failed', error: '超过最大审查次数' };
+    }
+
+    this.reviewCount++;
+    this.recordEvent('review_start', { reviewCount: this.reviewCount });
+
+    return { ok: true, state: AGENT_STATES.REVIEWING };
+  }
+
+  /**
+   * 审查通过
+   * @param {Object} [reviewResult] - 审查结果
+   * @returns {{ ok: boolean, state: string }}
+   */
+  approveReview(reviewResult = {}) {
+    this.completed = true;
+    this.finalStatus = 'approved';
+    this.recordEvent('review_approved', reviewResult);
+    return { ok: true, state: AGENT_STATES.COMPLETED };
+  }
+
+  /**
+   * 审查不通过，需要修复
+   * @param {Object} [reviewResult] - 审查结果（含问题列表）
+   * @returns {{ ok: boolean, state: string, needsRepair: boolean, error?: string }}
+   */
+  rejectReview(reviewResult = {}) {
+    if (this.completed || this.failed) {
+      return { ok: false, state: this.completed ? 'completed' : 'failed', needsRepair: false, error: '循环已结束' };
+    }
+
+    this.recordEvent('review_rejected', reviewResult);
+    return { ok: true, state: AGENT_STATES.REPAIRING, needsRepair: true };
+  }
+
+  // ============================================================
+  // Repair 阶段
+  // ============================================================
+
+  /**
+   * 开始修复
+   * @returns {{ ok: boolean, state: string, error?: string }}
+   */
+  startRepair() {
+    if (this.completed || this.failed) {
+      return { ok: false, state: this.completed ? 'completed' : 'failed', error: '循环已结束' };
+    }
+
+    if (this.repairCount >= this.config.maxRepairAttempts) {
+      this.fail('超过最大修复次数');
+      return { ok: false, state: 'failed', error: '超过最大修复次数' };
+    }
+
+    this.repairCount++;
+    this.recordEvent('repair_start', { repairCount: this.repairCount });
+
+    return { ok: true, state: AGENT_STATES.REPAIRING };
+  }
+
+  /**
+   * 修复完成，重新进入审查
+   * @param {Object} [repairResult] - 修复结果
+   * @returns {{ ok: boolean, state: string }}
+   */
+  completeRepair(repairResult = {}) {
+    this.recordEvent('repair_complete', repairResult);
+    return { ok: true, state: AGENT_STATES.REVIEWING };
+  }
+
+  /**
+   * 修复失败
+   * @param {Object} [repairResult] - 修复结果
+   * @returns {{ ok: boolean, state: string, escalation: string }}
+   */
+  failRepair(repairResult = {}) {
+    this.recordEvent('repair_failed', repairResult);
+
+    const policy = this.config.repairFailurePolicy;
+
+    if (policy === ESCALATION_POLICIES.RETRY && this.repairCount < this.config.maxRepairAttempts) {
+      return { ok: true, state: AGENT_STATES.REPAIRING, escalation: 'retry' };
+    }
+
+    if (policy === ESCALATION_POLICIES.SKIP) {
+      this.completed = true;
+      this.finalStatus = 'skipped';
+      this.recordEvent('escalation_skip', {});
+      return { ok: true, state: AGENT_STATES.COMPLETED, escalation: 'skip' };
+    }
+
+    // BLOCK 或 ABORT
+    this.fail(`修复失败，升级策略: ${policy}`);
+    return { ok: true, state: AGENT_STATES.FAILED, escalation: policy };
+  }
+
+  // ============================================================
+  // 超时处理
+  // ============================================================
+
+  /**
+   * 检查是否超时
+   * @returns {boolean}
+   */
+  isTimedOut() {
+    const elapsed = Date.now() - new Date(this.startedAt).getTime();
+    return elapsed > this.config.timeout;
+  }
+
+  /**
+   * 处理超时
+   * @returns {{ ok: boolean, state: string, escalation: string }}
+   */
+  handleTimeout() {
+    this.recordEvent('timeout', { elapsed: Date.now() - new Date(this.startedAt).getTime() });
+
+    const policy = this.config.timeoutPolicy;
+
+    if (policy === ESCALATION_POLICIES.SKIP) {
+      this.completed = true;
+      this.finalStatus = 'timeout_skipped';
+      return { ok: true, state: AGENT_STATES.COMPLETED, escalation: 'skip' };
+    }
+
+    this.fail('超时');
+    return { ok: true, state: AGENT_STATES.FAILED, escalation: policy };
+  }
+
+  // ============================================================
+  // 失败处理
+  // ============================================================
+
+  /**
+   * 标记循环失败
+   * @param {string} reason
+   */
+  fail(reason) {
+    this.failed = true;
+    this.finalStatus = 'failed';
+    this.recordEvent('loop_failed', { reason });
+  }
+
+  // ============================================================
+  // 查询
+  // ============================================================
+
+  /**
+   * 获取循环状态摘要
+   * @returns {Object}
+   */
+  getSummary() {
+    return {
+      completed: this.completed,
+      failed: this.failed,
+      finalStatus: this.finalStatus,
+      repairCount: this.repairCount,
+      reviewCount: this.reviewCount,
+      maxRepairAttempts: this.config.maxRepairAttempts,
+      maxReviewAttempts: this.config.maxReviewAttempts,
+      eventCount: this.events.length,
+      startedAt: this.startedAt,
+    };
+  }
+
+  /**
+   * 检查是否可以继续修复
+   * @returns {boolean}
+   */
+  canRepair() {
+    return !this.completed && !this.failed && this.repairCount < this.config.maxRepairAttempts;
+  }
+
+  /**
+   * 检查是否可以继续审查
+   * @returns {boolean}
+   */
+  canReview() {
+    return !this.completed && !this.failed && this.reviewCount < this.config.maxReviewAttempts;
+  }
+}
+
+module.exports = {
+  ReviewRepairLoop,
+  DEFAULT_LOOP_CONFIG,
+};

package/src/agent/tool-permission.js

@@ -0,0 +1,101 @@
+/**
+ * Tool Permission — 工具权限校验
+ *
+ * 根据 AgentProfile 的 allowedTools / deniedTools 判断是否允许使用某工具。
+ * 规则：deniedTools 优先于 allowedTools；空 allowedTools 表示全部允许。
+ */
+
+// ============================================================
+// checkToolPermission — 工具权限校验
+// ============================================================
+
+/**
+ * 检查 Agent 是否被允许使用指定工具
+ * @param {Object} profile - AgentProfile
+ * @param {string} toolName - 工具名称
+ * @returns {{ allowed: boolean, reason: string }}
+ */
+function checkToolPermission(profile, toolName) {
+  if (!profile || typeof profile !== 'object') {
+    return { allowed: false, reason: 'profile 无效' };
+  }
+
+  if (!toolName || typeof toolName !== 'string') {
+    return { allowed: false, reason: 'toolName 无效' };
+  }
+
+  const deniedTools = profile.deniedTools || [];
+  const allowedTools = profile.allowedTools || [];
+
+  // deniedTools 优先级最高 — 精确匹配
+  if (deniedTools.includes(toolName)) {
+    return { allowed: false, reason: `工具 ${toolName} 在 deniedTools 列表中` };
+  }
+
+  // 空 allowedTools 表示全部允许（除 deniedTools 中的）
+  if (allowedTools.length === 0) {
+    return { allowed: true, reason: 'allowedTools 为空，全部允许' };
+  }
+
+  // allowedTools 非空时，必须在列表中
+  if (allowedTools.includes(toolName)) {
+    return { allowed: true, reason: `工具 ${toolName} 在 allowedTools 列表中` };
+  }
+
+  return { allowed: false, reason: `工具 ${toolName} 不在 allowedTools 列表中` };
+}
+
+// ============================================================
+// checkBatchToolPermission — 批量工具权限校验
+// ============================================================
+
+/**
+ * 批量检查 Agent 是否被允许使用多个工具
+ * @param {Object} profile - AgentProfile
+ * @param {string[]} toolNames - 工具名称列表
+ * @returns {{ results: Record<string, { allowed: boolean, reason: string }>, allAllowed: boolean }}
+ */
+function checkBatchToolPermission(profile, toolNames) {
+  const results = {};
+  let allAllowed = true;
+
+  for (const toolName of toolNames) {
+    results[toolName] = checkToolPermission(profile, toolName);
+    if (!results[toolName].allowed) {
+      allAllowed = false;
+    }
+  }
+
+  return { results, allAllowed };
+}
+
+// ============================================================
+// getAllowedTools — 获取有效允许工具列表
+// ============================================================
+
+/**
+ * 获取 Agent 的有效允许工具列表
+ * @param {Object} profile - AgentProfile
+ * @param {string[]} allAvailableTools - 所有可用工具列表
+ * @returns {string[]}
+ */
+function getAllowedTools(profile, allAvailableTools = []) {
+  if (!profile) return [];
+
+  const deniedTools = profile.deniedTools || [];
+  const allowedTools = profile.allowedTools || [];
+
+  // 空 allowedTools = 全部允许，排除 denied
+  if (allowedTools.length === 0) {
+    return allAvailableTools.filter((t) => !deniedTools.includes(t));
+  }
+
+  // 非空 allowedTools，取交集后排除 denied
+  return allowedTools.filter((t) => !deniedTools.includes(t));
+}
+
+module.exports = {
+  checkToolPermission,
+  checkBatchToolPermission,
+  getAllowedTools,
+};