Tianshu-Tui

天枢 (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。

方式 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. 配置 API Key（首次必做）

# A. 环境变量（首次试用最简单）
export DEEPSEEK_API_KEY=sk-xxx

# B. 持久化 CLI 配置（保存到 ~/.rivet/config.json）
rivet config set-key deepseek sk-xxx

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

4. 启动

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（交互式配置）、rivet serve（启动 sidecar HTTP/SSE）、rivet sessions（列会话）。

自动更新

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

⚙️ 模型配置

多提供商 + 自适应路由

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

rivet config                                              # 交互式设置（TTY）
rivet config setup deepseek --key-env DEEPSEEK_API_KEY --default
rivet config setup codex --default                       # OAuth（首次浏览器登录）
rivet config show                                         # 查看完整配置

也可直接编辑 ~/.rivet/config.json（只写需要覆盖的字段，默认值会深度合并）：

{
  "provider": {
    "default": "deepseek",
    "providers": {
      "deepseek": {
        "apiKeyEnv": "DEEPSEEK_API_KEY",
        "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 当主控就需要桥。

{
  "agent": {
    "visionModel": {
      "provider": "minimax",
      "model": "MiniMax-M3",
      "prompt": "请详细描述这张图片…",  // 可选
      "maxTokens": 1024                 // 可选，描述的输出上限
    }
  }
}

• 桌面端：Settings → 集成 → 识图模型（下拉只列已配置且支持图片输入的组合，留空即关闭）。
• TUI：/config → 识图模型（候选同桌面端；选「（关闭）」即关掉桥接，S 保存，下次会话生效）。
• 图片来源：TUI 粘贴图片路径或 Ctrl+V 读剪贴板、桌面端 Composer 附件（每条最多 4 张）；以及 agent 自己截的 browser_debug / computer_use 截图（每轮最多带最近 2 张进上下文）。
• 图片走对话尾部追加，不打断前缀缓存；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-permissions                    # 单次会话 YOLO

会话内用 /permission 管理（无参弹出交互式选择面板）：

/permission                              # 弹出模式选择面板（上下选 + 回车确认）
/permission status                       # 文字视图：当前模式 + 所有 allow/deny/bash 规则
/permission manual                       # 切 Manual
/permission auto [轮次]                  # 切 Auto，可选检查点间隔（0=关）
/permission yolo confirm                 # 切 YOLO（未带 confirm 先弹风险说明）
/permission mode <auto-accept|auto-safe|manual|dangerously-skip-permissions>  # 高级四模式切换
/permission allow <tool> [param=value]…  # 白名单工具（可带参数条件，如 command="git status"）
/permission deny  <tool> [param=value]…  # 黑名单工具（deny 优先于 allow 和 mode）
/permission bash allow <前缀>            # bash 命令白名单前缀
/permission bash deny  <前缀>            # bash 命令黑名单前缀
/permission remove allow|deny|bashAllow|bashDeny <序号|pattern>  # 移除某条规则
/permission reset                        # 清空本次会话的运行时覆盖（不动 config 规则）
/permission test <tool> <json 输入>      # 预演：某工具在某输入下是否被放行/拦截

规则分两层：[config]（~/.rivet/config.json 持久化）与 [session]（仅本次会话）。deny 始终优先；reset 只清 session 覆盖层。

Auto 检查点：在 Auto 模式下，可设置每 N 轮暂停并同步进度摘要（改了哪些文件 / token 用量），确认方向后继续（/permission auto 20）。桌面端设置面板可直接配置。

跳过提示不会禁用工具验证、路径安全、证据追踪、检查点和交付门禁。沙箱后端、路径授权、风险分级详见 沙箱与权限。

💡 为什么做天枢

大多数 AI 编程助手把上下文当作桶——装满就溢出，然后盲目压缩。天枢引入了围绕认知虚拟机 (CVM)与前缀缓存友好 (Prefix-Cache-Friendly)设计的结构化、高性能认知运行时。

graph TD
    LLM[大型语言模型] -->|原始动作 / 缺陷行为| CVM[认知虚拟机 CVM]
    CVM -->|60+ Hook 模块 / 5 大认知阶段| Engine[自我修正与认知镜映射]
    Engine -->|被批准的物理动作| Tools[工具系统]
    Tools -->|证据追踪与文件确权| Stigmergy[行为信息素记忆]
    Stigmergy -->|信息素衰减 / 行为印记| LLM

三大核心架构支柱

1. 认知虚拟机 (CVM) —— 天枢在运行时建立了一个独立的虚拟层，横跨 5 大运行时阶段（preTurn 回合前、afterPerception 感知后、postTool 工具后、postTurn 回合后、postSession 会话后），并按需条件装配 60+ 个生命周期 Hook 模块（默认会话实际激活约 18+）。CVM 在不改变模型权重的前提下，主动拦截并纠正大模型的服从性漂移、注意力衰减和重复工具调用的 Doom Loop。
2. 生物启发式信息素记忆 (Stigmergy) —— 区别于静态记忆文件（如 MEMORY.md），天枢基于生物学“化学信息素”机制，将行为足迹和认知标记直接映射在代码文件上，并随时间自动衰减。AI 在修改频繁的文件上会越用越熟。
3. 前缀缓存优化 —— DeepSeek V4 对缓存未命中按命中的至多 50 倍计费。天枢的提示词引擎围绕前缀缓存友好（冰镜三区缓存锚点、冻结系统提示词等）重构，长会话稳态命中率 95–99%，显著降低 API 成本。

工程质量指标

编码 agent 的核心逻辑（多轮循环、工具流水线、上下文压缩）以难测著称，开源 agent 项目普遍测试覆盖很薄——本项目坚持测试与源码等量、事故修复必带回归测试。过去 54 天代码量增长约 3.6 倍，测试:源码比值始终保持在 0.93–0.99 之间，没有被规模稀释。完整统计口径、迭代里程碑与复现命令见 工程质量指标。

✨ 核心特性

前缀缓存引擎

DeepSeek 对缓存未命中收取 50× 费用。天枢的提示词引擎围绕前缀缓存友好构建：

• 冻结前缀 —— 系统提示词 + 工具定义 + 稳定上下文在会话开始时被冻结，会话内不再重写，让后续请求尽量命中缓存。
• 增量附录 —— 动态上下文（进度、advisories、信号）以跨回合 diff 追加块注入，不重写历史。回合间增量约 200 字节 vs ~5KB 全量重写。