一、项目概况

维度信息
名称Claw-ED（原名 eduagent）
作者Jon Maccarello（纽约公立学校教师）+ Claude Opus 4.6（AI co-author）
版本v5.15.2026（761次提交，活跃开发中）
协议MIT（完全商用友好）
Stars49 / Forks 10
语言Python ≥ 3.11
安装pip install clawed
定位面向教师的 CLI Agent，学习教师风格后批量生成完整教学包
口号"Made by a teacher, for teachers"

关键特点：这不是一个公司产品，而是一个真正的一线教师（教社会研究/Social Studies）从自己的备课痛点出发，用AI辅助开发的开源工具。所有功能设计都源于真实教学场景。

二、核心架构

2.1 整体架构分层

┌─────────────────────────────────────────────────┐
│                  Interface Layer                │
│  CLI / TUI / Web API / Telegram Bot / MCP Server │
│  Chrome Extension / Student CLI / Student Bot   │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│               Agent Core (Orchestrator)           │
│  agent.py / agent_core/ / multi_agent.py         │
│  - Tool Registry (51 tools)                      │
│  - Approval Gate (风险分级审批)                    │
│  - Session Compression (历史压缩)                  │
└────────┬──────────┬──────────┬──────────────────┘
         │          │          │
┌────────▼──┐ ┌────▼─────┐ ┌▼──────────────┐
│ Generation │ │ Quality  │ │ Brain / Memory │
│ Pipeline   │ │ Gate     │ │ System         │
│ - lesson   │ │ (12检)   │ │ - soul.md     │
│ - unit     │ │          │ │ - brain/       │
│ - assess   │ │          │ │   students/   │
│ - slides   │ │          │ │   topics/     │
│ - game     │ │          │ │   concepts/   │
│ - sim      │ │          │ │ - timeline    │
└────────┬──┘ └──────────┘ └────────────────┘
         │
┌────────▼──────────────────────────────────────┐
│              Export / Compilation Layer          │
│  DOCX / PPTX / PDF / HTML / Anki / Kahoot      │
│  IMS Common Cartridge / Audio / MP4 / CSV       │
└─────────────────────────────────────────────────┘

2.2 技术栈

层级技术选型
CLI框架Typer + Rich
Web框架FastAPI + Uvicorn
数据模型Pydantic v2（strict mode，全链路类型安全）
LLM客户端Anthropic SDK + OpenAI SDK（双模态支持）
模型路由自研 tier-based router（FAST / DEEP 两级）
文档解析pypdf + python-docx + python-pptx + lxml
PDF生成reportlab（MIT） / weasyprint（可选）
语音转录faster-whisper（GPU优先，whisper CLI降级）
TTSgTTS
动画Manim（3Blue1Brown风格教育动画）
浏览器自动化Playwright
向量搜索ONNX MiniLM + FTS5 + RRF融合
数据库SQLite
定时任务APScheduler
MCPmcp SDK（VS Code / Claude Code集成）
加密存储keyring（API密钥安全存储）

2.3 模型路由策略（值得借鉴）

Claw-ED设计了两级模型路由，不是所有任务都用最贵的模型：

Tier适用任务默认模型（Anthropic）默认模型（Google）
FAST意图识别、快速问答、搜索、课堂铃音、格式化、图片质量检查claude-opus-4gemini-2.5-flash
DEEP教案生成、单元规划、材料创建、差异化教学、IEP修改、评估创建、课程缺口分析、人设提取、游戏/仿真生成claude-opus-4gemini-2.5-pro

解析优先级：

  1. 用户自定义 per-task 模型覆盖（最高）
  2. 用户自定义 tier→provider 映射
  3. 用户自定义 tier→model 映射
  4. Provider内置默认值
  5. 全局默认值

产品启示：国内产品同样需要区分"快思考"和"慢思考"任务。意图识别、简单格式化用便宜的小模型；教案生成、差异化方案用强模型。这个路由机制直接控制成本。

三、核心功能模块深度分析

3.1 Voice Learning（教师风格学习）⭐ 核心差异化

这是Claw-ED最独特的设计，国内产品完全没有对标。

工作原理

教师文件 (PPT/DOCX/PDF/TXT)
        ↓
  Ingest Pipeline（文档解析）
        ↓
  文档截取（每文档≤3000字符，最多30文档，总计≤50000字符）
        ↓
  LLM分析（temperature=0.3，确定性采样）
        ↓
  TeacherPersona 结构化输出
        ↓
  合并到 soul.md（持久化教师画像）
        ↓
  每次生成时注入 system prompt

TeacherPersona 数据模型

