claude-distill 0.3.0 → 0.4.0

package/README.md

@@ -12,6 +12,13 @@
 
 사용자가 하는 일: `claude-distill init` **한 번. 끝.**
 
+부담 없는 이유:
+- **별도 서버 / 계정 없음** — 본인 머신 → Anthropic API 직통. distill 운영자한테도 transcript 안 감
+- **의존성 0개, 50KB 미만** — [GitHub](https://github.com/parksubeom/claude-distill)에서 코드 그대로 검수
+- **세션당 비용 ~$0** — 4단 게이트로 본 추출 호출 ~10× 컷 (휴리스틱 → Haiku → dedup hash → 재귀 가드)
+- **Plain markdown 결과** — 마음에 안 드는 entry는 그 줄 삭제. UI / DB / 락인 없음
+- **한국어 / 영어 자동 누적** — transcript 언어 자동 감지, 별도 설정 불필요
+
 ---
 
 ## 어떤 게 자동으로 누적되나
@@ -152,10 +159,30 @@ source ~/.zshrc
 - `ANTHROPIC_API_KEY` — 설정 시 Haiku 게이트 자동 활성 (~$0 가까이 게이트 비용)
 - `CLAUDE_DISTILL_GATE_MODEL` — 게이트 모델 (기본 `claude-haiku-4-5-20251001`)
 - `CLAUDE_DISTILL_MODEL` — 본 추출 모델 (기본 `claude-sonnet-4-6`)
+- `CLAUDE_DISTILL_LANG` — 누적 언어 강제 (`ko` / `en`). 미설정 시 transcript 한글 비율로 자동 감지
 - `CLAUDE_DISTILL_CHILD` — distill이 spawn한 자식 claude 표식. 수동 설정 불필요 (hook 무한 재귀 차단용 내부 플래그)
 
 ---
 
+## 언어 (i18n) — 한국어 / 영어
+
+`knowledge.md` / `gotchas.md`는 한국어 또는 영어로 누적할 수 있습니다. 헤더 / 필드 라벨 (`상황` / `함정` / `근거` … vs `Context` / `Trap` / `Basis` …) 과 entry 본문이 모두 해당 언어로 작성됩니다. 카테고리 키 (`api_quirk`, `trade_off_decision` 등) 는 머신 식별자라 영어 enum 그대로 유지.
+
+**우선순위**:
+1. `claude-distill analyze --lang=ko|en` (명시)
+2. `CLAUDE_DISTILL_LANG=ko|en` 환경변수
+3. **transcript 자동 감지** — 세션 turn에서 한글 음절 비율이 5% 넘으면 `ko`, 아니면 `en`
+4. `process.env.LANG` (예: `ko_KR.UTF-8` → `ko`)
+5. fallback: `en`
+
+대부분의 사용자는 **3번 자동 감지로 충분** — 한국어로 코딩하는 세션은 한국어로, 영어 세션은 영어로 자연스럽게 누적됩니다. 별도 설정 없이.
+
+영어 위주로 쓰다 한국어 entry가 섞이는 게 싫다면 `~/.zshrc`에 `export CLAUDE_DISTILL_LANG=en` 으로 고정.
+
+> **혼재 주의**: 기존 markdown이 영어로 쌓여있을 때 locale을 `ko`로 바꾸면, 같은 파일에 영/한 entry가 섞입니다. plain markdown이라 사용자가 직접 정리 가능 (헤더 / 라벨 일괄 치환). v0.4 첫 cut은 단일 파일 정책 — 언어별 파일 분리 (`knowledge.ko.md`)는 추후 검토.
+
+---
+
 ## 프라이버시 / 보안
 
 **별도 서버 없음.** distill은 본인 머신 → Anthropic API 직통입니다. 중간에 어떤 third-party 서버도 없음 — 코드도 50KB 미만, [GitHub](https://github.com/parksubeom/claude-distill)에서 그대로 검수 가능.
@@ -210,6 +237,7 @@ A. macOS / Linux / Windows (Node 18+ 설치돼있으면). 경로는 전부 `os.h
 
 ## 상태
 
+v0.4 — i18n. `knowledge.md` / `gotchas.md`를 한국어 / 영어로 자동 누적 (transcript 언어 감지 또는 `CLAUDE_DISTILL_LANG`).
 v0.3 — 게이트 도입 (휴리스틱 + Haiku) + Stop 훅 무한 재귀 가드. 본 추출 호출 ~10× 감소.
 v0.2 — 자동 누적 모델로 재정비.
 

package/bin/distill.js

@@ -21,7 +21,12 @@ const help = `claude-distill — Knowledge + Gotchas auto-accumulator for Claude
   claude-distill where      모든 파일 경로 / 존재 여부
 
 수동 분석 (보통 Hook이 자동으로 함):
-  claude-distill analyze [--no-auto] [--mock] [--quiet]
+  claude-distill analyze [--no-auto] [--mock] [--quiet] [--lang=ko|en]
+
+언어 (knowledge.md / gotchas.md 누적 언어):
+  --lang=ko|en              명시 (가장 우선)
+  CLAUDE_DISTILL_LANG=...   환경변수
+  (없으면) transcript 한글 비율로 자동 감지 → process.env.LANG → 'en'
 
 결과는 plain markdown:
   ~/.claude/knowledge.md    판례 (전역)

package/lib/analyze.js

@@ -22,6 +22,7 @@ const cfg = require('./config');
 const transcript = require('./transcript');
 const store = require('./store');
 const gate = require('./gate');
+const localeMod = require('./locale');
 
 // 자식 claude 프로세스 표식. distill→claude→Stop 훅→distill 무한 재귀 차단용.
 const CHILD_ENV_KEY = 'CLAUDE_DISTILL_CHILD';
@@ -35,6 +36,7 @@ function parseFlags(args) {
     auto: true,        // 기본값 — 자동 누적 (CLI 핵심)
     backend: 'auto',   // 'auto' | 'cli' | 'api' — auto는 ANTHROPIC_API_KEY 있으면 api, 없으면 cli
     noGate: false,     // 게이트 우회 (디버깅 / 강제 분석)
+    lang: null,        // 'ko' | 'en' | null — null이면 env / transcript 자동 감지
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -47,6 +49,8 @@ function parseFlags(args) {
     else if (a === '--backend') flags.backend = args[++i];
     else if (a.startsWith('--session=')) flags.session = a.slice('--session='.length);
     else if (a === '--session') flags.session = args[++i];
+    else if (a.startsWith('--lang=')) flags.lang = a.slice('--lang='.length);
+    else if (a === '--lang') flags.lang = args[++i];
   }
   return flags;
 }
@@ -62,10 +66,11 @@ function existingForDedup() {
   return out;
 }
 
-function buildAnalyzerPrompt(promptText, existing, t) {
+function buildAnalyzerPrompt(promptText, existing, t, locale) {
   const exBlock = `<existing>\n# knowledge.md\n${existing.knowledge}\n\n# gotchas.md\n${existing.gotchas}\n</existing>`;
   const txBlock = `<transcript file="${t.source}" total_lines="${t.totalLines}" slice_from="${t.sliceFrom}">\n${JSON.stringify(t.turns, null, 2)}\n</transcript>`;
-  return `${promptText}\n\n---\n\n${exBlock}\n\n${txBlock}\n\nReturn the JSON array now. No prose, no markdown fences.`;
+  const langDirective = localeMod.promptDirective(locale);
+  return `${promptText}\n\n---\n\n${exBlock}\n\n${txBlock}${langDirective}\n\nReturn the JSON array now. No prose, no markdown fences.`;
 }
 
 function mockExtract() {
@@ -227,6 +232,11 @@ async function run(args) {
     return;
   }
 
+  // Locale 결정 — transcript가 로드된 뒤(자동 감지에 필요). flag → env →
+  // transcript Hangul 비율 → process.env.LANG → 'en'.
+  const locale = localeMod.resolveLocale({ flag: flags.lang, transcript: t });
+  log(flags, 'locale: ' + locale + (flags.lang ? ' (--lang)' : process.env.CLAUDE_DISTILL_LANG ? ' (env)' : ' (auto)'));
+
   // ── 게이트 1: 휴리스틱 (로컬, 무료) ───────────────────────
   // 짧은 세션 / 도구 사용 0 / 에러 키워드 0 → 인사이트 후보 거의 없음.
   // mock 모드와 --no-gate 는 우회.
@@ -261,7 +271,7 @@ async function run(args) {
   } else {
     const prompt = fs.readFileSync(cfg.PROMPT_FILE, 'utf8');
     const existing = existingForDedup();
-    const fullPrompt = buildAnalyzerPrompt(prompt, existing, t);
+    const fullPrompt = buildAnalyzerPrompt(prompt, existing, t, locale);
     if (flags.dryRun) {
       log(flags, '[--dry-run] prompt 준비됨 (' + fullPrompt.length + ' chars). LLM 호출 생략.');
       return;
@@ -299,7 +309,7 @@ async function run(args) {
         },
       };
       try {
-        const dest = store.appendEntry(annotated);
+        const dest = store.appendEntry(annotated, locale);
         appended++;
         log(flags, '  ✓ ' + (c.title || c.id) + ' → ' + dest);
       } catch (err) {

package/lib/locale.js

@@ -0,0 +1,141 @@
+// Locale resolution + label tables for ko / en.
+//
+// 우선순위:
+//   1. --lang=ko|en 플래그
+//   2. CLAUDE_DISTILL_LANG 환경변수
+//   3. transcript 자동 감지 (Hangul 비율)
+//   4. process.env.LANG
+//   5. fallback 'en'
+//
+// 지원 범위는 의도적으로 ko / en 둘로만 제한. 추가 언어는 LABELS 테이블 + detector
+// 분기만 늘리면 되지만 v0.4 첫 cut에선 두 언어로 시작.
+
+const SUPPORTED = ['ko', 'en'];
+const DEFAULT = 'en';
+
+const LABELS = {
+  en: {
+    knowledgeHeader:
+      '# Knowledge — case law\n\n' +
+      '> Judgment calls worth remembering. Maintained by [claude-distill](https://github.com/parksubeom/claude-distill).\n\n',
+    gotchasHeader:
+      '# Gotchas — incident reports\n\n' +
+      '> Mistakes worth not repeating. Maintained by [claude-distill](https://github.com/parksubeom/claude-distill).\n\n',
+    category: 'Category',
+    confidence: 'Confidence',
+    date: 'Date',
+    source: 'Source',
+    sessionWord: 'session',
+    projectWord: 'project',
+    cmdsWord: 'cmds',
+    contextLabel: 'Context',
+    symptomLabel: 'Symptom',
+    insightLabel: 'Insight',
+    trapLabel: 'Trap',
+    basisLabel: 'Basis',
+    applicationLabel: 'Application',
+    tagsLabel: 'Tags',
+    untitled: '(untitled)',
+  },
+  ko: {
+    knowledgeHeader:
+      '# 판례 — Knowledge\n\n' +
+      '> 다음에도 기억할 만한 결정. [claude-distill](https://github.com/parksubeom/claude-distill)이 자동 누적합니다.\n\n',
+    gotchasHeader:
+      '# 사고 보고서 — Gotchas\n\n' +
+      '> 다시 빠지지 말아야 할 함정. [claude-distill](https://github.com/parksubeom/claude-distill)이 자동 누적합니다.\n\n',
+    category: '카테고리',
+    confidence: '신뢰도',
+    date: '날짜',
+    source: '출처',
+    sessionWord: '세션',
+    projectWord: '프로젝트',
+    cmdsWord: '명령',
+    contextLabel: '상황',
+    symptomLabel: '증상',
+    insightLabel: '인사이트',
+    trapLabel: '함정',
+    basisLabel: '근거',
+    applicationLabel: '적용',
+    tagsLabel: '태그',
+    untitled: '(제목 없음)',
+  },
+};
+
+function normalize(v) {
+  if (!v) return null;
+  const s = String(v).toLowerCase().trim();
+  if (s.startsWith('ko')) return 'ko';
+  if (s.startsWith('en')) return 'en';
+  return null;
+}
+
+// transcript의 turns를 stringify해서 한글 음절 (U+AC00–U+D7A3) 비율을 계산.
+// 시그널이 약하면 (글자 자체가 적으면) null 반환 — 호출자가 다음 우선순위로.
+function detectFromTranscript(t) {
+  if (!t || !Array.isArray(t.turns) || t.turns.length === 0) return null;
+  let kor = 0;
+  let letters = 0;
+  for (const turn of t.turns) {
+    const s = JSON.stringify(turn);
+    for (let i = 0; i < s.length; i++) {
+      const code = s.charCodeAt(i);
+      const isHangul = code >= 0xAC00 && code <= 0xD7A3;
+      const isLatin = (code >= 0x41 && code <= 0x5A) || (code >= 0x61 && code <= 0x7A);
+      if (isHangul) kor++;
+      if (isHangul || isLatin) letters++;
+    }
+  }
+  if (letters < 200) return null;
+  // 한글 음절은 글자 하나당 정보량이 라틴 알파벳보다 크므로 5%만 넘어도
+  // 실제로는 한국어 위주의 세션. 임계값 보수적으로 0.05.
+  return kor / letters > 0.05 ? 'ko' : 'en';
+}
+
+function resolveLocale({ flag, transcript } = {}) {
+  const fromFlag = normalize(flag);
+  if (fromFlag) return fromFlag;
+  const fromEnv = normalize(process.env.CLAUDE_DISTILL_LANG);
+  if (fromEnv) return fromEnv;
+  const fromTranscript = detectFromTranscript(transcript);
+  if (fromTranscript) return fromTranscript;
+  const fromSysLang = normalize(process.env.LANG);
+  if (fromSysLang) return fromSysLang;
+  return DEFAULT;
+}
+
+function labels(locale) {
+  return LABELS[SUPPORTED.includes(locale) ? locale : DEFAULT];
+}
+
+// LLM에 출력 언어를 강제하는 directive. JSON 식별자 필드는 enum 그대로
+// 유지하라고 명시 — 카테고리 키가 번역되면 store.js의 isGotcha 분기 등이 깨짐.
+function promptDirective(locale) {
+  if (locale === 'ko') {
+    return [
+      '',
+      '---',
+      '',
+      'OUTPUT LANGUAGE: 모든 entry의 자연어 필드(title, context, insight, basis, application)와 tags 배열은 **한국어**로 작성하세요.',
+      '단, 식별자 필드(type, category, confidence)는 명세된 영어 enum 값 그대로 유지 — 번역 금지.',
+      'JSON 키 이름과 구조도 그대로. 한국어로 표현하기 어려운 기술 용어는 영어 그대로 두어도 됩니다.',
+    ].join('\n');
+  }
+  return [
+    '',
+    '---',
+    '',
+    'OUTPUT LANGUAGE: Write the natural-language fields (title, context, insight, basis, application) and tags array in **English**.',
+    'Keep identifier fields (type, category, confidence) as their specified English enum values — do not translate.',
+    'Do not change JSON key names or structure.',
+  ].join('\n');
+}
+
+module.exports = {
+  SUPPORTED,
+  DEFAULT,
+  resolveLocale,
+  detectFromTranscript,
+  labels,
+  promptDirective,
+};

package/lib/store.js

@@ -5,6 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const cfg = require('./config');
+const locale = require('./locale');
 
 function resolveTarget(entry) {
   const isGotcha = entry.type === 'gotcha';
@@ -16,61 +17,53 @@ function resolveTarget(entry) {
   return isGotcha ? cfg.GLOBAL_GOTCHAS : cfg.GLOBAL_KNOWLEDGE;
 }
 
-function ensureHeader(file, isGotcha) {
+function ensureHeader(file, isGotcha, lang) {
   if (fs.existsSync(file)) return;
-  const header = isGotcha
-    ? `# Gotchas — incident reports
-
-> Mistakes worth not repeating. Maintained by [claude-distill](https://github.com/parksubeom/claude-distill).
-
-`
-    : `# Knowledge — case law
-
-> Judgment calls worth remembering. Maintained by [claude-distill](https://github.com/parksubeom/claude-distill).
-
-`;
+  const L = locale.labels(lang);
+  const header = isGotcha ? L.gotchasHeader : L.knowledgeHeader;
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, header);
 }
 
-function formatEntry(e) {
-  const title = e.title || '(untitled)';
+function formatEntry(e, lang) {
+  const L = locale.labels(lang);
+  const title = e.title || L.untitled;
   const date = (e.source && e.source.timestamp) ? e.source.timestamp.slice(0, 10) : new Date().toISOString().slice(0, 10);
   const sessionId = (e.source && e.source.sessionId) || 'unknown';
   const project = (e.source && e.source.project) || 'unknown';
   const cmds = (e.source && e.source.relatedCommands && e.source.relatedCommands.length)
-    ? ' · cmds: ' + e.source.relatedCommands.join(', ')
+    ? ' · ' + L.cmdsWord + ': ' + e.source.relatedCommands.join(', ')
     : '';
   const tags = (e.tags || []).map((t) => '`' + t + '`').join(' · ');
   const conf = e.confidence || 'medium';
-  const symptomLabel = e.type === 'gotcha' ? 'Symptom' : 'Context';
-  const insightLabel = e.type === 'gotcha' ? 'Trap' : 'Insight';
+  const symptomLabel = e.type === 'gotcha' ? L.symptomLabel : L.contextLabel;
+  const insightLabel = e.type === 'gotcha' ? L.trapLabel : L.insightLabel;
 
   return [
     `## ${title}`,
-    `**Category**: \`${e.category}\`  · **Confidence**: ${conf}  · **Date**: ${date}`,
-    `**Source**: session \`${sessionId.slice(0, 8)}\` · project \`${project}\`${cmds}`,
+    `**${L.category}**: \`${e.category}\`  · **${L.confidence}**: ${conf}  · **${L.date}**: ${date}`,
+    `**${L.source}**: ${L.sessionWord} \`${sessionId.slice(0, 8)}\` · ${L.projectWord} \`${project}\`${cmds}`,
     '',
     `**${symptomLabel}**: ${e.context || ''}`,
     '',
     `**${insightLabel}**: ${e.insight || ''}`,
     '',
-    `**Basis**: ${e.basis || ''}`,
+    `**${L.basisLabel}**: ${e.basis || ''}`,
     '',
-    `**Application**: ${e.application || ''}`,
+    `**${L.applicationLabel}**: ${e.application || ''}`,
     '',
-    `**Tags**: ${tags}`,
+    `**${L.tagsLabel}**: ${tags}`,
     '',
     '---',
     '',
   ].join('\n');
 }
 
-function appendEntry(entry) {
+function appendEntry(entry, lang) {
   const file = resolveTarget(entry);
   const isGotcha = entry.type === 'gotcha';
-  ensureHeader(file, isGotcha);
-  fs.appendFileSync(file, formatEntry(entry));
+  ensureHeader(file, isGotcha, lang);
+  fs.appendFileSync(file, formatEntry(entry, lang));
   return file;
 }
 

package/lib/where.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const cfg = require('./config');
+const localeMod = require('./locale');
 
 const CLAUDE_MD = path.join(cfg.CLAUDE_DIR, 'CLAUDE.md');
 
@@ -21,6 +22,11 @@ function run() {
   console.log('  analyzed.json   ' + exists(path.join(cfg.STATE_DIR, 'analyzed.json')) + '  중복 분석 방지 로그');
   console.log('');
   console.log('extract prompt    ' + exists(cfg.PROMPT_FILE)       + '  ' + cfg.PROMPT_FILE);
+  console.log('');
+  const envLang = process.env.CLAUDE_DISTILL_LANG || '(unset)';
+  const resolved = localeMod.resolveLocale();
+  console.log('locale (env)      ·  CLAUDE_DISTILL_LANG=' + envLang);
+  console.log('locale (resolved) ·  ' + resolved + '  (transcript 자동 감지가 우선 — 세션 분석 시점에 결정)');
 }
 
 module.exports = { run };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-distill",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Distill knowledge and gotchas from Claude Code session transcripts. Hook-based feedback loop: session → extract → review → accumulate.",
   "bin": {
     "claude-distill": "bin/distill.js",
@@ -39,7 +39,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/parksubeom/claude-distill.git"
+    "url": "git+https://github.com/parksubeom/claude-distill.git"
   },
   "files": [
     "bin",