xinyu-pro 0.21.0

package/lib/plugin-security.ts

@@ -0,0 +1,151 @@
+// lib/plugin-security.ts - 插件安全与权限检查工具
+
+import { UIPermission, PluginManifest, UISlotId } from './plugin-types';
+import { checkAppVersion } from './version';
+
+/** 默认共享权限集（插件未声明 commonPermissions 时使用） */
+const DEFAULT_COMMON_PERMISSIONS: UIPermission[] = [
+  'slot:input-toolbar',
+  'style:inject',
+  'modal:confirm',
+];
+
+/**
+ * 获取插件的有效共享权限列表（commonPermissions + exclusivePermissions 或默认权限集）
+ */
+export function getEffectivePermissions(manifest: PluginManifest): UIPermission[] {
+  const common = manifest.commonPermissions || [];
+  const exclusive = manifest.exclusivePermissions || [];
+  if (common.length > 0 || exclusive.length > 0) {
+    return [...common, ...exclusive];
+  }
+  return DEFAULT_COMMON_PERMISSIONS;
+}
+
+/**
+ * 检查插件是否具有指定共享权限
+ */
+export function checkUIPermission(
+  manifest: PluginManifest,
+  permission: UIPermission
+): boolean {
+  const permissions = getEffectivePermissions(manifest);
+  return permissions.includes(permission);
+}
+
+/**
+ * 检查插件是否具有指定插槽的注入权限
+ */
+export function checkSlotPermission(
+  manifest: PluginManifest,
+  slotId: UISlotId
+): boolean {
+  return checkUIPermission(manifest, `slot:${slotId}` as UIPermission);
+}
+
+/**
+ * 检查插件是否具有自由 DOM 操作权限
+ */
+export function checkDOMPermission(manifest: PluginManifest): boolean {
+  return checkUIPermission(manifest, 'dom:free');
+}
+
+/**
+ * 检查插件是否具有样式注入权限
+ */
+export function checkStylePermission(manifest: PluginManifest): boolean {
+  return checkUIPermission(manifest, 'style:inject');
+}
+
+/**
+ * 检查插件是否具有模态框权限
+ */
+export function checkModalPermission(manifest: PluginManifest): boolean {
+  return (
+    checkUIPermission(manifest, 'modal:confirm') ||
+    checkUIPermission(manifest, 'modal:custom')
+  );
+}
+
+/**
+ * 检查插件是否具有宿主事件监听权限
+ */
+export function checkHostEventPermission(manifest: PluginManifest): boolean {
+  return checkUIPermission(manifest, 'event:host');
+}
+
+/**
+ * 验证权限声明是否有效
+ */
+export function validatePermissions(permissions: UIPermission[]): {
+  valid: boolean;
+  invalid: string[];
+} {
+  const validPermissionPattern = /^(slot:[\w-]+|slot:style:[\w-]+|dom:free|dom:query|style:inject|modal:confirm|modal:custom|event:host|storage:plugin|file:read|file:write|game:info:read|game:info:write|input:control)$/;
+  const invalid = permissions.filter((p) => !validPermissionPattern.test(p));
+  return { valid: invalid.length === 0, invalid };
+}
+
+/**
+ * 检查插件的 minAppVersion 是否满足当前应用版本
+ * @returns { satisfied, current, required } — satisfied 为 false 时表示版本不兼容
+ */
+export function checkPluginVersionCompat(manifest: PluginManifest): {
+  satisfied: boolean;
+  current: string;
+  required: string;
+  warning?: string;
+} {
+  if (!manifest.minAppVersion) {
+    return { satisfied: true, current: '', required: '' };
+  }
+  const result = checkAppVersion(manifest.minAppVersion);
+  return {
+    ...result,
+    warning: result.satisfied
+      ? undefined
+      : `插件「${manifest.name}」要求星语 Pro v${result.required} 或更高版本，当前版本为 v${result.current}，部分功能可能不可用`,
+  };
+}
+
+/**
+ * 检查插件是否具有持久化存储权限
+ */
+export function checkStoragePermission(manifest: PluginManifest): boolean {
+  return checkUIPermission(manifest, 'storage:plugin');
+}
+
+/**
+ * 检查插件是否具有文件读取权限
+ */
+export function checkFileReadPermission(manifest: PluginManifest): boolean {
+  return checkUIPermission(manifest, 'file:read');
+}
+
+/**
+ * 检查插件是否具有文件写入权限
+ */
+export function checkFileWritePermission(manifest: PluginManifest): boolean {
+  return checkUIPermission(manifest, 'file:write');
+}
+
+/**
+ * 检查插件是否具有输入框控制权限
+ */
+export function checkInputControlPermission(manifest: PluginManifest): boolean {
+  return checkUIPermission(manifest, 'input:control');
+}
+
+/**
+ * 检查插件是否具有游戏信息读取权限
+ */
+export function checkGameInfoPermission(manifest: PluginManifest): boolean {
+  return checkUIPermission(manifest, 'game:info:read');
+}
+
+/**
+ * 检查插件是否具有游戏信息写入权限
+ */
+export function checkGameInfoWritePermission(manifest: PluginManifest): boolean {
+  return checkUIPermission(manifest, 'game:info:write');
+}

