feat: 外置插件一等公民——entry.renderer 宿主内 React 组件（.pi/extensions 一等插件源 + 开发版门控）

packages/plugin-sdk/package.json

@@ -6,7 +6,8 @@
   "description": "Inkreach harness 插件契约：清单/主进程工厂类型 + definePlugin + 插件页桥接 client（主入口给 main.mjs 作者，./client 给 iframe 页作者）",
   "exports": {
     ".": "./src/index.ts",
-    "./client": "./src/page.ts"
+    "./client": "./src/page.ts",
+    "./renderer": "./src/renderer.ts"
   },
   "scripts": {
     "typecheck": "tsc --noEmit"

packages/plugin-sdk/src/manifest.ts

@@ -28,6 +28,10 @@ export interface PluginManifest {
     page?: string
     /** 主进程模块（动态 import，默认导出 definePlugin 工厂） */
     main?: string
+    /** 渲染层模块（宿主动态 import `plugin://<id>/<renderer>`，
+     * 默认导出 mount(ctx)；React 组件用宿主实例（ctx.react），见 renderer 契约。
+     * 命名勿用 index.ts/index.js——那是 pi 原生扩展的自动发现名，会被 pi CLI 双重加载） */
+    renderer?: string
   }
   /** 外置插件遮蔽"组件级"内置插件时必须为 true（能力降级声明，
    * 防止带原生视图能力的内置被页面级外置静默顶掉） */

packages/plugin-sdk/src/renderer.ts

@@ -0,0 +1,38 @@
+/**
+ * 渲染层模块契约（entry.renderer，宿主渲染层动态 import 后调用默认导出 mount）。
+ * 与 main.mjs 契约并列：main 管 Agent 能力（pi），renderer 管宿主内 React UI。
+ *
+ * 单实例约束：组件必须使用 ctx.react（= 宿主 React）创建，插件自带 React 副本
+ * 会导致 hooks 全部失效。JSX 工程的构建配方见 docs/plugins.md（esbuild react 别名 shim）。
+ */
+import type { ComponentType } from 'react'
+import type { PluginManifest } from './manifest'
+
+/** 渲染层可用的注册槽位（每个插件各槽位一个组件，重复注册覆盖） */
+export interface PluginRendererSlots {
+  /** 整页视图（侧栏入口点击后的主内容区，与内置组件同槽位） */
+  registerView(component: ComponentType): void
+  /** 右侧 SidePanel tab 内容（需 manifest.panel: true） */
+  registerPanel(component: ComponentType): void
+}
+
+export interface PluginRendererContext extends PluginRendererSlots {
+  manifest: PluginManifest
+  /** 宿主 React 命名空间（window.__ASO_PLUGIN_HOST__.react 同一份实例） */
+  react: unknown
+}
+
+/** renderer.mjs 默认导出：mount(ctx)，同步执行注册后返回 */
+export type PluginRendererModule = (ctx: PluginRendererContext) => void
+
+/** 身份函数：为插件作者提供完整类型推断 */
+export function defineRenderer(module: PluginRendererModule): PluginRendererModule {
+  return module
+}
+
+/** 宿主注入到 window.__ASO_PLUGIN_HOST__ 的全局（插件构建期 react 别名 shim 消费） */
+export interface PluginHostGlobal {
+  react: unknown
+  /** react/jsx-runtime（esbuild --jsx=automatic 时 shim 消费） */
+  jsxRuntime: unknown
+}