lark-remote 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-09-13
+
+### 新增
+
+- **`/clone [name]`（复制分身）**：把当前配置目录克隆为一份新分身（`<configDir>-<name>`，省略名字时随机生成后缀；除飞书 `appId`/`appSecret` 外全部复制），引导你扫码创建全新飞书应用——二维码以图片消息直接发进私聊，约 10 分钟内有效。扫码成功后自动完成绑定并把 workspace 别名、常用指令、工作目录与会话状态一并同步到分身，随后自动拉起新实例（新应用会收到它的启动通知），原应用回执新应用 App ID、配置目录与进程号。等待扫码期间消息不转发给 agent：输入「重发」重新生成二维码，`/Q` 取消。`/help` 卡片的「/clone」按钮可直接点击开始
+- **一键复制分身按钮**：`/help` 卡片按钮区新增「/clone」，与无参 `/clone` 等价
+
+### 变更
+
+- **首次绑定简化**：未绑定时首条私聊消息（任意内容）即完成 owner 绑定，移除原 4 位 PIN。飞书自建应用私聊入口本身由 owner 掌控，把应用分享出去才属主动行为；绑定成功会回执确认
+
+### 修复
+
+- **Codex / Kimi CLI 版本探测走平台 spawn 收口**：CLI 可执行文件探测统一经由跨平台 spawn 层，修复 Windows 下的探测兼容性问题
+- **`bun run test:live` 退出码**：在 `bun run` 下正确透传退出码，不再误报失败
+
 ## [0.2.2] - 2026-09-12
 
 ### 修复

package/README.en.md

@@ -118,6 +118,7 @@ Your original message also gets an emoji reaction: `Typing` while the run is in
 | `/stop` | `/t` | Kill the current agent process (SIGKILL) |
 | `/ps` | - | Whether a process is running |
 | `/restart` | - | In-place bridge self-restart (new process takes over with the same config) |
+| `/clone [name]` | - | Clone the bridge: copies the current config into a new directory and walks you through creating a brand-new Feishu app by QR scan; on success it binds, syncs state, and launches the new instance |
 | `/config get\|set` | `/c` | View/change runtime config (agent-aware card) |
 | `/order save\|list\|edit` | `/o` | Save, list, or edit frequently used prompts |
 | `!<cmd>` | - | Run a bash command with streaming card output (bypasses the serial queue) |
@@ -125,6 +126,8 @@ Your original message also gets an emoji reaction: `Typing` while the run is in
 
 Any message not starting with `/` is forwarded to the current default agent.
 
+**Clone the bridge (`/clone`)**: to run an independent bridge instance next to another project directory, send `/clone <name>` — the current config directory is cloned to `<configDir>-<name>` (everything except the Feishu credentials), a QR code is sent into the chat as an image to create a brand-new Feishu app, and once you scan it the new app is bound automatically with workspace aliases, saved prompts, working directory, and session state carried over; the new instance launches itself and is ready to chat. You can also hit the "/clone" button on the `/help` card. See [docs/en/usage.md](docs/en/usage.md) for details.
+
 ## Testing
 
 ```bash

package/README.md

@@ -118,6 +118,7 @@ bridge 启动后不在终端输出，运行日志写入 `~/.lark-remote/logs/YYY
 | `/stop` | `/t` | 终止当前 agent 进程（SIGKILL） |
 | `/ps` | - | 是否有进程在跑 |
 | `/restart` | - | 原地自重启 bridge（新进程同 config 接管） |
+| `/clone [name]` | - | 复制分身：克隆当前配置到新目录并扫码创建新飞书应用，完成后自动绑定、同步状态并拉起新实例 |
 | `/config get\|set` | `/c` | 查改运行时配置（agent-aware 卡片） |
 | `/order save\|list\|edit\|alias` | `/o` | 收藏常用指令；`/order edit` 修改指令文本（保留别名/使用统计）；`/order alias` 注册快捷别名（输入 `$name` 展开） |
 | `!<cmd>` | - | 执行 bash 命令并流式输出到卡片（绕过串行队列） |
