@sunshaobei/dsh-mcp-manager 0.0.0-stage → 0.4.0

package/lib/server/catalog/impl/entries/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * dsh-mcp-manager — catalog/impl/entries/index.ts：能力目录条目与渲染（#664 阶段 5）。
+ *
+ * 自 src/catalog.ts 拆出（目录条目域）：条目类型/摘要常量/摘要计算/条目组装/
+ * 消息渲染与转义/消息定位读取。digest 与 history 归同域兄弟文件；目录注入决策
+ * 归 injection.ts；注入端缓存视图归 cache-view.ts；检索族归 search.ts。
+ */
+import type { SupervisorLite } from "../../../connection/interface.js";
+import type { CatalogMessage } from "../injection/index.js";
+import type { ContextFormed } from "@deepseek-ai/dsh-llm";
+import { DEFAULT_ANNOUNCE_CATALOG, DEFAULT_CATALOG_MAX_ENTRIES } from "../../../shared/interface.js";
+/**
+ * dsh 0.1.7-rc.2 producer-owned source kind。
+ *
+ * V4 将生产者身份编码进 kind；本包不再声明或依赖共享 `plugin` 基座，
+ * 也不把身份拆到 `plugin` 字段。snapshot 的 form/sections 由官方
+ * ContextFormed 约束。
+ */
+declare module "@deepseek-ai/dsh-llm" {
+    interface MessageSourceMap {
+        "plugin:dsh-mcp-manager": {
+            kind: "plugin:dsh-mcp-manager";
+        } & ContextFormed;
+    }
+}
+/** 目录条目。 */
+export interface CatalogEntry {
+    name: string;
+    text?: string;
+    /** 服务器归属（global/project）；用于区分调用引导（#228 双轨迁移）。 */
+    scope?: string;
+}
+/** supervisor 最小面（manager.supervisors 的条目；物理定义在 connection/interface.ts，此处 re-export）。 */
+export type { SupervisorLite } from "../../../connection/interface.js";
+/** 目录缓存（连接成功时持久化的工具描述摘要）。 */
+export type CatalogCache = Map<string, {
+    summary: string;
+}>;
+export { DEFAULT_ANNOUNCE_CATALOG, DEFAULT_CATALOG_MAX_ENTRIES };
+/** 本包 V4 producer-owned source kind；身份编码在 kind，不另设 plugin 字段。 */
+export declare const CATALOG_SOURCE_PLUGIN = "dsh-mcp-manager";
+export declare const CATALOG_SOURCE_KIND = "plugin:dsh-mcp-manager";
+/** 目录快照的段名（snapshot 形态下承载渲染后的目录正文）。 */
+export declare const CATALOG_SECTION_NAME = "mcp-catalog";
+/** 目录摘要总长上限（字符，含前缀与省略号）：目录注入 ≤6 条目，防远端工具描述
+ * 堆叠稀释上下文；截断先于 escapeCatalogText 转义，防不可信输入注入超长文本。 */
+export declare const CATALOG_SUMMARY_MAX_CHARS = 240;
+/** 目录摘要单句上限（字符）：无句读语言 / 超长描述的安全截断点。 */
+export declare const CATALOG_SUMMARY_PER_TOOL_CHARS = 120;
+/** 目录单条服务器描述上限（字符）：Level 1 发现层防远端超长说明书（如 context7 500 词）
+ * 撑爆会话上下文，符合渐进式披露原则。详细使用说明由 ws_mcp_detail / ws_mcp_search 按需承载。 */
+export declare const CATALOG_ENTRY_MAX_CHARS = 180;
+/**
+ * 从工具描述集合计算目录摘要（每工具取首句，按工具名升序 + 精确去重后拼接）。
+ *
+ * 为什么不再「排序取第一条」（#569）：tavily 等服务器的字典序第一条是次要工具
+ * （tavily_crawl），会把搜索服务器描述成爬虫、误导模型。改为每工具贡献首句：
+ * - 排序（按工具名而非描述）保证工具列表顺序/描述空白抖动时摘要稳定（重连不触发
+ *   缓存更新 → digest 不变）；
+ * - 首句提取（firstSentenceOf）防 "1." 编号 / URL / 缩写误切；多字节按字符截断；
+ * - 总长与单句均有上限：目录摘要的用途是让模型判断「该不该调这个服务器」，过长
+ *   描述（含远端不可信输入）反而稀释上下文；完整能力清单由 ws_mcp_list /
+ *   工具注册表承担，不塞进目录。
+ */
+export declare function summarizeToolDescriptions(toolMeta: Map<string, {
+    description?: unknown;
+}>): string | undefined;
+/** ① 收集 (工具名, 首句)；首句为空的工具不贡献摘要。 */
+export declare function collectToolSentences(toolMeta: Map<string, {
+    description?: unknown;
+}>): Array<[string, string]>;
+/** ② 按工具名升序（确定性：顺序抖动只变内容不变名序）→ 精确去重 → 单句截断。 */
+export declare function dedupeToolSentences(collected: Array<[string, string]>): string[];
+/** 单句上限截断（超限留一位给省略号）。 */
+export declare function truncatePerTool(sentence: string): string;
+/** ③ 拼接（"; " 分隔），超总长按句整段回退补 "…"（绝不句中切）。 */
+export declare function joinSentencesWithinBudget(sentences: string[], prefix: string): string;
+/**
+ * 生成能力目录条目（**数据源不依赖用户配置、不依赖实时连接状态**）：
+ * ① 服务器自定义 description（用户可选补充，优先）→
+ * ② 目录缓存摘要（连接成功时自动持久化的工具描述摘要，磁盘数据，与连接状态解耦）
+ * ③ 都没有 → 只显示服务器名。
+ * 连接/断开/重连不改变缓存内容 → digest 稳定 → 不触发重复注入。
+ * @param supervisors manager.supervisors（name → supervisor）。
+ * @param maxEntries 最大条目数。
+ * @param cache 目录缓存（manager.catalogCache）。
+ * @returns 目录条目。
+ */
+export declare function composeCatalogEntries(supervisors: Map<string, SupervisorLite>, maxEntries?: number, cache?: CatalogCache): CatalogEntry[];
+/** 条目描述文本的三级来源：① 用户自写描述（首句，空则整句压空白）→ ② 磁盘缓存摘要
+ * → ③ 都没有则 undefined（调用方据此不产出 text 键）。用户描述按单条上限截断。 */
+export declare function entryTextFor(name: string, server: SupervisorLite["server"], cache: CatalogCache | undefined): string | undefined;
+/** 渲染能力目录消息（source 标记供定位替换）。
+ *
+ * 当前 source 精确为 V4 producer-owned snapshot：
+ * `{ kind: "plugin:dsh-mcp-manager", form: "snapshot", sections: [...] }`。
+ */
+export declare function renderMcpCatalogMessage(entries: CatalogEntry[]): CatalogMessage;
+/** 转义远程来源文本（防提示注入/标签逃逸；与 skill catalog 的 escapeText 同思路）。
+ * 只做安全转义，**不做长度截断**（完整返回描述）。 */
+export declare function escapeCatalogText(value: unknown): string;
+/** 是否为本插件当前 V4 注入的能力目录消息。旧 V0/V2/V3 source 不在业务域兼容。 */
+export declare function isCatalogSource(source: {
+    kind?: unknown;
+} | undefined): boolean;
+/** 从消息列表里定位既有的当前 V4 能力目录消息。 */
+export declare function findCatalogMessage(messages: CatalogMessage[]): CatalogMessage | undefined;
+/**
+ * 取回一条目录消息所发布的条目：从快照正文的 `<available_mcp_servers>` 块还原
+ * 条目（格式化是单射的），使 digest 与 `composeCatalogEntries` 的条目 digest
+ * 同口径——否则每次启动都会误判"目录已变"而注入一条修正帧。
+ *
+ * 坏数据返回 undefined（按"不是本插件的目录"处理）：本函数在 step 监听器里被调用，
+ * 抛错会让该会话每一轮都失败。
+ */
+export declare function resolveCatalogEntries(source: CatalogSourceLike | undefined): CatalogEntry[] | undefined;
+/**
+ * 防御性读取当前 V4 source 的条目；旧 `entries` 形态由 maintenance 处理，
+ * 不在业务 reader 中兼容。
+ */
+export declare function readCatalogEntries(source: CatalogSourceLike | undefined): CatalogEntry[] | undefined;
+/** 当前 V4 source 最小面。 */
+export interface CatalogSourceLike {
+    kind?: unknown;
+    form?: unknown;
+    sections?: unknown;
+}
+/** 渲染"目录更新"消息（历史旧目录无法删除，新消息声明作废——与 tool-skill 同语义）。 */
+export declare function renderMcpCatalogUpdate(entries: CatalogEntry[]): CatalogMessage;

