@sendevia/pi-ask-author 1.0.6 → 1.1.1

package/dist/sanitize.d.ts

@@ -5,14 +5,29 @@
  * 核心架构特性：
  * - 容错范围：JSON 串包裹 / `raw` 包装键 / 字段别名 / 纯字符串选项 / 空选项兜底
  * - 白名单收敛：产物仅含 `RawParams` 声明字段（丢弃未知键），保障宿主 Schema 校验通过
+ * - 推演载荷清洗：`sanitizeExpansionPayload` 丢弃引用未知题目的选项追加、重复标签、与既有 ID 冲突的新题目与无选项题目
  * - 防御纵深：本层做类型收敛 / 别名映射 / 结构规整 / 区间兜底，模型层再幂等兜底一次
  *
- * 依赖方向：sanitize.ts → format.ts / texts.ts / schema.ts（类型）；仅由 index.ts 装配
+ * 依赖方向：sanitize.ts → format.ts / layout.ts / texts.ts / schema.ts（类型）；被 index / expansion / tool-card 消费
  */
-import type { RawParams } from "./schema.js";
+import type { ExpansionPayload, RawParams } from "./schema.js";
 /**
  * 入参防御性清洗（`prepareArguments` 钩子）；容错面见文件头，各字段先收敛为本地强类型 `const` 再组装为显式白名单产物
  * @param args - 工具调用原始入参（不可信边界）
  * @returns 仅含 Schema 声明字段的 `RawParams` 白名单对象；输入完全不可辨识时仅返回兜底 `formTitle`
  */
 export declare function sanitizeAskAuthorArgs(args: unknown): RawParams;
+/** 推演载荷的归集上下文：表单当前已声明的题目 ID 与各题已有选项标签 */
+export interface ExpansionContext {
+    /** 已声明的题目 ID（按题目顺序） */
+    readonly questionIds: readonly string[];
+    /** 题目 ID → 已有选项标签 */
+    readonly optionLabels: ReadonlyMap<string, readonly string[]>;
+}
+/**
+ * 规整推演模型的回复载荷（不可信边界）：丢弃引用未知题目的选项追加、与既有标签重复的选项以及与既有题目 ID 冲突的新题目
+ * @param value - 已解析的回复对象（非对象时视为无新增）
+ * @param context - 表单当前已声明的题目与选项标签
+ * @returns 仅含合法追加项的推演载荷；全部条目被过滤时返回空载荷（表单停止增长）
+ */
+export declare function sanitizeExpansionPayload(value: unknown, context: ExpansionContext): ExpansionPayload;

package/dist/schema.d.ts

@@ -6,12 +6,22 @@
  * - 字段名称、可选性与区间约束（`minItems` / `maxItems` / `minimum`）仅在 TypeBox 定义一次，运行时类型经 `Static<typeof>` 派生
  * - 默认值不写入 Schema：题目内字段由 `sanitize.ts` 规整时填入（`multiSelect`→false、`allowCustom`→true），模型层再按同一语义兜底
  * - LLM 端字段描述保持单句浓缩英文（取自 `TEXTS.schema`）
+ * - 推演载荷（`ExpansionPayload` / `OptionAddition`）的接口类型也在此声明，供 sanitize / model / expansion 共用
  *
- * 依赖方向：schema.ts → typebox / texts.ts（上限常量与字段描述）；被 sanitize / model / index 消费
+ * 依赖方向：schema.ts → typebox / layout.ts / texts.ts（上限常量与字段描述）；被 sanitize / model / expansion / index 消费
  */
 import { Type, type Static } from "typebox";
+/** 显示条件参数 Schema：引用更早题目的作答状态，决定本题或本选项是否出现 */
+export declare const ShowIfConditionSchema: Type.TObject<{
+    /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+    questionId: Type.TString;
+    /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+    option: Type.TOptional<Type.TString>;
+    /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+    answered: Type.TOptional<Type.TBoolean>;
+}>;
 /** 单个候选选项的参数 Schema */
