@shundoo-ai/dsh-cosmic 1.0.19 → 1.0.21

package/skills/cosmic-build/skills/cosmic-coding-impl/SKILL.md

@@ -1,180 +1,104 @@
-# Cosmic Coding Impl
+# Cosmic Java 编码实现
 
-根据调用方提供的已验证编码上下文生成或修改可注册 Java 插件。应用、元数据和操作身份已经
-绑定，禁止从会话、`archive.json` 或完整 Schema 重新发现；源码结构和调试方式由 AI 正常判断。
-注册和平台读回由调用方负责；本技能负责实现及其窄范围编译证明。
+针对用户已绑定的表单实现或修改 Java。未提供当前 handoff 时，按
+[plugin-handoff-input.md](../../references/plugin-handoff-input.md) 准备。优先读取准备好的 `coding-start`
+文件；否则从准确 handoff 查询 `coding-start`，缺失事实
+通过准确 pointer 查询，不重复准备。
+`{ROOT_DIR}` 是根技能的技能包目录。完整字段归属和运行时集合路径以 `formGraph` /
+`relatedForms` 为准，可选 `fields` 别名不是完整字段清单。使用已准备的项目、包与源码路径，
+不搜索兄弟项目或旧插件测试来重新推导。必需元数据缺失时，通过该目标的原生读取契约补齐；
+结构不完整不能猜测。无需额外规划文档或编码 Agent。
 
-`ROOT_DIR` 是根 app-build 技能提供的技能包目录。下文所有知识、指南和脚本路径
-都必须逐字使用它；本地化技能自身的 Base directory 不是 `ROOT_DIR`。
+## 使用已提供的证据
 
-## 输入契约
+`codingEvidence` 从唯一的类型/基类/后缀映射 `references/type-registry.json` 解析指南与 API
+契约。其中的准确签名、导入和弃用提示已经是 API 证据，不要求为满足“本轮已读”而重复打开
+页面。`coreLogic` 中的业务事件名不是 SDK 签名。
 
-必填：`appRoot`、`projectRoot`、`packagePath`、`type`、`coreLogic`、`formNumber`、
-`trigger`、`ownershipMode`。`coreLogic` 必须是精确行为数组。
+只读取缺失或适用的知识：
 
-按场景必填：
+- 已有证据不能确定事件位置、必需 `super` 调用或异常行为时，读所选指南的相关生命周期/场景。
+  没有指南的类型，按实际实现读取准确 API 参考。
+- 值访问、过滤或数据服务超出 `fieldContracts` 与 API 证据时，读
+  `knowledge/cosmic/platform/java-type-contracts.md` 的相关段落。
+- 从 `knowledge/cosmic/platform/standards.md` 的严格禁止事项中读取适用平台约束；专项标准
+  只读 `specialized.hitModules` 点名的部分。源码检查覆盖部分生命周期错误，不覆盖全部生产约束。
 
-- `type=operation`：`operationKeys` 为非空字符串数组。
-- Java 访问字段/实体：`fields` / `entities` 必须提供业务名到真实 key 的映射。随之提供
-  `fieldContracts` 时，其中带有每个字段已验证的 `fieldType`，引用字段还带
-  `valueAccessor`、`idAccessor`、`filterValue`。这些取值方式必须照抄使用；已有契约的字段
-  不得用自行推导或凭记忆的取值方式读取。
-- `ownershipMode=modify`：`sourcePath` 和 `existingMethods` 已提供。`sourcePath` 指向交接
-  编译器已经读取过的文件；`existingMethods` 列出该文件最外层类体已声明的方法签名。
-- 命中安全、幂等、大数据或审计约束：通过 `specialized.hitModules/constraints/evidence`
-  直接提供；已验证产物之外的数据或服务精确契约通过 `specialized.externalContracts` 提供
-  （`externalApis` 仅为旧别名）。
-  交接编译器已保证 `specialized.unresolvedDependencies` 为空。禁止在编码阶段重新设计。
+缺少 API 证据时，在一次本地查询中批量指定接收者类与所需成员：
 
-可选：`className`、`relateFormNumber`、`processingSteps`、`specialized`。
-缺少必填或出现未解析字段、实体、操作标识时立即失败；禁止重新拉取元数据或猜 key。
-
-`coreLogic` 只按业务语义处理。若其中混入 Java 事件、Helper、方法名或 SDK 调用步骤，不得
-照抄；以已选 guide 的验证 API 为准。必须依赖的外部集成若没有精确的
-`specialized.externalContracts`，返回 `L3-BLOCK`，不得猜服务名或用空值/默认值掩盖失败。
-
-## 1. 确定类和路径
-
-- `modify + sourcePath`：先完整读取该文件。起点是它，不是 guide 骨架。只写本次要求的改动
-  及直接相关辅助代码；为遵循工程惯例，可以窄范围读取同包附近已有插件。
-- 新建：`className` 已给出则直接使用；否则将 `formNumber` 转为 PascalCase 后追加下表
-  `classSuffix`。类名只能包含 `[A-Za-z0-9]`。
-- 新建输出固定为
-  `{projectRoot}/src/main/java/{packagePath}/{className}.java`。
-- `packagePath` 直接转成 Java package；禁止重新发现其他模块或读取兄弟工程。
-
-## 2. 最小知识读取
-
-写任何取值、过滤条件或数据服务调用之前，先只读取一次
-`{ROOT_DIR}/knowledge/cosmic/platform/java-type-contracts.md`。它收录的是"两种写法都能编译
-通过"的类型事实：引用字段存的是记录而不是它的 id、`QFilter` 的值可以是什么、每个比较操作符
-对应哪个 `QCP` 常量、以及最常被凭记忆写错的返回类型。编译边界会拒绝与登记返回类型矛盾的
-声明，但取值类型写错只会在数据库层暴露。
-
-生成源码之前，先只读取一次 `{ROOT_DIR}/knowledge/cosmic/platform/standards.md` 的
-`强制禁止项` 一节。那是平台的生产事故清单：循环内不能做什么、日志/多语言/线程池/缓存 key 必须用
-哪些 API、`initialize()` 里不能碰什么。本流程没有任何闸门检查其中任何一条，违反了照样能编译、能
-注册，并进入生产环境。
+```text
+{python} "{ROOT_DIR}/scripts/platform_api_contract.py" --describe-class "<receiver class>" [--describe-class "<another class>"] [--member "<required member>"]
+```
 
