event-description-generator

分类: 工具与效率 | 上传者: amplitude | 下载: 0 | 版本: v1.0（最新）

通过将块工作委托给 event-descriptions-worker 子代理来编排事件描述审核。需要时，通过 get_context 将项目名称解析为 projectId，然后在有界运行窗口的游标上生成工作子代理，并将输出写入运行范围的目录中。在大规模审核缺失事件描述时使用，而无需直接在此技能中进行每个事件分析。 --- # 事件描述生成器仅作为**编排者**运行此技能。不要在此技能主体中执行每个事件过滤、存储库搜索或描述编写逻辑。将块处理委托给“event-descriptions-worker”子代理。 ## 工作流程 1. 解析项目输入（`projectId` 或项目名称） 2. 使用短 git SHA 创建运行 ID (`<projectId>-<sha>`) 3. 在 `runs/` 下创建运行目录 4. 确定游标计划（`cursorStart`、`maxEvents`、块大小） 5. 为游标块生成“event-descriptions-worker”子代理 6. 收集工作人员摘要 + 输出路径 7. 将运行压缩到单个 CSV 中 8. 报告简明进度和下一个游标 ## 执行规则 - 将此技能保留为 **调度程序**；工人承担繁重的工作。 - 不要从此技能中调用“set_event_metadata”。 - 不要在此处手动重新实现工作人员过滤/搜索逻辑。 - 保留用户对范围的控制（项目、光标范围、块大小、并行性）。 ## 先决条件

更新日志: Source: GitHub https://github.com/amplitude/mcp-marketplace

目录结构

当前层级: tree/main/plugins/amplitude-experimental/skills/event-description-generator/

📁 references/
- 📄 search-playbook.md 4.6 KB
📁 scripts/
- 📄 compress-run.py 3.2 KB
- 📄 writer-plan.py 2.3 KB
📄 SKILL.md 7.4 KB

SKILL.md

---
name: event-description-generator
description: >
  Orchestrate event description audits by delegating chunk work to the event-descriptions-worker
  subagent. Resolve a project name to projectId via get_context when needed, then spawn worker
  subagents over cursors for a bounded run window and write outputs into run-scoped directories.
  Use when auditing missing event descriptions at scale without doing per-event analysis directly
  in this skill.
---

# Event Description Generator

Run this skill as an **orchestrator only**. Do not perform per-event filtering, repo search, or description-writing logic in this skill body. Delegate chunk processing to the `event-descriptions-worker` subagent.

## Workflow

1. Resolve project input (`projectId` or project name)
2. Create a run ID with short git SHA (`<projectId>-<sha>`)
3. Create run directories under `runs/`
4. Determine cursor plan (`cursorStart`, `maxEvents`, chunk size)
5. Spawn `event-descriptions-worker` subagents for cursor chunks
6. Collect worker summaries + output paths
7. Compress the run into a single CSV
8. Report concise progress and next cursor

## Execution Rules

- Keep this skill as a **dispatcher**; the worker does the heavy lifting.
- Do not call `set_event_metadata` from this skill.
- Do not manually re-implement worker filtering/search logic here.
- Preserve user control over scope (project, cursor range, chunk size, parallelism).

## Prerequisites

The user must provide either:

- `projectId`, or
- project name to resolve.

If neither is provided, stop and ask.

## Phase 1: Resolve Project

### 1.1 If `projectId` is provided

Use it directly.

### 1.2 If project name is provided

Call `get_context` and resolve the name to a single `projectId`.

- If exactly one clear match exists, continue with that ID.
- If multiple matches exist, ask the user to choose.
- Do not choose an ambiguous match on behalf of the user.

### 1.3 If project name is not provided

Prompt the user to input the project name or ID and halt.

## Phase 2: Build Cursor Plan

Default values unless the user specifies otherwise:

- `cursorStart`: `0`
- `maxEvents`: `400`
- `eventsPerWorker`: `50`
- `maxParallelWorkers`: `4`

For `maxEvents`:

- Compute total chunks as `ceil(maxEvents / eventsPerWorker)`.
- Process at most `maxEvents` events starting at `cursorStart`.
- For the final chunk, pass a reduced `eventsPerWorker` if needed to avoid exceeding `maxEvents`.

For each chunk:

- Worker input cursor = current cursor
- Next planned cursor = current cursor + `eventsPerWorker`

## Phase 3: Initialize Run Directory

Before launching workers:

1. Get the short git SHA by running `git rev-parse --short HEAD` in the workspace root.
2. Create `runId = <projectId>-<sha>`.
3. Ensure these directories exist:
   - `.agents/skills/event-description-generator/runs/`
   - `.agents/skills/event-description-generator/runs/<runId>/`

## Phase 4: Spawn Worker Subagents

For each planned cursor, invoke `event-descriptions-worker` with:

