技术

logbook 主题与 LogbookMCP 插件：这个博客的完整导览

2026 年 10 月 12 日 admin 1877 字 · 约 7 分钟暂无评论

这个博客由三样东西组成：Typecho 1.3、我自己写的主题 logbook、以及我自己写的插件 LogbookMCP。这篇把三者的分工、能力边界和接入方式一次讲清楚，篇幅控制在一屏能读完的程度——想看开发过程的坑，请看下一篇。

一、整体结构：两条互不干扰的链路

读者 / 搜索引擎 / AI 爬虫
        │
        ▼
   nginx ──► PHP-FPM ──► Typecho 核心 ──► MySQL
                │
                └── 主题 logbook（模板 / SEO 头 / 三个机器可读端点）

AI 客户端（DSH / Claude / Codex / Cursor …）
        │  stdio JSON-RPC
        ▼
   mcp/server.js ──► HTTPS + Bearer ──► /mcp-api ──► 插件 LogbookMCP ──► Typecho 核心 ──► MySQL

两条链路是解耦的：关掉插件，博客照常访问；换掉主题，MCP 照样能发文。主题只管「长什么样、机器怎么读」，插件只管「怎么被写」。

二、主题 logbook：它做了什么

设计目标很简单：文档风、双列、移动端可用、零构建步骤、零 CDN（所有 JS/CSS/字体都在站内，不引任何外部资源），不依赖前端框架。

能力	实现要点
深浅色切换	CSS 变量两套主题，`localStorage` 记忆；`<head>` 里的内联脚本在 CSS 之前定色，刷新不闪白
文章目录	服务端给正文的 `h2/h3` 补锚点 id，前端生成目录并做滚动高亮；没有小标题时整个目录盒不输出
代码高亮 + 复制	站内 `highlight.min.js`，代码块右上角带语言标签与一键复制（优先 `navigator.clipboard`，失败走兜底）
阅读时长	剥离标签后按「中日韩字符 ÷ 300 + 英文单词 ÷ 200」估算，最少 1 分钟，按文章缓存
封面图	自定义字段优先；留空时自动取正文第一张图；列表页 16:9 裁切，可以整体关掉
图片灯箱	用原生 `<dialog>` 实现，没有引入任何灯箱库；正文图片统一补 `loading="lazy"`
独立页面模板	归档页（按年分组）、友链页（读 `links` 字段渲染）、关于页（站点统计 + 联系方式）
评论	楼中楼、博主徽章、待审核提示、头像离线兜底；兼容第三方验证码插件
响应式	1080 / 860 / 520 三档断点，另有打印样式与 `prefers-reduced-motion` 降级；禁用 JS 时菜单静态展开
机器可读	每页唯一的 canonical / description / OG / Twitter / JSON-LD，加上 `robots.txt`、`sitemap.xml`、`llms.txt` 三个动态端点

发新文章不需要维护任何清单：RSS、sitemap、llms.txt、结构化数据都是实时拼装或现查数据库。草稿、加密文章、未发布内容不会进 sitemap。

三、后台能改什么

主题设置里有 20 项可调（站点标题描述、主色、侧栏开关、页脚、备案号、社交链接、SEO 总开关等）。除此之外，每篇内容还有 4 个自定义字段：

字段	位置	用途
`cover`	文章 + 页面	封面图，可直接上传、也可从本页附件里挑；留空自动取正文首图
`summary`	文章 + 页面	自定义摘要；独立页面会当作副标题显示
`hideToc`	文章 + 页面	这一篇不显示目录
`links`	仅友链页面	每行一条记录，用竖线分成三段，格式见下方

字段是「先发现、后使用」的：MCP 那边不写死字段名，AI 调用 blog_site_info 就能拿到当前主题声明了哪些字段——所以换主题不用改 MCP。

友链页的 links 字段每行一条，三段之间用 ASCII 竖线分隔（半角，不是全角）：

Typecho 官网 | https://typecho.org | 轻量级博客程序
好友博客 | https://example.com | 一句话描述

少于两段、或者链接不是 http(s) 的行会被直接跳过；名称留空时用域名兜底。

四、SEO 与 GEO：机器怎么读这个站

