@sendevia/pi-ask-author 1.1.0 → 1.1.1

package/README.md

@@ -24,6 +24,7 @@
   - **单题平铺模式**：快速发起单点决策（如重要剧情分歧、结局走向）。
   - **多题批量问卷模式**：支持在单次弹窗内汇集多个关联决策。
   - **自适应题目与选项**：支持引用更早题目的选项或作答存在性，按作者的实际选择逐步展开分支。
+  - **实时推演**：只声明最关键的一题；作者每次确认答案后，同一模型即时生成后续题目与新选项。
 - **多语言支持**
 - **高性能与极简依赖**
   - **遵守开发规范**：严格遵守 Pi 官方扩展生态规范，不引入其他第三方依赖。

package/dist/component.d.ts

@@ -9,16 +9,27 @@
  * - 逐题独立光标记忆与 `1~9` 跳转题目；内置编辑器透传 Focusable 以定位 IME 候选框
  * - 无输入框页面把输入法全角字符收敛为半角，`【`/`】` 与全角字母数字一样命中快捷键
  * - 自适应导航：Tab 循环 / 数字跳转 / 确认推进一律沿可见题目序列行走，被条件隐藏的题目自动跳过
+ * - 实时推演：作者确认答案后发起（答案未变则复用既有结果，变了先撤回再请求），结果写入同一表单；在途期间当前页的 Tab 标题与整页内容换成占位并暂停一切作答输入，就绪后恢复；只采纳最新请求，中止与卸载作废在途请求
  * - Esc / Ctrl+C 双通道取消（输入模式二次确认）；定时器、Abort 监听与缓存池全量回收
  *
  * 渲染纯度不变量：`render()` 及其可达被调函数禁止写入语义状态（`currentTab`、光标与各 `*ScrollOffset`、`inputMode`、`editTarget`、`editorEscArmed`、`statusMessage`、`isFinished`）；滚动位移归一化一律归属输入路径
  * 可写入透明备忘：`cached*`、`tabCache`、`menuCache`、`previewViewportObservation` 与视图层内部缓存均为「渲染输入的纯函数」缓存
  *
- * 依赖方向：component.ts → theme / texts / format / model / view-editor / view-question / view-rows / view-summary；本组件只做按键路由与整屏缓存编排
+ * 依赖方向：component.ts → theme / texts / format / model / expansion / view-editor / view-question / view-rows / view-summary；本组件只做按键路由、推演编排与整屏缓存编排
  */
 import { type Component, type Focusable, type TUI } from "@earendil-works/pi-tui";
+import type { ExpansionRunner } from "./expansion.js";
 import { AskAuthorFormModel, type AskAuthorResult } from "./model.js";
 import type { Theme } from "./theme.js";
+/**
+ * 实时推演服务（由入口层装配模型调用；缺省表示本表单不推演）
+ */
+export interface ExpansionService {
+    /** 执行一次推演（取消经 `signal` 级联） */
+    readonly run: ExpansionRunner;
+    /** 调用方给出的长期推演方向指示（可选） */
+    readonly guidance?: string;
+}
 /**
  * `ask_author` 交互式 TUI 组件（问卷作答与答卷总览）
  * 状态机：作答突变经 `AskAuthorFormModel`，`revision` 驱动多级缓存失效；`render()` 只写入透明备忘 / 观察缓存，绝不写回滚动位移等语义状态；`dispose()` 幂等且只设置 `disposed`，`finish()` 以 `isFinished` 保证 `done` 至多投递一次
@@ -85,6 +96,14 @@ export declare class AskAuthorComponent implements Component, Focusable {
     private editTarget?;
     /** 内置补充说明编辑器实例 */
     private readonly editor;
+    /** 实时推演服务（缺省表示本表单不推演） */
+    private readonly expansion?;
+    /** 推演请求序号：只有最新序号的结果会被采纳 */
+    private expansionTicket;
+    /** 进行中的推演请求中止器 */
+    private expansionAbort?;
+    /** 是否有推演请求正在进行（在途期间作答页整体换成占位页，一切作答输入暂停） */
+    private expansionPending;
     /** 题目作答页视图构建器（持有预览与左栏缓存） */
     private readonly questionView;
     /** 答卷总览页视图构建器（持有内容行缓存） */
