massgen

MassGen 技能

将任务委派给你的 MassGen 团队。

启动前

检查是否存在配置：

ls .massgen/config.yaml 2>/dev/null || ls ~/.config/massgen/config.yaml 2>/dev/null

如果不存在配置，请进行设置：

• 默认（浏览器）：运行 uv run massgen --web-quickstart — 用户在浏览器中选择 模型和密钥
• 无头模式：阅读 references/config_setup.md — 通过 --list-backends 查找可用的 后端，检查用户的 API 密钥，讨论偏好设置，并使用 --quickstart --headless 生成配置

如果配置已存在 — 立即启动。无需先提问。

重要：只添加用户要求的内容

除非用户明确要求，否则不要添加额外标志：

• 除非用户要求采用多种方法，否则不要使用 --personas
• 除非用户需要详细拆解，否则不要使用 --plan-depth deep
• 除非用户希望速度优先于质量，否则不要使用 --quick

默认设置已经足够。其余交给 MassGen 处理。

快速分派

1. 检测模式

用户意图	CLI 标志
常规任务（编写、构建、研究、设计）	(默认)
审查/评估现有成果	--checklist-criteria-preset evaluation
规划功能或项目	--plan
规划并自动执行	--plan-and-execute
编写需求/规格说明	--spec
执行现有计划	--execute-plan <path_or_latest>
根据现有规格说明执行	--execute-spec <path_or_latest>

2. 编写标准

始终编写有主见且适合任务的评估标准。 标准会影响 Agent 产出的内容，而不只是评分方式。保存到临时文件，并通过 --eval-criteria 传入。建议设置 4-7 条标准。

必需的 JSON 格式 — 每条标准都需要包含 text、category 和 anti_patterns：

{
  "aspiration": "A site a designer would screenshot for their portfolio",
  "criteria": [
    {
      "text": "Design coherence: Does it feel authored or assembled? ...",
      "category": "primary",
      "anti_patterns": ["unmodified library defaults", "AI-generic aesthetics"]
    },
    {
      "text": "Content depth: Every section teaches something specific ...",
      "category": "standard",
      "anti_patterns": ["Wikipedia-summary prose", "filler sections"]
    }
  ]
}

类别：primary（一个 — 模型最需要着力突破的方向）、standard （必须通过）、stretch（锦上添花）。有关如何编写有效且有主见的标准的完整指南，请参阅 references/criteria_guide.md。

对于评估/规划/规格说明模式，可以使用 --checklist-criteria-preset 代替自定义标准（预设：evaluation、planning、spec、 persona、decomposition、prompt、analysis）。

3. 编写提示词

常规任务：用户的任务及相关背景信息。

评估：要评估的内容。自动收集 git diff、变更文件和测试 输出。保持客观 — 说明构建了什么，而非表达你对质量的看法。让 Agent 独立发现问题。

规划：目标 + 约束条件。

规格说明：问题陈述 + 用户需求 + 约束条件。

4. 选择 CWD 上下文

如果任务会产出文件，默认使用 rw。 如果交付物是文件 （代码、文档、配置、README、网站等），Agent 需要写入权限。仅当 Agent 需要 读取代码库以了解背景，而输出是纯文本（答案、审查或分析）——而非文件时，才使用 ro。

场景	标志
任务会在项目中生成/修改文件（代码、文档、配置等）	--cwd-context rw
任务需要代码库上下文，但输出仅为文本（审查、分析、问答）	--cwd-context ro
独立任务，无需代码库（默认）	(省略标志)

经验法则：如果用户要求在项目中“编写”、“创建”、“构建”、“重写”、 “更新”或“编辑”某些内容 → rw。

5. 运行

始终使用包装脚本：

# Isolated task (default, no cwd-context needed)
bash "$SKILL_DIR/scripts/massgen_run.sh" \
  --mode general \
  --criteria /tmp/massgen_criteria.json \
  "Create an SVG of a butterfly mixed with a panda"

# Task that writes to the project → rw
bash "$SKILL_DIR/scripts/massgen_run.sh" \
  --mode general --cwd-context rw \
  --criteria /tmp/massgen_criteria.json \
  "Rewrite the README with better examples and structure"

