massgen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MassGen Skill

Delegate tasks to your MassGen team.

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

Before You Launch

启动前检查

Check that a config exists:

bash

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

If no config exists, set one up:

Default (browser): run
```
uv run massgen --web-quickstart
```
— user picks models and keys in the browser
Headless: read
```
references/config_setup.md
```
— you discover available backends via
```
--list-backends
```
, check the user's API keys, discuss preferences, and generate config with
```
--quickstart --headless
```

If config exists — launch immediately. No need to ask questions first.

检查是否存在配置文件：

bash

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
```
生成配置

如果配置已存在 —— 直接启动即可，无需提前询问用户。

Important: Only Add What's Asked

重要提示：仅添加用户明确要求的参数

Do NOT add extra flags unless the user explicitly requests them:

No
```
--personas
```
unless the user asks for diverse approaches
No
```
--plan-depth deep
```
unless the user wants detailed decomposition
No
```
--quick
```
unless the user wants speed over quality

The defaults are good. Let MassGen handle the rest.

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

不要添加
```
--personas
```
，除非用户要求多样化的解决方案思路
不要添加
```
--plan-depth deep
```
，除非用户需要详细的任务拆解
不要添加
```
--quick
```
，除非用户优先级是速度而非质量

默认配置已经足够完善，其余逻辑交给MassGen处理即可。

Quick Dispatch

快速任务分派

1. Detect Mode

1. 检测模式

User Intent	CLI Flags
General task (write, build, research, design)	(default)
Review/critique existing work	`--checklist-criteria-preset evaluation`
Plan a feature or project	`--plan`
Plan and auto-execute	`--plan-and-execute`
Write requirements/spec	`--spec`
Execute an existing plan	`--execute-plan <path_or_latest>`
Execute against an existing spec	`--execute-spec <path_or_latest>`

用户意图	CLI 标识
通用任务（写作、搭建、调研、设计）	(默认)
审核/评论现有成果	`--checklist-criteria-preset evaluation`
规划功能或项目	`--plan`
规划并自动执行	`--plan-and-execute`
编写需求/规格说明	`--spec`
执行现有规划	`--execute-plan <path_or_latest>`
基于现有规格说明执行	`--execute-spec <path_or_latest>`

2. Write Criteria

2. 编写评估标准

Always write opinionated evaluation criteria tailored to the task. Criteria shape what agents produce, not just how they're scored. Save to a temp file and pass via

--eval-criteria

. Aim for 4-7 criteria.

Required JSON format — each criterion needs

text

category

, and

anti_patterns

json

{
  "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"]
    }
  ]
}

Categories:

primary

(ONE — where the model needs most push),

standard

(must-pass),

stretch

(nice-to-have). See

references/criteria_guide.md

for full guidance on writing effective opinionated criteria.

For evaluate/plan/spec modes, you can use

--checklist-criteria-preset

instead of writing custom criteria (presets:

evaluation

planning

spec

persona

decomposition

prompt

analysis

始终编写贴合任务的、有明确倾向性的评估标准。评估标准会决定Agent的产出方向，而不仅仅是用于打分。将标准保存到临时文件，通过

--eval-criteria

传入，建议制定4-7条标准。

必须使用JSON格式 —— 每条标准需要包含

text

、

category

和

anti_patterns

字段：

json

{
  "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

（仅有1条 —— 模型最需要重点优化的方向）、

standard

（必须满足的要求）、

stretch

（加分项）。编写有效倾向性标准的完整指南可参考

references/criteria_guide.md

。

对于评估/规划/规格说明模式，你可以使用

--checklist-criteria-preset

代替自定义标准（预设值包括：

evaluation

、

planning

、

spec

、

persona

、

decomposition

、

prompt

、

analysis

）。

3. Build Prompt

3. 构建Prompt

General: User's task with relevant context.

Evaluate: What to evaluate. Auto-gather git diff, changed files, test output. Keep it factual — what was built, not your quality opinion. Let agents discover issues independently.

Plan: Goal + constraints.

Spec: Problem statement + user needs + constraints.

通用任务：用户的任务描述+相关上下文。

评估任务：待评估的内容。自动收集git diff、变更文件、测试输出，内容保持客观 —— 只说明已完成的内容，不要加入你的质量判断，让Agent独立发现问题。

规划任务：目标+约束条件。

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

4. Choose CWD Context

4. 选择工作目录上下文权限

Default to
rw
when the task produces files. If the deliverable is a file (code, docs, config, README, website, etc.), agents need write access. Use

ro

only when agents need to read the codebase for context but their output is pure text (an answer, review, or analysis) — not files.

Scenario	Flag
Task produces/modifies files in the project (code, docs, configs, etc.)	`--cwd-context rw`
Task needs codebase context but output is text only (review, analysis, Q&A)	`--cwd-context ro`
Isolated task, no codebase needed (default)	(omit flag)

Rule of thumb: if the user says "write", "create", "build", "rewrite", "update", or "edit" something in the project →

rw

当任务会生成文件时默认使用
rw
权限。如果交付物是文件（代码、文档、配置、README、网站等），Agent需要写入权限。仅当Agent需要读取代码库作为上下文，但输出是纯文本（答案、审核意见、分析报告）而非文件时，才使用

ro

权限。

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

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

rw

。

5. Run

5. 运行

Always use the wrapper script:

bash

undefined

始终使用封装脚本：

bash

undefined

Isolated task (default, no cwd-context needed)

独立任务（默认，不需要cwd-context）

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

需要写入项目的任务 → 使用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"


The wrapper includes `--web --no-browser` by default. The run starts
immediately — the user can open http://localhost:8000/ anytime to monitor
progress. **Tell the user about this URL.**

Run in the background. MassGen prints these for tracking:
- `LOG_DIR: <path>` — full run data
- `STATUS: <path>/status.json` — live status
- `ANSWER: <path>` — winning agent's answer.txt

Expect 15-45 minutes for multi-round runs.

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/ 查看进度。**请告知用户这个访问地址。**

后台运行任务，MassGen会输出以下信息用于追踪：
- `LOG_DIR: <path>` —— 完整运行数据
- `STATUS: <path>/status.json` —— 实时状态
- `ANSWER: <path>` —— 胜出Agent的answer.txt文件

多轮迭代任务预计运行15-45分钟。

5b. Review Notification (when

--cwd-context rw

)

5b. 审核通知（当使用

--cwd-context rw

时）

When agents have write access (

--cwd-context rw

), automatically add

--web-review

so the user can review git diffs before changes are applied. Review requires

--web

(the wrapper's default).

Headless (
--no-web
): If the user explicitly requests headless mode with

--cwd-context rw

, skip

--web-review

— changes are applied directly without a review gate. Warn the user that there will be no diff review.

After launching the MassGen run, also launch the review watcher in the background. Parse

LOG_DIR

from the MassGen output first:

bash

undefined

当Agent拥有写入权限（

--cwd-context rw

）时，自动添加

--web-review

参数，这样用户可以在变更生效前审核git diff。审核功能需要

--web

参数（封装脚本已默认开启）。

无界面模式（
--no-web
）：如果用户明确要求使用无界面模式且开启了

--cwd-context rw

，跳过

--web-review

—— 变更会直接生效，无需审核关卡。请警告用户不会有diff审核环节。

启动MassGen任务后，同时在后台启动审核监听器。首先从MassGen的输出中解析出

LOG_DIR

：

bash

undefined

Launch the watcher (reads LOG_DIR from the MassGen run output)

启动监听器（从MassGen运行输出中读取LOG_DIR）

bash "$SKILL_DIR/scripts/review_watcher.sh" "$LOG_DIR"


The watcher polls `status.json` and prints structured markers when review
is ready:

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


When you see `__REVIEW_PENDING__`, tell the user:
> "MassGen has changes ready for review. You can open the WebUI to review
> diffs visually, or tell me which files to approve/reject."

**Two resolution paths:**

1. **Browser**: User opens the REVIEW_URL and approves/rejects in the UI.
2. **Agent (text-based)**: Fetch diffs via `GET /api/sessions/{id}/review`,
   show the user a summary, then submit their decision:
   ```bash
   # 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"}'

