Tools 概览

Tools

工具是模型意图到系统效果的唯一路径。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 原生工具链

• 📁bin/
  • 📄carina-scan
  • 📄carina-grep
  • 📄carina-diff
  • 📄carina-patch-native
  • 📄carina-run
  • 📄carina-pty

二进制	职责
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 重启后，只有持久化源指纹仍与工作区匹配时才会复用已完成图。

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 等
• 能力要求：策略 · protocol/capabilities/
• 相关：MCP · Agents · CLI 参考

下一步

• MCP — 外部工具仍过策略
• 审计 — 每次工具结果都是事件