iwmei的博客

BilibiliContentFetcher 项目复盘：从单条演示到批处理闭环

Wed, 06 May 2026 00:00:00 +0000

这次复盘记录的是 BilibiliContentFetcher 一次完整落地过程。

我这次的目标不是做一条能看的演示链路，而是把批量生产链路做稳定，把输出质量做可控，把项目结构做可维护，把最终产物直接落到 Obsidian。

我按真实时间线展开，尽量保留全过程细节。

1. 起点目标

我在会话开始阶段先把目标重新收敛，避免中途跑偏。

当时我给自己定了六个硬条件。

主目标是批量稳定执行，不是单条效果展示。
输出格式必须严格贴合根目录 Tempate.md。
必须使用 DeepSeek 思考模式，不接受本地替代。
模块结构与链路逻辑要对齐 XHSContentFetcher。
最终笔记必须可直接出现在 Obsidian。
最终代码要推送远程，并补全 CLI 命令文档。

这一组条件决定了后续所有取舍。

2. 阶段 A

这个阶段是质量回归和模板约束加固，时间段是 18 点 20 到 18 点 33。

我先执行回归测试，确认基线可跑。

1

pytest -q

结果是 5 passed。

这一步给了我一个清晰信号，当前代码有可用基础，但输出质量不够。

我随后集中处理了四类问题。

文本里有泛化表达，观点和结论过于笼统。
有占位风格残留，章节质感不稳定。
评论区覆盖不足，子评论利用率偏低。
视频类笔记有明显模板痕迹。

2.1 质量约束改造

我在 src/bili_content_fetcher/ai_writer.py 里加了完整质量栅栏。

关键函数是：

_validate_markdown_output
_repair_markdown_once
_ensure_quality

这三步形成了质量闭环。

先检查结构完整性。
再执行自动修订。
最后做二轮兜底，不通过就回退。

我把检查项写得很细，包含章节顺序、占位词、概念数量、问题数量、评论数量、图片内联要求。

2.2 评论区典型性改造

我同时补了评论评分和代表性筛选。

对应新增逻辑：

_comment_score
_select_representative_comments
_comment_insight

这组改动让评论区从堆数据变成可读观点层。

我要求每条代表评论都要有我的提炼句，不再只贴原文。

2.3 阶段 A 实跑

我用单条链接做了一次实跑。

1

bili-note run https://www.bilibili.com/opus/1195483269038080034

结果是新笔记目录生成成功，结构可用，基础质量明显提升。

3. 阶段 B

这个阶段是切到 DeepSeek 真链路，时间段是 18 点 33 到 18 点 36。

问题不是代码逻辑，而是配置状态。

3.1 DeepSeek Key 缺失

我检查后确认当前项目没有可用 Key。

项目 .env 缺失。
环境变量 DEEPSEEK_API_KEY 为空。

我的处理方式是从 XHSContentFetcher 读取可用配置，再写入当前项目 .env。

3.2 Vault 路径空值误解析

我还遇到了一个配置细节问题。

OBSIDIAN_VAULT_PATH= 空值被解析为当前目录，bili-note check 显示默认 Vault 指向点目录。

我删除了空值行，恢复为未配置状态，避免误写路径。

3.3 DeepSeek 真链路验证

我重新执行带 DeepSeek 配置的运行命令。

结果是模型链路跑通，真实生成成功。

这个节点很关键，说明我已经从本地降级模式切回目标模式。

4. 阶段 C

这个阶段是方向纠偏，时间段是 18 点 36 到 18 点 56。

核心变化只有一句话，批量优先替代单条打磨。

我在这个阶段做了三件大事。

新增批处理子命令。
处理 Windows 编码崩溃。
落地批处理汇总产物。

4.1 批处理子命令落地

我在 src/bili_content_fetcher/cli.py 加了 batch 子命令体系。

支持参数包含：

--max-items
--fail-fast

并新增批处理汇总文件机制，输出 batch_summary_*.json。

我同时同步改了 README.md，保证命令文档可直接执行。

4.2 Windows 编码崩溃修复

这一步是阶段 C 的关键故障。

我当时遇到错误：

1

UnicodeEncodeError: 'gbk' codec can't encode character '\ufeff'

触发点是批量输入文件首行 BOM 加上控制台输出编码冲突。

我按三步修复。

_load_batch_inputs 改成 utf-8-sig 读取。
输入行统一剥离 \ufeff 前缀。
控制台输出前做安全预览过滤，剔除不可编码字符。

修完后我马上复跑批量命令。

1

bili-note batch batch_links.txt --max-items 2

结果是 2/2 成功。

并产出汇总文件：

output/batch_summary_20260506_185559.json

5. 阶段 D

这个阶段是视频笔记质量二次修复，时间段是 18 点 56 到 19 点 02。

5.1 英文噪声词进入概念区

我发现视频类笔记的概念区混入了 and the add no 这类词。

这是明显质量缺陷。

我做了三项补丁。

增加英文停用词 EN_STOPWORDS。
增加英文术语白名单 EN_TERM_ALLOWLIST。
非股票场景的问题标题改成稳定框架，避免弱标题漂移。

5.2 模型结果被回退过度覆盖

我还发现质量修订链有副作用。

多轮修订后，较好的模型版本有时会被过度回退。

我在 _ensure_quality 里加了保留策略。

当结构可用且占位残留已清空时，优先保留最后模型版本。

这一步直接改善了成文自然度。

5.3 阶段 D 复跑

我用视频批处理单条做复验。

1

bili-note batch batch_video_only.txt --max-items 1

结果是视频学习报告稳定生成，英文噪声问题消失。

6. 阶段 E

这个阶段是大改造，时间段是 19 点 02 到 19 点 28。

目标很明确，把 Bili 项目和 XHS 项目做同构对齐。

6.1 同构基线

我先对齐目标模块清单：

cli
config
workflow
fetcher
media
video_tools
deepseek
markdown_writer
obsidian
url_parser
ocr_engine

6.2 新增模块

我新增了以下文件。

src/bili_content_fetcher/url_parser.py
src/bili_content_fetcher/fetcher.py
src/bili_content_fetcher/media.py
src/bili_content_fetcher/video_tools.py
src/bili_content_fetcher/ocr_engine.py
src/bili_content_fetcher/deepseek.py
src/bili_content_fetcher/markdown_writer.py
src/bili_content_fetcher/obsidian.py
src/bili_content_fetcher/workflow.py

6.3 重构模块

我重点重构了两个文件。

config.py
- 增加本地配置文件 ~/.bili-content-fetcher/config.json
- 保留 .env 兼容链路，兼容历史配置
cli.py
- 从 Typer 切到 argparse
- 统一成与 XHS 对齐的 run config batch 命令体系

6.4 文档和入口

我同步重写：

README.md
pyproject.toml 脚本入口，改为 bili_content_fetcher.cli:main

6.5 阶段 E 验收

我执行整套验收。

1
2
3
4


pytest -q
python -m bili_content_fetcher.cli --help
python -m bili_content_fetcher.cli run --help
python -m bili_content_fetcher.cli batch --help

