@genee/omp-opsx-addon 0.7.0 → 0.9.0

package/lib/pick-model-render.ts

@@ -0,0 +1,414 @@
+/**
+ * Shared /pick-model rendering (change: pick-model-ux).
+ *
+ * One compact block skeleton for all four command outputs (choices /
+ * selector switch / refresh / reset) plus error paths:
+ *   状态行 → 明细区（变更行或 agent 清单）→ 候选概览 → 脚注
+ *
+ * - No markdown tables, no horizontal rules, no emoji. Status glyphs come
+ *   from the host `SYMBOL_PRESETS` table, resolved per render from the
+ *   `symbolPreset` setting (invalid/missing → `unicode`). The TUI theme
+ *   singleton is deliberately NOT consulted: headless and in-process
+ *   subagent contexts may not have it initialized.
+ * - Internal quantities (tier=, gap=, class=) are translated to plain
+ *   phrases for display; the data-layer fields (`pickedReason`/`decision`
+ *   with their `class=` annotations) are untouched.
+ * - Agent inventory classification mirrors OMP native resolution
+ *   (`resolveEffectiveAgentModelSelection`, `isSessionInheritedAgentPattern`,
+ *   `resolveConfiguredRolePattern`).
+ *
+ * Everything here is a pure function; index.ts assembles the parts and
+ * calls `renderPickModelReport` once per command output.
+ */
+import { SYMBOL_PRESETS, isValidSymbolPreset } from '@oh-my-pi/pi-coding-agent/modes/theme/symbols';
+import type { AgentDefinition } from '@oh-my-pi/pi-coding-agent/task/types';
+import { providerDisplayName } from './provider-variants.js';
+
+/** Minimal settings surface for the `symbolPreset` read (host `pi.pi.settings`). */
+export interface SymbolSettings {
+    get(key: string): unknown;
+}
+
+/** Internal glyph set used by every pick-model output (design D2). */
+export interface RenderSymbols {
+    /** 成功/已应用（status.success） */
+    success: string;
+    /** 失败/错误（status.error） */
+    error: string;
+    /** 警告/受限（status.warning） */
+    warning: string;
+    /** 候选/未选中（status.pending） */
+    pending: string;
+    /** 选中/主会话/状态行（status.info） */
+    selected: string;
+    /** agent 清单「跟随切换」（status.pending） */
+    follow: string;
+    /** agent 清单「固定」（status.shadowed） */
+    fixed: string;
+}
+
+/**
+ * Read the current preset per render; undefined/invalid — or a settings
+ * read that throws (early startup / partial init) — falls back to unicode
+ * without ever surfacing an error into a command output.
+ */
+export function resolveSymbols(settings?: SymbolSettings | null): RenderSymbols {
+    let raw: unknown;
+    try {
+        raw = settings?.get('symbolPreset');
+    } catch {
+        raw = undefined;
+    }
+    const preset = typeof raw === 'string' && isValidSymbolPreset(raw) ? raw : 'unicode';
+    const map = SYMBOL_PRESETS[preset];
+    return {
+        success: map['status.success'],
+        error: map['status.error'],
+        warning: map['status.warning'],
+        pending: map['status.pending'],
+        selected: map['status.info'],
+        follow: map['status.pending'],
+        fixed: map['status.shadowed'],
+    };
+}
+
+// ── 人话文案映射（design D3）────────────────────────────────────────
+
+const COVERAGE_HUMAN: Record<string, string> = {
+    '0': '计划内',
+    '1': '按量直连',
+    '2': '按量兜底',
+    plan: '计划内',
+    standard: '按量直连',
+    payg: '按量兜底',
+    '①plan': '计划内',
+    '②standard': '按量直连',
+    '③payg': '按量兜底',
+};
+
+/** Coverage class (numeric, `class=…`, or `①plan` form) → plain phrase. */
+export function coverageLabel(cls: number | string | undefined | null): string {
+    if (cls === undefined || cls === null) return '';
+    const key = String(cls);
+    return COVERAGE_HUMAN[key] ?? key;
+}
+
+const TIER_HUMAN: Record<string, string> = {
+    tiny: '轻量',
+    low: '低档',
+    mid: '中档',
+    high: '高档',
+    top: '旗舰',
+};
+
+/** Tier name → plain phrase (轻量/低档/中档/高档/旗舰). */
+export function tierLabel(tier: string | undefined | null): string {
+    if (!tier) return '';
+    return TIER_HUMAN[tier] ?? tier;
+}
+
+const ROLE_KIND_HUMAN: Record<string, string> = {
+    auto: '自动',
+    'omp-alias': 'role 链',
+    model: '已指定',
+    'provider-model': '已指定',
+};
+
+/** Role config kind → plain phrase (已指定/自动/role 链). */
+export function roleKindLabel(kind: string | undefined | null): string {
+    if (!kind) return '';
+    return ROLE_KIND_HUMAN[kind] ?? kind;
+}
+
+// ── agent 来源分类（design D4）──────────────────────────────────────
+
+/** Classification of one agent's model resolution source. */
+export interface AgentModelSource {
+    /** Plain-phrase label; carries the alias/literal where applicable. */
+    label: string;
+    /** Whether the agent's model follows /pick-model switches. */
+    follows: boolean;
+}
+
+/**
+ * Classify an agent by its frontmatter `model` patterns (design D4 table).
+ * Missing / `default` / `@default` / `@task` → inherit the primary session
+ * model; `@smol`/`@slow` follow the written roles; `@designer` follows via
+ * default inheritance; `@tiny`/`@advisor` resolve OMP static priority chains
+ * (unless config-pinned, which always wins over the label); literal patterns
+ * are pins; other `@role` values stay on the config layer.
+ */
+export function classifyAgentModelSource(model?: string[]): AgentModelSource {
+    const first = model?.find((m) => typeof m === 'string' && m.trim() !== '')?.trim();
+    if (!first || first === 'default' || first === '@default' || first === '@task') {
+        return { label: '继承主会话', follows: true };
+    }
+    if (first === '@smol' || first === '@slow') {
+        return { label: `role 链 ${first}`, follows: true };
+    }
+    if (first === '@designer') {
+        return { label: 'role 链 @designer（经 default 继承）', follows: true };
+    }
+    if (first === '@tiny' || first === '@advisor') {
+        return { label: `OMP 自动链 ${first}（静态 priority 模式）`, follows: false };
+    }
+    if (first.startsWith('@')) {
+        return { label: `自定义 role ${first}`, follows: false };
+    }
+    return { label: `钉值 ${model!.map((m) => m.trim()).join(' / ')}`, follows: false };
+}
+
+/** Resolution phrase for one inventory row (`跟随切换 · role 链 @smol` …). */
+function agentResolvePhrase(model: string[] | undefined, source: AgentModelSource): string {
+    if (source.label === '继承主会话') {
+        const first = model?.find((m) => typeof m === 'string' && m.trim() !== '')?.trim();
+        return first === '@task'
+            ? '继承主会话（@task 未配置回落主会话）'
+            : '继承主会话';
+    }
+    if (source.follows) return `跟随切换 · ${source.label}`;
+    if (source.label.startsWith('OMP 自动链')) return source.label;
+    return `固定 · ${source.label}`;
+}
+
+const SOURCE_GROUP_ORDER = ['project', 'user', 'bundled'] as const;
+const SOURCE_GROUP_LABEL: Record<string, string> = {
+    project: '项目',
+    user: '用户',
+    bundled: '内置',
+};
+
+/**
+ * Full agent inventory block for choices: `── agent 清单（N）──` header,
+ * grouped project → user → bundled, name-sorted inside each group, one
+ * `  <glyph> <name> — <phrase>` row per agent.
+ */
+export function formatAgentInventory(agents: AgentDefinition[], symbols: RenderSymbols): string {
+    if (agents.length === 0) {
+        return '── agent 清单 ──\n（未发现任何 agent）';
+    }
+    const bySource: Record<string, AgentDefinition[]> = {};
+    for (const agent of [...agents].sort((a, b) => a.name.localeCompare(b.name))) {
+        (bySource[agent.source] ??= []).push(agent);
+    }
+    const lines: string[] = [`── agent 清单（${agents.length}）──`];
+    for (const source of SOURCE_GROUP_ORDER) {
+        const list = bySource[source];
+        if (!list || list.length === 0) continue;
+        lines.push(SOURCE_GROUP_LABEL[source] ?? source);
+        for (const agent of list) {
+            const classified = classifyAgentModelSource(agent.model);
+            const phrase = agentResolvePhrase(agent.model, classified);
+            const glyph = classified.follows ? symbols.follow : symbols.fixed;
+            lines.push(`  ${glyph} ${agent.name} — ${phrase}`);
+        }
+    }
+    return lines.join('\n');
+}
+
+// ── 选择结果的展示辅助 ─────────────────────────────────────────────
+
+/** Structural subset of a selector candidate the renderer needs. */
+export interface RenderCandidate {
+    model: { provider: string; id: string };
+    /** Dedup key (`provider/id`). */
+    selector: string;
+    tier: string;
+    coverageClass: number;
+    reputation: number;
+    rank: number;
+    exhausted: boolean;
+}
+
+/** Structural subset of a SelectorResult the renderer needs. */
+export interface RenderRoleResult {
+    picked?: { provider: string; id: string } | null;
+    candidates?: RenderCandidate[];
+    allCandidates?: RenderCandidate[];
+}
+
+/**
+ * Plain-phrase coverage/tier of a picked model, looked up in the result's
+ * candidates. Empty when there is no pick or the candidate is absent.
+ */
+export function annotationOfPicked(
+    result: RenderRoleResult,
+    picked?: { provider: string; id: string } | null,
+): { coverage?: string; tier?: string } {
+    const target = picked ?? result.picked;
+    if (!target) return {};
+    const list = [...(result.candidates ?? []), ...(result.allCandidates ?? [])];
+    const candidate = list.find((c) => c.model.provider === target.provider && c.model.id === target.id);
+    if (!candidate) return {};
+    return { coverage: coverageLabel(candidate.coverageClass), tier: tierLabel(candidate.tier) };
+}
+
+/** One role row for `formatRoleLines`. */
+export interface RoleLineInput {
+    /** Display name (agent name, e.g. `coder` / `code-reviewer`). */
+    name: string;
+    /** Role config kind (auto/omp-alias/model/provider-model). */
+    kind?: string;
+    /** Configured model shown when the result has no pick. */
+    fallbackModel?: string;
+    result: RenderRoleResult;
+}
+
+/**
+ Role rows for choices: `主会话 <model> — 计划内 · 高档`, then one
+ `coder → <model> — 计划内 · 中档 · 自动` line per role.
+ */
+export function formatRoleLines(
+    rows: RoleLineInput[],
+    primary?: { model: { provider: string; id: string }; tier?: string },
+): string[] {
+    const lines: string[] = [];
+    if (primary) {
+        const allCandidates = rows.flatMap((r) => r.result.allCandidates ?? []);
+        const annotation = annotationOfPicked({ allCandidates }, primary.model);
+        const segments = [annotation.coverage, annotation.tier ?? tierLabel(primary.tier)].filter(Boolean);
+        lines.push(`主会话 ${primary.model.provider}/${primary.model.id}${segments.length > 0 ? ` — ${segments.join(' · ')}` : ''}`);
+    }
+    for (const row of rows) {
+        const target = row.result.picked ?? null;
+        const modelText = target ? `${target.provider}/${target.id}` : (row.fallbackModel ?? '(none)');
+        const annotation = annotationOfPicked(row.result, target);
+        const segments = [annotation.coverage, annotation.tier, roleKindLabel(row.kind)].filter(Boolean);
+        lines.push(`${row.name} → ${modelText}${segments.length > 0 ? ` — ${segments.join(' · ')}` : ''}`);
+    }
+    return lines;
+}
+
+/** One change line for switch/refresh/reset detail blocks. */
+export function formatChangeLine(opts: {
+    name: string;
+    from?: string;
+    to: string;
+    coverage?: string;
+    tier?: string;
+    kind?: string;
+}): string {
+    const head = opts.from ? `${opts.name} ${opts.from} → ${opts.to}` : `${opts.name} → ${opts.to}`;
+    const annotation = [opts.coverage, opts.tier, opts.kind].filter(Boolean).join(' · ');
+    return annotation ? `${head}（${annotation}）` : head;
+}
+
+/**
+ * Family × tier candidate overview (`── 候选 ──` block): per family the
+ * best candidate per tier by reputation, tagged with the plain coverage
+ * label of the family's class.
+ */
+export function formatCandidateOverview(results: RenderRoleResult[]): string {
+    const byFamily = new Map<string, Map<string, { modelId: string; rep: number; rank: number }>>();
+    // Coverage class is per-provider, so every candidate of a family carries
+    // the same class — first sighting wins (exhausted candidates are skipped
+    // entirely, mirroring the selector's display semantics).
+    const familyClass = new Map<string, number>();
+    for (const result of results) {
+        for (const c of result.allCandidates ?? []) {
+            if (c.exhausted) continue;
+            const fam = c.model.provider;
+            if (!familyClass.has(fam)) familyClass.set(fam, c.coverageClass);
+            const tierMap = byFamily.get(fam) ?? new Map<string, { modelId: string; rep: number; rank: number }>();
+            byFamily.set(fam, tierMap);
+            const existing = tierMap.get(c.tier);
+            if (!existing || c.reputation > existing.rep || (c.reputation === existing.rep && c.rank > existing.rank)) {
+                tierMap.set(c.tier, { modelId: c.model.id, rep: c.reputation, rank: c.rank });
+            }
+        }
+    }
+    const lines: string[] = ['── 候选 ──'];
+    const families = [...byFamily.keys()].sort();
+    let rendered = 0;
+    for (const fam of families) {
+        const tierMap = byFamily.get(fam)!;
+        const parts: string[] = [];
+        for (const tier of ['top', 'high', 'mid', 'low', 'tiny']) {
+            const m = tierMap.get(tier);
+            if (!m) continue;
+            const shortId = m.modelId.length > 35 ? `${m.modelId.slice(0, 32)}...` : m.modelId;
+            parts.push(`${tierLabel(tier)}→${shortId}`);
+        }
+        if (parts.length === 0) continue;
+        rendered++;
+        lines.push(`${providerDisplayName(fam)} [${coverageLabel(familyClass.get(fam) ?? -1)}]: ${parts.join('  ')}`);
+    }
+    if (rendered === 0) lines.push('（无可用模型）');
+    return lines.join('\n');
+}
+
+/**
+ * Choices footnote: distinct-candidate score count, plain-phrase partition
+ * counts with the PAYG fold suffix, and the command hints.
+ */
+export function formatFootnote(results: RenderRoleResult[], paygLastResort: boolean | undefined): string {
+    let total = 0;
+    const classCounts: Record<number, number> = { 0: 0, 1: 0, 2: 0 };
+    const counted = new Set<string>();
+    for (const result of results) {
+        total += result.allCandidates?.length ?? 0;
+        for (const c of result.allCandidates ?? []) {
+            if (!counted.has(c.selector)) {
+                counted.add(c.selector);
+                classCounts[c.coverageClass] = (classCounts[c.coverageClass] ?? 0) + 1;
+            }
+        }
+    }
+    const foldSuffix = paygLastResort === false
+        ? '（分区已折叠）'
+        : classCounts[0] + classCounts[1] > 0
+            ? '（兜底未参与）'
+            : '';
+    const partition = `分区: ${coverageLabel(0)} ${classCounts[0]} · ${coverageLabel(1)} ${classCounts[1]} · ${coverageLabel(2)} ${classCounts[2]}${foldSuffix}`;
+    return `${total} 个候选参与评分 · ${partition}\n/pick-model refresh 切换耗尽模型 · /pick-model update 更新 tier 数据`;
+}
+
+// ── 段式骨架（design D1）───────────────────────────────────────────
+
+export type ReportKind = 'choices' | 'switch' | 'refresh' | 'reset' | 'error';
+
+/** Parts assembled by each command branch; unknown sections are omitted. */
+export interface ReportParts {
+    /** 动作短语（状态行主体），如 `已切换 selector 约束` / `当前选择`。 */
+    action: string;
+    /** 约束段（formatFamilyConstraint 原文），嵌入状态行。 */
+    constraint?: string;
+    /** 状态符号（缺省 `selected`；error kind 恒用 `error`）。 */
+    status?: 'success' | 'error' | 'warning';
+    /** 明细区块（变更行组 / role 行 / agent 清单段），块间空行。 */
+    detail?: string[];
+    /** 候选概览段。 */
+    overview?: string;
+    /** 概览后的附加段（如并发控制小节）。 */
+    appendix?: string;
+    /** 脚注段。 */
+    footnote?: string;
+}
+
+/**
+ * Render one report: 状态行 → 明细区 → 候选概览 → 脚注, blocks separated
+ * by blank lines. choices embeds the constraint with the `constraint: `
+ * prefix; other kinds wrap it in parens after the action phrase.
+ */
+export function renderPickModelReport(kind: ReportKind, parts: ReportParts, symbols: RenderSymbols): string {
+    const mark = kind === 'error'
+        ? symbols.error
+        : parts.status === 'error'
+            ? symbols.error
+            : parts.status === 'warning'
+                ? symbols.warning
+                : parts.status === 'success'
+                    ? symbols.success
+                    : symbols.selected;
+    const constraint = parts.constraint
+        ? (kind === 'choices' ? ` · constraint: ${parts.constraint}` : ` (${parts.constraint})`)
+        : '';
+    const blocks = [`${mark} ${parts.action}${constraint}`];
+    for (const detail of parts.detail ?? []) {
+        if (detail) blocks.push(detail);
+    }
+    if (parts.overview) blocks.push(parts.overview);
+    if (parts.appendix) blocks.push(parts.appendix);
+    if (parts.footnote) blocks.push(parts.footnote);
+    return blocks.join('\n\n');
+}