@@ -125,6 +126,8 @@ bridge 启动后不在终端输出，运行日志写入 `~/.lark-remote/logs/YYY
 
 直接发非 `/` 开头的消息即转发给当前默认 agent。
 
+**复制分身（`/clone`）**：想在另一个项目/机器目录旁跑一个独立 bridge 实例时，发 `/clone 名字` 即可——当前配置目录会被克隆为 `<configDir>-<名字>`（除飞书凭据外全部复制），二维码以图片消息发进私聊引导你扫码创建一个全新飞书应用；扫码成功后自动完成绑定，workspace 别名、常用指令、工作目录与会话状态一并迁移，新实例自动拉起并可直接续聊。也可直接点 `/help` 卡片上的「/clone」按钮。详见 [docs/zh/usage.md](docs/zh/usage.md)。
+
 往飞书私聊发**图片/文件**会自动保存到当前目录的 `.lark-remote-temp/<YYYYMMDDHHmm>/`
 （建议把 `.lark-remote-temp/` 加进项目 `.gitignore`），随后说「请处理刚才保存的文件」
 即可让 agent 直接读本地文件。更多用法见 [docs/zh/usage.md](docs/zh/usage.md)。

package/dist/binder.d.ts

@@ -6,31 +6,25 @@ type BindDecision = {
     kind: 'rejected';
 } | {
     kind: 'bind_success';
-} | {
-    kind: 'pin_wrong';
 };
 /**
- * Owner 绑定器：首次私聊输入正确 PIN 完成"认领"，此后仅该 openId 可用。
+ * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 openId 可用。
  *
- * 设计依据（第一性原理）：bridge 进程持有用户本机完整权限，唯一合法主体是
- * owner 本人。任何入站事件都必须认证到该单一主体。`chatType==='p2p'` 不是认证
- * （任何能私聊机器人的用户都满足）。本类以"首次绑定 + openId 强校验"实现认证，
- * 复用已有 startup-contact.json，不新增配置字段。
+ * 设计依据：bridge 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
+ * 飞书自建应用的私聊入口本身就是 owner 掌控的（应用只有 owner 能看到/使用，
+ * 分享出去属于 owner 的主动行为），因此首次消息即绑定，不再要求输入 PIN。
+ * 本类复用已有 startup-contact.json，不新增配置字段。
  *
  * 状态机：
- * - 未绑定：生成 PIN（控制台展示），等待 owner 私聊输入正确 PIN -> 写入绑定。
- *   输错 PIN 完全静默（不回复、不提醒）；首次启动仅用户本机可见，无需严格防枚举。
+ * - 未绑定：第一条私聊消息（任意内容）即完成绑定 -> 写入 startup-contact.json。
  * - 已绑定：仅 senderId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
  *
  * cardAction 同样校验 operator.openId === bound.userId（未绑定也视为非 owner）。
  */
 export declare class OwnerBinder {
     private readonly store;
-    private pin;
     private rejectedTotal;
     constructor(store: StartupContactStore);
-    /** 仅未绑定时返回待输入的 PIN（控制台展示用）。 */
-    get pendingPin(): string | undefined;
     isBound(): boolean;
     /** 已绑定的 owner openId；未绑定时 undefined。 */
     boundOpenId(): string | undefined;
@@ -42,16 +36,15 @@ export declare class OwnerBinder {
      * 对入站私聊消息做绑定/授权判定，含副作用：
      * - `owner`：放行，调用方继续正常处理
      * - `rejected`：已绑定但非 owner，静默丢弃（计数 + debug）
-     * - `bind_success`：未绑定且 PIN 正确，写入绑定并清除 PIN
-     * - `pin_wrong`：未绑定且 PIN 错误，静默丢弃（不回复、不提醒）
+     * - `bind_success`：未绑定收到首条消息，写入绑定（任意内容均可）
      */
     classify(senderId: string, content: string, chatId: string): BindDecision;
     /** 卡片操作被拒时计数（与消息路径共用计数器）。 */
     recordRejectedCardAction(openId: string): void;
 }
 /**
- * 控制台 PIN 引导文案（首次未绑定时输出到 stderr；守护模式下被 watchdog
+ * 控制台绑定引导文案（首次未绑定时输出到 stderr；守护模式下被 watchdog
  * 重定向到 daemon 日志）。绑定后此文案不再出现。
  */
-export declare function formatPinGuidance(pin: string): string;
+export declare function formatBindGuidance(): string;
 export {};

package/dist/binder.js

@@ -1,40 +1,23 @@
-import crypto from 'node:crypto';
 import { getLogger } from './logger/index.js';
-/** 绑定 PIN 位数。4 位数字便于人工输入。 */
-const PIN_DIGITS = 4;
-/** 用 CSPRNG 生成固定长度、零填充的数字 PIN（首位可为 0）。 */
-function generatePin() {
-    const n = crypto.randomInt(0, 10 ** PIN_DIGITS);
-    return String(n).padStart(PIN_DIGITS, '0');
-}
 /**
- * Owner 绑定器：首次私聊输入正确 PIN 完成"认领"，此后仅该 openId 可用。
+ * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 openId 可用。
  *
- * 设计依据（第一性原理）：bridge 进程持有用户本机完整权限，唯一合法主体是
- * owner 本人。任何入站事件都必须认证到该单一主体。`chatType==='p2p'` 不是认证
- * （任何能私聊机器人的用户都满足）。本类以"首次绑定 + openId 强校验"实现认证，
- * 复用已有 startup-contact.json，不新增配置字段。
+ * 设计依据：bridge 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
+ * 飞书自建应用的私聊入口本身就是 owner 掌控的（应用只有 owner 能看到/使用，
+ * 分享出去属于 owner 的主动行为），因此首次消息即绑定，不再要求输入 PIN。
+ * 本类复用已有 startup-contact.json，不新增配置字段。
  *
  * 状态机：
- * - 未绑定：生成 PIN（控制台展示），等待 owner 私聊输入正确 PIN -> 写入绑定。
- *   输错 PIN 完全静默（不回复、不提醒）；首次启动仅用户本机可见，无需严格防枚举。
+ * - 未绑定：第一条私聊消息（任意内容）即完成绑定 -> 写入 startup-contact.json。
  * - 已绑定：仅 senderId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
  *
  * cardAction 同样校验 operator.openId === bound.userId（未绑定也视为非 owner）。
  */
 export class OwnerBinder {
     store;
-    pin;
     rejectedTotal = 0;
     constructor(store) {
         this.store = store;
-        if (!store.getContact()) {
-            this.pin = generatePin();
-        }
-    }
-    /** 仅未绑定时返回待输入的 PIN（控制台展示用）。 */
-    get pendingPin() {
-        return this.pin;
     }
     isBound() {
         return this.store.getContact() !== undefined;
@@ -56,8 +39,7 @@ export class OwnerBinder {
      * 对入站私聊消息做绑定/授权判定，含副作用：
      * - `owner`：放行，调用方继续正常处理
      * - `rejected`：已绑定但非 owner，静默丢弃（计数 + debug）
-     * - `bind_success`：未绑定且 PIN 正确，写入绑定并清除 PIN
-     * - `pin_wrong`：未绑定且 PIN 错误，静默丢弃（不回复、不提醒）
+     * - `bind_success`：未绑定收到首条消息，写入绑定（任意内容均可）
      */
     classify(senderId, content, chatId) {
         const bound = this.store.getContact();
@@ -68,16 +50,10 @@ export class OwnerBinder {
             getLogger().debug(`[binder] rejected message from ${senderId} (total rejected=${this.rejectedCount})`);
             return { kind: 'rejected' };
         }
-        // 未绑定：要求 PIN（精确匹配 trim 后内容，避免部分匹配绕过）
-        if (this.pin !== undefined && content.trim() === this.pin) {
-            this.store.save({ chatId, userId: senderId });
-            this.pin = undefined;
-            getLogger().info(`[binder] owner bound: openId=${senderId} chatId=${chatId}`);
-            return { kind: 'bind_success' };
-        }
-        // 输错 PIN：完全静默（不回复、不提醒、不计数），仅内部 debug 日志
-        getLogger().debug('[binder] wrong pin (unbound, ignored)');
-        return { kind: 'pin_wrong' };
+        // 未绑定：任意内容即绑定（首条消息完成认领）
+        this.store.save({ chatId, userId: senderId });
+        getLogger().info(`[binder] owner bound: openId=${senderId} chatId=${chatId}`);
+        return { kind: 'bind_success' };
     }
     /** 卡片操作被拒时计数（与消息路径共用计数器）。 */
     recordRejectedCardAction(openId) {
@@ -86,16 +62,14 @@ export class OwnerBinder {
     }
 }
 /**
- * 控制台 PIN 引导文案（首次未绑定时输出到 stderr；守护模式下被 watchdog
+ * 控制台绑定引导文案（首次未绑定时输出到 stderr；守护模式下被 watchdog
  * 重定向到 daemon 日志）。绑定后此文案不再出现。
  */
-export function formatPinGuidance(pin) {
+export function formatBindGuidance() {
     return [
         '',
         '🔒 首次绑定',
-        '请在飞书私聊本应用，发送以下 4 位数字完成绑定：',
-        '',
-        `    ${pin}`,
+        '请在飞书私聊本应用，发送任意消息完成绑定：',
         '',
         '绑定后仅该账号可使用本应用。',
         '需更换账号：删除 <configDir>/startup-contact.json 后重启。',

package/dist/clone.d.ts

@@ -0,0 +1,139 @@
+import { type QRCodeInfo, type RegisterAppResult } from '@larksuite/channel';
+/**
+ * 复制分身（/clone）状态机。
+ *
+ * 在当前 bridge 进程内引导用户扫码创建一个新飞书应用，并生成一份"分身"
+ * 配置目录：除 feishu.appId/appSecret 来自新应用外，其余配置原样复制；
+ * 创建完成后用新应用拿到的用户 openId 直接写好绑定（owner 无需再输入
+ * 任意内容认领），并 detached 拉起指向新配置目录的新实例——启动后新
+ * 实例自己会向新应用发送启动通知，即完成"在新应用主动触达用户"。
+ *
+ * 状态机（仅在原始应用内运行）：
+ * - idle：未进入流程。`/clone [name]` 进入 awaiting_scan。
+ * - awaiting_scan：二维码已发出，SDK 后台轮询等扫码。此阶段用户的一切
+ *   消息不转发 coding agent：「重发」重新生成二维码，/Q 取消，其余输入
+ *   回引导文案。
+ * - finalizing：扫码成功，正在写配置/绑定/拉起，短暂过渡态，输入被婉拒。
+ *
+ * 注册生命周期用「代际判定」管理：runRegistration 捕获本轮 AbortController，
+ * then 分支先比对 this.abortController —— /Q 取消或「重发」都会替换/清空
+ * controller，过期代际的 resolve/reject 一律静默，防止旧凭证覆盖新一轮。
+ *
+ * 安全边界：流程由已绑定 owner 在私聊里发起（router 入口已过 OwnerBinder
+ * 闸门），新配置目录写入本机，不涉及对外暴露。
+ */
+type CloneState = 'idle' | 'awaiting_scan' | 'finalizing';
+/**
+ * 校验用户指定的分身名字：路径分隔符、以 . 开头、尾点/尾空格（win32 会静默
+ * 吞掉）、win32 保留设备名一律拒绝。
+ */
+export declare function isValidCloneName(name: string): boolean;
+/** 随机后缀：2 位数字 + 2 位小写字母/数字，如 `37ab`。 */
+export declare function generateCloneSuffix(): string;
+/** clone 流程内发消息所需的上下文（router CommandContext 的结构子集）。 */
+export interface CloneContext {
+    userId: string;
+    chatId: string;
+    messageId?: string;
+}
+/** clone 流程依赖的 connector 发送面（测试用 stub 结构化满足）。 */
+export interface CloneConnector {
+    sendWithRetry(chatId: string, input: {
+        text: string;
+    } | {
+        markdown: string;
+    } | {
+        card: object;
+    }, opts?: {
+        replyTo?: string;
+    }): Promise<string>;
+    sendImage(chatId: string, filePath: string): Promise<string>;
+}
+type RegisterAppFn = (options: {
+    source: string;
+    signal?: AbortSignal;
+    /** 分身必须是全新应用：复用已有应用会让两个实例抢同一份凭证。 */
+    createOnly?: boolean;
+    onQRCodeReady: (info: QRCodeInfo) => void;
+    onStatusChange?: (info: {
+        status: string;
+    }) => void;
+}) => Promise<RegisterAppResult>;
+/**
+ * 默认新实例拉起：同入口 + 同参数，仅替换 --config-dir（detached，返回 pid）。
+ * spawn 骨架（log fd / windowsHide / error 兜底）单源于 restart.ts。
+ */
+export declare function spawnDetachedCloneBridge(targetDir: string): number | undefined;
+export interface CloneSessionOptions {
+    connector: CloneConnector;
+    /** 当前实例的 config.yaml 路径（配置复制源）。 */
+    configPath: string;
+    /** 当前实例的配置目录（分身目录 = 该目录 + '-' + 后缀/名字）。 */
+    configDir: string;
+    /** 覆盖 SDK registerApp（测试注入）。 */
+    registerAppFn?: RegisterAppFn;
+    /** 覆盖随机后缀生成（测试注入确定性序列）。 */
+    generateSuffix?: () => string;
+    /** 覆盖新实例拉起（测试注入；默认 detached spawn 同入口进程）。 */
+    spawnNewInstance?: (targetDir: string) => number | undefined;
+}
+export declare class CloneSession {
+    private state;
+    private targetDir;
+    private abortController;
+    private readonly connector;
+    private readonly configPath;
+    private readonly configDir;
+    private readonly registerAppFn;
+    private readonly generateSuffixFn;
+    private readonly spawnNewInstanceFn;
+    constructor(opts: CloneSessionOptions);
+    /** 当前状态（测试断言用）。 */
+    get currentState(): CloneState;
+    isActive(): boolean;
+    /** 已确定但尚未写入的分身配置目录（测试断言用）。 */
+    get pendingTargetDir(): string | undefined;
+    /**
+     * 进入创建分身流程：确定新配置目录 → 发二维码 → 等扫码。
+     * 目录已存在 / 名字非法时不进入流程（保持 idle），仅回错误说明。
+     */
+    start(nameArg: string | undefined, ctx: CloneContext): Promise<void>;
+    /**
+     * awaiting_scan / finalizing 阶段的一切入站消息都进这里（index.ts 在
+     * 消息入队前拦截，不转发 coding agent、不进命令分发）。
+     */
+    handleMessage(content: string, ctx: CloneContext): Promise<void>;
+    private dirFor;
+    /** 起一轮扫码注册：QR 就绪即发图，成功 finalize，失败回引导（保持流程）。 */
+    private runRegistration;
+    private sendQrCode;
+    private onRegistrationError;
+    /**
+     * 扫码成功后的自动绑定落地：
+     * 1. 复制当前 config.yaml，仅替换 feishu.appId/appSecret；
+     * 2. 同步 workspace / 常用指令 / 会话状态（session 按 openId 重绑）；
+     * 3. 用 registerApp 返回的新应用 openId 写 startup-contact.json（免认领绑定）；
+     * 4. detached 拉起指向新目录的新实例（启动后自动向新应用发启动通知）；
+     * 5. 在原应用回执「绑定完成 + 配置目录」，退出流程。
+     */
+    private finalize;
+    /** 全局状态文件（workspace 别名 / 常用指令）原样复制到分身目录。 */
+    private copyGlobalStateFiles;
+    /**
+     * last-session.json 按 openId 重绑后复制。SessionStore 以 userId 为主键，
+     * 旧应用的 openId 在新应用无效：只迁移旧 owner 的条目并挂到新 openId 名下
+     * （cwd / 各 agent sessionId / 停车位 / 到达基线 / sessionCwds 原样保留——
+     * session 文件在同一台机器上，分身实例自动恢复即可续聊）。其余用户条目
+     * 不迁移：分身实例只服务新 owner。
+     */
+    private copySessionState;
+    /** 旧实例绑定的 owner openId（来自当前目录 startup-contact.json）。 */
+    private readOldOwnerId;
+    /**
+     * 写配置失败时清理半成品目录。守卫：只删内容全部是本次产物
+     * （config.yaml / startup-contact.json 及其 .tmp）的目录，混入其他
+     * 文件时保留现场不动。
+     */
+    private cleanupPartialDir;
+}
+export {};