一、新增的三个文件#

二、配置上的改动#

只动了配置，不破坏原有结构：

• src/config/analyticsConfig.ts：给 Umami 配置补 shareId、shareApiBase（指向自建的 https://umami.520781.xyz）、historicalStats、showPageViews、showSiteStats
• src/types/analyticsConfig.ts：同步补充对应类型字段
• src/config/navBarConfig.ts：「其他」下拉里原来指向 Umami 外部分享页的「统计」，改成本地 /analytics/ 入口

Waline 已经在 src/config/commentConfig.ts 里启用，统计页的最新评论模块会直接复用它的 serverURL，不用额外配置。

三、验证方式#

• pnpm astro check：282 个文件，0 错误 0 警告
• pnpm exec biome ci 对新增/改动文件：通过

构建流程没有跑完整 build（本地较慢），静态产物和接口在 pnpm astro check 的类型检查下已经通过；部署后访问 /analytics/ 和 /api/github-pushes.json 即可看到效果。

结语#

这套统计页的价值在于”公开可读”——不需要暴露 Umami 管理后台，访客也能看到站点的真实活力。移植到 Firefly 后，主题原有的 UmamiStats 侧栏小组件保持不变，/analytics 只是多了一个更完整的数据总览入口。感谢 Aemeath 作者的开源与分享。

定位：.l2s 到底是谁#

顺着文件名查，dsh 自己的代码里根本搜不到 l2s 这个词。真正的来源是容器的启动方式：

1
proot --change-id=1001:1001 --pwd=/home/qwc \
2
      --rootfs=.../ubuntu-noble_arm64 \
3
      --link2symlink ...        # ← 就是它

--link2symlink 是 Termux/TMOE 系 PRoot 的一个扩展：Android 的存储上经常建不了真硬链接，于是 PRoot 拦截 link(2)，用符号链接来仿真硬链接。

所以 .l2s. = link to symlink。这个名字既是线索也是答案。

元凶：新建文件走的是硬链接#

dsh 的本地文件系统后端 @deepseek-ai/dsh-fs-local，在 writeFileAtomic 里对新建文件和覆盖文件用了两种不同的发布方式：

1
// dsh-fs-local/lib/index.js（节选）
2
const stagingDir = join(directory, `.${basename(absolutePath)}.${pid}.${uuid}.tmpdir`);
3
const tempPath = join(stagingDir, `${basename(absolutePath)}.tmp`);
4
// ...写入 tempPath、sync、chmod...
5

6
if (createIfAbsent !== void 0) await linkFile(tempPath, absolutePath); // ← 新建文件：硬链接
7
else await rename(tempPath, absolutePath);                             // ← 覆盖/编辑：rename
8

9
await removeStagingDir(stagingDir);   // 删掉整个 staging 目录

设计意图很清楚：先在自己的 staging 目录里把内容写完整、同步好，然后用 link() 一步”无覆盖地”发布出去——如果目标已存在，link() 会抛 EEXIST，dsh 再把它翻译成 FS_NOT_OBSERVED。这是很标准的原子 no-replace 写法。

但在 --link2symlink 下，link() 不再是硬链接，而是变成了一个符号链接代理：

1
link(temp, target)
2
   └─ target -> <stagingDir>/.l2s.temp0001 -> <stagingDir>/.l2s.temp0001.0001
3

4
removeStagingDir(stagingDir)
5
   └─ 代理文件被一起删掉 → target 悬空，内容不可恢复

代理文件就放在 staging 目录里面，而 dsh 紧接着就把整个 staging 目录删了。于是：写成功、文件”在”、内容没了。

覆盖面没事，是因为 rename() 是真的把文件移出 staging 目录，PRoot 处理得好好的。所以这个 bug 精确地只发生在”新建”这一条路径上。

为什么不能”事后修复悬空链接”#

我一开始的想法也是写个脚本扫描 .l2s 悬空链接去还原。但看清楚链路后就知道这条路走不通：内容在 removeStagingDir 那一刻就已经随着代理文件被删除了，等你在文件系统上看到悬空链接时，字节早没了。

修复必须发生在”发布”这一步之前，而不是之后。

修复：换掉发布原语，而不是改 dsh#

顺着代码往下看，writeFileAtomic 其实留了一个口子：

1
const linkFile = internals.linkFile ?? link;   // internals 优先，否则用内置 link
2
...
3
await linkFile(tempPath, absolutePath);

internals 是 LocalFileSystem 实例上的一个对象，而 dsh-fs-sandbox 的 SandboxedFileSystem 直接继承它——也就是说，只要拿到 ctx.fs 这个服务实例，把 internals.linkFile 换掉，两种后端就一起覆盖了，dsh 本体一个字节都不用改。

插件的做法分三步：

1. 加载时探测。在临时目录里原样复刻 dsh 的发布序列，看结果：

   1
   await writeFile(source, PROBE_CONTENT, { mode: 0o600, flag: "wx" });
   2
   await nativeLink(source, target);
   3
   await rm(staging, { recursive: true, force: true });   // dsh 也会删 staging
   4
   const observed = await readFile(target, "utf8");        // PRoot 下这里 ENOENT

2. 可信就完全不动。普通 Linux/macOS 上硬链接是好的，探测通过，保留原生 link()，行为零变化。

3. 不可信才替换。用”独占创建 + 内容拷贝”来等价实现硬链接的语义：

   1
   const handle = await open(targetPath, "wx", mode & 0o7777); // EEXIST = 竞争失败，语义不变
   2
   await handle.writeFile(await readFile(sourcePath));
   3
   await handle.sync();

   • open(..., "wx") 保住了 no-replace：并发创建者依然会拿到 EEXIST，dsh 依然把它翻成 FS_NOT_OBSERVED，和原生行为一致；
   • 内容从 staging 文件里拷出来，不再依赖 staging 目录活到发布之后；
   • staging 文件的权限位被保留，新文件落地的权限和 dsh 原本的选择一样（实测都是 0600）。

探测只跑一次，之后每次发布都 await 同一个 promise；安装又是同步完成的，所以不存在”探测还没结束就漏一次写”的窗口。

安装#

插件零运行时依赖，index.js 只用 Node 内置模块。两种装法：

方式 A：绝对路径（推荐给容器/离线环境）——在 ~/.dsh/profiles/web/cordis.patch.yml 里插一行：

1
- insert:
2
    - id: fs-link2symlink-fix
3
      name: /absolute/path/to/dsh-fs-link2symlink-fix/index.js

profile 配了 patchReload: "live"，保存即热重载，不用重启 dsh；也不经过 pnpm，pnpm install 不会把它清掉。

方式 B：当 bundle 装：

1
dsh plugin --profile web add github:qwc-ch/dsh-fs-link2symlink-fix
2
# 再把它加进 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles

验证#

新建文件之后：

1
ls -la  <new-file>     # 应该是 -rw-------，不是 lrwxrwxrwx
2
cat     <new-file>     # 内容完整
3
find . -name '.l2s.*'  # 没有残留

插件加载时会打一行日志说明走了哪条分支，比如这台机器上是：

1
fs-link2symlink-fix: link() unusable (ENOTEMPTY); publishing new files by exclusive-create copy

健康主机上则是 native hard link survived staging removal; native link publication retained。

我这边除了新建，还顺手验证了嵌套目录、并发新建、覆盖回归、edit 回归，以及补充的单测（真实文件 / 非 symlink / 内容 / 0600 权限 / 竞争时 EEXIST / 停用回滚），都过了。

几个注意点#

• internals.linkFile 是测试接缝，不是正式公开 API。 这是”不 fork dsh 又要修部署环境问题”的务实选择。插件对”接缝不存在”的情况做了安全降级（直接什么都不做），但如果哪天上游把它删了，插件会静默失效——那时候最好去上游提个 issue。
• 探测失败一律保守兜底。 连临时目录都建不了、或者 link() 直接报错，都会被判定为”不可信”，改用拷贝发布。对”文件创建正确性”来说，这是更安全的一侧。
• 会话日志的 .l2s 垃圾不在覆盖范围。 dsh-session-persistence-jsonl 落盘时也用了 link()，会在 ~/.dsh/sessions/** 留 .l2s.* 文件。但它不会丢日志（日志随后会被 rename 落成普通文件），只是碍眼，所以插件没去动会话目录。
• 覆盖/编辑故意不动。 那两条路径本来就正常，没必要扩大改动面。

仓库#

源码在 GitHub：qwc-ch/dsh-fs-link2symlink-fix，MIT 协议，就 index.js / package.json / cordis.patch.yml 加一份 README，看完就知道没藏东西。

如果你也在 Termux/PRoot 里跑 dsh，而且发现”新建的文件过一会儿就没了”，八成是同一个坑——ls -la 看一眼是不是 lrwxrwxrwx 指向 .l2s.* 就知道了。

说真的，我挺想在手机上认真玩一玩 vibe coding，但折腾下来还是觉得 opencode 这类项目更完善。不过手机终归只能玩一玩，不适合拿来实战。

排查：seed 参数是个摆设？#

主题的封面处理逻辑其实考虑到了这个问题。src/utils/image-utils.ts 里对每篇文章按 id 生成一个哈希，拼成 ?v=123456 这样的查询参数附加到随机图 API 后面，意图很明显：让同一篇文章每次都拿到同一张图。

列表卡片和文章页生成的 URL 完全一致。理论上浏览器该拿到同一张图才对。

那问题多半出在 API 端。直接用 curl 验证——用同一个 v 值连续请求三次：

1
for i in 1 2 3; do
2
  curl -s "https://tu.520781.xyz/random?type=img&dir=cover&v=12345" -o seed_$i
3
done
4
md5sum seed_*

三个文件的 md5 完全不同，甚至 Content-Type 都在 image/jpeg、image/webp、image/avif 之间横跳。v 参数根本没有被处理，每次请求都是纯随机。

再翻图床的 API 文档（图床是我自建的 CloudFlare ImgBed），/random 接口的参数只有 content / type / form / dir / orientation 五个——压根没有种子参数。主题代码和 API 能力之间，隔着一厢情愿。

也就是说：只要封面 URL 指向 /random 接口，就不可能做到每篇文章固定一张图。这是接口层面的能力缺失，不是主题代码的 bug。

转机：/random 的隐藏用法#

文档里有个细节救了我：/random 默认直接返回图片，但加上 type=url&form=text 后，返回的是一张确定图片的完整链接：

1
curl "https://tu.520781.xyz/random?type=url&form=text&dir=cover"
2
# https://a.520781.xyz/file/cover/绘梨衣/1788687100738_xxx.webp

返回的是 /file/... 下的静态文件地址——随机性在返回链接这一刻就”结算”完了，之后这个链接永远指向同一张图，还能吃满 CDN 缓存。

思路立刻清晰：构建时调一次接口，把每篇文章的封面链接钉死存下来，页面渲染时直接用存好的链接。

实现#

1
function computeEntryId(fileRelPath: string, frontmatter: string): string {
2
  const explicitSlug = extractFrontmatterField(frontmatter, "slug");
3
  if (explicitSlug) return explicitSlug;
4
  const withoutExt = fileRelPath.replace(/\.(md|mdx|markdown)$/i, "");
5
  return withoutExt
6
    .split("/")
7
    .map((segment) => githubSlug(segment))
8
    .join("/")
9
    .replace(/\/index$/, "");
10
}

1
import randomCoversData from "@constants/random-covers.json";
2

3
// ...
4
const pinned = getPinnedCover(seed);
5
if (pinned) return pinned;
6
// 未固定的文章仍走原来的 API + 随机兜底

验证#

脚本是幂等的（重复执行不产生 API 请求、文件字节级不变），但真正要回答的问题是：产物里列表和详情到底是不是同一张图？

跑完 pnpm build 后写了个小脚本扫 dist/，对每篇同时在列表卡片和文章页出现封面的文章，比对两处 <img src> 属性——27 篇全部一致，0 处不匹配。

效果与使用#

• 列表页、文章页、分享海报引用的封面从此完全一致
• 封面变成静态文件链接，CDN 可缓存，刷新不再换图
• 日常无感知：新文章写 image: 'api'，下次构建自动分配

想给某篇文章换封面，把 random-covers.json 里对应条目删掉再 pnpm covers 即可；也可以直接手动填任意图片 URL。

小结#

这次的问题链条挺典型：主题代码的”种子”设计看起来天衣无缝，但种子要生效得靠 API 端配合，而大多数随机图 API 并不支持。排查的关键一步是用 curl 剥掉所有中间层直接验证接口行为——**两次请求返回的字节一样吗？**一样才谈得上稳定。

解法也没有在渲染层纠缠（前端缓存、localStorage 同步都是歪路），而是把”随机”这件事挪到构建期一次性结算：随机只发生在构建时，发布出去的永远是确定结果。这和 SSG 的哲学意外地合拍。

问题现象#

插件安装成功（market 日志显示 @tonydua/dsh-web-search-exa@0.1.5 exit=0），但 web_search 依然报：

1
DeepSeek search has no API key for "DEEPSEEK_API_KEY";
2
store it through the credentials service ..., export it in the
3
launching environment, or set a literal "apiKey" in the
4
web-search-deepseek config

报错来自官方的 DeepSeek provider——也就是说搜索根本没走 Exa 插件。

排查过程#

按排除法一步步来：

1
$ node -e "import('@tonydua/dsh-web-search-exa').then(m => console.log(Object.keys(m)))"
2
Config, DEFAULT_MCP_URL, ExaSearchProvider, apply, inject, ...

1
$ curl -o /dev/null -w "%{http_code}\n" https://mcp.exa.ai/mcp      # → 405（GET 的预期响应）
2
$ curl -o /dev/null -w "%{http_code}\n" https://api.exa.ai/search   # → 404（同上）

1
$ node -e "fetch('https://mcp.exa.ai/mcp', { method: 'POST', headers: {...}, body })"
2
→ HTTP 200，text/event-stream，直接返回了真实搜索结果（J.K. 罗琳）

根因：web 行把 searchProvider 钉死在 deepseek-official#

翻 dsh-base 基础包的 cordis.patch.yml，web 行长这样：

1
- id: web
2
  name: '@deepseek-ai/dsh-web'
3
  config:
4
    searchProvider: deepseek-official   # ← 钉死了
5
    fetchProvider: http

WebRuntime 构造时读 config.searchProvider ?? process.env.DSH_WEB_SEARCH_PROVIDER，于是 searchProviderId = "deepseek-official"。再看搜索时 seam 的选择规则（dsh-web 源码，0.1.5-rc.3）：

1
function resolveProvider(selection) {
2
  const { configuredId, providers } = selection;
3
  if (configuredId !== void 0) {
4
    // 配置了 id：直接返回这个 provider，没注册/不可用才报错
5
    const provider = providers.get(configuredId);
6
    ...
7
    return provider;
8
  }
9
  // 没配置 id：过滤出"可用"的 provider
10
  // 恰好 1 个 → 用它；>1 个 → 报 AMBIGUOUS；0 个 → 报 UNAVAILABLE
11
}

关键就在这里：

• 插件宣称的”零配置自动接管”依赖第二条路——没配置 id 时，官方 provider 因无 key 不可用，过滤后只剩 Exa，自动选中。
• 但 dsh-base 把 searchProvider 钉死为 deepseek-official，选择器拿到配置的 id 就直接返回，永远走不到第二条路。
• 更微妙的是，DeepSeek provider 的 available() 检查的是 options.resolveApiKey !== void 0——这个 thunk 恒为定义，所以它永远”可用”，只在真正 search() 解析 key 时才抛凭据错误。

于是完整的链路是：每次搜索 → 配置 id deepseek-official → 命中 DeepSeek provider → 无 DEEPSEEK_API_KEY → 报错。Exa 插件从头到尾没被咨询过。

修复：profile 补丁层按 id 覆盖#

用户自己的 ~/.dsh/profiles/web/cordis.patch.yml 应用在所有 bundle 层之后，可以按 id 覆盖行：

1
- id: web
2
  config:
3
    searchProvider: exa
4
    fetchProvider: http

注意 fetchProvider: http 必须一并写上。这是本文初版的一个勘误：初版写的是”加载器用 Object.assign 合并 config override，没写的字段保留原值”，这是错的。实际查 cordis-plugin-include 的 applyEntryPatches 源码，覆盖语义是：

1
for (const [key, value] of Object.entries(overrides)) {
2
  if (key === "id") continue;
3
  target[key] = value;   // ← 整值替换，没有深合并
4
}

config 作为一个整体被替换掉，只写 searchProvider 会把 fetchProvider 丢掉。而 WebRuntime.Config 的 zod schema 里 searchProvider / fetchProvider 都是必填（z.string()），构造时 config.fetchProvider ?? process.env.DSH_WEB_FETCH_PROVIDER 会回退到环境变量——没配就是 undefined，web_fetch 会直接报”未配置 provider”。dsh-base 自家注释也写明了：“A patch replaces the targeted row’s whole config rather than merging into it”。按 id 覆盖行时，正确姿势是把整行 config 完整重述一遍，只改你想改的字段。

另外 profile 配了 patchReload: "live"，这个改动保存即热重载生效，无需重启。

之后 web_search 就走 Exa 插件了——搜”哈利波特作者是谁”直接返回真实结果（J.K. 罗琳），已在 2026-10-05 用上述两字段写法实测验证通过。

注意事项#

• 熔断器：Exa provider 连续 3 次瞬时失败（5xx、429、网络错误）会跳闸，5 分钟内 available() 为 false；冷却结束后下一次搜索会重新探测，成功一次即重置。因为现在配置了显式 id，跳闸期间 seam 会报 configured web provider "exa" is registered but unavailable——至少是个清晰的错误，而不是误导人的 DeepSeek 凭据错误。
• 为什么没提 PR：这个修复本质是用户本地的 profile 配置（cordis.patch.yml 是用户的补丁层，不属于任何仓库），插件代码本身没有 bug——端点通、模块能加载、注册也无条件。问题只是 dsh-base 钉死了 searchProvider，而插件按约定不能（也不应）在自己的 bundle patch 里覆盖官方的行。所以写成博客记录，算是给插件作者一个”文档该补充一句”的素材。

小结#

• 装插件 ≠ 会生效：dsh 基础包把 web 行的 searchProvider 钉死为 deepseek-official，无 key 时插件的零配置自动接管不会发生，搜索只会撞上凭据错误。
• 覆盖是整值替换：profile 补丁层按 id 覆盖 web 行时，config 整体被替换，必须把 fetchProvider: http 一并写上，只写 searchProvider 会丢抓取配置。
• 热生效：patchReload: "live" 下保存即生效，无需重启 dsh。
• 仓库地址：
  • 搜索插件：TonyDua/dsh-web-search-exa（@tonydua/dsh-web-search-exa@0.1.5）
  • DeepSeek Harness：deepseek-ai/deepseek-harness（@deepseek-ai/dsh@0.1.5-rc.3）

排查这类问题的关键思路：先证明”网络通、模块能加载、端点可用”，把怀疑范围收敛到 provider 选择，再去翻 seam 的源码。祝玩得开心！

数据结构#

课表的核心是 src/data/timetable.ts，两个数组：

• periods：作息时间，定义每一大节的起止时间和标签
• courses：课程列表，每条记录包含课程名、星期几、第几大节、上课周次规则、地点、教师

周次规则通过 weeks 字段控制，支持三种模式：

• { start: 1, end: 21 } — 全部周次
• { start: 1, end: 21, parity: "odd" } — 单周
• { start: 1, end: 21, parity: "even" } — 双周

这周五下午就是靠 parity 实现的：单周第一节化学，双周第一节体育，其余课程不变。

排课过程#

按时间表逐天录入，day: 1-5 对应周一到周五，slot 对应 periods 的下标。13 个时段分别是：

周二到周五的课程顺序和周一不同，逐一核对后填入对应 slot。地点和教师目前留空，后续补上。

学期信息#

semester 配置了学期的基本信息，startDate 设成 2026-09-01，totalWeeks 设为 21 周。组件会根据当前日期和开学第一天自动计算现在是第几周，高亮当前周的课程。

效果预览#

课表页面在 /timetable 路由下，桌面端是表格形式展示，手机端切换为按天列表。课程卡片会自动分配颜色，不同科目不同颜色，一眼就能分辨。

后续#

• 补上教室和教师信息
• 如果以后有科目调整，直接改 timetable.ts 即可，不需要动代码

问题：直接转 PDF 为什么会乱？#

用 ebook-convert 直接 MOBI → PDF 时，Calibre 会用 QtWebEngine 渲染 HTML 内容，再输出为 PDF。MOBI 文件里的图片通常是窄长的竖版（比如 900×1280），但默认的 PDF 页面是 Letter 尺寸（612×792），渲染时图片就被挤到页面一侧，另一边全是空白。

1
❌ 错误效果：
2
┌──────────────┐
3
│              │
4
│   [图片]     │  ← 图片只占右边，左边大片空白
5
│              │
6
└──────────────┘

解决方案：MOBI → EPUB → PDF#

核心思路是分两步走：先转 EPUB 提取原始图片，再用 Python/PIL 从图片生成 PDF，这样可以保持原始宽高比。

1
sudo apt-get install -y calibre

1
sudo apt-get install -f

1
QTWEBENGINE_DISABLE_SANDBOX=1 ebook-convert "输入.mobi" "/tmp/输出.epub"

1
import zipfile, os
2
from PIL import Image
3
import io
4

5
with zipfile.ZipFile("输出.epub") as z:
6
    imgs = sorted([n for n in z.namelist() if n.endswith(('.jpg','.jpeg','.png'))])
7
    pil_images = [Image.open(io.BytesIO(z.read(n))).convert('RGB') for n in imgs]
8
    pil_images[0].save("输出.pdf", 'PDF', save_all=True, append_images=pil_images[1:], resolution=150.0)

1
cd "mobi文件夹"
2
for f in *.mobi; do
3
  QTWEBENGINE_DISABLE_SANDBOX=1 ebook-convert "$f" "/tmp/$(basename "$f" .mobi).epub" 2>/dev/null
4
  python3 -c "
5
import zipfile, os
6
from PIL import Image
7
import io
8
epub = '/tmp/$(basename "$f" .mobi).epub'
9
pdf = '$f'.replace('.mobi', '.pdf')
10
with zipfile.ZipFile(epub) as z:
11
    imgs = sorted([n for n in z.namelist() if n.endswith(('.jpg','.jpeg','.png'))])
12
    pil = [Image.open(io.BytesIO(z.read(n))).convert('RGB') for n in imgs]
13
    pil[0].save(pdf, 'PDF', save_all=True, append_images=pil[1:], resolution=150.0)
14
    print(f'{pdf}: {len(pil)} pages')
15
"
16
done
17
rm -f /tmp/*.epub

实际效果#

我用这套方法转换了《金牌得主》的 12 本 MOBI（共约 2300 页），每本 PDF 都完美保持了原图比例，没有变形也没有空白边距。

总结#

1. 不要直接用 ebook-convert 转 PDF，渲染引擎会破坏图片比例
2. 走 MOBI → EPUB → 提取图片 → PDF 的路线
3. 安装 Calibre 时加上 QTWEBENGINE_DISABLE_SANDBOX=1 环境变量
4. 用 Python PIL 库从 EPUB 提取图片生成 PDF，保留原始分辨率

这个方法适用于漫画、杂志等以图片为主的 MOBI 文件。如果是纯文字 MOBI，直接转换也问题不大。

元凶：工具 id 每一步都重新编号#

把会话存档（~/.dsh/sessions/ 下的 jsonl）解压看事件流，原因很简单：

• 我用的 NVIDIA（openai-completions 协议）这条链路，工具调用 id 是每个 step 重新从 read:0 开始编的。step 3 有个 read:0，step 4 又来一个 read:0，step 5 还是 read:0。
• 而 dsh 的回放器（dsh-client-ui-conversation 里的 toolDefinition）拿裸 callId 当上下文的 key：

1
if (event.type === "tool/call")
2
  return { id: String(event.data.callId), role: "start" };

key 里不带 turn/step 隔离。回放时第二个 step 的 read:0 start 撞上同一个 key，dsh-client-runtime 直接抛 received more than one start Match。

我下载对比了最新的 0.1.1-rc.1，这段代码一模一样，上游还没修；项目也不收 issue，那就自己解决。

为什么做成插件，而不是改源码#

之前让 AI 改 node_modules 里的文件翻过车（改了半天发现改的是死代码，没被执行，而且一升级就丢）。所以这次的要求是：

1. 不碰 dsh 自身代码，升级 dsh 后修复要还在；
2. 用官方留的口子，不 hack。

dsh 正好满足：profile 目录（~/.dsh/profiles/web/）支持自己的 bundle 插件，由 pnpm 管理，而且 LLM 流上有一个 llm/stream 瀑布钩子——官方的 session-checkpoint-policy 就是用这个钩子在流前面插队的。插件连 dsh 本体的一个字节都不用改。

插件怎么修的#

思路一句话：让 id 在流进会话之前就唯一。挂在 llm/stream 上包住下游流，按会话记录已经用过的工具 id，撞号时重写：

1
第 1 个 step:  read:0  →  read:0    （原样放行）
2
第 2 个 step:  read:0  →  read:0~1  （发现本会话用过，加后缀）

改写发生在流层，而会话里的所有东西——拼好的 assistant 消息、持久化的 tool/call / tool/result 事件、下一次发给模型的请求——全都是从这条流往下游组装的，所以一处改写，全链路一致，不存在改写只改了显示层的半吊子状态。

核心代码就这么点：

1
ctx.on("llm/stream", (options, next) => {
2
  const state = stateFor(options.sessionId);      // 每个 session 一份已用 id 表
3
  return wrapStream(state, next());               // yield* 包一层，撞号就改名
4
}, { global: true });                              // global: true 连 subagent 一起覆盖

• tool-call-delta chunk：撞号时浅拷贝一份换掉 id
• block-end 里的组装好的 block：同样换 id
• 其他 chunk：原样透传
• id 本身唯一的（比如 Anthropic 链路的 toolu_xxx）：零改动，零开销

安装#

1
# 1. 装到 web profile
2
dsh plugin --profile web add github:qwc-ch/dsh-toolcall-id
3

4
# 2. 把它加进 bundle 列表：编辑 ~/.dsh/profiles/web/package.json，
5
#    dsh.profile.bundles 数组末尾加上 "dsh-toolcall-id"

然后重启 dsh web 就生效了。配置对不对可以随时用 dsh --profile web --dump-config 确认树里有它。

要卸载的话：dsh plugin --profile web uninstall dsh-toolcall-id，再把 bundle 列表里那行删掉。

注意点#

• 只防新坑：修复对插件安装之后产生的会话生效。已经被写坏的旧会话存档里重号已经落盘，救它需要回头改存档（把旧 jsonl 里的重复 id 一次性改写再重新压缩），不是插件的活。
• 插件会让重号 id 变成 read:0~1 这种形式，这个 id 同样会进下一次请求的上下文，模型侧不受任何影响（OpenAI 协议本就是靠 id 自匹配的，格式随便）。
• 如果哪天上游修了（key 带上 turn/step），这个插件可以直接卸掉，行为完全等效。

仓库#

源码在 GitHub：qwc-ch/dsh-toolcall-id，MIT 协议，就三个文件（index.js / package.json / cordis.patch.yml），看完就知道没藏东西。

碰到一样报错的，装完记得重启 dsh。

错误示例#

（省略实际运行日志，示例截图或文字）

provider “openai” failed, retry 5/5, backoff 2 s → abort

正确的做法：配置 retryPolicy#

1
llm-pi-ai:
2
  providers:
3
    nvm:
4
      displayName: 英伟达
5
      apiKeyEnv: NVM_API_KEY
6
      api: openai-completions
7
      baseURL: https://integrate.api.nvidia.com/v1
8
      retryPolicy:
9
        mode: always          # 无限重试
10
        backoff:
11
          initialDelayMs: 2000 # 第一次重试 2 s
12
          maxDelayMs: 30000   # 最大 30 s
13
          jitterRatio: 0.1    # ±10% 抖动避免“同步雨点”
14
    modelscope1:
15
      displayName: 魔搭
16
      apiKeyEnv: MODELSCOPE1_API_KEY
17
      api: openai-completions
18
      baseURL: https://api-inference.modelscope.cn/v1
19
      retryPolicy:
20
        mode: always
21
        backoff:
22
          initialDelayMs: 2000
23
          maxDelayMs: 30000
24
          jitterRatio: 0.1

1
$ dsh conversation -m openai/gpt-4
2
...
3
[retry] attempt 1/∞, wait 2.1s
4
[retry] attempt 2/∞, wait 4.3s
5
...

验证#

1. 故意让请求超时（如关闭网络或使用错误的 baseURL）。
2. 观察终端输出，确认重试次数持续递增，且延迟随 2x 增长直至 30 s。
3. 按 Ctrl+C 中断会话，dsh 会立刻停止后续重试。

注意事项#

• 无限重试会消耗配额。对 Quota/ Billing 错误（如 QUOTA、INVALID_CREDENTIAL）always 模式仍会重试，可能导致无限请求并触发封禁。请根据实际需要决定是否使用 always，或在 normal 模式下自行调高 maxRetries。
• 如果只想延长间隔而不想无限循环，可以保留 mode: normal，只调大 maxRetries 或 maxDelayMs。
• 配置错误会在启动时抛出 Schema validation 错误，记得检查 pnpm dev 或 pnpm build 输出的报错信息。

小结#

• 别改源码：dsh 的重试逻辑在 dsh-llm-retry，通过 settings.yaml 完全可配置。
• 用 retryPolicy.mode: always 实现无限重试，配合 backoff 参数得到指数退避。
• 手动中止：Ctrl+C（或发送中断信号）随时停止重试，避免不必要的费用。

这样就完成了让 dsh 无限重试的配置，你可以把它当作日常的容错手段，特别是在不稳定网络或临时限流的场景下。祝玩得开心！

修复一：补上 canonical#

在布局组件的 <head> 里加一行：

1
<link rel="canonical" href={Astro.url} />

配合 Astro 的 trailingSlash: "always"，输出的就是带斜杠的完整 URL，与 sitemap 保持一致。这是一个纯声明式的修复，不影响页面显示，只影响搜索引擎对 URL 的判断。

修复后无斜杠版本（如 /posts/astbot）虽然在 Vercel 上同样返回 200，但页面内的 canonical 指向带斜杠版本，Google 会自动剔除重复 URL。

修复二：robots.txt 屏蔽参数页#

/archive/?tag=xxx 这类带查询参数的过滤页会被反复抓取，但永远不会被收录，纯浪费抓取配额。在 robots.txt 里加上：

1
Disallow: /*?tag=

修复三：消除雷同的 meta description#

Bing 后台提示「太多页面使用相同的 meta description」。原因是我之前用的兜底逻辑：

1
description || siteConfig.description || pageTitle

所有没写 description 的页面（归档、搜索、标签、分类页）全部退回到同一个站点描述。修复方案：

1. 文章页：没有手写 description 时，兜底用正文第一段作为摘要（项目里本来就有 remark-excerpt 插件在生成 excerpt，只是没人用）
2. 归档/搜索/标签/分类页：各自补充独立的 description（走 i18n，六种语言都加了翻译）

修复四：接入 IndexNow#

IndexNow 是一个开放协议，Bing、Yandex、Naver、Seznam 都支持：网站根目录放一个 <key>.txt 文件作为”地盘证明”，发布内容后主动向搜索引擎提交 URL，通常几小时到一两天内就会被抓取，不需要等爬虫慢慢来。

我做了三件事：

1. 生成一个 UUID 作为 key，写入 public/<key>.txt（注意：文件内容不能有多余的换行符，Bing 校验非常严格，这是第一个坑）
2. 写了一个构建后脚本 scripts/indexnow.ts：读 sitemap 里的 URL，逐个端点提交
3. 接入 pnpm build 最后一步，以后每次部署自动提交

现状与总结#

• Google 侧：canonical、meta description、robots.txt 均已修复；sitemap-0.xml 已成功处理（39 个 URL）。剩下的交给时间（新站收录慢是正常的）
• Bing 侧：网站地图 ✅（39 个 URL）、IndexNow ✅（353 条提交记录），Yandex/Naver/Seznam 也已收到提交
• 后续发新文章，部署时自动提交 IndexNow，无需手动操作

这次排查最大的感悟：SEO 里 90% 的问题都是”少了一行标签”。canonical、description、robots.txt 这些基础项做好，剩下的就是内容质量和耐心。

项目是干什么的#

把 AstrBot（开源 AI 聊天机器人框架，可视化面板配置 OpenAI / Claude / Gemini / 本地 Ollama 等模型）+ NapCat（QQ / OneBot 协议桥接，扫码登录）打包进一个 Docker 镜像，git push 到 Hugging Face Space 就能跑。

HF 的 CPU Basic 免费档就够了，不需要服务器，不需要备案。

亮点在哪#

1. 数据全量备份，重启不丢

这是我觉得最值钱的部分。Space 每次重建容器都会被清空，所以项目内置了一个 sync 守护进程：

• 启动时从远端恢复数据（配置、会话、QQ 登录态）；
• 运行期间每 3 分钟自动 commit + push 一次；
• 大于 60MB 的文件自动走 LFS（git-lfs 协议），不会把仓库撑爆。

备份目标可以选 GitHub 仓库或 Hugging Face 仓库，GIT_BACKEND 一行切换。想把所有数据都放 HF 也行。

2. 三个开关，改一行配置就生效

1
# config.env
2
ENABLE_NAPCAT=true    # 是否启动 NapCat
3
ENABLE_GIT_PUSH=true  # 是否推送备份到远端
4
ENABLE_HF_PUSH=true   # 是否上传大文件到 LFS

改完推上去自动重新构建，不用改代码。

3. 单端口网关，路由可视化

所有服务（AstrBot 面板、NapCat WebUI、文件管理）都挂在同一个 7860 端口下，路由规则在 /admin/ui/ 页面里可视化编辑，不用懂 nginx。

部署就三步#

1. Hugging Face 上建一个 Space（SDK 选 Docker，建议 Private），再建一个空的 model 仓库当备份仓库；
2. Secrets 里填 HF_REPO 和 HF_TOKEN（写权限 token）；
3. git push 上去，等构建完成，打开 Space 地址。

初始账号是 astrbot，密码在启动日志里打印一次，记得去 /admin/ui/ 改掉默认路由密码 admin。

项目地址#

• GitHub：qwc-ch/Astrbot-Napcat-huggingface（MIT 协议）

我自己的部署就跑在 HF 免费档上，目前体验：构建一次约 10 分钟，日常占用很低，Bot 常驻不掉线。如果你正好在找地方安家你的 AstrBot，可以试试。

第一步，建个 Space#

打开 https://huggingface.co/new-space，名字随便起，SDK 记得选 Docker，不想被别人看到就勾 Private。建好之后可以去 Settings 里看一眼，免费的 CPU 档有个自动休眠的选项。

第二步，把代码推上去#

如果你本地已经有这个仓库，不用 clone 过去再拷文件，直接加一个远端就能推：

1
git clone https://github.com/MoYangking/Astrbot-Napcat-huggingface.git
2
cd Astrbot-Napcat-huggingface
3

4
git remote add hf https://<你的HF用户名>:<HF_TOKEN>@huggingface.co/spaces/<用户名>/<Space名>
5
git push --force hf main

Token 在 https://huggingface.co/settings/tokens 生成，权限选 Write 就行。

推完之后去 Space 页面点 Build，第一次构建大概二十分钟到四十分钟，别急着刷新，等它自己跑完。

第三步，配置备份#

在 Space 的 Settings → Variables and secrets 里加两个变量：

前提是你得先在 GitHub 建一个空的 Private 仓库，比如叫 astrbot-backup，PAT 在 https://github.com/settings/tokens 生成，勾上 repo 权限。

填完之后 Space 会自动重启。Sync 守护进程会把 AstrBot/data/ 每三分钟往备份仓库推一次，先 pull 再 commit 再 push，两边不会打架。这一对变量不配也能跑，但容器一重启数据就没了，到时候懂的都懂。

第四步，第一次登录#

访问 https://<space名>.hf.space/，有几个入口：

• / 是 AstrBot 控制台。新版首次登录账号固定是 astrbot，密码是随机生成打印在日志里的，去运行日志里搜 Initial password 就能看到。
• /admin/ui/ 是路由管理，默认密码 admin，建议进去改掉。
• /webui/ 是 NapCat 的界面，个人 QQ 号扫码登录用的，只用腾讯官方机器人可以跳过。

第五步，防休眠#

免费档四十八小时没访问就休眠，所以要定时去”戳”它一下。在仓库里加个 workflow，GitHub Actions 会替你每天戳三次：

1
name: Keep HF Space Alive
2
on:
3
  schedule:
4
    - cron: "0 */8 * * *"
5
  workflow_dispatch:
6
jobs:
7
  ping:
8
    runs-on: ubuntu-latest
9
    steps:
10
      - run: curl -sS -o /dev/null -H "Authorization: Bearer ${{ secrets.HF_TOKEN }}" https://<你的space名>.hf.space/

然后在仓库的 Settings → Secrets → Actions 里加一个 HF_TOKEN 就行。一天三次请求，Actions 的免费额度完全够用。

一些要提前知道的局限#

踩过的坑#

第一个是 FROM ubuntu:latest，六月份之后 latest 已经指向 26.04 了，OpenResty 的 apt 源还没跟上，构建直接 404 失败。改成 FROM ubuntu:24.04 就好了。

第二个是浏览器打开 404。Space 第一次启动会下载两百来兆的 AstrBot 前端资源，下载没完成之前 / 就是 404，等下载到 100% 刷新一下就好，不是坏了。

第三个是没配备份那一对变量的话，AstrBot 和 NapCat 会卡三十分钟起不来——Sync 守护进程拿不到配置会崩，标记文件永远不写，其他服务就干等超时。我给守护进程加了”没配置就直接放行”的处理，已经合到仓库里了。

总的来说，无服务器方案的核心矛盾就是拿在线率换零成本。这套路子数据有 GitHub 兜底，唯一的妥协是休眠后的冷启动，对个人机器人来说这个妥协还算能接受。

原因分析#

headless Chrome 在无 GPU 环境下默认禁用 WebGL 渲染。站点通过 WebGL 绘制的 3D/动画内容无法初始化，页面就只剩下一块黑色区域（有时带报错提示）。之前截图工具的 Chrome 启动参数里是 --disable-gpu，等于直接关掉了 GPU 相关的所有能力。

解决方案#

Chrome 支持通过 SwiftShader 做 WebGL 的软件渲染——没有 GPU 也能用 CPU 模拟渲染出 WebGL 内容。改动 screenshot.py 里的 Chrome 启动参数：

1
options = Options()
2
options.add_argument("--headless=new")
3
options.add_argument("--no-sandbox")
4
options.add_argument("--disable-dev-shm-usage")
5
# WebGL 软件渲染（Spline/Live2D 等 WebGL 内容在 headless 下默认不渲染，产生黑块）
6
# 新版 Chrome 需要 --enable-unsafe-swiftshader 才允许软件 WebGL
7
options.add_argument("--use-gl=angle")
8
options.add_argument("--use-angle=swiftshader")
9
options.add_argument("--enable-unsafe-swiftshader")
10
options.add_argument("--ignore-gpu-blocklist")
11
options.add_argument("--disable-extensions")
12
options.add_argument("--disable-software-rasterizer")
13
options.add_argument(f"--window-size={WINDOW_WIDTH},{WINDOW_HEIGHT}")

关键点：

• 移除 --disable-gpu，它会把 GPU 相关能力整个关掉
• --use-gl=angle + --use-angle=swiftshader：ANGLE 层之上跑 SwiftShader 软件实现
• --enable-unsafe-swiftshader：新版 Chrome 的必需参数，没有它软件 WebGL 依然不允许启用
• --ignore-gpu-blocklist：忽略对软件渲染器的黑名单限制

验证#

改完后对含 WebGL 内容的友链站点重新截图，Spline / Live2D 内容可以正常渲染，黑块消失。磁盘没有独立 GPU 的 CI 环境（GitHub Actions / 国内流水线）同样适用。

备注#

• 该修复已通过 PR 提交到上游项目：check-flink
• 此方案是”尽力”渲染：个别站点可能仍有兼容性问题，必要时可再叠加截图后黑区检测兜底
• 如果遇到 WebGL 内容加载慢，可适当调大截图前的等待时间（PAGE_LOAD_WAIT）

ip优选#

Vercel官方支持ip优选，并维维护了一条中国优化的 CNAME

1
cname-china.vercel-dns.com

只需替换为此cname，既可完成优选。

地区优选#

Vercel默认的函数的运行区域是美国东部，更改很简单只需 进入已部署的项目 → Settings → Functions → Functions Region 然后取消勾选美国东部，勾选香港，日本，新加坡等亚太地区，这里有一个坑免费计划只能选一个地区。

CDN缓存配置#

Vercel 默认情况下，你的主 HTML 根本命中不了缓存。vercel.json中可以配置。

1
{
2
  "buildCommand": "pnpm run build",
3
  "outputDirectory": "dist",
4
  "installCommand": "pnpm install",
5
  "framework": "astro",
6
  "headers": [
7
    {
8
      "source": "/(.*)",
9
      "headers": [
10
        {
11
          "key": "X-Content-Type-Options",
12
          "value": "nosniff"
13
        },
14
        {
15
          "key": "X-Frame-Options",
16
          "value": "SAMEORIGIN"
17
        },
18
        {
19
          "key": "X-XSS-Protection",
20
          "value": "1; mode=block"
21
        },
22
        {
23
          "key": "Referrer-Policy",
24
          "value": "strict-origin-when-cross-origin"
25
        },
26
        {
27
          "key": "Cache-Control",
28
          "value": "public, max-age=0, s-maxage=31536000, must-revalidate"
29
        }
30
      ]
31
    },
32
    {
33
      "source": "/_astro/(.*)",
34
      "headers": [
35
        {
36
          "key": "Cache-Control",
37
          "value": "public, max-age=31536000, immutable"
38
        }
39
      ]
40
    }
41
  ]
42
}

观察现象#

对线上逐路径探测，得到如下行为矩阵：

关键信息：

1. 非 HTML 静态资源 200，说明部署确实上传了文件；
2. 所有 HTML 页面 404，说明 HTML 部分出了问题；
3. *.html 请求被 308 重定向，说明存在 cleanUrls 风格的路由规则。

排查过程#

1
server: Vercel
2
x-vercel-cache: HIT

1
curl -H "Authorization: Bearer $TOKEN" \
2
  "https://api.vercel.com/v13/deployments/<id>/files"

1
{
2
  "overrides": {
3
    "index.html": { "path": "index" },
4
    "about/index.html": { "path": "about/index" }
5
  },
6
  "routes": [
7
    { "src": "^/(?:(.+)/)?index(?:\\.html)?/?$", "headers": { "Location": "/$1" }, "status": 308 }
8
  ]
9
}

1
/about 200    /archive 200    /search 200
2
/posts 404    /gallery 404    /dynamic 404     （这三个目录里还有子目录）

1
output/static/about/index.html      # 普通文件 529060 字节（正常）
2
output/static/posts/astbot/index.html -> /home/qwc/Firefly/dist/posts/astbot/.l2s..l2s.index.html0001.00010001   （符号链接！）

为什么新版本 CLI 有问题，旧版本没问题#

这次问题的核心在 Vercel CLI 58.x 引入的 l2s（large-file storage）上传优化。它的本意是把大文件切分成约 1MB 的小块（.l2s.<文件名>0001、0002…），以便内容寻址去重、并发上传、断点续传，服务器端再重组。57 和 58 都用了分片，但实现方式截然不同：

58.7.1 的具体问题有两个：

1. symlink 目标写死成本机绝对路径：posts/astbot/index.html -> /home/qwc/Firefly/dist/posts/astbot/.l2s..l2s.index.html0001.00010001。这个路径只在本机存在，上传到 Vercel 后无法解析，文件”在列表里、读不出内容”。
2. 对已分片的文件再次分片：正常的 l2s 分片命名是 .l2s.index.html0001.0001，而 58.7.1 在部分文件上生成了嵌套前缀 .l2s..l2s.index.html0001.00010001，说明分片逻辑对”分片产物”又跑了一遍，symlink 指向了错误的目标。

而 57 的处理方式是硬链接：index.html 和 .l2s.index.html0001.0002 是同一个 inode 的两个目录项，index.html 始终是真实文件、内容完整。上传时 CLI 读到的就是完整数据，服务器端重组无需依赖符号链接。

为什么”以前正常、某一天突然全站 404”：CI 里用的是 npx vercel（不带版本号），npx 每次拉取的都是最新版。以前最新版还是 57.x（实现正确），某次升级到 58.7.1（实现有 bug）后，CI 的每一次部署都带着坏掉的符号链接上传——所以在 GitHub Actions 部署日志全部成功的情况下，线上依旧全站 404。

根因总结#

两个问题叠加：

1. cleanUrls: true 与 Astro 的 trailingSlash: "always" 冲突 —— HTML 被改名导致带尾斜杠的路由全部 404；
2. Vercel CLI 58.x 的 l2s 上传 bug —— 更大的问题，大文件被替换成失效符号链接，导致部分目录的 HTML 无法读取。

两个问题都只在 Vercel 这边出现，Cloudflare / EdgeOne 的部署链路不受影响。

解决方案#

经验总结#

• 部署”成功”不等于内容完整，排查时对比线上返回值与本地产物而不是只看状态码；
• 对于知名 PaaS 的 CLI，锁定版本是避免”莫名其妙” bug 的最有效手段（npx vercel → npx vercel@57）；
• 多平台部署（CF / EdgeOne / Vercel）有交叉验证的作用：同一份 dist，wrangler 正常、vercel CLI 异常，直接指向 CLI 本身的问题。

整体思路#

改造的核心是用一个自定义的 Svelte 组件替换掉原来的 Twikoo 评论挂件。组件直接与 Twikoo 的 API 通信，获取留言数据，然后以聊天气泡的形式渲染出来。

这样做的几个好处：

• 视觉上更统一，可以完全控制样式
• 交互更灵活，可以加一些原版挂件没有的功能
• 不需要额外引入第三方 UI，自己写更容易控制体积

API 通信#

组件通过 fetch 直接调用 Twikoo 的 API 接口，主要就两个操作：

• COMMENT_GET：获取指定路径（这里是 /guestbook/）下的所有留言
• COMMENT_SUBMIT：提交新的留言

Twikoo 返回的数据是嵌套结构的——每条留言下可能有若干条回复。但聊天界面不适合树形展示，所以组件把整个回复树拍平成一个按时间排序的列表，回复内容前面加上 @昵称 的前缀，这样上下文就很清晰了。

聊天气泡#

整个界面是最像聊天软件的部分。每条消息是一行，包含头像、昵称、时间和气泡内容。

头像 36 像素的圆形，优先显示 Gravatar 头像，没有的话显示昵称首字。自己的消息靠右对齐，其他人的靠左。

气泡的样式靠 border-radius 的不对称处理来实现——别人的气泡是左下角直角、其他角圆角；自己的气泡反过来，右下角直角。这种不对称感就是聊天气泡的视觉特征。

自己的气泡使用主题色作为背景，白色文字，在视觉上突出区分。管理员的消息也使用相同的样式。

区分自己与他人#

组件通过 localStorage 存储用户的留言档案（昵称、邮箱、网址），提交时会记录这条留言的 ID。再次加载时，如果某条留言的邮箱或 ID 匹配，就把它标记为”自己的消息”，显示在右侧。

自动刷新#

留言板每隔 30 秒会自动请求一次新数据，新留言会即时出现，不需要手动刷新页面。但如果用户已经向上滚动浏览历史消息，自动滚动会暂停，只有停留在底部时才会自动滚到最新消息。

个人资料弹窗#

首次留言时会弹出一个资料填写框，输入昵称和邮箱后才会显示发送栏。这些信息存在 localStorage 里，下次访问就不用再填了。

回复功能#

每条消息悬浮时会出现”回复”按钮，点击后会在输入框上方显示”回复 @某某”的提示条，发送时会将这条回复关联到原消息上。点击提示条上的叉号可以取消回复。

一些样式细节#

所有样式都写在 Svelte 组件的 <style> 标签里，使用 gb__ 前缀来避免污染全局样式。

发送按钮是圆形的，不可用时有降低透明度。消息列表限制了最大高度（520px），超出可以滚动。每条新消息出现时有一个轻微的淡入动画，让感觉更自然。

深色模式的支持没有额外处理，因为组件直接使用了 CSS 变量 var(--primary)、var(--card-bg) 这些主题变量，切换主题时颜色会自动适配。

最后#

这个改造其实不复杂，核心就是”把树形评论拍平成聊天记录”。但效果还是挺明显的——留言板不再是冷冰冰的评论区，更像一个可以聊天的空间。如果你也用的 Twikoo，不妨试试类似的改造，让访客感觉更轻松一些。

什么是朋友圈#

这里的”朋友圈”不是微信那个朋友圈，而是博客圈里的一种内容聚合页。它会抓取友链列表中各位博友的最新文章，汇总展示在一个页面里。效果类似于一个迷你 RSS 阅读器，但更轻量，也更有人情味。

你可以在导航栏找到”钓鱼”入口（之所以叫钓鱼，是因为逛朋友们的博客就像钓鱼一样，你永远不知道下一秒会钓上来什么有趣的内容）。

核心思路#

实现思路其实不复杂：每个友链条目都可以配置一个 RSS 地址，系统定期去抓取这些 RSS 源，把文章信息整理后展示出来。

整个流程可以分为三步：

1. 配置友链时附带 RSS 地址
2. 服务端抓取并解析所有 RSS 源
3. 前端展示为卡片列表

数据源：friendsConfig#

所有的友链信息集中管理在 friendsConfig.ts 里。每个友链除了常规的站点名、头像、网址外，还可以配置一个 rss 字段：

1
{
2
  title: "友人A",
3
  siteurl: "https://example.com",
4
  imgurl: "https://example.com/avatar.png",
5
  rss: "https://example.com/feed.xml",
6
  enabled: true
7
}

没有配置 RSS 的友链不会出现在朋友圈里，但会正常显示在友情链接页面。这样设计的好处是，每个人可以自由选择是否参与内容聚合。

数据抓取：rss-utils#

抓取逻辑集中在 rss-utils.ts 里。它同时支持 RSS 2.0 和 Atom 两种格式，通过 Promise.allSettled 并行抓取所有友链的 Feed，单个源失败不会影响其他源。

每个 Feed 最多取 5 篇文章，超时时间设为 8 秒。抓取到的文章会解析标题、链接、发布时间、摘要等信息，摘要会被截断到 200 字以内。

API 端点#

/api/circle.json 这个接口负责整合数据。它在请求时调用抓取逻辑，然后将所有文章按发布时间排序，同时返回一些统计数据：

• 好友总数
• 活跃好友数（成功抓取到文章的数量）
• 文章总数
• 最后更新时间

接口会设置一小时的缓存，避免频繁请求给朋友们的服务器造成压力。

前端展示：CircleFeed.svelte#

前端是一个完全客户端渲染的 Svelte 组件。页面加载时会请求上述接口，拿到数据后以卡片网格的形式展示。

每张卡片包含：

• 文章标题（最多两行，超出省略）
• 作者头像和名称
• 发布时间
• 文章摘要

卡片排列采用自适应网格，auto-fill 配合 minmax(260px, 1fr)，在不同屏幕宽度下都能合理展示。鼠标悬停时作者头像会高亮，增加一点交互的趣味。

分页逻辑也在客户端完成，默认每页 20 条，点击”加载更多”逐步展示。排序支持按发布时间和最近更新两种方式，切换后即时生效，不需要重新请求接口。

一些细节#

页面顶部会随机展示一条最新的文章通知（取最近 6 篇中的随机一篇），算是一个小彩蛋。统计栏可以显示好友总数、活跃数和文章数，也可以选择关闭。

评论区在朋友圈页面是可选的，如果配置了评论系统且没有禁用，文章列表下方会显示评论区，方便朋友们留言互动。

最后想说的是，这个功能的初衷很简单——希望博客之间能有更多的连接。友链不只是单向的跳转，它也可以变成一种内容的流动。如果你也有自己的博客，不妨试试在你的站点上搭建类似的功能，感受一下博客圈的温度。

Cloudflare#

Cloudflare 依托其全球边缘网络，将计算和存储部署在离用户较近的节点上。以下是其四个核心服务。

Vercel#

Vercel 与前端的框架整合较好，提供了从开发到部署的一体化体验。

D1（SQLite）与 PG 的差异#

D1 基于 SQLite，PostgreSQL（Neon）是一个独立的关系型数据库，两者差异不小：

什么项目适合什么：

D1 适合个人博客、小型 API、配置管理、原型项目、边缘地理位置需要低延迟的场景。不需要复杂查询和高并发，追求简单和免运维。

PostgreSQL 适合需要事务完整性、复杂查询、高并发的项目：如电商系统、论坛、内容管理系统、数据分析后台等。如果已经有现成的 PG 应用迁移过来也更合适。

想法#

这几个功能里，后头没想法用伪后，还是做真后端。AI聊天页面我打算用Cloudflare Workers 不存任何记录，所以并不依赖任何数据库。其他的想到了在加……

为什么要搞这个#

每次手动构建、再部署，累不累啊？反正我累了。目标是：推送代码到 main 分支后，GitHub Actions 自动帮你搞定三件事：

1. 构建 Astro 项目（让它在 CI 里卷）
2. 把构建产物推送到 build 分支（留个备份）
3. 部署到 Cloudflare Workers（上线，收工）

一条龙服务，你只需要 git push，剩下的交给机器人。

整体流程#

1
push main → checkout → 安装依赖 → pnpm build → 推送 dist 到 build 分支 → wrangler deploy

实现思路#

1
on:
2
  push:
3
    branches: [main]
4
  workflow_dispatch:

1
- name: Setup pnpm
2
  uses: pnpm/action-setup@v4
3
  with:
4
    version: 9.14.4
5

6
- name: Setup Node.js
7
  uses: actions/setup-node@v4
8
  with:
9
    node-version: '24'
10
    cache: 'pnpm'  # 必须在 pnpm 安装之后

1
- name: Install Dependencies
2
  run: pnpm install --frozen-lockfile
3

4
- name: Build
5
  run: pnpm run build

1
- name: Push to build branch
2
  uses: peaceiris/actions-gh-pages@v4
3
  with:
4
    github_token: ${{ secrets.GITHUB_TOKEN }}
5
    publish_dir: ./dist
6
    publish_branch: build

1
- name: Deploy to Cloudflare Workers
2
  run: npx wrangler deploy
3
  env:
4
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
5
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

完整源码#

1
# 构建项目并将产物推送到 build 分支，然后部署到 Cloudflare Workers
2
name: Build to Branch
3

4
# 当推送到 main 分支时触发，也支持手动触发
5
on:
6
  push:
7
    branches: [main]
8
  workflow_dispatch:
9

10
# 需要写入权限来推送 build 分支
11
permissions:
12
  contents: write
13

14
# 同一时间只运行一个构建任务，取消正在运行的旧任务
15
concurrency:
16
  group: build
17
  cancel-in-progress: true
18

19
jobs:
20
  build:
21
    runs-on: ubuntu-latest
22
    steps:
23
      # 检出代码
24
      - name: Checkout
25
        uses: actions/checkout@v4
26

27
      # 安装 pnpm 包管理器
28
      - name: Setup pnpm
29
        uses: pnpm/action-setup@v4
30
        with:
31
          version: 9.14.4
32

33
      # 安装 Node.js 并配置 pnpm 缓存
34
      - name: Setup Node.js
35
        uses: actions/setup-node@v4
36
        with:
37
          node-version: '24'
38
          cache: 'pnpm'
39

40
      # 安装项目依赖
41
      - name: Install Dependencies
42
        run: pnpm install --frozen-lockfile
43

44
      # 构建项目：生成图标 → Astro 构建 → Pagefind 索引
45
      - name: Build
46
        run: pnpm run build
47

48
      # 推送 dist 目录到 build 分支
49
      - name: Push to build branch
50
        uses: peaceiris/actions-gh-pages@v4
51
        with:
52
          github_token: ${{ secrets.GITHUB_TOKEN }}
53
          publish_dir: ./dist
54
          publish_branch: build
55

56
      # 使用 wrangler CLI 部署到 Cloudflare Workers
57
      - name: Deploy to Cloudflare Workers
58
        run: npx wrangler deploy
59
        env:
60
          # Cloudflare API Token，需要 Edit Cloudflare Workers 权限
61
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
62
          # Cloudflare 账户 ID，在 Dashboard 右侧栏可见
63
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

需要配置的 Secrets#

在 GitHub 仓库 Settings → Secrets and variables → Actions 里加两个 secret，不加的话 workflow 会直接报错退出。

API Token 要选 “Edit Cloudflare Workers” 模板，这个模板包含 Workers 脚本编辑权限，部署够用了。

注意事项#

• --frozen-lockfile 是个好东西，确保 CI 里不会偷偷给你更新依赖版本，避免”我本地能跑线上挂了”的经典剧情
• concurrency 配置能避免同时跑多个构建任务，省点 CI 分钟数
• wrangler deploy 会老老实实读取仓库根目录的 wrangler.toml，所以记得把这个文件提交上去
• build 分支只包含 dist/ 的内容，源码不会泄露，放心用

涉及的文件#

整个组件涉及两个文件：

组件是怎么实现的#

这个组件的 frontmatter 是空的，没有任何服务端逻辑。所有事情都在浏览器端的 <script> 和 <style> 里完成。

1
#welcome-toast（固定在右下角，z-50）
2
└── 一个卡片 div（白色背景、圆角、阴影）
3
    ├── 👋 表情
4
    ├── 文字区
5
    │   ├── 问候语（一开始显示"正在加载..."，后面会变成具体地址）
6
    │   └── 副标题"欢迎来到我的博客"
7
    └── 关闭按钮（一个 ×）

1
// 用 sessionStorage 做会话标识，防止重复弹出
2
const VISIT_SESSION_KEY = 'blog_visit_flag';
3
let hasShownToast = false;
4

5
// 创建 Toast 的 DOM 结构，插入到页面上
6
function createWelcomeToast()
7

8
// 关掉 Toast：先滑出去，500ms 后把节点从 DOM 里移掉
9
function closeWelcomeToast()
10

11
// 请求一个免费的 IP API，拿到访客的位置信息
12
async function fetchLocation()
13

14
// 整个弹出流程的"导演"：创建 → 滑入 → 拿位置 → 5秒后自动关闭
15
async function showWelcomeToast()
16

17
// 入口函数：判断是不是第一次访问，是的话才弹
18
function initWelcome()

执行顺序#

说白了就是这么个流程：

1
if (document.readyState === 'loading') {
2
    document.addEventListener('DOMContentLoaded', initWelcome);
3
    document.addEventListener('astro:page-load', initWelcome);  // Swup 专用
4
} else {
5
    initWelcome();
6
}

1
(window as any).closeWelcomeToast = closeWelcomeToast;

在 MainGridLayout 里怎么放的#

MainGridLayout 是 Firefly 的主布局，导航栏、壁纸、侧边栏、Footer 都在这里面。WelcomeToast 在第 7 行被 import，然后放在了第 858 行：

1
import WelcomeToast from "@components/widget/WelcomeToast.astro";

具体位置是在 #swup-container 里面、<slot /> 后面：

1
<main id="swup-container" class="transition-main">
2
    <div id="content-wrapper">
3
        <slot></slot>
4
    </div>
5
    <WelcomeToast />
6
</main>

整个布局大概是这么个层级关系：

1
Layout.astro
2
└── MainGridLayout.astro
3
    ├── Navbar（导航栏）
4
    ├── Wallpaper（背景壁纸）
5
    ├── <main id="swup-container">      ← Swup 的容器，导航时会替换这里面的内容
6
    │   ├── <slot>                       ← 每个页面的具体内容
7
    │   └── <WelcomeToast />             ← 放在内容后面
8
    ├── Footer（页脚）
9
    └── FloatingControls（浮动控制按钮）

总结#

WelcomeToast 说白了就是一个浏览器端的欢迎弹窗，用 sessionStorage 保证每个会话只弹一次，用 IP API 拿位置做个性化问候，5 秒自动消失。放在 Firefly 主题的 MainGridLayout 里，和 Swup 的 SPA 导航机制配合得很好。

为什么要加统计#

搞个博客总想知道有没有人看吧。Umami 是个轻量级的统计工具，部署简单，也不会像 Google Analytics 那样隐私问题一堆。

但问题来了：Umami 自带的分享链接打开就是一个独立页面，跟博客风格完全不搭。所以我把它做成了一个侧边栏组件，嵌进博客里，打开就能看到访问数据，顺眼多了。

准备工作#

前提是你已经部署好了 Umami，然后拿到一个分享链接。后面填进代码里就行。

添加组件#

在 src/components/widget/ 目录下新建一个 UmamiStats.astro 文件，把下面的代码贴进去：

1
---
2
import WidgetLayout from "../common/WidgetLayout.astro";
3

4
interface Props {
5
  class?: string;
6
  style?: string;
7
}
8
const { class: className, style } = Astro.props;
9
---
10

11
<WidgetLayout name="统计" class:list={["umami-stats-container", className, "cursor-pointer transition-opacity active:scale-95"]} {style}>
12
    <a target="_blank" rel="noopener noreferrer" class="block umami-link">
13
        <div class="text-center py-2">
14
            <div class="text-3xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-pageviews">-</div>
15
            <div class="text-sm text-neutral-500 dark:text-neutral-400">总浏览量</div>
16
        </div>
17
        <div class="grid grid-cols-2 divide-x divide-neutral-200 dark:divide-neutral-700 text-center pt-2">
18
            <div class="px-2">
19
                <div class="text-xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-visits">-</div>
20
                <div class="text-sm text-neutral-500 dark:text-neutral-400">访问数</div>
21
            </div>
22
            <div class="px-2">
23
                <div class="text-xl font-bold text-neutral-900 dark:text-neutral-100 umami-total-visitors">-</div>
24
                <div class="text-sm text-neutral-500 dark:text-neutral-400">游客数</div>
25
            </div>
26
        </div>
27
    </a>
28
</WidgetLayout>
29

30
<script>
31
const UMAMI_CONFIG = {
32
    shareUrl: '你的分享链接',
33
};
34

35
let __UMAMI_INTERNAL = {
36
    baseUrl: '',
37
    websiteId: '',
38
    shareToken: '',
39
    shareId: '',
40
    isReady: false
41
};
42

43
const FALLBACK_STATS = {
44
    pageviews: 1000,
45
    visits: 1000,
46
    visitors: 1000,
47
};
48

49
async function initUmamiConfig() {
50
    try {
51
        const sharePath = UMAMI_CONFIG.shareUrl.split('/share/')[1];
52
        if (!sharePath) throw new Error('Invalid Umami Share URL');
53

54
        let apiBase = '';
55
        if (UMAMI_CONFIG.shareUrl.includes('cloud.umami.is') || UMAMI_CONFIG.shareUrl.includes('analytics.umami.is')) {
56
            const region = UMAMI_CONFIG.shareUrl.includes('/analytics/eu/') ? 'eu' : 'us';
57
            apiBase = `https://cloud.umami.is/analytics/${region}/api`;
58
        } else {
59
            const urlObj = new URL(UMAMI_CONFIG.shareUrl);
60
            apiBase = `${urlObj.origin}/api`;
61
        }
62

63
        const res = await fetch(`${apiBase}/share/${sharePath}`);
64
        if (!res.ok) throw new Error(`Failed to fetch share config: ${res.status}`);
65
        const data = await res.json();
66

67
        __UMAMI_INTERNAL = {
68
            baseUrl: apiBase,
69
            websiteId: data.websiteId,
70
            shareToken: data.token,
71
            shareId: data.shareId,
72
            isReady: true
73
        };
74

75
        const links = document.querySelectorAll('.umami-link');
76
        links.forEach(link => link.setAttribute('href', UMAMI_CONFIG.shareUrl));
77

78
    } catch (e) {
79
        console.error('Umami Config Init Failed:', e);
80
    }
81
}
82

83
function formatNumber(num: number): string {
84
    if (num >= 1000000) {
85
        return (num / 1000000).toFixed(1) + 'M';
86
    } else if (num >= 1000) {
87
        return (num / 1000).toFixed(1) + 'K';
88
    }
89
    return Math.round(num).toString();
90
}
91

92
function setStats(values: { pageviews: number; visits: number; visitors: number }) {
93
    const pageviewsElements = document.querySelectorAll('.umami-total-pageviews');
94
    const visitsElements = document.querySelectorAll('.umami-total-visits');
95
    const visitorsElements = document.querySelectorAll('.umami-total-visitors');
96

97
    const easeOutCubic = (t: number) => 1 - Math.pow(1 - t, 3);
98
    const animHandles = new Map<HTMLElement, number>();
99

100
    const animateStat = (el: HTMLElement | null, to: number, duration = 2000) => {
101
        if (!el) return;
102

103
        const prev = animHandles.get(el);
104
        if (prev) cancelAnimationFrame(prev);
105

106
        const from = 0;
107
        const startTime = performance.now();
108

109
        const tick = (now: number) => {
110
            const elapsed = now - startTime;
111
            const progress = Math.min(1, elapsed / duration);
112
            const easedProgress = easeOutCubic(progress);
113

114
            const current = from + (to - from) * easedProgress;
115
            el.textContent = formatNumber(current);
116

117
            if (progress < 1) {
118
                animHandles.set(el, requestAnimationFrame(tick));
119
            }
120
        };
121
        animHandles.set(el, requestAnimationFrame(tick));
122
    };
123

124
    pageviewsElements.forEach(el => animateStat(el as HTMLElement, values.pageviews));
125
    visitsElements.forEach(el => animateStat(el as HTMLElement, values.visits));
126
    visitorsElements.forEach(el => animateStat(el as HTMLElement, values.visitors));
127
}
128

129
async function fetchUmamiStats() {
130
    if (!__UMAMI_INTERNAL.isReady) {
131
        await initUmamiConfig();
132
    }
133

134
    if (!__UMAMI_INTERNAL.isReady) {
135
        setStats(FALLBACK_STATS);
136
        return;
137
    }
138

139
    try {
140
        const endAt = Date.now();
141
        const startAt = 0;
142
        const url = `${__UMAMI_INTERNAL.baseUrl}/websites/${__UMAMI_INTERNAL.websiteId}/stats?startAt=${startAt}&endAt=${endAt}&unit=hour&timezone=Asia%2FShanghai`;
143

144
        const response = await fetch(url, {
145
            headers: {
146
                'x-umami-share-context': '1',
147
                'x-umami-share-token': __UMAMI_INTERNAL.shareToken
148
            }
149
        });
150

151
        if (!response.ok) throw new Error(`HTTP ${response.status}`);
152
        const data = await response.json();
153
        const getValue = (field: any) => (typeof field === 'object' ? field?.value : field) || 0;
154

155
        setStats({
156
            pageviews: getValue(data.pageviews),
157
            visits: getValue(data.visits),
158
            visitors: getValue(data.visitors),
159
        });
160

161
    } catch (error) {
162
        console.error('Umami Fetch Failed:', error);
163
        setStats(FALLBACK_STATS);
164
    }
165
}
166

167
let __umamiStatsStarted = false;
168
function startUmamiStats() {
169
    if (__umamiStatsStarted) return;
170
    __umamiStatsStarted = true;
171
    fetchUmamiStats();
172
}
173

174
function initUmamiStatsVisibility() {
175
    const containers = document.querySelectorAll('.umami-stats-container');
176
    const io = new IntersectionObserver((entries) => {
177
        let isAnyVisible = false;
178
        entries.forEach(entry => {
179
            if (entry.isIntersecting) isAnyVisible = true;
180
        });
181

182
        if (isAnyVisible) {
183
            startUmamiStats();
184
            io.disconnect();
185
        }
186
    }, { threshold: 0.1 });
187

188
    containers.forEach(container => io.observe(container));
189
}
190

191
initUmamiStatsVisibility();
192

193
if (window.swup) {
194
    window.swup.hooks.on('page:view', () => {
195
        __umamiStatsStarted = false;
196
        initUmamiStatsVisibility();
197
    });
198
}
199
</script>