-按映射表只读取一次当前 `type` 的 guide。先使用 guide 中的事件签名、骨架和 top-1 场景；
-已经覆盖实现时立即停止读取。
+查询包含已文档化父类。未记载不等于不存在，剩余缺口查所选场景，或按返回的 `sdkLookup` 使用
+[SDK 查证](../../references/sdk-inspection.md) 核对实际目标库。
+插件、校验器和事件对象上的同名调用具有不同契约。需要搜索时，仅搜索相关平台知识或目标
+模块附近代码。必需 API 或外部契约仍无法确定时返回 `L3-BLOCK`。
 
-发出 `kd.bos.*` 调用前先遵循当前 guide 的 API 证据路由。所需调用仍无精确
-import/方法签名时，只读取 guide 点名的一份 API 参考，或在平台知识和目标模块附近插件代码中
-做窄范围搜索；禁止巡游目录索引、整套 SDK、无关场景或兄弟工程。仍无准确依据时返回
-`L3-BLOCK`，禁止写 TODO、占位方法或猜 API。
+查询、加载、保存调用直接使用已准备场景的 `apiContracts`。`EntryType` 或
+`collectionPath` 能证明字段归属，不能证明 `QueryServiceHelper` 接受该分录作为独立查询根。
+缺少查询用法时，先按目标 SDK 示例或限定范围的只读平台验证查证。状态行为依据 `operationContracts`
+和已验证枚举值，写源码前解决 `stateWarnings`；编译和注册保持已准备的操作键。
+多操作插件使用 `codingEvidence.operationDispatch`：校验器 `getOperateKey()` 与事务参数
+`getOperationKey()` 是不同接收者的契约。[操作分派参考](../../references/operation-dispatch.md)
+给出 SDK 查证范围，不能把猜测的 `operateMeta` Map 键作为操作契约。
 
-平台类自身的参考文档位于 `{ROOT_DIR}/knowledge/cosmic/platform/api/**/{Class}.md`，其方法列表
-只包含该类自己声明的方法。所需方法不在其中时，先读该页 Overview 中 `inherits from` 指向的那个
-类，再断定方法不存在 —— 继承来的方法记录在父类页面，不在子类页面。继承平台基类时，无论 guide
-路由到哪里，该基类页面都是必读项：它是你所重写方法的签名，以及获取上下文、结果等对象的 getter
-的唯一来源。
+读取表头与分录时，可按需参考 [CosmicEntryQuery.java](../../../../examples/java-rules/CosmicEntryQuery.java)：
+在表单根查询 ID，再加载结构化对象并读取集合属性。示例通过 8.0 SDK 编译验证；实际表单编码、
+集合属性、过滤条件与返回字段需在已授权目标中验证。展开查询继续使用已有 `query-entities.md` 场景。
 
-`specialized.hitModules` 非空时，只读取其中明确命名的对应规范；为空时不读取架构、安全、
-OOM、幂等专项文档。`constraints` 必须逐项落实。
+## 写入源码
 
-## 3. 生成源码
+modify 先完整读取现有文件，以它为起点。在已有触发方法内添加行为，`existingMethods` 是
+方法清单，不是要求重新声明。保留无关代码、包、类与导入。create 使用所选类型的基类及生命
+周期契约，写入返回的 `sourcePath`。
 
-写入前执行：
+写入前复用准备阶段的 `sourceGate.state="coding"`；只有缺少该状态时才执行：
 
 ```text
 {python} "{ROOT_DIR}/scripts/plugin_source_gate.py" --project-root "{projectRoot}" --class-name "{className}" --write coding
 ```
 
