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

package/dist/services/ConversationService.d.ts

@@ -0,0 +1,274 @@
+/**
+ * 对话服务：一段对话的诞生、改名、置顶、删除、撤回，以及两个「会话级调整」（换模型、换思考档位）。
+ *
+ * 对应能力编号：F-C1（稳定 id）、F-C3（可改名字）、F-C5（置顶 + 创建时间倒序）、
+ * F-C7（开新会话）、F-C8 / D24（撤回硬删 + 回填输入框）、F-C10 / D17（硬删 + 警告）、
+ * F-B4 / D20（会话级换模型、历史有图时拒绝降级）、F-B6 / F-B7（思考档位）、
+ * L5（重连按 id 拉）、L6（id 宿主分配）、R18（身份创建时必须有助手与模型）、
+ * R22（消息原样用 core 的类型）。
+ *
+ * 两条贯穿这个文件的边界：
+ *   1. **项目与助手创建即定死**：`workspaceId` / `agentId` 由 `create` 解析后落库，此后没有
+ *      任何方法改它们。模型与思考档位不在这条线上：它们是这段会话自己的，存在会话行上、可以改。
+ *   2. **服务层不缓存 agent、不驻留对话状态**：`running` 与「删掉之后的现场清理」都从注入的
+ *      {@link ConversationRuntimePort} 现取现放；模型与档位在库里，不在内存里存第二份。
+ */
+import type { ConfigManager } from "@ai-zen/agents-sdk";
+import type { ConversationDraftStore } from "../runtime/ConversationDrafts.js";
+import type { ChatEventEmitter } from "../runtime/ChatRunner.js";
+import type { Language } from "../i18n/index.js";
+import type { AssetRepository } from "../storage/AssetRepository.js";
+import type { ConversationRepository } from "../storage/ConversationRepository.js";
+import type { MessageRepository } from "../storage/MessageRepository.js";
+import type { QuestionRepository } from "../storage/QuestionRepository.js";
+import type { WorkspaceRepository } from "../storage/WorkspaceRepository.js";
+import type { Conversation } from "../storage/types.js";
+import type { ConversationCreateParams, ConversationCreateResult, ConversationDeleteParams, ConversationDeleteResult, ConversationGetParams, ConversationGetResult, ConversationListParams, ConversationListResult, ConversationPinParams, ConversationPinResult, ConversationRenameParams, ConversationRenameResult, ConversationRevertParams, ConversationRevertResult, ConversationSetModelParams, ConversationSetModelResult, ConversationSetThinkingParams, ConversationSetThinkingResult, ConversationSummary } from "../wire/index.js";
+/**
+ * 运行时注入给对话服务的窄接口。
+ *
+ * 只剩两件运行时才知道的事：
+ *   - 这段对话现在有没有在跑一轮（PRD F-I3 / D14，真相在 `RunRegistry` 一处）；
+ *   - 对话被删掉之后，把这一轮的现场丢掉（中止在跑的轮次）。
+ *
+ * 模型与思考档位不在这里：它们存在会话行上（`modelId` / `thinkingLevel`），服务层自己读写库。
+ *
+ * 服务层只按它读写，不 import `runtime/` 里的任何实现、也不自己存一份 —— 两份状态迟早
+ * 有一份先漂（D28：agent 用完即弃、对话不驻留）。
+ */
+export interface ConversationRuntimePort {
+    /** 这段对话现在是否在跑一轮 */
+    isRunning(conversationId: string): boolean;
+    /** 对话（或它的项目）被删掉之后，中止在跑的轮次并清掉现场 */
+    forget(conversationId: string): void | Promise<void>;
+}
+/** `conversation.delete` 的结果：wire 字段 + 交给 asset 层按引用清的文件清单 */
+export interface ConversationRemovalReport extends ConversationDeleteResult {
+    /**
+     * 这段对话引用过的素材 id。
+     *
+     * 行删了（关系行随外键级联消失）之后要交给素材层再问一次「还剩几张引用」：有人还在用就留着
+     * 字节，归零才删。这里只交 id，不交路径 —— 还在用的那份不该被当成可删的。
+     */
+    assetIds: string[];
+}
+/**
+ * 素材归零清扫口（`AssetService.sweepUnreferenced` 结构上满足）。
+ *
+ * 服务层不碰 `assets/` 下的文件：它只说「这几个素材可能没人用了」，删行删文件归素材层。
+ */
+export type AssetSweeper = (assetIds: string[]) => Promise<string[]>;
+/** 对话服务的依赖；由单根组装后注入 */
+export interface ConversationServiceDeps {
+    conversations: ConversationRepository;
+    messages: MessageRepository;
+    workspaces: WorkspaceRepository;
+    assets: AssetRepository;
+    /** 引用归零的素材交给它删行删文件；不注入时字节会留在盘上（引用行已经没了） */
+    sweepAssets?: AssetSweeper;
+    questions: QuestionRepository;
+    /** 配置唯一入口（SDK）：助手定义在 `<basePath>/agents/`，模型与默认项在 `config.json` 里 */
+    configManager: ConfigManager;
+    runtime: ConversationRuntimePort;
+    /** 草稿（R56）：`create` 只记在这里，首次 `send` 才落库；不注入时用一份自己的 */
+    drafts?: ConversationDraftStore;
+    /** 推 `conversation.changed`（多端在线同步，L5 / D22）；不注入时不推 */
+    emit?: ChatEventEmitter;
+    /** 时钟，测试注入用；缺省 `Date.now` */
+    now?: () => number;
+}
+export declare class ConversationService {
+    private readonly conversations;
+    private readonly messages;
+    private readonly workspaces;
+    private readonly assets;
+    private readonly sweepAssets?;
+    private readonly questions;
+    private readonly configManager;
+    private readonly runtime;
+    private readonly drafts;
+    private readonly emit?;
+    private readonly now;
+    /** 正在落库的草稿：同一个 id 的并发调用共用同一次写入（key 是 conversationId） */
+    private readonly persisting;
+    /** 助手定义是文件（PRD F-G3：一实体一文件），按配置根下的 `agents/` 目录读 */
+    private readonly agents;
+    constructor(deps: ConversationServiceDeps);
+    /**
+     * 列表（PRD F-C5 / D13）。
+     *
+     * 顺序由仓储定死：`pinned DESC, createdAt DESC` —— 活动、打开、改名都不影响它，所以这里
+     * 除了按 Workspace / 置顶筛、按 `limit` / `offset` 切页之外，不再重排。
+     *
+     * 列表只给已经落库的对话：草稿（还没发过消息，R56）不在侧栏里出现 —— 建了不发就断线
+     * 的那段对话应该像没建过一样。
+     */
+    list(params?: ConversationListParams): Promise<ConversationListResult>;
+    /**
+     * 开一段新对话（PRD F-C7 / L7 / R18 / R56）。
+     *
+     * 项目与助手在这里定死：项目就是入参的那个已登记项目（项目只走显式添加，PRD D10），助手从
+     * 磁盘上的定义文件解析。模型的值也在这里算出来（SDK 的三级解析 `会话级 > 助手定义 > 配置里的
+     * 兜底`，唯一实现在 `resolveModel`），但它落的是**会话行**：之后可以由 `setModel` 改。解析不
+     * 出来就报错，不写半成品行 —— 一条没有助手或没有模型的对话没有可用的身份。
+     *
+     * **这一行现在不写库**：只把 id 与身份留在草稿里（R56 / F-C2「没有用户消息就不写」）。
+     * 首次 `conversation.send` 时由 {@link ensurePersisted} 用同一个 id 落库。
+     */
+    create(params: ConversationCreateParams): Promise<ConversationCreateResult>;
+    /**
+     * 把草稿落成 `conversations` 的一行（R56：首次 `send` 时用同一个 id 写）。
+     *
+     * 已经在库里就直接返回那一行（重复调用是幂等的）；草稿不在、库里也没这一行就是
+     * `not_found`。先把草稿摘掉再写库：两次并发的调用里后到的那一次就抢不到同一份草稿，
+     * 不会两次插同一行；写失败时把草稿放回去，下一次还能再试。
+     *
+     * 但「抢不到草稿」不等于「这段对话不存在」：同一个 id 的并发调用（例如一次拖进四张图，
+     * 每个上传都在 `asset.begin` 里调一次）在这里排队共用同一次写入，免得后到的那次误报
+     * `not_found`、也免得那条隐藏的 cwd 消息被写两遍。
+     *
+     * 落行那一刻同时写上这段对话的第一条消息：一条 `hidden` 的 `user` 消息，告诉模型这段对话
+     * 对应的 cwd（PRD F-D9）。它最先写，所以 `seq` 在真实用户消息之前；之后每轮都不再重写。
+     * cwd 从这段对话的 Workspace 取（不是进程工作目录）；`workspaceId` 建会话时就定死了，
+     * 这里只读不改。
+     *
+     * `language` 是这条消息正文的渲染语言（D8：调用方传发起这条连接的语言；不传时用缺省语言）。
+     */
+    ensurePersisted(conversationId: string, language?: Language): Promise<Conversation>;
+    /** 草稿 → 库里那一行（含那条隐藏的 cwd 消息）；并发去重由 {@link ensurePersisted} 负责 */
+    private persistDraft;
+    /**
+     * 写会话开头那条 `hidden` 的 cwd 消息（PRD F-D9）。
+     *
+     * 它是一条普通的 `user` 消息，只是 `hidden` 为真：模型在上下文里能看到它，界面上不展示
+     * 它（core 的 `Message.hidden`）。内容用的是 i18n 里那两条既有键的拼装（与临时对话共用
+     * `injectedContextOf`）。
+     *
+     * cwd 来自这段对话所属的 Workspace（PRD D9：一段对话绑一个项目，cwd 创建即定死），
+     * 不读进程工作目录。
+     */
+    private writeCwdMessage;
+    /** 按 id 打开一段对话（PRD F-A6：宿主只提供「按 id 打开」） */
+    get(params: ConversationGetParams): Promise<ConversationGetResult>;
+    /** 改名（PRD D1 / F-C3）：只换名字，id、身份与排序都不动；名字从此归用户（R35） */
+    rename(params: ConversationRenameParams): Promise<ConversationRenameResult>;
+    /** 手动置顶（PRD F-C5 / D13）：只动 `pinned`，不碰创建时间 */
+    pin(params: ConversationPinParams): Promise<ConversationPinResult>;
+    /**
+     * 硬删一段对话（PRD F-C10 / D17 / F-F9 / R7）。
+     *
+     * `dryRun` 先算账（消息数、素材数），客户端据此警告用户。真删是 delete 语句 + 外键级联：
+     * 消息行、问题行、素材的引用关系（`conversation_assets`）随对话一起消失。素材行与 `assets/`
+     * 下的文件不一定：那张图可能还有别的对话在用，所以把「这段对话引用过哪几份素材」交给
+     * asset 层在删完之后再问一次「还剩几张引用」，归零才删（PRD D17「图片按引用清理」）。
+     *
+     * 还没落库的草稿也能删：没有行、没有消息、没有素材，代价是零。
+     */
+    delete(params: ConversationDeleteParams): Promise<ConversationRemovalReport>;
+    /**
+     * 撤回（PRD F-C8 / D24 / R10）。
+     *
+     * 撤回到某条**用户消息之前**：那条消息及其后全部硬删，被撤回的内容按 core 的内容形状
+     * 回给客户端填回输入框（只有纯文本段 + 当时带的素材 id，R62 / F-H3「带图消息连图一起
+     * 恢复」）。不留删除痕迹（R10）；正在跑一轮时拒绝，不然删的正是流式还在写的那几条。
+     */
+    revert(params: ConversationRevertParams): Promise<ConversationRevertResult>;
+    /**
+     * 换这段会话的模型（PRD F-B4 / F-B8 / D20）。
+     *
+     * 写的是**会话行**上的 `modelId`：这一段对话以后都用新模型，重开、重启都还是它。换模型
+     * 同时把这段会话的思考档位清成「跟随助手定义」—— 档位是模型的档位，同一个名字在不同
+     * 模型上对应不同参数，留着就变成把旧模型的参数发给新模型。
+     *
+     * `modelId: null` 表示回到助手定义上那个模型（它也没绑时用配置里的兜底）。
+     * 历史里已经有图、而新模型不看图时拒绝（D20），并说明原因。
+     */
+    setModel(params: ConversationSetModelParams): Promise<ConversationSetModelResult>;
+    /**
+     * 调这段会话的思考档位（PRD F-B6 / F-B7）。
+     *
+     * 写的是档位名（不是展开后的参数）：档位属于模型，同一个名字在不同模型的策略表里对应
+     * 不同参数。`level: null` 表示回到「跟随助手定义」。改助手默认档是另一个动作
+     * （`agent.setThinking`）。
+     *
+     * 档位名必须在该模型引用的策略表里 —— 表里没有的档发出去只会换来一句 400；模型没有
+     * 可调档位时整件事不成立（`unsupported`）。
+     */
+    setThinking(params: ConversationSetThinkingParams): Promise<ConversationSetThinkingResult>;
+    /**
+     * 把一批对话行拼成侧栏用的摘要（列表与搜索共用同一份口径）。
+     *
+     * `nameIsAuto` 直接读库里的那一列（R35）：它是「这个名字是不是自动起的」的唯一真值，
+     * 不由名字内容反推。
+     */
+    summarize(rows: Conversation[]): Promise<ConversationSummary[]>;
+    /** 一行对话 → 侧栏摘要；`pendingCount` 是挂在这段对话上还没答的问题数 */
+    private toSummary;
+    /** 拼一段对话的完整形状，顺带把 `setModel` 要的上下文占用一起算出来 */
+    private composeView;
+    /** 改完之后重新读一遍再拼视图：改名与置顶都要回写后的完整对象 */
+    private reloadView;
+    /**
+     * 推一条 `conversation.changed`（L5 / D22：两个窗口同时开着时，对方界面靠它去拉）。
+     *
+     * 只报「什么变了 + 够用的定位信息」，不搬整个对象（architecture §7）。
+     */
+    private emitChanged;
+    /**
+     * 读配置。
+     *
+     * `config.json` 是手改得了的文件（F-G3 的同款思路）：它坏了要让用户看见「配置用不了 +
+     * 哪一步读不动」，而不是一句「宿主内部错误」——所以解析失败在这里就折成 `config_invalid`。
+     */
+    private readConfig;
+    private viewContext;
+    /**
+     * 按 id 取一段对话：先看库里那一行，再看草稿（R56）。两者用同一份行形状，
+     * 于是视图拼装、换模型、写档位这些路径对草稿一字不改。
+     */
+    private requireConversation;
+    private requireWorkspace;
+    private loadWorkspace;
+    private loadAgent;
+    /** 读一个助手定义文件；不存在就是「没有这个助手」（PRD F-B5：不可用的也要说明原因） */
+    private readAgent;
+    private readAgentOrNull;
+    /**
+     * 这段对话**现在**用哪个模型：就是会话行上那个 `modelId`。
+     *
+     * 它可能已经从配置里删掉了 —— 那时 `model` 为空，调用方按 ID 显示。
+     */
+    private effectiveModel;
+    /**
+     * 这个模型是谁定的（PRD F-B4 两个动作的区别）。
+     *
+     * 会话行上的模型与助手定义绑的那个一致时算「跟着助手走」；否则算「会话自己定的」
+     * （创建时点名，或 `setModel` 改过）。助手没绑模型时它实际上用配置里的兜底，那一档也算
+     * 「跟着助手走」：装配时用的参数口径与这里同一个判断（见 `ChatRunner` 的 `conversationModelParams`）。
+     */
+    private modelSource;
+    /** 助手定义上那个模型（`/model` 不带 id 时回到它）；它没绑且没有兜底时报错 */
+    private agentModelIdOf;
+    /**
+     * 把模型写进会话（草稿还没落库时写进草稿，落库那一刻跟着写进去）。
+     *
+     * 与仓储的 `setModel` 一个口径：档位跟着清掉（档位是模型的档位）。
+     */
+    private writeModel;
+    /** 把思考档位写进会话（`null` = 回到跟随助手定义），回写后的行 */
+    private writeThinkingLevel;
+    /** 模型引用的思考策略（表里没有、或没有档位，就是「这个模型不可调」，F-B7） */
+    private presetOf;
+    /**
+     * 思考强度状态（PRD F-B6 / F-B7）。
+     *
+     * 三种来源：会话行上选了某一档（`manual`）；没选、而助手定义上的参数正好是某一档
+     * （`following_default`）；模型没有思考策略（`not_adjustable`）。
+     * 行上那个档位名在当前模型的策略表里不存在（换过模型、或策略表被改）时退回「跟随助手」。
+     */
+    private buildThinking;
+    /** 历史里有没有图（D20 的依据：消息内容里的图片段，或这段对话名下带图的素材） */
+    private hasImages;
+    /** 一批消息引用过的素材 id（删消息之前读一次：关系行随消息级联消失） */
+    private collectAssetsOfMessages;
+}