sintbot 1.3.0 → 1.4.1

package/docs/AI-ASSISTED-INSTALL.md

@@ -1,19 +1,19 @@
-# Install SintBot 1.3.0 with an AI assistant
+# Install SintBot 1.4.1 with an AI assistant
 
 English · [简体中文](./zh-CN/AI-ASSISTED-INSTALL.md)
 
-Use the terminal on the Mac that will run SintBot. A cloud shell cannot install it on the user's Mac. Follow the [installation guide](./install.md); its supported route is one Feishu group, Codex and a foreground process.
+Use the terminal on the Mac that will run SintBot. A cloud shell cannot install it on the user's Mac. Follow the [installation guide](./install.md); its supported route is 1–32 Feishu groups, Codex or Claude Code per group, and a foreground process.
 
-1. Check macOS, Node 22+, the actual Codex executable/login and any existing SintBot process. Do not print credentials. Preserve existing installations, configuration and state.
-2. Download and inspect the installer, run its `--dry-run`, then install the exact package into a new prefix. Continue within the user's authorization; ask only for missing decisions. The installer does not change Node, Codex, shell profiles or services.
-3. Use the executable under that prefix and verify it reports `1.3.0`. Do not substitute a globally installed command. A successful package install is not a successful group test.
-4. Prepare the single-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 old state or unresolved receipts is a stop condition: never delete files, fabricate a new authority or alter receipts to bypass it.
+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.
 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.3.0 on this Mac using the versioned, isolated installation guide. Preserve existing services, configuration, state and Codex account data. Do not expose credentials. Verify the actual installed executable and binary core, configure one Feishu group for Codex, 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. Do not use the old setup, console or service-install flow. Stop temporary processes when finished, and distinguish package installation from successful group acceptance.
+Install SintBot 1.4.1 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,93 +1,125 @@
-# Install SintBot 1.3.0
+# Install SintBot 1.4.1
 
 English · [简体中文](./zh-CN/install.md)
 
-This release supports macOS, Node.js 22+, one Feishu group and Codex message turns. It runs in the foreground. Multiple groups, other chat platforms or model routes, the console, automatic service setup, scheduled tasks, terminal chat and whiteboards are not supported in 1.3.0.
+You need a Mac, Node.js 22 or newer, and projects stored on that Mac. Install and sign in to at least one runner: Codex or Claude Code. This release connects 1–32 Feishu China groups, binds each group to one local project, and runs in the foreground.
 
-## 1. Prepare the Mac
-
-Use a terminal on the Mac where the project lives. Confirm Node.js 22+ and a working, authenticated Codex installation. Keep the existing Codex installation and account data. The SintBot installer does not install or log in to Codex and does not install Node.
+## 1. Install with one command
 
 ```bash
-node --version
-codex --version
+curl -fsSL https://sintbot.com/install.sh | bash
 ```
 
-If this Mac already runs SintBot, leave it running its current package and configuration. A separate package prefix is safe to install, but **1.3.0 does not automatically migrate existing state**. Its initialization refuses existing state, old receipts or an existing journal. Do not delete these files to bypass that check. Do not connect two processes to the same Feishu application.
-
-## 2. Install into a separate directory
+The installer checks the environment, installs `sintbot@1.4.1` into `~/.local/share/sintbot`, and verifies the entry, built-in core and Feishu module. Continue when you see `Installed and verified SintBot 1.4.1`. No sudo is needed.
 
-Download and inspect the installer, then run the same file:
+To preview, append `-s -- --dry-run`. To choose another location, set `SINTBOT_INSTALL_DIR` and adjust the executable paths below.
 
-```bash
-curl -fsSL https://sintbot.com/install.sh -o /tmp/sintbot-install.sh
-bash /tmp/sintbot-install.sh --dry-run
-bash /tmp/sintbot-install.sh
-```
+## 2. Connect Feishu
 
-It installs **sintbot@1.3.0** into `~/.local/share/sintbot/releases/1.3.0`, checks the actual executable, binary core and Feishu module, and leaves global packages, shell profiles, configuration and services untouched. It refuses an existing target directory. Use `--prefix /new/absolute/directory` for a different location. `--dry-run` makes no changes and does not fetch a package.
+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.
 
