@aiwayds/dsh-topics-memory 0.6.0

package/lib/onboard.js

@@ -0,0 +1,664 @@
+/**
+ * `/topics onboard` — an a/b/c configuration wizard that walks a new user
+ * through the five decisions that matter (storage mode, GitHub repo, distill
+ * model, injection budget, auto-observe) one command at a time.
+ *
+ * Design (ADR 0009):
+ *  - one invocation = one step: the wizard renders the current question with
+ *    lettered options; the answer arrives as the next invocation's argument
+ *    (`/topics onboard b`). Works unchanged on every surface (tui, web, feishu,
+ *    headless one-shots) because it never needs intra-turn interactivity.
+ *  - answers accumulate in a pending batch; only the final confirm step
+ *    writes settings — quitting midway leaves the config untouched.
+ *  - the step machine is pure (`applyAnswer` / `renderStep`), so tests drive
+ *    it without spawning `gh`; the handler injects the login detector.
+ *
+ * @module onboard
+ */
+import { spawn } from 'node:child_process';
+import { pickLlmCandidate } from "./distill.js";
+import { CONFIG_KEYS, parseConfigValue } from "./config.js";
+/** CamelCase → dash-display, shared with /topics config rendering. */
+export function displayKey(key) {
+    return key.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+const FOOTER = '→ 回复 /topics onboard a|b|c（自定义项把值直接打在后面）；quit 退出不写入';
+/**
+ * Suggested remote repo name. Deliberately NOT `dsh-topics-memory`: that is
+ * the plugin's own source repository, and the default data repo must never
+ * collide with it (ADR 0002/0009).
+ */
+export const DEFAULT_TOPICS_REPO = 'dsh-topics-data';
+export function freshState() {
+    return { step: 'mode', pending: {}, pathHasRepo: false };
+}
+/** Human-facing step sequence for the progress marker, honoring the path taken. */
+function sequence(state) {
+    return state.pathHasRepo ? ['mode', 'repo', 'distill', 'inject', 'observe'] : ['mode', 'distill', 'inject', 'observe'];
+}
+function header(state, title) {
+    if (state.step === 'confirm')
+        return `🧭 topics 配置向导（确认）—— ${title}`;
+    const seq = sequence(state);
+    const index = seq.indexOf(state.step);
+    const total = seq.length;
+    const at = index === -1 ? total : index + 1;
+    return `🧭 topics 配置向导（${at}/${total}）—— ${title}`;
+}
+/** Render the current step against live config overlaid with pending answers. */
+export function renderStep(state, cfg) {
+    const cur = { ...cfg, ...state.pending };
+    switch (state.step) {
+        case 'mode':
+            return [
+                header(state, '存储模式'),
+                `当前：${cur.repo === '' ? 'local-only（数据只在本地 bundle）' : `GitHub 同步（${cur.repo}）`}`,
+                '  a. local-only —— 零配置零凭据，先本地用起来（推荐）',
+                '  b. GitHub 同步 —— 指定私有仓，写穿 + 去抖推送，跨机共享',
+                '  c. 跳过这项，保持现状',
+                '',
+                FOOTER,
+            ].join('\n');
+        case 'repo':
+            return [
+                header(state, 'GitHub 仓库'),
+                `当前：${cur.repo === '' ? '未设置' : cur.repo}`,
+                '  a. 自动探测 gh 登录名，仓库用 <登录名>/' + DEFAULT_TOPICS_REPO,
+                '  b. 自定义：把 owner/name 直接打在命令里，如 /topics onboard myname/my-wiki',
+                '  c. 跳过（留在 local-only）',
+                '',
+                FOOTER,
+            ].join('\n');
+        case 'distill':
+            return [
+                header(state, '后台蒸馏模型'),
+                `当前：${cur.distillProvider !== '' && cur.distillModel !== '' ? `${cur.distillProvider} / ${cur.distillModel}` : '未配置（观察只积累，不自动蒸馏成 Topic）'}`,
+                '  a. 暂不开 —— 先用一阵，随时 /topics set distill-provider 再开（推荐）',
+                '  b. 配置：把 provider model 打在命令里，如 /topics onboard zai-coding-cn glm-4.7-air（也支持 provider/model）',
+                '  c. 跳过',
+                '',
+                FOOTER,
+            ].join('\n');
+        case 'inject':
+            return [
+                header(state, '注入档位'),
+                `当前：topK ${cur.topK} / 总预算 ${cur.totalBudget} tok / 阈值 ${cur.matchThreshold}`,
+                `会话级去重：${cur.injectDedup ? '开（同会话已注入的 Topic 不重注）' : '关'}`,
+                '  a. 保守 —— topK 2，总预算 800 tok（少而准，token 敏感选这个）',
+                '  b. 标准 —— topK 4，总预算 1500 tok（默认，推荐）',
+                '  c. 放量 —— topK 6，总预算 2500 tok（记忆多、上下文宽裕）',
+                '',
+                FOOTER,
+            ].join('\n');
+        case 'observe':
+            return [
+                header(state, '自动观察'),
+                `当前：${cur.autoObserve ? `开（每轮自动抓原子观察，每侧 ≤${cur.observationMaxChars} 字）` : '关（只手动 topic_save / topic_observe）'}`,
+                '  a. 保持开（推荐）—— 随手聊就被记录，后台蒸馏成 Topic',
+                '  b. 关 —— 只在你明确调用工具时记录',
+                '  c. 跳过',
+                '',
+                FOOTER,
+            ].join('\n');
+        case 'confirm': {
+            const keys = CONFIG_KEYS.filter((k) => k in state.pending);
+            if (keys.length === 0) {
+                return '向导结束——本次没有选择任何改动，配置保持原样。\n重新 /topics onboard 可再来；/topics set 可微调单项。';
+            }
+            return [
+                header(state, '待写入 settings（topics namespace）'),
+                ...keys.map((k) => `  ${displayKey(k)} = ${String(state.pending[k])}`),
+                '（未列出的项保持现状）',
+                '',
+                '  a. 确认写入 —— 下次会话启动后生效',
+                '  b. 放弃，不写入任何改动',
+            ].join('\n');
+        }
+        case 'done':
+            return '向导已结束。重新 /topics onboard 可再来；/topics config 查看当前配置。';
+    }
+}
+/**
+ * Pure step machine: consume one answer, return the next state. The caller
+ * intercepts control answers (quit) and confirm-write before calling this.
+ */
+export function applyAnswer(state, answer, cfg) {
+    const letter = /^[a-c]$/i.exec(answer)?.[0]?.toLowerCase();
+    const next = (patch) => ({ ...state, ...patch });
+    switch (state.step) {
+        case 'mode': {
+            if (letter === 'b')
+                return { state: next({ step: 'repo', pathHasRepo: true }) };
+            if (letter === 'a' || letter === 'c')
+                return { state: next({ step: 'distill', pathHasRepo: false }) };
+            return { state, error: '请回复 a（local-only）、b（GitHub 同步）或 c（跳过）' };
+        }
+        case 'repo': {
+            if (letter === 'c')
+                return { state: next({ step: 'distill' }) };
+            const parsed = parseConfigValue('repo', answer);
+            if (typeof parsed === 'object' && parsed !== null && 'error' in parsed)
+                return { state, error: `${parsed.error}（或回复 c 跳过）` };
+            return { state: next({ step: 'distill', pending: { ...state.pending, repo: parsed } }) };
+        }
+        case 'distill': {
+            if (letter === 'a' || letter === 'c')
+                return { state: next({ step: 'inject' }) };
+            // Shared with the /topics set mixed-value split: space form wins so model
+            // ids may themselves contain slashes (`openrouter meta-llama/llama-3`).
+            const parsed = parseDistillInput(answer);
+            if ('error' in parsed)
+                return { state, error: parsed.error };
+            return { state: next({ step: 'inject', pending: { ...state.pending, distillProvider: parsed.provider, distillModel: parsed.model } }) };
+        }
+        case 'inject': {
+            if (letter === 'a')
+                return { state: next({ step: 'observe', pending: { ...state.pending, topK: 2, totalBudget: 800 } }) };
+            if (letter === 'b')
+                return { state: next({ step: 'observe', pending: { ...state.pending, topK: 4, totalBudget: 1500 } }) };
+            if (letter === 'c')
+                return { state: next({ step: 'observe' }) };
+            return { state, error: '请回复 a（保守）、b（标准）或 c（放量）' };
+        }
+        case 'observe': {
+            if (letter === 'a')
+                return { state: next({ step: 'confirm', pending: { ...state.pending, autoObserve: true } }) };
+            if (letter === 'b')
+                return { state: next({ step: 'confirm', pending: { ...state.pending, autoObserve: false } }) };
+            if (letter === 'c')
+                return { state: next({ step: 'confirm' }) };
+            return { state, error: '请回复 a（开）、b（关）或 c（跳过）' };
+        }
+        case 'confirm':
+            return { state, error: '确认页只认 a（写入）或 b（放弃）' };
+        case 'done':
+            return { state: freshState() };
+    }
+}
+/** Settings ops for the pending batch, in stable CONFIG_KEYS order. */
+export function confirmOps(pending) {
+    return CONFIG_KEYS.filter((k) => k in pending).map((k) => ({ op: 'set', path: [k], value: pending[k] }));
+}
+/**
+ * `gh api user --jq .login` with a hard timeout; undefined on any failure
+ * (gh missing, not logged in, slow). Never throws.
+ */
+export function detectGithubLogin(timeoutMs = 5000) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (login) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(login);
+        };
+        try {
+            const child = spawn('gh', ['api', 'user', '--jq', '.login'], { stdio: ['ignore', 'pipe', 'ignore'] });
+            let out = '';
+            child.stdout?.on('data', (chunk) => {
+                out += String(chunk);
+            });
+            const timer = setTimeout(() => {
+                child.kill('SIGKILL');
+                done(undefined);
+            }, timeoutMs);
+            child.on('error', () => {
+                clearTimeout(timer);
+                done(undefined);
+            });
+            child.on('close', (code) => {
+                clearTimeout(timer);
+                const login = out.trim();
+                done(code === 0 && /^[A-Za-z0-9-]+$/.test(login) ? login : undefined);
+            });
+        }
+        catch {
+            done(undefined);
+        }
+    });
+}
+const QUIT = /^(q|quit|exit|退出)$/i;
+/**
+ * First candidate with a non-empty live route table wins. Distinguishes
+ * 「有实例但列表空」(service present, zero enabled providers) from
+ * 「均不可用」(nothing reachable) so each gets its own user hint.
+ */
+export function pickLlmDirectory(candidates) {
+    const { llm, probed } = pickLlmCandidate(candidates, (providers) => providers.length > 0);
+    if (llm !== undefined)
+        return { kind: 'ok', llm: llm };
+    return probed > 0 ? { kind: 'empty-directory' } : { kind: 'no-instance' };
+}
+/** One-line why-not for the distill pick panels; undefined when usable. */
+export function llmDirectoryNotice(pick) {
+    if (pick.kind === 'ok')
+        return undefined;
+    if (pick.kind === 'empty-directory') {
+        return 'llm 服务在，但本机没有已启用的模型 provider（先在 dsh 配置中启用模型适配器）';
+    }
+    return '本机未检测到可用模型路由（llm 服务缺失或会话作用域已释放）';
+}
+/** Build one ask() closure that rides the invocation's agent/signal context. */
+export function makePanel(ask, agent, signal) {
+    return async (questions) => {
+        const r = await ask.ask({
+            questions,
+            ...(agent === undefined ? {} : { agent }),
+            ...(signal === undefined ? {} : { signal }),
+        });
+        // Normalize: tolerate providers that omit `selected` on pure-custom answers.
+        return (r.answers ?? []).map((a) => ({ ...a, selected: a.selected ?? [] }));
+    };
+}
+/** provider model（空格）或 provider/model（斜杠）；model 本身可含斜杠。 */
+export function parseDistillInput(raw) {
+    let provider;
+    let model;
+    if (/\s/.test(raw.trim())) {
+        const split = raw.trim().split(/\s+/);
+        provider = split[0] ?? '';
+        model = split.slice(1).join(' ');
+    }
+    else {
+        const slash = raw.indexOf('/');
+        provider = slash === -1 ? raw : raw.slice(0, slash);
+        model = slash === -1 ? '' : raw.slice(slash + 1);
+    }
+    provider = provider.trim();
+    model = model.trim();
+    if (provider === '' || model === '' || /\s/.test(provider) || /\s/.test(model)) {
+        return { error: '蒸馏模型格式：provider model（空格分隔）或 provider/model（斜杠分隔），如 zai-coding-cn glm-4.7-air' };
+    }
+    return { provider, model };
+}
+function answerFor(answers, id) {
+    return answers?.find((a) => a.id === id);
+}
+/** Blank item = the UI's "skipped" encoding: keep the current value. */
+export function isAnswered(a) {
+    return a !== undefined && !(a.selected.length === 0 && (a.custom === undefined || a.custom.trim() === ''));
+}
+/** Custom input wins over a selected option (both may arrive). */
+function pickText(a) {
+    return (a.custom !== undefined && a.custom.trim() !== '' ? a.custom : a.selected[0] ?? '').trim();
+}
+const SKIP_LABEL = '暂不启用蒸馏（跳过）';
+const MAX_PANEL_OPTIONS = 10;
+const MAX_MODEL_OPTIONS = 8;
+/** Safe catalog reads: the advisory directory must never break the wizard. */
+function safeProviders(llm) {
+    try {
+        return [...llm.listProviders()];
+    }
+    catch {
+        return [];
+    }
+}
+async function safeModels(llm, provider) {
+    try {
+        return [...(await llm.listModels(provider))];
+    }
+    catch {
+        return [];
+    }
+}
+/** Panel P — which provider owns the distill route? Options = live ids (+ skip in the wizard). */
+function distillProviderQuestion(llm, current, notice, header, withSkip) {
+    const providers = safeProviders(llm);
+    const listed = providers.slice(0, MAX_PANEL_OPTIONS - (withSkip ? 1 : 0));
+    return {
+        id: 'distill-provider',
+        header,
+        question: '后台蒸馏用哪个 provider？',
+        detail: [
+            `当前：${current === '' ? '未启用蒸馏（观察只积累，不自动蒸馏成 Topic）' : current}`,
+            ...(notice === undefined ? [] : [`⚠️ ${notice}`]),
+            ...(providers.length > listed.length ? [`共 ${providers.length} 个已启用 provider（列出前 ${listed.length}），其他选 Other 手输 provider id`] : []),
+        ].join('\n'),
+        options: [
+            ...listed.map((p) => ({ label: p.id, description: p.name })),
+            ...(withSkip ? [{ label: SKIP_LABEL, description: '先不启用蒸馏，随时 /topics set distill-provider 再开' }] : []),
+        ],
+    };
+}
+/** Panel M — which model on that provider? Options = top of the advisory catalog + custom. */
+async function distillModelQuestion(llm, provider, current, header, notice) {
+    const models = await safeModels(llm, provider);
+    const listed = models.slice(0, MAX_MODEL_OPTIONS);
+    return {
+        id: 'distill-model',
+        header,
+        question: `蒸馏用 ${provider} 的哪个 model？`,
+        detail: [
+            `当前 model：${current === '' ? '未设置' : current}`,
+            ...(notice === undefined ? [] : [`⚠️ ${notice}`]),
+            `该 provider 目录共 ${models.length} 个模型${models.length > listed.length ? `（列出前 ${listed.length}）` : ''}；目录仅供参考，其他选 Other 手输 model id`,
+        ].join('\n'),
+        options: listed.map((m) => ({ label: m.id, description: m.description === undefined ? m.name : `${m.name} — ${m.description}` })),
+    };
+}
+const WIZARD_HEADER = 'topics 配置向导（2/4）';
+const SET_HEADER = 'topics distill 配置';
+/**
+ * Two dependent panels — provider first, then that provider's models — so the
+ * model list can come from the chosen provider's catalog. Answers run through
+ * `resolveModelInfo` before entering the pending batch: NO_ADAPTER blocks and
+ * re-asks (bounded), any other rejection (model outside the advisory catalog,
+ * possibly still usable) warns but allows. Returns undefined when the user
+ * skips or blanks the panel (keep current).
+ */
+export async function askDistillRoute(llm, panel, cfg, maxAttempts = 3) {
+    let notice;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const pAnswers = await panel([distillProviderQuestion(llm, cfg.distillProvider, notice, WIZARD_HEADER, true)]);
+        const pPick = answerFor(pAnswers, 'distill-provider');
+        if (!isAnswered(pPick) || pickText(pPick) === SKIP_LABEL)
+            return undefined;
+        const provider = pickText(pPick);
+        const mAnswers = await panel([await distillModelQuestion(llm, provider, cfg.distillModel, WIZARD_HEADER)]);
+        const mPick = answerFor(mAnswers, 'distill-model');
+        if (!isAnswered(mPick))
+            return undefined;
+        const model = pickText(mPick);
+        try {
+            await llm.resolveModelInfo(provider, model);
+            return { provider, model, unknownModel: false };
+        }
+        catch (error) {
+            if (error.code === 'NO_ADAPTER') {
+                notice = `provider ${provider} 当前没有可用的模型路由，请重新选择`;
+                continue;
+            }
+            // Non-NO_ADAPTER failure: the catalog is advisory — warn, allow.
+            return { provider, model, unknownModel: true };
+        }
+    }
+    throw new Error(`多次选择仍没有可用的模型路由（${notice ?? 'NO_ADAPTER'}），未写入任何改动；请确认 provider 已启用后重试 /topics onboard`);
+}
+/**
+ * Single-panel variant behind `/topics set distill-provider|distill-model`:
+ * one question, current value shown, blank answer = keep. Validation mirrors
+ * the wizard (`askDistillRoute`): a provider pick must sit in the live route
+ * table (the NO_ADAPTER equivalent — blocked, bounded re-ask); a model pick
+ * runs through `resolveModelInfo` — NO_ADAPTER blocks, any other failure
+ * warns but allows (model outside the advisory catalog, possibly still
+ * usable). Returns the picked value (plus the warning when a failed check was
+ * allowed through), or undefined on skip/blank.
+ */
+export async function askDistillSingle(llm, panel, key, cfg, maxAttempts = 3) {
+    let notice;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const question = key === 'distill-provider'
+            ? distillProviderQuestion(llm, cfg.distillProvider, notice, SET_HEADER, false)
+            : await distillModelQuestion(llm, cfg.distillProvider, cfg.distillModel, SET_HEADER, notice);
+        const a = answerFor(await panel([question]), question.id);
+        if (!isAnswered(a) || pickText(a) === SKIP_LABEL)
+            return undefined;
+        const value = pickText(a);
+        if (key === 'distill-provider') {
+            // Custom ids must still be a live route — the NO_ADAPTER equivalent.
+            if (safeProviders(llm).some((p) => p.id === value))
+                return { value };
+            notice = `provider ${value} 当前没有可用的模型路由，请重新选择`;
+            continue;
+        }
+        try {
+            await llm.resolveModelInfo(cfg.distillProvider, value);
+            return { value };
+        }
+        catch (error) {
+            if (error.code === 'NO_ADAPTER') {
+                notice = `provider ${cfg.distillProvider} 当前没有可用的模型路由，请重新选择`;
+                continue;
+            }
+            return {
+                value,
+                warning: `${value} 未通过 ${cfg.distillProvider} 的模型目录校验（模型目录外，可能仍可用），已放行；若实际不可用可再改`,
+            };
+        }
+    }
+    throw new Error('多次选择仍没有可用的模型路由，未写入任何改动；请确认 provider 已启用后重试');
+}
+/**
+ * The interactive flow: storage mode, then the distill route as two dependent
+ * panels (provider → that provider's models), then a batched panel (repo when
+ * GitHub mode, inject tier, observe), then a confirm panel whose detail lists
+ * exactly what will be written. A closed panel or a skipped question never
+ * writes. Hosts without the llm directory never enter here (the handler gates
+ * on it and falls back to the typed wizard).
+ */
+export async function runInteractiveOnboard(service, mutate, ask, detectLogin, agent, signal, llm) {
+    const ok = (text) => ({ kind: 'success', text });
+    const fail = (text) => ({ kind: 'error', text });
+    const panel = makePanel(ask, agent, signal);
+    try {
+        const cfg = service.cfg;
+        // Stage 1 — storage mode (its own panel: the batch depends on it).
+        const modeAnswers = await panel([{
+                id: 'mode',
+                header: 'topics 配置向导（1/4）',
+                question: 'Topic 记忆存在哪里？',
+                detail: `当前：${cfg.repo === '' ? 'local-only' : `GitHub 同步（${cfg.repo}）`}`,
+                options: [
+                    { label: 'local-only', description: '零配置零凭据，数据只在本地 bundle（推荐）' },
+                    { label: 'GitHub 同步', description: '指定私有仓，写穿 + 去抖推送，跨机共享' },
+                ],
+            }]);
+        const modePick = answerFor(modeAnswers, 'mode');
+        if (!isAnswered(modePick))
+            return ok('向导结束——未选择存储模式，配置保持原样。');
+        const githubMode = (modePick.selected[0] ?? '').includes('GitHub');
+        // Stage 2 — the distill route: two dependent asks (the model list comes
+        // from the chosen provider's catalog), pre-validated via resolveModelInfo.
+        const route = await askDistillRoute(llm, panel, cfg);
+        // Stage 3 — the remaining decisions in one batched panel (tabs / pager).
+        const questions = [];
+        let suggestedRepo;
+        if (githubMode) {
+            const login = await detectLogin();
+            if (login !== undefined)
+                suggestedRepo = `${login}/${DEFAULT_TOPICS_REPO}`;
+            questions.push({
+                id: 'repo',
+                header: 'topics 配置向导（3/4）',
+                question: 'GitHub 仓库（owner/name）？',
+                detail: `留空跳过 = 留在 local-only。默认建议 ${suggestedRepo ?? `${DEFAULT_TOPICS_REPO}（gh 登录名探测失败，请选 Other 输入完整 owner/name）`}`,
+                ...(suggestedRepo === undefined ? {} : { options: [{ label: suggestedRepo, description: '自动探测的 gh 登录名 + 默认仓库名' }] }),
+            });
+        }
+        questions.push({
+            id: 'inject',
+            header: 'topics 配置向导（3/4）',
+            question: '注入档位？',
+            detail: `当前：topK ${cfg.topK} / 总预算 ${cfg.totalBudget} tok / 阈值 ${cfg.matchThreshold}；会话级去重${cfg.injectDedup ? '开（同会话已注入不重注）' : '关'}`,
+            options: [
+                { label: '保守（topK 2 · 800 tok）', description: '少而准，token 敏感选这个' },
+                { label: '标准（topK 4 · 1.5k tok）', description: '默认档（推荐）' },
+                { label: '放量（topK 6 · 2.5k tok）', description: '记忆多、上下文宽裕' },
+            ],
+        }, {
+            id: 'observe',
+            header: 'topics 配置向导（3/4）',
+            question: '自动观察？',
+            detail: `当前：${cfg.autoObserve ? `开（每轮自动抓原子观察，每侧 ≤${cfg.observationMaxChars} 字）` : '关（只手动 topic_save / topic_observe）'}`,
+            options: [
+                { label: '保持开（推荐）', description: '随手聊就被记录，后台蒸馏成 Topic' },
+                { label: '关闭', description: '只在你明确调用工具时记录' },
+            ],
+        });
+        const batchAnswers = await panel(questions);
+        // Collect into the same pending batch the typed wizard confirms with.
+        const pending = {};
+        if (githubMode) {
+            const a = answerFor(batchAnswers, 'repo');
+            if (isAnswered(a)) {
+                const raw = (a.custom !== undefined && a.custom.trim() !== '' ? a.custom : a.selected[0] ?? '').trim();
+                const parsed = parseConfigValue('repo', raw);
+                if (typeof parsed === 'object' && parsed !== null && 'error' in parsed) {
+                    return fail(`${parsed.error}\n未写入任何改动；稍后可用 /topics set repo <owner/name> 单独设置。`);
+                }
+                pending.repo = parsed;
+            }
+        }
+        if (route !== undefined) {
+            pending.distillProvider = route.provider;
+            pending.distillModel = route.model;
+        }
+        const inject = answerFor(batchAnswers, 'inject');
+        if (isAnswered(inject)) {
+            const label = inject.selected[0] ?? '';
+            if (label.includes('保守')) {
+                pending.topK = 2;
+                pending.totalBudget = 800;
+            }
+            else if (label.includes('放量')) {
+                pending.topK = 6;
+                pending.totalBudget = 2500;
+            }
+            else {
+                pending.topK = 4;
+                pending.totalBudget = 1500;
+            }
+        }
+        const observe = answerFor(batchAnswers, 'observe');
+        if (isAnswered(observe))
+            pending.autoObserve = (observe.selected[0] ?? '').includes('关闭') ? false : true;
+        const ops = confirmOps(pending);
+        if (ops.length === 0)
+            return ok('向导结束——本次没有选择任何改动，配置保持原样。');
+        // Stage 4 — confirm with the exact write set in the detail.
+        const keys = CONFIG_KEYS.filter((k) => k in pending);
+        const confirmAnswers = await panel([{
+                id: 'confirm',
+                header: 'topics 配置向导（4/4）',
+                question: `写入这 ${ops.length} 项配置？（下次会话启动后生效）`,
+                detail: [
+                    ...keys.map((k) => `- ${displayKey(k)} = ${String(pending[k])}`),
+                    ...(route?.unknownModel === true ? [`- ⚠️ ${route.model} 未通过 ${route.provider} 的模型目录校验（模型目录外，可能仍可用）——已放行，若实际不可用可再改`] : []),
+                ].join('\n'),
+                options: [
+                    { label: '写入', description: '批量写入 settings（topics namespace）' },
+                    { label: '放弃', description: '不写入任何改动' },
+                ],
+            }]);
+        const confirmPick = answerFor(confirmAnswers, 'confirm');
+        if (!isAnswered(confirmPick) || (confirmPick.selected[0] ?? '').includes('放弃')) {
+            return ok('已放弃，未写入任何改动。随时 /topics onboard 重新开始。');
+        }
+        try {
+            await mutate(ops);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return fail(`写入 settings 失败：${message}`);
+        }
+        if (pending.repo !== undefined || pending.autoInject !== undefined)
+            service.invalidate();
+        return ok([
+            `✅ 已写入 topics 配置（${ops.length} 项）：`,
+            ...keys.map((k) => `  ${displayKey(k)} = ${String(pending[k])}`),
+            '下次会话启动后生效。',
+            '之后：/topics status 看健康；/topics stats 看注入命中；会话里说「记住…」就会沉淀 Topic。',
+        ].join('\n'));
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ASK_CANCELLED' || code === 'ASK_ABORTED') {
+            return ok('已取消配置向导，未写入任何改动。随时 /topics onboard 重新开始。');
+        }
+        if (code === 'ASK_MISSING_AGENT') {
+            return fail('当前 surface 的 ask-user 需要会话上下文，无法从命令发起。请改用 /topics set，或在 TUI / 浏览器会话里重跑 /topics onboard。');
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        return fail(`配置向导中断：${message}\n未写入任何改动。`);
+    }
+}
+/**
+ * The `/topics onboard <args>` handler. One instance per command registration —
+ * wizard state lives in the closure, so tests get a fresh wizard per
+ * buildTopicsCommand() and concurrent surfaces don't share progress.
+ *
+ * Primary path is the native ask-user seam when BOTH providers are present:
+ * `resolveAsk()` (TUI panel, web composer, feishu card — whichever surface
+ * owns the slot, with dsh-ask-router optionally fanning out) and a usable
+ * `resolveLlm()` candidate (the first with a non-empty live route table,
+ * feeding the distill provider/model panels). Either one missing — bare
+ * hosts, no UI, no model route — falls back to the typed wizard.
+ */
+export function createOnboardHandler(service, mutate, detectLogin = detectGithubLogin, resolveAsk = () => undefined, resolveLlm = () => []) {
+    let state = freshState();
+    const ok = (text) => ({ kind: 'success', text });
+    const fail = (text) => ({ kind: 'error', text });
+    const advance = (answer) => {
+        const r = applyAnswer(state, answer, service.cfg);
+        if (r.error !== undefined)
+            return fail(`${r.error}\n\n${renderStep(state, service.cfg)}`);
+        state = r.state;
+        return ok(renderStep(state, service.cfg));
+    };
+    return async (args, invocation) => {
+        const input = args.join(' ').trim();
+        if (input === '') {
+            // Bare `/topics onboard` with a live ask-user provider AND a usable llm
+            // directory (first candidate with a non-empty route table) opens the
+            // native panel flow; explicit args always mean typed-wizard answers.
+            const askService = resolveAsk();
+            const pick = pickLlmDirectory(resolveLlm());
+            if (askService !== undefined && typeof askService.ask === 'function' && pick.kind === 'ok') {
+                const invocationLike = invocation;
+                return runInteractiveOnboard(service, mutate, askService, detectLogin, invocationLike.agent, invocationLike.signal, pick.llm);
+            }
+            if (state.step === 'done')
+                state = freshState();
+            // Typed fallback; when only the model route is missing, say why the
+            // pick panels did not open.
+            const notice = llmDirectoryNotice(pick);
+            return ok(notice === undefined ? renderStep(state, service.cfg) : `${notice}\n${renderStep(state, service.cfg)}`);
+        }
+        if (QUIT.test(input)) {
+            state = freshState();
+            return ok('已退出配置向导，未写入任何改动。随时 /topics onboard 重新开始。');
+        }
+        if (state.step === 'done')
+            state = freshState();
+        if (state.step === 'confirm') {
+            const ops = confirmOps(state.pending);
+            if (ops.length === 0) {
+                state = freshState();
+                return ok('向导结束——本次没有选择任何改动，配置保持原样。随时 /topics onboard 重新开始。');
+            }
+            if (/^a$/i.test(input)) {
+                try {
+                    await mutate(ops);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    return fail(`写入 settings 失败：${message}\n\n${renderStep(state, service.cfg)}`);
+                }
+                if (ops.some((o) => o.path[0] === 'repo' || o.path[0] === 'autoInject'))
+                    service.invalidate();
+                const keys = ops.map((o) => `  ${displayKey(String(o.path[0]))} = ${String(o.value)}`);
+                state = freshState();
+                return ok([
+                    `✅ 已写入 topics 配置（${ops.length} 项）：`,
+                    ...keys,
+                    '下次会话启动后生效。',
+                    '之后：/topics status 看健康；/topics stats 看注入命中；会话里说「记住…」就会沉淀 Topic。',
+                ].join('\n'));
+            }
+            if (/^b$/i.test(input)) {
+                state = freshState();
+                return ok('已放弃，未写入任何改动。随时 /topics onboard 重新开始。');
+            }
+            return fail(`确认页只认 a（写入）或 b（放弃）。\n\n${renderStep(state, service.cfg)}`);
+        }
+        if (state.step === 'repo' && /^a$/i.test(input)) {
+            const login = await detectLogin();
+            if (login === undefined) {
+                return fail('探测 gh 登录名失败（gh 未登录或不可用）。直接输入 owner/name，或回复 c 跳过。');
+            }
+            return advance(`${login}/${DEFAULT_TOPICS_REPO}`);
+        }
+        return advance(input);
+    };
+}