排障指南

排障的顺序：先看 tansr doctor（命令行）或错误码（其他形态），再按下面的表找处置；十之八九不用联系人。

第一步：`tansr doctor`

tansr doctor          # 人读报告
tansr doctor --json   # 机器可读

零模型调用、零网络、只读（不创建任何目录）；退出码 0 = 可用，1 = 有阻断问题。它呈现的是最近一次装配拉取的事实——控制台改了配置，跑一次 CLI 即刷新。TUI 内的 /doctor 是另一份更短的装配态检查单（见下），不影响退出码。

哪些算阻断

tansr doctor 只把四类问题计入阻断（退出码 1）：no_provider（没有任何可用 provider）、unresolved_model（缺省别名解析不到模型）、missing_credential（解析到的 provider 缺 API key 环境变量）、session_store_unwritable（会话存储目录不可写）。显式加 --connectors 探测部署连接器时，其阻断问题并入同一结论。其余各段都是归因与提示，不改退出码。

报告段对照表

段	正常长什么样	异常时怎么办	阻断？
配置来源与诊断	五层各自 loaded / absent，无 skipped；error 级诊断 0 条	skipped = 该层 JSONC 语法错误或根节点非对象，修文件或删掉；诊断逐条给层 / 键路径 / 期望类型，非法值已被剔除并回退更低层	否
provider / 模型解析 / 凭据	缺省别名 → provider / 模型；凭据在场，只以 `sk-...尾4位` 形态呈现	「未知的模型别名或 ref」核对 `modelAliases` 与 `providers.models`；「缺少 API key：环境变量 X 未设置」导出该变量	是（`no_provider` / `unresolved_model` / `missing_credential`）
`localProviders`（归因）	平台模式：本地 providers 被剪枝属预期；逃生态：出横幅	「未配置 provider」先看这里分清是没配还是被剪	否
凭据存储（归因）	密钥库	降级明文文件时确认目录权限；`tansr init` 重跑	否
模型选择归因	`model.selected` 值与提供层；压制态	项目层钉了 `modelAliases.main` 时用户层粘滞选择被压制，属预期	否
套餐	「个人（仅 CLI，无套餐费）」或「档名 · 到期 · 状态」	个人档不是故障；宽限 / 回落态到控制台续费	否
媒体工具	四面 `byo` / `platform` / `none`	全 `none` 附开通指引：自带端点三件变量，或请管理员开媒体池	否
无人值守基线	`auto` 且有隔离迹象	无迹象时显著提示；确认已隔离后 `TANSR_ISOLATED=1` 压制	否
上下文 / memory	窗口两值与钳位侧、活动方案、近 7 天压缩统计；记忆目录与索引占用	窗口未知 → 给模型声明 `maxContext`；非 production 方案只是警示	否
会话存储	会话数、字节、sidecar-only 目录、损坏目录；可写性探针通过	只读不代删；清理走 `tansr sessions prune`；目录不可写要修权限或换 `TANSR_STORAGE_ROOT`	不可写为阻断（`session_store_unwritable`）
工作区信任	已信任	未信任是你的显式选择，不是故障；要放开在 TUI 里 `/trust grant`	否

TUI 里的 `/doctor`

TUI 内 /doctor 是另一份零网络、零子进程的装配态自检，逐项 ✓ / ✗，清单以实际输出为准（写作时点 12 项）：node_version（≥ 22.19）、config_sources（五层无 skipped）、config_diagnostics（无 error 级诊断）、model_resolution、context_window、context_scheme（非 production 方案标警）、custom_commands（命令源无 skipped）、mcp_connections（懒台未连也算健康；失败台看错误码，/mcp reconnect）、terminal（TTY 与尺寸）、workspace_trust、output_style（风格名不存在会诚实报错）、session_driver_state（当前相位、代际、轮数与最近迁移；相位本身不是故障，这一项恒为 ✓）。✗ 只是提示，不等于 tansr doctor 的阻断问题。

命令行常见提示

