FreePublished on GitHub

ok-cosmic

金蝶云苍穹开发主 Skill，优先复用 kd-cd-cosmic-commons 封装。适用于插件开发、单据/列表/表单逻辑、操作服务、BOTP 转换、后台视图打开、附件处理、DynamicObject 与元数据处理、弹性域解析及 OpenAPI 集成。

默认优先使用仓库封装；在涉及原生插件事件、SDK API、方法签名或封装未覆盖场景时，使用内置脚本进行查询。

The English summary is being prepared. Showing the original description.

ChenZeXian/ok-cosmic

See how to install

Files included (110)

SKILL.md18.1 KB
.gitignore58 B
agents/openai.yaml871 B
assets/BatchImportPluginTemplate.java3.4 KB
assets/BillPlugInTemplate.java5.1 KB
assets/ConvertPlugInTemplate.java9.9 KB
assets/FormPluginTemplate.java20.6 KB
assets/IWorkflowPluginTemplate.java3.7 KB
assets/ListPluginTemplate.java6.6 KB
assets/OpenApiControllerTemplate.java3.6 KB
assets/OpPluginTemplate.java7.6 KB
assets/PrintPluginTemplate.java3.4 KB
assets/ReportFormPluginTemplate.java9.2 KB
assets/ReportListDataPluginTemplate.java2.6 KB
assets/snippets/attachment/AttachmentUploadBindSample.java3.2 KB
assets/snippets/botp/BotpTracePushSample.java6.0 KB
assets/snippets/data/DynamicObjectOpsSample.java3.0 KB
assets/snippets/form/BeforeOperationConfirmSample.java5.6 KB
assets/snippets/form/ConfirmDialogSample.java4.5 KB
assets/snippets/form/EntryRowCalculateSample.java2.3 KB
assets/snippets/form/F7FilterSample.java3.3 KB
assets/snippets/form/GetAndSetValueSample.java3.8 KB
assets/snippets/form/OpenBillModalSample.java7.3 KB
assets/snippets/form/ReturnParentDataSample.java3.0 KB
assets/snippets/form/TreeControlSample.java4.6 KB
assets/snippets/list/ListPluginBasicSample.java4.5 KB
assets/snippets/list/ListPreOpenFilterSample.java2.4 KB
assets/snippets/message/MessageNotifySample.java3.3 KB
assets/snippets/operation/OpAddValidatorsSample.java4.2 KB
assets/snippets/package-info.java1002 B
assets/snippets/query/BaseDataQuerySample.java7.7 KB
assets/snippets/query/DataSetQueryStatSample.java4.9 KB
assets/snippets/task/ScheduleTaskSample.java2.9 KB
assets/StandardTreeListPluginTemplate.java4.5 KB
assets/TaskTemplate.java2.8 KB
assets/TreeListPluginTemplate.java5.0 KB
assets/WriteBackPlugInTemplate.java8.7 KB
CHANGELOG.md5.5 KB
LICENSE11.1 KB
manifest.json2.2 KB
mcp/mac注册示例（可选）.png470.2 KB
mcp/mcp_bill_metadata_server.py3.9 KB
mcp/requirements.txt130 B
README.md11.2 KB
references/adv/attachment-api.md5.3 KB
references/adv/botp-convert.md4.8 KB
references/adv/dynamic-object.md5.7 KB
references/adv/entity-metadata.md5.9 KB
references/adv/flex-prop.md4.6 KB
references/adv/form-utils.md5.2 KB
references/adv/operate-chain.md6.9 KB
references/adv/plugin-base.md8.8 KB
references/adv/query-dataset.md7.3 KB
references/adv/request-context.md3.6 KB
references/adv/view-handler.md5.8 KB
references/base/plugin/plugin-bill.md2.7 KB
references/base/plugin/plugin-botp.md3.2 KB
references/base/plugin/plugin-form.md5.7 KB
references/base/plugin/plugin-import.md2.3 KB
references/base/plugin/plugin-list.md7.2 KB
references/base/plugin/plugin-openapi.md3.9 KB
references/base/plugin/plugin-operation.md5.3 KB
references/base/plugin/plugin-print.md2.0 KB
references/base/plugin/plugin-report-data.md2.0 KB
references/base/plugin/plugin-report-form.md3.3 KB
references/base/plugin/plugin-task.md2.0 KB
references/base/plugin/plugin-tree-list.md2.9 KB
references/base/plugin/plugin-workflow.md2.7 KB
references/base/plugin/plugin-writeback.md2.9 KB
references/base/sdk/sdk-algo.md3.1 KB
references/base/sdk/sdk-cache.md2.5 KB
references/base/sdk/sdk-dynamic-model-svc.md4.2 KB
references/base/sdk/sdk-dynamic-object.md2.9 KB
references/base/sdk/sdk-entity-model.md2.8 KB
references/base/sdk/sdk-exception.md3.0 KB
references/base/sdk/sdk-file.md2.7 KB
references/base/sdk/sdk-id.md2.0 KB
references/base/sdk/sdk-lock.md2.5 KB
references/base/sdk/sdk-log.md2.3 KB
references/base/sdk/sdk-network-control.md2.9 KB
references/base/sdk/sdk-orm-access.md2.8 KB
references/base/sdk/sdk-request-context.md2.5 KB
references/base/sdk/sdk-threadpool.md2.7 KB
references/base/sdk/sdk-tx.md2.6 KB
references/base/sdk/sdk-utils.md2.9 KB
rules/anti-patterns.md3.0 KB
rules/cheat-sheet.md4.7 KB
rules/coding-preferences.md3.3 KB
rules/constraints.md1.3 KB
rules/plugin-dev-flow.md3.4 KB
rules/post-lint.md1.9 KB
rules/workflow.md962 B
scripts/config_loader.py2.8 KB
scripts/cosmic-api-knowledge.py34.9 KB
scripts/cosmic-form-metadata.py21.3 KB
scripts/cosmic-post-lint.py8.6 KB
scripts/lint/base.py3.1 KB
scripts/lint/hal_check.py4.5 KB
scripts/lint/resource_check.py1.8 KB
scripts/lint/scene_check.py4.3 KB
scripts/lint/style_check.py3.0 KB
scripts/lint/verify_check.py1.3 KB
setup/cuslib/kd-cd-cosmic-commons.jar249.2 KB
setup/cuslib/kd-cd-cosmic-features.jar127.1 KB
setup/ok-cosmic-docs.db9.1 MB
setup/ok-cosmic.json214 B
setup/setup-mac.sh452 B
setup/setup-windows.bat1.2 KB
setup/setup.jar3.1 MB
WORKFLOW.html6.5 KB

