agentic-flow-kit 2.0.0 → 2.1.0

package/src/tui/flows.mjs

@@ -0,0 +1,306 @@
+// TUI 业务流：安装 / 升级 / 追加宿主 / 体检 / 宿主列表，以及 FLOWS 派发表。
+// 只经 prompts 层问答、screen.print 输出与各 command 入口执行，不直接触碰终端状态。
+import { visualWidth, box, green, red, progressLine } from './ansi.mjs';
+import { pickOne, pickMany, confirmYes, showLines, askText } from './prompts.mjs';
+import { HOSTS, HOST_NAMES } from '../hosts/registry.mjs';
+import { probeModels } from '../models/probe.mjs';
+import { ROLE_NAMES, loadRoleConfig, recommendRoles, summarizeModels } from '../models/resolve.mjs';
+import { readManifest } from '../install/manifest.mjs';
+import { detectStackDetail, STACKS, stackMarkerLabel, formatInstallLog, installLogNotable, installCommand } from '../commands/install.mjs';
+import { stackDescription } from '../render/tokens.mjs';
+import { LANGUAGES } from '../i18n.mjs';
+import { doctorCommand } from '../commands/doctor.mjs';
+import { addHostCommand } from '../commands/add-host.mjs';
+import { upgradeCommand } from '../commands/upgrade.mjs';
+
+// flows 内部 argv 统一经 baseArgs 构造（形状与 cli/args.mjs parseArgs 一致：flag() 依赖 args.flags）
+export const baseArgs = () => ({ _: [], agents: [], flags: new Set() });
+
+function fileOf(msg) {
+  const text = String(msg ?? '');
+  const i = text.indexOf('（');
+  return (i >= 0 ? text.slice(0, i) : text).trim();
+}
+
+function clip(text, max) {
+  if (visualWidth(text) <= max) return text;
+  let out = '';
+  let width = 0;
+  for (const ch of text) {
+    const w = visualWidth(ch);
+    if (width + w > max - 1) return `${out}…`;
+    out += ch;
+    width += w;
+  }
+  return out;
+}
+
+// 常规创建/更新只留在进度条上。冲突和非常规跳过先换行落盘，避免被下一帧 \\r 清掉。
+export function installProgressWrites({ action, msg, done, total }) {
+  const writes = [];
+  if (installLogNotable(action, msg)) {
+    const text = formatInstallLog(action, msg);
+    writes.push(`\r\x1b[2K${action === 'conflict' ? red(text) : text}\n`);
+  }
+  const detail = clip(formatInstallLog(action, fileOf(msg)), 48);
+  const line = progressLine(done, total, detail);
+  writes.push(done === total ? `${line}\n` : line);
+  return writes;
+}
+
+// 栈菜单：名称在 label，hint 带典型标记与描述。命中项改写为实际文件名。
+export function stackItems({ detected, current, lang, t }) {
+  return STACKS.map((stack) => {
+    const matched = detected?.stack === stack;
+    const tags = [];
+    if (current && stack === current) tags.push(t('tui.currentStack'));
+    if (matched && detected.file) tags.push(t('tui.detectedFile', { file: detected.file }));
+    else if (matched) tags.push(t('tui.detected'));
+    else {
+      const marker = stackMarkerLabel(stack);
+      if (marker) tags.push(marker);
+    }
+    const hint = [...tags, stackDescription(stack, lang)].filter(Boolean).join(' · ');
+    return { value: stack, label: t(`tui.stack.${stack}`), hint };
+  });
+}
+
+// 宿主候选项单一映射：已安装的提示「已安装」，否则提示 label → dir
+function hostItems({ installed = [], t }) {
+  return HOST_NAMES.map((n) => ({
+    value: n,
+    label: n,
+    hint: installed.includes(n) ? t('tui.installed') : `${HOSTS[n].label} → ${HOSTS[n].dir}`,
+    checked: installed.includes(n),
+  }));
+}
+
+// 模型配置流：静态探测 → 可选只读 CLI 探测 → 推荐确认 / 逐角色选择（含手填、inherit、跳过）。
+async function modelFlow(ctx, hosts) {
+  const { t } = ctx;
+  const cwd = process.cwd();
+  const roleConfig = loadRoleConfig(cwd);
+  const models = {};
+  let explicit = false;
+
+  for (const host of hosts) {
+    const h = HOSTS[host];
+    if (!h?.agents?.modelField) continue;
+
+    let candidates = probeModels({ host, target: cwd, allowCli: false });
+    if (!candidates.length && (h.modelProbe?.cli || []).length) {
+      const allow = await confirmYes(ctx, t('tui.model.allowProbe', { host }));
+      if (allow === null) return null;
+      if (allow) candidates = probeModels({ host, target: cwd, allowCli: true });
+    }
+
+    const recommended = recommendRoles({ host, candidates, roleConfig });
+    const hasRecommended = ROLE_NAMES.some((role) => recommended[role]);
+    let useRecommended = false;
+    if (hasRecommended) {
+      useRecommended = await confirmYes(ctx, t('tui.model.useRecommended', { host }));
+      if (useRecommended === null) return null;
+    }
+    if (useRecommended) {
+      models[host] = recommended;
+      continue;
+    }
+
+    explicit = true;
+    const values = {};
+    for (const role of ROLE_NAMES) {
+      const items = candidates.map((c) => ({ value: c.id, label: c.id, hint: c.source }));
+      if (recommended[role] && !items.some((it) => it.value === recommended[role])) {
+        items.push({ value: recommended[role], label: recommended[role], hint: t('tui.model.recommended') });
+      }
+      if (h.agents.inheritValue) items.push({ value: h.agents.inheritValue, label: t('tui.model.inherit') });
+      items.push({ value: '__manual__', label: t('tui.model.manual') });
+      items.push({ value: '__skip__', label: t('tui.model.skip') });
+
+      const choice = await pickOne(ctx, {
+        question: t('tui.model.role', { role: t(`tui.model.role.${role}`) }),
+        hint: t('tui.hint.moveEnter'),
+        items,
+      });
+      if (choice === null) return null;
+      if (choice === '__skip__') {
+        values[role] = '__none__';
+      } else if (choice === '__manual__') {
+        const value = await askText(ctx, {
+          question: t('tui.model.manualPrompt'),
+          validate: (v) => (String(v).trim() ? null : t('tui.model.invalid')),
+        });
+        if (value === null) return null;
+        values[role] = value.trim();
+      } else {
+        values[role] = choice;
+      }
+    }
+    // 跳过 / inherit 不是具体模型，不触发同模型告警。
+    const concrete = (v) => Boolean(v) && v !== '__none__' && v !== h.agents.inheritValue;
+    if (concrete(values.review) && concrete(values.code) && values.review === values.code) {
+      showLines(ctx, [red(t('tui.model.sameAsCode'))]);
+    }
+    models[host] = values;
+  }
+
+  return { models, explicit };
+}
+
+// 安装流：宿主 → 语言 → 栈 → 模型 → 开关 → 计划确认 → 执行（进度行）→ 可选体检
+async function installFlow(ctx) {
+  const { screen, t, lang } = ctx;
+  const cwd = process.cwd();
+  const prev = readManifest(cwd);
+  const prevHosts = Array.isArray(prev && prev.hosts) ? prev.hosts : [];
+
+  const hosts = await pickMany(ctx, {
+    question: t('tui.hostsQuestion'),
+    hint: t('tui.hint.toggle'),
+    min: 1,
+    items: hostItems({ installed: prevHosts, t }),
+  });
+  if (hosts === null) return;
+
+  const selLang = await pickOne(ctx, {
+    question: t('tui.langQuestion'),
+    hint: t('tui.hint.moveEnter'),
+    items: LANGUAGES.map((l) => ({ value: l, label: l })),
+  });
+  if (selLang === null) return;
+
+  const detected = detectStackDetail(cwd);
+  const stack = await pickOne(ctx, {
+    question: t('tui.stackQuestion'),
+    hint: t('tui.hint.moveEnter'),
+    cursor: Math.max(0, STACKS.indexOf(detected.stack)),
+    items: stackItems({ detected, lang, t }),
+  });
+  if (stack === null) return;
+
+  const modelResult = await modelFlow(ctx, hosts);
+  if (modelResult === null) return;
+
+  const opts = await pickMany(ctx, {
+    question: t('tui.optsQuestion'),
+    hint: t('tui.hint.toggle'),
+    min: 0,
+    items: [
+      { value: 'git-config', label: t('tui.opt.gitConfig'), checked: true },
+      { value: 'dry-run', label: t('tui.opt.dryRun') },
+      { value: 'force', label: t('tui.opt.force') },
+    ],
+  });
+  if (opts === null) return;
+
+  const dryRun = opts.includes('dry-run');
+  // argv 形状与 wizard.mjs buildInstallArgs 一致：git 配置默认开，开关转 flags
+  const args = { ...baseArgs(), _: ['install'], agents: hosts, lang: selLang, stack };
+  if (modelResult.models && Object.keys(modelResult.models).length) args.tuiModels = modelResult.models;
+  if (!opts.includes('git-config')) args.flags.add('no-git-config');
+  if (dryRun) args.flags.add('dry-run');
+  if (opts.includes('force')) args.flags.add('force');
+
+  const planLines = [
+    t('tui.plan.target', { target: cwd }),
+    t('tui.plan.hosts', { hosts: hosts.join(', ') }),
+    t('tui.plan.lang', { lang: selLang }),
+    t('tui.plan.stack', { stack }),
+  ];
+  if (modelResult.models && Object.keys(modelResult.models).length) {
+    planLines.push(t('tui.plan.models', { models: summarizeModels({ hosts: modelResult.models }) }));
+  }
+  showLines(ctx, box(t('tui.planTitle'), planLines));
+  if (!(await confirmYes(ctx, t('tui.confirmInstall')))) return;
+
+  screen.print(t('tui.running') + '\n');
+  // 进度回调契约 (action, msg, done, total)：进度条带当前文件；冲突与非常规跳过单独留行。
+  await installCommand({
+    args,
+    t,
+    lang: selLang,
+    onLog: (action, msg, done, total) => {
+      for (const chunk of installProgressWrites({ action, msg, done, total })) screen.output.write(chunk);
+    },
+  });
+  // dry-run 未写盘，完成文案须区分，避免误导
+  screen.print(green(`✓ ${t(dryRun ? 'tui.dryDone' : 'tui.done')}`) + '\n');
+
+  screen.print('');
+  if (await confirmYes(ctx, t('tui.askDoctor'))) {
+    return doctorCommand({ args: { deep: false }, t, lang: selLang });
+  }
+}
+
+async function upgradeFlow(ctx) {
+  const { t, lang } = ctx;
+  const cwd = process.cwd();
+  const manifest = readManifest(cwd);
+  if (!manifest) throw new Error(t('error.noManifest'));
+  const recorded = STACKS.includes(manifest.stack) ? manifest.stack : 'empty';
+  const detected = detectStackDetail(cwd);
+  const stack = await pickOne(ctx, {
+    question: t('tui.upgradeStackQuestion'),
+    hint: t('tui.hint.moveEnter'),
+    cursor: Math.max(0, STACKS.indexOf(recorded)),
+    items: stackItems({ detected, current: recorded, lang, t }),
+  });
+  if (stack === null) return;
+  showLines(ctx, box(t('tui.planTitle'), [
+    t('tui.plan.hosts', { hosts: (manifest.hosts || []).join(', ') }),
+    t('tui.plan.lang', { lang: manifest.language || lang }),
+    t('tui.plan.stack', { stack }),
+  ]));
+  if (!(await confirmYes(ctx, t('tui.confirmUpgrade')))) return;
+  return upgradeCommand({ args: { ...baseArgs(), stack }, t, lang });
+}
+
+async function addHostFlow(ctx) {
+  const { t, lang } = ctx;
+  const manifest = readManifest(process.cwd());
+  if (!manifest) throw new Error(t('error.noManifest'));
+  const installed = Array.isArray(manifest.hosts) ? manifest.hosts : [];
+  const agents = await pickMany(ctx, {
+    question: t('tui.addHostQuestion'),
+    hint: t('tui.hint.toggle'),
+    min: 1,
+    items: hostItems({ installed, t }),
+  });
+  if (agents === null) return;
+  const modelResult = await modelFlow(ctx, agents);
+  if (modelResult === null) return;
+  const args = { ...baseArgs(), _: ['add-host'], agents };
+  if (modelResult.models && Object.keys(modelResult.models).length) args.tuiModels = modelResult.models;
+  return addHostCommand({ args, t, lang });
+}
+
+async function doctorFlow(ctx) {
+  const { t, lang } = ctx;
+  const deep = await pickOne(ctx, {
+    question: t('tui.doctorQuestion'),
+    hint: t('tui.hint.moveEnter'),
+    items: [
+      { value: false, label: t('tui.doctor.normal') },
+      { value: true, label: t('tui.doctor.deep') },
+    ],
+  });
+  if (deep === null) return;
+  return doctorCommand({ args: { deep }, t, lang });
+}
+
+function listHostsFlow(ctx) {
+  const { t } = ctx;
+  const rows = HOST_NAMES.map((n) => ({ name: n, label: HOSTS[n].label, dir: HOSTS[n].dir }));
+  const wName = Math.max(...rows.map((r) => visualWidth(r.name)));
+  const wLabel = Math.max(...rows.map((r) => visualWidth(r.label)));
+  const pad = (s, w) => s + ' '.repeat(w - visualWidth(s) + 2);
+  showLines(ctx, box(t('listHosts.title'), rows.map((r) => `${pad(r.name, wName)}${pad(r.label, wLabel)}${r.dir}`)));
+}
+
+export const FLOWS = {
+  install: installFlow,
+  upgrade: upgradeFlow,
+  'add-host': addHostFlow,
+  doctor: doctorFlow,
+  'list-hosts': listHostsFlow,
+};

