Claude 新手入门与高效调用指南

---

---

Claude 新手入门与高效调用指南

版本 ：2026年10月版

适用对象 ：零基础开发者、产品经理、内容创作者、技术爱好者

目标：从注册账号到独立构建 Claude 驱动的应用，覆盖网页端使用、API 编程、参数调优与安全规范

---

摘要

Claude 是由 Anthropic 开发的大型语言模型，以"有帮助、诚实、无害"为训练目标，在代码生成、长文档分析、复杂推理等场景中表现突出。截至 2026 年 10 月，Claude 系列模型（如 Opus 5.5、Sonnet 5.5、Haiku 5.5）已支持最高 100 万 token 上下文窗口 与 128k 输出 token，并通过网页端、桌面端、移动端及 API 多平台提供服务。

本文是一份从零起步的完整指南。第一部分 面向普通用户，讲解账号注册、界面操作、提示词基础与典型场景应用；第二部分 面向开发者，深入 API 密钥管理、Python SDK 调用、参数调优、上下文管理及错误排查；第三部分提供完整实战项目、常见陷阱清单与安全伦理规范。全文包含可直接运行的代码示例与注释，力求让读者在读完本文后具备独立使用 Claude 解决实际问题的能力。

关键词：Claude API；提示词工程；上下文窗口；Python SDK；模型部署；安全规范

目录

第一部分：Claude 基础入门（面向所有用户）

一、认识 Claude 与访问准备

1.1 Claude 是什么：定位与核心能力

1.2 访问渠道：网页、桌面与移动端

1.3 支持地区与年龄要求

1.4 账号注册实操（网页端 / Anthropic Console）

二、核心交互逻辑与提示词基础

2.1 提示词的本质：像对同事说话一样

2.2 清晰直接原则：从模糊到可执行

2.3 用 XML 标签组织复杂提示

2.4 角色设定的作用与写法

2.5 少样本示例（Few-Shot）的使用时机

三、首次对话实操：从提问到获取结果

3.1 界面功能速览：输入框、模型选择器与提交

3.2 一次完整对话的拆解

3.3 迭代追问：让结果逐步逼近目标

四、典型场景应用：代码生成与文本润色

4.1 代码生成：需求描述与约束条件的写法

4.2 代码审查与调试辅助

4.3 文本润色：风格、语气与受众控制

4.4 长文档摘要与信息提取

五、进阶技巧：上下文管理与角色设定

5.1 上下文窗口是什么（用户视角）

5.2 长对话中的上下文控制策略

5.3 系统提示与角色设定的进阶用法

第二部分：Claude API 开发指南（面向开发者）

六、开发环境准备与 API 密钥管理

6.1 Anthropic Console 账号与计费准备

6.2 创建 API 密钥的完整步骤

6.3 密钥安全存储的三种方案

6.4 环境变量配置与验证

七、Python SDK 基础调用

7.1 安装与最小可运行示例

7.2 消息结构解析：role、content 与 response

7.3 系统提示（system）的正确用法

7.4 流式输出（Streaming）实现

7.5 错误处理模板（可直接复用）

八、参数调优与输出效果提升

8.1 max_tokens：输出长度的硬约束

8.2 temperature 与采样行为

8.3 思考模式（Thinking）：自适应与手动

8.4 提示缓存（Prompt Caching）降低延迟与成本

8.5 停止序列（Stop Sequences）精确控制输出边界

九、上下文长度限制与应对策略

9.1 各模型上下文窗口对照

9.2 Token 计数与预估方法

9.3 长文档处理：分块、摘要与引用提取

9.4 多轮对话的上下文管理：压缩、清理与摘要

9.5 上下文腐化（Context Rot）及缓解手段

十、常见报错信息分析与排查方案

10.1 认证类错误（401 / 403）

10.2 请求类错误（400 / 413 / 429）

10.3 网络与连接类错误

10.4 模型与上下文超限错误

10.5 错误处理代码模板

第三部分：实战案例与完整工作流

十一、完整实战：构建一个智能文档助手

11.1 项目需求与架构设计

11.2 核心代码实现（逐行注释）

11.3 运行演示与输出示例

11.4 扩展方向：加入流式输出与错误重试

十二、效率提升：本地开发集成与工具链

12.1 VS Code 集成概览

12.2 Claude Code CLI 快速配置

12.3 快捷键与工作流优化建议

十三、常见陷阱与问题排除清单

13.1 账号与计费类陷阱

13.2 提示词设计类陷阱

13.3 API 调用类陷阱

13.4 上下文管理类陷阱

十四、安全使用规范与伦理边界

14.1 Anthropic 使用政策核心要点

14.2 高风险场景的"人类在环"要求

14.3 隐私与数据保护建议

14.4 开发者自查清单

十五、总结与持续学习路径

附录

A. 常用模型 ID 与能力对照表

B. 提示词模板速查卡

C. 错误码速查表

D. 官方资源链接汇总

---

第一部分：Claude 基础入门

一、认识 Claude 与访问准备

1.1 Claude 是什么：定位与核心能力

Claude 是 Anthropic 开发的大型语言模型（LLM），训练目标是在保持"有帮助、诚实、无害"的前提下，以对话式语气为用户提供协助。与一些追求"全能"的模型不同，Claude 在以下场景中尤其受到开发者与知识工作者的青睐：

能力领域	典型表现
长文档理解	支持最高 1M token 上下文，可一次性处理数百页 PDF 或技术文档
代码生成与审查	对 Python、TypeScript、Rust 等语言理解深入，擅长按规范生成可维护代码
结构化输出	在 XML 标签与 JSON 输出约束下，稳定性较高
指令遵循	对明确、具体的指令响应良好，适合自动化工作流

适用读者判断：如果你需要处理长文档、编写代码、构建 AI 驱动的自动化流程，或需要一个在复杂推理中保持"克制"的助手，Claude 是值得投入时间学习的选项。

1.2 访问渠道：网页、桌面与移动端

Claude 提供三种面向普通用户的访问方式，无需编程即可使用：

1. 网页版 ：访问 claude.ai，在浏览器中直接对话。适合快速试用与日常问答。
2. 桌面应用：提供 Mac 与 Windows 版本，功能与网页版基本一致，但支持系统级快捷键与本地文件交互（部分功能）。
3. 移动应用：iOS 与 Android 均可下载，适合碎片化使用与语音输入。

对于开发者而言，还有第四个入口：Anthropic Console （console.anthropic.com），用于管理 API 密钥、查看用量与调用模型 API。

