爱库录 目录即站点，文件即文章

后端能力插件协议-升级建议

2026-09-14 · 返回列表

AiKlog 后端能力插件协议 — 升级建议

写给 AiKlog 开发方。背景：AiKBox / AiKlog / qiuzhi（求职垂直站）共用同一知识库内核，出口与面对方向不同；功能不靠"买壳"实现，靠"买插件"实现——AiKBox 装博客插件即得 AiKlog，AiKlog 装采集/频道插件即得 qiuzhi 类站点，跨壳功能通过 SaaS 后端购买对应插件包获得。 这一构想成立的技术前提：插件协议必须覆盖"后端能力插件"，不只是前端挂载点。本文档盘点现状、指出问题、给出必须走后端协议的能力清单与形态建议。

一、现状核对（0.1.8 代码实测）

1.1 协议扩展点目前全部是前端挂载点

blog_plugins.go / blogPlugins/index.js / BlogPluginSlot.vue：

| 扩展点 | 类型 | 现状 | |---|---|---| | post_bottom（文章页正文下） | 前端挂载点 | 评论 / 相关推荐 / 文章元信息 | | sidebar（侧栏） | 前端挂载点 | 文章信息卡、归档、分类云 | | list_item（列表项） | 前端挂载点 | 标签徽章 | | head（HTML head） | 前端挂载点（预留） | SEO meta |

插件 = manifest（后端登记：mount_points / api_permissions / frontend_entry / min_core_version / enabled）+ 前端组件（前端注册表按 id 注册，启用即在挂载点渲染）。后端只负责登记与启用状态。

1.2 两类"能力"的现状归属

| 能力 | 当前实现 | 归属 | |---|---|---| | 评论 | 前端组件 + 后端评论核 API（读公开、写需登录） | 挂载点组件 + 后端数据 API | | RSS | GET /api/v1/blog/feed.xml 动态生成（公开白名单） | 后端原生内置（硬编码，非插件） | | Sitemap | blog_sitemap.go | 后端原生内置（硬编码，非插件） | | 主题 | zip 包 + manifest（kind=theme） | 前端包安装 |

结论：RSS / Sitemap 这类后端能力目前是硬编码内置，没有插件化出口；协议的扩展点全部在前端。这就是"后端能力插件化"要补的空白。

1.3 应用市场（0.1.8 已落地）

apps_market.go + docs/PLUGIN-MARKET.md v0.1：plugin/theme 两 kind、zip 包结构（manifest.json + dist/）、min_core_version 校验、frontend_entry 一致性、KV 按 plugin_id 隔离、不执行远程 JS eval。展示型插件的安装闭环已经成立——本协议升级只需在它之上扩展能力型插件的声明与接入形态。

二、问题清单（品牌收口补完）

0.1.1 品牌收口清了公开页与 schema，但 web/ 源码仍有多处 AiKmap 残留，其中 2 处用户可见、1 处是线上 title 的直接来源：

