@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/assets/report-algo-benchmark/ReportAlgoBenchmark.java

@@ -0,0 +1,48 @@
+import kd.bos.algo.*;
+import java.util.*;
+import java.util.concurrent.*;
+
+public class ReportAlgoBenchmark {
+    static Map<String, String> read(DataSet data) {
+        Map<String, String> result=new TreeMap<>();
+        while(data.hasNext()) { Row row=data.next();result.put(row.getString("supplier"),row.getDate("first_date").getTime()+":"+row.getDate("last_date").getTime()); }
+        data.close();return result;
+    }
+    static Map<String, String> baseline(DataSet data) {
+        Map<String, String> result=new TreeMap<>();
+        for(DataSet group:data.splitByGroup(new String[]{"supplier"})) {
+            DataSet first=group.copy().topBy(1,new String[]{"bill_date asc"});
+            DataSet last=group.topBy(1,new String[]{"bill_date desc"});
+            if(!first.hasNext() || !last.hasNext()) throw new AssertionError("empty group");
+            Row firstRow=first.next();String key=firstRow.getString("supplier");long start=firstRow.getDate("bill_date").getTime();
+            long end=last.next().getDate("bill_date").getTime();result.put(key,start+":"+end);first.close();last.close();
+        }
+        return result;
+    }
+    static void run(int rows, int groups, int iterations) {
+        List<Object[]> input=new ArrayList<>();Map<String,String> expected=new TreeMap<>();
+        for(int i=0;i<rows;i++) input.add(new Object[]{"S"+(i%groups),new Date(i*1000L)});
+        for(int i=0;i<groups;i++) expected.put("S"+i,(i*1000L)+":"+((i+((rows-1-i)/groups)*groups)*1000L));
+        RowMeta meta=new RowMeta(new Field("supplier",DataType.StringType),new Field("bill_date",DataType.DateType));
+        Algo algo=Algo.create("report-benchmark");
+        List<Long> oldTimes=new ArrayList<>(),newTimes=new ArrayList<>();
+        for(int i=-1;i<iterations;i++) {
+            long start=System.nanoTime();Map<String,String> old=baseline(algo.createDataSet(input,meta));long oldTime=System.nanoTime()-start;
+            start=System.nanoTime();Map<String,String> optimized=read(CosmicReportAggregation.dateBounds(algo.createDataSet(input,meta)));long newTime=System.nanoTime()-start;
+            if(!expected.equals(old) || !expected.equals(optimized)) throw new AssertionError("business result differs");
+            if(i>=0) { oldTimes.add(oldTime);newTimes.add(newTime); }
+        }
+        Collections.sort(oldTimes);Collections.sort(newTimes);
+        int p95=(int)Math.ceil(iterations*.95)-1;
+        System.out.println("{\"rows\":"+rows+",\"groups\":"+groups+",\"iterations\":"+iterations+",\"resultsEqual\":true,\"baselineP50Ms\":"+oldTimes.get(iterations/2)/1e6+",\"baselineP95Ms\":"+oldTimes.get(p95)/1e6+",\"optimizedP50Ms\":"+newTimes.get(iterations/2)/1e6+",\"optimizedP95Ms\":"+newTimes.get(p95)/1e6+",\"databaseQueries\":0}");
+    }
+    public static void main(String[] args) throws Exception {
+        ExecutorService executor=kd.bos.threads.ThreadPools.newExecutorService("report-benchmark",1);
+        java.util.concurrent.atomic.AtomicBoolean completed=new java.util.concurrent.atomic.AtomicBoolean();
+        try {
+            executor.submit(()->{try(AlgoContext context=Algo.newContext()) {run(Integer.parseInt(args[0]),Integer.parseInt(args[1]),Integer.parseInt(args[2]));completed.set(true);}}).get(60,TimeUnit.SECONDS);
+            if(!completed.get()) throw new AssertionError("managed task did not run");
+            executor.shutdownNow();System.exit(0);
+        } catch(Exception error) { error.printStackTrace();System.exit(2); }
+    }
+}

