stippi/code-assistant

# 代码助手 [](https://github.com/stippi/code-assistant/actions/workflows/build.yml) [](https://archestra.ai/mcp-catalog/stippi__code-assistant) 一款用 Rust 编写的 AI 编程助手，提供命令行和图形界面，用于自主代码分析与修改。 ## 主要特性 **多模态工具执行**：支持可插拔的工具调用模式——原生函数调用、XML 风格标签和三重插入符模块——以适应不同的 LLM 能力，确保与各种 AI 提供商的兼容性。 **实时流式接口**：高级流式处理器能在工具调用从 LLM 流式输出时实时解析并显示，并具备智能过滤功能以防止不安全的工具组合。 **基于会话的项目管理**：每个聊天会话都与特定项目绑定，并维护持久化状态、工作记忆以及支持附件的草稿消息。 **多种界面选项**：可在基于 Zed 的 GPUI 框架构建的现代 GUI、传统终端界面或用于与 MCP 客户端（如 Claude Desktop）集成的无头 MCP 服务器模式中进行选择。 **代理客户端协议 (ACP) 支持**：完全兼容 [代理客户端协议](https://agentclientprotocol.com/) 标准，可与支持 ACP 的编辑器（如 [Zed](https://zed.dev)）无缝集成。设置说明请参阅 Zed 文档中的 [添加自定义代理](https://zed.dev/docs/ai/external-agents#add-custom-agents) 部分。 **会话压缩**：在上下文空间耗尽前，代理会生成会话摘要并继续工作。 **自动加载仓库指南**：自动将项目根目录下的 `AGENTS.md`（或备选的 `CLAUDE.md`）包含在助手的系统上下文中，以使行为与仓库特定指令保持一致。 ## 安装 ``` # 在 macOS 或 Linux 上，通过 rustup 安装 Rust 工具链： curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # 在 Linux 上，安装 libxkbcommon‑dev 和 libxkbcommon‑x11‑dev # 在 macOS 上，你需要 metal 工具链： xcodebuild -downloadComponent MetalToolchain # 然后克隆仓库并进行构建： git clone https://github.com/stippi/code-assistant cd code-assistant cargo build --release ``` 二进制文件将位于 `target/release/code-assistant`。 ### 初始设置 构建完成后，创建配置文件： ``` # 创建配置目录 mkdir -p ~/.config/code-assistant # 复制示例配置文件 cp providers.example.json ~/.config/code-assistant/providers.json cp models.example.json ~/.config/code-assistant/models.json # 编辑文件以添加你的 API 密钥 # 设置环境变量或直接更新 JSON 文件 export ANTHROPIC_API_KEY="sk-ant-..." export OPENAI_API_KEY="sk-..." ``` 详细设置说明请参阅 [配置](#configuration) 部分。 ## 项目配置 创建 `~/.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](docs/format-on-save-feature.md)。 **重要说明：** - 从非配置中的文件夹启动时，会自动创建一个临时项目 - 助手可以访问当前项目（包括临时项目）以及所有已配置的项目 - 每个聊天会话都永久关联其初始项目和文件夹——此关联后续无法更改 - 工具语法（原生/xml/插入符）在创建时也会为每个会话固定 ## 使用 ### GUI 模式（推荐） ``` # 通过图形界面启动 code-assistant --ui # 启动带有初始任务的 GUI code-assistant --ui --task "Analyze the authentication system" ``` ### 终端模式 ``` # 基本用法 code-assistant --task "Explain the purpose of this codebase" # 使用特定模型 code-assistant --task "Add error handling" --model "GPT-5" ``` ### 工作目录很重要 启动 `code-assistant` 的目录决定了会话的项目上下文。助手使用你的当前工作目录 (PWD) 来理解你正在处理的代码库——它将文件操作、搜索和工具执行限定在该目录范围内。 **最佳实践：** 启动 `code-assistant` 前，务必先 `cd` 进入项目的根目录。 ``` cd ~/workspace/my-project code-assistant --ui ``` 聊天记录按**目录分组**，因此从正确的项目目录开始新聊天可以确保： - 助手拥有正确的文件上下文并能导航你的代码库 - 你的对话历史按项目保持组织 - 自动加载该项目下的 `AGENTS.md` 或 `CLAUDE.md` 指南文件 如果你需要处理不同的项目，请从该项目目录开始新聊天，而不是重用另一个位置的现有会话。 ### MCP 服务器模式 ``` code-assistant server ``` ### ACP 代理模式 ``` # 作为兼容 ACP 的代理运行 code-assistant acp # 使用特定模型 code-assistant acp --model "Claude Sonnet 4.5" ``` ACP 模式支持与支持 [代理客户端协议](https://agentclientprotocol.com/) 的编辑器（如 [Zed](https://zed.dev)）集成。在 ACP 模式下运行时，code-assistant 通过 stdin/stdout 上的 JSON-RPC 进行通信，支持待处理消息、实时流式传输以及具备适当权限处理的工具执行等功能。 ## 配置 ### 模型配置 code-assistant 使用两个 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 密钥。 **完整示例**：包含所有支持提供商（Anthropic、OpenAI、Ollama、SAP AI Core、Vertex AI、Groq、Cerebras、MistralAI、OpenRouter）的完整配置示例，请参阅 [`providers.example.json`](providers.example.json) 和 [`models.example.json`](models.example.json)。 ### 工具配置 某些工具需要外部 API 密钥才能运行。在 `~/.config/code-assistant/tools.json` 中进行配置： ``` { "perplexity_api_key": "${PERPLEXITY_API_KEY}" } ``` **可用工具设置**： - `perplexity_api_key` - 启用 `perplexity_ask` 工具进行 AI 驱动的网络搜索 未配置所需设置的工具将无法供助手使用。 **列出可用模型**： ``` # 查看所有已配置的模型 code-assistant --list-models # 查看所有已配置的提供商 code-assistant --list-providers ```

