Code Assistant

代码助手

 

Rust内置的AI编码助手，为自主代码分析和修改提供命令行和图形界面。

主要特点

多模态刀具执行：通过可插拔的工具调用模式（本机函数调用、XML样式标签和三重插入符块）适应不同的LLM功能，确保跨各种AI提供者的兼容性。

实时流媒体接口：高级流处理器在工具调用从LLM流式传输时解析和显示工具调用，并使用智能过滤来防止不安全的工具组合。

基于会话的项目管理：每个聊天会话都与一个特定的项目相关联，并维护持久状态、工作记忆和带有附件支持的草稿消息。

多种接口选项：在基于Zed的GPUI框架构建的现代GUI、传统终端界面或无头MCP服务器模式之间进行选择，以与Claude Desktop等MCP客户端集成。

代理客户端协议（ACP）支持：与完全兼容 代理客户端协议 标准，实现与ACP兼容编辑器的无缝集成，如 泽德请参阅Zed的文档 添加自定义代理 有关设置说明。

会话压缩：在上下文空间用完之前，代理会生成会话摘要并继续工作。

自动加载存储库指南：自动包含 AGENTS.md （或 CLAUDE.md 回退），以使行为与特定于仓库的指令保持一致。

安装

# On macOS or Linux, install Rust tool chain via rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# On Linux, install libxkbcommon‑dev and libxkbcommon‑x11‑dev

# On macOS, you need the metal tool chain:
xcodebuild -downloadComponent MetalToolchain

# Then clone the repo and build it:
git clone https://github.com/stippi/code-assistant
cd code-assistant
cargo build --release

二进制文件将在 target/release/code-assistant.

初始设置

构建后，创建配置文件：

# Create config directory
mkdir -p ~/.config/code-assistant

# Copy example configurations
cp providers.example.json ~/.config/code-assistant/providers.json
cp models.example.json ~/.config/code-assistant/models.json

# Edit the files to add your API keys
# Set environment variables or update the JSON files directly
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

看 配置 有关详细设置说明的部分。

项目配置

创建 ~/.config/code-assistant/projects.json 定义可用项目：

{
  "code-assistant": {
    "path": "/Users//workspace/code-assistant",
    "format_on_save": {
      "**/*.rs": "cargo fmt" // Formats all files in project, so make sure files are already formatted
    }
  },
  "my-project": {
    "path": "/Users//workspace/my-project",
    "format_on_save": {
      "**/*.ts": "prettier --write {path}" // If the formatter accepts a path, provide "{path}"
    }
  }
}

保存功能上的格式

这 _可选的_ format_on_save 字段允许修改后自动格式化文件。它将文件模式（使用glob语法）映射到shell命令：

• 与glob模式匹配的文件在助手修改后将自动格式化
• 更新工具参数以反映格式化内容，使LLM的心理模型保持同步
• 这可以防止自动格式化引起的编辑冲突

看 docs/format-on-save-feature.md 详细文档。

重要提示：

• 从不在此配置中的文件夹启动时，会自动创建一个临时项目
• 助理可以访问当前项目（包括临时项目）以及所有已配置的项目
• 每个聊天会话都与其初始项目和文件夹永久关联，以后无法更改
• 在创建时，每个会话的工具语法（native/xml/caret）也是固定的

用法

GUI模式（推荐）

# Start with graphical interface
code-assistant --ui

# Start GUI with initial task
code-assistant --ui --task "Analyze the authentication system"

终端模式

# Basic usage
code-assistant --task "Explain the purpose of this codebase"

# With specific model
code-assistant --task "Add error handling" --model "GPT-5"

工作目录很重要

您启动的目录 code-assistant 确定会话的项目上下文。助手使用您当前的工作目录（PWD）来了解您正在处理的代码库——它将文件操作、搜索和工具执行范围限定在该目录中。

最佳实践： 总是 cd 在开始之前，将其放入项目的根目录 code-assistant.

cd ~/workspace/my-project
code-assistant --ui

聊天是 按目录分组，因此从正确的项目目录启动新聊天可确保：

• 助手具有正确的文件上下文，可以浏览您的代码库
• 您的对话历史记录按项目保持有序
• AGENTS.md 或 CLAUDE.md 该项目中的指导文件将自动加载

如果你需要处理另一个项目，请从该项目的目录中打开一个新的聊天，而不是从另一个位置重用现有的会话。

MCP服务器模式

code-assistant server

ACP代理模式

# Run as ACP-compatible agent
code-assistant acp

# With specific model
code-assistant acp --model "Claude Sonnet 4.5"

ACP模式允许与支持以下功能的编辑器集成 代理客户端协议，例如 泽德在ACP模式下运行时，代码助手通过JSON-RPC在stdin/stdout上进行通信，支持挂起消息、实时流和具有适当权限处理的工具执行等功能。

配置

模型配置

代码助手使用两个JSON配置文件来管理LLM提供程序和模型：

~/.config/code-assistant/providers.json -配置提供程序凭据和终结点：

{
  "anthropic": {
    "label": "Anthropic Claude",
    "provider": "anthropic",
    "config": {
      "api_key": "${ANTHROPIC_API_KEY}",
      "base_url": "https://api.anthropic.com/v1"
    }
  },
  "openai": {
    "label": "OpenAI",
    "provider": "openai-responses",
    "config": {
      "api_key": "${OPENAI_API_KEY}"
    }
  }
}

~/.config/code-assistant/models.json -定义可用模型：

