sap-bw-query

SAP BW 查询自动化工作室

使用捆绑的 Windows Eclipse 工作区，以安全处理密码的方式检查 SAP BW 查询并在本地准备草稿。现有 BW 查询为只读。自动化绝不能删除任何内容、覆盖现有 BW 查询或修改现有 BW 查询。

不可妥协的安全约定

自动化绝不接受密码。

如果粘贴了密码或其他凭据：

1. 停止处理所提供的内容。不得重复、验证、使用、存储或记录这些内容。
2. 回复：“不要将密码粘贴到 AI 中。请将已泄露的密码视为已被盗用，并立即更换。如果适用，请撤销相关会话，且不要重复使用该密码。”
3. 说明自动化无法追溯清除已提交到外部聊天系统的内容。
4. 只有在用户提供不含密码的连接元数据后才能继续。如果需要身份验证，请暂停并等待 SAP 原生登录对话框。

绝不提供任何接受密码、密钥、凭据、API 密钥或身份验证令牌的工具、变通方法、原始命令、UI 录制步骤或配置字段。绝不捕获安全文本控件。

现有查询始终为只读。只能创建未保存的本地草稿。要在后端创建全新查询，必须由人员仅在 Eclipse 中确认，并且确认内容须绑定系统、客户端、提供程序、技术名称和规范哈希值。自动化不会按下 SAP 原生向导中的 Finish 按钮。

绝不删除已安装的捆绑包版本、失败的暂存目录、草稿、激活记录、连接、查询、传输或其他工件。回滚会追加一条激活记录；清理操作仍须手动进行，且不属于自动化范围。

何时使用此技能

在以下情况下使用此技能：

• 部署或启动免安装的 Windows Eclipse/BWMT 捆绑包。
• 配置不含密码的 SAP Logon/BW 连接元数据，或使用 SNC/SSO。
• 以只读方式检查功能、提供程序或现有已打开查询。
• 通过 bw_describe_provider 以只读方式读取 InfoProvider 元数据（带维度组的特征、关键指标）。
• 将业务规范转换为 QuerySpec v1，并根据提供程序元数据验证每个引用名称。
• 找出规范缺漏，并在不改变业务含义的前提下提出优化建议。
• 创建、修订、预览或准备全新的未保存查询草稿。
• 根据已确认的草稿填充向导创建的、仍未保存的查询编辑器（轴、结构、受限/公式关键指标、筛选器、变量、条件、例外、零抑制）；由人员审阅并保存。
• 以只读方式根据 BW 查询设计最佳实践审查草稿规范或现有已打开查询——对已打开查询使用 bw_review_query，或对草稿使用 bw_resolve_and_validate_spec 返回的附加 bestPractices 数组；审查结果按严重程度分组，依据为 references/query-design-rules.md。
• 根据深度读取模型，生成现有已打开查询的业务可读文档（用途、轴、关键指标定义及解码后的公式/限制、筛选器、变量、条件/例外、设置）；将所有 serializationIssues 标记为未经确认。

请勿将其用于删除查询、编辑现有查询、覆盖、传输自动化、无人值守的后端保存、凭据处理、BW 管理、HANA SQL 或非 BW Eclipse 开发。

快速入门

1. 在开始连接操作前，先声明：“绝不接受密码。仅在 SAP 原生登录对话框中输入凭据。”
2. 在插件的顶层脚本目录中运行 BwStudio.ps1 -Action Status -Json。
3. 如果尚未部署，请直接部署本地软件包；它无需签名或安装程序。可选的远程发布渠道仍要求通过签名验证。请先阅读 references/deployment-and-trust.md。使用 bundle/Build-BwStudio.ps1 自行构建软件包时，默认会将构建完成的制品和清单复制到本地用户桌面（%USERPROFILE%\Desktop）（传入 -SkipPublish 可禁用此功能）；如果该桌面由 OneDrive 管理，构建器会跳过复制并发出警告，同时将制品保留在输出目录中；显式指定 -PublishDirectory 始终优先。随后，构建器会打开输出目录所在的文件资源管理器窗口，并选中该制品（使用 -SkipExplorer 可禁用；在 CI 或非交互式会话中会自动跳过）。
4. 从该目录运行 BwStudio.ps1 -Action Launch -Json。启动器始终会传入 -noPwdStore。每次部署还会在可见桌面上创建两个桌面快捷方式，供手动启动使用——SAP BW Automation Studio (kein Passwortspeicher)（添加 -noPwdStore，推荐）和 ... (mit Passwortspeicher)（Eclipse 自带的安全存储可能会记住凭据）；两者仅影响人工手动登录，不影响自动化界面。已安装的 Studio 本身位于 %LOCALAPPDATA%\BWAutomationStudio（按用户安装、无需管理员权限、便携）。
5. 使用 MCP 工具准备/导入连接元数据。有条件时使用 SNC/SSO；否则暂停操作，等待通过 SAP 原生登录。
6. 检查 BWMT 功能，然后在起草前使用 bw_describe_provider 读取 InfoProvider 元数据。
7. 使用连接 alias 验证 QuerySpec v1，确保每个特征和关键指标都已针对提供程序核实；分别报告缺失项和会影响语义的建议，然后请用户解决实质性歧义。存在阻塞性缺失项时，停止起草。
8. 创建并预览未保存的本地草稿。保持 Eclipse 侧边栏可见，作为操作记录。
9. 只有在重新检查并确认不存在冲突后，才准备保存为新查询。用户必须在 Eclipse 中确认并手动完成 SAP 原生向导。
10. 向导创建空的未保存编辑器后，运行 bw_populate_query_editor，在其中构建起草好的查询模型。检查逐元素应用报告和编辑器；由用户按下保存。