Claude Desktop 集成 (MCP)

在 Claude Desktop 设置中配置（**开发者** 标签页 → **编辑配置**）： ``` { "mcpServers": { "code-assistant": { "command": "/path/to/code-assistant/target/release/code-assistant", "args": ["server"], "env": { "SHELL": "/bin/zsh" // Your login shell } } } } ```

Zed 编辑器集成 (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 文档中关于添加自定义代理的部分](https://zed.dev/docs/ai/external-agents#add-custom-agents)。

高级选项

**工具语法模式**： - `--tool-syntax native`：使用提供商的内置工具调用（最可靠，但参数流式传输取决于提供商） - `--tool-syntax xml`：用于参数流式传输的 XML 风格标签 - `--tool-syntax caret`：用于令牌效率和参数流式传输的三重插入符模块 **会话录制**： ``` # 记录会话（仅限 Anthropic） code-assistant --record session.json --model "Claude Sonnet 4.5" --task "Optimize database queries" # 回放会话 code-assistant --playback session.json --fast-playback ``` **其他选项**： - `--model `：从 models.json 指定模型（使用 `--list-models` 查看可用选项） - `--continue-task`：从先前的会话状态恢复 - `--use-diff-format`：为文件编辑启用替代 diff 格式 - `--sandbox-mode `：选择命令执行的沙盒策略（默认为 `danger-full-access`） - `--sandbox-network`：与 `--sandbox-mode workspace-write` 结合使用时，允许沙盒内出站网络访问 - `--verbose` / `-v`：启用详细日志记录（多次使用可增加详细程度）

## 架构亮点 code-assistant 采用了几项创新的架构决策： **自适应工具语法**：根据目标 LLM 的能力自动生成不同的系统提示和流式处理器，使相同的核心逻辑能够在不同函数调用支持的提供商之间工作。 **智能工具过滤**：实时分析工具调用模式，防止逻辑错误，例如在读取文件之前尝试编辑文件，并能在检测到不安全组合时中途截断响应。 **多线程流式传输**：复杂的异步架构，处理工具调用的实时解析，同时维持响应式 UI 更新和跨多个聊天会话的适当状态管理。 ## 贡献 欢迎贡献！代码库展示了异步 Rust、AI 代理架构和跨平台 UI 开发方面的高级模式。 ## 路线图 本部分并非真正的路线图，因为其中的事项没有特定顺序。 以下是可能作为下一个重点的一些主题： - **在已更改的文件中进行块替换**：当流式传输工具使用块时，我们已经知道 LLM 尝试使用 `replace_in_file` 并且我们很早就知道是哪个文件。如果我们还知道该文件自上次被 LLM 读取以来已更改，我们可以通过适当的错误消息阻止该尝试。 - **压缩工具使用失败**：当 LLM 产生无效的工具调用或不匹配的搜索块时，我们应该能够从消息历史中删除失败的尝试，节省令牌。 - **改进用户界面**：用户界面可以通过多种方式进行改进。 - **添加记忆工具**：添加便于构建对给定项目有用的知识库的工具。 - **安全性**：理想情况下，所有工具的执行都应在某种沙盒中运行，该沙盒限制对 git 跟踪的项目文件的访问。目前，工具会拒绝绝对路径，但不检查相对路径是否指向项目外部或尝试访问被 git 忽略的文件。`execute_command` 工具使用提供的命令行运行 shell，目前完全没有进行检查。 - **模糊匹配搜索块**：研究模糊匹配搜索块的好处。目前，文件会进行规范化处理（始终使用 `\n` 行结尾，无尾随空格）。这大大提高了搜索块匹配的成功率，但某些模糊匹配方式可能进一步提高成功率。失败的匹配会引入相当多的低效，因为它们几乎总是会触发 LLM 重新读取文件。即使 `replace_in_file` 工具的错误输出包含完整文件并告诉 LLM *不要* 重新读取文件。

标签：ACP协议, AI助手, DLL 劫持, MCP模式, Petitpotam, PMD, Rust语言, 上下文管理, 人工智能, 代码修改, 代码分析, 代码自动化, 会话管理, 凭证管理, 可视化界面, 命令行界面, 图形用户界面, 多模态工具执行, 大语言模型, 安全过滤, 实时流处理, 开发辅助, 用户模式Hook绕过, 编码助手, 自主代理, 通知系统