来源：halo-kb/插件选型调研.md（整篇）（原文 29071 字符）

Halo 插件选型调研 — AI 个人技术知识库

调研对象：Halo 2.x 插件生态 目标实例：http://<内网IP>:28090（站点「俗世客的思行小筑」） 调研方式：官方应用市场条目、GitHub 仓库 plugin.yaml manifest、GitHub Releases API、实例匿名端点实测

0. 证据来源与标注约定

本文严格区分两类内容：

0.1 目标实例的版本与已装插件（实测）

实测方式（匿名可访问，无需认证）：

curl.exe -s --noproxy "*" -m 12 http://<内网IP>:28090/
curl.exe -s --noproxy "*" -m 8  http://<内网IP>:28090/actuator/health

实例版本：Halo 2.26.1【官方来源】

证据是首页 HTML 中的生成器标记（原文片段）：

<meta name="generator" content="Halo 2.26.1"/>

实例当前已启用的插件（从首页 HTML 里被注入的前台资源直接读出，含版本号）：

当前主题：Ethereal v1.2.4【官方来源】（HTML 中 bannerVersion = "1.2.4"）

说明：这 4 个插件是实例上已经在跑的，因此「插件名 + 能在 Halo 2.26.1 上运行」这一点属于实测事实，而非文档推断。

插件清单的完整列表需要认证：Halo 的插件列表接口（Console API）需登录，匿名端点拿不到完整清单。上表只能反映"随前台页面注入资源"的插件，不含纯后台插件（如 AI Foundation、智阅、MiniDocs、项目集这类无前台注入的插件不会出现在这里）。

1. 目标插件核实表

用户点名的四类插件，其真实 metadata.name 与俗称差异较大，详见下表。

关键结论：整条链路的版本门槛由 AI Foundation 决定。 AI Foundation 要求 >=2.26.0，是本组四项中要求最高的；MiniDocs 同样要求 >=2.26.0。当前实例为 2.26.1，满足全部四项要求。

2. 各插件详情

2.1 AI Foundation（AI 基座）

这是用户所说"AI Foundation"的真实插件，名字与俗称完全一致。

功能定位【官方来源】：Halo 官方 AI 能力平台，统一接入主流大模型，为插件生态提供文本生成、嵌入向量、工具调用等能力。它本身不是一个面向访客的聊天界面，而是给其他插件调用的底座。

内置 AI 提供商【官方来源，市场页与 README 略有出入，以 README（更新更全）为准】： OpenAI、OpenRouter、DeepSeek、月之暗面 Kimi、硅基流动（SiliconFlow）、阿里云百炼、豆包、文心一言、智谱开放平台、Ollama、OpenAI 兼容（OpenAI-like）、AIHubMix、Gitee 模力方舟、MiniMax、Xiaomi MiMo。

市场页列出的提供商较少（未列 OpenRouter、阿里云百炼等），说明市场页描述滞后于仓库 README。选型时以插件内实际可选项为准。

关键配置项【官方来源，README「功能特性」】：

安装方式：

1. 应用市场一键安装（推荐）【官方来源，市场页「安装到 Halo」三方式】：
• 方式一：在市场页填入本站地址 → 跳转到本站后台应用市场 → 点卡片安装
• 方式二：后台 Console →「应用市场」搜索 AI Foundation 安装
• 方式三：点「手动下载」拿 jar，在 Console 上传
2. 后台上传 jar【官方来源】：Console → 插件管理 → 安装插件 → 上传 plugin-ai-foundation-1.1.0.jar
3. 官方 CLI【官方来源，语法见 §5.3】：halo plugin install --app-id app-acslk9nu

依赖关系：ai-foundation 是被依赖方，它自身不依赖其他插件。它是整组插件的底座。

⚠️ 升级风险【官方来源，v1.1.0 Release 说明】：v1.1.0 把最低支持 Halo 版本调整为 2.26。如果你的站点低于 2.26.0，只能用 1.0.1 及更早版本 —— 而智阅 4.x 要求 Halo >=2.25.0 且需要 AI Foundation，因此实际最低门槛是 Halo 2.26.0。

2.2 AI 助手 → 真实插件名是「智阅全能AI助手」