@@ -95,8 +114,9 @@ export declare class AskAuthorComponent implements Component, Focusable {
      * @param theme - 主题
      * @param model - 问卷模型
      * @param done - 结果回调
+     * @param expansion - 实时推演服务（可选；缺省时表单保持静态）
      */
-    constructor(tui: TUI, theme: Theme, model: AskAuthorFormModel, done: (result: AskAuthorResult) => void);
+    constructor(tui: TUI, theme: Theme, model: AskAuthorFormModel, done: (result: AskAuthorResult) => void, expansion?: ExpansionService);
     /**
      * 绑定中止信号（幂等，至多绑定一次）
      * @param signal - 外层 AbortSignal；缺省 / 已绑定 / 已卸载时直接返回
@@ -127,6 +147,11 @@ export declare class AskAuthorComponent implements Component, Focusable {
      * @param msg - 提示文案（取自 `TEXTS.status`，不做控制字符清洗）
      */
     private setStatus;
+    /**
+     * 底部状态行文案
+     * @returns 待展示的状态行文本；无提示时为 null
+     */
+    private get statusLine();
     /**
      * 终结作答流程并触发 `done`（至多投递一次）
      * `isFinished` 单守卫防止重复投递；不以 `disposed` 阻断（资源已回收但 `done` 未投递时仍须结算），跳转入 {@link dispose}
@@ -186,6 +211,33 @@ export declare class AskAuthorComponent implements Component, Focusable {
      * @param q - 当前题目（未达提交下限时仅提示状态栏，不切页）
      */
     private confirmAndAdvance;
+    /**
+     * 作者确认题目后刷新推演：答案未变则保留既有结果，变了则先撤回再重新请求
+     * @param qIndex - 刚确认的题目索引（0-based）
+     */
+    private expandAfterConfirm;
+    /**
+     * 写入推演结果（仅采纳最新请求；非最新、已终结或已卸载时丢弃）
+     * @param ticket - 请求序号
+     * @param qIndex - 触发题目索引（0-based）
+     * @param signature - 触发题目当时的答案签名
+     * @param payload - 推演载荷
+     */
+    private applyExpansion;
+    /**
+     * 报告推演失败（仅最新请求；作者已填内容保持不变）
+     * @param ticket - 请求序号
+     * @param err - 失败原因
+     */
+    private reportExpansionFailure;
+    /**
+     * 提取异常的可读描述
+     * @param err - 未知异常
+     * @returns `Error` 的 `message`，其余类型取字符串形式
+     */
+    private describeError;
+    /** 题目总数变化后收敛 Tab、光标与光标记忆（题数变少时当前页与越界光标一并回退） */
+    private trimTabs;
     /**
      * Component 接口约定：键盘事件三级路由（输入模式 → 全局键 → 分视图）
      * Esc 与 Ctrl+C 同为取消键（宿主不会自行中止工具信号）：常规模式直接 `finish(true)`，输入模式下编辑器非空时首次仅武装丢弃确认

package/dist/expansion.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file expansion.ts
+ * @description 实时推演协议：请求载荷构建、模型回复解析与推演结果的不可信边界收敛
+ *
+ * 核心架构特性：
+ * - 请求只携带表单上下文、已声明题目与已确认作答，不携带内部索引等不可见字段
+ * - 回复约束为纯 JSON 对象，解析失败即抛出明确异常，由组件层在状态栏报告并保留既有作答
+ * - 载荷过滤（未知题目、重复标签、ID 冲突）全部委托 `sanitize.ts`，本模块不重复实现清洗规则
+ *
+ * 依赖方向：expansion.ts → schema.ts（载荷类型）/ model.ts（只读类型）/ sanitize.ts / texts.ts；被 component.ts（运行器类型）与 index.ts（模型调用装配）消费
+ */
+import type { AuthorAnswerItem, NormalizedQuestion } from "./model.js";
+import { type ExpansionContext } from "./sanitize.js";
+import type { ExpansionPayload } from "./schema.js";
+/** 一次推演的输入：表单上下文、当前题目与已确认作答 */
+export interface ExpansionRequest {
+    /** 问卷总标题 */
+    readonly formTitle: string;
+    /** 问卷全局背景（可选） */
+    readonly formDescription?: string;
+    /** 调用方给出的长期推演方向指示（可选） */
+    readonly guidance?: string;
+    /** 推演题目的落点描述（供模型判定哪些题目位于插入点之前） */
+    readonly insert: string;
+    /** 本次允许新增的题目数量（不含已声明题目） */
+    readonly maxAdditionalQuestions: number;
+    /** 当前已声明的全部题目（按展示顺序） */
+    readonly questions: readonly NormalizedQuestion[];
+    /** 当前已确认的作答 */
+    readonly answers: readonly AuthorAnswerItem[];
+}
+/** 推演执行器：由入口层装配模型调用，组件层只等待载荷（取消经 `signal` 级联） */
+export type ExpansionRunner = (request: ExpansionRequest, signal: AbortSignal) => Promise<ExpansionPayload>;
+/**
+ * 构建推演用户消息（前缀说明 + 单行 JSON 载荷）
+ * @param request - 推演输入
+ * @returns 面向模型的用户消息正文
+ */
+export declare function buildExpansionUserMessage(request: ExpansionRequest): string;
+/**
+ * 从回复文本中提取并校验 JSON 对象
+ * @param reply - 模型回复原文（可能包含代码围栏或前后说明）
+ * @returns 已过滤的推演载荷
+ * @throws Error 回复中不存在 JSON 对象、JSON 解析失败时抛出（由组件层在状态栏报告）
+ */
+export declare function parseExpansionReply(reply: string, context: ExpansionContext): ExpansionPayload;
+/**
+ * 归集推演载荷的过滤上下文
+ * @param questions - 当前已声明的题目
+ * @returns 题目 ID 列表与各题已有选项标签
+ */
+export declare function expansionContext(questions: readonly NormalizedQuestion[]): ExpansionContext;

package/dist/i18n.d.ts

@@ -3,7 +3,7 @@
  * @description 语言资源注册、系统语言探测与模板字典编译的完整实现
  *
  * 资源约定：
- * - 语言文件位于仓库根 `lang/`，文件名即 locale 标识（`en_US`、`zh_CN`），新增语言只需在 {@link LOCALE_PACKAGES} 追加一项导入
+ * - 语言文件位于仓库根 `lang/`，文件名即 locale 标识，新增语言只需在 {@link LOCALE_PACKAGES} 追加一项导入
  * - 纯字符串即原样文案；字符串数组即文案列表；`{ "template": "…", "params": ["a", "b"] }` 为带插值的模板对象，声明形参时编译为定参函数，省略 `params` 时在装载期求值为常量文案
  * - 模板占位符 `{name}` 取 `params` 同名形参，`{icon.<键>}` 取调用方传入的共享常量解析器结果
  * - `en_US` 为规范语言：键集合、参数个数与取值种类以它为准；其余语言缺失的键回退 `en_US`，结构与规范语言不符时立即抛出异常

package/dist/index.d.ts

@@ -3,12 +3,13 @@
  * @description 作者请示插件入口：注册 `ask_author` 工具与 `/ask-author` 命令，并编排工具执行生命周期
  *
  * 核心架构特性：
- * - 执行流程只做守卫与分支：信号已中止 → 取消；非 TUI → 结构化错误；模型构建失败 → 条件错误或运行期异常；无题目 → 空题目错误；UI 返回 → 取消或完成
+ * - 执行流程只做守卫与分支：信号已中止 → 取消；非 TUI → 结构化错误；模型构建失败 → 条件错误或运行期异常；无题目 → 空题目错误；请求推演但无可用模型 → 结构化错误；UI 返回 → 取消或完成
+ * - 实时推演的模型调用只在本文件装配（`createExpansionRunner`），推演用量累加后挂在工具结果的 `usage` 上
  * - 结果构造、卡片渲染与执行编排分属 `tool-result.ts` / `tool-card.ts` / 本文件，宿主边界代码保持可独立测试
  * - 工具声明为 `model-only`（交互式 UI 只由模型直接发起），并标注只读、封闭世界，供权限扩展判断
  * - 本文件不注册监听器与定时器；组件级 AbortSignal 级联取消与 `dispose()` 幂等回收由 `AskAuthorComponent` 负责
  *
- * 依赖方向：index.ts 为模块依赖图的入口；`component` / `model` / `schema` / `sanitize` / `texts` / `tool-card` / `tool-result` 均为其直接依赖
+ * 依赖方向：index.ts 为模块依赖图的入口；`component` / `expansion` / `model` / `schema` / `sanitize` / `texts` / `tool-card` / `tool-result` 均为其直接依赖
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 /**
@@ -17,9 +18,10 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
  */
 export default function askAuthorExtension(pi: ExtensionAPI): void;
 export { askAuthorExtension };
-export { AdaptiveConditionError, AskAuthorFormModel, type AskAuthorResult, type AuthorAnswerItem, type NormalizedOption, type NormalizedQuestion, type VisibilityCondition, } from "./model.js";
-export { AskAuthorParams, OptionSchema, QuestionSchema, ShowIfConditionSchema, type RawParams } from "./schema.js";
-export { sanitizeAskAuthorArgs } from "./sanitize.js";
+export { AdaptiveConditionError, AskAuthorFormModel, type AskAuthorResult, type AuthorAnswerItem, type ExpansionRecord, type NormalizedOption, type NormalizedQuestion, type VisibilityCondition, } from "./model.js";
+export { AskAuthorParams, ExpansionSchema, OptionSchema, QuestionSchema, ShowIfConditionSchema, type ExpansionConfig, type ExpansionPayload, type OptionAddition, type RawParams, } from "./schema.js";
+export { sanitizeAskAuthorArgs, sanitizeExpansionPayload, type ExpansionContext } from "./sanitize.js";
+export { buildExpansionUserMessage, expansionContext, parseExpansionReply, type ExpansionRequest, type ExpansionRunner, } from "./expansion.js";
 export { TEXTS } from "./texts.js";
 export { ICONS, LAYOUT_CONFIG, MAX_OPTIONS, MAX_QUESTIONS } from "./layout.js";
 export { ACTIVE_LOCALE, detectLocale } from "./i18n.js";