--- name: kd-cosmic-dev description: 金蝶苍穹/Cosmic 平台 Java 插件开发技能，适用于苍穹、星瀚和星空旗舰版。处理表单、单据、列表、操作、转换、任务、工作流、OpenAPI、元数据、DynamicObject、附件、基础资料、SDK 方法签名等平台能力开发时使用。 --- # 金蝶 Cosmic 开发 当需要为以下产品实现或修改 Java 代码时使用本技能： - `cangqiong` - `xinghan` - `flagship` 不要把本技能用于金蝶 Enterprise C# 项目。 ## Harness 前置条件 生成或修改代码前： - 先用 `kd_plan_status` 查看当前运行状态。 - 确认产品画像是 `cangqiong`、`xinghan` 或 `flagship`。 - 执行阶段必须已有 `PLAN.md`。 - Cosmic 代码生成前必须运行 `kd_cosmic_config`。如果配置检查失败，停止编码并说明缺失配置。 在当前运行产物中记录决策和证据： - `.pi/kd/runs//PLAN.md` - `.pi/kd/runs//EXECUTION.md` - `.pi/kd/runs//evidence/cosmic-config.txt` - `.pi/kd/runs//evidence/cosmic-metadata.json` - `.pi/kd/runs//evidence/cosmic-api.txt` 官方工具会在存在 active run 时自动写入证据；如果没有自动写入，需要把命令、结果摘要和采用原因写进 `EXECUTION.md`。 ## 开发流程 1. 先把需求拆成“时机 + 载体 + 能力”。 - 时机：生命周期事件、操作阶段、转换阶段、定时任务、API 请求、UI 事件。 - 载体：表单插件、单据插件、列表插件、操作插件、校验器、转换插件、反写插件、任务、工作流、报表、控制器。 - 能力：元数据、字段访问、查询保存、基础资料、DynamicObject、附件、权限上下文、消息、集成。 2. 依赖平台行为前，先搜索内置知识。 - 用 `kd_search` 查询生命周期、插件类型、决策矩阵、平台约束、API 模式和审查清单。 - `kd_table` 只用于已覆盖的内置表结构。Cosmic 数据库字段优先使用官方元数据证据。 3. 通过官方适配器验证产品事实。 - 代码引用字段、表单 ID、单据名称、枚举/下拉值、实体 ID、操作编码、SQL 字段时，使用 `kd_cosmic_metadata`。 - 类名、方法名、方法签名、继承关系、Override 签名不确定时，优先使用 `kd_sdk_signature` 从当前项目实际 SDK jar 中验证；`kd_cosmic_api` 只作为随包知识线索和兜底。 - 多个表单或字段能够合并查询时，合并为一次元数据查询。 - 元数据查询和 API 签名查询互不依赖时并行执行。 4. 只有插件类型、生命周期方法、字段元数据和 API 签名都明确后，才生成或修改代码。 - 遵循项目已有包名、基类、常量、日志风格和 helper 封装。 - 星空旗舰版项目先检查当前目录结构，再选择真实目标路径。若存在 `code/`，跟随 `code/` 下既有组织；若不存在，跟随已发现的源码根或目标文件，不要在项目根目录新建 `src/main/java`。 - 优先使用项目本地封装和已批准的苍穹/Cosmic 平台 helper，再考虑底层 BOS API。 - 事件处理器只做当前事件阶段该做的事。 5. 验证结果。 - 对修改的 Java 代码运行 `kd_check`。 - 条件允许时运行 `kd_build` 或计划中的 Gradle 命令，优先用 `.\gradlew.bat build`、`./gradlew build` 或最窄可行的 `:模块:build` 检查语法和编译。 - 把验证证据写进 `EXECUTION.md`，最终验收交给 `kd-verify`。 ## 硬性规则 - 不臆造字段 key、表单 ID、操作名、枚举值、表名或 SDK 方法；本地 SDK 查不到且编译未验证时，不把知识库结果当作最终签名事实。 - 不把 Enterprise C# 命名空间或生命周期假设用于苍穹/Cosmic 平台 Java。 - 星空旗舰版不允许猜目录或写 demo/sample；无法判断真实代码位置时，先登记阻塞问题或更新计划，不得直接创建新目录。 - 不在数据绑定前的初始化阶段操作 UI 控件。 - 不在平台期望修改入参数据实体的事务钩子里另起保存。 - 不在循环中查询或保存，除非计划中明确说明无法批量处理并接受风险。 - 使用参数化查询或平台查询过滤，不拼接用户输入 SQL。 - 按 SDK 要求关闭 `DataSet` 和其他平台资源。 - 避免插件类中的不安全静态可变状态。 ## 输出要求 完成执行工作时说明： - 修改了哪些文件。 - 使用了哪些检查：配置、元数据、本地 SDK 签名、API 知识、编译。 - 哪些事实仍无法验证。 - 验证命令和结果。 - `EXECUTION.md` 中记录相对 `PLAN.md` 的偏差。