Tianshu-harness

天枢 (Tianshu) 是一个全功能、高性能的终端编程智能体运行时（TUI）。它跳出了传统 AI 编程助手把大模型仅当成“工具”的局限，基于认知虚拟机 (CVM)、自感知层和信息素（Stigmergy）自衰减记忆构建，让 AI 成为有独立判断与认知防护的“开发伙伴”。同时针对 DeepSeek V4 做了前缀缓存工程优化（长会话实测稳态命中率 95–99%）。

[!NOTE] 本项目最初的开发代号为 Rivet；为保持向后兼容，已安装的 CLI 命令名仍为 rivet。

🚀 快速开始

1. 环境要求

• Node.js 24.1.0（推荐；22+ 通常可用）—— 用 node --version 检查。
• Git（强烈建议）—— 可选。没有它天枢仍可运行（就地修改），但 git 能解锁：委派 worktree 隔离、检查点回滚、commit/diff 审查、每个 worker 的 diff 审查。安装：https://git-scm.com/downloads。

2. 安装（任选其一）

方式 A：桌面端（开箱即用） —— 从 GitHub Releases 下载：macOS .dmg · Windows .msi · Linux .AppImage。

Windows 支持范围：Windows 10（1809+，建议 22H2）/ Windows 11。界面渲染依赖 WebView2 Runtime——Win11 与多数 Win10 已预装；缺失时安装器会自动下载（离线环境可到 https://aka.ms/webview2installer 手动安装）。「设置 → 运行时与关于」页可查看当前 WebView2 版本。 Win10 平板模式已知行为：平板模式下切换应用会把上一个应用滑出屏幕——computer_use 的快照已做遮挡/后台自愈（PrintWindow 渲染），无需关闭平板模式。

方式 B：npm 全局安装（推荐，使用命令行） —— 已发布为 tianshu-tui，无需本地构建，且每次启动自动检查更新：

npm install -g tianshu-tui
rivet

Windows 提示：装完提示 rivet 无法识别 时——先新开一个终端（装 Node 时开着的窗口拿的是旧 PATH）；仍不行，把 npm prefix -g 输出的目录加进用户 PATH 再开新终端。官方安装器装的 Node 默认无此问题，nvm/fnm/scoop 安装的需手动加一次。

方式 C：从源码构建：

git clone https://github.com/huiliyi37/Tianshu-Tui.git
cd Tianshu-Tui
npm install
npm run build      # 生成 dist/main.js
npm start          # 或：node dist/main.js

3. 启用 Shell 补全（可选）

仓库自带 completions/ 目录，覆盖 bash / zsh / fish / Windows PowerShell 四种 shell。按你的 shell 安装对应文件：

bash —— 任选其一：

source /path/to/rivet.bash                                   # 追加到 ~/.bashrc
cp completions/rivet.bash ~/.local/share/bash-completion/completions/rivet
sudo cp completions/rivet.bash /usr/share/bash-completion/completions/rivet

zsh —— 把 rivet.zsh 以 _rivet 名字放入 $fpath：

mkdir -p ~/.zsh/completions
cp completions/rivet.zsh ~/.zsh/completions/_rivet
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc   # 需在 compinit 之前

fish：

mkdir -p ~/.config/fish/completions
cp completions/rivet.fish ~/.config/fish/completions/rivet.fish

Windows PowerShell —— 在 $PROFILE 里 dot-source：

Add-Content $PROFILE ". C:\path\to\rivet.ps1"

补全内容与 CLI 保持一致：顶层命令（config / serve / sessions / browser / logs）、全局 flags、config 全部子命令，以及从 ~/.rivet/config.json 动态读取的 provider 名。

4. 配置 API Key（首次必做）

直接安装的用户无需手动配置——首次运行 rivet 会先进入主界面，再自动打开 /connect；在那里选择服务商并完成认证。之后随时输入 /connect 添加或调整 Provider；桌面端也可在 Settings → Provider 管理配置。

开发者拉源码启动（或想在启动前预先配好）才需要手动来：

rivet config set-key deepseek sk-xxx   # 持久化到 config.json
export DEEPSEEK_API_KEY=sk-xxx         # 或：环境变量（仅当前 shell 有效）

其他提供商（Claude、GLM、Codex、MiniMax、MiMo）用法相同，详见 模型配置。

5. 启动

rivet            # 或：npm start / node dist/main.js

你会看到带有 〉 提示符的 TUI。输入需求后按回车即可。

无界面模式（脚本集成）

rivet -p "解释 src/agent/loop.ts"       # 单次提示，文本输出，无 TUI
rivet -p "列出所有 TODO 注释" --json    # JSON 输出，便于脚本处理
rivet --stream-json -p "重构这个模块"  # NDJSON 事件流：text_delta/tool_use/tool_result/turn_complete…（CI 集成首选，输出内置脱敏）
rivet --goal "修复所有类型错误" --budget 50   # 无头目标自主模式，最多跑 50 轮（默认 100）

命令行参数

子命令：rivet config（查看配置命令帮助；交互式 Provider 配置使用 TUI /connect）、rivet serve（启动 sidecar HTTP/SSE）、rivet sessions（列会话）、rivet logs（日志落点）、rivet browser status / rivet browser install [--no-mirror]（browser_debug 所需 chromium 的体检与一键安装，默认走国内镜像）。

自动更新

通过 npm 安装时，天枢每 24 小时在启动时检查新版本并弹出提示。/update 会执行 npm install -g tianshu-tui@latest 并重启；源码安装则用 git pull && npm install && npm run build。用 RIVET_NO_UPDATE_CHECK=1 可关闭检查。