-Keep using the exact executable, so an older global command cannot be selected accidentally:
+Enter the app credentials in the default macOS terminal (the secret is not echoed):
 
-```bash
-SINTBOT="$HOME/.local/share/sintbot/releases/1.3.0/bin/sintbot"
-"$SINTBOT" --version
-"$SINTBOT" help
+```zsh
+read -r "FEISHU_APP_ID?Feishu App ID: "
+read -rs "FEISHU_APP_SECRET?Feishu App Secret: "
+printf '\n'
+export FEISHU_APP_ID FEISHU_APP_SECRET
 ```
 
-The expected version is `1.3.0`. Installing the package does not start a bot.
-
-## 3. Configure one Feishu group
-
-Create a Feishu enterprise custom application on `open.feishu.cn`, enable its bot, grant message reception and reply permissions, choose long-connection event delivery, subscribe to message reception, publish the application and add its bot to your test group. Obtain that group's `oc_…` chat ID from Feishu. Use the China Feishu platform; international Lark is not supported.
+Never post the secret in a group or commit it. Keep using this terminal; set both variables again in a new one.
 
-Enter the app ID and app secret locally as `FEISHU_APP_ID` and `FEISHU_APP_SECRET` environment variables in the terminal that will start SintBot. Do not paste the secret into chat or commit it to your repository. Environment references are resolved at startup; both values must be present in each new terminal session.
+## 3. Bind projects
 
-Create the private configuration directory with `mkdir -p ~/.sbot && chmod 700 ~/.sbot`, then create `~/.sbot/config-1.3.0.json` with the following content. Replace the group ID and project path with actual values. The project must already exist. Keep exactly one group and the two explicit `false` flags.
+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.
 
 ```json
 {
   "defaultProvider": "codex",
-  "providers": { "codex": { "runner": "codex" } },
+  "providers": {
+    "codex": { "runner": "codex" },
+    "claude": { "runner": "claude" }
+  },
   "feishu": {
     "appId": "env:FEISHU_APP_ID",
     "appSecret": "env:FEISHU_APP_SECRET",
     "onlyWhenMentioned": false
   },
   "groups": {
-    "oc_REPLACE_WITH_YOUR_CHAT_ID": {
+    "oc_REPLACE_WITH_FIRST_CHAT_ID": {
       "platform": "feishu",
       "provider": "codex",
-      "workdir": "/absolute/path/to/your/project",
+      "workdir": "/absolute/path/to/first/project",
       "permissionMode": "dontAsk",
-      "codexSteer": false,
-      "codexApp": false
+      "codexSteer": true
+    },
+    "oc_REPLACE_WITH_SECOND_CHAT_ID": {
+      "platform": "feishu",
+      "provider": "claude",
+      "workdir": "/absolute/path/to/second/project",
+      "permissionMode": "dontAsk"
     }
   }
 }
 ```
 
-Keep the configuration private (`chmod 600 ~/.sbot/config-1.3.0.json`). This example begins read-only and receives ordinary messages in this one group; use a dedicated test group. To require mentions instead, set `onlyWhenMentioned: true` and supply the actual app-specific `botOpenId`; startup rejects a missing bot ID. Do not add console, other-platform, scheduled-task or whiteboard settings from an older example. The full historical configuration schema is not the supported 1.3.0 setup.
+Then run `chmod 600 ~/.sbot/config.json`.
+
+- `permissionMode: "dontAsk"` is restricted and suits a first test group. Use `"bypassPermissions"` (full access) once it should edit files and run commands.
+- 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. Initialize and start
+## 4. First start
 
-For a **new installation only**:
+Copy and run in the same terminal:
 
 ```bash
-"$SINTBOT" init --config "$HOME/.sbot/config-1.3.0.json"
-"$SINTBOT" start --config "$HOME/.sbot/config-1.3.0.json" --preflight
-"$SINTBOT" start --config "$HOME/.sbot/config-1.3.0.json"
+SINTBOT="$HOME/.local/share/sintbot/bin/sintbot"
+"$SINTBOT" init --config "$HOME/.sbot/config.json" &&
+"$SINTBOT" start --config "$HOME/.sbot/config.json" --preflight &&
+"$SINTBOT" start --config "$HOME/.sbot/config.json" --ui
 ```
 
-`init` creates a new persistent receipt journal at `~/.sbot/c2-v2.log`; it never resets an existing journal or migrates old state. Run it once. `--preflight` checks local configuration and assembly without starting the Feishu connection; it does not prove authentication or message delivery. `start` holds the single-writer lock and connects the configured group. Keep that terminal open.
+This initializes the message journals, checks the configuration and runners, connects Feishu and opens the local console, stopping at the first failure. **Run `init` only once**; never run it again for a restart. Keep the terminal open.
+
+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.
+
+## 5. Use it in a group
+
+Any text message is a task. Replies arrive in a card that appears once the model starts answering and refreshes as it works.
 
-Send a message in the group and request the first line of the project's README. Check the returned line against the file. Press Ctrl-C and wait for the process to exit, then run the same `start` command again. Do not rerun `init` for normal restarts.
+| Command | Effect |
+| --- | --- |
+| `/help` | List commands |
+| `/status` | Group status: model, project, busy or idle, queue |
+| `/model` | List models; `/model name` switches (only while the group is idle; starts a new conversation) |
+| `/new` | Start a new conversation (only while the group is idle) |
+| `/stop` | Stop the current task and cancel queued ones |
+| `/hud` | Quota of the current model and usage of this conversation |
+| `/issue text` | Log feedback; review and close it in the console overview |
 
-## Stop, failure and upgrades
+Messages sent while a task runs are added to that task in Codex groups (`codexSteer: true`) and queued in Claude Code groups. If a turn returns a model error or no result, only that group is asked to resend; there is no automatic retry. If a group's last result cannot be confirmed, such as a reply whose delivery is unknown, only that group is paused and answers new messages with a short notice; other groups keep working. Nothing is replayed or retried.
+
+## 6. Console
+
+With `--ui`, open `http://127.0.0.1:4600` on this Mac. The console shows each group (a paused group shows Needs attention), stops tasks, binds new groups, and switches the model or project folder of an idle group. For LAN access, set a console password in its settings first, then enable LAN access.
+
+You can also add a group without the console: add it to the configuration, stop the service and run `start` again; the new group is registered automatically. Bound groups cannot be removed or renamed by editing the configuration.
+
+## Stop and restart
+
+Press Ctrl-C and wait for exit. With the Feishu variables set, run:
+
+```bash
+"$HOME/.local/share/sintbot/bin/sintbot" start --config "$HOME/.sbot/config.json" --ui
+```
+
+If a group stays paused, first restart: a group whose records can recover reopens on its own and is told once to resend. If it is still paused, check what actually happened in that group, then stop the service and seal the group's incident:
+
+```bash
+"$HOME/.local/share/sintbot/bin/sintbot" incident seal --config "$HOME/.sbot/config.json" --group oc_PAUSED_GROUP_ID
+```
 
-- Stop with Ctrl-C and wait for shutdown. This version does not provide automatic login startup or a service-install command.
-- If a request fails or startup reports unresolved receipts, preserve the journal and state. Verify what happened before retrying. Do not clear unknown effects, overwrite the journal or run the same task again blindly.
-- The installer never replaces an earlier package. A version change still requires draining the old process, preserving configuration/state and checking receipt compatibility. A spare executable alone is not a safe rollback of state.
-- Existing multi-group installations remain on their previous release. A reviewed migration is required before replacing them with this single-group route.
+Sealing keeps the old journal unchanged under `incidents/` in the data directory and gives the group a new journal; messages left unfinished before the seal are never processed again. Start the service again to reopen the group. A preflight fails while any group would stay paused. Never delete journals or resend to get around a paused group. Run only one connected process per Feishu app. This release does not register a background service.
 
-See the [AI-assisted guide](./AI-ASSISTED-INSTALL.md) if an assistant is performing the local steps.
+[Illustrated website guide](https://sintbot.com/guide/install/) · [AI-assisted installation](./AI-ASSISTED-INSTALL.md)

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

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

package/docs/zh-CN/install.md

@@ -1,93 +1,125 @@
-# 安装 SintBot 1.3.0
+# 安装 SintBot 1.4.1
 
 [English](../install.md) · 简体中文
 
-本版支持 macOS、Node.js 22 及以上、一个飞书群和 Codex 消息轮次，以前台方式运行。多群、其他聊天平台或模型通道、控制台、自动后台服务、定时任务、终端聊天和画布不在 1.3.0 支持范围。
+准备一台 Mac、Node.js 22 及以上，以及保存在本机的项目。执行器至少装好并登录一个：Codex，或 Claude Code。本版连接中国区飞书的 1–32 个群，每个群绑定一个本地项目，以前台方式运行。
 
-## 1. 准备 Mac
-
-在项目所在 Mac 的本地终端操作，确认 Node.js 22 及以上、Codex 可以实际运行且已完成登录。保留已有 Codex 安装和账号数据。SintBot 安装器不安装或登录 Codex，也不安装 Node。
+## 1. 一行安装
 
 ```bash
-node --version
-codex --version
+curl -fsSL https://sintbot.com/install.sh | bash
 ```
 
-如果这台 Mac 已经运行 SintBot，保留原来的程序包与配置。可以把新包装到独立目录，但 **1.3.0 不自动迁移已有状态**。初始化会拒绝已有状态、旧收据或日志；不要删除它们来绕过检查。不要让两个进程连接同一个飞书应用。
-
-## 2. 安装到独立目录
+安装器会自动检查环境，把 `sintbot@1.4.1` 装到 `~/.local/share/sintbot`，并验证程序入口、内置核心和飞书模块。看到 `Installed and verified SintBot 1.4.1` 就可以继续。不需要 sudo。
 
-下载并检查安装脚本，再执行同一份文件：
+可选预览：在命令末尾加 `-s -- --dry-run`。要自定义安装位置，设置 `SINTBOT_INSTALL_DIR` 环境变量，并同步修改后面的可执行文件路径。
 
-```bash
-curl -fsSL https://sintbot.com/install.sh -o /tmp/sintbot-install.sh
-bash /tmp/sintbot-install.sh --dry-run
-bash /tmp/sintbot-install.sh
-```
+## 2. 连接飞书
 
-脚本把精确的 **sintbot@1.3.0** 安装到 `~/.local/share/sintbot/releases/1.3.0`，验证实际入口、二进制核心和飞书模块，保留全局安装、终端配置、应用配置和服务。目标目录已存在时拒绝覆盖；可用 `--prefix /全新/绝对/目录` 指定其他位置。`--dry-run` 不修改文件，也不下载程序包。
+在 [飞书开放平台](https://open.feishu.cn/) 创建企业自建应用，启用机器人、接收和回复消息的权限，事件订阅选择长连接并订阅消息接收。发布应用后，把机器人加入要使用的群，取得每个群的 `oc_…` 群 ID。
 
-始终使用这一个实际入口，避免误用全局旧版本：
+在 macOS 默认终端中输入应用凭据（密钥输入时不显示）：
 
-```bash
-SINTBOT="$HOME/.local/share/sintbot/releases/1.3.0/bin/sintbot"
-"$SINTBOT" --version
-"$SINTBOT" help
+```zsh
+read -r "FEISHU_APP_ID?Feishu App ID: "
+read -rs "FEISHU_APP_SECRET?Feishu App Secret: "
+printf '\n'
+export FEISHU_APP_ID FEISHU_APP_SECRET
 ```
 
-版本输出应为 `1.3.0`。装好程序包不会自动启动机器人。
-
-## 3. 配置一个飞书群
-
-在 `open.feishu.cn` 创建企业自建应用，启用机器人，授予接收与回复消息的权限，事件订阅选择长连接，订阅消息接收事件，发布应用并把机器人加入测试群。从飞书取得该群的 `oc_…` 群 ID。本版使用中国区飞书，不支持国际版 Lark。
+不要把密钥发进群或提交到仓库。后续步骤都在这个终端里做；新开终端时需要重新设置这两个变量。
 
-在启动 SintBot 的本地终端中，把应用 ID 和应用密钥分别设为 `FEISHU_APP_ID`、`FEISHU_APP_SECRET` 环境变量。不要把密钥发进聊天或提交到仓库。配置中的环境变量引用在启动时解析；每次新开终端都需要保证这两个变量存在。
+## 3. 绑定项目
 
-先用 `mkdir -p ~/.sbot && chmod 700 ~/.sbot` 创建私有配置目录，再创建 `~/.sbot/config-1.3.0.json`，内容如下。把群 ID 和项目路径换成真实值；项目目录必须已存在。只留一个群，两个显式 `false` 不要省略。
+用 `mkdir -p ~/.sbot && chmod 700 ~/.sbot` 创建私有配置目录，再创建 `~/.sbot/config.json`。把群 ID 和项目绝对路径换成你自己的，项目目录必须已经存在。下面的示例绑定两个群：一个用 Codex，一个用 Claude Code。只有一个群时删掉另一项即可。
 
 ```json
 {
   "defaultProvider": "codex",
-  "providers": { "codex": { "runner": "codex" } },
+  "providers": {
+    "codex": { "runner": "codex" },
+    "claude": { "runner": "claude" }
+  },
   "feishu": {
     "appId": "env:FEISHU_APP_ID",
     "appSecret": "env:FEISHU_APP_SECRET",
     "onlyWhenMentioned": false
   },
   "groups": {
-    "oc_REPLACE_WITH_YOUR_CHAT_ID": {
+    "oc_REPLACE_WITH_FIRST_CHAT_ID": {
       "platform": "feishu",
       "provider": "codex",
-      "workdir": "/absolute/path/to/your/project",
+      "workdir": "/absolute/path/to/first/project",
       "permissionMode": "dontAsk",
-      "codexSteer": false,
-      "codexApp": false
+      "codexSteer": true
+    },
+    "oc_REPLACE_WITH_SECOND_CHAT_ID": {
+      "platform": "feishu",
+      "provider": "claude",
+      "workdir": "/absolute/path/to/second/project",
+      "permissionMode": "dontAsk"
     }
   }
 }
 ```
 
-限制配置文件权限（`chmod 600 ~/.sbot/config-1.3.0.json`）。示例采用只读权限，接收这一个群里的普通消息，请使用专用测试群。若只接收 @ 机器人的消息，须设 `onlyWhenMentioned: true` 并填入该应用实际的 `botOpenId`；缺少机器人 ID 会在启动前被拒绝。不要从旧示例复制控制台、其他平台、定时任务或画布配置；历史完整配置不代表 1.3.0 支持范围。
+保存后执行 `chmod 600 ~/.sbot/config.json`。
+
+- `permissionMode: "dontAsk"` 是受限权限，适合先在测试群试用。确认需要让它修改文件、执行命令时，改为 `"bypassPermissions"`（完全访问）。
+- 要固定 Claude 型号，可在 `providers.claude` 里加 `"model"`；不写就用这台机器上 Claude Code 的默认模型。
+- 同时运行的任务默认最多 2 个，可在顶层加 `"agent": { "maxConcurrent": 4 }` 调整（1–32）。
 
-## 4. 初始化并启动
+## 4. 首次启动
 
-**仅全新安装**执行：
+在刚才的终端里一次复制执行：
 
 ```bash
-"$SINTBOT" init --config "$HOME/.sbot/config-1.3.0.json"
-"$SINTBOT" start --config "$HOME/.sbot/config-1.3.0.json" --preflight
-"$SINTBOT" start --config "$HOME/.sbot/config-1.3.0.json"
+SINTBOT="$HOME/.local/share/sintbot/bin/sintbot"
+"$SINTBOT" init --config "$HOME/.sbot/config.json" &&
+"$SINTBOT" start --config "$HOME/.sbot/config.json" --preflight &&
+"$SINTBOT" start --config "$HOME/.sbot/config.json" --ui
 ```
 
-`init` 在 `~/.sbot/c2-v2.log` 创建持久收据日志，只运行一次；不会重置已有日志或迁移旧状态。`--preflight` 检查本地配置与装配，不建立飞书连接，也不能代替认证或消息送达验证。`start` 持有单写锁并连接所配群，需要保持终端开启。
+这组命令依次初始化消息日志、预检配置和执行器、连接飞书并打开本机控制台，任一步失败就停止。**初始化只运行一次**；以后重启不要再执行 `init`。保持终端开启。
+
+在群里发“读取项目 README 的第一行，只回复这一行”，并和本地文件对照。预检通过不代表飞书认证或消息送达已经验证。
+
+## 5. 在群里使用
+
+直接发文字就是给它派任务。回复以卡片呈现，模型开始输出后就会出现并随进度刷新。
 
-在群里直接发消息，要求读取项目 README 的第一行。把返回结果与文件对照。按 Ctrl-C 并等待退出，再用相同的 `start` 命令启动一次。正常重启不要重新执行 `init`。
+| 命令 | 作用 |
+| --- | --- |
+| `/help` | 查看可用命令 |
+| `/status` | 本群状态：模型、项目、是否在忙、排队数 |
+| `/model` | 查看可选模型；`/model 名字` 切换（只在本群空闲时生效，切换后开始新的一段对话） |
+| `/new` | 开始新的一段对话（只在本群空闲时生效） |
+| `/stop` | 停止当前任务，连同排队的一起取消 |
+| `/hud` | 当前模型的额度与本段对话的用量 |
+| `/issue 一句话` | 记下问题反馈，在控制台概览里查看和标记处理 |
 
-## 停止、故障和升级
+任务进行中再发的消息：Codex 群（`codexSteer: true`）会补充进当前任务，Claude Code 群会排队，等这一轮结束再处理。某一轮模型报错或没有结果时，只在本群提示重新发送，不会自动重试。某个群上一轮的结果无法确认时（例如回复是否送达不明），只暂停这个群，它收到新消息会回一句说明，其他群照常；不重放、不重试。
+
+## 6. 控制台
+
+带 `--ui` 启动后，在本机浏览器打开 `http://127.0.0.1:4600`。控制台可以查看各群状态（暂停的群显示「需要处理」）、停止任务、绑定新群、给空闲的群切换模型或项目目录。要从局域网访问，先在控制台的设置里设访问密码，再开启局域网访问。
+
+不用控制台也能加群：在配置里加上新群，停止后重新 `start` 即可，新群会自动登记。已绑定的群不能通过改配置删除或改名。
+
+## 停止与重启
+
+按 Ctrl-C 并等待退出。确认飞书环境变量已设置，再执行：
+
+```bash
+"$HOME/.local/share/sintbot/bin/sintbot" start --config "$HOME/.sbot/config.json" --ui
+```
+
+某个群一直暂停时，先重启：记录能恢复的群会自己重新开放，并提示一次重新发送。重启后仍暂停，先核对这个群实际发生了什么，再停止服务，封存这个群的事故记录：
+
+```bash
+"$HOME/.local/share/sintbot/bin/sintbot" incident seal --config "$HOME/.sbot/config.json" --group oc_暂停的群ID
+```
 
-- 按 Ctrl-C 并等待退出；本版不提供登录自启或安装后台服务命令。
-- 任务失败或启动提示未结收据时，保留日志与状态，核对实际结果后再处置。不要清空未知效果、覆盖日志或盲目重发相同任务。
-- 安装器保留旧程序包，但切版本仍须排空旧进程、备份配置与状态、确认收据兼容。只有旧可执行文件不等于可以安全回退状态。
-- 已有多群安装继续用原版本，替换为单群路径前必须有经过核对的迁移方案。
+封存会把原日志原样留在数据目录的 `incidents/` 下，并给这个群换一份新日志；封存前没处理完的消息不会再处理。再次启动服务，这个群就重新开放。有群会保持暂停时，预检会失败。不要通过删除日志或重复发送来绕过暂停。一个飞书应用同一时间只运行一个连接进程。本版不自动注册后台服务。
 
-由助手操作时可用 [AI 辅助安装指南](./AI-ASSISTED-INSTALL.md)。
+[带图示的官网指南](https://sintbot.com/zh/guide/install/) · [AI 辅助安装](./AI-ASSISTED-INSTALL.md)

package/install.sh

@@ -1,84 +1,37 @@
 #!/usr/bin/env bash
-# SintBot 1.3.0: isolated macOS package install. Does not change services/config.
-set -u
-VERSION=1.3.0
-PREFIX="${HOME}/.local/share/sintbot/releases/${VERSION}"
-PACKAGE="sintbot@${VERSION}"
-DRY=0
-STAGE=''
-LOCK=''
-fail() { printf '%s\n' "SintBot: $*" >&2; exit 1; }
-cleanup() {
-  if [ -n "$STAGE" ] && [ -d "$STAGE" ]; then rm -rf -- "$STAGE"; fi
-  if [ -n "$LOCK" ] && [ -d "$LOCK" ]; then rmdir -- "$LOCK" 2>/dev/null || true; fi
-}
-trap cleanup EXIT
-trap 'exit 130' INT
-trap 'exit 143' TERM
-while [ "$#" -gt 0 ]; do
-  case "$1" in
-    --dry-run) DRY=1; shift ;;
-    --prefix|--package)
-      [ "$#" -ge 2 ] || fail "$1 needs a value"
-      if [ "$1" = --prefix ]; then PREFIX="$2"; else PACKAGE="$2"; fi
-      shift 2 ;;
-    --help|-h)
-      printf '%s\n' 'SintBot 1.3.0 — macOS / one Feishu group / Codex' \
-        'Usage: bash install.sh [--dry-run] [--prefix /new/absolute/directory]' \
-        '       [--package /absolute/sintbot-1.3.0.tgz]' \
-        'Installs to a new private prefix. Does not replace an existing global install,' \
-        'change configuration, authenticate Codex, start a bot or install a service.'
-      exit 0 ;;
-    *) fail "Unknown argument: $1" ;;
+# The function is parsed in full before installation starts, including when piped.
+sintbot_install() (
+  set -eu
+  version=1.4.1
+  prefix="${SINTBOT_INSTALL_DIR:-$HOME/.local/share/sintbot}"
+  fail() { printf 'SintBot: %s\n' "$*" >&2; exit 1; }
+  case "${1:-}" in
+    '') [ "$#" -eq 0 ] || fail 'Unexpected arguments.' ;;
+    --dry-run) [ "$#" -eq 1 ] || fail 'Unexpected arguments.' ;;
+    *) fail 'Usage: bash install.sh [--dry-run]' ;;
   esac