package/lib/server/catalog/impl/entries/type.d.ts

@@ -0,0 +1,19 @@
+/**
+ * dsh-mcp-manager — server/catalog/impl/entries/type.ts：目录条目类型落点（#767 W11b2a）。
+ *
+ * 目录外消费经 catalog/interface.ts 门面转出。
+ */
+/** 目录中的单服务器条目。 */
+export interface CatalogServer {
+    /** 发现时间戳。 */
+    discoveredAt: number;
+    /** 工具列表（裸名 → 描述 + schema 摘要）。 */
+    tools: Map<string, CatalogTool>;
+    /** 发现失败原因（unavailable 段）。 */
+    unavailable?: string;
+}
+/** 目录中的单工具。 */
+export interface CatalogTool {
+    description: string;
+    inputSchema: Record<string, unknown>;
+}

package/lib/server/catalog/impl/history/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * dsh-mcp-manager — catalog/impl/history/index.ts：会话内目录历史定位（#664 阶段 5）。
+ *
+ * 自 src/catalog.ts 拆出（history 域）：从会话持久化日志倒序找最后一条**可见**
+ * 的能力目录消息——目录注入去重的权威来源。新旧两代 source 形态都认（#723）。
+ */
+import type { CatalogSourceLike } from "../entries/index.js";
+/** 目录历史查询结果。 */
+export interface CatalogHistoryResult {
+    visibleDigest?: string;
+    published: boolean;
+}
+/** agent 最小面（session.snapshotEvents() 倒序找目录消息；0.1.2-rc.1 起 events getter 移除）。 */
+export interface CatalogAgent {
+    session?: {
+        surface?: {
+            nodes?: unknown[];
+        };
+        snapshotEvents?: () => ReadonlyArray<{
+            type?: string;
+            seq?: unknown;
+            data?: {
+                source?: CatalogSourceLike;
+            };
+        }>;
+    };
+}
+/**
+ * 从会话持久化日志（agent.session.snapshotEvents()）倒序找最后一条**可见**的
+ * 能力目录消息。**这是去重的权威来源**（与官方 dsh-tool-skill catalogHistory
+ * 同构）：
+ * - decision.messages 只含本轮新消息，历史目录消息不在其中——用它定位会导致每轮重复注入；
+ * - 可见性（surface.nodes）过滤：compaction/resume 后旧目录不可见 → visibleDigest 为空 → 重新注入；
+ * - 只认 snapshot 形态的目录消息（旧 kind:mcp-catalog 落盘走修复脚本迁移）。
+ */
+export declare function catalogHistory(agent: CatalogAgent | undefined): CatalogHistoryResult;

