SuperAPI AI 工具集

content-track-scaffolder

编程与开发

查看项目

更新于 10-28 13:24

技能介绍

Content Track Scaffolder 是一个技能/脚手架工具,用于在教程网站中创建一条完整的新内容轨道(content track),即一套完整的学习路径。它遵循现有 Foundation、Advanced 和 Terminal 轨道的既定模式,生成所有必要文件并完成接线。

用途

当需要添加新的学习路径(例如 “Mobile”、“Data”、“Enterprise”),扩展教程增加新的模块系列,或克隆现有架构到相关教程站点时,可使用此技能。它也可以帮助理解现有轨道是如何组装在一起的。

一条轨道包含的 7 组文件

  1. 内容文件:src/content/<track>/module-*.md
  2. 数据解析模块:src/data/<track>Content.ts
  3. 主页:src/pages/<Track>HomePage.tsx
  4. 课程页:src/pages/<Track>LessonPage.tsx
  5. 总结页:src/pages/<Track>SummaryPage.tsx
  6. 路由:src/App.tsx(懒加载导入 + Route 条目)
  7. 导航链接: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 成功。

适用场景

适用于教程站点新增学习路径、扩展模块系列、克隆架构到相关站点,或理解现有轨道的接线方式。

限制

资料未说明该技能有额外的运行时依赖或平台限制;具体安装命令、收费或价格信息暂未提供。