企业官网建设流程全解析

• GUI 自动化
• MCP 服务
• AI 应用

本文以 Peekaboo 仓库中的行为契约 live-multi-target-certification-coordinator.md 为主体，完整拆解live多目标认证协调器的目标形态、闭环 plan 结构、六围栏（fence）心跳纪律、外部 Computer Use 双窗口握手、monitor 密封与 PID 绑定挑战，以及两阶段 finalizer 的超时推导与清理语义；并对照协调器实现 run-live-multi-target-certification.mjs、确定性测试 live-multi-target-certification-coordinator.test.mjs 与目录文件 multi-target-certification-catalog.json，说明每一条契约条款是如何被实现并验证的。读完后你将掌握：如何构造一个合法的 owner-private plan、理解perform/restore两个外部前台窗口的事件时序，以及为什么“持久化的 summary 本身不是认证权威”。

1. 契约主体：一次全新的 owner-private 认证生命周期

契约文档开宗明义地定义了用户可见目标（User-Visible Goal）：运行一次全新的、owner-private 的认证生命周期，其中恰好包含两个持久化的后台控制器、一个 observe-only 语义见证者（semantic witness）、一个 source-pinned 的 monitor，以及一个有界的两阶段外部 Computer Use 窗口。持久化的 summary 本身绝不构成认证权威，只有最后的 live finalizer 退出才能完成整个 run。

这句话是整个体系的信任模型基石。它对应实现里的三处硬约束：

• 协调器只在所有 live 门（monitor 密封、两次 PID 绑定挑战、prepare、最终finalize、子进程释放）全部通过后，才发出认证合格的完成事件，见 run-live-multi-target-certification.mjs；
• 测试运行时（test-runtime）即使完整走通生命周期，也只发出test-runtime-complete且certification_eligible: false；
• finalizer 的持久化 summary 是“展示用”的，认证裁决来自 finalizer 进程退出状态本身（finalize-multi-target-certification.mjs 的 CLI 帮助明确“Exit status is 0 for a valid certificate”）。

1.1 运行入口与目标类型

契约声明 Target 为 CLI，启动方式为：

node scripts/run-live-multi-target-certification.mjs --plan OWNER_PRIVATE_PLAN.json

脚本头部帮助文本（run-live-multi-target-certification.mjs）与契约一一对应：协调器创建全新的 nonce 与 run root，持有恰好两个持久后台控制器加一个 observe-only 语义见证者，用 monitor fence 夹住一个显式有界的外部 Computer Use 窗口，密封 live corpus，然后执行prepare与最终 finalization。JSON 生命周期事件写 stdout，诊断信息写 stderr，只有所有 live 门通过时退出码才为 0。

契约还规定：owner-private 的假子进程可执行文件与文件可以用于演练生命周期行为，但测试运行时的输出必须被显式判定为不可认证——这正是PEEKABOO_COORDINATOR_TEST_RUNTIME=1环境变量开启的测试运行时模式（见 main() 入口）。

该脚本的适用前提是 macOS（仓库 package.json 声明os: darwin，且engines.node >= 22）；生产路径还会调用codesign、otool、plutil等 macOS 系统工具做代码签名身份校验。

1.2 四个用户任务

契约列出的 User Tasks 是外部操作者（或测试驱动方）在协调器运行期间要完成的事情：

1. 启动一次合法 run，观察新鲜的 nonce、monitor UUID 与新创建的私有 run root；
2. 等待perform外部前台事件，执行命名任务，并公布关闭的 task marker；
3. 等待restore外部前台事件，恢复精确的语义基线与 sentinel，并公布关闭的 restoration marker；
4. 观察两个控制器与语义观察者在 monitor 密封、PID 绑定挑战、prepare和最终 finalization 期间保持存活，并且只有在收到 owner release marker 后才退出。