package/lib/server/catalog/impl/injection/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * dsh-mcp-manager — catalog/impl/injection/index.ts：能力目录注入决策（#664 阶段 5）。
+ *
+ * 自 src/catalog.ts 拆出（injection 域）：pre-step 监听器的目录注入决策纯函数，
+ * 完全复刻官方 dsh-tool-skill 的 catalog 语义（根治重复注入）。
+ */
+import type { CatalogCache, SupervisorLite } from "../entries/index.js";
+import type { CatalogAgent } from "../history/index.js";
+/** 会话消息最小面（pre-step decision.messages / session.snapshotEvents()）。 */
+export interface CatalogMessage {
+    id?: unknown;
+    role?: string;
+    content?: Array<{
+        type?: string;
+        text?: string;
+    }>;
+    source?: {
+        kind?: unknown;
+        plugin?: unknown;
+        form?: unknown;
+        entries?: unknown;
+        sections?: unknown;
+    };
+}
+/** pre-step 决策最小面。 */
+export interface CatalogDecision {
+    kind: string;
+    messages: CatalogMessage[];
+}
+/**
+ * 目录注入决策（纯函数，pre-step 监听器薄调用，便于单测）。
+ * 完全复刻官方 dsh-tool-skill 的 catalog 语义（根治重复注入）：
+ * 1. 历史（session.snapshotEvents()）digest 相同 → 本轮不注入（撤销本轮已注入的）——**去重源是历史而非本轮消息**；
+ * 2. 历史 digest 不同 → 注入"更新"消息（声明替换旧目录）；
+ * 3. 从未发布且无服务器 → 不注入；
+ * 4. compaction/resume 后旧目录不可见 → 重新注入（events-based 重建）。
+ * @param decision next() 的决策。
+ * @param messages 本轮输入消息（签名兼容）。
+ * @param supervisors manager.supervisors。
+ * @param maxEntries 目录条目上限。
+ * @param cache 目录缓存。
+ * @param agent pre-step 的 agent（session.snapshotEvents() 来源）。
+ * @returns 新决策。
+ */
+export declare function resolveCatalogInjection(decision: CatalogDecision, messages: CatalogMessage[], supervisors: Map<string, SupervisorLite>, maxEntries?: number, cache?: CatalogCache, agent?: CatalogAgent): CatalogDecision;

package/lib/server/catalog/impl/search/type.d.ts

@@ -0,0 +1,59 @@
+/**
+ * dsh-mcp-manager — server/catalog/impl/search/type.ts：检索输出类型落点（#767 W11b2a）。
+ *
+ * 目录外消费经 catalog/interface.ts 门面转出。
+ */
+/** ws_mcp_search 单条命中。 */
+export interface SearchHit {
+    server: string;
+    tool: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    score: number;
+    matchedTerms: string[];
+    fresh: boolean;
+}
+/** ws_mcp_list 的单个工具条目（完整清单只给摘要，防上下文膨胀）。 */
+export interface ListToolEntry {
+    tool: string;
+    description: string;
+    /** 工具级被用户禁用（独立于服务器级 enabled；仅在禁用时置位）。 */
+    disabled?: boolean;
+}
+/** ws_mcp_list 的单个服务器条目。 */
+export interface ListServerEntry {
+    /** @<root>/<server> 全名。 */
+    server: string;
+    /** 用户已禁用（工具来自 last-good 目录缓存，明示）。 */
+    disabled?: boolean;
+    /** 发现失败原因（unavailable 段）。 */
+    unavailable?: string;
+    tools: ListToolEntry[];
+    /** 工具数被 perServerLimit 截断。 */
+    toolsTruncated: boolean;
+}
+/** ws_mcp_detail 的单工具详情（完整 inputSchema）。 */
+export interface ToolDetail {
+    /** @<root>/<server> 全名。 */
+    server: string;
+    /** 远端工具裸名（已归一化）。 */
+    tool: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /** 目录是否新鲜（TTL 内）。 */
+    fresh: boolean;
+    /** 用户已禁用。 */
+    disabled?: boolean;
+}
+/** ws_mcp_list 输出（多单元合并的完整盘点）。 */
+export interface ListCatalogResult {
+    /** 当前工作空间 root；无项目 cwd 时为 "@global"。 */
+    workspace: string;
+    servers: ListServerEntry[];
+    totalServers: number;
+    totalTools: number;
+    /** 任一服务器截断即为 true。 */
+    toolsTruncated: boolean;
+    /** 空返回时给模型的明确提示。 */
+    message?: string;
+}