这是本次调研最关键的纠偏：用户所说的"AI 助手"，在 Halo 生态里最匹配的真实插件是 智阅全能AI助手，其 metadata.name 为 summaraidGPT（既不是 ai-assistant，也不是 plugin-ai-assistant）。

判断依据【官方来源】：市场条目标题即「智阅全能AI助手」，描述为"面向 Halo 的一站式 AI 内容与站点助手"，功能覆盖用户列出的全部要点：编辑器内 AI 辅助创作（摘要/写作/润色/标题/标签）、RAG 知识库、AI 问答、前台助手、站内检索。

依赖关系（重点，权威证据）

manifest 中显式声明了对 ai-foundation 的依赖：

  pluginDependencies:
    ai-foundation?: "*"
  annotations:
    "store.halo.run/recommended-apps": '["app-acslk9nu"]'

【官方来源】要点解读：

• ai-foundation?: "*" —— 依赖 AI Foundation，? 后缀表示可选依赖（不装插件也能启用，但 AI 功能不可用）。
• 注解 recommended-apps 指向 app-acslk9nu，正是 AI Foundation 的市场 app-id，形成交叉印证。
• 代码层面同样有证据：仓库中存在 service/AiFoundationAiService.java 与降级实现 service/impl/UnavailableAiFoundationAiService.java —— 后者即"AI Foundation 不可用"时的兜底，属【推断】（我依据文件名与命名惯例判断，未读其实现）。

配置文档给出了更强的表述【官方来源，docs/configuration/ai-settings.md 原文】：

请先安装并启用 Halo AI Foundation，并在 AI 基座插件中配置可用模型。本插件会通过 AI 基座调用模型，不直接维护模型 API Key。

结论：智阅不自己存 API Key，模型一律经 AI Foundation 调用。没有 AI Foundation，智阅的 AI 能力等于不可用。

关键配置项【官方来源，docs/configuration/ 目录下的配置文档】

配置组 basic（AI 设置）：

访问模式取值【官方来源】：

配置组 rag（知识库设置）—— 这是决定 RAG 成败的一组：

注意：没有"相似度阈值"这一配置项【官方来源】。召回控制靠 vectorTopK / keywordTopK / rerankTopN 三个数量参数完成，不存在相似度分数阈值开关。用户预期的"相似度阈值"在本插件中不存在，这是需要修正的预期。

关于"脑图"【未确认】：官方市场描述与 README 均未提及"脑图"功能。仓库中确实存在 ui/src/components/article-reading/InsightGraphPreview.vue（洞察图预览）与 ui/src/views/ArticleReadingGraphView.vue（文章阅读图谱视图）两个文件（文件名是事实），但其功能是否等同用户所指的"脑图"未确认。请勿按"有脑图"来做选型决策。

安装方式：

1. 应用市场一键安装（推荐）：后台 Console →「应用市场」搜索「智阅全能AI助手」安装
2. 后台上传 jar：Console → 插件管理 → 安装插件 → 上传 plugin-summaraidGPT-4.0.5.jar
3. 官方 CLI【官方来源，语法与 app-id 见 §5.3】：halo plugin install --app-id <本插件的 app-id>

v4.0.5 修复要点【官方来源，Release 说明】：修复新版 Halo / Lucene 10.5 环境下 RAG 重建索引与增量写入报 This postings format may not be used for writing 的问题；保留最高 4096 维向量支持。若站点跑在较新 Halo 上，务必用 4.0.5 或更高版本。

2.3 MiniDocs → 真实插件名 halo-plugin-minidocs，显示名「知识库」

注意：plugin.yaml 里的 version: 1.0.1 不是发布版本号，文件内注释明确写着"打包时由 build.gradle 的 version 自动覆盖（devtools 内置同步），请改 build.gradle 而非此处"。不要把 1.0.1 当作最新版本。

功能定位【官方来源，README】：轻量知识库插件，多知识库管理、树形文档架构、原生 Markdown 创作、分类标签与权限管控，并将内容通过公开接口与 Finder 暴露给第三方主题。

关键配置项【官方来源，README】：

来源：src/main/resources/extensions/settings.yaml（仅 basic 一组，元数据名 halo-plugin-minidocs-settings）

