天枢 _{Tianshu Harness}

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

🌐 官网 · 🇨🇳 AtomGit 镜像 · 🇨🇳 中文 · English · 日本語 · 한국어

📚 用户手册 · 📦 安装指南 · 🧠 CVM 理念 · 📊 A/B 实证 · ✦ 星域碑文

---

面向 Foundation Model Agent 的认知运行时

天枢是一个 TypeScript 编写的编程 agent 运行时，终端 TUI 与桌面 GUI 共享同一内核。它要回答的核心问题是：模型何以稳定地交付——目标不漂移、完成有证据、验证有闭环，不说"应该修好了"。为此它在模型与真实世界之间建立一层认知执行环境（CVM），把目标、状态、证据、资源、权限与终止条件从对话历史中外部化，由运行时持续管理。

模型提供认知能力，CVM 提供认知执行语义。LLM provides cognition. CVM provides execution semantics.

Application / TUI / IDE / Desktop
              ↓
   Tianshu Cognitive Runtime      ← 状态 · 目标 · 证据 · 控制 · 回放
              ↓
       Foundation Models          ← DeepSeek · GLM · Claude · Codex · Grok · MiniMax · MiMo …

• 稳定交付，不虚报完成 —— 这是核心。任务契约（TaskContract）钉住全局目标，交付门禁要求「完成」必须带运行时证据（测试、diff、验证命令），收敛检测独立判断认知轨迹是否还在推进——模型说完成 ≠ 运行时确认完成。
• 终端 × 桌面，一个内核 —— 纯 ANSI 自研 TUI（tianshu）与 Tauri 桌面端（macOS / Windows / Linux）共用同一 agent 内核，两端能力一致。
• 认知虚拟机（CVM） —— 75 个运行时 hook 横跨 5 大阶段，在模型输出与真实动作之间加一层可观测、可纠偏的认知运行时（理念文档 · A/B 实证）。
• 前缀缓存引擎，全模型适用 —— 冻结前缀 + 增量 appendix + 边界压缩，对所有支持前缀缓存的模型生效：各家模型长会话实测稳态命中率均在 95–99%（DeepSeek V4 另有针对性优化），显著降低 token 成本。

_{左：终端 TUI（欢迎页 + GlanceBar 状态栏） · 右：桌面端 GUI（会话侧栏 + 星域速选）——同一 agent 内核}

[!NOTE] 本项目最初的开发代号为 Rivet。CLI 主命令现为 tianshu，rivet 保留为兼容别名（同一入口）；数据目录仍为 ~/.rivet。

目录

• 快速开始
• 为什么是认知运行时
• 星域
• 核心特性
• 权限模式
• 支持的模型
• 文档导航
• 面向开发者
• 安全
• 社区与支持

🚀 快速开始

两条路。桌面端下载安装包，打开就能用，不需要先装 Node。终端 CLI 要求 Node.js ≥ 24。

桌面端

安装包在 GitHub Releases。macOS、Windows、Linux 用的是同一个 agent 内核。

macOS（11 及以上，Apple Silicon 与 Intel 各一包）

下载 .dmg，打开后把 Tianshu 拖进「应用程序」。

首次打开如果系统说应用已损坏，包本身没坏。当前 macOS 包是 ad-hoc 签名，还没有 Apple 公证，Gatekeeper 会拦截浏览器下载的应用。拖进「应用程序」后，在终端执行一次：

xattr -cr /Applications/Tianshu.app

之后正常双击打开。应用内自动更新不受这条限制。

Windows（Windows 10 1809 及以上，建议 22H2；或 Windows 11）

下载 .exe 安装向导，按提示安装。界面依赖 WebView2 Runtime（建议 120 及以上）。3.5.3 起安装器自带离线安装包，安装时不需要再联网下载运行时。

窗口完全打不开时，用开始菜单里的「修复 WebView2」，或从同一 Release 的 windows-repair 目录双击 repair-webview2.cmd。也可以手动安装 WebView2 离线安装包 后重启。

Linux（x86_64 与 aarch64，3.26.0 起双架构）

