README.md

August 28, 2026 · View on GitHub

天枢 _{Tianshu Harness}

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

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

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

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

_{左：终端 TUI（v3.8.0，欢迎页 + GlanceBar 状态栏） · 右：桌面端 GUI（会话侧栏 + 星域速选，主题工作室自定义壁纸）——同一 agent 内核}

Note

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

🚀 快速开始

1. 环境要求

Node.js ≥ 24（engines 钉定）—— 用 node --version 检查。低版本 npm 安装时仅告警但不在支持范围；一键安装脚本会直接拦截并给出升级指引。
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（建议 ≥ 120）——v3.5 起的滚动与渲染优化需要较新运行时，旧版会导致会话区滚动卡顿。自 3.5.3 起安装器内嵌完整离线安装包（无需联网、系统级注册）。存量用户经自动更新升级后若提示过旧：在提示条或「设置 → 运行时与关于」里点「运行修复工具」。窗口完全打不开时，用开始菜单「修复 WebView2」，或从 Releases 下载 windows-repair 目录双击 repair-webview2.cmd。也可手动安装 WebView2 离线安装包后重启。 Win10 平板模式已知行为：平板模式下切换应用会把上一个应用滑出屏幕——computer_use 的快照已做遮挡/后台自愈（PrintWindow 渲染），无需关闭平板模式。

方式 B：一键安装脚本（推荐） —— 校验 Node ≥ 24 → 全局安装 tianshu-tui（默认 npmmirror 镜像加速，NPM_CONFIG_REGISTRY 可覆盖）→ 启动 rivet；幂等可重复执行：

# macOS / Linux（bash）
bash <(curl -fsSL https://raw.githubusercontent.com/huiliyi37/Tianshu-Tui/main/scripts/install-tui.sh)
# 只安装不启动：
bash <(curl -fsSL https://raw.githubusercontent.com/huiliyi37/Tianshu-Tui/main/scripts/install-tui.sh) --no-launch

# Windows（PowerShell）
powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/huiliyi37/Tianshu-Tui/main/scripts/install-tui.ps1 | iex"
# 只安装不启动（克隆仓库后本地跑）：
powershell -ExecutionPolicy Bypass -File scripts\install-tui.ps1 -NoLaunch

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

npm install -g tianshu-tui
rivet

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

方式 D：从源码构建：

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   # 密钥写入 secrets.json（0600），config.json 只留 keyRef
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）

命令行参数

参数	说明
`-p <prompt>` `--print <prompt>`	单次提示，文本输出后退出（退出码：成功 0 / 失败 1）
`--json`	与 `-p` 配合，输出单个 JSON 结果
`--stream-json`	NDJSON 事件流（`text_delta` / `tool_use` / `tool_result` / `worker` / `turn_complete` / `result`），输出内置脱敏，适合 CI
`--goal "<task>"`	无头目标自主模式，跑到目标完成或 `--budget` 上限
`--budget <N>`	goal 模式回合预算（默认 100）
`--model <name>`	本次会话覆盖模型
`--provider <name>`	本次会话覆盖 provider
`--continue` `-c`	恢复当前 cwd 的最近会话
`--resume <id\|前缀>` `-r <id\|前缀>`	恢复指定会话（短前缀即可）
`--resume` `-r`（裸）	启动后打开会话选择器
`--new`	强制开新会话
`--list` · `rivet sessions`	打印会话列表后退出
`--dangerously-skip-permissions`	单次会话全自动（跳过所有审批；沙箱仍开）
`--screen-reader`	读屏模式（动态段整体不渲染、周期重绘停转）
`--skip-welcome`	跳过欢迎屏
`--stream-events <path>`	把本次 run 镜像为 NDJSON `SessionEvent` 写入文件

子命令：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 可关闭检查。

⚙️ 模型配置

多提供商 + 自适应路由

提供商	认证方式	旗舰模型
DeepSeek	API key	deepseek-v4-pro (1M ctx), deepseek-v4-flash, deepseek-v4-flash-vision-exp（视觉）
DeepSeek Spark（Pro 专属）	API key（`DEEPSEEK_SPARK_API_KEY`）	deepseek-v4-flash（轻量推理 + 锚点缓存通道）
Claude	API key（通过 `cc-switch` 代理）	claude-opus-4-8, claude-sonnet-4-5
GLM（智谱）	API key	glm-5.3 (1M ctx), glm-5.3-flash（视觉）, glm-5.2
Codex (GPT-5.6)	OAuth PKCE（ChatGPT 订阅）	gpt-5.6-sol
MiniMax	API key	MiniMax-M3, MiniMax-M2.7
MiMo	API key	mimo-v2.5-pro

会话内用 /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"），不让模型凭"我截了图"断言渲染正常。

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

需要添加新的视觉 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.6-sol" },
      "cheap":   { "provider": "minimax", "model": "MiniMax-M2.7" }
    },
    "routing": { "code_edit": "capable", "repo_summarization": "cheap" }
  }
}

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