-`create-new`：按 guide 生成完整可编译类。
-
-`modify`：修改已经存在的那个类。guide 只提供事件签名和 API 用法，永远不提供文件的整体形状。
-
-- 每条行为写进已经承载对应触发时机的那个方法。所需方法出现在 `existingMethods` 中时，把逻辑
-  加进**那个已有声明的方法体内**；重复声明会被判为 `PLUGIN_SOURCE_DUPLICATE_METHOD`。
-  guide 骨架里写着 `afterCreateNewData`，不等于要新写一个 `afterCreateNewData`。
-- 只有签名不在 `existingMethods` 中的方法才允许新增。
-- 保持原有 package、类声明、基类、字段和无关方法不变。import 采用追加，不要替换整段 import。
-
-两种模式共同遵守：
-
-- 每个平台标识可回溯到本轮读取的 guide/场景/API 文档：在平台类型上调用的每个方法、每个 import
-  的类，不只是 `kd.bos.*` 引用。任何文档都没出现过的方法名、参数或包名就是臆想，哪怕变量是
-  局部的、类型很明显。
-- 基类及其 import 以类型注册表中该 `type` 的 `baseClass`/`baseImport` 为准，大小写与包路径
-  照登记原文。形如把 `kd.bos.bill.AbstractBillPlugIn` 写成
-  `kd.bos.form.plugin.AbstractBillPlugin` 的近似拼错是凭记忆写出的名字，并非平台类：最好情况也
-  只会以一句裸的符号错误暴露，跳过编译时更会注册一个平台根本加载不了的类。
-- 每条 `kd.bos` import、每个平台成员调用都携带登记拼写，大小写一致——登记名的 case-fold 或近似
-  拼错（把 `AbstractBillPlugIn` 写成 `AbstractBillPlugin`、把 `getEntryRowCount` 写成
-  `getEntryCount`）是凭记忆的名字，在哪儿都编译不过，会被编译边界拒绝。
-- `@Override` 照抄基类页面给出的签名，包括参数。绝不添加基类未声明的参数；方法需要但未接收的对象，
-  来自基类自身的 getter。参数类型与登记签名不一致——如把 `PropertyChangedArgs` 写成
-  `PropertyChangedEventArgs`——会使该方法变成平台永远不会调用的重载。
-- 字段和实体常量只使用 payload `fields/entities` 中的真实 key。
-- `QFilter` 的比较操作符绝不写等价的字符串字面量。操作符表里该行给出 `首选` 辅助方法时就用它
-  （多数 `QCP` 成员是 `@SdkInternal`，其中四个有 `@SdkPublic` 的 `QFilter` 辅助方法），否则写
-  `QCP` 常量。编译边界会拒绝字面量，并按该行规定的那一种给出改法。
-- 带有 `fieldContracts` 条目的字段一律按其给出的取值方式读取，其 `javaType` 就是该值的声明
-  类型。引用字段的 `get()` 拿到的是被引用记录，因此过滤条件或 id 比较必须用 `filterValue`
-  或 `idAccessor`，不能直接用字段值。
-- `operationKeys` 只决定事件与注册位置，不得把多个 key 拼成一个平台 key。
-- `modify` 只做与 `coreLogic` 相关的最小改动。
-- 调用重写方法所需的 `super`、事件签名、国际化和异常处理以当前 guide 为准；禁止用一套
-  通用规则覆盖不同插件基类。
-- 代码标识符使用英文；注释和用户可见文本跟随当前回复语言。
-
-只做一次源码自检：import/基类/override 签名、类体内无签名被声明两次、跨 package 的类与成员
-可见性、字段 key、空值与集合边界、异常不吞噬、`specialized.constraints`。发现问题直接修复
-源码，不扩展业务范围。
-
-## 4. 编译、归档并返回
-
-只读一次 `{ROOT_DIR}/references/compile-guide.md`，调用其中唯一编译脚本处理本轮
-`sourcePath`。按结构化诊断做正常的窄范围调试，必要时查看目标模块相关代码或准确 API 证据。
-禁止手工运行 Gradle、检查构建配置，或搜索 jar、兄弟工程、元数据、Gradle 缓存及外部源码。
-现有证据不能解决时返回 `L3-BLOCK`。
-
-编译命令同时写入当前类的归档项，并且只在编译和归档都成功后标记 gate。每个操作 key 单独
-传参，数组为空时整项省略。禁止再单独调用 `write_archive_json.py` 或
-`plugin_source_gate.py --write source_ready`。
-
-最后只输出一行：
-
-```text
-::TASK_STATUS::{"status":"source_ready","className":"<className>","fqcn":"<package.className>","sourcePath":"<绝对路径>","formNumber":"<formNumber>","operationKeys":["<key>"]}
-```
-
-失败只输出 `status=failed` 和简短 `error`。禁止输出源码、长推理、编译或注册结果。
-
-## 插件映射
-
-| type | classSuffix | guide |
-|---|---|---|
-| `form` | `FormPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/form-plugin.md` |
-| `billform` | `BillPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/form-plugin.md` |
-| `baseform` | `FormPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/form-plugin.md` |
-| `form_plugin` | `FormPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/form-plugin.md` |
-| `listform` | `ListPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/list-plugin.md` |
-| `mobbill` | `MobBillPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/form-plugin.md` |
-| `mobform` | `MobPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/form-plugin.md` |
-| `moblist` | `MobListPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/list-plugin.md` |
-| `treelist` | `TreeListPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/standardtreelist-plugin.md` |
-| `operation` | `OpPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/operation-plugin.md` |
-| `workflow` | `WorkflowPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/workflow-plugin.md` |
-| `task` | `Task` | `{ROOT_DIR}/knowledge/cosmic/platform/task-plugin.md` |
-| `customapi` | `ApiController` | `{ROOT_DIR}/knowledge/cosmic/platform/openapi-customapi-java-plugin.md` |
-| `apiplugin` | `ApiPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/openapi-ext-plugin.md` |
-| `reportform` | `ReportPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/report-plugin.md` |
-| `reportlist` | `ReportListPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/reportlistdata-plugin.md` |
-| `reporttreelist` | `ReportTreePlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/reporttreedata-plugin.md` |
-| `report-plugin` | `ReportListPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/reportlistdata-plugin.md` |
-| `compareplugin` | `FilterContantParser` | `{ROOT_DIR}/knowledge/cosmic/platform/compare-plugin.md` |
-| `printplugin` | `PrintPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/print-plugin-guide.md` |
-| `kwc` | `Controller` | `{ROOT_DIR}/knowledge/cosmic/platform/kwc-controller-plugin.md` |
-| `writeback` | `WriteBackPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/writeback-plugin.md` |
-| `botp` | `BotpPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/botp-plugin.md` |
-| `import` | `ImportPlugin` | `{ROOT_DIR}/knowledge/cosmic/platform/import-plugin.md` |
-| `service` | `Service` | 无 guide；所需 API 必须逐项取得文档依据 |
-
-## 禁止行为
-
-- 调用 app-build、建模技能、修改技能或插件设计。
-- 读取 `archive.json` 作为输入，重新发现应用、表单、字段、操作或路径。
-- 执行插件注册、`prepareFormMutationTarget`、describe/catalog 搜索或平台读回。
-- 在 `{projectRoot}` 和 `{appRoot}/archive.json` 之外写文件。
+- 使用已验证的 `fields` / `entities` 键，以及 `fieldContracts` 中的准确访问器和值类型。
+  引用字段的记录不是 ID，比较时使用其 `idAccessor` 或 `filterValue`。
+  目标 8.0 SDK 的 `TimeProp` 是距午夜的整秒数，使用返回的 `getInt` 访问器，
+  不用 `getDate`；空值及跨日情形另按实际业务规则处理。
+  [CosmicTimeAdapter.java](../../../../examples/java-rules/CosmicTimeAdapter.java)
+  示例演示先拒绝异常值，再转换为普通 Java 时间。
+- 准确复制基类导入和重写签名，包括大小写与参数类型。按接收者证据核对平台调用，不靠近似名称猜 API。
+- `QFilter` 使用操作符表推荐的辅助方法，否则使用对应 `QCP` 常量，不能用字符串操作符。
+  仅在所需操作符尚无证据时读取该表。
+- 实现 `coreLogic`、已提供的 `reportContract` 和 `specialized.constraints`。
+  报表过滤读取 [report-filter-contract.md](../../references/report-filter-contract.md)，
+  绑定实际取值 key、源字段类型、F7 组织身份、拆分日期和加载证据。
+  多个 `operationKeys` 保持独立；外部调用需要已提供的准确契约。
+- 每项行为绑定到真实操作/事件，注册多个操作时分别使用对应条件，不能每个操作都执行全部行为。
+  从操作数据包读取的字段要在属性准备钩子中声明。
+- 按真实状态字段和值显式实现所需业务状态变化；标准操作的 `statusFieldKey` 可能指向另一字段。
+  覆盖本任务要求的每条流转及其关联副作用。
+- 独立加载的关联对象通过已验证保存/更新 API 持久化，核对事务边界及所需幂等性；
+  `set` 本身不代表关联对象已保存。
+- 副作用保持在需求范围内，余额校验不隐含扣减或退款。附近测试/代码用于参考工程约定，
+  原始需求和 `coreLogic` 决定业务行为。
+- 对存在边界情况的时段、金额或状态规则，将判定写成可脱离平台对象检查的普通 Java 代码；
+  元数据读取、事件绑定和持久化留在轻量的苍穹适配层。简单校验无需机械拆类。
+  测试时检查实际生产规则，不要为了脱离平台运行而把规则复制到测试专用类。
+  返回真实命令与结果，未执行时如实标记未运行。本地规则测试不能证明平台事件绑定或运行态业务覆盖。
+- 按所选生命周期处理空值、异常和 `super`。标识符用英文，注释和用户可见文本跟随回复语言。
+
+检查修改源码中的重复签名、导入/可见性、字段访问、空值和集合边界、吞异常及已提供约束，
+在任务范围内修复。
+将每项所需行为对应到源码方法/条件及可观察结果；对照原始 AC 索引和可用操作，明确返回冻结键
+之外的未实现行为、缺少操作或依赖。常量或状态标签本身不代表实现了流转及关联副作用。
+未经验证的修复原因保留为假设；
+编译通过不能证明 SDK 查询行为正确或业务缺陷已经修复。
+
+## 编译并继续交付
+
+按 [compile-guide.md](../../references/compile-guide.md) 执行原生编译/归档边界。
+该命令同时推进源码门禁，不单独写归档或标记 `source_ready`。
+实施者随后继续 [java-plugin-delivery.md](../../references/java-plugin-delivery.md) 完成注册与交付；
+达到 `source_ready` 不代表用户整体请求结束。
+
+报告原生结果中的真实源码身份、编译/归档结果、`compileSkipped` 和未验证项。
+源码及编译/归档写入保持在已验证项目和应用路径内。