实现层面，任务 1 对应run-created事件：协调器用fs.mkdtempSync在runs_directory下创建peekaboo-live-certification-前缀的 run root（0700 权限），用randomBytes(32)生成 64 位 hex nonce，用randomUUID()生成 UUIDv4 的 monitor 实例 ID（runCoordinator 开头）。任务 2/3 对应两次external-foreground-window事件（详见第 4 节）。任务 4 对应释放语义：协调器在 finalizer 成功后为每个控制器写controller-release.json、为观察者写observer-release.json，然后以 5 秒超时等待子进程close，monitor 则由协调器主动SIGTERM终止（释放与等待退出）。

2. 闭环 plan：schema、闭包与前置失败

契约规定：plan schema 是闭环的。未知字段、非私有输入、错误的 target/controller 基数、无界超时，都必须在子进程启动之前失败。实现的validatePlan（validatePlan）逐条落实：

2.1 根键闭包

plan 根对象必须恰好包含这些键（且version === 1）：

测试运行时模式额外允许test_runtime键（必须恰含catalog_path、finalizer_path、diagnostic_reports_path三个绝对路径，且diagnostic_reports_path等于规范化的 DiagnosticReports 目录）。任何多余字段都会触发exactKeys失败并抛出plan keys are not closed——测试closed plan rejects unknown caller fields before creating a run用{ ...plan, success: true }验证了“调用者写入success: true也不能认证 run”（测试用例）。

requirePrivateDirectory/requirePrivateFile（私有性检查）实现了“非私有输入失败”：检查lstat非符号链接、(mode & 0o077) === 0、uid === geteuid()，文件还需nlink === 1且不超过 16 MiB（MAXIMUM_FILE_BYTES）。

2.2 bridge 子对象

bridge必须恰含socket_path（绝对路径）、trusted_host_team_ids（非空数组，每项为 10 位A-Z0-9Team ID）、expected_host（恰含host_kind∈ {gui,daemon}、process_identifier、process_start_identity_decimal、code_signature_hash（40 hex）、source_commit（40 hex））。两条强绑定：

• trusted_host_team_ids排序后必须等于 catalog 中trusted_bridge_host_team_ids；
• expected_host.source_commit必须等于当前构建推导出的 commit（生产路径来自干净 Git HEAD 的源绑定校验，测试运行时来自git rev-parse --verify HEAD，见 deriveCurrentBuildSource）。

测试Bridge host commit must equal the coordinator Git HEAD even in test runtime把source_commit换成目录文件中的协议字面量'e'.repeat(40)，验证其被bridge plan is malformed拒绝——即目录文件里的任何字面量都不能顶替 live commit（测试用例）。

2.3 controllers：恰好两个，且与 catalog 槽位对齐

每个 controller 条目恰含controller_id、target_id、target，其中：

• (controller_id, target_id)组合必须匹配 catalog 的controlled_target_ids与slots模板（catalog 中为controller-a→target-a、controller-b→target-b，见 multi-target-certification-catalog.json）；
• 两个controller_id与两个target_id各自不同；
• 物理目标必须互不相同：(pid, start_identity, window_id)三元组去重后必须仍为 2 个，否则报background controller physical targets must be distinct（测试duplicate exact physical targets fail before child launch验证此点，测试用例）。

target（controller 形态）必须恰含process_identifier、process_start_identity_decimal（无符号正十进制字符串、≤ uint64）、window_id（正安全整数且 ≤ 0xffffffff）、bounds（恰含x/y/width/height）、is_minimized（布尔或 null）、click_point（恰含x/y，且必须落在bounds矩形内）。数值校验函数finiteLosslessNumber（实现）允许有限分数（finite fractional coordinates 合法），但拒绝非有限值、-0、以及超出 safe-integer 的整数。测试finite fractional target geometry completes the coordinator lifecycle与nonfinite, nonpositive, and negative-zero target geometry fail before launch分别验证了这两侧（测试用例）。

2.4 observer：observe-only 语义计划

observer恰含target（标准窗口形态）、semantic_element、baseline_value。semantic_element必须恰含role（非空、无 NUL、≤ 256 字节）、identifier（可空，非空时 ≤ 1024 字节）、title（可空），且identifier与title不能同时为空；baseline_value为非空 UTF-8 字符串且 ≤ 4096 字节。测试semantic discriminator rejects empty, oversized, and NUL values before launch覆盖了空字符串、超 1024 字节 identifier、含 NUL 的 role 三种拒绝情形。

