From 4673494e730708a972047f765705d7c2c7f5b749 Mon Sep 17 00:00:00 2001
From: RainbowBird <git@luoling.moe>
Date: Fri, 27 Mar 2026 22:51:08 +0800
Subject: [PATCH] chore: cleanup

---
 apps/server/vitest.config.ts                  |  7 ---
 packages/plugin-sdk/package.json              |  1 +
 packages/server-sdk/package.json              |  1 -
 packages/server-sdk/src/events/chat.ts        |  1 -
 packages/server-sdk/src/index.ts              |  1 -
 packages/server-sdk/tsconfig.json             | 14 ------
 packages/server-shared/README.md              | 45 ++++++++++++++++++-
 packages/stage-pages/package.json             |  1 -
 .../components/context-flow-actions.vue       |  2 +-
 .../use-context-flow-formatters.ts            |  2 +-
 .../context-flow/context-flow-types.ts        |  2 +-
 .../src/pages/devtools/context-flow/index.vue |  4 +-
 packages/stage-ui/package.json                |  1 -
 packages/stage-ui/src/libs/auth.ts            |  1 +
 .../event-handler-spark-notify/index.ts       |  2 +-
 .../character/orchestrator/index.test.ts      |  2 +-
 .../stores/character/orchestrator/store.ts    |  2 +-
 packages/stage-ui/src/stores/chat.ts          |  2 +-
 .../stores/chat/context-providers/datetime.ts |  2 +-
 .../stage-ui/src/stores/chat/context-store.ts |  2 +-
 .../stores/devtools/websocket-inspector.ts    |  2 +-
 .../src/stores/mods/api/channel-server.ts     |  5 +--
 .../src/stores/modules/vision/orchestrator.ts |  2 +-
 packages/stage-ui/src/types/chat.ts           |  2 +-
 packages/stage-ui/src/utils/event-source.ts   |  2 +-
 pnpm-lock.yaml                                | 12 ++---
 26 files changed, 65 insertions(+), 55 deletions(-)
 delete mode 100644 packages/server-sdk/src/events/chat.ts

diff --git a/apps/server/vitest.config.ts b/apps/server/vitest.config.ts
index 58857b62d..9e551b734 100644
--- a/apps/server/vitest.config.ts
+++ b/apps/server/vitest.config.ts
@@ -1,13 +1,6 @@
-import { resolve } from 'node:path'
-
 import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
-  resolve: {
-    alias: {
-      '@proj-airi/server-sdk-shared': resolve(import.meta.dirname, '..', '..', 'packages', 'server-sdk-shared', 'src', 'index.ts'),
-    },
-  },
   test: {
     environment: 'node',
     globals: true,
diff --git a/packages/plugin-sdk/package.json b/packages/plugin-sdk/package.json
index cdda13872..494333b10 100644
--- a/packages/plugin-sdk/package.json
+++ b/packages/plugin-sdk/package.json
@@ -42,6 +42,7 @@
   "dependencies": {
     "@moeru/eventa": "catalog:",
     "@proj-airi/plugin-protocol": "workspace:*",
+    "@proj-airi/server-shared": "workspace:*",
     "nanoid": "catalog:",
     "valibot": "^1.3.1",
     "xstate": "^5.28.0"
diff --git a/packages/server-sdk/package.json b/packages/server-sdk/package.json
index 66ca6aed6..f16d656f1 100644
--- a/packages/server-sdk/package.json
+++ b/packages/server-sdk/package.json
@@ -38,7 +38,6 @@
   },
   "dependencies": {
     "@moeru/std": "catalog:",
-    "@proj-airi/server-sdk-shared": "workspace:^",
     "@proj-airi/server-shared": "workspace:^",
     "crossws": "^0.4.4",
     "superjson": "catalog:"
diff --git a/packages/server-sdk/src/events/chat.ts b/packages/server-sdk/src/events/chat.ts
deleted file mode 100644
index 268d1ead7..000000000
--- a/packages/server-sdk/src/events/chat.ts
+++ /dev/null
@@ -1 +0,0 @@
-export * from '@proj-airi/server-sdk-shared'
diff --git a/packages/server-sdk/src/index.ts b/packages/server-sdk/src/index.ts
index 8b471545a..78508edf6 100644
--- a/packages/server-sdk/src/index.ts
+++ b/packages/server-sdk/src/index.ts
@@ -1,4 +1,3 @@
 export * from './client'
-export * from './events/chat'
 export type * from '@proj-airi/server-shared/types'
 export { ContextUpdateStrategy, WebSocketEventSource } from '@proj-airi/server-shared/types'
diff --git a/packages/server-sdk/tsconfig.json b/packages/server-sdk/tsconfig.json
index 93f9f81ce..00dcfd807 100644
--- a/packages/server-sdk/tsconfig.json
+++ b/packages/server-sdk/tsconfig.json
@@ -4,20 +4,8 @@
     "lib": [
       "ESNext"
     ],
-    "baseUrl": ".",
     "module": "ESNext",
     "moduleResolution": "bundler",
-    "paths": {
-      "@proj-airi/server-shared": [
-        "../server-shared/src/index.ts"
-      ],
-      "@proj-airi/server-shared/*": [
-        "../server-shared/src/*"
-      ],
-      "@proj-airi/server-sdk-shared": [
-        "../server-sdk-shared/src/index.ts"
-      ]
-    },
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "isolatedModules": true,
@@ -25,8 +13,6 @@
     "skipLibCheck": true
   },
   "include": [
-    "../server-shared/src/**/*.ts",
-    "../server-sdk-shared/src/**/*.ts",
     "src/**/*.ts"
   ]
 }