package/skills/cosmic-build/skills/cosmic-coding-script/ATTRIBUTION.md

@@ -26,7 +26,7 @@ action-catalog record) is Chinese-free.
 | `references/examples/plugins/` | Plugin `templates/`, `community/`, and the source-language scenario-example directory (event/scenario-split real examples) |
 | `references/docs/` | Custom-development runtime guides and pitfall docs |
 | `references/typescript/` | `tsconfig.json` + `package.json` reference for a full `tsc --noEmit` setup |
-| `references/sdk/` | **Retrieval layer only**: `README.md`, `strategy.md`, `docs/`, `templates/`, the small `indexes/` entry points, and the small `manifests/` |
+| `references/sdk/` | **Retrieval layer only**: `README.md`, `strategy.md`, `docs/`, `templates/`, and the small `indexes/` entry points |
 
 ## What was intentionally NOT ported
 

package/skills/cosmic-build/skills/cosmic-coding-script/SKILL.md

@@ -1,5 +1,9 @@
 # Cosmic Coding Script
 
+KWC 工程的 Controller（`app/ks/controller/*.ts`）使用
+[KWC Controller 编写入口](references/kwc-controller-authoring.md)，完成后返回 KWC。
+该入口复用目标环境 SDK 检索和本地源码检查，不执行下方的插件注册流程。
+
 根据调用方提供的已验证编码上下文，编写可注册的 KingScript 插件或脚本控制器，用本地
 KingScript 门禁验证，并返回已验证源码。本技能是 `cosmic-coding-impl`（Java）的 KingScript
 姊妹技能。应用、表单、目标类型、字段标识与脚本身份均已绑定；禁止从会话、留档或完整
