笔者文中提及, 前一日所撰文章, 介绍了一处仓库, 此仓库之中, 维护着可借助Code以辅助进行SAP技术开发的部分。这部分所包括的哪些内容您没有写完全, 我先按已有内容尽力改写啦。

分享一个集合, 是专门用于 SAP 开发的, 属于 Code Skill 范畴。

文章之中, 我所运用的 Skill 里, 有一个名为 sap-cap- 的, 它能够用以辅助 SAP Cloud （CAP）的开发。

并非是将 SAP CAP 文档简单地塞给 Code 就算具备这个 skill, 相反, 是做了一套完整的工程化设计, 该设计涵盖从 MCP 协议集成, 有专业化 Agent 分工, 还包括代码验证 Hooks, 并且每一层都有着明确的设计意图。

本文就来拆解一下这个 skill 的技术架构和工作原理。

为什么需要一个专门的 CAP Skill？

笔者之前的文章已经对 SAP CAP 进行过详细介绍：

适用于 SAP Cloud 的 Model（CAP）, 属于那样一种是声明式的框架, 没错。

有着开发动作的人借助CDS（Core Data）去定义那种数据模型, 依靠CDL（CDS）来描述服务, 运用CQL（CDS Query）去编写查询呀。

能自动生成OData API 的框架, 会生成数据库, 还会生成Fiori UI 注解。

这套体系的好处是高度抽象，坏处是学习曲线陡峭。

倒不是说 CAP 技术有多艰深，有多难学。

而是用的人相对少，网上资料不多。

CDS的语法, 以及CAP的事件处理机制, 还有各个注解的含义, 均得查阅许许多多文档。

倘若把通用语言模型径直用于辅助能力获得与表现开发, 将会碰到若干问题:

第一个是上下文不足。

有几百个页面的CAP官方文档, 它包含CDS语法, 包含Node.js/Java API, 包含数据库配置, 包含部署指南, 包含安全机制, 包含多租户实现等内容。

通用大语言模型的那种知识截止的日期, 有可能是滞后的, 并且没办法在实时的状态下, 去获取项目当下的CDS模型结构。

第二个是专业性缺失。

CAP开发会涉及好些角色, 分别是, CDS建模, 还有服务实现, 以及性能优化, 再就是部署配置。

每个角色需要不同的知识深度和工具链。

通用 AI 很难针对具体场景给出最佳实践。

第三个是代码质量保证。

CAP项目的代码质量, 不光取决于语法是否正确, 还得要符合框架的设计模式, 像是要正确进行使用, 要避免出现N + 1查询, 要遵循OData规范。

这些都需要在代码生成后进行验证。

有一个名为, sap - cap - 的Skill, 是专门为处理, 这些问题而构想出的设计。

Skill 整体架构：四层设计

这个 skill 的目录结构很清晰：

从这个结构可以看出，设计者把 skill 分成了四层：

用于作对接外部服务的协议层（层）, 是那.mcp.json以及.lsp.json。

智能层, 其一和, 其二，提供专业化AI能力。

验证层（ Layer） ： hooks/ ，保证代码质量。

知识层面, 也就是 /sap-cap-/ , 它用于存储文档以及模板。

下面咱们来逐层分析。

协议层面, 有着 MCP 加、LSP 加这种双重的助力支撑呢, 而 MCP 的集成方面, 能够做到实时地去访问项目模型。

.mcp.json 配置了 CAP 官方的 MCP ：

{
"sap-cap-capire":{
"command":"npx",
"args":["-y","@cap-js/mcp-server"],
"env":{}
}
}

这样的配置开启了, @cap-js/mcp-包, 它属于SAP官方所给出的Model服务器。

MCP（Model）乃是被推出的某种协议, 此协议能够使得LLM借助标准接口去访问外部数据源。

CAP MCP 暴露了两个核心工具：

：搜索编译后的 CSN（Core ）模型。

存储网络文件系统是内容分发服务模型, 经过编译之后的, 以贾森格式呈现的表达形式, 其当中涵盖了全部的实体定义, 还有服务定义, 并附带关联关系以及注解信息。

通过 ， Code 可以完成下面的操作：

比如用户问："Books 实体有哪些关联？"

Code无需去读取那.cds 文件, 直接开展调用, 借助(query="Books", type="")这般的形式, 便能够获取Books的完整定义, 此定义涵盖了诸如genre等的关联项目, 还有额外的一些关联。

