下载与传输#

1. Free Download Manager：下载加速与管理#

官方网站：Free Download Manager · 下载页面

Free Download Manager（FDM）是一款免费的下载管理器，支持 Windows、macOS、Android 和 Linux。它可以把文件分成多个片段并行下载，支持断点续传，也内置 BitTorrent 和磁力链接下载功能。

它还提供浏览器集成，适合集中管理日常下载任务，尤其是较大的文件、视频和种子任务。软件官网提供无广告、无恶意软件的版本；安装时仍建议从官方网站下载，并留意下载来源与文件类型。截图来自 FDM 官网的 Windows 界面。

图像与视频#

1. Upscayl：图像超分辨率#

GitHub：Upscayl

Upscayl 是一款免费、开源的 AI 图像超分辨率工具，用于放大低分辨率图片并增强画面细节，支持 Windows、macOS 和 Linux。

适合需要提高图片分辨率时使用。运行需要兼容 Vulkan 的显卡，部分集成显卡可能无法使用，使用前应确认设备兼容性。

2. video-parser：视频解析与下载#

GitHub：video-parser

这是一个基于 FastAPI、Gradio 和 Qwen3-VL 的视频解析、下载与 AI 内容提取工具。项目提供抖音、哔哩哔哩、小红书、快手、好看视频等平台的视频链接解析、下载及在线播放功能，还可借助视觉语言模型提取视频内容并生成文字描述。

界面支持输入视频链接、选择或自动检测平台，并展示解析状态、视频标题和封面。具体解析效果可能受平台接口变化影响；下载和使用视频时应尊重版权与平台规则，仅处理自己有权使用的内容。

3. OpenScreen：屏幕录制与演示视频制作#

GitHub：OpenScreen

OpenScreen 是一款免费、开源的屏幕录制与演示视频制作工具，适合制作产品演示和操作教程。可以录制窗口或整个屏幕，再通过画面缩放、光标效果、自定义背景和时间轴剪辑整理录屏，导出 MP4 或 GIF。

它提供部分与 Screen Studio 类似的核心功能，但不是功能完全一致的替代品。项目说明提示软件仍可能存在问题，制作重要视频时应先测试录制与导出流程。

维护状态提醒：该仓库 README 已注明原项目归档、不再维护，并提供社区接续版本入口；下载前建议查看仓库中的维护说明和发布记录。

4. video-use：用 Coding Agent 剪辑视频#

GitHub：video-use

video-use 是一个面向 Coding Agent 的开源视频剪辑项目。把原始视频放到目录中，用自然语言描述剪辑目标，让 Agent 整理素材、提出剪辑方案，确认后完成渲染与检查。

它支持删除口头填充词和停顿、添加字幕、调色及制作动画叠加。它不是传统的图形化剪辑软件；截图展示的是辅助剪辑判断的时间轴视图。使用需要配置 FFmpeg 等依赖，项目的转写流程还依赖 ElevenLabs API，应留意素材上传与服务费用。

浏览器与网页体验#

1. BewlyBewly：哔哩哔哩界面美化#

GitHub：BewlyBewly · Chrome 应用商店：安装 BewlyBewly

BewlyBewly 是一个开源的哔哩哔哩浏览器扩展，主要通过重新设计网页界面改善浏览体验。它调整首页布局、视频卡片和导航，并为常用页面提供深色模式；截图展示的是扩展启用后的首页效果。

适合想让 B 站网页界面更简洁、统一的场景。项目侧重页面调整与视觉优化，并不是视频下载工具，也不意味着所有页面都已适配深色模式。

维护状态提醒：该 GitHub 仓库已于 2025 年 2 月 26 日归档，处于只读状态。安装前建议查看应用商店说明与项目维护状态，留意 B 站页面变化可能带来的兼容性问题。

阅读与收藏#

1. Omnivore：稍后阅读与文章管理#

GitHub：Omnivore

Omnivore 是一款开源的稍后阅读工具，用于集中保存文章，并通过标签、搜索、高亮和笔记整理阅读内容。它也支持 PDF、邮件订阅内容和 RSS，并提供 Obsidian 集成。

适合先收藏、再集中阅读和整理的场景。需要注意，原有云服务已于 2024 年 11 月停止，目前项目以自托管方式使用；截图展示的是界面示例，不代表原在线服务仍可用。

市场与行情#

1. OpenStock：股票行情与市场信息#

GitHub：OpenStock

OpenStock 是一款开源的股票市场信息应用，用于查看市场概览、股票行情、热力图及公司信息，也支持搜索股票和建立个人关注列表。

适合把关注的股票与市场信息集中到一个界面中查看。自行部署需要配置数据库和行情数据接口；数据更新频率、覆盖范围与实时性取决于数据源和部署配置，不能默认所有行情都是实时的。

它不是证券交易平台，页面中的行情与信息也不构成投资建议。

AI 与工作流#

1. TongFlow：多模态 AI 工作台#

GitHub：TongFlow

TongFlow 是一个开源的多模态生成式 AI 工作台，把文本、图像、音频、视频等输入与模型能力组织成画布上的节点，通过添加、转换和组合构建创作流程。

适合将多个生成步骤放到同一个工作流里，例如先根据文字生成图片，再组合多张图片，或串联脚本、语音和视频生成。不同能力由插件提供，实际可用功能取决于插件和模型服务配置。

项目提供浏览器云端工作台及桌面入口，也支持从源码或通过 Docker 自托管。桌面入口不等于所有模型都在本地运行，使用时应区分云端服务与自托管配置。

2. ComfyUI：节点式 AI 生成工作流#

GitHub：ComfyUI

ComfyUI 是一个开源的节点式 AI 生成界面与后端。通过连接模型加载、提示词编码、采样、解码和保存等节点，把生成过程组织成可以保存、复用和调整的工作流。

适合需要控制生成步骤、组合不同模型和反复调试参数的场景。可用能力取决于模型、节点和扩展配置，运行前需要确认相应的硬件与依赖要求；安装第三方节点时也应留意来源与安全性。

3. img2threejs：从参考图重建 Three.js 模型#

GitHub：img2threejs

img2threejs 是一个从参考图重建 Three.js 模型的开源项目与 Agent Skill。它强调用可检查、可修改的程序化代码构建几何体，通过分阶段检查与参考图对照，逐步调整模型。

输出重点是可维护、适合继续动画化的代码，而不是一个只能导入使用的封闭模型资产。适合探索图像到代码驱动 3D 场景的制作流程，重建效果仍取决于参考图、Agent 能力与迭代调整。

1. 中文授课稿改写提示词#

1
请把下面的文稿改成“专业教师可以直接朗读的中文授课稿”。
2

3
我的目标不是随意聊天，也不是教材摘要，而是：
4
句子完整、对象明确、上下文连贯、口语自然，同时保持专业准确。
5

6
请按以下要求修改：
7

8
1. 明确主语和讲述对象
9
定义句、提问句、结论句、转折句必须明确在讨论哪个对象。
10
不要让听众猜“谁满足条件”“哪个量在变化”“哪个事件有概率”。
11
不要机械地给每句话添加“我们”；应当使用准确的对象名称作主语。
12
同一句中主语清楚时，可以自然承接，避免重复啰嗦。
13

14
2. 保持专业定义
15
先给出准确的定义，再用完整的口头语言解释。
16
不要用模糊说法、比喻或口号代替定义。
17
保留结论成立的条件，不要为了通俗而扩大结论的适用范围。
18

19
3. 补足上下文衔接
20
引入新概念前，先说明当前有什么问题、为什么需要这个概念。
21
后一句应承接前一句已经出现的对象或问题。
22
不要只靠“接下来、那么、因此”等连接词制造表面的连贯。
23

24
4. 检查必要的前置知识
25
检查是否出现了未经解释的术语、符号、条件或方法。
26
对理解当前内容必需的知识，补上最短的必要解释。
27
不要默认听众能自行补出关键步骤，也不要展开完整理论和全部推导。
28

29
5. 准确区分对象
30
特别检查是否混淆了对象本身、对象的取值、相关集合、
31
条件以及由它们计算出的量。
32
数学稿中尤其要区分函数与函数值、事件与概率、密度与单点概率。
33

34
6. 使用自然的授课语言
35
使用完整、顺口、适合朗读的句子，避免提纲式短语和名词堆叠。
36
不要故意加入网络用语、语气词、夸张表达或不恰当的比喻。
37
不要把每一段都写成设问，也不要反复强调“这很重要”。
38

39
7. 控制内容与篇幅
40
保留原有知识范围和已经确定的教学顺序。
41
删除重复解释、没有教学作用的简单例子和无意义的演算。
42
只补理解所必需的内容，不要借修改之名扩写整门课程。
43
优先用更准确的句子替换旧句，而不是不断追加解释。
44

45
修改后，请再从“听众只听一遍、不回看文字”的角度检查：
46
- 听众能否知道每句话在讲哪个对象？
47
- 代词和省略成分是否有明确指向？
48
- 新概念是否有必要的引入？
49
- 结论是否交代了条件与必要理由？
50
- 是否仍有可以删去的重复内容？
51

52
请输出修改后的完整文稿，再简要列出主要修改。
53
如果发现会影响原意的专业错误，请单独说明。
54
若涉及文件，请另存新版本，不覆盖原稿。
55

56
文稿如下：
57
【粘贴文稿】

2. AGENTS.md 配置提示词#

