为Claude AI构建持久化文件记忆：Backblaze B2云存储技能实战指南

在AI应用开发中，大语言模型（LLM）的上下文限制和文件遗忘问题是常见的工程挑战。其核心原理在于模型本身不具备长期记忆存储能力，每次交互都依赖于有限的输入上下文。为了解决这一问题，开发者需要借助外部存储与检索系统来扩展AI的“记忆”。这种技术方案的价值在于，它能将私有知识库、历史文档等静态数据与模型的动态推理能力相结合，从而构建出具备持续学习能力和领域专精的智能体。典型的应用场景包括智能客服助手、

weixin_33730836

899人浏览 · 2026-05-11 14:49:46

weixin_33730836 · 2026-05-11 14:49:46 发布

1. 项目概述：一个让Claude AI“记住”文件的云端技能

最近在折腾AI应用开发的朋友，可能都遇到过同一个头疼的问题：Claude API虽然强大，但它是个“健忘症患者”。你上传一个文档让它分析，聊几句之后，它可能就把文档内容给忘了，或者上下文窗口一满，之前的文件就成了过眼云烟。更别提那些需要长期、稳定访问的私有知识库文件了。每次对话都重新上传？效率低下不说，对于大文件，API调用成本和等待时间都是问题。

这就是我最初注意到 backblaze-labs/claude-skill-b2-cloud-storage 这个开源项目时的痛点。简单来说，它是一个为Claude API设计的“技能”（Skill），能将你的文件持久化存储在Backblaze B2云存储中，并在需要时，让Claude智能地检索并使用它们。你可以把它想象成给Claude配了一个专属的、无限容量的、且Claude自己知道怎么用的“外接硬盘”。

这个项目来自Backblaze Labs，也就是那个以提供高性价比云存储和发布年度硬盘故障率报告而闻名的Backblaze公司的创新实验室。它本质上是一个中间件，架设在你的应用（或直接是Claude API）与Backblaze B2存储桶之间。其核心价值在于，它通过一种结构化的方式，将文件存储、元数据管理、语义检索和Claude的上下文调用无缝整合，让你能构建出真正具备“长期记忆”和“专业知识”的Claude应用。

举个例子，你开发了一个法律咨询助手，需要让Claude熟悉上千份法律条文和案例。传统做法要么是把所有文本塞进提示词（很快会超限），要么是每次用户提问时临时去向量数据库搜。而通过这个B2 Cloud Storage Skill，你可以预先将所有法律文档上传到B2，技能会为它们建立索引。当用户提问“关于劳动合同中竞业限制条款的效力”时，Claude能通过这个技能，自动、精准地从B2存储中检索出最相关的几个法律文档片段，作为上下文提供给Claude，从而生成专业、有据可依的回答。整个过程对最终用户是无感的，他们只觉得这个AI助手特别“博学”。

2. 核心架构与工作原理拆解

要理解这个技能怎么用，先得弄明白它背后是怎么转起来的。这不像简单的文件上传下载，而是一个精心设计的、面向AI智能体工作流的存储检索系统。

2.1 技能、工具与Claude API的三角关系

首先澄清几个关键概念。在Anthropic的Claude API体系中，“技能”是一种可复用的功能模块，它封装了一系列“工具”供Claude调用。Claude本身并不直接执行代码，而是根据对话上下文，判断是否需要以及如何调用你提供的工具。

在这个项目里， B2 Cloud Storage Skill 就是一个这样的技能包。它主要暴露了以下几个核心工具给Claude：

文件上传/存储工具 ：允许Claude（或者说，你的程序以Claude的名义）将对话中产生的重要文件或用户提供的文件保存到B2。
文件列表/检索工具 ：让Claude能够查询B2存储桶里有哪些文件，比如按名称、类型或时间过滤。
文件内容读取工具 ：这是最关键的工具。当Claude在回答问题时，如果判断需要某个已存储文件的内容作为参考，它会自动调用此工具，读取指定文件的内容，并将其作为上下文信息注入到当前的对话中。

工作流程可以概括为： 你的应用 -> 调用Claude API（附带技能配置）-> Claude思考 -> 决定调用B2技能工具 -> 工具执行（读写B2）-> 结果返回给Claude -> Claude生成最终回复 。