结果：

pytest -q 变为 8 passed
CLI 帮助命令全部可用

随后我提交并推送。

commit 03ac851
message feat: align bili workflow with xhs architecture and add full batch CLI
push origin/main 成功

7. 阶段 F

这个阶段是最终验收，时间点约 20 点 02。

目标只有一个，Obsidian 可见。

我执行命令：

1

python -m bili_content_fetcher.cli run "<opus链接>" --vault-dir "C:\Users\yourp\Documents\Obsidian Vault" --notes-folder "BiliNotes" --open-obsidian

验收结果：

DeepSeek 生成成功
图片 7
评论 18
OCR 7
笔记写入 Vault 成功
Obsidian 可直接查看

本次验收产物路径：

C:\Users\yourp\Documents\Obsidian Vault\BiliNotes\ru-he-zai-5000jia-gu-piao-zhong-shai-xuan-chu-long-tou-gu-bi-li-bi-li\ru-he-zai-5000jia-gu-piao-zhong-shai-xuan-chu-long-tou-gu-bi-li-bi-li.md

8. 问题清单汇总

我把全过程问题收敛成七类。

笔记里有占位和模板痕迹。
评论区代表性不足，回复利用不足。
项目缺 DeepSeek 配置。
批处理不是主链路。
Windows BOM 和编码导致批处理崩溃。
视频笔记出现英文噪声概念。
项目结构和 XHS 不一致。

对应修复策略分别是：

质量校验加自动重写加密度约束。
评论评分筛选加逐条提炼。
.env 补齐加 CLI 缺 Key 明确报错。
batch 子命令加失败续跑和汇总。
utf-8-sig 加 BOM 剥离加安全输出。
停用词加白名单加标题稳态框架。
同构重构模块加统一 CLI 和配置体系。

9. 关键命令流水

9.1 质量回归

1

pytest -q

9.2 单条链路

1
2


bili-note run "<链接>"
python -m bili_content_fetcher.cli run "<链接>" ...

9.3 批量链路

1
2


bili-note batch links.txt --max-items 2
python -m bili_content_fetcher.cli batch links.txt --max-items 1

9.4 配置检查

1
2


bili-note check
python -m bili_content_fetcher.cli config show

9.5 版本管理

1
2


git commit -m "..."
git push origin main

10. 最终状态

我在导出时间点确认的状态如下。

代码已提交并推送到远程主分支。
CLI 的 run batch config 全量可用。
DeepSeek 真链路实跑通过。
Obsidian 实跑可见笔记。
测试状态 8 passed。

11. 我这次最关键的决策

第一，先把批处理链路立成主线，单条只做回归样本。

第二，把输出质量做成程序约束，不靠模型临场发挥。

第三，把项目结构和 XHS 同构，换来后续维护和迁移的确定性。

12. 下一步计划

下一步我会继续补三组能力。

断点续跑，降低长任务重跑成本。
OCR 和 LLM 缓存，降低重复计算成本。
结构化日志，细化阶段耗时和错误分类。

这次项目的核心结果不是某一条笔记写得好看。

真正的结果是我把一条从抓取到笔记落地的链路做成了可批量执行、可定位故障、可重复验收的工程系统。

XHSContentFetcher 项目复盘：从空仓到可发布 CLI

Tue, 05 May 2026 00:00:00 +0000

这篇是我的全过程复盘，不是摘要版。重点是把“从空仓到可发布版本”的真实路径写清楚。

我会尽量保留操作细节，包括：

我执行过的关键命令
我遇到的报错
我如何定位
我具体改了什么
我怎么复测

文中所有 Cookie / API Key 都是脱敏表达，不写明文。

0. 起点与约束

0.1 初始仓库状态

项目路径是：

F:\College\Activ_CodeProjects\PycharmProjects\XHSContentFetcher

我一开始先看目录：

1
2


Get-ChildItem -Force
Get-ChildItem -Recurse -File

当时可见文件基本只有：

计划.md
LICENSE
venv/
.idea/

也就是说，业务代码几乎是 0。

0.2 我给自己写死的目标，来自 `计划.md`

输入小红书分享链接，支持图文和视频。
抓取正文、评论、图片 / 视频。
图片 OCR。
视频关键帧抽取。
调 DeepSeek 生成可用于 Obsidian 的学习笔记。
全部做成 CLI，不做 GUI。
最终产物是“能直接进 Obsidian”的笔记和素材。

0.3 现实条件

我手里有一个参考仓库，但不确定有没有可复用代码。
我有图文和视频两条测试链接。
我有开发阶段所需 Cookie 和 DeepSeek Key，后续代码和文档全部脱敏。

1. 预研阶段：先确认抓取链路可行

我没有上来就写框架。我先做了 5 个预研动作。

1.1 动作一：确认项目现状

执行：

1
2


Get-ChildItem -Force
Get-ChildItem -Recurse -File

结论：

仓库本体几乎没有业务代码。
这次必须从零搭。

1.2 动作二：完整读取计划

执行：

1

Get-Content -Raw -Encoding UTF8 计划.md

结论：

技术目标很清楚：抓取 + OCR + 大模型 + Obsidian。
文风要求也清楚：去 AI 味、逻辑分点、自然表达。

1.3 动作三：核查参考仓库

执行：

1
2
3
4


git ls-remote https://github.com/yourpapayouknow/XHSContentFetcher.git
git clone https://github.com/yourpapayouknow/XHSContentFetcher.git _ref_repo
Get-ChildItem -Force _ref_repo
Get-ChildItem -Recurse -File _ref_repo

发现：

仓库只有 LICENSE，无可复用实现。

决策：

我不再依赖这个仓库，直接独立实现。

1.4 动作四：抓取库选型

执行：

1
2


pip index versions xiaohongshu-cli
python -m pip download xiaohongshu-cli==0.6.4 -d _vendor

我后续做了 wheel 解包和源码检查，重点看：

xhs_cli/client.py
xhs_cli/client_mixins.py
xhs_cli/html_parser.py
xhs_cli/formatter.py
xhs_cli/cookies.py

我确认到的能力：

get_note_detail
get_comments / get_sub_comments
get_note_from_html，用于 HTML 回退
现成签名流程，我不用自己逆向签名

我写了临时脚本，直接调 XhsClient，分别验证图文和视频。

关键验证结果：

图文 note_card 里有 image_list、desc、interact_info。
视频 note_card.video.media.stream.h264 能取到可下载流地址。
评论接口能正常返回。

到这里我才进入工程实现阶段。

2. 工程搭建阶段：从 0 到可执行 CLI

2.1 基础文件落地

我先建了最小工程骨架：

pyproject.toml
.gitignore
src/xhs_content_fetcher/__init__.py
README.md，初版

2.2 模块化拆分，第一版

我按职责拆成 12 个模块：

config.py：配置持久化 + Cookie 解析
utils.py：通用工具函数
url_parser.py：链接解析，包含重定向处理
fetcher.py：详情 / 评论抓取 + 评论排序
media.py：图片和视频下载
video_tools.py：ffmpeg 调用、降采样、抽帧
ocr_engine.py：PaddleOCR 封装
deepseek.py：模型输入构造与调用
markdown_writer.py：Markdown 产物写入
obsidian.py：打开 Obsidian
workflow.py：端到端编排
cli.py：命令入口