：语义搜索 CAP 文档。

此工具借助向量嵌入, 对CAP官方文档予以预处理, 其支持语义搜索, 并非依赖关键词匹配。

比方说, 用户进行询问, 怎样于 Node.js 里, 去注册一个钩子呢?

当 AI 予以调用 的时候 , （此处查询内容为一段有一定间隔的空白字符即“query=""”）, 能够返回与之相关联的 API 所对应的文档 , 以及代码示例。

这两个工具的关键设计在于 本地化 和 零配置 。

MCP 完全于本地运行, 无需任何环境变量, 无需 API Key, 且不依赖外部服务。

被读取的那个, 是项目经过编译之后所生成的、处于本地的 CSN 文件, 所采用的呢, 是预先进行缓存的文档向量。

这意味着离线环境也能用，而且响应速度极快。

LSP 集成：实时语法检查

.lsp.json 配置了 CDS ：

{
"cds":{
"command":"cds-lsp",
"args":["--stdio"],
"extensionToLanguage":{
".cds":"cds"
}
}
}

cds-lsp, 它属于 SAP 官方所提供的用于 CDS 的语言服务器, 其具备语法高亮功能, 还拥有自动补全功能, 又能进行错误检查, 并且能够实现跳转定义等 IDE 功能。

在集成了 LSP 之后, 当 Code 进行生成或者修改 .cds 文件的时候, 它能够及时地获取到语法方面的错误以及警告。

比如 AI 生成了这样的代码：

entity Books {
title : String(111);
author : Association to Author; // 错误：Author 不存在
}

“LSP”, 会马上返回错误信息, 即“'' not found”。

AI 收到错误后，会自动修正为 （注意复数形式）。

这种实时反馈机制大大减少了生成代码的错误率。

智能层：专业化 Agent 分工协作

该skill出彩的部分在于, 有着四个专业化的Agent被设计出来, 这是它最精彩之处。

每个Agent都和CAP开发里的一个角色相对应, 它具备各异的工具权限, 还具有不一样的知识范围。

它们的源代码在 目录下可以找到。

Agent 1: cap-cds-（数据建模专家）

职责 ：定义 CDS 实体、设计数据模型、配置关联关系。

可用工具 ：

典型场景 ：用户说"创建一个 实体，关联到 "。

工作流程：

调用 (query="") ，确认 实体存在

调用 (query=" CDS") ，查找关联语法

生成代码：

entity Products : cuid, managed {
name : String(111) not ;
price : Decimal(9,2);
category : Association to Categories;
}

这个 Agent 的设计哲学是 先查询再生成 。

它并非会没缘由地去创建那并不存在的实体引用, 而是首先借着某种方式去证实目标实体是存在着的, 之后又凭借另外的方式去寻觅那正确的语法。

Agent 2: cap--（服务开发专家）

职责是, 定义CDS服务, 要去实现事件处理器, 还要编写CQL查询。

可用工具 ：

典型场景 ：用户说"给 实体添加一个 的自定义 "。

工作流程：

调用 (query="") ，了解实体结构

调用 (query=" CDS") ，查找 语法

生成服务定义（ .cds ）：

service OrderService {
entity Orders as projection on my.Orders;

action submitOrder(order: Orders:ID, quantity: Integer) returns String;
}

调用 (query=" ") ，查找处理器 API

生成处理器代码（ .js ）：

module.exports = classOrderServiceextendscds.ApplicationService {
init {
this.on('submitOrder', async (req) => {
const { order, quantity } = req.data;
// 业务逻辑
return { success: true };
});
return super.init;
}
}

这个 Agent 的特点是 跨文件协作 。

它不单单生成CDS定义, 又能够生成与之对应的, / 处理器代码, 并且确保这两者在接口方面的一致性。

Agent 3: cap--（项目架构师）

职责 ：初始化项目、配置部署、设置多租户、配置认证。

可用工具 ：

典型场景 ：用户说"配置 Cloud 部署"。

工作流程：

使用 (查询条件="Cloud MTA") , 去寻觅部署指南所指示的准则, 来进行查找 , 以获取相关内容。

生成 mta.yaml （MTA 部署描述符）

生成 xs-.json （XSUAA 安全配置）

更新 .json 中的 CAP 配置

这个 Agent 的价值在于 全栈配置 。

