berry-agent 0.1.0-alpha.1

package/dist/browser/service.js

@@ -0,0 +1,158 @@
+/**
+ * browser 编排件（03 §10.3 生命周期条款的执法位）。
+ *
+ * - 惰性首用：apply 零 spawn（「装载在场」≠「引擎在场」——零工具调用 =
+ *   零进程零连接）；首个工具调用才经 launchBrowserEngine 起引擎。
+ * - 会话路由：contexts Map by toolCtx.sessionId（?? 'default'）——每键一
+ *   BrowserPage（专属 BrowserContext，cookies/storage/缓存会话间隔离）。
+ * - 两级闲置回收（context 级 + 引擎级各 idleMs 缺省 300s）：自续 setTimeout
+ *   链扫掠（unref 不阻进程退出）——context 闲置即 dispose；全 context 空
+ *   且引擎闲置即协议化关停。非钩子驱动（页面态不跨进程恢复——durable 只落
+ *   工具事件）。
+ * - 引擎降级：spawn/运行期死 → enginePromise 清空 + 全 context 收口，下用
+ *   再试（BROWSER_CONNECT_FAILED 不炸宿主）；失败路径 launchPromise 同清
+ *   （启动失败不粘住）。
+ * - scope.effect 回卷：作用域 dispose 即 shutdown（页面全关 + 引擎关 +
+ *   工具面注销）。
+ * - 云端占位：config.providers 在场即 notify「引擎恒本地」（v1 执行面零接）。
+ */
+import { launchBrowserEngine } from './engine.js';
+import { createBrowserPage } from './page.js';
+import { buildBrowserTools } from './tools.js';
+import { BROWSER_IDLE_MS, BROWSER_SWEEP_INTERVAL_MS } from './types.js';
+/**
+ * 组 browser 编排（装载批装配根消费）。
+ * 生命周期：apply 起扫掠；scope 回卷或显式 shutdown 收口。
+ */
+export function createBrowserService(deps) {
+    const idleMs = deps.idleMs ?? BROWSER_IDLE_MS;
+    const sweepIntervalMs = deps.sweepIntervalMs ?? BROWSER_SWEEP_INTERVAL_MS;
+    const now = () => deps.clock?.() ?? Date.now();
+    let enginePromise;
+    /** 会话页面账（sessionKey → 页面 + 末用时刻——闲置回收判据） */
+    const contexts = new Map();
+    /** 引擎末用时刻（全 context 空时的引擎级闲置判据） */
+    let engineLastUsed = 0;
+    let sweepTimer;
+    let disposed = false;
+    const unregisters = [];
+    /** 惰性引擎（失败/降级即清——下用再试） */
+    const ensureEngine = () => {
+        if (enginePromise === undefined) {
+            engineLastUsed = now();
+            const launcher = deps.launchEngine ?? launchBrowserEngine;
+            enginePromise = launcher({
+                spawn: deps.spawn,
+                ws: deps.ws,
+                fs: deps.fs,
+                readEnv: deps.readEnv,
+                platform: deps.platform,
+                homeDir: deps.homeDir,
+                dataDir: deps.dataDir,
+                config: deps.config,
+                ...(deps.logger !== undefined ? { logger: deps.logger } : {}),
+            })
+                .then((handle) => {
+                // 引擎级降级双源（进程退/ws 关）：清粘滞 + 全 context 收口——
+                // 页面 send 已被 cdp 件快拒，close 幂等吞错
+                handle.onDown((reason) => {
+                    enginePromise = undefined;
+                    deps.notify?.(`browser：引擎已降级（${reason}）——下次使用时重试`);
+                    for (const entry of contexts.values())
+                        void entry.page.close().catch(() => { });
+                    contexts.clear();
+                });
+                return handle;
+            })
+                .catch((err) => {
+                enginePromise = undefined; // 启动失败不粘住（下用再试）
+                throw err;
+            });
+        }
+        return enginePromise;
+    };
+    /** 扫掠一步：context 级 → 引擎级（自续链 unref） */
+    const sweep = () => {
+        if (disposed)
+            return;
+        const t = now();
+        for (const [key, entry] of contexts) {
+            if (t - entry.lastUsed >= idleMs) {
+                contexts.delete(key);
+                void entry.page.close().catch(() => { });
+                deps.logger?.debug?.(`browser 闲置回收：context ${key}（${idleMs}ms 未用）`);
+            }
+        }
+        // 引擎级：全 context 空 + 引擎闲置 → 协议化关停（页面态不跨进程恢复）
+        if (contexts.size === 0 && enginePromise !== undefined && t - engineLastUsed >= idleMs) {
+            const closing = enginePromise;
+            enginePromise = undefined;
+            void closing.then((handle) => handle.close()).catch(() => { });
+            deps.logger?.debug?.('browser 闲置回收：引擎协议化关停');
+        }
+        sweepTimer = setTimeout(sweep, sweepIntervalMs);
+        sweepTimer.unref();
+    };
+    const service = {
+        apply() {
+            // 云端占位（03 §10.3：providers 在场即通知——v1 执行面零接）
+            if (deps.config.providers !== undefined && deps.config.providers.length > 0) {
+                deps.notify?.('browser：云端 providers 已配置——v1 未接云端执行面，引擎恒本地');
+            }
+            if (deps.register !== undefined) {
+                for (const def of buildBrowserTools({ pageFor: (key) => service.pageFor(key) })) {
+                    unregisters.push(deps.register.register(def));
+                }
+            }
+            if (deps.scope !== undefined) {
+                deps.scope.effect(() => () => {
+                    void service.shutdown();
+                });
+            }
+            sweepTimer = setTimeout(sweep, sweepIntervalMs);
+            sweepTimer.unref();
+        },
+        async pageFor(sessionKey) {
+            const existing = contexts.get(sessionKey);
+            if (existing !== undefined) {
+                existing.lastUsed = now();
+                return existing.page;
+            }
+            engineLastUsed = now();
+            const engine = await ensureEngine();
+            const page = await createBrowserPage({
+                conn: engine.conn,
+                fs: deps.fs,
+                dataDir: deps.dataDir,
+                web: deps.web,
+                ...(deps.logger !== undefined ? { logger: deps.logger } : {}),
+            });
+            // 并发竞态：建页期间（引擎首启慢）同键可能已入账——后建让先建
+            const raced = contexts.get(sessionKey);
+            if (raced !== undefined) {
+                void page.close().catch(() => { });
+                raced.lastUsed = now();
+                return raced.page;
+            }
+            contexts.set(sessionKey, { page, lastUsed: now() });
+            return page;
+        },
+        async shutdown() {
+            disposed = true;
+            if (sweepTimer !== undefined)
+                clearTimeout(sweepTimer);
+            for (const unregister of unregisters.splice(0))
+                unregister();
+            const entries = [...contexts.values()];
+            contexts.clear();
+            const closingEngine = enginePromise;
+            enginePromise = undefined;
+            // 全收口 best-effort（引擎死态页面 close 幂等吞错）
+            await Promise.allSettled([
+                ...entries.map((e) => e.page.close()),
+                ...(closingEngine !== undefined ? [closingEngine.then((h) => h.close())] : []),
+            ]);
+        },
+    };
+    return service;
+}