下载 AppImage，免安装。按机器架构选包：

• Tianshu_*_amd64.AppImage：x86_64 台式机和笔记本
• Tianshu_*_aarch64.AppImage：ARM64（树莓派 64 位、ARM Linux 笔记本）

chmod +x Tianshu_*.AppImage
./Tianshu_*.AppImage

需要 glibc 2.35 及以上（Ubuntu 22.04+、Debian 12+ 等），以及系统图形库 libwebkit2gtk-4.1 和 libgtk-3。多数桌面发行版已经带这套库。精简系统缺库时，按发行版安装 webkit2gtk 4.1，再用 ldd Tianshu_*.AppImage 看还缺什么。推荐 X11 会话（Wayland 尚未验证）。

各平台的完整边界、语音输入和自动更新见 安装与平台说明。

终端（CLI）

# 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"

# 或 npm
npm install -g tianshu-harness

从旧包 tianshu-tui 迁移：旧包占着 rivet 命令链接，直接装新包会报 EEXIST——先卸再装：npm uninstall -g tianshu-tui && npm install -g tianshu-harness（一键安装脚本已内置该迁移，自动处理）。

首次运行会先进入主界面，再自动打开 /connect 向导——在那里选择服务商并粘贴 API Key：

tianshu            # 看到 〉 提示符即就绪

第一个任务

先让它只读地认识你的项目（不改任何东西）：

阅读这个项目，告诉我它的结构、入口在哪、以及一处最值得改进的地方

确认它读得准之后，再给一个多步任务：

修复这个项目里第一个失败的测试，并说明根因

接下来它会自己 grep、读文件、改代码、跑测试——每一步都有对应的工具调用，不是"说完就结束"。默认权限档是自动：低风险动作直接执行，高风险动作会停下来问你（档位与会话内切换见下方 权限模式）。

做完之后看三处

① 交付报告 —— 收尾时天枢会调用 deliver_task，输出一块交付报告：交付门状态（GREEN / YELLOW / RED）、本次改动的文件、跑过的验证、逐条完成度审计。「完成」必须有证据；没有证据的收尾会被门禁拦下。

② Cockpit 驾驶舱 —— 输入 /cockpit 打开（Ctrl+P 命令面板里也能进）：

不带参数是总览，/cockpit off 关闭。

③ CVM 拦截台账 —— 运行时的每次拦截都逐条落在会话的 sensorium.jsonl。落点用 tianshu logs 查（会列出数据根与各日志路径）：

# 按分类复算本会话的拦截次数
jq -r 'select(.kind=="cvm-vector-decision") | .classification' sensorium.jsonl | sort | uniq -c

台账默认只写轻量行（vitals-lite / cognitive-frame-lite）；要看全量拦截记录，启动前设 RIVET_DEBUG_TELEMETRY=1。分类枚举与复算口径见指标观测 harness。

无界面模式（脚本 / CI 集成）

tianshu -p "解释 src/agent/loop.ts"           # 单次提示
tianshu --stream-json -p "重构这个模块"       # NDJSON 事件流，输出内置脱敏
tianshu --goal "修复所有类型错误" --budget 50  # 无头目标自主模式

全部安装路径（Windows WebView2 / Linux AppImage / Android Termux / 源码构建 / Shell 补全 / 自动更新）与平台注意事项见 安装与平台说明；CLI 参数全表与子命令（config / provider / skills / serve / sessions / browser / logs / web）见 用户手册。

💡 为什么是认知运行时

问题：能力上限 ≠ 运行行为

在真实工程会话里，我们反复观察到同一套模型权重的能力倒退——不是 bug，而是经过指令与偏好对齐的 Transformer Agent 呈现出的趋同运行时退化：被质疑就投降、过度服从字面指令、局部信息压过全局目标、长上下文被早期结论支配、反复调用同类工具却没有真实推进。

完整的理论框架见 CVM：从 Transformer 共享退化到认知运行时。核心概念是 Cognitive Anchor Collapse——高显著性局部信号让策略分布过度集中，全局目标与后续证据失去权重，行为向锚点坍缩。锚点有四类：