@@ -16,6 +20,8 @@ false、脚本记录不可修改也不可删除，`registerPlugin` 对坏源码
 - `{ROOT_DIR}` 为 app-build 根目录；`{python}` 为 Python 解释器。
 - 技能知识根：`{KS_ROOT}` = `{ROOT_DIR}/skills/cosmic-coding-script`。
 - 本地门禁：`{ROOT_DIR}/scripts/kingscript_source_gate.py`。
+- 环境 SDK 同步：`{ROOT_DIR}/scripts/kingscript_sdk_sync.py`；其构建的缓存位于
+  `~/.kd/kingscript-sdk/<envName>/`。
 
 下方所有知识路径均为加载时解析的 inline-code 引用；每个只读一次，当前层足够时绝不预加载
 更高层。
@@ -61,8 +67,9 @@ false、脚本记录不可修改也不可删除，`registerPlugin` 对坏源码
 字符数，达到上限即停止。绝不预加载整棵树、全部模板或全部示例。
 
 - **Tier 0（始终加载）**：`{KS_ROOT}/references/examples/kingscript/README.md`（语法、命名、
-  保留关键字、模块/引用规则）+ `{KS_ROOT}/references/sdk/indexes/quick-lookup.md`（覆盖大部分
-  SDK 路由）+ `{KS_ROOT}/references/examples/plugins/templates/` 下最匹配的 1 个模板。
+  保留关键字、模块/引用规则）+ `{KS_ROOT}/references/sdk/indexes/quick-lookup.md`（场景路由
+  到候选类；SDK 事实来自环境缓存，而非此处）+
+  `{KS_ROOT}/references/examples/plugins/templates/` 下最匹配的 1 个模板。
 - **Tier 1（Medium+）**：`{KS_ROOT}/references/examples/plugins/community/` 下最贴近的 1 个社区
   示例 + 事件签名索引 `{KS_ROOT}/references/sdk/indexes/methods-lifecycle.md` 或
   `methods-hot.md` + `plugin-index.md` / `scenario-index.md` / `keyword-index.md` 之一。
@@ -77,25 +84,47 @@ grep-only 规则：绝不 `read_file` 任何大于 100KB 的文件；`indexes/`
 `rg -n`（或 `rg --files`）在 `{KS_ROOT}` 上检索。
 
 **可选外部 SDK 知识盘（不随仓库分发）。** 完整类卡层（`references/sdk/classes/`、`packages/`、
