@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/references/java-plugin-delivery.md

@@ -1,168 +1,38 @@
 # Java 插件交付
 
-仅在元数据边界已验证、运行时行为仍需要 Java 时使用。稳定契约是：
+实现所选元数据入口无法表达的行为，`cosmic-coding-impl` 提供 Java 实现指导。
+`{ROOT_DIR}` 是根技能提供的技能包目录。
+
+1. 通过[运行类型路由](plugin-runtime-routing.md)按业务触发点选择类型。
+2. 按[交接输入](plugin-handoff-input.md)从准确表单编码准备每个类，独立读取当前原生元数据。
+   准备实施时加上 `--prepare-source`。
+3. 写源码前读取一次 [cosmic-coding-impl](../skills/cosmic-coding-impl/SKILL.md)，
+   准确路径使用准备结果中的 `codingEvidence.codingEntry`，完成源码和
+   [原生编译](compile-guide.md)。同模块中已准备好的多个源码可以共用一次批量构建。
+   编译前对照 `codingEvidence.signatureTypes` 核对导入，对照保存的原生结构核对查询根实体、
+   集合属性和字段路径。本轮源码问题一起处理，不把已知问题留到业务验收再修。
+4. 达到 `source_ready` 后注册已归档类，并验证注册结果：
 
 ```text
-已验证元数据 → 已验证编码上下文 → AI 编码 → 窄编译 → 批量注册并读回
+{python} "{ROOT_DIR}/scripts/register_plugins.py" --app-root "{appRoot}" --class-name "{fqcn1}" [--class-name "{fqcn2}"] --verify
 ```
 
