技能介绍

要解决什么问题

在 Azure 上跑 SMB 文件共享时，常见路径是用连接字符串或账号密钥直连 Storage。这类做法在 Entra 审计、密钥轮换和 RBAC 上都比较弱，也不利于本地开发与托管标识之间同一套代码切换。若还要做目录树管理、大文件流式读写、局部区间更新或变更前快照，直接翻 REST 文档成本高，也容易在同步/异步客户端混用、资源未释放上踩坑。

技能如何组织能力

本技能围绕 azure-storage-fileshare 的客户端分层：ShareServiceClient（账户级）、ShareClient（共享）、ShareDirectoryClient（目录）、ShareFileClient（文件）。示例强调两条贯穿规则：优先 DefaultAzureCredential（本地 Azure CLI/VS Code 与云端托管/工作负载标识同一套鉴权），以及 同步 with / 异步 async with 包裹客户端与异步凭据，避免 HTTP 连接与令牌缓存泄漏。

核心操作可按场景串联：创建/列出/删除共享；在共享内创建目录、列举内容、删除目录；上传/下载文件、读属性、删除与复制；对大对象用 chunks() 流式处理；需要局部更新时用 区间（range） 上传/下载；重大变更前 创建快照 并访问快照视图。异步路径使用 azure.storage.fileshare.aio 与 azure.identity.aio，要求同一调用链只选一种模式。

适用边界与注意点

技能聚焦 File Share（SMB 语义），不是 Blob 容器或 Data Lake 专用 API。
生产环境应配合 Microsoft Entra ID + RBAC，并可通过 AZURE_TOKEN_CREDENTIALS 收紧凭据链；避免在生产依赖连接字符串。
参考 references/capabilities.md 与 references/non-hero-scenarios.md 可补充非核心能力与高级场景；配额（quota）与快照策略需自行按成本与合规设定。