1
你是一个 Coding Agent。请在当前项目中创建或更新根目录的 `AGENTS.md`，为后续 AI 编程任务写入一套清晰、可执行、不过度冗长的规则，让 CodeGraph、Caveman、Ponytail 分工互补。
2

3
本任务不只是写文档：还要检查当前电脑上的全局工具配置、在缺少时完成必要配置、为当前项目初始化所需配置，并实际验证三者能否使用。
4

5
参考：
6
- Ponytail：https://github.com/DietrichGebert/ponytail
7
- Caveman：https://github.com/JuliusBrussee/caveman
8
- CodeGraph MCP 设置示例：https://github.com/shantham/codegraph/blob/main/docs/MCP-SERVER-SETUP.md
9
- Model Context Protocol：https://modelcontextprotocol.io/
10

11
## 执行步骤
12

13
1. 先检查当前项目的 `AGENTS.md`、Git 状态和未提交改动；检查当前 Coding Agent 的全局配置、相关 Skill/插件、MCP 服务和可用命令。不要覆盖已有配置或无关改动，也不要输出密钥、令牌或其他凭据。
14
2. 如果当前电脑缺少所需的全局配置，只为当前使用的 Coding Agent 补齐：
15
   - **CodeGraph**：按官方说明配置全局 MCP 服务。
16
   - **Caveman**：按 Skill/工作流安装和使用；不把 CLI 当作前置条件，不为此安装 CLI 或索取 API Key。
17
   - **Ponytail**：配置其 Skill/插件，使 Full 模式可用。
18
   修改已有全局配置前先备份到项目目录之外，并保留其他设置。若配置依赖用户提供的凭据，停止并说明如何在本机安全配置；不要让用户把密钥发到聊天中。
19
3. 全局工具可用后，初始化当前项目所需的 CodeGraph 索引。全局 MCP 配置与项目索引是两件事，不能互相替代。索引范围限制在源码、测试等代码目录；排除个人数据、凭据、依赖目录、构建产物和其他不相关内容。若无法安全划定索引范围，先询问用户。
20
4. 实际验证三者，而不只检查“已安装”状态：
21
   - **CodeGraph**：在当前项目索引中查询文件或符号，确认结果属于当前项目和预期范围。
22
   - **Caveman**：使用已安装的相关 Skill/工作流，完成一次不修改文件的调查或简报验证；明确区分事实与推断。
23
   - **Ponytail**：以 Full 模式对一个只读的小任务展示最小正确方案，不修改无关文件。
24
   不得把读取配置、找到 Skill 文件或其他项目的索引结果声称为成功调用。若工具无法实际运行，如实记录失败原因。
25
5. 创建或更新项目根目录的 `AGENTS.md`：
26
   - 若文件已存在，保留原有内容，只追加或合并；不得删除、覆盖或擅自重写现有规则。
27
   - 若已有 CodeGraph 规则，保留并复用，避免重复粘贴。
28
   - 只写对后续任务持久有效的协作规则，不把机器路径、密钥、临时日志写进项目文档。
29

30
## `AGENTS.md` 中应写明的协作规则
31

32
- **CodeGraph** 用于代码结构查询：定义、调用链、影响范围和上下文。结构问题优先使用；核实当前会话确实提供 CodeGraph，且索引对应当前项目。
33
- **Caveman** 按 Skill/工作流使用：不明问题先调查，报告简短且证据优先，必要时采用安全重构或外科式修复。不得将 CLI 作为前置条件，也不得声称调用了未加载的 Skill。
34
- **Ponytail** 用于最小正确实现：采用 YAGNI、复用现有代码、优先标准库/平台能力和已有依赖、避免无理由新增依赖或抽象。实现时使用 Full 模式；若 Skill 未加载，可遵循原则但不得声称已调用。
35
- 默认顺序：结构问题先用 CodeGraph；不明问题先调查；实现时用 Ponytail Full；最后按风险做最小必要验证，并遵守项目已有的强制检查。
36
- 正确性、安全、数据安全、用户明确要求和无障碍基础都高于“少写代码”；不得为精简而削弱这些要求。
37
- 最终报告简短说明改动、原因、实际验证结果和剩余风险；未运行的检查不得报告为通过。
38

39
## 验收与回复
40

41
检查 `AGENTS.md` 的 Markdown 标题层级、代码围栏和文件结尾；执行 `git diff --check`。文档改动不运行无关构建测试，但工具配置和项目索引必须按上面的步骤实际验证。
42

43
完成后分别报告：
44
- `AGENTS.md` 的绝对路径，以及是创建还是更新；
45
- 是否发现并保留已有 CodeGraph 规则；
46
- 全局配置中哪些已存在、哪些新配置；
47
- 项目索引的位置、范围和排除项；
48
- CodeGraph、Caveman、Ponytail 各自的实际验证结果；
49
- 未能验证的部分、原因和剩余风险。

3. 前端视觉与交互检查提示词#

1
请先全面检查现有前端页面，重点检查以下问题：
2

3
1. 不必要、丑陋或风格不统一的图标。
4
2. 多余且没有实际意义的小字。
5
3. 按钮点击、状态切换时的频闪，以及不自然或多余的动画效果。
6
4. 所有按钮的边框位置、对齐和显示是否正常；结合现有页面风格，判断哪些按钮需要补充或调整边框与阴影，避免统一套用。
7

8
需要替换的图标统一从 Iconify 图标库中挑选，尽量使用同一图标集，保持风格一致：
9
https://icon-sets.iconify.design/
10

11
先把发现的问题、对应页面或组件位置，以及修改建议整理出来给我审核。
12

13
涉及图标替换时，制作一个可在浏览器中查看的图标审核页，展示原图标与候选图标的对比、各自的 Iconify 名称（如适用）、使用位置和替换理由，方便我逐项审核。审核页仅用于预览，不直接替换业务页面中的图标。
14

15
确认后再动手修改，不要直接批量调整。

常用 Skills#

GitHub：我的 Skills 仓库

技术与实践#

1. 【文章】终端里的 ASCII 控制字符 · Julia Evans · 配套速查表
   解释终端中常见 Ctrl 组合键与 ASCII 控制字符的关系，并提供速查表，具体行为会因环境和配置而异。
   收录：2026-09-23

AI 与工具#

学习与思考#

1. 【视频】从理解差异到经营亲密：一套恋爱关系方法论 — real_屠龙的胭脂井
   从理解男女差异、建立吸引与依恋，到判断关系并经营亲密，也呈现了将恋爱策略化、强调掌控与忠诚的一面。
   收录：2026-09-23

2. 【视频】数学地图：数学全分支（26重制）
   从数、结构、空间与变化出发，梳理纯数学、应用数学与数学基础的主要分支，以及它们与物理、计算机科学、机器学习等领域的联系。适合建立数学全局视野，学习具体知识时回来定位它所在的位置。
   收录：2026-10-07

设计与表达#

生活与见闻#

数学基础与逻辑#

概率与统计#

我为什么开始折腾 CI/CD#

最开始，我的部署方式完全是手动的：本地写完代码，先推送到 GitHub，再通过 SSH 登录服务器，手动 git pull 拉取代码，执行 npm install 安装依赖，再用 npm run build 构建，最后更新线上服务。

但实际操作中，构建经常卡住，连带着 SSH 连接也会中断。我已经确认，原因就是服务器内存不足：服务器内存只有约 1.6 GiB，一边运行线上服务，一边执行构建，内存不够用。因此，需要把构建工作搬离服务器，让它只负责运行服务。

于是，我先想到一个办法：在本地构建好，再用 SCP 把产物上传到服务器，让服务器只负责运行。 这一步解决的是“在哪里构建”的问题，但构建、上传、更新版本这些操作，仍然需要我手动完成。

接着，我想到了以前一直听说、却从来没用过的 GitHub Actions：既然这些步骤每次都差不多，能不能让 GitHub 在收到代码后，自动替我执行？

我想达到的效果是：

1
本地修改代码，push 到 GitHub
2
  ↓
3
GitHub Actions 自动验证和构建
4
  ↓
5
把构建产物上传到服务器
6
  ↓
7
服务器更新版本并检查服务是否正常

所以，我学习 CI/CD 不是为了先记住一套概念，而是为了解决一个具体问题：从“SSH 登录服务器，手动拉代码、装依赖、构建”，变成“我只负责推送代码，流水线负责验证、构建和部署”。

这条思路分成两步就很清楚：先把构建搬离服务器，减轻服务器压力；再把重复的发布步骤交给 GitHub Actions，减少手动操作。

这张图展示从提交代码到上线的完整流程：push 后，GitHub Actions 自动验证、构建并打包，通过 SCP 上传产物，再通过 SSH 执行服务器上的版本切换和重启，最后做健康检查，失败时尝试回滚。核心是把构建交给 Actions，服务器只负责运行产物。

一、我的部署分工#

最终采用的分工是：

1
本地电脑
2
  └─ 写代码，git push
3

4
GitHub Actions runner
5
  ├─ 拉取代码
6
  ├─ 安装依赖
7
  ├─ 运行测试
8
  ├─ 构建 Next.js standalone
9
  └─ 打包部署产物
10

11
生产服务器
12
  ├─ 接收压缩包
13
  ├─ 解压到 releases/<commit-sha>
14
  ├─ 切换 current 软链接
15
  ├─ 重启 systemd 服务
16
  └─ 做健康检查

