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

package/dist/services/AutoNaming.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 自动命名（PRD D2 / F-C4）。
+ *
+ * 触发条件三件事同时成立才起名，缺一不动：
+ *
+ *   1. **第一轮结束之后**（本文件按「这段对话里只有一条用户消息」判定：第一轮刚结束就是这个
+ *      形状，第二轮之后就不再满足）；
+ *   2. **用户没改过名字**（`conversations.nameIsAuto`，R35 的那一列；不由名字内容反推）；
+ *   3. **开关开着**（`AppConfig.autoTitle`，缺省视为开 —— 老配置里没有这个字段，用户的意图
+ *      显然是「按出厂的样子跑」）。
+ *
+ * 用哪一个模型：「取名模型」`AppConfig.namingModel`，没配就回落 `defaultModel`；两个都拿不到
+ * 就**保持原名**（原名 = 创建时间，D2）。起不出名（调用失败 / 模型给了个空串）同样保持原名，
+ * 不报错、不重试 —— 改名是锦上添花，不该在界面上留一条失败提示。
+ *
+ * 写回走 `applyAutoName`（而不是用户改名那个方法）：它把 `nameIsAuto` 置 1，于是「这个名字是
+ * 自动起的」这个事实在库里继续成立（R35）。
+ */
+import type { ConfigManager } from "@ai-zen/agents-sdk";
+import type { Language } from "../i18n/index.js";
+import type { ChatEventEmitter } from "../runtime/ChatRunner.js";
+import type { ConversationRepository } from "../storage/ConversationRepository.js";
+import type { MessageRepository } from "../storage/MessageRepository.js";
+import type { ProblemFact } from "../wire/index.js";
+import type { NoticeService } from "./NoticeService.js";
+/** 一次「取名」调用的形状（用例注入替身，不必连模型） */
+export type TitleCompleter = (input: {
+    system: string;
+    user: string;
+    modelId: string;
+}) => Promise<string>;
+/** 为什么这次没起名（内部结果，用于测试与日志；不出网） */
+export type AutoNameSkip = "conversation_missing" | "config_unreadable" | "disabled" | "renamed_by_user" | "not_first_turn" | "already_named" | "no_model" | "empty_title" | "call_failed";
+/** 一次自动命名的结果 */
+export interface AutoNameOutcome {
+    /** 这次有没有真的改名 */
+    named: boolean;
+    /** 结果名字（没改名时是原来的名字） */
+    name: string;
+    /** 没改名时是原因；改了就为 `null` */
+    skipped: AutoNameSkip | null;
+    /** 起不出名的事实（失败时给结构化原因，便于日志与测试断言） */
+    problem: ProblemFact | null;
+}
+export interface AutoNamingDeps {
+    conversations: ConversationRepository;
+    messages: MessageRepository;
+    configManager: ConfigManager;
+    /** 取名调用；缺省走 SDK 的 `completeOnce`（与交接摘要共用同一份请求体形状） */
+    complete?: TitleCompleter;
+    /** 通知通道（起好名字后那条「给它起名叫…」的提示，F-I8） */
+    notices?: NoticeService;
+    emit?: ChatEventEmitter;
+    now?: () => number;
+}
+export declare class AutoNaming {
+    private readonly conversations;
+    private readonly messages;
+    private readonly configManager;
+    private readonly complete;
+    private readonly notices?;
+    private readonly emit?;
+    private readonly now;
+    /**
+     * 本进程里已经起过名的对话。
+     *
+     * 库里的 `nameIsAuto` 区分不了「没起过」与「自动起过」（R35 两条都置 1），而「第一轮」
+     * 这条判定在同一个轮次里连续调两次时会重复成立。这一份只防「同一进程内重复起名」，
+     * 重启后若仍是第一轮会再起一次 —— 那次起名同样只在第一轮里发生。
+     */
+    private readonly named;
+    constructor(deps: AutoNamingDeps);
+    /**
+     * 一轮结束之后调一次（接线层在 `conversation.send` 结算后调用）。
+     *
+     * 这个方法是幂等且可反复调用的：条件不成立时什么都不做（直接返回原因），所以接在每一轮
+     * 之后都不会多做一次请求 —— 第二轮之后 `not_first_turn` 会把后面的调用全部挡住。
+     */
+    afterTurn(conversationId: string, language?: Language): Promise<AutoNameOutcome>;
+    /** 这段对话当前该不该起名（接线层在调用前想做别的判断时用；不改任何状态） */
+    shouldName(conversationId: string): Promise<{
+        should: boolean;
+        reason: AutoNameSkip | null;
+    }>;
+    /**
+     * 缺省的取名调用：用 SDK 的 `completeOnce`（与交接摘要共用同一份请求体形状）。
+     *
+     * 客户端按配置里的模型现场装配（`createModelFromConfig`）—— 起名是一次几十 token 的小
+     * 请求，为它拉一个 Scope（会连带连 MCP）代价与收益不成比例，所以这里不借 Scope。
+     */
+    private completeOnce;
+}

