Skip to main content
Glama
Sign In
deenesjakoruzh
aedificium-template

aedificium-template

by clausd
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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 可以干净地处理大型二进制文件。

Related MCP server: Zettelkasten MCP Server

先决条件

在 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 库（最多几百篇论文）来说绰绰有余。

环境变量选项

变量

默认值

作用

AED_PORT

8788

HTTP 和 WebSocket 端口。

AED_NO_GIT

未设置

禁用所有自动提交。

AED_NO_PUSH

未设置

自动提交但从不自动推送。

AED_NO_CHAT_CHECKPOINT

未设置

禁用聊天日志检查点。

AED_PUSH_DEBOUNCE_MS

5000

将多次提交合并为一次推送。

AED_CHAT_IDLE_MS

300000

聊天检查点之前的空闲时间。

AED_CHAT_MAX_MS

900000

强制检查点之前聊天的最大时长。

AED_SCRIPTORIUM_DIR

../scriptorium

#code: 标签解析的位置。

AED_EDITOR_URL

vscode://file/{path}

卡片“在编辑器中打开”的 URL 方案。

故障排除

  • “我在聊天面板中键入，但什么也没有发生。” 几乎总是缺少 --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）滋养修道院图书馆的方式——名字由此而来。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Zettelkasten MCP Server

    vKumar67204
    F
    license
    Not graded
    quality
    A
    maintenance
    Enables users to create, link, tag, search, explore, and synthesize atomic notes through Claude and other MCP-compatible clients. Notes are stored as readable Markdown files with a SQLite index, supporting semantic link types and graph-based discovery of connected ideas.
    -

  • Zettelkasten MCP Server

    Taeyong75721
    F
    license
    Not graded
    quality
    A
    maintenance
    Enables users to create, link, tag, search, explore, and synthesize atomic notes through Claude and other MCP-compatible clients. Notes are kept as human-readable Markdown files (with an automatically rebuilt SQLite index) and connected through typed bidirectional links that form an explorable knowledge graph.
    -

  • Zettelkasten MCP Server

    ruthk69
    F
    license
    Not graded
    quality
    A
    maintenance
    Enables users to create, link, search, explore, and synthesize atomic notes through Claude and other MCP-compatible clients, using Markdown files backed by a SQLite index.
    -