kcode-pi 0.1.0

package/vendor/kingdee-skills/ok-cosmic/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: "ok-cosmic"
+description: "金蝶云苍穹开发主 Skill，优先复用 kd-cd-cosmic-commons 封装。适用于插件开发、单据/列表/表单逻辑、操作服务、BOTP 转换、后台视图打开、附件处理、DynamicObject 与元数据处理、弹性域解析及 OpenAPI 集成。默认优先使用仓库封装；在涉及原生插件事件、SDK API、方法签名或封装未覆盖场景时，使用内置脚本进行查询。"
+---
+
+# 苍穹开发
+
+默认按"封装优先，原生兜底"工作，避免在仓库已封装的场景里退回到 BOS 原生低层 API。
+
+## 路径约定
+
+- `<SKILL_ROOT>` = 当前 `SKILL.md` 所在的目录（即 `skills/ok-cosmic/`）
+
+## Step 0. 配置预检（先于一切）
+
+1. Step 0 的第一个动作必须直接执行：
+   `python3 <SKILL_ROOT>/scripts/cosmic-config-check.py`
+2. 默认在当前项目工作目录直接执行；不要先询问或搜索 `ok-cosmic.json` 的位置。
+3. 只有用户明确提供了其他配置路径，或当前工作目录不是目标项目根目录时，才改用：
+   `python3 <SKILL_ROOT>/scripts/cosmic-config-check.py --config <显式路径>`
+4. 若脚本返回非 0 或输出含 `ERROR`：停止生成代码，明确提示用户补齐缺失项。
+5. 若仅有 `WARNING`：先告知用户哪些在线能力不可用，再决定是否继续当前任务。后续脚本调用受以下限制：
+
+   | WARNING 类型 | 限制 |
+   |---|---|
+   | "API 不可达" 或 "在线服务不可用" | **禁止调用** `cosmic-basedata-query.py`；`cosmic-form-metadata.py` 仅允许使用本地缓存，**禁止 `--refresh` 刷新** |
+   | "知识库不存在" | `cosmic-api-knowledge.py` 不可用，改为仅依赖 `cheat-sheet.md` 和模板中的方法签名 |
+
+## 自然语言意图路由（首读）
+
+先把用户原话翻译成"**时机 + 载体 + 能力**"，再进入统一决策矩阵。
+
+> 详细自然语言映射、例句和误判修正见 [rules/intent-routing.md](rules/intent-routing.md)。
+
+## 统一决策矩阵（精简索引）
+
+使用方式：
+- 先命中 **1 行主场景**（通常是插件行），再按需补 **0-1 行能力行**。
+- 用户原话如果还是业务描述，先读 [rules/intent-routing.md](rules/intent-routing.md) 做语义翻译。
+- 完整矩阵和未命中兜底见 [rules/decision-matrix.md](rules/decision-matrix.md)。
+- 命中索引后，只跳到对应锚点附近 **1-3 行**，不要整表通读。
+- **短路条件**：如果需求明确单一（例如"加个保存前校验""加个 F7 过滤"），且 `rules/cheat-sheet.md` 已覆盖所需 API，可跳过 references 直接用模板 + snippet。只有在不确定事件时机、生命周期约束或封装边界时，才需要展开 references 全文。
+
+### 插件类
+
+| 需求关键词 | 场景 | 详见矩阵行 |
+|---|---|---|
+| 表单 UI / 字段联动 / 控件交互 | 表单插件 | [`#form-plugin`](rules/decision-matrix.md#form-plugin) |
+| 单据 UI / 审核提交按钮 | 单据插件 | [`#bill-plugin`](rules/decision-matrix.md#bill-plugin) |
+| 列表 / 多选操作 / 批量 | 列表插件 | [`#list-plugin`](rules/decision-matrix.md#list-plugin) |
+| 左树右表（单据 / 基础资料） | 树列表插件 | [`#tree-plugins`](rules/decision-matrix.md#tree-plugins) |
+| 审核 / 保存 / 状态流转 / 校验 / 回滚 | 操作插件 | [`#op-plugin`](rules/decision-matrix.md#op-plugin) |
+| 下推 / 选单 / 来源追踪 / 转换 | 转换插件 | [`#convert-plugin`](rules/decision-matrix.md#convert-plugin) |
+| 明确指定反写插件 / BOTP 回写阶段 | 反写插件 | [`#writeback-plugin`](rules/decision-matrix.md#writeback-plugin) |
+| 报表 / 数据分析 | 报表插件 | [`#report-form-plugin`](rules/decision-matrix.md#report-form-plugin) |
+| 报表取数 / 动态列 / 自定义数据源 | 报表取数插件 | [`#report-data-plugin`](rules/decision-matrix.md#report-data-plugin) |
+| 打印 / 套打 | 打印插件 | [`#print-plugin`](rules/decision-matrix.md#print-plugin) |
+| OpenAPI / 外部集成 | OpenAPI 控制器 | [`#openapi-plugin`](rules/decision-matrix.md#openapi-plugin) |
+| 后台任务 / 定时 / 调度作业 | 后台任务 | [`#task-plugin`](rules/decision-matrix.md#task-plugin) |
+| 工作流 / 审批流 | 工作流插件 | [`#workflow-plugin`](rules/decision-matrix.md#workflow-plugin) |
+| 导入 / 批量导入 | 导入插件 | [`#import-plugin`](rules/decision-matrix.md#import-plugin) |
+
+### 能力类
+
+| 需求关键词 | 能力 | 详见矩阵行 |
+|---|---|---|
+| 后台打开表单 / 列表 / 新页签跳转 | 视图打开与跳转 | [`#view-handler`](rules/decision-matrix.md#view-handler) |
+| 表单控件 / UI 消息 / 元数据读取 | 界面工具 | [`#form-utils`](rules/decision-matrix.md#form-utils) |
+| 数据加载 / 保存 / 查询 / ORM / DataSet | 查询与存取 | [`#query`](rules/decision-matrix.md#query) |
+| 基础资料 / 管控策略 / 分配 / 个性化 | 基础资料 | [`#basedata`](rules/decision-matrix.md#basedata) |
+| DynamicObject / 安全取值 / 序列化 | 数据包操作 | [`#dynamic-object`](rules/decision-matrix.md#dynamic-object) |
+| 实体元数据 / 字段路径 / DBRoute | 元数据与结构 | [`#entity-metadata`](rules/decision-matrix.md#entity-metadata) |
+| 弹性域字段 / 值解析 | 弹性域 | [`#flex-prop`](rules/decision-matrix.md#flex-prop) |
+| 消息 / 邮件 / 短信 / 企业微信 | 消息通知 | [`#message`](rules/decision-matrix.md#message) |
+| 附件上传 / 下载 / 复制 / 面板绑定 | 附件与文件 | [`#attachment`](rules/decision-matrix.md#attachment) |
+| 组织 / 权限 / 上下文 | 上下文判定 | [`#request-context`](rules/decision-matrix.md#request-context) |
+| 跨线程身份 / 上下文恢复 | 并发上下文恢复 | [`#thread-context`](rules/decision-matrix.md#thread-context) |
+| 业务拓展点 / 业务扩展点 / SDK 扩展接口 / Java 示例 | 业务拓展点查询 | [`#business-extpoints`](rules/decision-matrix.md#business-extpoints) |
+
+> 仍未命中时，按 [rules/decision-matrix.md#fallback](rules/decision-matrix.md#fallback) 的兜底流程处理；若 `ok-cosmic.json` 配置了 `extensionRepos`，则进入下方“扩展代码库探索”流程。
+
+## 开发前规范预检（需求涉及平台对象时必做）
+
+1. 先快速过一遍 `rules/platform-baseline.md`，确认需求是否涉及命名、设计器/PDM、数据库、多语言、微服务、报表等平台级规则。
+2. 若涉及新增或修改业务对象、表、字段、索引、默认值、主键，先确认对象编码、`Key`、PDM 命名、是否允许删除/隐藏。
+3. 若是扩展场景，先确认只做垂直扩展；源页面字段 `Key`、必录属性、基础资料类型不允许改，不需要显示时只做可见性处理。
+4. 若涉及微服务，先确认服务工厂前缀、接口命名和应用归属。
+5. 若涉及报表或大数据量查询，先设计字段裁剪、批量取数、子单据体拆分、`algo` 聚合方案。
+
+## 开发决策路径（完成 Step 0 后执行）
+
+> **并行优先原则**：下列步骤中标注 **‖** 的操作互不依赖，应在同一轮**同时发起**。具体方式：
+> - **多个 read_file / grep_code** → 直接并行 tool call
+> - **复杂多步探索**（标注 🔍）→ 启动多个 **Search Agent** 并行执行，每个 Agent 独立完成一个探索任务后汇总结果
+
+1. 先判断插件类型或能力类别（查上方决策矩阵）。
+   - 有交互界面 → 区分“表单事件”和“控件事件”；控件事件需 `implements XxxListener` + `registerListener` 注册。
+   - 无交互界面（操作、转换、反写、任务） → 按生命周期选正确事件，不套用 UI 插件写法。
+2. **‖ 并行加载**参考文档与模板（启动并行 Search Agent）：
+   - 🔍 **Agent A — 事件参考**：读对应 `references/*.md` 的 TL;DR 摘要 + `assets/*.java` 模板，提取事件签名与骨架。只读当前任务需要的事件方法段，不要一次性通读整个模板。如果卡在事件先后顺序，先读 [references/adv/event-lifecycle.md](references/adv/event-lifecycle.md)。
+   - 🔍 **Agent B — 项目探索**：在用户项目中搜索相似插件实现（同类型插件、相似业务场景），分析已有代码风格、import 习惯、封装用法，确保生成代码与项目风格一致。
+3. **‖ 并行验证**字段与 API 签名（互不依赖的查询应同时发起）：
+   - 调用脚本前，先查下方“脚本路由”表格确认调用模板；表格未覆盖时才执行 `python3 <script> --help`。
+   - 3a. 若目标 API 已在 `rules/cheat-sheet.md` 中列出 → 直接使用，**无需脚本验证**。
+   - 3b. 字段 / `entityId` / 枚举值验证 → 查 `cosmic-form-metadata.py`。**只要要生成代码且已知目标单据/表单，凡涉及字段（无论用户给中文名还是英文标识），都必须验证字段是否存在、字段类型、所属实体和特殊取值规则；多个字段合并到同一次调用**。
+   - 3c. SDK 类名/方法签名不在 cheat-sheet 中 → 查 `cosmic-api-knowledge.py`。**与 3b 互不依赖，应同时发起**。
+   - 3d. 需要查询多个不同类的 detail → **多个 `detail` 调用也可并行**。
+   - ⚠️ `cosmic-basedata-query.py` 必须等 `entityId` 从 3b 确认后才能调用，**不可并行**。
+4. 只有"插件类型 + 事件方法 + 字段/签名"都确认后，才开始生成代码。
+5. 编写代码时遵守最小干预：插件只做当前事件该做的事；能用封装就不退回原生。
+6. **代码生成后，必须执行 `cosmic-post-check.py` 自动校验**，详见"代码生成后自动校验"章节。
+
+## 写代码前的最小确认卡
+
+生成代码前，以下六项必须全部就绪，任一为空则继续查证：
+
+| # | 确认项 | 来源 |
+|---|--------|------|
+| 1 | 插件类型 | 决策矩阵 |
+| 2 | 目标事件方法 | 模板 / references |
+| 3 | 使用模板 | `assets/*.java` |
+| 4 | 已验证字段 / refType / entityId | 生成代码且已知目标单据/表单时，字段中文名/英文标识都必须经 `cosmic-form-metadata.py` 确认；`entityId` 来自用户明确给出或元数据脚本确认 |
+| 5 | 已确认枚举/下拉选项值（有使用时） | `cosmic-form-metadata.py --show-detail` |
+| 6 | 已验证类/方法签名 | cheat-sheet / `cosmic-api-knowledge.py` / 业务拓展点 `--full` 返回的清晰 Java 示例 |
+
+## 脚本路由
+
+### 脚本调用协议
+
+常用脚本的调用模板已列在下方表格，可直接按模板执行。仅当参数不确定或下表未覆盖时，才需先执行 `python3 <script> --help` 确认调用方式。
+
+### 先选脚本，再按模板调用
+
+| 场景 | 优先脚本 | 常用用法 | 调用模板 | 备注 |
+|---|---|---|---|---|
+| SDK 类名、方法名、继承链、`@Override` 签名确认 | `scripts/cosmic-api-knowledge.py` | `search` / `search-method` / `detail` | `python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json <subcommand> ...` | `detail` 支持逗号分隔批量查类详情（并发请求） |
+| 字段标识、枚举映射、`refType`、按中文名确认真实英文标识 | `scripts/cosmic-form-metadata.py` | `get` | `python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get ...` | 字段不确定先查它。`formIdOrName` 支持逗号分隔批量查询（formId 与中文名可混合，自动识别，并发请求） |
+| 已确认 `entityId` 后查询基础资料编码/名称/完整数据 | `scripts/cosmic-basedata-query.py` | `get` | `python3 <SKILL_ROOT>/scripts/cosmic-basedata-query.py --config ok-cosmic.json get ...` | 只在 `entityId` 来源已确认后调用 |
+| 查询业务拓展点 / SDK 扩展接口候选 | `scripts/cosmic-extpoints-query.py` | `get` | `python3 <SKILL_ROOT>/scripts/cosmic-extpoints-query.py --config ok-cosmic.json get --keyword ...` | 默认摘要模式；仅在需要生成代码或查看 Java 示例时加 `--full`；若 `--full` 已返回清晰 Java 示例，可先按示例，不强制立即 `detail` |
+| 生成或修改苍穹 Java 代码后的统一校验 | `scripts/cosmic-post-check.py` | 直接执行 | `python3 <SKILL_ROOT>/scripts/cosmic-post-check.py <file_or_directory> --fix-hint` | 必须形成"生成 -> 校验 -> 修复 -> 复检"闭环 |
+
+### 常用用法示例
+
+```bash
+# 搜索类名
+python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json search QueryServiceHelper
+
+# 搜索方法名
+python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json search-method loadSingle
+
+# 查看类详情（全部方法）
+python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json detail kd.bos.servicehelper.QueryServiceHelper
+
+# 查看类详情（单个方法筛选）
+python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json detail kd.bos.servicehelper.QueryServiceHelper --method loadSingle --compact
+
+# 批量查类详情（逗号分隔，并发请求）
+python3 <SKILL_ROOT>/scripts/cosmic-api-knowledge.py --config ok-cosmic.json detail kd.bos.servicehelper.QueryServiceHelper,kd.bos.servicehelper.SaveServiceHelper --method save --compact
+
+# 查元数据字段
+python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order
+
+# 查元数据字段（带数据库相关信息）
+python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order,ap_finapbill --sql
+
+# 批量查询多个单据（逗号分隔）
+python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order,ap_finapbill --fuzzy supplier
+
+# 混合查询：formId + 中文单据名（自动识别）
+python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get "ap_finapbill,物料,bd_supplier" --fuzzy number
+
+# 模糊筛选字段
+python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order --fuzzy qty price amount
+
+# 按多种字段类型筛选（正则 OR）
+python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order --type "combo|check"
+
+# 类型 + 关键词交集筛选（Decimal 类型且含 amount）
+python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order --type decimal --fuzzy amount
+
+# 按单据中文名查元数据
+python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get 物料
+
+# 查看单据所有操作
+python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order --op
+
+# 按关键词筛选操作
+python3 <SKILL_ROOT>/scripts/cosmic-form-metadata.py --config ok-cosmic.json get sal_order --op 审核 提交
+
+# 查基础资料
+python3 <SKILL_ROOT>/scripts/cosmic-basedata-query.py --config ok-cosmic.json get --entity-id bd_material --number-or-name 01.0001
+
+# 查业务拓展点
+python3 <SKILL_ROOT>/scripts/cosmic-extpoints-query.py --config ok-cosmic.json get --keyword 应付
+
+# 代码校验
+python3 <SKILL_ROOT>/scripts/cosmic-post-check.py ./src/main/java/MyPlugin.java --fix-hint
+```
+
+### 跨脚本硬约束
+
+- 完成 Step 0 后，后续脚本优先显式使用 `--config ok-cosmic.json`；若当前工作目录不是项目根目录，再传绝对路径。不要为了拼配置路径先额外搜索 `ok-cosmic.json`。
+- **参数不确定时**，先执行 `python3 <script> --help` 确认调用方式；如果 `--help` 仍不足以确认，就停止并报告。
+- **凡是带子命令的脚本，`--config` 等全局参数统一放在子命令前，按 `python3 <script> --config ok-cosmic.json <subcommand> ...` 组织。**
+- `entityId` 只允许来自"用户明确给出的准确英文标识"或"元数据脚本确认出的真实标识"；来源不明时，先查 `cosmic-form-metadata.py`，不得直接执行基础资料查询。
+- **字段生成代码强制验证**：只要要生成/修改代码，且已知目标单据/表单（`formId` 或 `billName`），凡涉及字段（无论用户给的是中文名还是英文标识），都必须先用 `cosmic-form-metadata.py` 验证字段是否存在、字段类型、所属实体（表头/表体/子表体/容器）和特殊取值规则（如 `BasedataPropField` 的 `refType`、`LargeTextField` 的 `{fieldKey}_tag`、Combo/下拉字段的 Ext 映射）。目标单据/表单不明确时，先确认目标，不要直接把用户给的字段写进代码。
+- **枚举/下拉选项值禁猜 [A1.8]**：使用 ComboField / 下拉字段的具体选项值前，必须先查 `cosmic-form-metadata.py` 的 Ext 列确认真实映射，详见 [constraints.md](rules/constraints.md) A1.8。
+- 需要确认多个字段时，优先一次性合并到同一次元数据查询里；不要逐个字段重复调用脚本。
+- **并行调用**：`cosmic-form-metadata.py`（字段/枚举验证）与 `cosmic-api-knowledge.py`（类/方法签名验证）查询不同数据源、互不依赖，应在同一轮并行发起。同理，多个 `detail` 查询、多个文件读取也应并行。唯一例外：`cosmic-basedata-query.py` 依赖 `entityId` 确认结果，必须串行等待。
+- **元数据批量查询**：`cosmic-form-metadata.py` 的 `formIdOrName` 位置参数支持逗号分隔多个查询目标（如 `get sal_order,ap_finapbill,物料`），含中文的自动走 billName、英文标识走 formId，脚本内部通过 `ThreadPoolExecutor` 并发请求（最多 4 线程），结果按原始顺序拼接输出。跨单据场景（如下推、对比源单与目标单字段）优先使用批量查询，减少脚本调用次数。
+- 查询超时或远端失败时，只能基于当前会话里已确认的字段、`refType`、`entityId`、接口返回继续；若本次查询结果是继续前提，则停止。
+- 若 Traceback 明确指向 Skill 脚本实现问题，立即停止并报告命令与错误摘要；不要绕过验证继续生成依赖该事实的代码。
+- 只有在用户已修正配置/环境，或本次明确修改了查询条件后，才允许重试同类脚本；不要原样重复执行。
+
+### 项目级配置文件 (`ok-cosmic.json`)
+
+脚本依赖 `ok-cosmic.json` 获取数据库路径及 API 地址。若需模板可参考 `<SKILL_ROOT>/setup/ok-cosmic.json`。
+
+- **显式指定**: 调用脚本时建议指定 `--config <路径>`。未指定时读取**当前执行目录**下的 `ok-cosmic.json`；不存在则报错。
+- **在线查询配置**: 三个在线查询脚本统一走 `route.apiUrl`（`runtime/route`，URL 中包含 `openApiSign`）/ `route.timeoutSeconds`；脚本内部通过 `data.type=meta|basedata|extpoint` 路由。
+- **统一路由请求体**: 元数据 `data.type=meta` + `reqData.entityId/formId/billName/full`；基础资料 `data.type=basedata` + `reqData.entityId/numberOrName/full`；业务拓展点 `data.type=extpoint` + `reqData.keyword`。
+
+## 扩展代码库探索（Extension Repos Fallback）
+
+当决策矩阵未命中、`rules/cheat-sheet.md` 和 `assets/snippets/` 也无覆盖时，允许回落到用户配置的扩展代码库进行实现参考。
+
+- **触发条件**（需同时满足）：
+  - 决策矩阵未命中，且 `cheat-sheet.md` / `assets/snippets/` 均无覆盖；
+  - 且 **当前项目中没有具体实现可以满足需求**（在用户项目搜相似插件/业务无果，或已有实现与当前需求不匹配）。
+- **不触发条件**：`ok-cosmic.json` 未配置 `extensionRepos` 或数组为空时，跳过本流程，继续按 fallback 第 1-3 步处理。
+- **探索方式**：
+  - 从当前需求提取关键词：插件类型、事件方法名、实体/字段标识、业务关键词。
+  - 在 `extensionRepos` 所列路径下用 `grep_code` 或 Search Agent 搜索 `.java` 文件；多个路径并行探索。
+  - 优先阅读匹配类的整体结构和相关事件方法，了解真实项目中的写法习惯。
+- **结果使用原则**：
+  - 扩展代码库仅作为**实现参考**，不等同于 ok-cosmic 推荐写法。
+  - 生成代码时仍须遵守 A 层硬约束（`rules/constraints.md`、`rules/anti-patterns.md`）与 B 层编码偏好（`rules/coding-preferences.md`）。
+  - 若扩展代码与 ok-cosmic 规范冲突，**以 ok-cosmic 规范为准**；只借鉴参考项目的业务组装方式与字段暴露结构。
+  - 若扩展代码库中未搜到相关实现，回落到 fallback 第 3 步（`cosmic-api-knowledge.py search`）后再向用户确认。
+
+## 代码生成后自动校验（Post-Check）
+
+修改任何苍穹 `.java` 文件后，必须执行：
+
+`python3 <SKILL_ROOT>/scripts/cosmic-post-check.py <生成的文件或目录> --fix-hint`
+
+- `ERROR` → 必须修复并复检；`WARNING` → 优先修复；`INFO` → 治理参考，不阻断。
+- Gradle 项目编译成功后仍串联 post-lint 静态校验，以综合结果为准；非 Gradle 直接回退静态 lint。
+- 最多连续 3 轮"修复 → 复检"；3 轮后仍有 `ERROR`，向用户报告。
+- 规则 ID 映射、修复示例、历史项目解释口径见 [rules/post-check.md](rules/post-check.md)。
+
+## 规则分层
+
+`ok-cosmic` 的规则默认分为三层，避免把"新代码默认要求"和"历史代码治理方向"混为一谈：
+
+- **A 层：硬约束 / 交付红线**
+  - 直接影响正确性、事件时机、插件上下文、事实准确性。
+  - 新生成代码必须满足；若命中这层问题，默认阻断交付。
+  - 主要参考：`rules/constraints.md`、`rules/anti-patterns.md`、`rules/platform-baseline.md`
+- **B 层：推荐项 / 新代码默认写法**
+  - 代表团队希望新代码优先采用的封装、工具类、查询方式和实现风格。
+  - 新代码默认尽量遵守；历史存量代码若能稳定运行，不因未完全满足而直接判错。
+  - 主要参考：`rules/coding-preferences.md`
+- **C 层：目标态治理 / 渐进优化**
+  - 代表团队长期希望逐步收敛的治理方向，例如补验证来源注释、统一异常体系、进一步减少原生样板。
+  - 适合用于重构、专项治理、模板升级，不作为当前默认一次性交付阻断条件。
+  - 主要参考：`rules/coding-preferences.md`、`rules/post-check.md`
+
+处理历史项目时，优先识别 **A 层问题**；对 **B/C 层** 问题应区分"当前可接受的历史写法"和"建议后续收敛的目标写法"。
+
+## 子文件引用
+
+以下文件提供详细规则，AI 应在需要时按需加载；优先先读文档开头的 `TL;DR` 摘要，再决定是否展开全文：
+
+| 层级 | 文件 | 用途 |
+|------|------|------|
+| A 层 | [constraints.md](rules/constraints.md) | 硬约束 / 交付红线 |
+| A 层 | [a-layer-rules.json](rules/a-layer-rules.json) | 规则 ID 配置（单一可信源） |
+| A 层 | [anti-patterns.md](rules/anti-patterns.md) | 禁忌清单（自动检测部分 → `scene_check`） |
+| 路由 | [intent-routing.md](rules/intent-routing.md) | 自然语言意图 → 技术场景路由 |
+| 路由 | [decision-matrix.md](rules/decision-matrix.md) | 完整决策矩阵与未命中兜底 |
+| 参考 | [event-lifecycle.md](references/adv/event-lifecycle.md) | 插件事件生命周期图 |
+| B/C 层 | [coding-preferences.md](rules/coding-preferences.md) | 编码偏好 + STYLE/RESOURCE/VERIFY 速查 |
+| 参考 | [platform-baseline.md](rules/platform-baseline.md) | 平台总规范摘要（guidance-only） |
+| 速查 | [cheat-sheet.md](rules/cheat-sheet.md) | 高频 API（无需脚本验证） |
+| 校验 | [post-check.md](rules/post-check.md) | 生成后自动校验规则（A/B/C 分层） |
+| 片段 | [snippets-guide.md](assets/snippets/snippets-guide.md) | 场景化代码片段（推荐 / 原生两层） |

package/vendor/kingdee-skills/ok-cosmic/agents/openai.yaml

@@ -0,0 +1,17 @@
+interface:
+  display_name: "ok cosmic"
+  short_description: "封装优先的苍穹开发主 skill"
+  default_prompt: |
+    使用 $ok-cosmic 来实现或审查苍穹插件代码。严格遵循以下流程：
+    0. 首先执行 cosmic-config-check.py 完成配置预检；ERROR 必须停止，WARNING 需告知用户受限能力
+    1. 先查 SKILL.md 决策矩阵确定插件类型和对应模板
+    2. 读 references/*.md 确认事件边界和适用场景
+    3. 读 assets/*.java 模板沿用已有骨架，小场景查 snippets 映射表
+    4. 首次调用任何脚本前，先执行 --help 读取调用契约，定好命令模板后再填参数执行（三步首调协议）
+    5. 字段不确定先查 cosmic-form-metadata.py；entityId 来源不明先查 cosmic-form-metadata.py（查 refType 或按中文名确认英文标识），严禁凭经验猜 entityId；枚举/下拉选项值必须查 --show-detail 的 Ext 列确认（A1.8 硬约束），严禁凭空编造；SDK 签名不确定先查 cosmic-api-knowledge.py
+    6. 只有"插件类型 + 事件方法 + 字段/基础资料/签名 + 枚举值来源"都确认后，才开始生成代码
+    7. 代码生成后，执行 cosmic-post-check.py 自动校验，有 ERROR 须修复后重验
+    核心原则：封装优先（kd-cd-cosmic-commons），原生兜底；严禁凭记忆猜测 API 签名。
+
+policy:
+  allow_implicit_invocation: true

package/vendor/kingdee-skills/ok-cosmic/assets/BatchImportPluginTemplate.java

@@ -0,0 +1,93 @@
+package kd.cd.common;
+
+import kd.bos.entity.api.ApiResult;
+import kd.bos.entity.plugin.ImportLogger;
+import kd.bos.form.plugin.impt.BatchImportPlugin;
+import kd.bos.form.plugin.impt.ImportBillData;
+
+import java.util.Iterator;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 批量导入插件骨架模板（原生 BatchImportPlugin）。
+ * 该类仅用于示例写法，生成后请按实际业务删除无用事件并替换占位常量。
+ */
+public class BatchImportPluginTemplate extends BatchImportPlugin {
+
+    /**
+     * 触发时机: 在需要了解当前插件可访问上下文能力时调用。
+     * 参数要点: 无入参；仅展示当前插件可通过 this. 访问的方法能力。
+     * 典型用途: 作为模板提示，指导在各事件内选择正确的上下文 API。
+     */
+    private void getContextSample() {
+        // this.getContext();
+        // this.getLogger();
+        // this.getBatchSize();
+        // this.refreshHeartbeat();
+        // this.call();
+    }
+
+    private static final int BATCH_SIZE = 200;
+    private static final String FIELD_BILL_STATUS = "billstatus";
+    private static final String FIELD_BILL_NO = "billno";
+    private static final String FIELD_NAME = "name";
+
+    // ===== 核心事件 =====
+
+    /**
+     * 触发时机: 导入引擎初始化批处理策略时。
+     * 参数要点: 返回值决定单批处理行数。
+     * 典型用途: 控制批量导入吞吐、内存占用与事务规模。
+     */
+    @Override
+    protected int getBatchImportSize() {
+        super.getBatchImportSize();
+        return BATCH_SIZE;
+    }
+
+    /**
+     * 触发时机: 导入引擎判断是否强制批处理时。
+     * 参数要点: 返回 true 表示按批次执行。
+     * 典型用途: 大数据量导入时强制走批处理模式。
+     */
+    @Override
+    protected boolean isForceBatch() {
+        super.isForceBatch();
+        return true;
+    }
+
+    /**
+     * 触发时机: 每批数据执行保存时。
+     * 参数要点:
+     * - rowdatas: 当前批次行数据。
+     * - logger: 导入日志记录器，用于记录行级失败原因。
+     * 典型用途: 批量校验、过滤非法数据、自定义保存逻辑。
+     * 返回值: 返回 ApiResult 表示自定义处理结果，返回 null 由框架继续默认保存流程。
+     */
+    @Override
+    protected ApiResult save(List<ImportBillData> rowdatas, ImportLogger logger) {
+        super.save(rowdatas, logger);
+        Iterator<ImportBillData> iterator = rowdatas.iterator();
+        while (iterator.hasNext()) {
+            ImportBillData data = iterator.next();
+            Map<String, Object> rowData = data.getData();
+            Object name = rowData == null ? null : rowData.get(FIELD_NAME);
+            String billStatus = rowData == null ? null : String.valueOf(rowData.get(FIELD_BILL_STATUS));
+            String billNo = rowData == null ? null : String.valueOf(rowData.get(FIELD_BILL_NO));
+            if (name == null) {
+                logger.log(data.getStartIndex(), "名称不能为空").fail();
+                iterator.remove();
+                continue;
+            }
+            if ("A".equalsIgnoreCase(billStatus)) {
+                logger.log(data.getStartIndex(), "单据" + billNo + "为暂存状态，不允许导入").fail();
+                iterator.remove();
+            }
+        }
+        if (rowdatas.isEmpty()) {
+            return ApiResult.fail("IMPORT_EMPTY", "当前批次无可保存数据");
+        }
+        return null;
+    }
+}

package/vendor/kingdee-skills/ok-cosmic/assets/BillPlugInTemplate.java

@@ -0,0 +1,156 @@
+package kd.cd.common;
+
+import kd.bos.dataentity.resource.ResManager;
+import kd.bos.entity.datamodel.events.PropertyChangedArgs;
+import kd.bos.form.control.events.ItemClickEvent;
+import kd.bos.form.events.AfterDoOperationEventArgs;
+import kd.bos.form.events.BeforeDoOperationEventArgs;
+import kd.cd.common.plugin.AbstractBillPlugInExt;
+import kd.cd.core.util.CharSequenceUtils;
+
+import java.math.BigDecimal;
+import java.util.EventObject;
+
+/**
+ * 单据界面插件骨架模板（原生 AbstractBillPlugIn）。
+ * 该类仅用于示例写法，生成后请按实际业务删除无用事件并替换占位常量。
+ *
+ * @template BillPlugInTemplate
+ * @extends AbstractBillPlugInExt (kd.cd.common.plugin)
+ * @highFreqEvents afterLoadData, propertyChanged, beforeDoOperation, afterDoOperation, itemClick
+ * @medFreqEvents registerListener, beforeF7Select, click
+ * @relatedDocs references/adv/plugin-base.md, references/base/plugin/plugin-bill.md
+ */
+public class BillPlugInTemplate extends AbstractBillPlugInExt {
+
+    /**
+     * 触发时机: 在需要了解当前插件可访问上下文能力时调用。
+     * 参数要点: 无入参；仅展示当前插件可通过 this. 访问的方法能力。
+     * 典型用途: 作为模板提示，指导在各事件内选择正确的上下文 API。
+     */
+    private void getContextSample() {
+        // this.getView();
+        // this.getModel();
+        // this.getPageCache();
+    }
+
+    private static final String TOOLBAR_KEY = "tbmain";
+    private static final String BTN_SYNC = "btn_sync";
+    private static final String OP_KEY_SAVE = "save";
+    private static final String FIELD_QTY = "qty";
+    private static final String BASEDATAFIELD = "basedatafield";
+    private static final String RES_APP_ID = "kd-cd-common-template";
+
+    /**
+     * 触发时机: 表单初始化完毕，所有事件监听注册前。
+     * 参数要点:
+     * - `EventObject e`: 通用事件对象。
+     * 典型用途: 注册菜单、按钮等交互监听。
+     */
+    @Override
+    public void registerListener(EventObject e) {
+        super.registerListener(e);
+        this.addItemClickListeners(TOOLBAR_KEY);
+        this.addClickListeners(BTN_SYNC);
+        this.addBeforeF7SelectListeners(BASEDATAFIELD);
+    }
+
+    /**
+     * 触发时机: 单据数据从数据库加载完毕后。
+     * 参数要点:
+     * - `EventObject e`: 通用事件对象。
+     * 典型用途: 基于历史数据做界面初始化。
+     */
+    @Override
+    public void afterLoadData(EventObject e) {
+        super.afterLoadData(e);
+        String billNo = this.getValue("billno");
+        if (CharSequenceUtils.isNotEmpty(billNo)) {
+            this.getView().showTipNotification(String.format(
+                    ResManager.loadKDString("加载单据：%s", "BillPlugInTemplate_0", RES_APP_ID),
+                    billNo
+            ));
+        }
+    }
+
+    /**
+     * 触发时机: 用户点击工具栏或菜单项时。
+     * 参数要点:
+     * - `ItemClickEvent evt`: 可通过 `getItemKey()` 获取菜单标识。
+     * 典型用途: 处理工具栏动作。
+     */
+    @Override
+    public void itemClick(ItemClickEvent evt) {
+        super.itemClick(evt);
+        if (BTN_SYNC.equals(evt.getItemKey())) {
+            this.getView().showTipNotification(ResManager.loadKDString("已触发同步动作", "BillPlugInTemplate_1", RES_APP_ID));
+        }
+    }
+
+    /**
+     * 触发时机: 用户点击表单控件时。
+     * 参数要点:
+     * - `EventObject evt`: `getSource()` 可获取控件对象。
+     * 典型用途: 处理按钮、链接等控件交互。
+     */
+    @Override
+    public void click(EventObject evt) {
+        super.click(evt);
+        String clickKey = getClickKey(evt);
+        if (BTN_SYNC.equals(clickKey)) {
+            this.getView().showTipNotification(ResManager.loadKDString("按钮点击处理完成", "BillPlugInTemplate_2", RES_APP_ID));
+        }
+    }
+
+    /**
+     * 触发时机: 单据操作执行前。
+     * 参数要点:
+     * - `BeforeDoOperationEventArgs e`: 通过 `(AbstractOperate) e.getSource()` 获取操作对象。
+     * 典型用途: 做轻量前置校验，必要时取消操作。
+     */
+    @Override
+    public void beforeDoOperation(BeforeDoOperationEventArgs e) {
+        super.beforeDoOperation(e);
+        String opKey = getOpKey(e);
+        if (OP_KEY_SAVE.equals(opKey)) {
+            BigDecimal qty = this.getValue(FIELD_QTY);
+            if (qty != null && qty.compareTo(BigDecimal.ZERO) <= 0) {
+                e.setCancel(true);
+                this.getView().showErrorNotification(ResManager.loadKDString("数量必须大于 0", "BillPlugInTemplate_3", RES_APP_ID));
+            }
+        }
+    }
+
+    /**
+     * 触发时机: 单据操作执行后。
+     * 参数要点:
+     * - `AfterDoOperationEventArgs e`: 可读取操作结果与操作标识。
+     * 典型用途: 做提示、刷新或后续联动。
+     */
+    @Override
+    public void afterDoOperation(AfterDoOperationEventArgs e) {
+        super.afterDoOperation(e);
+        this.getView().showTipNotification(String.format(
+                ResManager.loadKDString("操作完成：%s", "BillPlugInTemplate_4", RES_APP_ID),
+                e.getOperateKey()
+        ));
+    }
+
+    /**
+     * 触发时机: 字段值写入模型后。
+     * 参数要点:
+     * - `PropertyChangedArgs e`: 可读取字段标识与变更值。
+     * 典型用途: 做字段联动与提示。
+     */
+    @Override
+    public void propertyChanged(PropertyChangedArgs e) {
+        super.propertyChanged(e);
+        if (FIELD_QTY.equals(e.getProperty().getName())) {
+            Integer changedNewValue = getChangedNewValue(e);
+            this.getView().showTipNotification(String.format(
+                    ResManager.loadKDString("数量已更新为：%s", "BillPlugInTemplate_5", RES_APP_ID),
+                    changedNewValue
+            ));
+        }
+    }
+}