@aalis/plugin-cli 0.12.2 → 0.14.0

package/dist/index.js

@@ -1,55 +1,67 @@
 import { stdin as input, stdout as output } from 'node:process';
 import * as readline from 'node:readline';
+import { approvals, clipForCard, sanitizeForCard, } from '@aalis/api-approval';
+import { commands } from '@aalis/api-commands';
+import { unmetDependencies } from '@aalis/api-doctor';
 import { hostConfig } from '@aalis/api-host-config';
+import { hostLogs } from '@aalis/api-host-logs';
+import { i18n, localizeFor } from '@aalis/api-i18n';
 import { persona } from '@aalis/api-persona';
-import { getPlatformAdapters, platform } from '@aalis/api-platform';
-import { createStorageGateway, storage } from '@aalis/api-storage';
-import { config, definePlugin, defineService, events, LogHub, lifecycle, logger, optional, provide, services, } from '@aalis/core';
+import { getPlatformAdapters, platform, resolvePlatformBySession, } from '@aalis/api-platform';
+import { isUnfiled, sessionManager } from '@aalis/api-session-manager';
+import { sessionProtocol } from '@aalis/api-session-protocol';
+import { storage } from '@aalis/api-storage';
+import { config, definePlugin, defineService, events, lifecycle, logger, optional, pluginsService, provide, services, } from '@aalis/core';
 import { defineConfig, parseConfig } from '@aalis/schema-config';
+import { textOf } from '@aalis/schema-i18n';
 import chalk from 'chalk';
 import cliTruncate from 'cli-truncate';
 import stringWidth from 'string-width';
-import { ChatBuffer } from './chat-buffer.js';
-import { readLogFileTail } from './log-file.js';
-// ----- 服务描述符（按激活绑定；调用型：绑定接口是 ServiceRef）-----
+import { ChatLog } from './chat-log.js';
+import { groupSummary, languageOf, toolLine } from './fold.js';
+import { SessionView } from './session-view.js';
+import { t } from './texts.js';
+// ----- 服务描述符（调用型：业务层就是提供者的形状）-----
 export const cli = defineService('cli');
 // ===== 插件元数据 =====
 const name = '@aalis/plugin-cli';
 const configSchema = defineConfig({
     sessionId: {
         type: 'string',
-        label: '默认会话 ID',
+        label: t('sessionIdLabel'),
         default: 'cli-default',
         onInvalid: 'error',
-        description: 'CLI 聊天所在的会话标识。',
+        description: t('sessionIdDescription'),
     },
     lastView: {
         type: 'string',
-        label: '上次视图',
+        label: t('lastViewLabel'),
         default: 'chat',
-        description: '运行时自动写回；startupView=last 时启动恢复到这里记录的视图。',
+        description: t('lastViewDescription'),
     },
-    prompt: { type: 'string', label: '提示符', default: 'You', description: '命令行输入提示符前缀' },
+    prompt: { type: 'string', label: t('promptLabel'), default: 'You', description: t('promptDescription') },
     maxLogEntries: {
         type: 'number',
-        label: '日志内存缓冲上限（条）',
+        label: t('maxLogEntriesLabel'),
         default: 50000,
-        description: '日志页内存驻留的最大条数，超出后从最旧成块丢弃；完整日志始终在 data/latest.log',
+        description: t('maxLogEntriesDescription'),
     },
     startupView: {
         type: 'select',
-        label: '启动视图',
+        label: t('startupViewLabel'),
         default: 'last',
-        description: 'CLI 接管终端后的默认视图。last 表示恢复上次视图',
+        description: t('startupViewDescription'),
         options: [
-            { label: '恢复上次', value: 'last' },
-            { label: '聊天', value: 'chat' },
-            { label: '日志', value: 'logs' },
-            { label: '状态', value: 'status' },
-            { label: '帮助', value: 'help' },
+            { label: t('viewLast'), value: 'last' },
+            { label: t('viewChat'), value: 'chat' },
+            { label: t('viewLogs'), value: 'logs' },
+            { label: t('viewStatus'), value: 'status' },
+            { label: t('viewHelp'), value: 'help' },
         ],
     },
 });
