🔍 Claude Code CLI 架构深度解析

1️⃣ 核心循环引擎

Claude Code 的整个运行时可以归结为一件事：一个无限循环不断地向模型发起请求，模型决定下一步做什么。这个循环被称为 Agentic Loop，是整个系统的心脏。它的核心入口是一个 query() 函数——接收用户消息，进入「请求 → 执行工具 → 再请求」的迭代，直到模型认为任务完成（不再调用工具）才退出。

流式处理与并行工具执行

模型的输出是流式返回的——文字 token 逐个到达，工具调用的参数也在流式中渐进构建。Claude Code 在收到完整的工具调用参数后立即开始执行，而不是等所有输出结束。更关键的是，当模型在一轮响应中请求多个工具时，这些工具并行执行，所有结果收集完毕后一次性追加到对话历史中，再发起下一轮请求。这种设计极大地缩短了多文件读取、批量搜索等场景的延迟。

错误恢复机制

循环内置了多层容错逻辑：

• API 层重试：遇到速率限制（429）或服务端错误（5xx）时，采用指数退避策略自动重试，并向用户显示倒计时
• 工具执行容错：单个工具执行失败不会终止循环，而是将错误信息作为工具结果返回给模型，由模型决定如何处理（重试、换方案、或报告给用户）
• 上下文溢出恢复：当消息总量超过模型上下文窗口限制时，触发自动压缩（详见第三章），压缩完成后继续循环
• 中止信号传播：用户按 Esc 时，会通过 AbortController 向所有正在执行的工具广播中止信号，确保进程、子进程全部清理

Generator 嵌套与流式架构

整个循环采用 async generator 模式实现——query() 本身是一个异步生成器，每产出一个事件（文字片段、工具调用开始、工具结果、错误等）都通过 yield 向外传递。这使得 UI 层可以实时渲染每一个中间状态，而不必等待完整响应。当存在子 Agent（详见第六章）时，内层 Agent 的 generator 被嵌套进外层，事件自动向上冒泡。

2️⃣ System Prompt 架构设计

Claude Code 的系统提示词并非一段静态文本，而是由 14 个独立区段（Segment）按规则动态拼装而成的结构化文档。可将其理解为"乐高积木"——每个区段承担特定职责，根据当前运行环境、用户配置、对话状态按需组合。

14 区段拼装架构

静态 / 动态分界线

DYNAMIC_BOUNDARY 将 14 个区段分为两组。分界线以上的 7 个静态区段在会话创建时确定，只要工具集和权限模式不变就不会改变，因此可以被缓存以减少重复计算的开销。分界线以下的 7 个动态区段在每次 API 调用前实时拼装——例如用户切换了 Git 分支、读取了新文件触发路径作用域规则、或发生了自动压缩。

三层缓存策略

TTL 锁定机制

缓存命中后并不意味着永久使用。系统为每个缓存条目维护一个 TTL（Time-To-Live） 计时器。在 TTL 过期前，即使底层文件发生变化，也继续使用缓存版本——这避免了高频文件监听带来的性能开销。TTL 过期后，系统采用两阶段检测：先比对文件 hash 确认是否真的变化了，如果 hash 一致则直接续期而不重新计算。

优先级与覆盖规则

当多个来源的指令发生冲突时（例如组织策略要求禁止某操作，但项目 CLAUDE.md 允许），系统按以下优先级从高到低裁决：

1. Override 指令 — 组织级强制策略，不可被覆盖
2. Coordinator 指令 — 编排器向子 Agent 下发的指令
3. Agent 内置规则 — Agent 类型自带的行为约束
4. Custom 配置 — 用户在 settings 中的自定义规则
5. Default 指令 — 系统内置的默认行为
6. Append 指令 — 以追加方式注入的补充规则

3️⃣ 上下文工程与压缩策略

上下文窗口是 Agent 最宝贵也最容易耗尽的资源。Claude Code 的核心设计约束之一就是：窗口会很快填满，而模型性能随填充率上升而下降。因此，系统在"加载什么"和"何时丢弃"两端都做了精细设计。

分层加载策略

三级压缩策略

当上下文逐渐填满时，系统依次触发三个级别的压缩：