2.2 数据流与存储结构设计

项目在B2存储桶内的数据组织方式，体现了对AI应用场景的深度思考。它不仅仅是扔进去一堆文件那么简单。

存储桶（Bucket） ：你在Backblaze B2上创建的一个存储容器，所有文件都放在这里。

索引文件（ index.json ） ：这是整个技能的“大脑”。它不是一个传统的数据库，而是一个存储在B2根目录下的JSON文件。每当通过技能上传一个新文件，这个 index.json 就会被更新。它记录了所有文件的元数据，例如：

file_id : 技能生成的唯一标识符（UUID），用于内部引用。
file_name : 用户上传时的原始文件名。
b2_file_name : 在B2上实际存储的路径和文件名（通常为了避重和整理，会放在以 file_id 命名的子目录下）。
size : 文件大小。
mime_type : 文件类型（如 text/plain , application/pdf ）。
uploaded_at : 上传时间戳。
metadata : 用户自定义的键值对标签。这是非常关键的一环，你可以在这里添加诸如文档主题、作者、版本、关键词等信息，未来可以用于更精细的检索。

文件实际存储 ：文件内容本身被存储在类似 {file_id}/original 这样的路径下。这种设计将元数据（轻量、频繁读取）与文件数据（重量、按需读取）分离，优化了检索效率。

2.3 语义检索与上下文注入的魔法

“Claude怎么能知道该读哪个文件？”这是最精妙的部分。技能本身不直接做复杂的语义搜索（比如用向量数据库），它主要依赖基于元数据（文件名、自定义metadata）的过滤。真正的“智能”来自于Claude模型自身。

触发检索 ：当用户的问题暗示需要某类文件信息时（例如，“请用我们上周讨论的产品需求文档来回答”），Claude会根据当前的对话历史和它对这个技能工具的理解（由工具描述定义），判断是否需要调用 list_files 或 read_file 工具。
精准定位 ：Claude可能会先调用 list_files ，查看存储桶中有哪些文件，结合文件名和metadata，锁定目标文件的 file_id 。
内容获取 ：然后，Claude调用 read_file 工具，传入 file_id 。技能后端收到请求后，从B2存储桶中找到对应的文件，读取内容。
上下文注入 ：读取到的文件内容，会以系统消息或工具执行结果的形式， 追加到Claude本次API调用的上下文窗口中 。Claude在生成最终回答时，就能“看到”并利用这些文件内容。

这个过程的关键在于， 检索的逻辑和时机是由Claude这个大语言模型来主导的 ，而不是由开发者预先写死的规则。这使得交互更加自然和灵活。

3. 环境准备与项目部署实操

理论讲完了，我们动手把它跑起来。整个部署过程可以分为本地开发环境搭建和云服务配置两大部分。

3.1 本地开发环境配置

项目基于Node.js，所以首先确保你的系统环境符合要求。

Node.js与包管理器 ：推荐使用Node.js 18或20 LTS版本。你可以使用 nvm （Node Version Manager）来方便地切换版本。包管理器用npm或yarn都可以，项目一般提供 package.json 。

# 检查Node.js版本
node --version
# 检查npm版本
npm --version

# 如果版本过低，使用nvm安装（以nvm为例）
nvm install 20
nvm use 20

克隆项目与安装依赖 ：

# 克隆Backblaze Labs的官方仓库
git clone https://github.com/backblaze-labs/claude-skill-b2-cloud-storage.git
cd claude-skill-b2-cloud-storage

# 安装项目依赖
npm install

安装过程会拉取 @anthropic-ai/sdk （Claude官方SDK）、 @backblaze/b2 （B2 SDK）、 express （用于运行技能服务器）等关键依赖。

环境变量配置 ：这是连接Claude和B2的钥匙。项目根目录下应该有一个 .env.example 文件。复制它并创建你自己的 .env 文件。

cp .env.example .env

