EnterpriseArchitect/plans/BIZ-15_配置文件持续优化方案.md

# BIZ-15 智能体配置文件持续优化方案

> 版本：v1.0  
> 编制：陆怀瑾（COO）  
> 日期：2026-06-22  
> 状态：待审阅

---

## 一、目标

建立配置文件持续优化机制，通过定时任务每周检查并优化所有智能体的配置文件，核心策略是**"引用代替填塞"**，避免 Token 无谓增长。

---

## 二、问题分析

### 2.1 当前配置文件的 Token 浪费

| 文件 | 典型问题 | Token 浪费 |
|------|----------|----------|
| AGENTS.md | 嵌入全部 Agent 详细信息 | 3000+ tokens |
| SOUL.md | 嵌入完整的 SOP 模板 | 2000+ tokens |
| TOOLS.md | 嵌入工具使用详情 | 1500+ tokens |
| MEMORY.md | 未归档的历史记忆堆积 | 5000+ tokens |

**总计浪费**：~11,500 tokens/Agent

### 2.2 根本原因

1. **内联而非引用**：详细内容直接写入配置文件，而非引用外部文档
2. **缺乏归档机制**：历史记忆不断累积，从不归档清理
3. **无优化检查**：没有定期检查和优化机制

---

## 三、核心策略：引用代替填塞

### 3.1 优化前后对比

**优化前（错误做法）**：
```markdown
# AGENTS.md

## 团队成员详情

### 刘诗妮（secretary）
- Feishu ID: ou_6201fa2f987300046ca659cf231f1d3f
- 核心职能：业务入口、进度跟进、飞书对接
- 工作模式：不进项目，专职支持 Vincent
- 可用时间：工作日 9:00-18:00
- 技能清单：...
- 联系方式：...
（每个 Agent 都有 300+ tokens 的详细信息）

### 陆怀瑾（coo）
...
（共 12 个 Agent，总计 3600+ tokens）
```

**优化后（正确做法）**：
```markdown
# AGENTS.md

## 团队成员详情

完整 Agent 信息请参阅：[docs/agent-roster.md](docs/agent-roster.md)

核心协作协议：
| Agent | 核心职能 | 何时联系 |
|-------|----------|----------|
| secretary | 业务入口/进度跟进 | 任务接收、结果汇报 |
| coo | 资源协调/风险 | 资源协调、风险识别 |
...
（仅保留核心协作表，200 tokens）
```

### 3.2 可外部化的内容

| 配置文件 | 可外部化内容 | 外部文档路径 |
|----------|--------------|--------------|
| AGENTS.md | Agent 详细信息 | docs/agent-roster.md |
| AGENTS.md | 协作流程图 | docs/collaboration-flow.md |
| SOUL.md | SOP 模板 | docs/sop-templates/ |
| SOUL.md | 个性描述详情 | docs/persona-details/ |
| TOOLS.md | 工具使用详情 | docs/tools-reference.md |
| MEMORY.md | 超过 30 天的记忆 | memory/archive/YYYY-MM/ |

---

## 四、每周优化流程

### 4.1 流程概览

```
定时任务触发（每周日凌晨 2:00）
    ↓
扫描所有 Agent 配置文件
    ↓
检测内联冗余内容
    ↓
生成优化建议报告
    ↓
┌─────┴─────┐
│           │
自动优化   需人工审批
(低风险)   (高风险)
    ↓           ↓
执行优化   COO 审批 → 执行
    ↓
更新优化日志
    ↓
通知 COO
```

### 4.2 检测规则

#### 规则 1：大段内联内容检测

```python
def detect_inline_blocks(file_path):
    """检测超过 N 行的内联内容块"""
    with open(file_path) as f:
        lines = f.readlines()
    
    blocks = []
    current_block = []
    in_code_block = False
    
    for i, line in enumerate(lines):
        if line.startswith('```'):
            in_code_block = not in_code_block
            continue
        
        if in_code_block:
            continue
        
        # 检测密集内容（无空行的连续行）
        if line.strip() and (not current_block or lines[i-1].strip()):
            current_block.append((i+1, line))
        else:
            if len(current_block) >= 20:  # 20 行阈值
                blocks.append({
                    'start': current_block[0][0],
                    'end': current_block[-1][0],
                    'lines': len(current_block),
                    'preview': ''.join([l for _, l in current_block[:5]])
                })
            current_block = []
    
    return blocks