-`indexes/class-index*.md`、`enum-index.md` 及大清单文件）**刻意不在**本仓库内。
-`{KS_ROOT}/references/sdk/strategy.md` 将其描述为第 1–3 层；**仅当**维护者在本地挂载了离线 SDK
-资料包时（strategy.md 第 4 层）这些层才可用。当它缺失时，下方检索链从已分发的索引与清单直接
-跳到在线 Javadoc，再跳到有界的 `[D4-PENDING]` 回答。只读了索引时，绝不声称读了类卡。
+`indexes/class-index*.md`、`enum-index.md`）**刻意不在**本仓库内，且在存在性事实上
+已被下方环境 SDK 缓存——运行中平台自己的声明集——取代。把外部挂载的离线 SDK 资料包
+（strategy.md 第 4 层）仅当作编辑性知识（用法说明、真实示例）的补充，且仅当维护者已在本地挂载
+时；它绝不是存在性事实的来源。当它缺失时，下方检索链不依赖它也完整。只读了索引时，绝不声称
+读了类卡。
+
+## SDK 事实来源：目标环境，而非随仓快照
+
+SDK 开放面依赖苍穹版本：随仓的 `{KS_ROOT}/references/sdk/` 树只是构建期快照，两个方向的漂移都
+真实存在——旧环境缺少快照列出的类型，新环境暴露快照从未有过的模块（`@constellation/*` 业务
+套件）。做任何 import 实证之前，先与运行中的平台对齐：
+
+```text
+{python} "{ROOT_DIR}/scripts/kingscript_sdk_sync.py" ensure
+```
+
+- `ready` / `synced`：动态层是 SDK 存在性、包与签名的唯一事实来源。
+- `failed`（离线，或平台无 poll API）：降级为只用随仓索引做路由，并在任务状态返回中携带
+  `"sdk": "snapshot-degraded"`——依快照解析出的 import 未经运行平台验证，必须如实报告。
+
+缓存包含 `type-index.tsv`（`<类型>\t<模块>\t<包斜杠>\t<包点号>`，即 D4 三要素查询）与 `dts/`
+（该环境实际的 `@cosmic/*` 声明：包级导出文件，加上携带方法签名、Javadoc 与 `@since` 标记的
+模块根聚合声明）。使用 ensure 输出中的 `cacheDir` / `typeIndexPath` / `dtsDir` 值；绝不硬编码
+环境名。
 
 ## D4 import 实证门控（写入任何 import 前）
 
 只读一次 `{KS_ROOT}/rule/p0-group-d-imports.md`。每个非基础类型的 import（类、接口、事件参数、
 枚举）在写入前必须实证到三要素：**类型全名 + 所属模块 + 包路径**。
 
-检索链（已按实际分发文件调整）：
+检索链（动态优先）：
 
-1. `{KS_ROOT}/references/sdk/indexes/quick-lookup.md`
-2. `methods-lifecycle.md` / `methods-hot.md`（由事件/方法解析到其所属类型，再继续）
-3. `plugin-index.md` / `scenario-index.md` / `keyword-index.md` / `package-index.md`
-4. `{KS_ROOT}/references/sdk/manifests/summary.json` + `modules.json`
-5. 可选外部 SDK 知识盘（`classes/`、`class-index-full.md`），**仅在已挂载时**
-6. 在线 Javadoc（`https://dev.kingdee.com/sdk/Cosmic%20V8.0.1/index.html`）
-7. 有界回答
+1. `rg -F "<TypeName>" <typeIndexPath>`——来自环境缓存的直接三要素证明。
+2. 方法/签名证明：在 `<dtsDir>` 下 `rg` 方法名，读取命中的包级导出文件，以及声明
+   `interface <Type>$ { ... }` 的模块根聚合。聚合还暴露继承链
+   （`type X_T = X$ & Parent ...`），因此“该方法属于该变量的类型还是其继承链”可以本地解答。
+3. 随仓索引（`quick-lookup.md`、`methods-lifecycle.md` / `methods-hot.md`、
+   `plugin-index.md` / `scenario-index.md` / `keyword-index.md`）**仅作路由辅助**：它们把场景
+   与事件名映射到候选类型，但每个候选在写入 import 前仍须在第 1–2 步实证。
+4. 在线 Javadoc（`https://dev.kingdee.com/sdk/Cosmic%20V8.0.1/index.html`）。
+5. 有界回答。
 
 快速失败：最多 3 次 grep 尝试。若三要素仍未解析，在源码中把该 import 标注为
 `// [D4-PENDING] <类型> — <原因>`，在返回中报告它，并给出保守降级方案。绝不按命名模式臆测
@@ -211,4 +240,6 @@ List/Operation → `p0-group-a-syntax.md`（A1,A3,A4）+ `p0-group-d-imports.md`
 - 按命名模式臆测 import 路径或 API、写 TODO/占位代码，或编造 SDK 类型、事件、上下文结构。
 - 绕过门禁（`@ts-ignore`、`as any`、事件参数 `any`、`--skip-syntax`），或把降级/失败的证明报告
   为已编译或通过。
+- 在环境缓存可用时把随仓 SDK 索引当作存在性证明，或把 snapshot-degraded 的运行报告为完全
+  验证。
 - 删除任何脚本记录，或在 `sourceArchiveRoot` 之外写入。

package/skills/cosmic-build/skills/cosmic-coding-script/references/kwc-controller-authoring.md

@@ -0,0 +1,6 @@
+# KWC Controller 编写入口
+
+请读取唯一维护的 [KWC Controller authoring](../../../../../skills/cosmic-coding-script/references/kwc-controller-authoring.md)。
+沿该文件所在位置解析 `{ROOT_DIR}`，复用其 SDK 同步和源码检查命令。
+自然语言仍使用用户当前语言；KWC 保留 `.kws`、adapterApi、部署和最终验收职责。
+本入口不引入 Java 插件、`createScript`、`registerPlugin` 或独立子 Agent。

package/skills/cosmic-build/skills/cosmic-coding-script/references/sdk/README.md

@@ -2,6 +2,21 @@
 
 这个目录不是原始 `node_modules` 的镜像，而是面向大模型检索和二开使用的 SDK 知识层。
 