{
  "Claude Sonnet 4.5 (Thinking)": {
    "provider": "anthropic",
    "id": "claude-sonnet-4-5",
    "config": {
      "max_tokens": 32768,
      "thinking": {
        "type": "enabled",
        "budget_tokens": 8192
      }
    }
  },
  "Claude Sonnet 4.5": {
    "provider": "anthropic",
    "id": "claude-sonnet-4-5",
    "config": {
      "max_tokens": 32768
    }
  },
  "GPT-5": {
    "provider": "openai",
    "id": "gpt-5-codex",
    "config": {
      "temperature": 0.7
    }
  }
}

环境变量替换：使用 ${VAR_NAME} 在提供程序配置中引用API键的环境变量。

完整示例：参见 providers.example.json 和 models.example.json 查看所有支持的提供商（Anthropic、OpenAI、Ollama、SAP AI Core、Vertex AI、Groq、Cerebras、MistralAI、OpenRouter）的完整配置示例。

工具配置

有些工具需要外部API键才能运行。在中配置这些 ~/.config/code-assistant/tools.json:

{
  "perplexity_api_key": "${PERPLEXITY_API_KEY}"
}

可用工具设置:

• perplexity_api_key -启用 perplexity_ask 基于人工智能的网络搜索工具

助手将无法使用没有所需配置的工具。

列出可用型号:

# See all configured models
code-assistant --list-models

# See all configured providers
code-assistant --list-providers

Claude Desktop Integration (MCP)

在Claude Desktop设置中配置(开发者 tab → 编辑配置):

{
  "mcpServers": {
    "code-assistant": {
      "command": "/path/to/code-assistant/target/release/code-assistant",
      "args": ["server"],
      "env": {
        "SHELL": "/bin/zsh"                 // Your login shell
      }
    }
  }
}

Zed Editor Integration (ACP)

在Zed设置中配置：

{
  "agent_servers": {
    "Code-Assistant": {
      "command": "/path/to/code-assistant/target/release/code-assistant",
      "args": ["acp", "--model", "Claude Sonnet 4.5"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

确保你的 providers.json 和 models.json 使用您指定的模型进行配置。该特工将出现在Zed的助理小组中，并得到ACP的全力支持。

有关详细的设置说明，请参阅 Zed关于添加定制代理的文档.

Advanced Options

工具语法模式:

• --tool-syntax native：使用提供者的内置工具调用（最可靠，但参数流取决于提供者）
• --tool-syntax xml：用于参数流式传输的XML样式标记
• --tool-syntax caret：三重插入块，提高令牌效率和参数流

会话录制:

# Record session (Anthropic only)
code-assistant --record session.json --model "Claude Sonnet 4.5" --task "Optimize database queries"

# Playback session
code-assistant --playback session.json --fast-playback

其他选项:

• --model ：从models.json中指定模型（使用 --list-models 查看可用选项）
• --continue-task：从上一个会话状态恢复
• --use-diff-format：为文件编辑启用其他差异格式
• --sandbox-mode ：选择命令执行的沙盒策略（默认 danger-full-access)
• --sandbox-network：当与 --sandbox-mode workspace-write，允许出站网络访问-在沙盒内
• --verbose / -v：启用详细日志记录（多次使用以获得更多详细信息）

建筑亮点

代码助手具有几个创新的架构决策：

自适应工具语法：根据目标LLM的功能自动生成不同的系统提示和流处理器，允许相同的核心逻辑在具有不同函数调用支持的提供商之间工作。

智能工具过滤：对工具调用模式的实时分析可以防止在读取文件之前尝试编辑文件等逻辑错误，并能够在检测到不安全组合时截断中途的响应。

多线程流媒体：复杂的异步架构，处理工具调用的实时解析，同时在多个聊天会话中保持响应式UI更新和适当的状态管理。

贡献

欢迎投稿！该代码库展示了异步Rust、AI代理架构和跨平台UI开发中的高级模式。

路线图

本节并不是一个真正的路线图，因为这些项目没有特别的顺序。 以下是一些可能成为下一个焦点的话题。

• 更改文件中的块替换：在流式传输工具使用块时，我们已经知道LLM试图使用 replace_in_file 我们很早就知道是哪个文件。

如果我们还知道此文件自LLM上次读取以来已更改，我们可以通过适当的错误消息阻止该尝试。

• 紧凑型工具使用故障：当LLM生成无效的工具调用或不匹配的搜索块时，我们应该能够从消息历史中删除失败的尝试，从而节省令牌。
• 改进UI：用户界面可以通过多种方式进行改进。
• 添加内存工具：添加有助于建立知识库的工具，在特定项目中开展有用的工作。
• 安全：理想情况下，所有工具的执行都将在某种沙盒中运行，该沙盒限制了对git跟踪的项目中文件的访问。

目前，这些工具拒绝绝对路径，但不会检查相对路径是否指向项目外部，也不会尝试访问git忽略的文件。 这 execute_command 该工具使用提供的命令行运行shell，目前完全未选中该命令行。

• 模糊匹配搜索块：调查模糊匹配搜索块的好处。

目前，文件已标准化（始终 \n 行尾，无尾随空格）。 这大大提高了匹配搜索块的成功率，但某些模糊匹配的方法可能会进一步提高成功率。 失败的匹配会带来相当低的效率，因为它们几乎总是触发LLM重新读取文件。 即使错误输出 replace_in_file 工具包括完整的文件，并告诉LLM *不* 重新读取文件。