diff --git a/packages/server-shared/README.md b/packages/server-shared/README.md
index bcefc30b6..b84ee5c5d 100644
--- a/packages/server-shared/README.md
+++ b/packages/server-shared/README.md
@@ -1,6 +1,6 @@
 # @proj-airi/server-shared
 
-Server-side shared utilities for AIRI runtimes.
+The shared type definitions for all server-side packages of Project AIRI.
 
 ## Usage
 
@@ -12,9 +12,50 @@ npm i @proj-airi/server-shared -D
 ```
 
 ```typescript
-import { parseServerErrorMessage } from '@proj-airi/server-shared'
+import type { WebSocketEvents } from '@proj-airi/server-shared'
 ```
 
+## How to use the events in distributed use cases?
+
+### Scenarios
+
+#### Minecraft agent
+
+##### 1. Urgent combat (witch attack)
+
+- Minecraft sends `spark:notify` (kind=alarm, urgency=immediate, payload hp/location/gear, destinations=["character"]).
+- Character `spark:emit` working ("Seen it").
+- Character issues `spark:command` with interrupt=force and options (retreat vs push).
+- Minecraft `spark:emit` working ("Pillared up; healing") then done/blocked as it executes.
+- Optional `context:update` for summary/memory.
+
+##### 2. Prep plan (Ender Dragon)
+
+- Discord/user intent triggers character `spark:command` to Minecraft (intent=plan, interrupt=soft, steps gather beds/pots/gear, fallback).
+- Optional `context:update` with tips (lane='game').
+- Minecraft streams `spark:emit` progress.
+- If ambushed, Minecraft raises new `spark:notify` (alarm/immediate) to preempt.
+- Character revises with another `spark:command`.
+- Completion via `spark:emit` done + summary note.
+
+##### 3. Routine nudge
+
+- Minecraft signals low food via `spark:notify` (kind=reminder, urgency=soon, destinations=["character"]).
+- Character defers to next tick and sends `spark:command` (interrupt=soft, intent=plan: "gather food nearby").
+- Minecraft `spark:emit` queued/working then done.
+
+##### 4. Multi-step command while researching (plan + live control)
+
+> [!NOTE]
+> Using `intent=plan` keeps the loop alive even with un-finalized ideas—similar to TODO scaffolding in coding agents—while richer guidance is still being researched.
+
+- Character receives a user goal (e.g., fortify base) and issues an initial `spark:command` to Minecraft (interrupt=soft, intent=plan, steps to gather materials) so the agent keeps working.
+- Character simultaneously performs memory/search/design tasks outside the game loop (wiki lookup, prior notes).
+- As insights arrive, character sends `context:update` (lane='game', hints/ideas) to enrich the sub-agent without preemption.
+- If an urgent event occurs during prep, Minecraft raises `spark:notify` (alarm) → character responds with a short `spark:emit` working and a `spark:command` (interrupt=force) to handle it (e.g., retreat, block up).
+- Once design is ready, character sends a refined `spark:command` (`intent=proposal` (or `action`), `interrupt=soft`) with structured options/steps/fallbacks.
+- Minecraft streams `spark:emit` progress; when complete, character summarizes via `spark:emit` or `context:update` for memory.
+
 ## License
 
 [MIT](../../LICENSE)
diff --git a/packages/stage-pages/package.json b/packages/stage-pages/package.json
index 68c121482..efd865941 100644
--- a/packages/stage-pages/package.json
+++ b/packages/stage-pages/package.json
@@ -27,7 +27,6 @@
     "@proj-airi/ccc": "workspace:*",
     "@proj-airi/i18n": "workspace:*",
     "@proj-airi/server-sdk": "workspace:*",
-    "@proj-airi/server-shared": "workspace:*",
     "@proj-airi/stage-ui": "workspace:*",
     "@proj-airi/stage-ui-live2d": "workspace:*",
     "@proj-airi/stage-ui-three": "workspace:*",
diff --git a/packages/stage-pages/src/pages/devtools/context-flow/components/context-flow-actions.vue b/packages/stage-pages/src/pages/devtools/context-flow/components/context-flow-actions.vue
index 587e3b063..8ac547684 100644
--- a/packages/stage-pages/src/pages/devtools/context-flow/components/context-flow-actions.vue
+++ b/packages/stage-pages/src/pages/devtools/context-flow/components/context-flow-actions.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { ContextUpdateStrategy } from '@proj-airi/server-shared/types'
+import { ContextUpdateStrategy } from '@proj-airi/server-sdk'
 import { Section } from '@proj-airi/stage-ui/components'
 import { Button, FieldInput, FieldTextArea, SelectTab } from '@proj-airi/ui'
 
diff --git a/packages/stage-pages/src/pages/devtools/context-flow/composables/use-context-flow-formatters.ts b/packages/stage-pages/src/pages/devtools/context-flow/composables/use-context-flow-formatters.ts
index c2737078b..7d97e7574 100644
--- a/packages/stage-pages/src/pages/devtools/context-flow/composables/use-context-flow-formatters.ts
+++ b/packages/stage-pages/src/pages/devtools/context-flow/composables/use-context-flow-formatters.ts
@@ -1,4 +1,4 @@
-import type { WebSocketEvents } from '@proj-airi/server-shared/types'
+import type { WebSocketEvents } from '@proj-airi/server-sdk'
 
 import type { FlowEntry, PreviewItem } from '../context-flow-types'
 
diff --git a/packages/stage-pages/src/pages/devtools/context-flow/context-flow-types.ts b/packages/stage-pages/src/pages/devtools/context-flow/context-flow-types.ts
index 001885297..63f3358c9 100644
--- a/packages/stage-pages/src/pages/devtools/context-flow/context-flow-types.ts
+++ b/packages/stage-pages/src/pages/devtools/context-flow/context-flow-types.ts
@@ -1,4 +1,4 @@
-import type { WebSocketEvents } from '@proj-airi/server-shared/types'
+import type { WebSocketEvents } from '@proj-airi/server-sdk'
 
 type Optional<T> = T | undefined
 
diff --git a/packages/stage-pages/src/pages/devtools/context-flow/index.vue b/packages/stage-pages/src/pages/devtools/context-flow/index.vue
index f9f701bfb..7e7ef3928 100644
--- a/packages/stage-pages/src/pages/devtools/context-flow/index.vue
+++ b/packages/stage-pages/src/pages/devtools/context-flow/index.vue
@@ -1,11 +1,11 @@
 <script setup lang="ts">
-import type { WebSocketBaseEvent, WebSocketEventOf, WebSocketEvents } from '@proj-airi/server-shared/types'
+import type { WebSocketBaseEvent, WebSocketEventOf, WebSocketEvents } from '@proj-airi/server-sdk'
 import type { ChatStreamEvent, ContextMessage } from '@proj-airi/stage-ui/types/chat'
 
 import type { FlowDirection, FlowEntry, SparkNotifyEntryState } from './context-flow-types'
 
 import { errorMessageFrom } from '@moeru/std'
-import { ContextUpdateStrategy } from '@proj-airi/server-shared/types'
+import { ContextUpdateStrategy } from '@proj-airi/server-sdk'
 import { useCharacterOrchestratorStore, useCharacterStore } from '@proj-airi/stage-ui/stores/character'
 import { useChatOrchestratorStore } from '@proj-airi/stage-ui/stores/chat'
 import { CHAT_STREAM_CHANNEL_NAME, CONTEXT_CHANNEL_NAME } from '@proj-airi/stage-ui/stores/chat/constants'
diff --git a/packages/stage-ui/package.json b/packages/stage-ui/package.json
index 6b3f49767..ecc068887 100644
--- a/packages/stage-ui/package.json
+++ b/packages/stage-ui/package.json
@@ -70,7 +70,6 @@
     "@proj-airi/model-driver-lipsync": "workspace:^",
     "@proj-airi/pipelines-audio": "workspace:^",
     "@proj-airi/server-sdk": "workspace:^",
-    "@proj-airi/server-shared": "workspace:^",
     "@proj-airi/stage-shared": "workspace:^",
     "@proj-airi/stage-ui-live2d": "workspace:^",
     "@proj-airi/stage-ui-three": "workspace:^",
diff --git a/packages/stage-ui/src/libs/auth.ts b/packages/stage-ui/src/libs/auth.ts
index b3f999e1c..6f700d80a 100644
--- a/packages/stage-ui/src/libs/auth.ts
+++ b/packages/stage-ui/src/libs/auth.ts
@@ -23,6 +23,7 @@ export function initializeAuth() {
 export async function fetchSession() {
   const { data } = await authClient.getSession()
   const authStore = useAuthStore()
+
   if (data) {
     authStore.user = data.user
     authStore.session = data.session
diff --git a/packages/stage-ui/src/stores/character/orchestrator/agents/event-handler-spark-notify/index.ts b/packages/stage-ui/src/stores/character/orchestrator/agents/event-handler-spark-notify/index.ts
index 9c49e5dad..44e1515d7 100644
--- a/packages/stage-ui/src/stores/character/orchestrator/agents/event-handler-spark-notify/index.ts
+++ b/packages/stage-ui/src/stores/character/orchestrator/agents/event-handler-spark-notify/index.ts
@@ -1,4 +1,4 @@
-import type { WebSocketEventOf, WebSocketEvents } from '@proj-airi/server-shared/types'
+import type { WebSocketEventOf, WebSocketEvents } from '@proj-airi/server-sdk'
 import type { ChatProvider, ChatProviderWithExtraOptions, EmbedProvider, EmbedProviderWithExtraOptions, SpeechProvider, SpeechProviderWithExtraOptions, TranscriptionProvider, TranscriptionProviderWithExtraOptions } from '@xsai-ext/providers/utils'
 import type { Message } from '@xsai/shared-chat'
 
diff --git a/packages/stage-ui/src/stores/character/orchestrator/index.test.ts b/packages/stage-ui/src/stores/character/orchestrator/index.test.ts
index 8b9ac18c6..d1503eaf5 100644
--- a/packages/stage-ui/src/stores/character/orchestrator/index.test.ts
+++ b/packages/stage-ui/src/stores/character/orchestrator/index.test.ts
@@ -1,7 +1,7 @@
 /* eslint-disable style/indent-binary-ops */
 /* eslint-disable style/operator-linebreak */
 
-import type { WebSocketEventOf } from '@proj-airi/server-shared/types'
+import type { WebSocketEventOf } from '@proj-airi/server-sdk'
 import type { Store, StoreDefinition } from 'pinia'
 import type { Mock } from 'vitest'
 import type { UnwrapRef } from 'vue'
diff --git a/packages/stage-ui/src/stores/character/orchestrator/store.ts b/packages/stage-ui/src/stores/character/orchestrator/store.ts
index c1872ad66..56ebd496f 100644
--- a/packages/stage-ui/src/stores/character/orchestrator/store.ts
+++ b/packages/stage-ui/src/stores/character/orchestrator/store.ts
@@ -1,4 +1,4 @@
-import type { WebSocketBaseEvent, WebSocketEventOf, WebSocketEvents } from '@proj-airi/server-shared/types'
+import type { WebSocketBaseEvent, WebSocketEventOf, WebSocketEvents } from '@proj-airi/server-sdk'
 
 import { defineStore, storeToRefs } from 'pinia'
 import { ref } from 'vue'
diff --git a/packages/stage-ui/src/stores/chat.ts b/packages/stage-ui/src/stores/chat.ts
index 5d6939a10..c7674bf39 100644
--- a/packages/stage-ui/src/stores/chat.ts
+++ b/packages/stage-ui/src/stores/chat.ts
@@ -1,4 +1,4 @@
-import type { WebSocketEventInputs } from '@proj-airi/server-shared/types'
+import type { WebSocketEventInputs } from '@proj-airi/server-sdk'
 import type { ChatProvider } from '@xsai-ext/providers/utils'
 import type { CommonContentPart, Message, ToolMessage } from '@xsai/shared-chat'
 
diff --git a/packages/stage-ui/src/stores/chat/context-providers/datetime.ts b/packages/stage-ui/src/stores/chat/context-providers/datetime.ts
index 7bbf284a6..ecc6fe116 100644
--- a/packages/stage-ui/src/stores/chat/context-providers/datetime.ts
+++ b/packages/stage-ui/src/stores/chat/context-providers/datetime.ts
@@ -1,6 +1,6 @@
 import type { ContextMessage } from '../../../types/chat'
 
-import { ContextUpdateStrategy } from '@proj-airi/server-shared/types'
+import { ContextUpdateStrategy } from '@proj-airi/server-sdk'
 import { nanoid } from 'nanoid'
 
 const DATETIME_CONTEXT_ID = 'system:datetime'
diff --git a/packages/stage-ui/src/stores/chat/context-store.ts b/packages/stage-ui/src/stores/chat/context-store.ts
index 89b648fb4..1fd8b6fee 100644
--- a/packages/stage-ui/src/stores/chat/context-store.ts
+++ b/packages/stage-ui/src/stores/chat/context-store.ts
@@ -1,6 +1,6 @@
 import type { ContextMessage } from '../../types/chat'
 
-import { ContextUpdateStrategy } from '@proj-airi/server-shared/types'
+import { ContextUpdateStrategy } from '@proj-airi/server-sdk'
 import { defineStore } from 'pinia'
 import { ref, toRaw } from 'vue'
 
diff --git a/packages/stage-ui/src/stores/devtools/websocket-inspector.ts b/packages/stage-ui/src/stores/devtools/websocket-inspector.ts
index c0ed974e6..fb96d1f3f 100644
--- a/packages/stage-ui/src/stores/devtools/websocket-inspector.ts
+++ b/packages/stage-ui/src/stores/devtools/websocket-inspector.ts
@@ -1,4 +1,4 @@
-import type { WebSocketEvent } from '@proj-airi/server-shared/types'
+import type { WebSocketEvent } from '@proj-airi/server-sdk'
 
 import { nanoid } from 'nanoid'
 import { defineStore } from 'pinia'
diff --git a/packages/stage-ui/src/stores/mods/api/channel-server.ts b/packages/stage-ui/src/stores/mods/api/channel-server.ts
index c029b67a0..507701e35 100644
--- a/packages/stage-ui/src/stores/mods/api/channel-server.ts
+++ b/packages/stage-ui/src/stores/mods/api/channel-server.ts
@@ -1,8 +1,7 @@
-import type { ContextUpdate, InputContextUpdate, WebSocketBaseEvent, WebSocketEvent, WebSocketEventOptionalSource, WebSocketEvents } from '@proj-airi/server-shared/types'
+import type { ContextUpdate, InputContextUpdate, WebSocketBaseEvent, WebSocketEvent, WebSocketEventOptionalSource, WebSocketEvents } from '@proj-airi/server-sdk'
 import type { CommonContentPart } from '@xsai/shared-chat'
 
-import { Client } from '@proj-airi/server-sdk'
-import { WebSocketEventSource } from '@proj-airi/server-shared/types'
+import { Client, WebSocketEventSource } from '@proj-airi/server-sdk'
 import { isStageTamagotchi, isStageWeb } from '@proj-airi/stage-shared'
 import { useLocalStorage } from '@vueuse/core'
 import { nanoid } from 'nanoid'
diff --git a/packages/stage-ui/src/stores/modules/vision/orchestrator.ts b/packages/stage-ui/src/stores/modules/vision/orchestrator.ts
index 0814b7924..174b4ffe0 100644
--- a/packages/stage-ui/src/stores/modules/vision/orchestrator.ts
+++ b/packages/stage-ui/src/stores/modules/vision/orchestrator.ts
@@ -2,7 +2,7 @@ import type { CommonContentPart } from '@xsai/shared-chat'
 
 import type { VisionWorkloadId } from '../../../composables/vision/use-vision-workloads'
 
-import { ContextUpdateStrategy } from '@proj-airi/server-shared/types'
+import { ContextUpdateStrategy } from '@proj-airi/server-sdk'
 import { defineStore, storeToRefs } from 'pinia'
 import { ref } from 'vue'
 
diff --git a/packages/stage-ui/src/types/chat.ts b/packages/stage-ui/src/types/chat.ts
index cdcd4e0c6..6d44958c5 100644
--- a/packages/stage-ui/src/types/chat.ts
+++ b/packages/stage-ui/src/types/chat.ts
@@ -1,4 +1,4 @@
-import type { ContextUpdate, MetadataEventSource, WebSocketEventInputs } from '@proj-airi/server-shared/types'
+import type { ContextUpdate, MetadataEventSource, WebSocketEventInputs } from '@proj-airi/server-sdk'
 import type { AssistantMessage, CommonContentPart, CompletionToolCall, Message, SystemMessage, ToolMessage, UserMessage } from '@xsai/shared-chat'
 
 export interface ChatSlicesText {
diff --git a/packages/stage-ui/src/utils/event-source.ts b/packages/stage-ui/src/utils/event-source.ts
index b805f4978..f3ea7cf16 100644
--- a/packages/stage-ui/src/utils/event-source.ts
+++ b/packages/stage-ui/src/utils/event-source.ts
@@ -1,4 +1,4 @@
-import type { MetadataEventSource } from '@proj-airi/server-shared/types'
+import type { MetadataEventSource } from '@proj-airi/server-sdk'
 
 interface EventSourcePayload {
   source?: string
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index fd62e2c0e..7f3d3c954 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -2233,6 +2233,9 @@ importers:
       '@proj-airi/plugin-protocol':
         specifier: workspace:*
         version: link:../plugin-protocol
+      '@proj-airi/server-shared':
+        specifier: workspace:*
+        version: link:../server-shared
       nanoid:
         specifier: 'catalog:'
         version: 5.1.6
@@ -2281,9 +2284,6 @@ importers:
       '@moeru/std':
         specifier: 'catalog:'
         version: 0.1.0-beta.17
-      '@proj-airi/server-sdk-shared':
-        specifier: workspace:^
-        version: link:../server-sdk-shared
       '@proj-airi/server-shared':
         specifier: workspace:^
         version: link:../server-shared
@@ -2426,9 +2426,6 @@ importers:
       '@proj-airi/server-sdk':
         specifier: workspace:*
         version: link:../server-sdk
-      '@proj-airi/server-shared':
-        specifier: workspace:*
-        version: link:../server-shared
       '@proj-airi/stage-ui':
         specifier: workspace:*
         version: link:../stage-ui
@@ -2608,9 +2605,6 @@ importers:
       '@proj-airi/server-sdk':
         specifier: workspace:^
         version: link:../server-sdk
-      '@proj-airi/server-shared':
-        specifier: workspace:^
-        version: link:../server-shared
       '@proj-airi/stage-shared':
         specifier: workspace:^
         version: link:../stage-shared