📦 可运行 Demo 集合¶
21 个真正能跑的 mini-CC 实现。每个都从 CC 真实源码（3000+ 行）提炼到 ~80-400 行， 保留核心机制、去掉工程噪音，让你能 读懂 + 跑通 + 改写。
🎯 为什么做这个？¶
CC 源码总规模 1902 文件 / 50W 行，单看 claude.ts 一个文件就 3419 行。
新手直接读会劝退，老手想"快速验证理解"也找不到入口。
本目录的 21 个 demo 解决这个： - 每个 demo 对应 CC 一个核心子系统 - 每个 demo 都是独立 npm package（自带 mock，不依赖 API key） - 每个 demo 都经过实测（4~15 场景全过） - 每个 demo 都有详尽 README（核心设计 4 件套 + 真实代码对照 + 进阶练习）
📊 21 Demo 概览（按主题分组）¶
🟦 解析 / Parsing（3 demos）¶
| Demo | 真实代码 | 行数 | 简化比 | 跑通场景 |
|---|---|---|---|---|
| mini-bash-parser | bashParser.ts 4436 |
~500 | 9× | simple / pipe / if-else / for-in |
| mini-bash-ast | bash/ast.ts 2679 |
~380 | 7× | 6 个 query（find / 谓词 / visitor） |
| mini-yaml-parser | 0（CC 用 yaml 库） | ~360 | 自实现 | mapping / sequence / 标量 / 注释 / 嵌套 |
🟥 安全 / 权限（3 demos）¶
| Demo | 真实代码 | 行数 | 简化比 | 跑通场景 |
|---|---|---|---|---|
| mini-permission-system | bashPermissions.ts 2621 |
~410 | 6× | 25 测试（高危/中危/白名单/默认/边界） |
| mini-bash-security | bashSecurity.ts 2592 |
~310 | 8× | 12 测试（32 威胁模式 + 5 严重级） |
| mini-mcp-auth | mcp/auth.ts 2465 |
~500 | 5× | 4 阶段 OAuth + 3 错误场景（PKCE/CSRF/expired） |
🟨 状态 / 缓存（4 demos）¶
| Demo | 真实代码 | 行数 | 简化比 | 跑通场景 |
|---|---|---|---|---|
| mini-state-store | AppStateStore.ts 569 |
~310 | 2× | 5 测试（基本/订阅/Selector/same-ref/React 集成） |
| mini-prompt-cache | 散落 ~800 | ~430 | 2× | 6 测试（miss+write/full hit/prefix hit/TTL/持久化） |
| mini-session-storage | sessionStorage.ts 5105 |
~470 | 11× | 8 测试（基本/持久化/reload/TTL/事务/删除/并发/close） |
| mini-context-compaction | compact/ 12 文件 ~5000 |
~380 | 13× | 5 测试（不触发/drop-middle/keep-first-last/summarize/阈值对比） |
🟩 工具 / 扩展（3 demos）¶
| Demo | 真实代码 | 行数 | 简化比 | 跑通场景 |
|---|---|---|---|---|
| mini-marketplace | marketplaceManager.ts 2643 |
~490 | 5× | 6 测试（list/install/指定版本/peer/core 兼容/完整性） |
| mini-feature-flags | esbuild define 插件 | ~280 | 1× | 3 flavors DCE（default/enterprise/oss） |
| mini-error-codes | 28+ Error class | ~370 | 5× | 27 codes + 5 测试（list/format/retry/统计/helpers） |
🟪 协议 / 数据流（3 demos）¶
| Demo | 真实代码 | 行数 | 简化比 | 跑通场景 |
|---|---|---|---|---|
| mini-json-rpc | MCP 用 | ~540 | 通用库 | 7 测试（request/notification/method-not-found/invalid-params/parse-error/batch/concurrent） |
| mini-attachment-resolver | attachments.ts 3997 |
~370 | 11× | 5 测试（4 prefix/失败隔离/超时/tokenize/空） |
| mini-async-stream | 通用模式 | ~310 | 自实现 | 4 测试（基本消费/背压/abort/多 consumer） |
🟫 CLI / 启动（2 demos）¶
| Demo | 真实代码 | 行数 | 简化比 | 跑通场景 |
|---|---|---|---|---|
| mini-cli | main.tsx 4683 |
~470 | 10× | 4 命令 20+ flags + 自动 --help |
| mini-repl | REPL.tsx 5005 |
~430 | 12× | 5 测试（基本/history/completion/multi-line/集成） |
🏁 早期 3 demos（agent loop / 通信 / 扩展）¶
| Demo | 真实代码 | 行数 | 简化比 | 跑通场景 |
|---|---|---|---|---|
| mini-query-engine | claude.ts 3419 |
~740 | 5× | plain / echo / calc / 5xx retry / abort |
| mini-mcp-server | mcp/client.ts 3348 |
~710 | 5× | init / list / 4 tool calls / 2 errors |
| mini-plugin | pluginLoader.ts 3302 |
~620 | 5× | load / discover / 4 security tests |
合计 21 demos / ~8,500 行 / 总跑通测试场景 ~100+
🗺️ 选哪个 Demo 开始？¶
按"你想搞懂什么"分类： | 你想... | 推荐 | 理由 | |---|---|---| | 理解 Claude API 调用流 | mini-query-engine | 最核心的 agent loop 抽象 | | 写一个 MCP server 给 CC 用 | mini-mcp-server | 完整 JSON-RPC + 工具系统 | | 写一个 CC plugin | mini-plugin | 最小可运行 plugin loader | | 看 streaming 怎么实现 | mini-query-engine | AsyncGenerator 范式 | | 看 RPC 协议怎么工作 | mini-json-rpc | stdio + JSON-RPC 完整 | | 看 path traversal 怎么防 | mini-plugin / mini-bash-security | 4+12 攻击场景实测 | | 理解 OAuth 2.0 + PKCE | mini-mcp-auth | 4 阶段 + 3 错误场景 | | 写 state 管理 | mini-state-store | 5 行 store + React 集成 | | 写 cache | mini-prompt-cache | prefix hash + TTL | | 写 CLI 工具 | mini-cli | argv + subcommand + help | | 写 REPL | mini-repl | readline + history + completion |
🚀 怎么跑？（21 demos 跑 1 个示范）¶
每个 demo 都是独立 npm package：
# 例：mini-query-engine
cd learn_doc/demos/mini-query-engine
npm install
npm start
# 或传参数
node dist/src/cli.js "echo: hello"
node dist/src/cli.js "calc: 1 + 2 * 3"
📚 与手册其他部分的关系¶
demos/ ← 你在这（21 demos）
├── mini-query-engine/ ← 配 topics/deep-dive-claude-api.md
├── mini-mcp-server/ ← 配 topics/deep-dive-mcp-client.md
├── mini-plugin/ ← 配 topics/deep-dive-plugin-loader.md
├── mini-bash-parser/ ← 配 topics/deep-dive-bash-parser.md
├── mini-bash-ast/ ← 配 topics/deep-dive-bash-ast.md
├── mini-permission-system/ ← 配 topics/deep-dive-bash-permissions.md
├── mini-bash-security/ ← 配 topics/deep-dive-bash-security.md
├── mini-mcp-auth/ ← 配 topics/deep-dive-mcp-auth.md
├── mini-state-store/ ← 配 phase-03-state.md
├── mini-prompt-cache/ ← 配 topics/prompt-cache.md
├── mini-session-storage/ ← 配 topics/deep-dive-session-storage.md
├── mini-context-compaction/ ← 配 topics/context-compaction.md
├── mini-marketplace/ ← 配 topics/deep-dive-marketplace.md
├── mini-feature-flags/ ← 配 topics/dce-feature-flags.md
├── mini-error-codes/ ← 配 topics/error-codes.md
├── mini-json-rpc/ ← 配 topics/mcp-protocol-deep-dive.md
├── mini-attachment-resolver/ ← 配 topics/deep-dive-attachments.md
├── mini-async-stream/ ← 配 topics/async-generator-pattern.md
├── mini-cli/ ← 配 topics/deep-dive-main.md
└── mini-repl/ ← 配 topics/deep-dive-repl-screen.md
🎓 推荐学习路径¶
🟢 30 分钟（3 个早期 demo + 1 个新 demo）¶
跑 4 个 demo 看看效果： - mini-query-engine — agent loop - mini-mcp-server — 协议 - mini-plugin — 扩展 - mini-bash-parser — 解析器入门
🟡 2 小时（按主题挑 1 个深读）¶
- 读对应 README 的"核心设计 4 件套"节
- 改 1 个进阶练习
- 看真实 CC 对应 deep-dive 文档
🔴 1 周（21 demos 全部跑通）¶
- 每天 3-4 个 demo，每个 30 分钟
- 每个 demo 加 1 个自己的测试
- 提 PR 贡献新 demo（fork 一个感兴趣的 CC 模块）
❓ 常见问题¶
Q: 这些 demo 是 CC 官方代码吗？ A: 不是。是按 CC 源码设计思路重新实现的最小版本。功能等价但实现大幅简化。
Q: demo 能在 CC 真用吗？ A: 不能直接用。但代码设计接近真实 CC 的内部模块，理解了 demo 就能快速读懂真实代码。
Q: 为什么不用 CC 自己的 package.json / lock 文件？
A: 本仓库不包含 src/ 的依赖（详见 README.md）。demos 自己定义 package.json。
Q: 跑 demo 需要 API key 吗？ A: 不需要。每个 demo 都自带 mock（MockApiClient / MockTransport / 内存 registry），按字符串前缀模拟所有行为。
Q: 真实 CC 怎么读？ A: 看完 demo 后，去 topics/deep-dive-*.md 找对应模块的 500 行拆解，再回看 3000+ 行真实代码就有抓手了。
Q: 21 个 demo 都做完要多久？ A: 单 demo 30min - 2h。21 个全做 = ~20 小时（分 1-2 周可完成）。
🔗 相关阅读¶
- START-HERE.md —— 新读者路径图
- topics/ —— 17 篇 deep-dive + 15 跨阶段专题
- walkthrough/ —— 8 个练习答案
- PR-IDEAS.md —— 延伸研究方向