@xgspz/cli-ui 0.0.0-stage → 0.6.15

package/src/core/config.ts

@@ -0,0 +1,252 @@
+/**
+ * 组件的界面配置：哪些模块显示、文案怎么写。全部可选，缺省值见下方 DEFAULT_*_CONFIG。
+ *
+ *   <CliChat config={{ header: { title: true, status: true }, composer: { placeholder: "问点什么…", fileUpload: false } }} />
+ *   <CliMsgList config={{ header: { refresh: false }, card: { turns: false } }} />
+ *
+ * 开关类的模块写 false 就整块隐藏，写对象就逐项开关；文案里可以用 {title}（对话标题）、{agent}（智能体名）。
+ */
+
+// ── cli-chat ─────────────────────────────────────────
+
+export interface CliChatConfig {
+  /** 顶部栏。缺省隐藏；true = 每一项都显示；对象 = 只显示写了 true 的项。 */
+  header?: boolean | {
+    /** 面包屑：色块 + 名称 / 对话。 */
+    crumb?: boolean;
+    /** 「导出执行过程」按钮。 */
+    export?: boolean;
+    /** 对话标题。 */
+    title?: boolean;
+    /** 智能体标签（Codex / Claude Code）。 */
+    agent?: boolean;
+    /** token 用量。 */
+    usage?: boolean;
+    /** 模型（默认 + 实际模型）。 */
+    model?: boolean;
+    /** 对话状态（运行中 / 需要你处理 / 已结束）。 */
+    status?: boolean;
+    /** 「结束对话」按钮。 */
+    close?: boolean;
+  };
+  /** 底部输入框。false = 不显示输入框（只读）；对象 = 逐项配置。 */
+  composer?: boolean | {
+    /** 回复时的占位文案，可用 {title} {agent}。 */
+    placeholder?: string;
+    /** 新对话（还没有 jobId）时的占位文案。 */
+    placeholderNew?: string;
+    /** 智能体正在执行、发的消息会排队时的占位文案。 */
+    placeholderRunning?: string;
+    /** 不能发送时（对话已结束、只读）的占位文案。 */
+    placeholderDisabled?: string;
+    /** 底部「Shift + Enter 换行」提示；发送快捷键仍为 Enter。 */
+    hints?: boolean;
+    /** 底部字数统计。 */
+    charCount?: boolean;
+    /** 文件上传（按钮、拖拽、粘贴文件）。只收文档：Word、Excel、Markdown、TXT、HTML、CSV。 */
+    fileUpload?: boolean;
+    /** 智能体选择入口，默认显示；缺少服务端能力时禁用。 */
+    agentSelector?: boolean;
+    /** 执行模式选择入口，默认显示；缺少服务端能力时禁用。 */
+    executionMode?: boolean;
+    /** 「文件」按钮的文字。 */
+    fileButtonText?: string;
+    /** 执行控制：普通对话停止当前轮次，一次性子任务暂停 / 继续。 */
+    stop?: boolean;
+    /** 运行中允许发消息排队；false = 运行中不能发。 */
+    queue?: boolean;
+  };
+  /** 对话区。 */
+  transcript?: {
+    /** 右下角的上一条 / 下一条 / 跳到最新按钮。 */
+    nav?: boolean;
+    /** 「第 1 次会话 · 当前」分隔线。 */
+    sessionLabel?: boolean;
+    /** 消息时间。 */
+    timestamps?: boolean;
+    /** 已随项目上下文发送的初始提示。缺省不渲染；true 显示原文。 */
+    initialPrompt?: boolean;
+    /** 首条消息上的「初始提示」「已随项目上下文发送」标记。 */
+    initialBadge?: boolean;
+    /** 工具调用卡片（命令、读写文件……）；false 只留文字往来（提问卡片照常显示）。 */
+    tools?: boolean;
+    /** 「智能体 · 运行中 0:12」那一行。 */
+    runningIndicator?: boolean;
+    /** 状态说明行：新对话的「尚未开始」、结束时的「对话已结束」「子任务已完成」等。缺省不显示。 */
+    status?: boolean;
+  };
+  /** 消息头上的称呼。 */
+  labels?: { user?: string; agent?: string };
+  /** 新对话的空白页。false = 不显示。 */
+  empty?: boolean | { title?: string; description?: string };
+  /**
+   * 输入框上方显示哪些看板引用（不显示的照样随下一条消息带给智能体，只是不占地方、也不能点掉）。
+   * 种类：viewing（看板上正在看的文件 / 浏览器页面，缺省带上）、file、selection（选中的一段）、browser、changes，或宿主自定义的种类；
+   * "*" = 没列出的种类。true 全显示，false 全不显示。缺省 { viewing: false }：正在看的不显示，明确引用的都显示。
+   */
+  refs?: boolean | Record<string, boolean>;
+}
+
+export interface ResolvedChatConfig {
+  header: { show: boolean; crumb: boolean; export: boolean; title: boolean; agent: boolean; usage: boolean; model: boolean; status: boolean; close: boolean };
+  composer: {
+    show: boolean; placeholder: string; placeholderNew: string; placeholderRunning: string; placeholderDisabled: string | null;
+    hints: boolean; charCount: boolean; fileUpload: boolean; agentSelector: boolean; executionMode: boolean; fileButtonText: string; stop: boolean; queue: boolean;
+  };
+  transcript: { nav: boolean; sessionLabel: boolean; timestamps: boolean; initialPrompt: boolean; initialBadge: boolean; tools: boolean; runningIndicator: boolean; status: boolean };
+  labels: { user: string; agent: string };
+  empty: { show: boolean; title: string; description: string };
+  /** 按种类显示 / 不显示；"*" 是没列出的种类。用 refShown 判断。 */
+  refs: Record<string, boolean>;
+}
+
+/** 这个种类的看板引用（"viewing" = 正在看的）要不要显示在输入框上方。 */
+export const refShown = (cfg: Pick<ResolvedChatConfig, "refs">, kind: string) => cfg.refs[kind] ?? cfg.refs["*"] ?? true;
+
+export const DEFAULT_CHAT_CONFIG: ResolvedChatConfig = {
+  // 顶部栏缺省整栏隐藏（模型、状态、用量这些对使用者是干扰），需要的项在 config.header 里打开。
+  header: { show: true, crumb: false, export: false, title: false, agent: false, usage: false, model: false, status: false, close: false },
+  composer: {
+    show: true,
+    placeholder: "回复 {agent}…",
+    placeholderNew: "输入消息，开始新对话…",
+    placeholderRunning: "排队一条后续消息…（本轮结束后发送）",
+    placeholderDisabled: null,
+    hints: false, charCount: false, fileUpload: true, agentSelector: true, executionMode: true, fileButtonText: "", stop: true, queue: true,
+  },
+  transcript: { nav: true, sessionLabel: true, timestamps: true, initialPrompt: false, initialBadge: true, tools: true, runningIndicator: true, status: false },
+  labels: { user: "你", agent: "智能体" },
+  empty: { show: true, title: "开始一个新对话", description: "在下面输入第一条消息。可以附上 Word、Excel、Markdown、TXT、HTML、CSV 文档，内容会转成文字一起发送。" },
+  refs: { "*": true, viewing: false },
+};
+
+export function resolveChatConfig(config: CliChatConfig = {}): ResolvedChatConfig {
+  const d = DEFAULT_CHAT_CONFIG;
+  const header = config.header === true ? allOn(d.header) : toggle(config.header, d.header);
+  const composer = toggle(config.composer, d.composer);
+  const empty = toggle(config.empty, d.empty);
+  return {
+    header,
+    composer,
+    transcript: { ...d.transcript, ...defined(config.transcript) },
+    labels: { ...d.labels, ...defined(config.labels) },
+    empty,
+    refs: config.refs === true ? { "*": true } : config.refs === false ? { "*": false } : { ...d.refs, ...(defined(isObj(config.refs) ? config.refs : undefined) as Record<string, boolean>) },
+  };
+}
+
+// ── cli-msglist ──────────────────────────────────────
+
+export interface CliMsgListConfig {
+  /** 顶部栏。false = 整栏隐藏；对象 = 逐项开关。 */
+  header?: boolean | {
+    /** 色块 + 名称。 */
+    title?: boolean;
+    /** 「+ 对话」按钮。 */
+    newButton?: boolean;
+    /** 「+ 对话」按钮的文字。 */
+    newButtonText?: string;
+    /** 手动刷新按钮，缺省隐藏。列表不定时轮询：打开着的对话实时更新，其余在页面回到前台、获得焦点、网络恢复时刷新。 */
+    refresh?: boolean;
+    /** 上下文说明框（需同时给 context 或 onEditContext）。 */
+    context?: boolean;
+  };
+  /** 搜索框：true 总是显示，false 不显示，"auto"（缺省）对话数 ≥ 6 时显示。 */
+  search?: boolean | "auto";
+  searchPlaceholder?: string;
+  /**
+   * 按状态分组（需要你处理 / 进行中 / 已结束 / 已取消），配合 groups 改组名。缺省不分组：一个列表，最近活动的在前。
+   */
+  grouped?: boolean;
+  /** 卡片上显示哪些内容。 */
+  card?: {
+    /** 状态点、状态文字，以及底部的「运行中 / 等你处理 / 已完成」等字样。缺省不显示（底部只有时间）。 */
+    status?: boolean;
+    /** 智能体标签。 */
+    agent?: boolean;
+    /** 第一条消息摘要。 */
+    description?: boolean;
+    /** 底部活动（3 分钟前；打开 status 时带上运行中、排队等状态）。 */
+    activity?: boolean;
+    /** 「N 轮对话」。 */
+    turns?: boolean;
+    /** 「+」按钮：在这个任务（对话任务）里新开一个对话，共用同一个工作区。 */
+    newInJob?: boolean;
+  };
+  /** 分组标题（grouped 时）；写 false 隐藏这一组。 */
+  groups?: { needs?: string | false; active?: string | false; done?: string | false; cancelled?: string | false };
+  /** 没有对话时的提示。 */
+  emptyTitle?: string;
+  emptyDescription?: string;
+}
+
+export interface ResolvedMsgListConfig {
+  header: { show: boolean; title: boolean; newButton: boolean; newButtonText: string; refresh: boolean; context: boolean };
+  search: boolean | "auto";
+  searchPlaceholder: string;
+  grouped: boolean;
+  card: { status: boolean; agent: boolean; description: boolean; activity: boolean; turns: boolean; newInJob: boolean };
+  groups: { needs: string | false; active: string | false; done: string | false; cancelled: string | false };
+  emptyTitle: string;
+  emptyDescription: string;
+}
+
+export const DEFAULT_MSGLIST_CONFIG: ResolvedMsgListConfig = {
+  header: { show: true, title: true, newButton: true, newButtonText: "对话", refresh: false, context: true },
+  search: "auto",
+  searchPlaceholder: "搜索对话…",
+  grouped: false,
+  // 状态缺省不显示（未开始、进行中、已完成……对使用者是干扰），需要时打开 card.status / grouped。
+  card: { status: false, agent: true, description: true, activity: true, turns: true, newInJob: true },
+  groups: { needs: "需要你处理", active: "进行中", done: "已结束", cancelled: "已取消" },
+  emptyTitle: "还没有对话",
+  emptyDescription: "点「对话」开始一个新的对话。",
+};
+
+export function resolveMsgListConfig(config: CliMsgListConfig = {}): ResolvedMsgListConfig {
+  const d = DEFAULT_MSGLIST_CONFIG;
+  return {
+    header: toggle(config.header, d.header),
+    search: config.search ?? d.search,
+    searchPlaceholder: config.searchPlaceholder ?? d.searchPlaceholder,
+    grouped: config.grouped ?? d.grouped,
+    card: { ...d.card, ...defined(config.card) },
+    groups: { ...d.groups, ...defined(config.groups) },
+    emptyTitle: config.emptyTitle ?? d.emptyTitle,
+    emptyDescription: config.emptyDescription ?? d.emptyDescription,
+  };
+}
+
+// ── 小工具 ───────────────────────────────────────────
+
+/** 文案模板：{title}、{agent}。 */
+export function fillTemplate(template: string, vars: Record<string, string>) {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) => (key in vars ? vars[key] : match));
+}
+
+const isObj = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object";
+
+/** 去掉值为 undefined 的键，免得盖掉缺省值。 */
+function defined<T extends object>(value: T | undefined): Partial<T> {
+  if (!value) return {};
+  return Object.fromEntries(Object.entries(value).filter(([, v]) => v !== undefined)) as Partial<T>;
+}
+
+/**
+ * 开关型模块：false → 全关（show=false 且布尔项全 false，文案保留）；true / 不给 → 缺省；对象 → 合并缺省。
+ */
+function allOn<T extends { show: boolean }>(defaults: T): T {
+  const on = { ...defaults } as Record<string, unknown>;
+  for (const key of Object.keys(on)) if (typeof on[key] === "boolean") on[key] = true;
+  return on as T;
+}
+
+function toggle<T extends { show: boolean }>(value: boolean | object | undefined, defaults: T): T {
+  if (value === false) {
+    const off = { ...defaults, show: false } as Record<string, unknown>;
+    for (const key of Object.keys(off)) if (typeof off[key] === "boolean") off[key] = false;
+    return off as T;
+  }
+  if (!isObj(value)) return { ...defaults };
+  return { ...defaults, ...defined(value as Partial<T>), show: true };
+}