package/src/tui/prompts.mjs

@@ -0,0 +1,139 @@
+// 问答原语层：交互路径走 keypress widget（经 screen.mjs 的 runPrompt），
+// 非交互终端降级为「编号 + 回车」读行问答。本层只经 screen 输出，不直接触碰终端状态。
+import { box, dim, red } from './ansi.mjs';
+import { createSelect, createMultiSelect, createConfirm, createTextInput } from './widgets.mjs';
+import { runPrompt } from './screen.mjs';
+
+// 降级问答原语：每轮打印「题干 + 选项行 + 行内提示」→ 读一行 → parse 裁决。
+// parse 返回 { value } 结束；{ error } 红字重试；{ silent } 静默重印（如切换勾选后刷新行）；
+// undefined 视为非法输入，红字提示后重试。EOF（stdin 关闭）一律返回 null。
+async function askLine(ctx, { question = '', rows = () => [], prompt, parse }) {
+  const { screen, t, reader } = ctx;
+  while (true) {
+    const lines = [...(question ? [question] : []), ...rows()];
+    if (lines.length) screen.output.write(lines.join('\n') + '\n');
+    screen.output.write(prompt);
+    const line = await reader();
+    if (line === null) return null;
+    const result = parse(line.trim());
+    if (result === undefined) screen.output.write(`${red(t('tui.invalidNumber'))}\n`);
+    else if (result.error) screen.output.write(`${red(result.error)}\n`);
+    else if (!result.silent) return result.value;
+  }
+}
+
+// 降级三问：只保留 rows 生成与 parse，循环/读行/EOF/重试归 askLine
+async function askSelectDegraded(ctx, { question, items }) {
+  const { t } = ctx;
+  return askLine(ctx, {
+    question,
+    rows: () => items.map((it, i) => `  ${i + 1}. ${it.label}${it.hint ? `  ${dim(it.hint)}` : ''}`),
+    prompt: `${t('tui.inputNumber')} `,
+    parse: (s) => {
+      const idx = Number(s) - 1;
+      return Number.isInteger(idx) && idx >= 0 && idx < items.length ? { value: items[idx].value } : undefined;
+    },
+  });
+}
+
+async function askMultiSelectDegraded(ctx, { question, items, min = 1 }) {
+  const { t } = ctx;
+  const checked = items.map((it) => it.checked === true);
+  return askLine(ctx, {
+    question,
+    rows: () => items.map((it, i) => `  ${i + 1}. [${checked[i] ? 'x' : ' '}] ${it.label}${it.hint ? `  ${dim(it.hint)}` : ''}`),
+    prompt: `${t('tui.toggleNumber')} `,
+    parse: (s) => {
+      if (s === '') {
+        const value = items.filter((_, i) => checked[i]).map((it) => it.value);
+        return value.length < min ? { error: t('tui.minSelection', { min }) } : { value };
+      }
+      const idx = Number(s) - 1;
+      if (Number.isInteger(idx) && idx >= 0 && idx < items.length) {
+        checked[idx] = !checked[idx];
+        return { silent: true };
+      }
+      return undefined;
+    },
+  });
+}
+
+async function askConfirmDegraded(ctx, label, defaultYes = true) {
+  return askLine(ctx, {
+    prompt: `${label} ${defaultYes ? '[Y/n]' : '[y/N]'} `,
+    parse: (s) => {
+      if (!s) return { value: defaultYes };
+      if (s === 'y' || s === 'yes') return { value: true };
+      if (s === 'n' || s === 'no') return { value: false };
+      return undefined; // 非法输入红字提示后重试（原为静默重印，统一归 askLine）
+    },
+  });
+}
+
+// 交互 / 降级统一入口；降级路径 EOF 一律返回 null
+export function pickOne(ctx, { question, hint, items, cursor = 0 }) {
+  const { screen, t } = ctx;
+  if (screen.interactive) {
+    return runPrompt(screen, { title: t('tui.title'), question, hint, widget: createSelect({ items, cursor }) });
+  }
+  return askSelectDegraded(ctx, { question, items });
+}
+
+export function pickMany(ctx, { question, hint, items, min = 1 }) {
+  const { screen, t } = ctx;
+  if (screen.interactive) {
+    return runPrompt(screen, {
+      title: t('tui.title'),
+      question,
+      hint,
+      widget: createMultiSelect({ items, min, minMessage: t('tui.minSelection', { min }) }),
+    });
+  }
+  return askMultiSelectDegraded(ctx, { question, items, min });
+}
+
+export function confirmYes(ctx, label, defaultYes = true) {
+  const { screen, t } = ctx;
+  if (screen.interactive) {
+    return runPrompt(screen, {
+      title: t('tui.title'),
+      question: label,
+      hint: t('tui.hint.moveEnter'),
+      widget: createConfirm({ yesLabel: t('tui.yes'), noLabel: t('tui.no'), defaultYes }),
+    });
+  }
+  return askConfirmDegraded(ctx, label, defaultYes);
+}
+
+export function askText(ctx, { question, hint, initial = '', placeholder = '', validate = () => null }) {
+  const { screen, t } = ctx;
+  if (screen.interactive) {
+    return runPrompt(screen, {
+      title: t('tui.title'),
+      question,
+      hint: hint || t('tui.hint.typeEnter'),
+      widget: createTextInput({ initial, placeholder, validate }),
+    });
+  }
+  return askLine(ctx, {
+    question,
+    rows: () => (placeholder ? [dim(placeholder)] : []),
+    prompt: `${t('tui.hint.typeEnter')} `,
+    parse: (s) => {
+      const err = validate(s);
+      return err ? { error: err } : { value: s };
+    },
+  });
+}
+
+export function showLines(ctx, lines) {
+  if (ctx.screen.interactive) ctx.screen.render(lines);
+  else ctx.screen.output.write(lines.join('\n') + '\n');
+}
+
+export function showError(ctx, err) {
+  const { t } = ctx;
+  const message = err && err.message ? err.message : String(err);
+  // 多行 message 先拆行再进 box，避免转义后残影错位
+  showLines(ctx, box(t('tui.errorTitle'), message.split('\n').map(red)));
+}

