sap-sac-scripting

SAP Analytics Cloud 脚本编写

相关技能

• sap-dependency-security：在保护故事自动化流水线中使用的依赖项、SDK/工具，以及固定源码的 SAC MCP 升级时使用
• sap-browser-automation：用于在应用内手动进行身份验证、经同意后复用 Edge 配置文件、启动全新的 Edge/CDP、初始化身份验证状态以及恢复浏览器

何时使用此技能

编写或调试 SAC Analytics Designer 脚本、Optimized Story Experience 脚本、微件 API、数据源筛选/选择逻辑、计划/版本脚本、导出/导航处理程序、对性能敏感的故事逻辑，或 SAC MCP 辅助自动化时，请使用此技能。

用于在 SAP Analytics Cloud（SAC）Analytics Designer 和 Optimized Story Experience 中编写脚本的综合技能。

如需检查经过身份验证的 SAC 浏览器运行时，请使用 sap-browser-automation 进行应用内手动身份验证、经同意后复用 Edge 配置文件、启动全新的 Edge/CDP、初始化身份验证状态以及恢复浏览器。加载本地 references/edge-cdp-control.md，了解 SAC 脚本编写相关的边界。使用 CDP 进行本地运行时问题排查、微件状态检查和经批准的屏幕截图；不要操作无关的标签页。

入门

当用户在没有指定具体任务时调用此技能（例如“帮我处理 SAC 脚本编写”、“使用 SAC 脚本编写技能”，或没有后续问题），请按以下结构提供说明：

欢迎！我可以帮助你编写 SAP Analytics Cloud 脚本。

首先，你使用的是哪个环境？

1. Analytics Designer — 基于应用的脚本编写，完整 API
2. Optimized Story Experience — 基于故事的脚本编写，OSE API（v2025.20）

接下来，你需要什么帮助？

• 编写新脚本（筛选、计划、导航、导出……）
• 调试现有脚本
• 优化性能
• 查找合适的 API 方法
• 计划操作（版本管理、数据锁定……）

插件组件

此插件提供用于 SAC 开发的专用工具：

Agent（通过 Task 工具使用）：

• sac-script-debugger - 调试脚本错误、追踪问题
• sac-performance-optimizer - 分析并修复性能瓶颈
• sac-planning-assistant - 指导计划操作和版本管理
• sac-api-helper - 查找正确的 API 并提供代码示例

命令（通过 /command 使用）：

• /sac-script-template - 生成脚本模板（筛选、计划、导出等）
• /sac-debug - 提供交互式调试指导
• /sac-optimize - 分析性能并提供建议
• /sac-planning - 计划操作模板

钩子：

• 写入 SAC 脚本时自动检查常见问题

MCP 设置

此插件附带一个 .mcp.json，用于连接受信任的 secondsky/sap_analytics_cloud_mcp 服务，提供覆盖 11 个服务领域（内容、数据导出、数据导入、多重操作、日历、内容传输、用户管理、监控、计划与发布、翻译、智能查询）的 90 个 SAC REST API 工具。

SAC MCP 通过源码安装，而非通过 npm 安装。更改受信任的分支或提交固定版本前，请先使用 sap-dependency-security，因为此服务会接收 SAC OAuth 凭据，并提供租户 API 工具。

使用 MCP 工具前，请检查服务是否已安装：

• 查看项目中的 .claude/sac-mcp.local.md
• 或检查环境中是否设置了 SAC_MCP_PATH

如果尚未安装，只询问用户一次：“需要我帮助设置 SAC MCP 服务吗？”

如果需要，请引导用户完成以下步骤：

1. 克隆并构建：

   git clone https://github.com/secondsky/sap_analytics_cloud_mcp
   cd sap_analytics_cloud_mcp
   git checkout 2020235505d98111c2889598ab2217c1619b6943
   npm ci --ignore-scripts
   npm run build
   

