@xyz-agent/extension-protocol 0.1.1-dev.0

package/dist/index.d.mts

@@ -0,0 +1,277 @@
+/**
+ * GUI 渲染协议核心类型定义。
+ *
+ * GuiComponent 是 pi Component { render(width): string[] } 的可序列化镜像。
+ * extension 按 ctx.mode 分支：TUI 走原生 Component，RPC 走 GuiComponent（放进 details.__gui__）。
+ *
+ * GuiComponentProps 是类型路由的聚合点：通用布局原语 + extension 专属组件
+ * 全部在此声明键值，子类型直接内联本文件（纯类型，无运行时逻辑）。
+ *
+ * @see docs/architecture/extension-gui-protocol.md
+ */
+declare const PROTOCOL_VERSION: 1;
+/**
+ * GUI 渲染组件——pi Component 的可序列化镜像。
+ *
+ * pi:  Component { render(width): string[] }   ← ANSI 文本行
+ * gui: GuiComponent = { type, props }           ← 结构化数据
+ */
+interface GuiComponent<T extends GuiComponentType = GuiComponentType> {
+    /** 组件类型，前端按此路由到 Vue 组件 */
+    type: T;
+    /** 组件 props，类型由 type 决定 */
+    props: GuiComponentProps[T];
+}
+type GuiComponentType = keyof GuiComponentProps;
+interface GuiComponentProps {
+    /** ANSI 文本兜底——保留原始 ANSI 序列，前端用 ansi_up 渲染 */
+    'ansi-text': {
+        lines: string[];
+    };
+    /** 卡片容器——替代 TUI 的 ┌─┐││└─┘ box 边框 */
+    'card': {
+        variant?: 'default' | 'elevated' | 'danger' | 'success';
+        header?: GuiComponent | string;
+        body: GuiComponent[];
+    };
+    /** 统计行——替代 TUI 的 "N turns · Nk · Ns" */
+    'stats-line': {
+        items: StatItem[];
+    };
+    /** 进度条——替代 TUI 的 ████░░░░ */
+    'progress-bar': {
+        label?: string;
+        current: number;
+        total: number;
+        unit?: string;
+        severity?: 'ok' | 'warn' | 'danger';
+    };
+    /** 列表树——替代 TUI 的 ⎿ ├─ └─ 缩进 */
+    'list-tree': {
+        items: TreeItem[];
+    };
+    /** 双列网格——替代 TUI 的 │ 列分隔 */
+    'columns': {
+        children: GuiComponent[];
+        ratios?: number[];
+    };
+    /** 标签栏——替代 TUI 的 tab │ 分隔 */
+    'tab-bar': {
+        tabs: {
+            label: string;
+            active?: boolean;
+            status?: 'done' | 'pending';
+        }[];
+    };
+    /** 自定义组件——逃生口（仅限内置 extension 编译期注册） */
+    'custom': {
+        component: string;
+        props: Record<string, unknown>;
+    };
+}
+interface GuiRenderResult {
+    /** 版本协商，前端检测，不认识降级 ansi-text */
+    v: typeof PROTOCOL_VERSION;
+    component: GuiComponent;
+}
+interface StatItem {
+    label?: string;
+    value: string;
+    severity?: 'ok' | 'warn' | 'danger';
+    icon?: string;
+}
+interface TreeItem {
+    icon?: TreeItemIcon;
+    label: string;
+    status?: 'running' | 'done' | 'failed';
+    depth?: number;
+    children?: TreeItem[];
+}
+type TreeItemIcon = 'arrow' | 'check' | 'cross' | 'circle' | 'dot' | 'pause' | 'branch';
+
+/**
+ * 通用传输 marker。extension 用 guiSetWidget 编码进 string[]，
+ * runtime event-adapter 检测 marker 解码为结构化 WS 帧。
+ *
+ * NUL 字符开头的 marker，不会出现在正常文本中。
+ */
+declare const GUI_WIDGET_MARKER = "\0XYZ_GUI_WIDGET:";
+
+/**
+ * helpers 需要的 ctx 最小接口。
+ * pi 的 ExtensionContext 天然满足此结构（有 mode/hasUI/ui 字段）。
+ * 用结构化类型而非 import pi SDK，保持协议包零依赖。
+ */
+interface GuiContext {
+    mode: 'tui' | 'rpc' | 'json' | 'print';
+    hasUI: boolean;
+    ui?: {
+        setWidget?: (key: string, lines: string[] | undefined) => void;
+        select?: (header: string, options: string[], opts?: {
+            signal?: AbortSignal;
+        }) => Promise<string | undefined>;
+        input?: (header: string, prompt: string, opts?: {
+            signal?: AbortSignal;
+        }) => Promise<string | undefined>;
+        confirm?: (header: string, prompt: string, opts?: {
+            signal?: AbortSignal;
+        }) => Promise<boolean | undefined>;
+        custom?: (factory: unknown, opts?: unknown) => Promise<Record<string, string | string[]> | undefined>;
+    };
+}
+
+/**
+ * Extension GUI 渲染协议 helper 函数（通用层）。
+ *
+ * 设计原则：
+ * - 零运行时依赖（不依赖 pi SDK）
+ * - helpers 接受最小化的 ctx 结构（结构化类型），pi 的 ExtensionContext 天然满足
+ * - extension 开发者只需调这些 helper，不需要了解底层编码细节
+ */
+
+/**
+ * 检测当前环境是否支持 GUI 渲染（RPC 模式 = GUI 渲染通道有效）。
+ * TUI/json/print 模式走 pi 原生渲染，不需要 GuiComponent。
+ */
+declare function isGuiCapable(ctx: GuiContext): boolean;
+/**
+ * 构造 GuiRenderResult，放进 details.__gui__。
+ * stripUndefined 确保序列化不含 undefined（JSON.stringify 会丢弃 undefined 字段）。
+ */
+declare function guiResult(component: GuiComponent): GuiRenderResult;
+/**
+ * 构造 GuiComponent，带类型推断。
+ * 类型参数 T 约束 props 到对应类型的 props 形状。
+ */
+declare function guiComponent<T extends GuiComponentType>(type: T, props: GuiComponentProps[T]): GuiComponent<T>;
+/**
+ * 设置 GUI widget。RPC 模式下用 marker 编码 GuiComponent JSON 进 string[]，
+ * runtime event-adapter 检测 marker 解码为结构化 WS 帧。
+ * TUI 模式下此函数无操作（extension 应在 TUI 分支调原生 ctx.ui.setWidget 传 Component factory）。
+ *
+ * 传 undefined 清除 widget。
+ */
+declare function guiSetWidget(ctx: GuiContext, key: string, component: GuiComponent | undefined): void;
+/**
+ * 从 details 中提取 GuiRenderResult。前端统一用此函数读取 __gui__，
+ * 集中校验版本号，避免散落的 as 断言。
+ */
+declare function extractGui(details: Record<string, unknown> | undefined): GuiRenderResult | undefined;
+/**
+ * 最小形状校验：判断 unknown 值是否为合法 GuiComponent（有 type 字符串 + props 对象）。
+ * 用于 widgetGui marker 解码后防止异常结构进入渲染层。
+ * 不校验 type 是否为已知值（GuiComponentRenderer 对未知 type 有 AnsiText 降级）。
+ */
+declare function isGuiComponent(value: unknown): value is GuiComponent;
+
+/**
+ * ask-user extension 的富交互类型定义。
+ *
+ * custom() 在 RPC 模式不可用（Component 是代码不是数据），ask-user 的「表单类」
+ * 交互改走 select 通道：askUserInteract() 把 AskUserQuestion[] 序列化进 select 的
+ * options[0]，runtime event-adapter 检测 ASK_USER_MARKER 透传 questions，
+ * 前端 AskUserOverlay 渲染富交互 UI。
+ *
+ * 这是 ask-user 的定制协议，不是通用富交互协议。
+ * 设计参考 ask-user 的 Question 结构。
+ */
+/**
+ * ask-user 富交互问题声明。
+ */
+interface AskUserQuestion {
+    /** Tab 标签 / 简短标题。多问题时用于 tab 切换，≤12 字符。
+     *  可选——未提供时前端用 question 文本作为 tab 标签（前 12 字符截断显示）
+     *  和 answers key（完整 question 文本，不截断）。 */
+    header?: string;
+    /** 完整问题文本。也作为 answers 的 fallback key（header 缺失时） */
+    question: string;
+    /** 上下文摘要（可选）。显示在问题上方，帮用户理解背景 */
+    context?: string;
+    /** 互斥选项列表（可选）。无 options = 纯自由文本输入 */
+    options?: AskUserOption[];
+    /** 是否允许多选。仅 options 存在时有效 */
+    multiSelect?: boolean;
+    /** 是否允许自由文本输入（Other）。
+     *  - 有 options 时：默认 true，前端在选项末尾追加 Other 输入框；设 false 则不追加
+     *  - 无 options 时：整个问题就是自由输入，此字段被忽略 */
+    allowOther?: boolean;
+    /** 是否允许附加评论。选中后可追加短文本 */
+    allowComment?: boolean;
+}
+interface AskUserOption {
+    /** 显示标签 */
+    label: string;
+    /** 回传值。未提供时用 label */
+    value?: string;
+    /** 描述（可选）。显示在 label 下方，解释 tradeoff */
+    description?: string;
+}
+/**
+ * ask-user 富交互回传结果。key = question.header（header 缺失时用 question 文本）。
+ *
+ * 答案编码规则（避免逗号歧义）：
+ * - 单选：value = 选中项的 value string（或 label）
+ * - 多选：value = JSON.stringify(选中项 value 数组)，如 '["pg","mysql"]'
+ *   （不用逗号 join——option value 可能含逗号导致 split 歧义）
+ * - Other 文本：单独 key `${header}__other`，value = 自由文本（不混进选中项数组）
+ * - comment：单独 key `${header}__comment`，value = 评论文本
+ *
+ * extension 解析示例：
+ *   const selected = JSON.parse(answers[header])  // 多选 → string[]
+ *   const other = answers[`${header}__other`]     // Other 自由文本
+ *   const comment = answers[`${header}__comment`] // 评论
+ */
+type AskUserAnswers = Record<string, string>;
+
+/**
+ * ask-user 富交互请求的 title marker。runtime event-adapter 和前端 useExtensionUI
+ * 检测此 marker 区分 ask-user 请求与普通 select。
+ *
+ * NUL 前缀确保不会与 extension 正常的 select title 冲突。
+ * 与 GUI_WIDGET_MARKER 同理（见 core/markers.ts）。
+ */
+declare const ASK_USER_MARKER = "\0XYZ_ASK_USER";
+
+/**
+ * ask-user extension 的富交互 helper（定制层）。
+ *
+ * askUserInteract() 是 ask-user extension 在 RPC 模式下的交互入口。
+ * TUI 模式下 extension 必须自行调 ctx.ui.custom()。
+ *
+ * 走 select 通道 + marker（ASK_USER_MARKER），复用 select 的全部管道逻辑
+ * （队列 / 超时 / 回传 / abort），零重复代码。
+ */
+
+/**
+ * ask-user 富交互入口（RPC 模式专用）。
+ *
+ * RPC 模式：用 select 通道携带 questions 数据，前端渲染富交互 UI。
+ * TUI 模式：抛错。extension 必须自行调 ctx.ui.custom()。
+ *
+ * @param ctx        ExtensionContext（pi 提供）
+ * @param questions  交互问题声明
+ * @param options    可选：signal（abort）、allowCancel（前端是否显示取消按钮）
+ * @returns          answers（key=header/question, value=JSON编码的答案），用户取消返回 null
+ */
+declare function askUserInteract(ctx: GuiContext, questions: AskUserQuestion[], options?: {
+    signal?: AbortSignal;
+    allowCancel?: boolean;
+}): Promise<AskUserAnswers | null>;
+/**
+ * 从 answers 中提取某个问题的选中值（单选返回 string，多选返回 string[]）。
+ *
+ * 多选 answers 的 value 是 JSON.stringify(string[])，此 helper 自动 parse。
+ * parse 失败时降级返回 [raw]（兼容非标准格式的回传）。
+ */
+declare function getAskUserAnswer(answers: AskUserAnswers, question: AskUserQuestion): string | string[] | undefined;
+/** 从 answers 中提取 Other 自由文本 */
+declare function getAskUserOther(answers: AskUserAnswers, question: AskUserQuestion): string | undefined;
+/** 从 answers 中提取评论 */
+declare function getAskUserComment(answers: AskUserAnswers, question: AskUserQuestion): string | undefined;
+/**
+ * 类型守卫：验证 unknown 是否为合法的 AskUserQuestion。
+ * 用于前端从 runtime 透传的 askUserQuestions（unknown[]）中安全收窄。
+ */
+declare function isAskUserQuestion(value: unknown): value is AskUserQuestion;
+
+export { ASK_USER_MARKER, type AskUserAnswers, type AskUserOption, type AskUserQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, PROTOCOL_VERSION, type StatItem, type TreeItem, type TreeItemIcon, askUserInteract, extractGui, getAskUserAnswer, getAskUserComment, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, isGuiCapable, isGuiComponent };

