@tencent-ai/agent-harness 0.2.0-beta.6 → 0.2.0-beta.8

package/cli/dist-server/types/node/product/config-watch-service.d.ts

@@ -0,0 +1,201 @@
+import { Application, ApplicationLifecycle, Emitter, Logger } from '@celljs/core';
+import { type ICwdService } from '../../workspace/cbc-worktree/lib/node/index.js';
+import { type IPrewarmStateService } from '../prewarm/prewarm-protocol';
+import { ConfigWatchService } from './product-protocol';
+/**
+ * 热更新变更类型
+ */
+export type HotReloadChangeType = 'skills' | 'memory' | 'settings' | 'commands' | 'agents' | 'rules' | 'mcp';
+/**
+ * Config subdirectories under `.codebuddy/` (project) and `~/.codebuddy/` (user)
+ * that get their own recursive watcher. The parent-dir watcher also watches for
+ * these names so that CREATING one of them mid-session (e.g. the LLM writing a
+ * first agent file into a brand-new `agents/`) triggers a watcher rebind + sync
+ * instead of requiring a restart — Claude Code documents this restart caveat;
+ * we close it.
+ */
+export declare const CONFIG_SUBDIR_NAMES: readonly ['agents', 'skills', 'commands', 'rules'];
+/** Map a config subdir name to its hot-reload change type. */
+export declare function configSubdirChangeType(filename: string): HotReloadChangeType | undefined;
+/**
+ * 热更新事件
+ */
+export interface HotReloadEvent {
+    /** 变更类型 */
+    type: HotReloadChangeType;
+    /** 变更的文件路径 */
+    filePath: string;
+    /** 触发时间 */
+    timestamp: number;
+}
+/**
+ * File watcher service for monitoring specific configuration files and triggering hot reload
+ *
+ * Only watches explicitly configured directories/files:
+ * - Skills: .codebuddy/skills/
+ * - Memory: CODEBUDDY.md, CODEBUDDY.local.md in .codebuddy/
+ * - Settings: settings.json, settings.local.json in .codebuddy/
+ * - Commands: .codebuddy/commands/
+ * - Agents: .codebuddy/agents/
+ * - Rules: .codebuddy/rules/
+ *
+ * Can be disabled via environment variable: CODEBUDDY_DISABLE_HOT_RELOAD=1
+ */
+export declare class ConfigWatchServiceImpl implements ConfigWatchService, ApplicationLifecycle<Application> {
+    protected readonly logger: Logger;
+    protected readonly cwdService: ICwdService;
+    protected readonly prewarmState?: IPrewarmStateService;
+    private initialized;
+    private watchers;
+    private watchedPaths;
+    private debounceTimer;
+    private readonly debounceDelay;
+    /** cwd 变更订阅（用于 PreDestroy 时退订） */
+    private cwdChangeSubscription?;
+    /** 标记是否已完成首轮 watcher 建立，避免与首个 BehaviorSubject 种子值重复 setup */
+    private watchersInitialized;
+    /** 热更新是否启用 */
+    private hotReloadEnabled;
+    /** 热更新变更事件 */
+    protected readonly onDidHotReloadEmitter: Emitter<HotReloadEvent>;
+    readonly onDidHotReload: import("@celljs/core").Event<HotReloadEvent>;
+    /** 监听配置映射 */
+    private watchConfigMap;
+    /** 延迟启动文件监听的时间（毫秒），给 UI 渲染留出时间 */
+    private static readonly WATCH_SETUP_DELAY;
+    /** Windows recursive fs.watch gets expensive on large top-level trees. */
+    private static readonly WINDOWS_RECURSIVE_WATCH_ENTRY_THRESHOLD;
+    initialize(): void;
+    private initializeWatchers;
+    /**
+     * 失效所有 project 级缓存——cwd 变更后调用。
+     *
+     * 复用 hot-reload 已有的各类清缓存私有方法，等价于把所有 changeType 跑一遍：
+     * memory / settings / skill 缓存清空 + ProductManager.sync()（强制重扫，让
+     * skill / custom-agents / custom-commands / custom-models 等 WORKSPACE 级
+     * provider 基于新 cwd 重新读取 .codebuddy/*）。
+     *
+     * 设计意图：把「cwd 变了之后该刷哪些 project 级缓存」的知识**内聚**在
+     * ConfigWatchService（它本就是 project 级配置的失效协调者 + onDidChangeCwd
+     * 订阅者），而不是泄漏到 cli-dispatcher 等调用方。调用方只需 setCwdState，
+     * 失效由本服务自治完成，与 watcher 重绑风格一致。
+     *
+     * 注：ProductManager 在 @genie/product 包，无法反向依赖 agent-cli 的
+     * CwdService 自行订阅；由本服务（agent-cli 侧、单向依赖 product）代为触发，
+     * 避免架构倒挂。
+     */
+    private invalidateAllProjectCaches;
+    /**
+     * 重新绑定文件监听：先卸载所有旧 watcher，再按当前 cwd 重新 setup。
+     *
+     * 幂等且可重复调用——既用于首轮建立，也用于 cwd 变更后的重绑。
+     */
+    private rebindWatchers;
+    cleanup(): void;
+    /**
+     * 检查热更新是否启用
+     */
+    isHotReloadEnabled(): boolean;
+    /**
+     * 获取需要监听的目录配置列表
+     */
+    private getWatchConfigs;
+    private pathExists;
+    private setupWatchers;
+    /**
+     * 根据配置监听路径
+     */
+    private watchPath;
+    private getEffectiveRecursiveWatch;
+    /**
+     * 根据文件名确定变更类型
+     */
+    private determineChangeType;
+    /**
+     * 停止监听路径
+     */
+    unwatchPath(path: string): void;
+    /**
+     * 停止所有监听
+     */
+    unwatchAll(): void;
+    /**
+     * 因 FD 限制而禁用热更新
+     * 当检测到 EMFILE 错误时调用，停止所有监控并禁用热更新
+     */
+    private disableHotReloadDueToFdLimit;
+    /**
+     * 获取当前监听的路径列表
+     */
+    getWatchedDirectories(): string[];
+    /**
+     * 检查路径是否正在被监听
+     */
+    isWatching(path: string): boolean;
+    /**
+     * 带防抖的热更新触发（用于 change 事件）
+     */
+    private debouncedSync;
+    /**
+     * 执行热更新
+     */
+    private performHotReload;
+    /**
+     * 项目配置目录（如 `<workDir>/.codebuddy`）本身被新建或删除。
+     *
+     * 目录不存在时 getWatchConfigs 不会为它挂 watcher；删除后重建时旧 watcher 仍绑在已删除的
+     * 目录上（inotify 等按 inode 监听），同样收不到新目录内的事件。而 SettingsManager 会缓存
+     * 项目 settings「文件不存在」的读取结果，所以要先卸载旧 watcher、按当前磁盘状态补挂，
+     * watcher 就位后再按 settings 变更热更新：此后的写入由新 watcher 捕获，此前的写入由这次
+     * 失效后的读盘拿到。
+     */
+    private refreshProjectConfigDir;
+    /**
+     * 清除 SkillProductProvider 缓存
+     */
+    private clearSkillCache;
+    /**
+     * 清除 PluginManager 缓存
+     *
+     * enabledPluginsCache / installedPluginsCache 等读 PROJECT / PROJECT_LOCAL
+     * scope 的 settings（cwd 派生），cwd 变更后必须失效，否则 PluginsProductProvider
+     * 沿用旧 cwd 的启用插件列表。clearCache() 内部还会清 marketplace / inline
+     * 缓存并 fire onDidChange。
+     */
+    private clearPluginCache;
+    /**
+     * 清除 Memory 缓存
+     */
+    private clearMemoryCache;
+    /**
+     * 清除 Settings 缓存
+     */
+    private clearSettingsCache;
+    /**
+     * 通知 SettingsManager 补发 onDidChange（进程外改动 settings 文件时）。
+     */
+    private notifySettingsChanged;
+    /**
+     * 清除 cwd 派生的 MCP scope（PROJECT / LOCAL）配置缓存
+     *
+     * PROJECT（`<cwd>/.mcp.json`）与 LOCAL（`~/.codebuddy.json` 的 projects[cwd]）
+     * 的文件路径都由 cwd 派生。cwd 变更后，之前基于旧 cwd 读到并缓存的这两个
+     * scope 已失效——最典型是预热进程：冷启动 cwd 下预读 PROJECT scope（无
+     * .mcp.json → 空）并缓存，activate chdir 到带 .mcp.json 的 workspace 后，
+     * `list(PROJECT)` 命中旧空缓存，workspace 项目级 MCP 永远加载不出来。
+     * invalidateFilesystemScopeCaches 会清掉这两个 scope 并发 changedSubject，
+     * 触发 McpManager 在已 settle 时重扫。
+     *
+     * 注：cwd 无关的 USER scope 不在此清除——普通 cwd 变更（worktree 切换）无需
+     * 重读它。预热 activate 场景下 USER 可能被待命期 idle-build latch 成空，那由
+     * cli-dispatcher 的 activate 路径显式调 invalidateFilesystemScopeCaches(
+     * { includeUser: true }) 处理，不放这里避免误伤普通 cwd 变更。
+     */
+    private clearMcpConfigCache;
+    /**
+     * 同步 ProductManager
+     * @param force 是否强制重扫（跳过 provider 缓存）。cwd 变更后必须 force，
+     *              否则 SkillProductProvider 等会命中旧 cwd 的缓存。
+     */
+    private syncProductManager;
+}

package/cli/dist-server/types/node/product/craft-to-cli-agent-models-sync-provider.d.ts

@@ -0,0 +1,16 @@
+import { Logger } from '@celljs/core';
+import { type ProductConfiguration, ProductProvider, type ProductProviderContext } from '../../workspace/product/lib/common/index.js';
+/**
+ * 将 craft agent 的模型列表同步到 cli agent。
+ *
+ * 背景：WorkBuddy Desktop 的 product 配置中，默认 agent 是 craft，
+ * 而 agent-cli 使用的默认 agent 是 cli。云端配置通常只给 craft 配置模型列表，
+ * cli agent 可能缺少这些模型。此 provider 在 AgentModelResolver 之后运行，
+ * 检测到 craft agent 存在时，将其 models 合并到 cli agent 中（去重）。
+ */
+export declare class CraftToCliAgentModelsSyncProvider implements ProductProvider {
+    scope: 'runtime';
+    priority: number;
+    protected readonly logger: Logger;
+    provide(ctx: ProductProviderContext): Promise<ProductConfiguration>;
+}

package/cli/dist-server/types/node/product/custom-agents-product-provider.d.ts

@@ -0,0 +1,67 @@
+import { Logger } from '@celljs/core';
+import { Agent, ProductConfiguration, ProductProvider } from '../../workspace/product/lib/common/index.js';
+import { FileSystem } from '../../workspace/runtime/lib/common/index.js';
+import { CustomAgentPathRegistry } from '../agent/custom-agent-path-registry';
+export declare const MAX_CUSTOM_AGENT_FILES_PER_SOURCE = 2048;
+export declare const MAX_CUSTOM_AGENT_FILE_BYTES: number;
+export declare const MAX_CUSTOM_AGENT_DISCOVERY_BYTES_PER_SOURCE: number;
+export declare const MAX_CUSTOM_AGENT_SCAN_ENTRIES_PER_SOURCE = 4096;
+export declare const MAX_CUSTOM_AGENT_DISCOVERY_ENTRY_BYTES: number;
+export type CustomAgentSource = 'project' | 'user';
+export interface CustomAgentSummary {
+    name: string;
+    description: string;
+    path: string;
+    source: CustomAgentSource;
+    model?: string;
+    tools?: string[];
+    color?: string;
+}
+export interface CustomAgentScanError {
+    path: string;
+    message: string;
+}
+export interface CustomAgentListDetailedResult {
+    agents: CustomAgentSummary[];
+    errors: CustomAgentScanError[];
+}
+export interface CustomAgentDiscoveryOptions {
+    forceReload?: boolean;
+    signal?: AbortSignal;
+}
+export declare const CustomAgentDiscoveryService: unique symbol;
+export interface CustomAgentDiscoveryService {
+    listAgentsDetailed(cwd: string, options?: CustomAgentDiscoveryOptions): Promise<CustomAgentListDetailedResult>;
+}
+/**
+ * Custom agents product provider that reads markdown files from .codebuddy/agents directories
+ * and converts them to product agent format.
+ */
+export declare class CustomAgentsProductProvider implements ProductProvider, CustomAgentDiscoveryService {
+    scope: "runtime";
+    priority: number;
+    protected readonly fs?: FileSystem;
+    protected readonly logger: Logger;
+    protected readonly customAgentPathRegistry?: CustomAgentPathRegistry;
+    provide(): Promise<ProductConfiguration>;
+    private loadCustomAgents;
+    /** Served sessions resolve project and user definitions through their mounted filesystem. */
+    scanWorkspace(cwd: string): Promise<Agent[]>;
+    private pathExists;
+    listAgentsDetailed(cwd: string, options?: CustomAgentDiscoveryOptions): Promise<CustomAgentListDetailedResult>;
+    /** Full definitions for host assembly, using the same bounded parser as agent/list. */
+    loadAgents(cwd: string, options?: CustomAgentDiscoveryOptions): Promise<Agent[]>;
+    private discoverAgents;
+    /**
+     * Parse Claude-compatible `mcpServers` frontmatter without touching runtime MCP.
+     * Loading a markdown agent must stay cheap and side-effect free: no server
+     * connection, no config writes, no validation against the global MCP pool here.
+     */
+    private parseMcpServers;
+    private scanAgentsDirectory;
+    /** Apply the same dataFs file-link boundary to management and runtime reads. */
+    private inspectAgentFile;
+    private scanAgentsDirectoryDetailed;
+    private parseAgentFile;
+    private generateSourceLabel;
+}

