[Jacobinwwey]

1. Context & Motivation (Context)

• Issue: Related to 作者有计划发布规则的 npm 包么，想使用这套规则 #9; this experimental package does not stabilize the rule schema or close that discussion.
• Problem: Extension entry points prevent scripts and agents from reusing StackPrism's real browser evidence. A settled-page snapshot also misses navigation and delayed endpoint headers, so agents need observation that preserves ownership of their authenticated browser and readiness flow.
• Trade-offs: Share the existing detector, rule preparation, header matcher and deduplication; use playwright-core instead of a second HTML matcher. Real browser evidence costs startup and approximately 19.6 MB of bundled rules. Proposed package is @stackprism/sdk@0.2.0, executable stackprism; scope and publishing access remain maintainer-controlled. Nothing has been published to npm.

Rebased onto upstream/main 58cf3c9, including merged #30–#32 and the upstream Vue Devtools false-positive correction. Those fixes are outside this PR's diff.

2. Implementation Details (Implementation)

• Share the extension's page detector, rule normalizer and precompiler. Keep extension invocation semantics, with cooperative budget checks for SDK use.
• Export three explicit operations: scanUrl(url) creates/closes its browser; detectPage(page) inspects a settled caller-owned page without fetching; await observePage(page) attaches before caller navigation and returns a one-use detect() / dispose() session. No mode switch or SDK-owned agent navigation.
• Observation has one deadline across rules loading, caller waiting and detection. Success, failure, timeout, abort, close and explicit disposal detach listeners; disposal interrupts active detection. Caller Playwright operations retain their own cancellation/timeouts. Missing navigation headers remain not_observed; detection sends no recovery requests.
• Retain current document headers across SPA history changes; replace them after observed reloads. Reject main-frame navigation during detection with PAGE_CHANGED. Isolate subresource generations, retain at most 64 responses and at most 64 active header reads; expose skipped/failed counters. Keep endpoint technologies in network.responses rather than promoting them to site detections; omit credentials/query/fragment from network URLs.
• Return schema/engine/rule versions, rule SHA-256, evidence, confidence grades and explicit coverage. CLI emits one JSON report on stdout or a structured error on stderr, with stable exit codes.
• Add bilingual SDK contracts and CLI help covering API choice, application readiness, lifecycle, retry boundaries, endpoint attribution and untrusted evidence/prompt injection. Include an opt-in Bing baseline and Linux/Windows CI with explicit test-only Chromium installation; the SDK downloads no browser.
• Note: A local analysis primitive with private-network access allowed. Service deployment needs separate egress isolation and quotas. Frame internals, continuous mutation tracking, license-bundle sampling and supplementary WordPress fetches remain unobserved. Cleanup can extend wall time; JS timers do not preempt arbitrary synchronous scripts. Confidence grades are not probabilities, and merged source labels are not a provenance graph. Chrome is locally verified; other engines are unverified.

3. Testing Strategies (Validation)

• 36/36 unit tests: inherited rule preparation, extension regressions, response generations/read limits/failures and baseline evaluation.
• 22/22 real-Chrome SDK/CLI integration tests, no skips: owned/caller resources, pre-navigation observation, missed headers, delayed fetches, redirects, HTTP errors, endpoint attribution, iframe exclusion, same-URL reload, SPA history, one-use/concurrent detection, idle/active timeout/abort/disposal/close, argument validation and CLI streams/exit codes.
• ESLint, vue-tsc, production extension build, VitePress build, Prettier and git diff --check pass on the rebased branch. Existing Sass/bundle-size warnings remain.
• Pack the actual npm tarball, install offline outside the repository, compile strict NodeNext imports including PageObservation without skipLibCheck, and run real-browser SDK/observation/CLI smoke from that installation.
• Bing live baseline (2026-10-18): 8/8 assertions, HTTP 200 at cn.bing.com; 38 captured responses, zero skipped/failed. Windows x64, Node 22.19.0, Bun 1.3.11, installed Chrome. Rules 1.3.90 SHA-256: 09056a5ed496e74f395e0ca7a59211bd8a1f7cc9fc40ba1d649f17bbde2d7ef6.
• Existing extension rule tests and production build exercise the shared implementation; snapshot ownership/no-fetch behavior remains covered.
• Remote Linux and Windows CI pass at final HEAD 06f1cba, including unit/browser integration tests, lint, typecheck and extension build: https://github.com/setube/stackprism/actions/runs/39083399594 . Workflow Actions are pinned to verified official release commits.
• Performance: Rules load O(R) once per process. Sampling adds O(K) retained slots and at most K existing matcher invocations per document, K=64; matcher cost depends on rules/input. Outstanding reads are bounded separately; request-generation WeakMap entries scale with referenced requests, so total memory is not claimed O(64). Tarball is ~1.5 MB compressed/~19.7 MB unpacked. Latest Bing capture took 5366 ms including a 1000 ms observation window; this is one observation, not an accuracy measurement or before/after benchmark.

[Jacobinwwey]

Review follow-up summary

The three review findings belong to the independent fix PRs, and their signed follow-up commits are already pushed:

