Appearance

OMS Skills 使用指南 ​

📋 什么是 Skills？ ​

Skills 是 OMS 系统的唯一技术文档来源，既是 AI 的知识库，也是技术人员的开发指南。

Skills 的特点 ​

  • 双重用途：既是 AI 的知识库，也是技术人员的开发指南
  • 结构清晰：包含核心概念、代码示例、最佳实践
  • 完整内容：包含所有必要的技术信息，无需参考其他文档
  • 易于维护：单一文档来源，避免同步问题
  • AI 优化：包含 AI 专用的指令和指南，帮助 AI 更好地理解和协助开发

🚀 如何使用 Skills ​

在 Cursor 中使用 ​

  1. 自动识别：当你在 Cursor 中提问或请求帮助时，AI 会自动识别相关的 Skills
  2. 智能引用：AI 会根据你的问题，自动引用最相关的 Skills 知识
  3. 专业建议：基于 Skills 中的知识，AI 会提供更准确、更专业的开发建议

示例场景 ​

场景1：开发 Finder 列表

用户：如何开发一个订单列表页面？
AI：根据 oms-finder-development Skill，你需要...

场景2：创建定时任务

用户：如何创建一个每20分钟执行的定时任务？
AI：根据 oms-timer-task Skill，你需要...

场景3：数据库开发

用户：如何定义数据库表结构？
AI：根据 oms-database-development Skill，你需要...

📁 Skills 目录结构 ​

Skills 按层级分为两类：

框架级 Skills（framework/ 目录） ​

框架级Skills包含系统框架、开发规范、技术模板等，用于指导如何进行技术开发。

基础框架 ​

  • oms-app-structure.md - APP目录结构说明
  • oms-cache-mechanism.md - 缓存机制使用指南
  • oms-export-mechanism.md - 导出机制原理说明

开发规范 ​

  • oms-code-development.md - OMS代码开发规范
  • oms-app-development.md - APP开发标准模板
  • oms-database-development.md - 数据库开发完整指南
  • oms-finder-development.md - Finder列表开发指南
  • oms-dialog-development.md - Dialog对话框开发模板

数据处理 ​

  • oms-export-template.md - 数据导出模板
  • oms-import-template.md - 数据导入模板

接口集成 ​

  • oms-openapi-development.md - OpenAPI接口开发模板
  • oms-platform-integration.md - 平台对接标准模板

工具功能 ​

  • oms-image-upload.md - 图片上传完整指南
  • oms-timer-task.md - 定时任务创建指南
  • oms-translation.md - 多语言翻译标准模板
  • oms-phpunit-testing.md - PHPUnit测试用例编写规范

业务级 Skills（business/ 目录） ​

业务级Skills包含业务领域知识、业务流程、业务规则等，用于理解业务逻辑和业务需求。

  • oms-business-knowledge.md - OMS业务领域知识库（订单管理、库存管理、仓储管理等）

未来扩展：可以按业务模块进一步分类，如：

  • business/order/ - 订单管理相关Skills
  • business/inventory/ - 库存管理相关Skills
  • business/warehouse/ - 仓储管理相关Skills

OpenAPI接口Skills（openapi/ 目录） ​

OpenAPI接口Skills包含OpenAPI接口的使用指南，用于外部开发者调用OMS系统的开放API接口。

架构和使用 ​

  • oms-openapi-architecture.md - OpenAPI接口架构和使用指南（系统架构、请求流程、签名算法、响应格式、错误码、调用示例）

业务接口 ​

  • oms-openapi-orders.md - 订单管理API（订单列表查询、优惠券列表查询、支付方式列表查询）
  • oms-openapi-sales.md - 销售单管理API（销售单列表查询、销售金额统计、发货单列表查询）
  • oms-openapi-inventory.md - 库存管理API（库存列表查询、库存详情查询）
  • oms-openapi-delivery.md - 发货单管理API（物流单号列表查询、物流详情查询）
  • oms-openapi-po.md - 采购单管理API（采购单列表查询、采购单详情查询）
  • oms-openapi-aftersales.md - 售后单管理API（售后单列表查询、售后单详情查询）
  • oms-openapi-refunds.md - 退款单管理API（退款单列表查询、退款金额汇总）
  • oms-openapi-transfer.md - 出入库单管理API（出入库单列表查询、出入库单详情查询）
  • oms-openapi-stock.md - 库存查询API（商品库存查询、仓库库存查询、条形码库存查询）
  • oms-openapi-stockdump.md - 转储单管理API（转储单列表查询、转储单详情查询）
  • oms-openapi-workorder.md - 加工单管理API（加工单列表查询、加工单详情查询）
  • oms-openapi-appropriation.md - 调拨单管理API（调拨单列表查询、调拨单详情查询）
  • oms-openapi-purchasereturn.md - 采购退货单管理API（采购退货单列表查询、采购退货单详情查询）
  • oms-openapi-basicmaterial.md - 基础物料管理API（基础物料列表查询、基础物料详情查询）
  • oms-openapi-branch.md - 仓库管理API（仓库列表查询、仓库详情查询）
  • oms-openapi-brand.md - 品牌管理API（品牌列表查询、品牌详情查询）
  • oms-openapi-shop.md - 店铺管理API（店铺列表查询、店铺详情查询）
  • oms-openapi-supplier.md - 供应商管理API（供应商列表查询、供应商详情查询）
  • oms-openapi-member.md - 会员管理API（会员列表查询、会员详情查询）
  • oms-openapi-warehouse.md - 仓库转仓单管理API（转仓单创建、转仓单列表查询）
  • oms-openapi-finance.md - 财务账单API（账户余额查询、交易流水查询）
  • oms-openapi-ar.md - 应收应退单管理API（应收账款列表查询、应收账款详情查询）
  • oms-openapi-invoice.md - 发票管理API（发票列表查询、发票详情查询、发票更新）
  • oms-openapi-iostock.md - 出入库明细管理API（出入库明细列表查询、通过单据号查询出入库记录）
  • oms-openapi-salesmaterial.md - 销售物料管理API（销售物料列表查询、根据销售单号获取物料明细）