1.3 支持地区与年龄要求

访问 Claude 前需确认两项前提：

• 地区限制：你必须位于 Anthropic 的支持地区列表内。截至本文写作时，中国大陆及部分其他地区不在直接支持范围内。如果你所在地区不在列表中，网页端与 API 直连可能无法使用，需考虑合规的替代方案（如通过支持地区的云服务商间接调用，或使用国产替代模型）。
• 年龄要求：必须年满 18 岁才能使用服务。

1.4 账号注册实操

1.4.1 网页端注册（claude.ai）

1. 打开 https://claude.ai。
2. 点击"Sign up"或"Continue with Google / email"。
3. 输入邮箱地址，设置密码。
4. 查收验证邮件，点击确认链接。
5. 按提示填写姓名，完成注册。

免费账户存在使用限制：基于会话的额度每 5 小时重置一次，消息数量随需求波动。如需更高额度，可升级至 Pro（20/月）或 Max（100/$200/月）计划。

1.4.2 Anthropic Console 注册（API 开发者）

API 开发需要单独注册 Console 账号，流程略有不同：

步骤 1 ：访问 https://console.anthropic.com，使用邮箱或 Google 账号注册。

步骤 2：查收验证邮件，输入验证码或点击链接完成邮箱验证。

步骤 3：填写姓名与账号类型（个人 / 组织）。若选择组织，需补充组织名称与用途。

步骤 4 ：购买额度 。API 采用预付费制，最低充值 $5。未充值的情况下，API 密钥无法成功调用（会返回 401 或额度不足错误）。

步骤 5 ：进入控制台，左侧导航栏选择 API Keys ，点击 Create Key，命名后复制生成的密钥。

关键提醒 ：API 密钥仅在创建时显示一次。关闭弹窗后无法再次查看。如果遗失，只能重新生成。立即将其存入密码管理器或环境变量，不要粘贴到聊天记录、GitHub 仓库或前端代码中。

---

二、核心交互逻辑与提示词基础

2.1 提示词的本质：像对同事说话一样

Anthropic 官方文档给出的建议朴素但有效：像与同事或朋友交谈一样与 Claude 交流。这意味着：

• 你不需要记忆"魔法指令"或特殊语法。
• 自然语言描述你的需求即可。
• 但"自然"不等于"模糊"。好的提示词是自然表达与精确约束的结合。

2.2 清晰直接原则：从模糊到可执行

官方提示词文档中有一个关键比喻：把 Claude 想象成一位才华出众但刚入职的新员工，他对你的项目背景、规范和工作流程一无所知。你解释得越精确，结果越好。

效果较差：

帮我分析一下这个数据。

效果较好：

请分析以下销售数据（CSV 格式，共 3 列：日期、产品、销售额）。

要求：
1. 按产品汇总月度总销售额，输出为 Markdown 表格。
2. 找出销售额环比下降超过 10% 的产品，单独列出。
3. 用一句话总结整体趋势。
4. 如果数据中存在缺失值，先说明缺失情况再分析。

关键测试：把你的提示词拿给一位不了解该任务的同事看，如果他照着执行会感到困惑，Claude 也会。

2.3 用 XML 标签组织复杂提示

当提示词包含多种类型的内容（指令、背景资料、示例、待处理输入）时，XML 标签可以帮助 Claude 无歧义地解析每一部分。

推荐结构：

<instructions>
你是一位技术文档编辑。你的任务是将原始笔记整理为结构清晰的操作指南。
</instructions>

<context>
目标读者：从未使用过该工具的新手。
风格要求：简洁、步骤化、每步不超过 3 句话。
</context>

<example>
<raw_note>点设置，然后找账户，点一下就能改密码</raw_note>
<output>## 修改密码
1. 打开"设置"页面。
2. 点击"账户"选项。
3. 点击"修改密码"按钮，按提示操作。</output>
</example>

<input>
[此处粘贴需要整理的原始笔记]
</input>

标签名称不需要固定，但建议一致且具有描述性 。在长文档场景中，将每个文档包裹在 <document> 标签内，并嵌套 <document_content> 与 <source> 子标签，能显著提升模型对文档结构的理解。

2.4 角色设定的作用与写法

在系统提示（system prompt）中设定角色，可以让 Claude 的行为与语气聚焦于你的用例。官方文档明确指出：即使只有一句话也会产生效果。

基础写法：

你是一位资深 Python 后端工程师，擅长代码审查与性能优化。回答时优先指出潜在 bug 与可读性问题，再给出改进建议。

进阶写法（结合输出约束）：

你是一位面向非技术读者的科普作者。解释任何技术概念时：
- 先给出一个日常生活中的类比。
- 再用一句话给出正式定义。
- 最后说明这个概念在实际产品中如何被使用。
不要使用未经解释的缩写。

2.5 少样本示例（Few-Shot）的使用时机

当输出格式、语气或结构难以用文字精确描述时，给出 2~3 个精心设计的示例往往比长篇说明更有效。

适用场景：

• 需要特定 JSON 结构输出。
• 需要模仿某种文风（如品牌文案、法律条款摘要）。
• 需要模型遵循一套隐含的规则（如"总是先肯定用户感受，再给出建议"）。

示例结构：

<examples>
<example>
<input>用户说：我的订单三天了还没发货</input>
<output>理解你的着急。三天未发货确实超出了正常处理时间。请提供订单号，我帮你查询当前状态。</output>
</example>
<example>
<input>用户说：这个产品太差了，我要退款</input>
<output>很抱歉让你有这样的体验。退款是可以处理的。请告诉我订单号，我确认后为你发起退款流程。</output>
</example>
</examples>

注意示例应覆盖边界情况且具有差异性，避免让模型学到非预期的模式。

---

三、首次对话实操：从提问到获取结果

3.1 界面功能速览

进入 claude.ai 对话界面后，关注以下元素：

界面元素	位置	用途
输入框	页面底部	输入提示词，Enter 发送（Shift+Enter 换行）
模型选择器	输入框下方	切换 Opus / Sonnet / Haiku 等模型
"+"按钮 / "/"命令	输入框左下	上传文件、调用工具、查看命令
响应区域	页面中部	显示 Claude 回复，支持代码块复制

3.2 一次完整对话的拆解

目标：让 Claude 帮你写一个 Python 函数，用于从 URL 提取域名。

第一轮提问（模糊）：

写一个从 URL 提取域名的 Python 函数。

