berry-agent 0.1.0-alpha.1

package/dist/host/plugins-cmd.js

@@ -0,0 +1,302 @@
+/**
+ * host/plugins-cmd — `plugins` 子命令族 CLI 入口（03 §5.8 三面同源之 CLI 面；
+ * 07 §5 命令族；批 12f-3 骨架 → 成熟度缺口 #10 装机面落码批写真身）。
+ *
+ * 子动词分账：
+ *  - **list**：装载态清单三分区（启用/失败/禁用）。走与 dump-config **同一
+ *    合成代码路径**（真数据目录读侧 + 主库零落盘 + 不占标记）——装载面必须
+ *    跑（报告语义）。
+ *  - **check**：纯只读零装配（07 §5——不走装载器直读装机账本）。api 块三色
+ *    裁决挂账 API 治理批（03 §8.4/§8.9）。
+ *  - **install <ref>**：三源装机（plugin-install 执行器——ref 单参自含源前缀
+ *    与账本同词法；--min-release-age 旗标逐次覆盖 env 静置窗）。
+ *  - **uninstall <id>**：双相（无 --confirm = inspect 只读报告 / 加 = execute
+ *    四段清算——plugin-uninstall 编舞；--data keep|purge 缺省 keep，--data
+ *    单独在场即拒——execute 载荷不静默猜）。开库走 Persistence 直开 +
+ *    HOST_MIGRATION_TAIL 全链（零装配直开库纪律——sessions/credentials 同形）。
+ *  - **mount/unmount/toggle <id>**：enabled.yaml 行编辑（plugin-store 行编辑
+ *    面；mount 前置查账本——core: id 或已装机 id 才可挂）。
+ *  - **update <id>**：按源分派（plugin-install updatePlugin）。
+ *
+ * 写动词生效时点：CLI 短命进程不装配装载器——写侧动作**下次启动装载生效**
+ * （「装机零生效」语义的 CLI 面呈现；TUI 侧 /reload 排队编舞已落——assembly
+ * 编舞器 + 'reload' 命令注册，/reload 批收官）。
+ *
+ * 退出码：0 成功 / 1 执行失败（结算文本含原因）/ 用法错 2 归解析层。
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { stdout as processStdout, stderr as processStderr } from 'node:process';
+import { Persistence, createAuditFace, resolveDataDir } from '../persist/index.js';
+import { assembleHostStack } from './assembly.js';
+import { formatPluginFailureText } from './boot-failures.js';
+import { checkPluginId } from './manifest.js';
+import { installPlugin, updatePlugin, createDefaultSpawnRunner } from './plugin-install.js';
+import { executeUninstall, inspectUninstall } from './plugin-uninstall.js';
+import { mountRow, readLedger, toggleRow, unmountRow, createPluginStoreFs } from './plugin-store.js';
+import { HOST_MIGRATION_TAIL } from './runtime.js';
+/** plugins 子命令族主入口。返回进程退出码（0/1；用法错 2 归解析层） */
+export async function runPluginsEntry(sub, options) {
+    switch (sub.sub) {
+        case 'list':
+            return runList(options);
+        case 'check':
+            return runCheck(options);
+        case 'install':
+            return runInstall(sub.ref, sub.minReleaseAge, options);
+        case 'uninstall':
+            return runUninstall(sub.id, sub.confirm, sub.dataAction, options);
+        case 'mount':
+        case 'unmount':
+        case 'toggle':
+            return runRowVerb(sub.sub, sub.id, options);
+        case 'update':
+            return runUpdate(sub.id, options);
+    }
+}
+/** list：同一合成代码路径装载 → 三分区人读输出（07 §5「装载态清单」） */
+async function runList(options) {
+    const writeOut = options.writeOut ?? ((text) => processStdout.write(`${text}\n`));
+    const writeErr = options.writeErr ?? ((text) => processStderr.write(`${text}\n`));
+    // dataDir 解析与其他五动词同律（?? resolveDataDir()——env 梯子 BERRY_AGENT_DATA_DIR
+    // 由此接通；2026-09-13 可观测性批 obs-c 修：修前条件展开在 undefined 时省略
+    // dataDir ⇒ memory 诊断形 dataDir=null ⇒ enabled.yaml/账本整跳 ⇒ 磁盘装机
+    // 行三区皆隐〔真模型六轮实机实证：装+mount 后 list 仍只呈 16 core 件〕）
+    const dataDir = options.dataDir ?? resolveDataDir();
+    const assembly = await assembleHostStack({
+        runtime: {
+            dataDir,
+            memory: true, // 同构诊断形（与 dump-config 同形——真盘读侧 + 主库零落盘）
+        },
+        noPlugins: false, // list 语义 = 报告装载态——装载面必须跑（无 --no-plugins 旗标面）
+        debug: false,
+        version: options.version,
+        ...(options.env !== undefined ? { env: options.env } : {}),
+        ...(options.onRuntime !== undefined ? { onRuntime: options.onRuntime } : {}),
+        ...(options.corePlugins !== undefined ? { corePlugins: options.corePlugins } : {}),
+    });
+    if (!assembly.ok) {
+        writeErr(assembly.message);
+        return assembly.exitCode;
+    }
+    try {
+        const { activated, failed, skipped } = assembly.boot.report;
+        const lines = [];
+        lines.push(`启用（${activated.length}）：`);
+        for (const a of activated)
+            lines.push(`  ${a.id}` +
+                `${a.skillDirs.length > 0 ? `  技能目录：${a.skillDirs.join('、')}` : ''}` +
+                `${a.agentDirs.length > 0 ? `  子代理目录：${a.agentDirs.join('、')}` : ''}`);
+        lines.push(`失败（${failed.length}）：`);
+        for (const f of failed)
+            lines.push(`  ${f.id}  ${formatPluginFailureText(f)}`);
+        lines.push(`禁用（${skipped.length}）：`);
+        for (const s of skipped)
+            lines.push(`  ${s.id}  ${s.reason}`);
+        writeOut(lines.join('\n'));
+        return 0;
+    }
+    finally {
+        await assembly.runtime.shutdown();
+    }
+}
+/**
+ * check：纯只读零装配骨架（07 §5——数据面纯只读零装配；不走装载器）。
+ * 账本缺席/为空 = 零装机无可体检项（exit 0——「无断裂」成立）；非空账本的
+ * apiVersion 三色裁决挂账 API 治理批（03 §8.4/§8.9——api 块回填同批）。
+ */
+function runCheck(options) {
+    const writeOut = options.writeOut ?? ((text) => processStdout.write(`${text}\n`));
+    const dataDir = options.dataDir ?? resolveDataDir();
+    let raw = null;
+    try {
+        raw = readFileSync(join(dataDir, 'plugins', 'ledger.json'), 'utf8');
+    }
+    catch {
+        raw = null; // 缺席 = 零装机（ENOENT 同义——首启零文件零负担）
+    }
+    if (raw === null || raw.trim() === '' || raw.trim() === '{}') {
+        writeOut('装机账本缺席或为空——无可体检项（通过）');
+        return 0;
+    }
+    writeOut('装机账本非空，但 apiVersion 三色体检面尚未装配（归 API 治理批——03 §8.4/§8.9）——本命令本批不覆盖此形态');
+    return 1;
+}
+/* ---------------- 写侧六动词（装机面落码批 #10 真身） ---------------- */
+/**
+ * 生命周期归因账真身（05 §1.1 生命周期归因面行——audit 落账批）：惰性开库
+ * sink——动词成功尾首调才开 Persistence（只读路径 list/check 与失败路径零
+ * 开库零负担）；Persistence.close 是 async，故配对 close 由调用层 finally
+ * await（库件回调是同步面——close 责任在 CLI 编排层）。落账失败 warn 不
+ * 阻塞主流程（行编辑已生效不回滚——与 llm/usage append 异常 warn 同哲学）。
+ */
+function lifecycleAuditOf(options, writeErr) {
+    let persistence;
+    return {
+        sink: (type, data) => {
+            try {
+                if (persistence === undefined) {
+                    // dbPath 显式随 dataDir（Persistence 的 dbPath/dataDir 分立解析——
+                    // 缺省 dbPath 走 env 梯子不随 dataDir 选项；CLI 语义 = --data-dir
+                    // 指到哪库就在哪〔三级梯子第二级本意〕）
+                    persistence = Persistence.open({
+                        ...(options.dataDir !== undefined
+                            ? { dataDir: options.dataDir, dbPath: join(options.dataDir, 'sessions.db') }
+                            : {}),
+                        migrations: HOST_MIGRATION_TAIL,
+                        warn: (message) => writeErr(`warn：${message}`),
+                    });
+                }
+                createAuditFace(persistence.store.sqlite()).append(type, data);
+            }
+            catch (err) {
+                writeErr(`warn：生命周期审计落账失败（${type}）：${err instanceof Error ? err.message : String(err)}——主流程不受影响（行编辑已生效）`);
+            }
+        },
+        close: async () => {
+            if (persistence !== undefined) {
+                const closing = persistence;
+                persistence = undefined;
+                await closing.close();
+            }
+        },
+    };
+}
+/** 装机执行器 deps 构造（CLI 面——真盘真 spawn；env 缺省 process.env） */
+function installDepsOf(options, minReleaseAge, onLifecycleAudit) {
+    return {
+        dataDir: options.dataDir ?? resolveDataDir(),
+        fs: createPluginStoreFs(),
+        spawn: createDefaultSpawnRunner(),
+        env: options.env ?? process.env,
+        ...(minReleaseAge !== undefined ? { minReleaseAgeOverride: minReleaseAge } : {}),
+        ...(onLifecycleAudit !== undefined ? { onLifecycleAudit } : {}),
+    };
+}
+/** install <ref>：三源装机（§5.4——ref 词法坏形/撞名/收割失败各档结算文本直呈） */
+async function runInstall(ref, minReleaseAge, options) {
+    const writeOut = options.writeOut ?? ((text) => processStdout.write(`${text}\n`));
+    const writeErr = options.writeErr ?? ((text) => processStderr.write(`${text}\n`));
+    const audit = lifecycleAuditOf(options, writeErr);
+    try {
+        const outcome = await installPlugin(installDepsOf(options, minReleaseAge, audit.sink), ref);
+        if (!outcome.ok) {
+            writeErr(outcome.message);
+            return 1;
+        }
+        writeOut(outcome.text);
+        return 0;
+    }
+    finally {
+        await audit.close();
+    }
+}
+/** update <id>：按源分派（§5.4——npm 重装/git 重克隆/local no-op） */
+async function runUpdate(id, options) {
+    const writeOut = options.writeOut ?? ((text) => processStdout.write(`${text}\n`));
+    const writeErr = options.writeErr ?? ((text) => processStderr.write(`${text}\n`));
+    const audit = lifecycleAuditOf(options, writeErr);
+    try {
+        const outcome = await updatePlugin(installDepsOf(options, undefined, audit.sink), id);
+        if (!outcome.ok) {
+            writeErr(outcome.message);
+            return 1;
+        }
+        writeOut(outcome.text);
+        return 0;
+    }
+    finally {
+        await audit.close();
+    }
+}
+/**
+ * uninstall <id>：双相映射（§5.5——无 --confirm = inspect / 加 = execute）。
+ * 开库走 Persistence 直开 + 迁移链尾单源（域表 DROP/审计落账走同实例窄面）；
+ * --data 单独在场即拒（execute 载荷不静默猜——双相语义混淆当响亮指出）。
+ */
+async function runUninstall(id, confirm, dataAction, options) {
+    const writeOut = options.writeOut ?? ((text) => processStdout.write(`${text}\n`));
+    const writeErr = options.writeErr ?? ((text) => processStderr.write(`${text}\n`));
+    if (dataAction !== undefined && !confirm) {
+        writeErr('--data 是 execute 载荷——须与 --confirm 同场（无 --confirm 即 inspect 只读报告，不携带数据处置）');
+        return 1;
+    }
+    const dataDir = options.dataDir ?? resolveDataDir();
+    // dbPath 显式随 dataDir（同 lifecycleAuditOf——Persistence 的 dbPath/dataDir
+    // 分立解析，缺省 dbPath 走 env 梯子不随 dataDir 选项；CLI 语义 = --data-dir
+    // 指到哪库就在哪。装机面落码批遗留真 bug——审计落账批写测试抓获，修前
+    // 库恒开 env 梯子位、--data-dir 旗标形同虚设）
+    const persistence = Persistence.open({
+        ...(options.dataDir !== undefined
+            ? { dataDir: options.dataDir, dbPath: join(options.dataDir, 'sessions.db') }
+            : {}),
+        migrations: HOST_MIGRATION_TAIL,
+        warn: (message) => writeErr(`warn：${message}`),
+    });
+    try {
+        const deps = { dataDir, fs: createPluginStoreFs(), db: persistence.store.sqlite() };
+        const outcome = confirm
+            ? executeUninstall(deps, id, dataAction ?? 'keep') // 缺省 keep——execute 不静默猜 purge
+            : inspectUninstall(deps, id);
+        if (!outcome.ok) {
+            writeErr(outcome.message);
+            return 1;
+        }
+        writeOut(outcome.text);
+        return 0;
+    }
+    finally {
+        await persistence.close();
+    }
+}
+/**
+ * mount/unmount/toggle <id>：enabled.yaml 行编辑（§5.3/§5.2——下次启动装载
+ * 生效）。mount 前置两查：id 词法（enabled 行 id 空间——core: 前缀或用户
+ * 词法）+ 装机在场（core: id 豁免查账——内置态天然在场；用户 id 未装机拒，
+ * 防写死行 brick 下次 boot 读侧）。成功尾落生命周期归因账（unmount 幂等
+ * 跳过腿由库件零调用——无变更不造账）。
+ */
+async function runRowVerb(verb, id, options) {
+    const writeOut = options.writeOut ?? ((text) => processStdout.write(`${text}\n`));
+    const writeErr = options.writeErr ?? ((text) => processStderr.write(`${text}\n`));
+    const dataDir = options.dataDir ?? resolveDataDir();
+    const fs = createPluginStoreFs();
+    if (verb === 'mount') {
+        if (!checkPluginId(id, { official: true })) {
+            writeErr(`插件 id 词法违例（${id}——小写字母数字连字符，官方件 core: 前缀同律）`);
+            return 1;
+        }
+        if (!id.startsWith('core:')) {
+            const ledgerRead = readLedger(dataDir, fs);
+            if (!ledgerRead.ok) {
+                writeErr(`装机账本损坏：${ledgerRead.reason}——拒写防覆盖（03 §5.4）`);
+                return 1;
+            }
+            if (!ledgerRead.entries.some((e) => e.id === id)) {
+                writeErr(`插件 ${id} 未装机——mount 先走 install（未装机挂行会在下次启动读侧降级，03 §5.3）`);
+                return 1;
+            }
+        }
+    }
+    const audit = lifecycleAuditOf(options, writeErr);
+    try {
+        const result = verb === 'mount'
+            ? mountRow(dataDir, id, undefined, fs, audit.sink)
+            : verb === 'unmount'
+                ? unmountRow(dataDir, id, fs, audit.sink)
+                : toggleRow(dataDir, id, fs, audit.sink);
+        if (!result.ok) {
+            writeErr(result.message);
+            return 1;
+        }
+        writeOut(verb === 'mount'
+            ? `已挂载：${id}——下次启动装载生效（CLI 短命进程不装配装载器；改行时点生效归 TUI /reload，03 §5.2）`
+            : verb === 'unmount'
+                ? `已卸下：${id}（装机保留）——下次启动生效（03 §5.3）`
+                : `已切换：${id} 禁用态翻转——下次启动生效（03 §5.2 三态语义）`);
+        return 0;
+    }
+    finally {
+        await audit.close();
+    }
+}

