@keyou007/agent-bot 0.1.8 → 0.1.10

package/docs/technical-reference.md

@@ -35,7 +35,7 @@ The default user-data root is `~/.agent-bot`. `AGENT_BOT_HOME` replaces that roo
 
 The CLI also supports explicit directory-based profiles. Without `--profile`, commands use the main profile and the normal environment-based path rules. `--profile <directory>` pins both `AGENT_BOT_HOME` and `AGENT_BOT_CONFIG` for the command and every spawned supervisor or worker, with the configuration fixed at `<directory>/config.yaml`. It also clears inherited Feishu credential variables before loading the selected profile's `.env`, which prevents a secondary service launched from inside the primary Agent Bot process tree from accidentally reusing the primary bot. It cannot be combined with `--config`. Alternative profiles must be selected explicitly on every command; Agent Bot does not maintain a named-profile registry.
 
-All CLI interface text is English regardless of system locale. System-generated restart reasons remain Chinese because they are rendered in Chinese Lark status cards; an explicit `--reason` is preserved verbatim. `agent-bot server status` reports the running worker's Lark App ID as `feishuAppId` in JSON; when the server is stopped or predates that health field, the CLI falls back to the selected profile's configured App ID.
+The CLI reads the system locale through Node.js internationalization support. Locales beginning with `zh` use Chinese interface text; English and every unsupported locale use English. This applies to help, status, progress, prompts, and CLI-owned errors. JSON field names and enum values are not localized. System-generated restart reasons remain Chinese because they are rendered in Chinese Lark status cards; an explicit `--reason` is preserved verbatim. `agent-bot server status` reports the running worker's Lark App ID as `feishuAppId` in JSON; when the server is stopped or predates that health field, the CLI falls back to the selected profile's configured App ID.
 
 | Default path                         | Contents                           |
 | ------------------------------------ | ---------------------------------- |
@@ -75,9 +75,17 @@ When complete credentials are absent, initialization uses Feishu one-click regis
 
 Missing app configuration is handled in two stages:
 
-1. Core configuration is requested and polled until it becomes available.
+1. Core configuration is requested and polled until it becomes available. The manually configured all-group-message scope may be explicitly skipped with `Y`.
 2. Remaining optional configuration is requested. The CLI prints its QR code followed by the authorization URL, then immediately polls for up to five minutes. An interactive terminal offers only `Y` to skip optional authorization and continue; otherwise the user completes authorization in the browser while polling continues.
 
+Configuration supported by the one-click launcher is encoded in its `addons` manifest. The core `im:message.group_msg` scope is excluded from that manifest because Feishu does not add it through one-click configuration. Instead, the CLI prints a QR code and this app-specific, pre-filtered Developer Console URL:
+
+```text
+https://open.feishu.cn/app/<appId>/auth?q=im%3Amessage.group_msg&op_from=openapi&token_type=tenant
+```
+
+The user must add the permission, publish the app version, and complete tenant approval when required. Core polling then detects the permission in the published version before initialization continues. In an interactive terminal, entering `Y` skips only this manual permission wait; other missing core scopes and the message event remain blocking. Initialization returns a partial configuration result and warns that ordinary group messages which do not mention the bot are unavailable.
+
 Optional polling failures and timeouts return a partial configuration result instead of failing initialization. When stdin is not an interactive terminal, no skip input is available and polling continues until configuration becomes active or times out. Verification URLs and prompts use stderr, so `--json` keeps its final stdout machine-readable.
 
 The generated authorization links do not contain the app secret.
@@ -93,7 +101,7 @@ Core configuration required for basic messaging:
 - Bot capability
 - Persistent-connection event delivery
 - `im.message.receive_v1`
-- `im:message.group_msg:readonly` for all user messages in groups containing the bot
+- `im:message.group_msg` for all user messages in groups containing the bot
 - Tenant permission for private messages
 - `im:message:send_as_bot` or a broader equivalent
 - `application:application:self_manage` so initialization can inspect the published version
@@ -181,6 +189,8 @@ Starting a Feishu thread from a mapped user message, progress card, or final res
 
 `/forkgroup` has thread-aware source selection. An unbound thread, or a bound thread task with no completed turn of its own, forks directly from the thread's original anchor turn without creating an intermediate thread task. Once the thread task has completed a turn, `/forkgroup` uses its latest locally persisted completed turn. A newer active turn does not block the command and is excluded from the fork point.
 
+The new group's welcome message reports the persisted fork settings: model, reasoning effort, and permission type. Permission type is rendered as automatic execution or confirmation before execution.
+
 ## Turn And Message Behavior
 
 - Plain text creates a task when the route has no current task.
@@ -188,6 +198,7 @@ Starting a Feishu thread from a mapped user message, progress card, or final res
 - A steering race at turn completion becomes the next queued request.
 - `/nosteer` always creates a persistent FIFO queue item.
 - Queue card actions can cancel individual pending items.