Claude 可能返回一个基础实现，但可能缺少边界处理（如端口号、子域名、无协议头的 URL）。

第二轮追问（精确化）：

你的实现没有处理带端口号的情况。请修改，要求：
1. 输入 `https://example.com:8080/path` 时返回 `example.com`。
2. 输入 `example.com/path`（无协议头）时也能正确解析。
3. 对无效输入返回 None，而不是抛出异常。
4. 附上 3 个测试用例。

第三轮微调：

测试用例用 assert 语句写，方便直接运行验证。

结果：得到一段可以直接粘贴到项目中的代码，包含边界处理与可运行的测试。

3.3 迭代追问的核心心态

官方入门指南强调：不要犹豫改进你的提示词或提出后续问题 。Claude 不会因为你的追问而"厌烦"，相反，多轮迭代是获得高质量输出的正常路径。把第一次回复当作草稿，而非最终答案。

---

四、典型场景应用

4.1 代码生成：需求描述与约束条件

Claude 在代码任务上表现良好，但输出质量高度依赖提示词的精确度。一个可复用的代码生成提示词模板：

你是一位 [语言] 开发者。请实现以下功能：

## 功能描述
[一句话说明函数/模块做什么]

## 输入
- 类型：[类型]
- 约束：[取值范围 / 格式要求]

## 输出
- 类型：[返回类型]
- 异常情况：[何时抛出异常 / 返回 None]

## 代码要求
- 遵循 [PEP8 / Google Style / 项目现有风格]
- 添加 docstring，包含参数与返回值说明
- 对关键逻辑添加行内注释
- 不要引入外部依赖（或：可以使用 requests 库）

## 测试
附上至少 3 个测试用例，使用 [unittest / pytest / assert] 编写。

4.2 文本润色：风格、语气与受众控制

文本润色类任务的关键是明确受众与风格，而非简单说"润色一下"。

模板：

请润色以下文本。目标读者是 [受众]，风格要求是 [专业/亲切/学术/营销]，语气应 [正式/轻松/紧迫]。

润色原则：
1. 保持原意不变。
2. 删除冗余修饰词。
3. 将被动语态改为主动语态（除非学术写作需要）。
4. 长句拆分为短句。
5. 专业术语保留，但首次出现时用括号给出通俗解释。

输出格式：先给出润色后全文，再用列表说明主要修改点。

原文：
[粘贴文本]

4.3 长文档摘要与信息提取

当文档超过数千字时，直接要求"总结一下"往往得到泛泛的结果。更有效的策略是先引用再分析：

阅读以下文档。首先，从文档中找出与"定价策略变更"直接相关的段落，放入 <quotes> 标签中。然后，基于这些引用，列出变更要点（不超过 5 条），放入 <summary> 标签中。

<document>
[粘贴文档内容]
</document>

这种方法迫使 Claude 先定位相关证据，再生成摘要，减少遗漏关键信息的概率。

---

五、进阶技巧：上下文管理与角色设定

5.1 上下文窗口是什么（用户视角）

上下文窗口是 Claude 在生成回复时能"看到"的全部文本，包括系统提示、历史对话、上传的文件以及 Claude 自己的回复。你可以把它理解为 Claude 的工作记忆。

一个常见误解是"上下文越大越好"。Anthropic 文档明确指出：随着 token 数量增长，准确性和召回率会下降 ，这种现象被称为上下文腐化（Context Rot）。精心管理放入上下文的内容，与拥有更大空间同样重要。

5.2 长对话中的上下文控制策略

在网页端使用时，Claude 会自动管理上下文窗口（滚动式先进先出）。但作为用户，你可以主动采取以下策略：

策略	操作	适用场景
新话题开新对话	不要在一个对话中混用多个不相关的任务	避免旧上下文干扰新任务
显式摘要	在长对话中插入"请总结目前讨论的结论，用 5 条以内"	压缩历史信息，为后续对话腾出空间
文件分段上传	超大文档分多次上传，每次聚焦一个部分	避免一次性塞满上下文
关键信息前置	把最重要的要求放在提示词靠前位置	降低被"淹没"的风险

5.3 系统提示与角色设定的进阶用法

系统提示是每次对话开始时注入的"背景设定"，对所有后续交互生效。在网页端，Claude 的项目（Projects）功能允许你为不同任务设置不同的系统提示。在 API 中，system 参数承担这一角色。

一个生产级系统提示的要素：

角色：[专业身份]
目标：[核心任务]
约束：
- [禁止行为 1]
- [禁止行为 2]
输出格式：[格式要求]
语气：[语气要求]
不确定时的行为：[如何表达不确定性]

示例：

你是一位医疗信息助手，为医生提供文献参考摘要。你不提供诊断建议。

约束：
- 始终引用文献来源（期刊名 + 年份）。
- 如果证据不充分，明确说"现有证据不足以支持明确结论"。
- 不要使用"肯定""一定"等绝对化表述。

输出格式：先给出一句话结论，再列出 2~3 条支持证据，每条附引用。

注意：涉及健康、法律、财务等高风险领域时，Anthropic 使用政策要求必须有**具备资质的人类在环（human in the loop）**审核 Claude 的输出，并告知受影响个体 AI 被使用。

---

第二部分：Claude API 开发指南

---

六、开发环境准备与 API 密钥管理

6.1 计费准备

在 Console 中创建 API 密钥之前，必须完成额度充值 （最低 $5）。Anthropic API 采用预付费制，未充值账户的密钥在调用时会返回认证或额度相关错误。充值入口位于 Console 主页的 Buy Credits。

6.2 创建 API 密钥（完整步骤）

1. 登录 https://console.anthropic.com。
2. 左侧导航栏点击 API Keys。
3. 点击 Create Key。
4. 在弹窗中为密钥命名（建议包含用途与环境，如 dev-doc-assistant）。
5. 选择 Workspace（默认即可）。
6. 点击 Add。
7. 立即复制 生成的密钥（以 sk-ant- 开头），存入安全位置。

6.3 密钥安全存储的三种方案

方案 A：环境变量（推荐用于本地开发）

macOS / Linux：

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"

Windows PowerShell：

$env:ANTHROPIC_API_KEY = "sk-ant-xxxxxxxx"

写入 shell 配置文件（bash 为 ~/.bashrc，zsh 为 ~/.zshrc）可使其永久生效。

方案 B：.env 文件 + python-dotenv（适合项目开发）

创建 .env 文件（必须加入 .gitignore）：

ANTHROPIC_API_KEY=sk-ant-xxxxxxxx

