Font Split

English | API 参考 | English API | 行为说明

AI 生成代码声明

本项目由 AI 编程助理生成并持续维护。作者不对代码做任何保证，也不承担任何使用责任。代码按“原样”提供，不附带任何形式的担保。

[!NOTE] 项目状态：已正式发布 1.0.0。

稳定 MCP 工具、默认值、文档化错误类型和稳定响应字段现在作为兼容性契约维护。诊断字段仍可能增加或变得更精确；实验字段不属于稳定契约。使用或集成时请以当前仓库代码、实时 MCP schema、get_agent_guidance 返回值、API 文档和 release notes 为准。

---

一个 MCP (Model Context Protocol) 服务器，将 cn-font-split 封装为可由 AI agent 调用的字体分割、批量处理、目录整理和输出审计工具。

[!WARNING] 使用前请先阅读：工具完整行为说明（含高风险 / 非直觉行为）。README 只保留入口、常见工作流和关键风险；字段级细节以 API 参考 为准。

文档导航

你要解决的问题	建议先看
快速了解项目、安装和常见调用方式	当前 README
查 MCP 工具参数、返回字段和字段语义	API 参考；英文版见 API Reference
判断批量去重、目录整理、fallback、输出审计等高风险行为	工具完整行为说明
让 AI agent 选择下一步工具和安全参数	先调用 get_agent_guidance，再检查 inspectFields 和 successCriteria
维护项目、理解结构并验证改动	维护者结构指南；npm run check:compact；涉及行为时再跑 npm run smoke:real-corpus-suite -- <字体语料目录>

目录结构不匹配速查

如果字体来自多个网站、压缩包解包目录、vendor dump 或混合根目录，先不要直接写入批量输出。推荐顺序是：

1. 用 inspect_font_inputs 只读预检目录。
2. 查看 inputDirectoryDecision.directoryOrganizationSafety 和 sourceLayoutMismatchSummary。
3. 如果需要整理，先调用 organize_font_directory + workflowPreset: "safe-preview"。
4. 只有审查计划后才使用 reviewed-write；它仍然只是 copy-only 写入 outputDir，不会移动、删除或重写源字体。
5. 对整理后的暂存目录重新执行 inspect_font_inputs，再进入 split_font_batch safe-preview 和最终输出审计。

非直觉点：organize_font_directory 的输出是“整理后的源目录暂存”，不是最终 web-font 拆分结果；最终结果仍必须由 split_font_batch 写出，并用 inspect_split_output 审计目录结构。 如果这个暂存目录里有 font-organization-manifest.json，inspect_split_output 会把它识别为 organized-font-source-staging，这时它仍然是暂存目录，不是最终拆分输出。

功能

• 将 TTF/OTF/TTC/OTC/WOFF/WOFF2 字体处理为 web-font 输出。
• 扫描、预检和批量处理字体目录。
• 在源目录混乱时生成整理计划，或非破坏性复制到暂存源目录。
• 使用 manifest 支持增量跳过和输出审计。
• 提供 get_agent_guidance，让 AI agent 用机器可读指南选择安全工作流。
• 提供 MCP 文档 resources 和 safe-batch-workflow prompt，让客户端可以直接发现项目文档和安全批量流程。
• 工具响应同时提供 structuredContent 和兼容旧客户端的 JSON 文本内容。
• 提供真实语料库 smoke suite，用复杂本地字体集合做代表性可靠性验证。

工具列表

工具	用途
get_agent_guidance	返回面向 agent 的工作流指南、工具安全速查表、字段检查清单、目录/identity catalog 和推荐调用模板。
get_runtime_status	只读检查工作区、Node engine、包版本、平台和 WASM 可用性。
inspect_font_inputs	不写输出地扫描输入目录，报告字体计数、坏字体、忽略文件、目录布局和推荐第一步。
organize_font_directory	规划或 copy-only 整理源字体目录；默认 dry-run，不移动、不删除、不重写源字体。
split_font	处理单个字体，可能得到正常分片、单 WOFF2 fallback 或 copy-original 登记。
split_font_batch	批量扫描、去重、命名、跳过已有输出并处理字体。
inspect_split_output	审计生成的拆分输出目录，检查目录角色、manifest 覆盖和结构问题。

MCP 资源和 Prompt

除工具外，服务还通过 MCP resources 暴露 README、API 和行为说明文档；通过 safe-batch-workflow prompt 提供“预检 → safe-preview → reviewed-write → 输出审计”的安全批量流程提示。支持 resources / prompts 的客户端可以直接从 MCP schema 发现这些入口。

常见工作流

1. 先让 agent 自我定位

{
  "tool": "get_agent_guidance",
  "arguments": {
    "workflow": "batch",
    "detailLevel": "compact"
  }
}