为了尽早发现代码问题、减少手动发布操作，我们把验证和部署组织成 CI/CD 流程：

• CI（Continuous Integration，持续集成）：频繁地将代码变更集成到共享主干，并通过自动构建、测试等检查，尽早发现问题。本文中的安装依赖、测试和构建，就是其中的自动验证步骤。
• CD（Continuous Deployment，持续部署）：本文采用这一含义，即在 CI 检查通过后，自动将构建产物部署到生产环境并更新服务，不需要人工批准上线。

这个项目推送到 master 后会自动验证、构建并部署，采用的就是持续集成 + 持续部署。GitHub Actions 是执行这套流程的工具，不是 CI/CD 本身。

二、从 push 到上线的主线#

实际流程压缩起来就是这一条：

这张图按执行位置串起发布主线：本地 push 触发工作流，runner 负责验证、构建和打包，再通过 SCP 上传产物、SSH 执行服务器上的版本更新，健康检查通过后完成发布。

GitHub Actions 是 GitHub 提供的自动化工具：在 .github/workflows/ 中编写 workflow（工作流），由 on 指定 push 等触发事件。一个 workflow 包含一个或多个 job（任务），每个 job 由 **runner（执行机器）**执行，内部的 **step（步骤）**按顺序运行；step 用 run 执行命令，或用 uses 调用封装好的 action（操作）。不同 job 默认可并行，用 needs 指定先后依赖；runner 不等于生产服务器，远程部署需通过 SSH 等方式连接。

下面用项目中的几个配置项，看看这些概念在 YAML 中怎么写。以下是局部示例，不是完整的部署配置。

第一个例子：什么时候触发 workflow？

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

on 指定整个 workflow 的触发条件：push 配合 branches: [master]，表示向 master 推送代码时运行；workflow_dispatch 则允许在 GitHub 页面手动触发。这里决定的是“什么时候开始”，还没有描述具体做什么。

第二个例子：job 在哪里执行，step 做什么？

下面补出必要层级作示意，其他步骤省略：

1
jobs:
2
  build:
3
    runs-on: ubuntu-latest
4
    steps:
5
      - uses: actions/setup-node@v4
6
        with:
7
          node-version: 22
8
          cache: npm

这里的 build 是 job 的标识，runs-on 为它选择 GitHub 提供的 Ubuntu 执行机器；steps 中的这个步骤通过 uses 调用 actions/setup-node，准备 Node.js 环境。with 是传给这个 action 的参数：使用 Node.js 22，并启用 npm 缓存来加快依赖准备，但缓存不能代替后续的 npm ci 安装步骤。注意，@v4 是 action 的版本，22 才是 Node.js 的版本。

Next.js 使用 standalone 输出：

1
output: 'standalone'

standalone 的意义是：生产服务器不需要完整源码和完整 node_modules，主要运行构建后的：

1
.next/standalone/server.js

这正好适合低内存服务器。

三、服务器上怎么切换版本#

服务器不是直接覆盖旧目录，而是保留多个 release：

图中 incoming/ 暂存上传的包，releases/ 分别保存新旧版本，current 是指向所选版本的软链接，.env 则单独留在服务器。新版本先准备完整，再切换入口并重启服务，避免直接覆盖旧文件，也为失败回滚保留旧版本。

1
~/English_Context/
2
├── incoming/
3
├── releases/
4
│   ├── <sha-1>/
5
│   └── <sha-2>/
6
├── current -> releases/<当前版本>
7
└── .env

每次新版本上传后，先解压到：

1
releases/<commit-sha>/

然后把 current 软链接切过去：

1
ln -sfn "$release" "$next_link"
2
mv -Tf "$next_link" "$current"

这样做的好处是，服务目录要么指向完整旧版本，要么指向完整新版本，不会停在复制了一半的状态。

服务由用户级 systemd 运行：

1
WorkingDirectory=%h/English_Context/current
2
Environment=NODE_ENV=production
3
Environment=PORT=3456
4
Environment=HOSTNAME=0.0.0.0
5
ExecStart=/usr/bin/node server.js
6
Restart=on-failure
7
RestartSec=5

部署脚本切换 current 后，执行：

1
systemctl --user daemon-reload
2
systemctl --user restart english-context.service

最后用 curl 检查本机端口：

1
curl -fsS --max-time 2 "http://127.0.0.1:3456/"

这个检查不代表业务完全正常，但至少能确认 Next.js 服务已经启动，并且 HTTP 能返回成功状态。

四、失败时怎么退回去#

自动部署一定要考虑失败。这里最需要处理的是：文件已经上传了，current 也切到新版本了，但服务启动失败或健康检查失败。

脚本会在切换前记录旧版本：

沿着上排看：先记录旧版本，再切到新版本并重启，随后检查服务是否正常响应；如果检查失败，就沿虚线进入下排，把 current 切回旧目录并重启。回滚能成立，是因为旧版本仍被完整保留，而不是失败后再重新构建一次。

1
previous="$(readlink -f "$current")"

如果新版本失败，就把 current 切回旧版本，并重启服务：

1
ln -sfn "$previous" "$next_link"
2
mv -Tf "$next_link" "$current"
3
systemctl --user restart "$unit_name"

这只能回滚应用目录，不能回滚所有东西。数据库、用户数据、缓存、Service Worker 都可能有自己的状态。

五、数据库迁移单独处理#

ContextVocab 使用 Prisma 和 PostgreSQL。应用发布和数据库结构变更不是一回事：

左边的应用版本可以通过 current 切回旧目录，右边的数据库变更却不会随之撤销：例如字段已经被删除，退回旧代码也无法把它恢复。因此，数据库迁移需要单独处理，优先做兼容新旧代码的渐进变更，不能把应用回滚当成数据库回滚。

1
应用代码发布
2
数据库 schema/migration 发布

当前 workflow 不自动执行数据库迁移。原因是：应用 release 可以切回去，但数据库迁移未必可逆。

生产数据库更适合渐进式处理：

1
1. 先添加兼容旧代码的新字段
2
2. 部署兼容新旧结构的代码
3
3. 执行数据回填或索引调整
4
4. 验证生产读写
5
5. 后续版本再删除旧字段

这样新旧代码在过渡期都能工作，出问题时也更容易退回。

六、这套方案的核心#

这篇记录里真正重要的不是 GitHub Actions 的 YAML 细节，而是这条分工：

1
本地负责写代码和推送
2
GitHub Actions 负责验证和构建
3
服务器负责运行产物和切换版本
4
健康检查决定发布是否成功
5
失败时回滚应用 release
6
数据库迁移单独设计

对低内存服务器来说，这比“SSH 上去现场构建”稳定很多。

阈限空间#

“阈限”来自拉丁语 limen，意思是门槛或临界。走廊、等候室、停车场都属于这类空间：人们来这里是为了经过，很少把它们当作目的地。²

凌晨的商场、放假后的学校走廊、空停车场，都是常见题材。建筑和设施还在，人和日常活动却消失了。²

这条走廊属于什么建筑，又通向哪里，画面都没有交代。柱子、顶灯和转角一再重复，视线找不到可以停下来的终点。

我们平时会靠建筑和物件判断一个地方是做什么的。阈限空间没有抹掉这些提示，只是抽走了本该在这里发生的活动，于是熟悉的地方突然变得不太对劲。

“核类美学”是什么#

中文互联网所说的“核”，来自英文后缀 -core，大致是“围绕某种元素形成的风格”。它本身不等于恐怖，也不一定诡异。梦核偏向梦境感，怪核偏向异常感，池核则围绕水池空间展开。³

判断一幅图更接近哪种风格，可以先问几件事：

• 它主要在拍什么：梦境、异常信息，还是水池？
• 这个地方出了什么问题：空无一人、已经废弃、失去用途，还是根本不符合建筑逻辑？
• 画面又是怎样处理的：柔光和旧画质，故障效果，还是蓝白色的水光？

这些分类并不互斥。一座无人泳池，题材上是池核，空间状态带有阈限感；如果再加上故障和低清效果，画面也会染上怪核的味道。

梦核#

视觉语法#

按美学 Wiki 的说法，梦核是一种用图像、视频和音乐表现梦境及梦中感受的超现实主义美学。⁴

柔和的蓝色、浓雾、对称摆放的盆栽，还有一路向下的瓷砖台阶。楼梯通向哪里？水面从哪儿开始？图里没有答案，也找不到能判断尺度和方向的参照物。⁵

所以它既像池核，也像梦核。水池、瓷砖和蓝色调来自池核，柔焦、无人场景与含混的空间关系又把它推向了梦境。

梦核喜欢挪用学校走廊、游乐场、商场和卧室这类带有童年记忆的地方，再塞进不合常理的生物、物件或空间关系。你认得每样东西，却说不清它们为什么会同时出现在这里。

粗略地说，它常由童年场景、错位的物件或生物，再加一层旧影像质感组成。

胶片光晕、划痕、压缩噪点和冷色荧光灯，会让画面像一段来历不明的旧录像。童年符号让人产生“我好像见过”的感觉，空间错位又马上让这份熟悉感站不住脚。

它常以阈限空间、不切实际的地形或梦幻场所为底，再叠上文字、眼睛、翅膀、奇怪生物、RPG 文本框、电脑弹窗或 CRT 电视机。⁴

这些符号未必对应某个具体的梦。梦核借用的是梦的组织方式：东西可以一起出现，不必遵守现实中的尺度、位置和因果。

