模型的能力上限不等于它的运行行为。同一套权重放进真实工程会话，会被质疑就让步、只照字面执行、让局部信息压过全局目标，或者反复调用工具却没有推进，最后留下一句「应该修好了」。
天枢是一个 TypeScript 编写的编程 agent 运行时，终端 TUI、桌面端和 VS Code 插件共用同一个内核。它在模型和真实世界之间加了一层认知执行环境 CVM（Cognitive Virtual Machine），把目标、状态、证据、权限和终止条件从对话历史里拿出来，交给运行时持续管理：
- 任务契约：每个任务有独立的
TaskContract，记录目标、范围、约束和成功标准。长会话里的目标由运行时持有，不依赖模型「记得」。
- 提交、验证、审查分离的交付：
deliver_task 只做归属限定的安全提交——所有权、跨会话冲突、版本一致性不合格就拦下；验证缺口如实披露但不阻断、也不冒充质量背书。定向验证用 run_tests（显式范围），独立审查用 review_changes 或 /review。
- 确定性监督外环：75 个运行时 hook 模块分布在一个回合的五个阶段，配合 Sensorium 状态感知与收敛、空转检测，在模型输出与真实动作之间做观测和纠偏。
[!NOTE]
开发代号是 Rivet。CLI 主命令是 tianshu，rivet 是同一入口的兼容别名；数据目录仍为 ~/.rivet。
目录
安装
终端 CLI（Node.js 24.x ≥ 24.22.1 或 26.x ≥ 26.12.1）
npm install -g tianshu-harness
tianshu
看到 〉 提示符即就绪。首次启动会自动打开 /connect 向导，选服务商、粘贴 API Key。
桌面端（无需 Node）
从 Releases 下载：
- macOS 11+：
.dmg，Apple Silicon / Intel
- Windows 10 1809+ / 11：
-setup.exe
- Linux x86_64 / aarch64：
.AppImage
[!WARNING]
Node.js 版本硬门槛（v3.36.0 起）：CLI 仅支持 Node 24.22.1+（24.x 线）或 26.12.1+（26.x 线）。
Node 22 / 23 / 25 / 27、24.x < 24.22.1、26.x < 26.12.1 会在启动时被安全闸门拒绝；
/update 可能已经装上新包，但新 CLI 仍无法启动。先运行 node -v，不满足时用
nvm / fnm / Volta 或 nodejs.org 升级后再安装。
node -v # 需要 v24.22.1+ 或 v26.12.1+
桌面端自带运行时，不需要手动安装 Node。升级后仍失败时见
安装指南 与 排障指南。
# macOS / Linux
bash <(curl -fsSL https://raw.githubusercontent.com/huiliyi37/Tianshu-harness/main/scripts/install-tui.sh)
# Windows（PowerShell）
powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/huiliyi37/Tianshu-harness/main/scripts/install-tui.ps1 | iex"
从旧包 tianshu-tui 迁移时会因 rivet 命令链接冲突报 EEXIST，先执行 npm uninstall -g tianshu-tui。一键安装脚本会自动处理。
- macOS：暂未 Apple 公证。首次打开提示「已损坏」时，拖进「应用程序」后执行一次
xattr -cr /Applications/Tianshu.app。应用内自动更新不受影响。
- Windows：界面依赖 WebView2，安装器自带离线包。窗口打不开时用开始菜单里的「修复 WebView2」，或运行 Release 中
windows-repair 目录下的 repair-webview2.cmd。
- Linux：需要 glibc 2.35+（Ubuntu 22.04+、Debian 12+），以及
libwebkit2gtk-4.1 与 libgtk-3。推荐 X11 会话，Wayland 尚未验证。chmod +x Tianshu_*.AppImage 后直接运行。
Android Termux、源码构建、Shell 补全和自动更新见 安装指南。
第一个任务
先让它只读地认识你的项目，确认读得准，再给一个多步任务：
〉 阅读这个项目，告诉我它的结构、入口在哪、以及一处最值得改进的地方
〉 修复这个项目里第一个失败的测试，并说明根因
它会自己搜索、读文件、改代码、跑测试。默认权限档是自动：低风险动作直接执行，高风险动作停下来问你。做完之后看三处：
| 看哪里 | 看什么 |
|---|
| 交付报告 | 交付门状态（GREEN / YELLOW / RED）、改动的文件、跑过的验证、逐条完成度审计 |
/cockpit 驾驶舱 | 8 面板运行时仪表：验证与交付、提醒台账、缓存命中与成本、风险与空转（F4） |
sensorium.jsonl | 每个回合的状态感知与 CVM 判定记录。tianshu logs 列出路径，可用 jq 复算 |
tianshu -p "解释 src/agent/loop.ts" # 单次提示
tianshu --stream-json -p "重构这个模块" # NDJSON 事件流，输出内置脱敏
tianshu --goal "修复所有类型错误" --budget 50 # 目标驱动的自主续跑
参数全表和子命令见 用户手册。
CVM 是怎么工作的
经过指令与偏好对齐的模型，在 agent 场景下会呈现相似的运行时退化，我们称之为 Cognitive Anchor Collapse：一个高显著性的局部信号让策略过度集中，全局目标和后续证据失去权重，行为向这个锚点坍缩。Prompt 是信息，不是状态，它本身也会变成新的锚点，所以这类问题靠写更好的提示词治不了。
CVM 不改权重，也不把模型变成确定性程序，而是在概率认知外面加一层确定性监督。模型在内环里推理和行动，运行时在外环里度量、把关、验证，决定继续、纠偏还是停下：
内环 · 模型认知 reason → decide → act → observe
外环 · 运行时监督 observe → measure → evaluate → gate → verify → continue / correct / halt
| 层 | 机制 | 作用 |
|---|
| 1 · 信念宪法 | 星域信念块，写入静态提示词 | 零额外推理成本，在分析和建议阶段改变倾向 |
| 2 · Courage Hook | preTurn 阶段，阈值随星域变化 | 检测到连续让步时，注入带义务语义的纠偏指令 |
| 3 · Sensorium | 每回合由已有监控信号计算，不调用 LLM | 感知动量、压力、验证覆盖、复杂度、熟悉度、稳定性六个维度 |
| 4 · RuntimeHookPipeline | 75 个 hook 模块，五个阶段，按会话条件装配 | 收敛与 doom-loop 检测、证据追踪、交付门、编辑失败恢复等 |
| 锚点 | 来源 | 典型表现 |
|---|
| 词汇锚点 | 训练数据里的词与行为相关性 | 句子里有「修复」，就无视「不要改，只解释」去改代码 |
| 语义锚点 | 局部正确的事实 | 「文件已存在」被当成整个任务的解释中心，拒绝执行 |
| 策略锚点 | RLHF / 偏好训练先验 | 一句「按你的计划执行」，分析阶段的高质量判断就被丢弃 |
| 历史锚点 | 长上下文里的早期结论 | 第 20 轮的新证据被解释成第 3 轮旧假设的附属 |
八条设计原则和开放的研究问题见 CVM：从 Transformer 共享退化到认知运行时，系统分层见 架构总览。
实证
缓存：上下文越长，命中越稳
天枢以前缀缓存优先设计：会话内冻结前缀，只追加增量，压缩只发生在用户回合边界。上图是一个 4.2 小时的真实会话，15 次前缀重建总共只产生 383K cacheCreate，占全部 input 的 0.33%。
| 5 个真实自举会话（2026-08，DeepSeek V4） | 数值 |
|---|
| 请求数 / input tokens | 2,001 次 / 6.45 亿 |
| 整体缓存命中率 | 99.3–99.6% |
| 估算成本（刊例价） | 无缓存 ¥879.97 → 实际 ¥19.96，节省 97.7% |
缓存引擎对所有支持前缀缓存的模型生效，目前公开的实测只覆盖 DeepSeek。每个数字都附 jq 复算命令，见 指标观测 harness。
行为：同一套权重，相反的反应
最典型的是 T4。面对「文件已存在」的矛盾，A 组写了 196 行复盘文档后拒绝执行，B 组判断出用户的真实意图，交付了 +162 / −20 行可用代码。
这是一个小样本试点：5 个任务、单一模型、LLM 审查。它也测出了衰减，信念在分析和建议阶段有效，到确认和执行阶段明显减弱，这正是第 3、4 层运行时监督要补的部分。完整数据见 实证报告。
工程
截至 2026-10（v3.37）：src/ 约 1,700 个源码文件、35 万行，测试约 2,100 个文件、2.3 万条用例。TypeScript strict，开启 noUncheckedIndexedAccess，事故修复必须附回归测试。口径与里程碑见 工程质量指标。
星域
同一个模型，走进不同的星域，会亮起不同的工作倾向。星域不给模型加新能力，也不限制工具。它把模型本来就有的一面放大，对应 CVM 的第 1、2 层：每个星域有自己的信念块和勇气阈值。人还是那个人，模型还是那个模型。
新会话默认是启明，用 /domain <名字> 切换，/domain auto 按消息内容自动匹配，/domain list 列出全部。每颗星的完整信念与创始记忆见 星域碑文（English）。
更多能力
| |
|---|
| 多代理编排 | /scout 只读并行侦察，/team 按文件分波并行施工，/council 多星域会诊只出计划，/galaxy 按维度拆分并做全局审查。详情 |
| 审查与验证分离 | 提交不自动验证也不自动派审查：定向验证 run_tests（空参数只给范围预览），独立审查 review_changes（固定快照、只读 reviewer、发现持久化），交付回执不作质量背书 |
| 前缀缓存引擎 | 冻结前缀、增量附录、Read 去重、resume 缓存继承，/debug cache 诊断命中率与碎裂原因。详情 |
| Plan Mode 与 Goal | 先计划、审批、再执行；/goal 设定跨多轮目标，持续迭代到达成或预算耗尽。详情 |
| 交接与倒带 | /handoff 生成结构化交接文档；双击 Esc 倒带到任一历史点。详情 |
| 项目记忆 | 知识写入 .rivet/knowledge/memory.jsonl；自动注入只带约束类记忆，旧问题显式 recall，不劫持新任务；自动记忆形成为 opt-in（默认关闭）。详情 |
| LSP 集成 | 20+ 种语言服务器，跳转定义与查找引用作为 agent 工具，编辑后的诊断自动回注。本机装了才启用 |
| MCP 与 Skills | 接入外部工具服务器；可复用的工作流剧本，渐进披露，tianshu skills 统一管理。详情 |
| 成本控制 | 推理强度自动降档、压缩走轻量模型、峰谷计价提醒，/usage 查看本地 Token 账本。详情 |
支持的模型
内置 25 项服务商预设，会话内 /model 随时切换，也支持任意 OpenAI 兼容端点（Ollama、vLLM、one-api 中转等）。
多数服务商用 API Key 接入。Codex 走 ChatGPT 订阅 OAuth，Claude 经 cc-switch 代理，Gemini 走原生协议。具体模型 ID、上下文长度、识图与生图、子代理分模型路由见 Provider 配置手册 和 识图能力手册。
权限与安全
会话内用 /permission 管理，只有三档：
| 档位 | 命令 | 行为 |
|---|
| 监督 | /permission supervise | 每个高风险工具都弹确认 |
| 自动（默认） | /permission auto | 低风险直接执行，高风险确认 |
| 全自动 | /yes · /yolo | 免审批，但自动开启沙箱写边界，可回滚 |
跳过确认不会关闭底层防护：
| |
|---|
| 路径边界 | 拒绝 .. 穿越，validatePath 阻止逃逸出工作区 |
| 项目信任门 | 未授信项目不加载 hooks、项目 MCP、项目记忆与技能，用 /trust 管理 |
| 敏感文件 | .env、credentials.* 等禁止读取和提交，落盘密钥使用 AES-256-GCM 信封 |
| 破坏性命令 | rm -rf、force push、DROP / TRUNCATE 需要显式确认 |
| SSRF 防护 | 逐跳 DNS 解析，拦截私有 IP，作用于每一次重定向 |
| 检查点与撤销 | 每回合首次修改前创建 Git 检查点，每次写入前版本化备份 |
完整规则见 权限与沙箱指南。安全漏洞请走 私密报告，不要开公开 issue，详见 SECURITY.md。
文档
使用
理念与架构
英文版完整指南与参考速查见 README.en.md，文档中心见 docs/README.md。
参与开发
npm install
npm run typecheck # tsc --noEmit
npm test # node:test，全部用例
npm run build # tsup 打包
node dist/cli/entry.js
| 想做什么 | 从哪里开始 |
|---|
| 添加工具 | 在 src/tools/ 实现 ToolDefinition 和 executor，到 src/tools/default-registry.ts 注册，测试放 src/tools/__tests__/ |
| 添加 skill / 命令 / hook | .rivet/skills/*.md、.rivet/commands/*.md（支持 $ARGUMENTS）、HookRegistry 处理器 |
| 项目指令 | 项目根目录的 .rivet.md 会自动注入为项目上下文 |
本仓是开发主仓的同步投影，桌面端与部分高级实现不在本仓。架构地图见 AGENTS.md，贡献流程见 CONTRIBUTING.md 和 EXTERNAL-PRS.md。
社区
赞助随缘，不会改变 issue 优先级或功能排期。
贡献者
项目创建者与核心开发是 @huiliyi37。天枢官网 Tianshu-Official-Website 由 @jiangsx496 原创开发。外部 PR 经收编流程合入后以 Co-authored-by 署名，完整名单见 CONTRIBUTORS.md。
许可证
代码采用 Apache License 2.0。Copyright 2025-2026 Tianshu Contributors.
以下两篇理论与实证文档例外，采用 CC BY-NC-ND 4.0：可以署名转载原文链接，不得改编、摘编或商用。
致谢
桌面端「自定义壁纸与分区玻璃」的设计参考了 dsh-wallpaper-engine（MIT），功能为天枢独立实现，未引入上游代码，详见 THIRD-PARTY-NOTICES.md。感谢 @elysia395、@YV3507、@yuxilao、@oneincase 作为壁纸引擎渲染的技术顾问提供的指导。
