从零开始开发一个 Hexo 插件：以 hexo-plugin-llmstxt 为例

random-pic-api

前言

在 AI 时代，越来越多的开发者开始使用 AI 编程助手来提升开发效率。为了让 AI 更好地理解和学习我们的技术文档，社区提出了 llms.txt 规范。本文将以开发一个生成 llms.txt 的 Hexo 插件为例，介绍 Hexo 插件开发的基本流程。

什么是 llms.txt？

背景

随着 ChatGPT、Claude 等大语言模型的普及，越来越多的开发者开始使用 AI 编程助手。但是这些 AI 助手在访问网站内容时，往往需要处理复杂的 HTML 结构，这不仅增加了处理成本，还可能影响理解的准确性。

llms.txt 规范

llms.txt 类似于 robots.txt，它是一个专门为 AI 准备的纯文本格式的站点内容索引。通过提供结构化的纯文本内容，可以帮助 AI 更好地理解和学习网站的内容。

主要特点：

  1. 纯文本格式，易于解析
  2. 包含文章的标题、描述和链接
  3. 可选包含完整的文章内容
  4. 支持 Markdown 格式

查看本站的 llmx.txt 和 llmx-full.txt

Hexo 插件开发基础

插件类型

Hexo 支持多种类型的插件：

  • Generator：用于生成静态文件
  • Renderer：用于渲染文件
  • Helper：用于辅助模板渲染
  • Deployer：用于部署
  • Processor：用于处理源文件
  • Tag：用于在文章中插入特定内容
  • Console：用于添加控制台命令

我们的 llms.txt 生成插件属于 Generator 类型。

基本结构

一个典型的 Hexo 插件目录结构如下：

1
2
3
4
5
.
├── index.js
├── package.json
├── README.md
└── LICENSE

插件命名规范

Hexo 插件的命名需要遵循以下规则：

  • 以 hexo- 开头
  • 全小写
  • 使用连字符（-）连接单词

实战：开发 hexo-plugin-llmstxt

1. 初始化项目

首先创建项目目录并初始化：

1
2
3
mkdir hexo-plugin-llmstxt
cd hexo-plugin-llmstxt
npm init

2. 编写 package.json

1
2
3
4
5
6
7
8
9
10
11
12
{
  "name": "hexo-plugin-llmstxt",
  "version": "1.0.0",
  "description": "Generate llms.txt for Hexo sites",
  "main": "index.js",
  "keywords": [
    "hexo",
    "llms",
    "ai"
  ],
  "dependencies": {}
}

3. 实现核心功能

在 index.js 中实现插件的核心功能：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
'use strict';

const fs = require('fs');
const path = require('path');

// 注册生成器
hexo.extend.generator.register('llms', function (locals) {
  // 获取配置
  const config = Object.assign({
    generate_llms_full: false,
    debug: false,
    postsHeader: hexo.config.title,
    description: hexo.config.description,
    sort: 'desc'
  }, hexo.config.llmstxt);

  // 生成文件内容
  // ...
});

4. 处理文章内容

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// 处理每篇文章
locals.posts.sort('date', sortOrder)
  .filter(post => post.published !== false)
  .forEach(post => {
    const {
      title,
      raw,
      description,
    } = post;

    // 移除 Front-matter
    const content = raw.replace(/^---[\s\S]+?---\n/, '').trim();
    
    // 生成链接和内容
    // ...
  });

5. 文件生成

1
2
3
4
5
6
7
8
9
// 写入文件
try {
  fs.writeFileSync(llmsFilePath, llmsContent);
  if (config.debug) {
    console.log('生成 llms.txt 成功');
  }
} catch (err) {
  console.error('写入文件时发生错误:', err);
}

开发过程中的注意事项

  1. 错误处理

    • 确保目录存在
    • 处理文件写入错误
    • 添加调试日志

  2. 配置处理

    • 提供默认值
    • 支持用户自定义
    • 配置项文档化

  3. 文件路径

    • 使用 path.join 处理路径
    • 考虑跨平台兼容性

  4. 性能优化

    • 避免重复操作
    • 合理使用内存

  5. 代码风格

    • 遵循 JavaScript 规范
    • 添加适当的注释
    • 保持代码整洁

测试和发布

本地测试

  1. 在本地 Hexo 项目中使用 npm link：

    1
    2
    3
    4
    cd hexo-plugin-llmstxt
    npm link
    cd /path/to/hexo/project
    npm link hexo-plugin-llmstxt

  2. 运行 Hexo 命令测试：

    1
    2
    hexo clean
    hexo generate

发布到 NPM

  1. 登录 NPM：

    1
    npm login

  2. 发布包：

    1
    npm publish

源码:

https://github.com/dong4j/hexo-plugin-llms

参考资料