hexo-text-pipeline 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sentixxx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+**English** | [简体中文](README.zh-CN.md)
+
+# hexo-text-pipeline
+
+A general-purpose hooks bus for Hexo's render pipeline.
+
+Every text-in/text-out point of Hexo's rendering process is exposed as a stage. You hang things on stages — your own scripts, shell commands, or packaged presets — through plain declarative config. A checker system backstops everything: misconfiguration is caught before the first post renders, and a failing node is skipped, never your build.
+
+The design goal: most of what a small Hexo plugin does is "transform some text at some point of the pipeline". That shouldn't require publishing a package, or even config — **writing a plugin is writing one file**. Create `text-pipeline/` at your site root and drop this in:
+
+```js
+// text-pipeline/arrow.js — this is a complete plugin
+module.exports = {
+  replace: [[/-->/g, '→']]
+};
+```
+
+It runs on the next `hexo generate`: zero-config discovery, code blocks automatically protected in the markdown stage, logic edits apply on the next render, and a broken plugin is skipped — never your build. Full contract: [docs/PLUGINS.md](docs/PLUGINS.md).
+
+## Stages
+
+| Stage | Text flowing through |
+|-------|----------------------|
+| `before_post_render` | per-post **markdown**, before rendering |
+| `after_post_render` | per-post **HTML fragment**, after rendering |
+| `after_render:html` | **full page HTML**, after template rendering |
+| `after_render:css` / `after_render:js` | generated assets |
+
+These map 1:1 to [Hexo's filter API](https://hexo.io/api/filter). Non-text filters (`template_locals`, `server_middleware`, …) are deliberately out of scope.
+
+## Four ways to hang a node
+
+**1. Single-file plugin (the default answer)** — every `.js` file in the `text-pipeline/` directory mounts automatically. Export a node object in the unified contract shape (`name` defaults to the filename); a `replace` rule list is the declarative form of `convert`; `_config.yml` can override `enable` / `slot` / `priority` per plugin name, remaining sub-config reaches the plugin as `ctx.config`. Details: [docs/PLUGINS.md](docs/PLUGINS.md).
+
+```js
+// text-pipeline/ruby.js
+module.exports = {
+  stage: 'before_post_render',
+  match: '\\{ruby',
+  convert: (text, ctx) => text.replace(/\{ruby (.+?)\}/g, '<ruby>$1</ruby>')
+};
+```
+
+**2. Local script (hook)** — `module.exports = (text, ctx) => text`, resolved against the Hexo root, re-required on every run. Edit the file, the next render picks it up. Use it when you want the plain-function shape with placement living in YAML.
+
+```yaml
+hooks:
+  - script: scripts/minify.js
+    stage: after_render:html
+```
+
+**3. External command** — content on stdin, transformed content on stdout. Any language. Context via env vars: `HTP_STAGE` / `HTP_SLOT` always; `HTP_POST_SOURCE` / `HTP_POST_PATH` / `HTP_POST_TITLE` on post stages, `HTP_FILE_PATH` on string stages.
+
+```yaml
+hooks:
+  - command: python scripts/furigana.py
+    stage: before_post_render   # default stage
+    name: furigana              # optional, for logs
+    priority: 20                # optional, default 10, lower runs first
+    timeout: 10000              # optional, ms
+    match: '\\{furigana'        # optional regex: skip the hook (and the spawn) when the text doesn't match
+    slot: late                  # optional: late (default, sees the stage's final text) | early (raw text)
+```
+
+**4. Programmatic** — other plugins (or a script in your site's `scripts/` dir) can register nodes directly:
+
+```js
+hexo.textPipeline.register({
+  name: 'exclaim',
+  stage: 'before_post_render',
+  priority: 5,
+  convert: (text, ctx) => text + '!'
+});
+```
+
+Registration shares the same defaults and validation as hooks (slot defaults to `late`, `match` regex pre-checks work too). `ctx` is `{ hexo, stage, pluginConfig, utils, log }`, plus `ctx.post` on post stages / `ctx.file` on string stages; `ctx.utils` ships `replaceOutsideCode` / `segmentInlineCode` for safely skipping code blocks in the markdown stage.
+
+### Execution order: two slots per stage
+
+Each stage has two mounting slots, registered around Hexo's own filters:
+
+```
+[5]   early slot — preset nodes by default (they need the raw text, e.g. mermaid
+      must see fenced blocks before the highlighter eats them)
+[10]  hexo internals (code highlighting, …) and other plugins
+[100] late slot — your hooks by default (they see the final text of the stage)
+```
+
+Override with `slot: early` on a hook (run before everything) or `slot: late` on a preset node. Within a slot, nodes run by ascending `priority` (default 10), ties by declaration order. `hexo pipeline` prints the exact resolved order so you never have to guess.
+
+## The checker system (the safety net)
+
+1. **Static checks at registration** — before any post is touched: unknown config keys (with did-you-mean suggestions), invalid stages, duplicate node names, non-numeric priorities, missing script files, and order-ambiguity warnings when nodes from different sources share a priority.
+2. **Runtime guards on every execution** — a node that throws or returns a non-string is skipped with a warning and the original text flows on; a node that fails 3 times in a row is circuit-broken for the rest of the run; suspicious output (non-empty input wiped to empty, or 20x size explosion) is flagged but accepted.
+3. **`hexo pipeline`** — prints every stage's resolved node order (priority + source) plus all check results, so conflicts are visible before you deploy.
+
+Default policy is warn-and-skip: your build never breaks because of one bad hook. Set `strict: true` (for CI) to turn config errors and node failures into build failures.
+
+## Developing hooks (debug mode)
+
+Two tools answer "what does my hook actually receive at this stage?":
+
+**`hexo pipeline --dry-run source/_posts/x.md`** — runs the `before_post_render` chain on one file, printing each node's effect as a line diff (skipped / no change / changed / FAILED), without generating anything.
+
+**tap** — during a real `hexo generate` / `hexo s`, dumps the text flowing through every stage to snapshot files:
+
+```yaml
+text_pipeline:
+  tap:
+    enable: true
+    match: my-post        # strongly recommended: only capture matching sources/paths
+    dir: .text-pipeline-tap
+```
+
+```
+.text-pipeline-tap/_posts_my-post.md/after_post_render.late/
+├── 00-input.txt              ← exactly what a (late-slot) hook on this stage receives
+├── 01-hook_my-hook.txt       ← text after each node that changed it
+└── …                         ← the last file is the slot's final output
+```
+
+One snapshot directory per stage and slot (`<stage>.early` / `<stage>.late`).
+
+Each render cycle replaces the previous snapshot. Add the tap dir to `.gitignore` and turn `enable` off for normal builds.
+
+## Built-in preset: `obsidian`
+
+Compiles Obsidian Flavored Markdown for Hexo. Enable with `presets: [obsidian]`.
+
+| Node | Syntax | Default | Behavior |
+|------|--------|---------|----------|
+| `comment` | `%%inline%%`, multi-line `%% … %%` | on | Stripped before rendering (literal inside code) |
+| `embed` | `![[image.png\|300]]`, `![[Note]]` | on | Images → markdown image / `<img width>` (`asset_prefix` config); resolvable note embeds → link; others untouched |
+| `wikilink` | `[[target#anchor\|alias]]`, `[[#heading]]` | on | Rewritten to the post's permalink (`abbrlink` first, `post.path` fallback); same-page headings → `#anchor`; block-ref anchors (`#^id`) degrade to the post link |
+| `highlight` | `==text==` | on | `<mark>text</mark>` |
+| `blockid` | trailing `^block-id` | on | Stripped (invisible in Obsidian reading view too) |
+| `mdlink` | Leftover `.md` links in HTML | on | Fallback rewrite to the post's permalink |
+| `mermaid` | ` ```mermaid ` fenced blocks | on | Swapped to `<pre class="mermaid">` so highlighters don't eat the diagram; lazy CDN loader injected |
+| `callout` | `> [!type] Title` | **off** | `<div class="callout callout-type">`; off because most renderers/themes already support callouts |
+
+```yaml
+presets:
+  - name: obsidian
+    config:
+      domain_prefix: ''                  # link prefix for wikilink/mdlink/embed
+      callout: { enable: true }          # opt in
+      embed: { asset_prefix: /images }   # prepended to embedded image paths
+      mermaid: { theme: dark, priority: 15 }   # any node: sub-config + priority override
+```
+
+## Installation
+
+```bash
+npm install hexo-text-pipeline --save
+```
+
+## Full configuration reference
+
+```yaml
+text_pipeline:
+  enable: true       # master switch
+  debug: false       # verbose logging
+  strict: false      # config errors / node failures fail the build (CI)
+  inject_css: true   # nodes' default styles (e.g. callout)
+  inject_js: true    # nodes' frontend scripts (e.g. mermaid loader)
+  presets: []        # built-in name | npm package | ./local/path | { name, config }
+  hooks: []          # { script | command, stage, slot, priority, name, timeout, match, enable }
+  plugins_dir: text-pipeline   # single-file plugin directory; false disables discovery
+  plugins: {}        # per-plugin overrides: { <name>: { enable, slot, priority, ...rest lands in ctx.config } }
+  tap:               # debug mode: dump per-stage text snapshots (see "Developing hooks")
+    enable: false
+    match: ''
+    dir: .text-pipeline-tap
+```
+
+## Development
+
+Zero runtime dependencies, Node >= 16.
+
+```bash
+npm test   # node --test
+```
+
+- **Single-file plugins (start here to write a plugin)**: [docs/PLUGINS.md](docs/PLUGINS.md)
+- Hooks API reference (stage inputs, ctx fields, debugging workflow): [docs/HOOKS-API.md](docs/HOOKS-API.md)
+- Architecture, stage table, node contract: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Extending: hook vs preset node vs new preset: [docs/EXTENDING.md](docs/EXTENDING.md)
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,191 @@
+[English](README.md) | **简体中文**
+
+# hexo-text-pipeline
+
+Hexo 渲染管线的通用 hooks 总线。
+
+Hexo 渲染过程中所有"文本进、文本出"的执行点都被暴露为 stage。你用纯声明式配置往 stage 上挂东西——自己的脚本、shell 命令、或打包好的 preset。checker 系统全程兜底：配置错误在第一篇文章被处理之前就被发现，单个节点失败只会被跳过，构建永远不炸。
+
+设计目标：绝大多数小型 Hexo 插件做的事，本质都是"在管线的某个点变换一段文本"。这不该需要发包、不该需要配置——**写插件就是写一个文件**。在站点根目录建 `text-pipeline/`，丢进去：
+
+```js
+// text-pipeline/arrow.js —— 这就是一个完整插件
+module.exports = {
+  replace: [[/-->/g, '→']]
+};
+```
+
+下一次 `hexo generate` 它就在跑了：零配置自动发现，markdown 阶段自动跳过代码块，逻辑改动即改即用，坏了只会被跳过、构建永远不炸。完整契约见 [docs/PLUGINS.zh-CN.md](docs/PLUGINS.zh-CN.md)。
+
+## Stage 表
+
+| Stage | 流经的文本 |
+|-------|-----------|
+| `before_post_render` | 单篇文章的 **markdown**（渲染前） |
+| `after_post_render` | 单篇文章的 **HTML 片段**（渲染后） |
+| `after_render:html` | 模板套完后的**完整页面 HTML** |
+| `after_render:css` / `after_render:js` | 生成的静态资源 |
+
+与 [Hexo filter API](https://hexo.io/api/filter) 一一对应。非文本的 filter（`template_locals`、`server_middleware` 等）刻意不在范围内。
+
+## 四种挂载方式
+
+**1. 单文件插件（默认答案）** —— `text-pipeline/` 目录里每个 `.js` 文件自动挂载。导出与统一契约同形的 node 对象（`name` 缺省取文件名），`replace` 规则表是 `convert` 的声明式写法；`_config.yml` 可按插件名覆盖 `enable` / `slot` / `priority`，其余子配置进 `ctx.config`。详见 [docs/PLUGINS.zh-CN.md](docs/PLUGINS.zh-CN.md)。
+
+```js
+// text-pipeline/ruby.js
+module.exports = {
+  stage: 'before_post_render',
+  match: '\\{ruby',
+  convert: (text, ctx) => text.replace(/\{ruby (.+?)\}/g, '<ruby>$1</ruby>')
+};
+```
+
+**2. 本地脚本（hook）** —— `module.exports = (text, ctx) => text`，相对 Hexo 根目录解析，每次执行重新加载。改完文件，下一次渲染就生效。想要纯函数形态、placement 写在 YAML 里时用它。
+
+```yaml
+hooks:
+  - script: scripts/minify.js
+    stage: after_render:html
+```
+
+**3. 外部命令** —— 正文从 stdin 进，变换结果从 stdout 出，任何语言。上下文走环境变量：`HTP_STAGE` / `HTP_SLOT` 恒有，post 类 stage 给 `HTP_POST_SOURCE` / `HTP_POST_PATH` / `HTP_POST_TITLE`，string 类给 `HTP_FILE_PATH`。
+
+```yaml
+hooks:
+  - command: python scripts/furigana.py
+    stage: before_post_render   # 默认 stage
+    name: furigana              # 可选，日志标识
+    priority: 20                # 可选，默认 10，小者先跑
+    timeout: 10000              # 可选，毫秒
+    match: '\\{furigana'        # 可选正则：文本不命中直接跳过（command 可省一次 spawn）
+    slot: late                  # 可选：late（默认，看到该 stage 最终文本）| early（原始文本）
+```
+
+**4. 程序化注册** —— 其他插件（或站点 `scripts/` 目录里的脚本）可以直接注册 node：
+
+```js
+hexo.textPipeline.register({
+  name: 'exclaim',
+  stage: 'before_post_render',
+  priority: 5,
+  convert: (text, ctx) => text + '!'
+});
+```
+
+注册的默认值与校验和 hooks 同一套规则（slot 默认 `late`，也支持 `match` 正则预判）。`ctx` 为 `{ hexo, stage, pluginConfig, utils, log }`，post 类 stage 另有 `ctx.post`、string 类有 `ctx.file`；`ctx.utils` 自带 `replaceOutsideCode` / `segmentInlineCode`，在 markdown 阶段做行内替换时安全跳过代码块。
+
+### 执行顺序：每个 stage 两个挂点
+
+每个 stage 有两个挂点，注册在 Hexo 自己的 filter 前后：
+
+```
+[5]   early 挂点 —— preset node 默认在这里（它们需要原始文本，
+      比如 mermaid 必须在高亮器吃掉围栏代码块之前看到它）
+[10]  hexo 内置 filter（代码高亮等）和其他插件
+[100] late 挂点 —— 你的 hook 默认在这里（看到该 stage 的最终文本）
+```
+
+hook 加 `slot: early` 可以抢到所有人之前；preset node 加 `slot: late` 可以压到最后。同一挂点内按 `priority` 升序（默认 10），同级按声明顺序。`hexo pipeline` 会打印最终解析出的精确顺序，永远不用猜。
+
+## Checker 系统（兜底）
+
+1. **注册期静态检查**——在任何文章被处理之前：未知配置键（带 did-you-mean 建议）、非法 stage、node 重名、priority 类型错误、脚本文件缺失、不同来源的 node 共享同一 priority 的顺序歧义提示。
+2. **运行期防护**——每次执行都过守卫：抛错或返回非字符串的 node 被跳过并告警，原文继续流向下一环；连续失败 3 次的 node 整轮熔断；可疑输出（非空输入被清空、体积膨胀 20 倍）会被标记但放行。
+3. **`hexo pipeline` 诊断命令**——打印每个 stage 解析后的 node 顺序（priority + 来源）和全部检查结果，冲突在部署前就能看见。
+
+默认策略是 warn-and-skip：构建永远不会因为一个坏 hook 失败。`strict: true`（给 CI 用）则把配置错误和节点失败变成构建失败。
+
+## 开发 hook（调试模式）
+
+两个工具回答"我的 hook 在这个 stage 到底收到什么"：
+
+**`hexo pipeline --dry-run source/_posts/x.md`**——对单个文件跑 `before_post_render` 链，逐 node 打印效果（跳过 / 无变化 / 变更行级 diff / 失败），不生成任何东西。
+
+**tap（管线抽头）**——在真实 `hexo generate` / `hexo s` 过程中，把每个 stage 流过的文本落盘成快照：
+
+```yaml
+text_pipeline:
+  tap:
+    enable: true
+    match: my-post        # 强烈建议设置：只抓匹配的文章/页面
+    dir: .text-pipeline-tap
+```
+
+```
+.text-pipeline-tap/_posts_my-post.md/after_post_render.late/
+├── 00-input.txt              ← 挂在该 stage（late 挂点）的 hook 收到的就是这个
+├── 01-hook_my-hook.txt       ← 每个改动了文本的 node 改完后的样子
+└── …                         ← 最后一个文件即该挂点的最终输出
+```
+
+每个 stage 的每个挂点一个快照目录（`<stage>.early` / `<stage>.late`）。
+
+每轮渲染替换上一轮快照。tap 目录记得加进 `.gitignore`，正常构建时关掉 `enable`。
+
+## 内置 preset：`obsidian`
+
+把 Obsidian Flavored Markdown 编译为 Hexo 友好输出。`presets: [obsidian]` 启用。
+
+| Node | 语法 | 默认 | 行为 |
+|------|------|------|------|
+| `comment` | `%%行内%%`、跨行 `%% … %%` | 开 | 渲染前剥离（代码内为字面量） |
+| `embed` | `![[图片.png\|300]]`、`![[笔记]]` | 开 | 图片 → markdown 图片 / `<img width>`（`asset_prefix` 配置）；可解析的笔记嵌入 → 链接；其他原样保留 |
+| `wikilink` | `[[目标#锚点\|别名]]`、`[[#标题]]` | 开 | 重写为文章永久链接（`abbrlink` 优先，回退 `post.path`）；同页标题 → `#锚点`；块引用锚点（`#^id`）降级为文章链接 |
+| `highlight` | `==文本==` | 开 | `<mark>文本</mark>` |
+| `blockid` | 行尾 `^block-id` | 开 | 剥离（Obsidian 阅读视图里同样不可见） |
+| `mdlink` | HTML 里残留的 `.md` 链接 | 开 | 兜底重写为文章永久链接 |
+| `mermaid` | ` ```mermaid ` 围栏块 | 开 | 换成 `<pre class="mermaid">` 绕开语法高亮；按需注入懒加载 CDN 脚本 |
+| `callout` | `> [!type] 标题` | **关** | `<div class="callout callout-type">`；主流渲染器/主题已多自带支持，所以默认关 |
+
+```yaml
+presets:
+  - name: obsidian
+    config:
+      domain_prefix: ''                  # wikilink/mdlink/embed 的链接前缀
+      callout: { enable: true }          # 按需打开
+      embed: { asset_prefix: /images }   # 嵌入图片路径的前缀
+      mermaid: { theme: dark, priority: 15 }   # 任意 node：子配置 + priority 覆盖
+```
+
+## 安装
+
+```bash
+npm install hexo-text-pipeline --save
+```
+
+## 完整配置参考
+
+```yaml
+text_pipeline:
+  enable: true       # 总开关
+  debug: false       # 详细日志
+  strict: false      # 配置错误 / 节点失败让构建失败（CI 用）
+  inject_css: true   # node 的默认样式（如 callout）
+  inject_js: true    # node 的前端脚本（如 mermaid 加载器）
+  presets: []        # 内置名 | npm 包 | ./本地路径 | { name, config }
+  hooks: []          # { script | command, stage, slot, priority, name, timeout, match, enable }
+  plugins_dir: text-pipeline   # 单文件插件目录；false 关闭自动发现
+  plugins: {}        # 按插件名覆盖：{ <name>: { enable, slot, priority, ...其余进 ctx.config } }
+  tap:               # 调试模式：落盘每个 stage 的文本快照（见"开发 hook"）
+    enable: false
+    match: ''
+    dir: .text-pipeline-tap
+```
+
+## 开发
+
+零运行时依赖，Node >= 16。
+
+```bash
+npm test   # node --test
+```
+
+- **单文件插件（写插件从这里开始）**：[docs/PLUGINS.zh-CN.md](docs/PLUGINS.zh-CN.md)
+- Hooks 接口文档（stage 输入、ctx 字段、调试工作流）：[docs/HOOKS-API.zh-CN.md](docs/HOOKS-API.zh-CN.md)
+- 架构、stage 表、node 契约：[docs/ARCHITECTURE.zh-CN.md](docs/ARCHITECTURE.zh-CN.md)
+- 扩展指南：hook vs preset node vs 新 preset：[docs/EXTENDING.zh-CN.md](docs/EXTENDING.zh-CN.md)
+
+## 许可证
+
+MIT

package/index.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const engine = require('./lib/core/engine');
+
+function register(hexo) {
+  engine.register(hexo);
+}
+
+const runtimeHexo =
+  (typeof globalThis !== 'undefined' && globalThis.hexo) ||
+  (typeof hexo !== 'undefined' ? hexo : undefined);
+if (runtimeHexo) {
+  register(runtimeHexo);
+}
+
+module.exports = register;

package/lib/core/api.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const { STAGES } = require('./stages');
+const { resolvePlacement, resolveConvert, DEFAULT_PRIORITY } = require('./node-contract');
+const guard = require('./markdown-guard');
+
+/**
+ * 中央 node 注册表。engine 在 filter 执行时懒查询，所以注册可以发生在任何时刻
+ * （配置加载、preset 加载、其他插件经 hexo.textPipeline.register 程序化注册）。
+ *
+ * node 统一契约（唯一接口）：
+ * {
+ *   name,                       // 唯一标识；preset 的 node 自动带 '<preset>:' 前缀
+ *   stage,                      // stages.js 表里的键，默认 before_post_render
+ *   slot: 'early' | 'late',     // 挂点：early 在 hexo 内置/其他插件之前，late 在其之后
+ *                               // 默认值见 node-contract.js 的 SLOT_DEFAULTS（preset early，hook/api late）
+ *   priority: 10,               // 同挂点内小者先跑，同级按注册顺序
+ *   test(text),                 // 可选，廉价预判；match（正则）是它的声明式写法
+ *   convert(text, ctx),         // 纯函数：文本进、文本出；replace 规则表是它的声明式写法
+ *                               // （[[RegExp, 替换], ...]，markdown 阶段自动套 markdown-guard）
+ *   css, js,                    // 可选，默认样式/前端脚本
+ *   config, presetConfig,       // 可选；存在时原样出现在 ctx 上（hook 没有，ctx 上也不会有）
+ *   origin,                     // 'preset:<name>' | 'hook:command' | 'hook:script' | 'api'
+ * }
+ *
+ * 放置字段的默认值与校验统一在 node-contract.js——register 与 config hooks /
+ * preset 加载共享同一套规则。
+ */
+function createRegistry() {
+  const entries = [];
+  let seq = 0;
+
+  return {
+    add(node) {
+      entries.push({ node, seq: (seq += 1) });
+    },
+    // slot 省略时返回该 stage 全部 node（doctor 用）；指定时只返回该挂点的
+    forStage(stage, slot) {
+      return entries
+        .filter((entry) => entry.node.stage === stage && (!slot || (entry.node.slot || 'early') === slot))
+        .sort((a, b) => {
+          const pa = Number.isFinite(a.node.priority) ? a.node.priority : DEFAULT_PRIORITY;
+          const pb = Number.isFinite(b.node.priority) ? b.node.priority : DEFAULT_PRIORITY;
+          return pa - pb || a.seq - b.seq;
+        })
+        .map((entry) => entry.node);
+    },
+    all() {
+      return entries.map((entry) => entry.node);
+    }
+  };
+}
+
+/**
+ * 暴露为 hexo.textPipeline 的程序化 API：其他插件/脚本也能往管线挂 node。
+ * utils 给 script hook 用（如在 markdown 阶段跳过代码块）。
+ */
+function createPublicApi(registry, { onRegister, log } = {}) {
+  return {
+    stages: Object.keys(STAGES),
+    utils: {
+      replaceOutsideCode: guard.replaceOutsideCode,
+      replaceOutsideInlineCode: guard.replaceOutsideInlineCode,
+      segmentInlineCode: guard.segmentInlineCode
+    },
+    register(node) {
+      if (!node || typeof node.name !== 'string' || !node.name) {
+        throw new TypeError('textPipeline.register expects { name, stage, convert(text, ctx) | replace }');
+      }
+      const resolved = resolvePlacement(node, 'api');
+      if (resolved.error) {
+        throw new TypeError('textPipeline.register: ' + resolved.error);
+      }
+      const converted = resolveConvert(Object.assign({}, node, { stage: resolved.placement.stage }));
+      if (converted.error) {
+        throw new TypeError('textPipeline.register: node "' + node.name + '" ' + converted.error);
+      }
+      const wrapped = Object.assign({ origin: 'api' }, node, {
+        stage: resolved.placement.stage,
+        slot: resolved.placement.slot,
+        priority: resolved.placement.priority,
+        convert: converted.convert
+      });
+      if (typeof wrapped.test !== 'function' && resolved.placement.test) {
+        wrapped.test = resolved.placement.test;
+      }
+      // 与启动期 checkNodes 同一条规则：重名不拦截，但要告警（日志/tap/doctor 里分不清）
+      if (log && registry.all().some((existing) => existing.name === wrapped.name)) {
+        log.warn('duplicate node name "' + wrapped.name + '" — both will run; rename one to tell them apart in logs');
+      }
+      registry.add(wrapped);
+      if (typeof onRegister === 'function') onRegister(wrapped);
+      return wrapped;
+    }
+  };
+}
+
+module.exports = {
+  createRegistry,
+  createPublicApi,
+  DEFAULT_PRIORITY
+};

package/lib/core/checker/runtime.js

@@ -0,0 +1,71 @@
+'use strict';
+
+const FAILURE_TRIP_THRESHOLD = 3;
+const EXPLOSION_RATIO = 20;
+const EXPLOSION_MIN_BYTES = 64 * 1024;
+
+/**
+ * 运行期防护（兜底第二道防线）。每个 node 的每次执行都经过这里：
+ *
+ * - 硬防护：抛错 / 返回非字符串 → 丢弃该 node 的输出，原文继续流向下一环；
+ *   strict 模式下改为抛出，让构建失败（给 CI 用）。
+ * - 熔断：同一 node 连续失败 FAILURE_TRIP_THRESHOLD 次后整轮禁用，
+ *   不再为每篇文章刷一遍相同的错误日志。
+ * - 软告警（不拦截，输出仍被采纳）：输入非空但输出被清空；输出体积异常膨胀。
+ *   这两种都可能是正常行为（如注释剥离/资源内联），所以只提醒。
+ */
+function createRuntimeGuard({ strict } = {}) {
+  const failures = new Map(); // node -> consecutive failure count
+  const tripped = new Set();
+
+  return {
+    run(node, text, ctx) {
+      if (tripped.has(node)) {
+        return text;
+      }
+
+      let output;
+      try {
+        output = node.convert(text, ctx);
+        if (typeof output !== 'string') {
+          throw new Error('returned ' + typeof output + ' instead of a string');
+        }
+      } catch (err) {
+        if (strict) {
+          throw new Error('[' + node.name + '] ' + (err && err.message));
+        }
+        const count = (failures.get(node) || 0) + 1;
+        failures.set(node, count);
+        ctx.log.warn(ctx.stage + ' failed, skipped: ' + (err && err.message));
+        if (count >= FAILURE_TRIP_THRESHOLD) {
+          tripped.add(node);
+          ctx.log.warn('disabled for the rest of this run after ' + count + ' consecutive failures');
+        }
+        return text;
+      }
+
+      failures.set(node, 0);
+
+      if (text.length > 0 && output.length === 0) {
+        ctx.log.warn(ctx.stage + ' produced empty output from non-empty input (accepted — verify this is intended)');
+      } else if (output.length > EXPLOSION_MIN_BYTES && output.length > text.length * EXPLOSION_RATIO) {
+        ctx.log.warn(
+          ctx.stage + ' output grew ' + Math.round(output.length / Math.max(text.length, 1)) + 'x (' + output.length + ' bytes) — verify this is intended'
+        );
+      }
+
+      return output;
+    },
+    isTripped(node) {
+      return tripped.has(node);
+    },
+    // 每轮 generate 开始时由 engine 调用：hexo server 长进程下，
+    // 上一轮被熔断的 node 在新一轮重新获得机会（脚本可能已被修好——即改即用）
+    reset() {
+      failures.clear();
+      tripped.clear();
+    }
+  };
+}
+
+module.exports = { createRuntimeGuard, FAILURE_TRIP_THRESHOLD };