2.5 monitor 与超时预算

monitor必须恰含 7 个键：sentinel、foreground_controller、foreground_controller_team_id、foreground_target、invariant_names、crash_directory、interval_milliseconds、code_signature_hash（注意是 8 键，实现见 validatePlan monitor 段）。关键约束：

• interval_milliseconds必须落在5～100的有界区间；
• invariant_names必须是恰好 6 个、互不相同的非空字符串（测试 fixture 使用['focus','window','cursor','input','clipboard','overlay']）；
• foreground_target必须与observer.target完全相等（canonical JSON 比较），且该前台目标与两个后台物理目标都不同；
• foreground_controller（PID/start_identity/code_signature_hash 三元组）必须与 Bridge host 及两个后台控制器的 PID 都不同；
• crash_directory必须等于当前用户规范的~/Library/Logs/DiagnosticReports——生产模式下该路径由协调器直接用os.userInfo().homedir推导（main 中推导），调用者提供的空目录、别名、符号链接一律拒绝。测试crash evidence accepts only the canonical DiagnosticReports directory用自造空目录与符号链接两种变体验证（测试用例）。

超时预算的推导值得单独说明。协调器为每个控制器生成一段type_text：前缀peekaboo-certification-background:<nonce>:<controller_id>:，长度取“前缀字节数+1”与“覆盖external_foreground_timeout_seconds + 20秒、按每字符 50 ms（CONTROLLER_TYPING_DELAY_MILLISECONDS）所需字符数”的较大者，且不得超过 4096 字节（makeControllerText）。于是operation_timeout_seconds必须满足：

operation_timeout ≥ 最大 typing 时长 + 2 × external_foreground_timeout + 30s 生命周期余量

否则报operation timeout does not cover controller typing, both external windows, and lifecycle overhead。测试给出了三个数据点：65s（5s 外部窗口，500 字符）通过；64s 拒绝；external_foreground_timeout_seconds = 21时按旧公式2×21+30=72仍被拒绝——因为 typing 时长不对称地增长（21s 窗口需要 700 字符 = 35s typing），该测试命名为21-second asymmetric window budget rejects the former two-window-only formula（测试用例）。

3. Monitor 六围栏与心跳时钟纪律

契约的核心可观察行为是：baseline、grant、operations-start、operations-complete、revoke、final 围栏是严格有序的“稳定 monitor 心跳”；其 safe-integer 单调微秒严格递增，墙钟毫秒永不倒退，相邻时钟差保持在两秒之内；除 operations-complete 外没有前台活动，而 operations-complete 处的前台活动必须恰好归属于那个精确的集成 Computer Use producer PID。

3.1 六个围栏名与 producer 修订

围栏名在 catalog 的monitor_contract.required_fences中声明为baseline-stable、grant-stable、operations-start、operations-complete、revoke-stable、final-stable（catalog monitor_contract）。协调器通过 producer 文档的revision字段推进授权（producerDocument）：

waitForHeartbeat（实现）对每个候选心跳做如下闭环校验：

