原文地址: https://hartenfeller.dev/blog/teaching-ai-coding-assistants-apex # 如何利用 SKILL.md 文件教授 AI 编码助手使用 Oracle APEX  ## 小众技术面临的挑战 当要求 AI 创建网站时，它通常会选择 React 和 Tailwind CSS 这些开源、广泛使用且文档完善的技术。而 Oracle APEX 作为闭源、小众且公开代码较少的平台，AI 常常会虚构不存在的 API 包。因此我们需要通过上下文教导 AI 理解 APEX 的概念。 ## 通过上下文教导 APEX 这个问题可以通过提供适当的技术栈上下文来解决。关键在于平衡：上下文不足会导致 AI 虚构内容，过多则会造成性能下降。解决方案是采用检索增强生成（RAG）技术，仅提供与当前任务相关的信息。 新兴的 SKILL.md 规范可以方便地为编码助手提供临时上下文。例如我们可以创建专门针对 APEX 模板组件的 SKILL.md 文件： ```markdown --- name: template-component description: 为 Oracle APEX 应用创建模板组件 --- ## 输出文件 在 `src/template-components/<组件名称>/` 目录下创建： | 文件 | 必选 | 描述 | |----------------------|------|-----------------------------------------------------| | `partial.html` | 是 | 使用 `#COLUMN_NAME#` 替换渲染单行数据 | | `report-row.html` | 是 | 每行的包装器（默认：`<li #APEX$ROW_IDENTIFICATION#>#APEX$PARTIAL#</li>`） | | `report-body.html` | 是 | 所有行的包装器（默认：`<ul>#APEX$ROWS#</ul>`） | ## APEX 模板替换语法 **列值：** `#COLUMN_NAME#` → 替换为查询列值 **条件语句：** ```html {if IS_VISIBLE/}显示{else/}隐藏{endif/} ``` ## 用户输入要求 1. **组件名称**（kebab-case 格式，如 "employee-cards"） 2. **查询列**及类型（如 `EMP_ID NUMBER, NAME VARCHAR2`） 3. **视觉描述**组件布局 ``` ## 实现 APEX 风格化 虽然 AI 能生成优秀组件，但它们通常不具备 APEX 原生风格。为此需要额外创建 SKILL.md 文件来教授 APEX 的 CSS 变量和工具类： ```markdown --- name: apex-css-vars description: Oracle APEX CSS 自定义属性（变量） --- ## 可用 CSS 变量 ``` ut-palette-primary,主色调 ut-palette-primary-contrast,主色调对比色 ut-component-background-color,组件背景色 ``` 使用示例： ```css .my-component { background-color: var(--ut-component-background-color); } ``` ``` ## 图标搜索功能 对于图标系统，最佳实践是通过搜索而非浏览来定位所需图标。为此创建了专门的搜索工具和 SKILL.md 文件： ```markdown --- name: apex-icons description: 搜索 Oracle APEX 图标 --- 通过 CLI 搜索图标： ```bash apex-grep --type=icons --query=mail ``` ``` ## 总结 SKILL.md 文件是教授 AI 编码助手使用 Oracle APEX 等小众技术的有效方式。未来随着 APEXlang 的发布，这种基于文件的定义方式将更加重要。 相关工具已开源：https://github.com/United-Codes/uc-alfred-orclapex