From b6423afba4d1ecb621a31ea1f9b13924f554090e Mon Sep 17 00:00:00 2001 From: dd3ok <15044917+dd3ok@users.noreply.github.com> Date: Sat, 4 Jul 2026 23:08:36 +0900 Subject: [PATCH] Add Korean README --- MANIFEST.in | 2 +- README.ko.md | 282 ++++++++++++++++++++++++++++++++++++++ README.md | 225 +++--------------------------- scripts/validate_skill.py | 1 + tests/test_docs.py | 9 ++ tests/test_packaging.py | 4 +- 6 files changed, 311 insertions(+), 212 deletions(-) create mode 100644 README.ko.md diff --git a/MANIFEST.in b/MANIFEST.in index 00968a6..3c10605 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,5 +1,5 @@ recursive-include src/document_briefing_cache/templates *.md.j2 -include README.md LICENSE AGENTS.md VALIDATION.md +include README.md README.ko.md LICENSE AGENTS.md VALIDATION.md recursive-include examples *.json recursive-include evals *.json recursive-include references *.md diff --git a/README.ko.md b/README.ko.md new file mode 100644 index 0000000..c07c9dd --- /dev/null +++ b/README.ko.md @@ -0,0 +1,282 @@ +# Briefprint + +[![Python](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python&logoColor=white)](https://www.python.org/) +[![License](https://img.shields.io/github/license/dd3ok/briefprint)](https://github.com/dd3ok/briefprint/blob/main/LICENSE) +[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/dd3ok/briefprint/ci.yml?branch=main)](https://github.com/dd3ok/briefprint/actions/workflows/ci.yml) + +한 번 읽고, 어디서든 브리핑하세요. + +[English](README.md) | [한국어](README.ko.md) + +Briefprint는 반복 문서 브리핑을 위한 `briefprint` 에이전트 스킬과 Python 런타임입니다. + +문서를 재사용 가능한 구조화 브리핑으로 바꾸고, 문서 지문으로 캐시한 뒤, 같은 내용을 LLM에 다시 읽히지 않고 새 형식으로 렌더링합니다. + +```text +문서형 입력 + -> DocumentInput으로 정규화 + -> 콘텐츠 지문 계산 + -> 캐시 미스만 DocumentSummaryState로 요약 + -> brief / digest / executive / action_items / debug 렌더링 +``` + +## 무엇을 해결하나요? + +일반 요약 흐름은 요청이 조금만 바뀌어도 문서를 다시 LLM에 보냅니다. + +```text +"요약해줘" -> LLM이 전체 문서 읽음 +"짧게 바꿔줘" -> LLM이 다시 읽음 +"Slack용으로" -> LLM이 다시 읽음 +"업데이트 추가" -> 전체를 다시 읽을 수 있음 +``` + +Briefprint는 비용이 큰 경계를 바꿉니다. 비싼 작업은 문서 이해이고, 문서가 한 번 `DocumentSummaryState`가 되면 반복 렌더링은 그 상태를 재사용할 수 있습니다. + +```text +처음 보는 문서 -> 캐시 미스만 요약 +같은 문서 다시 요청 -> 렌더링 출력 캐시 히트 +출력 형식만 변경 -> 캐시된 문서 상태에서 템플릿 렌더링 +문서 하나만 추가 -> 새 문서만 요약 +``` + +이건 의미 기반 캐시가 아닙니다. 정확한 문서 요약 캐시입니다. 그래서 ID, 날짜, 지표, 장애 로그, 티켓, 보고서처럼 오래되거나 근사한 답이 위험한 작업에 더 안전합니다. + +## 빠른 실행 + +Python 런타임 설치: + +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install -e ".[dev]" +``` + +Python 3.10 이상이 필요합니다. 가상환경 활성화 뒤에는 환경에 따라 `python` 명령을 사용해도 됩니다. + +선택 확장: + +```bash +pip install -e ".[llm]" # OpenAI 기반 구조화 요약기 +pip install -e ".[pdf]" # PDF 텍스트 추출 helper +``` + +샘플 실행: + +```bash +python -m document_briefing_cache.cli run \ + --input examples/mixed_documents.json \ + --mode brief \ + --cache-dir .cache \ + --summary-mode rules \ + --show-stats \ + --explain-cache +``` + +같은 명령을 다시 실행하면 반복 문서에 대해서는 요약 호출이 없어야 합니다. + +```text +summarizer_calls: 0 +``` + +같은 문서를 액션 아이템 형식으로 다시 렌더링: + +```bash +python -m document_briefing_cache.cli run \ + --input examples/mixed_documents.json \ + --mode action_items \ + --cache-dir .cache \ + --summary-mode rules \ + --show-stats +``` + +## 에이전트 스킬 설치 + +Codex, Claude Code, Gemini CLI, Antigravity, OpenClaw, Hermes 같은 에이전트 호스트에는 가벼운 스킬 번들만 설치하세요. + +```text +skills/briefprint/ + SKILL.md + agents/openai.yaml + references/*.md +``` + +repo 루트를 에이전트 스킬로 설치하지 마세요. 루트 복사 방식은 테스트, 문서, 예제, eval, 소스 코드, 검증 스크립트까지 같이 복사할 수 있습니다. 자세한 내용은 [docs/agent-skill-installation.md](docs/agent-skill-installation.md)를 보세요. + +Claude.ai description variant: Cache structured briefings for supplied documents, notes, logs, tickets, reports, JSON/XML, or transcripts. Use for repeated summaries, rerendering, digests, actions, risks, or metrics. + +## 벤치마크 결과 + +현재 예제 데이터 기준 로컬 벤치마크 결과입니다. `rules` 요약기를 사용했기 때문에 provider 과금 수치가 아니라 결정적 로컬 추정치입니다. + +```bash +python -m document_briefing_cache.cli benchmark \ + --input examples/mixed_documents.json \ + --incremental-input examples/incident_update.json \ + --cache-dir .cache/readme-benchmark \ + --fresh \ + --mode brief \ + --mode digest \ + --mode executive \ + --mode action_items \ + --json +``` + +| 항목 | 결과 | +|---|---:| +| 시나리오 | 7 | +| 기본 문서 | 3 | +| 업데이트 후 문서 | 4 | +| 매번 다시 요약할 때 입력 토큰 추정 | 1,748 | +| 캐시 미스만 요약할 때 입력 토큰 추정 | 309 | +| 절약 추정 토큰 | 1,439 | +| 절약률 | 82.32% | +| 총 요약 호출 | 4 | +| 문서 캐시 히트 | 16 | +| 문서 캐시 미스 | 4 | +| 품질 경고 행 | 0 | + +시나리오별 핵심 결과: + +| 시나리오 | 요약 호출 | 캐시 인식 입력 토큰 | +|---|---:|---:| +| 문서 3개 최초 브리핑 | 3 | 226 | +| 같은 브리핑 반복 | 0 | 0 | +| digest로 재렌더링 | 0 | 0 | +| executive로 재렌더링 | 0 | 0 | +| action_items로 재렌더링 | 0 | 0 | +| 업데이트 1개 추가 | 1 | 83 | +| 합쳐진 문서 debug 렌더링 | 0 | 0 | + +숫자는 솔직하게 봐야 합니다. 이 결과는 로컬 harness의 토큰 추정치입니다. 실제 청구 비용을 보려면 provider usage, Codex CLI/OTel, 또는 사용하는 호스트의 telemetry와 함께 비교해야 합니다. 벤치마크의 품질 체크는 actions, decisions, risks, metrics에 대한 가벼운 smoke check이며 의미론적 정확도 점수는 아닙니다. + +## 효과가 큰 경우 + +- 같은 문서를 여러 번 요약하거나 형식만 바꾸는 경우 +- 티켓 묶음, 장애 보고서, 회의록, 로그처럼 재사용되는 문서가 많은 경우 +- 기존 문서에 업데이트 하나만 추가되는 경우 +- 액션 아이템, 임원 요약, Slack digest, 위험 보고서처럼 출력 목적이 여러 개인 경우 + +## 효과가 작거나 조심할 경우 + +- 한 번만 보고 버리는 문서 +- 매번 전체 내용이 크게 다시 작성되는 문서 +- 섹션 순서나 ID가 계속 바뀌는 문서 +- 최신 뉴스, 가격, 정책, 법률처럼 외부 최신성이 중요한 요청 + +## 입력 범위 + +현재 CLI의 `--input`은 로컬 파일 경로를 받습니다. `http://` 또는 `https://` URL을 직접 가져오지는 않습니다. + +JSON, XML, HTML, `DocumentInput.source` 안에 들어있는 URL 메타데이터는 evidence와 렌더링을 위한 source/reference 정보로 보존됩니다. 원격 문서를 요약하려면 먼저 외부에서 가져와 로컬 파일이나 정규화된 payload로 넘기면 됩니다. + +## 모드 + +| 모드 | 용도 | +|---|---| +| `brief` | 표준 다중 문서 브리핑 | +| `executive` | 의사결정자를 위한 짧은 요약 | +| `action_items` | 담당자, 기한, 후속 작업 중심 | +| `digest` | 채팅 친화적인 짧은 digest | +| `debug` | 파싱된 요약, evidence, 캐시 통계 | + +## 캐시와 보안 + +권장 기본값: + +- 반복 문서에는 `document_summaries`를 TTL 캐시로 유지 +- 템플릿 렌더링은 싸기 때문에 `rendered_outputs`는 짧게 유지 +- 민감한 일회성 문서는 `ephemeral` 사용 + +```bash +python -m document_briefing_cache.cli run \ + --input examples/mixed_documents.json \ + --cache-policy ttl \ + --document-ttl 30d \ + --output-ttl 24h \ + --prune-on-start +``` + +민감 문서: + +```bash +export DBC_CACHE_HMAC_SECRET="replace-with-a-local-secret" +python -m document_briefing_cache.cli run \ + --input sensitive.json \ + --sensitive \ + --cache-hmac-secret-env DBC_CACHE_HMAC_SECRET +``` + +민감 문서의 안전한 기본값은 영구 캐시를 남기지 않는 것입니다. `--sensitive`는 `--cache-policy ephemeral --no-output-cache --redact-pii --delete-on-exit created`의 편의 옵션입니다. + +`--redact-pii`는 `basic-contact-v1` 프로필을 적용합니다. 이메일, 한국 휴대폰 번호, 미국 전화번호를 다루지만 완전한 PII 탐지기는 아닙니다. + +`--redact-secrets`는 `basic-secrets-v1` 프로필을 적용합니다. bearer tokens, API keys, webhook URLs, card-like values, secret-shaped JSON keys를 best-effort로 가립니다. Secret redaction is not included in --sensitive; 민감 문서에 비밀값이 들어갈 수 있으면 별도로 켜야 합니다. + +`--cache-hmac-secret-env`는 HMAC-SHA256으로 캐시 envelope을 서명합니다. HMAC은 tamper detection only, not encryption 입니다. 캐시 내용 자체를 숨겨야 한다면 encrypted storage, tmpfs, 또는 별도 암호화 저장소를 사용해야 합니다. + +캐시 관리: + +```bash +python -m document_briefing_cache.cli cache stats --cache-dir .cache --json +python -m document_briefing_cache.cli cache prune --cache-dir .cache --older-than 30d --dry-run --json +python -m document_briefing_cache.cli cache clear --cache-dir .cache --layer rendered_outputs --yes +``` + +## LLM 요약기 + +기본 `rules` 요약기는 로컬, 결정적, 토큰-free 요약기입니다. 데모, 캐시 검증, 얕은 추출에 적합합니다. + +새 문서에 대해 고품질 요약이 필요하면 캐시 미스 단계에 LLM 요약기를 연결하고, 출력은 `DocumentSummaryState` 구조를 유지하세요. + +```bash +OPENAI_API_KEY="..." python -m document_briefing_cache.cli run \ + --input examples/mixed_documents.json \ + --summary-mode openai \ + --openai-model gpt-4.1-mini \ + --llm-timeout 60 \ + --llm-max-retries 2 \ + --llm-max-input-tokens 12000 \ + --llm-max-output-tokens 4000 \ + --cache-dir .cache \ + --show-stats +``` + +주의: LLM 기반 요약기는 캐시 미스 문서를 설정된 provider로 보냅니다. 캐시 디렉터리는 plaintext JSON이며 구조화 요약, 이름, ID, 날짜, 지표, evidence quote, source, 렌더링 결과를 저장할 수 있습니다. + +## 검증 + +```bash +python -m pytest -q +python scripts/validate_skill.py +python scripts/validate_skill.py --run-evals +``` + +`--run-evals`는 actions, risks, metrics, evidence에 대한 구조화 상태 검증을 실행합니다. `trigger_eval_cases.json`는 static boundary fixtures로 트리거 경계를 점검합니다. 이 fixture는 의도한 트리거와 near-miss를 확인하지만, 실제 모델이 스킬을 호출하는지 여부를 측정하지는 않습니다. + +`evals/model_invocation_benchmark_cases.json`는 실제 스킬 호출 telemetry를 제공하는 호스트를 위한 수동 벤치마크 worksheet입니다. schema 검증은 하지만 CI가 모델 측 라우팅을 측정한다고 주장하지는 않습니다. + +## repo 구성 + +```text +skills/briefprint/ 설치 가능한 에이전트 스킬 +src/document_briefing_cache/ Python 런타임과 CLI +src/document_briefing_cache/templates/ + 출력 템플릿 +examples/ 샘플 입력과 데모 +evals/ eval 및 벤치마크 fixture +references/ 아키텍처, 스키마, LLM 계약, 로드맵 +docs/agent-skill-installation.md 호스트별 설치 문서 +tests/ 테스트 +scripts/validate_skill.py repo 검증 스크립트 +``` + +## 더 읽을 문서 + +- [README.md](README.md) +- [docs/agent-skill-installation.md](docs/agent-skill-installation.md) +- [references/architecture.md](references/architecture.md) +- [references/schema.md](references/schema.md) +- [references/llm-contract.md](references/llm-contract.md) +- [references/best-practices.md](references/best-practices.md) +- [references/competitive-roadmap.md](references/competitive-roadmap.md) diff --git a/README.md b/README.md index b6f1389..3952822 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Read once. Brief anywhere. -[English](#english) | [한국어](#korean) +[English](README.md) | [한국어](README.ko.md) Briefprint packages the `briefprint` agent skill and Python runtime for repeated document briefing work. @@ -20,9 +20,7 @@ document-like input -> render brief / digest / executive / action items / debug ``` -## English - -### What It Solves +## What It Solves Most summarization workflows pay again every time the user asks for a slightly different answer. @@ -44,7 +42,7 @@ one new update -> summarize only the new document This is not a semantic cache. It is an exact document-summary cache, which is safer for IDs, dates, metrics, incident logs, tickets, and reports where stale or approximate answers are unacceptable. -### Quick Start +## Quick Start Install the Python runtime: @@ -92,7 +90,7 @@ python -m document_briefing_cache.cli run \ --show-stats ``` -### Agent Skill Install +## Agent Skill Install For Codex, Claude Code, Gemini CLI, Antigravity, OpenClaw, Hermes, or another agent host, install only the lightweight skill bundle: @@ -107,7 +105,7 @@ Do not install the repository root as an agent skill. Root-copy installers can i Claude.ai description variant: Cache structured briefings for supplied documents, notes, logs, tickets, reports, JSON/XML, or transcripts. Use for repeated summaries, rerendering, digests, actions, risks, or metrics. -### Benchmark Receipts +## Benchmark Receipts This local benchmark was run on the current examples with the deterministic `rules` summarizer: @@ -152,27 +150,27 @@ Scenario shape: Honest number warning: these are deterministic local estimates from the benchmark harness, not provider billing telemetry. Use OpenAI/provider usage or host telemetry when exact billing matters. The benchmark also includes lightweight quality smoke checks for obvious actions, decisions, risks, and metrics; it is not a semantic accuracy score. -### When It Helps +## When It Helps - Repeated briefs over the same tickets, incident reports, meeting notes, logs, or PR summaries. - Rendering one source into several outputs: executive memo, Slack digest, action list, risk report, debug view. - Incremental feeds where one new item is appended and older items keep stable IDs. - Agent workflows where the same source needs to be reused across several turns. -### When It Does Not Help Much +## When It Does Not Help Much - One-off documents that will never be reused. - Documents that are rewritten wholesale each time. - Inputs with unstable section IDs or reordered sections, unless you pass structured records with stable IDs. - Requests that require fresh external facts, policy changes, current prices, or live news. -### Input Scope +## Input Scope The CLI `--input` option currently accepts local file path values. It does not fetch URLs such as `http://` or `https://`. URL-bearing metadata inside JSON, XML, HTML, or `DocumentInput.source` is preserved as source/reference metadata for evidence and rendering. To summarize remote content, fetch it outside this tool and pass the saved local file or normalized payload. -### Modes +## Modes | Mode | Use | |---|---| @@ -182,7 +180,7 @@ URL-bearing metadata inside JSON, XML, HTML, or `DocumentInput.source` is preser | `digest` | Chat-friendly short digest | | `debug` | Parsed summaries, evidence, and cache stats | -### Cache And Privacy +## Cache And Privacy Recommended defaults: @@ -225,7 +223,7 @@ python -m document_briefing_cache.cli cache prune --cache-dir .cache --older-tha python -m document_briefing_cache.cli cache clear --cache-dir .cache --layer rendered_outputs --yes ``` -### LLM Summarizer +## LLM Summarizer The default `rules` summarizer is local, deterministic, and token-free. It is useful for demos, cache validation, and shallow extraction. @@ -246,7 +244,7 @@ OPENAI_API_KEY="..." python -m document_briefing_cache.cli run \ Privacy note: LLM-backed summarizers send cache misses to the configured provider. Cache directories are plaintext JSON and may persist structured summaries, names, IDs, dates, metrics, evidence quotes, sources, and rendered outputs. -### Validate +## Validate ```bash python -m pytest -q @@ -258,7 +256,7 @@ python scripts/validate_skill.py --run-evals `evals/model_invocation_benchmark_cases.json` is a manual benchmark worksheet for hosts that expose real skill invocation telemetry. It is schema-validated, but CI does not claim to measure model-side routing. -### Repository Map +## Repository Map ```text skills/briefprint/ installable agent skill @@ -273,201 +271,10 @@ tests/ unit and behavior tests scripts/validate_skill.py repository validation ``` - - -## 한국어 - -### 무엇인가요? - -Briefprint는 반복 문서 브리핑을 위한 경량 에이전트 스킬과 Python 런타임입니다. 한 번 읽은 문서를 `DocumentSummaryState`라는 구조화 상태로 저장하고, 이후에는 같은 문서를 다시 요약하지 않고 여러 형식으로 렌더링합니다. - -쉽게 말하면: - -```text -문서 읽기와 이해는 비싼 작업 -형식 바꾸기는 싼 작업 - -비싼 작업은 캐시 미스 때만 하고, -반복 요청은 캐시된 구조화 결과로 처리합니다. -``` - -### 해결하려는 문제 - -일반 요약 흐름은 요청이 조금만 바뀌어도 문서를 다시 LLM에 보냅니다. - -```text -"요약해줘" -> LLM이 전체 문서 읽음 -"짧게 바꿔줘" -> LLM이 다시 읽음 -"Slack용으로" -> LLM이 다시 읽음 -"업데이트 추가" -> 전체를 다시 읽을 수 있음 -``` - -Briefprint는 문서별 지문을 기준으로 캐시합니다. - -```text -처음 보는 문서 -> 요약 후 DocumentSummaryState 저장 -같은 문서 다시 요청 -> 캐시 사용 -출력 형식만 변경 -> 템플릿 렌더링 -문서 하나만 추가 -> 새 문서만 요약 -``` - -그래서 티켓, 장애 보고서, 회의록, 로그, PR 요약처럼 같은 원문을 여러 번 재사용하는 업무에 적합합니다. - -### 빠른 실행 - -```bash -python3 -m venv .venv -source .venv/bin/activate -pip install -e ".[dev]" -``` - -선택 확장: - -```bash -pip install -e ".[llm]" # OpenAI 기반 구조화 요약기 -pip install -e ".[pdf]" # PDF 텍스트 추출 helper -``` - -샘플 실행: - -```bash -python -m document_briefing_cache.cli run \ - --input examples/mixed_documents.json \ - --mode brief \ - --cache-dir .cache \ - --summary-mode rules \ - --show-stats \ - --explain-cache -``` - -같은 명령을 다시 실행하면 반복 문서에 대해서는 요약 호출이 없어야 합니다. - -```text -summarizer_calls: 0 -``` - -같은 문서를 액션 아이템 형식으로 다시 렌더링: - -```bash -python -m document_briefing_cache.cli run \ - --input examples/mixed_documents.json \ - --mode action_items \ - --cache-dir .cache \ - --summary-mode rules \ - --show-stats -``` - -### 에이전트 스킬 설치 - -에이전트에 설치할 때는 repo 전체가 아니라 아래 폴더만 설치합니다. - -```text -skills/briefprint/ -``` - -이 폴더에는 스킬 실행에 필요한 `SKILL.md`, `agents/openai.yaml`, `references/*.md`만 들어갑니다. repo 루트를 스킬로 설치하면 테스트, 문서, 예제, eval, 소스 코드, 검증 스크립트까지 같이 들어갈 수 있으므로 피해야 합니다. - -자세한 설치 경로는 [docs/agent-skill-installation.md](docs/agent-skill-installation.md)를 보세요. - -### 벤치마크 결과 - -현재 예제 데이터 기준 로컬 벤치마크 결과입니다. `rules` 요약기를 사용했기 때문에 provider 과금 수치가 아니라 결정적 로컬 추정치입니다. - -| 항목 | 결과 | -|---|---:| -| 시나리오 | 7 | -| 기본 문서 | 3 | -| 업데이트 후 문서 | 4 | -| 매번 다시 요약할 때 입력 토큰 추정 | 1,748 | -| 캐시 미스만 요약할 때 입력 토큰 추정 | 309 | -| 절약 추정 토큰 | 1,439 | -| 절약률 | 82.32% | -| 총 요약 호출 | 4 | -| 문서 캐시 히트 | 16 | -| 문서 캐시 미스 | 4 | -| 품질 경고 행 | 0 | - -시나리오별 핵심 결과: - -| 시나리오 | 요약 호출 | 캐시 인식 입력 토큰 | -|---|---:|---:| -| 문서 3개 최초 브리핑 | 3 | 226 | -| 같은 브리핑 반복 | 0 | 0 | -| digest로 재렌더링 | 0 | 0 | -| executive로 재렌더링 | 0 | 0 | -| action_items로 재렌더링 | 0 | 0 | -| 업데이트 1개 추가 | 1 | 83 | -| 합쳐진 문서 debug 렌더링 | 0 | 0 | - -숫자는 솔직하게 봐야 합니다. 이 결과는 로컬 harness의 토큰 추정치입니다. 실제 청구 비용을 보려면 provider usage, Codex CLI/OTel, 또는 사용하는 호스트의 telemetry와 함께 비교해야 합니다. - -### 효과가 큰 경우 - -- 같은 문서를 여러 번 요약하거나 형식만 바꾸는 경우 -- 티켓 묶음, 장애 보고서, 회의록, 로그처럼 재사용되는 문서가 많은 경우 -- 기존 문서에 업데이트 하나만 추가되는 경우 -- 액션 아이템, 임원 요약, Slack digest, 위험 보고서처럼 출력 목적이 여러 개인 경우 - -### 효과가 작거나 조심할 경우 - -- 한 번만 보고 버리는 문서 -- 매번 전체 내용이 크게 다시 작성되는 문서 -- 섹션 순서나 ID가 계속 바뀌는 문서 -- 최신 뉴스, 가격, 정책, 법률처럼 외부 최신성이 중요한 요청 - -### 입력 범위 - -현재 CLI의 `--input`은 로컬 파일 경로를 받습니다. `http://` 또는 `https://` URL을 직접 가져오지는 않습니다. - -JSON, XML, HTML, `DocumentInput.source` 안에 들어있는 URL 메타데이터는 evidence와 렌더링을 위한 source/reference 정보로 보존됩니다. 원격 문서를 요약하려면 먼저 외부에서 가져와 로컬 파일이나 정규화된 payload로 넘기면 됩니다. - -### 캐시와 보안 - -민감 문서에는 기본적으로 영구 캐시를 남기지 않는 흐름을 권장합니다. - -```bash -export DBC_CACHE_HMAC_SECRET="replace-with-a-local-secret" -python -m document_briefing_cache.cli run \ - --input sensitive.json \ - --sensitive \ - --cache-hmac-secret-env DBC_CACHE_HMAC_SECRET -``` - -`--sensitive`는 `--cache-policy ephemeral --no-output-cache --redact-pii --delete-on-exit created`의 편의 옵션입니다. - -`--redact-pii`는 `basic-contact-v1` 프로필을 적용합니다. 이메일, 한국 휴대폰 번호, 미국 전화번호를 다루지만 완전한 PII 탐지기는 아닙니다. - -`--redact-secrets`는 `basic-secrets-v1` 프로필을 적용합니다. bearer tokens, API keys, webhook URLs, card-like values, secret-shaped JSON keys를 best-effort로 가립니다. Secret redaction is not included in --sensitive; 민감 문서에 비밀값이 들어갈 수 있으면 별도로 켜야 합니다. - -HMAC 서명은 tamper detection only, not encryption 입니다. 캐시 내용 자체를 숨겨야 한다면 encrypted storage, tmpfs, 또는 별도 암호화 저장소를 사용해야 합니다. - -### 검증 - -```bash -python -m pytest -q -python scripts/validate_skill.py -python scripts/validate_skill.py --run-evals -``` - -`--run-evals`는 actions, risks, metrics, evidence에 대한 구조화 상태 검증을 실행합니다. `trigger_eval_cases.json`는 static boundary fixtures로 트리거 경계를 점검합니다. 이 fixture는 의도한 트리거와 near-miss를 확인하지만, 실제 모델이 스킬을 호출하는지 여부를 측정하지는 않습니다. - -### repo 구성 - -```text -skills/briefprint/ 설치 가능한 에이전트 스킬 -src/document_briefing_cache/ Python 런타임과 CLI -src/document_briefing_cache/templates/ - 출력 템플릿 -examples/ 샘플 입력과 데모 -evals/ eval 및 벤치마크 fixture -references/ 아키텍처, 스키마, LLM 계약, 로드맵 -docs/agent-skill-installation.md 호스트별 설치 문서 -tests/ 테스트 -scripts/validate_skill.py repo 검증 스크립트 -``` - -### 더 읽을 문서 +## Further Reading +- [README.ko.md](README.ko.md) +- [docs/agent-skill-installation.md](docs/agent-skill-installation.md) - [references/architecture.md](references/architecture.md) - [references/schema.md](references/schema.md) - [references/llm-contract.md](references/llm-contract.md) diff --git a/scripts/validate_skill.py b/scripts/validate_skill.py index 21accfd..28ae8fd 100644 --- a/scripts/validate_skill.py +++ b/scripts/validate_skill.py @@ -11,6 +11,7 @@ REQUIRED_FILES = [ "README.md", + "README.ko.md", "AGENTS.md", "pyproject.toml", "src/document_briefing_cache/models.py", diff --git a/tests/test_docs.py b/tests/test_docs.py index ec605fe..03e2163 100644 --- a/tests/test_docs.py +++ b/tests/test_docs.py @@ -23,6 +23,15 @@ def test_readme_documents_briefprint_skill_branding(): assert "briefprint-skill" not in readme +def test_readme_links_korean_readme(): + readme = (ROOT / "README.md").read_text(encoding="utf-8") + korean = (ROOT / "README.ko.md").read_text(encoding="utf-8") + + assert "[한국어](README.ko.md)" in readme + assert "[English](README.md)" in korean + assert "한 번 읽고, 어디서든 브리핑하세요." in korean + + def test_readme_includes_claude_ai_description_variant_under_200_chars(): readme = (ROOT / "README.md").read_text(encoding="utf-8") marker = "Claude.ai description variant:" diff --git a/tests/test_packaging.py b/tests/test_packaging.py index d677d9e..6fd02c9 100644 --- a/tests/test_packaging.py +++ b/tests/test_packaging.py @@ -43,6 +43,6 @@ def test_wheel_install_surface_is_runtime_only(): assert 'where = ["src"]' in pyproject assert 'document_briefing_cache = ["templates/*.md.j2"]' in pyproject - assert "include README.md LICENSE AGENTS.md SKILL.md VALIDATION.md" not in manifest - assert "include README.md LICENSE AGENTS.md VALIDATION.md" in manifest + assert "include README.md README.ko.md LICENSE AGENTS.md SKILL.md VALIDATION.md" not in manifest + assert "include README.md README.ko.md LICENSE AGENTS.md VALIDATION.md" in manifest assert "recursive-include skills *.md *.yaml" in manifest