# Claude Code 核心功能组件盘点（除工具与斜杠命令之外）

> 素材来源：`claude-code/src` 源码。每项给出：是什么（小白比喻）→ 源码实现（文件:行号）→ 具体例子。

---

## 1. 插件（Plugins）

### 是什么
插件是一个"打包好的能力包"——就像 VS Code 的扩展。一个目录里可以同时装着斜杠命令、技能（SKILL.md）、subagent 定义、hooks（钩子脚本）和 MCP 服务器配置，一次安装全部到位。它解决的问题是：单个 `.claude/commands/xxx.md` 文件太零散，没法方便地分享和版本管理一整套工作流。

### 源码实现
- **插件目录结构约定**：`plugin.json` 清单 + `commands/` + `agents/` + `hooks/hooks.json`，见 `utils/plugins/pluginLoader.ts:16-28`（文件头注释）与 `createPluginFromPath()`（`pluginLoader.ts:1357`），其中 `pluginLoader.ts:1392-1398` 会并行探测 `commands/`、`agents/`、`skills/`、`output-styles/` 四个可选目录是否存在。
- **内置插件（Built-in plugins）**：随 CLI 一起发布、可在 `/plugin` 界面里开关的插件，注册在 `plugins/builtinPlugins.ts:21-32`（`registerBuiltinPlugin`），ID 形如 `{name}@builtin`（`builtinPlugins.ts:23,38`）。它们与市场插件的区别：没有文件路径（`path: 'builtin'` 哨兵值，`builtinPlugins.ts:85`），用户开关状态持久化到 settings 的 `enabledPlugins`（`builtinPlugins.ts:71-76`）。
- **市场（Marketplace）机制**：marketplace 本质上是一个 git 仓库（或 URL/NPM），内含 `marketplace.json` 目录清单。官方市场是 GitHub 仓库 `anthropics/claude-plugins-official`（`utils/plugins/officialMarketplace.ts:13-27`）。添加市场走 `addMarketplaceSource()`（`utils/plugins/marketplaceManager.ts:1782`），克隆走部分克隆（partial clone）+ 稀疏检出以省流量（`marketplaceManager.ts:803 gitClone`、`1034 reconcileSparseCheckout`）。装好的插件由 `installPluginFromMarketplace()`（`utils/plugins/pluginInstallationHelpers.ts:506`）落地，加载总入口是 `loadAllPlugins()`（`pluginLoader.ts:3096`）。
- **与内置功能的优先级**：所有来源的命令在 `commands.ts:447-470 loadAllCommands` 里合并，顺序为 bundledSkills → builtinPluginSkills → 目录技能 → workflow → pluginCommands → pluginSkills → 硬编码内置命令（`COMMANDS()`）。查找命令用 `findCommand()`（`commands.ts:688`），按数组顺序第一个匹配者胜出，所以同名下用户/插件技能排在内置硬编码命令之前。
- **UI**：`/plugin` 命令对应的界面在 `commands/plugin/`（`ManagePlugins.tsx`、`BrowseMarketplace.tsx`、`AddMarketplace.tsx` 等）。

### 例子
用户在 `/plugin marketplace add anthropics/claude-plugins-official` 后，`gitClone` 把仓库稀疏克隆到 `~/.claude/plugins/marketplaces/`，再 `/plugin install feature-dev@claude-plugins-official`；下次启动时 `createPluginFromPath` 发现其 `commands/`、`agents/`、`hooks/hooks.json`，这些命令就出现在 `/` 列表里，来源标注为 plugin。

---

## 2. 技能（Skills）

### 是什么
技能是"按需取用的说明书"。比喻：工具的说明书全塞进抽屉（系统提示）会太重，所以 Claude Code 只在抽屉上贴一页"目录"（技能名+一句话描述）；当模型决定要用某本说明书时，才通过 Skill 工具把整本拿出来读。

