内容
# 奥托
[](https://github.com/0Smallcat0/otto/actions/workflows/ci.yml)
一款**本地、由 AI 操作的金融终端**。您可以用日常语言表达需求；AI 代理为您操作终端 — 拉取市场数据、运行回测、管理模拟投资组合、消化新闻等。所有操作都在您的机器上运行。
奥托的设计目标是**由 AI 操作**，而非手动点击：整个产品作为一个安全、可由机器操作的工具表面，通过 MCP 暴露出来，因此编码代理（Claude Code / Codex）可以从头到尾运行它，而人类只需观察仪表盘。
*上方：一个真实的（未脚本化的）代理会话。输入一个句子；代理记录其计划，通过 MCP 运行回测，并报告成功 — 每个步骤都实时显示在仪表盘的 **AI 活动** 流中，完成后在回测墙上显示。*
`LIVE OFF · EXEC OFF` 是结构性的，不是设置。
## 快速开始 — 给您的代理一个终端（30 秒）
需要 [uv](https://docs.astral.sh/uv/) 和 Python 3.12。一行命令 — 无需克隆、无需构建、无需单独的服务器步骤（MCP 服务器自动启动终端后端，状态存储在 `~/.otto` 中）：
```bash
claude mcp add otto -- uvx --from git+https://github.com/0Smallcat0/otto otto-mcp
```
如果您是从克隆的仓库开始的？克隆后，运行 `uv sync`，然后：
```bash
claude mcp add otto -- uv --directory /absolute/path/to/otto run otto-mcp
```
（任何 MCP 客户端都可以使用 — 服务器是标准输入/输出上的换行分隔的 JSON-RPC，仅限标准库。）然后只需询问：
- *"这个终端能做什么？列出路由和我可以运行的操作。"*
- *"刷新公共市场数据并给我看 BTC 快照。"*
- *"对 BTCUSDT 运行一个均线交叉回测并总结结果。"*
- *"你写了一个坏的观察列表 — 从最新的备份中恢复它。"*
代理通过 115 个操作的安全门控合约获得六个工具（`terminal_status`、`list_routes`、`get_route`、`list_actions`、`run_action`、`refresh_public_data`）。实时交易、凭证输入和代码执行在结构上无法通过此界面访问 — 请参见下面的评估表，了解拒绝评级意味着什么。
想要人类仪表盘吗？
```bash
cd frontend && npm install && npm run build # 一次性 UI 构建
uv run otto # http://127.0.0.1:8765/
```
## 可衡量的可操作性 — 而不仅仅是“AI 驱动”
“AI 可以操作它”是一个可测试的主张，因此奥托提供了一个基准来测试它。[代理可操作性评估套件](evals/README.md) 给一个真正的无头代理 20 个日常语言任务（读取、变异、生成神器、多步骤和安全任务）在密封的沙箱中，并以**编程方式**评估结果 — 终端状态、生成的神器、拒绝且状态不变 — 绝不使用 LLM 评估：
| 模型 | 任务 | 通过 | 成功率 | 平均回合 |
| --- | --- | --- | --- | --- |
| `claude-sonnet-5` | 20 | 20 | **100%** | 6.5 |
| `claude-haiku-4-5` | 20 | 19 | **95%** | 6.8 |
安全任务评估**拒绝**：要求代理下单或存储 API 密钥必须使终端状态保持不变（在标准化时钟字段后进行比较）。烟雾模式证明每个评估检查在新鲜状态下都以红色开始，因此没有任务可以凭空通过。完整结果、每任务矩阵和局限性： [`evals/EVAL.md`](evals/EVAL.md) · 方法论： [ADR-0004](docs/architecture/ADR-0004-eval-methodology.md).
## 亮点
- **单进程本地应用** — FastAPI 后端同时为 JSON API 和内置 React UI 提供服务，地址为 `http://127.0.0.1:8765/`。
- **AI 操作界面** — 标准库唯的 [MCP](https://modelcontextprotocol.io) 服务器（`otto/local_terminal/mcp_server.py`）将路由和门控操作作为工具暴露出来。
- **设计安全门控** — 实时交易、凭证输入和代码执行默认关闭，拒绝时会有提示；默认运行时为只读/模拟/干预运行。
- **公共、无密钥市场数据** 在可用时（加密、股票、FX、宏观），并为免费层提供商（Finnhub / FRED / Twelve Data）提供可选的本地密钥保险库。
- **工作台** — 市场、加密、投资组合（创建/导入/导出/演示）、回测、新闻摘要、算法扫描和基于本地神器的 AI 聊天研究界面。
- **诚实的量化研究轨道** — 仅使用已关闭的蜡烛且带有下一个开启预测保护，明确的费用/滑点经济性，步行验证带有引擎发布的 一致性裁决，以及用文字打印的过拟合红色旗帜（参见 [步行验证方法研究](docs/research/sma-cross-walk-forward-study.md)）。
- **470+ 测试** 涵盖合约、安全门控、提供商、评估套件和 UI 端到端，在 Windows + Linux CI 上。
## 截图
任务墙是人类的只读窗口：投资组合和模拟账户状态，AI 管理的报价监视器，头条新闻和 **AI 活动** 流，每个代理操作都带有 ✓ 和摘要：
多资产市场板块（加密、美国/台湾股票、FX）— 公共数据，无需密钥；实时交易和代码执行保持关闭：
每个回测都作为一个自我描述的神器目录（配置、数据快照、交易、回报分析、来源、人机可读报告），并显示在回测墙上：
## 运行
单进程自用（在 `http://127.0.0.1:8765/` 上提供内置 UI + API）：
```powershell
# Windows
.\.venv\Scripts\python.exe -m otto.local_terminal
```
```bash
# macOS / Linux
python -m otto.local_terminal
```
构建前端（或在 UI 更改后）：
```bash
npm --prefix frontend install && npm --prefix frontend run build
```
开发者热重载 UI 通过 `npm --prefix frontend run dev` 保持可用（代理 `/api` 到后端）。
## AI 操作
奥托由日常语言命令驱动：您告诉代理您想要什么，它通过 MCP 工具表面操作终端（`python -m otto.local_terminal.mcp_server`，在 [`.mcp.json`](.mcp.json) 中注册）。参见 [docs/AI_OPERATOR_GUIDE.md](docs/AI_OPERATOR_GUIDE.md)。实时交易、凭证输入和禁用运行时保持在明确的合约后面。
## 架构
设计是**代理原生**：一个类型化的合约（113 个操作）是唯一的真实来源，MCP 工具表面、UI 功能目录和评估套件都是从中派生出来的。完整的写作带有系统图：
[`docs/architecture/ARCHITECTURE.md`](docs/architecture/ARCHITECTURE.md) · 决定：
[ADR-0001 堆栈](docs/architecture/ADR-0001-stack.md) ·
[ADR-0002 代理合约](docs/architecture/ADR-0002-agent-contract.md) ·
[ADR-0003 安全门控](docs/architecture/ADR-0003-safety-gates.md) ·
[ADR-0004 评估方法论](docs/architecture/ADR-0004-eval-methodology.md).
- `otto/local_terminal/` — FastAPI 后端：路由、操作合约、提供商适配器、安全/秘密门控、本地状态存储和 MCP 操作服务器。
- `frontend/` — React + Vite 单页 UI，在生产中静态提供服务。
- `evals/` — 代理可操作性基准（沙箱，编程评估）。
- `tests/` — pytest 套件（合约、门控、提供商、评估套件）加上 Playwright 端到端测试。
- `docs/` — AI 操作指南、架构笔记、研究论文和规划/审计分类帐。
## 清洁室说明
奥托是一个**清洁室重新实现**：它是通过**观察**参考终端的工作流程和形状构建的，而不是通过阅读、复制、移植或适应其代码或资产。实施独立性被强制执行，而不仅仅是声称 —
[`AGENTS.md`](AGENTS.md) 定义了源墙，
[`tests/test_clean_room_source_wall.py`](tests/test_clean_room_source_wall.py) 如果产品运行时表面引用观察到的源或泄漏第三方品牌，则构建失败。
私有第三方观察笔记故意**不发布**，以保持清洁室边界完整（参见 [`docs/reference/`](docs/reference/））。它不是一个分支、破解、资产复制或任何商业产品的继续；品牌、商业机制和不安全的执行路径被本地等价物取代。
## 安全模型
除非后续单独审查的安全合同明确允许，否则不在范围内：
- 第三方品牌、标志、商标、商业副本、订阅、计费。
- 可达的真实订单、私人 API 密钥订单流、真实余额读取、保证金、杠杆、空头暴露或衍生品实时执行。
默认构建为模拟/干运行/只读。
## 测试
```bash
python -m pytest -q # 470+ 测试
python -m ruff check .
# 代理可操作性基准（需要 claude CLI；烟雾模式无令牌）
python evals/run_eval.py --smoke
python evals/run_eval.py --model claude-sonnet-5 --report
```
## 许可证
[MIT](LICENSE).
