![\"Tura](\"assets/tura/icon.svg\"){kind=icon}
\n \n\n \n \n \n
\n ![\"Website\"](\"https://img.shields.io/badge/Website-turaai.net-40e0d0?style=flat-square&labelColor=555555\" "\\"Tura"){kind=icon}
![\"Benchmark:](\"https://img.shields.io/badge/Benchmark-348_sessions-9b59b6?style=flat-square&labelColor=555555\" "\\"Tura"){kind=icon}
![\"npm](\"https://img.shields.io/npm/v/tura-ai?style=flat-square&logo=npm&label=npm&labelColor=555555&color=cb3837\" "\\"Tura")
English | 简体中文
\n\n![\"High-to-High](\"assets/data/benchmark-agent-comparison.svg\")
\n\n ![\"Tura](\"assets/screenshot/gui-ci-quality-demo.svg\")
\n
GUI 页面，支持多会话并发工作和 HTML 富文本渲染。
\n\n\n ![\"Tura](\"assets/screenshot/tui-ci-quality-demo.svg\")
\n
TUI 页面，支持多会话并发工作和 HTML 富文本渲染。
\n\n以下结果来自已发布的基准测试工件，而非未经引用的聚合数据。三项核心系统承担了大部分工作：\n\n## 宏 CLI 命令运行\n\n大多数编程助手仍然依赖重复的工具调用循环：检查、等待、打补丁、等待、构建、等待、测试、等待。\n\n_**传统工具调用型编程助手：**_\n\n```bash\n# 第 1 轮 — 检查环境\n\nrg -n \"TODO|command_run|handler\" crates/\nrg --files crates/runtime/src crates/tools/src\n```\n\n```bash\n# 第 2 轮 — 应用补丁\n\n*** Begin Patch\n*** Update File: crates/tools/src/command_run/handler.rs\n@@\n- // old command handler logic\n+ // patched command handler logic\n*** End Patch\n```\n\n```bash\n# 第 3 轮 — 构建\n\ncargo build -p runtime\n```\n\n```bash\n# 第 4 轮 — 运行测试\n\ncargo test -p runtime --lib\n```\n\n```bash\n# 第 5 轮 — 运行 lint 验证\n\ncargo clippy -p runtime --all-targets\n```\n\nTura 走了一条不同的路。它不是向模型暴露几十个小工具，而是暴露一个宏工具：`command_run`。这样，代理可以构建一个多步执行树，在一轮 LLM 调用中完成相关操作。\n\n在下面的例子中，两个代理运行相同的命令。传统工具调用型代理需要五轮 LLM 交互；Tura 将整个序列作为一个结构化的宏工作流处理。节省的是对话开销，而非工程纪律。\n\n_**Tura 宏 CLI 命令：**_\n\n```json\n{\n \"name\": \"command_run\",\n \"arguments\": {\n \"commands\": [\n {\n \"step\": 1,\n \"command_type\": \"shell_command\",\n \"command_line\": \"rg -n \\\"TODO|command_run|handler\\\" crates/\"\n },\n {\n \"step\": 1,\n \"command_type\": \"shell_command\",\n \"command_line\": \"rg --files crates/runtime/src crates/tools/src\"\n },\n {\n \"step\": 2,\n \"command_type\": \"apply_patch\",\n \"command_line\": \"*** Begin Patch\\n*** Update File: crates/tools/src/command_run/handler.rs\\n@@\\n- // old command handler logic\\n+ // patched command handler logic\\n*** End Patch\"\n },\n {\n \"step\": 3,\n \"command_type\": \"shell_command\",\n \"command_line\": \"cargo build -p runtime\"\n },\n {\n \"step\": 4,\n \"command_type\": \"shell_command\",\n \"command_line\": \"cargo test -p runtime --lib\"\n },\n {\n \"step\": 4,\n \"command_type\": \"shell_command\",\n \"command_line\": \"cargo clippy -p runtime --all-targets\"\n }\n ]\n }\n}\n```\n\n目前没有消融实验证明仅凭 `command_run` 就能带来 Tura 更低的轮次和 token 用量。但在匹配 High 配置的 DeepSWE 对比中，Balanced 比 Codex CLI High 少用了 66.8% 的模型轮次和 49.6% 的 token，而 Direct 则少用了 84.0% 的轮次和 83.5% 的 token。[^test-set-record][^debug-manifests]\n\n## 反向推理\n\n无论 LLM 多么令人印象深刻，其核心仍然是一个基于文本 token 概率的统计归纳模型。\n\n例如，让 LLM 在石头、剪刀、布中做选择并不能保证均匀随机的结果。如果真正三分之一的分布很重要，则需要外部随机数源，而不是对模型输出概率的未经引证的假设。\n\n在编程任务中，这往往是致命的。\n\n代理更倾向于执行和生成统计上更常见的代码和逻辑。但常见的代码和逻辑往往平庸且欠考虑。\n\nTura 采用了一种不同的策略。\n\n在推理过程中，普通代理从当前状态推理到提示目标。即，$s_1$ 是当前状态，$s_n$ 是用户提示给出的目标。\n\n$$\ns_1 \\rightarrow s_2 \\rightarrow s_3 \\rightarrow \\cdots \\rightarrow s_n\n$$\n\n相反，Tura 引导 LLM 先统计估计 $s_{n-1}$，然后从 $s_{n-1}$ 的状态反向推理到 $s_{n-2}$。\n\n在下面的例子中，LLM 能够正确推导出玩石头-剪刀-布的最优策略。\n\n```\n> 为了让石头-剪刀-布公平且具有挑战性，\n> 我们需要无偏的游戏。\n> 每一步必须拥有真正的三分之一概率。\n> LLM 仅凭文本概率无法保证这一点。\n> 使用随机数生成器脚本生成 randint(1, 3)\n> 然后将石头、剪刀、布映射到数字。\n```\n\n在编程任务中，这意味着当代理看到一个目标（如修复前端 bug）时，它被引导去推理完整的执行路径，重构失败状态，并在编写代码之前识别根本原因。在匹配 High 配置的 DeepSWE 对比中，Tura Balanced 比 Codex CLI High 多通过了 60 个二元任务验证器中的 12 个。\n\n该对比中的两种配置都使用 GPT-5.6 SOL 和 High 推理标签，因此 High 与 Medium 的推理强度差异无法解释这 20 个百分点的通过率差异。该结果仍然是一个系统层面的关联，而不是对反向推理或任何其他个体特征的因果估计。[^test-set-record][^debug-manifests]\n\n## 运行时上下文与提示管理器\n\n所谓技能，往往只是加载到上下文中的较弱提示。\n\n在许多代理框架中，长期运行的会话会不断累积技能文件、工具输出和陈旧的任务历史。当上下文变得过大时，代理会进入一个单独的压缩轮次，但这种压缩通常只保留一个压缩摘要。重要的执行细节可能会变得模糊或丢失。\n\nTura 将上下文视为运行时状态机的一部分。\n\nTura 不依赖用户手动重置会话或让 Markdown 技能堆积，而是使用 `task_status`、运行时提示和递归执行手册将活动上下文限定在当前任务范围内。\n\n传统基于技能的代理通常保持一个会话运行直到用户启动另一个会话，将宽泛的 Markdown 技能加载到该会话中，并使其保持激活直到重置或压缩。Tura 则将运行时提示绑定到显式的任务状态：会话可以被重命名、刷新和自动管理；任务特定的手册和 CLI 命令通过递归任务树加载；不相关的上下文可以被移除、替换或通过 CLI 压缩。检查点可以保留代码位置、补丁、测试和任务状态，而不仅仅是松散摘要。在实践中，这意味着更少的过期上下文、更低的任务范围 token 成本，以及更少的旧技能或模糊摘要误导当前工作的机会。\n\n由于压缩是一个 CLI 操作，Tura 可以在 `task_status.compact_context` 中保留精确的执行状态。在已发布的基准测试会话中，Tura 超越了只读检查，在压缩后平均恢复了 2.6 轮执行，而 Codex 估计需要 5.4 轮。[^compact-dynamodb][^compact-wasmi-r1][^compact-wasmi-r2][^compact-wasmi-r3][^compact-eza]\n\nTura 的 2.6 轮结果是根据其存档的轮次合约中的显式 `compact_context` 事件计算的。Codex 不暴露等效的压缩事件，因此其 5.4 轮结果是通过输入 token 用量急剧下降的点（排除可识别的媒体读取边界）估算得出的。\n\n## 安装与运行\n\n### NPM 发布版\n\nMac 和 Linux：\n\n```bash\nnpm install tura-ai\ntura\n```\n\nWindows：\n\n```powershell\nnpm install -g tura-ai\ntura\n```\n\n相同的主包也发布到 GitHub Packages 作为 `@tura-ai/tura`。为 `https://npm.pkg.github.com` 配置 `@tura-ai` 范围，使用具有 `read:packages` 权限的 token 进行身份验证，然后安装 `@tura-ai/tura`。npm 上的无范围 `tura-ai` 包仍然是最简单的公开安装方式。\n\nTura 不捆绑提供者凭证。首次启动时，在发送提示前配置一个 LLM 提供者并选择其模型。详见[提供者设置](docs/start/providers.md#first-run-configure-an-llm-provider)中的 CLI、TUI 和 GUI 流程。\n\n### 源码安装\n\nWindows PowerShell：\n\n```powershell\ngit clone https://github.com/Tura-AI/tura.git\ncd tura\n.\\scripts\\install.ps1\ntura\n```\n\nmacOS 或 Linux shell：\n\n```bash\ngit clone https://github.com/Tura-AI/tura.git\ncd tura\n./scripts/install.sh\ntura\n```\n\n源码安装程序会执行完整的环境设置、发布构建和用户 PATH 注册流程。当你只想安装依赖而不构建或注册 Tura 时，在 PowerShell 上传 `-EnvironmentOnly` 或在 macOS/Linux 上传 `--environment-only`。\n\n### 常用入口点\n\n| 入口 | 用途 |\n| ----------------------------------- | ---------------------------------------------------- |\n| `tura` | 交互式终端 UI。 |\n| `tura \"提示\"` | 使用初始提示打开 TUI。 |\n| `tura exec \"提示\"` | 直接 Rust CLI 提示运行器。 |\n| `tura run \"提示\"` | 支持流式传输/历史的网关提示。 |\n| `tura bash`、`tura zsh`、`tura shel` | 使用选定命令运行 shell 界面的提示。 |\n| `tura_gateway` | 本地 HTTP/SSE 网关及可选的 Web GUI 服务。 |\n| `tura_gui` | 桌面 GUI 工作区客户端。 |\n\n有关操作系统特定的 PATH 要求、执行器安装以及如何在可执行文件不在 PATH 上时注册 CLI，请阅读[如何开始](docs/start/how-to-start.md)。有关命令标志和模式，请阅读[CLI 参数](docs/start/cli-parameters.md)。\n\n## 文档\n\nGitBook 风格的文档索引位于 [docs/SUMMARY.md](docs/SUMMARY.md)。完整导航页面位于 [docs/start/navigation.md](docs/start/navigation.md)。\n\n### 开始\n\n- [概览](docs/start/overview.md)\n- [安装](docs/start/install.md)\n- [如何开始](docs/start/how-to-start.md)\n- [CLI 参数](docs/start/cli-parameters.md)\n- [设置](docs/start/settings.md)\n- [提供者](docs/start/providers.md)\n- [会话](docs/start/sessions.md)\n- [导航](docs/start/navigation.md)\n\n### 核心\n\n- [任务状态](docs/core/task-status.md)\n- [上下文管理](docs/core/context-management.md)\n- [运行时提示](docs/core/runtime-prompt.md)\n- [命令运行](docs/core/command-run.md)\n- [命令](docs/core/commands.md)\n- [代理](docs/core/agents.md)\n- [人格](docs/core/personas.md)\n- [富文本](docs/core/html-rich-text.md)\n- [动态提示注入](docs/core/prompt-style.md)\n\n### 架构\n\n- [Session DB](crates/session_log/ARCHITECTURE.md)\n- [Gateway](crates/gateway/ARCHITECTURE.md)\n- [Router](crates/router/ARCHITECTURE.md)\n- [Runtime](crates/runtime/ARCHITECTURE.md)\n- [Tool](crates/tools/ARCHITECTURE.md)\n- [终端用户界面](apps/tui/ARCHITECTURE.md)\n- [图形用户界面](apps/gui/ARCHITECTURE.md)\n\n### 自定义\n\n- [自定义提供者](docs/customization/custom-providers.md)\n- [自定义人格](docs/customization/custom-personas.md)\n- [自定义代理](docs/customization/custom-agents.md)\n- [自定义运行时提示](docs/customization/custom-runtime-prompt.md)\n- [自定义命令](docs/customization/custom-commands.md)\n\n### 开发\n\n- [脚本](scripts/ARCHITECTURE.md)\n- [测试](scripts/ARCHITECTURE.md#xtask-test-collection-scripts)\n- [环境](docs/start/settings.md)\n- [架构](ARCHITECTURE.md)\n- [基准测试方法](https://github.com/Tura-AI/benchmark/blob/main/doc/benchmark-methodology.md)\n- [当前测试集证据记录](https://github.com/Tura-AI/benchmark/blob/main/doc/current-test-set-record.md)\n- [基准测试工件](https://github.com/Tura-AI/benchmark/tree/main/results)\n\n## 贡献与项目治理\n\n贡献应该是有节制、可审查且有证据支持的，在负责受影响行为的测试层提供。选择匹配的问题和拉取请求类型，而不是为每次更改应用同一个清单。\n\n- [贡献指南](.github/CONTRIBUTING.md) — 从这里开始了解贡献类型、开发环境设置、测试选择和拉取请求步骤。\n- [贡献说明](docs/contributing-guide.md) — 测试所有权、影响矩阵、性能证据和工件清理规则。\n- [路线图](ROADMAP.md) — 当前的 0.1.x 稳定化优先级和计划中的 0.2 任务规划工作区。\n- [已知问题和证据缺口](docs/KNOWN_ISSUES.md) — 开放的架构、提供者、基准测试、性能和跨操作系统工作。\n- [行为准则](.github/CODE_OF_CONDUCT.md) — 社区标准和开放代理测试框架原则。\n- [安全策略](.github/SECURITY.md) — 受支持的版本和私有漏洞报告。\n- [支持](.github/SUPPORT.md) — 报告 bug、请求功能或提出设置和使用问题的地方。\n\n## 许可协议\n\nTura 采用 AGPL-3.0-or-later 许可。详见 [LICENSE](LICENSE)。\n\n## 基准测试注释与来源\n\n- [基准测试方法](https://github.com/Tura-AI/benchmark/blob/main/doc/benchmark-methodology.md)\n- [当前测试集证据记录](https://github.com/Tura-AI/benchmark/blob/main/doc/current-test-set-record.md)\n- [基准测试工件](https://github.com/Tura-AI/benchmark/tree/main/results)\n\n[^test-set-record]: [`tura-benchmark` 当前测试集证据记录](https://github.com/Tura-AI/benchmark/blob/main/doc/current-test-set-record.md)，定义了 280 次运行的已发布群体、278 次运行的关系分析群体、配置来源、聚合公式、排除规则和识别限制。README 的主要 High-to-High 表格从该已发布群体中选择了 210 次 Tura Balanced High、Tura Direct High 和 Codex CLI High 会话。\n\n[^debug-manifests]: Tura 的 DeepSWE 观测数据位于 [`tura-benchmark` 复现 1](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r01/manifest.json)、[复现 2](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r02/manifest.json) 和[复现 3](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r03/manifest.json)。匹配的 Codex CLI High 观测数据位于 [High 复现 1](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-codex-cli-high-r01/manifest.json)、[High 复现 2](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-codex-cli-high-r02/manifest.json) 和 [High 复现 3](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-codex-cli-high-r03/manifest.json)。每个配置在相同的 20 个任务 ID 上贡献了 60 次会话。\n\n[^rewrite-manifest]: Tura 的重构观测数据位于 [`tura-benchmark` GPT-5.6 Rewrite Repo 规范清单](https://github.com/Tura-AI/benchmark/blob/main/results/rewrite/report-20260710-gpt56-sol/canonical-manifest.json)；官方 Codex CLI High 观测数据位于 [Codex High 规范清单](https://github.com/Tura-AI/benchmark/blob/main/results/rewrite/report-20260714-codex-cli-0.144.1-gpt56-sol-high/canonical-manifest.json)。每个 High 配置贡献了 10 次会话和 472 个测试框架检查项。\n\n[^compact-dynamodb]: [`tura-benchmark` DynamoDB 第 107 轮压缩](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r01/dynamodb-toolbox-conditional-attribute-requirements/tura-balanced/dynamodb-toolbox-conditional-attribute-requirements-tura-balanced-run-01/metadata/contracts/rounds/round-0107.json)和[第 114 轮首次后续补丁](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r01/dynamodb-toolbox-conditional-attribute-requirements/tura-balanced/dynamodb-toolbox-conditional-attribute-requirements-tura-balanced-run-01/metadata/contracts/rounds/round-0114.json)。\n\n[^compact-wasmi-r1]: [`tura-benchmark` Wasmi 复现 1 第 43 轮压缩](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r01/wasmi-trap-coredumps/tura-balanced/wasmi-trap-coredumps-tura-balanced-run-01/metadata/contracts/rounds/round-0043.json)和[第 44 轮首次非读取操作](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r01/wasmi-trap-coredumps/tura-balanced/wasmi-trap-coredumps-tura-balanced-run-01/metadata/contracts/rounds/round-0044.json)。该运行在第 46 轮结束，无后续补丁或测试操作。\n\n[^compact-wasmi-r2]: [`tura-benchmark` Wasmi 复现 2 第 26 轮压缩](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r02/wasmi-trap-coredumps/tura-balanced/wasmi-trap-coredumps-tura-balanced-run-02/metadata/contracts/rounds/round-0026.json)、[第 28 轮首次非读取操作](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r02/wasmi-trap-coredumps/tura-balanced/wasmi-trap-coredumps-tura-balanced-run-02/metadata/contracts/rounds/round-0028.json)和[第 39 轮首次后续补丁/测试](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r02/wasmi-trap-coredumps/tura-balanced/wasmi-trap-coredumps-tura-balanced-run-02/metadata/contracts/rounds/round-0039.json)。\n\n[^compact-wasmi-r3]: [`tura-benchmark` Wasmi 复现 3 第 39 轮压缩](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r03/wasmi-trap-coredumps/tura-balanced/wasmi-trap-coredumps-tura-balanced-run-03/metadata/contracts/rounds/round-0039.json)和[第 41 轮首次后续补丁/测试](https://github.com/Tura-AI/benchmark/blob/main/results/debug/report-deepswe-v1.1-gpt56-sol-local-r03/wasmi-trap-coredumps/tura-balanced/wasmi-trap-coredumps-tura-balanced-run-03/metadata/contracts/rounds/round-0041.json)。\n\n[^compact-eza]: [`tura-benchmark` eza 第 23 轮压缩](https://github.com/Tura-AI/benchmark/blob/main/results/rewrite/report-20260710-gpt56-sol/eza/tura-balanced/eza-tura-balanced-gpt56-sol-run-02/metadata/contracts/rounds/round-0023.json)和[第 24 轮首次后续测试](https://github.com/Tura-AI/benchmark/blob/main/results/rewrite/report-20260710-gpt56-sol/eza/tura-balanced/eza-tura-balanced-gpt56-sol-run-02/metadata/contracts/rounds/round-0024.json)。\n","readmeFilename":"README.zh-CN.md"}