• fix(popup): return localization keys for unsupported pages #30 — f6375bc: assert exact unsupported-page fallback messages, including Chrome/Edge variants, while preserving HTTP(S) behavior.
• fix(rules): restrict jQuery patterns to resource URLs #31 — 590404f: restrict the duplicate dynamic-snapshot jQuery rule to resource URLs and add a title-negative/script-positive regression; runtime globals and resource versions remain covered.
• fix(build): restore the supported validation toolchain #32 — 6fa04cb: remove premature translation output and verify entries from the first and final translation groups when running the ESM generator from another working directory.

These fixes are also present in Jacobinwwey/stackprism on integration/agent-cli-sdk at 0849b52. They remain outside this feature PR to preserve atomic scope. No history was rewritten.

Revalidated on the combined branch: 36/36 unit tests, 13/13 real-Chrome SDK integration tests (no skips), ESLint, vue-tsc, and the production extension build. Each fix PR also passes its focused regression independently. Existing bundle-size/build-option warnings remain. This is combined-branch validation; it does not claim that the standalone feature branch passes without its toolchain prerequisite (#32) and the existing popup type fix (#30).

This PR remains draft pending prerequisite integration and maintainer agreement on the package namespace/API. No npm package has been published. There are currently no review comments on this feature PR.

[setube]

感谢这份详尽的提案。

方向接受：同意将检测引擎抽成可复用的 Node.js SDK/CLI 包，用 Playwright 驱动真实浏览器。

合并前需要确认的几点：

1. 包命名空间：使用 @stackprism/sdk 还是 stackprism？请给出你的建议。
2. 前置依赖：PR fix(popup): return localization keys for unsupported pages #30、fix(rules): restrict jQuery patterns to resource URLs #31、fix(build): restore the supported validation toolchain #32 已合并，可以基于最新 main rebase。
3. 草稿状态：请在 rebase 完成并确认所有测试通过后将其标记为 ready for review。

其他方面（API 接口、private-network 策略、观察窗口默认值）都在可接受范围内。

[Jacobinwwey]

感谢确认。建议使用 @stackprism/sdk，CLI 命令继续保留 stackprism；npm scope 和发布权限由项目维护者控制。我会基于最新 main rebase，补齐现有 Playwright 页面在导航前建立网络观察的能力及 agent 使用文档，完成全部验证后标记 ready for review。

[sourcery-ai]

Sorry @Jacobinwwey, your pull request is larger than the review limit of 150,000 diff characters

[Jacobinwwey]

已完成并标记 ready for review。

使用 @stackprism/sdk 还是 stackprism？

采用 @stackprism/sdk，可执行命令仍为 stackprism。包元数据指向上游仓库，scope 与发布权限由维护者控制；本次未发布 npm。

PR #30、#31、#32 已合并，可以基于最新 main rebase。

已 rebase 到 58cf3c9，同时保留上游 Vue Devtools 误报修复。相关 bugfix 不再出现在本 PR diff 中。此次仅为落实 rebase 使用精确旧 SHA 的 force-with-lease；后续 CI 修正均为追加的 DCO sign-off 提交。

这轮补齐的实际 agent 缺口：

• 新增 await observePage(page) → detect()/dispose()：在 agent 自行导航前建立观察，复用登录态和交互流程，捕获主文档及后续端点头。仍复用项目检测器、规则准备、header matcher 与去重；detectPage 保持无网络快照，scanUrl 复用同一观察实现。
• 明确一次性／并发消费、幂等释放、总预算、取消和页面关闭契约；闲置或检测中发生中断都释放监听器，不关闭调用方资源、不补发请求。缺失的导航头标记 not_observed；重载替换文档头，SPA history 保留文档头，检测时导航返回 PAGE_CHANGED。
• 保留 64 条响应／64 个在途读取上限及 skipped/failed 计数，端点技术不混入主站技术。CLI help 与中英 SDK 文档补齐 API 选择、业务就绪、coverage、重试、资源归属和不可信证据边界。
• 新增 Linux/Windows CI，显式安装测试浏览器，Action 固定到已核对的官方 release commit；SDK 本身不下载浏览器。

验证：36/36 单元测试、22/22 真实浏览器 SDK/CLI 测试（无跳过）；lint、vue-tsc、扩展构建、文档构建、格式和 diff 检查通过。实际 tarball 在仓库外离线安装，通过严格 NodeNext 类型编译（无 skipLibCheck）与 SDK/observePage/CLI 浏览器实测。Bing 2026-10-18 实测 8/8，HTTP 200，38 条响应、零 skipped/failed。

最终 HEAD：06f1cba。Linux 与 Windows 远端 CI 均通过： https://github.com/setube/stackprism/actions/runs/39083399594 。fork 的 integration/agent-cli-sdk 已同步；完整契约见 packages/stackprism/README.md。

[setube]

已合并（e16c1a5），谢谢。本地 Windows + Chrome 又跑了一遍：单测 36/36、SDK 浏览器测试 22/22、扩展构建正常，规则产物和合并前逐字节一致。