• 运行绑定：executionNonce与monitorInstanceID必须等于本次 run 的 nonce 与 UUIDv4；
• 顺序性：sequence必须大于上一个 fence 的 sequence，authorizationEpoch必须严格递增，否则立即失败（monitor authorization epoch did not increase）；
• 时钟纪律：monotonicMicroseconds严格大于上一个 fence；wallClockMilliseconds不得小于上一个；两者之差（heartbeatClockDriftMicroseconds）不得超过2,000,000 微秒，否则wall/monotonic clock drift exceeded two seconds。测试cross-clock drift beyond two seconds rejects a stable fence用FAKE_CLOCK_DRIFT=1让假 monitor 在每个心跳上把墙钟偏移 3s×sequence，验证协调器失败且一个外部窗口事件都不发出；
• 无污染：contaminationRetries === 0、contaminationBlocked === false、inputAttributionAvailable === true，否则monitor became contaminated or lost attribution；
• 前台活动纪律：requireActivity=false的围栏要求attributedForegroundEventCount === 0且foregroundActivityObserved === false，任何非零即失败foreground activity occurred before the <name> fence（测试foreground activity before operations-start fails closed immediately用FAKE_EARLY_ACTIVITY=1在 grant-stable 就注入活动，验证其在任何外部窗口事件之前失败）；requireActivity=true（仅 operations-complete）则要求计数 > 0、来源 PID 集合恰为[foregroundControllerPID]、foregroundActivityObserved === true；
• 陈旧采样防护：notBeforeWallClockMilliseconds = Date.now()在“刚刚 await 完某前置条件”时取定，心跳墙钟早于该值则视为陈旧样本继续轮询。测试operations-start rejects a heartbeat sampled before both mutation markers通过--import预载钩子拦截readFileSync，向协调器投喂一个真实的 mutation 前旧心跳，验证最终选中的operations-startfence 满足start.sequence > handoff.heartbeat.sequence且两个mutation-started时间戳都不晚于它（测试用例）。

心跳文档本身是闭环的 27 键结构（heartbeatIsClosed），涵盖sequence、monotonicMicroseconds、wallClockMilliseconds、lastCleanSequence、contaminationRetries、allowedProducerRevision、authorizationEpoch、foregroundActive/foregroundTargetPID/foregroundTargetWindowID、attributedForegroundEventCount/attributedForegroundSourcePIDs（去重校验）、historyCommitmentSHA256等。

3.2 围栏前后的“开放区间”断言

契约要求两个控制器的 mutation 区间必须跨住 operations-start 与 operations-complete。协调器用两组存在性检查实现：

• 采operations-start前：两个mutation-started.json都必须存在且闭环（含 nonce/controller/target/timestamp 全字段），且任何mutation-completed.json不得存在，否则a controller mutation completed before the operations-start fence；
• 采operations-complete前：再次断言没有任何mutation-completed.json；
• restore-complete事件之后，控制器才能公布mutation-completed.json（假控制器 fixture 正是等待FAKE_EXTERNAL_RESTORE_STARTED_PATH后才写，并保证时间戳严格晚于 restore marker）。

测试controller mutation completing before the operations fences fails closed用 1ms 的 mutation delay 触发失败，且断言restore窗口事件从未发出、finalizer 日志为空。

3.3 sentinel 与崩溃证据

verifiedSentinelSample（实现）在基线与终态各取一次 monitor 采样，并在采样前后各调一次process-identity校验 sentinel 的进程世代（start_identity 必须与 plan 精确一致），同时要求采样的frontmostPID/frontmostWindowID与 sentinel 完全相等。两个对应的失败路径都有测试：stale planned sentinel generation fails before the external window（plan 里写错 start_identity，失败且无外部窗口事件）与final sentinel generation drift fails before sealing or finalization（FAKE_FINAL_SENTINEL_START_IDENTITY在终态漂移，失败且 finalizer 未运行）。

崩溃证据来自契约的第二个关键条款：崩溃证据只来自当前用户规范的~/Library/Logs/DiagnosticReports；其闭环前缀集包含Playground、签名 fixture 解析后的可执行文件名与诊断报告基名，同时保留遗留的PeekabooPlayground监视条目；空的替代目录、别名或符号链接不作为更安静的证据源被接受。生产 catalog 的前缀集是["Peekaboo", "PeekabooPlayground", "Playground", "OpenClaw", "peekaboo-certification-controller"]（catalog），其中PeekabooPlayground即“保留的遗留监视条目”，OpenClaw对应签名 fixture 的可执行基名。crashInventory（实现）对每个匹配前缀的文件取name/size/mtime/sha256并按名排序；run 结束时的清单必须与基线 canonical 相等，任何新报告都导致new certification-related crash reports appeared during the run。

4. 两个有界的外部前台窗口：perform 与 restore

契约的 User Tasks 2/3 由实现中的两次“窗口—marker—见证”序列落实（perform 窗口 与 restore 窗口）：

