Skip to content

[PR] feat: POST /__bili/plugin/protect — durable-registration aux channel (#2556) - #2574

Closed
ranxianglei wants to merge 1 commit into
2026-10-09_bili-durable-markerfrom
2026-10-09_plugin-protect-tool
Closed

ranxianglei wants to merge 1 commit into
2026-10-09_bili-durable-markerfrom
2026-10-09_plugin-protect-tool

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Stacked on #2557 (marker guard composition lands there first) — base is the marker branch; it retargets to master automatically when #2557 merges.

Fixes #2556

What

POST /__bili/plugin/protect — server-side durable registration, the aux channel of the durable protocol. Body {conversationId, refs: [mNNNNN...], clear?}; refs resolve to raw content ids held in session.metadata.protectedRawIds (union on register, subtract on clear; empty set deletes the key). Registered raw ids compose into the same isMessageProtected guard as the marker (#2555) and lane guards, at both resolution sites: the wire path (src/server/handle.ts) and the read path (session.ts effectiveConfig), so a registration protects the very next fold on either surface. Manifest advertises protectEndpoint.

Why an aux channel (and why the marker stays primary)

The durable truth is content-embedded declaration: registration is session-keyed state, which fork raw-replay (#2383), cross-machine exports and proxy-mode re-sends do not carry. What registration buys instead: zero content pollution (no marker line in host-visible text) and post-hoc protection of a message emitted before the host learned the protocol. Ids are never reused (kernel contract), so a registration stays pinned to its message even after it dies.

Validation contract (loud, no guessing)

  • 400 INVALID_REQUEST: missing conversationId / refs not a non-empty mNNNNN array / clear not boolean
  • 400 UNKNOWN_REF naming the never-assigned refs (a typo cannot silently protect nothing)
  • 404 NOT_FOUND conversation not resident
  • idempotent re-registration (changed: 0); flushSync on mutation (warn + debounced retry on failure), same as the fork endpoint

Tests (tests/issue2556-protect-tool.test.ts, 4/4)

validation matrix · lane-less session: registered ref survives a positional fold that swallows its neighbors, then folds away after clear (registration was the only protection) · composition: marker + registration co-protected in one session · manifest advertises the endpoint.

Local verification: new suite 4/4; regression family issue2555/2446/2419/2447/2481 22/22; plugin-fork 43/43; ccr-plugin 12/12; dsh-acp 11/11; issue760 8/8; typecheck clean. (dsh-native / dsh-settings-ui / issue2082 hang or fail on this machine at the PR base too — environmental, CI arbitrates.)

Guardrail check (§7.4)

feat + new plugin-protocol endpoint => human merge by definition. No kernel change (isMessageProtected consumed as-is), no config surface, no persistence format change (metadata key is additive and clone-safe), no wire/message-shape change to model traffic.

…2556)

The marker (#2555) stays the durable truth; registration buys zero content
pollution and post-hoc protection. Refs resolve to raw ids into
session.metadata.protectedRawIds (persisted, fork-adoption clone-safe,
id-never-reused keeps registrations pinned), composed into the same
isMessageProtected guard at both resolution sites. Manifest advertises
protectEndpoint; PLUGIN.md documents the contract.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到,开始按 PR Review 规范审查 #2574(基于 #2557 分支的堆叠 PR)。步骤:审原 issue #2556 → 取分支通读 diff(高危域:plugin-protocol 端点、effectiveConfig 读路径、manifest)→ 回归审查既有点(fork 端点 / lane guard / marker guard 组合语义)→ 本地定向跑新套件 + 回归族 + typecheck → CI 状态。结论按结构化八问回复,有发现的小问题会直接修或立项。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 PR #2574 review — 可合(人工合并)

验证了什么(在 head 1135bb05b 上实测,非仅读 diff):

  • 本地定向测试 100/100:新套件 issue2556 4/4 + 回归族 issue2555/2446/2419/2447/2481/plugin-fork/ccr-plugin/dsh-acp/issue760,与 PR 声明的分解 (4+22+43+12+11+8) 完全一致;npm run typecheck clean。
  • CI:head sha 上已触发的 8 条 e2e lane(native-pi/native-dsh/codex-persona/fake-codex/dsh-plugin-lane/native-opencode/pi-codex-ws/local-registry)全绿。主 unit CI(ci.yml)只触发 pull_request → master,堆叠 PR 在 retarget 前不跑——设计使然,feat: lane-less <bili-durable> self-declaration marker for durable-state carriers (#2555) #2557 合并后自动补跑。
  • 逐点核查:路由门控、guard 解析点穷举、fork 白名单、持久化往返、kernel id 语义(见下)。

结构化八问:

  1. 是什么问题:插件宿主需要一条不污染消息内容、且可对协议学会之前已发出的消息事后生效的持久保护通道;marker 做不到这两点。
  2. 什么原因导致的(机制分层):保护真值分两层——marker 是内容内嵌声明,随字节走(fork raw-replay、跨机导出、proxy 模式重发都带得动),是 durable truth;注册是会话键控状态,实例本地真值,换的是零内容污染 + 事后保护。id 永不复用(kernel 契约),注册钉死在消息上即使消息已死。实现与 plugin lane: /__bili/plugin/protect tool (server-side equivalent registration, auxiliary channel) #2556 owner 拍板的 marker主/tool辅 分层一致,identifiers 收窄到 refs-only 也符合你在该线程确认的形状。
  3. 影响范围与严重程度:纯新增 opt-in 能力。零注册时行为与基线逐字节等价(registered=∅ ⇒ guard ≡ 旧 guard);端点不调用即不可达;manifest 仅加一个字段,老宿主忽略未知键。无缺陷语义,严重度不适用。
  4. 怎么修复的:ref → raw content id 解析后并入 session.metadata["protectedRawIds"](union / clear 减法 / 空集删键),在仅有的两个 guard 解析点(wire path src/server/handle.ts、read path src/session.ts effectiveConfig)读时合成进既有 isMessageProtected 谓词;响亮验证契约(INVALID_REQUEST / UNKNOWN_REF 点名坏 ref / NOT_FOUND,拒绝发生在任何变更之前,原子);flushSync 落盘同 fork 端点先例(fail→warn+debounced retry)。
  5. 是否有回归问题:审过的既有行为逐项——①路由门控:新路由落在整个 /__bili/plugin/* 家族共用的 loopback+trusted-origin 门之下(admin.ts:277-281),覆盖正确;②guard 解析点穷举:全 src 仅两处消费 isMessageProtected,均已更新且形状一致,无第三处漏网;③fork 子会话:plugin.ts:1219 元数据白名单不含 protectedRawIds,子会话不继承注册——与文档下一 bullet「forks must re-register」自洽,「carried through fork adoption」指 adoption 机制本身 clone-safe(string array,structuredClone-safe),不构成文档错误;④重启持久化:checkpoint 存 {...session.metadata},恢复 parsed.metadata ?? {},ephemeral key 删除清单不触碰该键,声明成立;⑤并发:handler 体内无 await,锁外同步变更安全,flushSync 模式与家族一致;⑥kernel id 语义:CoreMessage.id 即 raw content id(kernel/src/ccr.ts:524,634),guard 比对成立。未发现回归。注:protectedRawIds 单调增长(死 id 不清理)属设计内——id 不复用,无正确性风险,字节量有界。
  6. 是否破坏缓存:不涉及。未触碰缓存/重试/增量游标/去重逻辑;保护只收窄折叠范围(预期行为,与已在生产的 marker/lane guard 同类机制)。
  7. 是否改了设计方向:否。按 plugin lane: /__bili/plugin/protect tool (server-side equivalent registration, auxiliary channel) #2556 拍板的方向扩展 durable 协议;kernel 原样消费(Config.isMessageProtected hook),无内核改动,无 wire/message-shape 变更,无 config/env/CLI 新增。
  8. 是否引入了新的配置:否。端点经 manifest protectEndpoint 发现,无新 env/config/默认值。

测试有效性:断言有牙——行为级 e2e(折叠存活、clear 后再折叠被吞掉证明注册是唯一保护、marker+注册组合、幂等 changed:0、metadata 精确等于 byRef[target]、错误码点名坏 ref),该 bug 回归时抓得住。两个已知缺口(可接受,不拦):新套件未含重启持久化测试(机制与其他 metadata key 共用,round-trip 由其他套件覆盖);测试折叠走 plugin-tool=read path,wire-path guard 为同形代码隐式覆盖。

Guardrail:feat + 新插件协议端点 ⇒ §7.4 定义上人工合并,PR 自检标记正确。

判定:可合。 前置条件仅堆叠依赖:#2557 先落,retarget 后等主 unit CI 绿。本地证据链完整(100/100 + typecheck + 8/8 e2e),无需再改。

@ranxianglei

Copy link
Copy Markdown
Owner Author

后续重新设计

@ranxianglei ranxianglei changed the title feat: POST /__bili/plugin/protect — durable-registration aux channel (#2556) [PR] feat: POST /__bili/plugin/protect — durable-registration aux channel (#2556) Oct 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant