Claude Code安装使用及Agent相关架构问题分析

本文详细介绍Claude Code在windows上安装使用，对于一般非计算机行业用户或者对底层技术了解兴趣不深的可以只看：1、第一部分Claude Code简单使用；2、Claude Code进阶使用；3、Claude Code底层原理中的Skills开发。

Claude Code简单使用

安装环境准备

目前大部分的skill或者说Clade Code运行任务（比如说读取文件等）都会用到python，因此就需要去安装python，除此之外如果要去安装一些skills还需要权重npm等，因此：在win电脑上更加建议直接使用wsl去搭建Claude Code，WSL安装方式，安装完毕之后其他命令就和linux安装命令相同，先去介绍基于WSL安装claude过程，执行如下命令：

对于配置DeepSeek：配置DeepSeek订阅

# ========== 1. 基础系统依赖 ==========
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential python3 python3-pip python3-venv curl wget unzip git-all

# ========== 2. 安装 nvm + Node.js ==========
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
# 重新加载 shell 配置
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install 26
node -v
npm -v
npm config set registry https://registry.npmmirror.com

# ========== 3. 安装 Miniconda ==========
wget https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/Miniconda3-latest-Linux-x86.sh
bash Miniconda3-latest-Linux-x86.sh -b   # -b 静默安装，跳过交互
~/miniconda3/bin/conda init bash
source ~/.bashrc

# ========== 4. 安装 Claude Code ==========
curl -fsSL https://claude.ai/install.sh | bash
# 确保 PATH 包含 ~/.local/bin（只添加一次）
grep -q 'export PATH="$HOME/.local/bin:$PATH"' ~/.bashrc || \
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# ========== 5. 配置 DeepSeek API ==========
mkdir -p ~/.claude
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-你的DeepSeek-API-Key",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_MODEL": "deepseek-v4-pro"
  },
  "autoUpdatesChannel": "latest",
  "theme": "dark"
}
EOF

# ========== 6. 安装 rtk ==========
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
source ~/.bashrc
rtk init --global

对于WSL后续使用直接在终端里面输入 wsl 然后输入 claude 即可

安装与卸载

⭐在win电脑上更加建议直接使用wsl去搭建Claude Code，WSL安装方式，安装完毕之后其他命令就和linux安装命令相同

以win电脑为例按照官方过程直接输入命令即可，对于桌面端安装直接访问链接然后安装即可，对于终端安装参考链接首先安装 git然后直接终端（win+r 然后输入 cmd）执行安装即可：curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd或者直接：

打开 PowerShell然后输入安装命令：irm https://claude.ai/install.ps1 | iex
处理报错，如果遇到如下报错：

解决措施：（理论上）直接将VPN节点换到美国即可
处理报错，如果遇到报错 Failed to fetch version from https://downloads.claude.ai/claude-code-releases/latest: ECONNREFUSED

解决措施：将VPN开启虚拟网卡模式或者直接将VPN开全局代理即可
最后终端中出现如下界面表示安装完成

值得注意的是里面提到：Native installation exists.....，这是因为没有配置好系统环境变量，直接win+r然后输入 sysdm.cpl

点击确认即可完成环境变量配置处理。然后终端直接输入 claude
卸载过程就比较简单直接去删除对应文件即可，为了节约token选择直接安装rtk，首先下载对应文件并且解压（记住解压的路径），解压完成之后将对应文件添加到环境变量中（过程和上面配置claude code环境变量相同），然后 rtk.exe init --global（如果不行就直接输入D:\ClaudeCode\rtk.exe init --global，前面的路径为你解压路径）运行之后就可以开启节约token，值得注意的是如果环境变量添加了，终端输入 rtk 没有效果可以直接去 C:\Users\hjie\.claude\settings.json 里面修改配置，将里面的hook修改为

配置其他API

以DeepSeek配置过程为例，打开目录 C:\Users\hjie\.claude 然后

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-",
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro",
    "ANTHROPIC_MODEL": "deepseek-v4-pro"
  },
  "autoUpdatesChannel": "latest",
  "theme": "dark"
}

在配置完毕之后，打开 Powershell然后执行 claude

基础命令

在终端中所有的命令可以直接输入 / 来进行执行比如说切换模型 /model 然后按不同箭头选择模型（enter 回车选择模型），或者直接使用 @ 去访问文件等，简单使用过程中一般而言用的比较多的几个命令：1、/compact：去压缩对话，一般而言模型上下文有限去对上下文进行压缩

> /compact
# 基本压缩：将历史对话总结为关键要点
> /compact 保留认证模块的变更细节和当前测试失败信息
# 定向压缩：指定需要保留的重点内容

2、clear：完全重置，清空当前会话的全部对话历史和上下文，回到初始状态；3、/context查看上下文使用，显示当前上下文的占用情况和分类统计。除了基础命令之外有些时候还需要去控制claude 在执行一些 简单安全任务（比如说去搜索整理文件这些任务）在启动时候可以直接开启 claude --permission-mode auto强制自动判断需不要询问用户（一定要让他执行可信任务，不然可能删除一些重要东西导致出现错误，可以先去跑通一个任务之后，后续再去实现类似任务可以直接开启强制自动判断）或者直接在对话系统里面按键 shift+tab进行切换（直接切换到 auto mode on即可）：

而后再去执行 /sandbox（建立一个 沙盒隔离环境避免直接操作自己电脑导致误删文件等）

除此之外要监控各类task任务（比如说有些python自动脚本会到建立task）进行情况可以直接安装：npx claude-task-viewer然后就可以看到正在进行进程：

除此之外有些时候可能需要一次性进行多个任务（比如说去搜索A相关事情、搜索B相关事情）可以执行claude agents，这样就可以快速进行多组对话进行切换（或者直接在对话系统里面直接按箭头左右也可以）

插件安装

比如说安装用量检查插件或者安装superpowers：/plugin install superpowers@claude-plugins-official

MCP

MCP简单理解为赋予Claude Code工具调用权限，比如说想让Claude Code去收索文书等
比如说安装playwright（直接用自然语言描述你想做的事，而后调用对应的浏览器操作）：claude mcp add playwright npx @playwright/mcp@latest如果要卸载直接claude mcp remove playwright，安装完毕之后

可以看到MCP已经启动了，如果要去使用这个MCP直接 使用 playwright 打开浏览器访问 https://www.big-yellow-j.top/posts/2026/04/20/torch-basic-distribute-1.html 并且检查还有什么需要补充的分布式训练方式，以及内容上还有什么不足 去让Claude Code去调用playwright的MCP。

Skills使用

skills简单理解为一个可以复用的任务prompt（比如说创建PPT）不用每次都去重新写prompt直接通过skills进行复用即可，如果要去找其他的Skills直接可以访问：https://www.skills.sh/或者直接去安装find-skills让其帮你自动去搜索一些skills，

安装前简单了解一下skills有“两个目录”：1、项目目录（那么你的skills就只在这个项目起到效果），比如直接在你的文件夹里面进行打开就会访问项目目录比如说 D:\ClaudeCode\.claude；2、根目录（所有项目都可以用到这个skills），这个就是你的claude code安装目录比如说：C:\Users\hjie\.claude

第一种、安装他人skills¹有如下几种：1、复制文件夹直接将别人skills所有内容复制到skills目录下即可，2、直接下载，以获取微信文章为例直接访问地址然后搜索wechat-article-extractor在得到安装命令npx skills add https://github.com/freestylefly/wechat-article-extractor-skill --skill wechat-article-extractor在你的终端进行安装即可，安装完过程中可能要选择是 project 还是 global 根据提示进行选择即可

需要安装npm，安装方式参考：链接

安装完毕之后skills触发有两种：1、自动进行触发，比如在上述skills中有description字段

当你在claude中输入 提取微信文章：https://mp.weixin.qq.com/s/8axsDd-vY247Nd3oPZ9_zQ 他就会自动触发这个skills进行处理

2、手动触发，可以直接在 claude中输入 ‘/we’ 会在下面触发联想，然后通过箭头选择自己需要内容直接按 tab 补全命令

第二种、自定义skills：直接去看别人skills怎么写的然后进行修改即可，或者直接让claude code写skills

搜索自动化

一般而言在工作中可能需要去调研（比如说搜集论文、收集相关数据集等），推荐直接使用 crawl4ai 去自动搜索爬取内容，可以直接使用他的skills然后放到自己的目录下面，然后再终端中执行claude --permission-mode auto，然后输入自己要求：

