@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/knowledge/cosmic/platform/scenes/operation/pre-post-operation.md

@@ -7,7 +7,7 @@ status: "draft"
 scene_name: "操作插件前后处理"
 trigger_event: "beforeExecuteOperationTransaction / afterExecuteOperationTransaction"
 scene_keywords: ["AbstractOperationServicePlugIn", "操作插件", "beforeExecuteOperationTransaction", "afterExecuteOperationTransaction", "onPreparePropertys"]
-related_apis: ["AbstractOperationServicePlugIn", "OperationServicePlugIn"]
+related_apis: ["AbstractOperationServicePlugIn", "BusinessDataServiceHelper.load", "BusinessDataServiceHelper.loadSingle", "QueryServiceHelper.query", "SaveServiceHelper.save", "SaveServiceHelper.update"]
 ---
 
 # 场景：操作插件前后处理
@@ -20,12 +20,15 @@ related_apis: ["AbstractOperationServicePlugIn", "OperationServicePlugIn"]
 ## 涉及的核心对象（必读）
 | 对象 | 用途 | 文档路径 |
 |------|------|---------|
-| AbstractOperationServicePlugIn | 操作插件基类，提供操作生命周期钩子 | api/operation/AbstractOperationServicePlugIn.md |
-| BeforeOperationArgs | 操作执行前参数，包含 dataEntities | api/operation/BeforeOperationArgs.md |
-| AfterOperationArgs | 操作执行后参数，包含 dataEntities | api/operation/AfterOperationArgs.md |
-| DynamicObject | 动态数据对象，读写字段值 | core/MODEL.md |
-| SaveServiceHelper | 数据保存服务 | api/services/SaveServiceHelper.md |
-| BusinessDataServiceHelper | 数据查询服务 | api/services/BusinessDataServiceHelper.md |
+| AbstractOperationServicePlugIn | 操作生命周期 | api/entity/plugin/AbstractOperationServicePlugIn.md |
+| BeforeOperationArgs | 操作前数据 | api/entity/plugin/args/BeforeOperationArgs.md |
+| AfterOperationArgs | 操作后数据 | api/entity/plugin/args/AfterOperationArgs.md |
+| DynamicObject | 字段值 | api/dataentity/entity/DynamicObject.md |
+| SaveServiceHelper | 关联对象持久化 | api/servicehelper/operation/SaveServiceHelper.md |
+| BusinessDataServiceHelper | 加载关联对象 | api/servicehelper/BusinessDataServiceHelper.md |
+
+以上路径相对于 `knowledge/cosmic/platform/`。已提供的 API 契约已证明签名；
+只有仍有缺口时才读取参考页。
 
 ## 典型代码结构
 `extracted` `needs-verification`
