hiwork-core 0.0.10 → 0.0.11

package/lib/managed-mcp.js

@@ -0,0 +1,334 @@
+/**
+ * `/hiwork-managed-mcp` loopback RPC 的 Host 实现：管理员下发的 MCP 清单 + 换令牌用的短期断言。
+ *
+ * 设计要点（与 `src/usage-rpc.ts` / `src/daily-rpc.ts` 同构，差异都在下面写清）：
+ *  - 只注册一个 channel，endpoint 白名单在 {@link MANAGED_MCP_RPC_ENDPOINTS}，未知
+ *    endpoint 直接 `bad-request`；
+ *  - payload 严格校验：`snapshot` / `refresh` 只接受空对象，`assertion` 只接受
+ *    `{ assignmentId }`（这是唯一一处客户端可控输入，形状卡死在 Host）；
+ *  - **网关会话 cookie 绝不离开 Host**：调用方拿到的是清单与断言，cookie 只在
+ *    `resolveSession()` 内部出现；
+ *  - **本频道不换令牌、不持有令牌**。断言只是一张 120 秒的门票，拿它去 MCP 服务的
+ *    `/mcp-credential-exchange` 换 per-user 令牌是客户端（hiwork-capabilities）的事。
+ *    这样 ai-hub 与 hiwork-core 全程经手不了任何 MCP 凭据，被攻破也拿不到东西。
+ *  - **拉清单失败绝不清空上一次成功的清单**：客户端只有在拿到一份「成功拉到的清单」
+ *    时才允许删除本地受管连接，所以失败必须以「保留旧值 + 标注失败原因」的形状返回，
+ *    否则一次网络抖动就会让员工端把自己卸载干净。
+ *
+ * 本模块不 import cordis 运行时，只依赖结构化的 {@link ManagedMcpRpcContext} 端口，
+ * 便于单测直接伪造。
+ */
+import { GatewayError, } from "./ai-router-client.js";
+/** RPC 频道；必须与 client 半边 `src/client/managed-mcp.ts` 的 `MANAGED_MCP_CHANNEL` 一致（由测试锁定）。 */
+export const MANAGED_MCP_RPC_CHANNEL = '/hiwork-managed-mcp';
+/**
+ * 端点白名单。
+ *
+ * `snapshot` 是「你现在有什么」（有缓存就直接给，冷启动才拉一次），`refresh` 是
+ * 「现在去拉一次」。分两个端点的理由：客户端的同步策略（启动 / 30 分钟 / 打开连接器页
+ * 且 >5min stale）由它自己定，Host 不该替它决定什么时候必须联网。
+ */
+export const MANAGED_MCP_RPC_ENDPOINTS = ['snapshot', 'refresh', 'assertion'];
+/**
+ * Host 侧后台预热间隔：30 分钟（与客户端同步节奏同量级）。
+ * 它**不是**权威节奏——只为让客户端首次 `snapshot` 不必等一次网络往返。
+ */
+export const MANAGED_MCP_REFRESH_INTERVAL_MS = 30 * 60_000;
+/** 请求侧错误（只有 `bad-request`：未知端点 / 非法 payload）。 */
+export class ManagedMcpRequestError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ManagedMcpRequestError';
+    }
+}
+/** 各稳定错误码的用户可见文案（网关 message 含实现细节时用它兜底）。 */
+const MANAGED_MCP_MESSAGE_FALLBACK = {
+    SESSION_EXPIRED: '登录状态已过期，请重新登录',
+    GATEWAY_UNREACHABLE: '网关暂时不可用，请稍后重试',
+    MCP_ASSIGNMENT_GONE: '这条分配已失效，稍后同步会重新核对',
+    MCP_NOT_DELIVERABLE: '该 MCP 服务当前不可下发，请联系管理员',
+    MCP_ASSERTION_DISABLED: '本部署未启用 MCP 断言签发，请联系管理员',
+    NO_KEY_ASSIGNED: '当前账号尚未被分配虚拟 KEY，请联系管理员',
+};
+/** 通用失败文案：不暴露任何网关细节。 */
+export const MANAGED_MCP_GENERIC_FAILURE_MESSAGE = 'MCP 清单暂时无法获取，请稍后重试';
+/** 未登录 / 会话失效的统一文案（与用量、每日一句两个频道同口径）。 */
+export const MANAGED_MCP_SESSION_EXPIRED_MESSAGE = '登录状态已过期，请重新登录';
+/**
+ * 网关 message 消毒（与 `usage-rpc.ts` 的 `displayGatewayMessage` 同实现）：
+ * 含 baseURL / HTTP 状态码 / URL 的原始消息一律换成稳定文案，其余（网关自己写好的
+ * 中文业务文案）原样保留。code 不受影响，始终原样透传。
+ */
+export function displayManagedMcpMessage(code, message) {
+    const text = typeof message === 'string' ? message.trim() : '';
+    if (text === '')
+        return MANAGED_MCP_MESSAGE_FALLBACK[code] ?? MANAGED_MCP_GENERIC_FAILURE_MESSAGE;
+    const leaksImplementationDetail = /https?:\/\//i.test(text)
+        || /\bHTTP\s*\d{3}\b/i.test(text)
+        || /\bbaseURL\b/i.test(text);
+    if (leaksImplementationDetail)
+        return MANAGED_MCP_MESSAGE_FALLBACK[code] ?? MANAGED_MCP_GENERIC_FAILURE_MESSAGE;
+    return text;
+}
+/**
+ * `assertion` 的 assignmentId 形状：只放行 uuid 用的字符集与长度（1–64）。
+ * 这是全频道唯一一处客户端可控输入，卡在 Host 比卡在网关早——一个带空格 / 换行 /
+ * 百分号的串没有任何合法来源，直接 `bad-request`。
+ */
+const ASSIGNMENT_ID_PATTERN = /^[0-9a-fA-F-]{1,64}$/;
+/**
+ * payload 校验：`snapshot` / `refresh` 只放行空对象，`assertion` 只放行
+ * `{ assignmentId }`；其余字段 / 类型不符一律 `bad-request`。
+ */
+export function parseManagedMcpPayload(endpoint, raw) {
+    if (raw === undefined || raw === null) {
+        if (endpoint === 'assertion')
+            throw new ManagedMcpRequestError('bad-request', '取断言请求缺少 assignmentId。');
+        return {};
+    }
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ManagedMcpRequestError('bad-request', 'MCP 清单请求参数不合法。');
+    }
+    const record = raw;
+    const keys = Object.keys(record);
+    if (endpoint !== 'assertion') {
+        // snapshot / refresh 无任何入参：出现任何字段都是客户端实现缺陷。
+        if (keys.length > 0)
+            throw new ManagedMcpRequestError('bad-request', `MCP 清单请求包含未知字段 '${keys[0]}'。`);
+        return {};
+    }
+    for (const key of keys) {
+        if (key !== 'assignmentId')
+            throw new ManagedMcpRequestError('bad-request', `取断言请求包含未知字段 '${key}'。`);
+    }
+    const rawId = record['assignmentId'];
+    if (typeof rawId !== 'string' || !ASSIGNMENT_ID_PATTERN.test(rawId.trim())) {
+        throw new ManagedMcpRequestError('bad-request', '取断言请求的 assignmentId 不合法。');
+    }
+    return { assignmentId: rawId.trim() };
+}
+/** 是否为白名单端点。 */
+export function isManagedMcpRpcEndpoint(endpoint) {
+    return MANAGED_MCP_RPC_ENDPOINTS.includes(endpoint);
+}
+/** 非空字符串或 undefined（清单里一个字段坏了不该让整条清单失败）。 */
+function textOrUndefined(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+/**
+ * 把网关响应里的一条分配规范化成 {@link ManagedMcpAssignment}。
+ *
+ * **结构不完整就整条丢弃**（缺 id / serverName / url / auth.mintUrl 的条目装不了，
+ * 留着只会在下游变成一次诡异的失败），丢弃时记一条日志——服务端数据问题的证据在
+ * Host 侧，客户端看不到网关响应。
+ *
+ * **但 `transport` 与 `auth.kind` 不做白名单过滤**：认不认识的判断属于连接器域
+ * （hiwork-capabilities 知道自己能装什么），它要按「不认识的 kind 跳过并报冲突」的
+ * 契约把问题报到界面上；Host 在这里悄悄丢掉，冲突就永远不会被人看见。
+ */
+function normalizeAssignment(raw, log) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const record = raw;
+    const assignmentId = textOrUndefined(record['assignmentId']);
+    const serverName = textOrUndefined(record['serverName']);
+    const url = textOrUndefined(record['url']);
+    const transport = textOrUndefined(record['transport']);
+    const authRaw = record['auth'];
+    const auth = typeof authRaw === 'object' && authRaw !== null && !Array.isArray(authRaw)
+        ? authRaw
+        : undefined;
+    const kind = textOrUndefined(auth?.['kind']);
+    const mintUrl = textOrUndefined(auth?.['mintUrl']);
+    if (assignmentId === undefined || serverName === undefined || url === undefined
+        || transport === undefined || kind === undefined || mintUrl === undefined) {
+        log?.('hiwork-core: MCP 清单里有一条结构不完整的分配，已跳过');
+        return undefined;
+    }
+    const revision = record['revision'];
+    return {
+        assignmentId,
+        revision: typeof revision === 'number' && Number.isFinite(revision) ? revision : 0,
+        slug: textOrUndefined(record['slug']) ?? serverName,
+        displayName: textOrUndefined(record['displayName']) ?? serverName,
+        serverName,
+        transport,
+        url,
+        extraHeaders: stringMap(record['extraHeaders']),
+        auth: { kind, mintUrl, revokeUrl: textOrUndefined(auth?.['revokeUrl']) ?? '' },
+        updatedAt: textOrUndefined(record['updatedAt']) ?? '',
+    };
+}
+/** 头映射：只保留值为字符串的键（其余静默丢弃，头值只能是字符串）。 */
+function stringMap(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value === 'string')
+            out[key] = value;
+    }
+    return out;
+}
+/** 任意异常 → 可展示的失败（网关 code 透传，message 消毒；其余收敛为通用失败）。 */
+function failureOf(error) {
+    if (error instanceof ManagedMcpRequestError)
+        return { code: error.code, message: error.message, details: {} };
+    if (error instanceof GatewayError) {
+        return { code: error.code, message: displayManagedMcpMessage(error.code, error.message), details: {} };
+    }
+    return { code: 'internal', message: MANAGED_MCP_GENERIC_FAILURE_MESSAGE, details: {} };
+}
+/**
+ * 清单缓存：**只有成功响应才覆写**，失败只记原因。
+ *
+ * 进程内的（不落盘）是有意的：清单是「服务端此刻认什么」的投影，跨重启的旧清单
+ * 没有任何价值——重启后客户端会立刻同步一次，拿到新的比拿到旧的更安全。
+ */
+export class ManagedMcpStore {
+    deps;
+    now;
+    cached;
+    lastError;
+    inFlight;
+    constructor(deps, now = () => Date.now()) {
+        this.deps = deps;
+        this.now = now;
+    }
+    /**
+     * 当前缓存（同步读，不发请求）。从没成功过返回 undefined；
+     * 最近一次失败会以 `stale + lastError` 标注在上一次成功的结果上。
+     */
+    peek() {
+        if (this.cached === undefined)
+            return undefined;
+        return this.lastError === undefined
+            ? this.cached
+            : { ...this.cached, stale: true, lastError: this.lastError };
+    }
+    /**
+     * 去网关拉一次清单并更新缓存。失败时抛异常，且**缓存原样保留**。
+     *
+     * 并发调用合并成一次请求：后台预热与客户端手动同步撞在一起时不必打两遍网关。
+     */
+    async load() {
+        if (this.inFlight !== undefined)
+            return await this.inFlight;
+        const task = this.fetchOnce();
+        this.inFlight = task;
+        try {
+            return await task;
+        }
+        finally {
+            this.inFlight = undefined;
+        }
+    }
+    async fetchOnce() {
+        try {
+            const sessionCookie = await this.deps.resolveSession();
+            if (sessionCookie === undefined || sessionCookie === '') {
+                throw new GatewayError('SESSION_EXPIRED', MANAGED_MCP_SESSION_EXPIRED_MESSAGE);
+            }
+            const gateway = this.deps.gateway();
+            if (gateway === undefined) {
+                throw new GatewayError('GATEWAY_UNREACHABLE', '网关地址未配置，请先在「网关模型」里完成登录');
+            }
+            const view = await gateway.getMyMcpAssignments(sessionCookie);
+            const assignments = [];
+            for (const item of Array.isArray(view?.assignments) ? view.assignments : []) {
+                const normalized = normalizeAssignment(item, this.deps.log);
+                if (normalized !== undefined)
+                    assignments.push(normalized);
+            }
+            const snapshot = {
+                revision: typeof view?.revision === 'number' && Number.isFinite(view.revision) ? view.revision : 0,
+                fetchedAt: new Date(this.now()).toISOString(),
+                assignments,
+                stale: false,
+            };
+            this.cached = snapshot;
+            this.lastError = undefined;
+            return snapshot;
+        }
+        catch (error) {
+            this.lastError = failureOf(error);
+            throw error;
+        }
+    }
+}
+/** 取消判定（用函数包一层，避免 TS 把属性窄化固化到 `await` 之后）。 */
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+/**
+ * 处理一次端点调用：返回 DSH Connection 的结果信封，**永不抛异常**。
+ * 导出以便单测直接驱动（无需伪造 `ctx.connection`）。
+ */
+export async function handleManagedMcpEndpoint(endpoint, rawPayload, deps, store, signal) {
+    try {
+        if (isAborted(signal))
+            return failure('cancelled', 'MCP 清单请求已取消。');
+        if (!isManagedMcpRpcEndpoint(endpoint)) {
+            throw new ManagedMcpRequestError('bad-request', `未知的 MCP 清单端点 '${endpoint}'`);
+        }
+        const payload = parseManagedMcpPayload(endpoint, rawPayload);
+        if (endpoint === 'assertion') {
+            const assignmentId = payload.assignmentId;
+            if (assignmentId === undefined)
+                throw new ManagedMcpRequestError('bad-request', '取断言请求缺少 assignmentId。');
+            return await handleAssertion(assignmentId, deps, signal);
+        }
+        // snapshot：有缓存就直接给（可能是 stale），冷启动才走一次网络。
+        const cached = store.peek();
+        if (endpoint === 'snapshot' && cached !== undefined)
+            return { ok: true, value: cached };
+        return { ok: true, value: await store.load() };
+    }
+    catch (error) {
+        deps.log?.(`hiwork-core: MCP 清单 RPC '${endpoint}' 失败（${error instanceof Error ? error.name : typeof error}）`);
+        return { ok: false, error: failureOf(error) };
+    }
+}
+/** `assertion`：每次都要新的（120 秒的门票，缓存下来的那一张只会是废纸）。 */
+async function handleAssertion(assignmentId, deps, signal) {
+    const sessionCookie = await deps.resolveSession();
+    if (sessionCookie === undefined || sessionCookie === '') {
+        return failure('SESSION_EXPIRED', MANAGED_MCP_SESSION_EXPIRED_MESSAGE);
+    }
+    const gateway = deps.gateway();
+    if (gateway === undefined) {
+        return failure('GATEWAY_UNREACHABLE', '网关地址未配置，请先在「网关模型」里完成登录');
+    }
+    if (isAborted(signal))
+        return failure('cancelled', 'MCP 清单请求已取消。');
+    const ticket = await gateway.issueMyMcpAssertion(sessionCookie, assignmentId);
+    const assertion = textOrUndefined(ticket?.assertion);
+    const mintUrl = textOrUndefined(ticket?.mintUrl);
+    if (assertion === undefined || mintUrl === undefined) {
+        deps.log?.('hiwork-core: 取断言收到无效响应（缺 assertion / mintUrl）');
+        return failure('internal', MANAGED_MCP_GENERIC_FAILURE_MESSAGE);
+    }
+    return {
+        ok: true,
+        value: {
+            assertion,
+            mintUrl,
+            revokeUrl: textOrUndefined(ticket?.revokeUrl) ?? '',
+            expiresAt: textOrUndefined(ticket?.expiresAt) ?? '',
+            serverName: textOrUndefined(ticket?.serverName) ?? '',
+        },
+    };
+}
+function failure(code, message) {
+    return { ok: false, error: { code, message, details: {} } };
+}
+/**
+ * 注册 `/hiwork-managed-mcp` 频道，返回异步 disposer（交给 `ctx.effect` 管理生命周期）。
+ */
+export function registerManagedMcpRpc(ctx, deps, store) {
+    const handler = (endpoint, payload, signal) => handleManagedMcpEndpoint(endpoint, payload, deps, store, signal);
+    const remove = ctx.connection.rpc.handle(MANAGED_MCP_RPC_CHANNEL, handler, { authority: 'loopback' });
+    return async () => { await remove(); };
+}

