mkdocs.yml

site_name: Claude Code 源码导读手册
site_description: A public-facing source guide for understanding Claude Code internals
site_url: https://t0ugh.github.io/claude-code-source-guide/
repo_url: https://github.com/T0UGH/claude-code-source-guide
repo_name: T0UGH/claude-code-source-guide

docs_dir: docs
site_dir: site

use_directory_urls: true

theme:
  name: material
  language: zh
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.sections
    - navigation.expand
    - navigation.top
    - navigation.footer
    - toc.follow
    - search.suggest
    - search.highlight
    - content.code.copy
  palette:
    - scheme: default
      primary: white
      accent: blue
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式
    - scheme: slate
      primary: black
      accent: blue
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式

markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - tables
  - toc:
      permalink: true
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true

exclude_docs: |
  guidebook/README.md
  guidebook/volume-2/README.md
  guidebook/volume-3/README.md
  guidebook/volume-4/README.md
  guidebook/volume-5/README.md
  guidebook/volume-6/README.md
  notes/*
  superpowers/*
  guidebook/00-mapping-table-v2.md
  guidebook/01-volume-one-runtime-foundation.md

validation:
  omitted_files: ignore
  absolute_links: warn
  unrecognized_links: warn

extra_css:
  - stylesheets/mermaid.css

extra_javascript:
  - https://unpkg.com/mermaid@10/dist/mermaid.min.js
  - javascripts/mermaid-init.js

nav:
  - 首页: index.md
  - 开始阅读｜Guidebook v2 总览: guidebookv2/README.md
  - 卷一｜Claude Code 系统全景导论:
      - 导读: guidebookv2/volume-1/index.md
      - 01 Claude Code 到底是什么系统: guidebookv2/volume-1/01-claude-code-what-system-is-this.md
      - 02 Claude Code 由哪些核心对象组成: guidebookv2/volume-1/02-what-are-the-core-objects.md
      - 03 一次请求是怎么跑成一次 Agent Turn 的: guidebookv2/volume-1/03-how-a-request-becomes-an-agent-turn.md
      - 04 Claude Code 怎么把模型意图落成执行能力: guidebookv2/volume-1/04-how-intent-becomes-execution.md
      - 05 Claude Code 怎么维持上下文、状态与持续工作: guidebookv2/volume-1/05-how-claude-code-maintains-context-state-and-continuity.md
      - 06 Claude Code 怎么长出更多能力: guidebookv2/volume-1/06-how-claude-code-grows-new-capabilities.md
  - 卷二｜一次 Agent Turn 怎么跑起来:
      - 导读: guidebookv2/volume-2/index.md
      - 01 一次请求怎么进入 Claude Code 的主循环: guidebookv2/volume-2/01-how-a-request-enters-the-main-loop.md
      - 02 用户输入在进入运行时之前经历了什么: guidebookv2/volume-2/02-what-happens-before-user-input-enters-runtime.md
      - 03 请求是怎么进入 QueryEngine 的: guidebookv2/volume-2/03-how-a-request-enters-queryengine.md
      - 04 当前 query 是怎么被组织起来的: guidebookv2/volume-2/04-how-the-current-query-is-organized.md
      - 05 系统怎么决定这一轮要不要调用能力: guidebookv2/volume-2/05-how-the-system-decides-to-act.md
      - 06 结果怎么重新回到当前 turn: guidebookv2/volume-2/06-how-results-return-to-the-current-turn.md
      - 07 一轮 Agent Turn 什么时候继续，什么时候收口: guidebookv2/volume-2/07-when-an-agent-turn-continues-or-stops.md
      - 08 把整条主循环重新压成一张稳定运行图: guidebookv2/volume-2/08-stable-main-loop-map.md
  - 卷三｜工具系统怎么把模型意图落成执行:
      - 导读: guidebookv2/volume-3/index.md
      - 01 为什么模型意图不能直接变成现实动作: guidebookv2/volume-3/01-why-model-intent-cannot-directly-become-real-world-action.md
      - 02 tool execution 主线总览: guidebookv2/volume-3/02-tool-execution-mainline-overview.md
      - 03 为什么 tool 是正式运行时执行接口: guidebookv2/volume-3/03-why-tool-is-the-formal-runtime-execution-interface.md
      - 04 orchestration 怎么接住一次 tool use: guidebookv2/volume-3/04-how-orchestration-handles-a-tool-use.md
      - 05 为什么 BashTool 像通用执行器: guidebookv2/volume-3/05-why-bashtool-feels-like-the-general-executor.md
      - 06 FileReadTool 怎么把真实材料带进当前判断: guidebookv2/volume-3/06-how-filereadtool-brings-real-material-into-current-judgment.md
      - 07 FileEdit / FileWrite 怎么把判断写回文件: guidebookv2/volume-3/07-how-fileedit-and-filewrite-apply-judgment-back-to-files.md
      - 08 GrepTool 怎么在真实材料里找东西: guidebookv2/volume-3/08-how-greptool-finds-things-in-real-material.md
      - 09 ToolSearchTool 怎么找该用什么工具: guidebookv2/volume-3/09-how-toolsearchtool-finds-what-tool-to-use.md
      - 10 为什么执行层不只处理本地工具: guidebookv2/volume-3/10-why-execution-layer-does-not-only-handle-local-tools.md
      - 11 把执行层重新压成一张稳定运行图: guidebookv2/volume-3/11-stable-execution-layer-map.md
      - 12 为什么 Claude Code 的执行层必须先长出权限管线: guidebookv2/volume-3/12-why-execution-layer-must-grow-a-permission-pipeline-first.md
      - 13 permission decision 是怎样接到 tool execution 之前的: guidebookv2/volume-3/13-how-permission-decision-connects-before-tool-execution.md
      - 14 为什么 allow / deny / ask 不是 UI 选项，而是 runtime 决策面: guidebookv2/volume-3/14-why-allow-deny-ask-are-a-runtime-decision-surface.md
      - 15 为什么权限系统最后收口成执行边界: guidebookv2/volume-3/15-why-the-permission-system-finally-collapses-into-an-execution-boundary.md
  - 卷四｜上下文与状态怎么维持系统持续工作:
      - 导读: guidebookv2/volume-4/index.md
      - 01 为什么 Claude Code 不是一轮一重置系统: guidebookv2/volume-4/01-why-claude-code-is-not-a-one-turn-reset-system.md
      - 02 为什么 messages、context、system prompt、transcript、session 不是一回事: guidebookv2/volume-4/02-why-messages-context-system-prompt-transcript-session-are-not-the-same.md
      - 03 当前可工作上下文是怎么被组出来的: guidebookv2/volume-4/03-how-the-current-workable-context-is-assembled.md
      - 04 为什么系统不能一直把整段历史原样发出去: guidebookv2/volume-4/04-why-the-system-cannot-keep-sending-the-entire-history.md
      - 05 collapse / compaction / projection / restore 总图: guidebookv2/volume-4/05-overall-map-of-collapse-compaction-projection-restore.md
      - 06 projection 与 collapse 管的是可工作视图，不是 transcript 本身: guidebookv2/volume-4/06-projection-and-collapse-govern-the-workable-view-not-the-transcript-itself.md
      - 07 compact / compaction 是主动减载机制: guidebookv2/volume-4/07-compact-and-compaction-as-the-active-load-shedding-mechanism.md
      - 08 restore / session recovery 怎么让系统恢复工作: guidebookv2/volume-4/08-restore-and-session-recovery-how-the-system-resumes-work.md
      - 09 为什么 Claude Code 的 memory 不是 context 的别名: guidebookv2/volume-4/09-why-memory-is-not-just-another-name-for-context.md
      - 10 working memory / transcript / long-term memory 为什么不是一回事: guidebookv2/volume-4/10-why-working-memory-transcript-and-long-term-memory-are-not-the-same.md
      - 11 MEMORY.md / memdir 为什么不是普通文件，而是正式长期记忆层: guidebookv2/volume-4/11-why-memory-md-and-memdir-are-a-formal-long-term-memory-layer.md
      - 12 为什么自动记忆提取不是小功能，而是系统持续性的后台 runtime: guidebookv2/volume-4/12-why-automatic-memory-extraction-is-a-background-runtime-for-system-continuity.md
      - 13 长期记忆是按什么边界回注到新 runtime 的: guidebookv2/volume-4/13-how-long-term-memory-is-injected-back-into-a-new-runtime.md
  - 卷五｜外部扩展与多代理能力:
      - 导读: guidebookv2/volume-5/index.md
      - 01 为什么复杂场景会逼 Claude Code 长出扩展层: guidebookv2/volume-5/01-why-complex-scenarios-force-claude-code-to-grow-an-extension-layer.md
      - 02 为什么 Claude Code 选择把扩展权交给用户: guidebookv2/volume-5/02-why-claude-code-chooses-to-hand-extension-power-to-users.md
      - 03 skills / MCP / agents / subagents / hooks / plugins 怎么进入 Claude Code: guidebookv2/volume-5/03-how-skills-mcp-agents-subagents-hooks-and-plugins-enter-claude-code.md
      - 04 为什么 skill 不只是长 prompt: guidebookv2/volume-5/04-why-skills-are-more-than-long-prompts.md
      - 05 skill 怎么把用户体验、工作流和角色带进 Claude Code: guidebookv2/volume-5/05-how-skills-bring-user-experience-workflows-and-roles-into-claude-code.md
      - 06 SkillTool 与 skills runtime 怎么接入执行链: guidebookv2/volume-5/06-how-skilltool-and-skills-runtime-enter-the-execution-chain.md
      - 07 什么样的 skill 才是好 runtime skill: guidebookv2/volume-5/07-what-makes-a-good-runtime-skill.md
      - 08 skill、tool、agent 的边界: guidebookv2/volume-5/08-boundaries-between-skill-tool-and-agent.md
      - 09 为什么 MCP 不只是更多远程工具: guidebookv2/volume-5/09-why-mcp-is-not-just-more-remote-tools.md
      - 10 Claude Code 怎么用 MCP 接外部能力与资源系统: guidebookv2/volume-5/10-how-claude-code-uses-mcp-to-connect-external-capabilities-and-resource-systems.md
      - 11 MCP 与 skills、hooks、plugins 的关系: guidebookv2/volume-5/11-how-mcp-relates-to-skills-hooks-and-plugins.md
      - 12 为什么 agent 不只是另一个工具: guidebookv2/volume-5/12-why-agent-is-not-just-another-tool.md
      - 13 Claude Code 怎么长出更多执行者: guidebookv2/volume-5/13-how-claude-code-grows-more-executors.md
      - 14 为什么 runAgent 像 agent runtime 装配线: guidebookv2/volume-5/14-why-runagent-feels-like-an-agent-runtime-assembly-line.md
      - 15 为什么主 agent 需要 spawn subagents: guidebookv2/volume-5/15-why-the-main-agent-needs-to-spawn-subagents.md
      - 16 为什么 forkSubagent 不只是启动另一个 agent: guidebookv2/volume-5/16-why-forksubagent-is-not-just-starting-another-agent.md
      - 17 主 agent 与 worker agent 的边界和信息流: guidebookv2/volume-5/17-boundaries-and-information-flow-between-main-agent-and-worker-agent.md
      - 18 为什么 hooks 不只是挂几个脚本，而是正式 runtime 机制: guidebookv2/volume-5/18-why-hooks-are-more-than-just-some-scripts.md
      - 19 hooks 在 Claude Code runtime 里扮演什么角色: guidebookv2/volume-5/19-what-role-hooks-play-in-claude-code-runtime.md
      - 20 不同 hooks 各自拦截、连接和修改什么: guidebookv2/volume-5/20-what-different-hooks-intercept-connect-and-modify-in-claude-code.md
      - 21 为什么有了 skills、MCP、hooks 之后仍然需要 plugins: guidebookv2/volume-5/21-why-plugins-are-still-needed-after-skills-mcp-and-hooks.md
      - 22 plugins 相对其他扩展对象占在哪一层: guidebookv2/volume-5/22-what-layer-plugins-occupy-relative-to-other-extension-objects.md
      - 23 为什么 plugins 代表了更完整的打包、分发与复用形态: guidebookv2/volume-5/23-why-plugins-represent-a-more-complete-form-of-packaging-distribution-and-reuse.md
      - 24 为什么这些扩展对象最终收束成平台层: guidebookv2/volume-5/24-why-these-extension-objects-converge-into-a-platform-layer.md
  - 卷六｜多 agent 协作运行时:
      - 导读: guidebookv2/volume-6/index.md
      - 01 为什么 Claude Code multi-agent 是协作运行时: guidebookv2/volume-6/01-why-claude-code-multi-agent-is-a-collaboration-runtime.md
      - 02 team 与 teammate runtime 在 Claude Code 里处在哪: guidebookv2/volume-6/02-where-team-and-teammate-runtime-sit-in-claude-code.md
      - 03 teams 是怎么被创建、注册与清理的: guidebookv2/volume-6/03-how-teams-are-created-registered-and-cleaned-up.md
      - 04 InProcessTeammate runtime 是怎么真正跑起来的: guidebookv2/volume-6/04-how-inprocess-teammate-runtime-actually-runs.md
      - 05 mailbox / idle / shutdown 怎么把闭环合上: guidebookv2/volume-6/05-how-mailbox-idle-and-shutdown-close-the-loop.md
      - 06 local、remote、teammate task 的边界: guidebookv2/volume-6/06-boundaries-between-local-remote-and-teammate-tasks.md
      - 07 为什么 Claude Code team 本质上是一种 swarm: guidebookv2/volume-6/07-why-claude-code-team-is-a-swarm.md
  - 卷七｜命令、工作流与产品层整合:
      - 导读: guidebookv2/volume-7/index.md
      - 01 为什么 Claude Code 需要控制层: guidebookv2/volume-7/01-why-claude-code-needs-a-control-layer.md
      - 02 为什么 slash / prompt commands 不只是快捷方式: guidebookv2/volume-7/02-why-slash-and-prompt-commands-are-not-just-shortcuts.md
      - 03 命令入口是怎样接进 runtime 的: guidebookv2/volume-7/03-how-command-entry-enters-the-runtime.md
      - 04 为什么 frontmatter 与 command interface 是运行时接口: guidebookv2/volume-7/04-why-frontmatter-and-command-interface-are-runtime-interfaces.md
      - 05 工作流控制层是怎样在 Claude Code 里成立的: guidebookv2/volume-7/05-how-the-workflow-control-layer-forms-in-claude-code.md
      - 06 为什么 command、tool、skill、agent 的边界要在卷七收口: guidebookv2/volume-7/06-why-command-tool-skill-and-agent-boundaries-close-in-volume-7.md
      - 07 为什么 Claude Code 的产品形态本质上是 runtime 被包装给用户的方式: guidebookv2/volume-7/07-why-claude-codes-product-form-is-runtime-packaged-for-users.md
      - 08 为什么用户入口、运行时接口和工作流控制会收成今天这个产品: guidebookv2/volume-7/08-why-user-entry-runtime-interface-and-workflow-control-become-todays-product.md