mirror of
https://github.com/l0ng-ai/openidea.git
synced 2026-11-19 00:10:00 +00:00
Focus Agent Input (⌘L on macOS, Ctrl+L on Windows / Linux, in every built-in keymap) returns focus to the current writable task's message input from its conversation, in an editor tab or the tool window, keeping the draft, caret and selection. It applies only while focus is inside an agent task, so the keys keep their editor and terminal meaning elsewhere; the binding is under Settings › Keymap › Agents. Co-authored-by: Mr0Bread <55754540+Mr0Bread@users.noreply.github.com>
159 lines
12 KiB
Plaintext
159 lines
12 KiB
Plaintext
---
|
||
title: "Agent"
|
||
description: "在 IDE 中运行 Claude Code、Codex、Gemini CLI 等编码 agent,每个任务可以在独立的 Git worktree 中或直接在当前工作区里进行。"
|
||
---
|
||
|
||
OpenIDEA 可以运行命令行编码 agent,并在 IDE 中为它们提供聊天界面。每段对话是一个 **任务**。任务可以在一个新的 Git worktree 中进行,不影响你自己的改动;也可以直接在项目里修改文件。你可以以 diff 的形式查看它改了什么、回应它的权限请求,并同时运行多个任务。
|
||
|
||
OpenIDEA 本身不带模型或账号:它启动你已安装并登录的 agent,通过 [Agent Client Protocol](https://agentclientprotocol.com)(ACP)与之通信。
|
||
|
||
## 支持的 agent
|
||
|
||
以下 agent 是内置的。先安装 agent 自己的命令行工具,并在终端里登录一次;OpenIDEA 会在 `PATH` 中找到它。
|
||
|
||
| Agent | OpenIDEA 启动的命令 | 登录命令 |
|
||
| -------------- | --------------------------- | --------------------- |
|
||
| Claude Code | `claude` | `claude` |
|
||
| Codex | `codex app-server` | `codex login` |
|
||
| Gemini CLI | `gemini --experimental-acp` | `gemini` |
|
||
| GitHub Copilot | `copilot --acp` | `copilot` |
|
||
| Cursor | `cursor-agent acp` | `cursor-agent login` |
|
||
| OpenCode | `opencode acp` | `opencode auth login` |
|
||
| Qwen Code | `qwen --experimental-acp` | `qwen` |
|
||
| Qoder | `qodercli --acp` | `qodercli login` |
|
||
| Qoder CN | `qoderclicn --acp` | `qoderclicn login` |
|
||
| Kimi CLI | `kimi acp` | `kimi` |
|
||
| Goose | `goose acp` | `goose configure` |
|
||
| Auggie | `auggie --acp` | `auggie login` |
|
||
| Kiro | `kiro-cli acp` | `kiro-cli login` |
|
||
| Mistral Vibe | `vibe-acp` | `vibe` |
|
||
|
||
**Claude Code** 和 **Codex** 通过它们自己的协议驱动(Claude Code 的 stream-json 模式和 `codex app-server`)。它们的 ACP 适配器(`claude-acp`、`codex-acp`)不再列出;已经在用它们的任务照常运行,为这两个 id 写一个 [agent 文件](#添加自定义-agent)也会重新列出。agent 需要登录时,任务中会提示该运行哪条命令。
|
||
|
||
未被标记为受信任的项目中无法使用 agent。
|
||
|
||
## 新建任务
|
||
|
||
| 操作 | macOS | Windows / Linux |
|
||
| ------------------- | ----- | ------------------ |
|
||
| **新建 Agent 任务** | `⇧⌘I` | `Ctrl+Alt+Shift+I` |
|
||
|
||
<Steps>
|
||
<Step title="打开“新建 Agent 任务”页面">
|
||
按快捷键,或在右侧的 **智能体** 工具窗口中单击 **新建 Agent 任务**。
|
||
</Step>
|
||
<Step title="描述任务">
|
||
写下要 agent 做的事。输入 `@` 引用文件,输入 `/` 使用 agent 的斜杠命令;agent 支持时还可以粘贴或附加图片(**附加图片…**)。
|
||
</Step>
|
||
<Step title="选择工作位置">
|
||
- **新 worktree**:agent 在新的 Git worktree 中工作,分支名为 `agent/<任务>`,从你选择的基础分支创建,不会动你的工作区。worktree 创建在项目旁边名为 `<项目名>.worktrees` 的文件夹中。
|
||
- **当前工作区**:agent 直接修改你的文件。
|
||
</Step>
|
||
<Step title="选择 agent 及其设置">
|
||
选择 agent,以及它提供的模型、模式等选项。缓存的模型会立即显示;所选 agent 的模型列表超过 15 分钟未更新时,会在后台刷新,不发送提示词,也不接入项目 MCP 服务器。
|
||
|
||
更改 agent CLI 或账号后,打开模型选择器并单击 **刷新模型**。并发刷新会共用一次查询;每次查询完成后(包括失败)都有 30 秒冷却时间。刷新中或刷新失败后,缓存选项仍可使用。
|
||
|
||
可用模型取决于已安装的 agent 和账号。如果已选模型被移除,需要先选择其他模型才能开始任务。刷新不会更改正在运行的任务。
|
||
|
||
</Step>
|
||
<Step title="发送">
|
||
任务会在编辑器标签页中打开并开始运行。
|
||
</Step>
|
||
</Steps>
|
||
|
||
## 使用任务
|
||
|
||
任务标签页显示整段对话:你的消息、agent 的回复、思考过程、计划、它运行的工具以及启动的子 agent。agent 工作期间:
|
||
|
||
- 你发送的消息会进入队列,在本轮结束后发出(**排队中的消息**)。**立即发送** 会停止当前这一轮并接着发送这条消息;排队的消息也可以编辑或移除。
|
||
- **停止** 结束当前这一轮。
|
||
- `⌘F` / `Ctrl+F` 在对话中查找。
|
||
|
||
在你自己的消息上可以 **编辑**(其后的消息会被替换,已经改动的文件保持不变)或 **撤回消息**。在回复上可以 **复制 Markdown**、**引用回复**、**重新生成回复**,以及 **从此处创建分支对话**,从这一点开始一个新任务。
|
||
|
||
所有内置按键映射中,**聚焦 Agent 输入框** 的默认快捷键都是 macOS 上的 `⌘L`、Windows / Linux 上的 `Ctrl+L`。焦点位于你自己的可输入任务对话中时,无论对话显示在编辑器标签页还是工具窗口中,它都会将焦点移回消息输入框,保留草稿、光标位置和选区;重复按下也不会改变这些内容。它不会发送消息,也不会跳转消息历史。
|
||
|
||
此快捷键不适用于已归档任务、子 agent 对话或“新建任务”页面,也不会从打开的弹出窗口或对话框中抢走焦点。在任务对话之外,按键保留原有的编辑器或终端行为。要修改或移除绑定,请打开 **设置 › 按键映射 › 智能体 › 聚焦 Agent 输入框**。
|
||
|
||
右键点击链接并选择 **复制链接地址** 可复制它的 URL;**复制** 复制选中的文字。
|
||
|
||
### 权限
|
||
|
||
agent 要运行命令或调用需要授权的工具时,任务中会显示请求,并归入 **等待输入**。从 agent 提供的选项中选择,例如 **允许一次**、**在此会话中允许**、**始终允许**、**拒绝**、**始终拒绝** 或 **拒绝并停止**。很多 agent 还有模式选择器,可以自动批准编辑甚至所有操作,请谨慎使用。
|
||
|
||
agent 运行过一个任务后,新任务会以它自动批准所有操作的模式开始(Claude Code 的绕过权限、Codex 的完全访问),此时命令权限不生效。要让新任务以请求批准的模式开始,把 **设置 › 智能体 › 聊天 › 新任务开始时** 设为 **请求批准**。这一项只由你自己的设置决定,项目设置无法更改。
|
||
|
||
### 查看改动
|
||
|
||
在任务标题栏中单击 **显示更改**,列出任务改动过的文件;单击文件可以打开它从任务开始到现在的 diff。worktree 任务的改动在它的 `agent/…` 分支上:用 **在终端中打开** 在那里打开终端,满意后用 Git 工具合并或 cherry-pick 这个分支(见 [版本控制](/zh/guide/vcs))。
|
||
|
||
### 从编辑器提供上下文
|
||
|
||
- 编辑器和项目视图右键菜单中的 **发送给 Agent** 会把选区或选中的文件作为 `@` 引用加到你最近输入的消息中。它默认没有快捷键,可以在 **设置 › 按键映射** 中分配。
|
||
- agent 接受内嵌文件时,256 KB 以内的引用文件会直接嵌入提示词。
|
||
- 打开 [内置 MCP 服务器](/zh/guide/mcp) 后,每个任务都会把 OpenIDEA 的工具作为 MCP 服务器提供给 agent,让它可以使用 IDE 的搜索、符号查询、问题列表、运行配置等功能。
|
||
|
||
## 智能体工具窗口
|
||
|
||
**智能体** 工具窗口按需要你处理的程度列出项目中的任务:**等待输入**、**失败**、用量到达上限、**正在运行**、**待审阅** 和 **已归档**。它的角标显示等待输入或有未读回复的任务数。
|
||
|
||
任务默认在编辑器标签页中打开。**在工具窗口中聊天** 和 **在编辑器中聊天** 切换对话的打开位置,也可以把任务拖到编辑区。任务的右键菜单中有 **打开**、**重命名…**、**在终端中打开**、**复制为新任务**、**固定** / **取消固定**、**移动到组**、**归档** / **取消归档** 和 **删除…**。删除 worktree 任务时会一并删除它的 worktree。
|
||
|
||
置顶的任务显示在所有分组之上。**移动到组** 可以把任务放进自建的分组,把它拖到分组标题上也可以;工具窗口选项菜单(⋯)中的 **新建组…** 新建空分组,分组自身的菜单可以重命名或移除它。分组和置顶状态按项目保存。
|
||
|
||
任务按项目保存,重启后仍在。agent 支持恢复会话时,下次发消息会从上次中断处继续;这类 agent 空闲五分钟后会被停止,下次发消息时再重新启动。
|
||
|
||
## 管理 agent
|
||
|
||
**设置 › 工具 › 智能体**(也可以在 agent 选择器中点 **更多 Agent…**)有两个标签页:
|
||
|
||
- **内置**:每个内置 agent 的可执行文件是否在 `PATH` 中找到、指定 **自定义可执行文件** 的输入框、传给 agent 进程的 **环境变量**(格式为 `NAME=value; OTHER=value`;这些值保存在系统凭据存储中)以及登录方式。改动对新会话生效。
|
||
- **ACP 注册表**:[ACP Registry](https://agentclientprotocol.com) 中发布的 agent,可以搜索、**安装**、**更新** 和 **移除**。安装的 agent 保存在 OpenIDEA 的数据目录中;注册表提供 SHA-256 时会校验下载内容。
|
||
|
||
**设置 › 工具 › 智能体 › 聊天** 决定任务标题栏显示哪些信息:**上下文窗口用量**、**任务耗时**、**用量限额**(agent 报告时,例如 Claude Code)和 **会话花费**。
|
||
|
||
## 添加自定义 agent
|
||
|
||
任何通过 stdio 使用 ACP 的 agent,都可以用一个 agent 文件添加:OpenIDEA 配置目录下的 `agents/<id>.toml`。
|
||
|
||
| 系统 | agent 文件目录 |
|
||
| ------- | -------------------------------------------------------- |
|
||
| macOS | `~/Library/Application Support/ai.l0ng.openidea/agents/` |
|
||
| Windows | `%APPDATA%\ai.l0ng.openidea\agents\` |
|
||
| Linux | `~/.config/ai.l0ng.openidea/agents/` |
|
||
|
||
```toml
|
||
# agents/my-agent.toml
|
||
name = "My Agent"
|
||
command = "/usr/local/bin/my-agent"
|
||
args = ["--acp"]
|
||
|
||
[env]
|
||
MY_AGENT_LOG = "info"
|
||
```
|
||
|
||
<ParamField path="name" type="string">
|
||
在 agent 选择器中显示的名称,默认为文件名。
|
||
</ParamField>
|
||
<ParamField path="command" type="string" required>
|
||
要启动的可执行文件,可以是路径,也可以是 `PATH` 中的命令名。
|
||
</ParamField>
|
||
<ParamField path="args" type="string[]">
|
||
以 ACP 模式启动 agent 所需的参数。
|
||
</ParamField>
|
||
<ParamField path="env" type="table">
|
||
传给 agent 进程的额外环境变量。OpenIDEA 下次读取该文件时会把这些值移到系统凭据存储中,文件里只保留变量名(值为空)。从
|
||
ACP Registry 安装的 agent 会把其注册表条目设置的环境变量保留在文件中。
|
||
</ParamField>
|
||
<ParamField path="driver" type="string" default="acp">
|
||
ACP agent 用 `acp`;`claude` 和 `codex` 分别使用 Claude Code 和 Codex 的协议。
|
||
</ParamField>
|
||
|
||
文件名(去掉 `.toml`)就是 agent 的 ID。以内置 agent 命名的文件(`gemini.toml`、`claude.toml`…)会替换该 agent 的启动命令;在 **内置** 标签页中设置自定义可执行文件或环境变量时,写入的就是这个文件。无法解析的文件会被跳过并记录到日志。
|
||
|
||
## 限制
|
||
|
||
- agent 在你的电脑上运行,使用你自己的凭据、订阅或 API key;OpenIDEA 不做代理,也不计费。
|
||
- worktree 任务要求项目是至少有一次提交的 Git 仓库。
|