压缩后的恢复机制

压缩必然导致信息丢失，但某些关键信息必须在压缩后恢复。系统在每次压缩完成后，自动从磁盘重新注入以下内容：

• CLAUDE.md 指令 — 从文件系统重新读取，确保项目规则不丢失
• Auto Memory — 从本地存储重新加载
• 活跃 Skill 内容 — 截断至每个 ≤5KB 后重新注入
• Hooks 定义 — 生命周期钩子必须始终可用
• 当前文件状态 — 最近操作的 5 个文件路径和状态

但以下内容在压缩后不会恢复：嵌套的子目录 CLAUDE.md、已失效的路径作用域规则。这些会在下次读取匹配文件时按需重新加载。

上下文生命周期

4️⃣ 记忆与知识体系

LLM 天然无状态——每次对话都从零开始。Claude Code 通过四层记忆架构解决跨会话持久化问题，让 Agent 能够在项目中积累经验、遵守规范、在团队中共享知识。

四层 CLAUDE.md 层级

@include 模块化组合

CLAUDE.md 支持 @include 指令引用其他文件，实现模块化组织。例如一个 Monorepo 的根 CLAUDE.md 可以写 @include ./frontend/CLAUDE.md 和 @include ./backend/CLAUDE.md，各子团队独立维护自己的规范。被引用的文件在会话启动时递归解析并合并到同一个上下文块中。

CLAUDE.md 编写原则

Auto Memory 自动记忆

Auto Memory 是 Claude 在工作过程中自动积累的经验知识，无需人工维护。存储在 ~/.claude/projects/<project>/memory/ 目录下。

记忆提取通过独立 Fork Agent执行——主会话不受影响。Fork Agent 分析最近 5 轮对话，提取值得记住的信息，写入对应的主题文件（如 debugging.md、patterns.md）。索引文件 MEMORY.md 前 200 行/25KB 在每次会话自动加载。

Session Memory 会话记忆

Session Memory 是单个长会话内的结构化笔记，包含 9 个标准区段：

• 任务定义 — 当前任务的目标描述
• 当前方案 — 正在执行的实现计划
• 进度追踪 — 已完成/进行中/待办事项
• 关键决策 — 重要的技术选择及理由
• 遇到的问题 — 踩坑记录和解决方案
• 代码变更摘要 — 修改了哪些文件、做了什么变更
• 待验证项 — 需要确认但尚未验证的假设
• 上下文备注 — 压缩时可能丢失的关键上下文
• 后续步骤 — 下一步计划

Team Memory 团队记忆

在多 Agent 团队协作场景中，多个 Agent 共享一个目录存放团队级记忆。系统内置了路径遍历防护——Agent 写入记忆文件时，路径会被规范化并校验，确保不能通过 ../../ 之类的手法逃逸到共享目录之外，防止恶意 Agent 篡改其他团队的数据。

5️⃣ 工具注册与沙箱安全

Claude Code 内置了约 49 个工具，是 Agent 与外部世界交互的全部触点。整个工具系统的设计遵循一个原则：尽可能给模型强大的能力，同时确保安全边界不可突破。

工具接口规范

每个工具都实现统一的 Tool 接口，包含以下核心字段：

三层注册与过滤

六种权限模式

OS 级沙箱实现

Claude Code 在操作系统层面实现了真正的安全隔离，而非仅靠 prompt 约束：

• macOS: Seatbelt — 使用 sandbox-exec 创建沙箱 profile，限制文件系统访问路径（只允许项目目录 + 临时目录）、网络连接（只允许 API 端点）、进程创建（禁止启动特定危险进程）
• Linux: Landlock — 使用内核级的 Landlock LSM 实现类似的文件系统和网络限制，不需要 root 权限即可生效
• 两者共同目标：即使模型被提示注入攻击诱导，操作系统本身也会阻止越界操作

反逃逸三重防线

Bash 工具的特殊复杂度

在所有工具中，Bash 工具是最强大也最危险的——它可以执行任意 Shell 命令。Claude Code 为其设计了额外的安全层：

