어떻게? 이로케. 홈 검색

WEBBOOK CHAPTER

Kimi·Qwen·GLM 중국 AI 에이전트 실전: 18장 BridgePilot을 출시하고 다음 모델에 대비한다

18장 BridgePilot을 출시하고 다음 모델에 대비한다

출시 판정은 기능, 근거, 보안, 운영의 네 게이트다. 기능은 핵심 사용자 여정, 근거는 원문 역추적과 사람 승인, 보안은 비밀·권한·주입, 운영은 비용·재시도·중단 기준을 본다.

호환 행렬에는 fixture, 웹/CLI 가져오기, live API를 별도 열로 둔다. fixture는 이 책에서 검증 완료다. 실제 공급자 경로는 독자의 계정·지역·시점에 따라 달라 검증 전, 부분 검증, 검증 완료로 표시한다. 공급자 이름 대신 계약 버전을 의존성으로 삼으면 다음 모델이 나와도 어댑터만 바꿀 수 있다.


cd 03-labs
npm run verify

완료 조건은 15개 테스트 통과, 대시보드 fixture 로드, 근거 판정, 모바일 레이아웃, 보고서 역추적이다. 실제 출시 전에는 별도 CI에서 최신 Chromium 사용자 여정을 실행한다. 관리형 환경에서 브라우저 실행이 차단됐다는 사실도 숨기지 않고 테스트 보고서에 남긴다.

마지막 원칙은 간단하다. ChatGPT는 더 좋은 문제를 정의하고, Codex는 저장소와 품질 게이트를 지키고, 중국 AI는 언어·장문·구현 같은 전문 작업에서 경쟁한다. 사람은 어떤 근거를 받아들이고 어떤 위험을 감수할지 결정한다. 강한 모델 한 개보다 이 책임 구조가 더 오래간다.

부록

부록 A 처음 막혔을 때

Node 버전은 node -v로 확인한다. npm test가 실패하면 첫 번째 실패만 해결한 뒤 다시 실행한다. 4176 포트가 사용 중이면 PORT=4180 npm start로 바꾼다. 화면에 “불러오지 못했습니다”가 보이면 터미널에 표시된 HTTP 주소로 접속했는지 확인한다. HTML 파일을 file://로 직접 열면 브라우저 보안 정책 때문에 fixture 요청이 차단될 수 있으므로 지원 경로로 보지 않는다.

부록 B 계정과 지역 접근성

ChatGPT, Codex, Kimi, Qwen, GLM 계정·가격·지원 지역은 출간 후에도 변한다. 가입 전에 공식 서비스의 국가, 결제, 데이터 정책을 확인한다. 중국 전화번호나 기업 인증이 필요한 경로는 핵심 실습에서 제외한다. 접근 불가하면 A 경로 fixture를 사용하고 결과 봉투 구조만 연습한다.

부록 C 공급자 어댑터 체크리스트

  • 모델 ID와 확인일을 기록한다.
  • 입력·출력을 AgentTask/AgentResult로 변환한다.
  • timeout, retry, rate limit을 명시한다.
  • 스트리밍 중단을 실패로 기록한다.
  • 원문 citation을 모델 문장과 분리한다.
  • 비밀값과 고객 데이터를 로그에서 제거한다.
  • live 결과를 fixture로 자동 승격하지 않는다.

부록 D 작업·리뷰 템플릿


## 작업
- 목표:
- 입력 산출물:
- 허용 도구:
- 수정 가능 경로:
- 금지 행동:
- 출력 스키마:
- 수용 기준:
- 시간·비용 한도:

## 리뷰
- 계약 검사:
- 자동 테스트:
- 출처 대조:
- 보안 위험:
- 채택/반려와 이유:
- 남은 불확실성:

부록 E 중국어 AI 용어

중국어 한국어 책에서의 의미
智能体 지능형 에이전트 도구를 사용해 작업하는 시스템
大模型 대형 모델 기반 언어·멀티모달 모델
工具调用 도구 호출 모델이 정의된 함수를 선택·실행
多智能体 멀티에이전트 역할이 다른 여러 실행 주체
工作流 워크플로 상태와 게이트가 있는 작업 흐름
开源权重 공개 가중치 사용 조건이 붙을 수 있어 라이선스 확인 필요

