oh-my-agent-web 0.2.0 → 0.4.0

package/dist/server/engine/registry.js

@@ -0,0 +1,47 @@
+const ALL_ON = {
+    approvals: true,
+    tools: true,
+    modelSwitch: true,
+    thinkingLevel: true,
+    resume: true,
+};
+export function createEngineRegistry(descriptors, fallbackName = "pi") {
+    const byName = new Map(descriptors.map((descriptor) => [descriptor.name, descriptor]));
+    const fallback = byName.get(fallbackName) ?? descriptors[0];
+    if (!fallback)
+        throw new Error("引擎注册表为空（至少要注册一个引擎）");
+    /** name → 实例（懒建）；切换引擎复用它，避免每次 new 一个带状态的引擎 */
+    const instances = new Map();
+    const instantiate = (descriptor) => {
+        const known = instances.get(descriptor.name);
+        if (known)
+            return known;
+        const created = descriptor.create();
+        instances.set(descriptor.name, created);
+        return created;
+    };
+    return {
+        names: () => [...byName.keys()],
+        descriptors: () => descriptors.map((descriptor) => ({ ...descriptor })),
+        get(name) {
+            const found = byName.get(name);
+            return found ? { engine: instantiate(found), descriptor: found } : null;
+        },
+        resolve(name) {
+            const found = byName.get(name);
+            if (found)
+                return { engine: instantiate(found), descriptor: found, fallbackFrom: null };
+            return { engine: instantiate(fallback), descriptor: fallback, fallbackFrom: name };
+        },
+        capabilitiesOf: (name) => (byName.get(name) ?? fallback).capabilities,
+    };
+}
+/** 假引擎的能力：**没有审批**（它只是剧本，不需要拦），其余从简 */
+export const FAKE_CAPABILITIES = {
+    approvals: true, // 假引擎仍会走审批剧本（approve 触发词），保留 true 便于测试
+    tools: true,
+    modelSwitch: true,
+    thinkingLevel: false,
+    resume: true,
+};
+export const PI_CAPABILITIES = ALL_ON;

package/dist/server/engine/scratch.js