package/lib/server/catalog/impl/service/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * dsh-mcp-manager — catalog/impl/service/index.ts：目录域端口持有者（#767 B2a-wire W4）。
+ *
+ * 域内实现经 `catalogPorts.get()` 取数，写入只发生在组合根入口顶层的 `installCatalog`
+ * （见 `src/index.ts`）。形态照 `server/upgrade/impl/service/` 的 runner：模块级只有一个
+ * `const` 实例、状态收进实例字段（I9），装配与复位只经方法（方法内赋值）。
+ */
+import type { CatalogDeps } from "../../deps.js";
+/** 目录域端口表：装配一次、域内多处读。 */
+declare class CatalogPorts {
+    /** 未装配时保持 undefined——「没装配」与「装配了空实现」必须可区分（I6）。 */
+    private deps;
+    /** 装配：组合根递入静态模块引用；重复装配是编程错误，当场暴露。 */
+    install(deps: CatalogDeps): void;
+    /** 卸载：只复位装配标记，本域没有别的活资源要释放。 */
+    release(): void;
+    /**
+     * 域内取数的唯一入口。未装配即抛错而不是回落默认值：默认值会让「组合根漏装」表现成
+     * 行为正常但参数不对（目录 TTL 与检索/装箱限额静默换值），症状与本插件毫无字面关联。
+     */
+    get(): CatalogDeps;
+}
+/** 本域唯一的装配实例：类不外放，外部 new 不出第二份端口表。 */
+export declare const catalogPorts: CatalogPorts;
+export {};

package/lib/server/catalog/interface.d.ts

@@ -0,0 +1,45 @@
+/**
+ * dsh-mcp-manager — catalog/interface.ts：模型面+目录域唯一对外引用面（D10，#664 阶段 5）。
+ *
+ * 目录域 = 能力目录条目/渲染（entries）+ digest（digest）+ 会话内历史定位
+ * （history）+ 注入决策（injection）+ 注入端缓存视图（cache-view）+ 检索函数族
+ * （search），其中 entries/digest/history/injection/cache-view 五块住 impl/<块>/index.ts。
+ * 目录外模块**只能**从这里引用（verify-dir-imports 静态强制）；工具级禁用裁决
+ * （isToolDenied 等，#767 笔 2 后是唯一裁决）归执行管道域的 authorize 块。
+ *
+ * search 是本域唯一**暂留域根**的块——B2.4 就地重构的刻意偏差，不是漏做：它当时是
+ * fileCycles 那条环签名（catalog/interface.ts|catalog/search.ts|connection/interface.ts|
+ * connection/runtime/interface.ts|connection/runtime/middleware.ts）的成员，搬进
+ * impl/search/ 会让签名变成 catalog/impl/search/index.ts|... → verify-dir-imports 判
+ * 「新增未登记证据」且 --write-baseline 拒写（附录 G·G16 同族：证据 id 路径派生）。
+ * W4 装上 ConnectionPort 后该环已断（本笔实测叶子模块级 / 文件级值环均归零，基线同笔清理），
+ * 搬进 impl/search/ 不再制造证据位移；它改的是模块 id 与目录形态，与 B2b 的原子搬迁同笔。
+ */
+import type { CatalogDeps } from "./deps.js";
+/**
+ * 装配目录域：把组合根持有的三组端口写入域内注册表（见 impl/service）。组合根在
+ * `src/index.ts` 顶层调用，模块求值期即完成——三条 Port 全是静态模块引用，不需要宿主 ctx。
+ * 宿主能力（工具注册表读口 / 日志出口 / 落盘路径）都不在端口内：它们是本域声明的**入参契约**，
+ * 由 connection 在调用点构造递入（同 CatalogViewHost 的口径，见 deps.ts 头注释）。
+ *
+ * 为什么不是 `export async function`：注入面对账（verify-dir-imports 的
+ * analyzeInjectionFaces）按 `export function installXxx(` 采点，`async` 前缀会让这条对账
+ * 静默失明（附录 G·G12）。本域装配是纯同步写标记，签名保持同步形态即可。
+ */
+export declare function installCatalog(deps: CatalogDeps): void;
+/** 卸载目录域。只复位装配标记：本域读的是外部递进来的能力，没有活资源要释放。 */
+export declare function releaseCatalog(): void;
+export { DEFAULT_ANNOUNCE_CATALOG, DEFAULT_CATALOG_MAX_ENTRIES, CATALOG_SUMMARY_MAX_CHARS, CATALOG_SUMMARY_PER_TOOL_CHARS, CATALOG_ENTRY_MAX_CHARS, summarizeToolDescriptions, composeCatalogEntries, renderMcpCatalogMessage, renderMcpCatalogUpdate, escapeCatalogText, findCatalogMessage, readCatalogEntries, isCatalogSource, resolveCatalogEntries, CATALOG_SOURCE_PLUGIN, CATALOG_SOURCE_KIND, CATALOG_SECTION_NAME, } from "./impl/entries/index.js";
+export type { CatalogEntry, SupervisorLite, CatalogCache, CatalogSourceLike, } from "./impl/entries/index.js";
+export { digestCatalogEntries } from "./impl/digest/index.js";
+export { catalogHistory } from "./impl/history/index.js";
+export type { CatalogHistoryResult, CatalogAgent } from "./impl/history/index.js";
+export { resolveCatalogInjection } from "./impl/injection/index.js";
+export type { CatalogMessage, CatalogDecision } from "./impl/injection/index.js";
+export { makeCatalogViewFor, catalogCacheFile } from "./impl/cache-view/index.js";
+export type { CatalogViewHost, CatalogViewResolver } from "./impl/cache-view/index.js";
+export { scoreTool, searchCatalog, searchCatalogMulti, listCatalog, findToolDetail, isCatalogFresh, boundCatalogTools, } from "./search.js";
+export { catalogDirectory } from "./impl/directory/index.js";
+export type { SchemaView, RegisteredProjectionInput } from "./impl/directory/index.js";
+export type { CatalogServer, CatalogTool } from "./impl/entries/type.js";
+export type { SearchHit, ListToolEntry, ListServerEntry, ToolDetail, ListCatalogResult, } from "./impl/search/type.js";

