chore: initialize qiming workspace repository

qimingclaw/docs/acp-code-agent-config-isolation.md

@@ -0,0 +1,177 @@
+# 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. 验证记录与验收结论。