중단점 디버깅

Braidrun의 디버거는 대화형 브레이크포인트 디버거입니다: 임의의 단계에 브레이크포인트를 설정하고, 일시 중지 후 변수를 보고, 다 고친 뒤 계속하거나, 한 칸씩 스텝을 밟아 내려갑니다. 경험은 일반 코드를 디버깅하는 것과 같습니다.

디버그 켜기

"실행" 팝업 창에서 확인란을 선택합니다.

• 디버그 활성화 — 디버깅 모드를 켜고 실행 세부정보 페이지에 디버깅 패널을 표시합니다.
• 입장이 일시중지됨 — 첫 번째 단계 전에 자동으로 일시중지
• 예외 시 일시 중지 — 단계가 실패하면 자동으로 일시 중지
• 미리보기 — 팝업 하단의 "드라이런" 버튼은 실행 계획만 검증하고 실제로 실행하지 않습니다

9가지 브레이크포인트 유형

각 브레이크포인트에는 몇 가지 선택 필드가 더 있습니다:

• stepName — 지정한 단계만 명중(대소문자 구분 안 함). 비워 두면 해당 유형의 모든 위치를 명중
• condition — 조건 표현식으로, 충족될 때만 실제로 중단하며 문법은 workflow의 condition과 동일합니다
• once — 한 번 명중한 뒤 자동으로 비활성화

하위 워크플로 디버깅

브레이크포인트는 기본적으로 모든 계층에 적용됩니다: 상위 워크플로에서 설정한 브레이크포인트는 하위 워크플로가 동명 단계를 실행할 때도 마찬가지로 명중합니다.sub_workflow_entry / sub_workflow_exit 이 두 종류의 브레이크포인트는 상위 단계에 걸리며, 각각 하위 워크플로 진입 전과 반환 후에 멈추어 전달된 inputs와 기록된 outputs를 검사하기 편합니다.

같은 하위 워크플로(예: 마켓 모듈 하나)가 여러 상위 단계에서 재사용될 때, 디버깅 엔진은 브레이크포인트에 parentPath 필터 추가를 지원합니다: 브레이크포인트는 하위 워크플로가 지정한 상위 단계 경로를 통해 호출될 때만 명중하며, 다른 호출 경로의 동명 단계는 중단하지 않습니다.

디버그 패널

디버그 컨트롤은 모두 실행 상세 페이지의 디버그 패널 안에 있으며, 별도의 디버거 창은 없습니다:

• 집행 통제：일시 중지 / 계속 / 스텝 버튼. 상단에 현재 일시 중지 위치를 실시간으로 표시
• 상황별 보기：변수, 단계 출력, 단계 결과 요약
• 스냅샷 이력：각 체크포인트를 지날 때마다 컨텍스트 스냅샷 한 부를 자동으로 남기며(최근 50부까지 유지), 타임라인을 드래그하면 임의의 일시 중지 시점의 변수를 되돌아보고 Diff로 전후 변화를 비교할 수 있습니다
• 변수 편집：일시 정지된 동안 변수 값을 두 번 클릭하여 수정하세요.
• DAG 시각화：중단점 마커를 표시하고 DAG 다이어그램에 직접 강조 표시를 일시중지합니다.
• 로그 스트림：실행 세부정보 페이지 하단에 있는 터미널 스타일 로그 패널

REST로 디버그 제어

디버그 패널 이면에는 REST 엔드포인트 한 세트가 있어, 스크립트로 문제를 진단할 때 직접 호출할 수 있습니다(패널과 동일한 인터페이스):

접두사는 모두 /api/executions/{executionId}입니다. 예:

# 给 fetch_data 步骤加断点,再加一个"出错即停"的一次性断点
curl -X PUT https://braidrun.com/api/executions/<execution-id>/debug/breakpoints \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "breakpoints": [
      {"point": "before_step", "stepName": "fetch_data"},
      {"point": "step_error", "once": true}
    ]
  }'

# 暂停 / 单步 / 继续
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/pause \
  -H "Authorization: Bearer <token>"
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/step \
  -H "Authorization: Bearer <token>"
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/continue \
  -H "Authorization: Bearer <token>"

일시 중지 시 변수를 바꾸고 이어서 실행

일반적인 시나리오: 상류 단계가 명백히 잘못된 파라미터를 계산했을 때, 브레이크포인트에서 멈춘 뒤 변수를 바로 올바르게 고치고 "계속"을 클릭하면, 이후 단계는 새 값으로 실행되어 한 라운드를 통째로 다시 하는 것을 아낍니다. 패널에서는 변수 값을 더블클릭하면 편집할 수 있고, REST는 POST /debug/variables, 실행이 일시 중지 상태일 때만 수정을 받습니다.

# 暂停态下把变量改对,然后 continue
curl -X POST https://braidrun.com/api/executions/<execution-id>/debug/variables \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"variables": {"target_country": "US"}}'

지정한 단계부터 재실행

실행이 종료 상태에 도달한 뒤(완료, 실패 또는 취소), 어떤 단계부터 재실행할 수 있습니다: 실행 타임라인이나 단계 상세 패널에서 "이 단계부터 재실행"을 클릭합니다. 재실행 지점 이전의 단계 결과는 원래대로 유지되며, 이미 완료된 LLM 단계는 모델을 다시 호출하지 않으므로 중복 token 비용이 발생하지 않습니다.

• 재실행 지점은 반드시 이번 실행에서 실제로 실행된 단계여야 합니다. 첫 단계부터 재실행하는 것은 전체 재실행과 같으며 이 제한을 받지 않습니다
• 실행이 아직 진행 중일 때는 재실행할 수 없으며, 먼저 취소하거나 끝날 때까지 기다립니다
• REST:POST /api/executions/{executionId}/restart-from-step, body의 stepName을 비워 두면 처음부터 재실행을 의미합니다

현재 제한 사항

• 주로 단계 경계 및 복합 노드 핵심 지점에서 일시 중지
• 도구/토큰 스트림 내부에 걸리지 않습니다.
• 디버깅이 활성화되면 최상위 동시성이 직렬화됩니다.

다음 단계

• 스케줄링 — 디버그 통과 워크플로를 cron/webhook에 연결
• 자동 재개 — 디버깅 후 어떤 단계가 멱등성인지 결정