package/lib/server/catalog/search.d.ts

@@ -0,0 +1,108 @@
+/**
+ * dsh-mcp-manager — catalog/search.ts：能力目录检索函数族（#664 阶段 5）。
+ *
+ * 自 src/middleware-utils.ts 迁出（catalog 域检索族）：打分/单/多单元检索/
+ * 完整盘点/单工具详情/新鲜判定/装箱。工具级禁用裁决（isToolDenied 等）与
+ * globMatch 归 pipeline（authorize 块）。B10 截断事实
+ * 口径随迁保持「恰好命中 limit 不误报」。
+ */
+import type { CatalogServer, CatalogTool, ListCatalogResult, ListServerEntry, SearchHit, ToolDetail } from "./interface.js";
+import type { ProjectUnit } from "../connection/interface.js";
+import type { DisabledToolsMap } from "../store/interface.js";
+/** 跨字段打分：query 词命中 server 名 / 工具名 / description / 参数名。
+ * 中文（无空格分词）：query 连续中文串在原始描述中 substring 匹配即可命中
+ * （修复：原实现把连续中文当单个 token，中文召回率接近零）。 */
+export declare function scoreTool(query: string, server: string, toolName: string, tool: CatalogTool): {
+    score: number;
+    matchedTerms: string[];
+};
+/** 连续中文段命中原始文本即计 2 分（≥2 字才算命中）；一个都没命中返回 undefined
+ * ——让调用方回落分词打分（中文 query 同时含英文词时两路都试）。 */
+export declare function scoreCjkSegments(segments: string[], haystack: string): {
+    score: number;
+    matchedTerms: string[];
+} | undefined;
+/** 词元命中原始文本即计 1 分（≥2 字才算命中，单字词元不计）。 */
+export declare function scoreTerms(terms: string[], haystack: string): {
+    score: number;
+    matchedTerms: string[];
+};
+/** 检索目录：query 为空 → 能力摘要表（每服务器前 N 个工具）。
+ * 单 root 实现（searchCatalogMulti 循环调用；兼容既有测试）。
+ * truncated：任一服务器存在被 limit 裁掉的结果即 true（B10 截断事实，
+ * 供调用方精确标注「是否因 limit 裁掉」——恰好命中 limit 不误报）。 */
+export declare function searchCatalog(units: Map<string, ProjectUnit>, root: string, query: string, limit: number): {
+    results: SearchHit[];
+    unavailable: Array<{
+        server: string;
+        reason: string;
+    }>;
+    truncated: boolean;
+};
+/** 多单元合并检索（项目 root 单元 + @global 单元合并查询）。
+ * 与 searchCatalog 同语义，仅数据源扩展为多个 root。
+ * 单 root 直接委托 searchCatalog（保持原顺序，不引入跨单元排序变化）；
+ * 多 root 合并后统一排序并按全局 limit 截断（truncated=合并后曾有超限结果）。 */
+export declare function searchCatalogMulti(units: Map<string, ProjectUnit>, roots: readonly string[], query: string, limit: number): {
+    results: SearchHit[];
+    unavailable: Array<{
+        server: string;
+        reason: string;
+    }>;
+    truncated: boolean;
+};
+/** 工具级禁用标注判定（本 root 段 + @global 段并集命中即禁用；@global 自身不重复继承）。 */
+export declare function isToolDisabledForEntry(disabledTools: DisabledToolsMap | undefined, root: string, serverName: string, toolName: string): boolean;
+/**
+ * 完整盘点：列出当前工作空间全部服务器 + 每台完整工具清单（不受关键词/limit
+ * 截断服务器，工具数受 perServerLimit 保护）。
+ * @param units 连接池单元集合。
+ * @param roots 参与盘点的 root 列表（当前项目 root + @global）。
+ * @param serverFilter 可选：@<root>/<server> 全名或裸名过滤。
+ * @param toolLimit 每服务器工具条数上限（>0；超过置 toolsTruncated）。
+ * @param emptyHint 空返回时的 message。
+ * @param disabledTools 用户工具级禁用映射（root → server → Set<tool>）；
+ *    命中条目在工具行标注禁用（供模型感知）。
+ * @throws 全名 root 不属于当前 roots → 路由一致性错误（与 ws_mcp_call 口径一致）。
+ */
+export declare function listCatalog(units: Map<string, ProjectUnit>, roots: readonly string[], serverFilter: string | undefined, toolLimit: number, emptyHint: string, disabledTools?: DisabledToolsMap): ListCatalogResult;
+/** 每服务器工具条数上限：非有限数或非正回落缺省；正数向下取整（历史口径）。 */
+export declare function safeToolLimit(toolLimit: number): number;
+/** 该 root 是否参与盘点：显式过滤集命中即参与，无过滤集则全参与。 */
+export declare function rootParticipates(root: string, rootSet: Set<string> | undefined): boolean;
+/** 盘点过滤：serverFilter 为空即全收；给定后裸名或 @全名任一命中即收。 */
+export declare function matchesServerFilter(serverName: string, root: string, serverFilter: string | undefined, fullServerName: (root: string, server: string) => string): boolean;
+/** 单台服务器的盘点条目：用户禁用标注 + 目录失败原因，或工具清单（含截断与工具数结算）。 */
+export declare function buildListServerEntry(serverName: string, root: string, catalog: CatalogServer, userDisabled: ReadonlySet<string>, safeLimit: number, disabledTools: DisabledToolsMap | undefined, fullServerName: (root: string, server: string) => string): {
+    entry: ListServerEntry;
+    truncated: boolean;
+    toolCount: number;
+};
+/** 盘点定序比较器：root 出现序优先（不在列表里的排后），同 root 内按裸名升序。 */
+export declare function listOrderComparator(rootIndex: ReadonlyMap<string, number>, parseFullServerName: (full: string) => {
+    root: string;
+    server: string;
+} | undefined): (a: ListServerEntry, b: ListServerEntry) => number;
+/** 条目排序键两格：root 出现序（不在 roots 列表里的排到末尾）+ root 内裸名。 */
+export declare function listOrderKey(entry: ListServerEntry, rootIndex: ReadonlyMap<string, number>, parseFullServerName: (full: string) => {
+    root: string;
+    server: string;
+} | undefined): {
+    rootOrder: number;
+    server: string;
+};
+/**
+ * 单工具详情：按 @<root>/<server> + tool 裸名精确命中，返回完整 inputSchema。
+ * 错误三分：
+ * 1. server 发现失败（catalog.unavailable）→ 附原因；
+ * 2. 单元/服务器未发现 → 「server 未连接或未发现」；
+ * 3. 工具不存在 → 「tool 不存在」。
+ * @param units 连接池单元集合。
+ * @param root 目标 root（可为 @global）。
+ * @param server @<root>/<server> 全名。
+ * @param tool 远端工具裸名（兼容 mcp__ 前缀，复用 normalizeToolName）。
+ */
+export declare function findToolDetail(units: Map<string, ProjectUnit>, root: string, server: string, tool: string): ToolDetail;
+/** 目录里没有可用工具时的错误三分：发现失败（附原因）> 用户禁用（附说明）> 未连接。 */
+export declare function toolDetailMissError(catalog: CatalogServer | undefined, server: string, userDisabled: boolean): Error;
+export { boundCatalogTools, isCatalogFresh } from "./impl/directory/index.js";

