Tutorial Writer

Tutorial Writer v1.0.0 — 8-Sub Router (Monorepo Edition)

定位: 轻量路由枢纽 — 将教程创作请求分发到 8 个独立子技能 架构: 8-Entry Router (root → skills/ = Layer 0 → Layer 1) 工具链: Turborepo | 方案: 方案 C (8-Sub Hybrid + Independent Init) 架构版本: Monorepo-v1（内容-格式解耦 + 三层分离）

目标

将教程创作的完整生命周期（调研规划 → 撰写执行 → 内容管理 → 质量校验 → 网站构建 → 电子书生成 → 部署发布 → 决策贯穿）通过统一入口分发，每个阶段有独立的技能文件和细则。

能做什么:

• 智能路由用户请求到 8 个自含型子技能
• 提供全局速查（铁律/分类）
• 展示子技能概览和相互依赖关系
• 引导项目初始化流程

不能做什么:

• 不包含具体操作步骤（各子技能负责）
• 不执行校验或构建或发布（→ /review /web /book /github-pages）
• 不包含项目初始化逻辑（→ 见下方"🚀 项目初始化"章节）

🏗️ Monorepo 架构概览

设计来源: README.md 第 4、5 章 核心哲学: 内容是唯一真相源，格式是可扩展的表示层

架构核心理念