怪核#

怪核也爱用阈限空间、早期互联网画面和超现实拼贴。它最在意的不是“像不像梦”，而是让图像里的信息怎么都拼不成一个完整解释。

美学 Wiki 把它归为超现实主义美学。业余摄影、低质量图像和刻意粗糙的后期很常见，它们会带来混乱、陌生、怀旧甚至恐惧感。⁷

林中的发光人影#

树木、落叶和林间空地都很真实，中央两个人形却被白光抹去了面孔、衣着和身份。熟悉的森林因此失去尺度与解释：他们究竟是被照亮的人，还是只有轮廓的不明物体？

---

池核#

池核围绕水池、瓷砖和波光展开。有些画面干净、安静，像是可以休息的地方；另一些则空无一人，结构不断重复，建筑关系也根本不可能成立。⁸

蓝色、白色和蓝绿色最常见，整齐的瓷砖、清澈水面与公共泳池设施也几乎成了固定班底。⁸

没有出口的室内泳池#

这里没有怪物，也没有明显的破败痕迹，只有蓝色瓷砖、水面、天窗和一座空泳池。可右侧采光口被墙和水面隔开，远处两个门洞也不知通向哪里。它看起来能用，细想又处处不合理。

Jared Pike 的《Dream Pools》#

Jared Pike 从 2020 年开始制作《Dream Pools》。他称这个系列是在探索“诡异的怀旧”：无尽的泳池把梦境和清醒状态混在了一起。作品使用 Blender 3D 和 LuxCore 制作。⁹

这些泳池干净明亮，看上去随时可以下水，却没有人、出口和明确尺度。水、瓷砖、光照都足够真实，唯独泳池没有尽头，建筑关系也对不上现实。

《POOLS》游戏案例#

《POOLS》没有怪物追逐，也没有用户界面、对白、背景音乐或传统故事。玩家面对的只有黑暗区域、狭窄通道，以及一间接一间找不到明确出口的水池。¹⁰

每个房间的声音与回声都不一样，涉水还会拖慢脚步。这里的玩法就是听声、看路，并在相似的建筑里勉强维持方向感。

官网列出的灵感来源包括阈限空间、Backrooms 和 Poolrooms，也明确提到 Jared Pike 对 Poolrooms 概念的影响。¹⁰

三种核类美学如何重叠#

这次实践也说明，只给一幅图贴上“池核”或“怪核”的标签，往往会漏掉它真正起作用的部分。题材、场所状态和画面处理可以分别来自不同风格。

池核 × 怪核#

画面主体是池子和水域，所以首先是池核。这里空无一人，用途不明，带着阈限感；低清画质、黑暗区域和无法确认的背景，又让它靠近怪核。¹¹

更准确地说，池核说的是题材，阈限空间说的是场所状态，怪核说的是画面怎样变得异常。

把风格拆成参数#

Dreamcore Style Transfer 是一个使用 Python Pillow 的开源项目。它把十种核类风格拆成参数配方，再依次调整色彩、曝光、颗粒噪点、柔光 Bloom 和扭曲。¹²

截图里的原图是一座水池，界面选择了“怪核”预设。处理后，画面多了强对比、故障线和彩色噪点。

但滤镜只能改变图像的质感。梦核常见过曝、褪色和胶片颗粒，怪核偏爱色散与故障，池核则常用水下蓝和青色高光。¹²

如果原图里没有无人空间、异常比例、符号错位或信息断裂，套完滤镜往往只是复古、低清或者偏色。决定风格的，仍是场景本身和元素如何组合。

---

核类美学为什么吸引人#

这类图像先让人认出场所。建筑、家具和公共设施都很熟悉，大脑很快就会猜出这里“应该”发生什么。接着，画面用无人、黑暗、循环或异常比例打破这个预测，却又故意省略人物、事件和空间边界。我们只好自己补全缺失的信息。

吸引力就来自这段没有完成的判断：眼前的地方明明认识，却始终解释不通。梦核、怪核和池核改动的是场所状态、空间关系或图像信息，滤镜反而只是表面的一层。

场景目标

制作一条被洪水灌满的废弃地铁人行通道。两侧铺墨绿色小方块马赛克瓷砖，左侧露出金属楼梯扶手。天花板排列长条 LED 荧光灯，冷白光向下照射，暗色积水覆盖整条通道。水面缓慢荡漾，把灯光反射切成破碎的亮斑。

通道要像是一直延伸到远处，尽头被青绿色薄雾遮住。画面中没有人，也看不出明确出口，整体氛围死寂而幽闭。

美学拆解

• 积水、瓷砖和灯光倒影提供池核的题材特征。
• 失去通行功能的地下通道构成阈限空间。
• 被雾吞没的尽头切断空间信息，使画面靠近怪核。

材质与建模要求

• 可以从 Poly Haven 下载所需材质，优先使用 4K 版本。
• 下载的材质存入“材质（按照自己需求创建）”文件夹，也可以使用现有的材质资产和 HDR 资产。
• 门、窗和其他建筑开口使用布尔方式制作。
• 建模前先审核场景，确认空间结构没有明显问题。

灯光与渲染要求

• 使用 Cycles 渲染，整体效果以写实为目标。
• 先确定主光方向，再调整水面反射、环境亮度和整体氛围。
• 外景光照使用环境 HDR。
• 薄雾中需要出现带有丁达尔效应的体积光。
• 氛围和参考描述应尽量一致，不能只完成建筑模型而忽略光线与空气感。

工具

• Blender 下载
• Blender Production Skills

成品

观看积水地下通道成品视频

这个场景在美学文章中的分析见 本文的 Blender 实践章节。

Footnotes#

1. 图片原链接：Reddit 图片，出处为 r/weirdcore 的 “supermarket weirdcore” 帖子。 ↩

2. 美学 Wiki，〈Liminal Space（阈限空间）〉，访问于 2026-09-06。社区协作资料，用于说明美学分类与常见视觉特征，不等同于同行评审研究。 ↩ ↩²

3. 美学 Wiki，〈核类美学〉，访问于 2026-09-06。该分类页用于说明 -core/“核”的分类含义。 ↩

4. 美学 Wiki，〈梦核（Dreamcore）〉，访问于 2026-09-06。社区协作资料，用于说明梦核的常见定义、传播媒介与视觉元素。 ↩ ↩² ↩³

5. 梦核图片原链接。 ↩

6. Montraluz LLC，〈Dreamcore Official Website〉，访问于 2026-09-06。用于核对游戏定位、地图设计与探索方式。 ↩ ↩²

7. 美学 Wiki，〈怪核（Weirdcore）〉，访问于 2026-09-06。社区协作资料，用于说明怪核的视觉语言与情绪取向，不作为临床心理学资料。 ↩ ↩²

8. 美学 Wiki，〈池核（Poolcore）〉，访问于 2026-09-06。社区协作资料，用于说明池核的题材、视觉元素与情绪特征。 ↩ ↩²

9. Jared Pike，〈Dream Pools〉，访问于 2026-09-06。艺术家本人对系列的说明，用于核对创作时间、主题与工具。 ↩

10. Tensori，〈POOLS〉，访问于 2026-09-06。游戏官网，用于核对交互设计、声音机制、情绪目标与创作灵感。 ↩ ↩²

11. 图片原链接：Backrooms Wiki 图片，作者原帖为 Instagram @onion.wave，出处核对：Backrooms Wiki — Level 188.8。 ↩

12. George-Ye2012，〈Dreamcore Style Transfer〉，GitHub，访问于 2026-09-06。开源实践项目，用于说明核类风格的参数化处理方法，不是美学分类或心理学研究的权威来源。 ↩ ↩²

传统教学的问题：同一条路径无法服务所有人#

常见的教学模式是“多对多”：一个老师用同一套课程，面向多个学习者授课；或者多个资料来源共同影响一个学习者。这样的模式便于规模化，却很难做到精准。

对某个学生来说，课程中可能有一部分内容早已掌握，另一部分内容又超出了当前的理解能力。最有效的教学，不应该反复讲已经会的知识，也不应该强行讲解暂时还无法吸收的内容，而是应该持续工作在学习者的“理解边缘”。

所谓理解边缘，就是学习者已经具备了必要的基础，只差一个恰当的解释、一个例子，或者一个小的推导，就能继续向前理解的地方。

这也是一对一教学的优势：老师可以根据学生的即时反馈调整深度、顺序和表达方式。AI 如果能够准确掌握学习者的状态，就有机会把这种优势扩展到更多场景中。

第一步：Probe，探查我究竟理解了什么#

个性化教学的前提，是系统必须知道学习者当前的理解状态。只说“我想学人工智能”或“我看过这本书”，远远不够。AI 需要建立一张更细致的学习者理解地图。

一种可行的方法是使用分级多选测验。系统先提出比较宽泛的问题，了解学习者对主题的整体把握；然后沿着课程依赖的知识线继续追问，用类似二分搜索的方式逐步逼近理解边缘。

例如，学习者声称自己理解了“梯度下降”，系统不能只停留在术语层面。它还需要确认学习者是否理解函数、导数、斜率、损失函数，以及这些概念之间的依赖关系。

这种探查不是为了考试，而是为了避免教学建立在错误的假设上。只有知道哪些内容已经掌握、哪些内容似懂非懂、哪些内容完全陌生，后续的教学计划才有意义。

第二步：Plan，规划适合当前状态的路径#