package/skills/cosmic-build/assets/report-algo-benchmark/ReportBenchmarkLogFactory.java

@@ -0,0 +1,7 @@
+/** Isolates application logging/configuration only; computation uses the actual target SDK. */
+public class ReportBenchmarkLogFactory extends kd.bos.logging.LogFactory {
+    protected kd.bos.logging.Log _getLog(String name) {
+        return (kd.bos.logging.Log) java.lang.reflect.Proxy.newProxyInstance(kd.bos.logging.Log.class.getClassLoader(),
+            new Class[]{kd.bos.logging.Log.class}, (proxy, method, args) -> method.getReturnType()==boolean.class ? false : null);
+    }
+}

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

@@ -0,0 +1,26 @@
+import java.util.Arrays;
+import java.util.stream.Collectors;
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.entity.DynamicObjectCollection;
+import kd.bos.orm.query.QFilter;
+import kd.bos.servicehelper.BusinessDataServiceHelper;
+import kd.bos.servicehelper.QueryServiceHelper;
+
+/** Compile-checked against the 8.0 SDK. Runtime identities and results need target validation. */
+public final class CosmicEntryQuery {
+    private CosmicEntryQuery() {}
+
+    /** Query the verified form root; the result is flat and must not be saved. */
+    public static DynamicObjectCollection queryHeaderIds(String formNumber, QFilter[] filters) {
+        return QueryServiceHelper.query(formNumber, "id", filters);
+    }
+
+    /** Load a structured object by its queried header ID, then read its collection property. */
+    public static DynamicObjectCollection loadEntries(Object headerId, String formNumber,
+            String collectionProperty, String... entryFields) {
+        String selectFields = "id," + Arrays.stream(entryFields)
+            .map(field -> collectionProperty + "." + field).collect(Collectors.joining(","));
+        DynamicObject header = BusinessDataServiceHelper.loadSingle(headerId, formNumber, selectFields);
+        return header == null ? null : header.getDynamicObjectCollection(collectionProperty);
+    }
+}

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