Python 代码中加载：

from dotenv import load_dotenv
load_dotenv()

方案 C：密钥管理服务（生产环境）

使用 AWS Secrets Manager、HashiCorp Vault 或云厂商的密钥管理服务，在运行时注入。永远不要将密钥硬编码在源代码或前端 JavaScript 中。

6.4 验证密钥是否可用

使用 curl 快速验证（需先设置环境变量）：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Say OK"}]
  }'

如果返回包含 "content" 字段的 JSON，密钥有效。如果返回 401，检查密钥是否复制完整、是否已充值。

---

七、Python SDK 基础调用

7.1 安装与最小可运行示例

pip install anthropic

# minimal_example.py
# 最小可运行的 Claude API 调用示例
import anthropic
import os

# 从环境变量读取密钥（推荐方式）
# 确保已执行 export ANTHROPIC_API_KEY="sk-ant-..."
client = anthropic.Anthropic()
# 如果不使用环境变量，可显式传入：
# client = anthropic.Anthropic(api_key="sk-ant-...")

message = client.messages.create(
    model="claude-sonnet-5-5",       # 模型 ID，见附录 A
    max_tokens=256,                  # 输出 token 上限
    messages=[
        {
            "role": "user",
            "content": "用一句话解释什么是上下文窗口。"
        }
    ]
)

# message.content 是一个列表，可能包含 text / thinking 等块
# 简单场景下取第一个 text 块即可
print(message.content[0].text)

代码解析：

• anthropic.Anthropic()：创建客户端实例。SDK 会自动读取 ANTHROPIC_API_KEY 环境变量。
• client.messages.create()：发送消息请求，是 Claude API 的核心端点。
• messages：消息列表，每条包含 role（user 或 assistant）与 content。
• max_tokens：必填参数，控制输出长度的硬上限。不设置会直接报错。

7.2 消息结构解析

一次 API 调用的完整响应对象包含以下关键字段：

{
    "id": "msg_xxx",
    "type": "message",
    "role": "assistant",
    "content": [
        {"type": "text", "text": "上下文窗口是模型在生成回复时能参考的全部文本。"}
    ],
    "model": "claude-sonnet-5-5",
    "stop_reason": "end_turn",       # 停止原因：end_turn / max_tokens / stop_sequence
    "usage": {
        "input_tokens": 18,
        "output_tokens": 24
    }
}

stop_reason 的含义：

• end_turn：模型正常结束回复。
• max_tokens：达到 max_tokens 上限被截断。如果频繁出现，考虑调大上限或拆解任务。
• stop_sequence：命中了自定义停止序列。

7.3 系统提示（system）的正确用法

system 参数不是消息列表的一部分，而是独立字段：

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=512,
    system="你是一位面向非技术读者的科普作者。用日常类比解释技术概念，不超过 100 字。",
    messages=[
        {"role": "user", "content": "什么是 API？"}
    ]
)

系统提示与用户消息的分工：

• system：设定角色、全局约束、输出格式、禁止行为。在整个对话中持续生效。
• messages：具体的任务请求与对话历史。

7.4 流式输出（Streaming）

对于需要实时显示回复的场景（聊天界面、长文本生成），使用流式输出可以显著改善体验：

import anthropic

client = anthropic.Anthropic()

# stream=True 返回一个迭代器，逐块产出
with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "写一段 200 字的产品介绍，主题是智能笔记应用。"}]
) as stream:
    for text in stream.text_stream:
        # 每收到一个片段就打印，不换行
        print(text, end="", flush=True)

流式输出不会改变计费方式：最终仍然按完整的输入 + 输出 token 计费。但它让用户不必等待全部生成完成才看到内容。

7.5 错误处理模板（可直接复用）

import anthropic
import time

def call_claude_with_retry(
    messages: list,
    model: str = "claude-sonnet-5-5",
    max_tokens: int = 1024,
    max_retries: int = 3
):
    """
    带指数退避重试的 Claude 调用封装。
    适用于网络抖动或 429 限流场景。
    """
    client = anthropic.Anthropic()
    
    for attempt in range(max_retries):
        try:
            response = client.messages.create(
                model=model,
                max_tokens=max_tokens,
                messages=messages
            )
            return response.content[0].text
            
        except anthropic.RateLimitError:
            # 429：触发限流，等待后重试
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt  # 1s, 2s, 4s
            print(f"限流，{wait} 秒后重试（第 {attempt + 1} 次）")
            time.sleep(wait)
            
        except anthropic.APIConnectionError as e:
            # 网络连接失败
            if attempt == max_retries - 1:
                raise
            print(f"连接失败，重试中：{e}")
            time.sleep(2)
            
        except anthropic.APIStatusError as e:
            # 其他 4xx / 5xx，根据状态码决定是否重试
            if e.status_code >= 500 and attempt < max_retries - 1:
                time.sleep(2 ** attempt)
                continue
            raise  # 4xx 错误通常重试无意义，直接抛出
    
    raise RuntimeError("重试次数耗尽")

---

八、参数调优与输出效果提升

8.1 max_tokens：输出长度的硬约束

max_tokens 是必填参数，控制模型在单次回复中最多生成多少 token。它直接影响：

• 成本：输出 token 按量计费，设置过大不会"浪费"，但设置过小会导致回复被截断。
• 延迟：更大的上限允许更长的生成，但实际生成长度由模型根据任务决定。
• 截断风险 ：如果 stop_reason 为 max_tokens，说明回复不完整。

经验值参考：

任务类型	建议 max_tokens
简短问答 / 分类	256 ~ 512
中等长度文本生成	1024 ~ 2048
代码生成 / 长文分析	4096 ~ 8192
复杂推理 / 长文档输出	16000 ~ 32000

8.2 temperature 与采样行为

temperature 控制输出的随机性，取值范围通常为 0.0 ~ 1.0（部分模型支持更高）。

值	行为	适用场景
0.0 ~ 0.3	输出高度确定，相同输入几乎相同输出	代码生成、数据提取、分类任务
0.4 ~ 0.7	有一定多样性，保持连贯	一般对话、摘要、润色
0.8 ~ 1.0	输出多样，可能偏离预期	创意写作、头脑风暴

注意 ：即使 temperature=0，输出也不保证完全确定（底层浮点运算与并行采样存在微小差异）。如果需要严格可复现，建议缓存首次输出而非依赖重新生成。

8.3 思考模式（Thinking）：自适应与手动