完成探查后，AI 才能决定从哪里开始、讲到什么程度，以及哪些内容应该暂时跳过。这个过程可以称为优化教学（Optimized Teaching）。

优化教学的目标不是把所有知识都讲一遍，而是把有限的注意力用在最有价值的地方：减少重复，避开当前无法理解的内容，集中突破学习者刚好能够吸收的部分。

因此，同一个问题不应该只有一份固定答案。同一个概念，也不应该对所有人使用完全相同的解释。对于初学者，AI 需要先补充直觉和例子；对于已经掌握基础的人，则可以直接进入形式化定义、推导和应用。

更重要的是，学习路径应该随着理解变化而变化。学习者一旦掌握了某个前置概念，原本困难的内容可能就变得容易；如果某个基础环节没有真正理解，系统也应该及时回退，而不是机械地继续推进。

第三步：Teach，围绕理解边缘进行教学#

在教学阶段，AI 不只是输出一段解释，而是要不断判断“下一步讲什么最合适”。这要求它把讲解、提问、举例和练习结合起来。

一个好的教学循环可能是：先用简洁的语言解释概念，再让学习者用自己的话复述；接着给出一个略有变化的例子，检查理解能否迁移；最后根据回答决定继续深入、换一种说法，还是回到前置知识。

这个循环的核心不是让学习者获得更多文字，而是让系统获得更多反馈。每一次回答都在帮助 AI 更新对学习者状态的判断。

所以，持续反馈并不是教学结束后的附加测试，而是教学本身的一部分。没有反馈，个性化只是一种表面上的称呼；有了反馈，教学路径才真正具备适应性。

好的学习路径，也需要设计情绪曲线#

学习不只是信息输入和答案判断，也是一段持续变化的情绪体验。刚接触新主题时，好奇心可以帮助学习者投入；遇到暂时无法解决的问题时，适度的挫败感能够提示自己需要补足某个环节；解决问题后的满足感，则会强化继续学习的动力。

因此，AI 教师不应该只追求题目越来越难，也不能让学习者一直停留在舒适区。失败太多会让人沮丧，挑战太少又会让人感到无聊。更合理的路径，是根据学习者的状态调整挑战强度，在“我还不会”和“我能够学会”之间保持张力。

这意味着系统需要关注的不只是答对率，还包括学习者是否连续受挫、是否长时间没有获得进展感，以及是否已经因为任务过于简单而失去兴趣。一次适时的提示、一个更容易进入的例子，或者一道能够快速建立信心的练习，都可能让学习重新启动。

学习不止一种目标#

学习也不是单一的“理解知识”。它至少包含几个相互连接的方面。

• 发现：意识到一个问题、概念或知识领域的存在，知道自己接下来可以探索什么。
• 理解：建立心智模型，能够解释概念为什么成立，以及它和其他知识如何连接。
• 练习：通过重复和反馈形成掌握，提升准确率、熟练度和解决问题的速度。
• 应用：把知识放进真实情境，在具体任务中形成判断、视角和经验。

这几个方面不能完全互相替代。读懂一个概念，不代表能够快速使用它；做对几道练习，也不代表能够在陌生场景中迁移；知道一个领域存在，更不等于已经形成了可操作的理解。

所以，AI 在规划学习路径时，应该先判断学习者当前缺少的是哪一层能力。如果目标是建立整体认识，就应该安排探索和概念连接；如果目标是提高熟练度，就需要更多有梯度的重复练习；如果目标是解决实际问题，就应该提供案例、项目和开放性任务。

只有把这些目标组合起来，学习才不会停留在“看过”和“答对”的层面，而会逐渐转化为真正能够调用的能力。

测验之外：让反馈变成不同类型的练习#

测验适合用来探查理解状态，但它不应该成为 AI 教师唯一的输出形式。不同的学习目标，需要不同的学习材料和反馈方式。

对于需要记忆的事实、术语和关键定义，可以使用闪卡。闪卡的价值不在于把内容压缩成问答，而在于通过间隔重复，让学习者在即将遗忘时再次主动回忆。

对于需要形成熟练度的技能，可以设计重复练习。题目应该有清晰的梯度，并逐步提高速度要求，让学习者不仅知道怎么做，也能够更加准确、稳定地完成。

对于需要理解和表达的内容，则可以要求学习者解释概念、比较两个观点、指出例子的边界，或者用自己的话重建一段推理。这样的练习比单纯选择正确答案更能暴露心智模型中的缺口。

实际应用还需要另一类任务：案例分析、模拟决策、小型项目，以及带有不完整信息的问题。它们能够检验学习者是否可以把知识迁移到新情境中，并积累课本无法直接提供的经验。

因此，一个完整的 AI 学习系统，应该能够在讲解、闪卡、测验、重复练习、解释任务和真实应用之间切换。它输出的不是一串内容，而是一组围绕学习目标组织起来的活动。

学习中的隐性成本：信任也会消耗认知资源#

学习者通常会把注意力放在知识内容上，却容易忽略另一个重要成本：信任成本。

当我们同时使用多个老师、多个课程和多个资料库时，需要不断判断它们是否可靠、观点是否冲突、术语是否一致、哪种说法更值得采用。这些判断本身会消耗认知资源，并且可能打断对知识的深入理解。

从心理资源优化分配（Optimized Allocation of Mental Resources）的角度看，学习者应该尽量把精力放在材料本身，而不是放在资料管理和来源比较上。

这并不意味着学习者只能接受单一观点。更合理的方式是：由一个值得信任的教学界面，承担资料筛选、观点整合和冲突解释的工作，然后以适合个人理解水平的方式传递给学习者。

一个老师，不等于一个来源#

“只使用一个老师，会不会失去多视角？”这是一个自然的担忧。

但单一的教学界面，并不意味着背后只有一个知识来源。AI 可以先收集教材、论文、课程和其他可靠资料，再比较它们的观点，识别分歧，最后把多种视角组织成一条适合当前学习者的解释路径。

可以把它想象成这样：老师阅读了多个来源，理解它们各自的侧重点，然后面对面地为你讲解。你不需要直接面对一堆互相独立的资料，而是先获得一份经过整理、能够继续追问的知识地图。

当然，这种模式仍然需要工程化的信任机制。AI 应该尽可能说明知识来源，在存在争议时明确指出不确定性，在无法确认时承认不知道，而不是用流畅的表达掩盖错误。

结语：AI 教师的关键是适配，而不是生成#

AI 辅助学习最有价值的地方，不在于它能一次生成多少内容，而在于它能否围绕一个具体的人持续调整教学。

一个可信的 AI 教师系统，至少需要完成三个动作：先探查学习者当前理解到哪里，再规划一条合适的学习路径，最后通过教学、练习和多种反馈不断更新判断。这就是 Probe-Plan-Teach 的基本循环。

在这个循环之外，它还需要设计合适的情绪节奏，兼顾发现、理解、练习和应用，并根据不同目标提供闪卡、重复练习、解释任务和真实案例。AI 可以聚合多种知识来源，但最好通过一个稳定、透明、可追问的界面把这些活动组织起来。

最终，理想的学习体验不是“AI 替我学习”，而是“AI 让我始终在最适合自己的理解边缘学习”。当系统真正理解我已经会什么、还缺什么，以及下一步最值得理解什么时，学习才可能从资料堆积，转变为一场持续推进的对话。

我当时想要什么#

我想要的布局很简单：左边敲代码，右边跑 opencode，用 tmux 把两个终端分开。

我还希望 opencode 能尽量自己完成任务，不要每一步都等我确认。为了少确认几次，我做了个 opencodeskip，让它直接调用 opencode --auto。

tmux 是真学了，但也真被 Ctrl+C 坑了#

为了这套用法，我顺手学了 tmux 最基本的操作。最常用的是：

1
Ctrl+b，然后按 %

这个快捷键能把窗口一分为二，左边放代码，右边跑 opencode。刚开始用时，我觉得这个安排挺合理。

坑也从这里开始。我以前在 Windows 上习惯用 Ctrl+C 复制文字，到了 Linux 里还是会下意识按它。结果文字没复制到，服务先被我中断了。明明只是想拿一段输出，最后还得重新处理进程。

opencodeskip 这件事#

我在 Windows 本机上本来就有一个脚本：

1
@echo off
2
opencode --auto %*

所以我在 Linux 上也照着做了一个等价版本：

1
#!/usr/bin/env bash
2
exec opencode --auto "$@"

我把它放到 ~/.local/bin/opencodeskip，加上执行权限，想着以后可以像在本地一样直接调用。它只做一件事：把参数转给 opencode --auto，省掉一些确认。

真正让我崩溃的是服务器太小#

我用的是阿里云送的 2核2G 服务器，内存实在太紧。刚开始我以为跑一个 opencode 应该没问题，实际很快就发现不是这么回事。

只要我开两个 opencode，服务器就开始卡，甚至直接死掉，最后只能重启。

我原本想做的是远程协作，结果变成了远程把服务器折腾死。

退出 opencode 之后，麻烦也没有马上结束：

1. Ctrl+C 后子进程残留
2. 网络一卡，TUI 直接卡死
3. 服务器资源占用下不来
4. 环境版本冲突
5. 会话丢失

我重新运行 opencode 时，服务器还可能再次卡死。用着用着就得先救火，原本的工作反而没推进多少。

zshrc 这次也把我坑得不轻#