-`ROOT_DIR` 是根技能提供的技能包目录。下文必须逐字使用它；本地化参考文件自身
-所在目录不是技能包根目录。
-
-技能负责保护苍穹特有的身份和生命周期契约，不规定类如何拆分、编码顺序、调试方式或是否使用
-子 agent。
-
-## 1. 准备已验证编码上下文
-
-按 `references/plugin-runtime-routing.md` 一次确定 `type`。操作插件先创建必需的自定义操作，
-并对受影响表单取得一次已验证的 `listOperations` 结果。
-
-使用 CLI 自带输出文件参数保存纯 JSON，禁止用 shell 重定向：
-
-```text
-{python} "{cosmic_api}" --output "{operations.json}" listOperations \
-  --app-root "{appRoot}" --formNumber "{formNumber}"
-```
-
-把精简的业务意图直接传给上下文编译器：
-
-```text
-{python} "{ROOT_DIR}/scripts/prepare_plugin_handoff.py" \
-  --app-root "{appRoot}" --type "{type}" \
-  --artifact "{artifact1}" [--artifact "{artifact2}"] \
-  --run-result "{writeResultPath}" \
-  [--operations-file "{listOperations.json}"] \
-  [--external-schema "{entity.schema.json}"] --intent-json '<JSON>'
-```
-
-`--run-result` 接受两种写入结果信封：`runBatch` 的逐制品 `results[]`，或报表流水线在其 `resultPath`
-（`{appRoot}/_runtime/output/last_result.run.json`）返回的单制品 `run` 汇总。没有捕获到写入结果时
-整项省略，此时编译器只从制品中取身份。
-
-报表直接把报表 Artifact 传进来即可。编译器把 `entities[0].formNumber` 读作表单身份，从
-`reportColumns[].{fieldKey, caption}` 取字段目录，并采用已注册的 `reportPlugins[].className` 的包名，
-使编码出的类不会偏离平台将要加载的 FQCN。
-
-意图只包含业务行为、触发点、相关表单，以及代码实际读写的实体和字段。优先使用准确的业务
-显示名或 authoring ID；禁止自行拼接 ISV 前缀或猜测截断后的持久化 key。编译器负责从 emit
-产物映射为已验证的真实 key；重名字段用 `form + entity + field` 限定。
-
-每个映射到的字段都会在 `handoff.fieldContracts` 中返回制品所声明的 `fieldType`，引用字段还
-额外带 `valueAccessor`、`idAccessor`、`filterValue`。这补上了 `fields` 只是一个
-`{label: key}` 裸映射所留下的缺口：引用字段的 `get()` 返回的是被引用的 DynamicObject，把这
-个值写进 `QFilter` 能顺利编译，然后在数据库层以 `type=DynamicObject` 失败。这些契约原样传给
-编码阶段。
-
-```json
-{
-  "form": "收款记录单",
-  "relatedForm": "合同签订单",
-  "trigger": "保存或提交成功后",
-  "operationKeys": ["save", "submit"],
-  "fields": {
-    "receivedAmount": {"form": "收款记录单", "entity": "收款明细", "field": "收款金额"}
-  },
-  "coreLogic": ["汇总有效收款金额", "回写合同累计金额和收款状态"],
-  "specialized": {
-    "externalContracts": [],
-    "unresolvedDependencies": []
-  },
-  "ownershipMode": "create-new"
-}
-```
-
-`specialized.unresolvedDependencies` 必须显式声明。代码需要读取或影响 emit 产物之外的对象时，
-要么在 `specialized.externalContracts` 中提供精确的数据/服务契约，要么把未决业务依赖写入
-`unresolvedDependencies`；非空时编译器直接阻断。来源实体、字段集合、服务身份或方法签名
-仍未知时，禁止为了通过校验而填写空数组。`externalContracts` 的每一项从头到尾都是对象，所以要给出
-真实形状（`{"entity": ..., "fields": [...]}`），不要写成一句散文。
-
-`externalContracts` 中带 `entity` 的条目是被校验的，不是被采信的。这里可使用准确的
-表单/实体名称或编码及字段显示名；编译器会把它们解析成唯一实体和持久字段 key，歧义仍会
-拒绝。把该表单读一次并传进来，与操作插件传 `listOperations` 完全同理：
-
-```text
-{python} "{cosmic_api}" --output "{entity.schema.json}" getFormSchema --formNumber "{formNumber}"
-```
-
-缺少对应的 `--external-schema` 时，handoff 以 `PLUGIN_EXTERNAL_CONTRACT_UNVERIFIED` 阻断；声明的字段
-在 read-back 中不存在时同样阻断，并点名最接近的候选。凭记忆写的 key 就是在这里被拦住的：`bos_user`
-的手机字段是 `phone`，而按 `mobilephone` 编码此前会一路走到运行期。每个通过校验的条目都会带回
-`verifiedFields`，其中含每个字段真实的 `fieldKey`、`fieldName`、`fieldType`、`refEntity`，以及那些
-值为记录 id 的引用类型的 `javaType` —— 它是 `Long`，把它的文本形式传进 `QFilter` 会在数据库层失败，
-而不是在 Java 层失败。
-
-修改已经存在的类使用 `ownershipMode: "modify"` 加真实的 `sourcePath`（`patch-existing` 视为
-同一模式）。编译器会读取那个文件并回传 `handoff.existingMethods`，即其最外层类体已声明的方法
-签名，使编码阶段把逻辑加进已经承载该触发时机的方法内，而不是在原有 `afterCreateNewData`
-旁边再声明一个。`sourcePath` 不存在、或文件名不是 `{className}.java` 时以
-`PLUGIN_SOURCE_NOT_FOUND` 失败 —— 去定位那个类，不要降级为 `create-new`。
-
-目标文件已经存在于该 Java 模块时（包括按类型约定推导出的类名），`create-new` 会以
-`PLUGIN_OWNERSHIP_CONFLICT` 被拒绝。这个冲突本身就是答案，不是障碍：把报出的路径作为
-`sourcePath` 回传，并改用 `ownershipMode: "modify"`。
-
-优先使用 `--intent-json`。内联 JSON 是多行或含有 shell 敏感字符时改用 `--intent-file` —— 某些 shell
-会把它拆开，命令在脚本运行前就失败。禁止预先为预计的每个插件各写一份文件。按内聚业务逐个准备并
-编码，单个插件未解析时不得为全部插件重新建立计划图。
-禁止并行准备多个插件交接：一个插件必须先达到 `source_ready`，再开始下一个；全部完成后只批量
-注册一次。
-
-Java 模块根目录按此顺序解析：显式 `--java-project-root`、
-`context.javaProjectRoot/pluginProjectRoot`、当前绑定的工程根（当它含 `src/main/java`）、
-`appconfig.pluginProjects[appCode]`，最后是 appRoot 自身（当它含 `src/main/java`）。
-以上全部落空且 `compile=false` 时，解析器会在 appRoot 下预置应用本地 `src/main/java`
-并使用它：纯元数据工作区上的首次交付由此落进这个按应用固定的目录，而不是去问
-类放哪。预置的是源码树，不是臆造的 Gradle 模块：交付以
-`source_ready (compile skipped by config)` 收口，且一旦配置了编译，真实 Gradle 模块
-仍以更高优先级压过它。appconfig 是机器级配置且只以 appCode 为键，因此它只在
-绑定的工程根不存在或不是 Java 模块时生效。工程根跟随绑定工程，因此
-`GRADLE_ROOT` 必须指向同一个 checkout：指向别处会以 `PLUGIN_MODULE_UNRESOLVED`
-失败，因为它下面没有任何 Gradle 模块的 `projectDir` 等于该工程根。
-出现 `PLUGIN_WORKSPACE_UNRESOLVED` 时——现在只在编译开启或未决、预置不生效时
-才会到达——只询问一次现有
-Java 模块根目录并保存：
-
-```text
-{python} "{ROOT_DIR}/scripts/appconfig_load.py" --save-plugin-project "{appCode}" \
-  --plugin-project-root "{javaModuleRoot}"
-```
-
-禁止臆造 Gradle 模块或平台身份。未知外部数据或服务契约保持 `L3-BLOCK`，不得用 TODO 或
-默认值掩盖。
-
-## 2. 让 AI 正常编码
-
-读取 `skills/cosmic-coding-impl/SKILL.md`，依据已验证上下文实现。当前 agent 可以直接编码；
-只有子 agent 确实有助于并行或上下文隔离时才使用，不再强制派发，也不存在“一类一个 agent”规则。
-
-AI 自主决定类拆分、辅助方法复用、实现顺序和编译错误修复。必要时可以查看目标 Java 模块、
-附近已有插件和准确的平台参考，但不得重新发现或替换已经验证的应用、表单、字段和操作身份。
-
-每个需要注册的类必须达到 `source_ready`：窄编译通过且归档项已写入。这仍不代表已注册或
-运行态业务已通过。
-
-本环节不配置菜单，也不输出产物卡片；插件完成后由 app-build 输出卡片，并仅在用户明确要求时
-处理菜单事项。
-
-## 3. 确定性收口
-
-所有必需类达到 `source_ready` 后批量注册：
-
-```text
-{python} "{ROOT_DIR}/scripts/register_plugins.py" --app-root "{appRoot}" \
-  --class-name "{fqcn1}" [--class-name "{fqcn2}"] --verify
-```
-
-`register_plugins.py` 只读取 `write_archive_json.py` 写入的类归档，注册选中类，并对每个受影响
-表单只读回一次，验证 `fqcn + targetType + operationKey`。禁止手改归档或退回猜测的注册载荷。
-
-只报告最窄真实状态：`source_ready`、`source_ready（按配置跳过编译）`、`已编译并注册` 或
-`运行态已验证`。`compile_plugin_source.py` 返回 `compileSkipped=true` 时，该类是在没有编译证明的
-情况下归档并注册的 —— 要如实说明，不得报告为 `已编译并注册`。把验证后的类和受影响表单身份交回
-app-build；产物卡片和用户明确要求的菜单事项仍由 app-build 最后完成。
-
-## 4. 运行态验收独立
-
-编译、注册和插件读回只证明可部署且注册存在。只有用户明确要求运行态验收并点名可用工具或
-集成时，才执行真实业务操作；没有对应证据时只报告“已编译并注册”。
+注册会核对归档的 `sourceHash`、`compileStatus` 与当前源码。缺少证明或源码已变化时返回
+原生编译入口。失败时诊断同一类和目标，不通过更换运行类型获得注册成功。
+
+报告准确的类、受影响表单，并分别说明编译、注册和回读结果；注册后跳过的编译仍为跳过。
+`activation.runtimeVerified=false` 表示尚未验证运行态生效与行为；`requiresServiceRestart=null`
+表示工具无法确定目标环境是否需要重启。注册回读本身不能证明插件已生效或业务正确。
+生效方式依据所选环境的部署契约和已有授权确定；后续源码变化后刷新原生检查，
+在运行态检查前核实目标实际运行的是更新后的版本。
+
+业务验收依据原始需求，验证真实状态流转和关联对象持久化，并核对校验没有增加未要求的副作用。
+插件检查失败时保留输入，并回读插件实际使用的日期、状态、引用 ID 等字段。改源码前，
+把候选原因与事件是否进入、查询命中数、运行插件版本及返回的校验错误等实测证据分开。
+证据无法取得时如实报告诊断缺口，不凭编译通过反复更换查询写法和重启。
+有证据支持的修复完成后，重跑同一失败断言及受影响的相邻检查；新单据保存成功
+不证明后续查询用到的字段值，仍需回读。
+交付结果按同一目标身份保留未解决的生效与验收项。
+
+本环节不配置菜单，也不输出产物卡片。app-build 按 [delivery.md](delivery.md) 统一交付领域
+产物；菜单需要用户明确要求。

