@steerable/agent-shell 0.6.15

package/dist/project-rules.js

@@ -0,0 +1,102 @@
+/**
+ * W6-7a 项目规则文件加载（AGENTS.md / CLAUDE.md 生态约定）。
+ *
+ * 从绑定的项目目录向上遍历，收集每一层的规则文件，拼成一段注入模型上下文。
+ * 三个对照框架都有这一机制（pi 的 `ResourceLoader` 向上遍历
+ * `AGENTS.override.md`/`AGENTS.md`/`CLAUDE.md`；codex 把 AGENTS.md 当作
+ * WorldState 的一节），我们此前完全没有。
+ *
+ * 安全前提（W6-5）：这些文件是「项目作者写给 agent 的指令」，属于不可信输入。
+ * 本模块只做发现并返回内容；**是否注入由调用方按项目信任状态决定**——未信任
+ * 的项目一律不调用本模块。遍历与注入都有硬上限，单个文件与总量都截断。
+ *
+ * 「热重载」按回合粒度天然成立：每个回合重新读取磁盘，规则文件保存即生效，
+ * 不需要文件 watcher。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** 每层目录按此顺序查找（override 优先于通用约定）。 */
+const RULE_FILE_NAMES = ['AGENTS.override.md', 'AGENTS.md', 'CLAUDE.md'];
+/** 最多向上遍历的层数（含起始目录）——支持 monorepo 把规则放在父目录。 */
+const MAX_LEVELS = 6;
+/** 最多注入的规则文件个数。 */
+const MAX_RULE_FILES = 8;
+/** 单个规则文件的最大字符数（超出截断）。 */
+const MAX_FILE_CHARS = 8_000;
+/** 注入内容总字符上限（W4-7 注入内容必须有界）。 */
+const MAX_TOTAL_CHARS = 20_000;
+const EMPTY = { files: [], content: '', truncated: false };
+/**
+ * 收集并拼接项目规则。`folderPath` 为绑定的项目根目录。
+ *
+ * 向上遍历在「用户 home 目录」处封顶（若项目不在 home 下则按 MAX_LEVELS
+ * 封顶）——不扫 `/`、`/etc` 这类与项目无关的祖先目录。
+ */
+export function loadProjectRuleFiles(folderPath) {
+    if (!folderPath || !folderPath.trim())
+        return EMPTY;
+    const start = path.resolve(folderPath);
+    if (!fs.existsSync(start))
+        return EMPTY;
+    // 构造 根→…→起始目录 的目录链（根在前，越往后越贴近项目）。
+    const home = os.homedir();
+    const chain = [];
+    let dir = start;
+    const seen = new Set();
+    while (!seen.has(dir) && chain.length < MAX_LEVELS) {
+        seen.add(dir);
+        chain.unshift(dir);
+        if (dir === home)
+            break; // 不越过 home 向上
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // 已到文件系统根
+        dir = parent;
+    }
+    // 根→叶收集规则文件；每层内 override 优先。
+    const files = [];
+    for (const d of chain) {
+        for (const name of RULE_FILE_NAMES) {
+            const p = path.join(d, name);
+            try {
+                if (fs.statSync(p).isFile())
+                    files.push(p);
+            }
+            catch {
+                // 不存在或不可读——跳过该文件。
+            }
+            if (files.length >= MAX_RULE_FILES)
+                break;
+        }
+        if (files.length >= MAX_RULE_FILES)
+            break;
+    }
+    if (files.length === 0)
+        return EMPTY;
+    // 拼接并施加总量上限。
+    const sections = [];
+    let total = 0;
+    let truncated = false;
+    for (const file of files) {
+        let body;
+        try {
+            body = fs.readFileSync(file, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        if (body.length > MAX_FILE_CHARS) {
+            body = `${body.slice(0, MAX_FILE_CHARS)}\n…（规则文件过长，已截断）`;
+            truncated = true;
+        }
+        const section = `## 项目规则（来自 \`${file}\`）\n\n${body.trim()}`;
+        if (total + section.length > MAX_TOTAL_CHARS) {
+            truncated = true;
+            break;
+        }
+        sections.push(section);
+        total += section.length;
+    }
+    return { files, content: sections.join('\n\n'), truncated };
+}

package/dist/runtime.d.ts

@@ -0,0 +1,62 @@
+/** Electron 主进程里 `process.versions.electron` 有值；普通 Node（BS server、vitest）没有。 */
+export declare function isElectronRuntime(): boolean;
+/** 应用数据目录（SQLite、JSON store、用户技能目录的根）。 */
+export declare function getUserDataDir(): string;
+/**
+ * 注入应用根目录（产品组装根调用）。重复注入不同值抛错（组装期笔误，
+ * fail fast——与 setProductBrand 同语义）。
+ */
+export declare function setAppRootDir(dir: string): void;
+export declare function getAppRootDir(): string;
+/**
+ * 注入 preload bundle 绝对路径（产品组装根/入口调用）。重复注入不同值
+ * 抛错（组装期笔误，fail fast——与 setAppRootDir 同语义）。
+ */
+export declare function setPreloadPath(file: string): void;
+/**
+ * 解析窗口应加载的 preload bundle：产品注入优先，其次 shell 自带默认
+ * （shellDir 一般为 shell main.js 所在目录）。
+ */
+export declare function getPreloadPath(shellDir: string): string;
+/**
+ * 产品 web 产物目录（2.3）：产品入口（products/<id>/{main,server}.ts）
+ * 用本函数把 DEEPPATH_WEB_DIST 注入环境，shell 的 main/server 据此定位
+ * web dist。双平面探测：源码平面入口在 products/<id>/（web dist 在同级
+ * web/dist）；编译平面入口在 products/<id>/dist/products/<id>/（web dist
+ * 在仓库根的 products/<id>/web/dist）。两处都没有返回 null（打包后的
+ * CS 走 app.getAppPath()/web-dist 约定，不经本函数）。
+ */
+export declare function resolveProductWebDist(entryUrl: string): string | null;
+/** 用系统默认应用打开本地路径（Electron `shell.openPath` 的跨宿主等价物）。 */
+export declare function shellOpenPath(target: string): Promise<string>;
+/** 用系统浏览器打开 URL（Electron `shell.openExternal` 的跨宿主等价物）。 */
+export declare function shellOpenExternal(url: string): Promise<void>;
+/**
+ * 注册应用退出钩子（sidecar 的兜底清理）。BS 下没有 app 生命周期——
+ * 宿主退出由 server 的 SIGINT/SIGTERM 钩子统一负责，这里 no-op。
+ */
+export declare function onAppWillQuit(listener: () => void): void;
+export declare function offAppWillQuit(listener: () => void): void;
+interface NativeImageInstance {
+    isEmpty(): boolean;
+    getSize(): {
+        width: number;
+        height: number;
+    };
+    resize(o: {
+        width?: number;
+        height?: number;
+        quality?: string;
+    }): NativeImageInstance;
+    toPNG(): Buffer;
+    toJPEG(quality: number): Buffer;
+}
+interface NativeImageLike {
+    createFromPath(p: string): NativeImageInstance;
+}
+/**
+ * Electron `nativeImage`（图片解码/缩放）。BS / 单测等无 Electron 环境返回
+ * null——调用方按"不支持图片解码"降级（image-attachment 已有该分支）。
+ */
+export declare function getNativeImage(): NativeImageLike | null;
+export {};

package/dist/runtime.js

@@ -0,0 +1,217 @@
+/**
+ * 宿主运行时抽象：Electron 主进程与 BS 独立 Node server 共用的环境探测。
+ *
+ * CS 模式（Electron）下路径来自 `app.getPath('userData')`（按 productName
+ * 分目录）；BS 模式（`node dist/server/index.js`）没有 Electron，落到
+ * `DEEPPATH_USER_DATA_DIR` 或产品注入的 `~/<dataDirName>`（3.1）。两种模式共用
+ * 同一份 SQLite / JSON 存储代码，差异只在这一层。
+ *
+ * 本模块只允许依赖 node 内置模块（与 brand.ts 同约束）：storage 会被
+ * vitest 直接 import，不能碰 electron 包。
+ */
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getProductConfig } from './product-config.js';
+/** Electron 主进程里 `process.versions.electron` 有值；普通 Node（BS server、vitest）没有。 */
+export function isElectronRuntime() {
+    return Boolean(process.versions.electron);
+}
+let cachedApp;
+/**
+ * 同步拿 Electron app。普通 Node 下 `require('electron')` 返回二进制路径
+ * 字符串（没有 app），必须拒绝；Electron 主进程里才是真正的 API 对象。
+ */
+function tryElectronApp() {
+    if (cachedApp !== undefined)
+        return cachedApp;
+    if (!isElectronRuntime()) {
+        cachedApp = null;
+        return null;
+    }
+    try {
+        const require = createRequire(import.meta.url);
+        const mod = require('electron');
+        cachedApp = mod && typeof mod.app?.getPath === 'function' ? mod.app : null;
+    }
+    catch {
+        cachedApp = null;
+    }
+    return cachedApp;
+}
+/** 应用数据目录（SQLite、JSON store、用户技能目录的根）。 */
+export function getUserDataDir() {
+    if (process.env.DEEPPATH_USER_DATA_DIR)
+        return process.env.DEEPPATH_USER_DATA_DIR;
+    const app = tryElectronApp();
+    if (app)
+        return app.getPath('userData');
+    // BS：目录名是产品注入配置（3.1，product.json dataDirName），与 Electron
+    // 下 productName 分目录的共存语义对齐；中性 shell 缺省 .agent-shell。
+    const dirName = getProductConfig().dataDirName ?? '.agent-shell';
+    return path.join(os.homedir(), dirName);
+}
+/**
+ * 应用根目录（消费产品的仓库/打包根：含 products/manifest.json、assets、
+ * scripts 的那层）。3.2 起 shell 是被消费的框架包，本模块自己的位置
+ * （packages/agent-shell/ts/...）不再是应用根——产品组装根在入口最早
+ *  import 时经 setAppRootDir 注入；未注入时（单测）回退到 cwd 探测。
+ */
+let appRootOverride = null;
+/**
+ * 注入应用根目录（产品组装根调用）。重复注入不同值抛错（组装期笔误，
+ * fail fast——与 setProductBrand 同语义）。
+ */
+export function setAppRootDir(dir) {
+    if (appRootOverride && appRootOverride !== dir) {
+        throw new Error('[runtime] app root already set');
+    }
+    appRootOverride = dir;
+}
+export function getAppRootDir() {
+    const app = tryElectronApp();
+    if (app)
+        return app.getAppPath();
+    if (appRootOverride)
+        return appRootOverride;
+    // 单测/脚本平面：从 cwd 向上找含 package.json 的目录。
+    for (let dir = process.cwd();;) {
+        if (fs.existsSync(path.join(dir, 'package.json')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return process.cwd();
+        dir = parent;
+    }
+}
+/**
+ * preload  bundle 路径（3.4 修复）：shell main.ts 创建窗口时需要
+ * preload.cjs——shell 自带默认面（dist/preload.cjs，buildPreloadApi()
+ * 无包贡献），但带 invoke 型包贡献的产品由产品构建把组合后的
+ * preload.cjs 出在产品 main.js 旁，产品入口在动态 import
+ * shell main 之前经本函数注入。未注入时回退 shell 自带默认。
+ */
+let preloadPathOverride = null;
+/**
+ * 注入 preload bundle 绝对路径（产品组装根/入口调用）。重复注入不同值
+ * 抛错（组装期笔误，fail fast——与 setAppRootDir 同语义）。
+ */
+export function setPreloadPath(file) {
+    if (preloadPathOverride && preloadPathOverride !== file) {
+        throw new Error('[runtime] preload path already set');
+    }
+    preloadPathOverride = file;
+}
+/**
+ * 解析窗口应加载的 preload bundle：产品注入优先，其次 shell 自带默认
+ * （shellDir 一般为 shell main.js 所在目录）。
+ */
+export function getPreloadPath(shellDir) {
+    return preloadPathOverride ?? path.join(shellDir, 'preload.cjs');
+}
+/**
+ * 产品 web 产物目录（2.3）：产品入口（products/<id>/{main,server}.ts）
+ * 用本函数把 DEEPPATH_WEB_DIST 注入环境，shell 的 main/server 据此定位
+ * web dist。双平面探测：源码平面入口在 products/<id>/（web dist 在同级
+ * web/dist）；编译平面入口在 products/<id>/dist/products/<id>/（web dist
+ * 在仓库根的 products/<id>/web/dist）。两处都没有返回 null（打包后的
+ * CS 走 app.getAppPath()/web-dist 约定，不经本函数）。
+ */
+export function resolveProductWebDist(entryUrl) {
+    const here = path.dirname(fileURLToPath(entryUrl));
+    const productId = path.basename(here);
+    for (const candidate of [
+        path.join(here, 'web', 'dist'),
+        path.resolve(here, '..', '..', '..', '..', 'products', productId, 'web', 'dist'),
+    ]) {
+        if (fs.existsSync(path.join(candidate, 'index.html')))
+            return candidate;
+    }
+    return null;
+}
+/** 用系统默认应用打开本地路径（Electron `shell.openPath` 的跨宿主等价物）。 */
+export async function shellOpenPath(target) {
+    if (tryElectronApp()) {
+        const { shell } = (await import('electron'));
+        return shell.openPath(target);
+    }
+    const [cmd, args] = openCommand(target, false);
+    return spawnDetached(cmd, args);
+}
+/** 用系统浏览器打开 URL（Electron `shell.openExternal` 的跨宿主等价物）。 */
+export async function shellOpenExternal(url) {
+    if (tryElectronApp()) {
+        const { shell } = (await import('electron'));
+        await shell.openExternal(url);
+        return;
+    }
+    const [cmd, args] = openCommand(url, true);
+    const error = await spawnDetached(cmd, args);
+    if (error)
+        throw new Error(error);
+}
+function openCommand(target, isUrl) {
+    if (process.platform === 'darwin')
+        return ['open', [target]];
+    if (process.platform === 'win32') {
+        return isUrl
+            ? ['rundll32', ['url.dll,FileProtocolHandler', target]]
+            : ['explorer', [target]];
+    }
+    return ['xdg-open', [target]];
+}
+/** 返回空串表示成功（对齐 shell.openPath 的约定），否则是错误消息。 */
+function spawnDetached(cmd, args) {
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+            child.on('error', (err) => resolve(err.message));
+            child.on('spawn', () => {
+                child.unref();
+                resolve('');
+            });
+        }
+        catch (err) {
+            resolve(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+/**
+ * 注册应用退出钩子（sidecar 的兜底清理）。BS 下没有 app 生命周期——
+ * 宿主退出由 server 的 SIGINT/SIGTERM 钩子统一负责，这里 no-op。
+ */
+export function onAppWillQuit(listener) {
+    try {
+        tryElectronApp()?.on?.('will-quit', listener);
+    }
+    catch {
+        /* 非 Electron 宿主 */
+    }
+}
+export function offAppWillQuit(listener) {
+    try {
+        tryElectronApp()?.removeListener?.('will-quit', listener);
+    }
+    catch {
+        /* 非 Electron 宿主 */
+    }
+}
+/**
+ * Electron `nativeImage`（图片解码/缩放）。BS / 单测等无 Electron 环境返回
+ * null——调用方按"不支持图片解码"降级（image-attachment 已有该分支）。
+ */
+export function getNativeImage() {
+    if (!isElectronRuntime())
+        return null;
+    try {
+        const require = createRequire(import.meta.url);
+        const mod = require('electron');
+        return typeof mod.nativeImage?.createFromPath === 'function' ? mod.nativeImage : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/scenario/pack.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 兼容性 re-export（阶段 2.2）：场景包契约类型的单一真源已迁入
+ * `@steerable/pack-sdk`（packages/pack-sdk，零依赖纯类型包）。宿主内部
+ * 既有调用方继续从本模块取类型；包代码一律直接依赖 '@steerable/pack-sdk'。
+ *
+ * 契约全文与设计约束见 packages/pack-sdk/types/index.d.ts 头注释。
+ */
+export type { ScenarioId, ToolMode, ToolExposure, PackToolContext, PackToolHandler, ToolContribution, ServiceFactory, ServiceCreateContext, MigrationContribution, SkillContribution, AgentSeedIdentity, AgentSeed, IpcContribution, HttpRouteContribution, HttpRouteRequest, MainContribution, PreloadContribution, ComponentRef, SettingsPanelContribution, RouteContribution, ChatSlotContribution, CardRendererContribution, RendererContribution, BrandSpec, PackagingSpec, ScenarioPack, PackBackendRouteResponse, PackBackendRouteRequest, PackBackendRoute, PackTurnObserver, PackTurnHooks, } from '@steerable/pack-sdk';

package/dist/scenario/pack.js

@@ -0,0 +1 @@
+export {};

package/dist/scenario/registry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 场景包注册表：宿主装配期的单一入口。
+ *
+ * 产品的 composition root 在启动早期把选中的包 register 进来；宿主各
+ * 子系统（ToolRouter / storage / copy-skills / IPC / 渲染层槽位）从这里
+ * 按槽位读取贡献，而不是各自硬编码 import 场景代码。
+ *
+ * 注册期即校验（fail loud）：重复 id、IPC 通道不带 '<packId>:' 前缀、
+ * preload 命名空间与包 id 不一致，都在 register 时抛错，而不是等到
+ * 运行时才暴露。
+ */
+import type { ScenarioId, ScenarioPack } from './pack.js';
+export declare class ScenarioRegistry {
+    private readonly packs;
+    register(pack: ScenarioPack): void;
+    get(id: ScenarioId): ScenarioPack | undefined;
+    has(id: ScenarioId): boolean;
+    list(): readonly ScenarioPack[];
+}
+/**
+ * 进程级默认注册表。composition root（main.ts / server/index.ts /
+ * 渲染层入口）在最早阶段填充；各子系统消费同一个实例。
+ */
+export declare const scenarioRegistry: ScenarioRegistry;

package/dist/scenario/registry.js

@@ -0,0 +1,31 @@
+export class ScenarioRegistry {
+    packs = new Map();
+    register(pack) {
+        if (this.packs.has(pack.id)) {
+            throw new Error(`[scenario] duplicate pack id: ${pack.id}`);
+        }
+        for (const ipc of pack.main?.ipc ?? []) {
+            if (!ipc.channel.startsWith(`${pack.id}:`)) {
+                throw new Error(`[scenario] pack ${pack.id} ipc channel "${ipc.channel}" must start with "${pack.id}:"`);
+            }
+        }
+        if (pack.preload && pack.preload.namespace !== pack.id) {
+            throw new Error(`[scenario] pack ${pack.id} preload namespace "${pack.preload.namespace}" must equal pack id`);
+        }
+        this.packs.set(pack.id, pack);
+    }
+    get(id) {
+        return this.packs.get(id);
+    }
+    has(id) {
+        return this.packs.has(id);
+    }
+    list() {
+        return [...this.packs.values()];
+    }
+}
+/**
+ * 进程级默认注册表。composition root（main.ts / server/index.ts /
+ * 渲染层入口）在最早阶段填充；各子系统消费同一个实例。
+ */
+export const scenarioRegistry = new ScenarioRegistry();

package/dist/server/http-server.d.ts

@@ -0,0 +1,39 @@
+/**
+ * BS 模式 HTTP server：把 CS（Electron）模式下挂在 IPC 后面的同一组服务
+ * 暴露成真正的 HTTP 接口，并托管 apps/web/dist 静态产物。
+ *
+ * 路由分三层：
+ *   - `/api/v2/*`        → LocalBackendRouter（chat / 设置 / 技能 / MCP …），
+ *                          与 Electron 下 `local-backend:request` 同一入口；
+ *                          流式路径（chats/:id/run|send|agent、…/regenerate）
+ *                          走 handleStream，响应即标准 SSE。
+ *   - `GET /api/v2/events` → SseBus 事件总线（替代 webContents.send 广播）。
+ *   - `/host/*`          → preload 里 direct-IPC 能力的 HTTP 等价物
+ *                          （terminal / local / approval 为宿主自带；
+ *                          场景包路由经 host/http-routes 注册表匹配）。
+ *
+ * 安全约定：默认绑定 127.0.0.1、无认证——本机自用定位（与 Electron 版相同
+ * 的信任模型：能到端口 = 本机用户）。不要绑到非回环地址，那会把 shell /
+ * 文件读写 / 场景包工具控制暴露给整个网络。
+ */
+import { type Server } from 'node:http';
+import type { LocalBackendRouter } from '../local-backend/router.js';
+import type { LocalExecutor, LocalExecRequest, LocalExecResult } from '../local-executor.js';
+import type { LocalScriptRegistry } from '../local-script-registry.js';
+import type { TerminalManager } from '../terminal-manager.js';
+import type { createApprovalBridge } from '../sidecar/reverse-approval.js';
+import type { createAskUserBridge } from '../sidecar/reverse-ask-user.js';
+import type { SseBus } from './sse-bus.js';
+export interface BsServerDeps {
+    localBackendRouter: LocalBackendRouter;
+    localExecutor: LocalExecutor;
+    localScriptRegistry: LocalScriptRegistry;
+    terminalManager: TerminalManager;
+    approvalBridge: ReturnType<typeof createApprovalBridge>;
+    askUserBridge: ReturnType<typeof createAskUserBridge>;
+    maybeExecInTerminal: (req: LocalExecRequest) => Promise<LocalExecResult | null>;
+    bus: SseBus;
+    /** apps/web/dist 的绝对路径。 */
+    webDistDir: string;
+}
+export declare function createBsServer(deps: BsServerDeps): Server;