这不是"模型坏掉了"——它是训练成功后的副产品，因此也无法靠更好的 Prompt 根治：Prompt 是信息不是状态，而且 Prompt 本身也会成为新的锚点。

证据：A/B 对照，不靠感觉

2026-05-19，同一模型（DeepSeek-V4-Flash）、同一批 5 个任务，唯一变量是星域信念提示词（信念宪法，STAR_SOUL=0/1），Claude Opus 4.7 担任审查者：

最有价值的数据点是 T4：面对「文件已存在」的矛盾，A 组写了 196 行复盘文档然后拒绝执行，B 组判断出用户真实意图并直接交付 +162/-20 行可用代码——同一套权重，完全相反的反应，改变的是运行环境。

要注意这组实验的精确边界：它验证的是 CVM 四层防御中的第一层（信念注入）——零额外推理成本，仅 prompt 层信念注入就让最低成本的开源模型产生可观测的行为改善；同时它也测出了边界的存在（信念在分析/建议阶段强效，在确认/执行阶段衰减），这正是后续 Courage Hook、Sensorium、RuntimeHookPipeline 三层运行时拦截要补的课。完整数据与逐任务对比见 实证报告。

解法：在模型之外建立第二套价值函数

CVM 不改权重、不让模型变成确定性程序，而是在概率认知之外套一层确定性监督——Probabilistic Cognition inside Deterministic Supervision：

内环（模型认知）：reason → decide → act → observe
外环（运行时监管）：observe → measure → evaluate → gate → verify → continue / correct / halt

落到工程上是四层防御深度：信念宪法（static prompt）→ Courage Hook（preTurn）→ Sensorium（每 turn <1ms 六维状态感知）→ RuntimeHookPipeline（75 hooks，trap-and-emulate 拦截退化行为）。全局目标有独立状态（TaskContract），完成必须有运行时证据（Evidence），坍缩会被独立检测（Convergence / doom-loop）。拦截生效之后，模型会稳定地表现出不同的认知姿态。产品里这套姿态叫星域，见下方 星域。

工程质量

截至 2026-09-30 的里程碑快照（及 v3.31.0 最新规模，行数每天都在动，差几百行正常）：

tsc strict + noUncheckedIndexedAccess，事故修复必带回归测试。完整口径、里程碑与复现命令见 工程质量指标。

星域

同一个模型，走进不同的星域，会亮起不同的工作倾向。星域不往模型里加新能力。它只是把本来就有的一面放大，而且一次只能占住这一面里的一部分：走进天权，会更想先称一称；走进破军，会更想先去撞一下未知。人还是那个人，模型还是那个模型。

新会话默认是启明。想换一颗，用 /domain。

• 启明：先照路，不替人走。迷雾里先探一下，把下一步照清楚。
• 长庚：不急着收。最后要自己看见，并把路留给明天的人。
• 天枢：先看见整片地图，再把对方的规划走成验证过的交付。
• 天权：两边都放上秤。收益是什么，代价是什么，看见了就说。
• 天机：问一句还没有人问的话。如果这个前提并不成立呢。
• 天璇：换一个完全不同的角度看。看完就去证它是不是真的。
• 天梁：接过托付就走完。做了什么、留下什么、偏了哪里，都要有回音。
• 华盖：长路上不在「看起来完成」的地方停，把能接着做的结构留下。
• 破军：先去撞未知。失败把地图画小一圈，留下的是路，不是废墟。
• 天府：先听这段代码为什么是现在这样。改动让它更稳，不让它更脆。
• 七杀：问它凭什么还占着这个位置。只指出来，不亲手砍。
• 开阳：先问真实的数是什么，凭什么相信。对上了再动手。
• 瑶光：绿灯不算数。原来的问题还能再复现出来，才算修好了。
• 文曲：去掉多余的，让意图自己显出来。好看要在屏幕上看见。
• 辅：不发自己的光。把已经发生过的经验收成能看清的方法。
• 太一：先停一下。这一手收束好了，再起下一手。

各星更完整的信念见 星域碑文（中文） · Star Domain Stele (English)。