2. 配置环境变量：

   • SAC_MCP_PATH — 克隆仓库的绝对路径（例如 /home/user/sap_analytics_cloud_mcp）
   • SAC_MCP_COMMIT — 2020235505d98111c2889598ab2217c1619b6943
   • SAC_BASE_URL — SAC 租户根 URL（例如 https://mytenant.eu10.hanacloudservices.cloud.sap）
   • SAC_TOKEN_URL — OAuth 令牌端点
   • SAC_CLIENT_ID / SAC_CLIENT_SECRET — 来自 SAC OAuth 客户端配置

3. 安装成功后，创建 .claude/sac-mcp.local.md（已加入 gitignore），内容如下：

   # SAC MCP Installation Record
   - Installed: [date]
   - Repository: https://github.com/secondsky/sap_analytics_cloud_mcp
   - Commit: 2020235505d98111c2889598ab2217c1619b6943
   - Path: [absolute path to build/index.js]
   - Build command: npm ci --ignore-scripts && npm run build
   - Env vars configured: SAC_MCP_PATH, SAC_MCP_COMMIT, SAC_BASE_URL, SAC_TOKEN_URL, SAC_CLIENT_ID, SAC_CLIENT_SECRET
   

这样可以避免在后续会话中再次询问。

Q2 2026 新功能（2026.8）

最新 SAC 版本中的脚本增强功能：

• 增强的 onAfterExecute 事件 - 上传事件现在包含消息、统计信息、被拒绝的记录、目标版本和文件名
• 数据导出 API 作业监控 - 新增作业监控选项卡，用于监控增量提取和计算作业
• 数据导入服务 API - 将主数据导入 SAP Datasphere 中的公共维度；将外部事实数据导入私有版本
• 多重操作 API 步骤 - 现在允许 HTTP 204 响应；增强了标头字段限制
• 导出到 S/4HANA 已弃用 - 请改用回写集成场景
• 非对称报表 - 每行／列可使用不同的时间范围、层级和度量
• 复合版本控制 - 在故事设计期间管理多个复合版本

完整详情请参阅 references/whats-new-qrc2-2026.md。

环境检测

编写或分析任何脚本前，请先确定用户正在使用哪种 SAC 环境。

检测信号：

信号	环境
提及 .story、“Optimized Story”、OSE、Story.、Application.getActivePage()	OSE
提及 Analytics Designer、AnalyticApplication、Designer、.application	Analytics Designer
仅说“SAC 脚本”／“我的脚本”，未提供其他上下文	不明确

环境不明确时，请先提出一个简短问题，再继续：

“您是在 Analytics Designer 还是 Optimized Story Experience 中编写脚本？这会决定我使用哪份 API 参考文档。”

用户回答后，不要再次询问。

确认后，使用相应的参考文档：

• OSE → references/ose-api-*.md（8 个文件，Q2 2026，v2025.20）
• Analytics Designer → references/api-*.md（现有文件）

报表故事工作流

对于只读的 SAC 故事、仪表板和管理报告，请使用此工作流。此工作流与规划分开：将回写、版本发布、数据操作、分配、数据锁定及其他规划操作路由到 sap-sac-planning。

1. 明确约定：确认租户、故事、数据源、目标受众，以及用户是否禁止更改模型。除非用户明确授权更广泛的范围，否则将仅涉及报表的请求视为故事层工作。
2. 检查实际元数据：确认所选模型，并且只使用其公开的维度、度量、层次结构、时间字段、货币和比较类别。切勿仅仅因为某个字段对拟议的图表或 KPI 有用就凭空编造。
3. 在故事层进行设计：定义页面、微件、筛选器、选择项、导航和受支持的故事计算。明确标注比较类别，例如实际值与预算、预测值或其他可用类别。
4. 安全实施：保存前，确认当前 SAC 区域是 Story Designer，而不是 Modeler。确保常用筛选器和依赖微件交互均为只读且不会造成破坏。
5. 验证或移交：使用 sap-sac-test-automation 验证页面和微件是否就绪。如果无法控制经过身份验证的租户，请遵循 sap-browser-automation 和本地的 references/edge-cdp-control.md 恢复路径。如果仍无法访问，切勿声称故事已创建；请提供完整的故事规格，以便手动执行或在之后连接的会话中执行。