⚠️ 代码兜底与 yaml 默认相反（需注意的细节）：BasicSetting.java 中 anonymousReadEnabled() 的实现是 allowAnonymousRead == null || allowAnonymousRead，即值为 null 时返回 true，而 settings.yaml 里的默认值是 false。【推断】正常安装后以 yaml 的 false 为准（关闭匿名阅读）；仅当配置为空/未初始化时，Java 兜底才是"允许"。allowDocExport 与 showStats 的兜底均为 true，与 yaml 一致。选型时请以插件设置页实际显示为准。

权限模型【官方来源】：两层叠加 —— Halo 角色模板（role-template-minidocs-view 知识库查看 / role-template-minidocs-manage 知识库管理 / 隐藏的匿名角色）决定"能否在 Console 操作"，资源级访问控制（publicVisible 开关 + spec.members 成员列表）决定"能读哪个库"。私有库对非成员返回 403 或空。

主题集成【官方来源】：提供 Finder API minidocsFinder（listKnowledgeBases / getKnowledgeBase / listDocs / getDoc / getDocTree / getDocBySlug）与匿名公共 REST API。

安装方式【官方来源，README「安装使用」】：

1. 应用市场一键安装：后台「应用市场」搜索 MiniDocs 安装
2. 后台上传 jar：从 GitHub Releases 下载 Assets 中的 JAR，在 Console 上传安装
3. 官方 CLI【官方来源，语法与 app-id 见 §5.3】：halo plugin install --app-id <本插件的 app-id>

附加能力【官方来源】：内置 minidocs-cli Agent Skill（npm 包 minidocs-cli，需 Node.js >= 22），可让 Claude Code / Codex 等智能体直接管理知识库与文档；CLI 用 Halo 个人访问令牌（PAT）或 Basic 认证。

2.4 项目集 → 真实插件名 portfolio

⚠️ 仓库改名，旧名仍在多处流通【官方来源，经 GitHub API 核实】：该仓库现已改名为 liuyiwuqing/halo-plugin-portfolio；旧地址 liuyiwuqing/plugin-portfolio 会 301 重定向到新名，因此旧链接仍可用。但市场条目的 openSource.repo、市场页「去提交 issue」链接、以及 1.0.0-beta1 的 Release 正文仍写旧名。克隆、查 Release、提 issue 时以 halo-plugin-portfolio 为准。

我方先在 plugin.yaml 中读到 spec.repo = liuyiwuqing/halo-plugin-portfolio，一度判定为"manifest 写错"，经 API 核实后确认为仓库改名而非笔误 —— 此处更正先前判断。

功能定位【官方来源，README】：统一管理和展示 GitHub、Gitee、产品、插件、工具等项目作品。支持草稿/已发布/已归档三态、多平台、多类型、技术栈与标签、推荐项目、默认页面 /projects 与 /projects/{slug}、Finder API projectFinder、编辑器项目卡片、Markdown 详情、RBAC、SEO meta。

关键配置项【官方来源：src/main/resources/extensions/settings.yaml，仅 general 一组，元数据名 plugin-portfolio-settings】：

⚠️ 字段名纠正：README 表格只给中文名，不给字段名。经读 settings.yaml 与 PortfolioSetting.java 确认，开关字段是 defaultPageEnabled，不存在 enableDefaultPage。按后者写配置会静默无效。

⚠️ 路由不一致【两个官方来源互相矛盾，按原样记录】：settings.yaml 中 defaultPageEnabled 的说明写的是 /portfolio 与 /portfolio/{slug}，而 README 写的是 /projects 与 /projects/{slug}。二者必有一处过时，启用前请在实例上实测实际注册的路由，不要照抄任何一方。

设置标识：settingName = plugin-portfolio-settings，配置映射 plugin-portfolio-configmap【官方来源，manifest】。

项目数据模型要点【官方来源】：title（≤120）、slug（≤80）必填；summary、content（Markdown）、cover、platform、type、techStacks、tags、repoUrl、demoUrl、docsUrl、priority、featured、status（DRAFT/PUBLISHED/ARCHIVED）可选。

安装方式【官方来源，README「安装」】：

1. 从 Release 安装（README 标注为推荐）：前往 Releases 下载最新 .jar → Console → 插件管理 → 安装插件 → 上传 jar → 启用
2. 从源码构建：git clone → ./gradlew build → 产物 build/libs/plugin-portfolio-*.jar → 控制台上传
3. 应用市场：条目见 https://blog.muyin.site/portfolio/halo-plugin-portfolio ；是否有官方市场 app-id 未确认

