@zhin.js/host-http 1.1.17 → 1.2.1

package/src/console-events.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import type { ServerResponse } from 'node:http';
+import type { HttpResponseStream } from '@zhin.js/host-http-contract';
 import type {
   ConsoleEventEnvelope,
   ConsoleEventHistoryPage,
@@ -11,9 +11,13 @@ import { createToken } from '@zhin.js/plugin-runtime';
 
 /**
  * Console 实时事件枢纽（Plugin Runtime Host 的 `/api/events` SSE 事件源）。
- * 单进程内 fan-out：`publish` 向所有已订阅的 SSE response 写帧；
+ * 单进程内 fan-out：`publish` 向所有已订阅的 SSE 响应流写帧；
  * write 失败或连接断开自动摘除订阅。
  */
+
+/** The SSE response body a subscriber reads from (`createResponseStream()`). */
+export type ConsoleEventSink = Pick<HttpResponseStream, 'write' | 'onDrain' | 'onClose' | 'error'>;
+
 export interface ConsoleEventSubscriptionOptions {
   readonly runtimeId?: string;
   readonly after?: number;
@@ -31,7 +35,7 @@ export interface ConsoleEventHub {
   /** In-process delivery for trusted Host bridges such as Device Protocol. */
   listen(listener: (event: ConsoleEventEnvelope) => void): () => void;
   /** Atomically replay the resumable suffix, then join live fan-out. */
-  subscribe(response: ServerResponse, options?: ConsoleEventSubscriptionOptions): () => void;
+  subscribe(sink: ConsoleEventSink, options?: ConsoleEventSubscriptionOptions): () => void;
   readonly runtimeId: string;
   readonly subscriberCount: number;
 }
@@ -70,29 +74,61 @@ export function createConsoleEventHub(options: ConsoleEventHubOptions = {}): Con
   );
   const journal: JournalEntry[] = [];
   let journalBytes = 0;
-  const subscribers = new Set<ServerResponse>();
+  /**
+   * `null` while a subscriber is live. During replay catch-up it holds the frames
+   * (replay suffix, then live events) still waiting for the socket to drain.
+   */
+  const subscribers = new Map<ConsoleEventSink, JournalEntry[] | null>();
   const listeners = new Set<(event: ConsoleEventEnvelope) => void>();
 
-  const remove = (response: ServerResponse): void => {
+  const remove = (response: ConsoleEventSink): void => {
     subscribers.delete(response);
   };
 
-  const write = (response: ServerResponse, entry: JournalEntry): void => {
-    let failed = false;
-    const accepted = response.write(entry.frame, (error) => {
-      if (error) {
-        failed = true;
-        remove(response);
+  const drop = (response: ConsoleEventSink): void => {
+    remove(response);
+    response.error(new Error('Console event subscriber backpressure limit reached'));
+  };
+
+  /** Returns false when the consumer asks the producer to wait for drain. */
+  const write = (response: ConsoleEventSink, entry: JournalEntry): boolean =>
+    response.write(entry.frame);
+
+  /** Write queued frames until the socket pushes back again or the queue is empty. */
+  const flush = (response: ConsoleEventSink): void => {
+    const pending = subscribers.get(response);
+    if (!pending) return;
+    try {
+      while (pending.length > 0) {
+        if (!write(response, pending.shift()!)) {
+          const stop = response.onDrain(() => {
+            stop();
+            flush(response);
+          });
+          return;
+        }
       }
-    });
-    if (failed) throw new Error('Console event subscriber rejected replay');
-    if (!accepted) {
+      subscribers.set(response, null);
+    } catch {
       remove(response);
-      response.destroy(new Error('Console event subscriber backpressure limit reached'));
-      throw new Error('Console event subscriber backpressure limit reached');
     }
   };
 
+  const deliver = (response: ConsoleEventSink, entry: JournalEntry): void => {
+    const pending = subscribers.get(response);
+    if (pending === undefined) return;
+    if (pending === null) {
+      // A live subscriber that cannot keep up is disconnected; it resumes from history.
+      if (!write(response, entry)) drop(response);
+      return;
+    }
+    pending.push(entry);
+    // Catch-up may not outgrow what the journal itself is allowed to retain.
+    let bytes = 0;
+    for (const queued of pending) bytes += queued.bytes;
+    if (pending.length > historyLimit || bytes > historyByteLimit) drop(response);
+  };
+
   return {
     runtimeId,
     get subscriberCount() {
@@ -120,9 +156,9 @@ export function createConsoleEventHub(options: ConsoleEventHubOptions = {}): Con
       while (journal.length > historyLimit || journalBytes > historyByteLimit) {
         journalBytes -= journal.shift()?.bytes ?? 0;
       }
-      for (const response of [...subscribers]) {
+      for (const response of [...subscribers.keys()]) {
         try {
-          write(response, entry);
+          deliver(response, entry);
         } catch {
           remove(response);
         }
@@ -180,16 +216,11 @@ export function createConsoleEventHub(options: ConsoleEventHubOptions = {}): Con
         || requestedAfter > nextId
         ? 0
         : requestedAfter;
-      try {
-        for (const entry of journal) {
-          if (entry.event.eventId > after) write(response, entry);
-        }
-        subscribers.add(response);
-      } catch {
-        remove(response);
-      }
-      response.once('close', () => remove(response));
-      response.once('error', () => remove(response));
+      // Backpressure during replay is expected for a large suffix: the remaining frames
+      // (and any event published meanwhile) wait in order for the socket to drain.
+      subscribers.set(response, journal.filter((entry) => entry.event.eventId > after));
+      response.onClose(() => remove(response));
+      flush(response);
       return () => remove(response);
     },
   };

package/src/console-plugin-rpc.ts

@@ -5,7 +5,19 @@ import type {
   RuntimeConsoleRpcReply,
 } from './console-rpc.js';
 
-/** Dispatches the plugin-management slice; undefined means the type belongs elsewhere. */
+/**
+ * Refusal of the global plugin switch (`plugin:set-enabled`, `feature.set-enabled` at `global`)
+ * by an instance: the switch is a gateway transaction (stop → write `disable_plugins` → start,
+ * rollback on failure) and is never written by the instance itself (ADR 0054 §4).
+ */
+export const PLUGIN_SWITCH_REQUIRES_GATEWAY = '插件全局启停由管理网关执行（停止实例 → 写入 disable_plugins → 启动，失败回滚）：请在 zhin start 启动的 Console 中操作，或运行 zhin enable / zhin disable <插件>';
+
+/**
+ * Dispatches the plugin-management slice; undefined means the type belongs elsewhere. Package
+ * installs / updates / uninstalls are not handled in the instance: they are gateway dependency
+ * transactions (`gateway.packages.*`, ADR 0054 §4) that stop the instance first, and so is the
+ * global plugin switch (`plugin:set-enabled`, refused here).
+ */
 export async function dispatchPluginConsoleRpc(
   type: string,
   message: RuntimeConsoleRpcMessage,
@@ -14,32 +26,10 @@ export async function dispatchPluginConsoleRpc(
   const requestId = message.requestId as number | string | undefined;
   try {
     switch (type) {
-      case PLUGIN_RPC.SET_ENABLED: {
-        const instanceKey = stringField(message, 'instanceKey');
-        const enabled = message.enabled;
-        if (!instanceKey || typeof enabled !== 'boolean') {
-          return { requestId, error: 'instanceKey and boolean enabled are required' };
-        }
-        if (!ctx.setPluginEnabled) {
-          return { requestId, error: 'Plugin lifecycle management is not configured' };
-        }
-        const lifecycle = await ctx.setPluginEnabled(instanceKey, enabled);
-        ctx.publishEvent?.('plugin:lifecycle-updated', { instanceKey, enabled });
-        if (ctx.requestRestart) {
-          setTimeout(() => void Promise.resolve(ctx.requestRestart?.()).catch(() => undefined), 500);
-        }
-        return {
-          requestId,
-          data: {
-            success: true,
-            instanceKey,
-            enabled,
-            disabled: lifecycle.disabled,
-            restartRequired: true,
-            message: `${instanceKey} 已${enabled ? '启用' : '停用'}，Host 正在重启`,
-          },
-        };
-      }
+      case PLUGIN_RPC.SET_ENABLED:
+        // Global plugin on / off is a management gateway transaction (ADR 0054 §4): the gateway
+        // answers it before forwarding. Reaching the instance means no gateway is in front.
+        return { requestId, error: PLUGIN_SWITCH_REQUIRES_GATEWAY };
       case PLUGIN_RPC.INSPECT:
       case PLUGIN_RPC.APPLY:
       case PLUGIN_RPC.PLAN_VERIFICATION:
@@ -71,20 +61,6 @@ export async function dispatchPluginConsoleRpc(
         if (!ctx.pluginManagement) return { requestId, error: 'Plugin management is not configured' };
         return { requestId, data: await ctx.pluginManagement.planInstall(packageName) };
       }
-      case PLUGIN_RPC.INSTALL: {
-        const packageName = stringField(message, 'packageName');
-        if (!packageName) return { requestId, error: 'packageName is required' };
-        if (!ctx.pluginManagement?.install) {
-          return { requestId, error: 'Plugin installation is not configured' };
-        }
-        const result = await ctx.pluginManagement.install(
-          packageName,
-          optionalString(message.expectedRevision),
-          optionalString(message.expectedProjectRevision),
-        );
-        ctx.publishEvent?.('plugin:installed', { packageName, restartRequired: result.restartRequired });
-        return { requestId, data: { success: true, ...result } };
-      }
       case PLUGIN_RPC.PLAN_UNINSTALL: {
         const packageName = stringField(message, 'packageName');
         if (!packageName) return { requestId, error: 'packageName is required' };
@@ -93,22 +69,6 @@ export async function dispatchPluginConsoleRpc(
         }
         return { requestId, data: await ctx.pluginManagement.planUninstall(packageName) };
       }
-      case PLUGIN_RPC.UNINSTALL: {
-        const packageName = stringField(message, 'packageName');
-        if (!packageName || stringField(message, 'confirmation') !== packageName) {
-          return { requestId, error: 'confirmation must exactly match packageName' };
-        }
-        if (!ctx.pluginManagement?.uninstall) {
-          return { requestId, error: 'Plugin uninstall is not configured' };
-        }
-        const result = await ctx.pluginManagement.uninstall(
-          packageName,
-          optionalString(message.expectedRevision),
-          optionalString(message.expectedProjectRevision),
-        );
-        ctx.publishEvent?.('plugin:uninstalled', { packageName, restartRequired: result.restartRequired });
-        return { requestId, data: { success: true, ...result } };
-      }
       case PLUGIN_RPC.PLAN_UPDATE: {
         const packageName = stringField(message, 'packageName');
         const targetVersion = stringField(message, 'targetVersion');
@@ -120,26 +80,6 @@ export async function dispatchPluginConsoleRpc(
         }
         return { requestId, data: await ctx.pluginManagement.planUpdate(packageName, targetVersion) };
       }
-      case PLUGIN_RPC.UPDATE: {
-        const packageName = stringField(message, 'packageName');
-        const targetVersion = stringField(message, 'targetVersion');
-        if (!packageName || !targetVersion) {
-          return { requestId, error: 'packageName and targetVersion are required' };
-        }
-        if (!ctx.pluginManagement?.update) return { requestId, error: 'Plugin update is not configured' };
-        const result = await ctx.pluginManagement.update(
-          packageName,
-          targetVersion,
-          optionalString(message.expectedRevision),
-          optionalString(message.expectedProjectRevision),
-        );
-        ctx.publishEvent?.('plugin:updated', {
-          packageName,
-          version: result.installedVersion,
-          restartRequired: result.restartRequired,
-        });
-        return { requestId, data: { success: true, ...result } };
-      }
       case PLUGIN_RPC.VALIDATE_CONFIG: {
         const pluginName = stringField(message, 'pluginName');
         if (!pluginName) return { requestId, error: 'pluginName is required' };

package/src/console-rest-pages-helpers.ts

@@ -1,7 +1,14 @@
-import type { ServerResponse } from 'node:http';
 import type { HttpHost } from './http-host.js';
 import { HttpBodyError, readJsonBody } from './json-body.js';
-import type { AuthScope } from './token-registry.js';
+import { jsonResponse } from '@zhin.js/host-http-contract';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('console');
+
+/** Logs an unexpected failure server-side; clients only get a generic message. */
+export function logInternalError(op: string, error: unknown): void {
+  logger.warn(formatCompact({ op, error: error instanceof Error ? error.message : String(error) }));
+}
 import type {
   ConsoleAgentIntrospection,
   ConsoleAgentSessionTree,
@@ -125,7 +132,7 @@ export function registerIntrospectionRoutes(
   ];
 
   for (const { kind, collect, fields } of collectors) {
-    route('GET', `${base}/introspection/${kind}`, async (_request, response, url) => {
+    route('GET', `${base}/introspection/${kind}`, async (_request, { url }) => {
       const lease = kind === 'endpoints' ? null : ctx.acquireAgentRuntime?.() ?? null;
       try {
         const introspection = lease?.value.introspection;
@@ -146,15 +153,16 @@ export function registerIntrospectionRoutes(
             ? 'Endpoints 数据源未接线（ctx.getEndpoints 缺失）'
             : 'Agent runtime 未装配（basic/cli 未接线 acquireAgentRuntime）'
           : undefined);
-        writeJson(response, 200, {
+        return jsonResponse(200, {
           success: true,
           data: { ...slice, filter, note: degradedNote },
         });
       } catch (err) {
-        writeJson(response, 503, {
+        logInternalError(`introspection_${kind}_failed`, err);
+        return jsonResponse(503, {
           success: false,
           data: { items: [], page: 1, pageSize: 0, total: 0, totalPages: 0 },
-          error: err instanceof Error ? err.message : String(err),
+          error: 'Introspection unavailable',
         });
       } finally {
         lease?.release();
@@ -163,27 +171,25 @@ export function registerIntrospectionRoutes(
   }
 
   let activeComponentPreviews = 0;
-  route('POST', `${base}/introspection/components/render`, async (request, response, _url, authScope) => {
-    if (!requireWriteScope(response, ctx, authScope)) return;
+  route('POST', `${base}/introspection/components/render`, async (request) => {
+    const denied = requireWriteScope(ctx);
+    if (denied) return denied;
     const body = (await readJsonBody<Record<string, unknown>>(request)) ?? {};
     const requester = typeof body.requester === 'string' ? body.requester.trim() : '';
     const name = typeof body.name === 'string' ? body.name.trim() : '';
     if (!requester || !name || requester.length > 256 || name.length > 160) {
-      writeJson(response, 400, { success: false, error: '请提供有效的 requester 与 component name' });
-      return;
+      return jsonResponse(400, { success: false, error: '请提供有效的 requester 与 component name' });
     }
     const maxConcurrent = clampPositiveInt(options.componentPreviewMaxConcurrent, 2, 8);
     if (activeComponentPreviews >= maxConcurrent) {
-      writeJson(response, 503, { success: false, error: 'Component preview 正忙，请稍后重试' });
-      return;
+      return jsonResponse(503, { success: false, error: 'Component preview 正忙，请稍后重试' });
     }
     const lease = ctx.acquireAgentRuntime?.();
     const render = lease?.value.introspection?.renderComponent;
     const previewDelivery = lease?.value.introspection?.previewComponentDelivery;
     if (!lease || !render) {
       lease?.release();
-      writeJson(response, 503, { success: false, error: 'Component Runtime 未就绪' });
-      return;
+      return jsonResponse(503, { success: false, error: 'Component Runtime 未就绪' });
     }
     const controller = new AbortController();
     const timeoutMs = clampPositiveInt(options.componentPreviewTimeoutMs, 5_000, 30_000);
@@ -214,14 +220,17 @@ export function registerIntrospectionRoutes(
         controller.signal,
       );
       assertPreviewOutput(preview, options.componentPreviewMaxBytes ?? 256 * 1024);
-      writeJson(response, 200, { success: true, data: { requester, name, ...preview } });
+      return jsonResponse(200, { success: true, data: { requester, name, ...preview } });
     } catch (error) {
       const status = error instanceof ComponentPreviewTimeoutError
         ? 408
         : error instanceof ComponentPreviewLimitError ? 413 : 422;
-      writeJson(response, status, {
+      // Timeout / size limit messages are ours; a component's own failure detail stays in the log.
+      const known = error instanceof ComponentPreviewTimeoutError || error instanceof ComponentPreviewLimitError;
+      if (!known) logInternalError('component_preview_failed', error);
+      return jsonResponse(status, {
         success: false,
-        error: error instanceof Error ? error.message : String(error),
+        error: known ? (error as Error).message : 'Component preview failed',
       });
     } finally {
       clearTimeout(timeout);
@@ -311,77 +320,68 @@ export function registerAgentSessionRoutes(
     }
     return { tree, release: () => lease.release() };
   };
-  const unavailable = (response: ServerResponse) => {
-    writeJson(response, 503, {
+  const unavailable = (headers?: HeadersInit) => {
+    return jsonResponse(503, {
       success: false,
       error: 'Agent session tree runtime 未就绪（新 Runtime 需经 acquireAgentRuntime 装配 sessionTree）',
-    });
+    }, headers);
   };
 
   // HttpHost 无 `:param` 路由，用前缀路由匹配 `<sessionKey>/tree|message|leaf`。
-  route('GET', `${base}/agent/sessions/*`, async (_request, response, url) => {
+  route('GET', `${base}/agent/sessions/*`, async (_request, { url }) => {
     const messageAction = parseSessionAction(url.pathname, prefix, 'message');
-    if (messageAction) response.setHeader('Cache-Control', 'no-store');
+    const headers: HeadersInit | undefined = messageAction ? { 'cache-control': 'no-store' } : undefined;
+    const reply = (status: number, body: unknown) => jsonResponse(status, body, headers);
     const parsed = messageAction ?? parseSessionAction(url.pathname, prefix, 'tree');
     if (!parsed) {
-      writeJson(response, 404, { success: false, error: 'Not found' });
-      return;
+      return reply(404, { success: false, error: 'Not found' });
     }
     const messageId = Number(url.searchParams.get('messageId'));
     const expectedSessionId = url.searchParams.get('sessionId');
     if (messageAction && (!Number.isSafeInteger(messageId) || messageId < 1 || !expectedSessionId)) {
-      writeJson(response, 400, { success: false, error: '需要 sessionId 和正安全整数 messageId' });
-      return;
+      return reply(400, { success: false, error: '需要 sessionId 和正安全整数 messageId' });
     }
     const lease = acquireSessionTree();
     if (!lease) {
-      unavailable(response);
-      return;
+      return unavailable(headers);
     }
     const runtime = lease.tree;
     try {
       if (messageAction && !runtime.readBranchMessage) {
-        writeJson(response, 501, { success: false, error: '当前 Agent runtime 不支持读取完整消息' });
-        return;
+        return reply(501, { success: false, error: '当前 Agent runtime 不支持读取完整消息' });
       }
       const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
       if (messageAction) {
         if (!sessionId) {
-          writeJson(response, 404, { success: false, error: '未找到活跃会话' });
-          return;
+          return reply(404, { success: false, error: '未找到活跃会话' });
         }
         if (sessionId !== expectedSessionId) {
-          writeJson(response, 409, { success: false, error: '会话已变化，请重新读取会话列表' });
-          return;
+          return reply(409, { success: false, error: '会话已变化，请重新读取会话列表' });
         }
         const text = await runtime.readBranchMessage!(sessionId, messageId);
         if (text === null) {
-          writeJson(response, 404, { success: false, error: '未找到此会话的用户消息' });
-          return;
+          return reply(404, { success: false, error: '未找到此会话的用户消息' });
         }
-        writeJson(response, 200, { success: true, data: { messageId, text } });
-        return;
+        return reply(200, { success: true, data: { messageId, text } });
       }
       if (!sessionId) {
         if (!isRuntimeImSessionKey(parsed.sessionKey)) {
-          writeJson(response, 404, {
+          return reply(404, {
             success: false,
             error: `未找到会话：${parsed.sessionKey}`,
           });
-          return;
         }
         const knownConversation = await ctx.isKnownConversationSession?.(parsed.sessionKey);
         if (knownConversation === false) {
-          writeJson(response, 404, {
+          return reply(404, {
             success: false,
             error: `未找到会话：${parsed.sessionKey}`,
           });
-          return;
         }
         // 渠道会话与 Agent 会话的生命周期不同：用户可以先在 Console
         // 选中一个真实渠道会话，而该会话尚未触发过 Agent。树查询是只读操作，
         // 因而将这种正常状态返回为可渲染空态，而不是误报资源不存在。
-        writeJson(response, 200, {
+        return reply(200, {
           success: true,
           data: {
             state: 'not_started',
@@ -391,12 +391,11 @@ export function registerAgentSessionRoutes(
             points: [],
           },
         });
-        return;
       }
 
       const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
       const points = await runtime.listBranchPoints(sessionId);
-      writeJson(response, 200, {
+      return reply(200, {
         success: true,
         data: {
           state: 'active',
@@ -411,20 +410,19 @@ export function registerAgentSessionRoutes(
     }
   }, { summary: 'Get agent session tree or message', tags: ['console', 'agent'] });
 
-  route('POST', `${base}/agent/sessions/*`, async (request, response, url, authScope) => {
+  route('POST', `${base}/agent/sessions/*`, async (request, { url }) => {
     const parsed = parseSessionAction(url.pathname, prefix, 'leaf');
     if (!parsed) {
-      writeJson(response, 404, { success: false, error: 'Not found' });
-      return;
+      return jsonResponse(404, { success: false, error: 'Not found' });
     }
-    if (!requireWriteScope(response, ctx, authScope)) return;
+    const denied = requireWriteScope(ctx);
+    if (denied) return denied;
     let body: Record<string, unknown>;
     try {
       body = (await readJsonBody(request) ?? {}) as Record<string, unknown>;
     } catch (error) {
       if (error instanceof HttpBodyError) {
-        writeJson(response, error.statusCode, { success: false, error: error.message });
-        return;
+        return jsonResponse(error.statusCode, { success: false, error: error.message });
       }
       throw error;
     }
@@ -435,42 +433,37 @@ export function registerAgentSessionRoutes(
     if (messageIdRaw != null && messageIdRaw !== '') {
       const value = Number(messageIdRaw);
       if (!Number.isFinite(value) || value < 1) {
-        writeJson(response, 400, { success: false, error: 'messageId 须为正整数' });
-        return;
+        return jsonResponse(400, { success: false, error: 'messageId 须为正整数' });
       }
       messageId = value;
     } else if (indexRaw != null && indexRaw !== '') {
       const value = Number(indexRaw);
       if (!Number.isFinite(value) || value < 1) {
-        writeJson(response, 400, { success: false, error: 'index 须为正整数' });
-        return;
+        return jsonResponse(400, { success: false, error: 'index 须为正整数' });
       }
       branchIndex = value;
     } else {
-      writeJson(response, 400, { success: false, error: '需要 messageId 或 index 之一' });
-      return;
+      return jsonResponse(400, { success: false, error: '需要 messageId 或 index 之一' });
     }
 
     const lease = acquireSessionTree();
     if (!lease) {
-      unavailable(response);
-      return;
+      return unavailable();
     }
     const runtime = lease.tree;
     try {
       const sessionId = await runtime.resolveActiveSessionId(parsed.sessionKey);
       if (!sessionId) {
-        writeJson(response, 404, {
+        return jsonResponse(404, {
           success: false,
           error: `未找到活跃会话：${parsed.sessionKey}`,
         });
-        return;
       }
 
       if (branchIndex !== undefined) {
         const result = await runtime.jumpToBranchIndex(sessionId, branchIndex);
         const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
-        writeJson(response, result.ok ? 200 : 400, {
+        return jsonResponse(result.ok ? 200 : 400, {
           success: result.ok,
           message: result.message,
           data: {
@@ -479,12 +472,11 @@ export function registerAgentSessionRoutes(
             activeLeafMessageId,
           },
         });
-        return;
       }
 
       const ok = await runtime.switchActiveLeaf(sessionId, messageId!);
       const activeLeafMessageId = await runtime.getActiveLeafMessageId(sessionId);
-      writeJson(response, ok ? 200 : 400, {
+      return jsonResponse(ok ? 200 : 400, {
         success: ok,
         message: ok ? `已切换 active leaf 至消息 #${messageId}` : '切换失败',
         data: {
@@ -576,18 +568,13 @@ export function parsePositiveInt(raw: string | null, fallback: number): number {
 // helpers
 // ---------------------------------------------------------------------------
 
-/** 写操作门禁：demo 部署（ctx.fullScope=false）或 demo token 均 403。 */
-export function requireWriteScope(
-  response: ServerResponse,
-  ctx: ConsoleRestCtx,
-  authScope: AuthScope,
-): boolean {
-  if (ctx.fullScope && authScope === 'full') return true;
-  writeJson(response, 403, {
+/** 写操作门禁：demo 部署（ctx.fullScope=false）返回 403 响应，放行时返回 undefined。 */
+export function requireWriteScope(ctx: ConsoleRestCtx): Response | undefined {
+  if (ctx.fullScope) return undefined;
+  return jsonResponse(403, {
     success: false,
     error: 'Demo scope: 只读访问，写操作被拒绝',
   });
-  return false;
 }
 
 export function decodePathParam(raw: string): string {
@@ -608,12 +595,3 @@ export function normalizeBase(value: string): string {
   if (!value.startsWith('/')) return `/${value}`;
   return trimTrailingSlashes(value) || '/api';
 }
-
-export function writeJson(response: ServerResponse, status: number, body: unknown): void {
-  const payload = JSON.stringify(body);
-  response.writeHead(status, {
-    'content-type': 'application/json; charset=utf-8',
-    'content-length': Buffer.byteLength(payload),
-  });
-  response.end(payload);
-}