@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shundoo-ai/dsh-cosmic",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "description": "苍穹助手：金蝶云苍穹ERP的开发与数据分析，涵盖表单元数据建模、插件开发与热部署、数据可视化报告。",
   "keywords": [
     "dsh",

package/skills/cosmic-build/LOCAL-PATCHES.md

@@ -9,27 +9,25 @@
 
 | 项 | 值 |
 |---|---|
-| 本次对齐的上游版本 | **0.0.326**（`builtin-skills/.builtin-version`），文件日期 2026-10-19（金蝶灵基 app **1.8.0**，build 2610172146，2026-10-17 安装） |
-| 上一次对齐 | **0.0.299**（2026-09-29） |
+| 本次对齐的上游版本 | **0.0.343**（`builtin-skills/.builtin-version`），文件日期 2026-11-06（金蝶灵基 app **1.9.1**，build 2611032038，2026-11-03 安装；技能 2026-11-06 09:54 解压） |
+| 上一次对齐 | **0.0.326**（2026-10-19）；其间 0.0.338 曾调研后跳过 |
 | 更早的参照基线 | `~/.lingeebuild/config/builtin-skills/app-build`（**0.0.277**，2026-08-28，已过期） |
 | 上游解压位置（已变） | **`~/.lingeebuild/profiles/v1/<hash>/config/builtin-skills/app-build`** —— 灵基 1.8.0 起 skill 按 profile 隔离解压；旧的全局 `~/.lingeebuild/config/builtin-skills` 不再更新 |
 | 上游目录布局 | `app-build/`（英文 canonical）+ `app-build/.locales/zh/`（中文覆盖层） |
 | 本 preset 布局 | 单树：`skills/cosmic-build/`（= 上游 zh 覆盖层拍平，无 `.locales/`） |
 
-### 0.1 ⏸ 待同步：上游 0.0.338（**已调研完毕，暂缓执行**）
+### 0.1 ✅ 已同步：上游 **0.0.343**（2026-11-06）
 
-> 2026-10-30 用户决定：「过几天，等灵基更新稳定了再同步」。以下为已完成的前置调研，**下次直接照此执行，无需重新考古**。
+> 2026-10-30 曾暂缓；2026-11-06 用户确认同步并当日完成。**执行记录见 §5.2**。
+> 版本线：0.0.277（8/28）→ **0.0.299** ✅ → **0.0.326** ✅ → 0.0.338（跳过）→ **0.0.343** ✅（当前）
 
-| 项 | 结论 |
+| 项 | 结论（0.0.343 带来的） |
 |---|---|
-| 上游版本 | **0.0.338**（金蝶灵基 app **1.8.4**，build 2610261914，2026-10-26 安装；技能 2026-10-29 解压） |
-| 相对 0.0.326 的改动 | **0 个新文件**；**78 个文件改动** = `.md` 33 + `.py` 45（其中 **19 个是测试**，26 个功能文件） |
-| 改动分布 | `scripts/` 21 · `cosmic-meta-api` 20 · `cosmic-meta-modifier` 14 · `references/` 10 · 其余零散 |
-| 是否含新功能 | **否** —— CHANGELOG 条目与 0.0.326 完全相同（最新仍 2026-10-13）；命令数仍 **197**（+我们 7 = 204）；**无新端点** |
-| 我们的 11 项补丁上游做了吗 | **全部未做**（`#1/#2/#3/#4/#5/#6/#7/#8/#10/#16/#17` 均仍缺；`kd_auth` 仍 `usertype/Mobile`，`kd_env_loader` 仍 `default="ierp"` 且无 password） |
-| 补丁重贴风险 | **高** —— 10 个补丁落点文件**全部被上游改过**（`run.py`/`_http_client.py`/`appconfig_load.py`/`kd_env_loader.py`/`kd_auth.py`/`kd_token_cache.py`/`config.py`/`cosmic_api.py`/`field_decorator.py`/`pdm_client.py`） |
-| token 改名 | **仍需** —— 新 zh 中 `{APP_BUILD_ROOT}` 74 处 / `{ROOT_DIR}` 61 处混用 |
-| 恢复时起点 | 备份基线：当前树 = 0.0.326（git 干净）；旧备份 `/tmp/cosmic-build.bak-2026-10-19` 仅供参考，**同步前重新备份** |
+| 相对 0.0.326 的改动 | **17 个新文件** + **211 个文件改动**（`.py` 100 其中 48 测试 / `.md` 102 / `.json` 6 / `.java` 3） |
+| 新功能 | ① 新命令 **`removeReportColumn`**（197 → **198**）；② **DCS 代码闸门**（`dcs_code_gate.py` + `references/dcs-code-rules.md` + `dcs-rule-catalog.json`，按 Sonar/SpotBugs/Fortify/CVE-KD 规则交付前自检 Java 插件）；③ `run_java_tests.py`；④ `configure_list.py`；⑤ **报表场景知识**（`knowledge/cosmic/platform/scenes/report/` 现共 16 篇） |
+| 实质修复 | 插件交付链路整条 + `cmd_apps/formactions/forms/listui/metaops/plugins/properties/rules` + `report_ops`/`validators`/`property_reroute`/`data_model_emit` |
+| 新增兄弟技能 | `create-image`（技能 16 → 17，**不拷**） |
+| ⚠️ **新机制** | **执行绑定闸门** `scripts/execution_binding.py` —— 同步后必须重新 bootstrap 每个 app-root，见 §5 第 5 步 |
 
 上游会把旧的 R/D/E 管线、`capabilities/`、`cosmic-{requirements,design,executor,testing,code-review}`、
 `nano-coding-impl` 整批删除——那些**不是**本 preset 的本地内容，跟随上游删除即可。
@@ -181,7 +179,7 @@ rsync -a --ignore-existing --exclude '.locales/' "$SRC/." "$DST/"
 # 4) 重贴 §2 的 17 处补丁（先 config.py，再凭据三件套）
 
 # 5) 机械适配
-#    a. {ROOT_DIR} → {ROOT_DIR}（md 与 py 中花括号 token 形态；
+#    a. {APP_BUILD_ROOT} → {ROOT_DIR}（md 与 py 中花括号 token 形态；
 #       注意 py 里还有同名 Python 变量，不要一起改）
 #    b. md 链接标签里的 .locales/zh/ 前缀去掉
 #    c. 确认根 SKILL.md 里 {ROOT_DIR} 与 {python} 的绑定说明仍在
@@ -246,6 +244,12 @@ python3 -m compileall -q $D/scripts $D/skills && echo "compileall OK"
 # 4) 端到端只读冒烟（在工作区根执行，走工作区凭证）
 cd <工作区> && $PY $D/skills/cosmic-meta-api/scripts/cosmic_api.py --stdout queryForms --keyword "过磅"
 # 期望：退出码 0、stdout 为 JSON、stderr 出现 [auth] OK
+
+# 5) ⚠️ 0.0.343 起：重建每个 app-root 的执行绑定（否则带 --app-root 的命令报 SKILL_REVISION_MISMATCH）
+#    根因：context.json 存了技能树修订指纹（SKILL.md + scripts/skills/schemas 下全部 .py/.json 的 SHA256），
+#          rsync + 打补丁后指纹必变 ⇒ execution_binding.validate_execution_binding() 拒绝执行。
+$PY $D/scripts/bootstrap_cosmic_context.py --project-root <app-root> --resolve-existing-app
+# 期望：输出含 revision=<新指纹>、退出码 0；随后 exportKSQLByTable / getProperties 等恢复正常
 ```
 
 2026-09-29 同步后的实测结果：17/17 补丁通过、compileall 退出码 0、
@@ -256,6 +260,11 @@ markdown 断链 60 条（与上游 KD zh 完全一致，无新增）。
 命令 **204** 个（197 上游 + 7 KSQL）、compileall 退出码 0、`queryForms` 冒烟 `[auth] OK`、
 `exportKSQLByTable` 实调成功（返回 `scriptBase64`）、根 `SKILL.md` 断链 0。
 
+**2026-11-06（0.0.343）同步结果**：补丁 **15/15 检查点通过**、`_API_PATH` **105** 项、
+命令 **205** 个（198 上游 + 7 KSQL，含新 `removeReportColumn`）、compileall 退出码 0、
+`queryForms` / `getProperties` / `getFormSchema` / `exportKSQLByTable` 实调成功、`dataQuery` 取到真实数据、
+重新 bootstrap 后 `SKILL_REVISION_MISMATCH` 消除。
+
 ---
 
 ## 5.1 2026-10-19 同步记录（0.0.299 → 0.0.326）
@@ -285,6 +294,26 @@ markdown 断链 60 条（与上游 KD zh 完全一致，无新增）。
 
 ---
 
+## 5.2 2026-11-06 同步记录（0.0.326 → 0.0.343）
+
+| 步骤 | 实际执行 |
+|---|---|
+| 备份 | `cp -a` → `/tmp/cosmic-build.bak-2026-11-06`（65M）；补丁母本另存 `/tmp/sync343/head_*.py` |
+| 步骤1 | rsync `zh` `--delete`（exclude 同 §5.1：`erpdb/`、`cosmic-vibe-coding/`、`config.json`、`tenant.json`、entity-download 3 文件、`LOCAL-PATCHES.md`、`sdk/manifests/`）→ 6621 文件 |
+| 步骤2 | rsync canonical `--ignore-existing --exclude .locales/` → **7040** 文件 |
+| 步骤3 | AST 重算滞后/漂移文件 **35** 个并用 canonical 覆盖 → 与 canonical **AST 差异 0** |
+| 步骤4 | 重贴 17 处补丁（**15 个检查点全过**）。锚点均未变；`#2` 按"先替换 3 处 `resp.read()`、**再**插入 `_read_response`"的顺序贴，避开递归自伤 |
+| 步骤5 | a) `{APP_BUILD_ROOT}` → `{ROOT_DIR}`：md **77** + py **6**（89 个 py 变量不动）；b) md 的 `.locales/zh/` 清理 **16** 处；c) SKILL.md 补回 token 同义注 |
+| **步骤6（0.0.343 新增，必做）** | **重新 bootstrap**：`bootstrap_cosmic_context.py --project-root <app-root> --resolve-existing-app`。否则 0.0.343 的执行绑定闸门报 `SKILL_REVISION_MISMATCH`（`context.json` 里的技能树指纹因 rsync+打补丁而失效），**所有带 `--app-root` 的命令被拦** |
+
+**校验**：命令 **205**（198 上游 + 7 KSQL，含新 `removeReportColumn`）、`_API_PATH` **105**、compileall 0、
+`queryForms` / `getProperties` / `getFormSchema` / `exportKSQLByTable` / `dataQuery` 全部实调通过。
+
+**本次带入的上游新能力**：DCS 代码闸门（`dcs_code_gate.py` + `dcs-code-rules.md` + `dcs-rule-catalog.json`）、
+`run_java_tests.py`、`configure_list.py`、报表场景知识（`scenes/report/` 共 16 篇）、插件交付链路整条修复。
+
+---
+
 ## 6. 已知遗留（不影响运行）
 
 1. **35 个上游 dev 测试**里有 `.locales/zh/...` 硬路径假设，在单树布局下会失败；

