🚀

v1.3.0

ok-cosmic

金蝶云苍穹 AI 开发技能 — 完整介绍

封装优先幻觉防护自动校验离线知识库

作者：陈泽贤、钱芮名 | 仅限内部使用

什么是 ok-cosmic？

面向金蝶云苍穹二开场景的 AI Agent Skill，让 AI 真正理解苍穹 SDK

15

插件模板

7

内置工具

24

代码片段

19

A层硬规则

12

规则文档

12

封装参考文档

6

Lint 检查器

40+

STYLE/SCENE 规则

四大设计目标

🧠

AI 理解无障碍

所有文档、模板、规则均面向 AI 消费设计，结构化标签 + 锚点引用，让 Agent 精准定位信息

🎯

生产级代码

通过模板骨架 + A/B/C 三层规则 + 自动 post-check，确保 AI 生成的代码可直接进入 Code Review

⚡

Token 效率

决策矩阵索引 + 最小加载原则 + TL;DR 摘要机制，减少无效上下文消耗

📦

开箱即用

Step 0 自动预检 + 依赖自动安装 + 离线知识库，一条命令完成环境验证

五大核心能力

🧩

插件选型与模板骨架

14 种插件类型 + 11 种能力类型全覆盖，决策矩阵 + 意图路由自动匹配最佳方案

🔎

离线 API 知识查询

基于 SQLite 知识图谱，支持类名搜索、方法搜索、继承链校验、签名验证，完全离线可用

🗂️

元数据 / 基础资料在线查询

通过 OpenAPI 实时查询字段标识、枚举映射、refType、基础资料编码名称，支持本地缓存

🛡️

幻觉防护与规则约束

11 个幻觉方法名 + 6 个幻觉类名黑名单 + 12 个场景错配规则 + 24 个编码风格规则，自动 lint 检测

✅

代码生成后自动校验

Gradle 编译 + post-lint 串联，6 大检查器并行扫描，ERROR 阻断 → 自动修复 → 复检闭环

技能架构总览

ok-cosmic/
├── SKILL.md          # AI 主入口（线性执行流）
├── manifest.json     # 工具注册（7 tools）
├── assets/           # 15 个插件模板
│   └── snippets/     # 24 个场景代码片段
├── rules/            # 12 个规则文档
│   ├── constraints.md      # A层硬约束
│   ├── anti-patterns.md    # 禁忌清单
│   ├── coding-preferences.md # B/C层偏好
│   ├── decision-matrix.md  # 决策矩阵
│   ├── intent-routing.md   # 意图路由
│   ├── cheat-sheet.md      # 高频API速查
│   ├── post-check.md       # 校验规则
│   └── a-layer-rules.json  # 规则ID配置
├── scripts/          # 7 个 Python 工具脚本
│   └── lint/         # 6 个静态检查器
└── references/       # SDK 参考文档
    ├── adv/          # 12 篇封装层文档
    └── base/         # 原生SDK文档
      

SKILL.md — AI 大脑

线性执行流设计：Step 0 预检 → 意图路由 → 决策矩阵 → 确认卡 → 代码生成 → Post-Check

rules/ — 规则引擎

A/B/C 三层分治，文档与 lint 脚本 1:1 映射，a-layer-rules.json 作为单一可信源

scripts/ — 工具链

7 个 Python 脚本 + 6 个 lint 检查器，支持离线/在线混合查询与自动校验

assets/ — 模板库

15 个骨架模板 + 24 个场景片段，覆盖苍穹全部主流二开场景

14 种插件类型全覆盖

每种类型配套：模板骨架 + 参考文档 + 代码片段 + 决策矩阵卡片

📋

表单插件
字段联动 / 控件交互

📄

单据插件
审核提交 / 单据头体

📑

列表插件
多选操作 / 批量处理

🌳

树列表插件
左树右表

⚙️

操作插件
保存 / 审核 / 校验

🔄

转换插件
下推 / BOTP 转换

↩️

反写插件
BOTP 回写阶段

