berry-agent 0.1.0-alpha.1

package/dist/host/main.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * host/main — bin 入口装配位（package.json bin = berry-agent → dist/host/main.js）。
+ *
+ * 薄壳三件事：装崩溃编舞（前置窗口直写 crash.log——运行时组装后切
+ * runtime.writeCrashLog）→ 装信号编舞（SIGINT②→130 / SIGTERM 优雅序——
+ * 04 §1）→ parseCli + dispatchCli 分派 + process.exit。
+ *
+ * 本批（12c）执行器族全空——除 help/version 外一切命令诚实退 1「执行面
+ * 尚未装配」（错误路径及时非零退出铁律）；12d（装载器）/conversation
+ * 装配批/12e（TUI）逐席充实 handlers 并在组装运行时后挂 attachRuntime
+ * （信号/崩溃编舞切运行时本体）。
+ *
+ * 自动执行卫兵：仅作为主模块直跑时执行（import.meta.url 对 argv[1]）——
+ * 被 import（测试/程序化装配）不触发副作用。tsc 直出保留首行 shebang，
+ * bin 执行位由 npm pack 装配。
+ */
+import { readFileSync, realpathSync } from 'node:fs';
+import { argv, exit as processExit, stderr, stdin, stdout } from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolveDataDir } from '../persist/index.js';
+import { parseCli } from './cli.js';
+import { dispatchCli } from './dispatch.js';
+import { appendCrashLog } from './runtime.js';
+import { installCrashChoreography, installSignalChoreography } from './signals.js';
+import { DAEMON_CHILD_ENV, runDaemonServe, runServeStatus, runServeStop, spawnDaemonServe } from './serve-daemon.js';
+import { runServeEntry } from './serve-entry.js';
+import { runMcpEntry } from './mcp-entry.js';
+import { runTuiEntry } from './tui-entry.js';
+import { runRunEntry } from './run-entry.js';
+import { runDumpConfigEntry } from './dump-config.js';
+import { runPluginsEntry } from './plugins-cmd.js';
+import { runSessionsEntry } from './sessions-cmd.js';
+import { runCredentialsEntry } from './credentials-cmd.js';
+import { runDoorsEntry } from './doors-cmd.js';
+/** 在飞运行时柄（组装后挂入——信号/崩溃编舞切运行时本体；前置窗口 null） */
+let activeRuntime = null;
+/** 装配序挂入运行时（12d/12e 与 conversation 装配批的执行器在组装后调用） */
+export function attachRuntime(runtime) {
+    activeRuntime = runtime;
+}
+/** 读包版本（裸 semver——bin 与包根两级上溯；src 与 dist 同相对深度） */
+function readVersion() {
+    const pkgUrl = new URL('../../package.json', import.meta.url);
+    const pkg = JSON.parse(readFileSync(fileURLToPath(pkgUrl), 'utf8'));
+    return pkg.version ?? '0.0.0-unknown';
+}
+/** serve 分派三态：daemon child（env 标记）→ spawner（--daemon）→ stdio 前台 */
+function dispatchServe(flags) {
+    if (process.env[DAEMON_CHILD_ENV] === '1') {
+        // child 形态：HTTP 面常驻主体（spawner 已 detached + stderr 重定向 log）
+        return runDaemonServe({ flags, version: readVersion(), onRuntime: attachRuntime });
+    }
+    if (flags.daemon) {
+        // spawner 形态：spawn 自镜像后即退（起活确认窗内报结果；child 独立生命周期）
+        return spawnDaemonServe({ flags });
+    }
+    return runServeEntry({ flags, version: readVersion(), onRuntime: attachRuntime });
+}
+/** 执行器族（12c 空起——逐批充实；12e TUI / 13c serve stdio / 13e-3 daemon 编舞 + status/stop / 13f mcp 包装 / 12f-3 dump-config + plugins / 20b run / 20d sessions / g-2 doors 已接线，upgrade 诚实退 1） */
+const handlers = {
+    tui: (flags) => runTuiEntry({
+        flags,
+        version: readVersion(), // OSC title 基线真值（批 12 挂账兑现）
+        onRuntime: attachRuntime, // 信号/崩溃编舞切运行时本体
+    }),
+    serve: (flags) => dispatchServe(flags),
+    // run 单次执行（20b 接线——07 §5 run 旗标族全量消费位；tick 形 message 为
+    // 空串占位——提示词在 jobs 行内，由 run-entry 经行读取）
+    run: (message, flags) => runRunEntry({
+        message,
+        flags,
+        version: readVersion(),
+        onRuntime: attachRuntime, // 信号/崩溃编舞切运行时本体
+    }),
+    serveStatus: () => runServeStatus({ dataDir: resolveDataDir() }),
+    serveStop: () => runServeStop({ dataDir: resolveDataDir() }),
+    // MCP server 包装形态（13f 接线——零旗标面；serverInfo 版本真值同 tui 路径）
+    mcp: () => runMcpEntry({
+        version: readVersion(),
+        onRuntime: attachRuntime, // 信号/崩溃编舞切运行时本体
+    }),
+    // dump-config :memory: 同构诊断（12f-3——07 §5 禁侧门纪律，assembly 公共段）
+    dumpConfig: (flags) => runDumpConfigEntry({
+        flags,
+        version: readVersion(),
+        onRuntime: attachRuntime,
+    }),
+    // plugins 子命令族 CLI 面（12f-3——list 同构装配 / check 纯只读骨架 / 写侧六动词诚实退 1）
+    plugins: (sub) => runPluginsEntry(sub, {
+        version: readVersion(),
+        onRuntime: attachRuntime,
+    }),
+    // sessions 子命令族 CLI 面（20d——list/search/reindex 读腿零装配、resume 进
+    // TUI〔resumeSessionId 载体〕、fork 全装配同 run --fork 机；07 §5 定名）
+    sessions: (sub) => runSessionsEntry(sub, {
+        version: readVersion(),
+        onRuntime: attachRuntime, // fork/resume 装配路径——信号/崩溃编舞切运行时本体
+    }),
+    // credentials 子命令族 CLI 面（c-5——03 §10.9 人面命令：零装配直开库，
+    // 动词语义单源 credentials/commands 与 TUI /credentials 同底座）
+    credentials: (sub) => runCredentialsEntry(sub, {}),
+    // doors 子命令族 CLI 面（g-2——03 §4.6 / 07 §5 定名：list 只读零装配零库
+    // 纯文件读；open/close 合法解析形、执行层语义拒退 1——写动词 TUI /doors 专属）
+    doors: (sub) => runDoorsEntry(sub, {}),
+};
+/** 主序：编舞装配 → 分派 → 终局 */
+async function main() {
+    installCrashChoreography({
+        // 前置窗口（运行时未组装）直写缺省数据目录；组装后走运行时本体（memory 形跳过语义在其内）
+        writeCrashLog: (error) => {
+            if (activeRuntime !== null)
+                activeRuntime.writeCrashLog(error);
+            else
+                appendCrashLog(resolveDataDir(), error);
+        },
+    });
+    installSignalChoreography({
+        onGraceful: async () => {
+            await activeRuntime?.shutdown(); // 未组装 = 无优雅序可走，直退 0
+            return 0;
+        },
+    });
+    return dispatchCli(parseCli(argv.slice(2)), handlers, {
+        stdinIsTTY: stdin.isTTY === true,
+        stdoutIsTTY: stdout.isTTY === true,
+        writeOut: (text) => stdout.write(`${text}\n`),
+        writeErr: (text) => stderr.write(`${text}\n`),
+        version: readVersion(),
+    });
+}
+// 自动执行卫兵：仅主模块直跑（进程入口）才走主序——被 import 零副作用。
+// argv[1] 先 realpath 归一：入口模块 node 侧恒走真实路径解析，而 argv[1] 是
+// 调用面字面量——npm bin 符号链接或路径含符号链接环节（/tmp → /private/tmp、
+// nvm/volta shim 目录）两侧错配即静默 no-op 退 0（2026-09-08 发布面收口批
+// 安装冒烟逮到——真实装机路径含符号链接即坏，发布阻塞件）
+/**
+ * 主模块判定（bin 直跑卫兵）——argv[1] realpath 归一后对模块 URL 全等比对。
+ * @param argv1 进程 argv[1]（调用面字面量——可能是符号链接或含链接环节的路径）
+ * @param moduleUrl 本模块 import.meta.url（node 入口解析恒为真实路径）
+ */
+export function isMainModule(argv1, moduleUrl) {
+    if (argv1 === undefined)
+        return false;
+    try {
+        return pathToFileURL(realpathSync(argv1)).href === moduleUrl;
+    }
+    catch {
+        return false; // argv[1] 已不可解析（极端竞态）——按非主模块退
+    }
+}
+const isMain = isMainModule(argv[1], import.meta.url);
+if (isMain) {
+    void main()
+        .then((code) => processExit(code))
+        .catch((err) => {
+        // 主序自身抛错（编舞装配前的窄窗）——stderr 一行 + 执行失败档退
+        stderr.write(`启动失败：${err instanceof Error ? err.message : String(err)}\n`);
+        processExit(1);
+    });
+}

