技术实践 on TechLog 技术日志

Hugo + PaperMod 博客搭建记录(含踩坑)

Fri, 07 Aug 2026 03:30:00 +0800

本博客即本文的产物。记录完整搭建过程和踩过的坑,供以后重建参考。

技术选型

Hugo v0.164.0(extended)— Go 单二进制,极快
PaperMod 主题 — 极简技术风,内置搜索/归档/标签
目标:按日期更新的技术日志流

搭建步骤

1. 安装 Hugo(容器内,免 root)

# 下载官方 release 的 tar.gz 到用户目录(路径按实际环境替换)
curl -L "https://github.com/gohugoio/hugo/releases/download/v0.164.0/hugo_extended_0.164.0_linux-amd64.tar.gz" -o /tmp/hugo.tar.gz
mkdir -p ~/bin && tar -xzf /tmp/hugo.tar.gz -C ~/bin hugo
# 验证
~/bin/hugo version

2. 建站点 + 装主题

cd ~ && ~/bin/hugo new site techlog
git clone --depth 1 https://github.com/adityatelange/hugo-PaperMod ~/techlog/themes/PaperMod

3. 配置 config.toml(中文)

关键配置点:

theme = "PaperMod"
菜单:归档 / 搜索 / 标签
输出:HTML + RSS + JSON(搜索需要)

4. 创建归档/搜索页面

<!-- content/archives.md -->
---
title: "归档"
layout: "archives"
url: "/archives/"
---

<!-- content/search.md -->
---
title: "搜索"
layout: "search"
url: "/search/"
---

5. 构建

hugo --minify # 输出到 public/

踩坑记录

坑 1:hugo.toml vs config.toml 并存

Hugo 0.164 的 hugo new site 默认生成 hugo.toml,如果又写了 config.toml,两个文件并存时 hugo 优先读 hugo.toml(还是默认内容),你的配置全部不生效。

AI 用量成本真相:4 亿 token 里 98.6% 是便宜的缓存读

Thu, 06 Aug 2026 23:00:00 +0800

仪表盘显示 7 天消耗 4 亿 token,看似吓人——但拆开看,真实成本一个月才几十块。

现象

hermes insights 显示:

输入 477 万 + 输出 92 万
Total 4 亿(对不上?)

真相:Total = 输入 + 输出 + 缓存读 + 缓存写 + 推理

4 亿的真实构成:

项目	数量	占比
缓存读取(cache read)	3.99 亿	98.6%
输入	447 万	1.1%
输出	76 万	0.2%
推理	33 万	0.08%

“4 亿"几乎全是缓存读取——不是真的消耗了 4 亿新 token。

为什么有这么多缓存读

长会话场景(如 QQ 单窗口聊天):每轮对话都要把整个会话历史重新发给模型。但历史大部分没变,被**上下文缓存(cache)**命中——服务端只收极低的缓存价,不重新计费。

单轮实测:发一条消息,输入 2,421 token,但缓存读 23 万(整个历史)。

成本换算

按 DeepSeek V4-Flash 价格(涨价前):

Firecrawl 计费陷阱:PDF 提取按页计费

Thu, 06 Aug 2026 22:30:00 +0800

一次 82 页 PDF 提取烧掉 84 credits(月度免费额度的 8.4%),血的教训。

计费规则(官方确认)

操作	消耗
搜索	2 credits / 10 条结果(向上取整)
HTML 提取	1 credit / 页
PDF 提取	按页计费(82 页 ≈ 84 credits)
搜索+自动抓正文	搜索 2 + 每结果 1 credit

免费额度:1000 credits/月。

教训

PDF 绝对不要直接扔给 Firecrawl 提取——按页计费,一个几十页的 PDF 就能烧掉月度额度的百分之几到十几。

正确做法

PDF → curl 下载到本地 → 本地解析(pymupdf/read_file) → 免费
HTML → Firecrawl(1 credit/页) 或 curl
搜索 → DeepSeek 服务端(不耗 Firecrawl 额度)

实测对比:

82 页 PDF 扔 Firecrawl:84 credits
同 PDF curl + 本地解析:0 credits

为什么 Firecrawl 搜索也烧额度

Firecrawl 的搜索默认会抓每个结果的正文(“search + extraction in one call”)——一次搜索 10 条结果 = 2(搜索)+ 10(抓取)= 12 credits。所以搜索密集场景要小心,最好用纯搜索服务(如 DeepSeek web_search)。

搜索体系重建:DeepSeek 服务端搜索 + Firecrawl 提取

