feat: Chapters 9-12 — CLI, commands, permissions, production features

Chapter 9 — Commander.js CLI:
- Add cli.ts with --model, --max-tokens, --permission-mode, -p/--prompt
- Interactive (REPL) and non-interactive (--prompt) modes
- Update App.tsx and REPL.tsx to accept CLI props

Chapter 10 — Slash commands & context compression:
- Add commands/ with /help, /clear, /compact and command registry
- Add services/compact/compact.ts with compactMessages(), estimateTokens()
- Integrate command handling into REPL.tsx

Chapter 11 — Interactive permission confirmation:
- Add utils/interactive-permission.ts with terminal Y/n prompts
- Wraps checkPermission() for interactive use

Chapter 12 — Production-ready features:
- Add utils/history.ts for session persistence (~/.mini-claude/sessions/)
- Add utils/retry.ts with exponential backoff retry logic
- Add utils/config.ts for multi-source config loading

Documentation:
- Add "Hands-on Build" sections to Ch9-12 docs (zh-CN and en)
- Ch12 includes final project structure and completion message

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

Author: anthhub

demo/cli.ts

@@ -0,0 +1,72 @@
+/**
+ * cli.ts - Commander.js CLI 入口
+ *
+ * 对应真实 Claude Code: src/entrypoints/cli.tsx
+ * 解析命令行参数，决定运行模式，启动对应流程。
+ */
+
+import { Command } from "commander";
+import { render } from "ink";
+import React from "react";
+import { App } from "./components/App.js";
+import { query } from "./query.js";
+import { allTools } from "./tools.js";
+import { createPermissionContext, createCheckPermissionFn } from "./utils/permissions.js";
+import { DEFAULT_MODEL, DEFAULT_CONFIG } from "./types/index.js";
+import type { PermissionMode } from "./types/index.js";
+
+const program = new Command();
+
+program
+  .name("mini-claude")
+  .description("A minimal Claude Code clone — built chapter by chapter")
+  .version("0.1.0")
+  .option("-m, --model <model>", "Model to use", DEFAULT_MODEL)
+  .option("--max-tokens <n>", "Max output tokens", "4096")
+  .option("--permission-mode <mode>", "Permission mode: default, auto, bypassPermissions", "auto")
+  .option("-p, --prompt <text>", "Run a single prompt (non-interactive mode)")
+  .option("--print", "Print response and exit (implies -p)")
+  .action(async (options) => {
+    const model = options.model;
+    const maxTokens = parseInt(options.maxTokens, 10);
+    const permMode = options.permissionMode as PermissionMode;
+
+    // 非交互模式：单次查询
+    if (options.prompt || options.print) {
+      const promptText = options.prompt ?? process.argv.slice(2).join(" ");
+      if (!promptText) {
+        console.error("Error: --prompt requires a text argument");
+        process.exit(1);
+      }
+
+      if (!process.env.ANTHROPIC_API_KEY) {
+        console.error("Error: ANTHROPIC_API_KEY not set");
+        process.exit(1);
+      }
+
+      const permCtx = createPermissionContext(permMode);
+      const checkPerm = createCheckPermissionFn(permCtx);
+
+      const result = await query(promptText, [], {
+        model,
+        maxTokens,
+        checkPermission: checkPerm,
+        onText: (text) => process.stdout.write(text),
+        onToolUse: (name) => {
+          if (!options.print) {
+            process.stderr.write(`\n[tool: ${name}]\n`);
+          }
+        },
+      });
+
+      if (!options.print) {
+        console.error(`\n[${result.turns} turns, ${result.inputTokens}+${result.outputTokens} tokens]`);
+      }
+      process.exit(0);
+    }
+
+    // 交互模式：启动 REPL
+    render(React.createElement(App, { model, maxTokens, permissionMode: permMode }));
+  });
+
+program.parse();

demo/commands/clear.ts

@@ -0,0 +1,10 @@
+/**
+ * commands/clear.ts - /clear 命令
+ */
+export const clearCommand = {
+  name: "clear",
+  description: "清空对话历史",
+  execute(): string {
+    return "对话历史已清空。";
+  },
+};

demo/commands/compact.ts

@@ -0,0 +1,13 @@
+/**
+ * commands/compact.ts - /compact 命令
+ *
+ * 对应真实 Claude Code 的上下文压缩功能。
+ * 当对话历史过长时，用 AI 总结之前的对话，减少 token 使用。
+ */
+export const compactCommand = {
+  name: "compact",
+  description: "压缩对话上下文",
+  execute(): string {
+    return "上下文压缩完成。";
+  },
+};

demo/commands/help.ts