package/cli/dist-server/types/node/product/custom-commands-product-provider.d.ts

@@ -0,0 +1,49 @@
+import { Logger } from '@celljs/core';
+import { ProductConfiguration, ProductProvider } from '../../workspace/product/lib/common/index.js';
+import { FileSystem } from '../../workspace/runtime/lib/common/index.js';
+export type LegacyCommandSource = 'project' | 'user';
+export interface LegacyCommandMetadata {
+    name: string;
+    description: string;
+    path: string;
+    source: LegacyCommandSource;
+}
+export interface LegacyCommandScanError {
+    path: string;
+    message: string;
+}
+export interface LegacyCommandListDetailedResult {
+    commands: LegacyCommandMetadata[];
+    errors: LegacyCommandScanError[];
+}
+/**
+ * Custom commands product provider that reads markdown files from .codebuddy/commands directories
+ * and converts them to product command format. Scan/parse semantics live in
+ * command-file-scanner.ts, shared with the server surface's session-tier scan.
+ */
+export declare class CustomCommandsProductProvider implements ProductProvider {
+    scope: 'runtime';
+    /**
+     * Plugin and Skill products are rebuilt from the stable Product base.
+     * Re-read filesystem commands in that same volatile transaction, after
+     * the generic workspace layer, so workspace/user command precedence does
+     * not flip between initial sync and a later Plugin refresh.
+     */
+    volatile: boolean;
+    priority: number;
+    protected readonly fs?: FileSystem;
+    protected readonly logger: Logger;
+    provide(): Promise<ProductConfiguration>;
+    private loadCustomCommands;
+    private pathExists;
+    /**
+     * Discover legacy markdown commands for an explicit workspace.
+     *
+     * This management projection intentionally has no persistent cache:
+     * `forceReload` is accepted for parity with the other discovery APIs, and
+     * every call observes the filesystem without changing the process cwd.
+     * Command prompts remain private to the runtime ProductProvider result.
+     */
+    listCommandsDetailed(cwd: string, _forceReload?: boolean): Promise<LegacyCommandListDetailedResult>;
+    private scanCommandsDirectoryDetailed;
+}

package/cli/dist-server/types/node/product/custom-product-config-provider.d.ts

@@ -0,0 +1,6 @@
+import type { ProductConfiguration, ProductProviderContext } from '../../workspace/product/lib/common/index.js';
+import { ProductProvider } from '../../workspace/product/lib/common/index.js';
+export declare class CustomProductConfigProvider implements ProductProvider {
+    priority: number;
+    provide(ctx: ProductProviderContext): Promise<ProductConfiguration>;
+}

package/cli/dist-server/types/node/product/index.d.ts

@@ -0,0 +1,21 @@
+export * from './product-protocol';
+export * from './product-env-service.js';
+export * from './internet-enviroment-product-provider.js';
+export * from './api-key-helper-product-provider.js';
+export * from './cli-options-product-provider.js';
+export * from './sdk-initialize-product-provider.js';
+export * from './craft-to-cli-agent-models-sync-provider.js';
+export * from './custom-commands-product-provider.js';
+export * from './custom-agents-product-provider';
+export * from './skill-product-provider';
+export * from './settings-endpoint-product-provider.js';
+export * from './config-watch-service.js';
+export * from './mcp-watch-service.js';
+export * from './cloud-pre-product-provider.js';
+export * from './models-product-provider.js';
+export * from './plugin-product-provider.js';
+export * from './mcp-prompt-product-provider.js';
+export * from './product-config-controller.js';
+export * from './custom-product-config-provider.js';
+export * from './product-identity';
+export * from './product-capabilities';