• 命令在执行前经过 AST 解析，识别潜在危险模式（如 rm -rf /、curl | bash）
• 执行超时机制——长时间无输出的命令会被自动终止
• 输出截断——命令输出超过阈值时自动截断，防止上下文被巨量输出淹没
• 工作目录锁定——Bash 工具的工作目录被限制在项目根目录内

6️⃣ 多 Agent 协同架构

Claude Code 不是一个孤立的 Agent——它支持从轻量级子任务分发到持久化团队协作的完整多 Agent 体系。所有 Agent 相关能力可以分为三个层次：子 Agent 分治、团队协作、后台自主运行。

四种子 Agent 类型

三种执行模式

Coordinator 编排模式

当任务需要多个子 Agent 协作时，主 Agent 可以切换为 Coordinator（编排器）角色。编排器本身不执行具体工作，而是：

• 分析任务并拆解为子任务
• 通过 SendMessage 工具向各子 Agent 下发指令
• 收集结果并做最终整合
• 处理子 Agent 间的依赖关系

为防止无限递归，系统限制了 Agent 嵌套深度——子 Agent 不能再创建子 Agent，防止模型陷入无限委派。

持久化团队（Team / Swarm）

区别于临时的子 Agent，持久化团队是跨会话存续的多 Agent 组织：

邮箱系统有两种实现：进程内模式使用内存中的 Mailbox 对象，消息通过事件触发即时传递；文件模式使用 .ndjson 文件存储消息，支持跨进程甚至跨机器通信（通过 tmux/iTerm2 后端）。

Agent 标识采用 name@team 格式（如 alice@frontend-team），确保消息路由准确。UI 层对团队消息流限制最多显示最近 50 条，避免界面被大量消息淹没。

后台 Agent 与自主模式

后台Agent能够在无用户交互的情况下独立运行：

• 后台任务执行 — 拥有独立的 AbortController，输出写入磁盘而非终端，所有权限请求自动拒绝（安全第一）
• Dream 模式 — 记忆整理任务，在空闲时分析历史对话并整理归纳到 Auto Memory，具有完整的回滚机制（如果中途被中止，已写入的记忆会被撤销）
• Cron 定时调度 — 基于文件的调度器，支持 Jitter（随机延迟防止多实例同时触发）和文件锁互斥（防止同一任务并发执行）。提供 CronCreate、CronList、CronDelete 三个工具操作调度规则
• 远程 Agent — 在云端 VM 中运行的 Agent 实例，通过轮询机制与本地客户端同步状态

7️⃣ 任务编排与状态机

当 Agent 处理复杂工作流时，需要将大任务分解为可管理的子任务并追踪每个任务的生命周期。Claude Code 设计了一套任务图（Task Graph）系统来管理这种复杂性。

七种任务类型

统一状态机

所有 7 种任务类型共享同一套状态机，确保行为一致性：

扁平存储与引用关系

任务图采用扁平化存储——所有任务存放在同一个字典中，通过 parentId 字段建立父子关系。这种设计比嵌套树结构更易于序列化、查询和垃圾回收。

• 每个任务有唯一 ID 和可选的 parentId
• 父任务的状态由子任务的聚合状态自动推导（所有子任务完成 → 父任务完成；任一子任务失败 → 父任务失败）
• 任务输出采用增量写入磁盘的方式——长时间运行的任务不需要全部完成才能看到中间结果

通知与去重

当任务状态发生变化时，系统需要通知相关方（UI、父任务、编排器）。为避免重复通知，每个任务维护一个 notified 标志——状态变更时标记为 false，通知发出后标记为 true。这个简单机制确保在高并发场景下，同一个状态变更只产生一次通知。

垃圾回收机制

已完成的任务不会立刻清除，而是保留 30 秒宽限期。在此期间，如果有其他任务引用其结果（例如 Conditional 类型读取前置任务的输出），仍然可以正常访问。宽限期过后，GC 回收存储空间。对于不同结束状态的任务，终止行为也有区别：

• completed 任务 → 结果持久化到磁盘后回收内存
• failed 任务 → 保留错误信息用于诊断
• cancelled 任务 → 立即向所有子任务广播取消信号

8️⃣ Skill 与 MCP 扩展生态

