ChenZeXian

ok-cosmic

"金蝶云苍穹开发主 Skill，优先复用 kd-cd-cosmic-commons 封装。适用于插件开发、单据/列表/表单逻辑、操作服务、BOTP 转换、后台视图打开、附件处理、DynamicObject 与元数据处理、弹性域解析及 OpenAPI 集成。默认优先使用仓库封装；在涉及原生插件事件、SDK API、方法签名或封装未覆盖场景时，使用内置脚本进行查询。"

ChenZeXian 11 3 Updated 3mo ago

Resources

10
GitHub

Install

npx skillscat add chenzexian/ok-cosmic

Install via the SkillsCat registry.

SKILL.md

苍穹开发

默认按"封装优先，原生兜底"工作，避免在仓库已封装的场景里退回到 BOS 原生低层 API。

最短决策路径

  1. 先判断插件类型或能力类别（查下方决策矩阵）。
  2. 先读对应 references/*.md，确认事件边界与适用场景。
  3. 再读对应 assets/*.java 模板，沿用已有方法签名和骨架。小场景可直接用 assets/snippets/*.java。
  4. 字段不确定先查 cosmic-form-metadata.py，SDK 签名不确定先查 cosmic-api-knowledge.py。
  5. 只有"插件类型 + 事件方法 + 字段/签名"都确认后，才开始生成代码。
  6. 代码生成后，必须执行 cosmic-post-lint.py 自动校验；若存在 ERROR 级问题须立即修复并重新校验直到通过。

快速决策矩阵

需求关键词 插件类型 封装文档 (先读) 原生文档 (兜底) 模板文件
表单 UI / 字段联动 / 控件交互 表单插件 plugin-base.md plugin-form.md FormPluginTemplate.java
单据 UI / 审核提交按钮 单据插件 plugin-base.md plugin-bill.md BillPlugInTemplate.java
列表 / 多选操作 / 批量 列表插件 plugin-base.md plugin-list.md ListPluginTemplate.java
左树右表（单据） 单据树列表插件（列表） plugin-base.md plugin-tree-list.md TreeListPluginTemplate.java
左树右表（基础资料） 基础资料树列表插件（列表） plugin-base.md plugin-tree-list.md StandardTreeListPluginTemplate.java
审核 / 保存 / 状态流转 / 校验 操作插件 operate-chain.md plugin-operation.md OpPluginTemplate.java
下推 / 选单 / 转换 转换插件 botp-convert.md plugin-botp.md ConvertPlugInTemplate.java
反写 / 关联更新 反写插件 botp-convert.md plugin-writeback.md WriteBackPlugInTemplate.java
报表 / 数据分析 报表插件 — plugin-report-form.md ReportFormPluginTemplate.java
报表取数 报表取数插件 — plugin-report-data.md ReportListDataPluginTemplate.java
打印 / 套打 打印插件 — plugin-print.md PrintPluginTemplate.java
OpenAPI / 外部集成 OpenAPI 控制器 — plugin-openapi.md OpenApiControllerTemplate.java
后台任务 / 定时 后台任务 — plugin-task.md TaskTemplate.java
工作流 / 审批流 工作流插件 — plugin-workflow.md IWorkflowPluginTemplate.java
导入 / 批量导入 导入插件 — plugin-import.md BatchImportPluginTemplate.java

能力封装路由（按需加载，只读相关的 1-2 个文档）

原生 SDK 兜底路由（仅在封装层不够用时）

子文件引用

以下文件提供详细规则，AI 应在需要时按需加载：

场景化代码片段 (snippets)

模板骨架给出完整插件结构，snippets 给出单个场景的最小可运行示例。遇到以下场景时，优先读对应 snippet 再写实现：

场景关键词 snippet 文件
字段取值/赋值/getValue/setValue GetAndSetValueSample.java
分录行计算/汇总/金额联动 EntryRowCalculateSample.java
确认框/二次确认/ConfirmCallBack ConfirmDialogSample.java
操作前拦截确认/beforeDoOperation BeforeOperationConfirmSample.java
F7 过滤/基础资料弹窗过滤 F7FilterSample.java
打开单据弹窗/showForm/Modal OpenBillModalSample.java
子页面回传数据/closedCallBack ReturnParentDataSample.java
树形控件/TreeView/树节点 TreeControlSample.java
列表插件基础/选中行/批量操作 ListPluginBasicSample.java
列表预打开过滤/setFilter ListPreOpenFilterSample.java
操作校验器/addValidators OpAddValidatorsSample.java
下推/选单/来源追踪/BotpUtils BotpTracePushSample.java
查询/聚合/DataSet/统计 DataSetQueryStatSample.java
基础资料查询/loadFromCache BaseDataQuerySample.java
DynamicObject 操作/安全取值 DynamicObjectOpsSample.java
附件上传/绑定/AttachmentUtils AttachmentUploadBindSample.java
消息通知/邮件/MessageService MessageNotifySample.java
后台调度任务/定时任务 ScheduleTaskSample.java

API 知识与元数据查询脚本

本 Skill 提供了两个核心 Python 脚本，用于查询苍穹 SDK API 和表单元数据。

A. 知识图谱查询脚本 (cosmic-api-knowledge.py)

用于模糊搜索类名、获取类方法签名、继承树与注释。

  • 用法: python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py [options] <command> [args]
  • 常用命令:
    • search <query...>: 模糊搜索类名。支持多关键词，默认任一关键词命中即可返回；加 --all 表示全部关键词都要命中。
    • search-method <query...>: 全局搜索方法名。支持多关键词，默认任一关键词命中即可返回；加 --all 表示全部关键词都要命中。结果会优先把与查询词更接近的方法排在前面，并展示方法说明摘要。
    • detail <classname>: 获取指定全限定类名的详细信息。
      • 可配合 --method <keyword> 只看相关方法。
      • 可配合 --declared-only 只看当前类声明的方法，不展开父类。
      • 可配合 --compact 输出紧凑事实块，减少 token 消耗，适合继续交给 AI 生成代码。
  • 定向过滤能力:
    • --class-prefix <prefix>: 按包前缀或类名前缀过滤，可重复传入多个前缀。
    • --class-regex <regex>: 按类全限定名正则过滤。
    • --kind <helper|servicehelper|plugin|service|utils|runtime|entity|const|enum|controller>: 按常见类别快速过滤。
  • 配置: 通过 --config <path/to/ok-cosmic.json> 指定配置文件(优先匹配当前运行项目的根目录)。

推荐用法（比裸搜更稳）

  • 查某个领域的 helper：
    python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json search Helper --class-prefix kd.bos.servicehelper --kind helper
  • 查某个包下的方法：
    python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json search-method send email --class-prefix kd.bos.servicehelper.message
  • 查插件相关类：
    python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json search plugin operation --kind plugin --all
  • 精确确认某个类有没有目标方法：
    python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json detail "类全限定名" --method "关键词"
  • 精确确认方法是否由当前类自己声明：
    python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json detail "类全限定名" --method "关键词" --declared-only
  • 当需要把方法事实继续喂给 AI 做后续生成时：
    python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json detail "类全限定名" --method "关键词" --compact

AI 调用约束

  • 允许直接传多个关键词，不要再把多个词错误地拆成多个"未知参数"。
  • 当第一次裸搜结果过宽时，第二次必须优先补 --class-prefix 或 --kind，不要连续无过滤地重复大范围搜索。
  • 搜 BOS/苍穹核心能力时，优先从这些包前缀收窄：
    • kd.bos.servicehelper
    • kd.bos.entity
    • kd.bos.form
    • kd.bd
    • kd.scm

定向搜索优先级

  1. 先定"领域"：
    • BOTP / 下推 / 转换
    • BaseData / 基础资料
    • Message / 邮件 / 消息
    • Form / UI / List / Plugin
  2. 再定"包前缀"：
    • BOS 通用服务优先 kd.bos.servicehelper
    • 插件事件优先 kd.bos.entity、kd.bos.form
    • 主数据优先 kd.bd
  3. 最后再用关键词：
    • 类搜索用 search
    • 方法搜索用 search-method
    • 类已知时直接 detail
  4. 需要确认 @Override 是否应写在当前类，而不是父类已有实现时：
    • 优先 detail "类全限定名" --method "关键词" --declared-only
  5. 需要把方法签名、参数说明、返回值作为低噪音事实块继续注入当前会话时：
    • 优先 detail "类全限定名" --method "关键词" --compact

B. 元数据查询脚本 (cosmic-form-metadata.py)

用于根据 formId 或 billName 获取单据元数据字段，支持字段模糊筛选。

  • 用法: python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py [options] get [args]
  • 参数:
    • --form-id: 表单英文标识。
    • --bill-name: 表单中文名称。
    • --fuzzy: 字段标识或名称的模糊匹配列表。[强制] 多个关键词必须用空格分隔（例如 --fuzzy qty price amount），支持正则表达式（如 --fuzzy "qty|price|amount"），严禁使用逗号分隔。
    • --show-detail: 详情模式开关。当存在模糊匹配结果时，显示枚举项映射 (extMap) 或基础资料引用类型 (refType)。
  • 配置: 通过 --config <path/to/ok-cosmic.json> 指定配置文件(优先匹配当前运行项目的根目录)。

AI 调用约束 (元数据查询)

  • 常规对齐: 仅确认字段标识时，不带 --show-detail。
  • 深度实现: 当需要编写 if 条件判断（针对枚举值）、手动赋值 或 基础资料关联查询 前，必须带上 --show-detail。
  • 严禁 SQL: 有了此参数后，严禁直接通过 SQL 查询 form_metadata_cache 表，必须通过脚本获取详情，以保证逻辑的一致性和可维护性。

常见实体/能力地图

下面这张"先找哪里"的地图，优先用于缩小搜索范围。

  • 操作插件 / 审核保存提交流程

    • 先看：kd.bos.entity.plugin.AbstractOperationServicePlugIn
    • 常看包：kd.bos.entity.plugin、kd.bos.entity.plugin.args
    • 常见帮助类：OpUtils、OperateChain、OperationServiceHelper

  • 表单 / 单据 / 列表 UI 插件

    • 先看：kd.bos.form.plugin.*
    • 常看包：kd.bos.form、kd.bos.form.control、kd.bos.list
    • 关键入口：this.getView()、this.getModel()

  • BOTP 下推 / 选单 / 转换

    • 先看：kd.cd.common.util.BotpUtils
    • 关键运行时参数：kd.bos.entity.botp.runtime.PushArgs、DrawArgs、ConvertOperationResult
    • 插件扩展：kd.bos.entity.botp.plugin.AbstractConvertPlugIn
    • 常见帮助类：kd.bos.servicehelper.botp.ConvertServiceHelper

  • 基础资料 / 管控策略 / 分配 / 个性化

    • 先看：kd.bos.servicehelper.basedata.BaseDataServiceHelper
    • 主数据扩展包优先：kd.bd.master.*
    • 若涉及分配/个性化：再看 AssignIndividuationHelper、相关 helper / mservice

  • 数据加载 / 保存 / 查询

    • 先看：kd.bos.servicehelper.BusinessDataServiceHelper
    • 查询类：kd.bos.servicehelper.QueryServiceHelper
    • 过滤条件：kd.bos.orm.query.QFilter

  • 消息 / 邮件 / 短信 / 企业微信

    • 先看：kd.bos.servicehelper.message.MessageServiceHelper
    • 邮件对象：kd.bos.message.api.EmailInfo
    • 其他消息对象通常也在 kd.bos.message.api

  • DynamicObject / 元数据 / 实体结构

    • 先看：kd.bos.dataentity.entity.DynamicObject
    • 元数据常见入口：EntityType、MainEntityType
    • 如果字段路径/主键不确定，优先回到元数据脚本和 entity-metadata.md

  • 附件 / 文件

    • 先看：AttachmentUtils
    • BOS 层常见类：AttachmentServiceHelper

  • 组织 / 权限 / 上下文

    • 先看：RequestContext、Permission 相关 service/helper
    • 碰到组织维度过滤时，优先确认 appId、使用组织、主业务组织分别来自哪里

代码生成后自动校验（Post-Lint）

[强制] 在生成或修改任何苍穹 Java 代码后，必须执行以下校验流程：

  1. 对生成的文件执行校验脚本：
    python3 <SKILL_ROOT>/scripts/cosmic-post-lint.py <生成的文件或目录> --fix-hint
  2. 若报告中存在 ERROR 级问题，必须立即修复后重新执行校验，直到 ERROR 为 0。
  3. 若仅存在 WARNING 级问题，应优先修复；若有合理理由可保留，须在代码注释中说明原因。
  4. INFO 级问题为建议项，按团队风格决定是否处理。

AI 调用约束 (Post-Lint)

  • 每次生成或修改 .java 文件后，自动触发 lint 校验，不需要用户手动请求。
  • 修复后必须再次执行脚本确认通过，形成"生成 → 校验 → 修复 → 复检"闭环。
  • 若单次修复后仍有 ERROR，最多重试 3 次；3 次后仍未通过，报告给用户并附带剩余问题清单。
  • 校验脚本不替代编译检查；通过 lint 后仍应确保代码可编译。

Categories

Agents Database
GitHub

Install

npx skillscat add chenzexian/ok-cosmic

Install via the SkillsCat registry.

Recommended Skills