콘텐츠로 이동
tansr 资料站

设置与 doctor

이 콘텐츠는 아직 번역되지 않았습니다.

命令行的行为由三处决定：配置文件（五层 settings.json）、环境变量、命令行旗标。tansr doctor 把这三处合并后的装配结果零网络地打印出来，是排障的第一步。本页按 tansr 命令行 0.10.3（2026-10-10 发布，npm @tansr/cli，内嵌 @tansr/serve 0.15.1）核对；0.10.2 / 0.10.3 没有新增命令、旗标或配置键。单文件 SEA 目前只有 Linux x64 / arm64 两档（分发点 bash.tansr.com，与 npm 同版），其它平台的安装与升级走 npm，见命令行 5 分钟跑通。

五层配置与合并规则

Section titled “五层配置与合并规则”

settings.json 是 JSONC（允许注释），从五层读取，高层覆盖低层：

层 位置 说明
managed（最高） Windows %PROGRAMDATA%\tansr\managed-settings.json;POSIX /etc/tansr/managed-settings.json 企业托管层
projectLocal <项目根>/.tansr/settings.local.json 项目本地层（个人覆写，建议 gitignore）
projectShared <项目根>/.tansr/settings.json 项目共享层（随仓库分发）
user ~/.tansr/settings.json（可经 TANSR_CONFIG_DIR 重定向） 用户层
builtin（最低） 内置默认 兜底

项目根 = 从当前目录向上找最近的含 .tansr 目录的祖先。注意 ~/.tansr 本身也是一个「含 .tansr 的祖先」：当前目录落在家目录树内且沿途无项目 .tansr 时，家目录会被拾为项目根，用户配置随之兼任项目共享层。要隔离就设 TANSR_CONFIG_DIR（重定向即隔离），或在项目里放一个空 .tansr 目录显式锚定。

合并与容错：常规键深合并，高层胜；permissions / hooks / mcpServers 三段不走深合并，由内核逐层抽取并保留层归因。单键取值非法 → 剔除该键并回退更低层的值；未知键 → 告警忽略；整文件语法错误 → 该层整体跳过。一切损坏都不阻止启动，/config 可看诊断计数。$schemaVersion 当前为 1。

项目层只能收权，不能扩权：defaultMode: auto / acceptEdits / bypassPermissions 三种扩权模式在项目层声明被忽略并告警；项目层 allow 规则冻结不进引擎（经 /grants 确认后才升为仓库授权）；deny / ask 照常即时生效。克隆一个仓库不能给自己授权。自 tansr 命令行 0.7.0 起（2026-09-14 发布）：项目层 hooks 段跟随工作区信任——~/.tansr/trust.json 无记录或记为不信任时项目层 command / http hooks 零执行，无人值守入口可用 --trust-project-hooks / TANSR_TRUST_PROJECT_HOOKS=1 仅在无记录时本次放行，判据与边界见安全与隐私。自 tansr 命令行 0.6.0 起（0.5.0 候选能力并入该版发布）更严的层律：sandbox / update / http 三段只认 user 与 managed 层，managed 层是地板、环境变量对它只能收紧，组织在控制台锁定的键压过一切本地层与环境变量。

常用配置键

