@done-coding/admin-core 0.27.0 → 0.28.0

package/types/components/app-layout/app-page-geometry.d.ts

@@ -35,7 +35,7 @@ export interface AppPageSlotSizes {
  * AppPage（四槽 owner）据此扣槽后**同键重 provide**，四家一次修好。左右槽只减宽、不影响高，故只扣 top/bottom；
  * 扣减量与 shim padding 同式（见 {@link appPageSlotInset}）以与内容内缩一致。
  */
-export declare function computeAppPageReducedViewportHeight(bodyViewportHeight: number, slotSizes: AppPageSlotSizes, shimPadding: number): number;
+export declare function computeAppPageReducedViewportHeight(bodyViewportHeight: number, slotSizes: AppPageSlotSizes, outerGap: number): number;
 /**
  * 扣掉 left/right 槽后的内容视口可用宽（纯函数，钳非负）——「撑满且不出横向滚动条」的最大宽。
  *
@@ -43,7 +43,7 @@ export declare function computeAppPageReducedViewportHeight(bodyViewportHeight:
  * [MUST NOT] 用 `calc(100vw − …)` 推：100vw 含滚动条宽，有纵向滚动条时按其撑满会横向溢出）。
  * 扣减量与 {@link computeAppPageReducedViewportHeight} 同式（{@link appPageSlotInset}，与 shim padding 回写一致）。
  */
-export declare function computeAppPageReducedViewportWidth(pageBoxWidth: number, slotSizes: AppPageSlotSizes, shimPadding: number): number;
+export declare function computeAppPageReducedViewportWidth(pageBoxWidth: number, slotSizes: AppPageSlotSizes, outerGap: number): number;
 /**
  * 合成「固定 chrome 四边内衬」（px, 窗口坐标，纯函数）= app 级 chrome inset + 对应悬浮槽（含 gap，仅槽存在时计）。
  * 供 tile 等自然流 window 滚动定位不被固定 chrome 遮（`APP_PAGE_CONTENT_INSET`）。
@@ -63,17 +63,26 @@ export declare const APP_PAGE_SLOT_Z_INDEX = 1;
  *   未渲染时对应 H=0 即自动贴满。
  * 全 viewport 坐标、scroll 不变；调用方传响应式快照即随 chrome 跟。
  *
- * @param topH/bottomH top/bottom 区量得高（含其 shim 边距；未渲染为 0），用于 left/right 让位。
+ * @param slotSizes 四区量得尺寸（本函数只用 topH/bottomH —— left/right 只减宽、不影响竖向跨度）。
+ * @param outerGap 外圈档（`gapScaleValue(基数,"outer")`）——**槽 ↔ 槽**的间隔。
+ *
+ * 🔴 让位量走 {@link appPageSlotInset}（`v ? v + outerGap : 0`），与 `shimStyle`
+ * （槽 ↔ 默认内容）**同式同源**。huhyx7 只改了 shim 那一处、漏了本函数，导致
+ * 「默认内容让了一个外圈档、而 left/right 紧贴 top/bottom 零间隙」——同一页里
+ * 两种让位口径并存。[MUST NOT] 只改一处。
  */
-export declare function computeAppPageSlotStyles(rect: AppPageRectInset, topH: number, bottomH: number): AppPageSlotStyles;
+export declare function computeAppPageSlotStyles(rect: AppPageRectInset, slotSizes: AppPageSlotSizes, outerGap: number): AppPageSlotStyles;
 /**
  * AppPage 四区内层 shim 的四边 padding（纯函数）。
  *
- * 朝 chrome 的外侧边留 `sp`（= app-body-shim 内边距，复刻原呼吸）、朝内容的内侧边留
- * `gap`（AppPage 级控距）；left/right 的上下边为 0（竖向间隔由 top/bottom 区的 `gap` 边管）。
- * `padding` 简写按 上/右/下/左。
+ * 🔴 **huhyx7 起四边恒 0**，两个来源都消失了：
+ * - **朝 chrome 侧**：原本留 `shimPadding` 是为了复刻 `app-body-shim` 的内呼吸
+ *   （槽是 `fixed`、逃出了那层 padding 盒）。该 padding 已废除，无可复刻之物；
+ *   且槽本就贴在 `.app-body` 的 padding 盒边缘，**外圈档已经给过呼吸**。
+ * - **朝内容侧**：间隔改由**默认槽**让出（见 {@link appPageSlotInset}），
+ *   槽这边 [MUST] 归零，否则两边各让一份 = 双份。
  *
- * @param sp  app-body-shim 内边距（朝 chrome 侧呼吸）
- * @param gap AppPage gap（朝内容侧间隔）
+ * 保留本函数而非删掉挂点：槽内层 shim 仍是布局盒（`left/right` 靠它填满竖轨），
+ * 且留一个显式的「四边为 0 是刻意的」出口，比让下一个人从空 div 里猜要好。
  */
-export declare function computeAppPageSlotShimStyles(sp: number, gap: number): AppPageSlotStyles;
+export declare function computeAppPageSlotShimStyles(): AppPageSlotStyles;

package/types/components/app-layout/app-page-recommended.d.ts

@@ -0,0 +1,12 @@
+import { AppPageListLayoutRecommended } from './types';
+/**
+ * 窄栏（`AppPage#left` / `#right`）里放 `ListLayout` 的推荐配置（固定内置值，非运行时开关）。
+ *
+ * **唯一来源**：`AppPage` 经 `#left` / `#right` 插槽 scope 下发（`listLayoutRecommended`），
+ * `AppPageListDetailSplit` 经 `#list` 插槽 scope 转发 —— 两条通道读同一份常量，
+ * [MUST NOT] 各写一份（同一个会变的值抄两处必漂移）。
+ *
+ * 与 `useContextDefaults` 的分工：后者是**隐式**通道（自动生效但要求直系父可达），本常量是
+ * **显式**通道（消费方在 `#list` 里包了包裹层、隐式通道断链时的出路）。两者值域刻意重叠。
+ */
+export declare const APP_PAGE_LIST_LAYOUT_RECOMMENDED: AppPageListLayoutRecommended;

package/types/components/app-layout/index.d.ts

@@ -11,3 +11,4 @@ export { AppLayout, AppHeader, AppSidebar, AppAside, AppBody, AppBreadcrumb, App
 export * from './types';
 export * from './viewport';
 export * from './app-page-geometry';
+export * from './app-page-recommended';

package/types/components/data-view/types.d.ts

@@ -32,6 +32,12 @@ export type DataViewColumn<T extends Record<string, any> = Record<string, any>>
  * 外层用 CSS 决定，本组件不内置任何列数 / 布局。
  */
 export interface DataListViewProps<T extends Record<string, any>, F extends Record<string, any>> {
+    /**
+     * 当前项**跟随滚动**（默认开）：`activeId` 变化后把对应项滚进视口。
+     * 用 `nearest` 语义 ⇒ **已在视口内则零动作**，用户自己滚着看时点某项不会被拽走。
+     * 上/下一条导航、深链直达当前项等场景全靠它。关掉传 `false`。
+     */
+    activeScroll?: boolean;
     /** 当前页数据（外部传入，组件不持有请求 / 分页逻辑） */
     data: T[];
     /** 行唯一键：行数据键名 或 取键函数（内部统一 String 化） */
@@ -121,6 +127,12 @@ export interface InfiniteListViewProps<T extends Record<string, any> = Record<st
     estimateSize?: number;
     /** 视口外预渲染项数 */
     overscan?: number;
+    /**
+     * 自持面（默认 `true`）：面色 + 内呼吸 + 圆角，单独用也观感一致。
+     * 置于 `ModalConfirm` 正文时经上下文自动取 `false`；显式传值恒优先。
+     * 详见 `hooks/use-surface.ts`。
+     */
+    surface?: boolean;
     /** 传入时容器限高滚动（内部 overflowY: auto）；数字 = px，字符串 = CSS 长度（如 "100vh"） */
     maxHeight?: number | string;
     /** opt-in 触摸下拉刷新（默认关） */
@@ -155,6 +167,12 @@ export interface DataGridViewProps<T extends Record<string, any>, SQ extends Rec
      * （24 栅格，如 `{ xs: 24, sm: 12, md: 8, lg: 6, xl: 4 }`，列数 = 24 / span）。
      */
     gridColumns?: number | GridColumnsConfig;
+    /**
+     * 自持面（默认 `true`）：面色 + 内呼吸 + 圆角，单独用也观感一致。
+     * 置于 `ModalConfirm` 正文时经上下文自动取 `false`；显式传值恒优先。
+     * 详见 `hooks/use-surface.ts`。
+     */
+    surface?: boolean;
     /**
      * 数据区最大高度；与 refine 二选一作为高度基准。
      * 数字 = px；字符串 = CSS 长度（默认 "100vh" = 满视口高，等价视口高度限高，

package/types/components/data-view/use-active-scroll.d.ts

@@ -0,0 +1,30 @@
+import { Ref } from 'vue';
+import { ActiveRecordKey } from '../../hooks/use-active-record';
+/** {@link useActiveScroll} 入参 */
+export interface UseActiveScrollOptions {
+    /** 开关（默认由消费组件的 prop 决定） */
+    enabled: () => boolean;
+    /** 当前项 id（变化即触发跟随） */
+    activeId: Ref<ActiveRecordKey | undefined>;
+    /** 列表根容器（在其内部按 `activeSelector` 找当前项） */
+    container: () => HTMLElement | null | undefined;
+    /** 当前项选择器，默认 `.is-active` */
+    activeSelector?: string;
+}
+/**
+ * 当前项**跟随滚动**：`activeId` 变化后把对应 DOM 滚进视口（非主干增强，规则 22）。
+ *
+ * 用 `domScrollIntoViewport`（`block/inline: "nearest"`）：
+ * - **已在视口内则零动作** —— 用户自己滚着看时点某项不会被拽走，干扰极小；
+ * - `nearest` 同时避免「越级滚动」（默认 `start` 会把整个 body 滚了）。
+ *
+ * 🔴 瞬时（`behavior: "auto"`）而非 `smooth`：这是**跟随**不是**导航**。
+ * 本仓 `TabsTile` 自研 smooth 滚动曾被 v-model 回流重渲染打断（真机复现），
+ * [MUST NOT] 在此默认 smooth。
+ *
+ * `nextTick` 是必须的：`activeId` 变化到「当前项 DOM 拿到 active 类」要等一次渲染，
+ * 同步查会选中**上一个**当前项。
+ *
+ * 删除该功能 = 删本文件 + 组件里那一行委托 + prop（规则 22 可摘除边界）。
+ */
+export declare const useActiveScroll: (options: UseActiveScrollOptions) => void;

package/types/components/display/BadgeMark.vue.d.ts

@@ -108,7 +108,7 @@ declare function __VLS_template(): {
             max: number;
             showZero: boolean;
             badgeStyle: string | false | import('vue').CSSProperties | import('vue').StyleValue[] | null;
-        }> & Omit<Readonly<import('element-plus').BadgeProps> & Readonly<{}>, "value" | "max" | "content" | "offset" | "type" | "showZero" | "badgeStyle"> & {
+        }> & Omit<Readonly<import('element-plus').BadgeProps> & Readonly<{}>, "offset" | "type" | "value" | "max" | "content" | "showZero" | "badgeStyle"> & {
             content: string;
         } & {} & import('vue').ComponentCustomProperties & {} & {
             $slots: {
@@ -187,7 +187,7 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}
         max: number;
         showZero: boolean;
         badgeStyle: string | false | import('vue').CSSProperties | import('vue').StyleValue[] | null;
-    }> & Omit<Readonly<import('element-plus').BadgeProps> & Readonly<{}>, "value" | "max" | "content" | "offset" | "type" | "showZero" | "badgeStyle"> & {
+    }> & Omit<Readonly<import('element-plus').BadgeProps> & Readonly<{}>, "offset" | "type" | "value" | "max" | "content" | "showZero" | "badgeStyle"> & {
         content: string;
     } & {} & import('vue').ComponentCustomProperties & {} & {
         $slots: {

package/types/components/display/DragFloat.vue.d.ts

@@ -0,0 +1,35 @@
+/** 初始停靠角 */
+type DragFloatPlacement = "top-right" | "top-left" | "bottom-right" | "bottom-left";
+type __VLS_Props = {
+    /** 初始停靠角（拖动后失效，以拖后位置为准） */
+    placement?: DragFloatPlacement;
+    /** 初始角内缩偏移 px（负值 = 微溢出宿主角） */
+    offset?: number;
+    /** 呼吸光影（主色缓慢明暗；reduced-motion 静止、拖拽中暂停） */
+    breathing?: boolean;
+};
+declare function __VLS_template(): {
+    attrs: Partial<{}>;
+    slots: {
+        default?(_: {}): any;
+    };
+    refs: {
+        rootRef: HTMLDivElement;
+    };
+    rootEl: HTMLDivElement;
+};
+type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
+declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    placement: DragFloatPlacement;
+    offset: number;
+    breathing: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    rootRef: HTMLDivElement;
+}, HTMLDivElement>;
+declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
+export default _default;
+type __VLS_WithTemplateSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/types/components/display/TabsHeader.vue.d.ts

@@ -5,6 +5,12 @@ type __VLS_Props = {
     level?: number;
     /** 视觉风格变体;不传按 level 推导默认 */
     variant?: TabsHeaderVariant;
+    /**
+     * `card` 变体下**选中块**的底色（默认取底档 `--el-bg-color-page`）。
+     * 消费方可换成主色浅调等（如 `var(--el-color-primary-light-9)`）做高亮态。
+     * 🔴 [MUST] 传 CSS 变量或主题色，[MUST NOT] 写死色值 —— 写死切主题 / 亮暗不跟（规则 14）。
+     */
+    activeBg?: string;
 };
 type __VLS_PublicProps = {
     "activeKey"?: string;
@@ -25,6 +31,7 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_PublicProps,
     "onUpdate:activeKey"?: ((value: string) => any) | undefined;
 }>, {
     level: number;
+    activeBg: string;
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, HTMLDivElement>;
 declare const _default: __VLS_WithTemplateSlots<typeof __VLS_component, __VLS_TemplateResult["slots"]>;
 export default _default;

package/types/components/display/index.d.ts

@@ -1,3 +1,4 @@
+import { default as DragFloat } from './DragFloat.vue';
 import { default as ShadowClone } from './ShadowClone.vue';
 import { default as WatchSize } from './WatchSize.vue';
 import { default as TabsMain } from './TabsMain.vue';
@@ -55,5 +56,11 @@ BooleanTag,
  * `disabled` 关闭分身仅就地）。两份 vnode 树 = 两个独立实例，只适合无内部状态的受控组件
  * （v-model 绑同一 ref 即同源同步）；静态固定 id 双份会撞，消费方负责。
  */
-ShadowClone, };
+ShadowClone, 
+/**
+ * 可拖拽悬浮容器：默认插槽内容变成宿主容器（offsetParent，[MUST] 有定位）内可拖拽的
+ * 悬浮块——容器内约束 + 点击拖拽消歧（拖过阈值不触发 click）+ 呼吸光影 + 位置会话内
+ * 记忆。首个消费者 = FormMain AI 填充触发器。[MUST NOT] 当 fixed 全局悬浮球用。
+ */
+DragFloat, };
 export * from './types';

package/types/components/display/tabs-variant.d.ts

@@ -0,0 +1,17 @@
+import { TabsHeaderVariant } from './types';
+/** level 钳到 [1,4]（超 4 档按 4 处理） */
+export declare const tabsClampLevel: (level: number) => number;
+/**
+ * 解析最终 variant：显式传入恒优先，否则按 level 推导默认。
+ *
+ * 🔴 `TabsHeader`（画 tab 条）与 `TabsMain`（决定 header ↔ content 之间留不留呼吸位）
+ * **都要知道最终 variant**，故抽为纯函数共用 —— [MUST NOT] 两处各写一份推导，
+ * 那样 card 的「选中块与 content 连通」会在某一侧悄悄失配。
+ */
+export declare const resolveTabsHeaderVariant: (variant: TabsHeaderVariant | undefined, level: number) => TabsHeaderVariant;
+/**
+ * `card` 变体下选中块 / 根底的缺省色（底档）。
+ * 🔴 `TabsHeader`（画选中块）与 `TabsMain`（给根铺同色保连通）**共用此常量** ——
+ * 两处各写一份默认值，就会出现「选中块有色、根还是透明」的半截连通。
+ */
+export declare const TABS_ACTIVE_BG_DEFAULT = "var(--el-bg-color-page)";

package/types/components/display/types.d.ts

@@ -209,6 +209,12 @@ export interface TabsMainProps {
     refineReduceHeight?: number;
     /** 显式指定 TabsHeader 视觉风格,不传则按 visualLevel 推导默认(L1=card / L2=indicator / L3=indicator-compact / L4=plain)。字号始终跟随 level,不受 variant 影响。 */
     variant?: TabsHeaderVariant;
+    /**
+     * `card` 变体下**选中块**的底色（默认底档 `--el-bg-color-page`）。
+     * 换主色浅调（`var(--el-color-primary-light-9)`）即高亮态。
+     * [MUST] 传 CSS 变量 / 主题色，[MUST NOT] 写死色值（规则 14）。
+     */
+    activeBg?: string;
     /**
      * 把当前激活 tab(v-model)同步到路由 URL query 的 key 名。
      * - 传了即启用**双向同步**：切 tab → `router.replace` 写 `?{queryKey}={tab.key}`(不压历史栈、只增删自己这个 key、不动其它 query);

package/types/components/form/FormDivider.vue.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vue').DefineComponent<{}, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export default _default;

package/types/components/form/FormGroupTitle.vue.d.ts

@@ -0,0 +1,22 @@
+type __VLS_Props = {
+    /** 分组标题文案 */
+    title: string;
+    /** 是否可折叠（false = 纯标题，无箭头无点击） */
+    collapsible?: boolean;
+    /** 当前折叠态（真相在 swiftFormItemGroup 闭包，本组件只读） */
+    collapsed?: boolean;
+    /** 组内成员字段 key —— 用于判断校验错误是否落在本组 */
+    memberKeys?: string[];
+    /** 切换折叠（回调 prop，配置化挂载经 h() 传入） */
+    onToggle?: () => void;
+    /** 展开（幂等，校验失败自动展开用；回调 prop） */
+    onExpand?: () => void;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    onToggle: () => void;
+    collapsed: boolean;
+    collapsible: boolean;
+    memberKeys: string[];
+    onExpand: () => void;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/types/components/form/FormItemNestForm.vue.d.ts

@@ -31,6 +31,8 @@ declare const _default: import('vue').DefineComponent<__VLS_PublicProps, {}, {},
         generate: () => Record<string, any>;
         parse: (stringifyData: import('./types').ExcludeNeverProperties<import('./types').ExtractFormStringifyRawFromObject<Record<string, any>, Record<string, any>>>) => Record<string, any>;
         stringify: () => import('./types').ExcludeNeverProperties<import('./types').ExtractFormStringifyRawFromObject<Record<string, any>, Record<string, any>>>;
+        getAiSchema: () => Promise<import('./types').FormAiSchema>;
+        setValues: (partial: Partial<Record<string, any>>) => void;
     } | null;
 }, any>;
 export default _default;

package/types/components/form/ai-schema.d.ts

@@ -0,0 +1,24 @@
+import { FormAiSchema, FormItemConfigList } from './types';
+import { CoreConfigDescription } from '../../bridge';
+/**
+ * 表单目标描述解析（trsf36）：`FormMainProps.description` → schema 顶层 description 文本。
+ * string 直用；`CoreConfigDescription` 对象拼「适用：…／不适用：…」（与字段级
+ * {@link buildAiDescription} 措辞同源）；空 / 全空对象 → undefined（duck 不输出）。
+ */
+export declare const resolveFormAiFormDescription: (description: string | CoreConfigDescription | undefined) => string | undefined;
+/** `getFormAiSchema` 可选项（trsf36 追加，additive） */
+export interface GetFormAiSchemaOptions {
+    /** 表单目标描述（→ schema 顶层 description，见 {@link resolveFormAiFormDescription}） */
+    description?: string | CoreConfigDescription;
+}
+/**
+ * 导出表单机器可读描述——按 OpenAI strict 硬限制裁剪的 JSON Schema（AI 填充数据层）。
+ * ----
+ * - property key = 配置 key（key 是身份，description 是语义，D4）；全 key 进 required，
+ *   每字段 `anyOf: [载荷, {type:"null"}]`——null = 留空通道（不确定就留空，D8-ⓑ）。
+ * - 过滤：ignore（含 `__` 全大写约定）/ hide 为真 / aiIgnore 为真的项不导出（D5 + 隐私面）。
+ * - 选项三形态见 {@link resolveAiOptions}（getOptions 异步 ⇒ 本函数 async）。
+ * - 🔴 pattern / format / minLength 不被模型执行 ⇒ 校验回落表单自己的 rules（D1）。
+ * - 表单目标描述（trsf36）经 options.description 落顶层 description（缺省不输出）。
+ */
+export declare const getFormAiSchema: <PO extends Record<string, any>, SO extends Record<string, any>>(list: FormItemConfigList<PO, SO>, data: PO, options?: GetFormAiSchemaOptions) => Promise<FormAiSchema>;

package/types/components/form/group.d.ts

@@ -0,0 +1,36 @@
+import { FormItemConfig, FormItemConfigList } from './types';
+/**
+ * 折叠态的**视觉隐藏**类名（样式在 `FormMain.vue`）。
+ * 🔴 走 class 而非 `hide`：`hide` 会进 `hideKeyList` 并被 `validate()` 抹掉错误 ——
+ * 折叠区的必填项就此静默失效。视觉隐藏不影响 el-form-item 的校验。
+ */
+export declare const COLLAPSED_CLASS = "dc-form-item-collapsed";
+/** `swiftFormItemGroup` 可选项 */
+export interface SwiftFormItemGroupOptions {
+    /** 初始是否折叠（非受控，默认 false = 展开） */
+    defaultCollapsed?: boolean;
+    /** 是否可折叠（默认 true；false = 纯分组标题，不接管组内项显隐） */
+    collapsible?: boolean;
+    /** 标题伪 item key 覆盖（[MUST] `__` 前缀全大写；缺省内部自增 `__GROUP_<n>`） */
+    key?: string;
+}
+/**
+ * 快捷配置表单分组：`[标题伪 item, ...组内项]` 扁平展开。
+ *
+ * - 标题伪 item **恒 `span: 24` 不可配**（甲方 2026-09-15 明定，不给覆盖口子）。
+ * - 折叠态**按 FormMain 实例隔离**：以 `scope.data` 对象身份为键懒建 ref——同一份
+ *   配置喂多个表单实例（如 C4 行列表每行）互不串态。
+ * - 折叠 = **纯视觉收起**：组内项照常参与校验；有必填未填时 `validate()` 照常失败，
+ *   并由 `FormGroupTitle` **自动展开本组 + 滚动到错误项**（[MUST NOT] 让使用者
+ *   面对「看不见错在哪、却提交不了」，也 [MUST NOT] 把必填项静默跳过）。
+ * - 组内项原有 `hide`（布尔 / 函数）**不受折叠影响**，两者是正交的两件事。
+ */
+export declare const swiftFormItemGroup: <PO extends Record<string, any>, 
+/** 需要格式化的模型 */
+SO extends Record<string, any>>(title: string, items: FormItemConfigList<PO, SO>, options?: SwiftFormItemGroupOptions) => FormItemConfigList<PO, SO>;
+/**
+ * 快捷配置表单分割线：单个伪 item（`ElDivider`，恒整行、数据零污染）。
+ */
+export declare const swiftFormItemDivider: <PO extends Record<string, any> = Record<string, any>, 
+/** 需要格式化的模型 */
+SO extends Record<string, any> = Record<string, any>>() => FormItemConfig<PO, SO>;

package/types/components/form/index.d.ts

@@ -22,6 +22,8 @@ import { default as FormItemNestForm } from './FormItemNestForm.vue';
 import { default as FormItemNestFormList } from './FormItemNestFormList.vue';
 export * from './types';
 export * from './utils';
+export * from './group';
+export * from './ai-schema';
 export * from './nest-registry';
 export * from './use-nest-form';
 export * from './nest-form-item';

package/types/components/form/types.d.ts

@@ -1,5 +1,6 @@
 import { FormItemRule, ColProps, FormItemProps, ButtonProps, AffixProps } from 'element-plus';
-import { VNode, ComputedRef } from 'vue';
+import { VNode, ComputedRef, Component } from 'vue';
+import { CoreConfigDescription } from '../../bridge';
 export type OnlyOneKey<T extends Record<string, any>> = {
     [K in keyof T]: {
         [P in K]?: T[P];
@@ -22,6 +23,36 @@ export type FormItemConfigExtra = OnlyOneKey<{
 interface WrapProps extends FormItemProps {
     [key: string]: any;
 }
+/** AI 填充数据类型（`FormItemConfig.type`；OpenAI strict 支持的基元集，期一 array 恒字符串元素） */
+export type FormAiValueType = "string" | "number" | "integer" | "boolean" | "array";
+/** getAiSchema 单字段有效载荷（anyOf 第一分支；第二分支恒 `{type:"null"}` 留空通道） */
+export interface FormAiSchemaPayload {
+    type: FormAiValueType;
+    /** 选项枚举（options / getOptions 形态且值类型均一才挂；remoteMethod 不可穷举不产出） */
+    enum?: Array<string | number>;
+    /** 数组元素约束（仅 type:"array"；期一只支持字符串数组，D7） */
+    items?: {
+        type: "string";
+    };
+}
+/** getAiSchema 单字段投影（description = label + tip(string) + suitable/unsuitable + 选项 label 拼装） */
+export interface FormAiSchemaProperty {
+    description: string;
+    /** [载荷, null]——所有字段进 required 后由 null 分支表达"留空"（模型不确定就留空） */
+    anyOf: [FormAiSchemaPayload, {
+        type: "null";
+    }];
+}
+/** 表单机器可读描述（按 OpenAI strict 硬限制裁剪的 JSON Schema，`getAiSchema()` 返回值） */
+export interface FormAiSchema {
+    type: "object";
+    /** 表单目标描述（trsf36，JSON Schema 标准顶层字段）——来自 `FormMainProps.description`，缺省不输出 */
+    description?: string;
+    properties: Record<string, FormAiSchemaProperty>;
+    /** strict 约束：全部导出字段进 required（可空由各字段 anyOf null 分支表达） */
+    required: string[];
+    additionalProperties: false;
+}
 /** formItem联动配置 */
 interface FormItemLinkConfig<K extends string, BV, OV> {
     /** 关联(该宿主配置)表单项的key */
@@ -104,6 +135,22 @@ SV extends PK extends keyof SO ? SO[PK] : PV = PK extends keyof SO ? SO[PK] : PV
      * 额外一些配置
      */
     extra?: FormItemConfigExtra;
+    /**
+     * AI 填充数据类型（getAiSchema 导出用；可选——加必填即 breaking）。
+     * 解析优先级：显式 > init typeof 推导 > 兜底 "string"。
+     * 语义类型（人名/金额）写 description，[MUST NOT] 另开字段。
+     */
+    type?: FormAiValueType;
+    /**
+     * AI 填充选型描述（正/反两面精调位，复用主题那套 {@link CoreConfigDescription}），
+     * 拼进 schema property description（与 label / string 形态 tip 同拼）。
+     */
+    description?: CoreConfigDescription;
+    /**
+     * AI 填充排除（隐私面）：本项不出现在 getAiSchema 导出——
+     * schema 会带走 label + 选项数据（可能含客户名单 / 内部编码），逐字段按需排除。
+     */
+    aiIgnore?: boolean;
 }
 /** form配置 */
 export type FormItemConfigList<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> = FormItemConfig<PO, SO>[];
@@ -144,9 +191,19 @@ export interface FormMainInstance<PO extends Record<string, any> = Record<string
     generate: () => PO;
     parse: (stringifyData: ExtractFormStringifyFromObject<PO, SO>) => PO;
     stringify: () => ExcludeNeverProperties<ExtractFormStringifyRawFromObject<PO, SO>>;
+    /**
+     * 导出表单机器可读描述（OpenAI strict 裁剪 JSON Schema，AI 填充数据层）。
+     * async：getOptions 型选项需异步拉取后并入 enum。
+     */
+    getAiSchema: () => Promise<FormAiSchema>;
+    /**
+     * 按 key 就地 patch 表单值（[MUST NOT] 换 data 容器引用——父子同引用贯通，换即断链）。
+     * 只写配置内非 ignore 的 key；undefined / null 跳过（= 留空语义）。
+     */
+    setValues: (partial: Partial<PO>) => void;
 }
 /** FormSearch expose类型 */
-export interface FormSearchInstance<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> extends Omit<FormMainInstance<PO, SO>, "generate" | "parse" | "stringify"> {
+export interface FormSearchInstance<PO extends Record<string, any> = Record<string, any>, SO extends Record<string, any> = Record<string, any>> extends Omit<FormMainInstance<PO, SO>, "generate" | "parse" | "stringify" | "getAiSchema" | "setValues"> {
     /** 触发搜索 */
     triggerSearch: () => void;
     /** 触发重置 */
@@ -180,6 +237,28 @@ export interface FormMainProps<PO extends Record<string, any>, SO extends Record
      * 嵌套子表单（FormNest 等联结组件）是独立 FormMain 实例，需各自开启。
      */
     layoutByContainer?: boolean;
+    /**
+     * AI 填充入口开关（e9dzn4 交互层 / gf9z3w 控制反转）。缺省 undefined = 自动：
+     * 触发组件可用（bridge `aiFillTrigger` ∥ {@link aiFillTrigger} prop）且本实例非
+     * 嵌套子表单时出悬浮触点；`false` = 组件级否决恒关。嵌套实例（C1 / C4 内）恒关
+     * 不受此值影响。`FormSearch` 同自动档（透传本 prop，undefined [MUST] 保持三态）。
+     */
+    aiFill?: boolean;
+    /**
+     * AI 填充触发组件局部覆盖（某表单换触发器）；缺省走 bridge 主通道
+     * `bridge.register({ aiFillTrigger })`。core 渲染时喂 duck props
+     * （`getSchema` / `onData → { appliedCount, undo }`），组件来源任意。
+     */
+    aiFillTrigger?: Component;
+    /**
+     * 表单目标描述（trsf36）：这个表单是做什么的——落 `getAiSchema()` 产出的
+     * schema **顶层 `description`**，让模型带着表单意图理解字段（录入 vs 筛选等）。
+     * string = 主干场景直用；`CoreConfigDescription` 对象 = 正/反两面精调
+     * （拼「适用：…／不适用：…」，与字段级 {@link FormItemConfig.description} 同源语义）。
+     * 缺省不输出该字段。AI 只是第一个消费方——本 prop 描述表单本体，
+     * [MUST NOT] 冠 ai 前缀。`FormSearch` 同名 prop 透传并自动拼接筛选形态语义。
+     */
+    description?: string | CoreConfigDescription;
 }
 /** FormSearch props */
 export interface FormSearchProps<PO extends Record<string, any>, SO extends Record<string, any>, SQ extends Record<string, any>> extends FormMainProps<PO, SO> {
@@ -244,7 +323,7 @@ export interface DatePickerShortcut {
 }
 export type FormItemConfigSwiftOptionsCommon<PO extends Record<string, any>, 
 /** 需要格式化的模型 */
-SO extends Record<string, any>> = Omit<FormItemConfig<PO, SO>, "rules"> & {
+SO extends Record<string, any>> = Omit<FormItemConfig<PO, SO>, "rules" | "type"> & {
     /** label */
     /**
      *  表单类型
@@ -356,6 +435,18 @@ export type FormSubmitPanelProps<PO extends Record<string, any>, SO extends Reco
      * 与 divider 正交：divider 管边框+圆角，bare 管 padding，可叠加全 flush。
      */
     bare?: boolean;
+    /**
+     * 根面板是否**成面**（背景色 + 内呼吸 + 圆角），默认 `true`。
+     *
+     * 页面里它躺在灰底 `--el-bg-color-page` 上 ⇒ 要成面才有「一块卡」的层级；
+     * **弹窗里它躺在 `--el-bg-color-overlay`（已经是面）上 ⇒ [MUST NOT] 再刷一层**，
+     * 否则暗色下 overlay `#1d1e1f` 上盖 `#141414` = 弹窗里凹下去一块
+     * （亮色两者都是 `#fff`，看不出来 —— [MUST NOT] 只用亮色截图验收）。
+     *
+     * 缺省由上下文推导：直系父带 `SlotRegion.ModalConfirm_Body` 标记 ⇒ `false`；
+     * 其余 ⇒ `true`。显式传值恒优先。
+     */
+    surface?: boolean;
     /** 根面板自定义 class（显式根出口）
      * ----
      * inheritAttrs:false 下消费方 `class` 经 v-bind 转发内层 FormMain（对标 FormSearch），

package/types/components/form/use-ai-fill.d.ts

@@ -0,0 +1,59 @@
+import { Component, ComputedRef } from 'vue';
+import { CoreConfigDescription } from '../../bridge';
+import { FormAiSchema, FormItemConfigList } from './types';
+/**
+ * FormMain · AI 填充「插座 + 落表」hook（e9dzn4 交互层 → gf9z3w 控制反转终态；
+ * 组件同级收纳，规则 21/22，不出桶）。
+ *
+ * 控制反转分工（甲方 2026-09-15 拍定）：
+ * - **core（本 hook）**：挂点显隐三闸 + 喂 duck props（`getSchema` / `onData`）+
+ *   数据落表（setValues 同判据）+ 写入项高亮 + 撤销**机制**（快照回滚）。
+ * - **触发组件（bridge 注册，如 forge-agent LlmJsonTrigger）**：全部 AI 交互 UI——
+ *   popup / prompt 获取 / LLM 调用 / 错误展示 / 撤销**按钮**（拿 onData 回执渲染）。
+ * - 两侧互不知晓，应用层 bridge 组装。[MUST NOT] 在 core 里搓 LLM 调用或 prompt UI。
+ *
+ * 入口显隐三闸（都过才出）：
+ * - 触发组件可用：`aiFillTrigger` prop（局部覆盖）∥ bridge `aiFillTrigger`（主通道，
+ *   shallowRef 响应式）；
+ * - 非嵌套实例：C1 / C4 内的子 FormMain 经「能注入到父 FormMain registry」自判恒关；
+ * - `aiFill` prop ≠ false（组件级否决；三态布尔 [MUST] withDefaults 显式 undefined）。
+ */
+/** 触发组件 `onData` 回执（duck 契约的 core 半边） */
+export interface FormAiFillReceipt {
+    /** 实际写入的字段数 */
+    appliedCount: number;
+    /** 整体撤销本次写入（回滚到填充前快照 + 清高亮） */
+    undo: () => void;
+}
+/** `useFormAiFill` 依赖（getter 传入、只读不写——功能是主干状态的纯下游，规则 22） */
+export interface UseFormAiFillOptions<PO extends Record<string, any>> {
+    /** `props.aiFill`（undefined = 自动；false = 否决） */
+    getEnabled: () => boolean | undefined;
+    /** `props.aiFillTrigger`（局部覆盖，优先于 bridge 主通道） */
+    getTrigger: () => Component | undefined;
+    /** `props.description`（表单目标描述——bridge `aiFillRequireDescription` 策略位判据） */
+    getDescription: () => string | CoreConfigDescription | undefined;
+    /** 表单配置列表（算实际写入 key，与 `patchFormData` 同判据） */
+    getList: () => FormItemConfigList<PO, any>;
+    /** 表单数据（撤销快照源） */
+    getData: () => PO;
+    /** = `FormMainInstance.getAiSchema`（数据层，含表单目标 description 组装） */
+    getSchema: () => Promise<FormAiSchema>;
+    /** = `FormMainInstance.setValues`（数据层，就地 patch） */
+    applyValues: (partial: Partial<PO>) => void;
+}
+/** `useFormAiFill` 返回面（FormMain 模板挂点消费；符号带 aiFill 前缀，规则 9） */
+export interface UseFormAiFillReturn {
+    /** 入口是否渲染（三闸合一，响应式） */
+    aiFillVisible: ComputedRef<boolean>;
+    /** 生效触发组件（prop 局部覆盖 ∥ bridge 主通道） */
+    aiFillTriggerComponent: ComputedRef<Component | undefined>;
+    /** 喂给触发组件的 duck props（getSchema / onData） */
+    aiFillTriggerProps: {
+        getSchema: () => Promise<FormAiSchema>;
+        onData: (data: Record<string, any>) => FormAiFillReceipt;
+    };
+    /** 高亮 class（ElCol 挂点：本次写入的 key → 闪烁类） */
+    aiFillItemClass: (key: string) => string | undefined;
+}
+export declare const useFormAiFill: <PO extends Record<string, any>>(options: UseFormAiFillOptions<PO>) => UseFormAiFillReturn;

package/types/components/form/utils.d.ts

@@ -38,6 +38,15 @@ export declare const resolveFormLayout: (layout?: Partial<ColProps>, scale?: num
  * 与手动选日期完全同源，无需任何额外格式化依赖。
  */
 export declare const getDatePickerShortcuts: () => DatePickerShortcut[];
+/**
+ * 检测表单项是否忽略（`ignore` 显式 / `__` 前缀全大写 key 约定）。
+ * generate / parse / stringify / patch / AI schema 导出共用的**单一真相源判据**，
+ * [MUST NOT] 在消费侧另写一份。
+ */
+export declare const checkFormItemIsIgnore: (config: {
+    ignore?: boolean;
+    key: string;
+}) => boolean;
 /**
  * 生成表单数据
  */
@@ -50,6 +59,16 @@ export declare const parseFormData: <PO extends Record<string, any>, SO extends
  * 序列化表单数据
  */
 export declare const stringifyFormData: <PO extends Record<string, any>, SO extends Record<string, any>>(data: PO, list: FormItemConfigList<PO, SO>) => import('./types').ExcludeNeverProperties<import('./types').ExtractFormStringifyRawFromObject<PO, SO>>;
+/**
+ * 按 key 就地 patch 表单数据（AI 填充 / 程序化写值共用）。
+ * ----
+ * - [MUST NOT] 换 data 容器引用——PO 容器由 generate() 建、父子靠同一引用贯通，换引用当场断链；
+ *   本函数只做逐 key 赋值，父侧引用恒不变。
+ * - 只写配置内非 ignore 的 key（未知 key 不落容器，防幻觉 key 污染 PO 形态）。
+ * - undefined / null 跳过（= 留空语义，对齐 getAiSchema 的 null 留空通道）；
+ *   要清空字段由调用方传该字段类型的空值（"" / []）。
+ */
+export declare const patchFormData: <PO extends Record<string, any>, SO extends Record<string, any>>(data: PO, list: FormItemConfigList<PO, SO>, partial: Partial<PO>) => void;
 /**
  * 获取v-model语法糖配置
  */