ylib-syim 0.0.27 → 0.0.29

package/bridges/main.ts

@@ -22,6 +22,8 @@ import {
   saveRuntimeStateSnapshot,
 } from "./runtime/runtime-state-store.ts";
 
+process.env.TZ = "Asia/Shanghai";
+
 // bridges/main 是 Node 侧运行时中枢：
 // 1) 维护配置与 bridge 进程生命周期；
 // 2) 统一汇聚 status/heartbeat/diagnostic/probe 四类运行态；
@@ -1267,6 +1269,12 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
+/** 将 UTC ISO 字符串转为东八区 ISO 字符串（+08:00）。用于「最近探测」等前台展示字段。 */
+function toChina8Iso(utcIso: string): string {
+  const ms = new Date(utcIso).getTime() + 8 * 60 * 60 * 1000;
+  return new Date(ms).toISOString().replace('Z', '+08:00');
+}
+
 // rotateRuntimeInstanceId: 刷新运行实例标识。
 function rotateRuntimeInstanceId(): string {
   // 用于标识一次新的运行代际（例如 restart-all 后）。
@@ -1597,6 +1605,10 @@ function resolveRuntimeRunningForUpdate(params: {
   nextLastEvent: string | null | undefined;
   nextRestartPending: boolean;
 }): boolean {
+  // running 推导规则：
+  // 1) 优先尊重显式 hintedRunning；
+  // 2) event 断链（非 stop 生命周期）不等价于“进程停止”，避免误判；
+  // 3) manual stop / stopped lifecycle / restart_pending 才会收敛为 running=false。
   const {
     previous,
     hintedRunning,
@@ -1651,6 +1663,10 @@ function resolveRuntimeRestartPendingForUpdate(params: {
   nextLinkStatus: RuntimeBotStatus["link_status"];
   nextStatusSource?: RuntimeBotStatus["status_source"] | undefined;
 }): boolean {
+  // restart_pending 推导规则：
+  // - 显式 hint 优先；
+  // - 无显式 hint 时，仅 probe/connected 能清 pending；
+  // - event/manual 的 connected 仍可能是过渡态，保持 pending=true。
   const {
     previous,
     hintedRestartPending,
@@ -1713,6 +1729,7 @@ function resolveStatusProtectWindowMs(entry: RuntimeBotStatus): number {
 function isProbeDowngradeLinkStatus(
   status: RuntimeBotStatus["link_status"],
 ): boolean {
+  // 这些状态都属于“probe 视角的降级态”，可能被新鲜 event 保护逻辑拦截。
   return (
     status === "error" ||
     status === "disconnected" ||
@@ -1723,6 +1740,8 @@ function isProbeDowngradeLinkStatus(
 function resolveRuntimeLifecycleAnchorMsForGuard(
   status: RuntimeBotStatus,
 ): number | null {
+  // 生命周期锚点用于计算保护窗口年龄：
+  // started_at 与 transition_at 取较新值，避免老时间戳误伤新生命周期。
   const startedAtMs = parseIsoTimeMs(
     String(status.started_at || "").trim() || null,
   );
@@ -1739,6 +1758,7 @@ function isWithinRuntimeConnectGraceForGuard(
   status: RuntimeBotStatus,
   nowMs = Date.now(),
 ): boolean {
+  // connect grace 内允许“保守展示”，不急于接受 probe 降级结论。
   const lifecycleAnchorMs = resolveRuntimeLifecycleAnchorMsForGuard(status);
   if (lifecycleAnchorMs == null) return false;
   const lifecycleAgeMs = Math.max(0, nowMs - lifecycleAnchorMs);
@@ -1750,6 +1770,7 @@ function hasFreshRuntimeEventLivenessForProbeGuard(
   nowMs = Date.now(),
   lifecycleAnchorMs: number | null = null,
 ): boolean {
+  // 事件活性保护：只有在生命周期内且事件足够新鲜，才允许覆盖 probe 降级。
   const eventLiveness = runtimeEventLivenessRegistry.get(key);
   const eventAtMs = parseIsoTimeMs(
     String(eventLiveness?.last_event_at || "").trim() || null,
@@ -1765,6 +1786,7 @@ function hasFreshRuntimeEventLivenessForProbeGuard(
 function isConnectedRuntimeEventLivenessName(
   eventName: string | null | undefined,
 ): boolean {
+  // 这些事件被视为“数据面已连通”的强证据。
   const normalized = String(eventName || "")
     .trim()
     .toLowerCase();
@@ -1783,6 +1805,7 @@ function hasFreshConnectedRuntimeEventLivenessForRecovery(
   key: string,
   nowMs = Date.now(),
 ): boolean {
+  // 仅当最近事件本身是 connected 类强证据，才允许作为恢复旁路依据。
   const eventLiveness = runtimeEventLivenessRegistry.get(key);
   if (!isConnectedRuntimeEventLivenessName(eventLiveness?.last_event)) {
     return false;
@@ -1800,6 +1823,7 @@ function shouldGuardProbeDowngradeByFreshEvent(params: {
   prev: RuntimeBotStatus;
   next: RuntimeBotStatus;
 }): boolean {
+  // 规则：connected -> probe 降级时，如果有新鲜 event 事实，则先抑制降级抖动。
   const { key, prev, next } = params;
   if (next.status_source !== "probe") return false;
   if (!isProbeDowngradeLinkStatus(next.link_status)) return false;
@@ -1819,6 +1843,7 @@ function shouldGuardProbeConnectedByEventBroken(params: {
   prev: RuntimeBotStatus;
   next: RuntimeBotStatus;
 }): boolean {
+  // 规则：event 明确 broken 后，probe 的 connected 需要 event 新鲜度二次确认。
   const { key, prev, next } = params;
   const prevSource = prev.status_source || "probe";
   const nextSource = next.status_source || "probe";
@@ -1842,6 +1867,10 @@ type RuntimeConvergenceEvidence = "manual" | "event" | "probe";
 type RuntimeConvergenceSignal = "success" | "failure" | "transient";
 
 function resolveRuntimeConvergencePhase(status: RuntimeBotStatus): RuntimeConvergencePhase {
+  // 收敛阶段：
+  // pending: restart_pending=true；
+  // stopped: manual/disconnected 或 stop 生命周期事件；
+  // steady: 其余状态。
   if (status.restart_pending === true) return "pending";
   if (status.status_source === "manual" && status.link_status === "disconnected") {
     return "stopped";
@@ -1861,6 +1890,7 @@ function resolveRuntimeConvergencePhase(status: RuntimeBotStatus): RuntimeConver
 function resolveRuntimeConvergenceEvidence(
   source: RuntimeBotStatus["status_source"],
 ): RuntimeConvergenceEvidence {
+  // 证据源优先级由写入端控制，这里仅做枚举归一化。
   if (source === "manual") return "manual";
   if (source === "event") return "event";
   return "probe";
@@ -1869,6 +1899,8 @@ function resolveRuntimeConvergenceEvidence(
 function resolveRuntimeConvergenceSignal(
   entry: RuntimeBotStatus,
 ): RuntimeConvergenceSignal {
+  // 信号语义：
+  // success=connected；failure=probe/event 报告的明确失败；其余为 transient。
   if (entry.link_status === "connected") return "success";
   const evidence = resolveRuntimeConvergenceEvidence(entry.status_source);
   if (
@@ -1887,6 +1919,7 @@ function shouldGuardProbeConnectedWhilePendingWithoutEvent(params: {
   prev: RuntimeBotStatus;
   next: RuntimeBotStatus;
 }): boolean {
+  // pending 生命周期里，probe/connected 若缺少新鲜 connected event 证据则先抑制。
   const { key, prev, next } = params;
   const prevPhase = resolveRuntimeConvergencePhase(prev);
   if (prevPhase !== "pending") return false;
@@ -1957,6 +1990,7 @@ function logSuppressedTransition(params: {
 function projectRuntimeBotStatusFromSnapshot(
   snapshot: RuntimeChannelSnapshotEntry,
 ): RuntimeBotStatus {
+  // 快照结构 -> 运行态结构的单点投影，避免多处手工映射字段。
   return {
     platform: snapshot.platform,
     bot_account_id: snapshot.accountId,
@@ -1983,6 +2017,7 @@ function projectRuntimeBotStatusFromSnapshot(
 }
 
 function syncRuntimeChannelSnapshotFromStatus(status: RuntimeBotStatus): void {
+  // 每次状态写入后同步快照镜像，保证对外输出（含重启恢复）稳定可复现。
   const key = keyOf(status.platform, status.bot_account_id);
   runtimeChannelSnapshotRegistry.set(key, {
     key,
@@ -2015,12 +2050,14 @@ function syncRuntimeChannelSnapshotFromStatus(status: RuntimeBotStatus): void {
 }
 
 function getRuntimeBotStatusByKey(key: string): RuntimeBotStatus | undefined {
+  // 优先读 channel snapshot（包含更多持久化字段），fallback 到内存 registry。
   const snapshot = runtimeChannelSnapshotRegistry.get(key);
   if (snapshot) return projectRuntimeBotStatusFromSnapshot(snapshot);
   return runtimeStatusRegistry.get(key);
 }
 
 function listRuntimeBotStatuses(): RuntimeBotStatus[] {
+  // 对外列表统一按 platform+bot_account_id 排序，避免接口结果抖动。
   if (runtimeChannelSnapshotRegistry.size > 0) {
     return Array.from(runtimeChannelSnapshotRegistry.values())
       .map((item) => projectRuntimeBotStatusFromSnapshot(item))
@@ -4496,7 +4533,12 @@ function markRuntimeAccountsConnecting(
   platform: RuntimePlatform,
   accountIds: string[],
   lastEvent = "config_loaded",
+  options?: {
+    preserveExisting?: boolean;
+  },
 ): string[] {
+  // 配置收敛期把指定账号打到 manual/connecting。
+  // preserveExisting=true 时只标记“新增账号”，不覆盖已存在账号当前态。
   const normalizedIds = Array.from(
     new Set(
       accountIds
@@ -4506,7 +4548,12 @@ function markRuntimeAccountsConnecting(
   );
   if (normalizedIds.length === 0) return [];
   const startedAt = nowIso();
+  const preserveExisting = options?.preserveExisting === true;
   for (const accountId of normalizedIds) {
+    if (preserveExisting) {
+      const existing = getRuntimeBotStatusByKey(keyOf(platform, accountId));
+      if (existing) continue;
+    }
     clearRuntimeAccountManualStop(platform, accountId);
     upsertRuntimeStatus({
       platform,
@@ -4625,6 +4672,11 @@ async function reconcileRuntimeStateForConfigDelta(params: {
   nextConfig: Record<string, unknown>;
   trigger: string;
 }): Promise<void> {
+  // 增量 reconcile：
+  // 1) 按平台计算 added/removed；
+  // 2) removed 账号尝试 stop 并清理状态；
+  // 3) added 账号打 connecting（preserveExisting=true）；
+  // 4) 输出结构化审计日志。
   const previousAccounts = collectConfiguredAccountIdsByPlatform(
     params.previousConfig,
   );
@@ -4662,7 +4714,9 @@ async function reconcileRuntimeStateForConfigDelta(params: {
       clearPlatformStatuses(platform);
     } else {
       prunePlatformStatusesByAccounts(platform, nextIds, params.nextConfig);
-      markRuntimeAccountsConnecting(platform, added);
+      markRuntimeAccountsConnecting(platform, added, "config_delta_added", {
+        preserveExisting: true,
+      });
     }
 
     for (const accountId of added) {
@@ -5129,6 +5183,7 @@ function normalizeRuntimePlatform(input: unknown): RuntimePlatform | null {
 }
 
 function normalizeRuntimeLinkStatus(input: unknown): RuntimeBotStatus["link_status"] | null {
+  // status sink 入站时的状态白名单解析；未知值直接忽略。
   const raw = String(input || "")
     .trim()
     .toLowerCase();
@@ -5148,6 +5203,8 @@ function resolveLinkStatusFromSinkPayload(
   payload: RuntimeStatusSinkPayload,
   previous: RuntimeBotStatus | undefined,
 ): RuntimeBotStatus["link_status"] | null {
+  // sink 状态决议顺序：
+  // explicit link_status > connected 布尔 > running=false > previous.link_status。
   const explicit = normalizeRuntimeLinkStatus(payload.link_status);
   if (explicit) return explicit;
   if (payload.connected === true) return "connected";
@@ -5157,11 +5214,16 @@ function resolveLinkStatusFromSinkPayload(
 }
 
 function applyRuntimeStatusSinkPayload(payload: RuntimeStatusSinkPayload): void {
+  // status sink 是“外部状态事件入站”通道：
+  // 1) 先做账号合法性与配置态校验；
+  // 2) 再推导 link_status/restart_pending/running；
+  // 3) 最后统一走 upsertRuntimeStatus 写入状态机。
   const platform = normalizeRuntimePlatform(payload.platform);
   const botAccountId = String(payload.bot_account_id || "").trim();
   if (!platform || !botAccountId) return;
   const normalizedAccountId = normalizeRuntimeAccountId(platform, botAccountId);
   if (!isConfiguredRuntimeAccount(platform, normalizedAccountId || botAccountId)) {
+    // 未配置账号直接丢弃，避免历史脏事件或删除后迟到事件污染状态面板。
     logRuntimeStatusDebug(
       `status sink ignored: unconfigured account platform=${platform} account=${normalizedAccountId || botAccountId}`,
     );
@@ -5177,6 +5239,7 @@ function applyRuntimeStatusSinkPayload(payload: RuntimeStatusSinkPayload): void
     statusSourceRaw === "manual" || statusSourceRaw === "probe" || statusSourceRaw === "event"
       ? (statusSourceRaw as RuntimeBotStatus["status_source"])
       : "event";
+  // restart_pending / running 都由统一推导函数收敛，避免多处规则分叉。
   const nextRestartPending = resolveRuntimeRestartPendingForUpdate({
     previous,
     hintedRestartPending:
@@ -5203,6 +5266,7 @@ function applyRuntimeStatusSinkPayload(payload: RuntimeStatusSinkPayload): void
   });
 
   if (statusSource === "event") {
+    // 只有 event 来源才更新 event liveness 真源，probe/manual 不写这条链路。
     upsertRuntimeEventLiveness({
       platform,
       bot_account_id: normalizedAccountId || botAccountId,
@@ -5348,7 +5412,7 @@ async function invokeGatewayMethodByChannel(args: {
 function parseOptionalBoolFlag(input: unknown): boolean | null {
   // 支持多种布尔表达，无法识别时返回 null 交给上层兜底。
   if (input == null) return null;
-  const normalized = String(input || "")
+  const normalized = String(input)
     .trim()
     .toLowerCase();
   if (!normalized) return null;
@@ -5592,7 +5656,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                 upsertRuntimeProbe({
                   platform: "dingtalk",
                   bot_account_id: accountId,
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                   ok,
                   error,
                   result: (probeResult as Record<string, unknown>) || null,
@@ -5627,7 +5691,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                     runtimeHints.last_run_activity_at || probeAt,
                   mode: runtimeHints.mode || previous?.mode || null,
                   status_source: "probe",
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                 });
               } catch (err) {
                 const probeAt = nowIso();
@@ -5638,7 +5702,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                 upsertRuntimeProbe({
                   platform: "dingtalk",
                   bot_account_id: accountId,
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                   ok: false,
                   error: probeError,
                   result: null,
@@ -5662,7 +5726,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                   last_run_activity_at: probeAt,
                   mode: previous?.mode || null,
                   status_source: "probe",
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                 });
               }
             },
@@ -5725,7 +5789,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                 upsertRuntimeProbe({
                   platform: "dingtalk",
                   bot_account_id: accountId,
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                   ok,
                   error,
                   result: (probeResult as Record<string, unknown>) || null,
@@ -5764,7 +5828,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                     runtimeHints.last_run_activity_at || probeAt,
                   mode: runtimeHints.mode || previous?.mode || null,
                   status_source: "probe",
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                 });
               } catch (err) {
                 const probeAt = nowIso();
@@ -5775,7 +5839,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                 upsertRuntimeProbe({
                   platform: "dingtalk",
                   bot_account_id: accountId,
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                   ok: false,
                   error: probeError,
                   result: null,
@@ -5799,7 +5863,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                   last_run_activity_at: probeAt,
                   mode: previous?.mode || null,
                   status_source: "probe",
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                 });
               }
             },
@@ -5913,7 +5977,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                 upsertRuntimeProbe({
                   platform: "feishu",
                   bot_account_id: accountId,
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                   ok,
                   error: nextError,
                   result: (probeResult as Record<string, unknown>) || null,
@@ -5949,7 +6013,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                     runtimeHints.last_run_activity_at || probeAt,
                   mode: runtimeHints.mode || previous?.mode || null,
                   status_source: "probe",
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                 });
               } catch (err) {
                 const probeAt = nowIso();
@@ -5957,7 +6021,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                 upsertRuntimeProbe({
                   platform: "feishu",
                   bot_account_id: accountId,
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                   ok: false,
                   error: probeError || null,
                   result: null,
@@ -5985,7 +6049,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                   last_run_activity_at: probeAt,
                   mode: previous?.mode || null,
                   status_source: "probe",
-                  last_probe_at: probeAt,
+                  last_probe_at: toChina8Iso(probeAt),
                 });
               }
             },
@@ -6095,7 +6159,7 @@ async function runFullProbeAndRefreshStatuses(params: {
             upsertRuntimeProbe({
               platform: "weixin",
               bot_account_id: accountId,
-              last_probe_at: probeAt,
+              last_probe_at: toChina8Iso(probeAt),
               ok,
               error,
               result: (probeResult as Record<string, unknown>) || null,
@@ -6130,7 +6194,7 @@ async function runFullProbeAndRefreshStatuses(params: {
                 runtimeHints.last_run_activity_at || probeAt,
               mode: runtimeHints.mode || previous?.mode || null,
               status_source: "probe",
-              last_probe_at: probeAt,
+              last_probe_at: toChina8Iso(probeAt),
             });
           } catch (err) {
             const probeAt = nowIso();
@@ -6141,7 +6205,7 @@ async function runFullProbeAndRefreshStatuses(params: {
             upsertRuntimeProbe({
               platform: "weixin",
               bot_account_id: accountId,
-              last_probe_at: probeAt,
+              last_probe_at: toChina8Iso(probeAt),
               ok: false,
               error: probeError,
               result: null,
@@ -6165,7 +6229,7 @@ async function runFullProbeAndRefreshStatuses(params: {
               last_run_activity_at: probeAt,
               mode: previous?.mode || null,
               status_source: "probe",
-              last_probe_at: probeAt,
+              last_probe_at: toChina8Iso(probeAt),
             });
           }
         },
@@ -6226,7 +6290,7 @@ async function probeAndRefreshStatuses(
   }
 
   const startedAt = Date.now();
-  lastProbeStartedAt = new Date(startedAt).toISOString();
+  lastProbeStartedAt = toChina8Iso(new Date(startedAt).toISOString());
 
   const sweepTimeouts = resolveProbeTimeoutsFromRequest(
     options.timeoutMs == null ? undefined : Number(options.timeoutMs),
@@ -6242,7 +6306,7 @@ async function probeAndRefreshStatuses(
     });
   })().finally(() => {
     const finishedAt = Date.now();
-    lastProbeFinishedAt = new Date(finishedAt).toISOString();
+    lastProbeFinishedAt = toChina8Iso(new Date(finishedAt).toISOString());
     lastProbeDurationMs = Math.max(0, finishedAt - startedAt);
     probeInFlight = null;
     probeInFlightMeta = null;
@@ -6643,7 +6707,7 @@ async function runRuntimeHealthGuardCycle(): Promise<void> {
   }
 
   const startedAtMs = Date.now();
-  runtimeHealthGuardLastStartedAt = new Date(startedAtMs).toISOString();
+  runtimeHealthGuardLastStartedAt = toChina8Iso(new Date(startedAtMs).toISOString());
 
   try {
     await probeAndRefreshStatuses({ reason: "health_guard" });
@@ -6710,7 +6774,7 @@ async function runRuntimeHealthGuardCycle(): Promise<void> {
     }
   } finally {
     const finishedAtMs = Date.now();
-    runtimeHealthGuardLastFinishedAt = new Date(finishedAtMs).toISOString();
+    runtimeHealthGuardLastFinishedAt = toChina8Iso(new Date(finishedAtMs).toISOString());
     runtimeHealthGuardLastDurationMs = Math.max(0, finishedAtMs - startedAtMs);
   }
 }
@@ -7447,7 +7511,7 @@ async function startInternalApiServer(): Promise<void> {
         JSON.stringify({
           ok: true,
           runtime_instance_id: runtimeInstanceId,
-          generated_at: nowIso(),
+    generated_at: toChina8Iso(nowIso()),
           limit: clampedLimit,
           ...runtimeLogs,
         }),
@@ -7895,6 +7959,19 @@ async function startInternalApiServer(): Promise<void> {
             ? body.markConnecting
             : body.mark_connecting;
         const markConnecting = parseBoolFlag(markConnectingRaw, true);
+        const reconcileRuntimeStateRaw =
+          body.reconcile_runtime_state === undefined
+            ? body.reconcileRuntimeState
+            : body.reconcile_runtime_state;
+        const reconcileRuntimeState = parseBoolFlag(
+          reconcileRuntimeStateRaw,
+          !markConnecting,
+        );
+        const probeAfterApplyRaw =
+          body.probe_after_apply === undefined
+            ? body.probeAfterApply
+            : body.probe_after_apply;
+        const probeAfterApply = parseBoolFlag(probeAfterApplyRaw, true);
         const requestedVersion = String(body.version || "").trim();
         if (!config || typeof config !== "object") {
           res.writeHead(400, { "Content-Type": "application/json" });
@@ -7971,14 +8048,16 @@ async function startInternalApiServer(): Promise<void> {
             normalizedResult.normalized,
             "config_apply_mark_connecting",
           );
-        } else {
+        } else if (reconcileRuntimeState) {
           await reconcileRuntimeStateForConfigDelta({
             previousConfig,
             nextConfig: normalizedResult.normalized,
             trigger: "config_apply",
           });
         }
-        await probeAndRefreshStatuses({ force: true, reason: "config_apply" });
+        if (probeAfterApply) {
+          await probeAndRefreshStatuses({ force: true, reason: "config_apply" });
+        }
 
         res.writeHead(200, { "Content-Type": "application/json" });
         res.end(
@@ -7987,6 +8066,8 @@ async function startInternalApiServer(): Promise<void> {
             status: "applied",
             persisted: persist,
             mark_connecting: markConnecting,
+            reconcile_runtime_state: reconcileRuntimeState,
+            probe_after_apply: probeAfterApply,
             configPath: loadedConfigPathForRuntime,
             version: configVersionHash || "unknown",
           }),

package/bridges/runtime/bot-runtime-registry.ts

@@ -19,12 +19,14 @@ export type RuntimeBotStatus = {
 };
 
 export class BotRuntimeRegistry {
+  // 账号级运行态内存表：key=platform:bot_account_id。
   private readonly store = new Map<string, RuntimeBotStatus>();
 
   private keyOf(
     platform: RuntimeBotStatus["platform"],
     accountId: string,
   ): string {
+    // 单账号状态唯一键。
     return `${platform}:${accountId}`;
   }
 
@@ -33,6 +35,7 @@ export class BotRuntimeRegistry {
   }
 
   upsert(entry: RuntimeBotStatus): void {
+    // 合并更新：未传字段继承旧值，便于多来源状态渐进补齐。
     const key = this.keyOf(entry.platform, entry.bot_account_id);
     const prev = this.store.get(key);
     this.store.set(key, { ...(prev || {}), ...entry });
@@ -50,6 +53,7 @@ export class BotRuntimeRegistry {
     degraded: number;
     disconnected: number;
   } {
+    // 汇总用于外部状态面板统计，不改写任何账号状态。
     const summary = {
       total: 0,
       connected: 0,

package/bridges/runtime/runtime-health-policy.ts

@@ -1,5 +1,6 @@
 export type RuntimePlatform = "dingtalk" | "feishu" | "weixin";
 
+// 运行态主状态枚举（来自 Node 状态机 runtime.link_status）。
 export type RuntimeLinkStatus =
   | "connecting"
   | "connected"
@@ -9,6 +10,7 @@ export type RuntimeLinkStatus =
 
 export type RuntimeStatusSource = "event" | "probe" | "manual" | null | undefined;
 
+// health.reason 是“健康判定层”的语义，不等价于 link_status。
 export type RuntimeComposedHealthReason =
   | "healthy"
   | "unmanaged"
@@ -53,6 +55,7 @@ export type RuntimeStatusLike = {
   last_event_at?: string | number | null;
 };
 
+// RuntimeComposedBotLike: 统一的“状态 + 健康”输入结构，供 readiness/guard 使用。
 export type RuntimeComposedBotLike = {
   platform: RuntimePlatform;
   bot_account_id: string;
@@ -63,6 +66,7 @@ export type RuntimeComposedBotLike = {
   };
 };
 
+// display 快照是最终 UI 文案/颜色输出，不反向驱动状态机。
 export type RuntimeDisplaySnapshot = {
   status: RuntimeComposedDisplayStatus;
   reason: string;
@@ -146,13 +150,17 @@ const runtimeStartupFallbackEvents = new Set([
   "config_loaded",
 ]);
 
+// webhook 模式下没有持续 socket 心跳，不做 stale_socket 判定。
 const runtimeSkipStaleHeartbeatModes = new Set(["webhook"]);
+// busy 状态长期无活动则视为 stuck。
 const runtimeBusyActivityStaleMsDefault = 25 * 60_000;
+// 重连次数达到阈值后，健康守护可按 gave_up 分类。
 const runtimeGaveUpReconnectThreshold = 10;
 
 export function isExplicitReportedRuntimeFailure(
   status: Pick<RuntimeStatusLike, "link_status" | "status_source">,
 ): boolean {
+  // 只有 event/probe 上报的失败态被视为“显式失败证据”。
   return (
     (status.status_source === "probe" || status.status_source === "event") &&
     (status.link_status === "error" ||
@@ -168,6 +176,8 @@ export function shouldApplyReportedFailureOverManualConnecting(params: {
     | undefined;
   next: Pick<RuntimeStatusLike, "link_status" | "status_source">;
 }): boolean {
+  // manual/connecting 是控制面过渡态；
+  // 若后续出现 event/probe 明确失败，应允许失败覆盖 manual connecting。
   const previous = params.previous;
   const previousSource = previous?.status_source || "probe";
   return (
@@ -178,6 +188,7 @@ export function shouldApplyReportedFailureOverManualConnecting(params: {
 }
 
 function parseIsoTimeMs(value: string | null | undefined): number | null {
+  // ISO 时间文本解析；解析失败统一返回 null。
   const text = String(value || "").trim();
   if (!text) return null;
   const ms = Date.parse(text);
@@ -186,6 +197,7 @@ function parseIsoTimeMs(value: string | null | undefined): number | null {
 }
 
 function parseTimeMs(value: unknown): number | null {
+  // 通用时间解析：支持秒/毫秒数字与文本，统一返回毫秒时间戳。
   if (typeof value === "number" && Number.isFinite(value)) {
     const normalized = value > 1_000_000_000_000 ? value : value * 1000;
     return Math.max(0, Math.trunc(normalized));
@@ -201,6 +213,7 @@ function parseTimeMs(value: unknown): number | null {
 }
 
 function readNonNegativeInt(value: unknown, fallback = 0): number {
+  // 计数字段容错并裁剪到非负整数。
   const numeric = typeof value === "number" ? value : Number(value);
   if (!Number.isFinite(numeric)) return fallback;
   return Math.max(0, Math.trunc(numeric));
@@ -221,6 +234,9 @@ export function evaluateRuntimeHealth(params: {
   reason: RuntimeComposedHealthReason;
   evaluated_at: string;
 } {
+  // 健康判定优先级：
+  // unmanaged > not_running > busy/stuck > explicit failure > startup_grace
+  // > stale_socket > healthy。
   const {
     status,
     eventAtMs = null,
@@ -336,6 +352,7 @@ export function evaluateRuntimeHealth(params: {
 function normalizeRuntimeDisplayStatusFromText(
   value: unknown,
 ): RuntimeComposedDisplayStatus | null {
+  // 宽松文本到显示状态映射，兼容历史 status 文本。
   const text = String(value || "")
     .trim()
     .toLowerCase();
@@ -357,6 +374,7 @@ function resolveRuntimeDisplayDefaults(status: RuntimeComposedDisplayStatus): {
   color: RuntimeComposedDisplayColor;
   hint: string | null;
 } {
+  // 显示状态默认文案，不承担状态判定职责。
   if (status === "online") {
     return { label: "在线", color: "success", hint: null };
   }
@@ -369,9 +387,9 @@ function resolveRuntimeDisplayDefaults(status: RuntimeComposedDisplayStatus): {
   }
   if (status === "connecting") {
     return {
-      label: "连接中",
+      label: "状态确认中",
       color: "processing",
-      hint: "结构化状态显示机器人处于启动/连接阶段。",
+      hint: "正在同步并确认机器人在线状态。",
     };
   }
   if (status === "reconnecting") {
@@ -403,6 +421,8 @@ export function resolveRuntimeDisplayState(params: {
   healthReason: RuntimeComposedHealthReason;
   evaluatedAt: string;
 }): RuntimeDisplaySnapshot {
+  // 展示态判定优先级：
+  // restart_pending 分支 > health.reason 分支 > status 文本分支 > event fallback > unknown。
   const statusText = String(params.status.link_status || "")
     .trim()
     .toLowerCase();
@@ -433,6 +453,7 @@ export function resolveRuntimeDisplayState(params: {
 
   const linkConnected = params.status.link_status === "connected";
   if (params.status.restart_pending === true) {
+    // 重启生命周期下，优先输出“重连中/失败中”语义，避免过早显示在线。
     if (statusText === "error") {
       return build("error", "status:error", "status", {
         hint: "重启/启动流程中探测失败，请检查凭证与网络后重试。",
@@ -517,7 +538,8 @@ export function resolveRuntimeDisplayState(params: {
       });
     }
     return build("connecting", "health:startup_grace", "health", {
-      hint: "启动宽限期内先显示连接中，收到连接成功事件后再切换在线。",
+      label: "状态确认中",
+      hint: "正在同步并确认机器人在线状态。",
     });
   }
 
@@ -527,7 +549,10 @@ export function resolveRuntimeDisplayState(params: {
   }
 
   if (!statusText && runtimeStartupFallbackEvents.has(lastEvent)) {
-    return build("connecting", `event:${lastEvent}`, "event_fallback");
+    // 无 status 文本时，启动事件作为连接中兜底提示。
+    return build("connecting", `event:${lastEvent}`, "event_fallback", {
+      label: "状态确认中",
+    });
   }
 
   if (params.healthReason === "healthy") {
@@ -538,6 +563,7 @@ export function resolveRuntimeDisplayState(params: {
 }
 
 export function isManualStopState(item: RuntimeComposedBotLike): boolean {
+  // 显式人工停机态：manual + disconnected。
   return (
     item.runtime.status_source === "manual" &&
     item.runtime.link_status === "disconnected"
@@ -545,12 +571,14 @@ export function isManualStopState(item: RuntimeComposedBotLike): boolean {
 }
 
 function readRuntimeReconnectCount(item: RuntimeComposedBotLike): number {
+  // reconnect_count 统一按非负整数读取，避免 NaN/负值影响阈值判断。
   return readNonNegativeInt(item.runtime.reconnect_count);
 }
 
 export function resolveRuntimeHealthGuardTriggerReason(
   item: RuntimeComposedBotLike,
 ): RuntimeHealthGuardTriggerReason | null {
+  // 健康守护触发原因仅用于“是否自动恢复”决策，不直接改主状态。
   const reconnectCount = readRuntimeReconnectCount(item);
   const isRestartPending = item.runtime.restart_pending === true;
 
@@ -582,6 +610,10 @@ export function buildRuntimeReadinessSnapshot(params: {
   runtimeState?: "running" | "restarting";
   runtimeReady?: boolean;
 }): RuntimeReadinessSnapshot {
+  // readiness 只读聚合：
+  // 1) 把账号划分为 hard/soft/ignored/pending；
+  // 2) 计算 ready/pending/pending_reason；
+  // 3) 输出可诊断 summary 与账号明细。
   const {
     botsComposed,
     generatedAt,
@@ -612,6 +644,7 @@ export function buildRuntimeReadinessSnapshot(params: {
       reconnect_count: reconnectCount,
     };
 
+    // pending 维度是“尚在收敛”语义，不等价于 unhealthy。
     const isPendingByHealth = item.health.reason === "startup_grace";
     const isPendingByStatus = item.runtime.link_status === "connecting";
     const isPendingByRestart = isRestartPending;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ylib-syim",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "description": "多 IM / 多 Agent 的会话路由与上下文管理（支持 /new）",
   "type": "module",
   "exports": {

package/scripts/dingtalk-stdio-bridge.ts

@@ -809,7 +809,13 @@ async function startConfiguredAccounts(): Promise<void> {
   }
 
   let startedCount = 0;
-  for (const accountId of accountIds) {
+  // 有界并发启动：避免账号数多时串行等待导致首次启动时间过长。
+  // 并发数由环境变量 BRIDGE_START_CONCURRENCY_DINGTALK 控制，默认 3。
+  const concurrency = parseInt(process.env.BRIDGE_START_CONCURRENCY_DINGTALK || "3", 10);
+  const queue = [...accountIds];
+  const running = new Map<string, Promise<void>>();
+
+  async function startOne(accountId: string): Promise<void> {
     try {
       await startSingleAccount(accountId, "startup");
       startedCount++;
@@ -821,6 +827,19 @@ async function startConfiguredAccounts(): Promise<void> {
       emitRuntimeEvent(accountId, "error", detail);
     }
   }
+
+  while (queue.length > 0 || running.size > 0) {
+    while (running.size < concurrency && queue.length > 0) {
+      const accountId = queue.shift()!;
+      const task = startOne(accountId).finally(() => {
+        running.delete(accountId);
+      });
+      running.set(accountId, task);
+    }
+    if (running.size > 0) {
+      await Promise.race(running.values());
+    }
+  }
   console.log(
     `[dingtalk-stdio-bridge] started accounts=${startedCount} total=${accountIds.length}`,
   );

package/scripts/lark-stdio-bridge.ts

@@ -897,7 +897,13 @@ async function startConfiguredAccounts(): Promise<void> {
   }
 
   let startedCount = 0;
-  for (const accountId of accountIds) {
+  // 有界并发启动：避免账号数多时串行等待导致首次启动时间过长。
+  // 并发数由环境变量 BRIDGE_START_CONCURRENCY_LARK 控制，默认 3。
+  const concurrency = parseInt(process.env.BRIDGE_START_CONCURRENCY_LARK || "3", 10);
+  const queue = [...accountIds];
+  const running = new Map<string, Promise<void>>();
+
+  async function startOne(accountId: string): Promise<void> {
     try {
       await startSingleAccount(accountId, "startup");
       startedCount++;
@@ -909,6 +915,19 @@ async function startConfiguredAccounts(): Promise<void> {
       emitRuntimeEvent(accountId, "error", detail);
     }
   }
+
+  while (queue.length > 0 || running.size > 0) {
+    while (running.size < concurrency && queue.length > 0) {
+      const accountId = queue.shift()!;
+      const task = startOne(accountId).finally(() => {
+        running.delete(accountId);
+      });
+      running.set(accountId, task);
+    }
+    if (running.size > 0) {
+      await Promise.race(running.values());
+    }
+  }
   console.log(
     `[lark-stdio-bridge] started accounts=${startedCount} total=${accountIds.length}`,
   );

package/scripts/weixin-stdio-bridge.ts

@@ -818,7 +818,13 @@ async function startConfiguredAccounts(): Promise<void> {
   }
 
   let startedCount = 0;
-  for (const accountId of accountIds) {
+  // 有界并发启动：避免账号数多时串行等待导致首次启动时间过长。
+  // 并发数由环境变量 BRIDGE_START_CONCURRENCY_WEIXIN 控制，默认 2。
+  const concurrency = parseInt(process.env.BRIDGE_START_CONCURRENCY_WEIXIN || "2", 10);
+  const queue = [...accountIds];
+  const running = new Map<string, Promise<void>>();
+
+  async function startOne(accountId: string): Promise<void> {
     try {
       await startSingleAccount(accountId, "startup");
       startedCount++;
@@ -831,6 +837,19 @@ async function startConfiguredAccounts(): Promise<void> {
     }
   }
 
+  while (queue.length > 0 || running.size > 0) {
+    while (running.size < concurrency && queue.length > 0) {
+      const accountId = queue.shift()!;
+      const task = startOne(accountId).finally(() => {
+        running.delete(accountId);
+      });
+      running.set(accountId, task);
+    }
+    if (running.size > 0) {
+      await Promise.race(running.values());
+    }
+  }
+
   console.log(
     `[weixin-stdio-bridge] started accounts=${startedCount} total=${accountIds.length}`,
   );