massgen-develops-massgen

MassGen 使用 MassGen 进行开发

本技能提供有关如何使用 MassGen 开发和改进 MassGen 的指导。请根据要测试的内容选择合适的工作流。

两种工作流

1. 自动化模式 - 测试后端功能、协调逻辑和 Agent 响应
2. 视觉评估 - 测试终端显示、颜色、布局和用户体验

---

工作流 1：自动化模式

使用此模式测试功能，无需进行视觉检查。适用于程序化测试。

使用自动化模式运行 MassGen

在后台运行 MassGen（具体方式取决于你使用的工具）：

uv run massgen --automation --config massgen/configs/basic/multi/two_agents_gemini.yaml "What is 2+2?"

对于 MassGen Agent：使用 custom_tool__start_background_tool，目标设为 mcp__command_line__execute_command，然后使用 custom_tool__get_background_tool_status / custom_tool__get_background_tool_result 轮询。 对于 Claude Code：使用 Bash 工具的 run_in_background 参数。

为什么使用自动化模式

特性	优势
输出简洁	约 10 行可解析内容，而非 3,000 多个 ANSI 代码
打印 LOG_DIR	第一行显示日志目录路径
status.json	实时监控文件
退出代码	0=成功，1=配置错误，2=执行错误，3=超时，4=中断
工作区隔离	安全地并行执行

预期输出

LOG_DIR: .massgen/massgen_logs/log_20251120_143022_123456
STATUS: .massgen/massgen_logs/log_20251120_143022_123456/status.json

🤖 Multi-Agent Mode
Agents: gemini-2.5-pro1, gemini-2.5-pro2
Question: What is 2+2?

============================================================
QUESTION: What is 2+2?
[Coordination in progress - monitor status.json for real-time updates]

WINNER: gemini-2.5-pro1
DURATION: 33.4s
ANSWER_PREVIEW: The answer is 4.

COMPLETED: 2 agents, 35.2s total

从第一行解析 LOG_DIR，以查找日志目录。

监控进度

读取 status.json 文件（每 2 秒更新一次）：

cat .massgen/massgen_logs/log_20251120_143022_123456/status.json

关键字段：

{
  "coordination": {
    "completion_percentage": 65,
    "phase": "enforcement"
  },
  "results": {
    "winner": null  // null = running, "agent_id" = done
  },
  "agents": {
    "agent_a": {
      "status": "streaming",
      "error": null
    }
  }
}

Agent 状态值： waiting、streaming、answered、voted、completed、error

读取结果

完成后（退出代码为 0）：

# Read final answer
cat [log_dir]/final/[winner]/answer.txt

时间预期

• 标准任务：2-10 分钟
• 复杂/元任务：10-30 分钟
• 检查是否卡住：读取 status.json——如果 completion_percentage 增加，说明任务正在运行

进阶：多个后台监控器

你可以创建多个独立运行的后台监控任务，与 MassGen 主进程并行执行。每个监控器都可以跟踪不同方面，并将数据写入单独的日志文件，供后续检查。

方法

创建在后台 shell 中运行的小型 Python 脚本。每个脚本：

• 监控特定方面（令牌、错误、进度、协调等）
• 将带时间戳的数据写入自己的日志文件
• 以循环方式运行，并使用 sleep() 间隔
• 可随时检查，不会阻塞主任务

监控脚本示例

令牌用量监控器（token_monitor.py）：

import json, time, sys
from pathlib import Path

log_dir = Path(sys.argv[1])  # Pass LOG_DIR as argument
while True:
    if (log_dir / "status.json").exists():
        with open(log_dir / "status.json") as f:
            data = json.load(f)
        with open("token_monitor.log", "a") as log:
            log.write(f"=== {time.strftime('%H:%M:%S')} ===\n")
            log.write(f"Tokens: {data.get('total_tokens_used', 0)}\n")
            log.write(f"Cost: ${data.get('total_cost', 0):.4f}\n\n")
    time.sleep(5)

