feat: add Chapter 1 demo, VitePress docs site, Codespaces & Jupyter notebook

- Create demo/ with mini-claude scaffolding: types for messages, tools,
  permissions, and config — TypeScript compiles and runs successfully
- Set up VitePress with bilingual (zh-CN/en) docs, sidebar navigation,
  and GitHub Pages deployment workflow
- Add .devcontainer for one-click GitHub Codespaces environment
- Add Jupyter notebook (Deno kernel) for interactive Chapter 1 tutorial
- Update Chapter 1 docs with "Hands-on Build" section for demo walkthrough
- Update Chapter 1 "What's Next" to preview Chapter 2 (Tool implementation)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: anthhub

.devcontainer/devcontainer.json

@@ -0,0 +1,25 @@
+{
+  "name": "Learn Claude Code",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:22",
+  "features": {
+    "ghcr.io/anthropics/devcontainer-features/bun:1": {},
+    "ghcr.io/anthropics/devcontainer-features/deno:1": {}
+  },
+  "postCreateCommand": "bun install && cd demo && bun install",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-vscode.vscode-typescript-next",
+        "esbenp.prettier-vscode",
+        "ms-toolsai.jupyter"
+      ],
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "bash"
+      }
+    }
+  },
+  "forwardPorts": [5173],
+  "portsAttributes": {
+    "5173": { "label": "VitePress Dev", "onAutoForward": "openPreview" }
+  }
+}

.github/workflows/deploy-docs.yml

@@ -0,0 +1,48 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build docs
+        run: bun run docs:build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -27,6 +27,15 @@ bun.lockb
 package-lock.json
 yarn.lock
 
+# Demo dependencies (users install locally)
+demo/node_modules/
+demo/bun.lock
+demo/dist/
+
+# VitePress
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+
 # OS
 .DS_Store
 .DS_Store?

bun.lock

@@ -0,0 +1,113 @@
+/**
+ * main.ts - mini-claude 入口文件
+ *
+ * 对应真实 Claude Code: src/main.tsx
+ *
+ * 当前状态（第 1 章）：仅验证类型系统可正常工作
+ * 后续章节会逐步添加：
+ *   第 2 章: Tool 接口实现 + 工具注册表
+ *   第 3 章: Anthropic API 调用 + 流式响应
+ *   第 4 章: 查询循环（Agentic Loop）
+ *   ...
+ */
+
+import {
+  generateId,
+  isToolUseBlock,
+  isTextBlock,
+  toolToAPIFormat,
+  DEFAULT_CONFIG,
+} from "./types/index.js";
+
+import type {
+  Message,
+  UserMessage,
+  AssistantMessage,
+  ContentBlock,
+  Tool,
+  AppConfig,
+} from "./types/index.js";
+
+// ─── 验证类型系统 ────────────────────────────────────────────────────────────
+
+// 构造一条用户消息
+const userMsg: UserMessage = {
+  type: "user",
+  uuid: generateId(),
+  message: {
+    role: "user",
+    content: "帮我看一下 main.ts 的内容",
+  },
+};
+
+// 构造一条助手消息（模拟 AI 回复，包含工具调用）
+const assistantMsg: AssistantMessage = {
+  type: "assistant",
+  uuid: generateId(),
+  message: {
+    role: "assistant",
+    content: [
+      { type: "text", text: "好的，让我读取这个文件。" },
+      {
+        type: "tool_use",
+        id: "tool_001",
+        name: "Read",
+        input: { file_path: "main.ts" },
+      },
+    ],
+    model: DEFAULT_CONFIG.model,
+    stop_reason: "tool_use",
+  },
+};
+
+// 从助手消息中提取工具调用
+const toolCalls = assistantMsg.message.content.filter(isToolUseBlock);
+
+// 模拟一个工具定义
+const readTool: Tool = {
+  name: "Read",
+  description: "读取文件内容",
+  inputSchema: {
+    type: "object",
+    properties: {
+      file_path: { type: "string", description: "文件的绝对路径" },
+    },
+    required: ["file_path"],
+  },
+  isReadOnly: true,
+  async call(input) {
+    return { content: `[文件内容: ${input.file_path}]` };
+  },
+};
+
+// 转换为 API 格式
+const apiTool = toolToAPIFormat(readTool);
+
+// 构建消息历史
+const messages: Message[] = [userMsg, assistantMsg];
+
+// ─── 输出验证结果 ─────────────────────────────────────────────────────────
+
+console.log("mini-claude - 类型系统验证");
+console.log("=".repeat(40));
+console.log();
+console.log(`消息历史: ${messages.length} 条`);
+console.log(`  用户消息: "${typeof userMsg.message.content === "string" ? userMsg.message.content : "[复合内容]"}"`);
+console.log(`  助手消息: ${assistantMsg.message.content.length} 个内容块`);
+console.log(`  工具调用: ${toolCalls.length} 个`);
+toolCalls.forEach((tc) => {
+  console.log(`    → ${tc.name}(${JSON.stringify(tc.input)})`);
+});
+console.log();
+console.log(`注册工具: ${apiTool.name}`);
+console.log(`  描述: ${apiTool.description}`);
+console.log(`  参数: ${JSON.stringify(apiTool.input_schema.properties)}`);
+console.log(`  只读: ${readTool.isReadOnly}`);
+console.log();
+console.log(`默认配置:`);
+console.log(`  模型: ${DEFAULT_CONFIG.model}`);
+console.log(`  最大 Token: ${DEFAULT_CONFIG.maxTokens}`);
+console.log(`  权限模式: ${DEFAULT_CONFIG.permissionMode}`);
+console.log();
+console.log("类型系统验证通过！");
+console.log("下一步: 第 2 章 - 实现 Tool 接口和工具注册表");

