SuperAPI AI 工具集

dv-overview

数据与分析

查看项目

更新于 10-16 00:31

技能介绍

用途:这是 Dataverse / Power Platform 工作的基础技能,任何 Dataverse 任务都应首先加载。它承载每项任务都需要的跨领域上下文:工作范围、工具能力参考、硬性规则和变更生命周期。它本身不做路由,智能体依据各专家技能自身的 WHEN / DO NOT USE WHEN 前置触发条件自动选择;用户用自然语言描述需求,智能体自动串联技能,从不要求用户说出技能名或命令。

覆盖范围:面向各类角色(构建者与智能体开发者、数据科学家、环境管理员、业务用户),由专家技能交付,包括 dv-connect(连接、认证、配置 MCP、验证环境)、dv-metadata(表、列、关系、表单、视图等架构)、dv-data(记录 CRUD、批量创建/更新/upsert、CSV 导入、示例数据)、dv-query(OData 查询、QueryBuilder、FetchXML、DataFrame)、dv-solution(解决方案 ALM)、erp-xpp(Finance and Operations X++)、dv-admin(环境管理)、dv-security(安全与访问)。模型驱动应用的站点地图与导航尚不是一等技能。范围外:画布应用、Power Automate 流、超出服务主体设置所需的 Azure 基础设施、Business Central 等其它 Dynamics 产品。

硬性规则:安全规则(初始化、认证、环境确认)不可协商。规则 0 要求先检查初始化状态:在写任何代码或创建文件前,主动搜索名称或描述含 dataverse 的可调用工具;找到 MCP 工具就直接使用,跳过初始化检查与全部设置,MCP 认证由宿主管理,不需要 .env 或 scripts/auth.py。未找到 MCP 工具时检查 CLI 配置:dataverse auth who;若显示带环境 URL 的活动配置,直接用 CLI 做数据操作。否则检查工作区初始化:ls .env scripts/auth.py 2>/dev/null;两者都存在则继续任务;任一缺失则运行 python <plugin-scripts>/auth.py --ping,打印 REACHABLE(退出码 0)则确认 URL 后继续,失败则运行 dv-connect。规则 1 要求脚本逻辑用 Python,禁止用 JavaScript/TypeScript/Node.js 编写自动化逻辑或自建 MSAL 设备代码流;始终用 pip install 与 Python SDK(PowerPlatform-Dataverse-Client),用 scripts/auth.py 获取令牌,把 Dataverse CLI(dataverse)和 pac 视为允许的一等 CLI。规则 2 强调按能力选择工具面而非固定顺序:优先托管面(MCP、Dataverse CLI 或 SDK)而非手写原始 OData;MCP 无法处理时(批量超过 25 条、大批量读取、表单/视图/N:N 关系/全局选项集/备用键等高级架构、多步工作流、分析,或 MCP 不可用)默认用 Python SDK;原始 Web API 是最后手段。字段大小写方面,$select/$filter 用小写逻辑名,$expand 与 @odata.bind 用区分大小写的导航属性名,须与 $metadata 一致,否则 400 错误。发布者前缀绝不硬编码(尤其 new),须查询现有发布者并询问用户,前缀永久有效。规则 3 要求使用文档化认证模式:dataverse auth create 写入共享 MSAL 令牌缓存,供 CLI、MCP 代理和 scripts/auth.py 使用;scripts/auth.py 负责 Python/SDK 认证;pac auth create 为 dv-solution、dv-admin、erp-xpp 认证 pac。遥测归属须保持确定性,每个请求携带封闭 schema 的 app=dataverse-skills/<ver>;skill=<skill>;agent=<agent> 上下文,不得修改、省略或自由改写。禁止读取或解析原始令牌缓存文件、自建 MSAL 设备代码流、硬编码令牌或凭据、发明新认证机制。规则 4 要求诚实面对缺口:技能是受支持且未弃用 API 的事实来源;遇到技能未覆盖的缺口应说明并建议变通,不得臆造未记录的方法、参数或端点。连通性不等于认证,登录令牌成功不代表组织数据面域可达;绝不上报未由真实调用返回的计数或结果,可用 python scripts/auth.py --check 验证,失败就说“不可达”。

工具能力:MCP 服务器适合数据 CRUD(每次批量最多 25 条)、表创建/更新/删除与列添加、架构与记录检查、元数据搜索、数据与文件内容搜索、文件上传下载;不支持表单、视图、全局选项集、N:N 关系、备用键、解决方案,其 SQL 读取不支持 DISTINCT、HAVING、子查询、OFFSET、UNION、CASE/IF、CAST/CONVERT、CTE 或日期函数。Python SDK 适合脚本化数据写入(尤其大批量)、upsert、批量操作、CSV 导入、文件列上传,以及批量读取、OData 查询、QueryBuilder、FetchXML 聚合与 N:N 连接、pandas DataFrame 导出。Dataverse CLI 适合无头数据面操作与 Web API 逃生舱。PAC CLI 适合解决方案导出/导入/打包/解包、ERP X++ SDK 安装与部署、环境管理、认证配置、用户角色分配等。Azure CLI 与 GitHub CLI 不处理 Dataverse 专属操作。原始 Web API 仅在无托管面可用时使用,且优先 dataverse api。

限制:MCP 不可用且用户明确要求 MCP 时,不得静默回退到 SDK 或 Web API,应告知未配置并加载 dv-connect,配置后需重启会话。MCP 不可用但用户只是问数据问题时,可用 CLI 或 SDK 回答,之后再提议配置 MCP。部分 CLI 在 ChatGPT 网页 / Codex 云端因无 .NET 运行时被阻止,应改用 SDK;X++ SDK 安装与编译需要 Windows。资料未提供收费、价格与效果信息。