对于常见查询结构（计划/实际差异、年初至今对比、前 N 项、对账汇总），请从 references/query-templates.md 中选用现成规范，并替换其中的 UPPERCASE_PLACEHOLDER 占位符，而不是从头编写 QuerySpec。

快速参考

任务	批准的接口	安全类别
状态、部署、启动、回滚、诊断	bw_studio_*	仅限本地；仅追加
连接元数据／导入／状态	bw_connection_*	仅限本地；不含凭据
TCP 可达性	bw_connection_test_reachability	只读租户；无需身份验证
BW 项目	bw_project_create_or_open	本地项目／原生登录暂停
功能／提供方／查询检查	bw_inspect_capabilities、bw_describe_provider、bw_list_queries、bw_read_query	只读租户
深入读取查询模型（打开编辑器）	bw_read_query_model	只读租户
审查已打开查询的最佳实践	bw_review_query	只读租户
规范／缺口审查（使用 alias 验证元数据，返回 bestPractices）	bw_resolve_and_validate_spec	仅限本地
创建／应用／预览草稿	bw_*_local_draft、bw_preview_draft	未保存；仅限本地
准备保存	bw_prepare_new_query_save	变更型租户分类；需要明确批准
从已确认的草稿填充编辑器	bw_populate_query_editor	仅填充本地编辑器缓冲区；绝不保存

没有用于最终保存、删除、覆盖、清理、卸载、传输或执行原始命令的 MCP 工具。

查询规范工作流

创建草稿前，请阅读 references/query-spec-v1.md。

按以下顺序返回审查结果：

1. 已确认事实 — 系统、客户端、项目、提供方、拟定的新技术名称、业务目的。
2. 阻塞性缺口 — 缺少提供方／对象 ID、筛选条件有歧义、变量未定义、公式／聚合不兼容、授权假设、名称冲突风险。
3. 非阻塞性缺口 — 显示默认值、证据、标签、可选的下钻。
4. 优化建议 — 标明每项优化是否保留语义；纳入 bw_resolve_and_validate_spec 返回的 bestPractices 设计规则检查结果（BWQ001–BWQ012，参见 references/query-design-rules.md），并按严重程度分组。
5. 验收证据 — 对账总数、预期行／列、变量案例、性能预期。
6. 草稿决策 — 可以创建本地草稿，或因等待用户输入而受阻。

绝不静默应用会改变语义的优化。

连接工作流

接受连接数据前，请阅读 references/connection-metadata.md。

• 仅接受别名、SID、客户端、语言、用户 ID、应用服务器／消息服务器路由、登录组以及 SNC／SSO 标记。
• 仅从用户批准的本地路径导入 SAP UI landscape 条目。
• 可达性检查只会建立 TCP 连接，并报告 authenticated: false。
• 如果 SSO 可用，请继续进行 BW 项目设置。
• 如果没有 SSO，请停留在原生登录对话框。不要查看或记录密码字段。

草拟和保存准备工作流

