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 优化前后对比

优化前（错误做法）：

# AGENTS.md

## 团队成员详情

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

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

优化后（正确做法）：

# 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：大段内联内容检测

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：重复内容检测

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：引用缺失检测

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 优化建议报告格式

# 配置文件优化报告

**检查时间**: 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 扫描脚本

#!/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 自动优化脚本

#!/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 配置

# 每周日凌晨 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 回滚机制

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

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

8.3 变更日志

# 配置文件优化日志

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

---

九、实施步骤

阶段 1：工具开发（本周）

• 编写检测规则脚本
• 编写自动优化脚本
• 编写报告生成脚本
• 测试工具链

阶段 2：首次优化（下周）

• 运行首次全面扫描
• 生成基线报告
• 人工审批后执行首批优化
• 验证优化效果

阶段 3：自动化（持续）

• 配置 Cron 定时任务
• 配置飞书通知
• 建立回滚和审计机制

---

十、补充材料

10.1 检测脚本

已实现：

• scripts/detect_redundancy.py - 配置文件冗余检测脚本
• 用法：python3 scripts/detect_redundancy.py AGENTS.md SOUL.md

10.2 优化示例

• examples/optimized-AGENTS.md - 优化后的 AGENTS.md 示例
• 展示「引用代替填塞」的实际效果
• Token 从 ~4,000 降低到 ~500（节省 87.5%）

10.3 OpenClaw Cron 集成

使用 OpenClaw 的 cron 工具实现定时任务：

{
  "name": "配置文件每周检查",
  "schedule": {
    "kind": "cron",
    "expr": "0 2 * * 0",
    "tz": "Asia/Shanghai"
  },
  "payload": {
    "kind": "agentTurn",
    "message": "执行配置文件冗余检查，运行 scripts/detect_redundancy.py 并生成报告"
  },
  "sessionTarget": "isolated",
  "delivery": {
    "mode": "announce",
    "channel": "feishu",
    "to": "ou_9f73b4e54af59f038e2b754793ea0908"
  }
}

---

十一、交付物清单

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

---

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