package/dist/services/AutoNaming.js

@@ -0,0 +1,235 @@
+/**
+ * 自动命名（PRD D2 / F-C4）。
+ *
+ * 触发条件三件事同时成立才起名，缺一不动：
+ *
+ *   1. **第一轮结束之后**（本文件按「这段对话里只有一条用户消息」判定：第一轮刚结束就是这个
+ *      形状，第二轮之后就不再满足）；
+ *   2. **用户没改过名字**（`conversations.nameIsAuto`，R35 的那一列；不由名字内容反推）；
+ *   3. **开关开着**（`AppConfig.autoTitle`，缺省视为开 —— 老配置里没有这个字段，用户的意图
+ *      显然是「按出厂的样子跑」）。
+ *
+ * 用哪一个模型：「取名模型」`AppConfig.namingModel`，没配就回落 `defaultModel`；两个都拿不到
+ * 就**保持原名**（原名 = 创建时间，D2）。起不出名（调用失败 / 模型给了个空串）同样保持原名，
+ * 不报错、不重试 —— 改名是锦上添花，不该在界面上留一条失败提示。
+ *
+ * 写回走 `applyAutoName`（而不是用户改名那个方法）：它把 `nameIsAuto` 置 1，于是「这个名字是
+ * 自动起的」这个事实在库里继续成立（R35）。
+ */
+import { AgentNS } from "@ai-zen/agents-core";
+import { completeOnce, createModelFromConfig } from "@ai-zen/agents-sdk";
+import { DEFAULT_LANGUAGE, render } from "../i18n/index.js";
+import { toAgentMessage } from "./MessageService.js";
+/** 起名时喂给模型的正文上限（够看出在聊什么，又不至于把整段历史发一遍） */
+const PROMPT_CHARS = 2000;
+/** 起出来的名字最长多少个字符（侧栏一行的容量） */
+const MAX_TITLE_CHARS = 60;
+/**
+ * 起名的指令。
+ *
+ * 这是**给模型看**的提示，不是界面文案，所以不走 i18n 键空间（那套是给人看的句子）。
+ */
+const TITLE_INSTRUCTION = [
+    "You name conversations. Read the exchange below and give it a short title.",
+    "Rules: at most 6 words, no quotes, no trailing punctuation, no preamble like \"Title:\".",
+    "Name what the task actually is, in the language the user wrote in.",
+    "Answer with the title only.",
+].join("\n");
+function iso(ms) {
+    return new Date(ms).toISOString();
+}
+/** 一段消息里的纯文本（分段内容只取文本段） */
+function textOf(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((section) => ("text" in section && typeof section.text === "string" ? section.text : ""))
+            .filter((text) => text.length > 0)
+            .join("\n");
+    }
+    return "";
+}
+/** 截断到上限（模型看到的正文不必比这更长） */
+function clip(text, limit) {
+    const trimmed = text.trim();
+    return trimmed.length > limit ? `${trimmed.slice(0, limit)}…` : trimmed;
+}
+/**
+ * 把模型那句「标题」收拾成能放进侧栏的一行。
+ *
+ * 模型常见的越界只有三种：加引号、写「Title: xxx」、换行写解释。三种都在这里收掉；
+ * 收完是空串就当作「起不出名」。
+ */
+function sanitizeTitle(raw) {
+    let text = raw.trim();
+    if (text.length === 0)
+        return "";
+    text = text.split(/\r?\n/).find((line) => line.trim().length > 0) ?? "";
+    text = text.replace(/^\s*(title|name|标题)\s*[:：]\s*/i, "").trim();
+    text = text.replace(/^["'“”‘’「」『』]+|["'“”‘’「」『』]+$/g, "").trim();
+    text = text.replace(/\s+/g, " ").trim();
+    text = text.replace(/[。．.,，;；:：!！?？]+$/g, "").trim();
+    if (text.length === 0)
+        return "";
+    return text.length > MAX_TITLE_CHARS ? text.slice(0, MAX_TITLE_CHARS).trim() : text;
+}
+export class AutoNaming {
+    conversations;
+    messages;
+    configManager;
+    complete;
+    notices;
+    emit;
+    now;
+    /**
+     * 本进程里已经起过名的对话。
+     *
+     * 库里的 `nameIsAuto` 区分不了「没起过」与「自动起过」（R35 两条都置 1），而「第一轮」
+     * 这条判定在同一个轮次里连续调两次时会重复成立。这一份只防「同一进程内重复起名」，
+     * 重启后若仍是第一轮会再起一次 —— 那次起名同样只在第一轮里发生。
+     */
+    named = new Set();
+    constructor(deps) {
+        this.conversations = deps.conversations;
+        this.messages = deps.messages;
+        this.configManager = deps.configManager;
+        this.complete =
+            deps.complete ??
+                (async (input) => await this.completeOnce(input.system, input.user, input.modelId));
+        this.notices = deps.notices;
+        this.emit = deps.emit;
+        this.now = deps.now ?? Date.now;
+    }
+    /**
+     * 一轮结束之后调一次（接线层在 `conversation.send` 结算后调用）。
+     *
+     * 这个方法是幂等且可反复调用的：条件不成立时什么都不做（直接返回原因），所以接在每一轮
+     * 之后都不会多做一次请求 —— 第二轮之后 `not_first_turn` 会把后面的调用全部挡住。
+     */
+    async afterTurn(conversationId, language = DEFAULT_LANGUAGE) {
+        const conversation = await this.conversations.get(conversationId);
+        if (!conversation) {
+            return skip("conversation_missing", "", null);
+        }
+        let config;
+        try {
+            config = await this.configManager.read();
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return skip("config_unreadable", conversation.name, failure(reason, language));
+        }
+        if (config.autoTitle === false)
+            return skip("disabled", conversation.name, null);
+        if (!conversation.nameIsAuto)
+            return skip("renamed_by_user", conversation.name, null);
+        if (this.named.has(conversation.id))
+            return skip("already_named", conversation.name, null);
+        const rows = await this.messages.listByConversation(conversation.id);
+        const messages = rows.map((row) => toAgentMessage(row));
+        const userMessages = messages.filter((message) => message.role === AgentNS.Role.User);
+        if (userMessages.length !== 1)
+            return skip("not_first_turn", conversation.name, null);
+        // 取名模型：配了就用它，否则回落兜底模型；配置里找不到这个模型也等于「没有取名模型」
+        const namingModelId = config.namingModel ?? config.defaultModel;
+        if (!namingModelId)
+            return skip("no_model", conversation.name, null);
+        const namingModel = config.models.find((model) => model.id === namingModelId);
+        if (!namingModel)
+            return skip("no_model", conversation.name, null);
+        const user = buildPrompt(userMessages, messages);
+        if (user.length === 0)
+            return skip("empty_title", conversation.name, null);
+        let title;
+        try {
+            title = await this.complete({ system: TITLE_INSTRUCTION, user, modelId: namingModel.id });
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return skip("call_failed", conversation.name, failure(reason, language));
+        }
+        const name = sanitizeTitle(title);
+        if (name.length === 0)
+            return skip("empty_title", conversation.name, null);
+        const updatedAt = this.now();
+        await this.conversations.applyAutoName(conversation.id, name, updatedAt);
+        this.named.add(conversation.id);
+        this.emit?.("conversation.changed", {
+            conversationId: conversation.id,
+            workspaceId: conversation.workspaceId,
+            change: "renamed",
+            messageCount: messages.length,
+            at: iso(updatedAt),
+        });
+        if (this.notices) {
+            await this.notices.create({
+                level: "info",
+                code: "notice.autoNamed",
+                params: { name },
+                duration: 5,
+                conversationId: conversation.id,
+            }, language);
+        }
+        return { named: true, name, skipped: null, problem: null };
+    }
+    /** 这段对话当前该不该起名（接线层在调用前想做别的判断时用；不改任何状态） */
+    async shouldName(conversationId) {
+        const conversation = await this.conversations.get(conversationId);
+        if (!conversation)
+            return { should: false, reason: "conversation_missing" };
+        const config = await this.configManager.read();
+        if (config.autoTitle === false)
+            return { should: false, reason: "disabled" };
+        if (!conversation.nameIsAuto)
+            return { should: false, reason: "renamed_by_user" };
+        const rows = await this.messages.listByConversation(conversationId);
+        const userCount = rows.filter((row) => row.role === AgentNS.Role.User).length;
+        if (userCount !== 1)
+            return { should: false, reason: "not_first_turn" };
+        if (!config.namingModel && !config.defaultModel)
+            return { should: false, reason: "no_model" };
+        return { should: true, reason: null };
+    }
+    /**
+     * 缺省的取名调用：用 SDK 的 `completeOnce`（与交接摘要共用同一份请求体形状）。
+     *
+     * 客户端按配置里的模型现场装配（`createModelFromConfig`）—— 起名是一次几十 token 的小
+     * 请求，为它拉一个 Scope（会连带连 MCP）代价与收益不成比例，所以这里不借 Scope。
+     */
+    async completeOnce(system, user, modelId) {
+        const config = await this.configManager.read();
+        const { client, model, modelConfig } = createModelFromConfig(config, modelId);
+        return await completeOnce({ client, model, modelConfig, system, user });
+    }
+}
+/** 喂给模型的正文：第一条用户消息 + 最后一条助手回复 */
+function buildPrompt(userMessages, messages) {
+    const first = userMessages[0];
+    const userText = clip(first ? textOf(first.content) : "", PROMPT_CHARS);
+    const lastAssistant = [...messages]
+        .reverse()
+        .find((message) => message.role === AgentNS.Role.Assistant);
+    const replyText = clip(lastAssistant ? textOf(lastAssistant.content) : "", PROMPT_CHARS);
+    return [
+        userText.length > 0 ? `You: ${userText}` : "",
+        replyText.length > 0 ? `Assistant: ${replyText}` : "",
+    ]
+        .filter((line) => line.length > 0)
+        .join("\n\n");
+}
+/** 没改名：带上原因 */
+function skip(reason, name, problem) {
+    return { named: false, name, skipped: reason, problem };
+}
+/** 起不出名的事实（`autoName.failed`：不报错，只是记下为什么保持原名） */
+function failure(reason, language) {
+    const params = { reason };
+    return {
+        code: "autoName.failed",
+        messageKey: "autoName.failed",
+        params,
+        message: render(language, "autoName.failed", params),
+        detail: { reason },
+    };
+}

package/dist/services/CompletionService.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `@` 补全的数据来源：一个项目的文件清单（F-H5 / D7）。
+ *
+ * 为什么在宿主：远程前端看不到目录（PRD §3 尺子 ①），`@` 菜单列的是磁盘上的真实文件。
+ *
+ * 口径（D7 逐条）：
+ *   - **按需扫描**：第一次问才扫，扫完缓存一下；
+ *   - **git 仓库优先 `git ls-files`**：只列 git 认的文件（含未跟踪但没被 ignore 的），天然排除了
+ *     `node_modules`、构建产物这些不该出现在补全里的东西；
+ *   - **非 git 用遍历**：跳过 `node_modules` / `.git` / `dist` 三个目录；
+ *   - **20000 条上限**：到了上限就停，并如实说「被截断了」；
+ *   - **5s 超时**：超时返回已经读到的那些（可能不完整），并说明它不完整；
+ *   - **15s 缓存**：15 秒内重复问不重新扫；
+ *   - **未就绪要说话**：还在扫就回 `scanning`，扫不出来回 `unavailable` + 原因。
+ *     假装空目录比慢更糟 —— 界面会以为这个项目里没有文件。
+ *
+ * 计时与「跑 git」都是注入点：用例用假时钟与假执行器验证超时 / 缓存 / 上限，
+ * 不需要真的等 5 秒，也不需要真的有 git。
+ */
+import type { CompletionFilesParams, CompletionFilesResult, FileEntryView } from "../wire/index.js";
+import type { WorkspaceCwdLookup } from "./DiscoveryService.js";
+/** 清单条数上限（D7：20000 条） */
+export declare const DEFAULT_MAX_ENTRIES = 20000;
+/** 扫描超时（D7：5s） */
+export declare const DEFAULT_SCAN_TIMEOUT_MS = 5000;
+/** 缓存有效期（D7：15s） */
+export declare const DEFAULT_CACHE_TTL_MS = 15000;
+/** 一次补全默认回多少条 */
+export declare const DEFAULT_LIMIT = 50;
+/** 一次补全最多回多少条 */
+export declare const MAX_LIMIT = 500;
+/** 计时入口（与 `runtime/ScopeRegistry` 的 `Clock` 同形状：`setTimeout` 返回取消函数） */
+export interface CompletionClock {
+    now(): number;
+    setTimeout(handler: () => void, ms: number): () => void;
+}
+/** 真实时钟 */
+export declare const systemCompletionClock: CompletionClock;
+/** 一次 `git ls-files` 的结果 */
+export interface GitListing {
+    ok: boolean;
+    /** NUL 分隔输出的那些路径（已经切成一条条） */
+    files: string[];
+    /** 失败原因（`ok === false` 时给） */
+    reason?: string;
+}
+/** 跑 git 的方式（测试注入假的，生产走高定制的 `defaultGitLister`） */
+export type GitLister = (cwd: string, timeoutMs: number) => Promise<GitListing>;
+/** 补全服务的依赖 */
+export interface CompletionServiceOptions {
+    /** 按 workspaceId 取 cwd（项目不存在时回 `undefined`） */
+    findWorkspace?: WorkspaceCwdLookup;
+    /** 跑 git 的方式；缺省用子进程跑 `git ls-files` */
+    runGit?: GitLister;
+    /** 计时入口；缺省真实时钟 */
+    clock?: CompletionClock;
+    maxEntries?: number;
+    scanTimeoutMs?: number;
+    cacheTtlMs?: number;
+}
+export declare class CompletionService {
+    private readonly findWorkspace?;
+    private readonly runGit;
+    private readonly clock;
+    private readonly maxEntries;
+    private readonly scanTimeoutMs;
+    private readonly cacheTtlMs;
+    /** workspaceId → 扫描状态（cwd 创建即定死，PRD D9，所以按项目缓存是安全的） */
+    private readonly states;
+    constructor(options?: CompletionServiceOptions);
+    /**
+     * `completion.files`（F-H5 / D7）。
+     *
+     * 三条出口，全部带 `state`：
+     *   - 有现成清单 → `ready`（可能带「不完整 / 被截断」的说明）；
+     *   - 正在扫 → `scanning`（客户端继续打字时会再来问一次）；
+     *   - 扫不出来 → `unavailable` + 原因。
+     */
+    files(params: CompletionFilesParams): Promise<CompletionFilesResult>;
+    /**
+     * 等一次扫描落地（预热与用例用）。
+     *
+     * 接线层可以在项目被打开时预取一次：这样用户第一次按 `@` 已经是 `ready`。
+     */
+    prefetch(workspaceId: string): Promise<void>;
+    /** 丢掉一个项目的缓存（项目被删时用；下次问会重新扫） */
+    forget(workspaceId: string): void;
+    /**
+     * 扫一次并写状态。
+     *
+     * 超时不是「失败」：已经读到的那些仍然是真话，所以照常给出去，只是把
+     * 「不完整」这件事写在 `problem` 里（D7：未就绪要说话，而不是假装齐了）。
+     */
+    private scan;
+    /**
+     * 收集文件路径：git 仓库走 `git ls-files`，否则自己遍历。
+     *
+     * 失败时把「为什么拿不到」作为 `failure` 回出去（`null` 表示正常拿到）。
+     */
+    private collect;
+    /** 遍历目录（跳过 {@link EXCLUDED_DIRS}；符号链接不跟，避免环） */
+    private walk;
+    /** `<cwd>/.git` 在（目录或 worktree 的 `.git` 文件）就当它是 git 仓库 */
+    private isGitRepo;
+    /** 给 git 的超时：比整次扫描的预算略小 */
+    private gitTimeout;
+    /** 跑 `work`，到点就放弃等它（返回 `"timeout"`） */
+    private withTimeout;
+    /** 状态 → 出参（只切出这次要的那一页） */
+    private respond;
+    private stateOf;
+    private resolveCwd;
+}
+/** 用子进程跑 `git ls-files`；不在仓库里或者没有 git 时回 `ok: false`（调用方退回遍历） */
+export declare const defaultGitLister: GitLister;
+/**
+ * 把清单按已输入的前缀切成「目录 + 文件」两类条目。
+ *
+ * 前缀可以是路径形式（`src/co`）：目录部分当过滤基准，最后一段当「还差什么」；
+ * 没有斜杠时（`@READ`）同时按路径开头与文件名开头匹配，这样根目录里的文件也找得到。
+ */
+export declare function selectEntries(paths: string[], prefix: string, limit: number): FileEntryView[];