Sty 上手全流程：样式单元、作用域与多目标输出配置拆解

第一次拿到 Sty 这个项目名的时候，我手上只有四个字和一个空荡荡的目录。没有现成的范例、没有可参考的完整配置，只有一堆散落在不同文件里的样式定义，文件名各不相同、字段写法也对不上。我当时的第一反应是照着项目说明把安装命令跑一遍，结果跑完发现命令是通了，但产出的东西跟我预期完全不是一回事——这就是绝大多数人上手陌生开源工具的典型翻车方式。这篇东西写给两类人：一类是被各种零散样式定义折磨到想找个工具统一收口的前端或主题开发者，另一类是想把一个轻量开源项目真正吃透、而不只是"能跑起来就行"的实践者。我会把 Sty 从定位、环境、概念模型、配置拆解、真实场景到踩坑排查完整走一遍，中间该解释原理的地方绝不含糊，该给能直接抄的配置也绝不藏私。

1. 先判断 Sty 在你这条链路上站在哪个位置

很多人学新工具的习惯是先跑通再理解，这在小工具上没太大问题，但像 Sty 这类涉及"输入定义、中间合并、输出成品"三段式处理的工具，你不先搞清它的位置，后面每调试一次都要绕一大圈。我的建议是，动手之前先花十分钟做一次链路定位，这十分钟能省掉后面好几个小时的瞎试。

1.1 从"我到底缺哪一环"倒推要不要用它

Sty 解决的问题非常具体：你有一批以声明式方式写成的样式单元，它们分散、重复、有覆盖关系，而下游消费方需要的是干净、有序、格式统一的结果。这三句话对应三个判断条件，缺一个就说明你其实不需要 Sty。

第一个条件，输入必须是"结构化的声明"，而不是一堆自然语言描述或者不可解析的文本。第二个条件，输入之间存在相互覆盖、继承或者优先级关系，如果每个单元都是完全独立的、互不影响，那直接拼接就行，引入合并引擎纯属自找麻烦。第三个条件，输出格式与输入格式不一致，需要做转换。

我见过有人把一个只有五个独立样式块的项目硬套进来，结果配置文件比样式本身还长。这不是工具的问题，是需求判断的问题。你自己列一张对照表，把"我现在的输入是什么形态"、"我要的输出是什么形态"写清楚，如果两边的形态完全一致、单元之间也没有覆盖关系，那就老老实实用最朴素的拼接方式，别上工具。

反过来，如果你手上是几十个来源不同、命名有重叠、还带主题切换需求的样式单元，那 Sty 这种"解析—应用—输出"三段式的设计就正好卡在这个痛点上。它的价值不在于帮你写样式，而在于帮你管理样式的关系。

1.2 解析层、应用层、输出层：所有功能都落在这三层里

我把 Sty 的能力按处理阶段拆成三层，这个拆法是我用下来觉得最省心的思维模型，因为几乎所有你遇到的问题都能直接归到某一层，排查范围立刻缩小三分之二。

解析层负责把你写的配置文件读进来，转成内存里的对象结构。这一层出问题的表现通常是：报错说语法不对、字段不认识、某个值类型不匹配。它跟运行时版本关系最大，因为配置语法的支持程度是跟着版本走的。

应用层负责把一堆样式单元按作用域和优先级规则合并。这一层是 Sty 的核心，也是最容易出隐性 bug 的地方——它不一定报错，但结果可能跟你想的不一样。比如你以为后定义的会覆盖先定义的，结果因为作用域深度不同，先定义的反而赢了。这种"静默错误"最耗时间。

输出层负责把合并后的结果序列化成目标格式。这一层的坑主要在格式细节上，比如缩进、字段顺序、空值处理、末尾换行，这些看起来无关紧要，但如果你的下游有 diff 对比或者格式校验，一点点差异就会让校验失败。

三层各有各的失败特征，我下面这张表是我自己排查时用的对照，你可以直接拿去改：

1.3 上手前的五分钟自检清单

在敲第一条命令之前，我会强制自己回答四个问题，答不上来就先别装环境。