package/dist/host/manifest.js

@@ -0,0 +1,381 @@
+/**
+ * host/manifest — 插件清单契约与拒绝式形状校验（03 篇 §1.2/§1.3/§5.3）。
+ *
+ * 契约先行笔（批 12a）：形状类型 + 校验纯函数零副作用——jiti 装载、虚拟键
+ * 注入、时钟护栏等装载器机制归批 12d 实装笔消费本面。校验一律**拒绝式**
+ * （未知键拒载、坏形当场红——拼写错误不留静默通道），失败面统一 tagged
+ * union 不抛（调用方——装机腿/boot 合成腿——决定 fail-loud 还是行级隔离）。
+ *
+ * 复用件：清单 api 块形状与版本串判据单源在 contracts（ApiBlock /
+ * isValidApiVersion——§8.4 装载门同判据，不散拷）。
+ */
+import { join } from 'node:path';
+import { parseConfigSchemaFields } from './config-schema.js';
+import { isValidApiVersion } from '../contracts/index.js';
+// internal 桶机制符号深导（opens 授予位值域单源——02 §4.3 #2 深挖面册纪律）
+import { DOORS_SEGMENT_V1_DOMAIN, USER_GRANTABLE_CAPABILITIES } from '../contracts/api.js';
+/**
+ * 清单键目录（API 治理真相源⑤——03 §8.2「清单键与类型」；抽取器 jiti 导入
+ * 收割进 surface.json 的 manifest-keys 域）。校验闭集自本目录派生——键表增删
+ * 两路（目录 / parseManifest 未知键执法）同笔共变，结构性不可漂移。tier 全
+ * stable：清单键是插件作者依赖面（§1.2 拍板定形；§8.3「现役全 stable」同律）。
+ */
+export const MANIFEST_KEY_CATALOG = [
+    { key: 'id', tier: 'stable', desc: '插件 id；缺省取 package.json name，不合字符集须显式声明（无隐式映射变换）' },
+    { key: 'label', tier: 'stable', desc: '展示名；缺省取 id' },
+    { key: 'entry', tier: 'stable', desc: '入口文件（相对包根）；缺席走入口解析序三步' },
+    { key: 'grants', tier: 'stable', desc: '授权申请面；单维 writableRoots 字符串数组' },
+    {
+        key: 'config',
+        tier: 'stable',
+        desc: '宿主侧默认配置值（启用行 config 缺席时作 apply 的 config 实参；形状声明归 configSchema——2026-09-11 交互动词族批 schema/值分键）',
+    },
+    {
+        key: 'configSchema',
+        tier: 'stable',
+        desc: '配置字段声明面（字段描述数组——字段级校验与 /plugins config 表单渲染双消费源）',
+    },
+    { key: 'api', tier: 'stable', desc: 'API 治理块（minApiVersion/targetApiVersion/experimental）' },
+    { key: 'skills', tier: 'stable', desc: '技能目录清单；非空即在场的「声明载荷」之一（纯声明包零码装载）' },
+    {
+        key: 'agents',
+        tier: 'stable',
+        desc: '声明式子代理目录清单（06 §11.6 位 4；与 skills 同形——mount 即收集、物化消费腿挂 core:subagent 消费批）',
+    },
+];
+/** 清单块已知键闭集（未知键拒载——拒绝式而非忽略式；自目录派生单源） */
+const MANIFEST_KEYS = new Set(MANIFEST_KEY_CATALOG.map((k) => k.key));
+/** 插件 id 字符集：小写字母/数字/连字符，首字符非连字符（03 §1.2） */
+const PLUGIN_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+/** 官方前缀（core: 为官方插件保留——冒号仅许官方前缀位） */
+const CORE_PREFIX = 'core:';
+/**
+ * id 字符集校验（03 §1.2 前缀豁免句）。
+ *
+ * - 用户插件（official=false）：整串过字符集且**不含冒号**——起头 `core:` 或
+ *   含 `:` 一律拒（官方前缀保留 + 冒号仅许官方前缀位）；
+ * - 官方引用形（official=true，§1.4——core: 形状与磁盘插件同轨校验）：id 形如
+ *   `core:<name>` 时校验对象 = `<name>` 段过同一字符集。
+ */
+export function checkPluginId(id, opts) {
+    if (opts.official) {
+        if (!id.startsWith(CORE_PREFIX))
+            return PLUGIN_ID_RE.test(id) && !id.includes(':');
+        const name = id.slice(CORE_PREFIX.length);
+        return name.length > 0 && PLUGIN_ID_RE.test(name);
+    }
+    if (id.includes(':'))
+        return false;
+    return PLUGIN_ID_RE.test(id);
+}
+/**
+ * 解析并校验插件清单（纯函数）。
+ *
+ * 输入 = package.json 解析产物（JSON 对象——宿主侧 json/yaml 载体差异由调用方
+ * 抹平）；`official` 旗区分用户磁盘插件与 core: 官方引用形（§1.4 对象直调形态
+ * 的清单面也经本校验——同轨纪律）。失败一律 `PLUGIN_SHAPE_INVALID`，message
+ * 自带指路（缺省 id 不合字符集时指路清单显式声明 `berryAgent.id`——无隐式
+ * 映射变换，§1.2 拍板题 10）。
+ */
+export function parseManifest(pkg, opts = {}) {
+    const official = opts.official === true;
+    if (typeof pkg !== 'object' || pkg === null || Array.isArray(pkg)) {
+        return shapeFail('package.json 顶层须为对象');
+    }
+    const record = pkg;
+    const name = record['name'];
+    if (typeof name !== 'string' || name.length === 0) {
+        return shapeFail('package.json name 缺席或非非空字符串——插件包身份不可判定');
+    }
+    const block = record['berryAgent'];
+    if (block === undefined) {
+        // berryAgent 块缺席的包不是插件——install 拒绝（03 §1.2）
+        return shapeFail(`包 ${name} 无 berryAgent 字段——不是插件包（清单载体 = package.json 加字段，禁双载体）`);
+    }
+    if (typeof block !== 'object' || block === null || Array.isArray(block)) {
+        return shapeFail(`berryAgent 块须为对象（包 ${name}）`);
+    }
+    const manifest = block;
+    // 未知键拒载——拒绝式而非忽略式（拼写错误当场红）
+    for (const key of Object.keys(manifest)) {
+        if (!MANIFEST_KEYS.has(key)) {
+            return shapeFail(`berryAgent 未知键 "${key}"（包 ${name}）——已知键闭集：${[...MANIFEST_KEYS].join('/')}`);
+        }
+    }
+    // id：在场须字符串；缺省 = name；不合字符集即拒（缺省不合时指路显式声明）
+    let id;
+    if (manifest['id'] !== undefined) {
+        if (typeof manifest['id'] !== 'string' || manifest['id'].length === 0) {
+            return shapeFail(`berryAgent.id 须为非空字符串（包 ${name}）`);
+        }
+        id = manifest['id'];
+    }
+    else {
+        id = name;
+    }
+    if (!checkPluginId(id, { official })) {
+        return shapeFail(manifest['id'] === undefined
+            ? `缺省 id（= package.json name "${name}"）不合插件 id 字符集${official ? '' : '（含冒号或 core: 前缀保留）'}——在清单 berryAgent.id 显式声明合法 id（小写字母/数字/连字符，首字符非连字符；无隐式映射变换）`
+            : `berryAgent.id "${id}" 不合插件 id 字符集（小写字母/数字/连字符，首字符非连字符${official ? '；core: 前缀后段同判据' : '；冒号仅许官方前缀位——core: 为官方插件保留'}）`);
+    }
+    // label：缺省 = id；须字符串
+    let label = id;
+    if (manifest['label'] !== undefined) {
+        if (typeof manifest['label'] !== 'string' || manifest['label'].length === 0) {
+            return shapeFail(`berryAgent.label 须为非空字符串（插件 ${id}）`);
+        }
+        label = manifest['label'];
+    }
+    // version（package.json 顶层透传——git 源可缺席）
+    const version = record['version'];
+    if (version !== undefined && typeof version !== 'string') {
+        return shapeFail(`package.json version 须为字符串（插件 ${id}）`);
+    }
+    // entry：须字符串
+    if (manifest['entry'] !== undefined && (typeof manifest['entry'] !== 'string' || manifest['entry'].length === 0)) {
+        return shapeFail(`berryAgent.entry 须为非空字符串（插件 ${id}）`);
+    }
+    // grants：须对象（深校验 writableRoots 形随装载器批——本笔浅校验）
+    if (manifest['grants'] !== undefined) {
+        const grants = manifest['grants'];
+        if (typeof grants !== 'object' || grants === null || Array.isArray(grants)) {
+            return shapeFail(`berryAgent.grants 须为对象（插件 ${id}——申请面 { writableRoots: string[] }）`);
+        }
+        const roots = grants['writableRoots'];
+        if (roots !== undefined && (!Array.isArray(roots) || roots.some((r) => typeof r !== 'string'))) {
+            return shapeFail(`berryAgent.grants.writableRoots 须为字符串数组（插件 ${id}）`);
+        }
+    }
+    // config：须对象（宿主侧默认配置值——schema/值分键后值单源；secret 明文拒在 configSchema 解析后交叉判）
+    if (manifest['config'] !== undefined) {
+        const config = manifest['config'];
+        if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+            return shapeFail(`berryAgent.config 须为对象（插件 ${id}——宿主侧默认配置值）`);
+        }
+    }
+    // configSchema：字段描述数组深校验（ix-3——03 §1.2 configSchema 条款）+ 清单侧 secret 明文拒
+    let configSchema;
+    if (manifest['configSchema'] !== undefined) {
+        const parsed = parseConfigSchemaFields(manifest['configSchema'], { pluginId: id });
+        if (!parsed.ok) {
+            return shapeFail(parsed.message);
+        }
+        configSchema = parsed.fields;
+        // secret 明文拒（清单侧半边——宿主默认值位携 secret 键明文值拒；行 config 半边归装载器）
+        if (manifest['config'] !== undefined) {
+            const defaults = manifest['config'];
+            const leaked = configSchema.filter((f) => f.type === 'secret' && f.key in defaults).map((f) => f.key);
+            if (leaked.length > 0) {
+                return configFail(`清单 config 键携 secret 型键明文值（插件 ${id}：${leaked.join('、')}）——从 package.json 删该键、走表单/凭证盒（package.json 随 npm 分发明文更烈）`);
+            }
+        }
+    }
+    // api 块：形状 + 版本串判据（单源 contracts——isValidApiVersion 同判据）
+    let api;
+    if (manifest['api'] !== undefined) {
+        const rawApi = manifest['api'];
+        if (typeof rawApi !== 'object' || rawApi === null || Array.isArray(rawApi)) {
+            return shapeFail(`berryAgent.api 须为对象（插件 ${id}）`);
+        }
+        const apiRecord = rawApi;
+        for (const key of Object.keys(apiRecord)) {
+            if (key !== 'minApiVersion' && key !== 'targetApiVersion' && key !== 'experimental') {
+                return shapeFail(`berryAgent.api 未知键 "${key}"（插件 ${id}）——闭集：minApiVersion/targetApiVersion/experimental`);
+            }
+        }
+        if (typeof apiRecord['minApiVersion'] !== 'string' || !isValidApiVersion(apiRecord['minApiVersion'])) {
+            return shapeFail(`berryAgent.api.minApiVersion 缺席或坏形（插件 ${id}——应为 MAJOR.MINOR 整数点分两段，如 "1.0"）`);
+        }
+        let targetApiVersion;
+        if (apiRecord['targetApiVersion'] !== undefined) {
+            if (typeof apiRecord['targetApiVersion'] !== 'string' || !isValidApiVersion(apiRecord['targetApiVersion'])) {
+                return shapeFail(`berryAgent.api.targetApiVersion 坏形（插件 ${id}——应为 MAJOR.MINOR 整数点分两段）`);
+            }
+            targetApiVersion = apiRecord['targetApiVersion'];
+            if (versionPairLt(targetApiVersion, apiRecord['minApiVersion'])) {
+                return shapeFail(`berryAgent.api targetApiVersion < minApiVersion（插件 ${id}——行为锚不得低于硬地板）`);
+            }
+        }
+        let experimental;
+        if (apiRecord['experimental'] !== undefined) {
+            if (!Array.isArray(apiRecord['experimental']) ||
+                apiRecord['experimental'].some((k) => typeof k !== 'string' || k.length === 0)) {
+                return shapeFail(`berryAgent.api.experimental 须为非空字符串数组（插件 ${id}）`);
+            }
+            experimental = apiRecord['experimental'];
+        }
+        api = { minApiVersion: apiRecord['minApiVersion'], targetApiVersion, experimental };
+    }
+    // skills：须字符串数组（非空数组即在场的「声明载荷」之一）
+    let skills;
+    if (manifest['skills'] !== undefined) {
+        if (!Array.isArray(manifest['skills']) || manifest['skills'].some((s) => typeof s !== 'string' || s.length === 0)) {
+            return shapeFail(`berryAgent.skills 须为非空字符串数组（插件 ${id}——技能目录清单）`);
+        }
+        skills = manifest['skills'];
+    }
+    // agents：声明式子代理目录清单（§6.3——与 skills 同形同判据；生态启动批
+    // eco-1 键收下：entryPlan 判定同认「声明载荷」，装载收集在 loader）
+    let agents;
+    if (manifest['agents'] !== undefined) {
+        if (!Array.isArray(manifest['agents']) || manifest['agents'].some((s) => typeof s !== 'string' || s.length === 0)) {
+            return shapeFail(`berryAgent.agents 须为非空字符串数组（插件 ${id}——声明式子代理目录清单）`);
+        }
+        agents = manifest['agents'];
+    }
+    // 入口解析序三步定死（03 §1.2——声明载荷 = skills/agents 任一非空即第②步）
+    const entry = manifest['entry'];
+    const declaredPayload = (skills !== undefined && skills.length > 0) || (agents !== undefined && agents.length > 0);
+    const entryPlan = entry !== undefined
+        ? { kind: 'entry-file', entry }
+        : declaredPayload
+            ? { kind: 'declared-payload' }
+            : { kind: 'default-export' };
+    return {
+        ok: true,
+        manifest: {
+            id,
+            label,
+            version,
+            entry,
+            grants: manifest['grants'],
+            config: manifest['config'],
+            configSchema,
+            api,
+            skills,
+            agents,
+            entryPlan,
+        },
+    };
+}
+/** 形状失败速记（同码分流——install 拒绝与形状违例共用 PLUGIN_SHAPE_INVALID） */
+function shapeFail(message) {
+    return { ok: false, code: 'PLUGIN_SHAPE_INVALID', message };
+}
+/** 值违例失败（secret 明文拒专用——PLUGIN_CONFIG_INVALID 面） */
+function configFail(message) {
+    return { ok: false, code: 'PLUGIN_CONFIG_INVALID', message };
+}
+/** [major, minor] 数值比较：a < b（判据调用方保证两串已过格式校验） */
+function versionPairLt(a, b) {
+    const [amaj, amin] = a.split('.').map(Number);
+    const [bmaj, bmin] = b.split('.').map(Number);
+    return amaj !== bmaj ? amaj < bmaj : amin < bmin;
+}
+/* ---------------- 启用清单行（enabled.yaml——03 §5.3 单层 overlay） ---------------- */
+/**
+ * 启用清单文件路径（数据目录下单文件——boot 读侧与 fire 复检活体读侧共用
+ * 单源；C 批 C-3：plugin-boot 与 triggers 活体开门读取都经本函数取路径）。
+ */
+export function enabledYamlPath(dataDir) {
+    return join(dataDir, 'enabled.yaml');
+}
+/** 行 schema 已知键闭集 */
+const ROW_KEYS = new Set(['id', 'config', 'disabled', 'opens']);
+/** 顶层文档已知键闭集（plugins + doors——未知顶层键拒绝式，与行键同律） */
+const DOC_KEYS = new Set(['plugins', 'doors']);
+/**
+ * 校验启用清单行集（纯函数——输入 = yaml.load 产物，载体解析在装配层）。
+ *
+ * 逐行拒绝式：未知键 / id 缺席或坏形 / disabled 非布尔 / config 非对象 /
+ * opens 坏形或值域外 / core: 行带 opens 即拒，message 点名行序与插件 id。
+ * **同 id 多行即拒**（§5.3「单行 per id——行 schema 无多行载体」；uninstall
+ * 段①防线同判据）。用户行 id 不校验 core: 保留——用户行覆盖 core: 同名行
+ * 是合法形态（字段级后写胜出），core: 行自身不进用户文件（内置全启）；
+ * 覆盖合法性由装配层合成时裁决。
+ *
+ * 顶层两查（开门制扩展批 2026-09-09 增）：未知顶层键拒（闭集 plugins/doors
+ * ——无闭集则 `door:` 之类的段名手误将被静默忽略 = 静默不授予，拒绝式不留
+ * 静默通道）；`doors` 段坏形（非数组/空串/值域外）拒——值域 v1 =
+ * DOORS_SEGMENT_V1_DOMAIN 两门枚举（射程即值域，§8.2 名单系上界；六枚全宽
+ * 将致「清单呈现开、门检实效关」三读分叉），PLUGIN_ROW_INVALID 同门。
+ */
+export function parseEnabledRows(doc) {
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+        return rowFail('启用清单顶层须为对象 { plugins: [行...], doors?: [...] }');
+    }
+    const record = doc;
+    for (const key of Object.keys(record)) {
+        if (!DOC_KEYS.has(key)) {
+            return rowFail(`启用清单顶层未知键 "${key}"——已知键闭集：plugins/doors`);
+        }
+    }
+    const plugins = record['plugins'];
+    if (!Array.isArray(plugins)) {
+        return rowFail('启用清单 plugins 须为数组（行 schema：{ id, config?, disabled?, opens? }）');
+    }
+    // doors 段三查（03 §5.3 开门制扩展批增段——拒绝式不留静默通道）
+    let doors;
+    if (record['doors'] !== undefined) {
+        const rawDoors = record['doors'];
+        if (!Array.isArray(rawDoors) || rawDoors.some((d) => typeof d !== 'string' || d.length === 0)) {
+            return rowFail('启用清单顶层 doors 须为非空字符串数组（模型道高危面开门授予段——03 §4.6 双源并集律第二源）');
+        }
+        const values = rawDoors;
+        const illegal = values.find((d) => !DOORS_SEGMENT_V1_DOMAIN.includes(d));
+        if (illegal !== undefined) {
+            return rowFail(`启用清单顶层 doors 含非法能力位 "${illegal}"——值域 v1 = 两门枚举（现役：${DOORS_SEGMENT_V1_DOMAIN.join('、')}；§8.2 高危面名单系上界，扩枚随后续模型道高危面立题放宽）`);
+        }
+        doors = values;
+    }
+    const rows = [];
+    const seen = new Set();
+    for (let i = 0; i < plugins.length; i++) {
+        const row = plugins[i];
+        if (typeof row !== 'object' || row === null || Array.isArray(row)) {
+            return rowFail(`第 ${i + 1} 行须为对象（行 schema：{ id, config?, disabled?, opens? }）`);
+        }
+        const record = row;
+        for (const key of Object.keys(record)) {
+            if (!ROW_KEYS.has(key)) {
+                return rowFail(`第 ${i + 1} 行未知键 "${key}"——已知键闭集：id/config/disabled/opens`);
+            }
+        }
+        if (typeof record['id'] !== 'string' || record['id'].length === 0) {
+            return rowFail(`第 ${i + 1} 行 id 缺席或非非空字符串——id 即装机账本键`);
+        }
+        const id = record['id'];
+        // 用户行 id 过基础字符集（含 core: 前缀——覆盖官方行合法；校验 = 官方式前缀豁免）
+        if (!checkPluginId(id, { official: true })) {
+            return rowFail(`第 ${i + 1} 行 id "${id}" 坏形（小写字母/数字/连字符；官方前缀 core:<name> 后段同判据）`);
+        }
+        if (seen.has(id)) {
+            return rowFail(`插件 ${id} 多行——单行 per id（行 schema 无多行载体）`);
+        }
+        seen.add(id);
+        if (record['disabled'] !== undefined && typeof record['disabled'] !== 'boolean') {
+            return rowFail(`插件 ${id} 行 disabled 须为布尔`);
+        }
+        if (record['config'] !== undefined &&
+            (typeof record['config'] !== 'object' || record['config'] === null || Array.isArray(record['config']))) {
+            return rowFail(`插件 ${id} 行 config 须为对象（整值替换非合并）`);
+        }
+        // opens 三查（03 §4.6/§5.3 批 U1 增位——拒绝式不留静默通道）
+        let opens;
+        if (record['opens'] !== undefined) {
+            if (!Array.isArray(record['opens']) || record['opens'].some((o) => typeof o !== 'string' || o.length === 0)) {
+                return rowFail(`插件 ${id} 行 opens 须为非空字符串数组（高危面开门授予位——03 §4.6）`);
+            }
+            const values = record['opens'];
+            const illegal = values.find((o) => !USER_GRANTABLE_CAPABILITIES.includes(o));
+            if (illegal !== undefined) {
+                return rowFail(`插件 ${id} 行 opens 含非法能力位 "${illegal}"——值域 = 高危面名单单源（现役：${USER_GRANTABLE_CAPABILITIES.join('、')}；常规能力位不走开门制）`);
+            }
+            if (id.startsWith('core:')) {
+                return rowFail(`官方件 ${id} 行不设 opens——core: 件高危面窄面注入走宿主装配裁决，不走用户开门位（03 §4.6 治理判据：开门不可被静默继承）`);
+            }
+            opens = values;
+        }
+        rows.push({
+            id,
+            config: record['config'],
+            disabled: record['disabled'] === undefined ? undefined : record['disabled'],
+            ...(opens !== undefined ? { opens } : {}),
+        });
+    }
+    return { ok: true, rows, doors: doors ?? [] };
+}
+/** 行失败速记 */
+function rowFail(message) {
+    return { ok: false, code: 'PLUGIN_ROW_INVALID', message };
+}

