3.0 KiB
3.0 KiB
데이터 전달 · 에러 핸들링 (ubisam-deliverable-rebuild)
SKILL.md 본문에서 분리한 상세 규약이다. 오케스트레이터가 Phase 1~3 실행 중 참조한다.
데이터 전달 프로토콜
| 대상 | 방식 |
|---|---|
| 진행 추적 | docs/[Ubisam산출물]/_workspace/_progress.md (진실원) + TaskCreate/TaskUpdate(가용 시 보조) |
| 산출물 전달 | 파일 — docs/[Ubisam산출물]/_workspace/{phase}_{agent}_{artifact}.{ext} (예: 01_analyst_sw점검결과.md) |
| 실시간 조율 | SendMessage — to(이름) + summary(5~10단어, 필수) + message. 문서가 여러 건이면 같은 이름의 에이전트가 여러 개 뜬다. 그때는 이름 대신 에이전트 ID로 지정하고, ID를 _progress.md 행에 기록해 둔다 |
| 결과 수집 | Agent 반환값 |
서브에이전트가 오케스트레이터(메인 대화)에 회신할 때는
to: "main"이며, 이는 백그라운드로 기동된 서브에이전트만 쓸 수 있다.
에러 핸들링
재시도 횟수는 docs/[Ubisam산출물]/_workspace/_progress.md의 시도 칸에 기록한다(없으면 0회).
저장소 루트의 _workspace/(PTOP 하네스)와 다른 곳이다 — 베어 경로로 쓰지 않는다.
TaskUpdate가 가용하면 병행 기록해도 되나 판정 근거는 파일이다.
실패 판정 기준(관측 가능해야 한다): ① 에이전트가 에러로 종료 ② 지정 산출 파일이 생성되지 않음
③ 산출 파일이 비었거나 헤더만 있음 — 셋 중 하나면 실패로 본다. 지연은 실패가 아니다.
재시도는 같은 Agent 호출을 다시 하는 것을 뜻한다(SendMessage로 독촉하는 것이 아니다).
| 상황 | 처리 |
|---|---|
| analyst 실패 (2회) | 매핑표가 없으면 재생산 기준이 없다 → 하네스를 중단한다. 중단 전에 00_rebuild_summary.md를 "중단 — analyst 2회 실패" 1섹션만으로 먼저 작성해 흔적을 파일에 남기고, 사용자에게 보고한다. 이 경우만 "진행" 규칙의 예외다 |
| producer/qa 실패 | 1회 재시도. 재실패 시 해당 문서만 건너뛰고 나머지를 계속 진행, 보고서에 누락을 명시 |
| 산출물 파일 잠금 | 작업 사본으로 진행, "산출물 미갱신" 표시 후 사용자에게 파일 닫기 요청. (입력 원본은 읽기 전용이므로 애초에 쓰지 않는다) |
| 에이전트 타입 미등록 | Phase 0 가드에서 중단 → "세션 재시작 필요" 보고 |
| 슬롯 전용 xlsx 스크립트 부재 | producer가 xlsxfill.py 기반으로 신규 작성 (ubisam-producer.md 참조). 수작업 셀 편집은 금지 |
| 데이터 상충 | 삭제하지 않고 출처를 병기 |
| 결함 2회 재작업 후 잔존 | "미해결" 확정, 사용자 판단 항목으로 상신 |
표의 행을 늘리거나 줄이면
SKILL.md본문의 요약 3줄도 같은 편집에서 확인한다 (docs/harness-ptop.md§소비처 확인 의무).