+## 事实来源：目标环境动态 SDK（权威）
+
+SDK 面随苍穹版本变化：旧环境缺少本目录列出的类型，新环境多出本目录没有的模块（如
+`@constellation/*` 业务套件）。**SDK 存在性、包归属、方法签名的事实判定一律以目标环境为准**：
+
+```bash
+# 拉取/校验目标环境的真实 @cosmic/* 声明（缓存 7 天）
+python3 app-build/scripts/kingscript_sdk_sync.py ensure
+# 三要素直查（类型 → 模块 → 包路径）
+python3 app-build/scripts/kingscript_sdk_sync.py lookup --type AbstractFormPlugin
+```
+
+缓存位于 `~/.kd/kingscript-sdk/<envName>/`：`type-index.tsv`（三要素索引）+ `dts/`（真实声明树）。
+本目录的索引仅作场景路由与离线回退，不作为存在性证据。
+
 ## 建设目标
 
 - 让模型先找到正确的模块、包、类或场景，再读取细节
@@ -42,7 +57,7 @@
 
 ### 已知类名
 
-先读 `indexes/class-index.md`，再打开对应类文档。
+先用环境缓存直查（`kingscript_sdk_sync.py lookup --type <类名>`），再按需打开外部知识盘类卡。
 
 ### 已知业务场景
 
@@ -70,14 +85,13 @@
 
 ## 全量 SDK 检索降级链路
 
-当知识卡不足以回答问题时，必须按下面的顺序继续查找：
+当知识卡不足以回答问题时，必须按下面的顺序继续查找（第 -1 层为事实权威，详见 `strategy.md`）：
 
-1. `classes/`、`packages/`
-2. `indexes/`
-3. `manifests/`
-4. 本地 `.d.ts` 源文件
-5. 在线 Javadoc
-6. 如果仍不确定，明确说明假设和缺口
+-1. 环境动态层：`~/.kd/kingscript-sdk/<envName>/`（`type-index.tsv` + `dts/`，事实权威）
+1. `indexes/`（路由辅助：场景/事件名 → 候选类型；候选仍须回 -1 层实证）
+2. 外部知识盘类卡与本地 `.d.ts` 源文件（仅在维护者已挂载时）
+3. 在线 Javadoc
+4. 如果仍不确定，明确说明假设和缺口
 
 当前外部兜底来源：
 
@@ -89,20 +103,15 @@
 ```text
 sdk/
 ├─ README.md
-├─ strategy.md          — 7 层 SDK 检索策略
+├─ strategy.md          — 分层 SDK 检索策略
 ├─ docs/                — 桥接文档和 SDK 概览
-├─ indexes/             — 12 个 Markdown 索引
-├─ classes/             — 类知识卡片（~3800 个）
-├─ packages/            — kd.* 包概述卡片
-└─ manifests/           — JSON 元数据（packages.json, modules.json）
+├─ indexes/             — 10 个 Markdown 索引（路由辅助，grep 目标）
+└─ templates/           — SDK 文档生成模板
 
 ../examples/plugins/templates/ — 插件模板（SDK 方法速查由生成器自动注入）
 ```
 
-当前 `manifests/` 已接入：
-
-- 模块清单（`modules.json`）
-- kd.* 包清单（`packages.json`）
+`classes/`、`packages/`、`class-index*.md`、`enum-index.md` 等大类卡资产刻意不随仓库分发（外部知识盘产物）；SDK 存在性事实一律以环境动态缓存为准。
 
 ## 建设原则
 
@@ -146,14 +155,15 @@ sdk/
 
 ## 注意事项
 
-- 原始 SDK 清单、扫描结果统一放在 `manifests/`
-- 面向模型阅读的知识卡统一放在 `classes/`、`packages/`
+- 面向模型阅读的知识卡统一放在 `classes/`、`packages/`（外部知识盘，不随仓库分发）
 - 插件模板统一放在 `../examples/plugins/templates/`（SDK 方法速查由生成器自动注入）
 - 全量检索规则统一写在 `strategy.md`
 - 没有真实来源时，不要伪造任何 SDK 类、方法、参数或返回值
 
 ## 本轮新增的高频入口
 
+> 下列 `classes/*.md` 类卡为生成器/外部知识盘产物，不随仓库分发；仓库内请以环境缓存 `lookup --type` 实证同名类型。
+
 - Java 与 Kingscript 类型桥接: `docs/java-kingscript-bridge.md`
 - 数据操作: `classes/DynamicObject.md`、`classes/DynamicObjectCollection.md`
 - 操作结果与校验: `classes/OperationResult.md`、`classes/ValidationErrorInfo.md`、`classes/ValidateResult.md`、`classes/ErrorLevel.md`

package/skills/cosmic-build/skills/cosmic-coding-script/references/sdk/docs//350/204/232/346/234/254SDK.md