第一，我的输入文件有几个、分别放在哪、命名有没有规律。这个决定了后面 glob 通配怎么写，写错一个字符就是"解析成功但输出为空"。

第二，我的输出要被谁消费。是浏览器直接读、是打包流程读、还是另一个程序按字段取值。消费方决定了目标格式和字段命名风格，这一条如果搞错，等于白忙。

第三，我需不需要主题切换或者多套变体。如果需要，那就得提前规划作用域层级，事后再加会很痛苦。

第四，我的团队里其他人会不会改这份配置。如果会，配置就得写得可读、带注释、字段名别玩缩写，不然后面维护成本全压在先写的人身上。

这四条看起来啰嗦，但我自己踩过的坑里，至少一半是这四条没想清楚导致的。工具本身不复杂，复杂的是你没想明白自己要什么。

2. 环境装配：让第一条命令真正产出东西

装环境和"装完能用"是两件事，中间差着一整套验证动作。我的习惯是：装完不算完，必须看到一个符合预期的产出文件才算环境就绪。下面这套流程是我反复用下来最稳的顺序。

2.1 运行时版本对齐：主版本号必须严格匹配

Sty 这类工具对运行时版本的敏感度比一般库高，原因在于配置解析器通常依赖运行时的语法特性。相邻大版本之间，解析器行为可能有变化，最典型的就是默认值改了、某些写法从宽容变严格。

我的做法是锁定主版本号，次版本和修订版本可以放开。比如运行时要求主版本为 18 及以上，那我只保证主版本一致，不去死磕具体的次版本号。这样既保证兼容，又不会因为一个小修订被迫整体升级。

如果你的项目有版本管理文件，把它写进去；如果没有，就在项目根目录放一个说明文件，写清楚"本项目要求运行时主版本为 X"，并且配一个前置检查脚本，在启动前先判断版本，不匹配就直接终止并给出提示。这个前置检查看起来多余，但在多人协作里能省掉大量"我这里能跑你那里跑不了"的扯皮。

需要特别留意的两个点：一是某些系统自带的运行时要老很多，直接调用全局命令会命中系统版本而不是你装的新版本；二是多个项目并行开发时，如果都用全局安装，版本冲突几乎必然发生。解决办法见下一节。

2.2 全局装、项目内装、容器化，三种方式的取舍

三种安装方式我都用过，各有各的适用边界，没有绝对的好坏，只有场景匹配度。

全局安装最省事，命令在哪都能敲。缺点是版本被全局锁定，你同时维护两个要求不同版本的项目时，就得来回卸装，非常难受。我的建议是：只在你需要临时试玩、或者写一次性脚本的时候用全局安装，正式项目别这么干。

项目内安装是我默认推荐的方式。工具版本跟着项目走，在项目目录内调用命令，命中的一定是项目锁定的那个版本。多人协作时，别人拉下代码装一次就完全一致，不存在"你版本比我新所以行为不一样"的情况。代价是命令不能直接在任意目录敲，得通过项目脚本或者包管理器提供的调用入口来执行。

容器化适合两类场景：一是你的构建流程本身就跑在容器里，那工具自然要跟着进镜像；二是你想把"环境"这件事彻底固化，连运行时版本都锁死。缺点是调试体验差一些，改配置要重建或者挂载卷，迭代速度慢。我一般只在最终交付或者持续集成环节用容器，日常开发还是项目内安装更顺手。

这三种方式的调用路径差异，是新手最容易混淆的地方。同一个命令，全局装的可以直接敲，项目内装的必须走调用入口，容器里的必须先进入容器。搞混了就会出现"命令不存在"的假象——其实工具装得好好的，只是你没走对门。

2.3 最小可运行闭环：从初始化到看到产出

环境装好之后，别急着写复杂的配置。先用工具自带的初始化能力生成一份最小配置，跑通一次完整的"读入—处理—输出"，确认整条链路是通的，再往上堆东西。

整个流程分四步：

1. 在项目根目录执行初始化命令，生成一份默认配置文件和示例输入目录。
2. 打开配置文件，只改两个字段：输入路径和输出路径，其他一律不动。
3. 执行构建命令。
4. 打开输出路径，确认文件存在、内容非空、格式符合预期。