包装脚本默认包含 --web --no-browser。运行会立即开始 — 用户可以随时打开 http://localhost:8000/ 查看 进度。请告知用户此 URL。

在后台运行。MassGen 会输出以下信息以便跟踪：

• LOG_DIR: <path> — 完整运行数据
• STATUS: <path>/status.json — 实时状态
• ANSWER: <path> — 获胜 Agent 的 answer.txt

多轮运行预计需要 15-45 分钟。

5b. 审核通知（当使用 --cwd-context rw 时）

当 Agent 具有写入权限（--cwd-context rw）时，自动添加 --web-review，以便用户在应用更改前审核 git 差异。 审核需要 --web（封装器默认启用）。

无头模式（--no-web）：如果用户明确要求在 --cwd-context rw 下使用无头模式，则跳过 --web-review——直接应用更改， 不设审核关卡。提醒用户不会审核差异。

启动 MassGen 运行后，还要在后台启动审核监视器。先从 MassGen 输出中解析 LOG_DIR：

# Launch the watcher (reads LOG_DIR from the MassGen run output)
bash "$SKILL_DIR/scripts/review_watcher.sh" "$LOG_DIR"

监视器会轮询 status.json，并在审核就绪时打印结构化标记：

__REVIEW_PENDING__
REVIEW_URL: http://localhost:8000/?v=2
REVIEW_API: http://localhost:8000/api/sessions/{id}/review-response
FILES_CHANGED: src/foo.py (M), src/bar.py (A)
__END_REVIEW_INFO__

看到 __REVIEW_PENDING__ 时，告诉用户：

“MassGen 已准备好待审核的更改。你可以打开 WebUI 直观地审核差异，或告诉我批准／拒绝哪些文件。”

两种处理方式：

1. 浏览器：用户打开 REVIEW_URL，并在界面中批准／拒绝。
2. Agent（基于文本）：通过 GET /api/sessions/{id}/review 获取差异， 向用户展示摘要，然后提交其决定：

   # Approve all
   curl -X POST "$REVIEW_API" -H "Content-Type: application/json" \
     -d '{"approved": true, "action": "approve"}'
   # Approve specific files
   curl -X POST "$REVIEW_API" -H "Content-Type: application/json" \
     -d '{"approved": true, "approved_files": ["src/foo.py"]}'
   # Reject all
   curl -X POST "$REVIEW_API" -H "Content-Type: application/json" \
     -d '{"approved": false, "action": "reject"}'
   

任一方式都会完成审核，另一方会自动关闭。处理完成后，会打印 __REVIEW_COMPLETE__ APPROVED=true|false。

6. 读取结果

读取输出中的 ANSWER: 路径。获胜 Agent 的工作区始终位于 answer.txt 旁边的 workspace/ 目录中。

answer.txt 中的工作区路径会尽力规范化为指向相邻的 workspace/ 目录。不过，始终应以 answer.txt 旁边的 workspace/ 目录为准——不要使用文本中提到的路径。

对于 plan 模式，project_plan.json 位于工作区中。 对于 spec 模式，project_spec.json 位于工作区中。

可选标志（仅在用户要求时使用）

标志	用途
--quick	单次运行，不进行投票／优化
--plan-depth <level>	分解深度：dynamic（默认）、shallow、medium、deep
--plan-thoroughness thorough	更深入的战略推理（默认：standard）
--personas <style>	Agent 多样性：perspective、implementation、methodology 或 off
--cwd-context ro	授予 Agent 对代码库的读取权限
--cwd-context rw	授予 Agent 对代码库的写入权限
--web --no-browser	启用 WebUI 以查看进度（封装器默认启用）

配置

MassGen 会自动从 .massgen/config.yaml 或 ~/.config/massgen/config.yaml 发现配置。请参阅上文的设置说明。

参考资料

仅在快速调度不足以解决问题时查阅：

文件	适用场景
references/criteria_guide.md	标准格式、层级、示例
references/config_setup.md	创建无头配置
references/advanced_workflows.md	检查点循环、持续更新的文档、结构化评估、计划与评估集成