@shundoo-ai/dsh-cosmic 1.0.21 → 1.0.22

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

@@ -26,6 +26,14 @@ Java 插件已注册但仍等待用户选择或确认服务重启时，继续完
 
 每个本轮可交付目标分别传一次 `--form-number`。
 
+渲染器通过 stdout 返回 `PREVIEW_EVIDENCE`，并按表单保存到 `archive.previewEvidence`。
+`fresh` 只证明本次读取取得链接，不证明页面或查询运行成功；`archived` 仅在瞬态失败后复用同协议、
+同主机、同环境路径的历史链接；`unavailable` 表示没有已确认的当前链接。历史链接不得包含认证凭据。
+主预览读取失败时跳过列表读取；名称读取失败时以精确表单编码降级标题。
+证据状态、检查时间及错误/可重试信息与卡片协议分开保留，卡片格式不变。
+GET 网关失败（502/503/504）有界重试；POST 修改不自动重放。持续网关故障仍是外部阻塞，
+不表示报表不存在或权限已变化。预览证据、Java 生效与 DYM 同步分别说明。
+
 收口器同时返回 `TEST_ENVIRONMENT_HANDOFF` 并保存脱敏的 `_runtime/test-environment.json`。
 开发交给 QA 的摘要标题统一使用 `<应用名称> — 开发实现交付摘要`；英文使用
 `<Application name> — Implementation Delivery Summary`，产物路径沿用 `delivery-summary.md`。
@@ -35,7 +43,7 @@ Java 插件已注册但仍等待用户选择或确认服务重启时，继续完
 同时交接实际 previewUrl/listUrl、已发布菜单名称及导航路径，区分表单显示名、菜单名与元数据 ID。
 QA 默认从准确浏览器入口验收，不依赖 CLI alias。正式用户入口未实施或未验证时明确记录，
 不能用直达预览可用替代菜单入口通过。
-只有 `listUrl` 与编辑预览地址不同时才交接列表入口。平台对 `viewType=list` 返回编辑地址时，交付器先核对 `getFormSchema` 的列表元数据，再使用已验证的标准 `bos_list` 入口；两条路线均无法确认列表地址时才记录入口缺失。
+只有 `listUrl` 与编辑预览地址不同时才交接列表入口。平台对 `viewType=list` 返回编辑地址时，交付器先核对 其内部元数据读取 的列表元数据，再使用已验证的标准 `bos_list` 入口；两条路线均无法确认列表地址时才记录入口缺失。
 环境块必须随摘要传递，不能只链接被忽略的 runtime 文件，否则跨工作树不可用。
 只补充本次已确认的运行态 context、ERP loginUser 和 authMode；不把元数据 API 身份猜成 ERP 账号，
 不复制密码、cookie、token、appSecret。Java 部署/加载与未运行检查单独记录。
@@ -44,6 +52,10 @@ QA 默认从准确浏览器入口验收，不依赖 CLI alias。正式用户入
 正式专家团阶段已经提供 `nextOperation` 时，只在指定输入文件中填写 `environmentFile`、实际实现证据
 （`completed` 与必要的 `remaining`），可补简短 `summary` 和实际部署/未验证 `notes`，再调用
 `nextOperation` 一次。程序生成 `delivery-summary.md`，模型不重新排字段表、转抄环境 JSON 或写摘要文件。它统一完成需求/AC 引用归一化、冻结基线绑定、产物校验和阶段结算。
+原生写入及回读证据覆盖所有当前可结算的实现项时，使用 `completed: "all"` 加非空 `evidence`，
+不逐条抄写需求编号，也不据此宣称运行态验收通过。适配器自动展开冻结基线，将受待确认业务决定
+阻断的事项记入 `remaining: decision`；`remaining` 只补充实际例外。不能把待决事项写成已完成，
+也不能为了通过结算改写冻结的需求文档。
 不要再调用 `bind-delivery`、查校验器源码、创建单独的 StageResult 文件或重复读取成功回执。
 `.expert-team` 状态归运行时管理，不是手工输入目录；运行态验收仍交质量阶段。
 
@@ -76,7 +88,9 @@ queued/running 不代表源码已同步。宿主不能启动后台任务时说
 以下卡片格式同时适用于独立 app-build 和专家团共享交付。收口器返回三行协议块：
 协议头、一行 JSON、结束符。协议块只出现在工具结果中不代表已经交付；必须保留每个返回块，
 并原样放进最终答复。不在进度说明里展示卡片，也不另列预览或设计器链接。在约定终点，
-独立 app-build 呈现最终交付时，在宿主提供 `output_check` 时调用一次；正式团队阶段沿完成入口直接交付，不重复调用。
+独立列表修改由 `scripts/configure_list.py` 完成时，原生卡片 stdout 已激活现有输出校验，
+仅保留其卡片并启动返回的可追踪 DYM 任务，不重渲染、不调用 `output_check`；
+无变更及零写入拒绝不发新卡或复用旧卡。其他独立 app-build 呈现最终交付时，在宿主提供 `output_check` 时调用一次；正式团队阶段沿完成入口直接交付，不重复调用。
 先说明变更结果和必要的未完成
 事项，再在最终答复末尾集中展示本轮卡片，完成答复。必须使用渲染器返回的准确协议块；仅说明
 “渲染成功”不能替代协议块。

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

@@ -26,12 +26,22 @@ ImportError 或内置符号缺失属于技能安装缺陷，不是业务参数
 只有结果包含该命令的正向验证时，修改才算完成。Shell 成功、保存响应或后台句柄都不单独构成证明。
 已有独立回读时复用它，不重复读取同一事实。
 
