sintbot 1.4.16 → 1.4.17

package/CHANGELOG.en.json

@@ -1,4 +1,35 @@
 [
+  {
+    "version": "1.4.17",
+    "date": "2026-11-12",
+    "name": "Feishu scan-to-connect and third-party quotas",
+    "items": [
+      {
+        "t": "Connect Feishu with one scan",
+        "d": "New command sintbot connect: scan a QR code in the Feishu app to create the bot app; SintBot self-checks, opens the contact and availability scope and publishes, creates ~/Projects/<name>, creates a group with you in it, writes the configuration and initializes journals. On failure it stops at that step and tells you how to resume (--app-id, --chat); non-admins in a company organization can use --basic. The manual path remains."
+      },
+      {
+        "t": "Simpler Feishu settings",
+        "d": "Connection status and project groups come first. New users get a three-step scan setup guide; manual setup and app details are folded away. Console administrator sign-in is separate."
+      },
+      {
+        "t": "Third-party quota and balance",
+        "d": "GLM shows the 5-hour and weekly windows and falls back to the balance without a plan; MiniMax shows the 5-hour and weekly windows; DeepSeek shows the balance. Invalid credentials are shown as such; transient failures keep the last value for 10 minutes."
+      },
+      {
+        "t": "Claude subscription quota fallback",
+        "d": "When the Claude Code login token has expired, the CLI refreshes it itself and SintBot reads its cached quota instead of showing \"unverified\"; read-only, never refreshing on its own, never blocking group commands or the console."
+      },
+      {
+        "t": "Environment conflict check",
+        "d": "Preflight and the console model cards list environment variables and ~/.claude/settings.json or ~/.codex/config.toml settings that would reroute Claude Code or Codex; key names only, warnings only."
+      },
+      {
+        "t": "Built-in core ABI 36",
+        "d": "Connect decisions and wording, QR encoding, quota parsing and environment checks live in the built-in core; the core build pins its toolchain and no longer depends on the crate mirror used by the builder."
+      }
+    ]
+  },
   {
     "version": "1.4.16",
     "date": "2026-11-11",

package/CHANGELOG.json

@@ -1,4 +1,35 @@
 [
+  {
+    "version": "1.4.17",
+    "date": "2026-11-12",
+    "name": "飞书扫码接入与第三方额度",
+    "items": [
+      {
+        "t": "扫码一键接入飞书",
+        "d": "新命令 sintbot connect：手机飞书扫码即创建机器人应用，自动自检、放开通讯录与可用范围并发版，新建项目目录 ~/Projects/<项目名>，建群并拉你进群，写入配置并初始化日志。失败时按步骤停下并给出续做方式（--app-id、--chat）；公司组织里的非管理员可用 --basic。手动接入流程保留。"
+      },
+      {
+        "t": "飞书设置按使用流程整理",
+        "d": "优先查看连接状态和管理项目群；新用户按扫码、自动建群、群里发任务三步开始。手动接入与应用信息收进高级说明，管理员和控制台登录单独设置。"
+      },
+      {
+        "t": "第三方额度与余额",
+        "d": "GLM 显示 5 小时 / 周配额窗口，没有套餐时退回查余额；MiniMax 显示 5 小时与周窗口；DeepSeek 余额。凭据失效会明确显示，瞬时故障保留上次结果 10 分钟。"
+      },
+      {
+        "t": "Claude 登录额度兜底",
+        "d": "Claude Code 登录令牌过期时，由 CLI 自行刷新并读取其缓存的额度，不再显示「未验证」；只读不代刷，不阻塞群命令和控制台。"
+      },
+      {
+        "t": "环境冲突检查",
+        "d": "预检与控制台模型卡列出会改道 Claude Code / Codex 的环境变量和 ~/.claude/settings.json、~/.codex/config.toml 设置，只列键名，只提示不修改。"
+      },
+      {
+        "t": "内置核心 ABI 36",
+        "d": "扫码接入的决策与文案、二维码编码、额度解析和环境冲突判定都在内置核心中实现；核心构建锁定工具链，产物不再依赖构建机使用的 crate 镜像。"
+      }
+    ]
+  },
   {
     "version": "1.4.16",
     "date": "2026-11-11",

package/README.md

@@ -45,7 +45,7 @@ curl -fsSL https://sintbot.com/install.sh | bash
 
 The script checks the environment, installs SintBot and verifies the result, without `sudo`. You can read [install.sh](./install.sh) before running it. Installation does not sign in to a model account, connect a group or start a service.
 
-**2. Connect your group and project.** Follow the [installation guide](https://sintbot.com/guide/install/) to prepare Codex or Claude Code, connect a Feishu app and bind the group to a local project. The guide covers the currently distributed package, its configuration and startup steps.
+**2. Connect your group and project.** Run `sintbot connect` and scan the QR code with Feishu under an enterprise or team identity: it creates the app, a project folder and a group, then writes the configuration. The [installation guide](https://sintbot.com/guide/install/) covers the options, the manual route and the startup steps.
 
 Installing with an AI assistant? Use the [AI-assisted install and first-use guide](./docs/AI-ASSISTED-INSTALL.md).
 

package/README.zh-CN.md

@@ -45,7 +45,7 @@ curl -fsSL https://sintbot.com/install.sh | bash
 
 脚本会检查环境、安装 SintBot 并验证结果，不用 `sudo`。也可以先读 [install.sh](./install.sh)。安装本身不登录模型账号、不连接群，也不启动服务。
 
-**2. 接入群和项目。** 按[安装指南](https://sintbot.com/zh/guide/install/)准备 Codex 或 Claude Code、连接飞书应用，并把群绑定到本机项目目录。当前安装包的配置与启动步骤以指南为准。
+**2. 接入群和项目。** 运行 `sintbot connect`，用企业/团队身份的飞书扫码：它会创建应用、项目目录和群，并写好配置。参数、手动路径和启动步骤见[安装指南](https://sintbot.com/zh/guide/install/)。
 
 想让本机 AI 助手帮忙安装并完成首次使用？先看 [AI 安装与首次使用说明](./docs/zh-CN/AI-ASSISTED-INSTALL.md)。
 

package/bin/sintbot-v2.js

@@ -43,6 +43,9 @@ async function startService(rest) {
     throw new Error('Console options require --ui or ui.enabled:true')
   }
   assertInstallationJournals(installation)
+  // Settings outside this installation that can reroute a CLI (daemon env,
+  // ~/.claude/settings.json, ~/.codex/config.toml): warn-only, keys not values.
+  if (preflightOnly) require('../src/agent/envconflicts').reportEnvConflicts(installation)
   // Every installation, including one group, runs the multi-group service:
   // chat commands, the console writer and per-group fault closing live there.
   return startMultiGroupService({ installation, preflightOnly, uiEnabled, uiHost, uiPort })
@@ -111,6 +114,7 @@ async function startMultiGroupService({ installation, preflightOnly, uiEnabled =
   const { C2DurableRuntime } = require('../src/core/c2durableruntime')
   // /hud reads the group's model quota; /issue appends to the console's log.
   const usageProbe = require('../src/usage').createUsageProbe({
+    bin: cfg.agent?.bin || 'claude',
     codexUsage: async () => { const status = require('../src/agent/codexstatus')
       return status.formatUsage(await status.rateLimits('codex')) } })
   const issues = require('../src/core/issues').createIssues(path.join(stateDir, 'issues.jsonl'),
@@ -466,12 +470,17 @@ const HELP = `SintBot macOS Feishu multi-group candidate
 Usage:
   sintbot init [--config <absolute path>] [--data-dir <absolute path>]
   sintbot start [--config <absolute path>] [--data-dir <absolute path>] [--preflight] [--ui] [--ui-host <address>] [--ui-port <port>] [--no-open]
+  sintbot connect [--config <absolute path>] [--data-dir <absolute path>] [--workdir <absolute path>] [--name <project>] [--provider codex|claude] [--app-id <cli_…>] [--chat <oc_…>] [--basic] [--no-open]
   sintbot incident seal --group <oc_…> [--config <absolute path>] [--data-dir <absolute path>] [--reason <text>]
   sintbot feishu <action> [arguments…] [--chat <oc_…>] [--config <path>]
   sintbot version
   sintbot help
 
 Supports explicit Feishu groups using Codex or Claude Code. Start runs in the foreground.
+connect scans a Feishu QR code to create the app, then creates a group (or binds --chat), the project
+folder under ~/Projects, the configuration and the journals, in that order; a failed check stops before
+the folder and configuration exist. It refuses existing configuration, state or a running service;
+--app-id resumes only when no configuration or an empty-group one for that app exists.
 Initialization is for a new installation only; existing journals are never reset.
 Console shows live groups, binds groups and switches models or projects of idle groups;
 in a group, /model lists or switches models. Unsupported actions stay disabled.
@@ -492,7 +501,7 @@ async function main(argv = process.argv.slice(2)) {
     return
   }
   if (!sub || sub === 'help' || sub === '--help' || sub === '-h' ||
-      ['init', 'start'].includes(sub) && rest.length === 1 && ['--help', '-h'].includes(rest[0])) {
+      ['init', 'start', 'connect'].includes(sub) && rest.length === 1 && ['--help', '-h'].includes(rest[0])) {
     process.stdout.write(HELP)
     return
   }
@@ -504,10 +513,16 @@ async function main(argv = process.argv.slice(2)) {
     process.exitCode = outcome === 'done' ? 0 : 1
     return
   }
-  if (!['init', 'start', 'incident', 'feishu'].includes(sub)) {
+  if (!['init', 'start', 'connect', 'incident', 'feishu'].includes(sub)) {
     throw new Error(`${sub} is unavailable in this release; use sintbot help`)
   }
   if (process.platform !== 'darwin') throw new Error('this release supports macOS only')
+  if (sub === 'connect') {
+    // Operator-only onboarding; deliberately not an action of the feishu skill,
+    // which the agent may run from a group.
+    process.exitCode = await require('../src/connect').runConnect(rest)
+    return
+  }
   if (sub === 'feishu') {
     // The agent's group skills. Each call uses the app credentials directly;
     // the service need not run. Text after the action may itself start with

package/docs/AI-ASSISTED-INSTALL.md

@@ -1,4 +1,4 @@
-# Install SintBot 1.4.16 with an AI assistant
+# Install SintBot 1.4.17 with an AI assistant
 
 English · [简体中文](./zh-CN/AI-ASSISTED-INSTALL.md)
 
@@ -7,13 +7,13 @@ Use the terminal on the Mac that will run SintBot. A cloud shell cannot install
 1. Check macOS, Node 22+, the actual Codex or Claude Code executable and login, and any existing SintBot process. Do not print credentials. Preserve existing installations, configuration and state.
 2. Run the one-line installation command in the guide; `--dry-run` is optional. Continue within the user's authorization; ask only for missing decisions. The installer does not change Node, Codex, Claude Code, shell profiles or services.
 3. The installer verifies the version and core at `~/.local/share/sintbot/bin/sintbot`. A successful package install is not a successful group test.
-4. Prepare the group configuration in the install guide. Let the user enter secrets locally or use already authorized credential references without revealing them. Use an existing authorized Feishu app only when another process is not connected to it. If app setup or login requires the user, finish other independent preparation first.
-5. For fresh state only, run `init`, then `start --preflight`. Refusal due to an existing journal or unresolved receipts is a stop condition: never delete files, fabricate a new authority or alter receipts to bypass it.
+4. Prefer `sintbot connect`: it prints the scan link and opens a local QR page; only the user can scan and confirm on the phone, after which it creates the project folder and group, writes the configuration and initializes, so no secret passes through the assistant. It refuses when a Feishu configuration exists or the service is running; do not delete files to get past that. If the scan is not possible, prepare the configuration by the manual route in the install guide: let the user enter secrets locally or use already authorized credential references without revealing them. Use an existing authorized Feishu app only when another process is not connected to it.
+5. On the manual route, run `init` for fresh state only (never again after `connect` has initialized), then `start --preflight`. Refusal due to an existing journal or unresolved receipts is a stop condition: never delete files, fabricate a new authority or alter receipts to bypass it.
 6. Run the foreground service, send an authorized read-only group request and compare its response with the file. Stop cleanly and verify a restart. If no person is available, use an authorized test account to send the request; document the sender and do not call it independent human acceptance. A bot's own API message may be ignored and is not a substitute for an incoming user message.
 7. Stop temporary processes before ending the task. Report what was installed, what actually ran and any remaining setup. Do not register an automatic background service for this release.
 
 ## Copyable request
 
 ```text
-Install SintBot 1.4.16 on this Mac using the one-line installation guide. Preserve existing services, configuration, state and Codex or Claude Code account data. Do not expose credentials. Verify the actual installed executable and binary core, configure the Feishu groups with their runners, and initialize only clean new state. Run the foreground preflight and an authorized read-only group test, check the result, then verify clean stop/restart. Stop temporary processes when finished, and distinguish package installation from successful group acceptance.
+Install SintBot 1.4.17 on this Mac using the one-line installation guide. Preserve existing services, configuration, state and Codex or Claude Code account data. Do not expose credentials. Verify the actual installed executable and binary core, configure the Feishu groups with their runners, and initialize only clean new state. Run the foreground preflight and an authorized read-only group test, check the result, then verify clean stop/restart. Stop temporary processes when finished, and distinguish package installation from successful group acceptance.
 ```

package/docs/install.md

@@ -1,4 +1,4 @@
-# Install SintBot 1.4.16
+# Install SintBot 1.4.17
 
 English · [简体中文](./zh-CN/install.md)
 
@@ -10,11 +10,45 @@ You need a Mac, Node.js 22 or newer, and projects stored on that Mac. Install an
 curl -fsSL https://sintbot.com/install.sh | bash
 ```
 
-The installer checks the environment, installs `sintbot@1.4.16` into `~/.local/share/sintbot`, and verifies the entry, built-in core and Feishu module. Continue when you see `Installed and verified SintBot 1.4.16`. No sudo is needed.
+The installer checks the environment, installs `sintbot@1.4.17` into `~/.local/share/sintbot`, and verifies the entry, built-in core and Feishu module. Continue when you see `Installed and verified SintBot 1.4.17`. No sudo is needed.
 
 To preview, append `-s -- --dry-run`. To choose another location, set `SINTBOT_INSTALL_DIR` and adjust the executable paths below.
 
-## 2. Connect Feishu
+## 2. Connect by scanning (recommended)
+
+Prerequisite: the Feishu app on your phone is signed in with an enterprise or team identity; a personal identity without an organization cannot scan, so create a team first (free). The app created by the scan belongs to the scanner's organization; approval depends on its policies.
+
+```bash
+"$HOME/.local/share/sintbot/bin/sintbot" connect
+```
+
+The terminal prints the scan link and opens a local page with the QR code; scan it with Feishu and confirm on the phone. It then, in order: obtains the app credentials (and prints the app ID) → runs the self-check → opens the contact range and visibility and publishes a version → creates a group and adds you → creates the project folder `~/Projects/sintbot` (with a `README.md`) → writes `~/.sbot/config.json` → initializes the message journals. Every step reports its result. Once the scan is confirmed, the app exists in your organization; any later failed check or group creation stops before the folder and the configuration are created and prints the rerun command with `--app-id`.
+
+- The credentials are stored in clear text in `~/.sbot/config.json` (file 0600, directory 0700). To switch back to environment variables, change `appId` / `appSecret` to `"env:FEISHU_APP_ID"` / `"env:FEISHU_APP_SECRET"` and export both before every start.
+- `--basic`: for a non-administrator in a company organization. It does not request `application:application:patch` and skips the range and publish steps; ask an administrator to finish those two in the Open Platform.
+- `--app-id cli_…`: reuse an existing app (add permissions to it instead of creating one), to rerun after a stop or once a review is approved. Allowed only when there is no configuration file, or the file belongs to that app and binds no group yet; a configuration with groups is never replaced.
+- `--chat oc_…`: skip group creation and bind a group you created by hand with the bot added (the notice after a failed group creation shows this command).
+- `--workdir /absolute/path`: bind an existing directory instead of creating one; `--name` changes the default folder name; `--provider codex|claude` picks the runner (chosen automatically when only one is installed); `--no-open` prints the link without opening the page.
+- `connect` refuses to run when a Feishu configuration already exists or the service is running. The scan requests the card callbacks used by `/model`. If the card does not respond, check the callback subscription as in section 4.
+
+## 3. First start
+
+`connect` has already initialized, so start directly:
+
+```bash
+"$HOME/.local/share/sintbot/bin/sintbot" start --config "$HOME/.sbot/config.json" --ui
+```
+
+This checks the configuration and runners, connects Feishu and opens the local console. Keep the terminal open. In the group, send "Read the first line of the project README and reply with only that line", then compare it with `~/Projects/sintbot/README.md`. A passing preflight does not prove Feishu authentication or delivery.
+
+## 4. Manual setup (alternative)
+
+Use the manual route when the scan fails, an administrator does not approve, or you prefer to manage the app yourself; it is the same procedure as before.
+
+<details>
+<summary>Show the manual steps</summary>
+
+#### 4.1 Create the app
 
 In the [Feishu Open Platform](https://open.feishu.cn/), create a custom app, enable the bot and the permissions to receive and reply to messages, choose long connection for event subscription and subscribe to message receipt. For callbacks, also choose long connection and subscribe to card action callbacks (the tap-to-pick `/model` card needs them). Publish the app, add the bot to the groups you will use, and copy each group's `oc_…` chat ID.
 
@@ -29,7 +63,7 @@ export FEISHU_APP_ID FEISHU_APP_SECRET
 
 Never post the secret in a group or commit it. Keep using this terminal; set both variables again in a new one.
 
-## 3. Bind projects
+#### 4.2 Write the configuration
 
 Create a private directory with `mkdir -p ~/.sbot && chmod 700 ~/.sbot`, then create `~/.sbot/config.json`. Replace the chat IDs and absolute project paths; each project directory must already exist. The example binds two groups, one with Codex and one with Claude Code. With one group, delete the other entry.
 
@@ -69,9 +103,9 @@ Then run `chmod 600 ~/.sbot/config.json`.
 - To pin a Claude model, add `"model"` to `providers.claude`; otherwise Claude Code's default model on this Mac is used.
 - At most 2 tasks run at once by default; add `"agent": { "maxConcurrent": 4 }` at the top level to change it (1–32).
 
-## 4. First start
+#### 4.3 Initialize and start
 
-Copy and run in the same terminal:
+Copy and run in the same terminal (the manual route runs `init` itself):
 
 ```bash
 SINTBOT="$HOME/.local/share/sintbot/bin/sintbot"
@@ -84,6 +118,8 @@ This initializes the message journals, checks the configuration and runners, con
 
 In a group, send "Read the first line of the project README and reply with only that line", then compare it with the file. A passing preflight does not prove Feishu authentication or delivery.
 
+</details>
+
 ## 5. Use it in a group
 
 Any text message is a task. Replies arrive in a card that appears once the model starts answering, or after 25 seconds if it is still working without output. While the task runs, the card shows how long it has run, what it is doing and the steps already delivered; at the end those steps fold into a Process section.
@@ -123,7 +159,7 @@ You can also add a group without the console: add it to the configuration, stop
 
 ## Stop and restart
 
-Press Ctrl-C and wait for exit. With the Feishu variables set, run:
+Press Ctrl-C and wait for exit. If the configuration uses `env:` references, set those variables first, then run:
 
 ```bash
 "$HOME/.local/share/sintbot/bin/sintbot" start --config "$HOME/.sbot/config.json" --ui

package/docs/zh-CN/AI-ASSISTED-INSTALL.md

@@ -1,4 +1,4 @@
-# 用 AI 助手安装 SintBot 1.4.16
+# 用 AI 助手安装 SintBot 1.4.17
 
 [English](../AI-ASSISTED-INSTALL.md) · 简体中文
 
@@ -7,13 +7,13 @@
 1. 核对 macOS、Node 22 及以上、Codex 或 Claude Code 的实际程序与登录、是否已有 SintBot 进程。不输出凭据，保留已有安装、配置和状态。
 2. 运行指南中的一行安装命令；`--dry-run` 为可选预览。用户已经授权的步骤继续执行，只问缺失的决定。安装器不修改 Node、Codex、Claude Code、终端配置或服务。
 3. 安装器会验证 `~/.local/share/sintbot/bin/sintbot` 的版本和核心加载。安装程序包成功不等于群测试成功。
-4. 按安装指南准备群配置。让用户在本地输入密钥，或使用已经授权的凭据引用，不显示秘密。复用授权飞书应用时，确认没有另一个进程连接该应用。应用或登录需要本人操作时，先完成其他独立准备。
-5. 只有全新状态才能执行 `init`，然后执行 `start --preflight`。若已有日志或未结收据而拒绝启动，不得删文件、新造日志权威或篡改收据来绕过。
+4. 优先用 `sintbot connect` 接入：它打印扫码链接并打开本机二维码页面，扫码和手机确认只能由用户本人完成；之后它自己建项目目录、建群、写配置并初始化，密钥不需要经过助手。已有飞书配置或服务在跑时它会拒绝，不要删文件绕过。扫码走不通再按安装指南的手动路径准备配置：让用户在本地输入密钥，或使用已经授权的凭据引用，不显示秘密。复用授权飞书应用时，确认没有另一个进程连接该应用。
+5. 手动路径下，只有全新状态才能执行 `init`（`connect` 已经初始化过的不要再执行），然后执行 `start --preflight`。若已有日志或未结收据而拒绝启动，不得删文件、新造日志权威或篡改收据来绕过。
 6. 前台运行，用已经授权的账号在群内发只读请求，把回复和文件对照，再正常停止并验证重启。没有真人协助时可用授权测试账号发送，并记录实际发送方式，不称为独立真人验收；机器人自己发的接口消息可能被忽略，不能当作用户入站消息。
 7. 本轮临时进程用完停止。说明安装了什么、实际验证了什么、还缺什么。本版不注册自动后台服务。
 
 ## 可复制的请求
 
 ```text
-按一行安装指南，在这台 Mac 安装 SintBot 1.4.16。保留已有服务、配置、状态和 Codex 或 Claude Code 账号数据，不输出凭据。验证实际入口与二进制核心，配置飞书群及各群的执行器，只对全新状态初始化。运行前台预检和已授权的只读群测试，对照结果，再验证正常停止与重启。完成后停止临时进程，并区分程序包安装与群验收结果。
+按一行安装指南，在这台 Mac 安装 SintBot 1.4.17。保留已有服务、配置、状态和 Codex 或 Claude Code 账号数据，不输出凭据。验证实际入口与二进制核心，配置飞书群及各群的执行器，只对全新状态初始化。运行前台预检和已授权的只读群测试，对照结果，再验证正常停止与重启。完成后停止临时进程，并区分程序包安装与群验收结果。
 ```

package/docs/zh-CN/install.md

@@ -1,4 +1,4 @@
-# 安装 SintBot 1.4.16
+# 安装 SintBot 1.4.17
 
 [English](../install.md) · 简体中文
 
@@ -10,11 +10,45 @@
 curl -fsSL https://sintbot.com/install.sh | bash
 ```
 
-安装器会自动检查环境，把 `sintbot@1.4.16` 装到 `~/.local/share/sintbot`，并验证程序入口、内置核心和飞书模块。看到 `Installed and verified SintBot 1.4.16` 就可以继续。不需要 sudo。
+安装器会自动检查环境，把 `sintbot@1.4.17` 装到 `~/.local/share/sintbot`，并验证程序入口、内置核心和飞书模块。看到 `Installed and verified SintBot 1.4.17` 就可以继续。不需要 sudo。
 
 可选预览：在命令末尾加 `-s -- --dry-run`。要自定义安装位置，设置 `SINTBOT_INSTALL_DIR` 环境变量，并同步修改后面的可执行文件路径。
 
-## 2. 连接飞书
+## 2. 扫码接入（推荐）
+
+前提：手机飞书当前处于企业/团队身份；没有组织的个人身份扫不了，需先新建一个团队（免费）。扫码创建的应用归扫码人所在的组织，公司普通成员建了自己删不掉。
+
+```bash
+"$HOME/.local/share/sintbot/bin/sintbot" connect
+```
+
+终端先打印扫码链接，并打开一个本机页面显示二维码；用飞书扫码、在手机上确认。随后它依次：取得应用凭证（并打印应用 ID）→ 自检 → 放开通讯录范围与可用范围并发布版本 → 创建群并把你拉进去 → 新建项目目录 `~/Projects/sintbot`（含一个 `README.md`）→ 写入 `~/.sbot/config.json` → 初始化消息日志。每一步的结果都会打印。扫码一旦确认，应用就已在你的组织里创建；之后任一检查或建群失败都会在建目录、写配置之前停下，并给出带 `--app-id` 的重跑命令。
+
+- 凭证明文写在 `~/.sbot/config.json`（文件 0600、目录 0700）。要改回环境变量，把 `appId` / `appSecret` 改成 `"env:FEISHU_APP_ID"` / `"env:FEISHU_APP_SECRET"`，并在每次启动前导出这两个变量。
+- `--basic`：公司组织里的非管理员使用。不申请 `application:application:patch`，跳过放开范围与发布；之后请管理员在开放平台补这两步。
+- `--app-id cli_…`：复用已有应用（给它追加权限，不新建），用于中途停下后重跑或审核通过后继续。只在没有配置文件、或配置文件属于这个应用且还没绑定任何群时允许；已绑定群的配置不会被替换。
+- `--chat oc_…`：不自动建群，直接绑定你手动建好并拉入机器人的群（建群失败时的提示里会给出这条命令）。
+- `--workdir /绝对路径`：绑定一个已存在的目录，不新建；`--name` 换默认目录名；`--provider codex|claude` 指定执行器（本机只装了一个时自动选）；`--no-open` 只打印链接、不打开页面。
+- 已有飞书配置或服务正在运行时，`connect` 会拒绝执行。扫码会申请模型卡所需的卡片回调。`/model` 点选卡没有反应时，按第 4 节检查回调订阅。
+
+## 3. 首次启动
+
+`connect` 已经完成初始化，直接启动：
+
+```bash
+"$HOME/.local/share/sintbot/bin/sintbot" start --config "$HOME/.sbot/config.json" --ui
+```
+
+它会预检配置和执行器、连接飞书并打开本机控制台。保持终端开启。在群里发“读取项目 README 的第一行，只回复这一行”，并和 `~/Projects/sintbot/README.md` 对照。预检通过不代表飞书认证或消息送达已经验证。
+
+## 4. 手动接入（备选）
+
+扫码失败、管理员不放行，或者想自己管理应用时，走下面的手动路径；内容与之前的安装步骤相同。
+
+<details>
+<summary>展开手动步骤</summary>
+
+#### 4.1 创建应用
 
 在 [飞书开放平台](https://open.feishu.cn/) 创建企业自建应用，启用机器人、接收和回复消息的权限，事件订阅选择长连接并订阅消息接收；回调订阅同样选择长连接接收回调并订阅卡片回传交互（群里点选 `/model` 卡片要用）。发布应用后，把机器人加入要使用的群，取得每个群的 `oc_…` 群 ID。
 
@@ -29,7 +63,7 @@ export FEISHU_APP_ID FEISHU_APP_SECRET
 
 不要把密钥发进群或提交到仓库。后续步骤都在这个终端里做；新开终端时需要重新设置这两个变量。
 
-## 3. 绑定项目
+#### 4.2 手写配置
 
 用 `mkdir -p ~/.sbot && chmod 700 ~/.sbot` 创建私有配置目录，再创建 `~/.sbot/config.json`。把群 ID 和项目绝对路径换成你自己的，项目目录必须已经存在。下面的示例绑定两个群：一个用 Codex，一个用 Claude Code。只有一个群时删掉另一项即可。
 
@@ -69,9 +103,9 @@ export FEISHU_APP_ID FEISHU_APP_SECRET
 - 要固定 Claude 型号，可在 `providers.claude` 里加 `"model"`；不写就用这台机器上 Claude Code 的默认模型。
 - 同时运行的任务默认最多 2 个，可在顶层加 `"agent": { "maxConcurrent": 4 }` 调整（1–32）。
 
-## 4. 首次启动
+#### 4.3 初始化并启动
 
-在刚才的终端里一次复制执行：
+在刚才的终端里一次复制执行（手动路径需要自己执行 `init`）：
 
 ```bash
 SINTBOT="$HOME/.local/share/sintbot/bin/sintbot"
@@ -84,6 +118,8 @@ SINTBOT="$HOME/.local/share/sintbot/bin/sintbot"
 
 在群里发“读取项目 README 的第一行，只回复这一行”，并和本地文件对照。预检通过不代表飞书认证或消息送达已经验证。
 
+</details>
+
 ## 5. 在群里使用
 
 直接发文字就是给它派任务。回复以卡片呈现：模型开始输出时出现；25 秒还没有输出也会先出现。运行中卡片显示已跑多久、正在做什么和已完成的步骤，结束后这些步骤收进「过程」折叠区。
@@ -123,7 +159,7 @@ Codex 和 Claude Code 的忙时跟进默认开启；`steer:false` 改为排队
 
 ## 停止与重启
 
-按 Ctrl-C 并等待退出。确认飞书环境变量已设置，再执行：
+按 Ctrl-C 并等待退出。配置里用的是 `env:` 引用时，先确认环境变量已设置，再执行：
 
 ```bash
 "$HOME/.local/share/sintbot/bin/sintbot" start --config "$HOME/.sbot/config.json" --ui

package/install.sh

@@ -2,7 +2,7 @@
 # The function is parsed in full before installation starts, including when piped.
 sintbot_install() (
   set -eu
-  version=1.4.16
+  version=1.4.17
   prefix="${SINTBOT_INSTALL_DIR:-$HOME/.local/share/sintbot}"
   fail() { printf 'SintBot: %s\n' "$*" >&2; exit 1; }
   case "${1:-}" in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sintbot",
-  "version": "1.4.16",
+  "version": "1.4.17",
   "private": false,
   "description": "Drive your Mac projects from Feishu groups with Codex or Claude Code, using a built-in agent core.",
   "bin": {
@@ -51,6 +51,7 @@
     "src/agent/codexapp.js",
     "src/agent/codexcode.js",
     "src/agent/codexstatus.js",
+    "src/agent/envconflicts.js",
     "src/agent/errtag.js",
     "src/agent/modelwindows.js",
     "src/agent/privatecore.js",
@@ -69,6 +70,7 @@
     "src/c2upgradeswitch.js",
     "src/cdp.js",
     "src/config.js",
+    "src/connect.js",
     "src/consolesay.js",
     "src/consoletrials.js",
     "src/core/brain.js",