자격증명, 설정, 저장, 텔레메트리

먼저 해보고 말할게요. 위는 디스크의 자격증명 파일, 아래는 요청을 돌리는 프로세스 둘: 왼쪽은 DSH 방식—요청마다 파일에서 key를 다시 읽고; 오른쪽은 흔한 방식—기동 때 한 번 읽어 메모리에 죽을 때까지 둡니다. 스크립트가 중간에 key를 한 번 교체하고 비웁니다. 재생을 눌러 양쪽 운명을 보세요.

먼저 한 가지: DSH 설정 파일과 cordis.yml 어디에도 API key 값이 없어요. 담긴 건 참조, POSIX 스타일 환경 변수 이름(예: DEEPSEEK_API_KEY)입니다. 값은 자격증명 제공자 몫이고, 로컬 제공자는 네 층에서 찾아요. 프로세스 환경이 최우선, 그다음 $DSH_HOME/.credentials.yaml, 마지막이 프로젝트·사용자 .env. 부제가 말한 「설정에 비밀을 안 남긴다」: 디스크에는 이름만, 기밀은 설정 밖에 막혀 있어요(docs/subsystems/credentials.zh.md 5행).

그리고 이 레슨의 가장 중요한 규칙: 소비자는 작업마다 참조를 다시 해석하고, 작업을 넘어 캐시하지 않아요. 문서 원문이 직설적입니다—작업 단위 읽기가 곧 핫 업데이트 메커니즘(같은 문서 20행). DeepSeek 어댑터에서는 packages/llm/llm-deepseek/src/adapter.ts 214–222행: stream()마다 시작에 연결 설정과 key를 한 스냅샷으로 얼리고, 그 요청 내내 그걸 쓰며, 다음 요청은 자동으로 다시 해석합니다.

개요가 물은 경계 조건의 답이 여기 있어요. 요청 중간에 key를 교체하면 이번 요청은 옛 key로 끝나고, 새 key는 다음 요청부터—반반 섞임이 없습니다. 게다가 key는 연결 스냅샷에서 해석되므로 엔드포인트와 비밀은 늘 같은 세대 설정에서 오고, 설정 롤백 때 새 엔드포인트+옛 key 잡종이 안 생깁니다(그곳 주석이 의도를 밝힘).

놓치기 쉬운 seam급 규칙 둘. 첫째, 빈 저장 값은 어디서나 없음으로 보고, key를 빈 문자열로 두면 미설정과 같아 다음 요청이 바로 MISSING_CREDENTIAL—데모 마지막 단계가 그것. 둘째, 설정 UI는 describe(ref)로 「설정 여부·어느 층·쓰기 가능」만 돌려 주고 값은 절대 안 보여요. 프로세스 환경이 값을 주는 참조는 writable: false로 보고되는데, 거기에 쓰면 겉으로는 성공인데 해석은 환경의 옛 값을 계속 돌려주니 seam이 미리 거부합니다(같은 문서 34행).

이 구조의 깨끗함이 가장 잘 보이는 건 credentials/updated 이벤트(같은 문서 50행). 자격증명이 바뀌면 이벤트가 나가지만, 문서는 소비자가 필요 없다고 써 두었어요—설정 UI의 「설정됨」뱃지 새로고침용일 뿐. 핫 업데이트는 읽기 타이밍에 기대고 알림 브로드캐스트에 안 기대니, 쫓을 무효화 메시지도 관리할 구독도 없습니다.

이 부분은 resolveApiKey 함수체(225행부터)에 있고, 모델 요청마다 한 바퀴 돌아요. 자격증명 seam이 있으면 그쪽으로 바로 해석하고, 없으면 기동 환경 변수로 물러납니다. else 분기 주석을 보세요—seam이 없으면 순위 매길 관리 저장이 없어 환경이 곧 전체 자격증명 평면:

    if (credentials !== undefined) {
      const hit = await credentials.resolve(ref)
      if (hit !== undefined) return assertUsableApiKey(hit.value, 'llm-deepseek', ref)
    } else {
      // Without the seam there is no managed store to rank against, so the
      // environment is the whole credential plane.
      const ambient = launchEnvironmentOf(ctx).get(ref)
      if (ambient !== undefined && ambient.value.length > 0) {
        return assertUsableApiKey(ambient.value, 'llm-deepseek', ref)
      }
    }

두 길이 다 비면 바로 이어 MISSING_CREDENTIAL(241–245행)을 던지고, 오류 문구에 설정 입구 둘을 적어요. 데모 왼쪽 마지막 빨간 글자가 그 원문입니다.

