fix: address review findings for Chapter 1

anthhub · claude · anthhub · commit 2d963865f0a2 · 2026-04-01T17:43:51.000+08:00
Infrastructure:
- Fix devcontainer features to use existing community images
- Add VitePress head/meta for SEO and social sharing
- Add English locale outline and docFooter config

Demo code:
- Remove unnecessary @anthropic-ai/sdk dependency (defer to Ch3)
- Add PermissionRuleSource type and source field to PermissionRule
- Add ToolCategory type and category field to Tool interface
- Extract DEFAULT_MODEL constant in config.ts

Documentation:
- Enhance Ch1 Section 7 with config explanations and troubleshooting FAQ
- Make Ch1 "What's Next" preview more specific with concrete deliverables
- Add "Key Milestones" section to both README files (zh-CN and en)
- Sync all changes between Chinese and English versions

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -2,8 +2,9 @@
   "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": {}
+    "ghcr.io/devcontainers/features/node:1": { "version": "22" },
+    "ghcr.io/shyim/devcontainers-features/bun:0": {},
+    "ghcr.io/nicklasxyz/devcontainer-features/deno:1": {}
   },
   "postCreateCommand": "bun install && cd demo && bun install",
   "customizations": {
diff --git a/README.md b/README.md
@@ -24,6 +24,8 @@ Claude Code is more than a chatbot wrapper. It's a full-featured terminal applic
 
 Understanding its source is a masterclass in building production-grade AI applications.
 
+**Build as you learn.** This isn't just documentation — it's a progressive tutorial. Starting from Chapter 1, you'll build `mini-claude`, a working clone of Claude Code. Each chapter adds a new module to the demo. By Chapter 12, you'll have a fully functional AI coding assistant with tools, permissions, terminal UI, and more.
+
 ---
 
 ## Learning Roadmap
@@ -45,6 +47,87 @@ Understanding its source is a masterclass in building production-grade AI applic
 
 ---
 
+## The Demo: mini-claude
+
+As you read each chapter, you'll build `mini-claude` — a working AI coding assistant that mirrors Claude Code's real architecture. The demo lives in the `demo/` directory and grows chapter by chapter.
+
+### Final Architecture
+
+```
+demo/
+├── main.ts                    # CLI entry (Commander.js)
+├── context.ts                 # System prompt builder
+├── query.ts                   # Query loop (stream + tool calls)
+├── Tool.ts                    # Tool interface & factory
+├── tools.ts                   # Tool registry
+├── types/
+│   ├── message.ts             # Message types
+│   └── permissions.ts         # Permission types
+├── tools/
+│   ├── BashTool/
+│   ├── FileReadTool/
+│   ├── FileWriteTool/
+│   ├── FileEditTool/
+│   ├── GrepTool/
+│   ├── GlobTool/
+│   └── TodoWriteTool/
+├── services/
+│   ├── api/claude.ts          # Anthropic SDK wrapper
+│   └── compact/compact.ts     # Context compression
+├── screens/REPL.tsx           # Terminal UI (Ink)
+├── components/
+│   ├── App.tsx
+│   ├── MessageList.tsx
+│   └── PermissionRequest.tsx
+├── commands/
+│   ├── clear.ts
+│   ├── help.ts
+│   └── compact.ts
+└── utils/
+    ├── permissions.ts
+    ├── messages.ts
+    ├── format.ts
+    └── config.ts
+```
+
+### What You Build Each Chapter
+
+| Ch | Module Added | Demo Capability After |
+|----|-------------|----------------------|
+| 1 | Project scaffold + type system | Type definitions compile |
+| 2 | Tool.ts + tools.ts | Tool interface & registry |
+| 3 | services/api/ + context.ts | Streaming API calls |
+| 4 | query.ts + utils/messages.ts | Multi-turn tool-calling loop |
+| 5 | tools/BashTool, FileReadTool, GrepTool | Execute commands, read files, search |
+| 6 | tools/FileWriteTool, FileEditTool, GlobTool | Full file operations |
+| 7 | utils/permissions.ts | Dangerous command blocking |
+| 8 | screens/REPL.tsx + components/ | Interactive terminal UI |
+| 9 | main.ts (Commander.js) | Full CLI with args |
+| 10 | commands/ + compact service | /help, /clear, /compact |
+| 11 | components/PermissionRequest.tsx | Interactive permission dialogs |
+| 12 | History, retry, error handling | Production-ready demo |
+
+### Key Milestones
+
+- **After Chapter 2**: Tools can actually execute shell commands and read files
+- **After Chapter 4**: Complete Agentic Loop — AI automatically calls tools and reasons in a loop
+- **After Chapter 8**: Interactive terminal UI, experience close to real Claude Code
+- **After Chapter 12**: Fully functional AI coding assistant
+
+### Architecture Correspondence
+
+| Demo File | Real Claude Code Equivalent |
+|-----------|----------------------------|
+| `Tool.ts` | `src/Tool.ts` |
+| `tools.ts` | `src/tools/index.ts` |
+| `query.ts` | `src/query.ts` |
+| `context.ts` | `src/context.ts` |
+| `services/api/claude.ts` | `src/services/claude.ts` |
+| `screens/REPL.tsx` | `src/screens/REPL.tsx` |
+| `utils/permissions.ts` | `src/utils/permissions.ts` |
+
+---
+
 ## Chapters
 
 ### Foundation (Chapters 1-2)
@@ -115,6 +198,11 @@ learn-claude-code/
 │   │   └── dependency-graph.ts
 │   ├── 02-cli-entrypoint/
 │   └── ...
+├── demo/                   # mini-claude: the progressive demo you build
+│   ├── main.ts
+│   ├── query.ts
+│   ├── Tool.ts
+│   └── ...
 └── diagrams/               # Architecture diagrams
 ```
 
@@ -148,6 +236,11 @@ bun run ch1:structure
 
 # Or run any example directly
 bun run examples/01-overview/project-structure.ts
+
+# Run the demo (after completing chapters)
+cd demo
+bun install
+bun run main.ts
 ```
 
 Then open [docs/en/01-overview.md](docs/en/01-overview.md) and follow along.
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -24,6 +24,8 @@ Claude Code 远不止是一个聊天机器人包装器，它是一个功能完
 
 研究其源码，是构建生产级 AI 应用的绝佳实战教材。
 
+**边学边做。** 这不只是文档——这是一个渐进式实战教程。从第 1 章开始，你将构建 `mini-claude`，一个可运行的 Claude Code 克隆版。每章都会为 demo 新增一个模块。到第 12 章结束，你将拥有一个功能完整的 AI 编程助手，包含工具系统、权限控制、终端 UI 等完整功能。
+
 ---
 
 ## 学习路线
@@ -45,6 +47,87 @@ Claude Code 远不止是一个聊天机器人包装器，它是一个功能完
 
 ---
 
+## Demo：mini-claude
+
+在阅读每一章的同时，你将构建 `mini-claude`——一个与 Claude Code 真实架构对应的可运行 AI 编程助手。demo 位于 `demo/` 目录中，随章节逐步完善。
+
+### 最终目录结构
+
+```
+demo/
+├── main.ts                    # CLI 入口（Commander.js）
+├── context.ts                 # 系统提示词构建器
+├── query.ts                   # 查询循环（流式 + 工具调用）
+├── Tool.ts                    # 工具接口与工厂
+├── tools.ts                   # 工具注册表
+├── types/
+│   ├── message.ts             # 消息类型
+│   └── permissions.ts         # 权限类型
+├── tools/
+│   ├── BashTool/
+│   ├── FileReadTool/
+│   ├── FileWriteTool/
+│   ├── FileEditTool/
+│   ├── GrepTool/
+│   ├── GlobTool/
+│   └── TodoWriteTool/
+├── services/
+│   ├── api/claude.ts          # Anthropic SDK 封装
+│   └── compact/compact.ts     # 上下文压缩
+├── screens/REPL.tsx           # 终端 UI（Ink）
+├── components/
+│   ├── App.tsx
+│   ├── MessageList.tsx
+│   └── PermissionRequest.tsx
+├── commands/
+│   ├── clear.ts
+│   ├── help.ts
+│   └── compact.ts
+└── utils/
+    ├── permissions.ts
+    ├── messages.ts
+    ├── format.ts
+    └── config.ts
+```
+
+### 每章构建内容
+
+| 章 | 新增模块 | 完成后 Demo 能力 |
+|----|---------|----------------|
+| 1 | 项目脚手架 + 类型系统 | 类型定义可编译 |
+| 2 | Tool.ts + tools.ts | 工具接口与注册表 |
+| 3 | services/api/ + context.ts | 流式 API 调用 |
+| 4 | query.ts + utils/messages.ts | 多轮工具调用循环 |
+| 5 | tools/BashTool、FileReadTool、GrepTool | 执行命令、读取文件、搜索 |
+| 6 | tools/FileWriteTool、FileEditTool、GlobTool | 完整文件操作 |
+| 7 | utils/permissions.ts | 危险命令拦截 |
+| 8 | screens/REPL.tsx + components/ | 交互式终端 UI |
+| 9 | main.ts（Commander.js） | 完整 CLI 参数支持 |
+| 10 | commands/ + compact 服务 | /help、/clear、/compact 命令 |
+| 11 | components/PermissionRequest.tsx | 交互式权限确认对话框 |
+| 12 | 历史记录、重试、错误处理 | 生产就绪的 demo |
+
+### 关键里程碑
+
+- **第 2 章后**：工具可以实际执行 shell 命令和读取文件
+- **第 4 章后**：完整的 Agentic Loop——AI 自动调用工具并循环推理
+- **第 8 章后**：交互式终端 UI，体验接近真实 Claude Code
+- **第 12 章后**：功能完整的 AI 编程助手
+
+### 架构对应关系
+
+| Demo 文件 | 真实 Claude Code 对应文件 |
+|-----------|--------------------------|
+| `Tool.ts` | `src/Tool.ts` |
+| `tools.ts` | `src/tools/index.ts` |
+| `query.ts` | `src/query.ts` |
+| `context.ts` | `src/context.ts` |
+| `services/api/claude.ts` | `src/services/claude.ts` |
+| `screens/REPL.tsx` | `src/screens/REPL.tsx` |
+| `utils/permissions.ts` | `src/utils/permissions.ts` |
+
+---
+
 ## 章节详情
 
 ### 基础篇（第 1-2 章）
@@ -115,6 +198,11 @@ learn-claude-code/
 │   │   └── dependency-graph.ts
 │   ├── 02-cli-entrypoint/
 │   └── ...
+├── demo/                   # mini-claude：你逐章构建的渐进式 demo
+│   ├── main.ts
+│   ├── query.ts
+│   ├── Tool.ts
+│   └── ...
 └── diagrams/               # 架构图
 ```
 
@@ -148,6 +236,11 @@ bun run ch1:structure
 
 # 或直接运行任意示例
 bun run examples/01-overview/project-structure.ts
+
+# 运行 demo（完成相应章节后）
+cd demo
+bun install
+bun run main.ts
 ```
 
 然后打开 [docs/zh-CN/01-overview.md](docs/zh-CN/01-overview.md) 跟随学习。
diff --git a/demo/main.ts b/demo/main.ts
@@ -16,6 +16,7 @@ import {
   isToolUseBlock,
   isTextBlock,
   toolToAPIFormat,
+  DEFAULT_MODEL,
   DEFAULT_CONFIG,
 } from "./types/index.js";
 
diff --git a/demo/package.json b/demo/package.json
@@ -7,9 +7,7 @@
     "typecheck": "tsc --noEmit",
     "start": "bun run main.ts"
   },
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.52.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@types/bun": "^1.3.11",
     "typescript": "^5.7.0"