-declare const OptionSchema: Type.TObject<{
+export declare const OptionSchema: Type.TObject<{
     /** 选项简短标题/行动标签（必须填写；缺失时经 `sanitize.ts` → `model.ts` 两级兜底为自动占位标签） */
     label: Type.TString;
     /** 情节推演后果或设定阐述（可选） */
@@ -20,13 +30,31 @@ declare const OptionSchema: Type.TObject<{
     preview: Type.TOptional<Type.TString>;
     /** 该选项专属补充说明的占位引导文案（可选） */
     customPlaceholder: Type.TOptional<Type.TString>;
+    /** 该选项的显示条件（可选；不成立时不展示，选中态同样不计入答卷） */
+    showIf: Type.TOptional<Type.TUnion<[Type.TObject<{
+        /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+        questionId: Type.TString;
+        /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+        option: Type.TOptional<Type.TString>;
+        /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+        answered: Type.TOptional<Type.TBoolean>;
+    }>, Type.TArray<Type.TObject<{
+        /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+        questionId: Type.TString;
+        /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+        option: Type.TOptional<Type.TString>;
+        /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+        answered: Type.TOptional<Type.TBoolean>;
+    }>>]>>;
 }>;
 /** 单个问题的参数 Schema（批量问卷与平铺模式共用） */
-declare const QuestionSchema: Type.TObject<{
+export declare const QuestionSchema: Type.TObject<{
     /** 题目唯一标识符（可选；缺省由模型层按顺序生成，跨题重复由模型层去重） */
     id: Type.TOptional<Type.TString>;
     /** 题目标题（必须填写；缺失时两级兜底为自动占位标题） */
     title: Type.TString;
+    /** Tab 栏短标签（可选；缺省时 Tab 栏显示题号） */
+    tabLabel: Type.TOptional<Type.TString>;
     /** 题目背景与语境（可选） */
     description: Type.TOptional<Type.TString>;
     /** 是否允许多选（可选；默认 false，即单选） */
@@ -47,11 +75,58 @@ declare const QuestionSchema: Type.TObject<{
         preview: Type.TOptional<Type.TString>;
         /** 该选项专属补充说明的占位引导文案（可选） */
         customPlaceholder: Type.TOptional<Type.TString>;
+        /** 该选项的显示条件（可选；不成立时不展示，选中态同样不计入答卷） */
+        showIf: Type.TOptional<Type.TUnion<[Type.TObject<{
+            /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+            questionId: Type.TString;
+            /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+            option: Type.TOptional<Type.TString>;
+            /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+            answered: Type.TOptional<Type.TBoolean>;
+        }>, Type.TArray<Type.TObject<{
+            /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+            questionId: Type.TString;
+            /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+            option: Type.TOptional<Type.TString>;
+            /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+            answered: Type.TOptional<Type.TBoolean>;
+        }>>]>>;
     }>>;
     /** 是否允许自由补充说明（可选；默认 true） */
     allowCustom: Type.TOptional<Type.TBoolean>;
     /** 题目整体补充说明的占位引导词（可选） */
     customPlaceholder: Type.TOptional<Type.TString>;
+    /** 该题目的显示条件（可选；不成立时不展示，也不计入答卷） */
+    showIf: Type.TOptional<Type.TUnion<[Type.TObject<{
+        /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+        questionId: Type.TString;
+        /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+        option: Type.TOptional<Type.TString>;
+        /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+        answered: Type.TOptional<Type.TBoolean>;
+    }>, Type.TArray<Type.TObject<{
+        /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+        questionId: Type.TString;
+        /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+        option: Type.TOptional<Type.TString>;
+        /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+        answered: Type.TOptional<Type.TBoolean>;
+    }>>]>>;
+}>;
+/** 推演题目的插入位置预设：跟随触发题目 / 排到队尾 / 指定题目之后 */
+export declare const InsertPositionSchema: Type.TUnion<[Type.TLiteral<"follow">, Type.TLiteral<"tail">, Type.TObject<{
+    after: Type.TString;
+}>]>;
+/** 实时推演参数 Schema：作者确认答案后由同一模型追加题目与选项 */
+export declare const ExpansionSchema: Type.TObject<{
+    /** 推演后的题目总量上限（含已声明的题目） */
+    maxQuestions: Type.TOptional<Type.TInteger>;
+    /** 长期生效的推演方向指示 */
+    guidance: Type.TOptional<Type.TString>;
+    /** 推演题目的插入位置（缺省为跟随触发题目） */
+    insert: Type.TOptional<Type.TUnion<[Type.TLiteral<"follow">, Type.TLiteral<"tail">, Type.TObject<{
+        after: Type.TString;
+    }>]>>;
 }>;
 /** `ask_author` 工具完整参数 Schema（必须填写 `formTitle`；批量问卷传递 `questions`，单题平铺传递顶层 `question` + `options`） */
 export declare const AskAuthorParams: Type.TObject<{
@@ -59,12 +134,25 @@ export declare const AskAuthorParams: Type.TObject<{
     formTitle: Type.TString;
     /** 问卷全局背景或前述情境（可选；平铺单题模式下同时充当该题描述） */
     description: Type.TOptional<Type.TString>;
+    /** 实时推演开关（可选；开启后作者每次确认答案都追加后续题目与选项） */
+    expansion: Type.TOptional<Type.TObject<{
+        /** 推演后的题目总量上限（含已声明的题目） */
+        maxQuestions: Type.TOptional<Type.TInteger>;
+        /** 长期生效的推演方向指示 */
+        guidance: Type.TOptional<Type.TString>;
+        /** 推演题目的插入位置（缺省为跟随触发题目） */
+        insert: Type.TOptional<Type.TUnion<[Type.TLiteral<"follow">, Type.TLiteral<"tail">, Type.TObject<{
+            after: Type.TString;
+        }>]>>;
+    }>>;
     /** 关联多题批量问卷列表（可选；批量模式使用，上限 `MAX_QUESTIONS` 题） */
     questions: Type.TOptional<Type.TArray<Type.TObject<{
         /** 题目唯一标识符（可选；缺省由模型层按顺序生成，跨题重复由模型层去重） */
         id: Type.TOptional<Type.TString>;
         /** 题目标题（必须填写；缺失时两级兜底为自动占位标题） */
         title: Type.TString;
+        /** Tab 栏短标签（可选；缺省时 Tab 栏显示题号） */
+        tabLabel: Type.TOptional<Type.TString>;
         /** 题目背景与语境（可选） */
         description: Type.TOptional<Type.TString>;
         /** 是否允许多选（可选；默认 false，即单选） */
@@ -85,11 +173,43 @@ export declare const AskAuthorParams: Type.TObject<{
             preview: Type.TOptional<Type.TString>;
             /** 该选项专属补充说明的占位引导文案（可选） */
             customPlaceholder: Type.TOptional<Type.TString>;
+            /** 该选项的显示条件（可选；不成立时不展示，选中态同样不计入答卷） */
+            showIf: Type.TOptional<Type.TUnion<[Type.TObject<{
+                /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+                questionId: Type.TString;
+                /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+                option: Type.TOptional<Type.TString>;
+                /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+                answered: Type.TOptional<Type.TBoolean>;
+            }>, Type.TArray<Type.TObject<{
+                /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+                questionId: Type.TString;
+                /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+                option: Type.TOptional<Type.TString>;
+                /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+                answered: Type.TOptional<Type.TBoolean>;
+            }>>]>>;
         }>>;
         /** 是否允许自由补充说明（可选；默认 true） */
         allowCustom: Type.TOptional<Type.TBoolean>;
         /** 题目整体补充说明的占位引导词（可选） */
         customPlaceholder: Type.TOptional<Type.TString>;
+        /** 该题目的显示条件（可选；不成立时不展示，也不计入答卷） */
+        showIf: Type.TOptional<Type.TUnion<[Type.TObject<{
+            /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+            questionId: Type.TString;
+            /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+            option: Type.TOptional<Type.TString>;
+            /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+            answered: Type.TOptional<Type.TBoolean>;
+        }>, Type.TArray<Type.TObject<{
+            /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+            questionId: Type.TString;
+            /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+            option: Type.TOptional<Type.TString>;
+            /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+            answered: Type.TOptional<Type.TBoolean>;
+        }>>]>>;
     }>>>;
     /** 单题平铺模式题目标题（可选；仅在携带非空 `options` 时参与选题，缺省回退 `TEXTS.fallbacks.defaultQuestionTitle`） */
     question: Type.TOptional<Type.TString>;
@@ -111,6 +231,22 @@ export declare const AskAuthorParams: Type.TObject<{
         preview: Type.TOptional<Type.TString>;
         /** 该选项专属补充说明的占位引导文案（可选） */
         customPlaceholder: Type.TOptional<Type.TString>;
+        /** 该选项的显示条件（可选；不成立时不展示，选中态同样不计入答卷） */
+        showIf: Type.TOptional<Type.TUnion<[Type.TObject<{
+            /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+            questionId: Type.TString;
+            /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+            option: Type.TOptional<Type.TString>;
+            /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+            answered: Type.TOptional<Type.TBoolean>;
+        }>, Type.TArray<Type.TObject<{
+            /** 被引用的题目 ID（必须为本次表单中更早出现的题目） */
+            questionId: Type.TString;
+            /** 匹配的选项标签（可选；给出时条件等价于「该选项被选中」） */
+            option: Type.TOptional<Type.TString>;
+            /** 作答存在性（可选；缺省等价于 true，给出 `option` 时忽略） */
+            answered: Type.TOptional<Type.TBoolean>;
+        }>>]>>;
     }>>>;
     /** 单题平铺模式是否允许自由补充说明（可选；默认 true） */
     allowCustom: Type.TOptional<Type.TBoolean>;
@@ -126,4 +262,25 @@ export type RawParams = Static<typeof AskAuthorParams>;
 export type QuestionOption = Static<typeof OptionSchema>;
 /** 单个问题的运行时类型（由 `QuestionSchema` 经 `Static<typeof>` 派生，批量与平铺共用） */
 export type QuestionInput = Static<typeof QuestionSchema>;
-export {};
+/** 单个显示条件的运行时类型（由 `ShowIfConditionSchema` 经 `Static<typeof>` 派生） */
+export type VisibilityConditionInput = Static<typeof ShowIfConditionSchema>;
+/** `showIf` 字段的运行时类型：单个条件或条件数组 */
+export type ShowIfInput = VisibilityConditionInput | VisibilityConditionInput[];
+/** 实时推演配置的运行时类型（由 `ExpansionSchema` 经 `Static<>` 派生） */
+export type ExpansionConfig = Static<typeof ExpansionSchema>;
+/** 推演题目插入位置的运行时类型：预设字符串或指定题目之后的锚点 */
+export type InsertPosition = Static<typeof InsertPositionSchema>;
+/** 推演向既有题目追加的一组选项 */
+export interface OptionAddition {
+    /** 目标题目的 ID（必须是表单中已存在的题目） */
+    readonly questionId: string;
+    /** 待追加的选项（标签与既有选项不重复） */
+    readonly options: QuestionOption[];
+}
+/** 一次推演的产出：待追加的新题目与向既有题目追加的选项 */
+export interface ExpansionPayload {
+    /** 追加到题目列表末尾的新题目 */
+    readonly questions: QuestionInput[];
+    /** 向既有题目追加的选项 */
+    readonly optionAdditions: OptionAddition[];
+}