+/** 本地终端身份：物理访问即运维者本人。接审批面、接会话协议都以它 */
+const CONSOLE = { platform: 'cli', userId: 'console' };
 // ===== 插件入口 =====
 // platform 既被本插件提供又被状态页枚举，只能是可选依赖：required 会让激活等一个由自己提供的服务。
 const uses = {
@@ -60,13 +72,26 @@ const uses = {
     provide,
     services,
     hostConfig: optional(hostConfig),
+    /** 日志页：订阅时补发最近的历史（启动期的也在里面），之后接实时 */
+    logs: optional(hostLogs),
     platform: optional(platform),
     storage: optional(storage),
     persona: optional(persona),
+    /** 登记 cli 审批面：终端界面在场时审批推到这里，应答记在这个登记身份名下 */
+    approvals: optional(approvals),
+    /** 欢迎行下面的指路：有没有插件没起来，与 /doctor 在不在 */
+    plugins: optional(pluginsService),
+    commands: optional(commands),
+    /** 发出入站之前给配置的会话建档，创建来源写 cli 审批面的登记名 */
+    sessionManager: optional(sessionManager),
+    /** 界面文字按全局层的语言显示；缺席时按原文 */
+    i18n: optional(i18n),
+    /** 聊天区她的输出取会话协议里本会话的条目；缺席时只写整条回复 */
+    sessionProtocol: optional(sessionProtocol),
 };
 export default definePlugin({
     name,
-    displayName: 'CLI 终端',
+    displayName: t('displayName'),
     subsystem: 'platform',
     configSchema,
     provides: [cli, platform],
@@ -75,7 +100,7 @@ export default definePlugin({
 });
 function startCli(caps) {
     const { config, events, logger } = caps;
-    const cfg = parseConfig(configSchema, config, logger);
+    const cfg = parseConfig(configSchema, config.use, logger.use);
     const cliConfig = {
         prompt: cfg.prompt,
         sessionId: cfg.sessionId,
@@ -84,13 +109,25 @@ function startCli(caps) {
         maxLogEntries: Math.max(1000, cfg.maxLogEntries || configSchema.maxLogEntries.default),
     };
     const sessionId = cliConfig.sessionId;
+    const approvalSurface = caps.approvals.use.registerSurface('cli');
     let tui = null;
+    /** i18n 渲染界面文字抛错时告警过了：之后再出错不再告警 */
+    let renderWarned = false;
+    const onRenderError = (err) => {
+        if (renderWarned)
+            return;
+        renderWarned = true;
+        logger.use.warn('按全局层的语言渲染界面文字出错，按原文显示（之后再出错不再告警）:', err);
+    };
+    // 终端是 owner 自己看的：界面文字按全局层的语言，不看终端会话自己的语言设置（聊天输出已由网关按会话渲染）。终端不做
+    // Markdown 转义
+    const localize = value => localizeFor(caps.i18n, value, { host: true }, { onError: onRenderError });
     const adapter = {
         adapterName: 'CLI',
         platform: 'cli',
-        sessionTypes: [], // CLI 单会话，不区分 sessionType
+        // 终端界面在跑才有连接；后台运行（非 TTY）与界面起来之前没有连接，不是离线
         getConnections() {
-            return [{ id: sessionId, platform: 'cli', status: tui?.isRunning() ? 'online' : 'offline' }];
+            return tui?.isRunning() ? [{ id: sessionId, platform: 'cli', status: 'online' }] : [];
         },
         // sessionId 由配置直接给出（不带 platform 前缀），需显式声明只接管自己的 sessionId
         canHandle(sid) {
@@ -100,72 +137,83 @@ function startCli(caps) {
             if (tui)
                 tui.pushAssistant(content);
             else
-                logger.info(`[cli] ${content}`);
+                logger.use.info(`[cli] ${content}`);
         },
     };
-    caps.provide(platform, adapter);
+    caps.provide.use(platform, adapter);
     const cliService = {
         getSessionId: () => sessionId,
         isRunning: () => tui?.isRunning() ?? false,
     };
-    caps.provide(cli, cliService);
-    events.on('outbound:message', msg => {
+    caps.provide.use(cli, cliService);
+    // 附件：终端就是这个会话的平台，显示不了图片本身，写一行说明（类型、名称、大小、本机路径），写出即算送达并照常归档。
+    // 路径在支持超链接的终端里可以点开。类型的显示名取本插件字典（归档协议的类别占位符不当显示名）
+    const attachmentStorage = caps.storage.use;
+    async function attachmentLine(att) {
+        const label = `[${localize(t('attachmentKind', { kind: att.kind }))}]`;
+        if (/^https?:\/\//i.test(att.data))
+            return `${label} ${att.name ?? ''} ${att.data}`.replace(/\s+/g, ' ').trim();
+        if (att.data.startsWith('data:') && att.data.includes(';base64,')) {
+            const bytes = Math.floor(((att.data.length - att.data.indexOf(',') - 1) * 3) / 4);
+            return `${label} ${att.name ?? localize(t('inlineData'))} · ${localize(t('size', { bytes }))}`;
+        }
+        let path = att.data;
+        let size = '';
+        try {
+            path = await attachmentStorage.resolveLocalPath(att.data, 'read');
+            size = localize(t('size', { bytes: (await attachmentStorage.stat(att.data)).size }));
+        }
+        catch {
+            // 取不到本机路径时照写存储地址
+        }
+        return [`${label} ${att.name ?? path.split('/').pop() ?? ''}`, size, path].filter(Boolean).join(' · ');
+    }
+    /**
+     * 写到终端：她回复的正文由会话协议的条目画，终端订着这个会话时不再写一遍（订阅在途时等它落定再定）；没订上（会话服务不在、
+     * 会话还没建档）时整条写出。系统与指令消息照常写。附件消息的文字先写（非空时），再依次写各附件
+     */
+    async function write(msg, attachments) {
+        const drawn = msg.source === 'agent' && (await tui?.drawsReplies()) === true;
+        if (!drawn && (attachments.length === 0 || msg.content.trim()))
+            await adapter.sendMessage(msg.sessionId, msg.content);
+        for (const att of attachments)
+            await adapter.sendMessage(msg.sessionId, await attachmentLine(att));
+    }
+    events.use.on('outbound:message', msg => {
         if (msg.sessionId !== sessionId)
             return;
-        // 同一轮已流式输出时，agent 的整条回复是重复；系统/指令消息不是流式正文，照常显示
-        if (msg.source === 'agent' && tui?.consumeStreamedSend())
-            return;
-        adapter.sendMessage(msg.sessionId, msg.content);
-    });
-    events.on('outbound:stream', chunk => {
-        if (chunk.sessionId !== sessionId)
+        const attachments = (msg.attachments ?? []).map(att => ({ ...att }));
+        // 由条目画的正文不再写，其余照常显示。content 已由网关按会话的语言渲染（网关缺席时是原文）
+        const written = write(msg, attachments);
+        // 出站的平台另有在场的适配器（如 owner 从 WebUI 驱动这个会话）由那个平台认领并记进历史；回执已被别的入口认领的不覆盖。
+        // 这两种照样写到终端，不认领、不发 outbound:delivered，免得再记一份。平台没有适配器的（如工作流注入的）由终端认领
+        const handedOff = msg.platform !== adapter.platform && getPlatformAdapters(caps.platform).some(a => a.platform === msg.platform);
+        if (handedOff || msg.delivery) {
+            written.catch(err => logger.use.warn('[cli] 写到终端失败:', err));
             return;
-        tui?.applyStreamChunk(chunk);
-    });
-    // 临时缓冲：插件装配早于 app:started，但晚于 bootstrap-buffer.dispose()；
-    // 我们订阅一个 onEntry 把这段窗口的实时 entry 留住，并在 app:started 时合并
-    // data/latest.log 尾部（覆盖装配之前的早期 boot 日志）。
-    const liveBuffer = [];
-    let liveBufferActive = true;
-    const stopLiveBuffer = LogHub.default.onEntry(entry => {
-        if (liveBufferActive)
-            liveBuffer.push(entry);
+        }
+        // 写出即算送达，同步认领回执（作品通知等要等它）；写不出时回执交出原因。送达之后发 outbound:delivered，存档据此把
+        // 不是她回复的文字与发出的附件记进历史
+        msg.delivery = written.then(() => {
+            void events.use.emit('outbound:delivered', { ...msg, attachments, delivery: undefined });
+            return { ok: true };
+        }, err => ({ ok: false, error: textOf(err) }));
     });
-    events.on('app:started', async () => {
+    // 日志从激活起订阅：先补发最近 2000 条，之后实时接着送，seq 连续。界面起来之前攒着，起来之后交给它
+    const earlyLogs = [];
+    let onLog = entry => earlyLogs.push(entry);
+    const stopLogs = caps.logs.use.subscribe(entry => onLog(entry), { history: 2000 });
+    events.use.on('app:started', () => {
         // 非交互终端（日志重定向 / 容器 / systemd）：不接管终端、不画界面，控制台日志照常走 stdout；
         // 服务仍在线（平台枚举、子命令分发不受影响），出站消息退化为日志（见 sendMessage）。
         if (!output.isTTY || !input.isTTY) {
-            liveBufferActive = false;
-            stopLiveBuffer();
-            logger.info('stdin/stdout 非 TTY，CLI 界面未启动');
+            stopLogs();
+            logger.use.info('stdin/stdout 非 TTY，CLI 界面未启动');
             return;
         }
-        let initial = [];
-        try {
-            initial = await readLogFileTail(createStorageGateway(caps.storage), 2000);
-        }
-        catch {
-            // 文件未就绪可忽略——只是无早期历史
-        }
-        // 合并：file tail 与 live buffer 都可能含同一 seq，按 seq 去重排序
-        const seen = new Set();
-        const merged = [];
-        for (const e of initial) {
-            if (seen.has(e.seq))
-                continue;
-            seen.add(e.seq);
-            merged.push(e);
-        }
-        for (const e of liveBuffer) {
-            if (seen.has(e.seq))
-                continue;
-            seen.add(e.seq);
-            merged.push(e);
-        }
-        merged.sort((a, b) => a.seq - b.seq);
-        liveBufferActive = false;
-        stopLiveBuffer();
-        tui = new CliTui(caps, cliConfig, sessionId, merged);
+        const started = new CliTui(caps, cliConfig, sessionId, approvalSurface, localize, earlyLogs);
+        onLog = entry => started.appendLog(entry);
+        tui = started;
         tui.start();
     });
 }
@@ -176,6 +224,8 @@ class CliTui {
     caps;
     config;
     sessionId;
+    approvalSurface;
+    localize;
     view;
     previousView = 'chat';
     /** 非 chat 视图期间进入聊天区的条数（确认提示、回复）；header 的 CHAT 页签带计数，切回即清 */
@@ -185,27 +235,51 @@ class CliTui {
     cursor = 0;
     history = [];
     historyIndex = null;
-    chat = new ChatBuffer();
+    /** 提交的行依次投递：会话缺档时要先等建档，后一行不能越过前一行先发出 */
+    delivering = Promise.resolve();
+    /** 已告警过配置的会话 id 由别的平台适配器认领 */
+    warnedForeign = false;
+    log = new ChatLog();
+    /** 连续的工具调用全部展开（Ctrl+O）；不存配置，重启回到收起 */
+    expanded = false;
+    /** 经会话协议订阅终端的会话，条目进聊天区 */
+    session;
+    unfollow;
     logLines;
     logScroll = 0;
     logWrap = false;
     statusScroll = 0;
     helpScroll = 0;
-    removeLogListener = null;
-    // 流式状态：正在生成的 assistant 回复，其行由 ChatBuffer 维护为末尾一段
-    streamingContent = '';
-    streamedRecently = false;
     renderQueued = false;
     closing = false;
     restoreOnExit = () => restoreTerminalState();
-    constructor(caps, config, sessionId, initialEntries = []) {
+    /** 推到终端、还没结的审批，按推到的先后；卡上显示第一张 */
+    cards = [];
+    /** 卡上选中的应答。推出时不选：正在打字时按下的回车不会落到卡上 */
+    choice;
+    attendance;
+    constructor(caps, config, sessionId, approvalSurface, localize, initialEntries = []) {
         this.caps = caps;
         this.config = config;
         this.sessionId = sessionId;
+        this.approvalSurface = approvalSurface;
+        this.localize = localize;
         this.view = config.startupView === 'last' ? config.lastView : config.startupView;
-        // 启动期日志由插件入口通过尾读 data/latest.log + 实时 buffer 合并后注入，
-        // 之后通过 LogHub.onEntry 实时累积；按 seq 单调，下方 onEntry 用 lastSeq 去重避免与 initial 重复。
+        // 日志由插件入口的订阅送来：界面起来之前的这一批，之后经 appendLog 一条条接着
         this.logLines = initialEntries.slice();
+        // 以本地终端身份接入审批面（与输入消息的 userId 相同）。有按键才上报在场。卡上的文字按全局层的语言渲染，事实原样
+        this.attendance = this.approvalSurface.attend(CONSOLE, {
+            requested: approval => {
+                this.cards.push(approval);
+                this.queueRender();
+            },
+            settled: (approvalId, { state }) => this.closeCard(approvalId, tool => t(SETTLED_LINES[state], { tool })),
+        });
+        this.session = new SessionView(sessionId, { identity: CONSOLE, surface: approvalSurface }, {
+            item: item => this.timelineChanged(this.log.upsert(item)),
+            delta: (itemId, text) => this.timelineChanged(this.log.delta(itemId, text)),
+            tasks: this.queueRender,
+        }, caps.logger.use);
     }
     isRunning() {
         return this.running;
@@ -216,7 +290,7 @@ class CliTui {
         this.running = true;
         // 宣告"我接管终端"——任何写 stdout 的订阅者（runtime/console-sink 等）
         // 自行响应该事件停止写入，CLI 不直接干预日志系统。
-        this.caps.events.emit('terminal:claimed', 'cli').catch(() => { });
+        this.caps.events.use.emit('terminal:claimed', 'cli').catch(() => { });
         // 1049h: 进入备用屏 / 25l: 隐藏光标 / 1007h: alternate scroll——支持它的终端会把
         // 滚轮翻译成方向键，落到我们的键盘滚动路径上。不开启 SGR 鼠标上报（1000h/1006h）：
         // 终端保持原生的文本选择/复制，程序不接管任何鼠标事件。
@@ -227,99 +301,93 @@ class CliTui {
             input.setRawMode(true);
         input.resume();
         process.once('exit', this.restoreOnExit);
-        // 已注入 initialEntries 中最大的 seq；onEntry 收到 seq <= 此值的视为重复跳过
-        let lastSeq = this.logLines.length > 0 ? this.logLines[this.logLines.length - 1].seq : -1;
-        this.removeLogListener = LogHub.default.onEntry(entry => {
-            if (entry.seq <= lastSeq)
-                return;
-            lastSeq = entry.seq;
-            // 不限长——启动期起累积，渲染仅访问可见窗口，内存价格可接受
-            this.logLines.push(entry);
-            if (this.logLines.length > this.config.maxLogEntries)
-                this.trimLogHead();
-            // 用户已主动向上滚（logScroll > 0）时，新日志到来应保持视图锚定在原历史位置，
-            // 而非随 raw.length 增长把旧内容挤出可见区。logScroll === 0 表示跟随底部。
-            if (this.view === 'logs' && this.logScroll > 0)
-                this.logScroll += 1;
-            if (this.view === 'logs')
-                this.queueRender();
-        });
-        const assistantName = this.caps.persona.current?.getPersonaName() ?? 'Aalis';
-        this.chat.append([
-            chalk.gray(this.formatCont()) + chalk.gray(`欢迎使用 ${assistantName}。按 ${chalk.cyan('Ctrl+G')} 查看快捷键。`),
-        ]);
-        // 意图确认不自建通道：走 session-confirm 的公共协调器（authority 的 '*' 回调）——提示以消息
-        // 进聊天区（带参数摘要），在输入框回复 y / ys 即可；回复在 inbound:confirm 相位被拦截，不触达 agent。
-        // 与 WebUI / OneBot 同一份排队、超时、会话授予语义，CLI 不再维护第二套。
+        const welcome = t('welcome', { name: this.personaName() ?? 'Aalis', key: chalk.cyan('Ctrl+G') });
+        this.log.append([chalk.gray(this.formatCont()) + chalk.gray(this.localize(welcome))]);
+        void this.pointToUnready();
+        // 她的输出取会话协议里本会话的条目：会话服务在就接上，换提供者时断开旧的、接上新的
+        this.unfollow = this.caps.sessionProtocol.follow(service => this.session.attach(service));
         input.on('keypress', this.handleKeypress);
         output.on('resize', this.queueRender);
-        this.caps.lifecycle.onDispose(() => this.stop());
+        // 设置变了（全局层的语言、终端会话的人设，在宿主配置文档或会话设置里）：界面立即按新的设置重绘。聊天区的本地行写进时定住，
+        // 她的回复与工具行随当前设置重绘
+        this.caps.events.use.on('session-settings:changed', this.queueRender);
+        this.caps.events.use.on('host-config:changed', this.queueRender);
+        this.caps.lifecycle.use.onDispose(() => this.stop());
         this.render();
     }
+    /**
+     * 插件状态静置之后，有插件没起来时在欢迎行下面指路：数目是失败与缺服务之和（缺服务按 api-doctor 的共享判据，只在等
+     * 别的插件启动的不算），与 /doctor 的「失败」「未就绪」两项一致；有 doctor 指令时指向它，没有时指向日志页
+     */
+    async pointToUnready() {
+        if (!this.caps.plugins.present)
+            return;
+        const plugins = this.caps.plugins.use;
+        await plugins.idle();
+        const status = plugins.getStatus();
+        const lacking = [...unmetDependencies(status, this.caps.services.use.names()).values()].filter(u => u.lacking.length > 0);
+        const count = status.filter(p => p.state === 'error').length + lacking.length;
+        if (count === 0)
+            return;
+        const hint = (this.caps.commands.present ? this.caps.commands.use.has('doctor') : undefined)
+            ? t('unreadyDoctor', { count, command: chalk.cyan('/doctor') })
+            : t('unreadyLogs', { count, key: chalk.cyan('Ctrl+L') });
+        this.log.append([chalk.gray(this.formatCont()) + chalk.yellow(this.localize(hint))]);
+        this.queueRender();
+    }
     stop() {
         if (this.closing)
             return;
         this.closing = true;
         this.running = false;
-        this.removeLogListener?.();
-        this.removeLogListener = null;
+        this.unfollow?.();
         input.off('keypress', this.handleKeypress);
         output.off('resize', this.queueRender);
         process.off('exit', this.restoreOnExit);
         restoreTerminalState();
         // 归还终端——sink 等订阅者可自行恢复
-        this.caps.events.emit('terminal:released', 'cli').catch(() => { });
+        this.caps.events.use.emit('terminal:released', 'cli').catch(() => { });
     }
+    appendLog(entry) {
+        // 启动期起累积，渲染只访问可见窗口
+        this.logLines.push(entry);
+        if (this.logLines.length > this.config.maxLogEntries)
+            this.trimLogHead();
+        // 用户已主动向上滚（logScroll > 0）时，新日志到来应保持视图锚定在原历史位置，
+        // 而非随 raw.length 增长把旧内容挤出可见区。logScroll === 0 表示跟随底部。
+        if (this.view === 'logs' && this.logScroll > 0)
+            this.logScroll += 1;
+        if (this.view === 'logs')
+            this.queueRender();
+    }
+    /** 写一段她名下的本地行（整条回复、指令回复与系统消息、附件说明） */
     pushAssistant(content) {
         if (!content.trim())
             return;
-        this.chat.append(this.formatAssistantBlock(content));
+        this.log.append(this.formatAssistantBlock(content));
         if (this.view !== 'chat')
             this.unreadChat++;
         this.queueRender();
     }
-    /**
-     * 上一轮 是否有流式内容。调用后会重置。转发文件时 outbound:message 看到流完整后重复发送，需要跳过。
-     */
-    consumeStreamedSend() {
-        if (this.streamedRecently) {
-            this.streamedRecently = false;
-            return true;
-        }
-        return false;
-    }
-    applyStreamChunk(chunk) {
-        if (chunk.done) {
-            // 完结本轮流式
-            if (this.chat.streaming) {
-                this.streamedRecently = true;
-                this.chat.endStreaming();
-                this.streamingContent = '';
-                if (this.view === 'chat')
-                    this.queueRender();
-            }
-            return;
-        }
-        if (!chunk.contentDelta)
-            return;
-        // 首个块：开一个新的 assistant 条目；上一轮遗留的「已流式」标记一并作废
-        if (!this.chat.streaming) {
-            this.streamingContent = '';
-            this.streamedRecently = false;
-            if (this.view !== 'chat') {
-                this.unreadChat++;
-                this.queueRender();
-            }
-        }
-        this.streamingContent += chunk.contentDelta;
-        // 根据累积内容重建该消息占据的行
-        this.chat.replaceStreamingBlock(this.formatAssistantBlock(this.streamingContent));
-        if (this.view === 'chat')
-            this.queueRender();
+    /** 她回复的正文由条目画：订着终端的会话（订阅在途时等它落定） */
+    drawsReplies() {
+        return this.session.drawsReplies();
+    }
+    /** 条目来了：有字的回复刚出现、又不在聊天页时计一条未读 */
+    timelineChanged(fresh) {
+        if (fresh && this.view !== 'chat')
+            this.unreadChat++;
+        this.queueRender();
+    }
+    /** 终端会话生效的人设的名字：人设服务按这个会话取卡，与回合同一口径；没有人设服务或卡没取名时为 undefined */
+    personaName() {
+        return this.caps.persona.present
+            ? this.caps.persona.use.getPersonaName({ sessionId: this.sessionId, platform: 'cli' }) || undefined
+            : undefined;
     }
     /** 所有标签对齐到同一列宽，确保 │ 竖线垂直对齐 */
     labelCol() {
-        const persona = this.caps.persona.current?.getPersonaName() ?? 'Aalis';
+        const persona = this.personaName() ?? 'Aalis';
         return Math.max(visibleLen(`✦ ${persona}`), // assistant
         visibleLen(`❯ ${this.config.prompt}`), // user
         visibleLen('◆ System'), // system
@@ -336,14 +404,18 @@ class CliTui {
         return `${' '.repeat(col)} ${chalk.gray('│')} `;
     }
     formatAssistantBlock(content) {
-        const persona = this.caps.persona.current?.getPersonaName() ?? 'Aalis';
+        const persona = this.personaName() ?? 'Aalis';
         const firstHead = this.formatHead(chalk.green(`✦ ${persona}`));
         const contHead = this.formatCont();
         return content.split('\n').map((line, i) => (i === 0 ? firstHead : contHead) + line);
     }
-    handleKeypress = async (chunk, key) => {
+    handleKeypress = (chunk, key) => {
         if (!this.running)
             return;
+        // 卡片只接它推出之后的按键：这次按键让终端变为在场而补推来的卡，owner 还没看到，这次按键照常处理
+        const carded = this.cards.length > 0;
+        // 终端有输入即在场：最近一次按键在审批服务的时限内，审批就推到这里
+        this.attendance.presence(true);
         if (key.ctrl && key.name === 'c') {
             this.stop();
             process.kill(process.pid, 'SIGINT');
@@ -365,10 +437,20 @@ class CliTui {
             this.switchView('help');
             return;
         }
+        if (key.ctrl && key.name === 'o') {
+            this.expanded = !this.expanded;
+            this.queueRender();
+            return;
+        }
         if (key.name === 'escape') {
             this.switchView(this.previousView);
             return;
         }
+        // 审批卡是模态的：卡在时除了上面的切换视图与退出，按键只用来应答；打字与回车不算应答，也不进输入框
+        if (carded) {
+            this.handleCardKey(key);
+            return;
+        }
         if (this.view === 'logs') {
             this.handleLogsKey(key);
             return;
@@ -395,7 +477,7 @@ class CliTui {
             return;
         }
         if (key.name === 'return') {
-            await this.submitLine();
+            this.submitLine();
             return;
         }
         if (key.name === 'backspace') {
@@ -447,6 +529,40 @@ class CliTui {
             this.queueRender();
         }
     };
+    /** ← 选批准、→ 选拒绝，回车确定选中的一项；Ctrl+Y 直接批准、Ctrl+N 直接拒绝 */
+    handleCardKey(key) {
+        if (key.ctrl && (key.name === 'y' || key.name === 'n')) {
+            this.answer(key.name === 'y' ? 'approve' : 'deny');
+            return;
+        }
+        if (key.name === 'left' || key.name === 'right') {
+            this.choice = key.name === 'left' ? 'approve' : 'deny';
+            this.queueRender();
+            return;
+        }
+        if (key.name === 'return' && this.choice)
+            this.answer(this.choice);
+    }
+    /** 应答卡上的第一张。成功时结算同步推回、卡片随之关掉；被拒的应答（已结算、审批服务不在等）同样关卡并写明原因 */
+    answer(decision) {
+        const card = this.cards[0];
+        const reply = this.attendance.respond({ approvalId: card.id, decision, contentHash: card.contentHash });
+        if (!reply.ok)
+            this.closeCard(card.id, tool => t('answerRefused', { tool, reason: reply.message }));
+    }
+    /** 审批结算了：卡片关掉，聊天区留一行（line 按工具名给出这一行） */
+    closeCard(approvalId, line) {
+        const index = this.cards.findIndex(card => card.id === approvalId);
+        if (index < 0)
+            return;
+        const [card] = this.cards.splice(index, 1);
+        if (index === 0)
+            this.choice = undefined;
+        this.log.append([`${this.formatHead(chalk.yellow('◆ System'))}${this.localize(line(sanitizeForCard(card.tool)))}`]);
+        if (this.view !== 'chat')
+            this.unreadChat++;
+        this.queueRender();
+    }
     handleLogsKey(key) {
         if (key.ctrl && key.name === 'w') {
             this.logWrap = !this.logWrap;
@@ -485,7 +601,7 @@ class CliTui {
             this[field] = Number.MAX_SAFE_INTEGER;
         this.queueRender();
     }
-    async submitLine() {
+    submitLine() {
         const text = this.inputLine.trim();
         this.inputLine = '';
         this.cursor = 0;
@@ -498,20 +614,51 @@ class CliTui {
             this.history.shift();
         const firstHead = this.formatHead(chalk.cyan(`❯ ${this.config.prompt}`));
         const contHead = this.formatCont();
-        this.chat.append(text.split('\n').map((line, i) => (i === 0 ? firstHead : contHead) + line));
+        this.log.append(text.split('\n').map((line, i) => (i === 0 ? firstHead : contHead) + line));
         // 指令解析已统一到全局 inbound:command 相位（plugin-commands）。
         // 适配器不再内联解析：未注册命令被放行为普通消息进入 agent，命中命令
         // 由该相位执行并经 outbound:message 回送渲染到 TUI，与 onebot/webui 一致。
         // shutdown/restart 的 TUI 清理由 lifecycle.onDispose(() => this.stop()) 兜底。
-        // userId 'console'：本地终端身份（物理访问 = 运维者本人），命中 authority 的
-        // cli:console owner 快速通道；缺省 userId 会被当成匿名回退 defaultAuthority。
-        await this.caps.events.emit('inbound:message', {
+        // 一行没发出去只记 warn，不挡后面的行
+        this.delivering = this.delivering
+            .then(() => this.deliver(text))
+            .catch(err => this.caps.logger.use.warn('终端消息没有发出:', err));
+    }
+    /**
+     * 发出一行。会话在入站之前建档、写创建来源：入站时会话表里已有它，房间收录不会把它当成 IM 房间；会话被删后下一条消息
+     * 照样补建。已有的记录只有按 id 兜底建档留下的空记录（没有创建来源、出生平台与绑定，如会话被删后定时任务在它里面派了
+     * 子任务）补写创建来源，其余不动。配置的 id 由别的平台适配器认领（配错了）时不建档、不写创建来源：配错的 id 不能把
+     * 别人的窗口变成 owner 自己的会话。userId 'console'：本地终端身份（物理访问 = 运维者本人），命中 authority 的
+     * cli:console owner 快速通道；缺省 userId 会被当成匿名回退 defaultAuthority
+     */
+    async deliver(text) {
+        const sm = this.caps.sessionManager.present ? this.caps.sessionManager.use : undefined;
+        const session = sm?.getSession(this.sessionId);
+        const unfiled = !session || isUnfiled(session);
+        if (sm && unfiled && !(await this.claimedElsewhere())) {
+            await sm.ensureSession(this.sessionId, {}, { createdFrom: this.approvalSurface.name });
+        }
+        // 订上这个会话再发：这一轮的条目从头画进聊天区
+        await this.session.ensureSubscribed();
+        await this.caps.events.use.emit('inbound:message', {
             content: text,
             sessionId: this.sessionId,
             platform: 'cli',
             userId: 'console',
         });
     }
+    /** 配置的会话 id 由终端以外的平台适配器认领；第一次发现时告警 */
+    async claimedElsewhere() {
+        const { platform, logger } = this.caps;
+        const others = { list: () => platform.list().filter(({ use }) => use.platform !== 'cli') };
+        const owner = await resolvePlatformBySession(others, this.sessionId, logger.use);
+        if (owner && !this.warnedForeign) {
+            this.warnedForeign = true;
+            logger.use.warn(`终端配置的会话 ${this.sessionId} 由平台「${owner.use.platform}」（${owner.id}）认领：终端不给它建档、` +
+                '不写创建来源。改配置里的 sessionId');
+        }
+        return owner !== undefined;
+    }
     recallHistory(delta) {
         if (this.history.length === 0)
             return;
@@ -550,13 +697,13 @@ class CliTui {
         if (view === 'help')
             return;
         // 宿主没提供配置文档时不记：下次启动回到默认视图
-        const host = this.caps.hostConfig.current;
-        if (!host)
+        if (!this.caps.hostConfig.present)
             return;
+        const host = this.caps.hostConfig.use;
         const pluginConfig = host.getPluginConfig(name);
         host.setPluginConfig(name, { ...pluginConfig, lastView: view });
         // 尽力而为：最后视图丢了只是下次回到默认视图，不值得让渲染路径变 async
-        host.save().catch(err => this.caps.logger.warn('记录最后视图失败:', err));
+        host.save().catch(err => this.caps.logger.use.warn('记录最后视图失败:', err));
     }
     queueRender = () => {
         if (this.renderQueued)
@@ -572,20 +719,25 @@ class CliTui {
             return;
         const width = Math.max(40, output.columns || 100);
         const height = Math.max(14, output.rows || 30);
-        // 输入框可变高度（多行输入）：内容行数 + 上下边框，最多 8 行内容
-        const inputContentLines = this.computeInputDisplayLines(width);
-        const inputBoxHeight = inputContentLines.length + 2;
-        // 布局：header(1) + sep(1) + body + inputBox(inputBoxHeight) + footer(1)
-        const bodyHeight = Math.max(3, height - 3 - inputBoxHeight);
+        // 正文下面的框：有审批卡时是卡片；chat 视图是输入框，可变高度（多行输入）：内容行数 + 上下边框，最多 8 行内容；
+        // 别的视图是一行视图说明（框高 3 行），在正文之后算，滚动值取正文钳制过的
+        const box = this.cards.length > 0
+            ? this.renderCard(width, height)
+            : this.view === 'chat'
+                ? this.renderInputBox(width, this.computeInputDisplayLines(width))
+                : undefined;
+        // 布局：header(1) + sep(1) + body + box + footer(1)
+        const bodyHeight = Math.max(3, height - 3 - (box?.length ?? 3));
+        const body = this.renderBody(width, bodyHeight);
         const out = [];
         out.push(this.renderHeader(width));
         out.push(chalk.gray(LINE_H.repeat(width)));
-        out.push(...this.renderBody(width, bodyHeight));
-        out.push(...this.renderInputBox(width, inputContentLines));
+        out.push(...body);
+        out.push(...(box ?? this.renderInputBox(width, [this.viewLine(width)])));
         out.push(this.renderFooter(width));
         output.write('\x1b[?25l\x1b[H');
         output.write(out.map(line => clearLine(line, width)).join('\n'));
-        if (this.view === 'chat') {
+        if (this.view === 'chat' && this.cards.length === 0) {
             // 计算光标在多行输入中的 (row, col)
             const { row: cRow, col: cCol } = this.cursorPosInInput();
             // 行号布局（1-based）：1=header, 2=sep, 3..2+bodyHeight=body, 之后是 inputBox(顶/中.../底), 最后是 footer
@@ -597,7 +749,8 @@ class CliTui {
         }
     }
     renderHeader(width) {
-        const persona = this.caps.persona.current?.getPersonaName() ?? 'default';
+        // 卡没取名时写 -，同状态页
+        const persona = this.personaName() ?? '-';
         const left = ` ${chalk.bold.magenta('●')} ${chalk.bold('Aalis')} ${chalk.gray('·')} ${chalk.cyan(persona)} `;
         const tabs = ['chat', 'logs', 'status', 'help']
             .map(v => {
@@ -650,17 +803,41 @@ class CliTui {
         if (this.view === 'status')
             return this.getStatusViewLines();
         if (this.view === 'help')
-            return this.getHelpViewLines();
+            return this.getHelpViewLines(width);
         return this.getChatViewLines(width);
     }
     getChatViewLines(width) {
-        const lines = [];
         const inner = width - 2; // 缩进 2 列
-        for (const raw of this.chat.lines) {
-            // 宽度感知截断为单行；超长内容直接尾部省略。
-            lines.push(`  ${clipAnsi(raw, inner)}`);
+        // 宽度感知截断为单行；超长内容直接尾部省略。
+        return this.log
+            .layout(this.session.taskRunning)
+            .flatMap(part => ('lines' in part ? part.lines : this.rowLines(part.row)))
+            .map(raw => `  ${clipAnsi(raw, inner)}`);
+    }
+    /**
+     * 条目的一行画成的行：她的正文另起一块、第一行带人设名的标签；工具调用一行，收起的一组一行（展开时这一组的工具调用各一行），
+     * 都用续行的空标签头。思考、提问、通知与回合条目不画：输入回显、指令回复与附件说明是本地行，思考不显示
+     */
+    rowLines(row) {
+        if ('group' in row) {
+            const calls = row.group.filter((item) => item.kind === 'tool-call');
+            if (this.expanded)
+                return calls.map(call => this.callLine(call));
+            return [this.formatCont() + chalk.gray(this.localize(groupSummary(calls)))];
         }
-        return lines;
+        const { item } = row;
+        if (item.kind === 'agent-message')
+            return item.text.trim() ? this.formatAssistantBlock(item.text) : [];
+        return item.kind === 'tool-call' ? [this.callLine(item)] : [];
+    }
+    /** 工具调用一行：做了什么与状态，等你批准写成黄色、失败写成红色 */
+    callLine(call) {
+        const { summary, status } = toolLine(call, this.session.taskRunning, languageOf(this.localize));
+        const head = this.formatCont() + chalk.gray(this.localize(summary));
+        if (!status)
+            return head;
+        const paint = status.tone === 'attention' ? chalk.yellow : status.tone === 'danger' ? chalk.red : chalk.gray;
+        return `${head}${chalk.gray(' · ')}${paint(this.localize(status.text))}`;
     }
     /** 日志视图的增量格式化缓存。logLines 只追加、从不改写，因此已格式化的行
      * 可以按 (width, wrap) 为键永久复用——每帧只格式化"上次之后新增"的条目，
@@ -684,7 +861,7 @@ class CliTui {
         return c.lines;
     }
     /** 内存环形上限：超限时从最旧丢弃约 10% 一块（摊销 O(1)），格式化缓存按 lineCounts
-     * 对齐裁剪而非整体失效——避免每次裁剪都 O(全量) 重建。完整日志始终在 data/latest.log。 */
+     * 对齐裁剪而非整体失效——避免每次裁剪都 O(全量) 重建。完整日志始终在 logs/latest.log。 */
     trimLogHead() {
         const drop = Math.max(1, Math.ceil(this.config.maxLogEntries / 10));
         this.logLines.splice(0, drop);
@@ -735,25 +912,32 @@ class CliTui {
         }
     }
     getStatusViewLines() {
-        const serviceNames = this.caps.services.names();
+        const serviceNames = this.caps.services.use.names();
         const adapter = getPlatformAdapters(this.caps.platform).find(a => a.platform === 'cli');
         const connections = adapter?.getConnections?.() ?? [];
-        const persona = this.caps.persona.current?.getPersonaName() ?? '-';
-        const sec = (t) => chalk.bold.cyan(`▎ ${t}`);
+        const persona = this.personaName() ?? '-';
+        const text = this.localize({
+            runtime: t('statusRuntime'),
+            logs: t('logCount', { count: this.logLines.length }),
+            services: t('statusServices', { count: serviceNames.length }),
+            connections: t('statusConnections', { count: connections.length }),
+            none: t('noConnections'),
+        });
+        const sec = (title) => chalk.bold.cyan(`▎ ${title}`);
         const kv = (k, v) => `    ${chalk.gray(k.padEnd(14))} ${v}`;
         const out = [];
-        out.push(sec('运行时'));
+        out.push(sec(text.runtime));
         out.push(kv('persona', persona));
         out.push(kv('cli session', this.sessionId));
-        out.push(kv('log buffer', `${this.logLines.length} 条`));
+        out.push(kv('log buffer', text.logs));
         out.push('');
-        out.push(sec(`服务 (${serviceNames.length})`));
+        out.push(sec(text.services));
         for (const s of serviceNames)
             out.push(`    ${chalk.green('●')} ${s}`);
         out.push('');
-        out.push(sec(`平台连接 (${connections.length})`));
+        out.push(sec(text.connections));
         if (connections.length === 0)
-            out.push(`    ${chalk.gray('— 无')}`);
+            out.push(`    ${chalk.gray(text.none)}`);
         else
             for (const c of connections) {
                 const dot = c.status === 'online' ? chalk.green('●') : c.status === 'connecting' ? chalk.yellow('●') : chalk.red('●');
@@ -761,50 +945,34 @@ class CliTui {
             }
         return out.map(l => (l.length === 0 ? '' : ` ${l}`));
     }
-    getHelpViewLines() {
-        const sec = (t) => chalk.bold.cyan(`▎ ${t}`);
-        const row = (k, v) => `    ${chalk.cyan(k.padEnd(10))} ${chalk.gray(v)}`;
+    getHelpViewLines(width) {
+        const help = this.localize(HELP);
+        /** text 按宽度折行：第一行接在 head 后面，续行缩进到同一列 */
+        const wrap = (head, text, style) => {
+            const indent = ' '.repeat(visibleLen(head));
+            return wrapWords(text, width - indent.length).map((seg, i) => (i === 0 ? head : indent) + style(seg));
+        };
+        const sec = (title) => wrap(` ${chalk.bold.cyan('▎')} `, title, chalk.bold.cyan);
+        const row = (k, v) => wrap(`     ${chalk.cyan(k.padEnd(10))} `, v, chalk.gray);
         const out = [];
-        out.push(sec('视图切换'));
-        out.push(row('Ctrl+T', 'Chat   ·  聊天 / 命令输入'));
-        out.push(row('Ctrl+L', 'Logs   ·  实时日志'));
-        out.push(row('Ctrl+S', 'Status ·  服务与平台状态'));
-        out.push(row('Ctrl+G', 'Help   ·  当前页'));
-        out.push(row('Esc', '返回上一个视图'));
-        out.push(row('Ctrl+C', '退出'));
-        out.push('');
-        out.push(sec('滚动 (Logs / Status / Help)'));
-        out.push(row('↑ / ↓', '逐行滚动'));
-        out.push(row('PgUp/Dn', '翻页'));
-        out.push(row('Home', '回到顶部'));
-        out.push(row('End', '到底部'));
-        out.push(row('Ctrl+W', '日志页：切换换行模式（多行完整展示）'));
-        out.push('');
-        out.push(sec('编辑'));
-        out.push(row('Enter', '提交输入'));
-        out.push(row('Ctrl+J', '插入换行（macOS Ctrl+Enter）'));
-        out.push(row('Shift+Ent', '插入换行（如终端支持）'));
-        out.push(row('↑ / ↓', '历史记录回溯（chat 视图）'));
-        out.push('');
-        out.push(sec('提示'));
-        out.push(`    ${chalk.gray('• 完整日志写入 data/latest.log，每次启动时上一轮改名为 latest.1.log，保留 5 份；跨重启持续跟随用 tail -F。')}`);
-        out.push(`    ${chalk.gray('• 退出时自动恢复原终端内容（alternate screen）。')}`);
-        out.push(`    ${chalk.gray('• 输入以 / 开头会按命令解析，否则发给 agent。')}`);
-        out.push(`    ${chalk.gray('• ↑/↓、PgUp/PgDn、Home/End 滚动 Logs / Status / Help；选择 / 复制文本直接用终端原生操作。')}`);
-        return out.map(l => (l.length === 0 ? '' : ` ${l}`));
+        for (const { title, rows } of help.sections)
+            out.push(...sec(title), ...rows.flatMap(([k, v]) => row(k, v)), '');
+        out.push(...sec(help.tipsTitle), ...help.tips.flatMap(tip => wrap('     ', tip, chalk.gray)));
+        return out;
+    }
+    /** chat 以外的视图在输入框位置的说明：视图名、总行数与滚动值（正文渲染之后取，是钳制过的） */
+    viewLine(width) {
+        const total = this.view === 'logs'
+            ? this.logLines.length
+            : this.view === 'status'
+                ? this.getStatusViewLines().length
+                : this.getHelpViewLines(width).length;
+        const scroll = this.view === 'logs' ? this.logScroll : this.view === 'status' ? this.statusScroll : this.helpScroll;
+        return chalk.gray(this.localize(t('viewLine', { view: this.view, total, scroll })));
     }
     /** 计算输入框的多行内容（不含边框、不含 padding） */
     computeInputDisplayLines(width) {
         const inner = width - 2;
-        if (this.view !== 'chat') {
-            const total = this.view === 'logs'
-                ? this.logLines.length
-                : this.view === 'status'
-                    ? this.getStatusViewLines().length
-                    : this.getHelpViewLines().length;
-            const scroll = this.view === 'logs' ? this.logScroll : this.view === 'status' ? this.statusScroll : this.helpScroll;
-            return [chalk.gray(`${this.view} · ${total} 行 · scroll ${scroll}  ·  按 Ctrl+T 回到聊天`)];
-        }
         const inputLines = this.inputLine.split('\n');
         const display = [];
         const promptLen = visibleLen(this.makePrompt());
@@ -836,29 +1004,173 @@ class CliTui {
         const bot = chalk.gray(`${BOX_BL}${LINE_H.repeat(inner)}${BOX_BR}`);
         return [top, ...mid, bot];
     }
+    /**
+     * 审批卡：标题行、事实、应答项，上下边框。子会话里的审批在事实之前多一行「子任务」，写根会话以下的各级标题。卡片最多高到
+     * 正文只剩 3 行：事实放不下时保留首尾几行，写明省略了多少行。事实显示前经 clipForCard 清洗，太长的保留首尾、写明省略了多少字
+     */
+    renderCard(width, height) {
+        const card = this.cards[0];
+        const inner = width - 2;
+        const tool = sanitizeForCard(card.tool);
+        const session = sanitizeForCard(card.sessionId);
+        const text = this.localize({
+            heading: t('cardHeading'),
+            subject: this.cards.length > 1
+                ? t('cardSubjectWaiting', { tool, session, count: this.cards.length - 1 })
+                : t('cardSubject', { tool, session }),
+            labels: FACT_LABELS,
+            chain: card.chain?.map(level => level.title),
+            approve: t('approve'),
+            deny: t('deny'),
+            keys: t('cardKeys'),
+        });
+        const title = `${chalk.bold.yellow(text.heading)} ${text.subject}`;
+        const rows = cardFacts(card.facts, text.chain, text.labels);
+        const labelWidth = Math.max(0, ...rows.map(([label]) => visibleLen(label)));
+        const clipped = (value) => {
+            const { head, omitted, tail } = clipForCard(value, CARD_FACT_LIMIT);
+            return omitted === 0 ? head : `${head}${this.localize(t('charsOmitted', { count: omitted }))}${tail}`;
+        };
+        const facts = rows.flatMap(([label, value]) => factLines(label, labelWidth, clipped(value), inner - 2));
+        const option = (decision, label) => this.choice === decision ? chalk.inverse(`❯ ${label}`) : `  ${label}`;
+        const choices = `${option('approve', text.approve)}   ${option('deny', text.deny)}`;
+        // 应答行放不下按键提示时，提示另起一行（再放不下就折行）
+        const answer = visibleLen(`${choices}   ${text.keys}`) < inner
+            ? [`${choices}   ${chalk.gray(text.keys)}`]
+            : [choices, ...wrapWords(text.keys, inner - 1).map(line => chalk.gray(line))];
+        // 高度：header、sep、footer 各一行，正文至少 3 行，卡片的上下边框、标题行与应答行
+        const room = height - 9 - answer.length;
+        const shown = facts.length <= room
+            ? facts
+            : [
+                ...facts.slice(0, Math.ceil((room - 1) / 2)),
+                chalk.gray(this.localize(t('linesOmitted', { count: facts.length - room + 1 }))),
+                ...facts.slice(facts.length - Math.floor((room - 1) / 2)),
+            ];
+        const edge = chalk.yellow(BOX_V);
+        return [
+            chalk.yellow(`${BOX_TL}${LINE_H.repeat(inner)}${BOX_TR}`),
+            ...[title, ...shown, ...answer].map(line => `${edge}${padAnsi(` ${line}`, inner)}${edge}`),
+            chalk.yellow(`${BOX_BL}${LINE_H.repeat(inner)}${BOX_BR}`),
+        ];
+    }
     makePrompt() {
         return `${chalk.cyan('❯')} ${chalk.bold(this.config.prompt)} `;
     }
     makeContPrompt() {
         return `${chalk.gray('…')} ${' '.repeat(this.config.prompt.length)} `;
     }
+    /** 底栏：按键记号后面写它的作用（视图名同启动视图的选项，退出同帮助页），日志页另写换行的开关；按显示宽度截到一行 */
     renderFooter(width) {
-        const baseItems = [
-            `${chalk.cyan('^T')} chat`,
-            `${chalk.cyan('^L')} logs`,
-            `${chalk.cyan('^S')} status`,
-            `${chalk.cyan('^G')} help`,
-            `${chalk.cyan('Esc')} back`,
-            `${chalk.cyan('^C')} exit`,
+        const keys = [
+            ['^T', t('viewChat')],
+            ['^L', t('viewLogs')],
+            ['^S', t('viewStatus')],
+            ['^G', t('viewHelp')],
+            ['Esc', t('footerBack')],
+            ['^C', t('helpExit')],
         ];
+        const items = keys.map(([key, text]) => `${chalk.cyan(key)} ${this.localize(text)}`);
         if (this.view === 'logs') {
-            baseItems.push(`${chalk.cyan('^W')} wrap:${this.logWrap ? chalk.green('on') : chalk.gray('off')}`);
+            const state = this.logWrap ? chalk.green(this.localize(t('wrapOn'))) : chalk.gray(this.localize(t('wrapOff')));
+            items.push(`${chalk.cyan('^W')} ${this.localize(t('footerWrap', { state }))}`);
         }
-        const items = baseItems.join(chalk.gray('  ·  '));
-        const left = ` ${items} `;
-        return padAnsi(chalk.gray.dim(left), width);
+        return padAnsi(chalk.gray.dim(` ${items.join(chalk.gray('  ·  '))} `), width);
     }
 }
+// ===== 帮助页 =====
+/** 帮助页：各节的标题与「按键、作用」行，末尾一节是提示 */
+const HELP = {
+    sections: [
+        {
+            title: t('helpViews'),
+            rows: [
+                ['Ctrl+T', t('helpChat')],
+                ['Ctrl+O', t('helpExpand')],
+                ['Ctrl+L', t('helpLogs')],
+                ['Ctrl+S', t('helpStatus')],
+                ['Ctrl+G', t('helpHelp')],
+                ['Esc', t('helpBack')],
+                ['Ctrl+C', t('helpExit')],
+            ],
+        },
+        {
+            title: t('helpScrolling'),
+            rows: [
+                ['↑ / ↓', t('helpLine')],
+                ['PgUp/Dn', t('helpPage')],
+                ['Home', t('helpTop')],
+                ['End', t('helpBottom')],
+                ['Ctrl+W', t('helpWrap')],
+            ],
+        },
+        {
+            title: t('helpEditing'),
+            rows: [
+                ['Enter', t('helpSubmit')],
+                ['Ctrl+J', t('helpNewline')],
+                ['Shift+Ent', t('helpShiftNewline')],
+                ['↑ / ↓', t('helpHistory')],
+            ],
+        },
+        {
+            title: t('helpCard'),
+            rows: [
+                ['← / →', t('helpChoose')],
+                ['Ctrl+Y', t('approve')],
+                ['Ctrl+N', t('deny')],
+            ],
+        },
+    ],
+    tipsTitle: t('helpTips'),
+    tips: [t('tipLogFile'), t('tipRestore'), t('tipCommands'), t('tipKeys')],
+};
+/** 卡片结算后在聊天区留的话 */
+const SETTLED_LINES = {
+    approved: 'settledApproved',
+    denied: 'settledDenied',
+    expired: 'settledExpired',
+    cancelled: 'settledCancelled',
+};
+/** 每项事实显示的字数上限，超出的保留首尾 */
+const CARD_FACT_LIMIT = 1000;
+/** 卡上事实的标签 */
+const FACT_LABELS = {
+    subtask: t('factSubtask'),
+    command: t('factCommand'),
+    cwd: t('factCwd'),
+    file: t('factFile'),
+    patch: t('factPatch'),
+    params: t('factParams'),
+};
+/**
+ * 卡上的事实：标签（已按读者渲染）与原文。子会话里的审批先写来源链的各级标题（已按读者渲染），以「 › 」相接；标题里的换行与
+ * 别的多行事实一样成续行，缩进到值的那一列，冒充不了带标签的一行
+ */
+function cardFacts(facts, chain, labels) {
+    const rows = [];
+    if (chain?.length)
+        rows.push([labels.subtask, chain.join(' › ')]);
+    if (facts.command !== undefined)
+        rows.push([labels.command, facts.command]);
+    if (facts.cwd !== undefined)
+        rows.push([labels.cwd, facts.cwd]);
+    if (facts.diff)
+        rows.push([labels.file, facts.diff.path], [labels.patch, facts.diff.patch]);
+    if (Object.keys(facts.params).length > 0)
+        rows.push([labels.params, JSON.stringify(facts.params)]);
+    return rows;
+}
+/** 一项清洗过的事实：按换行拆开、按宽度折行；标签只在第一行，补齐到 labelWidth，续行缩进到值的那一列 */
+function factLines(label, labelWidth, text, width) {
+    const head = `${padAnsi(chalk.gray(label), labelWidth)}  `;
+    const indent = ' '.repeat(labelWidth + 2);
+    return text
+        .replace(/\t/g, '    ')
+        .split('\n')
+        .flatMap(line => wrapByVisibleWidth(line, width - indent.length))
+        .map((segment, i) => (i === 0 ? head : indent) + segment);
+}
 // ===== 视觉常量 / 工具 =====
 const LINE_H = '─';
 const BOX_TL = '╭';
@@ -915,6 +1227,32 @@ function clipExact(s, width) {
  * 把单行字符串按可见宽度软折行（CJK 算 2 列，emoji/ANSI 不破坏）。
  * 返回若干段，每段宽度 ≤ width。空字符串返回 [''] 以保留视觉空行。
  */
+/** 按宽度折行，优先在空格处断开（断处的空白去掉）：一行放不下的词（含不带空格的中日韩长句）再按宽度切 */
+function wrapWords(s, width) {
+    if (width <= 0 || stringWidth(s) <= width)
+        return [s];
+    const lines = [];
+    let line = '';
+    for (const token of s.split(/(\s+)/)) {
+        if (stringWidth(line + token) <= width) {
+            line += token;
+            continue;
+        }
+        if (/^\s+$/.test(token)) {
+            lines.push(line);
+            line = '';
+            continue;
+        }
+        if (line.trim())
+            lines.push(line.trimEnd());
+        const pieces = wrapByVisibleWidth(token, width);
+        line = pieces.pop() ?? '';
+        lines.push(...pieces);
+    }
+    if (line)
+        lines.push(line);
+    return lines;
+}
 function wrapByVisibleWidth(s, width) {
     if (width <= 0)
         return [s];