pydantic-claude-code Skill 技能

技能简介

pydantic-claude-code 让你在普通的 pydantic-ai Agent 或 CLAI2 中直接使用自己的 Claude Code 订阅额度，拥有完整的 pydantic-ai 工具支持——不需要 API Key，也不产生额外计费：只要 Claude Code 能在终端里用，这个包就能用。PyPI 包名 pydantic-claude-code（pip install pydantic-claude-code），导入名 pydantic_ai_claude_code。支持的模型包括 Claude Opus 5.5、Sonnet 5.5、Fable 5.1 与 Haiku 4.5（模型 ID 与 CLAI2 菜单一致，并对照 Anthropic 官方模型列表核验过），订阅能服务的其他模型 ID 同样可用。

核心能力

1. 订阅复用、零额外计费：使用与 Claude Code CLI 相同的共享公开 OAuth 客户端（PKCE 授权），把订阅令牌作为模型凭据，不再按 token 另行付费。
2. pydantic-ai 全功能兼容：@agent.tool_plain 定义的工具按标准 Anthropic 工具定义发送；Pydantic 结构化输出、流式输出（run_stream）与内置 anthropic 提供方行为一致。
3. CLAI2 插件形态：一条 curl 命令把插件装进 CLAI2 插件目录，/login claude-code 浏览器登录后，/model、/model_settings 直接选择 claude-code:MODEL，支持多账户 Profile（claude-code@work:模型）与账户用量查看。
4. 提示词缓存：ClaudeCodeModel 默认开启 1 小时 TTL 的提示缓存，可用 AnthropicModelSettings(anthropic_cache="5m") 覆盖或关闭，长会话省 token。
5. 安全的凭据存储：OAuth 令牌对默认存系统钥匙串（macOS 钥匙链 / Windows 凭据管理器 / Linux Secret Service），无钥匙串的机器降级为 0600 权限文件；令牌自动刷新，过期时抛出明确的 ClaudeCodeSignInExpiredError。
6. 自动更新提示：CLAI2 每次启动后台检查 PyPI，发现新版本只提示一次更新命令，离线静默，可用环境变量关闭。

安装配置

1. CLAI2 插件安装：curl -fsSL https://gist.githubusercontent.com/mpfaffenberger/bd75c7b424ffdc6d81645bfe7de822d3/raw/install.sh | sh（重复执行即更新）；或手动 git clone 该 gist 到 ~/.config/pydantic-clai2/plugins/claude_code。插件依赖已随 CLAI2 附带，无需 pip 安装。
2. CLAI2 版本要求：类式 Plugin 需 pydantic-clai2 0.53.0+（Python 3.10–3.14），可 uvx --from pydantic-clai2 clai2 免安装试用；旧版可回钉插件 0.5.0。
3. Python 库安装：pip install pydantic-claude-code，在自己代码里直接构造 ClaudeCodeModel('claude-fable-5-1')。
4. 登录：CLAI2 内 /login claude-code 走浏览器 OAuth；或命令行 python -m pydantic_ai_claude_code login。SSH/远程机器可复制回调 URL 粘贴完成登录；凭据存储可用 CLAUDE_CODE_CREDENTIALS=keyring|file 强制指定。

使用步骤

1. 一次性登录：运行 login()（或 shell 登录），浏览器授权后令牌入库；此后只在令牌被吊销时才需重登。
2. 创建 Agent：agent = Agent(ClaudeCodeModel('claude-opus-5-5'))，模型字符串也可写成 claude-code:claude-opus-5-5 形式交给 CLAI2。
3. 运行对话：result = await agent.run('用三个词打招呼')，普通对话、工具调用与结构化输出写法与 pydantic-ai 内置提供方完全一致。
4. 挂工具与结构化输出：@agent.tool_plain 装饰函数即成为 Anthropic 工具；output_type=Pydantic模型 得到类型安全的结果。
5. 无头运行：clai2 -p "总结这个仓库" -m claude-code:claude-fable-5-1 适合脚本与 CI。

适用场景

1. 已有 Claude Code 订阅的个人开发者：在自己的 Python Agent 项目里白嫖订阅额度，不另买 API Key。
2. 已在用 CLAI2 的用户：给 CLAI2 增加 claude-code: 模型档位，与其它提供方并存切换。
3. 多账户管理：订阅有工作/个人多个账号时，用 Profile 与 fallback 链（/chain）做额度池化。
4. 本地开发与评测：用同一套 pydantic-ai 代码在 Anthropic 官方 API 与订阅通道之间切换对比。
5. 结构化数据抽取/流水线：需要类型安全输出 + 订阅额度跑批量任务的自动化脚本。

适用人群

pydantic-ai 生态的 Python 开发者、CLAI2 用户、拥有 Claude Code 订阅并希望在脚本与 Agent 中复用额度的工程师。

工作原理

包内实现一个 ClaudeCodeProvider + ClaudeCodeModel：运行时用与 Claude Code CLI 相同的 OAuth 流程（授权端点 claude.ai/oauth/authorize、令牌端点 platform.claude.com/v1/oauth/token、同一 scope）拿到令牌并存入钥匙串；每次请求以 Messages API 直连 Anthropic，携带订阅令牌并自称 Claude Code CLI 版本（请求会前置 CLI 同款系统提示），刷新令牌在过期前自动续期、遇 401 重试一次。它并不以子进程运行 Claude Code CLI，因此不继承 CLI 的沙箱与权限提示——应像对待任何可执行代码的 Agent 一样审慎授予权限。

官方链接

• PyPI：https://pypi.org/project/pydantic-claude-code/
• 源码（gist 插件）：https://gist.github.com/mpfaffenberger/bd75c7b424ffdc6d81645bfe7de822d3
• 关联仓库：https://github.com/mpfaffenberger/code_puppy_core_plugins
• pydantic-ai：https://github.com/pydantic/pydantic-ai