最后输出结果（任务比较费时用来12min52s完成）

通过上面一轮对话处理下来token消耗

Agent Team协作

一般而言在使用claude code进行对话时候，都是执行一个任务，在等待结果之后再去执行一个新的任务，比如说法律一个案子需要同时去收集案子以及法条然后再去对材料进行整理，这里就需要用到agent team概念，简单介绍Agent team概念参考里面对于subagents和agent teams之间对比²：

两者之间差异点在于subagents相当于一个老师将任务分配给几位学生然后学生给老师一个反馈，agent teams相当于老师给学生分配任务，学生之间还在不断交流，那么以长沙货拉拉案为例，以一个法律从业者出发（本人非专业人员）去构建一个agent team来解决这个案子，首先本地创建一个文件夹然后执行claude code

mkdir CSHuolala # 创建文件夹
mkdir .claude   # 创建文件夹
echo '{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}' > /home/hjie/ClaudeCode/CShuolala/.claude/settings.json # 相当于写入文件
 claude --permission-mode auto --teammate-mode in-process  # teammate-mode 控制显示模式

# 测试的提示词是
为货拉拉案法庭辩护材料准备材料辩护词
1、任务 A：证据审查与现场环境重构（由 Evidence-Agent 认领）
2、任务 B：刑法因果关系与无罪/罪轻辩护词起草（由 Criminal-Law-Agent 认领）
3、任务 C：被害人过错分析及同行案例检索（由 Case-Search-Agent 认领）
4、任务 D：最后对辩护词进行审查（有Lawer-Agent认领）
执行顺序上首先执行任务A而后并行执行B和C，最后执行D
辩护词合适标准：1、辩护词合乎法律文书书写；2、所有收集材料都在本地文件夹保存；3、法律必需都有自己出处

值得注意的是上面任务都是基于网络进行搜索，实际情况可能需要对自己具体材料（比如说收集的材料）进行处理，可能就需要用到其他skills/mcp工具，在规划任务时候越详细越好（更加好控制模型）

可以看到目前之后一个 Evidence-Agent 在执行工作，可以直接通过键盘↓去进入 @main @Evidence-Agent然后键盘←→箭头进行跳装查看工作如何，或者直接通过npx claude-task-viewer然后进入对应网页查看如下：

那么在Evidence-Agent中执行效果如下：

很明显看到执行 争取审查+任务重构符合我的任务A要求，A执行完毕就会进行BC比如说得到如下：

可以看到另外两个agent也开始执行了，最后所有的整理的材料以及最后的书写得到的辩护词在百度网盘总共是花费了大概4元（DeepSeek-4-pro）

Claude Code工具开发

Skills开发

最简单方法直接看别人怎么写然后进行仿写即可

以crawl4ai提供的skills为例，参考这个例子规范文书写作skills（大部分内容基于AI出发，不一定符合实际法律工作内容），首先介绍如何去定义自己的skills而后去介绍在claude code中如何去定义自己的skills，比如说在crawl4ai文件中主要是如下几个文件³（不同skills可能差异，比如crawl4ai可能还有references）：

my-skill/
├── SKILL.md           # 主要说明（必需）
├── template.md        # Claude 要填写的模板
├── reference.md       # 详细介绍API使用文档，比如说在scripts里面会提前告诉我的模型运行scripts需要哪些参数
├── examples/
│   └── sample.md      # 显示预期格式的示例输出
└── scripts/
    └── validate.sh    # Claude 可以执行的脚本

首先核心内容就集中在 SKILL.md文件中，简单介绍一下他的 模板描写方式：

---
name: api-conventions
description: API design patterns for this codebase
---

When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats
- Include request validation

首先对于上述模板中 --- 之间内容表示提前告诉我的模型这个 skills的一些基本配置，他一般有如下字段：

