aedificium — 个人学习笔记本 + 词典，Claude 原生

卡片网格界面在 http://localhost:8788 上运行，用于笔记、定义（词典）和 PDF，并通过 MCP 将聊天面板桥接到 Claude Code。数学渲染是一流的（KaTeX）。磁盘上的所有内容都是纯 markdown，自动提交到 git，并（可选）自动推送到 GitHub。

这是一个开源模板。Fork 它，将你的 fork 克隆到相邻的 scriptorium/ 代码实验室旁，然后开始写作。

你能得到什么

• 卡片网格 + 阅读器 — 左侧是笔记，右侧是与 Claude 的聊天。

• 一流的数学公式 — $e^{i\pi}+1=0$ 行内，$$…$$ 展示，服务端 KaTeX。在卡片网格 和 阅读器中渲染。

• 词典 — 每个文件一个定义（lexicon/eigenvalue.md），渲染为带词头 + 同义词 + 领域标签的词典条目。

• PDF 库 — 将 PDF 放入 pdfs/；自动出现一个伴随讨论卡片。没有内嵌查看器——浏览器自带的更好。使用 #page=N 深链到页面。

• 聊天就是 Claude Code — 你在浏览器中键入，Claude 回答，你当前选中的卡片会作为上下文一并传递（refs=…）。

• Wiki 链接 — 任何笔记中的 [[slug]] 都会成为阅读器中点击即可打开的链接，并通过 History API 支持 /note/<slug> 深链。

• Git 原生 — 写入自动提交（防抖约 3 秒），如果设置了 origin 则自动推送。为 PDF 预配置了 LFS，这样 GitHub 可以干净地处理大型二进制文件。

先决条件

在 macOS (arm64) 上开发和测试。Linux 应可通过等价的包安装正常工作。

• bun — 服务器使用的 JavaScript 运行时。brew install oven-sh/bun/bun。

• git-lfs — 用于 PDF。brew install git-lfs。

• Claude Code — 聊天面板所对话的 CLI。这正是让笔记本 交互 的组件。

设置

# Fork on GitHub first, then:
git clone git@github.com:clausd/aedificium.git
cd aedificium
bun install
git lfs install

启动

有一个标志位很重要，而且容易被忽略。 Claude Code 需要 --dangerously-load-development-channels server:aedificium 才能让浏览器 → Claude 方向的通道工作。缺少它时，reply / commit_chat 工具仍然可以工作（Claude → 浏览器），但你在聊天面板中键入的任何内容都无法到达 Claude。沉默看起来像 bug，但不是。

claude --dangerously-load-development-channels server:aedificium

Claude Code 将自动启动 bun server.ts（根据 .mcp.json）。然后打开 http://localhost:8788。

可以考虑设置别名：

alias claude-aed='claude --dangerously-load-development-channels server:aedificium'

“不要 nohup bun”规则

不要自己使用 nohup / disown 启动 bun。如果这样做了，bun 会变成脱离 Claude Code 的 MCP stdio 管道的孤儿进程——浏览器仍然工作，但 Claude 会失去 reply 和 commit_chat，而且未来的 Claude Code 会话也无法绑定 8788 端口（因为孤儿进程占用着它）。

如果需要让 server.ts 的更改生效：

kill $(lsof -tiTCP:8788 -sTCP:LISTEN)   # or just kill the pid you see
# then exit + re-enter Claude Code; the harness respawns a fresh bun child.

布局

notes/                  YYYY-MM-DD-HHMM-slug.md — free-form notes
lexicon/                <slug>.md — one term per file, dictionary style
pdfs/                   PDFs + auto-generated sidecar .md discussion cards
assets/                 pasted / dropped images referenced from cards
files/                  misc non-PDF uploads
archive/                archived cards (preserves original subdir)
data/chat.jsonl         durable chat transcript (tracked + searchable)

server.ts               the Bun app (single file, ~2500 lines)
CLAUDE.md               the design doc + Claude Code project instructions
.mcp.json               MCP config (Claude Code reads this to spawn bun)
.gitattributes          LFS routing for *.pdf

约定速览

• 卡片类型是推断出来的，而非声明的：notes/ 中的文件是笔记，lexicon/ 中的文件是词典条目，PDF 会获得伴随卡片。

• 数学公式：行内 $x$（美元符号紧贴内容），展示 $$…$$。边缘情况见 CLAUDE.md。

• 正文中的机器标签：#area:calculus、#see:other-slug 或裸 #question。UI 会让它们不在正文中出现，而是渲染为标签（chips）。

• Wiki 链接：[[some-slug]]（可选 [[some-slug|display text]]）在服务端解析，并在阅读器中打开。

完整规范：CLAUDE.md。

可选——相邻代码实验室

如果你想要一个配套的 Python 仓库来存放模型、笔记本和图表，请使用 scriptorium-template 作为相邻检出：

your-workspace/
  aedificium/          # this repo
  scriptorium/         # from scriptorium-template

scriptorium 的 aedificium.py 桥接器可以让笔记本单元格内联渲染 aedificium 文本，并将 matplotlib 图表直接保存到 aedificium/assets/。如果两者不是相邻目录，请设置 AEDIFICIUM_DIR（在 scriptorium 中）或 AED_SCRIPTORIUM_DIR（在这里）。

GitHub 设置

本地安装好 LFS 后，像往常一样推送到 GitHub：

git remote set-url origin git@github.com:clausd/aedificium.git
git push -u origin main

每次自动提交（5 秒防抖）后都会执行自动推送。使用 AED_NO_PUSH=1 禁用。GitHub LFS 免费套餐为每个账户每月 1 GB 存储 / 1 GB 带宽——对于个人 PDF 库（最多几百篇论文）来说绰绰有余。

环境变量选项

故障排除

• “我在聊天面板中键入，但什么也没有发生。” 几乎总是缺少 --dangerously-load-development-channels server:aedificium 标志。使用该标志重启 Claude Code。

• “Claude 说 reply 工具不可用。” Bun 变成了孤儿进程。杀掉占用 8788 端口的进程，退出并重新进入 Claude Code。

• “git push 拒绝一个 PDF（exceeds 100 MB）。” 添加该 PDF 时 LFS 未生效。运行 git lfs install，然后 git lfs migrate import --include="*.pdf" --everything，再 git push --force-with-lease（只有你是唯一克隆时才安全）。

• “自动提交停止了。” 检查 bun 的 stderr。最常见的原因是机器间 data/chat.jsonl 上的合并冲突——冲突通常表现为两侧的并集（chat.jsonl 是只追加的）。

许可证

MIT。自由改编——重点在于你拥有自己的笔记本。

致谢

原始概念、架构和实现由 Claus Dahl 完成。双仓库拆分（文本 ↔ 代码）的灵感来自中世纪缮写室（scriptoria）滋养修道院图书馆的方式——名字由此而来。