package/skills/cosmic-build/SKILL.md

@@ -6,19 +6,22 @@ description: 创建或修改金蝶云苍穹表单、字段、规则、操作、
 # App Build
 
 通过已发布的 CLI 交付用户要求的苍穹应用修改。选择下方最具体的入口，
-只加载当前问题需要的内容，并保留全部明确业务要求。
+只加载当前问题需要的内容，并保留全部明确业务要求。沿当前语言入口的链接读取，
+不为确认同一契约再加载另一语言版本。
 
 表单及其当前设计保存在苍穹服务端。`appRoot` 是本地应用绑定和导出产物的目录，
 不是线上表单清单。修改已有表单时，读取下方对应领域入口，将已提供的 `appRoot`
 和用户使用的表单名称直接传给命令。本地文件或 archive 中没有记录，不证明线上表单不存在。
 
-`{ROOT_DIR}` 是本入口附带的技能包目录（本地补丁：上游 0.0.326 用 `APP_BUILD_ROOT` 这一同名 token，本 preset 统一为 `{ROOT_DIR}`；历史文本中的 `APP_BUILD_ROOT` 与本变量同义）。选定命令的参数尚不明确时，读取其本地契约：
+`{ROOT_DIR}` 是本入口附带的技能包目录（本地补丁：上游 0.0.343 用 `APP_BUILD_ROOT` 这一同名 token，本 preset 统一为 `{ROOT_DIR}`；历史文本中的 `APP_BUILD_ROOT` 与本变量同义）。先按领域入口选命令；没有匹配的已发布命令时，用 `catalog --search <能力>` 查找，不猜命令名。选定命令的参数尚不明确时，读取其本地契约：
 
 ```text
 {python} {ROOT_DIR}/skills/cosmic-meta-api/scripts/cosmic_api.py --stdout describeCommand <已选命令>
 ```
 