package/cli/dist-server/types/node/product/internet-enviroment-product-provider.d.ts

@@ -0,0 +1,61 @@
+import { Logger } from '@celljs/core';
+import { ProductConfiguration, ProductProvider, ProductProviderContext } from '../../workspace/product/lib/common/index.js';
+import { FileSystem } from '../../workspace/runtime/lib/common/index.js';
+import { SettingsManager } from '../settings';
+/**
+ * 插件客户端产品提供者。根据不同网络环境加载额外配置。
+ */
+export declare class ClientInternetEnviromentProductProvider implements ProductProvider {
+    priority: number;
+    protected readonly fs?: FileSystem;
+    protected readonly logger: Logger;
+    protected readonly settingsManager: SettingsManager;
+    private cachedProductConfigurations;
+    protected init(): void;
+    provide(ctx: ProductProviderContext): Promise<ProductConfiguration>;
+    /**
+     * 按网络环境 / endpoint 域名推导 deployment type，仅在宿主未注入 deploymentType（CLI 独立运行）
+     * 时作为兜底使用——`cli-saas` 是一份产物同时服务 SaaS / 专享版 / 私有化，没有可区分的打包值，
+     * 只能运行时推（见 #34747：专享版/企业版 X-Product 错误）。挂在宿主下时该结果会被
+     * `withHostDeploymentType` 覆盖，以宿主打包值为准。
+     */
+    private resolveDeploymentType;
+    private extractDomain;
+    /**
+     * 把 `cloudHostedDomain` 通配符模板（如 `*.sso.copilot.tencent.com`）编译成锚定正则。
+     * captureWildcard=true 时 `*` 作为捕获组，用于提取前缀；否则仅做匹配。
+     */
+    private compileWildcardPattern;
+    private isDomain;
+    /**
+     * 从企业 endpoint 域名前缀解析 enterpriseId：`<enterpriseId>.sso.copilot.tencent.com`
+     * 命中 `cloudHostedDomain` 通配模板时，`*` 捕获到的前缀段即 enterpriseId。
+     * 无 endpoint / 无模板 / 不匹配 / 前缀为空时返回 undefined。
+     */
+    private resolveEnterpriseIdFromEndpoint;
+    /**
+     * 读取宿主注入的产品配置中显式声明的权威字段：
+     * - `endpoint`——该 session 的权威后端网关地址；
+     * - `deploymentType`——宿主打包产物声明的部署形态，决定 X-Product header。
+     * 无注入或字段缺失时返回 undefined（此时由 product.<env>.json / 上游 provider 决定，
+     * 即 CLI 独立运行时回落到自身打包值）。
+     *
+     * 读取顺序与 env-product-provider.ts 对齐，覆盖宿主两种下发形态：
+     * 1. 内联 env（ACC_PRODUCT_CONFIG_V3/V2）——常规形态；
+     * 2. 落盘文件（ACC_PRODUCT_CONFIG_PATH）——Linux 上整份配置超阈值时，宿主会删除内联
+     *    env、只留文件路径以规避 execve E2BIG（阈值判定的是整份 JSON 体积，多agent /
+     *    大模型清单场景很容易触发，与 endpoint 字段本身大小无关）。缺了这条回退，spill
+     *    场景会读不到权威 endpoint，导致修复在真实大配置路径下失效。
+     *
+     * 内联优先、文件兜底：内联存在即代表宿主本轮下发的权威值，无需再读盘。两个字段来自同一份
+     * 快照，因此以「第一个存在的快照」整体为准，不逐字段跨快照拼接——否则 endpoint 与
+     * deploymentType 可能来自不同轮次的下发而互相矛盾。
+     */
+    private resolveAuthoritativeFieldsFromEnv;
+    /**
+     * 从ACC_PRODUCT_CONFIG_PATH 落盘文件解析权威字段。fs 为 @Optional 注入，
+     * headless / 无文件系统能力时缺省，此时安全返回空结果。
+     */
+    private resolveAuthoritativeFieldsFromConfigFile;
+    private getNetworkEnviromentFromConfigEnv;
+}