### 源码实现
- **目录格式**：`/skills/` 目录下只认 `技能名/SKILL.md` 的目录格式，单个 `.md` 文件不会被当作技能（`skills/loadSkillsDir.ts:424-428`）。加载位置有四层：企业托管（managed）、用户级 `~/.claude/skills`、项目级 `.claude/skills`（含 `--add-dir`）、以及旧版 `/commands/` 目录（`loadSkillsDir.ts:638-714`）。
- **SKILL.md frontmatter 字段全集**（解析入口 `parseSkillFrontmatterFields`，`loadSkillsDir.ts:185-265`）：
  - `name`（显示名，:238）、`description`（:208-214，缺省从正文提取）、`when_to_use`（:252，告诉模型什么场景调用）
  - `allowed-tools`（:242，技能运行期间可用的工具白名单）
  - `argument-hint`、`arguments`（:245-251，参数提示与命名参数）
  - `version`（:253）、`model`（:221-226，可为 `inherit` 或指定模型）
  - `effort`（:228-235，可指定思考力度）
  - `disable-model-invocation`（:255，只许人调用）、`user-invocable`（:216-219，false 时人在 `/` 菜单看不到）
  - `hooks`（:259，技能级钩子，Zod 校验见 `parseHooksFromFrontmatter` :136-153）
  - `context: fork`（:260，在 fork 出的子上下文执行）、`agent`（:261）
  - `shell`（:263，内嵌 shell 命令用哪个解释器）
  - `paths`（`parseSkillPaths` :159-178，gitignore 风格路径过滤——**条件技能**，只有当匹配路径的文件被读写时才激活，激活逻辑在 `activateConditionalSkillsForPaths` :997 起）
- **渐进披露（Progressive Disclosure）**：
  - 第一阶段——只注入清单：`utils/attachments.ts:2661 getSkillListingAttachments` 把所有技能的 name/description/whenToUse 打包成一个 `skill_listing` attachment（`attachments.ts:2744-2749`），按 token 预算裁剪（`formatCommandsWithinBudget` :2744），并且每个 agent 只发一次、增量补发（:2698-2732）。
  - 第二阶段——调用时才加载全文：模型调用 Skill 工具（`tools/SkillTool/SkillTool.ts:580 call`）→ 执行该 Command 的 `getPromptForCommand`（`loadSkillsDir.ts:344-399`），此时才拼入 `Base directory for this skill: ...` + 完整正文、做参数替换（`substituteArguments` :349）、替换 `${CLAUDE_SKILL_DIR}`/`${CLAUDE_SESSION_ID}`（:356-369），甚至执行 markdown 里内嵌的 `` !`...` `` shell 命令（:375）。**安全细节**：MCP 来源的技能是"远程不可信内容"，永不执行内嵌 shell（:372-374）。
- **动态发现**：会话中读写文件时会从文件路径向上递归发现嵌套的 `.claude/skills`（`discoverSkillDirsForPaths` :861-915），跳过 gitignore 的目录（:892-897），深层目录的技能覆盖浅层同名技能（:944-951）。
- **内置 bundled 技能**：编译进二进制、代码注册（`skills/bundledSkills.ts:53 registerBundledSkill`），目录 `skills/bundled/`：`batch`、`claudeApi`、`claudeInChrome`、`debug`、`keybindings`、`loop`、`loremIpsum`、`remember`、`scheduleRemoteAgents`、`simplify`、`skillify`、`stuck`、`updateConfig`、`verify`。带附件的技能（`files` 字段，`bundledSkills.ts:29-36`）首次调用时才把参考文件解包到磁盘（`extractBundledSkillFiles` :131-145），并做了 `O_NOFOLLOW|O_EXCL` 防符号链接攻击（:176-193）。
- **MCP 技能**：MCP 服务器也能提供技能，通过 `skills/mcpSkillBuilders.ts` 的注册表复用同一套解析逻辑（避免循环依赖）。

### 例子
`~/.claude/skills/pdf/SKILL.md` 写着 `description: PDF 表格提取` + `allowed-tools: Read, Bash`。启动时模型只看到一行"pdf — PDF 表格提取"；当用户说"把 report.pdf 第 3 页的表抠出来"，模型调用 Skill 工具，Claude 此刻才读到 SKILL.md 全文和 `scripts/extract.py` 的存在，然后用 Bash 跑脚本。

