course-blueprint

name	course-blueprint
description	在本项目中创建新课程（0N-xxx）时的蓝图/检查清单。当用户要求新增一节课程、添加新的学习目录、或创建新的入口文件时自动触发。涵盖：课程目录命名（含来源标签）、入口文件模板、TerminalFormatter 集成、sys.path 样板代码、敏感信息必须写入 .env。详细代码注释规范见项目根目录的 AGENTS.md，本 skill 不重复。

新课程创建蓝图

概述

为 langchain-ai-learn 项目创建新课程时，提供一站式检查清单和文件模板。确保所有新课程目录命名、文件结构、终端输出风格与现有课程保持一致。

创建新课程流程

第 1 步：确定课程来源（来源标签）

铁律：如果用户未明确说明课程来源（如 LangChain、OpenAI、Anthropic 等），必须先询问用户再继续。

课程来源标签附加在目录名末尾，格式为 [{来源}]：

• 01-quickstart[langchain] — 来自 LangChain 官方文档
• 02-agents[langchain] — 来自 LangChain 官方文档
• 03-models[langchain] — 来自 LangChain 官方文档

如果未来加入其他来源（如 OpenAI Cookbook），标签如 04-xxx[openai]。

第 2 步：创建课程目录

目录命名格式：{NN}-{英文短描述}[{来源}]

• NN：两位数字序号（01-99），与已有课程递增
• 英文短描述：小写字母 + 连字符，简洁描述课程主题
• [{来源}]：第 1 步确定的来源标签

mkdir {NN}-{topic}[{source}]

第 3 步：创建入口文件

每个入口文件命名格式：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 深度智能体

第 4 步：入口文件模板

每个入口文件必须包含以下样板代码。使用 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 组件等）

第 5 步：TerminalFormatter 使用规范

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)

核心规则：

1. 所有静态输出必须用 tf 方法 — 除流式事件的实时反馈外，不允许出现裸 print()
2. AI 消息必须先 extract_text 再渲染 — AIMessage.content 可能是 list[dict] 格式，直接 str() 会输出 Python 对象表示。tf.extract_text() 统一处理 str/list/content_blocks 三种格式，始终返回纯文本
3. 找不到合适方法时用 tf.print_info() — 作为通用替代
4. 流式事件的实时进度保留原始 print() — 因为需要即时逐行输出（flush=True），不宜用 Rich 组件包装。这些 print 应使用现有的 emoji 前缀格式（🔧/✅/💬）
5. 所有输出内容不能过滤或隐藏 — 包括第三方库的警告信息。TerminalFormatter 在导入时自动安装自定义 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()（文件自然结束）
• 默认不启用 BATCH_MODE（交互模式），需要时用户在 .env 中取消注释

第 6 步：环境变量与敏感信息

铁律：所有密钥、Token、密码等敏感信息必须写在 .env 文件中，严禁硬编码到代码。

• .env：真实配置（已被 .gitignore 排除，不可提交到 Git）
• .env.example：脱敏模板（可安全提交，供其他学员参考）

新学员上手流程：cp .env.example .env → 填入自己的 Key → 即可运行全部课程

若有新的配置项需要添加：

1. 先在 .env 中添加真实值
2. 同步更新 .env.example 中的对应项（使用占位符替换真实值）
3. 确保 .env.example 中的注释完整说明该项的用途和获取方式

参考资源

• 代码注释规范：详见项目根目录 AGENTS.md 的「代码规范」章节
• 环境变量规范：详见 AGENTS.md 的「环境变量」章节
• 入口文件模板：references/entry-template.py — 完整的可复制模板
• TerminalFormatter 源码：utils/terminal_formatter.py — 完整的 API 文档
• GitHub CI 规范检查：.github/workflows/check-course-standards.yml — 自动检查目录/文件命名和敏感文件防护