Claude Code 架构解析：文件工具

1
2
3
4
5
6
7
8

export const FileReadTool = buildTool({
  name: FILE_READ_TOOL_NAME,
  maxResultSizeChars: Infinity,  // 关键：读结果永不持久化
  strict: true,
  isConcurrencySafe() { return true },
  isReadOnly() { return true },
  // ...
} satisfies ToolDef<InputSchema, Output>)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

async validateInput({ file_path, pages }, toolUseContext) {
  // 第 1 关：PDF 页码参数纯字符串校验
  if (pages !== undefined) {
    const parsed = parsePDFPageRange(pages)
    if (!parsed) return { result: false, message: '...', errorCode: 7 }
    if (rangeSize > PDF_MAX_PAGES_PER_READ) return { result: false, errorCode: 8 }
  }

  // 第 2 关：路径展开 + deny 规则（无 I/O）
  const fullFilePath = expandPath(file_path)
  const denyRule = matchingRuleForInput(fullFilePath, ..., 'read', 'deny')
  if (denyRule !== null) return { result: false, errorCode: 1 }

  // 第 3 关：UNC 路径提前放行（避免触发 SMB 认证）
  if (fullFilePath.startsWith('\\\\') || fullFilePath.startsWith('//'))
    return { result: true }  // 交给权限系统处理

  // 第 4 关：二进制扩展名检查（纯字符串匹配）
  if (hasBinaryExtension(fullFilePath) && !isPDFExtension(ext) && !IMAGE_EXTENSIONS.has(...))
    return { result: false, errorCode: 4 }

  // 第 5 关：设备文件黑名单（防止进程挂起）
  if (isBlockedDevicePath(fullFilePath))
    return { result: false, errorCode: 9 }

  return { result: true }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

const BLOCKED_DEVICE_PATHS = new Set([
  '/dev/zero',    // 无限输出 — 永远到不了 EOF
  '/dev/random',  // 同上
  '/dev/urandom', // 同上
  '/dev/full',    // 同上
  '/dev/stdin',   // 阻塞等待输入
  '/dev/tty',     // 同上
  '/dev/console', // 同上
  '/dev/stdout',  // 读 stdout 毫无意义
  '/dev/stderr',  // 同上
  '/dev/fd/0', '/dev/fd/1', '/dev/fd/2',  // stdio 的 fd 别名
])

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// 检查 readFileState 中是否有该文件的记录
const readTimestamp = toolUseContext.readFileState.get(fullFilePath)
if (!readTimestamp || readTimestamp.isPartialView) {
  return {
    result: false,
    behavior: 'ask',
    message: 'File has not been read yet. Read it first before writing to it.',
    errorCode: 6,
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

export function checkReadPermissionForTool(tool, input, toolPermissionContext) {
  const pathsToCheck = getPathsForPermissionCheck(path)  // 预计算，避免重复 syscall

  // 第 1 步：UNC 路径拦截（defense-in-depth）
  for (const p of pathsToCheck) {
    if (p.startsWith('\\\\') || p.startsWith('//'))
      return { behavior: 'ask', ... }
  }

  // 第 2 步：Windows 可疑路径模式
  for (const p of pathsToCheck) {
    if (hasSuspiciousWindowsPathPattern(p))
      return { behavior: 'ask', ... }
  }

  // 第 3 步：deny 规则（优先级最高）
  for (const p of pathsToCheck) {
    const denyRule = matchingRuleForInput(p, ..., 'read', 'deny')
    if (denyRule) return { behavior: 'deny', ... }
  }

  // 第 4 步：ask 规则
  for (const p of pathsToCheck) {
    const askRule = matchingRuleForInput(p, ..., 'read', 'ask')
    if (askRule) return { behavior: 'ask', ... }
  }

  // 第 5 步：编辑权限隐含读取权限
  const editResult = checkWritePermissionForTool(tool, input, ...)
  if (editResult.behavior === 'allow') return editResult

  // 第 6 步：工作目录隐含允许读取
  if (pathInAllowedWorkingPath(path, ...))
    return { behavior: 'allow', ... }

  // 第 7 步：内部可读路径（session-memory、plans、tool-results）
  const internalReadResult = checkReadableInternalPath(absolutePath, input)
  if (internalReadResult.behavior !== 'passthrough') return internalReadResult

  // 第 8 步：allow 规则
  const allowRule = matchingRuleForInput(path, ..., 'read', 'allow')
  if (allowRule) return { behavior: 'allow', ... }

  // 默认：ask
  return { behavior: 'ask', ... }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

export function checkWritePermissionForTool(tool, input, ...) {
  // 第 1 步：deny 规则
  // 第 1.5 步：内部可编辑路径（plan、scratchpad、agent memory）
  // 第 1.6 步：.claude/ 目录的 session-only allow 规则
  // 第 1.7 步：安全检查（危险文件、危险目录、Claude 配置）
  // 第 2 步：ask 规则
  // 第 3 步：acceptEdits 模式下的工作目录放行
  // 第 4 步：allow 规则
  // 第 5 步：默认 ask
}

1
2
3
4
5
6
7

const DANGEROUS_FILES = [
  '.gitconfig', '.gitmodules', '.bashrc', '.bash_profile',
  '.zshrc', '.zprofile', '.profile', '.ripgreprc',
  '.mcp.json', '.claude.json',
]

const DANGEROUS_DIRECTORIES = ['.git', '.vscode', '.idea', '.claude']

1
2
3
4
5
6
7
8

checkEditableInternalPath(absolutePath, input) {
  if (isSessionPlanFile(normalizedPath)) return 'allow'     // plan 文件
  if (isScratchpadPath(normalizedPath)) return 'allow'       // scratchpad
  if (isAgentMemoryPath(normalizedPath)) return 'allow'      // agent 记忆
  if (isAutoMemPath(normalizedPath)) return 'allow'          // 跨会话记忆
  // ... 还有 job 目录
  return 'passthrough'
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

export function getPathsForPermissionCheck(inputPath: string): string[] {
  const pathSet = new Set<string>()
  pathSet.add(path)  // 始终检查原始路径

  // UNC 路径：不追踪，直接返回
  if (path.startsWith('//') || path.startsWith('\\\\'))
    return Array.from(pathSet)

  let currentPath = path
  const visited = new Set<string>()
  const maxDepth = 40  // 匹配 POSIX SYMLOOP_MAX

  for (let depth = 0; depth < maxDepth; depth++) {
    if (visited.has(currentPath)) break  // 循环 symlink 检测
    visited.add(currentPath)

    if (!fsImpl.existsSync(currentPath)) {
      // 路径不存在（可能是新文件写入场景）
      // 向上回溯找到最深的存在祖先，解析其 symlink
      if (currentPath === path) {
        const resolved = resolveDeepestExistingAncestorSync(fsImpl, path)
        if (resolved !== undefined) pathSet.add(resolved)
      }
      break
    }

    const stats = fsImpl.lstatSync(currentPath)

    // FIFO/socket/设备文件：不追踪（避免阻塞）
    if (stats.isFIFO() || stats.isSocket() || stats.isCharacterDevice() || stats.isBlockDevice())
      break

    if (!stats.isSymbolicLink()) break  // 普通文件：停止

    const target = fsImpl.readlinkSync(currentPath)
    const absoluteTarget = nodePath.isAbsolute(target)
      ? target
      : nodePath.resolve(nodePath.dirname(currentPath), target)
    pathSet.add(absoluteTarget)  // 收集中间目标
    currentPath = absoluteTarget
  }

  // 最终用 realpathSync 补漏
  const { resolvedPath, isSymlink } = safeResolvePath(fsImpl, path)
  if (isSymlink && resolvedPath !== path) pathSet.add(resolvedPath)

  return Array.from(pathSet)
}

1
2
3
4
5
6
7
8
9

const FAST_PATH_MAX_SIZE = 10 * 1024 * 1024  // 10 MB

const stats = await fsStat(filePath)

if (stats.isFile() && stats.size < FAST_PATH_MAX_SIZE) {
  // 快速路径：readFile + 内存分割
} else {
  // 流式路径：createReadStream + indexOf('\n') 手动分页
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

function readFileInRangeFast(raw, mtimeMs, offset, maxLines, truncateAtBytes) {
  const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw  // 去除 BOM

  const selectedLines: string[] = []
  let lineIndex = 0, startPos = 0

  while ((newlinePos = text.indexOf('\n', startPos)) !== -1) {
    if (lineIndex >= offset && lineIndex < endLine && !truncatedByBytes) {
      let line = text.slice(startPos, newlinePos)
      if (line.endsWith('\r')) line = line.slice(0, -1)  // CRLF → LF
      tryPush(line)
    }
    lineIndex++
    startPos = newlinePos + 1
  }
  // 处理最后没有换行符的行...
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

type StreamState = {
  stream: ReturnType<typeof createReadStream>
  offset: number
  endLine: number
  selectedLines: string[]
  partial: string          // 跨 chunk 的不完整行
  currentLineIndex: number
  // ...
}

function streamOnData(this: StreamState, chunk: string): void {
  // 第一个 chunk 检查 BOM
  if (this.isFirstChunk) {
    this.isFirstChunk = false
    if (chunk.charCodeAt(0) === 0xfeff) chunk = chunk.slice(1)
  }

  // 拼接上一轮的 partial
  const data = this.partial.length > 0 ? this.partial + chunk : chunk
  this.partial = ''

  let startPos = 0
  while ((newlinePos = data.indexOf('\n', startPos)) !== -1) {
    if (this.currentLineIndex >= this.offset && this.currentLineIndex < this.endLine) {
      let line = data.slice(startPos, newlinePos)
      if (line.endsWith('\r')) line = line.slice(0, -1)
      this.selectedLines.push(line)
    }
    this.currentLineIndex++  // 范围外的行只计数
    startPos = newlinePos + 1
  }

  // 保留尾部 fragment（仅在选中范围内）
  if (startPos < data.length) {
    if (this.currentLineIndex >= this.offset && this.currentLineIndex < this.endLine) {
      this.partial = data.slice(startPos)
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

async function validateContentTokens(content, ext, maxTokens) {
  // 阶段 1：粗估（免费，纯计算）
  const tokenEstimate = roughTokenCountEstimationForFileType(content, ext)
  if (!tokenEstimate || tokenEstimate <= effectiveMaxTokens / 4) return

  // 阶段 2：精确计数（需要 API 调用）
  const tokenCount = await countTokensWithAPI(content)
  const effectiveCount = tokenCount ?? tokenEstimate
  if (effectiveCount > effectiveMaxTokens)
    throw new MaxFileReadTokenExceededError(effectiveCount, effectiveMaxTokens)
}

1
2
3
4

const readTimestamp = toolUseContext.readFileState.get(fullFilePath)
if (!readTimestamp || readTimestamp.isPartialView) {
  return { result: false, message: 'File has not been read yet...', errorCode: 6 }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// validateInput 中的检查（异步，允许 I/O）
if (readTimestamp) {
  const lastWriteTime = getFileModificationTime(fullFilePath)
  if (lastWriteTime > readTimestamp.timestamp) {
    // Windows 特殊处理：mtime 变了但内容可能没变（云同步、杀毒软件）
    const isFullRead = readTimestamp.offset === undefined && readTimestamp.limit === undefined
    if (isFullRead && fileContent === readTimestamp.content) {
      // 内容未变，安全继续
    } else {
      return { result: false, message: 'File has been modified since read...', errorCode: 7 }
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

async call(input, { readFileState, ... }) {
  // 这些 await 必须在临界区之前——mkdir 和备份可以异步
  await fs.mkdir(dirname(absoluteFilePath))
  await fileHistoryTrackEdit(...)

  // === 临界区开始：中间不能有 yield ===
  const { content: originalFileContents, ... } = readFileForEdit(absoluteFilePath)
  // mtime 再次检查
  const lastWriteTime = getFileModificationTime(absoluteFilePath)
  if (lastWriteTime > lastRead.timestamp) { ... }
  // 生成 patch
  const { patch, updatedFile } = getPatchForEdit(...)
  // 写入磁盘
  writeTextContent(absoluteFilePath, updatedFile, encoding, endings)
  // === 临界区结束 ===
}

1
2
3
4
5
6
7

if (fileHistoryEnabled()) {
  await fileHistoryTrackEdit(
    updateFileHistoryState,
    absoluteFilePath,
    parentMessage.uuid,
  )
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

const existingState = readFileState.get(fullFilePath)
if (existingState && !existingState.isPartialView && existingState.offset !== undefined) {
  const rangeMatch = existingState.offset === offset && existingState.limit === limit
  if (rangeMatch) {
    const mtimeMs = await getFileModificationTimeAsync(fullFilePath)
    if (mtimeMs === existingState.timestamp) {
      logEvent('tengu_file_read_dedup', { ext: analyticsExt })
      return { data: { type: 'file_unchanged', file: { filePath: file_path } } }
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

const THIN_SPACE = String.fromCharCode(8239)  // U+202F 窄不换行空格

function getAlternateScreenshotPath(filePath: string): string | undefined {
  const filename = path.basename(filePath)
  const amPmPattern = /^(.+)([ \u202F])(AM|PM)(\.png)$/
  const match = filename.match(amPmPattern)
  if (!match) return undefined

  const currentSpace = match[2]
  const alternateSpace = currentSpace === ' ' ? THIN_SPACE : ' '
  return filePath.replace(
    `${currentSpace}${match[3]}${match[4]}`,
    `${alternateSpace}${match[3]}${match[4]}`,
  )
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

export async function readImageWithTokenBudget(filePath, maxTokens, maxBytes) {
  // 1. 只读一次文件
  const imageBuffer = await getFsImplementation().readFileBytes(filePath, maxBytes)

  // 2. 标准缩放
  const resized = await maybeResizeAndDownsampleImageBuffer(imageBuffer, ...)
  let result = createImageResponse(resized.buffer, ...)

  // 3. 检查 token 预算
  const estimatedTokens = Math.ceil(result.file.base64.length * 0.125)
  if (estimatedTokens > maxTokens) {
    // 4. 激进压缩（从同一 buffer，不重新读文件）
    const compressed = await compressImageBufferWithTokenLimit(imageBuffer, maxTokens, ...)
    return { type: 'image', file: { base64: compressed.base64, ... } }
  }

  return result
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

export function findActualString(fileContent, searchString): string | null {
  if (fileContent.includes(searchString)) return searchString  // 精确匹配

  // 尝试引号归一化
  const normalizedSearch = normalizeQuotes(searchString)
  const normalizedFile = normalizeQuotes(fileContent)
  const searchIndex = normalizedFile.indexOf(normalizedSearch)
  if (searchIndex !== -1) {
    return fileContent.substring(searchIndex, searchIndex + searchString.length)
  }
  return null
}

1
2
3
4
5

export function preserveQuoteStyle(oldString, actualOldString, newString) {
  if (oldString === actualOldString) return newString  // 没发生归一化
  // 检测 actualOldString 中的弯引号类型
  // 将 new_string 中的对应直引号替换为弯引号
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

export function expandPath(path: string, baseDir?: string): string {
  // 第 1 步：null byte 检查（安全：防止路径注入）
  if (path.includes('\0') || actualBaseDir.includes('\0'))
    throw new Error('Path contains null bytes')

  // 第 2 步：空白修剪
  const trimmedPath = path.trim()

  // 第 3 步：~ 展开
  if (trimmedPath === '~') return homedir().normalize('NFC')
  if (trimmedPath.startsWith('~/'))
    return join(homedir(), trimmedPath.slice(2)).normalize('NFC')

  // 第 4 步：Windows POSIX 路径转换（/c/Users/ → C:\Users\）
  if (getPlatform() === 'windows' && trimmedPath.match(/^\/[a-z]\//i))
    processedPath = posixPathToWindowsPath(trimmedPath)

  // 第 5 步：绝对/相对路径解析 + NFC 规范化
  if (isAbsolute(processedPath))
    return normalize(processedPath).normalize('NFC')
  return resolve(actualBaseDir, processedPath).normalize('NFC')
}

1
2
3
4
5

// FileReadTool
maxResultSizeChars: Infinity,

// FileEditTool
maxResultSizeChars: 100_000,

1

if (isUncPath) return { result: true }  // 看似矛盾

1

if (existingState && !existingState.isPartialView && existingState.offset !== undefined)

1
2
3
4
5
6

if (lastWriteTime > readTimestamp.timestamp) {
  const isFullRead = readTimestamp.offset === undefined && readTimestamp.limit === undefined
  if (isFullRead && fileContent === readTimestamp.content) {
    // 内容未变，安全继续
  }
}