+- Exact slash command names take priority. Otherwise, a unique command-name prefix or registered compound-command initialism is expanded before argument parsing; ambiguous matches are rejected with their candidate commands. Registered initialisms are `fg` for `forkgroup`, `ng` for `newgroup`, and `ns` for `nosteer`.
 - Unknown slash commands are rejected and never forwarded as Prompts.
 
 Each turn owns one progress card. Normal updates are throttled to one every two seconds; critical updates have a 500 ms minimum gap. On completion, Agent Bot updates the progress card to a terminal state before sending a separate final Markdown message.
@@ -200,6 +211,8 @@ Incoming rich-text images are downloaded into the inbound image cache and passed
 
 `/sessions` reads Codex tasks through `thread/list` and can discover tasks created by Codex Desktop, CLI, Agent Bot, or another App Server client under the same `CODEX_HOME`.
 
+Each task entry exposes `NewGroup` and `ForkGroup` callbacks. The callback payload keeps the selected task ID and source context, while the Lark operator `open_id` is used to invite the user to the new group. `NewGroup` resolves the selected task's project and execution settings; `ForkGroup` resolves its latest available completed turn.
+
 Agent Bot keeps a local routing key for Feishu cards and delivery state, but presents the Codex task ID to users. It does not resume, steer, stop, or fork externally running Codex work without an explicit user action.
 
 Project behavior:

package/docs/technical-reference.zh.md

@@ -35,7 +35,7 @@ Agent Bot 是基于 Node.js 22+、ESM 和 TypeScript 的应用，主要组件如
 
 CLI 还支持显式指定目录的 Profile。不使用 `--profile` 时，命令使用主 Profile 以及原有的环境变量路径规则。`--profile <目录>` 会为当前命令及其启动的 Supervisor、Worker 固定 `AGENT_BOT_HOME` 和 `AGENT_BOT_CONFIG`，配置文件固定为 `<目录>/config.yaml`。它还会先清除继承的飞书凭据环境变量，再加载所选 Profile 的 `.env`，避免从主 Agent Bot 进程树中启动辅助实例时误用主机器人的凭据。`--profile` 不能和 `--config` 同时使用。其他 Profile 必须在每次命令中显式选择；Agent Bot 不维护按名称注册的 Profile。
 
-CLI 界面文本不受系统语言影响，统一使用英文。系统生成的重启原因仍使用中文，因为它会显示在中文 Lark 状态卡中；显式传入的 `--reason` 保持原样。`agent-bot server status` 会报告运行中 Worker 的 Lark App ID，JSON 字段名为 `feishuAppId`；服务停止或旧版健康协议尚未提供该字段时，CLI 会回退到当前 Profile 配置的 App ID。
+CLI 通过 Node.js 国际化能力读取系统 Locale。以 `zh` 开头的 Locale 使用中文界面；英文及所有未支持 Locale 使用英文。帮助、状态、进度、交互提示和 CLI 自身错误都遵循此规则；JSON 字段名及枚举值不做本地化。系统生成的重启原因仍使用中文，因为它会显示在中文 Lark 状态卡中；显式传入的 `--reason` 保持原样。`agent-bot server status` 会报告运行中 Worker 的 Lark App ID，JSON 字段名为 `feishuAppId`；服务停止或旧版健康协议尚未提供该字段时，CLI 会回退到当前 Profile 配置的 App ID。
 
 | 默认路径                             | 内容                 |
 | ------------------------------------ | -------------------- |
@@ -75,9 +75,17 @@ CLI 界面文本不受系统语言影响，统一使用英文。系统生成的
 
 缺失配置分两阶段处理：
 
-1. 请求核心配置并轮询，直到基础能力生效
+1. 请求核心配置并轮询，直到基础能力生效；需要手动配置的全部群消息权限允许用户输入 `Y` 显式跳过
 2. 请求其余可选配置。CLI 会先显示二维码，随后显示授权链接，然后立即开始最多 5 分钟的轮询。交互式终端只提供 `Y` 选项，用于跳过可选授权并继续；否则用户直接在浏览器中完成授权，轮询会持续进行
 
+一键配置支持的内容会编码到 launcher 的 `addons` 清单中。核心权限 `im:message.group_msg` 不会放入该清单，因为飞书无法通过一键配置新增它。CLI 会改为显示二维码，以及当前应用已筛选该权限的开发者后台直达链接：
+
+```text
+https://open.feishu.cn/app/<appId>/auth?q=im%3Amessage.group_msg&op_from=openapi&token_type=tenant
+```
+
+用户需要手动新增权限、发布应用版本，并在需要时完成租户管理员审批。核心轮询会在已发布版本中检测到该权限后继续初始化。交互式终端中输入 `Y` 只会跳过这个手动权限的等待，其他缺失的核心权限和消息事件仍会阻塞。初始化会返回部分配置结果，并提示机器人无法响应未 @ 它的普通群消息。
+
 可选配置轮询失败或超时会返回部分配置结果，不会导致初始化失败。stdin 不是交互式终端时无法输入跳过指令，轮询会持续到配置生效或超时。验证链接和提示写入 stderr，因此 `--json` 的最终 stdout 仍可直接供程序读取。
 
 生成的授权链接不包含 App Secret。
@@ -93,7 +101,7 @@ CLI 界面文本不受系统语言影响，统一使用英文。系统生成的
 - 机器人能力
 - 长连接事件接收
 - `im.message.receive_v1`