思考模式让 Claude 在生成最终回复前进行内部推理，适用于数学、逻辑、复杂代码调试等任务。

当前推荐：自适应思考（Adaptive Thinking）

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[{"role": "user", "content": "一个数列的前三项是 2, 6, 12，求第 n 项公式。"}]
)

关键说明：

• type: "adaptive" 让 Claude 动态决定思考深度，无需手动设置预算。
• display: "summarized" 返回思考摘要，便于调试。设为 "omitted" 则只返回最终答案。
• 手动模式 {"type": "enabled", "budget_tokens": N} 是旧版机制，Claude 4.7 及之后模型会返回 400 错误。

思考 token 按输出 token 计费，并计入 max_tokens 上限。如果任务简单，可以关闭思考以节省成本。

8.4 提示缓存（Prompt Caching）

当你在多轮对话中反复使用相同的长系统提示或文档时，提示缓存可以显著降低延迟与输入成本。

# 在 system 内容块上设置 cache_control
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "[此处放置很长的系统提示或文档]",
            "cache_control": {"type": "ephemeral"}  # 标记为可缓存
        }
    ],
    messages=[{"role": "user", "content": "基于以上文档，总结三个要点。"}]
)

缓存命中的部分在 usage 中显示为 cache_read_input_tokens，费用远低于常规输入 token。缓存有效期约 5 分钟，适合连续多次调用同一上下文的场景。

8.5 停止序列（Stop Sequences）

使用 stop_sequences 参数让模型在遇到指定字符串时立即停止生成：

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    stop_sequences=["\n\n---", "END"],
    messages=[{"role": "user", "content": "生成三个 Python 函数签名，用 --- 分隔。"}]
)

返回的 stop_reason 会变为 stop_sequence。适用于需要精确控制输出边界的场景（如生成多条记录、分割不同部分）。

---

九、上下文长度限制与应对策略

9.1 各模型上下文窗口对照

截至 2026 年 10 月，主要模型的上下文窗口如下：

模型系列	上下文窗口	单次最大输出
Claude Opus 5.5 / 5	1M tokens	128k tokens
Claude Sonnet 5.5 / 5	1M tokens	128k tokens
Claude Haiku 5.5	1M tokens（>100k 输入加价）	128k tokens
Claude Sonnet 4.5（已弃用）	200k tokens	视配置

注意 ：上下文窗口包含请求中的所有内容：系统提示、每条消息、工具定义、图像与文档、以及模型生成的输出（含思考 token）。

9.2 Token 计数与预估方法

在发送请求前估算 token 数量，可以避免超限错误。Anthropic 提供 Token Counting API：

# 使用 SDK 的 count_tokens 方法（如可用）
# 或通过返回的 usage 字段观察实际消耗

response = client.messages.create(...)
print(response.usage.input_tokens)   # 本次请求的输入 token
print(response.usage.output_tokens)  # 本次输出的 token

粗略估算规则（英文）：1 token ≈ 4 个字符 ≈ 0.75 个单词。中文大约 1 个汉字 ≈ 1.5~2 tokens。实际值因内容而异，以上仅作快速判断参考。

9.3 长文档处理策略

当文档接近或超过上下文窗口时，采用以下策略：

策略一：分块处理

将文档按章节或固定长度切分，逐块发送并汇总结果。适合摘要、信息提取类任务。

策略二：先引用后分析

在提示词中要求 Claude 先摘录相关段落，再基于摘录进行分析。这既节省 token（Claude 可以选择性关注），也提高准确性。

策略三：使用提示缓存

如果同一文档需要被多次询问不同问题，将文档放在可缓存的系统提示中，后续调用只发送问题。缓存命中时输入成本大幅降低。

9.4 多轮对话的上下文管理

在构建聊天应用时，对话历史会不断累积。如果不加管理，很快会触及窗口上限，且"上下文腐化"会导致早期信息被稀释。

推荐做法：

def manage_conversation(history: list, max_turns: int = 10):
    """
    保留最近 N 轮对话，并对更早的内容做摘要。
    返回适合发送给 API 的消息列表。
    """
    if len(history) <= max_turns * 2:
        return history
    
    # 将较早的对话压缩为一段摘要
    old_messages = history[:-max_turns * 2]
    summary_prompt = "用不超过 3 句话总结以下对话的关键信息和结论：\n"
    summary_prompt += "\n".join([f"{m['role']}: {m['content'][:200]}" for m in old_messages])
    
    # 调用 Claude 生成摘要（简化示意，实际应处理错误）
    summary_response = client.messages.create(
        model="claude-haiku-5-5",  # 用轻量模型做摘要，成本更低
        max_tokens=256,
        messages=[{"role": "user", "content": summary_prompt}]
    )
    summary = summary_response.content[0].text
    
    # 构造新历史：摘要 + 最近 N 轮
    new_history = [
        {"role": "user", "content": f"[之前对话摘要：{summary}]"},
        {"role": "assistant", "content": "好的，我已了解之前的讨论。"}
    ]
    new_history.extend(history[-max_turns * 2:])
    return new_history

9.5 上下文腐化及缓解

上下文腐化指随着 token 数量增加，模型对关键信息的召回能力下降的现象。缓解手段包括：

1. 只放必要内容：不要把所有相关文档都塞进去，先筛选。
2. 关键信息前置：最重要的指令放在提示词靠前位置。
3. 使用结构化标签：XML 标签帮助模型定位内容。
4. 定期"重置"：在长对话中插入摘要，替换原始历史。
5. 分而治之：把复杂任务拆成多个子任务，每个子任务使用独立上下文。

---

十、常见报错信息分析与排查方案

10.1 认证类错误

状态码	错误类型	常见原因	解决方案
401	AuthenticationError	密钥无效、格式错误、已删除	重新生成密钥；确认请求头使用 x-api-key（非 Bearer）；检查是否有多余空格
403	PermissionDeniedError	地区限制、组织策略禁止、模型未授权	确认所在地区在支持列表；检查 Console 中模型访问权限

验证方法 ：用 curl 发送最小请求，排除 SDK 封装层面的干扰。

10.2 请求类错误

状态码	错误类型	常见原因	解决方案
400	BadRequestError	缺少 max_tokens、消息格式错误、无效模型 ID	检查必填参数；确认 messages 是列表且每个元素有 role 与 content
413	RequestTooLarge	请求体超过 32MB 或图像/PDF 过多	减少单次请求中的图像数量（上限 600 张 / 100 张视模型而定）；压缩文档
429	RateLimitError	超出速率限制	实现指数退避重试；降低请求频率；考虑升级 tier

