@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

package/dist/channels/phrases.d.ts

@@ -1,7 +1,8 @@
-/** 组织默认语言（`orgs.settings.locale`）。 */
+/** The language of kernel IM text: the recipient's, else the org's (`orgs.settings.locale`). */
 export type ChannelLocale = "zh" | "en";
 /**
- * 机器人在 IM 里说的固定话术（全部集中在这里，zh / en 同步）：按连接所属组织的默认语言选择。
+ * 机器人在 IM 里说的固定话术（全部集中在这里，zh / en 同步）. Chosen per recipient (run context spec
+ * §3.4): the sender's platform language, else their latest web language, else the org's.
  * 模型回复不经过这里，原样转换为 IM 富文本、不翻译。
  */
 export declare const CHANNEL_PHRASES: {
@@ -10,6 +11,36 @@ export declare const CHANNEL_PHRASES: {
         readonly zh: "已开始新对话";
         readonly en: "Started a new conversation.";
     };
+    /** 私聊 `/env`：列出可用环境（`{list}` 每行一个，当前的带标记）。 */
+    readonly envList: {
+        readonly zh: "你的环境：\n{list}\n发送 /env <名称> 选择下一个新对话使用的环境。";
+        readonly en: "Your environments:\n{list}\nSend /env <name> to choose the one your next new conversation uses.";
+    };
+    /** 私聊 `/env <名称>` 之后（`{name}` 是环境名）。 */
+    readonly envSwitched: {
+        readonly zh: "下一个新对话将使用环境「{name}」，发送 /new 开始。";
+        readonly en: "Your next new conversation will use the environment “{name}”; send /new to start one.";
+    };
+    /** 私聊 `/env <名称>` 没有匹配的可用环境（`{list}` 同 envList）。 */
+    readonly envUnknown: {
+        readonly zh: "没有找到名为「{name}」的环境。你的环境：\n{list}";
+        readonly en: "No environment named “{name}”. Your environments:\n{list}";
+    };
+    /** `/env <name>` names an existing environment that is unavailable now (`{list}` as in envList). */
+    readonly envUnavailable: {
+        readonly zh: "环境「{name}」当前不可用（它的文件由未启用的沙箱提供方保存）。你的环境：\n{list}";
+        readonly en: "The environment “{name}” is unavailable: its files are kept by a sandbox provider that is not active. Your environments:\n{list}";
+    };
+    /** 私聊 `/env` 时此人没有可用环境（部署没有云沙箱）。 */
+    readonly envNone: {
+        readonly zh: "你目前没有可用的环境。";
+        readonly en: "You have no usable environments.";
+    };
+    /** 环境列表里当前 IM 默认环境的标记。 */
+    readonly envCurrent: {
+        readonly zh: "（当前）";
+        readonly en: " (current)";
+    };
     /** 未绑定的人在私聊里发消息：附绑定卡片。 */
     readonly bindPrompt: {
         readonly zh: "请先绑定你的 Capybara 账号，再与我对话。";

package/dist/channels/phrases.js

@@ -1,10 +1,38 @@
 /**
- * 机器人在 IM 里说的固定话术（全部集中在这里，zh / en 同步）：按连接所属组织的默认语言选择。
+ * 机器人在 IM 里说的固定话术（全部集中在这里，zh / en 同步）. Chosen per recipient (run context spec
+ * §3.4): the sender's platform language, else their latest web language, else the org's.
  * 模型回复不经过这里，原样转换为 IM 富文本、不翻译。
  */
 export const CHANNEL_PHRASES = {
     /** 私聊 `/new` 之后。 */
     newConversation: { zh: "已开始新对话", en: "Started a new conversation." },
+    /** 私聊 `/env`：列出可用环境（`{list}` 每行一个，当前的带标记）。 */
+    envList: {
+        zh: "你的环境：\n{list}\n发送 /env <名称> 选择下一个新对话使用的环境。",
+        en: "Your environments:\n{list}\nSend /env <name> to choose the one your next new conversation uses.",
+    },
+    /** 私聊 `/env <名称>` 之后（`{name}` 是环境名）。 */
+    envSwitched: {
+        zh: "下一个新对话将使用环境「{name}」，发送 /new 开始。",
+        en: "Your next new conversation will use the environment \u201c{name}\u201d; send /new to start one.",
+    },
+    /** 私聊 `/env <名称>` 没有匹配的可用环境（`{list}` 同 envList）。 */
+    envUnknown: {
+        zh: "没有找到名为「{name}」的环境。你的环境：\n{list}",
+        en: "No environment named \u201c{name}\u201d. Your environments:\n{list}",
+    },
+    /** `/env <name>` names an existing environment that is unavailable now (`{list}` as in envList). */
+    envUnavailable: {
+        zh: "环境「{name}」当前不可用（它的文件由未启用的沙箱提供方保存）。你的环境：\n{list}",
+        en: "The environment \u201c{name}\u201d is unavailable: its files are kept by a sandbox provider that is not active. Your environments:\n{list}",
+    },
+    /** 私聊 `/env` 时此人没有可用环境（部署没有云沙箱）。 */
+    envNone: {
+        zh: "你目前没有可用的环境。",
+        en: "You have no usable environments.",
+    },
+    /** 环境列表里当前 IM 默认环境的标记。 */
+    envCurrent: { zh: "（当前）", en: " (current)" },
     /** 未绑定的人在私聊里发消息：附绑定卡片。 */
     bindPrompt: {
         zh: "请先绑定你的 Capybara 账号，再与我对话。",

package/dist/channels/supervisor.d.ts

@@ -1,8 +1,15 @@
-import type { ExtensionContext, InboundEvent, Logger } from "@capybara-hq/plugin-sdk";
+import { type ExtensionContext, type Logger } from "@capybara-hq/plugin-sdk";
 import type { Redis } from "ioredis";
 import type { KernelConfig } from "../config/schema.js";
-import type { KernelDb } from "../db/kernel-schema.js";
-import { type ChannelConnections } from "./connections.service.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { ExtensionRegistry } from "../extensions/registry.js";
+import { ReplicaStatusStore } from "../extensions/sources.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { type KernelLogger } from "../log.js";
+import { ChannelConnections } from "./connections.service.js";
+import { ChannelInbound } from "./inbound.js";
 /** 长连接租约键（内核锁）：值为持有方的随机 token。 */
 export declare const channelLeaseKey: (connectionId: string) => string;
 /**
@@ -32,50 +39,43 @@ export declare const gatewayMissingWarnedKey = "capk:gateway-missing-warned";
 export declare function shareTarget(runnable: number, live: number, slack: number, rank?: number): number;
 /** Live heartbeat members of each plugin (Redis server clock). */
 export declare function liveGateways(redis: Redis, plugins: string[], ttlMs: number): Promise<Map<string, string[]>>;
-export interface ChannelSupervisorDeps {
-    db: KernelDb;
-    redis: Redis;
-    bus: ExtensionContext["bus"];
-    connections: Pick<ChannelConnections, "runtime">;
-    /** 本进程已加载、提供 `channel@1` 的插件名（内核传 `host.list("channel")`）。 */
-    localPlugins: () => string[];
-    onEvent(connectionId: string, e: InboundEvent): Promise<void>;
-    config: () => Pick<KernelConfig, "channels">;
-    log: Pick<Logger, "warn" | "error">;
-    /**
-     * This process's replica id (`newReplicaId()` in kernel.ts), the member of the gateway heartbeat
-     * ZSET. Not `http.replicaId`, which is optional and may repeat across replicas.
-     */
-    replicaId: string;
-    /** Called at the start of every scan round (`claimOnly` for handoff nudges); for tests / metrics. */
-    onScan?: (claimOnly: boolean) => void;
-}
 /**
- * 渠道长连接选主（runs only on the gateway role）。每个副本两个各自独立的循环，周期都是 `channels.scanIntervalMs`（默认 10s）：
- * - 续租循环：为本进程持有的连接续租（`capk:channel-lease:<id>`，TTL `channels.leaseTtlMs` 默认 30s）。
- *   它不做任何可能慢的事（不等交还、不查库），一个插件迟迟不退出不会拖慢其他连接的续租。
+ * 渠道长连接选主（runs only on the gateway role: a provider of `GatewayModule`, started and stopped by
+ * `KernelLifecycle` through `GatewayRole` after the extension load）。每个副本两个各自独立的循环，周期都是 `channels.scanIntervalMs`（默认 10s）：
+ * - 心跳循环：写本副本的 gateway 心跳，再为本进程持有的连接续一次租。它不做任何可能慢的事（不等交还、不查库），
+ *   一个插件迟迟不退出不会拖慢其他连接的续租。
  * - 扫描循环：复核持有的连接仍为 active、未删除且插件在该组织启用（不满足就交还，交还不阻塞本轮），
- *   再扫描无人持有的这类连接，`SET NX PX` 取到租约的副本调用插件 `connect`（传 `signal`）。
- * 续租失败（租约已丢）→ 立即中止，不释放（已不是自己的）；Redis 出错时，自上次续租成功起满 `TTL - 扫描周期`
- * 仍续不上就按丢失处理（赶在租约可能被别的副本拿走之前断开）。连接被停用 / 删除 / 改配置（内核 bus `channel.changed`，
- * 或扫描时复核发现）→ 中止、等 `connect` 返回后释放租约，下一轮任一副本按新配置重连；取得租约到 `connect` 开始之间
+ *   再扫描无人持有的这类连接，取到租约（`LockService.hold`）的副本调用插件 `connect`（传 `signal`）。
+ * The lease `capk:channel-lease:<id>` (value: this replica's random token, TTL
+ * `channels.leaseTtlMs`, default 30 s) is renewed by `LockService` (every TTL/3, plus once in the
+ * heartbeat loop). A lost lease (overwritten or expired, or no successful renewal by the renewal
+ * deadline) aborts at once and is not released (it is no longer ours).
+ * 连接被停用 / 删除 / 改配置（内核 bus `channel.changed`，或扫描时复核发现）→ 中止、等 `connect` 返回后释放租约，下一轮任一副本按新配置重连；取得租约到 `connect` 开始之间
  * 收到的重连广播会被记下，开始后立即交还。
  * `connect` 抛错或提前返回 → 记 `last_error`，在 Redis 写退避标记（指数退避，上限 5 分钟），释放租约后由任一副本重试。
- * Fair share (E11-B): the renewal loop also writes this replica's heartbeat into `capk:gateway-replicas`;
+ * Fair share (E11-B): the heartbeat loop writes this replica's heartbeat into `capk:gateway-replicas`;
  * each scan computes this replica's target from the runnable count and the live replicas
  * (`shareTarget`), stops claiming at the target and, when above it, gives back one connection per
  * round (the most recently connected) with a handoff marker. Exactly one holder per connection is
  * still guaranteed by the lease alone; the share only decides who claims.
- * 停机时中止全部长连接并释放租约，并等进行中的 `onEvent`（入队）结束。持有的长连接、租约 token 与定时器都是「本进程持有的资源」，
+ * 停机时中止全部长连接并释放租约，并等进行中的 `onEvent`（入队）结束。持有的长连接、租约与定时器都是「本进程持有的资源」，
  * 跨副本的状态（租约、退避、失败计数）都在 Redis。
  */
 export declare class ChannelSupervisor {
-    private readonly deps;
+    private readonly db;
+    private readonly redis;
+    private readonly bus;
+    private readonly locks;
+    private readonly connections;
+    /** The channel extensions loaded in this process (`channel@1` providers). */
+    private readonly registry;
+    /** Events from a plugin's `connect` (dedupe and enqueue; ack after it resolves). */
+    private readonly inbound;
+    private readonly config;
+    private readonly log;
     private readonly held;
     /** 已取得租约、正在读配置准备 `connect` 的连接；值为期间是否收到了重连广播。 */
     private readonly connecting;
-    /** 正在交还（已中止、等 `connect` 返回）的连接 → 租约 token：等待期间照常续租，交还完成才释放。 */
-    private readonly settling;
     /** 进行中的交还（`stop()` 要等它们全部结束）。 */
     private readonly releasing;
     /** 进行中的 `onEvent`（去重 + 入队，很快）：`stop()` 等它们结束，插件才不会在内核关闭队列之后才拿到结果。 */
@@ -90,13 +90,31 @@ export declare class ChannelSupervisor {
     private heartbeated;
     /** A claim-only scan is queued and has not started yet: further nudges until then are dropped. */
     private claimQueued;
-    constructor(deps: ChannelSupervisorDeps);
+    /**
+     * This process's replica id (`ReplicaStatusStore.replicaId`), the member of the gateway heartbeat
+     * ZSET. Not `http.replicaId`, which is optional and may repeat across replicas.
+     */
+    readonly replicaId: string;
+    /** Called at the start of every scan round (`claimOnly` for handoff nudges); for tests / metrics. */
+    onScan: ((claimOnly: boolean) => void) | undefined;
+    constructor(db: KernelDb, redis: Redis, bus: ExtensionContext["bus"], locks: Pick<LockService, "hold">, connections: Pick<ChannelConnections, "runtime">, 
+    /** The channel extensions loaded in this process (`channel@1` providers). */
+    registry: Pick<ExtensionRegistry, "list">, 
+    /** Events from a plugin's `connect` (dedupe and enqueue; ack after it resolves). */
+    inbound: Pick<ChannelInbound, "onEvent">, config: Pick<KernelConfigService, "get">, log: Pick<Logger, "warn" | "error">, replicaStatus: Pick<ReplicaStatusStore, "replicaId">);
+    /** 本进程已加载、提供 `channel@1` 的插件名。 */
+    private localPlugins;
     start(): Promise<void>;
     /** Runs `fn` after any scan in progress. */
     private exclusive;
     /** 周期循环：上一轮结束后隔 `scanIntervalMs` 再跑下一轮；首轮立即执行。 */
     private loop;
-    private renewAll;
+    /**
+     * One heartbeat round: the heartbeat first, then one renewal of every lease held (on top of
+     * `LockService`'s own), so a crashed replica's heartbeat goes stale no later than its leases
+     * expire and the survivors' share already excludes it when those connections free up.
+     */
+    private heartbeatRound;
     /**
      * Writes this replica's heartbeat into the ZSET of every channel plugin loaded here (trimming
      * members older than one TTL; the keys expire too) and leaves the ZSETs of plugins no longer
@@ -117,6 +135,7 @@ export declare class ChannelSupervisor {
     private handOff;
     /** After-release callback: tells the other replicas a connection of `plugin` is free to claim. */
     private nudge;
+    /** A renewal succeeded: one lease period connected in a row clears the failure count. */
     private afterRenew;
     /**
      * 可以持有的连接：active、未删除、所属组织未删除、插件在该组织启用（组织停用插件 / 删除组织时持有方据此断开），
@@ -140,13 +159,15 @@ export declare class ChannelSupervisor {
     private track;
     /** 记录失败：`last_error`、连续失败计数与退避标记（都跨副本可见）。 */
     private failed;
-    /** 租约已丢：中止，不释放（已不是自己的）。 */
+    /** 租约已丢：中止，不释放（已不是自己的；续租已停）。 */
     private drop;
     /** 后台交还，记入 `releasing` 供 `stop()` 等待；`after` runs once the lease is released. */
     private releaseInBackground;
-    /** 主动交还：中止，等 `connect` 返回（至多 SETTLE_MS）后释放租约；超时则让租约自然过期，避免两边同时在线。 */
+    /**
+     * 主动交还：中止，等 `connect` 返回（至多 SETTLE_MS，期间租约照常续着，不会在别的副本眼里提前过期）后释放租约；
+     * 超时则停止续租、让租约自然过期，避免两边同时在线。
+     */
     private release;
-    private releaseLease;
     /**
      * 本进程的插件实例变了（撤销、替换为新实例；内核接 `host.onChange`，C17）：交还该插件持有的全部长连接
      * （中止旧实例的 `connect`、等它返回后释放租约）。插件仍在本进程（新实例）时，下一轮扫描由任一副本按新实例重新选主；
@@ -156,26 +177,47 @@ export declare class ChannelSupervisor {
     /** 停机：停止扫描，中止全部长连接并释放租约。幂等。 */
     stop(): Promise<void>;
 }
-/** Maintenance job that warns when channel connections need a gateway and none is live (Ruling R1). */
-export declare const GATEWAY_CHECK_JOB = "channel-gateway-check";
-export declare const GATEWAY_CHECK_SCHEDULER_ID = "channel-gateway-check-every";
+export { GATEWAY_CHECK_JOB, GATEWAY_CHECK_SCHEDULER_ID } from "./job-ids.js";
+/** The period of the gateway check (`@LockedCron` every minute). */
 export declare const GATEWAY_CHECK_EVERY_MS = 60000;
 /**
- * Runs on the worker role (maintenance queue), per channel plugin (Ruling R3): when a plugin has
+ * Warns when channel connections need a gateway and none is live (Ruling R1 / R3 / R4):
+ * {@link checkGatewayPresence}, every minute, once across replicas; a worker-role job
+ * (`WorkerModule`), as the maintenance job it replaces was. Silent for one lease TTL after this
+ * worker process built its providers (the gateways' first heartbeats; the old handler's grace also
+ * started at the worker's kernel construction). Replaces the maintenance scheduler
+ * `channel-gateway-check-every` (retired at worker start).
+ */
+export declare class GatewayCheckJob {
+    private readonly db;
+    private readonly redis;
+    private readonly config;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    /** The start of the grace period: when this process built its providers. */
+    private readonly graceFrom;
+    constructor(db: KernelDb, redis: Redis, config: Pick<KernelConfigService, "get">, lockService: LockService, log: KernelLogger);
+    run(): Promise<void>;
+}
+/**
+ * Runs once a minute across replicas ({@link GatewayCheckJob}), per channel plugin (Ruling R3): when a plugin has
  * active connections (not deleted, org not deleted, plugin enabled for the org; long connection or
  * webhook mode, Ruling R4) but no gateway replica with that plugin loaded has a heartbeat newer than
  * one lease TTL (Redis server clock), nobody holds those long connections or answers their webhooks.
  * - Logs one `warn` (naming the plugins) per interval at most across the cluster: a Redis
- *   `SET NX PX` rate limit a little shorter than the job period, so a duplicated job or several
- *   worker replicas do not repeat it while each period still gets its line.
+ *   marker (`LockService.lease`, a `SET NX PX`) a little shorter than the job period, so a
+ *   duplicated job or several replicas do not repeat it while each period still gets its line.
  * - Silent before `graceUntil` (this process's start + one lease TTL), so a fresh cluster does not
  *   warn before the gateways' first heartbeat.
  * Returns whether it warned.
  */
 export declare function checkGatewayPresence(deps: {
-    db: KernelDb;
+    db: KernelSchemaDb;
     redis: Redis;
-    config: () => Pick<KernelConfig, "channels">;
+    locks: Pick<LockService, "lease">;
+    config: {
+        get(): Pick<KernelConfig, "channels">;
+    };
     log: Pick<Logger, "warn">;
     everyMs?: number;
     graceUntil?: number;