当目录形态、写入风险或下一步工具不确定时，先看 recommendedWorkflowPlan、nextToolDecisionSummary、toolSafetyQuickReference 和 responseFieldsToCheck。

2. 预检输入目录

{
  "tool": "inspect_font_inputs",
  "arguments": {
    "inputDir": "fonts",
    "maxFiles": 50000,
    "includeFiles": false
  }
}

先看 inputCountGuide、inputDirectoryDecision、inputDirectoryDecision.directoryOrganizationSafety、unsupportedFileDecision、unsupportedFileSummary、layout 和 maxFilesHit。压缩包和非字体文件会被报告为忽略项，不会被自动解压、复制或拆分。

3. 批量 safe-preview

{
  "tool": "split_font_batch",
  "arguments": {
    "inputDir": "fonts",
    "outputRoot": "split-output",
    "workflowPreset": "safe-preview",
    "limit": 50000,
    "maxFiles": 50000
  }
}

确认 dryRun: true、batchWarnings[]、dedupeDecisionSummary、batchPolicySummary、sourceSafetyDecision、recommendedNextActions[] 和 errors[] 后，再决定是否写入。

4. 审查后写入并审计输出

{
  "tool": "split_font_batch",
  "arguments": {
    "inputDir": "fonts",
    "outputRoot": "split-output",
    "workflowPreset": "reviewed-write",
    "limit": 50000,
    "maxFiles": 50000
  }
}

写入后运行：

{
  "tool": "inspect_split_output",
  "arguments": {
    "outDir": "split-output",
    "maxFiles": 200000,
    "includeFiles": false,
    "includeFamilies": false
  }
}

只有输出目录审计明确通过、没有扫描截断，并且结构诊断确认这是合格的拆分输出时，才把结果视为完成。字段级判定请看 API 参考 和 行为说明。

5. 源目录需要整理时

{
  "tool": "organize_font_directory",
  "arguments": {
    "inputDir": "fonts",
    "workflowPreset": "safe-preview",
    "includePlan": true,
    "maxFiles": 50000
  }
}

整理工具默认只返回计划。即使 reviewed-write，也只是 copy-only 写入 outputDir；它的输出是源目录式暂存，不是最终拆分输出。先用 inspect_font_inputs 检查暂存目录，再用 split_font_batch safe-preview。

关键风险

• ok: true 只表示工具按所选策略完成，不代表一定发生了正常多子集分片；优先看 resultType、outputMode、performedSplit、usedFallback、skipped 和 warnings。
• 所有路径都限制在 FONT_SPLIT_ROOT 内；工具响应里用 . 表示工作区根目录。
• 写入类工具完成后，不要只看 ok；还要看 sourceSafetyDecision、safetySummary、recommendedNextActions[] 和必要时的 inspect_split_output 审计结果。
• inputDirectoryDecision.directoryOrganizationSafety 是判断 organize_font_directory 是否可用、是否可能改动源文件的最短答案。
• organize_font_directory 不移动、不删除、不重写源字体；它写出的 outputDir 只是 copy-only 暂存源目录。
• split_font_batch 默认 batchNamingMode: "numeric-suffix"：先用裸名，只有真实冲突时才加 -1、-2 等稳定数字后缀。
• batchDedupeMode: "same-path" 只是路径/stem 级去重；batchDedupeMode: "font-identity" 会跨格式比较字体身份。
• font-identity 会按字体身份跨格式收敛等价 OTF/TTF/WOFF 输入；具体 name table 回退规则和诊断字段请看 API / 行为文档。
• .woff / .woff2 输入会先解压成 sfnt-like 数据，再进入处理流程。
• 显式传入的无效配置会被拒绝，而不是静默回退；需要默认行为时请省略该选项。
• 如果 outputRoot 位于 inputDir 内，真实写入仍会落在输入目录树里；描述“源目录树无写入”前必须检查 writesSourceTree 和 outputTreeInsideInputTree。

常用参数速览

参数	入口级说明
workflowPreset	safe-preview、reviewed-write、structure-first、source-layout、metadata-family、preserve-all。只是起点，显式参数仍可覆盖。
batchGroupBy	auto、source-dir、font-family。决定家族目录来自源结构还是字体元数据。
batchNamingMode	plain、numeric-suffix、source-suffix。默认 numeric-suffix。
batchDedupeMode	none、same-path、font-identity。默认 font-identity。
batchErrorMode	collect、fail-fast、fail-after。默认 fail-after。
dryRun	true 只预览，false 实际写出。
limit / maxFiles	控制批量规模和扫描上限；大目录通常需要显式调高。
includeResults	大批量只需要摘要、warning 和错误时可设为 false。

批量自定义速查

