gitea-agent-testbed/docs/interface-contract.md

인터페이스 계약

목적과 범위

이 문서는 대화형 Textual 화면에서 사용자 메시지와 에이전트 응답을 작성자 역할, 라벨, 구조적 스타일 및 표시 순서로 구분하는 인터페이스를 정의한다. 메시지 역할과 본문은 표시 결과의 정본이며, 외부 API 연동이나 영속 저장은 범위에 포함하지 않는다.

계약

• 각 메시지는 작성자 역할과 본문을 함께 가져야 한다.
• 사용자 역할은 user, 에이전트 역할은 agent로 표현한다.
• 사용자 역할의 화면 라벨은 사용자, 에이전트 역할의 화면 라벨은 에이전트다.
• 사용자 메시지는 사용자: 본문 형식으로, 에이전트 응답은 에이전트: 본문 형식으로 표시한다.
• 사용자 메시지는 chat-message user-message user-role 클래스를 사용하고, 에이전트 응답은 chat-message response-message agent-role 클래스를 사용한다.
• 사용자 메시지와 에이전트 응답은 각각 왼쪽과 오른쪽 정렬 및 서로 다른 측면 테두리로 구분한다.
• 유효한 입력 하나는 사용자 메시지 다음에 에이전트 응답을 추가한다.

conversation-message-rendering

메시지 렌더링 인터페이스는 명시적인 역할을 가진 메시지 값을 화면 항목으로 변환한다.

• 입력: 작성자 역할과 문자열 본문을 가진 메시지
• 출력: 작성자 라벨과 본문을 결합한 라벨 위젯
• 사용자 역할: user 값, 사용자 라벨, user-message 및 user-role 클래스
• 에이전트 역할: agent 값, 에이전트 라벨, response-message 및 agent-role 클래스
• 표시 형식: 역할 라벨, 콜론, 공백, 본문 순서
• 구조적 표현: 사용자 항목은 왼쪽 정렬과 왼쪽 테두리, 에이전트 항목은 오른쪽 정렬과 오른쪽 테두리
• 순서: 유효한 제출마다 사용자 메시지를 먼저 표시하고 대응하는 에이전트 응답을 바로 뒤에 표시

역할과 본문은 하나의 메시지 의미로 취급하며, 라벨과 스타일은 역할에서 파생한다. 화면의 위치나 스타일만으로 작성자를 판정해서는 안 된다. 메시지 본문은 사용자 입력의 앞뒤 공백을 제거한 값 또는 고정 응답 목록에서 선택된 값이어야 한다.

빈 입력이나 공백만 포함한 입력은 정상적인 렌더링 요청으로 간주하지 않는다. 이 경우 응답을 선택하지 않고 메시지 목록과 대화 영역을 변경하지 않으며, 입력창만 비운다.

호환성을 위해 기존 대화 영역과 입력창의 위젯 식별자, 사용자 및 응답 항목의 클래스, Enter 제출, 고정 응답 선택, Escape와 Ctrl+Q 종료 동작을 유지한다. 작성자 라벨과 역할 클래스는 기존 표시 항목에 추가되는 계약이며, 대화 영역 전체 레이아웃을 재설계하지 않는다.

검증에서는 정상 입력 두 건을 제출하여 역할, 본문, 라벨, 클래스 및 표시 순서를 함께 비교한다. 역할별 정렬과 테두리 규칙이 색상과 독립적으로 존재하는지 확인하고, 빈 입력과 공백 입력에서 응답 선택과 새 화면 항목이 발생하지 않는지 확인한다. 또한 표준 응답 선택 호출과 종료 동작이 기존 방식대로 유지되는지 확인한다.

호환성

• Enter로 제출하는 기존 입력 방식을 유지한다.
• 입력은 앞뒤 공백을 제거한 뒤 처리하며, 빈 입력이나 공백만 있는 입력은 응답 선택과 화면 변경 없이 무시한다.
• 응답은 기존 고정 응답 목록에서 표준 무작위 선택 방식으로 생성한다.
• 기존 대화 영역과 입력창의 위젯 식별자 및 메시지 표시 순서를 유지한다.
• Escape와 Ctrl+Q 종료 동작을 유지한다.
• 역할 의미는 화면 위치나 CSS 클래스만으로 추론하지 않고 메시지 데이터에서 직접 제공한다.

예시

• 입력값이 첫 번째 입력 이면 사용자: 첫 번째 입력으로 표시한다.
• 선택된 응답이 맡겨만 주세요.이면 에이전트: 맡겨만 주세요.로 표시한다.
• 여러 제출은 각 제출마다 사용자 메시지와 에이전트 응답의 쌍을 만들며, 전체 순서는 제출 순서와 일치한다.
• 사용자 항목에는 왼쪽 정렬과 왼쪽 테두리를 적용하고, 에이전트 항목에는 오른쪽 정렬과 오른쪽 테두리를 적용한다.
• 빈 문자열 또는 공백 문자열을 제출하면 새 라벨과 응답이 생성되지 않는다.

검증

• 역할 값과 본문이 올바르게 결합되어 메모리의 메시지 목록에 보존되는지 확인한다.
• 렌더링된 라벨이 역할별 접두사와 본문을 정확히 포함하는지 확인한다.
• 역할별 CSS 클래스, 정렬 규칙 및 양쪽 테두리가 구현에 존재하는지 확인한다.
• 여러 입력에서 사용자 메시지 뒤에 에이전트 응답이 표시되는지 확인한다.
• 빈 입력과 공백 입력에서 응답 선택, 메시지 기록 및 라벨 추가가 발생하지 않는지 확인한다.
• 기존 무작위 응답 선택과 종료 동작이 변경되지 않았는지 회귀 검증한다.