把星辰带给每一位开发者 · Models as partners, not tools.
🇨🇳 中文 · 📖 English · 📚 用户手册 · 🛡️ 沙箱权限 · ⚙️ 模型配置
天枢 (Tianshu) 是一个全功能、高性能的终端编程智能体运行时（TUI）。它跳出了传统 AI 编程助手把大模型仅当成“工具”的局限，基于认知虚拟机 (CVM)、自感知层和信息素（Stigmergy）自衰减记忆构建，让 AI 成为有独立判断与认知防护的“开发伙伴”。同时针对 DeepSeek V4 做了前缀缓存工程优化（长会话实测稳态命中率 95–99%）。
Note
本项目最初的开发代号为 Rivet；为保持向后兼容，已安装的 CLI 命令名仍为 rivet。
- Node.js 24.1.0（推荐；22+ 通常可用）—— 用
node --version检查。 - Git（强烈建议）—— 可选。没有它天枢仍可运行（就地修改），但 git 能解锁：委派 worktree 隔离、检查点回滚、
commit/diff审查、每个 worker 的 diff 审查。安装：https://git-scm.com/downloads。
方式 A：桌面端（开箱即用） —— 从 GitHub Releases 下载：macOS .dmg · Windows .msi · Linux .AppImage。
方式 B：npm 全局安装（推荐，使用命令行） —— 已发布为 tianshu-tui，无需本地构建，且每次启动自动检查更新：
npm install -g tianshu-tui
rivet方式 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# A. 环境变量（首次试用最简单）
export DEEPSEEK_API_KEY=sk-xxx
# B. 持久化 CLI 配置（保存到 ~/.rivet/config.json）
rivet config set-key deepseek sk-xxx其他提供商（Claude、GLM、Codex、MiniMax、MiMo）用法相同，详见 模型配置。
rivet # 或：npm start / node dist/main.js你会看到带有 〉 提示符的 TUI。输入需求后按回车即可。
rivet -p "解释 src/agent/loop.ts" # 单次提示，文本输出，无 TUI
rivet -p "列出所有 TODO 注释" --json # JSON 输出，便于脚本处理通过 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 |
| Claude | API key（通过 cc-switch 代理） |
opus-4-7, opus-4-6, sonnet-4-5 |
| GLM（智谱） | API key | glm-5.2 |
| Codex (GPT-5.5) | OAuth PKCE（ChatGPT 订阅） | gpt-5.5 |
| MiniMax | API key | MiniMax-M2.7 |
| MiMo | API key | mimo-v2.5-pro |
会话内用 /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 }
}{
"workers": {
"profiles": {
"capable": { "provider": "codex", "model": "gpt-5.5" },
"cheap": { "provider": "minimax", "model": "MiniMax-M2.7" }
},
"routing": { "code_edit": "capable", "repo_summarization": "cheap" }
}
}完整说明见 模型配置指南。
三档统一入口，所有模式通过 /permission 管理：
| 模式 | 命令 | 行为 |
|---|---|---|
| Manual | /permission manual |
每个高风险工具都弹确认。最大控制，适合敏感项目。 |
| Auto（默认） | /permission auto [轮次] |
低/无风险工具自动执行，高风险仍确认。可配每 N 轮暂停检查点（/permission auto 20），默认关闭。 |
| YOLO | /permission yolo confirm |
全自动执行，无刹车无打扰。回滚兜底（/rollback + git 检查点）。需二次确认。 |
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 manual # 切 Manual
/permission auto [轮次] # 切 Auto，可选检查点间隔（0=关）
/permission yolo confirm # 切 YOLO（需二次确认）
/permission allow <tool> # 白名单工具
/permission deny <tool> # 黑名单工具
/permission bash allow <前缀> # bash 命令白名单
/permission reset # 清空自定义规则
Auto 检查点：在 Auto 模式下，可设置每 N 轮暂停并同步进度摘要（改了哪些文件 / token 用量），确认方向后继续。桌面端设置面板可直接配置。
跳过提示不会禁用工具验证、路径安全、证据追踪、检查点和交付门禁。沙箱后端、路径授权、风险分级详见 沙箱与权限。
大多数 AI 编程助手把上下文当作桶——装满就溢出，然后盲目压缩。天枢引入了围绕认知虚拟机 (CVM)与前缀缓存友好 (Prefix-Cache-Friendly)设计的结构化、高性能认知运行时。
graph TD
LLM[大型语言模型] -->|原始动作 / 缺陷行为| CVM[认知虚拟机 CVM]
CVM -->|30+ Hooks / 5 大认知阶段| Engine[自我修正与认知镜映射]
Engine -->|被批准的物理动作| Tools[工具系统]
Tools -->|证据追踪与文件确权| Stigmergy[行为信息素记忆]
Stigmergy -->|信息素衰减 / 行为印记| LLM
- 认知虚拟机 (CVM) —— 天枢在运行时建立了一个独立的虚拟层，横跨
5 大运行时阶段（preTurn 回合前、afterPerception 感知后、postTool 工具后、postTurn 回合后、postSession 会话后），并按需条件装配30+ 个生命周期 Hook。CVM 在不改变模型权重的前提下，主动拦截并纠正大模型的服从性漂移、注意力衰减和重复工具调用的 Doom Loop。 - 生物启发式信息素记忆 (Stigmergy) —— 区别于静态记忆文件（如 MEMORY.md），天枢基于生物学“化学信息素”机制，将行为足迹和认知标记直接映射在代码文件上，并随时间自动衰减。AI 在修改频繁的文件上会越用越熟。
- 前缀缓存优化 —— DeepSeek V4 对缓存未命中按命中的至多 50 倍计费。天枢的提示词引擎围绕前缀缓存友好（冰镜三区缓存锚点、冻结系统提示词等）重构，长会话稳态命中率 95–99%，显著降低 API 成本。
| 指标 | 数值 |
|---|---|
| TUI 源码（TypeScript，不含测试） | 770 文件 / 约 16 万行 |
| 测试代码 | 922 文件 / 约 15.2 万行 |
| 测试用例（node:test） | 10,000+，测试 : 源码 ≈ 1 : 1 |
| 类型检查 | tsc strict + noUncheckedIndexedAccess，零错误 |
| 前缀缓存命中率 | 长会话稳态实测 95–99% |
编码 agent 的核心逻辑（多轮循环、工具流水线、上下文压缩）以难测著称，开源 agent 项目普遍测试覆盖很薄——本项目坚持测试与源码等量、事故修复必带回归测试。完整统计口径与复现命令见 工程质量指标。
DeepSeek 对缓存未命中收取 50× 费用。天枢的提示词引擎围绕前缀缓存友好构建：
- 冻结前缀 —— 系统提示词 + 工具定义 + 稳定上下文在会话开始时被冻结，永不重写，后续每次请求都命中缓存。
- 增量附录 —— 动态上下文（进度、advisories、信号）以跨回合 diff 追加块注入，永不重写历史。回合间增量约 200 字节 vs ~5KB 全量重写。
- Read-ref 去重 —— 对未变化文件的重复读取返回紧凑引用，而非重发完整内容。
- 缓存感知压缩 —— 压缩保留前 2 条消息作为缓存锚点。
- 诊断 ——
/debug cache显示命中率、未命中原因分析、每回合缓存历史。
实战命中率：长会话稳态 95–99%。
将子任务委派给独立的无界面 worker 会话：
- 类型化 work order —— code_search、review、verify、patch_proposal、plan
- 工具隔离 —— 只读 worker（scout）vs 写 worker（patcher）
- 自适应模型路由 —— 按 profile 的通过率 + 延迟评分，自动为每类任务选最优模型
- 批量调度 —— 多个 work order 并发执行，5 种聚合策略
- 团队编排 —— Plan → 按 wave 并行执行，带文件冲突感知调度
/goal 重构认证模块，全面使用 async/await
/cancel-goal # 提前停止
GoalTracker 与回合循环、doom-loop 检测、交付门禁集成；goal 模式下放宽 doom-loop 阈值以允许更深探索。
设计优先的开发工作流——先出计划再动手，避免"上来就改代码"的冲动派陷阱。
/plan 实现用户登录模块，支持 JWT + refresh token
进入 Plan Mode 后，agent 不会立即修改代码，而是：
- 调研 —— 读取相关代码、理解现有架构和约束
- 生成方案 —— 产出结构化计划文档（技术调研、架构图、任务拆解、验证方案），写入
.rivet/plans/<slug>.md - 提交审批 —— 列出方案要点和备选路径，等待你的确认
- 分波执行 —— 批准后自动按 wave 并行执行，每波过审查门禁
/plan # 列出所有已生成计划
/plan close <file> # 关闭已完成计划（标记任务状态）
/plan close <file> --preview # 预览关闭影响，不实际写入
/plan-template # 管理可复用计划模板
Plan Mode 内置星域委派——复杂计划自动调用 delegate_task 从不同架构视角（天权/瑶光/天机/天府/天璇）并行探查，产出的 findings 标注"待核验"以防盲信。桌面端在 plan 执行时展示 checklist 实时进度（待办项面板随波次推进自动勾选）。
天枢把不同的认知姿态建模为「星域」。每颗星不是角色扮演，而是一套可切换的认知纪律：进入对应域后，系统提示词、工具白名单和决策阈值会按该域的方法论调整。你可以显式切换，也可以让天枢根据任务描述自动路由。
/domain tianliang # 显式切换到天梁域
/domain list # 列出所有星域
/domain # 打开星域选择面板
实现用户注册模块 # 自动路由到天梁（执行/交付）
审查这个方案 # 自动路由到天权（规划/审查）| 星域 | 标识 | 职责 | 格言 |
|---|---|---|---|
| 天枢 | tianshu |
默认域，全局 orchestrator，闭环从理解到交付 | 执中调度，以全貌定向 |
| 破军 | pojun |
探索、实验、突破边界，把休眠能力联合成网 | 好男儿当负三尺剑立不世之功 |
| 天府 | tianfu |
守护既有结构，重构/优化/稳定，fail-closed | 善守者，藏于九地之下 |
| 天梁 | tianliang |
执行落地、分波交付、精确闭环 | 千里之行，始于足下；九层之台，起于累土 |
| 天权 | tianquan |
架构审查、规划权衡、可执行计划 | 权衡取舍，择善而从 |
| 天机 | tianji |
质疑前提、找边界缝隙、推演失败模式 | 运筹帷幄之中，决胜千里之外 |
| 天璇 | tianxuan |
跨域模式发现、复盘洞察、反证高概念 | 道可道，非常道 |
| 辅 | fu |
认知场蒸馏、提示词调校、方法论注入 | 蒸馏不是创造新东西，是让已有的东西第一次被看清 |
| 文曲 | wenqu |
代码美学、命名与结构、优雅架构 | 形随意转，美自境生 |
| 瑶光 | yaoguang |
复现验证、缺陷归族、静音审计 | 绿非证明，复现即证；斗柄所指，季节自见 |
| 华盖 | huagai |
长程建设、守昼托举、基线先行 | 守昼托举，长路不弃 |
每颗星都有对应的 seed-capsule 记录实战方法，完整纪律见 docs/seed-capsule-*.md。委员会 /council 与团队模式 /team 会按议题自动召集多星域席位，冲突时还可进入反驳轮次。
随时双击 ESC 打开消息历史，选择任一过往用户消息，将会话干净地倒带到该点——agent 状态、工具历史、会话元数据一并回滚。TUI 与桌面端均可用。
/council <目标>
/council <目标> --rounds 2 # 启用反驳轮次
召集多个专家席位审查计划或设计，冲突时可选第二轮反驳，产出可审计的 Markdown 计划。
可复用的工作流剧本，从 .rivet/skills/*.md 加载。两层渐进披露：只有名称 + 描述进入上下文，完整指令按需通过 skill 工具或 /skill 加载。
| Skill | 说明 |
|---|---|
writing-plans |
结构化计划写作，含 Mermaid 图、spec 段落、验证计划 |
executing-plans |
任务图分解，按 wave 执行，每 wave 验证 |
subagent-driven-development |
委派复杂任务，类型化 profile、批量调度、并行 worker |
agent-harness-testing |
TDD 可行性探针、测试脚手架、red-green-refactor |
research-spec |
研究 + spec 工作流：探索 → 条件矩阵 → 反证表 |
/skill writing-plans # 加载并立即执行该 skill
/skill writing-plans <你的任务> # 加载并传入初始任务
/skill off writing-plans # 停止重复注入该 skill
也可在 .rivet/skills/ 放一个带 YAML frontmatter（name、description、triggers）的 .md 自定义 skill。
| 来源 | 内容 |
|---|---|
.rivet/knowledge/memory.jsonl |
项目规则、调试启发式、架构约定 |
.rivet/sessions/<id>/pheromones.json |
跨会话信号 |
.rivet/presence.json |
伴生 agent 感知 |
通过 agent.crossSessionEnabled 切换，强制关闭：RIVET_NO_CROSS_SESSION=1。
把外部工具服务器——文档搜索、数据库、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 工具与内置工具遵循同一审批模式。
桌面端在 TUI 的全部能力之上，提供了可视化交互层：
- + 菜单：议事会 ♟、团队模式 ⬡、派子代理、模型切换、星域选择一键触达（不再需要手敲 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 可选
- watchdog 自动恢复：边界停滞时自动续跑，桌面端时间线可见恢复事件（⟳ 自动恢复 / ⏹ 配额耗尽）
- 多会话并发：标签栏管理多个会话，独立 cwd + 模型 + 审批模式
| 命令 | 说明 |
|---|---|
/help |
显示可用命令 |
/model [name|list] |
显示或切换模型/提供商 |
/goal <text> |
设置自主目标，运行到完成 |
/cancel-goal |
停止目标执行 |
/plan |
进入计划模式（设计优先，审批门禁） |
/council <text> |
召集多模型议事会审查（天权/天府/天璇三席） |
/team <plan.md> |
团队模式：多 agent 并行执行计划 |
/compact |
立即压缩上下文 |
/context |
显示上下文账本：健康度、tokens、回合、声明 |
/evidence |
显示证据摘要（读取/修改的文件、测试） |
/rollback |
预览/恢复 git 检查点（confirm 执行） |
/undo |
撤销上次文件变更（预览，confirm 恢复） |
/rewind |
双击 ESC：倒带到过往用户消息 |
/sessions /resume <n> |
列出/恢复已保存会话（恢复侧栏、待办、活动计划） |
/effort [off|low|medium|high|max|auto] |
控制推理深度（无参数弹出选择面板） |
/theme [name|list] |
切换色彩主题 |
/permission [manual|auto|yolo|allow|deny|bash|remove|reset|test] |
权限模式：Manual / Auto / YOLO 三档统一 |
/skill <name> |
加载并立即执行一个 skill |
/skill off <name> |
停止重复注入某个 skill |
/debug [prompt|cache|mcp] |
调试 prompt、缓存统计或 MCP |
/mcp |
MCP 服务器连接状态 |
/memory <text> |
保存会话记忆条目 |
/update |
检查并安装更新（npm） |
/exit /quit |
保存会话并退出 |
双击 ESC 打开倒带覆盖层，按 Esc 关闭任意覆盖层。
Node.js 22 · TypeScript strict（noUncheckedIndexedAccess）· T9 ANSI 渲染引擎 · tsup 打包 · node:test + assert/strict
npx tsc --noEmit # 类型检查
npm test # 所有测试（10,000+ 用例）
npm run build # tsup 打包
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 融合）
会话日志存储在项目外的 ~/.rivet/sessions/<project-slug>/（slug = 目录名 + cwd 哈希前缀），避免被 glob/grep 扫到、也不污染工作区。可用 RIVET_SESSION_DIR 覆盖。全局配置在 ~/.rivet/config.json。每次启动得到唯一会话 ID，多个实例可并行运行互不干扰。
- 路径边界强制 —— glob/grep/diff 拒绝
..穿越；validatePath阻止逃逸 - 符号链接环保护 —— realpath + 访问集
- SSRF 保护 —— 逐跳 DNS + 私有 IP 拦截，作用于每次重定向
- 敏感文件拒绝 ——
.env、credentials.*、*key*、*token*禁止读/commit - 破坏性命令门禁 ——
rm -rf、force push、DROP/TRUNCATE需显式确认 - 检查点 + 回滚 —— 每回合首次修改文件前创建 Git 检查点
- 文件级撤销 —— 每次写/编辑前版本化备份
- Worker 安全 —— AbortController 超时预算，工具白名单强制
| 变量 | 作用 |
|---|---|
DEEPSEEK_API_KEY |
DeepSeek API 密钥 |
RIVET_NO_UPDATE_CHECK=1 |
关闭启动时的自动更新检查 |
RIVET_NO_CROSS_SESSION=1 |
禁用跨会话知识共享 |
RIVET_SESSION_DIR |
覆盖会话日志存储路径 |
RIVET_DEBUG_TELEMETRY |
开启遥测快照落盘（调试用） |
PORTABLE_GIT_MIRROR |
覆盖 PortableGit 下载镜像 |
{
"agent": {
"maxTurns": 200, // 单次会话最大回合数
"approval": "auto-safe", // manual | auto-safe | dangerously-skip-permissions
"crossSessionEnabled": true, // 跨会话知识共享
"checkpointEveryTurns": 0 // Auto 模式检查点间隔（0 = 关）
},
"compact": {
"enabled": true,
"autoThreshold": 800000 // 触发自动压缩的 token 阈值
},
"workers": {
"routing": {
"code_edit": "capable", // 按任务类型路由到不同模型
"repo_summarization": "cheap"
}
}
}完整配置项及默认值见 src/config/default.ts。
| 文档 | 说明 |
|---|---|
docs/user-guide.md |
安装、配置与使用指南 |
docs/user-guide-provider-config.md |
模型提供商配置指南 |
docs/user-guide-sandbox-permissions.md |
沙箱与权限模型完整指南 |
CONTRIBUTING.md |
贡献指南 |
config.example.json |
示例配置（含子代理/审查模型路由） |
- 使用问题 / 讨论 → GitHub Discussions
- Bug 报告 / 功能请求 → GitHub Issues
- 安全漏洞 → 私密报告（不要开公开 issue）
- 贡献代码 → 见 CONTRIBUTING.md
- 求助指南 → 见 SUPPORT.md
提示：需要先由仓库维护者在
Settings → General → Discussions中开启 Discussions 功能。
如果天枢对你有用，欢迎随缘打赏——这只是一杯咖啡，不是合同。赞助不会改变 issue 优先级，也不会影响功能排期。
本项目采用 Apache License, Version 2.0 开源许可。Copyright 2025-2026 Tianshu Contributors.