@@ -76,3 +79,8 @@ public class MyOperationPlugin extends AbstractOperationServicePlugIn {
 - 遍历 `e.getDataEntities()` 时注意可能包含多条数据（批量操作场景）
 - 读取关联对象字段前务必做 null 检查，避免 NullPointerException
 - 操作插件需在苍穹开发平台的操作配置中注册才能生效
+- 通过 `onPreparePropertys` 或校验器的属性准备声明操作需要读取的字段。
+  元数据结构说明字段可用，不代表操作已加载这些字段。
+- 区分当前操作数据包的修改和独立加载对象的修改。独立对象的 `set` 只修改内存，
+  需要在合适事务中调用已验证的保存/更新服务完成持久化，关联写入尽量批量执行。
+- 每项业务行为使用真实操作键。标准操作更新单据状态字段时，不会自动更新另一业务状态字段。

package/skills/cosmic-build/knowledge/cosmic/platform/sdk/sdk-algo.md

@@ -27,80 +27,36 @@ Algo 是苍穹平台的内存计算引擎，遵循 SQL-92 标准，提供类 SQL
 - `toCollection()`: 转为 `DynamicObjectCollection` (慎用)。
 
 ## 示例代码
-### 1. 基础转换与聚合
+### 转换和关联前聚合
+
 ```java
-try (DataSet ds = QueryServiceHelper.queryDataSet("key", "entity", "id, qty, price", null, null)) {
-    DataSet result = ds.addField("qty * price", "amount")
-                       .where("amount > 1000")
-                       .groupBy(new String[]{"id"})
-                       .sum("amount", "total")
-                       .finish();
-    while (result.hasNext()) {
-        Row row = result.next();
-        // 处理结果...
-    }
-}
+DataSet ds = QueryServiceHelper.queryDataSet("key", "entity", "id,qty,price", filters, null);
+return ds.addField("qty * price", "amount").where("amount > 1000")
+    .groupBy(new String[]{"id"}).sum("amount", "total").finish();
 ```
 
-### 2. 高性能 HashJoin
+返回流水线由框架管理，不能在渲染前关闭。两个一对多分录各自按主单 ID 聚合后再关联，避免金额倍增。
+使用已核验的 leftJoin/on/select/finish，不猜测 hashJoin 或 toHashTable 的签名。
+
+## 目标 SDK 的聚合能力
+
+已检查的 8.0 GroupbyDataSet 支持 sum、min、max、avg 的 expression/alias 重载和
+countDistinct(String[] fields, String alias)。使用直接聚合替代 splitByGroup/topBy/union，避免为每个分组
+物化、排序和合并数据集。签名见 api/algo/GroupbyDataSet.md，其他版本通过现有 SDK CLI 重查。
+
 ```java
-HashTable detailTable = dsDetail.toHashTable("order_id");
-DataSet joined = dsHeader.hashJoin(detailTable, "id", new String[]{"qty", "price"}, true);
+DataSet bounds = orders.groupBy(new String[]{"supplier"})
+    .min("bill_date", "first_date").max("bill_date", "last_date")
+    .countDistinct(new String[]{"id"}, "bill_count").finish();
 ```
 
-## 聚合：哪些有文档，哪些没有
-
-`groupBy(String[] fields)` 返回 `kd.bos.algo.GroupbyDataSet`。在本知识库里，只有上面示例用到的
-两个构造调用有确切签名：
-
-| 调用 | 状态 |
-|---|---|
-| `sum(String expr, String alias)` | 有文档（见上方示例） |
-| `finish()` | 有文档（见上方示例） |
-| `GroupbyDataSet` 上的 `count(...)` / `max(...)` / `min(...)` / `avg(...)` | **本知识库中无任何文档** |
-
-不要把 `kd.bos.algox.Grouper` 的签名借过来用。那个类确实有 `count(field, alias)`、
-`max(field, alias)`、`min(field, alias)` 的文档，但它属于 **AlgoX**（`DataSetX`，分布式计算），
-是另一个类型——混用就是猜。
-
-需求需要分组极值或去重计数时的后果：
-
-- **去重计数**可以用已有文档的能力表达。先归约到「每个被计数对象一行」，加一个常量列再求和：
-
-  ```java
-  DataSet bills = orm.queryDataSet(algo, entity, "supplier as sup, billno", filters, null);
-  DataSet counts = bills.addField("1", "one")
-                        .groupBy(new String[]{"sup"})
-                        .sum("one", "order_count")
-                        .finish();
-  ```
-
-- **分组 `min` / `max`** 可以表达，只是不在 `GroupbyDataSet` 上。`DataSet` 自身为
-  `splitByGroup(String[])`、`topBy(int, String[])` 和 `union(DataSet)` 提供了确切签名，而分组
-  极值就是「每组在正确排序下的第一行」：
-
-  ```java
-  // 按供应商取末单/首单日期，只用有文档签名的方法。
-  DataSet[] perSupplier = orders.splitByGroup(new String[]{"sup"});
-  DataSet latest = null;
-  for (DataSet group : perSupplier) {
-      DataSet top1 = group.topBy(1, new String[]{"order_date desc"});
-      latest = latest == null ? top1 : latest.union(top1);
-  }
-  // latest 现在每个供应商一行，携带该供应商的 max(order_date)。
-  // 把 "desc" 换成 "asc" 就是 min；报表列同时需要首单和末单时，按 "sup" 关联两个结果。
-  ```
-
-  `splitByGroup` 会为每个分组物化一个 DataSet，所以它适合按组织、供应商、物料分组的报表，不适合
-  基数极高的分组键（按单、按行）。分组数不可控时，应当先收窄输入 —— 加过滤，或改用更粗的分组键 ——
-  而不是去猜一个没有文档的聚合方法。
-
-`reduceGroup(ReduceGroupFunction)` 同样有确切签名，可以算出任意分组值，但 `ReduceGroupFunction`
-只有 `reduce(Iterator<Row>)` 一处文档：它还需要声明的输出 RowMeta 没有参考页，所以优先用上面的
-`splitByGroup` + `topBy` 写法。
-
-仍然不可用的是：**作为 `GroupbyDataSet` 构造调用**的 `max` / `min` / `count` / `avg`。不要写
-`groupBy(keys).max(field, alias)`。若 `GroupbyDataSet` 后续补上经验证的 API 参考页，请更新此表。
+examples/java-rules/CosmicReportAggregation.java 经过编译和运行核验，演示三次同范围表单根查询、
+分录预聚合和空分录处理。提供准确字段别名、权限和业务条件，不以 import Algo 作为性能证明。
+Row 立即取值；框架接管的返回 DataSet 不主动关闭。
+
+该引擎未提供 SQL COALESCE，使用示例中经过运行测试的 CASE WHEN 空值表达式。
+表达式字符串编译通过不能证明 SQL 有效。本地 CLI 基准校验相同数据结果并记录 p50/p95，
+数据库、权限、导出和页面耗时仍需在目标环境测量。
 
 ## 列类型：常量词汇表，以及每种类型怎么读
 

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

@@ -179,8 +179,8 @@ package kd.cd.common;
 import kd.bos.workflow.api.AgentExecution;
 import kd.bos.workflow.component.approvalrecord.IApprovalRecordItem;
 import kd.bos.workflow.engine.extitf.IWorkflowPlugin;
-import kd.cd.core.util.CollectionUtils;
 
+import java.util.ArrayList;
 import java.util.List;
 
 /**
@@ -214,8 +214,7 @@ public class IWorkflowPluginTemplate implements IWorkflowPlugin {
      */
     @Override
     public List<Long> calcUserIds(AgentExecution execution) {
-        super.calcUserIds(execution);
-        List<Long> userIds = CollectionUtils.newArrayList();
+        List<Long> userIds = new ArrayList<>();
         Object starter = execution.getVariable(VAR_START_USER);
         if (starter instanceof Number) {
             userIds.add(((Number) starter).longValue());
@@ -230,7 +229,6 @@ public class IWorkflowPluginTemplate implements IWorkflowPlugin {
      */
     @Override
     public boolean hasTrueCondition(AgentExecution execution) {
-        super.hasTrueCondition(execution);
         Object amount = execution.getVariable(VAR_AMOUNT);
         return amount instanceof Number && ((Number) amount).doubleValue() > 100000D;
     }
@@ -242,7 +240,6 @@ public class IWorkflowPluginTemplate implements IWorkflowPlugin {
      */
     @Override
     public void notify(AgentExecution execution) {
-        super.notify(execution);
         if (execution.getCurrentFlowElement() != null) {
             execution.setVariable(VAR_LAST_NODE, execution.getCurrentFlowElement().getName());
         }
@@ -255,7 +252,6 @@ public class IWorkflowPluginTemplate implements IWorkflowPlugin {
      */
     @Override
     public void notifyByWithdraw(AgentExecution execution) {
-        super.notifyByWithdraw(execution);
         execution.setVariable(VAR_LAST_NODE, "withdraw");
     }
 
@@ -266,7 +262,6 @@ public class IWorkflowPluginTemplate implements IWorkflowPlugin {
      */
     @Override
     public IApprovalRecordItem formatFlowRecord(IApprovalRecordItem item) {
-        super.formatFlowRecord(item);
         return item;
     }
 }

package/skills/cosmic-build/references/application-context.md

@@ -1,12 +1,42 @@
 # 应用上下文
 
+## 既有需求基线
+
+基线为 `target.kind=form` 时，将准确 `target.formNumber` 传给原生已有表单写入命令，不能当作 `--app-code`。复用命令的唯一归属解析及 `TEST_ENVIRONMENT_HANDOFF.path`。基线同时明确声明 `application.code` 时，将其作为应用约束传给写入命令，在写入前拒绝错误归属；已唯一定位的所属应用不额外查询或审批。
+
+请求提供 `cosmic-requirements-baseline/v1` 索引时，直接消费已选应用、当前确认要求、用户约束、
+假设及取消项，复用准确路径和完整 prepare 快照。不扫描其他本地应用、不重复询问已确认选择；
+平台身份仍由原生命令核实。
+
+计算范围、处理确认变更或交接 QA 时使用共享的[业务基线与交接](../../../../cosmic-requirements-spec/.locales/zh/references/baseline-handoff.md)。
+脚本位于 `{ROOT_DIR}/../cosmic-requirements-spec/scripts/requirements-baseline.mjs`，只读已知
+需求/交付路径。未结构化的既有来源继续使用并显式核对，不悄悄重写成新 PRD。
+
+保留明确实现排除约束。已核实的必需路线与约束冲突时，只提出受影响的业务决定；参数或引用
+解析失败不证明冲突。继续独立明确工作，不删除原要求以迁就实现。
+
 在命令需要应用绑定、出现归属冲突，或前序命令返回不同目标应用时读取。
 
-`ROOT_DIR` 是 Skill 包目录；`appRoot` 是准确业务应用目录。两者不能互换。
+`{ROOT_DIR}` 是 Skill 包目录；`appRoot` 是准确业务应用目录。两者不能互换。
 
 用户、宿主上下文或已验证 CLI 回执给出的准确 `appRoot` 可直接使用。项目根及其
 `app/` 容器不是应用根。不得通过扫描源码、DYM 或 archive 推断在线归属。
 
+## 元数据目录
+
+专家团及其他调用方统一使用 app-build 已绑定的 `appRoot` 和 CLI 返回的产物路径。
+不得另选输出根目录、另建专家团元数据目录或复制原生产物形成第二套交付目录。
+
+- `{appRoot}/archive.json`：应用绑定及交付索引。
+- `{appRoot}/_runtime/`：本地运行状态和命令输入、结果。
+- `{appRoot}/metadata/_emit/`：生成的元数据变更产物。
+- `{appRoot}/modify/`：变更批次清单。
+- DYM/DYMX 源文件：交付命令返回的已配置同步目录。
+
+标准工程布局下，`appRoot` 为 `{projectRoot}/app/{appCode}`。应用任务不得在
+`{projectRoot}` 下创建 `_runtime`、`metadata` 或 `modify`；这些名称出现在已绑定
+应用目录下是正常的，由 CLI 维护，不能只按目录名判断是否错误。
+
 新建时，“身份真实存在”不等于“用户选择了它”。绑定前必须取得用户选择或宿主明确选中的
 应用；不得把 appMapping.tsv 或本地唯一应用目录当作该选择。
 
@@ -20,6 +50,8 @@
 
 只有当前命令不支持直接绑定且没有可信应用时，才绑定选定应用。已有应用编码直接调用
 bootstrap；只有应用显示名才需要下面第一条查询。不要把已知编码传给 --app-name。
+本地应用目录不存在只代表尚未在此绑定。已有准确应用编码时直接执行绑定命令；
+旧调试页面状态和源码目录清单不能证明所选应用的线上身份。
 
 ```text
 {python} {ROOT_DIR}/scripts/getAllCloudApp.py --project-root "<项目根>" --app-name "<准确应用名>" --verbose
@@ -34,3 +66,5 @@ Shell 返回空输出或非零退出时，Python 运行环境尚未验证，不
 
 继承、复制或扩展可能返回新的目标。后续工作使用返回的 `appRoot` 与表单身份；归属漂移时停止，
 不得猜测替代身份。
+
+复用返回的 executionBinding 与[执行契约](execution-contract.md)中的续跑入口；工作区旧副本不能作为备用 CLI 来源。

package/skills/cosmic-build/references/common-reference.md

@@ -124,7 +124,7 @@
 2. **插件/路由文档**（插件类与 API 类需要）：先读取 `{ROOT_DIR}/references/type-registry.json`，按当前 `type` 取 `guide`；再读取对应文档
 3. **核心对象**：先读取 `{ROOT_DIR}/references/type-registry.json`，按当前类型的 `family` 判定是否需要 `view.md` / `model.md`；UI 生命周期(form_lifecycle,list_lifecycle,mobile_lifecycle)家族读取全部，其他类型默认跳过
 4. **场景匹配**：读取 `{ROOT_DIR}/knowledge/cosmic/platform/scenes/_index.md`，按上述「场景匹配规则」先做 `pluginType` 过滤，再做标签与语义筛选，并行读取匹配的场景文档
-5. **补充 API**：场景文档未覆盖时，查 `{ROOT_DIR}/knowledge/cosmic/platform/api/api-index.md` 或 Grep 搜索 `{ROOT_DIR}/knowledge/cosmic/platform/api/` 目录；**禁止反编译 jar 包**
+5. **补充 API**：场景文档未覆盖时，查 `{ROOT_DIR}/knowledge/cosmic/platform/api/api-index.md` 或相关 API 目录。必需证据仍缺失时，可只读查证已绑定项目的实际 SDK：定位准确类，用 `javap` 核对签名，行为仍不明确时才查看相关方法字节码或已有源码。记录 JAR 版本与证据范围，查证限定在目标配置的库内。
 
 ### 元数据文件
 

package/skills/cosmic-build/references/compile-guide.md

@@ -1,78 +1,65 @@
-# Java 插件窄范围编译
+# Java 插件编译
 
-精简编码 agent 只读一次本指南并负责窄范围编译。父会话消费其 `source_ready` 结果，不得
-再次编译同一个类。直接使用 handoff 中的
-`sourcePath/className/fqcn/formNumber/operationKeys`，禁止重新读取会话、归档或元数据来
-重建这些值。
+实施者负责编译，直接使用交接值；`{ROOT_DIR}` 由根技能提供。
+原生命令负责配置、模块解析、源码检查、编译、归档写入和 `source_ready` 门禁。
 
-## 1. 调用唯一编译边界
+## 执行
+
+优先使用已准备的上下文，由准备入口提供身份、操作键和 1–20 字描述：
+
+```text
+{python} "{ROOT_DIR}/scripts/compile_plugin_source.py" --handoff "{handoffPath}"
+```
+
+没有交接文件时，仍支持手动单源码输入：
 
 ```text
 {python} "{ROOT_DIR}/scripts/compile_plugin_source.py" \
   --project-root "{projectRoot}" --app-root "{appRoot}" \
   --source-path "{sourcePath}" --class-name "{className}" \
   --plugin-type "{type}" --form-number "{formNumber}" \
-  [--operation-key "{key}"] --description "{coreLogic 20字摘要}"
+  [--operation-key "{key}"] --description "{1-20字业务摘要}"
+```
+
+每个操作键单独传一次 `--operation-key`，为空则省略。同模块中多个已准备、已写入的源码
+使用一次批量调用：
+
+```text
+{python} "{ROOT_DIR}/scripts/compile_plugin_source.py" --project-root "{projectRoot}" --app-root "{appRoot}" --sources-file "{sources.json}"
 ```
 
-脚本统一负责编译配置、Gradle 模块解析、窄范围 `compileJava`、占位实现拦截、结构化诊断、
-归档写入和 `source_ready` gate。每个操作 key 重复传入一次 `--operation-key`，为空时整项省略。
-调用前后都不得检查 `settings.gradle`、`build.gradle`、Gradle 缓存、jar、环境变量或兄弟工程。
-
-## 2. 在封闭证据内修复
-
-- `status=true` 且 `compileSkipped=false`：编译、归档及源码就绪 gate 均通过。直接返回源码就绪结果，
-  不再重复编译或归档。
-- `status=true` 且 `compileSkipped=true`：`appconfig` 中 `compile=false`，窄范围编译被配置跳过。
-  归档项和源码就绪 gate 已写入，注册可以继续，但没有任何东西证明源码能编译。此时报告
-  `source_ready（按配置跳过编译）`，绝不能声称该类已编译通过。源码闸门仍然执行了，结果里的
-  `uncheckedWithoutCompile` 列出它们覆盖不到的部分——每道闸门都刻意比 javac 更窄，而在 javac
-  缺席时这些缺口就是全部剩余风险。
-- `PLUGIN_SOURCE_PLACEHOLDER_BLOCKED`：外部/数据依赖未闭合，按 `L3-BLOCK` 停止；禁止把
-  占位符改成猜测的实体、字段、服务或零值兜底。
-- `PLUGIN_SOURCE_RETURN_TYPE_MISMATCH`：某个平台调用被赋给了它登记签名并不返回的类型。每条
-  issue 都给出调用、声明类型和登记返回类型；把声明改成登记的返回类型。该检查在编译之前执行，
-  `compile=false` 时同样生效——那种配置下它是凭记忆写的签名与注册之间唯一的拦截。禁止用强制
-  类型转换绕过，也禁止把声明放宽成 `Object`。
-- `PLUGIN_SOURCE_QFILTER_STRING_OPERATOR`：`QFilter` 的比较操作符写成了字符串字面量。issue
-  带 `preferred` 时用那个辅助方法（多数 `QCP` 成员是 `@SdkInternal`）；没有时替换为 issue 给出的
-  `QCP` 常量并 import `kd.bos.orm.query.QCP`。替换时不要改动操作符本身。
-- `PLUGIN_SOURCE_NONEXISTENT_MEMBER`：某个调用用了并不存在的平台成员。每条 issue 都带上该调用
-  及其 `replacement`（已对照平台 API 参考验证）；换成该成员，并按它的签名调整实参。禁止通过强制
-  类型转换、换一个接收者或反射去够同一个名字——该成员是不存在，而不是不可访问。
-- `PLUGIN_SOURCE_LIFECYCLE_MISUSE`：某个调用写在了一个它根本无法生效的生命周期方法里。这里没有一个
-  调用本身是错的——每一个在另一个方法里都是写同一件事的正确写法——所以 javac 接受它、注册也会
-  成功，缺陷最后以“插件没反应”或“值默默变回去了”的形式到达用户。每条 issue 都点明当前所在方法
-  和应归位置；把调用移到那里，而不是删掉它；也不要靠改方法名或套一层辅助方法去绕过这项检查。
-- `PLUGIN_SOURCE_BASE_CLASS_MISMATCH`：`extends` 声明的不是登记在册的插件基类——是登记类的大小写或
-  包路径拼写错误，例如把 `kd.bos.bill.AbstractBillPlugIn` 写成 `kd.bos.form.plugin.AbstractBillPlugin`。
-  拼错的类名并非平台类：最好情况也只是在 javac 处得到一句既不含正确类名、也不含原因的
-  `cannot find symbol`；`compile=false` 时更会不经校验直接注册，直到平台加载该类才失败。替换成每条
-  issue 给出的 `registeredBaseImport`；不要只改大小写或只改 import 却留着错误的包路径。
-- `PLUGIN_SOURCE_OVERRIDE_SIGNATURE_MISMATCH`：某个 `@Override` 声明的参数不被基类任何登记签名接受——
-  例如把 `propertyChanged(PropertyChangedArgs e)` 写成 `propertyChanged(PropertyChangedEventArgs e)`。
-  凭记忆写出的参数类并非平台类：最好情况也只是在 javac 处得到一句不含正确签名的 `cannot find symbol`，
-  `compile=false` 时更会不经校验直接注册；即便该类碰巧存在，方法也只是一个平台永远不会调用的重载。
-  照抄每条 issue 给出的 `registeredSignatures` 签名。
-- `PLUGIN_SOURCE_UNVERIFIED_API`：某条 import 或成员调用写的是登记 API 凭记忆拼出的拼写——简单名
-  case-fold 后唯一命中某个登记类（把 `kd.bos.bill.AbstractBillPlugIn` 写成
-  `kd.bos.form.plugin.AbstractBillPlugin`），或成员与接收者类链登记的某个签名相似（把
-  `getEntryRowCount` 写成 `getEntryCount`、把 `ftlike` 写成 `ftLike`）。凭记忆的名字并非平台名：
-  最好情况也只是在 javac 处得到一句不含替代名的 `cannot find symbol`，`compile=false` 时漂移会
-  未经校验直达注册。照抄每条 issue 给出的 `registeredImport` 或 `registeredSignatures`。页面只
-  收录 `@SdkPublic` 导出集，与任何登记名都不相似的 import 或成员不构成发现：不要为过检而改宽
-  真实名字，也不要把未被报告的名字当作已验证。
-- `PLUGIN_COMPILE_FAILED`：只使用返回的 `diagnostics`、已选 type guide、该 guide 点名的
-  精确 API 参考及当前 Java 模块附近代码。修复目标源码后重调同一脚本。
-- 配置/模块错误：原样报告该边界，禁止手工重建 Gradle 命令。
-
-一次修复可同时处理同一轮全部诊断。反复猜 API、搜索 jar 或做编译器试验都不是证据来源。
-
-## 3. 编译证明
-
-源码文件存在、自检通过、手工 Gradle 成功或单独更新归档都不是本流程的交付证明。只有
-`compile_plugin_source.py` 返回 `status=true` 才建立 `source_ready`，而只有 `compileSkipped=false`
-才进一步证明源码可编译。
-
-注册及其回读只属于父会话在 `references/java-plugin-delivery.md` 中定义的收口职责；编码 agent
-到 `source_ready` 即停止。
+优先使用 `{handoffPath}` 数组，每个类保留自己的元数据和类型证据；所有交接必须属于传入的工程与应用。
+仍兼容 `{sourcePath, className, type, formNumber, operationKeys, description}` 输入；没有交接时，
+回执明确标记 `fieldAccessorCheck="not-run-no-handoff"`。源码检查逐类执行，同次调用共享模块构建。
+
+## 使用结果
+
+| 结果 | 后续动作 |
+|---|---|
+| `status=true`、`compileSkipped=false` | 源码、编译、归档和门禁已成功，继续交付，不重复构建。 |
+| `status=true`、`compileSkipped=true` | 报告 `source_ready (compile skipped by config)`。可以注册，但未证明编译通过；保留 `uncheckedWithoutCompile` 列出的检查缺口。 |
+| 失败 | 根据结构化诊断修复所指出的边界，再重试原生命令。未解决的外部契约保持 `L3-BLOCK`。 |
+
+交付前根据实际接收者和字段核实 `sourceWarnings`。TimeProp 提示不直接阻断编译，因为源码扫描
+不能证明实体归属或 Java 作用域；确认访问器错误后修正源码，合法无关接收者则在结果中说明。
+操作 Map 键与适用范围提示同样需要准确分派证据，保留需求规定的操作专属行为。`sourceReview`
+仅是源码清单，不代表 AC 覆盖已验证。成功构建的 `buildContext` 提供已解析的 Gradle 根、wrapper、
+模块和候选测试任务，后续复用该绑定环境，避免重新搜索其他工程。
+
+将诊断提供的替换或签名应用到对应接收者和生命周期；缺失 API 证据通过编码入口的查询或准确
+参考页补齐。已注册文档仍无法确认必需签名时，可对已绑定项目的实际 SDK 做有限的只读检查；
+不要从其他项目推断接口，也不要搜索无关 jar 或缓存。不使用强转、改插件类型、删除业务行为或
+伪造值绕过检查。模块/构建问题按准确诊断处理，不手工拼 Gradle 命令；目标模块附近代码可辅助定位源码错误。
+
+集中修复共同诊断。批量结果每个模块最多抽样五条，只有不足以定位时才读 `logPath`。
+同任务其他源码报错可能是共同原因，不能直接归为无关缺陷。做出相关修复后再重试，不原样重复。
+
+只有成功的原生结果能建立源码就绪状态，不手工写归档或门禁。
+随后按请求范围返回 [java-plugin-delivery.md](java-plugin-delivery.md) 做注册、源码一致性检查和收尾。
+
+独立源码问题在 `errorCodes` 中一并返回，集中修复后再调用编译。
+
+编译回执的 `loadingVerification.runtimeVerified` 仍为 false。默认 Gradle class 产物可观察时，
+`compiledArtifact` 绑定其 FQCN 和哈希；跳过编译或自定义输出未观察时为 null。报表运行测试
+按 [report-filter-contract.md](report-filter-contract.md) 使用只读加载 CLI 后再验收业务。
+复制 class 或重启 JVM 不等于加载证据。

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

@@ -1,6 +1,15 @@
 # 本轮交付
 
-在当前用户请求的修改和必要验证完成后读取。只读查询不进入本流程。
+当前请求进入完整交付或明确的部分交付时读取。只读查询不进入本流程。
+
+已准备完成适配器时，当前有效范围全部实现可提交 `{environmentFile, completed:"all", evidence:[真实实现引用], summary, notes}`，由程序展开范围。只有真实例外才填写 `remaining:[{itemId,reason,category}]`，类别为 `implementation|verification|decision|environment`。正常等待 QA 属于阶段边界，不逐项登记为 remaining。部分证据仍用 `completed:[{itemId,evidence}]`；不能把单次命令成功当作全部实现，实际缺口必须保留，元数据回读不等于运行验收。
+
+运行收口器前，对照原始需求核对已经验证的实际实现。先完成仍可执行的元数据、Java 行为和
+明确要求的菜单工作。尚未开始的必要插件属于剩余实现，不能只列为“待验收”。元数据无法表达
+该行为时使用 [java-plugin-delivery.md](java-plugin-delivery.md)。
+菜单发布还包括菜单入口要求的应用启用及验证步骤。
+Java 插件已注册但仍等待用户选择或确认服务重启时，继续完成独立交付，将插件运行态保留为
+未验证；不得把注册回执当成验收证据。
 
 `deleteForm` 验证表单已删除后，该表单没有可打开的产物，只报告删除目标和验证，不运行卡片
 收口。删除字段、规则、操作、控件或其他元数据元素后，表单仍然存在，继续为该表单生成卡片。
@@ -15,12 +24,43 @@
 {python} {ROOT_DIR}/scripts/render_output_cards.py --app-root "<appRoot>" --forms-only --form-number "<表单A>" --form-number "<表单B>"
 ```
 
-每个本轮目标分别传一次 `--form-number`。必需事项仍未解决或写后状态未知时，不执行收口。
+每个本轮可交付目标分别传一次 `--form-number`。
+
+收口器同时返回 `TEST_ENVIRONMENT_HANDOFF` 并保存脱敏的 `_runtime/test-environment.json`。
+开发交给 QA 的摘要标题统一使用 `<应用名称> — 开发实现交付摘要`；英文使用
+`<Application name> — Implementation Delivery Summary`，产物路径沿用 `delivery-summary.md`。
+正式完成适配器已准备时，在输入中传 `environmentFile: TEST_ENVIRONMENT_HANDOFF.path`，由程序原样嵌入环境，模型不转抄。
+仅手工兼容交接才把 `environment` 作为 `json` 围栏块嵌入摘要，
+保留 `schemaVersion: "cosmic-test-environment/v1"`、完整 baseUrl（端口及租户路径）、账套和应用/表单身份。
+同时交接实际 previewUrl/listUrl、已发布菜单名称及导航路径，区分表单显示名、菜单名与元数据 ID。
+QA 默认从准确浏览器入口验收，不依赖 CLI alias。正式用户入口未实施或未验证时明确记录，
+不能用直达预览可用替代菜单入口通过。
+只有 `listUrl` 与编辑预览地址不同时才交接列表入口。平台对 `viewType=list` 返回编辑地址时，交付器先核对 `getFormSchema` 的列表元数据，再使用已验证的标准 `bos_list` 入口；两条路线均无法确认列表地址时才记录入口缺失。
+环境块必须随摘要传递，不能只链接被忽略的 runtime 文件，否则跨工作树不可用。
+只补充本次已确认的运行态 context、ERP loginUser 和 authMode；不把元数据 API 身份猜成 ERP 账号，
+不复制密码、cookie、token、appSecret。Java 部署/加载与未运行检查单独记录。
+元数据回读和模板默认操作只证明实现配置；运行态 AC 保留 not-run，直到 QA 在同一环境中取得实际行为及持久化证据。
+
+正式专家团阶段已经提供 `nextOperation` 时，只在指定输入文件中填写 `environmentFile`、实际实现证据
+（`completed` 与必要的 `remaining`），可补简短 `summary` 和实际部署/未验证 `notes`，再调用
+`nextOperation` 一次。程序生成 `delivery-summary.md`，模型不重新排字段表、转抄环境 JSON 或写摘要文件。它统一完成需求/AC 引用归一化、冻结基线绑定、产物校验和阶段结算。
+不要再调用 `bind-delivery`、查校验器源码、创建单独的 StageResult 文件或重复读取成功回执。
+`.expert-team` 状态归运行时管理，不是手工输入目录；运行态验收仍交质量阶段。
 
-后续轮次修改属性后仍需本轮交付，即使之前已经展示过同一表单的卡片。成功属性回执提供
+只有没有完成适配器的独立交接才使用[应用上下文](application-context.md)中的底层
+`bind-delivery`。用户确认范围变更后，只调整受影响实现，再沿同一完成入口绑定；已撤回项
+不算未完成工作。保持一个环境块。
+
+- 仍可执行的明确需求继续完成，部分交付不是提前停止工作的理由。
+- 某事项因能力不支持或缺少业务决定而确认未执行时，完成独立事项，交付已验证修改，
+  并明确说明待处理内容。
+- 写入状态未知时，先查明该表单的状态，再交付该表单；其他独立验证通过的表单可以交付。
+  卡片不代表待处理事项已完成。
+
+后续轮次修改属性后仍需本轮交付，即使之前已经展示过同一表单的卡片。成功修改回执提供
 待执行的 `delivery.command`；汇总这些目标，在本轮写入结束后收口一次。
 
-收口器不等待 DYM 同步。本轮仍存在的目标表单会通过 stderr 返回
+收口器不等待 DYM 同步。本轮仍存在的目标表单会在卡片块之后通过 stdout 返回
 `DYM_BACKGROUND_REQUEST`，并保存持久化队列请求。使用宿主 Bash 工具执行返回的 command，
 设置 `run_in_background=true`、`preview=false`，保留 job ID；不等待任务结束，继续交付卡片。
 禁止启动无法追踪的脱离子进程。请求文件记录 queued/running/succeeded/failed/skipped；
@@ -28,11 +68,23 @@ queued/running 不代表源码已同步。宿主不能启动后台任务时说
 只有用户明确要求“源码同步完成后交付”时才加 `--wait-dym`。两种模式均导出 DYM/DYMX 到配置的同步目录，
 文件不存在则创建，已存在则更新；报表运行时证据导出与源码同步无关。后台完成通知只更新源码同步状态，不再生成或重复产物卡片。
 
-收口器返回三行协议块：协议头、一行 JSON、结束符。协议块只出现在工具结果中不代表已经
-交付；必须保留每个返回块，并原样放进最终答复。不在进度说明里展示卡片，也不另列预览或
-设计器链接。宿主提供 `output_check` 时，取得协议块后调用一次，先说明变更结果和必要的未完成
+专家团共享交付中，保留协议块与目标/检查引用供负责人最终答复使用，继续团队已约定的流程。
+子任务将结果交回负责人；内联执行在同一会话继续。生成卡片不代表团队适用的验收已经完成。
+负责人选择验收入口，完成对应检查或明确报告具体阻塞原因及未测范围后收尾。用户仅要求
+实施时沿用其约定终点；独立 app-build 在要求的实现完成后收尾。
+
+以下卡片格式同时适用于独立 app-build 和专家团共享交付。收口器返回三行协议块：
+协议头、一行 JSON、结束符。协议块只出现在工具结果中不代表已经交付；必须保留每个返回块，
+并原样放进最终答复。不在进度说明里展示卡片，也不另列预览或设计器链接。在约定终点，
+独立 app-build 呈现最终交付时，在宿主提供 `output_check` 时调用一次；正式团队阶段沿完成入口直接交付，不重复调用。
+先说明变更结果和必要的未完成
 事项，再在最终答复末尾集中展示本轮卡片，完成答复。必须使用渲染器返回的准确协议块；仅说明
 “渲染成功”不能替代协议块。
+解释面向业务用户：用表单名称说明可用功能、实际测试结果和未完成行为，不复述应用/表单编码、原始路径、状态字母、回执标记、后台任务编号或命令名称。
+自行撰写摘要卡片或报告链接时，标题与描述使用业务名称和有含义的说明，路径只用于内部引用；渲染器已返回的协议块仍原样保留。
+不能用“配置回读成功”等技术检查代替尚未验证的业务结果。
 不要因空白或换行差异重发已交付的卡片。
 
 DYM 失败不否定已验证的业务修改，也不阻止卡片交付。单独说明源码同步边界，不重放平台写入。
+
+正式阶段的完成命令返回 verified=true 且执行范围完成后，直接交付结果。不要再调用 output_check、查询源码同步后台任务或追加退出检查；源码同步状态按已知事实报告。用户明确要求等待同步时，应在完成阶段前满足该要求。文中的通用 output_check 约定只用于独立 app-build。

package/skills/cosmic-build/references/execution-contract.md

@@ -21,10 +21,18 @@ ImportError 或内置符号缺失属于技能安装缺陷，不是业务参数
 
 保留结构化 stdout 和退出状态。不得使用 `head`、`tail` 或 Shell 管道掩盖失败。
 大输入使用命令支持的 UTF-8 JSON 文件。认证由 CLI 处理，不读取凭据、Cookie 或令牌缓存。
+解析 JSON 时只消费 stdout；`2>&1` 会混入 stderr 的鉴权提示，使有效 JSON 解析失败。
 
 只有结果包含该命令的正向验证时，修改才算完成。Shell 成功、保存响应或后台句柄都不单独构成证明。
 已有独立回读时复用它，不重复读取同一事实。
 
+执行需求或 Spec 时，逐项比较要求的业务行为与实际配置行为。回读通过只证明该配置，
+不证明需求已覆盖：非空检查不能代替唯一性、日期范围或长度校验；空白页面和未实现操作
+仍属部分交付。Goal 续跑继续保留未决业务定义，非目标只约束其明确点名的范围，
+某个集成不在范围内不等于全部 Java 工作被排除。
+能力不明确时使用 `catalog --search <能力>` 与匹配的领域契约；猜测的命令名不存在，
+不能作为整个能力缺失的依据。
+
 写后未知或只部分验证时，保留回执并先确认真实状态再决定重试；后续修复不能倒推之前未知写入成功。
 结果要求披露时，在完成说明中保留该边界。
 
@@ -34,3 +42,33 @@ ImportError 或内置符号缺失属于技能安装缺陷，不是业务参数
 
 保留 CLI 运行状态，便于后续回合继续。`_runtime`、`metadata/_emit`、`modify`、`archive.json`
 及锁文件是运行状态，不是源码交付物。
+
+## 绑定来源与批量续跑
+
+初始化返回 `executionBinding`，包含实际技能根目录、命令修订、Python 可执行文件和
+准确 CLI 入口。同一应用持续复用这些值；来源、修订或环境不一致时，重新绑定所选的
+已安装技能，不执行工作区旧副本，也不自行编辑其实现。
+`describeCommand` 提供 `execution.argvPrefix` 与解析器生成的参数契约。各参数作为
+独立值传入，复杂输入使用命令支持的 JSON 文件。
+`--stdout --output <path>` 同时返回相同完整 JSON 并写入 UTF-8 文件；诊断只进入 stderr，
+参数失败也保持机器输出可解析。
+
+`runBatch` 在发出写入前、每个对象及根保存回执返回后，持续保存原有结果文件。
+输入修订、准确身份、验证、阶段与剩余步骤在中断后仍保留。仅当 `resume.ready=true`
+时执行返回的续跑参数；原 artifact 列表包含已成功依赖，它们直接复用验证回执，不重新
+创建或再次查身份。只有已确认未写入的输入可原地修正；成功输入保持原样。
+已保存对象的修订或名称变化由既有表单修改命令处理，同时修改受影响引用。
+
+写入未知时先执行返回的核对读取。原执行进程结束或退出后，才可使用
+`runBatch --resume-result <resultPath> --reconcile-only --verify`；实际执行时使用返回的
+`reconcile.arguments` 和 Python/入口路径，完整保留应用、输入与模板参数。该模式只读取平台。
+确认目标不存在后释放该目标，下一次显式续跑才执行创建。同名线上对象不能自动认作
+本请求的成功回执。已保留准确身份的对象继续使用原修复计划，窄范围修复，不重建。
+保留结果文件与目标占用回执，不通过删除或编辑它们绕过未知状态。
+新建前再次核对冲突；有引用依赖的写入按波次执行，`--flat-parallel` 拒绝本批依赖。
+
+失败返回 `errorCategory` 与 `capabilityLimitConfirmed`，区分输入、身份解析、环境、
+业务校验、有证据的能力限制和未知写入；未归类错误保留 `unknown`。
+引用未解析、缺参数或 CLI 命令不可用均不能证明平台不支持，也不能直接转为插件实现。
+
+业务 POST 请求丢失响应后不自动重放；GET 读取仍保留有界瞬时重试，已确认的鉴权拒绝仍走既有刷新路径。创建前的模板/冲突读取异常明确标记未写入；批次汇总保留各对象的真实写入边界，不能把未知状态折成零写入。

package/skills/cosmic-build/references/form-discovery.md

@@ -1,7 +1,11 @@
 # 查找表单与所属应用
 
 使用下列已有只读 CLI。准确应用编码已经是完整查询范围，无须初始化应用或准备修改绑定。
-`ROOT_DIR` 是根入口定义的包目录，不是其 `scripts/` 目录。
+`{ROOT_DIR}` 是根入口定义的包目录，不是其 `scripts/` 目录。
+
+需要程序解析 JSON 时，使用 CLI 的 `--output "<本次查询专属.json>"` 并读取该文件。
+认证和诊断日志写在 stderr；`2>&1` 会把它们混入 JSON。`head`/`grep` 截断的输出
+不能用于证明查询完整性。
 
 已知准确应用编码，列出该应用下全部表单时不传 `--keyword`：
 
@@ -20,6 +24,8 @@
 修改请求已给出应用显示名与准确表单时，由所选写命令使用 `--project-root`、`--app-name`、
 `--form-name` 直接绑定。应用名称不是 `--appNumber` 所需的编码。
 业务云过滤必须使用准确编码而非显示名。回执 `queryScope` 说明实际范围；空结果只代表该范围无匹配。
+关键词未命中不证明外部业务对象在环境中不存在。继续确认准确名称/编码，或保留未解析依赖；
+澄清目标时保留用户要求的引用字段类型。
 
 全局查找，或尚不清楚表单名称对应哪个应用：