package/lib/server/config/config-schema.d.ts

@@ -0,0 +1,85 @@
+/**
+ * dsh-mcp-manager — 插件 Config schema 与配置归一化（纯函数，单一事实源）。
+ *
+ * 插件自身 Config（cordis 配置注入入口）与浮窗 UI 配置的校验/归一化/默认值；
+ * 类型自 types.ts 取（防循环引用），placement-math 提供层级 clamp 与默认层级。
+ */
+import z from "schemastery";
+import type { ClientUiConfig } from "../../shared/interface.js";
+import type { UiPlacementConfig } from "./impl/ui/type.js";
+/** 默认浮窗 UI 配置（与升级前一致，无回归；层级基准引用 placement-math 单一事实源，
+ *  DEFAULT_Z_INDEX_BASE=10 对应 CSS 默认 z-index:10）。 */
+export declare const DEFAULT_UI_CONFIG: UiPlacementConfig;
+/**
+ * 归一化浮窗 UI 配置（纯函数，可单测）。
+ * 兼容三种形态：新 `Config.ui` 嵌套、旧隐藏命名空间的扁平 `position/offset`、
+ * 客户端扁平 `position/offsetX/offsetY/blankY`。非法或缺失 → 安全回退默认，不抛。
+ */
+export declare function normalizeUiConfig(raw: unknown): ClientUiConfig;
+/**
+ * 把客户端扁平形态（{position, offsetX, offsetY, blankY}）归一化为写入 `Config.ui`
+ * 的嵌套补丁（{position, offset:{x,y,blankY}}）。走 normalizeUiConfig 的净化为唯一
+ * 入口：非法值安全回退默认，负数 clamp 到 0，四舍五入。
+ */
+export declare function buildConfigUiPatch(raw: unknown): UiPlacementConfig;
+/** 面板垂直定位纯函数（供 smoke 断言翻转分支；clamp 到视口内，不溢出）。
+ *  实现自持于包内 src/shared/placement-math.ts（shared-leaf 叶子约束），此处
+ *  re-export 保持 index.ts 导出链不变。 */
+export { panelTopForAnchor } from "../../shared/interface.js";
+/**
+ * 插件 Config schema（标准 cordis 配置注入入口；含 `ui` 子对象）。
+ * 官方 ConfigForm 只开放 ui child；根级运行时字段全部 disabled。
+ */
+export declare const Config: z<{
+    enabled: boolean;
+    announceToAgent: boolean;
+    storePath: string;
+    announceCatalog: boolean;
+    catalogMaxEntries: number;
+    debug: {
+        callStats: boolean;
+        statsFile: string;
+    };
+    ui: UiPlacementConfig;
+}>;
+/**
+ * 默认配置（键集 = schema 中带 .default() 的字段）。从 schema 归一化**空输入**派生，
+ * 不手写第二份默认值——默认值只写在上面的 .default(...) 里，改一处即改两处。
+ * storePath 无默认值，故键集比 schema 字段数少 1（config-matrix 门禁的 N1/N2 锁这条不变式）。
+ */
+export declare const DEFAULT_CONFIG: {
+    enabled: boolean;
+    announceToAgent: boolean;
+    storePath: string;
+    announceCatalog: boolean;
+    catalogMaxEntries: number;
+    debug: {
+        callStats: boolean;
+        statsFile: string;
+    };
+    ui: UiPlacementConfig;
+};
+/**
+ * 归一化：把外部输入按 schema 校验并补默认值。
+ * 与 normalizeUiConfig 分工不同：后者只处理 ui 子面（设置页提交的局部 patch），
+ * 本函数给出一份**完整**配置。
+ */
+export declare function normalizeConfig(input: unknown): {
+    enabled: boolean;
+    announceToAgent: boolean;
+    storePath: string;
+    announceCatalog: boolean;
+    catalogMaxEntries: number;
+    debug: {
+        callStats: boolean;
+        statsFile: string;
+    };
+    ui: UiPlacementConfig;
+};
+/** 只接受布尔值的**顶层**配置键（客户端 UI 按它渲染开关）；嵌套的 debug.callStats 不是顶层键。 */
+export declare const BOOLEAN_KEYS: readonly string[];
+/**
+ * 非负整数键及其上界：本包**没有产品上界**——catalogMaxEntries 只被要求是正整数，
+ * 上界是机器/内存极限而非产品约束，编一个上界等于造假事实。空对象是显式声明而不是遗漏。
+ */
+export declare const COUNT_LIMITS: Record<string, number>;