错误监控器（error_monitor.py）：

import time, sys
from pathlib import Path

log_dir = Path(sys.argv[1])
while True:
    if log_dir.exists():
        with open("error_monitor.log", "a") as log:
            log.write(f"=== {time.strftime('%H:%M:%S')} ===\n")
            errors = []
            for logfile in log_dir.glob("*.log"):
                with open(logfile) as f:
                    for line in f:
                        if any(x in line.lower() for x in ['error', 'warning', 'failed']):
                            errors.append(line.strip())
            log.write('\n'.join(errors[-5:]) if errors else "No errors\n")
            log.write("\n")
    time.sleep(5)

进度监控器（progress_monitor.py）：

import json, time, sys
from pathlib import Path

log_dir = Path(sys.argv[1])
while True:
    if (log_dir / "status.json").exists():
        with open(log_dir / "status.json") as f:
            data = json.load(f)
        with open("progress_monitor.log", "a") as log:
            log.write(f"=== {time.strftime('%H:%M:%S')} ===\n")
            progress = data.get('completion_percentage', 0)
            active = sum(1 for a in data.get('agents', {}).values()
                        if a.get('status') == 'active')
            log.write(f"Progress: {progress}% Active agents: {active}\n\n")
    time.sleep(5)

协调监控器（coordination_monitor.py）：

import json, time, sys
from pathlib import Path

log_dir = Path(sys.argv[1])
while True:
    if (log_dir / "status.json").exists():
        with open(log_dir / "status.json") as f:
            data = json.load(f)
        coord = data.get('coordination', {})
        with open("coordination_monitor.log", "a") as log:
            log.write(f"=== {time.strftime('%H:%M:%S')} ===\n")
            log.write(f"Phase: {coord.get('phase', 'unknown')}\n")
            log.write(f"Round: {coord.get('round', 0)}\n")
            log.write(f"Total answers: {coord.get('total_answers', 0)}\n\n")
    time.sleep(5)

工作流

1. 启动主任务，从输出中解析 LOG_DIR
2. 按需创建监控脚本（编写 Python 文件）
3. 在后台 shell 中启动监控器：python3 token_monitor.py [LOG_DIR] &
4. 随时检查监控日志，读取 .log 文件即可
5. 完成后，终止监控进程并分析日志

自定义监控器

为想要跟踪的任何指标创建监控器：

• 特定模型的性能指标
• 内存/上下文用量模式
• 实时成本累积
• 回答质量趋势
• Agent 协调模式
• 特定错误类别

优势：

• 按需检查特定指标，不会造成阻塞
• 留存历史数据，便于运行后分析
• 针对不同方面设置独立的监控流
• 无需修改配置即可轻松添加新监控器

---

工作流 2：视觉评估

使用此工作流分析并改进 MassGen 的终端显示质量。需要使用 custom_tools/_multimodal_tools/ 中的工具。

重要： 此工作流会录制丰富的终端显示内容，因此实际录制时不会使用 --automation 模式。不过，务必先使用 --automation 进行预测试。

前提条件

工作区中应提供以下工具：

• run_massgen_with_recording - 将终端会话录制为视频
• understand_video - 使用 GPT-4.1 视觉功能分析视频帧

步骤 0：通过自动化进行预测试（必需）

录制视频前，验证配置是否正常，以及 API 密钥是否有效：

# Start with --automation to verify everything works
uv run massgen --automation --config [config_path] "[question]"

等待 30-60 秒（足以验证 API 密钥、解析配置并初始化工具），然后终止进程。

这一步至关重要：

• 在浪费录制时间前发现配置错误
• 验证 API 密钥是否存在且可用
• 确保工具能够正确初始化
• 避免录制出有问题的会话

如果自动化测试失败，请先解决问题，再开始录制。

步骤 1：录制 MassGen 会话

自动化预测试成功后，录制可视化会话：

from custom_tools._multimodal_tools.run_massgen_with_recording import run_massgen_with_recording