package/skills/cosmic-build/references/operation-dispatch.md

@@ -0,0 +1,17 @@
+# 操作分派证据
+
+同一操作插件注册到多个操作时按需读取。本轮核对的 8.0 SDK 中，不同接收者使用不同接口：
+
+| 位置 | 已核实访问器 |
+|---|---|
+| 校验器的 `validate()` | `AbstractValidator` 的 `this.getOperateKey()` |
+| 事务回调的事件参数 | 从 `OperationArgs` 继承的 `event.getOperationKey()` |
+
+`onAddValidators` 添加所需校验器，各校验器用自身访问器选择对应操作；事务回调在实施操作专属
+副作用前，用事件参数选择对应操作。多个操作共享行为需要来自实际需求。
+
+`operateMeta` 是 Map。Map 存在或编译成功均不能证明其中有 `operationKey`、`operateKey` 或 `key`。
+在正确接收者上使用上述类型化接口；不同 SDK 版本或上下文需要准确契约证据。
+
+接口签名已通过 8.0 SDK 的 `javap` 核对；隔离 SDK 检查构造事务参数与校验器实例并核对访问器值。
+这没有模拟平台事件执行、候选查询或持久化，不能替代这些验证。

package/skills/cosmic-build/references/plugin-handoff-input.md

@@ -0,0 +1,131 @@
+# 已验证的 Java 编码上下文
+
+使用根技能提供的 `{ROOT_DIR}`。准备源码前，先通过
+[plugin-runtime-routing.md](plugin-runtime-routing.md)确定业务触发点对应的类型。
+
+## 从已有表单独立准备
+
+```text
+{python} "{ROOT_DIR}/scripts/prepare_plugin_handoff.py" \
+  --app-root "{appRoot}" --form-number "{formNumber}" --type "{type}" \
+  --intent-json '<JSON>' --prepare-source
+```
+
+使用创建或已有表单发现返回的准确表单编码，不要求建模 artifact、manifest 或写入回执。操作插件即使传入回执，也只将它作为身份提示，
+仍读取原生结构。
+命令读取当前原生实体元数据（`getEntityType`）与操作，保存原始响应及完整的表头/分录/
+子分录结构。关联表按声明解析；中文目标名称的候选限于主表引用目标。
+本地文件存在不代表元数据完整或仍为当前版本。
+
+启用编译时，`--prepare-source` 先确认已有 Java 工程准确映射一个真实 Gradle 模块，
+并从该模块的目标 SDK 核验类，再开放源码门禁。额外选用的接口通过
+`sdkUsage: [{"class": "<准确全限定类名>", "members": ["<声明的方法>"]}]` 指定。
+继承方法需核验实际声明类；类缺失、版本不唯一或方法未声明均停止准备。
+查询 `/handoff/targetSdk` 获取库与类哈希及声明证据。明确配置 `compile=false` 时仍可
+仅准备源码，但 SDK、编译和运行均标记未验证。准备与编译不持久化推导出的运行配置。
+编译、注册、重启和真实事件验证分别记录结果。
+
+`formGraph` 是编码依据，包含真实实体类型、集合属性名、父子关系、限定字段路径、类型、
+引用目标和枚举值；`relatedForms` 包含关联数据的对应结构。`getDynamicObjectCollection`
+使用集合属性名，不能假设它与集合元素的实体类型名相同。继承和系统字段一并保留。
+不要从 authoring 名称推导这些信息、搜索旧源码，或手工重建 DYM/Schema 响应。
+
+编码前优先读取调用方提供的启动文件，或从原生 handoff 查询 `coding-start`。
+启动上下文包含字段/类型、状态值、可用操作、SDK 接收者接口和缺失细节的准确路径。
+大字段清单使用 `fieldsPath` 与 `fieldCount`，按需查询，不把省略的清单当作元数据不存在。
+
+这些事实描述结构和集合访问方式，不保证每个实体类型都是数据服务的查询根。
+不能仅因 `EntryType` 或 `SubEntryType` 出现在结构图中，就把它作为
+`QueryServiceHelper.query` 的独立根。以表单编码作为已知表单身份；
+要依赖具体查询结果时，先用 SDK 证据或限定范围的运行验证确认查询方式。
+
+`fields`、`entities` 选择器只是可选别名/校验，不是完整结构的前提。
+`header`、`entries`、`subentries` 按结构角色限定；多个分录/字段匹配时返回带归属的候选。
+删除选择器不得导致返回结构中的字段消失。同一类的完整业务行为与操作键一次传入，
+不拆成多个片段反复准备同名类。
+不同快照覆盖同一交接文件时，在修改源码门禁前返回 `PLUGIN_HANDOFF_CONFLICT`。
+先核对原快照并协调类身份和业务范围，再使用 `--replace-handoff` 明确替换。
+
+旧调用和报表仍支持 `--run-result`、`--emit-manifest`、`--artifact`；有运行实体的 Java 编码
+以原生结构为准。报表或仅元数据页面没有运行实体时，按其领域读取契约获取上下文。
+
+intent 描述业务行为和稳定选择器。从类型指南中选择适用 `scenes`，路径相对于
+`knowledge/cosmic/platform/scenes/`；准备入口会展开场景声明的 SDK 参考，提供准确导入和签名。
+例如校验及跨实体回写使用下面两个场景，只传实际适用项。
+
+```json
+{
+  "form": "<表单显示名>",
+  "trigger": "<业务触发点>",
+  "operationKeys": ["<已验证的操作键>"],
+  "scenes": ["operation/custom-validator", "operation/cross-entity-aggregate-writeback"],
+  "coreLogic": ["<所需行为>"],
+  "specialized": {"externalContracts": [], "unresolvedDependencies": []},
+  "ownershipMode": "create-new"
+}
+```
+
+非操作类型省略 `operationKeys`。原生元数据使用准确显示名或真实落库键。
+authoring ID 仅适用于旧 artifact 输入，不能去掉 ISV 前缀来构造运行键。
+编译器拒绝歧义；重名字段用表单/实体/字段限定。每项外部数据或服务依赖都在
+`specialized.externalContracts` 中声明为结构化对象，数据契约使用 `entity` 和 `fields`。
+失败回执里的相似字段只供核对，不能按前缀或后缀自动改写目标身份。
+需求已给出外部字段显示名时，直接在 `specialized.externalContracts` 使用该显示名；
+只有 authoring 标识时，先读取关联表单的当前元数据取得真实落库键，再准备 handoff，
+不自行拼接 ISV 前缀。
+未知依赖填写在必需的 `specialized.unresolvedDependencies` 中，非空列表会阻止编码；
+不得提交空列表掩盖缺失契约。复杂或含 shell 敏感字符的 JSON 使用 `--intent-file`，
+它只是命令输入，不增加规划阶段。
+
+## 消费交接结果
+
+准备入口默认返回 `contextMode="reference-only"` 的紧凑摘要和准确 `handoffPath`。
+完整文件继续保留本次线上读取的元数据和 SDK 证据，直接交给原生编译器。Java 编码先一次读取
+本类的字段、关联表、操作、状态警告和已注册 SDK 签名，其中包含 `QueryServiceHelper.query`
+的准确返回类型；不要直接 `read` 整份 JSON：
+准备后若平台元数据发生变化，先重新准备 handoff 再查询或编译；查询命令只读取已保存快照，不会刷新线上数据。
+
+```text
+{python} "{ROOT_DIR}/scripts/query_plugin_handoff.py" coding-context --handoff "{handoffPath}"
+```
+
+只有一次读取明确缺少契约或超过大小上限时，才在本插件的实施上下文中继续定向查询：
+
+```text
+{python} "{ROOT_DIR}/scripts/query_plugin_handoff.py" index --handoff "{handoffPath}"
+{python} "{ROOT_DIR}/scripts/query_plugin_handoff.py" index --handoff "{handoffPath}" --path /handoff/formGraph/entities
+{python} "{ROOT_DIR}/scripts/query_plugin_handoff.py" find --handoff "{handoffPath}" --path /handoff/operationContracts --field operationKey --equals "{verifiedOperationKey}"
+{python} "{ROOT_DIR}/scripts/query_plugin_handoff.py" get --handoff "{handoffPath}" --path "{matchedPointer}"
+```
+
+沿返回的 JSON 路径，读取准确实体与字段契约、关联表、外部契约、操作值、状态警告和所需 SDK 签名。
+大列表通过 `index --offset --limit` 分页；过大的 `get` 会返回缩小路径的提示，不截断证据。
+stdout 摘要和目录不代替编码上下文；写源码前必须读取实际所需的叶节点。需要旧版完整 stdout
+形状的非模型调用方可显式加 `--full-output`。原生编译直接传 `--handoff`，不重新搜索该文件。
+`operationContracts` 保留真实操作参数；`stateFields` 和 `fieldContracts.comboOptions` 保留
+真实枚举值。写源码前按业务意图解决 `stateWarnings`，不能猜测 submit/audit 对应确认/完成、
+编码中更换操作键，或将值冲突归为显示问题。外部 Schema 只有业务名称时，补准确 `formNumber`。
+
+直接使用返回的 `className`、`sourcePath`、`fqcn`、`type` 和目标身份。
+编译器根据 `references/type-registry.json` 和已绑定项目决定类名、包及模块，不在文档中
+重复实现这些规则。报表 Artifact 提供报表列、`reportContract` 和已有注册类身份。
+将 `fields`、`entities`、`fieldContracts`、已验证外部字段及 `specialized` 原样传给编码。
+`codingEvidence` 提供所选参考路径、API 签名及参数/返回类型的准确 `signatureTypes` 导入。
+使用这些真实导入；未解析类型沿其 `apiLookup` 查询，不凭记忆拼包名。查询字段路径结合
+实际查询根实体及原生结构确定，包含关联表与嵌套集合。`--prepare-source` 在验证后将已解析门禁标记
+为 `coding`，不写 Java；实施时复用返回的 `sourceGate`，并在已验证模块中创建目标包目录；
+新包无需通过构建文件或兄弟项目重新查找。
+
+已有类使用 `ownershipMode="modify"` 和真实 `sourcePath`，编译器保留其包并返回
+`existingMethods`。创建冲突会返回已有路径，应改为 modify，不能覆盖。modify 源码缺失时
+应定位文件，不能降级为 create。每个类写入前先准备上下文，已准备的同模块类可合并编译。
+
+若 `PLUGIN_WORKSPACE_UNRESOLVED` 无法通过已有项目上下文解决，询问一次现有 Java 模块根目录，
+随后保存：
+
+```text
+{python} "{ROOT_DIR}/scripts/appconfig_load.py" --save-plugin-project "{appCode}" --plugin-project-root "{javaModuleRoot}"
+```
+
+显式 `compile=false` 时，解析器可使用应用内源码目录；这不创建 Gradle 模块，也不证明编译。
+其他配置问题按 CLI 的准确诊断处理。未知外部契约保持 `L3-BLOCK`，不写 TODO 或默认结果。