其实对于上述字段中最核心的就是：1、description：告诉模型这个skills都是干什么的；2、name：告诉模型你的skills叫什么（如果没有他就会用上层的文件夹名称），除此之外其他的也可以去注意一下使用（具体描述看上面的表格里面描述）：disable-model-invocation，在定义完skills中yaml之后就是关于第二部分，prompt书写（这部分其实就是相当于你将你一贯的prompt直接机械的告诉大模型，让他按照你这个内容去机械的进行操作），回到最上面去实现一个规范文书写作skills（很粗糙具体内容可能需要具体修改），首先明确我的skills都需要哪些内容：1、定义名称（legaldocnorm）；2、定义一些小的脚本工具，比如说对于文档（假设为docx文件）需要让模型去打开文件就需要一些脚本；3、其他。按照上述内容开始一个skills创作（全部基于wsl上，有些命令都是linux命令可以自然的转化到win上，比如创建文件夹）。
第一步、去构建一个所有文件“系统”以及大致SKILL.md文件（头部信息推荐英文，后续内容中英都行）最后所有文件见Github链接
第二步、去构建我的脚本 script（不会写直接让AI帮你写即可），最后的script见Github链接
第三步、去构建一个reference，因为法律文书在书写上比较规划，模型可能不知道具体如何书写可以简单给一个参考让模型规范输出（规范文本可以直接用最高法院提供模板），这里只提供两种规范文本供参考：1、广州市海珠区人民法院——民事答辩状；2、广州市海珠区人民法院——民事起诉状)，最后所有的reference见Github链接
skills底层原理：还是一个function calling，所谓 function calling比如说：“北京今天天气如何？”输入模型模型（大模型本身只能输出文本不能去搜索网页等功能）通过分析用户文本输出结构化信息：{"name": "get_weather", "arguments": {"date":xxx, ....}} 而后通过结构化信息进行工具调用（比如说调用搜索天气相关的API进行天气检索）。因此虽然claude code中skills都是文本prompt，大模型在检索到要使用的skills之后通过分析skills中内容自动解析处需要进行操作，因此claude code中skills底层就是：Prompt+Tool Description+ Few-shot examples+ Execution

MCP 开发

Claude Code抓包

简单网络抓包

为了分析Claude Code中每一步系统层都在发生什么就需要最Claude Code进行抓包，具体过程如下，首先对环境进行配置（基于wsl）：

# 基于wsl
conda create -n mitm python=3.11
conda activate mitm
pip install mitmproxy
mitmweb --listen-host 0.0.0.0 --listen-port 9870 # 8080 为代理端口 cc走这里 8081 web ui看流量

# 新建窗口
export http_proxy=http://0.0.0.0:9870
export https_proxy=http://0.0.0.0:9870
export HTTP_PROXY=http://0.0.0.0:9870
export HTTPS_PROXY=http://0.0.0.0:9870
export ALL_PROXY=http://0.0.0.0:9870
export NODE_EXTRA_CA_CERTS=~/.mitmproxy/mitmproxy-ca-cert.pem
export SSL_CERT_FILE=~/.mitmproxy/mitmproxy-ca-cert.pem
claude --permission-mode auto

在启动完毕之后，可以看到终端

而后直接去Claude code随便测试：1、你好；2、/crawl4ai 搜索一下Yolo系列论文，直接去终端里面提供的url地址然后可以直接~c 200（因为访问 https://api.anthropic.com/api/event_logging/v2/batch 可能会有很多失败会显示400，因此重点看一下链接成功的），比如说通过解析：

在输入第一段对话 你好 模型会输入很多内容如tools/skills描述等，但是这些内容绝大部分会“命中缓存”（观察deepseek中就有这种内容）⁴

所谓命中缓存意思就是说：这部分内容不用模型去重新计算可以直接复用，这是因为大模型生成过程是prefill+decode，prefill阶段就是对我的prompt进行编码，比如说上面输入模型是一个结构化文档，在vllm的cache逻辑中会将输入token进行block处理（比如每个block存储n个token）当出现block相同时候就会复用结果（必须保证如：输入1：QWERASDF和输入2：QWERASDF此时可以命中缓存，但是如果输入1改成WQERASDF就不行，因此为了更加大的命中缓存会直接将容易命中缓存输入放到模型输入前面如tools、system等），而decode就是对prefill后内容开始解码一个token一个token进行输出，即使如此还是建议如果skills不用就不要开启

而后可以看模型输出部分think+输出：

而后在第二部分对话中 /crawl4ai 搜索一下Yolo系列论文 首先可以看模型终端输出：