我还试着让 opencode 帮我装几个 zsh 插件，想把远程 shell 调整得顺手一点。结果它写配置时，直接覆盖了原来的 ~/.zshrc。不是追加，是整份覆盖！！！

终端样式、别名和原来的配置全没了。

更烦的是，之前弄好的 opencodeskip 也不见了。服务器一出错，修复就变得很麻烦：配置没了，命令没了，插件没了，环境还不稳定。每一项单独看都不算大事，叠在一起就够折腾了。

到这时我才意识到，问题不在于要不要放权给 opencode，而在于这台服务器根本扛不住这种用法。

后来我换了个做法#

我最后还是改成本地运行 opencode，通过 SSH 操作服务器。对这台 2核2G 的机器来说，这样省事得多，也不容易因为进程残留、TUI 卡顿或配置覆盖反复救火。

相关命令#

下面是我当时用到的几组基础命令。第一组先更新软件源，安装 curl、git 和证书包，再安装 opencode。重新加载 shell 后，用版本号确认安装是否成功。

1
sudo apt update
2
sudo apt install -y curl git ca-certificates
3
curl -fsSL https://opencode.ai/install | bash
4
exec $SHELL
5
opencode --version

如果终端找不到刚安装的命令，就把 ~/.local/bin 加进 PATH，然后重新加载 ~/.zshrc。

1
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
2
source ~/.zshrc

最后这组命令用来删除 zsh 的补全缓存，再重新加载配置。修改过插件或补全设置后，通常需要这一步。

1
rm -f ~/.zcompdump*
2
source ~/.zshrc

我现在的想法很简单：服务器性能不够，就别硬把它当成本地主机。需要远程操作时用 SSH，能保守一点就保守一点。最后负责修系统的，还是自己。

从最简单的网页开始#

一个普通网页通常由三部分组成：HTML、CSS 和 JavaScript。

HTML 负责页面结构，CSS 负责页面样式，JavaScript 负责交互逻辑。

一个很小的页面，可以把它们都写在同一个 HTML 文件里；但项目稍微变大，这个文件就会越来越难维护。

所以更常见的做法，是把它们拆成不同文件：

1
<link rel="stylesheet" href="style.css" />
2
<script src="main.js"></script>

这样做之后，结构、样式和逻辑被分开了，代码确实更清晰。但新的问题很快出现：当 JavaScript 文件越来越多时，脚本的加载顺序会变得非常重要。

比如 a.js 里定义了一个变量，b.js 里要使用它，那么 a.js 就必须写在 b.js 前面。顺序一旦错了，页面运行时就可能报错：变量不存在、函数未定义。

如果项目里只有两三个脚本，这个问题还可以靠人脑记住。可如果项目里有几十个甚至上百个 JS 文件，手动维护它们的引用顺序就会非常痛苦。

模块化：让文件之间的关系写清楚#

为了解决这个问题，现代前端引入了一个非常重要的基础能力：模块化。

模块化的核心思想是：每个文件只暴露自己想让外部使用的内容，其他文件需要什么，就显式地导入什么。

例如：

1
export function add(a, b) {
2
  return a + b
3
}

1
import { add } from './utils.js'
2

3
console.log(add(1, 2))

这样一来，文件之间的依赖关系就不再依靠 HTML 里的 <script> 顺序来维持，而是直接写在 JavaScript 代码里。

这就是 ES Modules，也就是我们常说的 ESM。export 负责导出，import 负责导入。

模块化带来的第一个变化：不能再直接双击打开 HTML#

使用普通 <script> 标签时，很多简单页面可以直接双击 HTML 文件运行，也就是通过 file:// 协议打开。

但如果你使用了 ESM：

1
<script type="module" src="main.js"></script>

情况就不一样了。

浏览器在加载模块时，会按照更严格的规则处理文件请求。通过 file:// 打开页面时，模块之间的导入很容易因为同源策略或 CORS 限制而加载失败。

所以，使用模块化之后，我们通常不能再依赖“直接双击 HTML 文件”来开发页面，而是需要通过一个本地 HTTP 服务来访问页面。

也就是说，页面应该通过类似这样的地址打开：

1
http://localhost:5173

而不是：

1
file:///C:/project/index.html

项目变大后，还会遇到哪些问题？#

到这里，我们其实已经从“写几个静态文件”进入了“现代前端项目”的世界。

这个阶段通常会遇到三个典型问题。

1
main.8d3f4a1c.js
2
style.6a91b2ef.css

Vite：现代前端开发的基础工具#

为了解决上面这些问题，我们会引入构建工具。现在非常常用的一个构建工具，就是 Vite。

需要注意的是，Vite 不是 React、Vue 这种 UI 框架。它不负责规定页面怎么写，而是负责开发服务器、模块处理和生产构建。

Vite 主要做两类事情：开发阶段提升效率，生产阶段优化资源。

为什么使用 Vite 前要安装 Node.js？#

Vite 本质上是一个运行在 Node.js 环境里的前端工具。

JavaScript 原本主要运行在浏览器里，用来操作页面。但如果我们想在浏览器之外运行 JavaScript，比如执行构建工具、启动开发服务器、安装第三方库，就需要 Node.js。

你可以把 Node.js 理解成“让 JavaScript 在电脑本地运行的环境”。

安装 Node.js 后，可以在终端里检查版本：

1
node -v
2
npm -v

如果能看到版本号，就说明安装成功了。

这里的 npm 是 Node.js 自带的包管理工具。它的作用类似于 Python 里的 pip，用来安装和管理 JavaScript 生态里的第三方库。

如何在项目里安装 Vite？#

进入项目文件夹后，先初始化项目：

1
npm init -y

执行后，项目里会出现一个 package.json 文件。它用来记录项目名称、版本、脚本命令、依赖库等信息。

然后安装 Vite：

1
npm install -D vite

这里的 -D 表示把 Vite 安装为开发依赖，也就是写入 devDependencies。

所谓“开发依赖”，不是说它只能安装在你自己的电脑上，而是说它只在开发和构建阶段需要。

如果选择在服务器上执行 npm run build，服务器在构建阶段也需要安装 Vite，所以这时要安装 devDependencies。默认执行 npm install 会安装它们。

但网站真正运行起来以后，浏览器访问的是 dist 里的静态文件，Nginx 只负责把这些文件返回给浏览器，并不需要继续运行 Vite。

安装完成后，项目里通常会多出两个东西：

1
node_modules/
2
package-lock.json

node_modules 是第三方库实际存放的位置。Vite 以及 Vite 依赖的其他库，都会安装在这里。

package-lock.json 用来锁定依赖版本，保证其他人安装项目依赖时，尽量得到一致的结果。

补充一下，如果是从零创建一个新项目，也可以直接使用 Vite 官方脚手架：

1
npm create vite@latest

它会帮你生成基础项目结构。本文使用 npm init 和 npm install -D vite，是为了更清楚地说明 Vite 是如何作为项目依赖被安装进来的。

Vite 命令从哪里来？#

安装 Vite 后，node_modules/.bin 目录里会出现可执行命令。

在 Windows 下，你可能会看到类似这样的文件：

1
node_modules\.bin\vite.cmd

它就是本地项目里的 Vite 命令。

不过实际开发中，我们通常不会手动去执行这个路径，而是把命令写进 package.json 的 scripts 里。

例如：

1
{
2
  "scripts": {
3
    "dev": "vite",
4
    "build": "vite build",
5
    "preview": "vite preview"
6
  }
7
}

之后就可以这样使用：

1
npm run dev
2
npm run build
3
npm run preview

npm run dev 用来启动本地开发服务器。启动成功后，终端会显示本地访问地址，例如 http://localhost:5173/。

npm run build 用来生成生产环境文件。

npm run preview 用来在本地启动一个服务器，检查构建后的生产版本是否正常；它不是正式的生产服务器。

补充：构建后的 dist 如何部署到服务器？#

一种常见做法是：服务器拉取源码后，在服务器上安装依赖并执行构建，而不是把 dist 提交到 Git 仓库。

具体来说，Git 仓库里只保存项目源码和配置文件，dist 和 node_modules 都放进 .gitignore。

node_modules 不提交，是因为它体积很大，而且可以根据 package.json 和 package-lock.json 重新安装。

dist 不提交，是因为它是构建产物，可以随时通过源码重新生成。

所以一次典型的服务器部署流程是：

1
git pull
2
npm install
3
npm run build

注意：如果服务器负责执行 npm run build，就不能在构建前只安装 production 依赖。因为 Vite 在 devDependencies 中，构建阶段仍然需要它。

执行完 npm run build 后，服务器上会生成新的 dist 目录。

然后在 Nginx 中把网站根目录指向这个 dist 文件夹，并把入口文件设置为 index.html。

例如：

1
server {
2
  listen 80;
3
  server_name example.com;
4

5
  root /var/www/my-project/dist;
6
  index index.html;
7
}

这样浏览器访问网站时，Nginx 返回的就是 Vite 构建后的生产文件。

如果后续项目使用前端路由，例如 React Router，还需要让 Nginx 在找不到具体文件时回退到 index.html。

总结#

现代前端开发并不是一开始就复杂的。它是项目规模变大后，为了解决实际问题一步步演化出来的。

最开始，我们只需要 HTML、CSS 和 JavaScript。

后来，文件越来越多，手动维护脚本顺序变得困难，于是有了模块化。

模块化让依赖关系更清楚，但也要求我们通过 HTTP 服务来开发页面，于是需要本地开发服务器。

