1081 lines
34 KiB
Markdown
1081 lines
34 KiB
Markdown
# Agent 配置入参功能实现计划
|
||
|
||
## 1. 需求概述
|
||
|
||
### 1.1 功能目标
|
||
为 `/chat` 接口增加三个可选配置入参，允许用户自定义 Agent 的提示词和配置：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `system_prompt` | `Option<String>` | 系统提示词，可选 |
|
||
| `user_prompt` | `Option<String>` | 用户提示词模板，可选 |
|
||
| `agent_config` | `Option<ChatAgentConfig>` | Agent 运行时配置（MCP 服务器等），可选 |
|
||
|
||
### 1.2 设计原则：职责分离，无冲突
|
||
|
||
**提示词由独立入参控制，`agent_config` 只负责运行时配置**：
|
||
|
||
- `system_prompt`：直接传入系统提示词文本
|
||
- `user_prompt`：直接传入用户提示词模板（支持 `{user_prompt}` 变量）
|
||
- `agent_config`：只包含 MCP 服务器等运行时配置，**不包含提示词配置**
|
||
|
||
这样设计的优势：
|
||
1. **消除歧义**：用户不会困惑"到底用哪个提示词"
|
||
2. **简化代码**：不需要复杂的优先级合并逻辑
|
||
3. **职责清晰**：提示词归提示词，配置归配置
|
||
|
||
### 1.3 变量注入
|
||
`user_prompt` 支持模板变量 `{user_prompt}`，运行时用 `/chat` 的 `prompt` 字段值替换
|
||
|
||
### 1.4 配置生效逻辑
|
||
|
||
```
|
||
用户入参 内部组装
|
||
───────────────────────────────────────────────────────────────────
|
||
system_prompt ────────────────────────→ AgentStartConfig.system_prompt
|
||
user_prompt ──────────────────────────→ 模板替换后的最终 prompt
|
||
agent_config.agent_server ────────────→ AgentConfig (合并覆盖默认配置)
|
||
agent_config.context_servers ─────────→ AgentStartConfig.mcp_servers
|
||
|
||
（如果入参为空，使用默认配置）
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 新增数据结构定义
|
||
|
||
### 2.1 结构对比：内部配置 vs 外部入参
|
||
|
||
| 内部配置 (AgentServersConfig) | 外部入参 (ChatAgentConfig) | 说明 |
|
||
|-------------------------------|----------------------------|------|
|
||
| `agent_servers: HashMap<String, AgentConfig>` | `agent_server: Option<ChatAgentServerConfig>` | 内部支持多 Agent，外部只需单个 |
|
||
| `context_servers: HashMap<String, ContextServerConfig>` | `context_servers: HashMap<String, ChatContextServerConfig>` | MCP 工具可以有多个，保持一致 |
|
||
|
||
### 2.2 ChatAgentConfig 结构体
|
||
|
||
**位置**: `crates/shared_types/src/chat_agent_config.rs` (新文件)
|
||
|
||
```rust
|
||
//! Chat 接口专用的 Agent 配置结构体
|
||
//!
|
||
//! 简化版本，只包含运行时配置，不包含提示词配置。
|
||
//! 提示词由独立的 system_prompt 和 user_prompt 入参控制。
|
||
|
||
use serde::{Deserialize, Serialize};
|
||
use std::collections::HashMap;
|
||
use utoipa::ToSchema;
|
||
|
||
/// Chat 接口的 Agent 配置
|
||
///
|
||
/// 包含单个 Agent 的运行时配置和多个 MCP 服务器配置。
|
||
/// 提示词由独立入参 (system_prompt, user_prompt) 控制，不在此结构中。
|
||
#[derive(Debug, Clone, Serialize, Deserialize, Default, ToSchema)]
|
||
pub struct ChatAgentConfig {
|
||
/// 单个 Agent 服务器配置（可选）
|
||
///
|
||
/// 用于覆盖默认的 Agent 执行命令、参数、环境变量等。
|
||
/// 如果不传，使用内部默认配置 (claude-code-acp)。
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub agent_server: Option<ChatAgentServerConfig>,
|
||
|
||
/// MCP 服务器配置（Context Servers）
|
||
///
|
||
/// 可配置多个 MCP 工具服务器。
|
||
/// 如果不传，使用内部默认的 MCP 配置。
|
||
#[serde(default, skip_serializing_if = "HashMap::is_empty")]
|
||
pub context_servers: HashMap<String, ChatContextServerConfig>,
|
||
}
|
||
|
||
/// 单个 Agent 服务器配置
|
||
///
|
||
/// 对应内部 AgentConfig 的简化版本，只暴露必要的运行时配置。
|
||
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
|
||
pub struct ChatAgentServerConfig {
|
||
/// Agent 标识符（可选，默认使用 "claude-code-acp"）
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub agent_id: Option<String>,
|
||
|
||
/// 执行命令（如 "claude-code-acp", "custom-agent"）
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub command: Option<String>,
|
||
|
||
/// 命令参数
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub args: Option<Vec<String>>,
|
||
|
||
/// 环境变量
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub env: Option<HashMap<String, String>>,
|
||
|
||
/// 元数据（可选）
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub metadata: Option<HashMap<String, String>>,
|
||
}
|
||
|
||
/// MCP 服务器配置
|
||
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
|
||
pub struct ChatContextServerConfig {
|
||
/// 服务器来源类型: "custom" 或 "local"
|
||
#[serde(default = "default_custom")]
|
||
pub source: String,
|
||
|
||
/// 是否启用
|
||
#[serde(default = "default_true")]
|
||
pub enabled: bool,
|
||
|
||
/// 执行命令 (如 "bunx", "uvx", "npx")
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub command: Option<String>,
|
||
|
||
/// 命令参数
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub args: Option<Vec<String>>,
|
||
|
||
/// 环境变量
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub env: Option<HashMap<String, String>>,
|
||
}
|
||
|
||
fn default_custom() -> String {
|
||
"custom".to_string()
|
||
}
|
||
|
||
fn default_true() -> bool {
|
||
true
|
||
}
|
||
|
||
impl Default for ChatAgentServerConfig {
|
||
fn default() -> Self {
|
||
Self {
|
||
agent_id: None,
|
||
command: None,
|
||
args: None,
|
||
env: None,
|
||
metadata: None,
|
||
}
|
||
}
|
||
}
|
||
|
||
impl Default for ChatContextServerConfig {
|
||
fn default() -> Self {
|
||
Self {
|
||
source: "custom".to_string(),
|
||
enabled: true,
|
||
command: None,
|
||
args: None,
|
||
env: None,
|
||
}
|
||
}
|
||
}
|
||
|
||
impl ChatAgentConfig {
|
||
/// 检查是否有 Agent 服务器配置
|
||
pub fn has_agent_server(&self) -> bool {
|
||
self.agent_server.is_some()
|
||
}
|
||
|
||
/// 检查是否有 MCP 服务器配置
|
||
pub fn has_context_servers(&self) -> bool {
|
||
!self.context_servers.is_empty()
|
||
}
|
||
|
||
/// 获取启用的 MCP 服务器
|
||
pub fn get_enabled_context_servers(&self) -> HashMap<String, &ChatContextServerConfig> {
|
||
self.context_servers
|
||
.iter()
|
||
.filter(|(_, config)| config.enabled)
|
||
.map(|(name, config)| (name.clone(), config))
|
||
.collect()
|
||
}
|
||
}
|
||
|
||
impl ChatAgentServerConfig {
|
||
/// 获取 Agent ID，默认返回 "claude-code-acp"
|
||
pub fn get_agent_id(&self) -> &str {
|
||
self.agent_id.as_deref().unwrap_or("claude-code-acp")
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.3 JSON 请求示例（完整配置）
|
||
|
||
```json
|
||
{
|
||
"prompt": "帮我写一个 Hello World",
|
||
"project_id": "my_project",
|
||
"system_prompt": "你是一个专业的 Rust 开发者，擅长编写高性能代码",
|
||
"user_prompt": "请用 Rust 语言完成以下需求：{user_prompt}",
|
||
"agent_config": {
|
||
"agent_server": {
|
||
"agent_id": "claude-code-acp",
|
||
"command": "claude-code-acp",
|
||
"args": [],
|
||
"env": {
|
||
"ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
|
||
"RUST_LOG": "debug"
|
||
}
|
||
},
|
||
"context_servers": {
|
||
"context7": {
|
||
"source": "custom",
|
||
"enabled": true,
|
||
"command": "bunx",
|
||
"args": ["-y", "@upstash/context7-mcp"]
|
||
},
|
||
"fetch": {
|
||
"source": "custom",
|
||
"enabled": true,
|
||
"command": "uvx",
|
||
"args": ["mcp-server-fetch"]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.4 JSON 请求示例（只配置 MCP）
|
||
|
||
```json
|
||
{
|
||
"prompt": "帮我写一个 Hello World",
|
||
"system_prompt": "你是 Rust 专家",
|
||
"agent_config": {
|
||
"context_servers": {
|
||
"context7": {
|
||
"enabled": true,
|
||
"command": "bunx",
|
||
"args": ["-y", "@upstash/context7-mcp"]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.5 最简请求示例
|
||
|
||
```json
|
||
{
|
||
"prompt": "帮我写一个 Hello World",
|
||
"system_prompt": "你是 Rust 专家"
|
||
}
|
||
```
|
||
|
||
> **说明**: 不传 `agent_config` 时，使用默认的 Agent 和 MCP 服务器配置。
|
||
|
||
---
|
||
|
||
## 3. 现有架构分析
|
||
|
||
### 3.1 数据流路径
|
||
```
|
||
HTTP /chat (rcoder)
|
||
↓
|
||
gRPC ChatRequest (shared_types)
|
||
↓
|
||
agent_runner gRPC AgentServiceImpl
|
||
↓
|
||
ChatPromptBuilder → PromptMessage
|
||
↓
|
||
AcpAgentWorker → AcpSessionManager
|
||
↓
|
||
ClaudeCodeLauncher (agent_abstraction)
|
||
↓
|
||
NewSessionRequest._meta.systemPrompt (ACP协议)
|
||
```
|
||
|
||
### 3.2 关键文件和结构体
|
||
|
||
| 文件 | 结构体/模块 | 作用 |
|
||
|------|-------------|------|
|
||
| `crates/rcoder/src/handler/chat_handler.rs` | `ChatRequest` | HTTP 请求结构体 |
|
||
| `crates/shared_types/proto/agent.proto` | `ChatRequest` | gRPC 请求定义 |
|
||
| `crates/agent_runner/src/grpc/agent_service_impl.rs` | `AgentServiceImpl::chat()` | gRPC 服务实现 |
|
||
| `crates/agent_config/src/config/servers_config.rs` | `AgentServersConfig` | Agent 配置集合 |
|
||
| `crates/agent_abstraction/src/traits/agent.rs` | `AgentStartConfig` | Agent 启动配置 |
|
||
| `crates/agent_abstraction/src/compat/claude_code_launcher.rs` | `ClaudeCodeLauncher` | Agent 启动器 |
|
||
|
||
### 3.3 现有默认配置结构
|
||
|
||
**AgentServersConfig** (默认 JSON 配置):
|
||
```json
|
||
{
|
||
"agent_servers": {
|
||
"claude-code-acp": {
|
||
"agent_id": "claude-code-acp",
|
||
"system_prompt": {
|
||
"source": "embedded",
|
||
"template": "",
|
||
"enabled": true
|
||
},
|
||
"user_prompt": {
|
||
"template": "{user_prompt}",
|
||
"enabled": false
|
||
}
|
||
}
|
||
},
|
||
"context_servers": {
|
||
"context7": { ... },
|
||
"fetch": { ... }
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 详细实现计划
|
||
|
||
### 4.1 阶段一：新增 ChatAgentConfig 结构体
|
||
|
||
#### 4.1.1 创建新文件
|
||
|
||
**文件**: `crates/shared_types/src/chat_agent_config.rs`
|
||
|
||
内容见上文 **2.1 节**。
|
||
|
||
#### 4.1.2 导出新类型
|
||
|
||
**文件**: `crates/shared_types/src/lib.rs`
|
||
|
||
```rust
|
||
mod chat_agent_config;
|
||
pub use chat_agent_config::*;
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 阶段二：修改 HTTP/gRPC 请求结构
|
||
|
||
#### 4.2.1 修改 rcoder ChatRequest (HTTP)
|
||
|
||
**文件**: `crates/rcoder/src/handler/chat_handler.rs`
|
||
|
||
```rust
|
||
use shared_types::ChatAgentConfig;
|
||
|
||
#[derive(Debug, Deserialize, Serialize, Clone, ToSchema)]
|
||
pub struct ChatRequest {
|
||
// ... 现有字段 ...
|
||
|
||
/// 可选的系统提示词，覆盖默认配置
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
#[schema(example = "你是一个专业的 Rust 开发者")]
|
||
pub system_prompt: Option<String>,
|
||
|
||
/// 可选的用户提示词模板，支持 {user_prompt} 变量替换
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
#[schema(example = "请用 Rust 完成：{user_prompt}")]
|
||
pub user_prompt: Option<String>,
|
||
|
||
/// 可选的 Agent 运行时配置（MCP 服务器等）
|
||
#[serde(default, skip_serializing_if = "Option::is_none")]
|
||
pub agent_config: Option<ChatAgentConfig>,
|
||
}
|
||
```
|
||
|
||
#### 4.2.2 修改 gRPC ChatRequest
|
||
|
||
**文件**: `crates/shared_types/proto/agent.proto`
|
||
|
||
```protobuf
|
||
message ChatRequest {
|
||
string project_id = 1;
|
||
string session_id = 2;
|
||
string prompt = 3;
|
||
optional ModelProviderConfig model_config = 4;
|
||
repeated Attachment attachments = 5;
|
||
optional string request_id = 6;
|
||
repeated string data_source_attachments = 7;
|
||
|
||
// 新增字段
|
||
optional string system_prompt = 8; // 系统提示词
|
||
optional string user_prompt = 9; // 用户提示词模板
|
||
optional ChatAgentConfig agent_config = 10; // Agent 运行时配置
|
||
}
|
||
|
||
// Agent 运行时配置
|
||
message ChatAgentConfig {
|
||
optional ChatAgentServerConfig agent_server = 1; // 单个 Agent 配置
|
||
map<string, ChatContextServerConfig> context_servers = 2; // 多个 MCP 配置
|
||
}
|
||
|
||
// 单个 Agent 服务器配置
|
||
message ChatAgentServerConfig {
|
||
optional string agent_id = 1; // Agent 标识符
|
||
optional string command = 2; // 执行命令
|
||
repeated string args = 3; // 命令参数
|
||
map<string, string> env = 4; // 环境变量
|
||
map<string, string> metadata = 5; // 元数据
|
||
}
|
||
|
||
// MCP 服务器配置
|
||
message ChatContextServerConfig {
|
||
string source = 1; // "custom" 或 "local"
|
||
bool enabled = 2;
|
||
optional string command = 3;
|
||
repeated string args = 4;
|
||
map<string, string> env = 5;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.3 阶段三：修改 shared_types 数据结构
|
||
|
||
#### 4.3.1 修改 ChatPrompt
|
||
|
||
**文件**: `crates/shared_types/src/lib.rs`
|
||
|
||
```rust
|
||
use crate::ChatAgentConfig;
|
||
|
||
#[derive(Debug, Clone, Builder)]
|
||
pub struct ChatPrompt {
|
||
// ... 现有字段 ...
|
||
|
||
/// 可选的系统提示词覆盖
|
||
#[builder(default)]
|
||
pub system_prompt_override: Option<String>,
|
||
|
||
/// 可选的用户提示词模板覆盖
|
||
#[builder(default)]
|
||
pub user_prompt_template_override: Option<String>,
|
||
|
||
/// 可选的 Agent 运行时配置覆盖
|
||
#[builder(default)]
|
||
pub agent_config_override: Option<ChatAgentConfig>,
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.4 阶段四：修改 agent_abstraction 层
|
||
|
||
#### 4.4.1 修改 PromptMessage
|
||
|
||
**文件**: `crates/agent_abstraction/src/traits/agent.rs`
|
||
|
||
```rust
|
||
use shared_types::ChatAgentConfig;
|
||
|
||
#[derive(Debug, Clone)]
|
||
pub struct PromptMessage {
|
||
// ... 现有字段 ...
|
||
|
||
/// 系统提示词覆盖
|
||
pub system_prompt_override: Option<String>,
|
||
|
||
/// 用户提示词模板覆盖
|
||
pub user_prompt_template_override: Option<String>,
|
||
|
||
/// Agent 运行时配置覆盖（MCP 服务器等）
|
||
pub agent_config_override: Option<ChatAgentConfig>,
|
||
}
|
||
```
|
||
|
||
#### 4.4.2 修改 From<ChatPrompt> 实现
|
||
|
||
```rust
|
||
impl From<shared_types::ChatPrompt> for PromptMessage {
|
||
fn from(chat_prompt: shared_types::ChatPrompt) -> Self {
|
||
Self {
|
||
// ... 现有字段映射 ...
|
||
system_prompt_override: chat_prompt.system_prompt_override,
|
||
user_prompt_template_override: chat_prompt.user_prompt_template_override,
|
||
agent_config_override: chat_prompt.agent_config_override,
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.5 阶段五：新增配置组装工具
|
||
|
||
#### 4.5.1 新增 PromptConfigAssembler
|
||
|
||
**文件**: `crates/agent_config/src/config/prompt_assembler.rs` (新文件)
|
||
|
||
```rust
|
||
//! 提示词配置组装工具
|
||
//!
|
||
//! 将用户入参组装为内部使用的配置结构。
|
||
//! 简化设计：直接使用入参，无优先级冲突。
|
||
|
||
use shared_types::{ChatAgentConfig, ChatAgentServerConfig};
|
||
use super::servers_config::AgentServersConfig;
|
||
use crate::{AgentConfig, ContextServerConfig};
|
||
use std::collections::HashMap;
|
||
|
||
/// 提示词配置组装器
|
||
///
|
||
/// 职责：
|
||
/// 1. 组装系统提示词（入参 > 默认配置）
|
||
/// 2. 应用用户提示词模板
|
||
/// 3. 组装 Agent 服务器配置
|
||
/// 4. 合并 MCP 服务器配置
|
||
pub struct PromptConfigAssembler {
|
||
/// 系统提示词入参
|
||
system_prompt: Option<String>,
|
||
/// 用户提示词模板入参
|
||
user_prompt_template: Option<String>,
|
||
/// Agent 运行时配置入参
|
||
agent_config: Option<ChatAgentConfig>,
|
||
/// 默认配置
|
||
default_config: AgentServersConfig,
|
||
}
|
||
|
||
impl PromptConfigAssembler {
|
||
pub fn new(default_config: AgentServersConfig) -> Self {
|
||
Self {
|
||
system_prompt: None,
|
||
user_prompt_template: None,
|
||
agent_config: None,
|
||
default_config,
|
||
}
|
||
}
|
||
|
||
pub fn with_system_prompt(mut self, system_prompt: Option<String>) -> Self {
|
||
self.system_prompt = system_prompt;
|
||
self
|
||
}
|
||
|
||
pub fn with_user_prompt_template(mut self, template: Option<String>) -> Self {
|
||
self.user_prompt_template = template;
|
||
self
|
||
}
|
||
|
||
pub fn with_agent_config(mut self, config: Option<ChatAgentConfig>) -> Self {
|
||
self.agent_config = config;
|
||
self
|
||
}
|
||
|
||
/// 获取最终的系统提示词
|
||
///
|
||
/// 逻辑：入参有值则使用入参，否则使用默认配置
|
||
pub fn get_system_prompt(&self, agent_id: &str) -> String {
|
||
// 入参有值且非空，直接使用
|
||
if let Some(ref sp) = self.system_prompt {
|
||
if !sp.is_empty() {
|
||
return sp.clone();
|
||
}
|
||
}
|
||
|
||
// 使用默认配置
|
||
self.default_config.get_system_prompt(agent_id)
|
||
}
|
||
|
||
/// 应用用户提示词模板
|
||
///
|
||
/// 逻辑：
|
||
/// 1. 如果有模板入参，使用模板替换 {user_prompt}
|
||
/// 2. 如果没有模板入参，检查默认配置
|
||
/// 3. 都没有，直接返回原始输入
|
||
pub fn apply_user_prompt(&self, agent_id: &str, user_input: &str) -> String {
|
||
// 入参有模板且非空，使用入参模板
|
||
if let Some(ref template) = self.user_prompt_template {
|
||
if !template.is_empty() {
|
||
return template.replace("{user_prompt}", user_input);
|
||
}
|
||
}
|
||
|
||
// 检查默认配置中的 user_prompt 模板
|
||
if let Some(agent) = self.default_config.get_agent(agent_id) {
|
||
if let Some(ref prompt_config) = agent.user_prompt {
|
||
if prompt_config.enabled {
|
||
return prompt_config.apply(user_input);
|
||
}
|
||
}
|
||
}
|
||
|
||
// 无模板，直接返回原始输入
|
||
user_input.to_string()
|
||
}
|
||
|
||
/// 获取最终的 Agent 服务器配置
|
||
///
|
||
/// 逻辑：
|
||
/// 1. 如果入参有 agent_server，与默认配置合并（入参字段覆盖默认值）
|
||
/// 2. 如果入参没有 agent_server，使用默认配置
|
||
pub fn get_agent_server_config(&self, default_agent_id: &str) -> AgentConfig {
|
||
// 获取默认的 Agent 配置
|
||
let default_agent = self.default_config
|
||
.get_agent(default_agent_id)
|
||
.cloned()
|
||
.unwrap_or_default();
|
||
|
||
// 如果入参有 agent_server 配置，合并覆盖
|
||
if let Some(ref config) = self.agent_config {
|
||
if let Some(ref agent_server) = config.agent_server {
|
||
return self.merge_agent_config(&default_agent, agent_server);
|
||
}
|
||
}
|
||
|
||
// 使用默认配置
|
||
default_agent
|
||
}
|
||
|
||
/// 合并 Agent 配置（入参覆盖默认值）
|
||
fn merge_agent_config(
|
||
&self,
|
||
default: &AgentConfig,
|
||
override_config: &ChatAgentServerConfig,
|
||
) -> AgentConfig {
|
||
let mut merged = default.clone();
|
||
|
||
// agent_id: 入参有值则覆盖
|
||
if let Some(ref agent_id) = override_config.agent_id {
|
||
merged.agent_id = agent_id.clone();
|
||
}
|
||
|
||
// command: 入参有值则覆盖
|
||
if let Some(ref command) = override_config.command {
|
||
merged.command = command.clone();
|
||
}
|
||
|
||
// args: 入参有值则覆盖（替换而非追加）
|
||
if let Some(ref args) = override_config.args {
|
||
merged.args = args.clone();
|
||
}
|
||
|
||
// env: 入参有值则合并（入参优先）
|
||
if let Some(ref env) = override_config.env {
|
||
for (key, value) in env {
|
||
merged.env.insert(key.clone(), value.clone());
|
||
}
|
||
}
|
||
|
||
// metadata: 入参有值则合并
|
||
if let Some(ref metadata) = override_config.metadata {
|
||
for (key, value) in metadata {
|
||
merged.metadata.insert(key.clone(), value.clone());
|
||
}
|
||
}
|
||
|
||
merged
|
||
}
|
||
|
||
/// 获取最终的 MCP 服务器配置
|
||
///
|
||
/// 逻辑：入参有配置则使用入参，否则使用默认配置
|
||
pub fn get_context_servers(&self) -> HashMap<String, ContextServerConfig> {
|
||
// 入参有 MCP 配置，使用入参
|
||
if let Some(ref config) = self.agent_config {
|
||
if config.has_context_servers() {
|
||
return config.context_servers.iter()
|
||
.map(|(name, chat_config)| {
|
||
let ctx_config = ContextServerConfig {
|
||
source: chat_config.source.clone(),
|
||
enabled: chat_config.enabled,
|
||
command: chat_config.command.clone(),
|
||
args: chat_config.args.clone(),
|
||
env: chat_config.env.clone(),
|
||
};
|
||
(name.clone(), ctx_config)
|
||
})
|
||
.collect();
|
||
}
|
||
}
|
||
|
||
// 使用默认配置
|
||
self.default_config.context_servers.clone()
|
||
}
|
||
|
||
/// 获取使用的 Agent ID
|
||
///
|
||
/// 逻辑：入参有指定则使用入参，否则使用默认
|
||
pub fn get_agent_id(&self, default_agent_id: &str) -> String {
|
||
if let Some(ref config) = self.agent_config {
|
||
if let Some(ref agent_server) = config.agent_server {
|
||
return agent_server.get_agent_id().to_string();
|
||
}
|
||
}
|
||
default_agent_id.to_string()
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4.5.2 导出新模块
|
||
|
||
**文件**: `crates/agent_config/src/config/mod.rs`
|
||
|
||
```rust
|
||
pub mod prompt_assembler;
|
||
pub use prompt_assembler::PromptConfigAssembler;
|
||
```
|
||
|
||
**文件**: `crates/agent_config/src/lib.rs`
|
||
|
||
```rust
|
||
pub use config::prompt_assembler::PromptConfigAssembler;
|
||
```
|
||
|
||
---
|
||
|
||
### 4.6 阶段六：修改 agent_runner 业务逻辑
|
||
|
||
#### 4.6.1 修改 gRPC AgentServiceImpl::chat()
|
||
|
||
**文件**: `crates/agent_runner/src/grpc/agent_service_impl.rs`
|
||
|
||
```rust
|
||
use shared_types::ChatAgentConfig;
|
||
|
||
async fn chat(&self, request: Request<GrpcChatRequest>) -> Result<Response<GrpcChatResponse>, Status> {
|
||
let req = request.into_inner();
|
||
|
||
// ... 现有验证逻辑 ...
|
||
|
||
// 转换 gRPC ChatAgentConfig -> shared_types ChatAgentConfig
|
||
let agent_config_override: Option<ChatAgentConfig> = req.agent_config.map(ChatAgentConfig::from);
|
||
|
||
// 构建 ChatPrompt（包含覆盖配置）
|
||
let chat_prompt = ChatPromptBuilder::default()
|
||
.project_id(project_id.clone())
|
||
.project_path(project_dir)
|
||
.session_id(session_id.clone())
|
||
.prompt(req.prompt)
|
||
.system_prompt_override(req.system_prompt) // 新增
|
||
.user_prompt_template_override(req.user_prompt) // 新增
|
||
.agent_config_override(agent_config_override) // 新增
|
||
// ... 其他字段 ...
|
||
.build()
|
||
.map_err(|e| Status::internal(format!("构建 ChatPrompt 失败: {}", e)))?;
|
||
|
||
// ... 后续处理 ...
|
||
}
|
||
```
|
||
|
||
#### 4.6.2 修改 AcpAgentWorker
|
||
|
||
**文件**: `crates/agent_abstraction/src/session/acp_worker.rs`
|
||
|
||
```rust
|
||
use agent_config::PromptConfigAssembler;
|
||
|
||
impl AgentWorker for AcpAgentWorker {
|
||
async fn process_request(&self, request: WorkerRequest) -> Result<WorkerResponse> {
|
||
// 加载默认配置
|
||
let default_config = AgentServersConfig::load_or_default().await;
|
||
|
||
// 创建配置组装器
|
||
let assembler = PromptConfigAssembler::new(default_config)
|
||
.with_system_prompt(request.prompt_message.system_prompt_override.clone())
|
||
.with_user_prompt_template(request.prompt_message.user_prompt_template_override.clone())
|
||
.with_agent_config(request.prompt_message.agent_config_override.clone());
|
||
|
||
// 获取最终的系统提示词
|
||
let system_prompt = assembler.get_system_prompt("claude-code-acp");
|
||
|
||
// 构建 AgentStartConfig
|
||
let start_config = AgentStartConfig::new()
|
||
.with_system_prompt(system_prompt);
|
||
|
||
// 获取 MCP 服务器配置
|
||
let context_servers = assembler.get_context_servers();
|
||
// TODO: 将 context_servers 转换为 Vec<McpServer> 传递给 start_config
|
||
|
||
// 应用用户提示词模板
|
||
let final_user_prompt = assembler.apply_user_prompt(
|
||
"claude-code-acp",
|
||
&request.prompt_message.content,
|
||
);
|
||
|
||
// 更新 prompt_message 的 content 为处理后的用户提示词
|
||
let mut prompt_message = request.prompt_message.clone();
|
||
prompt_message.content = final_user_prompt;
|
||
|
||
// ... 创建会话 / 发送 prompt ...
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4.7 阶段七：修改 ClaudeCodeLauncher
|
||
|
||
**文件**: `crates/agent_abstraction/src/compat/claude_code_launcher.rs`
|
||
|
||
```rust
|
||
use shared_types::ChatAgentConfig;
|
||
|
||
pub async fn load_agent_config_with_override(
|
||
model_provider: Option<&ModelProviderConfig>,
|
||
agent_config_override: Option<&ChatAgentConfig>,
|
||
) -> Result<AgentLaunchConfig> {
|
||
// 加载默认配置
|
||
let default_config = AgentServersConfig::load_or_default().await;
|
||
|
||
// 合并 context_servers
|
||
let context_servers = if let Some(override_config) = agent_config_override {
|
||
if override_config.has_context_servers() {
|
||
// 使用覆盖的 MCP 配置
|
||
override_config.context_servers.iter()
|
||
.map(|(name, config)| {
|
||
(name.clone(), ContextServerConfig {
|
||
source: config.source.clone(),
|
||
enabled: config.enabled,
|
||
command: config.command.clone(),
|
||
args: config.args.clone(),
|
||
env: config.env.clone(),
|
||
})
|
||
})
|
||
.collect()
|
||
} else {
|
||
default_config.context_servers.clone()
|
||
}
|
||
} else {
|
||
default_config.context_servers.clone()
|
||
};
|
||
|
||
// ... 后续使用 context_servers 构建 AgentLaunchConfig ...
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 测试计划
|
||
|
||
### 5.1 单元测试
|
||
|
||
1. **ChatAgentConfig 结构体测试**
|
||
- 测试 JSON 序列化/反序列化
|
||
- 测试默认值
|
||
- 测试 `has_agent_server()` 方法
|
||
- 测试 `has_context_servers()` 方法
|
||
- 测试 `get_enabled_context_servers()` 方法
|
||
|
||
2. **ChatAgentServerConfig 结构体测试**
|
||
- 测试 JSON 序列化/反序列化
|
||
- 测试 `get_agent_id()` 默认值
|
||
- 测试部分字段覆盖
|
||
|
||
3. **PromptConfigAssembler 测试**
|
||
- 测试入参有值时直接使用入参
|
||
- 测试入参为空时使用默认配置
|
||
- 测试用户提示词模板 `{user_prompt}` 替换
|
||
- 测试 Agent 服务器配置合并（`get_agent_server_config()`）
|
||
- 测试 Agent 配置字段覆盖（command, args, env）
|
||
- 测试 MCP 服务器配置合并
|
||
|
||
### 5.2 集成测试
|
||
|
||
```bash
|
||
# 测试只传 system_prompt
|
||
curl -X POST http://localhost:8087/chat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"prompt": "hello", "system_prompt": "你是 Rust 专家"}'
|
||
|
||
# 测试只传 user_prompt
|
||
curl -X POST http://localhost:8087/chat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"prompt": "hello", "user_prompt": "请用中文回答：{user_prompt}"}'
|
||
|
||
# 测试只传 agent_config（仅 agent_server）
|
||
curl -X POST http://localhost:8087/chat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"prompt": "hello",
|
||
"agent_config": {
|
||
"agent_server": {
|
||
"env": {
|
||
"ANTHROPIC_MODEL": "claude-sonnet-4-20250514",
|
||
"RUST_LOG": "debug"
|
||
}
|
||
}
|
||
}
|
||
}'
|
||
|
||
# 测试只传 agent_config（仅 MCP 服务器）
|
||
curl -X POST http://localhost:8087/chat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"prompt": "hello",
|
||
"agent_config": {
|
||
"context_servers": {
|
||
"my-mcp": {
|
||
"enabled": true,
|
||
"command": "bunx",
|
||
"args": ["-y", "my-mcp-server"]
|
||
}
|
||
}
|
||
}
|
||
}'
|
||
|
||
# 测试 agent_server + context_servers 组合
|
||
curl -X POST http://localhost:8087/chat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"prompt": "hello",
|
||
"agent_config": {
|
||
"agent_server": {
|
||
"agent_id": "claude-code-acp",
|
||
"env": {"RUST_LOG": "info"}
|
||
},
|
||
"context_servers": {
|
||
"context7": {"enabled": true, "command": "bunx", "args": ["-y", "@upstash/context7-mcp"]}
|
||
}
|
||
}
|
||
}'
|
||
|
||
# 测试完整组合（所有入参）
|
||
curl -X POST http://localhost:8087/chat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"prompt": "帮我写一个 Hello World",
|
||
"system_prompt": "你是 Rust 专家",
|
||
"user_prompt": "请用 Rust 完成：{user_prompt}",
|
||
"agent_config": {
|
||
"agent_server": {
|
||
"env": {"ANTHROPIC_MODEL": "claude-sonnet-4-20250514"}
|
||
},
|
||
"context_servers": {
|
||
"context7": {"enabled": true, "command": "bunx", "args": ["-y", "@upstash/context7-mcp"]}
|
||
}
|
||
}
|
||
}'
|
||
```
|
||
|
||
### 5.3 端到端测试
|
||
- 验证 Agent 实际使用了自定义的系统提示词
|
||
- 验证用户提示词模板替换正确
|
||
- 验证自定义 agent_server 的 env 变量生效
|
||
- 验证自定义 MCP 服务器配置生效
|
||
- 验证 agent_server 配置的 command/args 覆盖生效
|
||
|
||
---
|
||
|
||
## 6. 修改文件清单
|
||
|
||
| 文件 | 修改类型 | 说明 |
|
||
|------|----------|------|
|
||
| `crates/shared_types/src/chat_agent_config.rs` | **新增** | ChatAgentConfig 结构体（简化版） |
|
||
| `crates/shared_types/src/lib.rs` | 修改 | 导出 ChatAgentConfig |
|
||
| `crates/shared_types/proto/agent.proto` | 修改 | 添加 gRPC 消息定义 |
|
||
| `crates/shared_types/src/grpc/agent.rs` | 自动生成 | proto 编译 |
|
||
| `crates/rcoder/src/handler/chat_handler.rs` | 修改 | HTTP ChatRequest 添加新字段 |
|
||
| `crates/rcoder/src/grpc/chat_client.rs` | 修改 | 传递新字段到 gRPC |
|
||
| `crates/agent_runner/src/grpc/agent_service_impl.rs` | 修改 | 处理新字段 |
|
||
| `crates/agent_config/src/config/prompt_assembler.rs` | **新增** | 配置组装逻辑 |
|
||
| `crates/agent_config/src/config/mod.rs` | 修改 | 导出新模块 |
|
||
| `crates/agent_config/src/lib.rs` | 修改 | 导出 PromptConfigAssembler |
|
||
| `crates/agent_abstraction/src/traits/agent.rs` | 修改 | PromptMessage 添加新字段 |
|
||
| `crates/agent_abstraction/src/session/acp_worker.rs` | 修改 | 使用配置组装器 |
|
||
| `crates/agent_abstraction/src/compat/claude_code_launcher.rs` | 修改 | 支持配置覆盖 |
|
||
|
||
---
|
||
|
||
## 7. 风险评估
|
||
|
||
### 7.1 兼容性风险
|
||
- **低风险**: 所有新字段都是可选的，不影响现有调用
|
||
- **缓解措施**: 添加版本检查，确保旧客户端可以正常工作
|
||
|
||
### 7.2 性能风险
|
||
- **低风险**: 配置组装逻辑简单，不涉及 I/O
|
||
- **缓解措施**: 配置组装器使用惰性求值
|
||
|
||
### 7.3 安全风险
|
||
- **中风险**: `agent_config` 允许用户传入自定义 MCP 服务器配置
|
||
- **缓解措施**:
|
||
- 使用强类型结构体验证配置格式
|
||
- 记录所有配置变更的日志
|
||
- 考虑添加白名单机制（可选）
|
||
|
||
---
|
||
|
||
## 8. 实现顺序建议
|
||
|
||
1. **第一批** (基础结构)
|
||
- 创建 `ChatAgentConfig` 结构体 (shared_types)
|
||
- 修改 proto 文件，添加 gRPC 消息定义
|
||
- 修改 ChatRequest (HTTP/gRPC)
|
||
- 修改 ChatPrompt 和 PromptMessage
|
||
|
||
2. **第二批** (核心逻辑)
|
||
- 实现 PromptConfigAssembler
|
||
- 修改 AgentServiceImpl
|
||
- 修改 AcpAgentWorker
|
||
|
||
3. **第三批** (启动器)
|
||
- 修改 ClaudeCodeLauncher
|
||
- 添加 gRPC 类型转换
|
||
|
||
4. **第四批** (测试和文档)
|
||
- 编写单元测试
|
||
- 编写集成测试
|
||
- 更新 API 文档 (Swagger/OpenAPI)
|
||
|
||
---
|
||
|
||
## 9. 附录：类型对照表
|
||
|
||
### 9.1 HTTP/gRPC 层
|
||
|
||
| 层级 | 类型名 | 用途 |
|
||
|------|--------|------|
|
||
| HTTP | `ChatRequest.system_prompt: Option<String>` | 接收系统提示词 |
|
||
| HTTP | `ChatRequest.user_prompt: Option<String>` | 接收用户提示词模板 |
|
||
| HTTP | `ChatRequest.agent_config: Option<ChatAgentConfig>` | 接收 Agent 运行时配置 |
|
||
| gRPC | `ChatRequest.system_prompt`, `user_prompt`, `agent_config` | 跨服务传输 |
|
||
|
||
### 9.2 shared_types 层（外部入参结构）
|
||
|
||
| 类型名 | 字段 | 用途 |
|
||
|--------|------|------|
|
||
| `ChatAgentConfig` | `agent_server`, `context_servers` | 外部入参的 Agent 配置（简化版） |
|
||
| `ChatAgentServerConfig` | `agent_id`, `command`, `args`, `env`, `metadata` | 单个 Agent 服务器配置 |
|
||
| `ChatContextServerConfig` | `source`, `enabled`, `command`, `args`, `env` | 单个 MCP 服务器配置 |
|
||
|
||
### 9.3 agent_config 层（内部配置结构）
|
||
|
||
| 类型名 | 字段 | 用途 |
|
||
|--------|------|------|
|
||
| `AgentServersConfig` | `agent_servers`, `context_servers` | 内部完整配置（支持多 Agent） |
|
||
| `AgentConfig` | `agent_id`, `command`, `args`, `env`, `system_prompt`, `user_prompt`, ... | 内部 Agent 配置（包含提示词模板） |
|
||
| `ContextServerConfig` | `source`, `enabled`, `command`, `args`, `env` | 内部 MCP 配置 |
|
||
|
||
### 9.4 业务逻辑层
|
||
|
||
| 层级 | 类型名 | 用途 |
|
||
|------|--------|------|
|
||
| agent_config | `PromptConfigAssembler` | 配置组装逻辑（外部 → 内部） |
|
||
| agent_abstraction | `PromptMessage.*_override` | Agent 层配置传递 |
|
||
| agent_abstraction | `AgentStartConfig` | Agent 启动时的最终配置 |
|
||
|
||
### 9.5 外部入参 vs 内部配置 映射关系
|
||
|
||
```
|
||
外部入参 (ChatAgentConfig) 内部配置 (AgentServersConfig)
|
||
─────────────────────────────────────────────────────────────────────
|
||
ChatAgentServerConfig (单个) → AgentConfig (HashMap 中的一个)
|
||
- agent_id → - agent_id
|
||
- command → - command
|
||
- args → - args
|
||
- env → - env
|
||
- metadata → - metadata
|
||
(无 system_prompt) → - system_prompt (保留默认)
|
||
(无 user_prompt) → - user_prompt (保留默认)
|
||
|
||
ChatContextServerConfig (多个) → ContextServerConfig (多个)
|
||
- source → - source
|
||
- enabled → - enabled
|
||
- command → - command
|
||
- args → - args
|
||
- env → - env
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 设计对比：简化方案 vs 原方案
|
||
|
||
| 方面 | 原方案 | 简化方案（当前） |
|
||
|------|--------|------------------|
|
||
| `agent_config` 内容 | 包含 `system_prompt`, `user_prompt`, `context_servers` | 包含 `agent_server` (单个) + `context_servers` (多个) |
|
||
| 提示词配置 | 在 `agent_config` 中 | 独立入参 (`system_prompt`, `user_prompt`) |
|
||
| 优先级冲突 | 存在（入参 vs agent_config 中的提示词） | 无（职责分离） |
|
||
| Agent 配置 | 无法覆盖 | 支持单个 Agent 的 command/args/env 覆盖 |
|
||
| MCP 配置 | 可配置多个 | 可配置多个（保持一致） |
|
||
| 合并逻辑 | 复杂的三级优先级 | 简单的二级（入参 > 默认） |
|
||
| 用户理解成本 | 高（需要理解优先级规则） | 低（职责分离，直观） |
|
||
| 代码复杂度 | ConfigMerger 需要处理多种情况 | PromptConfigAssembler 逻辑简单 |
|