Content Track Scaffolder 是一个技能/脚手架工具,用于在教程网站中创建一条完整的新内容轨道(content track),即一套完整的学习路径。它遵循现有 Foundation、Advanced 和 Terminal 轨道的既定模式,生成所有必要文件并完成接线。
用途
当需要添加新的学习路径(例如 “Mobile”、“Data”、“Enterprise”),扩展教程增加新的模块系列,或克隆现有架构到相关教程站点时,可使用此技能。它也可以帮助理解现有轨道是如何组装在一起的。
一条轨道包含的 7 组文件
- 内容文件:
src/content/<track>/module-*.md - 数据解析模块:
src/data/<track>Content.ts - 主页:
src/pages/<Track>HomePage.tsx - 课程页:
src/pages/<Track>LessonPage.tsx - 总结页:
src/pages/<Track>SummaryPage.tsx - 路由:
src/App.tsx(懒加载导入 + Route 条目) - 导航链接:
src/components/SiteHeader.tsx(头部导航)
现有轨道参考
- Foundation:路由
/learn/foundation/…,内容目录tutorial/,数据模块tutorialContent.ts,步骤前缀Step N:,模块 Parts 0-8。 - Advanced:路由
/learn/agentic/…,内容目录advanced/,数据模块advancedContent.ts,步骤前缀Step A1:,模块 A-E。 - Terminal:路由
/learn/terminal/…,内容目录terminal/,数据模块terminalContent.ts,步骤前缀Step F1:,模块 F-H。
旧路由(/lesson/、/advanced/、/terminal/)仍通过 App.tsx 中的重定向工作,但新代码不应使用。
轨道之间的关键差异
- 模板变量:Foundation 支持
{{projectName}}等;Advanced 和 Terminal 无模板变量(isAdvanced=true)。 - 提示类型:Foundation 每步单个提示;Advanced 每步多个提示;Terminal 每步多个提示并支持 metaPrompt。
- 提示编号格式:Foundation 为 1, 2, 3;Advanced 为 A1, B2, C3;Terminal 为 F1, G2, H3。
- Step 接口:Foundation 和 Advanced 用 Step(数字/字符串 prompt),Terminal 用 TerminalStep。
- Module 接口:Foundation 用 Part,Advanced 用 Module,Terminal 用 TerminalModule。
- Meta-prompts:仅 Terminal 支持(
===分隔符)。 - 主页主题:Foundation 默认主题;Advanced 渐变/玻璃主题;Terminal 绿色 CRT 主题。
创建新轨道的步骤
第一步:规划轨道身份
确定轨道名称(PascalCase,例如 Cloud)、路由前缀(小写,例如 /cloud/)、内容目录(小写,例如 src/content/cloud/)、模块字母前缀(按 H 之后顺序,例如 I, J, K)、步骤前缀(字母+数字,例如 Step I1:)、提示前缀(同字母,例如 I1, I2, J1)。
第二步:创建内容 Markdown 文件
在 src/content/<track>/module-<letter>-<slug>.md 创建文件,frontmatter 包含 id、number、title、subtitle;使用 ## step: 和 ### title: 格式;提示块使用 :::prompt 包裹。模块字母约定使用 import.meta.glob 模式 module-*.md,number 决定排序,步骤 ID 需在轨道内唯一。
第三步:创建数据解析模块
创建 src/data/<track>Content.ts,以 advancedContent.ts 为基础模板(支持每步多个提示)。定义 <Track>Step 和 <Track>Module 接口,使用 import.meta.glob 加载 Markdown。解析流程包括:normalizeLF、parseKeyValueBlock、parseFrontmatter、parsePromptBlocks、parseSteps、parseModuleMarkdown、load<Track>Data(带缓存的异步加载器),以及 <track>SummaryContent(包含 workflow、quickReference、troubleshooting、learned)。如果支持 meta-prompt,在 parsePromptBlocks 中增加 === 分隔符解析;如果使用模板变量,导入或复制 resolveContent / applyTemplate。
第四步:创建页面组件
- 主页:
src/pages/<Track>HomePage.tsx,使用 useState + useEffect 异步加载数据,渲染模块卡片链接到/<track>/module/${module.id},总结链接指向/<track>/summary。 - 课程页:克隆
AdvancedLessonPage.tsx,更新数据导入、路由参数、步骤深链接(可选:stepId)、IntersectionObserver、NavigationSidebar、StepCard(isAdvanced=true)和进度/导航。 - 总结页:克隆
AdvancedSummaryPage.tsx,导入<track>SummaryContent并渲染四个部分。
第五步:在 App.tsx 中添加路由
添加懒加载导入,并按 /learn/:pathId 模式添加四条路由:/learn/<track>、/learn/<track>/:moduleId、/learn/<track>/:moduleId/:stepId、/learn/<track>/summary。同时在 src/data/paths.ts(官方)或 src/content/community/<id>/path.json(社区)注册路径以出现在目录中。
第六步:添加头部导航
在 src/components/SiteHeader.tsx 中按现有模式添加新轨道的导航链接。
第七步:创建指令文件(可选)
如果轨道有特殊内容约定,创建 .github/instructions/<track>-content.instructions.md,使用 applyTo: src/content/<track>/** 模式。
总结内容模板
每条轨道需要一个总结内容对象,包含四个部分:workflow(工作流步骤,5-10 项)、quickReference(活动与提示对应)、troubleshooting(问题、预防、解决,5-10 项)、learned(关键概念列表和激励性结尾)。
验证
资料提供了一个 PowerShell 审计脚本,用于检查内容文件、数据模块、页面组件、路由、头部导航和构建检查。完成前应确认所有文件创建、接口正确、路由和导航更新,并运行 npm run build 成功。
适用场景
适用于教程站点新增学习路径、扩展模块系列、克隆架构到相关站点,或理解现有轨道的接线方式。
限制
资料未说明该技能有额外的运行时依赖或平台限制;具体安装命令、收费或价格信息暂未提供。