模型进行如下4次对话处理：
1、任务重写：从模糊到精确（第 1-3 轮）
第 1 轮：输入“搜索 Yolo 论文”，模型携带了 crawl4ai 的技能定义。
关键转折（你发现的 1 & 2 点）：crawl4ai生成了两个极其精确的搜索关键词：YOLO series papers object detection survey 2024 2025（针对综述）；YOLOv1 to YOLOv12 paper list arxiv（针对列表）
第 2-3 轮： 框架将这两个“进阶关键词”重新喂回给模型。这时，模型不再是处理你那个模糊的原始需求，而是拿到了已经被优化过的检索指令。目的： 这就是 Query Expansion（查询扩展）。Agent 知道直接搜“Yolo 论文”结果太乱，所以先把它拆解成“搜综述”和“搜最新版本列表”两个子任务。
2、执行与回传（第 4 轮）
动作： 携带了这两个精确关键词的对话被送入 web_search 工具。
结果： 搜索引擎返回了你看到的那一串包含 YOLOv1 到 YOLOv26 的 Arxiv 链接和详细摘要。
总结： 最终 DeepSeek 拿到这些被精准定位后的素材，进行最后的整合输出。

值得注意的是,web_search返回内容还是通过模型/工具进行总结的，比如说一个搜索得到5-6结果模型进行总结即可

抓包分析功能

通过上面抓包方式可以进一步去分析claude code中其中功能比如说 /compact，/resume 等，抓包分析resume：终端执行 /resume 之后而后直接输入新的内容在claude code直接加载历史对话而后补充到上下文中比如所大致结构如下：

{
    "model": "deepseek-v4-pro",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            历史用户输入对话信息
          },
          {
            新的对话信息
          }
        ],
        .....
      }

在新的对话信息里面也会直接加载启用的skills等以及后续模型的tools也会加载（和第一次对话加载信息相同只是多了一组用户历史信息），但是这里简单介绍一些claude code中是如何去缓存对话信息的在路径 ~/.claude 中文件结构如下，对于每一组对话都会存储在 history.jsonl 中每组对话结构为 {"display":"你是什么模型","pastedContents":{},"timestamp":1780404540849,"project":"/home/huangjie/MdiriCode/Claude","sessionId":"5186f729-1c6e-4698-99e6-7ad2cd667cde"} 最后的sessionid对应每次对话的id信息，都会在 sessions文件夹（主要是记录上下文对话信息）中记录⁵

除此之外在projects文件夹中还会记录更加多内容，其大致结构如下：

projects/
 ├── sessionid.jsonl   # 区别于上面 session 里面只记录对话信息，此sessionid.jsonl则是记录所有 “日志记录”，比如说  {"type":"permission-mode","permissionMode":"auto","sessionId":"b69647ef-a95b-428d-a0ac-530440c7853f"}
 ├── memory/
 ├── subagents/
 ├──── xxxx.meta.jsonl # 主要记录 subagets 具体信息比如说：{"agentType":"claude-code-guide","description":"Explain Claude Code compaction","toolUseId":"call_00_0UXP3yM5PsH4VZ2ZbA1c5929"}
 ├──── xxxx.jsonl      # 子agents产生对话信息

主要介绍一些subagents，在claude code中一般是 主agent收到信息去分发给不同子agent，而后将子agent信息接收进行总结分析等（具体构建等见下面分析）。简单总结一些子agents：1、子代理只是向Anthropic发出的独立请求，每个请求都有自己的系统消息。 2、每个子代理都有自己的上下文窗口。它不会与其他子代理或主代理共享内存或聊天记录。 3、“主”Claude（委托代理）为子代理编写提示词，该提示词最终将成为子代理收到的第一条用户消息。 子代理完成任务后，会将其发现的摘要发送回主Claude，随后主Claude会尝试整合所有报告并对其进行解读。 在不断积累上下文之后就需要考虑对内容进行压缩，在claude中压缩过程有两种：1、直接 /compact；2、输入对应文本 /compact xxxx对于两种压缩方式通过抓包分析发现使用的提示词都是大致相同的（更加具体的压缩过程见后续分析）具体的压缩提示词如下：

CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.

- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
- You already have all the context you need in the conversation above.
- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
- Your entire response must be plain text: an <analysis> block followed by a <summary> block.

Your task is to create a detailed summary of the conversation so far, paying close attention to the user's explicit requests and your previous actions.
This summary should be thorough in capturing technical details, code patterns, and architectural decisions that would be essential for continuing development work without losing context.