-返回的 schema 说明命令输入；目标查询由领域命令完成，不通过搜索应用目录完成。
+`describeCommand` 返回 `status: "found"` 时，命令和参数在 `action.command`、`action.arguments`，执行前缀在 `action.execution.argvPrefix`，不是顶层字段。同时遵循 `action.argumentGroups` 的必选/互斥组合、`action.argumentConstraints` 的条件约束和命令可用性；不把一个命令的参数移用到另一个命令。`not_found` 仅表示命令名未发布，不能证明平台不支持该能力。
+
+完整契约读取一次，不用 `head`、`tail` 截断。工具显示截断时用 `--output` 保存，从文件补读缺失内容，保留参数组、条件约束和输入 Schema。stdout/stderr 与失败处理遵循[执行契约](references/execution-contract.md)。目标查询由领域命令完成，不通过搜索应用目录完成。
 
 创建入口负责契约支持的初始状态，未覆盖属性或布局交给对应入口。写命令自行解析准确表单目标；
 只有用户要求发现，或没有表单目标时才进入发现入口。
@@ -28,22 +31,30 @@ description: 创建或修改金蝶云苍穹表单、字段、规则、操作、
 | 当前请求 | 入口 |
 |---|---|
 | 修改下拉菜单项，包括显示名称、说明及顺序 | [skills/cosmic-meta-ui/SKILL.md](skills/cosmic-meta-ui/SKILL.md)：`configureDropdownMenu` 根据菜单项或明确按钮定位菜单，保留绑定的操作定义 |
+| 查询指定模板预置字段 | [skills/cosmic-meta-modeling/SKILL.md](skills/cosmic-meta-modeling/SKILL.md)：只读模板查询分支 |
 | 查找表单或确认所属应用 | [references/form-discovery.md](references/form-discovery.md) |
 | 查询或新建功能分组（BizUnit），包括新建表单明确要求的分组；功能分组不是应用菜单 | [skills/cosmic-meta-modifier/modules/unit/SKILL.md](skills/cosmic-meta-modifier/modules/unit/SKILL.md) |
 | 将表单移动到其他功能分组（不是应用菜单） | [skills/cosmic-meta-modifier/SKILL.md](skills/cosmic-meta-modifier/SKILL.md) |
 | 创建表单、实体、基础资料或应用菜单（不是功能分组） | [skills/cosmic-meta-modeling/SKILL.md](skills/cosmic-meta-modeling/SKILL.md) |
 | 新增/删除字段或分录；继承、复制、扩展或移动已有表单 | [skills/cosmic-meta-modifier/SKILL.md](skills/cosmic-meta-modifier/SKILL.md) |
-| 修改字段/控件/分录标识或属性、必填、默认值、拆分表或页签操作 | [skills/cosmic-meta-modifier/modules/property/SKILL.md](skills/cosmic-meta-modifier/modules/property/SKILL.md) |
-| 配置计算或条件字段行为 | [skills/cosmic-meta-modifier/modules/rule/SKILL.md](skills/cosmic-meta-modifier/modules/rule/SKILL.md) |
+| 修改字段/控件/分录标识或属性、必填/条件必填、默认值、拆分表或页签操作 | [skills/cosmic-meta-modifier/modules/property/SKILL.md](skills/cosmic-meta-modifier/modules/property/SKILL.md) |
+| 配置计算、联动或表单规则（条件必填走上方属性入口） | [skills/cosmic-meta-modifier/modules/rule/SKILL.md](skills/cosmic-meta-modifier/modules/rule/SKILL.md) |
 | 配置保存、提交或其他操作校验 | [skills/cosmic-meta-modifier/modules/operation/SKILL.md](skills/cosmic-meta-modifier/modules/operation/SKILL.md) |
 | 新增可见控件或面板；修改布局、位置或容器外观 | [skills/cosmic-meta-ui/SKILL.md](skills/cosmic-meta-ui/SKILL.md)；明确交互的操作先使用操作入口 |