然后打开 .env 文件，填入你的核心密钥：

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx # 你的Claude API密钥，从Anthropic控制台获取
B2_APPLICATION_KEY_ID=003xxxxxxxxxxxxx0000000007 # B2应用密钥ID
B2_APPLICATION_KEY=K003xxxxxxxxxxxxxxxxxxxxxxxx # B2应用密钥
B2_BUCKET_NAME=your-claude-files-bucket # 你打算使用的B2存储桶名称
SKILL_SERVER_PORT=3000 # 技能服务器运行的端口，默认3000

重要安全提示 ： .env 文件包含最高机密，务必将其添加到 .gitignore 中，绝对不要提交到版本控制系统。在部署到生产环境时（如Vercel, Railway），应使用平台提供的环境变量配置功能。

3.2 Backblaze B2云存储配置

如果你还没有Backblaze B2账户，需要先注册。B2有非常慷慨的免费额度（10GB存储空间 + 每天1GB下载流量），对于开发和初期项目完全够用。

创建存储桶（Bucket） ：
- 登录Backblaze B2控制台。
- 点击“创建存储桶”。
- 桶名称 ：填写你在 .env 里设定的 B2_BUCKET_NAME （例如 claude-files-bucket ）。注意，B2的桶名称需要全局唯一。
- 类型：选择“公开”或“私有”。 为了安全起见，强烈建议选择‘私有’ 。我们的技能服务器会通过应用密钥来访问，不需要公开文件。如果某些文件需要公开链接，可以通过技能或B2 SDK生成有时限的授权下载链接。
- 其他设置保持默认，创建即可。
生成应用密钥（Application Keys） ：
- 在控制台侧边栏找到“应用密钥”。
- 点击“生成新密钥”。
- 给密钥起个名字，如 claude-skill-server 。
- 权限：这里需要精细控制。建议只授予最小必要权限：
  - 勾选“允许访问存储桶”，并选择你刚创建的桶。
  - 在“更多选项”中，明确勾选需要的权限： listFiles , readFiles , writeFiles , deleteFiles 。 listBuckets 可选。
- 不勾选 “允许绕过存储桶安全设置”。
- 点击“生成新密钥”。
- 关键一步 ：生成后，页面会一次性显示 keyID 和 applicationKey 。 务必立即复制保存 ，因为它们只会显示这一次。将这两个值分别填入 .env 文件的 B2_APPLICATION_KEY_ID 和 B2_APPLICATION_KEY 。

3.3 技能服务器的启动与验证

配置好后，启动技能服务器就很简单了。

# 在项目根目录下运行
npm start
# 或者，如果package.json中配置了dev脚本，也可以用
npm run dev

如果一切正常，终端会显示服务器正在监听你设置的端口（如 http://localhost:3000 ）。

验证服务器是否就绪 ：

打开浏览器或使用 curl ，访问 http://localhost:3000/.well-known/ai-plugin.json 。这是一个标准的技能描述文件端点。
你应该能看到一个JSON响应，其中包含了技能的 name 、 description 、 tools 定义等信息。这证明技能服务器已成功运行并加载了配置。
你还可以访问 http://localhost:3000/health 或根路径，可能会看到简单的状态信息。

至此，一个专属于Claude的“文件管家”后台服务就已经在本地运行起来了。接下来，我们要让Claude认识并使用这位“管家”。

4. 在Claude API中集成与调用技能

本地服务跑通了，但Claude API在云端，它怎么和你的本地服务器对话呢？这里就需要一个“中间人”——一个能公网访问的端点。在开发阶段，我们通常使用内网穿透工具。

4.1 暴露本地服务至公网

为了让Claude API能回调你的技能服务器，你需要一个HTTPS公网地址。 ngrok 是最方便的选择之一。

注册并安装ngrok ：去ngrok官网注册免费账户，获取你的Authtoken。然后按照指南安装ngrok客户端。

启动隧道 ：

# 假设你的技能运行在3000端口
ngrok http 3000

获取公网地址 ：命令执行后，ngrok会分配一个随机的 https://xxxxxx.ngrok-free.app 域名给你。复制这个 HTTPS 地址（例如 https://abc123.ngrok-free.app ）。这个地址就是你的技能服务器的临时公网入口。