package/lib/types/ai-router-client.d.ts

@@ -209,6 +209,56 @@ export interface GatewayDailyQuoteResponse {
 export interface GatewayDailyQuoteRandomResponse {
     item: GatewayDailyQuoteItem | null;
 }
+/**
+ * 一条下发给当前账号的 MCP 分配（`GET /api/me/mcp-assignments` 的 `assignments[]`）。
+ *
+ * **字段名是跨仓冻结契约**（ai-hub spec §4.1）：四仓（visio-mcp / ai-hub / hiwork-core /
+ * hiwork-capabilities）唯一的接口面，改一个字段名要先改 spec 并同步四仓注释。
+ */
+export interface GatewayMcpAssignment {
+    /** 服务端分配 id：客户端按它派生连接 key（`admin-<assignmentId>`），因此必须稳定。 */
+    assignmentId: string;
+    /** 单条版本号：管理员每次推送 +1，客户端据此判「这条要不要重新落地」。 */
+    revision: number;
+    /** 服务的 slug（ai-hub 侧唯一名，也是断言的 audience）。 */
+    slug: string;
+    displayName: string;
+    /** 服务端权威下发的装载名（工具前缀 `mcp__<serverName>__` 跨版本稳定的锚点）。 */
+    serverName: string;
+    /** `streamable-http | stdio`（与 capabilities 的传输判别联合同源）。 */
+    transport: string;
+    url: string;
+    /** 非凭证的业务请求头；`{}` 表示没有。 */
+    extraHeaders: Record<string, string>;
+    auth: GatewayMcpAssignmentAuth;
+    updatedAt: string;
+}
+/** 取凭证的入口：去哪换（mintUrl）、去哪还（revokeUrl）。`kind` 目前只有 `assertion`。 */
+export interface GatewayMcpAssignmentAuth {
+    kind: string;
+    mintUrl: string;
+    revokeUrl: string;
+}
+/**
+ * GET /api/me/mcp-assignments 响应。
+ * `revision` 是清单级序号（任何会影响清单的写入都 +1），客户端先比它、不同再逐条深比。
+ */
+export interface GatewayMcpAssignmentsView {
+    revision: number;
+    assignments: GatewayMcpAssignment[];
+}
+/**
+ * POST /api/me/mcp-assertions 响应：一张 **120 秒**的身份断言（RS256 JWT）+
+ * 去哪换令牌。断言本身不是凭据（换不成令牌就是废纸），所以它可以出现在这里；
+ * 真正的 per-user 令牌由 MCP 服务在 exchange 时一次性返回，网关与核心都拿不到。
+ */
+export interface GatewayMcpAssertionTicket {
+    assertion: string;
+    mintUrl: string;
+    revokeUrl: string;
+    expiresAt: string;
+    serverName: string;
+}
 /** 网关客户端端口：orchestration 只依赖此接口。 */
 export interface GatewayClient {
     /**
@@ -248,6 +298,10 @@ export interface GatewayClient {
     getMyKeyRecharges(sessionCookie: string, keyId?: string, modelName?: string): Promise<GatewayRecharge[]>;
     /** 网关权威计价：只回金额与生效单价，客户端不做任何算式。 */
     estimateCost(sessionCookie: string, items: GatewayCostEstimateItem[]): Promise<GatewayCostEstimateResponse>;
+    /** 管理员下发给当前账号的 MCP 清单（响应里没有令牌）。 */
+    getMyMcpAssignments(sessionCookie: string): Promise<GatewayMcpAssignmentsView>;
+    /** 为某条分配签一张 120 秒的身份断言（拿它去 MCP 服务换 per-user 令牌）。 */
+    issueMyMcpAssertion(sessionCookie: string, assignmentId: string): Promise<GatewayMcpAssertionTicket>;
     logout(sessionCookie: string): Promise<void>;
 }
 /**
@@ -313,6 +367,22 @@ export declare class AiRouterClient implements GatewayClient {
      * `input_tokens` 不含 cache；任何折算与单价计算都在网关侧完成。
      */
     estimateCost(sessionCookie: string, items: GatewayCostEstimateItem[]): Promise<GatewayCostEstimateResponse>;
+    /**
+     * GET /api/me/mcp-assignments：管理员下发给当前账号的 MCP 清单。
+     *
+     * 不复用 {@link getMeJson}：那条路径把 403 映射成 `NO_KEY_ASSIGNED`（「尚未被分配
+     * 虚拟 KEY」），而本端点的鉴权只有会话——一个还没被分配 Key 的账号照样应该有
+     * 清单（分 MCP 与分 Key 是两件事）。沿用它的 403 文案会把「没有 Key」错报成原因。
+     */
+    getMyMcpAssignments(sessionCookie: string): Promise<GatewayMcpAssignmentsView>;
+    /**
+     * POST /api/me/mcp-assertions：为某条分配签一张 120 秒断言。
+     *
+     * 三种拒绝各有确定含义（服务端 handler 的 404/409/503），必须分开映射——否则
+     * 客户端只会看到一句「取断言失败」，既分不清「被撤销了」（该卸连接）还是
+     * 「服务停用了」（该重试）还是「部署没配私钥」（找管理员）。
+     */
+    issueMyMcpAssertion(sessionCookie: string, assignmentId: string): Promise<GatewayMcpAssertionTicket>;
     /**
      * /api/me 自助端点的 GET 公共路径：网络异常 → GATEWAY_UNREACHABLE，
      * 401/403/400 映射为稳定 code，响应体非 JSON 时不把原文带进异常。

package/lib/types/client/contracts.d.ts

@@ -21,6 +21,7 @@
  * 即可（见 `hiwork-automation` 的 `contracts.ts`），运行期只按服务名读取。
  */
 import type { FeatureRegistry } from './feature-registry.ts';
+import type { ManagedMcpAssertion, ManagedMcpSnapshot } from './managed-mcp.ts';
 /** cordis 服务名：`hiwork-core` 的 client 半边提供，业务插件按名注入。 */
 export declare const HIWORK_FEATURE_CENTER_SERVICE = "hiworkFeatureCenter";
 /**
@@ -38,4 +39,28 @@ export interface HiWorkCoreClientFace {
     readonly openNativeSession: (sessionId: string) => void;
     /** 回到原生「新会话」首页：先退出 takeover，再触发原生新会话动作。 */
     readonly openNativeHome: () => void;
+    /**
+     * 管理员下发的 MCP（连接器域消费，见 `src/client/managed-mcp.ts`）。
+     *
+     * **可选成员**：老版本 hiwork-core 没有这个面、新版本 hiwork-capabilities 遇到它
+     * 时只会看到 `undefined`（能力中心照常工作，只是没有受管连接）；反过来新 core 遇到
+     * 老 capabilities 也只是没人来取。两侧因此不必严格同发一个版本。
+     *
+     * 这一面**只交出清单与短期断言**：换 per-user 令牌是连接器域自己拿断言去 MCP 服务
+     * 做的，核心既不换也不存。
+     */
+    readonly managedMcp?: {
+        /** 本地镜像（同步读，可能是上一次成功的结果）。**不要拿它做删除决策**。 */
+        readonly snapshot: () => ManagedMcpSnapshot | undefined;
+        /** 本地镜像是否陈旧（或从未同步过）。 */
+        readonly isStale: (ttlMs?: number) => boolean;
+        /** 用 Host 的预热缓存拿一份清单（命中缓存时零网络请求）。 */
+        readonly warm: (signal?: AbortSignal) => Promise<ManagedMcpSnapshot>;
+        /** 强制拉一次，返回**刚拉到的**清单；失败抛错。只有它的返回值保证是当下的真相。 */
+        readonly refresh: (signal?: AbortSignal) => Promise<ManagedMcpSnapshot>;
+        /** 取一张 120 秒的身份断言 + 去哪换令牌。 */
+        readonly assertion: (assignmentId: string, signal?: AbortSignal) => Promise<ManagedMcpAssertion>;
+        /** 订阅镜像变化（登出 / 换账号时会被清空）。返回退订函数。 */
+        readonly subscribe: (listener: () => void) => () => void;
+    };
 }