-done
-[ "$(uname -s)" = Darwin ] || fail 'This release supports macOS only.'
-command -v node >/dev/null 2>&1 || fail 'Install Node.js 22 or newer, then run this installer again.'
-command -v npm >/dev/null 2>&1 || fail 'npm is required.'
-node -e 'if (Number(process.versions.node.split(".")[0]) < 22) process.exit(1)' || fail 'Node.js 22 or newer is required.'
-case "$PREFIX" in /*) ;; *) fail '--prefix must be an absolute path.' ;; esac
-PREFIX="$(node -e 'process.stdout.write(require("node:path").resolve(process.argv[1]))' "$PREFIX")" || fail 'Invalid prefix.'
-[ "$PREFIX" != / ] || fail 'The filesystem root is not an installation prefix.'
-[ ! -e "$PREFIX" ] && [ ! -L "$PREFIX" ] || fail 'The target already exists; use a new prefix. Existing installations are never overwritten.'
-if [ "$PACKAGE" != "sintbot@${VERSION}" ]; then
-  case "$PACKAGE" in /*.tgz) ;; *) fail '--package must name an absolute local .tgz file.' ;; esac
-  [ -f "$PACKAGE" ] || fail 'The local package does not exist.'
-fi
-printf '%s\n' "SintBot ${VERSION}: isolated install into ${PREFIX}" 'Scope: macOS, one Feishu group, Codex messages; foreground operation.'
-if [ "$DRY" = 1 ]; then
-  printf '%s\n' "Would install ${PACKAGE}, verify version/binary/platform loading, then show setup instructions." 'Preview complete. No changes were made.'
-  exit 0
-fi
-PARENT="$(dirname "$PREFIX")"
-mkdir -p -- "$PARENT" || fail 'Cannot create the installation parent.'
-LOCK="${PREFIX}.install-lock"
-if ! mkdir -- "$LOCK" 2>/dev/null; then LOCK=''; fail 'Another install or a stale install lock exists; inspect it before retrying.'; fi
-[ ! -e "$PREFIX" ] && [ ! -L "$PREFIX" ] || fail 'The target appeared during installation; refusing to overwrite it.'
-STAGE="$(mktemp -d "${PARENT}/.sintbot-${VERSION}.XXXXXX")" || fail 'Cannot create staging directory.'
-if ! npm install --registry=https://registry.npmjs.org --global --prefix "$STAGE" --omit=dev --ignore-scripts --no-audit --no-fund "$PACKAGE"; then
-  fail 'Package installation failed; the previous installation was not changed.'
-fi
-if ! node - "$STAGE/lib/node_modules/sintbot" "$VERSION" <<'NODE'
-const path = require('node:path')
-const root = process.argv[2]
-const pkg = require(path.join(root, 'package.json'))
-if (pkg.name !== 'sintbot' || pkg.version !== process.argv[3]) throw new Error('Package version mismatch')
-if (pkg.bin?.sintbot !== 'bin/sintbot-v2.js') throw new Error('Package does not use the supported 1.3.0 entry')
-require(path.join(root, 'src/agent/privatecore.js'))
-require(path.join(root, 'src/platform/feishu.js'))
+  [ "$(uname -s)" = Darwin ] || fail 'macOS is required.'
+  command -v node >/dev/null 2>&1 || fail 'Install Node.js 22 or newer first.'
+  command -v npm >/dev/null 2>&1 || fail 'npm is required.'
+  node -e 'if (+process.versions.node.split(".")[0] < 22) process.exit(1)' || fail 'Node.js 22 or newer is required.'
+  case "$prefix" in /*) ;; *) fail 'SINTBOT_INSTALL_DIR must be an absolute path.' ;; esac
+  [ "$prefix" != / ] || fail 'Choose an installation directory, not the filesystem root.'
+  printf 'Installing SintBot %s to %s\n' "$version" "$prefix"
+  [ "${1:-}" != --dry-run ] || { printf 'Preview only. No changes made.\n'; exit 0; }
+  npm install --registry=https://registry.npmjs.org --global --prefix "$prefix" \
+    --omit=dev --ignore-scripts --no-audit --no-fund "sintbot@$version"
+  node - "$prefix/lib/node_modules/sintbot" "$version" <<'NODE'
+const path = require('node:path');
+const root = process.argv[2];
+const pkg = require(path.join(root, 'package.json'));
+if (pkg.name !== 'sintbot' || pkg.version !== process.argv[3] || pkg.bin?.sintbot !== 'bin/sintbot-v2.js') {
+  throw new Error('Installed package verification failed');
+}
+require(path.join(root, 'src/agent/privatecore.js'));
+require(path.join(root, 'src/platform/feishu.js'));
 NODE
-then fail 'Installed package failed version, entry or runtime verification.'; fi
-ACTUAL="$("$STAGE/bin/sintbot" --version)" || fail 'Installed executable did not start.'
-[ "$ACTUAL" = "$VERSION" ] || fail 'Installed executable reported an unexpected version.'
-[ ! -e "$PREFIX" ] && [ ! -L "$PREFIX" ] || fail 'The target appeared during installation; refusing to overwrite it.'
-if ! mv -- "$STAGE" "$PREFIX"; then fail 'Cannot finalize the isolated install.'; fi
-STAGE=''
-FINAL_VERSION="$("$PREFIX/bin/sintbot" --version)" || fail 'Final executable failed after relocation; inspect the new prefix before retrying.'
-[ "$FINAL_VERSION" = "$VERSION" ] || fail 'Final executable version mismatch.'
-printf '\n%s\n' "Installed and verified SintBot ${VERSION}. Existing services and configuration were not changed." \
-  'Finish the one-group configuration and first run using:' \
-  'https://github.com/sintlab/sintbot/blob/v1.3.0/docs/install.md' \
-  'Use this exact executable for the new installation:'
-printf '  %q\n' "$PREFIX/bin/sintbot"
-printf '%s\n' 'An existing multi-group installation must stay on its current version.' \
-  'Do not delete old state or receipts to make initialization succeed.'
+  [ "$("$prefix/bin/sintbot" --version)" = "$version" ] || fail 'Executable verification failed.'
+  printf '\nInstalled and verified SintBot %s.\n' "$version"
+  printf 'Connect your project: https://sintbot.com/guide/install/#feishu\n'
+)
+sintbot_install "$@"