- `projectId` (resolved)
- `cursor`
- `runId`
- `eventsPerWorker` (optional per-worker chunk size; pass when not default)

Worker output file convention:

- `.agents/skills/event-description-generator/runs/<runId>/event-descriptions-<cursor>.csv`

### 4.1 Parallelization guidance

- If user asks for one cursor, run one worker.
- If user asks for multiple cursors/range, run workers in parallel up to `maxParallelWorkers`.
- For large ranges, run in waves (bounded concurrency), then continue until limit reached.

## Phase 5: Collect Worker Results

From each worker response, capture:

- events fetched
- events written
- output CSV path
- next cursor
- any errors

## Phase 6: Compress Run

After all workers have completed, run the compress script to merge all chunk CSVs into a single file, keeping only rows with a `suggested_description`:

```bash
python3 .agents/skills/event-description-generator/scripts/compress-run.py <runId>
```

Capture the script's stdout to include compression stats in the report. If the script fails, note the error but do not block the report.

## Phase 7: User-Facing Report

Return a short summary:

```text
Event description generator dispatch complete for project {projectId}
- Run ID: {runId}
- Workers run: {n}
- Total fetched: {sum_fetched}
- Total written: {sum_written}
- Compressed output: .agents/skills/event-description-generator/runs/{runId}/{runId}-{YYYY-MM-DD}.csv
  - Rows with descriptions: {compress_written}
  - Rows filtered (no description): {compress_filtered}
- Next cursor to continue: {max_next_cursor_or_last_next_cursor}
- Errors: {none_or_list}
```

If the user never specified writing the descriptions, ask if they would like to write the suggested descriptions to Amplitude.

## Phase 8: Write Descriptions to Amplitude

IMPORTANT: Only execute this phase when the user has explicitly asked to write descriptions.

Fixed constants (not configurable):

- `eventsPerWriter`: `100`
- `maxParallelWriters`: `4`

### 8.1 Locate the compressed CSV

Use the compressed output path reported in Phase 7:

```
.agents/skills/event-description-generator/runs/<runId>/<runId>-<YYYY-MM-DD>.csv
```

If the file does not exist (e.g. the user is resuming a previous run), ask the user to provide the path and halt.

### 8.2 Build writer plan

Run the writer-plan script to count data rows and compute chunks in one step:

```bash
python3 .agents/skills/event-description-generator/scripts/writer-plan.py <csvPath>
```

The script outputs JSON with all the information needed to spawn writers:

```json
{
  "csvPath": "...",
  "totalDataRows": 137,
  "eventsPerWriter": 50,
  "totalChunks": 3,
  "chunks": [
    { "index": 0, "lineStart": 1, "lineEnd": 50 },
    { "index": 1, "lineStart": 51, "lineEnd": 100 },
    { "index": 2, "lineStart": 101, "lineEnd": 137 }
  ]
}
```

Parse the JSON output and use the `chunks` array to drive step 8.4.

### 8.3 Spawn writer subagents

For each planned chunk, invoke `event-descriptions-writer` with:

- `projectId` (resolved in Phase 1)
- `csvPath`
- `lineStart`
- `lineEnd`

Run workers in parallel up to `maxParallelWriters`. For large files, process in waves (bounded concurrency) until all chunks are complete.

### 8.4 Collect writer results

From each worker response, capture:

- `written`: events successfully written
- `skippedRows`: rows filtered due to missing fields
- `success`: true/false
- `errors`: any tool errors

### 8.5 Write report

Return a concise summary:

```text
Description write complete for project {projectId}
- Source: {csvPath}
- Total data rows: {totalDataRows}
- Writers run: {totalChunks}
- Total written: {sum_written}
- Total skipped: {sum_skipped}
- Errors: {none_or_list}
```

## Common Invocation Patterns

### Single chunk

- Inputs: `projectId=123`, `cursor=500`
- Run ID generated once for this invocation
- Action: spawn one worker
- Output: one CSV + next cursor

### Multi-chunk wave

- Inputs: `projectId=123`, `cursorStart=0`, `maxEvents=100`, `eventsPerWorker=20`
- Planned cursors: `0, 20, 40, 60, 80`
- Action: spawn workers with bounded parallelism
- Output: five CSVs under one run directory, continuation cursor `100`

## References

- Audit worker definition: `.cursor/agents/event-descriptions-worker.md`
- Writer worker definition: `.cursor/agents/event-descriptions-writer.md`
- Compress script: `.agents/skills/event-description-generator/scripts/compress-run.py`
- Legacy search heuristics (if needed for worker evolution): [search-playbook.md](references/search-playbook.md)

登录后下载/点赞/收藏 ❤ 18 | ★ 0

event-description-generator

目录结构

SKILL.md

举报内容

提示