sintbot 1.4.15 → 1.4.17

package/CHANGELOG.en.json

@@ -1,4 +1,54 @@
 [
+  {
+    "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",
+    "name": "Per-group model and thinking depth",
+    "items": [
+      {
+        "t": "Choose model and depth per group",
+        "d": "Pick the backend, model and thinking depth on each group card in the console. Model lists come live from the local Codex and Claude Code. Subscription model cards no longer carry a model or depth; a third-party endpoint keeps its model on the model card."
+      },
+      {
+        "t": "Group command /model",
+        "d": "Send /model for a tap-to-pick card and confirm to apply, or send /model high, /model <model>, or /model <backend> <model> <depth>. A model or depth change on the same backend continues the conversation; a backend change starts a new one. Changes wait until the group is idle; receipts and the audit log record who made them."
+      },
+      {
+        "t": "Existing settings migrate automatically",
+        "d": "After the upgrade connects, each model card's model and depth move into its groups with the same effective values and no session reset, after a configuration backup. Custom Codex context windows are checked against each group's chosen model."
+      }
+    ]
+  },
   {
     "version": "1.4.15",
     "date": "2026-11-11",

package/CHANGELOG.json

@@ -1,4 +1,54 @@
 [
+  {
+    "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",
+    "name": "按群选型号与思考深度",
+    "items": [
+      {
+        "t": "型号与深度按群选",
+        "d": "控制台「群 · 项目」卡上选后端、具体型号和思考深度，型号清单取自本机 Codex / Claude Code 的实时数据；订阅登录的模型卡不再设型号和深度，第三方端点的型号仍在模型卡上。"
+      },
+      {
+        "t": "群命令 /model",
+        "d": "发 /model 打开点选卡，选好点「确认更新」生效；也可直接发 /model high、/model 型号、/model 后端 型号 深度。同一后端换型号或调深度接着当前对话，换后端开新对话；都要等群空闲，回执和审计记下是谁改的。"
+      },
+      {
+        "t": "原有设置自动迁移",
+        "d": "升级连上后，模型卡上原有的型号和深度写进各群，生效值不变、会话不重置；改前自动备份配置。Codex 自定义上下文窗口按各群所选型号的上限校验。"
+      }
+    ]
+  },
   {
     "version": "1.4.15",
     "date": "2026-11-11",

package/README.md

@@ -31,7 +31,7 @@ SintBot is distributed under the [PolyForm Shield License 1.0.0](./LICENSE).
 <p align="center"><img src="https://raw.githubusercontent.com/sintlab/sintbot/main/docs/assets/how-it-works.svg" alt="Group (Slack, Feishu or WeCom) → SintBot on your machine → Claude Code or Codex in the project directory → the model chosen for that group; progress and results flow back to the group" width="880"></p>
 
 - **One group, one project.** Each group gets its own project directory, session, queue, permissions and scheduled tasks.
-- **Same agent, any brain.** Switch models with `/model` in the chat. Project files and shared notes in `CLAUDE.md` and `AGENTS.md` carry over. Switching starts a new conversation; save important decisions in the project first.
+- **Same agent, any brain.** Pick the backend, model and thinking depth with `/model` in the chat. A model or depth change continues the conversation; a backend change starts a new one, while project files and shared notes in `CLAUDE.md` and `AGENTS.md` carry over, so save important decisions in the project first.
 - **Stays on your machine.** Projects, sessions, memory and logs live on your disk and never pass through a SintBot server. Prompts and the code the model reads still go to the provider you chose.
 - **No public IP.** Every platform uses an outbound long connection (Socket Mode on Slack). One daemon can serve Slack, Feishu and WeCom at the same time.
 
@@ -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

@@ -31,7 +31,7 @@ SintBot 按 [PolyForm Shield 1.0.0 许可](./LICENSE) 分发。
 <p align="center"><img src="https://raw.githubusercontent.com/sintlab/sintbot/main/docs/assets/how-it-works-zh.svg" alt="群(飞书、Slack 或企业微信)→ 你机器上的 SintBot → 项目目录里的 Claude Code 或 Codex → 这个群选的模型;进度与结果回到群里" width="880"></p>
 
 - **一群一项目。** 每个群各有自己的项目目录、会话、排队、权限和定时任务。
-- **同一套 agent,任意大脑。** 群里发 `/model` 就能换模型。项目文件及 `CLAUDE.md`、`AGENTS.md` 中的共享记录可以延续。换模型会开新对话，重要决定先写进项目。
+- **同一套 agent,任意大脑。** 群里发 `/model` 点选后端、型号和思考深度。换型号或调深度接着当前对话；换后端会开新对话，项目文件及 `CLAUDE.md`、`AGENTS.md` 中的共享记录可以延续，重要决定先写进项目。
 - **数据留在本机。** 项目、会话、记忆、日志都在你自己的硬盘上,不经过任何 SintBot 服务器。提示词和模型读到的代码照常发给你选的模型服务商。
 - **不要公网 IP。** 每个平台都是机器主动往外连的长连接(Slack 用 Socket Mode)。一个守护进程可以同时接飞书、Slack、企业微信。
 
@@ -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,11 +43,58 @@ 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 })
 }
 
+// Model and depth used to live on model cards; they now belong to each group.
+// Once every group is connected (a console upgrade can no longer roll back
+// onto this configuration), copy each card's value into the groups that have
+// not chosen and remove it from the card, in one validated write. Effective
+// values do not change, so no session resets. The file is backed up first;
+// a group still running is retried later.
+function scheduleCardDefaultsMigration({ service, configControl, updater, cfg, stateDir, log,
+  delayMs = 15_000, tries = 40 } = {}) {
+  const fs = require('node:fs')
+  const { fillGroupPicks, stripCardDefaults } = require('../src/groupbrain')
+  const pending = () => {
+    const probe = JSON.parse(fs.readFileSync(cfg._path, 'utf8'))
+    const filled = fillGroupPicks(probe).changed
+    return stripCardDefaults(probe).changed || filled
+  }
+  try { if (!pending()) return } catch (error) { log(`card defaults migration skipped: ${error?.message || String(error)}`); return }
+  let left = tries
+  const attempt = () => {
+    left -= 1
+    try {
+      if (!service.serving || service.held.size || service.inMaintenance ||
+          updater?.status?.()?.job?.state === 'switching') throw new Error('service not settled')
+      if (!pending()) return
+      const dir = path.join(stateDir, 'config-backups')
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
+      const backup = path.join(dir, `${new Date().toISOString().replace(/[:.]/g, '-')}-group-model.json`)
+      fs.copyFileSync(cfg._path, backup)
+      fs.chmodSync(backup, 0o600)
+      let summary = null
+      configControl.writeConfig(raw => {
+        const filled = fillGroupPicks(raw)
+        const stripped = stripCardDefaults(raw)
+        summary = { groups: filled.groups.length, providers: stripped.providers }
+      })
+      log(`model and depth moved from model cards into groups: ${summary.groups} group(s), cards ${summary.providers.join(', ') || '-'}; backup ${path.basename(backup)}`)
+    } catch (error) {
+      if (left > 0) { const t = setTimeout(attempt, delayMs * 4); t.unref?.() }
+      else log(`card defaults migration not applied: ${error?.message || String(error)}`)
+    }
+  }
+  const timer = setTimeout(attempt, delayMs)
+  timer.unref?.()
+}
+
 async function startMultiGroupService({ installation, preflightOnly, uiEnabled = false, uiHost, uiPort }) {
   const { stateDir, cfg, routes } = installation
   const { assertPrivateDirectory, assertJournalScope } = require('../src/c2install')
@@ -67,11 +114,27 @@ 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'),
     { withFileLock: require('../src/core/store').withFileLock,
       log: message => process.stderr.write(`C2 multi-group · ${message}\n`) })
+  // Backend · model · depth: one live model list per process (also used by the
+  // console), and every effective change is audited.
+  const modelCatalog = require('../src/modelcatalog').createModelCatalog({
+    codexstatus: require('../src/agent/codexstatus'), claudemodels: require('../src/agent/claudemodels'),
+    claudeBin: cfg.agent?.bin || 'claude', cacheFile: path.join(stateDir, 'model-lists.json'),
+    log: message => process.stderr.write(`C2 multi-group · ${message}\n`) })
+  const groupBrainMod = require('../src/groupbrain')
+  const { buildModelCard } = require('../src/platform/modelcard')
+  const audit = require('../src/core/ledger').createLedger(path.join(stateDir, 'audit.jsonl'),
+    message => process.stderr.write(`C2 multi-group · ${message}\n`))
+  const setGroupBrain = (chatId, change, { by = '', source = 'console' } = {}) => {
+    const result = configControl.setGroupBrain(chatId, change)
+    if (result?.changed) audit.append(groupBrainMod.auditRow(chatId, result, { source, by }))
+    return result
+  }
   const runner = require('../src/agent/runner')
   const validators = { validateState: validatePersistentState,
     validateReceipts: validatePersistentReceipts, validateRelation: validatePersistentRelation }
@@ -173,6 +236,18 @@ async function startMultiGroupService({ installation, preflightOnly, uiEnabled =
       // Faults in a shared resource stop every group; others hold one group.
       sharedFault: () => capacity.snapshot().closed ? 'model concurrency closed' : null,
       log: message => process.stderr.write(`C2 multi-group · ${message}\n`),
+      // /model card taps: the engine decides, the reply replaces the card.
+      onModelCard: async (event, binding) => {
+        let who = event.operator?.name || ''
+        const adapter = liveTransport?.platform.forChat(event.chatId)
+        if (!who && adapter?.nameOf && event.operator?.openId) { try { who = (await adapter.nameOf(event.operator.openId)) || '' } catch {} }
+        const out = await binding.engine.handleModelCard({ chatId: event.chatId, who,
+          value: event.action.value || {}, option: event.action.option })
+        const resp = {}
+        if (out?.toast) resp.toast = out.toast
+        if (out?.state) resp.card = { type: 'raw', data: buildModelCard(out.state) }
+        return Object.keys(resp).length ? resp : undefined
+      },
       onFatal: (error, result) => {
         process.stderr.write(`C2 multi-group failure: ${error?.message || String(error)}\n`)
         finish(result)
@@ -250,8 +325,14 @@ async function startMultiGroupService({ installation, preflightOnly, uiEnabled =
             },
             durableV2SwitchProvider: (chatId, name) => {
               if (chatId !== route.chatId) throw new Error('Model switch targets another group')
-              configControl.switchGroupProvider(chatId, name)
+              setGroupBrain(chatId, { provider: name }, { source: 'command' })
+            },
+            durableV2SetBrain: (chatId, change, meta) => {
+              if (chatId !== route.chatId) throw new Error('Model change targets another group')
+              return setGroupBrain(chatId, change, meta)
             },
+            durableV2ModelCatalog: (name, provider) => modelCatalog(name, provider),
+            durableV2ModelCard: state => buildModelCard(state),
             durableV2UsageProbe: usageProbe, durableV2Issues: issues,
             durableV2Version: require('../package.json').version,
             durableV2DataDir: stateDir,
@@ -301,7 +382,7 @@ async function startMultiGroupService({ installation, preflightOnly, uiEnabled =
         getPlatform: chatId => liveTransport?.platform.forChat(chatId) || null,
         routeMessage: (msg, adapter) => service.routeMessage(msg, adapter),
         isServing: () => service.serving, isFrozen: () => service.inMaintenance,
-        assertWriterLock, ...configControl, updater,
+        assertWriterLock, ...configControl, setGroupBrain, modelCatalog, updater,
         log: message => process.stderr.write(`Console · ${message}\n`) })
       await new Promise((resolve, reject) => {
         ui.server.once('error', reject)
@@ -337,6 +418,14 @@ async function startMultiGroupService({ installation, preflightOnly, uiEnabled =
     // group is connected; then the daily version check starts.
     if (!started.held?.length) updater?.confirmStarted()
     void updater?.start()
+    // Model lists are probed once in the background shortly after startup, so
+    // a later /model or console group card does not wait for a CLI handshake.
+    const runners = new Set(Object.values(cfg.providers || {}).filter(p => p && !p.hidden)
+      .map(p => p.runner === 'codex' ? 'codex' : !p.baseUrl ? 'claude' : '').filter(Boolean))
+    const warm = setTimeout(() => { void modelCatalog.warm([...runners]).catch(() => {}) }, 30_000)
+    warm.unref?.()
+    scheduleCardDefaultsMigration({ service, configControl, updater, cfg, stateDir,
+      log: message => process.stderr.write(`SintBot · ${message}\n`) })
   } catch (error) {
     ui?.close()
     const stopped = await service?.stop('startup-failed', 1)
@@ -381,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.
@@ -407,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
   }
@@ -419,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.15 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.15 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.15
+# Install SintBot 1.4.17
 
 English · [简体中文](./zh-CN/install.md)
 
@@ -10,13 +10,47 @@ 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.15` into `~/.local/share/sintbot`, and verifies the entry, built-in core and Feishu module. Continue when you see `Installed and verified SintBot 1.4.15`. 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)
 
-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. Publish the app, add the bot to the groups you will use, and copy each group's `oc_…` chat ID.
+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.
 
 Enter the app credentials in the default macOS terminal (the secret is not echoed):
 
@@ -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.
@@ -94,7 +130,7 @@ Any text message is a task. Replies arrive in a card that appears once the model
 | `/skip` | Cancel only the current task; queued messages run next and the conversation is kept |
 | `/stop` | Stop the current task and cancel queued ones; the conversation is kept |
 | `/new` | Start a new conversation, forgetting the previous one (only while the group is idle) |
-| `/model` | List models; `/model name` switches (only while the group is idle; starts a new conversation) |
+| `/model` | Opens a tap-to-pick card: choose the backend, model and thinking depth, then confirm. You can also send `/model high`, `/model <model>` or `/model <backend>`. A model or depth change continues the conversation; a backend change starts a new one. Only while the group is idle |
 | `/hud` | Quota of the current model and usage of this conversation |
 | `/issue text` | Log feedback; review and close it in the console overview |
 | `/help` | List commands, with this group's project and model |
@@ -107,7 +143,7 @@ When the reply card moves below a confirmed follow-up, its existing text is show
 
 ## 6. Console
 
-Model cards distinguish requested settings from runtime reports; expand Capacity and runtime details for reference limits. Codex context and per-model compaction each offer Executor default or Custom. Numeric inputs appear only for Custom. Changes apply next turn without resetting the session; known catalog context limits are enforced. Compaction means a threshold for Codex and a window for Claude Code, and may start earlier. Explicit legacy global compaction values are converted into independent settings for existing models, preserving per-model overrides. New models use executor defaults. Reading does not rewrite the file; the converted settings are persisted on the next normal configuration save.
+Model and thinking depth are chosen per group: on the group card, the Model row picks the backend and model and the next row picks the depth, from lists read live from the local Codex and Claude Code. Subscription model cards no longer carry a model or depth; a third-party endpoint keeps its model on the model card. After the upgrade, each model card's existing model and depth move into its groups with the same effective values and no session reset, after a configuration backup. Model cards distinguish requested settings from runtime reports; expand Capacity and runtime details for reference limits. Codex context and per-model compaction each offer Executor default or Custom. Numeric inputs appear only for Custom. Changes apply next turn without resetting the session; known catalog context limits are enforced. Compaction means a threshold for Codex and a window for Claude Code, and may start earlier. Explicit legacy global compaction values are converted into independent settings for existing models, preserving per-model overrides. New models use executor defaults. Reading does not rewrite the file; the converted settings are persisted on the next normal configuration save.
 
 The overview combines group projects and concurrency. Each row shows the runner, state and elapsed time, project folder, model and configured reasoning effort, and the latest reported context usage. Select a group to view its tasks, then expand a task for tools, reply and usage. Context is a session sample, not cumulative token consumption; unknown capacity and older samples are labeled. Row icons provide console messages, stop and new-session controls according to the current group state.
 
@@ -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.15
+# 用 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.15。保留已有服务、配置、状态和 Codex 或 Claude Code 账号数据，不输出凭据。验证实际入口与二进制核心，配置飞书群及各群的执行器，只对全新状态初始化。运行前台预检和已授权的只读群测试，对照结果，再验证正常停止与重启。完成后停止临时进程，并区分程序包安装与群验收结果。
+按一行安装指南，在这台 Mac 安装 SintBot 1.4.17。保留已有服务、配置、状态和 Codex 或 Claude Code 账号数据，不输出凭据。验证实际入口与二进制核心，配置飞书群及各群的执行器，只对全新状态初始化。运行前台预检和已授权的只读群测试，对照结果，再验证正常停止与重启。完成后停止临时进程，并区分程序包安装与群验收结果。
 ```