🔐 权限模式

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

模式	命令	行为
监督	`/permission supervise`（别名 `manual`）	每个高风险工具都弹确认。最大控制，适合敏感项目。
自动（默认）	`/permission auto [轮次]`（别名 `default`）	低/无风险工具自动执行，高风险仍确认。可配每 N 轮暂停检查点（`/permission auto 20`），默认关闭。
全自动	`/permission unattended confirm`、`/yes` 或 `/yolo`	免审批执行，无刹车无打扰；写沙箱仍开。回滚兜底（`/rollback` + git 检查点）。未带 `confirm` 先看风险说明；`/yes` / `/yolo` 即时生效（显式输入即视为确认，持久化为默认），`/yolo off` 回到自动。

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

rivet config set-approval dangerously-skip-permissions  # 启动即全自动
rivet --dangerously-skip-permissions                    # 单次会话全自动

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

/permission                              # 弹出模式选择面板（上下选 + 回车确认）
/permission status                       # 文字视图：当前模式 + 所有 allow/deny/bash 规则
/permission supervise                    # 切监督（别名 manual）
/permission auto [轮次]                  # 切自动，可选检查点间隔（0=关）
/permission unattended 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 覆盖层。

自动档检查点：在自动档下，可设置每 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

三大核心架构支柱

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

三大支柱在真实会话里的运行台账——CVM 决策记录、信息素落盘、逐请求缓存命中——见指标观测 harness 与真实数据。

工程质量指标

指标	数值
CLI 源码（TypeScript，不含测试）	1,078 文件 / 约 25.8 万行
测试代码	1,361 文件 / 约 25.6 万行
测试用例（node:test，静态声明口径）	16,471，测试 : 源码 ≈ 1 : 1
累计提交	6,178（main 分支；2026-05-15 建仓，105 天）
类型检查	`tsc` strict + `noUncheckedIndexedAccess`
前缀缓存命中率	长会话稳态实测 95–99%

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

✨ 核心特性

前缀缓存引擎

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

冻结前缀 —— 系统提示词 + 工具定义 + 稳定上下文在会话开始时被冻结，会话内不再重写，让后续请求尽量命中缓存。
增量附录 —— 动态上下文（进度、advisories、信号）以跨回合 diff 追加块注入，不重写历史。回合间增量约 200 字节 vs ~5KB 全量重写。
Read-ref 去重 —— 对未变化文件的重复读取返回紧凑引用，而非重发完整内容。
缓存感知压缩 —— 压缩保留前 2 条消息作为缓存锚点。
resume 缓存继承 —— 会话冻结快照落盘（每个 user 边界 + shutdown），resume 时读回喂给新引擎，避免从字节 0 全 miss；无快照/坏文件/服务商缓存过期时才退化全量重建。
诊断 —— /debug cache 显示命中率、未命中原因分析、每回合缓存历史。

实战命中率：长会话稳态 95–99%。这不是"每次都命中"——缓存会在某些边界碎裂（见下）。真实工程会话的逐请求日志（5 个会话、2,001 请求、6.45 亿 input tokens、账单从 ¥880 压到 ¥20）与复算命令见指标观测 harness。

缓存碎裂与排查

