--- version: 1.0 last-updated: 2026-02-24 status: design --- # Agent 自我进化架构 - 隔离策略 ## 概述 本文档详细描述 Qiming Agent 的隔离策略，通过三区模型实现安全的受限自由，平衡用户体验与 Agent 能力。 --- ## 核心洞察 这是一个**二元矛盾**： | 极端 A：过度保护 | 极端 B：完全自由 | |-----------------|-----------------| | ❌ Agent 无法安装工具 | ❌ 用户环境被污染 | | ❌ 无法自我迭代升级 | ❌ 依赖版本冲突 | | ❌ 能力被限制死 | ❌ 门槛极高 | **我们的目标：中间地带 —— 安全的受限自由** --- ## 三区隔离模型 ``` ┌──────────────────────────────────────────────────────────────────┐ │ 应用核心区 (App Core) │ │ ───────────────────────── │ │ - 内容: Electron, Node.js, uv, 核心引擎 │ │ - 特点: 完全受控，不可变 │ │ - 目的: 保证应用稳定性 │ │ - Agent 权限: 只读 │ ├──────────────────────────────────────────────────────────────────┤ │ Agent 工作区 (Agent Workspace) │ │ ──────────────────────── │ │ - 内容: 工具、依赖、缓存、临时文件 │ │ - 特点: Agent 可写，受应用管理 │ │ - 目的: Agent 自我迭代的空间 │ │ - Agent 权限: 完全控制 │ ├──────────────────────────────────────────────────────────────────┤ │ 用户系统区 (User System) │ │ ──────────────────── │ │ - 内容: 系统工具、用户配置 │ │ - 特点: 只读访问，受污染风险 │ │ - 目的: 兼容性回退 │ │ - Agent 权限: 只读调用 │ └──────────────────────────────────────────────────────────────────┘ ``` --- ## Agent 自由度边界 | 能力 | 允许 | 限制 | 原因 | |------|------|------|------| | **安装 npm 包** | ✅ 到工作区 | ❌ 到全局 | 避免污染用户环境 | | **安装 Python 包** | ✅ 通过 uv | ❌ 系统 pip | 隔离环境 | | **修改配置** | ✅ 工作区内 | ❌ 应用配置 | 保护核心 | | **执行系统命令** | ✅ 只读工具 | ❌ 写入操作 | 安全考虑 | | **自我升级** | ✅ 工作区依赖 | ❌ 引擎核心 | 稳定性优先 | --- ## 目录结构设计 ``` ~/.qimingclaw/ ├── core/ # 应用核心区（只读） │ ├── engines/ # 引擎二进制（应用管理） │ └── config/ # 应用配置（用户通过 UI 修改） │ ├── workspace/ # Agent 工作区（Agent 可写） │ ├── {session-id}/ │ │ ├── node_modules/ # Agent 安装的 npm 包 │ │ ├── .venv/ # Agent 创建的 Python 环境 │ │ ├── tools/ # Agent 下载/编译的工具 │ │ ├── cache/ # 缓存文件 │ │ └── projects/ # Agent 操作的项目 │ ├── shared/ # 共享资源（受控） │ └── tools/ # 跨会话共享的工具 │ └── logs/ # 日志（审计） ``` --- ## 环境变量策略 ### 应用核心环境 ```typescript // 应用核心：严格隔离 const coreEnv = { PATH: [ '~/.qimingclaw/core/engines', '~/.qimingclaw/core/bin', ].join(':'), // 最小化环境变量 }; ``` ### Agent 工作区环境 ```typescript // Agent 工作区：灵活但受控 const agentEnv = { // 核心工具（来自应用） PATH: [ '~/.qimingclaw/core/engines', '~/.qimingclaw/core/bin', ], // Agent 工作区（Agent 可添加） PATH: [ './node_modules/.bin', // Agent 安装的包 './tools/bin', // Agent 安装的工具 './.venv/bin', // Agent 创建的 venv ], // 安装目标（指向工作区） npm_config_prefix: './workspace/tools/npm', UV_TOOL_DIR: './workspace/tools/uv', PYTHONPATH: './workspace/python', // 系统工具回退（只读） PATH: [ '/usr/bin', '/bin', '/usr/sbin', // git, bash 等 ].filter(systemPathsOnly), }; ``` --- ## Agent 能力接口 ```typescript // Agent 可以请求的权限 interface AgentCapabilities { // 安装工具（到工作区） installNpmPackage: (name: string, version?: string) => Promise; installPythonPackage: (name: string) => Promise; downloadTool: (url: string, checksum: string) => Promise; // 执行命令（受控） executeCommand: (cmd: string, args: string[]) => Promise; // 文件操作（沙箱内） readFile: (path: string) => Promise; writeFile: (path: string, content: string) => Promise; // 自我升级（工作区内） upgradeSelf: () => Promise; // 升级工作区依赖 } ``` --- ## Agent 自我迭代场景 ### 场景 1: Agent 发现需要新工具 ```typescript // Agent 的思考过程 // "我需要 jq 来处理 JSON，但系统没有" // Agent 行动 await capabilities.installNpmPackage('jq'); // 安装到工作区 // 结果 ~/.qimingclaw/workspace/{session-id}/node_modules/.bin/jq // ✅ Agent 可以使用 // ✅ 不污染用户环境 // ✅ 会话结束可清理 ``` ### 场景 2: Agent 发现更好的工具版本 ```typescript // Agent 的思考过程 // "qimingcode 有新版本，性能更好" // Agent 行动 await capabilities.installNpmPackage('@qiming/qimingcode@latest'); // 结果 ~/.qimingclaw/workspace/{session-id}/node_modules/.bin/qimingcode // ✅ Agent 使用新版本 // ✅ 应用核心引擎不受影响 // ✅ 可以回滚 ``` ### 场景 3: Agent 需要编译工具 ```typescript // Agent 的思考过程 // "这个项目需要 cargo build" // Agent 行动 if (!await capabilities.hasCommand('cargo')) { await capabilities.downloadTool('https://rustup.rs', 'sha256:...'); await capabilities.executeCommand('./rustup-init', ['--profile', 'minimal', '-y']); } // 结果 ~/.qimingclaw/workspace/{session-id}/tools/bin/cargo // ✅ Agent 可以编译项目 // ✅ 不影响用户系统 ``` --- ## 安全考虑 ### 沙箱边界 ```typescript // Agent 操作白名单 const ALLOWED_OPERATIONS = { // 文件：只能在工作区和用户指定目录 file: { read: ['workspace/**', 'user-selected/**'], write: ['workspace/**', 'user-selected/**'], }, // 网络：需要用户确认 network: { download: 'prompt', // 每次询问 apiCall: 'allowed', // 配置的 API }, // 执行：受限命令 execute: { safe: ['git', 'grep', 'find'], // 允许 dangerous: ['rm', 'dd', 'mkfs'], // 禁止或高权限确认 }, }; ``` ### 资源限制 ```typescript // 防止 Agent 占用过多资源 const AGENT_LIMITS = { maxDiskUsage: '5GB', // 工作区大小限制 maxExecutionTime: 300000, // 单个命令超时 maxMemoryUsage: '2GB', // 内存限制 maxNetworkBandwidth: '10MB/s', // 网络限制 }; ``` ### 审计日志 ```typescript // 记录所有 Agent 操作 interface AgentAuditLog { timestamp: number; sessionId: string; operation: 'install' | 'execute' | 'download' | 'write'; target: string; approvedBy: 'auto' | 'user' | 'policy'; result: 'success' | 'failed' | 'denied'; } ``` --- ## 用户体验设计 ### 原则: 用户看到的简单，不是能力的简单 ``` 用户看到 Agent 实际在做 ───────────────────────────────────────────── "正在分析项目..." → 检测依赖 → 安装工具 → 配置环境 "正在安装依赖..." → npm install → uv pip install "正在构建..." → cargo build → 编译工具链 ``` ### 透明度控制 | 用户类型 | 可见性 | 控制权 | |----------|--------|--------| | **普通用户** | 简化状态 | 启动/停止 | | **进阶用户** | 详细日志 | 允许/拒绝操作 | | **开发者** | 完全透明 | 完全控制 | --- ## 产品验证问题 在做技术决策时，问： 1. **这会限制 Agent 的能力吗？** - 如果是 → 能否通过工作区机制解决？ 2. **这会损害用户体验吗？** - 如果是 → 能否隐藏复杂性？ 3. **Agent 可以自我迭代吗？** - 如果不能 → 需要增加什么接口？ 4. **边界足够安全吗？** - 如果不是 → 需要什么限制？ --- ## 总结 **核心哲学：** ``` 简单 ≠ 能力弱 我们追求的是： - 用户界面：简单、友好、零门槛 - Agent 环境：灵活、强大、可成长 通过架构设计，而不是能力限制来实现简单。 ``` **关键架构决策：** 1. **三层隔离** - 核心 / 工作区 / 系统 2. **权限分级** - 只读 / 受控写入 / 完全控制 3. **透明度分层** - 简化 / 详细 / 完全 **最终目标：** > 让用户觉得简单，同时让 Agent 有能力变得更强。 --- ## 相关文档 - [总览](./OVERVIEW.md) - 产品定位、核心原则 - [核心组件](./COMPONENTS.md) - Memory、Skill Creator、EvoMap、Soul.md - [循环流程](./LOOP.md) - 完整循环流程、接口定义 - [存储实现](./STORAGE.md) - Markdown 格式、索引机制