深度防御验证Skill defense-in-depth

---

name: 深度防御验证 description: 当无效数据导致深层执行失败时使用，需要在多个系统层进行验证 - 在数据通过的每一层进行验证，使错误在结构上不可能发生

深度防御验证

概述

当您修复由无效数据引起的错误时，在一个地方添加验证感觉足够。但那个单一检查可能被不同的代码路径、重构或模拟绕过。

核心原则： 在数据通过的每一层进行验证。使错误在结构上不可能发生。

为什么需要多层

单一验证：“我们修复了错误” 多层验证：“我们使错误不可能发生”

不同层捕获不同情况：

• 入口验证捕获大多数错误
• 业务逻辑捕获边缘情况
• 环境守卫防止特定上下文中的危险
• 调试日志帮助当其他层失败时

四层

层1：入口点验证

目的： 在API边界拒绝明显无效的输入

function createProject(name: string, workingDirectory: string) {
  if (!workingDirectory || workingDirectory.trim() === '') {
    throw new Error('workingDirectory cannot be empty');
  }
  if (!existsSync(workingDirectory)) {
    throw new Error(`workingDirectory does not exist: ${workingDirectory}`);
  }
  if (!statSync(workingDirectory).isDirectory()) {
    throw new Error(`workingDirectory is not a directory: ${workingDirectory}`);
  }
  // ... 继续
}

层2：业务逻辑验证

目的： 确保数据对此操作有意义

function initializeWorkspace(projectDir: string, sessionId: string) {
  if (!projectDir) {
    throw new Error('projectDir required for workspace initialization');
  }
  // ... 继续
}

层3：环境守卫

目的： 在特定上下文中防止危险操作

async function gitInit(directory: string) {
  // 在测试中，拒绝在临时目录外进行git init
  if (process.env.NODE_ENV === 'test') {
    const normalized = normalize(resolve(directory));
    const tmpDir = normalize(resolve(tmpdir()));

    if (!normalized.startsWith(tmpDir)) {
      throw new Error(
        `Refusing git init outside temp dir during tests: ${directory}`
      );
    }
  }
  // ... 继续
}

层4：调试仪器

目的： 捕获上下文以供取证

async function gitInit(directory: string) {
  const stack = new Error().stack;
  logger.debug('About to git init', {
    directory,
    cwd: process.cwd(),
    stack,
  });
  // ... 继续
}

应用模式

当您发现错误时：

1. 跟踪数据流 - 坏值起源于哪里？在哪里使用？
2. 映射所有检查点 - 列出数据通过的每个点
3. 在每一层添加验证 - 入口、业务、环境、调试
4. 测试每一层 - 尝试绕过层1，验证层2捕获它

会话示例

错误：空的projectDir导致源代码中的git init

数据流：

1. 测试设置 → 空字符串
2. Project.create(name, '')
3. WorkspaceManager.createWorkspace('')
4. git init在process.cwd()中运行

添加的四层：

• 层1：Project.create()验证不为空/存在/可写
• 层2：WorkspaceManager验证projectDir不为空
• 层3：WorktreeManager在测试中拒绝在tmpdir外进行git init
• 层4：git init前进行堆栈跟踪日志

结果： 所有1847个测试通过，错误无法再现

关键洞察

所有四层都是必要的。在测试期间，每一层捕获了其他层错过的错误：

• 不同的代码路径绕过了入口验证
• 模拟绕过了业务逻辑检查
• 不同平台上的边缘情况需要环境守卫
• 调试日志识别了结构误用

不要只在一个验证点停止。 在每一层添加检查。