第三步和第四步之间有个细节特别容易被忽略：一定要亲眼打开输出文件看一眼内容，不能只看命令返回成功。Sty 在输入为空的时候有些配置下不会报错，只是安静地生成一个空文件。我第一次就栽在这里，盯着"构建完成"的提示折腾了半天，最后发现输入通配符少写了一层目录。

验证的判据我定得很死：输出文件存在、大小不为零、随便挑一个样式单元在输出里能找到对应片段。三条全中才算环境就绪。如果第三条不中，说明应用层或者输出层有问题，回头查作用域配置；如果第一条都不中，那就是路径问题，去检查输入通配和输出目录权限。

3. Sty 的核心概念模型：三个对象撑起整套用法

Sty 的文档里概念不少，但我用下来觉得真正需要刻进脑子里的只有三个：样式单元、作用域、输出目标。剩下的字段和选项都是围绕这三个转的。把这三个搞透，看任何配置都能一眼看出它在干什么。

3.1 样式单元：Sty 世界里的最小单位

样式单元是一段可以被独立识别、独立覆盖的最小定义块。它有三个必备属性：标识、内容、来源。

标识是它在这个系统里的唯一名字。标识的写法直接决定了后面覆盖规则能不能生效，所以命名要有层级感，别用a、b、c这种。我的习惯是按"领域-模块-用途"三段式命名，比如theme-color-primary，一眼能看出归属。

内容就是这个单元具体描述了什么东西。它可以是简单的键值对，也可以带嵌套结构，取决于你的目标格式复杂度。

来源是它从哪个文件读进来的。这个属性平时看不见，但排查问题时极其有用——当你发现某个值不对，第一步就是确认这个值到底来自哪个文件，没有来源信息你就得靠猜。

样式单元还有一个隐性属性叫声明顺序，也就是它在输入流里被读到的先后。这个属性在应用层参与优先级计算，而且是最容易被忽略的那一票。很多人以为配置文件里写在前面的优先，实际上大多数情况下是后面读到的覆盖前面读到的，但一旦引入作用域，这个直觉就不成立了。

我建议你在动手写第一批单元的时候，就先把命名规范定下来，只花十分钟，后面能省掉大量重命名的工作。规范里至少要包含：分隔符用什么、层级分几段、大小写规则、以及保留哪些前缀给内部使用。

3.2 作用域：决定谁覆盖谁的隐藏规则

作用域是 Sty 里最有价值也最容易理解错的概念。你可以把它想成"优先级的分组标签"——同一个单元在不同作用域下定义，最终生效的那个由作用域的层级决定，而不是由谁先谁后决定。

优先级的具体计算，我实测下来大致是三个因素叠加：作用域深度、单元标识的特异性、声明顺序。前两个是主要因素，第三个只在前两个打平时才起作用。这个叠加顺序非常关键，它意味着：你后写的单元不一定赢，如果它的作用域比前面的浅的话。

我遇到过最典型的一次翻车是这样的：我在一个基础配置文件里定义了一批默认值，然后在主题文件里覆盖了其中一个，结果构建出来还是默认值。查了半天才发现，基础配置的作用域被标成了高层级，主题文件反而是低层级。改法很简单，把主题文件的作用域调高一级就对了。

为了少踩这类坑，我在项目里定了一条铁律：作用域只分三层，基础层、主题层、覆盖层，层级严格递增，不允许出现第四层。层数一多，优先级计算就变成玄学，没人能在脑子里推演出来。三层足够覆盖绝大多数场景，实在不够就拆成多个配置文件分别处理。

表格最后一行那句"需标注原因"不是形式主义。覆盖层的东西一旦多了，后面没人知道哪些能删哪些不能删，加一行注释的成本远低于半年后逐行考古。

3.3 输出目标：从一份配置产出多种成品

输出目标的本质是"序列化策略"。同一份合并结果，你可以序列化成适合浏览器直读的格式，也可以序列化成便于程序按字段取值的结构化格式，还可以序列化成某种主题包需要的打包格式。差异只在序列化这一层，前面的解析和合并完全复用。