---

## 3. MCP（Model Context Protocol）

### 是什么
MCP 是"AI 界的 USB-C 接口"：任何外部服务（数据库、Figma、公司内部系统）只要按 MCP 协议实现一个服务器，Claude Code 就能即插即用它的工具、资源和提示词模板。

### 源码实现
- **客户端**：`services/mcp/client.ts`（3348 行），基于官方 `@modelcontextprotocol/sdk` 的 `Client`（`client.ts:7`）。支持的传输（schema 在 `services/mcp/types.ts:28-131`）：
  - `stdio`——本地子进程（`client.ts:950 new StdioClientTransport`）
  - `sse`——HTTP 长连接推送（`client.ts:673,702 SSEClientTransport`）
  - `http`——Streamable HTTP（`client.ts:861,900 StreamableHTTPClientTransport`）
  - `ws`/`ws-ide`——WebSocket（`client.ts:734,783`）
  - `sdk`——SDK 进程内传输（`client.ts:3278 SdkControlClientTransport`）、`sse-ide`、`claudeai-proxy` 等特殊类型
- **配置与审批**：项目根目录的 `.mcp.json` 里可以登记服务器（企业级还有 `managed-mcp.json`，`services/mcp/config.ts:64-66`）。因为项目级配置可能来自不可信仓库，启动时对每个 pending 服务器弹审批对话框：`handleMcpjsonServerApprovals()`（`services/mcpServerApproval.tsx:13-40`，单服务器用 `MCPServerApprovalDialog`，多个用 `MCPServerMultiselectDialog`）。状态机是 `getProjectMcpServerStatus()`（`services/mcp/utils.ts:351`）：settings 里 `enabledMcpjsonServers`/`disabledMcpjsonServers` 记录用户选择，`enableAllProjectMcpServers` 可全批（utils.ts:371）；`--dangerously-skip-permissions` 和非交互模式下自动批准但有严格防 RCE 注释（utils.ts:383-400）。加载时只放行 approved 的服务器（`config.ts:1164-1168`）。
- **工具进对话**：`fetchToolsForClient()`（`client.ts:1742`）调 `tools/list`，然后包装成 `MCPTool`（`tools/MCPTool/MCPTool.ts`），名字拼成 `mcp__服务器名__工具名`（`buildMcpToolName`，`client.ts:1767`）。权限规则支持服务器级通配：`mcp__server1` 或 `mcp__server1__*`（`utils/permissions/permissions.ts:236-259`）。
- **资源与提示词**：`ListMcpResourcesTool`、`ReadMcpResourceTool`、`McpAuthTool`（`client.ts:53-56` 导入）让模型能浏览/读取 MCP 资源；MCP prompts 被转成 Command（`client.ts:2038-2077`，名字同样是 `mcp__server__prompt` 格式 :2058）。
- **连接管理**：React 上下文 `MCPConnectionManager`（`services/mcp/MCPConnectionManager.tsx`）+ `useManageMCPConnections` 负责重连、开关；`/mcp` 命令提供管理 UI。服务器状态有 `connected/failed/needs-auth/pending/disabled`（`types.ts:183-248`），needs-auth 时走 MCP OAuth 登录。

### 例子
项目 `.mcp.json` 里写 `{"mcpServers": {"github": {"type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"]}}}`。新克隆仓库的同事第一次打开 Claude Code 会弹出"是否信任 github 服务器？"审批框；批准后工具列表里多出 `mcp__github__create_issue`，权限页可以一条规则 `mcp__github` 全放行。

---

## 4. API 与认证

### 是什么
Claude Code 支持四类"买单方式"：Claude 订阅账号（OAuth 登录）、API key 按量付费、以及企业云厂商渠道（AWS Bedrock / Google Vertex / Azure Foundry）。就像同一张电话卡可以走合约套餐、充值卡或公司专线。

