lark-remote 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.4.0] - 2026-09-15
+
+### 新增
+
+- **运行期间阻止系统休眠**：运行中自动阻止系统休眠（macOS 用 `caffeinate`、Windows 用 `SetThreadExecutionState`）——典型用法是人不在电脑前远程使用，系统一旦休眠连接即断。只阻止系统休眠，不影响显示器睡眠；退出（含异常退出）后自动解除，helper 意外退出也会留痕兜底。注意：MacBook 合盖睡眠无法阻止（除非接电源并外接显示器）
+- **入站媒体保存提示带完整路径**：收到的图片/文件落盘后，提示带目录完整路径，方便直接定位
+
+### 修复
+
+- **卡片更新瞬态失败自动重试**：飞书卡片更新遇到连接瞬时中断等瞬态传输错误时就地重试（最多 3 次），不再把失败直接落到未处理 rejection 上导致进程退出
+- **Kimi 审批卡恢复完整 Bash 命令**：审批卡片按 `toolCallId` 关联流式参数，恢复展示完整命令而非截断片段
+- **Kimi 权限模式文案对齐 kimi 0.40+ 语义**：`yolo` 现指「必要时询问」而非完全放行，完全自动请选 `auto`；README 与配置文档同步更新
+
+### 变更
+
+- **文档自称统一**：README、使用文档与架构文档中的自称统一为 lark-remote
+
 ## [0.3.0] - 2026-09-13
 
 ### 新增

package/README.en.md

@@ -16,7 +16,7 @@ Designed for a single-user, peer-to-peer private chat. The agent's system prompt
 
 ## ⚠️ Security Warning (read first)
 
-This tool turns Feishu messages directly into local agent executions. **Out of the box, agents run without approval prompts**: Claude defaults to `bypassPermissions` (no approval card), but that permission mode is **configurable** — set it to anything other than `bypassPermissions` (`default` / `acceptEdits` / `auto` / `dontAsk` / `plan`) to enable interactive approval, where high-risk actions wait for your confirmation on the Feishu card. Codex uses the **app-server approval mode** (default `approvalPolicy=on-request` — command execution requires your confirmation on the Feishu card, sandbox defaults to `workspace-write`); Kimi defaults to `manual` (per-action approval); other agents run with their CLI defaults. **In any mode**, agents can read and write the local directories you specify. You MUST:
+This tool turns Feishu messages directly into local agent executions. **Out of the box, agents run without approval prompts**: Claude defaults to `bypassPermissions` (no approval card), but that permission mode is **configurable** — set it to anything other than `bypassPermissions` (`default` / `acceptEdits` / `auto` / `dontAsk` / `plan`) to enable interactive approval, where high-risk actions wait for your confirmation on the Feishu card. Codex uses the **app-server approval mode** (default `approvalPolicy=on-request` — command execution requires your confirmation on the Feishu card, sandbox defaults to `workspace-write`); Kimi defaults to `manual` (per-action approval; note that since kimi 0.40, `yolo` means Ask-When-Needed rather than allow-everything — use `auto` for fully unattended, no-approval execution); other agents run with their CLI defaults. **In any mode**, agents can read and write the local directories you specify. You MUST:
 
 - **Use it only in your own private (p2p) chat.** Never add the bot to any group chat; never let anyone else talk to it.
 - Restrict the app's visibility to **yourself only** in the Feishu Open Platform.
@@ -52,7 +52,7 @@ git clone https://github.com/bungabungawoda/lark-remote.git
 cd lark-remote
 bun install
 bun run build
-bun install -g "$(pwd)"  # install globally as the lark-remote command (bun parses `.` as an empty package name; use an absolute path)
+bun install -g "$(pwd)"  # install globally as lark-remote command (bun parses `.` as an empty package name; use an absolute path)
 ```
 
 ## Configuration
@@ -94,7 +94,7 @@ lark-remote --config-dir ~/.lark-remote-test    # custom config dir (multiple in
 lark-remote --settings ~/.claude/settings.json  # specify Claude settings file
 ```
 
-The bridge prints nothing to the terminal after startup; logs go to `~/.lark-remote/logs/YYYY-MM-DD/lark-remote-<pid>.log` (rotated daily, one subdirectory per day). Only one `lark-remote` instance is allowed per `configDir` — a duplicate start fails with the existing pid. After connecting to Feishu, a startup notification (with start time and pid) is sent to the most recent private chat.
+lark-remote prints nothing to the terminal after startup; logs go to `~/.lark-remote/logs/YYYY-MM-DD/lark-remote-<pid>.log` (rotated daily, one subdirectory per day). Only one `lark-remote` instance is allowed per `configDir` — a duplicate start fails with the existing pid. After connecting to Feishu, a startup notification (with start time and pid) is sent to the most recent private chat.
 
 Each agent run creates one CardKit 2.0 card that updates in place with thinking, body text, and tool summaries in real time.
 Timestamps are read from the JSONL and shown in local time as `YYYY-MM-DD HH:mm` for thinking, body, tool call/result, and session history events.