项目上线时，还需要打包、压缩、文件指纹和缓存处理，于是构建工具就变得非常重要。

Vite 解决的正是这些问题：开发时提供快速的本地服务器和热更新，上线前生成优化后的生产资源。

所以，理解 Vite 的关键不是记命令，而是理解它为什么出现：它是在帮我们把“适合开发的代码”，转换成“适合上线的资源”。

学完 Vite 之后，下一步学什么#

学到这里，我们已经解决了一部分“工程化”的问题。

Vite 帮我们解决的是开发和构建：本地服务器、模块化、热更新、打包、压缩、文件指纹。

也就是说，Vite 主要回答的是：

1
项目怎么开发？
2
代码怎么组织成模块？
3
上线前怎么构建成生产资源？

但 Vite 并不会直接解决“页面本身如何组织”的问题。

当页面越来越复杂时，我们会遇到新的麻烦：按钮、表单、列表、弹窗、用户状态、加载状态都混在一起。如果继续手动操作 DOM，代码会很快变得难以维护。

这时就需要 React。

React 是一个用于构建用户界面（UI）的 JavaScript 库，也常被称为前端框架；它的核心思想是用组件来组织页面。

React 关注的是另一个层面：如何把页面拆成组件，如何让数据传入组件，如何让状态变化后页面自动更新。

所以，Vite 和 React 解决的是两个不同问题：

1
Vite：解决项目开发、构建、部署的问题
2
React：解决页面组织、数据驱动、状态更新的问题

也正因为如此，学完 Vite 之后，继续学习 React 是很自然的一步。

这条现代前端学习路线可以继续往下走：

1
HTML/CSS/JS
2
→ Vite
3
→ React（或 Vue、Svelte 等）
4
→ Next.js 等应用框架

前言#

我一开始是从 FastAPI 的 @app.get() 产生疑问，然后顺着“它到底在修饰谁”“为什么这样写”“装饰器什么时候执行”“带参数装饰器又是什么”这条线，一步一步把 Python 装饰器弄懂。

这篇整理记录的是我的学习过程，先把思路走通，再回头看结论。

1. 最初疑问：FastAPI 路由装饰器#

其中的代码：

1
@app.get("/api/profile")
2
def get_profile():
3
    return profile

1
def get_profile():
2
    return profile
3

4
app.add_api_route(path="/api/profile", endpoint=get_profile, methods=["GET"])

2. 切入基础：自定义装饰器（计时器示例）#

示例代码：

1
import time
2

3
def timer(function):
4
    def wrapper():
5
        time_start = time.time()
6
        function()
7
        time_end = time.time()
8
        cost_time = time_end - time_start
9
        print("花费时间：{}秒".format(cost_time))
10
    return wrapper
11

12
@timer
13
def func1():
14
    print('我是一个函数1')

1
@timer
2
def func1():
3
    pass
4

5
# 等价于
6

7
def func1():
8
    pass
9

10
func1 = timer(func1)

1
def deco(func):
2
    def inner():
3
        print("包装启动")
4
        func()
5
    return inner()  # 当场执行 inner，返回 None
6

7
@deco
8
def demo():
9
    print("demo执行")
10

11
demo()  # 报错 TypeError: 'NoneType' object is not callable

3. 随堂测试复盘：易错的时序考点#

1
def deco(func):
2
    def inner():
3
        print("开始")
4
        func()
5
        print("结束")
6
    return inner
7

8
@deco
9
def hello():
10
    print("Hello")
11

12
hello()

1
开始
2
Hello
3
结束

1
def deco(func):
2
    print("进入deco")
3
    def inner():
4
        print("inner运行")
5
        func()
6
    return inner
7

8
@deco
9
def test():
10
    print("执行test本体")
11

12
print("====分割线====")
13
test()

1
进入deco
2
====分割线====
3
inner运行
4
执行test本体

4. 知识迁移到 FastAPI#

回到最开始的代码：

1
@app.get("/api/profile")
2
def get_profile():
3
    return profile

它可以展开成：

1
def get_profile():
2
    return profile
3

4
# 1. app.get 先执行，得到一个装饰器
5
decorator = app.get("/api/profile")
6

7
# 2. 使用装饰器包装原始函数
8
get_profile = decorator(get_profile)

2 安装#

先安装 Git 与 Node.js。

1
# 国内用户（winget 源）
2
winget install Anthropic.ClaudeCode
3

4
# 官方渠道（npm 全局安装）
5
npm install -g @anthropic-ai/claude-code

安装完成后，在终端输入 claude 即可启动。

3 cc switch 多模型配置切换#

下载：CC Switch

cc switch 用于在多个模型配置之间快速切换，并对齐模型所需格式。

4 配置 DeepSeek 兼容端点#

Claude Code 默认走 Anthropic 官方 API，但也可以通过自定义端点接入 DeepSeek 等兼容模型，降低成本。

5 接入本地模型（llama.cpp）#

llama.cpp 默认提供的是 OpenAI 兼容 API，而 Claude Code 走的是 Anthropic 协议。直接在 settings.json 里填 llama.cpp 的地址是不行的，需要配合 cc switch 的自定义端点功能来桥接。

1
ngrok http 8080

6 Skill、Plugin、Agent 扩展#

Claude Code 的真正威力在于可扩展生态。通过插件市场，你可以安装社区提供的 Skill、Plugin 和 Agent，极大扩展能力边界。

1
/plugin marketplace add anthropics/skills

7 小结#

折腾一圈下来，Claude Code CLI 就配置好了—— 一套工具，多种后端模型，按需切换。希望这篇笔记能帮你少走弯路。

2 Git 基础全局配置#

在使用 Git 前，需先配置全局用户名和邮箱，这是提交代码时的身份标识，仅需配置一次。

1
# 配置全局用户名（替换为你的 GitHub 用户名）
2
git config --global user.name "Celyn"
3

4
# 配置全局邮箱（替换为你的 GitHub 绑定邮箱）
5
git config --global user.email "1249140039@qq.com"

1
# 查看用户名
2
git config user.name
3

4
# 查看邮箱
5
git config user.email

1
# 将当前本地分支强制重命名为 main
2
git branch -M main
3

4
# 首次推送，并关联本地 main 与远程 origin/main
5
git push -u origin main

3 Git 代理配置（解决 GitHub 下载慢）#

若访问 GitHub 速度缓慢，可配置 7897 端口代理（本地常用代理端口），提升克隆、拉取代码的效率。

1
# 配置 HTTP 代理
2
git config --global http.proxy http://127.0.0.1:7897
3

4
# 配置 HTTPS 代理
5
git config --global https.proxy https://127.0.0.1:7897

1
# 查看 HTTP 代理
2
git config --global --get http.proxy
3

4
# 查看 HTTPS 代理
5
git config --global --get https.proxy

1
# 取消 HTTP 代理
2
git config --global --unset http.proxy
3

4
# 取消 HTTPS 代理
5
git config --global --unset https.proxy

4 Fork 仓库与本地初始化#

1
# 关联自己的 Fork 仓库（origin）
2
git remote add origin https://github.com/HP-Patience/MathModelAgent.git
3

4
# 关联上游原仓库（upstream，用于同步最新代码）
5
git remote add upstream https://github.com/jihe520/MathModelAgent.git

1
git pull origin main

1
# 克隆自己的 Fork 仓库到本地
2
git clone https://github.com/HP-Patience/MathModelAgent.git

5 分支开发与代码提交#

1
# 创建并切换到 myfeat 分支（分支名可自定义）
2
git checkout -b myfeat

1
# 添加所有修改文件
2
git add .
3

4
# 提交代码（添加清晰的提交信息）
5
git commit -m "feat: 完成XX功能开发"

6 同步上游更新与推送代码#

1
# 将 myfeat 分支推送到自己的 GitHub 仓库
2
git push origin myfeat

1
git checkout main
2
git pull upstream main

1
git checkout myfeat
2
git rebase main

1
git push -f origin myfeat

7 PR 被合并后：同步代码 + 清理分支#

当你的 PR 被上游仓库合并完成后，执行以下命令同步代码并清理无用分支：

1
# 1. 切换到本地 main 分支
2
git checkout main
3

4
# 2. 拉取上游最新代码（包含你刚合并的功能）
5
git pull upstream main
6

7
# 3. 删除本地已完成的开发分支（强制删除）
8
git branch -D myfeat
9

10
# 4.（可选）同步到你自己的远程 main 分支
11
git push origin main

8 总结#

本文介绍了从配置 → 克隆 → 开发 → 提交 → 同步 → 提PR → 清理的完整闭环 Git 协作流程，所有命令都是团队开源协作最标准的用法，可以直接使用。

2 WSL 下载配置#

1
wsl --update

1
mkdir F:\wsl\Ubuntu2204

1
wsl --import Ubuntu-22.04 F:\wsl\Ubuntu2204 F:\wsl\jammy-server-cloudimg-amd64-root.tar.xz --version 2

1
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
2
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
3
dism.exe /online /enable-feature /featurename:Hyper-V-Online /all /norestart

1
wsl --import Ubuntu-22.04 F:\wsl\Ubuntu2204 F:\wsl\jammy-server-cloudimg-amd64-root.tar.xz --version 2

3 Docker下载与配置#