package/dist/browser/tools.js

@@ -0,0 +1,198 @@
+/**
+ * browser 工具面十件（03 §10.3 工具面条款——navigate/back/forward/snapshot/
+ * click/type/press/scroll/screenshot/console）。
+ *
+ * effect 分账：交互族七件 'write'（navigate/back/forward/click/type/press/
+ * scroll——改变页面状态的世界动作，走三段管道审批 fail-closed）；读族三件
+ * 'read'（snapshot/screenshot/console——只读观测）。
+ *
+ * 会话路由：toolCtx.sessionId 缺席折 'default'（无会话语境的调用方共一页
+ * 面——诚实简化非隔离缺失）。
+ *
+ * 失败编码为 isError 数据面（03 §2.3）——BaseError 携码前置披露（判别收紧：
+ * Node 系统错误也带 code 属性，只认注册码体系成员）。
+ */
+import { BaseError } from '../contracts/index.js';
+import { Type } from 'typebox';
+/** 命名键词表（press 工具 schema 收词面——运行时词表在 page 件单源） */
+const PRESS_KEYS = [
+    'Enter',
+    'Tab',
+    'Escape',
+    'Backspace',
+    'Delete',
+    'ArrowUp',
+    'ArrowDown',
+    'ArrowLeft',
+    'ArrowRight',
+    'Home',
+    'End',
+    'PageUp',
+    'PageDown',
+    'Space',
+];
+/** toolCtx → 会话键（sessionId 缺席折 'default'） */
+function sessionKeyOf(toolCtx) {
+    const sid = toolCtx?.sessionId;
+    return typeof sid === 'string' && sid !== '' ? sid : 'default';
+}
+/** 结果编码两分：成功面拼模型可见文本；失败面 isError（携码前置） */
+function ok(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function fail(error) {
+    const code = error instanceof BaseError ? error.code : undefined;
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: 'text', text: code ? `[${code}] ${message}` : message }], isError: true };
+}
+/** 参数窄化取串（schema 已校验——防御位） */
+const str = (args, key) => String(args[key] ?? '');
+/**
+ * 组工具面十件（装载批由装配根经注册窄面挂入工具注册表）。
+ * @param source 会话路由后的页面取用面（service 注入）
+ */
+export function buildBrowserTools(source) {
+    /** 执行包装：会话路由 + 失败编码统一（fn 收页面与已校验参数） */
+    const run = (fn) => {
+        return async (args, toolCtx) => {
+            try {
+                const page = await source.pageFor(sessionKeyOf(toolCtx));
+                return ok(await fn(page, args));
+            }
+            catch (error) {
+                return fail(error);
+            }
+        };
+    };
+    return [
+        {
+            name: 'navigate',
+            description: '导航当前页面到指定 URL（http/https）。入口 URL 先过安全卫生件（私网/环回' +
+                '地址拒绝）；自动跟随服务端重定向，回执给最终 URL。页面加载完成（load 事件）后才返回。',
+            parameters: Type.Object({ url: Type.String({ description: '完整 URL（须含 http:// 或 https://）' }) }, { additionalProperties: false }),
+            effect: 'write',
+            timeoutMs: 45_000,
+            execute: run(async (page, args) => {
+                const r = await page.navigate(str(args, 'url'));
+                return `已导航到 ${r.url}`;
+            }),
+        },
+        {
+            name: 'back',
+            description: '浏览器后退一步（导航史前一步）。无前史时回执「无前一步」不算错误。',
+            parameters: Type.Object({}, { additionalProperties: false }),
+            effect: 'write',
+            timeoutMs: 45_000,
+            execute: run(async (page) => {
+                const r = await page.back();
+                return r.moved ? `已后退到 ${r.url}` : '已在最早一页（无前一步可退）';
+            }),
+        },
+        {
+            name: 'forward',
+            description: '浏览器前进一步（导航史后一步）。无后史时回执「无后一步」不算错误。',
+            parameters: Type.Object({}, { additionalProperties: false }),
+            effect: 'write',
+            timeoutMs: 45_000,
+            execute: run(async (page) => {
+                const r = await page.forward();
+                return r.moved ? `已前进到 ${r.url}` : '已在最新一页（无后一步可进）';
+            }),
+        },
+        {
+            name: 'snapshot',
+            description: '取当前页面可交互元素清单（a11y 快照）——每个元素一行（角色 + 可见名 + ' +
+                '可选 href/name），锚形如 [ref=@e1]。click/type 用回执中的 ref 锚定位元素；' +
+                '每次快照重建锚表（旧锚作废）。页面结构变化后应重新快照。',
+            parameters: Type.Object({}, { additionalProperties: false }),
+            effect: 'read',
+            timeoutMs: 30_000,
+            execute: run(async (page) => page.snapshot()),
+        },
+        {
+            name: 'click',
+            description: '点击快照中的元素（ref 锚定位）。元素若在折叠线外会先自动滚入视口再点击。' +
+                'ref 不在当前快照（过期/未取）即报错——先 snapshot。',
+            parameters: Type.Object({ ref: Type.String({ description: 'snapshot 回执中的锚（形如 @e1）' }) }, { additionalProperties: false }),
+            effect: 'write',
+            timeoutMs: 30_000,
+            execute: run(async (page, args) => {
+                await page.click(str(args, 'ref'));
+                return `已点击 ${str(args, 'ref')}`;
+            }),
+        },
+        {
+            name: 'type',
+            description: '向快照中的输入框键入文本（ref 锚定位；整体插入不改写法——适合表单填充）。' + '目标会先自动滚入视口并获得焦点。',
+            parameters: Type.Object({
+                ref: Type.String({ description: 'snapshot 回执中的锚（形如 @e1）' }),
+                text: Type.String({ description: '要键入的文本' }),
+            }, { additionalProperties: false }),
+            effect: 'write',
+            timeoutMs: 30_000,
+            execute: run(async (page, args) => {
+                await page.type(str(args, 'ref'), str(args, 'text'));
+                return `已键入 ${str(args, 'text').length} 字符到 ${str(args, 'ref')}`;
+            }),
+        },
+        {
+            name: 'press',
+            description: '按键（命名键词表：Enter/Tab/Escape/Backspace/Delete/方向键/Home/End/PageUp/PageDown/Space；或任意单字符）。',
+            parameters: Type.Object({
+                key: Type.Union([
+                    ...PRESS_KEYS.map((k) => Type.Literal(k)),
+                    Type.String({ pattern: '^[\\s\\S]$' }), // 单字符（含空格）
+                ], { description: '命名键或单字符' }),
+            }, { additionalProperties: false }),
+            effect: 'write',
+            timeoutMs: 30_000,
+            execute: run(async (page, args) => {
+                await page.press(str(args, 'key'));
+                return `已按键 ${str(args, 'key')}`;
+            }),
+        },
+        {
+            name: 'scroll',
+            description: '滚动页面（缺省向下 600 像素）。direction 二值 up/down；amount 为像素量（1~10000）。',
+            parameters: Type.Object({
+                direction: Type.Optional(Type.Union([Type.Literal('up'), Type.Literal('down')], { description: '方向（缺省 down）' })),
+                amount: Type.Optional(Type.Integer({ minimum: 1, maximum: 10_000, description: '像素量（缺省 600）' })),
+            }, { additionalProperties: false }),
+            effect: 'write',
+            timeoutMs: 30_000,
+            execute: run(async (page, args) => {
+                const raw = args;
+                const direction = raw.direction === 'up' ? 'up' : 'down';
+                const amount = typeof raw.amount === 'number' ? raw.amount : 600;
+                await page.scroll(direction, amount);
+                return `已${direction === 'down' ? '向下' : '向上'}滚动 ${amount} 像素`;
+            }),
+        },
+        {
+            name: 'screenshot',
+            description: '截取当前视口 PNG，落数据目录可取阅位（滚动保留最近 20 张），回执给文件路径与字节数。',
+            parameters: Type.Object({}, { additionalProperties: false }),
+            effect: 'read',
+            timeoutMs: 30_000,
+            execute: run(async (page) => {
+                const r = await page.screenshot();
+                return `截图已保存：${r.path}（${r.bytes} 字节）`;
+            }),
+        },
+        {
+            name: 'console',
+            description: '读取页面 console 回流（log/warn/error 与未捕获异常，本页面上下文创建以来累积，环形上限 200 条）。',
+            parameters: Type.Object({ limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 200, description: '取最近 N 条（缺省 50）' })) }, { additionalProperties: false }),
+            effect: 'read',
+            timeoutMs: 15_000,
+            execute: run(async (page, args) => {
+                const raw = args;
+                const limit = typeof raw.limit === 'number' ? raw.limit : 50;
+                const entries = await page.consoleLog(limit);
+                if (entries.length === 0)
+                    return '（本页面上下文尚无 console 输出）';
+                return entries.map((e) => `[${e.kind === 'exception' ? 'exception' : e.level}] ${e.text}`).join('\n');
+            }),
+        },
+    ];
+}

