Menu
在本项目中创建新课程（0N-xxx）时的蓝图/检查清单。当用户要求新增一节课程、添加新的学习目录、或创建新的入口文件时自动触发。涵盖：课程目录命名（含来源标签）、入口文件模板、TerminalFormatter 集成、sys.path 样板代码、敏感信息必须写入 .env。详细代码注释规范见项目根目录的 AGENTS.md，本 skill 不重复。
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Basé sur la classification professionnelle SOC
| name | course-blueprint |
| description | 在本项目中创建新课程（0N-xxx）时的蓝图/检查清单。当用户要求新增一节课程、添加新的学习目录、或创建新的入口文件时自动触发。涵盖：课程目录命名（含来源标签）、入口文件模板、TerminalFormatter 集成、sys.path 样板代码、敏感信息必须写入 .env。详细代码注释规范见项目根目录的 AGENTS.md，本 skill 不重复。 |
为 langchain-ai-learn 项目创建新课程时，提供一站式检查清单和文件模板。确保所有新课程目录命名、文件结构、终端输出风格与现有课程保持一致。
铁律：如果用户未明确说明课程来源（如 LangChain、OpenAI、Anthropic 等），必须先询问用户再继续。
课程来源标签附加在目录名末尾，格式为 [{来源}]：
01-quickstart[langchain] — 来自 LangChain 官方文档02-agents[langchain] — 来自 LangChain 官方文档03-models[langchain] — 来自 LangChain 官方文档如果未来加入其他来源（如 OpenAI Cookbook），标签如 04-xxx[openai]。
目录命名格式：{NN}-{英文短描述}[{来源}]
NN：两位数字序号（01-99），与已有课程递增英文短描述：小写字母 + 连字符，简洁描述课程主题[{来源}]：第 1 步确定的来源标签mkdir {NN}-{topic}[{source}]
每个入口文件命名格式：main-{NN}-{topic}.py
NN：两位数字序号（01-99），表示课程内的学习顺序，由浅入深topic：小写字母 + 连字符，简洁描述本文件的知识点示例：
01-quickstart[langchain]/
├── main-01-basic-agent.py # 1.1 基本智能体
├── main-02-literature-analysis.py # 1.2 文学数据分析
└── main-03-deep-agent.py # 1.3 深度智能体
每个入口文件必须包含以下样板代码。使用 references/entry-template.py 作为起点。
必须包含的结构（按顺序）：
# 1. 文件头部 docstring — 说明本节课主题和学习目标
"""
第X课 · X.X：{标题}
====================================================================
学习目标：
1. ...
2. ...
"""
# 2. 标准库导入
import os
import sys
# 3. 项目根目录路径修正（必须 — 确保 utils/ 模块可被导入）
# 为什么需要：入口脚本可能通过 uv run python <相对路径> 执行，Python 不会自动
# 将项目根目录加入搜索路径。__file__ 往上两级即项目根目录
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
# 4. 第三方库导入
from dotenv import load_dotenv
load_dotenv() # 必须在 LangChain 导入之前调用
# 5. 本地工具导入 — TerminalFormatter 是项目标配的终端美化输出工具
# 导入时会自动安装警告可视化处理器：第三方库的 WARNING 将以 ⚠️ 黄色显示到 stderr
from utils.terminal_formatter import tf
# 6. 其他业务逻辑导入（LangChain 组件等）
tf 共 15 个公开方法，按使用频率排序：
| 场景 | 方法 | 典型用法 |
|---|---|---|
| 信息/状态提示 | tf.print_info(msg) | tf.print_info("智能体执行中...") |
| 阶段分隔标题 | tf.print_rule("标题") | tf.print_rule("2.1 基本智能体 — 运行结果") |
| 实验小节头部 | tf.print_section("标题", number=1) | tf.print_section("temperature 对比实验", number=2) |
| 实验间暂停 | check_continue() | check_continue() |
| 键值对配置 | tf.print_key_value(dict) | tf.print_key_value({"模型": "deepseek"}, title="配置") |
| JSON 数据 | tf.print_json(data) | tf.print_json(block, title="工具调用") |
| 面板/强调块 | tf.print_panel(text, title="标题") | tf.print_panel(task, title="任务描述") |
| Markdown 渲染 | tf.print_markdown(text) | tf.print_markdown(reply_text) |
| 成功消息 | tf.print_success(msg) | tf.print_success("清理完成") |
| 错误消息 | tf.print_error(msg) | tf.print_error(f"连接超时：{e}") |
| 警告消息 | tf.print_warning(msg) | tf.print_warning("API Key 未设置") |
| 表格数据 | tf.print_table(rows) | tf.print_table(tools, title="工具列表") |
| 语法高亮代码 | tf.print_code(code, language="python") | tf.print_code(script) |
| 树形结构 | tf.print_tree(data) | tf.print_tree(dir_struct, title="项目结构") |
| AI 消息文本提取 | tf.extract_text(message) | text = tf.extract_text(latest_message) |
核心规则：
print()extract_text 再渲染 — AIMessage.content 可能是 list[dict] 格式，直接 str() 会输出 Python 对象表示。tf.extract_text() 统一处理 str/list/content_blocks 三种格式，始终返回纯文本tf.print_info() — 作为通用替代print() — 因为需要即时逐行输出（flush=True），不宜用 Rich 组件包装。这些 print 应使用现有的 emoji 前缀格式（🔧/✅/💬）warnings.showwarning，将警告以 ⚠️ [WARNING] 黄色样式输出到 stderr，既不淹没信息也不干扰主输出流每个实验小节结束时必须调用 check_continue()，让用户有时间阅读输出、理解代码原理后再进入下一实验。
视觉层级设计：
| 场景 | 使用方法 | 说明 |
|---|---|---|
| 文件级标题 | tf.print_rule("第X课 · X.X：...") | 细线分隔，青色 |
| 实验小节头部 | tf.print_section("标题", number=N) | Panel 面板，黄色边框，更醒目 |
| 实验间暂停 | check_continue() | 等待用户确认（y/回车=继续，n/q=退出） |
| 知识点总结 | tf.print_rule("📖 知识点总结") | 细线分隔，保持一致性 |
| 代码内部子步骤 | tf.print_info("...") | 蓝色信息提示 |
标准模式（每个实验小节的代码结构）：
from utils.terminal_formatter import check_continue, tf
# 文件标题 — print_rule
tf.print_rule("第X课 · X.X：课程标题")
# 实验 1 — print_section（醒目面板）
tf.print_section("实验1标题", number=1)
# ... 实验代码 ...
check_continue() # 暂停，等用户确认后继续
# 实验 2
tf.print_section("实验2标题", number=2)
# ... 实验代码 ...
check_continue()
# 知识点总结 — print_rule（最后一个section，不暂停）
tf.print_rule("📖 知识点总结")
# ... 总结内容 ...
# 注意：总结后不调用 check_continue()，文件自然结束
批量模式（Batch Mode）：
设置环境变量 BATCH_MODE=1 可跳过所有交互确认，适合 CI 或一键运行：
# .env 中设置（持久生效）
BATCH_MODE=1
# 或命令行指定（单次生效）
BATCH_MODE=1 uv run python 03-models[langchain]/main-01-init-invoke.py
设计原则：
print_rule — 文件级标题和知识点总结，使用细线（青色）print_section — 实验小节标题，使用 Panel 面板（黄色），视觉权重更大check_continue() — 每个实验小节末尾调用一次，让用户掌控学习节奏check_continue()（文件自然结束）铁律：所有密钥、Token、密码等敏感信息必须写在 .env 文件中，严禁硬编码到代码。
.env：真实配置（已被 .gitignore 排除，不可提交到 Git）.env.example：脱敏模板（可安全提交，供其他学员参考）新学员上手流程：cp .env.example .env → 填入自己的 Key → 即可运行全部课程
若有新的配置项需要添加：
.env 中添加真实值.env.example 中的对应项（使用占位符替换真实值）.env.example 中的注释完整说明该项的用途和获取方式AGENTS.md 的「代码规范」章节AGENTS.md 的「环境变量」章节references/entry-template.py — 完整的可复制模板utils/terminal_formatter.py — 完整的 API 文档.github/workflows/check-course-standards.yml — 自动检查目录/文件命名和敏感文件防护