@@ -0,0 +1,35 @@
+import kd.bos.algo.DataSet;
+import kd.bos.orm.ORM;
+import kd.bos.orm.query.QFilter;
+
+/** Inputs are filtered at their owning ORM queries; headers contain exactly one row per id. */
+public final class CosmicReportAggregation {
+    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,
+                               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));
+    }
+
+    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()
+            .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();
+    }
+
+    /** 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();
+    }
+}

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

@@ -0,0 +1,77 @@
+import kd.bos.dataentity.entity.DynamicObject;
+import kd.bos.dataentity.entity.DynamicObjectCollection;
+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.Date;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Objects;
+
+/** Target 8.0 SDK adapter. Supply verified runtime keys and organization scope. */
+public final class CosmicReportFilters {
+    private CosmicReportFilters() { }
+
+    public static Object value(FilterInfo filter, String... keys) {
+        Object result = null;
+        if (filter == null) return null;
+        for (String key : keys) {
+            Object current = filter.getValue(key);
+            if (current == null) continue;
+            if (result != null && !Objects.equals(result, current)) {
+                throw new IllegalArgumentException("Conflicting report filter keys: " + key);
+            }
+            result = current;
+        }
+        return result;
+    }
+
+    public static Date date(FilterInfo filter, String itemKey) {
+        Date result = null;
+        if (filter == null) return null;
+        for (FilterItemInfo item : filter.getFilterItems()) {
+            if (!itemKey.equals(item.getPropName()) || item.getValue() == null) continue;
+            if (!(item.getValue() instanceof Date)) {
+                throw new IllegalArgumentException("Report date filter must carry Date: " + itemKey);
+            }
+            Date current = (Date) item.getValue();
+            if (result != null && !result.equals(current)) {
+                throw new IllegalArgumentException("Conflicting report date values: " + itemKey);
+            }
+            result = current;
+        }
+        return result;
+    }
+
+    /** For field.number comparisons only; this does not grant cross-organization access. */
+    public static List<String> numbers(Object value) {
+        LinkedHashSet<String> result = new LinkedHashSet<>();
+        if (value == null) return new ArrayList<>();
+        if (value instanceof DynamicObjectCollection) {
+            for (DynamicObject row : (DynamicObjectCollection) value) addNumber(result, row);
+            return new ArrayList<>(result);
+        }
+        if (value instanceof DynamicObject) {
+            addNumber(result, (DynamicObject) value);
+            return new ArrayList<>(result);
+        }
+        throw new IllegalArgumentException("F7 filter must carry DynamicObject or DynamicObjectCollection");
+    }
+
+    /** 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]));
+    }
+
+    private static void addNumber(LinkedHashSet<String> numbers, DynamicObject value) {
+        String number = value.getString("number");
+        if (number == null || number.trim().isEmpty()) {
+            throw new IllegalArgumentException("Selected F7 record has no number");
+        }
+        numbers.add(number);
+    }
+}

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

@@ -0,0 +1,25 @@
+import java.time.LocalTime;
+import kd.bos.dataentity.entity.DynamicObject;
+
+/** Adapt an 8.0 SDK TimeProp value; do not use DynamicObject.getDate for this field type. */
+public final class CosmicTimeAdapter {
+    private CosmicTimeAdapter() {}
+
+    public static LocalTime read(DynamicObject row, String fieldKey) {
+        if (row == null || fieldKey == null || fieldKey.isEmpty()) {
+            throw new IllegalArgumentException("A loaded TimeProp row and field key are required");
+        }
+        return fromSeconds(row.get(fieldKey));
+    }
+
+    public static LocalTime fromSeconds(Object value) {
+        if (!(value instanceof Integer)) {
+            throw new IllegalArgumentException("TimeProp must be an Integer number of seconds");
+        }
+        int seconds = ((Integer) value).intValue();
+        if (seconds < 0 || seconds >= 24 * 60 * 60) {
+            throw new IllegalArgumentException("TimeProp seconds are outside one day");
+        }
+        return LocalTime.ofSecondOfDay(seconds);
+    }
+}

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

@@ -0,0 +1,26 @@
+import java.time.LocalTime;
+
+public final class CosmicTimeAdapterCheck {
+    private static void expect(LocalTime actual, LocalTime expected) {
+        if (!actual.equals(expected)) throw new AssertionError(actual + " != " + expected);
+    }
+
+    private static void reject(Object value) {
+        try {
+            CosmicTimeAdapter.fromSeconds(value);
+            throw new AssertionError("invalid TimeProp value accepted: " + value);
+        } catch (IllegalArgumentException expected) {
+            // Invalid or absent platform data must not silently omit a business validation.
+        }
+    }
+
+    public static void main(String[] args) {
+        expect(CosmicTimeAdapter.fromSeconds(Integer.valueOf(36000)), LocalTime.of(10, 0));
+        expect(CosmicTimeAdapter.fromSeconds(Integer.valueOf(46800)), LocalTime.of(13, 0));
+        reject(null);
+        reject(Integer.valueOf(-1));
+        reject(Integer.valueOf(86400));
+        reject(Long.valueOf(36000));
+        System.out.println("CosmicTimeAdapter: 6 cases passed");
+    }
+}

package/skills/cosmic-build/knowledge/cosmic/platform/api/algo/GroupbyDataSet.md

@@ -0,0 +1,47 @@
+---
+framework_version: "8.0"
+api_class: "GroupbyDataSet"
+api_package: "kd.bos.algo"
+when_to_use: "按目标 SDK 对报表数据求和、计算日期边界和去重计数"
+---
+
+# GroupbyDataSet API
+
+通过目标 Algo SDK 的 javap 核验，并由 CosmicReportAggregation 运行测试。
+其他版本使用现有 SDK 查询。以下属于 Algo，不使用 AlgoX Grouper 的签名替代。
+
+## sum
+
+```java
+public GroupbyDataSet sum(String expression, String alias)
+```
+
+## min
+
+```java
+public GroupbyDataSet min(String expression, String alias)
+```
+
+## max
+
+```java
+public GroupbyDataSet max(String expression, String alias)
+```
+
+## avg
+
+```java
+public GroupbyDataSet avg(String expression, String alias)
+```
+
+## countDistinct
+
+```java
+public GroupbyDataSet countDistinct(String[] fields, String alias)
+```
+
+## finish
+
+```java
+public DataSet finish()
+```

package/skills/cosmic-build/knowledge/cosmic/platform/api/entity/report/FilterInfo.md

@@ -375,11 +375,11 @@ public FilterItemInfo getFilterItem(String propName)
 
 **方法签名：**
 ```java
-public List<kd.FilterItemInfo> getFilterItems()
+public List<kd.bos.entity.report.FilterItemInfo> getFilterItems()
 ```
 
 **返回值：**
-- `List<kd.FilterItemInfo>`: 返回过滤字段及其比较值集合
+- `List<kd.bos.entity.report.FilterItemInfo>`: 返回过滤字段及其比较值集合
 
 ---
 
@@ -389,14 +389,14 @@ public List<kd.FilterItemInfo> getFilterItems()
 
 **方法签名：**
 ```java
-public List<kd.FilterItemInfo> getFilterItems(String propName)
+public List<kd.bos.entity.report.FilterItemInfo> getFilterItems(String propName)
 ```
 
 **参数说明：**
 - `propName`: `String` — 字段
 
 **返回值：**
-- `List<kd.FilterItemInfo>`
+- `List<kd.bos.entity.report.FilterItemInfo>`
 
 ---
 
@@ -406,11 +406,11 @@ public List<kd.FilterItemInfo> getFilterItems(String propName)
 
 **方法签名：**
 ```java
-public List<kd.FilterItemInfo> getFlexFilterItems()
+public List<kd.bos.entity.report.FilterItemInfo> getFlexFilterItems()
 ```
 
 **返回值：**
-- `List<kd.FilterItemInfo>`: 返回弹性域过滤字段及其比较值集合
+- `List<kd.bos.entity.report.FilterItemInfo>`: 返回弹性域过滤字段及其比较值集合
 
 ---
 
@@ -527,11 +527,11 @@ public String getString(String propertyName)
 
 **方法签名：**
 ```java
-public List<kd.FilterItemInfo> getTableHeadFilterItems()
+public List<kd.bos.entity.report.FilterItemInfo> getTableHeadFilterItems()
 ```
 
 **返回值：**
-- `List<kd.FilterItemInfo>`
+- `List<kd.bos.entity.report.FilterItemInfo>`
 
 ---
 
@@ -601,11 +601,11 @@ public void setFastFilter(FastFilter fastFilter)
 
 **方法签名：**
 ```java
-public void setFlexFilterItems(List<kd.FilterItemInfo> flexFilterItems)
+public void setFlexFilterItems(List<kd.bos.entity.report.FilterItemInfo> flexFilterItems)
 ```
 
 **参数说明：**
-- `flexFilterItems`: `List<kd.FilterItemInfo>` — 弹性域过滤字段及其比较值集合
+- `flexFilterItems`: `List<kd.bos.entity.report.FilterItemInfo>` — 弹性域过滤字段及其比较值集合
 
 ---
 
@@ -657,11 +657,11 @@ public void setReportFilterConfig(ReportFilterConfig reportFilterConfig)
 
 **方法签名：**
 ```java
-public void setTableHeadFilterItems(List<kd.FilterItemInfo> tableHeadFilterItems)
+public void setTableHeadFilterItems(List<kd.bos.entity.report.FilterItemInfo> tableHeadFilterItems)
 ```
 
 **参数说明：**
-- `tableHeadFilterItems`: `List<kd.FilterItemInfo>` — 表头过滤条件集合
+- `tableHeadFilterItems`: `List<kd.bos.entity.report.FilterItemInfo>` — 表头过滤条件集合
 
 ---
 

package/skills/cosmic-build/knowledge/cosmic/platform/api/entity/report/FilterItemInfo.md

@@ -11,6 +11,8 @@ when_to_use: "当你需要使用报表单个过滤项信息时"
 报表单个过滤项信息。实现 Serializable。
 主要功能：读取属性、设置属性。
 
+FilterItemInfo 不是 DynamicObject。目标 bos-entity-metadata-8.0.jar 的 getPropName、getValue、getDate 均为公开方法，其他 SDK 先核验签名。拆分日期使用准确起止项 key，不能用 toString 解析日期。
+
 ## Import 路径
 ```java
 import kd.bos.entity.report.FilterItemInfo;

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

@@ -27,7 +27,7 @@ afterCopyData（仅复制）→ beforeBindData → afterBindData
 | `getEntityType` | 创建数据包前触发 | 指定动态表单实体类型 |
 | `createNewData` | 开始新建数据包时触发 | 自定义数据包创建 |
 | `afterCreateNewData` | 仅新增时，数据包创建后 | 设置默认字段值 |
-| `afterLoadData` | 仅编辑时，数据库数据加载后 | 读取数据做额外初始化 |
+| `afterLoadData` | 仅编辑时，数据库数据加载后。仅单据与基础资料插件（`billform` / `baseform` / `mobbill`）可用：`AbstractFormPlugin` 和 `AbstractMobFormPlugin` 没有声明 `afterLoadData` | 读取数据做额外初始化 |
 | `afterCopyData` | 仅复制时，数据包复制后 | 清空不应复制的字段 |
 | `beforeBindData` | 控件绑定数据之前 | 注册分录行监听 |
 | `afterBindData` | 控件绑定数据之后 | 控制控件显隐/启用 |
@@ -207,7 +207,7 @@ import kd.bos.form.control.events.ItemClickEvent;
 import kd.bos.form.events.BeforeDoOperationEventArgs;
 import kd.bos.form.events.AfterDoOperationEventArgs;
 import kd.bos.form.operate.FormOperate;
-import kd.bos.form.openStyle.ShowType;
+import kd.bos.form.ShowType;
 import kd.bos.form.plugin.AbstractFormPlugin;
 import kd.bos.logging.Log;
 import kd.bos.logging.LogFactory;
@@ -232,8 +232,6 @@ public class Xxx{PluginSuffix} extends {BaseClass} {
     @Override
     public void afterCreateNewData(EventObject e) { super.afterCreateNewData(e); }
     @Override
-    public void afterLoadData(EventObject e) { super.afterLoadData(e); }
-    @Override
     public void afterBindData(EventObject e) {}
     @Override
     public void propertyChanged(PropertyChangedArgs e) {

package/skills/cosmic-build/knowledge/cosmic/platform/java-type-contracts.md

@@ -126,6 +126,7 @@ QFilter filter = new QFilter("id", QCP.not_in, idSet);
 | 整数 | `getLong(key)` / `getInt(key)` |
 | 小数、金额、单价、数量 | `getBigDecimal(key)` |
 | 日期 | `getDate(key)` |
+| 时刻（`TimeProp` / `TimeField`） | `getInt(key)`；目标 8.0 SDK 中为距午夜的整秒数 |
 | 是/否 | `getBoolean(key)` |
 | 被引用的记录 | `getDynamicObject(key)` |
 | 分录行或 `Mul*` 值 | `getDynamicObjectCollection(key)` |
@@ -133,6 +134,11 @@ QFilter filter = new QFilter("id", QCP.not_in, idSet);
 
 写值用 `set(key, value)`。
 
+`TimeProp` 不是 `DateProp`：其 SDK 属性类型为 `Integer`，实测数据库中的 10:00 为 `36000`。
+对这个整数调用 `getDate(key)` 会经 SDK 的 `ObjectConverter` 返回 null；若代码直接跳过
+null，时段比较会悄然失效。比较前核对原始值和字段的空值设置，同日时段使用距午夜秒数；
+跨日与时区行为需要明确业务规则。
+
 ## 分录字段取值要带行号
 
 `getModel().getValue(key)` 读的是单据头字段，分录字段要用 `getValue(key, rowIndex)`。视图侧
@@ -152,5 +158,8 @@ QFilter filter = new QFilter("id", QCP.not_in, idSet);
 
 读该类自己的页面 `knowledge/cosmic/platform/api/**/{Class}.md`。它的方法列表只覆盖该类自身
 声明的方法——继承来的方法记录在页面概述里 `继承自` 指向的那个类上。这些页面由 Cosmic 8.0.1
-的 javadoc 导出生成，因此不含构造器，也不含非 `@SdkPublic` 的重载：页面上没有某个方法，不能
-证明它不存在，但同样不构成可以照写的依据。此时返回 `L3-BLOCK`，不要凭记忆写签名。
+的 javadoc 导出生成，因此不含构造器，也缺少部分公开重载：页面上没有某个方法，不能证明它不存在，
+但同样不构成可以照写的依据。此时到绑定的目标 SDK 中查证：
+`scripts/platform_api_contract.py --describe-class` 对未收录的类和成员会返回 `sdkLookup`，按
+`references/sdk-inspection.md` 执行。准确的目标 SDK 仍无法确认所需签名时才返回 `L3-BLOCK`，任何
+时候都不要凭记忆写签名。

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

@@ -22,17 +22,21 @@
 ### 列表数据格式化（packageData）
 
 ```java
-import kd.bos.list.events.ListPackageDataEvent;
+import kd.bos.entity.datamodel.events.PackageDataEvent;
 
 @Override
-public void packageData(ListPackageDataEvent e) {
+public void packageData(PackageDataEvent e) {
     super.packageData(e);
-    // 格式化某列显示值（原始值 → 显示文本）
-    Object rawValue = e.getField("targetColumn");
+    // 格式化某一列的显示值（原始值 → 显示文本）。
+    // getColKey() 返回列标识；需要同行其他值时用 getRowData() 取整行。
+    if (!"targetColumn".equals(e.getColKey())) {
+        return;
+    }
+    Object rawValue = e.getFormatValue();
     if ("C".equals(rawValue)) {
-        e.setValue("targetColumn", "已审核");
+        e.setFormatValue("已审核");
     } else if ("A".equals(rawValue)) {
-        e.setValue("targetColumn", "草稿");
+        e.setFormatValue("草稿");
     }
 }
 ```
@@ -42,15 +46,15 @@ public void packageData(ListPackageDataEvent e) {
 ### 自定义列表过滤（setFilter）
 
 ```java
-import kd.bos.list.events.PrepareFilterEvent;
+import kd.bos.form.events.SetFilterEvent;
 
 @Override
-public void setFilter(PrepareFilterEvent e) {
+public void setFilter(SetFilterEvent e) {
     super.setFilter(e);
     // 注入额外过滤条件（如限制仅查看本人数据）
     long userId = RequestContext.get().getCurrUserId();
     QFilter myFilter = new QFilter("creator", QCP.equals, userId);
-    e.addCustomFilter(myFilter);
+    e.addCustomQFilter(myFilter);
 }
 ```
 
@@ -154,7 +158,7 @@ public void billListHyperLinkClick(HyperLinkClickArgs args) {
 
 ```java
 import kd.bos.form.MobileFormShowParameter;
-import kd.bos.form.openStyle.ShowType;
+import kd.bos.form.ShowType;
 
 private void openMobileForm() {
     MobileFormShowParameter p = new MobileFormShowParameter();
@@ -232,8 +236,8 @@ package kd.{isv}.{module}.listplugin;
 
 import java.util.EventObject;
 import kd.bos.list.plugin.AbstractListPlugin;
-import kd.bos.list.events.ListPackageDataEvent;
-import kd.bos.list.events.PrepareFilterEvent;
+import kd.bos.entity.datamodel.events.PackageDataEvent;
+import kd.bos.form.events.SetFilterEvent;
 import kd.bos.list.events.ListRowClickEvent;
 import kd.bos.form.control.events.ItemClickEvent;
 import kd.bos.form.events.HyperLinkClickArgs;
@@ -251,9 +255,9 @@ public class Xxx{PluginSuffix} extends {BaseClass} {
         addItemClickListeners("tbmain");
     }
     @Override
-    public void setFilter(PrepareFilterEvent e) { super.setFilter(e); }
+    public void setFilter(SetFilterEvent e) { super.setFilter(e); }
     @Override
-    public void packageData(ListPackageDataEvent e) { super.packageData(e); }
+    public void packageData(PackageDataEvent e) { super.packageData(e); }
     @Override
     public void itemClick(ItemClickEvent evt) {
         super.itemClick(evt);

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

@@ -29,9 +29,9 @@ onPreparePropertys
 ## 插件内常见上下文方法
 
 ```java
-OperateMeta operateMeta = this.operateMeta;   // 操作信息
-OperationResult result = this.operationResult; // 操作结果
-Map<String, Object> options = this.getOption(); // 自定义参数
+Map<String, Object> operateMeta = this.operateMeta;   // 操作信息
+OperationResult result = this.getOperationResult(); // 操作结果
+OperateOption options = this.getOption(); // 自定义参数
 // OperateErrorInfo：kd.bos.entity.operate.result | ErrorLevel：kd.bos.entity.validate
 result.addErrorInfo(new OperateErrorInfo("ERR_01", ErrorLevel.Info, 4L));
 result.setMessage("操作成功");   // 需配 setShowMessage(true) 才会展示
@@ -48,7 +48,7 @@ result.setSuccess(false);
 2. **onPreparePropertys 声明依赖字段**，否则数据包会缺失
 3. **规则校验放 onAddValidators**，事务前事件 (`beforeExecuteOperationTransaction`) 只做兜底取消
 4. **数据修改放 beginOperationTransaction / endOperationTransaction**（事务内，异常自动回滚）
-5. **级联同步放 afterExecuteOperationTransaction**（事务已提交，需做好异常处理）
+5. **级联同步和关联对象写入按原子性选择位置**：必须与本操作同成同败的写入留在事务内（第 4 条），异常要向外传播；只有明确允许在操作提交后独立执行的同步才放 afterExecuteOperationTransaction，并且要有补偿策略，见下文跨实体回写场景
 
 ## 精选场景知识
 

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

@@ -71,9 +71,10 @@ getColumns → [用户点击查询] → query(queryParam, null)
 1. 必须定义 `private static final String ALGO_NAME` 用于可追溯性
 2. 必须包含权限过滤：`filter.getQFilters()` — 不得跳过
 3. selectFields CSV 必须与 `reportColumns[i].dateIndex` 精确匹配
-4. 使用 `filter.getFilterItems()` 获取用户输入的过滤条件
+4. 过滤条件读取技能根目录的 `references/report-filter-contract.md`。选择值用实际 key 调用
+   getValue，拆分日期用强类型 FilterItemInfo；getQFilters 的权限条件不能代替用户条件取值
 5. 构造 QFilter 前必须对过滤值做空判断
-6. DataSet 实现 AutoCloseable；插件不得关闭它（由框架管理生命周期）
+6. 框架接管的返回 DataSet 不由插件关闭，自有 copy() 副本用完关闭
 7. 使用 `private static final String ENTITY_NUMBER` 常量 — 禁止硬编码实体标识
 8. 返回的每一列都必须携带 `handoff.reportContract` 的 `dataSetColumnTypes` 给出的 Java 类型 ——
    用该条目的 `rowAccessor` 读它，手工构建的 `Field` 用它的 `algoDataType` 声明。类型不对是在 set
@@ -85,7 +86,7 @@ getColumns → [用户点击查询] → query(queryParam, null)
     `prepare_plugin_handoff --external-schema` 已校验的 read-back，在 `verifiedFields` 里返回
 11. `api/` 下的 API 参考页会丢掉 `throws` 子句，所以那里的签名不带它并不等于该方法没有声明。
     `query` 与 `getColumns` 都声明了 `throws Throwable` —— 见
-    `scenes/report/report-list-data-query.md` 的 Method Signatures 段。声明它或收窄掉都能编译，
+    `scenes/report/report-list-data-query.md` 的 Method Signatures 段。声明它总能编译；只有覆写不调用 `super` 时才能收窄掉，
     不要去「修」已经声明它的示例。API 页能确定的是 `abstract`，这也是 `query` 不带 `super` 调用的原因
 
 ## 骨架模板
@@ -101,6 +102,8 @@ import kd.bos.orm.query.QFilter;
 import kd.bos.servicehelper.QueryServiceHelper;
 
 import java.util.List;
+import java.util.ArrayList;
+import kd.bos.orm.query.QCP;
 
 /**
  * 报表取数插件骨架模板（原生 AbstractReportListDataPlugin）。
@@ -119,8 +122,8 @@ public class ReportListDataPluginTemplate extends AbstractReportListDataPlugin {
         // this.setProgress(30);
     }
 
-    private static final String QUERY_KEY = "report-query";
-    private static final String ENTITY_NAME = "entity_name";
+    private static final String ALGO_NAME = "report-query";
+    private static final String ENTITY_NUMBER = "entity_name";
     private static final String SELECT_FIELDS = "id,billno,name";
     private static final String ORDER_BY = "id desc";
     private static final String FIELD_BILL_NO = "billno";
@@ -140,10 +143,15 @@ public class ReportListDataPluginTemplate extends AbstractReportListDataPlugin {
         //（见 api/entity/report/AbstractReportListDataPlugin.md），Java 禁止通过 super 调用
         // 抽象方法。getColumns 是具体方法，所以那里要调 super。
         FilterInfo filter = queryParam.getFilter();
-        int top = 1000;
-        QFilter[] filters = filter == null ? null : filter.getQFilters().toArray(new QFilter[0]);
+        List<QFilter> filters = new ArrayList<>();
+        if (filter != null) {
+            filters.addAll(filter.getQFilters());
+            // Example only: bind the actual panel key to the source field from reportContract.
+            Object billNo = filter.getValue(FIELD_BILL_NO);
+            if (billNo != null) filters.add(new QFilter(FIELD_BILL_NO, QCP.equals, billNo));
+        }
         this.setProgress(20);
-        return QueryServiceHelper.queryDataSet(QUERY_KEY, ENTITY_NAME, SELECT_FIELDS, filters, ORDER_BY, top);
+        return QueryServiceHelper.queryDataSet(ALGO_NAME, ENTITY_NUMBER, SELECT_FIELDS, filters.toArray(new QFilter[0]), ORDER_BY);
     }
 
     /**
@@ -152,7 +160,7 @@ public class ReportListDataPluginTemplate extends AbstractReportListDataPlugin {
      * 典型用途: 动态隐藏列、修改列宽、冻结列或调整显示顺序。
      */
     @Override
-    public List<AbstractReportColumn> getColumns(List<AbstractReportColumn> columns) {
+    public List<AbstractReportColumn> getColumns(List<AbstractReportColumn> columns) throws Throwable {
         super.getColumns(columns);
         apply(columns);
         return columns;

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/operation/cross-entity-aggregate-writeback.md

@@ -41,3 +41,5 @@ handoff 必须已提供：源表头/分录和目标实体 key、关联字段、
 - 保存对象：`data-access/business-data/save-service.md`
 
 只在上述文档仍缺少某个精确签名时，按编码技能规则定位该 API；不要宽泛 grep 整个工程。
+
+以上证据路径均相对于 APP_BUILD_ROOT 下的 `knowledge/cosmic/platform/scenes/`。