@zhin.js/adapter 1.1.0 → 1.1.2

package/lib/endpoint-commands.js

@@ -0,0 +1,385 @@
+/**
+ * createEndpointCommands — 适配器 endpoint 管理命令套件（list / add / remove）。
+ *
+ * 把 QQ 适配器独有的 `qq endpoint` 命令族泛化为任意适配器可复用的套件：
+ *
+ * - `<adapter> endpoint list`：运行中的 endpoints（adapter create 注册的 runtime state）
+ *   + zhin.config.yml 配置里的 `plugins.<adapterKey>.endpoints`。
+ * - `<adapter> endpoint add <name> <key=value...>`：手动录入字段，
+ *   凭据类字段（env: true）值写入 .env（`<ADAPTER>_<NAME>_<FIELD>` 大写键），
+ *   yaml 中保存 `${REF}` 引用；其余字段内联写入。yaml 用 Document 节点级操作保留注释。
+ * - `<adapter> endpoint remove <name>`：从 `plugins.<adapterKey>.endpoints` 移除（重启生效）。
+ * - 权限：实例 config 声明了 master（顶层或 endpoints[i]）时仅 master 可用 add/remove，
+ *   未配置放行（isEndpointOperator）。
+ * - 特殊 add 流程（如 QQ 扫码绑定）经 spec.bindFlow 钩子接管 add 命令。
+ *
+ * 接入步骤（以 telegram 为例）：
+ * 1. plugin.ts setup 里 `context.resources.provide(telegramRuntimeStateToken, createEndpointRuntimeState())`，
+ *    token 由 `defineEndpointRuntimeStateToken('telegram')` 创建。
+ * 2. adapters/telegram.ts create() 里 `context.use(token).endpoints.set(config.name, { name, mode })`。
+ * 3. src 下 `export const telegramEndpointCommands = createEndpointCommands({ adapterKey: 'telegram', ... }, defineCommand)`
+ *    （defineCommand 由调用方从 @zhin.js/command 传入——provider 包之间禁止互相 import，
+ *    见 scripts/check-architecture-layers.mjs，故 defineCommand 走依赖注入）。
+ * 4. commands/endpoint/{list.ts, add/[name:string].ts, remove/[name:string].ts} 分别
+ *    `export default telegramEndpointCommands.list|add|remove`。
+ *
+ * 注意：adapterKey 即实例 key（zhin.config.yml 的 plugins.<key>）；多实例自定义 key 时
+ * 写回目标以 spec.adapterKey 为准（与 QQ 现状一致）。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createToken } from '@zhin.js/plugin-runtime';
+import { isMap, isSeq, parseDocument } from 'yaml';
+// ---------------------------------------------------------------------------
+// 权限：master 判定
+// ---------------------------------------------------------------------------
+/**
+ * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
+ * 仅 master 可执行管理命令；未配置则放行。
+ */
+export function isEndpointOperator(config, input) {
+    const cfg = (config ?? {});
+    const masters = new Set();
+    const collect = (value) => {
+        if (value === undefined || value === null)
+            return;
+        const text = String(value).trim();
+        if (text)
+            masters.add(text);
+    };
+    collect(cfg.master);
+    if (Array.isArray(cfg.endpoints)) {
+        for (const entry of cfg.endpoints) {
+            collect(entry?.master);
+        }
+    }
+    if (masters.size === 0)
+        return true;
+    const sender = String(input?.sender ?? '').trim();
+    return !!sender && masters.has(sender);
+}
+/** add/remove 的拒绝文案（list 只读，不校验）。 */
+export function endpointCommandForbidden(adapterDisplayName) {
+    return `仅 master 可执行 ${adapterDisplayName} endpoint 管理命令`;
+}
+/**
+ * 从命令 input（Runtime Message）提取 $reply；非消息来源（如 Host API 调用）降级为 no-op。
+ */
+export function extractEndpointCommandReply(input) {
+    const reply = input?.$reply;
+    if (typeof reply === 'function') {
+        return (text) => reply.call(input, text);
+    }
+    return async () => undefined;
+}
+export function createEndpointRuntimeState() {
+    return { endpoints: new Map() };
+}
+/** 每个适配器在模块顶层调用一次，创建自己的 runtime state token。 */
+export function defineEndpointRuntimeStateToken(adapterKey) {
+    return createToken(`zhin.${adapterKey}.runtime-state`, `${adapterKey} adapter runtime state (running endpoints)`);
+}
+// ---------------------------------------------------------------------------
+// .env 凭据持久化
+// ---------------------------------------------------------------------------
+/** 项目根：ZHIN_PROJECT_ROOT 优先，缺省 process.cwd()（替代 legacy runtimeCwd） */
+export function resolveProjectRoot() {
+    const envRoot = process.env.ZHIN_PROJECT_ROOT?.trim();
+    return path.resolve(envRoot || process.cwd());
+}
+function envSlug(text) {
+    return text
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[^a-zA-Z0-9_]/g, '_')
+        .toUpperCase();
+}
+/** 派生 endpoint 凭据的 env 键：`${ADAPTER}_${NAME}_${FIELD}`（如 `TELEGRAM_MY_BOT_TOKEN`） */
+export function buildEndpointEnvKey(adapterKey, endpointName, fieldKey) {
+    return `${envSlug(adapterKey)}_${envSlug(endpointName)}_${envSlug(fieldKey)}`;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function upsertEnvLine(content, key, value) {
+    const lineRe = new RegExp(`^${escapeRegExp(key)}\\s*=.*$`, 'm');
+    const newLine = `${key}=${value}`;
+    if (lineRe.test(content)) {
+        return content.replace(lineRe, newLine);
+    }
+    const trimmed = content.replace(/\s*$/, '');
+    if (trimmed.length === 0) {
+        return `${newLine}\n`;
+    }
+    return `${trimmed}\n${newLine}\n`;
+}
+/** 写入或更新 `.env` 中的键值，并同步到当前进程 `process.env` */
+export function persistEndpointEnvValues(values, projectRoot) {
+    const root = projectRoot ?? resolveProjectRoot();
+    const envPath = path.join(root, '.env');
+    let content = fs.existsSync(envPath) ? fs.readFileSync(envPath, 'utf-8') : '';
+    for (const [key, value] of Object.entries(values)) {
+        content = upsertEnvLine(content, key, value);
+        process.env[key] = value;
+    }
+    fs.writeFileSync(envPath, content);
+}
+const CONFIG_BASENAME = 'zhin.config';
+const YAML_EXTENSIONS = ['.yml', '.yaml'];
+/** 定位项目配置文件：ZHIN_CONFIG 指定优先，否则发现 zhin.config.yml/.yaml，都没有则默认新建 zhin.config.yml */
+export function findEndpointConfigFile(adapterKey, projectRoot) {
+    const root = projectRoot ?? resolveProjectRoot();
+    const envConfig = process.env.ZHIN_CONFIG?.trim();
+    if (envConfig)
+        return path.resolve(root, envConfig);
+    for (const ext of YAML_EXTENSIONS) {
+        const candidate = path.join(root, `${CONFIG_BASENAME}${ext}`);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    for (const ext of ['.json', '.toml', '.ts']) {
+        const candidate = path.join(root, `${CONFIG_BASENAME}${ext}`);
+        if (fs.existsSync(candidate)) {
+            throw new Error(`暂不支持写入 ${ext} 配置文件，请手动在 ${CONFIG_BASENAME}${ext} 的 plugins.${adapterKey}.endpoints 中维护`);
+        }
+    }
+    return path.join(root, `${CONFIG_BASENAME}.yml`);
+}
+function readConfigDocument(adapterKey, projectRoot) {
+    const filePath = findEndpointConfigFile(adapterKey, projectRoot);
+    const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : '';
+    const doc = parseDocument(content || '{}');
+    return { filePath, doc };
+}
+function writeConfigDocument({ filePath, doc }) {
+    fs.writeFileSync(filePath, doc.toString());
+}
+/** 读取 plugins.<adapterKey>.endpoints（plain JS）；plugins/<adapterKey> 缺失或形态不符时返回 [] */
+export function listConfiguredEndpoints(adapterKey, projectRoot) {
+    const { doc } = readConfigDocument(adapterKey, projectRoot);
+    const plugins = doc.toJS()?.plugins;
+    if (!plugins || typeof plugins !== 'object' || Array.isArray(plugins))
+        return [];
+    const endpoints = plugins[adapterKey]?.endpoints;
+    if (!Array.isArray(endpoints))
+        return [];
+    return endpoints.filter((entry) => !!entry && typeof entry === 'object' && typeof entry.name === 'string');
+}
+function entryName(item) {
+    if (!isMap(item))
+        return undefined;
+    const name = item.get('name');
+    return typeof name === 'string' && name ? name : undefined;
+}
+/**
+ * 确保 plugins.<adapterKey>.endpoints 存在并返回其 YAMLSeq（节点级操作，保留既有条目与注释）。
+ * `plugins: []`（legacy 空列表，Runtime 忽略）可直接替换为 map；非空数组拒绝写入。
+ */
+function ensureEndpointsSeq(doc, adapterKey) {
+    const plugins = doc.get('plugins');
+    if (isSeq(plugins) && plugins.items.length > 0) {
+        throw new Error('配置的 plugins 是数组形态（legacy 插件名列表），请手动迁移为 map 后再试');
+    }
+    if (plugins !== undefined && !isMap(plugins) && !isSeq(plugins)) {
+        throw new Error('配置的 plugins 字段形态异常，请手动检查 zhin.config.yml');
+    }
+    if (!isMap(doc.get('plugins'))) {
+        // 注意：空对象 {} 不会被 doc.set 自动包装为 YAMLMap，必须显式 createNode
+        doc.set('plugins', doc.createNode({}));
+    }
+    const adapterNode = doc.getIn(['plugins', adapterKey]);
+    if (adapterNode !== undefined && !isMap(adapterNode)) {
+        throw new Error(`配置的 plugins.${adapterKey} 字段形态异常，请手动检查 zhin.config.yml`);
+    }
+    if (!isMap(doc.getIn(['plugins', adapterKey]))) {
+        doc.setIn(['plugins', adapterKey], doc.createNode({}));
+    }
+    const endpoints = doc.getIn(['plugins', adapterKey, 'endpoints']);
+    if (endpoints !== undefined && !isSeq(endpoints)) {
+        throw new Error(`配置的 plugins.${adapterKey}.endpoints 字段形态异常，请手动检查 zhin.config.yml`);
+    }
+    if (!isSeq(doc.getIn(['plugins', adapterKey, 'endpoints']))) {
+        doc.setIn(['plugins', adapterKey, 'endpoints'], doc.createNode([]));
+    }
+    return doc.getIn(['plugins', adapterKey, 'endpoints']);
+}
+/** 追加 endpoint 到 plugins.<adapterKey>.endpoints；name 已存在时报错 */
+export function addEndpointToConfig(adapterKey, entry, projectRoot) {
+    const document = readConfigDocument(adapterKey, projectRoot);
+    const seq = ensureEndpointsSeq(document.doc, adapterKey);
+    if (seq.items.some((item) => entryName(item) === entry.name)) {
+        throw new Error(`配置中已存在 ${adapterKey} endpoint「${entry.name}」，可先 ${adapterKey} endpoint remove ${entry.name} 再重新添加`);
+    }
+    seq.items.push(document.doc.createNode(entry));
+    writeConfigDocument(document);
+    return document.filePath;
+}
+/** 按 name 移除 plugins.<adapterKey>.endpoints 项；不存在返回 false */
+export function removeEndpointFromConfig(adapterKey, name, projectRoot) {
+    const document = readConfigDocument(adapterKey, projectRoot);
+    const seq = ensureEndpointsSeq(document.doc, adapterKey);
+    const next = seq.items.filter((item) => entryName(item) !== name);
+    if (next.length === seq.items.length) {
+        return { removed: false, filePath: document.filePath };
+    }
+    seq.items = next;
+    writeConfigDocument(document);
+    return { removed: true, filePath: document.filePath };
+}
+function endpointNameParam(params) {
+    const name = params.name;
+    return typeof name === 'string' && name.trim() ? name.trim() : undefined;
+}
+/** list 文案：运行中 + 配置中两段，footer 可选。 */
+export function formatEndpointList(spec, source) {
+    const running = [...source.running];
+    const lines = [];
+    lines.push(`【运行中的 ${spec.adapterDisplayName} endpoints】`);
+    if (running.length === 0) {
+        lines.push('  （无）');
+    }
+    else {
+        for (const endpoint of running) {
+            lines.push(endpoint.mode ? `  - ${endpoint.name}（${endpoint.mode}）` : `  - ${endpoint.name}`);
+        }
+    }
+    lines.push(`【配置中的 ${spec.adapterDisplayName} endpoints】（zhin.config.yml → plugins.${spec.adapterKey}.endpoints）`);
+    if (source.configured.length === 0) {
+        lines.push('  （无）');
+    }
+    else {
+        for (const entry of source.configured) {
+            const detail = spec.describeEntry?.(entry);
+            lines.push(detail ? `  - ${entry.name}（${detail}）` : `  - ${entry.name}`);
+        }
+    }
+    if (source.footer)
+        lines.push(source.footer);
+    return lines.join('\n');
+}
+function addUsage(spec) {
+    const fields = spec.fields ?? [];
+    const fieldText = fields.length === 0
+        ? ''
+        : `\n字段：${fields.map((field) => {
+            const marks = [
+                field.required ? '必填' : '',
+                field.env ? '写入 .env' : '',
+                field.description ?? '',
+            ].filter(Boolean).join('，');
+            return marks ? `${field.key}（${marks}）` : field.key;
+        }).join('、')}`;
+    return `用法：${spec.adapterKey} endpoint add <name> <key=value...>${fieldText}`;
+}
+/** add（kv 模式）的完整业务逻辑：解析 kv → 凭据写 .env → 追加 yaml；返回回复文本。 */
+export function addEndpointFromKeyValues(spec, name, args, projectRoot) {
+    const fields = spec.fields ?? [];
+    const known = new Map(fields.map((field) => [field.key, field]));
+    const values = new Map();
+    for (const arg of args) {
+        const eq = arg.indexOf('=');
+        if (eq <= 0)
+            return `参数「${arg}」不是 key=value 形式。${addUsage(spec)}`;
+        const key = arg.slice(0, eq);
+        const value = arg.slice(eq + 1).trim();
+        const field = known.get(key);
+        if (!field) {
+            return `未知字段「${key}」，可用字段：${fields.map((item) => item.key).join('、')}`;
+        }
+        if (!value)
+            return `字段「${key}」的值不能为空`;
+        values.set(key, value);
+    }
+    const missing = fields.filter((field) => field.required && !values.has(field.key));
+    if (missing.length > 0) {
+        return `缺少必填字段：${missing.map((field) => field.key).join('、')}。${addUsage(spec)}`;
+    }
+    const entry = { name };
+    const envValues = {};
+    for (const field of fields) {
+        const value = values.get(field.key);
+        if (value === undefined)
+            continue;
+        if (field.env) {
+            const envKey = buildEndpointEnvKey(spec.adapterKey, name, field.key);
+            envValues[envKey] = value;
+            entry[field.key] = `\${${envKey}}`;
+        }
+        else {
+            entry[field.key] = value;
+        }
+    }
+    try {
+        // 先写配置（重名等校验失败时不留孤儿 .env 键），再落 .env 凭据
+        const filePath = addEndpointToConfig(spec.adapterKey, entry, projectRoot);
+        if (Object.keys(envValues).length > 0)
+            persistEndpointEnvValues(envValues, projectRoot);
+        return (`✅ endpoint「${name}」已追加到 ${filePath} 的 plugins.${spec.adapterKey}.endpoints` +
+            `${Object.keys(envValues).length > 0 ? '（凭据已写入 .env）' : ''}。\n` +
+            '⚠️ 需重启 zhin 后新 endpoint 才会生效。');
+    }
+    catch (error) {
+        return `添加失败：${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+/** remove 的完整业务逻辑：从 yaml 移除；返回回复文本。 */
+export function removeEndpointByName(spec, name, projectRoot) {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return `用法：${spec.adapterKey} endpoint remove <name>`;
+    try {
+        const { removed, filePath } = removeEndpointFromConfig(spec.adapterKey, trimmed, projectRoot);
+        if (!removed) {
+            return `配置中不存在 ${spec.adapterKey} endpoint「${trimmed}」（${filePath} → plugins.${spec.adapterKey}.endpoints）`;
+        }
+        return (`已从 ${filePath} 的 plugins.${spec.adapterKey}.endpoints 移除「${trimmed}」。\n` +
+            '⚠️ 需重启 zhin 后生效（运行中的连接届时才会断开）；.env 中的凭据键未删除，可手动清理。');
+    }
+    catch (error) {
+        return `移除失败：${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+/** 生成 `<adapter> endpoint` 的 list / add / remove 三个命令定义（见文件头接入步骤）。 */
+export function createEndpointCommands(spec, defineCommand) {
+    const forbidden = endpointCommandForbidden(spec.adapterDisplayName);
+    return Object.freeze({
+        list: defineCommand({
+            description: `列出 ${spec.adapterDisplayName} endpoints（运行中 + zhin.config.yml 配置）`,
+            execute({ use }) {
+                return formatEndpointList(spec, {
+                    running: spec.running?.(use) ?? [],
+                    configured: listConfiguredEndpoints(spec.adapterKey),
+                    footer: spec.listFooter?.(use),
+                });
+            },
+        }),
+        add: defineCommand({
+            description: spec.addDescription
+                ?? `手动添加 ${spec.adapterDisplayName} endpoint（凭据写入 .env 并追加到 zhin.config.yml，重启生效）`,
+            execute({ config, input, params, args, use }) {
+                if (!isEndpointOperator(config, input))
+                    return forbidden;
+                const name = endpointNameParam(params);
+                if (spec.bindFlow) {
+                    return spec.bindFlow({
+                        name,
+                        reply: extractEndpointCommandReply(input),
+                        config,
+                        input,
+                        use,
+                    });
+                }
+                if (!name)
+                    return addUsage(spec);
+                return addEndpointFromKeyValues(spec, name, args);
+            },
+        }),
+        remove: defineCommand({
+            description: `从 zhin.config.yml 的 plugins.${spec.adapterKey}.endpoints 移除指定 endpoint（重启生效）`,
+            execute({ config, input, params }) {
+                if (!isEndpointOperator(config, input))
+                    return forbidden;
+                return removeEndpointByName(spec, String(params.name ?? ''));
+            },
+        }),
+    });
+}

package/lib/endpoint-lifecycle.d.ts

@@ -0,0 +1,68 @@
+export type EndpointLifecycleState = 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed' | 'stopped';
+export interface EndpointLifecycleReconnectOptions {
+    /** 首次重连间隔（ms），默认 5000。 */
+    readonly initialIntervalMs?: number;
+    /** 退避倍数，默认 2（1 = 固定间隔，兼容旧 reconnect_interval 语义）。 */
+    readonly multiplier?: number;
+    /** 退避封顶（ms），默认 60000。 */
+    readonly maxIntervalMs?: number;
+    /** 每次重连附加的随机抖动上限（ms），默认 250；测试可配 random 使其确定。 */
+    readonly jitterMs?: number;
+    /** 最大连续重连失败次数，默认 Infinity；耗尽后进入 closed 终态。 */
+    readonly maxAttempts?: number;
+}
+export interface EndpointLifecycleHeartbeatOptions {
+    /** startHeartbeat 缺省间隔（ms），默认 30000；<=0 表示不开心跳。 */
+    readonly intervalMs?: number;
+    /**
+     * 看门狗轮数：连续 N 次心跳未收到回包（notifyHeartbeatAck）后，
+     * 下一心跳周期主动调用强关函数。默认 0 = 关闭看门狗。
+     */
+    readonly watchdogMisses?: number;
+}
+export interface EndpointLifecycleOptions {
+    /** 端点名，仅用于日志字段。 */
+    readonly name: string;
+    /** 重连配置；传 false 禁用自动重连（对端断开后进入 closed）。 */
+    readonly reconnect?: EndpointLifecycleReconnectOptions | false;
+    /** 心跳配置。 */
+    readonly heartbeat?: EndpointLifecycleHeartbeatOptions;
+    /** 随机源（jitter 用），默认 Math.random；测试注入 () => 0 获得确定退避序列。 */
+    readonly random?: () => number;
+}
+/**
+ * 每次 connect 尝试获得一个句柄；generation 过期后其方法自动失效，
+ * 因此适配器无需担心旧 socket 的迟到事件污染新连接。
+ */
+export interface EndpointConnectHandle {
+    /**
+     * 底层连接关闭（对端断开 / 看门狗强关 / 任意 close 事件）时调用。
+     * 仅当本次连接曾 open（即 connectFn 已 resolve）才武装退避重连；
+     * 初始连接失败由 start() 的拒绝路径复位，不武装重连。
+     */
+    notifyClosed(reason?: unknown): void;
+    /** 注册当前连接的强制关闭函数（心跳看门狗与 stop 使用）；每次 connect 覆盖。 */
+    onForceClose(close: () => void): void;
+}
+export type EndpointConnectFn = (handle: EndpointConnectHandle) => Promise<void>;
+export interface EndpointLifecycle {
+    readonly state: EndpointLifecycleState;
+    /** start 已成功且未 stop（含 connecting / open / reconnecting）。 */
+    readonly started: boolean;
+    /**
+     * 启动并建立首连。重复调用幂等（进行中/已连接时直接返回）。
+     * connectFn 须在连接 open 时 resolve、失败或 open 前 close 时 reject；
+     * stop-during-connect 时本方法静默 resolve（主动停止不算失败）。
+     */
+    start(connect: EndpointConnectFn): Promise<void>;
+    /** 主动停止：清全部定时器、强关连接、唤醒竞态等待；幂等，绝不触发重连。 */
+    stop(): Promise<void>;
+    /** 启动心跳；重复调用先清旧 timer。intervalMs 缺省取配置，<=0 不开。 */
+    startHeartbeat(beat: () => void, intervalMs?: number): void;
+    /** 清理心跳 timer（close / stop / 看门狗触发时基座会自动调用）。 */
+    stopHeartbeat(): void;
+    /** 喂狗：收到任何回包（message / pong / 心跳响应）时调用，复位看门狗计数。 */
+    notifyHeartbeatAck(): void;
+}
+/** 创建端点生命周期基座实例（见文件头迁移指引）。 */
+export declare function createEndpointLifecycle(options: EndpointLifecycleOptions): EndpointLifecycle;