설정도 함정이에요. 사용자가 편집기로 settings.yaml을 고치고 web도 고치며, harness 프로세스 둘이 동시에 열려 있을 수 있어요. 순진한 구현은 메모리 스냅샷을 그대로 직렬화해 쓰니 나중 쓴 쪽이 이기고 먼저 쓴 전체를 지웁니다. 편집기에서 방금 넣은 설정이 다른 프로세스 한 번 저장에 깨끗이 날아가요.

DSH 쓰기 경로는 그걸 막았어요(Agent Note 2026-07-30-settings-write-path-integrity.md). 디스크에 쓰기 전마다 디스크를 다시 읽어 외부 수정을 합치고, 프로세스 간 파일 잠금 안에서 「읽기·렌더·원자 커밋」한 바퀴를 끝냅니다. 잠금은 withFileLock: wx로 <파일이름>.lock을 독점 생성—성공하면 보유; 남이 쥐고 있으면 초기 지연부터 상한까지 지수 백오프 재시도, 시한 초과면 오류. 독자는 잠금 경쟁에 안 끼고, 커밋은 임시 파일 rename 원자 교체라 읽는 쪽은 늘 완전한 한 판만 봅니다.

디테일 하나: 잠금 대기가 타임아웃되면 남의 잠금 파일을 지우기보다 오류를 내요. 함수 위 주석 이유—잠금 파일 나이는 주인이 죽었다는 증거가 아니고, 살아 있는 잠금을 뺏는 일이 타임아웃보다 훨씬 위험하며, 고아 잠금 정리는 운영 작업입니다. 익숙한 레시피: 확 안 서면 시끄럽게 실패하고, 조용히 사고 치지 마세요.

출처:packages/util/atomic-write/src/index.ts withFileLock, 86–111행, 확인일 2026-08-13.

KV 저장 SQLite 백엔드도 같은 버전 입장을 이어가요. STORAGE_SQLITE_SCHEMA_VERSION은 현재 1, PRAGMA user_version에 쓰고; DB를 열 때 새 빈 DB만 현재 도장을 찍고 다른 버전은 전부 열기 거부—제자리 마이그레이션 없음. 이전 레슨 세션 로그 버전과 같은 철학: 미출시 소프트웨어엔 지킬 이력이 없으니, 마이그레이션 더미를 지기보다 분명히 거부합니다.

작고 단단한 취사선택 하나: journal 모드는 기본 WAL, 나쁜 파일시스템은 몇 가지 롤백 저널로 물러날 수 있지만 memory와 off는 타입에서 배제됐어요(같은 파일 23–29행 주석). 이유 한 줄, 로그 영속성을 버리면 KV 백엔드 계약의 영속성 조항을 조용히 어깁니다. 빠른 건 괜찮고, 거짓말할 만큼 빠른 건 안 돼요.

텔레메트리에서 가장 무서운 건 본말을 뒤집는 일. DSH는 선택 능력 seam으로 만들어요: agent loop 본줄기에 없고, 텔레메트리 내용은 모델 요청에 안 들어가며, harness 책임은 emit()까지(docs/subsystems/session-telemetry.zh.md). 레코드마다 내보내기 전 비식별 파이프라인을 지나고 배포 쪽이 규칙 리스너를 걸며; 리스너 예외는 fail-closed로 그 레코드를 막고 안 보냅니다. 비식별은 내보내기 사본만 고치고 권위 세션 로그는 한 글자도 안 움직여요.

마지막으로 익명 신원 설계. 난수 UUID v4가 $DSH_HOME/.anonymous-user-id에 떨어지고, 소비자 셋이 공유해요: OTel user.id, /feedback 확인 회신, DeepSeek로 가는 x-deepseek-harness-user-id 헤더(packages/identity/anonymous-user-id/README.zh.md). id 하나를 공유해야 수신 측이 세 길을 연관하고, 각자 신원 셋을 만들 필요가 없습니다.

묘미는 생성 시점. llm-deepseek에서 이 id는 게으른 생성—userId ??= getOrCreateAnonymousUserId()—정말 처음 쓸 때 파일이 생기고(index.ts 248–249행); stream()에서는 자격증명 해석이 신원 해석보다 앞이에요(adapter.ts 221–222행). 이어 보면: key를 한 번도 안 넣은 기계는 자격증명 단계에서 실패하고, 디스크에 추적 신원이 공짜로 안 생깁니다. 도구가 아직 한 일도 안 했는데 번호를 먼저 매기는 일—DSH는 안 해요.