@@ -0,0 +1,16 @@
+/**
+ * commands/help.ts - /help 命令
+ */
+export const helpCommand = {
+  name: "help",
+  description: "显示帮助信息",
+  execute(): string {
+    return `mini-claude 可用命令:
+  /help     — 显示此帮助信息
+  /clear    — 清空对话历史
+  /compact  — 压缩对话上下文
+  /exit     — 退出程序
+
+可用工具: Echo, Read, Write, Edit, Bash, Grep, Glob`;
+  },
+};

demo/commands/index.ts

@@ -0,0 +1,43 @@
+/**
+ * commands/index.ts - 命令注册表
+ *
+ * 对应真实 Claude Code: src/commands.ts
+ * 管理所有斜杠命令的注册和查找。
+ */
+
+import { helpCommand } from "./help.js";
+import { clearCommand } from "./clear.js";
+import { compactCommand } from "./compact.js";
+
+export interface SlashCommand {
+  name: string;
+  description: string;
+  execute(args?: string): string;
+}
+
+export const commands: SlashCommand[] = [
+  helpCommand,
+  clearCommand,
+  compactCommand,
+];
+
+export function findCommand(name: string): SlashCommand | undefined {
+  return commands.find((c) => c.name === name);
+}
+
+/**
+ * 检查输入是否为斜杠命令，如果是则执行
+ * @returns 命令输出，或 null 表示不是命令
+ */
+export function tryExecuteCommand(input: string): string | null {
+  if (!input.startsWith("/")) return null;
+
+  const parts = input.slice(1).split(/\s+/);
+  const cmdName = parts[0];
+  const args = parts.slice(1).join(" ");
+
+  const cmd = findCommand(cmdName);
+  if (!cmd) return `未知命令: /${cmdName}。输入 /help 查看可用命令。`;
+
+  return cmd.execute(args);
+}

demo/components/App.tsx

@@ -7,8 +7,15 @@
 import React from "react";
 import { Box, Text } from "ink";
 import { REPL } from "../screens/REPL.js";
+import type { PermissionMode } from "../types/index.js";
 