+所选命令支持时，复用同一已验证表单及父级范围内的实际字段 key，尤其是存在同名字段时。
+身份缺失或已失效时才使用定向读取或 writer 解析，不从翻译名或 ISV 前缀拼造平台 key。
+
+用回执中的准确目标、属性名、期望值、实际值和失败项核对剩余工作。原生回读包含继承后实际
+生效的元数据；DYM 导出是源码表示，可能省略继承控件，缺少导出节点不能推翻已通过的属性回读。
+未覆盖的具体维度用对应原生读取命令核实，不为此导出整单再逐段解析；用户要求的运行态检查另行执行。
+
 执行需求或 Spec 时，逐项比较要求的业务行为与实际配置行为。回读通过只证明该配置，
 不证明需求已覆盖：非空检查不能代替唯一性、日期范围或长度校验；空白页面和未实现操作
 仍属部分交付。Goal 续跑继续保留未决业务定义，非目标只约束其明确点名的范围，
 某个集成不在范围内不等于全部 Java 工作被排除。
-能力不明确时使用 `catalog --search <能力>` 与匹配的领域契约；猜测的命令名不存在，
-不能作为整个能力缺失的依据。
+能力不明确时遵循[根入口](../SKILL.md)的命令发现与契约消费规则。
+
+只有输入已完整且互不依赖结果时才合并安排命令，优先使用已发布批量 writer。修改同一表单
+元数据的多个写入必须串行，不作为并行工具调用。合并执行需保留每条 stdout 和退出状态，
+失败即停；依赖步骤和交付前检查验证结果，不能让最后一条成功掩盖前面的失败。
 
 写后未知或只部分验证时，保留回执并先确认真实状态再决定重试；后续修复不能倒推之前未知写入成功。
 结果要求披露时，在完成说明中保留该边界。
@@ -48,7 +58,9 @@ ImportError 或内置符号缺失属于技能安装缺陷，不是业务参数
 初始化返回 `executionBinding`，包含实际技能根目录、命令修订、Python 可执行文件和
 准确 CLI 入口。同一应用持续复用这些值；来源、修订或环境不一致时，重新绑定所选的
 已安装技能，不执行工作区旧副本，也不自行编辑其实现。
-`describeCommand` 提供 `execution.argvPrefix` 与解析器生成的参数契约。各参数作为
+从同一安装包的另一个语言入口调用时，编译器和 CLI 自动复用已绑定的运行时；不同安装目录、
+修订变化及环境变化仍要求显式重新绑定。
+`describeCommand` 提供 `action.execution.argvPrefix` 与解析器生成的参数契约。各参数作为
 独立值传入，复杂输入使用命令支持的 JSON 文件。
 `--stdout --output <path>` 同时返回相同完整 JSON 并写入 UTF-8 文件；诊断只进入 stderr，
 参数失败也保持机器输出可解析。

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

@@ -1,17 +1,12 @@
 # Java 插件交付
 
-实现所选元数据入口无法表达的行为，`cosmic-coding-impl` 提供 Java 实现指导。
+为已确认目标或现有源码实现用户要求的 Java 行为，`cosmic-coding-impl` 提供实现指导。
 `{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` 后注册已归档类，并验证注册结果：