package/skills/cosmic-build/references/plugin-runtime-routing.md

@@ -29,7 +29,7 @@
   `event.setTreeReportList(true)` 与 `event.setTreeExpandColId(<列>)`，或在 `beforeQuery` 里调
   `ReportQueryParam.setTreeReportList(true)`。`reportlist` 照常返回普通行。
 
-`type` 必须取 `cosmic-coding-impl` 插件映射表中的值；仅仅是描述性的取值（例如 `report`）解析不出
+`type` 必须取 `references/type-registry.json` 中的值；仅仅是描述性的取值（例如 `report`）解析不出
 类名后缀，也解析不出对应 guide。
 
 页面事件只保证当前交互会话，不能承担“所有保存/提交入口都生效”的承诺。`operation` 必须提供

package/skills/cosmic-build/references/report-filter-contract.md

@@ -0,0 +1,78 @@
+# 报表过滤与运行交付
+
+报表取数插件的过滤开发或过滤故障使用本参考。优先使用已发布的元数据 CLI 获取源字段、配置控件并独立回读，再使用原生交接、编译及加载验证 CLI。浏览器负责真实控件提交和用户要求的页面验收。不支持的类型化控件明确报告平台边界，不反复重建报表或添加不支持的 schema 属性。
+
+## 绑定每个条件
+
+结合 `reportContract.filterValueContracts`、`filterEnforcement` 和已核实的源 schema，确定源实体、字段与类型、引用或枚举配置、运行 key、比较方式、查询实体与字段、值类型及组织范围。过滤控件应与源字段一致：BasedataField 保留引用和 F7 选择语义，ComboField 保留真实枚举值，日期范围保留 date/datetime 时间语义。
+
+`candidateValueKeys`、`sourceBinding` 是声明的候选，不是运行实测证据。dataSourceId 不一定是实体编码。缺失事实通过已绑定的 CLI 或一次关联到具体请求的观察解决，不按业务名称猜字段。
+
+实测项目使用 `flt_x` / `shfz_x`，但来源地区实际 key 是源字段 `shfz_admindivision`。优先明确映射，兼容别名只在适用时尝试；多个别名有冲突值时拒绝执行。必填值缺失明确报错，不能静默丢弃已输入条件。枚举值 `0` 和编码前导零均须保留。
+
+## 按目标 SDK 读取 FilterInfo
+
+| 值形态 | 读取和比较 |
+| --- | --- |
+| Combo 或 F7 选择 | `getValue(实际key)`；Combo 使用存储值，F7 为 DynamicObject 或 DynamicObjectCollection |
+| 拆分日期范围 | `getFilterItems()`，匹配准确的 `<key>_startdate` / `<key>_enddate`，读取 Date |
+| 权限过滤 | 在对应实体查询中保留 `getQFilters()`，不能代替用户条件取值 |
+
+这些是面板实测形态，不是 SDK 内部三个互不交叉的存储。在已检查的 8.0 SDK 中，`getValue(key)` 会调用 `getFilterItem(key).getValue()`；FilterItemInfo 有公开的 `getPropName()`、`getValue()`、`getDate()`，应直接使用强类型访问器。
+
+[CosmicReportFilters.java](../examples/java-rules/CosmicReportFilters.java) 覆盖别名冲突、拆分日期、F7 单选多选和编码保留。全部分支编译校验；FilterInfo 测试无需服务即可运行，构造 F7 元数据需要已授权的目标配置和日志服务，缺失时明确跳过。其他 SDK 先通过现有 SDK CLI 核验访问器，仅在目标确实需要时使用有界反射兼容。FilterItemInfo 不是 DynamicObject；toString 只用于诊断，不能作为生产日期解析。
+
+按业务口径支持单边范围、开始与结束边界。同日范围覆盖全部数据时区分力不足，还需区间外记录及边界时刻。关联实体的权限条件需核对映射，不能照搬主实体字段 key。
+
+## F7 身份与 Algo
+
+跨组织业务身份按已确认的编码范围，使用 String 值和 `field.number` QFilter。ORM 解析相应分配记录，但不能因此扩大权限。pkValue 和 masterId 均不保证等于业务单据引用的 ID。只查特定分配记录时，对 `field` / `field.id` 使用确认后的 Long ID。核对编码在租户、实体和组织范围内的唯一性，不能始终合并同编码记录。
+
+确认范围后，`CosmicReportFilters.numberFilter(源字段, 选择值)` 生成 `源字段.number` 的 String 数组 QFilter。仍需同时保留权限与业务范围；空的可选选择值不增加 QFilter。
+
+使用 Algo/DataSet 查询，把用户及业务条件下推到所属数据源。各一对多分录分别聚合后关联，再按报表维度汇总。避免逐行服务或数据库调用、无界 Java Map 和 IN 列表。Row 立即读取，不能缓存；selectFields 需要引用编码时使用 `field.number`。框架接管的返回 DataSet 不由插件关闭，自有 copy 用完关闭。分页或任意 top 限制不能截断合计和导出所需数据。
+
+## 使用 CLI 编译部署并验证加载
+
+使用交接中的工程、包和 sourcePath。用户指定的报表目录是项目绑定，不是通用默认路径。由原生编译器解析 Gradle 模块，项目名不一定等于目录名。已有报表使用已发布的注册修改命令，不走创建管线。按 className upsert 不证明另一个旧 className 已被删除；独立回读注册或明确该边界。
+
+按 [compile-guide.md](compile-guide.md) 编译并保存 JSON 回执。回执包含 sourceHash、默认 Gradle 输出可绑定时的 compiledArtifact，以及 loadingVerification。compileSkipped 不证明编译。复制到 outputdir、重启 JVM 均不能单独证明本次请求使用了新版本。
+
+```text
+{python} "{ROOT_DIR}/scripts/verify_plugin_loading.py" \
+  --compile-result "<原生编译回执.json>" \
+  --compiled-class "<绑定的编译产物.class>" --deployed-class "<配置的加载路径.class>" \
+  [--runtime-trace "<本次请求的plugin-trace结果.json>"]
+```
+
+该 CLI 只读，核对当前源码与回执哈希、class FQCN 和产物哈希。仅 artifactMatch=true 时 runtimeVerified 仍为 false。运行证明需要准确 FQCN 和目标类加载工具捕获、关联到被测请求的 loadedClassSha256；plugin-trace 可从实际已授权日志提取。替换文件后读取资源或磁盘哈希不能代表 JVM 已加载的字节码。旧哈希失败，证据缺失 blocked，不能 passed。此工具不重启、复制、注册或伪造日志。
+
+自定义 sourceSets 或输出目录需使用其原生构建部署契约的真实产物回执，本工具不猜路径，也不把默认产物缺失解释为激活成功。已有可信的构建或版本加载证据可以直接复用，并准确说明证明范围；不为满足这个可选本地检查器而给生产服务增加诊断工具。
+
+确认当前加载后再验证业务。在授权修复范围内删除临时反推或诊断代码，重新编译、加载并复测受影响断言。编译、注册回读、激活和业务结果分别报告，SQL 执行或编译成功均不证明报表正确。
+
+## P1 同源控件与 Algo
+
+在 reportFilters.source 声明已核实的 formNumber/fieldKey。CLI 每个来源表单读取一次 fieldSchemas，
+使用 ReportFilters.typed 写入，再将报表实际配置与重新读取的来源比较。当前支持 TextField、DateField、
+DateTimeField、DateRangeField、ComboField/MulComboField、BasedataField/MulBasedataField、DecimalField。
+日期 between 转为 DateRangeField；专用类型以及未解决的组织或条件引用依赖明确拒绝。来源表单只读，
+不复制源单据必录默认值、继承标志或变更监听器。
+
+来源配置和类型化回读需要 assets/platform-report-filters 中的平台补丁和 TypedReportFilterFields 类，
+按平台原生构建部署流程安装。旧平台保持阻塞，不用 dry-run 或未知属性写入成功冒充支持。使用 CLI
+脚本 apply_report_filter_extension.py --project-root <准确平台模块> --dry-run 预检，确认版本后在授权范围应用；
+脚本不编译、发布或重启。控件提交及真实数据仍按 P0 验收。
+
+examples/java-rules/CosmicReportAggregation.java 用三次同范围的表单根 ORM 查询，先聚合两个分录，再关联。
+使用已核验的 min/max/countDistinct，避免按组拆分、排序和合并。表头别名为 id/supplier/bill_date/base_amount，
+分录为 main_id/amount；主表查询不能选分录字段造成展开。禁止逐 Row 查询。返回流水线由框架管理；测试驱动
+关闭自有 DataSet，并使用 SDK 托管线程。
+
+```text
+{python} "{ROOT_DIR}/scripts/report_algo_benchmark.py" --sdk-classpath "<目标SDK类路径>" \
+  --java-home "<目标Java8目录>" --rows 100000 --groups 1000 --iterations 5 --output "<结果.json>"
+```
+
+基准执行真实 SDK 并校验结果一致，仅测本地计算。SQL、权限、页面及完整导出需在授权服务上按 traceId、
+查询次数、输入行数、冷暖 p50/p95 与内存峰值分别测量，不能把本地加速比例当作应用 SLA。