1
{
2
  "builder": {
3
    "gc": {
4
      "defaultKeepStorage": "20GB",
5
      "enabled": true
6
    }
7
  },
8
  "experimental": false,
9
  "features": {
10
    "buildkit": true
11
  },
12
  "registry-mirrors": [
13
    "https://docker.1ms.run",
14
    "https://docker.xuanyuan.me",
15
    "https://registry-1.docker.io"
16
  ]
17
}

4 n8n 部署与使用#

1
docker volume create n8n_data

1
docker run -d ` --name n8n ` -p 5678:5678 ` -e GENERIC_TIMEZONE="Asia/Shanghai" ` -e TZ="Asia/Shanghai" ` -v n8n_data:/home/node/.n8n ` n8nio/n8n

5 参考文档：#

1. Docker | n8n Docs
2. GitHub | n8n-io/n8n

2 梯度下降收敛停滞的关键原因#

梯度下降过程中，当梯度∇L (θ)=0 时，损失函数值不再变化，优化陷入停滞。造成这一现象的原因并非仅为局部最小值点，还可能是鞍点，两者核心区别如下：

• 局部最小值点（local minimum point）：梯度为 0，且任意方向移动损失均增大，优化达到局部最优；
• 鞍点（saddle point）：梯度为 0，存在一对正交方向，沿其中一个方向移动损失增大，沿另一个方向移动损失减小，并非最优解，却会导致梯度下降停滞。

综上，局部最小值点与鞍点的梯度均为 0，这两类梯度为 0 的点统称为驻点。

那么当我们遇到梯度为 0 的驻点时，如何判断其是局部最小值点还是导致优化停滞的鞍点呢？此时需要引入 Hessian 矩阵进行判别：

3 Hessian 矩阵与二次型#

要判断一个临界点到底是什么，我们需要用到二阶泰勒展开，在临界点 θ′\theta'θ′ 附近近似损失函数：

这里的 HHH 就是Hessian 矩阵，是由损失函数 L (θ) 各参数的二阶偏导数构成的对称方阵，用于刻画损失函数曲率，辅助判断驻点类型。

我们设 v=θ−θ′v = \theta - \theta'v=θ−θ′（移动方向），那么损失的变化就完全由二次项决定：

而根据特征向量的定义，对于 Hessian 的特征向量 uuu 和对应的特征值 λ\lambdaλ，我们有：

因为 ∥u∥2>0\|u\|^2 > 0∥u∥2>0，所以 uTHuu^T H uuTHu 的符号完全由特征值 λ\lambdaλ 决定：

• λ>0\lambda > 0λ>0：沿 uuu 方向走，损失会变大（上坡）。
• λ<0\lambda < 0λ<0：沿 uuu 方向走，损失会变小（下坡）。

这就是为什么我们可以用 Hessian 的特征值来判断临界点的类型。

4 收敛点的真实本质#

我们可以做一个简单的实验：重复训练同一个网络很多次，每次训练到收敛，然后计算每个临界点 Hessian 矩阵的正特征值比例（我们称之为 Minimum Ratio），并记录对应的训练损失。

我们能从实验结果中清晰地看到一个强规律：

1. 左侧点群（Minimum Ratio 很低）：损失都很高（0.08-0.09），这些是典型的低维鞍点，有大量负特征值，模型困在这里根本没学好。
2. 右侧点群（Minimum Ratio 很高）：损失都很低，这些点看起来像“局部极小值”，但它们的 Minimum Ratio 远小于 1，说明 Hessian 矩阵里仍然存在少量负特征值，本质上还是鞍点。

图中的文字 never reach a real "local minima" 直接点破了真相： 我们几乎永远无法到达数学上严格定义的局部极小值，只能停在这些高维鞍点上。

5 总结#

1. 高维空间中，鞍点数量远多于局部极小值，是模型收敛的主要位置，且鞍点可进一步优化，并非优化终点；
2. 驻点类型可通过 Hessian 矩阵特征值判断：所有特征值>0 为局部最小值点，正负特征值共存为鞍点；
3. 可沿 Hessian 负特征值对应的特征向量方向，逃离劣质鞍点，继续降低损失；
4. 优化的关键并非追求严格局部极小值，而是收敛到负特征值少、正特征值占比偏高的平缓优质临界点，这类点损失更低、泛化性能更好。

使用 IPPure 检查 WebRTC 泄露情况#

Reference：#

1. WebRTC解释

逐行代码分析#

好的，我们逐行分析这段代码，它的主要功能是将训练集和验证集的数据从原始数据集中复制到新的目录中，并将多边形的坐标标准化为相对坐标。

1
if os.path.exists('yolo_seg_dataset'):
2
    shutil.rmtree('yolo_seg_dataset')

1
os.makedirs('yolo_seg_dataset/train')
2
os.makedirs('yolo_seg_dataset/valid')

1
def normalize_polygon(polygon, img_width, img_height):
2
    return [(x / img_width, y / img_height) for x, y in polygon]

1
# 采样训练集
2
for row in training_anno.iloc[:10000].iterrows():

1
    shutil.copy(row[1].Path, 'yolo_seg_dataset/train')

1
    img = cv2.imread(row[1].Path)
2
    img_height, img_width = img.shape[:2]

1
    txt_filename = os.path.join('yolo_seg_dataset/train/' + row[1].Path.split('/')[-1][:-4] + '.txt')

1
    with open(txt_filename, 'w') as up:

1
        for polygon in row[1].Polygons:
2
            normalized_polygon = normalize_polygon(polygon, img_width, img_height)

1
            normalized_coords = ' '.join([f'{coord[0]:.3f} {coord[1]:.3f}' for coord in normalized_polygon])

1
            up.write(f'0 {normalized_coords}\n')

1
# 采用验证集
2
for row in training_anno.iloc[10000:10150].iterrows():
3
    shutil.copy(row[1].Path, 'yolo_seg_dataset/valid')
4

5
    img = cv2.imread(row[1].Path)
6
    img_height, img_width = img.shape[:2]
7
    txt_filename = os.path.join('yolo_seg_dataset/valid/' + row[1].Path.split('/')[-1][:-4] + '.txt')
8
    with open(txt_filename, 'w') as up:
9
        for polygon in row[1].Polygons:
10
            normalized_polygon = normalize_polygon(polygon, img_width, img_height)
11
            normalized_coords = ' '.join([f'{coord[0]:.3f} {coord[1]:.3f}' for coord in normalized_polygon])
12
            up.write(f'0 {normalized_coords}\n')

步骤二：写入YOLO配置文件#

1
with open('yolo_seg_dataset/data.yaml', 'w') as up:
2
    data_root = os.path.abspath('yolo_seg_dataset/')
3
    up.write(f'''
4
path: {data_root}
5
train: train
6
val: valid
7

8
names:
9
    0: alter
10
''')

逐行代码分析#

这一段代码的目的是创建一个名为 data.yaml 的配置文件，通常用于YOLO等深度学习模型的数据配置。我们来逐步分析这段代码的结构和含义。

1
with open('yolo_seg_dataset/data.yaml', 'w') as up:

1
data_root = os.path.abspath('yolo_seg_dataset/')

1
up.write(f'''
2
path: {data_root}
3
train: train
4
val: valid
5

6
names:
7
    0: alter
8
''')

1
path: /home/user/projects/yolo_seg_dataset
2
train: train
3
val: valid
4

5
names:
6
    0: alter

步骤三：训练YOLO分割模型#

1
from ultralytics import YOLO
2

3
model = YOLO("./yolov8n-seg.pt")
4
results = model.train(data="./yolo_seg_dataset/data.yaml", epochs=10, imgsz=640)

逐行代码分析#

以下是对代码的逐行分析：

1
from ultralytics import YOLO

• 这行代码导入了 ultralytics 库中的 YOLO 类。
• ultralytics 是一个用于目标检测的库，提供了易于使用的接口来训练和推理 YOLO 模型，尤其是 YOLOv8 模型。
• YOLO 类是用于创建并管理 YOLO 模型的类，包括加载预训练模型、训练模型和进行推理。

1
model = YOLO("./yolov8n-seg.pt")

• 这行代码使用 YOLO 类创建了一个 model 实例。
• YOLO("./yolov8n-seg.pt") 加载一个预训练的 YOLOv8 模型，该模型文件是 yolov8n-seg.pt。这是 YOLOv8 模型的小型版本（n 代表 nano纳米），同时具有分割功能（-seg 代表分割任务）。
• 通过这种加载方式，可以直接基于预训练模型进行进一步训练或推理。

1
results = model.train(data="./yolo_seg_dataset/data.yaml", epochs=10, imgsz=640)

• model.train() 是 YOLO 模型的训练方法。
• data="./yolo_seg_dataset/data.yaml" 指定了用于训练的数据集配置文件。data.yaml 文件通常包含训练集、验证集的路径，以及类别名称等信息。
• epochs=10 指定模型要进行 10 个==训练周期==（epochs）。每个周期意味着模型将遍历完整的训练数据集一次。
• imgsz=640 设置了输入图像的尺寸为 640 像素。YOLO 模型会将训练数据的图像调整到 640x640 的尺寸进行训练。

训练完成后，results 会包含训练过程中的结果和性能指标（如损失值、准确度等），这些结果可以用于评估模型的训练效果。

步骤四：预测测试集#

1
from ultralytics import YOLO
2
import glob
3
from tqdm import tqdm
4

5
model = YOLO("./runs/segment/train6/weights/best.pt")
6
test_imgs = glob.glob('./test_set_A_rename/*/*')