跳到主要内容

技能包管理模块与生成器 Skill 设计

· 阅读需 8 分钟
Quany
Quany
软件工程师

日期：2025-02-09
状态：已确认

第一节：目标与范围​

目标

  • 系统侧：在现有芋道后台中增加「技能包」管理能力，运营/管理员可创建、编辑、发布技能包（业务数据落库，供 AI Agent 或其它业务消费）。
  • 开发侧：在 Cursor 中提供一个「创建技能包（管理模块）」的 skill，能像 biz-crud-create-page 一样一键生成「技能包」的整条管理链路（表结构 + 字典 + 菜单 + 后端 CRUD + 前端列表/表单/详情），并遵循项目既有规范。

范围

  • 技能包在系统内视为一种业务实体：有名称、编码、描述、状态（草稿/已发布等）、版本、所属分类等可配置字段；具体字段在第二节数据模型中确定。
  • 管理能力：列表（含筛选）、新增、编辑、删除、发布/下架；详情页可展示包内「技能」列表或配置摘要（首期做简单列表，复杂编排可后期扩展）。
  • 生成器 skill：只负责生成「技能包管理」这条 CRUD 链路（含一个技能包表及必要字典/菜单），不生成「包内单个 skill 的 SKILL.md 文件」；若以后需要「从管理页导出为 Cursor skill 目录」，再单独做导出功能。
  • 消费方式本期只做数据就绪：表与 API 先有，供前端或内部调用；若已有或计划有 Agent 服务，可直接读同一套 API。

不包含（YAGNI）

  • 包内技能的在线编辑器、版本 diff、审批流、多租户隔离（除非现有项目已强依赖租户）。
  • 技能包市场、分享、权限到「包内单条技能」的细粒度控制。

成功标准

  • 用 skill 生成一遍后，能在后台看到技能包菜单，完成列表/增删改/发布状态切换。
  • 生成物符合现有数据库、后端、前端规则（与 lead/source 或 lead/personal 风格一致）。

第二节：数据模型与字典​

主表 ai_skill_package

  • 与现有规范一致：主键 id（雪花）、creator/create_time/updater/update_time/deleted、tenant_id（多租户）。
  • 业务字段：name（名称）、code（编码，租户内唯一，用于 API/导出）、description（描述，VARCHAR(500) 或 TEXT）、status（状态，见下）、sort（排序，INT 默认 0）、content（TEXT，可选，存包内技能摘要或 JSON，后续可扩展）。
  • 索引：uk_ai_skill_package_code_tenant (code, tenant_id, deleted)，idx_ai_skill_package_status (status)，idx_ai_skill_package_sort (sort)。

字典

  • skill_package_status：草稿（DRAFT）、已发布（PUBLISHED）、已下架（OFFLINE）。列表筛选、详情、发布/下架操作均用该字典。
  • （可选）skill_package_category：如「业务生成」「Agent 技能」等，便于后续分类筛选；若首期不做分类，可不建该字典。

包内技能（首期从简）

  • 不单独建「技能项」表，用主表 content 存一段文本或 JSON 即可（例如技能名称列表 + 简要说明），详情页只读展示。若后续需要逐条增删改「包内技能」，再增加 ai_skill_package_item 表与前后端。

菜单与权限

  • 一级菜单（示例）：「AI 技能」或放在现有某父级下，path 如 /ai/skill-package。
  • 二级：技能包管理，permission 前缀 ai:skill-package:query/create/update/delete，并可加 ai:skill-package:publish 控制发布/下架。

第三节：后端与前端实现要点​

后端

  • 模块：放在现有 yudao-module-ai，若当前只有 pom，则在该模块下按规范建包：controller.admin、dal.dataobject.skill、dal.mysql.skill、service.skill、convert.skill、controller.admin.vo.skill（PageReqVO/RespVO/SaveReqVO，按需 SimpleRespVO）。
  • 接口约定：Base URL /admin-api/ai/skill-package。提供：分页查询 getPage、详情 get、新增 create、修改 update、删除 delete、发布 publish、下架 offline。权限标识：ai:skill-package:query/create/update/delete，发布/下架可用 ai:skill-package:publish 或复用 update。
  • 实现要点：DO 继承 TenantBaseDO，表名 ai_skill_package。发布/下架即把 status 置为 PUBLISHED/OFFLINE 并做幂等与状态校验（如仅草稿可发布、仅已发布可下架）。错误码在 yudao-module-ai 的 ErrorCodeConstants 中新增，Controller 用 @PreAuthorize 与现有风格一致。

