内容
# Sruja
[](https://codecov.io/gh/sruja-ai/sruja)
**Sruja 是一个优先使用命令行界面（CLI）的自主编码代理。** 它扫描您的代码仓库，确保每次修改都基于实际拓扑结构，并在发布前验证结果。
```text
focus / drift → 代理编辑代码 → verify-task → （批评或批准）
```
Sruja 还可以在任何编辑器（Cursor、Copilot、Claude、Windsurf）中作为 **被动工具** 使用，通过 MCP —— 使用相同的确定性网关，您的 LLM 驱动程序。
---
## 代理循环
核心产品是一个闭环代理，拥有完整的观察 → 执行 → 验证 → 批评 → 重新规划循环：
```bash
# 自主 - Sruja 计划、编辑、验证、批评和重新规划
sruja agent loop --goal "重构身份验证边界而不破坏测试"
```
Sruja 的确定性层（drift、lint、verify-task、intent check）是 **独立评估器** —— 演员永远不会自我评估。
### 编辑器托管循环（MCP）
当您的编辑器驱动 LLM 时，Sruja 提供基础和验证网关：
```text
1. MCP：focus / drift 状态 / 边界上下文
2. 主机 LLM 编辑代码
3. sruja verify-task --profile coding -r .
4. （可选）sruja agent record -c "…" 在失败时
```
---
## 快速入门
```bash
# 1. 安装
curl -fsSL https://sruja.ai/install.sh | bash
# 2. 扫描您的代码仓库
sruja start -r .
sruja drift -r . --structural-only --advisory
# 3. 简要介绍更改（粘贴到您的代理中）
sruja focus -r . --file path/to/file.rs
# 4. 编辑后验证
sruja verify-task --profile coding -r .
```
第一天不需要 `repo.sruja`。
---
## 工作原理
### 1. 捕获知识（可选）
将持久性上下文引入代码仓库 - 设计文档、ADR、决策：
```bash
sruja ingest <path>
sruja decision add --title "使用 async 进行 I/O" --rationale "..."
```
在 Git 中审查意图（可选，适用于希望 CI 强制边界的团队）：
```bash
sruja lint repo.sruja
sruja sync -r .
sruja drift -r . -a repo.sruja
```
### 2. 检索任务上下文
在编辑之前，获取具有爆炸半径、依赖项和相关决策的文件范围简介：
```bash
sruja focus -r . --file path/to/file.rs # 结构化简介
sruja ai -r . --task "重构身份验证边界" # 粘贴就绪简介
```
### 3. 验证对齐
编辑后，确定性检查确认结果仍然与结构和意图匹配：
```bash
sruja verify-task --profile coding -r . # 完整验证
sruja drift -r . --structural-only # 仅拓扑检查
sruja intent check -r . # 设计意图检查
```
---
## 编辑器集成
Sruja 通过 MCP 进行集成，为您的 AI 编辑器提供基础上下文和编辑后验证。
Cursor 模板：[.cursor/mcp.json](.cursor/mcp.json)
```json
{
"mcpServers": {
"sruja": {
"command": "sruja",
"args": ["mcp", "-r", "."],
"env": {
"SRUJA_MCP_TOOL_PROFILE": "coding",
"SRUJA_MCP_READONLY": "1"
}
}
}
}
```
使用默认的 `coding` 配置文件（15 个工具：focus、drift、verify、memory search、hybrid query、critique 等）。
---
## Sruja 比较
| | Copilot / Cursor / Windsurf | Sruja |
|---|---------------------------|-------|
| **它做什么** | 从提示生成代码 | 生成代码 **和** 验证代码仓库拓扑结构 |
| **基础** | 文件上下文 + 嵌入 | 结构扫描（循环、层、god 模块）+ 可选审查意图 |
| **验证** | 无内置验证 | `verify-task`、`drift`、`intent check` - 确定性，编辑后 |
| **自主模式** | 主机管理的代理循环 | `sruja agent loop` - 拥有完整的观察 → 执行 → 验证 → 批评 → 重新规划 |
| **编辑器故事** | 原生代理 UX | MCP `coding` 配置文件 - 相同的网关，任意编辑器 |
**一行代码：** AI 编码代理生成；Sruja 生成 **和** 网关 - 之前和之后。
**诚实的限制：** 查看 [KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md) - 动态导入、反射/DI、启发式层、绿色字段上的孤立错误正（使用 `drift --advisory`）。
---
## 扩展
所有其他功能都建立在上述代理循环和确定性网关之上。
### 核心相关
- **架构创作**：更丰富的 `repo.sruja` 工作流程、提案、作者证据
- **可视化**：Mermaid、Markdown、D2、GraphML、Neo4j、Obsidian 导出
- **团队工作流程**：审查、CI 中的漂移、合规性、批评、联合
### 高级
- **代理操作**：学习、运行快照、内存管理、持续学习
- **工作流程编排**：工作流程和 AI-DLC 流
- **分析**：仪表板、图历史、指标、注册工具
---
## 文档
- 网站：https://sruja.ai
- 入门指南：[book/src/getting-started.md](book/src/getting-started.md)
- 主机/编辑器设置：[HOST_AGENT_INTEGRATION.md](docs/HOST_AGENT_INTEGRATION.md)
- 代理循环 + 持续学习：[GROUNDED_HARNESS_AND_CONTINUAL_LEARNING.md](docs/GROUNDED_HARNESS_AND_CONTINUAL_LEARNING.md)
- 核心 vs 扩展：[FEATURE_TIERS.md](docs/FEATURE_TIERS.md)
- MCP 工具参考：[mcp_tools_reference.md](docs/mcp_tools_reference.md)
---
## 安装
**安装脚本**
```bash
curl -fsSL https://sruja.ai/install.sh | bash
```
**Cargo**
```bash
cargo install sruja-cli --git https://github.com/sruja-ai/sruja
```
**从源代码构建**
```bash
git clone https://github.com/sruja-ai/sruja.git
cd sruja
just build
```
### 可选技能
```bash
npx skills add https://github.com/sruja-ai/sruja --skill sruja-harness
npx skills add https://github.com/sruja-ai/sruja --skill sruja-architecture
```
---
## 故障排除
**`sruja: command not found`**
```bash
export PATH="$HOME/.local/bin:$PATH"
```
**AI 生成无效审查意图**
```bash
sruja lint repo.sruja --format json
```
**需要了解 Sruja 发现的内容**
- 修改前使用 `sruja focus`
- 使用 `sruja ai` 获取粘贴就绪的任务简介
- 使用 `sruja why` 进行调查
## 贡献
- [贡献指南](docs/CONTRIBUTING.md)
- [路线图](ROADMAP.md)
## 贡献者
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
该项目遵循 [all-contributors](https://github.com/all-contributors/all-contributors) 规范。欢迎任何类型的贡献！
## 许可证
Apache 2.0 或 MIT
