From 4fd672193f366df5eb2ed0a876b2d54ff2e089d5 Mon Sep 17 00:00:00 2001 From: altair823 Date: Fri, 29 May 2026 02:44:34 +0000 Subject: [PATCH] docs(#4): clarify lang vs code_lang semantic and und=code (Todo #4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit lang_breakdown description에 code 문서는 자연어 감지 미수행(lang="und" 정상) 사실 추가. README에 lang vs code_lang 설명 절 신규 추가. task spec grep: tasks/p9/p9-fb-15 의 rag-v2 언급은 historical 기술 → frozen 유지. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 6 ++++++ docs/wire-schema/v1/schema.schema.json | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0686b51..c5691d5 100644 --- a/README.md +++ b/README.md @@ -103,6 +103,12 @@ kebab doctor 글로벌 플래그: `--readonly` (또는 `KEBAB_READONLY=1`) — 모든 write-path 명령 (`ingest` / `ingest-file` / `ingest-stdin` / `reset`) 을 비활성화, exit 1. `--quiet` — 진행 바 / hint 등 human-readable stderr 억제 (exit code / stdout 출력은 그대로). `KEBAB_PROGRESS=plain` — TTY 가 없는 환경에서도 진행 상황을 plain-text 한 줄씩 stderr 로 출력 (spinner 대신). +### `lang` vs `code_lang` (v0.20.2) + +- `doc.lang` / search hit 의 `lang` 은 **자연어 prose** 의 언어 (lingua 감지 — Markdown / PDF 본문). 감지 불가 / 자연어 아님 → `"und"`. +- 소스코드 문서는 자연어 감지를 하지 않으므로 `lang = "und"` 가 정상이다. 소스 언어는 별도 `code_lang` (`rust` / `python` / ...) 에 담긴다. +- `schema --json` 의 `lang_breakdown` 에서 `und` 비중이 높은 것은 보통 code 문서 비중 때문 — `code_lang_breakdown` / `code_lang_chunk_breakdown` 로 소스 언어 분포를 확인한다. + ### Score 해석 (fb-38) `search_hit.v1.score` 는 **ranking signal** 이지 confidence 가 아니다. `score_kind` 필드로 의미 선언: diff --git a/docs/wire-schema/v1/schema.schema.json b/docs/wire-schema/v1/schema.schema.json index dd23700..46cfb5a 100644 --- a/docs/wire-schema/v1/schema.schema.json +++ b/docs/wire-schema/v1/schema.schema.json @@ -72,7 +72,7 @@ }, "lang_breakdown": { "type": "object", - "description": "p9-fb-37: per-language doc count. NULL lang keyed as the literal string 'null'. Map may be empty on empty corpus.", + "description": "p9-fb-37: per-language doc count. NULL lang keyed as the literal string 'null'. Map may be empty on empty corpus. v0.20.2 (Todo #4) 주의: `lang` 은 자연어 prose 의 lingua 감지 결과 (Markdown 등). 소스코드 문서는 자연어 감지를 하지 않아 `lang = \"und\"` 이며, 소스 언어는 별도 `code_lang_breakdown` 에 집계된다 — 따라서 code 비중이 큰 corpus 에서 `und` 가 높은 것은 설계상 정상 (감지 실패 아님).", "additionalProperties": { "type": "integer", "minimum": 0 } }, "index_bytes": {