파일시스템 및 셸 도구

Triggerfish는 에이전트에게 읽기, 쓰기, 검색, 명령 실행을 위한 범용 파일시스템 및 셸 도구를 제공합니다. 이는 다른 기능(exec 환경, 탐색, 스킬)이 기반하는 기본 도구입니다.

도구

read_file

절대 경로의 파일 내용을 읽습니다.

매개변수	유형	필수	설명
path	string	예	읽을 절대 파일 경로

파일의 전체 텍스트 내용을 반환합니다.

write_file

워크스페이스 상대 경로의 파일에 콘텐츠를 씁니다.

매개변수	유형	필수	설명
path	string	예	워크스페이스 내 상대 경로
content	string	예	쓸 파일 내용

쓰기는 에이전트의 워크스페이스 디렉터리로 범위가 지정됩니다. 에이전트는 파일시스템의 임의 위치에 쓸 수 없습니다.

edit_file

파일에서 고유한 문자열을 교체합니다. old_text는 파일에서 정확히 한 번 나타나야 합니다.

매개변수	유형	필수	설명
path	string	예	편집할 절대 파일 경로
old_text	string	예	찾을 정확한 텍스트 (파일에서 고유해야 함)
new_text	string	예	교체 텍스트

이것은 정밀 편집 도구입니다 -- 하나의 정확한 일치를 찾아 교체합니다. 텍스트가 두 번 이상 나타나거나 전혀 나타나지 않으면 작업이 오류와 함께 실패합니다.

list_directory

주어진 절대 경로의 파일과 디렉터리를 나열합니다.

매개변수	유형	필수	설명
path	string	예	나열할 절대 디렉터리 경로

디렉터리에는 / 접미사가 있는 항목을 반환합니다.

search_files

glob 패턴과 일치하는 파일을 검색하거나 grep으로 파일 내용을 검색합니다.

매개변수	유형	필수	설명
path	string	예	검색할 디렉터리
pattern	string	예	파일 이름의 glob 패턴 또는 파일 내 검색할 텍스트/정규식
content_search	boolean	아니오	true이면 파일 이름 대신 파일 내용을 검색

run_command

에이전트 워크스페이스 디렉터리에서 셸 명령을 실행합니다.

매개변수	유형	필수	설명
command	string	예	실행할 셸 명령

stdout, stderr, 종료 코드를 반환합니다. 명령은 에이전트의 워크스페이스 디렉터리에서 실행됩니다. PRE_TOOL_CALL hook이 실행 전에 거부 목록에 대해 명령을 확인합니다.

다른 도구와의 관계

이 파일시스템 도구는 Exec 환경 도구(exec.write, exec.read, exec.run, exec.ls)와 중첩됩니다. 차이점:

• 파일시스템 도구는 절대 경로와 에이전트의 기본 워크스페이스에서 작동합니다. 항상 사용 가능합니다.
• Exec 도구는 명시적 격리, 테스트 러너, 패키지 설치가 있는 구조화된 워크스페이스 내에서 작동합니다. exec 환경 통합의 일부입니다.

에이전트는 일반 파일 작업에 파일시스템 도구를 사용하고 개발 워크플로우(쓰기/실행/수정 루프)에서 작업할 때 exec 도구를 사용합니다.

보안

• write_file은 에이전트의 워크스페이스 디렉터리로 범위가 지정됩니다
• run_command는 명령을 컨텍스트로 하여 PRE_TOOL_CALL hook을 통과합니다
• 명령 거부 목록이 위험한 작업을 차단합니다 (rm -rf /, sudo 등)
• 모든 도구 응답은 분류 및 taint 추적을 위해 POST_TOOL_RESPONSE를 통과합니다
• 플랜 모드에서는 계획이 승인될 때까지 write_file이 차단됩니다