### 源码实现
- **Provider 判定**：`utils/model/providers.ts:6-13 getAPIProvider`——看环境变量 `CLAUDE_CODE_USE_BEDROCK`/`CLAUDE_CODE_USE_VERTEX`/`CLAUDE_CODE_USE_FOUNDRY`，都不设则是 `firstParty`。
- **OAuth 登录流程**（标准授权码 + PKCE）：`services/oauth/index.ts:14-120 OAuthService`——生成 code_verifier/challenge（:29,57-58），起本地 localhost 监听 `AuthCodeListener`（:49-50，`auth-code-listener.ts`），构造两个 URL：自动流（打开浏览器跳回 localhost）与手动流（复制粘贴 code，:71-72），拿到 code 后 `exchangeCodeForTokens` 换 token（:103-109）。登录后的落库逻辑在 `cli/handlers/auth.ts:44 installOAuthTokens`。scope 体系在 `constants/oauth.ts`（`user:inference`、`user:profile`、`org:create_api_key`）。
- **凭据存储**：macOS 上 OAuth token 存钥匙串（`utils/secureStorage/index.ts:9-17`：`macOsKeychainStorage` 失败时降级 `plainTextStorage`；其他平台目前用明文文件）。API key 来源优先级在 `utils/auth.ts`：`apiKeyHelper`（settings 里配的执行脚本，`auth.ts:123`）、`ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN` 环境变量（:126,134）、`--settings` 注入、keychain。
- **Token 刷新**：`checkAndRefreshOAuthTokenIfNeeded()`（`utils/auth.ts:1427-1560`）——发现 accessToken 过期后先清缓存重读（别的进程可能已刷新），再用文件锁（`lockfile.lock` :1500）防止多进程同时刷新，最多重试 5 次（:1453）；订阅用户刷新时省略 scopes 以便服务端扩 scope（:1544-1550）。401/"token revoked" 时在重试层强制刷新（`services/api/withRetry.ts:246-252`）。
- **计费/归属头**：每次请求的系统提示词第一块是 `x-anthropic-billing-header: cc_version=...; cc_entrypoint=...; cch=...; cc_workload=...`（生成于 `constants/system.ts:86-95`）。`splitSysPromptPrefix()`（`utils/api.ts:321-376`）会把它从系统提示中摘出来、标记 `cacheScope: null`（不参与提示缓存），其余静态块用 `global`/`org` 缓存作用域——这样换 entrypoint 不会打破缓存。

### 例子
用户跑 `/login` → OAuthService 打开浏览器授权 → 浏览器跳回 `http://localhost:PORT/callback?code=...` → CLI 换取 token 存进 macOS 钥匙串。一小时后 token 过期，`checkAndRefreshOAuthTokenIfNeeded` 拿文件锁静默续期，用户无感知。

---

## 5. effort / thinking 机制

### 是什么
"思考预算"——模型回答前可以先打草稿（thinking），草稿长度可以调。effort 是新世代的统一旋钮（low/medium/high/max），thinking budget 是老式的精确 token 数；Claude 4.6 系支持 "adaptive"（模型自己决定想多久）。