从教师文件中提取的结构化画像：

维度提取内容类型
teaching_style教学风格Enum（10种）
vocabulary_level词汇水平Enum（4种）
tone语气基调String
voice_sample语音样本String
do_now_style课堂开场风格String
exit_ticket_style收尾检测风格String
handout_style讲义风格String
assessment_style评估风格Enum（7种）
source_types偏好素材类型List（上限10）
activity_patterns活动模式List（上限10）
scaffolding_moves脚手架策略List（上限10）
signature_moves标志性教学动作List（上限8）
grouping_preferences分组偏好String

合并策略（关键设计）

不是简单覆盖，而是分字段类型用不同策略：

  • 身份字段（teaching_style, vocabulary_level）：永不覆盖，核心身份一旦建立就保护
  • 字符串字段（tone, do_now_style等）：仅填充空值，已有值不动
  • 列表字段（source_types, activity_patterns等）：去重合并，已有项优先，追加新项
  • 列表上限：防止无序膨胀

自蒸馏（Self-Distillation）

  • 教师对生成内容的评分和编辑会被记录
  • 系统定期将这些反馈合并回 soul.md
  • 相当于"教师越用越懂你"

产品启示：

- 国内产品目前都是"通用模板→填内容"，缺少"学习教师个人风格"这一层

- 合并策略的保守设计（身份永不覆盖、字符串仅填充空值）值得直接借鉴——避免LLM的不稳定性破坏已建立的用户画像

- 如果做中国K12，可以提取：教师常用的课堂用语（"同学们""请大家思考一下"）、板书风格（纲要式/图解式/推导式）、例题偏好（竞赛题/生活题/课本题）

3.2 Quality Gate（质量门控）⭐ 核心差异化

12道教学质检检查，不合格自动拒绝并重新生成。

检查项（从测试代码逆向还原）

#检查项拒绝条件原理
1引导笔记数量guided_notes < 8笔记太少=教学不充分
2创意活动缺少 creative_activity纯讲授式不够
3主源材料primary_sources < 2需要一手史料支撑
4出场券exit_ticket < 3 个条目检测不够
5Bloom层级出场券只有Level1（记忆/理解）认知深度不够
6刺激材料评估缺少stimulus-based问题需要基于材料的分析
7差异化具体性差异化方案太泛（"给更多时间"）要有具体的IEP适配
8多元性审计例子/人物单一需要多元代表性
9AI痕迹出现"delve""utilize"等70+个LLM用词不是教师写的
10内容完整性只有摘要没有实质内容不能糊弄
11教学活动结构缺少 I Do/We Do/You Do 或等价结构教学流程不完整
12评估与目标对齐评估没有覆盖教学目标教-学-评不一致

失败处理机制

生成内容 → 12项检查 → 全部通过?
                         ↓否
                    自动重试（最多2次）
                         ↓
                    仍失败? → 返回机器可解析的错误码
                    (NLAH Stage 4 错误枚举)
                         ↓
                    教师收到具体失败原因，可调整后重试

NLAH（Never-Let-A-Human）错误码

机器可解析的失败码系统，方便日志分析和后续自动化：

class FailureCode(Enum):
    INSUFFICIENT_GUIDED_NOTES = "..."
    MISSING_CREATIVE_ACTIVITY = "..."
    LOW_BLOOM_EXIT_TICKET = "..."
    # ...13种结构化错误码

产品启示：

- 国内产品基本都是"生成→直接展示"，缺少质检环节

- 12项检查完全基于教育学原理（Bloom分类、差异化教学、教-学-评一致性），不是泛泛的"格式检查"

- 自动重试+错误码设计，体验上用户感知不到失败（大部分情况下），但系统内部在保证质量

- 对中国K12的适配方向：检查是否符合新课标、是否有跨学科关联、是否符合核心素养目标

3.3 AI-ism Removal（AI痕迹清除）⭐ 核心差异化

三层分级清洗机制，让AI生成的材料读起来像真人教师写的。

三层设计

Tier触发条件处理方式示例
Tier 1始终替换直接词替换"delve"→"explore"、"utilize"→"use"、"leverage"→"use"
Tier 2同一段落出现≥2个条件替换"streamline"、"bolster"、"augment"、"groundbreaking"
Tier 3每500词出现>3个密度替换"innovative"、"dynamic"、"strategic"、"impactful"、"empower"

教育词汇白名单

Tier 2/3中的词如果属于合法学术词汇则不替换：

