Grinta 完全指南：本地优先、模型无关的终端 AI 编码 Agent
AI 编码 Agent 正在改变我们写代码的方式，但大多数主流工具都存在一个共同问题：被锁死在某个特定模型供应商。Claude Code 只支持 Anthropic，Codex CLI 只支持 OpenAI。如果你想在本地跑 Ollama 模型、自由切换不同的 LLM 供应商，或者希望 Agent 在完全离线的环境下工作，这些工具都难以满足需求。
Grinta 正是为此而生——一个本地优先、模型无关的终端 AI 编码 Agent。它不仅是开源的（MIT 许可证），还内置了 LSP 语言服务器集成、DAP 调试器支持、成本/延迟 HUD、以及完整的任务生命周期管理。本文将带你全面了解 Grinta 的核心特性、安装配置和实战用法。
什么是 Grinta？
Grinta 是一个 Python 编写的终端 AI 编码 Agent，遵循「规划→执行→观察→验证→完成」的完整任务循环。它与其他工具最大的区别在于：
| 特性 | Grinta | Aider | Claude Code | Codex CLI |
|---|---|---|---|---|
| 模型无关 | ✅ | ✅ | ❌ Anthropic 独占 | ❌ OpenAI 独占 |
| 本地优先（离线可用） | ✅ 自动检测 | 部分 | ❌ | ❌ |
| LSP 集成（自动发现 40+ 语言服务器） | ✅ | ❌ | 部分 | ❌ |
| DAP 调试器集成 | ✅ 自动发现 | ❌ | ❌ | ❌ |
| 成本/Token/延迟 HUD | ✅ 实时显示 | 部分 | ❌ | 部分 |
| 卡死循环检测 | ✅ | ❌ | 部分 | ❌ |
| 风险分类动作 + 审计日志 | ✅ | ❌ | 部分 | 部分 |
| 会话检查点/恢复/回退 | ✅ 事件流 | ✅ git | 部分 | ❌ |
| MCP 支持 | ✅ | ❌ | ✅ 强支持 | 部分 |
Grinta 的核心价值可以用一句话概括：一个内置深层次工具支持的本地优先编码 Agent，不锁定任何模型供应商。
安装
Grinta 推荐使用 pipx 安装，支持 Linux、macOS 和 Windows（含 WSL2）：
pipx install grinta-ai
Grinta 还提供了可选扩展包：
pipx install "grinta-ai[rag]" # 知识检索能力 pipx install "grinta-ai[browser]" # 浏览器自动化 pipx install "grinta-ai[all]" # 全部扩展
首次运行 grinta 会自动启动交互式设置向导，配置 API Key 和模型选择。也可以在 ~/.grinta/ 下手动编辑配置。
Docker 方式（实验性）：
docker run -it --rm -v "$PWD:/work" -w /work \ -e LLM_API_KEY=*** \ ghcr.io/josephsenior/grinta:latest
三种交互模式
Grinta 提供了三种交互模式，从根本上改变了对话的契约：
Chat（聊天模式）
只读的问答模式，Agent 只能使用探索性工具，不会编辑文件或执行 shell 命令。适合快速查阅代码库、提出技术问题。
Plan（计划模式）
只读的调查模式，Agent 可以使用 task_tracker 生成结构化计划。适合在设计阶段梳理实现方案。切换到 Agent 模式才能执行计划。
Agent（Agent 模式）
完整的任务循环模式（默认）。Agent 可以编辑代码、执行命令、调试程序。这是实际干活时使用的模式。
自主性控制
在 Agent 模式下，可以通过 /autonomy 命令控制确认行为的严格程度：
- conservative（保守）：每一步修改都需要确认
- balanced（平衡）：关键操作需要确认，常规操作自动执行
- full（完全）：Agent 自主执行，仅在 CRITICAL 级别动作时暂停
安全边界
Grinta 设计了多层安全机制：
- 风险分类动作：每个操作按风险级别分类（INFO / WARNING / CRITICAL），CRITICAL 操作有拒绝门
- 密钥掩码：自动检测并掩码 API Key、Token 等敏感信息
- 审计日志：会话范围内的完整操作追踪记录
- 执行配置文件（
security.execution_profile）：
standard：默认，支持完整交互终端和调试器hardened_local：增加更严格的策略检查sandboxed_local：对非交互命令增加进程隔离
常用斜杠命令
| 命令 | 功能 | |
|---|---|---|
/help | 完整斜杠命令参考 | |
/settings | 模型、API Key 和 MCP 配置 | |
/sessions | 列出历史会话；`/resume | id>` 恢复 | |
/model | 查看或切换当前提供商/模型 | |
/mode | 查看或设置交互模式 | |
/autonomy | 查看或设置确认行为 | |
/cost | Token 数、调用次数、花费 | |
/diff | 工作区 Git 变更 | |
/health | 快速自检（调试器、rg、git、模型设置） | |
/checkpoint | 快照工作区（可回退） | |
/status | HUD 快照；/status verbose 加诊断信息 | |
/compact | 强制上下文压缩 |
此外，Grinta 还支持一系列 Playbook 工作流：/debug、/testing、/feature 等，可以通过 /help 查看完整列表。
上手示例
安装后进入一个项目目录，运行：
cd my-project grinta
首次启动后，Grini 会启动 Textual 终端 UI，显示 HUD 面板、命令卡片和设置菜单。输入 /health 快速检查环境是否就绪：
✓ git: found ✓ ripgrep: found ✓ LSP: rust-analyzer (detected) ✓ DAP: lldb-dap (detected) ✓ Model: gpt-4o (configured)
确认一切就绪后，切换至 Agent 模式，告诉 Grinta 你的任务：
> 给这个模块添加单元测试，覆盖率目标 80%
Grinta 会自动规划任务步骤，执行测试编写，运行验证结果，最后报告完成情况。如果过程中遇到卡死循环，它会自动检测并尝试恢复路径。
Grinta 的架构概览
Grinta 的架构遵循清晰的分层设计：
- CLI 入口：
backend.cli.entry处理终端输入 - TTY 层：Textual 构建的终端 UI，或管道输入的飞交互模式
- Session Orchestrator：会话协调器，管理任务生命周期
- Engine：规划和工具意图引擎
- Operation Pipeline：安全检查和验证管道
- Runtime Executor：本地执行器
- EventStream Ledger：事件流账本，保证会话持久性和可恢复性
- Task Validation：完成前的质量验证门
总结
Grinta 作为一个本地优先、模型无关的终端 AI 编码 Agent，最大的价值在于给了开发者真正的选择自由。无论是跑本地 Ollama 模型、混合使用多个云供应商，还是在离线环境中工作，Grinta 都能胜任。内置的 LSP/DAP 集成、成本 HUD、卡死检测和安全边界，使其在功能完备性上不输给 Claude Code 或 Codex CLI，同时又避免了被单一供应商锁定的风险。
如果你正在寻找一个开源、灵活、可自托管的 AI 编码 Agent，Grinta 值得一试。当前版本为 v1.0.0-rc1（发布候选版），功能已趋于稳定，社区反馈窗口正在开放中。
相关链接