@dommaker/harness 0.13.0 → 0.13.2

package/src/safety/output-guardrail.ts

@@ -0,0 +1,174 @@
+/**
+ * 输出护栏
+ *
+ * 在最终输出前检查：
+ * - 敏感信息审查（API keys, passwords, tokens）
+ * - 代码质量检查
+ * - 知识引用完整性
+ */
+
+import type { OutputSafetyCheckResult, OutputViolation, OutputGuardrailConfig } from './types';
+
+const DEFAULT_SENSITIVE_PATTERNS: RegExp[] = [
+  // API keys
+  /(?:api[_-]?key|apikey)\s*[:=]\s*['"]?([a-zA-Z0-9_\-]{20,})['"]?/gi,
+  // AWS
+  /(?:AKIA|ASIA)[A-Z0-9]{16}/g,
+  // Generic secrets
+  /(?:secret|password|passwd|token|auth)\s*[:=]\s*['"]?([^\s'"]{8,})['"]?/gi,
+  // Private keys
+  /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/g,
+  // GitHub tokens
+  /gh[ps]_[A-Za-z0-9_]{36,}/g,
+  // Bearer tokens
+  /Bearer\s+[A-Za-z0-9_\-\.]{20,}/g,
+  // Connection strings
+  /(?:mongodb|postgres|mysql|redis):\/\/[^\s'"]+/gi,
+];
+
+const DEFAULT_MIN_QUALITY_SCORE = 0.6;
+
+export class OutputGuardrail {
+  private sensitivePatterns: RegExp[];
+  private minQualityScore: number;
+  private checkKnowledgeRefs: boolean;
+
+  constructor(config?: OutputGuardrailConfig) {
+    this.sensitivePatterns = config?.sensitivePatterns ?? DEFAULT_SENSITIVE_PATTERNS;
+    this.minQualityScore = config?.minQualityScore ?? DEFAULT_MIN_QUALITY_SCORE;
+    this.checkKnowledgeRefs = config?.checkKnowledgeRefs ?? false;
+  }
+
+  /**
+   * 检查输出安全性
+   */
+  check(content: string, knowledgeRefIds?: string[]): OutputSafetyCheckResult {
+    const violations: OutputViolation[] = [];
+
+    // 敏感信息检测
+    violations.push(...this.checkSensitiveInfo(content));
+
+    // 代码质量检查
+    violations.push(...this.checkQuality(content));
+
+    // 知识引用完整性
+    if (this.checkKnowledgeRefs && knowledgeRefIds) {
+      violations.push(...this.checkKnowledgeRefs_(
+        content,
+        knowledgeRefIds,
+      ));
+    }
+
+    const sanitized = violations.length > 0
+      ? this.sanitize(content, violations)
+      : undefined;
+
+    return {
+      safe: violations.length === 0,
+      violations,
+      sanitizedContent: sanitized,
+    };
+  }
+
+  /**
+   * 检测敏感信息
+   */
+  private checkSensitiveInfo(content: string): OutputViolation[] {
+    const violations: OutputViolation[] = [];
+
+    for (const pattern of this.sensitivePatterns) {
+      // Reset lastIndex for global patterns
+      pattern.lastIndex = 0;
+      let match: RegExpExecArray | null;
+      while ((match = pattern.exec(content)) !== null) {
+        const line = this.getLineNumber(content, match.index);
+        violations.push({
+          type: 'sensitive_info',
+          severity: 'high',
+          description: `检测到敏感信息: ${match[0].slice(0, 30)}...`,
+          location: { line, column: match.index - content.lastIndexOf('\n', match.index) - 1 },
+          matchedPattern: match[0],
+        });
+      }
+    }
+
+    return violations;
+  }
+
+  /**
+   * 代码质量检查（简单启发式）
+   */
+  private checkQuality(content: string): OutputViolation[] {
+    const violations: OutputViolation[] = [];
+
+    // 检查 TODO/FIXME/HACK
+    const todoPattern = /\b(TODO|FIXME|HACK|XXX)\b/gi;
+    let match: RegExpExecArray | null;
+    while ((match = todoPattern.exec(content)) !== null) {
+      const line = this.getLineNumber(content, match.index);
+      violations.push({
+        type: 'quality',
+        severity: 'low',
+        description: `代码包含 ${match[1]} 标记`,
+        location: { line, column: match.index - content.lastIndexOf('\n', match.index) - 1 },
+      });
+    }
+
+    // 检查 console.log 残留
+    const consolePattern = /console\.(log|debug|info)\(/g;
+    while ((match = consolePattern.exec(content)) !== null) {
+      const line = this.getLineNumber(content, match.index);
+      violations.push({
+        type: 'quality',
+        severity: 'low',
+        description: `代码包含 ${match[0].slice(0, -1)} 调用`,
+        location: { line, column: match.index - content.lastIndexOf('\n', match.index) - 1 },
+      });
+    }
+
+    return violations;
+  }
+
+  /**
+   * 检查知识引用完整性
+   */
+  private checkKnowledgeRefs_(content: string, referencedIds: string[]): OutputViolation[] {
+    const violations: OutputViolation[] = [];
+
+    for (const id of referencedIds) {
+      if (!content.includes(id)) {
+        violations.push({
+          type: 'knowledge_missing',
+          severity: 'medium',
+          description: `引用的知识条目 ${id} 未出现在输出中`,
+        });
+      }
+    }
+
+    return violations;
+  }
+
+  /**
+   * 清理敏感信息
+   */
+  private sanitize(content: string, violations: OutputViolation[]): string {
+    let sanitized = content;
+
+    for (const violation of violations) {
+      if (violation.type === 'sensitive_info' && violation.matchedPattern) {
+        // Escape special regex characters in the matched string
+        const escaped = violation.matchedPattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        sanitized = sanitized.replace(new RegExp(escaped, 'g'), '[REDACTED]');
+      }
+    }
+
+    return sanitized;
+  }
+
+  /**
+   * 获取行号
+   */
+  private getLineNumber(content: string, index: number): number {
+    return content.slice(0, index).split('\n').length;
+  }
+}

package/src/safety/sandbox.ts

@@ -0,0 +1,148 @@
+/**
+ * Sandbox 安全级别管理
+ *
+ * 四级权限模型：
+ * Level 1: 只读文件系统，无网络，无 shell
+ * Level 2: 可写限定目录（.harness/），无网络
+ * Level 3: 可写项目目录，受限网络（白名单）
+ * Level 4: 完全权限，需用户确认
+ */
+
+import type { SandboxLevel, SandboxConfig, SandboxCheckResult } from './types';
+
+const LEVEL_DESCRIPTIONS: Record<SandboxLevel, string> = {
+  1: '只读文件系统，无网络，无 shell',
+  2: '可写限定目录（.harness/），无网络',
+  3: '可写项目目录，受限网络（白名单）',
+  4: '完全权限，需用户确认',
+};
+
+const DEFAULT_WRITABLE_DIRS = ['.harness/'];
+
+export class Sandbox {
+  private config: SandboxConfig;
+
+  constructor(config?: Partial<SandboxConfig>) {
+    this.config = {
+      level: config?.level ?? 3,
+      writableDirs: config?.writableDirs ?? DEFAULT_WRITABLE_DIRS,
+      allowedHosts: config?.allowedHosts ?? [],
+      requiresConfirmation: config?.requiresConfirmation ?? (config?.level === 4),
+    };
+  }
+
+  getLevel(): SandboxLevel {
+    return this.config.level;
+  }
+
+  getDescription(): string {
+    return LEVEL_DESCRIPTIONS[this.config.level];
+  }
+
+  /**
+   * 检查当前级别是否满足操作所需级别
+   */
+  check(requiredLevel: SandboxLevel): SandboxCheckResult {
+    const allowed = this.config.level >= requiredLevel;
+    return {
+      allowed,
+      reason: allowed ? undefined : `当前 Level ${this.config.level} 不满足操作所需的 Level ${requiredLevel}`,
+      currentLevel: this.config.level,
+      requiredLevel,
+    };
+  }
+
+  /**
+   * 检查文件写入是否允许
+   */
+  checkFileWrite(filePath: string): SandboxCheckResult {
+    if (this.config.level >= 3) {
+      return { allowed: true, currentLevel: this.config.level, requiredLevel: 3 };
+    }
+
+    if (this.config.level >= 2) {
+      const inWritableDir = this.config.writableDirs?.some(dir => filePath.startsWith(dir));
+      if (inWritableDir) {
+        return { allowed: true, currentLevel: this.config.level, requiredLevel: 2 };
+      }
+      return {
+        allowed: false,
+        reason: `Level 2 只允许写入 ${this.config.writableDirs?.join(', ')}`,
+        currentLevel: this.config.level,
+        requiredLevel: 3,
+      };
+    }
+
+    return {
+      allowed: false,
+      reason: 'Level 1 禁止写入任何文件',
+      currentLevel: this.config.level,
+      requiredLevel: 2,
+    };
+  }
+
+  /**
+   * 检查网络访问是否允许
+   */
+  checkNetworkAccess(host: string): SandboxCheckResult {
+    if (this.config.level >= 4) {
+      return { allowed: true, currentLevel: this.config.level, requiredLevel: 4 };
+    }
+
+    if (this.config.level >= 3) {
+      const allowed = this.config.allowedHosts?.includes(host) ?? false;
+      return {
+        allowed,
+        reason: allowed ? undefined : `Host ${host} 不在白名单中`,
+        currentLevel: this.config.level,
+        requiredLevel: 3,
+      };
+    }
+
+    return {
+      allowed: false,
+      reason: `Level ${this.config.level} 禁止网络访问`,
+      currentLevel: this.config.level,
+      requiredLevel: 3,
+    };
+  }
+
+  /**
+   * 检查 shell 命令是否允许
+   */
+  checkShellAccess(): SandboxCheckResult {
+    if (this.config.level >= 3) {
+      return { allowed: true, currentLevel: this.config.level, requiredLevel: 3 };
+    }
+    return {
+      allowed: false,
+      reason: `Level ${this.config.level} 禁止 shell 访问`,
+      currentLevel: this.config.level,
+      requiredLevel: 3,
+    };
+  }
+
+  /**
+   * 检查是否需要用户确认
+   */
+  needsConfirmation(): boolean {
+    return this.config.requiresConfirmation ?? false;
+  }
+
+  /**
+   * 升级到指定级别
+   */
+  upgradeTo(level: SandboxLevel): void {
+    this.config.level = level;
+    if (level === 4) {
+      this.config.requiresConfirmation = true;
+    }
+  }
+
+  /**
+   * 获取当前配置
+   */
+  getConfig(): SandboxConfig {
+    return { ...this.config };
+  }
+}

package/src/safety/tool-guardrail.ts

@@ -0,0 +1,176 @@
+/**
+ * 工具护栏
+ *
+ * 每次工具调用前检查：
+ * - 命令黑名单
+ * - Sandbox 级别检查
+ * - 速率限制
+ */
+
+import type {
+  ToolCheckResult,
+  ToolViolation,
+  ToolGuardrailConfig,
+  RateLimitState,
+  SandboxLevel,
+} from './types';
+import { Sandbox } from './sandbox';
+
+const DEFAULT_BLACKLISTED_COMMANDS = [
+  'rm -rf /',
+  'rm -rf /*',
+  'mkfs',
+  'dd if=',
+  ':(){:|:&};:',  // fork bomb
+  'chmod -R 777 /',
+  '| sh',
+  '| bash',
+  'eval(',
+  'exec(',
+];
+
+const DEFAULT_RATE_LIMIT = 60; // per minute
+
+export class ToolGuardrail {
+  private blacklistedCommands: string[];
+  private rateLimit: number;
+  private toolSandboxLevels: Record<string, SandboxLevel>;
+  private rateLimitState: Map<string, RateLimitState>;
+  private sandbox: Sandbox;
+
+  constructor(sandbox: Sandbox, config?: ToolGuardrailConfig) {
+    this.sandbox = sandbox;
+    this.blacklistedCommands = config?.blacklistedCommands ?? DEFAULT_BLACKLISTED_COMMANDS;
+    this.rateLimit = config?.rateLimit ?? DEFAULT_RATE_LIMIT;
+    this.toolSandboxLevels = config?.toolSandboxLevels ?? {};
+    this.rateLimitState = new Map();
+  }
+
+  /**
+   * 检查工具调用是否允许
+   */
+  check(toolName: string, command?: string): ToolCheckResult {
+    const violations: ToolViolation[] = [];
+
+    // 命令黑名单检查
+    if (command) {
+      violations.push(...this.checkBlacklist(toolName, command));
+    }
+
+    // Sandbox 级别检查
+    violations.push(...this.checkSandboxLevel(toolName));
+
+    // 速率限制检查
+    violations.push(...this.checkRateLimit(toolName));
+
+    return {
+      allowed: violations.length === 0,
+      violations,
+    };
+  }
+
+  /**
+   * 检查命令黑名单
+   */
+  private checkBlacklist(toolName: string, command: string): ToolViolation[] {
+    const violations: ToolViolation[] = [];
+    const lower = command.toLowerCase();
+
+    for (const blocked of this.blacklistedCommands) {
+      if (lower.includes(blocked.toLowerCase())) {
+        violations.push({
+          type: 'blacklist',
+          severity: 'high',
+          description: `命令包含被阻止的模式: ${blocked}`,
+          toolName,
+        });
+      }
+    }
+
+    return violations;
+  }
+
+  /**
+   * 检查 sandbox 级别
+   */
+  private checkSandboxLevel(toolName: string): ToolViolation[] {
+    const violations: ToolViolation[] = [];
+    const requiredLevel = this.toolSandboxLevels[toolName];
+
+    if (requiredLevel !== undefined) {
+      const result = this.sandbox.check(requiredLevel);
+      if (!result.allowed) {
+        violations.push({
+          type: 'sandbox',
+          severity: 'high',
+          description: result.reason ?? `工具 ${toolName} 需要 Level ${requiredLevel}`,
+          toolName,
+        });
+      }
+    }
+
+    return violations;
+  }
+
+  /**
+   * 检查速率限制
+   */
+  private checkRateLimit(toolName: string): ToolViolation[] {
+    const violations: ToolViolation[] = [];
+    const now = Date.now();
+    const state = this.rateLimitState.get(toolName);
+
+    if (!state) {
+      this.rateLimitState.set(toolName, { count: 1, windowStart: now });
+      return violations;
+    }
+
+    // 重置窗口（1 分钟）
+    if (now - state.windowStart > 60000) {
+      state.count = 1;
+      state.windowStart = now;
+      return violations;
+    }
+
+    state.count++;
+
+    if (state.count > this.rateLimit) {
+      violations.push({
+        type: 'rate_limit',
+        severity: 'medium',
+        description: `工具 ${toolName} 超过速率限制 (${this.rateLimit}/min)`,
+        toolName,
+      });
+    }
+
+    return violations;
+  }
+
+  /**
+   * 添加黑名单命令
+   */
+  addBlacklistedCommand(command: string): void {
+    this.blacklistedCommands.push(command);
+  }
+
+  /**
+   * 设置工具 sandbox 级别要求
+   */
+  setToolSandboxLevel(toolName: string, level: SandboxLevel): void {
+    this.toolSandboxLevels[toolName] = level;
+  }
+
+  /**
+   * 重置速率限制状态
+   */
+  resetRateLimits(): void {
+    this.rateLimitState.clear();
+  }
+
+  /**
+   * 获取 sandbox 实例
+   */
+  getSandbox(): Sandbox {
+    return this.sandbox;
+  }
+}

package/src/safety/types.ts

@@ -0,0 +1,124 @@
+/**
+ * Safety Guardrails 类型定义
+ */
+
+// ── Sandbox ──────────────────────────────────────────────
+
+/** Sandbox 安全级别 */
+export type SandboxLevel = 1 | 2 | 3 | 4;
+
+/** Sandbox 配置 */
+export interface SandboxConfig {
+  level: SandboxLevel;
+  /** 允许写入的目录（Level 2+） */
+  writableDirs?: string[];
+  /** 允许的网络白名单（Level 3） */
+  allowedHosts?: string[];
+  /** 需要用户确认的操作（Level 4） */
+  requiresConfirmation?: boolean;
+}
+
+/** Sandbox 权限检查结果 */
+export interface SandboxCheckResult {
+  allowed: boolean;
+  reason?: string;
+  currentLevel: SandboxLevel;
+  requiredLevel: SandboxLevel;
+}
+
+// ── Input Guardrail ──────────────────────────────────────
+
+/** 输入检查结果 */
+export interface InputCheckResult {
+  safe: boolean;
+  violations: InputViolation[];
+}
+
+/** 输入违规 */
+export interface InputViolation {
+  type: 'injection' | 'intent' | 'permission';
+  severity: 'low' | 'medium' | 'high';
+  description: string;
+  matchedPattern?: string;
+}
+
+/** 输入护栏配置 */
+export interface InputGuardrailConfig {
+  /** 注入检测模式 */
+  injectionPatterns?: RegExp[];
+  /** 禁止的意图关键词 */
+  blockedIntents?: string[];
+  /** 最大输入长度 */
+  maxInputLength?: number;
+}
+
+// ── Output Guardrail ─────────────────────────────────────
+
+/** 输出检查结果 */
+export interface OutputSafetyCheckResult {
+  safe: boolean;
+  violations: OutputViolation[];
+  sanitizedContent?: string;
+}
+
+/** 输出违规 */
+export interface OutputViolation {
+  type: 'sensitive_info' | 'quality' | 'knowledge_missing';
+  severity: 'low' | 'medium' | 'high';
+  description: string;
+  location?: { line: number; column: number };
+  matchedPattern?: string;
+}
+
+/** 输出护栏配置 */
+export interface OutputGuardrailConfig {
+  /** 敏感信息模式（API keys, passwords, etc.） */
+  sensitivePatterns?: RegExp[];
+  /** 代码质量最低分数 */
+  minQualityScore?: number;
+  /** 是否检查知识引用完整性 */
+  checkKnowledgeRefs?: boolean;
+}
+
+// ── Tool Guardrail ───────────────────────────────────────
+
+/** 工具检查结果 */
+export interface ToolCheckResult {
+  allowed: boolean;
+  violations: ToolViolation[];
+}
+
+/** 工具违规 */
+export interface ToolViolation {
+  type: 'blacklist' | 'sandbox' | 'rate_limit';
+  severity: 'low' | 'medium' | 'high';
+  description: string;
+  toolName?: string;
+}
+
+/** 工具护栏配置 */
+export interface ToolGuardrailConfig {
+  /** 命令黑名单 */
+  blacklistedCommands?: string[];
+  /** 每分钟最大调用次数 */
+  rateLimit?: number;
+  /** 各工具的 sandbox 级别要求 */
+  toolSandboxLevels?: Record<string, SandboxLevel>;
+}
+
+/** 速率限制状态 */
+export interface RateLimitState {
+  count: number;
+  windowStart: number;
+}
+
+// ── Aggregate ────────────────────────────────────────────
+
+/** 安全检查汇总 */
+export interface SafetyCheckResult {
+  safe: boolean;
+  inputCheck: InputCheckResult;
+  outputCheck: OutputSafetyCheckResult;
+  toolCheck: ToolCheckResult;
+  timestamp: string;
+}

package/src/spec/CONTEXT.md

@@ -0,0 +1,19 @@
+# spec/
+
+## 职责
+代码注释规范检查：验证代码中的 @spec 注释是否符合规范。
+
+## 核心导出
+- `annotation-checker.ts` — AnnotationChecker: 检查 @spec 注释规范(有效/无效/警告)
+
+## 依赖关系
+- 依赖 `fs` / `path` 文件系统操作
+- 被 `src/cli/commands/spec.ts` CLI 命令消费
+
+## 约定
+- Spec 注释格式由 @spec 标签定义
+- 检查结果包含 valid: boolean + errors + warnings
+
+## 注意事项
+- 无 index.ts 统一导出，独立模块导入
+- 扫描指定目录下所有 TS 文件的 @spec 注释