package/lib/plugin-types.ts

@@ -0,0 +1,416 @@
+// lib/plugin-types.ts - 插件系统 TypeScript 类型定义
+
+/** 插件类型枚举 */
+export type PluginType = 'game-mechanics' | 'message-render' | 'ai-prompt' | 'input-enhance';
+
+/** 插件类型标签映射 */
+export const PLUGIN_TYPE_LABELS: Record<PluginType, { label: string; icon: string }> = {
+  'game-mechanics': { label: '游戏机制', icon: '🎮' },
+  'message-render': { label: '消息渲染', icon: '🎨' },
+  'ai-prompt': { label: 'AI Prompt', icon: '🤖' },
+  'input-enhance': { label: '输入增强', icon: '⌨️' },
+};
+
+/** 插件生命周期钩子 */
+export type PluginHook =
+  | 'onLoad'                // 插件自身加载完成时触发（参数：pluginId）
+  | 'onPluginLoad'          // 任意插件加载完成时触发（参数：被加载插件的 pluginId）
+  | 'onUnload'              // 插件卸载时触发（无参数）
+  | 'onGameInit'            // 游戏初始化：进入游戏且无聊天记录时触发（无参数）
+  | 'onPluginBindingWorld'  // 插件被绑定到世界时触发（参数：worldId）
+  | 'onConfigChange'        // 插件自身配置变更时触发（参数：config）
+  | 'onGlobalConfigChange'  // 任意插件配置变更时触发（参数：pluginId, config）
+  | 'onRenderMessage';      // 消息渲染前触发（参数：{ role, content }），返回修改后的 content
+
+/** 插件配置项定义 */
+export interface PluginConfigField {
+  key: string;
+  label: string;
+  type: 'text' | 'number' | 'boolean' | 'select' | 'textarea';
+  defaultValue: string | number | boolean;
+  description?: string;
+  options?: { label: string; value: string }[];
+}
+
+/** UI 插槽类型（旧版，保留兼容） */
+export type UISlotType = 'game-sidebar' | 'game-header' | 'game-input-toolbar' | 'message-bubble' | 'settings-panel';
+
+/** UI 插槽注册（旧版，保留兼容） */
+export interface UISlotRegistration {
+  slot: UISlotType;
+  component: string;
+  priority?: number;
+}
+
+// ==================== 全局 UI API 类型 ====================
+
+/** UI 插槽 ID（新版，游戏页面全区域） */
+export type UISlotId =
+  | 'header-left'
+  | 'header-center'
+  | 'header-right'
+  | 'sidebar-left'
+  | 'sidebar-right'
+  | 'message-top'
+  | 'message-bottom'
+  | 'input-toolbar'
+  | 'input-above'
+  | 'status-bar'
+  | 'floating'
+  | 'overlay';
+
+/** 所有可用插槽 ID 常量 */
+export const UI_SLOT_IDS: UISlotId[] = [
+  'header-left', 'header-center', 'header-right',
+  'sidebar-left', 'sidebar-right',
+  'message-top', 'message-bottom',
+  'input-toolbar', 'input-above',
+  'status-bar', 'floating', 'overlay',
+];
+
+/** 插槽 ID 的中文标签映射 */
+export const UI_SLOT_LABELS: Record<UISlotId, string> = {
+  'header-left': '顶部导航栏-左侧',
+  'header-center': '顶部导航栏-中间',
+  'header-right': '顶部导航栏-右侧',
+  'sidebar-left': '左侧边栏',
+  'sidebar-right': '右侧边栏',
+  'message-top': '消息区域-上方',
+  'message-bottom': '消息区域-下方',
+  'input-toolbar': '输入框工具栏',
+  'input-above': '输入框-正上方',
+  'status-bar': '底部状态栏',
+  'floating': '浮动层',
+  'overlay': '全屏遮罩层',
+};
+
+/** 插槽注册项 */
+export interface SlotRegistration {
+  id: string;
+  pluginId: string;
+  slotId: UISlotId;
+  content: string;
+  priority?: number;
+  persistent?: boolean;
+}
+
+/** 模态框操作按钮 */
+export interface ModalAction {
+  text: string;
+  primary?: boolean;
+  danger?: boolean;
+  onClick: () => void;
+}
+
+/** 模态框操作（插件声明时，onClick 接收上下文参数） */
+export interface ModalActionInput {
+  text: string;
+  primary?: boolean;
+  danger?: boolean;
+  onClick: (ctx: { modalId: string; close: () => void }) => void;
+}
+
+/** 模态框注册项 */
+export interface ModalRegistration {
+  id: string;
+  pluginId: string;
+  title: string;
+  content: string;
+  width?: string;
+  style?: React.CSSProperties;
+  closable?: boolean;
+  backdrop?: boolean;
+  onClose?: () => void;
+  actions?: ModalAction[];
+}
+
+/** 确认对话框选项 */
+export interface ConfirmOptions {
+  confirmText?: string;
+  cancelText?: string;
+  danger?: boolean;
+}
+
+/** 宿主事件映射 */
+export interface HostEventMap {
+  'message:received': { message: { role: string; content: string } };
+  'message:sent': { content: string };
+  'game:stateChange': { changedKeys: string[] };
+  'sidebar:open': undefined;
+  'sidebar:close': undefined;
+  'input:focus': undefined;
+  'input:blur': undefined;
+  'theme:change': { themeId: string };
+  'plugin:enabled': { pluginId: string };
+  'plugin:disabled': { pluginId: string };
+}
+
+/** UI 权限类型（通用权限标识符，可用于 common/exclusive/required 三种模式） */
+export type UIPermission =
+  | 'slot:header-left'
+  | 'slot:header-center'
+  | 'slot:header-right'
+  | 'slot:sidebar-left'
+  | 'slot:sidebar-right'
+  | 'slot:message-top'
+  | 'slot:message-bottom'
+  | 'slot:input-toolbar'
+  | 'slot:input-above'
+  | 'slot:status-bar'
+  | 'slot:floating'
+  | 'slot:overlay'
+  | 'dom:free'
+  | 'style:inject'
+  | 'modal:confirm'
+  | 'modal:custom'
+  | 'event:host'
+  | 'dom:query'
+  // 数据与文件权限
+  | 'storage:plugin'   // 插件持久化存储（key-value，页面刷新后保留）
+  | 'file:read'        // 读取插件私有目录下的文件
+  | 'file:write'       // 写入/删除插件私有目录下的文件
+  // 游戏数据权限
+  | 'game:info:read'   // 读取游戏世界信息（世界设定、会话ID、消息列表、游戏属性）
+  | 'game:info:write'  // 写入游戏世界设定（修改世界信息，实时生效并持久化）
+  // 输入框控制权限
+  | 'input:control'    // 控制聊天输入框（内容、样式、状态、事件）
+  /** 排他权限专用：独占插槽样式 */
+  | 'slot:style:header-left'
+  | 'slot:style:header-center'
+  | 'slot:style:header-right'
+  | 'slot:style:sidebar-left'
+  | 'slot:style:sidebar-right'
+  | 'slot:style:message-top'
+  | 'slot:style:message-bottom'
+  | 'slot:style:input-toolbar'
+  | 'slot:style:input-above'
+  | 'slot:style:status-bar'
+  | 'slot:style:floating'
+  | 'slot:style:overlay';
+
+/** UI 权限标签映射 */
+export const UI_PERMISSION_LABELS: Record<UIPermission, string> = {
+  'slot:header-left': '顶部导航栏-左侧',
+  'slot:header-center': '顶部导航栏-中间',
+  'slot:header-right': '顶部导航栏-右侧',
+  'slot:sidebar-left': '左侧边栏',
+  'slot:sidebar-right': '右侧边栏',
+  'slot:message-top': '消息区域-上方',
+  'slot:message-bottom': '消息区域-下方',
+  'slot:input-toolbar': '输入框工具栏',
+  'slot:input-above': '输入框-正上方',
+  'slot:status-bar': '底部状态栏',
+  'slot:floating': '浮动层',
+  'slot:overlay': '全屏遮罩层',
+  'dom:free': '自由 DOM 操作',
+  'style:inject': '样式注入',
+  'modal:confirm': '确认对话框',
+  'modal:custom': '自定义模态框',
+  'event:host': '宿主事件监听',
+  'dom:query': 'DOM 查询',
+  'storage:plugin': '持久化存储',
+  'file:read': '文件读取',
+  'file:write': '文件写入',
+  'game:info:read': '游戏信息读取',
+  'game:info:write': '游戏信息写入',
+  'input:control': '输入框控制',
+  'slot:style:header-left': '独占-顶部导航栏左侧样式',
+  'slot:style:header-center': '独占-顶部导航栏中间样式',
+  'slot:style:header-right': '独占-顶部导航栏右侧样式',
+  'slot:style:sidebar-left': '独占-左侧边栏样式',
+  'slot:style:sidebar-right': '独占-右侧边栏样式',
+  'slot:style:message-top': '独占-消息区域上方样式',
+  'slot:style:message-bottom': '独占-消息区域下方样式',
+  'slot:style:input-toolbar': '独占-输入框工具栏样式',
+  'slot:style:input-above': '独占-输入框正上方样式',
+  'slot:style:status-bar': '独占-底部状态栏样式',
+  'slot:style:floating': '独占-浮动层样式',
+  'slot:style:overlay': '独占-全屏遮罩层样式',
+};
+
+// ==================== 原有类型（保留） ====================
+
+/** 插件清单 */
+export interface PluginManifest {
+  id: string;
+  name: string;
+  version: string;
+  description: string;
+  author: string;
+  type: PluginType;
+  icon?: string;
+  minAppVersion?: string;
+  code: string;
+  configSchema?: PluginConfigField[];
+  uiSlots?: UISlotRegistration[];
+  /** 共享权限（可被多个插件同时声明，默认权限集：slot:input-toolbar, style:inject, modal:confirm） */
+  commonPermissions?: UIPermission[];
+  /** 排他权限（同时只能被一个插件声明，冲突时后加载的插件启动失败） */
+  exclusivePermissions?: UIPermission[];
+  /** 必要权限（没有此权限则插件不允许启动，必须在 commonPermissions 或 exclusivePermissions 中声明） */
+  requiredPermissions?: UIPermission[];
+  /** 插件公开导出的 API（供其他插件调用） */
+  publicExports?: Record<string, {
+    description: string;
+    params?: string;
+    returns?: string;
+  }>;
+  /** 插件依赖列表 */
+  dependencies?: PluginDependency[];
+  /** 入口代码文件路径（如 data/plugins/x.y/index.js），用于判断插件格式 */
+  codePath?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** 插件依赖定义 */
+export interface PluginDependency {
+  pluginId: string;
+  versionRange?: string;
+  optional?: boolean;
+}
+
+/** 依赖状态 */
+export interface DependencyStatus {
+  pluginId: string;
+  status: 'satisfied' | 'missing' | 'version_mismatch';
+  required: boolean;
+  installedVersion?: string;
+}
+
+/** 插件运行时实例 */
+export interface PluginInstance {
+  manifest: PluginManifest;
+  enabled: boolean;
+  config: Record<string, unknown>;
+  scope: 'global' | 'world';
+  worldId?: string;
+  exports?: Record<string, (...args: unknown[]) => unknown>;
+}
+
+/** 插件绑定（数据库存储） */
+export interface PluginBinding {
+  id?: number;
+  extensionId: string;
+  scope: 'global' | 'world';
+  worldId?: string;
+  enabled: boolean;
+  config: Record<string, unknown>;
+  sortOrder: number;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/** 游戏属性定义 */
+export interface GameAttribute {
+  pluginId?: string;
+  key: string;
+  label: string;
+  type: 'number' | 'string' | 'boolean';
+  value: number | string | boolean;
+  min?: number;
+  max?: number;
+  icon?: string;
+  color?: string;
+  group?: string;
+}
+
+/** 快捷指令 */
+export interface ChatCommand {
+  pluginId?: string;
+  name: string;
+  description: string;
+  icon?: string;
+  handler: (args: string) => string | void | Promise<string | void>;
+}
+
+/** 侧边栏面板注册（扩展 pluginId） */
+export interface SidebarPanelRegistration {
+  id: string;
+  pluginId?: string;
+  title: string;
+  icon?: string;
+  render: () => string;
+  priority?: number;
+}
+
+/** 工具栏按钮注册（扩展 pluginId） */
+export interface ToolbarButtonRegistration {
+  id: string;
+  pluginId?: string;
+  label: string;
+  icon?: string;
+  onClick: () => void;
+  order?: number;
+}
+
+/** 骰子结果 */
+export interface DiceResult {
+  notation: string;
+  rolls: number[];
+  modifier: number;
+  total: number;
+}
+
+/** AI 请求配置 */
+export interface AIRequestConfig {
+  temperature: number;
+  maxTokens: number;
+  model: string;
+}
+
+/** 消息渲染器（扩展 pluginId） */
+export type MessageRenderer = {
+  pluginId?: string;
+  matcher: (msg: { role: string; content: string }) => boolean;
+  renderer: (msg: { role: string; content: string }) => string;
+};
+
+/** 安全检测报告 */
+export interface SecurityScanResult {
+  riskLevel: 'low' | 'medium' | 'high' | 'critical';
+  score: number;
+  summary: string;
+  findings: SecurityFinding[];
+  recommendation: string;
+}
+
+/** 安全检测发现项 */
+export interface SecurityFinding {
+  level: 'info' | 'warning' | 'danger';
+  category: string;
+  description: string;
+  code?: string;
+  recommendation: string;
+}
+
+/** 插件导出/导入格式 */
+export interface PluginExportFormat {
+  format: 'xinyu-extension-v1';
+  exportedAt: string;
+  plugins: PluginManifest[];
+}
+
+/** .xye 插件包中的 manifest.json 结构 */
+export interface XyeManifest {
+  /** 插件入口 JS 文件路径（相对于包根目录） */
+  pluginEntry: string;
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+  type: PluginType;
+  icon?: string;
+  minAppVersion?: string;
+  configSchema?: PluginConfigField[];
+  uiSlots?: UISlotRegistration[];
+  commonPermissions?: UIPermission[];
+  exclusivePermissions?: UIPermission[];
+  requiredPermissions?: UIPermission[];
+  publicExports?: Record<string, { description: string; params?: string; returns?: string }>;
+  dependencies?: PluginDependency[];
+}
+
+/** Hook 处理函数类型 */
+export type HookHandler = (...args: unknown[]) => unknown;

package/lib/prompt-builder.ts

@@ -0,0 +1,55 @@
+// lib/prompt-builder.ts - 系统提示词构建器（客户端/服务端共享）
+
+/** 从动态字段构建 system prompt */
+export function buildSystemPrompt(worldData: Record<string, unknown>, extraPrompt?: string): string {
+  // 内部字段（不展示给 AI）
+  const internalKeys = new Set(['_plugins', '_labels', '_fieldMeta', '_fieldOrder']);
+
+  // 收集所有可展示字段
+  const entries = Object.entries(worldData).filter(([key, value]) =>
+    !internalKeys.has(key) && value !== null && value !== undefined && value !== ''
+  );
+
+  if (entries.length === 0) {
+    // 无世界设定，使用基础提示词
+    const base = `你是一位沉浸式角色扮演游戏的世界主持人。你的职责是推动剧情发展、扮演所有 NPC、描述场景氛围，以及回应玩家的每一次行动。
+
+## 你必须遵守的规则
+1. 始终使用第二人称"你"称呼玩家。
+2. 不能替玩家做决定或替玩家说话。
+3. 保持世界观的一致性和沉浸感。
+4. 扮演 NPC 时要符合该角色的性格和立场。
+5. 每次回复应包含：场景描写、NPC 反应、剧情推进，以及可探索的方向暗示（但不强制）。
+6. 回复应当生动、有画面感，让玩家有身临其境的感觉。
+7. 用中文回复。`;
+    if (extraPrompt && extraPrompt.trim()) {
+      return `${base}\n\n## 额外指令\n${extraPrompt.trim()}`;
+    }
+    return base;
+  }
+
+  // 构建 worldSection
+  let worldSection = '## 世界设定';
+  for (const [key, value] of entries) {
+    const displayValue = Array.isArray(value) ? value.join('、') : String(value);
+    worldSection += `\n- **${key}**: ${displayValue}`;
+  }
+
+  const base = `你是一位沉浸式角色扮演游戏的世界主持人。你的职责是推动剧情发展、扮演所有 NPC、描述场景氛围，以及回应玩家的每一次行动。
+
+${worldSection}
+
+## 你必须遵守的规则
+1. 始终使用第二人称"你"称呼玩家。
+2. 不能替玩家做决定或替玩家说话。
+3. 保持世界观的一致性和沉浸感。
+4. 扮演 NPC 时要符合该角色的性格和立场。
+5. 每次回复应包含：场景描写、NPC 反应、剧情推进，以及可探索的方向暗示（但不强制）。
+6. 回复应当生动、有画面感，让玩家有身临其境的感觉。
+7. 用中文回复。`;
+
+  if (extraPrompt && extraPrompt.trim()) {
+    return `${base}\n\n## 额外指令\n${extraPrompt.trim()}`;
+  }
+  return base;
+}