package/cli/dist-server/types/node/product/mcp-prompt-product-provider.d.ts

@@ -0,0 +1,17 @@
+import { Logger } from '@celljs/core';
+import { ProductConfiguration, ProductProvider } from '../../workspace/product/lib/common/index.js';
+import { McpManager } from '../mcp';
+/**
+ * MCP prompt product provider that converts MCP server prompts into commands.
+ * Commands are named with format: mcpName:promptName
+ */
+export declare class McpPromptProductProvider implements ProductProvider {
+    scope: 'runtime';
+    priority: number;
+    volatile: boolean;
+    protected readonly mcpManager: McpManager;
+    protected readonly logger: Logger;
+    provide(): Promise<ProductConfiguration>;
+    private loadMcpPrompts;
+    private convertPromptToCommand;
+}

package/cli/dist-server/types/node/product/mcp-watch-service.d.ts

@@ -0,0 +1,31 @@
+import { Application, ApplicationLifecycle, Logger } from '@celljs/core';
+import { McpServerModelManager } from '../mcp/mcp-protocol';
+import { McpWatchService } from './product-protocol';
+/**
+ * MCP server connection watcher service for monitoring MCP server status changes
+ * and reprojecting MCP-derived Product runtime state
+ */
+export declare class McpWatchServiceImpl implements McpWatchService, ApplicationLifecycle<Application> {
+    protected readonly logger: Logger;
+    protected readonly serverModelManager: McpServerModelManager;
+    private subscription;
+    private debounceTimer;
+    private readonly pendingSyncs;
+    private stopped;
+    private readonly lastTerminalStates;
+    protected debounceDelay: number;
+    initialize(): void;
+    cleanup(): Promise<void>;
+    /**
+     * Subscribe to MCP server model status changes
+     */
+    private setupServerModelSubscription;
+    /**
+     * Unsubscribe from MCP server model changes
+     */
+    private unsubscribe;
+    /**
+     * Reproject volatile Product providers with debounce to prevent excessive calls.
+     */
+    private debouncedSync;
+}

package/cli/dist-server/types/node/product/models-product-provider.d.ts