2.3 初始测试

我建了 3 个单测：

URL 解析测试
Cookie 解析测试
评论排序测试

执行：

1

venv\Scripts\python -m pytest

结果：

1

6 passed

3. 首轮端到端联调：先跑通图文 / 视频主链路

我先把变量收敛，避免 LLM 和 OCR 抢占排错注意力。

执行示意：

1
2


python -m xhs_content_fetcher.cli run "<图文链接>" --cookie "<脱敏>" --skip-llm --skip-ocr --output-root output
python -m xhs_content_fetcher.cli run "<视频链接>" --cookie "<脱敏>" --skip-llm --skip-ocr --output-root output

3.1 第一个关键故障：`API error: {"code": -1}`

图文链路首次运行报错：

1

[ERROR] API error: {"code": -1, "success": false}

3.2 我的定位路径

我没有直接改代码，而是先拆开验证：

get_note_detail 单独调，成功。
get_comments 单独调，成功。
失败集中在“抓子评论”阶段，部分 get_sub_comments 偶发异常。

3.3 修复动作

我在 fetcher.py 里改 _fetch_sub_comments：

改成单条容错。
单条失败就跳过。
不让局部失败中断主流程。

修复后复测：

图文链路跑通。
视频链路跑通。

关键产物验证：

视频下载成功，文件是 video_raw.mp4。
关键帧抽取成功，默认抽取 8 帧。
评论抓取成功。

4. 媒体与 OCR 深度修复：这部分最耗时

4.1 图片输出成 `.bin`

现象：

图片文件变成 image_01.bin。
Obsidian 预览和 OCR 都受到影响。

根因：

部分 CDN 响应缺失可靠 content-type。

修复：

我在 media.py 加了魔数检测和扩展名回退顺序：

先看内容头，覆盖 JPEG / PNG / GIF / BMP / WEBP / AVIF
再看 Content-Type
再看 URL 后缀
最后才用 .bin

结果：

图片稳定输出为 .webp/.jpg/...。

4.2 OCR 初始化失败：缺底层依赖

现象：

1

dependency 'paddlepaddle' is not installed

处理：

1
2


venv\Scripts\python -m pip install paddleocr
venv\Scripts\python -m pip install paddlepaddle

4.3 PaddleOCR 参数兼容问题

我遇到两个典型兼容问题：

某些版本不接受 show_log。
新版在 OCR 参数里带 cls=True 时会抛 unexpected keyword。

修复策略：

初始化参数做多套回退。
OCR 调用失败后回退到不带 cls 的方式。

4.4 oneDNN / MKLDNN 兼容报错

现象：

1

ConvertPirAttribute2RuntimeAttribute not support ...

修复：

在 ocr_engine.py 设置兼容环境变量，禁用问题路径。

4.5 中文路径导致 `Invalid argument`

现象：

Paddle 在部分中文路径下读取文件失败。

修复：

OCR 前先复制到临时 ASCII 路径。
识别完成后映射回原文件名。

4.6 OCR 文本污染

现象：

OCR 结果混入临时路径字符串。

修复：

过滤 xhs_ocr_、盘符路径、tmp 路径行。

结果：

OCR 文本可直接进入笔记。

4.7 OCR 超时不是功能失败

我实际还遇到过一次“超时中断”。

这次不是逻辑错误，而是首次全量 OCR 跑 8 张图时加载和推理时间偏长。

我采取的动作：

放宽命令超时窗口。
完整跑到底，再判断是否存在真实异常。

5. 提示词迭代：从“复述”改到“可读笔记”

链路跑通后，我回看产物，发现三个硬问题：

文本复述多，知识点拆解不够。
图片堆在文末，不是图文并茂。
口吻不像我的笔记。

5.1 第一次改造：强化提示词约束

我在 deepseek.py 做了三层调整：

固定第一人称口吻。
解释优先，要求按“是什么 / 为什么 / 怎么用 / 边界误区”拆解。
禁止教学腔、禁止空泛总结。

同时在 workflow.py 把素材相对路径直接喂模型：

assets/images/...
assets/frames/...
assets/video/...

目的很明确：模型必须内联引用，不允许文末堆图。

5.2 第二次改造：模板优先，禁用硬编码骨架

我后续把策略改成“模板优先”：

优先读取根目录 Tempate.md。
兼容 Template.md / template.md。
找不到模板就报错，不再自动生成章节骨架。
占位符替换真实路径：
- assets.images[*].path
- assets.video_frames[*].path

这一步的意义是：我把结构控制权从模型拿回到模板。

6. URL 解析事故：`discovery/item/<id>`

6.1 故障现象

新链接进入后，全链路失败：

1

[ERROR] 帖子详情为空，无法提取 note_card。

6.2 我的定位过程

我先用独立脚本验证，确认：

XhsClient.get_note_detail 能拿到 items。
我自己的 url_parser 把 note_id 解析错了，取成了 item。

6.3 修复方案

我在 url_parser.py 做三点修复：

优先匹配 24 位 ID-like 片段。
特判 discovery/item/<id>。
保留 explore/<id> 和 item/<id> 兼容逻辑。

复测结果：

1

7 passed

7. Obsidian 对接联调：命令可用，但编码有坑

7.1 CLI 可用性验证

执行：

1
2


obsidian --help
obsidian vaults verbose

我确认：

Obsidian CLI 可用。
Vault 路径能识别到，例如 C:\Users\yourp\Documents\Obsidian Vault。

7.2 真机写入 + 自动打开

执行示意：

1

xhs-fetch run "<链接>" --vault-dir "C:\Users\...\Obsidian Vault" --open-obsidian ...

结果：

笔记写入成功。
自动打开成功。

7.3 `UnicodeDecodeError` 修复

现象：

1

UnicodeDecodeError: 'gbk' codec can't decode ...

根因：

subprocess 捕获 Obsidian 输出时发生编码读流问题。

修复：

obsidian.py 把 stdout/stderr 改成 DEVNULL。

复测后恢复正常。

8. 我做过的回归验证清单

我不是“跑通一次就结束”，而是按层回归：

单测回归：venv\Scripts\python -m pytest
图文链路回归：--skip-llm --skip-ocr
视频链路回归：--skip-llm --skip-ocr
OCR 层验证：单图 + 全量图
DeepSeek 全链路验证：含模型调用产出
产物检查：笔记、图片、关键帧、视频、路径引用

期间我还做过环境检查：

1
2


Get-Command ffprobe -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source
Get-Command ffmpeg -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source

这样可以先排除本机 ffmpeg 工具链问题。

9. 文档、清理与发布

9.1 清理动作

我按交付要求清理：

output/
tests/
.pytest_cache/
全部 __pycache__/

保留：

Tempate.md，后续生成结构依赖它

9.2 README 重写范围

我把 README 改成简体中文，覆盖：

