# Marginalia：面向教育场景的开源AI工具框架

> 一个可自托管的开源AI教育工具平台，通过社交契约而非监控机制，让教师能够指导学生负责任地使用大语言模型。基于Cloudflare Workers + D1 + R2 + Vectorize构建。

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-06-07T00:22:03.000Z
- 最近活动: 2026-06-07T00:51:28.044Z
- 热度: 150.5
- 关键词: 教育AI, 大语言模型, 开源工具, Cloudflare, AI辅导, 教育技术, 自托管, TypeScript
- 页面链接: https://www.zingnex.cn/forum/thread/marginalia-ai
- Canonical: https://www.zingnex.cn/forum/thread/marginalia-ai
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**：asugden
- **来源平台**：GitHub
- **原始标题**：marginalia
- **原始链接**：https://github.com/asugden/marginalia
- **发布时间**：2026-06-07

## 项目背景与核心理念

当前关于"AI进课堂"的讨论大多围绕监控展开：检测器、封锁机制、抓作弊。Marginalia基于完全相反的理念构建——它依赖社交契约而非监督。教师为特定目的设置工具；工具向学生明确说明自身身份和行为方式；学生在知情的情况下使用。目标是让AI成为课程作业中更清晰、更诚实的一部分，并重建对AI的信任。

## 三大核心工具

Marginalia为教师提供了三类可构建的AI工具：

### 1. AI辅导助手（Agents）

学生可以与之对话的AI辅导老师。每个助手都有特定的"声音"（对话风格），并可通过两种方式构建：

**Outlines（大纲模式）**：一种引导式对话，按预设顺序引导学生完成一系列主题，每个主题有回合预算和结束条件。这是真正的状态机，在代码层面强制执行——而非依赖系统提示词期望模型按预期行为。这是NotebookLM和Custom GPT无法实现的能力。

### 2. 溯源知识库（Sources）

基于教师选定文档库的答案，答案中内嵌引用，学生可以查证信息来源。这种方式确保AI回答有据可查，培养学生的信息溯源意识。

### 3. 来源追踪写作（Provenance）

写作作业中每个词都被标记来源：手动输入、粘贴内容或AI生成。这是关于作品如何产生的诚实记录，对学生和教师都透明可见。

## 技术架构

Marginalia采用Cloudflare原生技术栈构建：

- **Workers**：无服务器计算
- **D1**：SQLite数据库
- **R2**：对象存储
- **Vectorize**：向量数据库
- **Workers AI**：AI推理服务
- **编程语言**：TypeScript

这种架构设计使得一个30人规模的课程每月运行成本约为5-15美元（不含LLM API调用费用），极具成本效益。

## 部署与自托管

Marginalia设计为每个机构独立部署，无"回拨"机制，无共享后端，需自备API密钥。部署流程包括：

1. 配置Worker（wrangler.toml）
2. 创建Cloudflare资源（D1数据库、R2存储桶、Vectorize索引）
3. 设置密钥（Anthropic API密钥、Google OAuth密钥、会话签名密钥）
4. 配置Google OAuth
5. 执行数据库迁移并部署
6. 使用管理员邮箱登录，创建首个课程

## 隐私与安全设计

项目从设计之初就考虑隐私保护：

- **无集中式后端**：每个机构独立运行实例
- **无数据共享**：不将数据发送到第三方服务
- **透明性**：每个工具在使用前向学生明确说明自身
- **无隐藏监控**：没有后台监督机制

## 多课程支持

v1.0版本支持教师同时教授多门课程，通过跨课程的代理复用（copy-on-use）机制实现。教授多门课程的教师在登录时会看到课程选择器，学生则直接进入其注册的课程。

## 本地开发环境

项目提供完整的本地开发支持：

```bash
cp apps/worker/.dev.vars.example apps/worker/.dev.vars
# 填写Anthropic API密钥；开发环境默认启用绕过认证

cp apps/worker/seed.sql.example apps/worker/seed.sql
npx wrangler d1 migrations apply DB --local --cwd apps/worker
npm run db:seed --workspace apps/worker

# 两个终端
npm run dev      # Worker服务 (:8787)
npm run dev:web  # Web前端 (:5173)
```

## 主题定制

Marginalia提供品牌中性的默认主题。机构可通过在`apps/web/src/branding/`放置theme.yaml文件进行品牌定制，Vite主题插件在构建时读取YAML并生成CSS变量覆盖——无需修改源代码。

## 代码结构

- **apps/web**：React + Vite SPA，分为"学生注册"（首页、对话页、加入页）和"教师注册"（创作页、花名册页、管理页）
- **apps/worker**：Cloudflare Worker，同时服务/api/*和静态SPA（同源，无CORS）
- **packages/auth**：Google OAuth + 通用OIDC适配器，身份标识为(provider_id, subject)而非邮箱
- **packages/backbone**：Outlines背后的对话状态机
- **packages/providers**：LLM提供商适配器（优先Anthropic，计划支持OpenAI兼容接口）
- **packages/rag**：分块、索引、Vectorize检索
- **packages/schema**：D1迁移脚本
- **packages/voices**：声音库（命名对话角色）

## 开源与可持续性

项目采用Apache 2.0许可证。维护者明确表示："这是我使用的工具；欢迎PR"——这种立场是可持续的，保持精简是特性而非缺陷。

## 教育意义

Marginalia代表了AI教育工具的一种新思路：不是通过技术手段限制学生，而是通过透明和信任建立健康的AI使用文化。它展示了如何将AI作为教学伙伴而非监控对象，为教育技术领域提供了重要的参考价值。