Skip to main content

ACP 使用教程

本教程将指导你如何在 AutoDev 中使用 ACP 代理进行日常开发工作。

基础使用​

1. 连接到代理​

方式 A: 自动连接​

如果已配置默认代理，打开 ACP 面板即可自动连接：

  1. 打开 IntelliJ IDEA
  2. 打开 AutoDev 工具窗口（通常在右侧或底部）
  3. 切换到 ACP 标签
  4. 代理会自动连接（显示为"已连接"状态）

方式 B: 手动选择​

  1. 在 ACP 面板中，点击代理下拉列表
  2. 选择想要使用的代理（如 "OpenCode"）
  3. 点击 连接 按钮
  4. 等待连接成功（通常 2-5 秒）

2. 发送提示​

连接成功后，在输入框中输入你的问题或任务：

基础示例：
- 解释这个函数的功能
- 这段代码有什么问题？
- 如何优化这个算法？

按 Enter 或点击发送按钮提交。

3. 查看响应​

代理的响应会实时显示在聊天区域，包括：

  • 💭 思考过程: 代理的分析思路
  • 🔧 工具调用: 代理执行的操作（读取文件、运行命令等）
  • 💬 回复内容: 最终的答案或建议
  • ✅ 完成状态: 任务完成情况

常见使用场景​

场景 1: 代码解释​

任务: 理解复杂代码

示例提示:

@文件名.kt 这个文件的主要功能是什么？
它如何与其他模块交互？

代理操作:

  1. 读取指定文件
  2. 分析代码结构
  3. 解释主要逻辑
  4. 指出关键交互点

场景 2: Bug 调试​

任务: 找出代码问题

示例提示:

这段代码在并发情况下会有问题吗？

@IdeaAcpAgentViewModel.kt:260-280

代理操作:

  1. 读取指定代码段
  2. 分析并发安全性
  3. 指出潜在的竞态条件
  4. 提供修复建议

场景 3: 代码重构​

任务: 改进代码质量

示例提示:

重构这个函数以提高可读性和可维护性：

@parseEnvLines

代理操作:

  1. 读取函数代码
  2. 识别可改进点
  3. 提供重构方案
  4. 可能直接修改代码（需要权限确认）

场景 4: 测试生成​

任务: 创建单元测试

示例提示:

为 IdeaAcpAgentPreset 类生成完整的单元测试，
包括边界情况和异常处理

代理操作:

  1. 读取类定义
  2. 分析公共方法
  3. 生成测试用例
  4. 创建测试文件（需要权限确认）

场景 5: 文档生成​

任务: 生成 API 文档

示例提示:

为 AcpAgentProcessManager 类生成详细的 KDoc 文档，
包括使用示例

代理操作:

  1. 读取类代码
  2. 分析方法签名
  3. 生成文档注释
  4. 添加使用示例

场景 6: 代码搜索​

任务: 在项目中查找特定模式

示例提示:

找出项目中所有使用 coroutineScope.launch 的地方，
并检查是否正确处理了异常

代理操作:

  1. 搜索代码库
  2. 分析每个使用位置
  3. 检查异常处理
  4. 提供改进建议

高级技巧​

1. 使用 @ 引用​

引用文件​

@src/main/kotlin/MyClass.kt 这个文件的设计模式是什么？

引用特定行​

@MyClass.kt:100-150 这段代码可以简化吗？

引用多个文件​

比较以下两个文件的实现差异：
@FileA.kt
@FileB.kt

2. 多轮对话​

代理会记住对话上下文，支持连续交互：

第一轮：
用户: "分析这个函数的时间复杂度"
代理: "这个函数的时间复杂度是 O(n²)，主要是因为嵌套循环..."

第二轮：
用户: "如何优化到 O(n)？"
代理: "可以使用哈希表来优化，具体方法是..."

第三轮：
用户: "帮我实现这个优化"
代理: [修改代码]

3. 组合命令​

结合多个任务：

请完成以下任务：
1. 分析 @UserService.kt 的代码质量
2. 找出潜在的性能问题
3. 生成优化方案
4. 为关键方法添加单元测试

4. 使用项目上下文​

代理会自动了解项目结构：

根据项目的现有架构，
为用户模块添加一个新的权限管理功能

5. 请求特定格式​

指定输出格式：

以 Markdown 表格形式列出这个类的所有方法及其用途

权限管理​

权限类型​

代理可能请求以下权限：

操作类型示例风险级别
读取文件查看代码低
写入文件修改代码中
执行命令运行测试高
删除文件清理临时文件高

权限选项​

当代理请求权限时，你可以选择：

  • Allow Once: 仅允许此次操作
  • Allow Always: 始终允许此类操作（此会话内）
  • Reject Once: 拒绝此次操作
  • Reject Always: 始终拒绝此类操作

