docs(wiki): service worker package page

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: gxkl

wiki/index.md

@@ -27,6 +27,7 @@ Read this file before exploring raw sources.
 - [Egg Bundler](./packages/egg-bundler.md) - Tooling package that bundles Egg applications and backs `egg-bin bundle`.
 - [Loader FS Package](./packages/loader-fs.md) - Shared loader-facing filesystem boundary for Egg loaders and future bundled runtimes.
 - [Onerror Plugin](./packages/onerror.md) - Default Egg error-handling plugin and configurable response negotiation layer.
+- [Standalone Service Worker](./packages/service-worker.md) - Fetch-semantics standalone runtime serving HTTP controllers and MCP tools from a tegg module without an egg application.
 - [Typings Package](./packages/typings.md) - Shared TypeScript type surface for cross-package Egg typings.
 - [Utils Package](./packages/utils.md) - Shared utility package for module loading and bundled module-loader integration.
 

wiki/log.md

@@ -132,3 +132,9 @@ Full **isolate:false suite validated GREEN** under CI-faithful parallelism (`--m
 - sources touched: `tegg/plugin/aop/src/lib/AopContextHook.ts`, `tegg/core/aop-runtime/src/AopContextAdviceRegistry.ts`, `tegg/core/aop-runtime/src/LoadUnitAopHook.ts`, `tegg/plugin/dal/src/index.ts`, `tegg/plugin/dal/src/lib/DalModuleLoadUnitHook.ts`
 - pages updated: `wiki/log.md`, `wiki/concepts/tegg-module-plugin.md`
 - note: Replaced stale DAL source paths and updated the AOP note after `AopContextHook` moved to lifecycle-proto/inner-object registration backed by `AopContextAdviceRegistry`.
+
+## [2026-07-05] package | standalone service worker (方案二 complete)
+
+- sources touched: `tegg/plugin/controller`, `tegg/standalone/{service-worker-runtime,service-worker}`, `examples/helloworld-service-worker`
+- pages updated: `wiki/index.md`, `wiki/log.md`, `wiki/packages/service-worker.md`
+- note: Completed the service-worker migration on top of the module plugin mechanism: made the controller plugin a dual-host module carrying its host-agnostic runtime under `lib/runtime/`, added the two service worker packages (fetch adapter + protocol-agnostic runtime), MCP stateless streamable HTTP via the SDK's web-standard transport (SDK >= 1.29 forbids stateless transport reuse — fresh server+transport per request), streaming-response lifecycle via BackgroundTaskHelper drain, unified `{ code, message }` errors, `mcpAuthHandler` auth extension point, and a runnable example. Gotcha recorded: frameworkDeps module scans must exclude `test/**` or framework test fixtures load as business modules.

wiki/packages/service-worker.md

@@ -0,0 +1,53 @@
+---
+title: Standalone service worker (@eggjs/service-worker[-runtime])
+type: package
+summary: Fetch-semantics standalone runtime — HTTP controllers and MCP tools served from a tegg module without an egg application
+source_files:
+  - tegg/standalone/service-worker-runtime/src
+  - tegg/standalone/service-worker/src
+  - examples/helloworld-service-worker
+updated_at: 2026-07-05
+status: active
+---
+
+Two packages provide the standalone service worker runtime on top of the
+module-plugin mechanism (declarative `@InnerObjectProto` /
+`@XxxLifecycleProto` hooks, see the module-plugin pages):
+
+- `@eggjs/service-worker-runtime` — protocol-agnostic: `@Runner()` entry
+  dispatching events to `@EventHandlerProto('<type>')` handlers, event
+  injection into ContextProtos, `BackgroundTaskHelper` re-export
+  (ctx-destroy draining).
+- `@eggjs/service-worker` — the fetch protocol: `FetchEventHandler`,
+  `FetchRouter` + fetch parameter binding (no `@Cookies`), MCP stateless
+  streamable HTTP under `/mcp[/name]/stream`, `ServiceWorkerApp` facade with
+  `serve()` (node:http bridge) and embedded `handleEvent()`.
+
+Key mechanics and constraints:
+
+- **Controller reuse**: metadata from `@eggjs/controller-decorator`,
+  registration runtime from `@eggjs/controller-plugin` (shared with
+  `@eggjs/controller-plugin`); only param binding and transports are
+  fetch-specific.
+- **MCP SDK >= 1.29 stateless transports are single-shot** (reuse throws), so
+  each MCP request builds a fresh `MCPServerHelper` + web-standard transport
+  from register records collected at boot. The service worker uses
+  `WebStandardStreamableHTTPServerTransport` (Request in, Response out) — no
+  node req/res bridging. Auth is an `mcpAuthHandler` extension point
+  (default: allow).
+- **Streaming lifecycle**: `FetchEventHandler` routes every response body
+  through a passthrough and registers the drain as a background task, so ctx
+  destroy waits (bounded by `config.backgroundTask.timeout`) until the client
+  consumes the stream.
+- **Unified errors**: framework failures reply `{ code, message }` JSON
+  (`NOT_FOUND` / `INTERNAL_SERVER_ERROR`); `ctx.responseHeaders` merge onto
+  the final response.
+- **frameworkDeps scan excludes `test/**`\*\*: the framework packages are
+  themselves modules; without the exclusion their test fixtures load as
+  business modules (duplicate controller names) in workspace layouts.
+- Per-app state is all inner objects in the app's TeggScope bag — two
+  concurrent `ServiceWorkerApp`s are isolated (`test/MultiApp.test.ts`).
+
+Example: `examples/helloworld-service-worker` (entry `main.ts` lives outside
+the scanned `app/` module dir on purpose — the scan imports every module
+file, and importing an entry that boots the app recurses).