+1. 用户未指定 Java 源码目录或已有源码时，先通过 `question`（AskUserQuestion）询问并等待；已有用户选择直接复用。
+2. 按[业务触发边界](plugin-runtime-routing.md)选定类型，执行 `{python} "{ROOT_DIR}/scripts/platform_api_contract.py" --describe-plugin-type "{type}"`，沿返回的准确 `codingEntry` 与 `guide` 读取，不手拼安装或语言目录。
+3. 编码技能自行获取当前在线元数据和目标 SDK，编写源码并按 [compile-guide.md](compile-guide.md) 编译归档；不要求上游 handoff 或元数据阶段产物。同模块源码齐备后批量构建，保留全部 AC 和质量约束。
+4. 用户范围包含平台绑定时，达到 `source_ready` 后注册已归档类并验证；仅交源码时完成所需源码和编译后结束：
 
 ```text
 {python} "{ROOT_DIR}/scripts/register_plugins.py" --app-root "{appRoot}" --class-name "{fqcn1}" [--class-name "{fqcn2}"] --verify
@@ -19,14 +14,27 @@
 
 注册会核对归档的 `sourceHash`、`compileStatus` 与当前源码。缺少证明或源码已变化时返回
 原生编译入口。失败时诊断同一类和目标，不通过更换运行类型获得注册成功。
+报表的 `reportform` 在这里注册到 `BILL_FORM`；`reportlist` 转交 `registerReportPlugin`，
+`reporttreelist` 使用已有左树的属性路由。`routed`/`partial` 与 `summary.deferred` 是待执行的注册事项，
+不算注册成功；只有准确身份匹配的真实回读才能标记 `verifiedHere=true`。
 
-报告准确的类、受影响表单，并分别说明编译、注册和回读结果；注册后跳过的编译仍为跳过。
+客户自行打包并通过 DCS 部署，必须在交付前按 [DCS 代码规则](dcs-code-rules.md)
+扫描一次整个模块，覆盖编译步骤未检查的旧类和随附文件，修复阻断项并处理建议项：
+
+```text
+{python} "{ROOT_DIR}/scripts/dcs_code_gate.py" --source "{projectRoot}"
+```
+
+报告准确的类、受影响表单，并分别说明编译、注册、回读结果以及扫描的 `findingCount` / `advisoryCount`；
+注册后跳过的编译仍为跳过。
 `activation.runtimeVerified=false` 表示尚未验证运行态生效与行为；`requiresServiceRestart=null`
 表示工具无法确定目标环境是否需要重启。注册回读本身不能证明插件已生效或业务正确。
 生效方式依据所选环境的部署契约和已有授权确定；后续源码变化后刷新原生检查，
 在运行态检查前核实目标实际运行的是更新后的版本。
 
 业务验收依据原始需求，验证真实状态流转和关联对象持久化，并核对校验没有增加未要求的副作用。
+运行验证前使用准备结果中的 `runtimeContextCommand`，或 `query_plugin_handoff.py runtime-context --handoff "{handoffPath}"`，取得同一绑定表单的准确入口。入口缺失时加 `--resolve-entry`，复用平台已有预览解析。登录使用已授权身份；不猜地址。
+
 插件检查失败时保留输入，并回读插件实际使用的日期、状态、引用 ID 等字段。改源码前，
 把候选原因与事件是否进入、查询命中数、运行插件版本及返回的校验错误等实测证据分开。
 证据无法取得时如实报告诊断缺口，不凭编译通过反复更换查询写法和重启。
@@ -36,3 +44,5 @@
 
 本环节不配置菜单，也不输出产物卡片。app-build 按 [delivery.md](delivery.md) 统一交付领域
 产物；菜单需要用户明确要求。
+
+纯页面控件和回调使用交接入口的 `metadataNeeds=["form"]`，无需持久化字段；已有非操作源码没有平台元数据依赖时使用 `[]`。源码任务仍沿原生编译归档入口，只有明确表单目标后才能注册。

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

@@ -1,8 +1,30 @@
-# 已验证的 Java 编码上下文
+# 编码技能自行获取上下文
+
+本流程由编码技能根据所选应用/表单和原始需求自行执行，不向上游索取 handoff，也不消费上游编码快照。
 
 使用根技能提供的 `{ROOT_DIR}`。准备源码前，先通过
 [plugin-runtime-routing.md](plugin-runtime-routing.md)确定业务触发点对应的类型。
 
+运行类型直接沿用 [plugin-runtime-routing.md](plugin-runtime-routing.md) 的已发布值，场景从所选类型的 guide 选取，
+不默认展开整个类型注册表或递归枚举全部场景目录。
+
+选定类型后执行 `{python} "{ROOT_DIR}/scripts/platform_api_contract.py" --describe-plugin-type "{type}"`，取得该类型的准确指南；只有指南未覆盖当前行为时才查返回的场景索引。
+
+## 按需选择元数据
+
+现有 intent 的 `metadataNeeds` 可选 `form`、`list`、`entity`、`operate`。
+无持久化字段的页面控件、参数和回调用 `["form"]`，列表控件用 `["list"]`；
+读写持久化字段或分录时增加 `entity`，需要实际操作定义时增加 `operate`。
+操作插件必须选择 `operate`，读写持久化字段时增加 `entity`。已有非操作源码若不依赖平台元数据，
+可用 `[]`，并指定 `ownershipMode="modify"` 和真实 `sourcePath`；此时表单编码为空，
+不能用于注册。省略该字段时保持原有实体准备路径。不得为通过准备新增字段，
+也不能把错误响应当作空页面。`uiContext` 包含已核实的页面控件与插件绑定；
+读取实体证据时才提供 `formGraph`。
+
+SDK 指南仅按所需能力读取：[ORM / QFilter](../knowledge/cosmic/platform/sdk/sdk-orm-access.md), [DataSet](../knowledge/cosmic/platform/sdk/sdk-algo.md), [ServiceHelper](../knowledge/cosmic/platform/sdk/sdk-dynamic-model-svc.md), [DynamicObject](../knowledge/cosmic/platform/sdk/sdk-dynamic-object.md), [EntityModel](../knowledge/cosmic/platform/sdk/sdk-entity-model.md), [ID](../knowledge/cosmic/platform/sdk/sdk-id.md), [Lock](../knowledge/cosmic/platform/sdk/sdk-lock.md), [Cache](../knowledge/cosmic/platform/sdk/sdk-cache.md), [Transaction](../knowledge/cosmic/platform/sdk/sdk-tx.md), [Log](../knowledge/cosmic/platform/sdk/sdk-log.md), [Exception](../knowledge/cosmic/platform/sdk/sdk-exception.md), [Thread pool](../knowledge/cosmic/platform/sdk/sdk-threadpool.md), [File](../knowledge/cosmic/platform/sdk/sdk-file.md), [Context](../knowledge/cosmic/platform/sdk/sdk-request-context.md), [Network control](../knowledge/cosmic/platform/sdk/sdk-network-control.md), [Utilities](../knowledge/cosmic/platform/sdk/sdk-utils.md)。
+
+已有源码没有平台元数据依赖时省略 `--form-number`，在 `--intent-file` 中提供
+`metadataNeeds: []`、`ownershipMode: "modify"` 和准确 `sourcePath`。
 ## 从已有表单独立准备
 
 ```text
@@ -13,10 +35,16 @@
 
 使用创建或已有表单发现返回的准确表单编码，不要求建模 artifact、manifest 或写入回执。操作插件即使传入回执，也只将它作为身份提示，
 仍读取原生结构。
-命令读取当前原生实体元数据（`getEntityType`）与操作，保存原始响应及完整的表头/分录/
+选择实体元数据时，命令读取当前原生实体元数据（`getEntityType`）与必要操作，保存原始响应及完整的表头/分录/
 子分录结构。关联表按声明解析；中文目标名称的候选限于主表引用目标。
 本地文件存在不代表元数据完整或仍为当前版本。
 