注意：免费版ngrok的域名每次重启都会变化，且可能有速率限制。用于生产环境时，你需要一个固定的域名和稳定的反向代理服务（如配置你自己的云服务器、使用Railway/Vercel等部署平台）。

4.2 创建并配置Claude技能

现在，我们进入Anthropic的开发者控制台，将技能“安装”给Claude。

登录控制台 ：访问Anthropic控制台，进入“Skills”或“Tools”部分（不同时期界面可能不同）。
创建新技能 ：点击“Create Skill”或“Add Tool”。
填写技能信息 ：
- Name : 给你的技能起个名，如 My File Vault 。
- Description : 详细描述技能功能，例如：“一个连接到Backblaze B2云存储的技能，允许Claude上传、列出和读取存储的文件。用于长期文件记忆和知识库检索。” 描述越清晰，Claude越能理解何时调用它 。
- Skill URL : 填入你的ngrok提供的HTTPS地址（例如 https://abc123.ngrok-free.app ）。Claude会向这个地址的 /.well-known/ai-plugin.json 端点获取工具定义。
授权（可选） ：如果技能需要API Key（我们这个技能需要B2密钥，但已保存在服务器环境变量中，不通过前端传递），这里通常选择“None”或根据技能要求配置。我们的认证是在服务器端完成的。
保存：创建完成后，该技能就会出现在你的技能列表中，并且状态应该是“Available”。

4.3 在API调用中启用技能

技能创建好后，你需要在调用Claude API时，明确告诉Claude本次对话可以使用这个技能。

以下是一个使用Node.js SDK的示例代码片段：

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await anthropic.messages.create({
  model: 'claude-3-5-sonnet-20241022', // 使用支持工具调用的模型
  max_tokens: 1024,
  tools: [{
    type: 'skill',
    name: 'My File Vault', // 必须与你创建技能时填写的Name完全一致
    description: 'Access files stored in Backblaze B2 cloud storage.',
    input_schema: {
      // 通常这里可以留空，Claude会自动从技能端点获取schema
      // 或者你也可以手动定义，但建议让Claude自动获取以保证同步
    }
  }],
  messages: [
    {
      role: 'user',
      content: `用户：你好，请帮我分析一下我们公司的Q3销售数据报告。报告我已经上传到文件库了，文件名是“Q3_Sales_Report_2023.pdf”。`
    }
  ],
});

console.log(message.content);

在这个调用中， tools 参数里声明了我们要使用的技能。Claude收到用户消息后，会结合技能描述，判断是否需要与技能交互。如果它认为需要读取那个PDF报告，它就会向你的技能服务器发起工具调用请求。

4.4 技能调用流程全链路追踪

当上述API调用发生时，一个完整的交互链路如下：

用户请求 ：你的应用服务器发送上述请求到Anthropic API。
Claude思考 ：Claude模型分析用户消息，识别出“Q3_Sales_Report_2023.pdf”这个文件名，并参考技能描述，判断需要调用 read_file 工具。
工具调用请求 ：Claude API会向你的技能服务器（即 https://abc123.ngrok-free.app ）发送一个POST请求，请求体包含工具调用的参数，比如 {"action": "read_file", "file_id": "对应的文件ID"} 。同时，请求头会包含用于验证的签名等信息（由Anthropic生成）。
技能服务器处理 ：你的技能服务器（ claude-skill-b2-cloud-storage ）收到请求： a. 验证请求签名（确保来自真正的Claude API）。 b. 解析请求，识别出要执行 read_file 动作。 c. 根据 file_id ，查询本地的 index.json 映射（或直接去B2查找）。 d. 使用B2 SDK，从私有存储桶中下载该文件的内容。 e. 将文件内容（或经过处理的部分，如提取文本）格式化为Claude API要求的响应格式。
返回结果 ：技能服务器将文件内容返回给Claude API。
Claude生成最终回复 ：Claude API收到文件内容后，将其作为上下文信息，注入到对话中，Claude模型基于此生成包含数据分析的最终回复，返回给你的应用服务器。
应用展示 ：你的应用将Claude的回复展示给用户。

你可以在技能服务器的终端日志中，看到详细的请求和响应信息，这对于调试至关重要。

5. 核心功能深度使用与最佳实践