result = await run_massgen_with_recording(
    config_path="massgen/configs/basic/multi/two_agents_gemini.yaml",
    question="What is 2+2?",
    output_format="mp4",  # ALWAYS use mp4 for maximum compatibility
    timeout_seconds=120,
    width=1920,
    height=1080
)

格式建议：始终使用 "mp4"，以获得最佳兼容性。支持 GIF 和 WebM，但优先使用 MP4。

录制内容：丰富的终端显示，包括颜色、状态指示器和协调过程可视化（不使用 --automation 标志）。

步骤 2：分析录制内容

使用 understand_video 分析 MP4 录制内容。 至少调用一次，也可以多次调用，以分析不同方面：

from custom_tools._multimodal_tools.understand_video import understand_video

# Overall UX evaluation
ux_eval = await understand_video(
    video_path=result["video_path"],  # The MP4 file from Step 1
    prompt="Evaluate the overall terminal display quality, clarity, and usability",
    num_frames=12
)

# Focused on coordination
coordination_eval = await understand_video(
    video_path=result["video_path"],
    prompt="How clearly does the display show agent coordination phases and voting?",
    num_frames=8
)

# Status indicators
status_eval = await understand_video(
    video_path=result["video_path"],
    prompt="Are status indicators (streaming, answered, voted) clear and visually distinct?",
    num_frames=8
)

要点：

• 录制工具会将视频保存到工作区；使用该路径进行分析
• 可以使用不同的提示词，多次调用 understand_video 分析同一视频
• 每次调用都聚焦于特定方面（用户体验、协调过程、状态、颜色等）

评估标准

分析终端显示时，请评估：

1. 视觉清晰度 - 对比度、颜色、字体渲染、ANSI 处理、间距
2. 信息组织 - 布局、内容密度、流式显示、滚动处理
3. 状态指示器 - Agent 状态、进度跟踪、阶段转换、获胜者选择
4. 用户体验 - 实时反馈、错误可见性、认知负荷、信息层级

输出格式建议

默认使用 MP4，兼顾最佳兼容性和质量。

格式	使用场景	说明
MP4	默认格式——所有情况都使用	质量最佳、普遍受支持，非常适合详细分析
GIF	文件较小，便于嵌入	质量较低，文件通常比预期更大；除非受文件大小限制，否则避免使用
WebM	面向现代 Web 发布	质量良好，但并非普遍受支持

经验法则：除非有特定理由，否则使用 MP4。

帧数指南

帧数	使用场景
4-8	快速评估
8-12	标准评估
12-16+	详细分析

---

要测试哪些配置

模型选择指南

生成配置或运行实验时，默认选择中端模型。 对于开发和测试，这类模型在成本、速度和能力之间最为均衡。

重要：务必根据今天的日期检查模型的新近程度。 发布超过 6-12 个月的模型应视为过时。

如何选择模型

步骤 1：读取后端文件，检查发布日期

# Check Gemini models and their release dates
grep -A 5 "model.*2\." massgen/backend/gemini.py

# Check OpenAI models and their release dates
grep -A 5 "model.*gpt" massgen/backend/openai.py

# Check Claude models and their release dates
grep -A 5 "model.*claude" massgen/backend/claude.py

步骤 2：检查令牌成本

cat docs/source/reference/token_budget.rst | grep -A 3 "gemini\|gpt\|claude"

步骤 3：对照今天的日期比较发布日期

• 计算自发布以来的月数：（今年-本月）-（模型发布年份-月份）
• 如果 > 12 个月：模型已过时
• 如果为 6-12 个月：模型正在老化；如有更新的模型，优先选择更新的模型
• 如果 < 6 个月：模型是当前版本

模型选择示例

✅ 良好（近期的中端模式）：

• Gemini：gemini-2.5-pro、gemini-2.5-flash（2.x 系列，2025）
• OpenAI：gpt-5-mini、gpt-4o-mini（GPT-5 代）
• Claude：claude-sonnet-4-*（4.x 系列，2025）