前端

  • 路由：在 router/routes/modules 下新增 ai.ts（或并入已有 AI 路由），path 如 /ai/skill-package，组件 ai/skill-package/index；列表、新增/编辑、详情对应同一模块下的 index、create、edit、detail。
  • 列表页：Page + useVbenVxeGrid，查询项：名称（Input）、编码（Input）、状态（Select，DICT_TYPE.skill_package_status）。表格列：名称、编码、状态（CellDict）、排序、更新时间、操作（编辑/删除/发布/下架，按状态显隐）。API 与后端分页约定一致（pageNo、pageSize、表单条件、排序）。
  • 表单（新增/编辑）：名称、编码、描述、排序、状态（草稿时可选）、content（可选，Textarea）。编码新增时必填，编辑时只读或禁用。校验：编码格式、名称非空。
  • 详情页：只读展示上述字段；若有 content，以只读区块或简单 JSON/文本展示「包内技能」摘要。
  • 发布/下架：列表操作列按钮，调用 publish/offline 接口后刷新列表；可加二次确认（如「确认发布？」）。

与现有风格对齐

  • 后端 VO 命名、分页参数、统一返回与 CRM 模块一致；前端 data.ts 中 formSchema/columns、TableAction、权限 ai:skill-package:xxx、i18n key 前缀统一（如 ai.skillPackage.xxx）。组件与数据源遵守 .cursor/skills/biz-crud-create-page/component-data-mapping.md（本业务若无特殊下拉可仅用字典）。

第四节：生成器 Skill 设计​

定位与触发

  • 新建项目内 skill：.cursor/skills/create-skill-package-module/，内含 SKILL.md。触发场景：用户说「生成技能包管理模块」「创建技能包管理页」「按 createPage 风格做技能包」等时，Agent 优先使用该 skill。
  • 与 biz-crud-create-page 的关系：不替代，复用其规则与参考。本 skill 只针对「技能包」这一固定业务，产出表名、实体名、模块名、菜单/权限前缀、字典类型等均写死在 skill 内，无需用户再走「查询项→表格→功能清单」多步交互；若以后要支持「自定义实体名的技能包」，再考虑引入类似 create-page 的交互。

生成顺序（与 create-page 一致，严禁颠倒）

  1. SQL：sql/mysql/ 下新增 ai_skill_package.sql（建表）、ai_skill_package_dict.sql（skill_package_status 等字典，幂等）、ai_skill_package_menu.sql（AI 技能 / 技能包管理菜单及 ai:skill-package:query 等按钮权限，含 role_id=1 的 system_role_menu）。
  2. 后端：在 yudao-module-ai 中生成 DO（TenantBaseDO）→ Mapper → Service 接口与 Impl → Controller（/admin-api/ai/skill-package）→ VO（PageReqVO、RespVO、SaveReqVO）；ErrorCodeConstants 中新增错误码；发布/下架在 Service 内做状态流转与校验。
  3. 前端：router/routes/modules/ai.ts 中注册列表与 detail/create/edit 路由；views/ai/skill-package/ 下 index.vue、data.ts、create.vue、edit.vue、detail.vue（弹窗 CRUD 则用 modules/form.vue）；api/ai/skill-package/index.ts；i18n 键与菜单名称一致。

Skill 文档必须写清的内容

  • 本模块固定参数表：表名 ai_skill_package、模块名 ai、实体名 skillPackage（前端）、权限前缀 ai:skill-package、字典类型 skill_package_status、参考实现路径（可与本设计文档互相引用）。
  • 必读规则：.cursor/rules/backend/database.mdc、backend-project-structure.mdc、.cursor/rules/frontend/biz-crud-page-standard.mdc；参考实现指向「技能包」生成后的代码或现有 lead/source 的目录结构说明。
  • 生成后校验：要求执行 node .cursor/skills/biz-crud-create-page/scripts/validate-page.mjs ai skill_package --backend（若 validate-page 支持 ai 模块）；或在本 skill 下提供专用 validate-skill-package.mjs，检查 SQL、菜单、路由、views、API、后端 DO/Controller 是否存在且符合约定。

可选

  • 本 skill 的 reference.md 中列出「技能包管理」字段与接口清单，便于 Agent 一次生成完整；scripts/ 下仅保留校验脚本，不提供通用代码生成引擎。

第五节：错误处理与验收​

错误处理

  • 后端：编码重复返回 400 及明确错误码；发布/下架状态不合法（如对已下架再下架）返回 400 并提示当前状态；删除前可做关联校验（若未来有包内技能表则先判空）。
  • 前端：接口失败用项目统一提示；列表加载失败可重试或空状态提示。
  • 生成器：校验脚本以非 0 退出并打印缺失项（如「缺少 ai_skill_package_menu.sql」），Agent 按提示补全后重新运行直至通过。

验收标准

  • 执行 skill 生成一遍后：执行 SQL、启动后端与前端，能在「AI 技能」下看到「技能包管理」，完成列表筛选、新增、编辑、删除、发布、下架、详情查看；数据落库且状态正确。
  • 生成代码通过项目既有 Lint/编译；菜单与权限与设计一致。