依赖关系：不依赖其他插件（manifest 中无 pluginDependencies）【官方来源】。

3. 补充推荐插件

3.1 已在目标实例上运行的 4 个（实测证据最强）

以下 4 个不是"推荐"而是"已经在跑"，版本号直接读自实例首页注入的资源路径，因此"插件真实存在 + 能在 Halo 2.26.1 上工作"是实测结论。

这 4 个都来自官方组织（halo-dev / halo-sigs），对技术知识库站点价值明确：搜索、评论、代码高亮、链接卡片。 editor-hyperlink-card 的版本与兼容范围未单独核实（子代理未覆盖该仓库），仅实例证据：1.9.2 正在 Halo 2.26.1 上运行。

3.2 补充推荐完整表（8 个，逐个核实）

以下 8 个均逐个读取了仓库 src/main/resources/plugin.yaml（同时比对 main HEAD 与最后 release tag 两版），并用 GitHub Releases API 取版本与日期。【官方来源】

8 个仓库全部 archived:false、disabled:false，无一停止维护。

交叉验证（强证据）：halo-dev/halo 的 issue #10287（Halo 2.26.1）与 #10277（2.26.0）中用户粘贴的已启用插件清单，其版本号与本表独立取得的结果完全一致（Sitemap 1.3.0 / Meilisearch 1.2.0 / Shiki 1.5.1 / KaTeX 3.0.0 / 内容助手 1.8.0 / 内容块 1.7.0 / 评论组件 3.2.2 / 搜索组件 1.7.1）。这同时说明本表插件在 2.26.x 上有真实运行案例。

选型要点（含必须成对安装的组合）

⚠️ 搜索组件 自 2025-09-09 起未发过新 Release（最近提交 2025-11-20）。它未归档、未停止维护，但如果你依赖 Meilisearch 全文搜索，需注意这一对组合中 UI 侧更新较慢。

⚠️ 两个 app-id 的来源不同：其余 7 个的 app-id 来自仓库内的 store.halo.run/app-id 注解，而 meilisearch 的 app-7mb5szjt 来自仓库 homepage 字段与 README（其 plugin.yaml 没有该注解）。子代理未逐个 HTTP 验证市场页面可访问性。

3.3 一个重要的生态事实：awesome-halo 是权威插件索引

官方维护的插件索引：https://github.com/halo-sigs/awesome-halo

本次调研中，plugin-sitemap、plugin-search-widget、plugin-meilisearch、plugin-shiki、plugin-comment-widget、plugin-katex、plugin-hybrid-edit-block 等多个插件都是从这份索引里交叉验证存在的【官方来源】。建议把它作为后续选型的唯一入口，避免搜到已废弃的同名插件。

该索引中与"技术知识库"直接相关的官方插件【官方来源，索引原文】：

⚠️ 已停止维护的同类插件（索引中明确标注）【官方来源】：Rainsheep/halo-plugin-meilisearch 标注"已停止维护，可以使用 halo-sigs/plugin-meilisearch 代替"。两个仓库名高度相似，装错会拿到无维护的老版本。

4. 依赖关系图

                    ┌─────────────────────────────┐
                    │  Halo 2.26.1（目标实例版本）  │
                    └──────────────┬──────────────┘
                                   │ 运行时平台
        ┌──────────────────────────┼──────────────────────────┐
        │                          │                          │
        ▼                          ▼                          ▼
┌───────────────┐        ┌──────────────────┐        ┌────────────────┐
│ ai-foundation │◄───────│  summaraidGPT    │        │ halo-plugin-   │
│ (AI Foundation)│  依赖  │ (智阅全能AI助手)  │        │ minidocs       │
│ 需 Halo≥2.26.0│        │ 需 Halo≥2.25.0   │        │ 需 Halo≥2.26.0 │
└───────┬───────┘        └──────────────────┘        └────────────────┘
        │ 提供 Provider / 语言模型 /
        │ Embedding / Rerank 能力
        │
        │  （被依赖，自身无依赖）
        │
        ▼
   其他消费方插件（官方 README 列出的「已接入插件」）
   ├── AI 回评            app-mo5tivjt
   ├── Live2d 看板娘      app-oPNFQ
   ├── 评论组件 Next      app-p8xona4f
   ├── 轻言               app-cmisffbv
   └── 链接管理           app-hfbQg