高命中率的前提是前缀字节稳定。以下情况会让缓存 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 并行执行，带文件冲突感知调度
子进程隔离（可选） —— RIVET_WORKER_ISOLATION=1 后每次派发独立子进程（stdio NDJSON 协议 + watchdog 击杀梯度），默认进程内

工具集与 preset

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

Preset	工具数	说明
minimal	29	日常开发全能力——读写/检索/bash/git/测试/委托/web/计划/todo/memory，省 token、保 prefix cache
frontend（默认）	30	minimal + `browser_debug`（UI 渲染验证闭环）
full	50	全集，含 `council_convene` / `team_orchestrate` / `attack_case` / `semantic_search` / `repo_graph` / `monitor` / `computer_use` / `capability` / `cli_discover` / 办公工具族等进阶能力
taiyi	16	最小评测档——高频核心 + 交付闭环，去编排/浏览器/网络/视觉等重工具；太一星域钉定时自动落此档（见下文「最小工具集」）

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 不会立即修改代码，而是：

调研 —— 读取相关代码、理解现有架构和约束（可 delegate_batch 并行派 code_scout 探查各模块）
生成方案 —— 产出结构化计划文档（技术调研、架构图、任务拆解、验证方案），写入 .rivet/plans/<slug>.md
提交审批 —— plan 工具 action=submit 提交，列出方案要点和备选路径，等待你的确认
审批执行 —— 你用 /plan-list 查看、/plan-approve <slug> 批准并启动分波执行、/plan-reject <slug> <反馈> 退回让 agent 修改重交
关闭收尾 —— /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 实时进度（待办项面板随波次推进自动勾选）。

星域系统

星域是什么：天枢把不同的认知姿态建模为「星域」——每颗星不是角色扮演，而是一套可切换的认知纪律。进入对应域后有三样东西真实切换，而非换个名字：系统提示词（该域方法论 volatile block）、工具白名单（worker 与域 toolWhitelist 求交集）、决策阈值（courageThreshold——破军 0.25 最敢闯、太一 0.95 最审慎、瑶光 0.7 要证据）。新会话默认钉定启明（全景洞察、根因推演），不自动切换；把默认星域设为 auto 才按任务描述关键词自动路由（池内为天权/开阳/瑶光/天梁 + 自定义域；华盖等特化域需手动指定）。星域在真实会话里的行为样本见指标观测与真实数据。

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

🌟 新用户推荐

第一次不知道选哪颗星，从这五颗开始——它们覆盖日常工程闭环，其余星域在下方按任务场景速查：

星域	别名	推荐理由
启明 `qiming`	晨光向导（默认域）	通用工程能力 · 全景洞察——需求模糊、方向不明时，先看清全局、直击根因再动手
长庚 `changgeng`	守夜人	通用工程能力 · 终局成全——视觉终验、长夜陪伴、交接收尾，收灯前把路标留下
太一 `taiyi`	极简中心	极简体验——内置 16 件核心工具（taiyi 档）、不催促不打扰；喜欢安静高效就手动 `/domain taiyi`
天权 `tianquan`	方案审查官	擅长规划与审查——架构评估、方案权衡、技术选型，产出可执行计划
瑶光 `yaoguang`	复现验证官	擅长审查与验收——复现缺陷、回归验证、盯假绿灯——绿灯不算数

五颗之外的日常出口：规划定稿后想精准交付，切天梁（交付执行官）——分波落地、逐批验证、交付留痕。

按任务场景选星