package/dist/host/plugins-command.js

@@ -0,0 +1,130 @@
+/**
+ * host/plugins-command — TUI `/plugins` 命令面纯逻辑件（03 §5.8 三面同源之
+ * TUI 面；task #88 笔二）。
+ *
+ * argv → `{ok, text}` 结算形（c-5 credentials/commands 同款底座形态）：动词语义
+ * 与回执文本在此单源，TUI 装配面只消费 text 经 notify 归因 'plugins' 投递。
+ * 与 CLI 面（plugins-cmd.ts runRowVerb）的分立点有三：
+ *  1. **成功尾自动链 /reload**（03 §5.2——mount/unmount/toggle 经 TUI 命令面
+ *     自动链；CLI 短命进程不装配装载器故不链，改行下次启动生效）；
+ *  2. **审计 sink = 进程内 audit face**（assembly 单写者实例——与 CLI 惰性
+ *     开库形分立；落账失败 warn 不阻塞主流程，行编辑已生效不回滚）；
+ *  3. **回执文案指向自动链**（CLI 文案指「下次启动生效」——两面对同一行编辑
+ *     动词的生效时点陈述各自诚实）。
+ *
+ * 子动词分账：
+ *  - `list`：装载态清单三分区（启用/失败/禁用）——读内存 boot 报告投影（换血
+ *    取值器闭包——/reload 换代后即见新代），零磁盘零开库。
+ *  - `mount <id>` / `unmount <id>` / `toggle <id>`：enabled.yaml 行编辑
+ *    （plugin-store 行编辑面同源）。mount 前置两查与 CLI 同律：id 词法 +
+ *    装机在场（core: id 豁免查账——内置态天然在场）。
+ *
+ * 纯 memory 诊断形（dataDir null）无数据目录——写动词诚实拒（行编辑无落点），
+ * list 仍可用（读内存投影）。
+ */
+import { formatPluginFailureText } from './boot-failures.js';
+import { checkPluginId } from './manifest.js';
+import { mountRow, readLedger, toggleRow, unmountRow } from './plugin-store.js';
+/** 用法说明（命令描述位 + 未知动词回执共用单源） */
+export const PLUGINS_CMD_USAGE = `/plugins list | mount <id> | unmount <id> | toggle <id> | config <id>
+  list                装载态清单三分区（启用/失败/禁用——内存读面零磁盘）
+  mount <id>          挂载已装机插件（成功尾自动链 /reload）
+  unmount <id>        卸下（装机保留——成功尾自动链 /reload）
+  toggle <id>         禁用态翻转（成功尾自动链 /reload）
+  config <id>         配置表单（configSchema 逐字段问答——secret 入凭证盒）
+（install/uninstall/update 走 CLI：berry-agent plugins <sub>——03 §5.8 三面同源）`;
+/** list 三分区渲染（CLI list 同构输出——两面同源人读形） */
+function renderList(report) {
+    if (report === undefined) {
+        return '装载面未装配（noPlugins 诊断形）——无装载态可列。';
+    }
+    const lines = [];
+    lines.push(`启用（${report.activated.length}）：`);
+    for (const a of report.activated)
+        lines.push(`  ${a.id}${a.skillDirs.length > 0 ? `  技能目录：${a.skillDirs.join('、')}` : ''}`);
+    lines.push(`失败（${report.failed.length}）：`);
+    for (const f of report.failed)
+        lines.push(`  ${f.id}  ${formatPluginFailureText(f)}`);
+    lines.push(`禁用（${report.skipped.length}）：`);
+    for (const s of report.skipped)
+        lines.push(`  ${s.id}  ${s.reason}`);
+    return lines.join('\n');
+}
+/** mount 前置两查（CLI runRowVerb 同律单源复述——id 词法 + 装机在场） */
+function mountPreflight(id, deps) {
+    if (!checkPluginId(id, { official: true })) {
+        return `插件 id 词法违例（${id}——小写字母数字连字符，官方件 core: 前缀同律）`;
+    }
+    if (!id.startsWith('core:')) {
+        const ledgerRead = readLedger(deps.dataDir, deps.fs);
+        if (!ledgerRead.ok) {
+            return `装机账本损坏：${ledgerRead.reason}——拒写防覆盖（03 §5.4）`;
+        }
+        if (!ledgerRead.entries.some((e) => e.id === id)) {
+            return `插件 ${id} 未装机——mount 先走 install（未装机挂行会在下次启动读侧降级，03 §5.3）`;
+        }
+    }
+    return undefined; // 两查全过
+}
+/**
+ * `/plugins` 命令面主入口（argv → 结算形；async——config 表单腿问询在途）。
+ * 行编辑失败零副作用（无变更不造账不链 reload）；成功尾序 = audit 落账 →
+ * 自动链 /reload → 回执。
+ */
+export async function runPluginsCommand(argv, deps) {
+    const verb = argv[0];
+    // list：读内存投影——dataDir null 与 noPlugins 形均诚实呈现（零写面）
+    if (verb === 'list') {
+        return { ok: true, text: renderList(deps.report()) };
+    }
+    if (verb === 'config') {
+        const id = argv[1];
+        if (id === undefined || id === '') {
+            return { ok: false, text: `用法错——缺 <id>。\n${PLUGINS_CMD_USAGE}` };
+        }
+        if (deps.dataDir === null) {
+            return { ok: false, text: '纯 memory 诊断形无数据目录——写动词不可用（行编辑无落点）' };
+        }
+        if (deps.configForm === undefined) {
+            return {
+                ok: false,
+                text: 'config 表单腿未装配（此命令面无发起会话/问询通道）——TUI 会话内 /plugins config 或手编 enabled.yaml',
+            };
+        }
+        return deps.configForm(id);
+    }
+    if (verb === 'mount' || verb === 'unmount' || verb === 'toggle') {
+        if (deps.dataDir === null) {
+            return { ok: false, text: '纯 memory 诊断形无数据目录——写动词不可用（行编辑无落点）' };
+        }
+        const id = argv[1];
+        if (id === undefined || id === '') {
+            return { ok: false, text: `用法错——缺 <id>。\n${PLUGINS_CMD_USAGE}` };
+        }
+        if (verb === 'mount') {
+            const rejected = mountPreflight(id, deps);
+            if (rejected !== undefined)
+                return { ok: false, text: rejected };
+        }
+        const result = verb === 'mount'
+            ? mountRow(deps.dataDir, id, undefined, deps.fs, deps.auditSink)
+            : verb === 'unmount'
+                ? unmountRow(deps.dataDir, id, deps.fs, deps.auditSink)
+                : toggleRow(deps.dataDir, id, deps.fs, deps.auditSink);
+        if (!result.ok) {
+            return { ok: false, text: result.message }; // 行编辑失败——零副作用零链
+        }
+        // 成功尾：自动链 /reload（fire-and-forget——busy 期 reloader 自排队）
+        deps.requestReload();
+        const tail = '已自动链 /reload（会话运行中自动排队，run 收场后执行）';
+        return {
+            ok: true,
+            text: verb === 'mount'
+                ? `已挂载：${id}——${tail}`
+                : verb === 'unmount'
+                    ? `已卸下：${id}（装机保留）——${tail}`
+                    : `已切换：${id} 禁用态翻转——${tail}`,
+        };
+    }
+    return { ok: false, text: `未知动词或用法错。\n${PLUGINS_CMD_USAGE}` };
+}