掌握了基础部署和调用，我们来深入看看这个技能的几种高级用法和实操中的最佳策略。

5.1 文件上传策略：手动 vs. 通过Claude

文件进入存储库有两种主要方式：

方式一：通过技能工具让Claude上传 这是最动态的方式。你可以在对话中直接说：“Claude，请把刚才我总结的会议纪要保存到文件库，命名为‘project-kickoff-meeting-notes.txt’。” 如果Claude判断合适，它会调用 upload_file 工具。这种方式适合在对话流程中即时保存有价值的产出。

方式二：通过技能服务器API直接上传 对于批量初始化知识库，更高效的方式是直接调用技能服务器提供的上传API（如果项目暴露了此端点），或直接使用B2 SDK上传。你需要确保上传后同步更新技能本地的 index.json 文件，或者技能设计了自动索引的机制。

最佳实践建议 ：

初始化知识库 ：采用方式二，编写脚本批量上传基础文档（公司制度、产品手册、历史数据等）。
对话中衍生文件 ：采用方式一，让Claude自动保存它生成的总结、方案、代码等，形成知识积累。
元数据（Metadata）是灵魂 ：无论哪种方式， 务必充分利用上传时的 metadata 字段 。为你上传的每个文件添加诸如 topic （主题）、 department （部门）、 year （年份）、 tags （标签，用逗号分隔）等自定义字段。这能极大提升后续Claude检索文件的精准度。例如，上传一份PDF时，metadata可以是 {"type": "report", "quarter": "Q3", "year": "2023", "department": "sales"} 。

5.2 高效检索：引导Claude找到对的文件

Claude的检索智能依赖于你的引导和文件本身的组织。

清晰的命名规范 ：文件名本身是最直接的线索。使用描述性强的文件名，如 2024-05-20_UX-Research-Report_Project-Alpha_v1.2.pdf ，远比 report.pdf 有效。
在对话中提供精确线索 ：用户提问时，应尽量提及文件的标识信息。对比以下两种提问：
- 差：“我们上次说的那个报告怎么说的？”（Claude需要猜测是哪个报告）
- 好：“请查看文件库中名为‘Q3销售报告’的PDF，告诉我华东区的销售额。”（提供了文件名和类型）
- 更好：“请查看标签包含‘销售’和‘Q3’的文件，总结一下趋势。”（利用了metadata进行过滤）
利用 list_files 进行探索 ：你可以直接指示Claude：“请列出文件库里所有关于‘财务’的文件。” Claude会调用 list_files 工具，可能结合metadata中的 topic 或 tags 进行过滤（如果技能实现了基于metadata的查询），然后将列表返回给你参考。

5.3 构建领域专属AI助手实例

结合以上两点，我们可以设计一个完整的客服AI助手流程：

知识库冷启动 ：将所有的产品FAQ文档、用户手册、故障处理指南、历史工单记录（脱敏后）PDF/Word/TXT文件，通过脚本批量上传至B2存储桶。每个文件都精心设置metadata，例如 {"category": "FAQ", "product": "Router-X3000", "tags": "setup, troubleshooting, wifi"} 。
用户提问 ：用户问：“我的Router-X3000路由器5G信号时好时坏怎么办？”
Claude检索与回答 ： a. Claude识别出“Router-X3000”、“5G信号”、“时好时坏”等关键词。 b. 它调用技能的 list_files 工具，可能附带过滤条件（如 metadata.product 包含‘Router-X3000’）。 c. 从返回的文件列表中，它识别出最相关的可能是《Router-X3000故障排查指南.pdf》和《常见无线网络问题FAQ.txt》。 d. 它依次调用 read_file 工具读取这两个文件的相关部分（技能可以设计为支持读取特定页码或章节）。 e. 综合读取到的专业文档内容和用户问题，生成结构化的解答：“根据故障排查指南，5G信号不稳定可能原因有：1. 信道干扰，建议… 2. 设备放置位置，请尝试… 3. 固件版本，您可检查…”
知识库热更新 ：如果这次对话产生了一个新的、有效的解决方案，你可以让Claude将其总结并保存为新的文件片段，存入知识库，metadata标记为 {"category": "solution", "product": "Router-X3000", "problem": "5g_signal_unstable"} ，实现AI助手的自我学习和知识库的持续丰富。