```

#### 规则 2：重复内容检测

```python
def detect_duplicates(config_files):
    """检测多个配置文件中的重复内容"""
    content_hashes = {}
    duplicates = []
    
    for file_path in config_files:
        with open(file_path) as f:
            content = f.read()
        
        # 分块计算 hash
        blocks = split_into_blocks(content)
        for block in blocks:
            h = hash(block)
            if h in content_hashes:
                duplicates.append({
                    'content': block[:100] + '...',
                    'files': [content_hashes[h], file_path]
                })
            else:
                content_hashes[h] = file_path
    
    return duplicates
```

#### 规则 3：引用缺失检测

```python
def detect_missing_refs(file_path, docs_dir):
    """检测应该引用但未引用的外部文档"""
    known_externalizable = [
        'SOP 模板', '岗位说明书', '工具详情', '流程图', '检查清单'
    ]
    
    with open(file_path) as f:
        content = f.read()
    
    missing = []
    for keyword in known_externalizable:
        if keyword in content and 'docs/' not in content:
            missing.append({
                'keyword': keyword,
                'suggestion': f'建议创建 docs/{keyword_to_filename(keyword)}.md 并引用'
            })
    
    return missing
```

### 4.3 优化建议报告格式

```markdown
# 配置文件优化报告

**检查时间**: 2026-06-22 02:00
**检查范围**: 所有 Agent 配置文件

---

## 概览

| 指标 | 数值 |
|------|------|
| 检查文件数 | 7 × 12 Agent = 84 |
| 发现冗余块 | 23 |
| 可优化 Token | 15,000 |
| 高风险变更 | 3 |

---

## 详细建议

### AGENTS.md (coo)

#### 建议 1：外部化 Agent 详情
- **位置**: 第 15-230 行
- **内容**: 12 个 Agent 的详细信息
- **建议**: 移动到 docs/agent-roster.md，AGENTS.md 仅保留协作表
- **节省**: 3,400 tokens
- **风险**: 低（只读引用）

#### 建议 2：外部化协作流程
- **位置**: 第 245-300 行
- **内容**: 开发 SOP 详细流程
- **建议**: 移动到 docs/sop-development.md，AGENTS.md 仅保留引用
- **节省**: 800 tokens
- **风险**: 低

---

### SOUL.md (secretary)

#### 建议 3：外部化 SOP 模板
- **位置**: 第 50-150 行
- **内容**: 完整 SOP 模板
- **建议**: 移动到 docs/sop-template.md，SOUL.md 仅保留引用
- **节省**: 1,500 tokens
- **风险**: 中（其他 Agent 可能引用）

---

## 自动优化建议

以下建议可自动执行（低风险）：
- [ ] 建议 1：外部化 Agent 详情
- [ ] 建议 2：外部化协作流程

以下建议需人工审批（中高风险）：
- [ ] 建议 3：外部化 SOP 模板（需确认无其他引用）

---

## 执行日志

执行后将在此处记录：
- 执行的优化项
- 跳过的优化项及原因
- Token 节省统计
```

---

## 五、优化工具实现

### 5.1 扫描脚本

```bash
#!/bin/bash
# optimize-configs.sh - 配置文件优化扫描脚本

WORKSPACE="/home/vincent/.openclaw/workspace/coo"
REPORT_FILE="$WORKSPACE/reports/$(date +%Y-%m-%d)_配置优化报告.md"

echo "# 配置文件优化报告" > "$REPORT_FILE"
echo "" >> "$REPORT_FILE"
echo "**检查时间**: $(date '+%Y-%m-%d %H:%M')" >> "$REPORT_FILE"

# 扫描所有 Agent 目录
for agent_dir in "$WORKSPACE"/agent-*/; do
    agent_name=$(basename "$agent_dir")
    echo "扫描 $agent_name..."
    
    # 检查各配置文件
    for config in AGENTS.md SOUL.md TOOLS.md MEMORY.md; do
        if [ -f "$agent_dir/$config" ]; then
            # 运行检测规则
            python3 detect_redundancy.py "$agent_dir/$config" >> "$REPORT_FILE"
        fi
    done
done

