部署一个有趣的开源 AI 教学系统：从零到完全体

ai写的again，仅供记录，参考。

背景

最近需要快速建立 Web Dev 技术栈的系统性认知（React/TypeScript/Next.js），传统教材存在两个痛点：

线性叙事低效：无法感知学习者的知识边界，已懂的内容和盲区混在一起讲
跨资源认知负载：The Odin Project、React.dev、JavaScript.info 等优质资源分散，需要手动做术语翻译和概念去重

发现一个基于 pi（开源终端 AI agent）+ Anthropic teach 哲学的项目：amosblomqvist/learn。核心特性：

自适应探底：二分法定位知识边界，只讲不会的 20%
依赖图教学：从 Axiom 到目标构建 DAG，每个节点 motivate → establish → connect → quiz-check
多模态笔记：实时镜像到 Markdown（LaTeX/Mermaid 原生渲染），配合 Obsidian 使用

决定在 WSL 环境中部署完整工作流。

技术栈

运行环境：WSL2 (Ubuntu)
AI 框架：pi-coding-agent (Node.js)
子代理编排：pi-interactive-subagents (tmux-based)
模型服务：自部署 OpenAI-compatible 端点（GLM-5.3 系列 + GPT/Gemini）
笔记系统：Obsidian（Windows 侧）+ Markdown 实时同步

核心依赖安装

1. 基础环境

# Node 环境（已有 v24.15.0 via nvm）
# tmux 终端复用器
sudo apt update && sudo apt install -y tmux

# pi 主体（注意包名）
npm install -g @mariozechner/pi-coding-agent

2. 子代理扩展

cd ~/learn
git clone https://github.com/amosblomqvist/learn .pi

cd .pi/extensions
git clone https://github.com/amosblomqvist/pi-interactive-subagents
cd pi-interactive-subagents && npm install

3. 渲染工具链

# Mermaid 图表渲染需要无头浏览器
# puppeteer 自带 Chromium 但需手动触发下载
npx -y @puppeteer/browsers install chrome-headless-shell@stable

# SVG 渲染
sudo apt install -y librsvg2-bin

# 中文字体支持（避免方框乱码）
sudo apt install -y fonts-wqy-microhei fonts-noto-cjk
sudo fc-cache -fv

WSL ↔ Windows 文件互通

核心问题：Obsidian（Windows）需要原生 NTFS 路径才能稳定监视文件变化，\\wsl.localhost\ 网络路径会触发 EISDIR 错误。

解决方案：笔记库建在 Windows，WSL 通过软链接写入

# Windows 侧建库
mkdir C:\ai-assisted-learning-tool

# WSL 软链接笔记目录
ln -s /mnt/c/ai-assisted-learning-tool ~/learn/notes

# 图片目录同理
mkdir /mnt/c/ai-assisted-learning-tool/viz
ln -s /mnt/c/ai-assisted-learning-tool/viz ~/learn/viz

Obsidian 打开 C:\ai-assisted-learning-tool 作为 vault。WSL 里的 pi 写入 ~/learn/notes/*.md 和 ~/learn/viz/*.png，物理存储在 Windows 盘，两侧实时同步。

使用流程

启动与绑定

cd ~/learn
tmux new -A -s pi 'pi --model local/gpt-6-astra'

进入后：

/md-log notes/js-event-loop.md

注意：笔记文件需提前创建（touch notes/xxx.md），md-log 不会自动创建。

教学流程示例

输入：

教我 JavaScript 的事件循环

系统自动执行三阶段：

Phase 1: Probe（探底）
- 二分法定位知识边界（答对加难度，答错收窄范围）
- 用 quiz 工具出选择题，即时反馈 ✓/✗ + 解析
- 用 ask_user_question 确认学习目标
Phase 2: Plan（路线图）
- 派 researcher 子代理核实领域事实
- 生成 Mermaid 依赖图（Axiom → 推导 → 目标）
- 等待确认后进入教学
Phase 3: Teach（逐节点循环）
- 每个节点：motivate（动机）→ establish（建立）→ connect（挂到已知）→ quiz-check（确认落地）
- 遇到需要可视化的概念，派 mermaid-maker/svg-maker 生成图表

所有内容实时镜像到 notes/js-event-loop.md，Obsidian 原生渲染 LaTeX 公式和 Mermaid 图。

关键排障记录

1. 无头浏览器缺失系统库

现象：mmdc 渲染 Mermaid 报缺 .so 文件，无 sudo 权限

解决：

# 下载 deb 包并本地解压
mkdir -p ~/lib
ar x package.deb data.tar.xz
tar -xf data.tar.xz -C ~/lib --strip-components=3 ./usr/lib/x86_64-linux-gnu/

# 封装 mmdc 入口脚本
cat > ~/.pi/bin/mmdc << 'EOF'
#!/bin/bash
export LD_LIBRARY_PATH="$HOME/lib:$LD_LIBRARY_PATH"
exec /path/to/real/mmdc "$@"
EOF
chmod +x ~/.pi/bin/mmdc

2. tmux 嵌套警告

现象：在 tmux 内再执行 tmux new 报 sessions should be nested with care

解决：

tmux kill-server  # 清理所有会话后重新启动

3. 模型调用成本异常

现象：一节不到 1 万字的课花费 14 元（预期应为 1 元以下）

原因分析：

首次运行时系统自主排障（修无头浏览器环境），多次工具调用累积上下文
主会话和画图子代理均使用高价模型

优化：

将体力活型子代理（researcher/mermaid-maker/scout/worker）降级为 Flash 模型
仅保留主会话和 svg-maker 使用顶级模型

成果验收

教学质量：Probe 阶段精准定位盲区，教学路径清晰（微任务 vs 宏任务、调用栈与队列）
多模态支持：Mermaid 架构图正常渲染中文，LaTeX 公式原生显示
工作流闭环：WSL 运行环境 + Windows Obsidian 双向同步稳定

背景

技术栈