症状	处置
「无法启动交互界面：当前不是交互式终端（TTY）」	在管道里启动了 `tansr`；脚本 / 管道场景改用 `tansr -p "<提示词>"`
「缺少 API token：请传 –token <值> 或设置 TANSR_SERVE_TOKEN」	`tansr serve` fail-closed，不会起无鉴权服务
「服务器启动失败」/ 「–port 的值无效」	端口被占或非法
「会话不存在」/ 「无法恢复会话」	`--resume` 的 id 不对或目录被占；`tansr --resume` 无参弹选择器核对
退出码 5 且提示 `tansr init`	无人值守形态未初始化；先登录或设 `TANSR_ESCAPE_LOCAL=1` 走本地模式
退出码 3	触顶：`--max-turns` / 预算 / 工具轮数；调大或拆任务
退出码 4	prompt 过长且压缩不可用；换更大窗口的模型
「并发已达套餐上限」横幅	只拒新会话；30 秒后再发或升级套餐

十个最常见的错误码

全部码的权威表在错误码表，这里只列最常撞到的十个与第一处置。

码	HTTP	你在哪会看到	第一处置
`unauthorized`	401	令牌过期或被吊销；会话服务 `authenticate` 返回 null	命令行：`tansr init` 重登。SDK：回你的服务端重新换发令牌。移动端：修好登录态后显式重连。这是唯一表示令牌坏了的码
`token_expired`	401	登录态 token 过期	重新登录 / 刷新
`invalid_api_key`	401	PAT 无效	控制台重建 PAT，`tansr init --fresh`
`rate_limited`	429	平台限流，或会话服务宿主限流 / 套餐配额（`detail.scope: 'plan'`）	按 `Retry-After` 整秒等待后重试；不要更密地重发
`plan_concurrency_exceeded`	429	套餐并发硬帽	只拒新会话；30 秒后手动再发；考虑升档
`insufficient_balance`	402	余额不足	充值；重试无益
`model_not_authorized`	403	模型不在应用授权面	控制台给应用开该模型授权
`validation_failed`	400	请求载荷形状非法	读 `message` 改请求；不是网络问题
`payload_too_large`	413	超体帽（如语音原始音频 > 24 MiB）	切分或压缩；不可重试
`session_archived`	410	平台会话已归档（30 天不活跃）	新建会话；这条不能再续

再补几个高频但含义直白的：upstream_error（502，上游模型故障，退避重试）、upstream_timeout（504，同上）、quota_exceeded（429，日配额）、forbidden（403，能力位关或归属不符）、context_window_exceeded（400，先压缩）。

各形态的排障第一步

SDK(Node / Electron)：分清是装配期还是运行期。装配期 TansrSdkError 读 code（invalid_options 改代码；assembly_failed 看 cause;capability_disabled 去控制台开位）；运行期看事件流 turn.error.recoverable——true 是咨询，false 才是失败。事件流「卡住不动」几乎都是忘了 session.close()；「工具全被拒」几乎都是没接 permission.askUser。详见错误处理与重试。

会话服务（@tansr/serve）：先看 GET /readyz（503 带 reasons）；再看结构化日志的 request.completed / store.commit_failed / session.rejected，用响应头 x-request-id 关联。resume 恒 409 resume_unavailable = 没接 store；500 store_corrupted 常见于共享存储目录（不安全配置）；建会话 503 upstream_unavailable 是平台侧铸令牌不可用，503 overloaded 是本机准入帽，503 draining 是正在优雅关闭。

移动端（Android / iOS / 鸿蒙）：先看连接态。Android / iOS 看 connectionState：Retrying 是正常的 L1 重连；Recovering 是 L2 重建；AuthExpired → Failed(Unauthorized) 是令牌刷了 2 次仍 401，修登录态后显式 start()。鸿蒙看 session.onState：retrying / recovering / failed。一连就 401 通常是认证头不被服务端 authenticate 认可。模拟器连不上：Android 用了 127.0.0.1 而非 10.0.2.2；鸿蒙回环仅本地调试，连开发机私网须 allowPrivateNetworkHttp。

拿着这些去联系支持

tansr doctor --json 的输出（不含密钥值；凭据以指纹形态呈现）。
错误码与完整 message；会话服务侧再带 x-request-id。
复现步骤与时间点；涉及计费带订单号或账单月份。
如果方便，tansr sessions export <id> 的转录（密钥已自动脱敏）。

入口见联系支持。

排障指南

第一步：tansr doctor