目标	最小参数起点	必须注意
保留每个源字体	workflowPreset: "preserve-all" 或 batchDedupeMode: "none"	不做 identity 去重；同名输出仍可能需要 numeric-suffix 避免互相覆盖。
按源目录分家族	workflowPreset: "source-layout" 或 batchGroupBy: "source-dir"	适合来源目录本身有意义的字体包；目录结构混乱时先做 organize_font_directory safe-preview。
按字体 metadata 分家族	workflowPreset: "metadata-family" 或 batchGroupBy: "font-family"	依赖字体内部 name 表；metadata 错乱时结果也会错。
快速扫大而杂的目录	workflowPreset: "structure-first"、includeResults: false	适合先看规模和结构；字体解析被推迟时，identity 去重和坏字体判断会受限。
强制裸输出名	batchNamingMode: "plain"	不自动加后缀，只在确认没有同名冲突或外部已处理冲突时使用。
保留错误报告继续跑	batchErrorMode: "collect"	批量可能仍返回 ok: true；必须检查 errorCount 和 errors[]。

完整参数、返回字段和错误形态请看 API 参考。

如何解释返回结果

工具	优先检查
split_font	outputMode、resultType、performedSplit、usedFallback、skipReason、warnings
inspect_font_inputs	inputCountGuide、inputDirectoryDecision、inputDirectoryDecision.directoryOrganizationSafety、unsupportedFileSummary、layout
split_font_batch	batchDecision、batchWarnings、batchPolicySummary、dedupeDecisionSummary、recommendedNextActions、sourceSafetyDecision、safetySummary
organize_font_directory	layoutDecision、sourceSafetyDecision、stagingDirectoryDecision、recommendedNextActions
inspect_split_output	输出角色判断、结构审计状态、阻塞原因、manifest 覆盖和输出结构摘要

这些字段是入口级阅读顺序，不替代 API 文档里的字段定义。

输出形态速查

看到的字段	含义	下一步
outputMode: "subset"、performedSplit: true	正常生成 web-font 分片。	真实写入后继续用 inspect_split_output 审计结构。
outputMode: "single-woff2"、usedFallback: true	没有正常多分片，退化为单个 WOFF2。	向用户说明 fallback，并检查 warnings[]。
outputMode: "copy-original"、skipped: true、usedFallback: false	没有生成 web-font 分片，只复制/登记原字体。	不要当成正常拆分结果；检查 manifest、resultType 和 skipReason。
skipped: true 且有 skipReason	单字体处理主动绕过正常多分片，例如小字形 fallback 或 copy-original。	结合 outputMode 和 usedFallback 解释；不要把它误当成批量已有输出跳过。
skippedExisting > 0 或 planned[].wouldProcess: false	批量 skip 逻辑接受了已有输出，或 dry-run 计划跳过该条目。	检查 skipMode、skippedByManifest、planned[].skipReason 并审计已有输出。
ok: true 但 errorCount > 0	批量按错误策略完成，但仍有单字体失败。	检查 batchErrorMode、errorCount 和 errors[]。

安装

git clone https://github.com/WenZhimo/mcp-font-split.git
cd mcp-font-split
npm install

依赖的 cn-font-split WASM 资源会通过 postinstall 脚本准备；也可以手动运行：

npm run install:wasm

使用方式

作为 MCP Server

claude mcp add font-split -- node "/path/to/mcp-font-split/src/server.js"

独立运行

npm start
npm run batch:run -- . split-output 50000 50000 --dry-run

batch:run 是给 agent 和维护者使用的安全批量入口。默认真实运行走 reviewed-write；--dry-run 或 FONT_SPLIT_DRY_RUN=true 会走 safe-preview。需要稳定 JSON 时用 --json 或 FONT_SPLIT_JSON=true。无效 preset、环境变量、位置参数或配置值会被拒绝；完整 CLI 参数和错误字段以 API 参考 为准。

验证

npm run check
npm run check:compact
npm run --silent check:compact -- --json
npm run smoke:api-docs
npm run smoke:behavior-docs
npm run smoke:real-corpus-suite -- <字体语料目录>

npm run check 是推荐给 AI agent / CI 的入口。check:compact 用于快速看 syntax + smoke 是否都通过；smoke:real-corpus-suite 用真实语料做代表性可靠性门禁，不是逐字体或逐目录人工验收。真实语料 suite 会区分全库扫描数量和代表性抽样数量，并明确压缩包只作为忽略文件统计，不会被自动解压验证。

环境变量

变量名	说明
FONT_SPLIT_ROOT	字体工作区根目录。未设置时默认使用 MCP Server 进程启动时的当前工作目录。
FONT_SPLIT_WASM_PATH	可选的自定义 libffi-wasm32-wasip1.wasm 运行时路径。

致谢与来源

本项目封装并调用 cn-font-split，核心字体分割能力来自该项目。

许可证

本项目采用 Apache License 2.0。使用依赖项时也请遵守其各自许可证。