package/skills/cosmic-build/references/sdk-inspection.md

@@ -0,0 +1,23 @@
+# 查证绑定的 SDK
+
+文档 API 查询不能确认必需类、重载或实现细节时使用。传入目标工程实际使用的 SDK JAR 或目录，
+不从主目录或其他项目猜路径。工具不安装反编译器、不访问服务。
+
+```text
+{python} "{ROOT_DIR}/scripts/inspect_platform_sdk.py" --class "<准确类名或简名>" --sdk-dir "<目标 SDK 目录>" --member "<方法>"
+```
+
+可多次传 `--jar` 选择准确库，或用 `--mode locate` 先定位类。同名类／多版本 JAR 返回候选，
+不自动选取。`javap` 优先来自已配置目标 JDK，再查 PATH；不可用时用 `--javap` 指定准确 JDK 工具。
+
+先看签名；行为仍不明确时，添加 `--mode bytecode` 和准确 `--member`。这是字节码查证，
+不会重建 Java 源码。确有必要时再使用已有源码／文档 JAR 或已安装反编译器，不假定它们可用。
+
+已有源码或文档 JAR 时，用 `--list-resources "<类名>"` 查条目，再用
+`--resource "<准确条目>" --first-line <n> --limit <n>` 分段读文本，不提取文件到磁盘。
+类查证与参考文本的证据范围不同。
+
+结果记录类、JAR 路径／哈希／版本、选中声明和证据范围。声明中缺少方法可能是继承方法，
+JAR manifest 没有实现版本时，`version` 为 null，哈希仍可核对准确文件。
+必要时查所列父类。签名证明调用形式，字节码证明选中方法的实现；二者均不证明目标服务已加载
+该版本或实际执行业务行为。