功能全览
安装与依赖
配置方式
模板机制
Obsidian 对接
常见问题排错

9.3 Git 提交和推送

我执行：

1
2
3


git add .gitignore README.md Tempate.md pyproject.toml src
git commit -m "feat: implement end-to-end xhs fetcher with obsidian integration"
git push origin main

结果：

提交：13f8545
分支：main
远程推送成功

安全处理：

含敏感信息的 计划.md 保持未跟踪，不进仓库。

10. 本次产出的最终代码结构

核心目录：

src/xhs_content_fetcher/cli.py
src/xhs_content_fetcher/workflow.py
src/xhs_content_fetcher/fetcher.py
src/xhs_content_fetcher/media.py
src/xhs_content_fetcher/video_tools.py
src/xhs_content_fetcher/ocr_engine.py
src/xhs_content_fetcher/deepseek.py
src/xhs_content_fetcher/markdown_writer.py
src/xhs_content_fetcher/obsidian.py
src/xhs_content_fetcher/url_parser.py
src/xhs_content_fetcher/config.py
src/xhs_content_fetcher/utils.py

工程文件：

pyproject.toml
.gitignore
README.md
Tempate.md

11. 关键报错与修复对照

阶段	报错 / 问题	根因	修复
抓取	`API error: {"code": -1}`	子评论接口偶发失败	子评论单条容错，不阻断主流程
媒体	图片输出 `.bin`	CDN 响应类型不稳定	魔数识别 + 多级扩展名回退
OCR	`paddlepaddle not installed`	只装了 `paddleocr`	补装 `paddlepaddle`
OCR	参数不兼容	PaddleOCR 版本差异	初始化 / 调用参数回退
OCR	oneDNN 报错	后端兼容问题	兼容环境变量兜底
OCR	`Invalid argument`	中文路径读取问题	临时 ASCII 路径识别
解析	`note_id` 被解析为 `item`	URL 规则覆盖不足	修复 `discovery/item/<id>` 解析
Obsidian	`UnicodeDecodeError`	子进程输出编码冲突	`stdout/stderr -> DEVNULL`

12. 命令流水节选

下面这组命令是我这次会话里反复执行的关键路径，按用途分组：

12.1 目录与文件检查

1
2
3


Get-ChildItem -Force
Get-ChildItem -Recurse -File
Get-Content -Raw -Encoding UTF8 计划.md

12.2 抓取依赖验证

1
2
3
4


git ls-remote https://github.com/yourpapayouknow/XHSContentFetcher.git
git clone https://github.com/yourpapayouknow/XHSContentFetcher.git _ref_repo
pip index versions xiaohongshu-cli
python -m pip download xiaohongshu-cli==0.6.4 -d _vendor

12.3 本地构建与测试

1
2
3


venv\Scripts\python -m pip install -e . pytest
venv\Scripts\python -m xhs_content_fetcher.cli --help
venv\Scripts\python -m pytest

12.4 图文 / 视频端到端

1
2


venv\Scripts\python -m xhs_content_fetcher.cli run "<图文链接>" --cookie "<脱敏>" --skip-llm --skip-ocr --output-root output
venv\Scripts\python -m xhs_content_fetcher.cli run "<视频链接>" --cookie "<脱敏>" --skip-llm --skip-ocr --output-root output

12.5 OCR 相关

1
2


venv\Scripts\python -m pip install paddleocr
venv\Scripts\python -m pip install paddlepaddle

12.6 Obsidian 验证

1
2


obsidian --help
obsidian vaults verbose

12.7 发布

1
2
3


git add .gitignore README.md Tempate.md pyproject.toml src
git commit -m "feat: implement end-to-end xhs fetcher with obsidian integration"
git push origin main

13. 我这次最值的三个决策

先做可用性验证，再做架构设计。
把长链路做成“局部失败不拖垮全流程”。
用模板约束生成结构，把质量控制权留在我手里。

14. 下一步优化计划

断点续跑，减少长任务重跑成本。
OCR / LLM 缓存，按 note_id + 素材 hash。
结构化日志，覆盖阶段耗时和错误分类。
模板变量校验，缺失章节自动报错。
“仅更新正文 / 仅更新评论”子命令。
多模型路由与失败回退策略。

15. 最终复盘一句话

这次我真正做成的，不是一个“能跑演示”的脚本，而是一条可定位、可修复、可复测、可发布、可复用的工程链路。

PubArticle2MD 项目复盘：从“能跑”到“可交付”

Mon, 04 May 2026 00:00:00 +0000

这篇文章记录 PubArticle2MD 的完整落地过程。

项目目标不复杂：把公众号文章转成 Markdown 或 PDF，并且给出三种可用形态：

在线可用（GitHub Pages）
本地源码可跑
桌面 EXE 可直接用

真正的难点不在“功能写出来”，而在“交付后别人也能稳定用”。下面按时间顺序展开。

1. 项目目标

初始目标有 4 个：

参考 wechat2pdf 思路，实现公众号文章转 Markdown/PDF。
支持本地运行，尽量不把内容上传到第三方。
提供 PWA 入口，发布到 GitHub Pages。
争取提供普通用户可直接运行的 EXE。

测试文章： https://mp.weixin.qq.com/s/5BOAnJ5H4seYxSbXWi5Ibg

2. 第一版实现：先把主链路跑通

项目先拆成两层：

前端（PWA）：输入链接、选择抓取模式、预览内容、下载文件。
后端（Node API）：/api/health、/api/parse、/api/export/markdown、/api/export/pdf。

PDF 由 Playwright 在后端渲染，优先保证稳定性。

核心代码位置：

public/app.js
server/index.js
desktop/main.js

第一版发布后，基本功能可用，但工程问题开始集中出现。

3. 问题一：GitHub Pages 404

现象

Pages 地址访问 404，页面提示： There isn't a GitHub Pages site here.

排查结果

部署日志显示，问题不在前端资源，而在 Pages 发布状态。工作流存在，但站点链路没有完整激活。

处理方式

检查仓库 Pages 配置。
重新触发部署。
部署后回测 URL。

恢复后的在线入口： https://yourpapayouknow.github.io/PubArticle2MD/

4. 问题二：有 Actions 不代表“可直接使用”

当时发现一个常见误区：流水线很多，但用户路径不清晰。

后续做了收敛：

CI 负责基本检查。
Deploy GitHub Pages 只负责发布 public/。
README 只讲用户需要的路径，删掉不必要的流程噪音。

目标从“流程完整”改为“用户可用”。这一步很关键。

5. 问题三（核心问题）：EXE 是前端壳，不是完整应用

现象

桌面版运行后：

选择本地 API 会报“当前环境没有本地 API 服务”。
运行模式一直显示“纯前端模式（GitHub Pages）”。

根因

桌面进程只做了 loadFile(index.html)，没有启动本地服务。

前端会请求 ./api/health 判断本地 API 是否存在。服务没启动，检测自然失败，所以始终落在纯前端模式。

修复动作

