跳转至

FAQ（常见问题）

Q&A 格式，覆盖阅读路径、术语、本地预览、许可、源码等常见疑问。 找答案：按 Ctrl+F 搜关键词，或用站点右上角搜索框。

📖 关于本手册

Q1：本手册和 Claude Code 商业产品是什么关系？

A：本手册是学习材料，不是 Claude Code 的官方产品。所讲解的 src/、vendor/ 源码版权归 Anthropic。本手册不分发、不销售、不替代 Claude Code，仅作学习与研究。

Q2：可以"安装运行"吗？

A：不能。讲解所基于的源码没有 package.json / 锁文件 / node_modules，只能纯读代码。要使用 Claude Code 请去 Claude Code 官网。

Q3：本手册是"反推商业产品"吗？

A：不是。本手册是"从源码学习"性质，目的是理解工程实现与设计思路，不是反推或复刻商业产品功能。

Q4：会持续更新吗？

A：会，但节奏不一定。有新内容时补充，平时不定期更新。最新进展见 blog/ 目录。

📚 关于阅读

Q5：我是新手，从哪开始？

A：按这个顺序： 1. README.md（5 min） 2. 00-index.md（5 min） 3. phase-01-entry.md（10 min） 4. phase-02-repl.md（20 min） 5. 按需深挖

Q6：30 分钟能看完吗？

A：能。看 00-index.md + phase-01-entry.md + 几个 deep-dive 摘要。

Q7：5 小时能过完主线吗？

A：能。看完 7 阶段文档（phase-01 到 phase-07），约 5-8 小时。

Q8：想深入某个模块怎么办？

A：去 topics/ 找对应专题，再看 deep-dive-X.md（17 篇源码深度拆解）。

Q9：找不到想看的概念怎么办？

A：查 glossary.md（150+ 词条）或 glossary_addendum.md（50+ 补充）。

Q10：术语看不懂？

A：每个术语首次出现时附有简注。完整索引见 glossary.md。

Q11：英文术语为什么没翻译？

A：保留英文以保持与上游代码 / 文档 / 社区讨论的一致性。例如 feature flag 不译为"特性旗标"（虽然有译，但括号附英文）。

Q12：图表怎么生成？

A：用 mermaid，直接写在 markdown 里。mkdocs-material 自动渲染。详见 data/ 目录。

Q13：源码引用为什么不直接给链接？

A：给的是行号 + 文件名，例如 src/main.tsx:42。手册讲解的就是源码本身，用文件路径 + 行号定位最快。

🛠️ 本地预览

Q14：本地怎么预览 mkdocs 站点？

A： 

python3 -m venv .mkdocs-venv
. .mkdocs-venv/bin/activate
pip install -r requirements-docs.txt
mkdocs serve
# 浏览器打开 http://127.0.0.1:8000/

Q15：strict build 报错怎么办？

A： 

mkdocs build --clean --strict 2>&1 | tail -30
看具体 warning 修。最常见：anchor 引用打错、跨目录链接、文件未在 nav。

Q16：pip install 失败（SSL EOF）？

A：用国内镜像： 

pip install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements-docs.txt
或跑 ./deploy-check.sh（自动 fallback 到镜像）。

Q17：mkdocs 启动慢？

A：mkdocs 1.6 + Material 9.5 启动约 3-5 秒。如果 10 秒+ 看是否有 plugin 报错。

🔒 关于引用与许可

Q18：可以引用本手册的图表吗？

A：learn_doc/ + docs/ 内容按 CC BY-SA 4.0 许可，可以引用，请标注出处。src/ 内容不可以（Anthropic 专有）。

Q19：可以商业使用本手册的文档吗？

A：可以。CC BY-SA 4.0 允许商业使用，但必须： 1. 标注作者和出处 2. 衍生作品也必须用 CC BY-SA 4.0

Q20：可以重新打包为"Claude Code 替代品"吗？

A：不可以。src/ 是 Anthropic 专有，重新打包违反 Anthropic 版权。

Q21：开源项目能用这里的代码吗？

A：不推荐开源项目使用 src/ 内容（Anthropic 专有）。learn_doc/ 文档内容可以（CC BY-SA）。

📊 关于数字

Q22：源码真实规模？

A：1902 个 .ts/.tsx 文件 / 512,664 行 / 50+ 子目录 / 43 工具 / 100+ 命令 / 85 hooks / 95+ feature flag / 400+ env var。

Q23：本手册文档规模？

A：~74,000 行 markdown / 180+ 个文档 / 260+ 个自动化测试（vitest 全过）。

Q24：哪些是源码里最大的文件？

A：详见 reference/largest-files.md。

🔍 关于源码

Q25：哪个文件最值得看？

A：按"价值/行数"： - ⭐⭐⭐⭐⭐ src/main.tsx（4683 行）—— 主入口 - ⭐⭐⭐⭐⭐ src/screens/REPL.tsx（5005 行）—— 主屏幕 - ⭐⭐⭐⭐ src/services/mcp/client.ts（3348 行）—— MCP - ⭐⭐⭐⭐ src/utils/bash/bashParser.ts（4436 行）—— bash 解析 - ⭐⭐⭐⭐ src/utils/attachments.ts（3997 行）—— 附件

详见 reference/largest-files.md。

Q26：哪些是"商业版独有"功能？

A：所有 DCE-gated 代码（feature('X') 检查）。详见 topics/dce-feature-flags.md 和 feature-flags-all.md。

Q27：商业版 (commercial) vs 内部版 (ant) vs 公开版 (external) 区别？

A：编译期通过 bun:bundle 的 "external" === 'ant' 字面量字符串检查切换。ANT 内部版 = true，其他都 = false。这是 DCE 的实现机制。详见 topics/dce-deep-dive.md。

Q28：怎么知道某段代码是商业版还是公开版？

A：搜 feature('X') 包裹的代码块。如果在 if (feature('X')) { ... } 里就是 DCE-gated。详见 reference/dce-product-matrix.md。

Q29：环境变量怎么用？

A：400+ 个 env var，完整列表 env-vars-all.md。速查 reference/env-vars.md。

🆘 故障排查

Q30：mkdocs serve 报 "Address already in use"？

A：换端口 mkdocs serve -a 127.0.0.1:8765，或杀掉占用进程 lsof -i :8000。

Q31：mermaid 图渲染失败？

A：检查 mkdocs.yml 的 markdown_extensions 包含 pymdownx.superfences + mermaid 配置。

Q32：本地 build 0 warning，但换台机器 fail？

A：用锁定的 mkdocs 1.6.1 + material 9.7.6 + awesome-nav 3.3.0（见 requirements-docs.txt）。版本不一致可能不兼容，必须用锁定的版本。

Q33：站点页面 404？

A： 1. 浏览器硬刷（Cmd+Shift+R） 2. 清缓存 3. 仍 404 检查该文件是否在 mkdocs.yml 的 nav 里

🆕 找不到答案？

最后更新：2026-06-07