10.3 网络与连接类错误

官方错误参考中列出的网络类错误包括：

• Unable to connect to API
• Connection refused
• SSL certificate verification failed
• Connection dropped

排查步骤：

1. 检查网络连通性：curl -I https://api.anthropic.com。
2. 如果使用代理，确认 HTTPS_PROXY 环境变量正确设置。
3. 公司网络可能有防火墙拦截，尝试切换网络。
4. SSL 错误通常与系统证书库或代理中间人有关，更新证书或联系网络管理员。

10.4 模型与上下文超限错误

错误信息	含义	解决方案
Prompt is too long	输入 token 超过模型上下文窗口	缩减提示词、分块处理、使用摘要替代长历史
Context limit reached	多轮对话累积超限	清理历史、使用 /clear 或代码层面重置
Model ... is not a recognized model id	模型 ID 拼写错误或不可用	查阅附录 A 的模型 ID 列表；确认账户是否有该模型权限

10.5 错误处理最佳实践

import anthropic

client = anthropic.Anthropic()

try:
    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}]
    )
except anthropic.AuthenticationError:
    print("密钥无效。请检查 ANTHROPIC_API_KEY 环境变量。")
except anthropic.RateLimitError:
    print("触发限流。请稍后重试或降低请求频率。")
except anthropic.BadRequestError as e:
    print(f"请求格式错误：{e.message}")
except anthropic.APIConnectionError:
    print("无法连接 API。检查网络或代理设置。")
except anthropic.APIStatusError as e:
    print(f"API 返回错误 {e.status_code}：{e.message}")

---

第三部分：实战案例与完整工作流

---

十一、完整实战：构建一个智能文档助手

11.1 项目需求与架构设计

目标：构建一个命令行工具，接收用户输入的文档文件（.txt / .md），支持三种操作：

1. 摘要：生成结构化摘要。
2. 问答：基于文档内容回答问题。
3. 提取：按用户指定的字段提取信息（如日期、金额、人名）。

架构：

用户输入 → 读取文件 → 构造提示词（文档 + 任务）
         → 调用 Claude API → 解析输出 → 打印结果

技术选型 ：Python 3.10+、anthropic SDK、python-dotenv（可选）。

11.2 核心代码实现

#!/usr/bin/env python3
"""
doc_assistant.py --- 基于 Claude 的智能文档助手

用法：
    python doc_assistant.py summarize <文件路径>
    python doc_assistant.py qa <文件路径> "你的问题"
    python doc_assistant.py extract <文件路径> "字段1,字段2,..."

依赖：
    pip install anthropic
"""

import sys
import os
import anthropic

# ============================================================
# 初始化客户端
# ============================================================
# 确保已设置环境变量 ANTHROPIC_API_KEY
# 或在调用前执行：export ANTHROPIC_API_KEY="sk-ant-..."
client = anthropic.Anthropic()


# ============================================================
# 工具函数：读取文件内容
# ============================================================
def read_document(path: str) -> str:
    """读取文本文件，返回内容。对超大文件做截断保护。"""
    if not os.path.exists(path):
        raise FileNotFoundError(f"文件不存在：{path}")
    
    with open(path, "r", encoding="utf-8") as f:
        content = f.read()
    
    # 粗略估算：1 token ≈ 2 个中文字符 / 4 个英文字符
    # 为安全起见，限制在约 500k 字符以内（远低于 1M token 窗口）
    if len(content) > 500_000:
        print(f"⚠️  文件较大（{len(content)} 字符），将截断至前 500k 字符。")
        print("   建议使用分块处理以获得完整分析。")
        content = content[:500_000]
    
    return content


# ============================================================
# 核心函数：调用 Claude
# ============================================================
def call_claude(system: str, user_content: str, max_tokens: int = 4096) -> str:
    """
    封装一次 Claude 调用。
    
    参数：
        system: 系统提示，设定角色与输出格式
        user_content: 用户消息，包含文档与具体任务
        max_tokens: 输出上限
    
    返回：
        模型生成的文本
    """
    response = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=max_tokens,
        system=system,
        messages=[
            {"role": "user", "content": user_content}
        ]
    )
    
    # 检查是否因 max_tokens 被截断
    if response.stop_reason == "max_tokens":
        print("⚠️  输出可能被截断（达到 max_tokens 上限）。")
        print("   考虑增大 max_tokens 或将任务拆分为更小的步骤。")
    
    return response.content[0].text


# ============================================================
# 任务一：摘要
# ============================================================
def summarize(path: str) -> None:
    """生成文档的结构化摘要。"""
    doc = read_document(path)
    
    system = """你是一位专业文档分析师。你的任务是为给定文档生成结构化摘要。
输出格式要求：
## 一句话概括
[用一句话说明文档的核心主题]

## 关键要点
- [要点 1]
- [要点 2]
- [要点 3，最多 5 条]

## 目标读者
[推断文档面向的读者群体]

## 值得注意的细节
[1~2 条容易被忽略但重要的信息]"""
    
    user = f"""请为以下文档生成摘要：

<document>
{doc}
</document>"""
    
    print("正在生成摘要...\n")
    result = call_claude(system, user)
    print(result)


# ============================================================
# 任务二：问答
# ============================================================
def qa(path: str, question: str) -> None:
    """基于文档内容回答问题。"""
    doc = read_document(path)
    
    system = """你是一位基于文档的问答助手。规则：
1. 只使用文档中明确出现的信息回答问题。
2. 如果文档中没有足够信息，回答"文档中未提及该信息"，不要猜测。
3. 回答时引用原文中的相关句子，放在 <quote> 标签中。"""
    
    user = f"""<document>
{doc}
</document>

<question>
{question}
</question>

请基于文档回答上述问题。"""
    
    print(f"问题：{question}\n")
    result = call_claude(system, user)
    print(result)


# ============================================================
# 任务三：信息提取
# ============================================================
def extract(path: str, fields: str) -> None:
    """按指定字段从文档中提取信息，输出 JSON。"""
    doc = read_document(path)
    
    system = f"""你是一位信息提取专家。从文档中提取以下字段：{fields}

输出要求：
- 严格输出 JSON，不要包含 Markdown 代码块标记或额外说明。
- 每个字段的值为字符串。如果文档中不存在该信息，值为 null。
- 如果同一字段有多个值，用 " | " 分隔。

示例输出格式：
{{"字段1": "值1", "字段2": null}}"""
    
    user = f"""<document>
{doc}
</document>

请提取指定字段。"""
    
    print(f"正在提取字段：{fields}\n")
    result = call_claude(system, user, max_tokens=2048)
    print(result)