6. 性能优化、安全与成本考量

将核心业务文件与AI整合，性能和安全性不容忽视。

6.1 性能优化策略

文件分块与索引 ：当前技能可能默认读取整个文件。对于大型文档（如数百页的PDF），这会导致工具响应慢，且迅速消耗Claude的上下文窗口。 优化方案 ：在上传时或技能服务器端，增加一个“文本提取与分块”的预处理流程。使用像 pdf-parse 、 mammoth （用于docx）等库提取纯文本，然后按章节或固定大小（如1000字符）分块。每个块作为一个独立的“逻辑文件”存入B2，并在 index.json 中建立关联。当Claude需要读取时，可以根据查询定位到最相关的几个块，而不是拉取整个文件。
缓存机制 ：对于频繁被访问的“热点”文件（如公司简介、核心产品文档），可以在技能服务器内存或Redis中建立缓存，避免每次都为相同的 file_id 重复从B2下载，显著降低响应延迟。
B2存储区域选择 ：Backblaze B2在全球有多个存储区域。如果你的应用用户和技能服务器主要在某一个地理区域，在创建B2存储桶时选择对应的区域（如 us-west-002 ），可以减少网络延迟。
技能服务器部署位置 ：将技能服务器部署在离你的主要用户群和B2存储区域网络延迟较低的地方。例如，使用AWS EC2（美西）来服务B2美西桶。

6.2 安全加固措施

B2密钥权限最小化 ：如前所述，创建B2应用密钥时，只授予 listFiles, readFiles, writeFiles, deleteFiles 于特定存储桶的权限。切勿使用主账户的Master Application Key。
技能服务器认证 ：确保技能服务器实现了对Claude API回调请求的签名验证。Anthropic的SDK或技能示例代码中应包含验证逻辑，防止伪造请求。 绝对不要 跳过此步骤。
敏感文件处理 ：存储到B2的文件可能包含敏感信息。确保：
- 存储桶权限为“私有”。
- 技能服务器在上传/下载时进行端到端加密（虽然B2本身支持服务器端加密，但客户端加密更安全）。
- 在metadata中避免存储明文敏感信息。
输入验证与清理 ：技能服务器对所有接收到的参数（如 file_id , file_name ）进行严格的验证和清理，防止路径遍历攻击（如 ../../../etc/passwd ）。
HTTPS与固定域名 ：生产环境务必使用有效的SSL证书（如Let‘s Encrypt）和固定域名，废弃开发时使用的临时ngrok地址。

6.3 成本分析与控制

使用这个方案主要涉及三部分成本：

Claude API成本 ：每次Claude调用工具（ list_files , read_file ）以及处理返回的文本内容，都会消耗API的输入/输出tokens。尤其是 read_file 返回大量文本时，成本增加明显。 控制策略 ：优化检索，只返回必要的文件片段；对返回的文本内容进行压缩或总结（可在技能服务器端实现一个轻量总结步骤）。
Backblaze B2成本 ：B2的费用包括存储费、下载流量费和API调用费。免费额度很高，但用量大时需关注。
- 存储费 ：非常低廉，约$0.005/GB/月。优化点：定期清理无用或过时的文件。
- 下载流量费 ：从B2下载到技能服务器的流量会产生费用（约$0.01/GB）。优化点：通过缓存（见性能优化）减少重复下载。
- API调用费 ：Class B交易（上传、列出文件）和Class C交易（删除、获取授权）费用极低，通常可忽略。
服务器成本 ：运行技能服务器的云主机/容器费用。选择适合流量的套餐即可。

总体而言，对于中小型应用，在免费额度和合理优化下，这套方案的月度成本可以控制在很低的水平，远低于自建一套复杂的向量数据库和文件存储系统。

7. 常见问题排查与调试技巧

在实际集成和使用过程中，你肯定会遇到各种问题。下面是一些常见坑点和排查方法。

7.1 技能连接失败

问题现象 ：在Claude控制台创建技能时，状态一直显示“Unavailable”或“Failed to fetch”。

排查步骤 ：

