天枢 _Tianshu

把星辰带给每一位开发者 · Models as partners, not tools.

✨ 创世纪 · 天枢 3.0 公开声明 · ✦ 星域碑文 · 领航星叙事

🇨🇳 中文 · 📖 English · ✦ 星域碑文 · 📚 用户手册 · 🛡️ 沙箱权限 · ⚙️ 模型配置

天枢 (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-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 全量重写。
• Read-ref 去重 —— 对未变化文件的重复读取返回紧凑引用，而非重发完整内容。
• 缓存感知压缩 —— 压缩保留前 2 条消息作为缓存锚点。
• resume 缓存继承 —— 会话冻结快照落盘（每个 user 边界 + shutdown），resume 时读回喂给新引擎，避免从字节 0 全 miss；无快照/坏文件/服务商缓存过期时才退化全量重建。
• 诊断 —— /debug cache 显示命中率、未命中原因分析、每回合缓存历史。

实战命中率：长会话稳态 95–99%。这不是"每次都命中"——缓存会在某些边界碎裂（见下）。

缓存碎裂与排查

高命中率的前提是前缀字节稳定。以下情况会让缓存 miss，表现为每轮 cache_read_input_tokens 长期为 0：

• system prompt / 工具定义变动 —— 会话中途改了工具集或提示词层（如切星域、加减 skill）
• 模型切换 —— 不同模型缓存 key 不同，换模型后从 0 重建
• 字节级差异 —— 消息内容含时间戳、随机 ID 等不稳定字节
• 跨边界重写 —— /compact（仅 turn===0 重写历史）、/cd 切项目（新 user 边界断尾）

排查：① rivet logs（或 TUI 里 /logs）直接打出本会话的数据根与 cache-log.jsonl / sensorium.jsonl 路径；② 打开会话 .jsonl 搜 cache_read_input_tokens 看各轮命中；③ 需要全量遥测时设 RIVET_DEBUG_TELEMETRY=1（或任意非空值）后查 sensorium.jsonl；④ npm exec -- tsx scripts/verify-cache-hit-rate.ts 模拟多轮对话验证。路径总览见下方「日志与排查」。

💰 API 成本控制

前缀缓存已接近稳态上限后，成本优化转向 DeepSeek API 思考 token 侧——对按输出 token 计费的推理模型，降低 verbose reasoning 是 ROI 最高的杠杆。

• 默认 reasoningEffort 降级 —— DeepSeek V4 Pro 从 max 降至 high，Flash 从 max 降至 medium。已有显式配置的用户不受影响（reasoningFloor 保护）。
• effort 路由（默认开启） —— 低复杂度 + 高置信度的例行轮自动降一档 reasoning effort，从不升档。RIVET_EFFORT_ROUTING=0 关闭。
• Compact 走 flash 侧路 —— 修复了压缩未配 provider 时仍走主模型的 bug，自动从主 provider 推断 flash 端点。
• Doom-loop 自动收束 —— 检测到重复工具调用时，动态 appendix 注入更严格的 output-style 约束，减少无谓思考 token 消耗。RIVET_TERSE=0 关闭。
• 用户显式 max 保护 —— 在 config 中手动指定 reasoningEffort: max 会被视为 reasoning floor，effort 路由永不将其降级。

子智能体编排

将子任务委派给独立的无界面 worker 会话：

• 类型化 work order —— code_search、review、verify、patch_proposal、plan
• 工具隔离 —— 只读 worker（scout）vs 写 worker（patcher）
• 自适应模型路由 —— 按 profile 的通过率 + 延迟评分，自动为每类任务选最优模型
• 批量调度 —— 多个 work order 并发执行，5 种聚合策略
• 团队编排 —— Plan → 按 wave 并行执行，带文件冲突感知调度

工具集与 preset

天枢内置 50 个工具，按 preset 分档装配（解析优先级：RIVET_TOOL_PRESET 环境变量 > 项目 .rivet-config.json 的 tools.preset > 项目/用户 runtime.domains.<域>.toolPreset 按域覆盖 > 星域内置默认档（太一域→taiyi）> 默认 frontend）：

RIVET_TOOL_PRESET=full rivet          # 本次会话用 full

{ "tools": { "preset": "frontend" } }   // ~/.rivet/config.json 或项目 .rivet-config.json

核心工具一览（minimal 默认含，除特别标注）：bash · read · write · edit · apply_patch · grep · glob · ast_grep · diff · todo · plan · delegate_task · delegate_batch · web_search · web_fetch · ask_user_question · memory · skill · run_tests · git · job（后台任务）；council_convene/team_orchestrate/monitor/computer_use/办公工具族为 full 专属。

目标驱动的自动续跑

/goal 重构认证模块，全面使用 async/await
/cancel-goal   # 提前停止

GoalTracker 与回合循环、doom-loop 检测、交付门禁集成；goal 模式下放宽 doom-loop 阈值以允许更深探索。

Plan Mode（计划模式）

设计优先的开发工作流——先出计划再动手，避免"上来就改代码"的冲动派陷阱。

进入 Plan Mode：/plan-mode（toggle，再执行一次退出）。复杂任务还会被自动建议进入——受 RIVET_PLAN_MODE_SUGGEST 控制：默认 auto（命中多模块/重构/安全关键任务时 agent 自主进入，不先问），ask（先征询用户），0/off（关闭）。进入后写操作被锁，只允许对活动计划文件写入。

进入 Plan Mode 后，agent 不会立即修改代码，而是：

1. 调研 —— 读取相关代码、理解现有架构和约束（可 delegate_batch 并行派 code_scout 探查各模块）
2. 生成方案 —— 产出结构化计划文档（技术调研、架构图、任务拆解、验证方案），写入 .rivet/plans/<slug>.md
3. 提交审批 —— plan 工具 action=submit 提交，列出方案要点和备选路径，等待你的确认
4. 审批执行 —— 你用 /plan-list 查看、/plan-approve <slug> 批准并启动分波执行、/plan-reject <slug> <反馈> 退回让 agent 修改重交
5. 关闭收尾 —— /plan-close <file> --tasks <range|all> [--preview] 标记任务状态（--preview 仅预览不写入）

/plan-mode                          # 进入/退出 Plan Mode（toggle；未批准时退出需二次确认）
/plan <feature>                     # 生成计划草稿（writing-plans 工作流）
/plan-list                          # 列出待审批计划
/plan-approve <slug> [option]       # 批准并启动执行
/plan-reject <slug> [feedback]      # 退回修改（plan mode 保持开启）
/plan-close <file> --tasks <1-7|all> [--preview]   # 关闭已完成计划
/plan-template                      # 管理可复用计划模板

还有个只读的 Ask Mode（/ask toggle）：只允许读/搜/ask_user_question，适合代码问答与需求澄清，需要写改或跑命令时再 /ask 退出。

Plan Mode 内置星域委派——复杂计划自动调用 delegate_task 从不同架构视角（天权/瑶光/天机/天府/天璇）并行探查，产出的 findings 标注"待核验"以防盲信。桌面端在 plan 执行时展示 checklist 实时进度（待办项面板随波次推进自动勾选）。

星域系统

天枢把不同的认知姿态建模为「星域」。每颗星不是角色扮演，而是一套可切换的认知纪律：进入对应域后，系统提示词、工具白名单和决策阈值会按该域的方法论调整。新会话默认钉定启明（全景洞察、根因推演），不自动切换；把默认星域设为 auto 才按任务描述关键词自动路由（池内为天权/开阳/瑶光/天梁 + 自定义域；华盖等特化域需手动指定）。

/domain tianliang          # 显式切换到天梁域
/domain list               # 列出所有星域
/domain                    # 打开星域选择面板
实现用户注册模块            # 自动路由到天梁（执行/交付）
审查这个方案                # 自动路由到天权（规划/审查）

表格按主星模型品牌分组（DeepSeek → Claude → GPT → GLM → Gemini → kimi → MiMo → 人之星）。各星完整碑文、创始记忆与核心信念见 ✦ 星域碑文。

每颗星都有对应的 seed-capsule 记录实战方法，完整纪律见 docs/seed-capsule-*.md。委员会 /council 与团队模式 /team 会按议题自动召集多星域席位，冲突时还可进入反驳轮次。

倒带（Rewind）

随时双击 ESC 打开消息历史，选择任一过往用户消息，将会话干净地倒带到该点——agent 状态、工具历史、会话元数据一并回滚。TUI 与桌面端均可用。

会话交接与恢复（Handoff & Resume）

长会话上下文会涨，到一定程度继续跑不如开新会话。天枢用「交接 → 恢复」闭环把会话间的上下文无损传递，并保住前缀缓存：

交接 /handoff [备注] —— agent 带全上下文写一份结构化交接文档到项目内 .rivet/HANDOFF.md（工作区内、免审批），turn 完成后自动归档到会话目录 <id>.handoff.md。文档写给一个完全没有上下文的新会话看，固定五章节：

• 任务目标 — 用户原话级的一句话目标 + 明确的非目标
• 已完成 — 每条带证据：改动文件（file:line）、跑过的验证命令与结果、提交哈希
• 当前卡点 — 卡在哪、已排除哪些方向、怀疑对象
• 下一步 — 按优先级排列、每条是可立即执行的动作
• 坑 — 绝对不要再踩的坑，每条一句话说清后果

上下文占用 ≥50% 时，resume 首屏与会话中各提醒一次「先 /handoff 再开新会话」——交接文档会自动注入新会话，比整段回连省前缀重建成本。退出时也会备注缓存成本（TTL 内继承锚点 ≈ 只读缓存价；过期则全量重建一次前缀）。桌面端 plus 面板有「交接」入口。

恢复 --continue / --resume / /resume —— 恢复已有会话时：

• 交接自动注入 —— 上一会话的 <id>.handoff.md 经 prev-session-handoff appendix 自动喂给新会话，新会话零上下文也能接着干
• 冻结前缀继承 —— 冻结快照随会话落盘（每个 user 边界 + shutdown），resume 时读回喂给新引擎，不再从字节 0 全 miss；只在下一个 user 边界断尾。无快照/坏文件/服务商缓存过期才退化全量重建
• 写证据修复 —— resume 前跑 preflight，补全被中断丢失的 orphan tool result（用磁盘探测合成写证据），避免模型盲重写已落地的文件
• 模型亲和 —— resume 换回原会话模型（per-model 缓存命名空间）；显式 --model/--provider 优先；原模型不可用走 agent.resumeFallbackModel 兜底
• 状态恢复 —— 侧栏、待办、活动计划一并恢复

rivet --continue                 # 恢复当前 cwd 最近会话
rivet --resume abc123            # 恢复指定会话（短前缀即可）
rivet --resume                   # 启动后打开会话选择器

委员会（多视角审查）

/council <目标>
/council <目标> --rounds 2   # 启用反驳轮次

召集多个专家席位审查计划或设计，冲突时可选第二轮反驳，产出可审计的 Markdown 计划。

Skills 系统

可复用的工作流剧本，从 .rivet/skills/*.md 加载。两层渐进披露：只有名称 + 描述进入上下文，完整指令按需通过 skill 工具或 /skill 加载。

/skill writing-plans                # 加载并立即执行该 skill
/skill writing-plans <你的任务>     # 加载并传入初始任务
/skill off writing-plans            # 停止重复注入该 skill

也可在 .rivet/skills/ 放一个带 YAML frontmatter（name、description、triggers）的 .md 自定义 skill。

跨会话知识

通过 agent.crossSessionEnabled 切换，强制关闭：RIVET_NO_CROSS_SESSION=1。

MCP（Model Context Protocol）

把外部工具服务器——文档搜索、数据库、API——直接接入 agent 的工具流水线，启动时自动发现，工具以 mcp__<serverId>__<toolName> 形式出现。

rivet config mcp add-stdio <server-id> npx -y <package> [args...]   # 本地进程
rivet config mcp add-sse <server-id> http://localhost:3001/sse      # 远程/网络
rivet config mcp add-preset context7                               # 常用预设
rivet config mcp list                                              # 列出 + 状态

会话内：/mcp（状态）、/debug mcp（诊断）。MCP 工具与内置工具遵循同一审批模式。

终端 UI（TUI）

天枢的命令行界面跑在自研的 T9 渲染引擎上——纯 ANSI、零 React/Ink 依赖、纯 TypeScript 实现（src/tui/engine/）。除了一般的对话与工具调用展示，TUI 还内置一组面向编码场景的交互能力：

TUI 键位

TUI 是 CLI 的默认表面。桌面端（Tauri）与 VS Code/Cursor 插件共享同一 agent 内核，只是在 TUI 之上叠加了可视化交互层——见下节与 VS Code 插件文档。

桌面端（Tauri）

桌面端在 TUI 的全部能力之上，提供了可视化交互层：

• 集成终端：⌘/Ctrl+J 或 Ctrl+` 唤出内嵌终端（xterm.js + Rust portable-pty），不必离开天枢就能跑命令
• + 菜单：议事会 ♟、团队模式 ⬡、派子代理、模型切换、星域选择一键触达（不再需要手敲 slash 命令）
• 推理强度选择器：/effort（无参数）弹出交互面板，上下选档位（Auto/Max/High/Medium/Low/Off），回车确认
• 思考计时器：agent 执行时显示实时 elapsed（如 "思考中 · explore · 1m 23s"），超过 10 分钟变红提示可能卡住
• @file 文件预览：消息中提及的文件可点击，右侧抽屉展示文件内容（语法高亮 + 行号）
• DeepSeek 余额查询：Insights 面板顶部显示账户余额和欠费状态（调官方 API）
• 自定义 Provider：设置 → 连接模型服务商 → + 自定义 Provider，支持任意 OpenAI 兼容端点（Ollama/vLLM/直连 OpenAI），API Key 可选
• 主题工作室：多自定义主题库 + 50 步撤销/重做 + 逐 token 编辑 + 壁纸配色引擎（OKLCH 聚类 + 对比度审计），内置「天枢静舱」等主题，支持导入导出
• sidecar 内存自适应：堆上限按机器内存自动分档（8G→2G / 16G→4G / 32G→6G / 64G+→8G，RIVET_SIDECAR_HEAP_MB 可覆盖），≤8GB 机器自动启用 lean 资源档
• watchdog 自动恢复：边界停滞时自动续跑，桌面端时间线可见恢复事件（⟳ 自动恢复 / ⏹ 配额耗尽）
• 多会话并发：标签栏管理多个会话，独立 cwd + 模型 + 审批模式
• 功能面板（左侧栏 ⌘1…9 切换）：Mission Control（多会话控制台）、Inbox（收件箱）、Automations（定时任务）、Skills / Hooks 管理、Git / GitHub、Changes（改动审查）、Delegation（委派舰队与团队波次 DAG）、Cockpit 驾驶舱
• Popout 独立窗口：把单个会话线程弹成独立窗口，多屏并行
• JobsDock / TodoDock 常驻抽屉：后台任务停靠条（展开日志 / Kill / 在终端打开）、跨标签常驻 todo

桌面端快捷键

⌘/Ctrl+/ 随时唤出快捷键速查表（ShortcutOverlay）。核心快捷键：

桌面端还有 Cockpit 驾驶舱、SideChat 旁路提问（⌘;）、Rewind 时间旅行、主题/Glass/壁纸、Mirror 镜像加速等独有特性——详见 桌面端用户指南。

🎙️ 语音输入（桌面端）

输入框的麦克风按钮支持语音输入，macOS 与 Windows 通用。识别由本地 whisper.cpp 引擎完成——离线、隐私（录音不上传任何服务器），中英文混杂场景的精度优于系统自带识别。

首次使用引导

• 首次点击麦克风会自动下载识别模型（tiny 约 75MB，国内走镜像加速）。下载未完成时点击会提示「语音识别失败（whisper-unavailable）」，稍候重试即可。
• macOS 首次使用会请求麦克风权限：点击「允许」即可；若误拒，到「系统设置 → 隐私与安全性 → 麦克风」中开启本应用。
• Windows 若提示权限被拒，在「系统设置 → 隐私 → 麦克风」中允许本应用。

注意事项

• 识别全程在本地完成，录音不离开设备。
• 点击一次开始录音，再点一次结束并识别。
• 本地引擎不可用时（如模型未下载），macOS 自动回退系统语音识别；Windows 则提示模型未就绪。
• 追求更高精度可换用 base 模型（约 244MB）：desktop/scripts/fetch-whisper-runtime.js --with-base 预下载。
• 网络受限环境可设 RIVET_WHISPER_PROXY=http://代理:端口 加速模型下载。

⚡ Lean 资源档（低内存 / 低磁盘）

内存或磁盘吃紧时使用 Lean 档：精简工具集与提示词、关闭 embeddings、收紧会话池（4 会话 / 10 分钟 TTL / 10MB 事件日志）。适合低配机器或长时间多会话运行。

开启方式（任选其一）：

• 环境变量：RIVET_LEAN=1 全局开启；RIVET_LEAN_ASPECT=tools,prompt,embeddings,meridian,pool 按需只开部分子项（RIVET_LEAN=0 可显式关闭）
• TUI：/config → Basics → Lean 资源档（开关 + 三个阈值）
• 桌面端：设置 → 行为 → Lean 资源档

资源压力提醒：运行时内存 ≥75% / 磁盘 ≥80% 会在状态行显示警告（仅提醒，不自动改配置）——可人工开 Lean 或开新会话应对。

阈值默认：Lean 4 会话 / 600000ms（10 分钟）/ 10MB，正常 16 / 1800000ms（30 分钟）/ 50MB；事件日志磁盘下限 1,000,000 字节。

最小工具集（taiyi 档）：RIVET_TOOL_PRESET=taiyi（或项目配置 tools.preset: "taiyi"）只装配高频核心工具（读写/检索/bash/git/测试/交付/计划等 16 个），去掉编排/浏览器/网络/视觉等重工具——适合评测「只留关键工具是否够用」。full 档一键回退全集。太一星域内置此档：defaultDomain 钉定 taiyi 时无需任何配置即自动落 taiyi 档（显式给档恒优先可覆盖）；一键组合见下方「最小集绑定星域」。

按域覆盖（runtime.domains）：defaultDomain 钉定某域时，该域的 lean/阈值/工具档位覆盖全局配置（其他域不受影响）：

{
  "runtime": {
    "domains": {
      "taiyi": {
        "lean": true,
        "toolPreset": "taiyi",
        "maxLoadedSessions": 4,
        "idleAgentTtlMs": 600000,
        "maxEventsDiskBytes": 10485760
      }
    }
  }
}

解析链：RIVET_LEAN 环境变量（恒优先）→ 域覆盖 → 全局 runtime。桌面端：设置 → 行为 → Lean 资源档 → 按域覆盖（域列表随新增星域自动扩展）。注意：域覆盖在会话装配期生效（启动钉定域时）；运行中 /domain 切换不影响已冻结的工具集与 lean（改工具指纹会重建前缀缓存）。

无需改文件的一键启动：/config → Basics → 「最小集绑定星域」——选中某域（如 changgeng 或 taiyi），保存即自动写入 defaultDomain 钉定该域 + 该域的 taiyi 最小工具档覆盖（不含 lean 资源减配）。此后 rivet 裸启动即进入该星域的最小集会话；配合「默认模型」字段（agent.defaultModel，provider:modelId 格式）即可完全免参数启动。清空绑定则恢复默认域（域覆盖配置保留）。桌面端同款项：设置 → 系统 → 「最小集绑定星域」。

⌨️ 斜杠命令

分层提示：输入框输入 / 默认只展示约 20 条核心命令（高频好用的优先露出）；继续输入任意字符即过滤全部命令（含 /team、/council、/skill 等进阶命令），Ctrl+P 命令面板永远全量模糊搜索。命令总数 65+ 条（外加已安装的 skills），分层只影响「发现性」，不删任何命令。

会话与项目

模型与权限

规划与编排

审查模式

每次 deliver_task 提交代码时，天枢会自动运行提交后审查。审查分两级：文档/配置等机械变更自动跳过（L1 nudge），核心代码变更触发 L2 接线检查（wiring inspector）。审查结果出现在交付报告中，不会阻止提交（advisory）。

• CLI（TUI）：默认开启。设置面板 → 审查 → 关闭提交后自动审查 可手动关闭（勾选即跳过审查）。也可用 RIVET_REVIEW_DISCIPLINE=0 环境变量全局关闭。
• 桌面端（desktop）：标准 DeepSeek 会话默认开启，Spark 会话默认开启且审查子代理用 spark-flash。在 设置 → Routing → 审查子代理 中可找到两个独立开关：SkipAuto（标准会话）、SkipAutoSpark（Spark 会话）。
• 手动审查：任何时候可用 /review（L2 对抗审查）或 /review max（L3 五席审查 squad）对当前改动执行深度审查。这是显式请求，不受开关控制。

子代理与后台任务

上下文与调试

回滚与界面

倒带：双击 ESC（间隔 <400ms）打开消息历史，选任一过往用户消息倒带到该点——不是斜杠命令，是快捷键。按 Esc 关闭任意覆盖层。

🛠️ 面向开发者

技术栈

Node.js 22 · TypeScript strict（noUncheckedIndexedAccess）· T9 ANSI 渲染引擎 · tsup 打包 · node:test + assert/strict

构建与测试

npx tsc --noEmit                                    # 类型检查
npm test                                             # 所有测试（13,000+ 用例）
npm run build                                        # tsup 打包 + 原生/wasm 载荷落位
node dist/main.js                                    # 启动 TUI
node dist/main.js -p "fix the typo"                  # 无界面模式

扩展

• 添加工具 —— 在 src/tools/ 实现 ToolDefinition + executor，在 src/main.tsx 注册，在 src/tools/__tests__/ 加测试。
• 添加 skill —— 在 .rivet/skills/ 放一个带 frontmatter（name、description、triggers）的 .md。
• 添加斜杠命令 —— 项目级 .rivet/commands/*.md，支持 $ARGUMENTS 插值。
• 添加 hook —— 实现 PreToolUse | PostToolUse | UserPromptSubmit | PreCompact 处理器，通过 HookRegistry 注册；处理器相互隔离，单个坏 hook 不会让循环崩溃。
• 项目指令 —— 在项目根放 .rivet.md，其内容会自动注入为项目上下文。

架构

src/
├── agent/     核心循环：turn-orchestrator、tool pipeline、coordinator、
│              advisory-bus、goal-tracker、sensorium、免疫系统
├── api/       流式 API 客户端 —— DeepSeek、GLM、Codex OAuth、多提供商路由
├── prompt/    提示词引擎 —— 冻结前缀 + 增量附录 + 易变上下文层
├── tools/     工具 —— bash、edit、read/write、grep、glob、run_tests、git、delegate…
├── tui/       终端 UI（T9 ANSI 引擎：scrollback、输入控制、覆盖层、流式渲染）
├── compact/   三层语义修剪 + 微压缩 + 请求时坍缩
├── context/   上下文账本、渐进式压缩、声明系统、锚点注册表
├── config/    Zod 验证配置：默认值 → ~/.rivet → 项目覆盖
├── server/    桌面端 sidecar：会话管理、REST 路由、SSE 流
├── mcp/       Model Context Protocol 客户端（stdio + SSE）
├── lsp/       Language Server Protocol 集成
└── search/    语义搜索（BM25 + embedding RRF 融合）

会话数据与日志排查

会话日志存在项目外的数据根下，避免被 glob/grep 扫到、也不污染工作区。全局配置在 <数据根>/config.json。每次启动得到唯一会话 ID，多个实例可并行运行互不干扰。

先定位数据根

CLI 与桌面不是同一套解析链。 CLI 认环境变量 RIVET_HOME；桌面端认 Settings → 存储位置写入的 launcher.json，不读 shell 里的 RIVET_HOME。两边要对齐，请在桌面设置里改，或让 CLI 也 export RIVET_HOME 到同一目录。

不用记路径：三个入口

# 终端（TUI 起不来也能用——不初始化 agent、不读配置、不联网）
rivet logs                         # 列出本项目最近主会话的全部落点 + 是否已产生 + 门控说明
rivet logs --session <id>          # 指定会话
rivet logs --json                  # 结构化输出，可贴进 issue
rivet logs open                    # 在文件管理器中打开会话目录
rivet logs open desktop            # 打开 sidecar 日志目录（GUI 起不来时第一现场）

• TUI：/logs（同上清单）；/logs open / /logs open desktop 直接打开目录
• 桌面端：Settings → 存储位置 →「打开数据目录」/「打开日志目录」

本会话常见落点（相对数据根）

slug = <项目目录名>-<cwd 的 sha256 前 6 位>。同名不同路径的项目不会撞车。

项目内另有 <cwd>/.rivet/knowledge/、artifacts/、plans/ 等共享数据；无 sessionId 时六维偶尔也会回退写到 <cwd>/.rivet/sensorium.jsonl——rivet logs 会把实际路径打出来。

场景速查

RIVET_SESSION_DIR / RIVET_DESKTOP_DIR 可分别搬走会话树与桌面树；生效中的覆盖会出现在 rivet logs 输出顶部。

🔒 安全

• 路径边界强制 —— glob/grep/diff 拒绝 .. 穿越；validatePath 阻止逃逸
• 符号链接环保护 —— realpath + 访问集
• SSRF 保护 —— 逐跳 DNS + 私有 IP 拦截，作用于每次重定向
• 敏感文件拒绝 —— .env、credentials.*、*key*、*token* 禁止读/commit
• 破坏性命令门禁 —— rm -rf、force push、DROP/TRUNCATE 需显式确认
• 检查点 + 回滚 —— 每回合首次修改文件前创建 Git 检查点
• 文件级撤销 —— 每次写/编辑前版本化备份
• Worker 安全 —— AbortController 超时预算，工具白名单强制

⚡ 关键配置速查

环境变量

路径与数据

模型与工具

TUI 显示

调试与任务

完整环境变量清单（120+ 项，含内部实验开关）见 src/config/env-registry.ts。

~/.rivet/config.json 关键字段

只写需要覆盖的字段，默认值会深度合并。完整 schema 见 src/config/schema.ts。

{
  "agent": {
    "maxTurns": 200,              // 单次会话最大回合数
    "approval": "auto-safe",      // manual | auto-safe | dangerously-skip-permissions
    "crossSessionEnabled": true,  // 跨会话知识共享
    "checkpointEveryTurns": 0,    // Auto 模式检查点间隔（0 = 关）
    "defaultDomain": "qiming",    // 默认星域（qiming/auto/显式域名）
    "visionModel": {              // 识图桥：主控模型不支持看图时，先转成文字描述
      "provider": "minimax",      // 需已配好 key，且该模型声明 supportsVision
      "model": "MiniMax-M3"
    },
    "visionAutoBridge": false,    // 未配 visionModel 时自动挑一个可用视觉模型（默认关）
    "permissions": {              // 权限规则（对应 /permission 命令）
      "allow": [{ "tool": "read" }],
      "deny":  [{ "tool": "bash", "params": { "command": "rm -rf" } }],
      "bash": { "allowlist": ["git status"], "denylist": ["git push"] }
    }
  },
  "compact": {
    "enabled": true,
    "autoThreshold": 800000       // 触发自动压缩的 token 阈值
  },
  "cache": {
    "enabled": true,              // 前缀缓存总开关
    "showHitRate": true           // GlanceBar 显示命中率
  },
  "tools": {
    "preset": "minimal"           // minimal（默认）| frontend | full
  },
  "workers": {
    "profiles": {                 // 自定义 worker 模型档位
      "capable": { "provider": "deepseek", "model": "deepseek-v4-pro" },
      "cheap":   { "provider": "minimax",  "model": "MiniMax-M2.7" }
    },
    "routing": { "code_edit": "capable", "repo_summarization": "cheap" },
    "patcherTier": "cheap"        // 天梁执行 worker 默认档位：cheap | balanced | strong
  },
  "search": {
    "backends": ["bing", "duckduckgo"],  // web_search 后端链（首个有结果即停）
    "braveApiKeyEnv": "BRAVE_API_KEY",   // 用 Brave 时填 env 变量名
    "tavilyApiKeyEnv": "TAVILY_API_KEY", // Tavily（需 key，offshore）
    "bochaApiKeyEnv": "BOCHA_API_KEY"    // 博查（国内直连 AI 搜索，Tavily 国内替代，需 key）
  },
  "ui": {
    "theme": "auto",              // 内置名 | auto（OSC 11 探测）| custom:<name>
    "reducedMotion": true,        // 无障碍：冻结 spinner/徽章动画
    "screenReader": true,         // 无障碍：读屏模式（同 --screen-reader）
    "glanceDensity": "compact"    // GlanceBar 密度：compact | full
  },
  "mirrors": { "enabled": true, "preset": "china" },  // npm/github 等镜像加速
  "env": { "extraPath": ["/usr/local/bin"] }           // 注入 PATH（Windows git-bash 等）
}

配置层叠优先级：命令行 flag > 环境变量 > 项目 .rivet-config.json > 用户 ~/.rivet/config.json > 内置默认值。

📚 文档

🤝 社区与支持

• 使用问题 / 讨论 → GitHub Discussions
• Bug 报告 / 功能请求 → GitHub Issues
• 安全漏洞 → 私密报告（不要开公开 issue）
• 贡献代码 → 见 CONTRIBUTING.md
• 求助指南 → 见 SUPPORT.md

提示：需要先由仓库维护者在 Settings → General → Discussions 中开启 Discussions 功能。

✨ 贡献者

感谢以下贡献者为天枢做出的贡献（按首次贡献时间排序）：

欢迎通过 PR 贡献代码，详见 CONTRIBUTING.md。

☕ 赞助支持

如果天枢对你有用，欢迎随缘打赏——这只是一杯咖啡，不是合同。赞助不会改变 issue 优先级，也不会影响功能排期。

许可证

本项目采用 Apache License, Version 2.0 开源许可。Copyright 2025-2026 Tianshu Contributors.