CH 04 · Web UI 알아보기
본장 목표
이전 장에서 dsh를 설치하고, Key를 입력하고, 작업 폴더를 골라, 첫 작업을 돌렸습니다. 이 장에서는 한 발 멈춰서 인터페이스를 읽어 봅니다. 각 영역이 무엇을 하고, 설정 패널에 어떤 스위치가 숨어 있고, 세 가지 권한 등급이 각각 Agent에게 무엇을 허용하며, 궤적(Trajectory) 뷰는 어떻게 읽는지. 이 장을 마치면, CH 02에서 말한 "모든 실행은 추적 가능"이라는 한 줄이 인터페이스 좌상단 — 단 한 탭 거리에 그대로 놓여 있다는 사실을 발견하게 됩니다.
인터페이스 레이아웃: 감 잡기
이것은 첫 작업을 돌린 뒤 제가 찍은 전체 인터페이스 스크린샷으로, 주요 영역에 주석을 달았습니다.
영역별 역할.
| 영역 | 역할 | 비고 |
|---|---|---|
| 왼쪽 | 작업 폴더 목록 | 프로젝트 폴더당 작업 폴더 하나. 여기서 작업 폴더를 선택(목록을 열고 고르거나, "⊕ 새 세션"으로 생성). 하단은 설정 버튼 |
| 가운데 | 세션 영역 | 메시지를 보내고, Agent가 일하고, 결과가 표시되는 곳. 상단에 대화(Conversation) / 궤적(Trajectory) 탭 |
| 하단 | 입력 영역 | 보내기 버튼 왼쪽에 컨텍스트 점유율 링. 더 왼쪽에는 모델(Model) 및 권한(Permission) 선택기. 그 아래에 통계 막대 |
설정 패널: 좌하단의 톱니바퀴
설정(Settings) 버튼은 인터페이스 좌하단에 있습니다. 열면 왼쪽에 기능 카테고리가 나열됩니다. 일반 설정(General Settings) / 모델(Models) / 플러그인(Plugins) / Agent 프리셋(Agent Presets).
먼저 일반 설정(General Settings) 페이지. 언어, 외관, 작업 중 Enter 키 동작 같은 항목이 모두 여기 있습니다. 그중 특히 중요한 두 가지. 권한(Permission)(새 세션의 기본 권한 모드. 제 환경은 Workspace Write), Agent 프리셋(Agent Preset)(현재 "Standard"). 여기서의 Agent 프리셋은 CH 02에서 살펴본 네 가지 실행 모드(Standard / Code / Minimal / Creator)이며, 여기서 고른 것이 "새 세션이 기본으로 사용할 플러그인 조합"이 됩니다. 그 아래 한 줄을 잘 봐 두십시오. "새로 만들어지는 세션에 적용됩니다. 이미 실행 중인 세션은 시작 시 사용된 프리셋을 유지합니다." — 일반 설정에서 바꾼 기본값은 새 세션에만 적용됩니다. 이 규칙은 앞으로도 계속 등장합니다.
이제 설정 → 모델(Settings → Models) 을 봅니다. DeepSeek 카드에는 API Key가 입력되어 있고(입력되어 있으면 "설정됨"으로 표시), 하단에서 제공자 추가(Add Provider)(Anthropic이나 OpenAI 같은 내장 디렉터리 사용)와 사용자 정의 제공자 추가(Add Custom Provider)(자체 게이트웨이 또는 로컬 모델 — Provider ID, API 주소, 프로토콜, Key, 최소 하나의 모델 입력)가 가능합니다. 모델 라우팅 변경은 즉시 적용되며, 서비스 재시작은 필요 없습니다. Key는 쓰기 전용입니다. 저장 후 페이지에는 마스킹된 설명만 표시되며, 평문은 로컬 $DSH_HOME/.credentials.yaml에만 기록됩니다. CH 03에서 언급한 그 경로입니다.
세 가지 권한 등급: 컴퓨터에서 무엇을 만질 수 있는가
이 부분은 dsh를 처음 접할 때 반드시 미리 이해해야 할 내용입니다. 공식 파일 샌드박스는 다음 세 가지 모드로 정의됩니다.
작업 폴더를 선택한 뒤 입력란 왼쪽에 나타나는 권한 선택기와 비교해 보십시오(작업 폴더 선택 후 뜨는 패널).
세 등급을 풀이하면 다음과 같습니다.
| 권한 | 무엇을 할 수 있는가 | 언제 쓸까 |
|---|---|---|
read-only | 읽기 전용, 한 바이트도 변경 불가 | 읽기 전용 분석, 코드 리뷰, 순수 Q&A |
workspace-write(기본) | 작업 폴더 + 시스템 임시 영역에서 쓰기 가능. 작업 폴더 밖은 대화상자를 띄워 먼저 묻습니다 | 일상 작업, 거의 대부분의 경우 |
danger-full-access | 전역 읽기/쓰기, 경계 없음 | 실제로 전역 변경이 필요한 시스템 유지보수 작업. 켜면 한 번 더 확인을 요구합니다 |
공식 의미에 대해 한 가지 보충합니다. workspace-write의 쓰기 경계는 "작업 폴더 루트 + 백엔드가 약속한 임시 영역"이며, read-only는 쓰기를 일절 거부하고, danger-full-access는 격리를 완전히 우회합니다. 권한은 파일 시스템 효과만 관리한다는 점에 유의하십시오. 네트워크와 프로세스 가시성은 이 정의의 적용 범위가 아닙니다.
일상 작업에서는 기본값인 workspace-write에 머물러 익숙해진 다음, 진짜로 전역 동작이 필요할 때만 세 번째 등급을 고려하십시오.
전환 방식은 두 가지인데, 헷갈리지 마십시오.
- 이번 세션에만 일시적으로: 입력란에
/permission을 치고 등급을 고르십시오. 현재 세션에만 영향을 줍니다. - 기본값을 바꾸기(앞으로 만들 새 세션에 적용): 설정 → 일반 → 권한(Settings → General → Permission) 으로 가십시오. 이후 만들어지는 세션에만 영향을 주며, 이미 실행 중인 세션은 손대지 않습니다.
모델과 추론 강도
모델 선택기에는 설정된 모델이 보입니다(Key를 입력하면 DeepSeek 모델이 자동으로 나타남). 공식 규칙이 명시되어 있습니다. 모델 선택기에서 고른 모델이 새 세션의 기본값입니다. 이미 요청을 보낸 세션은 시작 시 사용 중이던 모델을 그대로 유지하며, 기본값을 바꿔도 따라 바뀌지 않습니다. (세션이 자기 모델을 자체 기록하기 때문에, 기본값을 바꾼다고 과거 요청이 조용히 재작성되지는 않습니다.)
따라서 세션마다 다른 모델을 쓰고 싶다면(가벼운 일상 작업은 flash, 어려운 일은 pro 또는 그 이상), 그냥 새 세션을 여십시오. 세션마다 독립입니다.
추론 강도(reasoning effort)도 하나의 손잡이이며, DeepSeek 공식 모델은 네 단계로 나뉩니다.
| 단계 | 특징 |
|---|---|
off | 사고 비활성. 가장 빠르고 저렴 |
low | 가벼운 사고. 단순 Q&A에 충분 |
high(기본) | 깊은 추론. 복잡한 작업에서 정확도↑, 약간 느리고 비쌈 |
max | 가장 강한 강도. 가장 어려운 작업에만 사용 |
일상 작업에서는 그냥 high로 두십시오. 느리게 느껴지면 낮추면 됩니다. 각 단계가 실제로 무엇에 영향을 주는지, 변경 방법은 CH 06에서 깊이 다룹니다. 모델 변경도 다음 요청부터 즉시 적용되므로 재시작은 필요 없습니다.
궤적(Trajectory): CH 02의 "추적 가능"이 여기에 숨어 있다
CH 02에서 "모든 실행은 추적 가능"이라고 했던 그 한 줄, 기억나십니까. 인터페이스 좌상단을 보십시오. 대화(Conversation) / 궤적(Trajectory) 가 나란히 있습니다. 궤적 을 클릭하면 이번 라운드의 전체 실행 기록이 펼쳐집니다. 실제 스크린샷입니다.
읽는 법.
- 가운데가 타임라인이며, ASSISTANT(think/speak)와 TOOL(도구 호출)이 번갈아 나타납니다. 위에서 아래로가 Agent가 일한 실제 순서입니다.
- 각 TOOL 행: 왼쪽에 도구 이름(
pwsh/read/web_search), 오른쪽에 실제로 보낸 파라미터와 반환된 핵심 결과. - TOOL 행을 클릭하면 우측 패널이 해당 단계의 상세를 펼칩니다. 요약(Summary) / 페이로드(Payload) / 결과(Result) / 스키마(Schema) / 타이밍(Timing) 그리고 상태(Status, Completed)와 계층(Hierarchy).
- 상단에는 소요 시간(Duration) / 턴 수(Turns) / 호출 수(Calls) 요약, 그리고 단계 검색을 위한 검색창.
이번 제 작업에서 Agent가 실제로 헤매는 모습이 보입니다. 먼저 설정을 읽고, 파일을 읽다가, pwsh로 공식 문서를 직접 가져오려는 시도에 SSL 연결이 실패했고, "pwsh의 아웃바운드 HTTPS가 차단되었습니다"라고 말한 뒤 web_search로 우회해서 계속 찾아 나갑니다. 이 모든 시행착오가 궤적에 기록되어 있습니다. 그것이 바로 "추적 가능"이라는 말의 의미입니다.
하단 통계 막대는 같은 것의 또 다른 측면입니다.
| 지표 | 의미 |
|---|---|
| Turns · Steps | 이번 라운드에서 Agent가 거친 단계 수 |
| LLM time / Tool call time | "생각하는" 시간과 "하는" 시간 |
| First-token mean / tok/s | 출력 속도 |
| Cache hit | 컨텍스트 캐시를 맞힌 입력 토큰의 비율(아래 참조) |
| Input / Output tok | 이번 라운드에서 모델에 넣은 토큰과 모델이 만든 토큰 |
컨텍스트 캐시: 적중률이 왜 이렇게 높은가
통계 막대의 "캐시 적중(cache hit)"은 dsh 기능이 아니라 그 뒤에 있는 DeepSeek API의 컨텍스트 디스크 캐시입니다. 공식 방침은 이렇습니다. 재사용될 것으로 예상되는 캐시 내용을 분산 디스크 배열에 두고, 다음 입력에 반복되는 부분이 있으면 다시 계산하지 않고 캐시에서 읽어 지연과 비용을 모두 줄입니다.
캐시를 맞힌 입력 토큰의 과금은 캐시 미스보다 훨씬 저렴합니다. deepseek-v4-flash를 예로 들면, 공식 현행 요율에서 캐시 적중 입력은 백만 토큰당 약 0.1위안 수준이고, 캐시 미스 입력은 백만 토큰당 약 1.5~3위안(비첨두/첨두에 따라 다름)입니다. 입력의 그 캐시된 부분은 미스 가격의 일부에 불과합니다.
단일 세션에서 적중률이 왜 이렇게 높을까요. 같은 세션의 매 단계 입력은 직전의 시스템 프롬프트, 도구 정의, 대화 기록이라는 안정적인 반복 접두사를 포함하기 때문입니다. 첫 호출은 캐시가 비어 있지만, 두 번째 호출부터는 직전 구간이 캐시되어 있습니다. 제 작업은 입력 토큰 160K였지만 적중률이 높아 실제로 전액 미스 요율이 적용된 부분은 아주 적었습니다. 이것이 Agent 작업이 같은 세션에서 이루어지는 것이 가장 좋은 이유이기도 합니다. 세션이 길어질수록 뒤로 갈수록 절약 효과가 커집니다.
컨텍스트 점유율 링
입력 영역에서 보내기 버튼 왼쪽의 링 표시는 현재 세션 컨텍스트 윈도우의 점유 비율을 보여줍니다. 실제 측정 화면입니다.
그림의 링은 "컨텍스트 2% 사용"으로 표시되어 있습니다. 세션이 막 시작되어 사용량이 거의 없다는 뜻입니다. 컨텍스트 윈도우는 유한합니다. Agent가 긴 작업을 돌리면 대화 기록과 도구 결과가 쌓이고, 링을 보면 한눈에 남은 공간을 알 수 있습니다. 거의 가득 찼다면 선택지는 세 가지입니다. 새 세션을 시작한다, Agent에게 요약으로 정리하라고 한다, 또는 입력란에 /compact 를 치는 것입니다. 그러면 현재 대화의 핵심 정보를 더 압축된 요약으로 정리하고, AI는 그 요약으로 작업을 이어갑니다. 처음부터 다시 시작할 필요 없이 세션을 다이어트시키는 것과 같습니다.
첫 작업을 끝까지 진행하기
공식 README의 예제 작업은 이것입니다.
이 저장소를 요약하고 주요 패키지를 파악해 주세요.
이를 한글로 옮기면 지난 장에서 돌린 바로 그것이 됩니다. DeepSeek harness 저장소를 요약하고 주요 모듈을 파악하기. 즉, 공식 예제를 이미 돌린 셈입니다.
실행할 때 인터페이스가 작업을 어떻게 "펼쳐서" 보여 주는지 잘 보십시오. Agent가 먼저 컨텍스트를 주입하고, 계획을 세우고, 그다음 도구(파일 읽기, 명령 실행, 검색)를 호출하며, 모든 단계가 보입니다. 승인이 필요한 작업에는 대화상자가 뜹니다. 작업이 끝나면 궤적(Trajectory) 탭으로 옮겨 재생하고, 통계 막대의 숫자와 대조해 보십시오. 첫 작업은 보통 입력이 큽니다(제 경우 160K 토큰). 하지만 캐시 적중률이 높아 실제 비용은 매우 낮습니다.
이 장에서 배운 것
아래 항목들을 스스로 완수할 수 있으면 합격입니다.
- [ ] Web UI의 각 영역(왼쪽 / 가운데 / 하단)이 무엇인지, 어디에서 작업 폴더를 선택하는지 설명할 수 있다
- [ ] 설정 패널의 카테고리(일반 설정 / 모델 / 플러그인 / Agent 프리셋)와 "기본값은 새 세션에만 적용"이라는 규칙을 알고 있다
- [ ] 세 가지 권한 등급
read-only/workspace-write/danger-full-access의 차이를 설명할 수 있고, 일상 작업에서 두 번째 등급을 쓰는 이유를 알고 있다 - [ ]
/permission은 현재 세션의 권한을 임시로 바꾸고, 설정 → 일반 → 권한은 기본값을 바꾼다는 것을 알고 있다 - [ ] 모델 선택기의 선택이 새 세션의 기본값이며, 이미 실행된 세션은 원래 모델을 유지한다는 것을 알고 있다
- [ ] 궤적 뷰를 읽을 수 있다: ASSISTANT / TOOL 타임라인 + 우측 상세 패널 + 통계 막대
- [ ] "캐시 적중"이 무엇인지, 그리고 긴 세션에서 적중률이 높은 이유를 설명할 수 있다