这个设计带来的直接好处是：你不需要为每种输出维护一份配置，只要在目标列表里多加一项，前面的逻辑一行都不用改。我现在的项目里就是一份配置产出两种格式，一种给运行时用，一种给文档工具用，两边永远同步，不会出现"文档里的颜色和实际渲染的对不上"这种低级问题。

需要注意的一点是，多目标之间如果有共享的"公共部分"，尽量用引用而不是复制。有些目标格式要求把公共部分内联展开，有些要求单独成段，这些差异应该在目标配置里声明，而不是在源数据里复制两遍。复制两遍就意味着以后改一处忘一处。

目标配置里还有一个容易被忽略的字段：空值处理策略。合并之后，某些单元可能因为覆盖关系变成了空，这些空值是保留占位、还是直接裁掉，不同消费方的要求不一样。保留占位的好处是输出结构稳定，便于做 diff；裁掉的好处是输出干净，体积小。这个得按你的下游来定，没有通用答案，但一定要显式声明，别用默认值蒙混过去。

4. 配置文件逐字段拆解：一份可以直接改的模板

配置文件是 Sty 使用中最需要花心思的部分，因为它既是给人看的，也是给机器读的。我下面按"从上到下"的顺序拆一遍，每个字段讲清楚它管什么、什么时候需要改、以及改错了会有什么症状。

4.1 顶层字段：版本、输入、输出

顶层字段数量不多，但每一个都是全局性的，写错一个整个流程就崩。

版本声明这个字段大部分人直接抄默认值，但我建议你养成写死的习惯。它决定了工具用哪套解析规则去读你的配置，声明得越明确，将来升级时行为变化的可能性越小。如果不写，工具会用当前默认版本，而默认版本是会跟着工具升级变的，这就埋了个定时雷。

输入路径支持单个路径和通配符两种写法。我强烈建议用通配符，把输入目录整体框进去，而不是一个个列文件。原因很简单：以后新增文件不用改配置。但通配符有个陷阱，层级要写对。想匹配"目录下所有子目录里的文件"，通配符中间要跨一层，少写一段就变成了"只匹配当前目录"，这时候新增的子目录文件会被静默忽略——不报错，就是不生效。

输出路径除了目录，还要考虑文件命名规则。如果只有一个输出目标，写死文件名没问题；如果是多目标，就得用占位符让文件名跟着目标名走。命名规则定好之后尽量别改，因为下游可能已经按这个名字引用了。

我常用的最小配置骨架大致是这样一个结构（字段名以你手上的版本为准，这里只体现组织方式）：

version: 1 input: - "units/**/*.yaml" output: dir: "./dist" naming: "{target}.out" targets: - name: "runtime" format: "css" - name: "docs" format: "json"

这份配置里，输入用通配符框住了整个units目录及其子目录，输出目录统一，文件名按目标名生成，目标列表里挂两个格式不同的输出。这就是我说的"一份配置多份产出"的最小形态。

4.2 规则字段：匹配、应用、优先级

规则字段是应用层的核心，它决定了一个样式单元在什么条件下被处理、被怎么处理。典型结构包含三段：匹配条件、应用动作、优先级标记。

匹配条件负责圈定这条规则作用在哪些单元上。支持按标识匹配、按来源文件匹配、按所属作用域匹配，也支持组合。组合的时候注意逻辑关系，是"且"还是"或"，这两种写法的结果天差地别。我一般优先按来源文件匹配，因为文件本身已经承载了语义，比按标识去猜更稳。

应用动作定义了匹配到之后做什么。常见的有覆盖取值、追加内容、排除不输出、重命名。其中"排除"这个动作特别有用，比如某个单元只在开发环境需要，正式产出里不该出现，就在正式目标下加一条排除规则，比在两个地方维护两份输入干净得多。

优先级标记是给规则本身排序的。当多条规则同时命中一个单元时，谁的优先级高谁生效。这里的优先级跟前面说的作用域优先级是两套体系，别混。作用域决定单元之间的覆盖，规则优先级决定规则之间的执行顺序。我一开始把这两个搞混，调了半天发现改错了地方。