Layer 1: 路由层 (SKILL.md)          → 纯请求分发
Layer 2: 技能层 (skills/*)           → 每个技能只关注核心职责
Layer 3: 工具层 (scripts+templates)  → 初始化、模板、共享工具

apps/                            ← 应用层
├── web/ (表示层 A)         ← 网站 (Astro + Starlight, 依赖 content)
packages/                        ← 库层
├── content/ (数据层)             ← 唯一真相源
└── book/    (表示层 B)          ← 电子书 (Pandoc + PDF, 依赖 content)

依赖关系: content ← web, content ← book (禁止反向)

三大设计原则

版本兼容性要求

本路由器要求 web (apps/web) ≥ v1.0.0、book ≥ v1.0.0、github-pages ≥ v1.0.0。旧版子技能使用传统架构，与本版本不兼容。

🎯 核心原则（速查）

┌──────────────────────────────────────────────┐
│                三大铁律                        │
├──────────────────────────────────────────────┤
│ ① 层级 ≤3 层 (references/assets 不算)         │
│ ② NO SKILL WITHOUT USE CASE IN AGENTS         │
│ ③ description 只写触发条件 (CSO)              │
└──────────────────────────────────────────────┘

CSO 规则: description 含 "Use when..."，max 1024 字符

详情见 references/design-principles.md。

🧭 8-Sub 路由表

用户说...                                        → 调用
─────────────────────────────────              ─────────────────────────────────────
"搜索/调研/规划/找资料/设计章节结构"            → 📚 /research       (调研与规划)
"写/撰写/创作/编写章节"                        → ✍️ /writing        (撰写执行)
"检查/校对/质量/门禁/评分"                     → ✅ /review         (质量校验)
"内容结构/schema/命名规范/Frontmatter/目录组织" → 📝 /content        (内容管理) 🆕
"构建网站/Astro/Starlight/组件/配置"           → 🌐 /web            (网站构建) ⭐ 高频
"PDF/电子书/Pandoc/排版/EPUB/LaTeX"           -> 📖 /book           (电子书生成) 🆕
"部署/GitHub Pages/Actions/CI-CD/域名"         → 🚀 /github-pages   (Pages 部署) 🟢 低频
"配置/决策/改决策/看看决策/冲突"               → 📐 /decision      (决策系统)

复合场景

歧义处理

不确定用户意图时提供选项：

"您是想：a) 📚 调研规划 b) ✍️ 撰写/修改内容 c) 📝 内容结构管理 d) ✅ 质量检查 e) 🌐 构建网站 f) 📖 生成电子书 g) 🚀 部署发布 h) 📐 管理决策？"

📂 子技能一览

8 个子技能完全自含：独立 SKILL.md + references/ + 阶段性决策细则

频率说明: web 为高频子技能（预计每项目 10-20 次调用），github-pages 为低频（2-3 次），book 为中频（3-5 次）

变更说明:

• ✅ 保持: 职责不变，仅更新版本号和引用
• ⚠️ 精简: 移除了内容管理相关部分（→ content 子技能）
• 🆕 新增: 全新子技能，填补职责空白
• ✏️ 重命名: 目录重命名 + 职责聚焦（如 publish → github-pages 仅保留部署）

📂 项目结构

tutorial-writer/
├── SKILL.md                              ← 本文件 (8-Sub 路由器)
├── references/                           ← 全局共享参考
│   ├── design-principles.md              ← 铁律+分类+架构说明
│   ├── cross-chapter-rules.md            ← R7-R10 跨章一致性规则
│   ├── phase-mapping.md                  ← 阶段→决策项映射
│   └── monorepo-guide.md                 ← 🆕 Turborepo 使用指南
├── assets/                               ← 全局共享模板
│   ├── decision-record-schema.json
│   └── decision-record-template.json
└── skills/                               ← Layer 1: 8个独立子技能
    ├── ① tutorial-writer-research/       ← 📚 调研规划 (保持)
    ├── ② tutorial-writer-writing/        ← ✍️ 撰写执行 (精简)
    ├── ③ tutorial-writer-review/         ← ✅ 质量校验 (保持)
    ├── 🆕 ④ tutorial-writer-content/     ← 📝 内容管理 (新增)
    ├── ✏️ ⑤ tutorial-writer-web/         ← 🌐 网站构建 (原 build)
    ├── 🆕 ⑥ tutorial-writer-book/        ← 📖 电子书生成 (新增)
    ├── ✏️ ⑦ tutorial-writer-github-pages/← 🚀 Pages 部署 (原 publish)
    └── ⑧ tutorial-writer-decision/       ← 📐 决策贯穿 (保持)

🚀 项目初始化

重要: 项目初始化已迁移至官方 CLI 工具链，详见下方"🚀 项目初始化 (Official Tools)"章节。

⚠️ 注意事项

• 子技能优先: 根文件仅做路由，详细逻辑在各子技能中
• 每个子技能可独立使用: 有自己的 description，Agent 可直接触发
• 全局 references/ 仅放跨子技能公共内容: 设计原则/跨章规则/阶段映射/Monorepo 指南
• 职能归属明确: 搜索规划在 research，撰写在写作，内容管理在 content，校验在 review，网站构建在 web，电子书在 book，部署在 github-pages，决策在 decision
• 决策贯穿所有阶段: 每个子技能内有独立的 decision-record-rules.md 定义本阶段决策细则
• 🆕 Monorepo 架构约束:
  • 必须通过 init 脚本初始化项目: 不要在子技能中手动创建 Monorepo 结构
  • 版本要求: web ≥ v1.0.0, book ≥ v1.0.0, github-pages ≥ v1.0.0
  • 依赖方向: content 包被 web 和 book 依赖，禁止反向依赖
  • 内容唯一源: 所有 Markdown 内容放在 packages/content/src/chapters/
  • 初始化顺序: 先按照"🚀 项目初始化 (Official Tools)"章节初始化项目，再使用各子技能
  • 如需使用旧版架构: 请降级到 tutorial-writer v6.1.0

版本历史

最后更新: 2026-05-31 | 维护者: skill-factory + user collaboration

🚀 项目初始化 (Official Tools)

重要: Tutorial Writer 使用官方 CLI 工具链创建项目， 而非自定义脚本。这确保始终使用最新版本的模板和最佳实践。

初始化流程概览

graph LR
    A[Step 0: 环境准备] --> B[Step 1: 创建 Monorepo]
    B --> C[Step 2: 添加 content 包]
    C --> D[Step 3: 创建 web 包]
    D --> E[Step 4: 添加 book 包]
    E --> F[Step 5: 配置依赖]
    F --> G[Step 6: 注入 TW 配置]
    
    style A fill:#e3f2fd,stroke:#1565c0
    style G fill:#c8e6c9,stroke:#2e7d32

Step 0: 前置环境检查

# 确保 Node.js >= 18
node --version  # 需要 v18+

# 确保包管理器可用（任选其一）
bun --version    # 推荐（教程项目使用 bun）
# 或 pnpm --version
# 或 npm --version

# 可选：安装 Turborepo CLI（如果需要全局命令）
bun add -D turbo
# 或 npx turbo  （推荐，无需安装）

Step 1: 创建 Monorepo 骨架

使用 Turborepo 官方脚手架：

# 方式 A: 使用 create-turbo（推荐，交互式）
bunx create-turbo@latest <project-name>
# 会提示选择:
# - Package manager: bun (推荐) / pnpm / yarn / npm
# - App type: 根据需求选择

cd <project-name>
bun install

# 方式 B: 手动创建（更可控）
mkdir <project-name> && cd <project-name>
bun init
# 在 package.json 中添加 workspaces: ["apps/*", "packages/*"]
# 创建 turbo.json（详见 Turborepo 官方文档）

验证:

ls turbo.json package.json
# 然后检查 package.json 包含 workspaces 配置

Step 2: 添加 content 包（数据层）

# 使用 turbo gen 添加空包
turbo gen workspace \
  --name @repo/content \
  --type package \
  --destination packages/content

# 创建内容目录结构
mkdir -p packages/content/src/chapters
touch packages/content/src/chapters/.gitkeep

Step 3: 创建 web 应用（网站层）

# 在项目根目录运行，自动在 apps/web 下创建 Astro + Starlight 项目
bun create astro apps/web --template starlight --install --yes

注意: create-astro 会生成完整的 Astro 项目结构。 我们不需要手动复制任何模板文件！

Turbo 约定: 可运行的应用放在 apps/ 目录，共享库放在 packages/ 目录。apps/web 是新增的教程站点，与 create-turbo 默认生成的 apps/web、apps/docs 并列。

Step 4: 添加 book 包（电子书层）

turbo gen workspace \
  --name @repo/book \
  --type package \
  --destination packages/book

Step 5: 配置 Workspace 依赖

编辑各包的 package.json，声明依赖关系：

// apps/web/package.json
{
  "dependencies": {
    "@repo/content": "workspace:*"
  }
}

// packages/book/package.json
{
  "dependencies": {
    "@repo/content": "workspace:*"
  }
}

Step 6: 注入 Tutorial Writer 配置

这是 Tutorial Writer 的核心增值部分：

6.1 Content Schema 定义

详见 /content 子技能。

简要步骤：

# 创建 Content Collections 配置
cat > packages/content/src/config.ts << 'EOF'
import { defineCollection, z } from 'astro:content';
import { docsLoader, docsSchema } from '@astrojs/starlight/loaders';

const chapters = defineCollection({
  loader: docsLoader(),
  schema: docsSchema({
    schema: z.object({
      title: z.string(),
      description: z.string().optional(),
      draft: z.boolean().default(false),
      tags: z.array(z.string()).default([]),
      difficulty: z.enum(['beginner', 'intermediate', 'advanced']).optional(),
      readingTime: z.number().optional(),
      prerequisites: z.array(z.string()).default([]),
      hasInteractive: z.boolean().default(false),
      hasMermaid: z.boolean().default(false),
      hasMath: z.boolean().default(false),
    }),
  }),
});

export const collections = { chapters };
EOF

6.2 PDF 生成配置（可选）

详见 /book 子技能。

验证清单

初始化完成后，确认以下文件存在：

• turbo.json (根目录)
• package.json 包含 workspaces: ["apps/*", "packages/*"]
• packages/content/package.json
• packages/content/src/config.ts
• apps/web/package.json
• apps/web/astro.config.mjs (Starlight 配置)
• packages/book/package.json

常见问题

Q: 可以用 pnpm/npm/yarn 吗？ A: 可以！Turborepo 支持所有主流包管理器。本教程示例使用 bun 和 npm workspaces（"workspaces" 字段配置在 package.json 中）。

Q: 必须按顺序执行吗？ A: Step 2-4 可以并行执行（如果用多个终端），但 Step 5 必须在它们之后。

Q: 如何更新到最新模板？ A: 无需手动操作！每次运行 create-astro@latest 都会获取最新版本。