### 源码实现
- **effort 档位**：`utils/effort.ts:14-20` 定义 `low/medium/high/max`（另允许数字，内部用）。哪些模型支持由 `modelSupportsEffort()` 决定（`effort.ts:26-50`，目前 opus-4-6/sonnet-4-6 白名单）；`max` 档仅 Opus 4.6（`effort.ts:55-69`），不支持的模型自动降到 `high`（`resolveAppliedEffort` :152-168 的 clamp）。
- **优先级链**：`resolveAppliedEffort()`（`effort.ts:152-168`）：环境变量 `CLAUDE_CODE_EFFORT_LEVEL` → 会话状态（用户用 `/effort` 命令或 `/model` 选择设的 `appState.effortValue`）→ 模型默认值。持久化时数字档和外部用户的 `max` 不写入 settings（`toPersistableEffort` :101-112）。`/effort` 命令实现在 `commands/effort/effort.tsx:16-20`。
- **发送给 API**：`services/api/claude.ts:437-465 configureEffort`——字符串档位直接放 `outputConfig.effort`（:453-455），数字档位走内部 `effort_override`（:458-463，ant 专用）。最终生效点在 `claude.ts:1458 resolveAppliedEffort` → `:1483`。
- **thinking 配置**：类型定义 `ThinkingConfig = adaptive | enabled(budgetTokens) | disabled`（`utils/thinking.ts:10-13`）。`modelSupportsThinking()`（:90-110）按 provider 区分：一方和 Foundry 上所有 Claude 4+ 都支持；Bedrock/Vertex 只认 sonnet-4/opus-4。默认开启，可用 `MAX_THINKING_TOKENS=0` 或 settings `alwaysThinkingEnabled: false` 关闭（`shouldEnableThinkingByDefault` :146-162）。
- **请求构造**：`services/api/claude.ts:1596-1630`——支持 adaptive 的模型（4.6 系，`modelSupportsAdaptiveThinking` `thinking.ts:113-144`）发 `{type: 'adaptive'}` 不带预算；老模型发 `{type: 'enabled', budget_tokens: N}`，预算 = `min(maxOutputTokens-1, thinkingConfig.budgetTokens ?? 模型默认)`（:1617-1627）。
- **interleaved thinking**：作为 beta header 注入（`utils/betas.ts:95 'interleaved_thinking'`），让模型在工具调用之间穿插思考；Foundry 全模型支持（betas.ts:102）。
- **彩蛋**：用户输入 `ultrathink` 关键词会触发高亮和更高思考档位（`thinking.ts:29-31 hasUltrathinkKeyword`，彩虹色渲染 :60-86），由 feature flag `ULTRATHINK` + GrowthBook `tengu_turtle_carbon` 双重门控（:19-24）。

### 例子
用户 `/effort high`（持久化到 settings），下条请求 API body 里就是 `output_config: {effort: 'high'}`；如果是 Opus 4.6，thinking 字段为 `{type: 'adaptive'}`，模型自行决定思考长度；状态栏同步显示当前档位（`getDisplayedEffortLevel` `effort.ts:170-178`）。

---

## 6. 模型选择与 fallback

### 是什么
"主角与替身"机制：平时用主模型（mainLoopModel），当 Anthropic 服务器超载（HTTP 529）时自动换备用模型（fallbackModel）顶上，对话不中断。

### 源码实现
- **主模型解析优先级**（`utils/model/model.ts:84-101 getMainLoopModel`）：
  1. 会话中 `/model` 命令改的（`getMainLoopModelOverride`，`bootstrap/state.ts:838`）
  2. 启动参数 `--model`
  3. 环境变量 `ANTHROPIC_MODEL`
  4. settings 里的 `model`
  5. 内置默认（Opus 4.6；3P 渠道 Sonnet 默认 4.5 因为上架滞后，`model.ts:103-133` 的 `@[MODEL LAUNCH]` 注释）
- **fallback 指定**：CLI 参数 `--fallback-model <model>`（`main.tsx:1000`，帮助文本注明"only works with --print"），解析于 `main.tsx:2020`，传入查询循环 `main.tsx:2846 → query.ts:258`。fallback 模型不允许和主模型相同（`main.tsx:1337` 校验）。
- **触发机制**：在重试层 `services/api/withRetry.ts`——连续 529（服务器超载）计数，达到 `MAX_529_RETRIES = 3`（:54）且配置了 fallbackModel 时，抛出特殊的 `FallbackTriggeredError`（:163-165, :337-352）。注意：默认只对"非订阅用户的非定制 Opus"触发，设 `FALLBACK_FOR_ALL_PRIMARY_MODELS` 环境变量可放开（:330-336）。后台任务（摘要、标题生成）遇 529 直接丢弃不放大重试（:319-327）。
- **切换执行**：`query.ts:894-910`——捕获 `FallbackTriggeredError` 后把 `currentModel` 换成 fallbackModel，清空本轮半成品 assistant 消息（补齐 'Model fallback triggered' 的工具结果），整个请求重发。
- **小模型分工**：另有 `getSmallFastModel()`（`services/api/claude.ts:339-340`），对话主题检测、命令描述等杂活用 Haiku 级别小模型，与主循环模型分离。