+身份或 Schema 的确定性错误保留准确目标和结构化诊断，先解决共同原因再重试该批次；
+不对每张表重复同一失败准备，不为过校验删除或改写 `archive.json`、切换 `appCode` 或更改 Java 包。
+原生 `BizAppNumber` 不同不影响编码，继续使用用户所选应用和准确表单编码。
+外部表缺少 `getEntityType` 不代表没有数据，仍可能支持 `getFormSchema`；入口支持时通过
+`--external-schema` 使用其准确成功响应，不伪造结构。
+
 启用编译时，`--prepare-source` 先确认已有 Java 工程准确映射一个真实 Gradle 模块，
 并从该模块的目标 SDK 核验类，再开放源码门禁。额外选用的接口通过
 `sdkUsage: [{"class": "<准确全限定类名>", "members": ["<声明的方法>"]}]` 指定。
@@ -25,15 +53,11 @@
 仅准备源码，但 SDK、编译和运行均标记未验证。准备与编译不持久化推导出的运行配置。
 编译、注册、重启和真实事件验证分别记录结果。
 
-`formGraph` 是编码依据，包含真实实体类型、集合属性名、父子关系、限定字段路径、类型、
+有运行实体的插件以 `formGraph` 为编码依据，包含真实实体类型、集合属性名、父子关系、限定字段路径、类型、
 引用目标和枚举值；`relatedForms` 包含关联数据的对应结构。`getDynamicObjectCollection`
 使用集合属性名，不能假设它与集合元素的实体类型名相同。继承和系统字段一并保留。
 不要从 authoring 名称推导这些信息、搜索旧源码，或手工重建 DYM/Schema 响应。
 
-编码前优先读取调用方提供的启动文件，或从原生 handoff 查询 `coding-start`。
-启动上下文包含字段/类型、状态值、可用操作、SDK 接收者接口和缺失细节的准确路径。
-大字段清单使用 `fieldsPath` 与 `fieldCount`，按需查询，不把省略的清单当作元数据不存在。
-
 这些事实描述结构和集合访问方式，不保证每个实体类型都是数据服务的查询根。
 不能仅因 `EntryType` 或 `SubEntryType` 出现在结构图中，就把它作为
 `QueryServiceHelper.query` 的独立根。以表单编码作为已知表单身份；
@@ -49,6 +73,30 @@
 旧调用和报表仍支持 `--run-result`、`--emit-manifest`、`--artifact`；有运行实体的 Java 编码
 以原生结构为准。报表或仅元数据页面没有运行实体时，按其领域读取契约获取上下文。
 
+### 报表编码与只读对账
+
+报表使用 `reportContract`，不得伪造空 `formGraph`。`coding-start` 与 `coding-context`
+提供 DataSet 列、Algo 类型、展示及过滤值/查询契约和准确 JSON pointer；大列表省略时仍可沿路径查询。
+报表输出列不是持久化业务查询根，外部实体需要独立声明并验证。
+
+增量写入后使用 `reportAuthoringState` 返回的当前 `artifactPath`，不沿用历史运行回执。
+本地 `current` 基线保留完整需求及可观察设计证据；`incomplete` 时先对账再编码。
+两种状态都不证明 Java 编译、部署或业务运行。
+
+准备时传入完整的当前报表 artifact，并添加 `--refresh-report-state`：
+
+```text
+{python} "{ROOT_DIR}/scripts/prepare_plugin_handoff.py" \
+  --app-root "{appRoot}" --form-number "{formNumber}" --type reportlist \
+  --artifact "{currentArtifactPath}" --intent-file "{intentPath}" \
+  --refresh-report-state --prepare-source
+```
+
+该入口只读 `getReportSchema`，核对精确身份及可观察的列/过滤条件，仅修复本地需求状态，
+不重建、不写平台。仅有运行元数据不足以恢复完整需求；不可观察属性和其他分区仍是需求，
+不是本次新取得的验证证据，行为依赖它们时另行核对。
+网关失败不表示实体不存在；显式 external-schema 输入必须提供已验证证据，不能用猜测代替。
+
 intent 描述业务行为和稳定选择器。从类型指南中选择适用 `scenes`，路径相对于
 `knowledge/cosmic/platform/scenes/`；准备入口会展开场景声明的 SDK 参考，提供准确导入和签名。
 例如校验及跨实体回写使用下面两个场景，只传实际适用项。
@@ -70,6 +118,9 @@ authoring ID 仅适用于旧 artifact 输入，不能去掉 ISV 前缀来构造
 编译器拒绝歧义；重名字段用表单/实体/字段限定。每项外部数据或服务依赖都在
 `specialized.externalContracts` 中声明为结构化对象，数据契约使用 `entity` 和 `fields`。
 失败回执里的相似字段只供核对，不能按前缀或后缀自动改写目标身份。
+每个契约对应一个已验证实体，表头和分录分别声明；字段使用准确键/显示名或 `{entity, field}`，
+不能当作带点的查询路径。核心逻辑引用规则集时，用已有 `specialized.evidence` 指向详细规则文件，
+“按规则引擎执行”不能代替优先级和边界条件；写入唯一键相互冲突时先解决再生成源码。
 需求已给出外部字段显示名时，直接在 `specialized.externalContracts` 使用该显示名；
 只有 authoring 标识时，先读取关联表单的当前元数据取得真实落库键，再准备 handoff，
 不自行拼接 ISV 前缀。
