178 lines
6.6 KiB
Markdown
178 lines
6.6 KiB
Markdown
# ACP 方案中 Code Agent 全局配置冲突的隔离与实现计划
|
||
|
||
## 目的
|
||
通过 ACP 方案在客户端侧（项目中的 tauri-client）调用 qimingcode / claude (code) 等 CLI code agent 时，这些工具会读取用户全局配置（如 .claude、.opencode、.qimingcode），与 ACP 注入配置冲突。本文提供包含代码与落地步骤的完整实现计划。
|
||
|
||
## 目标与边界
|
||
目标：确保 ACP 注入配置优先或成为唯一配置来源；支持多项目/多实例并行运行；CI 环境稳定可复现。
|
||
非目标：不修改第三方工具内部逻辑，仅通过运行时隔离与启动策略控制。
|
||
|
||
## 方案概览（分层隔离）
|
||
1. 配置路径重定向（环境变量）
|
||
2. 显式配置参数（CLI 参数）
|
||
3. HOME 与 XDG 隔离
|
||
4. 统一 Wrapper
|
||
5. 容器化 / 沙箱
|
||
|
||
## 实施步骤（含代码，客户端为 tauri-client）
|
||
|
||
### Step 1：确认工具能力（参数与环境变量）
|
||
产出：每个工具的“配置入口清单”。
|
||
执行方式：查官方文档或源码确认参数与环境变量名。
|
||
|
||
模板记录（示例，仅为假设，需以实际文档/源码为准）：
|
||
```
|
||
tool: qimingcode
|
||
config_arg: --config
|
||
config_env: QIMINGCODE_CONFIG_DIR
|
||
xdg_supported: yes
|
||
```
|
||
|
||
### Step 2：定义隔离目录规范
|
||
目标：为每次 ACP 运行生成独立目录，避免并发冲突。
|
||
目录结构建议：
|
||
```
|
||
<base>/
|
||
runs/<run_id>/
|
||
config/
|
||
data/
|
||
cache/
|
||
logs/
|
||
```
|
||
|
||
### Step 3：运行时注入规则（tauri-client 侧）
|
||
目的：由 tauri-client 在启动子进程时注入隔离目录与配置参数。
|
||
|
||
#### 3.1 环境变量重定向（优先）
|
||
示例（以 bash 为例）：
|
||
```bash
|
||
export ACP_RUN_DIR="/tmp/acp-runs/$RUN_ID"
|
||
export XDG_CONFIG_HOME="$ACP_RUN_DIR/config"
|
||
export XDG_DATA_HOME="$ACP_RUN_DIR/data"
|
||
export XDG_CACHE_HOME="$ACP_RUN_DIR/cache"
|
||
```
|
||
|
||
如果工具提供专用环境变量：
|
||
```bash
|
||
export QIMINGCODE_CONFIG_DIR="$ACP_RUN_DIR/config"
|
||
export CLAUDE_CONFIG_DIR="$ACP_RUN_DIR/config"
|
||
```
|
||
|
||
#### 3.2 CLI 参数指定配置
|
||
示例：
|
||
```bash
|
||
qimingcode --config "$ACP_RUN_DIR/config/qimingcode.yaml" ...
|
||
claude --config "$ACP_RUN_DIR/config/claude.json" ...
|
||
```
|
||
|
||
### Step 4：Wrapper 统一入口（可选，tauri-client 侧）
|
||
目标：在 tauri-client 中统一处理隔离目录与环境变量。
|
||
|
||
示例伪代码（Node.js）：
|
||
```js
|
||
import { spawn } from "child_process";
|
||
import { mkdtempSync } from "fs";
|
||
import { tmpdir } from "os";
|
||
import path from "path";
|
||
|
||
const runId = process.env.ACP_RUN_ID || Date.now().toString();
|
||
const base = mkdtempSync(path.join(tmpdir(), "acp-runs-"));
|
||
const runDir = path.join(base, runId);
|
||
|
||
const env = {
|
||
...process.env,
|
||
XDG_CONFIG_HOME: path.join(runDir, "config"),
|
||
XDG_DATA_HOME: path.join(runDir, "data"),
|
||
XDG_CACHE_HOME: path.join(runDir, "cache"),
|
||
QIMINGCODE_CONFIG_DIR: path.join(runDir, "config"),
|
||
};
|
||
|
||
const args = ["--config", path.join(runDir, "config/qimingcode.yaml")];
|
||
spawn("qimingcode", args, { env, stdio: "inherit" });
|
||
```
|
||
|
||
### Step 5：清理策略
|
||
目的：确保隔离目录不会污染用户环境。
|
||
示例（bash）：
|
||
```bash
|
||
rm -rf "$ACP_RUN_DIR"
|
||
```
|
||
|
||
## tauri-client 集成点（明确落点）
|
||
以下落点均在 tauri-client 侧，可作为实现注入与隔离的“挂载点”。
|
||
|
||
1. 进程启动入口
|
||
文件：/Users/apple/workspace/qiming-agent_diff/crates/agent-tauri-client/src-tauri/src/lib.rs
|
||
位置：`tauri::command` 各类服务启动函数，例如 `file_server_start`、`lanproxy_start`、`rcoder_start`。
|
||
方案：在调用 ServiceManager 之前构建隔离目录与环境变量，并将其传递给下层。
|
||
|
||
示例（tauri 命令层注入）：
|
||
```rust
|
||
let run_dir = build_isolated_run_dir();
|
||
let env = build_isolated_env(&run_dir);
|
||
manager.file_server_start_with_config_and_env(config, env).await?;
|
||
```
|
||
|
||
2. ServiceManager 初始化与生命周期
|
||
文件：/Users/apple/workspace/qiming-agent_diff/crates/agent-tauri-client/src-tauri/src/lib.rs
|
||
位置：`ServiceManagerState::default` 与 `ServiceManager::new` 的调用处。
|
||
方案：在创建 ServiceManager 时注入“默认隔离策略”，确保后续所有启动路径统一受控。
|
||
|
||
示例（构造注入）：
|
||
```rust
|
||
let manager = ServiceManager::new_with_isolation(isolation_policy);
|
||
```
|
||
|
||
3. 实际进程 spawn 点（下沉到 core）
|
||
文件：/Users/apple/workspace/qiming-agent_diff/crates/qiming-agent-core/src/service/mod.rs
|
||
位置：`file_server_start_with_config` 等使用 `process_wrap::tokio::CommandWrap` 的地方。
|
||
方案：在 CommandWrap 构建阶段追加 env 与工作目录，保证隔离目录生效。
|
||
|
||
示例（CommandWrap 注入）：
|
||
```rust
|
||
let mut cmd = process_wrap::tokio::CommandWrap::with_new(bin, |cmd| {
|
||
cmd.envs(isolated_env).current_dir(run_dir);
|
||
});
|
||
```
|
||
|
||
4. macOS PATH 修复与隔离并行
|
||
文件：/Users/apple/workspace/qiming-agent_diff/crates/agent-tauri-client/src-tauri/src/lib.rs
|
||
位置：`fix_macos_path_env`。
|
||
方案：保持 PATH 修复不变，但在此之后叠加隔离目录注入，避免覆盖。
|
||
|
||
## 责任边界
|
||
tauri-client：注入隔离环境、维护配置目录生命周期、管理日志与缓存隔离。
|
||
CLI 工具侧：遵循参数/环境变量读取指定配置；不保证处理未声明的私有路径。
|
||
平台/基础设施：提供可写临时目录与权限，容器模式时提供运行环境。
|
||
|
||
## 风险评估
|
||
- 配置入口不一致：隔离策略失效导致读取全局配置。
|
||
缓解：先完成工具能力确认与验证。
|
||
- 隐式路径写入：token、history、cache 写入用户 HOME。
|
||
缓解：验证阶段检查写入痕迹并补充隔离目录。
|
||
- 多实例竞争：并发运行时覆盖配置或缓存。
|
||
缓解：每次运行生成唯一隔离目录。
|
||
- 性能与启动开销：隔离目录创建与初始化耗时增加。
|
||
缓解：控制目录层级与复用策略。
|
||
- 排障复杂：隔离层级增加定位成本。
|
||
缓解：规范日志与诊断输出路径。
|
||
|
||
## 验收标准
|
||
1. 工具在隔离模式下不读取用户全局配置。
|
||
2. 多实例并发运行时互不污染。
|
||
3. 启动、运行、退出后不在用户 HOME 目录产生新文件。
|
||
4. 日志与缓存均落在隔离目录内。
|
||
5. 在 CI 环境可稳定复现。
|
||
|
||
## 验证方法
|
||
1. 对比隔离前后读取配置路径的差异。
|
||
2. 检查隔离目录与用户 HOME 目录的写入痕迹。
|
||
3. 并发运行至少两组实例，确认目录与配置完全隔离。
|
||
4. 清理隔离目录后再次运行，确认不依赖全局配置。
|
||
|
||
## 输出物
|
||
1. 本方案文档（含代码实现计划）。
|
||
2. 工具能力确认清单。
|
||
3. 运行时注入规则说明。
|
||
4. 验证记录与验收结论。
|