@@ -117,12 +117,12 @@ Your original message also gets an emoji reaction: `Typing` while the run is in
 | `/status` | `/s` | Current directory, session, model, process status |
 | `/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 |
+| `/restart` | - | In-place lark-remote self-restart (new process takes over with the same config) |
+| `/clone [name]` | - | Clone lark-remote: 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) |
-| `/exit` | `/e` | Exit the bridge |
+| `/exit` | `/e` | Exit lark-remote |
 
 Any message not starting with `/` is forwarded to the current default agent.
 

package/README.md

@@ -16,7 +16,7 @@
 
 ## ⚠️ 安全警告（必读）
 
-本工具会把飞书消息直接转为本地 agent 执行。**开箱默认是不弹审批的**：Claude 默认以 `bypassPermissions` 运行（无审批卡），但该权限模式**可配置**——把它改成 `bypassPermissions` 以外的值（`default` / `acceptEdits` / `auto` / `dontAsk` / `plan`）即启用交互式审批，高风险操作会在飞书卡片上等你确认；Codex 采用 **app-server 审批模式**（默认 `approvalPolicy=on-request`，执行命令需在飞书卡片上确认，沙箱默认 `workspace-write`）；Kimi 默认 `manual`（逐条审批）；其他 agent 以各自 CLI 的默认权限运行。**无论哪种模式**，agent 都能读写你指定的本地目录，请务必：
+本工具会把飞书消息直接转为本地 agent 执行。**开箱默认是不弹审批的**：Claude 默认以 `bypassPermissions` 运行（无审批卡），但该权限模式**可配置**——把它改成 `bypassPermissions` 以外的值（`default` / `acceptEdits` / `auto` / `dontAsk` / `plan`）即启用交互式审批，高风险操作会在飞书卡片上等你确认；Codex 采用 **app-server 审批模式**（默认 `approvalPolicy=on-request`，执行命令需在飞书卡片上确认，沙箱默认 `workspace-write`）；Kimi 默认 `manual`（逐条审批；注意 kimi 0.40+ 起 `yolo` 已改为「必要时询问」而非全部放行，要完全不弹审批需选 `auto`）；其他 agent 以各自 CLI 的默认权限运行。**无论哪种模式**，agent 都能读写你指定的本地目录，请务必：
 
 - **仅限你自己的私聊（p2p）使用**。不要把机器人拉进任何群聊，不要让任何其他人能与它对话。
 - 在飞书开放平台把应用可见范围限制到**只有你自己**。
@@ -94,7 +94,7 @@ lark-remote --config-dir ~/.lark-remote-test    # 自定义配置目录（同机
 lark-remote --settings ~/.claude/settings.json  # 指定 Claude 配置文件
 ```
 
-bridge 启动后不在终端输出，运行日志写入 `~/.lark-remote/logs/YYYY-MM-DD/lark-remote-<pid>.log`（按日期轮转，每天一个子目录）。同一 `configDir` 只允许一个 `lark-remote` 实例，重复启动会直接报错并提示已有 pid。连接飞书成功后会向最近私聊用户发送启动通知，包含启动时间和进程号。
+lark-remote 启动后不在终端输出，运行日志写入 `~/.lark-remote/logs/YYYY-MM-DD/lark-remote-<pid>.log`（按日期轮转，每天一个子目录）。同一 `configDir` 只允许一个 `lark-remote` 实例，重复启动会直接报错并提示已有 pid。连接飞书成功后会向最近私聊用户发送启动通知，包含启动时间和进程号。
 
 每次 agent 运行会创建一张 CardKit 2.0 卡片，并在原地实时更新 thinking、正文和工具摘要。
 卡片会读取 JSONL 的 `timestamp`，以本地时间 `YYYY-MM-DD HH:mm` 显示 thinking、正文、tool call/result 和会话历史事件。
