human-in-the-loop

Human in the Loop (사람 개입)

소유자와 에이전트 사이의 일회용 인터페이스 계층입니다. 에이전트는 소유자가 검토하고 결정해야 할 내용을 설명하고, 스크립트는 독립형 HTML 페이지를 조립합니다. 소유자는 브라우저에서 자유롭게 응답하고 JSON을 반환합니다. 페이지는 직접 작성하지 않습니다. spec.json과 scripts/build.py만 사용합니다.

$SKILL은 이 파일이 위치한 폴더를 의미합니다.

언제 사용할까

• 승인 문서: 명세서, PRD, 제안서, 계획. 섹션별 상태, 텍스트 직접 수정, 개방형 질문에 대한 답변.
• 여러 질문에 대한 선택: 한 번에 여러 질문에 대해 각 질문별 에이전트의 옵션과 사용자 답변.
• 블라인드 라벨링: 소유자가 응답하고, 모델의 응답은 별도 파일에 저장되어 페이지에 표시되지 않음. 이후 score.py로 일치율 계산.
• 척도 평가: 제안을 척도로 평가.

질문이 하나나 두 개뿐이라면 채팅에서 직접 물어보세요.

워크플로우

1. Spec. spec.json을 생성하세요 (형식: references/spec-format.md). Markdown 문서용 템플릿이 준비되어 있습니다: python3 $SKILL/scripts/from_markdown.py doc.md --options options.json -o spec.json (## 및 ### 섹션은 수정 가능한 블록이 되고, '열린 질문(Open questions)' 섹션은 options.json의 옵션과 함께 질문이 됩니다). 블라인드 라벨링의 경우 숨겨진 응답은 별도의 sidecar.json에 저장하고, spec.json에는 포함하지 마세요.
2. 페이지. python3 $SKILL/scripts/build.py spec.json -o page.html 명령어로 페이지를 조립하고 엽니다. spec과 페이지는 프로젝트 옆(예: private/)에 두세요. 스크래치패드(scratchpad)가 아닌 곳에 두어 소유자가 다시 돌아올 수 있게 하세요. 한 줄로 소유자에게 무엇이 열렸고 무엇을 해야 하는지 알려주세요.
3. 소유자가 응답하고 채팅에 JSON을 붙여넣습니다 ('Copy JSON for agent' 버튼). JSON에는 소유자가 건드린 내용만 포함됩니다: status, comment, markdown_old/markdown_new, answers, notes, decision, general_comment.
4. 에이전트가 응답을 적용합니다. JSON의 task 필드를 기준으로 응답을 적용하고, 무엇을 변경했고 무엇이 남았는지 보고합니다. 결정 버튼이 있는데 decision이 비어 있다면 결정이 내려지지 않은 것입니다: 다시 물어보고, 문서가 승인된 것으로 간주하지 마세요. 라벨링의 경우 JSON을 저장한 후 다음을 실행하세요: python3 $SKILL/scripts/score.py labels.json sidecar.json --spec spec.json 불일치 사항은 목록으로 소유자에게 보여주고, 라벨링 오류는 직접 수정하지 마세요.

spec이 변경되면 페이지는 새 버전으로 다시 조립되며, 이전 브라우저 응답은 새 페이지에 적용되지 않습니다.

테스트

python3 $SKILL/tests/selftest.py [폴더] 명령어는 examples/의 두 예제를 조립하고, headless Chromium에서 실행한 후 내보내기를 검증합니다. 템플릿이나 스크립트를 수정한 후에는 반드시 실행하세요.