# ============================================================
# 命令行入口
# ============================================================
def main():
    if len(sys.argv) < 3:
        print(__doc__)
        sys.exit(1)
    
    command = sys.argv[1]
    path = sys.argv[2]
    
    try:
        if command == "summarize":
            summarize(path)
        elif command == "qa":
            if len(sys.argv) < 4:
                print("用法：python doc_assistant.py qa <文件> \"问题\"")
                sys.exit(1)
            qa(path, sys.argv[3])
        elif command == "extract":
            if len(sys.argv) < 4:
                print("用法：python doc_assistant.py extract <文件> \"字段1,字段2\"")
                sys.exit(1)
            extract(path, sys.argv[3])
        else:
            print(f"未知命令：{command}")
            print(__doc__)
            sys.exit(1)
    except FileNotFoundError as e:
        print(f"错误：{e}")
        sys.exit(1)
    except anthropic.AuthenticationError:
        print("错误：API 密钥无效。请设置 ANTHROPIC_API_KEY 环境变量。")
        sys.exit(1)
    except anthropic.RateLimitError:
        print("错误：触发限流。请稍后重试。")
        sys.exit(1)
    except anthropic.APIStatusError as e:
        print(f"API 错误 {e.status_code}：{e.message}")
        sys.exit(1)


if __name__ == "__main__":
    main()

11.3 运行演示

准备测试文件 sample.txt：

2026 年第三季度产品回顾

本季度核心产品"智记"的月活跃用户达到 12.8 万，环比增长 23%。
付费转化率从 3.2% 提升至 4.1%。用户留存方面，次日留存 41%，
7 日留存 22%，30 日留存 11%。主要增长来自教育行业客户，
占比达到 37%。技术团队完成了从单体架构到微服务的迁移，
平均响应时间从 850ms 降至 210ms。

问题：客服工单量同比上升 15%，主要原因是新用户引导流程存在
混淆。产品团队计划在下季度重做 onboarding 流程。

执行摘要：

python doc_assistant.py summarize sample.txt

输出示例（实际输出因模型随机性而略有差异）：

## 一句话概括
2026 年 Q3"智记"产品用户增长显著，但新用户引导流程问题导致客服工单上升。

## 关键要点
- 月活跃用户 12.8 万，环比增长 23%；付费转化率 3.2% → 4.1%
- 30 日留存 11%，教育行业客户占比 37%
- 技术架构完成微服务迁移，响应时间 850ms → 210ms
- 客服工单同比上升 15%，主因是 onboarding 流程混淆
- 下季度计划重做新用户引导流程

11.4 扩展方向

• 流式输出 ：将 call_claude 改为 client.messages.stream()，实现打字机效果。
• 错误重试 ：复用 7.5 节的 call_claude_with_retry 封装。
• 缓存优化 ：如果同一文档需要多次问答，将文档内容放入带 cache_control 的 system 块中。
• 批量处理 ：使用 client.messages.batches 异步处理多个文档，适合离线任务。

---

十二、效率提升：本地开发集成

12.1 VS Code 集成概览

Claude Code 提供 VS Code 扩展（需 v2.1.280 及以上），在编辑器内提供对话、文件编辑、权限管理等功能。核心能力包括：

• 在侧边栏与 Claude 对话，直接引用当前文件或选中代码。
• /export 导出对话为纯文本或文件。
• /status 查看当前模型、账户与 MCP 服务器状态。
• Focus View ：隐藏工具调用细节，只保留提示词与回复（快捷键 Ctrl+Option+F / Ctrl+Alt+F）。

12.2 Claude Code CLI 快速配置（非官方渠道提示）

对于无法直接访问 Anthropic 服务的地区，社区中存在通过设置 ANTHROPIC_BASE_URL 指向中转服务的方案。本文不推荐、不背书任何第三方中转服务，仅从技术角度说明其原理：

# 原理：Claude Code 读取两个环境变量
export ANTHROPIC_BASE_URL="https://你的中转服务地址"
export ANTHROPIC_AUTH_TOKEN="你的密钥"

风险提示：使用第三方中转意味着你的所有对话内容经过第三方服务器。请勿在此类服务中传输敏感信息、源代码或个人数据。生产环境应优先使用 Anthropic 官方渠道或支持地区的云服务商（如 AWS Bedrock、Google Cloud Vertex AI）。

12.3 快捷键与工作流建议

操作	快捷方式 / 命令	说明
发送消息	Enter	网页端 / 桌面端
换行	Shift + Enter	避免误发送
清空上下文	/clear	Claude Code CLI
压缩上下文	/compact	保留摘要，释放窗口空间
导出对话	/export	VS Code 扩展
切换模型	点击模型名称	网页端输入框下方

十三、常见陷阱与问题排除清单

13.1 账号与计费类

陷阱	表现	解决方案
未充值就调 API	401 或额度错误	Console 中 Buy Credits，最低 $5
密钥泄露到 Git	密钥被盗用产生费用	立即在 Console 中删除该密钥，重新生成；使用 .gitignore 排除 .env
误以为网页订阅包含 API	Pro 订阅无法用于 API 调用	网页订阅与 API 计费是独立的，需分别付费
地区判断错误	注册成功但调用被拒	确认 IP 与账单地址在支持地区

13.2 提示词设计类

陷阱	后果	改进
指令过于模糊	输出泛泛、不符合预期	遵循 2.2 节的"清晰直接"原则
未设置 max_tokens	直接报 400 错误	每次调用必须显式设置
系统提示与用户消息混淆	角色约束不生效	角色、格式、禁止项放 system；具体任务放 messages
忽略 stop_reason	使用被截断的输出而不自知	检查 stop_reason == "max_tokens" 时考虑增大上限或拆分任务

13.3 API 调用类

陷阱	表现	排查
代理配置错误	连接超时、SSL 错误	确认 HTTPS_PROXY 格式正确（含协议与端口）
429 未做退避	持续失败，产生大量错误日志	实现指数退避（见 7.5 节模板）
图像/PDF 数量超限	413 错误	单请求最多 600 张图像/PDF 页（200k 模型为 100）
模型 ID 拼写错误	400 model not found	对照附录 A，注意连字符与版本号

13.4 上下文管理类