Claude Code 的内置工具能力是有限的——紧紧围绕文件操作、搜索、执行、Web 这几类。如何让 Agent 连接到无限广阔的外部世界？答案是两个互补的扩展机制：Skill（技能）解决知识注入问题，MCP（Model Context Protocol）解决能力扩展问题。

Skill 技能系统

Skill 的本质是带 YAML 元数据的 Markdown 文件，存放在 .claude/skills/ 目录下。它可以是纯参考文档（API 规范、设计指南），也可以是包含执行步骤的工作流。

Skill 五层来源

Skill 的关键特性

• 变量替换：Skill 内容支持 ${ARGUMENTS}（调用时传入的参数）和 ${CLAUDE_SKILL_DIR}（Skill 文件所在目录）等变量，实现模板化复用
• 内嵌 Shell：用 !`command` 语法嵌入 Shell 命令，在 Skill 被加载时同步执行并将输出替换进文本——例如 !`git branch --show-current` 会被替换为当前分支名
• Fork 执行：在 frontmatter 中设置 context: fork，该 Skill 将在独立子 Agent 中运行，不污染主会话上下文
• 延迟加载：设置 disable-model-invocation: true 后，Skill 不会出现在模型的候选列表中，只能通过用户手动 /skill-name 调用，最大限度节省上下文

MCP —— Model Context Protocol

MCP 是 Anthropic 于 2024 年推出的开放协议，解决的问题是：每个 LLM 应用都要独立开发与外部服务的集成（N 个 LLM × M 个服务 = N×M 个集成），MCP 将其降为 N+M。

MCP 三大原语

六种传输方式

连接状态机与容错

MCP 连接维护 5 个状态：disconnected → connecting → running → error → disconnected。在 running 状态下，每隔 30 秒向 Server 发送心跳日志，若 30 秒内无响应则标记为 error 并尝试重连。重连采用指数退避策略，最多重试 3 次后放弃并通知用户。

工具调用时，Claude Code 在日志中记录调用开始，每 30 秒输出一次"仍在等待"的进度日志，帮助用户判断是否卡住。工具命名遵循 mcp__serverName__toolName 约定，确保不同 Server 的同名工具不会冲突。

Prompt → Skill 桥接

MCP Server 提供的 Prompt 原语可以自动桥接为 Claude Code 的 Skill——这意味着外部服务不仅可以提供工具能力，还可以提供知识和工作流模板，让 Agent 知道"怎么用"而不仅仅是"能用什么"。

9️⃣ 终端渲染引擎

Claude Code 运行在终端中，但它的界面绝非简单的文字输出——它拥有一个完整的自研终端渲染引擎，使用 React 式组件模型驱动终端像素。这个引擎脱胎于 Ink 项目的思想，但经过了深度重写以满足 Agent 场景的特殊需求。

六阶段渲染管线

虚拟 DOM 体系

渲染引擎维护一棵虚拟 DOM 树，支持 7 种元素类型：

每个 DOM 节点维护一个 dirty 标记。当节点属性变化时，dirty 向上冒泡至根节点，下一帧渲染时只重新计算 dirty 子树的布局和渲染。

8 字节 Cell 压缩

终端的每个字符位置用一个 Cell 表示。Claude Code 将 Cell 压缩到仅 8 字节（2 个 Int32）：

DECSTBM 硬件滚动加速

传统做法是在内容滚动时重绘整个屏幕。Claude Code 使用 DECSTBM（DEC Set Top and Bottom Margins）终端转义序列，告诉终端模拟器"在第 M 行到第 N 行之间滚动"——终端硬件直接移动像素行，无需逐字符重绘。这使得长文本滚动的渲染开销降低约 40 倍。

事件系统

渲染引擎实现了完整的事件捕获/冒泡模型：

• 捕获阶段：事件从根节点向目标节点传播，各层可拦截
• 目标阶段：到达目标节点，触发事件处理器
• 冒泡阶段：从目标向根节点回溯，父节点可监听子节点事件
• 焦点管理：Tab 键循环切换焦点元素，维护焦点栈（弹窗打开时暂存旧焦点，关闭时恢复）

全屏 vs 普通模式

🔟 提示词工程实践