-| 配置列表视图的列、搜索字段、过滤条件或排序 | [skills/cosmic-meta-modifier/references/list-filter-modification.md](skills/cosmic-meta-modifier/references/list-filter-modification.md) |
+| 配置列表列、汇总/零值显示、格式、搜索、过滤或排序 | [skills/cosmic-meta-modifier/references/list-filter-modification.md](skills/cosmic-meta-modifier/references/list-filter-modification.md) |
 | 修改报表元数据、插件注册、元数据脚本或其他已有元数据 | [skills/cosmic-meta-modifier/SKILL.md](skills/cosmic-meta-modifier/SKILL.md) |
+| 根据在线实体生成或同步物理模型、表结构、KSQL 建表或索引脚本 | [skills/cosmic-meta-api/modules/pdm/SKILL.md](skills/cosmic-meta-api/modules/pdm/SKILL.md)：使用平台生成结果；实体不可用时说明原因，不推测字段 |
 | 查看、比较或还原元数据版本 | [skills/cosmic-meta-api/apis/meta_log.md](skills/cosmic-meta-api/apis/meta_log.md) |
 | 编写或修改 Java 插件源码，包括元数据无法表达的后端行为 | [references/java-plugin-delivery.md](references/java-plugin-delivery.md) |
 | 将已有操作发布为 OpenAPI | [skills/openapi-gen/SKILL.md](skills/openapi-gen/SKILL.md) |
 | 注册、查询或管理 MCP 服务（open_mcp_ext） | [skills/mcp-server/SKILL.md](skills/mcp-server/SKILL.md) |
 
+用户明确要求 Java 插件或已有源码修改时，可独立进入该入口；只读取行为需要的页面、实体或操作事实。
+
+本地 `.dym` 文件不等于在线实体：PDM 命令不能直接转换此文件。不得推测生成 DDL、
+索引、隐含字段或类型。需要可访问且版本匹配的平台实体或平台生成的权威物理模型；
+比较之前先说明版本差异。
+
 自定义苍穹前端页面使用 kd-frontend-development；非苍穹应用使用对应的
 standalone 或 site 技能。
 
@@ -62,7 +73,7 @@ standalone 或 site 技能。
   [references/application-context.md](references/application-context.md)。
 - CLI 回执、写入验证、未知状态、删除和本地运行状态遵循
   [references/execution-contract.md](references/execution-contract.md)。
-- 只有所选元数据入口无法表达剩余行为时才进入 Java。
+- 用户明确要求 Java，或所选元数据入口无法表达剩余行为时，进入 Java。
 - 用户要求运行态验证，或诊断/修复运行报错时调用外部运行工具；优先使用可用的 `agent_browser`。
 - 只询问会实质改变业务结果的决定。
 
@@ -70,9 +81,11 @@ standalone 或 site 技能。
 
 先按选定入口实施。prepare 给出的完成输入路径是实施后要创建的文件，开始时不存在是正常状态。`TEST_ENVIRONMENT_HANDOFF` 由写入后的原生收口器生成，不在实施前到其他任务或工作树中寻找。
 
-消费已绑定的需求/前阶段产物一次，按“结构、静态属性、规则、操作校验、无法用元数据表达的行为”整理尚未完成的效果。选择每个效果的最小已发布 writer，输入完整时直接执行；仅加载命中的专题，独立读取可并行。同一表单的规则用已发布批量命令，属性批量保持其原生契约，避免逐项重新发现身份。
+消费已绑定的需求/前阶段产物一次，保留每项未完成要求。新建时先加载建模及结构专题，结构验证后再加载剩余属性、规则和操作细节。只有后续要求会决定初始结构、引用关系、初始必填或创建参数时，才提前处理；延后加载不等于延后必要业务决定或遗漏要求。
 
-复用 writer 返回的准确身份和验证回执；成功写入后不再查询无关候选、不重读同一说明、不为交付重做验证。参数错误按返回的准确形状修复；类型/能力边界错误直接切换该行为所属路线，避免在多个命令间摇摆。回执只证明它实际检查的内容：逐行必填不等于最少行数，设计态规则保存不等于浏览器运行通过。有运行验证请求时使用可用的 `agent_browser`；一次打开表单与检查默认值属于该行为的冒烟验证，不能冒充范围外测试阶段。
+为剩余事项选择最小已发布 writer。输入与契约已知的操作可在同一模型回合安排，独立读取可并行；同一表单优先使用原生属性/规则批量命令。共享表单的写入保持串行，并逐条检查回执；依赖前序身份或结果的命令等待其验证完成。失败边界遵循执行契约。
+
+复用 writer 返回的准确身份和验证回执；成功写入后不再查询无关候选、不重读同一说明、不为交付重做验证。参数错误按返回的准确形状修复。确定性的准备失败先解决共同原因，再继续该批次；不为通过校验改写已选应用绑定。类型/能力边界错误直接切换该行为所属路线，避免在多个命令间摇摆。回执只证明它实际检查的内容：逐行必填不等于最少行数，设计态规则保存不等于浏览器运行通过。有运行验证请求时使用可用的 `agent_browser`；一次打开表单与检查默认值属于该行为的冒烟验证，不能冒充范围外测试阶段。
 
 ## 完成条件
 
@@ -94,3 +107,5 @@ standalone 或 site 技能。
 所有明确要求都有验证证据或明确未完成边界，且不存在写后未知状态时任务完成。
 已验证无变化时可以直接说明现状，不重复写入。仍可执行的实现工作不属于“未完成边界”；
 必须继续完成，只有缺少具体业务决定或能力确实不支持时才能停下。
+
+具名 Python 辅助脚本使用对应专题中已提供的命令；参数不明确时查看该脚本的 `--help`。辅助脚本不是 `cosmic_api.py` 的子命令。