부록 F 벤치마크 판독 카드

평가 이름, 과업, 날짜, 표본 수, 도구 허용 여부, 하니스, 비용, 독립 재현, 회사 발표 여부를 한 카드에 적는다. “1위”는 이 칸을 모두 채운 뒤에만 쓴다. Arena 선호도와 정답형 평가, 장기 에이전트 평가를 같은 점수처럼 비교하지 않는다.

부록 G 출처·권리·개인정보 체크리스트

짧은 인용만 사용하고 나머지는 요약한다. 원문 URL·문서명·확인일을 남긴다. 자동 수집 허용 범위와 robots/약관을 확인한다. 개인정보가 포함된 원문은 수집 목적과 보유 기간을 정한다. 법률·의료·금융 결론은 전문가 검토 없이 출시 판단으로 사용하지 않는다.

부록 H 기대 화면과 문제 해결

대시보드에는 프로젝트 K-Flow 중국 시장 진출 검토, 준비도 83%, 출처 12, 근거 8, 채택 5, 비용 $3.84가 보여야 한다. 다르면 fixtures/bridgepilot.json이 책 버전과 같은지 확인한다. 판정 저장 후 새로고침하면 실행 중 메모리 저장소가 유지되는 동안 상태가 보인다. 서버 재시작 시 fixture 상태로 돌아오는 것은 의도된 교육용 동작이다.

참고 자료

에필로그: 모델 순위보다 오래가는 것

이 책을 다 읽은 독자는 중국 AI를 맹신하지도 무시하지도 않는다. 강한 작업에 투입하고, 결과의 출처와 실행 기록을 요구하고, 다른 에이전트와 같은 기준으로 비교한다. 새로운 Kimi와 Qwen이 나오거나 이름이 바뀌어도 작업 봉투와 테스트는 그대로다. 소프트웨어를 만드는 주체가 늘어날수록 최종 결정의 책임은 더 선명해야 한다. 그것이 에이전트 시대의 개발 실력이다.

실습 워크북: BridgePilot 완주 지도

이 워크북은 본문 18개 장과 일대일로 대응한다. 모든 실습은 03-labs에서 시작한다. [필수]는 fixture 경로, [선택]은 실제 서비스 계정이 있을 때만 수행한다. 실제 계정 화면이나 모델 이름이 책과 다르면 공식 문서를 우선하고 실행일을 기록한다.

Lab 01 벤치마크 주장을 감사한다

목표는 “누가 더 강한가”가 아니라 주장 범위를 잠그는 것이다. workbook/CLAIM-AUDIT.md를 만들고 주장, 평가 이름, 과업, 날짜, 수치, 회사/독립 여부, 반례 열을 만든다. K3의 Frontend Code Arena 결과와 종합 성능 문장을 별도 행에 둔다.


판정 문장 예시
확인: Kimi K3는 2026-07-16 공개 당시 특정 프런트엔드 선호도 평가에서
GPT-5.6 Sol과 Claude Fable 5보다 높은 점수를 기록했다.
제한: 이 결과는 종합 지능·보안·백엔드 정확성의 우위를 뜻하지 않는다.

기대 결과는 세계 1위 같은 무범위 문장이 하나도 없는 표다. 링크가 열리지 않으면 캐시된 요약을 사실로 승격하지 말고 재확인 필요로 둔다.

Lab 02 제품 브리프를 검토한다

workbook/PRODUCT-BRIEF.md를 열어 사용자, 결정, 실패 비용을 자신의 서비스에 맞게 바꾼다. 해결책 이름을 지워도 문제가 이해되어야 한다. ChatGPT에 다음 검토를 요청한다.


이 브리프에서 해결책을 미리 가정한 문장, 측정할 수 없는 성공 기준,
법률 판단을 제품 기능처럼 약속한 문장을 각각 찾아라. 고치지 말고 질문으로 반환하라.

