---
title: "Tools 概览"
description: "由能力内核中介的内置工具、Zig 工具链与外部工具。"
source: https://carina.nebutra.com/zh-cn/tools/overview/
---

# Tools 概览

> 由能力内核中介的内置工具、Zig 工具链与外部工具。

工具是模型意图到系统效果的唯一路径。Carina 将工具调用规范化，因此策略、审计、TUI 与 SDK 对同一动作看到一致的生命周期。

## 工具族

| 工具族 | 典型动作 | 治理边界 |
| --- | --- | --- |
| 文件系统 | list / read / search / patch | 只能访问会话工作区 |
| Shell | `run` | `CommandExec` 风险分级、超时、环境白名单 |
| Memory | add / replace / remove | `MemoryWrite` 审批与内容扫描 |
| 代码智能 | symbols / def / refs / impact | `FileRead` + 本地索引 |
| MCP | `mcp` / `mcp_find` | 外部服务仍需能力授权 |
| 编排 | spawn / workflow / best_of_n | 子能力衰减与独立审计 |
| 人工输入 | `ask_user` | 结构化 operator decision |

## Zig 原生工具链

| 二进制 | 职责 |
| --- | --- |
| `carina-scan` | 输出工作区文件树 |
| `carina-grep` | 结构化文本搜索 |
| `carina-diff` | 生成结构化差异 |
| `carina-patch-native` | dry-run、应用、校验与回滚补丁 |
| `carina-run` | 带超时和环境约束的命令执行 |
| `carina-pty` | 交互终端会话 |

这些工具输出机器可读 JSON，但**不会绕过能力内核**。原生工具负责快速、确定地执行；是否允许执行仍由策略决定。

## 代码智能

| 工具 | 结果 |
| --- | --- |
| `code.search` | 排序后的关键词与语义匹配 |
| `code.symbols` / `code.def` / `code.refs` | 定义、引用与精度来源 |
| `code.impact` | 受治理的传递依赖影响范围 |
| `code.map` | 工作区符号图的 token 有界投影 |

大型工作区首次使用时不会让 Agent 阻塞等待完整扫描。Carina 为每个工作区维护一份可恢复的完整图，并在后台按有界批次构建。构建期间，`code.map` 会返回明确进度和当前可用的局部语义投影；首个语义批次就绪前使用元数据概览。daemon 重启后，只有持久化源指纹仍与工作区匹配时才会复用已完成图。

```text frame="none"
Index coverage: complete; graph: 6434 indexed files, 44120 symbols, 228788 edges, 82687 chunks;
projection: 37/5689 files and 37/44120 symbols (pagerank-domain-diverse, about 1017 tokens).
```

有限投影不会伪装成完整符号转储。PageRank 提供全局相关性；选择器先覆盖不同顶层域和已排序文件，再为同一文件分配更多符号。每个保留符号都携带全局排名以及入边、出边数量。摄取、状态检查和图读取仍同时受会话 `CodeIndex` 与 `FileRead` 策略约束。

## 安全规则

1. 每个工具声明所需能力。
2. 参数在执行前校验，路径会归一化到工作区。
3. 成功、拒绝和错误都会进入事件流。
4. 插件若使用 manifest 未声明的能力，会产生 `PolicyViolation`。
5. 写文件优先走 patch，而不是把任意 shell 当编辑器。

  “工具已注册”不代表“当前会话可调用”。实际权限取决于 session profile、资源范围和审批结果。

## 权威来源

- Agent 工具表与 Zig 原生工具：`carina-scan`、`carina-grep`、`carina-patch-native` 等
- 能力要求：[策略](/zh-cn/concepts/policy/) · `protocol/capabilities/`
- 相关：[MCP](/zh-cn/tools/mcp/) · [Agents](/zh-cn/agents/overview/) · [CLI 参考](/zh-cn/reference/cli/)

## 下一步

- [MCP](/zh-cn/tools/mcp/) — 外部工具仍过策略
- [审计](/zh-cn/concepts/audit/) — 每次工具结果都是事件

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