Section titled “常用配置键”
键 含义
providers / modelAliases / fallbacks 完全本地模式的模型供给（平台模式下缺省被剪枝）；API key 只写环境变量名 auth.env
model.selected /model 的持久化落点：项目内写 .tansr/settings.local.json，项目外写用户层
locale 界面语言 zh-CN / en / ja / ko
ui.theme dark / light / high-contrast / colorblind;/theme <name> 持久化到用户层
permissions.defaultMode 六值 default / acceptEdits / plan / bypassPermissions / auto / dontAsk
permissions.allow / ask / deny 规则 DSL：Read、Shell(git *)、Read(./.env) 等
budget.maxUsd / maxTotalTokens / onExceeded 会话预算熔断（block 缺省 / warn）
effort / outputStyle 思考努力档位、输出风格；优先级旗标 > 环境变量 > 本键
context.activeScheme 上下文治理方案（/context scheme use 写入）
memory.autoMemory 自动记忆开合（`/memory on
sandbox.mode / allowWrite / network Shell 沙箱（仅 user / managed 层被尊重）
update.manifestUrl 企业自托管更新清单地址（{channel} 占位）
mcpServers MCP 服务器声明；env / headers 值支持 ${VAR} 整值引用，凭据不落文件
http.allowedAuthEnvVars Http 工具与 hooks 可引用的凭据环境变量白名单（user / managed 层）

环境变量：用户面速查

Section titled “环境变量：用户面速查”

「空串视同未设置」适用于全部路径 / 开关类变量。

变量 用途
TANSR_USER_HOME 配置总根（虚拟用户家目录）：配置目录与存储根统一派生 <dir>/.tansr；沙箱 / CI 一键隔离
TANSR_CONFIG_DIR / TANSR_STORAGE_ROOT 用户层配置根 / 会话存储根，缺省 ~/.tansr；显式设置时恒胜总根派生值
TANSR_PAT tansr init 免交互 PAT 供给（CI / 脚本）
TANSR_ESCAPE_LOCAL 严格 =1 进完全本地模式：平台凭据 / 远端模型 / 用量上报整体停用
TANSR_LANG 界面语言（低于 --lang 与配置 locale）
TANSR_TUI_GLYPHS / TANSR_TUI_PASTE_GUARD 终端字形档（unicode / ascii）与多行粘贴守卫覆盖
TANSR_EFFORT / TANSR_OUTPUT_STYLE 思考档位 / 输出风格
TANSR_SANDBOX =1 开沙箱、=required 硬要求
TANSR_ISOLATED =1 声明运行环境已隔离，只压制 doctor 的无人值守提示，不改运行时行为
TANSR_TRUST_PROJECT_HOOKS =1 在工作区无信任记录时本次启用项目层 hooks（等价旗标 --trust-project-hooks；不写 trust.json、压不过已记录的不信任；其余取值不生效）。命令行 0.7.0 起
TANSR_UPDATE_CHANNEL / TANSR_UPDATE_PINNED_VERSION / TANSR_NO_UPDATE_CHECK / TANSR_UPDATE_MANIFEST_URL 更新通道 / 组织锁定版本 / 个人退出检查 / 自托管清单
TANSR_WEBSEARCH_ENDPOINT / TANSR_WEBSEARCH_API_KEY WebSearch 自带端点（显式设置恒压过登录态平台搜索）
TANSR_IMAGEGEN_* / TANSR_ASR_* / TANSR_TTS_* 媒体工具自带端点三件（_ENDPOINT / _API_KEY / _MODEL,+ TANSR_TTS_VOICE）
TANSR_COMPILE_CACHE 启动编译缓存目录（命令行 0.10.1 起，npm 形态）：缺省落用户缓存目录 …/tansr/compile-cache（设 TANSR_USER_HOME 时落 <TANSR_USER_HOME>/.cache/tansr/compile-cache）；=<dir> 改目录、=0 关闭。每个新安装版本首次启动多写约 2 MB、数十个文件，之后同版本启动更快；旧版本缓存不自动删，可整目录清；任何失败静默跳过
TANSR_SERVE_TOKEN tansr serve 的 Bearer（--token 缺省时回退）
TANSR_SERVE_LOG_LEVEL tansr serve 日志级别，缺省 warn（命令行 0.10.0 / @tansr/serve 0.13.0 起）；此前靠 info 事件做仪表板的部署升级后要显式 =info
TANSR_SERVE_LEGACY_V1 =1 在 tansr serve --v2 部署里重开 /v1 面（等价旗标 --legacy-v1）。已废弃：0.14.0 / 命令行 0.10.1 起开启即出一条 warn 事件 server.deprecated_option，1.0.0 移除；审批凭证投递改 POST /api/approvals/:id/credential 后不再需要
TANSR_SERVE_SSE_MAX_FRAME_BYTES / TANSR_SERVE_AUTH_MAX_PENDING / TANSR_SERVE_AUTH_TIMEOUT_MS SDK2 装配在场时的单帧字节硬帽（缺省 2 MiB）与基础认证源限界（缺省 128 个未结束 / 10 s）；只装 SDK1 的部署缺席零变化（命令行 0.10.0 起）
TANSR_SERVE_LEGACY_PREFIX / TANSR_SERVE_LEGACY_SUNSET 旧 /v2、/v3/* 前缀的退役窗口（命令行 0.10.2 起，内嵌 @tansr/serve 0.15.0）：前者取 readwrite（缺省，0.10.3 未变）/ readonly（旧前缀写操作改答 410 gone）/ off（旧前缀全部 404）；后者为 HTTP-date 或 ISO-8601，设了才在旧前缀响应附 Sunset 头。只在 --v2 部署有消费点，非 --v2 启动时按既有律出现在「legacy 组未生效」提示里；没有对应旗标

tansr serve 的运维旋钮（准入帽、SSE 背压、日志形态等 TANSR_SERVE_*）与 @tansr/serve 同名同义，命令行 0.10.0 起 36 键、0.10.2 起 38 键，全表见环境变量表；例如 TANSR_SERVE_LOG_FORMAT、TANSR_SERVE_MAX_ACTIVE_SESSIONS。

tansr serve 的旗标（0.10.x）

Section titled “tansr serve 的旗标（0.10.x）”
旗标 含义
--token / --port / --host Bearer（缺省回退 TANSR_SERVE_TOKEN）、端口（缺省 7433）、监听地址（缺省回环，外部接入须显式 0.0.0.0）
--v2 挂 /v2 多租户面（同一 Bearer + x-tansr-end-user 头分域，0.6.0 起）；0.10.0 起同时在链首装配统一调用面 /api，且 /v1 面缺省关闭（0.13.0 的 serve 契约变更）
--legacy-v1 在 --v2 部署里重开 /v1；已废弃（0.10.1 起出 server.deprecated_option warn，1.0.0 移除），新集成改 /api
--host-module <absolute.cjs> --host-module-sha256 <sha256> 成对旗标（缺一即用法错误），显式装配本机绝对路径的 .cjs 受信宿主模块（≤ 16 MiB，核摘要后编译已验字节执行），@tansr/serve/extensions 的 SDK2 归档 / 缓存 / 终端服务在命令行形态只经此径可达；不传 = 0.9.0 行为（0.10.0 起）
--trust-project-hooks 工作区无信任记录时本次启用项目层 hooks（0.7.0 起）

0.10.2 / 0.10.3 未新增旗标：旧前缀退役窗口只经上表的两个环境变量控制。tansr bg kill --force 在装有大量 PowerShell 模块的 Windows 机上因身份探针超时被判「不可核」而拒杀的问题已随 0.10.1 修正（wire / 旗标 / 退出码零变化）。完整命令面见命令参考，部署形态见部署与鉴权。

tansr doctor 怎么读

Section titled “tansr doctor 怎么读”
终端窗口
tansr doctor          # 人读报告;退出码 0 可用、1 有阻断问题
tansr doctor --json   # 机器可读

它零模型调用、零网络、零子进程，全部取装配期缓存事实，适合 CI 预检。命令面参考见命令参考。TUI 内的 /doctor 是另一份页内自检：十二项 ✓ / ✗ 清单（node_version ≥ 22.19、config_sources 无 skipped 层、config_diagnostics 无 error 级、model_resolution、context_window、context_scheme 为 production 方案、custom_commands、mcp_connections、terminal 为 TTY、workspace_trust 非未信任、output_style 无坏文件、session_driver_state），只呈现、不产生退出码；两者取同一批装配期事实，但项目与结论口径不同，CI 以 tansr doctor 的退出码为准。

什么算阻断：退出码只看 --json 顶层 problems 数组（ok: true 即为空），四个问题码：

问题码 触发
no_provider 没有可用的 provider 注册表（未登录平台，且本地 provider 未配置）
unresolved_model 诊断别名 main 解析失败（未知别名 / 未知 provider 等，provider.error 携结构化码）
missing_credential 已解析的 provider 声明了 auth.env，而该环境变量为空（本地 provider 场景；credentials.envVar 只给名、永不给值）
session_store_unwritable 会话存储根不可写

加 --connectors 时连接器自检的阻断问题并入同一数组。配置层被整体跳过、error 级配置诊断、未信任工作区、MCP 连接失败、Node 版本等都只呈现、不阻断——它们出现在报告对应段里，但不改退出码。

报告段序：版本行 → 配置五层（层 / 状态 / 路径、error 级诊断计数、被层律忽略的段、设了 TANSR_USER_HOME 时的配置总根）→ provider 解析（main → provider / 模型、来源，图片输入三态）→ 模型选择归因 → 凭据 → 剪枝 / 逃生态 → 凭据存储 → 登录档、套餐、WebSearch 来源 → 会话存储 → 更新源 → 工作区信任 → 遥测、审计、输出风格、沙箱、语义索引、媒体 → 裁决链、权限指标 → 无人值守基线 → 上下文、记忆 →（--connectors）连接器 → 结论行（问题计数）。

归因段（不计阻断，排障最常看）：

  • localProviders：逃生态 / 平台混用开关 / 本地 providers 剪枝来源三元组。「未配置 provider」先看这里，分清是没配还是被剪。
  • 凭据存储：凭据落在密钥库还是降级明文文件；派生键有效期。
  • 模型选择归因：model.selected 值与提供层、项目是否钉定 main、压制态是否命中。
  • 套餐：登录态下一行「套餐：档名（并发上限 N）· 到期 · 状态」；个人档显「个人（仅 CLI，无套餐费）」——不是故障。--json 在顶层 plan 键，null = 个人档。
  • 媒体工具：四面来源三态 byo / platform / none；「模型说没有图像工具」先看这行，登录了却是 none 通常是管理员尚未为账套开媒体池。
  • 无人值守基线：defaultMode 为 auto 且探测不到隔离迹象时给显著提示（--json 落 unattended 字段）；提示不阻断。
  • 会话存储 / memory：会话数、总字节、工件目录数、损坏目录数；记忆索引行数与孤儿目录。只读，不代删——清理走 tansr sessions prune。
  • 裁决链：启用 / 降级 / 资格档快照。

doctor 呈现的是最近一次装配拉取的事实：控制台改了套餐或能力位，跑一次 CLI 即刷新。部署连接器（OIDC / 渠道桥 / SIEM）的网络探测要显式 tansr doctor --connectors。

其他排障工具

Section titled “其他排障工具”
  • /config：合并后配置概要与诊断计数；/status：版本 / 通道 / 语言 / 会话 / 模型。
  • tansr -p "…" --json：完整事件流是最细的排障数据，权限判定、hook 结果、供应商切换全在流内。
  • Shell 工具长输出全量落盘到 <工作目录>/.tansr/shell-output/<toolCallId>.log。
  • tansr sessions export <id>：导出转录（密钥自动脱敏），可直接进工单。
  • 常见错误码与 doctor 段位的对照表见排障指南。