推荐策略​

✅ 读取文件: Allow Always
✅ 写入文件: Allow Once (仔细审查后可改为 Always)
⚠️  执行命令: Allow Once (每次审查)
❌ 删除文件: 仔细审查，必要时 Allow Once

撤销权限​

如果误操作：

  1. 断开并重新连接代理
  2. 或重启 IDE
  3. 权限设置不会持久化到下次会话

性能优化​

1. 预热连接​

首次连接后，代理进程保持活动状态，后续使用更快：

首次连接: 3-5 秒
后续使用: < 1 秒

2. 限制上下文大小​

对于大型项目，精确指定范围：

❌ 不推荐: "分析整个项目的代码质量"
✅ 推荐: "分析 src/main/kotlin/agent/ 目录的代码质量"

3. 使用增量查询​

将大任务分解为小步骤：

第一步: "分析当前文件的主要功能"
第二步: "找出最复杂的方法"
第三步: "重构该方法"

4. 清理会话​

长时间使用后，断开重连以清理上下文：

// 在 UI 中点击 "断开连接" 然后重新连接

调试技巧​

查看详细日志​

  1. 启用详细日志：

    • Help → Diagnostic Tools → Debug Log Settings
    • 添加: #cc.unitmesh.devins.idea.toolwindow.acp

  2. 查看日志：

    tail -f ~/.autodev/logs/autodev-app.log

检查进程状态​

# 查看 ACP 代理进程
ps aux | grep opencode

# 检查端口占用（如果使用网络通信）
lsof -i :9999

测试 ACP 协议​

# 手动测试代理响应
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}' | opencode acp

查看 stderr 输出​

在 ACP 面板底部可以看到代理的 stderr 输出，包含：

  • 启动信息
  • 错误消息
  • 调试日志

最佳实践​

1. 提示词编写​

清晰具体:

❌ "改进这个"
✅ "重构 UserService.kt 中的 validateUser 方法，提取重复逻辑到单独的函数"

提供上下文:

❌ "修复这个 bug"
✅ "修复 UserService.kt:150 的 NullPointerException，
   当 user.profile 为 null 时发生"

分步骤:

❌ "完全重构这个模块"
✅ "先分析模块结构，然后提出重构方案，最后逐个文件实施"

2. 代码审查工作流​

1. 打开需要审查的文件
2. 向代理提问: "审查这个文件，关注安全性、性能和可维护性"
3. 代理提供分析报告
4. 针对具体问题继续提问
5. 让代理提供修复建议或直接修改

3. 学习新代码库​

1. "概述这个项目的架构"
2. "核心模块有哪些？它们如何交互？"
3. "带我了解用户认证的实现"
4. "这个项目使用了哪些设计模式？"

4. 增量开发​

1. "为用户管理创建基本的领域模型"
2. "添加数据访问层"
3. "实现业务逻辑"
4. "添加 API 端点"
5. "生成单元测试"

故障排除​

问题 1: 代理无响应​

症状: 发送消息后没有任何反应

解决方案:

  1. 检查连接状态（右上角指示器）
  2. 查看 stderr 输出是否有错误
  3. 断开重连
  4. 检查代理进程是否正在运行

问题 2: 响应中断​

症状: 代理响应到一半停止

解决方案:

  1. 检查是否超时（默认 60 秒）
  2. 简化提示，减少工作量
  3. 检查网络连接（如果使用远程代理）
  4. 查看日志了解详细错误

问题 3: 权限对话框未显示​

症状: 代理似乎卡住，没有弹出权限请求

解决方案:

  1. 检查是否有其他模态对话框遮挡
  2. 重启 IDE
  3. 检查日志是否有异常
  4. 尝试使用其他代理

问题 4: 代理不理解上下文​

症状: 代理给出不相关的答案

解决方案:

  1. 使用 @ 显式引用文件
  2. 提供更多背景信息
  3. 分解任务为更小的步骤
  4. 断开重连以清除混乱的上下文

快捷键（可配置）​

操作默认快捷键说明
发送消息Enter提交当前输入
换行Shift+Enter在输入框中换行
取消任务Esc停止当前代理任务
打开 ACP 面板自定义在设置中配置

与其他功能集成​

与 DevIns 集成​

在 DevIns 脚本中调用 ACP 代理：

/acp opencode "分析当前文件的复杂度"

与 MCP 集成​

ACP 代理自动使用配置的 MCP 服务器：

mcpServers:
  github:
    command: "npx"
    args: "@modelcontextprotocol/server-github"

代理可以直接访问 GitHub 数据。

与 Bridge 集成​

通过 Bridge 使用远程 ACP 代理：

acpAgents:
  "remote-opencode":
    name: "Remote OpenCode"
    url: "https://ai.company.com/acp"

下一步​