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

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/loaders/plugin-loader-manager.d.ts

@@ -0,0 +1,73 @@
+import { Logger } from '@celljs/core';
+import { CliRuntimeOptions } from '../../../../../../node/cli/cli-runtime-options.js';
+import { McpConfig } from '../../../../../../node/mcp/index.js';
+import { Command } from '../../../../../product/lib/common/index.js';
+import { PluginOptionsStorage } from '../plugin-options-storage.js';
+import { PluginComponents, PluginErrorCollector, PluginInfo } from '../plugin-protocol.js';
+import { AgentExtensionLoader } from './agent-loader.js';
+import { CommandExtensionLoader } from './command-loader.js';
+import { HookExtensionLoader } from './hook-loader.js';
+import { LSPExtensionLoader } from './lsp-loader.js';
+import { MCPExtensionLoader } from './mcp-loader.js';
+import { OutputStyleExtensionLoader } from './output-style-loader.js';
+import { SkillExtensionLoader } from './skill-loader.js';
+/**
+ * 插件加载器管理器
+ * 统一协调各类型扩展加载器，根据pluginInfo对象的配置智能加载扩展
+ * 内部智能合并配置加载和文件扫描的结果
+ */
+export declare class PluginLoaderManager {
+    protected readonly logger: Logger;
+    protected readonly errorCollector: PluginErrorCollector;
+    protected readonly agentLoader: AgentExtensionLoader;
+    protected readonly commandLoader: CommandExtensionLoader;
+    protected readonly skillLoader: SkillExtensionLoader;
+    protected readonly hookLoader: HookExtensionLoader;
+    protected readonly mcpLoader: MCPExtensionLoader;
+    protected readonly lspLoader: LSPExtensionLoader;
+    protected readonly outputStyleLoader: OutputStyleExtensionLoader;
+    protected readonly pluginOptionsStorage?: PluginOptionsStorage;
+    protected readonly cliRuntimeOptions: CliRuntimeOptions;
+    protected init(): void;
+    /**
+     * 归一化路径配置：仅保留字符串路径，过滤掉非字符串项。
+     *
+     * 背景：plugin-manager 的 enrichPluginInfo 出于 REST 展示目的，会把
+     * `{ name, description }` 对象写入同一个 PluginInfo 的 skills/commands 字段
+     * （契约本应为路径字符串）。这些展示元数据并非可加载的路径，若直接透传给
+     * 各 loader 的 `join(extensionDir, path)` 会抛 ERR_INVALID_ARG_TYPE，进而被
+     * 上层 catch 静默吞掉，最终降级为「0 个技能/命令」。这里在消费边界做归一化，
+     * 把非字符串项剔除；当过滤后为空时返回 undefined，使 loader 回退到默认目录扫描。
+     */
+    private normalizePathConfig;
+    private createPluginEnvironment;
+    private loadPluginCommandsWithEnvironment;
+    /**
+     * Load only slash commands from one already-resolved Plugin path. This is
+     * the runtime-parity boundary used by pre-session management discovery; it
+     * deliberately does not inspect hooks, MCP bundles, LSP or other Plugin
+     * components.
+     */
+    loadPluginCommands(pluginInfo: PluginInfo, pluginPath: string, projectDir: string): Promise<Command[]>;
+    /**
+     * Load only MCP declarations from one already-resolved Plugin path.
+     *
+     * Resource discovery uses this narrow boundary to describe Plugin MCP to
+     * the Harness-owned connection plane without activating the rest of the
+     * Plugin runtime or publishing the descriptors into this process's MCP
+     * manager. An ordinary Agent runtime can still load and connect its own
+     * Plugin MCP through {@link loadPluginComponents} when strict MCP config is
+     * disabled.
+     */
+    loadPluginMcpServers(pluginInfo: PluginInfo, pluginPath: string, projectDir: string, environment: Readonly<NodeJS.ProcessEnv>): Promise<Record<string, McpConfig>>;
+    /**
+     * 从插件信息加载所有组件
+     * 根据pluginInfo对象中的配置字段决定加载哪些扩展
+     * 各加载器内部会智能合并配置和文件扫描的结果
+     *
+     * @param pluginInfo 插件信息对象，包含name、description及agents/commands/skills/hooks/mcpServers等配置
+     * @param pluginPath 插件安装路径
+     * @returns PluginComponents 包含所有加载的扩展组件
+     */
+    loadPluginComponents(pluginInfo: PluginInfo, pluginPath: string): Promise<PluginComponents>;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/loaders/skill-loader.d.ts

@@ -0,0 +1,45 @@
+import { Logger } from '@celljs/core';
+import { Skill } from '../../../../../product/lib/common/index.js';
+import { PluginEnvironmentContext } from '../plugin-environment.js';
+import { PluginErrorCollector, PluginExtensionType } from '../plugin-protocol.js';
+/**
+ * Skill 扩展加载器
+ * 从扩展目录的 skills 子目录中加载 skill 配置
+ * 支持配置路径和默认扫描的合并
+ */
+export declare class SkillExtensionLoader {
+    readonly type = PluginExtensionType.Skill;
+    protected readonly logger: Logger;
+    protected readonly errorCollector: PluginErrorCollector;
+    protected init(): void;
+    /**
+     * 加载 skills
+     * 如果提供了 skillPaths 配置，则加载指定路径；否则默认扫描 skills 目录
+     * 两种方式的结果会被合并
+     * @param extensionDir 扩展目录路径
+     * @param extensionName 扩展名称（用于标记）
+     * @param skillPaths 可选的 skill 路径配置数组，相对于 extensionDir
+     * @returns Skill 数组
+     */
+    load(extensionDir: string, extensionName: string, skillPaths?: string[], pluginEnvironment?: PluginEnvironmentContext): Promise<Skill[]>;
+    /**
+     * 从指定的 skill 路径加载
+     * @param extensionDir 扩展目录路径
+     * @param extensionName 扩展名称
+     * @param skillPaths skill 路径配置数组
+     * @param loadedPaths 已加载的路径集合，用于去重
+     * @returns Skill 数组
+     */
+    private loadFromPaths;
+    private pathExists;
+    unload(extensionName: string): Promise<void>;
+    /**
+     * Maximum recursion depth for scanning nested skill directories.
+     */
+    private static readonly MAX_SCAN_DEPTH;
+    private scanSkillsDirectory;
+    private getSkillLoadConcurrency;
+    private isDirectoryEntry;
+    private isFileEntry;
+    private parseSkillFile;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/marketplace-name-validator.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 官方市场名称保护 - 四层防御
+ *
+ * 防止第三方冒充官方市场：
+ * 1. 白名单 - 官方保留名称
+ * 2. 黑名单模式 - 正则模式匹配冒充名称
+ * 3. 同形攻击防护 - 检测 Unicode 非 ASCII 字符
+ * 4. 源验证 - 官方名称必须来自可信源
+ *
+ * 参考: Claude Code schemas.ts:1-157
+ */
+/**
+ * 官方保留市场名称
+ * 仅官方市场允许使用这些名称，第三方注册会被拒绝
+ */
+export declare const ALLOWED_OFFICIAL_MARKETPLACE_NAMES: Set<string>;
+/**
+ * 检测冒充官方名称的正则模式
+ *
+ * 匹配以下变体：
+ * - "official" + "codebuddy/anthropic/claude" (如 "official-codebuddy-plugins")
+ * - "codebuddy/anthropic/claude" + "official" (如 "claude-official")
+ * - "codebuddy/anthropic/claude" 开头 + 官方后缀 (如 "anthropic-marketplace-new")
+ */
+export declare const BLOCKED_OFFICIAL_NAME_PATTERN: RegExp;
+/**
+ * 检查市场名称是否冒充官方名称
+ *
+ * @param name 市场名称
+ * @returns true 表示被阻止（冒充），false 表示允许
+ */
+export declare function isBlockedOfficialName(name: string): boolean;
+/**
+ * 验证官方名称的来源是否可信
+ * 官方保留名称只能从可信的 GitHub 组织或官方 CDN 路径注册
+ *
+ * @param name 市场名称
+ * @param source 市场源地址 (GitHub URL、org/repo 格式、或官方 CDN URL)
+ * @returns true 表示来源可信，false 表示不可信
+ */
+export declare function validateOfficialNameSource(name: string, source?: string): boolean;
+/**
+ * 检查是否为官方市场名称（用于自动更新默认值等）
+ */
+export declare function isOfficialMarketplace(name: string): boolean;
+/**
+ * 检查市场是否默认启用自动更新
+ * 官方市场默认启用（除了明确排除的），第三方默认不启用
+ */
+export declare function isMarketplaceAutoUpdateDefault(marketplaceName: string, autoUpdate?: boolean): boolean;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/marketplace-path-safety.d.ts

@@ -0,0 +1,86 @@
+import { MarketplaceInfo, MarketplaceType } from './plugin-protocol.js';
+export declare function getMarketplacesRoot(homePluginsDir?: string): string;
+/**
+ * Require a single non-empty path segment. Unicode/spaces are allowed; unsafe
+ * input is rejected rather than sanitized. Prefer {@link resolveMarketplaceInstallDir}
+ * when you also need the directory; call this alone only to validate a name
+ * without resolving a path (e.g. adopting an in-memory display name).
+ */
+export declare function assertSafePathSegment(value: unknown, label?: string): void;
+/**
+ * Plugin names used in `join(marketplaceRoot, 'plugins', name)` must be a
+ * single safe identifier (same rule as Local/Git installers).
+ */
+export declare function assertSafePluginName(name: unknown): void;
+/**
+ * Resolve `segments` under `baseDir` and reject any path that escapes the root
+ * (Zip Slip / `../` / absolute segments). By default the result must be a
+ * strict child of `baseDir` (the root itself is not a valid install target).
+ *
+ * Pass `{ allowRoot: true }` for local plugin sources like `"."` / `"./"` where
+ * the marketplace root is also the plugin root.
+ */
+export declare function resolveContainedPath(baseDir: string, ...segments: string[]): string;
+/** Same as {@link resolveContainedPath}, but `"."` / `"./"` may resolve to `baseDir`. */
+export declare function resolveContainedPathAllowingRoot(baseDir: string, ...segments: string[]): string;
+/** Resolve `marketplaces/<name>` after a single segment check. Do not pre-assert. */
+export declare function resolveMarketplaceInstallDir(marketplacesRoot: string, name: unknown): string;
+/**
+ * Persisted `installLocation` for non-directory marketplaces must stay inside
+ * `plugins/marketplaces`. Poisoned config must fail closed — never delete or
+ * update paths outside the root.
+ */
+export declare function assertInstallLocationInsideMarketplacesRoot(installLocation: string, marketplacesRoot?: string): void;
+export declare function isInstallLocationInsideMarketplacesRoot(installLocation: string, marketplacesRoot?: string): boolean;
+/**
+ * Resolve existing paths (or the nearest existing ancestor) via realpath and
+ * ensure the final target stays inside the marketplaces root. Blocks
+ * symlink/junction escapes that string containment alone would miss.
+ *
+ * Fail-closed: only ENOENT walks to a parent (first install / missing dest).
+ * EACCES, ELOOP, and other realpath failures refuse the operation.
+ */
+export declare function assertRealInstallLocationInsideMarketplacesRoot(installLocation: string, marketplacesRoot?: string): Promise<void>;
+export declare function isDirectoryMarketplaceType(type: MarketplaceType | string | undefined): boolean;
+export declare function isGeneratedMarketplaceSourceStagingName(name: string): boolean;
+/** Resolve the one durable source directory for a managed marketplace. */
+export declare function resolveStableMarketplaceInstallLocation(marketplace: Pick<MarketplaceInfo, 'name' | 'storageName'>, homePluginsDir?: string): string;
+/**
+ * Detect the layout accidentally persisted by older clients after they used a
+ * transaction-local `source-*` directory as the final marketplace directory.
+ */
+export declare function isLegacyMarketplaceSourceStagingLocation(marketplace: Pick<MarketplaceInfo, 'type' | 'source' | 'installLocation'>, homePluginsDir?: string): boolean;
+/**
+ * Check whether a persisted remote marketplace points at a complete local
+ * source snapshot.
+ *
+ * Directory marketplaces are declarations of a host-owned live directory,
+ * not copied source snapshots. Keep their registry entry even while that
+ * directory is temporarily unavailable so already-materialized plugin caches
+ * remain usable. Remote marketplaces, however, must have a readable catalog and every
+ * catalog-local plugin directory before reconcile may call them installed.
+ */
+export declare function isMarketplaceMaterialized(info: Pick<MarketplaceInfo, 'type' | 'source' | 'installLocation'>, marketplacesRoot?: string): Promise<boolean>;
+/**
+ * Non-directory marketplaces may only persist install paths under marketplaces root.
+ * Uses realpath so a junction/symlink that only *looks* contained is still rejected (#71947).
+ */
+export declare function isLoadableInstallLocation(info: {
+    type?: MarketplaceType | string;
+    source?: {
+        source?: string;
+    };
+    installLocation?: string;
+}, marketplacesRoot: string): Promise<boolean>;
+/**
+ * Refuse to persist a non-directory marketplace whose installLocation escapes the
+ * marketplaces root — including via symlink/junction (#71947).
+ */
+export declare function assertSavableInstallLocation(marketplace: {
+    name: string;
+    type?: MarketplaceType | string;
+    source?: {
+        source?: string;
+    };
+    installLocation?: string;
+}, marketplacesRoot?: string): Promise<void>;

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/marketplaces/base-marketplace.d.ts

@@ -0,0 +1,48 @@
+import { ContainerUtil } from '@celljs/core';
+import { Marketplace, MarketplaceInfo, MarketplaceManifest, MarketplaceSource, MarketplaceType, PluginInfo, ProgressCallback } from '../plugin-protocol.js';
+/**
+ * 市场实体类
+ */
+export declare class BaseMarketplace implements Marketplace {
+    protected componentServices?: typeof ContainerUtil;
+    protected get services(): typeof ContainerUtil;
+    name: string;
+    storageName: string;
+    manifestName?: string;
+    /** 见 {@link MarketplaceInfo.declaredName}。 */
+    declaredName?: string;
+    type: MarketplaceType;
+    source: MarketplaceSource;
+    installLocation: string;
+    description?: string;
+    lastUpdated?: string;
+    isBuiltIn?: boolean;
+    autoUpdate?: boolean;
+    manifest?: MarketplaceManifest;
+    constructor();
+    init(marketplaceInfo: MarketplaceInfo): void;
+    loadManifest(): Promise<void>;
+    install(onProgress?: ProgressCallback): Promise<void>;
+    update(onProgress?: ProgressCallback): Promise<boolean>;
+    /**
+     * 列出市场中的所有插件
+     * 仅返回marketplace.json中定义的插件元数据,不执行安装
+     * 实际安装由PluginManager通过PluginInstaller完成
+     */
+    listPlugins(): Promise<PluginInfo[]>;
+    /**
+     * 获取指定插件信息
+     * @param pluginName 插件名称
+     * @returns 插件信息，如果不存在则抛出异常
+     */
+    getPlugin(pluginName: string): Promise<PluginInfo | undefined>;
+    /**
+     * 转换为JSON对象
+     *
+     * 注意：必须包含 `storageName`，否则 marketplace 信息一旦经过 toJSON()
+     *（例如对外 API 响应、跨进程消息、缓存持久化）就会丢失稳定 ID。
+     * `name` 在 loadManifest() 后会被 manifest.name 覆盖，是不稳定字段，
+     * 不能作为外部唯一标识使用。
+     */
+    toJSON(): MarketplaceInfo;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/marketplaces/builtin-marketplace-provider.d.ts

@@ -0,0 +1,47 @@
+import { ContainerUtil } from '@celljs/core';
+import { ProductConfigurationContext } from '../../../../../product/lib/common/index.js';
+import { Logger } from '../../../../../telemetry/lib/common/index.js';
+import { BuiltInMarketplaceProvider, MarketplaceConfigEntry, MarketplaceSource } from '../plugin-protocol.js';
+export declare class BuiltInMarketplaceProviderImpl implements BuiltInMarketplaceProvider {
+    protected componentServices?: typeof ContainerUtil;
+    protected get services(): typeof ContainerUtil;
+    protected readonly logger: Logger;
+    protected readonly executionConfiguration?: ProductConfigurationContext;
+    /**
+     * 绑定配置身份，靠每轮同步发布的新快照自然失效。裸 Set 会把"配置里暂时没有内置市场"
+     * （定制版 `builtInMarketplaces: {}` 即此形态）固化成空集，之后永远判不出内置市场（#119844）。
+     */
+    private builtInNamesCache?;
+    protected init(): void;
+    /**
+     * 只读已发布配置：`getCurrentConfiguration()` 会暴露 doSync 逐个 provider 合并的中间态
+     * （打包 product.json 已合并、ENV 下发的带版本号 URL 尚未覆盖），据此对比会误判 source
+     * 变化并整包重装（#119844）。
+     *
+     * 尚未发布时返回 undefined 而不是回退读中间态：此时没有任何一层声明过期望状态，猜一个
+     * 出来就会按从未被声明的状态改写共享的市场存储。首次发布必然 fire `onDidChange`，
+     * 热加载会补跑安装（PluginManager 的 `wait-builtin-marketplace-refresh` 阶段）。
+     */
+    private getPublishedConfiguration;
+    /**
+     * #83869 builtin 市场静态资源 URL（市场 zip / version / meta）解析：
+     * enterprise 模式（UseEnterpriseDownloadSource + endpoint 就绪）下命中 SaaS
+     * 静态域名表的 URL 整域名改写为 {endpoint}{path}；saas / 未命中原样返回。
+     * 幂等：已改写的企业 URL 不会二次改写。
+     */
+    private resolveMarketplaceUrl;
+    /**
+     * 获取所有内置市场配置
+     * 将对象结构转换为带名称的数组结构
+     */
+    getBuiltInMarketplaces(): Promise<MarketplaceConfigEntry[]>;
+    /**
+     * 检查指定市场是否为内置市场
+     */
+    isBuiltInMarketplace(name: string): Promise<boolean>;
+    getVersionUrl(name: string): Promise<string | undefined>;
+    /**
+     * 将市场配置转换为 MarketplaceSource
+     */
+    toMarketplaceSource(config: MarketplaceConfigEntry): MarketplaceSource;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/marketplaces/directory-marketplace.d.ts

@@ -0,0 +1,19 @@
+import { PluginInfo, ProgressCallback } from '../plugin-protocol.js';
+import { BaseMarketplace } from './base-marketplace.js';
+/**
+ * 目录类型的市场实现类
+ */
+export declare class DirectoryMarketplace extends BaseMarketplace {
+    private pluginListCache?;
+    private pluginListLoading?;
+    private pluginListGeneration;
+    clearPluginListCache(): void;
+    install(onProgress?: ProgressCallback): Promise<void>;
+    /**
+     * 列出市场中的所有插件
+     */
+    listPlugins(): Promise<PluginInfo[]>;
+    private loadPluginList;
+    private findPluginManifestPath;
+    private clonePlugins;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/marketplaces/git-availability-detector.d.ts

@@ -0,0 +1,62 @@
+import { Logger } from '../../../../../telemetry/lib/common/index.js';
+/**
+ * Probes whether the local `git` executable is invokable.
+ *
+ * The result is cached for the lifetime of the process; concurrent callers
+ * share a single probe promise. Callers that want a fresh answer (for
+ * example after an in-app "install git" action) can call
+ * {@link invalidateCache}.
+ *
+ * The probe is guarded by a short timeout. On slow machines this trades a
+ * tiny chance of a false negative for a hard upper bound on how long
+ * marketplace installation waits before deciding to fall back to Zip.
+ *
+ * On macOS the probe first checks — WITHOUT executing git — whether the
+ * resolved `git` is merely the Apple Command Line Tools shim while the tools
+ * are absent. In that case it reports git as unavailable instead of running
+ * the shim, which would otherwise trigger the "install developer tools"
+ * dialog. `xcode-select -p` is used for the tools-presence check; unlike
+ * `git`/`xcode-select --install`, it never triggers the GUI prompt.
+ */
+export declare class GitAvailabilityDetector {
+    protected readonly logger: Logger;
+    /**
+     * Upper bound on the `git --version` probe. 5s is generous for a
+     * process-start benchmark yet short enough that users do not perceive
+     * a stall when git is absent but reported by shims that hang.
+     */
+    private static readonly DETECTION_TIMEOUT_MS;
+    private probePromise;
+    /** Returns true when `git --version` exits successfully within the timeout. */
+    isAvailable(): Promise<boolean>;
+    /** Clears the cached probe result so the next {@link isAvailable} call re-probes. */
+    invalidateCache(): void;
+    private probe;
+    /**
+     * macOS-only: decide whether executing `git` is safe (i.e. will not trigger
+     * the Command Line Tools install dialog).
+     *
+     * - No `git` anywhere on PATH → not safe (nothing to run anyway).
+     * - `git` resolves to a real binary (Homebrew/MacPorts/…, i.e. anything
+     *   other than {@link MACOS_GIT_STUB_PATH}) → safe.
+     * - `git` resolves to the Apple shim → safe only when the Command Line
+     *   Tools / Xcode developer directory is actually configured.
+     */
+    private isMacGitSafeToExecute;
+    /**
+     * Resolve the `git` executable the same way the OS would when spawning it:
+     * the first executable named `git` across `PATH`. Pure filesystem lookup —
+     * it never executes anything, so it cannot trigger the macOS prompt.
+     *
+     * Returns the absolute candidate path, or undefined when none is found.
+     */
+    private resolveGitOnPath;
+    /**
+     * Whether the macOS Command Line Tools (or Xcode) developer directory is
+     * configured. Uses `xcode-select -p`, which prints the active developer
+     * directory or exits non-zero when the tools are absent — and crucially
+     * does NOT trigger the install dialog (only `xcode-select --install` or
+     * running a shim binary does).
+     */
+    private isCommandLineToolsInstalled;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/marketplaces/git-fallback-coordinator.d.ts

@@ -0,0 +1,42 @@
+import { Logger } from '../../../../../telemetry/lib/common/index.js';
+import { MarketplaceSource } from '../plugin-protocol.js';
+import { GitAvailabilityDetector } from './git-availability-detector.js';
+import { GitToZipUrlConverter } from './git-to-zip-url-converter.js';
+/**
+ * Facade that decides whether a Git/Github marketplace source should be
+ * silently rewritten to a Zip source because the local `git` executable is
+ * not available.
+ *
+ * The rewrite is intentionally applied as early as possible in
+ * {@link PluginManagerImpl.addMarketplace} — before the marketplace info is
+ * persisted to disk — so that the on-disk state reflects the actual install
+ * method. This keeps subsequent `updateMarketplace`, autoUpdate and startup
+ * load paths on the Zip code path without requiring any per-path patches.
+ *
+ * See `apps/workbuddy-desktop/docs/refactor/marketplace/09-git-to-zip-fallback-design.md`
+ * for the full design.
+ */
+export declare class GitFallbackCoordinator {
+    protected readonly logger: Logger;
+    protected readonly detector: GitAvailabilityDetector;
+    protected readonly converter: GitToZipUrlConverter;
+    /**
+     * When the input is a Git/Github source and the local git is unavailable,
+     * return a new Zip source targeting the platform's archive URL. Otherwise
+     * return the input unchanged.
+     *
+     * Warnings are emitted (but no error is thrown) when git is unavailable
+     * but no conversion is possible; the original source is returned so the
+     * subsequent Git install can surface its native error message to the user.
+     *
+     * @param src Source produced by {@link PluginManagerImpl.parseSource}.
+     * @param displayName Optional marketplace name used only for logging.
+     */
+    maybeFallback(src: MarketplaceSource, displayName?: string): Promise<MarketplaceSource>;
+    /**
+     * Extract a usable reference string from a Git/Github source. Prefers
+     * the most explicit form (`url`) and falls back through `path` and
+     * `repo` shorthand.
+     */
+    private extractUrl;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/marketplaces/git-to-zip-url-converter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A single platform's rule for translating a Git repository URL to a ZIP
+ * download URL. Rules are matched by hostname and applied in registration
+ * order (newest first, see {@link GitToZipUrlConverter.registerRule}).
+ */
+export interface GitPlatformRule {
+    /** Human-readable rule identifier, used in logs and tests. */
+    readonly name: string;
+    /** Return true when this rule applies to the given lower-cased hostname. */
+    match(hostname: string): boolean;
+    /**
+     * Build the ZIP download URL.
+     *
+     * @param host Host with optional port, as returned by `URL#host`.
+     * @param pathname Repository pathname with leading `/` and no trailing `/`.
+     */
+    convert(host: string, pathname: string): string;
+}
+/**
+ * Converts Git-style references (http(s) URLs, SSH URLs, or `owner/repo`
+ * shorthand) into archive download URLs understood by {@link ZipMarketplace}.
+ *
+ * Rule set is intentionally aligned with the reference table in
+ * `packages/agent-craft/src/common/plugin/plugin-manager.ts` so the two
+ * implementations stay behaviour-compatible.
+ *
+ * The converter does not know whether git is available; that decision is
+ * made by {@link GitFallbackCoordinator}.
+ */
+export declare class GitToZipUrlConverter {
+    private readonly rules;
+    /**
+     * Register an additional rule. Newer rules take precedence over built-ins
+     * so callers can override default behaviour for a specific host.
+     */
+    registerRule(rule: GitPlatformRule): void;
+    /**
+     * Convert a Git reference to a ZIP archive URL.
+     *
+     * Accepts:
+     * - `https://host/owner/repo` / `https://host/owner/repo.git`
+     * - `git@host:owner/repo(.git)?`
+     * - `owner/repo` shorthand (assumed to be GitHub)
+     *
+     * Returns `undefined` when the host is not recognised or the input is
+     * not parseable as any of the accepted forms.
+     */
+    convert(input: string): string | undefined;
+    private normaliseToHttpUrl;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/marketplaces/github-marketplace.d.ts

@@ -0,0 +1,41 @@
+import { ProgressCallback } from '../plugin-protocol.js';
+import { DirectoryMarketplace } from './directory-marketplace.js';
+/**
+ * GitHub类型的市场实现类
+ */
+export declare class GithubMarketplace extends DirectoryMarketplace {
+    /**
+     * 安装或更新GitHub仓库到本地
+     */
+    install(onProgress?: ProgressCallback): Promise<void>;
+    /**
+     * clone 完成后根据 marketplace.json 里的 name rename 目录。
+     *
+     * 不复用 HttpMarketplace 的 tempLocation 预建方式：Git marketplace 的 manifest
+     * 是随 clone 一并下来的，install 开始时读不到 —— 因此只能在 update() 之后回头调整。
+     *
+     * rename 失败不抛异常：clone 已成功，稳住旧目录名仍可继续工作，由上层的
+     * known_marketplaces.json 记录 installLocation 做后续定位。
+     * 不安全的 manifest.name（路径穿越）忽略，同样保留 slug 目录 (#71947)。
+     */
+    private renameToManifestName;
+    /**
+     * 读取 installLocation 下的 marketplace.json 获取 name 字段
+     * 遍历所有支持的 metadata 目录（.codebuddy-plugin / .claude-plugin）
+     */
+    private readManifestName;
+    private readMarketplaceManifest;
+    update(onProgress?: ProgressCallback): Promise<boolean>;
+    private readRepoState;
+    /**
+     * 克隆Git仓库
+     * clone 失败时清理残留目录，避免后续 update 误判为已有仓库
+     */
+    private cloneRepo;
+    private swapDirectoryFromStaging;
+    /**
+     * 获取Git URL
+     * 从source中提取Git仓库地址
+     */
+    private getGitUrl;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/marketplaces/http-marketplace.d.ts

@@ -0,0 +1,47 @@
+import { ProgressCallback } from '../plugin-protocol.js';
+import { DirectoryMarketplace } from './directory-marketplace.js';
+/**
+ * HTTP类型的市场实现类
+ */
+export declare class HttpMarketplace extends DirectoryMarketplace {
+    /** 上次成功命中的远端元数据目录，用于后续插件探测时优先尝试 */
+    private detectedMetaDir?;
+    /**
+     * 安装或更新HTTP市场到本地
+     * HTTP市场需要下载marketplace.json和所有插件的plugin.json到本地缓存
+     */
+    install(onProgress?: ProgressCallback): Promise<void>;
+    /**
+     * 更新HTTP市场
+     * 重新下载marketplace.json和插件信息
+     */
+    update(onProgress?: ProgressCallback): Promise<boolean>;
+    /**
+     * 获取marketplace.json内容
+     */
+    private fetchManifest;
+    /**
+     * 下载marketplace.json到本地
+     */
+    private downloadManifest;
+    private downloadPluginManifest;
+    private fetchJson;
+    /** Compare complete metadata snapshots so a successful no-op refresh stays idempotent. */
+    private haveSameSnapshot;
+    private readSnapshotFiles;
+    /**
+     * 根据URL生成临时名称（用于初始下载）
+     */
+    private generateNameFromUrl;
+    /**
+     * 获取HTTP URL
+     * 从source中提取HTTP地址，source.url实际指向marketplace.json
+     */
+    private getHttpUrl;
+    /**
+     * 构建完整URL
+     */
+    private buildUrl;
+    private swapDirectoryFromStaging;
+    private safeRemove;
+}

package/cli/dist-server/types/workspace/cbc-plugins/lib/node/plugins/marketplaces/index.d.ts

@@ -0,0 +1,13 @@
+export * from './base-marketplace.js';
+export * from './directory-marketplace.js';
+export * from './github-marketplace.js';
+export * from './http-marketplace.js';
+export * from './zip-marketplace.js';
+export * from './marketplace-factory.js';
+export * from './marketplace-storage.js';
+export * from './marketplace-config-manager.js';
+export * from './marketplace-update-checker.js';
+export * from './builtin-marketplace-provider.js';
+export * from './git-availability-detector.js';
+export * from './git-to-zip-url-converter.js';
+export * from './git-fallback-coordinator.js';