Electron 主进程直接启动本地 API。
- host=127.0.0.1
- port=0（自动分配端口，避免冲突）
窗口优先加载本地 API URL；失败再降级到本地 HTML。
在 before-quit 里关闭 server，避免残留进程。
/api/health 增加 runtime 字段，前端按运行态显示文案：
- 本地 API 模式（桌面 EXE 内置后端）
- 本地 API 模式（Node 服务）
- 纯前端模式（GitHub Pages）

修复后，EXE 从“页面容器”变成了“前后端一体应用”。

6. 问题四：桌面版要稳定，运行环境必须随包

桌面版即使能启动，如果依赖没打进包，用户机器仍会失败。

这里主要处理两件事：

后端代码进包。
Playwright Chromium 随包。

对应改动

package.json 的 build.files 增加 server/**/*。
新增脚本 scripts/ensure-playwright-browsers.js：
- 打包前检查 .local-browsers
- 缺失时自动安装 Chromium
extraResources 加入浏览器目录。
启动时设置 PLAYWRIGHT_BROWSERS_PATH=resources/playwright-browsers。
排除 asar 内重复浏览器资源，避免包体翻倍。

这一步解决了“本机可用、别人不可用”的典型问题。

7. 问题五：Windows 本地发布脚本首次失败

现象

执行以下命令首次失败：

1

npm run release:local -- --tag v1.0.2

报错停在：npm.cmd run desktop:dist。

根因

Windows 下子进程执行 .cmd 时，spawnSync 的默认参数不稳定。

修复

在 scripts/release-local.js 中对 Windows 开启 shell: true。

随后发布链路跑通：

本地构建 EXE
创建 GitHub Release
上传发布资产

版本地址： https://github.com/yourpapayouknow/PubArticle2MD/releases/tag/v1.0.2

8. 当前状态

项目目前可以对外稳定使用：

Pages 在线版可用。
EXE 内置本地 API，不再是前端壳。
PDF 依赖环境已随包。
本地打包和发布流程可复现。
文档已按用户路径重写。

9. 使用方法

9.1 在线版（无需安装）

地址： https://yourpapayouknow.github.io/PubArticle2MD/

步骤：

输入公众号链接。
直连失败时切换“代理 URL”或“粘贴 HTML”。
点击解析。
下载 Markdown ZIP 或 PDF。

示例链接： https://mp.weixin.qq.com/s/5BOAnJ5H4seYxSbXWi5Ibg

9.2 桌面 EXE（推荐）

打开 Release： https://github.com/yourpapayouknow/PubArticle2MD/releases/tag/v1.0.2
下载并运行 EXE。
确认运行模式显示为“本地 API 模式（桌面 EXE 内置后端）”。

9.3 本地源码运行

1
2
3


npm install
npm run install:chromium
npm start

访问：http://127.0.0.1:8787

9.4 命令行批量转换

1

npm run convert -- --url "https://mp.weixin.qq.com/s/5BOAnJ5H4seYxSbXWi5Ibg" --outdir outputs

9.5 本机打包并发布

1
2


gh auth login
npm run release:local -- --tag v1.0.2

10. 这次复盘的核心结论

这个项目最大的收获，不是“做完了一个工具”，而是把工具做成了可交付物。

判断标准很直接：

用户能在线用。
用户能安装用。
开发者能本地复现。
版本能持续发布。

从结果看，真正推动项目跨过这道线的，往往不是新功能，而是对“不可用细节”的持续修复。

MP3 算法基本原理：从波形物理到心理声学

Sat, 04 Apr 2026 00:00:00 +0000

在数字音频讨论里，MP3 常被简单归类为“有损=音质差”。但在高码率（如 320kbps）场景下，很多听众在规范 ABX 测试中并不能稳定区分它和 44.1kHz/16bit 无损源。

这背后的关键不是“MP3 做到了物理无损”，而是它把误差控制在人耳不敏感或被掩蔽的区域。换句话说，MP3 的核心思路不是尽量复制全部波形细节，而是优先保证主观可听质量。

核心前提：心理声学与掩蔽

MP3 依赖两条基本事实：

绝对听阈（ATH）人耳对不同频率敏感度不同。部分极低频、极高频或很弱的信号，即便客观存在，也可能不可闻。
掩蔽效应（Masking）当某一频段存在强信号时，邻近频率的弱信号会变得更难被听见。编码器可以利用这点，把量化误差“放”进不易被察觉的区域。

MP3 编码流水线（简化版）

1. 双通路并行

输入 PCM 后，编码器通常并行进行：

数据通路：负责把信号变换到适合量化和编码的表示形式。
心理声学通路：估计当前帧各频段的可闻阈值，给数据通路提供约束。

2. 子带分析（Polyphase Filter Bank）

先把宽频带信号切成 32 个子带，便于后续分频处理。这一步时间分辨率较好，但频率分辨率仍偏粗。

3. 心理声学分析（常用 FFT 辅助）

编码器通过频谱分析估计：

哪些成分是强掩蔽音；
各频段可容忍多少噪声；
全局掩蔽阈值大致在哪里。

注意：这条通路主要提供“决策依据”，不是直接输出最终编码数据。

4. MDCT 精细频域表示

对子带信号进一步做 MDCT，得到更细粒度的频域系数（长窗常见 576 线，瞬态短窗模式下结构会变化）。

这些系数才是后续量化与码率分配的直接对象。

5. 比特分配与量化：质量和体积的平衡点

编码器需要同时满足两件事：

噪声尽量低于掩蔽阈值；
总比特数不超过目标码率预算。

一个常见参考量是信掩比：

$$ SMR = E_{signal} - T_{mask} $$

其中 $E_{signal}$ 表示信号能量（通常以 dB 度量），$T_{mask}$ 表示该频段掩蔽阈值。

实现上通常是迭代搜索：

内层调整局部量化，控制各频段噪声；
外层控制全局步长和总比特，保证码率目标。

6. 熵编码（Huffman）

量化后大量系数变小或归零，再进行哈夫曼编码，用更短码字表示高频出现符号，进一步压缩数据体积。该步骤本身是无损的。

7. 比特流封装

将主数据、比例因子、侧信息、帧头等按标准格式打包，形成连续 MP3 帧。

小结

MP3 的工程价值在于：它不是“简单删细节”，而是结合听觉模型做受控失真，让失真尽可能落在人耳不敏感区域。

因此，高码率 MP3 往往能在体积和主观听感之间取得很高的性价比。它不是物理意义上的无损，但在很多实际聆听条件下可以达到接近透明的结果。

性快感的进化机制、神经基础与行为功能：跨物种比较视角

Sat, 04 Apr 2026 00:00:00 +0000

性快感的进化机制、神经基础与行为功能：跨物种比较视角

本文基于一组连续讨论，整理一个核心问题：

性快感到底是“生殖副产物”，还是“被自然选择保留下来的行为引擎”？

结论先行：在大多数哺乳动物中，性快感至少是“强化交配行为”的底层机制；而在部分高社会复杂性物种里，它进一步被“升级”为维持关系、降低冲突、促进协作的社会工具。

一、概念拆分：同一个快感，不同层级

谈“性快感”时，常把两层机制混在一起：