只读故事约定

模型不得更改时，允许执行以下操作：

• 创建或编辑故事页面、图表、表格、KPI 卡片、筛选器、导航，以及 SAC 支持的故事层计算；
• 重命名故事对象并保存故事；
• 检查模型元数据并执行只读验证。

未经明确授权和批准，禁止执行以下操作：

• 编辑模型维度、度量、属性、连接、日历、分配或设置；
• 创建模型级计算度量，或更改主数据、角色或权限；
• 发布规划版本、执行数据操作、更改锁定状态，或回写规划数据。

如果模型未公开所需字段或度量，请省略依赖该字段或度量的微件，并记录省略原因。不要更改模型以适配设计。

可直接实施的移交说明

租户交互受阻时，请提供可用的规格，其中包括：

• 故事目的、目标受众、数据源和已确认的模型元数据；
• 按页面列出仅使用已确认字段的微件；
• 筛选器、比较语义、选择项和下钻；
• 已省略的微件或尚未解决的字段及各自原因；
• 只读安全限制和仍需提供的验证证据。

大型参考文档的搜索路由

打开大型 OSE API 参考文档前，先使用 rg 搜索。可使用如下模式：rg -n "class Chart|interface DataSource|enum Feed|setDimensionFilter|getPlanning|PlanningModel" references/ose-api-*.md，然后只阅读匹配的部分。

• DataSource、DataAction、DataBinding、DataLocking、DataChangeInsights 和结果集方法请参阅 references/ose-api-datasource.md。
• Chart、Table、GeoMap、RVisualization、ValueDriverTree、feeds 和可视化 API 请参阅 references/ose-api-chart-viz.md。
• Planning、PlanningModel、版本、日历、数据操作和规划工作流请参阅 references/ose-api-planning-calendar.md。
• Application、PageBook、Panel、Popup、Widget 以及生命周期或容器 API 请参阅 references/ose-api-application-core.md。
• 如果方法签名提及 Feed、Layout、NumberFormat、VariableValue 或其他 SAC 专用类型，请参阅 references/ose-api-types-enums.md 查询枚举或类型。
• 对于 Analytics Designer，请优先使用较小的 references/api-*.md 文件，除非用户明确指定 Optimized Story Experience。

快速入门

脚本编辑器访问

• Analytics Designer：编辑模式 → 选择微件 →「Scripts」标签页
• Optimized Story Experience：高级模式 → 选择微件 → 添加脚本

基本脚本结构

// Event handler example (onSelect on Chart_1)
var selections = Chart_1.getSelections();
if (selections.length > 0) {
    var selectedValue = selections[0]["Location"];
    Table_1.getDataSource().setDimensionFilter("Location", selectedValue);
}

核心 API

DataSource API

通过 Widget.getDataSource() 访问。主要方法：

• getMembers(dim, {accessMode: MemberAccessMode.BookedValues}) - 高效获取维度成员
• getResultSet() - 缓存数据访问（优先于 getData()）
• setDimensionFilter(dim, value) - 应用筛选器
• setRefreshPaused(true/false) - 批量执行多个操作

Planning API

通过 Table.getPlanning() 访问。主要操作：

• getPublicVersion() / getPrivateVersion() - 访问版本
• publish() - 将私有版本提交到公共版本
• copyFromPublicVersion() / copyToPublicVersion() - 复制数据
• setLock(true/false) - 锁定数据

微件 API

• 图表：addMeasure()、addDimension()、getSelections()
• 表格：addDimensionToRows()、setZeroSuppressionEnabled()
• 容器：用于布局的 Panel、TabStrip、PageBook