@@ -0,0 +1,41 @@
+import { Logger } from '@celljs/core';
+import { RestOperations } from '@celljs/http';
+import { AuthenticationManager } from '../../workspace/authentication/lib/common/index.js';
+import { LanguageModel, ProductConfiguration, ProductProvider, ProductProviderContext } from '../../workspace/product/lib/common/index.js';
+/**
+ * 从云端模型列表接口获取产品配置。
+ * 使用内存缓存避免重复 API 调用，同时确保不会覆盖其他 Provider 追加的自定义模型。
+ */
+export declare class ModelsProductProvider implements ProductProvider {
+    priority: number;
+    protected readonly restOperations: RestOperations;
+    protected readonly logger: Logger;
+    protected readonly authenticationManager: AuthenticationManager;
+    protected hasTriggeredSyncForEnterprise: boolean;
+    protected cachedResult: ProductConfiguration | undefined;
+    protected cacheExpireAt: number;
+    /**
+     * 失败/空响应后的退避截止时间。在此时间之前直接复用上一份结果，
+     * 避免私有化后端持续返回空/异常时每轮 sync 都重打接口，
+     * 进而让 ProductManager 反复判定配置变更并触发热循环（issue #52373）。
+     */
+    protected retryBackoffUntil: number;
+    /** 连续失败次数，用于指数退避 */
+    protected consecutiveFailures: number;
+    /** 失败退避最小间隔 30s */
+    protected static readonly MIN_FAILURE_BACKOFF_MS: number;
+    /** 失败退避最大间隔 5min */
+    protected static readonly MAX_FAILURE_BACKOFF_MS: number;
+    protected init(): void;
+    provide(ctx: ProductProviderContext): Promise<ProductConfiguration>;
+    /**
+     * 兜底结果：优先复用上一份成功获取的配置，避免空响应导致 merge 后配置抖动。
+     * 没有缓存时（首次启动、enterpriseId 未就绪等）返回空的 SmartMerge 配置。
+     */
+    protected getFallbackResult(): ProductConfiguration;
+    /**
+     * 记录一次失败/空响应并设置指数退避截止时间。
+     */
+    protected applyFailureBackoff(): void;
+    protected processModelAgentRelations(config: ProductConfiguration, models?: LanguageModel[]): ProductConfiguration;
+}

package/cli/dist-server/types/node/product/plugin-product-provider.d.ts

@@ -0,0 +1,13 @@
+import { PluginManager } from '../../workspace/cbc-plugins/lib/node/index.js';
+import { ProductConfiguration, ProductMerger, ProductProvider } from '../../workspace/product/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+export declare class PluginsProductProvider implements ProductProvider {
+    scope: 'runtime';
+    priority: number;
+    /** Plugin projection is runtime-only and must never enter Product cache. */
+    volatile: boolean;
+    protected readonly pluginManager: PluginManager;
+    protected readonly productMerger: ProductMerger;
+    protected readonly logger: Logger;
+    provide(): Promise<ProductConfiguration>;
+}

