# @dansyuqri/spark-joy 中文文档

规范地址：https://npmcn.com/package/%40dansyuqri/spark-joy/

版本：0\.11\.0
npm 元数据更新时间：2026-10-26T06:21:28.642Z
中文译文更新时间：2026-11-11T11:07:10.150Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dansyuqri/spark-joy
原文对照：https://npmcn.com/package/%40dansyuqri/spark-joy/?lang=original
项目主页：https://github.com/Dansyuqri/spark-joy#readme
源码仓库：https://github.com/Dansyuqri/spark-joy

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：839 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24
- 运行依赖：1 个
- 首次发布：2026-10-17T09:54:21.296Z
- 最新版本发布：2026-10-26T06:21:28.151Z
- 近 30 天下载量：3717（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

将一个庞大的公关分解成可审查块.

## 安装

```sh
npm install @dansyuqri/spark-joy
```

也可以使用：`pnpm add @dansyuqri/spark-joy`、`yarn add @dansyuqri/spark-joy`、`bun add @dansyuqri/spark-joy`

## README

![A drawer of neatly folded diffs, one sparking joy](https://npmcn.com/package/%40dansyuqri/spark-joy/assets/logo.svg)

# 火花欢乐

_让公关再次燃起欢乐._

[![npm version](https://img.shields.io/npm/v/@dansyuqri/spark-joy?style=flat-square&label=npm)](https://www.npmjs.com/package/@dansyuqri/spark-joy) ![MIT license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)

AI-写作的PR往往有上千行长:太大,无法适当审查. Spark -joy让你的编码代理 破解一个大 PR 成小块,订购, 然后打开一个本地的应用程序 在那里你一次审查一次.

工作从平地git, 所以GitHub,GitLab或其他任何东西。 除非您要求,否则不会张贴任何信息.

灵感来自 [主持人](https://github.com/phanshiyu/mr-cast)。 。 。 .

## 主要特点

### 将大型 PR 拆分为较小的 PR

叫你的经纪人"把我的修改分给较小的公关" 它会把您的舞台改变, 未经承诺的改变或整个分支 变成一叠小的公关, 每一个都建在以前的一个上. 您可以在应用程序中预览堆栈, 可以选择运行每个 PR 的测试, 然后获得本地分支, 每个分支都有标题和描述 。 你的工作树从不被打动 什么都没有被推倒.

![Extracting uncommitted changes, previewing five stacked PRs in the app, checking each PR's tests, then creating the branches](https://npmcn.com/package/%40dansyuqri/spark-joy/assets/split.gif)

更多进去 [自己拆分更改](https://npmcn.com/package/%40dansyuqri/spark-joy/#readme-split-your-own-changes)。 。 。 .

### 按基金会或特征审查大型公关

叫你的经纪人检查一下这个公关 它将diff分为100至300行的块,分为两个审查令:

-   **基金会优先** 逻辑 呼叫者 测试.
-   **按特点** 一次一个能力,结束到结束.

选择一个,然后切换 后不失去进展。 每变一分一分, 和火花快乐的检查, 没有遗漏或审查两次。 堆积和相关公关获得相同的两个订单,即公关的公关或所有公关.

**示例** 火花欢乐的历史,一个7.8克线 diff,变成了 **18块141至369行**每一个汉克都放过一次 2.7k行锁文件直接转到 _滑动_。 。 。 .

![Choosing a review order, reviewing a chunk with a line note, then zooming into a chunk on the map](https://npmcn.com/package/%40dansyuqri/spark-joy/assets/demo.gif)

更多进去 [使用](https://npmcn.com/package/%40dansyuqri/spark-joy/#readme-use)。 。 。 .

### 审查将公关联系在一起

一些修改跨越了PR:一个API和使用它的客户端,或者一个固定及其后续. 在描述( 或运行) 中添加“ 涉及 # 12” 一行 `spark-joy link`和 `spark-joy related` 将每个链接的 PR 装入一个视图, 每个 PR 块, 每个 diffect 与其目标相对 。 你的经纪人可以把它们组起来 _基金会首先跨越公关_ 或者说 _按公关的特征_,所以一个块收集地基,或一个特征, 从每一个接触的公关. **整个公关** 显示每个公关中一个触及它的文件, 你的笔记帖回到公关上.

![Loading three related PRs, reviewing one that builds on another, then viewing a file across the PRs](https://npmcn.com/package/%40dansyuqri/spark-joy/assets/related.gif)

更多进去 [审查相关的公关](https://npmcn.com/package/%40dansyuqri/spark-joy/#readme-review-related-prs)。 。 。 .

## 其他特点

-   **堆积的公关.** 装入 GitHub 或 GitLab 上已经打开的堆栈, 然后通过 PR 来审查 PR 。 见 [审查堆放的公关](https://npmcn.com/package/%40dansyuqri/spark-joy/#readme-review-stacked-prs)。 。 。 .
-   **跨块/跨公关.** 查看一个文件的 diff 在每一个块或 PR 并肩,顺序.
-   **地图.** 春克为图. 点击一个来查看其文件的 diffs 链接; 点击一个文件来审查它 .
-   **总结.** A 类 _这个公关做什么_ 列表中将每个特性与执行该特性的块联系起来,并显示每个特性中有多少已被审查。 全部导出为 `review.md`。 。 。 .
-   **张贴你的笔记.** 线条和块状笔记作为待批审查(GitHub)或草稿(GitLab)提交公关,只有提交前才能看到.
-   **机械变化相分离.** 锁定文件、生成的文件、二进制、重命名和仅白空域更改进入崩溃状态 _滑动_ 节.
-   **风险已经商定,没有猜测.** 在标注什么之前, 代理提出什么是高和中风险 对于你的回购, 等待你确认。 标题保存在 `.spark-joy.md` 在 repo 根; 承诺与你的团队分享.
-   **进步是新的承诺.** 检讨状态通过hunk内容存储,所以一推后您需要重新取出,只需要新的或已更改的hunks需要再次取出.
-   **链接代码 .** 每个文件下, **用途** 财务报告和审定财务报表 **用于** 列表它链接到的其他已更改文件; 单击下划线名称跳转到定义中.
-   **代理或终端.** 你的经纪人可以驾驶每一步,或者运行任何 `spark-joy` 指挥自己。 见 [代理或终端](https://npmcn.com/package/%40dansyuqri/spark-joy/#readme-agent-or-terminal)。 。 。 .
-   **签署承诺.** 如果您的 git 配置有 : `commit.gpgsign` 继续.
-   **任何探员.** 一个 [特工技能](https://agentskills.io/) 加上一个CLI,所以它与克洛德代码,Codex,双子座CLI,Cursor,OpenCode等合作.

## 如何运作

```
spark-joy extract   →  hunks.json    every hunk of the diff gets an id (h001, h012.1, …)
the agent (skill)   →  plan.json     hunks grouped into chunks, in two review orders, plus a feature list
spark-joy validate  →  ok / errors   every non-mechanical hunk is in exactly one chunk, sizes are sane
spark-joy serve     →  review app    choose an order, review chunk by chunk, export review.md
```

-   **探员从不把密码抄入计划.** 它指由id,和 `validate` 检查是否缺少任何变化或两次审查.
-   **春克还是小的.** 目标是100-300条变更线路,验证警告超过400条. 大型猎犬在功能边界上被分割,这样它们就可以进入不同的块.

## 安装

需要节点 24 或更新和 git。 npm上公布为 [`@dansyuqri/spark-joy`](https://www.npmjs.com/package/@dansyuqri/spark-joy)。 。 。 .

火花快乐是一种 [特工技能](https://agentskills.io/) 加上一个CLI,所以它与克洛德代码, Codex,双子座CLI, Cursor, OpenCode 和其他读取的代理商合作 `SKILL.md`。 。 。 .

```sh
npm install -g @dansyuqri/spark-joy
spark-joy install-skill
```

`install-skill` 复制技能到 `~/.claude/skills` (法规)和 `~/.agents/skills` (Codex,双子座CLI,Cursor,OpenCode等).

-   `--agent claude` 或者说 `--agent agents` 只安装到其中之一.
-   `--project` 安装到 repo 中.
-   `--print` 打印没有技能支持的代理商的技能:将其粘贴到 `AGENTS.md` 或代理人的指示.

在 Claude 代码中,您可以将其安装为插件 :

```
/plugin install spark-joy --marketplace Dansyuqri/spark-joy
```

## 使用

在与分公司核对的回购内,请您的经纪人"批量审查这个PR"(Claude Code, `/spark-joy` (见E/CN.4/Sub.2/2003/L.31)。 代理取出diff,读取后写出并验证了计划,并在http://127.0.0.1:4848上开始应用.

在应用中:

-   `j` 编号 : `k` 在块和块之间移动 `x` 切换已审查.
-   选中 **已查看** 在文件头上标记它审查并崩溃。 一旦全部文件被查看, 块就会完成 。 文件头在滚动时保持被绑,这样可以勾选或倒塌而无需回滚.
-   每个文件下, **用途** 财务报告和审定财务报表 **用于** 列出链接到的其他更改文件,每个块都坐入其中。 另一个文件中定义的名称在 diff 中下划线;单击一个以跳转到其定义,并使用浏览器的 Back 返回.
-   **横块** (单位:千美元)**整个公关** 文件头上显示文件的 diff 按顺序排列, 这样您就可以跟踪它从一个到另一个的变化 。 留下文件的块块显示 _此 PR 没有变化_。 。 。 .
-   单击行号在该行上留下注释.
-   使用 **↑ 20**, (中文(简体) ), **↓ 20** 或者说 **全部显示** 显示更多上下文,或者 **查看文件** 看整个文件.
-   **摘要-出口审查** 写一个带有进度的减记报告,注释(包括 `file:line`)和特征列表.

在GitHub或GitLab上,请您的经纪人"把我的笔记张贴到公关",或者运行 `spark-joy comments --post` 你自己来 您的笔记逐字递增, 作为等待审查( GitHub) 或草稿( GitLab) , 只有您在提交这些笔记之前才能看到 。 线路笔记在线路内;块笔记在审查机构内。 它检查公关 仍然在承诺 你先审查, 代理从来没有增加 自己的评论.

### 代理或终端

您的代理驱动每个步骤: 询问它并运行命令 。 唯一需要代理人的步骤是计划(读取diff并将其分组);其他的都是a `spark-joy` 命令.

每个命令都以 `next:` 线条表示接下来会发生什么:要运行的命令,或者询问您的代理。 如果您的代理在无法启动服务器的沙盒中运行, 请写信给 `.git` 或到达GitHub, 它给你的命令 在您的终端运行代替 `next:` 这里的行告诉你什么时候回去找探员。 迷路了吗? `spark-joy status` 说跑步站在哪.

![A sandboxed agent hands over spark-joy stack 13; the CLI says to ask the agent to break up a 522-line PR; the agent plans and hands over serve; the CLI posts the notes and status shows they are pending](https://npmcn.com/package/%40dansyuqri/spark-joy/assets/agent-cli.gif)

### 图标

| 命令 | 它会做什么 |
| --- | --- |
| `spark-joy extract [base] [--working]` | 抖动 `merge-base(base, HEAD)..HEAD` (或工作树) 在一个跑进 `.spark-joy/<branch>/` |
| `spark-joy extract --staged | --uncommitted` | 抖动 `HEAD` 以指数或工作树为对象,用于拆分 |
| `spark-joy stack <pr> | --prs a,b,c` | 将现有的堆叠式公关或 MR 装入运行中, 每个公关一个块( 代理可以将大块拆分) |
| `spark-joy related <pr> | --prs a,b,c` | 将公关和每条公关连接(“与”链接有关,双向)装入一次运行,每一次运行都以自己的基础为基准 |
| `spark-joy link <pr> <prs…>` | 在第一个 PR 描述中添加一条“ 关系” 线, 命名其他 PR |
| `spark-joy status` | 跑步时 `next:` 步骤 |
| `spark-joy outline` | 每个文件和有大小和旗帜的hunk的压缩列表 |
| `spark-joy show <ids…> | --file <path>` | 全部打印; 接受范围 `h003..h010` |
| `spark-joy links` | 交叉文件链接:哪个hunk使用另一个定义的名称 |
| `spark-joy rubric` | 从 `.spark-joy.md` |
| `spark-joy validate [--json]` | 检查 `plan.json` 对付猎人 |
| `spark-joy serve [--port n]` | 启动审查程序 |
| `spark-joy export [--stdout]` | 写入 `review.md` |
| `spark-joy comments [--gitlab] [--stdout]` | 写入 `comments.json`: 您的笔记作为待决的 GitHub 审查或 GitLab 草稿笔记; 每堆文件一个 PR |
| `spark-joy comments --post [--pr n]` | 寄过去 `gh` 或者说 `glab`,直到您提交 |
| `spark-joy split [--check cmd] [--apply]` | 将拆分计划变成堆叠的本地分行 |
| `spark-joy install-skill [--agent a] [--project] [--print]` | 安装代理技能 |

`base` 默认为 `origin/HEAD`,则 `origin/main`, (中文(简体) ), `origin/master` 或者说 `main`中存储运行 `.spark-joy/`却忽略了自己.

计划格式载于 [SKILLL.MD (英语)](https://npmcn.com/package/%40dansyuqri/spark-joy/plugin/skills/spark-joy/SKILL.md),而计划是在 [共享/schema.ts](https://npmcn.com/package/%40dansyuqri/spark-joy/shared/schema.ts)。 。 。 .

## 自己拆分更改

自己写大公关? 叫你的经纪人"把我的修改分给较小的公关" 它将你的舞台改变,无承诺的改变或整个分支变成小的公关, 每一个都建立在之前的.

![Extracting uncommitted changes, previewing five stacked PRs in the app, checking each PR's tests, then creating the branches](https://npmcn.com/package/%40dansyuqri/spark-joy/assets/split.gif)

1.  **摘录** 你想分多少吗 `--staged`, (中文(简体) ), `--uncommitted`,或整个分支的基分.
2.  **计划.** 代理将每次更改都分组成订购的公关:每一次都必须以之前的更改为基础,而锁文件则随需要的更改而去. 预览应用程序中的堆栈; 映射显示 PR 如何依赖对方 .
3.  **检查.** `split` 建立公关 并证实最后一个 完全匹配您的修改. `--check` 在一个临时工作树上检查每个公关.
4.  **应用.** `split --apply` 创建本地分支并将每个 PR 的标题和描述写入 `prs.md`。 。 。 。 承诺是签名的,如果您的 Git 配置有 `commit.gpgsign` 继续.

```sh
spark-joy extract --uncommitted                 # or --staged, or a base for the whole branch
spark-joy split                                 # dry run
spark-joy split --check "npm ci && npm test"    # optional
spark-joy split --apply                         # creates <branch>-split/1-…, 2-…
```

您的工作树, 舞台文件和当前分支从未被触动过: 公关由临时的 git 索引构建 。 若有事不相加,则无所分会.

## 审查堆放的公关

GitHub上有一堆公关, 或GitLab上的MR, 每一个都基于下面的分支? 装入并像拆分一样审查它们:每个公关一个块,用 **整个公关** 显示文件从 PR 到 PR 的变化 .

```sh
spark-joy stack 12                  # or a PR/MR URL; any PR in the stack works
spark-joy stack --prs 12,13,14      # exactly these, bottom first
spark-joy serve --run pr-12-stack
```

-   它通过跟随基干向下并按每个头向上打开公关来找到其余的堆栈. 如果两个公关建立在同一个公关上,它跟随较低的数字,并说是这样;使用 `--prs` 选择.
-   获取每个 PR (`refs/pull/N/head` 或者说 `refs/merge-requests/N/head`时,保持 `refs/spark-joy/`)并针对下面的公关进行分解,所以你只看到公关会有什么变化,即使它会从更早的公关中重写行.
-   这个计划是从每个公关的标题和描述中为你写的,与公关有联系. 您的代理可以添加风险和审查焦点;当您在新推后再次导入堆栈时,它们会被保存.
-   大公关也可以拆散:代理添加 _基金会优先_ 财务报告和审定财务报表 _按特点_ 命令,将每个公关分割成块, 公关由公关划分, 在公关下列出它们来自。 在计划页上选一个 或者留下来 _整个公关_;进展在它们之间延续. **整个公关** 仍按顺序显示每个公关一个面板.
-   它和伪造者说话 `gh` 或者说 `glab`,所以它使用他们的登录,并且没有存储任何符号. 伪造来自遥控器的宿主 传球 `--forge github|gitlab` 给一个自己主持的人,他的名字不说,和 `--remote` 如果公关没开 `origin`。 。 。 .
-   `comments --post` (或要求你的经纪人张贴你的笔记) 每一个都发给公关, 它被留在了公关上, 作为公关头上的等待审查(或草稿), 它没有张贴任何公关 已经移动,因为你加载它。 一个块的注释会写到它的公关上;一个块跨出公关会写到最高的一并取出其他的名字. 如果公关没有针对下方的公关(`--prs` 它的行记放在审查机构而不是内在.

## 审查相关的公关

有些修改跨越不是堆栈的 PR : API 和使用它的客户端, 每个都打开 `main`,或者一个固定及其后续, 在一个repo或跨越几个。 将它们连在一起,放在一个地方审查,每个公关一个块,与 **整个公关** 在每个 PR 中显示一个触及它的文件 .

```sh
spark-joy related 12                # or a PR/MR URL
spark-joy related --prs 12,15,20    # exactly these, no links needed
spark-joy link 12 15 20             # adds "Relates to #15, #20" to #12's description
spark-joy link 12 acme/web#7        # a PR in another repo
spark-joy serve --run pr-12-related
```

-   接下来 `Relates to #15` 线条( 也) `Related:`, (中文(简体) ), `Related PRs:`,公关URL,以及 `!15` 在GitLab上) 从PR到PR, 并找到开放的PR 链接回。 一个链接任何地方 连接两个公关.
-   **穿过雷波.** 链接可以在相同的 GitHub 或 GitLab 上的其他 repos 中命名 PR : `acme/web#7`, (中文(简体) ), `group/api!3`,或者一个 PR URL. `related` 也加载这些,并搜索它所到达的每个回转,用于连接回回转的PR,所以一个跨越多回转系统审查的更改是一个整体. 他们将被引入你的克隆人之中 `acme/web#7`在整个公关中,通过repo(`acme/web:package.json`并用它自己的回购笔记给公关。 跑步从其中任何一个开始: `spark-joy related acme/web#7`。 。 。 .
-   每一个公关都针对它的目标进行分解: 其基础分支,或者,当它基于另一个公关运行时,该公关. 评论页上写着哪个("目标主","建于#12").
-   你的经纪人把所有的公关都读了起来 加上 _基金会首先跨越公关_ 财务报告和审定财务报表 _按公关的特征_ 命令:一个块可以收集基础,或一个特征,从它所接触的每一个公关中收集. 每个文件一次显示每个 PR, 标记 `#12`, (中文(简体) ), `#15`,每张纸条都保留它留下的公关. _整个公关_ 保持一个块每公关.
-   `comments --post` 给公关发送每个音符 它留在了公关, 内含公关自己的行。 一个横跨公关的字条 写在最高的字条上 并点出其他名字.

![Linking an acme/api PR to an acme/web PR, loading both repos' PRs into one review, grouping them across PRs, and seeing each repo's package.json apart](https://npmcn.com/package/%40dansyuqri/spark-joy/assets/related-across-repos.gif)

## 开发

```sh
npm install
npm run build        # CLI (tsup) and app (Vite)
npm test             # unit and integration tests
npm run test:e2e     # browser walkthrough of the app (Playwright + Chromium)
npm run typecheck
npm run dev:app      # Vite dev server; proxies /api to a running `spark-joy serve`
```

布局 :

-   `cli/`:命令,diff解析,分解,分类,服务器,堆放的分支构建器.
-   `shared/`: schemas,验证和衍生状态,用于CLI和应用程序.
-   `src/`: react审查应用.
-   `plugin/`:技能,被包装为克洛德代码插件.
-   `test/`:维特克特,有固定克特回波.

## 常见问题

### @dansyuqri/spark-joy 是什么？

将一个庞大的公关分解成可审查块\.

### 如何安装 @dansyuqri/spark-joy？

在项目目录运行 npm install @dansyuqri/spark-joy，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 spark-joy，可以用 npx spark-joy 直接运行。

### @dansyuqri/spark-joy 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/dansyuqri\_\_spark-joy 是否存在。

### @dansyuqri/spark-joy 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dansyuqri/spark-joy 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dansyuqri/spark-joy 可以商用吗？

@dansyuqri/spark-joy 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dansyuqri/spark-joy 的下载量有多少？

根据 npm 官方下载统计，@dansyuqri/spark-joy 在 2026/10/12 – 2026/11/10 这 30 天内被下载 3,717 次，日均约 124 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dansyuqri/spark-joy 还在维护吗？

最新版本 0\.11\.0 发布于 2026/10/26（16 天前）；至今共发布 23 个版本，其中过去 12 个月发布了 23 个；首次发布于 2026/10/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。