@@ -77,22 +128,30 @@ authoring ID 仅适用于旧 artifact 输入，不能去掉 ISV 前缀来构造
 不得提交空列表掩盖缺失契约。复杂或含 shell 敏感字符的 JSON 使用 `--intent-file`，
 它只是命令输入，不增加规划阶段。
 
+编码前，在 `specialized.externalContracts` 中声明需要读取值的引用实体，包括元数据带出不支持后遗留的依赖，
+并在 intent 中保留已观察的原生字段/集合证据。实体字段与集合名称属于元数据事实：优先查询已保存的图或
+已发布实体读取命令，不在 SDK/JAR 或无关源码中寻找；Java 接收者签名仍走 SDK 契约。
+集合带出单值须有业务选择规则，不默取首行。
+
 ## 消费交接结果
 
-准备入口默认返回 `contextMode="reference-only"` 的紧凑摘要和准确 `handoffPath`。
-完整文件继续保留本次线上读取的元数据和 SDK 证据，直接交给原生编译器。Java 编码先一次读取
-本类的字段、关联表、操作、状态警告和已注册 SDK 签名，其中包含 `QueryServiceHelper.query`
-的准确返回类型；不要直接 `read` 整份 JSON：
+准备入口返回紧凑摘要、准确 `handoffPath` 和可直接执行的 `codingStartCommand` 参数数组；直接使用该命令，不手写或重新查找路径。
+完整文件继续保留本次线上读取的元数据和 SDK 证据，直接交给原生编译器。
+只首读一次已提供的 `coding-start` 文件；未提供时才执行下列查询，取得字段/类型、操作/状态值及
+SDK 接收者的准确路径。不为重复这些事实再调用 `coding-context` 或展开整份 JSON。
+编码前沿准确路径补读缺失签名，包括 `QueryServiceHelper.query` 的真实返回类型。
+大字段清单使用 `fieldsPath` 与 `fieldCount`；省略不代表元数据不存在。
 准备后若平台元数据发生变化，先重新准备 handoff 再查询或编译；查询命令只读取已保存快照，不会刷新线上数据。
+`inputFiles` 保存绝对路径和 SHA256。输入变化、消失或不可读时，查询/编译拒绝旧快照，须以当前输入重新准备。
+本地哈希不证明平台当前状态；`specialized`、`sdkUsage` 或 `reportContract` 冲突也需要明确替换交接文件。
 
 ```text
-{python} "{ROOT_DIR}/scripts/query_plugin_handoff.py" coding-context --handoff "{handoffPath}"
+{python} "{ROOT_DIR}/scripts/query_plugin_handoff.py" coding-start --handoff "{handoffPath}"
 ```
 
-只有一次读取明确缺少契约或超过大小上限时，才在本插件的实施上下文中继续定向查询：
+只在本插件上下文中补查缺失契约；已有准确 pointer 时直接 `get`，只有未知路径才用 `index` 或 `find` 定位：
 
 ```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}"
@@ -112,20 +171,19 @@ stdout 摘要和目录不代替编码上下文；写源码前必须读取实际
 将 `fields`、`entities`、`fieldContracts`、已验证外部字段及 `specialized` 原样传给编码。
 `codingEvidence` 提供所选参考路径、API 签名及参数/返回类型的准确 `signatureTypes` 导入。
 使用这些真实导入；未解析类型沿其 `apiLookup` 查询，不凭记忆拼包名。查询字段路径结合
-实际查询根实体及原生结构确定，包含关联表与嵌套集合。`--prepare-source` 在验证后将已解析门禁标记
-为 `coding`，不写 Java；实施时复用返回的 `sourceGate`，并在已验证模块中创建目标包目录；
-新包无需通过构建文件或兄弟项目重新查找。
+实际查询根实体及原生结构确定，包含关联表与嵌套集合。`--prepare-source` 验证后先原子保存 handoff，
+再将门禁推进到 `coding`，不写 Java。输入变化或快照保存失败不会推进门禁；门禁写入失败也不算准备成功。
+快照中的 `sourceGate.requestedState` 仅是请求，不是门禁现状；只有成功响应的 `sourcePreparation`
+报告 `state=coding`、`verified=true`，且仅证明门禁写入，不证明编译或运行。
+门禁文件本身才是实际状态依据。实施时复用其路径和已验证模块内的目标包目录。
 
 已有类使用 `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}"