-- `im:message.group_msg:readonly`，用于接收机器人所在群内的全部用户消息
+- `im:message.group_msg`，用于接收机器人所在群内的全部用户消息
 - 接收私聊消息所需的租户权限
 - `im:message:send_as_bot` 或覆盖它的更大权限
 - `application:application:self_manage`，供初始化检查已发布版本
@@ -181,6 +189,8 @@ AGENT_BOT=1
 
 `/forkgroup` 会根据话题状态选择来源。话题尚未绑定任务，或者已绑定任务但尚未完成过自己的 turn 时，直接从话题原始锚点 turn fork，不创建中间话题任务。话题任务完成过 turn 后，使用本地持久化的最近完成 turn；更晚的执行中 turn 不会阻塞命令，也不会成为 fork 点。
 
+新群欢迎消息会显示分支任务持久化后的模型、思考强度和权限类型；权限类型显示为自动执行或执行前确认。
+
 ## Turn 与消息行为
 
 - 路由没有当前任务时，普通文本会自动创建任务
@@ -188,6 +198,7 @@ AGENT_BOT=1
 - Steering 与 turn 完成发生竞态时，文字变为下一条排队请求
 - `/nosteer` 始终创建持久化 FIFO 队列项
 - 队列卡操作可以取消单个待执行项
+- 完整斜杠命令名优先；否则在解析参数前展开唯一的命令名前缀或已登记的复合命令首字母缩写，匹配多个命令时会拒绝并列出候选命令。当前缩写为 `fg` → `forkgroup`、`ng` → `newgroup`、`ns` → `nosteer`
 - 未知斜杠命令会被拒绝，不会作为 Prompt 转发
 
 每个 turn 只有一张进度卡。普通更新最多每两秒一次，关键更新最短间隔 500 毫秒。完成时先把进度卡更新为终态，再单独发送 Markdown 最终回答。
@@ -200,6 +211,8 @@ AGENT_BOT=1
 
 `/sessions` 通过 `thread/list` 读取 Codex 任务，可发现同一 `CODEX_HOME` 下由 Codex Desktop、CLI、Agent Bot 或其他 App Server 客户端创建的任务。
 
