03 多语言 SDK 组织：语言检测路由与共享概念层

03 多语言 SDK 组织：语言检测路由与共享概念层

学习目标

• 理解 claude-api 技能中的 8 语言支持矩阵
• 掌握语言检测路由机制
• 分析共享概念层（shared/）的设计决策
• 学习实时文档源（live-sources.md）的维护策略

前置知识

本章涉及 LLM 应用三层架构与 Skill 渐进式加载的通用原理，建议先阅读：

• LLM 应用三层架构与决策树
• Skill 渐进式知识管理

下文假设你已理解上述概念，直接聚焦 claude-api 技能的具体实现。

---

项目实践

8 语言支持矩阵

claude-api 技能覆盖了 8 种语言/协议：

语言	SDK	Tool Runner	Managed Agents	文件数
Python	anthropic	✅ (beta)	✅ (beta)	claude-api/README.md, tool-use.md, streaming.md, batches.md, files-api.md + managed-agents/README.md
TypeScript	@anthropic-ai/sdk	✅ (beta)	✅ (beta)	同上
Java	com.anthropic	✅ (beta)	✅ (beta)	单文件覆盖所有基础
Go	anthropic	✅ (beta)	✅ (beta)	单文件覆盖所有基础
Ruby	anthropic	✅ (beta)	✅ (beta)	单文件覆盖所有基础
PHP	社区 SDK	✅ (beta)	✅ (beta)	单文件覆盖所有基础
C#	Anthropic.SDK	❌	❌	单文件，仅基本 API
cURL	HTTP	N/A	✅ (beta)	managed-agents.md + examples.md

关键洞察：Python 和 TypeScript 是”完整支持”语言（多文件详细教程），其他语言是”基本覆盖”（单文件）。

语言检测路由机制

claude-api SKILL.md 中的语言检测逻辑：

检测规则：

• *.py、requirements.txt、pyproject.toml → Python
• *.ts、*.tsx、package.json → TypeScript
• *.js、*.jsx（无 .ts 文件）→ 也用 TypeScript 教程
• *.java、pom.xml、build.gradle → Java（Kotlin/Scala 也用 Java SDK）
• *.go、go.mod → Go
• *.rb、Gemfile → Ruby
• *.cs、*.csproj → C#
• *.php、composer.json → PHP

共享概念层设计

shared/ 目录存放语言无关的概念文档：

文件	内容
tool-use-concepts.md	工具调用的概念基础
agent-design.md	Agent 设计原则
prompt-caching.md	提示缓存策略
error-codes.md	HTTP 错误代码
model-migration.md	模型迁移指南
models.md	模型能力参考
live-sources.md	实时文档 URL 列表
managed-agents-*.md（13 个文件）	Managed Agents 的完整概念层

为什么需要共享概念层？ 如果每个语言目录都包含 Tool Use 概念的完整副本，当概念更新时需要同步更新 8 份。共享层确保”单一真相来源”。

实时文档源维护

shared/live-sources.md 维护了一份 URL 列表，指向官方文档的最新版本。当 SKILL.md 中的缓存数据可能过期时，通过 WebFetch 获取最新版本。

维护的 URL 包括：

• Anthropic SDK 文档（各语言）
• Claude API 参考文档
• Managed Agents 文档
• Anthropic CLI 文档

---

问题与规避

非 Anthropic 项目的误触发

问题：claude-api 技能可能在不相关的项目中被触发。

规避策略：技能开头有明确的提供程序检测：

Scan the target file for non-Anthropic provider markers — import openai, OpenAI(, gpt-4, filenames like *-openai.py. If you find any, stop and tell the user that this skill produces Claude/Anthropic SDK code.

不支持的语言

问题：Rust、Swift、C++、Elixir 等语言没有官方 SDK。

规避策略：建议 cURL/raw HTTP 示例，并注明社区 SDK 可能存在。

---

设计取舍

为什么 Python/TypeScript 是多文件而其他语言是单文件？

优势：Python 和 TypeScript 是最广泛使用的语言，值得详细文档。其他语言的用户群体较小，单文件足够。 代价：其他语言的高级功能可能需要额外查找官方文档。 Anthropic 的补偿：通过 live-sources.md 提供实时文档链接，弥补单文件的不足。

---

参考来源

• Anthropic Skills 仓库：skills/claude-api/SKILL.md
• Anthropic Python SDK：https://github.com/anthropics/anthropic-sdk-python
• Anthropic TypeScript SDK：https://github.com/anthropics/anthropic-sdk-typescript