@zhin.js/host-http 1.2.2 → 1.3.0

package/src/console-rest-pages.ts

@@ -17,6 +17,15 @@ import {
   isValidNpmPackageName,
 } from './marketplace-registry.js';
 import type { ConsoleMessageEventData } from '@zhin.js/console-protocol';
+import {
+  informativeKeywords,
+  isLocale,
+  normalizePluginCategory,
+  packageAuthorName,
+  pickLocalizedText,
+  readPluginMarketplaceMetadata,
+  type PluginLocalizedText,
+} from '@zhin.js/plugin-runtime';
 import {
   clampPositiveInt,
   decodePathParam,
@@ -65,7 +74,10 @@ export interface ConsoleAgentIntrospection {
   commands?(): readonly unknown[];
   middlewares?(): readonly unknown[];
   components?(): readonly unknown[];
-  bindings?(): readonly unknown[];
+  /** Agent bindings with the provider / model they actually run on (may read the provider graph). */
+  bindings?(): readonly unknown[] | Promise<readonly unknown[]>;
+  /** Recent Agent turns from the trace archive, newest first (#1250). */
+  recentTurns?(): readonly unknown[] | Promise<readonly unknown[]>;
   tools?(): readonly unknown[];
   promptSections?(): readonly unknown[];
   mcp?(): { rows: readonly unknown[]; note?: string } | readonly unknown[];
@@ -356,6 +368,11 @@ function registerLogsRoutes(
   }, { summary: 'Cleanup old system logs', tags: ['console', 'logs'] });
 }
 
+/** Locale-keyed texts from an untrusted registry entry (reuses the published-manifest reader). */
+function localizedTextOf(value: unknown): PluginLocalizedText | undefined {
+  return readPluginMarketplaceMetadata({ metadata: { displayNameI18n: value } }).displayNameI18n;
+}
+
 // ---------------------------------------------------------------------------
 // marketplace（legacy marketplace-rest-api.ts；plugins.json + npmmirror）
 // ---------------------------------------------------------------------------
