cap-developer

我的工作内容

为 CAP 开发提供准确、精炼、符合惯用写法的指导——涵盖项目设置、CDS 建模、声明式注解和编程式事件处理程序。

此 SKILL.md 是一个路由器。每个主题都单独存放在自己的参考文件中，可独立加载和交叉引用。只阅读任务所需的文件。

参考文件索引

主题	文件	何时加载
领域模型 + 服务投影	references/cds-modeling.md	建模实体／方面／关联，或通过投影公开它们时
声明式注解（验证、约束、身份验证）	references/declarative.md	添加验证、必填／只读／计算值、@restrict／@requires 时
自定义事件处理程序	references/custom-logic.md	仅当注解无法表达规则时；处理 before／on／after 逻辑时
示例／种子数据	references/sample-data.md	使用 CLI 生成测试数据时
Node.js 运行时细节	references/nodejs.md	项目是 CAP Node.js 应用时
Java 运行时细节	references/java.md	项目是 CAP Java 应用时

运行时选择

在新项目中，使用全局安装的 @sap/cds-dk（CLI：cds）。 必要时再决定语言。 只有在添加代码或部署应用时，才需要做出此选择。

如果只处理 CDS 模型，可以直接从 cds w 开始，无需定义运行时。

文档来源

在猜测 API 或注解之前——以及修改现有项目的模型之前——请查阅权威的 CAP 文档。使用可用的来源；切勿猜测 URL 或杜撰 API：

• CAP MCP 服务（优先使用，若可用）。 用于：
  • 在猜测 API 或注解之前搜索 CAP 文档
  • 在添加或更改内容之前读取现有项目的有效 CDS 模型
• capire LLM 文档（未配置 MCP 服务时的备用来源）。 官方文档提供了便于 LLM 使用的入口——请使用这些入口，而不要进行临时网页搜索：
  • https://cap.cloud.sap/docs/llms.txt — 所有文档页面的精选索引；从这里开始查找合适的主题。
  • https://cap.cloud.sap/docs/llms-full.txt — 拼接在一个文件中的完整文档，需要完整文本时使用。
  • https://cap.cloud.sap/docs/sitemap.md — 所有页面的语义站点地图。
  • 在任意页面的 URL 后附加 .md（例如 https://cap.cloud.sap/docs/get-started/bookshop.md），或发送 Accept: text/markdown 标头，即可获取 Markdown 格式的页面。请从 llms.txt／sitemap.md 中的链接找到确切页面，而不要猜测路径。
  • 无需 MCP 服务，也可通过 cds compile <path> 检查有效 CDS 模型（例如 cds compile srv --to edmx）。

切勿将 CAP 文档用作 Fiori／SAPUI5 参考资料。它们包含 CAP 如何与 Fiori／SAPUI5 集成的实用信息，但并非这些框架的完整参考资料。

有关发行说明和版本表格的注意事项： 来自发行说明或版本推荐表格的文档可能已经过时——它们反映的是发行时的情况，不一定适用于当前。请务必通过 cds version、npm view 或当前的 Getting Started 页面等实时来源，交叉核对特定版本的说法（例如“推荐的 Node.js 版本”），不要轻信过去发行说明中的快照。

项目设置规则

使用以下命令创建新项目：

cds init <name>        # creates a subdirectory; omit <name> to init in cwd
cd <name>
cds watch              # start the dev loop (works without a runtime for pure modeling)

如果一开始就确定了运行时，请在 cds init 中传入 --java 或 --nodejs（详情请参阅针对运行时的参考文件）。

• 切勿运行 cds add sample——它会在项目中搭建完整的演示应用。
• 仅当用户明确需要最小化起始模型时，才使用 cds add tiny-sample。
• 使用 cds add <feature>（例如 hana、xsuaa、approuter、mta）逐步添加功能，并且仅在需要时添加（例如，用户要求部署时）。

工作顺序

1. 建模领域 → references/cds-modeling.md
2. 通过投影公开服务 → references/cds-modeling.md
3. 优先以声明方式添加约束 → references/declarative.md
4. 仅在注解无法满足需求时编写处理程序 → references/custom-logic.md （以及运行时文件 references/nodejs.md 或 references/java.md）
5. 生成示例数据 → references/sample-data.md

不要

• 为通用服务提供程序已能处理的事项编写处理程序
• 在任何地方硬编码租户 ID、系统 ID 或凭据
• 内联编写面向用户的字符串——请使用 _i18n/ 资源包
• 运行 cds add sample

运行时特定的禁忌（例如在 Node 中于 cds.on('served', ...) 内使用 await）见相应的参考文件。