package/dist/host/mcp-entry.js

@@ -0,0 +1,53 @@
+import { stdin, stdout, stderr } from 'node:process';
+import { runMcpFace } from '../sdk/index.js';
+import { assembleHostStack } from './assembly.js';
+import { createServeBridge } from './serve-entry.js';
+/**
+ * mcp 主入口。阻塞至调用方收线（stdin EOF = 对端 agent 退出）/ 信号（经
+ * main 编舞 → runtime.shutdown → closer → face.dispose）/ 传输面坏死；
+ * 返回进程退出码。
+ */
+export async function runMcpEntry(options) {
+    // —— 装配公共段（批 19a-3 迁 assembly 件——与 TUI 同一合成代码路径；
+    // debug 恒 false：零旗标律〔07 §5〕，日志级只走 env）——
+    const assembly = await assembleHostStack({
+        runtime: {
+            ...(options.dataDir !== undefined ? { dataDir: options.dataDir } : {}),
+            ...(options.memory === true ? { memory: true } : {}),
+        },
+        noPlugins: false,
+        debug: false,
+        version: options.version ?? '0.0.0-unknown',
+        ...(options.providers !== undefined ? { providers: options.providers } : {}),
+        ...(options.model !== undefined ? { model: options.model } : {}),
+        ...(options.env !== undefined ? { env: options.env } : {}),
+        ...(options.sandboxMode !== undefined ? { sandboxMode: options.sandboxMode } : {}),
+        ...(options.onRuntime !== undefined ? { onRuntime: options.onRuntime } : {}),
+    });
+    if (!assembly.ok) {
+        stderr.write(`${assembly.crashed ? `mcp 运行失败：${assembly.message}` : assembly.message}\n`);
+        return assembly.exitCode;
+    }
+    const { runtime, stack, logger } = assembly;
+    let exitCode = 0;
+    try {
+        const bridge = createServeBridge(stack, runtime, { cwd: options.cwd ?? process.cwd() });
+        const face = runMcpFace({
+            io: options.io ?? { input: stdin, output: stdout },
+            bridge,
+            serverInfo: { name: 'berry-agent', version: options.version ?? '0.0.0-unknown' }, // 对外声明值位
+            log: (message) => logger.warn(message),
+        });
+        stack.channels.addBackend(face.backend); // 信封回流自动馈送（conversation-stack onEvent → emit）
+        // 信号路优雅档：六步退出序经 closer 收口 face（幂等）；EOF 路径 face 自决
+        runtime.registerCloser({ label: 'mcp-face', fn: () => Promise.resolve(face.dispose()) });
+        exitCode = await face.done; // EOF 0 / 传输面坏死 1
+        await runtime.shutdown().catch(() => { }); // 六步退出序（closer 内已 dispose——幂等双保险）
+    }
+    catch (err) {
+        runtime.writeCrashLog(err); // 崩溃取证先行（memory 形跳过——件内语义）
+        stderr.write(`mcp 运行失败：${err instanceof Error ? err.message : String(err)}\n`);
+        exitCode = 1;
+    }
+    return exitCode;
+}