📝 Skills 文件格式要求 ​

标准格式 ​

每个 Skill 文件必须包含以下部分：

markdown
---
name: oms-{feature-description}
description: {简要描述，说明这个Skill的核心内容和用途}
---

# {Skill标题}

你是 {角色描述}，{专业领域说明}。

## 核心概念
{核心概念说明}

## 使用方法
{使用方法说明}

## 参考文档
- 其他相关 Skills：`oms-{related-skill}.md`

## Examples
{使用示例说明}

## Guidelines
{使用指南和注意事项}

必需部分 ​

  1. YAML Frontmatter

    • name: Skill 名称（必须）
    • description: Skill 描述（必须）

  2. 角色定义

    • 以"你是..."开头，定义 AI 的角色和专业领域

  3. 核心内容

    • 核心概念
    • 使用方法
    • 关键要点

  4. 参考链接

    • 指向原始技术文档的链接

  5. 使用指南

    • Examples：使用示例
    • Guidelines：使用规范和注意事项

🔤 Skills 命名规则 ​

文件命名规范 ​

格式：oms-{feature-description}.md

规则：

  • 必须以 oms- 开头（表示 OMS 系统）
  • 使用小写字母和连字符（kebab-case）
  • 描述要简洁明确，体现核心功能
  • 文件名与 Skill 名称（name）保持一致

示例：

  • ✅ oms-finder-development.md - Finder开发
  • ✅ oms-database-development.md - 数据库开发
  • ✅ oms-timer-task.md - 定时任务
  • ❌ finder-development.md - 缺少 oms- 前缀
  • ❌ oms_finder_development.md - 使用下划线而非连字符
  • ❌ oms-Finder-Development.md - 使用大写字母

Skill 名称（name）规范 ​

格式：oms-{feature-description}

规则：

  • 与文件名保持一致
  • 使用小写字母和连字符
  • 简洁明确，体现核心功能

示例：

yaml
---
name: oms-finder-development
description: OMS系统Finder列表开发完整指南
---

命名原则 ​

  1. 一致性：文件名、Skill 名称、描述要保持一致
  2. 简洁性：名称要简洁，避免过长
  3. 明确性：名称要明确表达 Skill 的核心功能
  4. 规范性：严格遵循命名格式，便于 AI 识别和管理

🔄 如何创建新的 Skills ​

步骤1：确定 Skill 主题 ​

确定需要创建的 Skill 主题，例如：新的开发模板、新的功能指南等

步骤2：收集和整理内容 ​

  • 收集核心概念和关键要点
  • 整理使用方法和配置步骤
  • 准备代码示例和最佳实践
  • 收集常见错误和注意事项

步骤3：结构化组织 ​

  • 按照 Skills 格式要求组织内容
  • 添加 YAML frontmatter（name 和 description）
  • 定义 AI 角色和专业领域（"你是..."部分）
  • 添加参考文档链接（指向其他相关 Skills）

步骤4：命名和保存 ​

  • 按照命名规范命名文件（oms-{feature-description}.md）
  • 保存到 600.skills/ 目录
  • 更新本 README.md 文件

步骤5：验证和测试 ​

  • 检查格式是否正确
  • 验证链接是否有效
  • 测试 AI 是否能正确识别和使用
  • 确认技术人员可以看懂和使用

📚 相关文档 ​

Skills 内部链接 ​

  • 框架级Skills：framework/ 目录
  • 业务级Skills：business/ 目录
  • OpenAPI接口Skills：openapi/ 目录

其他文档 ​

  • 核心模块设计：../400.design-desc/
  • API 接口文档：../erpapi/

⚠️ 注意事项 ​

  1. 内容完整：Skills 应该包含所有必要的技术信息，确保技术人员可以直接使用
  2. 结构清晰：保持结构清晰，包含核心概念、使用方法、代码示例、注意事项
  3. 格式规范：严格遵循 Skills 格式要求，确保 AI 能正确识别和使用
  4. 命名规范：严格遵循命名规则（oms-{feature-description}.md），保持一致性
  5. 参考链接：参考文档应该指向其他相关 Skills，形成知识网络
  6. 错误示例：重要功能应该包含错误示例对比，帮助避免常见错误

🤖 AI 生成 Skills ​

AI 可以自动生成新的 Skills：

  1. 分析需求和技术要求
  2. 提取核心概念和关键要点
  3. 按照 Skills 格式要求组织内容
  4. 遵循命名规范生成文件
  5. 自动更新 README.md

使用方法：向 AI 描述需要创建的 Skill 主题，AI 会自动生成符合规范的 Skill 文件。

最后更新：2025年
维护者：OMS 开发团队