EDUCATION_WHITELIST = {
    # 科学
    "catalyst", "optimize", "synthesis", "integral", "fundamental",
    "dynamic", "equilibrium", "momentum", "vector", "matrix",
    # 数学
    "function", "variable", "coefficient", "parameter", "significant",
    "derivative", "transformation",
    # 社科/人文
    "paradigm", "revolution", "reform", "progressive", "cornerstone",
    # 通用学术
    "analyze", "evaluate", "compare", "contrast", "distinguish",
}

结构模式修复

不仅改词，还改AI特有的写作习惯：

  • 冒号标题："Key Takeaway: The revolution..." → "Key Takeaway — The revolution..."
  • 过度使用em-dash列表

产品启示：

- 国内大模型生成的中文内容同样有明显的"AI味"（"首先...其次...最后"、"综上所述"、"值得注意的是"、"不难发现"等）

- 可以建立中文AI痕迹词库+教育白名单（如"核心素养"、"跨学科关联"是新课标标准术语，不应替换）

- 三层分级设计很聪明——不一刀切，避免误杀

3.4 Voice Check（风格匹配验证）

生成后的风格一致性检查，纯规则引擎（不用LLM），轻量快速。

检查内容

检查项方法结果
称呼匹配persona中的称呼词 vs 生成文本中的称呼词不匹配→告警
Do Now风格persona偏好(scenario/recall/opinion) vs 实际生成类型场景型教师生成了回忆型→告警
结构匹配（预留但未实现）—

关键设计原则：只产生建议性提醒，永远不阻断导出。

Do Now风格分类器

基于正则的轻量分类：

  • 场景型：触发词 imagine, pretend, what if, you are, you wake, you discover
  • 回忆型：触发词 what do you remember/know, list three, define, yesterday...what
  • 观点型：触发词 do you think, should...?, is it fair/right/just

产品启示：

- 规则引擎比LLM检查更快更确定性，适合做"最后一道防线"

- "不阻断"原则很好——教师辛苦等了生成结果，不应该因为风格小问题被拦住，而是提醒他可以调整

- 对中国K12：可以检查"导入方式"是否匹配教师习惯（温故知新/情境创设/问题导入/实验导入）

3.5 Materials Generation（材料生成管线）

一条指令并行生成4类材料，每类有独立的Prompt模板和温度控制。

四类生成器

生成器输出Prompt来源TemperatureLLM角色
Worksheet练习题列表prompts/worksheet.txt0.5专家级练习设计师
Assessment评估题目+评分标准prompts/assessment.txt0.4（更低，格式一致性）专家级评估设计师
Slides幻灯片大纲内联prompt0.5演示设计师
IEP Notes个性化适配方案prompts/differentiation.txt0.5差异化教学专家

防御性JSON解析

class _WorksheetResult(PydanticBaseModel):
    items: list[WorksheetItem]

    @model_validator(mode="before")
    @classmethod
    def _wrap_list(cls, data):
        if isinstance(data, list):  # LLM有时返回裸数组
            return {"items": data}
        return data

产品启示：

- 每类材料的temperature不同——评估用更低的0.4保证格式一致性，练习用0.5留一些灵活性

- 防御性JSON解析处理LLM输出不稳定的问题（返回数组vs对象），很实用

- Prompt模板文件化，方便教研团队迭代调优

3.6 Differentiation（差异化教学）

针对IEP/504学生的自动化适配，是美国公立学校刚需。

三个子功能

功能输入输出核心逻辑
IEP课程修改DailyLesson + IEPProfile列表每个学生的修改版课程按具体住宿/修改/目标适配
504住宿说明DailyLesson + 住宿列表DifferentiationNotes504不改学什么，改怎么学
分层作业主题+年级+层数WorksheetItem列表同一概念不同难度

分层作业编码

Tier 1 (Approaching): items 1-99
Tier 2 (On-Level):    items 100-199
Tier 3 (Advanced):    items 200-299

IEPProfile 数据模型

class IEPProfile:
    student_name: str
    disability_type: str
    accommodations: list[str]    # 住宿（不改内容）
    modifications: list[str]     # 修改（改内容/期望）
    goals: list[str]             # IEP目标

产品启示：

- 中国K12没有正式IEP/504体系，但有类似需求：学困生/留守儿童/随迁子女/超常儿童的分层教学

- 可以转化为：学情数据驱动的分层教案生成——按班级学生的平均水平和薄弱点自动调整难度和重点

- "同一概念不同难度"的分层作业设计可以直接借鉴编码方式

3.7 Classroom Profile（课堂画像）

持久化的教室物理和社交环境描述，注入每次生成的prompt上下文。

数据模型