diff --git a/demo/types/config.ts b/demo/types/config.ts
@@ -37,11 +37,14 @@ export interface AppConfig {
   systemPrompt?: string;
 }
 
+/** 默认模型 ID — 更新模型时只需修改此处 */
+export const DEFAULT_MODEL = "claude-sonnet-4-20250514";
+
 /**
  * 默认配置
  */
 export const DEFAULT_CONFIG: Omit<AppConfig, "apiKey"> = {
-  model: "claude-sonnet-4-20250514",
+  model: DEFAULT_MODEL,
   maxTokens: 16384,
   permissionMode: "default",
   cwd: process.cwd(),
diff --git a/demo/types/index.ts b/demo/types/index.ts
@@ -31,6 +31,7 @@ export {
 // 工具类型
 export type {
   Tool,
+  ToolCategory,
   JSONSchema,
   JSONSchemaProperty,
   ToolRegistry,
@@ -48,10 +49,11 @@ export type {
   PermissionAskDecision,
   PermissionDecision,
   PermissionRule,
+  PermissionRuleSource,
   PermissionContext,
   CheckPermissionFn,
 } from "./permissions.js";
 
 // 配置类型
 export type { AppConfig } from "./config.js";
-export { DEFAULT_CONFIG } from "./config.js";
+export { DEFAULT_MODEL, DEFAULT_CONFIG } from "./config.js";
diff --git a/demo/types/permissions.ts b/demo/types/permissions.ts
@@ -72,6 +72,14 @@ export type PermissionDecision =
 
 // ─── 权限规则 ───────────────────────────────────────────────────────────────
 
+/**
+ * 权限规则来源
+ *
+ * 真实 Claude Code 中，权限规则可以来自多个来源，
+ * source 字段用于溯源和优先级判断
+ */
+export type PermissionRuleSource = "userSettings" | "projectSettings" | "session" | "default";
+
 /**
  * 权限规则 - 预定义的权限判断规则
  *
@@ -89,6 +97,8 @@ export interface PermissionRule {
   behavior: PermissionBehavior;
   /** 规则说明 */
   reason?: string;
+  /** 规则来源，用于溯源和优先级判断 */
+  source?: PermissionRuleSource;
 }
 
 // ─── 权限上下文 ──────────────────────────────────────────────────────────────
diff --git a/demo/types/tool.ts b/demo/types/tool.ts
@@ -14,6 +14,17 @@
 
 import type { ToolResult } from "./message.js";
 
+// ─── 工具分类 ───────────────────────────────────────────────────────────────
+
+/**
+ * 工具分类
+ *
+ * builtin: 内置工具（如 Bash、FileRead）
+ * mcp: 通过 MCP 协议桥接的外部工具
+ * skill: 通过技能系统加载的工具
+ */
+export type ToolCategory = "builtin" | "mcp" | "skill";
+
 // ─── 工具接口 ───────────────────────────────────────────────────────────────
 
 /**
@@ -57,6 +68,9 @@ export interface Tool {
    */
   call(input: Record<string, unknown>): Promise<ToolResult>;
 
+  /** 工具分类，默认 builtin */
+  category?: ToolCategory;
+
   /**
    * 是否为只读操作
    *
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -4,6 +4,14 @@ export default defineConfig({
   title: "Learn Claude Code",
   description: "深入理解 Claude Code 架构与实现的实战指南",
 
+  head: [
+    ["link", { rel: "icon", type: "image/svg+xml", href: "/learn-claude-code/logo.svg" }],
+    ["meta", { property: "og:type", content: "website" }],
+    ["meta", { property: "og:title", content: "Learn Claude Code" }],
+    ["meta", { property: "og:description", content: "深入理解 Claude Code 架构与实现的实战指南" }],
+  ],
+  lastUpdated: true,
+
   base: "/learn-claude-code/",
 
   locales: {
@@ -113,6 +121,8 @@ export default defineConfig({
             "https://github.com/anthhub/learn-claude-code/edit/main/docs/:path",
           text: "Edit this page on GitHub",
         },
+        outline: { label: "On this page" },
+        docFooter: { prev: "Previous", next: "Next" },
       },
     },
   },
diff --git a/docs/en/01-overview.md b/docs/en/01-overview.md
diff --git a/docs/zh-CN/01-overview.md b/docs/zh-CN/01-overview.md