package/lib/types/client/managed-mcp.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 「管理员下发的 MCP」客户端取数层：经 `/hiwork-managed-mcp` loopback RPC 拿到
+ * 清单与短期断言，交给连接器域（hiwork-capabilities）去换令牌并落地。
+ *
+ * 铁律：
+ *  - 客户端**不持有**会话 cookie，也**不直接 fetch 网关**——一切经 Host 频道；
+ *  - 客户端**不做 exchange、不持有 MCP 令牌**：本层交出去的只有「清单 + 一张刚取的
+ *    断言 + mintUrl」，per-user 令牌只在连接器域内部存在；
+ *  - **只有 {@link ManagedMcpStore.refresh} 成功返回的清单才允许用作删除本地受管连接的
+ *    依据**；{@link ManagedMcpStore.snapshot} 可能与界面展示共享，但它可能是上一次
+ *    成功的结果（服务端刚撤掉的分配还在里面），拿它做删除决策就会把「撤销」误做成
+ *    「没同步上」——反过来，拉取失败时它又是唯一的真相来源，所以两个入口必须分开。
+ *
+ * client bundle 纯度：本文件不 import 任何 `@deepseek-ai/*` 运行时值，也不 import
+ * Host 代码（类型按结构重声明，字段名与契约一致）。
+ */
+/** RPC 频道；必须与 Host `src/managed-mcp.ts` 的 `MANAGED_MCP_RPC_CHANNEL` 一致（由测试锁定）。 */
+export declare const MANAGED_MCP_CHANNEL = "/hiwork-managed-mcp";
+/** 端点白名单；必须与 Host `MANAGED_MCP_RPC_ENDPOINTS` 一致（由测试锁定）。 */
+export declare const MANAGED_MCP_ENDPOINTS: readonly ["snapshot", "refresh", "assertion"];
+export type ManagedMcpEndpoint = (typeof MANAGED_MCP_ENDPOINTS)[number];
+/**
+ * 本地镜像的「陈旧」阈值：5 分钟。
+ * 触发时机里的「打开连接器页且 >5min stale 就同步一次」用它判定——短于它只会让
+ * 用户每次切页都打一遍网关，长于它则界面上的清单明显落后于管理员的推送。
+ */
+export declare const MANAGED_MCP_STALE_MS: number;
+/** 一条分配（对齐 ai-hub spec §4.1 的冻结契约）。 */
+export interface ManagedMcpAssignment {
+    assignmentId: string;
+    revision: number;
+    slug: string;
+    displayName: string;
+    /** 服务端权威下发的装载名：工具前缀 `mcp__<serverName>__` 跨版本稳定的锚点。 */
+    serverName: string;
+    /** `streamable-http | stdio`；认不认识的判断在连接器域（不认识的整条跳过并报冲突）。 */
+    transport: string;
+    url: string;
+    extraHeaders: Record<string, string>;
+    auth: {
+        kind: string;
+        mintUrl: string;
+        revokeUrl: string;
+    };
+    updatedAt: string;
+}
+/** 一份清单快照。`stale` 为 true 表示最近一次拉取失败，展示的是上一次成功的结果。 */
+export interface ManagedMcpSnapshot {
+    revision: number;
+    fetchedAt: string;
+    assignments: ManagedMcpAssignment[];
+    stale: boolean;
+    lastError?: {
+        code: string;
+        message: string;
+    };
+}
+/** 取断言的结果：一张 120 秒的门票 + 去哪换令牌。 */
+export interface ManagedMcpAssertion {
+    assertion: string;
+    mintUrl: string;
+    revokeUrl: string;
+    expiresAt: string;
+    serverName: string;
+}
+/** 宿主 loopback RPC 调用面（结构兼容 `ctx.connection.rpc`）。 */
+export interface ManagedMcpRpcPort {
+    call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<unknown>;
+}
+/** 带稳定 code 的取数错误（message 已由 Host 消毒，可直接展示）。 */
+export declare class ManagedMcpRpcError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * 解开 DSH Connection 的结果信封。
+ * 宿主返回 `{ok:true,value}` / `{ok:false,error:{code,message}}`；形状不合法时抛
+ * 通用失败，绝不把未知结构当数据用。
+ */
+export declare function unwrapManagedMcpResult<T>(value: unknown): T;
+/** 任意异常 → 可展示的 `{code, message}`（传输层异常不暴露原始 message）。 */
+export declare function managedMcpErrorOf(error: unknown): {
+    code: string;
+    message: string;
+};
+/**
+ * 受管 MCP 的取数仓库。
+ *
+ * 本地镜像（`snapshot()` 同步读）是有必要的：DSH 的 client 半边在不同插件之间只通过
+ * 这个面同步取状态，而清单本身是异步来的。镜像**只由成功响应覆写**，失败时不改动它。
+ */
+export declare class ManagedMcpStore {
+    private readonly rpc;
+    private current;
+    private readonly listeners;
+    private inFlight;
+    constructor(rpc: ManagedMcpRpcPort);
+    /** 本地镜像（同步）。从没成功同步过返回 undefined。**不要拿它做删除决策**（见文件头）。 */
+    snapshot(): ManagedMcpSnapshot | undefined;
+    /** 本地镜像是否已经陈旧（或从未同步过）。 */
+    isStale(ttlMs?: number, now?: number): boolean;
+    /**
+     * 强制同步一次并返回**刚拉到的**清单。
+     *
+     * 返回值（而不是让人随后去读 `snapshot()`）是刻意的：只有这个返回值保证「这一次
+     * 网络请求成功了」，用它做删除决策才是安全的；读镜像可能读到上一次的结果。
+     * 失败时抛错且**不动镜像**——调用方据此保持现有的连接一条不删。
+     */
+    refresh(signal?: AbortSignal): Promise<ManagedMcpSnapshot>;
+    /**
+     * 取一份清单，**能用 Host 的预热缓存就用**（Host 后台每 30 分钟拉一次）。
+     *
+     * 与 {@link refresh} 的分工：这里是「启动时先把界面填上」的便宜入口——命中缓存时
+     * 一次网络请求都不发；Host 缓存也是冷的才会真的去拉。返回值仍保证是「某一次成功
+     * 拉取的结果」，但**可能比服务端现状旧**（最旧不超过 Host 的上一次成功拉取），
+     * 所以调用方按 `stale` / `isStale()` 判定它够不够权威，不够就再 `refresh()` 一次。
+     */
+    warm(signal?: AbortSignal): Promise<ManagedMcpSnapshot>;
+    /** 取一张新鲜断言（120 秒）。失败抛错；本层不缓存、不换令牌。 */
+    assertion(assignmentId: string, signal?: AbortSignal): Promise<ManagedMcpAssertion>;
+    /** 订阅镜像变化（连接器域据此重渲染 / 重排同步）。返回退订函数。 */
+    subscribe(listener: () => void): () => void;
+    /** 清空镜像（登出 / 换账号：清单是按人的，留着会串号）。 */
+    clear(): void;
+    /**
+     * 并发去重：`warm` 与 `refresh` 撞在一起（启动同步与定时同步常常同拍）时共用一次
+     * 请求，且**共用同一个返回值**——两边对「这一次拉到了什么」的判断必须一致。
+     */
+    private dedupe;
+    /** 采纳一份成功响应：写镜像 + 通知订阅者（失败路径永远不会走到这里）。 */
+    private adopt;
+    private emit;
+}

package/lib/types/client/types.d.ts

@@ -1,5 +1,11 @@
 /** 稳定错误码，供 settings card 分支渲染。 */
-export type LoginErrorCode = 'AUTH_FAILED' | 'RATE_LIMITED' | 'GATEWAY_UNREACHABLE' | 'NO_KEY_ASSIGNED' | 'SESSION_EXPIRED' | 'KEY_DISABLED' | 'KEY_INVALID' | 'NOT_FOUND';
+export type LoginErrorCode = 'AUTH_FAILED' | 'RATE_LIMITED' | 'GATEWAY_UNREACHABLE' | 'NO_KEY_ASSIGNED' | 'SESSION_EXPIRED' | 'KEY_DISABLED' | 'KEY_INVALID' | 'NOT_FOUND'
+/** 该分配已被管理员撤销（或从未属于当前账号）：取断言时 404。 */
+ | 'MCP_ASSIGNMENT_GONE'
+/** 服务或分配已停用（或被改成了不可下发的凭证方式）：取断言时 409。 */
+ | 'MCP_NOT_DELIVERABLE'
+/** 本部署未配置断言签名私钥（`mcp.assertion_key`）：取断言时 503。 */
+ | 'MCP_ASSERTION_DISABLED';
 /** 一个稳定的、可安全展示的登录/刷新错误。 */
 export interface LoginError {
     code: LoginErrorCode;