e433e68dd7
Documents the report archive feature in the Fusion Plugin Reports README and adds a patch changeset for the release. Fusion-Task-Id: FN-3784
139 lines
3.7 KiB
Markdown
139 lines
3.7 KiB
Markdown
# Reports Plugin for Fusion
|
|
|
|
Generates HTML system activity reports with multi-agent review.
|
|
|
|
## Review Panel
|
|
|
|
The plugin exposes `runReviewPanel()` / `runGeneratedReportReview()` to fan out a generated report draft to multiple reviewer agents in parallel.
|
|
|
|
### Panel member settings shape
|
|
|
|
Each reviewer uses this contract:
|
|
|
|
```ts
|
|
{
|
|
id: string;
|
|
name: string;
|
|
perspective: string;
|
|
promptTemplateId?: string;
|
|
provider?: string;
|
|
modelId?: string;
|
|
}
|
|
```
|
|
|
|
- `perspective` is appended to the reviewer system prompt.
|
|
- `promptTemplateId` selects a template from `settings.reviewPromptTemplates[templateId]` when present.
|
|
- `provider` + `modelId` optionally override model selection per reviewer.
|
|
|
|
### Prompt template contract
|
|
|
|
`runReviewPanel` resolves reviewer templates in this order:
|
|
|
|
1. `settings.reviewPromptTemplates[promptTemplateId ?? id]`
|
|
2. `settings.reviewPrompt`
|
|
3. Built-in fallback (`DEFAULT_REVIEW_PROMPT`)
|
|
|
|
This is the temporary compatibility contract until FN-3782 lands shared review-template helpers.
|
|
|
|
### Individual review shape
|
|
|
|
```ts
|
|
{
|
|
memberId: string;
|
|
memberName: string;
|
|
perspective: string;
|
|
verdict: "approve" | "revise" | "reject";
|
|
summary: string;
|
|
highlights: string[];
|
|
lowlights: string[];
|
|
suggestions: string[];
|
|
rawText: string;
|
|
durationMs: number;
|
|
}
|
|
```
|
|
|
|
### Combined review shape
|
|
|
|
```ts
|
|
{
|
|
overallVerdict: "approve" | "revise" | "reject";
|
|
consensusSummary: string;
|
|
mergedHighlights: string[];
|
|
mergedLowlights: string[];
|
|
mergedSuggestions: string[];
|
|
individual: IndividualReview[];
|
|
failures: ReviewFailure[];
|
|
}
|
|
```
|
|
|
|
Aggregation is deterministic:
|
|
|
|
- verdict precedence: `approve < revise < reject`
|
|
- merged arrays are case-insensitive de-duped, first-seen order, max 25 items each
|
|
- consensus summary is generated locally from reviewer summaries (no second AI call)
|
|
|
|
### Timeout and failure semantics
|
|
|
|
- Each reviewer has a hard timeout (`120_000ms`).
|
|
- A single reviewer failure never aborts the full panel.
|
|
- Failures are returned as:
|
|
|
|
```ts
|
|
{
|
|
memberId: string;
|
|
reason: "timeout" | "parse_error" | "session_unavailable" | "exception";
|
|
message: string;
|
|
}
|
|
```
|
|
|
|
- If all reviewers fail, combined verdict is `reject` with an explicit consensus summary describing panel failure.
|
|
|
|
## Report Archive
|
|
|
|
The plugin persists generated reports in SQLite via `ensureReportSchema(db)` and `ReportStore`.
|
|
|
|
### Schema
|
|
|
|
Table: `reports`
|
|
|
|
- identity/metadata: `id`, `cadence`, `title`, `metadataJson`
|
|
- period window: `periodStart`, `periodEnd`
|
|
- lifecycle/status: `status`, `failureReason`
|
|
- payload references: `draftMarkdown`, `renderedHtmlPath`
|
|
- review payload: `combinedReviewJson`
|
|
- timestamps: `generationStartedAt`, `generationCompletedAt`, `reviewStartedAt`, `reviewCompletedAt`, `approvedAt`, `publishedAt`, `archivedAt`, `createdAt`, `updatedAt`
|
|
- approval actor: `approvedBy`
|
|
|
|
Indexes:
|
|
|
|
- `idxReportsCadenceCreated` on `(cadence, createdAt DESC, id)`
|
|
- `idxReportsStatusUpdated` on `(status, updatedAt DESC, id)`
|
|
- `idxReportsPeriod` on `(periodStart, periodEnd, id)`
|
|
|
|
### Status lifecycle
|
|
|
|
`generating → review_pending → review_in_progress → review_complete → approved → published`
|
|
|
|
`failed` and `archived` are allowed from any non-terminal state. Idempotent transitions (`from === to`) are no-ops.
|
|
|
|
### ReportStore API
|
|
|
|
- `createReport(input)`
|
|
- `getReport(id)`
|
|
- `listReports(filter?)`
|
|
- `updateReport(id, patch)`
|
|
- `setStatus(id, next, opts?)`
|
|
- `attachReview(id, combinedReview)`
|
|
- `attachRenderedHtml(id, htmlPath)`
|
|
- `deleteReport(id)`
|
|
|
|
Emitted events:
|
|
|
|
- `report:created`
|
|
- `report:updated`
|
|
- `report:status-changed`
|
|
- `report:review-attached`
|
|
- `report:deleted`
|
|
|
|
This archive is the source of truth for downstream report HTML rendering (FN-3785) and dashboard report list/detail flows (FN-3786).
|