lark-remote 0.2.2 → 0.3.0

package/dist/connector/index.js

@@ -378,11 +378,10 @@ export class FeishuConnector {
         }
     }
     /**
-     * Upload a file to Feishu and send it to the specified chat.
-     * Uses the im/v1/files upload API.
+     * sendFile/sendImage 共用：校验文件存在与大小上限（30MB，对齐飞书
+     * im/v1 上传 API）。noun 是消息里的小写名词（'file'/'image'）。
      */
-    async sendFile(chatId, filePath) {
-        // Check file existence first with proper error handling
+    checkUploadable(filePath, noun) {
         let stat;
         try {
             stat = fs.statSync(filePath);
@@ -390,33 +389,32 @@ export class FeishuConnector {
         catch (err) {
             const code = err.code;
             if (code === 'ENOENT') {
-                throw new Error(`Cannot access file: file not found (${filePath})`, { cause: err });
+                throw new Error(`Cannot access ${noun}: file not found (${filePath})`, { cause: err });
             }
-            throw new Error(`Cannot access file: ${err.message}`, { cause: err });
+            throw new Error(`Cannot access ${noun}: ${err.message}`, { cause: err });
         }
-        // Check file size limit (30MB, aligned with Feishu im/v1/files API)
         if (stat.size > MAX_FILE_UPLOAD_SIZE) {
-            throw new Error(`File too large (${(stat.size / 1_000_000).toFixed(1)}MB), exceeds ${MAX_FILE_UPLOAD_SIZE / (1024 * 1024)}MB limit`);
+            const nounCap = noun.charAt(0).toUpperCase() + noun.slice(1);
+            throw new Error(`${nounCap} too large (${(stat.size / 1_000_000).toFixed(1)}MB), exceeds ${MAX_FILE_UPLOAD_SIZE / (1024 * 1024)}MB limit`);
         }
-        const fileName = displayName(filePath);
-        // P2-18: capture the read stream so it can be destroyed on any failure
-        // path. Without this, a token/upload/send failure leaks the fd (axios
-        // only closes the stream when it fully consumes it on success).
+    }
+    /**
+     * sendFile/sendImage 共用骨架：token → 上传（流在任何失败路径销毁，P2-18）
+     * → 发送媒体消息。上传端点 / form 字段 / 响应 key / msg_type 的差异由调用方
+     * 以 uploadUrl + buildForm + keyField + msgType 表达；timeout、noKeepAliveAgent
+     * （Bun keep-alive 修复）与错误包装在此单源。label 是对外错误前缀与日志
+     * 标签（'sendFile' | 'sendImage'）。
+     */
+    async uploadAndSendMedia(chatId, filePath, label, uploadUrl, buildForm, keyField, msgType) {
         let fileStream = null;
         try {
-            // P2-18: tenant_access_token cache. Avoid re-fetching on every file send
-            // (token is valid ~2h); validate data.code before trusting the token.
+            // P2-18: tenant_access_token cache（~2h），避免每次发送都取 token。
             const accessToken = await this.getTenantAccessToken();
-            // Upload file
-            const form = new FormData();
             fileStream = fs.createReadStream(filePath);
-            form.append('file', fileStream);
-            form.append('file_name', fileName);
-            form.append('file_type', 'stream');
-            // P2-18: timeout on the upload (large file, slow link) — 120s.
-            // httpsAgent: noKeepAlive — prevents Bun from reusing a server-RST'd
-            // keep-alive socket (ECONNRESET after ~30s; see noKeepAliveAgent docs).
-            const uploadResp = await axios.post('https://open.feishu.cn/open-apis/im/v1/files', form, {
+            const form = buildForm(fileStream);
+            // P2-18: timeout 120s（大文件慢链路）；httpsAgent: noKeepAlive 防止
+            // Bun 复用已被服务端 RST 的 keep-alive socket（ECONNRESET after ~30s）。
+            const uploadResp = await axios.post(uploadUrl, form, {
                 headers: {
                     ...form.getHeaders(),
                     Authorization: `Bearer ${accessToken}`,
@@ -425,15 +423,14 @@ export class FeishuConnector {
                 httpsAgent: noKeepAliveAgent,
             });
             if (uploadResp.data.code !== 0) {
-                throw new Error(`File upload failed: ${uploadResp.data.msg}`);
+                throw new Error(`Upload failed: ${uploadResp.data.msg}`);
             }
-            const fileKey = uploadResp.data.data.file_key;
-            // Send file message. P2-18: timeout 30s.
-            // httpsAgent: noKeepAlive — same Bun keep-alive fix as upload above.
+            const mediaKey = uploadResp.data.data[keyField];
+            // P2-18: timeout 30s；noKeepAlive 同上。
             const sendResp = await axios.post('https://open.feishu.cn/open-apis/im/v1/messages', {
                 receive_id: chatId,
-                msg_type: 'file',
-                content: JSON.stringify({ file_key: fileKey }),
+                msg_type: msgType,
+                content: JSON.stringify({ [keyField]: mediaKey }),
             }, {
                 headers: {
                     'Content-Type': 'application/json; charset=utf-8',
@@ -444,7 +441,7 @@ export class FeishuConnector {
                 httpsAgent: noKeepAliveAgent,
             });
             if (sendResp.data.code !== 0) {
-                throw new Error(`File message failed: ${sendResp.data.msg}`);
+                throw new Error(`Media message failed: ${sendResp.data.msg}`);
             }
             return sendResp.data.data.message_id;
         }
@@ -458,12 +455,39 @@ export class FeishuConnector {
                     /* already destroyed */
                 }
             }
-            // Log the error but throw a formatted error to prevent unhandled rejection
             const errorInfo = this.formatError(err);
-            getLogger().error('[feishu] sendFile failed:', errorInfo);
-            throw new Error(`sendFile failed: ${errorInfo}`, { cause: err });
+            getLogger().error(`[feishu] ${label} failed:`, errorInfo);
+            throw new Error(`${label} failed: ${errorInfo}`, { cause: err });
         }
     }
+    /**
+     * Upload a file to Feishu and send it to the specified chat.
+     * Uses the im/v1/files upload API.
+     */
+    async sendFile(chatId, filePath) {
+        this.checkUploadable(filePath, 'file');
+        return this.uploadAndSendMedia(chatId, filePath, 'sendFile', 'https://open.feishu.cn/open-apis/im/v1/files', (stream) => {
+            const form = new FormData();
+            form.append('file', stream);
+            form.append('file_name', displayName(filePath));
+            form.append('file_type', 'stream');
+            return form;
+        }, 'file_key', 'file');
+    }
+    /**
+     * Upload a local image file to Feishu and send it as an image message
+     * (im/v1/images + msg_type=image). Used by the clone wizard to deliver the
+     * scan-to-create QR code inline instead of as a downloadable file.
+     */
+    async sendImage(chatId, filePath) {
+        this.checkUploadable(filePath, 'image');
+        return this.uploadAndSendMedia(chatId, filePath, 'sendImage', 'https://open.feishu.cn/open-apis/im/v1/images', (stream) => {
+            const form = new FormData();
+            form.append('image_type', 'message');
+            form.append('image', stream);
+            return form;
+        }, 'image_key', 'image');
+    }
     /**
      * Cached tenant_access_token for sendFile (P2-18). The token is valid ~2h;
      * fetching it on every file send wastes a round-trip and an unguarded fetch

package/dist/index.js

@@ -15,7 +15,8 @@ import { buildCardActionFullValue } from './router/card-action-payload.js';
 import { Bridge } from './bridge/index.js';
 import { initLogger, getLogger } from './logger/index.js';
 import { StartupContactStore, sendStartupHello } from './startup-contact.js';
-import { OwnerBinder, formatPinGuidance } from './binder.js';
+import { OwnerBinder, formatBindGuidance } from './binder.js';
+import { CloneSession } from './clone.js';
 import { InstanceAlreadyRunningError, InstanceLock } from './instance-lock.js';
 import { spawnReplacementBridge, waitForPreviousInstance } from './restart.js';
 import { checkLatestVersion, isNewer, runInstallLatest, formatUpdateHint } from './update/index.js';
@@ -26,6 +27,14 @@ import { newSessionButton, resumeCompactButton, agentDisplayName } from './card/
 import path from 'node:path';
 import fs from 'node:fs';
 import { silentlyUnlink } from './common/fs.js';
+/**
+ * /stop 命令别名单源：普通消息的停止分支与 clone 活跃期拦截的排除条件
+ * 共用同一判定，防止将来加别名时两处漂移。
+ */
+function isStopCommand(text) {
+    const t = text.trim().toLowerCase();
+    return t === '/stop' || t === '/t';
+}
 /** Send auto-resume card for a restored session */
 async function sendAutoResumeCard(connector, contact, cwd, session, state, compactSupported = false) {
     if (!contact.userId)
@@ -280,7 +289,7 @@ function initializeRunner(config, configDir, cliArgs) {
     return { agentRegistry, sessionReaderRegistry };
 }
 /** Setup message and card action handlers. */
-function setupMessageHandlers(connector, router, bridge, sessionStore, workspaceStore, binder, logger, config) {
+function setupMessageHandlers(connector, router, bridge, sessionStore, workspaceStore, binder, logger, config, cloneSession) {
     // 入站媒体（图片/文件）：先认证后下载（P1 review 修复）。
     // connector 只上报"媒体到达"，这里先过 owner + enabled 闸门，通过后才
     // 下载——未认证/关闭配置时不会发生任何网络下载或内存/磁盘占用。
@@ -324,13 +333,10 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         })().catch((err) => logger.error('[media] inbound media download/save failed:', err));
     });
     connector.setMessageHandler((msg) => {
-        // 绑定/授权闸门：仅 owner 放行；非 owner 静默丢弃；未绑定时要求 PIN 认领
+        // 绑定/授权闸门：仅 owner 放行；非 owner 静默丢弃；未绑定时首条消息（任意内容）认领
         const decision = binder.classify(msg.userId, msg.content, msg.chatId);
         if (decision.kind === 'rejected')
             return;
-        // 未绑定且 PIN 错误：完全静默丢弃（不回复、不提醒）
-        if (decision.kind === 'pin_wrong')
-            return;
         if (decision.kind === 'bind_success') {
             // First-run onboarding: set default cwd + send welcome + Help card.
             // setCwd is synchronous (outside the async closure) so that the user's
@@ -385,12 +391,23 @@ function setupMessageHandlers(connector, router, bridge, sessionStore, workspace
         bridge.flushMediaNotifications(msg.userId, msg.chatId);
         // Add Typing reaction to indicate "still alive"
         void connector.addReaction(msg.messageId, 'Typing');
+        // 复制分身流程活跃期：一切消息先经 clone 状态机（stop 命令除外，保留其
+        // 绕队列停止能力），不转发 coding agent、不进命令分发、不展开别名。
+        if (cloneSession.isActive() && !isStopCommand(msg.content)) {
+            void cloneSession
+                .handleMessage(msg.content, {
+                userId: msg.userId,
+                chatId: msg.chatId,
+                messageId: msg.messageId,
+            })
+                .catch((err) => logger.error('[clone] message handling failed:', err));
+            return;
+        }
         // 别名展开：命令分发前对消息做一次 $name 展开（不递归）。
         // `!` / `/` 开头的消息不会进入展开路径（$PATH、$HOME 等 shell 变量不受影响），
         // 未知 $xxx 原样透传；展开结果若以 `/` 开头会自然落入命令路径。
         const content = router.expandAliasMessage(msg.content);
-        const trimmedLower = content.trim().toLowerCase();
-        if (trimmedLower === '/stop' || trimmedLower === '/t') {
+        if (isStopCommand(content)) {
             void (async () => {
                 const stopped = await bridge.interruptCurrentRun({
                     userId: msg.userId,
@@ -619,10 +636,10 @@ async function main() {
     const connector = new FeishuConnector(config);
     const startupContactStore = new StartupContactStore(path.join(configDir, 'startup-contact.json'));
     const binder = new OwnerBinder(startupContactStore);
-    if (binder.pendingPin) {
-        // 未绑定：控制台（stderr）展示 PIN。守护模式下被 watchdog 重定向到 daemon 日志
-        console.error(formatPinGuidance(binder.pendingPin));
-        logger.info('[binder] awaiting first binding (PIN printed to stderr)');
+    if (!binder.isBound()) {
+        // 未绑定：控制台（stderr）引导任意消息绑定。守护模式下被 watchdog 重定向到日志
+        console.error(formatBindGuidance());
+        logger.info('[binder] awaiting first binding (any first private message binds)');
     }
     else {
         logger.info(`[binder] bound to owner openId=${binder.boundOpenId()}`);
@@ -637,6 +654,11 @@ async function main() {
         agentRegistry,
         sessionReaderRegistry,
     });
+    const cloneSession = new CloneSession({
+        connector,
+        configPath: path.join(configDir, 'config.yaml'),
+        configDir,
+    });
     const router = new CommandRouter({
         sessionStore,
         bridge,
@@ -648,8 +670,9 @@ async function main() {
         sessionReaderRegistry,
         devMode: cliArgs.dev,
         updateCachePath: path.join(configDir, 'update-cache.json'),
+        cloneSession,
     });
-    setupMessageHandlers(connector, router, bridge, sessionStore, workspaceStore, binder, logger, config);
+    setupMessageHandlers(connector, router, bridge, sessionStore, workspaceStore, binder, logger, config, cloneSession);
     try {
         await connector.connect();
     }

package/dist/restart.d.ts

@@ -8,6 +8,23 @@
  */
 /** Env var telling a replacement child which parent pid to wait for before acquiring the instance lock. */
 export declare const RESTART_WAIT_PID_ENV = "LARK_REMOTE_RESTART_WAIT_PID";
+/**
+ * Spawn a detached bridge process (shared by /restart replacement and /clone
+ * new-instance) whose early output — before the child's own file logger
+ * initializes — lands on logFilePath. Returns the child pid, or null when
+ * spawn failed synchronously / no pid; filesystem errors (unwritable log
+ * dir) propagate. Caller picks throw-vs-degrade semantics.
+ *
+ * Two disciplines live here so every caller inherits them for free:
+ * - windowsHide: win32 detached children would flash a console window (§3.7);
+ * - the 'error' handler is attached BEFORE the pid check — a failed spawn
+ *   emits 'error' asynchronously (ENOENT/EACCES), and the synchronous pid
+ *   check throws/returns first, so attaching after would leave the 'error'
+ *   event unhandled → uncaughtException kills the parent.
+ */
+export declare function spawnDetachedBridge(args: string[], logFilePath: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+}): number | null;
 /**
  * Spawn a detached replacement bridge with the same executable and argv
  * (including --config-dir) and return its pid. The caller is expected to

package/dist/restart.js

@@ -15,6 +15,41 @@ import { sleep } from './common/sleep.js';
 export const RESTART_WAIT_PID_ENV = 'LARK_REMOTE_RESTART_WAIT_PID';
 const WAIT_TIMEOUT_MS = 20_000;
 const POLL_MS = 100;
+/**
+ * Spawn a detached bridge process (shared by /restart replacement and /clone
+ * new-instance) whose early output — before the child's own file logger
+ * initializes — lands on logFilePath. Returns the child pid, or null when
+ * spawn failed synchronously / no pid; filesystem errors (unwritable log
+ * dir) propagate. Caller picks throw-vs-degrade semantics.
+ *
+ * Two disciplines live here so every caller inherits them for free:
+ * - windowsHide: win32 detached children would flash a console window (§3.7);
+ * - the 'error' handler is attached BEFORE the pid check — a failed spawn
+ *   emits 'error' asynchronously (ENOENT/EACCES), and the synchronous pid
+ *   check throws/returns first, so attaching after would leave the 'error'
+ *   event unhandled → uncaughtException kills the parent.
+ */
+export function spawnDetachedBridge(args, logFilePath, opts) {
+    fs.mkdirSync(path.dirname(logFilePath), { recursive: true });
+    const out = fs.openSync(logFilePath, 'a');
+    try {
+        const child = spawnProcess(process.execPath, args, {
+            cwd: process.cwd(),
+            env: opts?.env ?? process.env,
+            detached: true,
+            windowsHide: true,
+            stdio: ['ignore', out, out],
+        });
+        child.on('error', () => { });
+        if (child.pid === undefined)
+            return null;
+        child.unref();
+        return child.pid;
+    }
+    finally {
+        fs.closeSync(out);
+    }
+}
 /**
  * Spawn a detached replacement bridge with the same executable and argv
  * (including --config-dir) and return its pid. The caller is expected to
@@ -22,29 +57,13 @@ const POLL_MS = 100;
  * startup failures (before the file logger initializes) are not lost.
  */
 export function spawnReplacementBridge(logsDir) {
-    fs.mkdirSync(logsDir, { recursive: true });
-    const out = fs.openSync(path.join(logsDir, 'restart-child.log'), 'a');
-    const child = spawnProcess(process.execPath, process.argv.slice(1), {
-        cwd: process.cwd(),
+    const pid = spawnDetachedBridge(process.argv.slice(1), path.join(logsDir, 'restart-child.log'), {
         env: { ...process.env, [RESTART_WAIT_PID_ENV]: String(process.pid) },
-        detached: true,
-        // win32：detached 继任者默认会闪控制台窗口（§3.7）
-        windowsHide: true,
-        stdio: ['ignore', out, out],
     });
-    // Late spawn errors (e.g. binary removed mid-run) must not crash the
-    // exiting parent via an unhandled 'error' event. Attach BEFORE the pid
-    // check — a failed spawn emits 'error' asynchronously (ENOENT/EACCES),
-    // and the pid check below throws synchronously first, so attaching after
-    // the throw would leave the 'error' event unhandled → uncaughtException
-    // → the old bridge exits despite having promised to stay alive.
-    child.on('error', () => { });
-    fs.closeSync(out);
-    if (child.pid === undefined) {
+    if (pid === null) {
         throw new Error('spawn replacement bridge failed: no pid');
     }
-    child.unref();
-    return child.pid;
+    return pid;
 }
 /**
  * On startup, if this process was spawned as a restart replacement, wait for

package/dist/router/index.d.ts

@@ -2,6 +2,7 @@ import type { SessionStore, SessionReaderRegistry } from '../session/index.js';
 import type { AppConfig } from '../config/index.js';
 import type { Bridge } from '../bridge/index.js';
 import type { AgentBinding } from '../bridge/queue-manager.js';
+import type { CloneSession } from '../clone.js';
 import { type VersionCheckResult, type InstallResult } from '../update/index.js';
 interface CommandContext {
     userId: string;
@@ -125,6 +126,8 @@ export declare class CommandRouter {
     private devMode;
     /** Cache file for version checks (<configDir>/update-cache.json). */
     private updateCachePath?;
+    /** 复制分身状态机（/clone 入口 + 活跃期消息拦截）。 */
+    private cloneSession?;
     /** Injected update functions (for testability; defaults to real implementation). */
     private updateFns;
     /** /config 卡片编辑暂存区（public：测试直接读取断言，替代 as unknown as）。 */
@@ -177,6 +180,8 @@ export declare class CommandRouter {
         devMode?: boolean;
         /** Version check cache path (<configDir>/update-cache.json). */
         updateCachePath?: string;
+        /** 复制分身状态机（/clone；index.ts 构造注入，未注入时命令回报不可用）。 */
+        cloneSession?: CloneSession;
         /** Override update functions for testability. */
         updateFns?: {
             checkLatestVersion?: (opts?: {
@@ -455,6 +460,11 @@ export declare class CommandRouter {
      * Flow: check version → if newer, install → report success (no auto-restart).
      */
     private cmdUpdate;
+    /**
+     * /clone [name] — 复制分身：进入 clone 状态机（发二维码、等扫码、自动绑定）。
+     * 全程由 CloneSession 自己经 connector 发消息（含二维码图片），故返回 null。
+     */
+    private cmdClone;
     private cmdNew;
     private cmdCd;
     private readSessionDisplayState;

package/dist/router/index.js

@@ -347,6 +347,8 @@ export class CommandRouter {
     devMode;
     /** Cache file for version checks (<configDir>/update-cache.json). */
     updateCachePath;
+    /** 复制分身状态机（/clone 入口 + 活跃期消息拦截）。 */
+    cloneSession;
     /** Injected update functions (for testability; defaults to real implementation). */
     updateFns;
     /** /config 卡片编辑暂存区（public：测试直接读取断言，替代 as unknown as）。 */
@@ -400,6 +402,7 @@ export class CommandRouter {
         this.sessionReaderRegistry = opts.sessionReaderRegistry;
         this.devMode = opts.devMode ?? false;
         this.updateCachePath = opts.updateCachePath;
+        this.cloneSession = opts.cloneSession;
         this.updateFns = {
             checkLatestVersion: opts.updateFns?.checkLatestVersion ?? defaultCheckLatestVersion,
             isNewer: opts.updateFns?.isNewer ?? defaultIsNewer,
@@ -421,6 +424,13 @@ export class CommandRouter {
         const startsWithBang = trimmed.startsWith('!');
         const startsWithSlash = trimmed.startsWith('/');
         getLogger().info(`[router] handle message="${message.slice(0, 50)}..." trimmed="${trimmed.slice(0, 50)}..." startsWithSlash=${startsWithSlash} startsWithBang=${startsWithBang}`);
+        // 复制分身流程活跃期：一切消息（含命令）交给 clone 状态机处理，
+        // 不转发 coding agent、不进命令分发（index.ts 已在入队前拦截，这里
+        // 兜住 order.exec 等其他 router.handle 入口）。
+        if (this.cloneSession?.isActive()) {
+            await this.cloneSession.handleMessage(trimmed, ctx);
+            return null;
+        }
         if (startsWithSlash) {
             const result = await this.executeCommand(trimmed, ctx);
             if (result) {
@@ -2001,6 +2011,8 @@ export class CommandRouter {
             case 'update':
             case 'u':
                 return await this.cmdUpdate(args, ctx);
+            case 'clone':
+                return await this.cmdClone(args, ctx);
             default:
                 return { text: `未知命令 /${cmd}，输入 /help 查看可用命令` };
         }
@@ -2021,6 +2033,11 @@ export class CommandRouter {
             { cmd: 'exit', label: '/exit /e', desc: '退出 bridge' },
             { cmd: 'restart', label: '/restart', desc: '重启 bridge（新进程，config 不变）' },
             { cmd: 'update', label: '/update /u', desc: '检查并升级到最新版本' },
+            {
+                cmd: 'clone',
+                label: '/clone',
+                desc: '复制分身：克隆配置并扫码创建新应用',
+            },
             { cmd: 'status', label: '/status /s', desc: '显示当前状态' },
         ].sort((a, b) => a.label.length - b.label.length || a.cmd.localeCompare(b.cmd));
         // 文本组（需带参数，不宜用按钮；以纯文本行展示）
@@ -2271,6 +2288,17 @@ ${sessionCwdLine}${agentLines.map((l) => `- ${l}`).join('\n')}
         // 4. Report success (no auto-restart — user decides when to /restart)
         return { text: `✅ 升级成功 (${current} → ${latest})，发送 /restart 重启后生效` };
     }
+    /**
+     * /clone [name] — 复制分身：进入 clone 状态机（发二维码、等扫码、自动绑定）。
+     * 全程由 CloneSession 自己经 connector 发消息（含二维码图片），故返回 null。
+     */
+    async cmdClone(args, ctx) {
+        if (!this.cloneSession) {
+            return { text: '当前环境未启用创建分身功能' };
+        }
+        await this.cloneSession.start(args[0], ctx);
+        return null;
+    }
     cmdNew(ctx) {
         // 只清 sessionId 保留 cwd — 否则 /new 之后 /resume 会提示"请先 /cd
         // 设置工作目录"，但用户的 workspace 还在。2026-06-21 复盘：用户

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-remote",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Feishu (Lark) private-chat bridge to local coding agents — Claude Code / Codex / opencode / pi / kimi, with live-streaming CardKit 2.0 cards",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -58,7 +58,7 @@
     "test:opencode-full": "vitest run --project agent-opencode --project infra-runner --project infra-session",
     "test:pi-full": "vitest run --project agent-pi --project infra-runner --project infra-session",
     "test:kimi-full": "vitest run --project agent-kimi --project infra-runner --project infra-session",
-    "test:live": "vitest run --project live",
+    "test:live": "node node_modules/vitest/vitest.mjs run --project live",
     "prepublishOnly": "npm run typecheck && vitest run && npm run build",
     "prepack": "node -e \"const fs=require('fs');if(!fs.existsSync('dist/cli.js')){console.error('dist/ missing — run bun run build first');process.exit(1)}\""
   },