+每个任务条目都提供 `NewGroup` 和 `ForkGroup` 回调。回调数据保留所选任务 ID 与来源上下文，并使用飞书操作者的 `open_id` 邀请用户进入新群。`NewGroup` 解析所选任务的项目和执行设置；`ForkGroup` 解析该任务最新可用的已完成 turn。
+
 Agent Bot 内部保留本地路由键以关联飞书卡片和投递状态，但对用户展示 Codex 任务 ID。没有明确用户操作时，不会续写、steer、停止或分支其他客户端正在运行的 Codex 工作。
 
 项目规则：

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@keyou007/agent-bot",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@keyou007/agent-bot",
-      "version": "0.1.8",
+      "version": "0.1.10",
       "license": "GPL-3.0-only",
       "dependencies": {
         "@agentclientprotocol/sdk": "1.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keyou007/agent-bot",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "description": "Using Codex in Lark/Feishu feels just like using native Codex.",
   "license": "GPL-3.0-only",

package/skills/agent-bot/SKILL.md

@@ -46,15 +46,15 @@ Run initialization once after installing or linking the CLI:
 agent-bot init
 ```
 
-Initialization creates the Agent Bot home, `config.yaml`, `.env`, `data/`, and `logs/` from the bundled examples. If Feishu credentials are absent, it starts Feishu one-click app registration, prints a QR code followed by its authorization URL, waits for the user to approve the request, and stores the returned app ID and secret in `.env`. It then audits the app's currently published tenant permissions, event subscriptions, and callbacks. Core and optional missing items produce separate incremental-configuration URLs. Core configuration is always polled until ready. For optional configuration, the CLI prints the QR code followed by the authorization URL and immediately waits up to five minutes for activation. The only terminal choice is `Y`, which skips optional authorization and continues initialization.
+Initialization creates the Agent Bot home, `config.yaml`, `.env`, `data/`, and `logs/` from the bundled examples. If Feishu credentials are absent, it starts Feishu one-click app registration, prints a QR code followed by its authorization URL, waits for the user to approve the request, and stores the returned app ID and secret in `.env`. It then audits the app's currently published tenant permissions, event subscriptions, and callbacks. Core and optional missing items produce separate configuration challenges. Core configuration is polled until ready, except that the manually configured all-group-message permission may be explicitly skipped with `Y`. For optional configuration, the CLI prints the QR code followed by the authorization URL and immediately waits up to five minutes for activation. The only terminal choice is also `Y`, which skips optional authorization and continues initialization.
 
-Core messaging configuration includes `im:message.group_msg:readonly`, not merely the narrower group-mention scope. Agent Bot groups accept ordinary messages without requiring users to @ the bot, so initialization must keep waiting until all-user group-message delivery is active.
+Core messaging configuration includes `im:message.group_msg`, not merely the narrower group-mention scope. Accept `im:message.group_msg:readonly` when an existing app version reports that alias. Feishu cannot add `im:message.group_msg` through the one-click launcher, so Agent Bot excludes it from `addons` and prints a QR code plus a direct filtered Developer Console permission-page URL. The user should add the permission manually, publish the app version, and complete tenant approval if required. Entering `Y` skips only this permission wait and continues with a partial configuration; the bot then cannot respond to ordinary group messages that do not mention it.
 
 Initialization always requests all-user group-message delivery. The runtime option `feishu.respondToAllGroupMessages` controls whether Agent Bot uses it: the default `true` responds to ordinary group messages, while `false` requires a mention of the current bot. Private messages are unaffected.
 
 After Feishu initialization succeeds, `init` releases its initialization lock and automatically starts the selected profile's server, waiting until it is ready. It does not create another supervisor when that profile is already running. `init --skip-feishu` is the exception: it prepares Console-only files and does not start the server. With `--json`, inspect `server.status` for `started`, `already-running`, or `skipped`.
 
-When running `init` on the user's behalf, relay every exact authorization or incremental-configuration URL and let the user complete it in their own browser. Optional polling starts automatically after the link is shown. Do not enter `Y` unless the user explicitly asks to skip optional authorization; there is no separate accept action. Optional capabilities such as group creation, group-title synchronization, reactions, images, and card actions never block initialization when skipped, timed out, or still unavailable; relay the final affected-feature warnings. In a non-interactive terminal, optional polling continues until activation or timeout because skip input is unavailable. Neither URL contains the app secret, and the secret itself is never printed.
+When running `init` on the user's behalf, relay every exact authorization, incremental-configuration, and manual permission-page URL and let the user complete it in their own browser. For `im:message.group_msg`, explicitly tell the user to add the filtered permission and publish the app version, or offer to enter `Y` when they intentionally accept mention-only group behavior. Optional polling starts automatically after the link is shown. Do not enter `Y` for either prompt unless the user explicitly asks to skip; there is no separate accept action. Optional capabilities such as group creation, group-title synchronization, reactions, images, and card actions never block initialization when skipped, timed out, or still unavailable; relay the final affected-feature warnings. In a non-interactive terminal, skip input is unavailable. None of the URLs contains the app secret, and the secret itself is never printed.
 
 Existing complete Feishu credentials are preserved but still audited and repaired when needed. Missing or incomplete credentials mean app creation did not complete, so a later `init` starts a new registration instead of resuming the previous device code. Once both credentials are durably saved, an interrupted permission audit resumes against the same remote app. `init` also holds a local lock to prevent concurrent registrations. Use `agent-bot init --skip-feishu` only for console-only initialization because it skips both registration and configuration auditing. Use `agent-bot init --reconfigure-feishu` only when the user explicitly wants to replace existing complete credentials. The command respects `AGENT_BOT_HOME`, `AGENT_BOT_CONFIG`, and `--config <path>`. Use `agent-bot init --json` when structured final output helps.
 
@@ -80,7 +80,7 @@ agent-bot server status
 agent-bot task list
 ```
 
-All Agent Bot CLI interface text is English regardless of system locale. `agent-bot server status` also reports the running profile's Lark App ID; with `--json`, read it from `feishuAppId`.
+Agent Bot CLI interface text follows the system locale: locales beginning with `zh` use Chinese, while English and unsupported locales use English. JSON output is not localized. `agent-bot server status` also reports the running profile's Lark App ID; with `--json`, read it from `feishuAppId`.
 
 Add `--json` to status and list commands when machine-readable output helps. If `agent-bot` is unavailable, report that the CLI is not installed or linked instead of guessing process state.
 
@@ -139,11 +139,11 @@ Use `/newgroup [title]` in Feishu to create a private group named `[agent] [proj
 
 Group names created by `/newgroup` and `/forkgroup` are capped at 60 displayed characters. When the generated name would exceed that limit, truncate only the title portion in the Feishu group name; preserve the underlying Agent Bot task title.
 
-Use `/forkgroup [title]` in Feishu to fork the current position into a newly created private group. In a Feishu thread, use the thread's original anchor turn when the thread has no bound task or its bound task has not completed a turn of its own. Once the bound thread task has completed a turn, use its latest locally persisted completed turn; exclude any newer active turn without interrupting it. Resolve this source before generic thread initialization so an unbound thread does not create an intermediate task. Outside a thread, fork the current Codex task's latest available completed turn. Agent Bot invites the command sender and binds the fork as the new group's current task, but does not automatically send a Sessions or Status card there. An explicit title is used directly. Without an explicit title, both the forked task and group name use the same persistent `source title（分支 N）` sequence as `/fork`. `/forkgroup` does not add a date suffix.
+Use `/forkgroup [title]` in Feishu to fork the current position into a newly created private group. In a Feishu thread, use the thread's original anchor turn when the thread has no bound task or its bound task has not completed a turn of its own. Once the bound thread task has completed a turn, use its latest locally persisted completed turn; exclude any newer active turn without interrupting it. Resolve this source before generic thread initialization so an unbound thread does not create an intermediate task. Outside a thread, fork the current Codex task's latest available completed turn. Agent Bot invites the command sender and binds the fork as the new group's current task, but does not automatically send a Sessions or Status card there. The new-group welcome message reports the forked task's model, reasoning effort, and permission type. An explicit title is used directly. Without an explicit title, both the forked task and group name use the same persistent `source title（分支 N）` sequence as `/fork`. `/forkgroup` does not add a date suffix.
 
 Use `/new [title] --nodir` to force a new Codex Projectless task even when the current task belongs to a project. `--nodir` and `--dir <cwd>` are mutually exclusive; omitting both preserves the normal project-shape inheritance behavior.
 
-Every task in the Feishu `/sessions` card has a `New` action. It inherits the source task's project directory, model, reasoning effort, and permission mode, creates a new task, and switches the current chat to it without stopping or forking the source task.
+Every task in the Feishu `/sessions` card has `New`, `NewGroup`, `Fork`, and `ForkGroup` actions. `New` inherits the source task's project directory, model, reasoning effort, and permission mode, creates a new task, and switches the current chat to it without stopping or forking the source task. `NewGroup` applies the same inheritance in a newly created private group. `Fork` switches the current chat to a branch, while `ForkGroup` binds the branch to a newly created private group; both fork actions use the selected task's latest available completed turn without interrupting an active turn.
 
 Use `/fork [number-or-task-id]` in Feishu to branch from the current or specified Codex task and switch to the new branch. If the source task is running, Agent Bot forks from its latest completed turn and leaves the active turn running; it rejects only when the task has no completed turn yet.
 
@@ -153,7 +153,7 @@ Use `/model` in Feishu to show an interactive Card 2.0 model selector for the cu
 
 Keep action labels placed to the right of card content or at the bottom of a card in English. Buttons above the main card content, such as activity-history navigation, may remain in Chinese.
 
-Messages whose trimmed text starts with `/` are always parsed as Agent Bot commands. Unknown slash commands are reported to the user with a `/help` hint and must never fall through to the model, including slash-prefixed messages that also contain images.
+Messages whose trimmed text starts with `/` are always parsed as Agent Bot commands. Command names accept unique prefixes, such as `/sess` for `/sessions`. Compound commands also accept registered initialisms: `/fg` for `/forkgroup`, `/ng` for `/newgroup`, and `/ns` for `/nosteer`. Exact command names take priority; ambiguous matches are rejected and list every matching command. Unknown slash commands are reported to the user with a `/help` hint and must never fall through to the model, including slash-prefixed messages that also contain images.
 
 When a group body has a current task, renaming the Feishu group to `[agent-name] [project directory] new title` also renames that current task if the Agent prefix matches the task's configured agent. Only `new title` is written to the task; the Agent and project-directory prefixes remain group metadata. The older `[agent-name] new title` shape remains supported. Malformed names, agent mismatches, empty groups, and thread-specific tasks are ignored.
 

package/src/cli/FeishuAppConfiguration.ts

@@ -1,5 +1,6 @@
 import { gzipSync } from "node:zlib";
 import type { FeishuAppCredentials } from "./FeishuAppRegistration.js";
+import { cliText } from "./i18n.js";
 
 const FEISHU_OPEN_BASE_URL = "https://open.feishu.cn";
 const TENANT_TOKEN_PATH = "/open-apis/auth/v3/tenant_access_token/internal";
@@ -28,10 +29,10 @@ const REQUIRED_SCOPE_REQUIREMENTS: ScopeRequirement[] = [
     accepted: ["im:chat:read", "im:chat:readonly", "im:chat"],
   },
   {
-    requested: "im:message.group_msg:readonly",
+    requested: "im:message.group_msg",
     accepted: [
-      "im:message.group_msg:readonly",
       "im:message.group_msg",
+      "im:message.group_msg:readonly",
     ],
   },
   {
@@ -66,11 +67,12 @@ export const REQUIRED_FEISHU_CALLBACKS = ["card.action.trigger"] as const;
 
 const CORE_FEISHU_SCOPES = new Set([
   "application:application:self_manage",
-  "im:message.group_msg:readonly",
+  "im:message.group_msg",
   "im:message.p2p_msg:readonly",
   "im:message:send_as_bot",
 ]);
 const CORE_FEISHU_EVENTS = new Set<string>(["im.message.receive_v1"]);
+const MANUAL_FEISHU_SCOPES = new Set(["im:message.group_msg"]);
 
 export interface FeishuAppConfiguration {
   scopes: string[];
@@ -85,6 +87,7 @@ export interface MissingFeishuAppConfiguration {
 }
 
 export interface FeishuConfigurationChallenge {
+  kind: "launcher" | "manual_scope";
   verificationUrl: string;
   missing: MissingFeishuAppConfiguration;
   blocking: boolean;
@@ -94,6 +97,7 @@ export interface EnsureFeishuAppConfigurationOptions {
   fetch?: typeof globalThis.fetch;
   sleep?: (milliseconds: number) => Promise<void>;
   signal?: AbortSignal;
+  manualPermissionSkipSignal?: AbortSignal;
   optionalSkipSignal?: AbortSignal;
   pollIntervalMs?: number;
   timeoutMs?: number;
@@ -157,15 +161,27 @@ export async function ensureFeishuAppConfiguration(
 
   let remainingMs = timeoutMs;
   let lastError: unknown;
+  let refreshImmediately = options.manualPermissionSkipSignal?.aborted === true;
   while (remainingMs > 0) {
     const waitMs = Math.min(pollIntervalMs, remainingMs);
-    await sleepWithAbort(sleep, waitMs, options.signal);
-    remainingMs -= waitMs;
+    if (!refreshImmediately) {
+      const waitResult = options.manualPermissionSkipSignal?.aborted
+        ? await sleepWithAbort(sleep, waitMs, options.signal).then(() => "elapsed" as const)
+        : await sleepWithOptionalSkip(
+            sleep,
+            waitMs,
+            options.signal,
+            options.manualPermissionSkipSignal,
+          );
+      if (waitResult === "elapsed") remainingMs -= waitMs;
+    }
+    refreshImmediately = false;
 
     try {
       configuration = await readFeishuAppConfiguration(credentials, fetchImpl, options.signal);
       const remaining = missingFeishuAppConfiguration(configuration);
-      if (!hasMissingConfiguration(coreMissingFeishuAppConfiguration(remaining))) {
+      const unresolvedCore = coreMissingFeishuAppConfiguration(remaining);
+      if (!hasBlockingCoreConfiguration(unresolvedCore, options.manualPermissionSkipSignal)) {
         return completeOptionalFeishuConfiguration(
           credentials,
           configuration,
@@ -175,17 +191,40 @@ export async function ensureFeishuAppConfiguration(
           pollIntervalMs,
           optionalTimeoutMs,
           options,
+          skippedManualScopes(coreMissing, options.manualPermissionSkipSignal),
         );
       }
       lastError = undefined;
     } catch (error) {
       if (options.signal?.aborted) throw abortError(options.signal);
+      const knownRemaining = missingFeishuAppConfiguration(configuration);
+      if (!hasBlockingCoreConfiguration(
+        coreMissingFeishuAppConfiguration(knownRemaining),
+        options.manualPermissionSkipSignal,
+      )) {
+        return completeOptionalFeishuConfiguration(
+          credentials,
+          configuration,
+          missing,
+          fetchImpl,
+          sleep,
+          pollIntervalMs,
+          optionalTimeoutMs,
+          options,
+          skippedManualScopes(coreMissing, options.manualPermissionSkipSignal),
+        );
+      }
       lastError = error;
     }
   }
 
-  const detail = lastError instanceof Error ? ` Last check failed: ${lastError.message}` : "";
-  throw new Error(`Timed out waiting for the core Lark scopes and message event. Run agent-bot init again.${detail}`);
+  const detail = lastError instanceof Error
+    ? cliText(` Last check failed: ${lastError.message}`, ` 上次检查失败：${lastError.message}`)
+    : "";
+  throw new Error(cliText(
+    `Timed out waiting for the core Lark scopes and message event. Run agent-bot init again.${detail}`,
+    `等待飞书核心权限和消息事件超时。请重新运行 agent-bot init。${detail}`,
+  ));
 }
 
 async function requestMissingFeishuConfiguration(
@@ -194,8 +233,28 @@ async function requestMissingFeishuConfiguration(
   blocking: boolean,
   onVerification: EnsureFeishuAppConfigurationOptions["onVerification"],
 ): Promise<void> {
-  const verificationUrl = buildFeishuConfigurationUrl(appId, missing);
-  await onVerification?.({ verificationUrl, missing, blocking });
+  const launcherMissing: MissingFeishuAppConfiguration = {
+    scopes: missing.scopes.filter((scope) => !MANUAL_FEISHU_SCOPES.has(scope)),
+    events: missing.events,
+    callbacks: missing.callbacks,
+  };
+  if (hasMissingConfiguration(launcherMissing)) {
+    await onVerification?.({
+      kind: "launcher",
+      verificationUrl: buildFeishuConfigurationUrl(appId, launcherMissing),
+      missing: launcherMissing,
+      blocking,
+    });
+  }
+
+  for (const scope of missing.scopes.filter((value) => MANUAL_FEISHU_SCOPES.has(value))) {
+    await onVerification?.({
+      kind: "manual_scope",
+      verificationUrl: buildFeishuPermissionManagementUrl(appId, scope),
+      missing: { scopes: [scope], events: [], callbacks: [] },
+      blocking,
+    });
+  }
 }
 
 async function completeOptionalFeishuConfiguration(
@@ -207,13 +266,15 @@ async function completeOptionalFeishuConfiguration(
   pollIntervalMs: number,
   timeoutMs: number,
   options: EnsureFeishuAppConfigurationOptions,
+  ignoredScopes: ReadonlySet<string> = new Set(),
 ): Promise<EnsureFeishuAppConfigurationResult> {
   let configuration = initialConfiguration;
   let remaining = missingFeishuAppConfiguration(configuration);
-  if (hasMissingConfiguration(remaining)) {
+  const requested = withoutIgnoredScopes(remaining, ignoredScopes);
+  if (hasMissingConfiguration(requested)) {
     await requestMissingFeishuConfiguration(
       credentials.appId,
-      remaining,
+      requested,
       false,
       options.onVerification,
     );
@@ -227,6 +288,7 @@ async function completeOptionalFeishuConfiguration(
         timeoutMs,
         options.signal,
         options.optionalSkipSignal,
+        ignoredScopes,
       );
       configuration = completed.configuration;
       remaining = completed.remaining;
@@ -249,6 +311,7 @@ async function waitForOptionalFeishuConfiguration(
   timeoutMs: number,
   signal?: AbortSignal,
   optionalSkipSignal?: AbortSignal,
+  ignoredScopes: ReadonlySet<string> = new Set(),
 ): Promise<{
   configuration: FeishuAppConfiguration;
   remaining: MissingFeishuAppConfiguration;
@@ -256,7 +319,7 @@ async function waitForOptionalFeishuConfiguration(
   let configuration = initialConfiguration;
   let remaining = missingFeishuAppConfiguration(configuration);
   let remainingMs = timeoutMs;
-  while (remainingMs > 0 && hasMissingConfiguration(remaining)) {
+  while (remainingMs > 0 && hasMissingConfiguration(withoutIgnoredScopes(remaining, ignoredScopes))) {
     if (optionalSkipSignal?.aborted) break;
     const waitMs = Math.min(pollIntervalMs, remainingMs);
     const waitResult = await sleepWithOptionalSkip(
@@ -346,6 +409,14 @@ export function buildFeishuConfigurationUrl(appId: string, missing: MissingFeish
   return url.toString();
 }
 
+export function buildFeishuPermissionManagementUrl(appId: string, scope: string): string {
+  const url = new URL(`/app/${encodeURIComponent(appId)}/auth`, FEISHU_OPEN_BASE_URL);
+  url.searchParams.set("q", scope);
+  url.searchParams.set("op_from", "openapi");
+  url.searchParams.set("token_type", "tenant");
+  return url.toString();
+}
+
 async function readFeishuAppConfiguration(
   credentials: FeishuAppCredentials,
   fetchImpl: typeof globalThis.fetch,
@@ -360,14 +431,14 @@ async function readFeishuAppConfiguration(
       `${FEISHU_OPEN_BASE_URL}${APPLICATION_PATH_PREFIX}/${appId}?lang=zh_cn`,
       { headers },
       signal,
-      "Read Lark app configuration",
+      cliText("Read Lark app configuration", "读取飞书应用配置"),
     ),
     fetchJson(
       fetchImpl,
       `${FEISHU_OPEN_BASE_URL}${APPLICATION_PATH_PREFIX}/${appId}/app_versions?lang=zh_cn&page_size=2`,
       { headers },
       signal,
-      "Read Lark app versions",
+      cliText("Read Lark app versions", "读取飞书应用版本"),
     ),
   ]);
 
@@ -415,10 +486,13 @@ async function getTenantAccessToken(
       }),
     },
     signal,
-    "Get the Lark tenant_access_token",
+    cliText("Get the Lark tenant_access_token", "获取飞书 tenant_access_token"),
   );
   const token = readString(payload, "tenant_access_token");
-  if (!token) throw new Error("The Lark tenant_access_token response is missing the access token.");
+  if (!token) throw new Error(cliText(
+    "The Lark tenant_access_token response is missing the access token.",
+    "飞书 tenant_access_token 响应中缺少访问令牌。",
+  ));
   return token;
 }
 
@@ -439,12 +513,18 @@ async function fetchJson(
     const response = await fetchImpl(url, { ...init, signal: controller.signal });
     const payload = (await response.json().catch(() => undefined)) as unknown;
     if (!isJsonObject(payload)) {
-      throw new Error(`${operation} returned an invalid response (HTTP ${response.status}).`);
+      throw new Error(cliText(
+        `${operation} returned an invalid response (HTTP ${response.status}).`,
+        `${operation}返回了无效响应（HTTP ${response.status}）。`,
+      ));
     }
     const code = readNumber(payload, "code");
     if (!response.ok || code !== 0) {
       throw new FeishuConfigurationApiError(
-        `${operation} failed: ${readString(payload, "msg") || response.statusText || `HTTP ${response.status}`}`,
+        cliText(
+          `${operation} failed: ${readString(payload, "msg") || response.statusText || `HTTP ${response.status}`}`,
+          `${operation}失败：${readString(payload, "msg") || response.statusText || `HTTP ${response.status}`}`,
+        ),
         code,
         response.status,
       );
@@ -452,7 +532,10 @@ async function fetchJson(
     return payload;
   } catch (error) {
     if (parentSignal?.aborted) throw abortError(parentSignal);
-    if (controller.signal.aborted) throw new Error(`${operation} timed out.`);
+    if (controller.signal.aborted) throw new Error(cliText(
+      `${operation} timed out.`,
+      `${operation}超时。`,
+    ));
     throw error;
   } finally {
     clearTimeout(timeout);
@@ -484,6 +567,33 @@ function hasMissingConfiguration(missing: MissingFeishuAppConfiguration): boolea
   return missing.scopes.length > 0 || missing.events.length > 0 || missing.callbacks.length > 0;
 }
 
+function hasBlockingCoreConfiguration(
+  missing: MissingFeishuAppConfiguration,
+  manualPermissionSkipSignal?: AbortSignal,
+): boolean {
+  if (!manualPermissionSkipSignal?.aborted) return hasMissingConfiguration(missing);
+  return hasMissingConfiguration(withoutIgnoredScopes(missing, MANUAL_FEISHU_SCOPES));
+}
+
+function skippedManualScopes(
+  initialCoreMissing: MissingFeishuAppConfiguration,
+  manualPermissionSkipSignal?: AbortSignal,
+): ReadonlySet<string> {
+  if (!manualPermissionSkipSignal?.aborted) return new Set();
+  return new Set(initialCoreMissing.scopes.filter((scope) => MANUAL_FEISHU_SCOPES.has(scope)));
+}
+
+function withoutIgnoredScopes(
+  missing: MissingFeishuAppConfiguration,
+  ignoredScopes: ReadonlySet<string>,
+): MissingFeishuAppConfiguration {
+  return {
+    scopes: missing.scopes.filter((scope) => !ignoredScopes.has(scope)),
+    events: missing.events,
+    callbacks: missing.callbacks,
+  };
+}
+
 function coreMissingFeishuAppConfiguration(missing: MissingFeishuAppConfiguration): MissingFeishuAppConfiguration {
   return {
     scopes: missing.scopes.filter((scope) => CORE_FEISHU_SCOPES.has(scope)),
@@ -554,7 +664,9 @@ function positiveInteger(value: number | undefined): number | undefined {
 }
 
 function abortError(signal: AbortSignal): Error {
-  return signal.reason instanceof Error ? signal.reason : new Error("Lark app configuration was cancelled.");
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new Error(cliText("Lark app configuration was cancelled.", "飞书应用配置已取消。"));
 }
 
 function delay(milliseconds: number): Promise<void> {

package/src/cli/FeishuAppRegistration.ts

@@ -41,12 +41,15 @@ export async function registerFeishuApp(options: FeishuAppRegistrationOptions =
     },
     options.signal,
   );
-  throwRegistrationError(begin, "Could not start Lark app creation");
+  throwRegistrationError(begin, cliText("Could not start Lark app creation", "无法开始创建飞书应用"));
 
   const deviceCode = readString(begin, "device_code");
   const userCode = readString(begin, "user_code");
   if (!deviceCode || !userCode) {
-    throw new Error("The Lark app creation response is missing device_code or user_code.");
+    throw new Error(cliText(
+      "The Lark app creation response is missing device_code or user_code.",
+      "飞书应用创建响应中缺少 device_code 或 user_code。",
+    ));
   }
 
   const expiresIn =
@@ -113,16 +116,22 @@ export async function registerFeishuApp(options: FeishuAppRegistrationOptions =
         intervalSeconds = Math.min(intervalSeconds + 5, MAX_POLL_INTERVAL_SECONDS);
         continue;
       case "access_denied":
-        throw new Error("Lark app creation was cancelled.");
+        throw new Error(cliText("Lark app creation was cancelled.", "飞书应用创建已取消。"));
       case "expired_token":
       case "invalid_grant":
-        throw new Error("The Lark app creation link expired. Run agent-bot init again.");
+        throw new Error(cliText(
+          "The Lark app creation link expired. Run agent-bot init again.",
+          "飞书应用创建链接已过期，请重新运行 agent-bot init。",
+        ));
       default:
-        throwRegistrationError(payload, "Lark app creation failed");
+        throwRegistrationError(payload, cliText("Lark app creation failed", "飞书应用创建失败"));
     }
   }
 
-  throw new Error("Timed out waiting for Lark app creation. Run agent-bot init again.");
+  throw new Error(cliText(
+    "Timed out waiting for Lark app creation. Run agent-bot init again.",
+    "等待飞书应用创建超时，请重新运行 agent-bot init。",
+  ));
 }
 
 function buildVerificationUrl(userCode: string): string {
@@ -152,7 +161,10 @@ async function postRegistration(
     });
     const payload = (await response.json().catch(() => undefined)) as unknown;
     if (!isRecord(payload)) {
-      throw new Error(`The Lark app registration endpoint returned an invalid response (HTTP ${response.status}).`);
+      throw new Error(cliText(
+        `The Lark app registration endpoint returned an invalid response (HTTP ${response.status}).`,
+        `飞书应用注册接口返回了无效响应（HTTP ${response.status}）。`,
+      ));
     }
     return payload;
   } finally {
@@ -165,7 +177,7 @@ function throwRegistrationError(payload: RegistrationPayload, prefix: string): v
   const code = readString(payload, "error");
   if (!code) return;
   const description = readString(payload, "error_description") || code;
-  throw new Error(`${prefix}: ${description}`);
+  throw new Error(`${prefix}${cliText(": ", "：")}${description}`);
 }
 
 function readString(value: RegistrationPayload, key: string): string {
@@ -189,7 +201,9 @@ function isRecord(value: unknown): value is RegistrationPayload {
 }
 
 function abortError(signal: AbortSignal): Error {
-  return signal.reason instanceof Error ? signal.reason : new Error("Lark app creation was cancelled.");
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new Error(cliText("Lark app creation was cancelled.", "飞书应用创建已取消。"));
 }
 
 function delay(milliseconds: number): Promise<void> {
@@ -218,3 +232,4 @@ async function sleepWithAbort(
     if (onAbort) signal.removeEventListener("abort", onAbort);
   }
 }
+import { cliText } from "./i18n.js";