package/src/tui/screen.mjs

@@ -0,0 +1,217 @@
+// 终端屏幕层：全仓唯一接触 stdin/stdout 的地方（终端状态机 + IO）。
+// render 记住上次行数，重绘时上移清行重写（行数变化会清残留行）；print 重置渲染原点后写原始输出，
+// 供 flows 在命令输出推进过光标时新起一块，无需感知光标行数协议。
+// 降级模式在 setRawMode 不可用或非 TTY 直调时进入：交互全部改走「编号 + 回车」问答（prompts.mjs）。
+// 视口高度裁剪明确不做：内容有界（最多 10 宿主选项 + 提示行），裁剪反而引入滚动定位复杂度。
+// 交互按键弃用内置 readline.emitKeypressEvents、改用自研解码器（attachKeyDecoder）：内置解码器在部分
+// Windows 终端 / Node 组合下对分片到达与 SS3 序列产出 undefined key（方向键 ↑↓ 失效），且事件契约不变。
+// 解码器不监听 stdin close：真实 EOF 由上层兜底（runPrompt 的 close → QuitError、降级路径的 eof），
+// 虚假 close（Windows 同步子进程后控制台句柄抖动）不得终止解码，否则 doctor 后的提问会冻结。
+import readline from 'node:readline';
+import { StringDecoder } from 'node:string_decoder';
+import { box, cyan, dim } from './ansi.mjs';
+
+// Ctrl+C / EOF 的退出哨兵：wizardCommand 捕获后返回 0，不裸抛堆栈
+export class QuitError extends Error {}
+
+// 方向键 / Home / End 映射：CSI（\x1b[<params><final>）与 SS3（\x1bO<final>，老终端）的终止字节 → key.name
+const SEQUENCE_KEYS = { A: 'up', B: 'down', C: 'right', D: 'left', H: 'home', F: 'end' };
+
+// 自研轻量按键解码器：监听 stdin 原始 data，解出 key 对象后逐个 emit ('keypress', key)，
+// 事件契约与内置解码器一致（runPrompt / widgets 无感知）。返回 detach：仅供 restore 摘监听、清计时。
+// 不监听 close：真实 EOF 由 runPrompt 兜底，虚假 close（Windows 同步子进程控制台句柄抖动）不得终止解码。
+function attachKeyDecoder(input) {
+  const decoder = new StringDecoder('utf8'); // 多字节字符跨 chunk 边界在此拼合
+  let buf = ''; // 未解完的余量（不完整转义序列前缀 / 孤立 ESC）
+  let escTimer = null; // 孤立 ESC 的 50ms 等待计时
+  const emit = (key) => {
+    if (process.env.FLOW_KIT_KEY_DEBUG) console.error('[flow-kit key] emit:', JSON.stringify(key));
+    input.emit('keypress', key);
+  };
+  const onEscTimeout = () => {
+    escTimer = null;
+    if (buf !== '\x1b') return; // 防御：等待期内已无孤立 ESC（正常应在 data 到达时清计时）
+    buf = '';
+    emit({ name: 'escape', sequence: '\x1b' });
+  };
+  const parse = () => {
+    while (buf.length > 0) {
+      if (buf[0] === '\x1b') {
+        if (buf.length === 1) {
+          // 只剩孤立 ESC：50ms 内无后续 → escape；期间 data 到达则清计时续解为序列
+          if (escTimer === null) escTimer = setTimeout(onEscTimeout, 50);
+          return;
+        }
+        if (buf[1] === '[' || buf[1] === 'O') {
+          // CSI 终止字节 0x40-0x7E，之前的 0x20-0x3F 是参数 / 中间字节；SS3 终止字节固定在第三位
+          let end = 2;
+          if (buf[1] === '[') while (end < buf.length && buf[end] >= ' ' && buf[end] <= '?') end += 1;
+          if (end >= buf.length) return; // 不完整前缀：保留余量等下一 chunk 续解
+          const final = buf[end];
+          const sequence = buf.slice(0, end + 1);
+          buf = buf.slice(end + 1);
+          // 仅无参数的单终止字节序列映射方向键 / Home / End；其余（带参数修饰、未识别）→ unknown，不误动光标
+          const name = end === 2 ? SEQUENCE_KEYS[final] : undefined;
+          emit({ name: name ?? 'unknown', sequence });
+          continue;
+        }
+        // ESC 后跟其他字符：整段按未知序列交付（不崩、不误动光标）
+        const sequence = buf.slice(0, 2);
+        buf = buf.slice(2);
+        emit({ name: 'unknown', sequence });
+        continue;
+      }
+      const ch = buf[0];
+      buf = buf.slice(1);
+      const code = ch.charCodeAt(0);
+      if (code === 13 || code === 10) emit({ name: 'return', sequence: ch }); // \r \n → 回车
+      else if (code === 9) emit({ name: 'tab', sequence: ch }); // \t
+      else if (code === 127 || code === 8) emit({ name: 'backspace', sequence: ch }); // \x7f \x08
+      else if (code >= 1 && code <= 26) emit({ name: String.fromCharCode(code + 96), ctrl: true, sequence: ch }); // \x01-\x1a → ctrl+小写字母（含 \x03 → Ctrl+C）
+      else if (ch === ' ') emit({ name: 'space', sequence: ch });
+      else emit({ name: ch, sequence: ch }); // 字母 / 数字 / 普通字符逐字符；粘贴多字符按序逐个
+    }
+  };
+  const onData = (chunk) => {
+    if (escTimer !== null) {
+      clearTimeout(escTimer); // 后续数据到达：取消孤立 ESC 判定，按序列续解
+      escTimer = null;
+    }
+    const text = decoder.write(chunk);
+    if (process.env.FLOW_KIT_KEY_DEBUG) console.error('[flow-kit key] raw:', JSON.stringify(text));
+    buf += text;
+    parse();
+  };
+  const detach = () => {
+    if (escTimer !== null) {
+      clearTimeout(escTimer); // restore 时清计时，避免挂着的 timer 悬住事件循环
+      escTimer = null;
+    }
+    input.removeListener('data', onData);
+  };
+  input.on('data', onData);
+  return detach;
+}
+
+export function createScreen({ input, output }) {
+  const state = { interactive: false, last: 0, detachKeyDecoder: null };
+  const renderLines = (lines) => {
+    let out = state.last > 0 ? `\x1b[${state.last}A` : '';
+    for (const line of lines) out += `\r\x1b[2K${line}\n`;
+    for (let i = lines.length; i < state.last; i += 1) out += '\r\x1b[2K\n';
+    if (state.last > lines.length) out += `\x1b[${state.last - lines.length}A`;
+    state.last = lines.length;
+    output.write(out);
+  };
+  const screen = {
+    input,
+    output,
+    // interactive 是交互态唯一事实源：setup 探测 raw mode 可用性后置位
+    get interactive() {
+      return state.interactive;
+    },
+    setup() {
+      try {
+        input.setRawMode(true);
+        state.interactive = true;
+      } catch {
+        state.interactive = false;
+      }
+      if (state.interactive) {
+        // 交互模式挂自研按键解码器（弃用 readline.emitKeypressEvents，理由见文件头）；重复 setup 不重复挂
+        if (state.detachKeyDecoder === null) state.detachKeyDecoder = attachKeyDecoder(input);
+        // 交互模式隐藏光标，restore 配对显示，消除重绘闪烁
+        output.write('\x1b[?25l');
+      }
+    },
+    render: renderLines,
+    clear: () => renderLines([]),
+    // 重置渲染原点后写原始输出：后续 render 从当前光标处新起一块，不覆盖已有内容
+    print(str) {
+      state.last = 0;
+      output.write(str);
+    },
+    restore() {
+      if (state.interactive) output.write('\x1b[?25h');
+      if (state.detachKeyDecoder !== null) {
+        state.detachKeyDecoder(); // 摘 data 监听并清孤立 ESC 计时
+        state.detachKeyDecoder = null;
+      }
+      try {
+        input.setRawMode(false);
+      } catch {
+        /* 非 TTY 无 raw mode */
+      }
+    },
+  };
+  return screen;
+}
+
+// 交互式单问：渲染 box → keypress 驱动 widget → 完成清掉区块返回 value；Ctrl+C / EOF 抛 QuitError
+export function runPrompt(screen, { title, question, hint, widget }) {
+  const draw = () => screen.render(box(title, [cyan(`◆ ${question}`), '', ...widget.view(), '', dim(hint)]));
+  draw();
+  return new Promise((resolve, reject) => {
+    const input = screen.input;
+    // keypress 与 close 监听成对清理，避免多问后监听器堆积
+    const cleanup = () => {
+      input.removeListener('keypress', onKey);
+      input.removeListener('close', onClose);
+    };
+    const onKey = (key) => {
+      // readline 对不完整/分片到达的转义序列会 emit ('keypress', undefined)，静默忽略
+      if (!key) return;
+      if (key.ctrl && key.name === 'c') {
+        cleanup();
+        reject(new QuitError());
+        return;
+      }
+      const done = widget.onKey(key);
+      if (done) {
+        cleanup();
+        screen.clear();
+        resolve(done.value);
+        return;
+      }
+      draw();
+    };
+    // stdin 关闭（EOF）：与降级路径同语义，按 Ctrl+C 干净退出
+    const onClose = () => {
+      cleanup();
+      reject(new QuitError());
+    };
+    input.on('keypress', onKey);
+    input.on('close', onClose);
+  });
+}
+
+// 降级读行器：整个会话共用一个 readline interface + 行队列，
+// 管道一次性到达的行按序消费不丢；EOF（stdin 关闭）resolve null，保证任意一步干净退出
+export function createLineReader(input, output) {
+  const queue = [];
+  let pending = null;
+  let eof = false;
+  const rl = readline.createInterface({ input, output });
+  rl.on('line', (line) => {
+    if (pending) {
+      const resolve = pending;
+      pending = null;
+      resolve(line);
+    } else {
+      queue.push(line);
+    }
+  });
+  rl.on('close', () => {
+    eof = true;
+    if (pending) {
+      const resolve = pending;
+      pending = null;
+      resolve(null);
+    }
+  });
+  return () => new Promise((resolve) => {
+    if (queue.length) return resolve(queue.shift());
+    if (eof) return resolve(null);
+    pending = resolve;
+  });
+}