⚠️ 不佳（过时模式——请查看日期！）：

• ❌ gpt-4o（2024 年发布——可能已超过 12 个月）
• ❌ gpt-4-turbo（2023 至 2024 年）
• ❌ gemini-1.5-pro（1.x 系列已被 2.x 取代）
• ❌ claude-3.5-sonnet（已有 4.x 系列，却仍使用 3.x 系列）

选择标准：

• 近期性：在过去 6 至 12 个月内发布（务必查看后端文件中的日期）
• 中端定价：非顶级（昂贵）或入门级（便宜）
• 普遍可用：稳定版本，而非实验版、预览版或 alpha 版
• 版本号：主版本号越高，版本越新（gemini-2.x > gemini-1.x、gpt-5 > gpt-4、claude-4 > claude-3）

偏离标准的情况：

• 高级模型：测试模型能力上限（例如，gpt-5、claude-opus-4、gemini-3-pro）
• 经济型模型：进行成本优化实验（例如，gpt-5-mini、gemini-2.5-flash）
• 旧版测试：验证与旧模型的向后兼容性

生成配置（适用于 Agent）

使用 --generate-config 以编程方式生成配置：

# WORKFLOW:
# 1. Read backend file to find recent mid-tier models
# 2. Verify release date (< 12 months old)
# 3. Check pricing tier (mid-range)
# 4. Use model in --config-model flag

# Example: Generate 2-agent config
massgen --generate-config ./test_config.yaml \
  --config-backend gemini \
  --config-model gemini-2.5-pro \  # (example - always verify this is current!)
  --config-agents 2 \
  --config-docker

# With context path
massgen --generate-config ./test_config.yaml \
  --config-backend openai \
  --config-model gpt-5-mini \  # (example - always verify this is current!)
  --config-context-path /path/to/project

重要：上方显示的模型名称仅为示例。请务必根据当天日期检查后端文件，确认当前可用模型。

这会创建一个功能齐全的配置，其中启用了基于代码的工具、技能和任务规划。

测试特定功能

修改生成的配置以启用或禁用功能：

代码执行：

agents:
  - backend:
      enable_mcp_command_line: true
      command_line_execution_mode: "docker"

自定义工具：

agents:
  - backend:
      enable_code_based_tools: true
      auto_discover_custom_tools: true

为不同 Agent 配置不同模型：

agents:
  - backend: {type: "gemini", model: "gemini-2.5-pro"}
  - backend: {type: "openai", model: "gpt-5-mini"}

常用参数：enable_code_based_tools、enable_mcp_command_line、command_line_execution_mode、auto_discover_custom_tools、timeout_settings

---

Docker 注意事项

自动检测 Docker

MassGen 会自动检测是否在 Docker 容器内运行。如果配置中设有 command_line_execution_mode: "docker"，MassGen 将：

1. 检测容器环境（通过 /.dockerenv）
2. 自动切换到 "local" 执行模式
3. 记录日志："Already running inside Docker container - switching to local execution mode"

**原理：**外层容器已经提供了隔离。在该容器内“本地”运行是安全且经过沙盒隔离的。

无需手动配置——在容器内运行时，采用 Docker 模式的配置即可正常工作。

权衡

自动切换到本地执行时：

• ✅ 仍与宿主机隔离
• ✅ 所有功能均可用（VHS、MassGen 和工具都在容器中）
• ⚠️ 工具调用之间没有单次执行级别的隔离
• ⚠️ 状态会在容器会话中持续保留

---

参考文件

• 状态文件文档：docs/source/reference/status_file.rst
• 终端评估文档：docs/source/user_guide/terminal_evaluation.rst
• 示例配置：massgen/configs/basic/、massgen/configs/meta/
• 录制工具：massgen/tool/_multimodal_tools/run_massgen_with_recording.py
• 视频分析工具：massgen/tool/_multimodal_tools/understand_video.py