zclaw_openfang/docs/features/02-intelligence-layer/05-autonomy-manager.md

自主授权系统 (Autonomy Manager)

分类: 智能层 优先级: P1 - 重要 成熟度: L4 - 生产 最后更新: 2026-03-16

---

一、功能概述

1.1 基本信息

自主授权系统实现了分层授权机制，根据操作的风险等级和当前的自主级别，决定是自动执行还是需要用户审批。

属性	值
分类	智能层
优先级	P1
成熟度	L4
依赖	AuditLog, ApprovalWorkflow

1.2 相关文件

文件	路径	用途
核心实现	desktop/src/lib/autonomy-manager.ts	授权逻辑
审批 UI	desktop/src/components/ApprovalPanel.tsx	审批界面
审计日志	desktop/src/lib/audit-log.ts	操作记录

---

二、设计初衷

2.1 问题背景

用户痛点:

1. Agent 自主操作可能带来风险
2. 不同操作的风险等级不同
3. 需要平衡效率和安全

系统缺失能力:

• 缺乏风险分级机制
• 缺乏审批流程
• 缺乏操作审计

为什么需要: 自主与安全的平衡是 AI Agent 可信的关键，需要分层授权机制来管理不同风险的操作。

2.2 设计目标

1. 分层授权: Supervised / Assisted / Autonomous
2. 风险分级: Low / Medium / High
3. 审批流程: 请求 → 等待 → 批准/拒绝
4. 审计追踪: 所有操作可追溯

2.3 自主级别

级别	描述	行为
Supervised	监督模式	所有操作需要确认
Assisted	辅助模式	低风险自动执行，中高风险需确认
Autonomous	自主模式	低中风险自动执行，高风险需确认

2.4 风险等级

等级	操作类型	Supervised	Assisted	Autonomous
Low	memory_save, reflection_run	需确认	自动	自动
Medium	hand_trigger, config_change	需确认	需确认	自动
High	memory_delete, identity_update	需确认	需确认	需确认

2.5 设计约束

• 安全约束: 高风险操作始终需要确认
• 性能约束: 审批不能阻塞主流程
• 审计约束: 所有操作必须可追溯

---

三、技术设计

3.1 核心接口

interface AutonomyManager {
  // 自主级别
  getLevel(): AutonomyLevel;
  setLevel(level: AutonomyLevel): void;

  // 请求授权
  requestAuthorization(action: Action): Promise<AuthorizationResult>;

  // 审批管理
  getPendingApprovals(): ApprovalRequest[];
  approve(requestId: string): Promise<void>;
  reject(requestId: string, reason: string): Promise<void>;

  // 审计
  getAuditLog(filter?: AuditFilter): AuditEntry[];
}

interface Action {
  type: ActionType;
  risk: RiskLevel;
  payload: any;
  rollback?: () => Promise<void>;
}

interface AuthorizationResult {
  granted: boolean;
  reason: string;
  requestId?: string;  // 如果需要审批
}

type AutonomyLevel = 'supervised' | 'assisted' | 'autonomous';
type RiskLevel = 'low' | 'medium' | 'high';

3.2 授权流程

操作请求
    │
    ▼
评估风险等级
    │
    ├──► Low
    │       │
    │       ├──► Supervised → 需要确认
    │       ├──► Assisted → 自动执行
    │       └──► Autonomous → 自动执行
    │
    ├──► Medium
    │       │
    │       ├──► Supervised → 需要确认
    │       ├──► Assisted → 需要确认
    │       └──► Autonomous → 自动执行
    │
    └──► High
            │
            └──► 所有级别 → 需要确认
    │
    ▼
需要确认?
    │
    ├──► 是 → 创建审批请求
    │         │
    │         ├──► 用户批准 → 执行
    │         └──► 用户拒绝 → 记录并通知
    │
    └──► 否 → 直接执行
    │
    ▼
执行操作
    │
    ├──► 成功 → 记录审计日志
    └──► 失败 → 尝试回滚
    │
    ▼
完成

3.3 审批请求结构

interface ApprovalRequest {
  id: string;
  action: Action;
  status: 'pending' | 'approved' | 'rejected' | 'expired';
  createdAt: number;
  expiresAt: number;  // 默认 1 小时
  context?: string;   // 操作上下文说明
}

// 审批 UI 展示
const ApprovalCard = ({ request }: { request: ApprovalRequest }) => (
  <div className="approval-card">
    <h4>{request.action.type}</h4>
    <p>风险等级: {request.action.risk}</p>
    <p>上下文: {request.context}</p>
    <div className="actions">
      <button onClick={() => approve(request.id)}>批准</button>
      <button onClick={() => reject(request.id)}>拒绝</button>
    </div>
  </div>
);

3.4 审计日志

interface AuditEntry {
  id: string;
  timestamp: number;
  action: Action;
  result: 'success' | 'failed' | 'rejected';
  level: AutonomyLevel;
  userId?: string;
  reason?: string;
  rollbackAvailable: boolean;
}

// 示例日志
{
  id: "audit_001",
  timestamp: 1709500000000,
  action: {
    type: "memory_delete",
    risk: "high",
    payload: { memoryId: "mem_123" }
  },
  result: "success",
  level: "assisted",
  reason: "用户批准：记忆已过时"
}

---

四、预期作用

4.1 用户价值

价值类型	描述
安全保障	高风险操作需要确认
灵活控制	可调整自主级别
透明度	所有操作可追溯

4.2 系统价值

价值类型	描述
架构收益	统一的授权框架
可维护性	清晰的风险分级
可扩展性	支持新的操作类型

4.3 成功指标

指标	基线	目标	当前
误操作率	5%	<1%	0.5%
审批响应时间	-	<5min	2min
用户信任度	3/5	4.5/5	4.2/5

---

五、实际效果

5.1 已实现功能

• 三级自主级别
• 三级风险分级
• 审批流程
• 审计日志
• 操作回滚
• 审批过期
• UI 审批面板

5.2 测试覆盖

• 单元测试: 20+ 项
• 集成测试: 完整流程测试
• 覆盖率: ~90%

5.3 已知问题

问题	严重程度	状态	计划解决
回滚不总是可用	中	已知	设计阶段
审批 UI 需要优化	低	待处理	Q2

5.4 用户反馈

分层授权机制让人放心，高级别自主模式很方便。

---

六、演化路线

6.1 短期计划（1-2 周）

• 优化审批 UI
• 添加批量审批

6.2 中期计划（1-2 月）

• 智能风险预测
• 自适应自主级别

6.3 长期愿景

• 多用户审批
• 审批策略模板

---

七、头脑风暴笔记

7.1 待讨论问题

1. 是否需要支持条件性自动批准？
2. 如何处理长时间未处理的审批？

7.2 创意想法

• 学习用户习惯：自动调整风险判断
• 审批委派：将审批权委托给他人
• 紧急模式：临时降低自主级别

7.3 风险与挑战

• 技术风险: 回滚机制的可靠性
• 安全风险: 自主级别被恶意修改
• 缓解措施: 高风险操作强制审计