1. 协调器写external-foreground-window.json（含execution_nonce、monitor_instance_id、phase: perform|restore、目标、task_complete_path/restore_complete_path、deadline_milliseconds），并发出external-foreground-window事件；截止时间为min(围栏墙钟 + external_foreground_timeout_seconds, operationDeadline)，即每个窗口都是有界的；
2. 外部操作者必须独占地写关闭的完成 marker：{version: 1, execution_nonce, monitor_instance_id, phase: task-complete|restore-complete}。externalMarkerIsValid（实现）要求四个键精确匹配本次 nonce、monitor UUID 与所请求的 phase——换 nonce、换 monitor 实例或换 phase 重放都会被拒绝，报external foreground <phase> marker is not closed and run-bound。测试stale external marker fails closed and preserves the run root用全零 nonce 重放 marker，验证失败、failed事件发出且 run root 被保留（测试用例）；
3. perform窗口完成后，协调器写observe-request.json，observe-only 观察者执行一次新鲜签名读回并写foreground-observation.json；restore窗口完成后，协调器写restore-request.json，观察者恢复基线值、写foreground-restoration.json与foreground-witness.json，并监听自己的 attestation socket。

观察者计划中还包含与运行绑定的语义承诺：request_marker = "peekaboo-foreground-postcondition:<nonce>"，expected_value_sha256 = sha256(request_marker)，baseline_value_sha256 = sha256(baseline_value)。观察者 readiness 必须回显focused_element（role/identifier/title 与 plan 的语义元素一致，且 frame 落在目标 bounds 内，见 focusedElementMatches）与两个摘要，任一不符即foreground observer readiness is not bound to the committed semantic plan。

5. 双控制器的 final-bounds 屏障与 owner-private 释放

契约：每个控制器公布一个进程绑定的非最终 readiness marker；在协调器校验两个 marker 并释放两个 owner-private 屏障之前，任何控制器都不得开始其 final-bounds 捕获。两个 attester 在发布响应后保持存活，只有在协调器写入其 owner-private release marker 后才退出。

实现流程（final-bounds 段）：

• 协调器等待两个final-bounds-ready.json，其completed_slot_ids必须恰好等于该控制器在 catalog 中除final-bounds外的槽位（测试中为mutation-001、protocol-130-001、checkpoint-001），且controller进程三元组必须与 readiness 阶段记录的完全一致；
• 在屏障释放前断言没有任何 receipt 存在（a controller crossed the final-bounds barrier before owner release）；
• 随后为每个控制器写final-bounds-start.json（phase: final-bounds），控制器才产出最后的 bundle 与 receipt。

测试final-bounds capture starts only after both process-bound controller readiness markers用FAKE_DELAY_FINAL_BOUNDS_READY=controller-b让 controller-b 延迟 250 ms 才发布 readiness，验证min(startTimes) >= max(readinessTimes)，即最慢的 readiness 决定屏障释放时刻。测试malformed final-bounds readiness fails before barrier release or finalization用FAKE_BAD_FINAL_BOUNDS_READY（把 start_identity 改成'1'）验证：两个控制器的final-bounds-start.json都不存在、finalizer 日志为空。

6. Monitor 密封、PID 绑定挑战与“调用者字段不可信”

契约条款：monitor 密封与 monitor/observer 挑战绑定 live PID 与精确证据字节。调用者写入的 success 或 certification 字段永不被接受。每个 attester 在发布响应后保持存活，只有在协调器写入其 owner-private release marker 后才退出。

6.1 密封语序

协调器把所有 fence、producer 集、基线/终态采样、violation/contamination 历史、崩溃基线/终态清单、foreground 计划、恢复摘要组装成monitorEvidence草稿，计算baselineCommitment（aggregateSHA256('monitor-baseline', …)，域前缀peekaboo.multi-target-certification.<domain>.v2\0）与historyCommitment（对含 6 个 fence 的历史投影做摘要），把草稿与seal-request.json写成私有文件后等待 monitor 自己写出密封证据与 seal receipt（密封段）。receipt 必须满足monitor_evidence_sha256 === aggregateSHA256('monitor-evidence', sealedEvidence)且密封证据与协调器草稿 canonical 相等；随后再核对 live heartbeat 与密封最终 fence 一致。测试monitor seal tampering is rejected before any finalizer invocation用FAKE_TAMPER_SEAL=1让假 monitor 把密封证据的execution_nonce改成全f，验证失败且 finalizer 日志为空（测试用例）。