@@ -75,12 +75,11 @@ HTTP / 缓存 / 编码工具类
 
 ```
 references/sdk/
-  manifests/     — 结构化 JSON 元数据
   indexes/       — Markdown 索引
-  classes/       — 类知识卡片
-  packages/      — 包概述卡片
+  classes/       — 类知识卡片（外部知识盘，不随仓库分发）
+  packages/      — 包概述卡片（外部知识盘，不随仓库分发）
   docs/          — 桥接文档和 SDK 概览
-  strategy.md    — 7 层 SDK 检索策略
+  strategy.md    — 分层 SDK 检索策略
 
 references/templates/
   *.md           — 插件模板（SDK 方法速查由生成器自动注入）

package/skills/cosmic-build/skills/cosmic-coding-script/references/sdk/indexes/package-index.md

@@ -1,7 +1,7 @@
 # 包索引（核心）
 
 > 自动生成于 2026-04-25 15:44:08
-> 核心包 107 个（type_count >= 10 或高价值包），完整列表（826 个）见 `manifests/packages.json`
+> 核心包 107 个（type_count >= 10 或高价值包）；完整列表以环境动态缓存为准（快照期统计 826 个）
 
 
 ## @cosmic/bos-core

package/skills/cosmic-build/skills/cosmic-coding-script/references/sdk/strategy.md

@@ -6,6 +6,13 @@ These files are 700KB+. ALWAYS use grep/rg to search them by exact class name or
 If grep returns no results, try alternative keywords (English/Chinese) before escalating to next layer.
 MAX 3 grep attempts per SDK type lookup. If still not found → use Layer 7 (bounded answer with assumptions).
 Files in references/sdk/indexes/ are grep-only. Never read_file on index files > 100KB.
+
+SDK existence facts are version-dependent. When the environment cache
+(`~/.kd/kingscript-sdk/<envName>/`, built by `app-build/scripts/kingscript_sdk_sync.py`)
+is available, `type-index.tsv` and `dts/` are the ONLY factual source;
+the shipped indexes below are routing aids and offline fallback. Resolve
+type → package → module from `type-index.tsv` first, prove signatures in
+`dts/`, then use the shipped indexes only to find candidates.
 <!-- @/rule -->
 
 本文件用于定义 Kingscript skill 的全量 SDK 检索降级链路。
@@ -13,8 +20,7 @@ Files in references/sdk/indexes/ are grep-only. Never read_file on index files >
 ## 大文件警告
 
 - `references/sdk/indexes/class-index-full.md` 为完整类型列表，仅供 grep 检索，不建议全文加载。
-- `references/sdk/manifests/` 下的结构化清单文件体积可能较大，只适合按需查询，不适合整体加载。
-- 处理 SDK 问题时，先走 `quick-lookup.md` → `classes/` → `indexes/`，只有在索引不足时再按需读取清单文件。
+- 处理 SDK 问题时，先走 `quick-lookup.md` → `classes/` → `indexes/`，索引不足时直接降级外部知识盘。
 
 ## 目标
 
@@ -25,6 +31,19 @@ Files in references/sdk/indexes/ are grep-only. Never read_file on index files >
 
 ## 标准降级链路
 
+### 第 -1 层：环境动态层（事实权威）
+
+优先读取（缓存可用时必经）：
+
+- `~/.kd/kingscript-sdk/<envName>/type-index.tsv`（类型 → 模块 → 包路径三要素直查）
+- `~/.kd/kingscript-sdk/<envName>/dts/`（目标环境真实的 `@cosmic/*` 声明：包级导出 + 模块根聚合，含方法签名与 `@since`）
+
+适用场景：
+
+- SDK 存在性、包归属、导入路径、方法签名的**事实判定**——苍穹版本不同，SDK 面不同，仓库快照只能作路由与离线回退
+- 缓存缺失或过期时先跑 `app-build/scripts/kingscript_sdk_sync.py ensure`
+- 缓存不可用（离线/老平台）：回退第 0 层以下，并在结果中声明 snapshot-degraded
+
 ### 第 0 层：快速路由层（新增）
 
 优先读取：
@@ -72,25 +91,15 @@ Files in references/sdk/indexes/ are grep-only. Never read_file on index files >
 - 用户说法与 SDK 正式名称不一致
 - 还没有对应知识卡
 
-### 第 3 层：清单层
-
-如果索引不足以回答细节，再读取结构化清单：
-
-- `references/sdk/manifests/summary.json`
-- `references/sdk/manifests/modules.json`
-- `references/sdk/manifests/packages.json`
-- `references/sdk/manifests/const-exports.json`
-- `references/sdk/manifests/namespaces.json`
-
-适用场景：
+### 第 3 层：清单层（已移除）
 
-- 需要全量定位
-- 需要确认导出名、namespace、模块归属
-- 需要做长尾 SDK 兜底检索
+原 `manifests/*.json` 结构化清单已随环境动态层（第 -1 层）的引入而移除：SDK 存在性、
+导出名、namespace、模块归属的事实判定一律走环境缓存 `type-index.tsv`。索引（第 2 层）
+未命中候选时直接降级第 4 层；缓存不可用（离线/老平台）时声明 snapshot-degraded。
 
 ### 第 4 层：外部挂载知识盘（可选扩展层）
 
-如果仓库内知识卡、索引和清单仍不足以回答问题，而维护者本地额外挂载了 SDK 文档包或反编译知识库，可以按需进入外部知识盘。
+如果仓库内知识卡和索引仍不足以回答问题，而维护者本地额外挂载了 SDK 文档包或反编译知识库，可以按需进入外部知识盘。
 
 推荐入口：
 
@@ -172,10 +181,10 @@ Files in references/sdk/indexes/ are grep-only. Never read_file on index files >
 
 - 当前命中的类或方法
 - 来源层级
+  - 环境动态
   - 快速路由
   - 知识卡
   - 索引
-  - 清单
   - 本地声明
   - 在线 Javadoc
 - 已确认事实