让开源，少一点语言距离。
npm包中文文档

@dansyuqri/spark-joy

中文文档
0.11.0发布于 2026/10/26MITES Module构建来源已验证近 30 天下载 3717

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

中文使用文档
中文原文
文档目录14 节
  1. 主要特点
  2. 将大型 PR 拆分为较小的 PR
  3. 按基金会或特征审查大型公关
  4. 审查将公关联系在一起
  5. 其他特点
  6. 如何运作
  7. 安装
  8. 使用
  9. 代理或终端
  10. 图标
  11. 自己拆分更改
  12. 审查堆放的公关
  13. 审查相关的公关
  14. 开发

A drawer of neatly folded diffs, one sparking joy

火花欢乐

让公关再次燃起欢乐.

npm version MIT license

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

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

灵感来自 主持人。 。 。 .

主要特点

将大型 PR 拆分为较小的 PR

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

Extracting uncommitted changes, previewing five stacked PRs in the app, checking each PR's tests, then creating the branches

更多进去 自己拆分更改。 。 。 .

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

叫你的经纪人检查一下这个公关 它将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

更多进去 使用。 。 。 .

审查将公关联系在一起

一些修改跨越了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

更多进去 审查相关的公关。 。 。 .

其他特点

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

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

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

图标

命令它会做什么
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 (英语),而计划是在 共享/schema.ts。 。 。 .

自己拆分更改

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

Extracting uncommitted changes, previewing five stacked PRs in the app, checking each PR's tests, then creating the branches

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

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 中显示一个触及它的文件 .

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

开发

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 共发布 23 个版本，首次发布于 2026/10/17；过去 12 个月发布了 23 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本发布日期距今
0.11.0latest2026/10/2616 天前
0.10.12026/10/2318 天前
0.10.02026/10/2318 天前
0.9.02026/10/2318 天前
0.8.02026/10/2319 天前
0.7.02026/10/2220 天前

关于 @dansyuqri/spark-joy 的常见问题

@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 和提交记录判断。