package/lib/server/config/impl/env/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * dsh-mcp-manager — server/config/impl/env/index.ts：配置模板预展开与凭据词根（#767 S1-1）。
+ *
+ * ${ENV} 模板必须在配置交给连接层之前展开：官方 dsh-mcp-client 的 env / headers 只接受
+ * 字面量，而落盘配置又必须保持模板形态（展开结果含明文凭据，写盘即泄漏）。展开点归本域，
+ * 是因为「哪些字段含模板」是配置面知识；连接域不再持有第二份定义。
+ *
+ * 凭据词根（SECRET_ENV_NAME）随本块一并迁入：它是 stdio 子进程环境过滤的判据，与
+ * ${ENV} 展开同属「配置值出入子进程」这一件事。
+ */
+import type { ServerConfig } from "../model/type.js";
+/** 凭据形状的环境变量名（父进程环境不自动透传给 MCP 子进程）。 */
+export declare const SECRET_ENV_NAME: RegExp;
+/** 展开字符串中的 ${ENV_NAME} 引用（未设置 → 空字符串），用于 header/env 值。 */
+export declare function expandEnv(value: unknown): string;
+/** 递归展开对象值中的 ${ENV_NAME} 引用。 */
+export declare function expandEnvObject(input: Record<string, unknown> | undefined): Record<string, string>;
+/**
+ * 展开一条服务器配置的 env 与 headers 模板，其余字段原样带上。
+ *
+ * 恒返回新对象：调用方拿着落盘配置就地改写，会让展开后的明文凭据随下一次 store.save()
+ * 落进配置文件——模板落盘、连接时才展开是本插件的凭据面不变量。
+ */
+export declare function expandServerEnv(server: ServerConfig): ServerConfig;