SKILL.md (original)

Review the instructions the agent will receive before you install.

苍穹开发

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

最短决策路径

先判断插件类型或能力类别（查下方决策矩阵）。
先读对应 references/*.md，确认事件边界与适用场景。
再读对应 assets/*.java 模板，沿用已有方法签名和骨架。小场景可直接用 assets/snippets/*.java。
字段不确定先查 cosmic-form-metadata.py，SDK 签名不确定先查 cosmic-api-knowledge.py。
只有"插件类型 + 事件方法 + 字段/签名"都确认后，才开始生成代码。
代码生成后，必须执行 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 个文档）

IF 涉及保存/提交/审核/回滚 → 读 operate-chain.md
IF 涉及下推/选单/来源追踪 → 读 botp-convert.md
IF 涉及查询/聚合/DataSet → 读 query-dataset.md
IF 涉及后台打开表单/列表 → 读 view-handler.md
IF 涉及表单控件/UI消息/元数据读取 → 读 form-utils.md
IF 涉及 DynamicObject 安全取值/序列化 → 读 dynamic-object.md
IF 涉及实体元数据/字段路径/DBRoute → 读 entity-metadata.md
IF 涉及弹性域字段/值解析 → 读 flex-prop.md
IF 涉及附件上传/下载/复制 → 读 attachment-api.md
IF 涉及跨线程身份/上下文恢复 → 读 request-context.md

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

ORM/QFilter/KSQL → sdk-orm-access.md
内存计算/DataSet → sdk-algo.md
公共服务/ServiceHelper → sdk-dynamic-model-svc.md
DynamicObject → sdk-dynamic-object.md
元数据/EntityModel → sdk-entity-model.md
分布式ID → sdk-id.md | 锁 → sdk-lock.md | 缓存 → sdk-cache.md | 事务KDTX → sdk-tx.md
日志 → sdk-log.md | 异常 → sdk-exception.md | 线程池 → sdk-threadpool.md
文件 → sdk-file.md | 上下文 → sdk-request-context.md | 网控 → sdk-network-control.md
工具类 → sdk-utils.md

子文件引用

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

高频 API 速查表（无需脚本验证） → rules/cheat-sheet.md
禁忌清单（幻觉方法名/类名/场景错配） → rules/anti-patterns.md
插件开发 8 步流程 → rules/plugin-dev-flow.md
编码偏好与实现细则 → rules/coding-preferences.md
强制约束与验证策略 → rules/constraints.md
工作流与配置自检 → rules/workflow.md
生成后自动校验规则 → rules/post-lint.md
场景化代码片段 → 见下方 snippets 映射表

场景化代码片段 (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

定向搜索优先级

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

对生成的文件执行校验脚本：

python3 <SKILL_ROOT>/scripts/cosmic-post-lint.py <生成的文件或目录> --fix-hint

若报告中存在 ERROR 级问题，必须立即修复后重新执行校验，直到 ERROR 为 0。
若仅存在 WARNING 级问题，应优先修复；若有合理理由可保留，须在代码注释中说明原因。
INFO 级问题为建议项，按团队风格决定是否处理。

AI 调用约束 (Post-Lint)

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

Reviews

No reviews yet. Tell others what you thought.

Comments

No login needed. Share how it worked for you, ask a question, or note where it did not run.

No comments yet. Be the first to write one.

Report a problem with this skill

Install

Install with a command

npx skills add https://github.com/ChenZeXian/ok-cosmic --skill ok-cosmic

Paste it into your terminal and run it (requires Node.js). You can choose which agents to install it for, such as Claude Code or Codex.

Ask your agent

Please install the following Agent Skill.
https://github.com/ChenZeXian/ok-cosmic

First review SKILL.md and the bundled files and confirm there is nothing suspicious (such as sending data externally or reading credentials). Then place it in ~/.claude/skills/ok-cosmic/ for Claude Code, or ~/.agents/skills/ok-cosmic/ for Codex.

Send this text to Claude Code or Codex as is. It checks the contents before installing.

View source on GitHub

Repository: ChenZeXian/ok-cosmic
Stars: 16
Forks: 6
Category: Development
License: Apache-2.0
Original language: Chinese
Last updated: Mar 30, 2026

A skill is a set of instructions and scripts for an agent. cccskills does not guarantee that skills are safe. Review the contents before you install.