场景	星域	别名	适合攻坚
规划与审查	启明 ☥ `qiming`	晨光向导	需求模糊、方向不明——探针先行，全景洞察、根因推演（默认域）
规划与审查	天权 ⚖ `tianquan`	方案审查官	架构评估、方案权衡、技术选型、出可执行计划
规划与审查	天机 ⚝ `tianji`	前提质疑官	给方案找漏洞、推演失败模式、挑战没人说出口的前提
规划与审查	天枢 ✵ `tianshu`	全局统筹官	跨模块统筹、全链路闭环、复杂系统治理（显式开启的统筹位）
执行与交付	天梁 ✧ `tianliang`	交付执行官	定稿计划精准落地、分波交付、逐批验证留痕
执行与交付	华盖 ☉ `huagai`	守昼者	长程建设、多轮审查马拉松、最后一英里收尾
验证与验收	瑶光 ↻ `yaoguang`	复现验证官	复现缺陷、回归验证、缺陷归族——绿灯不算数
验证与验收	开阳 ☌ `kaiyang`	对账师	性能测量、插桩对账、仿真回放、量化定位
验证与验收	长庚 ☽ `changgeng`	守夜人	视觉终验、交接收尾、长夜陪伴式任务
探索与攻坚	破军 ☄ `pojun`	探索先锋	陌生代码库、POC 原型、技术攻坚、边界突破
探索与攻坚	天璇 ☾ `tianxuan`	跨域寻迹者	换视角解死结、跨领域找同构、根因复盘
守护与重构	天府 ❖ `tianfu`	结构守护者	重构、稳定性、存量代码维护、守护既有结构
守护与重构	七杀 ◌ `qisha`	肃秋剪枝官	精简冗余、清理死代码、注意力预算审计
认知与美学	文曲 ✺ `wenqu`	代码美学者	命名与结构、代码质感、UI 与前端体验
认知与美学	辅 ⊕ `fu`	认知调校师	提示词调校、方法论蒸馏、agent 行为诊断
认知与美学	太一 ◉ `taiyi`	极简中心	极简高效——最小工具集、中虚不催（手动切换，不参与自动路由）

各星完整碑文、创始记忆、主星模型与核心信念见 ✦ 星域碑文。

每颗星都有对应的 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）、跑过的验证命令与结果、提交哈希
当前卡点 — 卡在哪、已排除哪些方向、怀疑对象
下一步 — 按优先级排列、每条是可立即执行的动作
坑 — 绝对不要再踩的坑，每条一句话说清后果

上下文占用 ≥60% 时，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	说明
`visual-acceptance`	前端/UI 改动验收：截图比对、渲染自检、交互走查
`subagent-driven-development`	委派复杂任务，类型化 profile、批量调度、并行 worker

/skill visual-acceptance <你的任务>    # 加载并立即执行该 skill
/skill off visual-acceptance           # 停止重复注入该 skill

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

writing-plans / executing-plans 已内置为原生流程（规划期按系统提示的 <plan-mode> 纪律、执行期按 <plan-executing> 纪律执行），不再需要技能文件。agent-harness-testing / cognitive-alignment / research-spec 撤出默认分发，归档在 docs/skills/optional/——需要时手动拷入 .rivet/skills/ 即可启用。

跨会话知识

来源	内容
`.rivet/knowledge/memory.jsonl`	项目规则、调试启发式、架构约定
`.rivet/sessions/<slug>/<id>/pheromones.json`	会话内信息素（非跨会话；跨会话知识见上一行）
`.rivet/presence.json`	伴生 agent 感知

通过 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 还内置一组面向编码场景的交互能力：