package/lib/server/config/impl/env/policy.d.ts

@@ -0,0 +1,54 @@
+/**
+ * dsh-mcp-manager — server/config/impl/env/policy.ts：环境变量凭据策略门（#770-2 环境净化，B 相）。
+ *
+ * 两阶段校验中的第二阶段（第一阶段是 normalizeServer 的纯形状校验，不读环境）：
+ * add / update / import 三个写边界在落盘前调用 assertEnvPolicy，对 env / headers /
+ * url / args 做「目标键 + 值 provenance」双审——用户裁决：边界拒绝 + 豁免表，拒绝静默过滤。
+ *
+ * 为什么不在 normalizeServer 里做：normalize 是纯函数，而本门要读父进程环境快照做展开后
+ * 审计（${VAR} 的值 provenance 只有读到快照才知道）；纯函数里读环境会让归一结果随调用
+ * 时机漂移。形状问题归 normalize，环境策略问题归本门，两门职责不混。
+ *
+ * 双审口径（fail-closed，命中即抛错，绝不静默丢弃/置空）：
+ * 1. 目标键审：键名按词精确匹配凭据词表（isSecretEnvName）。子串正则 SECRET_ENV_NAME 只作
+ *    候选快筛，确证必须走词表——MONKEY / TURKEY_SIZE / KEYBOARD 这类含 KEY 子串的正当名
+ *    在词级无命中，必须放行（误伤回归测试锁死）。
+ * 2. 值 provenance 审：值里的 ${VAR} 引用若指向凭据形名（非豁免），而目标键本身非凭据形
+ *    （如 DEBUG: "${MY_SECRET}"），即秘密被塞进非秘密槽位——子进程会把它当普通数据，
+ *    且按名识别的脱敏/投影都认不出它，拦截。引用名是否已 set 不影响判定（unset 时展开
+ *    为空串正是「零值消费」陷阱：换个环境就变泄漏，fail-closed 按名拦截）。
+ * 3. 活秘密查重：展开后的非空值若与某个凭据形父环境变量的活值逐字相等（如 MY_TOKEN 的
+ *    明文字面量与快照里 MY_TOKEN 相同），即把活秘密以明文 baked 进配置文件——轮转即漂移，
+ *    且与「模板落盘、连接时展开」的不变量相悖，拦截并指引改用同名模板。
+ *    豁免：凭据槽位经凭据引用取值（CONTEXT7_API_KEY: "${CONTEXT7_API_KEY}"、
+ *    Authorization: "Bearer ${CONTEXT7_API_KEY}"）是文档示例的合法形态，展开值等于活
+ *    秘密是预期结果，不在此列；空值（""，客户端语义=继承父环境）不注册不比对。
+ *
+ * 报错文案只含键名/变量名与模板，不含任何字面量值：写边界的错误经路由统一错误边界
+ * （handleError → redactError）原样进 400 body，而被拒配置尚未落盘、其展开值不在脱敏
+ * 快照内——回显字面量即泄漏。模板形态（"${MY_SECRET}"）无秘密可泄，可以出现。
+ */
+/** ${VAR} 引用抽取：字面量必须与 expandEnv 的替换口径逐字一致（门与展开同口径）。 */
+export declare function extractEnvRefs(value: unknown): string[];
+/**
+ * 名是否为凭据形（精确判定）：豁免表优先 → 子串正则只作候选快筛 → 切词精确确证。
+ *
+ * 切词规则：大写后按非字母数字切分（下划线/连横线/点/空格都是词界），每词去尾数后查表。
+ * 去尾数（TOKEN2 → TOKEN）收的是「带编号的凭据」常见写法；TURKEY2 → TURKEY 照样不命中，
+ * 不引入新误伤。MONKEY / TURKEY_SIZE / KEYBOARD / AUTHOR_NAME 在此全灭（子串命中但无整词）。
+ */
+export declare function isSecretEnvName(name: unknown): boolean;
+/**
+ * 写边界凭据策略门（add / update / import 同门；normalize 保持纯形状校验不调本函数；
+ * registerServer 内存态不调本函数，见 manager.registerServer 注释）。
+ *
+ * @param env 归一化后的 env 表（add/update 传 normalize 产物；import 经 parseClaudeJson →
+ *   manager.add/update 间接同门，不直调）。
+ * @param headers 归一化后的 headers 表。
+ * @param snapshot 父环境快照（缺省 process.env；单测注入隔离快照，离线可跑）。
+ * @param url 归一化后的 url（只审 userinfo/查询值中的活秘密值 + 引用污染；缺省跳过）。
+ * @param args 归一化后的 args（只审秘密 flag 值等于活秘密值 + 引用污染；缺省跳过）。
+ * @throws 命中即抛错（fail-closed）：文案含哪个键/槽位、为什么被拒、怎么改；不含字面量值
+ *   （400 body 经 redactError 原样返回，被拒配置不在脱敏快照内，回显即泄漏）。
+ */
+export declare function assertEnvPolicy(env: Record<string, unknown> | undefined, headers: Record<string, unknown> | undefined, snapshot?: Record<string, string | undefined>, url?: unknown, args?: unknown): void;