답변을 그대로 붙이지 말고 제품 책임자가 수정한다. 완료 표시는 비범위가 세 개 이상이고 각 성공 기준을 테스트하거나 사람이 판정할 수 있을 때만 한다.

Lab 03 저장소 첫 GREEN을 만든다


node -v
cd 03-labs
npm run verify

Node.js 20 이상과 15개 통과를 확인한다. 실패하면 마지막 줄보다 첫 번째 not ok을 읽는다. AGENTS.md에서 정본 fixture, 금지 데이터, 완료 정의를 확인한다. 자신의 운영체제에서 포트가 허용되면 npm start 후 대시보드를 연다.

기대 출력은 BridgePilot 검증 완료다. 포트가 금지돼도 테스트는 요청 핸들러를 직접 호출하므로 통과해야 한다. 이 차이는 “서버 로직 검증”과 “실제 브라우저 검증”을 분리하기 위한 설계다.

Lab 04 작업 봉투를 깨뜨려 본다

먼저 제공 스크립트를 실행한다. 원본 fixture를 바꾸지 않고 정상 작업과 목표가 모호한 작업을 차례로 검사한다.


node lab/04-contract-failure.mjs

정상 계약의 BP-01: PASS 다음에 TASK_OBJECTIVE_INVALID와 TASK_TOOLS_INVALID가 기대 출력이다. 에러 문구가 달라졌다면 책보다 현재 테스트를 기준으로 계약 변경 이유를 기록한다. 에이전트별 프롬프트가 달라도 봉투 계약은 같아야 한다.

Lab 05 동일 화면을 확인한다

대시보드의 기준 값은 프로젝트 K-Flow 중국 시장 진출 검토, 준비도 83%, 출처 12, 근거 8, 채택 5, 비용 $3.84다. 브라우저 개발자 도구의 반응형 모드에서 1440px, 768px, 390px를 차례로 확인한다.

390px에서는 사이드바가 화면 밖에 있고 메뉴 버튼으로 열린다. 지표는 두 열, 작업은 한 열이다. 근거 출처와 판정 버튼이 겹치면 CSS를 고치기 전에 실제 viewport가 390 CSS px인지 확인한다. 확대 배율 100%로 캡처하고 파일명에 viewport를 남긴다.

Lab 06 근거 중복을 재현한다

node lab/06-evidence-dedupe.mjs를 실행한다. 스크립트는 fixture를 수정하지 않고 첫 근거의 URL에 ?utm_source=lab을 붙여 key를 비교한다. 추적 URL 중복 제거: PASS가 나와야 한다.

스크립트가 quote에 문장을 추가한 두 번째 비교에서는 다른 인용문 분리: PASS가 나와야 한다. 이는 의도적 보수성이다. 의미가 비슷하다는 이유로 자동 병합하면 서로 다른 법령 문구가 사라질 수 있다.

Lab 07 판정 API의 실패를 본다

서버를 실행한 터미널과 요청 터미널을 나눈다.


curl -i -X POST http://127.0.0.1:4176/api/decisions 
  -H 'content-type: application/json' 
  -d '{"evidenceId":"EV-001","decision":"accepted","reason":"짧음"}'

Windows PowerShell에서는 다음을 사용한다.


Invoke-RestMethod -Method Post -Uri http://127.0.0.1:4176/api/decisions -ContentType 'application/json' -Body '{"evidenceId":"EV-001","decision":"accepted","reason":"짧음"}'

400과 DECISION_REASON_REQUIRED가 기대 결과다. 사유를 정부 원문과 인용 범위를 대조함으로 바꾸면 201과 DEC-... 레코드가 나온다. 새로고침 후 review 상태를 확인한다. 서버를 재시작하면 fixture로 돌아가는 것은 현재 메모리 저장소의 의도된 제한이다.

Lab 08 외부 문자열 경계를 표시한다

현재 앱은 safe-html.js의 escaping과 URL scheme 검사로 외부 문자열 경계를 방어한다. 먼저 quote에 <img src=x onerror=alert(1)>을 넣고 태그가 실행되지 않고 글자로 표시되는지 확인한다. 이어 javascript: 링크가 거부되고 정상 중국어와 https: 링크는 유지되는지 테스트한다.

