---
title: "Agents 概览"
description: "ReAct 编程 Agent — 模型决策、内核授权、Zig 执行。"
source: https://carina.nebutra.com/zh-cn/agents/overview/
---

# Agents 概览

> ReAct 编程 Agent — 模型决策、内核授权、Zig 执行。

Carina 驱动真实的 ReAct 编程 Agent。模型**只负责决定下一步**；每个副作用由 Rust 能力内核授权，再交给 Zig 原生工具执行。整个过程写入可校验的事件链，便于复盘和回滚。

## Agent 循环

每轮 reasoner 产生一个 JSON 动作。只读动作可以批量并行，写入动作仍按单步执行，以便审批、审计和失败恢复保持确定性。

| 动作 | 所需能力 / 路径 | 结果 |
| --- | --- | --- |
| `list` / `read` / `search` | `FileRead` | 工作区内文件树、内容或搜索结果 |
| `run` | `CommandExec` + 风险分级 | 受超时和环境变量白名单约束的命令结果 |
| `patch` | `PatchApply` | 可验证、可回滚的补丁事务 |
| `memory` | `MemoryWrite` | 经审批的持久记忆变更 |
| `mcp` / `mcp_find` | MCP manager + 对应能力 | 受治理的外部工具调用 |
| `spawn` | `SubagentSpawn` | 能力衰减的隔离子 Agent |
| `workflow` | `PluginLoad` | 命名依赖 DAG |
| `ask_user` | Operator input | 结构化人工选择 |
| `done` | 无副作用 | 结束任务并返回摘要 |

破坏性命令会在执行前拒绝；密钥文件默认不可读；每次文件编辑都经过补丁事务而非静默覆盖。

## Reasoner 后端

| 后端 | 用途 |
| --- | --- |
| **model-router** | BYOK provider、模型路由、流式输出与 token 统计 |
| **claude-cli** | 显式兼容后端；调用本机 `claude -p`，禁用工具并使用空 cwd |
| **codex-cli** | 显式兼容后端；调用 `codex exec`，使用临时 JSONL、工具禁用、只读隔离与 fail-closed 事件解析 |
| **scripted** | 测试中的固定决策与确定性回放 |

自动模式只会在 provider 可运行时选择 `model-router`，不会因为 PATH 中存在 CLI binary 而选择外部后端。使用 `CARINA_REASONER_BACKEND=claude-cli` 或 `CARINA_REASONER_BACKEND=codex-cli` 显式启用兼容后端；`CARINA_REASONER_MODEL` 固定所选后端的模型。`CARINA_SUMMARIZER_MODEL` 与 `CARINA_VERIFIER_MODEL` 可分别指定压缩和校验模型。

Claude 的非交互参数是 `-p`；Codex 必须使用 `codex exec`，其中 `-p` 表示 profile。Codex 的只读 sandbox 并非严格的禁止读取或禁止执行边界，因此 Carina 还会拒绝工具事件和未知 item，并保持该后端仅可显式启用。

## 可靠性护栏

- **LoopGuard**：按规范化动作签名阻断重复循环。
- **MistakeTracker**：连续失败达到阈值后停止继续试错。
- **Compaction**：旧轮次压缩为带收据的摘要，用户原文保留 verbatim 层。
- **Steering**：urgent / normal 两级消息箱只在轮次边界注入。
- **Checkpoint**：长任务可恢复，但恢复后仍重新经过当前策略判断。

## 运行与核验

```bash title="agent-loop.sh"
cd /path/to/repo
# 交互 TUI 会在需要时自动启动 daemon；无头跑也可先：
#   carina daemon start
carina run "fix the failing test in parser.go"
carina audit SESSION
carina audit verify SESSION
carina patch list SESSION
carina patch rollback SESSION PATCH_ID
```

## 消费 Agent 状态的表面

| 表面 | 角色 |
| --- | --- |
| TUI（`carina`） | **主**操作者体验 — slash 命令、审批浮层、plan/build 模式 |
| CLI | 无头 / CI：`carina run`、`approve`、`audit` 等 |
| VS Code 扩展 | 可选客户端（`integrations/vscode`）— 需要编辑器内附着时从 release 资产安装 |
| Web operator | 实验性静态壳（`integrations/web`）— 尚非完整 dashboard 产品 |

它们共享同一套会话与事件状态，不是四套不同的 Agent 引擎。

  多步并行任务优先使用工作流；单次委派再使用子 Agent。两者都会衰减权限，不能把父会话没有的能力授予子任务。

## 权威来源

- Agent 循环：`docs/agent.md` · reasoner：`go/daemon/reasoner.go`
- CLI：`carina run` / `carina ask` · [CLI 参考](/zh-cn/reference/cli/)
- 相关：[策略](/zh-cn/concepts/policy/) · [工具](/zh-cn/tools/overview/) · [子 Agent](/zh-cn/agents/sub-agents/)

## 下一步

- [子 Agent](/zh-cn/agents/sub-agents/) — 能力衰减委派
- [常用工作流](/zh-cn/getting-started/common-workflows/) — 首条受治理会话
- [审计](/zh-cn/concepts/audit/) — 跑完后核验

---
Source: https://carina.nebutra.com/zh-cn/agents/overview/
Markdown: https://carina.nebutra.com/zh-cn/agents/overview/index.md