独立无依赖：
   portfolio（项目集，需 Halo≥2.24.0）

依赖关系要点：

1. ai-foundation 是唯一的底座，被 summaraidGPT 依赖（manifest 的 pluginDependencies.ai-foundation?: "*"，? 表示可选依赖）。
2. portfolio 与 halo-plugin-minidocs 互不依赖，也不依赖 AI Foundation —— 它们可以独立安装使用。
3. 智阅不自己存 API Key，模型一律经 AI Foundation 调用【官方来源，ai-settings.md 原文】。
4. ai-foundation 在 README 中列出的"已接入插件"共 6 个（含智阅），说明它是生态级底座而非智阅专用组件。

5. 安装顺序建议

5.1 前置检查（必须先做）

# 确认实例版本；本报告实测为 Halo 2.26.1
curl.exe -s --noproxy "*" -m 12 http://<内网IP>:28090/ | Select-String 'generator'

版本门槛结论：AI Foundation 与 MiniDocs 均要求 >=2.26.0。若站点低于 2.26.0，这两项都装不了，必须先升级 Halo。当前实例 2.26.1 满足。

5.2 建议顺序

为什么底座必须先行：智阅的 vectorModelSetting.embeddingModelName 只是指向一个在 AI Foundation 里已配置的模型名，不是模型本身。若先装智阅再配底座，中途所有 AI 功能都会走 UnavailableAiFoundationAiService 降级路径（【推断】，依据是该降级类存在于源码树中）。

5.3 安装方式速查

官方 CLI 安装/管理插件的确认语法【官方来源：halo-dev/cli 仓库 skills/halo-cli-operations/SKILL.md】：

CLI 本身来自 npm 包 @halo-dev/cli（安装后二进制名 halo，要求 Node.js >= 22）：

npm install -g @halo-dev/cli

# 先登录（Bearer 令牌或 Basic 认证）
halo auth login --profile local --url http://<内网IP>:28090 --auth-type bearer --token <你的令牌>

# 插件安装 —— 三种来源
halo plugin install --file ./plugin.jar                              # 本地 jar
halo plugin install --url https://example.com/plugin.jar             # 远程 URL
halo plugin install --app-id app-acslk9nu                            # 直接按应用市场 app-id 安装

# 其他常用
halo plugin list
halo plugin get <name>
halo plugin enable <name>
halo plugin upgrade <name> --online
halo plugin upgrade --all --online --yes

可直接套用于本报告（用上表已确认的 app-id）：

CLI 注意事项【官方来源，同上技能文档原文】：plugin install --url 在远程主机不是 www.halo.run 时会要求确认，自动化场景加 --yes；disable / upgrade / uninstall 属变更性操作，执行前先用 list 或 get 确认目标。

⚠️ 任务提示中写的 halo plugin install 语法正确，但仓库 README 只列出 plugin 命令组、未给子命令 —— 上述语法来自 CLI 随包发布的 Agent Skill 文档，可信度等同官方。

6. 未确认项清单

以下内容查过但未获得可靠来源，一律标注未确认，未填入任何猜测值。

6.1 已确认不存在或与预期不符的事项（重要）

⚠️ 一条通用教训：plugin.yaml 里的 version 字段不可当作发布版本号 —— MiniDocs 写 1.0.1（实际 1.0.2）、sitemap tag 版写 1.0.2（tag 名 v1.3.0）。判断版本一律以 GitHub Releases 的 tag 或应用市场条目为准。

附录：本次调研使用的主要来源

来源：halo-kb/实例现状基线.md → ## B) 已装插件与主题（原文 5184 字符）

B) 已装插件与主题

B.1 当前启用的主题

仅 1 个主题被 Halo 注册：Ethereal

# MCP 工具
mcp__halo__halo_list_theme_setting_groups