| 级别 | 位置 | 内容 | 处理 | |---|---|---|---| | P1-直接可见 | web/src/router/index.js:116 | document.title = ... · AiKmap | 这就是线上 title"博客 · AiKmap"的来源，改为站点配置的 siteName | | P1-直接可见 | web/src/blogPlugins/builtin/seoMeta.vue:20-21 | 默认 title/desc = 'AiKmap 博客' / '由 AiKmap 知识库发布的公开文章' | 改为站点配置默认值 | | P1-直接可见 | web/src/blogPlugins/builtin/tagBadges.vue:5 | 列表徽章"来源：AiKmap 知识库" | 改为"爱库录"或站点名 | | P1-管理端 | web/src/components/AppShell.vue:8,359 | 顶栏 <h1>AiKMap</h1>、搜索 placeholder"问 AiKMap…" | 改品牌名；搜索框文案可顺带优化 | | P2-标识符 | web/package.json / package-lock.json | "name": "aikmap-web" | 改 aiklog-web | | P2-标识符 | web/src/api/index.js:7-8,654 | TOKEN_KEY='aikmap_token'、AUTH_FLAG='aikmap_auth'、下载文件名 aikmap-export-* | key 改名需登录态迁移兼容（旧 key 读取后写新 key 再删），或保留旧 key 仅改显示层；下载文件名可直接改 | | P2-标识符 | web/src/stores/files.js:14,79 / reading.js:4 / theme.js:11 / AppShell.vue:685,700 | localStorage aikmap.viewmode/reading/theme/aiwidth | 同上：改名需兼容迁移；注释类（AikIcon.vue:35、editor/plugins.js:2、styles/*.css、themes/index.js:2,33、api/index.js:1）低优先可随手清 |

提醒：P2 标识符（localStorage key、package name）改动有兼容成本，建议"显示层先清 + key 迁移函数一次到位"，不要只清一半。线上站点记得重新构建部署（webdist 构建产物不入库，见审查 P3）。

三、必须走后端协议的能力清单（核心）

按"跨壳互买 / SaaS 后端购买"的构想，以下能力无法靠前端挂载点实现，必须后端协议化。按必要性与复杂度分级：

第一级：能力型插件（当前协议完全空白，是"跨壳互买"的关键）

| 能力 | 场景 | 必须后端协议的原因 | |---|---|---| | 采集器 Collector | qiuzhi 类垂直站的数据源（官办站点抓取、入库） | 定时调度、抓取模板（列表/详情解析）、幂等去重、把关/剔除、运行状态；全是后端重逻辑，前端无挂载点可表达 | | 频道/解读模板 Channel | 采集产物结构化（kind=job/bid/training：薪资/编制/截止时间元数据）、AI 解读模板 | 需要声明化"频道定义包"：kind 名称、字段 schema、AI 解读提示词、状态规则（进行中/已过期）——数据层能力 | | 通知/订阅接入器 Notifier | "订阅某个方向""岗位过期早知道"（已过期触动的推送） | 订阅存储 + 到期扫描 + 通知渠道适配（邮件/Webhook/微信）；触发在服务端，不是页面渲染 | | 外部服务桥接器 Bridge | WebDAV 同步、OnlyOffice 在线编辑、第三方 API 对接 | 需要后端代理/路由、鉴权透传、文件读写权限——不能在前端完成 | | 检索/向量管道增强 | rerank 精排、混合检索、多供应商 embedding（SaaS 后端"购买更好检索能力"） | 检索在服务端执行；供应商/模型切换、额度校验都要后端 |

第二级：已有后端内核、需"插件化出口"的能力

| 能力 | 现状 | 升级方向 | |---|---|---| | RSS | 后端内置（硬编码） | 拆成可安装后端插件：feed 内容范围、缓存策略、自定义字段（frontend_entry 留空即可） | | Sitemap | 后端内置（硬编码） | 同上，可并入"SEO 能力包" | | 评论 | 前端组件 + 后端核 API | 加事件钩子：新评论审核、通知、第三方评论服务替换（如走 Notifier） | | 主题配置持久化 | 前端包 + KV | 已有 KV 隔离基础 ✅，补"主题级配置 schema"（侧栏开关/封面/布局选项） |

第三级：平台级后端能力（跨所有壳，属内核而非插件）

| 能力 | 说明 | |---|---| | 博客目录强鉴权 | 博客目录在存储层隐藏/强告警（删除/移动需二次确认）、公开目录与私有目录隔离——安全底线，不做成插件 | | 多用户权限矩阵 | 谁是编辑/发布者/读者——用户体系功能，不做成插件 | | 数据导出/迁移 | 整站备份、博客迁移（他站 md 导入即建站）——平台管道 |

四、能力型插件的接入形态建议：连接器（Connector）模式

核心主张：能力型插件不"装进内核"，而是"以外部服务身份接入"。 理由：

  1. 与现状一致：qiuzhi 的采集器本来就是独立 Go 服务，通过服务令牌调用主系统白名单 API（GET files / POST doc / mkdir / DELETE）。这套已被验证（多轮实测）。
  2. 安全：安装 zip 内执行任意后端代码风险不可控；外部服务 + 令牌 + 白名单端点，权限可审计、可吊销。
  3. 技术栈自由：Go / Python / Node 都能写连接器，插件市场因此能吸引不同生态的开发者。
  4. SaaS 后端购买天然契合：付费能力插件 = 平台签发连接器令牌/授权码 + 能力开关；插件市场分发的是"连接器配置包 + 前端壳"，重逻辑在插件服务侧或 SaaS 侧。

4.1 manifest 扩展（在现有 zip 协议上加，向后兼容）

{
  "id": "qiuzhi-collector",
  "kind": "connector",
  "name": "蚌埠求职采集",
  "version": "0.1.0",
  "min_core_version": "0.2.0",
  "backend_capabilities": ["collector", "channel", "notifier"],
  "routes": ["/api/v1/connectors/qiuzhi/*"],
  "hooks": ["file.created", "post.published", "schedule.daily"],
  "tables": ["conn_qiuzhi_sources", "conn_qiuzhi_runs"],
  "kv_prefix": "conn_qiuzhi_",
  "auth": "connector_token",
  "price": 0
}

| 新增字段 | 说明 | |---|---| | kind: connector | 新应用类型（区别于 plugin/theme） | | backend_capabilities | 声明能力：collector / channel / notifier / bridge / retriever | | routes | 连接器自带 API 路由前缀（注册后反代/挂载到该前缀） | | hooks | 订阅的系统事件集（见 4.2） | | tables / kv_prefix | 数据隔离命名空间（表前缀 conn_<id>_，KV 前缀已有先例） | | auth | 连接器接入鉴权方式（平台签发令牌） |

4.2 事件集建议（复用现有 bus）

AiKlog 已继承内核 bus（server/internal/engine/bus）。建议能力插件可订阅的事件（按需扩展）：

| 事件 | 触发点 | 典型消费方 | |---|---|---| | file.created / file.updated | 文件入库/更新 | 采集器（幂等登记）、频道解读、通知器 | | file.deleted（软删） | 删除 | 采集器 tombstone（清掉的别回来） | | post.published / post.unpublished | 博客发布/下架 | RSS/SEO 刷新、通知器 | | schedule.*（cron 触发） | 定时 | 采集调度、到期扫描（"已过期触动"） | | plugin.installed / plugin.uninstalled | 市场安装/卸载 | 平台级联动（如卸载时清理 KV/路由） |

4.3 安全模型

  • 连接器安装需登录 + 平台签发令牌；令牌最小权限（仅声明的能力端点）
  • 路由前缀隔离：/api/v1/connectors/<id>/ 由内核统一挂载/反代，连接器不接触内核路由表
  • 数据隔离：表前缀 + KV 前缀 + 独立 schema 迁移文件（连接器自带迁移，卸载可回滚）
  • 保持现有红线：不执行远程 JS/Go eval；zip 安装仅解析 manifest + 注册配置，不落代码
  • 连接器令牌可吊销（设置页启停已具备入口形态）

4.4 与 SaaS 后端购买的关系

插件市场（应用中心）                平台 SaaS 后端
─────────────────                ─────────────────
免费连接器包：manifest 分发  →  免费
付费能力包：授权码/订阅      →  签发连接器令牌 + 能力开关
（采集额度/rerank/通知渠道）    （计费、额度、审计）

内核只认"令牌 + 能力声明"：令牌有效 → 连接器可接入并声明其能力；令牌过期/吊销 → 对应能力下线。内核不需要知道价格与套餐，计费全在 SaaS 侧——这是"免费壳 + 付费能力"能落地的关键解耦。

五、实施建议顺序

| 阶段 | 内容 | 产出 | |---|---|---| | 近期（0.2.x） | ① 品牌收口补完（第二节清单）② manifest 加 kind=connector + backend_capabilities 字段（仅登记与列表，先不执行） | 协议面就绪 | | 中期（0.3.x） | ③ 连接器接入骨架：令牌签发/吊销 + 路由前缀挂载 + hooks 事件订阅注册表 ④ 把 RSS/Sitemap 改造成首个"内置连接器"（吃自己的狗粮） | 能力型插件第一条通路 | | 后期（0.4+） | ⑤ 采集器/频道/通知器作为连接器样例开放 ⑥ 与平台 SaaS 联调：授权码→令牌→能力开关 | 跨壳互买闭环 |

六、一句话总结

展示型功能（评论/侧栏/归档/封面）用现有前端挂载点协议即可；能力型功能（采集/频道/通知/桥接/检索增强）必须走"连接器"后端协议——外部服务 + 令牌 + 事件订阅 + 数据命名空间，不进内核代码。 这是"一个内核 + 插件市场 = 全形态"成立的技术前提，也是 AiKlog 从"博客壳"走向"底座样板房"的协议级支撑。