Agentswarm/desktop-client/src/ai/README.md

AI 模块 —— 任务复杂度分析

该模块为桌面客户端提供任务复杂度分析能力：根据用户需求评估其规模与难度，推荐应投入的 Agent 数量，作为蜂群规模与成本控制的依据。

组成

1. complexity-analyzer.ts

核心分析器，调用大模型对任务进行复杂度评估并给出推荐 Agent 数量。

特性：

• 结构化 JSON 结果解析，并对非 JSON 响应做兜底解析
• Agent 数量校验（1–50）
• 性能监控（目标单次 < 3 秒）
• 支持批量分析
• 单例模式复用客户端

用法：

import { ComplexityAnalyzer } from './ai';

const analyzer = new ComplexityAnalyzer({ temperature: 0.3 });
const analysis = await analyzer.analyzeTask('为整个项目补充单元测试');
console.log(`推荐 Agent 数：${analysis.agentCount}`);
console.log(`复杂度：${analysis.complexity}`);
console.log(`理由：${analysis.reasoning}`);

2. prompt-builder.ts

基于带标注的数据集构造 few-shot 提示词。

特性：

• 从 test-data/complexity-dataset.json 加载样例
• 按比例选取多样化样例（低 40% / 中 40% / 高 20%）
• 生成完整的 few-shot 提示，批量模式下提供简化提示
• 数据集不可用时回退到内置默认样例

3. validator.ts

对照标注数据集校验分析器的准确率。

特性与验收目标：

• 全量与快速（10 条抽样）校验
• 准确率（精确匹配、±2 个 Agent 容差）与平均绝对误差（MAE）
• 不匹配项报告与 Markdown 报告生成
• 目标：准确率 ≥ 70%（±2 容差）、MAE ≤ 2、单任务分析 < 3 秒

4. validate-analyzer.ts

独立的校验脚本，便于在集成前验证分析器质量：

npm run validate-analyzer

成本控制

分析结果与 CostControlDialog 组件联动，向用户提示资源开销：

• > 10 个 Agent：提示并给出资源预估
• > 15 个 Agent：要求用户显式确认
• 达到上限：遵循用户配置的最大值（默认 20）

数据集格式

标注数据集 test-data/complexity-dataset.json 的样例格式：

[
  {
    "task": "修复 main.py 第 42 行的语法错误",
    "expectedAgents": 1,
    "complexity": "low",
    "reasoning": "单文件单行修复，无依赖与副作用。"
  }
]

实现要点

1. Few-shot 学习：使用数据集中的多样化样例提升判断稳定性。
2. 温度 0.3：降低随机性以获得更一致的预测。
3. 稳健性：解析失败时优雅兜底。
4. 先验证后上线：集成进自动伸缩与任务提交流程前，应先通过校验。