在 Agent 场景下，提示词工程的含义远超"写好 prompt"。Anthropic 总结的核心原则涵盖从用户交互到工具设计的完整链路。

四大核心原则

① 给 Agent 提供验证方式（最高杠杆）

这是 Anthropic 标注为 "single highest-leverage thing" 的建议。当 Agent 可以自我验证（运行测试、对比截图、校验输出）时，表现显著提升。

② 先探索、再规划、再编码

推荐的四阶段工作流：

• 探索：进入 Plan Mode，Agent 读取文件、回答问题，不做任何修改
• 规划：创建详细实现方案，可在编辑器中直接调整方案
• 实现：切回 Normal Mode，按方案编码，运行测试
• 提交：让 Agent 提交并创建 PR

③ 提供精确上下文

• 用 @file 引用文件实际路径，而非描述文件位置
• 直接粘贴图片、错误日志——让 Agent 看到你看到的
• 给出信息来源："查看 ExecutionFactory 的 git 历史，总结 API 演变"
• 引用已有模式："参考 HotDogWidget.php 的实现，做日历组件"

④ ACI 设计（Agent-Computer Interface）

Anthropic 提出 ACI 概念——类比 HCI（人机交互），ACI 是模型与工具之间的交互设计：

• 站在模型角度思考：工具描述和参数是否足够清晰？新手开发者能否仅凭描述正确使用？
• 防错设计：修改参数使错误更难发生。例如要求绝对路径而非相对路径
• 格式选择：给模型足够的思考空间；使用训练数据中常见的格式；避免不必要的编码开销（如 JSON 转义）
• 实测驱动：在 Workbench 中大量测试工具使用，观察错误模式并迭代

1️⃣1️⃣ Harness 系统工程

Claude Code 官方定位自身为 "agentic harness around Claude"——围绕 Claude 模型的代理骨架。Harness 是将语言模型从"能生成文本"转化为"能执行任务"的工程基座。

四层架构

关键工程决策

Hooks 生命周期钩子

Hooks 是在特定事件触发时执行的外部脚本，运行在模型之外（上下文成本为零）：

1️⃣2️⃣ 设计哲学与反模式

纵观 Claude Code 的整体架构，可以提炼出三个一以贯之的设计哲学，以及从实践中总结的关键反模式。

三大架构哲学

Ⅰ. 简单性至上

Agent 的核心就是"LLM + 工具循环"。Claude Code 没有引入复杂的有限状态机编排、规则引擎、或多层中间件——循环本身就是最强大的抽象。Anthropic 明确表达："最成功的 Agent 实现使用简单、可组合的模式，而非复杂框架。"

Ⅱ. 纵深防御

安全不依赖任何单一防线。从 prompt 约束 → 权限确认 → 安全分类器 → OS 沙箱 → AST 注入检测，每一层都假设上一层可能失败。这种"洋葱模型"确保即使被提示注入攻击突破了某一层，后面的层仍然有效。

Ⅲ. 约束中的工程极致

终端是一个极度受限的输出环境——固定列宽、无像素级渲染、有限的颜色支持。Claude Code 不是绕过这些约束，而是在约束内做到极致：8 字节 Cell 压缩、硬件滚动加速、差量更新。类似地，上下文窗口是有限的，但通过分层加载、三级压缩、自动恢复，最大限度利用每一个 token。

Anthropic 五大 Workflow 模式

Claude Code 中的模式映射

五大反模式

高效协作原则

• 委派而非指令：像委派给能干的同事——给上下文和方向，信任 Agent 搞定细节
• 早纠正、勤纠正：发现偏离立即 Esc 中断并重定向，不要等到结束
• 干净会话 > 长会话：一个好的初始 prompt + 干净上下文，几乎总是胜过积累了大量纠正的长会话
• 发展直觉：观察成功时的结构和模式，失败时诊断原因（上下文太脏？任务太大？prompt 太模糊？）

1️⃣3️⃣ 后台任务与 Dream 系统

Claude Code 不只是一个「你问我答」的工具。它可以在后台默默干活：一个 Agent 在后台搜索代码、一个定时任务每小时检查构建状态、或者一个 Dream 任务在空闲时整理记忆。前台对话是你和秘书面对面沟通，后台任务是秘书回到办公室帮你做的事——做完了给你发个通知。