package/dist/browser/types.js

@@ -0,0 +1,81 @@
+/**
+ * core:browser 类型面（03 §10.3——CDP 手写最小桥 + 引擎发现序 + 十工具；
+ * 批 17b-2 传输层腿）。
+ *
+ * 词面独立律（02 §4.1 席 19 deps = contracts + web + persist）：spawn 与
+ * 工具注册全经**窄面注入**消费（mcp/lsp 先例同律——本件与 exec/tools 零 DAG
+ * 边）：
+ * - `BrowserSpawnFace` 与 exec SpawnPipeline.spawnInteractive 结构兼容（组合
+ *   根直接传管道真身；兼容性互证测试在 compat.test.ts）；
+ * - `BrowserRegisterToolsFace` 与 tools ToolRegistry.register 子面结构兼容
+ *   （返回注销器 = 撤工具面）；
+ * - `BrowserScopeFace` 与 context Scope 的 effect/isDisposed 子面结构兼容
+ *   （ctx.effect 回卷 + 续段 scope 活查）；
+ * - logger 窄面（本件无 context 边——createLogger 不可 import，装配根传真
+ *   身、缺省 no-op 测试静默）。
+ *
+ * web 席边为真消费（卫生单源复用——navigate 入口 URL 经 WebFetchService
+ * 同一 execute 跑五卫生件 + 同一在飞门实例，「两消费面同一 execute 同一限
+ * 流」的第三消费位）。persist 席边留白（v1 账本/截图走数据目录文件面——
+ * 页面态永不跨进程恢复，durable 只落工具事件不落页面态）。
+ */
+import { BaseError } from '../contracts/index.js';
+/* ---------------- 常量（缺省值单源——03 §10.3 生命周期与回收条款） ---------------- */
+/** 引擎启动预算 ms（spawn → DevTools 侦听行 → ws 建立 → Browser.getVersion 同罩） */
+export const BROWSER_STARTUP_TIMEOUT_MS = 20_000;
+/** 单条 CDP 命令缺省钟 ms（命令级超时——连接级失败分账 BROWSER_CONNECT_FAILED） */
+export const BROWSER_CDP_COMMAND_TIMEOUT_MS = 15_000;
+/** 两级闲置回收缺省（03 §10.3：context 级与引擎级各 300s） */
+export const BROWSER_IDLE_MS = 300_000;
+/** 闲置扫掠间隔 ms（自续 setTimeout 链——unref 不阻进程退出） */
+export const BROWSER_SWEEP_INTERVAL_MS = 5_000;
+/** 引擎协议化关停宽限 ms（Browser.close → 宽限等退 → kill 兜底） */
+export const BROWSER_CLOSE_GRACE_MS = 3_000;
+/** stderr DevTools 侦听行解析（Chrome 系引擎 --remote-debugging-port=0 唯一出口） */
+export const DEVTOOLS_LISTENING_RE = /DevTools listening on (ws:\/\/\S+)/;
+/** 导航预算 ms（Page.navigate 发出 → loadEventFired 等待同罩——慢页面不误杀） */
+export const BROWSER_NAV_TIMEOUT_MS = 30_000;
+/** console 环形缓冲帽（Runtime.consoleAPICalled/exceptionThrown 累积——超帽弃最旧） */
+export const BROWSER_CONSOLE_RING_CAP = 200;
+/** 截图滚动清理保留数（落数据目录可取阅位——超量弃最旧，图像字节永不进 durable） */
+export const BROWSER_SCREENSHOT_KEEP = 20;
+/** 截图子目录名（`${dataDir}/browser/` 下——与 engine/profile 同级） */
+export const BROWSER_SCREENSHOT_DIRNAME = 'screenshots';
+/** 引擎 spawn 归属名（登记簿同册——三桥同律） */
+export const BROWSER_ENGINE_OWNER = 'browser:engine';
+/**
+ * 引擎最小 env 白名单（deny-by-default 同律 exec）：Chrome headless 实测
+ * 需 HOME（用户数据目录解析）与 PATH（ crashpad 报告器自寻）；TMPDIR/locale
+ * 为崩溃报告与字体定位保底。零继承宿主其余变量（凭证面封死）。
+ */
+export const BROWSER_ENGINE_ENV_ALLOW = ['HOME', 'PATH', 'TMPDIR', 'LANG', 'LC_ALL'];
+/**
+ * 归一 config.browser（坏形响亮拒 BROWSER_CONFIG_INVALID）。
+ * undefined/null → 空配置（缺省行惰性无害零 spawn——零工具调用 = 零进程零连接）。
+ */
+export function normalizeBrowserConfig(raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new BaseError('BROWSER_CONFIG_INVALID', 'config.browser 须为对象');
+    }
+    const v = raw;
+    let executablePath;
+    if (v.executablePath !== undefined) {
+        if (typeof v.executablePath !== 'string' || v.executablePath === '') {
+            throw new BaseError('BROWSER_CONFIG_INVALID', `browser.executablePath 须为非空字符串（引擎可执行绝对路径）：${JSON.stringify(v.executablePath)}`);
+        }
+        executablePath = v.executablePath;
+    }
+    let providers;
+    if (v.providers !== undefined) {
+        if (!Array.isArray(v.providers)) {
+            throw new BaseError('BROWSER_CONFIG_INVALID', 'browser.providers 须为数组（云端占位——v1 执行面零接）');
+        }
+        providers = v.providers;
+    }
+    return {
+        ...(executablePath !== undefined ? { executablePath } : {}),
+        ...(providers !== undefined ? { providers } : {}),
+    };
+}