방어가 왜 필요한지 배우려면 정본이 아닌 격리 브랜치에서만 escaping 한 줄을 잠시 제거해 실패 테스트가 실제로 RED가 되는지 본 뒤 즉시 되돌린다. 수용 기준은 원문 태그가 글자로 보이고, 정상 중국어가 유지되며, 링크 URL은 http: 또는 https:만 허용되고, 회귀 테스트가 이 계약을 고정하는 것이다. 프로덕션 코드에 고의 취약 버전을 커밋하지 않는다.

Lab 09 오프라인 보고서 구조를 쓴다

workbook/REPORT-OUTLINE.md를 만들고 요약, 조건, 결론, 근거 색인, 판정 기록, 한계 절을 둔다. 각 결론 끝에 [EV-001]처럼 ID를 붙인다. Evidence 절의 같은 ID로 내부 링크가 이동해야 한다.

네트워크를 끈 상태에서도 보고서 본문과 도해가 보여야 한다. 외부 원문 링크는 연결이 있을 때만 열린다는 설명을 넣는다. PDF만 제공하면 링크와 원문 확인이 어려우므로 단일 HTML을 정본으로, PDF를 배포 사본으로 둔다.

Lab 10 Kimi에 원문 조사만 맡긴다

task-BP-01.json 내용을 Kimi Agent에 전달한다. 시스템 전체 구현이나 법률 결론을 요구하지 않는다. 결과는 원문 그대로 JSON 파일에 저장하되, 수동 편집했다면 transformedBy를 기록한다.

URL을 브라우저에서 열고 quote 일부를 검색한다. 문장이 없거나 문맥이 다른 경우 rejected로 두고 이유를 남긴다. 중국어를 몰라도 브라우저 찾기 기능으로 문자 일치를 검사하고, 번역의 적용 범위는 별도 검토한다. 계정이 없으면 result-kimi-BP-01.example.json으로 같은 과정을 수행한다.

Lab 11 Kimi Code 후보를 격리한다

정본과 다른 worktree에서만 실행한다.


git worktree add ../bridgepilot-kimi -b lab/kimi-evidence-compare

수정 가능 파일을 public/ 세 개로 제한하고 390px 1열, 기존 ID 보존, 새 의존성 없음이라는 수용 기준을 전달한다. 종료 후 git diff --stat, git diff, npm test 순서로 본다. 테스트 로그가 결과 봉투에 없으면 완료로 인정하지 않는다. worktree 삭제는 필요한 diff를 보존한 뒤에만 한다.

Lab 12 Qwen SubAgent 경계를 만든다

localizer의 출력은 artifacts/qwen-terms.json, validator의 출력은 artifacts/qwen-validation.json으로 분리한다. 두 작업 모두 bridgepilot.json을 수정하지 못하게 한다. 실행 전 입력 파일의 해시를 기록한다.

병렬 결과가 끝나면 용어 제안과 스키마 오류를 사람이 따로 읽는다. 상위 에이전트가 두 파일을 한 문단으로 요약해 세부 오류를 숨기지 않게 원본 링크를 보존한다. 계정이 없으면 두 역할을 사람이 순서대로 수행해 경계 설계만 익힌다.

Lab 13 결정론적 도구를 만든다

normalize_source의 입력과 출력을 표로 먼저 정의한다. https://EXAMPLE.com/a/?utm_source=x#top은 host 소문자화, 추적 변수와 fragment 제거 후 https://example.com/a가 되어야 한다. 인용문은 임의 번역하거나 고치지 않는다.

모델이 정규 URL을 직접 작성하게 하지 말고 도구를 호출하게 한다. 같은 입력을 100번 실행해 결과가 같은지 테스트한다. Qwen-Agent 연결은 선택이고, 핵심 합격 기준은 공급자 없이 도구 함수 테스트가 통과하는 것이다.

Lab 14 블라인드 비교표를 채운다