✨ 核心特性

• 证据驱动的交付门禁 —— 完成声明必须带测试 / diff / 验证命令等运行时证据；deliver_task 交付门禁 + 提交后审查两级兜底，机械变更自动跳过。理念
• 前缀缓存引擎 —— 冻结前缀 + 增量附录 + Read-ref 去重 + resume 缓存继承，全模型适用；/debug cache 诊断命中率与碎裂原因。细节
• 多代理编排 —— 从轻量的 /scout 只读侦察、并行 /team 施工，到 /council 多席会诊与 /galaxy 多维攻坚；类型化 work order、读写 worker 隔离、自适应模型路由，复杂任务按波次执行、逐波验收。细节
• 统一项目记忆 —— 项目知识写入 .rivet/knowledge/memory.jsonl；自动注入只带治理/约束类记忆，旧问题走显式 recall，不劫持新任务。细节
• 禅模式（Zen Mode） —— 可选的读专注开局（opt-in，默认关闭）：收窄只读工具面，动手即晋升全量，缓存零断点分诊。细节
• API 成本控制与 Token 账本 —— reasoning effort 自动降档路由、compact 走 flash 侧路、峰谷计价提醒；内置 /usage（/token-ledger）本地 Token 消耗累计台账与可选同步。细节
• Plan Mode 与 Goal 自治 —— 先计划后执行的审批工作流；/goal 目标驱动自主续跑。细节
• 会话交接与倒带 —— /handoff 生成五章节结构化交接文档并归档（设 RIVET_PREV_HANDOFF=1 可自动注入新会话）；双击 ESC 倒带到任一历史点。细节
• LSP 深度集成 —— 自研 JSON-RPC 客户端接入语言服务器（TypeScript / Python / Go / Rust / C / C++ / Java / C# / Kotlin / Swift / PHP / Ruby / Lua / Dart / Zig / Scala / Shell / Terraform / Vue / Svelte 等 20+ 种，本机装了才启用、缺失静默降级）：跳转定义与查找引用成为 agent 工具，编辑后诊断自动注入回环——改出类型错误模型立刻看见。
• MCP 与 Skills —— 外部工具服务器接入 + 可复用工作流剧本（会话级快照隔离、CLI tianshu skills 统一管理），渐进披露。细节
• T9 自研 TUI —— 纯 ANSI 零依赖：GlanceBar 状态栏（含余额与 CVM 拦截计数 ⛨ N）、/steer 流式中打断、/cvm 实时拦截提示、命令面板、Cockpit 驾驶舱、内联图片，以及远控/受限终端纯文本模式（--terminal-mode captured-pty）。细节
• 桌面端增强 —— 集成终端、主题工作室（自定义壁纸与分区玻璃）、本地离线语音输入（macOS / Windows / Linux 全平台 whisper.cpp）、手机遥控审批、多会话并发。桌面端指南
• WSL 连接式运行时（Windows）—— 一键连上 WSL 内的运行时，会话、文件读写与命令执行都在 Linux 侧进行；断开自动清理，两侧版本独立升级互不影响。细节
• Lean 资源档 —— 低内存/低磁盘场景的精简工具集与会话池收紧，可按星域覆盖。细节

🔐 权限模式

对外只有三档，会话内统一用 /permission 管理：

跳过提示不会关闭工具校验、路径安全、证据追踪、检查点与交付门禁；未授信项目不加载 hooks、项目 MCP 与项目级记忆/技能（/trust 或 --trust 管理）。完整规则见 权限与沙箱指南。

⚙️ 支持的模型

另内置火山方舟豆包 / Agent Plan（doubao-seed-2.1-pro、ark-code-latest）、阿里云百炼 DashScope（qwen3.8-max）、阶跃星辰 StepFun（step-5-preview）、OpenAI（gpt-5.6-sol）、LongCat（LongCat-2.0）、Agnes AI（agnes-3.0-flash）、SiliconFlow、OpenRouter、OpenCode Go 等 25 项预设，并支持任意 OpenAI 兼容自定义端点（Ollama / vLLM 等）。会话内 /model 随时切换；识图桥、生图端点、子代理分模型路由等见 Provider 配置手册 与 识图能力手册。