写规则的时候有个习惯我强烈推荐：每条规则都写一句注释说明为什么存在。规则这种东西，写的时候觉得天经地义，三个月后看就是天书。尤其是带排除和重命名的规则，不写原因后面没人敢动。

4.3 继承与覆盖：配置本身的分层

除了样式单元有覆盖关系，配置文件本身也可以分层。类继承的机制让你把公共配置抽成一个基础文件，各个场景的配置文件去继承它，只写差异部分。

这个机制的收益在配置变多之后才明显。我现在的做法是：基础配置文件里只放输入输出路径、目标列表这些几乎不变的东西；各环境各写一个配置文件继承基础配置，只写本环境特有的规则和覆盖。这样一来，改公共部分只改一处，改环境特有部分互不影响。

有个细节要注意：继承链不要太长。两层（基础 + 场景）是舒服的，三层就开始难追了，超过三层基本等于自找麻烦。因为你在读最末端的配置文件时，脑子里要同时装着三层的内容才能判断最终结果，人脑装不下这么多。

还有一点，继承来的字段如果在本层要取消，得有明确的"清空"写法，不能简单留空——留空在很多实现里等于"用继承来的值"，而不是"取消"。这个语义差异我第一次遇到时浪费了不少时间，明明写了空值，实际还是生效了。

5. 三个真实场景完整跑一遍

光讲字段太干，我挑三个我自己项目里真实用过的场景，把配置和产出都摊开讲，你可以照着改。

5.1 单目标场景：一套主题的最小闭环

最简单的场景：只需要输出一种格式，没有多环境，没有变体。这时候配置应该尽可能短。

我的一般做法是，输入目录下按模块分文件，每个文件里定义若干个单元，命名统一用三段式。目标列表只挂一项，格式选最常用的那种。规则只写一条：排除以_开头的单元（约定为内部使用，不输出）。

跑一遍之后检查三件事：输出文件里有没有漏掉应该有的单元、有没有多出不该有的单元、值对不对。第一项和第二项查的是匹配规则，第三项查的是覆盖关系。这个检查流程我用了很久，基本能在两分钟内定位问题所在。

这个场景里最容易过度设计。看到各种高级选项就想用，结果配置写了二百行，实际只用了其中三行的能力。我的经验是：单目标场景下，配置文件控制在三十行以内，超过就说明里面有可以删的东西。

5.2 多目标场景：一份数据喂两个消费方

第二个场景复杂一点：同一批样式单元，既要产出给运行时直接用的格式，又要产出给文档工具读的结构化格式。两个消费方对字段命名、嵌套结构、空值处理的偏好都不一样。

处理思路是：源数据保持中立，不做任何偏向某一方的处理；差异全部下沉到目标配置里。具体做法是给每个目标单独声明格式选项，包括字段命名风格（有的消费方喜欢连字符，有的喜欢驼峰）、嵌套深度、空值是否保留。

这里有个坑值得单独说：两个目标共用同一批规则时，规则里的排除和重命名会同时影响两边。如果你的排除逻辑是给某一方用的，一定要把规则挂在对应的目标下，而不是挂在全局。我第一次做多目标时就犯了这个错，给文档输出排除的单元，结果运行时输出里也一起没了，排查了好一阵。

另一个细节是输出顺序。结构化格式通常对字段顺序敏感（做 diff 对比时尤其），序列化的时候要保证顺序稳定。稳定顺序的来源有两个：一是输入读取顺序稳定，二是合并过程本身不引入随机性。前者靠输入路径排序保证，后者靠工具实现保证。如果你的输出顺序每次都变，先检查输入通配的展开顺序。

5.3 接进构建流程：前置校验与开发期监听

工具单独跑和接进构建流程是两码事。接进去之后要考虑两个时机：构建前的校验、开发期的监听。

构建前校验的作用是把配置错误挡在构建之前。Sty 一般带一个校验命令，它只做解析和规则推演，不产出文件，速度快。把它挂在构建流程的最前面，配置写错就立刻失败，不用等整个构建跑完才发现。

开发期监听的作用是改动即产出。开一个监听进程，盯着输入目录，文件一变就重新构建。这个在调样式的时候体验提升非常明显，比手动一遍遍敲命令强太多。注意监听的进程要跟构建进程分开，监听是常驻的，构建是一次性的，混在一起会互相干扰。

