LocalAgent/docs/P1-07_数据治理方案.md

P1-07 数据治理优化方案

问题概述

问题标题: 历史记录明文持久化完整输入/代码/输出，缺少治理策略
问题类型: 安全/数据一致性
所在位置: history/manager.py:16, history/manager.py:69, ui/history_view.py:652
影响分析: 本地泄露面扩大，调试日志可能含敏感路径/内容

解决方案

1. 数据脱敏模块 (history/data_sanitizer.py)

功能特性:

• 支持 10+ 种敏感信息类型识别（文件路径、邮箱、电话、API密钥、密码等）
• 智能脱敏策略（保留部分信息以便调试）
• 敏感度评分算法（0-1分值）
• 避免误判的特殊验证机制

核心能力:

# 敏感信息检测
matches = sanitizer.find_sensitive_data(text)

# 文本脱敏
sanitized_text, matches = sanitizer.sanitize(text)

# 敏感度评分
score = sanitizer.get_sensitivity_score(text)  # 0.0 - 1.0

2. 数据治理策略模块 (history/data_governance.py)

三级分类保存:

数据级别	敏感度阈值	保留期	处理方式
FULL（完整）	< 0.3	90天	无脱敏，完整保存
SANITIZED（脱敏）	0.3 - 0.7	30天	敏感字段脱敏
MINIMAL（最小化）	≥ 0.7	7天	仅保留元数据

生命周期管理:

• 自动过期检查
• 分级降级策略（完整→脱敏→归档→删除）
• 归档目录独立存储

度量指标收集:

• 各级别记录数量统计
• 敏感字段命中率
• 存储空间占用
• 过期记录数量

3. 历史记录管理器增强 (history/manager.py)

集成治理功能:

• 保存时自动应用治理策略
• 启动时自动清理过期数据
• 支持手动触发清理
• 导出脱敏数据功能

新增方法:

# 手动清理
stats = manager.manual_cleanup()
# 返回: {'archived': 5, 'deleted': 3, 'remaining': 92}

# 获取治理指标
metrics = manager.get_governance_metrics()

# 导出脱敏数据
count = manager.export_sanitized(output_path)

4. 治理监控面板 (ui/governance_panel.py)

可视化界面:

• 实时治理指标展示
• 一键执行数据清理
• 导出脱敏数据
• 打开归档目录
• 策略说明展示

5. 完整测试套件 (tests/test_data_governance.py)

测试覆盖:

• 数据脱敏器测试（10+ 测试用例）
• 治理策略测试（分类、过期、清理）
• 历史管理器集成测试
• 导出功能测试

度量指标

建议监控指标

1. 数据体积指标

   • 总记录数
   • 各级别记录占比
   • 存储空间占用（MB）

2. 敏感字段命中率

   • 各字段敏感信息检出次数
   • 敏感度分布统计

3. 过期清理完成率

   • 待清理记录数
   • 归档成功率
   • 删除完成率
   • 最后清理时间

4. 治理效果指标

   • 脱敏覆盖率
   • 数据降级次数
   • 归档文件数量

使用示例

基础使用（自动治理）

from history.manager import get_history_manager

# 获取管理器（自动启用治理）
manager = get_history_manager()

# 添加记录时自动分类和脱敏
record = manager.add_record(
    task_id='task-001',
    user_input='读取配置文件 /etc/config.json',
    code='with open("/etc/config.json") as f: ...',
    # ... 其他字段
)

# 记录会自动：
# 1. 分析敏感度
# 2. 应用对应级别的治理策略
# 3. 添加治理元数据
# 4. 保存时收集度量指标

手动清理

# 手动触发清理
stats = manager.manual_cleanup()
print(f"归档: {stats['archived']}, 删除: {stats['deleted']}")

导出脱敏数据

from pathlib import Path

# 导出用于分享或备份
count = manager.export_sanitized(Path("history_sanitized.json"))
print(f"已导出 {count} 条脱敏记录")

查看治理指标

metrics = manager.get_governance_metrics()
print(f"总记录: {metrics.total_records}")
print(f"完整保存: {metrics.full_records}")
print(f"脱敏保存: {metrics.sanitized_records}")
print(f"存储占用: {metrics.total_size_bytes / 1024 / 1024:.2f} MB")

安全改进

改进前

• ❌ 明文保存所有敏感信息
• ❌ 无数据分级策略
• ❌ 无过期清理机制
• ❌ 无敏感信息检测
• ❌ 无度量指标

改进后

• ✅ 自动识别并脱敏 10+ 种敏感信息
• ✅ 三级分类保存（完整/脱敏/最小化）
• ✅ 自动过期清理和归档
• ✅ 敏感度评分和分级
• ✅ 完整的度量指标体系
• ✅ 可视化监控面板
• ✅ 导出脱敏数据功能

配置选项

可在 history/manager.py 中调整：

class HistoryManager:
    MAX_HISTORY_SIZE = 100  # 最大记录数
    AUTO_CLEANUP_ENABLED = True  # 自动清理开关

可在 history/data_governance.py 中调整：

# 分级阈值
LEVEL_THRESHOLDS = {
    DataLevel.FULL: 0.0,
    DataLevel.SANITIZED: 0.3,
    DataLevel.MINIMAL: 0.7,
}

# 保留期配置
RETENTION_CONFIG = {
    DataLevel.FULL: 90,       # 天
    DataLevel.SANITIZED: 30,
    DataLevel.MINIMAL: 7,
}

运行测试

python tests/test_data_governance.py

预期输出：

• 数据脱敏器测试：6+ 通过
• 数据治理策略测试：5+ 通过
• 历史管理器测试：5+ 通过

总结

本方案通过四个核心模块实现了完整的数据治理体系：

1. 自动化: 保存时自动分类、脱敏、清理
2. 分级管理: 根据敏感度三级保存，差异化保留期
3. 可观测: 完整的度量指标和可视化面板
4. 可控性: 支持手动清理、导出、归档管理

有效降低了本地数据泄露风险，同时保持了调试和追溯能力。