package/dist/channels/ask-queue.js

@@ -0,0 +1,82 @@
+/**
+ * 提问队列（07 §4.3 提问队列机制正文——2026-09-06 channels 纵切批补写）：
+ * 阻塞原语（confirm/select/input）与审批 ask 统一入 per-session FIFO——
+ * 队首才呈现、应答即出队、后继顶上（「无并存态」即此律）。
+ *
+ * 收口三则（规范同条）：会话关闭按 sessionId 清队（余项按取消语义收场——
+ * 保守值同撤销面）；run 打断信号穿透队内该 run 发起的 ask（signal 由调用方
+ * ui-core 携带，队列不感知 run）；队列是内存态、崩溃即丢（durable 真相在
+ * 审批日志不在队列——与 04 §4 PendingMessageQueue 同纪）。
+ *
+ * 队列持在通道核、呈现形态归后端（TUI overlay 是队首呈现之一）——本类只管
+ * 排序与收口，backend 编舞（竞速/撤销说明行）归 ui-core。
+ */
+/**
+ * 提问队列（per-session FIFO）。同会话严格串行（队首在飞时后继排队）；
+ * 异会话队列独立（各自队首并行——呈现并存的裁决归后端 overlay 层）。
+ */
+export class AskQueue {
+    sessions = new Map();
+    ensure(sessionId) {
+        let q = this.sessions.get(sessionId);
+        if (q === undefined) {
+            q = { pending: [], active: null };
+            this.sessions.set(sessionId, q);
+        }
+        return q;
+    }
+    /** 入队：会话队列空闲即直晋队首（start 同步调用——FIFO 无空转窗）；否则排队 */
+    enqueue(sessionId, kind, hooks) {
+        const q = this.ensure(sessionId);
+        if (q.active === null) {
+            q.active = { kind, hooks };
+            hooks.start();
+        }
+        else {
+            q.pending.push({ kind, hooks });
+        }
+    }
+    /**
+     * 队首落定（应答/保守值收场都算——由 ui-core 在 promise 链尾调用）：
+     * 出队、后继顶上。未知会话/已清队 no-op（clearSession 后迟到落定不炸）。
+     */
+    settled(sessionId) {
+        const q = this.sessions.get(sessionId);
+        if (q === undefined)
+            return;
+        if (q.active === null)
+            return; // 空转（迟到落定）——幂等
+        const next = q.pending.shift();
+        if (next === undefined) {
+            q.active = null; // 队列清空（会话条目留存——防高频重建；clearSession 才真清）
+        }
+        else {
+            q.active = next;
+            next.hooks.start();
+        }
+    }
+    /**
+     * 会话收口（04 §9 归属围栏通道侧执法）：清排队项 + 取消在飞队首——
+     * 全部走 cancel（保守值同撤销面：confirm→false / select·input→''、
+     * approval→cancelled 语义由 ui-core 落）。
+     */
+    clearSession(sessionId) {
+        const q = this.sessions.get(sessionId);
+        if (q === undefined)
+            return;
+        const all = q.active === null ? [...q.pending] : [q.active, ...q.pending];
+        q.pending.length = 0;
+        q.active = null;
+        this.sessions.delete(sessionId);
+        // 逐项 cancel：在飞与排队同语义收场（cancel 实现须幂等——settled 迟到不双结）
+        for (const item of all)
+            item.hooks.cancel();
+    }
+    /** 观察面：会话在飞+排队项 kind 序列（测试与 /help 类诊断面消费） */
+    pending(sessionId) {
+        const q = this.sessions.get(sessionId);
+        if (q === undefined)
+            return [];
+        return q.active === null ? q.pending.map((p) => p.kind) : [q.active.kind, ...q.pending.map((p) => p.kind)];
+    }
+}