Thu, 06 Aug 2026 22:00:00 +0800

2026-08-05 ~ 08-06 折腾两天,解决"搜索引擎全被反爬"的痛点的完整方案。

背景

之前用 curl/浏览器直接抓搜索引擎(Google/Bing/DDG/Startpage/Yandex 等),结果全被反爬挡住(CAPTCHA/403/验证页)。需要一个稳定、免反爬、低成本的搜索方案。

方案演进

阶段 1:发现 DeepSeek 支持服务端 web_search

DeepSeek 官方 Responses API 支持 web_search 工具——搜索在 DeepSeek 服务器端执行,客户端拿到的就是结构化结果,完全绕开反爬。

关键验证:

api.deepseek.com/v1/responses 支持 tools: [{type: web_search}]
事件流有 web_search_call.in_progress / searching / completed
返回结果含 title/url/description

阶段 2:发现 opencode-go 中转也支持

意外收获:opencode-go 的 /zen/go/v1/responses 端点同样支持 web_search 工具——意味着可以用已有的 OPENCODE_GO_API_KEY(和主模型同一账户),不用额外注册 DeepSeek 官方 key。

实测:

{"tools": [{"type": "web_search"}]}
→ output 含 web_search_call(completed),返回真实搜索结果

阶段 3:Firecrawl 负责提取(分工)

社区共识:Firecrawl 擅长网页提取(extract),搜索是弱项(官方也承认"basic search endpoint, not true SERP")。于是分工:

web.search_backend: deepseek ← 搜索(服务端,免反爬)
web.extract_backend: firecrawl ← 提取(HTML 转 markdown)

最终架构

┌─────────────────────────────────────────────┐
│ 搜索(web_search) → opencode-go /responses │
│ → DeepSeek 服务端执行 → 结构化结果 │
├─────────────────────────────────────────────┤
│ 提取(web_extract) → Firecrawl API │
│ → 网页转 markdown(1 credit/页) │
├─────────────────────────────────────────────┤
│ 兜底 → cn.bing / 搜狗 / curl 直抓 │
└─────────────────────────────────────────────┘

关键点

搜索和提取解耦:搜索走模型服务商(不烧 Firecrawl 额度),提取走 Firecrawl(免费 1000 credits/月)
服务端搜索免反爬:反爬是客户端直抓的问题,服务端执行彻底绕开
成本极低:搜索按 token 计费(缓存命中 0.02 元/百万),提取 1 credit/页

附:Firecrawl 注册

2026 年 6 月起 Firecrawl 推出 Keyless 模式(免 key 每月 1000 credits),但 Hermes 插件仍需要 key——邮箱注册即可拿到 fc- 开头的 key,免费额度无需绑卡。

AI Agent 记忆分层架构:常驻内存 + 外部知识库

Wed, 05 Aug 2026 22:00:00 +0800

解决 AI Agent 记忆"不够用、存不下、查不到"三难问题的实践方案。

问题背景

AI Agent(如 Hermes)的持久记忆面临矛盾:

常驻记忆有容量上限(默认 2000 字符,可扩容)— 存不了多少事实
全部塞进上下文太贵——每轮对话都要重新发送,按 token 计费
低频信息不能丢——设备配置、排障细节、API 用法,几周后可能还要用

分层方案

┌─────────────────────────────────────────────┐
│ 第一层:常驻记忆(memory) │
│ · 高频事实:IP/端口/凭据位置/用户偏好/关键配置 │
│ · 默认2000字符可扩容,每轮注入上下文 │
│ · 只放精简核心 │
├─────────────────────────────────────────────┤
│ 第二层:外部知识库(fact_store) │
│ · 低频背景:设备配置/排障细节/软件特性/API用法 │
│ · 大容量、不衰减、不删除、不占 token │
│ · 结构化存储,支持实体关联/组合查询 │
├─────────────────────────────────────────────┤
│ 第三层:会话历史(session db) │
│ · 完整对话记录,可全文检索 │
│ · 用于回溯"当时怎么做的" │
└─────────────────────────────────────────────┘

核心机制

1. 自动分层存储

先扩容常驻记忆(默认 2000 → 8000 字符),容纳更多高频事实
扩容后仍放不下的低频信息 → 外部库
Agent 判断信息频度:高频 → 常驻 memory,低频 → 外部库
存储时自动打标签(tags),支持实体关联

2. 索引锚点(关键设计)

外部库内容不注入上下文(不占 token),但需要"知道有这回事"才能去查: