Sanya

博客 AI 助手“无回复”根因：反代网关地址缓存过期导致 502

Mon, 07 Sep 2026 00:00:00 GMT

博客 AI 助手“无回复”的完整排查记录：根因不是服务崩溃、也不是会话丢失，而是 Nginx 反向代理在后端容器重建后仍沿用缓存中的旧地址向服务端转发，导致网关错误（502）。修复方式是借助容器网络内置 DNS + 变量转发，让网关每次请求都重新解析后端容器名，从而在约 10 秒内自动跟上容器地址变化，从根上消除这一整类问题。

问题#

博客页面的 AI 助手平时正常，某天突然“一直弹提示、问什么都不回复”，同一批老对话也续不上。客户端始终拿不到访问令牌，任何对话请求都无响应。

根因#

前端每次发 Coze 消息前，先向后端网关请求一次访问令牌（POST /api/coze/token/init）。这一步被网关以 502 拒绝。真正根因不是后端崩溃、不是内存耗尽、也不是会话/刷新逻辑，而是 Nginx 反向代理的【上游地址缓存过期】。

Nginx 在启动或重载的那一刻，会把后端容器名一次性解析成内网地址并缓存下来。本次把后端从单体拆成独立容器（微服务拆分）后触发了容器重建，容器拿到新地址；但 Nginx 仍拿着缓存里的旧地址去连接。旧地址此刻已被另一个容器占用、且对应服务的监听端口也变了，于是连接被拒、向上游抛 502。后端应用本身完全健康，直连容器地址仍返回 200。

修复方案#

让 Nginx 改成“每次请求都重新解析”的方式：在配置顶层启用容器内网 DNS 解析器，并把各后端反代入口从“固定上游”改为“变量转发”。

1
# 容器网络内置 DNS（127.0.0.11），供变量 proxy_pass 每次请求重新解析
2
resolver 127.0.0.11 valid=10s ipv6=off;
3

4
location /api/coze/ {
5
    # 变量形式转发 → 每次请求都经内网 DNS 解析容器名
6
    set $coze_upstream http://coze-gateway:8080;
7
    proxy_pass $coze_upstream;
8
}

关键点：必须用「变量 proxy_pass + resolver」；server … resolve（upstream 自动解析）是 Nginx Plus 才有的能力，开源版 Nginx（nginx:alpine）只能走这套。容器重建换 IP 后，网关约 10 秒内自动跟上，无需任何手工重载。对每个需要转发到后端容器的入口都做同样处理；一些独立、负载小、极少重建的入口（如私有包仓库）保持原有写法不动。

如何应用#

修改网关配置模板（server/nginx/default.conf.template）：顶层加 resolver，各后端反代入口改成变量 proxy_pass。
渲染后用临时容器校验（nginx -t）。注意：校验容器必须挂到容器网络，否则解析不到尚在用的旧内联上游，会误报“找不到主机”——那是校验环境限制，不是配置问题。
先备份现有配置再替换，之后重启网关容器。因替换会生成新的文件节点，需【重启而非仅重载】才能让新配置生效。
验证：POST /api/coze/token/init 返回 200；首页 200；未带每日 JWT 的 POST /api/dify/chat 返回 401（说明已路由到 Dify 网关而非错上游）。

一条小坑#

发布到 Astro 时，若 frontmatter 的 tags 序列里写到裸数字（如 502），会被 YAML 强转成 number，而 posts 集合 schema 要求 tags 全为 string，构建会报 InvalidContentEntryDataError。需要加引号写成 "502"。

总结#

这条路径从 2026 年 9 月 7 日实测通过，彻底消除了容器重建导致的网关地址漂移 502。核心价值是把“地址缓存过期导致网关错误”这一整类问题从根上解决，同时不引入手工重启或重载的运维负担。

让博客文章携带可下载文件：随文附件功能实现记录

Wed, 19 Aug 2026 00:00:00 GMT

写技术文章时，经常想分享脚本、样例配置或打包好的工具。以前只能把内容整段贴进正文，或者丢到外部网盘——贴正文太占篇幅，网盘要跳转还要担心失效。最理想的形态是像写论文一样：正文里嵌一个下载链接，读者点击即得文件。这篇文章记录这次「随文附件下载」改造的思路、设计与踩坑。

需求背景#

博客原本只有文字和图片。遇到要分发文件（示例代码包、配置文件、小型工具）时，没有合适的载体。外部网盘体验差，临时粘贴又不可复用。希望达到的效果是：每篇文章可以有若干附件，附件以超链接形式嵌入正文，点击触发浏览器下载。

设计决策：附件不随整站部署#

第一个直觉是：把附件放进站点工程目录，随整站一起发布。但这个博客是静态站，每次发布都会把全站构建产物整体打包上传到服务器。如果把附件放进构建产物，每次部署都要全量搬运这些大文件，越积越大，拖慢部署。

于是改为双通道设计：

文章正文、样式、页面等，走原有的整站发布流程；
附件文件，走独立的上传通道，直接送到服务器上一个专用目录，不进入站点工程仓库；
Web 服务器把该专用目录挂载到站点文件路径的某个子路径下，对外提供下载。

这样附件与文章内容解耦：改正文不用重传附件，传新附件也不会触发全站重建。

实现要点#

上传脚本。本地一个脚本，从本地配置文件读取服务器地址、登录用户、密钥等连接信息（本地配置不进公开仓库）。执行时把指定文件或目录通过加密通道传送到服务器的附件目录，按文章标识分子目录存放。

失败重试与人工兜底。网络环境不稳定时，上传可能中途失败。脚本内置重试：自动重试数次、每次间隔几秒。多次失败后不再盲目重试，而是非零退出并打印排查指引——连通性检查、磁盘空间检查、手动上传命令。把”修不修”的判断交还给人，而不是静默失败或无限重试。

服务器挂载。附件目录以只读方式挂载进 Web 服务器的容器，映射到站点文件路径下的 /files/ 子路径。浏览器访问该路径时，Web 服务器按静态文件处理，直接返回文件内容并触发下载。文件名即下载后得到的文件名，无需额外路由逻辑。

正文引用。文章里用标准的 markdown 绝对链接指向附件的线上地址，例如「下载说明」。格式简单，任何 markdown 编辑器都能写。

踩坑：只读目录下创建不了挂载点#

改造时遇到一个隐蔽问题：站点根目录是以只读方式挂载进容器的，而附件目录要作为它的子目录再挂载一次。容器在只读文件系统里尝试创建新挂载点时报错，直接导致容器启动失败。

排查发现，docker 在挂载嵌套路径时，如果内层挂载点目录还不存在，会尝试自动创建——但这一步发生在只读的根目录里，必然失败。解决方式很朴素：启动容器前，先在服务器上把附件挂载点目录预先建好，再启动容器。目录已存在，嵌套挂载就成功了。

下载限流：防滥用与防带宽占满#

附件走公开的静态下载路径，理论上任何人都能访问。为了让功能可以长期稳定对外，在 Web 服务器层给下载路径加了两道限流：

请求频率限制。按访问来源 IP 计数：每个 IP 平均每秒最多 5 次下载请求，允许短时间内突发到 20 次，超过的部分直接返回「请求过多」状态码，提示稍后再试。这一道挡住脚本批量刷下载、盗链拉取等滥用。
下载速度限制。每个下载连接在文件前 8MB 全速传输，之后限制到每秒 2MB 以内。单个用户即使反复下载，也占不满服务器带宽，不影响其他访客正常浏览。

另外给下载路径关闭了缓存（每次都拿最新文件）——附件更新后，读者重新下载立刻得到新版本，不会被旧缓存误导。两道限流的数值都集中在服务器配置里，方便按实际流量调整。

使用方法#

发布带附件的文章，三步即可：

本地暂存：把附件放到本地暂存目录，按文章标识分子目录存放（该目录已排除出发布流程）；
上传：运行上传脚本，传入附件路径和文章标识，脚本自动传到服务器的附件目录并打印线上地址；
引用：在文章正文里用下载链接指向该线上地址。

上传脚本会自动重试、失败给出排查指引；若附件含敏感信息（密钥、内网地址、服务器路径），按规则不发到线上，改用占位说明。

配套：mdoc 定制化工具包#

这套博客背后还有一套定制化的「文档管理 + 发布流水线」技能（归档修复方案 → 审查 → 生成博客文章 → 自动发布）。为了让它能迁移到另一台机器，我把定制化的技能、子代理和配置打包成了便携工具包，并写了完整的部署说明——详见 mdoc 定制化工具包部署指南。

mdoc 定制化工具包：把修复文档管理系统搬到新机器

Wed, 19 Aug 2026 00:00:00 GMT

使用 AI 编程助手时，我长期维护着一套「修复方案文档管理系统」（mdoc）：每次排查、修复、改造的结论都会被归档成结构化文档，形成可搜索的个人知识库；在此基础上还有一套发布流水线，能把归档内容去敏后自动变成博客文章。这套系统是高度定制化的——命令协议、发布规则、归档格式都经过多轮打磨。本文分享的，是把它完整迁移到另一台机器的便携工具包。

mdoc 是什么#

mdoc 是一个「把修复经验沉淀成文档」的个人系统：用 /mdoc 斜杠命令管理文档，分类、命名、索引、搜索全部由 CLI 程序保证一致性；文档采用统一的格式规范，并附带一套「归档 → 审查 → 发布」的博客流水线。它的前世今生记录在 《mdoc 重构：从 Claude Code skill 到任意目录可解析的 CLI 工具库》 一文里。

问题在于：这套系统由技能、子代理、CLI 工具和配置文件共同组成，散落在本机的几个目录里，路径还是硬编码的。换一台机器就要全部重配，几乎不可能手动复刻。于是我把它们整理打包，做成了一个自包含、可移植、无敏感信息的部署工具包。

工具包里有什么#

解压后包含四类内容：

内容	作用
CLI 工具本体	纯 Python、零第三方依赖的安装包，可离线安装，负责文档系统的全部确定性操作
主技能	命令协议与发布规则：搜索、列表、创建、更新、删除、发布规范
发布流水线技能 + 三个子代理	归档 → 审查 → 发布一条龙；三个子代理各自独立工作，减少幻觉
配置模板	文档库路径、索引文件名、分类规则、内容风格等

工具包内不含任何敏感信息：所有个人路径都被替换成了 {{占位符}}，安装时按配置清单填好即可。

下载与三步部署#

📥 下载 mdoc 部署工具包

拿到压缩包后，三步即可完成部署：

安装 CLI：用 pip 安装包内的 wheel 文件，运行版本命令验证；
放置技能与子代理：把解压后的 skills 和 agents 目录复制到 Claude Code 的用户配置目录（Windows 在 C:\Users\<你>\.claude\，macOS/Linux 在 ~/.claude/）；
配置：复制配置模板为 ~/.mdoc.toml，按下表填写占位符。

需要设置的部分（配置清单）#

占位符	含义	是否必填
文档库目录	存放修复方案文档和索引文件的目录（绝对路径）	必填
博客项目目录	静态博客项目根目录（发布流水线需要）	仅用发布功能时
服务器附件目录	博客随文附件的服务器存放目录	仅用附件上传时

填好文档库目录后，系统功能即与当前机器一致；博客项目和附件相关项只在你需要发布流水线时才配置。

使用（以 Claude Code 为例）#

部署完成后，在 Claude Code 会话里直接用斜杠命令：

/mdoc 关键词 — 搜索修复方案文档
/mdoc -l — 列出文档
/mdoc -c 标题 — 新建文档
/mdoc -u 参考名 — 更新文档
/mdoc -d 参考名 — 删除文档

完整命令清单在技能文件里有速查表，也可以跑 /mdoc --help 查看。

AI 部署教程#

不想手动操作？把工具包交给新机器上的 AI 助手（Claude Code 或任何 AI CLI），粘贴下面的提示词即可：

请帮我在当前机器上部署 mdoc 工具包。工具包已解压到 某目录。

用 pip 安装其中的 CLI 安装包；

把 skills/ 和 agents/ 复制到我的 Claude Code 用户配置目录；

阅读配置模板，帮我创建 ~/.mdoc.toml，把文档库目录填成我指定的路径；

检查技能与子代理文件里的占位符，替换成我的实际路径；

运行版本命令和列表命令验证可用。

AI 会按提示逐步完成安装、放置和配置，最后给出验证结果。

安全说明#

工具包不含服务器地址、密钥、个人机器路径等敏感信息；
所有需要按本机环境填写的内容都以占位符形式给出，并集中列在配置清单里；
如果新机器与本文场景不同，只需在替换占位符时同步调整技能中的相关说明即可。

关联阅读#

工具包在博客上以附件形式提供下载，所用的随文附件机制见 《让博客文章携带可下载文件：随文附件功能实现记录》；
mdoc 系统的设计历程见 《mdoc 重构：从 Claude Code skill 到任意目录可解析的 CLI 工具库》。

mdoc 重构：从 Claude Code skill 到任意目录可解析的 CLI 工具库

Mon, 10 Aug 2026 00:00:00 GMT

作为 Claude Code 的个人技能，/mdoc 曾经把修复方案文档管理的规则全部写死在 SKILL.md 里，文档存放在 auto-memory 目录。用得越久问题越明显：规则散落在各处、命令直接读写文档文件、路径硬编码、也无法分发给别人使用。

这篇文章记录了我把 /mdoc 重构为可安装 CLI 工具库的全过程：从 core+CLI 三层分层、打包分发，到 0.1.1 版本支持任意目录解析文档库。项目已开源在 github.com/sanya2485/mdoc。

背景与目标#

原来的 /mdoc skill 把文档管理规则写死在 SKILL.md 里，问题集中在四个方面：

规则散落，维护困难
命令直接 Read/Write 文档文件，缺少抽象
路径硬编码在 skill 中，换个环境就失效
无法分发，只能自己用

重构目标很明确：把确定性操作锁进代码——分类、kebab-case 文件名、frontmatter、索引同步、搜索、校验等全部交给程序；skill 退化为 LLM 前端，只负责驱动 CLI。最终打包成可安装产物，分发给 Claude Code 用户各用各的库。

总体架构与决策#

采用三层架构，单一事实来源在 core：

层	组件	职责
core	`mdoc/core.py`	纯逻辑，零依赖，可单测，唯一数据写入方
CLI	`mdoc/cli.py`	core 的薄壳，argparse + `--json` 结构化输出
skill	LLM 前端	模型驱动 mdoc 命令，不直接碰文件

关键决策：

MCP 后置——先让 core+CLI 落定，MCP 服务作为将来对多台机器的能力出口
用 doc.json / patch.json 中间格式承载创建/更新
写操作二次确认：--dry-run 预览 + 用户确认保证
零第三方依赖，stdlib 单测 119 个

阶段 1-2：core + CLI#

core 层实现了全部确定性逻辑：

分类过滤（type: reference，排除 user/feedback/project）
kebab-case 文件名
frontmatter 解析与 YAML 安全（含「冒号+空格」的字段自动加引号）
INDEX/MEMORY 索引同步
全文搜索（索引 + frontmatter + 正文，相关度 + 时间排序）
validate 校验

CLI 提供 init/config/list/search/get/create/update/delete/slugify/validate 命令，--json 模式下 stdout 只输出一条 JSON 供 skill 消费。

阶段 3：迁移现网 skill 命令协议#

把现网 skill 的 SKILL.md 里三处直接跑 python 脚本的逻辑替换为 mdoc 命令；创建/更新/删除流程改为 mdoc create/update/delete + --dry-run 确认。个人胶水内容（auto-memory 路径、node_type 兼容、博客发布规则等）保留不动。

阶段 4：打包 + 通用 skill 模板 + 分发#

打包分发阶段做了四件事：

pyproject：SPDX license = MIT、package-data 收 skill_template、动态版本、入口 mdoc = mdoc.cli:main，新增 LICENSE
通用模板 mdoc/skill_template/SKILL.md：自包含、零机器路径（不含任何个人机器路径）、命令协议全走 mdoc CLI，斜杠调用形式为空格分隔：

1
/mdoc -f   # 按名字查文档
2
/mdoc -l   # 列出文档
3
/mdoc -c   # 创建
4
/mdoc -u   # 更新
5
/mdoc -d   # 删除

core.init_store 幂等写入模板到 <store>/SKILL.md（返回 written|exists|absent）；load_config 增加 cwd 向上发现 .mdoc.toml
构建 wheel + sdist，在干净 venv 里跑陌生机流程（init → 建库 → 搜索 → 删除）验收通过

0.1.1：任意目录可解析文档库（2026-08-10）#

重构完成后收到用户反馈：pip --force-reinstall 重装后，mdoc list 报「未配置文档库」，文档像”消失”了——但文件其实都在。

根因：文档库在 <桌面>/mdoc 子目录。从桌面根目录运行 mdoc list 时，store_dir 解析的 cwd 向上发现 .mdoc.toml（桌面 → 更上层）不进入子目录，又缺少用户级配置，于是 store_dir 为空，报「未配置」。文件从未被删除——唯一的文件删除路径是显式 mdoc delete，重装没有任何钩子动数据。

修复（v0.1.1）：mdoc init 新增 _ensure_user_store_dir，把新建库注册进用户级配置的 store_dir 字段：

用正斜杠规避 TOML 转义
行级编辑，保留 index_file / [classification] / [style] 等既有配置
已有有效 store_dir 时不覆盖，防止劫持已有库

之后在任意目录跑 mdoc 命令都能解析到库，无需先 cd 进库目录。

重装安全：pip --force-reinstall 只更新程序本体，不改文档和配置；重跑 mdoc init <库目录> 幂等，只补缺失文件。

恢复方式（如果遇到同样问题）：

Terminal window

1
# 方式一：重跑 init，幂等
2
mdoc init <你的库目录>
3

4
# 方式二：手动写入用户级配置
5
# 在 ~/.mdoc.toml 写入（注意用正斜杠）
6
# store_dir = "<你的库路径>"

验证：119 个单测全绿（新增 4 个：用户配置写入 / 不覆盖已有库 / 保留其他键 / 库外任意目录 list 解析到库）；干净 venv 陌生机验收完整复刻用户场景——先报「未配置」，重跑 init 后任意目录 list 成功。

验收踩坑（重要）#

Windows 编码 bug：非 UTF-8 locale 下 --stdin 读中文按 GBK + surrogateescape 解码成孤立代理对，写回 UTF-8 时报 UnicodeEncodeError: surrogates not allowed。修复：在 main() 里把 stdin/stdout/stderr 全部 reconfigure(utf-8)。
解析顺序 bug（手工验收抓到）：在陌生库目录内跑 mdoc config 解析到了用户配置里的默认库，把 create/delete 打到了错误位置。根因是 store_dir 解析时用户配置排在了 cwd 发现之前，与文档化的优先级链相悖。修复：cwd 发现的库优先于用户配置，并补了回归测试。
教训：陌生机验收如果用 MDOC_CONFIG=nonexistent 隔离用户配置，反而会掩盖配置优先级顺序 bug——真实陌生机验收要保留用户配置在场。

配置解析优先级（最终定稿）#

store_dir 的解析优先级最终定为：

1
--store > MDOC_DIR > 当前目录向上发现 .mdoc.toml（最多 5 层，到主目录即停）
2
        > 用户配置 ~/.mdoc.toml（$MDOC_CONFIG 可换）> 未配置

选定库后，库本地配置 <store>/.mdoc.toml 再覆盖 index_file / 排除项 / 风格等；在库目录内运行命令会自动选中该库。

未来：MCP 服务#

重构的初衷之一是将来做成 MCP 服务，供多台机器使用。core+CLI 的分层为 MCP 预留了自然挂点：MCP tool 可以直接复用 core 函数（确定性），也可以包一层 CLI。当前决策是 MCP 后置，等 core+CLI 稳定后再评估。

总结#

这次重构把一套散落在 skill 里的”约定”变成了可测试、可分发、可复用的工具。核心收益有三个：确定性操作全部由代码保证，skill 只做 LLM 前端；零依赖的 core 让单测（119 个）和验收可以完整覆盖；0.1.1 的任意目录解析能力让安装后的使用体验真正脱离了”必须 cd 进库目录”的限制。项目开源在 github.com/sanya2485/mdoc。

Coze 聊天窗 z-index 与 Swup 切页适配修复

Thu, 06 Aug 2026 00:00:00 GMT

博客的 Coze AI 助手聊天窗接入 Swup 做 SPA 切页后，陆续踩了三个相互独立的坑：聊天窗被浮动控件遮挡、切页后悬浮球图标永久消失、聊天窗”打不开”其实是 SDK 注入的样式被切页清掉了。这篇文章记录这三个问题的根因和修法。

z-index 层级#

聊天窗默认 ui.base.zIndex 是 1000，和博客的浮动控件（FloatingControls 1000 / FloatingTOC 999/1001）同级，会被遮住。把它提到 1020：

聊天窗：ui.base.zIndex = 1020
悬浮球：1010
toast：9999

之后如果再被遮挡，按这张层级表往上调即可。

Swup 切页重置（修复悬浮球图标消失）#

根因：悬浮球和 SDK 容器在 #swup-container 之外，跨页存活；聊天窗开着时切页，coze-chat-open class 残留 → 悬浮球永久消失。

修法：注册 content:replace 回调，切页时收起聊天窗：

1
window.swup.hooks.on("content:replace", () => {
2
  document.body.classList.remove("coze-chat-open");
3
  cozeClient.hideChatBot();
4
});

注册时做兜底判断：if (window.swup && window.swup.hooks) 已就绪直接用，否则监听 swup:enable 事件（布局层 dispatch）。

SwupScriptsPlugin 重跑脚本坑#

SwupScriptsPlugin 默认 scope 是整个 document，每次 content:replace（含首次加载）会重跑所有没带 data-swup-ignore-script 的 <script>。对 CozeChat 的破坏链：

重跑 → 新 IIFE 里 cozeClient 归零
bindCozeWidget 把悬浮球重绑到空客户端
重跑时 readyState 已是 complete，走 requestIdleCallback(initCozeChat, 500) 分支
第二参传数字抛 TypeError（Argument 2 can't be converted to a dictionary）
initCozeChat 永不执行 → 点悬浮球只弹 toast，聊天窗永远打不开

修复：

内联脚本加 data-swup-ignore-script，让浮窗独立于页面只初始化一次
requestIdleCallback 第二参从数字改成 { timeout: 500 }

通用教训：任何 is:inline 内联脚本如果声明了跨页状态（IIFE 内的 var），都必须加 data-swup-ignore-script 防止 Swup 重跑，否则状态会被第二次执行清零。

SwupHeadPlugin 清 `<style>` 坑#

Coze SDK 初始化时会往 <head> 动态注入约 230 个 <style>（聊天窗 position:fixed、.coz-layout 布局、.light-theme 主题变量、哈希类名组件样式）。之前为了做切页动画启用了 SwupHeadPlugin（updateHead: true），它每次切页用新页面 head 替换当前 head → SDK 注入的运行时样式全被删（实测 headStyleCount 237→5）→ 聊天窗失去 position:fixed、退化成 static 跑到左上角。表现就是”切页后打不开”，其实 cozeClient 活着、showChatBot() 也执行了，只是样式没了。

修法：updateHead 从 true 改成：

1
updateHead: { persistTags: "style" }

这是 SwupHeadPlugin 官方选项，让所有内联 <style> 跨页存活。博客自身页面特异样式都是 scoped（data-astro-cid-* / svelte-*），保留无副作用。

补充认知：SDK 注入的样式里只有 129 个含 “coze”、其中 18 个不含 “coze-chat-sdk” 标记（面板定位是哈希类名规则）→ 按内容字符串匹配不可靠，别用 textContent.includes 当 persistTags 判断条件。persistTags 支持 boolean / CSS 选择器字符串 / 函数三种形式，能用字符串选择器就别用函数。

实现位置#

src/components/widget/CozeChat.astro：resetCozeOnNavigate()（切页收起聊天窗）+ ui.base.zIndex: 1020
astro.config.mjs：updateHead: { persistTags: "style" }

这两个坑（脚本重跑 / head 样式被清）是两条独立破坏路径，之前只修了脚本重跑，没挡住样式被清——排查”切页后组件失灵”类问题时，建议先从这两个维度各自验证一遍。

关联阅读：Coze 浮窗 UI 定制实战：从 SDK 配置到自建悬浮球

Coze 浮窗 UI 定制实战：从 SDK 配置到自建悬浮球

Thu, 06 Aug 2026 00:00:00 GMT

博客的 Coze AI 助手用自建悬浮球 + 问候气泡替换了 SDK 默认的入口，全程逆向 Web SDK 1.2.0-beta.19（cn build）确认配置项行为。这篇文章整理 SDK 浮窗 UI 定制要点和改造中踩的坑。

SDK 浮窗 UI 定制要点（逆向确认）#

英文 UI 根源：ui.base.lang 默认 "en"，不设置就是英文界面，设 "zh-CN" 全转中文。
header 标题：默认硬编码 "Coze Bot"，用 ui.header.title 覆盖。
footer 链接：默认「由扣子提供支持，AI生成仅供参考」，「扣子」是链接，用 ui.footer.isShow=false 或 ui.footer.expressionText 控制。
悬浮球 asstBtn：只有 { isNeed } 一个配置项，图标走 ui.base.icon，class 是 hash 过的 CSS module → 靠 CSS 覆写样式不可靠，要自定义样式就 isNeed:false + 自建。
编程控制：client 暴露 showChatBot() / hideChatBot()；生命周期回调 ui.chatBot.onShow/onHide/onBeforeShow/onBeforeHide。
ui.chatBot.el：可把聊天窗 portal 到自定义容器；顶层 el 会把整个 app（球+窗）放进容器。
ui.base.zIndex 默认 1000，聊天窗与悬浮球共用 → 和博客浮动控件同级，需要提层（相关方案见 Coze 聊天窗 z-index 与 Swup 切页适配修复）。

自建悬浮球与问候气泡#

悬浮球#

自建悬浮球 #coze-ball 固定在右下角 56px，静止时 translateY(28px) 半隐藏（下半截压出视口），hover 弹出 translateY(-16px) 带回弹（cubic-bezier(0.34,1.56,0.64,1)）。

hover 抖动坑（已修）：hover 判定绝不能绑在会移动的元素上。原来 .coze-ball:hover 触发 transform，动画途中球带着判定框上移，鼠标位置不变就脱离 :hover → 弹出/缩回循环抖动。

修法：加一个不移动的 .coze-hitbox（56×40，锚定右下角，pointer-events:auto），hover 用 .coze-hitbox:hover .coze-ball，球在框内纯视觉位移；点击也绑 hitbox（球是其子元素会冒泡）。移动端 hitbox 48×32。

问候气泡#

问候气泡 #coze-bubble 文案「hi~请问有什么问题吗？」，每次打开都弹；× 仅本次关闭 / 3s 自动关；气泡内「不再显示」按钮写 coze_greeting_off 永久停用（此前是 coze_greeting_seen”仅首次”语义，已改）。

坑：clearCozeSessionCache() 会清掉所有 coze_/COZE_ 前缀的 key（只留 coze_visitor_id）。新加的持久化标记必须进白名单，否则每次刷新被清。

问候气泡最终样式（模板 09）#

定位在悬浮球左上方：桌面 right:32px; bottom:84px，移动端 right:24px; bottom:40px；尾巴 right:20px; bottom:-8px（14px 方块 45°）指向球（移动端 right:14px）。
样式：圆体字（"MiSans","HarmonyOS Sans SC","PingFang SC","Microsoft YaHei"）+ 20px 大圆角。颜色跟随主题色相（改 --hue 会同步变）：用 color-mix(in oklab, var(--primary) 10%, var(--card-bg)) 调淡主题色底、primary 30% + --line-divider 描边、primary 16% transparent 阴影；文字亮色 --deep-text、暗色 html.dark 覆盖为 --btn-content。不支持 color-mix 时降级 --btn-regular-bg/--line-divider。
坍缩 bug（重要）：容器 .coze-widget 是 width:0，气泡仅设 right 无显式宽度 → 绝对定位子元素走 shrink-to-fit，可用宽度为 0 → 坍缩成约 58px 窄条（“字体难看”的根因）。修法：气泡加 width:max-content; max-width:230px（显式非 auto 宽度避开 shrink-to-fit 分支）。移动端 max-width:190px。
气泡显示期间球要弹出：.coze-widget.coze-has-bubble .coze-ball { transform: translateY(-16px) }（否则球保持 28px 半隐，气泡尾巴会悬空 56px）。

如何应用#

改 Coze 浮窗样式/行为时：先查上面的 SDK 配置表，别去覆写 SDK 的 hash class；需要自定义交互就 asstBtn.isNeed:false 自建，再调 showChatBot()。聊天窗被遮挡或切页失灵的问题，看 Coze 聊天窗 z-index 与 Swup 切页适配修复。

一次阿里云 ECS 异地登录误报排查与顺手加固

Wed, 15 Jul 2026 00:00:00 GMT

凌晨的告警#

某天凌晨，阿里云发来异地登录告警：来自 美国弗吉尼亚 的 IP 以 root 身份 SSH 登录了 8 次。

第一反应：密钥泄露了。

排查过程#

登录日志分析#

Terminal window

1
# 追踪特定 IP
2
grep 'xx.xx.xx.xx' /var/log/secure
3

4
# 爆破统计
5
grep 'Failed password' /var/log/secure | \
6
  awk '{print $(NF-3)}' | sort | uniq -c | sort -rn
7

8
# 最近登录记录
9
last -20

发现模式重复#

为了验证，手动触发了一次 CI/CD 部署，服务器再次出现完全相同的连接模式：

对比项	第一次（被报警）	手动触发
连接 IP	美国 Azure	美国 Azure
连接次数	8 次	8 次
连接模式	22 秒内多端口并发	22 秒内多端口并发
部署结果	-	成功 ✅

模式完全一致——原来是 GitHub Actions 的 runner 跑在 Azure 基础设施上，SCP 上传时建立多个 SSH 并发连接（分片传输），被阿里云异地登录检测误报了。

顺手发现真实攻击#

在同一份日志中发现了来自另一个 IP 的 287 次 SSH 密码爆破尝试，持续 14 分钟，全部失败。

Terminal window

1
# 封禁爆破 IP
2
iptables -A INPUT -s xx.xx.xx.xx -j DROP

安全加固清单#

趁这个机会完成了一次完整的安全加固：

措施	说明
关闭 SSH 密码登录	`PasswordAuthentication no`，只允许密钥登录
安装 fail2ban	5 次失败自动封禁 24 小时
更换 SSH 密钥	旧密钥作废，更换新密钥对
更新 CI/CD Secrets	替换为新私钥
封禁爆破 IP	iptables DROP
解封 CI/CD IP	确认为 GitHub Actions，从黑名单移除

后门排查#

确认是误报后，还是彻底检查了一遍系统：

当前运行进程 → 无异常
systemd 服务 → 无新增服务
crontab / 定时任务 → 无后门
系统用户 → 只有必要的系统用户
authorized_keys → 清理到只剩 2 个必要密钥
Docker 容器 → 无异常
系统文件完整性（rpm -Va）→ 无篡改
监听端口 → 仅 22(SSH) + 80(nginx)
/tmp、/dev/shm → 无可疑文件

总结#

虚惊一场——所谓的”攻击”是 GitHub Actions CI/CD 的正常 SCP 上传行为，因 runner 位于美国 Azure 区域被阿里云异地登录检测误报。但借着这次误报完成了一次系统安全加固，也算是有惊无险的收获。

建议：如果你也用 GitHub Actions 部署到国内云服务器，收到异地登录告警时先确认是不是 CI runner 的连接，别急着封 IP。

用 Subagent 构建博客发布流水线：归档、审查、发布一条龙

Wed, 15 Jul 2026 00:00:00 GMT

日常维护博客时，常常需要反复执行”代码改动 -> 归档到 /mdoc -> 写成博客 -> 发布”这一流程。手动操作不仅繁琐，而且容易遗漏步骤——有时候修完 bug 就直接切去干别的事了，改完的配置、排查的思路全忘了归档。更烦人的是，单个 agent 处理这么长的链条，上下文一长就容易出现幻觉。

为了解决这个问题，我基于 Claude Code 的 subagent 机制搭了一套三步流水线，把归档、审查、发布全自动化了。

两层架构：Skill 编排 + Subagent 执行#

系统分为两层，各司其职：

层	组件	职责	存放位置
编排层	`blog-pipeline` skill	检测修复场景、调度 subagent、展示用户提示	`~/.claude/skills/blog-pipeline/SKILL.md`
执行层	`mdoc-archiver` subagent	将代码改动归档到 /mdoc 文档	`~/.claude/agents/mdoc-archiver.md`
执行层	`doc-validator` subagent	审查文档准确性，防幻觉	`~/.claude/agents/doc-validator.md`
执行层	`blog-publisher` subagent	将 /mdoc 文档转为博客并发布	`~/.claude/agents/blog-publisher.md`

每个 subagent 都有独立的 context window，互不干扰。skill 层只负责编排调度，不参与具体的文档处理。

blog-pipeline Skill：编排入口#

blog-pipeline skill 是整个工作流的调度大脑，承担四项职责：

自动检测修复场景 — 判断当前对话是否包含代码改动、问题排查、修复完成等信号
轻量用户提示 — 检测到修复场景时在回复末尾显示三段式提示
三步流水线执行 — 按顺序调用三个 subagent
安全规则 — push 前必须展示 git diff 并等待用户确认

当工作流检测到修复场景时，会在回复末尾显示这样的提示：

1
[r] 一条龙（归档→审查→博客→push）
2
[a] 仅归档到 /mdoc
3
[v] 审查博客与 /mdoc 源文档一致性
4
[s] 跳过

无侵入设计：未检测到修复场景时完全不打扰用户。

三步流水线#

完整的流程如下图：

1
代码改动/修复完成
2
      │
3
      ▼
4
[blog-pipeline skill 检测到修复场景]
5
      │
6
      ├── 用户选 [r] ──→ Step 1: mdoc-archiver 归档到 /mdoc
7
      │                         │
8
      │                         ▼
9
      │                   Step 2: doc-validator 审查文档
10
      │                         │
11
      │                    ┌─────┴─────┐
12
      │                    ▼           ▼
13
      │                  通过         不通过 → 用户决定修正/跳过/取消
14
      │                    │
15
      │                    ▼
16
      │                   Step 3: blog-publisher 写博客
17
      │                         │
18
      │                         ▼
19
      │                   git diff 展示给用户确认
20
      │                         │
21
      │                    ┌─────┴─────┐
22
      │                    ▼           ▼
23
      │                  确认         拒绝 → 不 push，保留本地
24
      │                    │
25
      │                    ▼
26
      │                   git commit + git push → GitHub Actions 自动部署
27
      │
28
      ├── 用户选 [a] ──→ 仅执行 Step 1（归档）
29
      │
30
      ├── 用户选 [v] ──→ 审查博客与 /mdoc 一致性
31
      │
32
      └── [s] 跳过 ──→ 什么也不做

展开收起

关键设计原则#

每步独立 context window — 每个 subagent 有独立的上下文，减少长上下文带来的幻觉。归档时不用关心博客格式，写博客时不用关心代码细节
doc-validator 只读 — 审查者与写文档者分离，交叉验证控制幻觉。validator 只有 Read/Grep/Glob 三个工具，没有写入权限
push 前确认 — git diff 必须展示给用户，防止误推送。这是最重要的安全防线
无侵入提示 — 未检测到修复场景时完全不打扰用户，避免无效干扰

三个 Subagent 的职责分工#

Subagent	职责	工具	模型
mdoc-archiver	分析代码改动/修复方案，提取结构化信息（问题描述、根因、解决方案、涉及文件、命令），按 /mdoc 格式写入 memory 目录。会先 Glob 检查是否已有同名文档，决定新建还是补充更新	Read, Grep, Glob, Bash, Write	sonnet
doc-validator	纯只读审查：文件路径真实存在、命令合理、代码引用与实际一致、跨文档链接有效。输出审查结论：通过 / 有警告 / 不通过	Read, Grep, Glob	sonnet
blog-publisher	将 /mdoc 文档转为 Astro 博客文章，写入 `src/content/posts/`。确保 frontmatter 完整，适配博客风格（概述、小标题、代码块标注语言），删除内部文档专用字段。创建后显示 git diff 待用户确认	Read, Grep, Glob, Bash, Write	sonnet

mdoc-archiver 设计要点#

从代码改动中提取结构化信息，包括问题描述、根因分析、解决方案、涉及的文件和命令。写入前会用 Glob 搜索是否已有相关文档，如果有则询问覆盖还是追加。

doc-validator 设计要点#

纯只读，工具限 Read / Grep / Glob。职责：

新文档审查 — 验证路径存在、命令合理、代码引用一致、链接有效
一致性审查（[v]）— 比对本地文档与博客文章，确保内容同步、无内部字段泄漏。遵循时间线一致性规则——以最新文档为准，旧文档允许过时

blog-publisher 设计要点#

将 /mdoc 文档转化为博客文章时做三件事：

确保 frontmatter 完整（title、published、tags、category、draft）
适配博客风格：开头有概述段落，分节用小标题，代码块标注语言
删除内部文档专用的 frontmatter 字段（name、description、metadata）

特殊情况处理#

情况	处理方式
无可归档内容	提示用户，问是否手动提供
文档已存在	问覆盖还是追加，再执行
审查不通过	展示问题，让用户决定修正/跳过/取消
push 前发现不对	不确认即可，保留本地不推送

使用方式#

自动流程（推荐）#

日常修复完代码后，blog-pipeline skill 会自动检测到修复场景，在回复末尾显示轻量提示：

输入 r — 自动走完归档→审查→博客→push 完整流程
输入 a — 仅归档到 /mdoc
输入 v — 审查博客与 /mdoc 源文档一致性
输入 s — 跳过

手动触发#

也可以直接对 skill 或 subagent 下达指令：

“用 mdoc-archiver 把这次修复归档” — 归档到 /mdoc
“用 doc-validator 审查刚才那篇文档” — 交叉验证
“用 blog-publisher 把 nginx 配置那篇写成博客发出去” — 发布
“执行 blog-pipeline” — 触发完整流水线

变更内容#

无代码变更。创建了 1 个 skill 定义文件和 3 个 subagent 定义文件：

~/.claude/skills/blog-pipeline/SKILL.md — 编排层，包含修复场景检测、用户提示模板、三步流水线调度
~/.claude/agents/mdoc-archiver.md — 归档 subagent
~/.claude/agents/doc-validator.md — 审查 subagent
~/.claude/agents/blog-publisher.md — 发布 subagent

注意：subagent 仅存放在用户级目录 ~/.claude/agents/，项目级目录 ~/Desktop/myFireflyBlog/.claude/agents/ 目前留空，仅供项目配置预留。

总结#

这套流水线的核心思路是分治 + 交叉验证：把长流程拆成三个独立步骤，每步由专门的 subagent 处理，中间加一层只读审查来兜底幻觉。从实际使用来看，doc-validator 确实抓出过几次归档文档里的路径错误和命令拼写问题，起到了预期的把关作用。

使用 GitHub Actions + Docker 自动化部署 Astro 静态博客

Wed, 15 Jul 2026 00:00:00 GMT

动机#

项目使用 Astro 构建生成 dist/ 静态文件，之前一直是手动执行 pnpm build → SCP 上传 → SSH 重启容器。每次更新都要重复这套流程，效率低且容易出错。

方案设计#

采用 GitHub Actions + Docker + nginx 的自动化部署方案：

1
Git Push → GitHub Actions (构建) → SCP → Server (nginx:alpine)

为什么不用 docker-compose？#

生产环境只有一个 nginx 容器，没有后端 API、数据库或其他服务，单容器的场景上 docker-compose 是过度工程。

为什么构建不在服务器上做？#

构建在 GitHub Actions 的 CI runner 上完成，服务器只做文件宿主 + 运行时启动。服务器不需要装 pnpm、Node.js，也不需要跑构建，攻击面更小、运维更轻。

工作流设计#

.github/workflows/deploy-server.yml：

1
触发条件：push 到 master 分支
2
步骤：
3
  1. Checkout 代码
4
  2. Setup Node.js 22 + pnpm
5
  3. pnpm install --frozen-lockfile
6
  4. pnpm build
7
  5. SCP 上传 dist/ 到服务器
8
  6. SSH 执行 docker run nginx:alpine

Secrets 配置#

Secret	用途
`SERVER_HOST`	服务器 IP
`SERVER_USERNAME`	SSH 用户名
`SERVER_SSH_KEY`	SSH 私钥
`BLOG_DOMAIN`	博客域名或 IP（nginx 模板用）

容器运行#

服务器上直接跑 nginx:alpine 官方镜像，通过 -v 挂载静态文件目录：

Terminal window

1
docker run -d --name myFireflyBlog \
2
  -v /path/to/blog:/usr/share/nginx/html:ro \
3
  -p 80:80 --restart always nginx:alpine

Nginx 配置#

通过独立的 deploy-nginx.yml workflow 管理，与博客内容部署解耦：

Gzip 压缩#

1
gzip on;
2
gzip_types text/plain text/css application/json application/javascript image/svg+xml;
3
gzip_vary on;

安全头#

1
add_header X-Content-Type-Options "nosniff" always;
2
add_header X-Frame-Options "DENY" always;
3
add_header X-XSS-Protection "1; mode=block" always;
4
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

缓存策略（针对 Astro 构建产物）#

1
# 内容哈希文件名 —— 不可变缓存
2
location /_astro/   { expires 365d; add_header Cache-Control "public, immutable"; }
3

4
# 通用静态资源
5
location /assets/   { expires 30d;  add_header Cache-Control "public"; }
6

7
# 搜索索引
8
location /pagefind/ { expires 7d;   add_header Cache-Control "public"; }
9

10
# HTML 页面不缓存（内容更新需即时生效）
11
location ~* \.html$ { expires -1;   add_header Cache-Control "no-cache"; }

一些经验#

条件挂载避免耦合#

nginx 配置通过独立 workflow 管理，博客内容 deploy 时检测配置是否存在：

Terminal window

1
CONFIG_MOUNT=""
2
if [ -f /path/to/conf/default.conf ]; then
3
  CONFIG_MOUNT="-v /path/to/conf/default.conf:/etc/nginx/conf.d/default.conf:ro"
4
fi
5

6
docker run -d \
7
  --name myFireflyBlog \
8
  -v /path/to/dist:/usr/share/nginx/html:ro \
9
  $CONFIG_MOUNT \
10
  -p 80:80 --restart always nginx:alpine

配置存在则挂载，不存在则退化到默认配置，两个 workflow 独立但不耦合。

安全加固顺手做#

在配置部署的过程中顺带加固了 SSH 安全：

关闭密码登录（PasswordAuthentication no）
安装 fail2ban 防爆破
更换密钥对

总结#

这套方案跑下来最满意的一点是变更域分离——博客内容和服务器配置走不同的 workflow，各自独立更新互不影响。改配置不需要重新构建，发文章不需要碰服务器配置。

对比之前的纯手动流程，现在每天更新博客的心理负担降到了零：写完 git push 等三分钟就好了。

隐藏的博客文章还在首页显示？排查 Astro draft 机制问题

Wed, 15 Jul 2026 00:00:00 GMT

问题现象#

把博客里的示例文章全部设为 draft: true 后，出现了两个问题：

首页仍能看见隐藏文章的预览卡片
分类（“文章示例""博客指南”）后面的文章数字还是旧的

排查过程#

第一层：draft 过滤逻辑#

查看 src/utils/content-utils.ts 中获取文章列表的函数：

1
const allBlogPosts = await getCollection("posts", ({ data }) => {
2
    return import.meta.env.PROD ? data.draft !== true : true;
3
});

问题出在这里。import.meta.env.PROD 在本地开发环境（pnpm dev）下是 false，此时过滤函数恒返回 true——所有文章包括草稿全部显示。所以本地预览时永远看到全部文章，分类计数也是错的。

修复很简单：去掉环境判断，始终过滤草稿。

1
return data.draft !== true;

第二层：为什么部署到服务器后还不对？#

代码改完、部署成功后，用户说还是看到旧内容。这就不是 draft 逻辑的问题了——应该是浏览器缓存。

检查服务器返回的响应头：

1
Cache-Control: no-cache

no-cache 的语义是”可以缓存，但使用前必须向服务器验证”。大部分浏览器会遵守这个规则，但 Safari 等浏览器的 bfcache（后退缓存） 在回退导航时会直接使用页面快照，根本不发验证请求。

将 HTML 的缓存策略改为更严格的 no-store：

1
# 旧
2
location ~* \.html$ {
3
    expires -1;
4
    add_header Cache-Control "no-cache";
5
}
6

7
# 新
8
location ~* \.html$ {
9
    add_header Cache-Control "no-store, must-revalidate";
10
}

no-store 告诉浏览器完全不要缓存页面，每次导航都从服务器获取最新内容。

第三层：配置怎么每次部署都丢了？#

配置写好后，部署一次博客——配置又丢了，容器退回到默认 nginx 配置。

查 deploy-server.yml 的 SCP 步骤：

1
- uses: appleboy/scp-action@v0.1.7
2
  with:
3
    source: "dist/"
4
    target: "/path/to/blog"
5
    rm: true

rm: true 每次部署清空整个目标目录再上传。而我把 nginx 配置放在了 /path/to/blog/conf/ 下——正好被清掉。

修复：把 nginx 配置文件移出 SCP 的打击范围。

1
/path/
2
├── blog/          # SCP 目标（rm:true 清空这里）
3
│   └── dist/      # 博客静态文件
4
└── nginx/
5
    └── conf/
6
        └── default.conf   # nginx 配置（SCP 碰不到）

经验总结#

问题	教训
draft 过滤	`import.meta.env.PROD` 的判断会让草稿在开发环境可见，计数也受影响
HTML 缓存	`no-cache` 不如 `no-store` 严格，bfcache 会绕过验证
配置文件被删	SCP 的 `rm: true` 清空整个目标目录，配置必须放在外面

三个问题单独看都不复杂，但串在一起会导致”明明部署成功了，为什么还是旧内容”的困惑——每个环节都以为自己没做错，合起来效果就不对。

Nginx 配置与项目部署解耦：envsubst + 独立 Workflow

Wed, 15 Jul 2026 00:00:00 GMT

问题#

博客的 nginx 一直跑着官方默认配置——Gzip 没开、安全头没有、缓存策略全无。更麻烦的是，nginx 配置和博客内容耦合在同一个部署流程里：

1
deploy-server.yml: pnpm build → SCP dist/ → docker run

想改个缓存时间？得改项目代码、走完整构建、等 CI/CD 跑完。改完容器重启，配置又丢了（无状态容器）。

方案：四层解耦#

1. 模板 + envsubst#

仓库是公开的，敏感信息（域名/IP）不能明文存。用 envsubst 做模板变量替换：

server/nginx/default.conf.template

1
server {
2
    server_name  ${BLOG_DOMAIN};
3
    # ...
4
}

CI/CD 中替换后上传：

1
- run: envsubst '${BLOG_DOMAIN}' < template > default.conf

envsubst '${BLOG_DOMAIN}' 精确替换指定变量，nginx 自身的 $ 变量（如 $remote_addr）不受影响。

GitHub Secrets 里存 BLOG_DOMAIN，仓库里只有模板，不留明文。

2. 独立 Workflow#

新增 .github/workflows/deploy-nginx.yml，只做一件事：

1
手动触发 → envsubst → SCP default.conf → nginx -t 测试 → nginx -s reload

和博客内容部署完全独立：

1
改 nginx 配置 → 编辑模板 → 手动触发 Deploy Nginx Config → 10 秒生效
2
改博客内容 → git push → Deploy to Server 自动触发 → 3 分钟

3. 条件挂载#

博客部署时检测配置文件是否存在：

Terminal window

1
CONFIG_MOUNT=""
2
if [ -f /path/to/conf/default.conf ]; then
3
  CONFIG_MOUNT="-v /path/to/conf/default.conf:/etc/nginx/conf.d/default.conf:ro"
4
fi
5

6
docker run -d --name myFireflyBlog \
7
  -v /path/to/dist:/usr/share/nginx/html:ro \
8
  $CONFIG_MOUNT \
9
  -p 80:80 --restart always nginx:alpine

配置存在则挂载，不存在则退化到默认配置——零耦合故障点。

4. 配置与内容目录分离#

服务器上配置文件和静态文件分开放：

1
/path/to/blog/
2
├── dist/           # 博客静态文件（SCP 上传）
3
├── conf/
4
│   └── default.conf  # nginx 配置（独立 workflow 管理）

两个目录互不覆盖，内容 deploy 不会丢配置，配置更新不影响内容。

结果#

操作	之前	之后
改缓存策略	改代码 → push → 等 3 分钟构建	改模板 → 触发 workflow → 10 秒 reload
改博客内容	同上流程	git push → 自动部署（不影响配置）
回滚配置	无解	git revert → 触发 workflow
服务器重建	手配 nginx	跑 workflow 一键恢复

最直接的收益：改 nginx 配置从”半小时的项目发布”变成了”10 秒的运维操作”。

Sanya

博客 AI 助手“无回复”根因：反代网关地址缓存过期导致 502

问题#

根因#

修复方案#

如何应用#

一条小坑#

总结#

让博客文章携带可下载文件：随文附件功能实现记录

需求背景#

设计决策：附件不随整站部署#

实现要点#

踩坑：只读目录下创建不了挂载点#

下载限流：防滥用与防带宽占满#

使用方法#

配套：mdoc 定制化工具包#

mdoc 定制化工具包：把修复文档管理系统搬到新机器

mdoc 是什么#

工具包里有什么#

下载与三步部署#

需要设置的部分（配置清单）#

使用（以 Claude Code 为例）#

AI 部署教程#

安全说明#

关联阅读#

mdoc 重构：从 Claude Code skill 到任意目录可解析的 CLI 工具库

背景与目标#

总体架构与决策#

阶段 1-2：core + CLI#

阶段 3：迁移现网 skill 命令协议#

阶段 4：打包 + 通用 skill 模板 + 分发#

0.1.1：任意目录可解析文档库（2026-08-10）#

验收踩坑（重要）#

配置解析优先级（最终定稿）#

未来：MCP 服务#

总结#

Coze 聊天窗 z-index 与 Swup 切页适配修复

z-index 层级#

Swup 切页重置（修复悬浮球图标消失）#

SwupScriptsPlugin 重跑脚本坑#

SwupHeadPlugin 清 <style> 坑#

实现位置#

Coze 浮窗 UI 定制实战：从 SDK 配置到自建悬浮球

SDK 浮窗 UI 定制要点（逆向确认）#

自建悬浮球与问候气泡#

悬浮球#

问候气泡#

问候气泡最终样式（模板 09）#

如何应用#

一次阿里云 ECS 异地登录误报排查与顺手加固

凌晨的告警#

排查过程#

登录日志分析#

发现模式重复#

顺手发现真实攻击#

安全加固清单#

后门排查#

总结#

用 Subagent 构建博客发布流水线：归档、审查、发布一条龙

两层架构：Skill 编排 + Subagent 执行#

blog-pipeline Skill：编排入口#

三步流水线#

关键设计原则#

三个 Subagent 的职责分工#

mdoc-archiver 设计要点#

doc-validator 设计要点#

blog-publisher 设计要点#

特殊情况处理#

使用方式#

自动流程（推荐）#

手动触发#

变更内容#

总结#

使用 GitHub Actions + Docker 自动化部署 Astro 静态博客

动机#

方案设计#

为什么不用 docker-compose？#

为什么构建不在服务器上做？#

工作流设计#

Secrets 配置#

SwupHeadPlugin 清 `<style>` 坑#