维度字段示例值
物理环境student_count, seating_arrangement, has_smartboard, has_chromebooks32学生, clusters, ✓, ✓
学生构成ell_count, iep_count, plan_504_count, gifted_count, reading_level_range5 ELL, 3 IEP, Grade 5-9
时间安排period_length_minutes, periods_per_day40分钟, [1节, 3节, 6节]
课程信息textbook, lms_platform, standards_framework, stateMcGraw-Hill, Google Classroom, NYS, NY
教师偏好preferred_grouping, noise_tolerance, preferred_activities, avoided_activitiespairs, structured talk

注入Prompt的方式

## Classroom Context (from saved profile)
- School: [name]
- Class size: [N] students
- Period length: [N] minutes
- Available tech: SmartBoard, projector, Chromebooks (1:1)
- Student needs: [N] ELL students, [N] IEP students
- Reading level spread: [range]
- Seating: [arrangement]
- Preferred grouping: [style]
- LMS: [platform]
- Textbook: [name]
Design ALL activities to work in THIS specific classroom.

产品启示：

- 国内产品缺少"教室环境感知"——40人班级的活动设计和20人完全不同

- 如果产品能对接学校的排课系统/班级信息系统，自动获取班级规模、课时长度、教室设备，生成的教案会更有实用性

- 对中国K12特别重要：标准教室vs实验室vs多媒体教室 vs大教室，直接影响教学活动设计

3.8 Brain System（记忆系统）

Markdown-based的知识图谱+时间线混合存储。

存储结构

brain/
  students/{slug}.md  — 每个学生的整合事实+时间线
  topics/{slug}.md    — 每个主题的教学历史
  lessons/{slug}.md   — 每个已生成课程的记录
  originals/{slug}.md — 教师教学洞察（Tier 1原始数据）
  concepts/{slug}.md  — 词汇表（生成课程时自动创建）

搜索能力

  • 混合搜索：关键词(FTS5) + 向量(ONNX MiniLM) + RRF融合
  • Brain-first Lookup：生成前先查brain，避免重复
  • Post-generation Writeback：生成后写回brain

Dream Cycle（梦境整合）

每天凌晨3:15自动运行：

  • 整合时间线 → 编译事实
  • 相当于"睡眠中整理记忆"

学生进度追踪

class StudentProgress:
    student_name: str
    topics_asked: dict[str, int]  # 每个主题问了多少次
    total_questions: int
    struggle_topics: list[str]    # 问≥3次自动标记为困难点

产品启示：

- 这是"长期记忆"的实现——不是session级别的，而是跨session积累的教学经验

- 中国K12可以转化：积累每个班级/每个知识点的教学效果反馈，逐步形成"什么方式讲这个知识点效果最好"的经验库

- 学生困难点自动检测（≥3次提问）是一个很轻量的学情分析，可以在课堂实时模式中使用

3.9 Classroom Mode（课堂实时模式）

WebSocket驱动的实时课堂交互。

功能

  • 实时幻灯片控制
  • 计时器
  • 投票/ polls
  • 学生通过class code加入
  • Exit ticket自动评分（关键词分析+形成性反馈+句子起步建议）
  • 自适应反馈循环：exit ticket结果自动影响下一节课（重教/拓展建议+家长通知）

四、导出能力

4.1 支持格式

格式用途技术
DOCX（教师版）教案python-docx
DOCX（学生版）讲义/笔记python-docx
PPTX课件python-pptx
PDF打印reportlab / weasyprint
HTML在线浏览Jinja2
MP4教育动画Manim
Anki TSV闪卡自定义导出
Kahoot CSV课堂游戏自定义导出
IMS Common CartridgeLMS导入（Canvas/Moodle）自定义导出
Audio Script旁白脚本gTTS
CSV/TSV数据导出标准

4.2 主题化

学科感知的主题系统：

  • 不同学科使用不同的配色和排版
  • 包含专业页眉/页脚/品牌标识

五、安全与权限设计

5.1 工具风险分级

每个Agent工具声明自己的风险等级：

风险等级行为审批要求
read_only只读操作无需审批
write_local本地写入自动批准
network_call网络请求自动批准
package_install安装包始终需教师确认
external_publish外部发布始终需教师确认

5.2 审计事件（v5.15硬化）

ED-1: classroom state永远不向学生泄露poll_responses
ED-2: auth bootstrap使用secrets.compare_digest（防时序攻击）
ED-3: 学生聊天需要share_token（缺失→422，错误→403）
ED-9: 社区评分拒绝1.0-5.0范围外的值
ED-10: 所有SQLite连接验证PRAGMA foreign_keys=ON