后台 Agent 执行模型

后台 Agent 和前台 Agent 运行的是完全相同的 query() 循环，区别在于：

• 独立 AbortController：前台中断不会影响后台任务
• 输出写入磁盘：不实时显示在终端，结果通过 <task-notification> XML 通知送达
• 不可弹窗：权限请求会被自动拒绝（无用户交互）
• 不阻塞主流程：主 Agent 可以继续处理新对话

能在后台运行的任务类型包括：LocalAgentTask（AI Agent，用户创建或 Ctrl+B 切换）、LocalShellTask（长时间运行的 Bash 命令自动后台化）、RemoteAgentTask（云端执行，天生后台）、InProcessTeammateTask（队友 Agent）、DreamTask（记忆整理）。

前台 ↔ 后台切换

Agent 可以在前后台之间无缝切换。用户按 Ctrl+B 将当前对话的 Agent 放入后台（isBackgrounded: true），然后可以开始新对话。后台 Agent 完成后生成 XML 通知插入到主 Agent 的消息队列，主 Agent 在下一轮循环时读到通知即可继续工作。

DreamTask：记忆整理

Dream 是一种特殊的后台任务，在用户空闲时自动触发，功能是复盘之前的对话、整理分散的记忆。就像人在睡觉时大脑会整理白天的记忆一样。

• 两个阶段：starting（读取对话历史、分析需要整理的记忆）→ updating（更新/创建记忆文件，最多 30 轮）
• 静默完成：不发通知给用户，标记 notified=true 即结束
• 可回滚：如果被用户中断（abort），会恢复整理锁的时间戳，下次可重新整理

Cron 定时调度

内置了基于 cron 表达式的定时调度器。定时任务分为持久化任务（存储在 .claude/scheduled_tasks.json，重启后仍在）和会话级任务（内存中，关闭即消失）。

• 调度器核心：每秒检查一次所有定时任务，到时间则触发
• 防雷群效应（Jitter）：加入随机延迟——重复任务延迟间隔的 10%（上限 15 分钟），一次性任务最多提前 90 秒
• 多会话互斥：通过 .claude/scheduled_tasks.lock 文件锁保证同一定时任务不会被多个窗口重复触发
• 管理工具：CronCreate（创建）、CronList（列出）、CronDelete（删除）

远程后台 Agent

大型任务可以在云端执行，不占用本地资源。远程 Agent 通过轮询获取进度更新，可以访问 GitHub 仓库（需安装 GitHub App），支持 --resume 恢复连接。前提条件：已登录 claude.ai、有远程环境访问权限、在 Git 仓库中、策略允许远程会话。

1️⃣4️⃣ Team/Swarm 协作体系

前面讲的「子 Agent」是临时的——干完活就没了。而 Team（团队）是一种持久的多 Agent 协作模式：一个 Leader（组长）创建团队，招募多个 Teammate（队友），它们各自独立运行，通过邮箱系统通信，遇到需要审批的操作向 Leader 请示。子 Agent 像临时帮忙的朋友，Team 像你组建的项目组——有组长、组员、通讯群、审批流程。

团队生命周期与配置

• 创建：TeamCreate("research-team") → 生成配置文件 ~/.claude/teams/{name}/config.json
• 招募：通过 Agent({ name, team_name, ... }) 创建 Teammate，Agent ID 格式为 名字@团队名（如 researcher@research-team）
• 运行：每个 Teammate 独立上下文、独立 AbortController、独立消息历史
• 解散：TeamDelete() → 检查所有 Teammate 已停止 → 清理团队目录和任务目录

邮箱系统：团队通信中枢

团队成员通过统一的邮箱系统通信，支持两种模式：

• In-Process（进程内）：同一 Node.js 进程内，通过内存中的 Mailbox 类直接投递（无文件 I/O），使用 AsyncLocalStorage 实现上下文隔离
• Tmux/iTerm2（终端面板）：每个 Teammate 是独立的 Claude Code 进程，通过文件系统通信（.ndjson 文件）