接进流程之后有个问题会冒出来：输出目录要不要纳入版本管理。我的建议是不要。输出是产物，产物入库会带来大量无意义的 diff，还会引发"改了源文件忘了重新构建"的错位。如果下游确实需要产物，就在流程里保证构建一定执行，而不是靠人工同步。

6. 五类高频故障的排查链路

这一节是我踩坑踩出来的，每一条都附完整排查链路，你可以照着一步步走，而不是直接跳到结论——因为结论往往依赖你的具体配置，只有过程可以复用。

6.1 提示命令不存在，但明明装过了

第一反应是"没装上"，实际上十有八九是调用路径问题。

排查顺序这样走：先确认工具在不在，用包管理器列一下已装列表，看看有没有它；如果在，说明是路径没对上，接着判断你敲的命令命中的是全局还是项目内的；如果全局和项目内都装了但版本不同，那就是调用入口走错了。

这里有个特别隐蔽的情况：全局装了一个老版本，项目内装的是新版本，你在项目目录里敲命令，如果没走项目内的调用入口，命中的还是全局老版本。表现就是"新版本的配置语法报错说字段不认识"——你会以为是语法写错了，实际上是版本不对。

判断方法很简单：让工具打印一下自己的版本号，跟你预期的对一下。对不上就是路径问题，不是配置问题。这一步能省掉大量无谓的配置排查。

6.2 构建成功但输出是空的

这是最高频的问题，没有之一。构建成功、没有报错、输出文件存在、大小为零或者只有一层空壳。

排查顺序：打开输出文件确认到底是不是空；然后回头看输入通配符，把它打印出来看实际匹配到了哪些文件；如果匹配列表是空的，问题在通配符层级；如果匹配到了但输出还是空，问题在规则上，很可能是某条排除规则把所有东西都排掉了。

通配符层级这个坑我说过很多次还是有人踩。判断方法很简单：把通配符换成具体的单个文件路径试一次，能出结果就是通配符的问题，还是空就是规则的问题。这个二分法是我排查这类问题的标准起手式。

还有一种情况是输入文件本身解析成功但内容为零——比如文件里只有一个顶层键，下面什么都没写。这种文件读进来不报错，但贡献不了任何单元。检查方法是看每个输入文件的实际单元数量，加起来是零就说明问题出在输入侧。

6.3 覆盖不生效，值还是老的

这类问题不报错，只是结果不对，最耗时间。

排查链路：先定位这个值最终来自哪个文件，也就是追来源属性；然后看这个文件里的单元属于哪个作用域；再对比其他定义了同名单元的作用域，比层级高低；最后确认规则的优先级标记有没有干扰。

大多数情况下问题出在作用域层级上。我前面提过的那条铁律——作用域只分三层——就是为了让这一步能在十秒内完成。如果你的作用域有五六层，这步就得靠工具输出详细日志来推演了。

另一个常见原因是标识写法不一致。看起来是同名，实际上一个用了连字符一个用了下划线，在系统眼里就是两个不同的单元，互相根本不会覆盖。这种情况尤其容易发生在多人协作、不同人负责不同文件的场景里。我的做法是定完命名规范后，加一条校验规则强制检查标识格式，不合规就报错。

6.4 批量处理跑到一半断掉

批量场景下，某一个文件出错导致整个流程中断，剩下的都没处理。这时候要区分是"应该中断"还是"应该跳过"。

我的判断标准是：解析层错误应该中断，应用层警告可以跳过。解析错误意味着这个文件根本读不进来，跳过它会让输出缺失一块而且没人知道，必须中断。应用层的警告比如某个单元没有匹配到任何规则，这个可以记录日志后继续，因为不影响整体产出。

Sty 一般提供错误处理策略的开关，把它显式设成你需要的模式。我默认设成"解析错误立即中断"，然后在持续集成里加一步日志扫描，把所有的跳过项打印出来人工过一遍。这样既不会因为一个小问题阻断整个流程，也不会让问题悄悄溜过去。