它不但晓得怎样去编写代码, 而且还清楚怎样去配置数据库, 以及认证服务, 再者是负载均衡, 另外还有日志系统。

Agent 4: cap--（性能调优专家）

职责 ：分析查询性能、优化关联查询、排查 N+1 问题。

可用工具 ：

典型场景 ：用户说"为什么这个查询很慢？"

工作流程：

分析查询代码，发现 N+1 问题（循环中查询关联实体）

实施调用操作, 该操作的具体内容为(query="query N+1 CAP") , 通过此操作去查找优化方案。

建议使用 CQN 的 参数批量加载关联数据

这四个Agent的设计, 依照了单一职责原则, （）。

每一个 Agent 仅负责一个领域, 不过, 可借助 Code 的 Agent 协作机制, 彼此进行调用。

比如说 cap, 当进行生成服务这个操作的时候, 会把确认实体定义是否正确这件事委托给 cap-cds- 去做。

验证层：Pre/Post Hooks 保证代码质量

这是最容易被忽视但非常重要的设计。

hooks/hooks.json 配置了代码验证钩子：

{
"hooks":{
"PreToolUse":[{
"matcher":"Write|Edit",
"hooks":[{
"type":"command",
"command":"./hooks/dispatch.sh",
"timeout":30
}]
}],
"PostToolUse":[{
"matcher":"Write|Edit",
"hooks":[{
"type":"command",
"command":"./hooks/dispatch.sh",
"timeout":15
}]
}]
}
}

这个配置的意思是：

先使得.sh这个脚本进行执行, 在Code执行Write工具或者Edit工具以前。

Code执行Write工具或Edit工具之后, 再去运行, 一次.sh脚本。

. sh 属于一个调度脚本, 此脚本会依照当时的环境状况, 来调用 Node.js 或者特定版本的验证器。

if command -v node >/dev/ 2>&1; then
printf'%s'"$INPUT_PAYLOAD" | node "$SCRIPT_DIR/validator.mjs"
elif command -v python3 >/dev/ 2>&1; then
printf'%s'"$INPUT_PAYLOAD" | python3 "$SCRIPT_DIR/validator.py"
fi

验证器（ .py 或 .mjs ）会检查：

1. 确保所进行的修改, 是针对 CAP,项目,文件, 也就是, .cds,, .json,, mta.yaml,等等这些类型的文件, 要达成文件类型匹配其要求。

2. 语法特征匹配, 去检查代码之中, 是不是包含CAP关键字, 像to、of等。

3. 最佳实践检查 ：

若出现验证失败的情况, Hook便会返回错误信息, Code会对这次操作进行阻止, 并且还会提示Code去作出修正。

这套挂钩机制处理掉了一项关键问题, 人工智能创编编成的代码未必契合框架的最优做法。

在 Code 操作之前以及之后, 借助 Pre/Post Hook, 我们增添了两道质量关卡, 以此保证所生成的代码, 不仅在语法方面是正确的, 而且还在设计模式上契合 CAP。

知识层：22 个参考文档 + 8 个模板

位于 /sap-cap-// 这个目录之中, 存在着 22 个用于参考的文档, 这些文档加起来总共超越了 1 万行。

这些文档并非单纯对 SAP 官方文档所作的那种复制, 而是经由精心予以整理的, 属于结构化的知识。

比如说, 有一个名为 -.md 的文件, 其行数为 432 行, 专门针对 Fiori UI 注解进行讲解。

每个注解都有完整的语法说明和代码示例。

再比如

名为event--.md 的文件, 行数有611行, 它对事件处理器的常见模式进行了总结。

这些文档是 Agent 调用 时的主要知识来源。

目录之下存在着 8 个, 那些作为代码适用的模仿样式, 并且将 CAP 项目里具有代表性的文件都包含了进去。

这些模板是 Agent 生成代码时的参考范例。

比如, 进行创建这么一个新起的尚未有过的服务时, cap, 它会先去读取那个有着特定格式的 -.cds 样式的模板, 并随后依据用户所提出的需求去做出相应的调整。

：交互式向导

这个skill中, 除了Agent, 另外还提供了5个交互式命令, 是这样的情况 , 没错吧。

cap - setup - , 这是项目初始化向导, 它能引导用户去选择框架, 框架可在Node.js、Java中任选, 还能去选择数据库，数据库可选/HANA/。

