EduCode-Agent

EduCode-Agent 是一个独立的 LLM 驱动教学 agent，用于从代码库自动生成 面向人类认知的教材。

使用方法，创建一个.env文件夹 然后填写内容：其他也行，用ai添加即可

DASHSCOPE_API_KEY=
EDUCODE_MODEL=deepseek-v4-pro
EDUCODE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

核心设计原则

按照人类认知规律编排教材：

1. 先让人知道系统在干什么（01-系统故事）
2. 再让人知道它怎么流动（02-主链路）
3. 再让人知道哪些抽象稳定（03-不变量）
4. 最后才深入最核心代码（深挖链路，逐段详解）

架构

Fat Platform（确定性）     Thin LLM Agents（生成）     Meta Layer（协调）
├── RepositoryScanner      ├── CognitivePlanner        ├── MetaAgent
│   ├── AST 符号提取        ├── ReadingOrderAgent       │   ├── 章节摘要
│   └── Import Graph       ├── SystemStoryAgent        │   └── prior_context
├── ContextEngine          ├── FlowTracerAgent         └── CriticAgent
│   ├── repo_brief()       ├── InvariantExtractor          ├── marker 检查
│   └── file_context()     ├── DeepDiveMenuAgent           └── LLM 审查 + 修正
├── SnippetExtractor       ├── InterfaceCardAgent
└── Verifier               ├── DeepDiveExplainer
                           │   ├── 段选择
                           │   └── 逐段教学
                           └── QuestionAgent

• Fat platform: 仓库扫描、符号索引、import graph、上下文压缩、 代码提取、路径验证、输出写入。
• Thin LLM agents: 学习路径规划、系统故事、链路追踪、不变量提取、 逐段深挖教学、接口卡片、理解检查题。
• MetaAgent: 每章生成后提取摘要，传给后续 agent 作为 prior_context， 避免章节间重复和矛盾。
• CriticAgent: marker 硬检查 + LLM 语义审查 + 迭代修正（Self-Refine）。

LLM 不允许自由浏览文件系统。它接收确定性的 repo map 和选定的代码上下文， 然后基于这些 grounded context 进行规划和写作。所有输出强制使用中文。

配置

填写 educode_agent/.env：

DASHSCOPE_API_KEY=your_api_key_here
EDUCODE_MODEL=deepseek-v4-pro
EDUCODE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

API key 也可以通过 EDUCODE_API_KEY、BAILIAN_API_KEY 或 OPENAI_API_KEY 提供。

使用

只需一条命令即可开启生成和交互式学习体验：

python -m educode_agent build --repo /mnt/e/llm/cosci --out /mnt/e/llm/cosci/doc/textbook

默认会进入交互模式（--focus interactive）。流程如下：

1. 先生成 01~05 的概览、主链路、不变量章节。
2. 命令行会自动停下来，把发现的核心链路列出来供你选择。
3. 敲入对应的数字编号后，系统会自动开始“逐段深挖”这条链路的代码，并输出到 deep-dives/ 下。

如果你只想生成特定链路（或在后台批量跑），可以直接传 --focus：

# 只生成概览
python -m educode_agent build --repo /mnt/e/llm/cosci --out /mnt/e/llm/cosci/doc/textbook --focus overview

# 非交互式直接生成某条链路
python -m educode_agent build --repo /mnt/e/llm/cosci --out /mnt/e/llm/cosci/doc/textbook --focus <focus-id>

支持增量生成（跳过已存在的文件），用 --force 强制重新生成：

python -m educode_agent build \
  --repo /mnt/e/llm/cosci \
  --out /mnt/e/llm/cosci/doc/textbook \
  --focus overview \
  --force

可以覆盖模型或端点：

python -m educode_agent build \
  --repo /mnt/e/llm/cosci \
  --out /mnt/e/llm/cosci/doc/textbook \
  --focus overview \
  --model deepseek-v4-pro \
  --base-url https://dashscope.aliyuncs.com/compatible-mode/v1