跑完之后还要核对数量：输入有多少个文件、成功处理多少个、跳过多少个，三个数对得上才算完整。这个核对步骤我写成了脚本，跑完自动打印，比人眼数靠谱。

6.5 升级之后行为变了，但配置没动

这是最让人抓狂的一类，因为你的配置一个字没改，结果变了。

成因通常是默认值调整。工具的某些字段有默认值，升级之后默认值可能变了，而你依赖了旧默认值。表现就是升级前正常、升级后不对。

排查方法：先回退版本确认是不是升级导致的；确认后在变更说明里找默认值相关的条目；然后把所有依赖默认值的字段全部显式写死。

这件事的教训是：别依赖默认值。我现在的习惯是，凡是会影响输出的字段，全部显式声明，哪怕它的值跟默认值一样。多写几行换来的是升级时的确定性，这笔账很划算。默认值是给人省事的，不是给生产环境用的。

7. 源码结构与二次开发：想加个输出格式怎么做

用熟之后难免会遇到"我要的输出格式它不支持"的情况。这时候要么等，要么自己加。自己加的成本其实不高，前提是你知道代码分几块。

7.1 源码的三段式结构

Sty 的源码基本对应我前面说的三层：解析、应用、输出。三块的边界通常很清晰，各自的输入输出都是明确定义的数据结构。

解析模块负责把配置文件和各种输入格式读成统一的内存结构。你想支持一种新的输入格式，就改这里，加一个读取器实现既定的接口。

应用模块负责合并、排序、算优先级。这块一般不需要动，除非你要改覆盖语义，那属于大改，慎之又慎。

输出模块负责序列化。你想加一种新输出，就在这里加一个输出器。这是二次开发里最常见也最安全的需求，因为它不影响前面的逻辑。

我第一次读源码时走了弯路，从入口一路往下读，读到一半就迷路了。后来换了个方法：先找到输出模块的注册点，看它是怎么把"格式名"映射到"输出器实现"的，然后照着已有的实现抄一个。这个方法比从头读快得多，因为注册点附近往往就是最清晰的扩展接口。

7.2 加一个输出器的完整动作

具体步骤大致是这样：先在输出目录下找一个结构最简单的现有实现，通读一遍搞清楚它接收什么、返回什么；然后复制一份改名，把核心的序列化逻辑替换掉；接着在注册的地方把新格式名挂上去；最后写一个最小输入跑一遍，对比输出。

写的时候有个原则：只动序列化，不动数据。输入给你的已经是合并好的结果，你只管把它变成字符串。任何"顺手在这里修一下数据"的念头都要掐掉，那会把职责搞乱，后面出问题根本定位不到。

序列化里最容易出错的是边界情况：空值、单元素、超长字段、特殊字符转义。我一般会造一组专门的边界输入，每次改完都跑一遍。这组输入花不了多少时间，但能挡掉大部分低级错误。

7.3 版本锁定与长期维护

自己维护一个分支之后，跟上游的关系要处理好。我的策略是：改动尽量小而集中，只碰输出模块，前面的模块一行不动。这样上游更新时，合并冲突基本集中在一两个文件，处理起来快。

版本锁定方面，我建议锁到修订号。因为你改动过源码，上游任何一个改动都可能跟你的补丁冲突，锁得越细，出问题的窗口越小。升级的时候不要直接跳到最新，一个版本一个版本往上走，每次升完跑一遍全量验证，确认输出没有意外变化。

长期维护还有一个容易被忽略的点：给自己写一份改动说明。改了什么、为什么改、怎么验证，三句话就行。这份说明放在仓库根目录，比写在提交记录里更容易被看到。半年后你自己回头看，会感谢当时写了这三句话。

最后分享一个我个人在实际操作中的体会：上手这类"输入—处理—输出"结构的开源工具，前期花在理解数据流上的时间，回报率远高于花在调参数上的时间。数据流想清楚了，参数就是填空题；数据流没想清楚，参数就是猜谜。我最初几次折腾都是急于看到产出，配置改了一版又一版，结果方向一直在错的地方。后来逼自己先画一遍数据流向图（在纸上画，不用任何工具），把每个环节的输入输出写清楚，问题往往在画的过程中就暴露了。