-export function App() {
+interface AppProps {
+  model?: string;
+  maxTokens?: number;
+  permissionMode?: PermissionMode;
+}
+
+export function App({ model, maxTokens, permissionMode }: AppProps) {
   if (!process.env.ANTHROPIC_API_KEY) {
     return (
       <Box flexDirection="column" padding={1}>
@@ -19,5 +26,5 @@ export function App() {
     );
   }
 
-  return <REPL />;
+  return <REPL model={model} maxTokens={maxTokens} permissionMode={permissionMode} />;
 }

demo/package.json

@@ -5,11 +5,13 @@
   "type": "module",
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "start": "bun run repl.tsx",
-    "demo": "bun run main.ts"
+    "start": "bun run cli.ts",
+    "demo": "bun run main.ts",
+    "repl": "bun run repl.tsx"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.52.0",
+    "commander": "^14.0.3",
     "ink": "^6.8.0",
     "react": "^19.2.4"
   },

demo/screens/REPL.tsx

@@ -12,17 +12,29 @@ import { query } from "../query.js";
 import { allTools } from "../tools.js";
 import { createPermissionContext, createCheckPermissionFn } from "../utils/permissions.js";
 import { DEFAULT_MODEL } from "../types/index.js";
-import type { Message } from "../types/index.js";
+import type { Message, PermissionMode } from "../types/index.js";
+import { tryExecuteCommand } from "../commands/index.js";
+import { compactMessages } from "../services/compact/compact.js";
+
+interface REPLProps {
+  model?: string;
+  maxTokens?: number;
+  permissionMode?: PermissionMode;
+}
 
-export function REPL() {
+export function REPL({ model: modelProp, maxTokens: maxTokensProp, permissionMode: permModeProp }: REPLProps = {}) {
   const { exit } = useApp();
   const [messages, setMessages] = useState<Message[]>([]);
   const [input, setInput] = useState("");
   const [isLoading, setIsLoading] = useState(false);
   const [streamText, setStreamText] = useState("");
   const [tokenUsage, setTokenUsage] = useState({ input: 0, output: 0 });
 
-  const permCtx = createPermissionContext("auto");
+  const activeModel = modelProp ?? DEFAULT_MODEL;
+  const activeMaxTokens = maxTokensProp ?? 4096;
+  const activePermMode = permModeProp ?? "auto";
+
+  const permCtx = createPermissionContext(activePermMode);
   const checkPerm = createCheckPermissionFn(permCtx);
 
   const handleSubmit = useCallback(async (value: string) => {
@@ -35,14 +47,32 @@ export function REPL() {
       return;
     }
 
+    // 检查斜杠命令
+    const cmdResult = tryExecuteCommand(trimmed);
+    if (cmdResult !== null) {
+      if (trimmed === "/clear") {
+        setMessages([]);
+      } else if (trimmed === "/compact") {
+        setMessages((prev) => compactMessages(prev));
+      }
+      // 将命令结果作为系统消息显示
+      setMessages((prev) => [...prev, {
+        type: "system" as const,
+        subtype: "local_command" as const,
+        message: cmdResult,
+      }]);
+      setInput("");
+      return;
+    }
+
     setInput("");
     setIsLoading(true);
     setStreamText("");
 
     try {
       const result = await query(trimmed, [...messages], {
-        model: DEFAULT_MODEL,
-        maxTokens: 4096,
+        model: activeModel,
+        maxTokens: activeMaxTokens,
         checkPermission: checkPerm,
         onText: (text) => {
           setStreamText((prev) => prev + text);
@@ -74,7 +104,7 @@ export function REPL() {
       {/* Header */}
       <Box marginBottom={1}>
         <Text bold color="cyan">mini-claude</Text>
-        <Text dimColor> | {DEFAULT_MODEL} | {allTools.length} tools | tokens: {tokenUsage.input}↑ {tokenUsage.output}↓</Text>
+        <Text dimColor> | {activeModel} | {allTools.length} tools | tokens: {tokenUsage.input}↑ {tokenUsage.output}↓</Text>
       </Box>
 
       {/* Message History */}

demo/services/compact/compact.ts

@@ -0,0 +1,50 @@
+/**
+ * services/compact/compact.ts - 上下文压缩
+ *
+ * 对应真实 Claude Code 的上下文压缩功能。
+ * 当对话历史超过 token 限制时，用 AI 总结历史对话。
+ *
+ * 简化版：用截断替代 AI 总结（真实版本调用 API 做总结）。
+ */
+
+import type { Message, SystemMessage } from "../../types/index.js";
+
+/**
+ * 压缩消息历史
+ *
+ * 策略：保留最近 N 条消息，之前的用摘要替代。
+ * 真实 Claude Code 会调用 API 生成摘要。
+ */
+export function compactMessages(
+  messages: Message[],
+  keepRecent: number = 6
+): Message[] {
+  if (messages.length <= keepRecent) return messages;
+
+  const removed = messages.length - keepRecent;
+  const summary: SystemMessage = {
+    type: "system",
+    subtype: "compact_boundary",
+    message: `[上下文已压缩：省略了前 ${removed} 条消息]`,
+  };
+
+  return [summary, ...messages.slice(-keepRecent)];
+}
+
+/**
+ * 估算消息的 token 数（粗略）
+ * 真实 Claude Code 使用 tiktoken 精确计算
+ */
+export function estimateTokens(messages: Message[]): number {
+  let chars = 0;
+  for (const msg of messages) {
+    if (msg.type === "user") {
+      const content = msg.message.content;
+      if (typeof content === "string") chars += content.length;
+      else chars += JSON.stringify(content).length;
+    } else if (msg.type === "assistant") {
+      chars += JSON.stringify(msg.message.content).length;
+    }
+  }
+  return Math.ceil(chars / 4); // 粗略估算：4 字符 ≈ 1 token
+}

demo/utils/config.ts

@@ -0,0 +1,49 @@
+/**
+ * utils/config.ts - 配置加载
+ *
+ * 从多个来源加载配置（优先级从高到低）：
+ * 1. CLI 参数
+ * 2. 环境变量
+ * 3. ~/.mini-claude/config.json
+ * 4. 默认值
+ */
+
+import type { AppConfig } from "../types/index.js";
+import { DEFAULT_CONFIG } from "../types/index.js";
+import { existsSync } from "fs";
+import { join } from "path";
+
+const CONFIG_PATH = join(process.env.HOME ?? ".", ".mini-claude", "config.json");
+
+/**
+ * 加载配置文件
+ */
+export async function loadConfigFile(): Promise<Partial<AppConfig>> {
+  try {
+    if (!existsSync(CONFIG_PATH)) return {};
+    const file = Bun.file(CONFIG_PATH);
+    return JSON.parse(await file.text());
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 合并配置
+ */
+export function mergeConfig(
+  cliOptions: Partial<AppConfig>,
+  fileConfig: Partial<AppConfig>
+): AppConfig {
+  return {
+    apiKey: cliOptions.apiKey
+      ?? process.env.ANTHROPIC_API_KEY
+      ?? fileConfig.apiKey
+      ?? "",
+    model: cliOptions.model ?? fileConfig.model ?? DEFAULT_CONFIG.model,
+    maxTokens: cliOptions.maxTokens ?? fileConfig.maxTokens ?? DEFAULT_CONFIG.maxTokens,
+    permissionMode: cliOptions.permissionMode ?? fileConfig.permissionMode ?? DEFAULT_CONFIG.permissionMode,
+    cwd: cliOptions.cwd ?? DEFAULT_CONFIG.cwd,
+    systemPrompt: cliOptions.systemPrompt ?? fileConfig.systemPrompt,
+  };
+}