陷阱	后果	策略
把所有历史都塞回请求	很快超限，成本飙升	使用 9.4 节的摘要 + 最近轮次策略
长文档一次性发送不设上限	超限或成本过高	分块、缓存、先引用后分析
忽略上下文腐化	早期关键信息在长对话中被"遗忘"	定期摘要，关键指令前置

---

十四、安全使用规范与伦理边界

14.1 Anthropic 使用政策核心要点

Anthropic 于 2026 年 10 月更新的使用政策（2026 年 11 月 12 日生效）明确了以下禁止行为：

• 欺骗性活动：利用 Claude 运营虚假账号网络、伪造新闻站点、掩盖信息来源或放大特定内容。
• 破坏民主进程：欺骗选民、传播虚假投票信息、冒充候选人。
• 武器开发：包括武器制导与控制软件、武装无人机等组件的开发。
• 未经同意的监控：追踪个人（无论实时还是基于历史数据），或用于决定谁应被调查、逮捕、起诉。
• 高风险场景缺少人类审核：健康、法律、财务、生计、基本服务接入等领域的 AI 建议，必须有具备资质的人类审核，并告知受影响个体 AI 被使用。

14.2 "人类在环"要求的具体含义

如果你的应用涉及以下场景，必须设计人工审核环节：

场景	要求
医疗建议 / 诊断辅助	由执业医师审核并签字，明确告知患者 AI 参与
法律文书生成	由律师审核，不得直接作为法律意见交付
信贷 / 保险决策	人工复核拒绝或不利决定，提供申诉渠道
招聘筛选	AI 仅作辅助排序，最终决定由人类做出

14.3 隐私与数据保护建议

• 不要向 Claude 发送未经脱敏的个人身份信息（PII） 。如果必须处理，先在本地做匿名化替换（如将姓名替换为 [NAME_1]）。
• API 请求的数据传输：Anthropic 声明 API 输入输出不用于训练模型（需在 Console 中确认数据使用设置）。但第三方中转服务不受此约束。
• 日志记录：生产环境中记录请求 ID 与 usage，但避免在日志中存储完整的用户输入与模型输出（可能含敏感信息）。

14.4 开发者自查清单

在将 Claude 集成到产品前，逐项确认：

• API 密钥通过环境变量或密钥管理服务注入，未硬编码。
• 已实现 429 与 5xx 的退避重试。
• max_tokens 已根据任务类型合理设置。
• 长对话场景有上下文管理策略（摘要 / 清理）。
• 高风险场景有人工审核环节与 AI 使用告知。
• 用户输入中的 PII 已脱敏或明确告知数据流向。
• 已阅读 Anthropic 使用政策，确认用例不在禁止范围内。

---

十五、总结与持续学习路径

---

核心要点回顾

1. 入门门槛低：网页端即可开始使用，像对话一样自然地表达需求。
2. 提示词质量决定输出质量：清晰、具体、带示例、用 XML 结构化。
3. API 使用需要三项准备：Console 账号 + 充值 + 密钥安全存储。
4. 参数调优有章可循 ：max_tokens 控制长度，temperature 控制随机性，思考模式处理复杂推理。
5. 上下文是稀缺资源：1M 窗口很大，但"塞满"不等于"用好"，腐化是真实风险。
6. 错误排查从状态码入手：401 → 密钥，400 → 参数，429 → 限流，网络错误 → 代理。
7. 安全与伦理是底线：高风险场景必须有人类在环，禁止用途不可触碰。

---

持续学习路径

阶段	目标	资源
入门	熟练使用网页端完成日常任务	Claude 帮助中心"开始使用"
进阶	掌握提示词工程核心技巧	Anthropic 提示词最佳实践文档
开发	用 SDK 构建可运行的应用	Python SDK 文档
生产	处理上下文管理、错误恢复、成本优化	API 参考、Token Counting、Prompt Caching
专家	跟进模型更新与政策变化	Anthropic 官方博客、Usage Policy 更新

---

附录

附录 A：常用模型 ID 与能力对照表

模型名称	模型 ID	上下文窗口	适用场景
Claude Opus 5.5	claude-opus-5-5	1M	最复杂推理、高难度代码、深度分析
Claude Sonnet 5.5	claude-sonnet-5-5	1M	通用场景，性能与成本平衡
Claude Haiku 5.5	claude-haiku-5-5	1M（>100k 加价）	高吞吐、低延迟、简单分类与提取

模型 ID 与可用性可能随账户类型与地区变化。以 Console 中实际可用的模型为准。截至 2026 年 10 月，Anthropic 官方文档中出现的模型包括 Opus 5.5、Sonnet 5.5、Haiku 5.5 等。

附录 B：提示词模板速查卡

代码生成：

你是一位 [语言] 开发者。实现 [功能]。
输入：[类型与约束]；输出：[类型与异常行为]。
要求：docstring、关键注释、无外部依赖。
附 3 个 assert 测试用例。

文本润色：

润色以下文本，读者是 [受众]，风格 [风格]，语气 [语气]。
保持原意；删冗余；主动语态；长句拆短；术语首现加解释。
先输出润色全文，再用列表说明修改点。

信息提取（JSON）：

从文档中提取 [字段列表]。只输出 JSON，无额外文本。
不存在的字段值为 null。多值用 " | " 分隔。

附录 C：错误码速查表

状态码	SDK 异常	首要排查方向
400	BadRequestError	max_tokens 是否缺失；消息格式；模型 ID
401	AuthenticationError	密钥是否有效、是否用 x-api-key 头
403	PermissionDeniedError	地区限制；组织策略；模型权限
413	RequestTooLarge	图像/PDF 数量；请求体大小
429	RateLimitError	降低频率；指数退避
5xx	APIStatusError	Anthropic 服务端问题，重试并关注状态页

附录 D：官方资源链接

资源	地址
Claude 网页端	https://claude.ai
Anthropic Console（API）	https://console.anthropic.com
帮助中心（中文）	https://support.claude.com/zh-CN
提示词最佳实践	https://platform.claude.com/docs/zh-CN/build-with-claude/prompt-engineering/claude-prompting-best-practices
Python SDK 文档	https://platform.claude.com/docs/zh-CN/cli-sdks-libraries/sdks/python
上下文窗口说明	https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows
使用政策	https://www.anthropic.com/news/2026-usage-policy-update

---

免责声明：本文档中的代码示例仅用于教学目的。生产环境部署前请根据实际需求补充日志、监控、限流与安全审计。模型名称、参数支持与政策条款可能随 Anthropic 更新而变化，请以官方文档为准。

---

---