---
name: ok-cosmic
description: >
  实现或修改金蝶AI苍穹/星瀚/套件 Cosmic Java 插件与相关能力。
  Use when: 用户要写/改表单单据列表操作转换报表打印 OpenAPI 后台任务工作流导入插件；
  处理 DynamicObject、元数据、F7、BOTP、附件、查询取数；或验证 kd.bos/SDK 签名与字段。
  Do not use when: 企业版 C#/IronPython 插件、纯前端非 Cosmic、与苍穹无关的通用 Java。
---

# 苍穹 Cosmic 插件开发

封装优先，原生兜底：先复用项目已有封装，再退到 BOS 原生 API。

## When / Do not

**Use when**

- 需求落在 Cosmic/BOS **Java 插件**（表单/单据/列表/操作/转换/反写/报表/打印/OpenAPI/任务/工作流/导入）
- 需要平台 API、字段元数据、事件生命周期、数据包操作

**Do not use when**

- 企业版 C# → `kd-enterprise-csharp`
- 企业版 IronPython → `kd-enterprise-python-plugin`
- 与苍穹无关的通用 Java 工程

## Input / Output

**Input（编码前必须具备或先查清）**

| 字段 | 说明 |
|------|------|
| pluginType | 表单/单据/列表/操作/转换/… |
| eventOrHook | 目标事件方法名 |
| formOrEntity | 单据/表单/entityId（英文标识，已验证） |
| fields | 字段 key、类型、枚举（元数据已验证） |
| projectPath | 真实源码路径与模块 |

**Output**

| 字段 | 说明 |
|------|------|
| files | 修改/新增的 `.java` 路径 |
| registration | BOS 注册点说明 |
| facts | 已确认的 form/entity/字段/API |
| verify | review/编译/功能验证结果 |

## Steps（执行清单，逐步勾选）

复制并跟踪：

```
- [ ] 1. 预检：cwd 执行 mvn validate -DdryRun=true（ERROR 则停；WARNING 告知后受限继续）
- [ ] 2. 意图 → 时机+载体+能力；读 rules/intent-routing.md（仅当原话仍是业务描述）
- [ ] 3. 决策矩阵命中 1 行主场景（+0~1 能力行）：rules/decision-matrix.md 锚点 1–3 行，勿通读
- [ ] 4. 读对应 assets/*.java 模板签名；项目内搜相似插件对齐风格
- [ ] 5. 并行验证：按 `skills/_shared/metadata-db-query.md` **Agent 引导只读 SQL + LLM 解析**（非 MCP）
        · 无连接信息 → **先问用户**（主机/库名/只读认证）
        · entityId=元数据标识，禁止物理表名；API ⊆ assets/cheat-sheet- [ ] 6. 仅当类型+事件+字段/签名齐备后写代码；禁止臆造 entityId/字段/方法

- [ ] 7. Post-check：review（kd-cosmic-review-rules）+ 条件允许则编译；P0 修完再交付
```

**短路**：需求单一且 `rules/cheat-sheet.md` 已覆盖 API → 可跳过 references 全文，模板+snippet 即可。

**失败策略**

| 失败 | 动作 |
|------|------|
| mvn validate ERROR | 停止生成，列出缺失依赖/配置 |
| 无库连接信息 | **向用户索取**连接；不假装已验证 |
| 元数据/entityId 查不到 | 换库/FormId；或用户给准标识 / 标 assumption || API 签名无法验证 | 不写调用；先验证再生成 |
| review P0 | 最多 3 轮修复→复检，仍失败则报告用户 |
| 决策矩阵未命中 | 见「扩展探索」；仍无则最小提问，不瞎猜 |

## 决策矩阵（只作索引）

完整表：[rules/decision-matrix.md](rules/decision-matrix.md)  
意图翻译：[rules/intent-routing.md](rules/intent-routing.md)

| 关键词 | 锚点 |
|--------|------|
| 表单 UI/联动 | form-plugin |
| 单据/审核提交 | bill-plugin |
| 列表/批量 | list-plugin |
| 树列表 | tree-plugins |
| 保存审核校验 | op-plugin |
| 下推转换 | convert-plugin |
| 反写 | writeback-plugin |
| 报表 UI | report-form-plugin |
| 报表取数 | report-data-plugin |
| 打印 | print-plugin |
| OpenAPI | openapi-plugin |
| 调度任务 | task-plugin |
| 工作流 | workflow-plugin |
| 导入 | import-plugin |

能力行（视图/查询/DynamicObject/元数据/附件/消息等）见矩阵全文。

## 硬约束（摘要）

全文：[rules/constraints.md](rules/constraints.md)、[rules/anti-patterns.md](rules/anti-patterns.md)

- 禁止臆造 API/字段；entityId 仅用户明确或元数据确认
- UI：`IFormView`；数据：`IDataModel`；操作插件无 `getView()` 假设
- 禁：`initialize` 注册 UI、绑定阶段乱 `setValue`、循环查库/updateView、直查 `t_meta_*`、空 catch、`printStackTrace`、`org.slf4j`/`MDC`
- 日志：`kd.bos.logging.Log`；业务异常优先平台业务异常类型
- **语言包 vs 平台**：`lang-java` 是阿里手册语言层；冲突时平台优先 → [rules/lang-vs-platform.md](rules/lang-vs-platform.md)

## 工具

| 场景 | 工具 |
|------|------|
| 预检/编译 | `bash` + mvn/gradle |
| 字段/枚举 | Agent 引导只读 SQL + LLM 解析（`metadata-db-query.md`，非 MCP）；无连接先问用户 |
| SDK 签名 | cheat-sheet；否则 `web_search` + `jar tf` |
| 审查 | `review` + kd-cosmic-review-rules |

## 渐进披露（按需 read，一层链接）

| 需要时 | 文件 |
|--------|------|
| 元数据连库+解析 | [../_shared/metadata-db-query.md](../_shared/metadata-db-query.md) |
| A 层红线 | [rules/constraints.md](rules/constraints.md) |

| 禁忌清单 | [rules/anti-patterns.md](rules/anti-patterns.md) |
| B 层偏好 | [rules/coding-preferences.md](rules/coding-preferences.md) |
| 事件生命周期 | [references/adv/event-lifecycle.md](references/adv/event-lifecycle.md) |
| API 速查 | [rules/cheat-sheet.md](rules/cheat-sheet.md) |
| 生成后校验 | [rules/post-check.md](rules/post-check.md) |
| 片段 | [assets/snippets/snippets-guide.md](assets/snippets/snippets-guide.md) |
| 平台摘要 | [rules/platform-baseline.md](rules/platform-baseline.md) |
| 语言 vs 平台 | [rules/lang-vs-platform.md](rules/lang-vs-platform.md) |
| Java 语言层（已裁冲突） | [references/lang-java/INDEX.md](references/lang-java/INDEX.md) |

## 扩展代码库

仅当：矩阵/cheat-sheet/snippets 皆无覆盖 **且** 当前项目无可用实现 **且** 已配置 extensionRepos。只作写法参考，冲突以本 skill A/B 层为准。

## 验证（交付时说明）

- 改了哪些 `.java`
- 注册点
- 已确认的 form/entity/字段/API
- review/编译/功能步骤与结果