Application 对象

全局实用工具：

• Application.showBusyIndicator() / hideBusyIndicator()
• Application.showMessage(type, text)
• Application.getUserInfo() / getInfo()

性能最佳实践

1. 尽量减少后端调用

   // Use getResultSet() (cached) instead of getMembers() (backend)
   var data = ds.getResultSet();
   

2. 批量执行筛选操作

   ds.setRefreshPaused(true);
   ds.setDimensionFilter("Dim1", value1);
   ds.setDimensionFilter("Dim2", value2);
   ds.setRefreshPaused(false); // Single refresh
   

3. 让 onInitialization 保持为空 将耗时操作延迟到懒加载或首次交互时执行。

4. 使用 BookedValues 获取成员

   var members = ds.getMembers("Dim", {accessMode: MemberAccessMode.BookedValues});
   

调试

控制台日志

console.log("Debug:", myVariable);
console.log("Selections:", JSON.stringify(Chart_1.getSelections()));

浏览器开发者工具

1. 按 F12 →「Console」标签页
2. 按「Info」类型筛选
3. 在 URL 中添加 ?APP_PERFORMANCE_LOGGING=true 以查看计时信息

捆绑资源

参考文件（66 个文件）：

• 核心 API：references/api-datasource.md、references/api-widgets.md、references/api-planning.md
• 高级内容：references/api-calendar-bookmarks.md、references/api-advanced-widgets.md
• 最佳实践：references/best-practices-developer.md、references/best-practices-planning-stories.md
• 语言：references/scripting-language-fundamentals.md
• 与 Q2 2026 相关的 API 更新：references/whats-new-qrc2-2026.md、references/whats-new-2025.23.md、references/chart-variance-apis.md
• 浏览器运行时问题排查：references/edge-cdp-control.md 介绍 SAC 特定的边界；身份验证、Edge/CDP 设置、DevToolsActivePort、目标选择和恢复请使用共享的 sap-browser-automation
• OSE API（Q2 2026，v2025.20） — 完整的方法、参数和返回值文档：
  • references/ose-api-application-core.md — Application、PageBook、Panel、Popup、Widget（15 个类）
  • references/ose-api-widgets.md — Button、Dropdown、InputField、Slider、Switch、Text、TextArea（15 个类）
  • references/ose-api-datasource.md — DataSource、DataAction、DataBinding、DataLocking、DataChangeInsights（39 个类）
  • references/ose-api-chart-viz.md — Chart、Table、GeoMap、RVisualization、ValueDriverTree（20 个类）
  • references/ose-api-planning-calendar.md — Planning、PlanningModel 和所有 Calendar 类（54 个类）
  • references/ose-api-filtering-selection.md — FilterLine、FilterValue、Selection（11 个类）
  • references/ose-api-utilities.md — BookmarkSet、MemberInfo、DimensionInfo、Timer、NavigationUtils（37 个类）
  • references/ose-api-types-enums.md — 所有枚举类型：Feed、Layout、NumberFormat、VariableValue（70 个类）

模板（56 种模式）：

• templates/common-patterns.js - 40 种通用脚本模式
• templates/planning-operations.js - 16 种规划专用模式

官方文档

• Analytics Designer API：https://help.sap.com/doc/958d4c11261f42e992e8d01a4c0dde25/release/en-US/
• Optimized Story Experience API：https://help.sap.com/doc/1639cb9ccaa54b2592224df577abe822/release/en-US/
• SAC 文档：https://help.sap.com/docs/SAP_ANALYTICS_CLOUD
• Q4 2025 新增内容：https://help.sap.com/docs/SAP_ANALYTICS_CLOUD/00f68c2e08b941f081002fd3691d86a7/c96a267c5da04fff90bb55313ee9f77c.html

---

SAC 版本：Q2 2026 (2026.8) | API 版本：2025.20 (OSE Q2 2026)