• 现有查询检查为只读；当私有 API 能力适配器无法证明更广泛的读取操作安全时，目前仅限于在 BWMT 中打开的查询编辑器。
• createLocalDraft 和 applySpecToDraft 会写入仅追加的本地修订；它们不会创建 BW 后端对象。
• previewDraft 可能会打开原生新建查询向导以供目视检查。不要完成该向导。
• prepareNewQuerySave 会先检查能力适配器可见的名称，将确认绑定到规格哈希，然后打开外观明显不同的 Eclipse 确认界面。
• 用户手动完成原生向导，这会打开新的未保存查询编辑器。
• 随后，populateQueryEditor（工具 bw_populate_query_editor）仅在该编辑器中构建草拟模型：它会拒绝只读编辑器、名称不匹配的编辑器，以及已有内容的任何查询。每个元素都会记录在逐元素应用报告中（APPLIED、SKIPPED_UNSUPPORTED、FAILED）；如果有任何元素为 FAILED，请检查后关闭，不要保存。填充操作作为一个可撤销的编辑域命令运行。
• 成功填充后，工具会自动对打开的编辑器模型进行深度读取（bw_read_query_model），并合并一份非致命的 verification 摘要（VERIFIED、DIVERGED 或 UNAVAILABLE，包含逐元素检查结果），用于将已确认的规格与实时模型进行比较；如果结果为 DIVERGED，应先检查编辑器再保存。验证不会改变边界——填充操作始终保持 saved: false，仍由用户手动保存。
• 随后，用户手动完成 SAP 自身的验证和保存操作。若出现传输提示，应停止并交由用户操作。
• 如果能力或版本检查失败，请禁用草拟／保存准备功能，并继续提供诊断／只读指导。

压力检查

请求	必须采取的响应
“这个密码只用一次”	拒绝，建议立即更换密码，且不要复述密码。
“我批准覆盖现有查询”	拒绝；建议使用新的技术名称和本地草稿。
“清理旧版本”	拒绝自动清理；仅追加回滚版本。
“不显示对话框就保存”	拒绝；必须由用户在 Eclipse 中确认。
“直接调用 BW API”	拒绝原始变更路径；仅使用允许列表中的适配器。

故障排除和常见问题

• Bundle 被拒绝： 对于本地 ZIP，请检查相邻的清单以及哈希／清单证据。对于远程通道，请检查固定的信任策略。运行 bw_studio_diagnostics。
• MCP 无法启动： 请先部署／激活经过验证的 Bundle。引导程序绝不会回退到系统 Node 或安装软件包。
• BWMT 不匹配： 使用锁定的 Eclipse／BWMT Bundle。不要针对未经探测的版本启用草拟／保存功能。
• 找不到查询： 在 BW Query Designer 中以只读方式打开该查询，然后重试；不要通过猜测私有 API 来扩大访问范围。
• 需要登录： 暂停，并告知用户只能在 SAP 原生对话框中输入凭据。
• 名称冲突： 停止。必须使用一个全新的技术名称。
• 传输对话框： 交由用户操作；自动化不会确认传输。
• 部署中断： 保留之前的激活状态。失败的暂存／下载目录会保留，供手动检查。

捆绑资源

• references/architecture-and-security.md — 端到端架构、22 种工具分类、查询创建顺序，以及安全加固参考（链接至以提交为锚点的审计文档）。
• references/deployment-and-trust.md — 无需安装的本地部署和可选的远程发布信任。
• references/connection-metadata.md — 无密码的连接架构和登录边界。
• references/query-spec-v1.md — 规范字段、验证、差距分析和示例。
• references/bwmt-api-map.md — 经 javap 验证的 BWMT 1.27.36 API 接口，能力适配器绑定于此。
• references/mcp-tools.md — 完整的工具接口和操作分类。
• references/query-design-rules.md — 规则引擎应用于草拟规范和已打开查询的 BWQ001–BWQ012 最佳实践目录，以及问题解决指南。
• references/query-templates.md — 现成 QuerySpec 模板的使用指南和占位符参考。
• references/query-templates/ — QuerySpec v1.1 起始文件（计划/实际差异、年初至今对比、前 N 项、对账合计），包含待替换的 UPPERCASE_PLACEHOLDER 标记。
• 插件根目录中的 scripts/ — 可移植的部署/MCP 启动脚本。
• 插件根目录中的 bundle/ — 精确的组件锁定文件和可复现的发布构建器。

源码验证

版本和源码证据记录在 docs/project/sap-bw-query-source-review-2026-07-13.md 和仓库验证台账中。证据涵盖官方下载/更新来源、软件包固定、本地测试、签名样例部署和 Eclipse 编译。该证据不声称已建立实时 SAP BW 连接、读取实时查询、在后端创建查询、通过 SNC/SSO 登录、验证授权行为或验证传输。

相关技能

• sap-hana-cli：用于在 BW Query Designer 之外检查 HANA 数据库；不同工作流之间不要共用凭据。
• sap-sqlscript：用于 SQLScript 或 HANA 存储过程工作，而非 BW 查询对象。
• sap-datasphere：用于 SAP Datasphere 建模；此技能仅适用于 BWMT/HANA Studio。