sintbot 1.4.16 → 1.4.18

package/docs/zh-CN/install.md

@@ -1,4 +1,4 @@
-# 安装 SintBot 1.4.16
+# 安装 SintBot 1.4.18
 
 [English](../install.md) · 简体中文
 
@@ -10,13 +10,61 @@
 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.18` 装到 `~/.local/share/sintbot`，并验证程序入口、内置核心和飞书模块。看到 `Installed and verified SintBot 1.4.18` 就可以继续。不需要 sudo。
 
 可选预览：在命令末尾加 `-s -- --dry-run`。要自定义安装位置，设置 `SINTBOT_INSTALL_DIR` 环境变量，并同步修改后面的可执行文件路径。
 
-## 2. 连接飞书
+## 2. 在浏览器里接入飞书（推荐）
 
-在 [飞书开放平台](https://open.feishu.cn/) 创建企业自建应用，启用机器人、接收和回复消息的权限，事件订阅选择长连接并订阅消息接收；回调订阅同样选择长连接接收回调并订阅卡片回传交互（群里点选 `/model` 卡片要用）。发布应用后，把机器人加入要使用的群，取得每个群的 `oc_…` 群 ID。
+前提：手机飞书当前处于企业/团队身份；没有组织的个人身份扫不了，需先新建一个团队（免费）。扫码创建的应用归扫码人所在的组织，审批与否取决于组织设置。
+
+```bash
+"$HOME/.local/share/sintbot/bin/sintbot" start --ui
+```
+
+还没有配置文件时，这条命令不会报错，而是在本机打开接入页（`http://127.0.0.1:4600`，只有这台 Mac 能访问）。页面上填项目名（默认 `sintbot`，会在 `~/Projects` 下新建并放一份 `README.md`）或选一个已有目录，两个执行器都装了就选一个，不是组织管理员就勾上精简接入，然后点「开始扫码」。用手机飞书扫页面上的二维码并确认。接下来它依次：取得应用凭证 → 自检 → 放开通讯录范围与可用范围并发布版本 → 创建群并把你拉进去 → 新建项目目录 → 写入 `~/.sbot/config.json` → 初始化消息日志，每一步的结果都显示在页面上。扫码一旦确认，应用就已在你的组织里创建；之后任一检查失败都会在建目录、写配置之前停下，页面给出「重试」（复用已创建的应用，不会再建一个）；自动建群失败时页面会让你手动建群、拉入机器人，粘贴群 ID 后点「继续」。
+
+显示二维码前会读取所选执行器的实时型号清单，在页面显示推荐型号和思考深度，并明确保存到新群配置。清单暂时取不到时会在创建应用之前停下；检查执行器登录和网络后重试。接入后可在控制台或通过 `/model` 调整，已有群的选择不会被覆盖。
+
+接入完成后服务直接接着启动，页面几秒后切到控制台。保持终端开启。在新群里发“读取项目 README 的第一行，只回复这一行”，并和项目目录里的 `README.md` 对照。
+
+### 终端方式
+
+不想开浏览器也可以在终端做同一件事，参数对应页面上的选项：
+
+```bash
+"$HOME/.local/share/sintbot/bin/sintbot" connect
+```
+
+在交互终端里它会先问项目名（直接回车即用默认的 `sintbot`），然后打印扫码链接，并打开一个本机页面显示二维码；步骤与上面相同，结果打印在终端，失败时给出带 `--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. 日常启动
+
+接入完成后以后每次启动都用同一条命令；配置在默认位置时和接入时那条一样：
+
+```bash
+"$HOME/.local/share/sintbot/bin/sintbot" start --ui
+```
+
+它会预检配置和执行器、连接飞书并打开本机控制台。保持终端开启。用了 `--config` 或 `--data-dir` 的，启动时带同样的参数。预检通过不代表飞书认证或消息送达已经验证。
+
+## 4. 手动接入（备选）
+
+扫码失败、管理员不放行，或者想自己管理应用时，走下面的手动路径；内容与之前的安装步骤相同。
+
+<details>
+<summary>展开手动步骤</summary>
+
+#### 4.1 创建应用
+
+在 [飞书开放平台](https://open.feishu.cn/) 创建企业自建应用，启用机器人，在「权限管理」开通与扫码接入相同的权限：`im:message.group_msg`、`im:message:readonly`、`im:message:send_as_bot`、`im:resource`、`im:message.reactions:write_only`、`im:chat`、`cardkit:card:write`、`contact:contact.base:readonly`、`contact:department.base:readonly`、`contact:user.base:readonly`，并在「数据权限」把通讯录授权范围设为全部成员；事件订阅选择长连接并订阅消息接收；回调订阅同样选择长连接接收回调并订阅卡片回传交互（群里点选 `/model` 卡片要用）。发布应用后，把机器人加入要使用的群，取得每个群的 `oc_…` 群 ID。
 
 在 macOS 默认终端中输入应用凭据（密钥输入时不显示）：
 
@@ -29,7 +77,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 +117,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 +132,8 @@ SINTBOT="$HOME/.local/share/sintbot/bin/sintbot"
 
 在群里发“读取项目 README 的第一行，只回复这一行”，并和本地文件对照。预检通过不代表飞书认证或消息送达已经验证。
 
+</details>
+
 ## 5. 在群里使用
 
 直接发文字就是给它派任务。回复以卡片呈现：模型开始输出时出现；25 秒还没有输出也会先出现。运行中卡片显示已跑多久、正在做什么和已完成的步骤，结束后这些步骤收进「过程」折叠区。
@@ -95,16 +145,18 @@ SINTBOT="$HOME/.local/share/sintbot/bin/sintbot"
 | `/stop` | 停止当前任务，连同排队的一起取消；之前的对话保留 |
 | `/new` | 忘掉之前的对话，开始新的一段（只在本群空闲时生效） |
 | `/model` | 打开点选卡，选后端、型号和思考深度后点「确认更新」；也可直接发 `/model high`、`/model 型号`、`/model 后端`。换型号或调深度接着当前对话，换后端开始新的一段对话；只在本群空闲时生效 |
-| `/hud` | 当前模型的额度与本段对话的用量 |
+| `/hud` | 当前模型的额度与本段对话的用量；Claude 群还显示空闲整理线和上次整理时间 |
 | `/issue 一句话` | 记下问题反馈，在控制台概览里查看和标记处理 |
 | `/help` | 查看可用命令，以及本群的项目和模型 |
 
-命令单独发一条；除 `/issue` 和 `/model` 外，后面不要跟别的字。如果飞书应用还订阅了消息撤回事件（控制台接入引导里建议订阅），撤回自己发的消息即取消那件事：还在排队的直接丢弃；当前任务只由这一条触发时会停下；两种执行器中，撤回已交给执行器的补话均会取消整轮，包括已受理但尚未读取的补话。
+命令单独发一条；除 `/issue` 和 `/model` 外，后面不要跟别的字。如果飞书应用还订阅了消息撤回事件（扫码接入会自动订阅，手动接入建议一并订阅），撤回自己发的消息即取消那件事：还在排队的直接丢弃；当前任务只由这一条触发时会停下；两种执行器中，撤回已交给执行器的补话均会取消整轮，包括已受理但尚未读取的补话。
 
 Codex 和 Claude Code 的忙时跟进默认开启；`steer:false` 改为排队，显式 `steer` 优先于旧 Codex 开关。Claude Code 未提供所需输入能力时保留排队。长工具调用可能延迟读取；确认读取后回复卡才跟随补话，续轮答案合并为一条最终回复。某一轮模型报错或没有结果时，只在本群提示重新发送，不会自动重试。某个群上一轮的结果无法确认时（例如回复是否送达不明），只暂停这个群，它收到新消息会回一句说明，其他群照常；不重放、不重试。
 
 回复卡移到已确认读取的补话下方时，会立即保留已有文字，后续输出继续更新；移动卡片不会重新启动任务。
 
+走 Claude Code 的群会在一轮结束、群里没人等的时候整理会话：上下文到了模型卡「压缩」阈值的一半，就对同一会话跑一次 `/compact`，群里不发消息，新消息到来会先停掉整理再开始这一轮。整理占一个并发名额，只在还有空余名额时进行；阈值为 0 时不整理。Claude 订阅额度改从每轮自带的额度事件读取，额度接口最多半小时查一次。
+
 ## 6. 控制台
 
 型号与思考深度按群选：在「群 · 项目」卡的「模型」行选后端和型号，下一行选深度，清单取自本机 Codex / Claude Code 的实时数据；订阅登录的模型卡上不再设型号和深度，第三方端点的型号仍在模型卡上设置。升级后，模型卡上原有的型号和深度会自动写进各群，生效值不变、会话不重置，改前备份配置。模型卡区分设置值与运行回报，容量依据可在「容量与运行信息」中查看。Codex 上下文窗口和各模型自动压缩都只提供「执行器默认 / 自定义」，仅自定义时显示数值输入；从下轮生效，保留当前会话。Codex 自定义窗口不能超过已知目录上限。压缩值对 Codex 表示阈值，对 Claude Code 表示窗口，实际可能提前触发。旧配置中的全局压缩值会转换为原有各模型的独立值，已有逐模型设置优先；新模型默认交给执行器，不继续继承旧全局值。读取不改磁盘，下一次正常保存配置时写入转换结果。
@@ -123,7 +175,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.18
   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.18",
   "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,8 @@
     "src/c2upgradeswitch.js",
     "src/cdp.js",
     "src/config.js",
+    "src/connect.js",
+    "src/setupserver.js",
     "src/consolesay.js",
     "src/consoletrials.js",
     "src/core/brain.js",

package/src/agent/claudecode.js

@@ -96,7 +96,13 @@ function normalizeEvent(ev) {
   const result = claudeNormalizeEvent(ev)
   // JSON cannot carry `undefined`; retain the frozen JS object's optional
   // property shape at the public runner boundary.
-  if (ev.type === 'system') { result.subtype = ev.subtype; result.sessionId = ev.session_id }
+  if (ev.type === 'system') {
+    result.subtype = ev.subtype; result.sessionId = ev.session_id
+    // init 里 CLI 自报的可用命令:含 compact ⇒ 可以空闲整理(ABI 37 idle_compact_plan 的 canCompact);
+    // 2.1.311 实测在 slash_commands 里。哪版拿掉了,引擎就只在轮内压缩。
+    if (ev.subtype === 'init' && Array.isArray(ev.slash_commands)) result.slashCommands = ev.slash_commands.filter(c => typeof c === 'string')
+    // 压缩边界(compact_boundary)的 preTokens 由核心 normalize 带出,引擎据此判整理成败。
+  }
   else if (ev.type === 'assistant' || ev.type === 'user') {
     result.sessionId = ev.session_id
     if (ev.type === 'assistant') for (const tool of result.tools) {
@@ -158,6 +164,8 @@ function runTurn({
   softStopGraceMs = 10000,
   steer = false, onSteerReady, onSteerLanded,
   steerReceiptTimeoutMs = 10000, steerHoldMs = 20000, interruptGraceMs = 2000,
+  requireCloseProof = false,
+  closeProofGraceMs = 3000,
   closeGraceMs = 3000, // short: the grace starts AFTER the answer, so we're only waiting for
   // the OS to close a possibly-clinging pipe (MCP browser children / cmd.exe shim). Claude
   // persists its session continuously, so killing ~3s post-answer is safe → the group frees
@@ -270,6 +278,7 @@ function runTurn({
       let aborted = false
       let killTimer = null
       let closeTimer = null
+      let closeProofTimer = null
       let settled = false
       let childCloseObserved = false
       let acceptanceFailed = false
@@ -279,7 +288,7 @@ function runTurn({
       // Resolution is guarded (exactly once) because a close-grace timer can force the
       // turn to settle before the 'close' event fires — otherwise a lingering pipe would
       // wedge the per-group lock forever (never-hang invariant).
-      const finish = (fn) => { if (settled) return; settled = true; followup?.dispose(); if (killTimer) clearTimeout(killTimer); if (closeTimer) clearTimeout(closeTimer); if (signal) signal.removeEventListener('abort', onAbort); fn() }
+      const finish = (fn) => { if (settled) return; settled = true; followup?.dispose(); if (killTimer) clearTimeout(killTimer); if (closeTimer) clearTimeout(closeTimer); if (closeProofTimer) clearTimeout(closeProofTimer); if (signal) signal.removeEventListener('abort', onAbort); fn() }
       const resolveRun = result => {
         if (childCloseObserved) closedRunnerResults.add(result)
         resolve(result)
@@ -335,6 +344,14 @@ function runTurn({
         closeTimer = setTimeout(() => {
           if (!aborted && !(lastResult && lastResult.authFailed)) log(`claude 答案已到但 ${closeGraceMs}ms 内没退出 ⇒ 强制收尾;本轮若起过后台命令(run_in_background),它会被一起收掉,下一轮可能空转一次`)
           killTree()
+          // Compaction shares a resumable session with the next turn. A result
+          // or a sent signal does not prove the process closed its files.
+          if (requireCloseProof && !childCloseObserved) {
+            closeProofTimer = setTimeout(() => finish(() => reject(Object.assign(
+              new Error('Claude compaction process close remains unproven'),
+              { code: 'CLAUDE_COMPACTION_CLOSE_UNPROVEN' }))), closeProofGraceMs)
+            return
+          }
           const complete = () => finish(() => resolveRun({ sessionId: capturedSessionId, result: lastResult, code: null, aborted }))
           if (onDurableEvent) durableWork.then(complete, failDurableEvent)
           else complete()
@@ -435,6 +452,11 @@ function runTurn({
             armCloseGrace()
             continue
           }
+          // 额度事件(ABI 37):订阅登录的 Claude 每次运行都带回 5 小时窗 / 7 天窗已用比例 —— 喂进额度缓存,
+          // 页脚与 /hud 就不必再去打那个常被限流的额度接口。第三方端点 / 自带密钥不是订阅额度,不喂。
+          if (raw.type === 'rate_limit_event' && isSubscription(provider)) {
+            try { require('./claudeusage').noteRateLimit(raw.rate_limit_info) } catch { /* 额度显示出错不能碰轮次 */ }
+          }
           let ev
           try { ev = normalizeEvent(raw) } catch (error) { failCore(error); return }
           if (ev.sessionId) capturedSessionId = ev.sessionId
@@ -572,4 +594,20 @@ function probeVersion(bin = 'claude') {
   })
 }
 
-module.exports = { runTurn, isClosedRunnerResult, isClosedRunnerError, buildEnv, normalizeEvent, probeVersion, supportsFlag, BASE_SKILL_ALLOWS }
+// 这一份 provider 跑的是不是本机登录的 Claude 订阅(额度事件只对它有意义)。env 里另指了端点 / 令牌的也不算。
+function isSubscription(provider = {}) {
+  const env = provider.env || {}
+  return !provider.baseUrl && !provider.apiKey && !env.ANTHROPIC_BASE_URL && !env.ANTHROPIC_AUTH_TOKEN && !env.ANTHROPIC_API_KEY
+}
+
+// 空闲整理(ABI 37,核心 idle_compact_plan 决定起不起、保留什么):对同一个会话跑一次 `/compact`。
+// ⚠ 参数必须与平时轮次**完全相同**(引擎用同一组启动参数):工具定义在提示最前面,换了工具集 / MCP / 系统提示附录,
+//   整段会话的缓存全部失效(旧 sbot 11-12 实测换工具集缓存写入 2.6 倍)。输入一律纯文本,不开跟进通道。
+// 停:引擎的 abort signal ⇒ 与普通轮同一条两段式收尾。结果:onEvent 收到 system/compact_boundary(preTokens)与 result。
+function compactSession(opts = {}) {
+  const { onSteerReady, onSteerLanded, steer, prompt, onDurableEvent, onTurnAccepted, keep, ...rest } = opts
+  if (!keep) return Promise.reject(new Error('compactSession: keep required'))
+  return runTurn({ ...rest, requireCloseProof: true, prompt: '/compact ' + keep })
+}
+
+module.exports = { runTurn, compactSession, isSubscription, isClosedRunnerResult, isClosedRunnerError, buildEnv, normalizeEvent, probeVersion, supportsFlag, BASE_SKILL_ALLOWS }

package/src/agent/claudeusage.js

@@ -171,7 +171,56 @@ const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms))
 // 里所有人都查不到额度(而这接口恰恰偶发超时/限流);完全不压又让连点几下就把限流捅穿。
 // 10 秒 = 人再问一次就真的重试,机器连点仍被挡住。
 const RAW = { at: 0, data: null }
+
+// ── 额度事件(ABI 37)──────────────────────────────────────────────────────────
+// claude CLI 每次运行都在 stream 里吐一个 `rate_limit_event`(订阅登录时),runner 收到就喂进来;解析在核心
+// `usage_parse('claude','event')`。EVENT_TTL 内有事件 ⇒ 5 小时窗 / 7 天窗用它,不打接口;按模型分的周窗
+// 事件里没有的窗口仍取接口；事件新鲜时接口最多 SCOPED_TTL 请求一次，避免频繁探测触发限流。
+const EVENT_TTL_MS = 10 * 60_000
+const SCOPED_TTL_MS = 30 * 60_000
+const EVT = { at: 0, windows: null } // windows: { session?: {percent, resetsAt, at}, weekly_all?: {…} }
+const EVENT_KIND = { session: 'session', weekly: 'weekly_all' } // 核心的窗口名 → 接口 limits[] 的 kind
+function noteRateLimit(info, now = Date.now()) {
+  if (!info || typeof info !== 'object') return false
+  let parsed
+  try { parsed = require('./privatecore').usageParse('claude', 'event', null, info, now) } catch { return false }
+  if (!parsed.ok) return false
+  const windows = {}
+  for (const w of parsed.windows) {
+    const kind = EVENT_KIND[w.kind]
+    if (kind) windows[kind] = { percent: w.percentUsed, resetsAt: w.resetsAt ?? null, at: now }
+  }
+  if (!Object.keys(windows).length) return false
+  EVT.windows = { ...(EVT.windows || {}), ...windows } // 只有一个窗时别把另一个窗的旧值丢了
+  EVT.at = now
+  // A new event must be visible immediately without invalidating the endpoint cache.
+  CACHE.at = 0; CACHE.val = null
+  return true
+}
+const eventFresh = (now = Date.now()) => !!(EVT.at && now - EVT.at < EVENT_TTL_MS && EVT.windows)
+// 事件与接口数据合成 parseLimits 的形状;同一个窗两边都有 ⇒ 取更新的那份(人点了「刷新」时接口比事件新)。
+function mergeEvent(limits, dataAt, now = Date.now()) {
+  const out = Array.isArray(limits) ? limits.slice() : []
+  for (const [kind, w] of Object.entries(EVT.windows || {})) {
+    if (!w || now - w.at >= EVENT_TTL_MS) continue
+    const i = out.findIndex(l => l && l.kind === kind)
+    if (i >= 0 && dataAt > w.at) continue
+    const row = { kind, percent: w.percent, resetsAt: w.resetsAt, scopeName: '' }
+    if (i >= 0) out[i] = row; else out.push(row)
+  }
+  return out
+}
+function clearEvents() { EVT.at = 0; EVT.windows = null } // 单测用
+
 async function fetchRaw(token, { ttl = 60_000, now = Date.now, log = warn, curl = fetchCurl, sleep = sleepMs } = {}) {
+  const t = now()
+  if (eventFresh(t)) {
+    // 事件新鲜:接口只为补「按模型分的周窗」,最多 SCOPED_TTL 打一次(成败都算一次 —— 限流时不连环重试)。
+    if ((RAW.at && t - RAW.at < SCOPED_TTL_MS) || !token) return RAW.data
+    const data = await curl(token, { log }) // 不重试:事件已经给了主要的两个窗
+    RAW.at = now(); RAW.data = data
+    return data
+  }
   if (RAW.at && now() - RAW.at < (RAW.data ? ttl : FAIL_TTL_MS)) return RAW.data
   // 只走 curl(纪律 1);失败隔一下再问一次 —— 超时与短限流重试一次往往就通,再不通就认了。
   let data = await curl(token, { log })
@@ -180,21 +229,206 @@ async function fetchRaw(token, { ttl = 60_000, now = Date.now, log = warn, curl
   return data
 }
 
+// ── 令牌过期兜底(2026-11-12,cc-switch takeaways B3)──────────────────────────────
+// 纪律 2 不变:我们**不刷新**令牌。过期时让 Claude CLI 自己在自己的锁里刷新 —— 跑一次
+// `claude -p /usage`(官方的非交互用量面板),它顺手把额度写进 `~/.claude.json` 的
+// `cachedUsageUtilization`,我们只读那份缓存,交给核心 `usage_parse('claude','cached')` 判
+//(当前 CLI 使用 fetchedAtMs + utilization.limits;旧 limits[] 也保留支持，超过 645 秒判旧)。
+// 约束:
+//   · **不阻塞调用方**:需要刷新时在后台起跑(进程内一次一个),本次立刻回 null(或在跑期间回
+//     上一次解析出的值);之后的调用再读结果。/hud、/api/claude/verify 都是秒级回复。
+//   · **只信本进程跑成功后的文件**:退出码 0 才记一次「刷新完成时刻」,读文件以它为准;文件
+//     里没有 fetchedAt 时就用这个完成时刻 —— 别的进程(交互式 CLI)写的旧缓存不当新数。
+//     跑失败 / 超时 ⇒ null。
+//   · 同账号(按凭据文件路径)10 分钟最多跑一次 · 45 秒后 SIGTERM、再 5 秒 SIGKILL,子进程
+//     没 close 之前不会起下一个 · 旗子探测合成一次(短超时、有缓存),老 CLI 不认 ⇒ 跳过。
+//   · env 走 buildEnv({}) 再去掉 ANTHROPIC_API_KEY(只认 OAuth 登录态,别让 /usage 打到 API key
+//     或第三方网关)· cwd 用临时目录(别让它读到哪个项目的 CLAUDE.md / .mcp.json)· 输出不看不记。
+const FALLBACK_TIMEOUT_MS = 45_000
+const FALLBACK_KILL_GRACE_MS = 5_000
+const FALLBACK_INTERVAL_MS = 10 * 60_000
+const FALLBACK_FLAG_PROBE_MS = 2_000
+const FALLBACK_ARGS = Object.freeze(['-p', '/usage', '--output-format', 'json', '--tools', '', '--strict-mcp-config', '--setting-sources', '', '--no-session-persistence'])
+const FALLBACK_FLAGS = Object.freeze(['--tools', '--strict-mcp-config', '--setting-sources', '--no-session-persistence'])
+const USAGE_HELP_INFLIGHT = new Map()
+
+// Some native CLI builds exit before a long help page drains through a pipe.
+// A private regular file receives the complete page. The four flag checks share
+// one bounded process; this temporary file contains help text only.
+function supportsUsageFlag(bin, flag) {
+  let probe = USAGE_HELP_INFLIGHT.get(bin)
+  if (!probe) {
+    probe = (async () => {
+      const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'sintbot-usage-help-'))
+      const file = path.join(dir, 'help.txt')
+      let fd
+      try {
+        fd = fs.openSync(file, 'wx', 0o600)
+        const ok = await new Promise(resolve => {
+          let child, timer, force, settled = false
+          const finish = value => { if (settled) return; settled = true; clearTimeout(timer); clearTimeout(force); resolve(value) }
+          try {
+            const command = require('./winexec').resolveSpawn(bin, ['--help'])
+            child = require('node:child_process').spawn(command.file, command.spawnArgs,
+              { cwd: dir, stdio: ['ignore', fd, 'ignore'], windowsHide: true })
+          } catch { return finish(false) }
+          child.once('error', () => finish(false))
+          child.once('close', code => finish(code === 0))
+          timer = setTimeout(() => {
+            try { child.kill('SIGTERM') } catch {}
+            force = setTimeout(() => { try { child.kill('SIGKILL') } catch {} }, 1000)
+            force.unref?.()
+          }, 5000)
+          timer.unref?.()
+        })
+        if (!ok || fs.statSync(file).size > 1024 * 1024) return null
+        return await fs.promises.readFile(file, 'utf8')
+      } finally {
+        if (fd !== undefined) fs.closeSync(fd)
+        await fs.promises.rm(dir, { recursive: true, force: true })
+      }
+    })().catch(() => null)
+    USAGE_HELP_INFLIGHT.set(bin, probe)
+    probe.finally(() => { if (USAGE_HELP_INFLIGHT.get(bin) === probe) USAGE_HELP_INFLIGHT.delete(bin) })
+  }
+  return probe.then(text => text === null ? null : text.includes(flag))
+}
+const FALLBACK = {
+  inflight: null,       // 正在跑的那次(Promise<boolean>);子进程 close 前不清
+  lastAt: new Map(),    // 凭据文件路径 -> 上次起跑时刻(节流)
+  doneAt: new Map(),    // 凭据文件路径 -> 本进程最近一次退出码 0 的完成时刻(没有 = 不信文件)
+  lastGood: new Map(),  // 凭据文件路径 -> 上一次解析出的一行(只在刷新进行中回它)
+  flags: null,          // { bin, until, p } 合成一次的旗子探测
+  file: null,           // { path, mtimeMs, body } 按 mtime 缓存的 ~/.claude.json 解析
+}
+
+// `~/.claude.json` 原文 → 交给核心的 body(cachedUsageUtilization 原样)。不是对象 ⇒ null。
+// 时效优先用对象自带的 fetchedAtMs/fetchedAt;两者都没有才用本进程刷新完成时刻。
+function readCachedUtilization(raw) {
+  let j = null
+  try { j = JSON.parse(String(raw || '')) } catch { return null }
+  const u = j && j.cachedUsageUtilization
+  return u && typeof u === 'object' && !Array.isArray(u) ? u : null
+}
+
+// 按 mtime 缓存的异步读:同一份文件只解析一次;stat/读失败 ⇒ null。
+async function readClaudeJson(file, { readFile, stat }) {
+  let st = null
+  try { st = await stat(file) } catch { return null }
+  const mtimeMs = st && typeof st.mtimeMs === 'number' ? st.mtimeMs : null
+  const c = FALLBACK.file
+  if (c && c.path === file && mtimeMs !== null && c.mtimeMs === mtimeMs) return c.body
+  let raw = null
+  try { raw = await readFile(file, 'utf8') } catch { return null }
+  const body = readCachedUtilization(raw)
+  FALLBACK.file = { path: file, mtimeMs, body }
+  return body
+}
+
+// 核心的 windows[] → parseLimits 的形状,formatClaudeUsage 原样可用。
+const windowsToLimits = (windows) => (Array.isArray(windows) ? windows : [])
+  .map((w) => ({ kind: w.kind, percent: w.percentUsed, resetsAt: w.resetsAt ?? null, scopeName: w.scopeName || '' }))
+
+// 四个旗子合成**一次**探测:默认共享同一份完整 --help 输出，测试可注入探测函数。
+// 短超时兜底;结论 true/false 缓存 10 分钟、不知道(null)缓存 60 秒。
+function probeFlags(bin, supportsFlag, now, timeoutMs = FALLBACK_FLAG_PROBE_MS) {
+  const hit = FALLBACK.flags
+  if (hit && hit.bin === bin && now() < hit.until) return hit.p
+  const all = Promise.all(FALLBACK_FLAGS.map((f) => Promise.resolve().then(() => supportsFlag(bin, f))))
+    .then((a) => (a.every((v) => v === true) ? true : a.some((v) => v === false) ? false : null))
+  const late = new Promise((resolve) => { const t = setTimeout(() => resolve(null), timeoutMs); t.unref?.() })
+  const p = Promise.race([all, late]).catch(() => null)
+  FALLBACK.flags = { bin, until: now() + 60_000, p }
+  p.then((v) => { if (FALLBACK.flags && FALLBACK.flags.p === p) FALLBACK.flags.until = now() + (v === null ? 60_000 : 10 * 60_000) })
+  return p
+}
+
+// 跑一次 `claude -p /usage`;只在子进程 close(或起不来)后才落定 ⇒ 卡住的子进程不会与下一次重叠。
+// 超时:SIGTERM,再过 killGraceMs 还没 close 就 SIGKILL;两个计时器都 unref。
+function runUsageRefresh({ bin, spawn, buildEnv, tmpdir, log, timeoutMs, killGraceMs = FALLBACK_KILL_GRACE_MS }) {
+  return new Promise((resolve) => {
+    let child, settled = false, timedOut = false
+    const timers = []
+    const done = (ok, why) => { if (settled) return; settled = true; for (const t of timers) clearTimeout(t); if (why) log(why); resolve(ok) }
+    const later = (ms, fn) => { const t = setTimeout(fn, ms); t.unref?.(); timers.push(t) }
+    try {
+      const env = buildEnv({})
+      delete env.ANTHROPIC_API_KEY // 只认 OAuth 登录态
+      const { file, spawnArgs } = require('./winexec').resolveSpawn(bin, [...FALLBACK_ARGS])
+      child = spawn(file, spawnArgs, { cwd: tmpdir(), env, stdio: ['ignore', 'ignore', 'ignore'], windowsHide: true })
+    } catch (e) { return done(false, '额度兜底:claude 起不来(' + ((e && e.message) || '未知错误') + ')') }
+    later(timeoutMs, () => {
+      timedOut = true
+      try { child.kill('SIGTERM') } catch {}
+      later(killGraceMs, () => { try { child.kill('SIGKILL') } catch {} })
+    })
+    child.on('error', (e) => done(false, '额度兜底:claude 起不来(' + ((e && e.code) || (e && e.message) || '未知错误') + ')'))
+    child.on('close', (code) => {
+      if (timedOut) return done(false, `额度兜底:claude -p /usage 超时(${timeoutMs}ms),已终止`)
+      done(code === 0, code === 0 ? null : `额度兜底:claude -p /usage 退出码 ${code}`)
+    })
+  })
+}
+
+// 需要就在后台起一次刷新(不 await):进程内一次一个,同账号 10 分钟一次。
+function startRefreshIfDue(account, { bin, now, log, spawn, supportsFlag, buildEnv, tmpdir, timeoutMs, killGraceMs, intervalMs, flagProbeMs }) {
+  if (FALLBACK.inflight) return
+  const last = FALLBACK.lastAt.get(account) || 0
+  if (last && now() - last < intervalMs) return
+  FALLBACK.lastAt.set(account, now())
+  FALLBACK.inflight = (async () => {
+    const flags = await probeFlags(bin, supportsFlag, now, flagProbeMs)
+    if (flags !== true) { log('额度兜底:本机 claude 不认所需旗子,跳过'); return false }
+    const ok = await runUsageRefresh({ bin, spawn, buildEnv, tmpdir, log, timeoutMs, killGraceMs })
+    if (ok) FALLBACK.doneAt.set(account, now())
+    else FALLBACK.doneAt.delete(account)
+    return ok
+  })().catch(() => { FALLBACK.doneAt.delete(account); return false })
+    .finally(() => { FALLBACK.inflight = null })
+}
+
+// 过期/缺凭据时的那条腿:(必要时)后台让 CLI 刷新 → 读缓存(只信本进程刷成功后的)→ 核心判 →
+// 一行人话;任何一步不行 ⇒ null。调用方不会被挡住:这里只 await 一次文件读。
+async function cachedUsageFallback({ home = os.homedir(), bin = 'claude', now = Date.now, log = warn,
+  spawn = require('node:child_process').spawn, readFile = fs.promises.readFile, stat = fs.promises.stat, tmpdir = os.tmpdir,
+  supportsFlag = null, buildEnv = null, timeoutMs = FALLBACK_TIMEOUT_MS, killGraceMs = FALLBACK_KILL_GRACE_MS,
+  intervalMs = FALLBACK_INTERVAL_MS, flagProbeMs = FALLBACK_FLAG_PROBE_MS } = {}) {
+  const account = path.join(home, '.claude', '.credentials.json')
+  startRefreshIfDue(account, { bin, now, log, spawn, tmpdir, timeoutMs, killGraceMs, intervalMs, flagProbeMs,
+    supportsFlag: supportsFlag || supportsUsageFlag, buildEnv: buildEnv || require('./claudecode').buildEnv })
+  const doneAt = FALLBACK.doneAt.get(account)
+  if (!doneAt) return FALLBACK.inflight ? (FALLBACK.lastGood.get(account) || null) : null
+  const raw = await readClaudeJson(path.join(home, '.claude.json'), { readFile, stat })
+  if (!raw) return null
+  const body = raw.fetchedAtMs != null || raw.fetchedAt != null ? raw : { ...raw, fetchedAt: doneAt }
+  const parsed = require('./privatecore').usageParse('claude', 'cached', null, body, now())
+  if (!parsed.ok) return FALLBACK.inflight ? (FALLBACK.lastGood.get(account) || null) : null
+  const line = formatClaudeUsage(windowsToLimits(parsed.windows), now())
+  if (line) FALLBACK.lastGood.set(account, line)
+  return line
+}
+function resetFallback() { FALLBACK.inflight = null; FALLBACK.lastAt.clear(); FALLBACK.doneAt.clear(); FALLBACK.lastGood.clear(); FALLBACK.flags = null; FALLBACK.file = null }
+// 单测用:等后台那次刷新落定(没有就立刻回)。
+const settleFallback = () => (FALLBACK.inflight ? FALLBACK.inflight.then(() => undefined) : Promise.resolve())
+
 // 拉一次 → 一行人话;拿不到 null。走 fetchRaw ⇒ 与告警共享那份缓存。
 // 缓存口径与 fetchRaw 一致:成功 60s、失败 10s(两层都压死一分钟就白搭下层的重试了)。
+// 凭据缺失/过期 ⇒ 走 cachedUsageFallback(见上),不再直接 null。
 const CACHE = { at: 0, val: null }
 const TTL = 60_000
-async function usageLine({ ttl = TTL, now = Date.now, readToken = readAccessToken, ...io } = {}) {
+async function usageLine({ ttl = TTL, now = Date.now, readToken = readAccessToken, fallback = cachedUsageFallback, home, bin, ...io } = {}) {
   if (CACHE.at && now() - CACHE.at < (CACHE.val ? ttl : FAIL_TTL_MS)) return CACHE.val
   let val = null
   const token = readToken()
-  if (token) {
-    const data = await fetchRaw(token, { ttl, now, ...io })
-    val = formatClaudeUsage(parseLimits(data), now())
+  if (token || eventFresh(now())) { // 令牌读不到(钥匙串偶发)但有新鲜的额度事件,照样出数
+    const data = token ? await fetchRaw(token, { ttl, now, log: io.log, curl: io.curl, sleep: io.sleep }) : null
+    val = formatClaudeUsage(mergeEvent(parseLimits(data), RAW.at, now()), now())
+  } else {
+    try { val = await fallback({ now, ...(home ? { home } : {}), ...(bin ? { bin } : {}), ...io }) } catch { val = null }
   }
   CACHE.at = now(); CACHE.val = val
   return val
 }
 function clearCache() { CACHE.at = 0; CACHE.val = null; RAW.at = 0; RAW.data = null }
 
-module.exports = { usageLine, fetchRaw, clearCache, parseCredentials, parseLimits, formatClaudeUsage, readAccessToken, fetchCurl, fetchNative, readCurlResult, fmtDurDecimal, QUOTA_SEP, TIMEOUT_MS, FAIL_TTL_MS, RETRY_WAIT_MS }
+module.exports = { usageLine, fetchRaw, clearCache, clearEvents, noteRateLimit, eventFresh, mergeEvent, parseCredentials, parseLimits, formatClaudeUsage, readAccessToken, fetchCurl, fetchNative, readCurlResult, fmtDurDecimal, cachedUsageFallback, readCachedUtilization, readClaudeJson, supportsUsageFlag, resetFallback, settleFallback, QUOTA_SEP, TIMEOUT_MS, FAIL_TTL_MS, RETRY_WAIT_MS, FALLBACK_ARGS, FALLBACK_FLAGS, FALLBACK_TIMEOUT_MS, FALLBACK_KILL_GRACE_MS, FALLBACK_INTERVAL_MS, FALLBACK_FLAG_PROBE_MS }

package/src/agent/envconflicts.js

@@ -0,0 +1,74 @@
+'use strict'
+
+// Environment conflicts (2026-11-12, cc-switch takeaways B5): things outside
+// SintBot's configuration that can silently reroute the Claude / Codex CLI —
+// daemon env (`ANTHROPIC_*`, `CLAUDE_CODE_*`, `AWS_*`, `VERTEX_*`, `OPENAI_*`),
+// `~/.claude/settings.json` (`env`, top-level `model` …) and `~/.codex/config.toml`
+// (`model_provider`, `[model_providers.*]`). The host only gathers the inputs; the
+// rule set lives in the binary core (`env_conflicts`, ABI 36) and it returns key
+// names only — values never leave the process. Warn-only: `buildEnv` keeps clearing
+// exactly what it cleared before.
+
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { envConflicts } = require('./privatecore')
+
+// JSON file → parsed object; missing / invalid / not an object ⇒ null.
+function readClaudeSettings(home, readFile) {
+  try {
+    const j = JSON.parse(String(readFile(path.join(home, '.claude', 'settings.json'), 'utf8')))
+    return j && typeof j === 'object' && !Array.isArray(j) ? j : null
+  } catch { return null }
+}
+
+// TOML text as-is (the core matches lines; no TOML parser); missing ⇒ null.
+function readCodexConfig(home, readFile) {
+  try { return String(readFile(path.join(home, '.codex', 'config.toml'), 'utf8')) } catch { return null }
+}
+
+// Only string-valued entries travel to the core (process.env can hold undefined).
+const snapshotEnv = (env) => Object.fromEntries(Object.entries(env || {}).filter(([, v]) => typeof v === 'string'))
+
+// → [{ where: 'env'|'claude-settings'|'codex-config', key, reason }]. `provider` is a
+// resolved provider ({ baseUrl, apiKey }) or an explicit { baseUrl, hasApiKey }.
+function collectEnvConflicts({ runner = 'claude', provider = {}, env = process.env, home = os.homedir(), readFile = fs.readFileSync } = {}) {
+  const p = provider || {}
+  const input = {
+    runner: runner === 'codex' ? 'codex' : 'claude',
+    provider: { baseUrl: p.baseUrl || null, hasApiKey: typeof p.hasApiKey === 'boolean' ? p.hasApiKey : !!p.apiKey },
+    env: snapshotEnv(env),
+    claudeSettings: readClaudeSettings(home, readFile),
+    codexConfig: readCodexConfig(home, readFile),
+  }
+  return envConflicts(input).warnings.map((w) => ({ where: w.where, key: w.key, reason: w.reason }))
+}
+
+// Preflight / log line: `<key> — <reason>`; never a value.
+const describeWarning = (w) => `${w.key} — ${w.reason}`
+
+// `sintbot start --preflight`: one line per key for each provider an active route
+// uses. The snapshot is this process's environment — a launchd job inherits a
+// different one, so the block is prefixed with that caveat. Never fatal.
+const PREFLIGHT_SCOPE_LINE = 'preflight · 环境冲突检查基于当前终端环境(launchd 任务的环境可能不同)\n'
+function reportEnvConflicts({ cfg, routes } = {}, write = (message) => process.stderr.write(message), { collect = collectEnvConflicts } = {}) {
+  const seen = new Set()
+  let prefixed = false
+  for (const route of routes || []) {
+    if (!route || route.paused) continue
+    const name = route.group?.provider || cfg?.defaultProvider || ''
+    if (!name || seen.has(name)) continue
+    seen.add(name)
+    if (!prefixed) { prefixed = true; write(PREFLIGHT_SCOPE_LINE) }
+    try {
+      for (const warning of collect({ runner: route.provider?.runner, provider: route.provider })) {
+        write(`preflight · ${name}: ${describeWarning(warning)}\n`)
+      }
+    } catch (error) {
+      write(`preflight · ${name}: environment check skipped (${error?.message || String(error)})\n`)
+    }
+  }
+  return [...seen]
+}
+
+module.exports = { collectEnvConflicts, describeWarning, reportEnvConflicts, PREFLIGHT_SCOPE_LINE }