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

package/dist/services/CompletionService.js

@@ -0,0 +1,442 @@
+/**
+ * `@` 补全的数据来源：一个项目的文件清单（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 { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { DEFAULT_LANGUAGE, render } from "../i18n/index.js";
+import { HostError } from "../wire/errors.js";
+const execFileAsync = promisify(execFile);
+// ---------------------------------------------------------------------------
+// 实现事实（D7 的几个数字）
+// ---------------------------------------------------------------------------
+/** 清单条数上限（D7：20000 条） */
+export const DEFAULT_MAX_ENTRIES = 20_000;
+/** 扫描超时（D7：5s） */
+export const DEFAULT_SCAN_TIMEOUT_MS = 5_000;
+/** 缓存有效期（D7：15s） */
+export const DEFAULT_CACHE_TTL_MS = 15_000;
+/** 一次补全默认回多少条 */
+export const DEFAULT_LIMIT = 50;
+/** 一次补全最多回多少条 */
+export const MAX_LIMIT = 500;
+/** 遍历时要跳过的目录名（D7：`node_modules/.git/dist`） */
+const EXCLUDED_DIRS = new Set(["node_modules", ".git", "dist"]);
+/** `git ls-files` 的超时上限（比扫描预算略小，留出解析与遍历的时间） */
+const GIT_TIMEOUT_MARGIN_MS = 500;
+/** 真实时钟 */
+export const systemCompletionClock = {
+    now: () => Date.now(),
+    setTimeout: (handler, ms) => {
+        const timer = setTimeout(handler, ms);
+        timer.unref?.();
+        return () => clearTimeout(timer);
+    },
+};
+// ---------------------------------------------------------------------------
+// 文案
+// ---------------------------------------------------------------------------
+function text(messageKey, params = {}) {
+    return {
+        code: messageKey,
+        messageKey,
+        params,
+        message: render(DEFAULT_LANGUAGE, messageKey, params),
+    };
+}
+// ---------------------------------------------------------------------------
+// 服务
+// ---------------------------------------------------------------------------
+export class CompletionService {
+    findWorkspace;
+    runGit;
+    clock;
+    maxEntries;
+    scanTimeoutMs;
+    cacheTtlMs;
+    /** workspaceId → 扫描状态（cwd 创建即定死，PRD D9，所以按项目缓存是安全的） */
+    states = new Map();
+    constructor(options = {}) {
+        this.findWorkspace = options.findWorkspace;
+        this.runGit = options.runGit ?? defaultGitLister;
+        this.clock = options.clock ?? systemCompletionClock;
+        this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.scanTimeoutMs = options.scanTimeoutMs ?? DEFAULT_SCAN_TIMEOUT_MS;
+        this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    }
+    /**
+     * `completion.files`（F-H5 / D7）。
+     *
+     * 三条出口，全部带 `state`：
+     *   - 有现成清单 → `ready`（可能带「不完整 / 被截断」的说明）；
+     *   - 正在扫 → `scanning`（客户端继续打字时会再来问一次）；
+     *   - 扫不出来 → `unavailable` + 原因。
+     */
+    async files(params) {
+        const workspaceId = requireWorkspaceId(params.workspaceId);
+        const cwd = await this.resolveCwd(workspaceId);
+        const state = this.stateOf(workspaceId);
+        const fresh = state.expiresAt !== null && state.expiresAt > this.clock.now();
+        if (fresh)
+            return this.respond(state, params);
+        if (state.pending === null) {
+            // 第一次问：起一次后台扫描，先如实说「还在扫」（D7：未就绪要说话）
+            state.pending = this.scan(cwd, state).finally(() => {
+                state.pending = null;
+            });
+        }
+        return {
+            state: "scanning",
+            entries: [],
+            truncated: false,
+            scannedAt: null,
+            problem: text("completion.scanning"),
+        };
+    }
+    /**
+     * 等一次扫描落地（预热与用例用）。
+     *
+     * 接线层可以在项目被打开时预取一次：这样用户第一次按 `@` 已经是 `ready`。
+     */
+    async prefetch(workspaceId) {
+        const id = requireWorkspaceId(workspaceId);
+        const state = this.stateOf(id);
+        if (state.pending !== null) {
+            await state.pending;
+            return;
+        }
+        if (state.expiresAt !== null && state.expiresAt > this.clock.now())
+            return;
+        const cwd = await this.resolveCwd(id);
+        state.pending = this.scan(cwd, state).finally(() => {
+            state.pending = null;
+        });
+        await state.pending;
+    }
+    /** 丢掉一个项目的缓存（项目被删时用；下次问会重新扫） */
+    forget(workspaceId) {
+        this.states.delete(workspaceId);
+    }
+    // -------------------------------------------------------------------------
+    // 扫描
+    // -------------------------------------------------------------------------
+    /**
+     * 扫一次并写状态。
+     *
+     * 超时不是「失败」：已经读到的那些仍然是真话，所以照常给出去，只是把
+     * 「不完整」这件事写在 `problem` 里（D7：未就绪要说话，而不是假装齐了）。
+     */
+    async scan(cwd, state) {
+        state.phase = "scanning";
+        state.paths = [];
+        state.truncated = false;
+        state.problem = null;
+        state.scannedAt = null;
+        state.expiresAt = null;
+        const bucket = [];
+        const flag = { truncated: false };
+        const work = this.collect(cwd, bucket, flag);
+        const outcome = await this.withTimeout(work);
+        if (outcome === "timeout") {
+            state.paths = bucket;
+            state.truncated = flag.truncated || bucket.length >= this.maxEntries;
+            state.scannedAt = this.clock.now();
+            state.problem = text("completion.timedOut", { seconds: this.scanTimeoutMs / 1000 });
+            // 读到了一点就还能用（哪怕不完整）；一条都没读到才是「拿不到」
+            state.phase = bucket.length > 0 ? "ready" : "unavailable";
+            if (state.phase === "unavailable") {
+                state.problem = text("completion.unavailable", {
+                    reason: render(DEFAULT_LANGUAGE, "completion.timedOut", {
+                        seconds: this.scanTimeoutMs / 1000,
+                    }),
+                });
+            }
+            state.expiresAt = state.scannedAt + this.cacheTtlMs;
+            return;
+        }
+        if (outcome.failure !== null) {
+            state.phase = "unavailable";
+            state.paths = [];
+            state.truncated = false;
+            state.scannedAt = this.clock.now();
+            state.problem = outcome.failure;
+            state.expiresAt = state.scannedAt + this.cacheTtlMs;
+            return;
+        }
+        state.phase = "ready";
+        state.paths = bucket;
+        state.truncated = flag.truncated;
+        state.scannedAt = this.clock.now();
+        state.problem = flag.truncated
+            ? text("completion.truncated", { limit: this.maxEntries })
+            : null;
+        state.expiresAt = state.scannedAt + this.cacheTtlMs;
+    }
+    /**
+     * 收集文件路径：git 仓库走 `git ls-files`，否则自己遍历。
+     *
+     * 失败时把「为什么拿不到」作为 `failure` 回出去（`null` 表示正常拿到）。
+     */
+    async collect(cwd, bucket, flag) {
+        let info;
+        try {
+            info = await fs.stat(cwd);
+        }
+        catch {
+            return {
+                failure: text("completion.unavailable", {
+                    reason: render(DEFAULT_LANGUAGE, "completion.noFolder"),
+                }),
+            };
+        }
+        if (!info.isDirectory()) {
+            return {
+                failure: text("completion.unavailable", {
+                    reason: render(DEFAULT_LANGUAGE, "completion.noFolder"),
+                }),
+            };
+        }
+        if (await this.isGitRepo(cwd)) {
+            const listing = await this.runGit(cwd, this.gitTimeout());
+            if (listing.ok) {
+                for (const file of listing.files) {
+                    if (bucket.length >= this.maxEntries) {
+                        flag.truncated = true;
+                        break;
+                    }
+                    const normalized = normalizePath(file);
+                    if (normalized !== "")
+                        bucket.push(normalized);
+                }
+                return { failure: null };
+            }
+            // git 跑不动（不在 PATH、仓库坏掉）就退回遍历：拿得到清单比走哪条路重要
+        }
+        try {
+            await this.walk(cwd, "", bucket, flag, 0);
+        }
+        catch (error) {
+            return {
+                failure: text("completion.unavailable", {
+                    reason: error instanceof Error ? error.message : String(error),
+                }),
+            };
+        }
+        return { failure: null };
+    }
+    /** 遍历目录（跳过 {@link EXCLUDED_DIRS}；符号链接不跟，避免环） */
+    async walk(root, relative, bucket, flag, depth) {
+        if (bucket.length >= this.maxEntries) {
+            flag.truncated = true;
+            return;
+        }
+        if (depth > 32)
+            return;
+        const dir = relative === "" ? root : join(root, relative);
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (bucket.length >= this.maxEntries) {
+                flag.truncated = true;
+                return;
+            }
+            if (entry.isSymbolicLink())
+                continue;
+            const childRelative = relative === "" ? entry.name : `${relative}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (EXCLUDED_DIRS.has(entry.name))
+                    continue;
+                await this.walk(root, childRelative, bucket, flag, depth + 1);
+                continue;
+            }
+            if (entry.isFile())
+                bucket.push(childRelative);
+        }
+    }
+    /** `<cwd>/.git` 在（目录或 worktree 的 `.git` 文件）就当它是 git 仓库 */
+    async isGitRepo(cwd) {
+        try {
+            await fs.stat(join(cwd, ".git"));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** 给 git 的超时：比整次扫描的预算略小 */
+    gitTimeout() {
+        return Math.max(this.scanTimeoutMs - GIT_TIMEOUT_MARGIN_MS, 1);
+    }
+    /** 跑 `work`，到点就放弃等它（返回 `"timeout"`） */
+    async withTimeout(work) {
+        // 取一个可变盒子：赋值发生在计时器回调里，TS 看不到那次赋值
+        const timer = { cancel: null };
+        const timeout = new Promise((resolve) => {
+            timer.cancel = this.clock.setTimeout(() => resolve("timeout"), this.scanTimeoutMs);
+        });
+        try {
+            return await Promise.race([work, timeout]);
+        }
+        finally {
+            timer.cancel?.();
+        }
+    }
+    // -------------------------------------------------------------------------
+    // 出口
+    // -------------------------------------------------------------------------
+    /** 状态 → 出参（只切出这次要的那一页） */
+    respond(state, params) {
+        if (state.phase !== "ready") {
+            return {
+                state: state.phase,
+                entries: [],
+                truncated: false,
+                scannedAt: state.scannedAt === null ? null : new Date(state.scannedAt).toISOString(),
+                problem: state.problem,
+            };
+        }
+        return {
+            state: "ready",
+            entries: selectEntries(state.paths, params.prefix ?? "", clampLimit(params.limit)),
+            truncated: state.truncated,
+            scannedAt: state.scannedAt === null ? null : new Date(state.scannedAt).toISOString(),
+            problem: state.problem,
+        };
+    }
+    stateOf(workspaceId) {
+        const existing = this.states.get(workspaceId);
+        if (existing)
+            return existing;
+        const created = {
+            phase: "scanning",
+            paths: [],
+            truncated: false,
+            scannedAt: null,
+            problem: null,
+            expiresAt: null,
+            pending: null,
+        };
+        this.states.set(workspaceId, created);
+        return created;
+    }
+    async resolveCwd(workspaceId) {
+        const found = this.findWorkspace ? await this.findWorkspace(workspaceId) : undefined;
+        if (!found) {
+            throw new HostError("not_found", {
+                params: { entity: "workspace" },
+                detail: {
+                    workspaceId,
+                    reason: this.findWorkspace ? "workspace_not_found" : "workspace_lookup_not_configured",
+                },
+            });
+        }
+        return found.cwd;
+    }
+}
+// ---------------------------------------------------------------------------
+// 默认的 git 执行器
+// ---------------------------------------------------------------------------
+/** 用子进程跑 `git ls-files`；不在仓库里或者没有 git 时回 `ok: false`（调用方退回遍历） */
+export const defaultGitLister = async (cwd, timeoutMs) => {
+    try {
+        const { stdout } = await execFileAsync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], { cwd, timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+        return {
+            ok: true,
+            files: stdout.split("\u0000").filter((item) => item !== ""),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            files: [],
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+};
+// ---------------------------------------------------------------------------
+// 纯函数
+// ---------------------------------------------------------------------------
+/** 入参的 workspaceId：空串按「参数不对」处理 */
+function requireWorkspaceId(value) {
+    const raw = typeof value === "string" ? value.trim() : "";
+    if (raw === "") {
+        throw new HostError("invalid_params", {
+            params: { field: "workspaceId" },
+            detail: { field: "workspaceId", reason: "empty" },
+        });
+    }
+    return raw;
+}
+/** 路径分隔符统一成 `/`，去掉开头的 `./` */
+function normalizePath(path) {
+    const unified = path.replace(/\\/g, "/");
+    return unified.startsWith("./") ? unified.slice(2) : unified;
+}
+/** 一次回多少条：缺省 {@link DEFAULT_LIMIT}，上限 {@link MAX_LIMIT} */
+function clampLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return DEFAULT_LIMIT;
+    const value = Math.floor(limit);
+    if (value <= 0)
+        return DEFAULT_LIMIT;
+    return Math.min(value, MAX_LIMIT);
+}
+/**
+ * 把清单按已输入的前缀切成「目录 + 文件」两类条目。
+ *
+ * 前缀可以是路径形式（`src/co`）：目录部分当过滤基准，最后一段当「还差什么」；
+ * 没有斜杠时（`@READ`）同时按路径开头与文件名开头匹配，这样根目录里的文件也找得到。
+ */
+export function selectEntries(paths, prefix, limit) {
+    const normalized = normalizePath(prefix.trim());
+    // 前缀以 `/` 结尾表示「这一层全要」：目录部分就是它，剩下要匹配的那一段为空
+    const underDirectory = normalized.endsWith("/");
+    const trimmed = underDirectory ? normalized.slice(0, -1) : normalized;
+    const slash = trimmed.lastIndexOf("/");
+    const baseDir = slash === -1 ? (underDirectory ? `${trimmed}/` : "") : trimmed.slice(0, slash + 1);
+    const partial = underDirectory
+        ? ""
+        : (slash === -1 ? trimmed : trimmed.slice(slash + 1)).toLowerCase();
+    const dirs = new Map();
+    const files = [];
+    for (const path of paths) {
+        if (baseDir !== "" && !path.toLowerCase().startsWith(baseDir.toLowerCase()))
+            continue;
+        const relative = baseDir === "" ? path : path.slice(baseDir.length);
+        if (relative === "")
+            continue;
+        const nextSlash = relative.indexOf("/");
+        if (nextSlash !== -1) {
+            const segment = relative.slice(0, nextSlash);
+            if (!segment.toLowerCase().startsWith(partial))
+                continue;
+            const dirPath = `${baseDir}${segment}`;
+            if (!dirs.has(dirPath)) {
+                dirs.set(dirPath, { path: dirPath, name: segment, kind: "directory" });
+            }
+            continue;
+        }
+        if (!relative.toLowerCase().startsWith(partial))
+            continue;
+        files.push({ path, name: relative, kind: "file" });
+    }
+    const orderedDirs = [...dirs.values()].sort((left, right) => left.name.localeCompare(right.name));
+    const orderedFiles = files.sort((left, right) => left.name.localeCompare(right.name));
+    return [...orderedDirs, ...orderedFiles].slice(0, limit);
+}

package/dist/services/ConfigService.d.ts

@@ -0,0 +1,171 @@
+/**
+ * 配置服务：`config.*`（F-F1 / F-F2 / F-E2 / F-F6 / F-F7 / F-A8 / D21）。
+ *
+ * 配置只有一处真相：数据根下的 `config.json`，读写都经 SDK 的 `ConfigManager`（D21）。
+ * 这个服务负责三件事：
+ *
+ *   1. **读得安全**：端点密钥读出即掩码（F-F2），明文不出网；顺带把「这份配置哪里不对」
+ *      结构化地报出来（F-A8：配错了要能当场修，问题指到具体字段）。
+ *   2. **写得及时**：每次写都回报「应用了什么」—— 哪些能力被重载、哪些 Workspace 的 Scope
+ *      被回收（随之重连 MCP）。改完不用重启（F-E2），客户端据此提示「已生效」。
+ *   3. **删得干净**：被引用的端点拒删并列出引用者（F-F2），默认项指向的东西不存在时
+ *      要能指出来（F-F7）。
+ *
+ * 「保存」这个动作本身不是状态：每次写就是一次生效（F-F1 没有全局保存键）。
+ */
+import type { AgentRepository } from "@ai-zen/agents-sdk";
+import type { AppConfig, ConfigManager } from "@ai-zen/agents-sdk";
+import type { ConfigDeleteEndpointParams, ConfigDeleteEndpointResult, ConfigDeleteMcpParams, ConfigDeleteMcpResult, ConfigGetDiscoveryParams, ConfigGetDiscoveryResult, ConfigGetParams, ConfigGetResult, ConfigPatchParams, ConfigPatchResult, ConfigSaveEndpointParams, ConfigSaveEndpointResult, ConfigSaveMcpParams, ConfigSaveMcpResult, ConfigSetDefaultsParams, ConfigSetDefaultsResult, ConfigView, HostReloadParams, HostReloadResult } from "../wire/index.js";
+import { DiscoveryService, type WorkspaceCwdLookup } from "./DiscoveryService.js";
+import { ModelService } from "./ModelService.js";
+/** 改配置时用到的几类「生效」信号（→ {@link ConfigApplyReport}） */
+export interface ConfigApplyChange {
+    /** `config.json` 被改写了 */
+    config: boolean;
+    /** 某一层 Mcp 被改写了 */
+    mcp: boolean;
+    /** 助手定义被改写了（`agent.*` 域用得到，配置域自己不会置它） */
+    agents: boolean;
+    /** 具体改了哪些段落：`endpoints` / `models` / `imageModels` / `defaults` / `limits` / `behavior` / `mcp` */
+    sections: string[];
+    /** MCP 变更涉及哪些项目（user 作用域时为空） */
+    workspaceIds: string[];
+}
+/** 改动生效之后能从组装层问到的事实 */
+export interface ConfigApplyOutcome {
+    /** 因为配置变化被回收（随后会重建）的 Workspace Scope */
+    recycledWorkspaceIds?: string[];
+    /** 这次改动合成的那一条通知（F-F9：一次改动合成一条通知） */
+    noticeId?: string | null;
+}
+/**
+ * 「让改动生效」的注入点。
+ *
+ * 谁能回收 Scope、谁能发通知，都是组装层知道的事（`ScopeRegistry` / 通知中心）；
+ * 配置服务只描述「变了什么」，由这一跳去动手、并回报真的回收了哪些。
+ */
+export interface ConfigApplyPort {
+    apply(change: ConfigApplyChange): Promise<ConfigApplyOutcome> | ConfigApplyOutcome;
+}
+/** 配置服务的依赖；由单根组装后注入 */
+export interface ConfigServiceOptions {
+    /** 配置唯一入口（SDK） */
+    configManager: ConfigManager;
+    /** 模型视图（`ConfigView.models` 与 `model.*` 用同一份口径）；缺省按本服务依赖造一个 */
+    models?: ModelService;
+    /** 能力发现（`config.getDiscovery` 与 `config.saveMcp` / `config.deleteMcp`）；缺省按本服务依赖造一个 */
+    discovery?: DiscoveryService;
+    /** 助手定义仓储（检查默认助手还在不在） */
+    agents?: AgentRepository;
+    /** 按 workspaceId 取 cwd（MCP 的 workspace 作用域要落到项目里） */
+    findWorkspace?: WorkspaceCwdLookup;
+    /** 让改动生效的注入点；不注入时回报「已重载配置、没有 Scope 被回收」 */
+    apply?: ConfigApplyPort;
+    /** 时钟，测试注入用；缺省 `Date.now` */
+    now?: () => number;
+}
+export declare class ConfigService {
+    private readonly configManager;
+    private readonly modelService;
+    private readonly discoveryService;
+    private readonly agents?;
+    private readonly findWorkspace?;
+    private readonly applyPort?;
+    private readonly now;
+    constructor(options: ConfigServiceOptions);
+    /** 能力发现服务（组装层要 `scopeAbilityPaths` / `mcpPaths` 时从这里拿同一份） */
+    get discovery(): DiscoveryService;
+    /** `config.get`（F-F1 / D21：读也走宿主，密钥掩码，同时报出配置问题） */
+    get(_params?: ConfigGetParams): Promise<ConfigGetResult>;
+    /** `config.getDiscovery`（F-G1 / F-G2 / F-F6）：转给发现服务，同一份口径 */
+    getDiscovery(params?: ConfigGetDiscoveryParams): Promise<ConfigGetDiscoveryResult>;
+    /**
+     * `config.patch`（F-F1 / F-E2）：默认项、上限、行为开关这些散落的小设置。
+     *
+     * 端点与模型各有自己的写方法（要做引用检查与掩码处理），不从这里进。
+     */
+    patch(params: ConfigPatchParams): Promise<ConfigPatchResult>;
+    /**
+     * `config.setDefaults`（F-F7 / D2 / D6 / R58）。
+     *
+     * 与 `config.patch` 的 `defaults` 是同一件事，只是入口更窄：默认助手、兜底模型、
+     * 迁移模型、图片模型、取名模型、自动命名开关，以及缺省语言（`hello` 没声明语言时用哪种）。
+     */
+    setDefaults(params: ConfigSetDefaultsParams): Promise<ConfigSetDefaultsResult>;
+    /**
+     * `host.reload`（PRD F-E1 / 裁定 R63）：从磁盘重读一遍，让改动生效。
+     *
+     * 不写盘：改的是磁盘上的东西（`config.json`、助手定义、技能 / 工具目录、MCP 文件），这里只
+     * 把「哪几类要重新装配」交给注入的生效一跳（回收受影响的 Scope + 合成一条通知），出参与
+     * `config.patch` 同一份形状，客户端于是可以用同一套提示。
+     */
+    reload(params?: HostReloadParams): Promise<HostReloadResult>;
+    /**
+     * `config.saveEndpoint`（F-F2）：同一个方法兼创建与修改。
+     *
+     * `apiKey` 省略 = 保留原值。把掩码当密钥存回去是这条路上最容易犯的错，所以：
+     *   - 省略 → 保留；
+     *   - 传回来的值正好等于当前掩码 → 当作「没改」（客户端把读到的整行原样写回来了）；
+     *   - 空串 → 把密钥清掉（这是唯一能清掉它的写法）。
+     */
+    saveEndpoint(params: ConfigSaveEndpointParams): Promise<ConfigSaveEndpointResult>;
+    /**
+     * `config.deleteEndpoint`（F-F2）：被模型引用时拒删并列出引用者。
+     *
+     * `dryRun` 只算引用：客户端先拿这份清单去问用户（F-F9 的二次确认）。
+     */
+    deleteEndpoint(params: ConfigDeleteEndpointParams): Promise<ConfigDeleteEndpointResult>;
+    /**
+     * `config.saveMcp`（F-F6 / F-G1）：有 id 则改、无则建，一次只动一条。
+     *
+     * `workspace` 作用域要落到某个项目自己的 `.ai-zen/mcp.json` 里，所以必须给 `workspaceId`。
+     * 合并与落盘的规则不在这里：发现服务的写入口只作一件事（把这一条叠到磁盘原文上），
+     * 于是这一版不认识的字段与 `oauth` 原样保留（F-F6）。
+     */
+    saveMcp(params: ConfigSaveMcpParams): Promise<ConfigSaveMcpResult>;
+    /**
+     * `config.deleteMcp`（F-F6）：删掉这一层里的一条。
+     *
+     * `id` 本来就不在这一层里时不是失败（`removed: false`）：重试一次删除、或另一个客户端
+     * 先一步删掉了，都不该变成一个错误（与 `config.deleteEndpoint` 的 `removed` 同口径）。
+     */
+    deleteMcp(params: ConfigDeleteMcpParams): Promise<ConfigDeleteMcpResult>;
+    /** MCP 写到哪：`user` 作用域与项目无关，`workspace` 作用域必须能拿到项目的 cwd */
+    private mcpWriteCwd;
+    /** 整个配置的只读形状（密钥掩码，F-F2） */
+    toView(config: AppConfig): Promise<ConfigView>;
+    private readConfig;
+    /** 端点的密钥：省略 / 等于当前掩码 → 保留原值；空串 → 清掉 */
+    private resolveApiKey;
+    /**
+     * 默认项合并（F-F7）。
+     *
+     * 每个 id 都要能落到实处：默认助手要真有定义文件，模型要在模型清单里，图片模型要在图片模型
+     * 清单里。传 `null` 表示清空（不是「不改」——不改就不传这个键）。
+     */
+    private mergeDefaults;
+    /** 上限合并（F-F8：工具输出上限） */
+    private mergeLimits;
+    /** 行为开关合并（D15 的中断修复口径 + F-E2 的工具刷新时机） */
+    private mergeBehavior;
+    /** workspace 作用域的 MCP 要写到项目里，所以必须能拿到 cwd */
+    private requireWorkspaceCwd;
+    /** 附件上限（D5：20MB/张、4 张/条）：与 wire 层的常量同源 */
+    private assetLimits;
+    /**
+     * 这份配置现在有什么问题。
+     *
+     * `error` 是「这么用会立刻失败」（模型指向不存在的端点、默认模型没了）；
+     * `warning` 是「能跑但不对劲」（端点还没配密钥、交接线不低于硬线）。
+     * 每条都带 `path`，客户端据此把光标放到那一栏。
+     */
+    private issuesOf;
+    /**
+     * 把一次改动「说出来」。
+     *
+     * `reloaded` 按改动涉及的段落推：端点 / 模型 / 图片模型 / 上限会改变工具与模型的可用性，
+     * MCP 会改变工具清单，所以这两种都算 `tools` 重载；`skills` 是每次装配现扫的目录，
+     * 配置改动不改变它。
+     */
+    private apply;
+}