@webskill/sdk 0.5.0 → 0.7.0

package/dist/governance.js

@@ -1,5 +1,6 @@
 import { O as messageOf, T as isValidSkillName, g as assertSafePathSegment, m as WebSkillError } from "./dist-8oQRa8Xz.js";
-import { i as textParts, n as partsToText } from "./memoryArtifactStore-BtOeB_hm-tj3fC5ip.js";
+import { a as textParts, n as partsToText } from "./memoryArtifactStore-52Zn9npI-BMPYwvoy.js";
+import { n as AUDIT_EVENT_TYPE_LIST, t as AUDIT_EVENT_TYPES } from "./eventTypes-DjIQpt8Y-Bj3vghj4.js";
 
 //#region ../governance/dist/index.js
 const invalid = (message, details) => {
@@ -331,19 +332,32 @@ function canonical(event) {
 	});
 }
 /**
+* 同一进程内按审计文件路径共享的链式 mutex。
+* 跟着实例走不行：本类允许多实例指向同一个 root，而交错追加正是分叉的来源。
+*/
+const APPEND_LOCKS = /* @__PURE__ */ new Map();
+/**
 * JSONL 追加式审计日志（<managedRoot>/.webskill/audit.jsonl）：
-* 真追加（fs.appendText，不整读改写）+ lastHash 内存缓存（同实例不重读）。
+* 真追加（fs.appendText，不整读改写）+ lastHash 缓存（仅当文件字节数未变时可用）。
 * 语义：**tamper-evident, not tamper-proof**——verifyChain 能检出篡改/删除/换序，
 * 但不阻止有写权限者直接改写文件；更强保证需要签名信任体系（未排期）。
+*
+* **并发边界**：追加的串行化只在**同一进程内**成立（模块级 mutex）。
+* 跨进程 / 跨标签页靠的是「写前用 `stat().size` 重新确认链尾」：
+* 外部写入会改变字节数，后写者因此会重读链尾而不会分叉——
+* 除非两个进程落在同一个 stat/append 窗口内。真正的跨进程互斥需要文件锁，
+* `FileSystemProvider` 不提供，不在本版承诺范围。
 */
 var FsAuditLog = class {
 	#root;
 	#fs;
 	#now;
 	#createId;
-	/** lastHash 内存缓存（同实例内追加不重读文件） */
+	/** lastHash 内存缓存（仅当 #lastKnownSize 与当前文件字节数相等时才作数） */
 	#lastHash;
 	#lastHashSeeded = false;
+	/** 本实例最后一次写入后观察到的文件字节数 */
+	#lastKnownSize;
 	constructor(deps) {
 		this.#root = deps.root.replace(/\/+$/, "");
 		this.#fs = deps.fs;
@@ -354,8 +368,13 @@ var FsAuditLog = class {
 	async #seedLastHash() {
 		this.#lastHashSeeded = true;
 		const path = fileOf$1(this.#root);
-		if (!await this.#fs.exists(path)) return "GENESIS";
-		const lines = (await this.#fs.readText(path)).split("\n").filter((l) => l.trim() !== "");
+		if (!await this.#fs.exists(path)) {
+			this.#lastKnownSize = void 0;
+			return "GENESIS";
+		}
+		const text = await this.#fs.readText(path);
+		this.#lastKnownSize = await this.#fileSize();
+		const lines = text.split("\n").filter((l) => l.trim() !== "");
 		if (lines.length === 0) return "GENESIS";
 		try {
 			const last = JSON.parse(lines.at(-1));
@@ -364,21 +383,50 @@ var FsAuditLog = class {
 			throw new WebSkillError("GOVERNANCE_FAILED", `Audit log tail line at ${path} is corrupted; refusing to append (the chain must not silently restart)`, e);
 		}
 	}
+	/** 当前字节数；文件不存在、提供方不报 size 或 stat 抛错时统一返回 undefined */
+	async #fileSize() {
+		try {
+			return (await this.#fs.stat(fileOf$1(this.#root))).size;
+		} catch {
+			return;
+		}
+	}
+	/**
+	* 追加前解析链尾（FR-13.1）。
+	* 缓存只在「文件字节数与本实例上次写后一致」时才作数；
+	* 拿不到 size 就无条件重读——不把「大概没变」当正确性依据。
+	*/
+	async #resolvePrevHash() {
+		if (!this.#lastHashSeeded) return this.#seedLastHash();
+		const size = await this.#fileSize();
+		if (size === void 0 || size !== this.#lastKnownSize) return this.#seedLastHash();
+		return this.#lastHash;
+	}
+	/** 同一审计文件上的追加串行化（前一个失败也要继续排队） */
+	async #withAppendLock(work) {
+		const path = fileOf$1(this.#root);
+		const next = (APPEND_LOCKS.get(path) ?? Promise.resolve()).then(work, work);
+		APPEND_LOCKS.set(path, next.catch(() => void 0));
+		return next;
+	}
 	async append(event) {
-		const prevHash = this.#lastHashSeeded ? this.#lastHash : await this.#seedLastHash();
-		const full = {
-			id: event.id ?? this.#createId?.() ?? `audit-${Math.random().toString(36).slice(2, 10)}`,
-			ts: event.ts ?? this.#now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
-			type: event.type,
-			target: event.target,
-			...event.actor !== void 0 ? { actor: event.actor } : {},
-			...event.data !== void 0 ? { data: event.data } : {},
-			prevHash
-		};
-		full.hash = await sha256Hex$1(canonical(full));
-		await this.#fs.appendText(fileOf$1(this.#root), `${JSON.stringify(full)}\n`);
-		this.#lastHash = full.hash;
-		return full;
+		return this.#withAppendLock(async () => {
+			const prevHash = await this.#resolvePrevHash();
+			const full = {
+				id: event.id ?? this.#createId?.() ?? `audit-${Math.random().toString(36).slice(2, 10)}`,
+				ts: event.ts ?? this.#now?.() ?? (/* @__PURE__ */ new Date()).toISOString(),
+				type: event.type,
+				target: event.target,
+				...event.actor !== void 0 ? { actor: event.actor } : {},
+				...event.data !== void 0 ? { data: event.data } : {},
+				prevHash
+			};
+			full.hash = await sha256Hex$1(canonical(full));
+			await this.#fs.appendText(fileOf$1(this.#root), `${JSON.stringify(full)}\n`);
+			this.#lastHash = full.hash;
+			this.#lastKnownSize = await this.#fileSize();
+			return full;
+		});
 	}
 	/**
 	* 分页 + 筛选下推。整文件读仍在（JSONL 布局未改，备案 D25），
@@ -425,29 +473,47 @@ var FsAuditLog = class {
 		}
 		const start = Math.max(0, end - limit);
 		const items = [];
+		let broken;
 		for (const line of matched.slice(start, end)) {
 			const event = records[line];
-			await this.#assertChainAt(records, line, path);
+			const failure = await this.#chainFailureAt(records, line);
+			if (failure !== void 0) {
+				if (filter.tolerateBrokenChain !== true) throw new WebSkillError("GOVERNANCE_FAILED", `Audit chain is broken at line ${line} of ${path}: ${failure}`);
+				broken ??= {
+					at: line,
+					reason: failure
+				};
+				break;
+			}
 			items.push(event);
 		}
 		return {
 			items,
-			...start > 0 ? { nextCursor: String(start) } : {}
+			...start > 0 ? { nextCursor: String(start) } : {},
+			...broken !== void 0 ? {
+				chainBrokenAt: broken.at,
+				chainReason: broken.reason
+			} : {}
 		};
 	}
-	/** 单行的链自洽：本行 hash 重算相符，且 prevHash 指向前一行的 hash */
-	async #assertChainAt(records, index, path) {
+	/** 单行的链自洽：本行 hash 重算相符，且 prevHash 指向前一行的 hash。自洽时返回 undefined */
+	async #chainFailureAt(records, index) {
 		const event = records[index];
 		const expectedPrev = index === 0 ? "GENESIS" : records[index - 1]?.hash;
-		if (expectedPrev === void 0 || event.prevHash !== expectedPrev) throw new WebSkillError("GOVERNANCE_FAILED", `Audit chain is broken at line ${index} of ${path}: prevHash link mismatch (events may have been removed, reordered or corrupted)`);
-		if (event.hash !== await sha256Hex$1(canonical(event))) throw new WebSkillError("GOVERNANCE_FAILED", `Audit chain is broken at line ${index} of ${path}: event hash mismatch (event content was tampered)`);
+		if (expectedPrev === void 0 || event.prevHash !== expectedPrev) return "prevHash link mismatch (events may have been removed, reordered or corrupted)";
+		if (event.hash !== await sha256Hex$1(canonical(event))) return "event hash mismatch (event content was tampered)";
 	}
-	/** hash 链完整性校验：逐行重算 hash 并核对 prevHash 链接 */
+	/** hash 链完整性校验：逐行重算 hash 并核对 prevHash 链接。**只读**，绝不改写历史 */
 	async verifyChain() {
 		const path = fileOf$1(this.#root);
-		if (!await this.#fs.exists(path)) return { ok: true };
+		if (!await this.#fs.exists(path)) return {
+			ok: true,
+			total: 0
+		};
 		const lines = (await this.#fs.readText(path)).split("\n").filter((l) => l.trim() !== "");
+		const total = lines.length;
 		let expectedPrev = "GENESIS";
+		let prevTs;
 		for (let i = 0; i < lines.length; i++) {
 			let event;
 			try {
@@ -456,23 +522,29 @@ var FsAuditLog = class {
 				return {
 					ok: false,
 					brokenAt: i,
-					reason: "line is not valid JSON"
+					reason: "line is not valid JSON",
+					total,
+					...prevTs !== void 0 ? { brokenBeforeTs: prevTs } : {}
 				};
 			}
-			if (event.prevHash !== expectedPrev) return {
+			const broken = (reason) => ({
 				ok: false,
 				brokenAt: i,
-				reason: "prevHash link mismatch (events may have been removed or reordered)"
-			};
+				reason,
+				total,
+				...prevTs !== void 0 ? { brokenBeforeTs: prevTs } : {},
+				...typeof event.ts === "string" ? { brokenAfterTs: event.ts } : {}
+			});
+			if (event.prevHash !== expectedPrev) return broken("prevHash link mismatch (events may have been removed or reordered)");
 			const expectedHash = await sha256Hex$1(canonical(event));
-			if (event.hash !== expectedHash) return {
-				ok: false,
-				brokenAt: i,
-				reason: "event hash mismatch (event content was tampered)"
-			};
+			if (event.hash !== expectedHash) return broken("event hash mismatch (event content was tampered)");
 			expectedPrev = event.hash;
+			prevTs = event.ts;
 		}
-		return { ok: true };
+		return {
+			ok: true,
+			total
+		};
 	}
 };
 const dirOf = (root, skillName) => {
@@ -560,7 +632,7 @@ var SkillVersionStore = class {
 	async rollback(skillName, targetVersionId, input) {
 		const target = await this.get(skillName, targetVersionId);
 		const auditEvent = await this.#audit?.append({
-			type: "skill.rolled_back",
+			type: AUDIT_EVENT_TYPES.skillRolledBack,
 			target: skillName,
 			...input.actor !== void 0 ? { actor: input.actor } : {},
 			data: { targetVersionId }
@@ -653,6 +725,21 @@ var RepairPlanner = class {
 };
 const fileOf = (root) => `${root}/.webskill/states.json`;
 /**
+* 用户策略主动拒绝的错误码（FR-12.4）：这是配置生效的证据，不是技能有问题，不计入隔离阈值。
+*
+* 集中在这一份常量里而不散在条件判断里，是为了让「哪些码不计数」只有一个事实源。
+*/
+const POLICY_DENIAL_CODES = /* @__PURE__ */ new Set([
+	"NETWORK_BLOCKED",
+	"TOOL_NOT_ALLOWED",
+	"FS_PERMISSION_DENIED"
+]);
+/** 自动隔离的原因判别式（FR-12.6）；人工隔离仍写自由文本 */
+const QUARANTINE_REASONS = {
+	integrity: "integrity",
+	failures: "failures"
+};
+/**
 * 降级治理：states.json 持久化；失败达阈值 → quarantined；
 * canRoute 仅 active；canExecute active|deprecated；disabled 执行抛 SKILL_DISABLED；
 * 卸载/状态变更经 UiBridge confirm 审批。
@@ -713,17 +800,22 @@ var SkillStatePolicy = class {
 		data.states[skillName] = state;
 		if (state === "active") delete data.failures[skillName];
 		await this.#persist();
+		const auditData = {
+			...input.reason !== void 0 ? { reason: input.reason } : {},
+			...input.detail !== void 0 ? { detail: input.detail } : {}
+		};
 		await this.#audit?.append({
 			type: `skill.${state === "active" ? "reactivated" : state === "quarantined" ? "quarantined" : state === "deprecated" ? "deprecated" : "disabled"}`,
 			target: skillName,
 			...input.actor !== void 0 ? { actor: input.actor } : {},
-			...input.reason !== void 0 ? { data: { reason: input.reason } } : {}
+			...Object.keys(auditData).length > 0 ? { data: auditData } : {}
 		});
 	}
 	/**
 	* 失败计数；达阈值（默认 3）→ quarantined + 审计。
 	*
-	* 计数是**累计**而非「连续」：成功不清零，只有 `setState(name, 'active')` 会清。
+	* 计数是**连续**而非累计（0.7.0 FR-12.5）：一次成功执行经 `clearFailures` 归零，
+	* `setState(name, 'active')` 同样清零。
 	*/
 	async recordFailure(skillName, input = {}) {
 		assertSafePathSegment(skillName, "skill name");
@@ -735,10 +827,11 @@ var SkillStatePolicy = class {
 			state = "quarantined";
 			data.states[skillName] = "quarantined";
 			await this.#audit?.append({
-				type: "skill.quarantined",
+				type: AUDIT_EVENT_TYPES.skillQuarantined,
 				target: skillName,
 				...input.actor !== void 0 ? { actor: input.actor } : {},
 				data: {
+					reason: QUARANTINE_REASONS.failures,
 					failures: count,
 					threshold: this.#failureThreshold
 				}
@@ -747,6 +840,17 @@ var SkillStatePolicy = class {
 		await this.#persist();
 		return state;
 	}
+	/**
+	* 成功清零（FR-12.5）。不写审计（成功是常态，写了会把审计流淹掉），
+	* 也**不改变 state**——已隔离的技能不会因一次成功自动解除。
+	*/
+	async clearFailures(skillName) {
+		assertSafePathSegment(skillName, "skill name");
+		const data = await this.#load();
+		if (data.failures[skillName] === void 0) return;
+		delete data.failures[skillName];
+		await this.#persist();
+	}
 	canRoute(state) {
 		return state === "active";
 	}
@@ -790,25 +894,44 @@ var SkillStatePolicy = class {
 					reason: `integrity check failed: ${e instanceof Error ? e.message : String(e)}`
 				};
 			}
-			if (!verdict.ok) await this.setState(skillName, "quarantined", { reason: verdict.reason ?? "integrity verification failed on activation" });
+			if (!verdict.ok) await this.setState(skillName, "quarantined", {
+				reason: QUARANTINE_REASONS.integrity,
+				detail: verdict.reason ?? "integrity verification failed on activation"
+			});
 			return verdict;
 		} };
 	}
 	/**
 	* runtime `SkillOutcomeReporter` 适配（F1）：一次真实的技能脚本执行失败 → `recordFailure`，
-	* 达阈值即自动 `quarantined` + 写审计。
+	* 达阈值即自动 `quarantined` + 写审计；一次成功 → `clearFailures`。
 	*
 	* 0.4.0 之前 `recordFailure` 没有任何生产调用方——`states.json` 的失败计数只在单测里增长，
 	* 于是「失败达阈值自动隔离」在真实部署里从不触发，Console 上那个计数恒为 0。
 	* 这个适配器就是把那一段接上：runtime 不能反向依赖治理，装配点只能在宿主。
 	*
-	* 只上报失败、不上报成功，与 `recordFailure` 的既有语义保持一致（累计计数，
-	* 成功不清零，只有 `setState(name, 'active')` 清零）。
+	* 策略拒绝的分流放在这里而不是 `recordFailure`：后者是**治理动作**（管理员也可手工调用），
+	* 它不该知道运行时错误码；判定“这次失败算不算技能的错”是**上报侧**的语义。
 	*/
 	toSkillOutcomeReporter(input = {}) {
-		return { onSkillFailed: async (report) => {
-			await this.recordFailure(report.skillName, input);
-		} };
+		const denied = input.policyDenialCodes ?? POLICY_DENIAL_CODES;
+		const actor = input.actor !== void 0 ? { actor: input.actor } : {};
+		return {
+			onSkillFailed: async (report) => {
+				if (denied.has(report.code)) {
+					await this.#audit?.append({
+						type: AUDIT_EVENT_TYPES.skillPolicyDenied,
+						target: report.skillName,
+						...actor,
+						data: { code: report.code }
+					});
+					return;
+				}
+				await this.recordFailure(report.skillName, actor);
+			},
+			onSkillSucceeded: async (report) => {
+				await this.clearFailures(report.skillName);
+			}
+		};
 	}
 	/** disabled → SKILL_DISABLED；quarantined → SKILL_QUARANTINED */
 	async assertExecutable(skillName) {
@@ -839,7 +962,7 @@ var SkillStatePolicy = class {
 		delete data.failures[skillName];
 		await this.#persist();
 		await this.#audit?.append({
-			type: "skill.uninstalled",
+			type: AUDIT_EVENT_TYPES.skillUninstalled,
 			target: skillName,
 			actor: input.actor
 		});
@@ -1089,4 +1212,4 @@ function createMissHook(deps) {
 }
 
 //#endregion
-export { AUDIT_PAGE_SIZE, AlwaysHumanApprovalPolicy, CANDIDATE_PAGE_SIZE, CandidateStore, CompositeApprovalPolicy, DependencyGraph, DocumentSkillExtractor, EvaluationRunner, FailureAnalyzer, FsAuditLog, LlmCandidateGenerator, RepairPlanner, SCORING_WEIGHTS, SKILL_VERSION_PAGE_SIZE, SimilarityDetector, SkillScorer, SkillStatePolicy, SkillVersionStore, candidateToCatalogEntry, completeText, createCandidateSink, createMissHook, jaccardSimilarity, normalizeCandidate, normalizeCandidateFiles, normalizeRisk, parseJsonObject, readDocument, sanitizeCandidateName, suggestFromFailedRun, validateCandidate };
+export { AUDIT_EVENT_TYPES, AUDIT_EVENT_TYPE_LIST, AUDIT_PAGE_SIZE, AlwaysHumanApprovalPolicy, CANDIDATE_PAGE_SIZE, CandidateStore, CompositeApprovalPolicy, DependencyGraph, DocumentSkillExtractor, EvaluationRunner, FailureAnalyzer, FsAuditLog, LlmCandidateGenerator, POLICY_DENIAL_CODES, QUARANTINE_REASONS, RepairPlanner, SCORING_WEIGHTS, SKILL_VERSION_PAGE_SIZE, SimilarityDetector, SkillScorer, SkillStatePolicy, SkillVersionStore, candidateToCatalogEntry, completeText, createCandidateSink, createMissHook, jaccardSimilarity, normalizeCandidate, normalizeCandidateFiles, normalizeRisk, parseJsonObject, readDocument, sanitizeCandidateName, suggestFromFailedRun, validateCandidate };

package/dist/{index-D_7ZZjkl.d.ts → index-Ba3xFtfz.d.ts}

@@ -1,5 +1,5 @@
-import { a as InteractionOrigin, b as UiBridge } from "./types-D_hoCri8-BnNPiZCi.js";
-import { x as ExternalToolSource } from "./index-vBz_FC9w.js";
+import { a as InteractionOrigin, c as InteractionResponse, s as InteractionRequest, x as UiBridge } from "./types-CcxRLdJG-DCXyw1US.js";
+import { k as ExternalToolSource } from "./index-DkbABR43.js";
 //#region ../agent/dist/index.d.ts
 //#region src/todo/types.d.ts
 /** 待办条目状态：未开始 / 进行中 / 已完成（FR-3.1） */
@@ -165,6 +165,9 @@ declare function createSkillGenerationToolSource(options: SkillGenerationToolSou
 /**
  * 技能自动生成的系统提示词。默认不注册工具，因此这段提示词只在
  * 宿主打开开关时才进入上下文（设计 02 §1.3）。
+ *
+ * 触发条件写成正面清单而不是「不要自发调用」（0.6.0 FR-18.5）：实测中后者会连
+ * 「帮我写一份流程规范」这类明确的沉淀请求一起抑制掉，开关等于白开。
  */
 declare const SKILL_GENERATION_SYSTEM_PROMPT: string;
 //#endregion
@@ -312,8 +315,52 @@ interface PerceivedNode {
   name?: string;
   /** 仅非敏感控件的当前值 */
   value?: string;
+  /** 关联的图像分片 id（FR-12.1）；节点里只放 id 不放 base64，否则 JSON 树会被截断切碎 */
+  imageId?: string;
+  /** 取像失败的降级说明（英文）；不得静默丢弃（FR-12.1） */
+  imageNote?: string;
+  /**
+   * 不透明元素句柄（S10）。**仅当该节点可被操作时出现**：
+   * 它落在宿主声明的操作范围内、且是可交互角色。
+   * 由 reader 生成，只在产生它的那次感知内有效；模型不得构造或推断。
+   */
+  ref?: string;
   children?: readonly PerceivedNode[];
 }
+/** 随感知一起下发的一张图像（FR-12.1） @experimental */
+interface PerceivedImage {
+  /** 与 `PerceivedNode.imageId` 对应 */
+  id: string;
+  mimeType: string;
+  /** base64，不含 `data:` 前缀 */
+  data: string;
+  /** 取像级别：`src` 为原图字节，`canvas` 为画布/SVG 读回 */
+  level: 'src' | 'canvas';
+}
+/**
+ * 取像预算与开关（FR-12.3 / FR-12.5）。
+ * 它只能来自宿主配置与当前模型能力，**不包含任何范围字段**：
+ * “读哪里”仍只由构造时的 `scope` 决定（AC-10.8）。
+ * @experimental
+ */
+interface PerceptionCaptureOptions {
+  /** false 时 reader 不得进入任何取像分支（抓完再丢弃不可接受） */
+  images: boolean;
+  maxImageBytes: number;
+  maxImages: number;
+}
+/**
+ * reader 的完整产物。只实现文本的 reader 可以继续返回节点数组。
+ * @experimental
+ */
+interface PerceptionResult {
+  nodes: readonly PerceivedNode[];
+  images?: readonly PerceivedImage[];
+  /** 超出 `maxImages` 而未下发的张数 */
+  imagesOmitted?: number;
+  /** 取像失败的张数；失败不影响整次感知的成功与否 */
+  imageFailures?: number;
+}
 /**
  * 页面读取实现的注入口（浏览器侧 `createDomPerceptionReader`）。
  *
@@ -322,7 +369,7 @@ interface PerceivedNode {
  * @experimental
  */
 interface PagePerceptionReader {
-  read(scope: PerceptionScope): Promise<readonly PerceivedNode[]> | readonly PerceivedNode[];
+  read(scope: PerceptionScope, capture?: PerceptionCaptureOptions): Promise<readonly PerceivedNode[] | PerceptionResult> | readonly PerceivedNode[] | PerceptionResult;
 }
 /** 一次感知的留痕（FR-10.5 的 UI 提示与 FR-10.6 的审计共用同一条记录） @experimental */
 interface PerceptionRecord {
@@ -333,19 +380,33 @@ interface PerceptionRecord {
   exclude: readonly string[];
   /** 读到的顶层节点数；用于「它读的比我预期的多」这类判断 */
   nodeCount: number;
+  /** 本次下发的图像张数，按取像级别分组（只在取像开启时存在） */
+  images?: {
+    src: number;
+    canvas: number;
+  };
+  imagesOmitted?: number;
+  /** 读取失败的张数；藏起来会让用户误以为模型看到了全部图片 */
+  imageFailures?: number;
 }
 /**
- * 审计落盘端口。刻意只声明 `append` 的结构化子集，`FsAuditLog` 直接满足——
+ * 页面侧留痕的统一出口（感知与操作共用）。
+ * 刻意只声明 `append` 的结构化子集，`FsAuditLog` 直接满足——
  * agent 包不能依赖 governance，但审计不能因此变成「记在内存里」。
  * @experimental
  */
-interface PerceptionAuditSink {
+interface PageAuditSink {
   append(event: {
     type: string;
     target: string;
     data?: Record<string, unknown>;
   }): Promise<unknown>;
 }
+/**
+ * @deprecated 改用 `PageAuditSink`。保留以兼容 0.5.0 的注入代码。
+ * @experimental
+ */
+type PerceptionAuditSink = PageAuditSink;
 //#endregion
 //#region src/perception/policy.d.ts
 interface PagePerceptionPolicyOptions {
@@ -361,9 +422,10 @@ interface PagePerceptionPolicyOptions {
 /**
  * 页面只读感知策略（需求 10）。
  *
- * **`perceive()` 不接受任何参数**——这是「白名单判定不受模型输出影响」
+ * **`perceive()` 不接受任何范围参数**——这是「白名单判定不受模型输出影响」
  * （AC-10.8）的实现方式。不是先拿模型给的范围再去校验，而是模型压根没有
  * 表达范围的入口：能被读的区域只由构造时的 `scope` 决定。
+ * 唯一的参数是取像预算（`PerceptionCaptureOptions`），它里面没有任何范围字段。
  *
  * 本类**没有**任何点击 / 输入 / 提交 / 导航 / 滚动方法（FR-10.7）。
  * @experimental
@@ -378,8 +440,10 @@ declare class PagePerceptionPolicy {
   get records(): readonly PerceptionRecord[];
   /** FR-10.5：感知发生时通知 UI，chatbot 据此在消息流里标注一行 */
   subscribe(listener: (record: PerceptionRecord) => void): () => void;
-  perceive(): Promise<{
+  perceive(capture?: PerceptionCaptureOptions): Promise<{
     nodes: readonly PerceivedNode[];
+    images: readonly PerceivedImage[];
+    imagesOmitted: number;
     record: PerceptionRecord;
   }>;
 }
@@ -388,6 +452,17 @@ declare class PagePerceptionPolicy {
 declare const PERCEIVE_PAGE_TOOL = "perceive_page";
 interface PagePerceptionToolSourceOptions {
   policy: PagePerceptionPolicy;
+  /**
+   * 取像预算与开关（FR-12.5）。每次调用重取，设置或选中模型改完立刻生效；
+   * 缺省即不取像。判定在遍历 DOM **之前**完成一次，不是每个节点判一次。
+   */
+  imageCapture?(): ImageCaptureBudget | Promise<ImageCaptureBudget>;
+}
+/** @experimental */
+interface ImageCaptureBudget {
+  enabled: boolean;
+  maxImageBytes: number;
+  maxImages: number;
 }
 /**
  * 把只读感知接到既有工具协议上。**本工具源不导出任何写入动作**（FR-10.7）：
@@ -408,4 +483,143 @@ declare function createPagePerceptionToolSource(options: PagePerceptionToolSourc
  */
 declare const PERCEPTION_SYSTEM_PROMPT: string;
 //#endregion
-export { SubAgentRunInput as A, createDelegationToolSource as B, SKILL_GENERATION_SYSTEM_PROMPT as C, SkillGenerationToolSourceOptions as D, SkillGenerationPolicy as E, TodoList as F, createSkillGenerationToolSource as H, TodoListener as I, TodoStatus as L, TODO_SYSTEM_PROMPT as M, TodoEvent as N, SkillGenerator as O, TodoItem as P, TodoStore as R, PerceptionScope as S, SkillGenerationOutcome as T, createTodoToolSource as U, createPagePerceptionToolSource as V, withDelegationOrigin as W, PagePerceptionToolSourceOptions as _, DelegationOrchestratorOptions as a, PerceptionAuditSink as b, DelegationToolSourceOptions as c, MANAGE_TODO_TOOL as d, PERCEIVE_PAGE_TOOL as f, PagePerceptionReader as g, PagePerceptionPolicyOptions as h, DelegationOrchestrator as i, SubAgentRunner as j, SkillGeneratorOptions as k, GENERATE_SKILL_TOOL as l, PagePerceptionPolicy as m, DELEGATION_SYSTEM_PROMPT as n, DelegationRequest as o, PERCEPTION_SYSTEM_PROMPT as p, DelegationBudget as r, DelegationResult as s, DELEGATE_TASK_TOOL as t, GeneratedSkillDraft as u, ParentBudget as v, SkillCandidateSink as w, PerceptionRecord as x, PerceivedNode as y, TodoToolSourceOptions as z };
+//#region src/pageAction/types.d.ts
+/**
+ * 页面操作的策略层类型（需求 23）。
+ *
+ * 与感知层同一条规矩：这一层不含任何 DOM 概念——执行落在 `@webskill/browser`，
+ * 本包只定义「什么允许被操作」以及一次操作长什么样。
+ */
+/**
+ * 可操作范围白名单（FR-23.1，硬约束）。
+ *
+ * **没有默认值，空 `include` 就是任何操作都不可执行。**
+ * 与 `PerceptionScope` 同构但**独立声明**：写成类型别名会让「感知与操作共用一份配置」
+ * 在类型层面合法，而 FR-23.1 写死了那是不可接受的——可读不等于可操作。
+ * @experimental
+ */
+interface PageActionScope {
+  /** 可操作的根节点选择器；未声明即不可操作 */
+  include: readonly string[];
+  /** 从 include 子树中剪除的危险控件（支付、删除、权限变更等） */
+  exclude?: readonly string[];
+}
+/** 本版的最小操作集（FR-23.4）。导航、拖拽、滚动均不在内。 @experimental */
+type PageActionKind = 'click' | 'fill' | 'submit';
+/** @experimental */
+interface PageActionRequest {
+  /** 感知产出的不透明句柄；不接受选择器（FR-23.4） */
+  ref: string;
+  action: PageActionKind;
+  /** `action === 'fill'` 时必填 */
+  value?: string;
+}
+/** @experimental */
+interface PageActionOutcome {
+  ok: boolean;
+  /**
+   * 实际操作到的元素的角色与可访问名称。
+   * 由**执行器**回填而不是调用方从感知结果里查：执行的那一刻元素可能已经变了，
+   * 留痕必须记实际操作到的东西（FR-23.3）。
+   */
+  target: {
+    role: string;
+    name?: string;
+  };
+  /** 目标是密码类控件：确认卡与留痕据此隐去值（FR-23.3） */
+  secret?: boolean;
+  /** 失败原因（英文） */
+  reason?: string;
+}
+/**
+ * 页面操作执行器。与 `PagePerceptionReader` 对称，同样不含 DOM 概念。
+ * 实现方负责校验句柄有效性、元素可交互性，以及目标是否仍在操作范围内。
+ * @experimental
+ */
+interface PageActionExecutor {
+  execute(request: PageActionRequest): Promise<PageActionOutcome> | PageActionOutcome;
+  /** 目标的角色与可访问名称，供确认卡在**执行前**说清将要做什么（FR-23.2） */
+  describe(ref: string): {
+    role: string;
+    name?: string;
+    secret?: boolean;
+  } | undefined;
+}
+/** 一次页面操作的留痕（FR-23.3 的五项字段） @experimental */
+interface PageActionRecord {
+  /** ISO 8601 */
+  at: string;
+  action: PageActionKind;
+  role: string;
+  name?: string;
+  /** 是否经用户确认；宿主预授权的操作记 `'preauthorized'` */
+  approved: boolean | 'preauthorized';
+  ok: boolean;
+  /** 非密码类控件填入的值；密码类控件**整个字段不存在** */
+  value?: string;
+  reason?: string;
+}
+//#endregion
+//#region src/pageAction/policy.d.ts
+/** 授权卡的最小出口；`UiBridge` 直接满足（与技能生成用的是同一个端口） */
+interface PageActionUi {
+  request(input: InteractionRequest): Promise<InteractionResponse>;
+}
+interface PageActionPolicyOptions {
+  /** 宿主声明的可操作范围；`include` 为空即整个能力不可用 */
+  scope: PageActionScope;
+  executor: PageActionExecutor;
+  ui: PageActionUi;
+  /** FR-23.3：每次操作写审计。不注入即不留痕，装配方要自己承担这个选择 */
+  audit?: PageAuditSink;
+  /** 审计事件的 target（缺省 `page`） */
+  auditTarget?: string;
+  /**
+   * 免确认的操作类型。**缺省即每一次操作都要确认**（AC-23.4）。
+   * 只有宿主显式配置才生效，SDK 不提供任何缺省放行项。
+   */
+  preauthorized?: readonly PageActionKind[];
+  now?(): string;
+}
+/**
+ * 页面操作策略（需求 23）。
+ *
+ * 三道闸门依次是：宿主有没有声明范围、用户认不认、执行器认不认。
+ * 模型能表达的只有「在哪个句柄上做哪个动作」——它没有任何影响范围的入口（AC-23.2）。
+ * @experimental
+ */
+declare class PageActionPolicy {
+  #private;
+  constructor(options: PageActionPolicyOptions);
+  /** 白名单为空即不可用（FR-23.1）：宿主没声明范围就没有这个能力 */
+  get enabled(): boolean;
+  get scope(): PageActionScope;
+  /** 最近的操作记录（只读展示用），新的在前 */
+  get records(): readonly PageActionRecord[];
+  act(request: PageActionRequest): Promise<PageActionOutcome>;
+}
+//#endregion
+//#region src/pageAction/toolSource.d.ts
+declare const PAGE_ACTION_TOOL = "act_on_page";
+interface PageActionToolSourceOptions {
+  policy: PageActionPolicy;
+}
+/**
+ * 把页面操作接到既有工具协议上。
+ *
+ * 策略未注入或宿主没声明可操作区域时 `listToolSpecs()` 返回空数组——
+ * 模型连这个工具的存在都看不到，而不是看得到再被拒（FR-23.5 / AC-23.8）。
+ * @experimental
+ */
+declare function createPageActionToolSource(options: PageActionToolSourceOptions): ExternalToolSource;
+//#endregion
+//#region src/prompts/pageAction.d.ts
+/**
+ * 页面操作的系统提示词（需求 23）。
+ *
+ * 措辞刻意保守：提示词里的鼓励性表述会直接抬高模型尝试操作的频率，
+ * 而每一次尝试都要打断用户去点确认。
+ */
+declare const PAGE_ACTION_SYSTEM_PROMPT: string;
+//#endregion
+export { TodoListener as $, PagePerceptionReader as A, SKILL_GENERATION_SYSTEM_PROMPT as B, PageActionRequest as C, PageAuditSink as D, PageActionUi as E, PerceptionAuditSink as F, SkillGenerator as G, SkillGenerationOutcome as H, PerceptionCaptureOptions as I, SubAgentRunner as J, SkillGeneratorOptions as K, PerceptionRecord as L, ParentBudget as M, PerceivedImage as N, PagePerceptionPolicy as O, PerceivedNode as P, TodoList as Q, PerceptionResult as R, PageActionRecord as S, PageActionToolSourceOptions as T, SkillGenerationPolicy as U, SkillCandidateSink as V, SkillGenerationToolSourceOptions as W, TodoEvent as X, TODO_SYSTEM_PROMPT as Y, TodoItem as Z, PageActionExecutor as _, DelegationOrchestratorOptions as a, createPagePerceptionToolSource as at, PageActionPolicy as b, DelegationToolSourceOptions as c, withDelegationOrigin as ct, ImageCaptureBudget as d, TodoStatus as et, MANAGE_TODO_TOOL as f, PERCEPTION_SYSTEM_PROMPT as g, PERCEIVE_PAGE_TOOL as h, DelegationOrchestrator as i, createPageActionToolSource as it, PagePerceptionToolSourceOptions as j, PagePerceptionPolicyOptions as k, GENERATE_SKILL_TOOL as l, PAGE_ACTION_TOOL as m, DELEGATION_SYSTEM_PROMPT as n, TodoToolSourceOptions as nt, DelegationRequest as o, createSkillGenerationToolSource as ot, PAGE_ACTION_SYSTEM_PROMPT as p, SubAgentRunInput as q, DelegationBudget as r, createDelegationToolSource as rt, DelegationResult as s, createTodoToolSource as st, DELEGATE_TASK_TOOL as t, TodoStore as tt, GeneratedSkillDraft as u, PageActionKind as v, PageActionScope as w, PageActionPolicyOptions as x, PageActionOutcome as y, PerceptionScope as z };