消息类型包括：permission_request/response（权限请求与回复）、plan_approval_request/response（计划审批）、sandbox_permission_request（网络权限）、shutdown_request（优雅关闭）、mode_set_request（权限级别设置）、普通文本消息。Leader 通过 useInboxPoller 每秒轮询一次收件箱，分类路由消息。

权限同步与计划审批

当 Teammate 需要执行危险操作（如 rm -rf）：先尝试分类器自动判断 → 无法自动判断则发送权限请求给 Leader → Leader 弹窗给用户 → 用户允许/拒绝 → 回调触发继续或中止。权限请求持久化到 ~/.claude/teams/{team}/permissions/ 目录（pending/resolved）。

配置为 planModeRequired: true 的 Teammate 必须先提交计划、得到 Leader 审批后才能执行。安全设计：只有 team-lead 发出的审批才会被接受。

Coordinator vs Team 模式

团队记忆与内存管理

团队有共享记忆空间（~/.claude/projects/<项目>/memory/team/），记忆归属规则：user 类永远个人、project 类倾向团队、API 密钥等敏感信息永远不写入团队记忆。

为防止内存溢出，UI 层只保留每个 Teammate 最近 50 条消息（TEAMMATE_MESSAGES_UI_CAP = 50），完整历史存磁盘。实测发现 292 个 Agent 的大型会话可占用 36.8GB 内存。

1️⃣5️⃣ 桌宠系统

Claude Code 里藏着一个完整的电子宠物系统。每个用户根据自己的 ID 生成一只独一无二的 ASCII 小动物——蹲在输入框旁边，会眨眼、戴帽子、冒爱心，还会对你的对话内容冒出评论。这是一个包含稀有度系统、属性面板、动画引擎和 AI 观察者的完整游戏化设计。

确定性抽卡：从用户 ID 到宠物

每个用户的宠物不是随机的——同一用户永远生成同一只。通过 hash(userId + 'friend-2026-401') 作为种子，使用 mulberry32 确定性伪随机数生成器，依次「掷骰子」确定稀有度、物种、眼睛、帽子、闪光、属性。设计意图：杜绝刷号。

• 18 种物种：🦆鸭子、🐱猫、🐉龙、🐙章鱼、🦉猫头鹰、🐧企鹅、🐢乌龟、🐌蜗牛、👻幽灵、🤖机器人等
• 5 级稀有度：★ Common 60% → ★★ Uncommon 25% → ★★★ Rare 10% → ★★★★ Epic 4% → ★★★★★ Legendary 1%
• 5 项属性：DEBUGGING 调试力、PATIENCE 耐心、CHAOS 混沌、WISDOM 智慧、SNARK 毒舌（1-100），一项特长+一项短板+其余随机
• 闪光（Shiny）：1% 概率，类似宝可梦色违

ASCII 精灵图与动画引擎

每只宠物占 5行×12字符，有 3 帧动画。帧循环每 500ms 切换一帧，大部分时间静止（IDLE_SEQUENCE），偶尔摇尾巴或眨眼。三种状态：空闲（按序列循环）、说话（快速循环所有帧模拟嘴巴动）、被摸（快速循环+爱心动画，持续 2.5 秒）。

高稀有度宠物佩戴帽子（王冠 \^^^/、礼帽 [___]、巫师帽 /^\ 等），眼睛样式包括 · ✦ × ◉ @ °。当终端宽度不足 100 列时，精灵图退化为单行表情符号（如鸭子 (·>、猫 =·ω·=、龙 <·~·>）。

AI 观察者与对话气泡

每轮对话结束后，系统调用一个独立的 AI 观察者（fireCompanionObserver）来生成宠物评论，显示在气泡中约 10 秒后渐隐消失。关键设计：宠物不是主 AI 的分身——它是一个独立的「观察者」。System Prompt 明确告知主 AI：「你不是它，别替它说话」，让两个角色各自独立。

数据持久化与 Feature Flag

只存「灵魂」不存「身体」：持久化数据仅包含 AI 起的名字、性格描述和孵化时间戳，身体属性（稀有度/物种/眼睛/帽子/闪光/属性值）每次启动根据 userId 重新计算。整个系统由编译时 feature('BUDDY') 控制，关闭时代码被完全移除（dead code elimination），零运行时开销。