内容
# Ortho — 工程决策引擎
> **AI 编程助手可以编写代码，但它们不知道您的架构是什么。**
Ortho 是一款本地优先的工程智能工具，它会扫描您的 Python 仓库，了解其架构，并在合并之前捕获违规行为 — 这样您的 AI 助手就不会在下游破坏事情。
**→ [2 分钟开始](ONBOARD.md) ← 新用户从这里开始**
---
---
## 问题所在
AI 编程工具（Copilot、Claude Code、Cursor）非常擅长编写代码。它们会建议从路由器层添加数据库调用，从实用程序模块导入服务，或在三个包中引入循环依赖 — 所有这些都看起来非常合理，直到它破坏了某些下游内容。
而且由于 AI 没有过去决策的记忆，它会在下一个冲刺中再次建议相同的模式。
---
## Ortho 的功能
**1. 扫描您的仓库** — 从您的实际代码中构建调用图、导入图、符号索引和架构模型。对于 1,000 个文件，耗时约 10-30 秒。
**2. 发现真正的违规行为** — 层边界违规、循环依赖链、膨胀和耦合热点。每个发现都引用了真实、可检查的证据：实际的导入边、实际的循环链、实际的行。
**3. 记住您拒绝的内容** — 当您将某个发现标记为误报时，Ortho 会存储它。下次扫描时： *"2026-07-10 拒绝：违反服务边界。原因：故意快捷方式待重构。*
---
## 安装
**Windows (PowerShell):**
```powershell
irm https://adithyak3106.github.io/Ortho-community/install.ps1 | iex
```
**macOS / Linux:**
```bash
git clone https://github.com/AdithyaK3106/Ortho.git && cd Ortho && ./install.sh
```
先决条件：`git`、`python`、`pip`、`node`、`npm`
---
## 快速开始
```bash
cd your-repo
ortho init # 扫描和索引您的仓库
ortho guardrails # 查找层边界违规行为
ortho decide "添加 Redis 缓存到 API 层" # 决策支持
ortho ask "哪些模块拥有身份验证？" # 仓库问答
```
---
## CLI 命令
| 命令 | 功能 |
|---|---|
| `ortho init` / `ortho scan` | 初始化和索引您的仓库 |
| `ortho guardrails [path]` | 检测层边界违规行为 |
| `ortho analyze [--impact\|--debt\|--deps]` | 架构报告 |
| `ortho decide <intent>` | 多源决策支持 |
| `ortho plan <intent>` | 功能实现路径 |
| `ortho refactor [path]` | 膨胀、耦合和循环查找 |
| `ortho ask <question>` | 仓库问答 |
| `ortho feedback` | 接受/拒绝发现结果 — 建立记忆 |
| `ortho memory search <query>` | 搜索过去的工作流制品 |
| `ortho cross-repo` | 跨仓库智能 |
| `ortho run <intent>` | 运行 ASES 多代理工作流（PLANNER → ARCHITECT → CODER → REVIEWER），带有真实的审批门控。设置 `ORTHO_LLM_API_KEY` 以获取真实的代理输出；否则回退到明确标记的存根。 |
| `ortho status` / `approve` / `reject` | 检查、批准或拒绝正在进行的工作流运行 |
---
## MCP 服务器
Ortho 附带了一个 10 工具 MCP 服务器。将它连接到 Claude、Cursor 或任何 MCP 兼容的助手，您的 AI 即可在生成代码之前获取架构上下文。
```json
{
"mcpServers": {
"ortho": {
"command": "node",
"args": ["path/to/ortho/apps/mcp-server/dist/index.js"]
}
}
}
```
---
## 为什么选择本地优先？
我与大多数团队交谈，他们无法将源代码发送到第三方云 — SOC2 范围、HIPAA、FedRAMP、合同 IP 条款。CodeRabbit、Greptile 和 Qodo 基于云，因此在功能比较开始之前，它们在结构上就不合格。
Ortho 完全在您的机器上运行。它唯一写入的文件是 `.ortho/ortho.db` — 您仓库根目录中的一个 SQLite 数据库。没有源代码离开您的机器。没有身份验证，没有云，没有安装程序。
---
## 当前状态
- **1,198 个测试** — 1,198 个通过，涵盖 7 个包（cli-commands、repo-intelligence、context-hub、decision-engine、orchestration、token-optimizer、apps/cli）
- **误报审计** — 9 个真实仓库（click、flask、requests、django、celery + 内部）；91% → 0% 误报率，针对真实架构违规行为
- **mypy --strict** — 所有 19 个积极触摸的源文件均干净，已验证
- **10 个 MCP 工具** — 通过真实的 stdio 往返验证，针对 Flask、Django 和 SQLAlchemy 与原始 Claude Code 进行基准测试
- **ASES 多代理工作流** (`ortho run`) — 真实的工作状态机，带有真实的审批门控；现在连接到一个带有真实只读仓库工具的实时 LLM（read_file、search_symbols、run_guardrails 等），在真实的重构任务上验证
- **Python 主要**（tree-sitter AST，Python 3.8-3.13）；TypeScript 次要
**已知限制：**
- 重新设计的层边界检查器在合成夹具上进行了验证；尚未观察到在野外触发真实的生产违规行为。这就是试点用户的作用。
- 影响分析通过间接耦合（例如共享全局状态）低估了爆炸半径 — 手动代码读取目前比自动检查捕获更多。
- `cross-repo` 的相似性搜索有一个 O(n²) 守卫，它在大型仓库上快速失败，但在文件对范围内的基准测试中尚未产生确认的真实阳性。
- ASES 工作流的工具执行循环在每个步骤中限制为 10 个真实的往返 — 足够架构规划，但对于整个多文件编码任务来说不总是足够。
---
## 寻找试点
5 个工程团队在一个真实的内部仓库上运行 Ortho 30 天，并提供诚实的反馈。
如果您已经在生成 AI 代码并遇到了“但它破坏了架构”的问题 — [联系](mailto:urbrain369@gmail.com)。
---
## 链接
- [ONBOARD.md](ONBOARD.md) — 2 分钟快速入门
- [PILOT_READINESS.md](PILOT_READINESS.md) — 试点计划详情
- [GitHub](https://github.com/AdithyaK3106/Ortho)
- urbrain369@gmail.com
