@webskill/sdk 0.7.0 → 0.8.0

package/dist/agent.d.ts

@@ -1,2 +1,2 @@
-import { $ as TodoListener, A as PagePerceptionReader, B as SKILL_GENERATION_SYSTEM_PROMPT, C as PageActionRequest, D as PageAuditSink, E as PageActionUi, F as PerceptionAuditSink, G as SkillGenerator, H as SkillGenerationOutcome, I as PerceptionCaptureOptions, J as SubAgentRunner, K as SkillGeneratorOptions, L as PerceptionRecord, M as ParentBudget, N as PerceivedImage, O as PagePerceptionPolicy, P as PerceivedNode, Q as TodoList, R as PerceptionResult, S as PageActionRecord, T as PageActionToolSourceOptions, U as SkillGenerationPolicy, V as SkillCandidateSink, W as SkillGenerationToolSourceOptions, X as TodoEvent, Y as TODO_SYSTEM_PROMPT, Z as TodoItem, _ as PageActionExecutor, a as DelegationOrchestratorOptions, at as createPagePerceptionToolSource, b as PageActionPolicy, c as DelegationToolSourceOptions, ct as withDelegationOrigin, d as ImageCaptureBudget, et as TodoStatus, f as MANAGE_TODO_TOOL, g as PERCEPTION_SYSTEM_PROMPT, h as PERCEIVE_PAGE_TOOL, i as DelegationOrchestrator, it as createPageActionToolSource, j as PagePerceptionToolSourceOptions, k as PagePerceptionPolicyOptions, l as GENERATE_SKILL_TOOL, m as PAGE_ACTION_TOOL, n as DELEGATION_SYSTEM_PROMPT, nt as TodoToolSourceOptions, o as DelegationRequest, ot as createSkillGenerationToolSource, p as PAGE_ACTION_SYSTEM_PROMPT, q as SubAgentRunInput, r as DelegationBudget, rt as createDelegationToolSource, s as DelegationResult, st as createTodoToolSource, t as DELEGATE_TASK_TOOL, tt as TodoStore, u as GeneratedSkillDraft, v as PageActionKind, w as PageActionScope, x as PageActionPolicyOptions, y as PageActionOutcome, z as PerceptionScope } from "./index-Ba3xFtfz.js";
+import { $ as TodoListener, A as PagePerceptionReader, B as SKILL_GENERATION_SYSTEM_PROMPT, C as PageActionRequest, D as PageAuditSink, E as PageActionUi, F as PerceptionAuditSink, G as SkillGenerator, H as SkillGenerationOutcome, I as PerceptionCaptureOptions, J as SubAgentRunner, K as SkillGeneratorOptions, L as PerceptionRecord, M as ParentBudget, N as PerceivedImage, O as PagePerceptionPolicy, P as PerceivedNode, Q as TodoList, R as PerceptionResult, S as PageActionRecord, T as PageActionToolSourceOptions, U as SkillGenerationPolicy, V as SkillCandidateSink, W as SkillGenerationToolSourceOptions, X as TodoEvent, Y as TODO_SYSTEM_PROMPT, Z as TodoItem, _ as PageActionExecutor, a as DelegationOrchestratorOptions, at as createPagePerceptionToolSource, b as PageActionPolicy, c as DelegationToolSourceOptions, ct as withDelegationOrigin, d as ImageCaptureBudget, et as TodoStatus, f as MANAGE_TODO_TOOL, g as PERCEPTION_SYSTEM_PROMPT, h as PERCEIVE_PAGE_TOOL, i as DelegationOrchestrator, it as createPageActionToolSource, j as PagePerceptionToolSourceOptions, k as PagePerceptionPolicyOptions, l as GENERATE_SKILL_TOOL, m as PAGE_ACTION_TOOL, n as DELEGATION_SYSTEM_PROMPT, nt as TodoToolSourceOptions, o as DelegationRequest, ot as createSkillGenerationToolSource, p as PAGE_ACTION_SYSTEM_PROMPT, q as SubAgentRunInput, r as DelegationBudget, rt as createDelegationToolSource, s as DelegationResult, st as createTodoToolSource, t as DELEGATE_TASK_TOOL, tt as TodoStore, u as GeneratedSkillDraft, v as PageActionKind, w as PageActionScope, x as PageActionPolicyOptions, y as PageActionOutcome, z as PerceptionScope } from "./index-fLskQfAS.js";
 export { DELEGATE_TASK_TOOL, DELEGATION_SYSTEM_PROMPT, type DelegationBudget, DelegationOrchestrator, type DelegationOrchestratorOptions, type DelegationRequest, type DelegationResult, type DelegationToolSourceOptions, GENERATE_SKILL_TOOL, type GeneratedSkillDraft, type ImageCaptureBudget, MANAGE_TODO_TOOL, PAGE_ACTION_SYSTEM_PROMPT, PAGE_ACTION_TOOL, PERCEIVE_PAGE_TOOL, PERCEPTION_SYSTEM_PROMPT, type PageActionExecutor, type PageActionKind, type PageActionOutcome, PageActionPolicy, type PageActionPolicyOptions, type PageActionRecord, type PageActionRequest, type PageActionScope, type PageActionToolSourceOptions, type PageActionUi, type PageAuditSink, PagePerceptionPolicy, type PagePerceptionPolicyOptions, type PagePerceptionReader, type PagePerceptionToolSourceOptions, type ParentBudget, type PerceivedImage, type PerceivedNode, type PerceptionAuditSink, type PerceptionCaptureOptions, type PerceptionRecord, type PerceptionResult, type PerceptionScope, SKILL_GENERATION_SYSTEM_PROMPT, type SkillCandidateSink, type SkillGenerationOutcome, type SkillGenerationPolicy, type SkillGenerationToolSourceOptions, SkillGenerator, type SkillGeneratorOptions, type SubAgentRunInput, type SubAgentRunner, TODO_SYSTEM_PROMPT, type TodoEvent, type TodoItem, type TodoList, type TodoListener, type TodoStatus, TodoStore, type TodoToolSourceOptions, createDelegationToolSource, createPageActionToolSource, createPagePerceptionToolSource, createSkillGenerationToolSource, createTodoToolSource, withDelegationOrigin };

package/dist/agent.js

@@ -1,4 +1,4 @@
-import { A as parseSkillMarkdown, O as messageOf, T as isValidSkillName, m as WebSkillError } from "./dist-8oQRa8Xz.js";
+import { A as messageOf, D as isValidSkillName, M as parseSkillMarkdown, m as WebSkillError } from "./dist-59XlqDuv.js";
 
 //#region ../agent/dist/index.js
 const STATUSES = [

package/dist/browser.d.ts

@@ -1,6 +1,6 @@
-import { A as ArchiveLimits, F as FileStat, I as FileSystemProvider, _ as MemoryStore, _t as UnsignedPolicy, bt as WebSkillError, c as InteractionResponse, ht as TrustedKeyStore, l as LlmClient, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, pt as SkillsLockfile, rt as SkillInstallSource, s as InteractionRequest, st as SkillManifest, u as LlmCompleteInput, x as UiBridge, y as RenderResultRequest, yt as VerifyResult } from "./types-CcxRLdJG-DCXyw1US.js";
-import { Et as ScriptExecutor, Fn as parseBridgeRequest, Kt as ToolResult, O as ExternalSkillProvider, Tt as ScriptExecutionContext, Wt as ToolDefinition, Y as NetworkPolicy, _ as BridgeCapabilities, b as BridgeResponse, cn as WebSkillApi, f as ApprovalScope, k as ExternalToolSource, pn as bridgeError, y as BridgeRequest } from "./index-DkbABR43.js";
-import { A as PagePerceptionReader, C as PageActionRequest, I as PerceptionCaptureOptions, P as PerceivedNode, R as PerceptionResult, _ as PageActionExecutor, w as PageActionScope, y as PageActionOutcome, z as PerceptionScope } from "./index-Ba3xFtfz.js";
+import { A as ArchiveLimits, F as FileStat, I as FileSystemProvider, St as WebSkillError, _ as MemoryStore, _t as TrustedKeyStore, at as SkillInstallSource, c as InteractionResponse, ht as SkillsLockfile, l as LlmClient, lt as SkillManifest, m as LlmStreamEvent, o as InteractionPolicy, p as LlmResponse, s as InteractionRequest, u as LlmCompleteInput, x as UiBridge, xt as VerifyResult, y as RenderResultRequest, yt as UnsignedPolicy } from "./types-B3n0cMZu-BdcqQ35O.js";
+import { Et as ScriptExecutor, O as ExternalSkillProvider, Tt as ScriptExecutionContext, Vn as parseBridgeRequest, Y as NetworkPolicy, Yt as ToolResult, _ as BridgeCapabilities, _n as bridgeError, b as BridgeResponse, f as ApprovalScope, fn as WebSkillApi, k as ExternalToolSource, qt as ToolDefinition, y as BridgeRequest } from "./index-K-eewlGL.js";
+import { A as PagePerceptionReader, C as PageActionRequest, I as PerceptionCaptureOptions, O as PagePerceptionPolicy, P as PerceivedNode, R as PerceptionResult, _ as PageActionExecutor, w as PageActionScope, y as PageActionOutcome, z as PerceptionScope } from "./index-fLskQfAS.js";
 //#region ../browser/dist/index.d.ts
 //#region src/fs/featureDetection.d.ts
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -86,6 +86,11 @@ declare class BrowserSkillManager {
   constructor(deps: {
     fs: FileSystemProvider;
     managedRoot: string;
+    /**
+     * 宿主的只读技能根（如 `/skills`）。Library 列的是 Catalog 全集，
+     * 不告诉管理器这些根，导出本地技能会报「is not installed」（FR-19.5）。
+     */
+    skillRoots?: readonly string[];
     fetchImpl?: typeof fetch;
     /** 归档体积三重上限（缺省 DEFAULT_ARCHIVE_LIMITS） */
     archiveLimits?: ArchiveLimits;
@@ -111,6 +116,8 @@ declare class BrowserSkillManager {
   });
   install(source: SkillInstallSource, options?: {
     expectedSha256?: string;
+    /** 缺省接受替换（升级/重装靠它）；`reject` 供「新建」这类不该覆盖的调用方声明意图 */
+    replace?: 'allow' | 'reject';
   }): Promise<SkillManifest>;
   /**
    * 浏览器导出（单技能与包集同构：始终产出含 webskill.skill-pack.json 的 zip 字节，
@@ -120,6 +127,12 @@ declare class BrowserSkillManager {
   uninstall(name: string): Promise<void>;
   verifyIntegrity(name: string): Promise<VerifyResult>;
   listInstalled(): Promise<SkillsLockfile>;
+  /**
+   * 库里已有的技能名：managed 目录 + 宿主声明的只读根。读失败按「库为空」处理，不阻断安装。
+   * 与 `listInstalled()` 的区别是**含本地技能**（后者只看安装账本）。
+   * @experimental
+   */
+  listSkillNames(): Promise<string[]>;
 }
 //#endregion
 //#region src/skillManagement/zipExtract.d.ts
@@ -643,4 +656,138 @@ declare function openMemoryEncryptionKey(name?: string): Promise<CryptoKey>;
 /** 删除本地数据加密密钥；清除画像与记录时一并调用，避免留下解不开的旧密文 @experimental */
 declare function deleteMemoryEncryptionKey(name?: string): Promise<void>;
 //#endregion
-export { type BridgeCapabilities, type BridgeRequest, type BridgeResponse, BrowserSkillManager, BrowserWorkerScriptExecutor, type CaptureFailure, type CaptureLevel, type CapturedImage, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type CompressResult, type ConfiguredLlmClient, type DictationAvailability, type DictationOptions, type DictationSession, type DomPageActionExecutor, type DomPageActionOptions, type DomPerceptionReader, type DomPerceptionReaderOptions, IframeWorkerLike, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, OpfsProvider, type SandboxMode, type SerializedError, TsTranspiler, type TypeScriptSupportOptions, WORKER_BOOTSTRAP_SOURCE, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractZipWeb, generateMemoryEncryptionKey, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };
+//#region src/host/portMatrix.d.ts
+/**
+ * 浏览器宿主装配（分册 17）。
+ *
+ * 本子路径**刻意不 import** `ChatbotHostAdapter` / `ConsoleBackend` / `ConnectFacade`：
+ * 它们分别在 `@webskill/chatbot` 与 `@webskill/console`，而 sdk 依赖不到那两个包
+ * （反过来让 sdk 依赖 app 包会把依赖方向倒过来，见偏差 D-18）。
+ * 这里只声明**结构等价**的形状，靠 TS 的结构类型系统在宿主侧自动对上。
+ *
+ * 代价是结构等价靠手工维持：上游接口加了必填字段而这里没跟，
+ * 只有宿主赋值时才会报错。因此配了一条测试侧的真实赋值断言（T-17-A），
+ * 那条判据是本方案成立的前提，不是可选项。
+ */
+/**
+ * 端口矩阵覆盖的宿主面。
+ * `chatbot-config` 与 `chatbot-adapter` 分开：两者是不同的接口（`ChatbotConfig` / `ChatbotHostAdapter`），
+ * 把它们归成一面会让探测去错误的对象上找字段，永远报 missing。
+ */
+type HostSurface = 'chatbot-adapter' | 'chatbot-config' | 'console-backend' | 'connect-facade';
+/** 本版只区分浏览器与 Node：矩阵要能表达「tar 在 node 上是应有的」，否则 not-applicable 会变成无条件结论 */
+type HostKind = 'browser' | 'node';
+type PortApplicability = 'expected' | 'not-applicable';
+interface PortSpec {
+  id: string;
+  surface: HostSurface;
+  /** 在该 surface 上探测的字段名 */
+  key: string;
+  applicability: Readonly<Record<HostKind, PortApplicability>>;
+  /** `not-applicable` 时是原因，`expected` 时是接入指引 */
+  note: string;
+}
+/**
+ * 端口 × 宿主类型的**唯一定义**（AC-17.4）。
+ * About 页与装配工厂都读这一份；护栏 `port-matrix-single-source` 盯着不许再抄。
+ */
+declare const HOST_PORT_MATRIX: readonly PortSpec[];
+/**
+ * 第四态 `unknown` 表示「这个 surface 没交给我看」，不是「没接」。
+ * About 页拿不到 `ChatbotHostAdapter` 实例（console 不依赖 chatbot），
+ * 只能自检两个面——把没看到的报成「未接线」是错的说法。
+ */
+type PortStatus = 'wired' | 'missing' | 'not-applicable' | 'unknown';
+interface PortReport extends PortSpec {
+  status: PortStatus;
+}
+interface InspectHostWiringInput {
+  kind?: HostKind;
+  /** 只对提供了的 surface 出结论；未提供的整面记为 `unknown` */
+  surfaces: Partial<Record<HostSurface, Record<string, unknown> | undefined>>;
+}
+declare function inspectHostWiring(input: InspectHostWiringInput): PortReport[];
+/** 缺口 = 该接却没接的项；`unknown` 不算缺口，没看到不等于没接 */
+declare function missingPorts(reports: readonly PortReport[]): PortReport[];
+//#endregion
+//#region src/host/createBrowserChatbotHost.d.ts
+/**
+ * 浏览器宿主装配工厂（分册 17 FR-17.1 / 偏差 D-18）。
+ *
+ * 三个目标接口分属 chatbot 与 console，sdk 依赖不到它们；反过来让 sdk 依赖 app 包
+ * 会倒转依赖方向，让 chatbot 依赖 console 又违反 FR-20.5。所以这里只声明**结构等价**的形状，
+ * 宿主侧 `const a: ChatbotHostAdapter = bundle.chatbotAdapter` 靠结构类型自动成立。
+ *
+ * 结构等价是**手工维持**的——上游加必填字段这里不会红，只有宿主赋值时才报错。
+ * `packages/browser/test/hostAssembly.test.ts` 里做了真实赋值（T-17-A），
+ * 那条判据是本方案成立的前提。
+ */
+/**
+ * 与 `ChatbotHostAdapter` 结构等价的最小形状。
+ *
+ * `navigation` 是**必填**：跳 console 是宿主的路由决定，工厂造不出合理缺省。
+ * `skillCandidates` **不在这里**——它长在 `ChatbotConfig` 上，不是 adapter 的字段。
+ */
+interface HostChatbotAdapterShape {
+  storage: FileSystemProvider;
+  skillRoots: string[];
+  navigation: HostNavigationShape;
+  skillManager: BrowserSkillManager;
+  pagePerception?: PagePerceptionPolicy;
+}
+/** 与 `ChatbotHostAdapter['navigation']` 结构等价 */
+interface HostNavigationShape {
+  openConsole(): void;
+  openConsoleTrace?(runId: string): void;
+  openConsoleCandidate?(candidateId: string): void;
+}
+/** 与 `ConsoleBackend` 结构等价的最小形状 */
+interface HostConsoleBackendShape {
+  catalog(): Promise<unknown>;
+  install?: unknown;
+  exportSkill?: unknown;
+  exportSkillTar?: unknown;
+  verifyIntegrity?: unknown;
+  writeSkillFile?: unknown;
+  listVersions?: unknown;
+  runs?: unknown;
+  sessions?: unknown;
+}
+/** 与 `ConnectFacade` 结构等价的最小形状 */
+interface HostConnectFacadeShape {
+  listEndpoints(): Promise<unknown[]>;
+  listTools(): Promise<unknown[]>;
+  temporarySkills?: unknown;
+}
+interface BrowserHostBundle {
+  readonly chatbotAdapter: HostChatbotAdapterShape;
+  readonly consoleBackend: HostConsoleBackendShape;
+  readonly connectFacade: HostConnectFacadeShape;
+}
+/**
+ * 逃生口（FR-17.1 硬要求）：任一件都可替换，其余仍由工厂提供。
+ * 没有它，宿主会绕过工厂自建全套装配——那等于工厂没做。
+ */
+interface BrowserHostOverrides {
+  chatbotAdapter?: HostChatbotAdapterShape;
+  consoleBackend?: HostConsoleBackendShape;
+  connectFacade?: HostConnectFacadeShape;
+}
+interface BrowserHostOptions {
+  /** 必填：没有合理默认值 */
+  fs: FileSystemProvider;
+  /** 受管技能目录（安装 / 回滚的作用点） */
+  managedRoot: string;
+  /** 只读技能根；本地技能从这里被发现 */
+  skillRoots: string[];
+  /** 必填：跳 console 是宿主的路由，工厂无从缺省 */
+  navigation: HostNavigationShape;
+  /** opt-in 的能力保持可选：强制必填只会逼宿主传 undefined，把类型检查变成形式 */
+  pagePerception?: PagePerceptionPolicy;
+  consoleBackend?: HostConsoleBackendShape;
+  connectFacade?: HostConnectFacadeShape;
+  overrides?: BrowserHostOverrides;
+}
+declare function createBrowserChatbotHost(options: BrowserHostOptions): BrowserHostBundle;
+//#endregion
+export { type BridgeCapabilities, type BridgeRequest, type BridgeResponse, type BrowserHostBundle, type BrowserHostOptions, type BrowserHostOverrides, BrowserSkillManager, BrowserWorkerScriptExecutor, type CaptureFailure, type CaptureLevel, type CapturedImage, type ChromeBuiltinAvailability, ChromeBuiltinLlmClient, type CompressResult, type ConfiguredLlmClient, type DictationAvailability, type DictationOptions, type DictationSession, type DomPageActionExecutor, type DomPageActionOptions, type DomPerceptionReader, type DomPerceptionReaderOptions, HOST_PORT_MATRIX, type HostChatbotAdapterShape, type HostConnectFacadeShape, type HostConsoleBackendShape, type HostKind, type HostSurface, IframeWorkerLike, type InspectHostWiringInput, type LlmClientConfig, type LlmEntryConfig, type MainToWorkerMessage, OpfsProvider, type PortApplicability, type PortReport, type PortSpec, type PortStatus, type SandboxMode, type SerializedError, TsTranspiler, type TypeScriptSupportOptions, WORKER_BOOTSTRAP_SOURCE, type WorkerEvent, type WorkerFactory, type WorkerLike, type WorkerRequest, WorkerRuntimeClient, type WorkerRuntimeClientDeps, type WorkerRuntimeHostOverrides, type WorkerScopeLike, WorkerUiBridge, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };

package/dist/browser.js

@@ -1,6 +1,6 @@
-import { A as parseSkillMarkdown, B as unzipWithLimits, H as verifyManifest, L as resolveInsideRoot, M as readResponseWithLimit, N as readSkillSignature, O as messageOf, T as isValidSkillName, U as verifySkillSignature, V as validateSkills, _ as atomicWriteText, f as SkillDiscovery, h as assertRemoteUrlAllowed, j as parseSkillPackManifest, m as WebSkillError, o as SKILLS_LOCKFILE, r as MANIFEST_EXCLUDED_FILES, s as SKILL_MANIFEST_FILE, u as SKILL_PACK_FILE, v as buildCatalog, w as exportSkills, y as buildManifest } from "./dist-8oQRa8Xz.js";
-import { B as bridgeError, C as ProgressiveRouter, S as OpenAiCompatibleClient, U as createWebSkillApi, a as AgentLoop, b as GoogleGenAiClient, c as CapabilityApproval, ct as normalizeToolError, g as FsRunSnapshotStore, h as FsMemoryStore, it as networkPolicyLibSource, lt as parseBridgeRequest, m as FsArtifactStore, nt as mergeCatalogEntries, o as AnthropicClient, st as normalizeToolContent } from "./dist-D0qW6e40.js";
-import { n as MockLlmClient } from "./testing-CYTFqkDm.js";
+import { A as messageOf, D as isValidSkillName, E as exportSkills, F as readSkillSignature, G as verifyManifest, K as verifySkillSignature, M as parseSkillMarkdown, N as parseSkillPackManifest, P as readResponseWithLimit, U as unzipWithLimits, W as validateSkills, _ as atomicWriteText, f as SkillDiscovery, h as assertRemoteUrlAllowed, m as WebSkillError, o as SKILLS_LOCKFILE, r as MANIFEST_EXCLUDED_FILES, s as SKILL_MANIFEST_FILE, u as SKILL_PACK_FILE, v as buildCatalog, w as detectSkillArchiveShapeFromFs, y as buildManifest, z as resolveInsideRoot } from "./dist-59XlqDuv.js";
+import { B as bridgeError, C as ProgressiveRouter, S as OpenAiCompatibleClient, U as createWebSkillApi, a as AgentLoop, b as GoogleGenAiClient, c as CapabilityApproval, dt as parseBridgeRequest, g as FsRunSnapshotStore, h as FsMemoryStore, it as mergeCatalogEntries, lt as normalizeToolContent, m as FsArtifactStore, o as AnthropicClient, ot as networkPolicyLibSource, ut as normalizeToolError } from "./dist-DmI5SBBF.js";
+import { n as MockLlmClient } from "./testing-BCUO5gZR.js";
 
 //#region ../browser/dist/index.js
 /** 检测当前环境是否可用 OPFS（navigator.storage.getDirectory） */
@@ -490,7 +490,8 @@ const PRESERVED_INSTALL_CODES = /* @__PURE__ */ new Set([
 	"SIGNATURE_MALFORMED",
 	"SIGNATURE_UNTRUSTED_KEY",
 	"SIGNATURE_MISMATCH",
-	"SIGNATURE_UNSUPPORTED"
+	"SIGNATURE_UNSUPPORTED",
+	"SKILL_DUPLICATE_NAME"
 ]);
 const asInstallFailed = (e) => e instanceof WebSkillError && (e.code === "INSTALL_FAILED" || e.code === "TOOL_UNSUPPORTED" || PRESERVED_INSTALL_CODES.has(e.code)) ? e : new WebSkillError("INSTALL_FAILED", `Install failed: ${messageOf(e)}`, e);
 const lockfilePath = (root) => `${root}/${SKILLS_LOCKFILE}`;
@@ -510,6 +511,8 @@ const EMPTY_TRUSTED_KEYS = {
 var BrowserSkillManager = class {
 	#fs;
 	#managedRoot;
+	/** 只读技能根（宿主自带的本地技能）：参与导出与依赖存在性判定，但不可卸载 */
+	#skillRoots;
 	#fetchImpl;
 	#archiveLimits;
 	#onChanged;
@@ -519,6 +522,7 @@ var BrowserSkillManager = class {
 	constructor(deps) {
 		this.#fs = deps.fs;
 		this.#managedRoot = deps.managedRoot.replace(/\/+$/, "");
+		this.#skillRoots = (deps.skillRoots ?? []).map((root) => root.replace(/\/+$/, ""));
 		this.#fetchImpl = deps.fetchImpl;
 		this.#archiveLimits = deps.archiveLimits;
 		this.#onChanged = deps.onChanged;
@@ -572,17 +576,16 @@ var BrowserSkillManager = class {
 			const contentDir = `${stagingRoot}/content`;
 			await fs.mkdir(contentDir);
 			await extractZipWeb(fs, data, contentDir, this.#archiveLimits);
-			const packFilePath = `${contentDir}/${SKILL_PACK_FILE}`;
-			if (await fs.exists(packFilePath)) return (await this.#installPack({
-				contentDir,
-				manifest: parseSkillPackManifest(await fs.readText(packFilePath))
-			}, source, stagingRoot))[0];
-			let skillDir = contentDir;
-			if (!await fs.exists(`${contentDir}/SKILL.md`)) {
-				const dirs = (await fs.list(contentDir)).filter((e) => e.type === "directory");
-				if (dirs.length === 1 && await fs.exists(`${dirs[0]?.path}/SKILL.md`)) skillDir = dirs[0].path;
-				else throw new WebSkillError("INSTALL_FAILED", "Archive does not contain a SKILL.md at its root or in a single top-level directory");
+			const detection = await detectSkillArchiveShapeFromFs(fs, contentDir);
+			if (detection.shape === "invalid") throw new WebSkillError("INSTALL_FAILED", detection.reason ?? "Archive layout is not recognised");
+			if (detection.shape === "pack-set") {
+				const packRoot = detection.rootDir === void 0 ? contentDir : `${contentDir}/${detection.rootDir}`;
+				return (await this.#installPack({
+					contentDir: packRoot,
+					manifest: parseSkillPackManifest(await fs.readText(`${packRoot}/${SKILL_PACK_FILE}`))
+				}, source, stagingRoot))[0];
 			}
+			const skillDir = detection.rootDir === void 0 ? contentDir : `${contentDir}/${detection.rootDir}`;
 			let name;
 			let version;
 			try {
@@ -593,13 +596,18 @@ var BrowserSkillManager = class {
 				throw new WebSkillError("INSTALL_FAILED", `Failed to read skill name from SKILL.md: ${messageOf(e)}`, e);
 			}
 			if (!isValidSkillName(name)) throw new WebSkillError("INSTALL_FAILED", `Invalid skill name in SKILL.md (path traversal rejected): ${JSON.stringify(name)}`);
+			if (options?.replace === "reject" && await fs.exists(`${this.#managedRoot}/${name}`)) throw new WebSkillError("SKILL_DUPLICATE_NAME", `A skill named "${name}" is already installed. Installing it again replaces the existing files; use the packages flow if that is intended.`);
 			const finalRoot = `${stagingRoot}/final`;
 			const finalDir = `${finalRoot}/${name}`;
 			await copyDir(fs, skillDir, finalDir);
-			const report = await validateSkills(fs, [finalRoot]);
+			const report = await validateSkills(fs, [finalRoot], { extraKnownSkillNames: await this.listSkillNames() });
 			if (!report.ok) {
-				const errors = report.issues.filter((i) => i.severity === "error");
-				throw new WebSkillError("INSTALL_FAILED", `Skill "${name}" failed validation: ${errors.map((i) => i.message).join("; ")}`, errors);
+				const errors = report.issues.filter((i) => i.severity === "error" && i.code !== "SKILL_UNKNOWN_DEPENDENCY");
+				for (const issue of report.issues) if (issue.code === "SKILL_UNKNOWN_DEPENDENCY") this.#onWarning?.({
+					skill: name,
+					message: issue.message
+				});
+				if (errors.length > 0) throw new WebSkillError("INSTALL_FAILED", `Skill "${name}" failed validation: ${errors.map((i) => i.message).join("; ")}`, errors);
 			}
 			const manifest = await this.#createManifest(finalDir, {
 				name,
@@ -714,6 +722,21 @@ var BrowserSkillManager = class {
 			throw asInstallFailed(e);
 		}
 	}
+	/** 技能的真实根：先 managed，再只读根。都没有则 undefined */
+	async #resolveSkillRoot(name) {
+		const managed = `${this.#managedRoot}/${name}`;
+		if (await this.#fs.exists(managed)) return {
+			root: managed,
+			managed: true
+		};
+		for (const base of this.#skillRoots) {
+			const candidate = `${base}/${name}`;
+			if (await this.#fs.exists(candidate)) return {
+				root: candidate,
+				managed: false
+			};
+		}
+	}
 	/**
 	* 浏览器导出（单技能与包集同构：始终产出含 webskill.skill-pack.json 的 zip 字节，
 	* 统一安装路径；保存/下载由应用层处理）。
@@ -721,11 +744,13 @@ var BrowserSkillManager = class {
 	async exportArchive(names) {
 		const list = Array.isArray(names) ? names : [names];
 		if (list.length === 0) throw new WebSkillError("EXPORT_FAILED", "exportArchive requires at least one skill name");
-		const roots = list.map((name) => {
+		const roots = [];
+		for (const name of list) {
 			if (!isValidSkillName(name)) throw new WebSkillError("EXPORT_FAILED", `Invalid skill name (path traversal rejected): ${JSON.stringify(name)}`);
-			return `${this.#managedRoot}/${name}`;
-		});
-		for (const [index, root] of roots.entries()) if (!await this.#fs.exists(root)) throw new WebSkillError("EXPORT_FAILED", `Skill "${list[index]}" is not installed`);
+			const resolved = await this.#resolveSkillRoot(name);
+			if (resolved === void 0) throw new WebSkillError("EXPORT_FAILED", `Skill "${name}" is not installed`);
+			roots.push(resolved.root);
+		}
 		return exportSkills(this.#fs, {
 			roots,
 			manifestBuilder: (root) => this.#readManifest(root)
@@ -733,8 +758,10 @@ var BrowserSkillManager = class {
 	}
 	async uninstall(name) {
 		if (!isValidSkillName(name)) throw new WebSkillError("UNINSTALL_FAILED", `Invalid skill name (path traversal rejected): ${JSON.stringify(name)}`);
-		const targetDir = `${this.#managedRoot}/${name}`;
-		if (!await this.#fs.exists(targetDir)) throw new WebSkillError("UNINSTALL_FAILED", `Skill "${name}" is not installed`);
+		const resolved = await this.#resolveSkillRoot(name);
+		if (resolved === void 0) throw new WebSkillError("UNINSTALL_FAILED", `Skill "${name}" is not installed`);
+		if (!resolved.managed) throw new WebSkillError("UNINSTALL_FAILED", `Skill "${name}" ships with the host application and is not managed by the skill manager; remove it from the host's skill root instead.`);
+		const targetDir = resolved.root;
 		try {
 			await this.#fs.remove(targetDir, { recursive: true });
 			await this.#removeLockEntry(name);
@@ -763,6 +790,22 @@ var BrowserSkillManager = class {
 			throw new WebSkillError("INTEGRITY_FAILED", `Skills lockfile at ${path} is corrupted: ${messageOf(e)}`, e);
 		}
 	}
+	/**
+	* 库里已有的技能名：managed 目录 + 宿主声明的只读根。读失败按「库为空」处理，不阻断安装。
+	* 与 `listInstalled()` 的区别是**含本地技能**（后者只看安装账本）。
+	* @experimental
+	*/
+	async listSkillNames() {
+		const names = [];
+		for (const root of [this.#managedRoot, ...this.#skillRoots]) {
+			if (!await this.#fs.exists(root).catch(() => false)) continue;
+			for (const stat of await this.#fs.list(root).catch(() => [])) {
+				const name = stat.path.split("/").pop() ?? "";
+				if (stat.type === "directory" && isValidSkillName(name)) names.push(name);
+			}
+		}
+		return names;
+	}
 	async #createManifest(skillRoot, input) {
 		const files = [];
 		for (const rel of (await listFiles(this.#fs, skillRoot)).sort()) {
@@ -787,7 +830,16 @@ var BrowserSkillManager = class {
 	}
 	async #readManifest(skillRoot) {
 		const path = `${skillRoot}/${SKILL_MANIFEST_FILE}`;
-		if (!await this.#fs.exists(path)) throw new WebSkillError("INTEGRITY_FAILED", `Skill manifest not found at ${path} (was the skill installed via BrowserSkillManager?)`);
+		if (!await this.#fs.exists(path)) {
+			const name = skillRoot.split("/").pop() ?? skillRoot;
+			return this.#createManifest(skillRoot, {
+				name,
+				source: {
+					type: "local",
+					path: skillRoot
+				}
+			});
+		}
 		try {
 			return JSON.parse(await this.#fs.readText(path));
 		} catch (e) {
@@ -2670,6 +2722,179 @@ async function deleteMemoryEncryptionKey(name = "user-profile") {
 		db.close();
 	}
 }
+/**
+* 端口 × 宿主类型的**唯一定义**（AC-17.4）。
+* About 页与装配工厂都读这一份；护栏 `port-matrix-single-source` 盯着不许再抄。
+*/
+const HOST_PORT_MATRIX = [
+	{
+		id: "install / uninstall",
+		surface: "console-backend",
+		key: "install",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.install to let the console install and remove skills."
+	},
+	{
+		id: "export (zip)",
+		surface: "console-backend",
+		key: "exportSkill",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.exportSkill to enable zip export."
+	},
+	{
+		id: "export (tar)",
+		surface: "console-backend",
+		key: "exportSkillTar",
+		applicability: {
+			browser: "not-applicable",
+			node: "expected"
+		},
+		note: "Browsers have no tar toolchain in the platform; zip export covers the same need."
+	},
+	{
+		id: "integrity",
+		surface: "console-backend",
+		key: "verifyIntegrity",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.verifyIntegrity to enable the integrity report."
+	},
+	{
+		id: "editing",
+		surface: "console-backend",
+		key: "writeSkillFile",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.writeSkillFile to enable in-place skill editing."
+	},
+	{
+		id: "versions",
+		surface: "console-backend",
+		key: "listVersions",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.listVersions to show version history and rollback."
+	},
+	{
+		id: "runs",
+		surface: "console-backend",
+		key: "runs",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.runs to read run history; without it the runs pages have no source."
+	},
+	{
+		id: "sessions",
+		surface: "console-backend",
+		key: "sessions",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConsoleBackend.sessions to list chat sessions."
+	},
+	{
+		id: "page perception",
+		surface: "chatbot-adapter",
+		key: "pagePerception",
+		applicability: {
+			browser: "expected",
+			node: "not-applicable"
+		},
+		note: "Page perception reads the live DOM; there is no page outside a browser."
+	},
+	{
+		id: "skill candidates",
+		surface: "chatbot-config",
+		key: "skillCandidates",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire skillCandidates so skill-miss suggestions can be reviewed in the console."
+	},
+	{
+		id: "remote endpoints",
+		surface: "connect-facade",
+		key: "listEndpoints",
+		applicability: {
+			browser: "expected",
+			node: "expected"
+		},
+		note: "Wire ConnectFacade.listEndpoints to manage remote MCP endpoints."
+	},
+	{
+		id: "page-declared skills",
+		surface: "connect-facade",
+		key: "temporarySkills",
+		applicability: {
+			browser: "expected",
+			node: "not-applicable"
+		},
+		note: "Page-declared temporary skills come from the document; Node hosts have none."
+	}
+];
+function inspectHostWiring(input) {
+	const kind = input.kind ?? "browser";
+	return HOST_PORT_MATRIX.map((spec) => {
+		if (!(spec.surface in input.surfaces)) return {
+			...spec,
+			status: "unknown"
+		};
+		if (spec.applicability[kind] === "not-applicable") return {
+			...spec,
+			status: "not-applicable"
+		};
+		const surface = input.surfaces[spec.surface];
+		const wired = surface !== void 0 && surface[spec.key] !== void 0;
+		return {
+			...spec,
+			status: wired ? "wired" : "missing"
+		};
+	});
+}
+/** 缺口 = 该接却没接的项；`unknown` 不算缺口，没看到不等于没接 */
+function missingPorts(reports) {
+	return reports.filter((report) => report.status === "missing");
+}
+function createBrowserChatbotHost(options) {
+	const { fs, managedRoot, skillRoots, navigation, overrides } = options;
+	const chatbotAdapter = {
+		storage: fs,
+		skillRoots,
+		navigation,
+		skillManager: new BrowserSkillManager({
+			fs,
+			managedRoot,
+			skillRoots
+		}),
+		...options.pagePerception !== void 0 ? { pagePerception: options.pagePerception } : {}
+	};
+	const consoleBackend = options.consoleBackend ?? { catalog: async () => ({ entries: [] }) };
+	const connectFacade = options.connectFacade ?? {
+		listEndpoints: async () => [],
+		listTools: async () => []
+	};
+	return {
+		chatbotAdapter: overrides?.chatbotAdapter ?? chatbotAdapter,
+		consoleBackend: overrides?.consoleBackend ?? consoleBackend,
+		connectFacade: overrides?.connectFacade ?? connectFacade
+	};
+}
 
 //#endregion
-export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, IframeWorkerLike, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractZipWeb, generateMemoryEncryptionKey, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };
+export { BrowserSkillManager, BrowserWorkerScriptExecutor, ChromeBuiltinLlmClient, HOST_PORT_MATRIX, IframeWorkerLike, OpfsProvider, TsTranspiler, WORKER_BOOTSTRAP_SOURCE, WorkerRuntimeClient, WorkerUiBridge, bridgeError, captureElementImage, checkDictationAvailability, compressImageToBudget, createBrowserChatbotHost, createDomPageActionExecutor, createDomPerceptionReader, createEncryptedMemoryStore, createIframeWorker, createLlmClient, deleteMemoryEncryptionKey, extractZipWeb, generateMemoryEncryptionKey, inspectHostWiring, installWebSkillNavigator, isCapturableElement, isCaptureFailure, isEncryptedMemoryValue, isOpfsAvailable, missingPorts, openMemoryEncryptionKey, parseBridgeRequest, parseMainMessage, parseWorkerEvent, probeChromeBuiltinAvailability, sha256HexWeb, startDictation, startWorkerRuntimeHost };