Kimi, Qwen, GLM 또는 사용 가능한 두 공급자에 동일 task를 준다. 결과 파일을 A, B로 바꾸고 공급자 필드를 가린 복사본을 평가자에게 준다. 출처 정확성 40, 누락 20, 스키마 15, 시간 10, 비용 10, 설명 가능성 5점이다.

점수가 같으면 더 적은 권한과 더 낮은 재현 비용을 요구한 후보를 고른다. 결과가 하나뿐이면 우승을 선언하지 말고 단일 실행 사례로 표기한다. GUI 조작 제품에는 읽기 전용 테스트 사이트 외의 로그인 계정을 주지 않는다.

Lab 15 실제 통합 리뷰를 쓴다

workbook/REVIEW-BP-01.md를 템플릿으로 새 후보를 리뷰한다. “좋음” 대신 수용 기준별 통과·실패와 증거를 쓴다. 보안 리뷰에는 외부 입력 렌더링, 경로, 로그, 네트워크 권한을 포함한다.

구현자가 만든 테스트 외에 반대 사례 하나를 추가한다. 예를 들어 secret redaction에 token=과 api_key: 두 형태를 함께 넣는다. 테스트가 실제 결함을 발견하면 수정 전 실패 로그와 수정 후 통과 로그를 리뷰 산출물로 보존한다.

Lab 16 한 기능을 종단 실행한다

작업 ID를 하나 정하고 다음 체크박스를 순서대로 완료한다.

  • [ ] Product brief의 결정과 연결
  • [ ] AgentTask 계약 통과
  • [ ] 격리된 전문 작업자 실행 또는 fixture 사용
  • [ ] AgentResult 계약 통과
  • [ ] 출처 원문 대조
  • [ ] 정본 병합과 자동 테스트
  • [ ] UI에서 사람 판정
  • [ ] 보고서에서 근거 역추적

중간 산출물을 삭제하지 않는다. 마지막 화면만 남기면 실패를 재현할 수 없다. 입력이 바뀐 재실행은 새 runId를 쓴다.

Lab 17 공격자처럼 실패를 넣는다

가짜 비밀 sk-abcdefghijklmnop, api_key:abc123, token=hello-secret을 마스킹 함수에 넣는다. 출력에는 키 이름만 남고 값은 모두 [REDACTED]여야 한다. 다음으로 /..%2Ffixtures%2Fbridgepilot.json 경로를 요청해 403을 확인한다.

프롬프트 주입 문장을 evidence quote에 넣고 연구 에이전트가 지시로 실행하지 않는지 확인한다. 공격 문자열은 교육용 가짜 데이터만 사용한다. 실패 결과를 숨기지 말고 위협, 기대 방어, 실제 결과, 수정, 회귀 테스트로 기록한다.

Lab 18 출시 판정 회의를 연다

기능·근거·보안·운영 네 열의 표를 만든다. 각 열에 통과 증거 파일을 링크한다. live provider가 없더라도 fixture 제품은 출시 후보가 될 수 있지만, 실제 시장 결론 서비스라고 홍보할 수는 없다. 법률 감수와 실제 공급자 정책 확인을 HOLD로 둔다.

최종 명령은 다음과 같다.


cd ../..
npm run qa

18개 장, 출처, 도해, 코드 펜스, 이미지 경로와 15개 실습 테스트가 통과해야 한다. 실패가 하나라도 있으면 버전을 올리지 않는다. 통과 로그, 실행일, Node 버전, 아직 검증하지 못한 브라우저/계정 조건을 production/STATUS.md에 남기면 완주다.

워크북 제출물 목록

범주 파일 합격 조건
제품 PRODUCT-BRIEF, USER-JOURNEYS 결정·비범위·실패 상태 포함
계약 task/result JSON validator 통과, provenance 존재
근거 evidence cards URL·원문·확인일·판정 연결
코드 BridgePilot 15개 테스트 통과
리뷰 REVIEW 문서 채택/반려 근거와 남은 위험
화면 desktop/mobile 캡처 같은 fixture 값, 오버플로 없음
출시 STATUS 완료와 HOLD를 명확히 분리