-```
+若 `PLUGIN_WORKSPACE_UNRESOLVED`，通过 `question`（AskUserQuestion） 询问源码目录或模块根，直接传入用户所选路径；不要搜索本地工程，也不要擅自持久化选择。
 
-显式 `compile=false` 时，解析器可使用应用内源码目录；这不创建 Gradle 模块，也不证明编译。
+显式 `compile=false` 时，`--prepare-source` 可在明确指定的 Java 工程根下创建 `src/main/java`，
+且用户明确选择该目录。未请求准备或启用编译时，源码目录缺失仍报错；未知插件类型在建目录前拒绝，
+modify 仍需真实源码。合法 `sdkUsage` 声明在 source-only 模式仍未验证，不创建 Gradle 模块，也不证明编译。
 其他配置问题按 CLI 的准确诊断处理。未知外部契约保持 `L3-BLOCK`，不写 TODO 或默认结果。

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

@@ -11,23 +11,40 @@
 | 定时执行、工作流节点、单据转换或无生命周期业务服务 | 分别使用 `task`、`workflow`、`botp`、`service` |
 | 产出报表展示的数据行 | `reportlist` |
 | 构建左树右表报表左侧的树导航 | `reporttreelist` |
-| 响应报表页面自身的事件，如过滤交互、工具栏点击，或开启折叠式树形渲染 | `reportform` |
+| 响应报表页面自身的事件，如过滤交互、表头过滤、工具栏点击、钻取联查、合计行标签、图表，或开启折叠式树形渲染 | `reportform` |
+| 打印报表的数据行（它们背后没有实体数据） | `printplugin` |
 | 解析自定义过滤比较值 | `compareplugin` |
 
 每张报表都由插件驱动：报表元数据只声明展现，所以任何带数据的报表都需要 `reportlist`。它是继承
 `AbstractReportListDataPlugin` 的取数插件，不是表单插件 —— 没有 `getView()` / `getModel()`。报表
 数据源过去表达的关联、合并、过滤和汇总，全部落在它的 `query(ReportQueryParam, Object)` 里。
-`reportform` 是附加的页面行为插件，永远不能替代 `reportlist`。
+`reportform` 是附加的页面行为插件，永远不能替代 `reportlist`；它也不是 `reportPlugins` 条目，因为那个
+槽位是报表列表的取数插件。
+
+每种报表类型有自己的注册方式。报表流水线把 `reportlist` 写进报表列表的取数槽位。`reporttreelist` 进入
+`ReportTreeAp.ReportPlugin`，在用户给报表新增「报表树」控件后由 `setReportProperties --target tree` 写入；
+没有任何公共模板预置该控件，所以流水线从不写它。
+`reportform` 在 Java 交付后由 `register_plugins.py --verify` 注册：它以
+`targetType` `BILL_FORM` 加到报表表单自己的插件列表，并以 `location` `BILL_FORM` 回读。
+`prepare_plugin_handoff.py` 只在请求类型对应的槽位里匹配已注册的类，所以在已有取数插件的报表上做 `reportform`
+交接时，准备的是它自己的类，而不是取数插件的类。
+
+`register_plugins.py` 转交类型不代表另一注册器已经执行。取数/左树插件返回 `status=routed`、
+`deferred=true`、`success=false`、`registeredHere=false`、`verifiedHere=false`，在这里既未注册也未验证。
+页面注册与转交混合时返回 `partial`；进程退出码为零也必须解析这些结果，再完成对应槽位的注册和回读。
 
 有两件不同的事都叫「树」，选错会写出方法签名都不对的插件：
 
 - **左树右表** —— `reporttreelist` 继承 `AbstractReportTreeDataPlugin`，实现
-  `query(ReportQueryParam, String nodeId)` 返回 `List<TreeNode>`。它只负责导航。数据行仍来自
-  `reportlist` 插件，被点击的节点作为它的 `selectedObj` 传入。这类报表**两种类型都需要**。
+  `query(ReportQueryParam, String nodeId)` 返回 `List<TreeNode>`。它只负责导航，注册在左树自己身上，
+  即 `ReportTreeAp.ReportPlugin`。左树是用户在设计器里给报表新增的报表树控件，不是模板自带的功能：
+  `bos_grouprpttpl` 是分组报表。数据行仍来自 `reportlist` 插件，
+  被点击节点的 id 作为它的 `selectedObj` 传入。这类报表**两种类型都需要**。
 - **折叠式树形行** —— 同一批行按层级渲染。这属于 `reportform` 的职责：
   `AbstractReportFormPlugin.setTreeReportList(TreeReportListEvent)` 里调
   `event.setTreeReportList(true)` 与 `event.setTreeExpandColId(<列>)`，或在 `beforeQuery` 里调
-  `ReportQueryParam.setTreeReportList(true)`。`reportlist` 照常返回普通行。
+  `ReportQueryParam.setTreeReportList(true)`。`reportlist` 返回带 `rowid` / `pid` / `isgroupnode`
+  列的数据行，由这些列承载层级。
 
 `type` 必须取 `references/type-registry.json` 中的值；仅仅是描述性的取值（例如 `report`）解析不出
 类名后缀，也解析不出对应 guide。
@@ -36,5 +53,5 @@
 真实 `operationKeys`；表单类不得携带 `operationKeys`。需求没有说明触发边界且两种行为会产生
 不同业务结果时才询问用户，禁止用“优先表单插件”或编码方便程度兜底。
 
-类型确定后立即交给 `scripts/prepare_plugin_handoff.py` 校验并冻结。交接失败时补充缺失身份，
+编码技能自行确定类型并调用 `scripts/prepare_plugin_handoff.py` 获取、校验本轮上下文。失败时补充缺失身份，
 不得在编码阶段换类型、猜操作 key 或改用页面事件绕过。

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

@@ -1,6 +1,25 @@
 # 报表过滤与运行交付
 
-报表取数插件的过滤开发或过滤故障使用本参考。优先使用已发布的元数据 CLI 获取源字段、配置控件并独立回读，再使用原生交接、编译及加载验证 CLI。浏览器负责真实控件提交和用户要求的页面验收。不支持的类型化控件明确报告平台边界，不反复重建报表或添加不支持的 schema 属性。
+报表取数插件的过滤开发或过滤故障使用本参考。优先使用已发布的元数据 CLI 获取源字段、配置控件并独立回读，再使用原生交接、编译及加载验证 CLI。浏览器负责真实控件提交和用户要求的页面验收。过滤控件用 `fieldType` 声明，由平台的类型化报表过滤 API 创建；该 API 以平台补丁发布，而本技能随客户端发布。未安装补丁的平台改为渲染旧控件，CLI 把该过滤报告为降级，而不是写入失败。不要为更换控件而重建报表或模拟控件：补丁安装后重新执行 `setReportFilters` 即可。
+
+## 声明每个条件的控件
+
+先确定用户选什么、来自哪个基础资料或选项列表、选一个还是多个，以及比较方式。源字段的类型和引用的基础资料从该表单的 `getFormSchema` 读取（schemaText 会同时打印两者），不按业务名称猜字段。
+
+| 用户选择 | `fieldType` | 必填参数 |
+|---|---|---|
+| 自由文本、编码或名称 | `TextField`，或不声明 `fieldType` | — |
+| 数值 | `IntegerField` / `BigIntField` / `DecimalField` | — |
+| 一个日期或日期范围 | `DateField` / `DateTimeField`；配合 `between` 时变为 `DateRangeField` | — |
+| 一个时刻或时间范围 | `TimeField`；配合 `between` 时变为 `TimeRangeField` | — |
+| 是或否 | `CheckBoxField` | —（可选 `showStyle`） |
+| 一个或多个选项 | `ComboField`，或 `MulComboField` / `CheckBoxGroupField` | `comboItems` |
+| 一条或多条基础资料 | `BasedataField`，或 `MulBasedataField` | `basedataNumber` |
+| 组织、用户、币别、计量单位、物料、客户或供应商 | `OrgField` / `UserField` / `CurrencyField` / `UnitField` / `MaterielField` / `CustomerField` / `SupplierField` | —（`OrgField` 可选 `orgFuncs`） |
+| 辅助资料 | `AssistantField` | `asstTypeId` |
+| 先选基础资料类型，再选该类型的记录 | `ItemClassTypeField` 配合 `ItemClassField` | `itemClassTypes`；`typeFieldKey` 指向类型过滤 |
+
+`compare` 仍需在 `query()` 实现：已检查的控件构建器不会将它绑定到业务查询，生成了范围控件也不证明插件执行了范围过滤。`in` 对应多选控件，`between` 对应范围控件。范围控件提交两个条目：`<key>_startdate` / `<key>_enddate`（时间范围为 `_starttime` / `_endtime`），除非 `startDateFieldKey` / `endDateFieldKey` 另行指定。F7 控件不接受 `defaultValue`，`mustInput` 的过滤不能同时 `visible: false`。CLI 会在写入前拒绝这些情况，规则与补丁完全一致。
 
 ## 绑定每个条件
 
@@ -18,12 +37,26 @@
 | 拆分日期范围 | `getFilterItems()`，匹配准确的 `<key>_startdate` / `<key>_enddate`，读取 Date |
 | 权限过滤 | 在对应实体查询中保留 `getQFilters()`，不能代替用户条件取值 |
 
-这些是面板实测形态，不是 SDK 内部三个互不交叉的存储。在已检查的 8.0 SDK 中，`getValue(key)` 会调用 `getFilterItem(key).getValue()`；FilterItemInfo 有公开的 `getPropName()`、`getValue()`、`getDate()`，应直接使用强类型访问器。
+这些是面板实测形态，不是 SDK 内部三个互不交叉的存储。在已检查的 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。
 
+## 平台实际渲染的控件
+
+每次 `setReportFilters` 结果都带有 `filterEditors`，报表运行则以 `reportFilterEditors` 给出同样的结果。已安装补丁的平台对每次写入返回逐个过滤的回执，写明实际创建的控件；较早版本的补丁会在保存任何内容之前拒绝它不支持的控件类型，CLI 随即去掉该过滤的控件部分重新发送；未安装补丁的平台忽略 `fieldType`。随后回读从 schemaText 读取每个过滤的控件类型。
+
+| `typedFilterSupport` | 含义 | 处理 |
+|---|---|---|
+| `available` | 所有类型化过滤都得到了请求的控件 | 无需处理 |
+| `partial` | 部分得到，其余渲染为旧控件 | 把降级的过滤作为未解决边界说明 |
+| `unavailable` | 平台早于类型化过滤补丁 | 报表以旧控件正常使用；补丁安装后重新设置过滤 |
+| `unconfirmed` | 既无回执也无回读类型 | 控件类型按未验证报告 |
+| `mismatch` | 控件既不是请求的也不是旧控件 | 写入失败 |
+
+降级不等于元数据写入失败，但不代表已经实现用户要求的 F7 或多选体验；将该要求列为未完成，不能宣称文本输入就是复杂过滤控件。每个类型化过滤的契约条目在自身 `valueAccessor` 之外还带有 `legacyEditor`，运行报告过状态时还带 `editorStatus`。按实际渲染的控件读取取值；只要 `editorStatus` 不是 `typed`，就同时兼容旧控件的取值形态，这样补丁安装、过滤重新设置后同一个 `query()` 仍能正常工作。对 F7 过滤而言，旧形态就是用户输入的 `String`，而 `CosmicReportFilters.numbers` 会拒绝它，所以调用 `numberFilter` 之前先判断这种情况。`valueEvidence: observeOnce` 表示该控件的取值类型尚未实测，依赖它之前先做一次关联到具体请求的观察确认。
+
 ## F7 身份与 Algo
 
 跨组织业务身份按已确认的编码范围，使用 String 值和 `field.number` QFilter。ORM 解析相应分配记录，但不能因此扩大权限。pkValue 和 masterId 均不保证等于业务单据引用的 ID。只查特定分配记录时，对 `field` / `field.id` 使用确认后的 Long ID。核对编码在租户、实体和组织范围内的唯一性，不能始终合并同编码记录。
@@ -32,6 +65,22 @@
 
 使用 Algo/DataSet 查询，把用户及业务条件下推到所属数据源。各一对多分录分别聚合后关联，再按报表维度汇总。避免逐行服务或数据库调用、无界 Java Map 和 IN 列表。Row 立即读取，不能缓存；selectFields 需要引用编码时使用 `field.number`。框架接管的返回 DataSet 不由插件关闭，自有 copy 用完关闭。分页或任意 top 限制不能截断合计和导出所需数据。
 
+## 新 API 的结构化回读与逐项回执
+
+`getFormSchema` 返回结构化 `data.reportFilters` 时，CLI 独立于 `data.reportSchema` 消费过滤分区，以 `readBackSources.reportFilters` 标记来源；`reportFilterProjection` 保留面板格式、引用、范围键、unknown 和孤儿/重复/未管理控件诊断。名称只从同一响应中身份匹配的控件取得。缺面板、坏 JSON、重复或无法定位的控件不能通过验收；null/unknown 不当 false。旧平台保留布局/schemaText 和新鲜 DYM 兼容回读，DYM 不得覆盖新过滤投影。
+
+`compareConfig` 保留实际比较配置的来源和目标，不将未验证的比较 ID 猜成 `=`/`in`/`between`；业务查询仍需显式落实条件。`modifyMeta` 仅在 committed、无回滚、同请求完整 `no_op` 回执且 `metadataChanged=false` 时报告未变更成功；no_channel、rejected 或不完整回执不能全成功。submitted/applied 或不完整快照不证明每个属性已持久化，普通属性仍走独立回读的改道；结果未知时先核对现场，不重放整批。
+
+## 实现防线
+
+`CosmicReportFilters.ids` 从 `fbasedataid` 引用或明确的 `fbasedataid_id` 影子 Long 取业务主键，不能取多选关联表行自己的主键；引用与影子主键冲突时拒绝。`numbers` 需要已加载的业务引用。`comparison` 生成标量 `=` 或集合 `in`，`rangeFilters` 生成 Date 范围并明确终点是否包含。条件必须下推到所属数据源，同时保留业务和权限范围。
+
+必录过滤在 `verifyQuery()` 和 query 访问数据源前共用 `require` 检查；范围端点按业务要求校验，0 和 false 不是空值。保存 MustInput 字段标志不能代替查询校验。
+
+动态币别/单位精度需要运行行上的 DynamicObject 引用，不是未转换的 Long。已检查的 NumberFormatProvider 强转精度源；ReportPropUtil 则复用已有实体属性，因此 getColumns 工厂调用不会将已有 BigInt 字段升级成引用字段。引用列创建及行物化得到验证前，不交付动态精度方案；固定精度或静默丢弃绑定不能满足原需求。
+
+已检查的 designer API 支持 Boolean add.mustInput，并已包含类型化过滤复用及 JSON ShowFilterFields。先核对实际部署版本，不把旧行为直接归因于此版本。结构创建后先回读实际字段，再独立写入并回读属性；不要混合字段重建与自动属性改道后宣称原子成功。未知属性及 null/重复 combo 身份在写前拒绝。旧平台中已确认的 ShowFilterFields 逗号值，使用已有 filterPanel 属性写入通道转换为 JSON 数组并回读；回读失败不能重放 setReportFilters。
+
 ## 使用 CLI 编译部署并验证加载
 
 使用交接中的工程、包和 sourcePath。用户指定的报表目录是项目绑定，不是通用默认路径。由原生编译器解析 Gradle 模块，项目名不一定等于目录名。已有报表使用已发布的注册修改命令，不走创建管线。按 className upsert 不证明另一个旧 className 已被删除；独立回读注册或明确该边界。
@@ -51,20 +100,9 @@
 
 确认当前加载后再验证业务。在授权修复范围内删除临时反推或诊断代码，重新编译、加载并复测受影响断言。编译、注册回读、激活和业务结果分别报告，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 验收。
+## Algo 聚合
 
-examples/java-rules/CosmicReportAggregation.java 用三次同范围的表单根 ORM 查询，先聚合两个分录，再关联。
+examples/java-rules/CosmicReportAggregation.java 用三次同范围的表单根 `QueryServiceHelper` 查询，先聚合两个分录，再关联。
 使用已核验的 min/max/countDistinct，避免按组拆分、排序和合并。表头别名为 id/supplier/bill_date/base_amount，
 分录为 main_id/amount；主表查询不能选分录字段造成展开。禁止逐 Row 查询。返回流水线由框架管理；测试驱动
 关闭自有 DataSet，并使用 SDK 托管线程。

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

@@ -10,7 +10,10 @@
 可多次传 `--jar` 选择准确库，或用 `--mode locate` 先定位类。同名类／多版本 JAR 返回候选，
 不自动选取。`javap` 优先来自已配置目标 JDK，再查 PATH；不可用时用 `--javap` 指定准确 JDK 工具。
 
-先看签名；行为仍不明确时，添加 `--mode bytecode` 和准确 `--member`。这是字节码查证，
+先看签名，核对接收者的准确成员、重载参数数量和类型，不从另一个 helper 推断缺少的成员。
+`javap` 可能只给参数类型而没有参数名：相邻同型参数（如操作编码与实体编码）的角色顺序，
+还须按对应参数文档、源码或选中实现查证。
+行为仍不明确时，添加 `--mode bytecode` 和准确 `--member`。这是字节码查证，
 不会重建 Java 源码。确有必要时再使用已有源码／文档 JAR 或已安装反编译器，不假定它们可用。
 
 已有源码或文档 JAR 时，用 `--list-resources "<类名>"` 查条目，再用