@ai-zen/agents-host 0.0.0-stage → 0.1.0-alpha.0

package/dist/services/WorkspaceService.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Workspace 服务：项目（一个工作目录）的登记、查看、改名、删除。
+ *
+ * 对应能力编号：F-C1 的前置（项目中承载对话）、D9 / D10 / D12（一等公民、cwd 不可变、
+ * 目录不存在照常可看）、D11（删项目连带删名下对话，目录本身不碰）、D17（删除前给代价）、
+ * F-F9（不可撤销动作由客户端二次确认，宿主负责算账）、R14（cwd 唯一）、R20（列表顺序）。
+ *
+ * 这个服务只做「一条项目记录怎么变」与「代价是多少」；文件系统方面只回答一件事 ——
+ * 目录还在不在（`FolderFact.exists`），是否只读由客户端判断（D12）。
+ */
+import type { AssetRepository } from "../storage/AssetRepository.js";
+import type { ConversationRepository } from "../storage/ConversationRepository.js";
+import type { MessageRepository } from "../storage/MessageRepository.js";
+import type { WorkspaceRepository } from "../storage/WorkspaceRepository.js";
+import type { FolderFact, WorkspaceCreateParams, WorkspaceCreateResult, WorkspaceGetParams, WorkspaceGetResult, WorkspaceListParams, WorkspaceListResult, WorkspaceRemoveParams, WorkspaceRemoveResult, WorkspaceRenameParams, WorkspaceRenameResult } from "../wire/index.js";
+import type { ConversationRuntimePort, AssetSweeper } from "./ConversationService.js";
+/**
+ * `workspace.remove` 的结果。
+ *
+ * wire 的 `WorkspaceRemoveResult` 只有「删了没 + 代价」；真正把 `assets/` 下的文件
+ * 清掉是 asset 那一层的事（PRD D17「图片按引用清理」），所以这里多带一份这些对话引用过的
+ * 素材 id（删完之后由 asset 层问「还剩几张引用」，归零才删）。
+ */
+export interface WorkspaceRemovalReport extends WorkspaceRemoveResult {
+    /** 这些对话引用过的素材 id（可能还有别的对话在用） */
+    assetIds: string[];
+}
+/** Workspace 服务的依赖；由单根组装后注入，服务自己不取任何全局路径 */
+export interface WorkspaceServiceDeps {
+    workspaces: WorkspaceRepository;
+    conversations: ConversationRepository;
+    messages: MessageRepository;
+    assets: AssetRepository;
+    /** 引用归零的素材交给它删行删文件；不注入时字节会留在盘上（引用行已经没了） */
+    sweepAssets?: AssetSweeper;
+    /**
+     * 运行时钩子：删项目会连带删掉它名下的对话，这些对话在运行时里可能还留着
+     * 临时覆盖、空闲计时之类的东西，删之前一并请它扔掉。
+     */
+    runtime: ConversationRuntimePort;
+    /** 时钟，测试注入用；缺省 `Date.now` */
+    now?: () => number;
+}
+/** 目录是否存在；取不到（权限、悬空链接等）按「不存在」回报事实（D12） */
+export declare function pathExists(path: string): Promise<boolean>;
+/**
+ * 目录事实：路径 + 还在不在（PRD D12）。
+ *
+ * 只给事实，不给结论 —— 目录没了对话照样能看，是否禁掉发送由客户端判断。
+ */
+export declare function toFolderFact(cwd: string): Promise<FolderFact>;
+export declare class WorkspaceService {
+    private readonly workspaces;
+    private readonly conversations;
+    private readonly messages;
+    private readonly assets;
+    private readonly sweepAssets?;
+    private readonly runtime;
+    private readonly now;
+    constructor(deps: WorkspaceServiceDeps);
+    /**
+     * 列出项目（PRD D9 / D12 / R20）。
+     *
+     * 顺序按创建时间倒序（仓储里定死）。目录已不存在的项目默认也列出来 —— 它名下的对话
+     * 与历史仍然可用（D12），藏起来只会让人以为数据丢了；显式传 `includeMissingFolders: false`
+     * 时才过滤掉。
+     */
+    list(params?: WorkspaceListParams): Promise<WorkspaceListResult>;
+    /**
+     * 登记一个目录为项目（PRD D9 / D10）。
+     *
+     * 同一个 cwd 只登记一次（R14：两次登记会让两个 Scope 抢同一个目录）。名字不传就用
+     * 目录名 —— 这个名字之后可改，cwd 不可改。
+     */
+    create(params: WorkspaceCreateParams): Promise<WorkspaceCreateResult>;
+    get(params: WorkspaceGetParams): Promise<WorkspaceGetResult>;
+    /** 改名：id 与 cwd 不动（PRD D9），只换显示名 */
+    rename(params: WorkspaceRenameParams): Promise<WorkspaceRenameResult>;
+    /**
+     * 删项目（PRD D11 / D17 / F-F9 / R7）。
+     *
+     * `dryRun` 只算账：名下对话数、消息数、素材数，客户端拿去向用户说明代价。真删时按外键
+     * 级联把对话、消息、问题行、素材的引用关系一起删掉；`assets/` 下的文件不在服务的删除范围里
+     * （D11：目录本身宿主不碰），但素材的字节要按引用清 —— 那张图可能还有别的项目的对话在用，
+     * 所以只把「这些对话引用过哪几份素材」交给 asset 层，删完之后由它问「还剩几张引用」。
+     */
+    remove(params: WorkspaceRemoveParams): Promise<WorkspaceRemovalReport>;
+    private requireRow;
+    /**
+     * 组装一个项目的对外形状。
+     *
+     * `updatedAt` 在 `workspaces` 表里没有对应列，这里取「最近一次对话活动」当它；一条对话
+     * 都没有时就是创建时间。`lastActivityAt` 同理来自对话的 `updatedAt`（新增消息会推进它）。
+     */
+    private toView;
+}

