hyperscribe-diff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Step 0 — Preference: Before running any renderer command, perform the theme-preference resolution block from the base
hyperscribe
skill (
~/.claude/skills/hyperscribe/SKILL.md
, section "Step 0"). It sets
$THEME
and
$MODE
. If absent, this wrapper falls back to
studio
+
light
.

步骤0 — 偏好设置: 在运行任何渲染器命令之前，请执行基础
hyperscribe
技能中的主题偏好解析模块（路径：
~/.claude/skills/hyperscribe/SKILL.md
，“步骤0”章节）。该模块会设置
$THEME
和
$MODE
变量。如果该模块不存在，此包装器将默认使用
studio
主题 +
light
模式。

Hyperscribe — Diff review mode

Hyperscribe — 差异评审模式

Produces a self-contained HTML diff review using

hyperscribe/CodeDiff

hyperscribe/ArchitectureGrid

(for impacted modules), and

hyperscribe/Callout

(for risks). Thin wrapper over the

hyperscribe

skill.

利用

hyperscribe/CodeDiff

、

hyperscribe/ArchitectureGrid

（用于受影响模块）和

hyperscribe/Callout

（用于风险提示）生成独立的HTML差异评审页面。是

hyperscribe

技能的轻量包装器。

When to use

使用场景

User pastes a unified diff or
```
git diff
```
output and asks for review/summary.
User gives a PR URL (
```
github.com/owner/repo/pull/N
```
) and asks for review.
User gives a git range (
```
main..HEAD
```
,
```
HEAD~5..HEAD
```
, SHA range).
User says "review these changes", "what changed", "impact of this diff".