6.2 PID 绑定挑战

runPIDAttestation（实现）为 monitor 与 observer 各发起一次挑战：

• 计划makeAttestationPlan含expected_peer（PID/start_identity/code_signature_hash 三元组）、response_kind（monitor或observer）、socket 路径、10 秒超时与 1 MiB 响应上限；
• 用controllerExecutable --attest-monitor <plan>派生 attester 子进程（即 Swift 侧的MonitorAttestationRunner/LocalPIDAttestation，源文件在 Apps/CLI/Sources/PeekabooCertificationController/）；attester 连接 owner-private Unix socket，向 monitor 发送 challenge，monitor 响应中必须回显expected_peer与证据摘要；
• monitor 响应的monitor_evidence_sha256必须等于aggregateSHA256('monitor-evidence', sealedEvidence)；observer 响应的witness_sha256必须等于见证文件字节本身的 SHA-256（且响应同时携带observation/restoration/before/expected/observed/restored六个摘要，见 期望键列表）；
• 挑战前后用requireOwnerSocket核对 socket 的(dev, ino)，任何变化都是an attestation endpoint changed during its PID-bound challenge；
• 协调器随后写release.json，attester 在close后等待 release 才退出；失败路径的finally保证 release 始终被写、并执行有界 TERM/KILL 清理。

测试PID-bound monitor digest mismatch is rejected before prepare用FAKE_BAD_ATTESTATION=monitor让 attester 篡改摘要，验证monitor PID attestation does not bind且prepare从未运行。这正是契约“调用者写入的 success 或 certification 字段永不被接受”的机制化表达：写心跳、证据、receipt 文件的行为都不能铸造 monitor 权威，权威只能通过内核 peer PID 的挑战响应获得（操作者文档 background-computer-use.md 对同一机制的叙述可作对照）。

7. 两阶段 finalizer：字节保留、独占 artifact root 与推导式外部超时

契约：协调器在 live run 之前保留已验证的 finalizer 字节，为两个阶段执行这些精确字节；prepare被授予对先前不存在的 artifact root 的独占所有权；其外部 deadline 由每次串行调用中全部八个有界 bundle 校验加上身份/运行时开销推导而来。

7.1 保留 finalizer 字节

retainFinalizerSource（实现）在生产模式下比对 finalizer 源投影的 SHA-256 与 catalog 的current_build_source.finalizer.projected_sha256（投影方式normalize-builtin-catalog-sha256-to-zero-v1，见 catalog），并用retainRegularFile以打开文件描述符 + 前后fstat比对的方式在 run 早期固定字节（changed while its exact bytes were retained防 TOCTOU）。

执行时finalizerCommand（实现）把保留的字节临时写入 staging 目录、打开读描述符后unlink，再通过>赞分享

• Peekaboo 精确窗口后台键盘行为契约:type、press、paste 如何不打扰前景完成投递

  Peekaboo 精确窗口后台键盘行为契约:type、press、paste 如何不打扰前景完成投递 Peekaboo 的 type 、 press 、 pas

  GUI 自动化MCP 服务AI 应用

• RustFS 后台控制器契约（Background Controller Contract）解析：无 Trait 的 Snapshot / Reconcile 控制面设计

  RustFS 后台控制器契约（Background Controller Contract）解析：无 Trait 的 Snapshot / Reconcile

  后端对象存储分布式存储

• RVC语音转换WebUI新手指南：10分钟音频，5分钟跑出你的专属变声器

  RVC语音转换WebUI新手指南：10分钟音频，5分钟跑出你的专属变声器 游戏开黑、直播连麦时想换一副声音，却不想折腾复杂的音频处理工具？RVC（Retriev

  人工智能AI 应用语音音频深度学习