### 例子
用户跑 `claude -p --model opus --fallback-model sonnet "重构这个模块"`。高峰期 Opus 连续 3 次返回 529，重试层抛 `FallbackTriggeredError`，query 循环静默切到 Sonnet 继续，用户只在 transcript 里看到一条模型切换提示。

---

## 7. 权限模式（Permission Modes）

### 是什么
权限模式是"给 AI 的遛狗绳长度"：从"每一步都问你"到"完全放养"分几档，Shift+Tab 一键换档。

### 源码实现
- **各模式语义与 UI 配置**（`utils/permissions/PermissionMode.ts:42-91`）：
  - `default`——每次危险操作弹窗询问
  - `plan`（Plan Mode）——只许研究和出方案，不许动文件/跑命令；结束时用 ExitPlanMode 工具交方案给用户批（`utils/permissions/filesystem.ts:1446` 起拦截写操作）
  - `acceptEdits`——文件编辑自动接受（`filesystem.ts:1366`：工作目录内的编辑直接放行），其余仍询问
  - `bypassPermissions`——全部跳过询问（危险，需 `--dangerously-skip-permissions` 或在 UI 确认启用）
  - `dontAsk`——不在 UI 循环中暴露（`getNextPermissionMode.ts:70-72`）
  - `auto`——内部（ant-only）模式，由转录分类器实时判断每个操作是否安全（feature flag `TRANSCRIPT_CLASSIFIER`，`PermissionMode.ts:80-90`），循环进入前要过 `isAutoModeAvailable` 门（`getNextPermissionMode.ts:17-29`）
- **Shift+Tab 循环**：键位定义 `keybindings/defaultBindings.ts:30-36`（`MODE_CYCLE_KEY`，Windows 无 VT 模式时降级 `meta+m`）。循环顺序在 `utils/permissions/getNextPermissionMode.ts:34-79`：`default → acceptEdits → plan → bypassPermissions（若可用）→ default`。切换时 `cyclePermissionMode()`（:88-101）调用 `transitionPermissionMode` 做上下文清理（如进 auto 模式剥离危险权限）。
- **模式横幅**：状态栏按模式变色（`PermissionMode.ts:26-30` 颜色映射：plan 蓝色、accept 青色、bypass 红色）。

### 例子
让 Claude 帮你调研一个 bug 但怕它乱改代码：Shift+Tab 切到 `plan`，Claude 读代码、写方案，最后通过 ExitPlanMode 工具弹出"批准计划吗？"；批准后自动切到 `acceptEdits` 直接落地修改（`filesystem.ts:1450` 的模式建议）。

---

## 8. 输出样式（Output Styles）

### 是什么
输出样式是"给 Claude 换人格面具"——它直接改写系统提示词的开篇部分，让同一个模型以不同风格回答（比如教学式 vs 极简式）。

### 源码实现
- **内置样式**：`constants/outputStyles.ts:42-100`——`default`（值为 null，不加料）、`Explanatory`（解释每个实现选择，附 `★ Insight` 块模板）、`Learning`（故意留 2-10 行小任务让 human 亲手写，`TODO(human)` 机制）。
- **自定义样式**：往 `~/.claude/output-styles/*.md` 或项目 `.claude/output-styles/*.md` 放 markdown 文件即可，frontmatter 支持 `name`、`description`、`keep-coding-instructions`（`outputStyles/loadOutputStylesDir.ts:41-62`）；插件也可通过 `output-styles/` 目录提供（`loadOutputStylesDir.ts:11`）。
- **注入方式**：选中的样式拼成 `# Output Style: {name}\n{prompt}` 段落插进系统提示（`constants/prompts.ts:152-157`），并改变总纲句为"according to your Output Style below"（prompts.ts:180）。`keep-coding-instructions: true` 表示保留原有的编程指令，只是叠加风格。
- **切换**：`/output-style` 命令（`commands/output-style/`）；插件可用 `force-for-plugin` 强制启用某样式（`outputStyles.ts:14-21`）。

