القائمة
在本项目中创建新课程（0N-xxx）时的蓝图/检查清单。当用户要求新增一节课程、添加新的学习目录、或创建新的入口文件时自动触发。涵盖：课程目录命名（含来源标签）、入口文件模板、TerminalFormatter 集成、sys.path 样板代码、敏感信息必须写入 .env。详细代码注释规范见项目根目录的 AGENTS.md，本 skill 不重复。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف 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 — 自动检查目录/文件命名和敏感文件防护