校验、权限与资源限制
视图发布前完整下载并校验 Go 兼容清单摘要、SHA-256、大小、路径和权限位。仅使用视图私有内存缓存，没有共享磁盘或离线缓存。默认上限：10,000 个文件，单文件及清单各 8 MiB，单快照 64 MiB，SKILL.md 解析输入 256 KiB。并发和保留旧视图会叠加内存，应用应限制并发并释放引用。
每次公共读取、目录获取、导出均在线重新检查指定快照清单，即使内容已缓存。权限变化使捕获视图失效，已知客户端撤销在本客户端实例内持续生效。网络失败即阻止操作。不提供离线模式、透明网络重试或业务任务重试。最后检查之后的鉴权竞态和已交付内容无法撤回。不跟随 HTTP 重定向，SDK 错误消息不包含令牌；自行开启的底层网络日志仍可能暴露凭据，需要正确配置。默认忽略环境代理和 CA 配置（trust_env=False），需要时显式设置 trust_env=True；SOCKS 代理还需安装 httpx[socks]。也可传入自定义 HTTPX transport 配置 TLS 或代理。
主要错误：VersionMismatch、ManifestChanged、AuthorizationDenied、IntegrityError、ProtocolError、LimitExceeded、SkillNotFound、TransportError、ClosedError。
开发与验证
uv sync --extra dev --extra pydantic-ai
uv run pytest -q
uv run ruff check src tests examples
uv run python -m build
uv run python examples/offline_demo.py
测试使用受控分发服务和真实 Pydantic FunctionModel 执行循环，不调用外部模型。覆盖更新、回滚、同快照权限变化、并发读取和执行、历史内容版本、损坏、目录隔离及 Go 生成的清单兼容样例。离线演示不需要服务端或凭据；不能替代与实际部署和模型供应商的联调验收。
参见 examples/ 和 CHANGELOG.zh-CN.md。官方集成依据：Pydantic capabilities、Agent Skills 实现指南。
完整场景和结果记录：测试指南。
验证范围
三组复杂 Skill（expense-audit、release-review、data-contract）覆盖双版本、嵌套引用、脚本、Unicode、二进制和空文件。还覆盖并发更新、回滚、撤权、损坏和模型多轮加载。
已验证提交 011bf4f 的 Linux CI 在 Python 3.11、3.12、3.13 上通过 102 项测试、构建和离线示例。Agent 测试使用真实 Pydantic AI 循环与脚本化 FunctionModel，不调用真实模型；真实服务端、供应商和部署环境仍需联调。
继续阅读
Python SDK 快速开始 · 快照与更新策略 · Pydantic AI 集成 · 导出文件与框架接入
授权与暂时故障
凭据缺失、过期、Profile 禁用或撤销返回 403 CLIENT_FORBIDDEN；数据库故障返回 503 DISTRIBUTION_UNAVAILABLE，附带 Retry-After: 1，由应用决定重试边界。SSE 在数据库故障时发出 unavailable 并关闭以便重连；只有确实拒绝凭据时才发出 revoked。响应不暴露数据库细节。已交付的 Skill 或模型上下文无法撤回。
成功认证的请求最多每 30 秒更新一次活动时间，普通 SDK 请求也能显示在线。这表示请求活动，不保证 Agent 任务健康；不会伪造挂载缓存指标或上报快照。
历史授权保留
运行新版服务端前执行 00004_snapshot_grant_retention.sql 迁移。可选 SKIVA_SNAPSHOT_GRANT_TTL_SECONDS：不配置或 0 保持历史授权无限期；正整数（最大 315360000）使新授权从首次授权时起按固定期限有效，后续读取不会续期。已有无限期授权不会追溯缩短。无效配置返回 503，拒绝发放授权。
过期的历史授权会拒绝清单与对象读取。当前通道目标、Profile 配置的固定目标仍可访问并重新授权。因此它是历史版本保留策略，不是对某个发布的管理封禁。回滚不会撤销此前授权；停止后续读取可以移除 Profile 的 Skill 权限或撤销客户端凭据。不会自动回收授权记录、删除快照或撤回导出文件。SDK 持久化绑定遇到授权过期时明确失败，不改用最新版本。
保持在线授权的性能优化
SDK 使用有界元数据缓存发送 If-None-Match。服务器在返回 304 前仍检查授权与当前权限过滤后的清单。ETag 包含快照 ID、清单摘要与通道 generation，避免相同内容的不同快照被混淆。对象授权改用 SQL 成员查询，无需每个文件都重新生成完整清单，仍检查当前 Profile 权限。这减少重复工作；尚未通过基准测试量化吞吐提升。