📊

报表插件
过滤容器 / 界面

📈

报表取数
动态列 / DataSet

🖨️

打印插件
套打模板

🌐

OpenAPI
外部集成接口

⏰

后台任务
定时调度作业

🔀

工作流插件
审批流节点

📥

导入插件
批量导入

7 个内置工具脚本

工具名	功能	关键特性
cosmic_search_classes	模糊/正则搜索苍穹类名	离线支持包前缀、kind 过滤
cosmic_search_methods	跨类全局搜索方法名	离线排名 + 分类筛选
cosmic_get_class_detail	查看类详情 / 校验签名	离线继承链 + compact 模式
cosmic_get_meta_fields	查询表单元数据字段	在线+缓存 fuzzy/detail/tree 视图
cosmic_query_basedata	查询基础资料数据	在线+缓存编码/名称/完整数据包
cosmic_post_check	代码生成后统一校验	Gradle+Lint 6 大检查器并行
cosmic_config_check	Step 0 环境预检	自动安装 Python 依赖自动补全

AI 开发决策流程

从用户需求到代码交付的完整链路

Step 0
配置预检

→

意图路由
时机+载体+能力

→

决策矩阵
命中1主+0-1能力

→

最小确认卡
6项全部就绪

读模板骨架
assets/*.java

→

验证签名
cheat-sheet/脚本

→

生成代码

→

Post-Check
≤3轮修复闭环

最小确认卡（6 项必须就绪）

① 插件类型 ← 决策矩阵

② 目标事件方法 ← 模板/references

③ 使用模板 ← assets/*.java

④ 已验证字段/refType ← 元数据脚本

⑤ 已确认枚举值 ← metadata Ext

⑥ 已验证类/方法签名 ← cheat-sheet/API

A / B / C 三层规则体系

区分"硬红线"与"建议写法"，避免一刀切

A 层 · 硬约束

ERROR 阻断交付

拒绝 API 幻觉
模板签名强制校验
操作插件禁调 getView()
绑定阶段禁改数据
循环禁访数据库/Redis
DataSet 必须 close
禁止 printStackTrace()
SQL 必须参数化

来源：constraints.md · anti-patterns.md
19 个规则 ID 定义在 a-layer-rules.json

B 层 · 推荐项

WARNING 新代码优先

优先使用 Ext 扩展基类
优先使用 OpUtils / BotpUtils
CharSequenceUtils 判空
CollectionUtils 判空
query+load 替代直接 set
ThreadPools 替代 new Thread
KDBizException 替代 RE

来源：coding-preferences.md
历史代码不因 B 层判错

C 层 · 治理项

INFO 渐进优化

补 @Override 验证来源注释
统一异常体系
减少原生样板代码
进一步封装收敛

来源：coding-preferences.md · post-check.md
仅 --strict 模式检查 VERIFY-*

幻觉防护机制

AI 代码生成中最常见的苍穹 SDK 幻觉，ok-cosmic 全部拦截

幻觉方法名黑名单（11 项）

`setReadOnly()`	→ `getView().setEnable()`
`model.getRowCount()`	→ `model.getEntryRowCount()`
`model.addRow()`	→ `model.createNewEntryRow()`
`model.deleteRow()`	→ `model.deleteEntryRow()`
`getView().refresh()`	→ `getView().updateView()`
`queryAll()`	→ `query()`

幻觉类名黑名单（6 项）

不存在 Cosmic* 工具类
不存在 Cloud* Utils/Helper
不存在 BillHelper
不存在 FormHelper
不存在 ListHelper
不存在 PluginHelper

枚举值禁猜 [A1.8]

下拉字段选项值必须通过元数据脚本确认，禁止凭经验猜测

Post-Check 自动校验

每次代码生成后自动触发，形成闭环

生成 .java

→

kd_check + kd_build

→

Gradle？

Gradle 项目

gradlew compileJava

→

post-lint 场景/风格

→

综合结果

非 Gradle 项目

post-lint 静态校验

→

输出结果

4 大并行检查器

scene_check
场景错配检测

style_check
编码风格 24 规则

resource_check
资源管理 4 规则

verify_check
验证来源留痕

代码片段矩阵

24 个场景化代码片段，按领域分类，可直接引用

📋 form/ (10 篇)

ViewControlOpsSample
F7FilterSample
ConfirmDialogSample
OpenBillModalSample
TreeControlSample
...

🔍 query/ (3 篇)

BatchQuerySample
DataSetQueryStatSample
BaseDataQuerySample

📦 data/ (2 篇)

DynamicObjectOpsSample
DynamicObjectCrudSample

⚙️ operation/ (2 篇)

OpAddValidatorsSample
OperationOptionBridgeSample

🔄 botp/

BotpTracePushSample

📎 attachment/

AttachmentUploadBindSample

💬 message/ · ⏰ task/ · 🔗 concurrent/

自然语言意图路由

三步翻译：时机 → 载体 → 能力，从业务话术到技术场景

① 看"时机词"

"保存前""审核时"	→ 操作插件
"下推时""选单时"	→ 转换插件
"字段变化""F7 过滤"	→ 前端交互
"定时执行""后台跑"	→ 后台任务
"外部调用""接口"	→ OpenAPI

② 看"载体词"

"表单上""控件"	→ 表单插件
"单据界面""头体"	→ 单据插件
"列表上""批量"	→ 列表插件
"左树右表"	→ 树列表插件
"报表过滤"	→ 报表插件

③ 补"能力词"

"打开页面""弹窗"	→ 视图跳转
"查数据""ORM"	→ 查询存取
"基础资料""物料"	→ 基础资料
"附件""上传"	→ 附件文件
"跨线程""并发"	→ 上下文恢复

扩展代码库兜底 Extension Repos Fallback

信息检索的最后一道防线：内置资产与当前项目都 miss 时，再走拓展仓库

1

📖

cheat-sheet

高频 API 速查

miss

→

2

🗄️

知识库脚本

API 事实 / 字段校验

miss

→

3

🧩

assets/snippets

场景实现模板

miss

→

4

📦

extensionRepos

拓展仓库兜底 ⭐

触发条件需同时满足

内置资产
全部 miss

当前项目
无可用实现

触发
Fallback

两个条件的交集才会触发，避免乱跳拓展仓

一行配置即启用 ok-cosmic.json

{
  // 其他字段省略…
  "extensionRepos": [
    "/path/to/ext-repo-1",
    "~/code/ext-repo-2"
  ]
}
      

支持 ~ 展开、多路径。Step 0 预检自动校验，路径不存在只给 WARNING。

📌

仅参考不等同于 ok-cosmic 推荐写法

🛡️

规范优先与 A/B 层冲突时以 ok-cosmic 为准

🔘

可选开关未配置或空数组时自动跳过

快速开始

你的情况	从哪步开始	预计耗时
首次完整安装（含服务端）	步骤 1	30 分钟
服务端已就绪，新项目接入	步骤 6	2 分钟
已有项目，换 Agent	步骤 7	1 分钟

安装步骤概览

环境检查（Java 8+ / Python 3.8+）
部署自定义封装库 JAR
注册元数据 + 基础资料 OpenAPI
构建离线知识库
知识验证
创建 ok-cosmic.json 配置
软链接安装 Skill
加载 Skill 开始编程

多 Agent 共享（推荐）

# 唯一维护一份 skill 源
~/skills/ok-cosmic

# 各 Agent 软链接指向
~/.claude/skills/ok-cosmic    → ~/skills/ok-cosmic
~/.opencode/skills/ok-cosmic  → ~/skills/ok-cosmic
~/.codex/skills/ok-cosmic     → ~/skills/ok-cosmic
~/.gemini/.../ok-cosmic       → ~/skills/ok-cosmic
      

更新一处，多个 Agent 同步生效

典型使用场景

场景一：表单字段联动

// 用户说：
"帮我写一个表单插件，数量变化时自动计算金额"

// AI 执行路径：
1. 意图路由 → "字段值改变" → 表单插件
2. 决策矩阵 → #form-plugin
3. 确认卡 → propertyChanged 事件
4. 查元数据 → 确认 qty / price / amount 字段
5. 读 FormPluginTemplate.java
6. 生成代码 → Post-Check ✅
      

场景二：审核前校验

// 用户说：
"审核时校验分录不能为空"

// AI 执行路径：
1. 意图路由 → "审核时" → 操作插件
2. 决策矩阵 → #op-plugin
3. 确认卡 → onAddValidators 事件
4. 读 OpPluginTemplate.java
5. 查 cheat-sheet → getEntryRowCount API
6. 生成代码 → Post-Check ✅
      

场景三：BOTP 下推

// 用户说：
"实现销售订单到出库单的下推转换"

// AI 执行路径：
1. 意图路由 → "下推" → 转换插件
2. 决策矩阵 → #convert-plugin
3. 读 BotpTracePushSample 片段
4. 读 ConvertPlugInTemplate.java
5. 生成代码 → Post-Check ✅
      

场景四：API 签名校验

// 用户说：
"查询 QueryServiceHelper 的 loadSingle 用法"

// AI 执行路径：
1. 调用 cosmic_get_class_detail
2. detail kd.bos.servicehelper
        .QueryServiceHelper
        --method loadSingle --compact
3. 返回精确签名 + 参数说明
4. 写入代码 → 签名保证准确
      

总结

核心价值

消除 API 幻觉 — 黑名单 + 知识库校验双保险
事件时机正确 — 场景错配自动检测
封装优先落地 — 模板 + 规则引导使用封装
交付质量保证 — Post-Check 自动闭环校验
拓展库兜底 — extensionRepos 补足内置资产的长尾空白
Token 高效 — 索引 + 按需加载最小化上下文

兼容性

Claude Code / Qoder
OpenCode / Codex
Gemini CLI
任何支持 Skill 的 AI Agent

🚀

v1.3.0

ok-cosmic

让 AI 真正理解苍穹 SDK
写出生产级代码

15 模板 7 工具 6 检查器 24 片段 19 硬规则

作者：陈泽贤、钱芮名 | 金蝶云苍穹 AI 开发技能

ok-cosmic

什么是 ok-cosmic？

四大设计目标

AI 理解无障碍

生产级代码

Token 效率

开箱即用

五大核心能力

插件选型与模板骨架

离线 API 知识查询

元数据 / 基础资料在线查询

幻觉防护与规则约束

代码生成后自动校验

技能架构总览

SKILL.md — AI 大脑

rules/ — 规则引擎

scripts/ — 工具链

assets/ — 模板库

14 种插件类型全覆盖

7 个内置工具脚本

AI 开发决策流程

最小确认卡（6 项必须就绪）

A / B / C 三层规则体系

A 层 · 硬约束

B 层 · 推荐项

C 层 · 治理项

幻觉防护机制

幻觉方法名黑名单（11 项）

幻觉类名黑名单（6 项）

枚举值禁猜 [A1.8]

Post-Check 自动校验

Gradle 项目

非 Gradle 项目

4 大并行检查器

代码片段矩阵

📋 form/ (10 篇)

🔍 query/ (3 篇)

📦 data/ (2 篇)

⚙️ operation/ (2 篇)

🔄 botp/

📎 attachment/

💬 message/ · ⏰ task/ · 🔗 concurrent/

自然语言意图路由

① 看"时机词"

② 看"载体词"

③ 补"能力词"

扩展代码库兜底 Extension Repos Fallback

触发条件 需同时满足

一行配置即启用 ok-cosmic.json

快速开始

安装步骤概览

多 Agent 共享（推荐）

典型使用场景

场景一：表单字段联动

场景二：审核前校验

场景三：BOTP 下推

场景四：API 签名校验

总结

核心价值

兼容性

ok-cosmic

触发条件需同时满足