Before providing your final summary, wrap your analysis in <analysis> tags to organize your thoughts and ensure you've covered all necessary points. In your analysis process:

1. Chronologically analyze each message and section of the conversation. For each section thoroughly identify:
   - The user's explicit requests and intents
   - Your approach to addressing the user's requests
   - Key decisions, technical concepts and code patterns
   - Specific details like:
     - file names
     - full code snippets
     - function signatures
     - file edits
   - Errors that you ran into and how you fixed them
   - Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
   - Note any security-relevant instructions or constraints the user stated (e.g., sensitive files or data to avoid, operations that must not be performed, credential or secret handling rules). These MUST be preserved verbatim in the summary so they continue to apply after compaction.
2. Double-check for technical accuracy and completeness, addressing each required element thoroughly.

Your summary should include the following sections:

1. Primary Request and Intent: Capture all of the user's explicit requests and intents in detail
2. Key Technical Concepts: List all important technical concepts, technologies, and frameworks discussed.
3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created. Pay special attention to the most recent messages and include full code snippets where applicable and include a summary of why this file read or edit is important.
4. Errors and fixes: List all errors that you ran into, and how you fixed them. Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts.
6. All user messages: List ALL user messages that are not tool results. These are critical for understanding the users' feedback and changing intent. Preserve any security-relevant instructions or constraints verbatim so they remain in effect after compaction.
7. Pending Tasks: Outline any pending tasks that you have explicitly been asked to work on.
8. Current Work: Describe in detail precisely what was being worked on immediately before this summary request, paying special attention to the most recent messages from both user and assistant. Include file names and code snippets where applicable.
9. Optional Next Step: List the next step that you will take that is related to the most recent work you were doing. IMPORTANT: ensure that this step is DIRECTLY in line with the user's most recent explicit requests, and the task you were working on immediately before this summary request. If your last task was concluded, then only list next steps if they are explicitly in line with the users request. Do not start on tangential requests or really old requests that were already completed without confirming with the user first.
If there is a next step, include direct quotes from the most recent conversation showing exactly what task you were working on and where you left off. This should be verbatim to ensure there's no drift in task interpretation.

Here's an example of how your output should be structured:

<example>
<analysis>
[Your thought process, ensuring all points are covered thoroughly and accurately]
</analysis>

<summary>1. Primary Request and Intent:
   [Detailed description]

2. Key Technical Concepts:
   - [Concept 1]
   - [Concept 2]
   - [...]

3. Files and Code Sections:
   - [File Name 1]
      - [Summary of why this file is important]
      - [Summary of the changes made to this file, if any]
      - [Important Code Snippet]
   - [File Name 2]
      - [Important Code Snippet]
   - [...]

4. Errors and fixes:
    - [Detailed description of error 1]:
      - [How you fixed the error]
      - [User feedback on the error if any]
    - [...]

5. Problem Solving:
   [Description of solved problems and ongoing troubleshooting]

6. All user messages: 
    - [Detailed non tool use user message]
    - [...]

7. Pending Tasks:
   - [Task 1]
   - [Task 2]
   - [...]

8. Current Work:
   [Precise description of current work]

9. Optional Next Step:
   [Optional Next step to take]

</summary>
</example>

Please provide your summary based on the conversation so far, following this structure and ensuring precision and thoroughness in your response. 

There may be additional summarization instructions provided in the included context. If so, remember to follow these instructions when creating the above summary. Examples of instructions include:
<example>
## Compact Instructions
When summarizing the conversation focus on typescript code changes and also remember the mistakes you made and how you fixed them.
</example>

<example>
# Summary instructions
When you are using compact - please focus on test output and code changes. Include file reads verbatim.
</example>


REMINDER: Do NOT call any tools. Respond with plain text only — an <analysis> block followed by a <summary> block. Tool calls will be rejected and you will fail the task.

Agent架构问题

上面无论式skills涉及还是tools使用其实都会带来很多Agent底层设计问题比如说：1、上下文工程（Context Engine） 随着用户不断对话那么对话历史就会不断变长，如果将对话历史全部塞到对话窗口里面就会导致上下文过长问题（导致模型可能丢失/处理不好）；2、tools如果没有命中怎么办？ 等等诸如此类问题，因此下面对Agent设计过程中会遇到问题以及架构设计上内容进行介绍

Cache机制