{"themeName":"Ethereal","themeDisplayName":"Ethereal","themeVersion":"1.2.4",
 "groups":[{"name":"layout","label":"布局设置"},
           {"name":"style","label":"样式设置"},
           {"name":"sidebar","label":"侧边栏"},
           {"name":"post","label":"文章"},
           {"name":"extendPages","label":"扩展页面"},
           {"name":"footer","label":"页脚"},
           {"name":"links","label":"友情链接"},
           {"name":"external_link","label":"外链跳转"},
           {"name":"performance","label":"速度优化"},
           {"name":"auth","label":"认证"}]}

主题元信息（themes/Ethereal/theme.yaml）：

可配置项：10 个设置组（见上），模板文件 27 个，settings.yaml 达 99 KB（配置项极多）。 自定义页面模板 4 个：朋友圈（friends.html）、心愿便签（wishes.html）、时间轴（timeline.html）、技能（skills.html）。

⚠️ 主题配置目前基本是「出厂演示值」（从首页 HTML 内联的主题配置读出）：

• 头像仍是 /themes/Ethereal/assets/images/demo-avatar.png
• 侧边栏昵称是 NanNan，简介是 Lorem ipsum dolor sit amet...
• 站点页脚署名是 「俗世客的思行小筑」（这一项已改成真实值）
• banner 标题 Hello,Ethereal!，副标题「生而为人，爱而无畏 / 心之所向，素履以往 / 保持热爱，奔赴山海」
• 公告栏 enable: false，欢迎弹窗 enable: false，ICP 备案号为空

⚠️ 磁盘上还有一个 themes/theme-earth/ 目录（Earth 1.15.3），但 Halo 并未注册它 —— 数据库 kind=Theme 的记录只有 1 条（Ethereal）。它属于文件系统残留，见 C.3。

B.2 已安装插件清单（20 个）

取证方式：两条独立通道互证，结果完全一致。

1. 文件侧：/vol1/1000/docker/halo/halo2/plugins/ 下 20 个 jar 内的 plugin.yaml（displayName / version / author）
• 同目录 disabled.txt（实例级禁用名单）
2. 数据库侧：extensions 表中 kind=Plugin 的 spec.enabled 字段

# 数据库侧权威查询（只读 SELECT）
docker exec PostgreSQL psql -U halo -d halo -tAc \
  "select name || ' | enabled=' || coalesce(convert_from(data,'UTF8')::jsonb->'spec'->>'enabled','?')
   from extensions where convert_from(data,'UTF8')::jsonb->>'kind'='Plugin' order by 1;"

✅ 已启用（10 个）

⛔ 已安装但被禁用（10 个）

禁用名单原始文件（plugins/disabled.txt，153 B，mtime 2026-09-13 19:39）：

backup-improved
PluginContactForm
plugin-docsme
plugin-maxkb
plugin-ldap-login
restricted-reading
plugin-social-login
seo-tools
ai-assistant
aimodel-hub

（10 行，与数据库 enabled=false 的 10 条逐条对应，无差异）

B.3 任务点名四个插件的查证结论

B.4 AI Foundation 已完成的配置（后续工作的既定起点）

数据库 extensions 中已有的 AI 资源（只读查出）：

kind=AiProvider  1 条
  /registry/aifoundation.halo.run/aiproviders/deepseek-57bttiwz
  spec: {"providerType":"deepseek","displayName":"深度求索 DeepSeek","enabled":true,
         "apiKeySecretName":"<Secret 引用>"}
  status: {"phase":"OK","message":"Connectivity check passed","lastCheckedAt":"2026-09-13T11:38:39Z"}

kind=AiModel     2 条
  deepseek-57bttiwz / deepseek-flash    (language, enabled=true, 支持 streaming/structured-output/tool-call/reasoning)
  deepseek-57bttiwz / deepseek-v4-pro   (language, enabled=true, 同上)

即：DeepSeek 供应商已接入且连通性检查通过，已注册 2 个语言模型。 （API Key 存放于 Secret 资源 <Secret 引用>，本次未读取其内容。）

来源：halo-kb/AI能力验证.md → ## 一页纸结论（原文 2605 字符）

一页纸结论

一句话：AI Foundation 1.1.0 是一个「模型接入 + 调用 SDK + 控制台测试台」的底座，它不含知识库、不含向量库、不含分块、不含前台页面、不含编辑器集成，且当前实例连 embedding 模型都没有配。任务给出的「只有控制台管理界面 + Java SDK + RAG 测试台，不含访客前台问答页」这一调研结论，经本次独立实测成立。