### 例子
新手用户 `/output-style Learning` 后，Claude 写 30 行代码时会刻意留下核心函数，发一条"Learn by Doing"卡片让你补全 `TODO(human)` 部分，并等你就位后才继续。

---

## 9. 记忆系统与快捷记忆

### 是什么
四层"大脑"：跨会话长期记忆（MEMORY.md 自动记忆）、项目公约（CLAUDE.md 系列）、当前会话笔记（Session Memory）、以及手动管理的 `/memory` 编辑器。

### 源码实现
- **自动记忆（auto memory / memdir）**：`memdir/memdir.ts`——每个项目一个记忆目录（默认 `~/.claude/projects/<项目路径>/memory/`，`memdir/paths.ts`），入口文件 `MEMORY.md`（`memdir.ts:35`）硬上限 200 行 / 25KB，超出截断并附警告（`memdir.ts:37-40, 59-95 truncateEntrypointContent`）。Claude 自主把用户偏好、项目习惯写进该目录下的 markdown 文件；启动时按相关性检索注入（`memdir/findRelevantMemories.ts`），注入的条目带"新鲜度"前缀（`tools/FileReadTool/FileReadTool.ts:749 memoryFileFreshnessPrefix`）。用户纠正 Claude 时，拒绝消息尾部会追加"考虑存到记忆"的提示（`utils/messages.ts:177-191`）。
- **会话记忆（Session Memory）**：`services/SessionMemory/sessionMemory.ts:1-7`——后台 fork 一个子 agent 周期性把当前对话要点提炼成 markdown 笔记，不打断主对话；用于 auto-compact 后恢复上下文。压缩整合见 `services/compact/sessionMemoryCompact.ts`。
- **CLAUDE.md 体系**：`utils/claudemd.ts getMemoryFiles` 收集项目/用户/嵌套 CLAUDE.md 与 `.claude/rules`；子目录的 CLAUDE.md 在被读到的文件触发时按需注入（`utils/attachments.ts:1710 memoryFilesToAttachments` + `nestedMemoryAttachmentTriggers` 去重，`FileReadTool.ts:848,870`）。
- **`/memory` 命令**：`commands/memory/memory.tsx`——弹出 `MemoryFileSelector`（`components/memory/MemoryFileSelector.tsx:44`）选择用户记忆/项目记忆/嵌套记忆文件，然后用 `$EDITOR`/`$VISUAL` 打开编辑（memory.tsx:72, editFileInEditor）。
- **关于 `#` 快捷记忆**：本源码快照中**没有** `#` 前缀输入模式——`components/PromptInput/inputModes.ts:31-33` 只识别 `!`（bash 模式），`PromptInputMode` 类型（`types/textInputTypes.ts:265-269`）也只有 bash/prompt 等。早期版本的 `#` 快捷追加记忆在本快照中已演进为 `/memory` 命令 + auto memory 体系（科普写作时请注意版本差异）。

### 例子
你随口说"我们团队 Commit 都用中文"，Claude 把这条写进 `~/.claude/projects/xxx/memory/team-conventions.md` 并更新 `MEMORY.md` 索引；下周新开会话，这条偏好随相关记忆自动出现在系统提示里。

---

## 10. 其他值得科普的机制

### Vim 模式（`src/vim/`）
输入框支持 Vim 键位（NORMAL/INSERT 模式切换、motion、operator、text object），实现拆成纯函数模块：`vim/motions.ts`、`vim/operators.ts`、`vim/textObjects.ts`、`vim/transitions.ts`；状态类型在 `types/textInputTypes.ts:255-260 VimInputState`。