生理层：局部刺激 -> 神经传导 -> 奖赏系统激活（多巴胺、内啡肽等）。
行为层：个体是否会在非生殖必要时段，主动重复并利用这种快感。

前者在许多动物中都存在，后者只在少数物种中表现得非常明显。

二、跨物种观察：从“生殖驱动”到“社交驱动”

目前常被讨论的物种包括：

倭黑猩猩（Bonobos）：大量非受孕导向性行为，常用于缓和冲突和建立联盟。
宽吻海豚（Bottlenose dolphins）：存在与繁殖无直接关系的性接触行为，并可见较复杂的社交功能。
日本猕猴（Japanese macaques）：可观察到与快感相关的行为与生理反应模式。
部分蝙蝠等非灵长类：存在会影响交配效率与时长的相关行为。

可粗略看成一个连续谱：

类型	行为特征	典型结果
严格生殖型	高度受发情周期限制	行为短促、目标单一
过渡型	非发情期也有少量相关行为	兼具生殖与减压功能
高社会化型	全年可出现非受孕导向行为	快感成为“社交粘合剂”

三、神经基础：为什么快感会被保留

从演化角度看，交配是高成本行为（耗能、受伤、被捕食风险）。

因此自然选择倾向于把“即时奖励”绑定在交配相关行为上：

奖赏回路（多巴胺系统）提供“值得做”的主观价值。
催产素等系统在部分物种中强化亲密与信任。
强化学习让个体更可能重复有收益的行为。

这使得“个体并不理解后代逻辑，也会愿意去交配”。

四、关键区分：生理反射 vs. 心理预期

很多争论点都在这里。

以犬类为例：

在非发情期，局部刺激也可能引发勃起或排精，这说明“快感硬件”存在。
但是否能稳定转化为“主动、计划性、社交化的追求”，取决于认知能力、社会结构、学习机会与生态成本。

换句话说，不是“有没有快感”，而是“快感在该物种行为系统里的权限有多高”。

五、实验视角：外部刺激能否重塑行为？

经典奖赏实验（如啮齿类自我刺激研究）表明：

只要奖赏反馈足够直接、稳定，动物可快速形成“行为 -> 奖励”的强化闭环。
在实验室环境中，这种闭环甚至能压过进食、休息等行为。

这提示两点：

奖赏系统非常强大。
自然环境中的行为表达，常被捕食压力、资源约束与社会结构“上锁”。

六、人类处境：优势与代价并存

人类的特殊性在于：

性行为较大程度脱离固定发情窗口。
快感可被记忆、想象和文化规则反复重构。

这带来双重结果：

优势：强化亲密关系、社会协作、群体稳定。
代价：在现代“超常刺激”环境下，可能出现注意力挤占、成瘾倾向、风险行为增加等问题。

结语

从跨物种角度看，性快感不是单一现象，而是一套分层系统：

底层是神经奖励机制。
中层是强化学习。
高层才是社交与文化功能。

因此，与其问“哪些动物有性快感”，不如问：

在不同生态和社会条件下，快感被允许承担了多大的行为功能？

这或许才是理解该议题最有解释力的框架。

本地项目上传github的坑点与正确姿势

Mon, 16 Mar 2026 00:00:00 +0000

本地项目上传github的坑点与正确姿势

首先，无论是什么IDE或者编辑器（VS、VScode、Pycharm、Idea、Clion等等），统统不要先在本地创建仓库。

一些坑点

要先绑定github远程仓库，可能出现各种奇怪的问题；
git创建的本地仓库，分支名字是 master ，而github是 main ，直接上传会导致不同分支，不好看；
如果是使用IDE内的版本管理操作的，写完项目再创建仓库，添加文件是会出现困难，重新加 .gitignore 太麻烦了，还可能有各种报错；
仓库间文件不统一，即使使用了 git pull 也还是会报各种错误；
可能因为各种权限问题导致被拒绝push。

建议的正确姿势

进入github主页，点击 New 创建同名的仓库；
1

https://github.com/
- 点击左上角的绿色按钮，按照提示填即可。
创建完毕后，cd到项目存放地，使用 git clone 命令把仓库克隆过来；
1

git clone https://github.com/yourname/yourdepository
- 请在预存放项目的地方打开终端，执行上面的link，后面的仓库地址可以直接从仓库页面下的浏览器链接栏里面复制。
将你要上传的所有文件全部复制进clone下来的文件夹里面；
- 注意，超过100MB的文件无法上传github；
- 注意使用AI添加一个 .gitignore 文件，把有的没的的路径都放进去。
1 2 3 4 5 6 7 8

__pycache__/ *.pyc .env venv/ .idea/ .vscode/ dist/ build/

在终端中依次执行以下命令：

1
2
3


git add .
git commit -m "init"
git push

后续的操作就转移到这个项目目录下进行即可，在IDE中图形化操作即可。

总结

请下次写项目前，先创建仓库别直接开写好吗 /smile

M芯片Mac 配置oMLX遇到的问题相关解决

Sat, 14 Mar 2026 00:00:00 +0000

M芯片Mac配置oMLX遇到的问题相关解决

1

https://github.com/jundot/omlx

1

https://zhuanlan.zhihu.com/p/2014650251089302644

建议使用Homebrew安装

Homebrew是Mac和Linux上的一款包管理，很多应用通过Homebrew分发；
1