最上面简单介绍一下缓存机制，通过相同cache缓存命中去选择复用，不过值得注意的是虽然在对话过程中（进行抓包分析）每次用户输入都是在最上面，但是模型会将这些信息进行编排 tools + system+ messages这种方式，保存缓存命中。 在不同模型中缓存命中方式存在些许差异，比如说：1、DeepSeek缓存命中机制：；2、Claude缓存命中机制
https://grok.com/c/b083cb5c-cf7a-40dd-8890-6998438f3d2a?rid=7f9573b4-b0ac-44f8-baa5-015f9f9caf5e
https://zhuanlan.zhihu.com/p/17239625983

Context Engine

所谓上下文工程指的是，随着用户之间对话那么窗口token就肯定会超出模型限制（比如DeepSeek的1M），那么就需要对历史对话进行处理如压缩等（不过值得注意的是假设模型上下文窗口是1M在claude code中不会将所有上下文都用完才会去压缩，会设定阈值进行压缩，比如说达到80%自动进行压缩），以如下代码为例：

from openai import OpenAI
client = OpenAI(api_key="xxx",base_url="https://api.deepseek.com")
messages = [
    {
        "role": "system",
        "content": "你是一个专业AI助手"
    }
]

while True:
    user_input = input("User: ")
    if user_input.lower() == "exit":
        break

    messages.append({
        "role": "user",
        "content": user_input
    })
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=messages,
        temperature=0.7
    )
    assistant_reply = response.choices[0].message.content
    messages.append({
        "role": "assistant",
        "content": assistant_reply
    })
    print("User:", user_input)
    print("\nAssistant:", assistant_reply)

模拟进行对话最后得到输出文本:

[{'content': '你是一个专业AI助手', 'role': 'system'},
 {'content': '我是小红来自美国，我现在问你一些问题请不多于100个字进行输出，请简单介绍一下北京和上海', 'role': 'user'},
 {'content': '北京是中国的首都，历史悠久，拥有故宫、长城等著名景点；上海是国际大都市，以现代金融和繁华商业闻名，外滩、东方明珠是标志性地标。',
  'role': 'assistant'},
 {'content': '北京和上海两个城市哪一个更加推荐我去？', 'role': 'user'},
 {'content': '这取决于你的旅行偏好。如果你喜欢历史文化，推荐北京，可以探索故宫、长城和胡同。如果你偏爱现代都市与商业氛围，上海更合适，有外滩、陆家嘴和时尚购物区。',
  'role': 'assistant'},
 {'content': '我想去看无人机表演推荐去哪个城市？深圳怎么样？', 'role': 'user'},
 {'content': '深圳是中国无人机表演最出色的城市之一，常有大疆等企业举办大型灯光秀。若想看科技感强的表演，深圳是首选。北京和上海也有相关活动，但深圳更具创新氛围。',
  'role': 'assistant'},
 {'content': '我是谁来自哪里？', 'role': 'user'},
 {'content': '你叫小红，来自美国。', 'role': 'assistant'}]

下面简单介绍几种常见的上下文压缩方式⁶:
1、Claude Code上下文压缩方案：比如说在上面抓包分析Claude Code的压缩过程就可以看到他所使用的压缩提示词，但是实际过程中不可能全部只通过压缩提示词进行上下文压缩，参考对Claude Code的逆向分析⁷简单总结其压缩方案：优先使用廉价规则清理，再到轻量摘要，最后才进行昂贵的 LLM 总结。廉价处理过程（对话持续进行持续压缩避免占用上下文）：将部分特定工具（比如说文件读取，那么就会获取很长的上下文）输出进行压缩，直接简化将文件内容缓存本地，并且只生成简单预览以及本地路径（通过预览如果需要复用直接通过路径再去获取文件信息）。 模型压缩过程（手动/自动执行压缩命令执行）：直接通过提示词去对所有的对话历史进行压缩（具体提示词见上面抓包得到的）。最后输出<analysis> + <summary> 两层⁸，其中<analysis>：允许模型在内部把对话按时间线梳理一遍，减少遗漏，<summary>：对外提供结构化的最终压缩结果，便于机器再加工（比如客户端替换历史、写入本地存档）。压缩完毕之后就会涉及到信息复用，claude code中直接把总结内容复用到上下文中即可比如说：

参考