### 语音输入（`src/voice/` + `src/services/voiceStreamSTT.ts`）
按住说话（push-to-talk）：`voiceStreamSTT.ts:1-36` 连 Anthropic 的 `/api/ws/speech_to_text/voice_stream` WebSocket 做流式转写。门槛：`voice/voiceModeEnabled.ts:18-24` GrowthBook 急停开关 + `:31-40 hasVoiceAuth`——**必须有 OAuth token**（走 claude.ai 端点，API key/Bedrock/Vertex 不可用）。

### 远程与 Bridge（`src/remote/`、`src/bridge/`）
- `bridge/bridgeMain.ts`：让本机成为 claude.ai 网页/App 的"执行端"——轮询云端领取会话任务、本地跑、回传结果（`createSessionSpawner`、`getRemoteSessionUrl`、`createBridgeApiClient`），支持 worktree 隔离（:22 导入）。
- `remote/SessionsWebSocket.ts` + `RemoteSessionManager.ts`：把本地 REPL 会话桥接到网页端实时控制（WebSocket 双向，`remotePermissionBridge.ts` 把权限弹窗同步给网页确认）。

### Cost 追踪（`src/cost-tracker.ts`）
每次 API 返回的 usage 经 `calculateUSDCost()`（`utils/modelCost.js`，按模型价目表）累计进 `bootstrap/state` 里的计数器（`cost-tracker.ts:3-27` 导入一串 getTotalCostUSD/getTotalInputTokens 等），`/cost` 命令展示，并把 `lastCost` 持久化到项目配置（:146）供跨会话累计。

### 遥测 / Analytics（`src/services/analytics/`）
事件埋点统一走 `logEvent()`，事件名形如 `tengu_*`（如 `tengu_api_opus_fallback_triggered`、`tengu_oauth_token_refresh_starting`）；后端有 Statsig（feature flag）、GrowthBook（实验分流，`growthbook.ts`）、Datadog（`datadog.ts`）、一方事件上报（`firstPartyEventLogger.ts`），敏感字段用类型标记强制声明（`AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS`）。

### 快捷键系统（`src/keybindings/`）
声明式键位系统：默认绑定表 `keybindings/defaultBindings.ts:37+`（按 `Global`/`Chat` 等 context 分块，值是 `app:interrupt`、`history:search` 这类动作字符串），用户可在 `keybindings.json` 覆盖（`loadUserBindings.ts`），解析与匹配在 `parser.ts`/`match.ts`，React 侧用 `useKeybinding` hook 订阅。`ctrl+c`/`ctrl+d` 为保留键不可改绑。

### UDS 消息服务（外部注入消息）
`setup.ts:86-101`：启动时在 `$TMPDIR` 建 Unix Domain Socket（`--messaging-socket-path` 可指定），外部进程可向 socket 写入消息注入到对话（ant 默认开启，feature `UDS_INBOX`，实现动态导入 `utils/udsMessaging.js`）；路径经 `$CLAUDE_CODE_MESSAGING_SOCKET` 环境变量传给子进程，且必须在 SessionStart hook 之前完成绑定（注释 :91-94）。`--bare` 模式跳过。

### `--worktree` 隔离
`entrypoints/cli.tsx:247-261`：`-w/--worktree` 让会话在 git worktree（`.claude/worktrees/<slug>`）里运行，改动不碰主工作区；slug 有路径穿越防护（`utils/worktree.ts:52-55` 注释），配 `--tmux` 还有快速 exec 路径。

### SDK / Headless 模式
- `cli/print.ts`（5594 行）：`claude -p "..."` 非交互模式入口，无 React 树（:517 注释），支持 `--output-format json/stream-json`、headless profiler（:314-317）、headless 插件安装（:331）。
- `QueryEngine.ts`：把"一次查询"抽象成可复用引擎（SDK 与 CLI 共用）：组装 tools/systemPrompt/toolUseContext（:370, :518），驱动 `query.ts` 的异步生成器循环，产出 `SDKMessage` 流（SDK 消费）或文本（print 模式）。
- 也支持 `--bare`（精简启动：跳过技能发现、UDS、遥测初始化等，`loadSkillsDir.ts:654-675`、`setup.ts:86-88`）。