🎯 START-HERE.md —— 新读者路径图¶

30 秒选路径、30 分钟入门、2 小时精通、8 小时深入。这页帮你在 180+ 文档里找到最该读的那 5~8 篇，不迷路。

📋 用法¶

回答两个问题：我有多少时间？我是谁？
顺着对应路径的链接读
读完一段回这页选下一段

👤 你是谁？选你的角色¶

角色	关心的问题	优先看
🖥️ 前端 / TUI 开发者	TUI 怎么渲染？状态怎么管？打字为啥不卡？	[REPL.tsx 拆解] · [Ink 渲染] · [状态管理] · [PromptInput]
⚙️ 后端 / 全栈	agent loop 怎么跑？tool 怎么调？错误怎么恢复？	[QueryEngine 拆解] · [services/claude.ts] · [bridge 协议] · [async generator]
🧩 工具 / MCP 插件作者	怎么写 MCP server？怎么发 plugin？marketplace 怎么搭？	[MCP 协议深入] · [plugin 加载] · [MCP client] · [plugin 教程]
🔬 架构 / 学术研究	50W 行怎么摸清脉络？设计哲学是什么？	[架构演进史] · [模块依赖图] · [设计哲学] · [性能优化编年]
🛡️ 安全 / 红蓝队	bash 怎么拦？路径怎么校验？OAuth 怎么走？	[bash 安全] · [path 校验] · [MCP auth] · [鉴权工具]
🎓 学生 / 转行	第一次看 50W 行开源项目，怎么不劝退？	[怎么读 50W 行] · [方法论] · [练习答案] · [贡献指南]

不确定自己是谁？ 默认走 ⏱️ 时间路径（下一节），角色选错了大不了回这页换。

⏱️ 三条时间路径¶

🟢 30 分钟速览 ——「我想先看看是什么」¶

目标：知道 CC 是什么、规模多大、怎么组织的

#	文档	时长	重点
1	00-index.md 技术栈速览	5 min	文件数 / 行数 / 技术栈 / 顶层目录
2	00-index.md 架构骨架图	5 min	10 大子系统 + mermaid 关系图
3	phase-01-entry.md 入口层级	10 min	bin → main.tsx → 路由 → 子命令
4	topics/big-files-untold-stories.md	10 min	5 大巨型文件揭秘 + 1 句话总结

读完你能说：

"CC 是 1902 文件 / 50W 行的 Node.js TUI，主体 TypeScript + React (Ink)，有 N-API native、跨 MCP 通信、95+ feature flag 编译时门控。"

🟡 2 小时入门 ——「我想搞懂核心机制」¶

目标：理解 agent loop + 工具调用 + 状态管理 三件套

#	文档	时长	重点
1~4	30 分钟速览（上面 4 步）	30 min	—
5	phase-06-agent-loop.md	20 min	query.ts 主循环
6	topics/deep-dive-claude-api.md	30 min	services/claude.ts 3419 行
7	topics/async-generator-pattern.md	15 min	async function* 精髓（流式响应）
8	phase-03-state.md	15 min	60 行 store 极简（useSyncExternalStore）
9	topics/deep-dive-query-engine.md	10 min	1295 行的 query 主循环

读完你能画：

用户输入 → agent loop → tool call（maybe 编排）→ 结果回流 → 状态更新 → 渲染输出的完整流程图。

🔴 8 小时深入 ——「我想自己改一改」¶

目标：能看懂 main.tsx 改 prompt、能新加 tool、能写 mini MCP server

#	文档	时长	重点
1~9	2 小时入门（上面 9 步）	120 min	—
10	topics/deep-dive-main.md	40 min	main.tsx 4683 行（21 章节）
11	topics/deep-dive-repl-screen.md	40 min	REPL.tsx 5005 行（21 章节）
12	topics/mcp-protocol-deep-dive.md	30 min	MCP 协议完整（含 3 种 transport）
13	topics/deep-dive-plugin-loader.md	30 min	6 种 plugin 源 + 4 级缓存
14	topics/deep-dive-mcp-client.md	40 min	mcp/client.ts 3348 行
15	topics/deep-dive-attachments.md	30 min	17+ 附件类型 + 1s 总体超时
16	tutorials/build-mcp-server.md	20 min	手写 200 行 MCP server
17	跑 practice-tests/ ~10 道代表测试	30 min	验证理解 + 找盲点

读完你能做： - 给 CC 加个新 tool（修改 [tutorials/build-plugin.md]） - 改 prompt 模板（看 [topics/deep-dive-main.md] 的 default action） - 写 mini MCP server（[tutorials/build-mcp-server.md] + [demos/] 待做） - 调一个 feature flag 看效果（[feature-flags-all.md]）

🚀 读完路径后 → 下一步¶

你的下一步	看这里
想看更多源码拆解	topics/ —— 17 篇 deep-dive + 15 篇跨阶段专题
想练手 / 验证理解	practice-tests/ —— 79 个测试
想查具体 API / 文件	reference/ —— 6 篇速查
想看架构图 / 时序图	data/ —— 6 篇 mermaid（132 图）
想看实际案例	showcase.md —— 6 真实改造案例
遇到具体问题	faq.md —— 56 Q&A
想知道更多术语	glossary.md —— ~150 词条 + 4 套 addendum
想看研究方法论	how-to-read-500k-loc.md
想知道怎么贡献	PR-IDEAS.md —— 延伸研究方向
想看视频讲解	video-script.md —— 5/15/30 分钟脚本

🗺️ 阅读路径导航图¶

graph TD
    A[新读者进站] --> B{你有多少时间?}
    B -->|30min| C[速览]
    B -->|2h| D[入门]
    B -->|8h+| E[深入]

    C --> F[00-index + phase-1 + big-files]
    F --> G{还想深入?}
    G -->|是| D
    G -->|否| H[回头用 CC 写代码]

    D --> F
    D --> I[phase-6 + claude.ts + state + async-gen]
    I --> G

    E --> I
    E --> J[main.tsx + REPL.tsx + MCP + plugin + attachments]
    J --> K[跑 practice-tests]
    K --> L[改源码 / 写新 tool / 写 MCP server]

    style A fill:#4a90e2,color:#fff
    style H fill:#7ed321,color:#fff
    style L fill:#7ed321,color:#fff

❓ 我还是不知道从哪开始¶

1 小时能花完 → 走 🟢 30 分钟速览
1 个周末 → 走 🟡 2 小时入门
1 周 + → 走 🔴 8 小时深入
完全没头绪 → 先看 00-index.md（5 分钟），再回来选
就想知道"这仓库干嘛的" → 看 00-index.md 的「3. 规模与定位」一节

📍 关于本手册本身¶

来源：2026-03-31 源码公开事件后整理的研究笔记（非官方）
规模：180+ 文档 / ~74K 行 markdown / 280 自动化测试 / 95% 覆盖率
站点：https://cc.ccgo.top
维护：单人力，2026-06 起 v1.0
许可：CC BY-SA 4.0（手册部分）/ 详见 LICENSE