能力	说明 · 快捷键
GlanceBar 状态栏	输入框上方单行实时显示：星域 glyph · git 分支 · 模型 · 推理强度 · 缓存命中率 · 上下文占比 · 本轮 cost · 耗时 · turn 计数 · todo 徽章。一屏掌握会话健康度。
流式中打断（Steer）	agent 还在跑时直接打字，回车即可注入。输入按 `now / next / later` 三档优先级排队，在工具结果或回合边界 drain 给 AgentLoop——不必等它说完。`halt` 类意图自动升到 `now`。
消息排队（/queue）	`/queue <text>` 显式排队：agent busy 时攒下整条消息，settle 后自动投递；Esc 中断后排队内容回填输入框不丢失。输入区实时显示后台任务条与 await 等待区。
终端内联图片	kitty / iTerm2 图形协议在终端里直接渲染图片（工具产物、截图验证结果）。默认自动检测协议，`RIVET_IMAGES=0` 关闭、`kitty`/`iterm2` 强制指定。
@mention 补全	输入 `@file:` / `@folder:` / `@symbol:` 触发路径补全（走 `git ls-files`，支持带空格的 `@file:"a b.ts"` 引用形）。直接粘贴图片自动转 base64 内联（macOS/Linux/Windows 三级降级）。
倒带 Rewind	双击 `ESC`（间隔 <400ms）打开消息历史，选任一过往用户消息倒带到该点；可选「仅对话 / 仅代码改动 / 两者」三种恢复粒度，代码动作附带精确的文件影响预览。详见倒带。
命令面板	`Ctrl+P` 打开，模糊搜索所有 slash 命令与 surface 动作（开关侧栏、切主题、进 Cockpit 等），↑/↓ 选中、Enter 执行，再按 `Ctrl+P` 关闭。原 `Ctrl+Esc` 在 Windows 被系统「开始菜单」抢占、在传统转义序列下与 Esc 同码不可区分，已换绑。
Cockpit 驾驶舱	`Ctrl+P` → 选 Cockpit，或 `/cockpit <panel>` 进入。8 面板全屏视图：summary / trace / verify / context / safety / model / mcp / advisory，←/→/Tab 切换聚焦，实时展示 doom-loop 等级、验证交付状态、缓存与投机预读统计、MCP 连接、advisory 提醒等。
多智能体面板	`/tasks` 打开全屏 worker 详情（融合 live 视图 + JSONL 转录，含 Contract/Activity/Result/Transcript 分段与诚实标签）；宽终端（≥100 列）下 `Ctrl+]` 切出右侧抽屉，实时展示舰队树、团队波次 DAG、todo、token 仪表。
主题与无障碍	`/theme [name
欢迎页「定盘星」	立体 TIANSHU 字标 + 使命行星光扫过 + 进入提示区（交接提醒 / 缓存提示）。`RIVET_WELCOME_LOGO=pixel` 切点阵字标（窄屏 <58 列自动降档），`RIVET_WELCOME_ANIM=0` 关扫光，`--skip-welcome` 跳过整页。
diff 行内高亮	行内 word-level 粒度差异标色，长行改动一眼定位实际变化。

TUI 键位

键位	作用
`Enter`	发送 · `Shift+Enter` 换行
`Ctrl+C`	三态：agent 活跃时中断当前 run；有输入时清空输入行；空闲时 2 秒内双击退出
`Esc`	关闭覆盖层 / 退出 worker 视图；agent 跑时中断；vim 模式下兼 normal↔insert；双击（<400ms）倒带
`Ctrl+P`	命令面板（Ctrl+Esc 被 Windows「开始菜单」抢占，已换绑）
`Ctrl+]`	切右侧抽屉（宽终端）
`Ctrl+R`	历史搜索 overlay（仅空闲时）
`Ctrl+O`	展开/折叠最近被截断的工具结果
`Ctrl+T`	折叠/展开推理（thinking）区
`Ctrl+X` `r`	leader 键：`Ctrl+X` 后接 `r` 开右侧面板
`Ctrl+X` `t`	leader 键：`Ctrl+X` 后接 `t` 展开 todo 全量回看
`↑`	输入框为空且队列有 pending 时，取回最近一条排队 steer 消息编辑
`@`	触发文件/文件夹/符号补全（`Tab` 循环候选，退格整块删除）
`Ctrl+V`	粘贴剪贴板图片（自动转 base64 内联）
`F1`–`F8`	高频命令直绑：F1 /help · F2 /tasks · F3 /cache · F4 /cockpit · F5 /theme · F6 /model · F7 /permission · F8 /sessions

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）。核心快捷键：

快捷键	作用
`⌘/Ctrl+K`	命令面板
`⌘/Ctrl+N`	新会话
`⌘/Ctrl+1…9`	切换功能面板
`⌘/Ctrl+,`	设置
`⌘/Ctrl+Shift+]` / `[`	下/上一个会话标签
`⌘/Ctrl+W`	关闭标签
`⌘/Ctrl+B`	切侧栏
`⌘/Ctrl+Shift+B`	切审查面板
`⌘/Ctrl+J` · Ctrl+`	切集成终端
`⌘/Ctrl+;`	SideChat 旁路提问
`⌘/Ctrl+.`	Zen 模式
`⌘/Ctrl+O`	视图模式循环（standard → verbose → summary）
`Shift+Tab`	Plan / Agent 模式切换
`Esc Esc`	倒带（桌面端 Rewind）

桌面端还有 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 命令面板永远全量模糊搜索。命令总数 90+ 条（外加已安装的 skills），分层只影响「发现性」，不删任何命令。

会话与项目

命令	说明
`/help`	显示可用命令
`/sessions` `/resume <n>`	列出/恢复已保存会话（恢复侧栏、待办、活动计划）
`/fork`	分叉当前会话（可选从某条消息起）
`/handoff [备注]`	写结构化交接文档（五章节），归档后自动注入新会话
`/init`	交互式项目初始化：verify 声明 / skills / hooks 脚手架
`/doctor`	环境健康检查 + bash 工具用的哪个 shell
`/logs [open [desktop]]`	本会话日志落点（会话 / 缓存 / 六维 / 桌面 sidecar），含写入门控与回收说明；`open` 在文件管理器中打开
`/connect`	连接模型服务商向导（选内置或自定义，填 API 密钥）
`/config` `/settings` `/setup`	设置面板：子代理路由 / 审查开关（`审查 → 关闭提交后自动审查`） / 识图模型 / 工具档位·审批·默认星域·默认模型 / 镜像·代理·搜索后端。`Tab` 切栏、`Enter` 编辑、`S` 保存，每项标注即时或下次会话生效
`/cd <path>`	会话中途切换工作目录（保前缀缓存，会话归属迁往新项目）
`/trust`	项目信任管理——未授信项目不加载 hooks / 项目 MCP，剥离项目配置安全键
`/exit` `/quit`	保存会话并退出

模型与权限

命令	说明
`/model [name\|list]`	显示或切换模型/提供商
`/effort [off\|low\|medium\|high\|max\|auto]`	控制推理深度（无参数弹出选择面板）。默认 `high`（Pro）/ `medium`（Flash），例行轮自动降档；手动设 `max` 永不被降级
`/permission [supervise\|auto\|unattended\|manual\|yolo\|allow\|deny\|bash\|remove\|reset\|test]`	权限模式：监督 / 自动 / 全自动
`/yes [off]` `/yolo [off]`	一键全自动，两者同语义（`off` 回到自动）—— 持久化为默认，重启后仍生效
`/domain [list\|<name>\|auto\|off]`	查看或切换星域人格

规划与编排

命令	说明
`/goal <text>`	设置自主目标，运行到完成
`/cancel-goal`	停止目标执行
`/plan <feature>`	生成计划草稿（writing-plans 工作流）
`/plan-mode`	进入/退出 Plan Mode（toggle；未批准退出需二次确认）
`/plan-list`	列出待审批计划
`/plan-view [ref]`	全屏预览计划全文（审批卡上按 `v` 同效）
`/plan-approve <slug>`	批准计划并启动分波执行
`/plan-reject <slug> [feedback]`	退回计划让 agent 修改重交
`/plan-close <file> --tasks <1-7\|all> [--preview]`	关闭已完成计划，标记任务状态
`/ask`	进入/退出 Ask Mode（只读问答，toggle）
`/council <text>`	召集多模型议事会审查（天权/天府/天璇三席）
`/team <plan.md>`	团队模式：多 agent 并行执行计划
`/scout <目标> [--dims 前端,后端,集成]`	巡天侦察蜂群：并行只读诊断，交付带证据的实测核对清单 + runbook（不写文件；选型口诀——要留计划资产用 /team，只要这一次并行加速用 /scout）

审查模式

每次 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）对当前改动执行深度审查。这是显式请求，不受开关控制。

子代理与后台任务

命令	说明
`/tasks`	打开子代理任务面板（查看 / 切入 `f` / 停止 `x`）
`/enter <orderId> [prompt]`	进入/续跑某个 worker 子会话
`/jobs`	打开后台任务面板（bash 后台启动的 shell 任务列表）

上下文与调试

命令	说明
`/compact`	立即压缩上下文
`/context`	显示上下文账本：健康度、tokens、回合、声明
`/evidence`	显示证据摘要（读取/修改的文件、测试）
`/memory <text>`	保存会话记忆条目
`/btw <问题>`	侧问——就当前会话问一句，回答显示在浮层，不进对话历史
`/debug [prompt\|cache\|mcp]`	调试 prompt、缓存统计或 MCP
`/mcp`	MCP 服务器连接状态
`/verbose`	切换详细工具输出（on 显 200 行 / off 显 20 行）

回滚与界面

命令	说明
`/rollback`	预览/恢复 git 检查点（`confirm` 执行）
`/undo`	撤销上次文件变更（预览，`confirm` 恢复）
`/theme [name\|list]`	切换色彩主题
`/vim`	切换 vim 键绑定
`/cockpit`	切换 Cockpit 驾驶舱面板
`/scroll`	浏览输出历史（q / Esc 关闭）
`/skill <name>`	加载并立即执行一个 skill
`/skill off <name>`	停止重复注入某个 skill
`/update`	检查并安装更新（npm）

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

🛠️ 面向开发者

技术栈

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

构建与测试

npx tsc --noEmit                                    # 类型检查
npm test                                             # 所有测试（16,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	`RIVET_HOME` → 平台默认	macOS/Linux: `~/.rivet`；Windows: `%LOCALAPPDATA%\.rivet`
桌面 · 系统安装	Settings → 存储位置（`launcher.json`）→ 平台默认	同上
桌面 · 便携版	exe 旁 `TianshuData\.rivet`	例如 `D:\Tools\Tianshu\TianshuData\.rivet`

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 位>。同名不同路径的项目不会撞车。

文件	用途	写入条件
`sessions/<slug>/<id>.jsonl`	对话主体（含 `usage` / `model_switch`）	始终
`sessions/<slug>/<id>/cache-log.jsonl`	逐请求缓存命中与侧路成本	始终
`sessions/<slug>/<id>/sensorium.jsonl`	六维 / CVM / advisory 台账	轻量行默认开；全量需 `RIVET_DEBUG_TELEMETRY`（任意非空）
`sessions/<slug>/<id>/frames.jsonl`	认知帧（相位、策略）	默认开；`RIVET_FRAME_TELEMETRY=0` 关
`logs/sidecar-<时间戳>.log`	桌面 sidecar stdout/stderr	每次启动一个新文件
`desktop/sidecar-exit.json`	sidecar 退出原因面包屑	退出时
`desktop/sessions/<id>/events.jsonl`	桌面 UI 事件流（与上面的会话 `.jsonl` 是两份数据）	桌面非 ephemeral 会话

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

场景速查

现象	先看
桌面窗口开了但助手不回话	`rivet logs open desktop`，或 Settings →「打开日志目录」；再看 `desktop/sidecar-exit.json`
缓存命中率异常 / 成本突然升高	`rivet logs` → 打开该会话的 `cache-log.jsonl` 与 `.jsonl` 里的 `cache_read_*`
想复盘六维 / advisory 是否生效	确认开了 `RIVET_DEBUG_TELEMETRY`，再读 `sensorium.jsonl`
上报 bug / 贡献排查	`rivet logs --json` 整段贴进 issue（不含对话正文，只含路径与体积）

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

🔒 安全

路径边界强制 —— glob/grep/diff 拒绝 .. 穿越；validatePath 阻止逃逸
项目信任门 —— 未授信项目的 .rivet/hooks.json 不加载、项目配置安全键被剥离、MCP 服务器不拉起；/trust 管理（CLI --trust / --untrust）
符号链接环保护 —— realpath + 访问集
SSRF 保护 —— 逐跳 DNS + 私有 IP 拦截，作用于每次重定向
敏感文件拒绝 —— .env、credentials.*、*key*、*token* 禁止读/commit
破坏性命令门禁 —— rm -rf、force push、DROP/TRUNCATE 需显式确认
检查点 + 回滚 —— 每回合首次修改文件前创建 Git 检查点
文件级撤销 —— 每次写/编辑前版本化备份
Worker 安全 —— AbortController 超时预算，工具白名单强制

⚡ 关键配置速查

环境变量

路径与数据

变量	作用
`RIVET_HOME`	覆盖整个 `~/.rivet` 数据根（CLI 生效；桌面端认 Settings → 存储位置，不读此变量）
`RIVET_CONFIG_PATH`	覆盖 `config.json` 路径（多套配置切换）
`RIVET_SESSION_DIR`	覆盖会话日志存储路径
`RIVET_RESUME` / `RIVET_RESUME_ID`	启动时恢复会话（对应 `--resume`）
`RIVET_NEW_SESSION` / `RIVET_NO_AUTO_RESUME`	强制新会话 / 禁用自动续接

模型与工具

变量	作用
`DEEPSEEK_API_KEY`	DeepSeek API 密钥
`DEEPSEEK_SPARK_API_KEY`	DeepSeek Spark（Pro 专属预设）API 密钥
`RIVET_TOOL_PRESET`	工具集档位：`minimal` / `frontend`（默认）/ `full` / `taiyi`
`RIVET_EMBEDDING_MODEL` / `RIVET_EMBEDDING_BASE_URL` / `RIVET_EMBEDDING_API_KEY`	语义搜索的嵌入模型路由（默认 `text-embedding-3-small`）
`RIVET_NO_EMBEDDINGS=1`	关闭嵌入索引
`RIVET_SANDBOX` / `RIVET_SANDBOX_WRITABLE`	追加可写沙箱根目录 / 可写目录列表
`RIVET_PLAN_MODE_SUGGEST`	Plan Mode 自动进入策略：`auto`（默认）/ `ask` / `0`（关闭）

TUI 显示

变量	作用
`RIVET_ASCII_UI=1`	强制纯 ASCII UI（降级终端）
`RIVET_IMAGES`	终端内联图片：默认自动检测；`0`/`off` 关闭；`kitty`/`iterm2` 强制协议
`RIVET_HYPERLINKS=1`	开启 OSC 8 超链接渲染
`RIVET_NOTIFY_BELL=1`	完成时响终端铃
`RIVET_AMBIGUOUS_WIDTH`	CJK 宽度判定覆盖（终端对齐错乱时用）
`RIVET_TUI_HARDWARE_CURSOR=1`	硬件光标模式

调试与任务

变量	作用
`RIVET_DEBUG=1`	总调试日志开关（最常用）
`RIVET_DEBUG_TELEMETRY`	任意非空值开启全量 `sensorium.jsonl`；只有字面 `1` 会额外拉起 TUI perf 那行 UI
`RIVET_TELEMETRY_LITE=0`	连 vitals-lite 轻量行一起关（默认开）
`RIVET_HEADLESS_MAX_TURNS`	`-p` 无头模式单次最大轮数（默认 15）
`RIVET_JOB_MAX_MS`	后台 job 超时上限
`RIVET_NO_CROSS_SESSION=1`	禁用跨会话知识共享
`RIVET_NO_UPDATE_CHECK=1`	关闭启动时的自动更新检查
`PORTABLE_GIT_MIRROR`	覆盖 PortableGit 下载镜像

完整环境变量清单（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": "frontend"          // minimal | frontend（默认）| full | taiyi
  },
  "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 > 内置默认值。

📚 文档

文档	说明
`docs/user-guide.md`	安装、配置与使用指南
`docs/desktop-guide.md`	桌面端用户指南（Cockpit/SideChat/Rewind/主题/Mirror 等独有特性）
`docs/user-guide-provider-config.md`	模型提供商配置指南
`docs/user-guide-vision.md`	识图能力（视觉通道）配置与排查
`docs/user-guide-sandbox-permissions.md`	沙箱与权限模型完整指南
`docs/reference/observability-harness.md`	指标观测 harness：缓存 / CVM / 信息素的真实会话数据样本与复算命令
`CONTRIBUTING.md`	贡献指南
`config.example.json`	示例配置（含子代理/审查模型路由）

🤝 社区与支持

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

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

✨ 贡献者

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

贡献者	贡献内容
@banxia	项目创建者 · 核心开发
@qiaodier	CC Switch provider 预设（PR #8）

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

☕ 赞助支持

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

天枢 Tianshu Harness