package/dist/host/plugins-config.js

@@ -0,0 +1,195 @@
+/**
+ * host/plugins-config — `/plugins config <id>` 表单腿编排（ix-3b/c——03 §1.2
+ * 表单条款 + 07 §4.3 提问队列消费）。
+ *
+ * fields 驱动逐字段问答：text/secret 用 input（secret 空答 = 保留现值）、
+ * boolean 用 select 两值（开/关——s-9 修）、select 用 select；问询经 ask
+ * seam（sessionId 由装配面绑定——表单需会话锚，无发起会话的面装配缺席）。写盘分两落点：
+ *  - 非_secret 字段 + 未声明键透传 → enabled.yaml 行 config 整值替换
+ *    （setRowConfig——保留 disabled/opens/doors 原样）；
+ *  - secret 字段 → 凭证盒 plugin:<id>/config:<key>（meta source 'manual'，
+ *    credentials/changed seam 归因——值恒不入生命周期面）。
+ *
+ * 取消语义（03 §1.2「取消 = 整次放弃」）：任一 ask 拒绝（通道取消/abort）
+ * → 捕获为诚实回执，零写盘零凭证写；select 面永不 reject——取消/降级链
+ * 出值域答复的保守值 '' 是取消唯一信使（select 与 boolean 两值形同律；
+ * options 值域结构性非空，合法答复恒非 ''），按取消语义整次放弃——'' 落行
+ * 即写坏插件（不在值域，下次装载
+ * PLUGIN_CONFIG_INVALID 拒载）。落盘期异常按进度分档诚实回执（已写事实
+ * 不谎称零写盘）。缺省烘焙回避：值等于缺省源（行缺席
+ * 时宿主默认/字段 default）的字段不落行——行是覆盖仓，表单全默认直存会把
+ * 清单缺省烙进用户行，作者后续改 default 不再传播。
+ *
+ * 成功尾序：行写盘 → secret 入盒 → requestReload（与 mount 同律 03 §5.2
+ * 自动链）→ 回执（maskConfigSecrets 呈现纪律——secret 值恒遮蔽）。
+ */
+import { pluginNamespace } from '../credentials/index.js';
+import { readEnabledRowsForEdit, setRowConfig } from './plugin-store.js';
+/** boolean 呈现词（人读形） */
+const onOff = (v) => (v ? '开' : '关');
+/**
+ * 表单腿主入口（id → 结算形）。异常问询（取消/abort/通道断）整次放弃——
+ * 捕获为诚实回执，不向上抛（TUI 装配面只消费 text）。
+ */
+export async function runPluginConfigForm(pluginId, deps) {
+    const face = deps.configFaceOf(pluginId);
+    if (face === undefined) {
+        return { ok: false, text: `插件 ${pluginId} 无声明配置面（configSchema 缺席）——无可编辑字段。` };
+    }
+    // 现行行读（未声明键透传源 + 行内现值）；损坏 = fail-loud 诚实拒（不写防覆盖）
+    const read = readEnabledRowsForEdit(deps.dataDir, deps.fs);
+    if (!read.ok)
+        return { ok: false, text: read.message };
+    const row = read.rows.find((r) => r.id === pluginId);
+    const rowConfig = typeof row?.config === 'object' && row.config !== null && !Array.isArray(row.config) ? { ...row.config } : {};
+    const defaults = typeof face.hostDefaults === 'object' && face.hostDefaults !== null && !Array.isArray(face.hostDefaults)
+        ? { ...face.hostDefaults }
+        : {};
+    let rowWritten = false; // 行 config 已写盘旗（落盘期异常分档回执判据——try/catch 两面共见，故置 try 外）
+    let writtenSecrets = 0; // 已入盒 secret 计数（同上——审计 seam 失败不折抵已写事实）
+    try {
+        // —— 逐字段问答（03 §1.2 表单条款——text/secret→input、boolean→select
+        // 两值〔s-9 修〕、select→select）——
+        const next = {}; // 落行值（非 secret）
+        const secrets = []; // 入盒值
+        const receipt = []; // 回执逐字段行（呈现纪律：secret 恒遮蔽）
+        for (const field of face.fields) {
+            const label = field.label ?? field.key;
+            const hint = field.description === undefined ? '' : `\n  ${field.description}`;
+            // 字段 default 的型外安全读（secret 型无 default 位——判别联合外共取须窄化）
+            const fieldDefault = 'default' in field ? field.default : undefined;
+            // 生效现值 = 行 config ?? 宿主默认 ?? 字段 default（装载合成序同源——三级）
+            const currentRaw = field.key in rowConfig ? rowConfig[field.key] : (defaults[field.key] ?? fieldDefault);
+            const fromRow = field.key in rowConfig;
+            const defaultSource = fromRow ? rowConfig[field.key] : (defaults[field.key] ?? fieldDefault);
+            if (field.type === 'text') {
+                const placeholder = typeof currentRaw === 'string' ? currentRaw : undefined;
+                const answer = await deps.ask.input(`${label}：${hint}`, placeholder === undefined ? undefined : { placeholder });
+                // 空答 = 保留现值（清除值不可达——v1 诚实面：清值走手编 enabled.yaml）
+                const value = answer !== '' ? answer : typeof currentRaw === 'string' ? currentRaw : field.default;
+                if (value === undefined) {
+                    if (field.required === true) {
+                        return { ok: false, text: `必填字段 ${field.key}（text）无值——整次放弃（零写盘）。` };
+                    }
+                    receipt.push(`  ${field.key} =（缺席）`);
+                    continue;
+                }
+                if (fromRow || value !== defaultSource)
+                    next[field.key] = value; // 缺省烘焙回避
+                receipt.push(`  ${field.key} = ${value}`);
+                continue;
+            }
+            if (field.type === 'secret') {
+                const ns = pluginNamespace(pluginId);
+                const name = `config:${field.key}`;
+                const exists = deps.getCredential(ns, name) !== undefined;
+                const answer = await deps.ask.input(`${label}（敏感——入凭证盒不落 yaml）：${hint}`, {
+                    placeholder: exists ? '留空保留现值' : '未设置——输入新值',
+                });
+                if (answer !== '') {
+                    secrets.push({ key: field.key, value: answer });
+                    receipt.push(`  ${field.key} = ***（凭证盒，已更新）`);
+                }
+                else if (exists) {
+                    receipt.push(`  ${field.key} = ***（凭证盒，保留现值）`);
+                }
+                else if (field.required === true) {
+                    return { ok: false, text: `必填 secret 字段 ${field.key} 未提供且凭证盒无现值——整次放弃（零写盘）。` };
+                }
+                else {
+                    receipt.push(`  ${field.key} =（未设置）`);
+                }
+                continue;
+            }
+            if (field.type === 'boolean') {
+                // boolean 走 select 两值（开/关）不走 confirm——s-9 修（03 §1.2
+                // 2026-09-13 定形注）：07 §4.3 confirm 后端 Esc 折保守值 false、与
+                // 显式「否」结构性不可辨，「取消 = 整次放弃」经 confirm 面不可表达
+                // （旧码取消折「关」落盘违取消条款）；'' 取消信使同 select 律
+                const current = typeof currentRaw === 'boolean' ? currentRaw : (field.default ?? false);
+                const answer = await deps.ask.select(`${label}（当前 ${onOff(current)}）:${hint}`, [
+                    { value: 'true', label: '开' },
+                    { value: 'false', label: '关' },
+                ]);
+                if (answer === '') {
+                    return {
+                        ok: false,
+                        text: `已取消——${pluginId} config 编辑整次放弃（boolean 问询取消——零写盘零凭证写）。`,
+                    };
+                }
+                const value = answer === 'true';
+                if (fromRow || value !== defaultSource)
+                    next[field.key] = value;
+                receipt.push(`  ${field.key} = ${onOff(value)}`);
+                continue;
+            }
+            // select：choices 即声明 options（值域单源）；'' = 取消/降级链保守值
+            // （select 面永不 reject——ui-core 保守值恒 ''；options 值域结构性非空
+            // 〔config-schema 深校验拒空 value〕，合法答复恒非 ''——'' 是取消唯一
+            // 信使，按取消语义整次放弃，绝不落行〔落行即写坏插件：'' 不在值域，
+            // 下次装载 PLUGIN_CONFIG_INVALID 拒载〕）
+            const choices = field.options;
+            const current = typeof currentRaw === 'string' ? currentRaw : field.default;
+            const value = await deps.ask.select(`${label}${current === undefined ? '' : `（当前 ${current}）`}:${hint}`, choices);
+            if (value === '') {
+                return {
+                    ok: false,
+                    text: `已取消——${pluginId} config 编辑整次放弃（select 问询取消——零写盘零凭证写）。`,
+                };
+            }
+            if (fromRow || value !== defaultSource)
+                next[field.key] = value;
+            receipt.push(`  ${field.key} = ${value}`);
+        }
+        // —— 落盘序：行 config 整值替换（未声明键透传）→ secret 入盒 → reload ——
+        const undeclared = Object.keys(rowConfig).filter((k) => !face.fields.some((f) => f.key === k));
+        const newRowConfig = {};
+        for (const key of undeclared)
+            newRowConfig[key] = rowConfig[key]; // 未声明键原样透传
+        for (const [key, value] of Object.entries(next))
+            newRowConfig[key] = value;
+        // 行缺席且新 config 为空 = 零覆盖需求（全随缺省）——不造 overlay 空行；
+        // 行在场则照写（幂等归一，未声明键清面场景亦达）
+        const rowWriteNeeded = row !== undefined || Object.keys(newRowConfig).length > 0;
+        if (rowWriteNeeded) {
+            const write = setRowConfig(deps.dataDir, pluginId, newRowConfig, deps.fs);
+            if (!write.ok)
+                return { ok: false, text: write.message };
+            rowWritten = true;
+        }
+        const ns = pluginNamespace(pluginId);
+        for (const { key, value } of secrets) {
+            deps.setCredential(ns, `config:${key}`, { apiKey: value, meta: { source: 'manual' } });
+            writtenSecrets += 1; // 入盒即已写（onCredentialChanged 审计 seam 失败不折抵）
+            deps.onCredentialChanged?.({ namespace: ns, name: `config:${key}`, action: 'add', origin: 'human' });
+        }
+        const changed = rowWriteNeeded || secrets.length > 0;
+        if (changed)
+            deps.requestReload();
+        // 呈现纪律内嵌于回执逐字段行（secret 恒 '***'——secret 值结构性不落行，
+        // maskConfigSecrets 的装载呈现位在 dump-config/list 面，此面无需再过一道）
+        const undeclaredLine = undeclared.length === 0 ? '' : `\n未声明键透传 ${undeclared.length} 个：${undeclared.join('、')}`;
+        const head = changed
+            ? `已更新 ${pluginId} 配置（行 config 整值替换 + secret 入凭证盒）——已自动链 /reload（会话运行中自动排队，run 收场后执行）`
+            : `无变更——全随缺省（值等于缺省源不落行，行是覆盖仓不烙缺省）`;
+        return {
+            ok: true,
+            text: `${head}\n${receipt.join('\n')}${undeclaredLine}`,
+        };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        // 问询期取消（落盘未达）= 整次放弃；落盘期异常按进度分档诚实回执——
+        // 已写事实不谎称零写盘（行写盘在全部问询之后，问询期异常恒走首档）
+        if (!rowWritten) {
+            return {
+                ok: false,
+                text: `已取消——${pluginId} config 编辑整次放弃（零写盘零凭证写）：${reason}`,
+            };
+        }
+        return {
+            ok: false,
+            text: `已写入 ${pluginId} 行 config（${writtenSecrets} 个 secret 已入凭证盒、未回滚）：${reason}——表单未完整收口，可重跑 /plugins config 覆盖修复或手编 enabled.yaml`,
+        };
+    }
+}