[Homebrew官网](https://brew.sh/)
- 要像流畅使用homebrew，建议提前准备科学上网环境。

使用Homebrew安装的oMLX，可以在终端直接使用命令** omlx * **；
请遵循项目地址中readme.md的 Install.Homebrew 这一节来安装，由于涉及到下载与编译，需要等待较长时间（接近1GB的大小）；
下载完毕后，通过 Quickstart.Homebrew Service 这一节教程来启动，以默认设置启动。

配置 ~/.omlx/settings.json

打开访达，进入下载文件夹，按住option键，点击左下角的Macintosh HD，依次点击User\mac，找到.omlx文件夹后进入；
打开settings.json，找到"api_key"这一项，修改或填入为任意短字符串，例如omlx
- 注意，此处为一个坑点，如果此处填写32或者48字符的长字符串，将会导致无法被外部认证，请务必填写短字符串。
- 如果填写长apikey，在一键接入openclaw时，会提示 run omlx serve first 的报错，这个是一个bug。
下载模型文件夹放入 ~/.omlx/models 中
1

https://huggingface.co/Qwen/Qwen3-4B-MLX-4bit
- 注意，模型文件一定是整个文件夹；
- 模型一定是要带 MLX 字样的，否则无法被正常调用；
- 拉取推荐使用 git clone 和 git lfs pull，详情询问AI。
使用brew命令重启omlx服务
1

brew services restart omlx
进入管理GUI，察看状态
1

http://127.0.0.1:8000/admin
- 注意要加admin进入二级页。
- 点击菜单栏中最右边的Chat，看看是否可以正常聊天。如果不可以，则重新尝试，或者打开活动监视器，检查内存是否够用（MAc的机载RAM最少16G）；
- 如果提示 request timeout，调小上下文长度，在 Settings 栏里面。

接入openclaw

在终端中键入 openclaw onboard 配置模型提供商；

1

http://127.0.0.1:8000/v1

1

omlx # 如果你按我的来，就是这个，在本地运行不用担心泄露问题

按部就班填写即可。

配置完毕，切换模型后，请使用 openclaw gateway restart 重启以应用更改（旧版），新版则直接在openclaw GUI中修改即可。

🎵 数字音频与 Hi-Fi 系统硬核指南

Sun, 08 Mar 2026 00:00:00 +0000

🎵 数字音频与 Hi-Fi 系统硬核指南

一、音频规格与听感本质

1. 6Mbps 与 Hi-Res 音频

你目前通过网线传输的 6Mbps 属于极高规格的无损音频流，通常对应 24-bit / 96kHz 或更高的母带级音源。

网线传输的优势：带宽远超蓝牙（LDAC 最高仅 990 Kbps），能确保高规格数据流不被压缩、不卡顿。

音质等级	典型码率	规格参数
标准流媒体	320 Kbps	MP3 / AAC
CD 级无损	~1.4 Mbps	16-bit / 44.1kHz
Hi-Res 高解析	4.6 - 9.2 Mbps	24-bit / 96kHz

2. 听感的两大维度：位深与采样率

位深 (Bit Depth) 决定“动态与底噪”：从 16-bit 升级到 24-bit，理论动态范围从 96dB 提升至 144dB。这带来了极其深邃的“黑背景”，让你能听清极微弱的乐器余音，起伏更加从容。
采样率 (Sample Rate) 决定“空间感与相位”：96kHz 保留了大量极高频泛音（Overtones）和录音室的微小反射声。同时，高采样率让抗混叠滤波器（Anti-aliasing Filter）的介入更平缓，保证了高频的时间/相位准确度。大脑正是通过这些高频的时间差来建立**“空间感”和“结像定位”**的。

3. 历史冷知识：44.1kHz 的由来

早期数字音频没有大容量硬盘存储，工程师只能将其伪装成“视频信号”录在录像带上。为了同时兼容 NTSC（30帧/525行）和 PAL（25帧/625行）两种电视制式，算出了 44,100 Hz 这个完美公约数。

二、信号的翻译与放大 (DAC 与功放)

1. DAC (数模转换器)：精密的“调味师”

负责将 0 和 1 的数字包翻译成连续的模拟微电压信号。

评判好坏的标准：
- 时钟精度：顶级 DAC 使用飞秒时钟消除“抖动（Jitter）”，确保时间轴上的绝对精准，否则声音会发干、毛刺。
- 噪底控制：优秀的数字滤波和极低的量化噪声。
- 模拟输出级：运放（Op-amp）的用料决定了声音最终的色调与质感。

2. 前级 (运放) vs 后级 (功放)

DAC+运放（前级）处理“电压”：它们处理信号级别的能量，负责完美还原声音的波形（乐谱），功率极小。
功放（后级）处理“电流”：它负责能量放大，为微弱的电压信号注入强大的电流，从而产生足够的物理驱动力去推响沉重的音箱振膜（执行力）。
注意：放大信号必然放大底噪。高端功放的核心技术在于提供巨大推力的同时，维持极高的信噪比 (SNR)。

三、发声的物理学：电压、电流与电容

1. 电压与电流的分工

在驱动音箱/耳机时：

电压 (V) 是“信使”：代表了音乐波形的形状和高低起伏，决定振膜“该往哪走、走多远”。
电流 (I) 是“苦力”：根据洛伦兹力公式 F = B * I * L，电流大小直接决定了推动振膜的物理力道。

2. 瞬态失真与削波 (Clipping)

根据欧姆定律 V = I * R：

当音乐出现大动态（如定音鼓重击），线圈瞬间需要极大的电流 $I$。如果功放供电不足（给不出足够的电流），系统的实际输出电压 V 就会被迫下垂（Voltage Sag）。

后果：原本圆滑的波形顶部被“削平”，产生奇次谐波失真。听感上就是低音发软、高音撕裂、声音糊成一团。

3. 大电容的作用：“水压储水罐”

为了防止上述的削波失真，功放电路中会配备硕大的储能电容。

运作逻辑：基于公式 Q = C * V。在音乐平缓时，变压器为电容充电（储蓄电荷 Q）。在大动态瞬间，电容作为离晶体管最近的“水塔”，瞬间向电路释放电荷，从而稳住电压 (V) 不下垂，并提供爆发性的电流 (I)。
结论：电容的容量和响应速度（超低 ESR）直接决定了音响系统“拳拳到肉”的瞬态爆发力。

四、耳机的阻抗博弈

高阻抗耳机的意义

物理设计：采用极细、极轻的导线绕制极多圈数的线圈。轻量化的音圈带来了无与伦比的“瞬态响应”（起停极其干脆）。
驱动逻辑（高压小电流）：基于功率公式 P = V^2 / R。为了达到相同功率，高阻抗耳机主动提升阻抗 $R$，从而允许输入更高的电压 V，同时将电流 I 压制在极低水平。
优势：避免了大电流带来的大发热和线圈烧毁风险，极大降低了输出端的非线性失真，且对线材和接口的接触电阻完全免疫。

关于蓝牙耳机响度的误区：蓝牙耳机连不同设备（如 iPad vs iPhone）听感响度不同，并非因为设备的“推力”不同（蓝牙自身内置功放），而是源于系统的音量归一化策略或绝对音量控制协议差异。

Windows 上有关 Torch 的版本管理问题

Sun, 08 Mar 2026 00:00:00 +0000

Windows上有关Torch的版本管理问题

不要完全相信AI的话

AI在此领域的资料有明显滞后性；
AI处理环境问题显得非常力不从心，容易陷入思维定势；
一旦AI然你重新配置环境，立刻放弃继续询问AI。

配置环境的正确步骤

如果你使用Nvidia显卡，请务必仔细；

打开Pytorch官网链接：

1

[https://pytorch.org/get-started/locally/](https://pytorch.org/get-started/locally/)

在页面中选择与自身机器匹配的版本：

1

nvidia-smi # 在终端执行此命令，查看CUDA版本，若为非Nvidia显卡，则忽略此条

1

pip3 install torch torchaudio torchvision --index-url [https://download.pytorch.org/whl/cu130](https://download.pytorch.org/whl/cu130) # 根据我的电脑来的，pip3 可换成 pip 或 uv pip

如果有torchcodec的需求：

1

[https://github.com/meta-pytorch/torchcodec?tab=readme-ov-file#installing-torchcodec](https://github.com/meta-pytorch/torchcodec?tab=readme-ov-file#installing-torchcodec)

在这里查看与所安装的torch相匹配的版本。

在环境目录下的终端中，运行安装命令。

1

uv pip install torch torchaudio torchvision --index-url [https://download.pytorch.org/whl/cu130](https://download.pytorch.org/whl/cu130)

1

conda install -c conda-forge "torchcodec=*=*cuda*"

注意，windows下的torchcodec需要在conda环境下安装，以支持调用cuda加速。

为什么ISO都100了，噪点还是爆炸？

Mon, 09 Jun 2025 00:00:00 +0000

前情提要

然思齐是一名摄影小白，使用Z30相机在网上自学摄影。他知道，ISO很影响噪点，因此他一直保持ISO100-400。有一次，他和朋友晚上去公园拍摄，即使环境很暗，也坚持400的ISO。回家后导入电脑一看，发现照片有很多噪点，尤其是暗部，密集的彩色噪点极大影响了照片质量。因此他很苦恼，想了解为什么会变成这样。

噪点的分类

对于一幅图像上的噪点，可以分为三类：**读出噪声**、**光子散粒噪声**、**热噪声**。
**读出噪声**

读出噪声

总览

Tue, 28 May 2019 00:00:00 +0000

Mon, 01 Jan 0001 00:00:00 +0000

博客润色固定规范

本文件用于约束 content/post 下文章的润色方式。后续本线程内提交的每一篇文稿，默认按本规范执行。

1. 目标

降低 AI 生成痕迹。
降低与原始稿件的表面相似度。
保留原文关键信息、观点和结论，不改变事实。
输出风格符合学术写作基本规范，术语准确，标点规范，逻辑清楚。

2. 语言风格

以直白、准确、自然为主。
少用修辞，少用夸张表达，避免堆叠形容词。
避免空泛套话，避免模板化段落开头与结尾。
语气可口语化，但不随意，不失专业性。
叙述视角固定为我的第一人称口吻，不使用助手视角或对用户说明式口吻。

3. 句式规则

优先短句，减少长复合句和多层从句。
一句只承载一个核心信息点。
允许灵活变换语序，避免整段句式过于工整。
控制连接词密度，避免首先其次最后反复出现。

4. 结构与信息

不删减关键事实、数据、限定条件、前提假设。
不引入原文没有的新结论。
对重复信息做合并，但保留必要解释链条。
专业术语保留准确写法，首次出现时可补最短说明。
若原文是过程记录，优先保留可证明执行过程的细节，包含关键命令、典型报错、定位步骤、修复动作、复测结果。

5. 标点与格式

中文语境下统一使用中文标点。
禁止用括号补充说明、编者注或版本标签，不写对读者无增益的元信息。
减少连续破折号和感叹号堆叠等痕迹化写法。
段落长度自然，不机械对齐。
列表仅在确有并列信息时使用，不强行列表化。

6. 每次润色执行清单

动笔前先通读本规范并按条执行。
检查是否有 AI 套话，如空泛总结、过度平衡句。
检查形容词和副词是否过多，能删则删。
检查长句是否可拆分，拆后是否更清楚。
检查术语、事实、数字是否与原文一致。
检查全文语气是否自然统一。
检查是否全程为我的叙述角度，避免出现用户、我方、助手等第三方代写痕迹词。

7. 默认工作方式

你提供原稿后，我直接给出润色稿。
如你未特别说明，我会在保留原意的前提下进行中等强度改写。
如你要求，我可切换为轻度改写，最小改动，或重度改写，更大幅度重写表达。

8. 生效范围

本规则对本仓库后续所有博客润色任务持续生效，直至你明确要求修改或废止。

关于

Mon, 01 Jan 0001 00:00:00 +0000

This is a test page for i18n support.

快速链接

Mon, 01 Jan 0001 00:00:00 +0000

设计令牌

Mon, 01 Jan 0001 00:00:00 +0000

SVG图标

MingCute Icons

精心设计的开源图标库，提供1663个核心图标，覆盖常规与实心两种风格。

Solar Icons

1451个图标的统一目录，六种风格同源输出，适配主流框架与设计工具。

Iconoir

基于24像素网格的1600余个SVG图标，风格克制，覆盖Web与移动端场景。

色卡

待上传

UI布局

待上传

搜索

Mon, 01 Jan 0001 00:00:00 +0000

iwmei的博客

BilibiliContentFetcher 项目复盘：从单条演示到批处理闭环

1. 起点目标

2. 阶段 A

2.1 质量约束改造

2.2 评论区典型性改造

2.3 阶段 A 实跑

3. 阶段 B

3.1 DeepSeek Key 缺失

3.2 Vault 路径空值误解析

3.3 DeepSeek 真链路验证

4. 阶段 C

4.1 批处理子命令落地

4.2 Windows 编码崩溃修复

5. 阶段 D

5.1 英文噪声词进入概念区

5.2 模型结果被回退过度覆盖

5.3 阶段 D 复跑

6. 阶段 E

6.1 同构基线

6.2 新增模块

6.3 重构模块

6.4 文档和入口

6.5 阶段 E 验收

7. 阶段 F

8. 问题清单汇总

9. 关键命令流水

9.1 质量回归

9.2 单条链路

9.3 批量链路

9.4 配置检查

9.5 版本管理

10. 最终状态

11. 我这次最关键的决策

12. 下一步计划

XHSContentFetcher 项目复盘：从空仓到可发布 CLI

0. 起点与约束

0.1 初始仓库状态

0.2 我给自己写死的目标，来自 计划.md

0.3 现实条件

1. 预研阶段：先确认抓取链路可行

1.1 动作一：确认项目现状

1.2 动作二：完整读取计划

1.3 动作三：核查参考仓库

1.4 动作四：抓取库选型

1.5 动作五：用真实 Cookie + 真实链接做最小验证

2. 工程搭建阶段：从 0 到可执行 CLI

2.1 基础文件落地

2.2 模块化拆分，第一版

2.3 初始测试

3. 首轮端到端联调：先跑通图文 / 视频主链路

3.1 第一个关键故障：API error: {"code": -1}

3.2 我的定位路径

3.3 修复动作

4. 媒体与 OCR 深度修复：这部分最耗时

4.1 图片输出成 .bin

4.2 OCR 初始化失败：缺底层依赖

4.3 PaddleOCR 参数兼容问题

4.4 oneDNN / MKLDNN 兼容报错

4.5 中文路径导致 Invalid argument

4.6 OCR 文本污染

4.7 OCR 超时不是功能失败

5. 提示词迭代：从“复述”改到“可读笔记”

5.1 第一次改造：强化提示词约束

5.2 第二次改造：模板优先，禁用硬编码骨架

6. URL 解析事故：discovery/item/<id>

6.1 故障现象

6.2 我的定位过程

6.3 修复方案

7. Obsidian 对接联调：命令可用，但编码有坑

7.1 CLI 可用性验证

7.2 真机写入 + 自动打开

7.3 UnicodeDecodeError 修复

8. 我做过的回归验证清单

9. 文档、清理与发布

9.1 清理动作

9.2 README 重写范围

9.3 Git 提交和推送

10. 本次产出的最终代码结构

11. 关键报错与修复对照

0.2 我给自己写死的目标，来自 `计划.md`

3.1 第一个关键故障：`API error: {"code": -1}`

4.1 图片输出成 `.bin`

4.5 中文路径导致 `Invalid argument`

6. URL 解析事故：`discovery/item/<id>`

7.3 `UnicodeDecodeError` 修复

一、音频规格与听感本质