@@ -0,0 +1,13 @@
+/**
+ * 「一次性会话」判定：临时目录里跑出来的会话不进侧栏（codex / dsh 共用）。
+ *
+ * 两个引擎都会在 `/tmp` 里留下大量 `codex exec` / 测试跑出来的会话，
+ * 把它们塞进侧栏只是噪音。判据放在一处，两个引擎的过滤规则保持一致。
+ */
+import { tmpdir } from "node:os";
+export function isScratchCwd(cwd) {
+    if (cwd === "")
+        return true;
+    const scratch = [tmpdir(), "/tmp", "/private/tmp", "/var/folders", "/private/var/folders"];
+    return scratch.some((prefix) => cwd === prefix || cwd.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`));
+}

package/dist/server/engine/suggestion-guidance.js

@@ -0,0 +1,9 @@
+/** 教模型「下一步建议」的写法（ADR-0022）：纯文本标记，不需要调用任何工具 */
+export const SUGGESTION_GUIDANCE = [
+    "## Suggested next actions",
+    "When the user must choose what to do next, end the reply with 4 to 5 lines of:",
+    "[[action:suggest:<button text>]]",
+    "Clicking a button sends that text as the next user message.",
+    "Use [[action:suggest:<short label>,prompt=<text to send>]] when the label should differ from the sent text.",
+    "Put them on their own lines at the very end, and never mention this syntax in prose.",
+].join("\n");

package/dist/server/engine/switchable.js

@@ -0,0 +1,22 @@
+export function createSwitchableEngine(first) {
+    let current = first;
+    const port = new Proxy({}, {
+        get(_target, property) {
+            const value = current[property];
+            return typeof value === "function" ? value.bind(current) : value;
+        },
+        has: (_target, property) => property in current,
+        ownKeys: () => Reflect.ownKeys(current),
+        getOwnPropertyDescriptor: (_target, property) => {
+            const descriptor = Reflect.getOwnPropertyDescriptor(current, property);
+            return descriptor ? { ...descriptor, configurable: true } : undefined;
+        },
+    });
+    return {
+        port,
+        use: (engine) => {
+            current = engine;
+        },
+        current: () => current,
+    };
+}

package/dist/server/engine/wiring.js

@@ -0,0 +1,107 @@
+/**
+ * 引擎接线（index.ts 的 400 行护栏 + 一处装配）。
+ *
+ * 把三件事绑在一起，因为它们必须指向**同一批实例**：
+ *   1. 注册表（有哪些引擎、怎么造）；
+ *   2. codex 的 app-server 客户端（引擎与会话清单共用一个子进程）；
+ *   3. 目录（每个引擎的历史会话从哪来）。
+ *
+ * codex 客户端构造时不 spawn：机器上没装 codex 也能正常启动，只有在切到它时才报错。
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { createBuiltinEngineRegistry } from "./builtin.js";
+import { createEngineCatalog } from "./catalog.js";
+import { createCodexSessionsProvider } from "./codex-sessions.js";
+import { createCodexClient } from "./codex-transport.js";
+import { createDshClient } from "./dsh-transport.js";
+import { createDshSessionsProvider } from "./dsh-sessions.js";
+/**
+ * 读 `<patchDir>/default-model.json`（`{"provider":"…","model":"…"}` 或 `{"id":"provider/model"}`）。
+ *
+ * 为什么要有它：把自定义 provider 通过 `--patch` 带给 acp 之后，ACP 的 `session/new`
+ * 仍然按它自己的默认路由给 `currentValue`（实测 `agent-default-model` 不生效），
+ * 于是「新会话默认用哪个模型」必须由我们自己指定。
+ */
+export function readDshDefaultModel(dir) {
+    const file = join(dir, "default-model.json");
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        if (typeof parsed.id === "string" && parsed.id.trim() !== "")
+            return parsed.id.trim();
+        if (typeof parsed.provider === "string" && typeof parsed.model === "string") {
+            return `${parsed.provider}/${parsed.model}`;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function createEngineWiring(options) {
+    const codexClient = createCodexClient({
+        bin: options.codexBin,
+        home: options.codexHome ?? undefined,
+        log: (text) => options.onLog(text, { engine: "codex" }),
+    });
+    /**
+     * dsh 的 patch 叠加层：把「自定义 provider / 默认模型」带给 acp profile。
+     * 顺序 = 环境变量里显式给的 → 用户目录里的 `*.yml`（按文件名）。
+     */
+    const patchDir = options.dshPatchDir;
+    const patchFiles = [
+        ...(options.dshPatches ?? []),
+        ...(patchDir && existsSync(patchDir)
+            ? readdirSync(patchDir)
+                .filter((name) => name.endsWith(".yml") || name.endsWith(".yaml"))
+                .sort()
+                .map((name) => join(patchDir, name))
+            : []),
+    ].filter((file) => existsSync(file));
+    if (patchFiles.length > 0)
+        options.onLog(`dsh：加载 ${patchFiles.length} 个 patch 叠加层`, { files: patchFiles });
+    // 自定义 provider 的「默认模型」：patch 里的 agent-default-model 不会被 ACP 带到
+    // session/new 的 configOptions（实测），所以这里用一个伴随文件显式指定。
+    const defaultModel = options.dshModel ?? (patchDir ? readDshDefaultModel(patchDir) : null);
+    const dshClient = createDshClient({
+        bin: options.dshBin,
+        home: options.dshHome ?? undefined,
+        patches: patchFiles,
+        log: (text) => options.onLog(text, { engine: "dsh" }),
+    });
+    const registry = createBuiltinEngineRegistry({
+        onNotice: options.onNotice,
+        onLog: (text) => options.onLog(text),
+        codex: { client: codexClient },
+        dsh: { client: dshClient, model: defaultModel },
+    });
+    const catalog = createEngineCatalog({
+        registry,
+        sessions: {
+            pi: options.piSessions,
+            // fake 是「剧本回放」引擎：历史沿用 pi 的存储（本地演练 / 冒烟时侧栏不至于全空）
+            fake: options.piSessions,
+            codex: createCodexSessionsProvider({ client: codexClient, log: (text) => options.onLog(text) }),
+            // dsh 的历史会话清单：读 ~/.dsh 的 workspace.json + 会话投影缓存（只读）
+            dsh: createDshSessionsProvider({ home: options.dshHome ?? undefined, log: (text) => options.onLog(text) }),
+        },
+    });
+    const resolved = registry.resolve(options.engineName);
+    if (resolved.fallbackFrom) {
+        options.onLog(`AGENT_WEB_ENGINE 未注册，回落到 pi（可选：${registry.names().join(" / ")}）`, {
+            requested: resolved.fallbackFrom,
+        });
+    }
+    return {
+        registry,
+        catalog,
+        resolved,
+        // 收掉外部引擎的子进程；pi 是进程内 SDK，不需要额外收
+        close: () => {
+            codexClient.close();
+            dshClient.close();
+        },
+    };
+}

package/dist/server/files/dir-routes.js

@@ -0,0 +1,40 @@
+/**
+ * 目录浏览（「新建项目」用）：**只读列目录**，不创建、不删除任何东西。
+ *
+ * 与文件面板的区别：这里要能走出当前工作区（新建项目就是要在别处选目录），
+ * 所以只做「绝对路径 + 存在 + 是目录」的校验，且只返回**目录名**（不返回文件、不返回内容）。
+ */
+import { realpathSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+export function registerDirRoutes(app, options) {
+    app.get("/api/fs/dirs", async (request, response) => {
+        const raw = typeof request.query.path === "string" && request.query.path.startsWith("/")
+            ? request.query.path
+            : (options.workspaceOf() ?? process.env.HOME ?? "/");
+        let real;
+        try {
+            real = realpathSync(raw);
+            if (!statSync(real).isDirectory())
+                throw new Error("not a directory");
+        }
+        catch {
+            response.status(400).json({ error: { code: "fs.bad_path", message: "不是可用的目录" } });
+            return;
+        }
+        let entries = [];
+        try {
+            const items = await readdir(real, { withFileTypes: true });
+            entries = items
+                .filter((item) => item.isDirectory() && !item.name.startsWith(".") && item.name !== "node_modules")
+                .map((item) => ({ name: item.name, path: join(real, item.name) }))
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .slice(0, 500);
+        }
+        catch {
+            response.status(403).json({ error: { code: "fs.unreadable", message: "这个目录读不了（权限）" } });
+            return;
+        }
+        response.json({ path: real, parent: real === "/" ? null : dirname(real), entries });
+    });
+}

package/dist/server/files/file-search.js

@@ -0,0 +1,63 @@
+/**
+ * 文件名搜索（文件管理标题栏的放大镜）。
+ *
+ * 只按**文件名**匹配（不做内容搜索：那是 grep 的活，也不该把大仓库全读一遍）。
+ * 约束：只在工作区根内、跳过 node_modules/.git 等重目录、深度与结果数都有上限 ——
+ * 单用户工作台里「点了没反应」比「慢一点」更难受，所以宁可少返回也要快。
+ */
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { IGNORED_ENTRIES } from "./file-service.js";
+export const SEARCH_MAX_RESULTS = 200;
+export const SEARCH_MAX_DEPTH = 8;
+/** 纯函数：名字是否命中（大小写不敏感的包含匹配） */
+export function matchesQuery(name, query) {
+    return name.toLowerCase().includes(query.toLowerCase());
+}
+export async function searchFiles(root, query, options = {}) {
+    const needle = query.trim();
+    if (needle === "")
+        return { ok: true, entries: [], truncated: false };
+    const maxResults = options.maxResults ?? SEARCH_MAX_RESULTS;
+    const maxDepth = options.maxDepth ?? SEARCH_MAX_DEPTH;
+    const found = [];
+    let truncated = false;
+    /** 广度优先一层层扫：先命中的是浅层文件，视觉上更符合预期 */
+    const walk = async (dir, relPath, depth) => {
+        if (depth > maxDepth || found.length >= maxResults) {
+            truncated ||= found.length >= maxResults;
+            return;
+        }
+        let items;
+        try {
+            items = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // 没权限 / 刚被删：跳过
+        }
+        const dirs = [];
+        for (const item of items) {
+            if (IGNORED_ENTRIES.has(item.name))
+                continue;
+            if (found.length >= maxResults) {
+                truncated = true;
+                return;
+            }
+            const childPath = join(dir, item.name);
+            const childRel = join(relPath, item.name);
+            if (item.isDirectory())
+                dirs.push({ path: childPath, rel: childRel });
+            if (matchesQuery(item.name, needle))
+                found.push({ name: item.name, path: childRel, isDir: item.isDirectory() });
+        }
+        for (const dir2 of dirs)
+            await walk(dir2.path, dir2.rel, depth + 1);
+    };
+    try {
+        await walk(root, "", 0);
+        return { ok: true, entries: found, truncated };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/server/files/file-service.js

@@ -0,0 +1,232 @@
+/**
+ * 文件浏览与只读预览（M4）——服务端。
+ *
+ * 三条硬约束：
+ *   1. **只能看当前项目内**（ADR-0006）：所有路径 `realpath` 后必须落在工作区根内；
+ *   2. **懒加载**：列目录只列一层（91 个会话那种大目录也不卡）；
+ *   3. **有上限**：预览只读前 N 字节，二进制给「不可预览」而不是塞满界面。
+ */
+import { realpathSync } from "node:fs";
+import { open, readFile, readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { resolveInsideRoot } from "../util/paths.js";
+export const MAX_PREVIEW_BYTES = 512 * 1024;
+/** 默认不列的目录/文件（与参考实现的 IGNORED_ENTRIES 同口径：依赖与构建产物不该占满文件树） */
+export const IGNORED_ENTRIES = new Set(["node_modules", ".git", "dist", "web/dist", "coverage", ".next", "target"]);
+/** 目录里最多列多少项（防止某个目录把界面撑爆） */
+export const MAX_DIR_ENTRIES = 500;
+/** 纯函数：按「目录优先、同类按名字」排序（与常见文件树一致） */
+export function sortEntries(entries) {
+    return [...entries].sort((a, b) => (a.isDir === b.isDir ? a.name.localeCompare(b.name) : a.isDir ? -1 : 1));
+}
+/** 纯函数：看起来像文本吗（NUL 字节 = 二进制；常见图片扩展名直接判二进制） */
+export function looksBinary(bytes, name) {
+    if (/\.(png|jpe?g|gif|webp|ico|pdf|zip|gz|tar|exe|dylib|so|woff2?|ttf|mp4|mp3|wav)$/i.test(name))
+        return true;
+    const sample = bytes.subarray(0, 4096);
+    for (const byte of sample)
+        if (byte === 0)
+            return true;
+    return false;
+}
+/**
+ * 列一层目录。
+ *
+ * `showHidden` 控制**点开头的隐藏文件**（.env / .github 之类）：默认只放行 .gitignore 与 .env.example
+ * （它们是项目说明的一部分），需要时由界面的「眼睛」按钮显式打开。
+ * `node_modules` / `dist` 这类永远不列（ADR：依赖与构建产物不该占满文件树）。
+ */
+export async function listDirectory(root, relPath, options = {}) {
+    const target = relPath === "" ? root : join(root, relPath);
+    const safe = resolveInsideRoot(root, target, realpathSync);
+    if (!safe.ok)
+        return { ok: false, error: safe.reason };
+    try {
+        const items = await readdir(safe.path, { withFileTypes: true });
+        const entries = items
+            .filter((item) => !IGNORED_ENTRIES.has(item.name))
+            .filter((item) => options.showHidden === true ||
+            !item.name.startsWith(".") ||
+            item.name === ".gitignore" ||
+            item.name === ".env.example")
+            .map((item) => ({ name: item.name, path: join(relPath, item.name), isDir: item.isDirectory() }));
+        return {
+            ok: true,
+            root,
+            path: relPath,
+            entries: sortEntries(entries).slice(0, MAX_DIR_ENTRIES),
+            truncated: entries.length > MAX_DIR_ENTRIES,
+        };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export async function readPreview(root, relPath, limit = MAX_PREVIEW_BYTES) {
+    const safe = resolveInsideRoot(root, join(root, relPath), realpathSync);
+    if (!safe.ok)
+        return { ok: false, error: safe.reason };
+    try {
+        const info = await stat(safe.path);
+        if (info.isDirectory())
+            return { ok: false, error: "这是一个目录" };
+        // 只读前 limit 字节：以前是 readFile 全读进来再截断（工作区里一个几 GB 的日志
+        // 就能把进程内存打爆），512KB 的上限等于没设。
+        const size = info.size;
+        const take = Math.min(size, limit);
+        const handle = await open(safe.path, "r");
+        let bytes;
+        try {
+            bytes = Buffer.alloc(take);
+            if (take > 0)
+                await handle.read(bytes, 0, take, 0);
+        }
+        finally {
+            await handle.close();
+        }
+        const binary = looksBinary(bytes, safe.path);
+        return {
+            ok: true,
+            path: relPath,
+            text: binary ? "" : bytes.toString("utf8"),
+            bytes: size,
+            truncated: size > limit,
+            binary,
+        };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** 允许直接当图片/文档发给浏览器的扩展名（其余一律拒绝，避免变成任意文件下载器） */
+const RAW_MIME = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    avif: "image/avif",
+    svg: "image/svg+xml",
+    ico: "image/x-icon",
+    bmp: "image/bmp",
+    pdf: "application/pdf",
+};
+/** 图片原始大小上限（超过就拒绝，别让浏览器卡死） */
+export const MAX_RAW_BYTES = 20 * 1024 * 1024;
+/** 纯函数：按扩展名给 Content-Type（不在白名单里返回空串 = 拒绝） */
+export function mimeOf(path) {
+    const extension = path.split(".").pop()?.toLowerCase() ?? "";
+    return RAW_MIME[extension] ?? "";
+}
+/** 读取图片原始字节（markdown 里 \`![](docs/shot.png)\` 能直接显示的关键一环） */
+export async function readRaw(root, relPath) {
+    const mime = mimeOf(relPath);
+    if (mime === "")
+        return { ok: false, error: `不支持的文件类型：${relPath.split(".").pop() ?? "无扩展名"}` };
+    // 绝对路径（agent 把截图写到 /tmp/x.png 这种）：只做「存在 + 是文件 + 类型白名单」，
+    // 不做工作区包含 —— 否则模型刚生成的图在对话里就看不见。相对路径仍限制在工作区内。
+    let safe;
+    try {
+        safe = relPath.startsWith("/")
+            ? { ok: true, path: realpathSync(relPath) }
+            : resolveInsideRoot(root, join(root, relPath), realpathSync);
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    if (!safe.ok)
+        return { ok: false, error: safe.reason };
+    try {
+        const info = await stat(safe.path);
+        if (info.isDirectory())
+            return { ok: false, error: "这是一个目录" };
+        if (info.size > MAX_RAW_BYTES)
+            return { ok: false, error: "文件太大（上限 20MB）", tooLarge: true };
+        return { ok: true, bytes: await readFile(safe.path), mime };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+// ---------------------------------------------------------------------------
+// 视频 / 音频：走「流 + Range」，不整块读进内存（大文件也能拖动进度条）
+// ---------------------------------------------------------------------------
+/** 允许内联播放的媒体类型（白名单之外的扩展名一律拒绝） */
+const MEDIA_MIME = {
+    mp4: "video/mp4",
+    m4v: "video/mp4",
+    webm: "video/webm",
+    ogv: "video/ogg",
+    mov: "video/quicktime",
+    mkv: "video/x-matroska",
+    mp3: "audio/mpeg",
+    m4a: "audio/mp4",
+    aac: "audio/aac",
+    wav: "audio/wav",
+    ogg: "audio/ogg",
+    opus: "audio/opus",
+    flac: "audio/flac",
+};
+/** 纯函数：媒体扩展名 → Content-Type（不是媒体返回空串） */
+export function mediaMimeOf(path) {
+    const extension = path.split(".").pop()?.toLowerCase() ?? "";
+    return MEDIA_MIME[extension] ?? "";
+}
+/**
+ * 解析一个可播放的媒体文件：校验路径（与 readRaw 同规矩）、类型白名单、大小上限。
+ * 只 stat，不读内容 —— 真正的字节由路由用 createReadStream + Range 流出去。
+ */
+export async function resolveMediaFile(root, relPath) {
+    const mime = mediaMimeOf(relPath);
+    if (mime === "")
+        return { ok: false, error: `不支持的媒体类型：${relPath.split(".").pop() ?? "无扩展名"}` };
+    let safePath;
+    try {
+        safePath = relPath.startsWith("/") ? realpathSync(relPath) : "";
+        if (safePath === "") {
+            const safe = resolveInsideRoot(root, join(root, relPath), realpathSync);
+            if (!safe.ok)
+                return { ok: false, error: safe.reason };
+            safePath = safe.path;
+        }
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+    try {
+        const info = await stat(safePath);
+        if (info.isDirectory())
+            return { ok: false, error: "这是一个目录" };
+        if (info.size > MAX_MEDIA_BYTES)
+            return { ok: false, error: "文件太大（上限 4GB）", tooLarge: true };
+        return { ok: true, path: safePath, size: info.size, mime };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** 媒体文件大小上限：4GB（流式发送，不会占内存；只是别把「伪装的巨型文件」当视频播） */
+export const MAX_MEDIA_BYTES = 4 * 1024 * 1024 * 1024;
+/** 纯函数：解析 Range 头（只认单段 `bytes=a-b`），返回闭区间；无效返回 null（按整文件发） */
+export function parseRange(header, size) {
+    if (!header)
+        return null;
+    const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!match)
+        return null;
+    const [, rawStart, rawEnd] = match;
+    if (rawStart === "" && rawEnd === "")
+        return null;
+    if (rawStart === "") {
+        // 后缀写法：bytes=-N → 最后 N 字节
+        const length = Number(rawEnd);
+        if (!Number.isFinite(length) || length <= 0)
+            return null;
+        return { start: Math.max(0, size - length), end: size - 1 };
+    }
+    const start = Number(rawStart);
+    const end = rawEnd === "" ? size - 1 : Number(rawEnd);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || start > end)
+        return null;
+    return { start: Math.min(start, size - 1), end: Math.min(end, size - 1) };
+}