package/dist/channels/commands.js

@@ -0,0 +1,129 @@
+/**
+ * 命令面注册表与分发（03 §2.2 registerCommand 签名定形 + §2.7 冲突律；
+ * 2026-09-06 channels 纵切批）。
+ *
+ * 两律：①后写胜出——命令名是可换实现位（用户插件覆盖 core: 同名命令 =
+ * 显式换装正道），撞名不拒、胜出即生效；②词法违例拒——命令名主段连字符式
+ * + 可选冒号子段，非法名拒绝注册（CHANNEL_COMMAND_INVALID——与
+ * AGENT_ROLE_INVALID 同构：撞名不拒、格式拒）。
+ */
+import { BaseError } from '../contracts/index.js';
+/** 命令名词法（03 §2.2 定形：^[a-z][a-z0-9-]*(:[a-z0-9-]+)?$——/memory-export 与 /skill:name 实况同形） */
+const COMMAND_NAME_RE = /^[a-z][a-z0-9-]*(?::[a-z0-9-]+)?$/;
+/**
+ * 命令面注册表。注册即生效（03 §2.1——下一次消费点重取，不待重启）；
+ * 全部方法同步（注册/查询/解析零 I/O，分发是唯一异步面）。
+ */
+export class CommandRegistry {
+    commands = new Map();
+    /** 注册代币发生器（每注册一枚新 token——disposer 校验「自己仍是现任」用） */
+    tokenSeed = 0;
+    /**
+     * 注册命令（后写胜出）。词法违例抛 CHANNEL_COMMAND_INVALID；撞名静默覆盖
+     * （03 §2.7：胜出即生效无拒码）。
+     *
+     * @returns disposer——注销该命令；若已被后写覆盖则 no-op（不误注接任者）
+     */
+    register(name, handler, description) {
+        if (!COMMAND_NAME_RE.test(name)) {
+            throw new BaseError('CHANNEL_COMMAND_INVALID', `命令名词法违例：${JSON.stringify(name)}（主段连字符式 + 可选冒号子段，小写）`);
+        }
+        const token = { seed: this.tokenSeed++ };
+        this.commands.set(name, { name, handler, description, token });
+        return () => {
+            // 只有现任可注（token 相等 = 未被后写覆盖）——后写的接任者不因旧 disposer 被误注
+            const current = this.commands.get(name);
+            if (current !== undefined && current.token === token) {
+                this.commands.delete(name);
+            }
+        };
+    }
+    /** 命令清单（/help 与 @-mention 补全面的消费面——注册序） */
+    list() {
+        return [...this.commands.values()].map(({ token: _token, ...spec }) => spec);
+    }
+    /** 按名查询（分发前置——后写胜出者即现任） */
+    get(name) {
+        const entry = this.commands.get(name);
+        return entry === undefined
+            ? undefined
+            : { name: entry.name, handler: entry.handler, description: entry.description };
+    }
+    /**
+     * 解析输入行（同步纯函数面）：`/name rest...` → { name, args }；
+     * 非 `/` 开头返回 null（普通消息路——去哪归驱动侧/conversation 裁决，
+     * 命令面只报「不是命令」）。
+     */
+    parse(input) {
+        if (!input.startsWith('/'))
+            return null;
+        // 首空白分割命令名与实参原文（命令名自身无空白——词法保证）
+        const rest = input.slice(1);
+        const sep = rest.search(/\s/);
+        const name = sep === -1 ? rest : rest.slice(0, sep);
+        const raw = sep === -1 ? '' : rest.slice(sep + 1).trim();
+        if (!COMMAND_NAME_RE.test(name))
+            return null;
+        return { name, args: { raw, argv: tokenize(raw) } };
+    }
+    /**
+     * 分发输入行：命中注册命令 → 执行 handler 返回 true；未命中（非命令形或
+     * 名不在册）返回 false——「未注册的 /词 怎么处置（提示未知命令 or 当普通
+     * 消息进 run）」是驱动侧语义，归 conversation 件。
+     *
+     * sessionId 位（ix-2 新建）：发起会话透传进 CommandArgs（CLI 面缺席）——
+     * 插件命令 handler 可显式携带（ctx.ui opts.sessionId 透传），ambient 自动
+     * 锚另由 host 侧 ALS 承载（两轨并行——显式位是插件可见面、ALS 是零自觉面）。
+     */
+    async dispatch(input, sessionId) {
+        const parsed = this.parse(input);
+        if (parsed === null)
+            return false;
+        const spec = this.commands.get(parsed.name);
+        if (spec === undefined)
+            return false;
+        await spec.handler(sessionId !== undefined ? { ...parsed.args, sessionId } : parsed.args);
+        return true;
+    }
+}
+/**
+ * 引号感知词切分（03 §2.2 定形：shell 词法的最小实现——不进 glob/变量展开）。
+ * 规则：裸词按空白切；'单引号' 保字面（内部再无转义）；"双引号" 保内部空格；
+ * 引号未闭合按行尾收口（宽容收场——终端输入无第二行可续）。
+ */
+export function tokenize(raw) {
+    const out = [];
+    let current = '';
+    let hasCurrent = false;
+    let quote = null;
+    for (const ch of raw) {
+        if (quote !== null) {
+            if (ch === quote) {
+                quote = null; // 引号闭合——段继续累积（拼接态 "ab'cd ef'" 保空格）
+            }
+            else {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            hasCurrent = true; // 空引号段 '' 也是一段（与裸词不同——显式空串）
+            continue;
+        }
+        if (ch === ' ' || ch === '\t') {
+            if (hasCurrent) {
+                out.push(current);
+                current = '';
+                hasCurrent = false;
+            }
+            continue;
+        }
+        current += ch;
+        hasCurrent = true;
+    }
+    // 行尾：未闭合引号宽容收口（current 原样成段）；尾段在
+    if (hasCurrent)
+        out.push(current);
+    return out;
+}