package/dist/services/WorkspaceService.js

@@ -0,0 +1,213 @@
+/**
+ * Workspace 服务：项目（一个工作目录）的登记、查看、改名、删除。
+ *
+ * 对应能力编号：F-C1 的前置（项目中承载对话）、D9 / D10 / D12（一等公民、cwd 不可变、
+ * 目录不存在照常可看）、D11（删项目连带删名下对话，目录本身不碰）、D17（删除前给代价）、
+ * F-F9（不可撤销动作由客户端二次确认，宿主负责算账）、R14（cwd 唯一）、R20（列表顺序）。
+ *
+ * 这个服务只做「一条项目记录怎么变」与「代价是多少」；文件系统方面只回答一件事 ——
+ * 目录还在不在（`FolderFact.exists`），是否只读由客户端判断（D12）。
+ */
+import { randomUUID } from "node:crypto";
+import { stat } from "node:fs/promises";
+import { basename, isAbsolute, resolve } from "node:path";
+import { HostError } from "../wire/errors.js";
+/** 时间戳（毫秒）转 wire 上的 ISO 8601 字符串 */
+function iso(ms) {
+    return new Date(ms).toISOString();
+}
+/** 目录是否存在；取不到（权限、悬空链接等）按「不存在」回报事实（D12） */
+export async function pathExists(path) {
+    try {
+        const info = await stat(path);
+        return info.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 目录事实：路径 + 还在不在（PRD D12）。
+ *
+ * 只给事实，不给结论 —— 目录没了对话照样能看，是否禁掉发送由客户端判断。
+ */
+export async function toFolderFact(cwd) {
+    return { cwd, exists: cwd.length > 0 && (await pathExists(cwd)) };
+}
+/** 名字不能是空白串；`field` 用于把「哪个字段不对」结构化地告诉客户端 */
+function requireName(value, field) {
+    const name = typeof value === "string" ? value.trim() : "";
+    if (name.length === 0) {
+        throw new HostError("invalid_params", {
+            params: { field },
+            detail: { field, reason: "empty" },
+        });
+    }
+    return name;
+}
+/**
+ * cwd 归一化成绝对路径。
+ *
+ * 相对路径按宿主进程的工作目录解析会得到「随启动方式漂移」的路径（D9 的 cwd 一旦
+ * 定死就不再变），所以这里要求调用方给绝对路径，再由 `resolve` 把 `..`、尾斜杠归一。
+ */
+function normalizeCwd(value) {
+    const raw = typeof value === "string" ? value.trim() : "";
+    if (raw.length === 0) {
+        throw new HostError("invalid_params", {
+            params: { field: "cwd" },
+            detail: { field: "cwd", reason: "empty" },
+        });
+    }
+    if (!isAbsolute(raw)) {
+        throw new HostError("invalid_params", {
+            params: { field: "cwd" },
+            detail: { field: "cwd", reason: "not_absolute", cwd: value },
+        });
+    }
+    return resolve(raw);
+}
+export class WorkspaceService {
+    workspaces;
+    conversations;
+    messages;
+    assets;
+    sweepAssets;
+    runtime;
+    now;
+    constructor(deps) {
+        this.workspaces = deps.workspaces;
+        this.conversations = deps.conversations;
+        this.messages = deps.messages;
+        this.assets = deps.assets;
+        this.sweepAssets = deps.sweepAssets;
+        this.runtime = deps.runtime;
+        this.now = deps.now ?? Date.now;
+    }
+    /**
+     * 列出项目（PRD D9 / D12 / R20）。
+     *
+     * 顺序按创建时间倒序（仓储里定死）。目录已不存在的项目默认也列出来 —— 它名下的对话
+     * 与历史仍然可用（D12），藏起来只会让人以为数据丢了；显式传 `includeMissingFolders: false`
+     * 时才过滤掉。
+     */
+    async list(params = {}) {
+        const rows = await this.workspaces.list();
+        const views = [];
+        for (const row of rows) {
+            const view = await this.toView(row);
+            if (params.includeMissingFolders === false && !view.folder.exists)
+                continue;
+            views.push(view);
+        }
+        return { workspaces: views };
+    }
+    /**
+     * 登记一个目录为项目（PRD D9 / D10）。
+     *
+     * 同一个 cwd 只登记一次（R14：两次登记会让两个 Scope 抢同一个目录）。名字不传就用
+     * 目录名 —— 这个名字之后可改，cwd 不可改。
+     */
+    async create(params) {
+        const cwd = normalizeCwd(params.cwd);
+        const existing = await this.workspaces.getByCwd(cwd);
+        if (existing) {
+            throw new HostError("invalid_params", {
+                params: { field: "cwd" },
+                detail: { field: "cwd", reason: "already_registered", cwd, workspaceId: existing.id },
+            });
+        }
+        const name = params.name === undefined || params.name.trim().length === 0
+            ? basename(cwd) || cwd
+            : params.name.trim();
+        const id = randomUUID();
+        await this.workspaces.create({ id, name, cwd, createdAt: this.now() });
+        const row = await this.workspaces.get(id);
+        if (!row) {
+            throw new HostError("internal", { detail: { reason: "workspace vanished after insert", id } });
+        }
+        return { workspace: await this.toView(row) };
+    }
+    async get(params) {
+        return { workspace: await this.toView(await this.requireRow(params.workspaceId)) };
+    }
+    /** 改名：id 与 cwd 不动（PRD D9），只换显示名 */
+    async rename(params) {
+        const row = await this.requireRow(params.workspaceId);
+        const name = requireName(params.name, "name");
+        await this.workspaces.rename(row.id, name);
+        return { workspace: await this.toView({ ...row, name }) };
+    }
+    /**
+     * 删项目（PRD D11 / D17 / F-F9 / R7）。
+     *
+     * `dryRun` 只算账：名下对话数、消息数、素材数，客户端拿去向用户说明代价。真删时按外键
+     * 级联把对话、消息、问题行、素材的引用关系一起删掉；`assets/` 下的文件不在服务的删除范围里
+     * （D11：目录本身宿主不碰），但素材的字节要按引用清 —— 那张图可能还有别的项目的对话在用，
+     * 所以只把「这些对话引用过哪几份素材」交给 asset 层，删完之后由它问「还剩几张引用」。
+     */
+    async remove(params) {
+        const row = await this.requireRow(params.workspaceId);
+        const conversations = await this.conversations.listByWorkspace(row.id);
+        const consequences = {
+            conversations: conversations.length,
+            messages: 0,
+            assets: 0,
+        };
+        const assetIds = new Set();
+        for (const conversation of conversations) {
+            // 这个数来自 `countByConversation`：每段对话在 `messages` 表里的全部行，**含子 Agent 的
+            // 消息**（它们落在同一张表、`parentToolCallId` 非空）。侧栏摘要的 `messageCount` 是另一条
+            // 读数（`listByConversation`，只数主线），所以「删这个项目会少多少条消息」通常比列表里那些
+            // 对话的条数加起来大——两个数在问两件事（删表代价 / 侧栏显示），不互相抵消。
+            consequences.messages += await this.messages.countByConversation(conversation.id);
+            const assets = await this.assets.listByConversation(conversation.id);
+            consequences.assets += assets.length;
+            for (const asset of assets)
+                assetIds.add(asset.id);
+        }
+        if (params.dryRun === true) {
+            return { removed: false, consequences, assetIds: [...assetIds] };
+        }
+        // 先请运行时忘掉这些对话，再删行：反过来会在运行时里留下指向已删记录的覆盖项
+        for (const conversation of conversations) {
+            await this.runtime.forget(conversation.id);
+        }
+        const changes = await this.workspaces.delete(row.id);
+        // 关系行已经随外键没了：归零的那几份素材才删行删文件
+        if (changes > 0)
+            await this.sweepAssets?.([...assetIds]);
+        return { removed: changes > 0, consequences, assetIds: [...assetIds] };
+    }
+    async requireRow(workspaceId) {
+        const row = typeof workspaceId === "string" && workspaceId.length > 0
+            ? await this.workspaces.get(workspaceId)
+            : undefined;
+        if (!row) {
+            throw new HostError("not_found", {
+                params: { entity: "workspace" },
+                detail: { workspaceId },
+            });
+        }
+        return row;
+    }
+    /**
+     * 组装一个项目的对外形状。
+     *
+     * `updatedAt` 在 `workspaces` 表里没有对应列，这里取「最近一次对话活动」当它；一条对话
+     * 都没有时就是创建时间。`lastActivityAt` 同理来自对话的 `updatedAt`（新增消息会推进它）。
+     */
+    async toView(row) {
+        const conversations = await this.conversations.listByWorkspace(row.id);
+        const lastActivityAt = conversations.reduce((latest, conversation) => latest === null || conversation.updatedAt > latest ? conversation.updatedAt : latest, null);
+        return {
+            id: row.id,
+            name: row.name,
+            folder: await toFolderFact(row.cwd),
+            createdAt: iso(row.createdAt),
+            updatedAt: iso(lastActivityAt ?? row.createdAt),
+            conversationCount: conversations.length,
+            lastActivityAt: lastActivityAt === null ? null : iso(lastActivityAt),
+        };
+    }
+}

package/dist/services/imageSize.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 图片的像素尺寸：从文件头解出 `width` / `height`（PRD F-H8 / 裁定 R76）。
+ *
+ * 客户端拿到这两个数就能先摆好占位框，不必等字节下载完再量，图片加载时界面不会跳。
+ *
+ * 认的容器只有两种，各读一处现成的字段：
+ *
+ *   - **PNG**：8 字节签名之后第一个块就是 IHDR，它的第 4–11 字节是大端宽高；
+ *   - **JPEG**：`SOI` 之后按段长逐段往后跳，碰到 `SOF0` / `SOF1` / `SOF2` 等帧头段就读它的高宽。
+ *
+ * 其它容器（以及截断、认不出的字节）回 `null`，尺寸这一栏就留空。
+ *
+ * {@link readImageSize} 是纯函数（Buffer 进、尺寸出），{@link readImageSizeFromFile} 负责把
+ * 文件头读进来再交给它 —— 原图可能有 20MB（D5），这里只读开头一小段。
+ */
+/** 像素尺寸 */
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+/**
+ * 读文件头时取多少字节。
+ *
+ * PNG 的尺寸在头 24 字节里；JPEG 的帧头段前面可能排着 APP1（EXIF，里面还常带一张缩略图）
+ * 这类段，几十 KB 的也见过。64 KiB 覆盖常见情况，又不会为了量尺寸把整份原图读进内存。
+ */
+export declare const IMAGE_HEAD_BYTES: number;
+/**
+ * 从文件头（前若干字节）解出像素尺寸；解不出来回 `null`。
+ *
+ * 入参可以是文件开头的一段，不要求是整份文件：两份解码都只往后读固定的几处字节，
+ * 不够长（截断）时按「解不出来」处理。
+ */
+export declare function readImageSize(header: Buffer): ImageSize | null;
+/**
+ * 读一个文件的头部字节，解出像素尺寸；打不开或解不出来都回 `null`。
+ *
+ * 这一步发生在素材已经改名落盘、登记入库之前，它的结论只影响 `assets.width` / `height`
+ * 两列，所以读失败不往外抛：素材该落的照样落。
+ */
+export declare function readImageSizeFromFile(absolutePath: string): Promise<ImageSize | null>;

package/dist/services/imageSize.js

@@ -0,0 +1,146 @@
+/**
+ * 图片的像素尺寸：从文件头解出 `width` / `height`（PRD F-H8 / 裁定 R76）。
+ *
+ * 客户端拿到这两个数就能先摆好占位框，不必等字节下载完再量，图片加载时界面不会跳。
+ *
+ * 认的容器只有两种，各读一处现成的字段：
+ *
+ *   - **PNG**：8 字节签名之后第一个块就是 IHDR，它的第 4–11 字节是大端宽高；
+ *   - **JPEG**：`SOI` 之后按段长逐段往后跳，碰到 `SOF0` / `SOF1` / `SOF2` 等帧头段就读它的高宽。
+ *
+ * 其它容器（以及截断、认不出的字节）回 `null`，尺寸这一栏就留空。
+ *
+ * {@link readImageSize} 是纯函数（Buffer 进、尺寸出），{@link readImageSizeFromFile} 负责把
+ * 文件头读进来再交给它 —— 原图可能有 20MB（D5），这里只读开头一小段。
+ */
+import { promises as fs } from "node:fs";
+/** PNG 的 8 字节签名 */
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+/** PNG 读到 IHDR 末尾需要的字节数（8 签名 + 4 块长 + 4 块类型 + 4 宽 + 4 高） */
+const PNG_HEADER_BYTES = 24;
+/**
+ * 读文件头时取多少字节。
+ *
+ * PNG 的尺寸在头 24 字节里；JPEG 的帧头段前面可能排着 APP1（EXIF，里面还常带一张缩略图）
+ * 这类段，几十 KB 的也见过。64 KiB 覆盖常见情况，又不会为了量尺寸把整份原图读进内存。
+ */
+export const IMAGE_HEAD_BYTES = 64 * 1024;
+/**
+ * 从文件头（前若干字节）解出像素尺寸；解不出来回 `null`。
+ *
+ * 入参可以是文件开头的一段，不要求是整份文件：两份解码都只往后读固定的几处字节，
+ * 不够长（截断）时按「解不出来」处理。
+ */
+export function readImageSize(header) {
+    return pngSize(header) ?? jpegSize(header);
+}
+/**
+ * 读一个文件的头部字节，解出像素尺寸；打不开或解不出来都回 `null`。
+ *
+ * 这一步发生在素材已经改名落盘、登记入库之前，它的结论只影响 `assets.width` / `height`
+ * 两列，所以读失败不往外抛：素材该落的照样落。
+ */
+export async function readImageSizeFromFile(absolutePath) {
+    let handle;
+    try {
+        handle = await fs.open(absolutePath, "r");
+        const head = Buffer.alloc(IMAGE_HEAD_BYTES);
+        const { bytesRead } = await handle.read(head, 0, IMAGE_HEAD_BYTES, 0);
+        return readImageSize(head.subarray(0, bytesRead));
+    }
+    catch {
+        // 文件不存在 / 读不了：当作量不到，尺寸留空
+        return null;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+// ---------------------------------------------------------------------------
+// PNG
+// ---------------------------------------------------------------------------
+/**
+ * PNG：签名 + 第一个块 IHDR 里的宽高（大端 uint32）。
+ *
+ * 签名对不上、第一块不是 IHDR（块长固定 13）、字节不够长，都回 `null`。
+ */
+function pngSize(buffer) {
+    if (buffer.length < PNG_HEADER_BYTES)
+        return null;
+    for (let index = 0; index < PNG_SIGNATURE.length; index += 1) {
+        if (buffer[index] !== PNG_SIGNATURE[index])
+            return null;
+    }
+    // 块长恒为 13、块类型恒为 "IHDR"：两处都对上才说明布局是 PNG 那一种
+    if (buffer.readUInt32BE(8) !== 13)
+        return null;
+    if (buffer.toString("latin1", 12, 16) !== "IHDR")
+        return null;
+    return positiveSize(buffer.readUInt32BE(16), buffer.readUInt32BE(20));
+}
+// ---------------------------------------------------------------------------
+// JPEG
+// ---------------------------------------------------------------------------
+/** 一个标记占两字节：`FF` + 标记值 */
+const MARKER_BYTES = 2;
+/** 段长字段本身占两字节，所以合法的段长至少是 2 */
+const MIN_SEGMENT_LENGTH = 2;
+/** 帧头段（SOF）：段内顺序是精度(1) + 高(2) + 宽(2) + 分量数(1)… */
+const SOF_DATA_BYTES = 5;
+/** 帧头标记：C0–CF 里除了 C4（DHT）、C8（JPG）、CC（DAC）这三个非 SOF 的 */
+function isFrameHeader(marker) {
+    return marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+}
+/**
+ * JPEG：从 `SOI` 开始按段长往后走，走到帧头段就取高宽。
+ *
+ * 段长让这里不必认每一个标记是什么意思（APPn / DQT / DHT 大小各不相同），跳过去就行。
+ * 走上 `SOS`（扫描数据开始）说明帧头段已经错过，字节不够长说明文件被截断 —— 两种都回 `null`。
+ */
+function jpegSize(buffer) {
+    if (buffer.length < 4)
+        return null;
+    if (buffer[0] !== 0xff || buffer[1] !== 0xd8)
+        return null;
+    let offset = 2;
+    while (offset + 1 < buffer.length) {
+        if (buffer[offset] !== 0xff)
+            return null;
+        let marker = buffer[offset + 1];
+        // 标记前面允许重复填 0xFF（编码器会这么写）
+        while (marker === 0xff) {
+            offset += 1;
+            if (offset + 1 >= buffer.length)
+                return null;
+            marker = buffer[offset + 1];
+        }
+        // 不带长度字段的独立标记：TEM(01) / RSTn(D0–D7) / SOI(D8) / EOI(D9)
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+            offset += MARKER_BYTES;
+            continue;
+        }
+        // SOS(DA)：图像数据从这里开始，尺寸只能在前面的帧头段里
+        if (marker === 0xda)
+            return null;
+        if (offset + 4 > buffer.length)
+            return null;
+        const segmentLength = buffer.readUInt16BE(offset + 2);
+        if (segmentLength < MIN_SEGMENT_LENGTH)
+            return null;
+        if (isFrameHeader(marker)) {
+            const dataOffset = offset + 4;
+            if (dataOffset + SOF_DATA_BYTES > buffer.length)
+                return null;
+            const height = buffer.readUInt16BE(dataOffset + 1);
+            const width = buffer.readUInt16BE(dataOffset + 3);
+            return positiveSize(width, height);
+        }
+        // 下一段 = 这一段的标记两字节 + 段长（段长从它自己那两字节算起）
+        offset += MARKER_BYTES + segmentLength;
+    }
+    return null;
+}
+/** 宽高都要是正数；0 或负值只可能来自读错了位置，按「解不出来」处理 */
+function positiveSize(width, height) {
+    return width > 0 && height > 0 ? { width, height } : null;
+}

package/dist/services/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 服务层出口：一服务一文件，全部按构造参数注入依赖（单根组装，PRD architecture §3）。
+ *
+ * 这里只做再导出。除了五个服务类与它们的依赖形状，还把两类**跨层要用的东西**一并导出：
+ *
+ *   1. {@link ConversationRuntimePort}：运行时（W2-D）要实现的窄接口。服务层靠它读「在不在跑」
+ *      与「删掉之后中止在跑的轮次」，自己不存这些状态（D28）。
+ *   2. `toAgentMessage` / `readUsage` / `toCoreRole`：存储行 → core 消息的唯一一份转换。
+ *      运行时要接着往下跑一轮时也得用同一份，否则同一行会读出两个样子（R21）。
+ */
+export { WorkspaceService, pathExists, toFolderFact } from "./WorkspaceService.js";
+export type { WorkspaceServiceDeps, WorkspaceRemovalReport } from "./WorkspaceService.js";
+export { ConversationService } from "./ConversationService.js";
+export type { ConversationRuntimePort, ConversationServiceDeps, ConversationRemovalReport, } from "./ConversationService.js";
+export { MessageService, readUsage, toAgentMessage, toCoreRole } from "./MessageService.js";
+export type { MessageDraftLookup, MessageServiceDeps } from "./MessageService.js";
+export { SearchService } from "./SearchService.js";
+export type { ConversationSummarizer, SearchServiceDeps } from "./SearchService.js";
+export { CredentialService } from "./CredentialService.js";
+export type { CredentialServiceDeps } from "./CredentialService.js";

package/dist/services/index.js

@@ -0,0 +1,15 @@
+/**
+ * 服务层出口：一服务一文件，全部按构造参数注入依赖（单根组装，PRD architecture §3）。
+ *
+ * 这里只做再导出。除了五个服务类与它们的依赖形状，还把两类**跨层要用的东西**一并导出：
+ *
+ *   1. {@link ConversationRuntimePort}：运行时（W2-D）要实现的窄接口。服务层靠它读「在不在跑」
+ *      与「删掉之后中止在跑的轮次」，自己不存这些状态（D28）。
+ *   2. `toAgentMessage` / `readUsage` / `toCoreRole`：存储行 → core 消息的唯一一份转换。
+ *      运行时要接着往下跑一轮时也得用同一份，否则同一行会读出两个样子（R21）。
+ */
+export { WorkspaceService, pathExists, toFolderFact } from "./WorkspaceService.js";
+export { ConversationService } from "./ConversationService.js";
+export { MessageService, readUsage, toAgentMessage, toCoreRole } from "./MessageService.js";
+export { SearchService } from "./SearchService.js";
+export { CredentialService } from "./CredentialService.js";

package/dist/services/secretMask.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 密钥掩码 —— 端点密钥与 MCP 的 oauth `clientSecret` 共用这一份（F-F2：明文不出网）。
+ *
+ * 两处密钥的读写口径完全一样，所以生成掩码与「识别入参是不是掩码」都只在这里写一次：
+ *
+ *   1. **读**：宿主返回给客户端的永远是 {@link maskSecret} 的结果，明文一个字节都不出网；
+ *   2. **写**：客户端「没改」用省略表达；万一它把读到的掩码原样写回来了，
+ *      {@link isSecretMask} 认得出来，宿主按磁盘原文保留，不会把掩码当密钥存下去。
+ *
+ * 单独成文件是因为服务的依赖方向是单向的（配置服务 → 发现服务），发现服务不能反向 import
+ * 配置服务；掩码这种纯函数放中间，两边都引它。
+ */
+/**
+ * 密钥的掩码（F-F2：明文不出网）。
+ *
+ * 短密钥整串都掩掉：`sk-1` 这种长度的密钥，露头露尾就等于把整串给人看了。
+ */
+export declare function maskSecret(secret: string): string;
+/**
+ * 入参是不是「当前那把密钥的掩码」（客户端把读回来的整行原样写回来时的情形）。
+ *
+ * 是掩码就当「这一项没改」，写盘时保留原值。当前没有密钥时不存在「掩码」这回事，恒为 false。
+ */
+export declare function isSecretMask(incoming: string, current: string): boolean;

package/dist/services/secretMask.js

@@ -0,0 +1,34 @@
+/**
+ * 密钥掩码 —— 端点密钥与 MCP 的 oauth `clientSecret` 共用这一份（F-F2：明文不出网）。
+ *
+ * 两处密钥的读写口径完全一样，所以生成掩码与「识别入参是不是掩码」都只在这里写一次：
+ *
+ *   1. **读**：宿主返回给客户端的永远是 {@link maskSecret} 的结果，明文一个字节都不出网；
+ *   2. **写**：客户端「没改」用省略表达；万一它把读到的掩码原样写回来了，
+ *      {@link isSecretMask} 认得出来，宿主按磁盘原文保留，不会把掩码当密钥存下去。
+ *
+ * 单独成文件是因为服务的依赖方向是单向的（配置服务 → 发现服务），发现服务不能反向 import
+ * 配置服务；掩码这种纯函数放中间，两边都引它。
+ */
+/**
+ * 密钥的掩码（F-F2：明文不出网）。
+ *
+ * 短密钥整串都掩掉：`sk-1` 这种长度的密钥，露头露尾就等于把整串给人看了。
+ */
+export function maskSecret(secret) {
+    const key = secret.trim();
+    if (key === "")
+        return "";
+    if (key.length <= 8)
+        return "…";
+    return `${key.slice(0, 3)}…${key.slice(-4)}`;
+}
+/**
+ * 入参是不是「当前那把密钥的掩码」（客户端把读回来的整行原样写回来时的情形）。
+ *
+ * 是掩码就当「这一项没改」，写盘时保留原值。当前没有密钥时不存在「掩码」这回事，恒为 false。
+ */
+export function isSecretMask(incoming, current) {
+    const secret = current.trim();
+    return secret !== "" && incoming.trim() === maskSecret(secret);
+}