package/skills/cosmic-build/schemas/data-model-authoring.schema.json

@@ -442,7 +442,7 @@
             "TreeSubEntryEntity"
           ]
         },
-        "templateKey": {"type": "string"},
+        "templateKey": {"type": "string", "description": "Optional for BillEntity/BaseEntity; the emitter supplies the standard template when omitted. Explicit values must resolve to a real template."},
         "parentEntityRef": {"$ref": "#/definitions/entityIdentifier"},
         "entryDisplayType": {
           "type": "string",
@@ -451,7 +451,7 @@
         "listConfiguration": {"$ref": "#/definitions/listConfiguration"},
         "uiComposition": {
           "type": "object",
-          "description": "Optional screenshot/business PC layout intent. Each sections/tabs block uses caption and rows; each row uses fields with display names or null slots. Emitted as one post-build applyFormComposition closure."
+          "description": "Optional screenshot/business PC layout intent. Each sections/tabs block uses caption and rows. Every row contains only a non-empty fields array; a full-line field is {\"fields\":[{\"field\":\"Description\",\"fullLine\":true}]}, never row-level fullLine. Emitted as one post-build applyFormComposition closure."
         },
         "logicalName": {
           "type": "string",
@@ -496,7 +496,6 @@
             "required": ["type"]
           },
           "then": {
-            "required": ["templateKey"],
             "properties": {
               "templateKey": {"type": "string", "minLength": 1}
             }