package/dist/index.mjs

@@ -0,0 +1,126 @@
+// src/core/types.ts
+var PROTOCOL_VERSION = 1;
+
+// src/core/markers.ts
+var GUI_WIDGET_MARKER = "\0XYZ_GUI_WIDGET:";
+
+// src/core/helpers.ts
+function isGuiCapable(ctx) {
+  return ctx.mode === "rpc";
+}
+function guiResult(component) {
+  return {
+    v: PROTOCOL_VERSION,
+    component: stripUndefined(component)
+  };
+}
+function guiComponent(type, props) {
+  return { type, props };
+}
+function guiSetWidget(ctx, key, component) {
+  if (!ctx.ui?.setWidget) return;
+  if (component) {
+    const encoded = [GUI_WIDGET_MARKER + JSON.stringify(stripUndefined(component))];
+    ctx.ui.setWidget(key, encoded);
+  } else {
+    ctx.ui.setWidget(key, void 0);
+  }
+}
+function extractGui(details) {
+  const g = details?.__gui__;
+  if (g && typeof g === "object" && "v" in g && "component" in g && g.v === PROTOCOL_VERSION) {
+    return g;
+  }
+  return void 0;
+}
+function isGuiComponent(value) {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value;
+  return typeof obj.type === "string" && obj.props !== null && obj.props !== void 0 && typeof obj.props === "object";
+}
+function stripUndefined(obj) {
+  if (obj === null || obj === void 0) return obj;
+  if (typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(stripUndefined);
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== void 0) {
+      result[key] = typeof value === "object" ? stripUndefined(value) : value;
+    }
+  }
+  return result;
+}
+
+// src/extensions/ask-user/marker.ts
+var ASK_USER_MARKER = "\0XYZ_ASK_USER";
+
+// src/extensions/ask-user/helpers.ts
+async function askUserInteract(ctx, questions, options) {
+  if (questions.length === 0) return {};
+  if (isGuiCapable(ctx) && ctx.ui?.select) {
+    const payload = JSON.stringify(stripUndefined({
+      questions,
+      allowCancel: options?.allowCancel ?? true
+    }));
+    const value = await ctx.ui.select(
+      ASK_USER_MARKER,
+      // title = marker，runtime/前端据此识别
+      [payload],
+      // options[0] = JSON payload（runtime 解析）
+      { signal: options?.signal }
+    );
+    if (value === void 0) return null;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  throw new Error(
+    "askUserInteract() is only available in RPC mode. In TUI mode, use ctx.ui.custom() with your own Component directly."
+  );
+}
+function askUserKey(question) {
+  return question.header ?? question.question;
+}
+function getAskUserAnswer(answers, question) {
+  const key = askUserKey(question);
+  const raw = answers[key];
+  if (raw === void 0) return void 0;
+  if (question.multiSelect) {
+    try {
+      const parsed = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed : [raw];
+    } catch {
+      return [raw];
+    }
+  }
+  return raw;
+}
+function getAskUserOther(answers, question) {
+  return answers[`${askUserKey(question)}__other`];
+}
+function getAskUserComment(answers, question) {
+  return answers[`${askUserKey(question)}__comment`];
+}
+function isAskUserQuestion(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const q = value;
+  return typeof q.question === "string" && (q.header === void 0 || typeof q.header === "string") && (q.options === void 0 || Array.isArray(q.options)) && (q.multiSelect === void 0 || typeof q.multiSelect === "boolean") && (q.allowOther === void 0 || typeof q.allowOther === "boolean") && (q.allowComment === void 0 || typeof q.allowComment === "boolean");
+}
+export {
+  ASK_USER_MARKER,
+  GUI_WIDGET_MARKER,
+  PROTOCOL_VERSION,
+  askUserInteract,
+  extractGui,
+  getAskUserAnswer,
+  getAskUserComment,
+  getAskUserOther,
+  guiComponent,
+  guiResult,
+  guiSetWidget,
+  isAskUserQuestion,
+  isGuiCapable,
+  isGuiComponent
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@xyz-agent/extension-protocol",
+  "version": "0.1.1-dev.0",
+  "description": "Extension GUI rendering protocol: types and helpers for pi extension dual-mode (TUI/GUI) rendering",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}