Do not use for: generic commit history summaries (no concrete diff), feature spec writing, or rendering a single code snippet (use

hyperscribe

with

CodeBlock

用户粘贴统一diff或
```
git diff
```
输出并请求评审/摘要时。
用户提供PR URL（格式：
```
github.com/owner/repo/pull/N
```
）并请求评审时。
用户提供git范围（如
```
main..HEAD
```
、
```
HEAD~5..HEAD
```
、SHA哈希范围）时。
用户提出“评审这些变更”、“有哪些变更”、“该diff的影响是什么”等请求时。

请勿用于：通用提交历史摘要（无具体diff内容）、功能规格编写，或渲染单个代码片段（此类场景请使用带有

CodeBlock

的

hyperscribe

）。

Source detection

来源检测

Git range — run
```
git diff <range>
```
to get the unified diff.

PR URL — use

gh pr diff <N> -R owner/repo

gh api repos/owner/repo/pulls/<N>.diff

Pasted diff — use the provided text directly.
No clear source — ask the user before continuing.

Git范围 — 执行
```
git diff <range>
```
命令获取统一diff。

PR URL — 使用

gh pr diff <N> -R owner/repo

或

gh api repos/owner/repo/pulls/<N>.diff

命令获取diff。

粘贴的diff — 直接使用用户提供的文本内容。
来源不明确 — 继续操作前请询问用户。

Envelope structure

信封结构

json

{
  "a2ui_version": "0.9",
  "catalog": "hyperscribe/v1",
  "is_task_complete": true,
  "parts": [
    {
      "component": "hyperscribe/Page",
      "props": { "title": "Diff: <short summary>", "subtitle": "<N files, +X -Y lines>", "toc": true },
      "children": [
        {
          "component": "hyperscribe/Section",
          "props": { "id": "summary", "title": "Summary", "lead": "**What changed** and **why it matters**." },
          "children": [
            { "component": "hyperscribe/Prose", "props": { "markdown": "One-paragraph summary." } },
            { "component": "hyperscribe/ArchitectureGrid", "props": {
              "layout": "grid",
              "nodes": [ { "id": "auth", "title": "Auth module", "tag": "modified" } ]
            }}
          ]
        },
        {
          "component": "hyperscribe/Section",
          "props": { "id": "risks", "title": "Risks" },
          "children": [
            { "component": "hyperscribe/Callout", "props": { "severity": "warn", "title": "Migration required", "body": "..." }}
          ]
        },
        {
          "component": "hyperscribe/Section",
          "props": { "id": "changes", "title": "Changes" },
          "children": [
            { "component": "hyperscribe/CodeDiff", "props": {
              "filename": "src/auth.ts",
              "lang": "ts",
              "hunks": [ { "before": "const x = 1;", "after": "const x = 2;", "atLine": 42 } ]
            }}
          ]
        }
      ]
    }
  ]
}

json

{
  "a2ui_version": "0.9",
  "catalog": "hyperscribe/v1",
  "is_task_complete": true,
  "parts": [
    {
      "component": "hyperscribe/Page",
      "props": { "title": "Diff: <short summary>", "subtitle": "<N files, +X -Y lines>", "toc": true },
      "children": [
        {
          "component": "hyperscribe/Section",
          "props": { "id": "summary", "title": "Summary", "lead": "**What changed** and **why it matters**." },
          "children": [
            { "component": "hyperscribe/Prose", "props": { "markdown": "One-paragraph summary." } },
            { "component": "hyperscribe/ArchitectureGrid", "props": {
              "layout": "grid",
              "nodes": [ { "id": "auth", "title": "Auth module", "tag": "modified" } ]
            }}
          ]
        },
        {
          "component": "hyperscribe/Section",
          "props": { "id": "risks", "title": "Risks" },
          "children": [
            { "component": "hyperscribe/Callout", "props": { "severity": "warn", "title": "Migration required", "body": "..." }}
          ]
        },
        {
          "component": "hyperscribe/Section",
          "props": { "id": "changes", "title": "Changes" },
          "children": [
            { "component": "hyperscribe/CodeDiff", "props": {
              "filename": "src/auth.ts",
              "lang": "ts",
              "hunks": [ { "before": "const x = 1;", "after": "const x = 2;", "atLine": 42 } ]
            }}
          ]
        }
      ]
    }
  ]
}

Section checklist

章节检查清单

A solid diff review includes:

Summary — 1-paragraph
```
Prose
```
+
```
ArchitectureGrid
```
of impacted modules (tag each
```
modified
```
/
```
added
```
/
```
removed
```
)
Risks —
```
Callout
```
s for breaking changes, migrations, perf, security
Changes — one
```
CodeDiff
```
per significant file. Aggregate tiny typo-level changes; split big refactors by file.
(Optional) Testing plan —
```
StepList
```
of manual verification steps
(Optional) Follow-ups — bullet list of deferred work

一份优质的差异评审应包含：

摘要 — 一段
```
Prose
```
内容 + 展示受影响模块的
```
ArchitectureGrid
```
（为每个模块标记
```
modified
```
/
```
added
```
/
```
removed
```
）
风险 — 使用
```
Callout
```
提示破坏性变更、迁移需求、性能影响、安全问题等
变更内容 — 每个重要文件对应一个
```
CodeDiff
```
。汇总微小的笔误级变更；大型重构按文件拆分展示。
（可选）测试计划 — 使用
```
StepList
```
列出手动验证步骤
（可选）后续工作 — 使用项目符号列表记录延迟处理的任务

Callout severity guide

Callout严重程度指南

Severity	When
`info`	Notable but benign (e.g., removes unused import)
`note`	Context reviewer should know (e.g., related to issue #42)
`warn`	Behavior change callers should verify
`danger`	Breaking change, security concern, data-loss risk
`success`	Celebratory (new test coverage, perf win)

严重程度	使用场景
`info`	值得注意但无影响的变更（例如：移除未使用的导入）
`note`	评审者需要了解的上下文信息（例如：与#42号问题相关）
`warn`	调用方需要验证的行为变更
`danger`	破坏性变更、安全隐患、数据丢失风险
`success`	值得肯定的变更（例如：新增测试覆盖率、性能提升）

Render

渲染流程

Same as the base

hyperscribe

skill — resolve renderer, pipe JSON, write HTML, open.

bash

HS=$(for p in \
  ./.claude/skills/hyperscribe ~/.claude/skills/hyperscribe \
  ./.codex/skills/hyperscribe ~/.codex/skills/hyperscribe \
  ./.cursor/skills/hyperscribe ~/.cursor/skills/hyperscribe \
  ./.opencode/skills/hyperscribe ~/.opencode/skills/hyperscribe \
  ~/.claude/plugins/cache/hyperscribe-marketplace/*/plugins/hyperscribe
do [ -x "$p/scripts/hyperscribe" ] && { echo "$p/scripts/hyperscribe"; break; }; done)

if [ -z "$HS" ]; then
  echo "hyperscribe renderer not found. Install with: npx skills add Atipico1/hyperscribe" >&2
  exit 1
fi

mkdir -p ~/.hyperscribe/out
OUT=~/.hyperscribe/out/diff-$(date +%Y%m%d-%H%M%S).html
MODE_FLAG=""
[ "${MODE:-}" = "light" ] && MODE_FLAG="--mode light"
[ "${MODE:-}" = "dark" ]  && MODE_FLAG="--mode dark"

cat <<'EOF' | "$HS" --theme "${THEME:-studio}" $MODE_FLAG --out "$OUT"
<the JSON you built>
EOF
open "$OUT"

与基础

hyperscribe

技能一致 — 解析渲染器、传入JSON、生成HTML并打开。

bash

HS=$(for p in \
  ./.claude/skills/hyperscribe ~/.claude/skills/hyperscribe \
  ./.codex/skills/hyperscribe ~/.codex/skills/hyperscribe \
  ./.cursor/skills/hyperscribe ~/.cursor/skills/hyperscribe \
  ./.opencode/skills/hyperscribe ~/.opencode/skills/hyperscribe \
  ~/.claude/plugins/cache/hyperscribe-marketplace/*/plugins/hyperscribe
do [ -x "$p/scripts/hyperscribe" ] && { echo "$p/scripts/hyperscribe"; break; }; done)

if [ -z "$HS" ]; then
  echo "hyperscribe renderer not found. Install with: npx skills add Atipico1/hyperscribe" >&2
  exit 1
fi

mkdir -p ~/.hyperscribe/out
OUT=~/.hyperscribe/out/diff-$(date +%Y%m%d-%H%M%S).html
MODE_FLAG=""
[ "${MODE:-}" = "light" ] && MODE_FLAG="--mode light"
[ "${MODE:-}" = "dark" ]  && MODE_FLAG="--mode dark"

cat <<'EOF' | "$HS" --theme "${THEME:-studio}" $MODE_FLAG --out "$OUT"
<the JSON you built>
EOF
open "$OUT"

Avoid

注意事项

Dumping the raw diff into one giant
```
CodeBlock
```
— use
```
CodeDiff
```
per file so before/after lanes render.
Inventing risks not supported by the diff content.
Using
```
Mermaid
```
for diff visualization unless the diff itself restructures a flow (then: before/after
```
ArchitectureGrid
```
side by side).

不要将原始diff直接放入一个巨大的
```
CodeBlock
```
中 — 按文件使用
```
CodeDiff
```
，以便渲染前后对比栏。
不要编造diff内容未体现的风险。
除非diff本身重构了流程（此时可将前后
```
ArchitectureGrid
```
并排展示），否则不要使用
```
Mermaid
```
进行diff可视化。