10 KiB
10 KiB
version, last-updated, status
| version | last-updated | status |
|---|---|---|
| 1.0 | 2026-02-24 | 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/ # 日志（审计）
环境变量策略
应用核心环境
// 应用核心：严格隔离
const coreEnv = {
PATH: [
'~/.qimingclaw/core/engines',
'~/.qimingclaw/core/bin',
].join(':'),
// 最小化环境变量
};
Agent 工作区环境
// 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 能力接口
// Agent 可以请求的权限
interface AgentCapabilities {
// 安装工具（到工作区）
installNpmPackage: (name: string, version?: string) => Promise<void>;
installPythonPackage: (name: string) => Promise<void>;
downloadTool: (url: string, checksum: string) => Promise<string>;
// 执行命令（受控）
executeCommand: (cmd: string, args: string[]) => Promise<ExecuteResult>;
// 文件操作（沙箱内）
readFile: (path: string) => Promise<string>;
writeFile: (path: string, content: string) => Promise<void>;
// 自我升级（工作区内）
upgradeSelf: () => Promise<void>; // 升级工作区依赖
}
Agent 自我迭代场景
场景 1: Agent 发现需要新工具
// Agent 的思考过程
// "我需要 jq 来处理 JSON，但系统没有"
// Agent 行动
await capabilities.installNpmPackage('jq'); // 安装到工作区
// 结果
~/.qimingclaw/workspace/{session-id}/node_modules/.bin/jq
// ✅ Agent 可以使用
// ✅ 不污染用户环境
// ✅ 会话结束可清理
场景 2: Agent 发现更好的工具版本
// Agent 的思考过程
// "qimingcode 有新版本，性能更好"
// Agent 行动
await capabilities.installNpmPackage('@qiming/qimingcode@latest');
// 结果
~/.qimingclaw/workspace/{session-id}/node_modules/.bin/qimingcode
// ✅ Agent 使用新版本
// ✅ 应用核心引擎不受影响
// ✅ 可以回滚
场景 3: Agent 需要编译工具
// 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 可以编译项目
// ✅ 不影响用户系统
安全考虑
沙箱边界
// 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'], // 禁止或高权限确认
},
};
资源限制
// 防止 Agent 占用过多资源
const AGENT_LIMITS = {
maxDiskUsage: '5GB', // 工作区大小限制
maxExecutionTime: 300000, // 单个命令超时
maxMemoryUsage: '2GB', // 内存限制
maxNetworkBandwidth: '10MB/s', // 网络限制
};
审计日志
// 记录所有 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 → 编译工具链
透明度控制
| 用户类型 | 可见性 | 控制权 |
|---|---|---|
| 普通用户 | 简化状态 | 启动/停止 |
| 进阶用户 | 详细日志 | 允许/拒绝操作 |
| 开发者 | 完全透明 | 完全控制 |
产品验证问题
在做技术决策时，问：
-
这会限制 Agent 的能力吗？
- 如果是 → 能否通过工作区机制解决？
-
这会损害用户体验吗？
- 如果是 → 能否隐藏复杂性？
-
Agent 可以自我迭代吗？
- 如果不能 → 需要增加什么接口？
-
边界足够安全吗？
- 如果不是 → 需要什么限制？
总结
核心哲学：
简单 ≠ 能力弱
我们追求的是：
- 用户界面：简单、友好、零门槛
- Agent 环境：灵活、强大、可成长
通过架构设计，而不是能力限制来实现简单。
关键架构决策：
- 三层隔离 - 核心 / 工作区 / 系统
- 权限分级 - 只读 / 受控写入 / 完全控制
- 透明度分层 - 简化 / 详细 / 完全
最终目标：
让用户觉得简单，同时让 Agent 有能力变得更强。