demo/main.ts

@@ -0,0 +1,17 @@
+{
+  "name": "mini-claude",
+  "version": "0.1.0",
+  "description": "A minimal Claude Code clone - built chapter by chapter",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "start": "bun run main.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.52.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.11",
+    "typescript": "^5.7.0"
+  }
+}

demo/package.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "types": ["@types/bun"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "react"
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

demo/tsconfig.json

@@ -0,0 +1,48 @@
+/**
+ * types/config.ts - 配置类型定义
+ *
+ * mini-claude 的运行时配置
+ *
+ * 真实 Claude Code 的配置散布在多个地方：
+ * - CLI 参数（Commander.js）
+ * - 环境变量
+ * - ~/.claude/settings.json
+ * - 项目级 CLAUDE.md
+ *
+ * 我们先定义一个简化的统一配置类型
+ */
+
+import type { PermissionMode } from "./permissions.js";
+
+/**
+ * mini-claude 全局配置
+ */
+export interface AppConfig {
+  /** Anthropic API Key */
+  apiKey: string;
+
+  /** 使用的模型 ID，默认 claude-sonnet-4-20250514 */
+  model: string;
+
+  /** 最大输出 token 数 */
+  maxTokens: number;
+
+  /** 权限模式 */
+  permissionMode: PermissionMode;
+
+  /** 工作目录 */
+  cwd: string;
+
+  /** 系统提示词（可选追加） */
+  systemPrompt?: string;
+}
+
+/**
+ * 默认配置
+ */
+export const DEFAULT_CONFIG: Omit<AppConfig, "apiKey"> = {
+  model: "claude-sonnet-4-20250514",
+  maxTokens: 16384,
+  permissionMode: "default",
+  cwd: process.cwd(),
+};

demo/types/config.ts

@@ -0,0 +1,57 @@
+/**
+ * types/index.ts - 类型统一导出
+ *
+ * 其他模块通过 import { ... } from "./types/index.js" 引入所有类型
+ */
+
+// 消息类型
+export type {
+  TextBlock,
+  ToolUseBlock,
+  ToolResultBlock,
+  ContentBlock,
+  UserMessage,
+  AssistantMessage,
+  SystemMessage,
+  Message,
+  StopReason,
+  APIMessage,
+  APIContentBlock,
+  ToolResult,
+} from "./message.js";
+
+export {
+  generateId,
+  isToolUseBlock,
+  isTextBlock,
+  isAssistantMessage,
+  isUserMessage,
+} from "./message.js";
+
+// 工具类型
+export type {
+  Tool,
+  JSONSchema,
+  JSONSchemaProperty,
+  ToolRegistry,
+  APIToolDefinition,
+} from "./tool.js";
+
+export { toolToAPIFormat } from "./tool.js";
+
+// 权限类型
+export type {
+  PermissionMode,
+  PermissionBehavior,
+  PermissionAllowDecision,
+  PermissionDenyDecision,
+  PermissionAskDecision,
+  PermissionDecision,
+  PermissionRule,
+  PermissionContext,
+  CheckPermissionFn,
+} from "./permissions.js";
+
+// 配置类型
+export type { AppConfig } from "./config.js";
+export { DEFAULT_CONFIG } from "./config.js";