⚙️ 模型配置

多提供商 + 自适应路由

会话内用 /model <name> 随时切换提供商。

rivet                                 # 启动 TUI；首次缺 key 时自动打开 /connect
rivet config                          # 查看配置命令帮助
rivet config setup codex --default    # Codex 走 OAuth（首次浏览器登录）
rivet config show                     # 查看完整配置

也可直接编辑 config.json（只写需要覆盖的字段，默认值会深度合并）。文件位置：CLI 在 ~/.rivet/config.json（Windows 为 %LOCALAPPDATA%\.rivet）；桌面端以 Settings → 存储位置为准，便携版在 exe 旁 TianshuData\.rivet——详见先定位数据根：

{
  "provider": {
    "default": "deepseek",
    "providers": {
      "deepseek": {
        "apiKey": "sk-xxx",
        "models": [
          { "id": "deepseek-v4-pro", "contextWindow": 1000000, "maxTokens": 384000 }
        ]
      }
    }
  },
  "agent": { "maxTurns": 200, "approval": "auto-safe", "crossSessionEnabled": true },
  "compact": { "enabled": true, "autoThreshold": 800000 }
}

识图（视觉能力）

图片能不能进模型看主控模型的能力：声明 supportsVision 的直接看图；不支持的，配一个识图桥（agent.visionModel）把图先换成文字描述；两者都没有则图片被丢弃——且会明说（TUI 给警告，截图工具的结果文字里写明"该附件已被丢弃，改用 observe/extract/eval 读 DOM"），不让模型凭"我截了图"断言渲染正常。

内置能直接看图的模型：glm-5.2（glm / ccswitch）、MiniMax-M3（minimax）、zai-org/GLM-5.2（siliconflow）、gpt-5.5（codex）。默认的 deepseek-v4-pro 不支持，用 DeepSeek 当主控就需要桥。

需要添加新的视觉 endpoint 时，在 TUI 输入 /vision。它会从 endpoint 的 /models 获取候选，只允许选择刚发现的模型，并对所选模型发送一次真实图片验证；验证成功后才保存专用视觉 Provider，不会替换默认 Provider 或进入普通模型路由。inline API key 只写入 secrets.json，环境变量方式只保存变量名。

如果视觉 Provider 已经配置好，再使用 /config 或桌面 Settings → 集成 → 识图模型从已有 supportsVision 模型中选择即可。

{
  "agent": {
    "visionModel": {
      "provider": "minimax",
      "model": "MiniMax-M3",
      "prompt": "请详细描述这张图片…",  // 可选
      "maxTokens": 1024,                // 可选，描述的输出上限
      "fallback": { "provider": "glm", "model": "glm-5.2" }  // 可选，主桥 5xx/超时时自动切
    },
    "visionAutoBridge": false           // 未配 visionModel 时是否自动挑一个可用视觉模型（默认关）
  }
}

• 桌面端：Settings → 集成 → 识图模型（下拉只列已配置且支持图片输入的组合，留空即关闭；同卡还有备用识图模型与自动选桥开关）。卡片顶部显示当前会话的真实桥状态；附图而图不会被看到时，Composer 直接警告并给「去配置」按钮。
• TUI：/config → 识图模型（候选同桌面端；选「（关闭）」即关掉桥接，同分类还有自动选桥开关，S 保存，下次会话生效）。
• ask_image：配了桥（或主控本身多模态）后，模型可就同一张图反复追问细节（"逐字念出红色报错那一行"），你附的图和 agent 自己截的图都能问；同一问法命中缓存零额外调用。
• 自动选桥默认关：开了它就会把图片发给一个你没为此选择过的 provider。关着时若检测到可用视觉模型，天枢会点名它并告诉你怎么启用，不闷声丢图。
• 图片来源：TUI 粘贴图片路径或 Ctrl+V 读剪贴板、桌面端 Composer 附件（每条最多 4 张）；以及 agent 自己截的 browser_debug / computer_use 截图（每轮最多带最近 2 张进上下文）。browser_debug 缺 chromium 时：终端 rivet browser install，或桌面端 Settings → 集成 → 浏览器（截图） 一键装（带安装日志）。
• CLI 与桌面各自独立：识图模型、备用桥、自动选桥、chromium 安装两端都配得全，只装一个也能自己把识图跑通。
• 图片走对话尾部追加，不打断前缀缓存；token 按分辨率估算（1280×800 ≈ 1105，不是固定值）。

完整说明与排查见 识图能力用户手册。

Worker 路由（子智能体用不同模型）

{
  "workers": {
    "profiles": {
      "capable": { "provider": "codex", "model": "gpt-5.5" },
      "cheap":   { "provider": "minimax", "model": "MiniMax-M2.7" }
    },
    "routing": { "code_edit": "capable", "repo_summarization": "cheap" }
  }
}

完整说明见 模型配置指南。

🔐 权限模式

三档统一入口，所有模式通过 /permission 管理：

Windows 注意：Windows 原生无文件系统沙箱。天枢桌面版安装包内嵌 PortableGit（完整 Git + Git Bash，开箱即用，不依赖用户自装 Git for Windows；已装系统 Git 时优先用系统版）。无沙箱环境下，安全写命令在 Auto 模式自动放行，风险写（rm/mv/git 写操作）仍需审批。

rivet config set-approval dangerously-skip-permissions  # 启动即 YOLO
rivet --dangerously-skip-permissi