package/cli/dist-server/types/node/product/product-capabilities.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 运行时能力表：每一项都是"允许做什么"的正向语义。
+ * 官方版全部为 true，定制版按协议约束关掉相应位。
+ */
+export interface ProductCapabilities {
+    /** 是否允许自动更新（后台定时检查并下载新版本）。定制版按 `updates` 派生。 */
+    autoUpdate: boolean;
+    /** 是否允许手动 `codebuddy update` 触发官方 registry 更新。定制版按 `updates` 派生。 */
+    manualUpdate: boolean;
+    /** 是否允许注册系统 Daemon（launchd / systemd / TaskScheduler）。定制版禁用。 */
+    systemDaemon: boolean;
+    /**
+     * 是否允许 settings.json 里的 `endpoint` / `enterpriseEndpoint` 覆盖默认端点。
+     * 定制版禁用：客户 Endpoint 由 customization.json 固定，用户手改 settings 不能绕过。
+     */
+    settingsEndpointOverride: boolean;
+    /**
+     * 客户自建更新源。
+     *
+     * `undefined` 表示走官方更新源（官方版 or 定制版 `updates: {disabled:true}` 时都是它）。
+     * 有值时表示定制版启用了客户源，`ReleasesService` 用 `baseUrl` 派生
+     * `${baseUrl}/latest` / `${baseUrl}/download/{version}/{filename}`。
+     *
+     * 只在 `autoUpdate` / `manualUpdate` 至少一项为 true 时非空。
+     */
+    customUpdateSource?: {
+        /** 从 checkVersion.url 派生的 baseUrl（已去除 `/latest` 尾部与末尾斜杠）。 */
+        baseUrl: string;
+        /** 后台轮询间隔（秒），来自 `updates.checkVersion.intervalSeconds`。 */
+        intervalSeconds?: number;
+    };
+}
+/**
+ * 派生当前进程的能力表。
+ *
+ * 官方版返回所有能力开启；定制版按协议关掉：更新、系统 Daemon、
+ * settings endpoint 覆盖、官方市场。
+ *
+ * **判定颗粒度**（Issue 评审 blocker：显式禁用更新不能被误判为空配置而静默丢弃）：
+ * - 「真实定制内容」（品牌 / 端点 / 目录 / 链路 / 遥测任一有实际内容）→ 四个能力位全关（白牌全面隔离）；
+ * - 「只显式禁更新」的最小配置（如 `{"updates":{"disabled":true}}`）→ **只关**
+ *   autoUpdate / manualUpdate；systemDaemon 与 settingsEndpointOverride 维持官方行为
+ *   （客户没提这两项，不替他做决定）；
+ * - `{}` 空模板 / 未涉及更新意图 → 视同官方。
+ *
+ * `updates` 派生规则：
+ * - 未配 / `{ disabled: true }` → autoUpdate=false, manualUpdate=false, customUpdateSource=undefined
+ * - 配了 `checkVersion.url + download.url`：
+ *   - manualUpdate 恒为 true
+ *   - autoUpdate = !manualOnly
+ *   - customUpdateSource = 派生 baseUrl
+ *
+ * 未来若需要按定制配置细粒度控制，在此函数内加分支即可，消费方无需任何改动。
+ */
+export declare function resolveProductCapabilities(): ProductCapabilities;

package/cli/dist-server/types/node/product/product-config-controller.d.ts

@@ -0,0 +1,27 @@
+import { ProductManager } from '../../workspace/product/lib/common/index.js';
+import { Logger } from '../../workspace/telemetry/lib/common/index.js';
+/**
+ * 产品配置 REST 控制器
+ *
+ * 提供全局产品配置的 HTTP 接口，供 Desktop UI 在无会话上下文时获取配置。
+ *
+ * 调用链路：
+ *   Desktop UI → RestClient.getProductConfiguration()
+ *     → GET /api/v1/product/config
+ *     → ProductConfigController.getProductConfig()
+ *     → ProductManager.waitConfiguration()
+ */
+export declare class ProductConfigController {
+    protected readonly productManager: ProductManager;
+    protected readonly logger: Logger;
+    /**
+     * GET /api/v1/product/config
+     *
+     * 等待产品配置合并完成后返回完整配置。
+     *
+     * issue #78178：此端点此前完全无鉴权检查，无凭据即可读取完整产品配置
+     * （含模型清单、endpoint 等）。鉴权现由全局 GatewayGlobalAuthMiddleware
+     * （issue #81089）统一执行。
+     */
+    getProductConfig(): Promise<void>;
+}

package/cli/dist-server/types/node/product/product-env-service.d.ts

@@ -0,0 +1,20 @@
+import { Logger } from '@celljs/core';
+import { AuthSession } from '../../workspace/authentication/lib/common/index.js';
+import { ProductConfigurationContext, ProductManager } from '../../workspace/product/lib/common/index.js';
+import { SettingsManager } from '../settings';
+import { ProductEnviroment, ProductEnvService } from './product-protocol';
+export declare class ProductEnvServiceImpl implements ProductEnvService {
+    protected readonly productContext?: ProductConfigurationContext;
+    protected readonly productManager: ProductManager;
+    protected readonly settingsManager: SettingsManager;
+    protected readonly logger: Logger;
+    /** Track last switched environment to avoid redundant sync calls */
+    protected lastSwitchedEnv: ProductEnviroment | undefined;
+    protected earlyEnvInit(): void;
+    switch(env: ProductEnviroment | undefined): Promise<void>;
+    switchBySession(session?: AuthSession): Promise<void>;
+    getCurrent(): Promise<ProductEnviroment | undefined>;
+    private resolveEnvBySession;
+    private isDomain;
+    private matchDomain;
+}