检查技能服务器是否运行 ： curl http://localhost:3000/.well-known/ai-plugin.json 本地是否能通？
检查公网可达性 ：用 curl 或浏览器访问你的ngrok地址对应的 /.well-known/ai-plugin.json 路径。确保返回正确的JSON。
检查CORS ：如果浏览器访问出现CORS错误，需要在技能服务器（Express）中正确配置CORS头，允许Anthropic的域名。示例代码中通常已包含。
检查ngrok日志 ：在ngrok终端查看是否有入站请求，以及请求是否被转发到本地服务器成功。
检查防火墙/安全组 ：确保本地服务器的端口（3000）没有被防火墙阻止，且ngrok客户端能正常连接其云服务。

7.2 Claude不调用工具

问题现象 ：用户明明提到了已知的文件名，但Claude的回复中完全没有调用工具的迹象。

排查步骤 ：

确认技能已附加 ：检查API请求的 tools 参数是否正确包含了技能定义，且 name 字段与控制台创建的完全一致（大小写敏感）。
审视技能描述 ：返回控制台，仔细阅读你为技能写的 Description 。这个描述是Claude理解技能用途的主要依据。确保描述清晰、准确地说明了技能能做什么（“上传、列出、读取B2中的文件”），以及何时使用（“当用户需要访问之前存储的文档或保存当前内容时”）。可以尝试将描述写得更直白、场景化。
检查Claude模型 ：确保你使用的Claude模型版本支持工具调用（如 claude-3-opus-20240229 , claude-3-5-sonnet-20241022 及以后版本）。
用户指令清晰度 ：在用户消息中，更明确地指示Claude使用技能。例如：“请使用‘我的文件库’技能，找到名为‘xx’的文件并阅读它。”
查看API响应 ：Claude API的响应中，如果决定调用工具，会在 content 数组里包含类型为 tool_use 的块。检查完整的API响应日志。

7.3 工具调用出错

问题现象 ：Claude尝试调用工具，但返回了错误（在Claude回复中体现，或技能服务器日志报错）。

排查步骤 ：

查看技能服务器日志 ：这是最重要的调试信息源。查看终端输出的错误堆栈。
常见错误类型 ：
- B2认证失败 ：检查 .env 文件中的 B2_APPLICATION_KEY_ID 和 B2_APPLICATION_KEY 是否正确，是否有空格。检查B2密钥是否被禁用。
- 存储桶不存在或无权访问 ：确认 B2_BUCKET_NAME 拼写正确，且B2应用密钥确实授权给了这个桶。
- index.json 损坏或丢失 ：检查B2存储桶根目录下是否有 index.json 文件。如果丢失，技能可能无法将 file_id 映射到实际文件。可以尝试通过技能重新上传一个小文件，看是否能自动重建索引。
- 文件不存在 ：Claude请求的 file_id 在 index.json 中找不到。可能是文件已被手动删除（在B2控制台），但 index.json 未同步更新。需要手动修复索引或重新上传文件。
- 网络超时 ：从技能服务器下载大文件到B2超时。考虑优化网络，或增加技能服务器的超时设置。

7.4 文件内容处理乱码或格式错误

问题现象 ：Claude读取了文件，但回复中显示乱码，或无法理解文件内容。

排查步骤 ：

检查文件编码 ：确保文本文件是UTF-8编码。对于其他编码的文件，需要在技能服务器读取时进行转码。
检查二进制文件处理 ：技能默认可能只适合处理文本文件。对于PDF、Word等，需要在技能服务器端集成解析库（如 pdf-parse , mammoth ），将内容提取为纯文本后再返回给Claude。查看项目代码，看是否支持或需要你扩展这些解析器。
内容过长截断 ：Claude的上下文窗口有大小限制。如果文件内容巨大，技能服务器或Claude API可能会静默截断。需要在技能端实现内容分块或摘要提取逻辑。

调试心法 ：始终遵循“由内向外”的排查原则。先确保技能服务器本地运行、单接口测试通过；再确保公网可访问、Claude能获取定义；最后在完整对话流程中观察工具调用和返回。详细记录每一次请求和响应的日志，是快速定位问题的关键。

DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