echo "报告已生成：$REPORT_FILE"
```

### 5.2 自动优化脚本

```python
#!/usr/bin/env python3
# auto-optimize.py - 自动执行低风险优化

import sys
import os

def extract_and_replace(file_path, start_line, end_line, external_doc_path):
    """提取内容到外部文档，并替换为引用"""
    
    # 读取原文件
    with open(file_path, 'r') as f:
        lines = f.readlines()
    
    # 提取内容
    extracted = ''.join(lines[start_line-1:end_line])
    
    # 写入外部文档
    os.makedirs(os.path.dirname(external_doc_path), exist_ok=True)
    with open(external_doc_path, 'w') as f:
        f.write(extracted)
    
    # 替换为引用
    ref_line = f"\n详细内容请参阅：[{external_doc_path}]({external_doc_path})\n"
    new_lines = lines[:start_line-1] + [ref_line] + lines[end_line:]
    
    with open(file_path, 'w') as f:
        f.writelines(new_lines)
    
    return len(extracted.split())  # 返回节省的字数估算
```

---

## 六、定时任务配置

### 6.1 Cron 配置

```cron
# 每周日凌晨 2:00 执行配置文件优化检查
0 2 * * 0 /home/vincent/.openclaw/workspace/coo/scripts/optimize-configs.sh
```

### 6.2 任务执行流程

```
Cron 触发
    ↓
运行扫描脚本
    ↓
生成优化报告
    ↓
检查是否有低风险优化项
    ↓
┌─────┴─────┐
│           │
有          无
│           │
自动执行   仅通知
    ↓
更新报告
    ↓
通知 COO（飞书）
```

---

## 七、Token 节省估算

### 7.1 预期效果

| 配置文件 | 优化前 | 优化后 | 节省 |
|----------|--------|--------|------|
| AGENTS.md | 4,000 | 500 | 87.5% |
| SOUL.md | 3,500 | 800 | 77% |
| TOOLS.md | 2,500 | 400 | 84% |
| MEMORY.md | 5,000 | 2,000 | 60% |
| **总计/Agent** | **15,000** | **3,700** | **75%** |

### 7.2 全局影响

- **12 个 Agent** × 11,300 tokens = **135,600 tokens** 节省
- **每次对话** 节省上下文，提升响应速度
- **降低成本**：减少 Token 使用量

---

## 八、风险控制

### 8.1 风险等级划分

| 等级 | 标准 | 处理方式 |
|------|------|----------|
| 低 | 仅影响当前 Agent 的只读引用 | 自动执行 |
| 中 | 可能影响其他 Agent 的共享内容 | COO 审批 |
| 高 | 核心配置变更 | Vincent 审批 |

### 8.2 回滚机制

```bash
# 每次优化前自动备份
backup_file="$file_path.backup.$(date +%Y%m%d%H%M%S)"
cp "$file_path" "$backup_file"

# 如需回滚
cp "$backup_file" "$file_path"
```

### 8.3 变更日志

```markdown
# 配置文件优化日志

| 日期 | Agent | 文件 | 优化项 | 节省 Token | 执行者 |
|------|-------|------|--------|------------|--------|
| 2026-06-22 | coo | AGENTS.md | 外部化 Agent 详情 | 3,400 | auto |
| 2026-06-22 | coo | AGENTS.md | 外部化协作流程 | 800 | auto |
```

---

## 九、实施步骤

### 阶段 1：工具开发（本周）
- [ ] 编写检测规则脚本
- [ ] 编写自动优化脚本
- [ ] 编写报告生成脚本
- [ ] 测试工具链

### 阶段 2：首次优化（下周）
- [ ] 运行首次全面扫描
- [ ] 生成基线报告
- [ ] 人工审批后执行首批优化
- [ ] 验证优化效果

### 阶段 3：自动化（持续）
- [ ] 配置 Cron 定时任务
- [ ] 配置飞书通知
- [ ] 建立回滚和审计机制

---

## 十、交付物清单

- [ ] 配置文件优化检测脚本
- [ ] 自动优化工具
- [ ] 优化报告模板
- [ ] Cron 定时任务配置
- [ ] 变更日志模板
- [ ] 回滚脚本

---

> ⚠️ 本方案需 Vincent 审阅后方可实施。审阅前不修改任何 Agent 配置文件。