@@ -390,10 +407,17 @@ function registerMarketplaceRoutes(
       const versions = meta.versions as Record<string, Record<string, unknown>> | undefined;
       const latestInfo = latest && versions ? versions[latest] : undefined;
       const time = meta.time as Record<string, string> | undefined;
+      // Marketplace fields come from the published manifest (`zhin.metadata`); the author is the
+      // package's author / maintainers, never the publishing account (`_npmUser`, a release bot).
+      const market = readPluginMarketplaceMetadata(latestInfo?.zhin);
       return {
         name: meta.name,
         version: latest,
-        description: meta.description || '',
+        ...(market.displayName ? { displayName: market.displayName } : {}),
+        ...(market.displayNameI18n ? { displayNameI18n: market.displayNameI18n } : {}),
+        ...(market.descriptionI18n ? { descriptionI18n: market.descriptionI18n } : {}),
+        ...(market.category ? { category: market.category } : {}),
+        description: (latestInfo?.description as string | undefined) || meta.description || '',
         readme: meta.readme || '',
         license: meta.license || latestInfo?.license || '',
         homepage: meta.homepage || latestInfo?.homepage || '',
@@ -401,11 +425,8 @@ function registerMarketplaceRoutes(
           (meta.repository as { url?: string } | undefined)?.url ||
           (latestInfo?.repository as { url?: string } | undefined)?.url ||
           '',
-        author:
-          typeof meta.author === 'string'
-            ? meta.author
-            : (meta.author as { name?: string } | undefined)?.name || '',
-        keywords: (latestInfo?.keywords as string[]) || [],
+        author: packageAuthorName(latestInfo ?? {}) ?? packageAuthorName(meta) ?? '',
+        keywords: informativeKeywords(latestInfo?.keywords),
         engines: latestInfo?.engines || {},
         peerDependencies: latestInfo?.peerDependencies || {},
         versions: Object.keys(versions || {}),
@@ -421,32 +442,48 @@ function registerMarketplaceRoutes(
       100,
       Math.max(1, parseInt(url.searchParams.get('size') ?? url.searchParams.get('limit') ?? '20', 10) || 20),
     );
-    const category = url.searchParams.get('category') ?? undefined;
+    const rawCategory = url.searchParams.get('category') || undefined;
+    const category = rawCategory === undefined ? undefined : normalizePluginCategory(rawCategory) ?? rawCategory;
     const official = url.searchParams.get('official') ?? undefined;
+    const rawLocale = url.searchParams.get('locale');
+    const locale = isLocale(rawLocale) ? rawLocale : undefined;
     const searchKeyword = q.trim().toLowerCase();
 
     try {
       const allPlugins = (await registry.list()) as readonly Record<string, unknown>[];
-      let plugins = allPlugins.map((p) => ({
+      let plugins = allPlugins.map((p) => {
+        const displayNameI18n = localizedTextOf(p.displayNameI18n);
+        const descriptionI18n = localizedTextOf(p.descriptionI18n);
+        const displayName = typeof p.displayName === 'string' ? p.displayName : '';
+        const description = typeof p.description === 'string' ? p.description : '';
+        return {
         name: p.name,
-        displayName: p.displayName || '',
+        // `locale` resolves the display texts for the caller; translations stay available either way.
+        displayName: locale ? pickLocalizedText(displayNameI18n, locale, displayName) ?? '' : displayName,
+        ...(displayNameI18n ? { displayNameI18n } : {}),
         version: p.version || '',
-        description: p.description || '',
+        description: locale ? pickLocalizedText(descriptionI18n, locale, description) ?? '' : description,
+        ...(descriptionI18n ? { descriptionI18n } : {}),
         author: p.author || '',
         isOfficial: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
         official: typeof p.name === 'string' && /^@zhin\.js\/[a-z0-9][a-z0-9._-]*$/.test(p.name),
-        category: p.category || 'util',
-        keywords: (p.tags as string[]) || [],
+        category: normalizePluginCategory(p.category) ?? 'utility',
+        keywords: informativeKeywords(p.tags),
         npm: p.npm || `https://www.npmjs.com/package/${p.name}`,
         date: p.lastUpdate || '',
         downloads: p.downloads || { weekly: 0, monthly: 0 },
         readme: p.readme || '',
         license: p.license || '',
-      }));
+        };
+      });
 
       if (searchKeyword) {
         plugins = plugins.filter((p) => {
-          const haystack = [p.name, p.displayName, p.description, ...(p.keywords || [])]
+          const haystack = [
+            p.name, p.displayName, p.description,
+            ...Object.values(p.displayNameI18n ?? {}), ...Object.values(p.descriptionI18n ?? {}),
+            ...p.keywords,
+          ]
             .join(' ')
             .toLowerCase();
           return haystack.includes(searchKeyword);

package/src/console-rpc-extended/contracts.ts

@@ -22,6 +22,11 @@ export interface ConsoleRpcExtendedCtx {
   databaseHost?: { models: { get(name: string): unknown } };
   /** Narrow generation-bound persistent-job port; null when Assistant is disabled. */
   resolveScheduleEngine?: () => ConsoleScheduleEngine | null | undefined;
+  /**
+   * Resolves a persistent job's delivery target (#1250): `{ resolved, display?, reason? }`, where
+   * `resolved: false` means the job's results cannot be delivered (no target / unknown account).
+   */
+  describeScheduleTarget?: (notify: unknown) => ConsoleScheduleTarget;
   /** LoginAssist list/submit/cancel（刷新后仍可消费扫码/滑块待办）；ADR 0058 flow methods are optional. */
   loginAssist?: ConsoleLoginAssistPort;
   /** ADR 0058: the Endpoint's login declaration and lease-scoped login control (`null` = unknown Endpoint). */
@@ -160,6 +165,11 @@ export interface ScheduleJobRow {
   id: string;
   cron: string;
   description?: string;
+  /** Host display metadata (`ScheduleJobDisplay` in `@zhin.js/plugin-runtime`). */
+  title?: string;
+  titleI18n?: Readonly<Partial<Record<string, string>>>;
+  kind?: 'plugin-internal' | 'user-task';
+  lastRun?: { startedAt: number; finishedAt: number; status: 'succeeded' | 'failed'; error?: string };
 }
 
 export interface InboxSelection {
@@ -219,3 +229,11 @@ export interface EndpointManagementPort {
   setGroupAdmin?(request: EndpointAdminCommand): Promise<void>;
   deleteFriend?(request: EndpointUserCommand): Promise<void>;
 }
+
+/** `target` of a `schedule:list` persistent row (#1250). */
+export interface ConsoleScheduleTarget {
+  readonly resolved: boolean;
+  readonly display?: string;
+  /** `missing_target` | `incomplete_target` | `endpoint_not_found` */
+  readonly reason?: string;
+}

package/src/console-rpc-extended/dispatcher.ts

@@ -21,7 +21,7 @@ export async function dispatchExtendedConsoleRpc(
   switch (type) {
     case 'schedule:list':
     case 'cron:list':
-      return listSchedule(ctx);
+      return listSchedule(ctx, d);
 
     case 'cron:validate':
       return validateCron(d);

package/src/console-rpc-extended/endpoint-rpc.ts

@@ -1,4 +1,5 @@
 import type { ConsoleRpcExtendedCtx, EndpointManagementPort, ExtendedRpcResult } from './contracts.js';
+import type { EndpointManagementCapability } from '@zhin.js/console-protocol';
 import { boolField, numField, strField, withLiveEndpoint } from './rpc-values.js';
 
 export async function listFriends(
@@ -12,7 +13,7 @@ export async function listFriends(
       const friends = [...await management.listFriends()];
       return { data: { friends, count: friends.length } };
     }
-    return { error: `当前适配器（${endpoint.adapter}）不支持好友列表` };
+    return unsupportedList('friends', 'listFriends', endpoint.adapter, '好友列表');
   });
 }
 
@@ -27,7 +28,7 @@ export async function listGroups(
       const groups = [...await management.listGroups()];
       return { data: { groups, count: groups.length } };
     }
-    return { error: `当前适配器（${endpoint.adapter}）不支持群列表` };
+    return unsupportedList('groups', 'listGroups', endpoint.adapter, '群列表');
   });
 }
 
@@ -42,7 +43,7 @@ export async function listChannels(
       const channels = [...await management.listChannels()];
       return { data: { channels, count: channels.length } };
     }
-    return { error: `当前适配器（${endpoint.adapter}）不支持频道列表` };
+    return unsupportedList('channels', 'listChannels', endpoint.adapter, '频道列表');
   });
 }
 
@@ -59,13 +60,36 @@ export async function listGroupMembers(
   return withLiveEndpoint(ctx, adapter, endpointKey, async (management) => {
     const method = management.listGroupMembers;
     if (!method) {
-      return { error: `当前适配器（${adapter}）不支持群成员列表` };
+      return unsupportedList('members', 'listGroupMembers', adapter, '群成员列表');
     }
     const members = [...await method.call(management, { groupId })];
     return { data: { members, count: members.length } };
   });
 }
 
+/**
+ * A read the Adapter does not declare is not a failure (#1250): reply with an empty list plus
+ * `status: 'unsupported'` (`ConsoleEndpointCapabilityUnsupported`) instead of `{ error }`, so the
+ * Console can render "该平台不提供" rather than a red read error. Older clients still see an empty
+ * list with `count: 0`.
+ */
+function unsupportedList(
+  key: 'friends' | 'groups' | 'channels' | 'members',
+  capability: EndpointManagementCapability,
+  adapter: string,
+  label: string,
+): ExtendedRpcResult {
+  return {
+    data: {
+      [key]: [],
+      count: 0,
+      status: 'unsupported',
+      capability,
+      message: `当前适配器（${adapter}）不支持${label}`,
+    },
+  };
+}
+
 // ---------------------------------------------------------------- 群管/好友写操作
 
 interface GroupWriteSpec {

package/src/console-rpc-extended/index.ts

@@ -1,6 +1,7 @@
 export type {
   ConsoleRpcExtendedCtx,
   ConsoleScheduleEngine,
+  ConsoleScheduleTarget,
   ConsoleWorkroomKnowledgeControlPort,
   ConsoleWorkroomProfileControlPort,
   ExtendedRpcResult,

package/src/console-rpc-extended/schedule-rpc.ts

@@ -6,7 +6,32 @@ const CRON_NOT_WIRED =
   '持久化调度未接线：当前 Plugin Runtime ScheduleHost 仅支持插件注册的内存任务（list），' +
   '不支持 add/remove/pause/resume（需要 @zhin.js/agent 持久化调度引擎）';
 
-export function listSchedule(ctx: ConsoleScheduleListCtx): Promise<ExtendedRpcResult> | ExtendedRpcResult {
+/** `titleI18n[locale]` → `titleI18n[language]` → `title`. */
+function localizedTitle(job: ScheduleJobRow, locale: string | undefined): string | undefined {
+  const map = job.titleI18n && typeof job.titleI18n === 'object' ? job.titleI18n : undefined;
+  if (locale && map) {
+    const exact = map[locale];
+    if (typeof exact === 'string' && exact.trim()) return exact.trim();
+    const language = locale.split('-')[0]!;
+    const byLanguage = map[language];
+    if (typeof byLanguage === 'string' && byLanguage.trim()) return byLanguage.trim();
+  }
+  return typeof job.title === 'string' && job.title.trim() ? job.title.trim() : undefined;
+}
+
+function lastRunFields(job: ScheduleJobRow): Record<string, unknown> {
+  const run = job.lastRun;
+  if (!run || typeof run !== 'object' || typeof run.startedAt !== 'number') return {};
+  return {
+    lastExecutedAt: run.startedAt,
+    ...(typeof run.finishedAt === 'number' ? { lastFinishedAt: run.finishedAt, lastDurationMs: Math.max(0, run.finishedAt - run.startedAt) } : {}),
+    lastStatus: run.status === 'failed' ? 'failed' : 'succeeded',
+    ...(run.status === 'failed' && typeof run.error === 'string' ? { lastError: run.error } : {}),
+  };
+}
+
+export function listSchedule(ctx: ConsoleScheduleListCtx, d: Record<string, unknown> = {}): Promise<ExtendedRpcResult> | ExtendedRpcResult {
+  const locale = typeof d.locale === 'string' && d.locale.trim() ? d.locale.trim() : undefined;
   const host = ctx.scheduleHost as { list?: () => unknown } | undefined;
   if (!host || typeof host.list !== 'function') {
     return { error: '调度服务未配置（scheduleHost 未挂载）' };
@@ -18,17 +43,26 @@ export function listSchedule(ctx: ConsoleScheduleListCtx): Promise<ExtendedRpcRe
         !!job && typeof job === 'object'
         && typeof (job as ScheduleJobRow).id === 'string'
         && typeof (job as ScheduleJobRow).cron === 'string')
-      .map((job) => ({
+      .map((job) => {
+        const title = localizedTitle(job, locale);
+        return {
         id: job.id,
         cron: job.cron,
         ...(typeof job.description === 'string' ? { description: job.description } : {}),
+        // #1250: plugin polling is not a user reminder; title is localized, displayName never falls back to a bare id when a title exists.
+        kind: job.kind === 'user-task' ? 'user-task' : 'plugin-internal',
+        ...(title ? { title } : {}),
+        ...(job.titleI18n && typeof job.titleI18n === 'object' ? { titleI18n: job.titleI18n } : {}),
+        displayName: title ?? (typeof job.description === 'string' && job.description ? job.description : job.id),
+        ...lastRunFields(job),
         // console cron 页渲染字段（由 schedule host 提供时透传）
         expression: (job as { expression?: string }).expression ?? job.cron,
         running: (job as { running?: boolean }).running ?? true,
         ...((job as { plugin?: string }).plugin ? { plugin: (job as { plugin?: string }).plugin } : {}),
         ...((job as { nextExecution?: number }).nextExecution
           ? { nextExecution: (job as { nextExecution?: number }).nextExecution } : {}),
-      }));
+        };
+      });
     return listPersistentJobs(ctx).then((persistent) => ({ data: { memory, persistent, capabilities: { persistent: !!ctx.resolveScheduleEngine?.() && ctx.fullScope } } })).catch((error) => ({ error: errorMessage(error) }));
   } catch (error) {
     return { error: errorMessage(error) };
@@ -50,10 +84,14 @@ async function listPersistentJobs(ctx: ConsoleRpcExtendedCtx): Promise<Record<st
       prompt: (job.action as { prompt?: string } | undefined)?.prompt ?? '',
       enabled: job.enabled !== false,
       source: job.source ?? 'manual',
+      // Persistent jobs are created by a person or on their behalf by the Agent.
+      kind: 'user-task',
       createdAt: (job as { createdAt?: number }).createdAt,
       nextExecution: (job.state as { nextRunAtMs?: number } | undefined)?.nextRunAtMs,
       ...((job.notify as { target?: unknown } | undefined)?.target
         ? { context: { target: (job.notify as { target?: unknown }).target } } : {}),
+      // #1250: the resolved delivery target; `resolved: false` = results cannot be delivered.
+      ...(ctx.describeScheduleTarget ? { target: ctx.describeScheduleTarget(job.notify) } : {}),
       lastExecutedAt: (job.state as { lastExecutedAt?: number } | undefined)?.lastExecutedAt,
       lastStatus: (job.state as { lastStatus?: string } | undefined)?.lastStatus,
     }));
@@ -62,6 +100,22 @@ async function listPersistentJobs(ctx: ConsoleRpcExtendedCtx): Promise<Record<st
   }
 }
 
+/** The account (`adapter` / `endpoint`) a schedule delivery target sends from, if it names one. */
+function deliveryAccount(target: unknown): { adapter: string; endpoint: string } | undefined {
+  if (typeof target === 'string') {
+    // `<adapter>:<endpoint>:<kind>:<id>`
+    const [adapter, endpoint] = target.split(':');
+    return adapter && endpoint ? { adapter, endpoint } : undefined;
+  }
+  if (!target || typeof target !== 'object') return undefined;
+  const scene = (target as { scene?: unknown }).scene;
+  if (!scene || typeof scene !== 'object') return undefined;
+  const { platform, endpointKey } = scene as { platform?: unknown; endpointKey?: unknown };
+  return typeof platform === 'string' && platform && typeof endpointKey === 'string' && endpointKey
+    ? { adapter: platform, endpoint: endpointKey }
+    : undefined;
+}
+
 export async function addCron(
   d: Record<string, unknown>,
   ctx: ConsoleRpcExtendedCtx,
@@ -80,6 +134,16 @@ export async function addCron(
   const label = typeof d.label === 'string' && d.label.trim() ? d.label.trim() : undefined;
   const context = (d.context ?? {}) as Record<string, unknown>;
   const target = context.target ?? context.channel;
+  // A delivery target sends to that account on every run: `endpoint.operate` there, like
+  // `/message/send`, on top of `ops.schedule.write` (absent check = trusted in-process caller).
+  if (target && ctx.canOperateEndpoint) {
+    const account = deliveryAccount(target);
+    if (!account || !ctx.canOperateEndpoint(account.adapter, account.endpoint)) {
+      return { error: account
+        ? `没有向该账号投递的权限：需要 ${account.adapter} / ${account.endpoint} 上的 endpoint.operate`
+        : '投递目标需要指明账号（scene.platform 与 scene.endpointKey）' };
+    }
+  }
   const job = {
     id: `console-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`,
     ...(label ? { label } : {}),

package/src/console-rpc-handlers.ts

@@ -1,7 +1,11 @@
 import {
   CONFIG_PATCH_LIMITS,
+  CONSOLE_SEND_FAILURE_MESSAGES,
   ENDPOINT_RPC,
+  classifyConsoleSendFailure,
   type ConsoleConfigApplicationStatus,
+  type ConsoleSendFailure,
+  type ConsoleSendFailureStatus,
 } from '@zhin.js/console-protocol';
 import type {
   ConversationAddress,
@@ -30,6 +34,43 @@ export function wireConversation(
   };
 }
 
+const SEND_FAILURE_STATUSES: ReadonlySet<string> = new Set(['failed', 'rejected', 'unsupported', 'suppressed']);
+
+/**
+ * Structural read of an outbound failure (#1250): Core's `EndpointDeliveryError` carries `code`,
+ * `disposition` and the canonical receipt; host/http must not import Core, so only those fields are
+ * read. `endpoint not found` is the Endpoint directory's plain error. An error counts as a send
+ * failure only when its `code` is a known delivery code or it carries a `disposition` / `receipt`;
+ * anything else (a Node `ENOENT`, a database error, …) is unclassified and keeps its own message.
+ */
+export function consoleSendFailure(error: unknown): ConsoleSendFailure | undefined {
+  if (!(error instanceof Error)) return undefined;
+  const record = error as Error & { code?: unknown; disposition?: unknown; receipt?: unknown };
+  if (typeof record.code !== 'string' || !record.code) {
+    return error.message === 'endpoint not found'
+      ? { code: 'endpoint_not_found', reason: 'endpoint_not_found', status: 'failed' }
+      : undefined;
+  }
+  // Every known delivery code maps to a reason other than the catch-all `failed`.
+  const knownCode = classifyConsoleSendFailure(record.code) !== 'failed';
+  const delivery = typeof record.disposition === 'string' || (!!record.receipt && typeof record.receipt === 'object');
+  if (!knownCode && !delivery) return undefined;
+  const receipt = record.receipt && typeof record.receipt === 'object'
+    ? record.receipt as { status?: unknown; failure?: { retryable?: unknown; deliveryUnknown?: unknown } }
+    : undefined;
+  const status: ConsoleSendFailureStatus = record.disposition === 'unknown' || receipt?.failure?.deliveryUnknown === true
+    ? 'unknown'
+    : typeof receipt?.status === 'string' && SEND_FAILURE_STATUSES.has(receipt.status)
+      ? receipt.status as ConsoleSendFailureStatus
+      : record.disposition === 'rejected' ? 'rejected' : 'failed';
+  return {
+    code: record.code,
+    reason: classifyConsoleSendFailure(record.code, status),
+    status,
+    ...(receipt?.failure?.retryable === true ? { retryable: true } : {}),
+  };
+}
+
 const FORBIDDEN_PATCH_SEGMENTS = new Set(['__proto__', 'constructor', 'prototype']);
 
 /**
@@ -145,12 +186,12 @@ export async function dispatchHostResourceConsoleRpc(
           emit({ requestId, error: 'filename is required' });
           return true;
         }
-        if (!ctx.readEnvFile) {
+        // Masked only (issue #1250): the file as written is never answered here.
+        if (!ctx.readEnvFileView) {
           emit({ requestId, error: 'Env read is not configured' });
           return true;
         }
-        const content = await ctx.readEnvFile(filename);
-        emit({ requestId, data: { content } });
+        emit({ requestId, data: await ctx.readEnvFileView(filename) });
       } catch (error) {
         emit({
           requestId,
@@ -159,23 +200,70 @@ export async function dispatchHostResourceConsoleRpc(
       }
       return true;
     }
+    case 'env:reveal': {
+      try {
+        const filename = String(message.filename ?? '');
+        const key = message.key;
+        if (!filename) {
+          emit({ requestId, error: 'filename is required' });
+          return true;
+        }
+        if (typeof key !== 'string' || !key) {
+          emit({ requestId, error: 'key is required' });
+          return true;
+        }
+        if (!ctx.revealEnvVariable) {
+          emit({ requestId, error: 'Env reveal is not configured' });
+          return true;
+        }
+        emit({ requestId, data: await ctx.revealEnvVariable(filename, key) });
+      } catch (error) {
+        emit({
+          requestId,
+          error: `Failed to reveal env variable: ${error instanceof Error ? error.message : String(error)}`,
+        });
+      }
+      return true;
+    }
     case 'env:save': {
       try {
         const filename = String(message.filename ?? '');
-        const content = message.content;
         if (!filename) {
           emit({ requestId, error: 'filename is required' });
           return true;
         }
-        if (typeof content !== 'string') {
-          emit({ requestId, error: 'content field is required' });
+        const hasChanges = message.changes !== undefined;
+        const hasContent = message.content !== undefined;
+        if (hasChanges && hasContent) {
+          emit({ requestId, error: 'changes 与 content 只能提供一个' });
           return true;
         }
-        if (!ctx.writeEnvFile) {
+        if (hasChanges) {
+          if (!ctx.updateEnvVariables) {
+            emit({ requestId, error: 'Env write is not configured' });
+            return true;
+          }
+          const { changed } = await ctx.updateEnvVariables(filename, message.changes);
+          emit({ requestId, data: { success: true, message: `环境文件已保存: ${filename}`, changed } });
+          return true;
+        }
+        if (typeof message.content !== 'string') {
+          emit({ requestId, error: 'changes field is required' });
+          return true;
+        }
+        // The whole-file form must be asked for: an older Console sends back what `env:get` showed it.
+        if (message.mode !== 'replace') {
+          emit({
+            requestId,
+            error: '此 Host 只接受逐键保存（changes）；整文件保存需显式声明 mode: "replace"。请升级 Console 后重试',
+          });
+          return true;
+        }
+        if (!ctx.replaceEnvFile) {
           emit({ requestId, error: 'Env write is not configured' });
           return true;
         }
-        await ctx.writeEnvFile(filename, content);
+        await ctx.replaceEnvFile(filename, message.content);
         emit({ requestId, data: { success: true, message: `环境文件已保存: ${filename}` } });
       } catch (error) {
         emit({
@@ -555,9 +643,11 @@ export async function dispatchHostResourceConsoleRpc(
         });
         emit({ requestId, data: { messageId: result.messageId } });
       } catch (error) {
+        const failure = consoleSendFailure(error);
         emit({
           requestId,
-          error: error instanceof Error ? error.message : String(error),
+          error: failure ? CONSOLE_SEND_FAILURE_MESSAGES[failure.reason] : error instanceof Error ? error.message : String(error),
+          ...(failure ? { data: failure } : {}),
         });
       }
       return true;

package/src/console-rpc-types.ts

@@ -0,0 +1,45 @@
+/**
+ * RPC types the runtime Console dispatcher of this package answers (`dispatchRuntimeConsoleRpc`:
+ * shell, configuration, plugin management, project files / environment / database, endpoints,
+ * schedules, inbox, login assist, workrooms). Used to tell an RPC this Host has but forgot to map
+ * (audited `unmapped`) from one it does not have at all (`unknown_rpc`, zhinjs/zhin#1250), and to
+ * build the Host's capability list. `console-rpc-types.test.ts` keeps it in step with the
+ * dispatchers' `case` labels.
+ */
+import { CONFIG_RPC, ENDPOINT_RPC, PLUGIN_RPC } from '@zhin.js/console-protocol';
+
+export const RUNTIME_CONSOLE_RPC_TYPES: ReadonlySet<string> = new Set<string>([
+  // Shell
+  'ping', 'entries:get', 'pages:list',
+  // Configuration
+  ...Object.values(CONFIG_RPC),
+  'workrooms:get', 'workrooms:set',
+  // Plugin management (the global switch is refused with a pointer to the gateway)
+  ...Object.values(PLUGIN_RPC),
+  // Project files / environment / schemas / database / process
+  'files:tree', 'files:read', 'files:save',
+  'env:list', 'env:get', 'env:reveal', 'env:save',
+  'schema:get', 'schema:get-all',
+  'db:info', 'db:tables', 'db:select', 'db:query', 'db:execute',
+  'db:schema:describe', 'db:schema:preview', 'db:schema:apply',
+  'db:insert', 'db:update', 'db:delete', 'db:drop-table',
+  'db:kv:get', 'db:kv:set', 'db:kv:delete', 'db:kv:entries',
+  'system:restart',
+  // Endpoints
+  ...Object.values(ENDPOINT_RPC),
+  // Schedules
+  'schedule:list', 'cron:list', 'cron:validate', 'cron:add', 'cron:remove', 'cron:pause', 'cron:resume',
+  // Requests / notices / inbox
+  'request.list', 'request.approve', 'request.reject', 'request.consumed', 'notice.consumed',
+  'inbox.requests', 'inbox.notices', 'inbox.messages', 'inbox.recent',
+  // Login assist
+  'login.list', 'login.submit', 'login.cancel', 'login.flow.list', 'login.flow.get', 'login.relogin', 'login.refresh',
+  // Workroom profiles / knowledge
+  'workroom.profile.status', 'workroom.profile.bootstrap', 'workroom.profile.pack.publish',
+  'workroom.profile.publish', 'workroom.profile.rollback', 'workroom.profile.policy.publish',
+  'workroom.knowledge.get', 'workroom.knowledge.publish', 'workroom.knowledge.rollback',
+]);
+
+export function isRuntimeConsoleRpcType(type: unknown): type is string {
+  return typeof type === 'string' && RUNTIME_CONSOLE_RPC_TYPES.has(type);
+}

package/src/console-rpc.ts

@@ -3,6 +3,7 @@ import type { DatabaseHostConsole } from '@zhin.js/plugin-runtime';
 import {
   CONFIG_PATCH_LIMITS,
   CONFIG_RPC,
+  CONSOLE_UNKNOWN_RPC_CODE,
   grantsAllow,
   type ConsoleConfigPatchRequest,
   type ConsoleConfigPatchResult,
@@ -12,6 +13,7 @@ import {
   type ConsoleEndpointSummary,
 } from '@zhin.js/console-protocol';
 import { authorizeConsoleRpc, principalAllows, type ConsolePrincipal } from './access-control.js';
+import { isRuntimeConsoleRpcType } from './console-rpc-types.js';
 import { dispatchExtendedConsoleRpc, type ConsoleRpcExtendedCtx } from './console-rpc-extended/index.js';
 import { dispatchPluginConsoleRpc } from './console-plugin-rpc.js';
 import {
@@ -128,9 +130,21 @@ export interface PluginVerificationResult {
   readonly evidenceI18n?: import('@zhin.js/plugin-runtime').PluginVerificationOutcome['evidenceI18n'];
 }
 
+/** `inspect` options. `dependencies: 'skip'` leaves the project-wide graph check out (`dependencies: 'unchecked'`). */
+export interface PluginInspectOptions {
+  readonly dependencies?: 'check' | 'skip';
+}
+
+/** Result of the project-wide dependency graph check (the same check `inspect` runs per plugin). */
+export type PluginDependencyCheck =
+  | { readonly status: 'passed' }
+  | { readonly status: 'failed'; readonly error: string };
+
 export interface PluginManagementPort {
   explainConfiguration?(instanceKey: string, expectedRevision: string): Promise<ConsoleConfigExplanation>;
-  inspect?(packageName: string): Promise<PluginManagementState>;
+  inspect?(packageName: string, options?: PluginInspectOptions): Promise<PluginManagementState>;
+  /** Runs the project-wide dependency graph check once, for callers that inspect many plugins. */
+  checkDependencies?(): Promise<PluginDependencyCheck>;
   apply?(packageName: string, expectedProjectRevision?: string): Promise<{ readonly requested: boolean; readonly state: PluginManagementState }>;
   verificationPlan?(packageName: string): Promise<PluginVerificationPlan>;
   verify?(packageName: string, checkId: string, expectedGeneration: number | null, expectedProjectRevision: string, expectedCheckRevision: string): Promise<PluginVerificationResult>;
@@ -209,8 +223,21 @@ export type RuntimeConsoleRpcContext = {
   readProjectFile?(filePath: string): Promise<{ content: string; size: number }>;
   saveProjectFile?(filePath: string, content: string): Promise<void>;
   listEnvFiles?(): Promise<readonly { name: string; exists: boolean }[]>;
+  /**
+   * @deprecated Not used any more: `env:get` answers {@link readEnvFileView} only, so the file as
+   * written never reaches the Console (issue #1250).
+   */
   readEnvFile?(filename: string): Promise<string>;
+  /** @deprecated Not used any more: `env:save` writes through {@link updateEnvVariables} / {@link replaceEnvFile}. */
   writeEnvFile?(filename: string, content: string): Promise<void>;
+  /** `env:get`: masked view (key names, masks, lengths; comments and blank lines in place). */
+  readEnvFileView?(filename: string): Promise<import('@zhin.js/console-protocol').ConsoleEnvFileView>;
+  /** `env:reveal`: one variable as written. The route requires `ops.env.write` + `ops.env.read` and audits. */
+  revealEnvVariable?(filename: string, key: string): Promise<import('@zhin.js/console-protocol').ConsoleEnvRevealResult>;
+  /** `env:save { changes }`: validates and writes only the named keys (mask placeholders refused). */
+  updateEnvVariables?(filename: string, changes: unknown): Promise<{ readonly changed: readonly string[] }>;
+  /** `env:save { content, mode: 'replace' }`: whole file; refused when it holds mask placeholders. */
+  replaceEnvFile?(filename: string, content: string): Promise<void>;
   /** Optional schema accessors (plugin schema.json / Runtime schema registry). */
   getSchema?(pluginName?: string): Promise<unknown>;
   getAllSchemas?(): Promise<Record<string, unknown>>;
@@ -288,9 +315,9 @@ export async function dispatchRuntimeConsoleRpc(
   let canOperateEndpoint: ConsoleRpcExtendedCtx['canOperateEndpoint'];
   if (ctx.principal) {
     const principal = ctx.principal;
-    const decision = authorizeConsoleRpc(principal, message as Record<string, unknown>);
+    const decision = authorizeConsoleRpc(principal, message as Record<string, unknown>, { registered: isRuntimeConsoleRpcType });
     if (!decision.allowed) {
-      emit({ requestId, error: decision.error, code: decision.code });
+      emit({ requestId, error: decision.error, code: decision.code, ...(decision.reason ? { reason: decision.reason } : {}) });
       return payloads;
     }
     authorizedEndpoint = scopedAuthorizedEndpoint(principal, decision);
@@ -618,7 +645,7 @@ export async function dispatchRuntimeConsoleRpc(
         });
         return payloads;
       }
-      emit({ requestId, error: `Unknown RPC type: ${type || '<empty>'}` });
+      emit({ requestId, error: `Unknown RPC type: ${type.slice(0, 64) || '<empty>'}`, code: CONSOLE_UNKNOWN_RPC_CODE });
       return payloads;
     }
   }