cap - , 这是一种故障排查工具, 它能够针对常见错误展开分析 , 诸如CDS编译错误。而OData错误同样是其要探究的内容。还有HANA这一类型的部署错误它也会去予以剖析。

围绕cap - mcp - tools展开, 是关于MCP工具的使用指南, 其目的在于教导用户怎样去进行手动调用, 以及另外的某个方面。

cap-cds- ：CDS 语法快速参考。

cap-- ：部署前检查清单。

这些 和 Agent 的区别在于交互方式。

Agent并非主动引导用户去完成特定任务, 而是被动地响应用户请求。

要是用户不清楚该怎样去做初始化项目这一操作, 可以直接去运行那个 /cap - setup - , 而向导它, 是会按照一步步要求去询问相关需求的, 最终就会形成完整的初始化命令。

工作原理：一个完整的请求流程

当下, 我们将各个组件串联到一起，去瞧瞧一个完整的开发请求是怎样被处理的。

场面: 使用者讲“咱要给Books这个实体增添一套评分体系, 涵盖评分以及评论”。

步骤1: 将代码路由所针对的请求转到资本连续数据服务代理那里。

步骤二: 智能体进行调用, 调用内容为（查询语句="Books", 类型=""）, 以此查询Books实体的当下定义。

返回结果：

{
"entity":"Books",
"fields":["ID","title","author_ID","stock","price"],
"associations":["author"]
}

步骤3, 代理调用了, 里边查询是“of many CDS” , 以查找怎么样去定义一对多的关系。标点符号就用逗号, 确保句末有标点符号。

返回文档片段：

entity Parent {
children : Composition of many Child on children.parent = $self;
}

步骤4: 智能体设计全新的实体构成形式, 预备去生成代码。

步骤5, 引发Hook事件, 验证装置核查即将被生成的代码是不是契合规范要求。

步骤6, 验证得以通过, Agent去调用Write工具, 进而生成全新的CDS代码:

entity Books : cuid, managed {
// 原有字段...
reviews : Composition of many Reviews on reviews.book = $self;
}

entity Reviews : cuid, managed {
book : Association to Books;
rating : Integer;
comment : String(1000);
}

Step 7 ：触发 Hook，验证器检查生成的代码：

Step 8 ：验证通过，代码写入文件。

步骤九, 智能体向用户提议开展cds watch去测试全新模型。

全过程里, AI开启了2次MCP工具调用（ +）, 2次Hook校核, 终于产出了契合SAP CAP最优举措的代码。

设计哲学：可组合性与可验证性

回顾整个 skill 的设计，我们可以总结出两个核心理念：

可组合性（）

协议层是独立的模块, 智能层是独立的模块, 验证层是独立的模块, 知识层是独立的模块, 它们可以单独升级, 可以单独替换。

例如, 在未来, 当 CAP 推出新版本的 MCP 之后, 我们仅仅只需要去更新那个 .mcp.json 配置就行, 然而这并不会对其他的层产生任何影响。

拥有四个独立设 Agent, 它们既能被单独调用, 又能够进行组合使用。

可验证性（）

利用LSP实时开展语法错误检查, 借助Hook对最佳实践予以验证, 凭借MCP去访问权威的模型定义。

每一步生成的代码都有验证机制，确保质量。

这两点对企业级开发尤其重要。

就企业而言, 其不能接纳那或许正确之代码, 且势必有明晰的质量保证相关的机制存在了。

小结

sap - cap - 这项技能, 展现出怎样去为特定的技术栈, 设计一个具备工程化特质的 Code 辅助系统。

它不是把文档塞给 Code 让它自己理解，而是：

这套设计思路, 并非仅仅适用于CAP, 它能够被迁移至其他企业级框架, 像是Boot, 还有Rails等等。

关键是理解 AI 的能力边界，并通过工程化手段补齐短板。

AI 擅长生成代码，但不擅长保证质量。

AI 能理解通用语法，但不一定了解框架的最佳实践。

AI 可以搜索文档，但未必能实时获取项目的当前状态。

经过协议集成的设计, 借助专业分工来开展, 再加上质量验证这一环节, 如此这般, 我们能够促使AI切实成为企业级开发里可资信赖的有力辅助。

众人于阅读完此文以后, 能够依照文章那分析的思路, 自行前往 sap - cap - 所处的代码仓库的别的文件夹, 去查看自身更为感兴趣的Skill实现。