docs(compression): document the output-style catalog and its extension point (#10649)

The five output styles (terse-prose, less-code, ponytail, i-have-adhd,
terse-cjk) shipped in Phase 4 but COMPRESSION_GUIDE.md had zero mention of
them. Add the catalog table with per-style language coverage, the injection
contract (catalog order, single marker, shared boundaries once), the config
shape and back-compat note, plus an 'Adding an Output Style' recipe in
EXTENDING_COMPRESSION.md covering the matrix guard and translation floor.

Refs #10426

Co-authored-by: Xiangzhe <bakryun0718@proton.me>
This commit is contained in:
Diego Rodrigues de Sa e Souza
2026-08-18 06:14:20 -03:00
committed by GitHub
parent 8ba25e9318
commit ea0cdc559c
2 changed files with 88 additions and 0 deletions

View File

@@ -446,6 +446,60 @@ Caveman output mode is **opt-in** — set it via the combo config:
}
```
### Output Styles (catalog)
Caveman output mode above is the **legacy single-style path**. Phase 4 generalized it
into a catalog of composable output styles: `OUTPUT_STYLE_CATALOG` in
`open-sse/services/compression/outputStyles/catalog.ts`. Each style is a system-prompt
instruction that makes the model itself produce cheaper output; styles can be enabled
together and are injected in catalog order.
| Style | `id` | What it does | Instruction languages |
| --- | --- | --- | --- |
| Terse prose | `terse-prose` | Drop filler/articles/hedging; keep technical substance exact. Same text as the legacy caveman output mode (referenced, not re-typed). | en, pt-BR, ja, id |
| Less code | `less-code` | YAGNI ladder: smallest working change, no unrequested abstractions. | en only (backlog: [#10426](https://github.com/diegosouzapw/OmniRoute/issues/10426)) |
| Ponytail (lazy senior dev) | `ponytail` | "The best code is the code never written": reuse > rewrite, root cause > symptom, shortest working diff. | en, pt-BR, vi, ja, id |
| I have ADHD (action-first) | `i-have-adhd` | Action first (command/path/snippet before prose), numbered bounded steps, ONE concrete next step, no preamble/recap/closers. Adapted from [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd) (MIT). | en, pt-BR, vi, ja, id |
| Terse CJK (文言) | `terse-cjk` | Classical-Chinese ultra-terse style. | zh (locale-gated: only offered when the detected language is `zh`) |
Every style ships three intensity levels — `lite`, `full`, `ultra` — and every level
ends with the shared boundaries clause, which keeps code blocks, file paths, commands,
error strings, URLs and identifiers verbatim.
#### How injection works
`applyOutputStyles()` (`open-sse/services/compression/outputStyles/apply.ts`) resolves
the selection against the catalog (unknown ids and locale-mismatched styles are
dropped, never an error), concatenates the selected instructions in catalog order,
appends the boundaries clause **once**, and front-loads the result into the system
prompt behind a single idempotency marker (`[OmniRoute Output Styles]`) — re-applying
is a no-op. When the detected request language has a translation, the localized
instruction is injected instead of English.
#### How to enable
In the dashboard: **Context → Settings → Compression** — one row per style with an
on/off toggle and a level selector. Programmatically, the compression config persists
the selection as:
```json
{
"outputStyles": [
{ "id": "i-have-adhd", "level": "full" },
{ "id": "less-code", "level": "lite" }
]
}
```
Back-compat: the legacy `outputMode: "caveman"` combo setting still works and maps to
`terse-prose`, byte-identical to the old injection in all four legacy languages.
The style × language matrix is pinned by
`tests/unit/compression/output-styles-i18n-matrix.test.ts`: a new style cannot ship
without at least a pt-BR translation (or an explicit tracked exception), and an
existing style cannot silently lose a locale. To add a style, see
[EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md#adding-an-output-style).
### Tool Result Compression
The `toolResultCompressor.ts` module provides **5 specialized compression strategies**