Either path resolves the review — the other side auto-closes. After resolution,

__REVIEW_COMPLETE__ APPROVED=true|false

is printed.

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直观查看diff，或者告诉我要批准/驳回哪些文件。"

**两种解决路径：**

1. **浏览器方式**：用户打开REVIEW_URL，在UI中批准/驳回变更。
2. **Agent（文本方式）**：通过`GET /api/sessions/{id}/review`获取diff，向用户展示摘要，然后提交用户的决策：
   ```bash
   # 批准所有变更
   curl -X POST "$REVIEW_API" -H "Content-Type: application/json" \
     -d '{"approved": true, "action": "approve"}'
   # 批准指定文件
   curl -X POST "$REVIEW_API" -H "Content-Type: application/json" \
     -d '{"approved": true, "approved_files": ["src/foo.py"]}'
   # 驳回所有变更
   curl -X POST "$REVIEW_API" -H "Content-Type: application/json" \
     -d '{"approved": false, "action": "reject"}'

任意一种路径完成审核后，另一方会自动关闭。审核完成后会打印

__REVIEW_COMPLETE__ APPROVED=true|false

。

6. Read Results

6. 读取结果

Read the

ANSWER:

path from the output. The winning agent's workspace is always in the

workspace/

directory next to

answer.txt

Workspace paths in

answer.txt

are best-effort normalized to reference the adjacent

workspace/

directory. However, always navigate to the

workspace/

next to

answer.txt

as the ground truth — not paths mentioned in the text.

For plan mode,

project_plan.json

is in the workspace. For spec mode,

project_spec.json

is in the workspace.

从输出中读取

ANSWER:

对应的路径，胜出Agent的工作区始终位于

answer.txt

同级的

workspace/

目录下。

answer.txt

中的工作区路径已尽量标准化，指向同级的

workspace/

目录。但请始终以

answer.txt

同级的

workspace/

目录内容为准，而非文本中提到的路径。

对于规划模式，

project_plan.json

会存放在工作区中。对于规格说明模式，

project_spec.json

会存放在工作区中。

Optional Flags (only when requested)

可选参数（仅用户要求时使用）

Flag	Purpose
`--quick`	One-shot, no voting/refinement
`--plan-depth <level>`	Decomposition depth: `dynamic` (default), `shallow` , `medium` , `deep`
`--plan-thoroughness thorough`	Deeper strategic reasoning (default: `standard` )
`--personas <style>`	Agent diversity: `perspective` , `implementation` , `methodology` , or `off`
`--cwd-context ro`	Give agents read access to codebase
`--cwd-context rw`	Give agents write access to codebase
`--web --no-browser`	Enable WebUI for watching progress (on by default in wrapper)

标识	用途
`--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查看进度（封装脚本默认开启）