5.3 认证安全

  • API密钥通过 keyring 安全存储，永不写入磁盘明文JSON
  • Web API默认绑定localhost
  • Bearer token认证
  • HttpOnly + SameSite=strict cookies

六、数据模型设计要点

6.1 LLM抗性验证（重要）

由于LLM输出不稳定，Claw-ED的Pydantic模型做了大量模糊映射：

# TeachingStyle 模糊映射
aliases = {
    "lecture": "lecture_discussion",
    "collaborative": "cooperative",
    "experiential": "inquiry_based",
    "problem_based": "project_based",
    "student_centered": "inquiry_based",
    "teacher_centered": "direct_instruction",
    "traditional": "direct_instruction",
}
# 未识别 → 默认 BLENDED

6.2 确定性采样

Persona提取时使用 Random(42) 确定性采样——同一批文档多次提取得到相同结果。

6.3 文档截取策略

维度限制原因
每文档最大字符3,000控制单文档权重
最大文档数30控制总量
总字符上限50,000 (~12K tokens)适配任意模型上下文

七、测试体系

  • 90+ 测试文件，从1,083个增长到2,063+个测试用例
  • 核心Agent/API代码覆盖率 85%+
  • pytest + async模式
  • 安全回归测试21项
  • 质量门控测试（验证auto-retry机制）
  • 语音匹配测试
  • 导出编译测试
  • 全链路 mypy --strict 通过，270个源文件零错误

八、与国内产品的对比

维度Claw-ED国内主流产品（九章/希沃/星火）
教师风格学习✅ soul.md深度画像，自蒸馏❌ 基本没有
质量门控✅ 12项教育学检查+自动重试❌ 生成即展示
AI痕迹清除✅ 三层分级+教育白名单❌ 未关注
差异化教学✅ IEP/504/分层，每学生定制⚠️ 有但不精细
课堂环境感知✅ 持久化classroom profile❌ 无
长期记忆✅ brain系统+时间线+dream cycle⚠️ 有学情记录但非教学经验
模型路由✅ FAST/DEEP分级⚠️ 通常单一模型
导出格式✅ 12种（含LMS兼容）⚠️ 3-5种
标准对齐✅ 50州标准✅ 新课标
交互界面❌ CLI为主✅ Web/App为主
B端部署❌ 个人工具✅ 学校/教育局
中国市场❌ 无✅ 原生
学科覆盖深度⚠️ 文科见长（作者背景）✅ 全学科

九、对中国K12 AI备课产品的建议

9.1 值得直接移植的设计

  1. 教师画像系统（soul.md）：学习教师常用课堂导入方式、板书风格、例题偏好、语言习惯
  2. 质量门控：新课标对齐检查、核心素养目标检查、教-学-评一致性检查、AI痕迹检测
  3. 三层AI痕迹清除：建立中文AI痕迹词库+新课标术语白名单
  4. 模型路由：简单任务用小模型/快模型，教案生成用强模型
  5. 防御性LLM输出解析：Wrapper Model处理裸数组/格式不一致

9.2 需要本地化的部分

Claw-ED设计中国K12适配
IEP/504学困生分层+随堂学情数据驱动的难度调整
50州标准新课标+各省市考纲（可建立标准知识库）
Classroom Profile对接学校排课/班级信息系统
CLI为主Web/App为主，保留API能力
英语教法术语中国教法术语（导入/新授/巩固/练习/拓展）
英文AI痕迹词中文AI痕迹词（综上所述/值得注意的是/不难发现）

9.3 Claw-ED的不足（你的机会）

  1. 单学科偏重：作者教社会研究，理科（数学推导、实验设计、物理公式）支持较弱
  2. 无B端能力：纯个人工具，缺少学校级/区域级的协同、审核、分发
  3. 无学情闭环：虽然有学生进度追踪，但没有对接真实的学生测评数据
  4. 无中文支持：全英文，中文K12需要大量本地化
  5. 无真实课标库：50州标准是简化版的，不是完整的课程标准知识图谱

十、总结

Claw-ED是一个设计理念先进但产品化程度有限的项目。它的价值不在于可以直接拿来用，而在于它展示了"AI备课工具应该做到什么精细度"：

  • Voice Learning证明了"AI可以学习教师的个人风格"这个方向是可行的
  • Quality Gate证明了"12道教育学质检+自动重试"可以在实际中运作
  • AI-ism Removal证明了"让AI输出读起来不像AI"可以系统化解决
  • Brain System证明了"教学经验可以跨session积累"

这些设计理念如果移植到中国K12场景，结合国内产品的全学科覆盖、B端部署、课标对齐能力，有潜力做出差异化明显的产品。