结构化数据：WebSite + Person（含 sameAs 社交实体）+ 文章页 BlogPosting、列表页 CollectionPage；作者实体是机器判断「这是谁写的」的关键。
三个端点：/robots.txt、/sitemap.xml、/llms.txt 都是 PHP 实时生成，URL 保持标准形式。nginx 用 location = 精确匹配转发，所以地址看起来是静态文件，内容永远最新。
llms.txt：按 llmstxt.org 的约定组织，给 AI 一段引用摘要 + 主要页面/分类/最新文章的索引。

一句实话：结构化数据和 llms.txt 只能让机器更准确地理解并引用你，它不保证排名，也不保证被 AI 选中——那取决于内容质量和外部引用。所以这个主题把 SEO 当「不要做错」，而不是「做了就赢」。

五、LogbookMCP：为什么要写一个插件

Typecho 原生没有对外的写作 API。XML-RPC 只覆盖 pingback 和旧式客户端，想用 AI 发文、传图、改字段，只能自己补一层。

于是拆成两端：

PHP 插件端（/mcp-api 单端点）：负责鉴权、参数校验、安全防护，业务上写入走 Typecho 核心的 PostEdit / PageEdit（保证钩子、分类、附件逻辑跟后台一致），读取直接查库（所以草稿和私密内容也读得到）。
Node 端（mcp/server.js）：把 HTTP 接口翻译成 MCP 协议，零依赖，只用 Node 内置模块，Node 18+ 就能跑。

工具清单（20 个 MCP 工具 / 23 个接口 action）

分类	工具
站点	`blog_site_info`（站点全貌 + 当前主题声明的字段）、`blog_get_fields` / `blog_set_fields`
文章	`blog_list_posts`、`blog_get_post`、`blog_create_post`、`blog_update_post`、`blog_delete_post`
页面	`blog_create_page`、`blog_update_page`、`blog_delete_page`
媒体	`blog_upload_image`、`blog_list_media`、`blog_delete_media`
分类标签	`blog_list_taxonomy`、`blog_create_category`、`blog_delete_category`、`blog_set_post_terms`
评论	`blog_list_comments`、`blog_moderate_comment`

几个容易被忽略但很实用的参数：status（默认 draft）、password（加密文章）、created（传未来时间就是定时发布）、fields（写主题自定义字段）、attachments（把附件挂到文章下）。

六、接入只要三步

后台 → 插件 → LogbookMCP → 复制访问令牌；
写一份 mcp/config.json（或在环境变量里给），URL 指向站点；
在支持 MCP 的客户端里加一段配置，例如 DSH：

- id: mcp-logbook
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: logbook
    transport: stdio
    command: node
    args: ['path/to/mcp/server.js']
    env:
      LOGBOOK_SITE_URL: https://zxfblog.ren
      LOGBOOK_TOKEN: 把插件设置里的令牌粘到这里
    toolCallTimeoutMs: 60000

先确认接口活着（不需要令牌）：

curl -s "https://zxfblog.ren/mcp-api?action=ping"
# {"ok":true,"data":{"plugin":"LogbookMCP","version":"1.0.1"}}

七、安全上的几个刻意设计

令牌支持三种传法（Authorization: Bearer / X-Logbook-Token / ?token=），比较用 hash_equals 防时序侧信道。
IP 白名单：用 inet_pton 做二进制前缀比较，IPv4/IPv6 同一套逻辑；位宽解析失败一律不放行（fail-closed），
因为一个 127.0.0.1/abc 的笔误如果被当成 /0，就等于白名单形同虚设。
默认草稿：新建内容默认 draft，只有显式传 publish 才会公开，避免 AI 误解意图把半成品捅到线上。
防 SSRF：上传图片支持传远程 URL，这里会拒绝内网/环回/保留地址，但放行站点自身域名——「抓自己的附件」是正常用法。
最小暴露：未带令牌的 ping 只回插件名与版本，不吐 PHP/Typecho 版本、站点地址这类指纹信息。

八、边界与还没做的

为了避免看完觉得「无所不能」，把边界写清楚：目前只考虑单用户（令牌等同于管理员权限，没有多用户与细粒度权限）；第三方验证码走的是真实交互式组件，自动化测试没覆盖真实 token；SMTP 发信、评论分页、1000+ 文章的性能、老浏览器兼容、XML-RPC 都没做。

想继续往下看的话，下一篇是这两个东西的完整开发复盘：流程、设计取舍，以及 25 个真实踩过的坑。