ai-review（AI 评论）

MR Review Skill

Review a GitLab Merge Request and optionally post inline comments.

Arguments

$ARGUMENTS — Optional GitLab MR URL (e.g. https://gitlab.com/group/repo/-/merge_requests/123). If not provided, ask the user.

Workflow

Step 1 — Verify CLI

ai-review --version

If not found, tell the user to run npm install -g. inside the ai-review-cli repo and stop.

Step 2 — Check credentials

cat ~/.ai-review/credentials.json

If the file is missing or has no gitlab key, tell the user to run ai-review configure gitlab and stop.

Step 3 — Obtain and validate the MR URL

Use $ARGUMENTS if it starts with http. Otherwise ask the user. Validate the URL matches: https://<host>/<namespace>/<repo>/-/merge_requests/<number>.

Step 4 — Fetch MR context

ai-review get-context <MR_URL>

Writes to ~/.ai-review/mr-context.json. On non-zero exit, surface the error code clearly:

• CREDENTIALS_NOT_FOUND → run ai-review configure gitlab
• INVALID_URL → ask user to check the URL
• API_ERROR → show the message

Step 5 — Analyse and generate review

Read ~/.ai-review/mr-context.json and analyse every changed file as a senior engineer. Focus on:

• Bugs — logic errors, off-by-one, null/undefined handling
• Security — injection flaws, hardcoded secrets, improper auth
• Performance — unnecessary loops, N+1 queries, excessive allocations
• Correctness — wrong types, missing edge cases, incorrect API usage
• Readability — confusing naming, overly complex logic
• Test coverage — untested branches, missing assertions

Diff lines are annotated as [oldLine:newLine]. Use newLine as the line field. Only comment on lines inside the changed hunks.

Write the review to ~/.ai-review/review-output.json:

{
  "description": "A concise Markdown summary of the MR: what changed, why, and any significant design decisions or risks observed.",
  "comments": [
    {
      "file": "path/to/file.ts",
      "line": 42,
      "severity": "critical",
      "comment": "Concise, actionable explanation and suggested fix."
    }
  ]
}

The description field must always be populated. It should be a Markdown-formatted summary covering:

• What changed — a high-level summary of the modifications
• Why — inferred intent or purpose of the changes
• Notable details — any significant design decisions, potential risks, or things reviewers should know

Severity levels:

If there are no issues, write {"comments": []} and tell the user the MR looks clean.

Step 6 — Validate output

ai-review validate-output ~/.ai-review/review-output.json

On failure, inspect the error, fix the JSON, and re-validate before continuing.

Step 7 — Present summary

Print counts by severity and the top findings (up to 5):

Review complete: 2 critical, 3 warning, 4 suggestion

Top findings:
• [critical] src/auth.ts:88 — JWT secret without fallback validation
• [warning]  src/api.ts:102 — Missing error handling on external HTTP call

Step 8 — Ask whether to post

Ask the user which minimum severity to post:

1. suggestion — all comments
2. warning — warnings and critical only
3. critical — critical only
4. No — skip (default)

If the user provides no input or presses Enter without selecting an option, default to option 4 (skip) and do not post any comments.

If 1–3:

ai-review post-comments <MR_URL> --input ~/.ai-review/review-output.json --severity <level>

Report how many were posted and how many skipped.

Step 9 — Ask whether to update MR description

Ask the user:

The review includes an MR description summary. Do you want to post it as the MR description on GitLab? (y/N)

Default is No — do not update the description unless the user explicitly answers y or yes.

If yes:

ai-review post-description <MR_URL> --input ~/.ai-review/review-output.json

Confirm success or surface any error returned.

Notes

• All output files live under ~/.ai-review/ and are overwritten on each run.
• Credentials in ~/.ai-review/credentials.json are keyed by hostname; multiple GitLab instances are supported.