package/skills/cosmic-build/examples/java-rules/CosmicReportAggregation.java

@@ -1,35 +1,44 @@
 import kd.bos.algo.DataSet;
-import kd.bos.orm.ORM;
 import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.QueryServiceHelper;
 
-/** Inputs are filtered at their owning ORM queries; headers contain exactly one row per id. */
+/** Inputs are filtered at their owning queries; headers contain exactly one row per id. */
 public final class CosmicReportAggregation {
+    private static final String MAIN_ID = "main_id";
+    private static final String ID = "id";
+    private static final String AMOUNT = "amount";
+    private static final String ADD_AMOUNT = "add_amount";
+    private static final String DEDUCT_AMOUNT = "deduct_amount";
+    private static final String BASE_AMOUNT = "base_amount";
+    private static final String SUPPLIER = "supplier";
+    private static final String BILL_DATE = "bill_date";
+
     private CosmicReportAggregation() { }
 
     /** Three form-root queries, with identical permission/business/user scope pushed into each. */
-    public static DataSet query(ORM orm, String algo, String entity, String headerSelect,
+    public static DataSet query(String algo, String entity, String headerSelect,
                                String additionSelect, String deductionSelect, QFilter[] filters) {
-        return aggregate(orm.queryDataSet(algo, entity, headerSelect, filters, null),
-            orm.queryDataSet(algo, entity, additionSelect, filters, null),
-            orm.queryDataSet(algo, entity, deductionSelect, filters, null));
+        return aggregate(QueryServiceHelper.queryDataSet(algo, entity, headerSelect, filters, null),
+            QueryServiceHelper.queryDataSet(algo, entity, additionSelect, filters, null),
+            QueryServiceHelper.queryDataSet(algo, entity, deductionSelect, filters, null));
     }
 
     public static DataSet aggregate(DataSet headers, DataSet additions, DataSet deductions) {
-        DataSet added = additions.groupBy(new String[]{"main_id"}).sum("amount", "add_amount").finish();
-        DataSet deducted = deductions.groupBy(new String[]{"main_id"}).sum("amount", "deduct_amount").finish();
-        DataSet joined = headers.leftJoin(added).on("id", "main_id")
-            .select(new String[]{"id", "supplier", "bill_date", "base_amount"}, new String[]{"add_amount"}).finish()
-            .leftJoin(deducted).on("id", "main_id")
-            .select(new String[]{"id", "supplier", "bill_date", "base_amount", "add_amount"}, new String[]{"deduct_amount"}).finish()
+        DataSet added = additions.groupBy(new String[]{MAIN_ID}).sum(AMOUNT, ADD_AMOUNT).finish();
+        DataSet deducted = deductions.groupBy(new String[]{MAIN_ID}).sum(AMOUNT, DEDUCT_AMOUNT).finish();
+        DataSet joined = headers.leftJoin(added).on(ID, MAIN_ID)
+            .select(new String[]{ID, SUPPLIER, BILL_DATE, BASE_AMOUNT}, new String[]{ADD_AMOUNT}).finish()
+            .leftJoin(deducted).on(ID, MAIN_ID)
+            .select(new String[]{ID, SUPPLIER, BILL_DATE, BASE_AMOUNT, ADD_AMOUNT}, new String[]{DEDUCT_AMOUNT}).finish()
             .select("id,supplier,bill_date,base_amount,case when add_amount is null then 0 else add_amount end as add_amount,case when deduct_amount is null then 0 else deduct_amount end as deduct_amount");
-        return joined.groupBy(new String[]{"supplier"})
-            .sum("base_amount", "base_amount").sum("add_amount", "add_amount").sum("deduct_amount", "deduct_amount")
-            .min("bill_date", "first_date").max("bill_date", "last_date")
-            .countDistinct(new String[]{"id"}, "bill_count").finish();
+        return joined.groupBy(new String[]{SUPPLIER})
+            .sum(BASE_AMOUNT, BASE_AMOUNT).sum(ADD_AMOUNT, ADD_AMOUNT).sum(DEDUCT_AMOUNT, DEDUCT_AMOUNT)
+            .min(BILL_DATE, "first_date").max(BILL_DATE, "last_date")
+            .countDistinct(new String[]{ID}, "bill_count").finish();
     }
 
     /** Direct aggregates avoid materializing/sorting/unioning a DataSet for each supplier. */
     public static DataSet dateBounds(DataSet headers) {
-        return headers.groupBy(new String[]{"supplier"}).min("bill_date", "first_date").max("bill_date", "last_date").finish();
+        return headers.groupBy(new String[]{SUPPLIER}).min(BILL_DATE, "first_date").max(BILL_DATE, "last_date").finish();
     }
 }

package/skills/cosmic-build/examples/java-rules/CosmicReportFilters.java

@@ -1,11 +1,13 @@
 import kd.bos.dataentity.entity.DynamicObject;
 import kd.bos.dataentity.entity.DynamicObjectCollection;
+import kd.bos.entity.property.MulBasedataProp;
 import kd.bos.entity.report.FilterInfo;
 import kd.bos.entity.report.FilterItemInfo;
 import kd.bos.orm.query.QFilter;
 import kd.bos.orm.query.QCP;
 
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.Date;
 import java.util.LinkedHashSet;
 import java.util.List;
@@ -64,11 +66,103 @@ public final class CosmicReportFilters {
     /** Call only after verifying code uniqueness and retaining organization/permission filters. */
     public static QFilter numberFilter(String sourceField, Object selection) {
         List<String> values = numbers(selection);
-        return values.isEmpty() ? null : new QFilter(sourceField + ".number", QCP.in, values.toArray(new String[0]));
+        return values.isEmpty() ? null : new QFilter(sourceField + ".number", QCP.in, values.toArray(new String[values.size()]));
+    }
+
+    // MulBasedataProp 的集合元素是关联表行，fbasedataid 才是业务记录；绝不回退到包装行主键。
+    private static DynamicObject record(DynamicObject value) {
+        if (value == null) throw new IllegalArgumentException("F7 选择项不能为空");
+        boolean hasReference = value.getDynamicObjectType().getProperty(MulBasedataProp.KEY_BASEDATAID) != null;
+        boolean hasShadow = value.getDynamicObjectType().getProperty(MulBasedataProp.KEY_BASEDATAID_ID) != null;
+        if (!hasReference && !hasShadow) return value;
+        Object reference = hasReference ? value.get(MulBasedataProp.KEY_BASEDATAID) : null;
+        if (!(reference instanceof DynamicObject)) {
+            throw new IllegalArgumentException("多选基础资料引用未加载，不能使用关联表行主键");
+        }
+        return (DynamicObject) reference;
+    }
+
+    public static List<Long> ids(Object selection) {
+        LinkedHashSet<Long> result = new LinkedHashSet<>();
+        if (selection == null) return new ArrayList<>();
+        if (selection instanceof DynamicObjectCollection) {
+            for (DynamicObject row : (DynamicObjectCollection) selection) addId(result, row);
+            return new ArrayList<>(result);
+        }
+        if (selection instanceof DynamicObject) {
+            addId(result, (DynamicObject) selection);
+            return new ArrayList<>(result);
+        }
+        throw new IllegalArgumentException("F7 过滤值必须是基础资料对象或对象集合");
+    }
+
+    private static void addId(LinkedHashSet<Long> ids, DynamicObject row) {
+        if (row == null) throw new IllegalArgumentException("F7 选择项不能为空");
+        boolean hasShadow = row.getDynamicObjectType().getProperty(MulBasedataProp.KEY_BASEDATAID_ID) != null;
+        Object shadow = hasShadow ? row.get(MulBasedataProp.KEY_BASEDATAID_ID) : null;
+        Object id = shadow != null ? shadow : record(row).getPkValue();
+        if (shadow != null && row.getDynamicObjectType().getProperty(MulBasedataProp.KEY_BASEDATAID) != null) {
+            Object reference = row.get(MulBasedataProp.KEY_BASEDATAID);
+            if (reference != null && (!(reference instanceof DynamicObject)
+                    || !Objects.equals(id, ((DynamicObject) reference).getPkValue()))) {
+                throw new IllegalArgumentException("多选基础资料引用主键与影子主键冲突");
+            }
+        }
+        if (!(id instanceof Long) || ((Long) id) <= 0L) {
+            throw new IllegalArgumentException("基础资料必须携带有效 Long 业务主键");
+        }
+        ids.add((Long) id);
+    }
+
+    public static QFilter idFilter(String sourceField, Object selection) {
+        List<Long> values = ids(selection);
+        return values.isEmpty() ? null : new QFilter(sourceField, QCP.in, values.toArray(new Long[values.size()]));
+    }
+
+    public static boolean missing(Object value) {
+        return value == null || (value instanceof String && ((String) value).trim().isEmpty())
+            || (value instanceof Collection && ((Collection<?>) value).isEmpty())
+            || (value instanceof Object[] && ((Object[]) value).length == 0);
+    }
+
+    // verifyQuery 与 query 开头共用；0、false、带前导零的编码都不是空值。
+    public static void require(Object value, String label) {
+        if (missing(value)) throw new IllegalArgumentException("必录过滤条件不能为空：" + label);
+    }
+
+    public static QFilter comparison(String sourceField, String compare, Object value) {
+        if (!"=".equals(compare) && !"in".equals(compare)) {
+            throw new IllegalArgumentException("仅支持 =、in；日期 between 使用 rangeFilters");
+        }
+        if (missing(value)) return null;
+        if ("=".equals(compare)) {
+            scalar(value);
+            return new QFilter(sourceField, QCP.equals, value);
+        }
+        if (!(value instanceof Collection)) throw new IllegalArgumentException("in 必须携带标量集合");
+        for (Object item : (Collection<?>) value) scalar(item);
+        return new QFilter(sourceField, QCP.in, ((Collection<?>) value).toArray());
+    }
+
+    private static void scalar(Object value) {
+        if (missing(value) || !(value instanceof String || value instanceof Number
+                || value instanceof Boolean || value instanceof Date)) {
+            throw new IllegalArgumentException("查询条件必须携带非空标量；F7 先提取业务主键或编码");
+        }
+    }
+
+    public static List<QFilter> rangeFilters(String sourceField, Date start, Date end, boolean inclusiveEnd) {
+        if (start != null && end != null && (start.after(end) || (!inclusiveEnd && start.equals(end)))) {
+            throw new IllegalArgumentException("日期范围起点必须早于终点");
+        }
+        List<QFilter> result = new ArrayList<>();
+        if (start != null) result.add(new QFilter(sourceField, QCP.large_equals, start));
+        if (end != null) result.add(new QFilter(sourceField, inclusiveEnd ? QCP.less_equals : QCP.less_than, end));
+        return result;
     }
 
     private static void addNumber(LinkedHashSet<String> numbers, DynamicObject value) {
-        String number = value.getString("number");
+        String number = record(value).getString("number");
         if (number == null || number.trim().isEmpty()) {
             throw new IllegalArgumentException("Selected F7 record has no number");
         }

package/skills/cosmic-build/knowledge/cosmic/arch/security/security_standard.md

@@ -377,16 +377,16 @@ ArrayList<String> arrayList = (ArrayList<String>) subList;  // 抛出异常
 List<String> subList = list.subList(0, 1);
 ```
 
-**【🔴 强制】使用集合转数组必须使用 toArray(T[] array)，传入长度为 0 的空数组**
+**【🔴 强制】使用集合转数组必须使用 toArray(T[] array)，数组类型与集合元素一致、长度等于集合大小（DCS 禁止 new T[0]：ITA_INEFFICIENT_TO_ARRAY）**
 
 ```java
 // ❌ 错误：直接使用无参方法
 List<String> list = new ArrayList<>();
 String[] array = list.toArray();  // 返回 Object[]，强转会出错
 
-// ✅ 正确：传入类型为完全一致、长度为 0 的空数组
+// ✅ 正确：数组元素类型完全一致，长度等于集合大小
 List<String> list = new ArrayList<>();
-String[] array = list.toArray(new String[0]);
+String[] array = list.toArray(new String[list.size()]);
 ```
 
 ### 3.4 OOP 安全规约
@@ -1862,7 +1862,7 @@ if (maxAmt == null) {
 5. **long 赋值时使用大写 L**
 6. **不要在 foreach 循环里进行元素的 remove/add 操作**
 7. **ArrayList 的 subList 结果不可强转**
-8. **使用集合转数组必须传入类型为完全一致、长度为 0 的空数组**
+8. **集合转数组传入类型完全一致、长度等于集合大小的数组（DCS 禁止 new T[0]）**
 9. **所有的覆写方法必须加@Override 注解**
 10. **所有整型包装类对象之间值的比较全部使用 equals 方法**
 

package/skills/cosmic-build/knowledge/cosmic/platform/allimport.md

@@ -6,7 +6,7 @@
 无法机器校验，只能凭实测来源信任。用 `python3 scripts/gen_api_index.py` 重新生成；不要手工
 编辑 java 代码块——需要新增 import 时请补充场景，让该 import 获得证据。
 
-## Registered API classes（已注册 API 类，1527 个）
+## Registered API classes（已注册 API 类，1528 个）
 
 ```java
 import kd.bos.algo.Algo;
@@ -23,6 +23,7 @@ import kd.bos.algo.DataSetBuilder;
 import kd.bos.algo.DataType;
 import kd.bos.algo.Field;
 import kd.bos.algo.FilterFunction;
+import kd.bos.algo.GroupbyDataSet;
 import kd.bos.algo.HashTable;
 import kd.bos.algo.Input;
 import kd.bos.algo.JoinHint;

package/skills/cosmic-build/knowledge/cosmic/platform/core/dynamic-object-collection.md

@@ -124,12 +124,12 @@ if (entries == null || entries.isEmpty()) {
 
 // 获取分录行数
 int rowCount = entries.size();
-if (entries.size() == 0) {
+if (entries.isEmpty()) {
     // 处理空分录
 }
 
 // 判断分录行数是否满足条件
-if (entries.size() > 0) {
+if (!entries.isEmpty()) {
     // 处理非空分录
 }
 ```
@@ -171,7 +171,7 @@ for (DynamicObject parentRow : parentEntries) {
 ```java
 // 转换为 DynamicObject 数组（用于批量加载或操作）
 DynamicObjectCollection entries = getModel().getEntryEntity("entry");
-DynamicObject[] entryArray = entries.toArray(new DynamicObject[0]);
+DynamicObject[] entryArray = entries.toArray(new DynamicObject[entries.size()]);
 
 // 用于 BusinessDataServiceHelper.load()
 QFilter filter = new QFilter("id", QCP.in, idList);
@@ -296,5 +296,7 @@ if (parentRow != null) {
 if (entries.size() > 0) { } // entries 可能为 null
 
 // ✅ 使用 isEmpty()
-if (entries != null && !entries.isEmpty()) { }
+if (entries != null && !entries.isEmpty()) {
+    // 在这里处理非空分录；不要保留空块。
+}
 ```

package/skills/cosmic-build/knowledge/cosmic/platform/core/model.md

@@ -80,11 +80,11 @@ related_scenes:
 
 Model 对象常用于以下技术模式（详细代码结构和变体请参考对应文档）：
 
-- [字段联动](../scenes/patterns/field-linkage.md) - 字段值变化时自动更新其他字段
-- [批量更新](../scenes/patterns/batch-update.md) - 一次性更新多个字段，避免重复触发事件
-- [数据初始化](../scenes/patterns/data-init.md) - 表单打开时设置默认值
-- [分录批量操作](../scenes/patterns/entry-batch-operation.md) - 循环处理分录数据
-- [分录行管理](../scenes/patterns/entry-row-management.md) - 新增、删除、清空分录行
+- [字段联动](../scenes/event/property-changed-set-value.md) - 字段值变化时自动更新其他字段
+- [批量更新](../scenes/common/model-begin-end-init.md) - 一次性更新多个字段，避免重复触发事件
+- [数据初始化](../scenes/event/after-bind-data-set-value.md) - 表单打开时设置默认值
+- [分录批量操作](../scenes/event/property-changed-entry-batch.md) - 循环处理分录数据
+- [分录行管理](../scenes/_index.md) - 新增、删除、清空分录行
 
 > 技术模式文档包含：模式定义、涉及的核心对象、典型代码结构、常见变体、业务场景示例
 
@@ -514,7 +514,7 @@ getView().updateView("entry");
 ## 相关文档
 
 - [View 核心对象](view.md) - 界面控制和刷新
-- [Control 核心对象](control.md) - 控件操作
-- [字段联动场景](../scenes/patterns/field-linkage.md) - propertyChanged 中的 Model 用法
-- [分录批量操作场景](../scenes/patterns/entry-batch-operation.md) - getEntryEntity 的典型用法
-- [数据初始化场景](../scenes/patterns/data-init.md) - afterBindData 中的 Model 用法
+- [Control 核心对象](view.md) - 控件操作
+- [字段联动场景](../scenes/event/property-changed-set-value.md) - propertyChanged 中的 Model 用法
+- [分录批量操作场景](../scenes/event/property-changed-entry-batch.md) - getEntryEntity 的典型用法
+- [数据初始化场景](../scenes/event/after-bind-data-set-value.md) - afterBindData 中的 Model 用法

package/skills/cosmic-build/knowledge/cosmic/platform/core/view.md

@@ -81,11 +81,11 @@ related_scenes:
 
 View 对象常用于以下技术模式（详细代码结构和变体请参考对应文档）：
 
-- [消息通知](../scenes/patterns/notification.md) - 向用户显示提示、警告、错误、成功消息
-- [动态控件控制](../scenes/patterns/dynamic-control.md) - 根据业务逻辑动态控制控件显示和启用状态
-- [页面跳转](../scenes/patterns/page-navigation.md) - 打开新表单、关闭页面、返回数据
-- [确认对话框](../scenes/patterns/confirm-dialog.md) - 在执行危险操作前请求用户确认
-- [父子页面交互](../scenes/patterns/parent-child-interaction.md) - 子页面与父页面的数据传递和操作触发
+- [消息通知](../api/form/IFormView.md) - 向用户显示提示、警告、错误、成功消息
+- [动态控件控制](../scenes/event/after-bind-data-set-visible.md) - 根据业务逻辑动态控制控件显示和启用状态
+- [页面跳转](../scenes/event/item-click-show-form.md) - 打开新表单、关闭页面、返回数据
+- [确认对话框](../scenes/event/item-click-show-confirm.md) - 在执行危险操作前请求用户确认
+- [父子页面交互](../scenes/event/closed-call-back-set-value.md) - 子页面与父页面的数据传递和操作触发
 
 > 技术模式文档包含：模式定义、涉及的核心对象、典型代码结构、常见变体、业务场景示例
 

package/skills/cosmic-build/knowledge/cosmic/platform/form-plugin.md

@@ -189,7 +189,7 @@ public void registerListener(EventObject e) {
 
 ```java
 /**
- * Kingdee Cosmic 插件模板（自动生成）
+ * Kingdee Cosmic plugin template (auto-generated)
  * Author: [your-name] | Date: [yyyy-MM-dd]
  */
 package kd.{isv}.{module}.formplugin;
@@ -232,18 +232,22 @@ public class Xxx{PluginSuffix} extends {BaseClass} {
     @Override
     public void afterCreateNewData(EventObject e) { super.afterCreateNewData(e); }
     @Override
-    public void afterBindData(EventObject e) {}
+    public void afterBindData(EventObject e) { super.afterBindData(e); }
     @Override
     public void propertyChanged(PropertyChangedArgs e) {
         super.propertyChanged(e);
         String key = e.getProperty().getName();
-        if (FIELD_XXX.equals(key)) {}
+        if (FIELD_XXX.equals(key)) {
+            // 在此处理字段变化；DCS 不允许空代码块（S108）
+        }
     }
     @Override
     public void itemClick(ItemClickEvent evt) {
         super.itemClick(evt);
         String itemKey = evt.getItemKey();
-        if (BTN_XXX.equals(itemKey)) {}
+        if (BTN_XXX.equals(itemKey)) {
+            // 在此处理按钮点击；DCS 不允许空代码块（S108）
+        }
     }
     @Override
     public void closedCallBack(ClosedCallBackEvent e) {

package/skills/cosmic-build/knowledge/cosmic/platform/list-plugin.md

@@ -229,7 +229,7 @@ ListSelectedRow row = billList.getCurrentSelectedRowInfo();
 
 ```java
 /**
- * Kingdee Cosmic 列表插件模板（自动生成）
+ * Kingdee Cosmic list plugin template (auto-generated)
  * Author: [your-name] | Date: [yyyy-MM-dd]
  */
 package kd.{isv}.{module}.listplugin;
@@ -261,12 +261,14 @@ public class Xxx{PluginSuffix} extends {BaseClass} {
     @Override
     public void itemClick(ItemClickEvent evt) {
         super.itemClick(evt);
-        if (BTN_XXX.equals(evt.getItemKey())) {}
+        if (BTN_XXX.equals(evt.getItemKey())) {
+            // 在此处理按钮点击；DCS 不允许空代码块（S108）
+        }
     }
     @Override
     public void listRowClick(ListRowClickEvent evt) { super.listRowClick(evt); }
     @Override
-    public void billListHyperLinkClick(HyperLinkClickArgs args) {}
+    public void billListHyperLinkClick(HyperLinkClickArgs args) { super.billListHyperLinkClick(args); }
 }
 ```
 

package/skills/cosmic-build/knowledge/cosmic/platform/print-plugin-guide.md

@@ -623,6 +623,7 @@ public class PurchaseOrderPrintPlugin extends AbstractPrintPlugin {
 7. 使用 `beforeExpFile` 自定义文件名时，需保证文件名唯一性。
 8. `AbstractPrintSeniorPlugin` 仅在需要控制数据访问器参数时使用，一般场景使用 `AbstractPrintPlugin` 即可。
 9. 表格操作中插入/删除行列后如果之前有合并设置，建议使用带 `isReMerge=true` 参数的方法重新处理合并。
+10. 报表没有可供引擎加载的实体行：报表的打印插件在 `afterLoadData` 和 `loadCustomData` 中读取报表页面的列表模型（`MainDataSource.getPageId()` → `ReportView` → `ReportListModel.getRowData(startIndex, length)`）。见 `{ROOT_DIR}/knowledge/cosmic/platform/scenes/report/report-print-data.md`。
 
 ## 骨架模板