[REQ-128][CODE] 用通用详情页呈现 package 兼容、组件与 prerequisite #695

⚠️ 本期范围裁决（2026-07-30，owner）—— 优先于下方原文与基线

REQ-128 分四相，本期只做 Phase 1、只支持单组件 package。裁决见
alpha-work#49。

一、上游已交付（本票只消费它，不自己推导任何 installability）

alpha-code#702 已合并（691f5a57）。CatalogPackageViewV1
（packages/ui-mac/src/shared/catalog-package-view.ts）已冻结为：

{ catalogId, verdict: "compatible"|"update-required"|"blocked",
  action: { kind: "install"|"update-alpha"|"resolve-prerequisite"|"none", enabled, reasonCode },
  prerequisites: { status: "ready"|"required-action", items: [{prerequisiteId,label,required}] },
  presentation: { displayName, description, version } }

零 payload、零 URL、零 config、零 secret target。 renderer 拿到的就是这些，没有别的。

二、本票被删除的范围（不实现，不写它们的测试，不留插槽）

• skippedOptional[] —— 单组件 package 没有 optional child，safe view 里根本没这个字段；
• prerequisite 的 optional-disconnected 状态 —— 属 Alpha Connection（#704，Phase 2）；
• Acceptance 里 「Skill/MCP/Agent/Plugin/mixed Bundle 共用同一页面」 的
  Plugin 与 mixed Bundle 两项 —— Phase 1 的 profile 闭包只有
  skill / agent / mcp-local / mcp-remote（无 cloud、无 Plugin、无 Bundle）；
• Development plan 第 1 条里的 skippedOptional。

三、设计稿：不另开设计轮，以已批基线 §2.5 为准

本票是已批页面上的状态与数据源增量，不是新页面/新 IA：基线 §2.5 已经冻结了
五个 canonical state 组合与固定信息顺序，并明写「现有页面布局、card 与明暗 token 不变；
这是状态和数据源增量，不另造通用 UI framework」。因此照 §2.5 实现，
不重画 IA、不新增 gallery/media proxy/HTML/SVG/iframe。

但 L2 视觉证据仍是本票的退出门：named req128-package-detail，
五个 canonical state × pairwise（light/dark、长文本、无 icon、键盘焦点），不跑完整乘积。

四、从前四票八轮审计带进来的四条硬要求

1. 断言返回值，不要断言源码文本。（#696 R1：零回显闸读 7 个源文件，
   而真实组装点不在清单里 ⇒ 两个绕过全绿。）
2. 闸门要测我们真走的那条路。（#696 R2：canary 闸靠改 entry.source 才够得着分支，
   而真实 catalog 里那个形状一条都没有。）写任何闸门前先问：走我们自己的 catalog 到得了吗？
   本票尤其注意：真实 Catalog 里今天 0 个 package，你的用例必然是构造的 ——
   像 #702 那样显式标注，不要假装它已经在跑。
3. 闸门要测生产入口，不是你自己拼的等价链。（#702 R1 Blocker：wiring 用例自己拼四条链，
   五处真实接线任删其一全量仍全绿。）
4. 绿的理由必须是你声称的那个。（#702 R2：编排者自己写的用例在变异下也绿 ——
   因为输入先被另一条更早的规则拒掉、根本走不到被测的门。necessary 时加一条断言把理由钉死。）

五、反过度工程（owner 直令）

复用现有 extension-detail.tsx 与 card、现有 i18n 机制、现有明暗 token。
不新建通用 UI framework / 状态机 / registry；不引入新依赖；
不为 Phase 2/3/4 预留插槽、空接口、TODO 钩子；不做预防性抽象。
发现超范围缺陷写回票，不顺手修。

UI 文案纪律：产品界面与设计稿内禁止出现 REQ 号、票号、内部术语。

Outcome

复用现有 ExtensionDetail/card，以数据驱动方式呈现 package、组件、能力、认证与兼容状态；
不为 provider/Bundle 建硬编码页面，不让 renderer 推测 installability。

Covers

alpha-work#49 AC3/AC4/AC7。

Solution baseline

Accepted REQ-128 baseline
§2.5 的 UI state/data-source baseline。

Boundary and development plan

• packages/ui-mac/src/renderer/extensions/extension-detail.tsx
• existing extension card/detail styles与i18n
• pure state mapper/wiring tests；不接raw installSpec

1. 只消费 alpha-code#702 的 CatalogPackageViewV1：
   verdict compatible/update-required/blocked、main-owned action/reasonCode、
   skippedOptional、prerequisite status与bounded presentation。
2. 固定信息顺序：identity/provenance → installability → components →
   capabilities/runtime/download → prerequisites → Compatibility summary → action。
3. reasonCode用本地i18n；provider文案不能决定安全原因/按钮。
4. update-required/blocked不调用install IPC；点击其他action后main仍重判。
5. v1复用现有icon，不做gallery/media proxy/HTML/SVG/iframe。

Acceptance and named gates

• ext-package-presentation.test.ts exhaustive safe-view union mapping。
• production wiring证明renderer不接execution payload/config/secret target。
• named L2 req128-package-detail：五个canonical states，pairwise覆盖light/dark、
  long text、no icon、focus/a11y；不跑完整乘积。
• Skill/MCP/Agent/Plugin/mixed Bundle共用同一页面。

Dependencies

Blocked by alpha-code#702。

Out of scope

provider-specific页面、远程HTML/JS、screenshot gallery、认证协议实现。

Exit condition

Merged UI PR + unit/wiring + L2 visual evidence + i18n/docs同步。