From 1c8d8e1d34a15fb6bb6e04db25764237d718eebc Mon Sep 17 00:00:00 2001 From: devswha Date: Fri, 7 Aug 2026 21:36:47 +0900 Subject: [PATCH 1/2] docs: unbreak the Three Independent Axes table in all four READMEs Two defects from the v7 cutover: EN/KR ran body text straight into the last table row (no blank line), and the six-column layout squeezed the CLI/Config/ Playground cells until code tokens wrapped vertically on GitHub. The three mapping columns collapse into one 'Select with' cell per axis. --- README.md | 12 ++++++------ README_JA.md | 10 +++++----- README_KR.md | 11 ++++++----- README_ZH.md | 10 +++++----- 4 files changed, 22 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 73f1b2c..049e07c 100644 --- a/README.md +++ b/README.md @@ -122,17 +122,17 @@ Scores are editing signals with false positives and false negatives, not proof o Patina does not infer one axis from another. Omit Persona and Register to keep the source voice and register. -| Axis | Controls | Does not control | CLI | Config | Playground | -|---|---|---|---|---|---| -| **Document Type** | Genre, purpose, structural conventions, pattern policy | Voice, casual/professional delivery, meaning floors | `--document-type` | `document-type` | Document | -| **Persona** | Reusable voice fingerprint: vocabulary, rhythm, explanation habits | Genre, pattern policy, register, meaning floors | `--persona` | `persona` | Voice | -| **Register** | `casual` or `professional` delivery | Genre, persona identity, pattern policy | `--register` | `register` | Register | +| Axis | Controls | Does not control | Select with | +|---|---|---|---| +| **Document Type** | Genre, purpose, structural conventions, pattern policy | Voice, casual/professional delivery, meaning floors | `--document-type` · config `document-type` · Playground "Document Type" | +| **Persona** | Reusable voice fingerprint: vocabulary, rhythm, explanation habits | Genre, pattern policy, register, meaning floors | `--persona` · config `persona` · Playground "Persona" | +| **Register** | `casual` or `professional` delivery | Genre, persona identity, pattern policy | `--register` · config `register` · Playground "Register" | + Meaning preservation is the outer guard. If instructions appear to overlap, field ownership resolves them: Document Type wins for document structure and domain constraints, Persona for idiolect and rhythm, and Register for casual/professional markers. An explicit value never fills an omitted axis. - Examples: ```bash diff --git a/README_JA.md b/README_JA.md index 68feb13..a7b2156 100644 --- a/README_JA.md +++ b/README_JA.md @@ -110,11 +110,11 @@ printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon.' \ patina は一つの軸から別の軸を推論しません。Persona と Register を省略すると、原文のボイスとレジスターを保持します。 -| 軸 | 制御するもの | 制御しないもの | CLI | 設定 | Playground | -|---|---|---|---|---|---| -| **Document Type** | ジャンル、目的、構造慣習、パターン方針 | ボイス、casual/professional の伝え方、意味保全フロア | `--document-type` | `document-type` | Document | -| **Persona** | 再利用ボイス指紋：語彙、リズム、説明習慣 | ジャンル、パターン方針、Register、意味保全フロア | `--persona` | `persona` | Voice | -| **Register** | `casual` または `professional` の伝え方 | ジャンル、Persona の同一性、パターン方針 | `--register` | `register` | Register | +| 軸 | 制御するもの | 制御しないもの | 選択方法 | +|---|---|---|---| +| **Document Type** | ジャンル、目的、構造慣習、パターン方針 | ボイス、casual/professional の伝え方、意味保全フロア | `--document-type` · 設定 `document-type` · Playground "Document Type" | +| **Persona** | 再利用ボイス指紋：語彙、リズム、説明習慣 | ジャンル、パターン方針、Register、意味保全フロア | `--persona` · 設定 `persona` · Playground "Persona" | +| **Register** | `casual` または `professional` の伝え方 | ジャンル、Persona の同一性、パターン方針 | `--register` · 設定 `register` · Playground "Register" | ```bash patina --document-type email --register professional note.md diff --git a/README_KR.md b/README_KR.md index a167e0c..15e8160 100644 --- a/README_KR.md +++ b/README_KR.md @@ -110,11 +110,12 @@ printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon.' \ patina는 한 축에서 다른 축을 추론하지 않습니다. Persona와 Register를 생략하면 원문의 목소리와 레지스터를 보존합니다. -| 축 | 정하는 것 | 정하지 않는 것 | CLI | 설정 | Playground | -|---|---|---|---|---|---| -| **Document Type** | 장르·용도·구조 관습·패턴 정책 | 목소리, casual/professional 전달 방식, 의미 보존 하한 | `--document-type` | `document-type` | Document | -| **Persona** | 재사용 보이스 지문: 어휘·리듬·설명 습관 | 장르, 패턴 정책, Register, 의미 보존 하한 | `--persona` | `persona` | Voice | -| **Register** | `casual` 또는 `professional` 전달 방식 | 장르, Persona 정체성, 패턴 정책 | `--register` | `register` | Register | +| 축 | 정하는 것 | 정하지 않는 것 | 선택 방법 | +|---|---|---|---| +| **Document Type** | 장르·용도·구조 관습·패턴 정책 | 목소리, casual/professional 전달 방식, 의미 보존 하한 | `--document-type` · 설정 `document-type` · Playground "Document Type" | +| **Persona** | 재사용 보이스 지문: 어휘·리듬·설명 습관 | 장르, 패턴 정책, Register, 의미 보존 하한 | `--persona` · 설정 `persona` · Playground "Persona" | +| **Register** | `casual` 또는 `professional` 전달 방식 | 장르, Persona 정체성, 패턴 정책 | `--register` · 설정 `register` · Playground "Register" | + 의미 보존은 세 축 바깥의 공통 하한입니다. 지시가 겹쳐 보이면 소유 필드로 판단합니다. 문서 구조와 도메인 제약은 Document Type, 고유 어휘와 리듬은 Persona, casual/professional 표지는 Register가 정합니다. 명시된 한 축으로 생략된 다른 축을 diff --git a/README_ZH.md b/README_ZH.md index 09e7b0c..9f7fe1b 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -112,11 +112,11 @@ printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon.' \ patina 不会从一个轴推断另一个轴。省略 Persona 和 Register 时，会保留原文的声音与语域。 -| 轴 | 控制 | 不控制 | CLI | 配置 | Playground | -|---|---|---|---|---|---| -| **Document Type** | 体裁、用途、结构惯例、模式策略 | 声音、casual/professional 表达、含义保留下限 | `--document-type` | `document-type` | Document | -| **Persona** | 可复用声音指纹：词汇、节奏、解释习惯 | 体裁、模式策略、Register、含义保留下限 | `--persona` | `persona` | Voice | -| **Register** | `casual` 或 `professional` 表达方式 | 体裁、Persona 身份、模式策略 | `--register` | `register` | Register | +| 轴 | 控制 | 不控制 | 选择方式 | +|---|---|---|---| +| **Document Type** | 体裁、用途、结构惯例、模式策略 | 声音、casual/professional 表达、含义保留下限 | `--document-type` · 配置 `document-type` · Playground "Document Type" | +| **Persona** | 可复用声音指纹：词汇、节奏、解释习惯 | 体裁、模式策略、Register、含义保留下限 | `--persona` · 配置 `persona` · Playground "Persona" | +| **Register** | `casual` 或 `professional` 表达方式 | 体裁、Persona 身份、模式策略 | `--register` · 配置 `register` · Playground "Register" | ```bash patina --document-type email --register professional note.md From 5962aff084945a02706839b3059a379b10980e6f Mon Sep 17 00:00:00 2001 From: devswha Date: Fri, 7 Aug 2026 21:44:11 +0900 Subject: [PATCH 2/2] docs: cut the READMEs to the essentials MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All four READMEs drop from ~250 lines to ~130: one pitch paragraph plus five value bullets, a three-path quick start, the axes table, one commands block with the config example, a facts table, and links. The CI yaml, how-it-works diagram, giant command table, and long persona section move behind their existing docs links. Structure informed by getpaseo/paseo's README (structure only; no text copied — AGPL source, expression written fresh). Every pinned contract survives: hero GIFs/alt rules, version badge, config-example version, the canonical 184-pattern catalog line, and the 'full 184-pattern catalog' phrase. --- README.md | 218 ++++++++++----------------------------------------- README_JA.md | 197 ++++++++++------------------------------------ README_KR.md | 203 ++++++++++------------------------------------- README_ZH.md | 199 ++++++++++------------------------------------ 4 files changed, 169 insertions(+), 648 deletions(-) diff --git a/README.md b/README.md index 049e07c..b600a7d 100644 --- a/README.md +++ b/README.md @@ -33,42 +33,26 @@

Paste AI-sounding text → patina rewrites it in place, keeps the facts (the "30 templates" number survives), and drops the deterministic AI signal 100 → 0 (MPS 100 / Fidelity 75).

-**The words are not the tell. The architecture is.** We ran a pre-registered study with independent cross-family LLM judges: a rewrite can strip the AI vocabulary, yet judges still recognize AI documents by their *shape* — uniform paragraphs, checklist-complete coverage, the tidy problem→lesson arc. Word-level cleanup moved judged AI-likeness a lot on English documents (−23 points) and barely at all on long Korean ones. That result decides patina's design: detect both layers, and publish the losses next to the wins ([the study](docs/research/2026-rewrite-efficacy-study1.md)). -patina is a deterministic, pattern-based humanizer for Korean, English, Chinese, and Japanese. It finds AI-sounding phrasing and rewrites it without changing the claim, numbers, polarity, or causation. It is not a black-box paraphraser, authorship detector, or detector-bypass tool — it is built for allowed AI-assisted drafting where the author wants cleaner voice, an audit trail, and meaning-preservation checks. +patina is a deterministic, pattern-based humanizer for Korean, English, Chinese, and Japanese. It finds AI-sounding phrasing and rewrites it **without changing the claim, numbers, polarity, or causation** — built for allowed AI-assisted drafting, not for evading detectors. -More examples: [Before/After Gallery](docs/EXAMPLES.md) ([한국어](docs/EXAMPLES_KR.md)) · [CLI transcript](docs/DEMO.md). +- **Auditable, not a black box** — 184 named patterns drive every edit; `--diff` shows exactly what changed and why. +- **Meaning survives, verified** — every rewrite is gated by meaning-preservation (MPS) and fidelity floors; drifted rewrites are retried or rolled back. +- **Three independent axes** — Document Type owns genre, Persona owns voice, Register owns delivery. Omit any axis to preserve the source. +- **Every surface** — agent skill (Claude Code · Codex · Cursor · OpenCode), Node CLI, and a [browser playground](https://patina.vibetip.help/). +- **Honest about limits** — scores are editing signals, not authorship proof; our own [pre-registered study](docs/research/2026-rewrite-efficacy-study1.md) publishes where rewriting fails alongside where it works. ## Quick Start -### Browser playground +**Browser — nothing to install.** Open **[patina.vibetip.help](https://patina.vibetip.help/)** and paste text. Rewrites run server-side with the MPS/fidelity gates; API mode forwards your own key per request (never stored or logged). -Open **[patina.vibetip.help](https://patina.vibetip.help/)** — paste KO / EN / ZH / JA text for a real rewrite gated by the MPS/fidelity floors, with the deterministic AI signal measured before → after. Rewrites and scoring run server-side; the free tier uses the service's own model key (rate-limited). **API mode** forwards your own key per request through the patina server to the provider you pick — never stored or logged (metrics are sanitized: no text, prompt, output, key, or IP). A hosted **Pro** tier unlocks higher limits — [see pricing](https://patina.vibetip.help/#pricing). - -### Agent skill - -**Let your coding agent install it** — paste this into Claude Code, Codex CLI, Cursor, Gemini CLI, or any agent: +**Agent skill — paste this into Claude Code, Codex CLI, Cursor, or any agent:** ```text Install patina by following https://raw.githubusercontent.com/devswha/patina/main/INSTALLATION.md ``` -The agent fetches [`INSTALLATION.md`](INSTALLATION.md) (written for AI agents) and runs the right install path for your host, then verifies it. Or do it yourself: - -**Claude Code — plugin marketplace (no clone, recommended):** - -```text -/plugin marketplace add devswha/patina -/plugin install patina@patina -``` - -**Claude Code · Codex CLI · Cursor · OpenCode — install script:** - -```bash -curl -fsSL https://raw.githubusercontent.com/devswha/patina/main/install.sh | bash -``` - -Then run the skill from Claude Code, Codex CLI, Cursor, or OpenCode: +Then use it: ```text /patina --lang en @@ -76,51 +60,18 @@ Then run the skill from Claude Code, Codex CLI, Cursor, or OpenCode: [paste your text here] ``` -Useful skill calls: - -```text -/patina --document-type email --register professional -/patina --document-type blog --persona pragmatic-founder -``` - -### Standalone CLI - -Requires Node.js >= 18. - -```bash -npx patina-cli doctor -npx patina-cli --lang en input.txt -``` - -Use a logged-in local model CLI without an API key: +**CLI — Node >= 18:** ```bash -printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon.' \ - | npx patina-cli --lang en --backend codex-cli +npx patina-cli --lang en input.txt # rewrite +npx patina-cli doctor # check backends and keys ``` -Supported local backends: `codex-cli`, `claude-cli`, `gemini-cli`, `kimi-cli` — patina passes the strongest documented default model per backend. See [Authentication](docs/AUTHENTICATION.md) ([한국어](docs/AUTHENTICATION_KR.md)). - -For large `--batch` runs, prefer an OpenAI-compatible HTTP backend; local CLI backends are agent runtimes, capped conservatively with `--timeout-ms`, `--max-concurrency`, `--max-retries`, and `--max-failures` for batch safety. - -## What You Get - -| | | -|---|---| -| **184 patterns** | 37 rewrite-capable + 9 score-only viral-hook per language (46 each across KO/EN/ZH/JA) — see the full 184-pattern catalog in [PATTERNS.md](docs/PATTERNS.md) | -| **Modes** | rewrite · verify · audit · score · diff | -| **Surfaces** | agent skill · Node CLI · in-place preview · browser playground (rewrite + score) | -| **Rewrite axes** | `--document-type` controls genre/policy · `--persona` controls reusable voice · `--register` controls casual/professional delivery | -| **Free usage** | logged-in `codex`, `claude`, or `gemini` CLI can run rewrites without `PATINA_API_KEY` | -| **Calibration** | 67.3% editing-hotspot catch [63.5–71.0%] across GPT-5.5 / Claude Sonnet 4.6 / Gemini 2.5 Pro (n=600, KO+EN); 16.0% false positives [11.6–21.7%] on KO+EN human controls (n=200) | -| **License** | MIT | - -Scores are editing signals with false positives and false negatives, not proof of authorship. See [Ethics](docs/ETHICS.md). +A logged-in `codex`, `claude`, or `gemini` CLI works with no API key: add `--backend codex-cli`. Full install options: [INSTALLATION.md](INSTALLATION.md). ## Three Independent Axes -Patina does not infer one axis from another. Omit Persona and Register to keep -the source voice and register. +patina does not infer one axis from another. Omit Persona and Register to keep the source voice and register. | Axis | Controls | Does not control | Select with | |---|---|---|---| @@ -128,107 +79,27 @@ the source voice and register. | **Persona** | Reusable voice fingerprint: vocabulary, rhythm, explanation habits | Genre, pattern policy, register, meaning floors | `--persona` · config `persona` · Playground "Persona" | | **Register** | `casual` or `professional` delivery | Genre, persona identity, pattern policy | `--register` · config `register` · Playground "Register" | -Meaning preservation is the outer guard. If instructions appear to overlap, -field ownership resolves them: Document Type wins for document structure and -domain constraints, Persona for idiolect and rhythm, and Register for -casual/professional markers. An explicit value never fills an omitted axis. +Meaning preservation is the outer guard; an explicit value never fills an omitted axis. -Examples: +## Commands ```bash -patina --document-type email --register professional note.md -patina --document-type blog --persona pragmatic-founder post.md -patina --document-type technical --persona technical-explainer --register casual guide.md +patina input.txt # rewrite with defaults +patina --audit input.txt # detect patterns only +patina --score --offline --exit-on 30 input.txt # deterministic CI gate, no API key +patina --diff input.txt # pattern-by-pattern changes +patina --verify input.txt # rewrite + MPS/fidelity floor check +patina --document-type email --register professional input.txt +patina persona new my-voice --from-sample past-posts.txt # learn a reusable voice +patina --persona my-voice draft.md +patina --batch docs/*.md --outdir cleaned/ ``` -## Common Commands +`patina --help` prints the full flag list. CI wrapper for GitHub Actions: [devswha/patina-action](https://github.com/devswha/patina-action) — plus [pre-commit, static-site, Docker, and release integrations](docs/integrations/pre-commit.md). -```bash -patina --lang [mode] [--document-type ] [--persona ] [--register ] input.txt -``` - -| Command | Purpose | -|---|---| -| `patina input.txt` | rewrite with defaults | -| `patina --audit input.txt` | detect patterns only | -| `patina --score input.txt` | output a 0-100 score using the LLM judge plus deterministic signals | -| `patina --score --offline input.txt` | score with deterministic signals only; no backend or API key | -| `patina --score --offline --exit-on 30 input.txt` | offline CI gate with exit code `3` when `overall > 30` | -| `patina --diff input.txt` | show pattern-by-pattern changes | -| `patina --preview page.html` | render rewrites back onto a saved HTML page with toggles and inline diff | -| `patina --verify input.txt` | rewrite, then check MPS/fidelity floors with one retry | -| `patina --document-type email --register professional input.txt` | use email conventions with professional delivery | -| `patina --persona pragmatic-founder input.txt` | rewrite in a built-in voice persona | -| `patina persona new my-voice --from-sample past.txt` | author your own persona from a writing sample | -| `patina persona list` | list built-in + custom personas | -| `patina persona show my-voice --json` | print a persona's normalized config (never the docs body) | -| `patina persona edit my-voice --name "New Name"` | copy-on-edit a persona into `custom/personas/` | -| `patina persona rm my-voice` | remove a custom persona (built-ins are protected) | -| `patina --format json --quiet input.txt` | script-friendly output | -| `patina --batch docs/*.md --outdir cleaned/` | batch file processing | - -`patina --help` prints the full flag list. `patina doctor --json` checks Node, backend, tmux, and API-key readiness without making an LLM call. - -### Personas (voice) - -A **persona** is a reusable voice — a built-in (`patina persona list`) or your own, authored without editing source: - -```bash -patina persona new my-voice --from-sample past-posts.txt # learn from your writing -patina persona new my-voice --describe "plain-spoken founder, casual" -patina --persona my-voice draft.md # then reuse it - -patina persona show my-voice # inspect the normalized config (--json for machine output) -patina persona edit my-voice --name "Founder voice" # copy-on-edit into custom/personas/ (built-ins stay intact) -patina persona rm my-voice # remove a custom persona (--force to skip the confirm) -``` - -Works on ko/en/zh/ja and composes independently with `--document-type` and `--register`. Persona v2 changes reusable voice only; it cannot select a document type, set register, change pattern policy, or define verification/meaning floors. Authored Personas are validated on save, while global rewrite guards and `--verify` enforce meaning preservation independently. - -## CI - -For GitHub Actions, the maintained wrapper is shorter than hand-rolled setup: +Project config lives in `.patina.yaml`: ```yaml -name: Patina prose score -on: - pull_request: - paths: ['**/*.md', '**/*.mdx'] -permissions: - contents: read - pull-requests: read - issues: write -jobs: - patina: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 - - uses: devswha/patina-action@v1 - with: - score-threshold: 30 - lang: auto - comment: true -``` - -Other integrations: [pre-commit](docs/integrations/pre-commit.md), [static sites](docs/integrations/static-sites.md), [Docker](docs/integrations/docker.md), [release workflow](docs/integrations/release.md). - -## How It Works - -```text -Input - -> semantic anchor extraction (claims, polarity, causation, numbers) - -> stylometry + AI-lexicon scan - -> pattern-guided rewrite - -> self-audit and MPS/fidelity checks - -> cleaned text -``` - -If meaning drifts, the change is retried or rolled back. Deterministic analysis lives in `src/features/*`; LLM-backed rewrite and score calls use the selected backend. - -## Configuration - -```yaml -# .patina.yaml version: "7.0.0" language: ko # ko | en | zh | ja document-type: default # genre/purpose + pattern policy @@ -236,30 +107,25 @@ persona: # optional reusable voice; omit to preserve source register: # casual | professional; omit to preserve source ``` -Project `.patina.yaml` overrides defaults. Pattern packs are auto-discovered by language prefix. Additive list keys (`blocklist`, `allowlist`, `skip-patterns`) merge; other arrays replace. +## Facts -## Documentation - -Start here: - -- [Cookbook](docs/COOKBOOK.md) — common recipes and workflows -- [CLI Contract](docs/CLI.md) — flags, formats, score gates, exit behavior -- [Authentication](docs/AUTHENTICATION.md) — local CLI backends and API providers -- [Patterns](docs/PATTERNS.md) — full pattern catalog -- [Subagents & strict flow](docs/agents.md) — optional read-only detector/fidelity/naturalness subagents and the `--strict` multi-pass mode -- [Benchmarks](docs/benchmarks/README.md) · [latest report](docs/benchmarks/latest.md) · [2026 rebaseline](docs/research/2026-rebaseline.md) -- [Measurement harness](docs/HARNESS.md) — index of every benchmark, calibration, and gate tool (incl. the signal-impact ablation harness) -- [FAQ](docs/FAQ.md) ([한국어](docs/FAQ_KR.md)) -- [Ethics](docs/ETHICS.md) -- [Contributing](CONTRIBUTING.md) ([한국어](CONTRIBUTING_KR.md)) -- [Changelog](CHANGELOG.md) +| | | +|---|---| +| **184 patterns** | 37 rewrite-capable + 9 score-only viral-hook per language (46 each across KO/EN/ZH/JA) — see the full 184-pattern catalog in [PATTERNS.md](docs/PATTERNS.md) | +| **Modes** | rewrite · verify · audit · score · diff | +| **Calibration** | 67.3% editing-hotspot catch [63.5–71.0%] across GPT-5.5 / Claude Sonnet 4.6 / Gemini 2.5 Pro (n=600, KO+EN); 16.0% false positives [11.6–21.7%] on KO+EN human controls (n=200) | +| **License** | MIT | -Brand assets and usage rules live in [Branding](docs/BRANDING.md). Design notes live in [DESIGN.md](DESIGN.md). +Scores are editing signals with false positives and false negatives, not proof of authorship. See [Ethics](docs/ETHICS.md). -## Acknowledgements +## Documentation -Inspired by [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh)'s plugin architecture, [Wikipedia's "Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), and [blader/humanizer](https://github.com/blader/humanizer). +- [Cookbook](docs/COOKBOOK.md) — common recipes · [CLI contract](docs/CLI.md) — flags, gates, exit codes +- [Before/After gallery](docs/EXAMPLES.md) ([한국어](docs/EXAMPLES_KR.md)) · [Pattern catalog](docs/PATTERNS.md) +- [Architecture](docs/ARCHITECTURE.md) · [Configuration & authentication](docs/AUTHENTICATION.md) +- [Benchmarks](docs/benchmarks/latest.md) · [Research](docs/research/2026-rewrite-efficacy-study1.md) · [FAQ](docs/FAQ.md) ([한국어](docs/FAQ_KR.md)) +- [Contributing](CONTRIBUTING.md) ([한국어](CONTRIBUTING_KR.md)) · [Changelog](CHANGELOG.md) ## License -MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE). +MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE). Inspired by [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh), [Wikipedia's "Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), and [blader/humanizer](https://github.com/blader/humanizer). diff --git a/README_JA.md b/README_JA.md index a7b2156..e9c1f20 100644 --- a/README_JA.md +++ b/README_JA.md @@ -28,83 +28,38 @@ AI っぽいテキストを **[playground](https://patina.vibetip.help/)** に ほかの例：[Before/After Gallery](docs/EXAMPLES.md)（[한국어](docs/EXAMPLES_KR.md)）· [CLI transcript](docs/DEMO.md)。 -## クイックスタート - -### ブラウザ playground +- **ブラックボックスではなく、監査可能** — 名前付きの 184 パターンがすべての編集を決め、`--diff` が何をなぜ変えたかをそのまま示します。 +- **意味は検証されて残る** — すべての書き換えは意味保全（MPS）と忠実度フロアを通過する必要があり、逸脱すれば再試行かロールバックされます。 +- **互いに独立した3つの軸** — Document Type はジャンル、Persona はボイス、Register は伝え方を担当。省略した軸は原文が保たれます。 +- **あらゆるサーフェスで** — エージェントスキル（Claude Code · Codex · Cursor · OpenCode）、Node CLI、[ブラウザ playground](https://patina.vibetip.help/)。 +- **限界に正直** — スコアは編集シグナルであり著者判定ではありません。[事前登録研究](docs/research/2026-rewrite-efficacy-study1.md)では失敗点も併せて公開しています。 -**[patina.vibetip.help](https://patina.vibetip.help/)** を開き、KO / EN / ZH / JA のテキストを貼り付けると、MPS/忠実度フロアでゲートされた実際の書き換えを、決定的な AI シグナルの before → after 付きで試せます。書き換えと採点はサーバー側で実行され、無料ティアはサービス自身のモデルキーを使います（レート制限あり）。**API モード**では、リクエストごとに自分のキーが patina サーバーを経由して選択したプロバイダーへ転送され、保存もログ記録もされません（メトリクスはサニタイズ済み：テキスト・プロンプト・出力・キー・IP を含みません）。 +## クイックスタート -### エージェントスキル +**ブラウザ — インストール不要。** **[patina.vibetip.help](https://patina.vibetip.help/)** を開いて貼り付けるだけ。書き換えと採点はサーバー側で実行され、API モードは自分のキーをリクエスト単位で転送します（保存・ログなし）。 -**コーディングエージェントにインストールさせる** — Claude Code、Codex CLI、Cursor、Gemini CLI などのエージェントに以下を貼り付けてください： +**エージェントスキル — Claude Code、Codex CLI、Cursor などに貼り付けてください：** ```text Install patina by following https://raw.githubusercontent.com/devswha/patina/main/INSTALLATION.md ``` -エージェントが [`INSTALLATION.md`](INSTALLATION.md)（AI エージェント向けに書かれています）を取得し、ホストに合ったインストール手順を実行して検証します。自分で行う場合： - -**Claude Code — プラグインマーケットプレイス（クローン不要・推奨）：** +その後： ```text -/plugin marketplace add devswha/patina -/plugin install patina@patina -``` - -**Claude Code · Codex CLI · Cursor · OpenCode — インストールスクリプト：** - -```bash -curl -fsSL https://raw.githubusercontent.com/devswha/patina/main/install.sh | bash -``` - -続いて Claude Code、Codex CLI、Cursor、OpenCode からスキルを実行します： - -```text -/patina --lang en +/patina --lang ja [ここにテキストを貼り付け] ``` -便利なスキル呼び出し： - -```text -/patina --document-type email --register professional -/patina --document-type blog --persona pragmatic-founder -``` - -### スタンドアロン CLI - -Node.js >= 18 が必要です。 - -```bash -npx patina-cli doctor -npx patina-cli --lang en input.txt -``` - -API キーなしで、ログイン済みのローカルモデル CLI を使う： +**CLI — Node 18 以上：** ```bash -printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon.' \ - | npx patina-cli --lang en --backend codex-cli +npx patina-cli --lang ja input.txt # 書き換え +npx patina-cli doctor # バックエンドとキーの確認 ``` -対応するローカルバックエンド：`codex-cli`、`claude-cli`、`gemini-cli`、`kimi-cli` — patina はバックエンドごとに、ドキュメント化された中で最も強力なデフォルトモデルを渡します。[Authentication](docs/AUTHENTICATION.md)（[한국어](docs/AUTHENTICATION_KR.md)）を参照してください。 - -大規模な `--batch` 実行には OpenAI 互換の HTTP バックエンドを推奨します。ローカル CLI バックエンドはエージェントランタイムであり、バッチ処理の安全のために `--timeout-ms`、`--max-concurrency`、`--max-retries`、`--max-failures` で保守的に上限が設定されます。 - -## できること - -| | | -|---|---| -| **184 パターン** | 各言語 37 個の書き換え可能パターン + 9 個のスコア専用 viral-hook（KO/EN/ZH/JA 各 46 個） — 完全な 184 パターンカタログは [PATTERNS.md](docs/PATTERNS.md) を参照 | -| **モード** | rewrite · verify · audit · score · diff | -| **利用形態** | agent skill · Node CLI · ページ内 preview · ブラウザ playground（rewrite + score） | -| **3つの書き換え軸** | `--document-type` はジャンル/方針 · `--persona` は再利用ボイス · `--register` は casual/professional レジスター | -| **無料利用** | ログイン済みの `codex`、`claude`、`gemini` CLI なら `PATINA_API_KEY` なしで書き換え可能 | -| **キャリブレーション** | GPT-5.5 / Claude Sonnet 4.6 / Gemini 2.5 Pro で編集ホットスポット再現率 67.3% [63.5–71.0%]（n=600、KO+EN）；KO+EN の人間文章コントロールで誤検出 16.0% [11.6–21.7%]（n=200） | -| **ライセンス** | MIT | - -スコアは誤検出と見逃しを含む編集シグナルであり、著者判定の根拠ではありません。[Ethics](docs/ETHICS.md) を参照してください。 +ログイン済みの `codex`・`claude`・`gemini` CLI があれば API キーなしで `--backend codex-cli` を使えます。詳細は [INSTALLATION.md](INSTALLATION.md)。 ## 互いに独立した3つの軸 @@ -116,93 +71,30 @@ patina は一つの軸から別の軸を推論しません。Persona と Registe | **Persona** | 再利用ボイス指紋：語彙、リズム、説明習慣 | ジャンル、パターン方針、Register、意味保全フロア | `--persona` · 設定 `persona` · Playground "Persona" | | **Register** | `casual` または `professional` の伝え方 | ジャンル、Persona の同一性、パターン方針 | `--register` · 設定 `register` · Playground "Register" | +意味保全は3軸の外側の共通フロアであり、明示した軸が省略された軸を埋めることはありません。 + ```bash patina --document-type email --register professional note.md patina --document-type blog --persona pragmatic-founder post.md -patina --document-type technical --persona technical-explainer --register casual guide.md ``` ## 主なコマンド ```bash -patina --lang [mode] [--document-type ] [--persona ] [--register ] input.txt -``` - -| コマンド | 目的 | -|---|---| -| `patina input.txt` | デフォルトで書き換え | -| `patina --audit input.txt` | パターン検出のみ | -| `patina --score input.txt` | LLM 判定と決定論的シグナルを併用して 0-100 のスコアを出力 | -| `patina --score --offline input.txt` | バックエンドや API キーを使わず、決定論的シグナルのみでスコアを計算 | -| `patina --score --offline --exit-on 30 input.txt` | `overall > 30` で終了コード `3` を返すオフライン CI ゲート | -| `patina --diff input.txt` | 変更をパターンごとに表示 | -| `patina --preview page.html` | 保存済み HTML ページ上に書き換えを反映し、トグルとインライン diff を表示 | -| `patina --verify input.txt` | 書き換え後、1 回のリトライで MPS/忠実度フロアを検査 | -| `patina --document-type email --register professional input.txt` | メールの慣習と professional レジスターを適用 | -| `patina --persona pragmatic-founder input.txt` | 組み込みボイスペルソナで書き換え | -| `patina persona new my-voice --from-sample past.txt` | 文章サンプルから自分のペルソナを作成 | -| `patina persona list` | 組み込み + カスタムペルソナを一覧表示 | -| `patina persona show my-voice --json` | Persona の正規化済みボイス設定を表示 | -| `patina persona edit my-voice --name "New Name"` | 組み込み Persona を custom shadow にコピーして編集 | -| `patina persona rm my-voice` | カスタム Persona を削除（組み込みは保護） | -| `patina --format json --quiet input.txt` | スクリプト向け出力 | -| `patina --batch docs/*.md --outdir cleaned/` | 複数ファイルの一括処理 | - -`patina --help` は全フラグ一覧を表示します。`patina doctor --json` は LLM 呼び出しなしで Node・backend・tmux・API キーの準備状況を確認します。 - -### ペルソナ（ボイス） - -**ペルソナ**は再利用できるボイスです — 組み込み（`patina persona list`）か、ソースを触らずに自作できます： - -```bash -patina persona new my-voice --from-sample past-posts.txt # learn from your writing -patina persona new my-voice --describe "plain-spoken founder, casual" -patina --persona my-voice draft.md # then reuse it -``` - -ko/en/zh/ja で `--document-type`、`--persona`、`--register` を独立して組み合わせられます。Persona v2 は再利用ボイスだけを変え、文書タイプ、レジスター、パターン方針、verification、意味フロアを定義できません。作成した Persona は保存時に検証され、グローバル rewrite guard と `--verify` が意味保全を独立して担当します。 - -## CI - -GitHub Actions では、メンテナンス済みのラッパーが手書きのセットアップよりも短く済みます： - -```yaml -name: Patina prose score -on: - pull_request: - paths: ['**/*.md', '**/*.mdx'] -permissions: - contents: read - pull-requests: read - issues: write -jobs: - patina: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 - - uses: devswha/patina-action@v1 - with: - score-threshold: 30 - lang: auto - comment: true -``` - -そのほかの連携：[pre-commit](docs/integrations/pre-commit.md)、[static sites](docs/integrations/static-sites.md)、[Docker](docs/integrations/docker.md)、[release workflow](docs/integrations/release.md)。 - -## 仕組み - -```text -Input - -> semantic anchor extraction (claims, polarity, causation, numbers) - -> stylometry + AI-lexicon scan - -> pattern-guided rewrite - -> self-audit and MPS/fidelity checks - -> cleaned text +patina input.txt # デフォルトで書き換え +patina --audit input.txt # パターン検出のみ +patina --score --offline --exit-on 30 input.txt # API キー不要の決定論的 CI ゲート +patina --diff input.txt # パターンごとの変更を表示 +patina --verify input.txt # 書き換え + MPS/忠実度フロア検査 +patina --document-type email --register professional input.txt +patina persona new my-voice --from-sample past-posts.txt # 自分の文章からボイスを学習 +patina --persona my-voice draft.md +patina --batch docs/*.md --outdir cleaned/ ``` -意味がずれた場合、その変更は再試行またはロールバックされます。決定的な解析は `src/features/*` にあり、LLM を用いる書き換えとスコア呼び出しは選択したバックエンドを使います。 +`patina --help` が全フラグを表示します。GitHub Actions ラッパー：[devswha/patina-action](https://github.com/devswha/patina-action) · [pre-commit などの統合](docs/integrations/pre-commit.md)。 -## 設定 +プロジェクト設定は `.patina.yaml` に置きます： ```yaml # .patina.default.yaml @@ -213,30 +105,25 @@ persona: # 任意。省略時は原文ボイスを保持 register: # casual | professional。省略時は原文レジスターを保持 ``` -プロジェクトの `.patina.yaml` がデフォルトを上書きします。パターンパックは言語プレフィックスで自動検出されます。追加型のリストキー（`blocklist`、`allowlist`、`skip-patterns`）はマージされ、その他の配列は置き換えられます。 - -## ドキュメント - -まずはここから： +## できること -- [Cookbook](docs/COOKBOOK.md) — 一般的なレシピとワークフロー -- [CLI Contract](docs/CLI.md) — フラグ、フォーマット、スコアゲート、終了時の挙動 -- [Authentication](docs/AUTHENTICATION.md) — ローカル CLI バックエンドと API プロバイダー -- [Patterns](docs/PATTERNS.md) — 完全なパターンカタログ -- [Subagents & strict flow](docs/agents.md) — 任意の読み取り専用 detector/fidelity/naturalness サブエージェントと `--strict` マルチパスモード -- [Benchmarks](docs/benchmarks/README.md) · [latest report](docs/benchmarks/latest.md) · [2026 rebaseline](docs/research/2026-rebaseline.md) -- [Measurement harness](docs/HARNESS.md) — すべてのベンチマーク・キャリブレーション・ゲートツールの索引（signal-impact ablation ハーネスを含む） -- [FAQ](docs/FAQ.md)（[한국어](docs/FAQ_KR.md)） -- [Ethics](docs/ETHICS.md) -- [Contributing](CONTRIBUTING.md)（[한국어](CONTRIBUTING_KR.md)） -- [Changelog](CHANGELOG.md) +| | | +|---|---| +| **184 パターン** | 各言語 37 個の書き換え可能パターン + 9 個のスコア専用 viral-hook（KO/EN/ZH/JA 各 46 個） — 完全な 184 パターンカタログは [PATTERNS.md](docs/PATTERNS.md) を参照 | +| **モード** | rewrite · verify · audit · score · diff | +| **キャリブレーション** | GPT-5.5 / Claude Sonnet 4.6 / Gemini 2.5 Pro で編集ホットスポット再現率 67.3% [63.5–71.0%]（n=600、KO+EN）；KO+EN の人間文章コントロールで誤検出 16.0% [11.6–21.7%]（n=200） | +| **ライセンス** | MIT | -ブランドアセットと利用ルールは [Branding](docs/BRANDING.md) にあります。設計メモは [DESIGN.md](DESIGN.md) にあります。 +スコアは誤検出・見逃しを含む編集シグナルであり、著者性の証明ではありません。[Ethics](docs/ETHICS.md) を参照してください。 -## 謝辞 +## ドキュメント -[oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh) のプラグインアーキテクチャ、[Wikipedia「Signs of AI writing」](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing)、[blader/humanizer](https://github.com/blader/humanizer) に着想を得ています。 +- [Cookbook](docs/COOKBOOK.md) — よく使うレシピ · [CLI 契約](docs/CLI.md) — フラグ・ゲート・終了コード +- [Before/After ギャラリー](docs/EXAMPLES.md) · [パターンカタログ](docs/PATTERNS.md) +- [アーキテクチャ](docs/ARCHITECTURE.md) · [設定と認証](docs/AUTHENTICATION.md) +- [ベンチマーク](docs/benchmarks/latest.md) · [研究](docs/research/2026-rewrite-efficacy-study1.md) · [FAQ](docs/FAQ.md) +- [コントリビュート](CONTRIBUTING.md) · [変更履歴](CHANGELOG.md) ## ライセンス -MIT。[LICENSE](LICENSE) と [NOTICE](NOTICE) を参照してください。 +MIT。[LICENSE](LICENSE) と [NOTICE](NOTICE) を参照。[oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh)、[Wikipedia の "Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing)、[blader/humanizer](https://github.com/blader/humanizer) に着想を得ています。 diff --git a/README_KR.md b/README_KR.md index 15e8160..cf0ea64 100644 --- a/README_KR.md +++ b/README_KR.md @@ -28,83 +28,38 @@ AI 티가 나는 글을 **[playground](https://patina.vibetip.help/)** 에 붙 더 많은 예시: [Before/After 갤러리](docs/EXAMPLES_KR.md) ([English](docs/EXAMPLES.md)) · [CLI transcript](docs/DEMO.md). -## 빠른 시작 - -### 브라우저 playground +- **블랙박스가 아닌, 감사 가능한 도구** — 184개의 이름 붙은 패턴이 모든 수정을 결정하고, `--diff`가 무엇이 왜 바뀌었는지 그대로 보여줍니다. +- **의미는 검증되어 살아남습니다** — 모든 재작성은 의미 보존(MPS)·충실도 하한을 통과해야 하며, 어긋나면 재시도하거나 되돌립니다. +- **서로 독립적인 세 축** — Document Type은 장르를, Persona는 목소리를, Register는 전달 방식을 정합니다. 생략한 축은 원문이 유지됩니다. +- **모든 채널에서** — 에이전트 스킬(Claude Code · Codex · Cursor · OpenCode), Node CLI, [브라우저 playground](https://patina.vibetip.help/). +- **한계에 정직하게** — 점수는 편집 신호이지 작성자 판정이 아니며, [사전 등록 연구](docs/research/2026-rewrite-efficacy-study1.md)에서 실패 지점까지 함께 공개합니다. -**[patina.vibetip.help](https://patina.vibetip.help/)** 를 열고 KO / EN / ZH / JA 문장을 붙여넣으면 MPS/충실도 하한으로 게이팅된 실제 리라이트를 받아볼 수 있고, 결정론적 AI 시그널이 before → after로 측정됩니다. 리라이트와 채점은 서버에서 실행되며, 무료 티어는 서비스 자체 모델 키를 사용합니다(요청량 제한). **API 모드**는 요청마다 개인 키를 patina 서버를 경유해 선택한 프로바이더로 전달할 뿐, 저장하거나 로깅하지 않습니다(메트릭은 텍스트·프롬프트·출력·키·IP 없이 정제됩니다). +## 빠른 시작 -### 에이전트 스킬 +**브라우저 — 설치 없음.** **[patina.vibetip.help](https://patina.vibetip.help/)** 를 열고 붙여넣으면 끝. 재작성과 채점은 서버에서 실행되고, API 모드는 개인 키를 요청 단위로만 전달합니다(저장·로깅 없음). -**코딩 에이전트에게 설치를 맡기세요** — Claude Code, Codex CLI, Cursor, Gemini CLI 등 아무 에이전트에나 아래를 붙여넣으세요: +**에이전트 스킬 — Claude Code, Codex CLI, Cursor 등 아무 에이전트에나 붙여넣으세요:** ```text Install patina by following https://raw.githubusercontent.com/devswha/patina/main/INSTALLATION.md ``` -에이전트가 [`INSTALLATION.md`](INSTALLATION.md)(AI 에이전트용으로 작성됨)를 가져와 사용 환경에 맞는 설치 경로를 실행하고 검증합니다. 직접 하려면: - -**Claude Code — 플러그인 마켓플레이스 (클론 불필요, 권장):** - -```text -/plugin marketplace add devswha/patina -/plugin install patina@patina -``` - -**Claude Code · Codex CLI · Cursor · OpenCode — 설치 스크립트:** - -```bash -curl -fsSL https://raw.githubusercontent.com/devswha/patina/main/install.sh | bash -``` - -이후 Claude Code, Codex CLI, Cursor, OpenCode에서 스킬을 실행하세요: +설치 후: ```text -/patina --lang en +/patina --lang ko -[paste your text here] -``` - -유용한 스킬 호출: - -```text -/patina --document-type email --register professional -/patina --document-type blog --persona pragmatic-founder +[여기에 글을 붙여넣으세요] ``` -### 독립형 CLI - -Node.js 18 이상이 필요합니다. - -```bash -npx patina-cli doctor -npx patina-cli --lang en input.txt -``` - -API 키 없이 로그인된 로컬 모델 CLI를 사용하려면: +**CLI — Node 18 이상:** ```bash -printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon.' \ - | npx patina-cli --lang en --backend codex-cli +npx patina-cli --lang ko input.txt # 재작성 +npx patina-cli doctor # 백엔드·키 상태 점검 ``` -지원 로컬 백엔드: `codex-cli`, `claude-cli`, `gemini-cli`, `kimi-cli` — patina는 백엔드별로 문서화된 가장 강력한 기본 모델을 넘깁니다. [Authentication](docs/AUTHENTICATION_KR.md) ([English](docs/AUTHENTICATION.md))를 참고하세요. - -대규모 `--batch` 실행에는 OpenAI 호환 HTTP 백엔드를 권장합니다. 로컬 CLI 백엔드는 에이전트 런타임이므로 배치 안전을 위해 `--timeout-ms`, `--max-concurrency`, `--max-retries`, `--max-failures`로 보수적으로 제한됩니다. - -## 한눈에 보기 - -| | | -|---|---| -| **184개 패턴** | 언어별 재작성 가능 37개 + 스코어 전용 바이럴 훅 9개(KO/EN/ZH/JA 각각 46개) — 전체 184개 패턴 카탈로그는 [PATTERNS.md](docs/PATTERNS.md) 참고 | -| **모드** | rewrite · verify · audit · score · diff | -| **사용 채널** | 에이전트 스킬 · Node CLI · 페이지 내 preview · 브라우저 playground (리라이트 + 점수) | -| **재작성 3축** | `--document-type`은 장르/정책 · `--persona`는 재사용 보이스 · `--register`는 casual/professional 전달 방식 | -| **무료 사용** | 로그인된 `codex`, `claude`, `gemini` CLI 중 하나로 `PATINA_API_KEY` 없이 재작성 실행 | -| **캘리브레이션** | GPT-5.5 / Claude Sonnet 4.6 / Gemini 2.5 Pro 기준 편집 핫스팟 catch 67.3% [63.5–71.0%] (n=600, KO+EN); KO+EN 사람 글 컨트롤에서 오탐 16.0% [11.6–21.7%] (n=200) | -| **라이선스** | MIT | - -점수는 오탐과 미탐이 있는 편집 신호이지 작성자 판정의 근거가 아닙니다. [Ethics](docs/ETHICS.md)를 참고하세요. +로그인된 `codex`·`claude`·`gemini` CLI가 있으면 API 키 없이 `--backend codex-cli`로 실행됩니다. 전체 설치 옵션: [INSTALLATION.md](INSTALLATION.md). ## 서로 독립적인 세 축 @@ -116,99 +71,30 @@ patina는 한 축에서 다른 축을 추론하지 않습니다. Persona와 Regi | **Persona** | 재사용 보이스 지문: 어휘·리듬·설명 습관 | 장르, 패턴 정책, Register, 의미 보존 하한 | `--persona` · 설정 `persona` · Playground "Persona" | | **Register** | `casual` 또는 `professional` 전달 방식 | 장르, Persona 정체성, 패턴 정책 | `--register` · 설정 `register` · Playground "Register" | -의미 보존은 세 축 바깥의 공통 하한입니다. 지시가 겹쳐 보이면 소유 필드로 -판단합니다. 문서 구조와 도메인 제약은 Document Type, 고유 어휘와 리듬은 Persona, -casual/professional 표지는 Register가 정합니다. 명시된 한 축으로 생략된 다른 축을 -추론하지 않습니다. - +의미 보존은 세 축 바깥의 공통 하한이며, 명시된 한 축이 생략된 다른 축을 채우지 않습니다. ```bash patina --document-type email --register professional note.md patina --document-type blog --persona pragmatic-founder post.md -patina --document-type technical --persona technical-explainer --register casual guide.md ``` ## 자주 쓰는 명령 ```bash -patina --lang [mode] [--document-type ] [--persona ] [--register ] input.txt -``` - -| 명령 | 목적 | -|---|---| -| `patina input.txt` | 기본값으로 재작성 | -| `patina --audit input.txt` | 패턴 탐지만 수행 | -| `patina --score input.txt` | LLM 판정과 결정론적 신호를 함께 사용해 0-100 점수 출력 | -| `patina --score --offline input.txt` | 백엔드나 API 키 없이 결정론적 신호만으로 점수 계산 | -| `patina --score --offline --exit-on 30 input.txt` | `overall > 30`이면 종료 코드 `3`을 내는 오프라인 CI 게이트 | -| `patina --diff input.txt` | 패턴별 변경 사항 표시 | -| `patina --preview page.html` | 저장된 HTML 페이지 위에 재작성을 다시 렌더링(토글 + 인라인 diff) | -| `patina --verify input.txt` | 재작성 후 MPS/충실도 하한을 검사하고 1회 재시도 | -| `patina --document-type email --register professional input.txt` | 이메일 관습과 professional 레지스터 적용 | -| `patina --persona pragmatic-founder input.txt` | 내장 보이스 페르소나로 재작성 | -| `patina persona new my-voice --from-sample past.txt` | 글 샘플에서 나만의 페르소나 제작 | -| `patina persona list` | 내장 + 커스텀 페르소나 목록 | -| `patina persona show my-voice --json` | persona의 정규화된 voice config 조회 | -| `patina persona edit my-voice --name "New Name"` | built-in은 custom shadow로 복사해 수정 | -| `patina persona rm my-voice` | custom persona 삭제(built-in은 보호) | -| `patina --format json --quiet input.txt` | 스크립트 친화적 출력 | -| `patina --batch docs/*.md --outdir cleaned/` | 배치 파일 처리 | - -`patina --help`는 전체 플래그 목록을 출력합니다. `patina doctor --json`은 LLM 호출 없이 Node, 백엔드, tmux, API 키 준비 상태를 점검합니다. - -### 페르소나 (보이스) - -**페르소나**는 재사용 가능한 "말투"입니다 — 내장 페르소나(`patina persona list`)를 쓰거나, 소스 코드를 건드리지 않고 직접 만들 수 있습니다: - -```bash -patina persona new my-voice --from-sample past-posts.txt # 내 글에서 학습 -patina persona new my-voice --describe "plain-spoken founder, casual" -patina --persona my-voice draft.md # 이후 재사용 +patina input.txt # 기본값으로 재작성 +patina --audit input.txt # 패턴 탐지만 +patina --score --offline --exit-on 30 input.txt # API 키 없는 결정론적 CI 게이트 +patina --diff input.txt # 패턴별 변경 표시 +patina --verify input.txt # 재작성 + MPS/충실도 하한 검사 +patina --document-type email --register professional input.txt +patina persona new my-voice --from-sample past-posts.txt # 내 글에서 보이스 학습 +patina --persona my-voice draft.md +patina --batch docs/*.md --outdir cleaned/ ``` -ko/en/zh/ja에서 `--document-type`/`--register`와 독립적으로 조합됩니다. Persona v2는 재사용 보이스만 바꾸며 문서 유형, 레지스터, 패턴 정책, verification/의미 하한을 정의할 수 없습니다. 제작한 Persona는 저장 시 검증되고, 전역 rewrite guard와 `--verify`가 의미 보존을 독립적으로 담당합니다. +`patina --help`가 전체 플래그를 출력합니다. GitHub Actions용 래퍼: [devswha/patina-action](https://github.com/devswha/patina-action) · [pre-commit 등 통합](docs/integrations/pre-commit.md). -## CI - -GitHub Actions에서는 손수 설정하는 것보다 유지 관리되는 래퍼가 더 간단합니다: - -```yaml -name: Patina prose score -on: - pull_request: - paths: ['**/*.md', '**/*.mdx'] -permissions: - contents: read - pull-requests: read - issues: write -jobs: - patina: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 - - uses: devswha/patina-action@v1 - with: - score-threshold: 30 - lang: auto - comment: true -``` - -기타 연동: [pre-commit](docs/integrations/pre-commit.md), [static sites](docs/integrations/static-sites.md), [Docker](docs/integrations/docker.md), [release workflow](docs/integrations/release.md). - -## 동작 원리 - -```text -Input - -> semantic anchor extraction (claims, polarity, causation, numbers) - -> stylometry + AI-lexicon scan - -> pattern-guided rewrite - -> self-audit and MPS/fidelity checks - -> cleaned text -``` - -의미가 어긋나면 해당 변경을 재시도하거나 롤백합니다. 결정론적 분석은 `src/features/*`에 있으며, LLM 기반 재작성과 점수 호출은 선택한 백엔드를 사용합니다. - -## 설정 +프로젝트 설정은 `.patina.yaml`에 둡니다: ```yaml # .patina.default.yaml @@ -219,30 +105,25 @@ persona: # 선택 사항; 생략하면 원문 보이스 보존 register: # casual | professional; 생략하면 원문 레지스터 보존 ``` -프로젝트의 `.patina.yaml`이 기본값을 오버라이드합니다. 패턴 팩은 언어 접두사로 자동 탐색됩니다. 추가형 목록 키(`blocklist`, `allowlist`, `skip-patterns`)는 병합되고, 다른 배열은 대체됩니다. - -## 문서 - -여기서 시작하세요: +## 한눈에 보기 -- [Cookbook](docs/COOKBOOK.md) — 자주 쓰는 recipe와 워크플로우 -- [CLI Contract](docs/CLI.md) — 플래그, 포맷, score gate, 종료 동작 -- [Authentication](docs/AUTHENTICATION_KR.md) ([English](docs/AUTHENTICATION.md)) — 로컬 CLI 백엔드와 API 프로바이더 -- [Patterns](docs/PATTERNS.md) — 전체 패턴 카탈로그 -- [Subagents & strict flow](docs/agents.md) — 선택형 read-only detector/fidelity/naturalness 서브에이전트와 `--strict` 멀티패스 모드 -- [Benchmarks](docs/benchmarks/README.md) · [latest report](docs/benchmarks/latest.md) · [2026 rebaseline](docs/research/2026-rebaseline.md) -- [Measurement harness](docs/HARNESS.md) — 모든 벤치마크·보정·게이트 도구의 인덱스(신호 임팩트 ablation 하네스 포함) -- [FAQ](docs/FAQ_KR.md) ([English](docs/FAQ.md)) -- [Ethics](docs/ETHICS.md) -- [Contributing](CONTRIBUTING_KR.md) ([English](CONTRIBUTING.md)) -- [Changelog](CHANGELOG.md) +| | | +|---|---| +| **184개 패턴** | 언어별 재작성 가능 37개 + 스코어 전용 바이럴 훅 9개(KO/EN/ZH/JA 각각 46개) — 전체 184개 패턴 카탈로그는 [PATTERNS.md](docs/PATTERNS.md) 참고 | +| **모드** | rewrite · verify · audit · score · diff | +| **캘리브레이션** | GPT-5.5 / Claude Sonnet 4.6 / Gemini 2.5 Pro 기준 편집 핫스팟 catch 67.3% [63.5–71.0%] (n=600, KO+EN); KO+EN 사람 글 컨트롤에서 오탐 16.0% [11.6–21.7%] (n=200) | +| **라이선스** | MIT | -브랜드 리소스와 사용 규칙은 [Branding](docs/BRANDING.md)에 있습니다. 디자인 메모는 [DESIGN.md](DESIGN.md)에 있습니다. +점수는 오탐과 미탐이 있는 편집 신호이지 작성자 판정의 근거가 아닙니다. [Ethics](docs/ETHICS.md)를 참고하세요. -## 영감 +## 문서 -[oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh)의 플러그인 아키텍처, [Wikipedia의 "Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), [blader/humanizer](https://github.com/blader/humanizer)에서 영감을 받았습니다. +- [Cookbook](docs/COOKBOOK.md) — 자주 쓰는 레시피 · [CLI 계약](docs/CLI.md) — 플래그·게이트·종료 코드 +- [Before/After 갤러리](docs/EXAMPLES_KR.md) ([English](docs/EXAMPLES.md)) · [패턴 카탈로그](docs/PATTERNS.md) +- [아키텍처](docs/ARCHITECTURE.md) · [설정과 인증](docs/AUTHENTICATION_KR.md) ([English](docs/AUTHENTICATION.md)) +- [벤치마크](docs/benchmarks/latest.md) · [연구](docs/research/2026-rewrite-efficacy-study1.md) · [FAQ](docs/FAQ_KR.md) ([English](docs/FAQ.md)) +- [기여 가이드](CONTRIBUTING_KR.md) ([English](CONTRIBUTING.md)) · [체인지로그](CHANGELOG.md) ## 라이선스 -MIT. [LICENSE](LICENSE)와 [NOTICE](NOTICE)를 참고하세요. +MIT. [LICENSE](LICENSE)와 [NOTICE](NOTICE)를 참고하세요. [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh), [Wikipedia의 "Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), [blader/humanizer](https://github.com/blader/humanizer)에서 영감을 받았습니다. diff --git a/README_ZH.md b/README_ZH.md index 9f7fe1b..f3ca08a 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -30,83 +30,38 @@ patina 是一个面向韩文、英文、中文和日文的确定性、基于模 更多例子：[Before/After Gallery](docs/EXAMPLES.md)（[한국어](docs/EXAMPLES_KR.md)） · [CLI transcript](docs/DEMO.md)。 -## 快速开始 - -### 浏览器 playground +- **可审计，不是黑箱** — 184 条有名字的模式驱动每一次修改；`--diff` 展示改了什么、为什么改。 +- **含义经过验证地保留** — 每次改写都要通过含义保留（MPS）与忠实度下限；漂移的改写会重试或回滚。 +- **三个相互独立的轴** — Document Type 管体裁，Persona 管声音，Register 管语域；省略的轴保持原文。 +- **全渠道可用** — 代理技能（Claude Code · Codex · Cursor · OpenCode）、Node CLI，以及[浏览器 playground](https://patina.vibetip.help/)。 +- **对局限诚实** — 分数是编辑信号而非作者判定；我们的[预注册研究](docs/research/2026-rewrite-efficacy-study1.md)把失败之处与成功一并公开。 -打开 **[patina.vibetip.help](https://patina.vibetip.help/)** —— 粘贴 KO / EN / ZH / JA 文本，即可获得由 MPS/忠实度下限把关的真实改写，并附带确定性 AI 信号的 before → after 测量。改写与评分在服务器端执行；免费层使用服务自己的模型 key（有速率限制）。**API 模式**会把你自己的 key 按请求经由 patina 服务器转发给你选择的 provider —— 从不存储、也不记录（指标已脱敏：不含文本、prompt、输出、key 或 IP）。 +## 快速开始 -### Agent skill +**浏览器 — 无需安装。** 打开 **[patina.vibetip.help](https://patina.vibetip.help/)** 粘贴文本即可。改写与评分在服务端运行；API 模式按请求转发你自己的密钥（不存储、不记录）。 -**让你的编码代理来安装** —— 把下面这行粘贴到 Claude Code、Codex CLI、Cursor、Gemini CLI 或任意代理： +**代理技能 — 把下面这行粘贴给 Claude Code、Codex CLI、Cursor 等任意代理：** ```text Install patina by following https://raw.githubusercontent.com/devswha/patina/main/INSTALLATION.md ``` -代理会获取 [`INSTALLATION.md`](INSTALLATION.md)（面向 AI 代理编写），按你的宿主环境执行相应安装路径，然后验证。或者自己来： - -**Claude Code — 插件市场（无需克隆，推荐）：** - -```text -/plugin marketplace add devswha/patina -/plugin install patina@patina -``` - -**Claude Code · Codex CLI · Cursor · OpenCode — 安装脚本：** - -```bash -curl -fsSL https://raw.githubusercontent.com/devswha/patina/main/install.sh | bash -``` - -然后在 Claude Code、Codex CLI、Cursor 或 OpenCode 中运行 skill： - -```text -/patina --lang en - -[paste your text here] -``` - -常用 skill 调用： +然后使用： ```text -/patina --document-type email --register professional -/patina --document-type blog --persona pragmatic-founder -``` - -### 独立 CLI +/patina --lang zh -需要 Node.js >= 18。 - -```bash -npx patina-cli doctor -npx patina-cli --lang en input.txt +[在这里粘贴文本] ``` -使用已登录的本地模型 CLI，无需 API 密钥： +**CLI — Node 18 及以上：** ```bash -printf '%s\n' 'Coffee has emerged as a pivotal cultural phenomenon.' \ - | npx patina-cli --lang en --backend codex-cli +npx patina-cli --lang zh input.txt # 改写 +npx patina-cli doctor # 检查后端与密钥 ``` -支持的本地后端：`codex-cli`、`claude-cli`、`gemini-cli`、`kimi-cli` —— patina 会按每个后端传入其文档记载的最强默认模型。见 [Authentication](docs/AUTHENTICATION.md)（[한국어](docs/AUTHENTICATION_KR.md)）。 - -对于较大的 `--batch` 运行，建议使用兼容 OpenAI 的 HTTP 后端；本地 CLI 后端是代理运行时，会通过 `--timeout-ms`、`--max-concurrency`、`--max-retries` 和 `--max-failures` 保守设限以保证批处理安全。 - -## 一览 - -| | | -|---|---| -| **184 条模式** | 每种语言 37 条可改写模式 + 9 条仅评分的病毒式钩子模式（KO/EN/ZH/JA 各 46 条）—— 完整的 184 条模式目录见 [PATTERNS.md](docs/PATTERNS.md) | -| **模式** | rewrite · verify · audit · score · diff | -| **使用入口** | agent skill · Node CLI · 页面内 preview · 浏览器 playground（改写 + 评分） | -| **三个改写轴** | `--document-type` 控制体裁/策略 · `--persona` 控制可复用声音 · `--register` 控制 casual/professional 语域 | -| **免费使用** | 已登录的 `codex`、`claude` 或 `gemini` CLI 可直接运行改写，无需 `PATINA_API_KEY` | -| **校准** | 编辑热点命中率 67.3% [63.5–71.0%]，跨 GPT-5.5 / Claude Sonnet 4.6 / Gemini 2.5 Pro（n=600，KO+EN）；在 KO+EN 人类对照上误检率 16.0% [11.6–21.7%]（n=200） | -| **许可证** | MIT | - -分数是有误报和漏报的编辑信号，不是作者身份的证明。见 [Ethics](docs/ETHICS.md)。 +已登录的 `codex`、`claude` 或 `gemini` CLI 无需 API 密钥：加 `--backend codex-cli`。完整安装选项见 [INSTALLATION.md](INSTALLATION.md)。 ## 三个相互独立的轴 @@ -118,93 +73,30 @@ patina 不会从一个轴推断另一个轴。省略 Persona 和 Register 时， | **Persona** | 可复用声音指纹：词汇、节奏、解释习惯 | 体裁、模式策略、Register、含义保留下限 | `--persona` · 配置 `persona` · Playground "Persona" | | **Register** | `casual` 或 `professional` 表达方式 | 体裁、Persona 身份、模式策略 | `--register` · 配置 `register` · Playground "Register" | +含义保留是三轴之外的共同下限；显式指定的轴不会填充被省略的轴。 + ```bash patina --document-type email --register professional note.md patina --document-type blog --persona pragmatic-founder post.md -patina --document-type technical --persona technical-explainer --register casual guide.md ``` ## 常用命令 ```bash -patina --lang [mode] [--document-type ] [--persona ] [--register ] input.txt -``` - -| 命令 | 用途 | -|---|---| -| `patina input.txt` | 用默认设置改写 | -| `patina --audit input.txt` | 仅检测模式 | -| `patina --score input.txt` | 结合 LLM 评判与确定性信号输出 0-100 分 | -| `patina --score --offline input.txt` | 无需后端或 API key，仅使用确定性信号评分 | -| `patina --score --offline --exit-on 30 input.txt` | 离线 CI gate：当 `overall > 30` 时以退出码 `3` 结束 | -| `patina --diff input.txt` | 按模式逐项展示改动 | -| `patina --preview page.html` | 把改写结果渲染回保存的 HTML 页面，带视图切换和内联 diff | -| `patina --verify input.txt` | 改写后检查 MPS/忠实度下限，并重试一次 | -| `patina --document-type email --register professional input.txt` | 使用邮件惯例和 professional 语域 | -| `patina --persona pragmatic-founder input.txt` | 用内置声音人格改写 | -| `patina persona new my-voice --from-sample past.txt` | 从写作样本创建你自己的人格 | -| `patina persona list` | 列出内置 + 自制人格 | -| `patina persona show my-voice --json` | 查看人格的规范化声音配置 | -| `patina persona edit my-voice --name "New Name"` | 将内置人格复制为 custom shadow 后编辑 | -| `patina persona rm my-voice` | 删除自制人格（内置人格受保护） | -| `patina --format json --quiet input.txt` | 适合脚本的输出 | -| `patina --batch docs/*.md --outdir cleaned/` | 批量文件处理 | - -`patina --help` 会打印完整的选项列表。`patina doctor --json` 会在不调用 LLM 的情况下检查 Node、后端、tmux 和 API-key 就绪状态。 - -### 人格（声音） - -**人格**是可复用的“声音” —— 一个内置人格（`patina persona list`）或你自己创建的、无需改动源码的人格： - -```bash -patina persona new my-voice --from-sample past-posts.txt # 从你的写作中学习 -patina persona new my-voice --describe "plain-spoken founder, casual" -patina --persona my-voice draft.md # 之后复用 -``` - -可在 ko/en/zh/ja 上独立组合 `--document-type`、`--persona` 与 `--register`。Persona v2 只改变可复用声音，不能定义文档类型、语域、模式策略、verification 或含义下限。自制 Persona 会在保存时校验；全局 rewrite guard 和 `--verify` 独立负责含义保留。 - -## CI - -对于 GitHub Actions，官方维护的 wrapper 比手写配置更简短： - -```yaml -name: Patina prose score -on: - pull_request: - paths: ['**/*.md', '**/*.mdx'] -permissions: - contents: read - pull-requests: read - issues: write -jobs: - patina: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 - - uses: devswha/patina-action@v1 - with: - score-threshold: 30 - lang: auto - comment: true -``` - -其他集成：[pre-commit](docs/integrations/pre-commit.md)、[静态站点](docs/integrations/static-sites.md)、[Docker](docs/integrations/docker.md)、[release workflow](docs/integrations/release.md)。 - -## 工作原理 - -```text -Input - -> semantic anchor extraction (claims, polarity, causation, numbers) - -> stylometry + AI-lexicon scan - -> pattern-guided rewrite - -> self-audit and MPS/fidelity checks - -> cleaned text +patina input.txt # 按默认设置改写 +patina --audit input.txt # 仅检测模式 +patina --score --offline --exit-on 30 input.txt # 无需 API 密钥的确定性 CI 门槛 +patina --diff input.txt # 逐模式展示改动 +patina --verify input.txt # 改写 + MPS/忠实度下限检查 +patina --document-type email --register professional input.txt +patina persona new my-voice --from-sample past-posts.txt # 从自己的文字学习声音 +patina --persona my-voice draft.md +patina --batch docs/*.md --outdir cleaned/ ``` -如果含义发生偏移，改动会被重试或回滚。确定性分析位于 `src/features/*`；由 LLM 支撑的改写与评分调用则使用所选后端。 +`patina --help` 打印完整参数。GitHub Actions 包装器：[devswha/patina-action](https://github.com/devswha/patina-action) · [pre-commit 等集成](docs/integrations/pre-commit.md)。 -## 配置 +项目配置放在 `.patina.yaml`： ```yaml # .patina.default.yaml @@ -215,30 +107,25 @@ persona: # 可选；省略时保留原文声音 register: # casual | professional；省略时保留原文语域 ``` -项目级 `.patina.yaml` 会覆盖默认值。模式包按语言前缀自动发现。可追加的列表键（`blocklist`、`allowlist`、`skip-patterns`）会合并；其他数组会直接替换。 - -## 文档 - -从这里开始： +## 一览 -- [Cookbook](docs/COOKBOOK.md) —— 常用配方与工作流 -- [CLI Contract](docs/CLI.md) —— 选项、格式、score gate 和退出行为 -- [Authentication](docs/AUTHENTICATION.md) —— 本地 CLI 后端与 API 服务商 -- [Patterns](docs/PATTERNS.md) —— 完整模式目录 -- [Subagents & strict flow](docs/agents.md) —— 可选的只读 detector/fidelity/naturalness 子代理，以及 `--strict` 多轮模式 -- [Benchmarks](docs/benchmarks/README.md) · [latest report](docs/benchmarks/latest.md) · [2026 rebaseline](docs/research/2026-rebaseline.md) -- [Measurement harness](docs/HARNESS.md) —— 每个基准、校准和 gate 工具的索引（含信号影响 ablation harness） -- [FAQ](docs/FAQ.md)（[한국어](docs/FAQ_KR.md)） -- [Ethics](docs/ETHICS.md) -- [Contributing](CONTRIBUTING.md)（[한국어](CONTRIBUTING_KR.md)） -- [Changelog](CHANGELOG.md) +| | | +|---|---| +| **184 条模式** | 每种语言 37 条可改写模式 + 9 条仅评分的病毒式钩子模式（KO/EN/ZH/JA 各 46 条）—— 完整的 184 条模式目录见 [PATTERNS.md](docs/PATTERNS.md) | +| **模式** | rewrite · verify · audit · score · diff | +| **校准** | 编辑热点命中率 67.3% [63.5–71.0%]，跨 GPT-5.5 / Claude Sonnet 4.6 / Gemini 2.5 Pro（n=600，KO+EN）；在 KO+EN 人类对照上误检率 16.0% [11.6–21.7%]（n=200） | +| **许可证** | MIT | -品牌资源和使用规则见 [Branding](docs/BRANDING.md)。设计说明见 [DESIGN.md](DESIGN.md)。 +分数是带有误检与漏检的编辑信号，不是作者身份的证明。见 [Ethics](docs/ETHICS.md)。 -## 致谢 +## 文档 -灵感来自 [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh) 的插件架构、[Wikipedia 的 “Signs of AI writing”](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) 和 [blader/humanizer](https://github.com/blader/humanizer)。 +- [Cookbook](docs/COOKBOOK.md) — 常用配方 · [CLI 契约](docs/CLI.md) — 参数、门槛、退出码 +- [Before/After 画廊](docs/EXAMPLES.md) · [模式目录](docs/PATTERNS.md) +- [架构](docs/ARCHITECTURE.md) · [配置与认证](docs/AUTHENTICATION.md) +- [基准](docs/benchmarks/latest.md) · [研究](docs/research/2026-rewrite-efficacy-study1.md) · [FAQ](docs/FAQ.md) +- [贡献指南](CONTRIBUTING.md) · [变更日志](CHANGELOG.md) ## 许可证 -MIT。见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。 +MIT。见 [LICENSE](LICENSE) 与 [NOTICE](NOTICE)。灵感来自 [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh)、[Wikipedia 的 "Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) 与 [blader/humanizer](https://github.com/blader/humanizer)。