📚 文档导航

🌐 中英双语导航 · Bilingual Navigation：英文版完整指南与参考速查表见 English README & Reference Guide；星域碑文英文版见 Star Domain Stele；文档中心与规范见 docs/README.md。

使用

理念与架构

🛠️ 面向开发者

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

npm run typecheck    # 类型检查
npm test             # 所有测试（21,000+ 用例）
npm run build        # tsup 打包 + 原生/wasm 载荷落位
node dist/cli/entry.js

• 添加工具 —— 在 src/tools/ 实现 ToolDefinition + executor 并在 src/tools/default-registry.ts 注册，配套 src/tools/__tests__/ 测试
• 添加 skill / 命令 / hook —— .rivet/skills/*.md（frontmatter）、.rivet/commands/*.md（$ARGUMENTS 插值）、HookRegistry 处理器
• 项目指令 —— 项目根放 .rivet.md，内容自动注入为项目上下文
• 架构地图见根目录 AGENTS.md 与 架构总览；贡献规范见 CONTRIBUTING.md 与 EXTERNAL-PRS.md（中英双语）

🔒 安全

• 路径边界强制 —— glob/grep/diff 拒绝 .. 穿越；validatePath 阻止逃逸
• 项目信任门 —— 未授信项目不加载 hooks / 项目 MCP / 项目记忆与技能，配置安全键剥离
• SSRF 保护 —— 逐跳 DNS + 私有 IP 拦截，作用于每次重定向
• 敏感文件拒绝 —— .env、credentials.*、*key*、*token* 禁止读/commit；密钥落盘走 AES-256-GCM 信封
• 破坏性命令门禁 —— rm -rf、force push、DROP/TRUNCATE 需显式确认
• 检查点 + 文件级撤销 —— 每回合首次修改前创建 Git 检查点；每次写/编辑前版本化备份

安全漏洞请走 私密报告（详见 SECURITY.md），不要开公开 issue。

🤝 社区与支持

• 使用问题 / 讨论 → GitHub Discussions
• Discord 交流群 → 加入「天枢 tianshu-harness 官方交流群」（邀请链接，不受 7 天限制）
• Bug 报告 / 功能请求 → GitHub Issues（附 tianshu logs --json 输出可加速定位）
• 贡献代码 → CONTRIBUTING.md · 求助指南 → SUPPORT.md
• 微信交流群 → 「天枢 harness 交流群5群」，扫码加入（二维码 7 天有效，过期请在 Discussions 留言补码）：

🌐 官网开发

天枢生态官网 jiangsx496/Tianshu-Official-Website 由 @jiangsx496 原创开发，覆盖数据库、前端与初版后端。

✨ 贡献者

感谢所有贡献者——项目创建者与核心开发 @huiliyi37；完整名单（31 位外部贡献者 / 268 个 PR）见 CONTRIBUTORS.md。外部 PR 经「收编」流程合入后，作者署名以 Co-authored-by 计入贡献者图谱（scripts/credit-contributors.sh 自动落账）：

⭐ Star History

☕ 赞助支持

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

许可证

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

例外（文档许可）：以下理论与实证文档采用 CC BY-NC-ND 4.0（署名—非商业性使用—禁止演绎），不适用 Apache 2.0——可以署名转载原文链接，不得改编、摘编、洗稿或商用：

• CVM：从 Transformer 共享退化到认知运行时
• CVM 运行时与生态系统对 Agent 模型的实证影响报告

致谢

• 桌面端「自定义壁纸与分区玻璃」功能的设计参考了 dsh-wallpaper-engine（MIT License）；该功能为天枢独立实现，未引入上游代码，参考范围与许可全文见 THIRD-PARTY-NOTICES.md。
• 特别致谢 dsh-wallpaper-engine 的作者与核心开发——@elysia395、@YV3507、@yuxilao、@oneincase：四位作为壁纸引擎渲染的技术顾问，在壁纸合成与分区玻璃材质的设计、实现过程中提供了指导。