@webskill/sdk 0.4.0 → 0.6.0

package/dist/{env--jJB-TSX-04klhTYi.js → env-8cY40DXB-CGnEVZby.js}

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 
-//#region ../node/dist/env--jJB-TSX.js
+//#region ../node/dist/env-8cY40DXB.js
 /** 解析 .env（简单 KEY=VALUE 行解析，不引依赖）；文件缺失返回 undefined */
 function readEnvVars(dotenvPath) {
 	let raw;
@@ -23,15 +23,16 @@ function readEnvVars(dotenvPath) {
 	return vars;
 }
 /**
-* 读取 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL（优先），
-* 向后兼容 VITE_BASE_URL / VITE_API_KEY / VITE_MODEL_NAME；缺项返回 undefined 供测试 skip 判断。
+* 读取 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL；缺项返回 undefined 供测试 skip 判断。
+* 0.6.0 FR-13.2 移除了旧的 `VITE_` 前缀回退：该前缀是 Vite 向**客户端 bundle** 注入变量的开关，
+* 把 API key 放在它名下等于告诉使用者“这个 key 会被打进前端产物”。
 */
 function loadLlmConfigFromEnv(dotenvPath = ".env") {
 	const vars = readEnvVars(dotenvPath);
 	if (!vars) return void 0;
-	const baseUrl = vars.get("LLM_BASE_URL") ?? vars.get("VITE_BASE_URL");
-	const apiKey = vars.get("LLM_API_KEY") ?? vars.get("VITE_API_KEY");
-	const model = vars.get("LLM_MODEL") ?? vars.get("VITE_MODEL_NAME");
+	const baseUrl = vars.get("LLM_BASE_URL");
+	const apiKey = vars.get("LLM_API_KEY");
+	const model = vars.get("LLM_MODEL");
 	if (!baseUrl || !apiKey || !model) return void 0;
 	return {
 		baseUrl,

package/dist/{env-BPUBZCwJ-4jat_SVG.d.ts → env-AK3cSMEA-Dli6QU5E.d.ts}

@@ -1,4 +1,4 @@
-//#region ../node/dist/env-BPUBZCwJ.d.ts
+//#region ../node/dist/env-AK3cSMEA.d.ts
 //#region src/env.d.ts
 interface LlmEnvConfig {
   baseUrl: string;
@@ -12,8 +12,9 @@ interface ProviderEnvConfig {
   baseUrl?: string;
 }
 /**
- * 读取 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL（优先），
- * 向后兼容 VITE_BASE_URL / VITE_API_KEY / VITE_MODEL_NAME；缺项返回 undefined 供测试 skip 判断。
+ * 读取 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL；缺项返回 undefined 供测试 skip 判断。
+ * 0.6.0 FR-13.2 移除了旧的 `VITE_` 前缀回退：该前缀是 Vite 向**客户端 bundle** 注入变量的开关，
+ * 把 API key 放在它名下等于告诉使用者“这个 key 会被打进前端产物”。
  */
 declare function loadLlmConfigFromEnv(dotenvPath?: string): LlmEnvConfig | undefined;
 /** ANTHROPIC_API_KEY / ANTHROPIC_MODEL（可选 ANTHROPIC_BASE_URL）；缺项返回 undefined */

package/dist/governance.d.ts

@@ -1,6 +1,6 @@
-import { $ as SkillDocument, N as FileSystemProvider, R as Page, Z as SkillCatalogEntry, c as LlmClient, d as LlmMessage, rt as SkillManagerPort, y as UiBridge, z as PageQuery } from "./types-7Wcg--Vh-1YlQ4jF9.js";
-import { Ct as SkillOutcomeReporter, Lt as WebSkillRuntime, P as IntegrityVerdict, St as SkillIntegrityGuard, Tt as SkillStateGuard, ut as RuntimeRun } from "./index-DLfR2Y6I.js";
-import { _ as SkillVersion, a as AuditLog, c as CandidateFile, d as CandidateSource, f as CandidateStatus, g as SkillState, h as SKILL_VERSION_PAGE_SIZE, i as AuditEvent, l as CandidateRisk, m as CompositeApprovalPolicy, n as ApprovalDecision, o as AuditQueryFilter, p as CandidateStore, r as ApprovalPolicy, s as CANDIDATE_PAGE_SIZE, t as AlwaysHumanApprovalPolicy, u as CandidateSkill, v as SkillVersionStore, y as candidateToCatalogEntry } from "./skillVersionStore-uyefLPR1-DXOzbksv.js";
+import { B as PageQuery, P as FileSystemProvider, Q as SkillCatalogEntry, b as UiBridge, et as SkillDocument, f as LlmMessage, it as SkillManagerPort, l as LlmClient, z as Page } from "./types-4pg-qp_I-Gq63X8Oa.js";
+import { It as SkillStateGuard, Mt as SkillOutcomeReporter, V as IntegrityVerdict, jt as SkillIntegrityGuard, on as WebSkillRuntime, vt as RuntimeRun } from "./index-C-KFAZoF.js";
+import { _ as SkillVersion, a as AuditLog, c as CandidateFile, d as CandidateSource, f as CandidateStatus, g as SkillState, h as SKILL_VERSION_PAGE_SIZE, i as AuditEvent, l as CandidateRisk, m as CompositeApprovalPolicy, n as ApprovalDecision, o as AuditQueryFilter, p as CandidateStore, r as ApprovalPolicy, s as CANDIDATE_PAGE_SIZE, t as AlwaysHumanApprovalPolicy, u as CandidateSkill, v as SkillVersionStore, y as candidateToCatalogEntry } from "./skillVersionStore-BzLbzFOL-CxdAFWO2.js";
 //#region ../governance/dist/index.d.ts
 //#region src/candidate/candidateNormalizer.d.ts
 /** 剥 markdown fence 与 <think> 块、截取首尾 {}；非对象 → CANDIDATE_INVALID */
@@ -32,6 +32,48 @@ declare function normalizeCandidate(input: {
 /** 候选校验：缺 SKILL.md / 非法扩展名 → CANDIDATE_INVALID */
 declare function validateCandidate(candidate: CandidateSkill): void;
 //#endregion
+//#region src/candidate/candidateSink.d.ts
+/**
+ * agent 侧 `SkillCandidateSink.submit()` 的入参形状。
+ * 这里按结构声明而不是 import `@webskill/agent`：治理层是可选层，
+ * 不该因为 agent 策略而多一条运行时依赖（两侧的兼容性由测试钉住）。
+ */
+interface GeneratedSkillSubmission {
+  draft: {
+    name: string;
+    description: string;
+    /** SKILL.md 全文，含 frontmatter */
+    content: string;
+    files?: readonly {
+      path: string;
+      content: string;
+    }[];
+  };
+  /** 触发生成的会话，写进候选 metadata 供 console 溯源 */
+  sessionId?: string;
+  /** 用户确认的时刻（FR-9.7 的「用户确认事实」） */
+  confirmedAt: string;
+}
+interface CandidateSinkOptions {
+  store: CandidateStore;
+  /** 缺省不写审计——但 FR-9.7 要求宿主接上它 */
+  audit?: AuditLog;
+  now?: () => string;
+  createId?: () => string;
+}
+interface CandidateSink {
+  submit(input: GeneratedSkillSubmission): Promise<{
+    id: string;
+  }>;
+}
+/**
+ * 把 agent 生成的技能草稿接进既有的候选管线（设计 02 §5）。
+ *
+ * 走的是与文档抽取、runtime-miss 完全相同的 `normalizeCandidate` → `CandidateStore.save`，
+ * 因此候选恒为 `draft`，审批/发布链路一行都不用改；差别只有 `source: 'generated'`。
+ */
+declare function createCandidateSink(options: CandidateSinkOptions): CandidateSink;
+//#endregion
 //#region src/candidate/llmCandidateGenerator.d.ts
 /** LLM 候选生成器：prompt 强制约束 + 不信任归一化管线 + candidate.created 审计 */
 declare class LlmCandidateGenerator {
@@ -363,4 +405,4 @@ declare function createMissHook(deps: {
  */
 declare function completeText(llm: LlmClient, messages: LlmMessage[]): Promise<string>;
 //#endregion
-export { AUDIT_PAGE_SIZE, AlwaysHumanApprovalPolicy, type ApprovalDecision, type ApprovalPolicy, type AuditEvent, type AuditLog, type AuditQueryFilter, CANDIDATE_PAGE_SIZE, type CandidateFile, type CandidateRisk, type CandidateSkill, type CandidateSource, type CandidateStatus, CandidateStore, CompositeApprovalPolicy, DependencyGraph, DocumentSkillExtractor, type EvaluationReport, type EvaluationResult, EvaluationRunner, type EvaluationTask, FailureAnalyzer, type FailureDiagnosis, FsAuditLog, LlmCandidateGenerator, type RepairOption, RepairPlanner, SCORING_WEIGHTS, SKILL_VERSION_PAGE_SIZE, type ScoreInput, SimilarityDetector, SkillScorer, type SkillState, SkillStatePolicy, type SkillVersion, SkillVersionStore, type SourceDocument, candidateToCatalogEntry, completeText, createMissHook, jaccardSimilarity, normalizeCandidate, normalizeCandidateFiles, normalizeRisk, parseJsonObject, readDocument, sanitizeCandidateName, suggestFromFailedRun, validateCandidate };
+export { AUDIT_PAGE_SIZE, AlwaysHumanApprovalPolicy, type ApprovalDecision, type ApprovalPolicy, type AuditEvent, type AuditLog, type AuditQueryFilter, CANDIDATE_PAGE_SIZE, type CandidateFile, type CandidateRisk, type CandidateSink, type CandidateSinkOptions, type CandidateSkill, type CandidateSource, type CandidateStatus, CandidateStore, CompositeApprovalPolicy, DependencyGraph, DocumentSkillExtractor, type EvaluationReport, type EvaluationResult, EvaluationRunner, type EvaluationTask, FailureAnalyzer, type FailureDiagnosis, FsAuditLog, type GeneratedSkillSubmission, LlmCandidateGenerator, type RepairOption, RepairPlanner, SCORING_WEIGHTS, SKILL_VERSION_PAGE_SIZE, type ScoreInput, SimilarityDetector, SkillScorer, type SkillState, SkillStatePolicy, type SkillVersion, SkillVersionStore, type SourceDocument, candidateToCatalogEntry, completeText, createCandidateSink, createMissHook, jaccardSimilarity, normalizeCandidate, normalizeCandidateFiles, normalizeRisk, parseJsonObject, readDocument, sanitizeCandidateName, suggestFromFailedRun, validateCandidate };

package/dist/governance.js

@@ -1,5 +1,5 @@
 import { O as messageOf, T as isValidSkillName, g as assertSafePathSegment, m as WebSkillError } from "./dist-8oQRa8Xz.js";
-import { i as textParts, n as partsToText } from "./memoryArtifactStore-BtOeB_hm-tj3fC5ip.js";
+import { a as textParts, n as partsToText } from "./memoryArtifactStore-52Zn9npI-BMPYwvoy.js";
 
 //#region ../governance/dist/index.js
 const invalid = (message, details) => {
@@ -182,6 +182,49 @@ function candidateToCatalogEntry(candidate) {
 	};
 }
 /**
+* 把 agent 生成的技能草稿接进既有的候选管线（设计 02 §5）。
+*
+* 走的是与文档抽取、runtime-miss 完全相同的 `normalizeCandidate` → `CandidateStore.save`，
+* 因此候选恒为 `draft`，审批/发布链路一行都不用改；差别只有 `source: 'generated'`。
+*/
+function createCandidateSink(options) {
+	return { async submit(input) {
+		const { draft } = input;
+		const candidate = normalizeCandidate({
+			raw: {
+				name: draft.name,
+				description: draft.description,
+				files: [{
+					path: "SKILL.md",
+					content: draft.content
+				}, ...draft.files ?? []]
+			},
+			source: "generated",
+			...options.now ? { now: options.now } : {},
+			...options.createId ? { createId: options.createId } : {}
+		});
+		candidate.metadata = {
+			...candidate.metadata,
+			confirmedAt: input.confirmedAt,
+			...input.sessionId !== void 0 ? { sessionId: input.sessionId } : {}
+		};
+		await options.store.save(candidate);
+		await options.audit?.append({
+			type: "candidate.created",
+			target: candidate.id,
+			data: {
+				name: candidate.name,
+				source: candidate.source,
+				risk: candidate.risk,
+				userConfirmed: true,
+				confirmedAt: input.confirmedAt,
+				...input.sessionId !== void 0 ? { sessionId: input.sessionId } : {}
+			}
+		});
+		return { id: candidate.id };
+	} };
+}
+/**
 * 文本补全：优先走流式（慢速本地模型下非流式整响应缓冲会触发 fetch 头超时，
 * SSE 首包秒到不受此限）；无 stream 的客户端回退 complete。
 */
@@ -1046,4 +1089,4 @@ function createMissHook(deps) {
 }
 
 //#endregion
-export { AUDIT_PAGE_SIZE, AlwaysHumanApprovalPolicy, CANDIDATE_PAGE_SIZE, CandidateStore, CompositeApprovalPolicy, DependencyGraph, DocumentSkillExtractor, EvaluationRunner, FailureAnalyzer, FsAuditLog, LlmCandidateGenerator, RepairPlanner, SCORING_WEIGHTS, SKILL_VERSION_PAGE_SIZE, SimilarityDetector, SkillScorer, SkillStatePolicy, SkillVersionStore, candidateToCatalogEntry, completeText, createMissHook, jaccardSimilarity, normalizeCandidate, normalizeCandidateFiles, normalizeRisk, parseJsonObject, readDocument, sanitizeCandidateName, suggestFromFailedRun, validateCandidate };
+export { AUDIT_PAGE_SIZE, AlwaysHumanApprovalPolicy, CANDIDATE_PAGE_SIZE, CandidateStore, CompositeApprovalPolicy, DependencyGraph, DocumentSkillExtractor, EvaluationRunner, FailureAnalyzer, FsAuditLog, LlmCandidateGenerator, RepairPlanner, SCORING_WEIGHTS, SKILL_VERSION_PAGE_SIZE, SimilarityDetector, SkillScorer, SkillStatePolicy, SkillVersionStore, candidateToCatalogEntry, completeText, createCandidateSink, createMissHook, jaccardSimilarity, normalizeCandidate, normalizeCandidateFiles, normalizeRisk, parseJsonObject, readDocument, sanitizeCandidateName, suggestFromFailedRun, validateCandidate };

package/dist/{index-CHXxDccV.d.ts → index-BMocOEi0.d.ts}

@@ -1,11 +1,11 @@
-import { F as JsonSchema, _ as RenderBlock, b as UiSpecActionCapability, o as InteractionRequest, pt as UiSpecNode, r as ChartSpec, s as InteractionResponse, v as RenderResultRequest, w as UiSpecSnapshot, y as UiBridge } from "./types-7Wcg--Vh-1YlQ4jF9.js";
-import { x as ExternalToolSource } from "./index-DLfR2Y6I.js";
+import { I as JsonSchema, T as UiSpecSnapshot, b as UiBridge, c as InteractionResponse, mt as UiSpecNode, r as ChartSpec, s as InteractionRequest, v as RenderBlock, x as UiSpecActionCapability, y as RenderResultRequest } from "./types-4pg-qp_I-Gq63X8Oa.js";
+import { O as ExternalToolSource } from "./index-C-KFAZoF.js";
 import { z } from "zod";
 import { ComponentType, ReactNode } from "react";
 //#region ../ui/dist/index.d.ts
 //#region src/model/formModel.d.ts
 interface FormModel {
-  kind: 'ask' | 'confirm' | 'form' | 'select' | 'authorize';
+  kind: 'ask' | 'confirm' | 'form' | 'select' | 'authorize' | 'file-pick';
   title?: string;
   message?: string;
   controls: ControlModel[];
@@ -15,7 +15,7 @@ interface FormModel {
 interface ControlModel {
   name: string;
   label: string;
-  control: 'text' | 'number' | 'boolean' | 'select' | 'textarea';
+  control: 'text' | 'number' | 'boolean' | 'select' | 'textarea' | 'file';
   required?: boolean;
   description?: string;
   defaultValue?: unknown;
@@ -23,6 +23,18 @@ interface ControlModel {
     label: string;
     value: unknown;
   }>;
+  /** 传给 `input.accept` 的类型列表（仅 file 控件） */
+  accept?: readonly string[];
+  multiple?: boolean;
+  /**
+   * 建议值（FR-19.4）。与 `defaultValue` 严格分开：渲染器只能把它展示为建议，
+   * 用户主动采纳后才能进控件。
+   * @experimental
+   */
+  suggestion?: {
+    value: unknown;
+    reason?: string;
+  };
 }
 /** 提交值按请求类型归形（WebFormBridge 与框架组件库共享单一来源） */
 declare function shapeInteractionValue(model: FormModel, values: Record<string, unknown>): unknown;
@@ -42,6 +54,13 @@ interface CollectedValues {
  * - required 空值列入 missingRequired（由调用方阻止提交并标记）
  */
 declare function collectValues(controls: ControlModel[], container: ParentNode): CollectedValues;
+/**
+ * 采纳建议值（FR-5.9）：把 `control.suggestion` 写进已渲染的控件。
+ * 与 `collectValues` 共用同一套选择器与编码约定——两边分开实现的话，
+ * select 的 JSON 编码值迟早会对不上。
+ * @experimental
+ */
+declare function applySuggestion(control: ControlModel, container: ParentNode): void;
 //#endregion
 //#region src/markdown/miniMarkdown.d.ts
 /**
@@ -51,7 +70,10 @@ declare function collectValues(controls: ControlModel[], container: ParentNode):
 declare function renderMiniMarkdown(text: string, doc: Document): HTMLElement;
 //#endregion
 //#region src/chart/miniChart.d.ts
-/** 固定 8 色循环调色板 */
+/**
+ * 固定 8 色循环调色板。这是**数据编码**（区分序列），不是主题色；
+ * 图表的轴线与文字等“外壳”颜色走 currentColor，跟随宿主容器的主题。
+ */
 declare const CHART_PALETTE: readonly ["#4e79a7", "#f28e2b", "#e15759", "#76b7b2", "#59a14f", "#edc948", "#b07aa1", "#ff9da7"];
 /**
  * ChartSpec → SVG（bar 等宽柱 + 值标签；line 折线 + 点；pie 扇形 + 图例；空数据容错）
@@ -115,7 +137,7 @@ declare function renderRenderResult(request: RenderResultRequest, doc: Document)
 //#endregion
 //#region src/web/styles.d.ts
 /** 最小样式（BEM class，应用可整体覆写） */
-declare const WEBSKILL_STYLES_CSS = "\n.webskill-form { display: block; padding: 12px; border: 1px solid #d0d0d0; border-radius: 8px; font-family: system-ui, sans-serif; max-width: 420px; }\n.webskill-form__title { margin: 0 0 8px; font-size: 15px; font-weight: 600; }\n.webskill-form__message { margin: 0 0 10px; font-size: 14px; }\n.webskill-form__control { margin-bottom: 10px; display: flex; flex-direction: column; gap: 4px; }\n.webskill-form__control--invalid .webskill-form__input { border-color: #d33; }\n.webskill-form__label { font-size: 13px; font-weight: 500; }\n.webskill-form__label-required::after { content: ' *'; color: #d33; }\n.webskill-form__description { font-size: 12px; color: #666; }\n.webskill-form__error { font-size: 12px; color: #d33; display: none; }\n.webskill-form__control--invalid .webskill-form__error { display: block; }\n.webskill-form__input { padding: 6px 8px; border: 1px solid #bbb; border-radius: 4px; font-size: 14px; font-family: inherit; }\n.webskill-form__actions { display: flex; gap: 8px; margin-top: 12px; }\n.webskill-form__button { padding: 6px 14px; border-radius: 4px; border: 1px solid #bbb; background: #fff; cursor: pointer; font-size: 14px; }\n.webskill-form__button--primary { background: #2563eb; border-color: #2563eb; color: #fff; }\n.webskill-form__button--ghost { background: transparent; }\n.webskill-result { font-family: system-ui, sans-serif; font-size: 14px; }\n.webskill-result__summary { font-size: 12px; color: #666; margin-bottom: 6px; }\n.webskill-result__json { background: #f5f5f5; padding: 8px; border-radius: 4px; overflow-x: auto; }\n.webskill-result__file { padding: 4px 0; font-size: 13px; }\n.webskill-md pre { background: #f5f5f5; padding: 8px; border-radius: 4px; overflow-x: auto; }\n.webskill-md h1, .webskill-md h2, .webskill-md h3 { margin: 8px 0 4px; }\n.webskill-md p { margin: 4px 0; }\n.webskill-md ul { margin: 4px 0; padding-left: 20px; }\n";
+declare const WEBSKILL_STYLES_CSS = "\n.webskill-form { display: block; padding: 12px; border: 1px solid #d0d0d0; border-radius: 8px; font-family: system-ui, sans-serif; max-width: 420px; }\n.webskill-form__title { margin: 0 0 8px; font-size: 15px; font-weight: 600; }\n.webskill-form__message { margin: 0 0 10px; font-size: 14px; }\n.webskill-form__control { margin-bottom: 10px; display: flex; flex-direction: column; gap: 4px; }\n.webskill-form__control--invalid .webskill-form__input { border-color: #d33; }\n.webskill-form__label { font-size: 13px; font-weight: 500; }\n.webskill-form__label-required::after { content: ' *'; color: #d33; }\n.webskill-form__description { font-size: 12px; color: #666; }\n.webskill-form__error { font-size: 12px; color: #d33; display: none; }\n.webskill-form__control--invalid .webskill-form__error { display: block; }\n.webskill-form__input { padding: 6px 8px; border: 1px solid #bbb; border-radius: 4px; font-size: 14px; font-family: inherit; }\n.webskill-form__suggestion { display: flex; align-items: center; gap: 6px; font-size: 12px; color: #666; }\n.webskill-form__suggestion-use { padding: 1px 8px; border-radius: 4px; border: 1px solid #bbb; background: #fff; cursor: pointer; font-size: 12px; }\n.webskill-form__actions { display: flex; gap: 8px; margin-top: 12px; }\n.webskill-form__button { padding: 6px 14px; border-radius: 4px; border: 1px solid #bbb; background: #fff; cursor: pointer; font-size: 14px; }\n.webskill-form__button--primary { background: #2563eb; border-color: #2563eb; color: #fff; }\n.webskill-form__button--ghost { background: transparent; }\n.webskill-result { font-family: system-ui, sans-serif; font-size: 14px; }\n.webskill-result__summary { font-size: 12px; color: #666; margin-bottom: 6px; }\n.webskill-result__json { background: #f5f5f5; padding: 8px; border-radius: 4px; overflow-x: auto; }\n.webskill-result__file { padding: 4px 0; font-size: 13px; }\n.webskill-md pre { background: #f5f5f5; padding: 8px; border-radius: 4px; overflow-x: auto; }\n.webskill-md h1, .webskill-md h2, .webskill-md h3 { margin: 8px 0 4px; }\n.webskill-md p { margin: 4px 0; }\n.webskill-md ul { margin: 4px 0; padding-left: 20px; }\n";
 /** 每个 document 只注入一次 */
 declare function ensureStyles(doc: Document): void;
 //#endregion
@@ -130,6 +152,8 @@ interface UiComponentDef {
   /** 允许的子节点组件名；省略表示叶子节点 */
   children?: readonly string[] | 'any';
   group: 'layout' | 'content' | 'data' | 'input' | 'feedback';
+  /** 同一容器（声明了 children 的父节点）下至多出现一个；超出时校验不通过 */
+  singletonPerContainer?: boolean;
   /** 给模型的额外约束 */
   constraints?: readonly string[];
   /** 最小示例（进 prompt，显著提升生成质量） */
@@ -192,9 +216,76 @@ declare const uiCatalog: UiCatalog;
 /** prompt / 文档里引用的分组顺序（Console 展示同序） */
 declare const UI_CATALOG_GROUPS: {
   readonly content: readonly ["Stack", "Card", "Separator", "Heading", "Text", "Markdown", "Badge"];
-  readonly data: readonly ["Metric", "Table", "Chart", "FileLink"];
+  readonly data: readonly ["Metric", "Table", "Chart", "Timeline", "FileLink"];
   readonly input: readonly ["Form", "Field", "Button"];
 };
+/**
+ * catalog 系统提示的体积上限（UTF-8 字节，FR-6.6）。
+ * 描述每次请求都要重发，所以上限必须是可判定的数字而不是「尽量精简」。
+ * 要改这个数字，先想清楚是否值得让每次请求都多付这些 token。
+ */
+declare const UI_CATALOG_PROMPT_BUDGET_BYTES = 20480;
+//#endregion
+//#region src/catalog/formScopes.d.ts
+/** 声明树里一个 `Form` 的提交作用域。@experimental */
+interface UiFormScope {
+  /** 提交动作所属的表单容器：节点 id 优先，否则按出现序生成 */
+  scopeId: string;
+  /** 该表单的提交 action id */
+  submitActionId: string;
+  /** 该表单的取消 action id（仅在声明了 cancelLabel 时会进能力表） */
+  cancelActionId: string;
+  /** 该表单子树内的字段名，按声明序 */
+  fieldNames: readonly string[];
+  form: UiSpecNode;
+}
+/**
+ * 按出现序列出声明树里的每个 `Form`。
+ *
+ * 单表单时 action id 保持 `submit` / `cancel`，回传形状与容器级放宽前逐字节一致——
+ * 向后兼容是 FR-6.3 的硬约束，不能让既有单表单卡片跟着改。
+ * 多表单时每个表单拿到独立的 action id 与 `scopeId`，渲染层据此只收集本表单子树内的字段。
+ */
+declare function collectFormScopes(spec: UiSpecNode): UiFormScope[];
+/**
+ * 多表单时字段值在渲染层的存储键。
+ *
+ * 跨表单重名过去不可能发生，容器级放宽后它变成合法输入：两个表单各有一个 `email`，
+ * 共用一张扁平表就是后写的覆盖先写的，用户在 A 里输入会串到 B。
+ * 因此多表单时按作用域限定键；单表单不加前缀，存储与草稿形状保持不变。
+ */
+declare function qualifyFieldName(name: string, scopeId?: string): string;
+/**
+ * 提交时回传的字段值。
+ *
+ * 不给 `scope` → 整张 surface 的扁平值，与容器级放宽前完全一致（FR-6.3 第 3 条）。
+ * 给了 `scope` → 只取该表单子树内的字段，键回落成裸字段名，
+ * 因此接收端看到的载荷形状与单表单时相同。
+ */
+declare function collectScopedValues(values: Readonly<Record<string, unknown>>, scope?: Pick<UiFormScope, 'scopeId' | 'fieldNames'>): Record<string, unknown>;
+//#endregion
+//#region src/catalog/presets.d.ts
+/** 场景预设名（FR-6.4） */
+type UiPresetName = 'charts' | 'cards' | 'dashboards' | 'slides' | 'reports';
+/**
+ * 一类场景的排版模板。产出的是 catalog 节点树，不是标记语言——
+ * 技能可以引用预设，但不能自带 HTML（需求 8 的方案 A）。
+ * @experimental
+ */
+interface UiPreset {
+  name: UiPresetName;
+  /** 一行说明，进工具入参枚举；这行是唯一无条件计入请求上下文的部分 */
+  summary: string;
+  /** 详细排版指引，只在模型显式索取该预设时才下发（FR-6.5） */
+  guidance: string;
+  /** 可运行示例：必须通过 `uiCatalog.validate`（AC-6.6） */
+  example: UiSpecNode;
+}
+/** 五类场景预设（FR-6.4）。@experimental */
+declare const UI_PRESETS: readonly UiPreset[];
+declare const UI_PRESET_NAMES: readonly UiPresetName[];
+/** Returns undefined for names outside the catalog presets. @experimental */
+declare function uiPreset(name: string): UiPreset | undefined;
 //#endregion
 //#region src/catalog/toJsonRenderSpec.d.ts
 /** json-render 的扁平 spec：`elements` 以 key 索引，`children` 只存 key */
@@ -232,11 +323,14 @@ declare function interactionToUiSpec(request: InteractionRequest, labels?: Inter
 //#endregion
 //#region src/catalog/uiCatalogToolSource.d.ts
 declare const RENDER_UI_TOOL = "render_ui";
+declare const DESCRIBE_UI_PRESET_TOOL = "describe_ui_preset";
 interface UiCatalogToolSourceOptions {
   /** 默认使用 v1 catalog */
   catalog?: UiCatalog;
   /** surface id 生成（默认时间戳 + 随机后缀） */
   newSurfaceId?: () => string;
+  /** 向模型开放的场景预设；缺省全部开放，空数组等于关闭预设。不认识的名字直接忽略 */
+  presets?: readonly string[];
 }
 /** 节点树声明的 action 能力表（renderer 据此生成按钮，runtime 据此签发 nonce）。@experimental */
 declare function collectSpecActions(spec: UiSpecNode): UiSpecActionCapability[];
@@ -289,10 +383,12 @@ interface UiSurfaceActionDispatch {
   actionId: string;
   intent: UiSpecActionCapability['intent'];
   nonce?: string;
+  /** 提交动作所属的表单容器；单表单场景可省略 */
+  scopeId?: string;
   value?: Record<string, unknown>;
   cancelled?: boolean;
 }
-declare function toUiSurfaceActionDispatch(snapshot: UiSpecSnapshot, action: UiSpecActionCapability, value?: Record<string, unknown>): UiSurfaceActionDispatch;
+declare function toUiSurfaceActionDispatch(snapshot: UiSpecSnapshot, action: UiSpecActionCapability, value?: Record<string, unknown>, scopeId?: string): UiSurfaceActionDispatch;
 /** Returns undefined for malformed or non-WebSkill renderer events. @experimental */
 declare function fromUiSurfaceActionDispatch(value: unknown): UiSurfaceActionDispatch | undefined;
 //#endregion
@@ -316,7 +412,7 @@ interface A2uiMessage {
 /** Decodes a nonce-bound action emitted by a WebSkill A2UI extension host. @experimental */
 declare function fromA2uiSurfaceAction(event: unknown): UiSurfaceActionDispatch | undefined;
 /** Builds the A2UI event payload an extension host sends after a user action. @experimental */
-declare function toA2uiSurfaceAction(snapshot: UiSpecSnapshot, action: UiSpecActionCapability, value?: Record<string, unknown>): {
+declare function toA2uiSurfaceAction(snapshot: UiSpecSnapshot, action: UiSpecActionCapability, value?: Record<string, unknown>, scopeId?: string): {
   name: string;
   context: UiSurfaceActionDispatch;
 };
@@ -512,4 +608,4 @@ interface LoadedOpenUiPeers {
  */
 declare function loadOpenUiPeers(): Promise<LoadedOpenUiPeers>;
 //#endregion
-export { fromA2uiSpecAction as $, UiCatalogToolSourceOptions as A, WEBSKILL_SURFACE_ACTION as B, OpenUiRuntime as C, UiCatalog as D, UiActionDef as E, VERCEL_INTERACTION_TOOL_NAME as F, buildA2uiCatalogDefinition as G, ZodRuntime as H, VercelToolInvocation as I, collectSpecActions as J, chartSpecFromProps as K, VercelUiBridge as L, UiSpecIssue as M, UiSpecValidation as N, UiCatalogInput as O, UiSurfaceActionDispatch as P, ensureStyles as Q, WEBSKILL_A2UI_CATALOG_ID as R, OpenUiRendererProps as S, UI_CATALOG_GROUPS as T, a2uiComponentSchema as U, WebFormBridge as V, a2uiComponentShapes as W, createUiCatalogToolSource as X, collectValues as Y, defineUiCatalog as Z, EchartHandle as _, toUiSurfaceActionDispatch as _t, A2UI_SURFACE_ACTION as a, loadOpenUiPeers as at, JsonRenderSpec as b, A2uiCatalogDefinition as c, renderBlocks as ct, A2uiMessage as d, renderRenderResult as dt, fromA2uiSurfaceAction as et, A2uiSpecActionEvent as f, shapeInteractionValue as ft, ControlModel as g, toOpenUiSpecLang as gt, CollectedValues as h, toJsonRenderSpec as ht, A2UI_SPEC_FORM_PATH as i, interactionToUiSpec as it, UiComponentDef as j, UiCatalogPromptOptions as k, A2uiCatalogHandle as l, renderMiniChart as lt, CHART_PALETTE as m, toA2uiSurfaceAction as mt, A2UI_COMMON_TYPES as n, fromVercelToolResult as nt, A2UI_VERSION as o, loadWebSkillLitCatalog as ot, A2uiSpecMessageOptions as p, toA2uiSpecMessages as pt, chartToTable as q, A2UI_SPEC_ACTION as r, interactionToFormModel as rt, A2uiCatalogComponent as s, mountEchart as st, A2UI_BASIC_CATALOG_ID as t, fromUiSurfaceActionDispatch as tt, A2uiComponentShape as u, renderMiniMarkdown as ut, FormModel as v, toVercelToolInvocation as vt, RENDER_UI_TOOL as w, LoadedOpenUiPeers as x, InteractionSpecLabels as y, uiCatalog as yt, WEBSKILL_STYLES_CSS as z };
+export { buildA2uiCatalogDefinition as $, UiActionDef as A, uiCatalog as At, UiSpecValidation as B, OpenUiRendererProps as C, shapeInteractionValue as Ct, UI_CATALOG_PROMPT_BUDGET_BYTES as D, toOpenUiSpecLang as Dt, UI_CATALOG_GROUPS as E, toJsonRenderSpec as Et, UiComponentDef as F, WEBSKILL_A2UI_CATALOG_ID as G, VERCEL_INTERACTION_TOOL_NAME as H, UiFormScope as I, WebFormBridge as J, WEBSKILL_STYLES_CSS as K, UiPreset as L, UiCatalogInput as M, UiCatalogPromptOptions as N, UI_PRESETS as O, toUiSurfaceActionDispatch as Ot, UiCatalogToolSourceOptions as P, applySuggestion as Q, UiPresetName as R, LoadedOpenUiPeers as S, renderRenderResult as St, RENDER_UI_TOOL as T, toA2uiSurfaceAction as Tt, VercelToolInvocation as U, UiSurfaceActionDispatch as V, VercelUiBridge as W, a2uiComponentSchema as X, ZodRuntime as Y, a2uiComponentShapes as Z, DESCRIBE_UI_PRESET_TOOL as _, mountEchart as _t, A2UI_SURFACE_ACTION as a, collectValues as at, InteractionSpecLabels as b, renderMiniChart as bt, A2uiCatalogDefinition as c, ensureStyles as ct, A2uiMessage as d, fromUiSurfaceActionDispatch as dt, chartSpecFromProps as et, A2uiSpecActionEvent as f, fromVercelToolResult as ft, ControlModel as g, loadWebSkillLitCatalog as gt, CollectedValues as h, loadOpenUiPeers as ht, A2UI_SPEC_FORM_PATH as i, collectSpecActions as it, UiCatalog as j, uiPreset as jt, UI_PRESET_NAMES as k, toVercelToolInvocation as kt, A2uiCatalogHandle as l, fromA2uiSpecAction as lt, CHART_PALETTE as m, interactionToUiSpec as mt, A2UI_COMMON_TYPES as n, collectFormScopes as nt, A2UI_VERSION as o, createUiCatalogToolSource as ot, A2uiSpecMessageOptions as p, interactionToFormModel as pt, WEBSKILL_SURFACE_ACTION as q, A2UI_SPEC_ACTION as r, collectScopedValues as rt, A2uiCatalogComponent as s, defineUiCatalog as st, A2UI_BASIC_CATALOG_ID as t, chartToTable as tt, A2uiComponentShape as u, fromA2uiSurfaceAction as ut, EchartHandle as v, qualifyFieldName as vt, OpenUiRuntime as w, toA2uiSpecMessages as wt, JsonRenderSpec as x, renderMiniMarkdown as xt, FormModel as y, renderBlocks as yt, UiSpecIssue as z };