Config

配置

MassGen auto-discovers config from

.massgen/config.yaml

~/.config/massgen/config.yaml

. See setup instructions above.

MassGen会自动从

.massgen/config.yaml

或

~/.config/massgen/config.yaml

读取配置，配置方法见上文说明。

References

参考文档

Only consult when the quick dispatch isn't enough:

File	When
`references/criteria_guide.md`	Criteria format, tiers, examples
`references/config_setup.md`	Headless config creation
`references/advanced_workflows.md`	Checkpoint loops, living documents, structured eval, plan-evaluate integration

仅当快速分派流程无法满足需求时查阅：

文件	使用场景
`references/criteria_guide.md`	评估标准格式、层级、示例
`references/config_setup.md`	无界面模式配置创建
`references/advanced_workflows.md`	检查点循环、动态文档、结构化评估、规划-评估集成

massgen

Original

Translation

MassGen Skill

MassGen Skill

Before You Launch

启动前检查

Important: Only Add What's Asked

重要提示：仅添加用户明确要求的参数

Quick Dispatch

快速任务分派

1. Detect Mode

1. 检测模式

2. Write Criteria

2. 编写评估标准

3. Build Prompt

3. 构建Prompt

4. Choose CWD Context

4. 选择工作目录上下文权限

5. Run

5. 运行

Isolated task (default, no cwd-context needed)

独立任务（默认，不需要cwd-context）

Task that writes to the project → rw

需要写入项目的任务 → 使用rw

5b. Review Notification (when
`--cwd-context rw`
)

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

Launch the watcher (reads LOG_DIR from the MassGen run output)

启动监听器（从MassGen运行输出中读取LOG_DIR）

6. Read Results

6. 读取结果

Optional Flags (only when requested)

可选参数（仅用户要求时使用）

Config

配置

References

参考文档

massgen

Original

Translation

MassGen Skill

MassGen Skill

Before You Launch

启动前检查

Important: Only Add What's Asked

重要提示：仅添加用户明确要求的参数

Quick Dispatch

快速任务分派

1. Detect Mode

1. 检测模式

2. Write Criteria

2. 编写评估标准

3. Build Prompt

3. 构建Prompt

4. Choose CWD Context

4. 选择工作目录上下文权限

5. Run

5. 运行

Isolated task (default, no cwd-context needed)

独立任务（默认，不需要cwd-context）

Task that writes to the project → rw

需要写入项目的任务 → 使用rw

5b. Review Notification (when --cwd-context rw)

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

Launch the watcher (reads LOG_DIR from the MassGen run output)

启动监听器（从MassGen运行输出中读取LOG_DIR）

6. Read Results

6. 读取结果

Optional Flags (only when requested)

可选参数（仅用户要求时使用）

Config

配置

References

参考文档

5b. Review Notification (when
`--cwd-context rw`
)

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