内容
# Pretexter
**一款全能的 Claude Code 插件，使代理专家于 [`@chenglou/pretext`](https://github.com/chenglou/pretext)** — 一个用于快速、准确、多语言的**文本测量和布局，无需 DOM 重排**（换行、段落高度、行数、收缩宽度、丰富的内联流；渲染到 DOM、Canvas、SVG 和服务器端）的库。
Pretexter 为您的代理提供了知识和工具，以按需生成**惊艳、流畅、技术正确的排版**：中心辐射技能、斜杠命令、多代理工作流、精选的离线参考和捆绑的 MCP 服务器，其他工具可以连接到它。
> Pretexter 是关于 pretext 的**工具**。它不分叉或修改库。真正的 pretext 源代码，不做任何修改，位于 [`reference/`](reference/PROVENANCE.md)。
## 为什么我创建了这个
AI 编程代理是优秀的通才，但却是**浅度专家**。他们听说过大多数库，但并不了解它们——就像真正阅读过文档的人一样。他们猜测 API，跳过陷阱，编写可以运行但不太正确的代码。
所以我选择了一个小巧、美丽、专注的库—— [`@chenglou/pretext`](https://github.com/chenglou/pretext)，它在无需浏览器缓慢的情况下测量和布局文本——并提出了一个简单的问题：**要使代理真正成为该领域的专家，需要什么？** 不是“听说过”，而是“直接使用正确的 API，避免陷阱，生成真正看起来不错的排版”。
这个仓库是我找到的答案。它最初是一个有趣的实验，最终成长为一个完整的小工具包：代理自动使用的技能、精选的配方、一个可以捕获经典错误的检查器、多代理工作流和一个可以启动**真正浏览器**来检查其自身工作的 MCP 服务器。我试图保持诚实——所有内容都针对真实源代码进行了验证，**零发明 API**。
所以，这主要是**一个有趣的实验**：一个关于如果你真的尝试的话，可以将代理在某个狭窄领域内的专业知识推到多深的研究。但它也确实很有用。如果你构建了带有文本的网页，这里提供的配方和工具是真实的，而且它们有效。
如果有一人因为这个而交付了一些更漂亮的东西，那么它就值得了。**我希望你能从中得到一些用处。 :)**
*— [New1Direction](https://github.com/New1Direction) · 在 [Claude Code](https://claude.com/claude-code) 的帮助下构建。*
## 看看它的实际效果
无需安装 - 只需在浏览器中打开这些：
- **[`index.html`](index.html)** — 登陆页面（从这里开始）
- **[`demo/showcase.html`](demo/showcase.html)** — 一个**有/无 pretext** 的实时演示：翻转一个开关，观察 7 个示例的变化。拖动示例 07 中的照片，实时查看文本如何环绕它。
- 三个解释器： **[工具包解释](pretexter-explained.html)** · **[渲染 · 形状 · 查看](pretexter-capabilities.html)** · **[完整游览](pretexter-toolkit.html)**
## 内部结构
```
pretexter/
├── knowledge/ ← 真相的单一来源：api.md, pitfalls.json/.md, typography.md, 15 个配方
├── reference/ ← 精心策划的、未修改的 pretext 源代码 + 演示 + 文档（离线基本事实）
├── lib/ ← 纯粹、经过测试的工具包：placeRuns · layoutBox · render · cssSync · fontFallback · balance · cssBridge
├── skills/ ← pretext（中心）+ 8 个辐条：measure · manual-layout · rich-inline · typography · i18n · render · shaping · css
├── commands/ ← /pretext-new · /pretext-review · /pretext-demo · /pretext-explain
├── agents/ ← pretext-reviewer 子代理
├── workflows/ ← pretext-build · pretext-audit（多代理编排）
└── mcp/ ← 捆绑的 MCP 服务器（知识 + 配方 + 检查器；第 2 阶段布局/字形指标/预览）
```
**知识层是规范的**：技能引用它，MCP 服务器提供它，检查器强制执行它 - 因此它们永远不会漂移。工具包中的每个代码片段都只使用真实的 pretext 导出，并针对 `reference/src` 进行验证。
## 安装
**开发/最快（加载会话）：**
```sh
claude --plugin-dir /Users/clubpenguin/Documents/pretexter
```
编辑后使用 `/reload-plugins`。使用 `claude plugin validate /Users/clubpenguin/Documents/pretexter` 验证。
**持久（设置）：** 添加到 `~/.claude/settings.json`（或项目 `.claude/settings.json`）：
```jsonc
{ "enabledPlugins": ["pretexter@local"],
"extraKnownMarketplaces": { "local": { "source": { "source": "github", "repo": "you/pretexter" } } } }
```
（或推送到 Git 仓库并 `/plugin marketplace add` + `/plugin install pretexter@…`。）
安装插件会自动发现技能、命令和代理，**并自动连接 MCP 服务器**（通过 `.claude-plugin/plugin.json`，使用 `${CLAUDE_PLUGIN_ROOT}` 使其在插件缓存中解析）。
## 技能（自动触发）
| 技能 | 使用场景 |
|---|---|
| **pretext**（中心） | 任何文本测量/换行/布局问题 - 路由到正确的辐条 + 配方 |
| **pretext-measure** | 需要高度/行数而无需 DOM 重排：虚拟化、溢出保护、 masonry 高度、布局偏移预防 |
| **pretext-manual-layout** | 自己布局行：Canvas/SVG 渲染、浮动感知流、收缩包装、光标 |
| **pretext-rich-inline** | 混合字体内联流，带有原子芯片/提及、代码片段、边界空白折叠 |
| **pretext-typography** | 使其**美丽**：平衡的段落、 justification、垂直节奏、 masonry、编辑组成、排版艺术 |
| **pretext-i18n** | RTL/bidi、CJK `keep-all`、SE-Asian 脚本、软连字符、区域设置 |
| **pretext-render** | 轻松的高级布局框（文本 + 框 + 对齐 → 定位运行）和渲染到 DOM / SVG / Canvas / WebGL，加上垂直/CJK 编写模式 |
| **pretext-shaping** | 每 glyph /每集群指标（Canvas TextMetrics，DOM Range）和真正的 glyph 形状（HarfBuzz / fontkit） |
| **pretext-css** | CSS 协同作用：同步到 `getComputedStyle`，使用 `@font-face` 回退指标消除布局偏移（CLS），无上限 `text-wrap: balance`/`pretty`，适合框 `clamp()`，内在尺寸，行距，CSS 自定义属性 |
## 命令
- `/pretext-new [描述组件] [react|canvas|svg|server]` — 搭建一个正确、精致的 pretext 组件。
- `/pretext-review [文件或代码]` — 审核现有的 pretext 用法是否符合 11 个陷阱 + 排版。
- `/pretext-demo [效果] [react|canvas|svg]` — 在上游 house 样式中生成一个精致的演示。
- `/pretext-explain [布局需求]` — “我应该使用哪个 API/方法？”带有验证的草图。
## 工作流（多代理）
插件无法自动注册工作流，因此请使用工作流工具显式运行它们（或复制到 `.claude/workflows/`）：
```js
// 设计 → 实现 → 4 镜头审查 → 验证一个精致的功能
Workflow({ scriptPath: "/Users/clubpenguin/Documents/pretexter/workflows/pretext-build.js",
args: { task: "一个随文本收缩的聊天气泡", target: "react",
root: "/Users/clubpenguin/Documents/pretexter" } })
// 在代码库中找到每个 pretext 用法，检查陷阱，进行对抗性验证
Workflow({ scriptPath: "/Users/clubpenguin/Documents/pretexter/workflows/pretext-audit.js",
args: { target: "/path/to/your/src", root: "/Users/clubpenguin/Documents/pretexter" } })
```
## MCP 服务器
一个捆绑的 stdio MCP 服务器，为任何连接的代理提供规范知识。**第 1 阶段（已发货）**无需浏览器，可以在任何地方运行：
| 工具 | 功能 |
|---|---|
| `pretext_api_reference` | 验证的 API（可选，按查询过滤） |
| `pretext_recipe` | 一个经过验证的任务配方（23 个可用） |
| `pretext_pitfalls` | 陷阱目录（可选过滤） |
| `pretext_lint` | pretext 代码的静态检查，针对 11 个陷阱 - 行号 + 修复，从不执行 |
| `pretext_catalog` | 列出工具、配方、陷阱、资源 |
| `pretext_layout_run` | **第 2 阶段（受控）**：真正的 `{height, lineCount, lines, maxLineWidth}` 通过无头 Chromium - 基本事实数字 |
| `pretext_glyph_metrics` | **第 2 阶段（受控）**：Canvas TextMetrics + 每字形推进 + DOM Range 框 + 可选 HarfBuzz 字形形状 |
| `pretext_render_preview` | **第 2 阶段（受控）**：在真正的 Chromium 中布局 + 渲染文本，并返回一个 **PNG** 你可以看到 |
| `pretext_font_fallback` | **第 2 阶段（受控）**：在真正的 Chromium 中测量网页字体 + 回退 → 发出零 CLS `@font-face` `size-adjust`/`ascent-override` CSS |
资源：`pretext://api`, `pretext://pitfalls`, `pretext://typography`, `pretext://recipes/<name>`.
**连接：**
- **Claude Code（带有插件）：** 自动 - 启用插件会注册它。
- **Claude Code（独立）：**
```sh
claude mcp add pretext -e PRETEXT_KNOWLEDGE_DIR=/Users/clubpenguin/Documents/pretexter/knowledge \
-- node /Users/clubpenguin/Documents/pretexter/mcp/dist/server.js
```
- **Cursor / 其他 stdio 客户端** (`mcp.json`)：
```json
{ "mcpServers": { "pretext": {
"command": "node",
"args": ["/Users/clubpenguin/Documents/pretexter/mcp/dist/server.js"],
"env": { "PRETEXT_KNOWLEDGE_DIR": "/Users/clubpenguin/Documents/pretexter/knowledge" } } } }
```
服务器作为单个自包含的 `mcp/dist/server.js`（所有依赖项都已捆绑）发货 - **零安装，纯 `node`**。参见 [`mcp/README.md`](mcp/README.md) 了解第 2 阶段。
## 开发
```sh
node scripts/check.mjs # 仓库不变式：0 个发明的 API，链接解析，中心路由，陷阱有效
bun test lib/ # 纯布局工具包（place-runs, balance, css-sync, knuth-plass, …）
cd mcp
bun install # 开发专用 - 第 1 阶段运行时不需要（捆绑包是自包含的）
bun test # 检查器 + 第 2 阶段禁用路径测试（无浏览器）
bun run build # 重建 dist/pretext-browser.js + dist/server.js
bun run scripts/smoke.ts # 在纯 node 下进行端到端 MCP 烟雾测试
# 启用第 2 阶段（通过 pretext_layout_run 进行真正的无头 Chromium 布局）：
bun add playwright && bunx playwright install chromium
bun run test:layout # PRETEXT_ENABLE_LAYOUT=1 - 在 Chromium 中进行真正的布局
```
当您更改 pretext 知识时，**请一次编辑 `knowledge/`** - 技能和 MCP 都读取它（参见 [`AGENTS.md`](AGENTS.md)）。
## 致谢与许可
基于 Cheng Lou 的 [`@chenglou/pretext`](https://github.com/chenglou/pretext) - 对一个令人愉快构建的库表示巨大的感谢。参考快照及其出处位于 [`reference/`](reference/PROVENANCE.md)。
该工具包是 **MIT 许可**的 - 拿走它，fork 它，从中学习，用它构建一些东西。没有
字符串。如果你制作了很酷的东西，我很乐意听到它。
感谢您的访问。去创造一些漂亮的文字。✦