@@ -117,20 +117,21 @@ bridge 启动后不在终端输出，运行日志写入 `~/.lark-remote/logs/YYY
 | `/status` | `/s` | 当前目录、session、模型、进程状态 |
 | `/stop` | `/t` | 终止当前 agent 进程（SIGKILL） |
 | `/ps` | - | 是否有进程在跑 |
-| `/restart` | - | 原地自重启 bridge（新进程同 config 接管） |
+| `/restart` | - | 原地自重启 lark-remote（新进程同 config 接管） |
 | `/clone [name]` | - | 复制分身：克隆当前配置到新目录并扫码创建新飞书应用，完成后自动绑定、同步状态并拉起新实例 |
 | `/config get\|set` | `/c` | 查改运行时配置（agent-aware 卡片） |
 | `/order save\|list\|edit\|alias` | `/o` | 收藏常用指令；`/order edit` 修改指令文本（保留别名/使用统计）；`/order alias` 注册快捷别名（输入 `$name` 展开） |
 | `!<cmd>` | - | 执行 bash 命令并流式输出到卡片（绕过串行队列） |
-| `/exit` | `/e` | 退出 bridge |
+| `/exit` | `/e` | 退出 lark-remote |
 
 直接发非 `/` 开头的消息即转发给当前默认 agent。
 
-**复制分身（`/clone`）**：想在另一个项目/机器目录旁跑一个独立 bridge 实例时，发 `/clone 名字` 即可——当前配置目录会被克隆为 `<configDir>-<名字>`（除飞书凭据外全部复制），二维码以图片消息发进私聊引导你扫码创建一个全新飞书应用；扫码成功后自动完成绑定，workspace 别名、常用指令、工作目录与会话状态一并迁移，新实例自动拉起并可直接续聊。也可直接点 `/help` 卡片上的「/clone」按钮。详见 [docs/zh/usage.md](docs/zh/usage.md)。
+**复制分身（`/clone`）**：想在另一个项目/机器目录旁跑一个独立 lark-remote 实例时，发 `/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)。
+（建议把 `.lark-remote-temp/` 加进项目 `.gitignore`），保存提示里会带上目录完整路径，
+随后说「请处理刚才保存的文件」（或直接把提示转给 agent）即可让 agent 直接读本地文件。
+更多用法见 [docs/zh/usage.md](docs/zh/usage.md)。
 
 ## 测试
 

package/dist/binder.d.ts

@@ -10,7 +10,7 @@ type BindDecision = {
 /**
  * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 openId 可用。
  *
- * 设计依据：bridge 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
+ * 设计依据：lark-remote 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
  * 飞书自建应用的私聊入口本身就是 owner 掌控的（应用只有 owner 能看到/使用，
  * 分享出去属于 owner 的主动行为），因此首次消息即绑定，不再要求输入 PIN。
  * 本类复用已有 startup-contact.json，不新增配置字段。

package/dist/binder.js

@@ -2,7 +2,7 @@ import { getLogger } from './logger/index.js';
 /**
  * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 openId 可用。
  *
- * 设计依据：bridge 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
+ * 设计依据：lark-remote 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
  * 飞书自建应用的私聊入口本身就是 owner 掌控的（应用只有 owner 能看到/使用，
  * 分享出去属于 owner 的主动行为），因此首次消息即绑定，不再要求输入 PIN。
  * 本类复用已有 startup-contact.json，不新增配置字段。

package/dist/bridge/final-usage.js

@@ -26,7 +26,7 @@ export function resolveFinalUsage(registry, defaultAgent, sessionId, cwd, agentK
             // EnterWorktree relocate (2026-08-04): jsonl read silently returned no
             // usage (e.g. transcript moved mid-session). Surface it so token-stat
             // fallback to per-run live usage is visible in logs, not silent.
-            getLogger().warn(`[bridge] resolveFinalUsage: no usage from jsonl sessionId=${sessionId} cwd=${cwd} agent=${agentKind}, card falls back to per-run live usage`);
+            getLogger().warn(`[lark-remote] resolveFinalUsage: no usage from jsonl sessionId=${sessionId} cwd=${cwd} agent=${agentKind}, card falls back to per-run live usage`);
         }
         return content.usage
             ? {
@@ -48,7 +48,7 @@ export function resolveFinalUsage(registry, defaultAgent, sessionId, cwd, agentK
             : undefined;
     }
     catch (err) {
-        getLogger().warn(`[bridge] resolveFinalUsage failed sessionId=${sessionId}: ${errorMessage(err)}`);
+        getLogger().warn(`[lark-remote] resolveFinalUsage failed sessionId=${sessionId}: ${errorMessage(err)}`);
         return undefined;
     }
 }

package/dist/bridge/inbound-media.js

@@ -266,11 +266,13 @@ export class InboundMediaHandler {
         const lines = batch.saved.slice(0, MAX_PATHS_IN_NOTIFICATION).map((p) => `- ${p}`);
         const overflow = batch.saved.length > MAX_PATHS_IN_NOTIFICATION ? `\n… 等 ${batch.saved.length} 个文件` : '';
         const failures = batch.errors.length > 0 ? `\n⚠️ ${batch.errors.join('；')}` : '';
-        const text = `📎 已保存 ${batch.saved.length} 个文件：\n` +
-            lines.join('\n') +
-            overflow +
-            failures +
-            '\n💡 你可以直接说：请处理刚才保存的文件';
+        // 提示带上保存目录：用户把整句转给 agent 即可定位，无需靠目录约定反查。
+        // 合批窗口跨分钟时可能落在两个目录，此时全部列出。
+        const dirs = [...new Set(batch.saved.map((p) => path.dirname(p)))];
+        const hint = dirs.length === 1
+            ? `\n💡 你可以直接说：请处理 ${dirs[0]} 下的文件`
+            : `\n💡 你可以直接说：请处理以下目录下的文件：${dirs.join('、')}`;
+        const text = `📎 已保存 ${batch.saved.length} 个文件：\n` + lines.join('\n') + overflow + failures + hint;
         await this.deps.send({
             userId: batch.payload.userId,
             chatId: batch.payload.chatId,